@anureo/adapter-ahp 0.2.0 → 0.3.0

package/src/index.js

@@ -0,0 +1,360 @@
+/** Negotiates a remote AHP peer and routes its validated streams into SDK session sinks. */
+import { HarnessSdkError, } from "@anureo/sdk";
+import { assertDefinition, assertEvent, assertRequest, assertResult, negotiateVersion, publicValue, supportsExtension, } from "@anureo/protocol";
+import { AhpWire, createStdioTransport } from "./wire.js";
+export { AhpWire, createStdioTransport } from "./wire.js";
+export { createWebSocketTransport } from "./websocket.js";
+/** Create an adapter without I/O. Pass it to createClient and dispose the resulting client. */
+export function createAhpAdapter(options) {
+    return new AhpAdapter(options);
+}
+/**
+ * Connect SDK sessions to one AHP peer. Direct users await initialize before opening sessions,
+ * release their backend handles, and then await adapter disposal.
+ */
+export class AhpAdapter {
+    options;
+    /** Configure the connection without opening it. */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Negotiate once and send initialized before resolving. Valid calls share the first attempt,
+     * including rejection. Invalid params or unsupported offered versions throw synchronously.
+     * Disposal, transport and handshake failures reject. The SDK's output wrapper awaits this result
+     * and uses the negotiated output capability before Client stores the capabilities.
+     */
+    initialize(params) {
+        if (this.disposed)
+            return Promise.reject(new HarnessSdkError("RUNTIME_DISPOSED"));
+        assertRequest("initialize", params);
+        negotiateVersion(params.protocolVersions);
+        return this.initialized ??= this.initializeConnection(params);
+    }
+    /**
+     * Open a remote session. OutputSession.open supplies the sink, which may receive notifications
+     * before the open reply. Resolve with the validated backend handle after any fallback metadata
+     * publication. Duplicate IDs, RPC/schema failures, invalid bindings, retired streams and sink
+     * failures reject. Failed setup removes local routing. The SDK wrapper owns backend disposal.
+     */
+    async openSession(params, sink) {
+        if (!this.wire || this.disposed)
+            throw new HarnessSdkError("NOT_INITIALIZED");
+        if (this.sessions.has(params.binding.sessionId))
+            throw new HarnessSdkError("SESSION_ALREADY_OPEN");
+        const wire = this.wire;
+        const record = { sink, lastByStream: new Map(), pendingInteractionIds: new Set() };
+        // The peer may send source events before replying to session/open.
+        this.sessions.set(params.binding.sessionId, record);
+        try {
+            const opened = await wire.request("session/open", params);
+            assertResult("session/open", opened);
+            this.bindOpenedStream(record, params.binding, opened);
+            if (!record.metadataObserved && opened.state?.metadata) {
+                await sink.emit({ type: "session/metadata", payload: opened.state.metadata });
+            }
+            return this.createBackendSession({ wire, params, record, opened });
+        }
+        catch (cause) {
+            this.sessions.delete(params.binding.sessionId);
+            throw cause;
+        }
+    }
+    /**
+     * Close the owned connection and clear routing after successful close. The SDK wrapper attempts
+     * session cleanup first. The first disposal awaits wire cleanup and can reject. Later calls return
+     * immediately. If acquisition is pending, initialize closes the arriving transport before rejecting.
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.wire?.close();
+        this.sessions.clear();
+    }
+    wire;
+    initialized;
+    result;
+    sessions = new Map();
+    retiredStreams = new Set();
+    // Registered while the SDK's responder runs. Its finally block or wire close clears the entry.
+    inFlightInteractionResponses = new Map();
+    disposed = false;
+    /**
+     * initialize shares this attempt. Attach wire callbacks before sending the handshake, then store
+     * capabilities for notification handling before notifying the peer of readiness. Acquisition,
+     * validation and write failures reject the shared attempt. Adapter disposal owns wire cleanup.
+     */
+    async initializeConnection(params) {
+        const selection = this.selectTransport();
+        const transport = "ready" in selection ? selection.ready : await selection.pending;
+        if (this.disposed) {
+            await transport.close();
+            throw new HarnessSdkError("RUNTIME_DISPOSED");
+        }
+        const wire = this.wire = new AhpWire(transport, this.options);
+        wire.onNotification = (method, event) => this.notification(wire, method, event);
+        wire.onClose = cause => this.failConnection(cause);
+        const result = await wire.request("initialize", withMetadataCapability(params));
+        assertResult("initialize", result);
+        negotiateVersion([result.protocolVersion]);
+        this.result = result;
+        await wire.notify("initialized");
+        return result;
+    }
+    /**
+     * Select one transport for initializeConnection. Keep a supplied instance synchronous so the
+     * wire starts immediately. Factory promises and selection errors flow to the initialization attempt.
+     */
+    selectTransport() {
+        if (this.options.transport) {
+            return typeof this.options.transport === "function"
+                ? { pending: this.options.transport() }
+                : { ready: this.options.transport };
+        }
+        if (this.options.url) {
+            if (!this.options.connect)
+                throw new HarnessSdkError("WEBSOCKET_FACTORY_REQUIRED");
+            return { pending: this.options.connect(this.options.url) };
+        }
+        if (!this.options.command)
+            throw new HarnessSdkError("HARNESS_UNAVAILABLE");
+        return { pending: createStdioTransport({ ...this.options, command: this.options.command }) };
+    }
+    /** Commit the open reply's stream after checking its identity. A throw leaves openSession to remove routing. */
+    bindOpenedStream(record, requested, opened) {
+        const { binding } = opened;
+        if (binding.sessionId !== requested.sessionId
+            || binding.adapterId !== requested.adapterId
+            || binding.runtimeConfigId !== requested.runtimeConfigId) {
+            throw new HarnessSdkError("SESSION_BINDING_MISMATCH");
+        }
+        const streamId = opened.streamId;
+        if (this.retiredStreams.has(streamKey(requested.sessionId, streamId))) {
+            throw new HarnessSdkError("SOURCE_STREAM_UNAVAILABLE");
+        }
+        record.streamId = streamId;
+    }
+    /** Build the backend that openSession transfers to OutputSession after setup and metadata publication. */
+    createBackendSession({ wire, params, record, opened }) {
+        const adapter = this;
+        return {
+            binding: opened.binding,
+            capabilities: opened.capabilities,
+            state: opened.state,
+            /** OutputSession.execute supplies validated input and receives the peer result or RPC/schema rejection. */
+            async execute(method, params) {
+                const result = await wire.request(method, params);
+                assertResult(method, result);
+                return result;
+            },
+            /** OutputSession.dispose releases local routing here. The SDK sends session/close separately. */
+            async dispose() {
+                adapter.retire(params.binding.sessionId, record);
+            },
+        };
+    }
+    /** AhpWire awaits this on close. Fail sinks in registration order before rejecting response waiters. */
+    async failConnection(cause) {
+        for (const session of this.sessions.values())
+            await session.sink.fail(cause);
+        for (const response of this.inFlightInteractionResponses.values())
+            response.reject(cause);
+        this.inFlightInteractionResponses.clear();
+    }
+    /**
+     * AhpWire serializes this callback while continuing to read RPC replies. Ignore duplicate
+     * sequences and retired streams, repair gaps before delivery, and forward unknown methods as
+     * notices. Rejection starts wire cleanup, which invokes failConnection.
+     */
+    async notification(wire, method, value) {
+        if (!KNOWN_NOTIFICATIONS.includes(method)) {
+            const raw = publicValue(JSON.parse(JSON.stringify(value ?? null)));
+            for (const session of this.sessions.values()) {
+                await session.sink.emit({
+                    type: "notice",
+                    payload: { severity: "info", code: "UNKNOWN_NOTIFICATION", message: "Unknown AHP notification", raw },
+                });
+            }
+            return;
+        }
+        assertEvent(value);
+        if (value.type !== method)
+            throw new HarnessSdkError("PROTOCOL_ERROR");
+        if (this.retiredStreams.has(streamKey(value.sessionId, value.streamId)))
+            return;
+        const session = this.sessions.get(value.sessionId);
+        if (!session)
+            throw new HarnessSdkError("SOURCE_SESSION_MISMATCH");
+        const last = session.lastByStream.get(value.streamId) ?? 0;
+        if (value.seq <= last)
+            return;
+        if (session.streamId && session.streamId !== value.streamId) {
+            throw new HarnessSdkError("SOURCE_STREAM_UNAVAILABLE");
+        }
+        session.streamId = value.streamId;
+        if (value.seq !== last + 1)
+            await this.replayMissingEvents({ wire, session, next: value, last });
+        await this.deliver(wire, session, value);
+    }
+    /**
+     * Fill the prefix immediately before the live event. notification awaits each repaired event before
+     * delivering the live one. Replayed events can already have reached the sink when a later entry
+     * proves the range invalid or incomplete and rejects the callback.
+     */
+    async replayMissingEvents({ wire, session, next, last }) {
+        if (!this.result || !supportsExtension(this.result.capabilities, "x-anureo/event-replay", "1")) {
+            throw new HarnessSdkError("SOURCE_SEQUENCE_GAP");
+        }
+        const raw = await wire.request("x-anureo/events/read", {
+            sessionId: next.sessionId,
+            streamId: next.streamId,
+            afterSeq: last,
+            throughSeq: next.seq - 1,
+        });
+        if (!raw || typeof raw !== "object" || !("events" in raw) || !Array.isArray(raw.events)) {
+            throw new HarnessSdkError("SOURCE_STREAM_UNAVAILABLE");
+        }
+        for (const event of raw.events) {
+            assertEvent(event);
+            if (event.sessionId !== next.sessionId || event.streamId !== next.streamId) {
+                throw new HarnessSdkError("SOURCE_SEQUENCE_GAP");
+            }
+            const nextExpectedSeq = (session.lastByStream.get(next.streamId) ?? 0) + 1;
+            if (event.seq !== nextExpectedSeq || event.seq >= next.seq) {
+                throw new HarnessSdkError("SOURCE_SEQUENCE_GAP");
+            }
+            await this.deliver(wire, session, event);
+        }
+        if ((session.lastByStream.get(next.streamId) ?? 0) + 1 !== next.seq) {
+            throw new HarnessSdkError("SOURCE_SEQUENCE_GAP");
+        }
+    }
+    /**
+     * Admit one source event from notification or replayMissingEvents. Advance its sequence before
+     * awaiting publication, so replay checks the admitted sequence. Await sink operations except the
+     * interaction answer, whose confirmation can itself arrive on this notification queue.
+     */
+    async deliver(wire, session, event) {
+        session.lastByStream.set(event.streamId, event.seq);
+        const scope = { turnId: event.turnId, itemId: event.itemId };
+        if (event.type === "session/metadata" || (event.type === "extension" && event.payload.name === METADATA_EXTENSION.name)) {
+            const metadata = this.readMetadata(event);
+            if (Object.hasOwn(metadata, "title"))
+                session.metadataObserved = true;
+            await session.sink.emit({ type: "session/metadata", payload: metadata });
+            return;
+        }
+        if (event.type === "interaction/requested") {
+            this.registerInteraction(wire, session, event);
+            return;
+        }
+        if (event.type === "interaction/resolved") {
+            const key = interactionKey(event.sessionId, event.payload.interactionId);
+            const inFlightResponse = this.inFlightInteractionResponses.get(key);
+            if (inFlightResponse) {
+                inFlightResponse.resolve(event.payload);
+                return;
+            }
+            // Only unresolved requests can still be settled by the peer.
+            if (session.pendingInteractionIds.delete(event.payload.interactionId)) {
+                await session.sink.resolveInteraction(event.payload);
+            }
+            return;
+        }
+        if (event.type === "session/state" && event.payload.metadata && Object.hasOwn(event.payload.metadata, "title")) {
+            session.metadataObserved = true;
+        }
+        await session.sink.emit({ type: event.type, payload: event.payload }, scope);
+    }
+    /** Decode either metadata channel for deliver. Reject unnegotiated versions or invalid payloads before publication. */
+    readMetadata(event) {
+        if (!this.result || !supportsExtension(this.result.capabilities, METADATA_EXTENSION.name, METADATA_EXTENSION.version)) {
+            throw new HarnessSdkError("CAPABILITY_UNSUPPORTED");
+        }
+        if (event.type === "extension" && event.payload.version !== METADATA_EXTENSION.version) {
+            throw new HarnessSdkError("CAPABILITY_UNSUPPORTED");
+        }
+        const metadata = event.type === "session/metadata" ? event.payload : event.payload.data;
+        assertDefinition("SessionMetadata", metadata);
+        return metadata;
+    }
+    /**
+     * Register the sink's responder when deliver receives a native interaction. The sink owns local
+     * publication and settlement. Observe rejection without blocking the notification queue.
+     */
+    registerInteraction(wire, session, event) {
+        const request = event.payload;
+        const key = interactionKey(event.sessionId, request.interactionId);
+        session.pendingInteractionIds.add(request.interactionId);
+        void session.sink.requestInteraction(request, (response, reason) => this.respondToInteraction({ wire, session, event, request, key, response, reason })).catch(() => { });
+    }
+    /**
+     * The SDK invokes the responder on answer or cancellation, including rejection at admission.
+     * Await the first RPC reply or matching resolution, validate it, and reject unknown outcomes.
+     * The SDK publishes local settlement. Release both registrations on exit and leave any outstanding
+     * RPC under the wire's own deadline and close handling.
+     */
+    async respondToInteraction({ wire, session, event, request, key, response, reason }) {
+        let resolve;
+        let reject;
+        const confirmation = new Promise((yes, no) => { resolve = yes; reject = no; });
+        this.inFlightInteractionResponses.set(key, { resolve, reject });
+        try {
+            const method = response ? "interaction/respond" : "interaction/cancel";
+            const call = wire.request(method, {
+                requestId: `ahp:${event.streamId}:${event.seq}`,
+                sessionId: event.sessionId,
+                interactionId: request.interactionId,
+                ...(response ? { response } : { reason }),
+            });
+            const result = await Promise.race([call, confirmation]);
+            assertResult(method, result);
+            if (result.outcome === "unknown")
+                throw new HarnessSdkError("RESULT_UNKNOWN", "RESULT_UNKNOWN", false, true);
+        }
+        finally {
+            this.inFlightInteractionResponses.delete(key);
+            session.pendingInteractionIds.delete(request.interactionId);
+        }
+    }
+    /** Backend disposal removes its own registration and remembers up to 128 streams to ignore late events. */
+    retire(sessionId, record) {
+        if (this.sessions.get(sessionId) !== record)
+            return;
+        this.sessions.delete(sessionId);
+        if (!record.streamId)
+            return;
+        this.retiredStreams.add(streamKey(sessionId, record.streamId));
+        if (this.retiredStreams.size > 128) {
+            const oldest = this.retiredStreams.values().next();
+            if (!oldest.done)
+                this.retiredStreams.delete(oldest.value);
+        }
+    }
+}
+const METADATA_EXTENSION = { name: "x-anureo/session-metadata", version: "1" };
+const KNOWN_NOTIFICATIONS = [
+    "submission/bound", "submission/status", "session/metadata", "session/state", "turn/started",
+    "turn/completed", "item/started", "item/delta", "item/completed", "usage/updated",
+    "interaction/requested", "interaction/resolved", "notice", "extension",
+];
+/** Replace offers for this extension so initializeConnection always advertises the version it can decode. */
+function withMetadataCapability(params) {
+    const clientCapabilities = {
+        ...params.clientCapabilities,
+        extensions: [
+            ...(params.clientCapabilities?.extensions ?? []).filter(e => e.name !== METADATA_EXTENSION.name),
+            METADATA_EXTENSION,
+        ],
+    };
+    return { ...params, clientCapabilities };
+}
+/** Preserve tuple boundaries even when either peer-supplied identifier contains a separator. */
+function streamKey(sessionId, streamId) {
+    return JSON.stringify([sessionId, streamId]);
+}
+/** Correlate the response callback and remote resolution using the same session/interaction key. */
+function interactionKey(sessionId, interactionId) {
+    return `${sessionId}:${interactionId}`;
+}

