session-manager

Name: session-manager
Author: iii

v1.0.24

Durable, reactive, branching store of typed conversation entries with six emitted trigger types.

license: Apache-2.0Published 25d agochat conversation history session

Install

bash

iii trigger compose::add worker=session-manager@1.0.24

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions40

session::append

Function

Append one entry (idempotent on entry_id); fires session::message-added.

Request

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_typestringrequired
App-defined discriminator (e.g. `"compaction"`).
dataunknown
Opaque app data.
Variant 2
valuenull
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
Variant 2
valuenull
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_idstringrequired

Response

entry_idstringrequired
parent_idstring
timestampinteger· int64required

session::append-many

Function

Append several message entries in order; fires session::message-added per entry.

Request

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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
originobject
Opaque correlation echoed on every emitted event.
parent_idstring
Parent of the first appended entry (default: active leaf).
session_idstringrequired

Response

entry_idsstring[]required
last_entry_idstringrequired

session::config-status

Function

Report 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.

Request

Empty object

Response

last_errorstring
Build error from the most recent rejected reload (why it was refused).
last_outcomeone ofrequired
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· uint64requiredmin 0
Cumulative count of rejected reloads since boot (never reset).

session::create

Function

Create a session at status idle; fires session::created.

Request

descriptionstring
Session description. Default "".
kindany of
Session kind. Default `user`.
any of (2)
Variant 1
valuestringenum user, automation, e2e
Variant 2
valuenull
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 "".

Response

metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.
session_idstringrequired

session::delete

Function

Delete a session and its entries; fires session::deleted.

Request

session_idstringrequired

Response

deletedbooleanrequired
False when the session did not exist (no event fires).

session::delete-attachment

Function

Delete one stored attachment no transcript entry references (e.g. a chip removed from the composer); also drops it from the draft. Event-silent.

Request

attachment_idstringrequired
session_idstringrequired

Response

deletedbooleanrequired
`false` when the attachment was already absent (a silent no-op).

session::ensure

Function

Idempotently ensure a session with a given id exists; fires session::created only when it creates.

Request

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
Variant 2
valuenull
metadataobject
Metadata applied only when the session is created.
session_idstringrequired
Caller-chosen session id to ensure.
titlestring
Title applied only when the session is created.

Response

createdbooleanrequired
True when this call created the session (and fired `session::created`).
metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.
session_idstringrequired

session::fork

Function

Copy history up to an entry into a new session (copy-on-fork); fires session::created.

Request

