Protocol methods

Every JSON-RPC method of bma.executor.v1.1 outside the capability requests, with its direction, parameters and result, and how each SDK sends or serves it. Most are handled by the SDK itself (registration, heartbeats, token refresh, tool dispatch); the rest map to the typed methods on the other pages.

Generated from bma-executor-sdk 1.3.0 and its contract (contracts/bma/executor, protocol bma.executor.v1.1). Install, credentials and quick starts are on the bma-executor-sdk overview; the protocol itself is described in Executor Protocol.

Methods

Method	Direction	Description
`executor.register`	executor → harness	Register an executor connection.
`executor.heartbeat`	executor → harness	Refresh the executor lease.
`executor.token.refresh`	executor → harness	Extend the connection with a fresh executor token.
`executor.capabilities.update`	executor → harness	Publish changed executor capabilities.
`executor.drain`	harness → executor	Ask the executor to drain.
`executor.close`	both directions	Close the executor connection.
`session.assign`	harness → executor	Assign a session to the executor.
`session.ready`	executor → harness	Report a session ready.
`session.event`	executor → harness	Emit a durable session event.
`session.status`	executor → harness	Report session status.
`session.stop`	harness → executor	Stop a session.
`session.ended`	executor → harness	Report a session ended.
`tool.call`	harness → executor	Dispatch a tool call.
`tool.result`	executor → harness	Report a tool result.
`tool.cancel`	harness → executor	Cancel a running tool call.
`tool.progress`	executor → harness	Report tool progress.
`fs.mount`	harness → executor	Mount session file views backed by bma-file.
`fs.unmount`	harness → executor	Unmount the session file views.
`turn.start`	harness → executor	Start an agent turn.
`turn.input`	harness → executor	Add user input to the running turn.
`turn.cancel`	harness → executor	Stop the running turn.
`session.close`	harness → executor	Close an agent session.
`session.event_delta`	executor → harness	Stream a preview of a durable agent event.
`interaction.request`	executor → harness	Ask the platform for an approval or an answer.
`interaction.response`	harness → executor	Deliver the answer to an interaction.
`agent.custom_tool_result`	harness → executor	Deliver the user’s result of a custom tool call.
`interaction.cancel`	executor → harness	Withdraw an open interaction.
`model_token.refresh`	executor → harness	Fetch a fresh model token for a running turn.
`tools_token.refresh`	executor → harness	Fetch a fresh platform tools token for a running turn.

executor.register

Register an executor connection. Executor to harness request, the first frame on the control channel. protocol MUST equal the negotiated WebSocket subprotocol; otherwise the server answers -32010 and closes with 4003. A machine-scoped executor sends an empty environment_id. resume.active_sessions reattaches sessions after reconnect. A machine-scoped executor that declares neither capabilities.process nor capabilities.agent is answered -32012 with data.reason “capability_missing” and data.capability “process” instead of a result; no runtime is bound and the connection stays unregistered. Direction: executor → harness · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`protocol`	`"bma.executor.v1" \| "bma.executor.v1.1"`	yes	Value of both the WebSocket subprotocol and executor.register protocol. A v1.1 server serves v1 executors and never sends them v1.1 methods.
`environment_id`	`string`	yes	Selfhost environment id; empty for a machine-scoped executor.
`executor`	`ExecutorInfo`	yes	Executor identity reported at token bootstrap and registration.
`capabilities`	`Capabilities`	yes	Executor capability object. The server only sends a method to an executor that advertised its capability; otherwise the executor answers -32012 capability_unavailable.
`resume`	`ExecutorResume`	no	Reattach state sent on reconnect.

Result ExecutorRegisterResult

Name	Type	Required	Description
`executor_id`	`string`	yes
`connection_id`	`string`	yes
`server_time`	`string`	yes
`heartbeat_interval_ms`	`integer`	yes
`lease_ttl_ms`	`integer`	yes
`max_control_frame_bytes`	`integer`	yes
`max_mcp_frame_bytes`	`integer`	yes
`drain`	`boolean`	yes
`protocol`	`"bma.executor.v1" \| "bma.executor.v1.1"`	no	Value of both the WebSocket subprotocol and executor.register protocol. A v1.1 server serves v1 executors and never sends them v1.1 methods.
`limits`	`Limits`	no	Limits the executor must enforce, advertised in the v1.1 executor.register result (v1.1 §1.3).

In the SDK Handled by the SDK: sent by start, with the capabilities and the resume id after a reconnect. (executor)

executor.heartbeat

Refresh the executor lease. Executor to harness request, sent every heartbeat_interval_ms. Two missed heartbeats expire the lease server-side. drain=true means the executor must stop accepting new sessions and finish current work. Direction: executor → harness · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`connection_id`	`string`	yes
`active_sessions`	`string[]`	yes
`load`	`ExecutorLoad`	no	Advisory executor load reported with executor.heartbeat. The server does not act on it.

Result ExecutorHeartbeatResult

Name	Type	Required
`server_time`	`string`	yes
`lease_ttl_ms`	`integer`	yes
`drain`	`boolean`	yes

In the SDK Handled by the SDK: sent by the client at the interval executor.register returns. (executor)

executor.token.refresh

Extend the connection with a fresh executor token. Executor to harness request. Before the current token expires the executor fetches a new one from POST /v1/machines/{machine_id}/token or POST /v1/environments/{environment_id}/token (legacy alias POST /v1/executors/token) with its original credential and sends it on the open control channel. The harness verifies that it names the same executor, scope and machine credential as the connection and moves the connection’s 4001 deadline to the new token’s expiry; nothing else about the connection changes. A rejected token leaves the old deadline in place. A harness without the method answers -32601; the executor then keeps reconnecting on 4001. Direction: executor → harness · Kind: request · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`token`	`string`	yes

Result ExecutorTokenRefreshResult

Name	Type	Required	Description
`expires_at`	`string`	yes	RFC 3339 time of the new connection deadline.

In the SDK Handled by the SDK: the client fetches a fresh executor token and extends the connection before it expires. (executor)

executor.capabilities.update

Publish changed executor capabilities. Executor to harness notification. It may change capabilities, not the protocol version. Direction: executor → harness · Kind: notification · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`capabilities`	`Capabilities`	yes	Executor capability object. The server only sends a method to an executor that advertised its capability; otherwise the executor answers -32012 capability_unavailable.

Result No result (notification). In the SDK

client.notify("executor.capabilities.update", params) // ExecutorCapabilitiesUpdateParams

client.notify(methods.EXECUTOR_CAPABILITIES_UPDATE, params)  # ExecutorCapabilitiesUpdateParams

bmaexecutor.Notifications.ExecutorCapabilitiesUpdate.Notify(ctx, client, params) // ExecutorCapabilitiesUpdateParams

executor.drain

Ask the executor to drain. Harness to executor request. The executor stops accepting new sessions, finishes current work, and reports active_sessions. Direction: harness → executor · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`reason`	`string`	yes
`deadline_ms`	`integer`	no

Result ExecutorDrainResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`active_sessions`	`string[]`	yes

In the SDK Handled by the SDK: served with onDrain; sent by the harness drain. (executor)

executor.close

Close the executor connection. Either side notification, followed by WebSocket close code 1000 or 1001. Direction: both directions · Kind: notification · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`reason`	`string`	yes

Result No result (notification). In the SDK Handled by the SDK: sent by stop; received, it stops the client for good. (executor)

session.assign

Assign a session to the executor. Harness to executor request. The executor rejects a session that exceeds its capability or resource limits with -32009. metadata.source “harness” marks a long-lived harness session; any other source is one-shot and ends after its tool call. Direction: harness → executor · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`work_id`	`string`	yes
`agent_id`	`string`	no
`environment_id`	`string`	yes
`deadline_ms`	`integer`	no
`lease`	`Lease`	yes	Fencing lease for a session assignment.
`resources`	`SessionMemoryResource[]`	no
`mcp_servers`	`McpServerConfig[]`	no
`metadata`	`map<string, string>`	no

Result SessionAssignResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`session_id`	`string`	yes

In the SDK Handled by the SDK: served with onSessionAssign (or the Go Core); sent by the harness assignSession. (executor)

session.ready

Report a session ready. Executor to harness request after session.assign is accepted. Direction: executor → harness · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`work_id`	`string`	yes
`lease_token`	`string`	yes

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

await client.call("session.ready", params) // SessionReadyParams -> Ack

await client.call(methods.SESSION_READY, params)  # SessionReadyParams -> Ack

bmaexecutor.Calls.SessionReady.Call(ctx, client, params) // SessionReadyParams -> (Ack, error)

