Append one entry (idempotent on entry_id); fires session::message-added.
customany of
Append a bookkeeping `kind: "custom"` entry instead of a message (e.g. the harness's compaction record). Custom entries do not count toward `message_count` and are only returned by `session::messages` when `include_custom` is set.
any of (2)
variant 1
custom_typestring*required
App-defined discriminator (e.g. `"compaction"`).
dataunknown
Opaque app data.
entry_idstring
Caller-supplied id for idempotent appends: appending an id that already exists is a no-op — the existing entry is returned and no event fires.
messageany of
The message to append (a `kind: "message"` entry). Exactly one of `message` / `custom` must be supplied.
any of (2)
variant 1
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque correlation (e.g. `{ "turn_id": ... }`), echoed on events.
parent_idstring
Override the parent (default: active leaf). Appending always moves the active leaf to the new entry.
session_idstring*required
timestampinteger· int64*required
session::append-many
functionAppend several message entries in order; fires session::message-added per entry.
messagesone of[]*required
Messages appended in order, each chained to the previous one. Not idempotent — use `session::append` with `entry_id` where redelivery is possible.
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque correlation echoed on every emitted event.
parent_idstring
Parent of the first appended entry (default: active leaf).
session_idstring*required
entry_idsstring[]*required
last_entry_idstring*required
session::config-status
functionReport the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads (count since boot). A rejected outcome or non-zero count means a stored config was refused and the active storage adapter diverged from the central store. Takes no arguments.
last_errorstring
Build error from the most recent rejected reload (why it was refused).
last_outcomeone of*required
Outcome of the most recent hot-reload attempt, exposed via `session::config-status`.
one of (2)
variant 1
valuestringenum: applied
variant 2
valuestringenum: rejected
rejected_reloadsinteger· uint64*requiredmin 0
Cumulative count of rejected reloads since boot (never reset).
Create a session at status idle; fires session::created.
descriptionstring
Session description. Default "".
metadataobject
App-defined metadata persisted onto `SessionMeta` — the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
titlestring
Session title; may be refined later with `session::set-meta`. Default "".
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session_idstring*required
Delete a session and its entries; fires session::deleted.
session_idstring*required
deletedboolean*required
False when the session did not exist (no event fires).
Idempotently ensure a session with a given id exists; fires session::created only when it creates.
descriptionstring
Description applied only when the session is created.
metadataobject
Metadata applied only when the session is created.
session_idstring*required
Caller-chosen session id to ensure.
titlestring
Title applied only when the session is created.
createdboolean*required
True when this call created the session (and fired `session::created`).
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session_idstring*required
Copy history up to an entry into a new session (copy-on-fork); fires session::created.
entry_idstring*required
Fork point: the root -> entry path is copied (copy-on-fork, fresh entry ids) and becomes the new session's active path.
session_idstring*required
Source session.
titlestring
Title for the new session (default: the source's title).
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session_idstring*required
The new session's id (`forked_from` is set on its meta).
Read one session's metadata (null when unknown).
session_idstring*required
any of (2)
variant 1
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session::get-message
functionRead a single entry by id (null when unknown).
session_idstring*required
any of (2)
variant 1
entryone of*required
The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.
one of (2)
variant 1
kindstring*requiredenum: message
messageone of*required
The canonical transcript message union, discriminated by `role`.
… expand 4 nestedcollapse
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
variant 2
custom_typestring*required
kindstring*requiredenum: custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
List sessions with pagination, ordering, and status/metadata filters.
cursorstring
Opaque pagination cursor from a previous response.
limitinteger· uintmin 0
Page size. Default 50, clamped to the configured maximum.
metadataobject
Equality filter against `SessionMeta.metadata` (tenancy): every given key must equal the stored value.
orderany of
Sort order. Default `updated_desc`.
any of (2)
variant 1
valuestringenum: created_asc, created_desc, updated_desc
statusany of
Only sessions with this status.
any of (2)
variant 1
valuestringenum: idle, working, done, error
next_cursorstring
Present when more pages remain.
sessionsobject[]*required
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session::messages
functionLoad the active path as messages with entry ids, oldest first; pagination and role filtering.
cursorstring
Opaque pagination cursor from a previous response.
from_entry_idstring
Treat this entry as the leaf: return its parent chain, root -> entry, oldest first (branch view).
include_customboolean
Interleave `kind: "custom"` entries at their path position. Default false.
limitinteger· uintmin 0
Page size. Default 50, clamped to the configured maximum.
rolesstring[]enum: user, assistant, function_result, custom
Only messages with these roles. Setting this also excludes `kind: "custom"` entries (it is an explicit narrowing to roles).
session_idstring*required
messagesobject[]*required
customany of
any of (2)
variant 1
custom_typestring*required
App-defined discriminator (e.g. `"compaction"`).
dataunknown
Opaque app data.
messageany of
any of (2)
variant 1
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
next_cursorstring
Present when more pages remain.
Internal: hot-reload session-manager from the authoritative configuration when it changes — rebuilds the storage adapter and event plumbing on an adapter change (replaying current state to subscribers) and swaps the list limits otherwise.
idstring
Configuration id that changed (advisory; the handler re-fetches the value).
session::set-active-leaf
functionMove the active path to end at a given entry (branch switch).
entry_idstring*required
The entry the active path should end at. Subsequent `session::append` without `parent_id` chains from here.
session_idstring*required
active_leafstring*required
session::set-meta
functionUpdate a session's title/description/metadata; fires session::meta-updated.
descriptionstring
New description (omit to keep the current one).
metadataobject
New metadata object — **replaces** the stored one wholesale.
session_idstring*required
titlestring
New title (omit to keep the current one).
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
session::set-status
functionSet status idle/working/done/error; fires session::status-changed (no-op when unchanged).
reasonstring
Short cause stored as `status_reason` — kept on `error`, cleared on any other status.
session_idstring*required
statusall of*required
Target status: `idle` / `working` / `done` / `error`.
all of (1)
variant 1
valuestringenum: idle, working, done, error
previous_statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
Internal store protocol: clear a session's active leaf pointer.
session_idstring*required
Internal store protocol: delete every entry of a session.
session_idstring*required
Internal store protocol: delete one SessionMeta.
session_idstring*required
Internal store protocol: read a session's active leaf pointer.
session_idstring*required
entry_idstring
`null` when the session has no active leaf.
Internal store protocol: read one SessionEntry (null when unknown).
session_idstring*required
any of (2)
variant 1
one of (2)
variant 1
kindstring*requiredenum: message
messageone of*required
The canonical transcript message union, discriminated by `role`.
… expand 4 nestedcollapse
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
variant 2
custom_typestring*required
kindstring*requiredenum: custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
session::store::get-meta
functionInternal store protocol: read one SessionMeta (null when unknown).
session_idstring*required
any of (2)
variant 1
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
Internal store protocol: list every entry of a session.
session_idstring*required
entriesone of[]*required
one of (2)
variant 1
kindstring*requiredenum: message
messageone of*required
The canonical transcript message union, discriminated by `role`.
… expand 4 nestedcollapse
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
variant 2
custom_typestring*required
kindstring*requiredenum: custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
Internal store protocol: list every SessionMeta.
metasobject[]*required
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
Internal store protocol: ingest a bridged instance's event envelopes and fan them out to local subscribers and every attached bridge.
eventsobject[]*required
Event envelopes produced by a bridged instance's mutation.
payloadunknown*required
The spec payload for that trigger type.
session_metadataobject
`SessionMeta.metadata` as of the mutation.
trigger_typestring*required
One of the six public trigger type ids.
publishedinteger· uint*requiredmin 0
Number of well-formed envelopes accepted and fanned out.
Internal store protocol: write one SessionEntry.
entryone of*required
The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.
one of (2)
variant 1
kindstring*requiredenum: message
messageone of*required
The canonical transcript message union, discriminated by `role`.
… expand 4 nestedcollapse
one of (4)
variant 1
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64*required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstring*required
Echoes the `function_call` block id this result answers.
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
Milliseconds since epoch.
variant 4
contentone of[]*required
… expand 5 nestedcollapse
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
App-defined discriminator.
rolestring*requiredenum: custom
timestampinteger· int64*required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
variant 2
custom_typestring*required
kindstring*requiredenum: custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64*required
Milliseconds since epoch (entry creation time).
session_idstring*required
session::store::put-meta
functionInternal store protocol: write one SessionMeta.
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
forked_fromstring
Source session id when created by `session::fork`.
message_countinteger· uint64*requiredmin 0
Number of `kind: "message"` entries (custom entries are bookkeeping and not counted).
metadataobject
App-defined; the tenancy hook (e.g. `{ "owner": "u_1" }`) that `session::list` and every trigger config can filter on.
session_idstring*required
statusstring*requiredenum: idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short cause, set on `error`, cleared on any other status.
updated_atinteger· int64*required
Milliseconds since epoch.
Internal store protocol: move a session's active leaf pointer.
session_idstring*required
session::update-message
functionReplace a message entry's content (optimistic concurrency via expected_revision); fires session::message-updated.
contentone of[]*required
New content for the message (full replacement).
one of (5)
variant 1
typestring*requiredenum: text
variant 2
datastring*required
Base64-encoded image bytes.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstring*required
The iii function id to invoke.
idstring*required
Unique per call, echoed by the result.
typestring*requiredenum: function_call
variant 5
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
detailsunknown
New `details` — only for `function_result` / `custom` messages.
expected_revisioninteger· uint64min 0
Optimistic concurrency: when supplied and it does not match the entry's current revision, nothing is written and `{ updated: false, revision }` returns the current revision.
originobject
Opaque correlation echoed on the event.
session_idstring*required
revisioninteger· uint64*requiredmin 0
The entry's revision after this call (unchanged on a mismatch).
