harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 11:02:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/server/CLAUDE.md
Nathan Flurry 4335ef6af6
feat: add process management API (#203) 
* feat: add process management API

Introduces a complete Process Management API for Sandbox Agent with process lifecycle management (start, stop, kill, delete), one-shot command execution, log streaming via SSE and WebSocket, stdin input, and PTY/terminal support. Includes new process_runtime module for managing process state, HTTP route handlers, OpenAPI documentation, and integration tests.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* fix: address review issues in process management API

- Add doc comments to all 13 new #[utoipa::path] handlers (CLAUDE.md compliance)
- Fix send_signal ESRCH check: use raw_os_error() == Some(libc::ESRCH) instead of ErrorKind::NotFound
- Add max_input_bytes_per_request enforcement in WebSocket terminal handler
- URL-decode access_token query parameter for WebSocket auth
- Replace fragile string prefix matching with proper SandboxError::NotFound variant

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* feat: add TypeScript SDK support for process management

Add process CRUD operations (create, get, list, update, delete) and
event streaming to the TypeScript SDK. Includes integration tests,
mock agent updates, and test environment fixes for cross-platform
home directory handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: provide WebSocket impl for process terminal test on Node 20

Node 20 lacks globalThis.WebSocket. Add ws as a devDependency and
pass it to connectProcessTerminalWebSocket in the integration test
so CI no longer fails.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
2026-03-05 18:20:20 -08:00

1.6 KiB
Raw Blame History

Server Instructions

Architecture

  • Public API routes are defined in server/packages/sandbox-agent/src/router.rs.
  • ACP proxy runtime is in server/packages/sandbox-agent/src/acp_proxy_runtime.rs.
  • All API endpoints are under /v1.
  • Keep binary filesystem transfer endpoints as dedicated HTTP APIs:
    • GET /v1/fs/file
    • PUT /v1/fs/file
    • POST /v1/fs/upload-batch
    • Rationale: host-owned cross-agent-consistent behavior and large binary transfer needs that ACP JSON-RPC is not suited to stream efficiently.
    • Maintain ACP variants in parallel only when they share the same underlying filesystem implementation; SDK defaults should still prefer HTTP for large/binary transfers.
  • /opencode/* stays disabled (503) until Phase 7.
  • Agent install logic (native + ACP agent process + lazy install) is handled by server/packages/agent-management/.

API Contract Rules

  • Every #[utoipa::path(...)] handler needs a summary line + description lines in its doc comment.
  • Every responses(...) entry must include description.
  • Regenerate docs/openapi.json after endpoint contract changes.
  • Keep CLI and HTTP endpoint behavior aligned (docs/cli.mdx).

Tests

Primary v1 integration coverage:

  • server/packages/sandbox-agent/tests/v1_api.rs
  • server/packages/sandbox-agent/tests/v1_agent_process_matrix.rs

Run:

cargo test -p sandbox-agent --test v1_api
cargo test -p sandbox-agent --test v1_agent_process_matrix

Migration Docs Sync

  • Keep research/acp/spec.md as the source spec.
  • Update research/acp/todo.md when scope/status changes.
  • Log blockers/decisions in research/acp/friction.md.