@grackle-ai/ahp-transport 0.132.0

package/dist/ahp-server-socket.js

@@ -0,0 +1,260 @@
+/**
+ * Server-side AHP transport. Mounts on an existing HTTP/HTTP2 server,
+ * authenticates the upgrade request via `Authorization: Bearer <token>`,
+ * runs the AHP `initialize` handshake, then surfaces an
+ * {@link AhpServerConnection} (with a ready-to-use {@link JsonRpcSession})
+ * to the application.
+ *
+ * Heartbeat: WebSocket-level pings every 30s; 2 consecutive missed pongs
+ * close with code 4001.
+ */
+import { JsonRpcErrorCodes } from "@grackle-ai/ahp";
+import { timingSafeEqual } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { WsCloseCode } from "./error-codes.js";
+import { Heartbeat } from "./heartbeat.js";
+import { JsonRpcSession } from "./json-rpc-session.js";
+/** Default WS path mounted on the host HTTP server. */
+const DEFAULT_PATH = "/ahp";
+/** Default ping interval in milliseconds. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+/** Default number of consecutive missed pongs before close-4001. */
+const DEFAULT_HEARTBEAT_MISSED_LIMIT = 2;
+/**
+ * AHP-spec JSON-RPC/WebSocket server. Mounts on an existing
+ * `http.Server`/`http2.SecureServer` and surfaces fully-initialized
+ * `AhpServerConnection`s to the application.
+ *
+ * @example Mount on an HTTP server and accept one client:
+ * ```ts
+ * import { createServer } from "node:http";
+ * const server = createServer();
+ * server.listen(7433, "127.0.0.1");
+ *
+ * const ahp = new AhpServerSocket({
+ *   server,
+ *   powerlineToken: process.env.GRACKLE_POWERLINE_TOKEN ?? "",
+ *   onInitialize: (params) => ({
+ *     protocolVersion: "0.1.0",
+ *     serverSeq: 0,
+ *     snapshots: [],
+ *   }),
+ *   onConnection: (conn) => {
+ *     console.log("client connected:", conn.clientId);
+ *     conn.session.notify("action", { channel: "ahp-session:/x", serverSeq: 1, action: {...} });
+ *   },
+ *   onRequest: async (req, conn) => {
+ *     // typed dispatch on req.method
+ *     return { jsonrpc: "2.0", id: req.id, result: null };
+ *   },
+ * });
+ * ```
+ */
+export class AhpServerSocket {
+    server;
+    powerlineToken;
+    path;
+    onInitialize;
+    onRequest;
+    onNotification;
+    onConnection;
+    onDisconnect;
+    heartbeatIntervalMs;
+    heartbeatMissedLimit;
+    wss;
+    connections = new Set();
+    upgradeListener;
+    closed = false;
+    constructor(opts) {
+        this.server = opts.server;
+        this.powerlineToken = opts.powerlineToken;
+        this.path = opts.path ?? DEFAULT_PATH;
+        this.onInitialize = opts.onInitialize;
+        this.onRequest = opts.onRequest;
+        this.onNotification = opts.onNotification;
+        this.onConnection = opts.onConnection;
+        this.onDisconnect = opts.onDisconnect;
+        this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.heartbeatMissedLimit = opts.heartbeatMissedLimit ?? DEFAULT_HEARTBEAT_MISSED_LIMIT;
+        this.wss = new WebSocketServer({ noServer: true });
+        this.upgradeListener = (req, socket, head) => this.handleUpgrade(req, socket, head);
+        this.server.on("upgrade", this.upgradeListener);
+    }
+    /** Stops accepting new connections and closes all existing sessions. */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.server.off("upgrade", this.upgradeListener);
+        for (const conn of this.connections) {
+            conn.heartbeat.stop();
+            conn.session.close(WsCloseCode.Normal, "server shutting down");
+        }
+        this.connections.clear();
+        await new Promise((resolve) => this.wss.close(() => resolve()));
+    }
+    // ─── Upgrade + auth ────────────────────────────────────────────────
+    handleUpgrade(req, socket, head) {
+        // Only handle our path; let other listeners see other paths.
+        const requestPath = (req.url ?? "/").split("?")[0];
+        if (requestPath !== this.path) {
+            return;
+        }
+        if (!this.authorizeUpgrade(req)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => this.attachSocket(ws, req));
+    }
+    authorizeUpgrade(req) {
+        if (this.powerlineToken === "") {
+            return true;
+        }
+        const header = (req.headers["authorization"] ?? "").toString();
+        const bearerMatch = /^Bearer\s+(\S+)$/i.exec(header);
+        if (bearerMatch === null) {
+            // Reject anything that isn't an `Authorization: Bearer <token>` header
+            // — including a raw token with no scheme prefix.
+            return false;
+        }
+        const supplied = bearerMatch[1] ?? "";
+        const a = Buffer.from(supplied);
+        const b = Buffer.from(this.powerlineToken);
+        if (a.length !== b.length) {
+            return false;
+        }
+        return timingSafeEqual(a, b);
+    }
+    // ─── Per-connection lifecycle ──────────────────────────────────────
+    attachSocket(ws, req) {
+        const state = {
+            socket: ws,
+            session: undefined,
+            connection: undefined,
+            heartbeat: undefined,
+        };
+        state.session = new JsonRpcSession({
+            socket: ws,
+            onRequest: (innerReq) => this.handleRequest(innerReq, state, req),
+            onNotification: (notif) => this.handleNotification(notif, state),
+            onClose: (code, reason) => this.handleSocketClose(state, code, reason),
+        });
+        state.heartbeat = new Heartbeat({
+            target: {
+                ping: () => ws.ping(),
+                close: (code, reason) => state.session.close(code, reason),
+                on: (event, listener) => {
+                    ws.on(event, listener);
+                },
+            },
+            intervalMs: this.heartbeatIntervalMs,
+            missedLimit: this.heartbeatMissedLimit,
+        });
+        this.connections.add(state);
+        state.heartbeat.start();
+    }
+    async handleRequest(req, state, httpReq) {
+        if (req.method === "initialize") {
+            if (state.connection !== undefined) {
+                return {
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    error: {
+                        code: JsonRpcErrorCodes.InvalidRequest,
+                        message: "session already initialized",
+                    },
+                };
+            }
+            try {
+                const params = req.params;
+                const result = await this.onInitialize(params);
+                const connection = {
+                    clientId: params.clientId,
+                    initializeParams: params,
+                    session: state.session,
+                    remoteAddress: httpReq.socket.remoteAddress,
+                };
+                state.connection = connection;
+                // Surface the connection AFTER the initialize response has been
+                // flushed to the wire. `afterSend` runs in JsonRpcSession's
+                // `ws.send(data, callback)` completion path — deterministic ordering,
+                // no event-loop assumptions.
+                return {
+                    response: { jsonrpc: "2.0", id: req.id, result },
+                    afterSend: () => this.onConnection?.(connection),
+                };
+            }
+            catch (err) {
+                // onInitialize failure: send the error response, then close the
+                // session. The handshake boundary requires the peer can't retry
+                // initialize on the same socket after a handshake-layer failure.
+                return {
+                    response: {
+                        jsonrpc: "2.0",
+                        id: req.id,
+                        error: {
+                            code: JsonRpcErrorCodes.InternalError,
+                            message: err.message || "onInitialize threw",
+                        },
+                    },
+                    afterSend: () => state.session.close(WsCloseCode.Normal, "initialize failed"),
+                };
+            }
+        }
+        const connection = state.connection;
+        if (connection === undefined) {
+            // Enforce the handshake boundary: the first inbound JSON-RPC must be
+            // `initialize`. Close the session after the error response is flushed.
+            return {
+                response: {
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    error: {
+                        code: JsonRpcErrorCodes.InvalidRequest,
+                        message: "first request must be initialize",
+                    },
+                },
+                afterSend: () => state.session.close(WsCloseCode.Normal, "initialize required first"),
+            };
+        }
+        if (this.onRequest === undefined) {
+            return {
+                jsonrpc: "2.0",
+                id: req.id,
+                error: {
+                    code: JsonRpcErrorCodes.MethodNotFound,
+                    message: `no handler for ${req.method}`,
+                },
+            };
+        }
+        return this.onRequest(req, connection);
+    }
+    handleNotification(notif, state) {
+        if (state.connection === undefined) {
+            // Pre-initialize notification violates the handshake contract.
+            // Notifications have no response to flush, so we can close
+            // immediately — no ordering concern.
+            state.session.close(WsCloseCode.Normal, "initialize required first");
+            return;
+        }
+        if (this.onNotification === undefined) {
+            return;
+        }
+        try {
+            this.onNotification(notif, state.connection);
+        }
+        catch {
+            // Handler errors are swallowed to keep the session alive.
+        }
+    }
+    handleSocketClose(state, code, reason) {
+        state.heartbeat.stop();
+        this.connections.delete(state);
+        if (state.connection !== undefined) {
+            this.onDisconnect?.(state.connection.clientId, code, reason);
+        }
+    }
+}
+//# sourceMappingURL=ahp-server-socket.js.map

package/dist/ahp-server-socket.js.map

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

package/dist/backoff.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reconnect backoff policy used by {@link AhpClientSocket}. Pure logic — no
+ * timers; callers do the actual sleeping.
+ */
+/** A stateful policy that yields successive delays. */
+export interface BackoffPolicy {
+    /** Returns the next delay (in milliseconds) to wait before reconnecting. */
+    next(): number;
+    /** Resets the policy back to the initial delay (called after a successful reconnect). */
+    reset(): void;
+}
+/** Options for {@link exponentialBackoff}. */
+export interface ExponentialBackoffOptions {
+    /** First delay returned by `next()`. Default 250ms. */
+    readonly initialMs?: number;
+    /** Cap on the delay. Default 30_000ms. */
+    readonly maxMs?: number;
+    /** Symmetric multiplicative jitter, e.g. 0.25 = ±25%. Default 0.25. */
+    readonly jitter?: number;
+    /** Random source, injectable for tests. Defaults to `Math.random`. */
+    readonly random?: () => number;
+}
+/**
+ * Returns a {@link BackoffPolicy} that doubles each call up to `maxMs`,
+ * with symmetric jitter applied to each yielded value.
+ */
+export declare function exponentialBackoff(options?: ExponentialBackoffOptions): BackoffPolicy;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,IAAI,MAAM,CAAC;IACf,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACf;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,aAAa,CAoBzF"}