package/src/websocket.d.ts

@@ -0,0 +1,23 @@
+import type { AhpTransport } from "./wire.js";
+/**
+ * Open a text-frame transport for AhpAdapterOptions.connect or direct AhpWire use. Resolve once
+ * the socket is open, before AHP negotiation. The owner must close the returned transport.
+ * Accept wss: or loopback ws: and reject parsed credentials or nonempty query/fragment components.
+ * Address, construction and queue setup failures reject setup. An error or close before open
+ * rejects with RPC_CONNECTION_FAILED. At the deadline the socket is closed before reporting
+ * RPC_TIMEOUT, so a synchronous close event may report RPC_CONNECTION_FAILED first.
+ * Native error and close events end reads. Non-text or rejected frames also initiate socket close.
+ * Buffer up to 2048 incoming frames and drain buffered frames before reporting read failure.
+ * Send resolves after socket.send accepts data. Close resolves after initiating native closure.
+ * A native exception during either operation rejects that operation.
+ */
+export declare function createWebSocketTransport(url: string, options?: {
+    /** Construct a socket from the original validated URL. Omission uses the global WebSocket or rejects if unavailable. */
+    factory?: (url: string) => WebSocket;
+    /** Socket open timeout in milliseconds. Defaults to 30,000. */
+    timeoutMs?: number;
+    /** Incoming UTF-8 frame budget. Defaults to 8 MiB and must be a positive safe integer. */
+    maxFrameBytes?: number;
+    /** Incoming byte budget and outgoing bufferedAmount threshold. Defaults to 16 MiB and must be a positive safe integer. */
+    maxBufferedBytes?: number;
+}): Promise<AhpTransport>;

