typescript

@microsoft/agent-host-protocol

TypeScript client for the Agent Host Protocol (AHP).

Browser-friendly client built on the global WebSocket API. Works in modern browsers and Node 21+ without additional runtime dependencies.

Entry points

The package exposes four subpath exports:

Import path	What it gives you
@microsoft/agent-host-protocol	Wire types, actions, commands, reducers, version constants. No I/O.
@microsoft/agent-host-protocol/client	AhpClient, Subscription, AhpStateMirror, the AhpTransport interface, InMemoryTransport, and the error taxonomy.
@microsoft/agent-host-protocol/hosts	MultiHostClient, HostClientHandle, ReconnectPolicy, ClientIdStore (with InMemoryClientIdStore), MultiHostStateMirror, and the Host*Error family. Builds on /client to manage one or more host connections with reconnect, generation-checked handles, and fan-in events.
@microsoft/agent-host-protocol/ws	WebSocketTransport — an AhpTransport implementation backed by the global WebSocket.

The split mirrors the Rust SDK (ahp-types, ahp, ahp::hosts, ahp-ws) — wire types and reducers are decoupled from the client, which is in turn decoupled from a specific transport and from the multi-host orchestration layer.

Quickstart

import { ActionType, type ActionEnvelope } from '@microsoft/agent-host-protocol';
import { AhpClient, AhpStateMirror } from '@microsoft/agent-host-protocol/client';
import { WebSocketTransport } from '@microsoft/agent-host-protocol/ws';

const transport = await WebSocketTransport.connect('ws://localhost:12345');
const client = new AhpClient(transport);
const mirror = new AhpStateMirror();

client.connect();

const init = await client.initialize({
  clientId: 'my-client',
  protocolVersions: ['0.3.0'],
  initialSubscriptions: ['ahp-root://'],
});

for (const snapshot of init.snapshots) {
  mirror.applySnapshot(snapshot);
}

const root = client.attachSubscription('ahp-root://');
(async () => {
  for await (const event of root) {
    if (event.type === 'action') mirror.apply(event.params);
  }
})();

const sessionUri = `ahp-session:/${crypto.randomUUID()}`;
client.dispatch(sessionUri, {
  type: ActionType.SessionTurnStarted,
  // … remaining action fields
} as unknown as ActionEnvelope['action']);

Pluggable transports

AhpClient is transport-agnostic. Any framed message stream — a WebSocket, a Unix socket, stdio, or an in-memory pair for tests — can back an AhpTransport:

import type { AhpTransport, TransportFrame, JsonRpcMessage } from '@microsoft/agent-host-protocol/client';

class MyTransport implements AhpTransport {
  send(message: JsonRpcMessage | string): void { /* … */ }
  async recv(): Promise<TransportFrame | null> { /* … */ }
  close(): void { /* … */ }
}

InMemoryTransport.pair() returns two connected halves that exchange text frames — handy for unit tests that don't need a real socket.

Reducers and state mirror

The reducer functions (rootReducer, sessionReducer, terminalReducer, changesetReducer) are pure: replaying actions in serverSeq order on any prior snapshot yields identical state. This is the same property the Rust and Swift clients rely on for reconnection.

AhpStateMirror is a convenience that holds one RootState, a Map<URI, SessionState>, a Map<URI, TerminalState>, and a Map<URI, ChangesetState>. Apply Snapshots and ActionEnvelopes and it keeps those maps up to date. Larger apps usually keep their own state and call the reducers directly.

Errors

Class	When it's thrown
RpcError	JSON-RPC error response from the server. Carries code, message, data.
RpcTimeoutError	Client-side timeout fired before the server responded. Carries method, timeoutMs. Distinct from RpcError.
TransportError	Failure of the underlying transport. kind: 'closed' | 'io' | 'protocol'.
ClientClosedError	Request was in flight when the client was shut down.
AhpClientError	Base class for every error this SDK throws — use instanceof to catch them all.

