@anureo/adapter-hermes 0.0.0-stage → 0.3.0

package/src/rpc.js

@@ -0,0 +1,266 @@
+import { BoundedEventQueue, HarnessSdkError } from '@anureo/sdk';
+import { event, GATEWAY_PROTOCOL, HermesRpcError, object, protocolError } from "./native.js";
+/**
+ * Internal, bounded JSON-RPC channel for adapter probes and sessions. Responses settle requests
+ * immediately; events and server requests run serially so a handler can await an RPC acknowledgement.
+ * HermesAdapter.probeRuntime disposes its probe. HermesSession owns the channel during observation
+ * and disposes it on recovery or close.
+ */
+export class HermesRpc {
+    socket;
+    handlers;
+    options;
+    /** Install transport listeners and start serial delivery before connect waits for the opening handshake. */
+    constructor(socket, handlers, options) {
+        this.socket = socket;
+        this.handlers = handlers;
+        this.options = options;
+        this.queue = new BoundedEventQueue({ maxFrameBytes: options.maxFrameBytes, maxBytes: options.maxBufferedBytes, maxEvents: options.maxEvents });
+        this.finished = this.read().catch(cause => {
+            const error = cause instanceof HarnessSdkError ? cause : protocolError();
+            this.stop(error);
+            if (!this.disposed)
+                this.handlers.failure(error);
+        });
+        socket.binaryType = 'arraybuffer';
+        socket.addEventListener('message', message => {
+            if (this.closed)
+                return;
+            try {
+                this.receive(message.data);
+            }
+            catch (cause) {
+                this.stop(cause instanceof HarnessSdkError ? cause : protocolError());
+            }
+        });
+        socket.addEventListener('close', () => this.stop(new HarnessSdkError('CONNECTION_CLOSED', 'Hermes connection closed', false, true)));
+        socket.addEventListener('error', () => this.stop(new HarnessSdkError('CONNECTION_CLOSED', 'Hermes connection failed', false, true)));
+    }
+    /**
+     * Open a fresh grant and require hermes-gateway-v1 negotiation. Reject factory/open failures,
+     * timeout, protocol mismatch or abort; after channel construction, failure disposes its socket.
+     * The signal only cancels opening. On success the caller must dispose the channel separately
+     * and must use a freshly minted grant for each connection attempt.
+     */
+    static async connect(grant, handlers, options, signal) {
+        if (signal?.aborted)
+            throw new HarnessSdkError('RUNTIME_DISPOSED');
+        let socket;
+        try {
+            socket = options.webSocketFactory ? options.webSocketFactory(grant.url, [...grant.protocols]) : new WebSocket(grant.url, grant.protocols);
+        }
+        catch {
+            throw new HarnessSdkError('HARNESS_UNAVAILABLE', 'Cannot connect to Hermes gateway', true);
+        }
+        const client = new HermesRpc(socket, handlers, options);
+        try {
+            await waitForOpen(socket, options.timeoutMs ?? 30_000, signal);
+            return client;
+        }
+        catch (cause) {
+            client.dispose();
+            throw cause;
+        }
+    }
+    /** Whether the local channel still permits writes. HermesSession.ready uses this to decide when to recover. */
+    get connected() { return !this.closed && this.socket.readyState === 1; }
+    /**
+     * Resolve with the correlated native result, without waiting for event delivery or execution
+     * completion. Reject native RPC errors, admission/write failures, timeout or channel closure.
+     * HermesSession and HermesInteractions set mutation for submissions, creation, interrupts and
+     * prompt answers so timeout, channel loss or an unclassified write failure reports an unknown
+     * outcome. A request never retries or cancels remote work.
+     */
+    request(method, params = {}, mutation = false) {
+        if (!this.connected)
+            return Promise.reject(new HarnessSdkError('CONNECTION_CLOSED'));
+        if (this.pending.size >= (this.options.maxPending ?? 128))
+            return Promise.reject(new HarnessSdkError('BACKPRESSURE_EXCEEDED'));
+        const id = `anureo-${++this.nextId}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new HarnessSdkError('RPC_TIMEOUT', 'Hermes request timed out', false, mutation));
+            }, this.options.timeoutMs ?? 30_000);
+            this.pending.set(id, { resolve, reject, timer, mutation });
+            try {
+                this.send({ jsonrpc: '2.0', id, method, params });
+            }
+            catch (cause) {
+                this.forgetRequest(id, timer);
+                reject(cause instanceof HarnessSdkError ? cause : new HarnessSdkError('CONNECTION_CLOSED', 'Hermes write failed', false, mutation));
+            }
+        });
+    }
+    /**
+     * Send HermesInteractions' answer to a gateway request. Resolve after local socket.send, without
+     * remote acknowledgement; any write failure rejects RESULT_UNKNOWN with an unknown outcome.
+     */
+    reply(id, result) {
+        return this.respond({ jsonrpc: '2.0', id, result });
+    }
+    /** Reject an unsupported gateway request; delivery and failure semantics match reply. */
+    reject(id) {
+        return this.respond({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Unsupported client interaction' } });
+    }
+    /**
+     * Idempotently close local observation and reject pending RPCs without stopping native execution.
+     * Suppress failure callbacks; callers needing handler completion must also await finished.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.stop(new HarnessSdkError('CONNECTION_CLOSED', 'Hermes observation closed', false, true));
+    }
+    /**
+     * Settle when queued delivery ends and any failure callback returns. Disposal skips buffered
+     * entries and lets the active handler finish. HermesSession.retryRecovery awaits this before
+     * opening a replacement. Reader failures are reported to the callback, whose own throw rejects this promise.
+     */
+    finished;
+    queue;
+    pending = new Map();
+    nextId = 0;
+    closed = false;
+    disposed = false;
+    /**
+     * Deliver queued events/requests in order. The constructor's catch closes the channel on handler
+     * failure and reports it; disposed channels skip buffered entries while an active handler finishes.
+     */
+    async read() {
+        for await (const entry of this.queue) {
+            if (this.disposed)
+                continue;
+            if (entry.kind === 'event')
+                await this.handlers.event(entry.value);
+            else
+                await this.handlers.request(entry.value);
+        }
+    }
+    /** The message listener validates/routes each frame; throwing closes the channel through that listener. */
+    receive(raw) {
+        const frame = decodeFrame(raw, this.options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES);
+        const { id, method } = frame;
+        if (typeof method !== 'string') {
+            this.receiveResponse(frame);
+            return;
+        }
+        if (id === undefined) {
+            if (method === 'event')
+                this.queue.push({ kind: 'event', value: event(frame.params) });
+            return;
+        }
+        if (typeof id !== 'string' && (typeof id !== 'number' || !Number.isSafeInteger(id)))
+            throw protocolError();
+        this.queue.push({ kind: 'request', value: { id, method, params: object(frame.params ?? {}) } });
+    }
+    /**
+     * Settle matching requests without entering the handler queue. Ignore uncorrelated responses
+     * after checking the envelope, so late replies after timeout leave other requests pending.
+     */
+    receiveResponse(frame) {
+        const id = frame.id;
+        const hasError = Object.hasOwn(frame, 'error');
+        if ((typeof id !== 'string' && typeof id !== 'number') || Object.hasOwn(frame, 'result') === hasError)
+            throw protocolError();
+        const waiting = this.pending.get(id);
+        if (!waiting)
+            return;
+        // Invalid error data must leave the waiter visible so stop can reject it with the channel failure.
+        const nativeError = hasError ? new HermesRpcError(object(frame.error)) : undefined;
+        this.forgetRequest(id, waiting.timer);
+        if (nativeError)
+            waiting.reject(nativeError);
+        else
+            waiting.resolve(frame.result);
+    }
+    /** Release the pending slot and its deadline before settling a response or reporting a write failure. */
+    forgetRequest(id, timer) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+    }
+    /** Enforce per-frame and socket backlog limits before a synchronous write; callers decide how to report failures. */
+    send(frame) {
+        if (!this.connected)
+            throw new HarnessSdkError('CONNECTION_CLOSED', 'Hermes connection is closed');
+        const value = JSON.stringify(frame);
+        const bytes = Buffer.byteLength(value);
+        if (bytes > (this.options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES))
+            throw new HarnessSdkError('FRAME_TOO_LARGE');
+        if (this.socket.bufferedAmount + bytes > (this.options.maxBufferedBytes ?? 16 * 1024 * 1024))
+            throw new HarnessSdkError('BACKPRESSURE_EXCEEDED');
+        this.socket.send(value);
+    }
+    /** Share response delivery/error mapping so answers and unsupported-request replies cannot drift. */
+    respond(frame) {
+        try {
+            this.send(frame);
+            return Promise.resolve();
+        }
+        catch {
+            return Promise.reject(new HarnessSdkError('RESULT_UNKNOWN', 'Hermes response could not be delivered', false, true));
+        }
+    }
+    /** End observation once. Reject pending RPCs with their mutation uncertainty before ending queued delivery and closing the socket. */
+    stop(cause) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiting of this.pending.values()) {
+            clearTimeout(waiting.timer);
+            waiting.reject(new HarnessSdkError(cause.code, cause.message, false, waiting.mutation));
+        }
+        this.pending.clear();
+        this.queue.end(cause);
+        this.socket.close();
+    }
+}
+const DEFAULT_MAX_FRAME_BYTES = 8 * 1024 * 1024;
+/** Require bounded UTF-8 JSON-RPC input; decoding/parsing errors are normalized by the message listener. */
+function decodeFrame(raw, maxFrameBytes) {
+    let value;
+    if (typeof raw === 'string')
+        value = raw;
+    else if (raw instanceof ArrayBuffer)
+        value = new TextDecoder('utf-8', { fatal: true }).decode(raw);
+    else
+        throw protocolError();
+    if (Buffer.byteLength(value) > maxFrameBytes)
+        throw new HarnessSdkError('FRAME_TOO_LARGE');
+    const frame = object(JSON.parse(value));
+    if (frame.jsonrpc !== '2.0')
+        throw protocolError();
+    return frame;
+}
+/** Own opening listeners/deadline only; connect disposes the channel if negotiation, cancellation or transport fails. */
+function waitForOpen(socket, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.removeEventListener('open', opened);
+            socket.removeEventListener('close', failed);
+            socket.removeEventListener('error', failed);
+            signal?.removeEventListener('abort', aborted);
+        };
+        const opened = () => {
+            cleanup();
+            socket.protocol === GATEWAY_PROTOCOL ? resolve() : reject(new HarnessSdkError('HERMES_GATEWAY_UNSUPPORTED', 'Hermes WebSocket protocol mismatch'));
+        };
+        const failed = () => { cleanup(); reject(new HarnessSdkError('HARNESS_UNAVAILABLE', 'Hermes connection failed', true)); };
+        const aborted = () => { cleanup(); reject(new HarnessSdkError('RUNTIME_DISPOSED')); };
+        const timer = setTimeout(failed, timeoutMs);
+        socket.addEventListener('open', opened, { once: true });
+        socket.addEventListener('close', failed, { once: true });
+        socket.addEventListener('error', failed, { once: true });
+        signal?.addEventListener('abort', aborted, { once: true });
+        if (signal?.aborted) {
+            aborted();
+            return;
+        }
+        if (socket.readyState === 1)
+            opened();
+        else if (socket.readyState > 1)
+            failed();
+    });
+}

package/src/session.d.ts

@@ -0,0 +1,151 @@
+import { type BackendSession, type SessionEventSink, type SessionMethod } from '@anureo/sdk';
+import { type AhpRequestMap, type AhpResultMap, type Capabilities, type SessionBinding, type SessionOpenParams, type SessionState } from '@anureo/protocol';
+import type { HermesAdapterOptions } from "./options.js";
+/** Return a fresh native capability snapshot for HermesAdapter.initialize and each HermesSession. */
+export declare function hermesCapabilities(): Capabilities;
+/**
+ * Internal BackendSession owned by HermesAdapter.openSession and adopted by OutputSession.open.
+ * Reconcile durable admissions and replay before releasing live traffic; native acceptance and turn
+ * completion remain independent. The owner must dispose this observation, including after open fails.
+ */
+export declare class HermesSession implements BackendSession {
+    /** Native session capabilities read by OutputSession before it applies any structured-output fallback. */
+    readonly capabilities: Capabilities;
+    /** SDK identity augmented with the native reference after snapshot validation. */
+    binding: SessionBinding;
+    /** Set up local observation state for HermesAdapter.openSession. Call open before dispatching native requests. */
+    constructor({ params, sink, options, profileId, released }: {
+        params: SessionOpenParams;
+        sink: SessionEventSink;
+        options: HermesAdapterOptions;
+        profileId: string;
+        /** Remove this handle from HermesAdapter's tracked sessions when local disposal finishes. */
+        released: () => void;
+    });
+    /** Supply OutputSession with the native attachment snapshot, including active turns restored from pending rows. */
+    get state(): SessionState;
+    /**
+     * HermesAdapter.openSession awaits connection, creation/resume, snapshot projection and held events.
+     * Reject native/validation/publication failures; the adapter disposes partial setup before rethrowing.
+     */
+    open(): Promise<void>;
+    /**
+     * Handle a native submission, interrupt or observation close for OutputSession.execute. A queued
+     * receipt confirms admission, and a later native claim publishes its turn binding. Interrupt
+     * acknowledges the targeted generation, while turn completion arrives through the sink.
+     * Close attempts detach and disposes local observation with execution stop unconfirmed.
+     * Reject invalid bindings, unsupported requests and native failures with their outcome uncertainty.
+     */
+    execute<M extends SessionMethod>(method: M, params: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
+    /** Idempotently abort local work, drop retained evidence and release adapter tracking; native execution is left running. */
+    dispose(): Promise<void>;
+    private nativeId;
+    private rpc?;
+    private description?;
+    private subscriptionId;
+    private cursor;
+    private readonly submissions;
+    private submissionBytes;
+    private readonly turns;
+    private readonly retired;
+    private readonly interactions;
+    private holding;
+    private held;
+    private heldBytes;
+    private recovery?;
+    private readonly ownerRecoveries;
+    private disposed;
+    private readonly abort;
+    private title?;
+    private model?;
+    /**
+     * Ask a connected owner to detach, then release local observation. Report an unconfirmed detach
+     * through the diagnostic callback. A callback exception rejects close before disposal.
+     */
+    private closeObservation;
+    /**
+     * After channel recovery, interrupt only a live turn in the current authority. Verify the ACK
+     * against the original turn, which may have completed while the request was in flight.
+     */
+    private interrupt;
+    /** Request the initial attachment snapshot. Only creation sends editor configuration, after capability discovery. */
+    private openSnapshot;
+    /** Preserve omission of toolsets/model and opt into ACP only for explicitly supplied session MCP servers. */
+    private createParameters;
+    /** Require local channel setup; connectedness and recovery are checked separately by ready. */
+    private channel;
+    /**
+     * Attach and describe the expected profile. HermesRpc invokes these event/request callbacks
+     * serially. Process traffic only from the current channel while the session is live. The RPC
+     * failure callback starts recovery or reports observation loss through sink.fail. The session
+     * owns successful channels and disposes them on retry or teardown.
+     */
+    private connect;
+    /** Reject overflow during setup or recovery because dropping held traffic would lose correlation evidence. */
+    private hold;
+    /** RPC's request callback buffers during reconciliation, otherwise registers a nonblocking interaction. */
+    private serverRequest;
+    /** RPC's event callback buffers during reconciliation, otherwise awaits ordered projection. */
+    private receive;
+    /** Drain held batches, including traffic arriving during awaits; only snapshot recovery tolerates replay discontinuity. */
+    private flush;
+    /** Reuse an execution only with matching authority/generation; evict terminal turns only when unacknowledged inputs cannot need them. */
+    private turn;
+    /**
+     * Match receipt evidence to local inputs, publish bindings and project any supplied terminal result.
+     * Receipts without an execution generation create no turn; unknown execution or transferred local input
+     * rejects with outcome uncertainty. Snapshot, event, submit and recovery paths all use this rule.
+     */
+    private associate;
+    /** Record evidence before publishing a binding or reporting uncertainty. A known input cannot change admissions. */
+    private recordAdmission;
+    /** Validate admission evidence against this observation's profile and native session. */
+    private parseReceipt;
+    /** Adopt validated attachment identity/metadata, then reconcile native pending rows and interactions before releasing held traffic. */
+    private snapshot;
+    /** Trust the pending row's explicit input id only for a locally tracked submission. */
+    private associatePending;
+    /** Apply live or replayed traffic, advancing the cursor only after all resulting publications succeed. */
+    private apply;
+    /** Ignore unrelated or already applied events, but send explicit replay gaps back through recovery. */
+    private eventPosition;
+    /**
+     * Associate native execution evidence before projecting progress. A terminal event waits only for
+     * responders already delivering answers, so their ACK/settlement can precede turn completion.
+     */
+    private applyTurnEvent;
+    /** Await any current recovery, or start one for a disconnected channel, before dispatching another request. */
+    private ready;
+    /** Share one recovery across RPC failure callbacks and request paths; keep live traffic held until reconciliation succeeds. */
+    private recover;
+    /** Wait for the old reader and run the retry budget. Dispose failed channels and propagate the first non-retryable failure or the final retryable one. */
+    private retryRecovery;
+    /** Open a replacement channel and reconcile execution evidence before restoring live delivery. */
+    private recoverObservation;
+    /** Try attachment first; subsequent attempts may request owner recovery within the rolling per-session budget. */
+    private recoveryMode;
+    /** Replay available events, reconcile the resume snapshot and watermark, then select continuity for the final held batch. */
+    private replaySnapshot;
+    /** Query known admissions during recovery. Reject if terminal evidence still leaves an associated turn unfinished. */
+    private reconcileAdmissions;
+    /** Fetch and validate result-bearing receipt evidence for both submit completion and recovery reconciliation. */
+    private resultReceipt;
+    /** Mark every retained live turn's intermediate progress incomplete; each turn emits at most one notice. */
+    private reportProgressGap;
+    /**
+     * Dispatch a text-only native input once. Resolve a queued or started admission after reconciling
+     * available evidence, or reject while retaining correlation for uncertain acceptance.
+     */
+    private submit;
+    /** Enforce identity/count/byte budgets before native dispatch, evicting only acknowledged inputs with known outcomes. */
+    private retainInput;
+    /** Recover evidence after a retryable submit failure. Return the recovered admission or reject with an unknown outcome. */
+    private submitReceipt;
+    /** Release retained text idempotently without discarding the admission's replay/correlation guard. */
+    private releaseInput;
+    private readonly params;
+    private readonly sink;
+    private readonly options;
+    private readonly profileId;
+    private readonly released;
+}