design-ahp-protocol

Design AHP Protocol

Use this skill for a change to the AHP contract itself: a command, action, channel state shape, error, reducer rule, schema, generated binding, version rule, or interoperability invariant.

Use this / use another skill

Use this skill	Use another skill
The requested outcome changes what AHP peers may send, receive, reduce, or negotiate.	Use build-ahp-host for an implementation-only server concern.
You need to evaluate compatibility, capability gating, or cross-language code generation.	Use build-ahp-client for consuming an established contract in an app or SDK client.
You are defining the observable contract that tests must enforce.	Use test-ahp-conformance to implement black-box probes for an established contract.

If a task includes design and implementation, settle the contract and its observable invariants here first, then activate the implementation skill for the code-owning portion.

Establish the current authority

1. Identify the protocol version and branch actually targeted; do not infer shapes from an old sample, package, or blog post.
2. Locate the protocol source in the workspace. Read its types/, canonical channel reducers, schemas, docs/specification/, docs/guide/, version registry, and the relevant Rust and TypeScript SDK bindings.
3. If the source is not present, use the released schemas and documentation in microsoft/agent-host-protocol; state which revision or release informed the decision. Do not hard-code a local sibling-repository path.
4. Inspect nearby prior art, existing test cases, generated-file conventions, and release/versioning instructions before proposing a new shape.
5. Separate normative AHP behavior from profile, host, or sample policy. A bounded replay log, a selected persistence engine, or an unsupported feature in one host is not automatically a protocol requirement.

Model the change before editing

Write a compact contract table:

Question	Decide explicitly
Scope	Channel URI, command/notification, action, state fields, and ownership
Direction	Client request/notification, server response/notification, or both
Reducer	Pure state transition, idempotence, replacement/merge/append behavior
Ordering	serverSeq, origin echo/rejection, and ordering with related actions
Failure	JSON-RPC versus rejected action, error code/data, recoverability
Compatibility	Version introduction, capability gate, old-peer behavior, omission rules

Actions are state mutations, not a substitute for vague side effects. Route an inner action by its envelope's channel; retain action fields that are intrinsic to the action. Define who assigns identifiers and how multiple clients converge.

For client-dispatchable actions, specify authoritative echo and rejection semantics. A client may optimistically reduce an action, but it must rebase pending work on server-authoritative envelopes and undo a rejected prediction.

State and reducer discipline

• Start from the canonical state and action discriminated unions, not a handwritten partial copy.
• Make reducers pure, exhaustive, and immutable. Keep I/O, transport, model calls, and persistence outside reducer code.
• Define snapshot and action equivalence: reducing a snapshot followed by ordered actions must reach the same observable state for all subscribers.
• State which fields are complete replacements, patches, keyed upserts, or append-only histories. Define unknown IDs, duplicate IDs, and terminal-state handling.
• Do not let a session catalog summary silently become live session state; use the current channel definitions and typed snapshots.

Versioning and generated artifacts

1. Classify the change as additive, breaking, or clarification under the protocol's current SemVer and stability policy.
2. For additive behavior, decide whether a capability is needed before it becomes baseline. Older peers must safely ignore behavior they do not know.
3. Ensure negotiation selects one offered version for the whole connection; never design per-message renegotiation.
4. Change canonical types, schemas, version registry, and fixtures first. Run the repository's generators and commit their outputs only when that repository tracks them. Never hand-edit generated bindings as the source of truth.
5. Update normative documentation, compatibility notes, and changelog material required by the repository's release process.

Validate the contract

Test the smallest affected layer first: schema/type checks and reducer fixtures. Then run generated-binding checks and cross-client or wire tests relevant to the change. Include:

• valid and malformed shapes;
• ordering and repeated delivery;
• old/new compatible peers and unsupported negotiation;
• two clients racing or observing the same resource;
• snapshots versus action replay and rejection reconciliation.

Stop when the types, schema, canonical reducer behavior, generated SDKs, and normative docs agree. Record intentional scope and non-goals, especially features left capability-gated or profile-specific.