Add examples and update imports

Author: federicociner

package.json

@@ -27,22 +27,27 @@
   "exports": {
     ".": {
       "types": "./dist/acp.d.ts",
+      "import": "./dist/acp.js",
       "default": "./dist/acp.js"
     },
     "./http-client": {
       "types": "./dist/http-stream.d.ts",
+      "import": "./dist/http-stream.js",
       "default": "./dist/http-stream.js"
     },
     "./ws-client": {
       "types": "./dist/ws-stream.d.ts",
+      "import": "./dist/ws-stream.js",
       "default": "./dist/ws-stream.js"
     },
     "./server": {
       "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
       "default": "./dist/server.js"
     },
     "./node": {
       "types": "./dist/node-adapter.d.ts",
+      "import": "./dist/node-adapter.js",
       "default": "./dist/node-adapter.js"
     },
     "./schema/schema.json": "./schema/schema.json"
@@ -67,8 +72,14 @@
     "docs:ts:verify": "cd src && typedoc --emit none && echo 'TypeDoc verification passed'"
   },
   "peerDependencies": {
+    "ws": ">=8.0.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@hey-api/openapi-ts": "^0.97.0",

src/examples/README.md

@@ -4,6 +4,9 @@ This directory contains examples using the [ACP](https://agentclientprotocol.com
 
 - [`agent.ts`](./agent.ts) - A minimal agent implementation that simulates LLM interaction
 - [`client.ts`](./client.ts) - A minimal client implementation that spawns the [`agent.ts`](./agent.ts) as a subprocess
+- [`http-server.ts`](./http-server.ts) - A minimal ACP Streamable HTTP server with WebSocket upgrade support
+- [`http-client.ts`](./http-client.ts) - A minimal client using `createHttpStream`
+- [`ws-client.ts`](./ws-client.ts) - A minimal client using `createWebSocketStream`
 
 ## Running the Agent
 
@@ -75,3 +78,25 @@ npx tsx src/examples/client.ts
 ```
 
 This client will spawn the example agent as a subprocess, send a message, and print the content it receives from it.
+
+## Running the HTTP and WebSocket Examples
+
+Start the Streamable HTTP server with WebSocket upgrade support:
+
+```bash
+npx tsx src/examples/http-server.ts
+```
+
+In another terminal, run the HTTP client:
+
+```bash
+npx tsx src/examples/http-client.ts
+```
+
+Or run the WebSocket client:
+
+```bash
+npx tsx src/examples/ws-client.ts
+```
+
+The HTTP example sends a bearer token through custom request headers. The WebSocket example passes the Node `ws` constructor so custom headers can be sent during the WebSocket handshake. Browser WebSocket clients can use `createWebSocketStream` too, but browsers do not allow custom WebSocket headers.

src/examples/http-client.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import * as acp from "@agentclientprotocol/sdk";
+import { createHttpStream } from "@agentclientprotocol/sdk/http-client";
+
+class HttpExampleClient implements acp.Client {
+  async requestPermission(
+    params: acp.RequestPermissionRequest,
+  ): Promise<acp.RequestPermissionResponse> {
+    return {
+      outcome: {
+        outcome: "selected",
+        optionId: params.options[0]?.optionId ?? "allow",
+      },
+    };
+  }
+
+  async sessionUpdate(params: acp.SessionNotification): Promise<void> {
+    const update = params.update;
+
+    if (update.sessionUpdate === "agent_message_chunk") {
+      process.stdout.write(
+        update.content.type === "text" ? update.content.text : "",
+      );
+      return;
+    }
+
+    console.log(`[${update.sessionUpdate}]`);
+  }
+}
+
+const serverUrl = process.env.ACP_HTTP_URL ?? "http://127.0.0.1:7331/acp";
+const stream = createHttpStream(serverUrl, {
+  headers: {
+    Authorization: "Bearer example-token",
+  },
+  // To use cookies, pass a cookie-aware fetch implementation here instead of relying on a built-in cookie jar.
+  // fetch: cookieAwareFetch,
+});
+const connection = new acp.ClientSideConnection(
+  (_agent) => new HttpExampleClient(),
+  stream,
+);
+
+try {
+  await connection.initialize({
+    protocolVersion: acp.PROTOCOL_VERSION,
+    clientCapabilities: {},
+  });
+
+  const session = await connection.newSession({
+    cwd: process.cwd(),
+    mcpServers: [],
+  });
+
+  const result = await connection.prompt({
+    sessionId: session.sessionId,
+    prompt: [
+      {
+        type: "text",
+        text: "Hello over Streamable HTTP",
+      },
+    ],
+  });
+
+  console.log(`\nDone: ${result.stopReason}`);
+} finally {
+  await stream.writable.close();
+}

src/examples/http-server.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+
+import { WebSocketServer } from "ws";
+
+import * as acp from "@agentclientprotocol/sdk";
+import { createNodeHttpHandler } from "@agentclientprotocol/sdk/node";
+import { AcpServer } from "@agentclientprotocol/sdk/server";
+
+class HttpExampleAgent implements acp.Agent {
+  private readonly connection: acp.AgentSideConnection;
+  private readonly sessions = new Set<string>();
+
+  constructor(connection: acp.AgentSideConnection) {
+    this.connection = connection;
+  }
+
+  async initialize(
+    _params: acp.InitializeRequest,
+  ): Promise<acp.InitializeResponse> {
+    return {
+      protocolVersion: acp.PROTOCOL_VERSION,
+      agentCapabilities: {
+        loadSession: false,
+      },
+    };
+  }
+
+  async newSession(
+    _params: acp.NewSessionRequest,
+  ): Promise<acp.NewSessionResponse> {
+    const sessionId = crypto.randomUUID();
+    this.sessions.add(sessionId);
+    return { sessionId };
+  }
+
+  async authenticate(
+    _params: acp.AuthenticateRequest,
+  ): Promise<acp.AuthenticateResponse> {
+    return {};
+  }
+
+  async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
+    if (!this.sessions.has(params.sessionId)) {
+      throw new Error(`Session ${params.sessionId} not found`);
+    }
+
+    await this.connection.sessionUpdate({
+      sessionId: params.sessionId,
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: {
+          type: "text",
+          text: "Hello from the ACP HTTP/WebSocket example server.",
+        },
+      },
+    });
+
+    return { stopReason: "end_turn" };
+  }
+
+  async cancel(_params: acp.CancelNotification): Promise<void> {}
+}
+
+const acpServer = new AcpServer({
+  createAgent: (connection) => new HttpExampleAgent(connection),
+});
+const acpHttpHandler = createNodeHttpHandler(acpServer);
+const webSocketServer = new WebSocketServer({ noServer: true });
+const port = Number.parseInt(process.env.PORT ?? "7331", 10);
+
+const httpServer = createServer((req, res) => {
+  if (!isAcpPath(req.url)) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+    return;
+  }
+
+  // Put authentication or tenant-selection middleware here before routing to AcpServer.
+  // For example, validate `req.headers.authorization` and reject unauthorized requests.
+  if (!isAuthorized(req.headers.authorization)) {
+    res.writeHead(401, { "Content-Type": "text/plain" });
+    res.end("Unauthorized");
+    return;
+  }
+
+  acpHttpHandler(req, res);
+});
+
+httpServer.on("upgrade", (req, socket, head) => {
+  if (!isAcpPath(req.url) || !isAuthorized(req.headers.authorization)) {
+    socket.destroy();
+    return;
+  }
+
+  webSocketServer.handleUpgrade(req, socket, head, (ws) => {
+    acpServer.handleWebSocket(ws);
+  });
+});
+
+httpServer.listen(port, () => {
+  console.log(`ACP HTTP endpoint listening at http://127.0.0.1:${port}/acp`);
+  console.log(`ACP WebSocket endpoint listening at ws://127.0.0.1:${port}/acp`);
+});
+
+function isAcpPath(url: string | undefined): boolean {
+  return new URL(url ?? "/", "http://127.0.0.1").pathname === "/acp";
+}
+
+function isAuthorized(authorization: string | undefined): boolean {
+  return (
+    authorization === undefined || authorization === "Bearer example-token"
+  );
+}

