13. Долгие цели, Plan mode и side-разговоры

/goal, /plan и /side решают разные задачи:

• /goal хранит долгую цель в состоянии конкретного треда и позволяет агенту автоматически продолжать работу между ходами.
• /plan переключает текущую сессию в режим планирования без изменений repo-tracked файлов.
• /side открывает временное ответвление для отдельного вопроса, пока основной тред может продолжать работу.

Это не три равнозначных режима. Цель может оставаться привязанной к треду, пока пользователь переключает его между Plan и Default mode. Side-разговор является отдельным ephemeral-тредом и цель родительского треда не наследует.

1. /goal — долгоиграющая цель

Цель — это устойчивое описание результата, которое:

• Хранится вместе с конкретным тредом и доступно после перезапуска при resume этого треда.
• Может иметь локальный лимит токенов — token budget.
• Автоматически продолжает работу после завершения хода, когда тред свободен и нет ожидающих сообщений или другой работы.
• Не переносится в новый тред, созданный через /new или /clear.

Синтаксис

/goal Implement user-facing OAuth flow with Google as IdP
/goal --budget 200k Implement OAuth flow

--budget (или --tokens) принимает положительное число. Поддерживаются суффиксы k и m: 100k = 100 000 токенов, 1m = 1 000 000.

Команда /goal без аргументов показывает текущую цель и её состояние.

Subcommands

/goal edit             # отредактировать описание цели
/goal pause            # остановить автоматическое продолжение
/goal resume           # снова сделать цель активной
/goal clear            # удалить цель
/goal budget 300k      # изменить лимит
/goal budget clear     # снять лимит

Если цель получила статус budget_limited, сначала увеличьте или снимите бюджет, затем выполните /goal resume. Один только /goal resume не обходит уже исчерпанный лимит.

Статусы цели

Модель может выставить blocked или complete через update_goal. Команды пользователя управляют созданием, редактированием, паузой, возобновлением, бюджетом и удалением цели. usage_limited и budget_limited выставляются runtime автоматически.

Автоматическое продолжение

После завершения хода AstraCode может автоматически начать следующий ход по активной цели. Продолжение запускается только на безопасной границе, когда:

• статус цели — active;
• в треде нет выполняющегося хода;
• нет queued user input и другой ожидающей работы;
• предыдущее автоматическое продолжение не завершилось без единого tool call.

Поэтому для активной цели не требуется после каждого шага писать continue или go. /goal pause останавливает цикл. Прерывание выполняющегося хода также переводит активную цель в paused, чтобы работа не возобновилась неожиданно.

Plan mode временно исключает цель из runtime-обработки: пока тред находится в Plan, расход цели не учитывается и автоматические продолжения не запускаются. Сама запись цели при этом остаётся в state DB.

Как работает token budget

Budget — это локальный счётчик model tokens, потраченных во время работы над активной целью. Cached input в этот счётчик не входит.

Лимит проверяется во время учёта прогресса, а не прерывает генерацию ровно на заданном токене. Поэтому фактический расход может немного превысить budget. После достижения лимита runtime:

1. Выставляет статус budget_limited.
2. Просит модель не начинать новую существенную работу.
3. Даёт завершить текущий ход кратким итогом, оставшейся работой и следующим полезным шагом.
4. Не запускает следующее автоматическое продолжение.

Остановка по budget не означает, что цель выполнена.

Popup автодополнения

Когда вы вводите /goal, открывается popup с подсказками:

• Для пустого ввода или произвольного текста echo-row предлагает использовать текст как описание цели.
• Для edit, resume, pause, clear и budget показываются подкоманды.

Реализация находится в tui/src/bottom_pane/goal_args_popup.rs (GoalRow::Subcommand / GoalRow::Echo).

Скрытый runtime-контекст

Runtime передаёт модели цель через скрытый contextual user fragment с ролью user, обёрнутый в теги <goal_context>. Это не system- и не developer-prompt. Тип фрагмента определён в core/src/context/goal_context.rs.

Текст строится шаблонами из core/templates/goals/:

