--- work_item: ORCH-099 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-10 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-099 — FND/F1a: лёгкий `/metrics` в орке (отдать сырьё) Work Item: **ORCH-099** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода. > Архитектурное обоснование/решения (формат полей liveness, способ чтения CPU, версионирование > контракта) — задача архитектора (`06-adr/`). ## 1. Сводка изменения Добавить read-only HTTP-эндпоинт `GET /metrics`, отдающий JSON-снимок «сырья» о самом орке для будущего sidecar (F1b): активные стадии задач, очередь jobs, agent-liveness, стоимость/токены. Логика сборки выносится в **новый leaf-модуль** `src/metrics.py` (чистая функция-сборщик, never-raise, без побочных эффектов — по образцу `serial_gate.snapshot()`/`task_deps.snapshot()`/`cancel.snapshot()`). Эндпоинт в `src/main.py` — тонкая обёртка над сборщиком, в том же стиле, что `GET /queue` (`src/main.py`, дикт с разделами). Никаких изменений `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схемы БД/machine-verdict ключей. Только чтение существующих таблиц и существующих in-memory-снапшотов. ## 2. Задействованные модули / пути | Путь | Действие | |------|----------| | `src/metrics.py` | **создать** — leaf-сборщик снимка из БД (`build_metrics() -> dict`, never-raise) | | `src/main.py` | изменить — добавить `@app.get("/metrics")` (тонкая обёртка над `metrics.build_metrics()`) | | `src/db.py` | изменить (при необходимости) — добавить read-only helper(ы) для агрегатов `agent_runs` (напр. `agent_cost_totals()`); существующие `job_status_counts`/`get_running_jobs`/`recent_jobs`/`get_active_tasks_for_reconcile` переиспользуются как есть | | `docs/architecture/README.md` | изменить — задокументировать контракт `/metrics` (формат для sidecar F1b) | | `CHANGELOG.md` | изменить — запись `## [Unreleased]` (ORCH-099) | | `tests/test_metrics.py` | **создать** — pytest на структуру/never-raise/read-only | **Существующие источники данных (переиспользуются, НЕ дублируются):** - `db.get_active_tasks_for_reconcile()` — задачи с `stage != 'done'` + вычисленный `age_s` (секунды с `updated_at`). Базис для раздела стадий. - `db.job_status_counts()` — `{queued, running, done, failed}` из `jobs`. - `db.get_running_jobs()` — running-jobs с `running_age_s`, плюс джойн на `agent_runs` (`agent`, `run_id`, `pid`, `started_at`, `model`, `effort`). Базис для liveness. - `queue_worker.worker.status()` / `worker.breaker.snapshot()` — breaker-состояние in-memory (`state`/`consecutive_transient`/`pause_remaining_s`), `max_concurrency`, `poll_interval`. ## 3. Функциональные требования ### FR-1 — Раздел `stages` (активные стадии задач) — BR-2 Список активных (незавершённых) задач. По каждой: - `work_item` — `tasks.work_item_id`. - `stage` — `tasks.stage` (значение слоя A, машина стадий). - `age_in_stage_s` — целое; секунды с `tasks.updated_at` (= момент последней смены стадии). Источник вычисления — SQL `CAST(strftime('%s','now') - strftime('%s', updated_at) AS INTEGER)`, как в `get_active_tasks_for_reconcile`. - `repo` — `tasks.repo` (sidecar мультипроектный; нужно отличать orchestrator от enduro-trails). - (опционально) `task_id`, `created_age_s` (общий возраст задачи). Инвариант: выборка только `stage NOT IN ('done', 'cancelled')` (терминальные исключены — см. ORCH-090: множество терминалов `{done, cancelled}`). Пустой список — валидный ответ. ### FR-2 — Раздел `queue` (очередь jobs) — BR-3 - `counts` — `db.job_status_counts()` (`queued`/`running`/`done`/`failed`); при наличии — добавить `cancelled` (ORCH-090 терминал). - `depth` — глубина очереди = число `queued`-jobs, готовых к выдаче (можно вернуть как `counts.queued`; при желании — отдельно «доступные сейчас» с учётом `available_at <= now`). - `retries` — сырьё по ретраям: сумма/список `attempts` vs `max_attempts` и `transient_attempts` по незавершённым jobs; как минимум агрегат «сколько jobs в backoff» (`available_at > now`). - `breaker` — `worker.breaker.snapshot()`: `state` (`closed`/`open`/`half-open`), `consecutive_transient`, `pause_remaining_s`. - `max_concurrency` — `worker.max_concurrency`. Инвариант: ни одно поле не обязано существовать ценой падения — недоступный breaker (например, worker не инициализирован в тесте) → `breaker: null`, не 500 (NFR-2). ### FR-3 — Раздел `agents` (agent-liveness) — BR-4 Список running-jobs (из `db.get_running_jobs()`), по каждому: - `agent` — `agent_runs.agent` (через джойн; роль: analyst/architect/developer/…). - `run_id` — `jobs.run_id` (= `agent_runs.id`). - `job_id` — `jobs.id`. - `pid` — `jobs.pid` (может быть `null`, если процесс ещё не застамплен / уже завершён). - `runtime_s` — `running_age_s` из `get_running_jobs` (секунды с `jobs.started_at`); как альтернатива — секунды с `agent_runs.started_at`. Решение о базисе — за архитектором (ADR). - **Сырьё для alive-детекта** — одно из (выбор реализации — ADR архитектора, BR-4 допускает оба): - вариант A: `cpu_ticks` — суммарные utime+stime из `/proc//stat` (поля 14–15), плюс `clk_tck` (`os.sysconf("SC_CLK_TCK")`), чтобы sidecar посчитал CPU-дельту между опросами; - вариант B: орк сам не считает дельту (он опрашивается стейтлесс sidecar'ом) — отдаёт только сырые тики + временную метку выборки. - `model`, `effort` — `agent_runs.model`/`effort` (контекст стоимости). Инвариант (NFR-2): `pid is None` ИЛИ `/proc/` отсутствует/гонка (процесс умер) → `cpu_ticks: null` для этого агента, остальные поля и весь эндпоинт целы. НЕ бросать, НЕ ждать. ### FR-4 — Раздел `cost` (стоимость/токены) — BR-5 - `running` — по каждому running-job текущие накопленные значения из `agent_runs`, если уже застамплены (часто `null` до завершения — токены/cost парсятся из CLI-JSON в `_monitor_agent` по окончании). Допустимо отдавать `null` для незавершённых — это честное сырьё. - `aggregate` — агрегаты по `agent_runs`: суммарные `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`. Желателен срез: всего + за последние N (или по `repo`). Реализуется новым read-only helper'ом `db.agent_cost_totals()` (чистый SELECT с `COALESCE(SUM(...),0)`). Инвариант: пустая `agent_runs` → нули, не ошибка. ### FR-5 — Конверт ответа (envelope) — BR-1, BR-6, NFR-6 `GET /metrics` возвращает JSON: ```json { "schema_version": 1, "generated_at": "", "stages": [ ... ], "queue": { ... }, "agents": [ ... ], "cost": { "running": [...], "aggregate": {...} } } ``` - `schema_version` — целое; точка стабильности контракта для sidecar (NFR-6). Стартовое значение и политика инкремента — за архитектором. - `generated_at` — метка времени снимка (нужна sidecar'у для расчёта дельт). - Точные имена ключей разделов/полей фиксируются в `docs/architecture/README.md` (BR-7) и являются контрактом; reviewer/tester сверяют ответ с документом. ### FR-6 — Never-raise сборщик — NFR-2 `metrics.build_metrics()` строит ответ по-раздельно; каждый раздел — в своём `try/except`, в `except` пишет `logger.warning(...)` и подставляет безопасный дефолт (`null`/`[]`/`{}`). Функция **никогда** не пробрасывает исключение. Эндпоинт `main` дополнительно не нуждается в обработке, но обязан вернуть результат сборщика как есть. Эталон — `serial_gate.snapshot()`. ## 4. Изменения API **Новый эндпоинт:** - `GET /metrics` → `200 application/json`, тело — конверт FR-5. Без параметров. Без аутентификации сверх существующей (тот же уровень, что `/queue`/`/status`). Read-only. **Изменённые эндпоинты:** Нет. `/health`, `/status`, `/queue`, `/webhook/*` — без изменений (BR-6). Регресс-проверка: существующие тесты эндпоинтов остаются зелёными. ## 5. Изменения схемы БД **Нет.** Новые таблицы/колонки/индексы/миграции не вводятся. Используются существующие `tasks`/`jobs`/`agent_runs` и их колонки (перечислены в §2). Допускается добавление **read-only** helper-функций в `src/db.py` (например `agent_cost_totals()`) — это код, не схема; `CREATE`/`ALTER` не выполняются. `STAGE_TRANSITIONS`/`QG_CHECKS`/схема — байт-в-байт прежние (NFR-5). ## 6. Требования к новым/изменённым QG checks **Нет.** `/metrics` — наблюдаемость, не гейт конвейера. `QG_CHECKS` / `check_*` / `_parse_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/ `coverage_status:`) — НЕ трогаются. Новых артефактов pipeline (`NN-*.md`) задача не создаёт. ## 7. Совместимость / регресс - **Аддитивность:** новый модуль (`src/metrics.py`) + новый эндпоинт + read-only helper(ы). Существующий код путей конвейера не модифицируется. - **Read-only / never-raise:** по конструкции (NFR-1/NFR-2) эндпоинт не влияет на состояние и не падает → нулевой риск для прод-конвейера, общего с enduro-trails (NFR-4). - **Kill-switch:** жёсткий флаг не обязателен (эндпоинт инертен и не подключён к конвейеру). Если архитектор сочтёт нужным — допустим конфиг-флаг включения `/metrics` (по образцу snapshot-флагов), но это НЕ требование BRD; дефолт — эндпоинт доступен. - **Обратимость:** удаление эндпоинта/модуля полностью откатывает изменение без следов в БД/схеме. - **Контракт sidecar:** `schema_version` + документ в README обеспечивают, что F1b не сломается при будущих аддитивных расширениях (NFR-6). - **Артефакты pipeline, создаваемые/обновляемые задачей:** `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml` (analysis); далее — `06-adr/` (architect), обновление `docs/architecture/README.md` и `CHANGELOG.md` (developer в том же PR — правило «доки = golden source»).