bma-executor-sdk 0.4.0__py3-none-any.whl

bma_executor_sdk/generated.py

@@ -0,0 +1,1155 @@
+# Code generated by tools/contract/gen-python.mjs from contracts/bma (executor protocol 1.1.0). DO NOT EDIT.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, IntEnum
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
+
+# Annotations stay strings (PEP 563), so NotRequired is only needed by type
+# checkers and Python 3.10 works without typing_extensions at runtime.
+if TYPE_CHECKING:
+    from typing_extensions import NotRequired
+
+class Ack(TypedDict):
+    """Generic acknowledgement returned by executor RPC methods."""
+    accepted: bool
+
+class AgentCapability(TypedDict):
+    """agent capability. Present with enabled=true when the executor runs a complete agent and accepts turn.start, turn.input, turn.cancel, session.close and interaction.response."""
+    enabled: bool
+    models: NotRequired[list[AgentModel]]
+    permission_modes: NotRequired[list[str]]
+    interaction_kinds: NotRequired[list[InteractionKind]]
+    file_inputs: NotRequired[bool]
+    max_sessions: NotRequired[int]
+
+class AgentErrorInfo(TypedDict):
+    """Typed session error."""
+    type: str
+    message: NotRequired[str]
+
+class AgentEventType(str, Enum):
+    """Durable events an agent executor emits with session.event. Names and members follow Anthropic Managed Agents session events. user.* events are written by the platform, never by the executor."""
+    AgentMessage = "agent.message"
+    AgentThinking = "agent.thinking"
+    AgentToolUse = "agent.tool_use"
+    AgentToolResult = "agent.tool_result"
+    AgentMcpToolUse = "agent.mcp_tool_use"
+    AgentMcpToolResult = "agent.mcp_tool_result"
+    SessionStatusRunning = "session.status_running"
+    SessionStatusIdle = "session.status_idle"
+    SessionError = "session.error"
+
+class AgentInputBlock(TypedDict):
+    """One block of user input. A file block references a platform session file by file_id; the executor downloads it through the executor files API. File bytes never travel on the control channel."""
+    type: AgentInputBlockType
+    text: NotRequired[str]
+    file_id: NotRequired[str]
+    name: NotRequired[str]
+    mime_type: NotRequired[str]
+    size_bytes: NotRequired[int]
+
+class AgentInputBlockType(str, Enum):
+    """Agent input block type."""
+    Text = "text"
+    File = "file"
+
+class AgentMcpToolResultEvent(TypedDict):
+    """Result of an agent.mcp_tool_use."""
+    type: Literal["agent.mcp_tool_result"]
+    mcp_tool_use_id: str
+    content: NotRequired[list[ContentBlock]]
+    is_error: NotRequired[bool]
+
+class AgentMcpToolUseEvent(TypedDict):
+    """An MCP tool the local agent is calling. Its event_id is the mcp_tool_use_id."""
+    type: Literal["agent.mcp_tool_use"]
+    mcp_server_name: str
+    name: str
+    input: dict[str, Any]
+    evaluated_permission: NotRequired[EvaluatedPermission]
+
+class AgentMessageEvent(TypedDict):
+    """Final assistant text. Streaming previews for the same event_id arrive earlier as session.event_delta."""
+    type: Literal["agent.message"]
+    content: list[ContentBlock]
+
+class AgentModel(TypedDict):
+    """One model the local agent can run."""
+    id: str
+    display_name: NotRequired[str]
+    thinking_levels: NotRequired[list[str]]
+    default_thinking_level: NotRequired[str]
+
+class AgentThinkingEvent(TypedDict):
+    """Model thinking. content may be empty when the model only reports that it thought."""
+    type: Literal["agent.thinking"]
+    content: NotRequired[list[ContentBlock]]
+
+class AgentToolResultEvent(TypedDict):
+    """Result of an agent.tool_use."""
+    type: Literal["agent.tool_result"]
+    tool_use_id: str
+    content: NotRequired[list[ContentBlock]]
+    is_error: NotRequired[bool]
+
+class AgentToolUseEvent(TypedDict):
+    """A built-in or custom tool the local agent is calling. Its event_id is the tool_use_id."""
+    type: Literal["agent.tool_use"]
+    name: str
+    input: dict[str, Any]
+    evaluated_permission: NotRequired[EvaluatedPermission]
+
+class AgentTurnConfig(TypedDict):
+    """Requested (turn.start) or effective (TurnStartResult.effective) turn configuration. Every member is optional in a request; the executor reports the values it actually applied."""
+    model: NotRequired[str]
+    thinking_level: NotRequired[str]
+    permission_mode: NotRequired[str]
+    cwd: NotRequired[str]
+    system: NotRequired[str]
+
+class ArtifactCapability(TypedDict):
+    """v1.1 artifact upload (POST /v1/executors/artifacts). Environment-scoped executors only."""
+    upload: bool
+    max_bytes: NotRequired[int]
+
+class ArtifactRef(TypedDict):
+    """Artifact reference returned by POST /v1/executors/artifacts and listed in tool.result artifacts (v1.1 §6.5)."""
+    artifact_id: str
+    name: NotRequired[str]
+    mime_type: str
+    size_bytes: int
+    digest: str
+    created_at: NotRequired[str]
+
+class Capabilities(TypedDict):
+    """Executor capability object. The server only sends a method to an executor that advertised its capability; otherwise the executor answers -32012 capability_unavailable."""
+    shell: NotRequired[ShellCapability]
+    files: NotRequired[FilesCapability]
+    mcp: NotRequired[McpCapability]
+    chrome: NotRequired[bool]
+    computer_use: NotRequired[bool]
+    display: NotRequired[bool | DisplayCapability]
+    process: NotRequired[ProcessCapability]
+    artifacts: NotRequired[ArtifactCapability]
+    terminal: NotRequired[TerminalCapability]
+    skills: NotRequired[SkillsCapability]
+    workspace: NotRequired[WorkspaceCapability]
+    agent: NotRequired[AgentCapability]
+
+class ChannelScope(str, Enum):
+    """Channels a short-lived executor JWT may open."""
+    Control = "control"
+    Mcp = "mcp"
+
+class ComputerAction(str, Enum):
+    """Input actions accepted by the computer_action tool."""
+    Click = "click"
+    Type = "type"
+    Key = "key"
+    Scroll = "scroll"
+    Drag = "drag"
+
+class ConnectionState(str, Enum):
+    """Executor control channel state machine."""
+    Disconnected = "disconnected"
+    Connecting = "connecting"
+    Registered = "registered"
+    Ready = "ready"
+    Draining = "draining"
+    Closed = "closed"
+
+class ContentBlock(TypedDict):
+    """Tool result content block. An artifact block carries artifact_id and mime_type instead of text (v1.1 §6.5)."""
+    type: ContentBlockType
+    text: NotRequired[str]
+    data: NotRequired[str]
+    mime_type: NotRequired[str]
+    url: NotRequired[str]
+    artifact_id: NotRequired[str]
+
+class ContentBlockType(str, Enum):
+    """Tool result content block type."""
+    Text = "text"
+    Image = "image"
+    Resource = "resource"
+    Artifact = "artifact"
+
+class Cursors(TypedDict):
+    """Per-stream byte cursors."""
+    stdout: int
+    stderr: int
+
+class DisplayCapability(TypedDict):
+    """v1.1 display object. v1 sent a boolean; the server accepts both."""
+    rfb: NotRequired[bool]
+
+class EvaluatedPermission(TypedDict):
+    """Permission decision the executor applied to a tool use. ask means the executor opened an interaction.request for it."""
+    type: Literal["allow", "ask", "deny"]
+
+class EventDeltaType(str, Enum):
+    """Durable event type a streaming preview belongs to."""
+    AgentMessage = "agent.message"
+    AgentThinking = "agent.thinking"
+
+class ExecutorDrainResult(TypedDict):
+    """executor.drain result."""
+    accepted: bool
+    active_sessions: list[str]
+
+class ExecutorHeartbeatResult(TypedDict):
+    """executor.heartbeat result."""
+    server_time: str
+    lease_ttl_ms: int
+    drain: bool
+
+class ExecutorInfo(TypedDict):
+    """Executor identity reported at token bootstrap and registration."""
+    name: str
+    os: str
+    arch: str
+    version: str
+
+class ExecutorLoad(TypedDict):
+    """Advisory executor load reported with executor.heartbeat. The server does not act on it."""
+    cpu_percent: NotRequired[float]
+    memory_percent: NotRequired[float]
+
+class ExecutorRegisterResult(TypedDict):
+    """executor.register result. protocol and limits are v1.1 only."""
+    executor_id: str
+    connection_id: str
+    server_time: str
+    heartbeat_interval_ms: int
+    lease_ttl_ms: int
+    max_control_frame_bytes: int
+    max_mcp_frame_bytes: int
+    drain: bool
+    protocol: NotRequired[ProtocolVersion]
+    limits: NotRequired[Limits]
+
+class ExecutorResume(TypedDict):
+    """Reattach state sent on reconnect."""
+    executor_id: NotRequired[str]
+    last_connection_id: NotRequired[str]
+    active_sessions: NotRequired[list[str]]
+
+class ExecutorTokenRequest(TypedDict):
+    """POST /v1/executors/token body. The bearer is an environment key, or a machine daemon token. An empty environment_id with a machine token requests a machine-scoped executor: its executor_id is exec_<machine_id>, stable across refreshes, and the JWT carries machine_id and daemon_token_id."""
+    environment_id: str
+    executor: ExecutorInfo
+
+class ExecutorTokenResponse(TypedDict):
+    """POST /v1/executors/token response."""
+    executor_id: str
+    token: str
+    expires_in: int
+    ws_url: str
+    channel_scope: list[ChannelScope]
+
+class FileTransferDirection(str, Enum):
+    """File transfer direction relative to the machine."""
+    Upload = "upload"
+    Download = "download"
+
+class FileTransferError(TypedDict):
+    """Failed file transfer."""
+    code: str
+    error: str
+    current_digest: NotRequired[str]
+
+class FileTransferResult(TypedDict):
+    """Ended file transfer outcome: the uploaded path and digest, the downloaded digest, or an error."""
+    path: NotRequired[str]
+    digest: NotRequired[str]
+    error: NotRequired[FileTransferError]
+
+class FilesCapability(TypedDict):
+    """v1 file tools."""
+    enabled: bool
+    read_roots: NotRequired[list[str]]
+    write_roots: NotRequired[list[str]]
+
+class IOMode(str, Enum):
+    """process.start io_mode. "pty" runs the command on a 24x80 pseudo-terminal: stdout is the PTY output, stdin writes go to the PTY and close_stdin is rejected. Requires process.pty."""
+    Pty = "pty"
+
+class InteractionCancelReason(str, Enum):
+    """Why the executor withdrew an open interaction."""
+    ResolvedLocally = "resolved_locally"
+    TurnCanceled = "turn_canceled"
+    Expired = "expired"
+    ToolCanceled = "tool_canceled"
+
+class InteractionKind(str, Enum):
+    """Interaction kinds; they map 1:1 to platform agent interactions."""
+    Permission = "permission"
+    Question = "question"
+
+class InteractionOutcome(str, Enum):
+    """How the platform resolved an interaction. allow/deny answer permission, answered answers question, expired and canceled close either kind without an answer."""
+    Allow = "allow"
+    Deny = "deny"
+    Answered = "answered"
+    Expired = "expired"
+    Canceled = "canceled"
+
+class InteractionQuestion(TypedDict):
+    """Question shown to the user."""
+    prompt: str
+    options: NotRequired[list[InteractionQuestionOption]]
+    multi_select: NotRequired[bool]
+    allow_free_text: NotRequired[bool]
+
+class InteractionQuestionOption(TypedDict):
+    """One answer option of a question interaction."""
+    id: str
+    label: str
+
+class InteractionRequestResult(TypedDict):
+    """interaction.request result. Idempotent by interaction_id: a repeat returns the same platform interaction."""
+    accepted: bool
+    platform_interaction_id: str
+
+class InteractionResponder(TypedDict):
+    """Who answered, for local audit. surface is the client that resolved it, for example desktop, mobile, web, slack."""
+    actor_id: NotRequired[str]
+    surface: NotRequired[str]
+
+class InteractionResponseResult(TypedDict):
+    """interaction.response result. accepted=false when the interaction is unknown or already resolved (first answer wins); the platform then marks its copy stale."""
+    accepted: bool
+
+class InteractionScope(str, Enum):
+    """How long a permission grant lasts on the executor: this tool use only, or the rest of the session."""
+    Once = "once"
+    Session = "session"
+
+class JsonRpcError(TypedDict):
+    """JSON-RPC 2.0 error object."""
+    code: JsonRpcErrorCode
+    message: str
+    data: NotRequired[JsonRpcErrorData]
+
+class JsonRpcErrorCode(IntEnum):
+    """Executor protocol JSON-RPC error codes. -32011..-32013 are v1.1 additions."""
+    ParseError = -32700
+    InvalidRequest = -32600
+    MethodNotFound = -32601
+    InvalidParams = -32602
+    InternalError = -32603
+    Unauthorized = -32000
+    Forbidden = -32001
+    NotFound = -32002
+    LeaseExpired = -32003
+    Timeout = -32004
+    Canceled = -32005
+    PayloadTooLarge = -32006
+    SessionNotActive = -32007
+    McpUnavailable = -32008
+    ExecutorBusy = -32009
+    UnsupportedProtocol = -32010
+    ResourceUnavailable = -32011
+    CapabilityUnavailable = -32012
+    Conflict = -32013
+
+class JsonRpcErrorData(TypedDict):
+    """JSON-RPC error.data. Members are code-specific; unknown members are ignored."""
+    retryable: NotRequired[bool]
+    detail: NotRequired[str]
+    capability: NotRequired[str]
+    reason: NotRequired[str]
+    terminal_code: NotRequired[str]
+    expected_sequence: NotRequired[int]
+
+class JsonRpcErrorResponse(TypedDict):
+    """JSON-RPC 2.0 error response envelope."""
+    jsonrpc: Literal["2.0"]
+    id: JsonRpcId
+    error: JsonRpcError
+
+class JsonRpcNotification(TypedDict):
+    """JSON-RPC 2.0 notification envelope (no id)."""
+    jsonrpc: Literal["2.0"]
+    method: str
+    params: dict[str, Any]
+
+class JsonRpcRequest(TypedDict):
+    """JSON-RPC 2.0 request envelope."""
+    jsonrpc: Literal["2.0"]
+    id: JsonRpcId
+    method: str
+    params: dict[str, Any]
+
+class JsonRpcSuccessResponse(TypedDict):
+    """JSON-RPC 2.0 success response envelope."""
+    jsonrpc: Literal["2.0"]
+    id: JsonRpcId
+    result: Any
+
+class Lease(TypedDict):
+    """Fencing lease for a session assignment."""
+    token: str
+    fencing_token: int
+
+class Limits(TypedDict):
+    """Limits the executor must enforce, advertised in the v1.1 executor.register result (v1.1 §1.3)."""
+    max_inflight_requests: int
+    max_concurrent_process_reads: int
+    max_process_read_bytes: int
+    max_process_write_bytes: int
+    max_processes_per_session: int
+    max_artifact_bytes: int
+
+class McpCapability(TypedDict):
+    """Environment-origin MCP servers."""
+    stdio: NotRequired[bool]
+    http: NotRequired[bool]
+    max_servers: NotRequired[int]
+
+class McpConnectionOrigin(str, Enum):
+    """Who connects the MCP server. environment means the executor starts/connects it; service means the harness connects."""
+    Service = "service"
+    Environment = "environment"
+
+class McpContentBlock(TypedDict):
+    """MCP tool content block. Large binary content must go to artifact storage."""
+    type: Literal["text", "image", "resource"]
+    text: NotRequired[str]
+    data: NotRequired[str]
+    mimeType: NotRequired[str]
+    resource: NotRequired[Any]
+
+class McpImplementation(TypedDict):
+    name: str
+    version: str
+
+class McpInitializeParams(TypedDict):
+    protocolVersion: str
+    capabilities: dict[str, Any]
+    clientInfo: McpImplementation
+
+class McpInitializeResult(TypedDict):
+    protocolVersion: str
+    capabilities: dict[str, Any]
+    serverInfo: McpImplementation
+
+class McpJsonRpcError(TypedDict):
+    code: int
+    message: str
+    data: NotRequired[Any]
+
+class McpJsonRpcErrorResponse(TypedDict):
+    jsonrpc: Literal["2.0"]
+    id: McpJsonRpcId
+    error: McpJsonRpcError
+
+class McpJsonRpcNotification(TypedDict):
+    jsonrpc: Literal["2.0"]
+    method: str
+    params: NotRequired[dict[str, Any]]
+
+class McpJsonRpcRequest(TypedDict):
+    jsonrpc: Literal["2.0"]
+    id: McpJsonRpcId
+    method: str
+    params: NotRequired[dict[str, Any]]
+
+class McpJsonRpcSuccessResponse(TypedDict):
+    jsonrpc: Literal["2.0"]
+    id: McpJsonRpcId
+    result: Any
+
+class McpProgressParams(TypedDict):
+    progressToken: str | int
+    progress: float
+    total: NotRequired[float]
+
+class McpServerConfig(TypedDict):
+    server_key: str
+    connection_origin: McpConnectionOrigin
+    transport: McpServerTransport
+
+class McpServerTransport(TypedDict):
+    """Transport for one MCP server. stdio requires command; http requires url. Fields for the other transport are omitted."""
+    type: McpTransportType
+    command: NotRequired[str]
+    args: NotRequired[list[str]]
+    cwd: NotRequired[str]
+    env: NotRequired[dict[str, str]]
+    timeout_ms: NotRequired[int]
+    command_sha256: NotRequired[str]
+    url: NotRequired[str]
+
+class McpTool(TypedDict):
+    name: str
+    description: NotRequired[str]
+    inputSchema: dict[str, Any]
+
+class McpToolsCallParams(TypedDict):
+    name: str
+    arguments: dict[str, Any]
+
+class McpToolsCallResult(TypedDict):
+    content: list[McpContentBlock]
+    isError: NotRequired[bool]
+    structuredContent: NotRequired[Any]
+
+class McpToolsListParams(TypedDict):
+    cursor: NotRequired[str]
+
+class McpToolsListResult(TypedDict):
+    tools: list[McpTool]
+    nextCursor: NotRequired[str | None]
+
+class McpTransportType(str, Enum):
+    Stdio = "stdio"
+    Http = "http"
+
+class PermissionMode(str, Enum):
+    """Tool permission mode; always_ask means the harness already resolved approval."""
+    AlwaysAllow = "always_allow"
+    AlwaysAsk = "always_ask"
+
+class ProcessCapability(TypedDict):
+    """v1.1 process.* support. pty, file_transfer and git_credentials are additive: the harness only sends the matching process.start fields to an executor that set them, and fails the process explicitly otherwise."""
+    enabled: bool
+    max_processes: NotRequired[int]
+    buffer_bytes: NotRequired[int]
+    pty: NotRequired[bool]
+    file_transfer: NotRequired[bool]
+    git_credentials: NotRequired[bool]
+
+class ProcessFileTransfer(TypedDict):
+    """Replaces argv: the executor moves one file between the machine and the process BMA file endpoint and reports the outcome in ProcessState.file_transfer. Requires process.file_transfer."""
+    direction: FileTransferDirection
+    local_path: str
+
+class ProcessListResult(TypedDict):
+    """process.list result."""
+    processes: list[ProcessState]
+
+class ProcessReadResult(TypedDict):
+    """process.read result."""
+    process_id: str
+    stream: ProcessStream
+    data: str
+    from_cursor: int
+    next_cursor: int
+    earliest_cursor: int
+    gap: bool
+    truncated: bool
+    eof: bool
+    state: ProcessStateName
+    ended_at: NotRequired[str]
+    reason: NotRequired[str]
+    exit_code: int | None
+    exit_signal: str | None
+    file_transfer: NotRequired[FileTransferResult]
+
+class ProcessState(TypedDict):
+    """Result of process.start/interrupt/terminate and one process.list entry. ended_at (RFC 3339, executor clock) is set once the process is no longer running; reason explains a "failed" state (for example "timeout"). A spawn failure never creates a state: it is the process.start error with data.reason "spawn_failed"."""
+    process_id: str
+    state: ProcessStateName
+    pid: NotRequired[int]
+    started_at: NotRequired[str]
+    ended_at: NotRequired[str]
+    reason: NotRequired[str]
+    cursors: Cursors
+    exit_code: int | None
+    exit_signal: str | None
+    stderr: NotRequired[str]
+    accepted: NotRequired[bool]
+    file_transfer: NotRequired[FileTransferResult]
+
+class ProcessStateName(str, Enum):
+    """Process state (v1.1 §3.3)."""
+    Running = "running"
+    Exited = "exited"
+    Failed = "failed"
+    Killed = "killed"
+
+class ProcessStream(str, Enum):
+    """Process output stream (v1.1 §3.2)."""
+    Stdout = "stdout"
+    Stderr = "stderr"
+
+class ProcessWriteResult(TypedDict):
+    """process.write result."""
+    accepted: bool
+
+class ProtocolVersion(str, Enum):
+    """Value of both the WebSocket subprotocol and executor.register protocol. A v1.1 server serves v1 executors and never sends them v1.1 methods."""
+    BmaExecutorV1 = "bma.executor.v1"
+    BmaExecutorV11 = "bma.executor.v1.1"
+
+class SessionAssignResult(TypedDict):
+    """session.assign result."""
+    accepted: bool
+    session_id: str
+
+class SessionCloseResult(TypedDict):
+    """session.close result."""
+    closed: bool
+
+class SessionErrorEvent(TypedDict):
+    """A turn-level error. A failed turn still ends with session.status_idle turn_outcome=failed."""
+    type: Literal["session.error"]
+    error: AgentErrorInfo
+
+class SessionEvent(TypedDict):
+    """Durable session event emitted by the executor."""
+    type: SessionEventType
+    tool_use_id: NotRequired[str]
+    content: NotRequired[list[ContentBlock]]
+    is_error: NotRequired[bool]
+
+class SessionEventResult(TypedDict):
+    """session.event result."""
+    accepted: bool
+    event_id: str
+    acked_sequence: NotRequired[int]
+
+class SessionEventType(str, Enum):
+    """Durable event types an executor may emit. Event names follow Anthropic Managed Agents; the executor must not invent new names. A tool executor emits agent.tool_result only; an agent executor (capability agent) emits every type, shaped as schemas/agent.json AgentEvent."""
+    AgentToolResult = "agent.tool_result"
+    AgentMessage = "agent.message"
+    AgentThinking = "agent.thinking"
+    AgentToolUse = "agent.tool_use"
+    AgentMcpToolUse = "agent.mcp_tool_use"
+    AgentMcpToolResult = "agent.mcp_tool_result"
+    SessionStatusRunning = "session.status_running"
+    SessionStatusIdle = "session.status_idle"
+    SessionError = "session.error"
+
+class SessionMemoryResource(TypedDict):
+    """A memory store mounted into the session workspace."""
+    type: Literal["memory_store"]
+    memory_store_id: str
+    mount_path: str
+
+class SessionStatus(str, Enum):
+    """Lifecycle status reported by the executor."""
+    Starting = "starting"
+    Running = "running"
+    Idle = "idle"
+    Stopping = "stopping"
+    Stopped = "stopped"
+    Error = "error"
+
+class SessionStatusIdleEvent(TypedDict):
+    """The turn ended. It is the last event of its turn_id; the platform publishes the turn as finished only after it accepted this event and every lower sequence."""
+    type: Literal["session.status_idle"]
+    stop_reason: StopReason
+    turn_outcome: TurnOutcome
+
+class SessionStatusRunningEvent(TypedDict):
+    """The local agent started working on the turn."""
+    type: Literal["session.status_running"]
+
+class SessionStopResult(TypedDict):
+    """session.stop result."""
+    stopped: bool
+
+class ShellCapability(TypedDict):
+    """v1 one-shot shell tools."""
+    enabled: bool
+
+class SkillInstallResult(TypedDict):
+    """skill.install result. state is "ready", or "failed" with error_code and error."""
+    state: Literal["ready", "failed"]
+    error_code: NotRequired[str]
+    error: NotRequired[str]
+
+class SkillsCapability(TypedDict):
+    """skill.install support. Machine-scoped executors only."""
+    install: bool
+
+class StderrMode(str, Enum):
+    """process.start stderr mode. "merge" redirects stderr into stdout at the OS level so one cursor covers both."""
+    Merge = "merge"
+
+class StdinMode(str, Enum):
+    """process.start stdin mode. Empty or "closed" closes stdin at start; "open" keeps it open for process.write."""
+    Open = "open"
+    Closed = "closed"
+
+class StopReason(TypedDict):
+    """Why the turn stopped."""
+    type: StopReasonType
+
+class StopReasonType(str, Enum):
+    """Anthropic stop_reason types an executor may report. requires_action is not in the list: the platform projects it from open interactions."""
+    EndTurn = "end_turn"
+    RetriesExhausted = "retries_exhausted"
+
+class TerminalAttachResult(TypedDict):
+    """terminal.attach result, returned after the host socket is connected and the attached frame was written on it."""
+    accepted: bool
+    writer_epoch: int
+
+class TerminalCapability(TypedDict):
+    """v1.1 terminal.* support. Machine-scoped executors only."""
+    enabled: bool
+    kinds: NotRequired[list[str]]
+    max_sessions: NotRequired[int]
+
+class TerminalCloseResult(TypedDict):
+    """terminal.close result. Idempotent: closing an unknown or closed terminal returns closed=true."""
+    closed: bool
+    exit_code: NotRequired[int | None]
+
+class TerminalErrorData(TypedDict):
+    """JSON-RPC error.data of a failed terminal.* call. terminal_code is the bma.terminal.v1 code the harness relays to the attach (for example terminal_writer_busy)."""
+    terminal_code: NotRequired[str]
+
+class TerminalHost(TypedDict):
+    """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."""
+    url: str
+    ticket: str
+
+class TerminalOpenResult(TypedDict):
+    """terminal.open result. epoch starts at 1 and increments when the executor recreates the PTY under the same terminal_id; attach is fenced by it."""
+    terminal_id: str
+    epoch: int
+    pid: int
+    rows: int
+    cols: int
+    earliest_seq: int
+    latest_seq: int
+    created_at: str
+
+class ToolCancelResult(TypedDict):
+    """tool.cancel result."""
+    canceled: bool
+
+class ToolInput(TypedDict):
+    """Built-in tool input. The selected tool decides which members are meaningful; unknown members are ignored."""
+    command: NotRequired[str]
+    cwd: NotRequired[str]
+    timeout_ms: NotRequired[int]
+    env: NotRequired[dict[str, str]]
+    path: NotRequired[str]
+    offset: NotRequired[int]
+    limit: NotRequired[int]
+    content: NotRequired[str]
+    old_string: NotRequired[str]
+    new_string: NotRequired[str]
+    pattern: NotRequired[str]
+    glob: NotRequired[str]
+    display: NotRequired[str]
+    action: NotRequired[ComputerAction]
+
+class ToolName(str, Enum):
+    """Built-in tool names. bmad serves bash only and answers -32012 for the rest."""
+    Bash = "bash"
+    Read = "read"
+    Write = "write"
+    Edit = "edit"
+    Glob = "glob"
+    Grep = "grep"
+    ListFiles = "list_files"
+    ComputerObserve = "computer_observe"
+    ComputerAction = "computer_action"
+
+class ToolOutcome(str, Enum):
+    """Tool outcome."""
+    Succeeded = "succeeded"
+    Failed = "failed"
+    Canceled = "canceled"
+
+class ToolPermission(TypedDict):
+    """Tool permission resolved by the harness."""
+    mode: PermissionMode
+
+class TurnCancelResult(TypedDict):
+    """turn.cancel result. canceled=false when the turn is unknown or already ended; the turn still ends with its own session.status_idle event."""
+    canceled: bool
+
+class TurnOutcome(str, Enum):
+    """BMA extension on session.status_idle: how the turn ended."""
+    Completed = "completed"
+    Canceled = "canceled"
+    Failed = "failed"
+
+class TurnStartResult(TypedDict):
+    """turn.start result. Idempotent by turn_id: a repeated turn.start for a turn the executor already accepted returns the same result without starting a second run."""
+    accepted: bool
+    turn_id: str
+    executor_session_ref: str
+    resumed: bool
+    effective: AgentTurnConfig
+
+class WorkspaceBackupResult(TypedDict):
+    """workspace.backup result. digest and size_bytes describe the archive as the server stored it; skipped counts entries that could not be read (missing from the archive)."""
+    state: Literal["uploaded", "unchanged", "failed"]
+    fingerprint: NotRequired[str]
+    digest: NotRequired[str]
+    size_bytes: NotRequired[int]
+    entries: NotRequired[int]
+    skipped: NotRequired[int]
+    error: NotRequired[str]
+
+class WorkspaceCapability(TypedDict):
+    """workspace.backup support and the startup restore of a pending backup. Machine-scoped executors only."""
+    backup: bool
+
+AgentEvent = AgentMessageEvent | AgentThinkingEvent | AgentToolUseEvent | AgentToolResultEvent | AgentMcpToolUseEvent | AgentMcpToolResultEvent | SessionStatusRunningEvent | SessionStatusIdleEvent | SessionErrorEvent
+
+JsonRpcId = str
+
+McpJsonRpcId = str | int
+
+class ExecutorRegisterParams(TypedDict):
+    "Params object of executor.register."
+    protocol: ProtocolVersion
+    environment_id: str
+    executor: ExecutorInfo
+    capabilities: Capabilities
+    resume: NotRequired[ExecutorResume]
+
+class ExecutorHeartbeatParams(TypedDict):
+    "Params object of executor.heartbeat."
+    connection_id: str
+    active_sessions: list[str]
+    load: NotRequired[ExecutorLoad]
+
+class ExecutorCapabilitiesUpdateParams(TypedDict):
+    "Params object of executor.capabilities.update."
+    capabilities: Capabilities
+
+class ExecutorDrainParams(TypedDict):
+    "Params object of executor.drain."
+    reason: str
+    deadline_ms: NotRequired[int]
+
+class ExecutorCloseParams(TypedDict):
+    "Params object of executor.close."
+    reason: str
+
+class SessionAssignParams(TypedDict):
+    "Params object of session.assign."
+    session_id: str
+    work_id: str
+    agent_id: NotRequired[str]
+    environment_id: str
+    deadline_ms: NotRequired[int]
+    lease: Lease
+    resources: NotRequired[list[SessionMemoryResource]]
+    mcp_servers: NotRequired[list[McpServerConfig]]
+    metadata: NotRequired[dict[str, str]]
+
+class SessionReadyParams(TypedDict):
+    "Params object of session.ready."
+    session_id: str
+    work_id: str
+    lease_token: str
+
+class SessionEventParams(TypedDict):
+    "Params object of session.event."
+    session_id: str
+    turn_id: NotRequired[str]
+    event_id: NotRequired[str]
+    sequence: NotRequired[int]
+    event: SessionEvent
+
+class SessionStatusParams(TypedDict):
+    "Params object of session.status."
+    session_id: str
+    status: SessionStatus
+    detail: NotRequired[str]
+
+class SessionStopParams(TypedDict):
+    "Params object of session.stop."
+    session_id: str
+    reason: str
+    deadline_ms: NotRequired[int]
+
+class SessionEndedParams(TypedDict):
+    "Params object of session.ended."
+    session_id: str
+    reason: str
+
+class ToolCallParams(TypedDict):
+    "Params object of tool.call."
+    session_id: str
+    tool_call_id: str
+    tool: ToolName
+    input: ToolInput
+    deadline_ms: NotRequired[int]
+    permission: NotRequired[ToolPermission]
+
+class ToolResultParams(TypedDict):
+    "Params object of tool.result."
+    session_id: str
+    tool_call_id: str
+    outcome: ToolOutcome
+    is_error: bool
+    content: list[ContentBlock]
+    duration_ms: NotRequired[int]
+    artifacts: NotRequired[list[ArtifactRef]]
+
+class ToolCancelParams(TypedDict):
+    "Params object of tool.cancel."
+    session_id: str
+    tool_call_id: str
+    reason: NotRequired[str]
+
+class ToolProgressParams(TypedDict):
+    "Params object of tool.progress."
+    session_id: str
+    tool_call_id: str
+    message: str
+
+class ProcessStartParams(TypedDict):
+    "Params object of process.start."
+    session_id: str
+    process_id: str
+    argv: list[str]
+    cwd: NotRequired[str]
+    env: NotRequired[dict[str, str]]
+    stdin: NotRequired[StdinMode]
+    stderr: NotRequired[StderrMode]
+    wait_ms: NotRequired[int]
+    timeout_ms: NotRequired[int]
+    metadata: NotRequired[dict[str, str]]
+    io_mode: NotRequired[IOMode]
+    file_transfer: NotRequired[ProcessFileTransfer]
+    git_credentials: NotRequired[bool]
+
+class ProcessReadParams(TypedDict):
+    "Params object of process.read."
+    session_id: str
+    process_id: str
+    stream: ProcessStream
+    cursor: int
+    max_bytes: NotRequired[int]
+    wait_ms: NotRequired[int]
+
+class ProcessWriteParams(TypedDict):
+    "Params object of process.write."
+    session_id: str
+    process_id: str
+    data: NotRequired[str]
+    close_stdin: NotRequired[bool]
+
+class ProcessSignalParams(TypedDict):
+    "Params object of process.interrupt and process.terminate."
+    session_id: str
+    process_id: str
+    grace_ms: NotRequired[int | None]
+
+class ProcessListParams(TypedDict):
+    "Params object of process.list."
+    session_id: str
+
+class ProcessStatusParams(TypedDict):
+    "Params object of process.status."
+    session_id: str
+    process_id: str
+    state: ProcessStateName
+    exit_code: NotRequired[int | None]
+    exit_signal: NotRequired[str | None]
+    ended_at: NotRequired[str]
+    reason: NotRequired[str]
+    observed_at: str
+
+class TerminalOpenParams(TypedDict):
+    "Params object of terminal.open."
+    terminal_id: str
+    kind: str
+    shell: NotRequired[str]
+    argv: NotRequired[list[str]]
+    cwd: NotRequired[str]
+    env: NotRequired[dict[str, str]]
+    rows: NotRequired[int]
+    cols: NotRequired[int]
+
+class TerminalAttachParams(TypedDict):
+    "Params object of terminal.attach."
+    terminal_id: str
+    epoch: int
+    stream_id: str
+    can_write: bool
+    from_seq: int
+    ack_seq: int
+    host: TerminalHost
+
+class TerminalCloseParams(TypedDict):
+    "Params object of terminal.close."
+    terminal_id: str
+    reason: NotRequired[str]
+
+class SkillInstallParams(TypedDict):
+    "Params object of skill.install."
+    machine_id: str
+    skill_id: str
+    revision_id: str
+    digest: str
+    download_token: str
+    download_expires_at: int
+
+class WorkspaceBackupParams(TypedDict):
+    "Params object of workspace.backup."
+    backup_id: str
+    paths: list[str]
+    exclude: NotRequired[list[str]]
+    skip_if_fingerprint: NotRequired[str]
+
+class TurnStartParams(TypedDict):
+    "Params object of turn.start."
+    session_id: str
+    turn_id: str
+    input_id: str
+    input: list[AgentInputBlock]
+    executor_session_ref: NotRequired[str]
+    config: NotRequired[AgentTurnConfig]
+    deadline_ms: NotRequired[int]
+    metadata: NotRequired[dict[str, str]]
+
+class TurnInputParams(TypedDict):
+    "Params object of turn.input."
+    session_id: str
+    turn_id: str
+    input_id: str
+    input: list[AgentInputBlock]
+
+class TurnCancelParams(TypedDict):
+    "Params object of turn.cancel."
+    session_id: str
+    turn_id: str
+    reason: NotRequired[str]
+
+class SessionCloseParams(TypedDict):
+    "Params object of session.close."
+    session_id: str
+    reason: str
+
+class SessionEventDeltaParams(TypedDict):
+    "Params object of session.event_delta."
+    session_id: str
+    turn_id: str
+    event_id: str
+    event_type: EventDeltaType
+    index: int
+    text: str
+
+class InteractionRequestParams(TypedDict):
+    "Params object of interaction.request."
+    session_id: str
+    turn_id: str
+    interaction_id: str
+    kind: InteractionKind
+    tool_use_id: NotRequired[str]
+    tool_name: NotRequired[str]
+    tool_input: NotRequired[dict[str, Any]]
+    scopes: NotRequired[list[InteractionScope]]
+    question: NotRequired[InteractionQuestion]
+    expires_at: NotRequired[str]
+
+class InteractionResponseParams(TypedDict):
+    "Params object of interaction.response."
+    session_id: str
+    interaction_id: str
+    outcome: InteractionOutcome
+    scope: NotRequired[InteractionScope]
+    deny_message: NotRequired[str]
+    answers: NotRequired[list[str]]
+    responder: NotRequired[InteractionResponder]
+
+class InteractionCancelParams(TypedDict):
+    "Params object of interaction.cancel."
+    session_id: str
+    interaction_id: str
+    reason: InteractionCancelReason
+
+
+@dataclass(frozen=True, slots=True)
+class MethodSpec:
+    "since is the first protocol that has the method; result_type is the Python type expression of a request result; capability is the capability bit the harness checks before sending it."
+
+    name: str
+    direction: str
+    kind: str
+    since: str
+    params_type: str
+    result_type: str | None = None
+    capability: str | None = None
+    idempotent_by: str | None = None
+
+
+METHOD_EXECUTOR_REGISTER = "executor.register"
+METHOD_EXECUTOR_HEARTBEAT = "executor.heartbeat"
+METHOD_EXECUTOR_CAPABILITIES_UPDATE = "executor.capabilities.update"
+METHOD_EXECUTOR_DRAIN = "executor.drain"
+METHOD_EXECUTOR_CLOSE = "executor.close"
+METHOD_SESSION_ASSIGN = "session.assign"
+METHOD_SESSION_READY = "session.ready"
+METHOD_SESSION_EVENT = "session.event"
+METHOD_SESSION_STATUS = "session.status"
+METHOD_SESSION_STOP = "session.stop"
+METHOD_SESSION_ENDED = "session.ended"
+METHOD_TOOL_CALL = "tool.call"
+METHOD_TOOL_RESULT = "tool.result"
+METHOD_TOOL_CANCEL = "tool.cancel"
+METHOD_TOOL_PROGRESS = "tool.progress"
+METHOD_PROCESS_START = "process.start"
+METHOD_PROCESS_READ = "process.read"
+METHOD_PROCESS_WRITE = "process.write"
+METHOD_PROCESS_INTERRUPT = "process.interrupt"
+METHOD_PROCESS_TERMINATE = "process.terminate"
+METHOD_PROCESS_LIST = "process.list"
+METHOD_PROCESS_STATUS = "process.status"
+METHOD_TERMINAL_OPEN = "terminal.open"
+METHOD_TERMINAL_ATTACH = "terminal.attach"
+METHOD_TERMINAL_CLOSE = "terminal.close"
+METHOD_SKILL_INSTALL = "skill.install"
+METHOD_WORKSPACE_BACKUP = "workspace.backup"
+METHOD_TURN_START = "turn.start"
+METHOD_TURN_INPUT = "turn.input"
+METHOD_TURN_CANCEL = "turn.cancel"
+METHOD_SESSION_CLOSE = "session.close"
+METHOD_SESSION_EVENT_DELTA = "session.event_delta"
+METHOD_INTERACTION_REQUEST = "interaction.request"
+METHOD_INTERACTION_RESPONSE = "interaction.response"
+METHOD_INTERACTION_CANCEL = "interaction.cancel"
+
+METHODS: dict[str, MethodSpec] = {
+    "executor.register": MethodSpec(name="executor.register", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="ExecutorRegisterParams", result_type="ExecutorRegisterResult", capability=None, idempotent_by=None),
+    "executor.heartbeat": MethodSpec(name="executor.heartbeat", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="ExecutorHeartbeatParams", result_type="ExecutorHeartbeatResult", capability=None, idempotent_by=None),
+    "executor.capabilities.update": MethodSpec(name="executor.capabilities.update", direction="executor-to-harness", kind="notification", since="bma.executor.v1", params_type="ExecutorCapabilitiesUpdateParams", result_type=None, capability=None, idempotent_by=None),
+    "executor.drain": MethodSpec(name="executor.drain", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="ExecutorDrainParams", result_type="ExecutorDrainResult", capability=None, idempotent_by=None),
+    "executor.close": MethodSpec(name="executor.close", direction="bidirectional", kind="notification", since="bma.executor.v1", params_type="ExecutorCloseParams", result_type=None, capability=None, idempotent_by=None),
+    "session.assign": MethodSpec(name="session.assign", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="SessionAssignParams", result_type="SessionAssignResult", capability=None, idempotent_by=None),
+    "session.ready": MethodSpec(name="session.ready", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="SessionReadyParams", result_type="Ack", capability=None, idempotent_by=None),
+    "session.event": MethodSpec(name="session.event", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="SessionEventParams", result_type="SessionEventResult", capability=None, idempotent_by="jsonrpc_id"),
+    "session.status": MethodSpec(name="session.status", direction="executor-to-harness", kind="notification", since="bma.executor.v1", params_type="SessionStatusParams", result_type=None, capability=None, idempotent_by=None),
+    "session.stop": MethodSpec(name="session.stop", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="SessionStopParams", result_type="SessionStopResult", capability=None, idempotent_by=None),
+    "session.ended": MethodSpec(name="session.ended", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="SessionEndedParams", result_type="Ack", capability=None, idempotent_by=None),
+    "tool.call": MethodSpec(name="tool.call", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="ToolCallParams", result_type="Ack", capability=None, idempotent_by=None),
+    "tool.result": MethodSpec(name="tool.result", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="ToolResultParams", result_type="Ack", capability=None, idempotent_by="tool_call_id"),
+    "tool.cancel": MethodSpec(name="tool.cancel", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="ToolCancelParams", result_type="ToolCancelResult", capability=None, idempotent_by=None),
+    "tool.progress": MethodSpec(name="tool.progress", direction="executor-to-harness", kind="notification", since="bma.executor.v1", params_type="ToolProgressParams", result_type=None, capability=None, idempotent_by=None),
+    "process.start": MethodSpec(name="process.start", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessStartParams", result_type="ProcessState", capability="process.enabled", idempotent_by="session_id+process_id"),
+    "process.read": MethodSpec(name="process.read", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessReadParams", result_type="ProcessReadResult", capability="process.enabled", idempotent_by=None),
+    "process.write": MethodSpec(name="process.write", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessWriteParams", result_type="ProcessWriteResult", capability="process.enabled", idempotent_by=None),
+    "process.interrupt": MethodSpec(name="process.interrupt", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessSignalParams", result_type="ProcessState", capability="process.enabled", idempotent_by=None),
+    "process.terminate": MethodSpec(name="process.terminate", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessSignalParams", result_type="ProcessState", capability="process.enabled", idempotent_by=None),
+    "process.list": MethodSpec(name="process.list", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="ProcessListParams", result_type="ProcessListResult", capability="process.enabled", idempotent_by=None),
+    "process.status": MethodSpec(name="process.status", direction="executor-to-harness", kind="notification", since="bma.executor.v1.1", params_type="ProcessStatusParams", result_type=None, capability="process.enabled", idempotent_by=None),
+    "terminal.open": MethodSpec(name="terminal.open", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TerminalOpenParams", result_type="TerminalOpenResult", capability="terminal.enabled", idempotent_by="terminal_id"),
+    "terminal.attach": MethodSpec(name="terminal.attach", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TerminalAttachParams", result_type="TerminalAttachResult", capability="terminal.enabled", idempotent_by=None),
+    "terminal.close": MethodSpec(name="terminal.close", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TerminalCloseParams", result_type="TerminalCloseResult", capability="terminal.enabled", idempotent_by="terminal_id"),
+    "skill.install": MethodSpec(name="skill.install", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="SkillInstallParams", result_type="SkillInstallResult", capability="skills.install", idempotent_by="skill_id+revision_id+digest"),
+    "workspace.backup": MethodSpec(name="workspace.backup", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="WorkspaceBackupParams", result_type="WorkspaceBackupResult", capability="workspace.backup", idempotent_by="backup_id"),
+    "turn.start": MethodSpec(name="turn.start", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnStartParams", result_type="TurnStartResult", capability="agent", idempotent_by="turn_id"),
+    "turn.input": MethodSpec(name="turn.input", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnInputParams", result_type="Ack", capability="agent", idempotent_by="input_id"),
+    "turn.cancel": MethodSpec(name="turn.cancel", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnCancelParams", result_type="TurnCancelResult", capability="agent", idempotent_by=None),
+    "session.close": MethodSpec(name="session.close", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="SessionCloseParams", result_type="SessionCloseResult", capability="agent", idempotent_by=None),
+    "session.event_delta": MethodSpec(name="session.event_delta", direction="executor-to-harness", kind="notification", since="bma.executor.v1.1", params_type="SessionEventDeltaParams", result_type=None, capability="agent", idempotent_by=None),
+    "interaction.request": MethodSpec(name="interaction.request", direction="executor-to-harness", kind="request", since="bma.executor.v1.1", params_type="InteractionRequestParams", result_type="InteractionRequestResult", capability="agent", idempotent_by="interaction_id"),
+    "interaction.response": MethodSpec(name="interaction.response", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="InteractionResponseParams", result_type="InteractionResponseResult", capability="agent", idempotent_by="interaction_id"),
+    "interaction.cancel": MethodSpec(name="interaction.cancel", direction="executor-to-harness", kind="request", since="bma.executor.v1.1", params_type="InteractionCancelParams", result_type="Ack", capability="agent", idempotent_by="interaction_id"),
+}