Skip to content

[WIP] Add experimental HTTP backend SPI#198

Draft
federicociner wants to merge 2 commits into
agentclientprotocol:mainfrom
federicociner:feat/http-backend-spi
Draft

[WIP] Add experimental HTTP backend SPI#198
federicociner wants to merge 2 commits into
agentclientprotocol:mainfrom
federicociner:feat/http-backend-spi

Conversation

@federicociner

@federicociner federicociner commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR adds an experimental httpBackend SPI to the TypeScript SDK’s AcpServer. The motivation is to make the Streamable HTTP transport implementation deployable in the same kinds of environments the RFD is targeting: remote ACP servers behind normal HTTP load balancers, potentially with many stateless web nodes.

Today, the SDK’s HTTP transport state is process-local. Acp-Connection-Id effectively points into an in-memory ConnectionRegistry, which owns the connection metadata, SSE streams, replay buffers, pending response-route maps, and server→client request correlation state. That is fine for a single process, but it means a client that initializes on node A must keep hitting node A for subsequent POST, GET SSE, and DELETE requests. That makes Streamable HTTP much less useful for cloud/server deployments unless the deployment provides perfect stickiness.

The RFD already describes Streamable HTTP as a remote transport with connection-scoped and session-scoped SSE streams, where most POSTs return 202 Accepted and the actual JSON-RPC response is later delivered on the appropriate stream. It also notes that deployments may preserve affinity using cookies or supply their own affinity/state via an external store such as Redis.

Concretely, the SPI lets the SDK server delegate HTTP transport state to a backend while keeping the public wire protocol unchanged:

  • connection mint/load/touch/close
  • connected POST acceptance
  • connection-level and session-level stream opening
  • response routing for server→client requests
  • injectable server-originated JSON-RPC request ID generation

That last point matters because server → client requests such as permission requests, elicitation, terminal, and filesystem methods need request IDs that do not collide if multiple web nodes can originate messages for the same logical ACP connection.

Importantly, this is not a protocol fork and does not change client behavior. A stock ACP HTTP client still sees the same initialize, Acp-Connection-Id, POST 202, GET SSE, and DELETE behavior described by the RFD. The default SDK behavior also remains in-memory, so simple/local deployments keep working as before. WebSocket upgrades remain on the existing in-memory full-duplex path, which preserves the RFD’s simpler WebSocket deployment story.

The main benefit is that SDK users can choose the right operational model:

  • single-process or sticky deployments can use the default in-memory backend
  • horizontally scaled streamable HTTP deployments can provide a distributed backend

@federicociner federicociner marked this pull request as draft June 23, 2026 06:30
@federicociner federicociner force-pushed the feat/http-backend-spi branch from c36d6fc to 2bfed85 Compare June 23, 2026 06:40
@federicociner federicociner changed the title Add experimental HTTP backend SPI [WIP] Add experimental HTTP backend SPI Jun 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant