Process, terminal & machine

Beyond tools, an executor can serve capability requests: long-running processes (process.*), PTY terminals (terminal.*), skill installation and workspace backups. Each is advertised by a capability bit and served with a typed handler; a request for a capability you did not advertise is refused with capability_unavailable (-32012). The Go execution core serves process.* and skill.install for you (see Execution core).

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
`process.start`	harness → executor	Start a process.
`process.read`	harness → executor	Read process output from a cursor.
`process.write`	harness → executor	Write to process stdin.
`process.interrupt`	harness → executor	Interrupt a process (SIGINT).
`process.terminate`	harness → executor	Terminate a process (SIGTERM, then SIGKILL after grace_ms).
`process.list`	harness → executor	List the processes of a session.
`process.status`	executor → harness	Advise a process state change.
`terminal.open`	harness → executor	Create or reuse a PTY.
`terminal.attach`	harness → executor	Attach one consumer to a live PTY.
`terminal.close`	harness → executor	Close a PTY.
`skill.install`	harness → executor	Install one skill revision on the machine.
`workspace.backup`	harness → executor	Upload one backup of the machine workspace.

process.start

Start a process. Harness to executor request (v1.1 §3.3). Idempotent by (session_id, process_id): a repeat returns the live state. wait_ms waits up to that long for the process to end before answering. A spawn failure is an error with data.reason “spawn_failed”. io_mode, file_transfer, package_install and git_credentials each require the matching process capability bit. Direction: harness → executor · Kind: request · Capability: process.enabled · Idempotent by: session_id+process_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`process_id`	`string`	yes
`argv`	`string[]`	yes	Command and arguments (at most 256 entries, 4 KiB each, 16 KiB total). Must be empty when file_transfer or package_install is set.
`cwd`	`string`	no
`env`	`map<string, string>`	no
`stdin`	`"open" \| "closed"`	no	process.start stdin mode. Empty or “closed” closes stdin at start; “open” keeps it open for process.write.
`stderr`	`"merge"`	no	Empty keeps separate stdout/stderr streams.
`wait_ms`	`integer`	no
`timeout_ms`	`integer`	no	Kills the process and ends it as failed with reason “timeout”.
`metadata`	`map<string, string>`	no	Who started the process. A process an agent tool started (a command, a file transfer, a package install) always carries agent_session_id (the public agent session id) and tool_call_id; it carries no initiator. A process the platform started on its own, such as the machine desktop agent, carries initiator “platform” and no agent_session_id. A process with neither is not started by the harness: an executor that resolves a directory, files or owner per session refuses it (reason session_rejected) instead of using a default. Human console terminals are terminal.attach, not process.start.
`io_mode`	`"pty"`	no	Requires capability process.pty.
`file_transfer`	`ProcessFileTransfer`	no	Requires capability process.file_transfer. Excludes argv entries, io_mode and git_credentials.
`package_install`	`ProcessPackageInstall`	no	Requires capability process.package_install. Excludes argv entries, io_mode, file_transfer and git_credentials.
`git_credentials`	`boolean`	no	Installs a per-process Git credential helper for https://github.com that fetches short-lived tokens for this process while it runs. Requires capability process.git_credentials.

Result ProcessState

Name	Type	Required	Description
`process_id`	`string`	yes
`state`	`"running" \| "exited" \| "failed" \| "killed"`	yes	Process state (v1.1 §3.3).
`pid`	`integer`	no
`started_at`	`string`	no
`ended_at`	`string`	no
`reason`	`string`	no
`cursors`	`Cursors`	yes	Per-stream byte cursors.
`exit_code`	`integer \| null`	yes
`exit_signal`	`string \| null`	yes
`stderr`	`string`	no
`accepted`	`boolean`	no
`file_transfer`	`FileTransferResult`	no	Ended file transfer outcome: the uploaded path and digest, the downloaded digest, or an error.

In the SDK

client.onRequest("process.start", (params: ProcessStartParams) => ProcessState | Promise<ProcessState>)

client.on_request(methods.PROCESS_START, handler)  # async handler(params: ProcessStartParams) -> ProcessState

bmaexecutor.Requests.ProcessStart.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessStartParams) (bmaexecutor.ProcessState, error))

process.read

Read process output from a cursor. Harness to executor request (v1.1 §3.4). Long-polls up to wait_ms for new bytes. gap=true when bytes before earliest_cursor were dropped from the ring buffer. Direction: harness → executor · Kind: request · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`process_id`	`string`	yes
`stream`	`"stdout" \| "stderr"`	yes	Process output stream (v1.1 §3.2).
`cursor`	`integer`	yes
`max_bytes`	`integer`	no
`wait_ms`	`integer`	no