session.event

Emit a durable session event. Executor to harness request for durable session events. A tool executor’s event is idempotent by its JSON-RPC id. An agent executor (capability agent) also sends turn_id, event_id and sequence; the harness deduplicates by (session_id, event_id), accepts a sequence at or below acked_sequence as a duplicate, and rejects a gap with -32013 conflict (data.expected_sequence). An agent event matches schemas/agent.json AgentEvent. The JSON-RPC response is the ACK; the executor keeps every unacked event and resends them in sequence order after reconnect, before any new event. Direction: executor → harness · Kind: request · Idempotent by: jsonrpc_id · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`turn_id`	`string`	no	Agent sessions; the turn that produced the event.
`event_id`	`string`	no	Agent sessions; executor-assigned, unique within the session, stable across resends.
`sequence`	`integer`	no	Agent sessions; starts at 1 and increases by 1 per durable event within the session.
`idempotency_key`	`string`	no	Agent sessions; optional key the executor keeps for this event across process restarts (its outbox entry id, for example). A new executor epoch renumbers sequence and suffixes event_id, so only this key lets the harness recognize an event it stored just before the executor crashed. The harness acknowledges an event whose key the session already stored as a duplicate (sequence advanced, nothing added to the session log), in any epoch. Without it an event resent in a new epoch is stored again (at-least-once).
`event`	`SessionEvent`	yes	Durable session event emitted by the executor.

Result SessionEventResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`event_id`	`string`	yes
`acked_sequence`	`integer`	no	Agent sessions: highest contiguous sequence the platform has persisted for the session. A duplicate event is accepted and reports the current value.

In the SDK

await client.call("session.event", params) // SessionEventParams -> SessionEventResult

await client.call(methods.SESSION_EVENT, params)  # SessionEventParams -> SessionEventResult

bmaexecutor.Calls.SessionEvent.Call(ctx, client, params) // SessionEventParams -> (SessionEventResult, error)

session.status

Report session status. Executor to harness notification. detail carries free-form context such as tool_running or mcp_unavailable. Direction: executor → harness · Kind: notification · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`status`	`"starting" \| "running" \| "idle" \| "stopping" \| "stopped" \| "error"`	yes	Lifecycle status reported by the executor.
`detail`	`string`	no

Result No result (notification). In the SDK

client.notify("session.status", params) // SessionStatusParams

client.notify(methods.SESSION_STATUS, params)  # SessionStatusParams

bmaexecutor.Notifications.SessionStatus.Notify(ctx, client, params) // SessionStatusParams

session.stop

Stop a session. Harness to executor request. The executor terminates every process and MCP server of the session (SIGTERM, then SIGKILL) and then sends session.ended. Direction: harness → executor · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`reason`	`string`	yes
`deadline_ms`	`integer`	no

Result SessionStopResult

Name	Type	Required	Description
`stopped`	`boolean`	yes

In the SDK Handled by the SDK: served with onSessionStop (or the Go Core); sent by the harness session stop. (executor)

session.ended

Report a session ended. Executor to harness request, sent after every process of the session is gone. Retried until accepted. Direction: executor → harness · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`reason`	`string`	yes

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

await client.call("session.ended", params) // SessionEndedParams -> Ack

await client.call(methods.SESSION_ENDED, params)  # SessionEndedParams -> Ack

bmaexecutor.Calls.SessionEnded.Call(ctx, client, params) // SessionEndedParams -> (Ack, error)

tool.call

Dispatch a tool call. Harness to executor request. The executor acknowledges the dispatch and reports the outcome separately with tool.result. A duplicate tool_call_id is acknowledged without re-execution. A tool the executor does not serve is -32012 with data.capability “tool:<name>”. Direction: harness → executor · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`tool_call_id`	`string`	yes
`tool`	`ToolName`	yes	Built-in tool names. bmad serves bash only and answers -32012 for the rest.
`input`	`ToolInput`	yes	Superset of every built-in tool input, decoded by executors that read input generically. tool.call selects the exact per-tool schema through x-bma-params-discriminator; unknown members are ignored.
`deadline_ms`	`integer`	no
`permission`	`ToolPermission`	no	Tool permission resolved by the harness.

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK Handled by the SDK: served by the typed tool slots client.tools.<name>.handle; sent by the harness callTool / session.tools.<name>.call. (tools)

