Plan Webchat migration to ACP v2

[philz3906]

Summary

Track a future migration of AgentConnect Webchat from its current custom browser wire protocol to ACP v2.

The target should be ACP v2 for standard session and agent semantics, plus a thin AgentConnect remote profile for product-specific authorization, routing, idempotency, and bounded reconnect recovery. This is a tracking/design issue, not a request to replace the current protocol before ACP v2 and its remote transport are ready.

Motivation

The current Webchat protocol mirrors a constrained ACP session:

• user turns map to prompts;
• message, thought, tool-call, tool-update, title, usage, and state changes are projected from ACP updates;
• model, reasoning effort, permission mode, and fast mode mirror ACP session config options;
• cancel and close mirror ACP session lifecycle operations.

Maintaining a second application-level event model creates duplicated schemas and translation code across the daemon, relay, protocol package, and Web UI. ACP v2 is a better long-term semantic foundation because it supports session-owned updates outside the lifetime of a prompt request, message IDs, message upserts/chunks, session state, configuration options, usage/cost, permissions, and replayable session history.

As of 2026-08-02, the official experimental TypeScript SDK provides the v2 API and experimental HTTP/WebSocket transports, but it does not yet provide the complete reliability contract Webchat currently needs: transport replay IDs, incremental stream resumption, automatic reconnect, WebSocket liveness, prompt/turn IDs, gap detection, or generation fencing.

Architectural invariants

Any migration must preserve the daemon-centric architecture:

• The Control Plane remains off the message hot path.
• The CP may mint short-lived authorization tokens and persist only the conversation ownership tuple.
• Browser content continues through the relay directly to the owning daemon.
• The relay does not persist message bodies, attachment bytes, or ACP update streams.
• Reconnect replay remains bounded and volatile; this does not introduce a durable offline inbox.
• Rolling deployments must fail closed rather than silently weaken conversation ownership or replay fencing.

Proposed protocol split

ACP v2 core

Use standard ACP v2 methods and types where they provide the required semantics:

• initialization and capability negotiation;
• session creation/resume/close;
• prompt acceptance;
• user, agent, and thought messages;
• tool calls, permissions, plans, and state updates;
• session config options;
• usage, cost, title, cancellation, and stop reasons;
• supported content blocks, including bounded image input.

AgentConnect remote profile

Keep only the concerns that are outside ACP v2 or are not yet standardized:

• token-bound authorization for orgId, userId, agentId, and conversationId;
• daemon placement and relay routing;
• browser-generated clientTurnId and prompt idempotency;
• per-stream sequencing and an incremental replay cursor;
• reconnect generation fencing;
• bounded replay-window limits;
• explicit stale, not-found, gap, and overflow outcomes;
• structured admission outcomes such as busy, paused, draining, queued, and no-agent;
• attachment limits and remote-MCP entitlement policy.

Prefer ACP extension points such as namespaced _meta, extension capabilities, custom cursor variants, or typed extension errors over a parallel message/event model.

Readiness criteria

Do not cut over solely because an SDK exports an experimental v2 namespace. Re-evaluate migration when:

• The ACP v2 wire format has a usable compatibility commitment.
• The remote HTTP/WebSocket transport is sufficiently specified for browser use.
• Transport event IDs and incremental replay/resumption semantics are defined.
• Keepalive, liveness detection, and reconnect behavior are defined or deliberately owned by AgentConnect.
• The TypeScript SDK implements the required transport behavior, or the remaining owned profile is explicitly scoped.
• Supported ACP agents/adapters can speak v2, or the daemon has a tested v1↔v2 compatibility boundary.
• Browser authentication and origin handling are designed for both HTTP and WebSocket transports.

Migration outline

1. Maintain a feature-parity matrix between the current Webchat contract and ACP v2.
2. Define and document the minimal AgentConnect remote profile.
3. Add protocol-version/capability negotiation and a dual-stack compatibility period.
4. Implement the v2 adapter without moving content through the CP.
5. Verify prompt admission, exact turn correlation, cancellation, config updates, bounded replay, stale-connection fencing, and rolling-version behavior.
6. Remove the legacy Webchat event model only after all supported browser/relay/daemon version combinations have a safe migration path.

Acceptance criteria

• A design document records the selected ACP v2 version, minimum SDK version, and AgentConnect extension profile.
• Every current Webchat operation and output has a standard ACP mapping or a documented extension.
• Duplicate/retried prompts cannot execute twice.
• A reconnecting browser can recover the missing live tail or receive an explicit bounded-replay failure.
• Missing or out-of-order output cannot be rendered as a completed turn.
• Conversation ownership and daemon placement are never inferred from browser-supplied session IDs.
• No message content, attachment bytes, or ACP stream is persisted by the relay or Control Plane.
• The rollout supports mixed versions and fails closed on incompatible peers.

References

• ACP v2 draft overview
• ACP Streamable HTTP & WebSocket transport RFD
• Official TypeScript SDK experimental exports
• Current Webchat frames
• Current relay Webchat operations
• Current browser stream ordering
• Relay architecture and Webchat reconnect semantics