feat: proxy() — typed ACP proxies, the TS counterpart of the Rust Proxy role

README.md

@@ -49,6 +49,8 @@ If you're building an [Agent](https://agentclientprotocol.com/protocol/overview#
 
 If you're building a [Client](https://agentclientprotocol.com/protocol/overview#client), start with `client({ name })`, register client-side handlers such as `requestPermission(...)` and `sessionUpdate(...)`, then run your agent workflow with `connectWith(stream, async (ctx) => ...)`.
 
+If you're building something that sits between the two — a logger, an authorization gate, a message transformer — start with `proxy()`. Register typed handlers with `onRequestFromClient(...)` / `onNotificationFromAgent(...)` (the method names say which direction they intercept) just like the agent/client builders, then call `connect({ client, agent })`. Anything you don't claim is forwarded untouched in both directions; handlers can rewrite, answer, or drop messages before they cross.
+
 ### Study a Production Implementation
 
 For a complete, production-ready implementation, check out the [Gemini CLI Agent](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/zed-integration/zedIntegration.ts).

src/acp.ts

@@ -52,6 +52,19 @@ export function ndJsonStream(
   return createJsonStream(output, input);
 }
 
+export { proxy } from "./proxy.js";
+// ProxyBuilder is type-only on purpose: proxy() is the sole factory, so its
+// constructor is not part of the public contract.
+export type {
+  ProxyBuilder,
+  ProxyHandle,
+  ProxyNotificationContext,
+  ProxyNotificationHandler,
+  ProxyRequestContext,
+  ProxyRequestHandler,
+  ProxySideConnection,
+  ProxyStreams,
+} from "./proxy.js";
 export { RequestError } from "./jsonrpc.js";
 export type {
   AnyMessage,
@@ -68,7 +81,6 @@ export type {
 import type { WireStream } from "./stream.js";
 import { Connection, Handled, HandlerRegistration } from "./jsonrpc.js";
 import type {
-  AnyWireMessage,
   ConnectionBuilder,
   ConnectionContext,
   ConnectionOptions,
@@ -93,9 +105,9 @@ function isStream(value: unknown): value is WireStream {
   );
 }
 
-function memoryStreamPair(): [WireStream, WireStream] {
-  const leftToRight = new TransformStream<AnyWireMessage>();
-  const rightToLeft = new TransformStream<AnyWireMessage>();
+function memoryStreamPair(): [Stream, Stream] {
+  const leftToRight = new TransformStream<AnyMessage>();
+  const rightToLeft = new TransformStream<AnyMessage>();
   return [
     {
       readable: rightToLeft.readable,

src/examples/README.md

@@ -4,6 +4,7 @@ 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
+- [`proxy.ts`](./proxy.ts) - A pass-through proxy that wraps any agent command and logs the messages crossing it in both directions
 - [`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`

src/examples/proxy.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+
+import * as acp from "../acp.js";
+
+// A minimal ACP proxy: it presents as an agent on its own stdio, spawns the
+// real agent as a subprocess, and forwards every message between the two
+// while logging traffic to stderr. Point an ACP client (like Zed) at this
+// script exactly as it would run the agent directly — neither side needs to
+// know the proxy is there.
+//
+// Usage: proxy.ts [command args...]
+// Runs the example agent from this directory when no command is given.
+
+function logAndForward(
+  direction: string,
+): acp.ProxyRequestHandler<unknown, unknown> {
+  return ({ method, params, forward }) => {
+    console.error(`[proxy] ${direction} request: ${method}`);
+    return forward(params);
+  };
+}
+
+function logAndForwardNotification(
+  direction: string,
+): acp.ProxyNotificationHandler<unknown> {
+  return async ({ method, params, forward }) => {
+    console.error(`[proxy] ${direction} notification: ${method}`);
+    await forward(params);
+  };
+}
+
+// Spawn the wrapped agent: the command from argv, or the example agent.
+const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
+const exampleAgent = join(dirname(fileURLToPath(import.meta.url)), "agent.ts");
+const [command, ...args] =
+  process.argv.length > 2
+    ? process.argv.slice(2)
+    : [npxCmd, "tsx", exampleAgent];
+const agentProcess = spawn(command, args, {
+  stdio: ["pipe", "pipe", "inherit"],
+});
+
+// "*" catches anything without an exact registration; typed interception is
+// also available, e.g.
+// .onRequestFromClient("session/prompt", async ({ params, forward }) => ...).
+const handle = acp
+  .proxy()
+  .onRequestFromClient("*", logAndForward("client → agent"))
+  .onNotificationFromClient("*", logAndForwardNotification("client → agent"))
+  .onRequestFromAgent("*", logAndForward("agent → client"))
+  .onNotificationFromAgent("*", logAndForwardNotification("agent → client"))
+  .connect({
+    client: acp.ndJsonStream(
+      Writable.toWeb(process.stdout),
+      Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>,
+    ),
+    agent: acp.ndJsonStream(
+      Writable.toWeb(agentProcess.stdin!),
+      Readable.toWeb(agentProcess.stdout!) as ReadableStream<Uint8Array>,
+    ),
+  });
+
+agentProcess.once("exit", () => handle.close());
+await handle.closed;
+agentProcess.kill();

src/jsonrpc.ts

@@ -633,7 +633,12 @@ function requestCancelledError(reason?: unknown): RequestError {
   return RequestError.requestCancelled(reason);
 }
 
-function errorToRequestResult<T>(
+/**
+ * Maps an error thrown while handling a request to a JSON-RPC result:
+ * `RequestError` keeps its code/message/data, an abort after cancellation
+ * maps to request-cancelled, anything else becomes a generic internal error.
+ */
+export function errorToRequestResult<T>(
   error: unknown,
   signal: AbortSignal,
 ): Result<T> {