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

package/dist/harness.d.ts

@@ -0,0 +1,261 @@
+import { type IncomingMessage, type Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { ChannelScope, type Ack, type AgentCapability, type Capabilities, type ExecutorDrainResult, type ExecutorInfo, type InteractionCancelParams, type InteractionRequestParams, type InteractionResponseParams, type InteractionResponseResult, type SessionAssignParams, type SessionCloseParams, type SessionCloseResult, type SessionEventDeltaParams, type SessionEventParams, type SessionEventResult, type SessionStatusParams, type ToolCallParams, type ToolProgressParams, type ToolResultParams, type TurnCancelParams, type TurnCancelResult, type TurnInputParams, type TurnStartParams, type TurnStartResult } from './generated/executor.js';
+import { type Dialer } from './client.js';
+import { RpcPeer, type LogLevel, type Logger } from './rpc.js';
+import { FrameChannel, type Conn } from './transport.js';
+export declare const DEFAULT_HARNESS_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const DEFAULT_HARNESS_LEASE_TTL_MS = 60000;
+/** What authenticate learns from a connection. A non-empty executorId pins the executor identity. */
+export interface Principal {
+    executorId?: string;
+}
+/** One durable agent event, validated. */
+export interface AgentEventRecord {
+    sessionId: string;
+    turnId: string;
+    eventId: string;
+    sequence: number;
+    type: string;
+    /** The event object as sent, for example an agent.message event. */
+    event: Record<string, unknown>;
+}
+/** The platform half of the agent capability. */
+export interface AgentPlatform {
+    /** Highest contiguous sequence already persisted for the session (0 when none). Asked once per session. */
+    ackedSequence(sessionId: string): Promise<number>;
+    /** Persists one durable event; resolves once durable. Called once per event, in sequence order per session. */
+    agentEvent(executor: HarnessExecutor, event: AgentEventRecord): Promise<void>;
+    /** Relays a transient preview. Never persisted. */
+    agentDelta(executor: HarnessExecutor, delta: SessionEventDeltaParams): void;
+    /** Opens (or for a repeated interaction_id returns) the platform interaction; returns its id. */
+    interactionRequested(executor: HarnessExecutor, request: InteractionRequestParams): Promise<string>;
+    /** Closes the platform interaction without an answer. */
+    interactionCanceled(executor: HarnessExecutor, cancel: InteractionCancelParams): Promise<void>;
+}
+export interface HarnessOptions {
+    /**
+     * Verifies every WebSocket upgrade (control and MCP). Throwing answers 401.
+     * Omitted accepts every connection: use that only on loopback.
+     */
+    authenticate?: (request: IncomingMessage) => Principal | Promise<Principal>;
+    /** Returned by executor.register. A disconnected executor keeps its sessions and calls for leaseTtlMs. */
+    heartbeatIntervalMs?: number;
+    leaseTtlMs?: number;
+    requestTimeoutMs?: number;
+    /** Accepted subprotocols in preference order; defaults to v1.1 then v1. */
+    protocols?: string[];
+    onExecutor?: (executor: HarnessExecutor) => void;
+    /** Persists a tool executor's session.event; omitted accepts with a generated id. */
+    onSessionEvent?: (executor: HarnessExecutor, params: SessionEventParams) => Promise<SessionEventResult>;
+    onSessionStatus?: (executor: HarnessExecutor, params: SessionStatusParams) => void;
+    onToolProgress?: (executor: HarnessExecutor, params: ToolProgressParams) => void;
+    onLog?: Logger;
+    /** Receives agent-capability traffic; omitted rejects it as unknown methods. */
+    agent?: AgentPlatform;
+}
+/** Where a connection came from: its principal and, for MCP, its session and server key. */
+export interface AcceptOptions {
+    principal?: Principal;
+    channel?: ChannelScope;
+    sessionId?: string;
+    serverKey?: string;
+    /** @internal Set when the harness dialed the executor: where to dial its MCP channels. */
+    dialBack?: DialBack;
+}
+/** @internal */
+export interface DialBack {
+    url: string;
+    token?: string;
+}
+export declare class Harness {
+    readonly options: Required<Pick<HarnessOptions, 'heartbeatIntervalMs' | 'leaseTtlMs' | 'requestTimeoutMs' | 'protocols'>> & HarnessOptions;
+    private readonly executorsById;
+    /** @internal */
+    readonly sessionsById: Map<string, HarnessSession>;
+    private changed;
+    private nextConn;
+    private readonly wss;
+    /** @internal */
+    readonly ledger: AgentLedger;
+    constructor(options?: HarnessOptions);
+    /** Executors currently registered (connected or within their lease). */
+    executors(): HarnessExecutor[];
+    /** Resolves with a connected executor, waiting for one to register. */
+    waitExecutor(signal?: AbortSignal): Promise<HarnessExecutor>;
+    /** @internal */
+    signal(): void;
+    /**
+     * Handles an HTTP upgrade for /v1/executors/channel style URLs: the control
+     * channel by default, an MCP channel with ?channel=mcp&session_id=&server_key=.
+     */
+    handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
+    /** Serves executor channels on an HTTP server's upgrade event. */
+    attach(server: Server): void;
+    /** Listens on host:port (defaults 127.0.0.1, an ephemeral port) and returns the ws:// URL. */
+    listen(port?: number, host?: string): Promise<{
+        url: string;
+        close(): Promise<void>;
+    }>;
+    /**
+     * Listens on a Unix domain socket or Windows named pipe (\\.\pipe\<name>)
+     * and returns its unix:// or npipe:// URL. Same handler, subprotocols,
+     * authenticate and close codes as listen; set authenticate (for example
+     * bearerAuthenticator with the local token).
+     */
+    listenLocal(path: string): Promise<{
+        url: string;
+        close(): Promise<void>;
+    }>;
+    /**
+     * Dials an executor that listens (listenExecutor) at a unix://, npipe:// or
+     * ws:// URL: the local "who dials" inversion. The harness also dials the
+     * MCP channels of that executor's sessions (HarnessSession.mcp).
+     */
+    dialExecutor(url: string, options?: {
+        token?: string;
+    }): Promise<void>;
+    /** @internal Opens the MCP channel of a session whose executor this harness dialed. */
+    dialMcp(executor: HarnessExecutor, sessionId: string, serverKey: string): Promise<void>;
+    /** A Dialer for an ExecutorClient in the same process. */
+    inProcessDialer(principal?: Principal): Dialer;
+    /** Takes over an established connection (any transport). */
+    accept(conn: Conn, options?: AcceptOptions): void;
+    /** Only the executor holding the session may serve its MCP servers. */
+    private mcpAllowed;
+    /** @internal */
+    executorFor(id: string): HarnessExecutor;
+    /** @internal */
+    forgetExecutor(executor: HarnessExecutor): void;
+    /** @internal */
+    log(level: LogLevel, message: string, error?: unknown): void;
+}
+/** One registered executor; it outlives a connection within its lease. */
+export declare class HarnessExecutor {
+    private readonly harness;
+    readonly id: string;
+    /** @internal */ conn?: HarnessConn;
+    info: ExecutorInfo;
+    /** The negotiated protocol of the current connection. */
+    protocol: string;
+    environmentId: string;
+    capabilities: Capabilities;
+    /** @internal */ readonly sessionsById: Map<string, HarnessSession>;
+    /** @internal */ leaseTimer?: ReturnType<typeof setTimeout>;
+    /** @internal */ draining: boolean;
+    /** @internal */ gone: boolean;
+    /** @internal */ readonly eventIds: Map<string, SessionEventResult>;
+    /** @internal */ dialBack?: DialBack;
+    constructor(harness: Harness, id: string);
+    get connected(): boolean;
+    sessions(): HarnessSession[];
+    /** @internal */
+    call<T>(method: string, params: unknown): Promise<T>;
+    /** Asks the executor to stop accepting sessions; heartbeats report drain=true from now on. */
+    drain(reason: string): Promise<ExecutorDrainResult>;
+    /**
+     * Binds a session and sends session.assign. work_id and the lease token are
+     * generated when empty. The session is bound before the request is sent, so
+     * session.ready and MCP channels racing the answer are accepted.
+     */
+    assignSession(params: Omit<SessionAssignParams, 'work_id' | 'environment_id' | 'lease'> & Partial<SessionAssignParams>): Promise<HarnessSession>;
+    /** @internal Ends every session; pending tool calls fail with ToolOutcomeUnknownError. */
+    forget(reason: string): void;
+    /** The advertised agent capability, undefined when absent. */
+    get agentCapability(): AgentCapability | undefined;
+    private requireAgent;
+    /** turn.start; safe to repeat with the same turn_id after a timeout or reconnect. */
+    startTurn(params: TurnStartParams): Promise<TurnStartResult>;
+    /** turn.input; a conflict means the turn is over and the input belongs in a new turn.start. */
+    sendTurnInput(params: TurnInputParams): Promise<Ack>;
+    /** turn.cancel; the turn's end is still reported by its session.status_idle event. */
+    cancelTurn(params: TurnCancelParams): Promise<TurnCancelResult>;
+    closeAgentSession(params: SessionCloseParams): Promise<SessionCloseResult>;
+    /** Delivers the platform's answer; accepted=false means the executor no longer waits for it. */
+    respondInteraction(params: InteractionResponseParams): Promise<InteractionResponseResult>;
+}
+/** One session bound to an executor. */
+export declare class HarnessSession {
+    private readonly harness;
+    readonly executor: HarnessExecutor;
+    readonly id: string;
+    readonly workId: string;
+    /** @internal */ readonly leaseToken: string;
+    private readonly readyDeferred;
+    private readonly doneDeferred;
+    private isReady;
+    /** Set once the session ended. */
+    endReason: string;
+    private readonly calls;
+    private readonly mcpChannels;
+    private mcpChanged;
+    constructor(harness: Harness, executor: HarnessExecutor, id: string, workId: string, 
+    /** @internal */ leaseToken: string);
+    /** Resolves when the session ended. */
+    get done(): Promise<void>;
+    /** Waits for session.ready. */
+    ready(signal?: AbortSignal): Promise<void>;
+    /** @internal */
+    markReady(): void;
+    /**
+     * Sends tool.call and waits for its tool.result. Idempotent by tool_call_id
+     * (generated when empty): a repeat joins the in-flight call or returns the
+     * recorded result without re-dispatching. Aborting signal stops waiting
+     * only; use cancelTool to abort the tool.
+     */
+    callTool(params: Omit<ToolCallParams, 'session_id' | 'tool_call_id'> & {
+        tool_call_id?: string;
+    }, signal?: AbortSignal): Promise<ToolResultParams>;
+    /** Sends tool.cancel; the waiting callTool still receives the executor's tool.result. */
+    cancelTool(toolCallId: string, reason: string): Promise<boolean>;
+    /** Sends session.stop; the session ends locally on success. */
+    stop(reason: string): Promise<void>;
+    /**
+     * Waits for the executor to open the MCP channel for serverKey (one of the
+     * session.assign mcp_servers). A newer channel replaces the old one.
+     */
+    mcp(serverKey: string, signal?: AbortSignal): Promise<HarnessMcpChannel>;
+    /** @internal */
+    attachMcp(serverKey: string, channel: HarnessMcpChannel): void;
+    private notifyMcp;
+    /** @internal Records a tool.result; false when this harness never dispatched the call. */
+    complete(result: ToolResultParams): boolean;
+    /** @internal Unbinds the session, fails waiting calls and closes MCP channels. Idempotent. */
+    end(reason: string, pendingError: () => Error): void;
+    private race;
+}
+/**
+ * The harness end of one MCP channel, isolated by (session_id, server_key).
+ * Frames are raw MCP JSON-RPC: the harness is the MCP client. After a
+ * transport error, call session.mcp again and re-initialize.
+ */
+export declare class HarnessMcpChannel extends FrameChannel {
+}
+/** Serializes agent events per session and remembers the acknowledged sequence. */
+declare class AgentLedger {
+    readonly acked: Map<string, number>;
+    private readonly tails;
+    /** Runs fn after every earlier fn of the same session. */
+    serialize<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
+}
+/** The harness side of one connection. */
+declare class HarnessConn {
+    private readonly harness;
+    readonly conn: Conn;
+    private readonly principal;
+    private readonly id;
+    private readonly dialBack?;
+    readonly peer: RpcPeer;
+    private executor?;
+    constructor(harness: Harness, conn: Conn, principal: Principal, id: string, dialBack?: DialBack | undefined);
+    private onRequest;
+    private register;
+    private disconnected;
+    private dispatch;
+    private sessionEvent;
+    /** Agent methods; undefined for everything else, including session.event without event_id. */
+    private dispatchAgent;
+    private agentEvent;
+    private onNotification;
+}
+export {};