mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 10:05:18 +00:00
72 lines
7.5 KiB
Markdown
72 lines
7.5 KiB
Markdown
# Universal ↔ Agent Term Mapping
|
|
|
|
Source of truth: generated agent schemas in `resources/agent-schemas/artifacts/json-schema/`.
|
|
|
|
Identifiers
|
|
|
|
+----------------------+------------------------+------------------------------------------+-----------------------------+------------------------+
|
|
| Universal term | Claude | Codex (app-server) | OpenCode | Amp |
|
|
+----------------------+------------------------+------------------------------------------+-----------------------------+------------------------+
|
|
| session_id | n/a (daemon-only) | n/a (daemon-only) | n/a (daemon-only) | n/a (daemon-only) |
|
|
| native_session_id | none | threadId | sessionID | none |
|
|
| item_id | synthetic | ThreadItem.id | Message.id | StreamJSONMessage.id |
|
|
| native_item_id | none | ThreadItem.id | Message.id | StreamJSONMessage.id |
|
|
+----------------------+------------------------+------------------------------------------+-----------------------------+------------------------+
|
|
|
|
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.
|
|
|
|
Events / Message Flow
|
|
|
|
+------------------------+------------------------------+--------------------------------------------+-----------------------------------------+----------------------------------+
|
|
| Universal term | Claude | Codex (app-server) | OpenCode | Amp |
|
|
+------------------------+------------------------------+--------------------------------------------+-----------------------------------------+----------------------------------+
|
|
| session.started | none | method=thread/started | type=session.created | none |
|
|
| session.ended | SDKMessage.type=result | no explicit session end (turn/completed) | no explicit session end (session.deleted)| type=done |
|
|
| message (user) | SDKMessage.type=user | item/completed (ThreadItem.type=userMessage)| message.updated (Message.role=user) | type=message |
|
|
| message (assistant) | SDKMessage.type=assistant | item/completed (ThreadItem.type=agentMessage)| message.updated (Message.role=assistant)| type=message |
|
|
| message.delta | synthetic | method=item/agentMessage/delta | type=message.part.updated (delta) | synthetic |
|
|
| tool call | synthetic from tool usage | method=item/mcpToolCall/progress | message.part.updated (part.type=tool) | type=tool_call |
|
|
| tool result | synthetic from tool usage | item/completed (tool result ThreadItem variants) | message.part.updated (part.type=tool, state=completed) | type=tool_result |
|
|
| permission.requested | none | none | type=permission.asked | none |
|
|
| permission.resolved | none | none | type=permission.replied | none |
|
|
| question.requested | ExitPlanMode tool (synthetic)| experimental request_user_input (payload) | type=question.asked | none |
|
|
| question.resolved | ExitPlanMode reply (synthetic)| experimental request_user_input (payload) | type=question.replied / question.rejected | none |
|
|
| error | SDKResultMessage.error | method=error | type=session.error (or message error) | type=error |
|
|
+------------------------+------------------------------+--------------------------------------------+-----------------------------------------+----------------------------------+
|
|
|
|
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 |
|
|
| 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 |
|
|
| 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 (OpenCode) | part delta before message | item.delta | If part arrives first, create item.started stub then delta |
|
|
+------------------------------+------------------------+--------------------------+--------------------------------------------------------------+
|
|
|
|
Delta handling
|
|
|
|
- Codex emits agent message and other deltas (e.g., item/agentMessage/delta).
|
|
- OpenCode emits part deltas via message.part.updated with a delta string.
|
|
- Claude and Amp do not emit deltas in their schemas.
|
|
|
|
Policy:
|
|
- Always emit item.delta across all providers.
|
|
- For providers without native deltas, emit a single synthetic delta containing the full content prior to item.completed.
|
|
- For providers with native deltas, forward as-is; also emit item.completed when final content is known.
|
|
|
|
Message normalization notes
|
|
|
|
- user vs assistant: normalized via role in the universal item; provider role fields or item types determine role.
|
|
- 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.
|