Перейти к основному содержимому

Эксперименты

План супервизии PTY и процессов

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

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

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

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

2. Область действия и границы​

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

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

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

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

В этом этапе завершено​

  1. Явный контракт PTY-команды
  • SpawnInput теперь является размеченным объединением в src/process/supervisor/types.ts.
  • Для PTY-запусков требуется ptyCommand вместо повторного использования общего argv.
  • Супервизор больше не пересобирает строки PTY-команд из объединения argv в src/process/supervisor/supervisor.ts.
  • Exec runtime теперь передает ptyCommand напрямую в src/agents/bash-tools.exec-runtime.ts.
  1. Разделение типов на уровне процесса
  • Типы супервизора больше не импортируют SessionStdin из агентов.
  • Контракт локального stdin процесса находится в src/process/supervisor/types.ts (ManagedRunStdin).
  • Адаптеры теперь зависят только от типов уровня процесса:
    • src/process/supervisor/adapters/child.ts
    • src/process/supervisor/adapters/pty.ts
  1. Улучшение владения жизненным циклом инструментов процесса
  • src/agents/bash-tools.process.ts теперь запрашивает отмену сначала через супервизор.
  • process kill/remove теперь используют завершение через дерево процессов в качестве запасного варианта, если поиск в супервизоре не дал результатов.
  • 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. Добавлены тесты прямого пути супервизора
  • Добавлен src/agents/bash-tools.process.supervisor.test.ts для покрытия маршрутизации kill и remove через отмену в супервизоре.
  1. Устранены пробелы в надежности
  • src/agents/bash-tools.process.ts теперь использует реальное завершение процесса на уровне ОС в качестве запасного варианта, если поиск в супервизоре не дал результатов.
  • src/process/supervisor/adapters/child.ts теперь использует семантику завершения дерева процессов для путей отмены/таймаута по умолчанию.
  • Добавлена общая утилита для работы с деревом процессов в src/process/kill-tree.ts.
  1. Добавлено покрытие крайних случаев контракта PTY
  • Добавлен src/process/supervisor/supervisor.pty-command.test.ts для проверки дословной передачи PTY-команды и отклонения пустых команд.
  • Добавлен src/process/supervisor/adapters/child.test.ts для проверки поведения завершения дерева процессов при отмене в адаптере child.

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

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

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

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

Устойчивость и восстановление при запуске​

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

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

Последующие действия по поддержке​

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

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

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

  • Запасной вариант реального завершения для process kill/remove
  • Отмена через дерево процессов для пути 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 отделены от типов агентов.
  • src/process/supervisor/registry.ts идемпотентная финализация не изменена и сохранена.

Интеграция Exec и Process​

  • src/agents/bash-tools.exec-runtime.ts обновлен для явной передачи PTY-команды и сохранения запасного пути.
  • src/agents/bash-tools.process.ts обновлен для отмены через супервизор с запасным вариантом реального завершения дерева процессов.
  • 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 vitest src/agents/cli-runner.test.ts
  • pnpm vitest run src/agents/bash-tools.exec.pty-fallback.test.ts src/agents/bash-tools.exec.background-abort.test.ts src/agents/bash-tools.process.send-keys.test.ts

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

  • Используйте pnpm build (и pnpm check для полной проверки линтера/документации) в этом репозитории. Более старые заметки, упоминающие pnpm tsgo, устарели.

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

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

9. Критерии завершения​

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

10. Итог​

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

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

План шлюза OpenResponsesПлан агностического канала привязки сессии