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

package/dist/runtime/server/utils/client-capability-bridge.d.ts

@@ -0,0 +1,647 @@
+import type { Capability } from "@skaile/workspaces/sdk/types";
+import * as z from "zod";
+import { type CapabilityHandlerCtx, type CapabilityRegistry } from "./capability-registry.js";
+/** 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 declare const NO_UI_ATTACHED_ERROR: string;
+/** Error text used when a parked call is dropped because its session ended. */
+export declare 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 declare const DEFAULT_DISCONNECT_GRACE_MS = 5000;
+/**
+ * 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 declare const DEFAULT_CLIENT_CALL_TIMEOUT_MS = 30000;
+/** Stable prefix of every §L3 timeout message, so callers can match on it. */
+export declare const CALL_TIMEOUT_ERROR_PREFIX = "The UI did not answer";
+/** Error text the agent receives when a parked call outlives its timeout (§L3). */
+export declare function capabilityTimeoutError(name: string, timeoutMs: number): string;
+/** 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>;
+}
+/** Zod schema for one announced capability descriptor. */
+export declare const clientCapabilityDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    side: z.ZodOptional<z.ZodLiteral<"client">>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        session: "session";
+        turn: "turn";
+    }>>;
+    requiresApproval: z.ZodOptional<z.ZodBoolean>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        effect: "effect";
+        render: "render";
+        query: "query";
+    }>>;
+    audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        llm: "llm";
+        user: "user";
+        runtime: "runtime";
+    }>>>;
+    promptFragment: z.ZodOptional<z.ZodString>;
+    callTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    render: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Zod schema for the body of an upward announce POST. */
+export declare const clientCapabilityAnnouncementSchema: z.ZodObject<{
+    subscriberId: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        side: z.ZodOptional<z.ZodLiteral<"client">>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            session: "session";
+            turn: "turn";
+        }>>;
+        requiresApproval: z.ZodOptional<z.ZodBoolean>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            effect: "effect";
+            render: "render";
+            query: "query";
+        }>>;
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            llm: "llm";
+            user: "user";
+            runtime: "runtime";
+        }>>>;
+        promptFragment: z.ZodOptional<z.ZodString>;
+        callTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        render: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 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 declare const clientCapabilityResultSchema: z.ZodObject<{
+    callId: z.ZodString;
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+/** 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>;
+/**
+ * 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 declare class ClientCapabilityBridge {
+    private readonly sessions;
+    private readonly senders;
+    private readonly invokers;
+    /** In-flight invocations, keyed `${sessionKey}` → `callId` → entry. */
+    private readonly parked;
+    /** §L3 timers, parallel to {@link parked}. */
+    private readonly callTimers;
+    /**
+     * 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;
+    /** §L1 pending grace timers, keyed by session key. */
+    private readonly graceTimers;
+    /** Last merged list pushed per session key, for the §L5 change diff. */
+    private readonly lastSent;
+    /** Names in the last pushed list, so §L5 can deregister what dropped out. */
+    private readonly lastSentNames;
+    /** `${sessionKey}::${name}` pairs already warned about, so §L6 logs once. */
+    private readonly warnedCollisions;
+    private readonly serverRegistry;
+    private readonly log;
+    private readonly disconnectGraceMs;
+    private readonly defaultCallTimeoutMs;
+    /** Monotonic announce counter backing §L4's owner election. */
+    private announceSeq;
+    constructor(options?: ClientCapabilityBridgeOptions);
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Client-announced capabilities for `sessionKey`, in wire shape. */
+    listClient(sessionKey: string): Capability[];
+    /** True when a browser has announced a non-empty registry for `sessionKey`. */
+    hasClient(sessionKey: string): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Live subscriber ids for `sessionKey`. */
+    subscriberIds(sessionKey: string): string[];
+    /** How many downstream subscribers are live for `sessionKey`. */
+    subscriberCount(sessionKey: string): number;
+    /**
+     * 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;
+    /** Whether a §L1 grace timer is currently pending for `sessionKey`. */
+    isAwaitingGrace(sessionKey: string): boolean;
+    private cancelGrace;
+    /**
+     * §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 expireSession;
+    /** Every session key that currently has an announced registry. */
+    sessionKeys(): string[];
+    /**
+     * 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[];
+    /**
+     * 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;
+    /** Whether a sender is currently attached for `sessionKey`. */
+    hasSender(sessionKey: string): boolean;
+    /**
+     * 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;
+    /** Whether a downstream invoker is currently attached for `sessionKey`. */
+    hasInvoker(sessionKey: string): boolean;
+    /**
+     * 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;
+    /**
+     * 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).
+     */
+    invoke(sessionKey: string, invocation: Omit<ClientCapabilityInvocation, "sessionKey" | "ownerId">): Promise<InvokeOutcome>;
+    /**
+     * 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>;
+    /**
+     * 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 park;
+    /**
+     * 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;
+    private armCallTimer;
+    private clearCallTimer;
+    private clearCallTimers;
+    /**
+     * 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.
+     */
+    resolve(sessionKey: string, callId: string, result: unknown): Promise<boolean>;
+    /**
+     * 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?: string): number;
+    /** `callId`s currently parked for `sessionKey`. Ticket 05's timeout seam. */
+    pendingCallIds(sessionKey: string): string[];
+    /** The parked entry for one `callId`, or `undefined`. */
+    pendingCall(sessionKey: string, callId: string): ParkedCall | undefined;
+    /**
+     * 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.
+     */
+    sendResult(sessionKey: string, callId: string, result: unknown): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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).
+     */
+    sync(sessionKey: string, options?: {
+        force?: boolean;
+    }): Promise<Capability[]>;
+    /**
+     * 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;
+    /** Test-only: wipe all state. Parked calls are dropped, not answered. */
+    reset(): void;
+    /**
+     * 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;
+}
+/**
+ * Process-wide singleton, matching `capabilityRegistry`'s lifetime. Apps that
+ * need isolation (tests, multi-tenant harnesses) can construct their own.
+ */
+export declare const clientCapabilityBridge: 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 declare 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>;