Kế hoạch giám sát PTY và Process

1. Vấn đề và mục tiêu

Chúng ta cần một vòng đời đáng tin cậy cho thực thi lệnh chạy lâu qua:

  • Chạy foreground exec
  • Chạy background exec
  • Hành động theo dõi process (poll, log, send-keys, paste, submit, kill, remove)
  • Subprocess runner agent CLI

Mục tiêu không chỉ là hỗ trợ PTY. Mục tiêu là quyền sở hữu có thể dự đoán, hủy, timeout và dọn dẹp không có heuristic khớp process không an toàn.

2. Phạm vi và ranh giới

  • Giữ triển khai nội bộ trong src/process/supervisor.
  • Không tạo package mới cho điều này.
  • Giữ tương thích hành vi hiện tại khi thực tế.
  • Không mở rộng phạm vi sang replay terminal hoặc lưu trữ phiên kiểu tmux.

3. Được triển khai trong branch này

Baseline supervisor đã có mặt

  • Module supervisor đã có tại src/process/supervisor/*.
  • Runtime exec và runner CLI đã được định tuyến qua spawn và wait supervisor.
  • Finalization registry là idempotent.

Pass này đã hoàn thành

  1. Hợp đồng lệnh PTY rõ ràng
  2. Tách rời kiểu lớp process
  3. Cải thiện quyền sở hữu vòng đời công cụ process
  4. Mặc định watchdog nguồn đơn
  5. Dọn dẹp helper đã chết
  6. Test đường dẫn supervisor trực tiếp được thêm
  7. Sửa khoảng trống độ tin cậy hoàn thành
  8. Bao phủ trường hợp biên hợp đồng PTY được thêm

4. Khoảng trống còn lại và quyết định

Trạng thái độ tin cậy

Hai khoảng trống độ tin cậy bắt buộc cho pass này bây giờ đã đóng:

  • process kill/remove bây giờ có dự phòng termination OS thực khi lookup supervisor bỏ lỡ.
  • cancel/timeout child bây giờ sử dụng ngữ nghĩa kill process-tree cho đường dẫn kill mặc định.
  • Test regression được thêm cho cả hai hành vi.

Độ bền và hòa giải khởi động

Hành vi khởi động lại bây giờ được định nghĩa rõ ràng như vòng đời chỉ trong bộ nhớ.

  • reconcileOrphans() vẫn là no-op trong src/process/supervisor/supervisor.ts theo thiết kế.
  • Run đang hoạt động không được khôi phục sau khi process khởi động lại.
  • Ranh giới này là cố ý cho pass triển khai này để tránh rủi ro lưu trữ một phần.

5. Kế hoạch triển khai

Pass triển khai cho các item độ tin cậy và hợp đồng bắt buộc hoàn thành.

Đã hoàn thành:

  • Dự phòng termination thực process kill/remove
  • Hủy process-tree cho đường dẫn kill mặc định adapter child
  • Test regression cho kill dự phòng và đường dẫn kill adapter child
  • Test trường hợp biên lệnh PTY dưới ptyCommand rõ ràng
  • Ranh giới khởi động lại trong bộ nhớ rõ ràng với reconcileOrphans() no-op theo thiết kế

Follow-up tùy chọn:

  • chia runExecProcess thành helper tập trung không có trôi dạt hành vi

6. Bản đồ file

Supervisor process

  • src/process/supervisor/types.ts được cập nhật với input spawn được phân biệt và hợp đồng stdin local process.
  • src/process/supervisor/supervisor.ts được cập nhật để sử dụng ptyCommand rõ ràng.
  • src/process/supervisor/adapters/child.ts và src/process/supervisor/adapters/pty.ts tách rời khỏi kiểu agent.
  • src/process/supervisor/registry.ts finalize idempotent không thay đổi và được giữ lại.

Tích hợp exec và process

  • src/agents/bash-tools.exec-runtime.ts được cập nhật để truyền lệnh PTY rõ ràng và giữ đường dẫn dự phòng.
  • src/agents/bash-tools.process.ts được cập nhật để hủy qua supervisor với dự phòng termination process-tree thực.
  • src/agents/bash-tools.shared.ts xóa đường dẫn helper kill trực tiếp.

7. Chạy xác thực trong pass này

Test đơn vị:

  • 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
  • (và nhiều test khác...)

Target e2e:

  • pnpm test:e2e src/agents/cli-runner.e2e.test.ts
  • pnpm test:e2e src/agents/bash-tools.exec.pty-fallback.e2e.test.ts

8. Đảm bảo hoạt động được bảo toàn

  • Hành vi củng cố env exec không thay đổi.
  • Luồng phê duyệt và allowlist không thay đổi.
  • Khử trùng output và giới hạn output không thay đổi.
  • Adapter PTY vẫn đảm bảo giải quyết wait khi kill bắt buộc và disposal listener.

9. Định nghĩa hoàn thành

  1. Supervisor là chủ sở hữu vòng đời cho run được quản lý.
  2. Spawn PTY sử dụng hợp đồng lệnh rõ ràng không có tái tạo argv.
  3. Lớp process không có phụ thuộc kiểu vào lớp agent cho hợp đồng stdin supervisor.
  4. Mặc định watchdog là nguồn đơn.
  5. Test đơn vị và e2e được nhắm mục tiêu vẫn xanh.
  6. Ranh giới độ bền khởi động lại được ghi lại rõ ràng hoặc được triển khai đầy đủ.

10. Tóm tắt

Branch bây giờ có shape giám sát mạch lạc và an toàn hơn:

  • hợp đồng PTY rõ ràng
  • phân lớp process sạch hơn
  • đường dẫn hủy điều khiển supervisor cho hoạt động process
  • termination dự phòng thực khi lookup supervisor bỏ lỡ
  • hủy process-tree cho đường dẫn kill mặc định child-run
  • mặc định watchdog thống nhất
  • ranh giới khởi động lại trong bộ nhớ rõ ràng (không có hòa giải orphan qua khởi động lại trong pass này)