Gateway protocol (WebSocket)
The Gateway WS protocol is the single control plane + node transport for WednesdayAI. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless nodes) connect over WebSocket and declare their role + scope at handshake time.Transport
- WebSocket, text frames with JSON payloads.
- First frame must be a
connectrequest.
Handshake (connect)
Gateway → Client (pre-connect challenge):hello-ok also includes:
features object: required methods and events list the RPC
methods and events this gateway serves, and the optional capabilities string array advertises
param-level feature flags a client must detect before sending (for example
"chat.send.turnContext" — see the chat.send params below — or
"chat.history.spanTranscripts" — see the chat.history params). Older gateways omit
capabilities, so its absence means the feature is unavailable.
Protocol admission (role floors)
minProtocol/maxProtocol must admit the gateway’s current protocol version. The floors are
role-keyed (src/gateway/server/ws-connection/connect-admission.ts):
- a node-role connect with
mode: "node"is admitted down toMIN_NODE_PROTOCOL_VERSION(3), so legacy v3 nodes keep working after the protocol-4 cut (ADR 2691); - a
mode: "probe"connect is admitted down toMIN_PROBE_PROTOCOL_VERSION(3); - every other client (operators, UIs) must include the current
PROTOCOL_VERSION(3 today, 4 after the cut).
ok: false, error.code: "INVALID_REQUEST", and
error.details carrying the PROTOCOL_MISMATCH shape: clientMinProtocol,
clientMaxProtocol, expectedProtocol, the server’s minProtocol/maxProtocol window, and
reloadRequired: true for control_ui clients (reload the web app; do not reconnect blind).
The socket then closes with 1002. One gateway/protocol log line per successful connect
records {role, mode, clientId, clientVersion, min, max}, and an operator connection with
maxProtocol < 4 warns that the protocol-4 cut will refuse it.
Plugin surface URLs (canvas)
hello-ok carries optional pluginSurfaceUrls: a record of surface name to scoped URL. The
only surface today is canvas — the same per-node capability-scoped URL the legacy
canvasHostUrl field carries. The legacy field is deprecated and is removed at protocol 4
(ADR 2691); protocol 3 keeps both so existing nodes are unaffected. Clients that support
protocol 4 read pluginSurfaceUrls.canvas first and fall back to canvasHostUrl.
Node example
Framing
- Request:
{type:"req", id, method, params, accessoryId?} - Response:
{type:"res", id, ok, payload|error} - Event:
{type:"event", event, payload, seq?, stateVersion?}
accessoryId on a
request frame names an accessory of the calling device; the gateway clamps such requests to that
accessory’s profile (Device accessories).
Roles + scopes
Roles
operator= control plane client (CLI/UI/automation).node= capability host (camera/screen/canvas/system.run).
Scopes (operator)
Common scopes:operator.readoperator.writeoperator.adminoperator.approvalsoperator.pairing
operator.talk.secrets admits no method on its own. talk.config with includeSecrets: true
returns the unredacted talk config (provider API keys) only to a connection holding
operator.talk.secrets or operator.admin; anything else is refused with
missing scope: operator.talk.secrets. Setup-code pairing grants it (see the client profile table
below).
Narrow session scopes, for bounded chat clients (ADR 0077):
operator.sessions.readoperator.sessions.write
Scope implication
A requested scope is satisfied by any scope in its row. Read downward only: the narrow session scopes never imply anything broader.
The same table governs method admission, event delivery, and the device-token subset check at
connect, so an operator device may request only the narrow scopes and connect normally.
Narrow scope method allowlist
A narrow session scope admits a method only when the method is on its allowlist. Anything else in theoperator.read or operator.write groups, and every operator.admin, operator.approvals and
operator.pairing method, is refused with missing scope: <group scope>. Methods added to the
read or write groups later are refused until they are allowlisted.
operator.sessions.read:health,status,models.list,models.authStatus,agents.list,agent.identity.get,sessions.list,sessions.describe,sessions.compaction.list,sessions.resolve,sessions.subscribe,sessions.direct,chat.history,identity.self,device.self,chat.surfaces.list,chat.surfaces.get,sessions.runs.list,sessions.runs.get,sessions.runs.events,tasks.runs.list,tasks.runs.get,tasks.runs.events,talk.catalog,tts.readAloud.status.talk.catalogjoined the list with ADR 0086 (cascaded voice admission) so a narrow client can render Dictate/Voice as available or disabled; it reports provider/gate state only, never a secret.tts.readAloud.statusjoined with ADR 0102 (read aloud): it reports the read-aloud gate andmaxTextLengthfor the requested agent, never a secret.chat.surfaces.listandchat.surfaces.getjoined with ADR 0106 (assistant UI surfaces): they read the session’s assistant-composed surfaces for the web client’s Canvas panel. Theui-surfacesplugin seam answersenabled: falsewhen the plugin is off, so admission is unconditional; the methods report the plugin’s state rather than the absence of the capability. See Assistant UI surfaces.identity.selfjoined with ADR 0116 (identity binding at enrollment): it reads the calling browser’s own person and links; the device id comes from the verified connection, never the request body.device.selfjoined with ADR 2242 (app device integration): it reads the caller’s own device group only. See Device companions and device.self.identity.devices.listjoined with the app-login plan (ADR 2600): it reads the caller’s own person’s devices from any own device. See Identity RPCs.operator.sessions.write:chat.send,chat.surfaces.pin,chat.abort,sessions.create,sessions.steer,sessions.abort,sessions.runs.cancel,sessions.runs.continue,sessions.patch,sessions.title.prepare,talk.session.create,talk.session.appendAudio,talk.session.close,talk.session.cancelTurn,talk.session.mark,talk.session.bargeIn,talk.session.update,identity.link.claim,identity.logoutandidentity.devices.remove.chat.surfaces.pinjoined with ADR 0106 (assistant UI surfaces): it is the one surfaces write, flipping the pinned boolean on a surface the session already owns. Submitting a form or choice is not this method - it is achat.sendwith auiActionparam, and the turn is command-inert (see Assistant UI surfaces).sessions.patch/sessions.title.preparejoined with client-chat-v3 P2 (ADR 0083):sessions.patchis field-guarded (below), andsessions.title.prepareneeds no guard because it changes no session state. The seventalk.session.*methods joined with ADR 0086/0087/0088 (cascaded voice admission): they let a narrow client run thestt-tts,transcriptionand (ADR 0103)realtimeTalk session modes Dictate and Voice mode use. Admission is independent oftalk.conversation.enabled. That gate is checked insidetalk.session.create, not by this table:mode: "stt-tts"andmode: "realtime"are refusedUNAVAILABLE(voice conversation disabled) for every caller while the gate is off, and a narrow connection is refused the same way formode: "transcription"too. An operator-scopetranscriptioncreate is not gated. Request and event shapes are under Talk sessions.tts.speakjoined with ADR 0102 (read aloud) so a narrow client can read replies aloud on demand; shapes and errors are under TTS read aloud.identity.link.claimandidentity.logoutjoined with ADR 0116 (identity binding at enrollment): redeeming a self-service/linkcode and the server-side logout of the calling device. Both take the device id from the verified connection, never the request body; behaviour is under Identity RPCs.identity.devices.removejoined with the app-login plan (ADR 2600): a person removes one of their own devices (the lost-phone path). See Identity RPCs.talk.realtime.*,talk.configandtalk.modestay operator-only, as do every othertts.*method.
userFacing: false (ADR 0121) is refused on every admitted method and
hidden from every admitted listing, so internal ids look the same as unconfigured ones:
handleGatewayRequest refuses any request whose params name an internal agent (agentId,
sessionKey, key, parentSessionKey, …) with the same unknown agent "<id>" error an
unconfigured id gets; sessions.create enforces the same inside createSession and answers
unknown agent: <id>; agents.list and sessions.direct omit internal agents’ rows, sessions.list
hides their agent activity, sessions.resolve searches a store without their sessions, and
sessions.runs.list drops their runs; a run id that resolves to an internal agent’s session is
refused where it resolves (sessions.runs.get/events/continue/cancel); and session-bearing
events for their sessions are withheld from the connection. Operators and other agents keep full
access.
sessions.patch is admitted per call, not per method name: the fields the call carries decide the
scope it needs.
A field counts when it is present, whatever its value, so
{ "execHost": null } still needs admin,
and a call without a params object resolves to operator.admin. A narrow or write-only connection
that sends any other field is refused with missing scope: operator.admin before the handler runs,
and the stored entry is unchanged. The write and narrow field sets are two separate lists
(SESSIONS_PATCH_WRITE_FIELDS and NARROW_SESSION_PATCH_FIELDS in src/gateway/method-scopes.ts),
so widening one never widens the other, and a field added to the schema later needs
operator.admin until an ADR admits it. Before ADR 0083 the whole method needed operator.admin;
a write-only integration can now change these five settings on any session key it names. archived
joined both allowlists with ADR 0083’s amendment (2026-11-02): true sets archived: true and
archivedAt: <now> on the stored entry, false deletes both, the echo projects them like any
allowed field, and only the unarchive patch clears them — a new message and sessions.reset leave
an archived session archived. sessions.list rows project archived: true for archived sessions
(see sessions.list sorting, agent activity, and visibility);
there is no server-side filter for it, clients filter.
A narrow connection never receives the admin-only session fields: the sessions.patch echo and
every sessions.list / sessions.describe row omit execHost, execNode, execSecurity,
execAsk, sendPolicy, spawnedBy, spawnDepth, elevatedLevel, verboseLevel,
responseUsage and groupActivation. Write and admin connections receive them unchanged.
health and status return the existing non-admin redacted projection for these scopes, and
health with probe: true is refused (missing scope: operator.read) because a forced live probe
is an operator diagnostic. talk.catalog and the seven talk.session.* methods above are the only
talk.* methods allowlisted; every other talk.* method (talk.realtime.*, talk.config,
talk.mode, talk.metrics) stays refused with missing scope: operator.read or
missing scope: operator.write. Behaviour of the admitted methods is in
Voice conversation sessions; the frames are under
Talk sessions.
Narrow scope event allowlist
A connection that either carries a narrow session scope, or presents the boundedopenclaw-user-client id, and in either case does not satisfy operator.read, receives only these
events:
talk.event joined this table with ADR 0086/0088: a narrow connection receives it only for its own
Talk sessions, never another connection’s.
Everything else, including presence, health, cron, exec.approval.*, device.pair.*,
node.pair.*, node.invoke.request, talk.mode, agent, sessions.runsUpdate and any event
registered later, is not delivered. Operator connections are unaffected.
Chat events are not filtered per session owner: every session stays visible to every operator-role
connection on a gateway.
Assistant UI surfaces
Assistant-composed inline UI (ADR 0106) travels the same chat and session methods, with one new event and a small method family. Everything lives behind the bundledui-surfaces plugin
(docs/plugins/ui-surfaces.md); when the plugin is off, chat.surfaces.list
answers enabled: false and the methods never surface a show_ui output;
chat.surfaces.get and chat.surfaces.pin answer UNAVAILABLE with
details.reason: "ui-surfaces-disabled".
chat.surfaces.list(operator.sessions.read) with{sessionKey}answers{ "ok": true, "enabled": <boolean>, "surfaces": [...] }. Each summary row is{ "surfaceId": "...", "title": "...", "revision": <int>, "pinned": <boolean>, "updatedAt": <epoch ms> }.chat.surfaces.get(operator.sessions.read) with{sessionKey, surfaceId, revision?}answers{ "ok": true, "surfaceId": "...", "revision": <int>, "latestRevision": <int>, "pinned": <boolean>, "title": "...", "protocol": "...", "catalogId": "...", "components": [...], "consumedActionId": "..." }. Omittingrevisionfetches the latest revision.componentsis the stored A2UI surface (catalogwednesdayai.dev:client/1); it is not re-encoded here - theui-contractpackage owns that schema. AsurfaceIdorrevisionthat no longer exists answersINVALID_REQUESTwithdetails.reason: "surface-not-found".chat.surfaces.pin(operator.sessions.write) with{sessionKey, surfaceId, pinned}flips the pinned boolean and answers{ "ok": true, "surfaceId": "...", "pinned": <boolean> }. Pinning is a display-only flag: it controls Canvas ordering, never session state.chat.sendaccepts an optionaluiActionparam that submits a form or choice on a stored surface:{ "surfaceId": "...", "revision": <int>, "actionId": "...", "data": {...} }. The handler refuses amessagebody alongside the action (ui-action-with-message), a serializeddataobject over the size cap (ui-action-too-large), and - through the plugin’s provider - an unknown surface (ui-action-unknown-surface), a revision older than the surface’s latest (ui-action-stale), anactionIdthe surface does not declare (ui-action-undeclared), values that fail the action’s schema (ui-action-invalid-data), and a submit action that has already been consumed (ui-action-consumed). Each accepted action turns into one normal turn: the gateway composes the[ui-action]text with the sender’schat.sendidentity and appends it to the transcript before the user message, so it is stored, replayed and audited like any other turn. The turn is command-inert - a submitted value of/newnever resets the session, and the turn never resolves a pending exec approval.chat.activity(operator.sessions.read) streams bounded per-step tool activity for a turn. The event carries{ "runId": "...", "sessionKey": "...", "toolCallId": "...", "name": "...", "status": "running" | "done" | "error" | "waiting-approval", "startedAt": <epoch ms>, "durationMs": <ms>?, "turnSeq": <int>? }; when the step published a surface, an extrauiobject is present ({ "surfaceId": "...", "revision": <int> }).nameis a display title only - tool arguments and results are never included. Start frames may also carry a displayverb(at most 64 characters) anddetail(at most 200 characters): the verb and detail resolved from the shared tool-display spec for the step’s arguments, where every argument string is passed throughredactToolDetailbefore the resolver runs (redaction must not race a cap that can cut a secret’s closing delimiter), and both fields are redacted and capped again before sending - the same label the client’s stored chip later resolves from the stored arguments, so a live chip and the chip that replaces it at turn end do not drift; the one accepted difference is a live label that redaction or the cap changed. Raw args and results are still never included. It is broadcast ordered with the session’schatframes and is droppable under backpressure rather than blocking the turn.turnSeqfollows the rule under Chat event transcript positions.connect.params.renderProfile(optional,"full"|"compact"|"hud") declares how much UI the client can show. With"hud", ashow_uitool result is plain text of at most four lines plus at most two submit actions (see ui-surfaces plugin)."full","compact"and an omitted field all get the unchanged result. Any other value refuses the connect withINVALID_REQUEST.
Client identity
connect.params.client.id is a closed enum. It is identity and audit metadata, not authorization:
the v3 signature proves the device signed the id it declared, so altering the id after signing (or
replaying a signature produced for another id) fails signature verification.
Four client ids declare a bootstrap profile, which is the role + scope set their setup code mints
at pairing time:
wednesdayai-mobile and wednesdayai-desktop mint the identical app credential as the
deprecated wednesdayai-glass-node alias (ADR 2242 D4); the app signs in through
identity-oidc, which is also how its person is set.
operator.approvals on an app connection (wednesdayai-glass-node, wednesdayai-mobile or
wednesdayai-desktop) without operator.admin covers only
exec approvals whose session actor is the app’s own linked person (ADR 2242 D5). Such a connection
receives no exec.approval.requested/exec.approval.resolved event for any other approval,
including one with no session or an unowned session, or any approval when its device is not linked
to a person. exec.approval.resolve and exec.approval.waitDecision answer for a hidden approval
exactly as for a missing one. The learning.* approval methods are refused with
missing scope: operator.admin. A device paired as one of the app client ids stays bound to that
app identity: a reconnect declaring a non-app id is refused with details.reason = "metadata-upgrade"
until an administrator approves the new pairing request.
With the identity-oidc plugin configured for appSignIn: "required", a device-token connect of an
app device whose pairing record has no person is refused with
details.code = app_sign_in_required (and close 1008): the app must sign in, which pairs it as a
new device with its person. When appSessionMaxAgeDays is set, an app device paired more than
that many days ago is refused with details.code = app_sign_in_expired. Setup-code issuance for
the app profiles is refused the same way over device.bootstrap.issue (details.reason = "app_sign_in_required"). Companions and non-app devices are unaffected; see
identity-oidc.
Rules that apply to bootstrap redemption:
- Exact profile binding. The stored profile of the bootstrap token must equal the connecting
client’s declared profile (same role set, same scope set). A cross-profile redemption is refused
with
details.code = bootstrap_profile_violationin both directions, and the token is neither consumed nor device-bound by the refusal. The human-readableerror.messageand the websocket close reason state the setup-code cause (“setup code was issued for a different client profile”), not a shared-token cause; every other bootstrap reason (bootstrap_token_invalid,bootstrap_token_expired,bootstrap_token_consumed,bootstrap_token_device_mismatch,bootstrap_code_verifier_invalid,bootstrap_device_owned) names the setup code the same way. - Code-verifier binding. A setup code minted with an RFC 7636 S256 challenge (native sign-in,
see Identity OIDC) is redeemable only when the connect also
sends
auth.bootstrapCodeVerifier, the 43–128 character verifier whose SHA-256 base64url digest equals the stored challenge. A missing, malformed or wrong verifier is refused withdetails.code = bootstrap_code_verifier_invalidbefore the token is bound to the device, so an app that intercepted the redirect cannot pair with the code. Setup codes minted without a challenge ignore the field. - No rebinding. A token whose identity differs from the owner on the redeeming device’s
pairing record is refused with
details.code = bootstrap_device_owned. The token stays bound to that device but is not consumed; log the device out or remove it, then pair again with a new setup code. An owner write that loses a race to another person’s after this check refuses the connect the same way (that token is already consumed); the winning owner stays. - No widening. The minted device token is approved for exactly the profile’s scopes. A later
connect requesting anything outside that set is refused;
details.codeisAUTH_DEVICE_TOKEN_MISMATCHwith the additivedetails.deviceTokenReason = "scope-mismatch". A subset of the approved scopes connects normally. - Redeemed under ambient auth. A presented bootstrap token is redeemed even when the connect is
already admitted by
none,tailscaleortrusted-proxyauth or a shared secret, so a client pairing through Tailscale Serve still gets the full profile silently. If redemption fails there, the earlier admission stands and the connect proceeds as it would without the token. - Device tokens under ambient auth. Under
none,trusted-proxyor Tailscale identity auth, a connect that presentsauth.deviceTokenhas it verified exactly as undertokenmode. A revoked, unknown or over-scoped token is refused withAUTH_DEVICE_TOKEN_MISMATCH(plusdetails.deviceTokenReason), and the client should drop the token and reconnect. A valid token connects under the ambient admission. A connect that presentsauth.deviceTokenwithout adeviceblock is refused the same way (deviceTokenReason: "device-identity-required"), since there is no identity to bind the token to.auth.tokenis not treated as a device credential there.
openclaw-mentra-node pairs the WednesdayAI miniapp for MentraOS display glasses
(apps/mentra-glass).
Its bootstrap profile is operator-only: role operator with the broad operator.read and
operator.write scopes (chat, session reads, agents.list, voice wake get/set and the rest of
the operator read/write surface), not a narrow allowlist like the user client’s session scopes.
Tokens minted by this bootstrap profile carry no node role and none of operator.admin,
operator.approvals, operator.pairing or operator.talk.secrets; the client id itself is
identity metadata, not an authorization ceiling, and an administrator-approved pairing request
can still grant the device more. One scan pairs the glasses: the setup code is single-use,
redemption approves the pairing silently, and later reconnects authenticate with the minted
operator device token. Setup and device management: MentraOS Glasses.
openclaw-even-g2-node pairs the third-party Even G2 node client. It connects as both
roles: a node socket (role node, no scopes, canvas capability) that answers the glass.* HUD
command family granted by the device’s attached accessories — the glass.hud.show,
glass.hud.dismiss, glass.app.open, glass.state.get commands — and an operator socket with
operator.read + operator.write. It also pulls plugin glance widgets via glance.widgets.list.
wednesdayai-glass-node pairs WednesdayAI Glass (ADR 0107) as both roles. The node socket is role
node with no scopes, canvas capability, and answers the glass.* family (glass.hud.show,
glass.hud.dismiss, glass.app.open, glass.state.get, plus declared glass.tool.*). Grants
come from the device’s attached accessories (device.accessory.attach, profile table
ACCESSORY_PROFILES): the deprecated accessory:g2 connect cap is accepted for one release as an
alias that auto-attaches a cap:glasses accessory on the verified device (the gateway logs the
deprecation once per device; a shared-token node without a device keeps the grant from the cap
itself). Attach and detach refresh the live node session without a reconnect, and
gateway.nodes.denyCommands still wins over any accessory grant. Device family glasses remains
a separate deprecated alias for one release. The
operator socket has operator.read, operator.write and own-person operator.approvals, and pulls
glance.widgets.list. Its profile mints exactly those three scopes, so setup codes for other client
ids, including the default wednesdayai qr code, cannot be redeemed by it.
openclaw-user-client carries two further admission rules:
- No shared credentials. A connect declaring
openclaw-user-clientwithauth.tokenorauth.passwordis refused withdetails.code = CLIENT_SHARED_AUTH_NOT_ALLOWED. It must use its bounded bootstrap token or the device token minted from it. Operator client ids are unaffected. - A bounded device credential under every auth mode. Admission for this client id requires a
device identity plus a verified bounded device token, or a bootstrap redemption that mints one.
This holds under every
gateway.auth.mode:token,password,none,trusted-proxyandtailscaleauthenticate the transport or the deployment, not the device, so none of them admits this client id on its own. A connect with no device block or no device credential is refused withdetails.code = CLIENT_DEVICE_CREDENTIAL_REQUIREDand websocket close1008before any scope is granted, no matter whatroleorscopesit declared. Behind a reverse proxy the client connects normally with its bounded device token, and the device token is verified there exactly as it is undertokenmode (an over-scoped request still fails withAUTH_DEVICE_TOKEN_MISMATCHanddetails.deviceTokenReason = "scope-mismatch"). Other client ids keep the auth mode’s behavior unchanged - atrusted-proxydeployment still admits an operator console with no device identity. - Always-on browser origin check. The websocket
Originis checked againstgateway.webClient.allowedOriginson every connect, including when reverse-proxy headers are present. A missingOrigin, a loopbackOrigin, or an origin that only appears ingateway.controlUi.allowedOriginsis refused withdetails.code = WEB_CLIENT_ORIGIN_NOT_ALLOWEDand websocket close1008 origin not allowed. Control UI origin behavior is unchanged.
Caps/commands/permissions (node)
Nodes declare capability claims at connect time:caps: high-level capability categories.commands: command allowlist for invoke.permissions: granular toggles (e.g.screen.record,camera.capture).
Command descriptors (node)
A node may describe its commands with an optionalcommandSpecs array next to commands
(ADR 2242 D3). Each entry is a NodeCommandSpec:
namemust be incommandsafter the Gateway applies the node command allowlist. A descriptor never widens that policy; a spec for any other name is ignored.inputSchemais a JSON Schema whose top-leveltypeisobject. It uses the provider-safe subset: noanyOf,oneOf,allOf, orformatkeyword, and no property namedformat, at any depth. Each schema is capped at 8 KiB of JSON.descriptionis capped at 1024 characters; it becomes model-visible tool text.timeoutMs(positive integer) andproactive(boolean) are optional; other values are ignored.- The Gateway reads at most the first 64 entries (valid or not) and keeps the first spec for a duplicated name.
gateway/nodes). It never rejects the
connection. To replace the whole set while connected, the node sends
node.event with event: "node.commands.changed" and payload: { "commandSpecs": [...] }. This
never changes the node’s commands, and it applies only from the connection that currently owns
the node session; an event from a superseded connection of the same node is ignored.
Each described command becomes an agent device tool for the person the node is linked to (see
Device tools). Every node.invoke of a described command, from a device
tool or any other caller, passes these Gateway checks before the node receives
node.invoke.request; a refusal fails the call with UNAVAILABLE and a <CODE>: <message> text
naming the limit:
The wait for the node is the smallest of the caller’s
timeoutMs, the descriptor’s timeoutMs,
and 30000 ms. Missing params are validated and forwarded as {}. Commands without a descriptor
keep the node.invoke behaviour below.
node.invoke
node.invoke runs a command on a connected node (used by the nodes CLI, exec with host=node,
and operators). Params: nodeId, command, optional params, optional timeoutMs, and
idempotencyKey. timeoutMs bounds how long the gateway waits for the node result; when omitted
the default is 30000 ms (clamped to the Node timer max). The timeout travels to the node in
node.invoke.request; a result that arrives after the gateway stopped waiting is dropped and
logged as late invoke result dropped at warn level.
node.invoke.request may carry an optional run (NodeInvokeRunContext, gateway contract 3.13)
naming the agent run behind the call:
node.invoke params cannot carry it (a run field is rejected with
INVALID_REQUEST), so no RPC caller can claim a user-initiated run. userInitiated is true when
a user message started the run and false for cron, heartbeat, and other background runs, so a
node can apply its own limits to proactive use without inferring the turn from chat.activity
events. Requests from the CLI, operators, and exec omit it. It carries no session key or
identity.
A request tagged with an accessoryId narrows the command to what the accessory’s kind grants
(glass.* means the glass. prefix; any other profile entry is an exact match), checked after the
command allowlist above so a gateway deny still wins. The refusal carries
error.details.reason: accessory_command_denied. See
Device accessories.
Presence
system-presencereturns entries keyed by device identity.- Presence entries include
deviceId,roles, andscopesso UIs can show a single row per device even when it connects as both operator and node.
Node helper methods
- Nodes may call
node.pluginSurface.refreshwith{ surface: "canvas" }to rotate their canvas capability and get a fresh scoped URL; the response is{ pluginSurfaceUrls: { canvas: <scoped url> } }. An unknown or missing surface fails withINVALID_REQUEST. The deprecatednode.canvas.capability.refresh(empty params) returns the same rotation as{ canvasHostUrl, canvasCapability, canvasCapabilityExpiresAtMs }and is removed at protocol 4 (ADR 2691). - Nodes may call
skills.binsto fetch the current list of skill executables for auto-allow checks. - Nodes may send
node.eventwithevent: "device.context"to publish live device state. The payload isoptIn(required boolean) plus any ofglassesWorn(boolean),glassesBattery(integer 0–100),audioRoute(glasses,phone_speaker,phone_receiver,headphones,bluetooth,car,other),watchReachable(boolean), andforegroundGlassesApp(string, at most 64 characters). Invalid fields are dropped one by one. The gateway stores the latest state only for a connection with an authenticated device identity whose device id is linked to a person insession.identityLinks(device:<deviceId>).optIn: falseor a disconnect clears it, with no TTL, so the app republishes on connect. Turns whose session actor is that person get a “Device context (untrusted metadata)” block; see Session history hygiene.
Operator helper methods
-
Operators may call
healthto fetch the status summary. With theoperator.adminscope the response also carriesprotocolClients: the live connection inventory grouped by{ role, mode, maxProtocol, clientVersion, count }(ADR 2691). The protocol-4 cut reads this inventory, so an operator socket that sentmaxProtocol < 4stays visible there until it reconnects or is closed. -
Operators may call
tools.catalog(operator.read) to fetch the runtime tool catalog for an agent. The response includes grouped tools and provenance metadata:source:coreorpluginpluginId: plugin owner whensource="plugin"optional: whether a plugin tool is optional
-
Operators may call
agent.nudge(operator.admin) to inject non-user context into an agent’s main session by enqueuing a dedicatedagent.turnwithkind=nudge(claimed and executed directly; it is not a heartbeat wake). The request schema isAgentNudgeParams:textis required; optional fields aredata,agentId,sessionKey,reason,source,dedupeKey,ttlMs,priority, andrequiresIdle. Extra fields are rejected.reason,source,ttlMs,priority, andrequiresIdleare accepted for compatibility and ignored.sessionKey, when given, must name the same agent asagentId(session-agent-mismatchotherwise); a successful response isAgentNudgeResultwith{ "ok": true, "sessionKey": "...", "signalId": "..." }and confirms durable admission:signalIdis the idempotency key of the persisted row. Dedupe is requester-scoped — the key isagent-turn:nudge:operator:<runId>, whererunIdis derived from the requester, the target session, anddedupeKeywhen one is supplied, so the same operator request with the samededupeKeyis admitted once and different requesters never collide. Plugin and agent callers use the same seam with their own requester-scoped keys; see Agent coordination. A refusal surfaces asINVALID_REQUESTwith the reason (empty-text,unknown-agent,self-target,session-agent-mismatch,depth-exceeded) as the message, except the two backpressure outcomes:enqueue-failedanswersUNAVAILABLE, andrejected-overflow— the target session already holds its cap of 32 parked delayed turns — answersUNAVAILABLEwithretryable: truebecause it clears once the lane drains. -
Operators may call
sessions.describe(operator.read; narrow-admitted) with{key, includeDerivedTitles?, includeLastMessage?}to fetch a single gateway session row:{ "ok": true, "key": "...", "session": <row> }, wherekeyis the session’s canonical key and<row>has the same fields as that key’ssessions.listrow (including the resolvedmodelandmodelProvider, andthinkingLevelandreasoningLevelwhen the session overrides them). The two flags behave as they do onsessions.list. An unknown key returnsINVALID_REQUESTwithdetails.reason = "session_not_found"anddetails.keyset to the key that was asked for. -
Operators may call
sessions.compaction.list(operator.read) with{key}to list a session’s durable compaction checkpoints, newest first:{ "ok": true, "key": "...", "checkpoints": [{ "id": "...", "createdAt": "<ISO-8601>", "tokensBefore": 0, "firstKeptEntryId": "..." }] }. The checkpoints come from the session transcript, so an empty array means the transcript has no compaction entries. -
Operators may call
sessions.compact(operator.admin) with{key, maxLines?}to run model compaction for the session — the same compaction/compactruns over the session’s stored history, queued on the session’s lane. A success answers{ "ok": true, "key": "...", "compacted": true }(compacted: falseplus areasonwhen there was nothing to compact, e.g."no sessionId"). Conversation history is append-only: compaction appends a compaction entry rather than deleting or rewriting earlier entries.maxLinespredates SQL session storage, where it capped JSONL transcript lines; it is accepted for compatibility with older clients, ignored, and reported aswarnings: ["maxLines ignored"]. A compaction that fails at the model (unknown model, missing credentials, provider error) answersUNAVAILABLEwithmessage: "session compaction failed: <reason>". -
sessions.deletetombstones the session index without deleting stored conversation entries or moving legacy import sources. Its result is{ "ok": true, "key": "...", "deleted": true, "archived": [] }. ThedeleteTranscriptrequest flag is accepted but ignored, andarchivedis always empty. Both fields are deprecated compatibility fields, removed in the next release. -
Operators may call
sessions.export(operator.read) with{key, cursor?}to page the session’s stored transcript as JSONL lines. Each answer is{ "sessionId": "...", "lines": ["..."], "nextCursor": "...", "warnings": ["..."] }; every page’s serialized response targets at most 4 MiB, the first page starts with a synthesized{"type":"session","id":"...","timestamp":"...","cwd":""}header line, andnextCursoris absent on the last page. Lines follow event-time order (the order turns happened); pass the previousnextCursorascursorto fetch the next page — the token is opaque and bound to the session it was issued for, so reusing it against another session is refused withINVALID_REQUESTand every line arrives exactly once across pages. An entry whose serialized line exceeds the export frame limit ships alone on its own page up to a hard cap of 5.5 MiB; beyond it the entry is replaced by a{"type":"export-omitted","id":"...","reason":"entry exceeds export frame limit","bytes":0}placeholder line named inwarnings— storage is untouched, the export is a view. An unknownkeyanswersINVALID_REQUESTwithdetails.reason = "session_not_found"anddetails.keyset to the key that was asked for. -
Operators may call
sessions.storage.status(operator.read) with no params at any time — it is classifiednone, so it answers during the storage boot window too — for{ "backend": "sqlite" | "postgres", "ready": boolean, "legacyImport": <LegacyImportStatus> }.legacyImportcarries the legacy JSONL import progress:state(none | pending | running | completed | error),total/done/failedcounts pluspending/imported/capped/vanished/rejectedEntriesdetail counts, thearchiveRoot, the pre-importbackupPathwhen one was written, andlastError. A failed source never disappears: it stays visible here and indoctoruntil a retry succeeds. -
Operators may call
sessions.storage.import(operator.admin) with{retryFailed?}to run the legacy import sweep to completion now and get{ "ok": true, "status": <LegacyImportStatus> }. A source that has burned its five automatic attempts is retried only whenretryFailedis true; thewednesdayai session-storage importcommand always sets it for its run (an operator-invoked pass retries capped sources by design — there is no separate CLI flag). -
Operators may call
sessions.storage.validate(operator.admin) with no params to run the schema/integrity validation thewednesdayai session-storage validateCLI uses against the configured storage:{ "ok": boolean, "backend": "...", "checks": [{ "name", "ok", "detail?" }] }. -
Operators may call
sessions.storage.backup(operator.admin) with{path?}to write one online SQLite backup (VACUUM INTOon a separate read-only connection; appends never wait). A relative or absentpathresolves under the gateway’s<state-dir>/backups/; a path outside it is refused. The answer is{ "ok": true, "path": "...", "bytes": N }(file mode0600). Postgres storage rejects this method — usepg_dumpthere. -
Operators may call
sessions.maintenance.run(operator.admin) with{ task: "cleanup" | "backfill" | "drop-legacy-archive", agent?, allAgents?, dryRun?, enforce?, activeKey?, batchSize? }.cleanupruns the same retention core aswednesdayai sessions cleanup(--enforcemaps toenforce: true) and answerssummaries;backfillanddrop-legacy-archiveanswercounts.dryRun: truenever mutates. -
Operators may call
memory.index(operator.admin) with{agentId?, force?}to run the memory index sync for one agent (or every configured agent) inside the gateway:{ "agents": [{ "agentId", "ok", "error?" }] }. -
Operators may call
models.authStatus(operator.read) with no params to list configured auth profiles per provider:{ "providers": [{ "provider": "...", "profiles": [{ "id": "...", "type": "api_key|oauth|token", "lastGood": true }] }] }. The response never contains key, token, access, or refresh material. -
Operators may call
chat.abort(operator.write; narrow-admitted) with{sessionKey, runId?}andsessions.abort(operator.write; narrow-admitted) with{key, runId?}.sessions.abortis an additive alias ofchat.abortwith session-shaped params and identical semantics. Both answer{ "ok": true, "aborted": true|false, "runIds": ["..."] }. WithoutrunIdevery gateway-tracked run of the session is aborted. WithrunIdonly that run is: an id that is not running (unknown, or already finished) answersaborted: falsewith an emptyrunIds, and an id that belongs to a different session is refused withINVALID_REQUEST(runId does not match sessionKey). An aborted run keeps the assistant text it had streamed (persisted to the transcript) and ends with achatevent whosestateisaborted. That event, and the answer to the call, come only once the run’s reply is in the transcript, so a client that re-readschat.historywhen it sees the event gets the final transcript. The run saves its own reply while it stops; the gateway waits for that for up to 10 seconds and then announces the stop regardless, so a stuck run never leaves a client waiting. When the gateway has to save the text itself and cannot, the event is still sent and the call returnsUNAVAILABLE. A run the gateway expires on its own timer is announced at once (stopReasontimeout) and saves nothing. -
Operators may call
sessions.steer(operator.write) with{key, message, mode?, fallback?, idempotencyKey, thinking?, timeoutMs?, attachments?, dictated?, location?}to deliver a message to a session that may already be running a turn.modeisinject(default),interruptorqueue; legacy queue names such assteer,steer-backlog,followupandcollectare rejected. Whenmodeis omitted the gateway defaultgateway.sessions.steer.defaultModeapplies (itself defaulting toinject); the session’s own queue mode is never used for this method.injectdelivers the message into the active run at its next tool-batch boundary and answers{mode, outcome: "injected", runId, targetRunId}, both ids being the active run (omitted when the gateway tracks no run for the session). It is text only: a call whoseattachmentsarray holds at least one entry returnsINVALID_REQUESTwithdetails.reason = "attachments_not_supported_with_inject", whatever the entry looks like.interruptaborts the active run, waits for it to reach a terminal state, then starts the new turn and answers{mode, outcome: "interrupted", runId, targetRunId}. If the old run does not settle withingateway.sessions.steer.settleTimeoutMs(default 15000 ms) the call returnsCONFLICTwithretryable: trueanddetails.reason = "steer_settle_timeout", and no new turn is started.queueleaves the active run alone and runs the message as one follow-up turn afterwards, answering{mode, outcome: "queued", runId, targetRunId};targetRunIdnames the run it waits behind and is omitted when the gateway tracks none.- With no active run every mode answers
{mode, outcome: "started", runId}. - When
modeisinjectbut the active run cannot be steered,fallbackdecides:queue(default) answersoutcome: "queued"withreason: "fallback_queue", andrejectanswersoutcome: "rejected"withreason: "run_not_steerable"and dispatches nothing. A message the session’s own queue policy drops after admission also answersoutcome: "rejected", withreason: "dropped_by_queue_policy". - Reusing an
idempotencyKeyreplays the first response and starts no second run; a second call while the first is still in flight returnsCONFLICTwithdetails.reason = "duplicate_in_flight". queueandinterruptaccept attachments under the same contract aschat.send: any file type, inline base64contentor an ADR 1330uploadIdreference, raster images inline, everything else through the inbound media store (see thechat.sendbullet below). An attachment with neithercontentnor anuploadId(for example, url-only) is dropped by the wire normalizer, and a call that loses an entry that way returnsINVALID_REQUESTwithdetails.reason = "attachment_content_required"rather than silently delivering less than was sent. Attachment resolution runs after the last pre-start refusal (lane admission, the inject guard, the interrupt settle wait), so a steer refused before its turn starts consumes no uploads and itsuploadIdreferences stay retryable.- A
messagethat is blank once trimmed returnsINVALID_REQUEST, as does a session whose send policy denies the send.sessions.steerhas noreplyToIdand noexpectedLeafEntryId: a steered or queued message carries neither a reply reference nor a leaf guard. dictated(optional boolean) marks speech-to-text provenance: some or all ofmessagewas dictated. The turn gets a user-role “Speech input (untrusted metadata)” note so the model can tolerate mis-transcribed names (for example a homophone of a person it knows); the note is never persisted into the message text.location(optional object) carries the device position the user chose to share with the steered message:{latitude, longitude, accuracyMeters?, capturedAtMs}with the same bounds aschat.send’slocation(described below). The turn gets the same user-role “Device location (untrusted metadata)” block on that turn only, never persisted into the message text (ADR 0121).runIdandtargetRunIdalways name a real run, never an id the gateway minted for a call that started no run. Forinjected,startedandinterruptedthe id is a live gateway run: it can be passed tosessions.abortand is reported bysessions.runs.list. Forqueuedit is the id the follow-up turn carries once it starts, not a run that exists yet. A message that joined another run never gets an id of its own, so steering repeatedly into one run reports that same run’s id every time.- Once a
queuedfollow-up’s run actually starts, its id converges with the other outcomes: from that point it can be passed tochat.abort/sessions.abortandsessions.runs.listreports it (sessions.runs.listmerges the live streaming run alongside the durable store;sessions.runs.getreads the durable store only). This supersedes ADR 0072’s original “not abortable while the follow-up runs” consequence (ADR 0084 section 7, ADR 0085 M6).
-
Operators may call
sessions.runs.list(operator.read) with{sessionKey?, agentId?, statuses?, updatedAfter?, limit?, cursor?}to page the session runs:{ "runs": [<SessionRunRecord>], "nextCursor": "..." }. The durable part of the page orders(createdAt DESC, sessionRunId DESC)regardless of a row’s mutableupdatedAt(ADR 0074). On the first page (nocursor) the handler also merges the live in-flight gateway runs fromcontext.chatAbortControllers- any run whose agent run has started, including asessions.steer-queued follow-up once its run has started and achat.send-started run - deduped byrunIdagainst the durable rows, merged newest first and cut tolimit; later pages walk the durable store only. A live run with no durable row is reported as a synthetic record (sessionRunId: "live:<runId>",kind: "chat",status: "running",recoveryMode: "off") and only matches astatusesfilter that is empty or includesrunning. The live/durable merge applies once session storage is ready. Before storage publishes,sessions.runs.listis arequiredmethod: dispatch holds the request and answers the readiness errors described under Session storage readiness — never an empty page and never live-only records. Unliketasks.runs.list, the row is not summarized: it is the fullSessionRunRecord, includinggatewayInstanceId,recoveryMode,lastEvidencePointerandrecoveryReason- with one exception: the per-run executioncontext(ADR 1929) is stripped from every row, so a polled listing does not grow with the per-run snapshot. Onlysessions.runs.getreturns it. -
Operators may call
sessions.runs.get(operator.read) with{sessionRunId}for a single run:{ "record": <SessionRunRecord> }, or{ "record": null }for an unknown id or an unconfigured store - this method never errors on a missing id. It reads the durable store only, so it never returns the syntheticlive:records thatsessions.runs.listadds. The record may carry an optional executioncontextsnapshot (ADR 1929) holding sizes, counts, names and sanitized labels only: the provider/model that answered, the fallback candidates that failed before it (eachprovider/modelplus an optional reason, never error text), token usage, the stop reason, the error kind, the final prompt’s composition in characters (system prompt, workspace files, skills, tools, per-source injected context and messages), the injected workspace files by basename with sizes and truncated/missing flags, and tool and skill names (capped at 200). It never holds prompt text, injected text, file contents, file paths or fallback error strings. Runs recorded before the feature, runs registered outside the embedded-agent terminal seam (ACP, subagent registry), and heartbeat, nudge, announce and main-session cron turns carry no context. -
Operators may call
sessions.runs.events(operator.read) with{sessionRunId}for that run’s full event history, unpaged:{ "events": [<SessionRunEvent>] }(empty without a configured store). Unliketasks.runs.events, each event’s rawpayloadJsonis included, not stripped. -
Operators may call
tasks.runs.list(operator.read) with{view, status?, taskId?, limit, cursor?}to read the run/task projection. Params are strict: an unknown field, alimitoutside1..200, an unknownviewor an unknownstatusis rejected.view: "queued"lists bus work that is enqueued and not currently claimed, over the REGISTERED task topics only (task.<pass id>for every registered task pass, core passes included). Rows are exactly{ "workId": "...", "topic": "task....", "state": "queued", "changedAt": "<ISO-8601>" }. A row waiting out a retry backoff is still queued. Arbitrary non-task bus work never appears, and a row never carries payload, access context, privacy context, lease owner or attempt counts. AtaskIdfilters this view too, intersecting the registered topic set withtask.<taskId>; an unknown or non-allowlistedtaskIdreturns an empty page, not an error.view: "history"pages durable task runs as{ "taskRunId": "...", "taskId": "...", "status": "...", "mode": "normal|dry_run", "attempts": 0, "createdAt": "<ISO-8601>", "updatedAt": "<ISO-8601>", "startedAt": "...", "completedAt": "...", "durationMs": 0 }where the last three are optional.statusandtaskIdfilter the page.statusis history-only.view: "queued"combined withstatusreturnsINVALID_REQUESTwithdetails.reason = "status_is_history_only"rather than ignoring the filter.- Paging is keyset, not offset: pass the response’s
nextCursorback ascursor. The queued view walks(changedAt DESC, numeric workId DESC)and the history view walks the immutable(createdAt DESC, taskRunId DESC), so a run whose status changes mid-walk is neither duplicated nor skipped.nextCursoris absent on the last page. Cursors are view-tagged: a cursor from one view used on the other, or any undecodable cursor, returnsINVALID_REQUESTwithdetails.reason = "invalid_cursor". - A row claimed into a task run leaves the queued view and appears once in the history view. Work returned to the queue after a failed, deferred or preempted attempt is listed as queued again while its earlier attempt stays in history.
-
Operators may call
tasks.runs.get(operator.read) with{taskRunId}. The response is the history summary above plus optionalstage, and nothing else - never the event list. An unknown id returnsINVALID_REQUESTwithdetails.reason = "task_run_not_found". -
Operators may call
tasks.runs.events(operator.read) with{taskRunId, limit, cursor?}for a bounded per-run event page:{ "events": [{ "eventId": "...", "eventType": "...", "createdAt": "<ISO-8601>" }], "nextCursor": "..." }, ordered(createdAt DESC, eventId DESC). Event payloads are never exposed. -
Before session storage publishes its runtime, all three
tasks.runs.*methods answer the storage-readiness errors described under Session storage readiness rather than an empty page. Additionally,tasks.runs.listwithview: "queued",tasks.runDryRunandtasks.rollbackalso need the task operator registry: they wait up to 4 seconds for it while the task pipeline is still booting and recovery has not settled blocked; if it is still absent they answerRECOVERY_NOT_READYwithdetails.reasonCodes = ["task_pipeline_booting"],retryable: trueandretryAfterMs: 1000; once recovery has settled blocked they answer the plain non-retryableUNAVAILABLE(task_registry_unavailable) instead. -
None of the three read methods exposes
lastError,evidencePointer,scopeKind,scopeKey,gatewayInstanceId,ownerPluginId,retryPolicy,budgetDenials,preemptionCount,costClass,triggerSourceor the raw work id. The join and the redaction run on the server;tasks.statusis unchanged and notasks.*mutation was added. -
chat.history(operator.read; narrow-admitted) takes{sessionKey, limit?, maxChars?, before?}and pages backward through the transcript, oldest message first within a page.limitis 1..1000 (default 200).beforeis the opaquecursorof an earlier response; without it the call returns the newest page. The response carriessessionKey,sessionId,messages,thinkingLevel,verboseLevelandhasMore, pluscursorwhenhasMoreis true: pass that value back asbeforeto fetch the next older page. When the gateway’s response size budget drops older rows from a page,hasMoreis forced true andcursorpoints at the oldest row that was kept, so the nextbeforecall resumes exactly at the first dropped message.maxChars(1..500000) is applied last, to the finished page: it keeps the newest messages whose text fits and drops older ones whole (the newest message is always kept), and it does not movecursor, so messages it drops are not revisited by paging. An undecodable cursor, or one issued by a different session store backend, returnsINVALID_REQUESTwithdetails.reason = "invalid_cursor". -
spanTranscripts(optional boolean,apps/weband the Control UI v2 console today) pages across the session key’s earlier transcripts - idle, daily and explicit resets each start a new transcript under the same key. Rows then carry__openclaw.transcriptIdand__openclaw.rowIdbecomes"<sessionId>:<seq>"(placeholder chunk ids derive from it);__openclaw.seqstays per-transcript. When a transcript is exhausted the read continues into its predecessor, at most 8 hops, stopping at the key’s oldest transcript or at a tombstone (a deleted chat’s history never reappears). Every item cursor carries the transcript id, so paging cannot drift into another chat; when a page ends because an older transcript was reached, the cursor is a transcript-head cursor andhasMoreis true. A transcript-head cursor sent withoutspanTranscriptsis refused withINVALID_REQUESTanddetails.reason = "invalid_cursor". Without the flag, behavior is unchanged and rows keep__openclaw.rowId = String(seq). Clients detect support fromhello-ok.features.capabilitiescontaining"chat.history.spanTranscripts"before sending it, since older gateways reject unknown params. During the boot window the call is held by the dispatch fence and answered per Session storage readiness, never with an empty page. The leaf and reply fields that client-chat-v3 P2 added are described below. -
Operators may call the three
doctor.recovery.*methods to inspect and repair the restart-recovery journal (behaviour and reason codes in Restart recovery).doctor.recovery.inspect(operator.read, no params) answers{ "available": true, "snapshot", "items", "historyItems", "actions", "incidents", "storage" }, or{ "available": false, "reason": "<code>" }while the control plane or its journal is not serving.itemsis the current epoch’s actionable inventory andhistoryItemsthe retained rows from earlier epochs; each entry is the server-side operator projection of one journal row:itemId,title,reasonText,disposition, the recordedsubject(agent, session, run, cron job, channel, trigger, timestamps, a bounded preview) and the item’s ownactions- only the actions the gateway will accept for that item, each{ "id", "requestedAction", "replay", "label", "description", "recommended" }. The top-levelactionsarray is the audit trail: one row per recorded action with the requested action, its result and the acting client ("<client id>@<device id>").doctor.recovery.plananddoctor.recovery.apply(operator.admin) drive repairs: plan takes{ "itemId", "requestedAction" }and answers{ "plan": <RecoveryPlan>, "authorityToken": "..." }, a one-time token bound to the plan digest and the current owner generation; apply takes{ "plan", "authorityToken", "confirm": true, "replay": false }(replayoptional) and answers{ "result": "applied", "disposition": "..." }- plus"replay": { "result": "requested" }when Run again was requested - or{ "result": "rejected", "reasonCode": "...", "reasonText": "..." }.replay: true(Run again) is accepted only on acancelplan and only when the journal holds a replay target for that item; the target is read from the journal, never from the request.
Session storage readiness
With restart recovery on, the gateway serves its WebSocket before its configured SQLite or Postgres session storage starts (ADR 0092). Every core method carries a storage classification in one table, checked at dispatch after authorization and rate limits (so an unauthorized caller never learns readiness) and before the handler runs. Only core methods are classified: plugin andextraHandlers methods are unaffected, and a method without a classification dispatches
unchanged.
required— reads or writes the session storage runtime. With SQL-only storage there is no always-available file view to answer from, so session reads, session writes and usage reads are allrequired:chat.history,chat.inject,sessions.claims.status,sessions.compact,sessions.compaction.list,sessions.create,sessions.delete,sessions.describe,sessions.export,sessions.list,sessions.maintenance.run,sessions.patch,sessions.preview,sessions.reset,sessions.resolve,sessions.runHistory,sessions.runs.list,sessions.runs.get,sessions.runs.events,sessions.runs.continue,sessions.runs.cancel,sessions.subscribe,sessions.title.prepare,sessions.usage,sessions.usage.logs,sessions.usage.timeseries,sessions.storage.validate,sessions.storage.backup,sessions.storage.import,memory.index,tasks.runs.list,tasks.runs.get,tasks.runs.events,tasks.status,tasks.resetBudget,tasks.runDryRun,tasks.rollback,tasks.runEvents,usage.cost,usage.status.none— everything the gateway answers without session storage: chat turns (chat.send,chat.abort,sessions.abort), live control, diagnostics,doctor.*,health,status, andsessions.storage.status(so operators can see why storage is not ready).healthandstatusnever hold and never throw on storage: their session sections degrade tosessions: { unavailable: "<reason>" }while storage is starting or failed.
required method’s request is in flight, the storage state decides the answer:
- Starting: the request is held for up to 10 seconds. If the storage start completes inside
the hold, the handler runs normally. Otherwise the answer is
RECOVERY_NOT_READYwithmessage: "session storage is still starting",retryable: true,retryAfterMs: 500anddetails: { producer: "session-storage", phase: "starting", reasonCodes: ["storage_starting"] }. A gateway still starting after the hold logs a single warning. - Stopping:
markStoppingis terminal, so a request that arrives while the state is alreadystoppingis held for up to the same 10 seconds —whenSettledgets no earlier wake and the socket normally closes first — and then answersRECOVERY_NOT_READYwithmessage: "gateway is stopping",retryable: true,retryAfterMs: 500anddetails: { producer: "session-storage", phase: "stopping", reasonCodes: ["storage_stopping"] }. A request already held throughstartinganswers the same shape as soon asmarkStoppingfires. - Failed start:
requiredmethods answerUNAVAILABLEwithmessage: "session storage failed to start",retryable: false, anddetails: { code: "storage_start_failed", reasonCodes: [...] }.UNAVAILABLEfrom these methods is permanent until an operator acts; a client may latch on it. No handler runs after a failed start, so a write can never land outside the database. - Ready: the handler runs unchanged.
RECOVERY_NOT_READY should retry after retryAfterMs; the web client does
this automatically.
client-chat-v3 P2 additions (ADR 0083, ADR 0084, ADR 0085)
These shipped with the/v2/client chat controls. Every new param is optional and every new result
field is additive, so existing callers are unchanged; the one rule change is how sessions.patch
is authorized (see Narrow scope method allowlist).
sessions.create(operator.write; narrow-admitted) takes{parentSessionKey?, label?, agentId?, model?}and answers{ key, sessionKey, sessionId };keyandsessionKeyare the same newagent:<agentId>:dashboard:<uuid>key. The agent isagentId, else the parent session’s agent, else the default agent.labelis 1..512 characters, trimmed, and no other session in the store may hold it.modelis resolved through the sameresolveAllowedModelRefchecksessions.patchuses, before the session is created, and applied to the new session;agents.defaults.modelsbounds the allowed set the same way it boundssessions.patch(see Configuration reference). A refusal writes nothing and returnsINVALID_REQUEST: an unknown agent, anagentIdthat differs from the parent’s agent, a parent session that does not exist, an empty, over-long or already-usedlabel(label already in use: <label>), or an unresolvable or disallowedmodel(invalid model: ...,model not allowed: ...). The call returnsUNAVAILABLEwhen the model catalog cannot be loaded (model catalog unavailable) or the session cannot be written (failed to create session). Asessions.changedevent with reasoncreatefollows, to connections that calledsessions.subscribe.sessions.patch(scope per call, see above) answers{ ok: true, path?, key, entry, resolved: { modelProvider, model } }: the stored entry after the patch and the model the session now resolves to. A field set tonullis cleared (model: nullreturns the session to the agent’s default model).labelmust not be held by another session (label already in use: <label>), andmodelgoes through the same allowlist assessions.create; both refusals areINVALID_REQUEST, and a missing model catalog isUNAVAILABLE. Asessions.changedevent with reasonpatchfollows. For a connection that carries a narrow session scope the echo is redacted:path(the gateway’s session-store path) is omitted, andexecHost,execNode,execSecurity,execAsk,sendPolicy,spawnedBy,spawnDepth,elevatedLevel,verboseLevel,responseUsageandgroupActivationare removed fromentry, even when the call set only an allowed field, because the stored entry can hold values another caller set. Connections without a narrow scope (admin, oroperator.writeonly) get the full entry. The redaction covers this response only:sessions.listandsessions.describerows still carryverboseLevel,elevatedLevel,sendPolicyandresponseUsagefor every scope (ADR 0083).chat.historymessages each carry__openclaw.id(the transcript entry id) when the entry has one. The result gainsleafEntryId: string | null- the id of the newestmessage-type transcript entry that has an id, ornullwhen there is none - plus the identical value atsessionInfo.activeLeafEntryId(upstream’s name for it). On the newest page it is read from the same transcript rows the page is built from, with the exact rulechat.sendcompares against, so it never disagrees with the send-side check; abefore-paged request reportsnullfor both because an older page says nothing about the current leaf. Only message entries move the leaf: a model-change entry, a custom entry (including the reply-reference entry below) or a compaction divider never moves it, so none of those ever causes a false conflict. The internal__openclaw.ingressprovenance carrier is stripped from every message before it reaches the client and never appears inchat.historyoutput; sibling__openclawkeys (id,replyToId, …) are untouched.chat.historymessages also carry__openclaw.runIdwhen the stored entry recorded the run that wrote it. For a run a client started, it equals theidempotencyKeyof that client’schat.sendorsessions.steer(modequeue), so a client can pair its own turn with the stored row even when the stored text differs, and group every row of one reply. Cascaded voice rows carry it too: thestt-ttsassistant rows and the cancelled-fragment user rows record the talk turn id, so a client can pair atranscript.persisted/turn.startedturnId with the stored row. Entries without a stored run id (written before the field existed) omit the key. An oversized message’s placeholder keeps it, and is marked__openclaw.truncated: truewithreason: "oversized". When an oversized tool message’s bare call identities exceed the per-message cap, one stored entry returns as several consecutive placeholder rows that share its run id; only the last carries__openclaw.id. Every returned row additionally carries__openclaw.rowId, an opaque identity of the returned ROW (the entry’s storage position; placeholder chunks suffix a chunk ordinal) that is unique within the session and stable across pages, reloads and window shifts — a client can key rows with it instead of a positional fallback id, which moves when the head window slides. Every returned row also carries__openclaw.seq: <int>, the transcript entry’s per-session monotonic position as a number: the gateway derives it from the cursor paired with the row, so every placeholder chunk of one oversized row carries its row’s ownseq. Clients order the thread with it (Chat event transcript positions).- A user message that quoted another message gains
__openclaw.replyTo: { id, sender?, body? }, plus the same reference under upstream’s field names,__openclaw.replyToIdand__openclaw.replyToPreview: { text, senderLabel? }.bodyis at most 2000 characters andsender(the quoted message’s author) at most 200; both are absent on an id-only reference. The reference is stored as a custom transcript entry written just before the user turn, so it never enters the model context. - A user message that arrived from another session’s turn - an inter-session relay (ADR 0081’s
provenance:
provenance.kind === "inter_session") - gains__openclaw.sourceAgentId: <agentId>, the agent whose session sent it, parsed from the storedsourceSessionKeywithparseAgentSessionKey(never a hand-split of the key). Messages without inter-session provenance omit the field. Per ADR 0120, the field is also omitted when the source agent is internal (userFacing: false) — user clients never learn internal agent ids. The web client renders the field as the From <assistant> label on the row. - Every row also carries
__openclaw.triggerwhen its storedtriggerSourceis set - the system origin of the turn that wrote it:user,heartbeat,cron,subagentoracp. Rows written before the field existed (a nulltrigger_sourcecolumn) omit the key. The internal__openclaw.ingresscarrier stays stripped (above), so this projection is the only provenance a client sees: a client can hide system-origin exchanges (heartbeat/cron prompts and their replies) by this field, never by message text. Clients detect support fromhello-ok.features.capabilitiescontaining"chat.history.trigger". chat.send(operator.write; narrow-admitted) takes{sessionKey, message, idempotencyKey, thinking?, deliver?, attachments?, timeoutMs?, replyToId?, replyToTranscriptId?, expectedLeafEntryId?, dictated?, location?}and answers{ runId, status: "started" }("in_flight"when the sameidempotencyKeyis still running). When an embedded run is already active in the session and the queue policy enqueues the turn behind it, the answer is{ runId, status: "queued" }, sent once the policy decides (at most 30 s). No emptyfinalis broadcast for a queued turn; its events stream underrunIdwhen the queue drains. P2 added the last two params, anddictated(described below) is also optional:replyToIdis the entry id of the message being replied to (the__openclaw.idof achat.historymessage). The gateway looks it up in this session’s own transcript first, then through the chat’s earlier transcripts (seereplyToTranscriptIdbelow), and gives the turn’s prompt the quoted message as reply context: its text (at most 2000 characters) and its sender (the assistant’s name for an assistant message, otherwise the connecting client’sdisplayNameorUser). It also persists the reference beside the user turn, which is howchat.historylater reports__openclaw.replyTo; when a run is already active for the session, that write waits until this turn’s own run starts. An id that does not resolve in this session (unknown, or from another session) keeps an id-only reference - no body or sender - and logs a warning; the message still sends. The reference is persisted only when the session already has a stored session id.replyToTranscriptId(ADR 1966 span history) names the transcript holdingreplyToIdwhen the target predates the current one (from the row’s__openclaw.transcriptId). The gateway then resolves the entry exclusively in that transcript - entry ids are unique only per(session_id, entry_id), so a current-transcript-first fallback could silently quote a different message sharing the id - and the owner-checkedtranscriptInChatprobe (the same checkchat.historycursor binding uses, keyed on the resolved store key) keeps the read inside this chat: a transcript of another chat, an unknown one, or a tombstone keeps an id-only reference, and no other transcript is read. Naming the current transcript also resolves exclusively there: a miss reports not-found instead of walking predecessors. Without the param, resolution reads the current transcript first, then a bounded predecessor walk (at most 8 hops, stopping at tombstones).expectedLeafEntryId(string ornull) refuses the send when the chat has moved on since the caller last read it. It is compared for exact equality with the leafchat.historyreports (leafEntryId). A mismatch is refused withINVALID_REQUEST, messageactive branch changed; review and retry, anddetails.reason = "active-leaf-changed"; no run starts, nothing is written and no attachment is parsed or stored.nullasserts an empty transcript (it also matches a session with no stored transcript yet), and omitting the field skips the check. The check runs after the send-policy check and after idempotent-replay handling, so a retry of an earlieridempotencyKey(cached or still in flight) is answered as before instead of being re-checked against a leaf that may have advanced; a/stopmessage is not checked. The guard narrows the race between two devices. It is not a lock: two sends that arrive together can both pass.attachmentsaccepts any file type (ADR 0093). An attachment item carries inline base64content(a binaryArrayBufferor typed-array view is normalized to base64), or, since ADR 1330, anuploadIdreferencing a file the client uploaded overPOST /v2/uploads- an item with neither is dropped before validation. Raster images (mime sniffed from the bytes, else the declared type; SVG never counts as inline) travel as inlineimages[]; every other file is written through the inbound media store and handed to the turn as media paths, with the mime resolved from the sniffed bytes, else the declared type, elseapplication/octet-stream(a sniffed WAV is stored asaudio/wavunless the client declaredaudio/x-wav). Limits: 32 attachments per message and 5,000,000 decoded bytes percontentitem. AnuploadIdreference does not count against that byte budget: its file is bounded by the upload endpoint’s own 50 MiB per-file cap instead. A reference resolves only inside the sending device’s own upload directory (the device id comes from the verified connection, never the request), is claimed atomically before it is read, and is consumed by the first send that reads it: a raster image of 5 MB or less is read into inline base64 like acontentimage, anything else is moved into the inbound media store. A missing, foreign, malformed or already-consumed id answersINVALID_REQUESTwithattachment upload expired or not found. Every attachment is validated before any file is stored, and a failure answersINVALID_REQUESTwith one oftoo many attachments (max 32),attachment <fileName>: content must be base64 string,attachment <fileName>: invalid base64 content, orattachment <fileName>: exceeds size limit (N > 5000000 bytes); a batch that fails after files were written is rolled back, so a rejected batch leaves no partial media files and returns claimed uploads for a retry. A mixedcontent/uploadIdbatch is delivered to the turn in the order the client listed it. A retry or in-flight replay of the sameidempotencyKeyis answered without re-parsing or re-consuming uploads (attachment resolution runs after the idempotency dedupe), so a replay never writes duplicate media-store files.dictated(optional boolean) marks speech-to-text provenance: some or all ofmessagewas dictated. The turn gets a user-role “Speech input (untrusted metadata)” note so the model can tolerate mis-transcribed names; the note is never persisted into the message text. It is ignored foruiActionsubmits, and a turn with the flag stays command-capable.location(optional object) carries the device position the user chose to share with the message (ADR 0121):{latitude, longitude, accuracyMeters?, capturedAtMs}with latitude in [-90, 90], longitude in [-180, 180], an optional non-negativeaccuracyMetersin meters, and acapturedAtMsepoch-millisecond fix time (bounded by the largest validDate). The turn gets a user-role “Device location (untrusted metadata)” block beside the Speech-input note so the model can use the position on this request only; like that note it is never persisted into the message text, stays out ofchat.historyand replay, and is kept only in the stored row’s__openclaw.ingress.untrustedcarrier. It is ignored foruiActionsubmits.turnContext(optional string, at most 4000 characters; longer isINVALID_REQUEST) is a per-turn client instruction for embedded-runner turns. The gateway trims it and strips control characters (newline and tab are kept), the cache boundary marker, and the refusal test token, then renders it as the closingTurn context (client-provided):lane of that turn’s current user prompt envelope, after the user message (ADR 2105 PR 6). The system prompt is untouched — the whole cached prefix stays byte-identical across turns, with and without a context. One exception: when core cannot resolve the turn’s current user row in the final provider input (an overflow compaction cut it out of a continuation request, or atransform_llm_inputhook replaced the messages without their ingress carrier), the context rides that provider request’s system-prompt tail instead (the legacy placement). It is absent from later turns and is never stored: not in transcript rows,clean_user_message, session metadata, or the persisted system-prompt report, and plugin prompt hooks and model-call diagnostics see the prompt without it. Only operator-enabled raw request capture (cache trace, model payload log) records it, as part of the full provider request. A send carryingturnContextis never steered into a run that is already streaming; it queues as its own turn, and queued turns with differentturnContextvalues are never collected into one run. CLI backends ignore it (their system prompt is not resent per turn). It is ignored foruiActionsubmits and is not accepted bysessions.steer. Clients detect support fromhello-ok.features.capabilitiescontaining"chat.send.turnContext"before sending it, since older gateways reject unknown params.
- A
sessions.steer-queued follow-up registers its own run-table entry once its run actually starts, from run start to run end (never from the moment it was merely enqueued). From then it is exactly as abortable and listable as a run started any other way - see thequeuedoutcome bullet in thesessions.steersection above (ADR 0084 section 7, ADR 0085 M6). sessions.title.prepare(operator.write; narrow-admitted; behind the web client’s “Suggest a title” button) takes{ agentId, message, model?, catalogId?, incognito? }-messageis 0..1000 characters - and answers{ title: string (1..60) | null }. It is one completion call, never an agent run, and persists nothing; applying a suggestion is a separatesessions.patch { label }call. The completion is budgeted at 4,096 tokens, or the resolved model’s ownmaxTokenswhen that is set and smaller: some providers emit reasoning tokens before the visible title even when the catalog flags the modelreasoning: false, and a tiny cap left them stopping atlengthwith no text to normalize (src/gateway/session-title-completion.ts).- It answers
{ title: null }without a model call forincognito: true, for a message that is blank once trimmed, and for a message that starts with/. It also answers{ title: null }when the completion times out (15 seconds), the provider returns an error, or no model or credential resolves for the agent. - The model is
modelwhen given, resolved through the same allowlist assessions.patch(past the fast paths above, an unresolvable or disallowed model isINVALID_REQUEST), otherwise the agent’s default model, using that agent’s own credentials.catalogIdis accepted for wire compatibility with upstream and is inert on its own (this fork has no model-catalog create targets);modelandcatalogIdtogether are refused withINVALID_REQUEST, even for a message the fast paths would have answered. - Rate limit: its own control-plane bucket of 3 calls per 60 seconds per
deviceId+clientIp, independent of the shared budget forconfig.apply,config.patchandupdate.run(see Config writes), and not configurable. A call is counted as soon as it passes authorization, before validation and before the fast paths above, so one that answers{ title: null }without a model call still uses budget. The next call in the window is refused withUNAVAILABLE,retryable: true,retryAfterMsanddetails: { method: "sessions.title.prepare", limit: "3 per 60s" }; the message israte limit exceeded for sessions.title.prepare; retry after <seconds>s.
- It answers
agents.list(operator.read; narrow-admitted) rows gainidentity.colorwhen the agent setsagents.list[].identity.colorin config: one ofindigo,violet,pink,rose,amber,lime,tealorsky(see Configuration reference). The key is absent when no colour is configured, and the web client then derives a stable colour from the agent id.agent.identity.getdoes not carry it. Rows also carry the ADR 0121 fields:description(the trimmedagents.list[].description, absent when unset),userFacing(present only asfalse, marking an internal agent), andteam({ id, name?, role: "lead" | "member" }, fromagents.teams[], absent when the agent is in no team). For user clients the row list itself is filtered to user-facing agents, so an internal agent’s row never reaches a narrow connection.
sessions.list sorting, agent activity, and visibility
sessions.list (operator.read) accepts the following request parameters. All are optional.
Transcript enrichment runs against the database with fixed entry windows:
- Titles query the oldest 20 stored entries; previews query the newest 20 stored messages. These are entry limits, not byte caps.
includeInternal is a tristate, not a simple default-false flag:
- Omitted (
undefined) preserves legacy operator behavior and filters only cron run keys recognized byisCronRunSessionKey. falsehides any key for whichisUserFacingSessionKey(key)is false, plus persisted isolated heartbeat sessions. The structural classifier treats the root segmentsacp,cron,hook,heartbeat, andsubagentas internal. It also hidesmain:heartbeat,dashboard:*:heartbeat, and keys matching the persistedheartbeatIsolatedBaseSessionKey. Since ADR 0083’s amendment it also hides rows whose persisted entry records the a2a channel -entry.channelorentry.lastChannelofa2a, assistant-to-assistant sessions - classified from stored entry fields only, never from the key text (ADR 0081). Unknown key shapes remain visible.trueincludes internal cron, ACP, hook, heartbeat, and subagent sessions.
includeAgentActivity is true, the result initializes every agent returned by
listAgentsForGateway(cfg) to null. It then maps each normalized agent id to the newest non-null
updatedAt timestamp among all surviving agent-keyed sessions. Non-agent keys such as global and
unknown are ignored. This aggregation happens before the agentId, spawnedBy, label,
search, activeMinutes, offset, and limit narrowing, so an assistant’s activity does not
disappear merely because the current query or page excludes its newest session.
Activity values are Unix timestamps in milliseconds, or null when no eligible activity exists.
Unless configuredAgentsOnly is true, activity may also contain unconfigured agent IDs found in
surviving session keys.
The operation applies work in this exact order:
- Apply the
includeInternalvisibility rule, then theincludeGlobalandincludeUnknownnon-agent-key filters. - Apply
configuredAgentsOnlyto agent-keyed sessions. - If requested, aggregate
agentActivityacross all surviving agent sessions. - Apply
agentId,spawnedBy,label,search, andactiveMinutesquery filters. - For
sortBy: "title", enrich every unlabelled surviving session before paging. Work runs in batches of 16 (TITLE_ENRICHMENT_BATCH_SIZE) and yields to the event loop between batches. A label becomes the lowercase sort key; otherwise the key is the derived title, thendisplayName, then the session key, lowercased. - Sort the complete filtered set.
updatedAtcompares(a.updatedAt ?? 0) - (b.updatedAt ?? 0), whiletitleandkeyuselocaleCompare; the selected direction multiplies that primary comparison. A zero primary comparison always usesa.key.localeCompare(b.key)in ascending order as the deterministic tie-breaker. - Compute
totalCountbefore paging. - Apply
offsetwithenrichedSessions.slice(offset). - Apply
limitwithenrichedSessions.slice(0, limit). - If
includeDerivedTitlesorincludeLastMessageis true, read transcripts only for rows in the sliced page and add the requested title or preview fields.
ts (server time of the read, epoch ms); limitApplied when the caller
supplied a limit; non-zero offset; nextOffset (or null at the end); and hasMore. count
is the number of rows in the returned page, while totalCount is the filtered count before
offset and limit.
Each row also carries lastReplyAt (optional, number | null): epoch ms of the latest
user-visible assistant reply for that session - a chat final that carried assistant text. The
gateway records it (stampReplyActivity in src/gateway/session-reply-activity.ts) when such a
final is broadcast, when chat.inject appends an assistant message, and when an out-of-band send
mirrors an assistant reply into the session (src/infra/outbound/deliver.ts,
outbound-send-service.ts); the session entry carries the same field. The field is monotonic and
distinct from updatedAt, which other writes such as renames and inbound routing also move. It is
null when the session has had no such reply.
Rows that are not user-facing carry internal: true (GatewaySessionRow.internal): the
structural classifier treats the root segments acp, cron, hook, heartbeat, and subagent
as internal, as do the built-in isolated-heartbeat shapes, persisted isolated-heartbeat sessions,
and rows whose persisted entry records the a2a channel (entry.channel or entry.lastChannel of
a2a). The same rows survive the true value of includeInternal and are hidden by false.
An archived session carries archived: true on its row (archivedAt is not projected; the field
is absent on a live session). Archiving is entry state, not a filter: the projection is
deliberately not paired with a sessions.list filter parameter, so clients filter the rows
themselves. Only sessions.patch { archived: false } clears the flag; a new message and
sessions.reset leave an archived session archived.
Each row also carries agentId (optional, string): the agent the session key is attributed to,
from the key’s agent:<id>: prefix, or the default agent for keys without one (including bare
global and unknown keys). It is attribution, not the store that holds the row, so do not use
it for store routing. Clients must not parse the key to recover the agent (ADR 0081); read this
field instead.
For example, these are complete RPC params objects; they require no imports:
Session-chat broadcast finals
Heartbeat and system-event agent-turn output delivered to the session chat (an explicitwebchat target or a fallback) is appended to the session transcript and broadcast as a
chat final event so live clients see it without re-reading history. These finals
carry a runId prefixed with session-chat- (for example session-chat-<uuid>) and
reuse the standard display pipeline, so they look like any other assistant reply.
chat.inject is unchanged. The final’s message.model is "delivery-mirror", the same model
the appended row stores, so a client can pair the live copy with the raw system reply it
duplicates, as it does for history rows.
Chat event transcript positions
Every transcript entry has a per-session monotonic integer position, itsseq. chat.history
exposes it as __openclaw.seq on every returned row (above). Live frames carry the position of
their run’s user turn, so a client can order the thread from gateway positions instead of
reconstructing it from arrival order:
chatevents (delta,final,error,aborted) andchat.activityevents carry optionalturnSeq: <int ≥ 0>: the transcriptseqof the run’s first user entry.turnSeqis omitted while it is unknown: the user-entry append has not resolved yet, or the run wrote no user entry at all (heartbeat and system-event turns, inline command replies). A client must not hold its first frame waiting for the field.- The existing
seqfield onchatevents is unchanged and keeps its other meaning: a per-run stream counter for frame ordering within one run, not a transcript position. - For a run remapped to a client-supplied run id, the gateway stamps the recorded seq of the client id when it has one and falls back to the source run id otherwise.
Chat deltas (deltaText/replace)
Every chat delta carries deltaText: the text added since the previous broadcast delta of
the run (a run’s first delta carries the full text). When the new assistant text is not an
extension of the already-streamed prefix (a restart or rewrite), the delta resends the full
text with replace: true — “replace the streamed prefix with this text”; otherwise replace
is absent and the client appends. The cumulative message field stays on every delta for
clients that have not switched to deltaText. Under protocol 4 (ADR 2691) the flat chat
event becomes a per-state union whose delta arm requires deltaText, and a clearing delta is
{ deltaText: "", replace: true }.
Chat run origin
chat events (delta, final, error, aborted) of a run started from a device carry optional
origin: { deviceId, clientId }: the device.id and client.id of the connection that started
the run with chat.send, sessions.steer, a talk session turn or agent, or of the node that sent
voice.transcript. A client compares
origin.deviceId with its own device id to recognise replies to its own turns. The field is absent
when the starting connection presented no device identity, and for runs the gateway started itself
(heartbeat, cron, channel inbound). A replayed idempotency key never re-tags a run.
The inverse marking is trigger: chat events (delta, final, error, aborted) of a
system-origin run carry optional trigger: "heartbeat" | "cron" | "subagent" | "acp", the same
values chat.history projects as __openclaw.trigger. It comes from the run’s registered
context, never from session-key text (ADR 0081): heartbeat and cron from the reply run’s
trigger, subagent from the spawn-declared subagent lane on the agent request, and acp from
the ACP control-plane turn. A person typing into a child session starts an untagged user run. A
client can hide the live system turn by provenance: its deltas, reasoning and aborted partial are
internal, and its final is the run’s user-facing result unless a delivery-mirror final follows.
A role: "node" connection receives chat, chat.activity and agent events only for sessions
it subscribed to with node.event chat.subscribe; the operator broadcast of those events never
reaches it. Subscriptions match on the canonical session key, so subscribing to main delivers
frames whose sessionKey is agent:main:main. A chat.subscribe naming a session the node may not
see (another person’s, or any person’s for a node with no linked person) is answered
INVALID_REQUEST with details.reason: "session_not_found" and subscribes nothing.
Suppressed finals and the clearing delta
Afinal or aborted chat event with no message means the run’s reply was suppressed (a
NO_REPLY or HEARTBEAT_OK sentinel, or a display transform that rewrote it into one) or was
empty: nothing renders. This matches upstream protocol v4; there is no silent field.
- When the suppressed message had already offered text in deltas, a zero-text delta arrives in
session order right before the terminal:
state: "delta",message.content: [{ type: "text", text: "" }], and the sameseq,turnSeq,triggerandoriginas the terminal. It means “retract this message’s streamed text”, and it is never dropped under backpressure. Anerrorterminal never clears. - The clearing delta retracts the run’s latest message on the client. That is always the suppressed one: a message’s first delta is never dropped under backpressure either (later deltas of the same message may be), so a client has seen every message a clear can target.
- No clearing delta is sent when the suppressed message’s first shown text repeats, extends or
(ignoring surrounding whitespace) equals the shown text of the run’s previous message (for example, the same sentence again after a tool
step). v3 deltas start a new message only when the text stops extending the last one, so a
client renders both messages as one bubble, and a retraction would remove the earlier message
too. That text stays visible. A previous message that offered nothing (a held
No) protects nothing, so the clear is sent as usual. - An aborted partial uses the deltas’ sentinel view: a trailing lead fragment such as
NO_REand standalone edge sentinel lines are removed, and a sentinel-only partial ships with nomessage. hello-ok.features.capabilitiescontains"chat.final.silent"when the gateway guarantees the clearing delta. With it, a client may render deltas immediately and retract on the clearing delta. Without it (older gateways), a client keeps holding sentinel-prefix text and ignores a zero-text delta.- The capability is WednesdayAI-only and protocol-v3-only. Protocol v4 adoption retires it and
adds upstream’s
deltaText: ""andreplace: trueto the clearing delta.
The chat error event
A dispatched turn that fails without an assistant reply ends with achat broadcast event
carrying state: "error": { runId, sessionKey, seq, state: "error", errorMessage, turnSeq? }. seq
continues the per-run sequence the other chat events for that run use, turnSeq follows the
transcript position rule, and the event reaches
operator subscriptions and node sessions the same way the final event does. chat.send answers
started immediately, so this event is the only signal a failed turn gives the requesting client;
the run disappears from the active-run tracking and chat.history gains no assistant message.
errorMessage is user-facing where a reason exists: a workspace-lane denial (below) puts its
message here verbatim, and an unlinked device sees its own device:<id> in the text.
The runs.invalidated event
runs.invalidated tells a subscribed client that something it may be showing has changed. It
carries identity only, never content: no payload, no access or privacy context, no scope key, no
error text. Delivery requires operator.read, the same bar as the read methods it invalidates, so
a node-role connection and an operator connection without a read scope never receive it.
The payload is a strict discriminated union on scope. Each shape is closed: an unknown field
makes it match nothing.
- Every event is emitted after the transition is persisted. Re-query the matching read method
the instant an event lands and you see the new state: a
taskevent reports thestatusandupdatedAtthattasks.runs.getalready returns, and asessionevent reports whatsessions.runs.getalready returns. workIdis the raw bus-work id, the same valuetasks.runs.listreports, never the internal claim handle.state: "queued"follows an enqueue that really inserted a row (an idempotent enqueue that inserts nothing emits nothing) and a released claim.state: "removed"follows the claim that co-commits the task run.- Only registered task topics (
task.<pass id>) produceworkevents. Arbitrary bus work never does, in either direction. - Delivery is best effort. There is no replay, no per-client buffering and no ordering guarantee between scopes, and a client that is not connected misses the event entirely.
Reconciling a client view
Correctness never depends on receiving an event. Treatruns.invalidated purely as a hint to
refresh:
- On an event, re-query the view it touches:
tasks.runs.listforwork,tasks.runs.getortasks.runs.listfortask,sessions.runs.getorsessions.runs.listforsession. Ataskevent can also change queued membership, so a client showing both views refreshes both. - On reconnect, re-query before trusting anything cached. A run that reached a terminal state
while the socket was down is read back in full from
sessions.runs.get/tasks.runs.get. - Keep a bounded periodic refresh (a slow poll of the visible page, not a tight loop) as the backstop for a dropped event. Keyset pages stay stable for rows whose membership is unchanged, so a refresh at the current cursor is cheap.
Agent one-shot and session-effect fields
agent (operator.write) accepts four additive, optional fields that control how much of a turn
becomes durable. All four are strict: an unknown value is rejected, never accepted and ignored.
The full rationale lives in the repo at dev-docs/adr/0073-client-contract-rpc-additions.md.
promptModepicks how much of the assembled system prompt the turn gets.fullis the default for a normal session key,minimaldrops the conversational sections (reply tags, silent replies, heartbeats, voice, docs, model aliases, user identity), andnonesends the bare identity line with no sections at all. Omitting it keeps today’s behavior, where the mode is derived from the session key (subagent keys already runminimal).promptMode: "none"requiresmodelRun: true. Without it the call is rejected withINVALID_REQUESTanddetails.reason = "prompt_mode_none_requires_model_run", because a raw prompt must not be able to mutate a durable session.modelRun: trueis a one-shot run. It reads the session’s history but writes nothing back: the transcript and the session store are byte-identical afterwards, nosessions.changedis emitted, nochatevents are broadcast, and nothing is delivered. It is allowed foroperator.writebecause it is strictly less effectful than a normal turn.sessionEffectsdefaults tovisible(today’s behavior).internalruns the turn with no user-visible session side effect: no outbound delivery, nosessions.changed, nochatevents to other subscribers, and no change to the stored session row (updatedAt, tokens, model). The prompt message is not persisted, but the assistant reply is, so the session can resume. The transcript-derived fieldslastMessagePreviewandderivedTitlefollow that persisted reply; they are read from the transcript, not stored on the row.suppressPromptPersistence: trueruns the turn without writing the prompt (user) message to the transcript. The assistant reply is persisted as usual unlesssessionEffectsisinternal.modelRun: truewithsessionEffects: "visible"is rejected (details.reason = "model_run_requires_internal_session_effects"); a one-shot run is internal by definition.sessionEffects: "internal"orsuppressPromptPersistence: truefrom a connection withoutoperator.adminis rejected withINVALID_REQUESTanddetails.reason = "internal_session_effects_reserved", and no run is started. Declaring clientmode: "backend"does not help: client mode is self-asserted on the connect frame, so the scope is the authority.- Any of these combined with
deliver: trueis rejected withdetails.reason = "delivery_not_allowed_for_internal_session_effects"rather than silently dropping the delivery. - CLI-backed providers own their own transcript, so a turn that would need one of these suppressions on a CLI provider fails the run instead of persisting anyway.
Agent identity inheritance and lane denials
agent accepts two more additive, optional params: inheritedCanonicalIdentity and
inheritedSenderId. They carry the requester identity of in-process callers that run on behalf of
a person: sessions_send, subagent announces, and Discord voice. They are trusted assertions, not
authenticated data — any operator.write caller may set them, and the only validation is a match
against session.identityLinks keys. Never accept them from a narrow-scope end-user client.
On a lane-enabled agent (agents.list[].workspaceLanes.enabled), a run that cannot be attributed
to a linked identity is rejected before the run starts:
-
The error frame carries
code: "UNAVAILABLE", the user-facing denial asmessage, anddetails.reason: "workspace_lane_denied". Example denial on acanonical-identityagent: -
The second
resframe (same request id) carries{ runId, status: "error", summary: <denial> }. -
A terminal lifecycle event for the
runId(phase: "error",retryable: false) is emitted even though no run started, soagent.waitends withstatus: "error"and the denial instead of timing out. Internal runs (ADR 0073sessionEffects: "internal") emit no lifecycle events and are not covered. - Nothing is written: no transcript entries, no session-store update, no delivery.
details.reason with gatewayErrorReason(err) (src/gateway/client.ts) instead of matching
the message text. The CLI agent command treats this marker as final and does not fall back to an
embedded run. The device sender, lane keys, and the denial behavior of every path are documented
in Workspace Lanes.
Talk sessions
talk.session.* (operator.write; narrow-admitted) and talk.catalog (operator.read;
narrow-admitted) are the cascaded Dictate and Voice surface. talk.metrics is operator.read
and is not narrow-admitted. Unknown fields are rejected. A call for a session this connection
does not own is INVALID_REQUEST.
talk.event frames on the wire are {type, sessionId, seq, turnId?, final?, payload?}. payload
is omitted when it is empty, including turn.started, turn.ended, and session.ready.
Turn-scoped types always carry turnId. Do not treat a missing payload as a zero-filled object.
talk.session.create
Params (all required except provider):
readMode and speed apply to stt-tts sessions only: they override the speech read mode
derived from messages.tts.naturalize (literal/human/hybrid) and the synthesis speed for
this session. See Read modes.
brain stays "none" on this method. Voice still runs an agent turn; that pairing is handler
logic, not a second enum value on create.
Result: {sessionId, audio: {inputEncoding: "pcm16", inputSampleRateHz, channels: 1}}.
inputSampleRateHz is 16000 for transcription and stt-tts, and 24000 for realtime;
capture at the advertised rate. The response is written before session.ready. appendAudio
for a session that has not readied is rejected with Talk session is not ready for audio, so
clients must buffer captured audio until the session’s session.ready talk.event and flush it
in capture order then. Input is base64 PCM16 mono. Output audio events
are PCM16 mono at 24 kHz.
Gate and provider errors are UNAVAILABLE:
voice conversation disabled— gate off, for everystt-ttscaller and for every narrow caller, and for everyrealtimecaller.realtime voice conversation disabled—mode: "realtime"whiletalk.conversation.engineis not"realtime", for every caller.stt-tts requires a configured STT and TTS provider— Voice has no registered streaming transcription and streaming speech provider pair for the configuration.stt-tts requires a configured STT and TTS provider: <transcription|speech> provider "<id>" is not configured; check talk.providers.<id>.apiKey— the pair is registered, but the named provider’s key is missing or does not resolve.stt-tts requires talk.providers.<id>.voiceId: speech provider "<id>" has no default voice— both keys resolved, the config sets novoiceId, and the speech provider declares nodefaultVoiceId. A missing key is reported before a missing voice.
providerConfig.commitStrategy: "vad" and
providerConfig.endOfTurnSilenceMs from talk.conversation.endOfTurnSilenceMs. Keys already set
on talk.providers.<id> win. Dictate does not inject those defaults.
mode: "realtime" (ADR 0103) runs speech-to-speech through the auto-selected talk realtime
provider (talk.catalog realtime.activeProvider) over the gateway relay, bound to sessionKey.
The realtime model speaks with the realtime provider’s own voice; neither messages.tts nor the
cascaded talk.providers.<id> TTS settings apply. A provider resolution failure is UNAVAILABLE
with the provider’s message. The model is seeded with
recent session history and reaches tools only through the agent consult, which is read-only for
narrow callers. The session is driven only by the talk.session.* methods; talk.realtime.* calls
on it are rejected, and its owner receives talk.event frames only. A session chat.send would
refuse for this connection (send blocked by session policy) is refused here too, and an empty
sessionKey is INVALID_REQUEST. Each final user utterance is written to the session. An
assistant reply is written once its audio has played; a reply interrupted by barge-in is written
as [interrupted] only. A consult emits tool.call {name: "openclaw_agent_consult"} with no
arguments. A talk.session.bargeIn the provider rejects (below its acknowledged-playback
floor) emits no output.audio.cleared; the relay answers with output.audio.resumed {markName} instead, so the client un-pauses the playback it suspended on detection.
Speech marks are rt-<n>: attach each once at output.audio.done and acknowledge it
with talk.session.mark when its audio has played, using a playback timestamp that never
decreases within the session (unlike stt-tts per-turn offsets).
talk.session.appendAudio, close, cancelTurn
appendAudio is INVALID_REQUEST when the base64 text is longer than 512 KiB, is not canonical
base64, or decodes to an odd byte count (PCM16 samples are 2 bytes). close answers before the
drain emits terminal events for transcription and stt-tts sessions. On an stt-tts session
an explicit close detaches the active turn: no turn.cancelled and no [interrupted] write.
Speech stops, the agent run finishes, its full reply is written once when the run ends, and
transcript.persisted follows the write (it may arrive after session.closed, whose reason
stays completed). A chat delete or reset cancels the active turn instead, and a client socket
drop still cancels with reason cancelled. A session-bound realtime
session’s close resolves after its drain: the session retires and audio stops at once, but
transcript admission stays open while the commit queue settles (bounded by the 3 s user-settle
window plus a 2 s commit grace), then the provider closes and the RPC resolves.
talk.session.mark
Params: sessionId (string, min length 1), markName (string, min length 1), timestamp
(number, minimum 0). Result: {}.
For stt-tts speech marks, timestamp is milliseconds of audio played for that turn, 0 at the
turn’s first speech sample — the same domain as the alignment timeline. It is not
performance.now(), and it is not the realtime relay’s media clock. A performance.now() value
is past every alignment entry, so a mid-turn ack would persist text whose audio was still
buffered. Attach the speech mark when the chunk is enqueued and report the offset when that
chunk’s playback barrier is reached. A mark sent after turn.ended is too late: the relay has
retired the turn. Barge-in timestamps below stay on the performance.now() clock and must not be
mixed with mark timestamps.
talk.session.bargeIn
Params: sessionId (string, min length 1), speechDetectedAt? (number, minimum 0),
playbackPausedAt? (number, minimum 0). Result: {}. Both timestamps are client-local monotonic
milliseconds (performance.now()). When both are present, playbackPausedAt - speechDetectedAt
must be in [0, 10000] or the call is INVALID_REQUEST. Omitting either is accepted and the
stop-latency sample is unmeasured. The call is a no-op when the session is idle or the active turn
has not yet played reply speech. Server handling does not arm on filler or ack; the web client
arms its detector only while kind: "speech" is playing.
talk.session.update
Params: sessionId (string, min length 1), readMode? ("literal" | "human" | "hybrid"),
speed? (number, 0.75-2). Result: {}. ADR 0122 amendment: a mid-session synthesis-settings
change for a live stt-tts session. Send only what changed; a speed of 1 is meaningful (it
overrides a previously set non-1 speed). The change applies from the session’s next synthesised
clause - the open TTS stream is not reopened but receives the new speed live (providers honour it
for clauses whose synthesis has not started; the clause in flight is not restarted), and a
one-shot filler/ack synthesised at the old speed is re-synthesised at the new one (the filler/ack
cache keys on speed). The
readMode is re-resolved against the session’s voice agent exactly as talk.session.create
resolves it. An unknown sessionId, or a session the connection does not own, fails with the
same INVALID_REQUEST error talk.session.mark/talk.session.bargeIn produce; a
transcription or session-bound realtime session fails with INVALID_REQUEST
(talk.session.update is only supported for stt-tts sessions), the established
unsupported-mode pattern.
talk.event types
Canonical names, in order: session.started, session.ready, session.closed, session.error,
session.replaced, turn.started, turn.ended, turn.cancelled, capture.started,
capture.stopped, capture.cancelled, capture.once, input.audio.delta,
input.audio.committed, transcript.delta, transcript.done, output.text.delta,
output.text.done, transcript.persisted, output.audio.started, output.audio.delta,
output.audio.done, output.audio.resumed, output.audio.cleared, tool.call,
tool.progress, tool.result, tool.error, usage.metrics, latency.metrics,
health.changed.
transcript.delta payload.text is the cumulative text of the in-progress segment. Replace the
stored caption; do not append.
transcript.persisted arrives after that utterance was written to the session; reload the thread
on it. It never carries the text. A realtime frame is {role: "user" | "assistant"} with no
turnId. Cascaded stt-tts sessions also emit the event, for the assistant write only, as
{turnId, payload: {role: "assistant"}} where turnId matches that turn’s turn.started. It is
the completion barrier for that turn’s assistant write: it follows a natural finish, an
explicit-close detach (the run’s full reply), or a cancelled turn’s heard-prefix write, including
a cancel that heard nothing, which writes no row and still announces. It is not sent when the
write throws, nor for a turn cancelled while still queued (only the user’s fragment is written),
and it may arrive after session.closed.
output.audio.started, output.audio.delta, and output.audio.done carry markName and
kind ("speech", "filler", or "ack"). output.audio.delta also carries audioBase64,
sampleRateHz (24000), and sequence (1-based, monotonic per markName). Filler and ack do
not count toward stopToFirstAudioMs. output.audio.resumed is {markName} only — a resume
continues the in-flight speech stream. output.audio.cleared is {markName, reason: "barge-in"}.
turn.started and turn.ended have an empty payload. turn.ended means the TTS stream drained.
It does not mean the session entry or the transcript has been written. Those writes land after
the event and are not awaited, so a disk write cannot block the next turn. Wait for the chat
final event, or poll chat.history, before reading the turn back; a voice turn’s
transcript.persisted marks the same completion. A confirmed barge-in persists
only the heard prefix plus an [interrupted] marker; zero heard characters append no assistant
message, and that turn’s transcript.persisted still follows. On the JSONL backend the rewrite
truncates the file and writes the loaded transcript back, so earlier entries stay.
turn.cancelled payload is {reason}. Reasons you must handle include client-cancelled (the
cancel RPC), agent-error (the agent run failed to start; the turn is cancelled rather than left
open), tts-stall (the speech stream sat silent for 30 seconds after end(), or a ready or
backpressure promise stayed unsettled that long; audio that is still arriving resets that wait;
waiting on the model is not a stall), tts-error, barge-in, turn-resumed, and the session
close reasons below when they cancel the active turn. session-closed now comes only from relay
expiry (the session TTL or the prune sweep), where the close reason is completed; an explicit
talk.session.close detaches the active turn instead of cancelling it, and a socket drop cancels
with reason cancelled.
session.ready is emitted once: for stt-tts, when the first STT connect succeeds (including
the one allowed reconnect after an initial connect failure); for a realtime session, when the
provider bridge signals ready. A later reconnect of an already-ready session
does not emit session.ready again. A second STT fault emits session.error (empty payload) and
then session.closed. For stt-tts, session.closed payload is
{reason: "completed" | "error" | "cancelled" | "session-minutes-exceeded" | "turn-seconds-exceeded"}.
Other session kinds still omit an empty session.closed payload.
latency.metrics payload: turnId, provider: {stt, tts}, optional stage fields
endOfTurnMs, preModelMs, modelFirstTokenMs, ttsFirstByteMs, gatewayAddedMs,
stopToFirstAudioMs, bargeInStopMs (each a number, minimum 0; omitted, never a fabricated 0,
when the turn did not reach that stage), and booleans recallDeadlineExceeded, fillerPlayed,
toolAckPlayed.
talk.catalog
Params: {}. Result fields: required transcription (activeProvider string or null, rows,
and providers — the same rows: {id, label, configured, modes: ["transcription"], transports: ["gateway-relay"], brains: ["none"]}), optional streamingTranscription, speech,
realtime, conversationEnabled, and conversationEngine ("stt-tts" or "realtime", the
resolved talk.conversation.engine). Streaming transcription and speech rows are
{id, label, configured, diagnostic?, modes, transports} plus brains: ["agent-consult"] on
streaming transcription only. modes is ["streaming"]. transports is ["gateway-relay"].
diagnostic, present only when configured is false and a cause is known, is
"missing-api-key", "secret-ref-unresolved", "provider-error", or, on a speech row whose
config sets no voiceId and whose provider declares no defaultVoiceId, "missing-voice-id".
Realtime rows use
modes: ["realtime"] and transports of "provider-websocket" and/or "webrtc". The catalog
never includes a secret.
talk.metrics
Params: {}. Not narrow-admitted (missing scope: operator.read). Result:
p50 and p95 use the same optional stage fields as latency.metrics, including
bargeInStopMs. falseInterruptionRate is falseInterruptions / (falseInterruptions + confirmedInterruptions)
and is omitted when that denominator is 0. The window is 500 turns per provider pair, in memory
only. The same samples are the talk.turn.timing diagnostic event. With the diagnostics OpenTelemetry
plugin enabled they export as openclaw.talk.turn.end_of_turn_ms, pre_model_ms,
model_first_token_ms, tts_first_byte_ms, gateway_added_ms, stop_to_first_audio_ms, and
barge_in_stop_ms histograms, plus counters openclaw.talk.turn.false_interruption,
confirmed_interruption, and interruption_candidate.
TTS read aloud
Two RPCs back the web client Read aloud control (ADR 0102). Both resolve the TTS config foragentId when given, otherwise for the default agent; an unknown agentId silently falls back to
the global messages.tts config. Both are narrow-admitted (above), and neither is rate limited:
maxTextLength caps every call and chunked playback issues several calls back to back. TTS config
changes need a gateway restart.
tts.speak
operator.write; admitted to a narrow operator.sessions.write.
Params (all required except agentId; additionalProperties: false):
readMode overrides the speech read mode derived from messages.tts.naturalize for this request
and speed sets a provider-native synthesis speed multiplier; see
Read modes.
Result: {audioBase64, mimeType, provider, outputFormat} — one clip of inline base64 audio,
synthesized with the agent’s resolved TTS config. The clip is capped at 16 MiB raw bytes (about
21.3 MiB as base64) to stay inside the 25 MiB WS frame cap.
Errors:
INVALID_REQUESTtts.speak requires text—textis empty once trimmed.UNAVAILABLEread aloud is disabled for this assistantwithdetails.reason = "read_aloud_disabled"— themessages.tts.readAloud.enabledgate (default true, per-agent overridable) is off. No synthesis runs.INVALID_REQUESTtts.speak text too long (N chars, max M)withdetails.reason = "text_too_long"anddetails.maxTextLength—textexceeds the resolvedmaxTextLength(default 4096).UNAVAILABLEwith the provider error, absolute filesystem paths stripped — synthesis failed.UNAVAILABLEunsupported audio format "<ext>"withdetails.reason = "unsupported_audio_format"— the provider emitted an extension outside the mime map (mp3,opus,ogg,webm,wav).UNAVAILABLEsynthesized audio too large to return inline (N bytes, max M)withdetails.reason = "audio_too_large"— the clip exceeds the 16 MiB inline cap.
tts.readAloud.status
operator.read; admitted to a narrow operator.sessions.read.
Params: {agentId?} (string, min length 1; additionalProperties: false). Result:
{enabled, maxTextLength} with maxTextLength an integer of at least 1. enabled is true only
when the read-aloud gate is on and at least one provider in the resolved provider order is
configured; it reports gate state only, never a secret. A handler failure is UNAVAILABLE.
Exec approvals
- When an exec request needs approval, the gateway broadcasts
exec.approval.requested. - Operator clients resolve by calling
exec.approval.resolve(requiresoperator.approvalsscope). - For
host=node,exec.approval.requestmust includesystemRunPlan(canonicalargv/cwd/rawCommand/session metadata). Requests missingsystemRunPlanare rejected.
Versioning
PROTOCOL_VERSIONlives insrc/gateway/protocol/schema/protocol-schemas.tsand is exported fromsrc/gateway/protocol/schema.ts.- Clients send
minProtocol+maxProtocol; the server rejects mismatches. - Core generates the JSON Schema snapshot from the TypeBox definitions and commits it at
src/gateway/protocol/gateway-protocol.schema.json(pnpm protocol:checkguards it); the schema root carriesx-protocol-versionandx-error-codes, and reused definitions carryx-schema-name. The npm tarball ships it atdist/contracts/gateway-protocol.schema.json, with the exec and system-run parity fixtures underdist/contracts/fixtures/for the native clients’ parity tests. pnpm protocol:genalso writes the protocol-4 preview next to the live snapshot:src/gateway/protocol/gateway-protocol.v4.schema.json, shipped asdist/contracts/gateway-protocol.v4.schema.json. It is the target registry of the protocol-4 cut (ADR 2691) —x-protocol-version: 4,ChatEventas the per-state union (ChatDeltaEvent/ChatFinalEvent/ChatAbortedEvent/ChatErrorEvent),hello-okwithpluginSurfaceUrlsonly, andnode.pluginSurface.refreshparams — published so client generators (P2) build and test against the final shape before the cut. The live wire protocol stays version 3 until the cut.- Deprecated at protocol 3, removed for protocol 4 sessions (ADR 2691):
hello-ok.canvasHostUrl(→pluginSurfaceUrls.canvas),node.canvas.capability.refresh(→node.pluginSurface.refresh), and the flatchatevent members — the flat shape becomes the per-state union above. Legacy v3 node sessions (admitted underMIN_NODE_PROTOCOL_VERSION = 3) keepcanvasHostUrlandnode.canvas.capability.refreshuntil that floor rises to 4. - Swift models are generated in the
WednesdayAI-apps repository from the synced
snapshot (
npm run contracts:sync).
Auth
- If
OPENCLAW_GATEWAY_TOKEN(or--token) is set,connect.params.auth.tokenmust match or the socket is closed. - After pairing, the Gateway issues a device token scoped to the connection
role + scopes. It is returned in
hello-ok.auth.deviceTokenand should be persisted by the client for future connects. - Device tokens can be rotated/revoked via
device.token.rotateanddevice.token.revoke(requiresoperator.pairingscope). - Revocation takes effect on live sockets, not only on the next connect.
device.token.revokecloses the device’s open sockets that hold the revoked role.device.pair.remove,device.identity.unlinkandidentity.logoutclose every open socket of the device and of its companions. Each closes with code1008.
Device identity + pairing
-
Nodes should include a stable device identity (
device.id) derived from a keypair fingerprint. - Gateways issue tokens per device + role.
- Pairing approvals are required for new device IDs unless local auto-approval is enabled.
- Local connects include loopback and the gateway host’s own tailnet address (so same‑host tailnet binds can still auto‑approve).
-
All WS clients must include
deviceidentity duringconnect(operator + node). Control UI can omit it only whengateway.controlUi.dangerouslyDisableDeviceAuthis enabled for break-glass use. -
All connections must sign the server-provided
connect.challengenonce. -
A device’s person is
ownerPersonon its pairing record, managed by operators:device.identity.link({deviceId}+{identity}→{deviceId, identity, changed}) anddevice.identity.unlink({deviceId}→{deviceId, unlinkedFrom, deregistered}) both requireoperator.admin, because linking grants a person’s identity. The owner is set once, in one pairing-store transaction; the same person again answerschanged: false. Device ids match case-insensitively (responses carry the canonical lowercase id). Only deregistration clears an owner: unlinking a paired device is the same asdevice.pair.remove(record, tokens and owner removed in one transaction;deregistered: true), and both answer before the device’s connections close, so a caller removing its own device still gets its response.device.pair.listanddevice.pair.approveitems (operator.pairing) carry the stored owner asownerPersonand, while it is still a configured person, asidentity;device.pair.removereports it inunlinkedFrom. Re-pair approvals keep the owner. The paired-device methods themselves stayoperator.pairing; link and unlink from the CLI withwednesdayai devices link/wednesdayai devices unlink(see devices).session.identityLinksholds channel identities only:device:values there confer nothing, are moved onto their records (a device listed under several people goes to the first) and stripped at gateway startup, andidentity.link/identity.unlinkrefuse them.config.set,config.patchandconfig.applyrefuse a write that adds one withdetails.code = DEVICE_LINK_VALUE_REFUSED(plusdetails.deviceId). Device-link refusals carrydetails.reason: -
Before a handshake registers its socket, it re-checks in the session database that the
device’s record still exists with the owner and role token it saw (bounded by the handshake
deadline). Every deregistration (remove, unlink, logout, prune, supersede) first revokes the
device’s connections, so one committing after the re-check is refused at registration or closes
the socket. A device admitted through pairing whose record vanished before its token was issued
is refused too. Refusals carry
details.code = device_deregistered(or close the socket withdevice revoked); a re-check read that fails closes it with code 1011. A client whose device token is rejected drops only its local token; the gateway’s record and owner are untouched. -
Paired records carry lifecycle fields:
device.pair.listitems addfirstRegisteredAtMs(set once, kept across re-pairing),lastActiveAtMs(latest of last activity, token use, approval and registration),connected,stale(inactive longer thangateway.devices.staleAfterDays, never while connected) andsupersedes(ids of older records this enrolment replaces).node.listpaired entries addfirstRegisteredAtMs,lastActiveAtMsandstale. -
device.pair.prune(operator.pairing), params{stale?, superseded?, neverUsed?, dryRun?}: at least one ofstale,supersededorneverUsedmust betrue. Runs are serialized per gateway process, so two prune requests never interleave one run’s selection with another run’s archive. It revokes every token of each selected record, archives it in the session database pairing archive tables (token secrets dropped), removes it, and unlinks its identity. Connected records are never selected and are listed underskippedConnected. A record selected by any selector of the run appears exactly once — indevices, never also inkept— and a record whose replacement the same run archives is kept instead (across all selectors). Companion records cascade with their primary, so they count as removed, never as a person’s survivor. WithneverUsed: true, candidates (nolastActiveAtMs, no tokenlastUsedAtMs) older thangateway.devices.neverUsedAfterDaysare selected only when they are not connected, hold no node role (role, roles or node token), hold no companions, are not a companion of another record, have no accessories and are not their person’s only device; the full check re-runs against the locked pairing snapshot inside the archive transaction, and a run never takes a person’s last device (the most recently approved selection survives). Every paired record considered is listed either as selected or underkept: [{deviceId, keptBecause}]with the first failing check (used,node-role,recent,connected,token-used,has-companions,companion,has-accessories,only-device-of-owner). Response:{dryRun, staleAfterDays, devices: [{deviceId, displayName?, reason, supersededBy?, firstRegisteredAtMs, approvedAtMs, lastActiveAtMs, revokedRoles, unlinkedFrom}], kept?, nodes: [{nodeId, displayName?, firstRegisteredAtMs, lastActiveAtMs}], skippedConnected}withreasonstale,supersededornever-used.dryRun: truewrites nothing. -
device.bootstrap.issue(operator.admin): issue a bootstrap enrolment token for a setup code. Params{profile: {roles, scopes}, identity?, codeChallenge?}; result{token, setupId, expiresAtMs}.wednesdayai qrcalls this method when a gateway owns storage and issues the token locally from the session database otherwise. -
Re-enrolment supersede (ADR 0116 D8 pattern): when a bootstrap redemption bound to a person
pairs a new device whose
client.idandclient.modelIdentifiermatch older, disconnected records linked to the same person,hello-ok.auth.supersedeCandidateslists them ([{deviceId, displayName?, firstRegisteredAtMs, lastActiveAtMs}]) and the new record’ssupersedesflags them for operators. The person confirms withdevice.supersede(operator.write), params{deviceId}→{deviceId, supersededBy, unlinkedFrom}, called from the new device. It failsINVALID_REQUESTwithdetails.reasondevice_identity_required,device_unpaired,identity_unlinkedornot_supersedable(never naming another person’s device). Clients that send nomodelIdentifiernever receive candidates. Only a strictly later registration (firstRegisteredAtMs) supersedes, so two records never replace each other; re-pairing a device clears every other record’s flag on it. The ownership check ofdevice.supersedeis re-run by the store’s revision-checked archive transaction, so a device deregistered (or re-paired) meanwhile failsnot_supersedable. The archived record keeps its owner.device.pair.prune {superseded}never archives a record whose replacement it is also archiving.
Device auth migration diagnostics
For legacy clients that still use pre-challenge signing behavior,connect now returns
DEVICE_AUTH_* detail codes under error.details.code with a stable error.details.reason.
Common migration failures:
Migration target:
- Always wait for
connect.challenge. - Sign the v2 payload that includes the server nonce.
- Send the same nonce in
connect.params.device.nonce. - Preferred signature payload is
v3, which bindsplatformanddeviceFamilyin addition to device/client/role/scopes/token/nonce fields. - Legacy
v2signatures remain accepted for compatibility, but paired-device metadata pinning still controls command policy on reconnect.
Device companions and device.self
ADR 2242 D1 lets a signed-in WednesdayAI app device hand the person’s browser a credential tied to itself. Both methods take{} and read the device id from the verified connection.
device.companion.issueanswers only a device enrolled by an app-profile bootstrap (wednesdayai-glass-node; renaming the client id on a later connect does not count), connected as that client, with a live operator token and a linked person. It mints anopenclaw-user-clientsetup code for that person; the redeemed device recordscompanionOf: <app deviceId>. Refusals carryerror.details.reason:device_companion_forbidden(not a signed-in app device) ordevice_companion_person_required(no linked person).device.companion.adopttakes{bootstrapToken}and is answered on an already-pairedopenclaw-user-clientconnection: the calling record becomes the code’s app’s companion in place (same device id, no new enrollment, no token, role or scope change) when its owner, the code’s person and the connection’s person are all the same and the app is still live. The code is consumed either way a grant is made; refusals write nothing and carryerror.details.reason:companion_code_invalid(unknown, expired, consumed, not a companion code, or the app is gone) orcompanion_adopt_refused(unknown device, not a user-client record, or the record, code and connection are not the same person).device.selfreturns the caller asself(relation: "self") and, inlinked, its app device (relation: "primary") or its companions (relation: "companion"), only when they are linked to the caller’s own person. Each entry carriesdeviceId,online(a live node connection), sortedcapsandcommandsfrom that connection, optionalclientId,displayName,platform,deviceFamily, andglassState({payload, receivedAtMs}, the last successfulglass.state.getresult on the live connection).- Removing, revoking a token of, re-linking (
device.identity.link), unlinking (device.identity.unlink, oridentity.unlink device:<id>), logging out, re-bootstrapping or archiving (device.pair.prune,device.supersede) the app device removes its companions, their pending setup codes and their person links. Removing, revoking, re-bootstrapping and archiving the app revoke every companion credential in the same pairing-store write; the rows and person links are cleaned up right after. A refused re-link removes nothing. If the cleanup fails, the admin methods answerUNAVAILABLEand a retry repeats it; until then the revoked companion stays listed. Removing a companion alone leaves the app intact.device.identity.linkrefuses to move a companion to another person (device_companion_person_mismatch). - A companion connects (under every auth mode) and passes a device-token check (
/v2/uploads) only while its own credential is unrevoked, its app is paired with a live operator token, and both are linked to the person the companion was issued for. A revoked companion credential is re-minted only by a fresh companion setup code. Open sockets are not closed by revocation; the companion is refused on its next connect. openclaw devices listshows a companion as<name> (companion of <app name>).
Device accessories (device.accessory.attach/detach/list)
ADR 2242 D4: a signed-in app device vouches for credential-less accessories (glasses, watch,
earbuds, ring). An accessory is a record under the app device — no credential, no pairing step of
its own — and traffic rides the app’s sockets, tagged with accessoryId on the request frame.
attachparams are{accessoryId, kind, model?}(accessoryId≤ 128 chars;modelis free text for display only, ≤ 128 chars).kindmust be one of the closedACCESSORY_PROFILESkinds; the caller never supplies a profile. Re-attaching an existingaccessoryIdupdates kind and model to the given values and does not count against the limit.- The profile is gateway-owned per kind:
glassesgrants commandsglass.*,glass.tool.*and scopesoperator.read,operator.write,operator.approvals;watchno commands, the same three scopes;earbudsno commands,operator.read,operator.write;ringno commands,operator.readonly. At most 8 accessories per app device. A kind with commands in its profile grants its node-command family on the device’s live node session (plan C3): attach and detach re-derive the session’s allowed commands from the node’s declared list without a reconnect, andgateway.nodes.denyCommandsstill wins over any accessory grant. - The
accessory:<kind>node connect caps (accessory:g2,accessory:glasses,accessory:watch,accessory:earbuds,accessory:ring) are a deprecated one-release alias for an attached accessory: at node connect the gateway maps each cap to its kind, auto-attaches an accessory with idcap:<kind>(idempotent; a re-attach refresheslastSeenAtMs) on the verified paired device, and logs the deprecation once per device. A limit refusal is logged and never fails the handshake, and a node without a paired device (shared token) keeps its grant from the cap kinds directly. Detaching thecap:<kind>row revokes the grant until the next connect re-attaches it; thecap:accessory-id prefix is reserved for the gateway’s auto-attachments. - Only the app manages accessories: the caller must carry a verified device id, be connected as
the app-profile client it enrolled with (
bootstrapClientIddecides, never a relabelled client id) and hold a live operator token. Every refusal carrieserror.details.reason:accessory_forbidden(not a signed-in app device),accessory_kind_unknown,accessory_id_invalid,accessory_limit(the 9th accessory),accessory_not_attached(detaching, or tagging, an id that is not attached to the calling device), and — withUNAVAILABLEinstead ofINVALID_REQUEST—accessory_busy(the device’s accessory state is locked by a concurrent connect or mutation; retry the request). - The
accessoryIdrequest tag clamps a call to the accessory’s profile, after the method-scope check so it only narrows. The tag must name an accessory of the calling device’s own record (elseaccessory_not_attached— companions and other callers can never borrow the app’s accessories). A tag admits only an explicit allowlist of core methods —node.invoke,node.event,node.invoke.result,chat.send,chat.abort,chat.history,exec.approval.resolve,device.self(ACCESSORY_TAGGABLE_METHODSinsrc/shared/accessory-profiles.ts); everything else tagged, including every plugin method anddevice.accessory.*itself, is refused withaccessory_method_denied(checked before the scope check, so a tag can never reach a handler that dispatches node commands of its own, such asbrowser.request). On the allowlist, the method’s required operator scope must be in the kind’sscopes(elseaccessory_scope_denied; admin-only and unclassified methods are refused), and the handler runs with a request-local view whose scopes hold every profile scope the connection satisfies under the implication rules — an extra scope the socket holds (for example a re-approvedoperator.admin) is invisible to the handler while the tag is on, and the view never gains a scope outside the profile. The view’s connection binding delegates to the original connection, so a suspension or unlink recorded on it (ADR 2243 suspend-before-close) applies to tagged requests exactly as to untagged ones. A taggednode.invokemay only run a command the kind’scommandsgrants (accessory_command_denied, checked after the node command allowlist so a deny still wins). An untagged request is the app itself and is unchanged (it keeps the connection’s full scopes); node-role frames (node.event,node.invoke.result) accept a tag only when it names an accessory of the node’s own device. - The tag is attribution plus a ceiling on the accessory’s own direct requests — not an
isolation boundary against the app or the person’s agent. An agent turn started by a tagged
chat.sendruns under the person’s tool policy and exec approvals like any untagged app request, because a compromised app can omit the tag anyway. For audit and approval display, a run started by a taggedchat.sendcarriesaccessoryIdandkindin itschatevents’origin(next todeviceId/clientId).
Alert mutes (push.mute.get / push.mute.set)
A signed-in person reads and changes their own alert mutes from any of their own devices. Mutes are durable gateway state per person and apply to every device of that person.
A
PushAlertMute is { kind: "chat.final" | "inbox", source?, accountId? }. A mute matches an
alert when the kind is equal, source is absent or equal to the alert source, and accountId
is absent or equal to the alert account id:
{kind:"inbox"}mutes all inbox alerts,{kind:"inbox",source:"whatsapp"}mutes every WhatsApp account, and addingaccountIdmutes one account.{kind:"chat.final"}mutes reply alerts.push.mute.settakes{ kind, source?, accountId?, muted }and is one idempotent toggle, not a snapshot replace:muted:trueadds the exactly equal entry if absent,muted:falseremoves it if present, so concurrent devices never overwrite each other. Strings are trimmed before matching and storing; matching is exact and case-sensitive. The result is the person’s full list after the change, sorted bykind, thensource ?? "", thenaccountId ?? "".- Approval alerts are never muted and never deduped.
- A repeat of the same event (inbox item, reply run) is pushed to a device at most once per kind every 10 minutes, measured from the last successful send. Distinct events are never deduped by text. Only digests are kept in memory.
- Refusals carry
error.details.reason:push_mute_person_required(the connection resolves no person; sign in again),push_mute_invalid(sourceoraccountIdempty after trimming,accountIdwithoutsource, orsourcewithkind:"chat.final"), andpush_mute_limit(adding a 65th entry; at most 64 per person).kind:"approval"and unknown fields fail the validator with the standard invalid-paramsINVALID_REQUEST.
Identity RPCs
ADR 0116 binds people to their linked accounts at enrollment. The CLI, the web client and every other client talk to the same sevenidentity.* methods; the flows they serve are in
Identities. Linking grants a person’s identity, so only operator.admin binds
or unbinds a value.
- The three narrow methods (
identity.self,identity.link.claim,identity.logout) read the verified device id from the connection, never from the request body. A connection without one is refused fail-closed withidentity_device_required(“This connection has no verified device.”), so a caller can only act on its own device and person. identity.linkrefusesdevice:values (identity_link_invalid) and points atwednesdayai devices link <deviceId> --identity <name>: devices have their own operator path (see Device identity + pairing).identity.link.claimanswersidentity_link_conflictwith<value> is already linked to another person; ask them to unlink it first.— it never names the other person to a narrow caller. Claims are serialized per claimed value and rate limited per device (5/min) and per person (15/min), with a 5-minute lockout.identity.devices.listreturns every paired device whose storedownerPersonis the caller’s person (app installs, their companions and nodes alike;companionOfmarks a companion,currentmarks the calling device,accessorieslists the vouched accessories), and holds no tokens, public keys or scopes. A caller with no person gets an empty list.identity.devices.remove { deviceId }runs the same removal cascade asdevice.pair.remove(the target’s and its companions’ sockets close with 1008 after the response). Refusals carrydetails.reason:identity_person_required(the connection is not bound to a person) andidentity_device_not_owned— the same answer for a device of another person and for an unknown id, so other persons’ device ids are never revealed. The web client renders the pair as the account menu’s Your devices dialog; removing the current device ends in the logout path (ADR 0116 D10).
TLS + pinning
- TLS is supported for WS connections.
- Clients may optionally pin the gateway cert fingerprint (see
gateway.tlsconfig plusgateway.remote.tlsFingerprintor CLI--tls-fingerprint).
Scope
This protocol exposes the full gateway API (status, channels, models, chat, agent, sessions, nodes, approvals, etc.). The exact surface is defined by the TypeBox schemas insrc/gateway/protocol/schema.ts.