acp-websocket-transport 0.1.1

package/dist/src/client.js

@@ -0,0 +1,125 @@
+/**
+ * ACP WebSocket client library.
+ *
+ * Provides a high-level `createClientConnection` function that opens a WebSocket
+ * to an {@link WebSocketACPServer} (or any ACP-over-WebSocket server) and returns
+ * a fully initialized `ClientSideConnection` from `@agentclientprotocol/sdk`.
+ *
+ * Authentication helpers (`withBearerToken`, `withBasicAuth`, `withApiKey`) generate
+ * the `wsOptions` fragment needed to pass credentials during the HTTP upgrade handshake.
+ *
+ * @example Bearer token
+ * ```ts
+ * import { createClientConnection, withBearerToken } from "acp-websocket-transport";
+ *
+ * const { connection, close } = await createClientConnection(
+ *   "ws://localhost:3000",
+ *   {
+ *     ...withBearerToken("my-secret"),
+ *     toClient: (agent) => ({
+ *       sessionUpdate: async (params) => { console.log(params); },
+ *       requestPermission: async () => ({ outcome: "allow_once" }),
+ *     }),
+ *   }
+ * );
+ *
+ * const init = await connection.initialize({ protocolVersion: 0, clientCapabilities: {} });
+ * console.log(init.agentInfo);
+ * close();
+ * ```
+ */
+import WebSocket from "ws";
+import { ClientSideConnection } from "@agentclientprotocol/sdk";
+import { wsStream } from "./transport.js";
+// ─── Connection factory ───────────────────────────────────────────────────────
+/**
+ * Opens a WebSocket connection to an ACP server and returns a
+ * `ClientSideConnection` ready for use.
+ *
+ * @param url  WebSocket URL of the ACP server (e.g. `"ws://localhost:3000"`)
+ * @param options  Optional configuration (auth headers, client handler, timeout)
+ * @throws If the WebSocket fails to open within `connectTimeout` ms
+ */
+export async function createClientConnection(url, options = {}) {
+    const { toClient, protocols, wsOptions, connectTimeout = 10_000 } = options;
+    const ws = new WebSocket(url, protocols, wsOptions);
+    await waitForOpen(ws, connectTimeout);
+    const stream = wsStream(ws);
+    // Default no-op client for callers that only make outgoing requests
+    const noopClient = () => ({
+        sessionUpdate: async () => { },
+        requestPermission: async () => ({
+            outcome: "reject_once",
+        }),
+    });
+    const connection = new ClientSideConnection(toClient ?? noopClient, stream);
+    const close = () => ws.close(1000, "Client closed");
+    return { connection, stream, close };
+}
+// ─── Auth helpers ─────────────────────────────────────────────────────────────
+/**
+ * Returns the `wsOptions` fragment needed to authenticate with a Bearer token.
+ *
+ * Spread this into the options passed to {@link createClientConnection}:
+ * ```ts
+ * await createClientConnection(url, { ...withBearerToken("tok"), toClient });
+ * ```
+ */
+export function withBearerToken(token) {
+    return {
+        wsOptions: { headers: { Authorization: `Bearer ${token}` } },
+    };
+}
+/**
+ * Returns the `wsOptions` fragment needed for HTTP Basic authentication.
+ *
+ * ⚠️ Use TLS (`wss://`) in production — credentials are only base64-encoded.
+ */
+export function withBasicAuth(username, password) {
+    const encoded = Buffer.from(`${username}:${password}`).toString("base64");
+    return {
+        wsOptions: { headers: { Authorization: `Basic ${encoded}` } },
+    };
+}
+/**
+ * Returns the `wsOptions` fragment needed to authenticate via an arbitrary
+ * HTTP header (e.g. an API key).
+ *
+ * @param header  Header name (e.g. `"x-api-key"`)
+ * @param key     The key value
+ */
+export function withApiKey(header, key) {
+    return {
+        wsOptions: { headers: { [header]: key } },
+    };
+}
+// ─── Internals ────────────────────────────────────────────────────────────────
+/**
+ * Waits for a WebSocket to transition to the OPEN state, with a timeout.
+ */
+function waitForOpen(ws, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        if (ws.readyState === WebSocket.OPEN) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            ws.terminate();
+            reject(new Error(`WebSocket connection timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const cleanup = () => clearTimeout(timer);
+        ws.once("open", () => {
+            cleanup();
+            resolve();
+        });
+        ws.once("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        ws.once("close", (code, reason) => {
+            cleanup();
+            reject(new Error(`WebSocket closed before open: ${code} ${reason.toString()}`));
+        });
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * acp-websocket-transport
+ *
+ * WebSocket transport layer for ACP (Agent Client Protocol).
+ *
+ * ## Architecture
+ *
+ * ```
+ * [Client Library] <── WebSocket ──> [WebSocketACPServer] <── stdio ──> [ACP Agent]
+ * ```
+ *
+ * The server acts as a transparent proxy: it spawns one ACP agent subprocess per
+ * WebSocket connection and pipes raw JSON-RPC messages between them.
+ *
+ * Authentication is handled at the HTTP Upgrade handshake stage using standard
+ * HTTP mechanisms (Bearer token, Basic auth, API key header).
+ *
+ * ## Quick start
+ *
+ * **Server:**
+ * ```ts
+ * import { WebSocketACPServer, bearerAuth } from "acp-websocket-transport";
+ *
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "node",
+ *   args: ["dist/my-agent.js"],
+ *   verifyClient: bearerAuth(["my-secret-token"]),
+ * });
+ * await server.listening();
+ * ```
+ *
+ * **Client:**
+ * ```ts
+ * import { createClientConnection, withBearerToken } from "acp-websocket-transport";
+ *
+ * const { connection, close } = await createClientConnection(
+ *   "ws://localhost:3000",
+ *   withBearerToken("my-secret-token")
+ * );
+ *
+ * const init = await connection.initialize({ protocolVersion: 0, clientCapabilities: {} });
+ * console.log(init.agentInfo);
+ * close();
+ * ```
+ */
+/**
+ * Creates an ACP `Stream` from an open `ws` WebSocket.
+ * This is the foundational building block — server and client both use it internally.
+ */
+export { wsStream } from "./transport.js";
+export { WebSocketACPServer } from "./server.js";
+export type { WebSocketACPServerOptions, ErrorContext } from "./server.js";
+export { createClientConnection, withBearerToken, withBasicAuth, withApiKey } from "./client.js";
+export type { ClientConnectionOptions, ClientConnection } from "./client.js";
+export { bearerAuth, basicAuth, apiKeyAuth, anyAuth } from "./auth.js";
+export type { VerifyClientFn, VerifyClientInfo } from "./auth.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3E,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI7E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,59 @@
+/**
+ * acp-websocket-transport
+ *
+ * WebSocket transport layer for ACP (Agent Client Protocol).
+ *
+ * ## Architecture
+ *
+ * ```
+ * [Client Library] <── WebSocket ──> [WebSocketACPServer] <── stdio ──> [ACP Agent]
+ * ```
+ *
+ * The server acts as a transparent proxy: it spawns one ACP agent subprocess per
+ * WebSocket connection and pipes raw JSON-RPC messages between them.
+ *
+ * Authentication is handled at the HTTP Upgrade handshake stage using standard
+ * HTTP mechanisms (Bearer token, Basic auth, API key header).
+ *
+ * ## Quick start
+ *
+ * **Server:**
+ * ```ts
+ * import { WebSocketACPServer, bearerAuth } from "acp-websocket-transport";
+ *
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "node",
+ *   args: ["dist/my-agent.js"],
+ *   verifyClient: bearerAuth(["my-secret-token"]),
+ * });
+ * await server.listening();
+ * ```
+ *
+ * **Client:**
+ * ```ts
+ * import { createClientConnection, withBearerToken } from "acp-websocket-transport";
+ *
+ * const { connection, close } = await createClientConnection(
+ *   "ws://localhost:3000",
+ *   withBearerToken("my-secret-token")
+ * );
+ *
+ * const init = await connection.initialize({ protocolVersion: 0, clientCapabilities: {} });
+ * console.log(init.agentInfo);
+ * close();
+ * ```
+ */
+// ── Transport primitive ───────────────────────────────────────────────────────
+/**
+ * Creates an ACP `Stream` from an open `ws` WebSocket.
+ * This is the foundational building block — server and client both use it internally.
+ */
+export { wsStream } from "./transport.js";
+// ── Server ────────────────────────────────────────────────────────────────────
+export { WebSocketACPServer } from "./server.js";
+// ── Client ────────────────────────────────────────────────────────────────────
+export { createClientConnection, withBearerToken, withBasicAuth, withApiKey } from "./client.js";
+// ── Auth helpers ──────────────────────────────────────────────────────────────
+export { bearerAuth, basicAuth, apiKeyAuth, anyAuth } from "./auth.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,iFAAiF;AAEjF;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,iFAAiF;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,iFAAiF;AAEjF,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGjG,iFAAiF;AAEjF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/server.d.ts

@@ -0,0 +1,117 @@
+/**
+ * WebSocket ACP server.
+ *
+ * Listens for incoming WebSocket connections and, for each one, spawns an
+ * ACP-compatible agent process via stdio. Incoming WebSocket frames are
+ * forwarded to the agent's stdin, and the agent's stdout is forwarded back
+ * as WebSocket frames.
+ *
+ * The server acts as a **transparent proxy** — it does not interpret ACP
+ * messages itself. All protocol handling is end-to-end between the remote
+ * client library and the spawned agent process.
+ *
+ * ```
+ * [WS Client] <── WebSocket ──> [WebSocketACPServer] <── stdio ──> [Agent process]
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { WebSocketACPServer, bearerAuth } from "acp-websocket-transport";
+ *
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "node",
+ *   args: ["dist/my-agent.js"],
+ *   verifyClient: bearerAuth(["my-secret-token"]),
+ * });
+ *
+ * await server.listening();
+ * console.log("Listening on", server.address);
+ * ```
+ */
+import type WebSocket from "ws";
+import type { VerifyClientFn } from "./auth.js";
+/** Error context indicating which subsystem produced the error. */
+export type ErrorContext = "websocket" | "process" | "bridge";
+/**
+ * Configuration options for {@link WebSocketACPServer}.
+ */
+export interface WebSocketACPServerOptions {
+    /**
+     * TCP port to listen on.
+     * Use `0` to let the OS pick an available port (useful in tests).
+     */
+    port: number;
+    /**
+     * The command to spawn for each incoming WebSocket connection.
+     * This should be the path to an ACP-compatible agent executable.
+     *
+     * @example "node"
+     * @example "/usr/bin/my-agent"
+     */
+    command: string;
+    /** Arguments to pass to the spawned command. */
+    args?: string[];
+    /**
+     * Additional environment variables merged into the spawned process's
+     * environment (on top of the current `process.env`).
+     */
+    env?: Record<string, string>;
+    /**
+     * Hostname / IP address to bind to.
+     * @default "localhost"
+     */
+    host?: string;
+    /**
+     * Optional authentication callback invoked on every incoming WebSocket
+     * upgrade request. Return `true` to allow the connection or `false` to
+     * reject it with HTTP 401.
+     *
+     * If omitted, all connections are accepted (no authentication).
+     *
+     * @see {@link bearerAuth}, {@link basicAuth}, {@link apiKeyAuth}, {@link anyAuth}
+     */
+    verifyClient?: VerifyClientFn;
+    /**
+     * Called when an unhandled error occurs in any subsystem.
+     * Useful for logging — the server attempts to recover gracefully regardless.
+     */
+    onError?: (err: Error, context: ErrorContext) => void;
+}
+/**
+ * WebSocket server that bridges ACP clients to stdio-based ACP agent processes.
+ *
+ * Each accepted WebSocket connection spawns one agent subprocess. The connection
+ * and subprocess lifecycles are tied together:
+ * - Agent exits → WebSocket is closed with code 1001
+ * - WebSocket closes → agent receives SIGTERM (then SIGKILL after 5 s)
+ */
+export declare class WebSocketACPServer {
+    private readonly wss;
+    private readonly sessions;
+    private readonly options;
+    constructor(options: WebSocketACPServerOptions);
+    private handleConnection;
+    /**
+     * Reads all messages from `src` and writes them to `dst`.
+     * Errors are forwarded to `onError` and both streams are cleaned up.
+     */
+    private pumpStream;
+    /**
+     * Returns a Promise that resolves once the server is bound and listening.
+     * Useful for waiting before connecting clients in tests or examples.
+     */
+    listening(): Promise<void>;
+    /**
+     * Closes the server: stops accepting new connections, terminates all active
+     * agent sessions, and resolves once the underlying server socket is closed.
+     */
+    close(): Promise<void>;
+    /**
+     * The address the server is listening on, or `null` if not yet listening.
+     * Cast to `AddressInfo` after calling {@link listening()} when binding to a
+     * numeric port (including `0`).
+     */
+    get address(): string | WebSocket.AddressInfo | null;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,SAAS,MAAM,IAAI,CAAC;AAOhC,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,WAAW,CAAC;AAIlE,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;CACvD;AAID;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,EAAE,yBAAyB;IAsC9C,OAAO,CAAC,gBAAgB;IA6ExB;;;OAGG;YACW,UAAU;IA4BxB;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAW1B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B;;;;OAIG;IACH,IAAI,OAAO,0CAEV;CACF"}

package/dist/src/server.js

@@ -0,0 +1,203 @@
+/**
+ * WebSocket ACP server.
+ *
+ * Listens for incoming WebSocket connections and, for each one, spawns an
+ * ACP-compatible agent process via stdio. Incoming WebSocket frames are
+ * forwarded to the agent's stdin, and the agent's stdout is forwarded back
+ * as WebSocket frames.
+ *
+ * The server acts as a **transparent proxy** — it does not interpret ACP
+ * messages itself. All protocol handling is end-to-end between the remote
+ * client library and the spawned agent process.
+ *
+ * ```
+ * [WS Client] <── WebSocket ──> [WebSocketACPServer] <── stdio ──> [Agent process]
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { WebSocketACPServer, bearerAuth } from "acp-websocket-transport";
+ *
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "node",
+ *   args: ["dist/my-agent.js"],
+ *   verifyClient: bearerAuth(["my-secret-token"]),
+ * });
+ *
+ * await server.listening();
+ * console.log("Listening on", server.address);
+ * ```
+ */
+import { WebSocketServer } from "ws";
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { ndJsonStream } from "@agentclientprotocol/sdk";
+import { wsStream } from "./transport.js";
+// ─── Server ───────────────────────────────────────────────────────────────────
+/**
+ * WebSocket server that bridges ACP clients to stdio-based ACP agent processes.
+ *
+ * Each accepted WebSocket connection spawns one agent subprocess. The connection
+ * and subprocess lifecycles are tied together:
+ * - Agent exits → WebSocket is closed with code 1001
+ * - WebSocket closes → agent receives SIGTERM (then SIGKILL after 5 s)
+ */
+export class WebSocketACPServer {
+    wss;
+    sessions = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+        this.wss = new WebSocketServer({
+            port: options.port,
+            host: options.host ?? "localhost",
+            // Wire verifyClient when provided
+            ...(options.verifyClient != null
+                ? {
+                    verifyClient: (info, done) => {
+                        Promise.resolve(options.verifyClient(info))
+                            .then((ok) => done(ok, ok ? 200 : 401, ok ? "OK" : "Unauthorized"))
+                            .catch((err) => {
+                            options.onError?.(err, "websocket");
+                            done(false, 500, "Internal Server Error");
+                        });
+                    },
+                }
+                : {}),
+        });
+        this.wss.on("connection", this.handleConnection.bind(this));
+        this.wss.on("error", (err) => {
+            options.onError?.(err, "websocket");
+        });
+    }
+    // ─── Connection handler ─────────────────────────────────────────────────────
+    handleConnection(ws) {
+        const { command, args = [], env = {}, onError } = this.options;
+        // Spawn the agent process with all stdio piped
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...env },
+        });
+        this.sessions.set(ws, child);
+        // Relay agent stderr → server stderr for debuggability
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(`[echo-agent stderr] ${chunk.toString()}`);
+        });
+        // Build the stdio Stream for the agent
+        // ndJsonStream(output, input):
+        //   output = WritableStream the SDK writes messages TO  (→ child stdin)
+        //   input  = ReadableStream the SDK reads messages FROM (← child stdout)
+        const agentStream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        // Build the WebSocket Stream for the remote client
+        const clientStream = wsStream(ws);
+        // Bidirectional bridge (transparent proxy — no ACP interpretation)
+        void this.pumpStream(clientStream.readable, agentStream.writable, "client → agent", onError);
+        void this.pumpStream(agentStream.readable, clientStream.writable, "agent → client", onError);
+        // ─── Lifecycle ────────────────────────────────────────────────────────────
+        // Agent exits → close WebSocket
+        child.on("exit", (code, signal) => {
+            this.sessions.delete(ws);
+            if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+                ws.close(1001, `Agent exited (${signal ?? String(code)})`);
+            }
+        });
+        child.on("error", (err) => {
+            onError?.(err, "process");
+            this.sessions.delete(ws);
+            if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+                ws.close(1011, "Agent process error");
+            }
+        });
+        // WebSocket closes → terminate agent
+        ws.on("close", () => {
+            this.sessions.delete(ws);
+            if (!child.killed) {
+                child.kill("SIGTERM");
+                // Grace period: escalate to SIGKILL after 5 s if the process persists
+                const t = setTimeout(() => {
+                    if (!child.killed)
+                        child.kill("SIGKILL");
+                }, 5_000);
+                // Don't prevent the Node.js event loop from exiting due to this timer
+                if (typeof t.unref === "function")
+                    t.unref();
+            }
+        });
+    }
+    // ─── Stream pump ────────────────────────────────────────────────────────────
+    /**
+     * Reads all messages from `src` and writes them to `dst`.
+     * Errors are forwarded to `onError` and both streams are cleaned up.
+     */
+    async pumpStream(src, dst, _label, onError) {
+        const reader = src.getReader();
+        const writer = dst.getWriter();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                await writer.write(value);
+            }
+            await writer.close();
+        }
+        catch (err) {
+            onError?.(err, "bridge");
+            await writer.abort(err).catch(() => {
+                /* ignore secondary errors during abort */
+            });
+        }
+        finally {
+            reader.releaseLock();
+            writer.releaseLock();
+        }
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Returns a Promise that resolves once the server is bound and listening.
+     * Useful for waiting before connecting clients in tests or examples.
+     */
+    listening() {
+        return new Promise((resolve) => {
+            if (this.wss.address() !== null) {
+                // Already listening
+                resolve();
+            }
+            else {
+                this.wss.once("listening", resolve);
+            }
+        });
+    }
+    /**
+     * Closes the server: stops accepting new connections, terminates all active
+     * agent sessions, and resolves once the underlying server socket is closed.
+     */
+    async close() {
+        // Hard-terminate all active connections so wss.close() callback fires promptly
+        for (const [ws, child] of this.sessions) {
+            child.kill("SIGTERM");
+            ws.terminate(); // immediately destroy the socket (no close handshake needed)
+        }
+        this.sessions.clear();
+        return new Promise((resolve, reject) => {
+            this.wss.close((err) => {
+                if (err != null)
+                    reject(err);
+                else
+                    resolve();
+            });
+            // Safety net: resolve after 2 s in case the callback stalls
+            setTimeout(resolve, 2_000).unref?.();
+        });
+    }
+    /**
+     * The address the server is listening on, or `null` if not yet listening.
+     * Cast to `AddressInfo` after calling {@link listening()} when binding to a
+     * numeric port (including `0`).
+     */
+    get address() {
+        return this.wss.address();
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

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

package/dist/src/transport.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WebSocket transport for ACP (Agent Client Protocol).
+ *
+ * Converts a `ws` WebSocket into the SDK's {@link Stream} interface,
+ * enabling ACP connections over WebSocket instead of stdio.
+ *
+ * Each WebSocket text frame carries exactly one JSON-encoded AnyMessage.
+ * Binary frames are silently ignored (ACP only uses text frames).
+ */
+import type WebSocket from "ws";
+import type { Stream } from "@agentclientprotocol/sdk";
+/**
+ * Creates an ACP {@link Stream} from an open (or opening) `ws` WebSocket.
+ *
+ * Stream lifetime is tied to the WebSocket:
+ * - WS `close` / `error` → readable stream closes / errors
+ * - WritableStream `close()` → `ws.close(1000, ...)`
+ * - WritableStream `abort()` → `ws.terminate()` (hard close)
+ *
+ * @param ws - An open or opening `ws` WebSocket instance
+ * @returns Bidirectional ACP message stream
+ */
+export declare function wsStream(ws: WebSocket): Stream;
+//# sourceMappingURL=transport.d.ts.map

package/dist/src/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,SAAS,MAAM,IAAI,CAAC;AAEhC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAkBvD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CA2F9C"}