@skaile/forge-app-actions 0.0.0-stage → 0.2.0

package/src/runtime/server/utils/client-capability-bridge.ts

@@ -0,0 +1,1201 @@
+// server/utils/client-capability-bridge.ts
+//
+// NOTE: this file must live *directly* in `runtime/server/utils/`. The Nuxt
+// module auto-imports that directory NON-recursively (`src/module.ts:116`), so
+// a subdirectory would silently never reach consumers.
+
+import type { Capability } from "@skaile/workspaces/sdk/types";
+import * as z from "zod";
+import {
+  type CapabilityHandlerCtx,
+  type CapabilityRegistry,
+  capabilityRegistry,
+} from "./capability-registry";
+
+// ── Session-key contract ───────────────────────────────────────────────────
+//
+// The bridge keys everything — announced registries, owners, senders — by an
+// **opaque string**. It never parses the key or assumes a shape. Each app picks
+// the identity its SSE stream already filters on (spec §4):
+//
+//   forge-workspace / forge-site  →  a constant (one session per process)
+//   forge-project                 →  `` `${userId}:${slug}:${mode}` ``
+//   forge-concept                 →  the concept name
+//   forge-assistant               →  its `processKey` getter
+//
+// Callers must derive the key **server-side** wherever possible. A browser that
+// can name its own session key can announce into someone else's session.
+
+/** Commands the bridge pushes upstream toward the agent. */
+export type ClientCapabilityCommand =
+  | { type: "capability_register"; capabilities: Capability[] }
+  | { type: "capability_deregister"; names: string[] }
+  | { type: "capability_result"; callId: string; result: unknown };
+
+/**
+ * Transport that delivers a command **upstream to the agent** for one session
+ * key. Apps register it from their agent-manager.
+ *
+ * It must NOT be `session.dispatcher.sendCommand`. `SessionDispatcher.shouldPersist()`
+ * is a pure denylist against `TRANSIENT_TYPES`, and none of the three capability
+ * command types appear in it — a dispatcher send is therefore written into the
+ * JSONL message store and resurfaces as a chat message. Use
+ * `processManager.sendCommand(processKey, command)`, which goes straight to the
+ * transport with no message store involved.
+ */
+export type ClientCapabilitySender = (command: ClientCapabilityCommand) => Promise<void> | void;
+
+/** One `capability_invoked` on its way down to the browser. */
+export interface ClientCapabilityInvocation {
+  /** Correlation token minted by the agent runner. */
+  callId: string;
+  /** Name as invoked — may be a deprecated alias of the handler's real name. */
+  name: string;
+  /** Raw, unvalidated arguments. The browser validates against the zod schema. */
+  input: unknown;
+  /** The opaque key this invocation was routed under. */
+  sessionKey: string;
+  /**
+   * Spec §L4 — the single subscriber this invocation is addressed to, or `null`
+   * when the app does not track subscribers (then it goes to whoever is
+   * listening, the pre-05 behaviour).
+   *
+   * The app's invoker is expected to tag its SSE frame with this so only the
+   * owning tab runs the handler. `useCapabilityInvocations()` in the browser
+   * enforces the same rule a second time as defence in depth, for apps whose
+   * fan-out cannot filter.
+   */
+  ownerId: string | null;
+  /**
+   * Who started this invocation. Absent means the workspace agent; `"driver"`
+   * is a server-side caller using {@link ClientCapabilityBridge.call}. The
+   * browser never reads it — it is for logs and the app's `capability_invoked`
+   * frame only.
+   */
+  invokedBy?: "agent" | "driver";
+}
+
+/**
+ * Transport that delivers an invocation **downstream to the browser** for one
+ * session key — in every forge app this is the existing SSE fan-out.
+ *
+ * Returns whether at least one live UI actually received it. `false` is what
+ * makes spec §L2 work: the bridge answers the agent immediately with a
+ * no-UI-attached error instead of parking a call nobody will ever resolve.
+ */
+export type ClientCapabilityInvoker = (
+  invocation: ClientCapabilityInvocation,
+) => boolean | Promise<boolean>;
+
+/** Error text the agent receives when an invocation arrives with no live UI (§L2). */
+export const NO_UI_ATTACHED_ERROR =
+  "No UI is attached to this session, so the capability cannot run. " +
+  "Tell the user to open the app in a browser and try again.";
+
+/** Error text used when a parked call is dropped because its session ended. */
+export const SESSION_ENDED_ERROR = "The UI session ended before the capability returned a result.";
+
+/**
+ * Spec §L1 — how long the last subscriber for a session key may stay gone
+ * before its browser-announced capabilities are deregistered.
+ *
+ * A page reload drops and re-opens the SSE connection within a few hundred
+ * milliseconds; 5 s is comfortably longer than that and short enough that the
+ * agent stops advertising a dead UI quickly.
+ */
+export const DEFAULT_DISCONNECT_GRACE_MS = 5_000;
+
+/**
+ * Spec §L3 — fallback per-call timeout for a capability that declares no
+ * `callTimeoutMs` of its own.
+ *
+ * Deliberately **under** the runner's own `DEFAULT_CAPABILITY_CALL_TIMEOUT_MS`
+ * (60 s). The runner's timer is the last-resort backstop; this one has to fire
+ * first or it buys nothing.
+ */
+export const DEFAULT_CLIENT_CALL_TIMEOUT_MS = 30_000;
+
+/** Stable prefix of every §L3 timeout message, so callers can match on it. */
+export const CALL_TIMEOUT_ERROR_PREFIX = "The UI did not answer";
+
+/** Error text the agent receives when a parked call outlives its timeout (§L3). */
+export function capabilityTimeoutError(name: string, timeoutMs: number): string {
+  return (
+    `${CALL_TIMEOUT_ERROR_PREFIX} "${name}" within ${Math.round(timeoutMs / 1000)}s. ` +
+    "The browser may have navigated away or the handler may be stuck. " +
+    "Tell the user what you were trying to do and ask them to retry."
+  );
+}
+
+/** What the bridge remembers about one in-flight invocation. */
+export interface ParkedCall extends ClientCapabilityInvocation {
+  /** `Date.now()` at park time. */
+  parkedAt: number;
+  /** The §L3 deadline this call is under, in ms. */
+  timeoutMs: number;
+  /**
+   * Set only for a call made through {@link ClientCapabilityBridge.call}: the
+   * browser's answer (or a session-end `{ error }`) goes here instead of
+   * upstream to the agent.
+   */
+  settle?: (result: unknown) => void;
+  /** Companion of {@link settle}: receives the §L3 timeout. */
+  reject?: (error: Error) => void;
+}
+
+/** Outcome of {@link ClientCapabilityBridge.invoke}. */
+export type InvokeOutcome =
+  /** Parked and handed to a live UI; a `capability_result` is expected. */
+  | "dispatched"
+  /** §L2 — answered immediately with {@link NO_UI_ATTACHED_ERROR}; never parked. */
+  | "no-ui";
+
+export interface ClientCapabilityBridgeLogger {
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+/** The `list()` half of a server-side capability registry. */
+export interface ServerCapabilitySource {
+  list(): Capability[];
+}
+
+export interface ClientCapabilityBridgeOptions {
+  /**
+   * Server-side registry merged into every registration. Defaults to the
+   * process-wide `capabilityRegistry` singleton, which keeps working untouched.
+   */
+  serverRegistry?: ServerCapabilitySource;
+  logger?: ClientCapabilityBridgeLogger;
+  /** §L1 disconnect grace period. Defaults to {@link DEFAULT_DISCONNECT_GRACE_MS}. */
+  disconnectGraceMs?: number;
+  /**
+   * §L3 fallback per-call timeout, used when the announced capability declares
+   * no `callTimeoutMs`. Defaults to {@link DEFAULT_CLIENT_CALL_TIMEOUT_MS}.
+   */
+  callTimeoutMs?: number;
+}
+
+/** What the bridge remembers about one announcing session. */
+export interface ClientCapabilitySessionState {
+  /** Normalised, wire-shaped capabilities the browser announced. */
+  capabilities: Capability[];
+  /** §L4 owner: the most recent *genuine* announcer. See {@link ClientCapabilityBridge.announce}. */
+  ownerId: string | null;
+  /** `Date.now()` of the most recent announcement. */
+  announcedAt: number;
+  /**
+   * Announce **sequence number** per announcing subscriber, highest wins. Kept
+   * alongside {@link ownerId} so that when the incumbent owner's SSE connection
+   * goes away the bridge can fall back to the next-most-recent announcer that
+   * is still connected, instead of routing into a closed tab (§L4).
+   *
+   * A counter, not a timestamp: two tabs can easily announce inside the same
+   * millisecond, and `Date.now()` would then make last-writer-wins a coin flip
+   * decided by Map insertion order. The counter cannot tie.
+   */
+  announcers: Map<string, number>;
+}
+
+// ── Announcement validation ────────────────────────────────────────────────
+// Announcements arrive as untrusted browser input, so consumer routes should
+// parse before handing them to `announce()`.
+
+/** Zod schema for one announced capability descriptor. */
+export const clientCapabilityDescriptorSchema = z.object({
+  name: z.string().min(1),
+  displayName: z.string().optional(),
+  description: z.string(),
+  inputSchema: z.record(z.string(), z.unknown()),
+  outputSchema: z.record(z.string(), z.unknown()).optional(),
+  side: z.literal("client").optional(),
+  scope: z.enum(["session", "turn"]).optional(),
+  requiresApproval: z.boolean().optional(),
+  kind: z.enum(["effect", "render", "query"]).optional(),
+  audience: z.array(z.enum(["llm", "user", "runtime"])).optional(),
+  promptFragment: z.string().optional(),
+  callTimeoutMs: z.number().optional(),
+  render: z.unknown().optional(),
+});
+
+/** Zod schema for the body of an upward announce POST. */
+export const clientCapabilityAnnouncementSchema = z.object({
+  subscriberId: z.string().optional(),
+  capabilities: z.array(clientCapabilityDescriptorSchema),
+});
+
+/**
+ * Zod schema for the body of the upward `capability-result` POST — the browser
+ * answering a parked `callId`.
+ *
+ * `result` is deliberately opaque: it is either the handler's return value or an
+ * `{ error: string }` envelope, and the runner distinguishes the two itself
+ * (`resolveCapabilityResult` rejects the LLM's tool call when `"error" in result`).
+ * The bridge never inspects it.
+ */
+export const clientCapabilityResultSchema = z.object({
+  callId: z.string().min(1),
+  result: z.unknown(),
+});
+
+/** Body of an upward `capability-result` POST, minus app-specific session fields. */
+export type IncomingClientCapabilityResult = z.infer<typeof clientCapabilityResultSchema>;
+
+/**
+ * A capability descriptor **as it arrives on the wire** — exactly what
+ * {@link clientCapabilityDescriptorSchema} produces, which is what
+ * {@link ClientCapabilityBridge.announce} accepts.
+ *
+ * Looser than {@link ClientCapabilityDescriptor} in two places, both because
+ * the bridge is the authority rather than the browser:
+ *  - `side` is optional; {@link ClientCapabilityBridge} stamps it either way.
+ *  - `render` is `unknown`; it is narrowed to `RenderSpec` on normalisation.
+ *
+ * A `ClientCapabilityDescriptor` (what `useAgentCapabilities().toWire()`
+ * returns) is assignable to this, so the browser-side and server-side types
+ * meet without a cast at the route boundary.
+ */
+export type IncomingClientCapability = z.infer<typeof clientCapabilityDescriptorSchema>;
+
+/**
+ * How many past announcers one session key remembers. Only needed so a
+ * reconnect can be told apart from a first announce (§L4), so a small window is
+ * plenty — and the cap keeps a long-lived key from growing without bound.
+ */
+const MAX_REMEMBERED_ANNOUNCERS = 16;
+
+const defaultLogger: ClientCapabilityBridgeLogger = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(message),
+};
+
+/**
+ * Nitro-side relay between the browser's capability registry and the agent.
+ *
+ * Responsibilities in this (announce-half) ticket:
+ *  - own the announced client capability list per opaque session key
+ *  - merge it with the server-side registry into ONE `capability_register`
+ *  - on a name collision the **server entry wins** and a warning is logged (§L6)
+ *  - only push upstream when the merged list actually changed (§L5)
+ *
+ * And the invoke half (ticket 04):
+ *  - route a `capability_invoked` whose name the browser announced downstream
+ *    over the app's existing SSE fan-out ({@link setInvoker})
+ *  - park the `callId` until the browser POSTs a result ({@link resolve})
+ *  - §L2: an invocation that reaches no live UI is answered **immediately** with
+ *    {@link NO_UI_ATTACHED_ERROR}. It is never parked, so it can never hang.
+ *
+ * And the lifecycle half (ticket 05):
+ *  - §L1 subscriber counting per session key ({@link addSubscriber} /
+ *    {@link removeSubscriber}), with a grace period before the last
+ *    disconnect deregisters browser-owned capabilities
+ *  - §L2 sharpened: liveness is now *this key's* subscriber count, not "is
+ *    anything at all listening"
+ *  - §L3 per-call timeout, defaulting to {@link DEFAULT_CLIENT_CALL_TIMEOUT_MS}
+ *    and overridable per capability via `callTimeoutMs`
+ *  - §L4 last-writer-wins owner election ({@link routeTo}), stamped onto every
+ *    invocation as {@link ClientCapabilityInvocation.ownerId}
+ *  - §L5 {@link sync} emits `capability_deregister` for names that dropped out
+ *    of the merged list, and stays silent when nothing changed
+ *
+ * ── What the *model* actually sees ────────────────────────────────────────
+ * Everything above is exact at the **registry** level: after a §L1 grace expiry
+ * the runner's `CapabilityRegistry` really has dropped the client capability,
+ * and after a re-announce it really has it back.
+ *
+ * The LLM's view lags, and by how much depends on the harness. `composeTools()`
+ * runs inside `startQuery()` — a session's first prompt — and later prompts
+ * reuse that query via `streamInput`, so a tool the model already materialised
+ * stays materialised for the rest of the conversation. Observed live against
+ * `skaile serve` + the Claude Agent SDK harness, however, capabilities reach the
+ * model through a *deferred* MCP surface it has to search for: after a §L1
+ * deregistration mid-conversation the model's `ToolSearch` returned "no
+ * matching deferred tools" and it told the user the tool was unavailable —
+ * i.e. the deregistration did land within the same conversation.
+ *
+ * Do not rely on that. It is a property of how one harness exposes the registry,
+ * not a guarantee of the protocol. The invariant to design against is: §L1 is
+ * the advertisement, §L2 is the enforcement. A model that calls a capability
+ * whose UI has gone gets {@link NO_UI_ATTACHED_ERROR} immediately, whatever its
+ * tool list happens to say.
+ */
+export class ClientCapabilityBridge {
+  private readonly sessions = new Map<string, ClientCapabilitySessionState>();
+  private readonly senders = new Map<string, ClientCapabilitySender>();
+  private readonly invokers = new Map<string, ClientCapabilityInvoker>();
+  /** In-flight invocations, keyed `${sessionKey}` → `callId` → entry. */
+  private readonly parked = new Map<string, Map<string, ParkedCall>>();
+  /** §L3 timers, parallel to {@link parked}. */
+  private readonly callTimers = new Map<string, Map<string, ReturnType<typeof setTimeout>>>();
+  /**
+   * Live downstream subscribers per session key → **open connection count** for
+   * that subscriber id.
+   *
+   * Ref-counted rather than a plain set because one tab can legitimately hold
+   * more than one stream for a key (a remount that opens before the old socket
+   * finishes closing, a second component subscribing). A plain set would let
+   * the first close retire a subscriber the second connection still needs.
+   *
+   * The entry is created on the first {@link addSubscriber} for a key and then
+   * kept **forever**, even when it empties. Its presence is what
+   * {@link tracksSubscribers} reports, and that is what lets an app opt in to
+   * §L1/§L2/§L4 by wiring its SSE endpoint without forcing every app to.
+   */
+  private readonly subscribers = new Map<string, Map<string, number>>();
+  /** §L1 pending grace timers, keyed by session key. */
+  private readonly graceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Last merged list pushed per session key, for the §L5 change diff. */
+  private readonly lastSent = new Map<string, string>();
+  /** Names in the last pushed list, so §L5 can deregister what dropped out. */
+  private readonly lastSentNames = new Map<string, Set<string>>();
+  /** `${sessionKey}::${name}` pairs already warned about, so §L6 logs once. */
+  private readonly warnedCollisions = new Set<string>();
+
+  private readonly serverRegistry: ServerCapabilitySource;
+  private readonly log: ClientCapabilityBridgeLogger;
+  private readonly disconnectGraceMs: number;
+  private readonly defaultCallTimeoutMs: number;
+  /** Monotonic announce counter backing §L4's owner election. */
+  private announceSeq = 0;
+
+  constructor(options: ClientCapabilityBridgeOptions = {}) {
+    this.serverRegistry = options.serverRegistry ?? capabilityRegistry;
+    this.log = options.logger ?? defaultLogger;
+    this.disconnectGraceMs = options.disconnectGraceMs ?? DEFAULT_DISCONNECT_GRACE_MS;
+    this.defaultCallTimeoutMs = options.callTimeoutMs ?? DEFAULT_CLIENT_CALL_TIMEOUT_MS;
+  }
+
+  /**
+   * Record (or replace) the capability list a browser announced for
+   * `sessionKey`. Announcements are whole registries, never deltas.
+   *
+   * §L4 — an announcement re-seats ownership only when it is a genuine *write*:
+   * a subscriber this key has not heard from before, or a registry whose
+   * contents actually changed. An identical re-announce from a subscriber
+   * already on record refreshes liveness and cancels the §L1 grace timer, but
+   * leaves the running order alone.
+   *
+   * That distinction matters because re-announcing is not a rare event. Every
+   * SSE reopen re-announces (§L5), and at least one consumer — forge-concept —
+   * ties its stream to a drawer the user can toggle, so a tab can re-announce
+   * many times a minute without the user meaning anything by it. Under plain
+   * "the newest announce wins", a background tab's reconnect would silently
+   * steal routing from the foreground tab the user is actually looking at.
+   * A genuinely new tab, or a tab that changed what it offers, still wins.
+   *
+   * @returns `true` when the stored client list changed.
+   */
+  announce(
+    sessionKey: string,
+    capabilities: IncomingClientCapability[],
+    options: { subscriberId?: string } = {},
+  ): boolean {
+    const normalised = capabilities.map((c) => this.normalise(c));
+    const previous = this.sessions.get(sessionKey);
+    const changed = signature(previous?.capabilities ?? []) !== signature(normalised);
+    const announcedAt = Date.now();
+
+    // An announcement is proof of life: it cancels a pending §L1 grace timer
+    // even if the SSE connection has not (re)registered yet.
+    this.cancelGrace(sessionKey);
+
+    const announcers = previous?.announcers ?? new Map<string, number>();
+    const { subscriberId } = options;
+    if (subscriberId && (changed || !announcers.has(subscriberId))) {
+      announcers.set(subscriberId, ++this.announceSeq);
+    }
+
+    this.sessions.set(sessionKey, {
+      capabilities: normalised,
+      ownerId: highestAnnouncer(announcers) ?? subscriberId ?? null,
+      announcedAt,
+      announcers,
+    });
+
+    // Let a name that is no longer announced warn again if it comes back.
+    const announcedNames = new Set(normalised.map((c) => c.name));
+    for (const key of [...this.warnedCollisions]) {
+      const [key0, name] = splitWarnKey(key);
+      if (key0 === sessionKey && !announcedNames.has(name)) {
+        this.warnedCollisions.delete(key);
+      }
+    }
+
+    return changed;
+  }
+
+  /**
+   * Drop the announced list for `sessionKey` — the "no browser attached" state.
+   * The sender registration survives, so a later re-announce can still push.
+   *
+   * @returns `true` when something was actually removed.
+   */
+  withdraw(sessionKey: string): boolean {
+    const had = (this.sessions.get(sessionKey)?.capabilities.length ?? 0) > 0;
+    this.sessions.delete(sessionKey);
+    for (const key of [...this.warnedCollisions]) {
+      if (splitWarnKey(key)[0] === sessionKey) this.warnedCollisions.delete(key);
+    }
+    return had;
+  }
+
+  /** Client-announced capabilities for `sessionKey`, in wire shape. */
+  listClient(sessionKey: string): Capability[] {
+    return [...(this.sessions.get(sessionKey)?.capabilities ?? [])];
+  }
+
+  /** True when a browser has announced a non-empty registry for `sessionKey`. */
+  hasClient(sessionKey: string): boolean {
+    return (this.sessions.get(sessionKey)?.capabilities.length ?? 0) > 0;
+  }
+
+  /**
+   * The §L4 owner as elected from announcements alone, ignoring who is still
+   * connected — i.e. the most recent *genuine* announcer (see {@link announce}
+   * for why a bare re-announce does not count as one).
+   *
+   * {@link routeTo} is what routing actually uses; this is the answer for an
+   * app that does not track subscribers, and the fallback when it does but
+   * nobody connected has announced.
+   */
+  ownerOf(sessionKey: string): string | null {
+    return this.sessions.get(sessionKey)?.ownerId ?? null;
+  }
+
+  /**
+   * Spec §L4 — the subscriber an invocation for `sessionKey` should be routed
+   * to right now: **the most recently announced one that is still connected**.
+   *
+   * Plain last-writer-wins ({@link ownerOf}) is the rule while every announcer
+   * is still around. It is not enough on its own: when the newest tab closes,
+   * routing to its dead subscriber id would strand every subsequent call in the
+   * §L2 no-UI branch even though an older tab is sitting there fully able to
+   * answer. So the election is over *live* announcers.
+   *
+   * Returns `null` when the app does not track subscribers (in which case the
+   * announced {@link ownerOf} is used verbatim, preserving pre-05 behaviour) or
+   * when nobody who is connected has announced.
+   */
+  routeTo(sessionKey: string): string | null {
+    if (!this.tracksSubscribers(sessionKey)) return this.ownerOf(sessionKey);
+
+    const live = this.subscribers.get(sessionKey);
+    const announcers = this.sessions.get(sessionKey)?.announcers;
+    if (!live || !announcers) return null;
+
+    let best: string | null = null;
+    let bestSeq = -1;
+    for (const [id, seq] of announcers) {
+      if (!live.has(id)) continue;
+      if (seq > bestSeq) {
+        best = id;
+        bestSeq = seq;
+      }
+    }
+    return best;
+  }
+
+  // ── Subscribers (spec §L1, §L2, §L4) ─────────────────────────────────────
+
+  /**
+   * Record that a downstream subscriber (one SSE connection) is live for
+   * `sessionKey`. Apps call this from the endpoint that opens the stream.
+   *
+   * Idempotent per `subscriberId`, and it cancels any pending §L1 grace timer —
+   * which is exactly what makes a page reload a no-op: the tab's stream closes
+   * and reopens well inside the grace window, so nothing is ever deregistered.
+   */
+  addSubscriber(sessionKey: string, subscriberId: string): void {
+    this.cancelGrace(sessionKey);
+    const live = this.subscribers.get(sessionKey) ?? new Map<string, number>();
+    live.set(subscriberId, (live.get(subscriberId) ?? 0) + 1);
+    this.subscribers.set(sessionKey, live);
+  }
+
+  /**
+   * Record that a subscriber's stream closed.
+   *
+   * When it was the last one for `sessionKey`, arm the §L1 grace timer. On
+   * expiry — and only if nobody has connected or announced since — the
+   * browser-announced registry is withdrawn and the resulting
+   * `capability_deregister` is pushed upstream.
+   *
+   * Deliberately *not* {@link clear}: the sender and invoker belong to the agent
+   * session, which is still very much alive, and tearing them down would leave
+   * a returning browser unable to register anything until the session restarts.
+   *
+   * @returns `true` when this disconnect armed the grace timer.
+   */
+  removeSubscriber(sessionKey: string, subscriberId: string): boolean {
+    const live = this.subscribers.get(sessionKey);
+    if (!live) return false;
+    const open = (live.get(subscriberId) ?? 0) - 1;
+    if (open > 0) {
+      live.set(subscriberId, open);
+      return false;
+    }
+    live.delete(subscriberId);
+    // NB: the (possibly empty) map stays — see the `subscribers` field comment.
+    //
+    // The subscriber deliberately stays in `announcers`. Its entry is what
+    // makes a reconnect a *re*-announce rather than a first announce, and
+    // {@link routeTo} already skips announcers that are not currently live, so
+    // a stale entry can never win the election. Only the memory is a concern,
+    // and that is bounded below.
+    this.pruneAnnouncers(sessionKey);
+    if (live.size > 0) return false;
+
+    this.cancelGrace(sessionKey);
+    const timer = setTimeout(() => {
+      this.graceTimers.delete(sessionKey);
+      void this.expireSession(sessionKey);
+    }, this.disconnectGraceMs);
+    (timer as { unref?: () => void }).unref?.();
+    this.graceTimers.set(sessionKey, timer);
+    return true;
+  }
+
+  /**
+   * Keep {@link ClientCapabilitySessionState.announcers} bounded: a long-lived
+   * session key can accumulate one entry per tab that ever announced. Live
+   * subscribers and the current owner are never dropped; the oldest departed
+   * announcers go first.
+   */
+  private pruneAnnouncers(sessionKey: string): void {
+    const announcers = this.sessions.get(sessionKey)?.announcers;
+    if (!announcers || announcers.size <= MAX_REMEMBERED_ANNOUNCERS) return;
+    const live = this.subscribers.get(sessionKey);
+    const owner = highestAnnouncer(announcers);
+    const droppable = [...announcers.entries()]
+      .filter(([id]) => id !== owner && !live?.has(id))
+      .sort((a, b) => a[1] - b[1]);
+    for (const [id] of droppable) {
+      if (announcers.size <= MAX_REMEMBERED_ANNOUNCERS) break;
+      announcers.delete(id);
+    }
+  }
+
+  /** Live subscriber ids for `sessionKey`. */
+  subscriberIds(sessionKey: string): string[] {
+    return [...(this.subscribers.get(sessionKey)?.keys() ?? [])];
+  }
+
+  /** How many downstream subscribers are live for `sessionKey`. */
+  subscriberCount(sessionKey: string): number {
+    return this.subscribers.get(sessionKey)?.size ?? 0;
+  }
+
+  /**
+   * Whether this app has ever registered a subscriber for `sessionKey` — i.e.
+   * whether subscriber counts are meaningful for it.
+   *
+   * An app that never calls {@link addSubscriber} keeps the pre-05 contract:
+   * liveness is whatever its invoker returns. One that does gets §L1/§L2/§L4.
+   */
+  tracksSubscribers(sessionKey: string): boolean {
+    return this.subscribers.has(sessionKey);
+  }
+
+  /** Whether a §L1 grace timer is currently pending for `sessionKey`. */
+  isAwaitingGrace(sessionKey: string): boolean {
+    return this.graceTimers.has(sessionKey);
+  }
+
+  private cancelGrace(sessionKey: string): void {
+    const timer = this.graceTimers.get(sessionKey);
+    if (timer === undefined) return;
+    clearTimeout(timer);
+    this.graceTimers.delete(sessionKey);
+  }
+
+  /**
+   * §L1 grace expiry: the last browser really is gone. Drop the announced
+   * registry and push the deregistration upstream.
+   *
+   * In-flight calls are left alone on purpose. Their §L3 timers are the
+   * authority on when they die, and a grace expiry is not proof the answer is
+   * never coming — a slow reload can land just past the window.
+   */
+  private async expireSession(sessionKey: string): Promise<void> {
+    if (this.subscriberCount(sessionKey) > 0) return;
+    const names = this.listClient(sessionKey).map((c) => c.name);
+    if (!this.withdraw(sessionKey)) return;
+    this.log.info(
+      `[client-capability-bridge] [${sessionKey}] last subscriber gone for ` +
+        `${this.disconnectGraceMs}ms — deregistering ${names.length} browser-owned ` +
+        `capabilit${names.length === 1 ? "y" : "ies"}`,
+    );
+    await this.sync(sessionKey);
+  }
+
+  /** Every session key that currently has an announced registry. */
+  sessionKeys(): string[] {
+    return [...this.sessions.keys()];
+  }
+
+  /**
+   * The single list to register with the agent: the server-side registry plus
+   * whatever the browser announced.
+   *
+   * Spec §L6 — on a name collision **the server entry wins** and the bridge logs
+   * a warning (once per session key + name).
+   */
+  merged(sessionKey: string): Capability[] {
+    const server = this.serverRegistry.list();
+    const serverNames = new Set(server.map((c) => c.name));
+    const merged = [...server];
+
+    for (const client of this.listClient(sessionKey)) {
+      if (serverNames.has(client.name)) {
+        const warnKey = `${sessionKey}::${client.name}`;
+        if (!this.warnedCollisions.has(warnKey)) {
+          this.warnedCollisions.add(warnKey);
+          this.log.warn(
+            `[client-capability-bridge] capability name collision on "${client.name}" ` +
+              `for session "${sessionKey}": the server-side entry wins, the ` +
+              `client-announced entry is ignored.`,
+          );
+        }
+        continue;
+      }
+      merged.push(client);
+    }
+
+    return merged;
+  }
+
+  /**
+   * Register the transport used to push commands upstream for `sessionKey`.
+   * Pass `null` to detach (e.g. when the agent session is replaced).
+   */
+  setSender(sessionKey: string, sender: ClientCapabilitySender | null): void {
+    if (sender) {
+      this.senders.set(sessionKey, sender);
+    } else {
+      this.senders.delete(sessionKey);
+      this.lastSent.delete(sessionKey);
+      this.lastSentNames.delete(sessionKey);
+    }
+  }
+
+  /** Whether a sender is currently attached for `sessionKey`. */
+  hasSender(sessionKey: string): boolean {
+    return this.senders.has(sessionKey);
+  }
+
+  // ── Invocation (spec §2 downward leg, §L2) ───────────────────────────────
+
+  /**
+   * Register the transport that pushes an invocation **down to the browser** for
+   * `sessionKey` — in every forge app, the app's existing SSE fan-out. Pass
+   * `null` to detach.
+   *
+   * The invoker's boolean return is the liveness signal §L2 hinges on: `false`
+   * means nothing received it, and the bridge answers the agent rather than
+   * parking a call that can never be resolved.
+   */
+  setInvoker(sessionKey: string, invoker: ClientCapabilityInvoker | null): void {
+    if (invoker) {
+      this.invokers.set(sessionKey, invoker);
+    } else {
+      this.invokers.delete(sessionKey);
+    }
+  }
+
+  /** Whether a downstream invoker is currently attached for `sessionKey`. */
+  hasInvoker(sessionKey: string): boolean {
+    return this.invokers.has(sessionKey);
+  }
+
+  /**
+   * Whether `name` is one the browser announced for `sessionKey` — i.e. whether
+   * this invocation belongs to the app channel rather than to the server-side
+   * `capabilityRegistry`. This is the routing predicate;
+   * {@link routeCapabilityInvocation} is the routing itself.
+   *
+   * §L6: a name the *server* registry also owns is not a client capability. The
+   * server entry is the one that was registered with the agent, so it is the one
+   * that must answer.
+   */
+  hasClientCapability(sessionKey: string, name: string): boolean {
+    if (this.serverRegistry.list().some((c) => c.name === name)) return false;
+    return this.listClient(sessionKey).some((c) => c.name === name);
+  }
+
+  /**
+   * Route one `capability_invoked` to the browser that announced it.
+   *
+   * Parks the `callId` and hands the invocation to the registered invoker. When
+   * there is no invoker, or the invoker reports that no live UI received it,
+   * the call is answered immediately with {@link NO_UI_ATTACHED_ERROR} and
+   * never parked (§L2).
+   */
+  async invoke(
+    sessionKey: string,
+    invocation: Omit<ClientCapabilityInvocation, "sessionKey" | "ownerId">,
+  ): Promise<InvokeOutcome> {
+    const outcome = await this.park(sessionKey, invocation);
+    if (outcome === "no-ui") {
+      await this.sendResult(sessionKey, invocation.callId, { error: NO_UI_ATTACHED_ERROR });
+    }
+    return outcome;
+  }
+
+  /**
+   * Like {@link invoke}, but the browser's answer resolves this promise instead
+   * of going to the sender — for a server-side caller that is not the agent
+   * (a test driver, a route).
+   *
+   * Resolves with exactly what the browser posted, `{ error }` envelopes
+   * included; the caller maps them. Rejects with `Error(NO_UI_ATTACHED_ERROR)`
+   * when no live UI received the invocation (never parked), and with
+   * `Error(capabilityTimeoutError(...))` when the §L3 timer fires first. A
+   * session restart or clear ({@link dropPendingCalls}) resolves it with
+   * `{ error }`, like any other parked call.
+   */
+  call(
+    sessionKey: string,
+    invocation: Omit<ClientCapabilityInvocation, "sessionKey" | "ownerId">,
+  ): Promise<unknown> {
+    return new Promise<unknown>((resolve, reject) => {
+      this.park(
+        sessionKey,
+        { ...invocation, invokedBy: "driver" },
+        { settle: resolve, reject },
+      ).then((outcome) => {
+        if (outcome === "no-ui") reject(new Error(NO_UI_ATTACHED_ERROR));
+      }, reject);
+    });
+  }
+
+  /**
+   * Shared by {@link invoke} and {@link call}: the §L2 liveness checks, the
+   * §L4 owner stamp, the park and the §L3 timer, then the hand-off to the
+   * invoker. Answers nobody — a `"no-ui"` outcome leaves that to the caller,
+   * with the call already unparked.
+   */
+  private async park(
+    sessionKey: string,
+    invocation: Omit<ClientCapabilityInvocation, "sessionKey" | "ownerId">,
+    driver?: { settle: (result: unknown) => void; reject: (error: Error) => void },
+  ): Promise<InvokeOutcome> {
+    const invoker = this.invokers.get(sessionKey);
+
+    // §L2, sharpened. Before ticket 05 the only liveness signal was the
+    // invoker's boolean, and every forge app derived it from "is anything at
+    // all listening to my event emitter" — which counts a subscriber for a
+    // different session as a live UI. Once an app tracks subscribers per
+    // session key we can answer that question exactly, and do it *before*
+    // burning a fan-out.
+    if (this.tracksSubscribers(sessionKey) && this.subscriberCount(sessionKey) === 0) {
+      return "no-ui";
+    }
+
+    if (!invoker) return "no-ui";
+
+    // §L4 — one owner. The app's invoker is expected to deliver only to this
+    // subscriber; the others stay connected and inert.
+    const full: ClientCapabilityInvocation = {
+      ...invocation,
+      sessionKey,
+      ownerId: this.routeTo(sessionKey),
+    };
+
+    // Park BEFORE dispatching: an SSE round trip can complete inside the same
+    // tick as the invoker call, and a result that arrives before the park would
+    // be dropped as unknown.
+    const timeoutMs = this.timeoutFor(sessionKey, invocation.name);
+    const entry: ParkedCall = { ...full, parkedAt: Date.now(), timeoutMs, ...driver };
+    const calls = this.parked.get(sessionKey) ?? new Map<string, ParkedCall>();
+    calls.set(invocation.callId, entry);
+    this.parked.set(sessionKey, calls);
+    this.armCallTimer(sessionKey, invocation.callId, invocation.name, timeoutMs);
+
+    let delivered = false;
+    try {
+      delivered = await invoker(full);
+    } catch (err) {
+      this.log.warn(
+        `[client-capability-bridge] [${sessionKey}] invoker threw for ` +
+          `"${invocation.name}" (callId=${invocation.callId}): ${err}`,
+      );
+      delivered = false;
+    }
+
+    if (delivered) return "dispatched";
+
+    // Nothing received it — unpark; the caller answers.
+    this.clearCallTimer(sessionKey, invocation.callId);
+    if (calls.delete(invocation.callId) && calls.size === 0) this.parked.delete(sessionKey);
+    return "no-ui";
+  }
+
+  // ── Per-call timeouts (spec §L3) ─────────────────────────────────────────
+
+  /**
+   * The §L3 deadline for one capability: whatever the browser announced as
+   * `callTimeoutMs`, else this bridge's default.
+   *
+   * Both must stay under the runner's own `DEFAULT_CAPABILITY_CALL_TIMEOUT_MS`
+   * (60 s) to be worth anything — a timer that fires second only ever reports
+   * what the runner has already given up on.
+   */
+  timeoutFor(sessionKey: string, name: string): number {
+    const declared = this.listClient(sessionKey).find((c) => c.name === name)?.callTimeoutMs;
+    return typeof declared === "number" && declared > 0 ? declared : this.defaultCallTimeoutMs;
+  }
+
+  private armCallTimer(sessionKey: string, callId: string, name: string, timeoutMs: number): void {
+    const timer = setTimeout(() => {
+      this.clearCallTimer(sessionKey, callId);
+      const calls = this.parked.get(sessionKey);
+      const entry = calls?.get(callId);
+      if (!calls || !entry) return;
+      calls.delete(callId);
+      if (calls.size === 0) this.parked.delete(sessionKey);
+      this.log.warn(
+        `[client-capability-bridge] [${sessionKey}] "${name}" (callId=${callId}) timed out ` +
+          `after ${timeoutMs}ms — the browser never answered`,
+      );
+      const message = capabilityTimeoutError(name, timeoutMs);
+      if (entry.reject) {
+        entry.reject(new Error(message));
+        return;
+      }
+      void this.sendResult(sessionKey, callId, { error: message });
+    }, timeoutMs);
+    (timer as { unref?: () => void }).unref?.();
+
+    const timers = this.callTimers.get(sessionKey) ?? new Map();
+    timers.set(callId, timer);
+    this.callTimers.set(sessionKey, timers);
+  }
+
+  private clearCallTimer(sessionKey: string, callId: string): void {
+    const timers = this.callTimers.get(sessionKey);
+    const timer = timers?.get(callId);
+    if (timer !== undefined) clearTimeout(timer);
+    timers?.delete(callId);
+    if (timers && timers.size === 0) this.callTimers.delete(sessionKey);
+  }
+
+  private clearCallTimers(sessionKey: string): void {
+    for (const timer of this.callTimers.get(sessionKey)?.values() ?? []) clearTimeout(timer);
+    this.callTimers.delete(sessionKey);
+  }
+
+  /**
+   * Answer a parked `callId` with what the browser posted back and forward it
+   * to the agent as one `capability_result`.
+   *
+   * Returns `false` — and sends nothing — when the `callId` is not parked under
+   * `sessionKey`. That covers the duplicate answer (two tabs both saw the SSE
+   * event and both posted), the late answer after a timeout, and a forged POST
+   * for someone else's call. Only a call this bridge actually parked can be
+   * answered.
+   */
+  async resolve(sessionKey: string, callId: string, result: unknown): Promise<boolean> {
+    const calls = this.parked.get(sessionKey);
+    const entry = calls?.get(callId);
+    if (!calls || !entry) return false;
+
+    this.clearCallTimer(sessionKey, callId);
+    calls.delete(callId);
+    if (calls.size === 0) this.parked.delete(sessionKey);
+
+    // A driver-originated call answers its own caller; the agent never saw this callId.
+    if (entry.settle) {
+      entry.settle(result);
+      return true;
+    }
+    await this.sendResult(sessionKey, callId, result);
+    return true;
+  }
+
+  /**
+   * Answer every parked call for `sessionKey` with an error and forget them,
+   * leaving the announced registry, sender and invoker in place.
+   *
+   * This is what a session restart needs: the agent process behind those calls
+   * is gone, so nothing will ever resolve them, but the browser is still
+   * attached and its announcement must survive — {@link clear} would throw it
+   * away and the agent would come back up with no client capabilities until the
+   * next page load.
+   *
+   * @returns how many calls were dropped.
+   */
+  dropPendingCalls(sessionKey: string, error = SESSION_ENDED_ERROR): number {
+    const count = this.parked.get(sessionKey)?.size ?? 0;
+    this.settleAll(sessionKey, error);
+    return count;
+  }
+
+  /** `callId`s currently parked for `sessionKey`. Ticket 05's timeout seam. */
+  pendingCallIds(sessionKey: string): string[] {
+    return [...(this.parked.get(sessionKey)?.keys() ?? [])];
+  }
+
+  /** The parked entry for one `callId`, or `undefined`. */
+  pendingCall(sessionKey: string, callId: string): ParkedCall | undefined {
+    return this.parked.get(sessionKey)?.get(callId);
+  }
+
+  /**
+   * Push one `capability_result` upstream, bypassing the parked-call check.
+   *
+   * For results the bridge did not park — i.e. the server-side
+   * `capabilityRegistry` path, which runs in Nitro and answers synchronously.
+   * Browser-supplied results must go through {@link resolve} instead, which only
+   * answers a `callId` this bridge actually parked.
+   *
+   * Never throws.
+   */
+  async sendResult(sessionKey: string, callId: string, result: unknown): Promise<void> {
+    const sender = this.senders.get(sessionKey);
+    if (!sender) {
+      this.log.warn(
+        `[client-capability-bridge] [${sessionKey}] no sender — capability_result ` +
+          `for callId=${callId} dropped; the agent will wait out its own timeout.`,
+      );
+      return;
+    }
+    try {
+      await sender({ type: "capability_result", callId, result });
+    } catch (err) {
+      this.log.warn(`[client-capability-bridge] [${sessionKey}] capability_result failed: ${err}`);
+    }
+  }
+
+  /**
+   * Answer every parked call for `sessionKey` with `error`, then forget them.
+   *
+   * Synchronous on purpose: {@link clear} tears the sender down in the same tick,
+   * so the sender is snapshotted here rather than looked up per call.
+   *
+   * Calls parked by {@link call} have no `callId` the agent knows about: their
+   * `settle` receives the `{ error }` envelope instead of the sender.
+   */
+  private settleAll(sessionKey: string, error: string): void {
+    this.clearCallTimers(sessionKey);
+    const calls = this.parked.get(sessionKey);
+    if (!calls || calls.size === 0) return;
+    const entries = [...calls.values()];
+    this.parked.delete(sessionKey);
+
+    const sender = this.senders.get(sessionKey);
+    for (const entry of entries) {
+      const { callId } = entry;
+      try {
+        if (entry.settle) {
+          entry.settle({ error });
+        } else if (sender) {
+          void Promise.resolve(
+            sender({ type: "capability_result", callId, result: { error } }),
+          ).catch((err) => {
+            this.log.warn(
+              `[client-capability-bridge] [${sessionKey}] settle of callId=${callId} failed: ${err}`,
+            );
+          });
+        }
+      } catch (err) {
+        this.log.warn(
+          `[client-capability-bridge] [${sessionKey}] settle of callId=${callId} failed: ${err}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Reconcile the agent's registry with the merged list: `capability_deregister`
+   * for names that dropped out, then `capability_register` for what remains.
+   *
+   * Spec §L5 — no-ops entirely when the merged list is byte-identical to what
+   * was last sent for this key, so an SSE reconnect that re-announces an
+   * unchanged registry produces **zero** upstream traffic. Pass `force: true` at
+   * session creation, where a fresh agent process has no prior registration.
+   *
+   * The deregister leg is not optional bookkeeping: the runner's
+   * `handleCapabilityRegister` loops `registry.register(cap)` per entry, so a
+   * `capability_register` only ever **adds**. Re-sending a shorter list would
+   * leave the removed capability registered and callable. Only
+   * `capability_deregister` takes one away.
+   *
+   * @returns the merged list (whether or not anything was sent).
+   */
+  async sync(sessionKey: string, options: { force?: boolean } = {}): Promise<Capability[]> {
+    const capabilities = this.merged(sessionKey);
+    const sender = this.senders.get(sessionKey);
+    if (!sender) return capabilities;
+
+    const next = signature(capabilities);
+    if (!options.force && this.lastSent.get(sessionKey) === next) return capabilities;
+
+    const nextNames = new Set(capabilities.map((c) => c.name));
+    const removed = [...(this.lastSentNames.get(sessionKey) ?? [])].filter(
+      (name) => !nextNames.has(name),
+    );
+
+    try {
+      if (removed.length > 0) {
+        await sender({ type: "capability_deregister", names: removed });
+        this.log.info(
+          `[client-capability-bridge] [${sessionKey}] deregistered ${removed.length} ` +
+            `capabilit${removed.length === 1 ? "y" : "ies"}: ${removed.join(", ")}`,
+        );
+      }
+      if (capabilities.length > 0) {
+        await sender({ type: "capability_register", capabilities });
+        this.log.info(
+          `[client-capability-bridge] [${sessionKey}] registered ${capabilities.length} ` +
+            `capabilities (${this.listClient(sessionKey).length} from the browser)`,
+        );
+      }
+      this.lastSent.set(sessionKey, next);
+      this.lastSentNames.set(sessionKey, nextNames);
+    } catch (err) {
+      this.log.warn(
+        `[client-capability-bridge] [${sessionKey}] capability registration failed: ${err}`,
+      );
+    }
+
+    return capabilities;
+  }
+
+  /**
+   * Forget everything for `sessionKey`, sender and invoker included.
+   *
+   * Parked calls are answered with {@link SESSION_ENDED_ERROR} on the way out —
+   * dropping them silently would leave the agent's turn blocked until the
+   * runner's own 60 s timeout.
+   */
+  clear(sessionKey: string): void {
+    this.settleAll(sessionKey, SESSION_ENDED_ERROR);
+    this.cancelGrace(sessionKey);
+    this.sessions.delete(sessionKey);
+    this.senders.delete(sessionKey);
+    this.invokers.delete(sessionKey);
+    this.subscribers.delete(sessionKey);
+    this.lastSent.delete(sessionKey);
+    this.lastSentNames.delete(sessionKey);
+    for (const key of [...this.warnedCollisions]) {
+      if (splitWarnKey(key)[0] === sessionKey) this.warnedCollisions.delete(key);
+    }
+  }
+
+  /** Test-only: wipe all state. Parked calls are dropped, not answered. */
+  reset(): void {
+    for (const key of [...this.callTimers.keys()]) this.clearCallTimers(key);
+    for (const key of [...this.graceTimers.keys()]) this.cancelGrace(key);
+    this.sessions.clear();
+    this.senders.clear();
+    this.invokers.clear();
+    this.subscribers.clear();
+    this.parked.clear();
+    this.lastSent.clear();
+    this.lastSentNames.clear();
+    this.warnedCollisions.clear();
+  }
+
+  /**
+   * Stamp the wire fields the browser must not author: `side` is fixed to
+   * `"client"` and `origin` to `{ kind: "client" }` (the analogue of app-sdk's
+   * SDK-stamped `origin`). Unknown fields are dropped.
+   */
+  private normalise(descriptor: IncomingClientCapability): Capability {
+    return {
+      name: descriptor.name,
+      displayName: descriptor.displayName,
+      description: descriptor.description,
+      inputSchema: descriptor.inputSchema,
+      outputSchema: descriptor.outputSchema,
+      side: "client",
+      origin: { kind: "client" },
+      scope: descriptor.scope,
+      requiresApproval: descriptor.requiresApproval,
+      kind: descriptor.kind,
+      audience: descriptor.audience,
+      promptFragment: descriptor.promptFragment,
+      callTimeoutMs: descriptor.callTimeoutMs,
+      render: descriptor.render as Capability["render"],
+    };
+  }
+}
+
+/** The subscriber with the highest announce sequence, or `null` for an empty map. */
+function highestAnnouncer(announcers: Map<string, number>): string | null {
+  let best: string | null = null;
+  let bestSeq = -1;
+  for (const [id, seq] of announcers) {
+    if (seq > bestSeq) {
+      best = id;
+      bestSeq = seq;
+    }
+  }
+  return best;
+}
+
+/** Stable content signature used for the §L5 change diff. */
+function signature(capabilities: Capability[]): string {
+  return JSON.stringify([...capabilities].sort((a, b) => a.name.localeCompare(b.name)));
+}
+
+/** `${sessionKey}::${name}` — session keys may contain `:`, names may not. */
+function splitWarnKey(key: string): [string, string] {
+  const idx = key.lastIndexOf("::");
+  return [key.slice(0, idx), key.slice(idx + 2)];
+}
+
+/**
+ * Process-wide singleton, matching `capabilityRegistry`'s lifetime. Apps that
+ * need isolation (tests, multi-tenant harnesses) can construct their own.
+ */
+export const clientCapabilityBridge = new ClientCapabilityBridge();
+
+/** Which side of the channel answered a `capability_invoked`. */
+export type CapabilityRoute = "client" | "server";
+
+/**
+ * The whole `capability_invoked` branch of an app's agent-manager `onEvent`
+ * hook, in one call.
+ *
+ * A name the browser announced goes down the app channel (SSE → handler in the
+ * browser → POST back → {@link ClientCapabilityBridge.resolve}). Anything else
+ * — including a name the server registry owns, and an unknown name — is
+ * dispatched in Nitro against the server-side `capabilityRegistry`, exactly as
+ * before. That fallback is why spec §L6 holds: genuinely server-side
+ * capabilities keep working untouched.
+ *
+ * Both branches answer through the bridge's sender, so both get the
+ * `processManager.sendCommand` transport rather than the persisting
+ * `SessionDispatcher` one (see {@link ClientCapabilitySender}).
+ *
+ * @returns which side took the call.
+ */
+export async function routeCapabilityInvocation(
+  sessionKey: string,
+  invocation: { callId: string; name: string; input: unknown },
+  deps: {
+    /** Defaults to the process-wide {@link clientCapabilityBridge}. */
+    bridge?: ClientCapabilityBridge;
+    /** Defaults to the process-wide `capabilityRegistry`. */
+    registry?: CapabilityRegistry;
+    /** Context handed to a server-side handler. */
+    ctx: CapabilityHandlerCtx;
+  },
+): Promise<CapabilityRoute> {
+  const bridge = deps.bridge ?? clientCapabilityBridge;
+
+  if (bridge.hasClientCapability(sessionKey, invocation.name)) {
+    await bridge.invoke(sessionKey, invocation);
+    return "client";
+  }
+
+  const registry = deps.registry ?? capabilityRegistry;
+  const input =
+    invocation.input && typeof invocation.input === "object"
+      ? (invocation.input as Record<string, unknown>)
+      : {};
+  const result = await registry.dispatch(invocation.name, input, deps.ctx);
+  await bridge.sendResult(sessionKey, invocation.callId, result);
+  return "server";
+}