Result ProcessReadResult

Name	Type	Required	Description
`process_id`	`string`	yes
`stream`	`"stdout" \| "stderr"`	yes	Process output stream (v1.1 §3.2).
`data`	`string`	yes	Base64 bytes from from_cursor to next_cursor.
`from_cursor`	`integer`	yes
`next_cursor`	`integer`	yes
`earliest_cursor`	`integer`	yes
`gap`	`boolean`	yes
`truncated`	`boolean`	yes
`eof`	`boolean`	yes
`state`	`"running" \| "exited" \| "failed" \| "killed"`	yes	Process state (v1.1 §3.3).
`ended_at`	`string`	no
`reason`	`string`	no
`exit_code`	`integer \| null`	yes
`exit_signal`	`string \| null`	yes
`file_transfer`	`FileTransferResult`	no	Ended file transfer outcome: the uploaded path and digest, the downloaded digest, or an error.

In the SDK

client.onRequest("process.read", (params: ProcessReadParams) => ProcessReadResult | Promise<ProcessReadResult>)

client.on_request(methods.PROCESS_READ, handler)  # async handler(params: ProcessReadParams) -> ProcessReadResult

bmaexecutor.Requests.ProcessRead.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessReadParams) (bmaexecutor.ProcessReadResult, error))

process.write

Write to process stdin. Harness to executor request (v1.1 §3.5). Exactly one of data (base64, at most 32 KiB decoded) or close_stdin. close_stdin is rejected for io_mode “pty”. Direction: harness → executor · Kind: request · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required
`session_id`	`string`	yes
`process_id`	`string`	yes
`data`	`string`	no
`close_stdin`	`boolean`	no

Result ProcessWriteResult

Name	Type	Required	Description
`accepted`	`boolean`	yes

In the SDK

client.onRequest("process.write", (params: ProcessWriteParams) => ProcessWriteResult | Promise<ProcessWriteResult>)

client.on_request(methods.PROCESS_WRITE, handler)  # async handler(params: ProcessWriteParams) -> ProcessWriteResult

bmaexecutor.Requests.ProcessWrite.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessWriteParams) (bmaexecutor.ProcessWriteResult, error))

process.interrupt

Interrupt a process (SIGINT). Harness to executor request (v1.1 §3.6). Direction: harness → executor · Kind: request · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`process_id`	`string`	yes
`grace_ms`	`integer \| null`	no	Only meaningful for process.terminate.

Result ProcessState

Name	Type	Required	Description
`process_id`	`string`	yes
`state`	`"running" \| "exited" \| "failed" \| "killed"`	yes	Process state (v1.1 §3.3).
`pid`	`integer`	no
`started_at`	`string`	no
`ended_at`	`string`	no
`reason`	`string`	no
`cursors`	`Cursors`	yes	Per-stream byte cursors.
`exit_code`	`integer \| null`	yes
`exit_signal`	`string \| null`	yes
`stderr`	`string`	no
`accepted`	`boolean`	no
`file_transfer`	`FileTransferResult`	no	Ended file transfer outcome: the uploaded path and digest, the downloaded digest, or an error.

In the SDK

client.onRequest("process.interrupt", (params: ProcessSignalParams) => ProcessState | Promise<ProcessState>)

client.on_request(methods.PROCESS_INTERRUPT, handler)  # async handler(params: ProcessSignalParams) -> ProcessState

bmaexecutor.Requests.ProcessInterrupt.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessSignalParams) (bmaexecutor.ProcessState, error))

process.terminate

Terminate a process (SIGTERM, then SIGKILL after grace_ms). Harness to executor request (v1.1 §3.6). Direction: harness → executor · Kind: request · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`process_id`	`string`	yes
`grace_ms`	`integer \| null`	no	Only meaningful for process.terminate.

Result ProcessState

Name	Type	Required	Description
`process_id`	`string`	yes
`state`	`"running" \| "exited" \| "failed" \| "killed"`	yes	Process state (v1.1 §3.3).
`pid`	`integer`	no
`started_at`	`string`	no
`ended_at`	`string`	no
`reason`	`string`	no
`cursors`	`Cursors`	yes	Per-stream byte cursors.
`exit_code`	`integer \| null`	yes
`exit_signal`	`string \| null`	yes
`stderr`	`string`	no
`accepted`	`boolean`	no
`file_transfer`	`FileTransferResult`	no	Ended file transfer outcome: the uploaded path and digest, the downloaded digest, or an error.

