@anureo/adapter-hermes 0.0.0-stage → 0.3.0

package/src/interactions.js

@@ -0,0 +1,206 @@
+import { HarnessSdkError } from '@anureo/sdk';
+import { array, identity, integer, object, protocolError, stableId, text } from "./native.js";
+/**
+ * Internal interaction registry owned by HermesSession. Map replayed prompts and gateway requests
+ * to stable SDK interaction ids without blocking the serial reader on user answers. The two native
+ * mechanisms share this registry but retain their different acknowledgement semantics. The SDK
+ * Session owns handler cancellation and answer privacy. HermesSession owns channel cleanup and recovery.
+ */
+export class HermesInteractions {
+    /** Capture callbacks supplied by HermesSession; resolve identity/channel lazily so pending answers use the recovered connection. */
+    constructor({ sessionId, rpc, sink, turnId, epoch, options }) {
+        this.sessionId = sessionId;
+        this.rpc = rpc;
+        this.sink = sink;
+        this.turnId = turnId;
+        this.epoch = epoch;
+        this.options = options;
+    }
+    /**
+     * Register an approval/clarification from HermesSession.apply or snapshot, ignoring replayed ids.
+     * Invalid prompts and a full registry reject registration. The sink can invoke the responder with
+     * an answer or null, which sends a denial or empty clarification. Delivery checks the current
+     * authority before sending once and requires a native ACK for the same prompt id. The sink
+     * observes delivery failures through the responder.
+     */
+    async prompt(value) {
+        const nativeId = identity(value.prompt_id), generation = integer(value.execution_generation), epoch = this.epoch();
+        const id = `hermes-prompt-${stableId(this.sessionId(), epoch, generation, nativeId)}`;
+        if (this.pending.has(id))
+            return;
+        const kind = value.kind;
+        if (kind !== 'approval' && kind !== 'clarify')
+            throw protocolError();
+        const request = kind === 'approval' ? approvalRequest(id, value)
+            : { interactionId: id, kind: 'userInput', questions: [this.question(nativeId, text(value.question), value.choices)] };
+        const scopedTurn = this.turnId(generation);
+        if (scopedTurn)
+            request.turnId = scopedTurn;
+        if (typeof value.timeout_s === 'number' && value.timeout_s > 0)
+            request.expiresAt = new Date(Date.now() + value.timeout_s * 1000).toISOString();
+        const pending = { id, nativeId, generation, wire: 'prompt', done: false, responding: false };
+        this.register(pending, request, async (response) => {
+            if (this.epoch() !== epoch)
+                throw new HarnessSdkError('INTERACTION_EXPIRED');
+            const params = { session_id: this.sessionId(), execution_generation: generation, prompt_id: nativeId };
+            const answer = kind === 'approval'
+                ? { ...params, choice: response?.kind === 'approval' ? response.optionId : 'deny' }
+                : { ...params, answer: response?.kind === 'userInput' ? this.answer(response.answers[nativeId]) : '' };
+            const result = object(await this.rpc().request(kind === 'approval' ? 'approval.respond' : 'clarify.respond', answer, true));
+            if (result.prompt_id !== nativeId || !['resolved', 'already_resolved'].includes(String(result.status)))
+                throw protocolError();
+            if (result.status === 'already_resolved')
+                throw new HarnessSdkError('INTERACTION_ALREADY_RESOLVED', 'Hermes prompt already settled', false, true);
+        });
+    }
+    /**
+     * Register session-scoped srq requests from HermesSession's live or held traffic, or from snapshot.
+     * Reply with a native error for unsupported requests and reject malformed supported payloads.
+     * The sink owns the wait for answers. The responder resolves after local send, so snapshot checks
+     * whether a finished delivery still appears open remotely.
+     */
+    async serverRequest(request) {
+        if (request.params.session_id !== this.sessionId()) {
+            await this.rpc().reject(request.id);
+            return;
+        }
+        if (typeof request.id !== 'string' || !request.id.startsWith('srq-')) {
+            await this.rpc().reject(request.id);
+            return;
+        }
+        const id = `hermes-request-${stableId(this.sessionId(), request.id)}`;
+        if (this.pending.has(id))
+            return;
+        let questions;
+        if (request.method === 'clarify') {
+            questions = this.batchQuestions(request.params);
+        }
+        else if (request.method === 'sudo' || request.method === 'secret') {
+            questions = [{ id: 'value', prompt: request.method === 'sudo' ? 'Hermes requests a sudo password' : text(request.params.prompt), secret: true }];
+        }
+        else {
+            await this.rpc().reject(request.id);
+            return;
+        }
+        const pending = { id, nativeId: request.id, wire: 'request', done: false, responding: false };
+        this.register(pending, { interactionId: id, kind: 'userInput', questions }, async (response) => {
+            const answers = response?.kind === 'userInput' ? response.answers : undefined;
+            const result = request.method === 'clarify'
+                ? { answers: Object.fromEntries(questions.map(question => [question.id, answers ? this.answer(answers[question.id]) : null])), outcome: answers ? 'submitted' : 'cancelled' }
+                : { value: answers ? this.answer(answers.value) : '' };
+            await this.rpc().reply(request.id, result);
+        });
+    }
+    /** Let deliveries already in flight settle before HermesSession.applyTurnEvent projects a terminal frame. The sink handles their outcomes. */
+    async waitResponders() {
+        // A terminal frame may beat the native response ACK. The reader still routes ACKs directly.
+        await Promise.all([...this.pending.values()].filter(value => value.responding && !value.done).map(value => value.completion));
+    }
+    /**
+     * Handle peer settlement from HermesSession.apply or withdrawal from snapshot. Match prompt
+     * generations to fence reused ids and leave in-flight delivery to its own settlement path.
+     * Publish an unknown outcome for a bare native resolved signal because it carries no answer.
+     * Sink publication failures reject to the caller.
+     */
+    async settled(target, reason) {
+        for (const pending of this.pending.values()) {
+            if (pending.done || pending.nativeId !== target.nativeId || pending.wire !== target.wire || target.wire === 'prompt' && pending.generation !== target.generation)
+                continue;
+            pending.cancelled = reason;
+            if (pending.responding)
+                continue; // The local native ACK arbitrates the response already in flight.
+            pending.done = true;
+            await this.sink.resolveInteraction({ interactionId: pending.id, outcome: reason === 'timeout' ? 'expired' : reason === 'resolved' ? 'unknown' : 'cancelled', reason: reason === 'resolved' ? 'native_settled' : reason });
+        }
+    }
+    /**
+     * HermesSession.snapshot reconciles open native questions before releasing held traffic. Withdraw
+     * missing questions and register new ones; reject RESULT_UNKNOWN if a locally finished delivery is
+     * still open remotely, preventing silent suppression or replay of a possibly delivered secret.
+     */
+    async snapshot(prompts, requests) {
+        const promptIds = new Set(prompts.map(value => identity(object(value).prompt_id)));
+        const requestIds = new Set(requests.map(value => identity(object(value).id)));
+        for (const value of this.pending.values())
+            if (value.done && !value.cancelled && (value.wire === 'prompt' ? promptIds : requestIds).has(value.nativeId)) {
+                // A response may have left this process without reaching the owner. Never replay a secret
+                // or silently suppress the still-open native question as though it had been answered.
+                throw new HarnessSdkError('RESULT_UNKNOWN', 'Hermes interaction delivery could not be confirmed', false, true);
+            }
+        for (const value of this.pending.values())
+            if (!value.done && !(value.wire === 'prompt' ? promptIds : requestIds).has(value.nativeId)) {
+                await this.settled(value, 'withdrawn');
+            }
+        for (const value of prompts)
+            await this.prompt(object(value));
+        for (const value of requests) {
+            const entry = object(value);
+            await this.serverRequest({ id: identity(entry.id), method: identity(entry.method), params: object(entry.params) });
+        }
+    }
+    pending = new Map();
+    /** Parse a nonempty clarify batch with distinct native question ids so one answer can be sent per id. */
+    batchQuestions(params) {
+        const questions = array(params.questions).map(value => {
+            const question = object(value);
+            return this.question(identity(question.qid), text(question.question), question.choices);
+        });
+        if (!questions.length || new Set(questions.map(value => value.id)).size !== questions.length)
+            throw protocolError();
+        return questions;
+    }
+    /** Normalize optional native choices; null, omission and an empty array all leave the question open-ended. */
+    question(id, prompt, choices) {
+        const values = choices == null ? [] : array(choices);
+        return { id, prompt, ...(values.length ? { options: values.map(value => ({ id: text(value), label: text(value) })) } : {}) };
+    }
+    /** Encode SDK answers for Hermes text fields; unanswered/null values become empty text and string selections are comma-separated. */
+    answer(value) {
+        if (Array.isArray(value) && value.every(entry => typeof entry === 'string'))
+            return value.join(', ');
+        if (value === undefined || value === null)
+            return '';
+        return text(value);
+    }
+    /**
+     * Admit within registry budgets and register the responder with the SDK sink. Session invokes it
+     * for unsupported or closed requests, and InteractionRegistry invokes it for answers and
+     * cancellations. Mark delivery in flight before writing so native settlement can defer to it.
+     * Observe fulfillment and rejection as local completion without blocking the reader on the user.
+     */
+    register(pending, request, respond) {
+        if ([...this.pending.values()].filter(value => !value.done).length >= (this.options.maxInteractions ?? 32))
+            throw new HarnessSdkError('BACKPRESSURE_EXCEEDED');
+        if (this.pending.size >= (this.options.maxInteractions ?? 32) + 1024) {
+            const retired = [...this.pending].find(([, value]) => value.done);
+            if (retired)
+                this.pending.delete(retired[0]);
+        }
+        this.pending.set(pending.id, pending);
+        // Do not await the user from the receive loop. Core owns cancellation and response privacy.
+        pending.completion = this.sink.requestInteraction(request, async (response) => {
+            if (pending.done)
+                throw new HarnessSdkError('INTERACTION_EXPIRED');
+            pending.responding = true;
+            await respond(response);
+            if (pending.cancelled && pending.cancelled !== 'resolved')
+                throw new HarnessSdkError('RESULT_UNKNOWN', 'Hermes interaction ended while responding', false, true);
+        }).then(() => { pending.done = true; }, () => { pending.done = true; });
+    }
+    sessionId;
+    rpc;
+    sink;
+    turnId;
+    epoch;
+    options;
+}
+/** Offer only supported native approval choices and require an explicit denial path. */
+function approvalRequest(id, value) {
+    const semantics = { once: 'allowOnce', session: 'allowSession', deny: 'deny' };
+    const options = array(value.choices).map(text).filter((choice) => Object.hasOwn(semantics, choice))
+        .map(choice => ({ id: choice, label: choice, semantic: semantics[choice] }));
+    if (!options.some(option => option.id === 'deny'))
+        throw protocolError();
+    return { interactionId: id, kind: 'approval', options, title: 'Hermes approval',
+        input: { ...(typeof value.command === 'string' ? { command: value.command } : {}), ...(typeof value.description === 'string' ? { description: value.description } : {}) } };
+}

