Add docstrings

Author: federicociner

src/http-stream.ts

@@ -14,15 +14,17 @@ import type { AnyMessage } from "./jsonrpc.js";
 import type { Stream } from "./stream.js";
 
 export interface HttpStreamOptions {
+  /** Fetch implementation to use. Defaults to `globalThis.fetch`. */
   readonly fetch?: typeof globalThis.fetch;
+  /** Headers to include on every HTTP/SSE request. */
   readonly headers?: Record<string, string>;
 }
 
 /**
- * Creates an ACP Stream that speaks the Streamable HTTP transport.
+ * Creates an ACP Stream over Streamable HTTP.
  *
- * The transport uses HTTP POST for client-to-agent messages and SSE GET streams for agent-to-client messages.
- * Cookie management is intentionally not built in; pass a cookie-aware fetch implementation when needed.
+ * Uses POST for client messages and SSE GET streams for server messages.
+ * Pass a custom `fetch` for cookies, auth, proxies, or non-browser runtimes.
  */
 export function createHttpStream(
   serverUrl: string,

src/server.ts

@@ -26,10 +26,19 @@ import type {
 import type { Agent, AgentSideConnection } from "./acp.js";
 import type { AnyMessage, AnyRequest, AnyResponse } from "./jsonrpc.js";
 
+/** Options for creating an ACP server transport. */
 export interface AcpServerOptions {
+  /** Creates the agent implementation for each accepted ACP connection. */
   createAgent: (conn: AgentSideConnection) => Agent;
 }
 
+/**
+ * ACP server transport for Streamable HTTP and WebSocket connections.
+ *
+ * Route HTTP requests to {@link handleRequest}. For WebSocket upgrades, let your
+ * framework perform the upgrade and pass the accepted socket to
+ * {@link handleWebSocket}.
+ */
 export class AcpServer {
   private readonly createAgent: (conn: AgentSideConnection) => Agent;
   private readonly registry = new ConnectionRegistry();
@@ -38,6 +47,7 @@ export class AcpServer {
     this.createAgent = options.createAgent;
   }
 
+  /** Handles one Streamable HTTP ACP request. */
   async handleRequest(req: Request): Promise<Response> {
     if (req.method === "POST") {
       return await this.handlePost(req);
@@ -54,13 +64,15 @@ export class AcpServer {
     return textResponse("Method Not Allowed", 405);
   }
 
+  /** Handles one accepted ACP WebSocket connection. */
   handleWebSocket(socket: WebSocketServerSocket): void {
     handleWebSocketConnection(socket, {
       registry: this.registry,
       createAgent: this.createAgent,
     });
   }
 
+  /** Closes all active ACP connections owned by this server. */
   async close(): Promise<void> {
     this.registry.closeAll();
   }

src/ws-server.ts

@@ -18,6 +18,7 @@ import type {
 import type { AnyMessage, AnyRequest } from "./jsonrpc.js";
 import type { WebSocketLike } from "./ws-utils.js";
 
+/** WebSocket shape accepted by `AcpServer.handleWebSocket`. */
 export type WebSocketServerSocket = WebSocketLike;
 
 type ForwardResult =

src/ws-stream.ts

@@ -5,18 +5,18 @@ import type { AnyMessage } from "./jsonrpc.js";
 import type { Stream } from "./stream.js";
 
 export interface WebSocketStreamOptions {
-  /** WebSocket subprotocols. */
+  /** WebSocket subprotocols to request. */
   readonly protocols?: string[];
   /**
-   * Custom headers for runtimes/constructors that support them, such as Node.js
-   * `ws`. Browsers ignore custom headers because the browser WebSocket API does
-   * not expose a headers option.
+   * Headers for WebSocket constructors that support them, such as Node `ws`.
+   * Browser WebSocket constructors ignore custom headers.
    */
   readonly headers?: Record<string, string>;
-  /** Custom WebSocket constructor, for example `ws.WebSocket` in Node.js. */
+  /** WebSocket constructor to use. Defaults to `globalThis.WebSocket`. */
   readonly WebSocket?: WebSocketConstructor;
 }
 
+/** Constructor shape used by `createWebSocketStream`. */
 export interface WebSocketConstructor {
   new (
     url: string,
@@ -25,14 +25,15 @@ export interface WebSocketConstructor {
   ): WebSocketLike;
 }
 
+export type { WebSocketLike };
+
 const SOCKET_OPEN = 1;
 
 /**
- * Creates an ACP Stream that speaks JSON-RPC over WebSocket text frames.
+ * Creates an ACP Stream over WebSocket.
  *
- * Browser WebSocket constructors do not support custom headers. The `headers`
- * option is passed as a best-effort third constructor argument for runtimes such
- * as Node.js `ws` that accept it.
+ * Sends and receives ACP JSON-RPC messages as WebSocket text frames. In Node,
+ * pass a WebSocket constructor such as `ws.WebSocket` via `options.WebSocket`.
  */
 export function createWebSocketStream(
   serverUrl: string,

src/ws-utils.ts

@@ -1,3 +1,4 @@
+/** Minimal browser/Node-compatible WebSocket shape used by ACP transports. */
 export interface WebSocketLike {
   readonly readyState?: number;
   send(data: string): void;