acp-websocket-transport 0.1.1

package/dist/examples/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Example: connect to the ACP WebSocket server with the client library.
+ *
+ * Usage (start the server first):
+ *   node dist/examples/server.js
+ *   node dist/examples/client.js
+ */
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/examples/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../examples/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/examples/client.js

@@ -0,0 +1,51 @@
+/**
+ * Example: connect to the ACP WebSocket server with the client library.
+ *
+ * Usage (start the server first):
+ *   node dist/examples/server.js
+ *   node dist/examples/client.js
+ */
+import { createClientConnection } from "../src/index.js";
+const { connection, close } = await createClientConnection("ws://localhost:3000", {
+    // Optional: supply auth credentials
+    // ...withBearerToken("my-secret-token"),
+    toClient: (_agent) => ({
+        sessionUpdate: async (params) => {
+            const { update } = params;
+            if ("content" in update &&
+                update.content != null &&
+                !Array.isArray(update.content) &&
+                update.content.type === "text" &&
+                "text" in update.content) {
+                console.log(`[agent] ${update.content.text}`);
+            }
+        },
+        requestPermission: async () => ({
+            outcome: "allow_once",
+        }),
+    }),
+});
+// ── ACP handshake ─────────────────────────────────────────────────────────────
+const initResult = await connection.initialize({
+    protocolVersion: 0,
+    clientInfo: { name: "example-client", version: "0.1.0" },
+    clientCapabilities: {},
+});
+console.log(`Connected to agent: ${initResult.agentInfo?.name} v${initResult.agentInfo?.version}`);
+// ── Create a session ──────────────────────────────────────────────────────────
+const session = await connection.newSession({
+    cwd: process.cwd(),
+    mcpServers: [],
+});
+console.log(`Session created: ${session.sessionId}`);
+// ── Send a prompt ─────────────────────────────────────────────────────────────
+console.log(`Sending prompt…`);
+const result = await connection.prompt({
+    sessionId: session.sessionId,
+    prompt: [{ type: "text", text: "Hello from the example client!" }],
+});
+console.log(`Turn ended with stopReason: ${result.stopReason}`);
+// ── Cleanup ───────────────────────────────────────────────────────────────────
+close();
+console.log("Connection closed.");
+//# sourceMappingURL=client.js.map

package/dist/examples/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../examples/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,MAAM,sBAAsB,CACxD,qBAAqB,EACrB;IACE,oCAAoC;IACpC,yCAAyC;IAEzC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACrB,aAAa,EAAE,KAAK,EAAE,MAA2B,EAAE,EAAE;YACnD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;YAC1B,IACE,SAAS,IAAI,MAAM;gBACnB,MAAM,CAAC,OAAO,IAAI,IAAI;gBACtB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;gBAC9B,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM;gBAC9B,MAAM,IAAI,MAAM,CAAC,OAAO,EACxB,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,iBAAiB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YAC9B,OAAO,EAAE,YAAqB;SAC/B,CAAC;KACH,CAAC;CACH,CACF,CAAC;AAEF,iFAAiF;AAEjF,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC;IAC7C,eAAe,EAAE,CAAC;IAClB,UAAU,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE;IACxD,kBAAkB,EAAE,EAAE;CACvB,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CACT,uBAAuB,UAAU,CAAC,SAAS,EAAE,IAAI,KAAK,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,CACtF,CAAC;AAEF,iFAAiF;AAEjF,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC;IAC1C,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,UAAU,EAAE,EAAE;CACf,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC,oBAAoB,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;AAErD,iFAAiF;AAEjF,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAC/B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC;IACrC,SAAS,EAAE,OAAO,CAAC,SAAS;IAC5B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAAC;CACnE,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC,+BAA+B,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;AAEhE,iFAAiF;AAEjF,KAAK,EAAE,CAAC;AACR,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * Minimal ACP echo agent for testing and examples.
+ *
+ * Communicates over stdio using the ndJsonStream transport (newline-delimited JSON).
+ * Responds to `session/prompt` requests by echoing the last text block back to the
+ * client prefixed with "Echo: ".
+ *
+ * Usage (as a standalone process):
+ *   node dist/examples/echo-agent.js
+ *
+ * The WebSocketACPServer example starts this as a subprocess for each connection.
+ */
+export {};
+//# sourceMappingURL=echo-agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"echo-agent.d.ts","sourceRoot":"","sources":["../../examples/echo-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/examples/echo-agent.js