package/src/native.d.ts

@@ -0,0 +1,97 @@
+import { HarnessSdkError } from '@anureo/sdk';
+import type { JsonObject, JsonValue } from '@anureo/protocol';
+/** Internal gateway object after only a non-null, non-array shape check; fields remain untrusted. */
+export type NativeObject = Record<string, unknown>;
+/** Validated runtime identity and creation capabilities consumed by HermesSession.open and adapter initialization. */
+export interface Description {
+    instanceId: string;
+    profileId: string;
+    /** Owner authority epoch; sessions bind executions and interaction answers to this authority. */
+    epoch: number;
+    /** Advertised session.create parameter names used to gate optional configuration. */
+    createParameters: string[];
+    /** True only when the ACP source, editor parameter and session MCP capability are all advertised. */
+    editorMcp: boolean;
+}
+/** Validated durable admission evidence; acceptance alone does not establish that execution has started or finished. */
+export interface Receipt {
+    id: string;
+    /** Native admission sequence, distinct from the replay event sequence. */
+    sequence: number;
+    status: 'queued' | 'started' | 'unknown' | 'terminal';
+    /** Native outcome when supplied, passed to turn projection for terminal receipts. */
+    outcome: string | null;
+    epoch: number;
+    /** Required for started receipts; absent terminal generations can describe cancellation before execution. */
+    generation?: number;
+    /** Native submission identity used to match local inputs during snapshot reconciliation. */
+    inputId?: string;
+    /** A native transfer to steering rather than a locally queued execution. */
+    steering?: boolean;
+    /** Optional terminal evidence; HermesTurn.fromReceipt validates the fields it consumes. */
+    result?: NativeObject;
+}
+/** Gateway event envelope; HermesSession validates session/replay continuity and HermesTurn validates event-specific payloads. */
+export interface NativeEvent {
+    type: string;
+    /** Absent for global notifications, including an empty native session id. */
+    session_id?: string;
+    payload: NativeObject;
+    /** Position within the replay history named by replay_epoch. */
+    seq?: number;
+    replay_epoch?: string;
+    authority_epoch?: number;
+    execution_generation?: number;
+    admission_id?: string;
+}
+/** Wire identifier required in the CLI grant and in the WebSocket handshake. */
+export declare const GATEWAY_PROTOCOL = "hermes-gateway-v1";
+/** Create a malformed-message error with unknown outcome. Attach and the adapter probe clear uncertainty for their read-only failures. */
+export declare const protocolError: () => HarnessSdkError;
+/** Require a non-null, non-array object without validating fields; throw PROTOCOL_ERROR on other shapes. */
+export declare function object(value: unknown): NativeObject;
+/** Require a string, allowing empty text for message content and answers; otherwise throw PROTOCOL_ERROR. */
+export declare function text(value: unknown): string;
+/** Require an identifier of 1..4096 UTF-16 code units; otherwise throw PROTOCOL_ERROR. */
+export declare function identity(value: unknown): string;
+/** Require a nonnegative safe integer for gateway counters and epochs; otherwise throw PROTOCOL_ERROR. */
+export declare function integer(value: unknown): number;
+/** Require an array without validating its elements; otherwise throw PROTOCOL_ERROR. */
+export declare function array(value: unknown): unknown[];
+/**
+ * Hash JSON-serializable identity parts in order for HermesTurn and HermesInteractions' replay-stable
+ * local ids. This is an identity hash, not credential protection; serialization failures propagate.
+ */
+export declare function stableId(...parts: unknown[]): string;
+/** Detach native tool input/output through a JSON round trip for HermesTurn.apply. Serialization or parse failures propagate. */
+export declare function json(value: unknown): JsonValue;
+/**
+ * Validate runtime.describe against the fresh attach identity and required gateway capabilities.
+ * HermesAdapter.probeRuntime publishes capabilities only after this succeeds; HermesSession.connect
+ * stores the result for session creation and epoch checks. Throw SESSION_BINDING_MISMATCH for a
+ * different owner/profile, HERMES_GATEWAY_UNSUPPORTED for missing capabilities, or PROTOCOL_ERROR
+ * for malformed fields. Extra capabilities are accepted and creation parameters are retained.
+ */
+export declare function describe(value: unknown, expected: {
+    instanceId: string;
+    profileId: string;
+}): Description;
+/**
+ * Parse a durable admission for HermesSession.parseReceipt, rejecting a different profile/session
+ * with SESSION_BINDING_MISMATCH and malformed evidence with PROTOCOL_ERROR. A started admission
+ * requires an execution generation; terminal result payloads remain subject to HermesTurn validation.
+ */
+export declare function receipt(value: unknown, profileId: string, sessionId: string): Receipt;
+/** Select the admission metadata HermesSession.submit returns to SDK callers; omit native input, steering and result evidence. */
+export declare function publicReceipt(value: Receipt): JsonObject;
+/**
+ * Parse a gateway event envelope for live RPC delivery or HermesSession.replaySnapshot, throwing
+ * PROTOCOL_ERROR for malformed fields. Missing/null payload becomes {}; session continuity and
+ * event-specific payload validation remain with HermesSession.apply and HermesTurn.apply.
+ */
+export declare function event(value: unknown): NativeEvent;
+/** Map a gateway rejection for HermesRpc.receiveResponse without retaining native error messages or data. */
+export declare class HermesRpcError extends HarnessSdkError {
+    /** Map an explicit rejection to a known-outcome failure; only storage_unavailable is retryable. Array-shaped error data throws PROTOCOL_ERROR. */
+    constructor(error: NativeObject);
+}

