@automatalabs/acp-server 0.1.0 → 0.2.1

package/README.md

@@ -1,14 +1,20 @@
 # `@automatalabs/acp-server`
 
 Connection-pinned ACP V1 proxy for the backends configured through
-`@automatalabs/acp-agents`. The package exposes the `agentprism-acp-server` stdio executable and a
-programmatic `serveAcpServer()` entry point.
+`@automatalabs/acp-agents`. The `agentprism-acp-server` executable defaults to stdio and can also
+listen for Streamable HTTP and WebSocket clients on one endpoint.
 
 ```bash
-npx @automatalabs/acp-server
+npx @automatalabs/acp-server                    # stdio
+npx @automatalabs/acp-server --http             # http://127.0.0.1:7331/acp + ws://…
+npx @automatalabs/acp-server --http --host 127.0.0.1 --port 8080 --path /acp
 agentprism-acp-server --version
 ```
 
+`--host`, `--port`, and `--path` apply only with `--http`; their defaults are `127.0.0.1`, `7331`,
+and `/acp`. Each accepted HTTP or WebSocket connection has an independent discovery/backend mode
+and pinned downstream connection.
+
 The server accepts only clients that negotiate AgentPrism router extension version 1 under
 `clientCapabilities._meta["@automatalabs/agentprism"].acpRouter`.
 
@@ -72,17 +78,283 @@ proxy stores no session-routing table.
 Built-in backend IDs are `claude`, `codex`, `opencode`, and `pi`. Custom backends use the existing
 `AGENTPRISM_BACKENDS` registry.
 
