@beeos-ai/bma-executor-sdk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# @beeos-ai/bma-executor-sdk (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Executor (`ExecutorClient`), harness (`Harness`) and agent ends of the BMA
+executor protocol `bma.executor.v1.1`, with protocol types generated from the
+BMA contract (`contracts/bma/executor`). Transports: WebSocket, WebSocket over
+a Unix domain socket or Windows named pipe (`unix://`, `npipe://`), in-process.
+Node >= 20.
+
+```sh
+npm install @beeos-ai/bma-executor-sdk
+```
+
+The REST/façade client is the separate
+`@beeos-ai/bma-sdk` package.
+
+## Usage
+
+The executor protocol (`bma.executor.v1.1` and `v1`) for Node.js 20+, with
+the same three parts and behavior as [Go `executor`](..). Protocol
+types are generated from the contract
+([`src/generated/executor.ts`](src/generated/executor.ts), snapshot and lock in
+[`contracts/bma/executor`](../contracts/bma/executor)); the runtime is
+handwritten.
+
+### Executor quick start
+
+```ts
+import { ExecutorClient } from "@beeos-ai/bma-executor-sdk";
+
+const client = new ExecutorClient({
+  environmentKey: process.env.BMA_ENVIRONMENT_KEY,
+  environmentId: process.env.BMA_ENVIRONMENT_ID!,
+  executor: { name: "my-executor", os: process.platform, arch: process.arch, version: "0.1.0" },
+  capabilities: { shell: { enabled: true } },
+});
+client.handleTool("bash", async (call, { signal, progress }) => {
+  progress("running");
+  return { outcome: "succeeded", is_error: false, content: [{ type: "text", text: "ok" }] };
+});
+await client.start();
+```
+
+### Executor lifecycle, cancellation, and results
+
+- `tool.cancel` aborts the handler's `signal` (so do `deadline_ms` and
+  `stop()`); the client answers `{"canceled":true}` and reports
+  `outcome: "canceled"`. A repeated `tool.call` id is acknowledged, not run
+  twice. `handleTool(name, …)` routes one tool, `onToolCall` the rest.
+- Call `sessionReady` after workspace/MCP setup and `sessionEnded` after
+  cleanup. `tool.result` is retried on `-32009`, `-32004` or
+  `data.retryable: true`, idempotent by `tool_call_id`; when every attempt
+  fails `onToolResultLost` receives the result to persist and replay.
+- Reconnect: exponential backoff (500 ms base, ×2, 30 s cap, jitter) with a
+  fresh token per dial and `resume` (`executor_id`, `last_connection_id`,
+  `active_sessions`). Close codes 1008, 4002, 4003, 4004 and 4005 are terminal;
+  4001 (token expired) reconnects with a new token.
+- `openMcpChannel(sessionId, serverKey)` opens the raw MCP channel
+  (`?channel=mcp&session_id=&server_key=`); `read()`/`write()` carry MCP
+  JSON-RPC frames unchanged.
+- A handler that throws `RpcError` keeps its code and data on the wire.
+  `onRequest(method, …)` serves `process.*`, `terminal.*` and `skill.install`.
+
+### Harness quick start
+
+```ts
+import { Harness } from "@beeos-ai/bma-executor-sdk";
+
+const harness = new Harness({ authenticate: (request) => verify(request) }); // omit only on loopback
+const { url } = await harness.listen(); // or harness.attach(httpServer)
+
+const executor = await harness.waitExecutor();
+const session = await executor.assignSession({ session_id: "sess_1" });
+await session.ready();
+const result = await session.callTool({ tool: "bash", input: { command: "ls" } });
+const mcp = await session.mcp("echo"); // raw MCP JSON-RPC
+await session.stop("done");
+```
+
+Semantics match the Go `Harness`: `callTool` is idempotent by `tool_call_id`;
+an unknown call's `tool.result` is `-32002`, a foreign session `-32007`;
+sessions and pending calls survive a reconnect within `leaseTtlMs`; a newer
+connection replaces the old one with 4004; lease expiry or `executor.close`
+fails pending calls with `ToolOutcomeUnknownError`.
+
+### Transports
+
+Messages are identical on every transport; who dials is independent of the
+protocol role (the executor always sends `executor.register` first).
+
+| Transport | Executor end | Harness end |
+| --- | --- | --- |
+| WebSocket (cloud, executor dials) | default, or `webSocketDialer(...)` | `listen()`, `attach(server)`, `handleUpgrade(...)` |
+| Local socket, executor dials | `webSocketDialer({ ..., tokenSource: staticToken('unix:///path.sock', token) })` | `new Harness({ authenticate: bearerAuthenticator(token) }).listenLocal(path)` |
+| Local socket, harness dials (bmad listens) | `listenExecutor({ path, token })` → `new ExecutorClient({ dialer: listener.dialer })` | `harness.dialExecutor(listener.url, { token })` |
+| In-process | `dialer: harness.inProcessDialer()` | — |
+
+Local sockets carry the same WebSocket protocol as the cloud (subprotocol
+negotiation, bearer token, close codes) over a Unix domain socket
+(`unix:///path.sock`, 0700 directory, 0600 socket) or a Windows named pipe
+(`npipe:////./pipe/<name>`), as the Go and Python SDKs do. Each start writes a
+fresh local token (`createLocalToken`, 0600); environment keys are never used
+locally (see [`src/executor/local.ts`](src/executor/local.ts)). When the harness
+dials the executor it also dials the session MCP channels (`session.mcp`).
+
+### Agent executors
+
+```ts
+client.serveAgent(
+  {
+    openTurn: async (p) => ({ accepted: true, turn_id: p.turn_id, executor_session_ref: "conv_1", resumed: false, effective: {} }),
+    runTurn: async (turn, signal) => {
+      const answer = await turn.requestInteraction({ kind: "permission", tool_use_id: "tu_1", tool_name: "bash" }, signal);
+      turn.emit({ type: "agent.message", content: [{ type: "text", text: answer.outcome }] });
+    },
+    closeSession: async () => {},
+  },
+  { models: [{ id: "my-model" }] },
+);
+```
+
+The SDK assigns event ids and sequences, delivers events in order with
+ACKs, resends after a reconnect, and frames each turn with
+`session.status_running` and `session.status_idle` (`completed`, `canceled`,
+`failed`). The harness side is `HarnessOptions.agent` (`AgentPlatform`) plus
+`executor.startTurn / sendTurnInput / cancelTurn / closeAgentSession /
+respondInteraction`; a sequence gap answers `-32013` with
+`data.expected_sequence`.
+
+### Examples
+
+[`examples`](examples) (`npm install` there first):
+`executor-minimal` (cloud executor with bash), `harness-loopback` (bmad-style
+local socket: executor listens, harness dials), `agent-minimal` (agent
+executor and in-memory platform in one process).
+
+### Go ↔ TypeScript
+
+| Go (`github.com/beeos-ai/bma-sdks/executor`) | TypeScript (`@beeos-ai/bma-executor-sdk`) |
+| --- | --- |
+| `NewClient(Options)` / `Start` / `Stop` | `new ExecutorClient(options)` / `start()` / `stop()` |
+| `Options.TokenSource`, `StaticToken` | `tokenSource`, `staticToken` (or `dialer`) |
+| `OnToolCall(ctx, call)` | `onToolCall(call, { signal, progress })`, `handleTool(name, …)` |
+| `OnSessionAssign` / `OnSessionStop` / `OnDrain` / `OnRequest` / `OnNotification` | `onSessionAssign` / `onSessionStop` / `onDrain` / `onRequest` / `onNotification` |
+| `SessionReady` / `SessionEnded` / `ReportToolResult` | `sessionReady` / `sessionEnded` / `reportToolResult` |
+| `SendSessionStatus` / `SendToolProgress` / `SendExecutorCapabilitiesUpdate` | `sessionStatus` / `toolProgress` / `updateCapabilities` |
+| `OpenMCPChannel` → `MCPChannel` | `openMcpChannel` → `FrameChannel` |
+| `ServeAgent(AgentHandler, AgentCapability)` | `serveAgent(handler, capability)` |
+| `AgentTurn.Emit/EmitWithID/Delta/Flush/Inputs/RequestInteraction/CancelInteraction` | `emit/emitWithId/delta/flush/inputs/requestInteraction/cancelInteraction` |
+| `NewHarness(HarnessOptions)` (`http.Handler`) | `new Harness(options)` + `listen/listenLocal/attach/handleUpgrade/accept/dialExecutor/inProcessDialer` |
+| `Harness.WaitExecutor` / `Executors` | `waitExecutor` / `executors` |
+| `Executor.AssignSession/Drain/StartTurn/SendTurnInput/CancelTurn/CloseAgentSession/RespondInteraction` | `HarnessExecutor.assignSession/drain/startTurn/sendTurnInput/cancelTurn/closeAgentSession/respondInteraction` |
+| `Session.Ready/CallTool/CancelTool/Stop/MCP/Done/EndReason` | `HarnessSession.ready/callTool/cancelTool/stop/mcp/done/endReason` |
+| `AgentPlatform` | `AgentPlatform` |
+| `*RPCError`, `ErrNotConnected`, `ErrClientStopped`, `ErrSessionEnded`, `ErrToolOutcomeUnknown`, `ErrAssignRejected` | `RpcError`, `NotConnectedError`, `ClientStoppedError`, `SessionEndedError`, `ToolOutcomeUnknownError`, `AssignRejectedError` |
+| `Core` (bash/files/stdio MCP) | not provided |
+| — (TCP WebSocket only) | `Harness.listenLocal` / `listenExecutor` + `Harness.dialExecutor` / `inProcessPair` |
+
+### Tests
+
+`npm test` runs, besides the REST tests: the conformance examples against
+both TS ends ([`test/conformance.test.ts`](test/conformance.test.ts)), executor ↔
+harness over every transport with reconnect and lease
+([`test/executor.test.ts`](test/executor.test.ts)), the agent capability
+([`test/agent.test.ts`](test/agent.test.ts)), and interop with the Go SDK
+([`test/interop.test.ts`](test/interop.test.ts): TS executor ↔ Go harness, TS
+agent ↔ Go platform, TS harness ↔ Go executor; needs Go), and interop with the
+Python SDK over WebSocket on a Unix socket
+([`test/interop-python.test.ts`](test/interop-python.test.ts): TS executor ↔
+Python harness, Python executor ↔ TS harness; `BMA_PYTHON_SDK=<python dir with
+.venv>`, skipped without it). Go has no Unix-socket dialer yet, so TS ↔ Go
+local-socket interop is pending.