package/src/native.js

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { HarnessSdkError } from '@anureo/sdk';
+/** Wire identifier required in the CLI grant and in the WebSocket handshake. */
+export const GATEWAY_PROTOCOL = 'hermes-gateway-v1';
+/** Create a malformed-message error with unknown outcome. Attach and the adapter probe clear uncertainty for their read-only failures. */
+export const protocolError = () => new HarnessSdkError('PROTOCOL_ERROR', 'Invalid Hermes gateway message', false, true);
+/** Require a non-null, non-array object without validating fields; throw PROTOCOL_ERROR on other shapes. */
+export function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw protocolError();
+    return value;
+}
+/** Require a string, allowing empty text for message content and answers; otherwise throw PROTOCOL_ERROR. */
+export function text(value) {
+    if (typeof value !== 'string')
+        throw protocolError();
+    return value;
+}
+/** Require an identifier of 1..4096 UTF-16 code units; otherwise throw PROTOCOL_ERROR. */
+export function identity(value) {
+    const result = text(value);
+    if (!result.length || result.length > 4096)
+        throw protocolError();
+    return result;
+}
+/** Require a nonnegative safe integer for gateway counters and epochs; otherwise throw PROTOCOL_ERROR. */
+export function integer(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw protocolError();
+    return value;
+}
+/** Require an array without validating its elements; otherwise throw PROTOCOL_ERROR. */
+export function array(value) {
+    if (!Array.isArray(value))
+        throw protocolError();
+    return value;
+}
+/**
+ * Hash JSON-serializable identity parts in order for HermesTurn and HermesInteractions' replay-stable
+ * local ids. This is an identity hash, not credential protection; serialization failures propagate.
+ */
+export function stableId(...parts) {
+    return createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+/** Detach native tool input/output through a JSON round trip for HermesTurn.apply. Serialization or parse failures propagate. */
+export function json(value) { return JSON.parse(JSON.stringify(value)); }
+/**
+ * Validate runtime.describe against the fresh attach identity and required gateway capabilities.
+ * HermesAdapter.probeRuntime publishes capabilities only after this succeeds; HermesSession.connect
+ * stores the result for session creation and epoch checks. Throw SESSION_BINDING_MISMATCH for a
+ * different owner/profile, HERMES_GATEWAY_UNSUPPORTED for missing capabilities, or PROTOCOL_ERROR
+ * for malformed fields. Extra capabilities are accepted and creation parameters are retained.
+ */
+export function describe(value, expected) {
+    const data = object(value);
+    const creation = object(data.session_create);
+    if (data.instance_id !== expected.instanceId || data.profile_id !== expected.profileId)
+        throw new HarnessSdkError('SESSION_BINDING_MISMATCH');
+    const capabilities = array(data.capabilities).map(identity);
+    const sources = array(creation.sources).map(identity);
+    const parameters = array(creation.parameters).map(identity);
+    assertCanonicalCreation({ capabilities, sources, parameters });
+    return {
+        instanceId: expected.instanceId,
+        profileId: expected.profileId,
+        epoch: integer(data.authority_epoch),
+        createParameters: parameters,
+        editorMcp: capabilities.includes('acp-session-mcp-v1') && sources.includes('acp') && parameters.includes('editor'),
+    };
+}
+/**
+ * Parse a durable admission for HermesSession.parseReceipt, rejecting a different profile/session
+ * with SESSION_BINDING_MISMATCH and malformed evidence with PROTOCOL_ERROR. A started admission
+ * requires an execution generation; terminal result payloads remain subject to HermesTurn validation.
+ */
+export function receipt(value, profileId, sessionId) {
+    const data = object(value), ref = object(data.ref);
+    if (ref.profile_id !== profileId || ref.session_id !== sessionId)
+        throw new HarnessSdkError('SESSION_BINDING_MISMATCH');
+    if (!['queued', 'started', 'unknown', 'terminal'].includes(String(data.status)))
+        throw protocolError();
+    const generation = data.execution_generation == null ? undefined : integer(data.execution_generation);
+    if (data.status === 'started' && generation === undefined)
+        throw protocolError();
+    return {
+        id: identity(data.admission_id), sequence: integer(data.sequence), status: data.status,
+        outcome: data.outcome == null ? null : text(data.outcome), epoch: integer(data.authority_epoch), generation,
+        ...(data.input_id !== undefined ? { inputId: identity(data.input_id) } : {}),
+        ...(data.steering === true ? { steering: true } : {}),
+        ...(data.result != null ? { result: object(data.result) } : {}),
+    };
+}
+/** Select the admission metadata HermesSession.submit returns to SDK callers; omit native input, steering and result evidence. */
+export function publicReceipt(value) {
+    return { admissionId: value.id, sequence: value.sequence, status: value.status, authorityEpoch: value.epoch,
+        ...(value.generation !== undefined ? { executionGeneration: value.generation } : {}) };
+}
+/**
+ * Parse a gateway event envelope for live RPC delivery or HermesSession.replaySnapshot, throwing
+ * PROTOCOL_ERROR for malformed fields. Missing/null payload becomes {}; session continuity and
+ * event-specific payload validation remain with HermesSession.apply and HermesTurn.apply.
+ */
+export function event(value) {
+    const data = object(value);
+    return {
+        type: identity(data.type), payload: data.payload == null ? {} : object(data.payload),
+        // Global notifications such as sessions.changed use an empty session ID.
+        ...(data.session_id !== undefined && data.session_id !== '' ? { session_id: identity(data.session_id) } : {}),
+        ...(data.seq !== undefined ? { seq: integer(data.seq) } : {}),
+        ...(data.replay_epoch !== undefined ? { replay_epoch: identity(data.replay_epoch) } : {}),
+        ...(data.authority_epoch !== undefined ? { authority_epoch: integer(data.authority_epoch) } : {}),
+        ...(data.execution_generation !== undefined ? { execution_generation: integer(data.execution_generation) } : {}),
+        ...(data.admission_id !== undefined ? { admission_id: identity(data.admission_id) } : {}),
+    };
+}
+/** Map a gateway rejection for HermesRpc.receiveResponse without retaining native error messages or data. */
+export class HermesRpcError extends HarnessSdkError {
+    /** Map an explicit rejection to a known-outcome failure; only storage_unavailable is retryable. Array-shaped error data throws PROTOCOL_ERROR. */
+    constructor(error) {
+        const reason = error.data && typeof error.data === 'object' ? object(error.data).reason : undefined;
+        const code = typeof reason === 'string' ? REASONS[reason] : undefined;
+        super(code ?? (error.code === -32601 ? 'METHOD_NOT_FOUND' : error.code === -32602 ? 'INVALID_PARAMS' : 'NATIVE_RPC_ERROR'), 'Hermes gateway refused the request', reason === 'storage_unavailable', false);
+    }
+}
+/** Reject owners that cannot create ordinary sessions and recover their durable admissions and event history. */
+function assertCanonicalCreation({ capabilities, sources, parameters }) {
+    if (!['durable-admission-v1', 'event-replay-v1', 'local-cli-create-v1'].every(value => capabilities.includes(value))
+        || !sources.includes('tool')
+        || !['request_id', 'source', 'cwd', 'model'].every(value => parameters.includes(value))) {
+        throw new HarnessSdkError('HERMES_GATEWAY_UNSUPPORTED', 'Hermes canonical gateway capabilities are required');
+    }
+}
+const REASONS = {
+    invalid_params: 'INVALID_PARAMS', permission_denied: 'AUTHORIZATION_FAILED', profile_mismatch: 'SESSION_BINDING_MISMATCH',
+    stale_generation: 'TURN_NOT_ACTIVE', not_found: 'SESSION_NOT_FOUND', admission_conflict: 'SUBMISSION_ID_CONFLICT',
+    queue_full: 'BACKPRESSURE_EXCEEDED', session_busy: 'SESSION_BUSY', storage_unavailable: 'HARNESS_UNAVAILABLE',
+    unsupported_control: 'CAPABILITY_UNSUPPORTED', execution_not_ready: 'TURN_NOT_ACTIVE',
+};

package/src/options.d.ts

@@ -0,0 +1,60 @@
+import type { HarnessProcess, HarnessProcessOptions } from '@anureo/sdk/process';
+/**
+ * Configure createHermesAdapter's local CLI attachment, gateway channel and session budgets.
+ * Numeric values must be safe integers; limits and timeouts are positive except the explicitly
+ * zero-enabled recovery settings below. Millisecond values must fit a signed 32-bit timer.
+ */
+export interface HermesAdapterOptions {
+    /** Hermes executable or wrapper; defaults to 'hermes'. Must be nonempty and contain no NUL. */
+    command?: string;
+    /** Arguments preceding Hermes CLI arguments, for a wrapper executable; entries must contain no NUL. */
+    args?: string[];
+    /** CLI profile selection; omit to use the CLI default. Must contain non-whitespace text and no NUL. */
+    profile?: string;
+    /** Native toolsets for new sessions; [] disables model tools. Omit to inherit the profile. Names must be nonblank and contain no NUL. */
+    toolsets?: string[];
+    /** Complete child environment; omitted means inherit. */
+    env?: Record<string, string | undefined>;
+    /** Defaults to start, which ensures a shared owner. attach uses an existing owner even during reconnects. */
+    startup?: 'start' | 'attach';
+    /** Separate deadline in ms for CLI response after spawn, WebSocket open and each RPC response. Defaults to 30,000. */
+    timeoutMs?: number;
+    /** Maximum UTF-8 frame/queued-entry bytes; defaults to 8 MiB. CLI attach stdout has its own 64 KiB cap. */
+    maxFrameBytes?: number;
+    /** Byte budget for socket backlog and, separately, incoming buffers, retained inputs and each turn's items; defaults to 16 MiB. */
+    maxBufferedBytes?: number;
+    /** Separate count limit for the incoming queue and traffic held during setup or recovery. Defaults to 2048 each. */
+    maxEvents?: number;
+    /** Maximum outstanding RPC requests per channel; defaults to 128. */
+    maxPending?: number;
+    /** Maximum unresolved interactions per session; defaults to 32. Settled identities are retained separately. */
+    maxInteractions?: number;
+    /** Maximum retained executions per session; defaults to 128. Eligible terminal executions are evicted first. */
+    maxExecutions?: number;
+    /** Maximum retained submissions per session; defaults to 1024. Eligible acknowledged submissions are evicted first. */
+    maxSubmissions?: number;
+    /** Attempts per session recovery cycle, including the first attach-only attempt. Defaults to 3. Zero disables automatic recovery. */
+    reconnectAttempts?: number;
+    /** Base retry delay in ms, doubled after each delayed attempt; defaults to 100. First attempt is immediate; zero selects a zero-ms delay. */
+    reconnectDelayMs?: number;
+    /** Owner recovery requests per session in a rolling minute; defaults to 2. Zero prohibits owner recovery. */
+    maxOwnerRecoveriesPerMinute?: number;
+    /**
+     * Replace CLI spawning for each ticket request. Resolve with usable pipes and exit observation
+     * and release partial resources on rejection. The adapter takes ownership of the returned
+     * handle and awaits its disposal, including when attachment fails.
+     */
+    processFactory?: (options: HarnessProcessOptions) => Promise<HarnessProcess>;
+    /**
+     * Replace WebSocket construction for each ticket. Return a socket that implements the standard
+     * WebSocket interface. Keep the credential subprotocol private. The adapter owns socket closure.
+     */
+    webSocketFactory?: (url: string, protocols: string[]) => WebSocket;
+    /**
+     * Receive fixed diagnostic codes synchronously when attach reports stderr or session detach
+     * cannot be confirmed. Return normally so detach cleanup can proceed.
+     */
+    diagnostic?: (code: string) => void;
+}
+/** Validate configuration synchronously; HermesAdapter's constructor converts failures to INVALID_PARAMS before starting resources. */
+export declare function validateOptions(options: HermesAdapterOptions): void;

package/src/options.js

@@ -0,0 +1,29 @@
+/** Validate configuration synchronously; HermesAdapter's constructor converts failures to INVALID_PARAMS before starting resources. */
+export function validateOptions(options) {
+    for (const [key, value] of Object.entries(options)) {
+        if (value === undefined)
+            continue;
+        if (key.endsWith('Ms') || key.startsWith('max') || key === 'reconnectAttempts')
+            validateNumericOption(key, value);
+    }
+    if (options.toolsets !== undefined && (!Array.isArray(options.toolsets)
+        || options.toolsets.some(value => typeof value !== 'string' || !value.trim() || value.includes('\0'))))
+        throw new Error('Invalid Hermes toolsets');
+    if (options.startup !== undefined && !['start', 'attach'].includes(options.startup))
+        throw new Error('Invalid Hermes startup mode');
+    if (options.profile !== undefined && (!options.profile.trim() || options.profile.includes('\0')))
+        throw new Error('Invalid Hermes profile');
+    if (options.command !== undefined && (typeof options.command !== 'string' || !options.command || options.command.includes('\0')))
+        throw new Error('Invalid Hermes command');
+    if (options.args !== undefined && (!Array.isArray(options.args)
+        || options.args.some(value => typeof value !== 'string' || value.includes('\0'))))
+        throw new Error('Invalid Hermes arguments');
+}
+/** Allow zero only for recovery controls; keep configured millisecond values within the native timer range. */
+function validateNumericOption(key, value) {
+    const minimum = ['reconnectAttempts', 'reconnectDelayMs', 'maxOwnerRecoveriesPerMinute'].includes(key) ? 0 : 1;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`Invalid Hermes option: ${key}`);
+    if (key.endsWith('Ms') && value > 2_147_483_647)
+        throw new Error(`Invalid Hermes option: ${key}`);
+}

