@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/core/host.ts

@@ -0,0 +1,882 @@
+/**
+ * The AHP host: message routing, subscriptions, sequencing, and broadcast.
+ *
+ * The host owns the authoritative state for every channel it serves. Clients
+ * apply their own actions optimistically and reconcile when the host echoes
+ * them back in server order, so N clients converge on the same view.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/guide/doctrine
+ */
+
+import {
+	type ActionEnvelope,
+	type CommandMap,
+	type CompletionsParams,
+	type CompletionsResult,
+	type CreateResourceWatchParams,
+	type CreateResourceWatchResult,
+	type CreateSessionParams,
+	type CreateTerminalParams,
+	type DispatchActionParams,
+	type FetchTurnsParams,
+	type FetchTurnsResult,
+	type InitializeParams,
+	type InitializeResult,
+	isClientDispatchable,
+	JsonRpcErrorCodes,
+	type ListSessionsResult,
+	type ReconnectParams,
+	type ReconnectResult,
+	ReconnectResultType,
+	type ResolveSessionConfigParams,
+	type ResolveSessionConfigResult,
+	type ResourceCopyParams,
+	type ResourceDeleteParams,
+	type ResourceListResult,
+	type ResourceMkdirParams,
+	type ResourceMoveParams,
+	type ResourceReadParams,
+	type ResourceReadResult,
+	type ResourceResolveParams,
+	type ResourceResolveResult,
+	type ResourceWriteParams,
+	type SessionConfigCompletionsParams,
+	type SessionConfigCompletionsResult,
+	type Snapshot,
+	type StateAction,
+	type SubscribeParams,
+	type SubscribeResult,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { ProtocolError } from "../protocol/errors.ts";
+import {
+	errorResponse,
+	isJsonRpcNotification,
+	isJsonRpcRequest,
+	type JsonRpcNotification,
+	type JsonRpcRequest,
+	notification,
+	readChannel,
+	successResponse,
+} from "../protocol/jsonrpc.ts";
+import { negotiateProtocolVersion } from "../protocol/version.ts";
+import { actionBelongsToChannel, type ChannelKind, channelKind, ROOT_CHANNEL } from "./channels.ts";
+import { ClientConnection, type Transport } from "./connection.ts";
+import { Sequencer } from "./sequencer.ts";
+import { StateStore } from "./state-store.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+/** Minimum envelope shape; capability handlers validate accepted payloads. */
+function isActionLike(value: unknown): value is StateAction {
+	return isRecord(value) && typeof value.type === "string";
+}
+
+function isImplementation(value: unknown): value is NonNullable<InitializeParams["clientInfo"]> {
+	return (
+		isRecord(value) &&
+		typeof value.name === "string" &&
+		(value.version === undefined || typeof value.version === "string") &&
+		(value.title === undefined || typeof value.title === "string")
+	);
+}
+
+/** Commands whose routing channel is always the singleton root channel. */
+const ROOT_COMMANDS = new Set<keyof CommandMap>([
+	"initialize",
+	"ping",
+	"reconnect",
+	"listSessions",
+	"resourceRead",
+	"resourceWrite",
+	"resourceList",
+	"resourceCopy",
+	"resourceDelete",
+	"resourceMove",
+	"resourceResolve",
+	"resourceMkdir",
+	"resourceRequest",
+	"createResourceWatch",
+	"authenticate",
+	"resolveSessionConfig",
+	"sessionConfigCompletions",
+	"listAutomationTriggerDefinitions",
+]);
+
+function validateInitialize(params: InitializeParams | undefined): asserts params is InitializeParams {
+	if (typeof params?.clientId !== "string" || params.clientId.length === 0) {
+		throw ProtocolError.invalidParams("initialize requires a clientId");
+	}
+	if (params.initialSubscriptions !== undefined && !isStringArray(params.initialSubscriptions)) {
+		throw ProtocolError.invalidParams("initialSubscriptions must be an array of URIs");
+	}
+	if (params.clientInfo !== undefined && !isImplementation(params.clientInfo)) {
+		throw ProtocolError.invalidParams("clientInfo must be an implementation descriptor");
+	}
+	if (params.locale !== undefined && typeof params.locale !== "string") {
+		throw ProtocolError.invalidParams("locale must be a string");
+	}
+	if (params.capabilities !== undefined && !isRecord(params.capabilities)) {
+		throw ProtocolError.invalidParams("capabilities must be an object");
+	}
+}
+
+function validateReconnect(params: ReconnectParams | undefined): asserts params is ReconnectParams {
+	if (typeof params?.clientId !== "string" || params.clientId.length === 0) {
+		throw ProtocolError.invalidParams("reconnect requires a clientId");
+	}
+	if (!Number.isSafeInteger(params.lastSeenServerSeq) || params.lastSeenServerSeq < 0) {
+		throw ProtocolError.invalidParams("reconnect requires a non-negative integer lastSeenServerSeq");
+	}
+	if (!isStringArray(params.subscriptions)) {
+		throw ProtocolError.invalidParams("reconnect requires a subscriptions array of URIs");
+	}
+}
+
+/**
+ * Optional protocol surfaces. Requests for an absent surface receive an empty
+ * result where meaningful and `MethodNotFound` otherwise.
+ */
+export interface HostCapabilities {
+	/** The session catalogue behind `listSessions`. */
+	readonly catalogue?: SessionCatalogue;
+	/** `createSession` / `disposeSession`. */
+	readonly sessions?: SessionLifecycleHandler;
+	/** `createTerminal` / `disposeTerminal`. */
+	readonly terminals?: TerminalHandler;
+	/** The `resource*` request/response family. */
+	readonly resources?: ResourceHandler;
+	/** `createResourceWatch`. */
+	readonly resourceWatches?: ResourceWatchHandler;
+	/** `completions`. */
+	readonly completions?: CompletionHandler;
+	/** `resolveSessionConfig` / `sessionConfigCompletions`. */
+	readonly sessionConfig?: SessionConfigHandler;
+	/** `fetchTurns`. */
+	readonly turnPaging?: TurnPagingHandler;
+	/** Loads a channel that exists durably but is not yet in memory. */
+	readonly hydrator?: ChannelHydrator;
+}
+
+export interface HostOptions {
+	/** Advertised on `InitializeResult.serverInfo`. Informational only. */
+	readonly serverInfo?: { name: string; version?: string; title?: string };
+	/** Starting location for remote filesystem browsing, as a `file:` URI. */
+	readonly defaultDirectory?: URI;
+	/**
+	 * Characters that should make a client issue a `completions` request.
+	 *
+	 * Only advertise what the host can actually answer: every completion item
+	 * must carry an attachment, so a trigger with nothing to attach would make
+	 * the client ask and always get nothing back.
+	 */
+	readonly completionTriggerCharacters?: readonly string[];
+	readonly replayBufferCapacity?: number;
+	readonly log?: (message: string) => void;
+}
+
+/**
+ * Supplies the session catalogue. Split out because the catalogue is not part
+ * of root state — clients fetch it imperatively and keep it fresh from
+ * `root/session*` notifications.
+ */
+export interface SessionCatalogue {
+	list(limit: number | undefined, cursor: string | undefined): Promise<ListSessionsResult>;
+}
+
+/**
+ * Handles the session lifecycle commands. Kept behind an interface so the core
+ * router stays agnostic of how sessions are actually backed.
+ */
+export interface SessionLifecycleHandler {
+	create(params: CreateSessionParams): void | Promise<void>;
+	dispose(channel: URI): void | Promise<void>;
+}
+
+/** Handles interactive terminal lifecycle commands. */
+export interface TerminalHandler {
+	create(params: CreateTerminalParams, clientId: string): void | Promise<void>;
+	dispose(channel: URI): void | Promise<void>;
+}
+
+/** Post-commit hook for actions a client dispatched. */
+export type ClientActionListener = (channel: URI, action: StateAction) => void;
+
+/** Observes every accepted action after it has been reduced and broadcast. */
+export type CommittedActionListener = (channel: URI, action: StateAction) => void;
+
+/**
+ * Pre-commit check for actions a client dispatched.
+ *
+ * Returns a reason to refuse the action, or `undefined` to accept it. This runs
+ * *before* the reducer, which is the only point where refusing is meaningful:
+ * once an action is applied and broadcast, every client has already moved on.
+ */
+export type ClientActionValidator = (channel: URI, action: StateAction, clientId: string) => string | undefined;
+
+/** Notified when the number of clients subscribed to a channel changes. */
+export type SubscriberCountListener = (channel: URI, count: number) => void;
+
+/**
+ * Materialises a channel that exists durably but is not yet in memory.
+ *
+ * A client lists sessions and then subscribes to one; only sessions this host
+ * created are live, so the rest have to be loaded on demand. Returning `false`
+ * means the channel genuinely does not exist.
+ */
+export interface ChannelHydrator {
+	hydrate(channel: URI): Promise<boolean>;
+}
+
+/** Serves the pre-creation session configuration exchange. */
+export interface SessionConfigHandler {
+	resolve(params: ResolveSessionConfigParams): ResolveSessionConfigResult | Promise<ResolveSessionConfigResult>;
+	completions(
+		params: SessionConfigCompletionsParams,
+	): SessionConfigCompletionsResult | Promise<SessionConfigCompletionsResult>;
+}
+
+/** Loads older turns into a chat. */
+export interface TurnPagingHandler {
+	fetchTurns(params: FetchTurnsParams): Promise<FetchTurnsResult>;
+}
+
+/** Serves inline `completions` for a chat's message input. */
+export interface CompletionHandler {
+	complete(params: CompletionsParams): Promise<CompletionsResult>;
+}
+
+/**
+ * Opens filesystem watchers. Separate from {@link ResourceHandler} because a
+ * watch owns a live resource with its own lifetime, whereas the rest of the
+ * family is request/response.
+ */
+export interface ResourceWatchHandler {
+	create(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult>;
+}
+
+/** Serves the host side of the connection-level `resource*` family. */
+export interface ResourceHandler {
+	read(params: ResourceReadParams): Promise<ResourceReadResult>;
+	write(params: ResourceWriteParams): Promise<Record<string, never>>;
+	list(uri: string): Promise<ResourceListResult>;
+	resolve(params: ResourceResolveParams): Promise<ResourceResolveResult>;
+	mkdir(params: ResourceMkdirParams): Promise<Record<string, never>>;
+	delete(params: ResourceDeleteParams): Promise<Record<string, never>>;
+	move(params: ResourceMoveParams): Promise<Record<string, never>>;
+	copy(params: ResourceCopyParams): Promise<Record<string, never>>;
+}
+
+export class AhpHost {
+	readonly #store = new StateStore();
+	readonly #sequencer: Sequencer;
+	readonly #options: HostOptions;
+	readonly #connections = new Set<ClientConnection>();
+	/** `reconnect` omits clientInfo; an undefined value still records an id seen by this host process. */
+	readonly #clientInfoById = new Map<string, InitializeParams["clientInfo"]>();
+	#capabilities: HostCapabilities = {};
+	readonly #actionListeners = new Set<ClientActionListener>();
+	readonly #committedActionListeners = new Set<CommittedActionListener>();
+	readonly #actionValidators = new Set<ClientActionValidator>();
+	readonly #subscriberListeners = new Set<SubscriberCountListener>();
+
+	constructor(options: HostOptions = {}) {
+		this.#options = options;
+		this.#sequencer = new Sequencer(options.replayBufferCapacity);
+	}
+
+	get store(): StateStore {
+		return this.#store;
+	}
+
+	/** Removes a channel and releases every connection subscribed to that identity. */
+	deleteChannel(channel: URI): boolean {
+		const deleted = this.#store.delete(channel);
+		let released = false;
+		for (const connection of this.#connections) {
+			if (connection.isSubscribed(channel)) {
+				connection.unsubscribe(channel);
+				released = true;
+			}
+		}
+		if (released) {
+			this.#notifySubscriberCount(channel);
+		}
+		return deleted;
+	}
+
+	get serverSeq(): number {
+		return this.#sequencer.current;
+	}
+
+	/**
+	 * Declares what this host serves.
+	 *
+	 * Merges into whatever was declared before, so a caller can wire one area
+	 * at a time without restating the rest.
+	 */
+	serve(capabilities: HostCapabilities): void {
+		this.#capabilities = { ...this.#capabilities, ...capabilities };
+	}
+
+	// ── Connection lifecycle ────────────────────────────────────────────────
+
+	/** Attaches a transport. The `clientId` is not known until `initialize`. */
+	accept(transport: Transport): ClientConnection {
+		const connection = new ClientConnection(transport);
+		this.#connections.add(connection);
+		transport.onMessage((message) => {
+			this.#handleMessage(connection, message);
+		});
+		transport.onClose(() => {
+			this.#connections.delete(connection);
+			// A dropped socket releases its subscriptions just like an explicit
+			// unsubscribe; resources tied to them must not outlive the client.
+			for (const channel of connection.subscriptions) {
+				this.#notifySubscriberCount(channel);
+			}
+		});
+		return connection;
+	}
+
+	// ── Message routing ─────────────────────────────────────────────────────
+
+	#handleMessage(connection: ClientConnection, message: unknown): void {
+		if (isJsonRpcRequest(message)) {
+			void this.#handleRequest(connection, message);
+			return;
+		}
+		if (isJsonRpcNotification(message)) {
+			this.#handleNotification(connection, message);
+			return;
+		}
+		this.#log(`Ignoring unroutable message: ${JSON.stringify(message).slice(0, 200)}`);
+	}
+
+	async #handleRequest(connection: ClientConnection, request: JsonRpcRequest): Promise<void> {
+		try {
+			const result = await this.#dispatchRequest(connection, request);
+			connection.send(successResponse(request.id, result));
+		} catch (error) {
+			const protocolError =
+				error instanceof ProtocolError
+					? error
+					: new ProtocolError(JsonRpcErrorCodes.InternalError, error instanceof Error ? error.message : String(error));
+			this.#log(`${request.method} failed: ${protocolError.message}`);
+			connection.send(errorResponse(request.id, protocolError.code, protocolError.message, protocolError.data));
+		}
+	}
+
+	async #dispatchRequest(connection: ClientConnection, request: JsonRpcRequest): Promise<unknown> {
+		const handshake = request.method === "initialize" || request.method === "reconnect";
+		if (handshake && connection.clientId) {
+			throw new ProtocolError(JsonRpcErrorCodes.InvalidRequest, "Connection is already initialized");
+		}
+		if (!handshake && request.method !== "ping" && !connection.clientId) {
+			throw new ProtocolError(JsonRpcErrorCodes.InvalidRequest, "initialize or reconnect must be the first request");
+		}
+
+		let protocolVersion = "";
+		if (request.method === "initialize") {
+			const params = request.params as InitializeParams | undefined;
+			validateInitialize(params);
+			protocolVersion = negotiateProtocolVersion(params.protocolVersions);
+			connection.workarounds.identify(params.clientInfo ?? this.#clientInfoById.get(params.clientId));
+		} else if (request.method === "reconnect") {
+			const params = request.params as ReconnectParams | undefined;
+			validateReconnect(params);
+			connection.workarounds.identify(this.#clientInfoById.get(params.clientId));
+		}
+		connection.workarounds.applyToIncoming(request);
+		if (ROOT_COMMANDS.has(request.method as keyof CommandMap) && readChannel(request.params) !== ROOT_CHANNEL) {
+			throw ProtocolError.invalidParams(`${request.method} requires channel ${ROOT_CHANNEL}`);
+		}
+		switch (request.method) {
+			// `ping` must be answered whether or not the client has completed
+			// `initialize` or holds any subscription.
+			case "ping":
+				return null;
+			case "initialize":
+				return this.#initialize(connection, request.params as InitializeParams, protocolVersion);
+			case "reconnect":
+				return this.#reconnect(connection, request.params as ReconnectParams);
+			case "subscribe":
+				return await this.#subscribe(connection, request.params as SubscribeParams);
+			case "listSessions": {
+				const params = (request.params ?? {}) as { limit?: number; cursor?: string };
+				if (!this.#capabilities.catalogue) {
+					return { items: [] } satisfies ListSessionsResult;
+				}
+				return this.#capabilities.catalogue.list(params.limit, params.cursor);
+			}
+			case "createSession": {
+				if (!this.#capabilities.sessions) {
+					throw ProtocolError.methodNotFound("createSession");
+				}
+				await this.#capabilities.sessions.create(request.params as CreateSessionParams);
+				return null;
+			}
+			case "disposeSession": {
+				if (!this.#capabilities.sessions) {
+					throw ProtocolError.methodNotFound("disposeSession");
+				}
+				const channel = readChannel(request.params);
+				if (!channel) {
+					throw ProtocolError.invalidParams("disposeSession requires a channel");
+				}
+				this.#assertCompatibleChannel(channel, "session", "disposeSession");
+				await this.#capabilities.sessions.dispose(channel);
+				return null;
+			}
+			case "createTerminal": {
+				if (!this.#capabilities.terminals) {
+					throw ProtocolError.methodNotFound("createTerminal");
+				}
+				await this.#capabilities.terminals.create(request.params as CreateTerminalParams, connection.clientId);
+				return null;
+			}
+			case "disposeTerminal": {
+				if (!this.#capabilities.terminals) {
+					throw ProtocolError.methodNotFound("disposeTerminal");
+				}
+				const channel = readChannel(request.params);
+				if (!channel) {
+					throw ProtocolError.invalidParams("disposeTerminal requires a channel");
+				}
+				this.#assertCompatibleChannel(channel, "terminal", "disposeTerminal");
+				await this.#capabilities.terminals.dispose(channel);
+				return null;
+			}
+			case "resourceRead":
+				return this.#requireResources().read(request.params as ResourceReadParams);
+			case "resourceWrite":
+				return this.#requireResources().write(request.params as ResourceWriteParams);
+			case "resourceList":
+				return this.#requireResources().list((request.params as { uri: string }).uri);
+			case "resourceResolve":
+				return this.#requireResources().resolve(request.params as ResourceResolveParams);
+			case "resourceMkdir":
+				return this.#requireResources().mkdir(request.params as ResourceMkdirParams);
+			case "resourceDelete":
+				return this.#requireResources().delete(request.params as ResourceDeleteParams);
+			case "resourceMove":
+				return this.#requireResources().move(request.params as ResourceMoveParams);
+			case "resourceCopy":
+				return this.#requireResources().copy(request.params as ResourceCopyParams);
+			case "resolveSessionConfig": {
+				// A client calls this before `createSession`; answering
+				// MethodNotFound stops it from getting as far as creating one.
+				if (!this.#capabilities.sessionConfig) {
+					return { schema: { type: "object", properties: {} }, values: {} } satisfies ResolveSessionConfigResult;
+				}
+				return this.#capabilities.sessionConfig.resolve(request.params as ResolveSessionConfigParams);
+			}
+			case "sessionConfigCompletions": {
+				if (!this.#capabilities.sessionConfig) {
+					return { items: [] } satisfies SessionConfigCompletionsResult;
+				}
+				return this.#capabilities.sessionConfig.completions(request.params as SessionConfigCompletionsParams);
+			}
+			case "fetchTurns": {
+				// The result carries no turns: the host must dispatch
+				// `chat/turnsLoaded` *before* responding, so the client's state
+				// already holds the page by the time this returns.
+				if (!this.#capabilities.turnPaging) {
+					return {} satisfies FetchTurnsResult;
+				}
+				this.#assertChatChannel(request.params, "fetchTurns");
+				return this.#capabilities.turnPaging.fetchTurns(request.params as FetchTurnsParams);
+			}
+			case "completions": {
+				// Best-effort by contract: a client debounces keystrokes into this,
+				// so an unconfigured host answers with nothing rather than an error.
+				if (!this.#capabilities.completions) {
+					return { items: [] } satisfies CompletionsResult;
+				}
+				this.#assertChatChannel(request.params, "completions");
+				return this.#capabilities.completions.complete(request.params as CompletionsParams);
+			}
+			case "createResourceWatch": {
+				if (!this.#capabilities.resourceWatches) {
+					throw ProtocolError.methodNotFound("createResourceWatch");
+				}
+				return this.#capabilities.resourceWatches.create(request.params as CreateResourceWatchParams);
+			}
+			case "resourceRequest":
+				// No per-resource grants are tracked: a client that reaches this
+				// endpoint already holds the token and can start a session, so a
+				// grant ledger here would imply a boundary that does not exist.
+				// The receiver may still refuse individual operations.
+				return {};
+			default:
+				throw ProtocolError.methodNotFound(request.method);
+		}
+	}
+
+	#assertCompatibleChannel(channel: URI, expected: ChannelKind, method: string): void {
+		const actual = this.#store.kindOf(channel);
+		if (actual !== undefined && actual !== expected) {
+			throw ProtocolError.invalidParams(`${method} cannot target a ${actual} channel`);
+		}
+	}
+
+	#assertChatChannel(params: unknown, method: string): void {
+		const channel = readChannel(params);
+		if (!channel) throw ProtocolError.invalidParams(`${method} requires a channel`);
+		if ((this.#store.kindOf(channel) ?? channelKind(channel)) !== "chat") {
+			throw ProtocolError.invalidParams(`${method} requires a chat channel`);
+		}
+	}
+
+	#requireResources(): ResourceHandler {
+		if (!this.#capabilities.resources) {
+			throw ProtocolError.methodNotFound("resource*");
+		}
+		return this.#capabilities.resources;
+	}
+
+	#handleNotification(connection: ClientConnection, message: JsonRpcNotification): void {
+		if (!connection.clientId) {
+			this.#log(`Ignoring ${message.method} before initialize or reconnect`);
+			return;
+		}
+		connection.workarounds.applyToIncoming(message);
+		switch (message.method) {
+			case "unsubscribe": {
+				const channel = readChannel(message.params);
+				if (channel) {
+					connection.unsubscribe(channel);
+					this.#notifySubscriberCount(channel);
+				}
+				return;
+			}
+			case "dispatchAction":
+				this.#dispatchClientAction(connection, message.params as DispatchActionParams);
+				return;
+			default:
+				this.#log(`Ignoring unknown notification: ${message.method}`);
+		}
+	}
+
+	// ── Handshake ───────────────────────────────────────────────────────────
+
+	async #initialize(
+		connection: ClientConnection,
+		params: InitializeParams,
+		protocolVersion: string,
+	): Promise<InitializeResult> {
+		this.#bindClient(connection, params.clientId);
+
+		const identifiedClient = params.clientInfo ?? this.#clientInfoById.get(params.clientId);
+		this.#clientInfoById.set(params.clientId, identifiedClient);
+
+		const snapshots: Snapshot[] = [];
+		for (const uri of params.initialSubscriptions ?? []) {
+			if (!this.#store.has(uri)) {
+				// Same lazy load as `subscribe`: a client reconnecting with its
+				// previously-open sessions must get them back.
+				await this.#capabilities.hydrator?.hydrate(uri).catch(() => false);
+			}
+			const snapshot = this.#trySubscribe(connection, uri);
+			if (snapshot) {
+				snapshots.push(snapshot);
+			}
+		}
+
+		return {
+			protocolVersion,
+			serverSeq: this.#sequencer.current,
+			...(this.#options.serverInfo ? { serverInfo: this.#options.serverInfo } : {}),
+			...(this.#options.defaultDirectory ? { defaultDirectory: this.#options.defaultDirectory } : {}),
+			...(this.#options.completionTriggerCharacters
+				? { completionTriggerCharacters: [...this.#options.completionTriggerCharacters] }
+				: {}),
+			snapshots,
+		};
+	}
+
+	async #reconnect(connection: ClientConnection, params: ReconnectParams): Promise<ReconnectResult> {
+		const knownClient = this.#clientInfoById.has(params.clientId);
+		if (!knownClient) {
+			this.#clientInfoById.set(params.clientId, undefined);
+		}
+		this.#bindClient(connection, params.clientId);
+
+		const requested = params.subscriptions ?? [];
+		const missing: URI[] = [];
+		connection.subscriptions.clear();
+		for (const uri of requested) {
+			if (uri !== ROOT_CHANNEL && !this.#store.has(uri)) {
+				await this.#capabilities.hydrator?.hydrate(uri).catch(() => false);
+			}
+			if (uri === ROOT_CHANNEL || this.#store.has(uri)) {
+				this.#addSubscription(connection, uri);
+			} else {
+				missing.push(uri);
+			}
+		}
+
+		const lastSeen = params.lastSeenServerSeq ?? 0;
+		if (knownClient && this.#sequencer.canReplayFrom(lastSeen)) {
+			const actions = this.#sequencer.replayFrom(lastSeen, connection.subscriptions);
+			return { type: ReconnectResultType.Replay, actions, missing };
+		}
+
+		// Replay is unavailable after buffer eviction or in a fresh host process.
+		// Durable subscriptions were hydrated above; return current snapshots.
+		const snapshots: Snapshot[] = [];
+		for (const uri of connection.subscriptions) {
+			const snapshot = this.#store.snapshot(uri, this.#sequencer.current);
+			if (snapshot) {
+				snapshots.push(snapshot);
+			}
+		}
+		return { type: ReconnectResultType.Snapshot, snapshots };
+	}
+
+	/** Replaces a half-open socket when the same clientId reconnects. */
+	#bindClient(connection: ClientConnection, clientId: string): void {
+		for (const previous of this.#connections) {
+			if (previous !== connection && previous.clientId === clientId) {
+				this.#connections.delete(previous);
+				previous.transport.close();
+			}
+		}
+		connection.clientId = clientId;
+	}
+
+	// ── Subscriptions ───────────────────────────────────────────────────────
+
+	async #subscribe(connection: ClientConnection, params: SubscribeParams): Promise<SubscribeResult> {
+		const channel = params?.channel;
+		if (typeof channel !== "string") {
+			throw ProtocolError.invalidParams("subscribe requires a channel");
+		}
+		if (!this.#store.has(channel)) {
+			// Not in memory does not mean it does not exist: a session from the
+			// catalogue lives on disk until someone opens it. The hydrator gets the
+			// first chance to resolve known aliases before the strict scheme check.
+			const hydrated = (await this.#capabilities.hydrator?.hydrate(channel)) ?? false;
+			if (!hydrated) {
+				throw channelKind(channel) === undefined
+					? ProtocolError.invalidParams(`Unsupported channel scheme: ${channel}`)
+					: ProtocolError.notFound(channel);
+			}
+		}
+		const snapshot = this.#trySubscribe(connection, channel);
+		return snapshot ? { snapshot } : {};
+	}
+
+	#trySubscribe(connection: ClientConnection, channel: URI): Snapshot | undefined {
+		// Membership in the store is the real test: a session opened at a
+		// non-standard URI has no recognised scheme but is a perfectly valid
+		// channel.
+		if (!this.#store.has(channel)) {
+			this.#log(`Ignoring subscription to unknown channel: ${channel}`);
+			return undefined;
+		}
+		this.#addSubscription(connection, channel);
+		return this.#store.snapshot(channel, this.#sequencer.current);
+	}
+
+	#addSubscription(connection: ClientConnection, channel: URI): void {
+		if (connection.isSubscribed(channel)) return;
+		connection.subscribe(channel);
+		this.#notifySubscriberCount(channel);
+	}
+
+	// ── Actions ─────────────────────────────────────────────────────────────
+
+	#dispatchClientAction(connection: ClientConnection, params: DispatchActionParams): void {
+		const channel = params?.channel;
+		const action = params?.action as unknown;
+		if (typeof channel !== "string" || typeof params?.clientSeq !== "number" || !isActionLike(action)) {
+			this.#log("Ignoring malformed dispatchAction");
+			return;
+		}
+		// Spec: an action naming a channel that does not exist is silently
+		// ignored — no echo, no rejection.
+		if (!this.#store.has(channel)) {
+			this.#log(`Ignoring action for unknown channel: ${channel}`);
+			return;
+		}
+		const origin = { clientId: connection.clientId, clientSeq: params.clientSeq };
+		if (!isClientDispatchable(action as never)) {
+			this.#rejectAction(channel, action, origin, `Action is not client-dispatchable: ${action.type}`);
+			return;
+		}
+		const kind = this.#store.kindOf(channel);
+		if (kind && !actionBelongsToChannel(action.type, kind)) {
+			this.#rejectAction(channel, action, origin, `${action.type} does not belong on a ${kind} channel`);
+			return;
+		}
+		for (const validator of this.#actionValidators) {
+			const reason = validator(channel, action, connection.clientId);
+			if (reason !== undefined) {
+				this.#rejectAction(channel, action, origin, reason);
+				return;
+			}
+		}
+		this.#commit(channel, action, origin);
+		this.#emitClientAction(channel, action);
+	}
+
+	/**
+	 * Applies a host-originated action and broadcasts it.
+	 *
+	 * This is the single write path for everything the agent backend produces.
+	 */
+	dispatchServerAction(channel: URI, action: StateAction): void {
+		if (!this.#store.has(channel)) {
+			this.#log(`Dropping server action for unknown channel: ${channel}`);
+			return;
+		}
+		this.#commit(channel, action, undefined);
+	}
+
+	#commit(channel: URI, action: StateAction, origin: ActionEnvelope["origin"]): void {
+		this.#store.apply(channel, action);
+		const envelope: ActionEnvelope = {
+			channel,
+			action,
+			serverSeq: this.#sequencer.next(),
+			origin,
+		};
+		this.#sequencer.retain(envelope);
+		this.#broadcast(channel, notification("action", envelope));
+		this.#emitCommittedAction(channel, action);
+	}
+
+	/** Echoes a rejected action so the write-ahead client can roll it back. */
+	#rejectAction(channel: URI, action: StateAction, origin: ActionEnvelope["origin"], rejectionReason: string): void {
+		const envelope: ActionEnvelope = {
+			channel,
+			action,
+			serverSeq: this.#sequencer.next(),
+			origin,
+			rejectionReason,
+		};
+		this.#sequencer.retain(envelope);
+		this.#broadcast(channel, notification("action", envelope));
+	}
+
+	// ── Broadcast ───────────────────────────────────────────────────────────
+
+	/** Sends a channel-scoped message to every client subscribed to that channel. */
+	#broadcast(channel: URI, message: JsonRpcNotification): void {
+		for (const connection of this.#connections) {
+			if (connection.isSubscribed(channel)) {
+				connection.send(message);
+			}
+		}
+	}
+
+	/** How many connected clients are subscribed to a channel. */
+	subscriberCount(channel: URI): number {
+		let count = 0;
+		for (const connection of this.#connections) {
+			if (connection.isSubscribed(channel)) {
+				count += 1;
+			}
+		}
+		return count;
+	}
+
+	/**
+	 * Observes changes to a channel's subscriber count.
+	 *
+	 * Some channels own a resource that should not outlive interest in it — a
+	 * filesystem watcher has no dispose command and is released when its last
+	 * subscriber goes away.
+	 */
+	onSubscriberCountChanged(listener: SubscriberCountListener): () => void {
+		this.#subscriberListeners.add(listener);
+		return () => this.#subscriberListeners.delete(listener);
+	}
+
+	#notifySubscriberCount(channel: URI): void {
+		const count = this.subscriberCount(channel);
+		for (const listener of this.#subscriberListeners) {
+			try {
+				listener(channel, count);
+			} catch (error) {
+				this.#log(`Subscriber-count listener threw for ${channel}: ${String(error)}`);
+			}
+		}
+	}
+
+	/** Emits a protocol notification (`root/sessionAdded`, `auth/required`, …). */
+	notify(channel: URI, method: string, params: Record<string, unknown>): void {
+		this.#broadcast(channel, notification(method, { channel, ...params }));
+	}
+
+	// ── Side effects ────────────────────────────────────────────────────────
+
+	/**
+	 * Registers a post-commit hook for client-dispatched actions.
+	 *
+	 * Actions are applied and broadcast *before* the hook runs, so the
+	 * authoritative state already reflects the action by the time a backend is
+	 * asked to act on it. Rejected actions never reach the hook.
+	 */
+	onClientAction(listener: ClientActionListener): () => void {
+		this.#actionListeners.add(listener);
+		return () => this.#actionListeners.delete(listener);
+	}
+
+	/**
+	 * Observes every accepted action after its envelope has been broadcast.
+	 *
+	 * Cross-channel projections use this boundary so a derived session action is
+	 * always sequenced after the chat action that caused it. Rejected actions do
+	 * not reach observers.
+	 */
+	onActionCommitted(listener: CommittedActionListener): () => void {
+		this.#committedActionListeners.add(listener);
+		return () => this.#committedActionListeners.delete(listener);
+	}
+
+	/**
+	 * Registers a pre-commit check.
+	 *
+	 * Needed whenever accepting an action would leave the host unable to carry
+	 * it out: applying it anyway would show the client a change the backend
+	 * never made, which is worse than a refusal it can report.
+	 */
+	addClientActionValidator(validator: ClientActionValidator): () => void {
+		this.#actionValidators.add(validator);
+		return () => this.#actionValidators.delete(validator);
+	}
+
+	#emitClientAction(channel: URI, action: StateAction): void {
+		for (const listener of this.#actionListeners) {
+			try {
+				listener(channel, action);
+			} catch (error) {
+				// A failing side effect must not corrupt the action stream that
+				// other clients have already observed.
+				this.#log(`Side effect for ${action.type} threw: ${String(error)}`);
+			}
+		}
+	}
+
+	#emitCommittedAction(channel: URI, action: StateAction): void {
+		for (const listener of this.#committedActionListeners) {
+			try {
+				listener(channel, action);
+			} catch (error) {
+				this.#log(`Post-commit observer for ${action.type} threw: ${String(error)}`);
+			}
+		}
+	}
+
+	#log(message: string): void {
+		this.#options.log?.(`[ahp-host] ${message}`);
+	}
+}