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

package/dist/harness.js

@@ -0,0 +1,809 @@
+// Harness ("brain") end of the BMA executor protocol: accepts executor
+// control and MCP channels on any transport and drives them with
+// session.assign / tool.call / tool.cancel / session.stop, plus the agent
+// capability. It speaks the same protocol as the BMA service, so an executor
+// cannot tell a local harness from the cloud. Mirrors go/executor Harness.
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { ChannelScope, JsonRpcErrorCode, ProtocolVersion, } from './generated/executor.js';
+import { channelUrl } from './client.js';
+import { AssignRejectedError, deferred, NotConnectedError, rpcError, RpcError, SessionEndedError, ToolOutcomeUnknownError, } from './errors.js';
+import { DEFAULT_PROTOCOLS, listenHttpLocal, localUrl, refuseUpgrade } from './local.js';
+import { RpcPeer } from './rpc.js';
+import { dialWebSocket, FrameChannel, inProcessPair, MAX_FRAME_BYTES, webSocketConn } from './transport.js';
+export const DEFAULT_HARNESS_HEARTBEAT_INTERVAL_MS = 15_000;
+export const DEFAULT_HARNESS_LEASE_TTL_MS = 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_REMEMBERED_EVENT_IDS = 1024;
+function randomId(bytes) {
+    return randomBytes(bytes).toString('hex');
+}
+export class Harness {
+    options;
+    executorsById = new Map();
+    /** @internal */
+    sessionsById = new Map();
+    changed = deferred();
+    nextConn = 0;
+    wss;
+    /** @internal */
+    ledger = new AgentLedger();
+    constructor(options = {}) {
+        this.options = {
+            ...options,
+            heartbeatIntervalMs: options.heartbeatIntervalMs ?? DEFAULT_HARNESS_HEARTBEAT_INTERVAL_MS,
+            leaseTtlMs: options.leaseTtlMs ?? DEFAULT_HARNESS_LEASE_TTL_MS,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            protocols: options.protocols ?? DEFAULT_PROTOCOLS,
+        };
+        this.wss = new WebSocketServer({
+            noServer: true,
+            maxPayload: MAX_FRAME_BYTES,
+            handleProtocols: (offered) => this.options.protocols.find((protocol) => offered.has(protocol)) ?? false,
+        });
+    }
+    /** Executors currently registered (connected or within their lease). */
+    executors() {
+        return [...this.executorsById.values()];
+    }
+    /** Resolves with a connected executor, waiting for one to register. */
+    async waitExecutor(signal) {
+        for (;;) {
+            const executor = this.executors().find((candidate) => candidate.connected);
+            if (executor)
+                return executor;
+            const changed = this.changed.promise;
+            await (signal
+                ? Promise.race([
+                    changed,
+                    new Promise((_resolve, reject) => {
+                        if (signal.aborted)
+                            reject(signal.reason);
+                        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+                    }),
+                ])
+                : changed);
+        }
+    }
+    /** @internal */
+    signal() {
+        const changed = this.changed;
+        this.changed = deferred();
+        changed.resolve();
+    }
+    /**
+     * 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=.
+     */
+    async handleUpgrade(request, socket, head) {
+        const refuse = (status, message) => refuseUpgrade(socket, status, message);
+        let principal = {};
+        if (this.options.authenticate) {
+            try {
+                principal = await this.options.authenticate(request);
+            }
+            catch {
+                refuse(401, 'Unauthorized');
+                return;
+            }
+        }
+        const query = new URL(request.url ?? '/', 'http://localhost').searchParams;
+        const channel = query.get('channel') || ChannelScope.Control;
+        if (channel !== ChannelScope.Control && channel !== ChannelScope.Mcp) {
+            refuse(400, 'Bad Request');
+            return;
+        }
+        const offered = (request.headers['sec-websocket-protocol'] ?? '').split(',').map((value) => value.trim());
+        if (!this.options.protocols.some((protocol) => offered.includes(protocol))) {
+            refuse(400, 'Bad Request');
+            return;
+        }
+        const target = {
+            principal,
+            channel,
+            sessionId: query.get('session_id') ?? undefined,
+            serverKey: query.get('server_key') ?? undefined,
+        };
+        if (channel === ChannelScope.Mcp && !this.mcpAllowed(target)) {
+            refuse(403, 'Forbidden');
+            return;
+        }
+        this.wss.handleUpgrade(request, socket, head, (ws) => this.accept(webSocketConn(ws), target));
+    }
+    /** Serves executor channels on an HTTP server's upgrade event. */
+    attach(server) {
+        server.on('upgrade', (request, socket, head) => void this.handleUpgrade(request, socket, head));
+    }
+    /** Listens on host:port (defaults 127.0.0.1, an ephemeral port) and returns the ws:// URL. */
+    async listen(port = 0, host = '127.0.0.1') {
+        const server = createServer((_request, response) => response.writeHead(426).end());
+        this.attach(server);
+        await new Promise((resolve) => server.listen(port, host, resolve));
+        const address = server.address();
+        if (!address || typeof address === 'string')
+            throw new Error('unexpected listen address');
+        return {
+            url: `ws://${host}:${address.port}/v1/executors/channel`,
+            close: () => new Promise((resolve) => {
+                for (const client of this.wss.clients)
+                    client.terminate();
+                server.closeAllConnections();
+                server.close(() => resolve());
+            }),
+        };
+    }
+    /**
+     * 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).
+     */
+    async listenLocal(path) {
+        const server = createServer((_request, response) => response.writeHead(426).end());
+        this.attach(server);
+        const closeServer = await listenHttpLocal(server, path);
+        return {
+            url: localUrl(path),
+            close: () => {
+                for (const client of this.wss.clients)
+                    client.terminate();
+                return closeServer();
+            },
+        };
+    }
+    /**
+     * 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).
+     */
+    async dialExecutor(url, options = {}) {
+        const conn = await dialWebSocket(channelUrl(url, { channel: ChannelScope.Control }), {
+            protocols: this.options.protocols,
+            token: options.token,
+        });
+        this.accept(conn, { dialBack: { url, token: options.token } });
+    }
+    /** @internal Opens the MCP channel of a session whose executor this harness dialed. */
+    async dialMcp(executor, sessionId, serverKey) {
+        const dialBack = executor.dialBack;
+        const target = { channel: ChannelScope.Mcp, sessionId, serverKey };
+        const conn = await dialWebSocket(channelUrl(dialBack.url, target), { protocols: this.options.protocols, token: dialBack.token });
+        this.accept(conn, { principal: { executorId: executor.id }, ...target });
+    }
+    /** A Dialer for an ExecutorClient in the same process. */
+    inProcessDialer(principal = {}) {
+        return async (target) => {
+            const options = { principal, channel: target.channel, sessionId: target.sessionId, serverKey: target.serverKey };
+            if (target.channel === ChannelScope.Mcp && !this.mcpAllowed(options))
+                throw new Error('session is not active for this executor');
+            const [executorEnd, harnessEnd] = inProcessPair(this.options.protocols[0] ?? ProtocolVersion.BmaExecutorV11);
+            this.accept(harnessEnd, options);
+            return executorEnd;
+        };
+    }
+    /** Takes over an established connection (any transport). */
+    accept(conn, options = {}) {
+        if (options.channel === ChannelScope.Mcp) {
+            const session = options.sessionId ? this.sessionsById.get(options.sessionId) : undefined;
+            if (!session || !options.serverKey || !this.mcpAllowed(options)) {
+                conn.close(1008, 'session is not active for this executor');
+                return;
+            }
+            session.attachMcp(options.serverKey, new HarnessMcpChannel(conn));
+            return;
+        }
+        new HarnessConn(this, conn, options.principal ?? {}, `conn_${++this.nextConn}_${randomId(4)}`, options.dialBack);
+    }
+    /** Only the executor holding the session may serve its MCP servers. */
+    mcpAllowed(options) {
+        const session = options.sessionId ? this.sessionsById.get(options.sessionId) : undefined;
+        if (!session || !options.serverKey)
+            return false;
+        const pinned = options.principal?.executorId;
+        return !pinned || pinned === session.executor.id;
+    }
+    /** @internal */
+    executorFor(id) {
+        let executor = this.executorsById.get(id);
+        if (!executor) {
+            executor = new HarnessExecutor(this, id);
+            this.executorsById.set(id, executor);
+        }
+        return executor;
+    }
+    /** @internal */
+    forgetExecutor(executor) {
+        if (this.executorsById.get(executor.id) === executor)
+            this.executorsById.delete(executor.id);
+        this.signal();
+    }
+    /** @internal */
+    log(level, message, error) {
+        this.options.onLog?.({ level, message, error });
+    }
+}
+/** One registered executor; it outlives a connection within its lease. */
+export class HarnessExecutor {
+    harness;
+    id;
+    /** @internal */ conn;
+    info = { name: '', os: '', arch: '', version: '' };
+    /** The negotiated protocol of the current connection. */
+    protocol = '';
+    environmentId = '';
+    capabilities = {};
+    /** @internal */ sessionsById = new Map();
+    /** @internal */ leaseTimer;
+    /** @internal */ draining = false;
+    /** @internal */ gone = false;
+    /** @internal */ eventIds = new Map();
+    /** @internal */ dialBack;
+    constructor(harness, id) {
+        this.harness = harness;
+        this.id = id;
+    }
+    get connected() {
+        return this.conn !== undefined;
+    }
+    sessions() {
+        return [...this.sessionsById.values()];
+    }
+    /** @internal */
+    call(method, params) {
+        if (!this.conn)
+            return Promise.reject(new NotConnectedError());
+        return this.conn.peer.call(method, params);
+    }
+    /** Asks the executor to stop accepting sessions; heartbeats report drain=true from now on. */
+    drain(reason) {
+        this.draining = true;
+        return this.call('executor.drain', { reason });
+    }
+    /**
+     * 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.
+     */
+    async assignSession(params) {
+        if (!params.session_id?.trim())
+            throw new Error('session_id is required');
+        const full = {
+            ...params,
+            work_id: params.work_id || `work_${randomId(8)}`,
+            environment_id: params.environment_id || this.environmentId,
+            lease: { token: params.lease?.token || `lease_${randomId(16)}`, fencing_token: params.lease?.fencing_token ?? 0 },
+        };
+        if (this.harness.sessionsById.has(full.session_id))
+            throw new Error(`session ${full.session_id} is already bound`);
+        if (this.gone)
+            throw new NotConnectedError();
+        const session = new HarnessSession(this.harness, this, full.session_id, full.work_id, full.lease.token);
+        this.harness.sessionsById.set(session.id, session);
+        this.sessionsById.set(session.id, session);
+        try {
+            const result = await this.call('session.assign', full);
+            if (!result.accepted)
+                throw new AssignRejectedError();
+        }
+        catch (error) {
+            session.end('assign_failed', () => new SessionEndedError());
+            throw error;
+        }
+        return session;
+    }
+    /** @internal Ends every session; pending tool calls fail with ToolOutcomeUnknownError. */
+    forget(reason) {
+        this.gone = true;
+        for (const session of this.sessions())
+            session.end(reason, () => new ToolOutcomeUnknownError());
+        this.harness.forgetExecutor(this);
+    }
+    // --- agent capability ---
+    /** The advertised agent capability, undefined when absent. */
+    get agentCapability() {
+        return this.capabilities.agent;
+    }
+    requireAgent() {
+        if (!this.agentCapability?.enabled) {
+            throw new RpcError(JsonRpcErrorCode.CapabilityUnavailable, 'executor does not advertise the agent capability');
+        }
+    }
+    /** turn.start; safe to repeat with the same turn_id after a timeout or reconnect. */
+    async startTurn(params) {
+        this.requireAgent();
+        return this.call('turn.start', params);
+    }
+    /** turn.input; a conflict means the turn is over and the input belongs in a new turn.start. */
+    sendTurnInput(params) {
+        return this.call('turn.input', params);
+    }
+    /** turn.cancel; the turn's end is still reported by its session.status_idle event. */
+    cancelTurn(params) {
+        return this.call('turn.cancel', params);
+    }
+    closeAgentSession(params) {
+        return this.call('session.close', params);
+    }
+    /** Delivers the platform's answer; accepted=false means the executor no longer waits for it. */
+    respondInteraction(params) {
+        return this.call('interaction.response', params);
+    }
+}
+/** One session bound to an executor. */
+export class HarnessSession {
+    harness;
+    executor;
+    id;
+    workId;
+    leaseToken;
+    readyDeferred = deferred();
+    doneDeferred = deferred();
+    isReady = false;
+    /** Set once the session ended. */
+    endReason = '';
+    calls = new Map();
+    mcpChannels = new Map();
+    mcpChanged = deferred();
+    constructor(harness, executor, id, workId, 
+    /** @internal */ leaseToken) {
+        this.harness = harness;
+        this.executor = executor;
+        this.id = id;
+        this.workId = workId;
+        this.leaseToken = leaseToken;
+    }
+    /** Resolves when the session ended. */
+    get done() {
+        return this.doneDeferred.promise;
+    }
+    /** Waits for session.ready. */
+    async ready(signal) {
+        if (this.isReady)
+            return;
+        if (this.endReason)
+            throw new SessionEndedError();
+        await this.race(Promise.race([this.readyDeferred.promise, this.done.then(() => Promise.reject(new SessionEndedError()))]), signal);
+    }
+    /** @internal */
+    markReady() {
+        this.isReady = true;
+        this.readyDeferred.resolve();
+    }
+    /**
+     * 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.
+     */
+    async callTool(params, signal) {
+        const call = { ...params, session_id: this.id, tool_call_id: params.tool_call_id || `call_${randomId(8)}` };
+        let record = this.calls.get(call.tool_call_id);
+        if (!record) {
+            if (this.endReason)
+                throw new SessionEndedError();
+            const created = { done: deferred(), settled: false };
+            record = created;
+            this.calls.set(call.tool_call_id, created);
+            try {
+                const ack = await this.executor.call('tool.call', call);
+                if (!ack.accepted)
+                    throw new Error('executor did not accept tool.call');
+            }
+            catch (error) {
+                // Not dispatched: forget the call so the same id can be retried.
+                if (this.calls.get(call.tool_call_id) === created)
+                    this.calls.delete(call.tool_call_id);
+                throw error;
+            }
+        }
+        const settled = record;
+        await this.race(settled.done.promise, signal);
+        if (settled.error !== undefined)
+            throw settled.error;
+        return settled.result;
+    }
+    /** Sends tool.cancel; the waiting callTool still receives the executor's tool.result. */
+    async cancelTool(toolCallId, reason) {
+        const result = await this.executor.call('tool.cancel', {
+            session_id: this.id,
+            tool_call_id: toolCallId,
+            reason,
+        });
+        return result.canceled;
+    }
+    /** Sends session.stop; the session ends locally on success. */
+    async stop(reason) {
+        await this.executor.call('session.stop', { session_id: this.id, reason });
+        this.end(reason, () => new ToolOutcomeUnknownError());
+    }
+    /**
+     * 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.
+     */
+    async mcp(serverKey, signal) {
+        for (;;) {
+            if (this.endReason)
+                throw new SessionEndedError();
+            const channel = this.mcpChannels.get(serverKey);
+            if (channel)
+                return channel;
+            const changed = this.mcpChanged.promise;
+            // The executor cannot dial a harness that dialed it; open the channel from here.
+            if (this.executor.dialBack)
+                await this.race(this.harness.dialMcp(this.executor, this.id, serverKey), signal);
+            await this.race(changed, signal);
+        }
+    }
+    /** @internal */
+    attachMcp(serverKey, channel) {
+        if (this.endReason) {
+            channel.close();
+            return;
+        }
+        const previous = this.mcpChannels.get(serverKey);
+        this.mcpChannels.set(serverKey, channel);
+        void channel.done.then(() => {
+            if (this.mcpChannels.get(serverKey) === channel)
+                this.mcpChannels.delete(serverKey);
+        });
+        this.notifyMcp();
+        previous?.close();
+    }
+    notifyMcp() {
+        const changed = this.mcpChanged;
+        this.mcpChanged = deferred();
+        changed.resolve();
+    }
+    /** @internal Records a tool.result; false when this harness never dispatched the call. */
+    complete(result) {
+        const record = this.calls.get(result.tool_call_id);
+        if (!record)
+            return false;
+        if (!record.settled) {
+            record.settled = true;
+            record.result = result;
+            record.done.resolve();
+        }
+        return true;
+    }
+    /** @internal Unbinds the session, fails waiting calls and closes MCP channels. Idempotent. */
+    end(reason, pendingError) {
+        if (this.endReason)
+            return;
+        this.endReason = reason || 'ended';
+        for (const record of this.calls.values()) {
+            if (record.settled)
+                continue;
+            record.settled = true;
+            record.error = pendingError();
+            record.done.resolve();
+        }
+        const channels = [...this.mcpChannels.values()];
+        this.mcpChannels.clear();
+        this.doneDeferred.resolve();
+        this.notifyMcp();
+        for (const channel of channels)
+            channel.close();
+        if (this.harness.sessionsById.get(this.id) === this)
+            this.harness.sessionsById.delete(this.id);
+        if (this.executor.sessionsById.get(this.id) === this)
+            this.executor.sessionsById.delete(this.id);
+    }
+    race(promise, signal) {
+        if (!signal)
+            return promise;
+        return Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                if (signal.aborted)
+                    reject(signal.reason);
+                signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+            }),
+        ]);
+    }
+}
+/**
+ * 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 class HarnessMcpChannel extends FrameChannel {
+}
+/** Serializes agent events per session and remembers the acknowledged sequence. */
+class AgentLedger {
+    acked = new Map();
+    tails = new Map();
+    /** Runs fn after every earlier fn of the same session. */
+    serialize(sessionId, fn) {
+        const previous = this.tails.get(sessionId) ?? Promise.resolve();
+        const next = previous.then(fn, fn);
+        this.tails.set(sessionId, next.catch(() => { }));
+        return next;
+    }
+}
+const AGENT_EVENT_TYPES = new Set([
+    'agent.message',
+    'agent.thinking',
+    'agent.tool_use',
+    'agent.tool_result',
+    'agent.mcp_tool_use',
+    'agent.mcp_tool_result',
+    'session.status_running',
+    'session.status_idle',
+    'session.error',
+]);
+/** The harness side of one connection. */
+class HarnessConn {
+    harness;
+    conn;
+    principal;
+    id;
+    dialBack;
+    peer;
+    executor;
+    constructor(harness, conn, principal, id, dialBack) {
+        this.harness = harness;
+        this.conn = conn;
+        this.principal = principal;
+        this.id = id;
+        this.dialBack = dialBack;
+        this.peer = new RpcPeer(conn, {
+            idPrefix: 'h_',
+            requestTimeoutMs: harness.options.requestTimeoutMs,
+            onRequest: (method, params, requestId) => this.onRequest(method, params, requestId),
+            onNotification: (method, params) => this.onNotification(method, params),
+            onClose: () => this.disconnected(),
+            log: harness.options.onLog,
+        });
+    }
+    onRequest(method, params, requestId) {
+        // Synchronous: nothing else is meaningful before register.
+        if (method === 'executor.register')
+            return this.register(params);
+        const executor = this.executor;
+        if (!executor)
+            throw rpcError(JsonRpcErrorCode.InvalidRequest, 'executor.register must come first', false);
+        return this.dispatch(executor, method, params, requestId);
+    }
+    register(params) {
+        if (this.executor)
+            throw rpcError(JsonRpcErrorCode.InvalidRequest, 'already registered', false);
+        if (!params || typeof params !== 'object' || typeof params.protocol !== 'string') {
+            throw rpcError(JsonRpcErrorCode.InvalidParams, 'invalid executor.register params', false);
+        }
+        if (params.protocol !== this.conn.protocol) {
+            setImmediate(() => this.conn.close(4003, 'unsupported protocol'));
+            throw rpcError(JsonRpcErrorCode.UnsupportedProtocol, 'protocol must match the negotiated subprotocol', false);
+        }
+        const resumeId = params.resume?.executor_id ?? '';
+        let executorId = this.principal.executorId ?? '';
+        if (executorId && resumeId && resumeId !== executorId) {
+            throw rpcError(JsonRpcErrorCode.Forbidden, 'resume.executor_id does not match the authenticated executor', false);
+        }
+        if (!executorId)
+            executorId = resumeId || `exe_${randomId(8)}`;
+        const harness = this.harness;
+        const executor = harness.executorFor(executorId);
+        const previous = executor.conn;
+        executor.conn = this;
+        executor.info = params.executor;
+        executor.capabilities = params.capabilities ?? {};
+        executor.environmentId = params.environment_id;
+        executor.protocol = params.protocol;
+        executor.dialBack = this.dialBack;
+        clearTimeout(executor.leaseTimer);
+        executor.leaseTimer = undefined;
+        this.executor = executor;
+        // The new connection is authoritative (4004 replaced).
+        previous?.conn.close(4004, 'replaced by a newer connection');
+        // Sessions the executor no longer reports were lost with its old process.
+        const keep = new Set(params.resume?.active_sessions ?? []);
+        for (const session of executor.sessions()) {
+            if (!keep.has(session.id))
+                session.end('executor_lost', () => new ToolOutcomeUnknownError());
+        }
+        setImmediate(() => {
+            harness.signal();
+            harness.options.onExecutor?.(executor);
+        });
+        return {
+            executor_id: executorId,
+            connection_id: this.id,
+            server_time: new Date().toISOString(),
+            heartbeat_interval_ms: harness.options.heartbeatIntervalMs,
+            lease_ttl_ms: harness.options.leaseTtlMs,
+            max_control_frame_bytes: MAX_FRAME_BYTES,
+            max_mcp_frame_bytes: MAX_FRAME_BYTES,
+            drain: executor.draining,
+            protocol: params.protocol,
+        };
+    }
+    disconnected() {
+        const executor = this.executor;
+        if (!executor || executor.conn !== this || executor.gone)
+            return;
+        executor.conn = undefined;
+        executor.leaseTimer = setTimeout(() => {
+            if (!executor.conn && !executor.gone)
+                executor.forget('lease_expired');
+        }, this.harness.options.leaseTtlMs);
+        // A lease alone does not keep the process alive; the listener does.
+        executor.leaseTimer.unref?.();
+        this.harness.signal();
+    }
+    dispatch(executor, method, params, requestId) {
+        const agentResult = this.dispatchAgent(executor, method, params);
+        if (agentResult !== undefined)
+            return agentResult;
+        switch (method) {
+            case 'executor.heartbeat': {
+                const result = {
+                    server_time: new Date().toISOString(),
+                    lease_ttl_ms: this.harness.options.leaseTtlMs,
+                    drain: executor.draining,
+                };
+                return result;
+            }
+            case 'session.ready': {
+                const ready = params;
+                const session = executor.sessionsById.get(ready?.session_id);
+                if (!session)
+                    throw rpcError(JsonRpcErrorCode.SessionNotActive, 'session is not active on this executor', false);
+                if (ready.lease_token && ready.lease_token !== session.leaseToken) {
+                    throw rpcError(JsonRpcErrorCode.LeaseExpired, 'lease token does not match', false);
+                }
+                session.markReady();
+                return { accepted: true };
+            }
+            case 'session.ended': {
+                const ended = params;
+                executor.sessionsById.get(ended?.session_id)?.end(ended.reason, () => new ToolOutcomeUnknownError());
+                return { accepted: true };
+            }
+            case 'tool.result': {
+                const result = params;
+                const session = executor.sessionsById.get(result?.session_id);
+                if (!session)
+                    throw rpcError(JsonRpcErrorCode.SessionNotActive, 'session is not active on this executor', false);
+                if (!session.complete(result)) {
+                    throw rpcError(JsonRpcErrorCode.NotFound, 'tool_call_id was not dispatched by this harness', false);
+                }
+                return { accepted: true };
+            }
+            case 'session.event':
+                return this.sessionEvent(executor, params, requestId);
+            default:
+                throw rpcError(JsonRpcErrorCode.MethodNotFound, `unknown method ${method}`, false);
+        }
+    }
+    async sessionEvent(executor, params, requestId) {
+        if (!executor.sessionsById.has(params?.session_id)) {
+            throw rpcError(JsonRpcErrorCode.SessionNotActive, 'session is not active on this executor', false);
+        }
+        // A retried JSON-RPC id is answered with the first result.
+        const previous = executor.eventIds.get(requestId);
+        if (previous)
+            return previous;
+        let result = { accepted: true, event_id: `evt_${randomId(8)}` };
+        if (this.harness.options.onSessionEvent) {
+            try {
+                result = await this.harness.options.onSessionEvent(executor, params);
+            }
+            catch (error) {
+                throw rpcError(JsonRpcErrorCode.InternalError, error instanceof Error ? error.message : String(error), true);
+            }
+        }
+        if (executor.eventIds.size >= MAX_REMEMBERED_EVENT_IDS)
+            executor.eventIds.clear();
+        executor.eventIds.set(requestId, result);
+        return result;
+    }
+    /** Agent methods; undefined for everything else, including session.event without event_id. */
+    dispatchAgent(executor, method, params) {
+        const platform = this.harness.options.agent;
+        if (!platform)
+            return undefined;
+        switch (method) {
+            case 'session.event': {
+                const event = params;
+                if (!event?.event_id)
+                    return undefined;
+                return this.agentEvent(platform, executor, event);
+            }
+            case 'interaction.request': {
+                const request = params;
+                const valid = request?.session_id &&
+                    request.interaction_id &&
+                    ((request.kind === 'permission' && request.tool_use_id) || (request.kind === 'question' && request.question));
+                if (!valid)
+                    return Promise.reject(rpcError(JsonRpcErrorCode.InvalidParams, 'invalid interaction.request params', false));
+                return platform.interactionRequested(executor, request).then((id) => ({ accepted: true, platform_interaction_id: id }), (error) => Promise.reject(rpcError(JsonRpcErrorCode.InternalError, String(error), true)));
+            }
+            case 'interaction.cancel': {
+                const cancel = params;
+                if (!cancel?.session_id || !cancel.interaction_id) {
+                    return Promise.reject(rpcError(JsonRpcErrorCode.InvalidParams, 'invalid interaction.cancel params', false));
+                }
+                return platform.interactionCanceled(executor, cancel).then(() => ({ accepted: true }), (error) => Promise.reject(rpcError(JsonRpcErrorCode.InternalError, String(error), true)));
+            }
+            default:
+                return undefined;
+        }
+    }
+    agentEvent(platform, executor, params) {
+        const event = params.event;
+        const type = typeof event?.type === 'string' ? event.type : '';
+        const sequence = params.sequence ?? 0;
+        if (!params.session_id || !params.turn_id || sequence < 1 || !AGENT_EVENT_TYPES.has(type)) {
+            return Promise.reject(rpcError(JsonRpcErrorCode.InvalidParams, 'invalid agent session.event', false));
+        }
+        const ledger = this.harness.ledger;
+        return ledger.serialize(params.session_id, async () => {
+            let acked = ledger.acked.get(params.session_id);
+            if (acked === undefined) {
+                try {
+                    acked = await platform.ackedSequence(params.session_id);
+                }
+                catch (error) {
+                    throw rpcError(JsonRpcErrorCode.InternalError, String(error), true);
+                }
+                ledger.acked.set(params.session_id, acked);
+            }
+            const result = { accepted: true, event_id: params.event_id, acked_sequence: acked };
+            if (sequence <= acked)
+                return result;
+            if (sequence !== acked + 1) {
+                this.harness.log('warn', `agent session.event sequence gap in ${params.session_id}`);
+                throw new RpcError(JsonRpcErrorCode.Conflict, 'conflict', { retryable: false, expected_sequence: acked + 1 });
+            }
+            try {
+                await platform.agentEvent(executor, {
+                    sessionId: params.session_id,
+                    turnId: params.turn_id,
+                    eventId: params.event_id,
+                    sequence,
+                    type,
+                    event: event,
+                });
+            }
+            catch (error) {
+                throw rpcError(JsonRpcErrorCode.InternalError, String(error), true);
+            }
+            ledger.acked.set(params.session_id, sequence);
+            return { ...result, acked_sequence: sequence };
+        });
+    }
+    onNotification(method, params) {
+        const executor = this.executor;
+        if (!executor)
+            return;
+        const options = this.harness.options;
+        switch (method) {
+            case 'session.event_delta': {
+                const delta = params;
+                if (options.agent && delta?.session_id && delta.event_id)
+                    options.agent.agentDelta(executor, delta);
+                return;
+            }
+            case 'session.status':
+                options.onSessionStatus?.(executor, params);
+                return;
+            case 'tool.progress':
+                options.onToolProgress?.(executor, params);
+                return;
+            case 'executor.capabilities.update': {
+                const capabilities = params?.capabilities;
+                if (capabilities)
+                    executor.capabilities = capabilities;
+                return;
+            }
+            case 'executor.close':
+                // A deliberate shutdown: no reconnect grace.
+                executor.forget('executor_closed');
+                this.conn.close(1000, 'executor.close');
+                return;
+        }
+    }
+}
+//# sourceMappingURL=harness.js.map