@grackle-ai/ahp-transport 0.132.0

package/dist/examples/echo-subscriber.js

@@ -0,0 +1,102 @@
+/**
+ * Echo subscriber — minimal end-to-end example that exercises the public
+ * `@grackle-ai/ahp-transport` surface (`JsonRpcSession`, `AhpServerSocket`,
+ * `AhpClientSocket`, `ClientIdStore`) for a realistic workflow:
+ *
+ * - Server hosts a single "echo" session. When a client subscribes to
+ *   `ahp-session:/echo`, the server fires a sequence of `action`
+ *   notifications back to the client.
+ * - Client connects, subscribes (via a `subscribe` JSON-RPC request, even
+ *   though the framing layer doesn't formally route by channel — `MultiHost
+ *   Client` in HR8b will), and collects every received notification.
+ *
+ * This file is not exported from the package barrel. It's referenced from
+ * `examples.integration.test.ts` to confirm the public API composes
+ * without requiring consumers to reach into internals.
+ */
+import { JsonRpcErrorCodes } from "@grackle-ai/ahp";
+import { createServer } from "node:http";
+import { AhpClientSocket } from "../ahp-client-socket.js";
+import { InMemoryClientIdStore } from "../client-id-store.js";
+import { AhpServerSocket, } from "../ahp-server-socket.js";
+const INIT_RESULT = {
+    protocolVersion: "0.1.0",
+    serverSeq: 0,
+    snapshots: [],
+};
+/**
+ * Spawn an echo subscriber: a server that emits `count` `action`
+ * notifications to any client that issues a `subscribe` JSON-RPC request,
+ * paired with a client that connects, subscribes, and returns the
+ * collected actions.
+ *
+ * Returns a `dispose()` that tears everything down.
+ */
+export async function runEchoSubscriber(count) {
+    // ── Server ──────────────────────────────────────────────────────
+    const server = createServer();
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    const subscribers = [];
+    const handleRequest = async (req, conn) => {
+        if (req.method === "subscribe") {
+            // Register this connection as a subscriber and fan out `count`
+            // notifications AFTER the response is on the wire. The afterSend
+            // primitive in the framing layer is exposed via the request handler's
+            // wrapped return; here we use a plain response and a microtask
+            // because the example demonstrates the *consumer* surface.
+            subscribers.push(conn);
+            queueMicrotask(() => {
+                for (let i = 0; i < count; i++) {
+                    conn.session.notify("action", {
+                        channel: "ahp-session:/echo",
+                        serverSeq: i + 1,
+                        action: { type: "echo/tick", payload: { i } },
+                    });
+                }
+            });
+            return {
+                jsonrpc: "2.0",
+                id: req.id,
+                result: { channel: "ahp-session:/echo", snapshot: undefined },
+            };
+        }
+        return {
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: JsonRpcErrorCodes.MethodNotFound, message: `no handler for ${req.method}` },
+        };
+    };
+    const ahp = new AhpServerSocket({
+        server,
+        powerlineToken: "echo-token",
+        onInitialize: (_params) => INIT_RESULT,
+        onRequest: handleRequest,
+    });
+    // ── Client ──────────────────────────────────────────────────────
+    const received = [];
+    const client = new AhpClientSocket({
+        url: `ws://127.0.0.1:${port}/ahp`,
+        powerlineToken: "echo-token",
+        clientIdStore: new InMemoryClientIdStore(),
+        clientIdKey: "echo-example",
+        onNotification: (notif) => {
+            if (notif.method === "action") {
+                received.push(notif.params);
+            }
+        },
+    });
+    await client.open();
+    await client.request("subscribe", {
+        channel: "ahp-session:/echo",
+    });
+    // Give notifications a beat to arrive.
+    await new Promise((r) => setTimeout(r, 50));
+    const dispose = async () => {
+        await client.close();
+        await ahp.close();
+        await new Promise((r) => server.close(() => r()));
+    };
+    return { received, dispose };
+}
+//# sourceMappingURL=echo-subscriber.js.map

