Add multi-host SDK to the TypeScript client

[colbylwilliams]

What

Adds the multi-host SDK to the TypeScript client as a fourth subpath export — @microsoft/agent-host-protocol/hosts — mirroring the Rust ahp::hosts module and the Swift MultiHostClient actor.

Why

This is the largest remaining gap in the TypeScript client's surface relative to the Rust SDK. A real product that talks to two or more hosts at once (a local sessions server + a tunnel-attached remote, a personal host + a teammate's, N project hosts in a desktop sidebar, …) otherwise hand-rolls the same boilerplate: N AhpClients, N transports + reconnect supervisors with backoff, a per-host metadata registry, per-host scoping of resource URIs, a fan-in of inbound events tagged with host of origin, and clientId persistence so reconnect identity survives launches. This PR ships that layer.

Originally drafted as a follow-up to #156 (the now-closed publish pipeline PR). Rebased onto main since #156 was closed without merging; the multi-host work stands on its own and doesn't depend on the publish pipeline.

Surface

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

// Single-host: never see "registry" concepts.
const { multi, host } = await MultiHostClient.single({
  id: 'local',
  label: 'Local sessions server',
  transportFactory: openLocal,
});

// Or multi-host: add as many as you need.
await multi.addHost({ id: 'tunnel', label: 'Tunnel', transportFactory: openTunnel });
for await (const event of multi.events()) {
  console.log(`[${event.hostId}] ${event.channel}`, event.event.type);
}

What ships:

• MultiHostClient — single, addHost, removeHost, reconnectHost, reconnectAllUnavailable, host/hostsSnapshot, client (returns a generation-checked HostClientHandle), subscribe/unsubscribe/dispatch, events/hostEvents, aggregatedSessions/aggregatedAgents, shutdown.
• HostConfig / HostHandle / HostState discriminated union (disconnected | connecting | connected | reconnecting | failed) / HostEvent / HostSubscriptionEvent / HostedSessionSummary / HostedAgent.
• Error family extending AhpClientError: HostMultiError, UnknownHostError, DuplicateHostError, HostReconnectedError (carries both handleGeneration and currentGeneration for clean stale-handle recovery), HostShutDownError, ClientIdStoreError.
• ReconnectPolicy + Backoff with jitter, plus disabledPolicy() / exponentialPolicy() (default: 250 ms → 30 s, ×2, 25 % jitter, retry forever) / immediateForeverPolicy(). Pure functions backoffDelayForAttempt, delayWithJitter, attemptsExhausted are exposed for deterministic testing.
• HostTransportFactory — (hostId, signal) => Promise<AhpTransport>. The AbortSignal is aborted on remove / shutdown so factories can bail out of a slow handshake instead of blocking teardown.
• ClientIdStore + InMemoryClientIdStore — pluggable persistence for stable per-host clientIds. Explicit > stored > generated; resolved id is always written back. Store failures surface as ClientIdStoreError from addHost.
• MultiHostStateMirror + hostedResourceKey — host-aware reducer façade that keys session/terminal/changeset state by (hostId, uri) so URIs that legitimately collide across hosts (the normal case for session URIs) don't clobber.

Design notes

• Cancellation in single-threaded JS. The Rust runtime uses tokio::select! racing futures against shutdown_signal.notified(). JS can't preempt an in-flight await, so the port threads AbortSignal through HostTransportFactory and ClientIdStore.load/store, and routes every internal handshake through a raceWithAbort(promise, signal) helper that resolves with an ABORTED sentinel on signal abort. That helper attaches a no-op rejection handler to the inner promise so late ClientClosedErrors (from a half-built AhpClient.initialize whose client got shutdown()'d in the finally) don't surface as unhandledRejections.
• Generation invalidation. Every successful (re)connect bumps a per-host generation. HostClientHandle reads generation + shutdownReason through a shared reference on every checkAlive — handle-after-reconnect surfaces HostReconnectedError; handle-after-removeHost surfaces HostShutDownError. Both errors are recoverable via a fresh multi.client(hostId) (or, for removal, the host being re-added).
• Replay-before-connected. Reconnect-replay envelopes are fanned through the per-host state mirror and the cross-host event tap before transitionTo({status: 'connected'}) / HostEvent.connected, so consumers observing the connected event already see catch-up state.
• Snapshot pruning. ReconnectResult.Snapshot only drops URIs that were in the prior subscriptions set AND missing from returned snapshots — URIs added locally between disconnect and reconnect survive.
• addHost race safety. A pending-host id set guards against concurrent addHost calls slipping past the duplicate check while one is awaiting the ClientIdStore. The reservation is cleared in finally so any error path (including store failures) frees the slot for a retry.
• Events stream lifetime. The client's all-events broadcast is attached before initialize / reconnect so notifications pushed between the handshake response and the moment the supervisor enters its event loop are captured instead of dropped by the broadcast queue's no-replay-for-late-readers semantics.
• HostId as string alias. Kept a plain string for ergonomics — equality is === and tests pass string literals directly. A branded type was considered but added too much friction for the surface gain.