package/src/websocket.js

@@ -0,0 +1,126 @@
+/** Owns WebSocket address policy, connection setup and bounded incoming text frames. */
+import { BoundedEventQueue, HarnessSdkError } from "@anureo/sdk";
+/**
+ * Open a text-frame transport for AhpAdapterOptions.connect or direct AhpWire use. Resolve once
+ * the socket is open, before AHP negotiation. The owner must close the returned transport.
+ * Accept wss: or loopback ws: and reject parsed credentials or nonempty query/fragment components.
+ * Address, construction and queue setup failures reject setup. An error or close before open
+ * rejects with RPC_CONNECTION_FAILED. At the deadline the socket is closed before reporting
+ * RPC_TIMEOUT, so a synchronous close event may report RPC_CONNECTION_FAILED first.
+ * Native error and close events end reads. Non-text or rejected frames also initiate socket close.
+ * Buffer up to 2048 incoming frames and drain buffered frames before reporting read failure.
+ * Send resolves after socket.send accepts data. Close resolves after initiating native closure.
+ * A native exception during either operation rejects that operation.
+ */
+export async function createWebSocketTransport(url, options = {}) {
+    validateWebSocketAddress(url);
+    if (!options.factory && typeof WebSocket === "undefined")
+        throw new HarnessSdkError("WEBSOCKET_FACTORY_REQUIRED");
+    const socket = options.factory ? options.factory(url) : new WebSocket(url);
+    const transport = createSocketTransport(socket, options);
+    await waitForConnection(socket, options.timeoutMs ?? 30_000);
+    return transport;
+}
+const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+/**
+ * Check address policy before the factory receives the URL. Propagate URL parse failures and
+ * throw INVALID_PARAMS for unsupported protocols, restricted URL components or remote plaintext.
+ */
+function validateWebSocketAddress(url) {
+    const address = new URL(url);
+    const isSupportedProtocol = ["ws:", "wss:"].includes(address.protocol);
+    const hasForbiddenAddressInfo = Boolean(address.username || address.password || address.search || address.hash);
+    const isPlaintextRemoteHost = address.protocol === "ws:"
+        && !["127.0.0.1", "localhost", "[::1]"].includes(address.hostname);
+    if (!isSupportedProtocol || hasForbiddenAddressInfo || isPlaintextRemoteHost) {
+        throw new HarnessSdkError("INVALID_PARAMS", "Invalid AHP WebSocket address");
+    }
+}
+/**
+ * Set up framed reads and local close state before createWebSocketTransport waits for open,
+ * so early frames and failures are retained. Invalid queue budgets throw during construction.
+ */
+function createSocketTransport(socket, options) {
+    const queue = new BoundedEventQueue({
+        maxFrameBytes: options.maxFrameBytes,
+        maxBytes: options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES,
+        maxEvents: 2048,
+    }, frame => new TextEncoder().encode(frame).byteLength);
+    let closed = false;
+    /** Message events admit text frames. Failure ends the queue with the cause before native close can fire. */
+    const receiveFrame = (event) => {
+        try {
+            if (typeof event.data !== "string")
+                throw new HarnessSdkError("PROTOCOL_ERROR");
+            queue.push(event.data);
+        }
+        catch (cause) {
+            queue.end(cause);
+            socket.close();
+        }
+    };
+    /** Native errors and closes fail reads after buffered frames drain. The owner still handles socket release. */
+    const failReads = () => {
+        queue.end(new HarnessSdkError("RPC_CONNECTION_CLOSED", "RPC_CONNECTION_CLOSED", false, true));
+    };
+    socket.addEventListener("message", receiveFrame);
+    socket.addEventListener("close", () => {
+        closed = true;
+        failReads();
+    });
+    socket.addEventListener("error", failReads);
+    return {
+        messages: queue,
+        /** Reject unless open or if bufferedAmount exceeds the threshold before sending. Native send failures propagate. */
+        async send(message) {
+            if (closed || socket.readyState !== 1) {
+                throw new HarnessSdkError("RPC_CONNECTION_CLOSED", "RPC_CONNECTION_CLOSED", false, true);
+            }
+            if (socket.bufferedAmount > (options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES)) {
+                throw new HarnessSdkError("BACKPRESSURE_EXCEEDED");
+            }
+            socket.send(message);
+        },
+        /** Mark closed before invoking native close to prevent duplicate close calls. End reads after native close returns. */
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            socket.close();
+            queue.end();
+        },
+    };
+}
+/**
+ * Await socket readiness for createWebSocketTransport, accepting an already-open factory socket.
+ * Open/error/close settle setup and remove the temporary listeners. The timer initiates close
+ * before rejecting, preserving native error/close ordering.
+ */
+function waitForConnection(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            socket.close();
+            reject(new HarnessSdkError("RPC_TIMEOUT"));
+        }, timeoutMs);
+        /** Detach setup callbacks and clear the deadline when a socket event settles setup. */
+        const removeHandshakeListeners = () => {
+            clearTimeout(timeout);
+            socket.removeEventListener("open", onOpen);
+            socket.removeEventListener("error", onConnectionFailure);
+            socket.removeEventListener("close", onConnectionFailure);
+        };
+        const onOpen = () => {
+            removeHandshakeListeners();
+            resolve();
+        };
+        const onConnectionFailure = () => {
+            removeHandshakeListeners();
+            reject(new HarnessSdkError("RPC_CONNECTION_FAILED"));
+        };
+        socket.addEventListener("open", onOpen);
+        socket.addEventListener("error", onConnectionFailure);
+        socket.addEventListener("close", onConnectionFailure);
+        if (socket.readyState === 1)
+            onOpen();
+    });
+}

