This content is for the 0.1 version. Switch to the latest version for up-to-date documentation.

Agent state, mirrored

Attach to a running agent host, mirror its state through the same pure reducers the host runs, and keep every client in step.

Quickstart What is AHP?pub.dev

dart pub add ahp_sdk

final client = AhpConnection(
  await WebSocketAhpTransport.connect(Uri.parse('ws://localhost:51234')),
);
final mirror = AhpStateMirror(clientId: 'my-app');
client.actions.listen(mirror.applyEnvelope);

await client.initialize(
  InitializeParams(
    channel: 'ahp-root://',
    protocolVersions: supportedProtocolVersions,
    clientId: 'my-app',
  ),
);

final root = mirror.storeFor(Uri.parse('ahp-root://')).optimistic! as RootState;
for (final agent in root.agents) {
  print('${agent.provider} — ${agent.displayName}');
}

Why this exists

A host — an editor, an IDE, a terminal — runs the agent. Everything else watches. AHP is how those watchers stay honest: the host emits an ordered stream of actions, each client folds them through identical pure reducers, and every client lands on the same state without polling for it.

State you read synchronously

No futures, no polling. Actions arrive in order, run through the reducers, and leave a plain immutable object you can read on the spot.

Optimistic, and honest about it

A dispatched action applies locally before it reaches the wire, then reconciles against the server’s echo. Rejected, and the effect reverts with the host’s reason attached.

Generated from the published schema

Every wire type comes from upstream’s JSON Schema through a Dart generator in this repo. No hand-maintained model layer to drift.

Verified against upstream's corpora

39 round-trip and 246 reducer fixtures — the same ones the Rust, Go, Swift, and Kotlin clients assert against.

Where to go

If you want to	Read
Understand the protocol’s shape	What is AHP?
Get something running	Quickstart
Know how state stays correct	Reconciliation
Wire it into a Flutter app	Flutter setup
Know what is and isn’t implemented	Protocol coverage

Scope

This site documents the Dart SDK. The protocol itself — wire format, channel semantics, the normative rules — is specified at microsoft.github.io/agent-host-protocol.

Where the two disagree, the specification is right and this client has a bug.