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

package/dist/runtime/server/utils/client-capability-bridge.js

@@ -0,0 +1,755 @@
+import * as z from "zod";
+import {
+  capabilityRegistry
+} from "./capability-registry.js";
+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.";
+export const SESSION_ENDED_ERROR = "The UI session ended before the capability returned a result.";
+export const DEFAULT_DISCONNECT_GRACE_MS = 5e3;
+export const DEFAULT_CLIENT_CALL_TIMEOUT_MS = 3e4;
+export const CALL_TIMEOUT_ERROR_PREFIX = "The UI did not answer";
+export function capabilityTimeoutError(name, timeoutMs) {
+  return `${CALL_TIMEOUT_ERROR_PREFIX} "${name}" within ${Math.round(timeoutMs / 1e3)}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.`;
+}
+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()
+});
+export const clientCapabilityAnnouncementSchema = z.object({
+  subscriberId: z.string().optional(),
+  capabilities: z.array(clientCapabilityDescriptorSchema)
+});
+export const clientCapabilityResultSchema = z.object({
+  callId: z.string().min(1),
+  result: z.unknown()
+});
+const MAX_REMEMBERED_ANNOUNCERS = 16;
+const defaultLogger = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(message)
+};
+export class ClientCapabilityBridge {
+  sessions = /* @__PURE__ */ new Map();
+  senders = /* @__PURE__ */ new Map();
+  invokers = /* @__PURE__ */ new Map();
+  /** In-flight invocations, keyed `${sessionKey}` → `callId` → entry. */
+  parked = /* @__PURE__ */ new Map();
+  /** §L3 timers, parallel to {@link parked}. */
+  callTimers = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  subscribers = /* @__PURE__ */ new Map();
+  /** §L1 pending grace timers, keyed by session key. */
+  graceTimers = /* @__PURE__ */ new Map();
+  /** Last merged list pushed per session key, for the §L5 change diff. */
+  lastSent = /* @__PURE__ */ new Map();
+  /** Names in the last pushed list, so §L5 can deregister what dropped out. */
+  lastSentNames = /* @__PURE__ */ new Map();
+  /** `${sessionKey}::${name}` pairs already warned about, so §L6 logs once. */
+  warnedCollisions = /* @__PURE__ */ new Set();
+  serverRegistry;
+  log;
+  disconnectGraceMs;
+  defaultCallTimeoutMs;
+  /** Monotonic announce counter backing §L4's owner election. */
+  announceSeq = 0;
+  constructor(options = {}) {
+    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, capabilities, options = {}) {
+    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();
+    this.cancelGrace(sessionKey);
+    const announcers = previous?.announcers ?? /* @__PURE__ */ new Map();
+    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
+    });
+    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) {
+    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) {
+    return [...this.sessions.get(sessionKey)?.capabilities ?? []];
+  }
+  /** True when a browser has announced a non-empty registry for `sessionKey`. */
+  hasClient(sessionKey) {
+    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) {
+    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) {
+    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 = 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, subscriberId) {
+    this.cancelGrace(sessionKey);
+    const live = this.subscribers.get(sessionKey) ?? /* @__PURE__ */ new Map();
+    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, subscriberId) {
+    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);
+    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.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.
+   */
+  pruneAnnouncers(sessionKey) {
+    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) {
+    return [...this.subscribers.get(sessionKey)?.keys() ?? []];
+  }
+  /** How many downstream subscribers are live for `sessionKey`. */
+  subscriberCount(sessionKey) {
+    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) {
+    return this.subscribers.has(sessionKey);
+  }
+  /** Whether a §L1 grace timer is currently pending for `sessionKey`. */
+  isAwaitingGrace(sessionKey) {
+    return this.graceTimers.has(sessionKey);
+  }
+  cancelGrace(sessionKey) {
+    const timer = this.graceTimers.get(sessionKey);
+    if (timer === void 0) 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.
+   */
+  async expireSession(sessionKey) {
+    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 \u2014 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() {
+    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) {
+    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, sender) {
+    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) {
+    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, invoker) {
+    if (invoker) {
+      this.invokers.set(sessionKey, invoker);
+    } else {
+      this.invokers.delete(sessionKey);
+    }
+  }
+  /** Whether a downstream invoker is currently attached for `sessionKey`. */
+  hasInvoker(sessionKey) {
+    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, name) {
+    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, invocation) {
+    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, invocation) {
+    return new Promise((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.
+   */
+  async park(sessionKey, invocation, driver) {
+    const invoker = this.invokers.get(sessionKey);
+    if (this.tracksSubscribers(sessionKey) && this.subscriberCount(sessionKey) === 0) {
+      return "no-ui";
+    }
+    if (!invoker) return "no-ui";
+    const full = {
+      ...invocation,
+      sessionKey,
+      ownerId: this.routeTo(sessionKey)
+    };
+    const timeoutMs = this.timeoutFor(sessionKey, invocation.name);
+    const entry = { ...full, parkedAt: Date.now(), timeoutMs, ...driver };
+    const calls = this.parked.get(sessionKey) ?? /* @__PURE__ */ new Map();
+    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";
+    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, name) {
+    const declared = this.listClient(sessionKey).find((c) => c.name === name)?.callTimeoutMs;
+    return typeof declared === "number" && declared > 0 ? declared : this.defaultCallTimeoutMs;
+  }
+  armCallTimer(sessionKey, callId, name, timeoutMs) {
+    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 \u2014 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.unref?.();
+    const timers = this.callTimers.get(sessionKey) ?? /* @__PURE__ */ new Map();
+    timers.set(callId, timer);
+    this.callTimers.set(sessionKey, timers);
+  }
+  clearCallTimer(sessionKey, callId) {
+    const timers = this.callTimers.get(sessionKey);
+    const timer = timers?.get(callId);
+    if (timer !== void 0) clearTimeout(timer);
+    timers?.delete(callId);
+    if (timers && timers.size === 0) this.callTimers.delete(sessionKey);
+  }
+  clearCallTimers(sessionKey) {
+    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, callId, result) {
+    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);
+    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, error = SESSION_ENDED_ERROR) {
+    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) {
+    return [...this.parked.get(sessionKey)?.keys() ?? []];
+  }
+  /** The parked entry for one `callId`, or `undefined`. */
+  pendingCall(sessionKey, callId) {
+    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, callId, result) {
+    const sender = this.senders.get(sessionKey);
+    if (!sender) {
+      this.log.warn(
+        `[client-capability-bridge] [${sessionKey}] no sender \u2014 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.
+   */
+  settleAll(sessionKey, error) {
+    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, options = {}) {
+    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) {
+    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() {
+    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.
+   */
+  normalise(descriptor) {
+    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
+    };
+  }
+}
+function highestAnnouncer(announcers) {
+  let best = null;
+  let bestSeq = -1;
+  for (const [id, seq] of announcers) {
+    if (seq > bestSeq) {
+      best = id;
+      bestSeq = seq;
+    }
+  }
+  return best;
+}
+function signature(capabilities) {
+  return JSON.stringify([...capabilities].sort((a, b) => a.name.localeCompare(b.name)));
+}
+function splitWarnKey(key) {
+  const idx = key.lastIndexOf("::");
+  return [key.slice(0, idx), key.slice(idx + 2)];
+}
+export const clientCapabilityBridge = new ClientCapabilityBridge();
+export async function routeCapabilityInvocation(sessionKey, invocation, deps) {
+  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 : {};
+  const result = await registry.dispatch(invocation.name, input, deps.ctx);
+  await bridge.sendResult(sessionKey, invocation.callId, result);
+  return "server";
+}