The CLI

The package ships one executable. It attaches to a running host, negotiates a protocol version, subscribes to the root channel, and prints what it mirrors back.

dart run ahp_sdk:ahp --url ws://localhost:51234

Activated globally, it is just ahp:

dart pub global activate ahp_sdk
ahp --url ws://localhost:51234

Options

Option
--url <ws-url>	Host WebSocket URL. Required.
--token <token>	Connection token, if the host requires one
--watch	Stay connected and reprint on every change
-h, --help	Usage

What it is for

Every other test in this package runs against a fixture corpus. This one runs against a host that has never heard of it — which is the only way to find out whether the generated types, the reducers, the reconciliation mirror, and the transport agree with a real implementation rather than merely with each other.

A fixture corpus cannot catch a field the schema describes differently from what hosts actually send. This can.

Reading the output

connecting to ws://localhost:51234
negotiated protocol 0.7.0
host: vscode-copilot 1.2.3
serverSeq at handshake: 41
2 agent(s):
  copilot — GitHub Copilot
  claude  — Claude

serverSeq at handshake is the sequence number the host had reached when the handshake completed. Everything after it arrives as actions; everything before it is folded into the snapshot. That boundary is the whole basis of reconciliation.

With --watch it also reports sequence gaps as they happen:

! sequence gap: SeqGap(expected: 42, received: 47)

A gap means envelopes were dropped in transit. The CLI only observes them; a real client reconnects and replays.

Exit codes

Chosen from sysexits.h so a shell can tell the failures apart:

Code	Name	Means
0		Connected, mirrored, printed
64	EX_USAGE	Bad arguments
69	EX_UNAVAILABLE	Could not open the socket
70	EX_SOFTWARE	Host rejected the handshake
75	EX_TEMPFAIL	Timed out — retryable

The distinction that matters is 70 against 75. An unsupported protocol version is terminal: the client already offered every version it can speak, so there is nothing left to degrade to and retrying will fail identically. On that path the CLI prints both sides of the disagreement:

host rejected the handshake: AhpRpcException(-32005, unsupported protocol version)
  host speaks: [0.9.0, 0.8.0]
  we offered:  [0.7.0, 0.6.0, 0.5.2, 0.5.1]

which tells you immediately that the fix is upgrading the client, not retrying.