session-manager

Name: session-manager
Author: iii

v1.0.17

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

license: Apache-2.0Published 1mo agochat conversation history session

Install

bash

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

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

Functions29

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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 "".
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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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::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.
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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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-message

Function

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

Request

entry_idstringrequired
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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.
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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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::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.
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 5 nestedHide nested
  one of (5)
  Variant 1
  textstringrequired
  typestringrequiredenum text
  Variant 2
  datastringrequired
  Base64-encoded image bytes.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 4
  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 5
  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 5 nestedHide nested
  one of (5)
  Variant 1
  textstringrequired
  typestringrequiredenum text
  Variant 2
  datastringrequired
  Base64-encoded image bytes.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 4
  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 5
  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 5 nestedHide nested
  one of (5)
  Variant 1
  textstringrequired
  typestringrequiredenum text
  Variant 2
  datastringrequired
  Base64-encoded image bytes.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 4
  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 5
  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 5 nestedHide nested
  one of (5)
  Variant 1
  textstringrequired
  typestringrequiredenum text
  Variant 2
  datastringrequired
  Base64-encoded image bytes.
  mimestringrequired
  MIME type, e.g. `image/png`.
  typestringrequiredenum image
  Variant 3
  signaturestring
  textstringrequired
  typestringrequiredenum thinking
  Variant 4
  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 5
  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::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::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; event-silent, read back on SessionMeta.draft.

Request

draftstring
The unsent input to park. Omit, or send empty/whitespace-only text, to clear the stored draft.
session_idstringrequired

Response

draftstring
The draft 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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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-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-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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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.
forked_fromstring
Source session id when created by `session::fork`.
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-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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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-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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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 5 nestedHide nested
one of (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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.
- forked_fromstring
  Source session id when created by `session::fork`.
- 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 (5)
Variant 1
textstringrequired
typestringrequiredenum text
Variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum image
Variant 3
signaturestring
textstringrequired
typestringrequiredenum thinking
Variant 4
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 5
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

Functions29

Triggers7

Search the registry