• continuation.md — продолжение активной цели: objective, время, расход и остаток бюджета;
• budget_limit.md — достижение бюджета и требование завершить текущий ход;
• objective_updated.md — новая или отредактированная objective и бюджет.

Примерная суть continuation-контекста:

Continue working toward the active thread goal.
Objective: Implement user-facing OAuth flow with Google as IdP
Tokens used: 145000
Token budget: 200000
Tokens remaining: 55000

Evidence и завершение

Механизма goal_artifacts — отдельной папки с evidence-файлами — в коде нет. Шаблон continuation.md требует от модели перед complete провести evidence-аудит: сопоставить требования цели с файлами, тестами, выводом команд или другими проверяемыми результатами.

Это инструкция модели, а не отдельный runtime-валидатор: runtime самостоятельно не проверяет тесты или файлы перед обработкой update_goal(status = "complete"). Скилл goal-usage (см. 05-skills.md) помогает формулировать измеримые цели и критерии завершения, но не пишет артефакты на диск.

Хранение

~/.astracode/state_5.sqlite
  → table: thread_goals (thread_id, goal_id, objective, status, token_budget,
                          tokens_used, time_used_seconds, created_at_ms, updated_at_ms)
  → status: active | paused | blocked | usage_limited | budget_limited | complete
  → логика: core/src/goals.rs
  → DB-модель: state/src/runtime/goals.rs, state/src/model/thread_goal.rs

2. /plan — режим планирования

/plan Refactor the auth module to use the new session API

В Plan mode агент:

1. Исследует код и устраняет вопросы, которые можно разрешить чтением репозитория.
2. Уточняет у пользователя существенные продуктовые решения и компромиссы.
3. Готовит decision-complete план с изменениями, тестами и допущениями.
4. Не изменяет repo-tracked файлы и не выполняет действия, реализующие план.

Запрет изменений обеспечивается не только инструкцией модели: для хода используется read-only permission profile, а mutating tools исключаются. При этом разрешены чтение файлов, поиск, статический анализ и проверки, которые не изменяют repo-tracked состояние.

Когда модель выдаёт финальный <proposed_plan>, TUI предлагает:

• Переключиться в Default mode и реализовать план в текущем треде.
• Создать свежий тред с утверждённым планом и реализовать его там.
• Остаться в Plan mode и продолжить обсуждение.

Императивный текст вроде implement it сам по себе не снимает Plan mode. Для реализации нужно выбрать соответствующий пункт TUI или явно переключиться в Default mode.

Параметр reasoning effort

plan_mode_reasoning_effort = "high"

Этот параметр задаёт отдельный reasoning effort для Plan mode. Если override не задан, используется reasoning effort выбранной модели/текущих настроек.

Вход и выход

• /plan или /plan <instructions> включает Plan mode.
• Shift+Tab циклически переключает доступные collaboration modes.
• После готового <proposed_plan> пункт «Да, реализовать план» переключает сессию в Default mode и отправляет запрос на реализацию.
• Subcommand /plan clear не существует.

3. /side — побочный разговор

/side Quick question: how does the rollout recorder serialize tool calls?

/side создаёт временный ephemeral-форк текущего треда:

• У side собственный контекст, а история родителя доступна только как справочный материал.
• Сообщения side не добавляются в историю родительского треда.
• Основной тред не прерывается и может продолжать работу параллельно.
• Esc закрывает side и возвращает в родительский тред; отдельной команды /quit-side нет.
• Side не создаёт сохраняемый rollout и недоступен для последующего resume.

Перед первым /side текущий разговор должен уже начаться: необходимо отправить хотя бы одно сообщение, чтобы у родительского треда существовала история для fork.

Полезные сценарии:

• Уточнить понимание кода, пока основной агент выполняет долгую задачу.
• Спросить про API или функцию, не добавляя вопрос в основной контекст.
• Выполнить лёгкое read-only исследование в отдельном контексте.

Side не является изолированной копией рабочей директории. Родитель и side видят одни и те же файлы. По умолчанию side-инструкции направляют агента на non-mutating работу, но явно запрошенная пользователем правка разрешена и будет видна основному агенту. Такие изменения могут конфликтовать с параллельной работой родительского треда.