Malformed inbound frames don't throw — they're logged via console.warn and the channel stays alive (matching the Rust client's tracing::warn! behavior). Pending requests still time out via RpcTimeoutError if the dropped frame would have been their reply.

Server-initiated requests

Some AHP methods (currently resourceRequest) can be initiated by the server. By default, the client responds with JSON-RPC MethodNotFound so the server does not leak a pending request. Install a typed handler to take over:

client.setServerRequestHandler(async (method, params) => {
  if (method === 'resourceRequest') {
    return { /* … */ };
  }
  throw new RpcError(JsonRpcErrorCodes.MethodNotFound, 'unhandled');
});

Reconnection

AhpClient.reconnect(...) sends the typed AHP reconnect request on an already-open transport. It does not decide when to reconnect, how often to retry, whether authentication errors are terminal, or how to update UI while reconnecting — those policies live in the app.

A typical app-level reconnect flow is:

1. Open a fresh transport and AhpClient.
2. Attach event streams before the handshake.
3. Call connect() and reconnect({ clientId, lastSeenServerSeq, subscriptions }).
4. Apply the returned replay actions or snapshots to your app store.
5. Re-fetch listSessions or other ephemeral data — protocol notifications are not replayed.

If you'd rather not write that loop yourself, see @microsoft/agent-host-protocol/hosts — it ships a MultiHostClient that owns the reconnect supervisor, re-subscribes across reconnects, mirrors root state, and exposes generation-checked client handles. Single-host consumers use MultiHostClient.single(...).

Multi-host orchestration

For apps that talk to one or more AHP hosts at once (a local sessions server plus a tunnel-attached remote, multiple project hosts in a sidebar, …), the @microsoft/agent-host-protocol/hosts entry point ships MultiHostClient:

import { ActionType } from '@microsoft/agent-host-protocol';
import { WebSocketTransport } from '@microsoft/agent-host-protocol/ws';
import {
  MultiHostClient,
  type HostTransportFactory,
} from '@microsoft/agent-host-protocol/hosts';

const openLocal: HostTransportFactory = async (_hostId, _signal) =>
  WebSocketTransport.connect('ws://localhost:12345');

// Single-host: same API, never see "registry" concepts.
const { multi, host } = await MultiHostClient.single({
  id: 'local',
  label: 'Local sessions server',
  transportFactory: openLocal,
});
console.log(`connected to ${host.label}: ${host.state.status}`);

// Multi-host: add as many as you need.
await multi.addHost({
  id: 'tunnel',
  label: 'Tunnel',
  transportFactory: async (_id, _signal) =>
    WebSocketTransport.connect('wss://my-tunnel.example/sessions'),
});

// Fan-in of every inbound event, tagged with host of origin.
for await (const event of multi.events()) {
  console.log(`[${event.hostId}] ${event.channel}`, event.event.type);
}

Each host runs its own reconnect supervisor with the configured ReconnectPolicy (defaults to exponential backoff from 250 ms to 30 s with 25 % jitter), re-subscribes to known URIs after reconnects, and mirrors root state plus a session-summary cache so MultiHostClient .aggregatedSessions() and aggregatedAgents() are snapshot reads, not fan-out subscriptions. Every successful (re)connect bumps a per- host generation counter; HostClientHandles minted at an earlier generation throw HostReconnectedError instead of silently writing to the new connection.

Persistent clientIds are pluggable via the ClientIdStore interface. The default InMemoryClientIdStore is session-stable; production apps that need cross-launch identity wrap their platform's secure storage (localStorage, IndexedDB, Node fs, safeStorage, …) in a custom ClientIdStore.

For multi-host state, MultiHostStateMirror keys per-resource state by (hostId, uri) so URIs that legitimately collide across hosts (the normal case for session URIs) don't clobber each other.

Wire types

The wire types under src/types/ are generated from types/*.ts at the repository root and are not committed to the repo — avoiding a byte-for-byte duplication of the canonical TypeScript sources. Regenerate them whenever you pull or change the protocol:

npm run generate:typescript    # from the repo root

Generated files carry a banner; do not edit them by hand. The generate:typescript script is also part of npm run generate, which regenerates every language's client output.

Protocol version mapping

This package exports two protocol-version constants from its default entry point:

import { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@microsoft/agent-host-protocol';

• PROTOCOL_VERSION — SemVer string for the version this package's source tree implements.

• SUPPORTED_PROTOCOL_VERSIONS — every version this package is willing to negotiate (most-preferred-first). Pass it as protocolVersions on InitializeParams:

  await client.initialize({
    clientId: 'my-client',
    protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
    initialSubscriptions: ['ahp-root://'],
  });

The same information is mirrored, in machine-readable form, in release-metadata.json and, in human-readable form, in CHANGELOG.md. CI verifies all three sources agree on every PR.

Development

From a fresh checkout:

# 1. Install the root tooling and generate the TS client's wire types.
npm install
npm run generate:typescript

# 2. Work in the client package.
cd clients/typescript
npm install
npm run typecheck
npm test
npm run build

CI runs the generate step automatically before the install/typecheck/test/build sequence, so contributors only need to remember step 1 locally after pulling protocol changes.

License

MIT