feat: sync universal schema and sdk updates

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.