build-ahp-client

Build an AHP Client

Use this skill when consuming AHP from an application or client integration. It applies naturally to TypeScript and browser clients, but the state and transport rules are cross-language.

Use this / use another skill

Use this skill	Use another skill
The client must connect, initialize, subscribe, render, dispatch, or reconnect.	Use build-ahp-host for server routing, persistence, fan-out, or model execution.
You need a new action, state field, wire command, or compatibility rule.	Use design-ahp-protocol before changing the contract.
You are authoring raw WebSocket black-box probes or fixture-driven conformance coverage.	Use test-ahp-conformance.

Ground in the active protocol

1. Identify the current AHP version, SDK release, and target host capabilities. Read the protocol's lifecycle, subscriptions, reconciliation, state-model, and versioning documentation plus the generated client APIs.
2. Find existing connection, store, reducer, and projection code in the repository. Reuse the SDK's client, transport, state mirror, and canonical reducers when they fit instead of duplicating wire handling.
3. If protocol source is not in the workspace, consult the upstream microsoft/agent-host-protocol documentation and schemas. Never assume a particular local checkout exists.
4. Separate AHP guarantees from local product policy: reconnect backoff, UI limits, retention assumptions, and a particular host's unsupported surfaces are not portable requirements.

Design the client state boundary

Maintain a protocol layer and a presentation layer:

Layer	Responsibility
Transport/client	Connection lifecycle, JSON-RPC requests, subscriptions, and shutdown
Protocol store	Typed snapshots, ordered envelopes, canonical reducers, sequence tracking
Projection	Fresh immutable view models, sort/filter/format policy, UI selection state
UI	Renders projections and invokes application commands; never mutates protocol maps

Keep snapshots typed by channel/state rather than treating all JSON as one untyped store. Treat the server's action envelope as authoritative and route it using its channel URI. Do not invent a channel from fields on the inner action.

Connection and subscription flow

1. Create one durable client identity per logical client according to the protocol, then open the selected host transport.
2. Initialize with the SDK's supported protocol-version list, root channel, and useful initial subscriptions. Record the selected version and each snapshot's fromSeq/server sequence.
3. Attach local subscription consumers before or as the SDK requires so no actions are lost between handshake and consumption. Close them deliberately when the user leaves a resource or disconnects.
4. Subscribe on demand to session, chat, or other resources. Apply a returned snapshot before relying on later actions, and retain the desired subscription set for reconnect.
5. Fetch or list catalog data where the protocol requires it. Do not depend on ephemeral notifications being replayed.

Reduce and reconcile correctly

• Apply only envelopes newer than the last observed serverSeq; update the sequence monotonically.
• Use immutable reducers and immutable/frozen UI projections. Mutable SDK mirrors or maps are protocol internals, not React or UI snapshots.
• If using optimistic dispatch, keep confirmed state and ordered pending actions separately. Match your own authoritative echo, rebase remaining actions over foreign/server changes, and remove/revert a rejected action.
• Respect terminal turn states. A cancel affordance should not make a late delta or completion appear valid after the host has terminated the turn.
• Keep multi-host data isolated by connection/host identity. Reset or namespace state, sequence numbers, subscriptions, and selected resources when switching hosts.

Reconnect without stale events

Use a connection epoch/token (or equivalent ownership guard):

1. Invalidate the old epoch before closing a socket or starting another.
2. Close async iterators and subscriptions from the old client.
3. Ignore delayed callbacks, errors, and action streams unless they still belong to the current epoch and current client.
4. Reconnect with the durable client ID, last observed sequence, and desired subscriptions.
5. If the host returns replay, reduce every envelope in order; if it returns snapshots because the replay gap is unavailable, replace confirmed state and clear/reconcile pending work as the protocol requires. Remove resources named missing by the host.
6. Re-fetch catalog state after reconnect because protocol notifications are not replayed.

For configurable agents, render the host's SessionModelInfo.configSchema and session configuration schema instead of hardcoding provider-specific values. Use resolveSessionConfig and sessionConfigCompletions, preserve unknown configuration entries when editing known ones, and attach the effective ModelSelection to the user message so history records what actually ran.

Validate and document

Test the smallest layer first: reducer/projection purity, sequence rejection, and epoch cleanup. Then test initialization, delayed subscription events, reconnect replay and snapshot fallback, two-client updates, host switching, and cancel/error rendering. Run the application's broader typecheck/build/tests after focused tests pass.

Document unsupported host capabilities, degraded UI behavior, and intentional local policy. Stop when an old socket cannot update the new connection and the UI always sees a fresh immutable projection of authoritative protocol state.