package/src/rpc.d.ts

@@ -0,0 +1,94 @@
+import { HarnessSdkError } from '@anureo/sdk';
+import type { GatewayGrant } from "./attach.js";
+import type { HermesAdapterOptions } from "./options.js";
+import { type NativeEvent, type NativeObject } from "./native.js";
+/** Internal gateway-to-client request; probe handlers and HermesInteractions reply or reject using the same id. */
+export interface ServerRequest {
+    id: string | number;
+    method: string;
+    params: NativeObject;
+}
+/**
+ * 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 declare class HermesRpc {
+    private readonly socket;
+    private readonly handlers;
+    private readonly options;
+    /** Install transport listeners and start serial delivery before connect waits for the opening handshake. */
+    private constructor();
+    /**
+     * 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 connect(grant: GatewayGrant, handlers: Handlers, options: HermesAdapterOptions, signal?: AbortSignal): Promise<HermesRpc>;
+    /** Whether the local channel still permits writes. HermesSession.ready uses this to decide when to recover. */
+    get connected(): boolean;
+    /**
+     * 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: string, params?: NativeObject, mutation?: boolean): Promise<unknown>;
+    /**
+     * 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: string | number, result: unknown): Promise<void>;
+    /** Reject an unsupported gateway request; delivery and failure semantics match reply. */
+    reject(id: string | number): Promise<void>;
+    /**
+     * Idempotently close local observation and reject pending RPCs without stopping native execution.
+     * Suppress failure callbacks; callers needing handler completion must also await finished.
+     */
+    dispose(): void;
+    /**
+     * 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.
+     */
+    readonly finished: Promise<void>;
+    private readonly queue;
+    private readonly pending;
+    private nextId;
+    private closed;
+    private disposed;
+    /**
+     * 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.
+     */
+    private read;
+    /** The message listener validates/routes each frame; throwing closes the channel through that listener. */
+    private receive;
+    /**
+     * Settle matching requests without entering the handler queue. Ignore uncorrelated responses
+     * after checking the envelope, so late replies after timeout leave other requests pending.
+     */
+    private receiveResponse;
+    /** Release the pending slot and its deadline before settling a response or reporting a write failure. */
+    private forgetRequest;
+    /** Enforce per-frame and socket backlog limits before a synchronous write; callers decide how to report failures. */
+    private send;
+    /** Share response delivery/error mapping so answers and unsupported-request replies cannot drift. */
+    private respond;
+    /** End observation once. Reject pending RPCs with their mutation uncertainty before ending queued delivery and closing the socket. */
+    private stop;
+}
+/**
+ * Supplied by HermesAdapter.probeRuntime for probes and HermesSession.connect for session delivery.
+ * read awaits event/request callbacks serially; failure is invoked when read fails, unless disposed.
+ * Callbacks must not wait for a user answer: response RPCs bypass this queue, but later events do not.
+ */
+interface Handlers {
+    event(value: NativeEvent): Promise<void>;
+    request(value: ServerRequest): Promise<void>;
+    failure(cause: HarnessSdkError): void;
+}
+export {};