+## Using the official TypeScript client SDK
+
+Install the router, the official ACP TypeScript SDK, and a TypeScript runner:
+
+```bash
+pnpm add @automatalabs/acp-server @agentclientprotocol/sdk ws
+pnpm add --save-dev tsx @types/node @types/ws
+```
+
+The following examples are consecutive sections of one `router-client.ts` file. They follow the
+official SDK's [current client example](https://github.com/agentclientprotocol/typescript-sdk/blob/main/src/examples/client.ts):
+`client(...).onRequest(...).connectWith(...)`, `ctx.request(...)`, and the
+`buildSession(...).withSession(...)` active-session API. The stdio helper starts a fresh
+`agentprism-acp-server` process for each connection. The example permission handler rejects
+safely; replace it with the application's actual user-confirmation UI.
+
+### Shared client and stdio setup
+
+```ts
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { createHttpStream } from "@agentclientprotocol/sdk/experimental/http-client";
+import { createWebSocketStream } from "@agentclientprotocol/sdk/experimental/ws-client";
+import { WebSocket } from "ws";
+
+const ROUTER_NAMESPACE = "@automatalabs/agentprism";
+const PROBE_METHOD = "_automatalabs/agentprism/backends/probe";
+
+type ProbeBackendsParams = {
+  cwd: string;
+  additionalDirectories?: string[];
+  mcpServers: acp.McpServer[];
+  _meta?: Record<string, unknown> | null;
+};
+
+type BackendProbe =
+  | {
+      id: string;
+      name: string;
+      available: true;
+      agentInfo?: acp.Implementation | null;
+      agentCapabilities?: acp.AgentCapabilities;
+      modes?: acp.SessionModeState | null;
+      configOptions?: acp.SessionConfigOption[] | null;
+      initializeMeta?: Record<string, unknown> | null;
+      sessionMeta?: Record<string, unknown> | null;
+    }
+  | {
+      id: string;
+      name: string;
+      available: false;
+      stage: "initialize" | "session/new";
+      error: string;
+    };
+
+type ProbeBackendsResult = { backends: BackendProbe[] };
+
+class RouterClient implements acp.Client {
+  async requestPermission(
+    params: acp.RequestPermissionRequest,
+  ): Promise<acp.RequestPermissionResponse> {
+    const reject = params.options.find(
+      (option) => option.kind === "reject_once" || option.kind === "reject_always",
+    );
+    return reject
+      ? { outcome: { outcome: "selected", optionId: reject.optionId } }
+      : { outcome: { outcome: "cancelled" } };
+  }
+
+  async sessionUpdate(params: acp.SessionNotification): Promise<void> {
+    const update = params.update;
+    if (
+      update.sessionUpdate === "agent_message_chunk" &&
+      update.content.type === "text"
+    ) {
+      process.stdout.write(update.content.text);
+    } else {
+      console.error(`[${update.sessionUpdate}]`);
+    }
+  }
+}
+
+const client = new RouterClient();
+
+function initializeRequest(
+  mode: "discovery" | "backend",
+  backend?: string,
+): acp.InitializeRequest {
+  return {
+    protocolVersion: acp.PROTOCOL_VERSION,
+    clientInfo: { name: "agentprism-router-example", version: "1.0.0" },
+    clientCapabilities: {
+      _meta: {
+        [ROUTER_NAMESPACE]: {
+          acpRouter: { versions: [1] },
+        },
+      },
+    },
+    _meta: {
+      [ROUTER_NAMESPACE]: {
+        acpRouter:
+          mode === "discovery"
+            ? { version: 1, mode }
+            : { version: 1, mode, backend },
+      },
+    },
+  };
+}
+
+async function withRouter<T>(
+  operation: (ctx: acp.ClientContext) => Promise<T>,
+): Promise<T> {
+  const pnpm = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+  const child = spawn(pnpm, ["exec", "agentprism-acp-server"], {
+    stdio: ["pipe", "pipe", "inherit"],
+  });
+  if (!child.stdin || !child.stdout) throw new Error("router stdio unavailable");
+
+  const stream = acp.ndJsonStream(
+    Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+  );
+
+  try {
+    return await connectRouter(stream, operation);
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  }
+}
+
+function connectRouter<T>(
+  stream: acp.Stream,
+  operation: (ctx: acp.ClientContext) => Promise<T>,
+): Promise<T> {
+  return acp
+    .client({ name: "agentprism-router-example" })
+    .onRequest(acp.methods.client.session.requestPermission, (ctx) =>
+      client.requestPermission(ctx.params),
+    )
+    .connectWith(stream, operation);
+}
+
+async function withNetworkRouter<T>(
+  transport: "http" | "websocket",
+  operation: (ctx: acp.ClientContext) => Promise<T>,
+): Promise<T> {
+  const stream =
+    transport === "http"
+      ? createHttpStream("http://127.0.0.1:7331/acp")
+      : createWebSocketStream("ws://127.0.0.1:7331/acp", { WebSocket });
+  try {
+    return await connectRouter(stream, operation);
+  } finally {
+    await stream.writable.close().catch(() => undefined);
+  }
+}
+
+function withConfiguredRouter<T>(
+  operation: (ctx: acp.ClientContext) => Promise<T>,
+): Promise<T> {
+  const transport = process.env.ACP_TRANSPORT ?? "stdio";
+  if (transport === "stdio") return withRouter(operation);
+  if (transport === "http" || transport === "websocket") {
+    return withNetworkRouter(transport, operation);
+  }
+  throw new Error(`ACP_TRANSPORT must be stdio, http, or websocket; got ${transport}`);
+}
+```
+
+The network adapters are the same official experimental transport APIs used by the SDK's current
+HTTP server, HTTP client, and WebSocket client examples; the messages negotiated through them
+remain ACP V1.
+
+### Discover configured backends
+
+Discovery uses one initialized connection and the router-owned probe extension. The generic
+`request<Response, Params>()` overload is the official SDK path for custom methods:
+
+```ts
+const cwd = process.cwd();
+
+const { backends } = await withConfiguredRouter(async (ctx) => {
+  await ctx.request(
+    acp.methods.agent.initialize,
+    initializeRequest("discovery"),
+  );
+
+  return ctx.request<ProbeBackendsResult, ProbeBackendsParams>(PROBE_METHOD, {
+    cwd,
+    mcpServers: [],
+  });
+});
+
+for (const backend of backends) {
+  if (backend.available) {
+    console.log(`${backend.id}: available (${backend.agentInfo?.name ?? backend.name})`);
+  } else {
+    console.log(`${backend.id}: unavailable at ${backend.stage}: ${backend.error}`);
+  }
+}
+```
+
+### Pin a backend, create a session, and prompt
+
+Backend operation uses a second initialized connection. The selection is repeated in
+`session/new`; the SDK's active-session helper then sends ordinary ACP traffic without additional
+router metadata. `session.sessionId` is the selected backend's native session ID.
+
+```ts
+const selected = process.argv[2] ?? backends.find((backend) => backend.available)?.id;
+if (!selected) throw new Error("No configured backend is available");
+
+await withConfiguredRouter(async (ctx) => {
+  const initialized = await ctx.request(
+    acp.methods.agent.initialize,
+    initializeRequest("backend", selected),
+  );
+  console.log(`Connected to ${selected} using ACP v${initialized.protocolVersion}`);
+
+  await ctx
+    .buildSession({
+      cwd,
+      mcpServers: [],
+      _meta: {
+        [ROUTER_NAMESPACE]: {
+          acpRouter: { version: 1, backend: selected },
+        },
+      },
+    })
+    .withSession(async (session) => {
+      console.log(`Native backend session: ${session.sessionId}`);
+      session.prompt("Summarize this repository in three bullets.");
+
+      for (;;) {
+        const message = await session.nextUpdate();
+        if (message.kind === "stop") {
+          console.log(`\nStop reason: ${message.stopReason}`);
+          return message.response;
+        }
+
+        await client.sessionUpdate(message.notification);
+      }
+    });
+});
+```
+
+Run the file over stdio, or start `agentprism-acp-server --http` and select a network transport:
+
+```bash
+pnpm exec tsx router-client.ts codex
+ACP_TRANSPORT=http pnpm exec tsx router-client.ts codex
+ACP_TRANSPORT=websocket pnpm exec tsx router-client.ts codex
+```
+
 ## Library API
 
 ```ts
-import { serveAcpServer } from "@automatalabs/acp-server";
+import {
+  listenAcpHttpServer,
+  serveAcpServer,
+} from "@automatalabs/acp-server";
 
-await serveAcpServer();
+await serveAcpServer(); // one stdio connection
+
+const server = await listenAcpHttpServer({
+  host: "127.0.0.1",
+  port: 7331,
+  path: "/acp",
+});
+console.log(server.url, server.webSocketUrl);
+await server.close();
 ```
 
 Embedding hosts can pass a custom ACP `stream`, custom backend registrations, exact `targets`, a