package/dist/backoff.js

@@ -0,0 +1,31 @@
+/**
+ * Reconnect backoff policy used by {@link AhpClientSocket}. Pure logic — no
+ * timers; callers do the actual sleeping.
+ */
+const DEFAULT_INITIAL_MS = 250;
+const DEFAULT_MAX_MS = 30_000;
+const DEFAULT_JITTER = 0.25;
+/**
+ * Returns a {@link BackoffPolicy} that doubles each call up to `maxMs`,
+ * with symmetric jitter applied to each yielded value.
+ */
+export function exponentialBackoff(options = {}) {
+    const initialMs = options.initialMs ?? DEFAULT_INITIAL_MS;
+    const maxMs = options.maxMs ?? DEFAULT_MAX_MS;
+    const jitter = options.jitter ?? DEFAULT_JITTER;
+    const random = options.random ?? Math.random;
+    let current = initialMs;
+    return {
+        next() {
+            const base = Math.min(current, maxMs);
+            current = Math.min(current * 2, maxMs);
+            // Symmetric jitter: scale by [1-jitter, 1+jitter].
+            const jitterFactor = 1 + (random() * 2 - 1) * jitter;
+            return Math.max(0, Math.round(base * jitterFactor));
+        },
+        reset() {
+            current = initialMs;
+        },
+    };
+}
+//# sourceMappingURL=backoff.js.map

package/dist/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,cAAc,GAAG,IAAI,CAAC;AAsB5B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAqC,EAAE;IACxE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAE7C,IAAI,OAAO,GAAG,SAAS,CAAC;IAExB,OAAO;QACL,IAAI;YACF,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACtC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YACvC,mDAAmD;YACnD,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;YACrD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC;QACtD,CAAC;QACD,KAAK;YACH,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/client-id-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Persistence for the AHP `clientId`. Per the AHP spec, the client owns
+ * its identifier — `InitializeParams.clientId` is supplied by the client
+ * on every connect. {@link AhpClientSocket} mints a fresh UUID via
+ * `randomUUID()` the first time it sees an empty store, persists it here,
+ * and replays the same id on every subsequent connect so the host can
+ * resume in-flight subscriptions.
+ *
+ * Keyed by an opaque string so a single store can serve multiple
+ * connections (e.g., one `ClientIdStore` per `MultiHostClient` keyed
+ * by host id).
+ */
+/** Persistent storage for AHP client identifiers. */
+export interface ClientIdStore {
+    /** Returns the stored client id for `key`, or `undefined` if none exists. */
+    load(key: string): Promise<string | undefined>;
+    /** Persists `clientId` under `key`, replacing any prior value. */
+    save(key: string, clientId: string): Promise<void>;
+}
+/**
+ * In-memory store. Suitable for tests and for the lifetime of a single
+ * process where persistence across restarts is not required.
+ */
+export declare class InMemoryClientIdStore implements ClientIdStore {
+    private readonly entries;
+    load(key: string): Promise<string | undefined>;
+    save(key: string, clientId: string): Promise<void>;
+}
+/**
+ * On-disk store using one file per key under `rootDir`. Writes are atomic
+ * via a `.tmp`-then-`rename` pattern, so a crash mid-write can never corrupt
+ * a previously-saved value.
+ */
+export declare class FileClientIdStore implements ClientIdStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    load(key: string): Promise<string | undefined>;
+    save(key: string, clientId: string): Promise<void>;
+    private fileFor;
+}
+//# sourceMappingURL=client-id-store.d.ts.map