Ограничения внутри /side

• Нельзя открыть вложенный /side.
• Разрешены только /help, /copy, /diff, /mention, /status, /expand, /collapse (available_in_side_conversation в slash-commands/src/commands.rs).
• /goal, /plan, /model и остальные команды без side-флага недоступны.
• Side-тред ephemeral, поэтому у него нет собственной persistent goal и goal tools.

4. Code mode

Крейт code-mode/ реализует JavaScript code mode поверх in-process V8 runtime. Это не slash-команда: варианта /code-mode в SlashCommandId нет.

Два feature-флага ведут себя по-разному:

• code_mode = true добавляет model-visible инструменты exec и wait, но не скрывает обычные инструменты.
• code_mode_only = true также включает code_mode, скрывает от модели обычные инструменты и оставляет exec/wait точками входа. Остальные инструменты вызываются из JavaScript через объект tools.

Оба флага имеют статус UnderDevelopment и по умолчанию выключены. Описание exec и wait находится в code-mode/src/description.rs.

5. Взаимодействие механизмов

/new и /clear создают новый тред и не переносят в него цель. Чтобы вернуться к цели, нужно возобновить исходный тред через astracode sessions <thread-id>.

6. Типичный workflow с /goal

1. Пользователь:  /goal --budget 300k Add real-time collab to the editor,
                  verified by integration tests and without regressing offline editing
2. Модель:        исследует код, выполняет следующий конкретный шаг, проверяет результат
3. Runtime:       после завершения хода автоматически запускает продолжение, если цель
                  всё ещё active и тред свободен
4. Модель:        продолжает следующие шаги без отдельного сообщения "go"
5. Пользователь:  /goal pause

[позже]

6. Пользователь:  /goal resume
7. Runtime:       делает цель active и продолжает её, когда тред свободен
8. Модель:        завершает evidence-аудит и вызывает update_goal(status = "complete")

Если TUI был закрыт во время выполняющегося хода и цель получила paused, после astracode sessions <thread-id> TUI предложит возобновить её или оставить на паузе. Такой prompt показывается также для blocked и usage_limited.

Для budget_limited сначала увеличьте или снимите budget. complete не возобновляется автоматически. Конфигурационного ключа [goal] auto_resume_on_startup не существует.

7. Команды и связанные файлы

• /goal dispatch: astracode-rs/tui/src/chatwidget/slash_dispatch.rs.
• Goal UI: astracode-rs/tui/src/chatwidget/goal_menu.rs и astracode-rs/tui/src/bottom_pane/goal_args_popup.rs.
• Goal runtime: astracode-rs/core/src/goals.rs и astracode-rs/core/templates/goals/.
• Goal DB: astracode-rs/state/src/runtime/goals.rs и astracode-rs/state/src/model/thread_goal.rs.
• /plan dispatch: astracode-rs/tui/src/chatwidget/slash_dispatch.rs; инструкции: astracode-rs/collaboration-mode-templates/templates/plan.md.
• Подтверждение реализации плана: astracode-rs/tui/src/chatwidget/plan_implementation.rs.
• /side lifecycle: astracode-rs/tui/src/app/side.rs; инструкции: astracode-rs/slash-commands/prompt_side_developer_instructions.md и prompt_side_boundary.md.
• Скилл goal-usage: astracode-rs/skills/src/assets/samples/goal-usage/.

8. Рекомендации

• Измеримая цель: укажите результат, критерии проверки и ограничения, а не только общее направление работы.
• Budget: выбирайте лимит исходя из допустимого расхода и сложности задачи; универсального «правильного» диапазона нет.
• Evidence: перечислите тесты, команды или артефакты, которые подтверждают завершение.
• Pause при отвлечении: используйте /goal pause, если автоматическое продолжение сейчас нежелательно.
• Plan для неоднозначной крупной работы: сначала согласуйте решения в Plan, затем переходите в Default для реализации.
• Side для уточнений: используйте его для отдельных вопросов и read-only исследования; избегайте параллельных правок тех же файлов.