package/dist/examples/echo-subscriber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo-subscriber.js","sourceRoot":"","sources":["../../src/examples/echo-subscriber.ts"],"names":[],"mappings":"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"}

package/dist/heartbeat.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Heartbeat state machine. Sends WebSocket-level pings on a fixed interval
+ * and closes the connection when too many pings go un-pong'd in a row.
+ *
+ * Extracted from {@link AhpServerSocket} so the close-on-threshold branch can
+ * be tested deterministically with a stub target (real `ws` clients auto-pong
+ * and make the close path unreachable in integration tests).
+ */
+/** Minimal interface the heartbeat needs from its underlying socket. */
+export interface HeartbeatTarget {
+    /** Send a WebSocket-level PING frame. */
+    ping(): void;
+    /** Close the connection with the given code and reason. */
+    close(code: number, reason: string): void;
+    /** Subscribe to PONG events. The heartbeat only listens for "pong". */
+    on(event: "pong", listener: () => void): void;
+}
+/** Construction options for {@link Heartbeat}. */
+export interface HeartbeatOptions {
+    /** Target socket the heartbeat operates on. */
+    readonly target: HeartbeatTarget;
+    /** Interval between ping ticks in milliseconds. */
+    readonly intervalMs: number;
+    /**
+     * Number of consecutive missed pongs (i.e., ticks where the previous tick's
+     * ping never got a pong before this tick) before closing with 4001.
+     *
+     * - `1` closes on the first real missed pong.
+     * - `2` (default in `AhpServerSocket`) closes on the second.
+     */
+    readonly missedLimit: number;
+    /**
+     * Injectable timer factory for testing. Defaults to global
+     * `setInterval`/`clearInterval`. Tests use `vi.useFakeTimers()` to bypass
+     * real time without needing to inject anything here.
+     */
+    readonly timers?: {
+        setInterval: typeof setInterval;
+        clearInterval: typeof clearInterval;
+    };
+}
+/**
+ * Heartbeat for a single WebSocket-like target. Owns no `WebSocket` itself;
+ * the integration with `ws.WebSocket` happens in {@link AhpServerSocket} via
+ * the {@link HeartbeatTarget} adapter.
+ */
+export declare class Heartbeat {
+    private readonly target;
+    private readonly intervalMs;
+    private readonly missedLimit;
+    private readonly setInterval;
+    private readonly clearInterval;
+    private timer;
+    /** True between a `ping()` and the matching `pong` event. */
+    private pingOutstanding;
+    /** Count of consecutive ticks where the previous tick's ping went un-pong'd. */
+    private missedPongs;
+    /** True once `stop()` has been called; prevents the timer body from running. */
+    private stopped;
+    constructor(opts: HeartbeatOptions);
+    /** Begin pinging on the configured interval. Idempotent. */
+    start(): void;
+    /** Stop pinging. After this, the heartbeat will not fire again. Idempotent. */
+    stop(): void;
+    private onTick;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,IAAI,IAAI,IAAI,CAAC;IACb,2DAA2D;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,uEAAuE;IACvE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/C;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,aAAa,EAAE,OAAO,aAAa,CAAC;KACrC,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IAErD,OAAO,CAAC,KAAK,CAA6B;IAC1C,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAAS;IAChC,gFAAgF;IAChF,OAAO,CAAC,WAAW,CAAK;IACxB,gFAAgF;IAChF,OAAO,CAAC,OAAO,CAAS;gBAEL,IAAI,EAAE,gBAAgB;IAazC,4DAA4D;IACrD,KAAK,IAAI,IAAI;IAOpB,+EAA+E;IACxE,IAAI,IAAI,IAAI;IAQnB,OAAO,CAAC,MAAM;CAuBf"}

package/dist/heartbeat.js

@@ -0,0 +1,79 @@
+/**
+ * Heartbeat state machine. Sends WebSocket-level pings on a fixed interval
+ * and closes the connection when too many pings go un-pong'd in a row.
+ *
+ * Extracted from {@link AhpServerSocket} so the close-on-threshold branch can
+ * be tested deterministically with a stub target (real `ws` clients auto-pong
+ * and make the close path unreachable in integration tests).
+ */
+import { WsCloseCode } from "./error-codes.js";
+/**
+ * Heartbeat for a single WebSocket-like target. Owns no `WebSocket` itself;
+ * the integration with `ws.WebSocket` happens in {@link AhpServerSocket} via
+ * the {@link HeartbeatTarget} adapter.
+ */
+export class Heartbeat {
+    target;
+    intervalMs;
+    missedLimit;
+    setInterval;
+    clearInterval;
+    timer;
+    /** True between a `ping()` and the matching `pong` event. */
+    pingOutstanding = false;
+    /** Count of consecutive ticks where the previous tick's ping went un-pong'd. */
+    missedPongs = 0;
+    /** True once `stop()` has been called; prevents the timer body from running. */
+    stopped = false;
+    constructor(opts) {
+        this.target = opts.target;
+        this.intervalMs = opts.intervalMs;
+        this.missedLimit = opts.missedLimit;
+        this.setInterval = opts.timers?.setInterval ?? setInterval;
+        this.clearInterval = opts.timers?.clearInterval ?? clearInterval;
+        this.target.on("pong", () => {
+            this.pingOutstanding = false;
+            this.missedPongs = 0;
+        });
+    }
+    /** Begin pinging on the configured interval. Idempotent. */
+    start() {
+        if (this.timer !== undefined || this.stopped) {
+            return;
+        }
+        this.timer = this.setInterval(() => this.onTick(), this.intervalMs);
+    }
+    /** Stop pinging. After this, the heartbeat will not fire again. Idempotent. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined) {
+            this.clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    onTick() {
+        if (this.stopped) {
+            return;
+        }
+        // If the prior tick's ping never got a pong before this tick, count it
+        // as a real miss. The initial tick (pingOutstanding=false) skips this
+        // — there's no prior ping to have missed.
+        if (this.pingOutstanding) {
+            this.missedPongs += 1;
+            if (this.missedPongs >= this.missedLimit) {
+                this.stop();
+                this.target.close(WsCloseCode.HeartbeatTimeout, "heartbeat timeout");
+                return;
+            }
+        }
+        try {
+            this.target.ping();
+            this.pingOutstanding = true;
+        }
+        catch {
+            // Target already closing; the AhpServerSocket close handler will tear
+            // down the timer via stop().
+        }
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAqC/C;;;;GAIG;AACH,MAAM,OAAO,SAAS;IACH,MAAM,CAAkB;IACxB,UAAU,CAAS;IACnB,WAAW,CAAS;IACpB,WAAW,CAAqB;IAChC,aAAa,CAAuB;IAE7C,KAAK,CAA6B;IAC1C,6DAA6D;IACrD,eAAe,GAAG,KAAK,CAAC;IAChC,gFAAgF;IACxE,WAAW,GAAG,CAAC,CAAC;IACxB,gFAAgF;IACxE,OAAO,GAAG,KAAK,CAAC;IAExB,YAAmB,IAAsB;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,IAAI,WAAW,CAAC;QAC3D,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,EAAE,aAAa,IAAI,aAAa,CAAC;QAEjE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YAC1B,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;YAC7B,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IACrD,KAAK;QACV,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtE,CAAC;IAED,+EAA+E;IACxE,IAAI;QACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,MAAM;QACZ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,uEAAuE;QACvE,sEAAsE;QACtE,0CAA0C;QAC1C,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;YACtB,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACzC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACZ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,6BAA6B;QAC/B,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@grackle-ai/ahp-transport` — WebSocket + JSON-RPC 2.0 framing primitive
+ * for the Agent Host Protocol (AHP) wire. Provides the low-level transport
+ * layer that {@link MultiHostClient} (HR8b) and the PowerLine AHP host
+ * (HR8d) build on. The package is consumer-agnostic: it ships the framing,
+ * auth handshake, and reconnect semantics; channel-scoped concerns
+ * (per-`(host, channel)` `serverSeq` tracking, subscription replay, the
+ * generation counter for stale-handle invalidation) live one layer up.
+ */
+export { JsonRpcSession } from "./json-rpc-session.js";
+export type { JsonRpcSessionOptions, RequestHandler, RequestHandlerResult, NotificationHandler, } from "./json-rpc-session.js";
+export { AhpServerSocket } from "./ahp-server-socket.js";
+export type { AhpServerSocketOptions, AhpServerConnection } from "./ahp-server-socket.js";
+export { AhpClientSocket } from "./ahp-client-socket.js";
+export type { AhpClientSocketOptions, AhpConnectionState } from "./ahp-client-socket.js";
+export type { ClientIdStore } from "./client-id-store.js";
+export { FileClientIdStore, InMemoryClientIdStore } from "./client-id-store.js";
+export { exponentialBackoff } from "./backoff.js";
+export type { BackoffPolicy, ExponentialBackoffOptions } from "./backoff.js";
+export { TransportError, WsCloseCode } from "./error-codes.js";
+export type { TransportErrorKind } from "./error-codes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@grackle-ai/ahp-transport` — WebSocket + JSON-RPC 2.0 framing primitive
+ * for the Agent Host Protocol (AHP) wire. Provides the low-level transport
+ * layer that {@link MultiHostClient} (HR8b) and the PowerLine AHP host
+ * (HR8d) build on. The package is consumer-agnostic: it ships the framing,
+ * auth handshake, and reconnect semantics; channel-scoped concerns
+ * (per-`(host, channel)` `serverSeq` tracking, subscription replay, the
+ * generation counter for stale-handle invalidation) live one layer up.
+ */
+export { JsonRpcSession } from "./json-rpc-session.js";
+export { AhpServerSocket } from "./ahp-server-socket.js";
+export { AhpClientSocket } from "./ahp-client-socket.js";
+export { FileClientIdStore, InMemoryClientIdStore } from "./client-id-store.js";
+export { exponentialBackoff } from "./backoff.js";
+export { TransportError, WsCloseCode } from "./error-codes.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/json-rpc-session.d.ts

@@ -0,0 +1,106 @@
+/**
+ * JSON-RPC 2.0 framing engine over a single WebSocket. Owns:
+ *   - outbound request/response correlation by numeric id
+ *   - inbound dispatch to `onRequest` / `onNotification`
+ *   - per-request timeouts
+ *   - close-rejects-all-pending-with-ConnectionLost
+ *
+ * Channels (AHP routing) are deliberately NOT understood here — that's
+ * `MultiHostClient`'s job. This class only does framing.
+ */
+import type { AhpNotification, AhpRequest, AhpResponse, CommandMap } from "@grackle-ai/ahp";
+import type { WebSocket } from "ws";
+/**
+ * Result returned by a {@link RequestHandler}. Either a bare `AhpResponse`
+ * (from `@grackle-ai/ahp`, the common case), or a wrapped result that
+ * includes an `afterSend` callback fired AFTER the response frame has been
+ * flushed to the wire. The wrapped form is the deterministic ordering
+ * primitive: use it whenever a side effect (e.g., close the session, emit
+ * a notification) must follow the response on the wire rather than precede it.
+ */
+export type RequestHandlerResult = AhpResponse | {
+    readonly response: AhpResponse;
+    readonly afterSend: () => void;
+};
+/** Handler for inbound peer-initiated requests. */
+export type RequestHandler = (req: AhpRequest) => Promise<RequestHandlerResult>;
+/** Handler for inbound peer-initiated notifications. */
+export type NotificationHandler = (notif: AhpNotification) => void;
+/** Construction options for {@link JsonRpcSession}. */
+export interface JsonRpcSessionOptions {
+    /** An already-OPEN WebSocket. The session takes ownership of close/error events. */
+    readonly socket: WebSocket;
+    /** Called when the peer sends a JSON-RPC request. Omit to reject all inbound requests. */
+    readonly onRequest?: RequestHandler;
+    /** Called when the peer sends a JSON-RPC notification. Omit to drop silently. */
+    readonly onNotification?: NotificationHandler;
+    /** Called once when the socket closes; pending requests have already been rejected. */
+    readonly onClose?: (code: number, reason: string) => void;
+    /** If set, pending requests time out after this many milliseconds. */
+    readonly requestTimeoutMs?: number;
+}
+/**
+ * Bidirectional JSON-RPC session over one WebSocket.
+ *
+ * @example Wrap an already-OPEN ws connection and exchange a typed request:
+ * ```ts
+ * import { WebSocket } from "ws";
+ * const socket = new WebSocket(url);
+ * await new Promise((r) => socket.once("open", r));
+ *
+ * const session = new JsonRpcSession({
+ *   socket,
+ *   onNotification: (n) => console.log("inbound:", n.method),
+ * });
+ * const result = await session.request("ping", { channel: "ahp-root://" });
+ * ```
+ *
+ * @example Send a response that closes the session after the frame flushes:
+ * ```ts
+ * const session = new JsonRpcSession({
+ *   socket,
+ *   onRequest: async (req) => ({
+ *     response: { jsonrpc: "2.0", id: req.id, error: { code: -32600, message: "bad" } },
+ *     afterSend: () => session.close(1000, "bye"),
+ *   }),
+ * });
+ * ```
+ */
+export declare class JsonRpcSession {
+    private readonly socket;
+    private readonly onRequest;
+    private readonly onNotification;
+    private readonly onClose;
+    private readonly requestTimeoutMs;
+    private nextRequestId;
+    private readonly pendingRequests;
+    private closed;
+    constructor(opts: JsonRpcSessionOptions);
+    /** Sends a request and resolves with the result (or rejects with the error). */
+    request<M extends keyof CommandMap>(method: M, params: CommandMap[M]["params"]): Promise<CommandMap[M]["result"]>;
+    /** Sends a notification (fire-and-forget). Silently drops if already closed. */
+    notify(method: string, params: unknown): void;
+    /** Closes the underlying socket. Idempotent. */
+    close(code?: number, reason?: string): void;
+    /** True between construction and the socket's "close" event firing. */
+    get isOpen(): boolean;
+    private readonly handleMessage;
+    private resolvePending;
+    private rejectPending;
+    private handleInboundRequest;
+    /**
+     * Sends `frame` and invokes `after` once the data has been flushed to the
+     * OS socket buffer. Use this when a side effect (e.g., closing the session)
+     * MUST follow the frame on the wire.
+     *
+     * `after` runs even if `socket.send` errors — the typical close-after-error
+     * caller wants the close to proceed regardless.
+     */
+    sendAndThen(frame: unknown, after: () => void): void;
+    private handleInboundNotification;
+    private writeError;
+    private tryWriteParseError;
+    private readonly handleClose;
+    private readonly handleError;
+}
+//# sourceMappingURL=json-rpc-session.d.ts.map

package/dist/json-rpc-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-rpc-session.d.ts","sourceRoot":"","sources":["../src/json-rpc-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5F,OAAO,KAAK,EAAW,SAAS,EAAE,MAAM,IAAI,CAAC;AAI7C;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX;IAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAEvE,mDAAmD;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEhF,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEnE,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IAC9C,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuD;IAC/E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IAEtD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,MAAM,CAAS;gBAEJ,IAAI,EAAE,qBAAqB;IAY9C,gFAAgF;IACzE,OAAO,CAAC,CAAC,SAAS,MAAM,UAAU,EACvC,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAC9B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IA6CnC,gFAAgF;IACzE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAWpD,gDAAgD;IACzC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAOlD,uEAAuE;IACvE,IAAW,MAAM,IAAI,OAAO,CAE3B;IAID,OAAO,CAAC,QAAQ,CAAC,aAAa,CAiD5B;IAEF,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,aAAa;YAYP,oBAAoB;IA0BlC;;;;;;;OAOG;IACI,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI;IAqB3D,OAAO,CAAC,yBAAyB;IAWjC,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAmB1B;IAEF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAI1B;CACH"}