package/dist/client-id-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-id-store.d.ts","sourceRoot":"","sources":["../src/client-id-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC/C,kEAAkE;IAClE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAExC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI9C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhE;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM;IAEtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAc9C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D,OAAO,CAAC,OAAO;CAQhB"}

package/dist/client-id-store.js

@@ -0,0 +1,66 @@
+/**
+ * Persistence for the AHP `clientId`. Per the AHP spec, the client owns
+ * its identifier — `InitializeParams.clientId` is supplied by the client
+ * on every connect. {@link AhpClientSocket} mints a fresh UUID via
+ * `randomUUID()` the first time it sees an empty store, persists it here,
+ * and replays the same id on every subsequent connect so the host can
+ * resume in-flight subscriptions.
+ *
+ * Keyed by an opaque string so a single store can serve multiple
+ * connections (e.g., one `ClientIdStore` per `MultiHostClient` keyed
+ * by host id).
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+/**
+ * In-memory store. Suitable for tests and for the lifetime of a single
+ * process where persistence across restarts is not required.
+ */
+export class InMemoryClientIdStore {
+    entries = new Map();
+    async load(key) {
+        return this.entries.get(key);
+    }
+    async save(key, clientId) {
+        this.entries.set(key, clientId);
+    }
+}
+/**
+ * On-disk store using one file per key under `rootDir`. Writes are atomic
+ * via a `.tmp`-then-`rename` pattern, so a crash mid-write can never corrupt
+ * a previously-saved value.
+ */
+export class FileClientIdStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async load(key) {
+        try {
+            const data = await readFile(this.fileFor(key), "utf8");
+            const trimmed = data.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+        catch (err) {
+            // ENOENT is the only expected error; anything else is a real problem.
+            if (err.code === "ENOENT") {
+                return undefined;
+            }
+            throw err;
+        }
+    }
+    async save(key, clientId) {
+        const target = this.fileFor(key);
+        const tmp = `${target}.${randomUUID()}.tmp`;
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(tmp, clientId, "utf8");
+        await rename(tmp, target);
+    }
+    fileFor(key) {
+        // Sanitize: only allow [A-Za-z0-9._-]. Other characters are URL-encoded.
+        const safe = key.replace(/[^A-Za-z0-9._-]/g, (c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+        return join(this.rootDir, `${safe}.clientid`);
+    }
+}
+//# sourceMappingURL=client-id-store.js.map

package/dist/client-id-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-id-store.js","sourceRoot":"","sources":["../src/client-id-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAUzC;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IACf,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE9C,KAAK,CAAC,IAAI,CAAC,GAAW;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,QAAgB;QAC7C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACQ;IAApC,YAAoC,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEhD,KAAK,CAAC,IAAI,CAAC,GAAW;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YACvD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sEAAsE;YACtE,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,QAAgB;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,UAAU,EAAE,MAAM,CAAC;QAC5C,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5B,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,yEAAyE;QACzE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CACtB,kBAAkB,EAClB,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC3D,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,WAAW,CAAC,CAAC;IAChD,CAAC;CACF"}

package/dist/error-codes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local transport-layer errors. These are NEVER sent on the wire — they are
+ * thrown / used to reject pending promises inside this package when a request
+ * cannot complete (connection lost, timed out, etc.).
+ *
+ * On-the-wire JSON-RPC + AHP error codes live in `@grackle-ai/ahp`'s
+ * `JsonRpcErrorCodes` / `AhpErrorCodes` (spec-defined integers).
+ */
+/** Discriminator for {@link TransportError}. */
+export type TransportErrorKind = 
+/** A pending request was abandoned because the underlying socket closed. */
+"connection-lost"
+/** A pending request exceeded its `requestTimeoutMs`. */
+ | "request-timeout"
+/** Authentication was rejected by the host (HTTP 401 on upgrade, or close-code 4401). */
+ | "auth-failed"
+/** Peer sent a binary frame; we close 1003 and abort. */
+ | "binary-frame"
+/** Peer sent a non-`initialize` request before the handshake completed. */
+ | "not-initialized"
+/** Peer sent `initialize` twice on the same connection. */
+ | "already-initialized"
+/** Operation attempted after the caller invoked `.close()`. */
+ | "user-closed";
+/** Error thrown / used to reject promises for transport-internal failures. */
+export declare class TransportError extends Error {
+    readonly kind: TransportErrorKind;
+    constructor(kind: TransportErrorKind, message: string);
+}
+/**
+ * WebSocket close codes used by this package. The 4xxx range is the
+ * application-defined range per [RFC 6455 §7.4.2](https://www.rfc-editor.org/rfc/rfc6455#section-7.4.2).
+ */
+export declare const WsCloseCode: {
+    /** Normal closure initiated by either peer. */
+    readonly Normal: 1000;
+    /** Peer sent a binary frame; we don't speak binary. */
+    readonly UnsupportedData: 1003;
+    /** Heartbeat: 2 consecutive missed pongs. */
+    readonly HeartbeatTimeout: 4001;
+    /** Auth rejected mid-session (rare; pre-upgrade auth covers most cases). */
+    readonly AuthRejected: 4401;
+};
+export type WsCloseCode = (typeof WsCloseCode)[keyof typeof WsCloseCode];
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,MAAM,MAAM,kBAAkB;AAC5B,4EAA4E;AAC1E,iBAAiB;AACnB,yDAAyD;GACvD,iBAAiB;AACnB,yFAAyF;GACvF,aAAa;AACf,yDAAyD;GACvD,cAAc;AAChB,2EAA2E;GACzE,iBAAiB;AACnB,2DAA2D;GACzD,qBAAqB;AACvB,+DAA+D;GAC7D,aAAa,CAAC;AAElB,8EAA8E;AAC9E,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAC;gBAEtB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAK7D;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,+CAA+C;;IAE/C,uDAAuD;;IAEvD,6CAA6C;;IAE7C,4EAA4E;;CAEpE,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC"}

package/dist/error-codes.js

@@ -0,0 +1,32 @@
+/**
+ * Local transport-layer errors. These are NEVER sent on the wire — they are
+ * thrown / used to reject pending promises inside this package when a request
+ * cannot complete (connection lost, timed out, etc.).
+ *
+ * On-the-wire JSON-RPC + AHP error codes live in `@grackle-ai/ahp`'s
+ * `JsonRpcErrorCodes` / `AhpErrorCodes` (spec-defined integers).
+ */
+/** Error thrown / used to reject promises for transport-internal failures. */
+export class TransportError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "TransportError";
+        this.kind = kind;
+    }
+}
+/**
+ * WebSocket close codes used by this package. The 4xxx range is the
+ * application-defined range per [RFC 6455 §7.4.2](https://www.rfc-editor.org/rfc/rfc6455#section-7.4.2).
+ */
+export const WsCloseCode = {
+    /** Normal closure initiated by either peer. */
+    Normal: 1000,
+    /** Peer sent a binary frame; we don't speak binary. */
+    UnsupportedData: 1003,
+    /** Heartbeat: 2 consecutive missed pongs. */
+    HeartbeatTimeout: 4001,
+    /** Auth rejected mid-session (rare; pre-upgrade auth covers most cases). */
+    AuthRejected: 4401,
+};
+//# sourceMappingURL=error-codes.js.map

package/dist/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,8EAA8E;AAC9E,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvB,IAAI,CAAqB;IAEzC,YAAmB,IAAwB,EAAE,OAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,+CAA+C;IAC/C,MAAM,EAAE,IAAI;IACZ,uDAAuD;IACvD,eAAe,EAAE,IAAI;IACrB,6CAA6C;IAC7C,gBAAgB,EAAE,IAAI;IACtB,4EAA4E;IAC5E,YAAY,EAAE,IAAI;CACV,CAAC"}

package/dist/examples/echo-subscriber.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function runEchoSubscriber(count: number): Promise<{
+    received: unknown[];
+    dispose: () => Promise<void>;
+}>;
+//# sourceMappingURL=echo-subscriber.d.ts.map

package/dist/examples/echo-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo-subscriber.d.ts","sourceRoot":"","sources":["../../src/examples/echo-subscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqBH;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CA4ED"}