Not in this PR

• FileClientIdStore. A filesystem-backed ClientIdStore would pull in node:fs and break browser bundlers even if consumers never instantiate it. Browsers can implement ClientIdStore against localStorage / IndexedDB; Node/Electron consumers can wrap node:fs/promises or safeStorage. The interface is the contract. If a Node-only adapter ends up wanted later, it can ship as a separate @microsoft/agent-host-protocol/hosts/file-client-id-store subpath without re-exporting from the browser-safe /hosts entry point.
• A dedicated docs/guide/connecting-to-multiple-hosts.md page. The TS client's README has a full Multi-host orchestration section with a runnable example; mirroring the Rust SDK's MULTI_HOST.md into the docs site can ship in a follow-up if the docs site wants a language-agnostic narrative.

Verification

From a fresh npm run generate:typescript at the repo root, then in clients/typescript:

• ✅ npm run typecheck clean.
• ✅ npm test — 47 tests pass (24 new). Coverage includes:
  • MultiHostClient.single / addHost / removeHost / DuplicateHostError.
  • addHost surfaces ClientIdStoreError and frees the reservation so a retry succeeds.
  • HostClientHandle.generation invalidates after a reconnect (carries both generations).
  • HostClientHandle after removeHost throws HostShutDownError.
  • ReconnectPolicy.delayWithJitter / backoffDelayForAttempt / attemptsExhausted shapes (mirrors the Rust unit tests).
  • InMemoryClientIdStore round-trip + overwrite.
  • hostedResourceKey distinguishes same-URI hosts; MultiHostStateMirror.applySnapshot / resetHost scoping.
  • aggregatedSessions sorts by modifiedAt descending and tags hostLabel; aggregatedAgents tags every agent with host.
  • hostEvents lifecycle ordering (added → stateChanged → connected → removed).
  • events fan-in delivers notifications tagged with hostId.
  • reconnectAllUnavailable skips connected/connecting hosts and returns per-host errors without throwing.
  • Manual reconnectHost wakes a host whose ReconnectPolicy is exhausted (the post-failed resumption path).
  • MultiHostClient.shutdown is idempotent.
  • subscribe / unsubscribe / dispatch on an unknown host throws UnknownHostError.
• ✅ npm run build clean. npm pack --dry-run ships dist/client/hosts/.
• ✅ Root npm run lint + npm run typecheck unchanged (the ESLint config already excludes clients/typescript/** and the root tsc only covers types/).

[Copilot]

Pull request overview

Adds a new TypeScript multi-host orchestration layer exposed as @microsoft/agent-host-protocol/hosts, bringing the TS client closer to the Rust/Swift SDK surface by providing per-host supervisors, reconnect policy/backoff, fan-in events, aggregated views, and host-aware state mirroring.

Changes:

• Introduces MultiHostClient + supporting types/errors (Host*, ReconnectPolicy, ClientIdStore, generation-checked HostClientHandle).
• Implements per-host runtime supervisor with reconnect/backoff, replay handling, and fan-in event publishing.
• Adds a comprehensive hosts.test.ts suite and updates docs/package exports to expose the new /hosts entry point.

Show a summary per file

File	Description
clients/typescript/src/client/hosts/index.ts	Exposes the public /hosts surface (types, errors, helpers, mirrors).
clients/typescript/src/client/hosts/multi.ts	Implements the MultiHostClient registry façade and fan-in streams.
clients/typescript/src/client/hosts/runtime.ts	Implements the per-host supervisor loop, connect/reconnect, and event fan-out.
clients/typescript/src/client/hosts/types.ts	Defines public multi-host types, errors, and config resolution.
clients/typescript/src/client/hosts/policy.ts	Adds reconnect policy/backoff + deterministic helpers.
clients/typescript/src/client/hosts/host-client-handle.ts	Adds generation-checked client handles (HostClientHandle).
clients/typescript/src/client/hosts/state-mirror.ts	Adds host-aware reducer mirror keyed by (hostId, uri).
clients/typescript/src/client/hosts/factory.ts	Defines HostTransportFactory contract and docs.
clients/typescript/src/client/hosts/client-id-store.ts	Defines ClientIdStore + InMemoryClientIdStore.
clients/typescript/test/hosts.test.ts	Adds integration/unit tests for multi-host behavior and helpers.
clients/typescript/README.md	Documents new /hosts entry point and multi-host usage.
clients/typescript/package.json	Adds ./hosts subpath export to the package.

Copilot's findings

• Files reviewed: 12/12 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

• Files reviewed: 12/12 changed files
• Comments generated: 5

[Copilot]

Copilot's findings

• Files reviewed: 12/12 changed files
• Comments generated: 2