Неделя 5. Runtime и оркестрация workflow

🧭 Где мы: LLM → Context / State → Tools → [Runtime / Orchestration] → Policy / Permissions → Evaluation / Observability.

Вспомни прошлую неделю

1. Что делает ModelClient между workflow и provider SDK?
2. Где в Capstone tool proposal проходит validation до исполнения?

Материал

В Week 4 мы научились вызывать модель через ModelClient. Теперь строим runtime вокруг этой capability: сохраняем состояние между ролями, задаём переходы кодом, ограничиваем бюджет и останавливаем опасные side effects до исполнения. Реализуем это на обычном Python; новый framework не нужен.

Основной проход недели: State → Workflow → RunPolicy → HumanGate. ModelClient остаётся известной зависимостью, которую runtime вызывает внутри шага.

Обязательное ядро: State, Workflow, RunPolicy, HumanGate и runtime, который связывает их. Поля State, условия переходов и лимиты должны быть проверяемы тестами; модель остаётся за интерфейсом из Week 4.

Компоненты

Не обязательно строить инфраструктуру целиком. Каждый компонент вводится только против конкретной проблемы:

Один проход через эти компоненты

Теперь те же пять абстракций на одном реальном шаге — узле planner:

Workflow: решить, что делать дальше; условие перехода — заполнены acceptance_criteria
  ↓ передаёт не текст, а поле state
State: {issue, acceptance_criteria[2], allowed_paths[], status: planning}
  ↓ собирает сообщение из state, инструкции роли и правил формата
RoleRunner → ModelClient: один вызов; на выходе — JSON по схеме или явная ошибка
  ↓ схема невалидна / пустой ответ / timeout во время вызова
RunPolicy: один ограниченный повтор; после исчерпания — failed, дальше не идём
  ↓ scope не подтверждён человеком
HumanGate: needs_approval, запись не выполняется

Один вызов — одно решение: где хранится факт, кто зовёт модель, что проверяется до вызова и что происходит после. Когда все пять компонентов на месте, этот проход одинаков для любой роли: planner, analyst, reviewer отличаются только содержимым state и инструкцией.

Бюджет (обязательное ядро) и model routing (расширение)

Лимит вызовов — не оптимизация, а граница отказа: без конечного числа повторов цикл «попробовать ещё раз» превращается в зависший процесс, который выглядит как работа.

Зафиксируйте один провайдер и модель, установите конечные лимиты вызовов, времени и повторов. Не допускайте тихого переключения на другой или платный endpoint.

Расширение: добавьте routing — детерминированное правило, какая модель или обычный код обрабатывает какой тип шага:

Платный API для local-first пути не требуется. Облачный fallback необязателен и потенциально платен: он должен быть явно включён, иметь лимит и не получать приватный контекст без отдельного разрешения. Условия локального прогона — модель и тег, квантование, num_ctx, wall-clock, число вызовов, память — фиксируются по странице о выборе модели.

Расширение: сравните две модели или провайдера на одном наборе задач; routing должен иметь явные лимиты и завершать execution error как failed, возвращать needs_input для неоднозначности и blocked только при отказе policy до вызова.

Состояние задачи

State из недели 3 теперь становится конкретной структурой. Минимальный набор полей, который реально используется в capstone:

run_id
issue
acceptance_criteria[]
allowed_paths[]
plan
human_plan_approved
repo_evidence[]
test_plan[]
proposed_patch
commands_requested[]
commands_approved[]
test_results[]
review_findings[]
iteration_count
status: planning|needs_approval|implementing|testing|blocked|failed|done

blocked — policy не допустила действие до исполнения; failed — model/tool/runtime execution уже начался, но завершился ошибкой или исчерпал retry budget.

Секреты, .env, токены и содержимое credentials не должны попадать в промпты, артефакты логов или commit. Используйте .gitignore, redaction и отдельный учебный репозиторий.

Практика

Соберите первую цепочку без автоматического shell:

issue → planner → schema validation → человек утверждает план
     → read-only analyst → один отчёт

На выходе программа печатает артефакт и предлагает следующий шаг; она не меняет код. Добавьте тесты на invalid schema, provider timeout и needs_input.

Проверь себя

1. Какую проблему решает runtime поверх ModelClient?
2. Чем RunPolicy отличается от HumanGate?
3. Где в Capstone сохраняется состояние и где останавливается side effect?

✅ Definition of Done

• Объяснить, зачем runtime нужен поверх ModelClient, и различать обязанности RunPolicy и HumanGate.
• Реализовать переходы workflow по полям State, а не по свободному тексту модели.
• Тестом проверить invalid schema, timeout, конечный retry budget и needs_input.
• Показать, что исчерпание retry завершает выполнение как failed, а policy rejection до tool execution даёт blocked; незакрытый HumanGate не допускает side effect.

→ Дальше: runtime управляет переходами и остановками; в Week 6 сузим, какие инструменты и действия ему вообще разрешено выполнять.

Навигация