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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 "".
kindany of
Session kind. Default `user`.
any of (2)
variant 1
valuestringenum: user, automation, e2e
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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).
Delete one stored attachment no transcript entry references (e.g. a chip removed from the composer); also drops it from the draft. Event-silent.
attachment_idstring*required
session_idstring*required
deletedboolean*required
`false` when the attachment was already absent (a silent no-op).
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.
kindany of
Kind applied only when the session is created. Defaults to `user`.
any of (2)
variant 1
valuestringenum: user, automation, e2e
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
… expand 7 nestedcollapse
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
updated_atinteger· int64*required
Milliseconds since epoch.
session::get-attachment
functionRead one stored attachment's metadata and bytes (null when unknown).
attachment_idstring*required
include_databoolean
Include the bytes (`data`, standard base64). Default true; pass false for a metadata-only read.
session_idstring*required
any of (2)
variant 1
attachmentobject*required
Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
datastring
Standard base64 of the bytes; `null` when `include_data` was false.
session::get-message
functionRead a single entry by id (null when unknown).
include_image_databoolean
Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: ""` (same rule as `session::messages`).
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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.
kindsstring[]enum: user, automation, e2e
Only sessions whose kind is one of these. Omit for every kind; an empty list matches nothing.
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
updated_atinteger· int64*required
Milliseconds since epoch.
List the metadata of every attachment stored for a session.
session_idstring*required
attachmentsobject[]*required
Oldest first (`created_at`, then `attachment_id`).
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
session::mention::get
functionResolve a @session(id=…) chat mention to its pill, preview card and agent summary; null for an unknown id. Declares the session mention provider.
idstring*required
The id from the token.
any of (2)
variant 1
dataunknown
The domain object, for a worker's own preview renderer.
fieldsobject[]
Labelled values for the preview card (status, assignee, …).
tonestring
`neutral`, `info`, `success`, `warning` or `danger`.
idstring*required
The canonical id (may differ from the one asked for, e.g. a key resolved to a uuid).
openany of
What clicking the mention opens.
any of (2)
variant 1
any of (3)
variant 1
pagestring*required
Console page id (as registered with `host.pages`).
variant 2
sessionstring*required
Session id to select.
summarystring
One line for an agent: what the item is and its state. Defaults to the label, hint, description and fields.
updated_atstring
RFC 3339 time of the item's last change.
session::mention::search
functionSearch sessions for the chat @session mention menu, by title words or session id; best match first.
contextany of
Where the search was asked from, for providers that rank by it.
limitinteger· uintmin 0
Maximum rows (default 8, at most 50).
querystring
What the user typed after `@<name>:`. Empty asks for the most relevant recent items.
itemsobject[]*required
colorstring
Overrides the provider's color for this row.
descriptionstring
One line after the label ("in progress · high").
hintstring
A short human handle shown before the label ("KAN-12").
iconstring
Overrides the provider's icon for this row.
idstring*required
The id written into the token; stable for the item's lifetime.
labelstring*required
The item's name ("Fix login redirect").
session::messages
functionLoad the active path as messages with entry ids, oldest first; pagination and role filtering.
after_entry_idstring
Return only entries strictly after this entry id on the requested path (incremental fetch from a known watermark). Errors `session/invalid_cursor` when the entry is not on the path — e.g. after a fork moved the active leaf — so callers fall back to a full load. Ignored when `cursor` is set.
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.
include_image_databoolean
Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: ""`; the reader fetches the bytes on demand with `session::get-attachment`. Images without a stored original are returned inline regardless. Lets a UI open a long, picture-heavy transcript without pulling every image first; model-bound readers keep the default.
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
The entry's writer-supplied origin (turn correlation plus hook annotations, e.g. which memory bank and facts fed the generate). Absent on custom entries and on entries written without one.
next_cursorstring
Present when more pages remain.
session::messages-range
functionFull entries for a span (from/to) or list (entry_ids) of the active path — how a reader fetches the calls a collapsed run left out.
cursorstring
Opaque pagination cursor from a previous response.
entry_idsstring[]
Specific entries, returned in path order (duplicates folded).
from_entry_idstring
With `to_entry_id`: every entry of the active path from this one to `to_entry_id`, both inclusive, oldest first. Exactly one selector (`from_entry_id`+`to_entry_id`, or `entry_ids`) is required.
include_image_databoolean
Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: ""` (as `session::messages`).
limitinteger· uintmin 0
Page size in entries. Default 50, clamped to the configured maximum; a long run comes back in several pages.
session_idstring*required
messagesobject[]*required
Oldest first; never `elided`.
customany of
any of (2)
variant 1
custom_typestring*required
App-defined discriminator (e.g. `"compaction"`).
dataunknown
Opaque app data.
elidedboolean
Present and true when this entry sits inside a collapsed activity run and the heavy parts of its message were left out: `function_call` blocks keep `id` + `function_id` but carry `arguments: {}` (an `agent_trigger` call keeps its string `function` + `description` label and drops `payload`), `function_result` messages keep `function_call_id` + `is_error` with `content: []` and `details: null`, thinking is dropped, text is kept. `session::messages-range` returns the whole entry.
messageany of
any of (2)
variant 1
one of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
The entry's writer-supplied origin, as on `session::messages`.
next_cursorstring
Present when more entries of the selection remain.
session::messages-tail
functionNewest page of the active path, walking backwards in block-aligned pages (a tool run never splits) with activity runs collapsed to placeholders; the reader a chat UI opens a session with.
before_entry_idstring
Exclusive upper bound: return the page ending just before the block that contains this entry (the oldest entry the caller already has). Omitted = the newest page. `session/invalid_cursor` when the entry is not on the active path (e.g. after a fork moved the leaf), so callers reload from the top.
include_customboolean
Interleave `kind: "custom"` entries at their path position. Default TRUE here (unlike `session::messages`): a transcript reader wants compaction markers and wake records in place.
include_image_databoolean
Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: ""` (as `session::messages`).
limitinteger· uintmin 0
Page size in *blocks* (an entry, or one whole activity run), not entries: a page is "N conversational steps", and a tool run of 300 calls counts once. Default 50, clamped to the configured maximum.
session_idstring*required
until_entry_idstring
Extend the page backwards until the block containing this entry is included, ignoring `limit` (deep links: "go to message"). No-op when the entry is already within the page or newer than it. `session/invalid_cursor` when not on the active path.
has_moreboolean*required
True when older blocks exist before this page.
messagesobject[]*required
Oldest first, like `session::messages`.
customany of
any of (2)
variant 1
custom_typestring*required
App-defined discriminator (e.g. `"compaction"`).
dataunknown
Opaque app data.
elidedboolean
Present and true when this entry sits inside a collapsed activity run and the heavy parts of its message were left out: `function_call` blocks keep `id` + `function_id` but carry `arguments: {}` (an `agent_trigger` call keeps its string `function` + `description` label and drops `payload`), `function_result` messages keep `function_call_id` + `is_error` with `content: []` and `details: null`, thinking is dropped, text is kept. `session::messages-range` returns the whole entry.
messageany of
any of (2)
variant 1
one of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
The entry's writer-supplied origin, as on `session::messages`.
oldest_entry_idstring
The first entry of this page: pass it as `before_entry_id` to fetch the page before. Absent on an empty page.
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::put-attachment
functionStore an attachment's original bytes (base64) for a session and return the `file` content block that references it; event-silent.
datastring*required
The bytes as standard (padded) base64. Decoded size must not exceed the configured `max_attachment_bytes`.
mimestring*required
MIME type; pass `application/octet-stream` when unknown.
namestring*required
Original filename (non-empty).
session_idstring*required
attachmentobject*required
Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
blockall of*required
Ready-made `type: "file"` content block referencing the attachment, to embed in the message's `content`.
all of (1)
variant 1
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
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-draft
functionPark (or clear) the session's unsent composer input — text and attachment ids; event-silent, read back on SessionMeta.draft / draft_attachments.
attachment_idsstring[]
Attachments parked with the draft, by id (uploaded beforehand with `session::put-attachment`; an unknown id is `session/invalid_request`). Omit to leave the parked attachments unchanged — a text-only save must not drop them — or send `[]` to clear them.
draftstring
The unsent input to park. Omit, or send empty/whitespace-only text, to clear the stored draft text.
session_idstring*required
attachmentsobject[]*required
The parked attachments as stored after this call, in request order.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
draftstring
The draft text as stored after this call (`null` when cleared).
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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/phase stored as `status_reason` — kept on `error` (failure cause), `working` (live phase detail), and `done` (for terminal detail such as `stopped`); cleared on `idle`.
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: atomically commit one session append.
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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).
parent_explicitboolean*required
session_idstring*required
committedboolean*required
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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).
metaobject*required
A session's metadata record.
created_atinteger· int64*required
Milliseconds since epoch.
descriptionstring*required
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
updated_atinteger· int64*required
Milliseconds since epoch.
Internal store protocol: clear a session's active leaf pointer.
session_idstring*required
Internal store protocol: delete one attachment (deleted: false when unknown).
attachment_idstring*required
session_idstring*required
Internal store protocol: delete every attachment of a session.
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 attachment (metadata + base64 bytes; null when unknown).
attachment_idstring*required
session_idstring*required
any of (2)
variant 1
metaobject*required
Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
updated_atinteger· int64*required
Milliseconds since epoch.
Internal store protocol: list every attachment's metadata of a session.
session_idstring*required
attachmentsobject[]*required
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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 attachment (metadata + base64 bytes).
datastring*required
Standard (padded) base64 of the bytes.
metaobject*required
Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
Milliseconds since epoch.
variant 2
agentstring
The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
draftstring
Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.
draft_attachmentsobject[]
Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.
attachment_idstring*required
Store-generated id (`a_<uuid>`), unique within the session.
created_atinteger· int64*required
Milliseconds since epoch.
mimestring*required
MIME type, as uploaded (`application/octet-stream` when unknown).
namestring*required
Original filename, as uploaded.
session_idstring*required
sha256string*required
Lowercase hex SHA-256 of the bytes.
sizeinteger· uint64*requiredmin 0
Decoded byte length.
forked_fromstring
Source session id when created by `session::fork`.
kindall of
Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`.
all of (1)
variant 1
valuestringenum: user, automation, e2e
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 lifecycle detail retained on `working`, `done`, and `error`.
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 (6)
variant 1
typestring*requiredenum: text
variant 2
attachment_idstring
The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.
datastring*required
Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.
mimestring*required
MIME type, e.g. `image/png`.
typestring*requiredenum: image
variant 3
attachment_idstring*required
Id returned by `session::put-attachment`.
mimestring*required
MIME type, e.g. `application/pdf`.
namestring*required
Original filename.
sizeinteger· uint64*requiredmin 0
Original byte length.
typestring*requiredenum: file
variant 4
typestring*requiredenum: thinking
variant 5
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 6
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
usageany of
Final token/cost accounting — only for `assistant` messages. Omit for streaming content updates that do not yet have terminal usage.
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
revisioninteger· uint64*requiredmin 0
The entry's revision after this call (unchanged on a mismatch).