package/src/wire.d.ts

@@ -0,0 +1,119 @@
+import { type HarnessProcess, type HarnessProcessOptions } from "@anureo/sdk/process";
+/**
+ * Supply framed text I/O to AhpWire or through AhpAdapterOptions.transport/connect.
+ * Ownership transfers to the wire or adapter. Implementations report source failure by
+ * rejecting iteration. Direct wire users await AhpWire.close to release the connection.
+ */
+export interface AhpTransport {
+    /** Yield one complete JSON-RPC text frame per value. AhpWire claims the reader immediately. */
+    messages: AsyncIterable<string>;
+    /** Submit one frame and resolve when accepted locally. Reject write or admission failures; sends can overlap. */
+    send: (message: string) => Promise<void>;
+    /** Release the connection and unblock a waiting reader. Report local cleanup failures by rejecting. */
+    close: () => Promise<void>;
+}
+/** Configure AhpWire directly or through the fields inherited by AhpAdapterOptions. */
+export interface WireOptions {
+    /** Per-request reply deadline in milliseconds, starting before send; defaults to 30,000. */
+    timeoutMs?: number;
+    /** Maximum UTF-8 bytes per incoming frame or outgoing request. Defaults to 8 MiB. */
+    maxFrameBytes?: number;
+    /** Maximum requests awaiting settlement, including during send. Defaults to 256. */
+    maxPending?: number;
+    /** Maximum queued and running notification callbacks; defaults to 2048. */
+    maxNotifications?: number;
+    /**
+     * Called once at cleanup with the first cause's SDK error code, or PROTOCOL_ERROR for other
+     * causes. Throws are ignored.
+     */
+    diagnostic?: (code: string) => void;
+}
+/**
+ * Exchange JSON-RPC requests and serialized notifications over one owned transport. AhpAdapter
+ * uses this for its handshake, session operations and replay, and validates the returned payloads.
+ * Direct consumers likewise own payload validation and must await close to observe cleanup failure.
+ */
+export declare class AhpWire {
+    private readonly transport;
+    private readonly options;
+    /** Take ownership of the transport and start reading immediately. Install callbacks before sending requests. */
+    constructor(transport: AhpTransport, options?: WireOptions);
+    /**
+     * Receives notifications serially without blocking reply reads. AhpAdapter.initializeConnection
+     * registers its notification router here so replay can await RPC replies. A throw or rejection
+     * starts cleanup. The queue looks up the current callback at delivery time and keeps processing
+     * frames already queued when close starts.
+     */
+    onNotification?: (method: string, params: unknown) => Promise<void> | void;
+    /**
+     * Invoked once with the first close cause, concurrently with transport cleanup.
+     * AhpAdapter.initializeConnection registers failConnection to fail session sinks and interaction
+     * waiters. A throw or rejection becomes a resource-release failure reported by close.
+     * The callback must return independently of close, which awaits its completion.
+     */
+    onClose?: (cause: unknown) => Promise<void> | void;
+    /**
+     * Send a request and resolve with its correlated result. Callers validate the result schema.
+     * Serialization errors throw synchronously. Remote errors, malformed replies, admission limits,
+     * timeouts and connection loss reject the promise. The reply deadline includes sending. Timeouts
+     * and asynchronous send failures reject with outcomeUnknown and leave the wire open. A synchronous
+     * transport send exception rejects as supplied and leaves correlation until reply, timeout or close.
+     * Callers own retry decisions. Use close to stop waiting for outstanding replies.
+     */
+    request(method: string, params: unknown): Promise<unknown>;
+    /**
+     * Send a notification directly through transport.send, which controls admission and completion
+     * and receives the frame regardless of the wire's request and frame limits.
+     * Omitted or undefined params leave the field out. Serialization can throw synchronously and
+     * transport failures propagate as supplied.
+     * AhpAdapter.initializeConnection awaits this for initialized before reporting readiness.
+     */
+    notify(method: string, params?: unknown): Promise<void>;
+    /**
+     * Stop admitting requests and reject outstanding ones with RPC_CONNECTION_CLOSED immediately.
+     * Await onClose and transport.close concurrently. Repeated calls share the same promise, including
+     * after background failure. It settles when both release operations finish and rejects with
+     * RESOURCE_RELEASE_FAILED if either fails. The reader and notification queue run independently.
+     * AhpAdapter.dispose awaits this after the SDK has released its session handles.
+     */
+    close(): Promise<void>;
+    private nextId;
+    private readonly pending;
+    private closing;
+    private closePromise?;
+    private notificationTail;
+    private queuedNotificationCount;
+    /**
+     * Register correlation and its deadline before dispatch so a fast reply can settle the request.
+     * Asynchronous send rejection retires any still-pending entry and reports an unknown outcome.
+     */
+    private sendRequest;
+    /** Read until EOF or failure and initiate cleanup unless it has already started. */
+    private read;
+    /** Return the method-not-found write for read to await. Correlation and notification admission run inline. */
+    private dispatchMessage;
+    /** Consume matching correlation once. A malformed reply rejects that caller with PROTOCOL_ERROR. */
+    private settleResponse;
+    /** Remove live correlation and clear its deadline so a late response or send failure cannot settle it again. */
+    private takePending;
+    /** Serialize callback delivery in frame order. Backlog overflow throws to read and starts cleanup. */
+    private enqueueNotification;
+    /** Retire pending requests immediately and cache first-cause cleanup before invoking callbacks. */
+    private beginClose;
+    /** Run both releases and report their stable failure codes in RESOURCE_RELEASE_FAILED, without retaining private causes. */
+    private releaseConnection;
+}
+/**
+ * Acquire a process and expose newline-delimited UTF-8 frames as soon as process startup succeeds.
+ * Startup failures reject. Reads accept CRLF, skip empty lines and reject oversized frames or
+ * an unterminated nonblank tail. The transport drains stderr privately. Send appends a newline
+ * and completes with process.write. Close awaits process.dispose and follows its ownership policy.
+ * AhpAdapter.initializeConnection transfers the transport to AhpWire or closes it if disposal
+ * occurred during acquisition. Direct transport users own close, including after EOF.
+ */
+export declare function createStdioTransport(options: HarnessProcessOptions & {
+    /** Acquire a process from the supplied options. The transport reads its output and disposes it on close. */
+    processFactory?: (p: HarnessProcessOptions) => Promise<HarnessProcess>;
+    /** Incoming decoded UTF-8 frame budget, including unfinished lines; defaults to 8 MiB. */
+    maxFrameBytes?: number;
+}): Promise<AhpTransport>;