# GET /v1/sessions/{session_id}/events - List events (JSON) Source: GET /v1/sessions/{session\_id}/events Select code samplecURL (shell:curl) ```js const url = 'https://app.everruns.com/api/v1/sessions/example/events'; const options = {method: 'GET'}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://app.everruns.com/api/v1/sessions/example/events ``` * Production APIapp.everruns.com/api/v1/sessions/{session\_id}/events Returns events for a session as a JSON array. Supports filtering by event type via `types` (positive: only these types) and `exclude` (negative: remove these types). When both are provided, `types` narrows first, then `exclude` removes from that set. Both accept only known event types (max 25 per parameter). Unknown types return 400. ## Pagination Supports backward pagination via `limit` and `before_sequence`: * `limit=200` returns the last 200 events (oldest→newest) * `limit=200&before_sequence=4500` returns 200 events before sequence 4500 * When `limit` is provided, the response includes an `X-Total-Count` header with the count of non-delta events for the session * Turn boundary snapping: when fetching older pages, the batch boundary snaps to the nearest `turn.started` event to avoid splitting turns * Without `limit`, all events are returned (backward compatible) ## Parameters ### Path Parameters **session\_id** required string Session ID (prefixed, e.g., sess\_…) ### Query Parameters **since\_id** One of: * string Prefixed identifier with ‘event’ prefix string /^event\_\[0-9a-f]{32}$/ ##### Example ```plaintext event_01933b5a000070008000000000000001 ``` * null null Filter events with ID greater than this event ID (prefixed format: event\_{32-hex}) **types** Array\ Positive type filter (repeat key). Empty = all types. **exclude** Array\ Event types to exclude (repeat key); applied after `types`. **limit** integer | null format: int32 \>= 1 <= 1000 Max events to return (backward pagination). When set, returns the last N events (or last N before `before_sequence`). Results are ordered oldest→newest. **before\_sequence** integer | null format: int32 Cursor for backward pagination: only return events with sequence < this value. **after\_sequence** integer | null format: int32 Forward cursor: only return events with sequence > this value. **around** One of: * string Prefixed identifier with ‘event’ prefix string /^event\_\[0-9a-f]{32}$/ ##### Example ```plaintext event_01933b5a000070008000000000000001 ``` * null null Anchor event id: returns up to `window` events on each side (default 50, max 500). Mutually exclusive with `since_id`, `after_sequence`, and `before_sequence` — 400 if combined. **window** integer | null format: int32 Window size for `around` (events on each side). Defaults to 50, max 500. **from\_ts** string | null format: date-time Lower bound on `created_at` (RFC 3339, e.g. `2025-05-07T00:00:00Z`). **to\_ts** string | null format: date-time Upper bound on `created_at`. **turn\_id** string | null Filter by `context.turn_id` (prefixed id, e.g. `turn_...`). **exec\_id** string | null Filter by `context.exec_id` (prefixed id, e.g. `exec_...`). **trace\_id** string | null Filter by `context.trace_id`. **tags** Array\ Tag any-match against `events.tags` (repeat key for multiple values). **tool\_name** string | null Filter by `data.tool_name` — useful for narrowing `tool.*` events. **q** string | null Full-text search (Postgres tsvector; substring fallback for in-memory mode). **order\_desc** boolean When true, return newest first; default oldest first. ## Responses ### 200 Events list Media typeapplication/json Response wrapper for list endpoints. All list endpoints return responses wrapped in a `data` field. object **data** required Array of items returned by the list operation. Array\ Standard event following the Everruns event protocol. All events have a consistent structure: * `id`: Unique event identifier (format: event\_{32-hex}) * `type`: Event type in dot notation (e.g., “input.message”, “reason.started”) * `ts`: ISO 8601 timestamp with millisecond precision * `session_id`: Session this event belongs to (format: session\_{32-hex}) * `context`: Correlation context for tracing * `data`: Event-specific payload (typed via EventData enum) * `metadata`: Optional arbitrary metadata * `tags`: Optional list of tags for filtering object **context** required Correlation context object **exec\_id** Atom execution identifier string | null **input\_message\_id** User message that triggered this turn string | null **parent\_span\_id** Parent span ID for hierarchical linking (OTel-style). Links this span to its parent in the trace hierarchy. string | null **span\_id** This event’s span ID for observability (OTel-style). Uniquely identifies this span within the trace. string | null **trace\_id** Trace ID for observability (OTel-style). Groups related spans into a single trace. For agent turns, this is typically the turn\_id string. string | null **turn\_id** Turn identifier (for turn-scoped events) string | null **data** required One of: * object Data for input.message event object **message** required The user message object **content** required Message content as array of content parts (text, images, tool calls, tool results) Array One of: * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque **controls** One of: * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * null Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * string null * null null **created\_at** required Timestamp when the message was created string format: date-time **external\_actor** One of: * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * null null **id** required Unique message ID (format: message\_{32-hex}) string **metadata** Message-level metadata object | null **phase** One of: * string Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * null null **phase\_source** One of: * string Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * null null **role** required Message role string Allowed values: system user agent tool\_result * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * object Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * object null * object null * object null * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * object null * object Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * object null * object Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * object null * object Data for output.message.delta event Incremental text update during LLM generation. Events are batched (\~100ms) to reduce volume while providing real-time feedback. object **accumulated** required Accumulated text so far string **delta** required The new text chunk string **message\_id** required Stable public ID for this assistant message across its streaming lifecycle. This is the same identifier as `OutputMessageCompletedData.message.id`. string **phase** One of: * string Best-effort streamed phase hint (EVE-774). `None` means “not yet classified — treat as ordinary assistant text”, NEVER “thinking”. Refinement is monotonic: once a stream reveals a native phase (`Commentary` or `FinalAnswer`) it stays fixed for the rest of the message — it never flip-flops and never reverts to `None` (see `ExecutionPhase::refine_streamed_hint`). Providers without native mid-stream phase (Anthropic, Gemini, …) leave this `None` until completion. The authoritative classification remains the completed `RuntimeMessage.phase`. string Allowed values: commentary final\_answer * null null **turn\_id** required Turn ID this delta belongs to string * object Best-effort streamed phase hint (EVE-774). `None` means “not yet classified — treat as ordinary assistant text”, NEVER “thinking”. Refinement is monotonic: once a stream reveals a native phase (`Commentary` or `FinalAnswer`) it stays fixed for the rest of the message — it never flip-flops and never reverts to `None` (see `ExecutionPhase::refine_streamed_hint`). Providers without native mid-stream phase (Anthropic, Gemini, …) leave this `None` until completion. The authoritative classification remains the completed `RuntimeMessage.phase`. string Allowed values: commentary final\_answer * object null * object Data for output.message.started event Emitted when the LLM starts generating a response. UI can show a “thinking” indicator until output.message.delta or output.message.completed events arrive. object **iteration** Current iteration number within this turn (1-based). Useful for UI to show progress during multi-step tool-calling flows. integer | null format: int32 **message\_id** required Stable public ID for this assistant message across its streaming lifecycle. This is the same identifier as `OutputMessageCompletedData.message.id`. string **model** Optional model name being used string | null **phase** One of: * string Best-effort streamed phase hint (EVE-774). `None` means “not yet classified — treat as ordinary assistant text”, NEVER “thinking”. A missing/unknown phase must fall back to the assistant-text channel, never the reasoning channel. Only populated when the provider stream reveals a native phase before this event is emitted; today `output.message.started` is emitted before the LLM call, so this is generally `None` at start. The authoritative classification remains the completed `RuntimeMessage.phase`. string Allowed values: commentary final\_answer * null null **reasoning\_state** One of: * object Prepared Astra effort state, persisted before the provider call so an interrupted worker can resume without changing the request baseline. object **baseline** One of: * string Original request-level effort preserved throughout this epoch. string Allowed values: none minimal low medium high xhigh max * null null **effective** One of: * string Effort currently active after ordered configuration updates. string Allowed values: none minimal low medium high xhigh max * null null **epoch** required A new epoch starts when switching model/provider or entering this mode. string * null Original request-level effort preserved throughout this epoch. string Allowed values: none minimal low medium high xhigh max * string null * null Effort currently active after ordered configuration updates. string Allowed values: none minimal low medium high xhigh max * string null * null null **turn\_id** required Turn ID this output belongs to string * object Best-effort streamed phase hint (EVE-774). `None` means “not yet classified — treat as ordinary assistant text”, NEVER “thinking”. A missing/unknown phase must fall back to the assistant-text channel, never the reasoning channel. Only populated when the provider stream reveals a native phase before this event is emitted; today `output.message.started` is emitted before the LLM call, so this is generally `None` at start. The authoritative classification remains the completed `RuntimeMessage.phase`. string Allowed values: commentary final\_answer * object null * object Prepared Astra effort state, persisted before the provider call so an interrupted worker can resume without changing the request baseline. object **baseline** One of: * string Original request-level effort preserved throughout this epoch. string Allowed values: none minimal low medium high xhigh max * null null **effective** One of: * string Effort currently active after ordered configuration updates. string Allowed values: none minimal low medium high xhigh max * null null **epoch** required A new epoch starts when switching model/provider or entering this mode. string * object Original request-level effort preserved throughout this epoch. string Allowed values: none minimal low medium high xhigh max * object null * object Effort currently active after ordered configuration updates. string Allowed values: none minimal low medium high xhigh max * object null * object null * object Data for `output.message.replaced` event. Emitted between the last (suppressed) `output.message.delta` and the final `output.message.completed`. Tells the client to discard the text accumulated for `message_id` and use `replacement` as that assistant message’s text. The original model output is never persisted or replayed. object **guardrail\_capability\_id** required Stable ID of the capability that contributed the guardrail (e.g. `"prompt_canary_guardrail"`). string **guardrail\_id** required Stable ID of the guardrail itself (e.g. `"prompt_canary"`). string **message\_id** required Stable public ID for the assistant message whose streamed text is replaced. This is the same identifier as the subsequent completed `RuntimeMessage.id`. string **reason\_code** required Stable machine-readable reason code (e.g. `"system_prompt_leak"`). Clients localize their copy from this rather than the human text. string **replacement** required Replacement text shown to the user and stored as the assistant message. string **turn\_id** required Turn ID this replacement belongs to. string * object Data for `conversation.message`: a message the agent sent to the conversation with `send_message`. For an agent that talks explicitly this is the whole of what people see; its assistant text is working notes. Every surface reads it through \[`crate::runtime::conversation`], never directly. object **delivery** One of: * object Where an external platform accepted it, when the conversation lives on one (a Slack thread). Absent when the conversation is the session itself (web chat, API, A2A, AG-UI, MCP). object **channel** required Platform channel or conversation identifier. string **message\_ref** required Platform message identifier, usable by platform-specific editing tools. string **platform** required Destination platform, such as `slack`. string * null null **message\_id** required Identifier of this sent message, for later references (edits, replies). string **text** required The message as the agent wrote it. Markdown. string **tool\_call\_id** required The `send_message` call that sent it. string * object Where an external platform accepted it, when the conversation lives on one (a Slack thread). Absent when the conversation is the session itself (web chat, API, A2A, AG-UI, MCP). object **channel** required Platform channel or conversation identifier. string **message\_ref** required Platform message identifier, usable by platform-specific editing tools. string **platform** required Destination platform, such as `slack`. string * object null * object Data for output.message.completed event object **error\_code** Stable error code for user-facing failures surfaced as assistant text. string | null **error\_disclosure** Error-disclosure mode applied to `error_code`/`error_fields` (“generic” | “standard” | “detailed”). Tracking metadata; absent for non-error messages and for paths that predate disclosure modes. string | null **error\_fields** Structured interpolation fields for localized error rendering. object | null **message** required The agent message object **content** required Message content as array of content parts (text, images, tool calls, tool results) Array One of: * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque **controls** One of: * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * null Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * string null * null null **created\_at** required Timestamp when the message was created string format: date-time **external\_actor** One of: * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * null null **id** required Unique message ID (format: message\_{32-hex}) string **metadata** Message-level metadata object | null **phase** One of: * string Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * null null **phase\_source** One of: * string Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * null null **role** required Message role string Allowed values: system user agent tool\_result **metadata** One of: * object Metadata about the model used object **model** required Model name (e.g., “gpt-5.6-sol”, “claude-sonnet-5”) string **model\_id** Model ID (internal identifier) string | null format: uuid **provider\_id** Provider ID (internal identifier) string | null format: uuid * null null **usage** One of: * object Token usage object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * object Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * object null * object null * null null * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * null null * object Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * object null * object Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * null null * object Metadata about the model used object **model** required Model name (e.g., “gpt-5.6-sol”, “claude-sonnet-5”) string **model\_id** Model ID (internal identifier) string | null format: uuid **provider\_id** Provider ID (internal identifier) string | null format: uuid * object null * object Token usage object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * object null * null Data for turn.started event object **agent\_description** Agent description snapshot at turn start. string | null **agent\_id** Agent the turn runs as, when the session is bound to one. Carried on the turn root so trace exporters can label the `invoke_agent` span without a store lookup (the Gen-AI conventions want the agent name in the span name and `gen_ai.agent.*` attributes). string | null **agent\_name** Human-readable agent name snapshot at turn start. string | null **input\_content** Input message content (for observability) string | null **input\_message\_id** required Input message ID that triggered this turn string **turn\_id** required Turn identifier string * object Data for turn.completed event object **duration\_ms** Duration in milliseconds integer | null format: int64 **final\_answer\_preview** Bounded preview of the final visible assistant answer. string | null **final\_message\_id** Canonical assistant message emitted by `output.message.completed`. string | null **input\_content** Input message content (for observability, passed through from turn.started) string | null **iterations** required Number of iterations in this turn integer format: int32 **llm\_call\_count** Number of LLM generation calls executed during the turn. integer | null format: int32 **status** Optional explicit completion status for consumers that summarize turns. string | null **stop\_reason** Normalized finish reason of the turn’s final LLM generation (`stop`, `length`, `content_filter`, `refusal`, …). A turn that “completed” on `length` ended because the model ran out of output budget, not because it was done. `None` when the provider reported no reason. string | null **time\_to\_first\_token\_ms** First-token latency for the turn, usually from the first LLM generation. integer | null format: int64 **tool\_call\_count** Number of tool calls completed during the turn. integer | null format: int32 **turn\_id** required Turn identifier string **usage** One of: * object Aggregated token usage for all LLM calls in this turn object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * null Aggregated token usage for all LLM calls in this turn object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * string null * null Data for turn.failed event object **error** required Error message string **error\_code** Error code string | null **error\_disclosure** Error-disclosure mode applied to `error_code`/`error_fields` (“generic” | “standard” | “detailed”). Full diagnostic detail remains available to operators via reason.completed failure events and tracing. string | null **error\_fields** Structured interpolation fields for localized error rendering. object | null **turn\_id** required Turn identifier string * object Data for reason.started event object **agent\_id** One of: * string Agent ID being used (optional) string /^agent\_\[0-9a-f]{32}$/ * null null **harness\_id** required Harness ID being used string /^harness\_\[0-9a-f]{32}$/ **metadata** One of: * object Metadata about the model being used object **model** required Model name (e.g., “gpt-5.6-sol”, “claude-sonnet-5”) string **model\_id** Model ID (internal identifier) string | null format: uuid **provider\_id** Provider ID (internal identifier) string | null format: uuid * null null * null Agent ID being used (optional) string /^agent\_\[0-9a-f]{32}$/ * string null * null Metadata about the model being used object **model** required Model name (e.g., “gpt-5.6-sol”, “claude-sonnet-5”) string **model\_id** Model ID (internal identifier) string | null format: uuid **provider\_id** Provider ID (internal identifier) string | null format: uuid * string null * null Data for reason.completed event object **duration\_ms** Duration of the reason phase in milliseconds integer | null format: int64 **error** Error message if failed string | null **has\_tool\_calls** required Whether tool calls were requested boolean **success** required Whether the LLM call succeeded boolean **text\_preview** Text response preview (first 200 chars) string | null **tool\_call\_count** required Number of tool calls requested integer format: int32 **usage** One of: * object Token usage from the LLM call object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * string Token usage from the LLM call object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * string Data for the `reason.recovered` event (EVE-532). Emitted by `ReasonAtom` when it detects an in-flight partial assistant message from a previous worker execution and applies the ContinuePartial recovery policy. object **accumulated\_len** required Character length of the persisted accumulated text. integer **mode** required Recovery action taken. string Allowed values: finalize restart **turn\_id** required Turn ID the partial belonged to. string * null Data for capability.usage events. object **records** required Array\ Single capability usage record. This intentionally carries only stable IDs and small snapshots; prompts, messages, tool arguments, and results are not allowed in reporting facts. object **capability\_id** required Capability id (prefixed or namespaced) attributing this usage. string **capability\_name** Capability display name for UI. `None` when the capability is unnamed. string | null **duration\_ms** Total wall-clock duration of the usage in milliseconds (duration-style records). `None` for count-style records. integer | null format: int64 **tool\_name** Concrete tool name when `usage_kind` is `tool_call`. `None` for non-tool usage kinds. string | null **usage\_count** Number of distinct usages recorded in this record (count-style records). `None` for duration-style records. integer | null format: int64 **usage\_kind** required Discriminator for the kind of usage being recorded (e.g. `tool_call`, `subagent_spawn`). string Allowed values: configured resolved exposed invoked effect\_ran * object Data for act.started event object **headline** Human-readable headline for the batch string | null **tool\_calls** required Tool calls to be executed Array\ Summary of a tool call (compact form without arguments) object **completed\_narration** Human-readable narration after the call completes string | null **display\_name** Human-readable display name for UI rendering string | null **id** required string **name** required string **narration** Human-readable narration for timeline rendering string | null * null Data for act.completed event object **completed** required Whether all tool calls completed boolean **duration\_ms** Duration of the act phase in milliseconds integer | null format: int64 **error\_count** required Number of failed tool calls integer format: int32 **headline** Human-readable headline for the completed batch string | null **success\_count** required Number of successful tool calls integer format: int32 * string Data for tool.started event object **display\_name** Human-readable display name for UI rendering string | null **narration** Human-readable narration for timeline rendering string | null **tool\_call** required The tool call being executed object **arguments** required Arguments as JSON object **id** required Unique ID for this tool call string **name** required Tool name to execute string **tool\_call\_fingerprint** Stable fingerprint of tool name + normalized arguments. string | null * null Data for tool.completed event object **acted\_as** One of: * string Account an MCP tool call ran as: `user` (the invoking person’s own grant) or `service` (the agent’s). Set only for MCP calls that resolved a credential, so a `user_or_service` attachment’s fallback is visible. string Allowed values: none service user user\_or\_service * null null **capability\_id** Capability that contributed the tool definition, when known. string | null **capability\_name** Human-readable capability name snapshot, when known. string | null **details** Details for people reading the run (chat details view, Session Trace) that the model never saw. Web search puts the provider that answered, every attempt and the raw provider responses here. **display\_name** Human-readable display name for UI rendering string | null **duration\_ms** Duration of the tool call in milliseconds integer | null format: int64 **error** Error message if failed string | null **executed\_arguments** Arguments the tool actually ran with, present only when `pre_tool_use` hooks rewrote the model-authored arguments (which `tool.started` carries). Values under credential-named keys (`password`, `*_token`, `authorization`, …) read `[REDACTED]`. Bounded like the approval preview: past the budget this is a truncated JSON string and `executed_arguments_truncated` is set. **executed\_arguments\_truncated** True when `executed_arguments` is a truncated preview. boolean **narration** Human-readable narration for timeline rendering string | null **result** Result content (for successful calls) Array | null One of: * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque **status** required Status: “success”, “error”, “timeout”, “cancelled” string **success** required Whether the tool call succeeded boolean **tool\_call\_fingerprint** Stable fingerprint of tool name + normalized arguments. string | null **tool\_call\_id** required Tool call ID string **tool\_name** required Tool name string **tool\_result\_fingerprint** Stable fingerprint of tool name + normalized result/error. string | null * string Account an MCP tool call ran as: `user` (the invoking person’s own grant) or `service` (the agent’s). Set only for MCP calls that resolved a credential, so a `user_or_service` attachment’s fallback is visible. string Allowed values: none service user user\_or\_service * null null * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * null Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * null One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque * object Data for tool.progress event. Emitted by tools during execution to report interim status updates. This allows long-running tools (e.g., browser operations, sandbox setup) to stream progress feedback between tool.started and tool.completed. object **display\_name** Human-readable display name for UI rendering string | null **message** required Human-readable status message (e.g., “Connecting to browser…”) string **tool\_call\_id** required Tool call ID this progress belongs to string **tool\_name** required Tool name string * object Data for tool.output.delta event. Emitted by tools during execution to stream incremental output chunks. This enables live output rendering (e.g., bash stdout/stderr, command output) between tool.started and tool.completed. Generic — usable by any tool that produces streamed output (bashkit, Daytona exec, subagent speech, etc.). The consumer accumulates deltas by tool\_call\_id for display. The final tool.completed result is authoritative — deltas are informational only. object **delta** required Incremental output chunk string **stream** required Output stream identifier (e.g., “stdout”, “stderr”) string **tool\_call\_id** required Tool call ID this output belongs to string **tool\_name** required Tool name string * object Data for tool.call\_requested event Emitted when the agent needs client-side tool calls executed. The workflow pauses until the client submits results via the API. object **completed\_headline** Human-readable headline after the requested batch completes string | null **headline** Human-readable headline for the requested batch string | null **tool\_calls** required Tool calls that need to be executed by the client Array\ Tool call from LLM response object **arguments** required Arguments as JSON object **id** required Unique ID for this tool call string **name** required Tool name to execute string **tool\_summaries** Optional summaries with display names and narration for UI rendering Array\ Summary of a tool call (compact form without arguments) object **completed\_narration** Human-readable narration after the call completes string | null **display\_name** Human-readable display name for UI rendering string | null **id** required string **name** required string **narration** Human-readable narration for timeline rendering string | null * null Data for transcript.repaired event (EVE-533). Emitted once per dangling tool call when transcript repair runs before a `reason` call. A dangling call is an assistant `tool_call` with no matching `ToolResult` in the message history. Repair makes the transcript well-formed so the next LLM call succeeds. object **action** required Action taken: `replay` (settled result reused) or `synthesize` (interrupted placeholder added). string Allowed values: replay synthesize **tool\_call\_id** required The tool call ID that was repaired. string **tool\_name** The tool name, if known. string | null * object Data for the `tool.call_repaired` event (EVE-600). Emitted once per malformed tool call handled by the opt-in `tool_call_repair` capability. `outcome` is the stable label (`local-salvage` | `re-prompt` | `gave-up`). object **outcome** required Stable outcome label: `local-salvage`, `re-prompt`, or `gave-up`. string **tool\_call\_id** required The tool call ID that was inspected/repaired. string **tool\_name** required The tool name the malformed call targeted. string **turn\_id** required Turn this repair belongs to. string * null A provider-executed (hosted) tool call changed state. object **call\_id** required Provider item id; stable across the call’s state changes. string **status** required `in_progress`, `completed`, or `failed`. string **summary** Short detail once known, e.g. the search query. string | null **tool\_name** required Hosted tool name, e.g. `web_search`. string **turn\_id** required Turn this call belongs to. string * string A tool a shell script called through `tools` finished. object **call\_id** required This call’s id: unique within the parent call. string **command** required How the script spelled it, e.g. `github list-pulls`. string **duration\_ms** Wall-clock time the tool ran, in milliseconds; absent when it did not run. integer | null format: int64 **error** What went wrong, for `failed` and `refused`. string | null **input\_preview** required The call’s input, shortened for display. string **parent\_tool\_call\_id** required The `bash` tool call the script ran in. string **status** required `completed`, `failed`, `needs_approval` (the script stopped here and a person is asked), or `refused` (a pre-tool hook blocked the call). string **tool\_name** required Registry name of the tool that was called, e.g. `mcp_github__list_pulls`. string * null Data for llm.generation event Emitted after each LLM API call to provide full visibility into the messages sent to the model and the response received. object **messages** required Messages sent to the LLM (including system prompt) Array\ A message in the conversation object **content** required Message content as array of content parts (text, images, tool calls, tool results) Array One of: * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque **controls** One of: * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * null Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * string null * null null **created\_at** required Timestamp when the message was created string format: date-time **external\_actor** One of: * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * null null **id** required Unique message ID (format: message\_{32-hex}) string **metadata** Message-level metadata object | null **phase** One of: * string Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * null null **phase\_source** One of: * string Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * null null **role** required Message role string Allowed values: system user agent tool\_result **metadata** required Metadata about the generation object **compaction** One of: * object Compaction information if context was compressed before generation Occurs when the conversation context exceeded the model’s limit object **compacted** required Whether compaction was performed boolean **cost\_usd** Provider-reported cost of the compaction call itself, in USD. Compaction is a separate billable model call, so its cost is also folded into the generation’s `usage.actual_cost_usd` — that is what budgets and `llm_generations` read. This field keeps the split visible, so an operator can see how much of a turn’s spend was compaction (EVE-895). number | null format: double **duration\_ms** Duration of the compaction operation in milliseconds integer | null format: int64 **input\_tokens\_after** Number of input tokens after compaction integer | null format: int32 **input\_tokens\_before** Number of input tokens before compaction integer | null format: int32 * null null **cost\_components** Billable components of this generation and what each cost, when the generation bills more than its tokens (provider-run tools, hosted containers, a managed harness). A component whose `cost_usd` is `None` is an explicit unknown amount, never a zero: budgets debit the priced components and record the unknown ones (EVE-1125). Empty for an ordinary token-billed generation. Array\ One billable component of a generation. object **cost\_usd** USD amount. `None` is an explicit unknown amount, not zero. number | null format: double **kind** required What is billed: `model_tokens`, `hosted_tool`, or `container`. string **name** required Which one, e.g. the model or the provider item type (`web_search_call`). string **quantity** Billed units (tokens, calls), when known. integer | null format: int64 **duration\_ms** Duration of the generation in milliseconds integer | null format: int64 **error** Error message if generation failed string | null **finish\_reasons** Finish reasons from the LLM (e.g., \[“stop”], \[“tool\_calls”]) Required for gen-ai semantic conventions Array\ | null **model** required Model identifier used for generation string **provider** Provider type (openai, anthropic, etc.) string | null **provider\_finish\_reason** The provider’s own finish/stop reason, verbatim (`max_tokens`, `MAX_TOKENS`, `max_output_tokens`, …). `finish_reasons` carries the normalized value; this keeps the provider vocabulary it came from. string | null **provider\_id** The provider account that served the call: the id of the org’s provider row (`provider_...`) when the host resolves models from stored providers. Usage tracking reads it to record which provider row was billed and whether that row is host-managed, which is what tells managed spend apart from the org’s own keys (BYOK). string | null **request\_options** One of: * object Request-side driver options that were enabled for this generation. object **max\_tokens** Maximum output tokens requested, when set. integer | null format: int32 **metadata** General request metadata passed to the LLM provider for tracking and observability. Includes embedder-supplied labels merged with system tracking keys (session\_id, turn\_id, etc.). object ***key*** additional properties string **prompt\_cache** One of: * object Prompt caching configuration for this request. object **enabled** required Whether prompt caching was enabled on the request. boolean **provider\_mode** Provider-specific prompt-cache mode used by the driver. string | null **retention** Cache retention the driver requested after snapping to what the provider supports (`5m`, `30m`, `1h`). Absent when the provider’s retention is not configurable. string | null **strategy** required Strategy used to enable prompt caching. string Allowed values: auto explicit * null null **provider\_options** Provider-specific request options that do not warrant dedicated fields. object ***key*** additional properties **reasoning\_effort** Reasoning / thinking effort level requested, as the string sent to the provider (`low`, `medium`, `high`, …), when set. string | null **stream** Whether the request used the provider’s streaming mode. boolean | null **temperature** Sampling temperature sent with the request, when set. number | null format: float **tool\_search** One of: * object Deferred tool-loading configuration for this request. object **enabled** required Whether tool\_search was enabled on the request. boolean **threshold** required Minimum number of tools before deferred loading activates. integer * null null * null Prompt caching configuration for this request. object **enabled** required Whether prompt caching was enabled on the request. boolean **provider\_mode** Provider-specific prompt-cache mode used by the driver. string | null **retention** Cache retention the driver requested after snapping to what the provider supports (`5m`, `30m`, `1h`). Absent when the provider’s retention is not configurable. string | null **strategy** required Strategy used to enable prompt caching. string Allowed values: auto explicit * object null * null Deferred tool-loading configuration for this request. object **enabled** required Whether tool\_search was enabled on the request. boolean **threshold** required Minimum number of tools before deferred loading activates. integer * object null * null null **response\_id** Unique response identifier from the LLM provider Required for gen-ai semantic conventions string | null **response\_model** Model the provider reported actually serving the request. `model` is what was *asked for*, which is routinely an alias that resolves at request time — `claude-sonnet-4-6` served by `claude-sonnet-4-6-20260217`, or an OpenRouter route landing on one upstream of several. Collapsing the two loses the only record of which weights produced the answer, which is what a regression in output quality has to be correlated against. `None` when the provider reported no model, which is the honest answer: consumers fall back to `model` rather than being told the alias was confirmed. string | null **retry** One of: * object Retry information if rate limit retries occurred Contains number of retries and total wait time object **attempts** required Number of retry attempts made (0 = succeeded on first try) integer format: int32 **total\_wait\_ms** required Total time spent waiting between retries in milliseconds integer format: int64 * null null **success** required Whether the generation was successful boolean **time\_to\_first\_token\_ms** Time to first token in milliseconds (streaming latency) integer | null format: int64 **tool\_calls\_dropped** Tool calls the model started that the driver discarded because the response was cut off or rejected. Omitted when zero. integer format: int32 **tool\_calls\_truncated\_executed** Tool calls handed on for execution from a response that was cut off. Their own arguments are complete: a call whose arguments were cut off or do not parse is dropped (`tool_calls_dropped`), never run with `{}`. Omitted when zero. integer format: int32 **truncation\_gate** What the output-truncation gate did because this generation lost tool calls (`finish_reason` `length`, or arguments that did not parse): `retried` (the model was told and the turn ran another generation) or `failed` (the turn ended with an error). Omitted when the gate did not act. string | null **usage** One of: * object Token usage statistics object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null **output** required Output from the LLM object **text** Text response from the model string | null **tool\_calls** Tool calls requested by the model Array\ Tool call from LLM response object **arguments** required Arguments as JSON object **id** required Unique ID for this tool call string **name** required Tool name to execute string **request\_body** The request body exactly as the driver serialized it for the provider, when the driver captures it (see \[`crate::driver_registry::LlmCallConfig::capture_request`]). `messages` above is the runtime’s view of the prompt; this is the provider’s: its roles, its content blocks, its tool schemas and cache markers. Absent for drivers that do not capture. THREAT\[TM-LLM-039]: the body repeats the prompt `messages` already carries, so it widens nothing beyond this event’s existing audience. Credentials travel in headers and are never part of it. object | null **tools** Tools available to the LLM for this generation Array\ Summary of a tool definition (compact form for events) object **capability\_id** Capability that contributed the tool definition, when known. string | null **capability\_name** Human-readable capability name snapshot, when known. string | null **category** Tool category for namespace grouping. string | null **description** required Tool description string **display\_name** Human-readable display name for UI rendering string | null **name** required Tool name string * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * null Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * string null * null Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * string Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * null File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * null One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * string Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * null One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null null * string Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque * null Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * object null * object null * object null * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * object null * object Execution phase for this message. Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider. string Allowed values: commentary final\_answer * object null * null Whether \[`Self::phase`] was reported by the provider or inferred from tool-call presence. A derived phase carries no information beyond “this message called tools”, so consumers that need a real classification must be able to tell the two apart. string Allowed values: provider derived communication * object null * null Compaction information if context was compressed before generation Occurs when the conversation context exceeded the model’s limit object **compacted** required Whether compaction was performed boolean **cost\_usd** Provider-reported cost of the compaction call itself, in USD. Compaction is a separate billable model call, so its cost is also folded into the generation’s `usage.actual_cost_usd` — that is what budgets and `llm_generations` read. This field keeps the split visible, so an operator can see how much of a turn’s spend was compaction (EVE-895). number | null format: double **duration\_ms** Duration of the compaction operation in milliseconds integer | null format: int64 **input\_tokens\_after** Number of input tokens after compaction integer | null format: int32 **input\_tokens\_before** Number of input tokens before compaction integer | null format: int32 * object null * object Request-side driver options that were enabled for this generation. object **max\_tokens** Maximum output tokens requested, when set. integer | null format: int32 **metadata** General request metadata passed to the LLM provider for tracking and observability. Includes embedder-supplied labels merged with system tracking keys (session\_id, turn\_id, etc.). object ***key*** additional properties string **prompt\_cache** One of: * object Prompt caching configuration for this request. object **enabled** required Whether prompt caching was enabled on the request. boolean **provider\_mode** Provider-specific prompt-cache mode used by the driver. string | null **retention** Cache retention the driver requested after snapping to what the provider supports (`5m`, `30m`, `1h`). Absent when the provider’s retention is not configurable. string | null **strategy** required Strategy used to enable prompt caching. string Allowed values: auto explicit * null null **provider\_options** Provider-specific request options that do not warrant dedicated fields. object ***key*** additional properties **reasoning\_effort** Reasoning / thinking effort level requested, as the string sent to the provider (`low`, `medium`, `high`, …), when set. string | null **stream** Whether the request used the provider’s streaming mode. boolean | null **temperature** Sampling temperature sent with the request, when set. number | null format: float **tool\_search** One of: * object Deferred tool-loading configuration for this request. object **enabled** required Whether tool\_search was enabled on the request. boolean **threshold** required Minimum number of tools before deferred loading activates. integer * null null * object Prompt caching configuration for this request. object **enabled** required Whether prompt caching was enabled on the request. boolean **provider\_mode** Provider-specific prompt-cache mode used by the driver. string | null **retention** Cache retention the driver requested after snapping to what the provider supports (`5m`, `30m`, `1h`). Absent when the provider’s retention is not configurable. string | null **strategy** required Strategy used to enable prompt caching. string Allowed values: auto explicit * null null * object Deferred tool-loading configuration for this request. object **enabled** required Whether tool\_search was enabled on the request. boolean **threshold** required Minimum number of tools before deferred loading activates. integer * object null * object null * object Retry information if rate limit retries occurred Contains number of retries and total wait time object **attempts** required Number of retry attempts made (0 = succeeded on first try) integer format: int32 **total\_wait\_ms** required Total time spent waiting between retries in milliseconds integer format: int64 * object null * object Token usage statistics object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * object null * object Data for reason.thinking.delta event (extended thinking content from models like Claude) This event streams incremental thinking/reasoning content from models that support extended thinking mode (e.g., Claude with thinking enabled). The thinking content represents the model’s chain-of-thought reasoning before producing the final response. object **accumulated** required Accumulated thinking text so far (convenience for UI) string **delta** required The thinking delta (new thinking text since last delta) string **turn\_id** required Turn ID this delta belongs to (for correlation) string * object Data for `reason.item` event. Durable record of one provider reasoning artifact. Carries identity and curated summary text only. Opaque replay state (signatures, encrypted reasoning context) is deliberately absent: it is state the driver hands back to the provider, not content, and it must not reach an event stream or any API surface. Plaintext chain-of-thought is likewise never persisted here. object **item\_id** required Provider-assigned identifier for the reasoning item. string **model** Model identifier reported by the provider, if known. string | null **provider** required Provider that produced the reasoning item (e.g., “openai”). string **summary** Safe summary text segments curated by the provider. Never includes plaintext reasoning content. Array\ **token\_count** Per-item reasoning token count, when the provider reports one. integer | null format: int32 **turn\_id** required Turn ID this reasoning item belongs to. string * object Data for reason.thinking.started event Emitted when extended thinking begins during reasoning phase. This signals the model is using chain-of-thought reasoning. UI can show a “thinking” indicator. object **model** Optional model name being used string | null **turn\_id** required Turn ID this thinking belongs to string * object Data for reason.thinking.completed event Emitted when extended thinking completes and the model transitions to producing the final response. Contains the complete thinking content. object **thinking** required Complete thinking content string **turn\_id** required Turn ID this thinking belongs to string * object Data for turn.sealed event (EVE-534). A sealed turn was deliberately stopped to prevent waste. It is observably distinct from `turn.completed` (success) and `turn.failed` (error). The `reason` is the durable engine’s stable seal-reason wire value. (`"no_progress"` or `"budget"`). object **detail** Human-readable detail for operators (optional). string | null **iterations** Iterations completed before the turn was sealed (if known). integer | null format: int32 **reason** required Why the turn was sealed: `"no_progress"` (crash-loop with no forward progress) or `"budget"` (work budget exhausted). string **turn\_id** required Turn identifier string **usage** One of: * object Aggregated token usage before sealing, if available. object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * null Aggregated token usage before sealing, if available. object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * object null * null Data for turn.cancelled event object **reason** Reason for cancellation string | null **turn\_id** required Turn identifier string **usage** One of: * object Token usage before cancellation (if available) object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * object Token usage before cancellation (if available) object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * object null * object Data for session.started event object **agent\_id** Agent ID (optional) string | null **harness\_id** required Harness ID string **model\_id** Model ID if specified string | null * null Data for session.activated event (turn started, session now active) object **input\_message\_id** required Input message ID that triggered the turn string **turn\_id** required Turn ID that activated the session string * object Data for session.idled event (turn completed, session now idle) object **iterations** Number of iterations in the completed turn integer | null format: int32 **turn\_id** required Turn ID that just completed string **usage** One of: * object Cumulative token usage for the session at this point object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * null null * object Cumulative token usage for the session at this point object **actual\_cost\_usd** Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s `usage.cost`, which reflects real post-routing/BYOK/cache pricing). `None` for providers that do not return a cost. number | null format: double **cache\_creation\_tokens** Number of tokens written to cache, disjoint from `input_tokens` integer | null format: int32 **cache\_read\_tokens** Number of tokens read from cache (reduces cost), disjoint from `input_tokens` integer | null format: int32 **effective\_cost\_usd** Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895). number | null format: double **estimated\_cost\_usd** Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of `actual_cost_usd`, so estimate-vs-actual drift can be reconciled. `None` when there is no profile cost data for the model. number | null format: double **input\_tokens** required Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct) integer format: int32 **output\_tokens** required Number of output/completion tokens integer format: int32 * object null * object Data for `session.title.updated`. object **previous\_title** Title before the mutation. `None` means the session was untitled. string | null **title** required New session title. string * null Data for `session.model.changed`. Names are the provider’s own model identifiers, captured at emission time so the transcript stays readable after a model is renamed or removed from the organization. Clients that still have the model may prefer its display name. object **model\_id** required Model selected for the next turn. string **model\_name** required Name of the selected model, captured at emission time. string **previous\_model\_id** Model used before the switch. `None` when the previous turn ran on an inherited default that the emitter could not name. string | null **previous\_model\_name** Name of the previous model, captured at emission time. string | null * object Data for `timer.set`. object **cron\_expression** Cron expression for a recurring timer; absent for a one-shot timer. string | null **description** Text delivered to the session when the timer fires. string | null **fire\_at** required First time the timer is due. string format: date-time **metadata** Host-defined fields kept with the timer (for example a schedule’s name). object **purpose** required What the timer wakes the session for. string Allowed values: schedule **timer\_id** required Timer identity. For a schedule, the schedule id. string **timezone** IANA timezone the cron expression is read in. string | null * null Data for `timer.fired`. object **fired\_at** required When the occurrence was delivered. string format: date-time **next\_fire\_at** Next time the timer is due; absent when this was its last occurrence. string | null format: date-time **timer\_id** required Timer that fired. string * string Data for `timer.cancelled`. object **timer\_id** required Timer that will not fire again. string * null Non-secret lifecycle details for a managed Sandbox incarnation. object **current\_instance\_id** Replacement physical resource. Present only on the recovery event. string | null **generation** Current incarnation fence, when hosted persistence is available. integer | null format: int64 **previous\_instance\_id** required Physical provider resource that was lost or replaced. string **process\_state\_lost** required Provider process state is ephemeral and is not restored across replacement. boolean **provider** required Compute provider selected by the Sandbox Template specification. string **sandbox\_id** Durable logical Sandbox identifier, when hosted persistence is available. string | null * object Non-secret lifecycle details for a managed Sandbox incarnation. object **current\_instance\_id** Replacement physical resource. Present only on the recovery event. string | null **generation** Current incarnation fence, when hosted persistence is available. integer | null format: int64 **previous\_instance\_id** required Physical provider resource that was lost or replaced. string **process\_state\_lost** required Provider process state is ephemeral and is not restored across replacement. boolean **provider** required Compute provider selected by the Sandbox Template specification. string **sandbox\_id** Durable logical Sandbox identifier, when hosted persistence is available. string | null * null Non-secret lifecycle details for a managed Sandbox incarnation. object **current\_instance\_id** Replacement physical resource. Present only on the recovery event. string | null **generation** Current incarnation fence, when hosted persistence is available. integer | null format: int64 **previous\_instance\_id** required Physical provider resource that was lost or replaced. string **process\_state\_lost** required Provider process state is ephemeral and is not restored across replacement. boolean **provider** required Compute provider selected by the Sandbox Template specification. string **sandbox\_id** Durable logical Sandbox identifier, when hosted persistence is available. string | null * string Non-secret lifecycle details for a managed Sandbox incarnation. object **current\_instance\_id** Replacement physical resource. Present only on the recovery event. string | null **generation** Current incarnation fence, when hosted persistence is available. integer | null format: int64 **previous\_instance\_id** required Physical provider resource that was lost or replaced. string **process\_state\_lost** required Provider process state is ephemeral and is not restored across replacement. boolean **provider** required Compute provider selected by the Sandbox Template specification. string **sandbox\_id** Durable logical Sandbox identifier, when hosted persistence is available. string | null * null Data for task lifecycle events (`task.created`, `task.updated`). Carries the full task snapshot so consumers never need a follow-up read; UIs reconcile by `task.id` (snapshot-then-delta). object **task** required A unit of background work owned by a session. object **artifacts** Array\ Typed link to something the task produced. object **name** required string **path** Session VFS path, when the artifact lives in the session filesystem. string | null **type** required Artifact type: “file”, “url”, “session”, “pr”, etc. string **url** External URL, when the artifact lives elsewhere. string | null **attempt** Execution attempt, starting at 1. Incremented on re-attach. integer format: int32 **cancel\_requested\_at** Cooperative cancel intent. A flag, not a state. string | null format: date-time **created\_at** required string format: date-time **display\_name** required Human-readable label. string **error** One of: * object Terminal error detail. Timeout/rejection/orphaned are kinds, not states. object **kind** required string **message** required string * null null **finished\_at** string | null format: date-time **heartbeat\_at** string | null format: date-time **id** required `task_*` public ID. string **input\_request** One of: * object Pending ask while `awaiting_input`; cleared when answered. object **expected** Optional machine-readable description of the expected answer. object **id** required Stable ID referenced by the answering message’s `in_reply_to`. string **prompt** required Human/agent-readable prompt. string * null null **kind** required Task kind: “subagent”, “external\_agent”, “background\_tool”, “monitor”, … string **links** Cross-references owned by a task. object **child\_session\_id** Child session, for subagent-shaped tasks. Full transcript lives there. string | null **remote\_task\_id** Remote task ID, for tasks wrapping an external protocol task (A2A). string | null **resource\_ids** Session resources (sandboxes, browser sessions) this task holds. Array\ **progress** One of: * object Structured progress reported by background tools. object **current** integer | null format: int64 **label** string | null **steps** Ordered checklist, for work that plans its steps up front (a thread’s assignment). Empty for plain counters. Array\ One checklist line in \[`BackgroundProgress::steps`]. object **status** required State of one checklist line. string Allowed values: pending in\_progress done skipped **title** required string **total** integer | null format: int64 **unit** string | null * null null **result\_path** Machine result in the session VFS: `/.tasks/{task_id}/result.json`. string | null **root\_session\_id** Root of the owning session’s delegation tree (EVE-680). Populated on API reads from the denormalized storage column so cross-session tooling (e.g. the Work view) can group a whole tree’s tasks by one id. `None` for a top-level session that is its own root, or when unavailable. Storage-derived, never client-settable on create. string | null **session\_id** required Owning session. string **spec** Kind-specific input (instructions, tool args, external agent id). object **started\_at** string | null format: date-time **state** required Lifecycle state of a session task. Three classes: active (`queued`, `running`), interrupted (`awaiting_input`, resumable), terminal (`succeeded`, `failed`, `canceled`). Timeout and rejection are `error.kind` values on `failed`, not states. string Allowed values: queued running awaiting\_input succeeded failed canceled **state\_detail** Short live status line (“polling remote task”, “iteration 4/10”). string | null **summary** Human-readable outcome. string | null **updated\_at** required string format: date-time **wake\_policy** When outbound task activity wakes the owning session’s agent. string Allowed values: silent on\_terminal on\_activity **worker\_id** string | null * string Terminal error detail. Timeout/rejection/orphaned are kinds, not states. object **kind** required string **message** required string * null null * object Pending ask while `awaiting_input`; cleared when answered. object **expected** Optional machine-readable description of the expected answer. object **id** required Stable ID referenced by the answering message’s `in_reply_to`. string **prompt** required Human/agent-readable prompt. string * null null * object Structured progress reported by background tools. object **current** integer | null format: int64 **label** string | null **steps** Ordered checklist, for work that plans its steps up front (a thread’s assignment). Empty for plain counters. Array\ One checklist line in \[`BackgroundProgress::steps`]. object **status** required State of one checklist line. string Allowed values: pending in\_progress done skipped **title** required string **total** integer | null format: int64 **unit** string | null * null null * object Data for task lifecycle events (`task.created`, `task.updated`). Carries the full task snapshot so consumers never need a follow-up read; UIs reconcile by `task.id` (snapshot-then-delta). object **task** required A unit of background work owned by a session. object **artifacts** Array\ Typed link to something the task produced. object **name** required string **path** Session VFS path, when the artifact lives in the session filesystem. string | null **type** required Artifact type: “file”, “url”, “session”, “pr”, etc. string **url** External URL, when the artifact lives elsewhere. string | null **attempt** Execution attempt, starting at 1. Incremented on re-attach. integer format: int32 **cancel\_requested\_at** Cooperative cancel intent. A flag, not a state. string | null format: date-time **created\_at** required string format: date-time **display\_name** required Human-readable label. string **error** One of: * object Terminal error detail. Timeout/rejection/orphaned are kinds, not states. object **kind** required string **message** required string * null null **finished\_at** string | null format: date-time **heartbeat\_at** string | null format: date-time **id** required `task_*` public ID. string **input\_request** One of: * object Pending ask while `awaiting_input`; cleared when answered. object **expected** Optional machine-readable description of the expected answer. object **id** required Stable ID referenced by the answering message’s `in_reply_to`. string **prompt** required Human/agent-readable prompt. string * null null **kind** required Task kind: “subagent”, “external\_agent”, “background\_tool”, “monitor”, … string **links** Cross-references owned by a task. object **child\_session\_id** Child session, for subagent-shaped tasks. Full transcript lives there. string | null **remote\_task\_id** Remote task ID, for tasks wrapping an external protocol task (A2A). string | null **resource\_ids** Session resources (sandboxes, browser sessions) this task holds. Array\ **progress** One of: * object Structured progress reported by background tools. object **current** integer | null format: int64 **label** string | null **steps** Ordered checklist, for work that plans its steps up front (a thread’s assignment). Empty for plain counters. Array\ One checklist line in \[`BackgroundProgress::steps`]. object **status** required State of one checklist line. string Allowed values: pending in\_progress done skipped **title** required string **total** integer | null format: int64 **unit** string | null * null null **result\_path** Machine result in the session VFS: `/.tasks/{task_id}/result.json`. string | null **root\_session\_id** Root of the owning session’s delegation tree (EVE-680). Populated on API reads from the denormalized storage column so cross-session tooling (e.g. the Work view) can group a whole tree’s tasks by one id. `None` for a top-level session that is its own root, or when unavailable. Storage-derived, never client-settable on create. string | null **session\_id** required Owning session. string **spec** Kind-specific input (instructions, tool args, external agent id). object **started\_at** string | null format: date-time **state** required Lifecycle state of a session task. Three classes: active (`queued`, `running`), interrupted (`awaiting_input`, resumable), terminal (`succeeded`, `failed`, `canceled`). Timeout and rejection are `error.kind` values on `failed`, not states. string Allowed values: queued running awaiting\_input succeeded failed canceled **state\_detail** Short live status line (“polling remote task”, “iteration 4/10”). string | null **summary** Human-readable outcome. string | null **updated\_at** required string format: date-time **wake\_policy** When outbound task activity wakes the owning session’s agent. string Allowed values: silent on\_terminal on\_activity **worker\_id** string | null * null Terminal error detail. Timeout/rejection/orphaned are kinds, not states. object **kind** required string **message** required string * object null * null Pending ask while `awaiting_input`; cleared when answered. object **expected** Optional machine-readable description of the expected answer. object **id** required Stable ID referenced by the answering message’s `in_reply_to`. string **prompt** required Human/agent-readable prompt. string * object null * null Structured progress reported by background tools. object **current** integer | null format: int64 **label** string | null **steps** Ordered checklist, for work that plans its steps up front (a thread’s assignment). Empty for plain counters. Array\ One checklist line in \[`BackgroundProgress::steps`]. object **status** required State of one checklist line. string Allowed values: pending in\_progress done skipped **title** required string **total** integer | null format: int64 **unit** string | null * object null * null Data for task message events (`task.message.sent`, `task.message.received`). object **message** required A message exchanged between a session and one of its tasks. object **content** required Array One of: * object object **text** required string **type** required string Allowed values: text * object object **data** required object **type** required string Allowed values: data **created\_at** required string format: date-time **direction** required Direction of a task message. Inbound = session → task. string Allowed values: inbound outbound **id** required `tmsg_*` public ID. string **in\_reply\_to** Set when this message answers a `TaskInputRequest`. string | null **task\_id** required string **task\_id** required string * object object **text** required string **type** required string Allowed values: text * null object **data** required object **type** required string Allowed values: data * object Data for task message events (`task.message.sent`, `task.message.received`). object **message** required A message exchanged between a session and one of its tasks. object **content** required Array One of: * object object **text** required string **type** required string Allowed values: text * object object **data** required object **type** required string Allowed values: data **created\_at** required string format: date-time **direction** required Direction of a task message. Inbound = session → task. string Allowed values: inbound outbound **id** required `tmsg_*` public ID. string **in\_reply\_to** Set when this message answers a `TaskInputRequest`. string | null **task\_id** required string **task\_id** required string * null object **text** required string **type** required string Allowed values: text * object object **data** required object **type** required string Allowed values: data * null Data for context.compacting event (compaction starting). object **budget\_remaining\_tokens** Tokens of headroom remaining when the attempt started, when measurable. integer | null format: int64 **bytes\_before** Serialized request-context bytes before compaction, when measurable. integer | null format: int64 **cache\_creation\_tokens** Cache-creation tokens written before compaction, when reported. integer | null format: int32 **cache\_read\_tokens** Cached input tokens read before compaction, when reported. integer | null format: int32 **driver** Local driver identifier, when known. string | null **messages\_before** required Number of messages before compaction. integer **model** Model performing the compaction. string **provider** Provider backend (e.g. “openai”), when known. string | null **reason** required Why compaction was triggered. string Allowed values: proactive\_budget request\_too\_large manual **source\_sequence** Source message sequence the attempt ran at, when known. integer | null format: int64 **strategy** required Strategy requested (may differ from strategy\_used in the completed event). string **tokens\_before** Estimated or provider-reported input tokens before compaction. integer | null format: int64 **trigger** What triggered this attempt: context-window budget or cost pressure. string Allowed values: context\_budget cost\_pressure * object Data for context.compacted event (compaction completed). object **budget\_remaining\_tokens** Tokens of headroom remaining when the install completed, when measurable. integer | null format: int64 **bytes\_after** Serialized compact output bytes, when measurable. integer | null format: int64 **bytes\_before** Serialized request-context bytes before compaction, when measurable. integer | null format: int64 **cache\_creation\_tokens** Cache-creation tokens written after compaction, when reported. integer | null format: int32 **cache\_read\_tokens** Cached input tokens read after compaction, when reported. integer | null format: int32 **checkpoint\_bytes** Serialized provider checkpoint size in bytes, when measured. integer | null format: int64 **checkpoint\_id** Durable checkpoint installed by this compaction, when applicable. string | null **driver** Local driver identifier, when known. string | null **duration\_ms** required Total duration of all compaction steps in milliseconds. integer format: int64 **messages\_after** required Number of messages after compaction. integer **messages\_before** required Number of messages before compaction. integer **model** Model that performed the compaction. string **provider** Provider backend (e.g. “openai”), when known. string | null **replay\_source** Source used to reconstruct the provider prefix (`checkpoint` or `raw`). string | null **source\_sequence** Source message sequence the compaction ran at, when known. integer | null format: int64 **steps** Individual steps in the cascade. Array\ A single step in a compaction cascade. object **duration\_ms** required Duration of this step in milliseconds. integer format: int64 **messages\_after** required Number of messages after this step. integer **strategy** required Strategy used in this step. string **strategy\_used** required Combined strategy description (e.g., “observation\_masking+native”). string **tokens\_after** Provider-reported output tokens after compaction, when available. integer | null format: int64 **tokens\_before** Estimated or provider-reported input tokens before compaction. integer | null format: int64 **trigger** What triggered this compaction: context-window budget or cost pressure. string Allowed values: context\_budget cost\_pressure * null Evaluation ran but installed nothing (context.compaction.skipped). object **budget\_remaining\_tokens** Tokens of headroom remaining, when measurable. integer | null format: int64 **driver** Local driver identifier, when known. string | null **messages\_observed** required Number of messages observed. integer **model** required Model the evaluation ran under. string **provider** Provider backend (e.g. “openai”), when known. string | null **reason** required Why compaction was evaluated. string Allowed values: proactive\_budget request\_too\_large manual **skip\_reason** required Why nothing was installed. string Allowed values: strategy\_excludes\_native driver\_unsupported checkpoint\_store\_unavailable cooldown\_active native\_returned\_none no\_material\_reduction guard\_rejected **source\_sequence** Source message sequence the evaluation ran at, when known. integer | null format: int64 **strategy** required Strategy requested. string **tokens\_observed** required Estimated input tokens observed at evaluation time. integer format: int64 **trigger** required Whether window/budget or cost pressure triggered the evaluation. string Allowed values: context\_budget cost\_pressure * object Attempt errored before installing (context.compaction.failed). object **budget\_remaining\_tokens** Tokens of headroom remaining, when measurable. integer | null format: int64 **checkpoint\_id** Durable checkpoint being installed when the failure hit, if any. string | null **driver** Local driver identifier, when known. string | null **error** required Human-readable failure. string **messages\_before** required Number of messages before the attempt. integer **model** required Model the attempt ran under. string **provider** Provider backend (e.g. “openai”), when known. string | null **reason** required Why compaction was attempted. string Allowed values: proactive\_budget request\_too\_large manual **source\_sequence** Source message sequence the attempt ran at, when known. integer | null format: int64 **stage** required Which stage failed. string Allowed values: native\_compaction checkpoint\_install summarization **strategy** required Strategy requested. string **tokens\_before** required Estimated or provider-reported input tokens before the attempt. integer format: int64 **trigger** required Whether window/budget or cost pressure triggered the attempt. string Allowed values: context\_budget cost\_pressure * null Data for file.written events emitted when files are written to the session filesystem. object **created** required Whether this is a new file (true) or an update to an existing file (false). boolean **operation** required Operation type (see `FILE_OP_*` constants). string **path** required File path within the session filesystem (normalized, e.g. “/reports/summary.md”). string **size\_bytes** required File size in bytes after write. integer format: int64 * object Data for budget lifecycle events (warning, paused, exhausted, resumed). object **balance** required Current remaining balance. number format: double **budget\_id** required Budget that triggered this event. string **currency** required Budget currency (e.g. “usd”, “tokens”). string **limit** required Budget limit. number format: double **message** Human-readable message. string | null **soft\_limit** Soft limit threshold (present for warning/paused events). number | null format: double * null Data for budget lifecycle events (warning, paused, exhausted, resumed). object **balance** required Current remaining balance. number format: double **budget\_id** required Budget that triggered this event. string **currency** required Budget currency (e.g. “usd”, “tokens”). string **limit** required Budget limit. number format: double **message** Human-readable message. string | null **soft\_limit** Soft limit threshold (present for warning/paused events). number | null format: double * object Data for budget lifecycle events (warning, paused, exhausted, resumed). object **balance** required Current remaining balance. number format: double **budget\_id** required Budget that triggered this event. string **currency** required Budget currency (e.g. “usd”, “tokens”). string **limit** required Budget limit. number format: double **message** Human-readable message. string | null **soft\_limit** Soft limit threshold (present for warning/paused events). number | null format: double * null Data for budget lifecycle events (warning, paused, exhausted, resumed). object **balance** required Current remaining balance. number format: double **budget\_id** required Budget that triggered this event. string **currency** required Budget currency (e.g. “usd”, “tokens”). string **limit** required Budget limit. number format: double **message** Human-readable message. string | null **soft\_limit** Soft limit threshold (present for warning/paused events). number | null format: double * object Data for voice.session.started. object **model** required Provider-side realtime model identifier negotiated for this session. string **reasoning\_effort** required Reasoning effort applied to the realtime model. One of `low`, `medium`, `high`. string **transport** required Transport carrying the audio stream. One of `webrtc`, `sip`, `websocket`. string **voice** required Realtime voice preset selected for this session. string **voice\_connection\_id** required Prefixed voice connection identifier for the started session. string * null Data for voice transcript delta/completed events. object **accumulated** required Full transcript accumulated for this item up to and including `delta`. string **delta** Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion. string **item\_id** Provider-specific identifier of the conversation item being transcribed. `None` when not yet assigned. string | null **phase** Transcript phase: `user_partial`, `user_final`, `assistant_partial`, `assistant_final`. `None` when not yet classified. string | null **response\_id** Provider-specific identifier of the response stream emitting this transcript. `None` for user-side transcripts. string | null **voice\_connection\_id** required Prefixed voice connection identifier this transcript belongs to. string * object Data for voice transcript delta/completed events. object **accumulated** required Full transcript accumulated for this item up to and including `delta`. string **delta** Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion. string **item\_id** Provider-specific identifier of the conversation item being transcribed. `None` when not yet assigned. string | null **phase** Transcript phase: `user_partial`, `user_final`, `assistant_partial`, `assistant_final`. `None` when not yet classified. string | null **response\_id** Provider-specific identifier of the response stream emitting this transcript. `None` for user-side transcripts. string | null **voice\_connection\_id** required Prefixed voice connection identifier this transcript belongs to. string * null Data for voice transcript delta/completed events. object **accumulated** required Full transcript accumulated for this item up to and including `delta`. string **delta** Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion. string **item\_id** Provider-specific identifier of the conversation item being transcribed. `None` when not yet assigned. string | null **phase** Transcript phase: `user_partial`, `user_final`, `assistant_partial`, `assistant_final`. `None` when not yet classified. string | null **response\_id** Provider-specific identifier of the response stream emitting this transcript. `None` for user-side transcripts. string | null **voice\_connection\_id** required Prefixed voice connection identifier this transcript belongs to. string * object Data for voice transcript delta/completed events. object **accumulated** required Full transcript accumulated for this item up to and including `delta`. string **delta** Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion. string **item\_id** Provider-specific identifier of the conversation item being transcribed. `None` when not yet assigned. string | null **phase** Transcript phase: `user_partial`, `user_final`, `assistant_partial`, `assistant_final`. `None` when not yet classified. string | null **response\_id** Provider-specific identifier of the response stream emitting this transcript. `None` for user-side transcripts. string | null **voice\_connection\_id** required Prefixed voice connection identifier this transcript belongs to. string * object Data for voice.session.ended. object **duration\_ms** Total wall-clock duration of the connection in milliseconds. `None` when the connection never completed an audio handshake. integer | null format: int64 **reason** Free-text end reason captured from the client or server. `None` when no reason was supplied. string | null **voice\_connection\_id** required Prefixed voice connection identifier for the ended session. string * object Data for voice.session.failed. object **error** required Error message captured at failure. Provider-formatted; not stable for parsing. string **voice\_connection\_id** required Prefixed voice connection identifier for the failed session. string * object Data for voice.output.interrupted: the caller talked over a spoken answer. object **heard** required What the caller heard of the answer before speech stopped, from the provider’s output transcript. string **policy** required What the interruption did to the running turn: `steer` (the caller’s next words steer it) or `cancel`. string **unspoken** required Answer text that was dropped and never spoken. string **voice\_connection\_id** required Prefixed voice connection identifier. string **id** required Unique event identifier (format: event\_{32-hex}) string **metadata** Arbitrary metadata for the event **sequence** Sequence number within session (for ordering) integer | null format: int32 **session\_id** required Session this event belongs to (format: session\_{32-hex}) string **tags** Tags for filtering and categorization Array\ | null **ts** required Event timestamp string format: date-time **type** required Event type in dot notation string ##### Example ```json { "data": [ { "context": { "exec_id": "exec_01933b5a00007000800000000000001", "input_message_id": "message_01933b5a00007000800000000000001", "turn_id": "turn_01933b5a00007000800000000000001" }, "data": { "message": { "content": [], "id": "...", "role": "user" } }, "id": "event_01933b5a00007000800000000000001", "session_id": "session_01933b5a00007000800000000000001" } ] } ``` #### Headers **X-Total-Count** integer format: int64 Total non-delta event count for the session (only present when limit is used) ### 400 Invalid session ID or invalid event type filter ### 404 Session not found ### 500 Internal server error