harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 10:05:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/server/CLAUDE.md
Nathan Flurry 5c594f07c8 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>
2026-03-05 17:53:29 -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.