@@ -0,0 +1,67 @@
+/**
+ * Minimal ACP echo agent for testing and examples.
+ *
+ * Communicates over stdio using the ndJsonStream transport (newline-delimited JSON).
+ * Responds to `session/prompt` requests by echoing the last text block back to the
+ * client prefixed with "Echo: ".
+ *
+ * Usage (as a standalone process):
+ *   node dist/examples/echo-agent.js
+ *
+ * The WebSocketACPServer example starts this as a subprocess for each connection.
+ */
+import { Readable, Writable } from "node:stream";
+import { AgentSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
+// ─── stdio stream setup ───────────────────────────────────────────────────────
+// Use the static Readable.toWeb / Writable.toWeb methods (Node.js 17+)
+const stdinReadable = Readable.toWeb(process.stdin);
+const stdoutWritable = Writable.toWeb(process.stdout);
+const stream = ndJsonStream(stdoutWritable, stdinReadable);
+// ─── Agent implementation ─────────────────────────────────────────────────────
+const _connection = new AgentSideConnection((conn) => ({
+    initialize(params) {
+        return Promise.resolve({
+            protocolVersion: params.protocolVersion,
+            agentInfo: {
+                name: "echo-agent",
+                version: "0.1.0",
+            },
+            agentCapabilities: {},
+        });
+    },
+    newSession(_params) {
+        return Promise.resolve({
+            sessionId: crypto.randomUUID(),
+        });
+    },
+    authenticate(_params) {
+        // No authentication required by this agent
+        return Promise.resolve();
+    },
+    cancel(_params) {
+        // No ongoing work to cancel in this simple echo agent
+        return Promise.resolve();
+    },
+    async prompt(params) {
+        // Find the last text block in the prompt and echo it
+        const textBlock = [...params.prompt]
+            .reverse()
+            .find((block) => block.type === "text");
+        const inputText = textBlock?.text ?? "(no text)";
+        // Send a session update notification with the echoed text
+        await conn.sessionUpdate({
+            sessionId: params.sessionId,
+            update: {
+                sessionUpdate: "agent_message_chunk",
+                content: {
+                    type: "text",
+                    text: `Echo: ${inputText}`,
+                },
+            },
+        });
+        return { stopReason: "end_turn" };
+    },
+}), stream);
+// Keep the process alive until the connection stream closes
+// (AgentSideConnection manages the stream lifecycle internally)
+//# sourceMappingURL=echo-agent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"echo-agent.js","sourceRoot":"","sources":["../../examples/echo-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAc7E,iFAAiF;AAEjF,uEAAuE;AACvE,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAClC,OAAO,CAAC,KAAK,CACgB,CAAC;AAChC,MAAM,cAAc,GAAG,QAAQ,CAAC,KAAK,CACnC,OAAO,CAAC,MAAM,CACe,CAAC;AAChC,MAAM,MAAM,GAAG,YAAY,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;AAE3D,iFAAiF;AAEjF,MAAM,WAAW,GAAG,IAAI,mBAAmB,CACzC,CAAC,IAAyB,EAAS,EAAE,CAAC,CAAC;IACrC,UAAU,CAAC,MAAyB;QAClC,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,SAAS,EAAE;gBACT,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,OAAO;aACjB;YACD,iBAAiB,EAAE,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,OAA0B;QACnC,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,YAAY,CACV,OAA4B;QAE5B,2CAA2C;QAC3C,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,OAA2B;QAChC,sDAAsD;QACtD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAqB;QAChC,qDAAqD;QACrD,MAAM,SAAS,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;aACjC,OAAO,EAAE;aACT,IAAI,CACH,CAAC,KAAK,EAAsE,EAAE,CAC5E,KAAK,CAAC,IAAI,KAAK,MAAM,CACxB,CAAC;QAEJ,MAAM,SAAS,GAAG,SAAS,EAAE,IAAI,IAAI,WAAW,CAAC;QAEjD,0DAA0D;QAC1D,MAAM,IAAI,CAAC,aAAa,CAAC;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE;gBACN,aAAa,EAAE,qBAAqB;gBACpC,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,SAAS,SAAS,EAAE;iBAC3B;aACF;SACF,CAAC,CAAC;QAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;IACpC,CAAC;CACF,CAAC,EACF,MAAM,CACP,CAAC;AAEF,4DAA4D;AAC5D,gEAAgE"}

package/dist/examples/server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Example: start the ACP WebSocket server.
+ *
+ * Usage:
+ *   node dist/examples/server.js
+ *
+ * Then run the client example in a separate terminal:
+ *   node dist/examples/client.js
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../examples/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/examples/server.js

@@ -0,0 +1,36 @@
+/**
+ * Example: start the ACP WebSocket server.
+ *
+ * Usage:
+ *   node dist/examples/server.js
+ *
+ * Then run the client example in a separate terminal:
+ *   node dist/examples/client.js
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { WebSocketACPServer } from "../src/index.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const echoAgentPath = join(__dirname, "echo-agent.js");
+const server = new WebSocketACPServer({
+    port: 3000,
+    command: "node",
+    args: [echoAgentPath],
+    // Optional: enable bearer token authentication
+    // verifyClient: bearerAuth(["my-secret-token"]),
+    onError: (err, ctx) => {
+        console.error(`[server error / ${ctx}]`, err.message);
+    },
+});
+await server.listening();
+console.log(`ACP WebSocket server listening on ws://localhost:3000`);
+console.log("Press Ctrl-C to stop.");
+// Graceful shutdown
+for (const signal of ["SIGTERM", "SIGINT"]) {
+    process.once(signal, async () => {
+        console.log(`\nReceived ${signal} — shutting down…`);
+        await server.close();
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/examples/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../examples/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAc,MAAM,iBAAiB,CAAC;AAEjE,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;AAEvD,MAAM,MAAM,GAAG,IAAI,kBAAkB,CAAC;IACpC,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,CAAC,aAAa,CAAC;IAErB,+CAA+C;IAC/C,iDAAiD;IAEjD,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC;CACF,CAAC,CAAC;AAEH,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;AACzB,OAAO,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;AACrE,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAErC,oBAAoB;AACpB,KAAK,MAAM,MAAM,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAU,EAAE,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;QAC9B,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,mBAAmB,CAAC,CAAC;QACrD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/auth.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Authentication helpers for the ACP WebSocket server.
+ *
+ * WebSocket connections begin with an HTTP Upgrade request, so standard HTTP
+ * authentication mechanisms (Bearer token, Basic auth, API key headers) can be
+ * applied directly at the handshake stage — before the WebSocket is established.
+ *
+ * The `ws` library exposes a `verifyClient` callback that receives the HTTP
+ * Upgrade request and can accept or reject the connection. This module provides
+ * the {@link VerifyClientFn} type and a set of built-in factory functions for
+ * common authentication schemes.
+ *
+ * @example Bearer token
+ * ```ts
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "my-agent",
+ *   verifyClient: bearerAuth(["secret-token-alice", "secret-token-bob"]),
+ * });
+ * ```
+ *
+ * @example Custom async validator (e.g. database lookup)
+ * ```ts
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "my-agent",
+ *   verifyClient: async ({ req }) => {
+ *     const token = req.headers["authorization"]?.split(" ")[1] ?? "";
+ *     return await db.tokens.isValid(token);
+ *   },
+ * });
+ * ```
+ */
+import type { IncomingMessage } from "node:http";
+/**
+ * Information about the incoming WebSocket upgrade request,
+ * as provided by the `ws` library's `verifyClient` callback.
+ */
+export interface VerifyClientInfo {
+    /** The raw Node.js HTTP request for the WebSocket upgrade */
+    req: IncomingMessage;
+    /** Value of the `Origin` header, or an empty string if absent */
+    origin: string;
+    /** Whether the connection was made over TLS (i.e. `wss://`) */
+    secure: boolean;
+}
+/**
+ * Authentication callback for the WebSocket server.
+ *
+ * Return (or resolve) `true` to allow the connection, `false` to reject it
+ * with HTTP 401 Unauthorized. Rejecting with a custom status code is possible
+ * via the lower-level `ws` `verifyClient` API; this interface keeps things simple.
+ *
+ * May be synchronous or asynchronous.
+ */
+export type VerifyClientFn = (info: VerifyClientInfo) => boolean | Promise<boolean>;
+/**
+ * Bearer token authentication.
+ *
+ * Accepts connections whose `Authorization` header matches
+ * `Bearer <token>` for any token in `validTokens`.
+ *
+ * @param validTokens - Iterable of accepted token strings
+ */
+export declare function bearerAuth(validTokens: Iterable<string>): VerifyClientFn;
+/**
+ * HTTP Basic authentication.
+ *
+ * Accepts connections whose `Authorization: Basic <base64(user:pass)>` header
+ * matches an entry in `credentials`.
+ *
+ * ⚠️ Always use TLS (`wss://`) in production — Basic auth credentials are only
+ * base64-encoded, not encrypted.
+ *
+ * @param credentials - Map of `{ username: password }`
+ */
+export declare function basicAuth(credentials: Record<string, string>): VerifyClientFn;
+/**
+ * API key authentication via an arbitrary HTTP header.
+ *
+ * Accepts connections that include a matching `<header>: <key>` in their
+ * upgrade request. Header name matching is case-insensitive (HTTP spec).
+ *
+ * @param header - Header name (e.g. `"x-api-key"`)
+ * @param validKeys - Iterable of accepted key strings
+ *
+ * @example
+ * ```ts
+ * verifyClient: apiKeyAuth("x-api-key", ["key1", "key2"])
+ * ```
+ */
+export declare function apiKeyAuth(header: string, validKeys: Iterable<string>): VerifyClientFn;
+/**
+ * Combines multiple {@link VerifyClientFn}s with OR semantics.
+ *
+ * The connection is accepted if **any** of the provided verifiers returns `true`.
+ * Useful when the server supports multiple authentication methods simultaneously.
+ *
+ * @param verifiers - One or more VerifyClientFn instances
+ *
+ * @example
+ * ```ts
+ * verifyClient: anyAuth(
+ *   bearerAuth(["service-token"]),
+ *   apiKeyAuth("x-api-key", ["ui-key"]),
+ * )
+ * ```
+ */
+export declare function anyAuth(...verifiers: VerifyClientFn[]): VerifyClientFn;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,GAAG,EAAE,eAAe,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,gBAAgB,KACnB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAIhC;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,cAAc,CAUxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,cAAc,CAgBhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,cAAc,CAQhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,GAAG,SAAS,EAAE,cAAc,EAAE,GAAG,cAAc,CAOtE"}

package/dist/src/auth.js

@@ -0,0 +1,135 @@
+/**
+ * Authentication helpers for the ACP WebSocket server.
+ *
+ * WebSocket connections begin with an HTTP Upgrade request, so standard HTTP
+ * authentication mechanisms (Bearer token, Basic auth, API key headers) can be
+ * applied directly at the handshake stage — before the WebSocket is established.
+ *
+ * The `ws` library exposes a `verifyClient` callback that receives the HTTP
+ * Upgrade request and can accept or reject the connection. This module provides
+ * the {@link VerifyClientFn} type and a set of built-in factory functions for
+ * common authentication schemes.
+ *
+ * @example Bearer token
+ * ```ts
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "my-agent",
+ *   verifyClient: bearerAuth(["secret-token-alice", "secret-token-bob"]),
+ * });
+ * ```
+ *
+ * @example Custom async validator (e.g. database lookup)
+ * ```ts
+ * const server = new WebSocketACPServer({
+ *   port: 3000,
+ *   command: "my-agent",
+ *   verifyClient: async ({ req }) => {
+ *     const token = req.headers["authorization"]?.split(" ")[1] ?? "";
+ *     return await db.tokens.isValid(token);
+ *   },
+ * });
+ * ```
+ */
+// ─── Built-in helpers ─────────────────────────────────────────────────────────
+/**
+ * Bearer token authentication.
+ *
+ * Accepts connections whose `Authorization` header matches
+ * `Bearer <token>` for any token in `validTokens`.
+ *
+ * @param validTokens - Iterable of accepted token strings
+ */
+export function bearerAuth(validTokens) {
+    const tokens = new Set(validTokens);
+    return ({ req }) => {
+        const auth = req.headers["authorization"] ?? "";
+        const spaceIdx = auth.indexOf(" ");
+        if (spaceIdx === -1)
+            return false;
+        const scheme = auth.slice(0, spaceIdx).toLowerCase();
+        const token = auth.slice(spaceIdx + 1);
+        return scheme === "bearer" && tokens.has(token);
+    };
+}
+/**
+ * HTTP Basic authentication.
+ *
+ * Accepts connections whose `Authorization: Basic <base64(user:pass)>` header
+ * matches an entry in `credentials`.
+ *
+ * ⚠️ Always use TLS (`wss://`) in production — Basic auth credentials are only
+ * base64-encoded, not encrypted.
+ *
+ * @param credentials - Map of `{ username: password }`
+ */
+export function basicAuth(credentials) {
+    return ({ req }) => {
+        const auth = req.headers["authorization"] ?? "";
+        const spaceIdx = auth.indexOf(" ");
+        if (spaceIdx === -1)
+            return false;
+        const scheme = auth.slice(0, spaceIdx).toLowerCase();
+        if (scheme !== "basic")
+            return false;
+        const encoded = auth.slice(spaceIdx + 1);
+        const decoded = Buffer.from(encoded, "base64").toString("utf8");
+        const colonIdx = decoded.indexOf(":");
+        if (colonIdx === -1)
+            return false;
+        const user = decoded.slice(0, colonIdx);
+        const pass = decoded.slice(colonIdx + 1);
+        return Object.prototype.hasOwnProperty.call(credentials, user) &&
+            credentials[user] === pass;
+    };
+}
+/**
+ * API key authentication via an arbitrary HTTP header.
+ *
+ * Accepts connections that include a matching `<header>: <key>` in their
+ * upgrade request. Header name matching is case-insensitive (HTTP spec).
+ *
+ * @param header - Header name (e.g. `"x-api-key"`)
+ * @param validKeys - Iterable of accepted key strings
+ *
+ * @example
+ * ```ts
+ * verifyClient: apiKeyAuth("x-api-key", ["key1", "key2"])
+ * ```
+ */
+export function apiKeyAuth(header, validKeys) {
+    const keys = new Set(validKeys);
+    const normalizedHeader = header.toLowerCase();
+    return ({ req }) => {
+        const value = req.headers[normalizedHeader];
+        if (typeof value !== "string")
+            return false;
+        return keys.has(value);
+    };
+}
+/**
+ * Combines multiple {@link VerifyClientFn}s with OR semantics.
+ *
+ * The connection is accepted if **any** of the provided verifiers returns `true`.
+ * Useful when the server supports multiple authentication methods simultaneously.
+ *
+ * @param verifiers - One or more VerifyClientFn instances
+ *
+ * @example
+ * ```ts
+ * verifyClient: anyAuth(
+ *   bearerAuth(["service-token"]),
+ *   apiKeyAuth("x-api-key", ["ui-key"]),
+ * )
+ * ```
+ */
+export function anyAuth(...verifiers) {
+    return async (info) => {
+        for (const verifier of verifiers) {
+            if (await verifier(info))
+                return true;
+        }
+        return false;
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/auth.js.map

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

package/dist/src/client.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 type { Stream } from "@agentclientprotocol/sdk";
+/** Factory function type accepted by `ClientSideConnection`. */
+type ToClientFactory = ConstructorParameters<typeof ClientSideConnection>[0];
+/**
+ * Options for {@link createClientConnection}.
+ */
+export interface ClientConnectionOptions {
+    /**
+     * Factory that creates the `Client` handler for incoming agent requests
+     * (e.g. `session/update` notifications, `session/request_permission`).
+     *
+     * If omitted, a no-op handler is used — suitable for fire-and-forget or
+     * when the caller only needs to make outgoing requests.
+     */
+    toClient?: ToClientFactory;
+    /**
+     * WebSocket subprotocols to negotiate during the upgrade handshake.
+     */
+    protocols?: string | string[];
+    /**
+     * Additional options passed directly to the `ws` WebSocket constructor.
+     * Use this to set custom headers (e.g. authentication) or TLS options.
+     *
+     * @see {@link withBearerToken}, {@link withBasicAuth}, {@link withApiKey}
+     */
+    wsOptions?: WebSocket.ClientOptions;
+    /**
+     * Milliseconds to wait for the WebSocket connection to open.
+     * @default 10000
+     */
+    connectTimeout?: number;
+}
+/**
+ * The result of {@link createClientConnection}.
+ */
+export interface ClientConnection {
+    /** The ACP `ClientSideConnection` — use this to call agent methods. */
+    connection: ClientSideConnection;
+    /** The underlying bidirectional stream (rarely needed directly). */
+    stream: Stream;
+    /** Closes the WebSocket and tears down the connection. */
+    close: () => void;
+}
+/**
+ * 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 declare function createClientConnection(url: string | URL, options?: ClientConnectionOptions): Promise<ClientConnection>;
+/**
+ * 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 declare function withBearerToken(token: string): Pick<ClientConnectionOptions, "wsOptions">;
+/**
+ * Returns the `wsOptions` fragment needed for HTTP Basic authentication.
+ *
+ * ⚠️ Use TLS (`wss://`) in production — credentials are only base64-encoded.
+ */
+export declare function withBasicAuth(username: string, password: string): Pick<ClientConnectionOptions, "wsOptions">;
+/**
+ * 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 declare function withApiKey(header: string, key: string): Pick<ClientConnectionOptions, "wsOptions">;
+export {};
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKvD,gEAAgE;AAChE,KAAK,eAAe,GAAG,qBAAqB,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE9B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC;IAEpC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,UAAU,EAAE,oBAAoB,CAAC;IACjC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAsB3B;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GACZ,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAI5C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAK5C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAI5C"}