Real-world feedback: session/resume Preview works for browser-bridge use case

[Alemusica]

Draft issue per agentclientprotocol/agent-client-protocol

Tipo: GitHub issue (post-Preview feedback). Riferimenti: tracking #984
(closed), PR #969 (Move to Preview, merged), PR #324 (draft impl, merged).

---

Title

Real-world feedback: session/resume Preview works for browser-bridge use case (claude-agent-acp 0.31.4)

Body

Filing this as concrete feedback after exercising the session/resume
Preview spec end-to-end against @agentclientprotocol/claude-agent-acp@0.31.4,
in the hope it's useful before stabilization.

Use case

Browser-side embedded chat panel inside a SaaS app (ricchexxa,
B2B finance tool). Architecture:

Browser (React)  ⟷  WebSocket  ⟷  local Node bridge  ⟷  stdio JSON-RPC  ⟷  claude-agent-acp

The bridge is a long-running process that brokers between many short-lived
browser tabs and one stable agent session. Browser tabs come and go on
refresh; the bridge restarts on code changes; the agent subprocess and
its session need to survive both. The "stessa sessione" requirement from
the user is the one thing that makes the in-app assistant feel different
from a fresh chat.

What I tested (and what passed)

The flow that the spec calls out as the canonical "preserve conversation
across reconnects" works:

1. Start bridge → session/new → persist sessionId to disk
2. Send a prompt ("remember tag X") → agent replies → done
3. SIGKILL bridge process (clean cold start, no graceful shutdown)
4. Restart bridge → read persisted sessionId → call session/load (with
   capability agentCapabilities.loadSession=true)
5. Browser reconnects via WS, sends "what tag did I tell you?"
6. Agent replies with the exact tag from step 2 — context preserved

(I'm using session/load rather than the new session/resume for now
because v0.31.4 of the agent doesn't yet expose resume in the wire
protocol; happy to retest once it does.)

Two things I'd like to flag for stabilization

1. The session/load vs session/resume migration story for clients.

For a wrapper that already gets session/load working (with replay), what
is the recommended path: stay on load indefinitely, or migrate to
resume once available and synthesize the replay client-side from a
local message log? The Preview spec section is clear on the agent side
but reads ambiguous on the client/wrapper side.

A short paragraph in docs/protocol/draft/session-setup.mdx saying
"Clients SHOULD prefer X when Y" would prevent silent fragmentation
between SDK consumers.

2. Capability discovery before reconnection.

In a browser-bridge topology, the bridge does the initialize handshake
on startup, before any browser is connected. By the time the user opens
the chat panel, the bridge already needs to know whether to advertise
"resumable history" UX to the user (e.g. a "continue previous session"
button). Today this means the bridge has to remember agentCapabilities
across restarts.

It would help to make capability discovery cacheable — e.g. a stable
agent identity in the InitializeResponse (agent name + version) so
clients can persist capabilities keyed on that identity and avoid a
re-initialize round-trip on every cold start. Probably a separate
small RFD; happy to write it up if there's interest.

What I can offer back

The bridge code is open-source. If a reference implementation that
exercises both session/load and (eventually) session/resume is useful
infrastructure for stabilizing the spec, I can extract it as a standalone
npm package (@flutur/acp-http-bridge or similar) and keep it in step
with the Preview as it evolves. It also doubles as a working pre-impl of
the Streamable HTTP & WebSocket Transport
RFD.

— @Alemusica / flutur

[Alemusica]

Heads up: published the bridge as a standalone npm-style package — https://github.com/Alemusica/acp-http-bridge — alpha but exercises both WebSocket and HTTP/SSE legs of the streamable transport RFD
against a working ACP agent. Happy to keep it aligned with the Preview as it evolves.