91 lines
7.8 KiB
Markdown
91 lines
7.8 KiB
Markdown
# 01 — Business Requirements Document (BRD)
|
||
|
||
**Work Item:** ORCH-044
|
||
**Title:** Надёжность запуска агента: preflight ловит auth+битый флаг, --effort фикс
|
||
**Приоритет:** Высокий (надёжность конвейера)
|
||
**Автор запроса:** Слава, 05.06 («почему перед стартом аналитика не прошла проверка?»)
|
||
|
||
## 1. Контекст и инцидент (05.06)
|
||
Задача **ORCH-17** застряла на стадии Analysis ~30 минут. Аналитик-агент стартовал и
|
||
мгновенно «умирал»: run-лог — **пустой файл (0 байт)**, а job в очереди оставался в
|
||
состоянии `running` (вечное зависание без сигнала).
|
||
|
||
Корневые причины (две, наложились):
|
||
1. **`claude` Not logged in** после ребилда контейнера — токен/сессия не поднялись.
|
||
2. **Флаг `--effort`** в связке с `--print --output-format json` (CLI 2.1.142) **гасил весь
|
||
stdout** — claude завершался с пустым выводом.
|
||
|
||
**Главная системная проблема:** preflight-проверка пропустила обе битые задачи в работу —
|
||
она слепа к авторизации и не ловит «битый флаг → пустой вывод».
|
||
|
||
## 2. Проблема (как есть)
|
||
- **P1. Дыра в preflight (главное).** `src/preflight.py` сознательно проверяет только
|
||
(a) `os.path.exists(CLAUDE_BIN)` и (b) `claude --version` (timeout 5s, без токенов).
|
||
Но `--version` отвечает успешно **даже когда claude НЕ залогинен** (версия — локальная
|
||
информация). Итог: `preflight=ok`, а реальный запуск падает `Not logged in`. Preflight
|
||
слеп к авторизации и пропускает заведомо нерабочие задачи в очередь.
|
||
- **P2. `--effort` ломает вывод.** Флаг `--effort <low..max>` совместно с
|
||
`--print`/`--output-format json` в CLI 2.1.142 даёт **пустой stdout** — агент молча
|
||
умирает. Сейчас effort **отключён в проде** хотфиксом (`.env`: `ORCH_AGENT_EFFORT_*=""`),
|
||
но дефолты в `src/config.py` всё ещё `high`/`medium`, а документация (INFRA.md,
|
||
internals.md, ORCH-41) описывает effort как рабочую фичу. Несоответствие кода/доков/прода.
|
||
- **P3. Пустой лог ≠ провал.** Агент с пустым run-логом (0 байт) и `exit 0` трактуется как
|
||
**успех** (`_finalize_job` → `done`, авто-advance стадии) либо вечно висит `running`.
|
||
Ни watchdog, ни ретрай не срабатывают. Нет сигнала об инциденте.
|
||
|
||
## 3. Бизнес-последствия
|
||
- Любой сбой авторизации или несовместимости флага → **тихое зависание** задачи без алерта.
|
||
- Блокируется конвейер **всех** проектов (общий инстанс/очередь, self-hosting) — как было с
|
||
ORCH-17 (30 мин простоя, ручное вмешательство).
|
||
- Деградация доверия к автономности оркестратора: «проверка перед стартом» не работает.
|
||
|
||
## 4. Цель
|
||
Сделать запуск агента **отказоустойчивым по входу и по выходу**:
|
||
1. Preflight ловит отсутствие/протухание авторизации **дёшево и без траты токенов** до того,
|
||
как job будет заклеймлен.
|
||
2. Разобраться с `--effort` и привести код/доки/прод к одному непротиворечивому состоянию.
|
||
3. Пустой/невалидный результат запуска трактуется как **провал** (job → `failed`), чтобы
|
||
сработали watchdog/ретрай и алерт, а не вечное зависание.
|
||
|
||
## 5. Заинтересованные стороны
|
||
- **Owner/Слава** — инициатор, требует «проверки перед стартом».
|
||
- **Все проекты на инстансе** (enduro-trails и self-hosting ORCH) — страдают от простоя.
|
||
- **Агенты конвейера** — analyst/architect/... — все запускаются через единый launcher.
|
||
|
||
## 6. Объём (Scope)
|
||
**В объёме:**
|
||
- Дешёвая token-free проверка авторизации в preflight.
|
||
- Расследование и решение по `--effort` (вернуть корректно ИЛИ задокументировать как
|
||
unsupported и убрать из кода/дефолтов/доков).
|
||
- Детекция «пустой лог / нет валидного result-JSON» как провала job с корректным
|
||
переводом в `failed` и срабатыванием ретрая/алерта.
|
||
- Обновление документации (INFRA.md / internals.md / CHANGELOG) в том же PR.
|
||
|
||
**Вне объёма:**
|
||
- Prompt-ping (ping→pong) — **запрещено** (жжёт rate limit). Только локальные/дешёвые проверки.
|
||
- Реформа circuit breaker / backoff-логики (используем существующие механизмы).
|
||
- Изменение схемы стадий/конвейера.
|
||
- Автоматический re-login claude (восстановление авторизации) — отдельная задача.
|
||
|
||
## 7. Бизнес-правила
|
||
- BR-1: Preflight **не тратит токены** и не делает сетевых вызовов к API модели.
|
||
- BR-2: Протухшая/нечитаемая авторизация → `preflight=fail` → job **не клеймится** (остаётся
|
||
`queued`), пишется warning, при необходимости — алерт/брейкер.
|
||
- BR-3: Пустой run-лог ИЛИ отсутствие валидного result-JSON при `exit 0` → job `failed`
|
||
(никогда не `done` и не вечный `running`).
|
||
- BR-4: Никаких `--no-verify`/обхода хуков без явного одобрения Owner.
|
||
- BR-5: Код, дефолты `config.py`, прод `.env` и документация по `--effort` должны быть
|
||
взаимно непротиворечивы после задачи.
|
||
|
||
## 8. Критерии успеха (бизнес-уровень)
|
||
- Симуляция «не залогинен» → preflight ловит до клейма, job не стартует впустую.
|
||
- Симуляция «пустой лог + exit 0» → job становится `failed`, срабатывает ретрай/алерт.
|
||
- Состояние `--effort` однозначно: либо работает с json-форматом, либо удалён из активного
|
||
пути и доков (без «мёртвого» флага в дефолтах).
|
||
- Инцидент класса ORCH-17 больше не приводит к тихому 30-минутному зависанию.
|
||
|
||
## 9. Связанные материалы
|
||
- `src/preflight.py`, `src/queue_worker.py`, `src/agents/launcher.py`, `src/config.py`
|
||
- `docs/history/LESSONS_ORCH-017.md`, `docs/history/LESSONS_2026-06-05.md`
|
||
- ORCH-41 (effort/model resolver), ORCH-1 (очередь/resilience), ORCH-7 (watchdog)
|