In the SDK

client.onRequest("process.terminate", (params: ProcessSignalParams) => ProcessState | Promise<ProcessState>)

client.on_request(methods.PROCESS_TERMINATE, handler)  # async handler(params: ProcessSignalParams) -> ProcessState

bmaexecutor.Requests.ProcessTerminate.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessSignalParams) (bmaexecutor.ProcessState, error))

process.list

List the processes of a session. Harness to executor request (v1.1 §3.7). A new connection starts with an empty process table. Direction: harness → executor · Kind: request · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes

Result ProcessListResult

Name	Type	Required	Description
`processes`	`ProcessState[]`	yes

In the SDK

client.onRequest("process.list", (params: ProcessListParams) => ProcessListResult | Promise<ProcessListResult>)

client.on_request(methods.PROCESS_LIST, handler)  # async handler(params: ProcessListParams) -> ProcessListResult

bmaexecutor.Requests.ProcessList.Handle(client, func(ctx context.Context, params bmaexecutor.ProcessListParams) (bmaexecutor.ProcessListResult, error))

process.status

Advise a process state change. Executor to harness notification (v1.1 §3.8). Advisory: the harness confirms state with process.read or process.list. Direction: executor → harness · Kind: notification · Capability: process.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`session_id`	`string`	yes
`process_id`	`string`	yes
`state`	`"running" \| "exited" \| "failed" \| "killed"`	yes	Process state (v1.1 §3.3).
`exit_code`	`integer \| null`	no
`exit_signal`	`string \| null`	no
`ended_at`	`string`	no
`reason`	`string`	no
`observed_at`	`string`	yes

Result No result (notification). In the SDK

client.notify("process.status", params) // ProcessStatusParams

client.notify(methods.PROCESS_STATUS, params)  # ProcessStatusParams

bmaexecutor.Notifications.ProcessStatus.Notify(ctx, client, params) // ProcessStatusParams

terminal.open

Create or reuse a PTY. Harness to executor request (machine-scoped). Returns the live PTY with the same terminal_id; rows/cols only size a new PTY, and the rest of the spec must match a live terminal or the executor answers -32013. Direction: harness → executor · Kind: request · Capability: terminal.enabled · Idempotent by: terminal_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`terminal_id`	`string`	yes
`kind`	`string`	yes	human or agent.
`shell`	`string`	no
`argv`	`string[]`	no
`cwd`	`string`	no
`env`	`map<string, string>`	no
`rows`	`integer`	no
`cols`	`integer`	no

Result TerminalOpenResult

Name	Type	Required
`terminal_id`	`string`	yes
`epoch`	`integer`	yes
`pid`	`integer`	yes
`rows`	`integer`	yes
`cols`	`integer`	yes
`earliest_seq`	`integer`	yes
`latest_seq`	`integer`	yes
`created_at`	`string`	yes

In the SDK

client.onRequest("terminal.open", (params: TerminalOpenParams) => TerminalOpenResult | Promise<TerminalOpenResult>)

client.on_request(methods.TERMINAL_OPEN, handler)  # async handler(params: TerminalOpenParams) -> TerminalOpenResult

bmaexecutor.Requests.TerminalOpen.Handle(client, func(ctx context.Context, params bmaexecutor.TerminalOpenParams) (bmaexecutor.TerminalOpenResult, error))

terminal.attach

Attach one consumer to a live PTY. Harness to executor request. The executor dials host.url with the ticket, offering subprotocol bma.terminal.v1, and answers after the attached frame was written. from_seq/ack_seq resume output exactly as the bma.terminal.v1 attach frame does; can_write requests the single writer lease. Closing the host socket detaches; the PTY survives. Direction: harness → executor · Kind: request · Capability: terminal.enabled · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`terminal_id`	`string`	yes
`epoch`	`integer`	yes
`stream_id`	`string`	yes
`can_write`	`boolean`	yes
`from_seq`	`integer`	yes
`ack_seq`	`integer`	yes
`host`	`TerminalHost`	yes	Outbound host socket for one attach. The ticket is a single-use, short-lived bearer credential sent only in the Authorization header, never in the URL.

Result TerminalAttachResult

Name	Type	Required	Description
`accepted`	`boolean`	yes
`writer_epoch`	`integer`	yes

In the SDK

client.onRequest("terminal.attach", (params: TerminalAttachParams) => TerminalAttachResult | Promise<TerminalAttachResult>)