src/examples/ws-client.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { WebSocket } from "ws";
+
+import * as acp from "@agentclientprotocol/sdk";
+import { createWebSocketStream } from "@agentclientprotocol/sdk/ws-client";
+import type { WebSocketConstructor } from "@agentclientprotocol/sdk/ws-client";
+
+class WebSocketExampleClient implements acp.Client {
+  async requestPermission(
+    params: acp.RequestPermissionRequest,
+  ): Promise<acp.RequestPermissionResponse> {
+    return {
+      outcome: {
+        outcome: "selected",
+        optionId: params.options[0]?.optionId ?? "allow",
+      },
+    };
+  }
+
+  async sessionUpdate(params: acp.SessionNotification): Promise<void> {
+    const update = params.update;
+
+    if (update.sessionUpdate === "agent_message_chunk") {
+      process.stdout.write(
+        update.content.type === "text" ? update.content.text : "",
+      );
+      return;
+    }
+
+    console.log(`[${update.sessionUpdate}]`);
+  }
+}
+
+const serverUrl = process.env.ACP_WS_URL ?? "ws://127.0.0.1:7331/acp";
+const stream = createWebSocketStream(serverUrl, {
+  WebSocket: WebSocket satisfies WebSocketConstructor,
+  // Custom headers work with Node's `ws` constructor. Browser WebSocket does not support custom headers.
+  headers: {
+    Authorization: "Bearer example-token",
+  },
+});
+const connection = new acp.ClientSideConnection(
+  (_agent) => new WebSocketExampleClient(),
+  stream,
+);
+
+try {
+  await connection.initialize({
+    protocolVersion: acp.PROTOCOL_VERSION,
+    clientCapabilities: {},
+  });
+
+  const session = await connection.newSession({
+    cwd: process.cwd(),
+    mcpServers: [],
+  });
+
+  const result = await connection.prompt({
+    sessionId: session.sessionId,
+    prompt: [
+      {
+        type: "text",
+        text: "Hello over WebSocket",
+      },
+    ],
+  });
+
+  console.log(`\nDone: ${result.stopReason}`);
+} finally {
+  await stream.writable.close();
+}