tool.result

Report a tool result. Executor to harness request, idempotent by tool_call_id and retried until accepted. Large output is uploaded first (POST /v1/environments/{environment_id}/artifacts; legacy alias POST /v1/executors/artifacts) and referenced by an artifact content block. Direction: executor → harness · Kind: request · Idempotent by: tool_call_id · Since: bma.executor.v1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`tool_call_id`	`string`	yes
`outcome`	`"succeeded" \| "failed" \| "canceled"`	yes	Tool outcome.
`is_error`	`boolean`	yes
`content`	`ContentBlock[]`	yes
`duration_ms`	`integer`	no
`artifacts`	`ArtifactRef[]`	no

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

await client.call("tool.result", params) // ToolResultParams -> Ack

await client.call(methods.TOOL_RESULT, params)  # ToolResultParams -> Ack

bmaexecutor.Calls.ToolResult.Call(ctx, client, params) // ToolResultParams -> (Ack, error)

tool.cancel

Cancel a running tool call. Harness to executor request. The executor kills the process group; canceled=false when the call is unknown or already finished. Direction: harness → executor · Kind: request · Since: bma.executor.v1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`tool_call_id`	`string`	yes
`reason`	`string`	no

Result ToolCancelResult

Name	Type	Required	Description
`canceled`	`boolean`	yes

In the SDK Handled by the SDK: aborts the running handler (its signal or context); sent by the harness cancelTool. (tools)

tool.progress

Report tool progress. Executor to harness notification, optional. Direction: executor → harness · Kind: notification · Since: bma.executor.v1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`tool_call_id`	`string`	yes
`message`	`string`	yes

Result No result (notification). In the SDK

client.notify("tool.progress", params) // ToolProgressParams

client.notify(methods.TOOL_PROGRESS, params)  # ToolProgressParams

bmaexecutor.Notifications.ToolProgress.Notify(ctx, client, params) // ToolProgressParams

fs.mount