entry_idstringrequired
Fork point: the root -> entry path is copied (copy-on-fork, fresh entry ids) and becomes the new session's active path.
session_idstringrequired
Source session.
titlestring
Title for the new session (default: the source's title).

Response

metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.
session_idstringrequired
The new session's id (`forked_from` is set on its meta).

session::get

Function

Read one session's metadata (null when unknown).

Request

session_idstringrequired

Response

any of (2)

Variant 1

metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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`.
  Show 7 nestedHide nested
  attachment_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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`.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  valuestringenum user, automation, e2e
- message_countinteger· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.

Variant 2

valuenull

session::get-attachment

Function

Read one stored attachment's metadata and bytes (null when unknown).

Request

attachment_idstringrequired
include_databoolean
Include the bytes (`data`, standard base64). Default true; pass false for a metadata-only read.
session_idstringrequired

Response

any of (2)

Variant 1

attachmentobjectrequired
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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.
datastring
Standard base64 of the bytes; `null` when `include_data` was false.

Variant 2

valuenull

session::get-message

Function

Read a single entry by id (null when unknown).

Request

entry_idstringrequired
include_image_databoolean
Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: ""` (same rule as `session::messages`).
session_idstringrequired

Response

any of (2)

Variant 1

entryone ofrequired
The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.
one of (2)
Variant 1
idstringrequired
kindstringrequiredenum message
messageone ofrequired
The canonical transcript message union, discriminated by `role`.
Show 4 nestedHide nested
one of (4)
Variant 1
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).
Variant 2
custom_typestringrequired
dataunknown
idstringrequired
kindstringrequiredenum custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).

Variant 2

valuenull

session::list

Function

List sessions with pagination, ordering, and status/metadata filters.

Request

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
Variant 2
valuenull
statusany of
Only sessions with this status.
any of (2)
Variant 1
valuestringenum idle, working, done, error
Variant 2
valuenull

Response

next_cursorstring
Present when more pages remain.
sessionsobject[]required
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.

session::list-attachments

Function

List the metadata of every attachment stored for a session.

Request

session_idstringrequired

Response

attachmentsobject[]required
Oldest first (`created_at`, then `attachment_id`).
- attachment_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.

session::messages

Function

Load the active path as messages with entry ids, oldest first; pagination and role filtering.

Request

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_idstringrequired

Response

messagesobject[]required
- customany of
  any of (2)
  Variant 1
  custom_typestringrequired
  App-defined discriminator (e.g. `"compaction"`).
  dataunknown
  Opaque app data.
  Variant 2
  valuenull
- entry_idstringrequired
- messageany of
  any of (2)
  Variant 1
  one of (4)
  Variant 1
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  rolestringrequiredenum user
  timestampinteger· int64required
  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
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  error_kindany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
  Variant 2
  valuenull
  error_messagestring
  modelstringrequired
  native_stop_reasonstring
  Provider's raw finish reason, passed through untouched.
  providerstringrequired
  rolestringrequiredenum assistant
  stop_reasonstringrequiredenum end, length, function_call, aborted, error
  Why an assistant message stopped generating.
  timestampinteger· int64required
  Milliseconds since epoch.
  usageany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  cache_readinteger· uint64min 0
  cache_writeinteger· uint64min 0
  cost_usdnumber· double
  inputinteger· uint64min 0
  outputinteger· uint64min 0
  reasoninginteger· uint64min 0
  Variant 2
  valuenull
  warningsstring[]
  Report-and-continue notices (e.g. dropped unsupported param).
  Variant 3
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  detailsunknown
  Opaque structured payload kept alongside the rendered content.
  function_call_idstringrequired
  Echoes the `function_call` block id this result answers.
  function_idstringrequired
  is_errorboolean
  rolestringrequiredenum function_result
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 4
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  custom_typestringrequired
  App-defined discriminator.
  detailsunknown
  displaystring
  rolestringrequiredenum custom
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 2
  valuenull
- 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

Function

Full 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.

Request

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_idstringrequired
to_entry_idstring

Response

messagesobject[]required
Oldest first; never `elided`.
- customany of
  any of (2)
  Variant 1
  custom_typestringrequired
  App-defined discriminator (e.g. `"compaction"`).
  dataunknown
  Opaque app data.
  Variant 2
  valuenull
- 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: {}`, `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.
- entry_idstringrequired
- messageany of
  any of (2)
  Variant 1
  one of (4)
  Variant 1
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  rolestringrequiredenum user
  timestampinteger· int64required
  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
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  error_kindany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
  Variant 2
  valuenull
  error_messagestring
  modelstringrequired
  native_stop_reasonstring
  Provider's raw finish reason, passed through untouched.
  providerstringrequired
  rolestringrequiredenum assistant
  stop_reasonstringrequiredenum end, length, function_call, aborted, error
  Why an assistant message stopped generating.
  timestampinteger· int64required
  Milliseconds since epoch.
  usageany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  cache_readinteger· uint64min 0
  cache_writeinteger· uint64min 0
  cost_usdnumber· double
  inputinteger· uint64min 0
  outputinteger· uint64min 0
  reasoninginteger· uint64min 0
  Variant 2
  valuenull
  warningsstring[]
  Report-and-continue notices (e.g. dropped unsupported param).
  Variant 3
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  detailsunknown
  Opaque structured payload kept alongside the rendered content.
  function_call_idstringrequired
  Echoes the `function_call` block id this result answers.
  function_idstringrequired
  is_errorboolean
  rolestringrequiredenum function_result
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 4
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  custom_typestringrequired
  App-defined discriminator.
  detailsunknown
  displaystring
  rolestringrequiredenum custom
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 2
  valuenull
- originobject
  The entry's writer-supplied origin, as on `session::messages`.
next_cursorstring
Present when more entries of the selection remain.

session::messages-tail

Function

Newest 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.

Request

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_idstringrequired
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.

Response

has_morebooleanrequired
True when older blocks exist before this page.
messagesobject[]required
Oldest first, like `session::messages`.
- customany of
  any of (2)
  Variant 1
  custom_typestringrequired
  App-defined discriminator (e.g. `"compaction"`).
  dataunknown
  Opaque app data.
  Variant 2
  valuenull
- 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: {}`, `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.
- entry_idstringrequired
- messageany of
  any of (2)
  Variant 1
  one of (4)
  Variant 1
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  rolestringrequiredenum user
  timestampinteger· int64required
  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
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  error_kindany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
  Variant 2
  valuenull
  error_messagestring
  modelstringrequired
  native_stop_reasonstring
  Provider's raw finish reason, passed through untouched.
  providerstringrequired
  rolestringrequiredenum assistant
  stop_reasonstringrequiredenum end, length, function_call, aborted, error
  Why an assistant message stopped generating.
  timestampinteger· int64required
  Milliseconds since epoch.
  usageany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  cache_readinteger· uint64min 0
  cache_writeinteger· uint64min 0
  cost_usdnumber· double
  inputinteger· uint64min 0
  outputinteger· uint64min 0
  reasoninginteger· uint64min 0
  Variant 2
  valuenull
  warningsstring[]
  Report-and-continue notices (e.g. dropped unsupported param).
  Variant 3
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  detailsunknown
  Opaque structured payload kept alongside the rendered content.
  function_call_idstringrequired
  Echoes the `function_call` block id this result answers.
  function_idstringrequired
  is_errorboolean
  rolestringrequiredenum function_result
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 4
  contentone of[]required
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  textstringrequired
  typestringrequiredenum 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.
  datastringrequired
  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.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  attachment_idstringrequired
  Id returned by `session::put-attachment`.
  mimestringrequired
  MIME type, e.g. `application/pdf`.
  namestringrequired
  Original filename.
  sizeinteger· uint64requiredmin 0
  Original byte length.
  typestringrequiredenum file
  Variant 4
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 5
  argumentsunknown
  Model-produced arguments (JSON).
  function_idstringrequired
  The iii function id to invoke.
  idstringrequired
  Unique per call, echoed by the result.
  typestringrequiredenum function_call
  Variant 6
  contentunknown[]required
  function_call_idstringrequired
  is_errorboolean
  typestringrequiredenum function_result
  custom_typestringrequired
  App-defined discriminator.
  detailsunknown
  displaystring
  rolestringrequiredenum custom
  timestampinteger· int64required
  Milliseconds since epoch.
  Variant 2
  valuenull
- 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.

session::on-config-change

Function

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.

Request

idstring
Configuration id that changed (advisory; the handler re-fetches the value).

Response

okbooleanrequired

session::put-attachment

Function

Store an attachment's original bytes (base64) for a session and return the `file` content block that references it; event-silent.

Request

datastringrequired
The bytes as standard (padded) base64. Decoded size must not exceed the configured `max_attachment_bytes`.
mimestringrequired
MIME type; pass `application/octet-stream` when unknown.
namestringrequired
Original filename (non-empty).
session_idstringrequired

Response

attachmentobjectrequired
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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.
blockall ofrequired
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
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result

session::set-active-leaf

Function

Move the active path to end at a given entry (branch switch).

Request

entry_idstringrequired
The entry the active path should end at. Subsequent `session::append` without `parent_id` chains from here.
session_idstringrequired

Response

active_leafstringrequired

session::set-draft

Function

Park (or clear) the session's unsent composer input — text and attachment ids; event-silent, read back on SessionMeta.draft / draft_attachments.

Request

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_idstringrequired

Response

attachmentsobject[]required
The parked attachments as stored after this call, in request order.
- attachment_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.
draftstring
The draft text as stored after this call (`null` when cleared).

session::set-meta

Function

Update a session's title/description/metadata; fires session::meta-updated.

Request

descriptionstring
New description (omit to keep the current one).
metadataobject
New metadata object — **replaces** the stored one wholesale.
session_idstringrequired
titlestring
New title (omit to keep the current one).

Response

metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.

session::set-status

Function

Set status idle/working/done/error; fires session::status-changed (no-op when unchanged).

Request

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_idstringrequired
statusall ofrequired
Target status: `idle` / `working` / `done` / `error`.
all of (1)
Variant 1
valuestringenum idle, working, done, error

Response

previous_statusstringrequiredenum idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
statusstringrequiredenum idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.

session::store::delete-active-leaf

Function

Internal store protocol: clear a session's active leaf pointer.

Request

session_idstringrequired

Response

okbooleanrequired

session::store::delete-attachment

Function

Internal store protocol: delete one attachment (deleted: false when unknown).

Request

attachment_idstringrequired
session_idstringrequired

Response

deletedbooleanrequired

session::store::delete-attachments

Function

Internal store protocol: delete every attachment of a session.

Request

session_idstringrequired

Response

okbooleanrequired

session::store::delete-entries

Function

Internal store protocol: delete every entry of a session.

Request

session_idstringrequired

Response

okbooleanrequired

session::store::delete-meta

Function

Internal store protocol: delete one SessionMeta.

Request

session_idstringrequired

Response

okbooleanrequired

session::store::get-active-leaf

Function

Internal store protocol: read a session's active leaf pointer.

Request

session_idstringrequired

Response

entry_idstring
`null` when the session has no active leaf.

session::store::get-attachment

Function

Internal store protocol: read one attachment (metadata + base64 bytes; null when unknown).

Request

attachment_idstringrequired
session_idstringrequired

Response

any of (2)

Variant 1

datastringrequired
metaobjectrequired
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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.

Variant 2

valuenull

session::store::get-entry

Function

Internal store protocol: read one SessionEntry (null when unknown).

Request

entry_idstringrequired
session_idstringrequired

Response

any of (2)

Variant 1

one of (2)

Variant 1

idstringrequired
kindstringrequiredenum message
messageone ofrequired
The canonical transcript message union, discriminated by `role`.
Show 4 nestedHide nested
one of (4)
Variant 1
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).

Variant 2

custom_typestringrequired
dataunknown
idstringrequired
kindstringrequiredenum custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).

Variant 2

valuenull

session::store::get-meta

Function

Internal store protocol: read one SessionMeta (null when unknown).

Request

session_idstringrequired

Response

any of (2)

Variant 1

created_atinteger· int64required
Milliseconds since epoch.
descriptionstringrequired
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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
statusstringrequiredenum idle, working, done, error
Coarse session lifecycle status, rendered directly by consumers.
status_reasonstring
Short lifecycle detail retained on `working`, `done`, and `error`.
titlestringrequired
updated_atinteger· int64required
Milliseconds since epoch.

Variant 2

valuenull

session::store::list-attachments

Function

Internal store protocol: list every attachment's metadata of a session.

Request

session_idstringrequired

Response

attachmentsobject[]required
- attachment_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.

session::store::list-entries

Function

Internal store protocol: list every entry of a session.

Request

session_idstringrequired

Response

entriesone of[]required
one of (2)
Variant 1
idstringrequired
kindstringrequiredenum message
messageone ofrequired
The canonical transcript message union, discriminated by `role`.
Show 4 nestedHide nested
one of (4)
Variant 1
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).
Variant 2
custom_typestringrequired
dataunknown
idstringrequired
kindstringrequiredenum custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).

session::store::list-metas

Function

Internal store protocol: list every SessionMeta.

Request

Empty object

Response

metasobject[]required
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.

session::store::publish-events

Function

Internal store protocol: ingest a bridged instance's event envelopes and fan them out to local subscribers and every attached bridge.

Request

eventsobject[]required
Event envelopes produced by a bridged instance's mutation.
- payloadunknownrequired
  The spec payload for that trigger type.
- session_metadataobject
  `SessionMeta.metadata` as of the mutation.
- trigger_typestringrequired
  One of the six public trigger type ids.

Response

publishedinteger· uintrequiredmin 0
Number of well-formed envelopes accepted and fanned out.

session::store::put-attachment

Function

Internal store protocol: write one attachment (metadata + base64 bytes).

Request

datastringrequired
Standard (padded) base64 of the bytes.
metaobjectrequired
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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
- created_atinteger· int64required
  Milliseconds since epoch.
- mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
- namestringrequired
  Original filename, as uploaded.
- session_idstringrequired
- sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
- sizeinteger· uint64requiredmin 0
  Decoded byte length.

Response

okbooleanrequired

session::store::put-entry

Function

Internal store protocol: write one SessionEntry.

Request

entryone ofrequired
The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.
one of (2)
Variant 1
idstringrequired
kindstringrequiredenum message
messageone ofrequired
The canonical transcript message union, discriminated by `role`.
Show 4 nestedHide nested
one of (4)
Variant 1
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
rolestringrequiredenum user
timestampinteger· int64required
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
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
error_kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
Variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum assistant
stop_reasonstringrequiredenum end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
Show 2 nestedHide nested
any of (2)
Variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
Variant 3
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum function_result
timestampinteger· int64required
Milliseconds since epoch.
Variant 4
contentone of[]required
Show 6 nestedHide nested
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum custom
timestampinteger· int64required
Milliseconds since epoch.
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).
Variant 2
custom_typestringrequired
dataunknown
idstringrequired
kindstringrequiredenum custom
originobject
Opaque writer-supplied correlation (e.g. `{ turn_id }`).
parent_idstring
revisioninteger· uint64min 0
Starts at 0; increments on every content update.
timestampinteger· int64required
Milliseconds since epoch (entry creation time).
session_idstringrequired

Response

okbooleanrequired

session::store::put-meta

Function

Internal store protocol: write one SessionMeta.

Request

metaobjectrequired
A session's metadata record.
- created_atinteger· int64required
  Milliseconds since epoch.
- descriptionstringrequired
- 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_idstringrequired
  Store-generated id (`a_<uuid>`), unique within the session.
  created_atinteger· int64required
  Milliseconds since epoch.
  mimestringrequired
  MIME type, as uploaded (`application/octet-stream` when unknown).
  namestringrequired
  Original filename, as uploaded.
  session_idstringrequired
  sha256stringrequired
  Lowercase hex SHA-256 of the bytes.
  sizeinteger· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
- statusstringrequiredenum idle, working, done, error
  Coarse session lifecycle status, rendered directly by consumers.
- status_reasonstring
  Short lifecycle detail retained on `working`, `done`, and `error`.
- titlestringrequired
- updated_atinteger· int64required
  Milliseconds since epoch.

Response

okbooleanrequired

session::store::set-active-leaf

Function

Internal store protocol: move a session's active leaf pointer.

Request

entry_idstringrequired
session_idstringrequired

Response

okbooleanrequired

session::update-message

Function

Replace a message entry's content (optimistic concurrency via expected_revision); fires session::message-updated.

Request

contentone of[]required
New content for the message (full replacement).
one of (6)
Variant 1
textstringrequired
typestringrequiredenum 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.
datastringrequired
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.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
attachment_idstringrequired
Id returned by `session::put-attachment`.
mimestringrequired
MIME type, e.g. `application/pdf`.
namestringrequired
Original filename.
sizeinteger· uint64requiredmin 0
Original byte length.
typestringrequiredenum file
Variant 4
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 5
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum function_call
Variant 6
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum function_result
detailsunknown
New `details` — only for `function_result` / `custom` messages.
entry_idstringrequired
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_idstringrequired
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
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
Variant 2
valuenull

Response

revisioninteger· uint64requiredmin 0
The entry's revision after this call (unchanged on a mismatch).
updatedbooleanrequired

Triggers7

session::created

Trigger

A new session exists (via session::create or session::fork).

Invocation

metadataobject
Equality match against `SessionMeta.metadata`: every key given here must equal the stored value (subset match).

Return

valueunknown

session::deleted

Trigger

A session and its entries were removed.

Invocation

metadataobject
Equality match against `SessionMeta.metadata` (subset match).
session_idstring
Only deliver events for this session.

Return

valueunknown

session::message-added

Trigger

A message entry was appended to a session.

Invocation

metadataobject
Equality match against `SessionMeta.metadata` (subset match).
rolesstring[]enum user, assistant, function_result, custom
Only deliver events whose message role is in this list. `kind: "custom"` entries carry no role and never match a `roles` filter.
session_idstring
Only deliver events for this session.

Return

valueunknown

session::message-updated

Trigger

A message entry's content changed (e.g. streaming deltas).

Invocation

metadataobject
Equality match against `SessionMeta.metadata` (subset match).
rolesstring[]enum user, assistant, function_result, custom
Only deliver events whose message role is in this list. `kind: "custom"` entries carry no role and never match a `roles` filter.
session_idstring
Only deliver events for this session.

Return

valueunknown

session::meta-updated

Trigger

A session's title/description/metadata changed.

Invocation

metadataobject
Equality match against `SessionMeta.metadata` (subset match).
session_idstring
Only deliver events for this session.

Return

valueunknown

session::status-changed

Trigger

A session's status changed (idle/working/done/error).

Invocation

metadataobject
Equality match against `SessionMeta.metadata` (subset match).
session_idstring
Only deliver events for this session.

Return

valueunknown

session::store::events

Trigger

Internal: event-envelope feed for bridged session-manager instances. Not for direct consumption — bind the six public session::* types instead.

Invocation

Empty object

Return

valueunknown

Install

Functions40

Triggers7

Search the registry