[WIP] Add experimental HTTP backend SPI

package.json

@@ -45,6 +45,11 @@
       "import": "./dist/server.js",
       "default": "./dist/server.js"
     },
+    "./experimental/http-backend": {
+      "types": "./dist/http-backend.d.ts",
+      "import": "./dist/http-backend.js",
+      "default": "./dist/http-backend.js"
+    },
     "./experimental/node": {
       "types": "./dist/node-adapter.d.ts",
       "import": "./dist/node-adapter.js",

src/acp.ts

@@ -15,6 +15,7 @@ export type {
   AnyRequest,
   AnyResponse,
   ErrorResponse,
+  JsonRpcRequestIdGenerator,
   MaybePromise,
   Result,
   SendRequestOptions,
@@ -29,6 +30,7 @@ import type {
   HandleResult,
   IncomingMessage,
   JsonRpcHandler,
+  JsonRpcRequestIdGenerator,
   MaybePromise,
   SendRequestOptions,
 } from "./jsonrpc.js";
@@ -184,6 +186,16 @@ export interface ClientConnection extends AcpConnection {
   readonly agent: ClientContext;
 }
 
+export interface AcpConnectionOptions {
+  /**
+   * Allocates IDs for JSON-RPC requests sent by this app-side connection.
+   *
+   * Most users should not need this. HTTP server integrations use it to keep
+   * server-originated request IDs unique across distributed server instances.
+   */
+  readonly requestIdGenerator?: JsonRpcRequestIdGenerator;
+}
+
 class AcpContext {
   /** @internal */
   constructor(private readonly cx: ConnectionContext) {}
@@ -1675,7 +1687,7 @@ const appBuilder = Symbol("appBuilder");
 const runAgentConnectHandlers = Symbol("runAgentConnectHandlers");
 const runClientConnectHandlers = Symbol("runClientConnectHandlers");
 
-type AppConnectOptions = {
+type AppConnectOptions = AcpConnectionOptions & {
   readonly deferConnectHandlers?: boolean;
 };
 
@@ -1746,7 +1758,6 @@ export class AgentApp {
   ): AgentConnection {
     return this.connectConnection(target, options).connection;
   }
-
   /**
    * Connects this agent app to a transport stream for the lifetime of `op`.
    *
@@ -1756,6 +1767,7 @@ export class AgentApp {
   connectWith<T>(
     stream: Stream,
     op: (context: AgentContext) => MaybePromise<T>,
+    options?: AcpConnectionOptions,
   ): Promise<T>;
   /**
    * Connects this agent app directly to a client app for the lifetime of `op`.
@@ -1767,8 +1779,12 @@ export class AgentApp {
   connectWith<T>(
     target: Stream | ClientApp,
     op: (context: AgentContext) => MaybePromise<T>,
+    options: AppConnectOptions = {},
   ): Promise<T> {
-    const { rawConnection, connection } = this.connectConnection(target);
+    const { rawConnection, connection } = this.connectConnection(
+      target,
+      options,
+    );
     return rawConnection.runUntil(() => op(connection.client));
   }
 
@@ -1901,7 +1917,7 @@ export class AgentApp {
     options: AppConnectOptions = {},
   ): AgentConnectionState {
     if (isStream(target)) {
-      const state = this.openStreamConnection(target);
+      const state = this.openStreamConnection(target, options);
       if (!options.deferConnectHandlers) {
         this[runAgentConnectHandlers](state.connection);
       }
@@ -1925,8 +1941,13 @@ export class AgentApp {
     return state;
   }
 
-  private openStreamConnection(stream: Stream): AgentConnectionState {
-    const rawConnection = this.builder.connect(stream);
+  private openStreamConnection(
+    stream: Stream,
+    options: AcpConnectionOptions = {},
+  ): AgentConnectionState {
+    const rawConnection = this.builder.connect(stream, {
+      requestIdGenerator: options.requestIdGenerator,
+    });
     return {
       rawConnection,
       connection: agentConnection(rawConnection, this.connectHandlers),
@@ -2542,10 +2563,14 @@ export class AgentSideConnection {
    *
    * @deprecated Prefer `agent({ name }).connect(stream)`.
    */
-  constructor(toAgent: (conn: AgentSideConnection) => Agent, stream: Stream) {
+  constructor(
+    toAgent: (conn: AgentSideConnection) => Agent,
+    stream: Stream,
+    options?: AcpConnectionOptions,
+  ) {
     this.connection = legacyAgentApp(toAgent(this))
       [appBuilder]()
-      .connect(stream);
+      .connect(stream, options);
   }
 
   /**