План надзора за PTY и процессами

1. Проблема и цель

Нам нужен один надежный жизненный цикл для долгоживущего выполнения команд в:

  • exec запуски на переднем плане
  • exec фоновые запуски
  • process последующие действия (poll, log, send-keys, paste, submit, kill, remove)
  • Подпроцессы CLI agent runner

Цель - не просто поддержка PTY. Цель - предсказуемое владение, отмена, таймаут и очистка без небезопасных эвристик сопоставления процессов.

2. Область и границы

  • Сохранить реализацию внутренней в src/process/supervisor.
  • Не создавать новый пакет для этого.
  • Сохранить совместимость текущего поведения, где практично.
  • Не расширять область до воспроизведения терминала или сохранения сессий в стиле tmux.

3. Реализовано в этой ветке

Базовый уровень Supervisor уже присутствует

  • Модуль Supervisor присутствует в src/process/supervisor/*.
  • Exec runtime и CLI runner уже маршрутизируются через spawn и wait supervisor.
  • Финализация Registry идемпотентна.

Этот проход завершен

  1. Явный контракт команды PTY
  • SpawnInput теперь размеченное объединение в src/process/supervisor/types.ts.
  • Запуски PTY требуют ptyCommand вместо переиспользования общего argv.
  • Supervisor больше не перестраивает строки команд PTY из объединений argv в src/process/supervisor/supervisor.ts.
  • Exec runtime теперь передает ptyCommand напрямую в src/agents/bash-tools.exec-runtime.ts.
  1. Развязка типов слоя процесса
  • Типы Supervisor больше не импортируют SessionStdin из agents.
  • Контракт процессного локального stdin живет в src/process/supervisor/types.ts (ManagedRunStdin).
  • Адаптеры теперь зависят только от типов уровня процесса:
    • src/process/supervisor/adapters/child.ts
    • src/process/supervisor/adapters/pty.ts
  1. Улучшение владения жизненным циклом инструмента Process
  • src/agents/bash-tools.process.ts теперь запрашивает отмену через supervisor первым.
  • process kill/remove теперь используют резервное завершение process-tree, когда поиск supervisor пропускает.
  • remove сохраняет детерминированное поведение удаления, немедленно сбрасывая записи запущенной сессии после запроса завершения.
  1. Значения по умолчанию одного источника watchdog
  • Добавлены общие значения по умолчанию в src/agents/cli-watchdog-defaults.ts.
  • src/agents/cli-backends.ts использует общие значения по умолчанию.
  • src/agents/cli-runner/reliability.ts использует те же общие значения по умолчанию.
  1. Очистка мертвого помощника
  • Удален неиспользуемый путь помощника killSession из src/agents/bash-tools.shared.ts.
  1. Добавлены тесты прямого пути supervisor
  • Добавлен src/agents/bash-tools.process.supervisor.test.ts для покрытия kill и remove маршрутизации через отмену supervisor.
  1. Исправления пробелов надежности завершены
  • src/agents/bash-tools.process.ts теперь откатывается к реальному завершению процесса на уровне ОС, когда поиск supervisor пропускает.
  • src/process/supervisor/adapters/child.ts теперь использует семантику завершения process-tree для путей kill по умолчанию cancel/timeout.
  • Добавлена общая утилита process-tree в src/process/kill-tree.ts.
  1. Добавлено покрытие граничных случаев контракта PTY
  • Добавлен src/process/supervisor/supervisor.pty-command.test.ts для дословной пересылки команд PTY и отклонения пустых команд.
  • Добавлен src/process/supervisor/adapters/child.test.ts для поведения kill process-tree в отмене адаптера child.

4. Оставшиеся пробелы и решения

Статус надежности

Два требуемых пробела надежности для этого прохода теперь закрыты:

  • process kill/remove теперь имеет реальный откат завершения ОС, когда поиск supervisor пропускает.
  • child cancel/timeout теперь использует семантику kill process-tree для пути kill по умолчанию.
  • Регрессионные тесты были добавлены для обоих поведений.

Долговечность и согласование запуска

Поведение перезапуска теперь явно определено как жизненный цикл только в памяти.

  • reconcileOrphans() остается no-op в src/process/supervisor/supervisor.ts по дизайну.
  • Активные запуски не восстанавливаются после перезапуска процесса.
  • Эта граница намеренна для этого прохода реализации, чтобы избежать рисков частичного сохранения.

Продолжения поддерживаемости

  1. runExecProcess в src/agents/bash-tools.exec-runtime.ts все еще обрабатывает несколько обязанностей и может быть разделен на целевые помощники в продолжении.

5. План реализации

Проход реализации для требуемых пунктов надежности и контракта завершен.

Завершено:

  • process kill/remove откат реального завершения
  • отмена process-tree для пути kill по умолчанию адаптера child
  • регрессионные тесты для отката kill и пути kill адаптера child
  • тесты граничных случаев команды PTY под явной ptyCommand
  • явная граница перезапуска в памяти с reconcileOrphans() no-op по дизайну

Опциональное продолжение:

  • разделить runExecProcess на целевые помощники без расхождения поведения

6. Карта файлов

Супервизор процесса

  • src/process/supervisor/types.ts обновлен с размеченным вводом spawn и контрактом процессного локального stdin.
  • src/process/supervisor/supervisor.ts обновлен для использования явной ptyCommand.
  • src/process/supervisor/adapters/child.ts и src/process/supervisor/adapters/pty.ts развязаны от типов agent.
  • src/process/supervisor/registry.ts идемпотентная финализация не изменена и сохранена.

Интеграция Exec и process

  • src/agents/bash-tools.exec-runtime.ts обновлен для явной передачи команды PTY и сохранения пути отката.
  • src/agents/bash-tools.process.ts обновлен для отмены через supervisor с реальным откатом завершения process-tree.
  • src/agents/bash-tools.shared.ts удален прямой путь помощника kill.

Надежность CLI

  • src/agents/cli-watchdog-defaults.ts добавлен как общий базовый уровень.
  • src/agents/cli-backends.ts и src/agents/cli-runner/reliability.ts теперь используют одни и те же значения по умолчанию.

7. Запуск валидации в этом проходе

Юнит-тесты:

  • pnpm vitest src/process/supervisor/registry.test.ts
  • pnpm vitest src/process/supervisor/supervisor.test.ts
  • pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts
  • pnpm vitest src/process/supervisor/adapters/child.test.ts
  • pnpm vitest src/agents/cli-backends.test.ts
  • pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts
  • pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts
  • pnpm vitest src/agents/bash-tools.process.supervisor.test.ts
  • pnpm vitest src/process/exec.test.ts

E2E цели:

  • pnpm test:e2e src/agents/cli-runner.e2e.test.ts
  • pnpm test:e2e src/agents/bash-tools.exec.pty-fallback.e2e.test.ts src/agents/bash-tools.exec.background-abort.e2e.test.ts src/agents/bash-tools.process.send-keys.e2e.test.ts

Примечание по проверке типов:

  • pnpm tsgo в настоящее время падает в этом репо из-за предсуществующей проблемы зависимости типизации UI (разрешение @vitest/browser-playwright), не связанной с этой работой по надзору за процессами.

8. Сохраненные операционные гарантии

  • Поведение усиления окружения Exec не изменено.
  • Поток одобрения и allowlist не изменен.
  • Санитизация вывода и ограничения вывода не изменены.
  • Адаптер PTY все еще гарантирует урегулирование wait при принудительном kill и удалении слушателя.

9. Определение завершения

  1. Supervisor - владелец жизненного цикла для управляемых запусков.
  2. Spawn PTY использует явный контракт команды без реконструкции argv.
  3. Слой процесса не имеет зависимости типа от слоя agent для контрактов stdin supervisor.
  4. Значения по умолчанию Watchdog - один источник.
  5. Целевые юнит и e2e тесты остаются зелеными.
  6. Граница долговечности перезапуска явно документирована или полностью реализована.

10. Резюме

Ветка теперь имеет связную и более безопасную форму надзора:

  • явный контракт PTY
  • более чистое наслоение процесса
  • путь отмены, управляемый supervisor, для операций процесса
  • реальное резервное завершение, когда поиск supervisor пропускает
  • отмена process-tree для путей kill по умолчанию child-run
  • унифицированные значения по умолчанию watchdog
  • явная граница перезапуска в памяти (нет согласования orphan через перезапуск в этом проходе)