diff --git a/CLAUDE.md b/CLAUDE.md index 877b4c9..dfcafd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,10 +40,10 @@ 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. -- The UI must reflect every field in AgentCapabilities; keep it in sync with `docs/agent-compatibility.mdx` and `agent_capabilities_for`. +- The UI must reflect every field in AgentCapabilities; keep it in sync with `docs/session-transcript-schema.mdx` and `agent_capabilities_for`. - 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/universal-schema.mdx` as the source of truth for universal schema terminology and keep it updated alongside schema changes. +- Use `docs/session-transcript-schema.mdx` as the source of truth for 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. - Keep the FAQ in `README.md` and `frontend/packages/website/src/components/FAQ.tsx` in sync. When adding or modifying FAQ entries, update both files. diff --git a/README.md b/README.md index 38d0a18..59b62fa 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ - **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 -- **Universal session schema**: [Universal schema](https://sandboxagent.dev/docs/universal-schema) to store agent transcripts +- **Universal session schema**: [Session transcript schema](https://sandboxagent.dev/docs/session-transcript-schema) to store agent transcripts - **Supports your sandbox provider**: Daytona, E2B, Vercel Sandboxes, and more - **Lightweight, portable Rust binary**: Install anywhere with 1 curl command - **Automatic agent installation**: Agents are installed on-demand when first used @@ -160,9 +160,9 @@ Debug sessions and events with the [Inspector UI](https://inspect.sandboxagent.d [Explore API](https://sandboxagent.dev/docs/api-reference) — [View Specification](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json) -### Universal Schema +### Session Transcript Schema -All events follow a [universal schema](https://sandboxagent.dev/docs/universal-schema) that normalizes differences between agents. +All events follow a [session transcript schema](https://sandboxagent.dev/docs/session-transcript-schema) that normalizes differences between agents. ### Tip: Extract credentials diff --git a/docs/agent-compatibility.mdx b/docs/agent-compatibility.mdx deleted file mode 100644 index 13222a4..0000000 --- a/docs/agent-compatibility.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Session Event Coverage" -description: "What appears in your session transcript for each agent." -icon: "table" ---- - -Each coding agent outputs events in its own native format. The sandbox-agent converts these into a [universal event schema](/docs/universal-schema), giving you a consistent session transcript regardless of which agent you use. - -This page shows which agent capabilities appear in the universal event stream. All agents retain their full native capabilities—this only reflects what's normalized into the universal schema. - -## Coverage Matrix - -| Feature | Claude | Codex | OpenCode | Amp | -|--------------------|:------:|:-----:|:------------:|:------------:| -| Stability | Stable | Stable| Experimental | Experimental | -| Text Messages | ✓ | ✓ | ✓ | ✓ | -| Tool Calls | ✓ | ✓ | ✓ | ✓ | -| Tool Results | ✓ | ✓ | ✓ | ✓ | -| Questions (HITL) | ✓ | | ✓ | | -| Permissions (HITL) | ✓ | ✓ | ✓ | - | -| Images | - | ✓ | ✓ | - | -| File Attachments | - | ✓ | ✓ | - | -| Session Lifecycle | - | ✓ | ✓ | - | -| Error Events | - | ✓ | ✓ | ✓ | -| Reasoning/Thinking | - | ✓ | - | - | -| Command Execution | - | ✓ | - | - | -| File Changes | - | ✓ | - | - | -| MCP Tools | - | ✓ | - | - | -| Streaming Deltas | ✓ | ✓ | ✓ | - | - -Agents: [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) - -- ✓ = Appears in session events -- \- = Agent supports natively, schema conversion coming soon -- (blank) = Not supported by agent - -## Feature Descriptions - -### Text Messages - -Basic message exchange between user and assistant. - -### Tool Calls & Results - -Visibility into tool invocations (file reads, command execution, etc.) and their results. When not natively supported, tool activity is embedded in message content. - -### Questions (HITL) - -Interactive questions the agent asks the user. Emits `question.requested` and `question.resolved` events. - -### Permissions (HITL) - -Permission requests for sensitive operations. Emits `permission.requested` and `permission.resolved` events. - -### Images - -Support for image attachments in messages. - -### File Attachments - -Support for file attachments in messages. - -### Session Lifecycle - -Native `session.started` and `session.ended` events. When not supported, the daemon emits synthetic lifecycle events. - -### Error Events - -Structured error events for runtime failures. - -### Reasoning/Thinking - -Extended thinking or reasoning content with visibility controls. - -### Command Execution - -Detailed command execution events with stdout/stderr. - -### File Changes - -Structured file modification events with diffs. - -### MCP Tools - -Model Context Protocol tool support. - -### Streaming Deltas - -Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`. - -## Synthetic Events - -For features not natively supported, the daemon generates synthetic events to maintain a consistent event stream. Synthetic events have: - -- `source: "daemon"` -- `synthetic: true` - -This lets you build UIs that work with any agent without special-casing each provider. - -## Request Support - -Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it. diff --git a/docs/docs.json b/docs/docs.json index d4a2ed8..0a67364 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -62,8 +62,7 @@ "pages": [ "cli", "inspector", - "universal-schema", - "agent-compatibility", + "session-transcript-schema", "cors", { "group": "AI", diff --git a/docs/universal-schema.mdx b/docs/session-transcript-schema.mdx similarity index 68% rename from docs/universal-schema.mdx rename to docs/session-transcript-schema.mdx index 3c3531a..7a527ef 100644 --- a/docs/universal-schema.mdx +++ b/docs/session-transcript-schema.mdx @@ -1,13 +1,85 @@ --- -title: "Universal Schema" -description: "Reference for the universal event and item schema." +title: "Session Transcript Schema" +description: "Universal event schema for session transcripts across all agents." icon: "brackets-curly" --- -The universal schema normalizes events from all supported agents (Claude Code, Codex, OpenCode, Amp) into a consistent format. This lets you build UIs and persistence layers that work with any agent without special-casing. +Each coding agent outputs events in its own native format. The sandbox-agent converts these into a universal event schema, giving you a consistent session transcript regardless of which agent you use. The schema is defined in [OpenAPI format](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json). See the [HTTP API Reference](/api-reference) for endpoint documentation. +## Coverage Matrix + +This table shows which agent capabilities appear in the universal event stream. All agents retain their full native capabilities—this only reflects what's normalized into the schema. + +| Feature | Claude | Codex | OpenCode | Amp | +|--------------------|:------:|:-----:|:------------:|:------------:| +| Stability | Stable | Stable| Experimental | Experimental | +| Text Messages | ✓ | ✓ | ✓ | ✓ | +| Tool Calls | ✓ | ✓ | ✓ | ✓ | +| Tool Results | ✓ | ✓ | ✓ | ✓ | +| Questions (HITL) | ✓ | | ✓ | | +| Permissions (HITL) | ✓ | ✓ | ✓ | - | +| Images | - | ✓ | ✓ | - | +| File Attachments | - | ✓ | ✓ | - | +| Session Lifecycle | - | ✓ | ✓ | - | +| Error Events | - | ✓ | ✓ | ✓ | +| Reasoning/Thinking | - | ✓ | - | - | +| Command Execution | - | ✓ | - | - | +| File Changes | - | ✓ | - | - | +| MCP Tools | - | ✓ | - | - | +| Streaming Deltas | ✓ | ✓ | ✓ | - | + +Agents: [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) + +- ✓ = Appears in session events +- \- = Agent supports natively, schema conversion coming soon +- (blank) = Not supported by agent + + + + Basic message exchange between user and assistant. + + + Visibility into tool invocations (file reads, command execution, etc.) and their results. When not natively supported, tool activity is embedded in message content. + + + Interactive questions the agent asks the user. Emits `question.requested` and `question.resolved` events. + + + Permission requests for sensitive operations. Emits `permission.requested` and `permission.resolved` events. + + + Support for image attachments in messages. + + + Support for file attachments in messages. + + + Native `session.started` and `session.ended` events. When not supported, the daemon emits synthetic lifecycle events. + + + Structured error events for runtime failures. + + + Extended thinking or reasoning content with visibility controls. + + + Detailed command execution events with stdout/stderr. + + + Structured file modification events with diffs. + + + Model Context Protocol tool support. + + + Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`. + + + +Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it. + ## UniversalEvent Every event from the API is wrapped in a `UniversalEvent` envelope.