feat: sync universal schema and sdk updates

Author: NathanFlurry

CLAUDE.md

@@ -38,6 +38,11 @@ Universal schema guidance:
 - Never use synthetic data or mocked responses in tests.
 - Never manually write agent types; always use generated types in `resources/agent-schemas/`. If types are broken, fix the generated types.
 - The universal schema must provide consistent behavior across providers; avoid requiring frontend/client logic to special-case agents.
+- When parsing agent data, if something is unexpected or does not match the schema, bail out and surface the error rather than trying to continue with partial parsing.
+- When defining the universal schema, choose the option most compatible with native agent APIs, and add synthetics to fill gaps for other agents.
+- Use `docs/glossary.md` as the source of truth for universal schema terminology and keep it updated alongside schema changes.
+- On parse failures, emit an `agent.unparsed` event (source=daemon, synthetic=true) and treat it as a test failure. Preserve raw payloads when `include_raw=true`.
+- Track subagent support in `docs/conversion.md`. For now, normalize subagent activity into normal message/tool flow, but revisit explicit subagent modeling later.
 
 ### CLI ⇄ HTTP endpoint map (keep in sync)
 

Cargo.toml

@@ -12,7 +12,7 @@ description = "Universal agent API for AI coding assistants"
 
 [workspace.dependencies]
 # Internal crates
-sandbox-agent-core = { path = "server/packages/sandbox-agent" }
+sandbox-agent = { path = "server/packages/sandbox-agent" }
 sandbox-agent-error = { path = "server/packages/error" }
 sandbox-agent-agent-management = { path = "server/packages/agent-management" }
 sandbox-agent-agent-credentials = { path = "server/packages/agent-credentials" }

README.md

@@ -1,6 +1,6 @@
 # Sandbox Agent SDK
 
-Universal API for running Claude Code, Codex, OpenCode, and Amp inside sandboxes.
+Universal API for automatic coding agents in sandboxes. Supprots Claude Code, Codex, OpenCode, and Amp.
 
 - **Any coding agent**: Universal API to interact with all agents with full feature coverage
 - **Server or SDK mode**: Run as an HTTP server or with the TypeScript SDK
@@ -16,14 +16,14 @@ Roadmap:
 
 ## Agent Support
 