Mount session file views backed by bma-file. Harness to executor request (machine-scoped). The executor mounts each listed view at its path as a FUSE file system that reads from service_url with the view’s token, and keeps the token in memory only. Idempotent by (session_id, view), so resending the same mounts with new tokens renews the tokens without remounting; a changed path or readonly remounts. Sent when the session is bound to the machine and again after a resume or reconnect, because tokens are bound to the binding epoch. Direction: harness → executor · Kind: request · Capability: fs.fuse · Idempotent by: session_id+view · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`service_url`	`string`	yes	Complete prefix of the bma-file routes for this machine, ending in /v1/machines/{machine_id}/fs (for example https://executor.example.com/v1/machines/mach_01/fs). The executor appends ”/<op>” and nothing else; it does not compose the machine id itself. The previous <origin>/v1/fs/<op> routes stay as an alias until they are removed.
`mounts`	`FsMount[]`	yes

Result FsMountResult

Name	Type	Required
`state`	`"mounted" \| "failed"`	yes
`error_code`	`string`	no
`error`	`string`	no

In the SDK

client.onRequest("fs.mount", (params: FsMountParams) => FsMountResult | Promise<FsMountResult>)

client.on_request(methods.FS_MOUNT, handler)  # async handler(params: FsMountParams) -> FsMountResult

bmaexecutor.Requests.FsMount.Handle(client, func(ctx context.Context, params bmaexecutor.FsMountParams) (bmaexecutor.FsMountResult, error))

fs.unmount

Unmount the session file views. Harness to executor request (machine-scoped). Unmounts every view of the session and drops its tokens. With flush the executor first commits pending writes (none for read-only views). Idempotent by session_id, a session with nothing mounted answers “unmounted”. Direction: harness → executor · Kind: request · Capability: fs.fuse · Idempotent by: session_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`flush`	`boolean`	no

Result FsUnmountResult

Name	Type	Required
`state`	`"unmounted" \| "failed"`	yes
`pending_bytes`	`integer`	yes
`error_code`	`string`	no
`error`	`string`	no

In the SDK

client.onRequest("fs.unmount", (params: FsUnmountParams) => FsUnmountResult | Promise<FsUnmountResult>)

client.on_request(methods.FS_UNMOUNT, handler)  # async handler(params: FsUnmountParams) -> FsUnmountResult

bmaexecutor.Requests.FsUnmount.Handle(client, func(ctx context.Context, params bmaexecutor.FsUnmountParams) (bmaexecutor.FsUnmountResult, error))

turn.start

Start an agent turn. Harness to executor request (capability agent). Opens the agent session on first use (no session.assign) or continues it; executor_session_ref from an earlier TurnStartResult lets the executor resume its local conversation after a restart. The executor answers as soon as the turn is accepted and reports progress with session.event. Idempotent by turn_id. A session with a running turn answers -32013 conflict (use turn.input); a new session beyond max_sessions answers -32009. Direction: harness → executor · Kind: request · Capability: agent · Idempotent by: turn_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes	Platform session id.
`turn_id`	`string`	yes
`input_id`	`string`	yes	Platform input id of the user message that starts the turn.
`input`	`AgentInputBlock[]`	yes
`executor_session_ref`	`string`	no
`config`	`AgentTurnConfig`	no	Requested (turn.start) or effective (TurnStartResult.effective) turn configuration. Every member is optional in a request; the executor reports the values it actually applied.
`deadline_ms`	`integer`	no
`metadata`	`map<string, string>`	no	String key/value pairs the platform adds to the turn. Per-turn credentials the executor declared in AgentCapability.platform_credentials: model_base_url, model_token (and optionally model_context_window, model_max_output_tokens) for harness_model; for brain_tools (contract 1.4.0, only when this machine is the brain and a different machine the hands of the session) tools_mcp_url (https://executor.<domain>/v1/machines/\{brain_machine_id\}/mcp), tools_mcp_token and tools_mcp_token_expires_at (RFC 3339, 1 hour after turn.start). With tools_mcp_* present every tool call of the turn must go to that endpoint as an MCP tools/call (tools bash, read, write, edit, glob, grep) and none may run on this machine: when the endpoint cannot be reached or refuses the token the call fails and the executor never falls back to running the tool locally (fail closed). The token is bound to the turn’s event epoch: the same turn started again after an executor restart (turn.start with the same turn_id, a new epoch) carries a new token and the previous token is refused. Refresh with tools_token.refresh. Keys the executor does not know are ignored.

Result TurnStartResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`turn_id`	`string`	yes
`executor_session_ref`	`string`	yes	Opaque local session handle (for example the local agent’s conversation id). The platform stores it and sends it back in the next turn.start so the executor can resume the local conversation after a restart.
`resumed`	`boolean`	yes	true when the executor continued an existing local conversation, false when it started a new one.
`effective`	`AgentTurnConfig`	yes	Requested (turn.start) or effective (TurnStartResult.effective) turn configuration. Every member is optional in a request; the executor reports the values it actually applied.

In the SDK Handled by the SDK: served by serveAgent (openTurn, then runTurn); sent by the harness startTurn. (agent)

turn.input

Add user input to the running turn. Harness to executor request (capability agent). The local agent consumes the input at its next step. Idempotent by input_id. When turn_id is not the running turn the executor answers -32013 conflict and the harness starts a new turn instead. Direction: harness → executor · Kind: request · Capability: agent · Idempotent by: input_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`turn_id`	`string`	yes
`input_id`	`string`	yes
`input`	`AgentInputBlock[]`	yes

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK Handled by the SDK: delivered to the running turn’s inputs; sent by the harness sendTurnInput. (agent)

turn.cancel

Stop the running turn. Harness to executor request (capability agent). The executor stops the agent loop, cancels its local tool calls, withdraws open interactions (interaction.cancel turn_canceled), and ends the turn with session.status_idle turn_outcome=canceled. The session stays open for the next turn.start. Unlike tool.cancel (one harness-dispatched tool call) and session.stop (a hand session and its processes), it targets only the agent turn. Direction: harness → executor · Kind: request · Capability: agent · Since: bma.executor.v1.1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`turn_id`	`string`	yes
`reason`	`string`	no

Result TurnCancelResult

Name	Type	Required	Description
`canceled`	`boolean`	yes

In the SDK Handled by the SDK: cancels runTurn; sent by the harness cancelTurn. (agent)

session.close

Close an agent session. Harness to executor request (capability agent). The executor cancels a running turn as turn.cancel does, waits until its events are acknowledged, releases the local conversation, and then sends session.ended. closed=false for an unknown session. A later turn.start with the same session_id starts a new local conversation. Direction: harness → executor · Kind: request · Capability: agent · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`reason`	`string`	yes

Result SessionCloseResult

Name	Type	Required	Description
`closed`	`boolean`	yes

In the SDK Handled by the SDK: served by serveAgent (closeSession); sent by the harness closeAgentSession. (agent)

session.event_delta

Stream a preview of a durable agent event. Executor to harness notification (capability agent). Transient and lossy; never acknowledged or resent. event_id is the event_id of the durable session.event that finalizes the preview. The harness relays it to subscribers as Anthropic event_start and event_delta. Direction: executor → harness · Kind: notification · Capability: agent · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`turn_id`	`string`	yes
`event_id`	`string`	yes
`event_type`	`"agent.message" \| "agent.thinking"`	yes	Durable event type a streaming preview belongs to.
`index`	`integer`	yes	Content block index within the event.
`text`	`string`	yes	Text appended to the block.

Result No result (notification). In the SDK

client.notify("session.event_delta", params) // SessionEventDeltaParams

client.notify(methods.SESSION_EVENT_DELTA, params)  # SessionEventDeltaParams

bmaexecutor.Notifications.SessionEventDelta.Notify(ctx, client, params) // SessionEventDeltaParams

interaction.request

Ask the platform for an approval or an answer. Executor to harness request (capability agent). The harness opens one platform agent interaction (the same request on desktop, mobile and integrations) and answers with interaction.response later. Idempotent by interaction_id. A permission request references the agent.tool_use event in tool_use_id, sent earlier with evaluated_permission ask. The executor keeps local authority; it may still deny, and it treats expires_at as a local deny. An interaction_id of the form appr_ plus 24 lower-case hex digits (the deterministic approval id) is adopted as the platform interaction id; the interactions API, its card and the session stream use it, platform_interaction_id equals it, and a repeat of it (after an executor restart too) names the same interaction, never a second card. The same id for another tool_use_id (within one executor epoch) or another kind is refused with error conflict (-32013) and the stored interaction is left unchanged. An interaction_id of any other form is only the executor’s key; the platform assigns its own id (int_…) and returns it. Direction: executor → harness · Kind: request · Capability: agent · Idempotent by: interaction_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`turn_id`	`string`	yes
`interaction_id`	`string`	yes	Executor-assigned, unique within the session and stable for the same tool call or question across executor and brain restarts (derive it from the session, the turn and the call, for example appr_ + the first 24 hex chars of sha256(session_id, NUL, turn_id, NUL, call_id); the turn is part of it because some providers reuse call ids such as call_0 in every turn), so a restarted executor asks again with the same id and gets the same platform interaction, and an answer given while it was offline, back. The platform interaction is the one card every client of the session shows; a local UI shows the same interaction rather than a separate local prompt.
`kind`	`"permission" \| "question"`	yes	Interaction kinds; they map 1:1 to platform agent interactions.
`tool_use_id`	`string`	no	Required for permission.
`tool_name`	`string`	no
`tool_input`	`object`	no
`scopes`	`("once" \| "session")[]`	no	Grant scopes the user may pick for permission; defaults to once.
`question`	`InteractionQuestion`	no	Required for question.
`expires_at`	`string`	no	RFC 3339 time after which the executor stops waiting.

Result InteractionRequestResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`platform_interaction_id`	`string`	yes

In the SDK

await client.call("interaction.request", params) // InteractionRequestParams -> InteractionRequestResult

await client.call(methods.INTERACTION_REQUEST, params)  # InteractionRequestParams -> InteractionRequestResult

bmaexecutor.Calls.InteractionRequest.Call(ctx, client, params) // InteractionRequestParams -> (InteractionRequestResult, error)

interaction.response

Deliver the answer to an interaction. Harness to executor request (capability agent). Sent once the platform interaction resolves, expires or is canceled; retried with the same interaction_id until answered. The first answer wins; a repeat or an unknown interaction answers accepted=false. Direction: harness → executor · Kind: request · Capability: agent · Idempotent by: interaction_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`interaction_id`	`string`	yes
`outcome`	`"allow" \| "deny" \| "answered" \| "expired" \| "canceled"`	yes	How the platform resolved an interaction. allow/deny answer permission, answered answers question, expired and canceled close either kind without an answer.
`scope`	`"once" \| "session"`	no	Granted scope for allow.
`deny_message`	`string`	no
`answers`	`string[]`	no	Selected option ids or free text for answered.
`responder`	`InteractionResponder`	no	Who answered, for local audit. surface is the client that resolved it, for example desktop, mobile, web, slack.

Result InteractionResponseResult

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK Handled by the SDK: resolves the waiting requestInteraction; sent by the harness respondInteraction. (agent)

agent.custom_tool_result

Deliver the user’s result of a custom tool call. Harness to executor request (capability agent; sent only to an executor that declared agent.custom_tools). The executor emitted agent.custom_tool_use (its event_id is the tool_use_id) and waits; the platform sends the result the user’s application submitted with user.custom_tool_result. Only the first result of a call counts: the platform accepts one per tool_use_id and the executor answers a repeat, an unknown tool_use_id or a call it no longer waits for with accepted=false. Idempotent by tool_use_id: the platform retries the same result until the executor answers, also on a new connection. Timeout: the executor owns the wait. When its own limit passes it ends the call with a failed agent.tool_result (tool_use_id of the call, is_error true), continues the turn, and answers a later result with accepted=false; the platform stops accepting results for that call. Cancel: turn.cancel ends the waiting call as canceled with the turn, and the platform drops results it has not delivered yet for a turn that ended. Direction: harness → executor · Kind: request · Capability: agent · Idempotent by: tool_use_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`tool_use_id`	`string`	yes	The event_id of the agent.custom_tool_use this result answers.
`content`	`ContentBlock[]`	yes
`is_error`	`boolean`	no	The user’s application reports the call failed; the content explains why.

Result CustomToolResultResult

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

client.onRequest("agent.custom_tool_result", (params: AgentCustomToolResultParams) => CustomToolResultResult | Promise<CustomToolResultResult>)

client.on_request(methods.AGENT_CUSTOM_TOOL_RESULT, handler)  # async handler(params: AgentCustomToolResultParams) -> CustomToolResultResult

bmaexecutor.Requests.AgentCustomToolResult.Handle(client, func(ctx context.Context, params bmaexecutor.AgentCustomToolResultParams) (bmaexecutor.CustomToolResultResult, error))

interaction.cancel

Withdraw an open interaction. Executor to harness request (capability agent). The executor no longer needs the answer, for example the user answered in the local UI (resolved_locally) or the turn was canceled. The harness cancels the platform interaction so every client dismisses it. Idempotent by interaction_id. Direction: executor → harness · Kind: request · Capability: agent · Idempotent by: interaction_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`interaction_id`	`string`	yes
`reason`	`"resolved_locally" \| "turn_canceled" \| "expired" \| "tool_canceled"`	yes	Why the executor withdrew an open interaction.

Result Ack

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

await client.call("interaction.cancel", params) // InteractionCancelParams -> Ack

await client.call(methods.INTERACTION_CANCEL, params)  # InteractionCancelParams -> Ack

bmaexecutor.Calls.InteractionCancel.Call(ctx, client, params) // InteractionCancelParams -> (Ack, error)

model_token.refresh

Fetch a fresh model token for a running turn. Executor to harness request (capability agent). A brain started by turn.start with a model credential (metadata model_token, valid 1 hour) calls it before the token expires (the reference executors do so when less than 10 minutes remain) and joins model_base_url with the new model_token for its next model calls; the old token stays valid until it expires. The platform signs a new token only while the turn is active (pending, running or rescheduling) and the turn belongs to a session routed to this executor’s machine, so a turn that ended, was canceled or failed gets no further tokens: this is how the platform revokes model access per turn (a token already issued runs out its own expiry). Each call returns a new token; calls are not idempotent and a repeat is harmless. Errors carry data.reason: turn_inactive (-32007: the turn is not active), forbidden (-32001: the session or turn is unknown, belongs to another executor, or this executor is not entitled to platform credentials), model_token_unavailable (-32012: the platform issues no such token). A harness without the method answers -32601; the executor then keeps the token it has. Direction: executor → harness · Kind: request · Capability: agent · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes	Platform session id of the turn.
`turn_id`	`string`	yes	Platform id of the running turn the token is for.

Result ModelTokenRefreshResult

Name	Type	Required	Description
`model_token`	`string`	yes	Bearer token for model_base_url. Valid until expires_at.
`model_base_url`	`string`	yes	Base URL the token is for (an OpenAI / Anthropic base URL path).
`expires_at`	`string`	yes	RFC 3339 time the token stops being accepted.

In the SDK

await client.call("model_token.refresh", params) // ModelTokenRefreshParams -> ModelTokenRefreshResult

await client.call(methods.MODEL_TOKEN_REFRESH, params)  # ModelTokenRefreshParams -> ModelTokenRefreshResult

bmaexecutor.Calls.ModelTokenRefresh.Call(ctx, client, params) // ModelTokenRefreshParams -> (ModelTokenRefreshResult, error)

tools_token.refresh

Fetch a fresh platform tools token for a running turn. Executor to harness request (capability agent, contract 1.4.0). A brain started by turn.start with a platform tools credential (metadata tools_mcp_token, valid 1 hour, handed over only when the session’s brain machine and hands machine differ) calls it before the token expires (the reference executors do so when less than 10 minutes remain) and uses the new tools_mcp_token with tools_mcp_url for its next tool calls; the old token stays valid until it expires or its epoch is superseded. The shape and rules are those of model_token.refresh: the platform signs a new token only while the turn is active (pending, running or rescheduling), the turn belongs to a session routed to this executor’s machine as the brain machine, and the call comes from the turn’s current epoch, so a turn that ended, was canceled or failed, or was started again in a newer epoch gets no further token for the old epoch. Each call returns a new token; calls are not idempotent and a repeat is harmless. Errors carry data.reason: turn_inactive (-32007: the turn is not active), forbidden (-32001: the session or turn is unknown, belongs to another executor, or this executor is not entitled to brain_tools), tools_token_unavailable (-32012: the platform issues no such token for this turn, for example brain and hands are one machine). A harness without the method answers -32601; the executor then keeps the token it has. Direction: executor → harness · Kind: request · Capability: agent · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes	Platform session id of the turn.
`turn_id`	`string`	yes	Platform id of the running turn the token is for.

Result ToolsTokenRefreshResult

Name	Type	Required	Description
`tools_mcp_token`	`string`	yes	Bearer token for tools_mcp_url, bound to the org, session, turn, brain machine and brain epoch of the turn. Valid until expires_at.
`tools_mcp_url`	`string`	yes	The session’s platform tools endpoint the token is for (https://<executor host>/v1/machines/{brain_machine_id}/mcp).
`expires_at`	`string`	yes	RFC 3339 time the token stops being accepted.

In the SDK

await client.call("tools_token.refresh", params) // ToolsTokenRefreshParams -> ToolsTokenRefreshResult

await client.call(methods.TOOLS_TOKEN_REFRESH, params)  # ToolsTokenRefreshParams -> ToolsTokenRefreshResult

bmaexecutor.Calls.ToolsTokenRefresh.Call(ctx, client, params) // ToolsTokenRefreshParams -> (ToolsTokenRefreshResult, error)

SDKs

Anthropic SDKs

bma-executor-sdk

Methods

executor.register

executor.heartbeat

executor.token.refresh

executor.capabilities.update

executor.drain

executor.close

session.assign

session.ready

session.event

session.status

session.stop

session.ended

tool.call

tool.result

tool.cancel

tool.progress

fs.mount

fs.unmount

turn.start

turn.input

turn.cancel

session.close

session.event_delta

interaction.request

interaction.response

agent.custom_tool_result

interaction.cancel

model_token.refresh

tools_token.refresh

​Methods

​executor.register

​executor.heartbeat

​executor.token.refresh

​executor.capabilities.update

​executor.drain

​executor.close

​session.assign

​session.ready

​session.event

​session.status

​session.stop

​session.ended

​tool.call

​tool.result

​tool.cancel

​tool.progress

​fs.mount

​fs.unmount

​turn.start

​turn.input

​turn.cancel

​session.close

​session.event_delta

​interaction.request

​interaction.response

​agent.custom_tool_result

​interaction.cancel

​model_token.refresh

​tools_token.refresh

Methods

executor.register

executor.heartbeat

executor.token.refresh

executor.capabilities.update

executor.drain

executor.close

session.assign

session.ready

session.event

session.status

session.stop

session.ended

tool.call

tool.result

tool.cancel

tool.progress

fs.mount

fs.unmount

turn.start

turn.input

turn.cancel

session.close

session.event_delta

interaction.request

interaction.response

agent.custom_tool_result

interaction.cancel

model_token.refresh

tools_token.refresh