harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 06:04:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/sdks/CLAUDE.md
Nathan Flurry 99abb9d42e
chore(foundry): workbench action responsiveness (#254) 
* wip

* wip
2026-03-14 20:42:18 -07:00

2.9 KiB
Raw Permalink Blame History

SDK Instructions

TypeScript SDK Architecture

  • TypeScript clients are split into:
    • acp-http-client: protocol-pure ACP-over-HTTP (/v1/acp) with no Sandbox-specific HTTP helpers.
    • sandbox-agent: SandboxAgent SDK wrapper that combines ACP session operations with Sandbox control-plane and filesystem helpers.
  • SandboxAgent entry points are SandboxAgent.connect(...) and SandboxAgent.start(...).
  • Stable Sandbox session methods are createSession, resumeSession, resumeOrCreateSession, destroySession, rawSendSessionMethod, onSessionEvent, setSessionMode, setSessionModel, setSessionThoughtLevel, setSessionConfigOption, getSessionConfigOptions, getSessionModes, respondPermission, rawRespondPermission, and onPermissionRequest.
  • Session helpers are prompt(...), rawSend(...), onEvent(...), setMode(...), setModel(...), setThoughtLevel(...), setConfigOption(...), getConfigOptions(), getModes(), respondPermission(...), rawRespondPermission(...), and onPermissionRequest(...).
  • Cleanup is sdk.dispose().

React Component Methodology

  • Shared React UI belongs in sdks/react only when it is reusable outside the Inspector.
  • If the same UI pattern is shared between the Sandbox Agent Inspector and Foundry, prefer extracting it into sdks/react instead of maintaining parallel implementations.
  • Keep shared components unstyled by default: behavior in the package, styling in the consumer via className, slot-level classNames, render overrides, and data-* hooks.
  • Prefer extracting reusable pieces such as transcript, composer, and conversation surfaces. Keep Inspector-specific shells such as session selection, session headers, and control-plane actions in frontend/packages/inspector/.
  • Document all shared React components in docs/react-components.mdx, and keep that page aligned with the exported surface in sdks/react/src/index.ts.

TypeScript SDK Naming Conventions

  • Use respond<Thing>(id, reply) for SDK methods that reply to an agent-initiated request (e.g. respondPermission). This is the standard pattern for answering any inbound JSON-RPC request from the agent.
  • Prefix raw/low-level escape hatches with raw (e.g. rawRespondPermission, rawSend). These accept protocol-level types directly and bypass SDK abstractions.

Docs Source Of Truth

  • For TypeScript docs/examples, source of truth is implementation in:
    • sdks/typescript/src/client.ts
    • sdks/typescript/src/index.ts
    • sdks/acp-http-client/src/index.ts
  • Do not document TypeScript APIs unless they are exported and implemented in those files.

Tests

  • TypeScript SDK tests should run against a real running server/runtime over real /v1 HTTP APIs, typically using the real mock agent for deterministic behavior.
  • Do not use Vitest fetch/transport mocks to simulate server functionality in TypeScript SDK tests.