auto-sync: 2026-06-05 19:10:01

tasks/orchestrator/DEV_TASK_ORCH41_AGENT_MODELS.md

@@ -9,6 +9,11 @@
 Слава хочет: **модель выбирается в настройках, под каждого агента, с возможностью задать per-project.**
 Это первый шаг к мультипровайдерности (ORCH-13). НЕ хардкодить версию — вынести в конфиг.
 
+**Расширено (решение Славы 05.06):** 4.7 и 4.8 стоят одинаково → дефолт = `claude-opus-4-8`.
+Дополнительно конфигурируем **режим работы модели `--effort`** (low/medium/high/xhigh/max) —
+это рычаг «качество vs стоимость/время», per-agent + per-project, тем же резолвингом.
+Опционально: `--fallback-model` (авто-фолбэк при overloaded, работает с --print).
+
 ## Репозиторий / ветка
 - Репо: `orchestrator`, база `main` (HEAD `8da571d`)
 - Ветка: `feat/ORCH-41-agent-models`, PR в main, НЕ мержить.
@@ -28,7 +33,8 @@
 ## Что сделать
 
 ### 1. Глобальные дефолты модели per-agent — в Settings (src/config.py)
-Добавить поля (env `ORCH_AGENT_MODEL_<AGENT>`), дефолт — единый базовый, напр. `claude-opus-4-8`:
+Добавить поля (env `ORCH_AGENT_MODEL_<AGENT>` и `ORCH_AGENT_EFFORT_<AGENT>`).
+Дефолт модели = `claude-opus-4-8` (цена 4.7==4.8, решение Славы).
 ```python
 # Per-agent LLM model (ORCH-41). Empty -> agent_model_default. Resolution order:
 # project-override > ORCH_AGENT_MODEL_<AGENT> > agent_model_default > CLI default.
@@ -39,38 +45,70 @@ agent_model_developer: str = ""
 agent_model_reviewer: str = ""
 agent_model_tester: str = ""
 agent_model_deployer: str = ""
+
+# Per-agent effort / reasoning level (ORCH-41): low|medium|high|xhigh|max.
+# Empty -> agent_effort_default. Same resolution order as model.
+# Раскладка по умолчанию: думающие агенты — high, механические — medium.
+agent_effort_default: str = "high"
+agent_effort_analyst: str = "high"
+agent_effort_architect: str = "high"
+agent_effort_developer: str = "high"
+agent_effort_reviewer: str = "high"
+agent_effort_tester: str = "medium"
+agent_effort_deployer: str = "medium"
+
+# Optional per-agent fallback model when primary is overloaded (--fallback-model).
+agent_fallback_model: str = ""
 ```
 
 ### 2. Per-project override — в ProjectConfig (src/projects.py)
-Добавить опциональное поле `agent_models: dict[str, str]` (агент→модель), парсить из
-`projects_json` (ключ `agent_models` в JSON каждого проекта, опционально). Пример записи реестра:
+Добавить опциональные поля `agent_models: dict[str,str]` И `agent_efforts: dict[str,str]`
+(агент→модель / агент→effort), парсить из `projects_json`. Пример записи реестра:
 ```json
 {"plane_project_id":"...","repo":"orchestrator","work_item_prefix":"ORCH",
- "agent_models":{"developer":"claude-opus-4-8","reviewer":"claude-sonnet-4-6"}}
+ "agent_models":{"developer":"claude-opus-4-8","reviewer":"claude-sonnet-4-6"},
+ "agent_efforts":{"developer":"xhigh","tester":"low"}}
 ```
-Поле опционально → старые записи без `agent_models` работают (default = {}).
+Оба поля опциональны → старые записи работают (default = {}).
 ВНИМАНИЕ: dataclass `frozen=True` + mutable default → используй `field(default_factory=dict)`.
 
-### 3. Резолвинг модели — helper (где удобнее: launcher или projects)
-Функция `resolve_agent_model(agent: str, project_id: str) -> str` с приоритетом:
-1. `ProjectConfig.agent_models[agent]` (per-project override) — если есть
-2. `settings.agent_model_<agent>` (глобальный per-agent env) — если непусто
+### 3. Резолвинг — helper(ы) (где удобнее: launcher или projects)
+`resolve_agent_model(agent, project_id) -> str` с приоритетом:
+1. `ProjectConfig.agent_models[agent]` (per-project override)
+2. `settings.agent_model_<agent>` (глобальный per-agent env, если непусто)
 3. `settings.agent_model_default`
-4. (если всё пусто) — без флага, CLI-дефолт
-Вернуть строку модели (или "" → без `--model`).
+4. (пусто) → без `--model`, CLI-дефолт
+
+Аналогично `resolve_agent_effort(agent, project_id) -> str` (тот же приоритет, через
+`agent_efforts` / `agent_effort_<agent>` / `agent_effort_default`). Валидировать значение
+по множеству {low,medium,high,xhigh,max}; невалидное → лог-warning + опустить флаг.
+Желательно общий приватный резолвер, чтобы не дублировать логику приоритета.
 
 ### 4. Применить в launcher.py
 - Убрать хардкод `"model": "opus"` из AGENT_CONFIGS (architect, reviewer) — модель теперь резолвится.
-- При сборке команды: `model = resolve_agent_model(agent, project_id)` вместо `config.get("model","")`.
+- При сборке команды:
+  ```python
+  model = resolve_agent_model(agent, project_id)
+  effort = resolve_agent_effort(agent, project_id)
+  model_flag  = f"--model {model} " if model else ""
+  effort_flag = f"--effort {effort} " if effort else ""
+  fb = settings.agent_fallback_model
+  fb_flag = f"--fallback-model {fb} " if fb else ""
+  ```
+  и подставить `{model_flag}{effort_flag}{fb_flag}` в cmd.
 - `project_id` уже доступен в потоке запуска (передаётся в launch — проверь сигнатуру, протяни если надо).
 
 ### 5. Тесты (tests/)
 - `test_resolve_agent_model.py`: все 4 уровня приоритета (project > env > default > пусто),
   отсутствие проекта, неизвестный агент, frozen-dataclass с agent_models.
-- Проверить, что `--model` корректно подставляется/опускается в собранной команде.
+- `test_resolve_agent_effort.py`: те же уровни + валидация значения (невалидное → опускается).
+- Проверить, что `--model` / `--effort` / `--fallback-model` корректно подставляются/опускаются
+  в собранной команде (по флагу присутствия).
 
 ### 6. Документация
-- Обновить `docs/` (конфиг-референс орка): новые env `ORCH_AGENT_MODEL_*`, поле `agent_models` в projects_json.
+- Обновить `docs/` (конфиг-референс орка): новые env `ORCH_AGENT_MODEL_*`, `ORCH_AGENT_EFFORT_*`,
+  `ORCH_AGENT_FALLBACK_MODEL`, поля `agent_models`/`agent_efforts` в projects_json.
+- Кратко описать значения effort (low|medium|high|xhigh|max) и дефолтную раскладку по агентам.
 - CHANGELOG.md.
 
 ## Команды проверки (ОБЯЗАТЕЛЬНО до отчёта)