package/dist/agent.d.ts

@@ -0,0 +1,126 @@
+import { type Ack, type AgentCapability, type AgentEvent, type ConnectionState, type EventDeltaType, type InteractionCancelReason, type InteractionRequestParams, type InteractionResponseParams, type SessionEndedParams, type TurnInputParams, type TurnStartParams, type TurnStartResult } from './generated/executor.js';
+import { type Deferred } from './errors.js';
+import type { LogLevel } from './rpc.js';
+export type { ConnectionState };
+/** A complete local agent (model loop and tools). */
+export interface AgentHandler {
+    /**
+     * Decides whether to accept a turn.start and reports the configuration the
+     * agent will apply. It runs before turn.start is answered, so it must not
+     * do the turn's work. A thrown RpcError keeps its code.
+     */
+    openTurn(params: TurnStartParams): Promise<TurnStartResult>;
+    /**
+     * Does the turn's work. signal is aborted by turn.cancel, session.close and
+     * deadline_ms. Resolving ends the turn as completed, an aborted signal as
+     * canceled (failed for deadline_ms), a rejection as failed (the SDK emits
+     * session.error first).
+     */
+    runTurn(turn: AgentTurn, signal: AbortSignal): Promise<void>;
+    /** Releases the local conversation after session.close. */
+    closeSession(sessionId: string, reason: string): Promise<void>;
+}
+/** What the agent runtime needs from the executor client. */
+export interface AgentHost {
+    call<T>(method: string, params: unknown): Promise<T>;
+    notify(method: string, params: unknown): void;
+    readonly stopSignal: AbortSignal;
+    connected(): boolean;
+    /** Resolves after the next successful executor.register. */
+    nextRegistration(): Promise<void>;
+    addSession(id: string): void;
+    removeSession(id: string): void;
+    sessionEnded(params: SessionEndedParams): Promise<Ack>;
+    log(level: LogLevel, message: string, error?: unknown): void;
+}
+/** The handle runTurn uses to talk to the platform. */
+export declare class AgentTurn {
+    private readonly session;
+    readonly params: TurnStartParams;
+    ended: boolean;
+    readonly abort: AbortController;
+    readonly done: Deferred<void>;
+    readonly seen: Set<string>;
+    private readonly queue;
+    constructor(session: AgentSession, params: TurnStartParams);
+    get sessionId(): string;
+    get turnId(): string;
+    /** turn.input messages in arrival order; the iteration ends with the turn. */
+    get inputs(): AsyncIterable<TurnInputParams> & {
+        next(): Promise<IteratorResult<TurnInputParams>>;
+    };
+    /** @internal */
+    pushInput(input: TurnInputParams): void;
+    /** @internal */
+    finish(): void;
+    /** A fresh event id, for a message streamed with delta before emitWithId. */
+    newEventId(): string;
+    /**
+     * Queues one durable event and returns its id. Delivery is asynchronous,
+     * ordered and at-least-once; the platform deduplicates by event id.
+     */
+    emit(event: AgentEvent): string;
+    emitWithId(eventId: string, event: AgentEvent): string;
+    /** Streams a transient preview of the durable event eventId; dropped while disconnected, never resent. */
+    delta(eventId: string, eventType: EventDeltaType, index: number, text: string): void;
+    /** Resolves once every event emitted so far is acknowledged. */
+    flush(signal?: AbortSignal): Promise<void>;
+    /**
+     * Asks the platform for an approval or an answer and waits for
+     * interaction.response. It flushes first so the platform already has the
+     * agent.tool_use the request references. When signal aborts or expires_at
+     * passes, it withdraws the interaction with interaction.cancel; an expiry
+     * resolves with outcome expired, which the agent must treat as a deny.
+     */
+    requestInteraction(request: Omit<InteractionRequestParams, 'session_id' | 'turn_id' | 'interaction_id'> & {
+        interaction_id?: string;
+    }, signal?: AbortSignal): Promise<InteractionResponseParams>;
+    /** Withdraws an open interaction, for example one the user answered locally (resolved_locally). */
+    cancelInteraction(interactionId: string, reason: InteractionCancelReason): Promise<void>;
+}
+/** One platform session on this executor: its outbox of durable events and at most one running turn. */
+declare class AgentSession {
+    readonly host: AgentHost;
+    readonly id: string;
+    private nextSequence;
+    private nextId;
+    private readonly outbox;
+    private wake;
+    private drained;
+    closed: boolean;
+    turn?: AgentTurn;
+    readonly results: Map<string, TurnStartResult>;
+    readonly pending: Map<string, Deferred<InteractionResponseParams>>;
+    readonly answered: Set<string>;
+    constructor(host: AgentHost, id: string);
+    newEventId(): string;
+    enqueue(turnId: string, eventId: string, event: AgentEvent): void;
+    signal(): void;
+    flush(signal?: AbortSignal): Promise<void>;
+    /**
+     * Delivers the outbox head first, one event at a time, so the platform sees
+     * every session in sequence order. A transport failure keeps the event and
+     * waits for the next registration: the resend after reconnect.
+     */
+    private sendLoop;
+    /** Retries call across disconnects; only transport failures, executor_busy and retryable errors are retried. */
+    callUntilConnected<T>(call: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    withdraw(interactionId: string, reason: InteractionCancelReason): Promise<void>;
+}
+/** @internal Routes agent methods for one ExecutorClient. */
+export declare class AgentRuntime {
+    private readonly host;
+    private readonly handler;
+    readonly capability: AgentCapability;
+    private readonly sessions;
+    constructor(host: AgentHost, handler: AgentHandler, capability: AgentCapability);
+    /** Handles an agent method; undefined for every other method. */
+    dispatch(method: string, params: unknown): Promise<unknown> | undefined;
+    private session;
+    private turnStart;
+    private runTurn;
+    private turnInput;
+    private turnCancel;
+    private sessionClose;
+    private interactionResponse;
+}