-version string, and an abort signal through `ServeAcpServerOptions`. The package also exports the
-router constants, request parsers, response helpers, probe types, and backend-target resolver.
-
-Authentication, authorization, workspace policy, HTTP, WebSocket, and ACP V2 are outside this
-package.
+version string, and an abort signal through `ServeAcpServerOptions`. `ListenAcpHttpServerOptions`
+adds `host`, `port`, `path`, and `maxRequestBodyBytes`; the returned handle exposes the bound URLs,
+a `closed` promise, and idempotent `close()`. The package also exports the default network listener
+constants, router constants, request parsers, response helpers, probe types, and backend-target
+resolver.

package/dist/cli.js

@@ -5,6 +5,17 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${manifest.version}\n`);
     process.exit(0);
 }
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    process.stdout.write(`Usage:
+  agentprism-acp-server
+  agentprism-acp-server --http [--host <host>] [--port <port>] [--path <path>]
+
+With no transport flag, the server speaks ACP over stdio. --http starts both
+Streamable HTTP and WebSocket transports on one endpoint (default:
+http://127.0.0.1:7331/acp and ws://127.0.0.1:7331/acp).
+`);
+    process.exit(0);
+}
 console.log = console.error;
 console.info = console.error;
 console.warn = console.error;
@@ -16,8 +27,23 @@ const abortController = new AbortController();
 process.once("SIGTERM", () => abortController.abort(new Error("SIGTERM")));
 process.once("SIGINT", () => abortController.abort(new Error("SIGINT")));
 try {
-    const { serveAcpServer } = await import("./server.js");
-    await serveAcpServer({ signal: abortController.signal });
+    const options = parseCliOptions(process.argv.slice(2));
+    if (options.mode === "stdio") {
+        const { serveAcpServer } = await import("./server.js");
+        await serveAcpServer({ signal: abortController.signal });
+    }
+    else {
+        const { listenAcpHttpServer } = await import("./http-server.js");
+        const server = await listenAcpHttpServer({
+            host: options.host,
+            port: options.port,
+            path: options.path,
+            signal: abortController.signal,
+        });
+        console.error(`ACP Streamable HTTP endpoint listening at ${server.url}`);
+        console.error(`ACP WebSocket endpoint listening at ${server.webSocketUrl}`);
+        await server.closed;
+    }
 }
 catch (error) {
     if (!abortController.signal.aborted) {
@@ -25,4 +51,64 @@ catch (error) {
         process.exitCode = 1;
     }
 }
+function parseCliOptions(args) {
+    let http = false;
+    let host = "127.0.0.1";
+    let port = 7331;
+    let path = "/acp";
+    let networkOption = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--http") {
+            http = true;
+            continue;
+        }
+        if (argument === "--host" || argument === "--port" || argument === "--path") {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`${argument} requires a value`);
+            }
+            networkOption = true;
+            index += 1;
+            if (argument === "--host")
+                host = value;
+            if (argument === "--path")
+                path = value;
+            if (argument === "--port")
+                port = parsePort(value);
+            continue;
+        }
+        if (argument.startsWith("--host=")) {
+            host = argument.slice("--host=".length);
+            networkOption = true;
+            continue;
+        }
+        if (argument.startsWith("--port=")) {
+            port = parsePort(argument.slice("--port=".length));
+            networkOption = true;
+            continue;
+        }
+        if (argument.startsWith("--path=")) {
+            path = argument.slice("--path=".length);
+            networkOption = true;
+            continue;
+        }
+        throw new Error(`unknown argument ${JSON.stringify(argument)}; run with --help for usage`);
+    }
+    if (!http) {
+        if (networkOption)
+            throw new Error("--host, --port, and --path require --http");
+        return { mode: "stdio" };
+    }
+    return { mode: "http", host, port, path };
+}
+function parsePort(value) {
+    if (!/^\d+$/.test(value))
+        throw new Error("--port must be an integer from 0 through 65535");
+    const port = Number(value);
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65_535) {
+        throw new Error("--port must be an integer from 0 through 65535");
+    }
+    return port;
+}
 export {};

package/dist/http-server.d.ts

@@ -0,0 +1,41 @@
+import type { CustomBackendConfig } from "@automatalabs/acp-agents";
+import { type BackendTarget } from "./backends.js";
+export declare const DEFAULT_ACP_HTTP_HOST: "127.0.0.1";
+export declare const DEFAULT_ACP_HTTP_PORT: 7331;
+export declare const DEFAULT_ACP_HTTP_PATH: "/acp";
+export interface ListenAcpHttpServerOptions {
+    /** Interface to bind. Defaults to loopback. */
+    host?: string;
+    /** TCP port to bind. Pass zero to allocate an ephemeral port. */
+    port?: number;
+    /** Exact HTTP and WebSocket endpoint path. Defaults to /acp. */
+    path?: string;
+    /** Maximum JSON request body accepted by the Streamable HTTP adapter. */
+    maxRequestBodyBytes?: number;
+    /** Programmatic custom backends merged over AGENTPRISM_BACKENDS. */
+    backends?: Record<string, CustomBackendConfig>;
+    /** Exact backend targets, primarily for embedding and deterministic tests. */
+    targets?: readonly BackendTarget[];
+    /** Package version advertised on discovery connections. */
+    version?: string;
+    /** Stops the listener and every active transport connection when aborted. */
+    signal?: AbortSignal;
+}
+export interface AcpHttpServerHandle {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    readonly url: string;
+    readonly webSocketUrl: string;
+    readonly closed: Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Listen for ACP V1 Streamable HTTP and WebSocket connections on one endpoint.
+ *
+ * Each accepted transport connection receives an independent connection-pinned router. The
+ * experimental SDK surface used here is the official ACP HTTP/WebSocket transport implementation;
+ * the router protocol carried over it remains ACP V1.
+ */
+export declare function listenAcpHttpServer(options?: ListenAcpHttpServerOptions): Promise<AcpHttpServerHandle>;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAG1E,eAAO,MAAM,qBAAqB,EAAG,WAAoB,CAAC;AAC1D,eAAO,MAAM,qBAAqB,EAAG,IAAa,CAAC;AACnD,eAAO,MAAM,qBAAqB,EAAG,MAAe,CAAC;AAErD,MAAM,WAAW,0BAA0B;IACzC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,mBAAmB,CAAC,CA8H9B"}

package/dist/http-server.js

@@ -0,0 +1,200 @@
+import { createServer } from "node:http";
+import { AcpServer } from "@agentclientprotocol/sdk/experimental/server";
+import { createNodeHttpHandler, createNodeWebSocketUpgradeHandler, } from "@agentclientprotocol/sdk/experimental/node";
+import { WebSocketServer } from "ws";
+import { resolveBackendTargets } from "./backends.js";
+import { serveAcpServer } from "./server.js";
+export const DEFAULT_ACP_HTTP_HOST = "127.0.0.1";
+export const DEFAULT_ACP_HTTP_PORT = 7331;
+export const DEFAULT_ACP_HTTP_PATH = "/acp";
+/**
+ * Listen for ACP V1 Streamable HTTP and WebSocket connections on one endpoint.
+ *
+ * Each accepted transport connection receives an independent connection-pinned router. The
+ * experimental SDK surface used here is the official ACP HTTP/WebSocket transport implementation;
+ * the router protocol carried over it remains ACP V1.
+ */
+export async function listenAcpHttpServer(options = {}) {
+    options.signal?.throwIfAborted();
+    const host = requireHost(options.host ?? DEFAULT_ACP_HTTP_HOST);
+    const port = requirePort(options.port ?? DEFAULT_ACP_HTTP_PORT);
+    const path = requirePath(options.path ?? DEFAULT_ACP_HTTP_PATH);
+    const targets = options.targets
+        ? [...options.targets]
+        : resolveBackendTargets({ backends: options.backends });
+    requireUniqueTargets(targets);
+    const transportServer = new AcpServer({
+        createAgent: () => ({
+            connect(stream) {
+                // AcpServer exposes a batch-capable transport stream so it can also host draft ACP V2.
+                // This router rejects non-V1 initialize requests, after which the SDK guarantees that V1
+                // connections contain individual messages only.
+                const closed = serveAcpServer({
+                    stream: stream,
+                    targets,
+                    ...(options.version === undefined ? {} : { version: options.version }),
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                }).catch((error) => {
+                    // One failed client connection must not become a process-level unhandled rejection or
+                    // stop the shared listener. AcpServer observes this lifecycle promise to tear down only
+                    // the affected transport connection.
+                    console.error("ACP network connection failed:", error);
+                });
+                return { closed };
+            },
+        }),
+    });
+    const httpHandler = createNodeHttpHandler(transportServer, {
+        ...(options.maxRequestBodyBytes === undefined
+            ? {}
+            : { maxRequestBodyBytes: options.maxRequestBodyBytes }),
+    });
+    const webSocketServer = new WebSocketServer({ noServer: true });
+    const upgradeHandler = createNodeWebSocketUpgradeHandler(transportServer, webSocketServer);
+    const httpServer = createServer((request, response) => {
+        if (!isAcpPath(request, path)) {
+            notFound(response);
+            return;
+        }
+        httpHandler(request, response);
+    });
+    httpServer.on("upgrade", (request, socket, head) => {
+        if (!isAcpPath(request, path)) {
+            socket.destroy();
+            return;
+        }
+        upgradeHandler(request, socket, head);
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            httpServer.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            httpServer.off("error", onError);
+            resolve();
+        };
+        httpServer.once("error", onError);
+        httpServer.once("listening", onListening);
+        httpServer.listen(port, host);
+    });
+    const address = httpServer.address();
+    if (!isAddressInfo(address)) {
+        await closeNodeServer(httpServer).catch(() => undefined);
+        await transportServer.close();
+        throw new Error("ACP HTTP server did not bind to a TCP address");
+    }
+    let resolveClosed;
+    let rejectClosed;
+    const closed = new Promise((resolve, reject) => {
+        resolveClosed = resolve;
+        rejectClosed = reject;
+    });
+    closed.catch(() => { });
+    let closePromise;
+    let runtimeError;
+    const close = () => {
+        closePromise ??= (async () => {
+            options.signal?.removeEventListener("abort", onAbort);
+            const stopListening = closeNodeServer(httpServer);
+            const results = await Promise.allSettled([
+                transportServer.close(),
+                stopListening,
+            ]);
+            for (const client of webSocketServer.clients)
+                client.terminate();
+            await closeWebSocketServer(webSocketServer).catch((error) => {
+                results.push({ status: "rejected", reason: error });
+            });
+            const errors = results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (runtimeError !== undefined)
+                errors.unshift(runtimeError);
+            if (errors.length > 0)
+                throw new AggregateError(errors, "Failed to close ACP HTTP server");
+        })();
+        closePromise.then(resolveClosed, rejectClosed);
+        return closePromise;
+    };
+    const onAbort = () => {
+        void close();
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    httpServer.on("error", (error) => {
+        runtimeError = error;
+        void close();
+    });
+    if (options.signal?.aborted)
+        void close();
+    const endpointHost = formatUrlHost(host);
+    return {
+        host,
+        port: address.port,
+        path,
+        url: `http://${endpointHost}:${address.port}${path}`,
+        webSocketUrl: `ws://${endpointHost}:${address.port}${path}`,
+        closed,
+        close,
+    };
+}
+function requireHost(value) {
+    const host = value.trim();
+    if (host.length === 0)
+        throw new TypeError("ACP HTTP host must not be empty");
+    return host;
+}
+function requirePort(value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 65_535) {
+        throw new RangeError("ACP HTTP port must be an integer from 0 through 65535");
+    }
+    return value;
+}
+function requirePath(value) {
+    if (!value.startsWith("/") || value.includes("?") || value.includes("#")) {
+        throw new TypeError("ACP HTTP path must be an absolute path without a query or fragment");
+    }
+    const parsed = new URL(value, "http://localhost");
+    if (parsed.pathname !== value) {
+        throw new TypeError("ACP HTTP path must be a canonical URL path");
+    }
+    return value;
+}
+function requireUniqueTargets(targets) {
+    const ids = new Set(targets.map((target) => target.id));
+    if (ids.size !== targets.length)
+        throw new Error("ACP backend target ids must be unique");
+}
+function isAcpPath(request, path) {
+    return new URL(request.url ?? "/", "http://localhost").pathname === path;
+}
+function notFound(response) {
+    response.writeHead(404, { "Content-Type": "text/plain" });
+    response.end("Not Found");
+}
+function isAddressInfo(value) {
+    return value !== null && typeof value === "object";
+}
+function formatUrlHost(host) {
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function closeNodeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+function closeWebSocketServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { serveAcpServer } from "./server.js";
 export type { ServeAcpServerOptions } from "./server.js";
+export { DEFAULT_ACP_HTTP_HOST, DEFAULT_ACP_HTTP_PATH, DEFAULT_ACP_HTTP_PORT, listenAcpHttpServer, } from "./http-server.js";
+export type { AcpHttpServerHandle, ListenAcpHttpServerOptions } from "./http-server.js";
 export { resolveBackendTargets } from "./backends.js";
 export type { BackendTarget, ResolveBackendTargetsOptions } from "./backends.js";
 export { ACP_BACKENDS_PROBE_METHOD, ACP_ROUTER_META_NAMESPACE, ACP_ROUTER_VERSION, assertSessionBackend, discoveryInitializeResponse, mergeBackendInitializeResponse, parseProbeBackendsParams, parseRouterInitialize, } from "./protocol.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,8BAA8B,EAC9B,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,8BAA8B,EAC9B,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { serveAcpServer } from "./server.js";
+export { DEFAULT_ACP_HTTP_HOST, DEFAULT_ACP_HTTP_PATH, DEFAULT_ACP_HTTP_PORT, listenAcpHttpServer, } from "./http-server.js";
 export { resolveBackendTargets } from "./backends.js";
 export { ACP_BACKENDS_PROBE_METHOD, ACP_ROUTER_META_NAMESPACE, ACP_ROUTER_VERSION, assertSessionBackend, discoveryInitializeResponse, mergeBackendInitializeResponse, parseProbeBackendsParams, parseRouterInitialize, } from "./protocol.js";

package/dist/server.d.ts

@@ -13,6 +13,6 @@ export interface ServeAcpServerOptions {
     /** Closes the active outer and downstream connections when aborted. */
     signal?: AbortSignal;
 }
-/** Serve one connection-pinned AgentPrism ACP stdio connection until either side closes. */
+/** Serve one connection-pinned AgentPrism ACP V1 stream until either side closes. */
 export declare function serveAcpServer(options?: ServeAcpServerOptions): Promise<void>;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAYL,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB1E,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4FAA4F;AAC5F,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiEvF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAYL,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB1E,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qFAAqF;AACrF,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiEvF"}

package/dist/server.js

@@ -4,7 +4,7 @@ import { Readable, Writable } from "node:stream";
 import { resolveBackendTargets } from "./backends.js";
 import { ACP_BACKENDS_PROBE_METHOD, assertSessionBackend, discoveryInitializeResponse, isRecord, mergeBackendInitializeResponse, parseProbeBackendsParams, parseRouterInitialize, } from "./protocol.js";
 import { RawRpcPeer, errorResponse } from "./raw-rpc.js";
-/** Serve one connection-pinned AgentPrism ACP stdio connection until either side closes. */
+/** Serve one connection-pinned AgentPrism ACP V1 stream until either side closes. */
 export async function serveAcpServer(options = {}) {
     const stream = options.stream ?? stdioStream();
     const targets = options.targets ? [...options.targets] : resolveBackendTargets({ backends: options.backends });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-server",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -31,7 +31,11 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.4.0",
-    "@automatalabs/acp-agents": "1.1.0"
+    "ws": "^8.21.3",
+    "@automatalabs/acp-agents": "1.1.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
   },
   "scripts": {
     "build": "tsc -b",