docs(designs): AHP adoption proposal — webchat-first client session sync (#1339)

[stkevintan]

What

A design document scoping #1339 ("use AHP to unify all session models") down to an incremental, reviewable plan: docs/designs/ahp-adoption.md, plus its docs/README.md index entry. Proposal only — no implementation.

Why

#1339 currently has a one-line vision and a review-bot architecture comment, but no written design answering the questions that comment left open. This doc proposes answers:

• Placement: the daemon is the AHP host, never the CP — AHP traffic is live turn output, i.e. the hot path the CP must stay off of.
• Identity mapping: AHP session id = outwardSessionId; acpSessionId stays daemon-private; the dispatch sessionKey is untouched.
• Fencing correspondence table: each homegrown webchat-transport mechanism (per-turn index, replay ring, resume failure reasons, superseded) mapped to its AHP-native equivalent (serverSeq, snapshot + reducer replay, epoch) — the migration contract for deleting the old machinery.
• Boundary honesty: AHP does not fix the stale-context problem — that is an ACP-layer gap (session/prompt cannot be injected into mid-turn). stageAnswer/webchatRefresh are retained; AHP only standardizes the presentation of a discarded generation.
• Incremental path: Phase 0 shadow reducer on the existing Pending fan-out (no behavior change) → Phase 1 webchat over AHP behind a flag → Phase 2 (optional) console live views. Explicit non-goals: IM renderers, agent-to-agent messaging, the CP.
• Upstream gaps to raise on microsoft/agent-host-protocol before Phase 1 hardens.

Relates to

• Use AHP (https://github.com/microsoft/agent-host-protocol) to unify all session models #1339 (does not close it — this is the design step)

cc @zfy0701 — happy to iterate on scope or split anything out.

[agentconnect-md-test]

Approved as a proposal. The daemon-host placement, outward session identity, retained regeneration workflow, and webchat-first scope fit the current architecture. No blocking findings.

Two nonblocking notes for the implementation plan are inline: serverSeq does not establish gap-free delivery for a subscription, and the shadow projection needs daemon-owned discard events alongside ACP updates.

Reviewed the verified revision against the current daemon/webchat flow and upstream AHP transport requirements. git diff --check passed; no runtime tests were run for this documentation-only change.

_{sent by review-bot (Codex · gpt-6-astra) · open in session}

[agentconnect-md-test]

Approved. This revision addresses both prior notes: the fencing table now treats serverSeq as an ordering/replay cursor rather than a per-subscription completeness proof, and Phase 0 explicitly consumes daemon-owned discard/reset events alongside masked ACP updates.

The daemon-host placement, outward session identity, retained regeneration workflow, and incremental rollout remain consistent with the current architecture. I left one nonblocking clarification for the optional Phase 2 transport: deployed daemons are generally not directly reachable from browsers, so that phase will need a relay or another explicit data-plane route in addition to its token design.

git diff --check passed, and all local Markdown targets resolve. No runtime tests were run for this documentation-only change.

_{sent by review-bot (Codex · gpt-5.6-sol) · open in session}

[agentconnect-md-test]

Approved. Revision 3d4aed50 resolves the remaining Phase 2 reachability note by making the relay-forwarded data-plane route explicit for both NAT-bound self-hosted daemons and cluster-internal managed daemons. This preserves the Control Plane hot-path boundary and leaves authorization details for the appropriate implementation design pass.

The earlier serverSeq/transport and daemon-owned reducer-input corrections remain intact. No blocking or additional nonblocking findings.

git diff --check passed, and all local Markdown targets resolve. No runtime tests were run for this documentation-only change.

_{sent by review-bot (Codex · gpt-5.6-sol) · open in session}

[Poytr1]

Thanks for writing this up — appreciate the care that went into scoping #1339 down to something incremental and reviewable.

To be upfront on timing: AHP is still pre-1.0 (0.9.0 as of late August), with breaking changes landing in nearly every minor release, and VS Code is the only shipping host so far. We're actively looking into it, but it may not be a priority for us in the near term. Please don't read slow movement here as disinterest — the placement, identity mapping, and fencing sections are a useful reference regardless of when we pick this up.