-| Feature | [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) | [Codex](https://github.com/openai/codex) | [OpenCode](https://github.com/opencode-ai/opencode) | [Amp](https://ampcode.com) |
+| Feature | [Claude Code*](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) | [Codex](https://github.com/openai/codex) | [OpenCode](https://github.com/opencode-ai/opencode) | [Amp](https://ampcode.com) |
 |---------|:-----------:|:-----:|:--------:|:---:|
 | Stability | Stable | Stable | Experimental | Experimental |
 | Text Messages | ✓ | ✓ | ✓ | ✓ |
-| Tool Calls | ✓ | ✓ | ✓ | ✓ |
-| Tool Results | ✓ | ✓ | ✓ | ✓ |
-| Questions (HITL) | ✓ | | ✓ | |
-| Permissions (HITL) | | | ✓ | |
+| Tool Calls | —* | ✓ | ✓ | ✓ |
+| Tool Results | —* | ✓ | ✓ | ✓ |
+| Questions (HITL) | —* | | ✓ | |
+| Permissions (HITL) | —* | | ✓ | |
 | Images | | ✓ | ✓ | |
 | File Attachments | | ✓ | ✓ | |
 | Session Lifecycle | | ✓ | ✓ | |
@@ -34,13 +34,15 @@ Roadmap:
 | MCP Tools | | ✓ | | |
 | Streaming Deltas | | ✓ | ✓ | |
 
+* Claude headless CLI does not natively support tool calls/results or HITL questions/permissions yet; these are WIP.
+
 Want support for another agent? [Open an issue](https://github.com/anthropics/sandbox-agent/issues/new) to request it.
 
 ## Architecture
 
 - TODO
-    - Embedded (runs agents locally)
-    - Sandboxed
+    - Local
+    - Remote/Sandboxed
 
 ## Components
 
@@ -49,6 +51,26 @@ Want support for another agent? [Open an issue](https://github.com/anthropics/sa
 - Inspector: inspect.sandboxagent.dev
 - CLI: TODO
 
+## Quickstart
+
+### SDK
+
+- Local
+- Remote/Sandboxed 
+
+Docs
+
+### Server
+
+- Run server
+- Auth
+
+Docs
+
+### CLI
+
+Docs
+
 ## Project Goals
 
 This project aims to solve 3 problems with agents:
@@ -98,4 +120,3 @@ TODO
 
 - the harnesses do a lot of heavy lifting
 - the difference between opencode, claude, and codex is vast & vastly opinionated
-

ROADMAP.md

@@ -1,12 +1,19 @@
 ## launch
 
+- provide mock data for validating your rendering
+    - provides history with all items, then iterates thorugh all items on a stream
+    - this is a special type of serve function
+    - make sure claude.md covers everything
 - re-review agent schemas and compare it to ours
+- write integration guide
+- add optional raw payloads to events via query parameters
 - auto-serve frontend from cli
 - verify embedded sdk works
 - fix bugs in ui
     - double messages
     - user-sent messages
     - permissions
+- add an API option to stream only the next assistant item after a posted message (single-response stream)
 - consider migraing our standard to match the vercel ai standard
 - discuss actor arch in readme + give example
 - skillfile
@@ -18,9 +25,18 @@
 - **Auto-configure MCP & Skills**: Auto-load MCP servers & skills for your agents
 - **Process & logs manager**: Manage processes, logs, and ports for your agents to run background processes
 - **Codex app-server concurrency**: Run a single shared Codex app-server with multiple threads in parallel (like OpenCode), with file-write safety
+- persistence
 
 ## later
 
+- missing features
+    - file changes
+- api compat
+    - vercel ai sdk + hono proxy
+    - tanstack ai
+    - opencode ui
+- synthetic question tool
+    - since claude headless does not support this
 - guides:
     - ralph
     - swarms

docker/release/linux-x86_64.Dockerfile

@@ -20,7 +20,7 @@ RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
     --mount=type=cache,target=/build/target \
     RUSTFLAGS="-C target-feature=+crt-static" \
-    cargo build -p sandbox-agent-core --release --target x86_64-unknown-linux-musl && \
+    cargo build -p sandbox-agent --release --target x86_64-unknown-linux-musl && \
     mkdir -p /artifacts && \
     cp target/x86_64-unknown-linux-musl/release/sandbox-agent /artifacts/sandbox-agent-x86_64-unknown-linux-musl
 

docker/release/macos-aarch64.Dockerfile

@@ -55,7 +55,7 @@ COPY . .
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
     --mount=type=cache,target=/build/target \
-    cargo build -p sandbox-agent-core --release --target aarch64-apple-darwin && \
+    cargo build -p sandbox-agent --release --target aarch64-apple-darwin && \
     mkdir -p /artifacts && \
     cp target/aarch64-apple-darwin/release/sandbox-agent /artifacts/sandbox-agent-aarch64-apple-darwin
 

docker/release/macos-x86_64.Dockerfile

@@ -55,7 +55,7 @@ COPY . .
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
     --mount=type=cache,target=/build/target \
-    cargo build -p sandbox-agent-core --release --target x86_64-apple-darwin && \
+    cargo build -p sandbox-agent --release --target x86_64-apple-darwin && \
     mkdir -p /artifacts && \
     cp target/x86_64-apple-darwin/release/sandbox-agent /artifacts/sandbox-agent-x86_64-apple-darwin
 

docker/release/windows.Dockerfile

@@ -42,7 +42,7 @@ COPY . .
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
     --mount=type=cache,target=/build/target \
-    cargo build -p sandbox-agent-core --release --target x86_64-pc-windows-gnu && \
+    cargo build -p sandbox-agent --release --target x86_64-pc-windows-gnu && \
     mkdir -p /artifacts && \
     cp target/x86_64-pc-windows-gnu/release/sandbox-agent.exe /artifacts/sandbox-agent-x86_64-pc-windows-gnu.exe
 

docs/conversion.md

@@ -17,6 +17,10 @@ Notes:
 - When a provider does not supply IDs (Claude), we synthesize item_id values and keep native_item_id null.
 - native_session_id is the only provider session identifier. It is intentionally used for thread/session/run ids.
 - native_item_id preserves the agent-native item/message id when present.
+- source indicates who emitted the event: agent (native) or daemon (synthetic).
+- raw is always present on events. When clients do not opt-in to raw payloads, raw is null.
+- opt-in via `include_raw=true` on events endpoints (HTTP + SSE).
+- If parsing fails, emit agent.unparsed (source=daemon, synthetic=true). Tests must assert zero unparsed events.
 
 Events / Message Flow
 
@@ -42,14 +46,14 @@ Synthetics
 +------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
 | Synthetic element            | When it appears        | Stored as               | Notes                                                        |
 +------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
-| session.started              | When agent emits no explicit start | session.started event | Mark origin=daemon                                            |
-| session.ended                | When agent emits no explicit end   | session.ended event   | Mark origin=daemon; reason may be inferred                    |
+| session.started              | When agent emits no explicit start | session.started event | Mark source=daemon                                            |
+| session.ended                | When agent emits no explicit end   | session.ended event   | Mark source=daemon; reason may be inferred                    |
 | item_id (Claude)             | Claude provides no item IDs        | item_id               | Maintain provider_item_id map when possible                   |
-| user message (Claude)        | Claude emits only assistant output | item.completed        | Mark origin=daemon; preserve raw input in event metadata       |
+| user message (Claude)        | Claude emits only assistant output | item.completed        | Mark source=daemon; preserve raw input in event metadata       |
 | question events (Claude)     | Plan mode ExitPlanMode tool usage  | question.requested/resolved | Synthetic mapping from tool call/result                       |
 | native_session_id (Codex)    | Codex uses threadId                | native_session_id     | Intentionally merged threadId into native_session_id          |
 +------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
-| message.delta (Claude/Amp)   | No native deltas               | item.delta             | Synthetic delta with full message content; origin=daemon       |
+| message.delta (Claude/Amp)   | No native deltas               | item.delta             | Synthetic delta with full message content; source=daemon       |
 +------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
 | message.delta (OpenCode)     | part delta before message       | item.delta             | If part arrives first, create item.started stub then delta     |
 +------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
@@ -68,5 +72,9 @@ Policy:
 Message normalization notes
 
 - user vs assistant: normalized via role in the universal item; provider role fields or item types determine role.
+- file artifacts: always represented as content parts (type=file_ref) inside message/tool_result items, not a separate item kind.
+- reasoning: represented as content parts (type=reasoning) inside message items, with visibility when available.
+- subagents: OpenCode subtask parts and Claude Task tool usage are currently normalized into standard message/tool flow (no dedicated subagent fields).
 - OpenCode unrolling: message.updated creates/updates the parent message item; tool-related parts emit separate tool item events (item.started/ item.completed) with parent_id pointing to the message item.
-- If a message.part.updated arrives before message.updated, we create a stub item.started (origin=daemon) so deltas have a parent.
+- If a message.part.updated arrives before message.updated, we create a stub item.started (source=daemon) so deltas have a parent.
+- Tool calls/results are always emitted as separate tool items to keep behavior consistent across agents.

docs/glossary.md

@@ -0,0 +1,62 @@
+# Glossary (Universal Schema)
+
+This glossary defines the universal schema terms used across the daemon, SDK, and tests.
+
+Session terms
+- session_id: daemon-generated identifier for a universal session.
+- native_session_id: provider-native thread/session/run identifier (thread_id merged here).
+- session.started: event emitted at session start (native or synthetic).
+- session.ended: event emitted at session end (native or synthetic); includes reason and terminated_by.
+- terminated_by: who ended the session: agent or daemon.
+- reason: why the session ended: completed, error, or terminated.
+
+Event terms
+- UniversalEvent: envelope that wraps all events; includes source, type, data, raw.
+- event_id: unique identifier for the event.
+- sequence: monotonic event sequence number within a session.
+- time: RFC3339 timestamp for the event.
+- source: event origin: agent (native) or daemon (synthetic).
+- raw: original provider payload for native events; optional for synthetic events.
+
+Item terms
+- item_id: daemon-generated identifier for a universal item.
+- native_item_id: provider-native item/message identifier when available; null otherwise.
+- parent_id: item_id of the parent item (e.g., tool call/result parented to a message).
+- kind: item category: message, tool_call, tool_result, system, status, unknown.
+- role: actor role for message items: user, assistant, system, tool (or null).
+- status: item lifecycle status: in_progress, completed, failed (or null).
+
+Item event terms
+- item.started: item creation event (may be synthetic).
+- item.delta: streaming delta event (native where supported; synthetic otherwise).
+- item.completed: final item event with complete content.
+
+Content terms
+- content: ordered list of parts that make up an item payload.
+- content part: a typed element inside content (text, json, tool_call, tool_result, file_ref, image, status, reasoning).
+- text: plain text content part.
+- json: structured JSON content part.
+- tool_call: tool invocation content part (name, arguments, call_id).
+- tool_result: tool result content part (call_id, output).
+- file_ref: file reference content part (path, action, diff).
+- image: image content part (path, mime).
+- status: status content part (label, detail).
+- reasoning: reasoning content part (text, visibility).
+- visibility: reasoning visibility: public or private.
+
+HITL terms
+- permission.requested / permission.resolved: human-in-the-loop permission flow events.
+- permission_id: identifier for the permission request.
+- question.requested / question.resolved: human-in-the-loop question flow events.
+- question_id: identifier for the question request.
+- options: question answer options.
+- response: selected answer for a question.
+
+Synthetic terms
+- synthetic event: a daemon-emitted event used to fill gaps in provider-native schemas.
+- source=daemon: marks synthetic events.
+- synthetic delta: a single full-content delta emitted for providers without native deltas.
+
+Provider terms
+- agent: the native provider (claude, codex, opencode, amp).
+- native payload: the provider’s original event/message object stored in raw.