client.on_request(methods.TERMINAL_ATTACH, handler)  # async handler(params: TerminalAttachParams) -> TerminalAttachResult

bmaexecutor.Requests.TerminalAttach.Handle(client, func(ctx context.Context, params bmaexecutor.TerminalAttachParams) (bmaexecutor.TerminalAttachResult, error))

terminal.close

Close a PTY. Harness to executor request. Idempotent. Direction: harness → executor · Kind: request · Capability: terminal.enabled · Idempotent by: terminal_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`terminal_id`	`string`	yes
`reason`	`string`	no

Result TerminalCloseResult

Name	Type	Required	Description
`closed`	`boolean`	yes
`exit_code`	`integer \| null`	no

In the SDK

client.onRequest("terminal.close", (params: TerminalCloseParams) => TerminalCloseResult | Promise<TerminalCloseResult>)

client.on_request(methods.TERMINAL_CLOSE, handler)  # async handler(params: TerminalCloseParams) -> TerminalCloseResult

bmaexecutor.Requests.TerminalClose.Handle(client, func(ctx context.Context, params bmaexecutor.TerminalCloseParams) (bmaexecutor.TerminalCloseResult, error))

skill.install

Install one skill revision on the machine. Harness to executor request (machine-scoped). The executor downloads the revision archive with download_token, verifies digest, and installs it. Idempotent by (skill_id, revision_id, digest). Direction: harness → executor · Kind: request · Capability: skills.install · Idempotent by: skill_id+revision_id+digest · Since: bma.executor.v1.1 Parameters

Name	Type	Required	Description
`machine_id`	`string`	yes
`skill_id`	`string`	yes
`revision_id`	`string`	yes
`digest`	`string`	yes
`download_token`	`string`	yes
`download_expires_at`	`integer`	yes	Unix seconds.

Result SkillInstallResult

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

In the SDK

client.onRequest("skill.install", (params: SkillInstallParams) => SkillInstallResult | Promise<SkillInstallResult>)

client.on_request(methods.SKILL_INSTALL, handler)  # async handler(params: SkillInstallParams) -> SkillInstallResult

bmaexecutor.Requests.SkillInstall.Handle(client, func(ctx context.Context, params bmaexecutor.SkillInstallParams) (bmaexecutor.SkillInstallResult, error))

workspace.backup

Upload one backup of the machine workspace. Harness to executor request (machine-scoped). The executor walks paths (absolute), skipping exclude entries and its own BMA_HOME, and streams a tar+zstd archive with PUT to /daemon/machine-backups/{backup_id}/archive over the machine token, with the tree fingerprint in X-BMA-Backup-Fingerprint. When the fingerprint equals skip_if_fingerprint nothing is uploaded and the result is “unchanged”. Restore has no method; a recreated executor fetches /daemon/machine-backup-restore before executor.register. Direction: harness → executor · Kind: request · Capability: workspace.backup · Idempotent by: backup_id · Since: bma.executor.v1.1 Parameters

Name	Type	Required
`backup_id`	`string`	yes
`paths`	`string[]`	yes
`exclude`	`string[]`	no
`skip_if_fingerprint`	`string`	no

Result WorkspaceBackupResult

Name	Type	Required
`state`	`"uploaded" \| "unchanged" \| "failed"`	yes
`fingerprint`	`string`	no
`digest`	`string`	no
`size_bytes`	`integer`	no
`entries`	`integer`	no
`skipped`	`integer`	no
`error`	`string`	no

In the SDK

client.onRequest("workspace.backup", (params: WorkspaceBackupParams) => WorkspaceBackupResult | Promise<WorkspaceBackupResult>)

client.on_request(methods.WORKSPACE_BACKUP, handler)  # async handler(params: WorkspaceBackupParams) -> WorkspaceBackupResult

bmaexecutor.Requests.WorkspaceBackup.Handle(client, func(ctx context.Context, params bmaexecutor.WorkspaceBackupParams) (bmaexecutor.WorkspaceBackupResult, error))

SDKs

Anthropic SDKs

bma-executor-sdk

Methods

process.start

process.read

process.write

process.interrupt

process.terminate

process.list

process.status

terminal.open

terminal.attach

terminal.close

skill.install

workspace.backup

​Methods

​process.start

​process.read

​process.write

​process.interrupt

​process.terminate

​process.list

​process.status

​terminal.open

​terminal.attach

​terminal.close

​skill.install

​workspace.backup

Methods

process.start

process.read

process.write

process.interrupt

process.terminate

process.list

process.status

terminal.open

terminal.attach

terminal.close

skill.install

workspace.backup