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

package/src/runtime/composables/useCapabilityApproval.ts

@@ -0,0 +1,219 @@
+/**
+ * The browser-side **approval gate** for agent-invoked capabilities
+ * (spec §3 L7).
+ *
+ * On the platform, `requiresApproval` is a gateway feature: the gateway parks
+ * the invocation, renders a confirm card, and only then forwards the call to
+ * the app. Forge has no such gate — but it does not need one, because the forge
+ * handler already runs in the browser. So the gate is simply: the inbound
+ * dispatcher awaits a confirm dialog before it dispatches. Far simpler
+ * machinery, identical observable contract (`{ error: "declined" }` back to the
+ * agent, handler untouched).
+ *
+ * This module is the queue behind that dialog. It holds no UI of its own —
+ * `<ForgeCapabilityApproval />` (one variant per UI kit) renders
+ * {@link UseCapabilityApprovalReturn.current} and calls `approve` / `decline`.
+ * A consumer that wants its own dialog can ignore the component and read the
+ * same queue.
+ *
+ * **Every request settles exactly once, and settling removes it from the
+ * queue.** That is the difference between a cancellable dialog and one that
+ * merely loses a race: when the per-call deadline elapses, the entry
+ * disappears — the dialog closes, the promise resolves `"timeout"`, and the
+ * dispatcher answers the parked call. Nothing is left open for a user to
+ * confirm after the agent has already been told the call expired.
+ */
+
+import { type ComputedRef, computed, type ShallowRef, shallowRef } from "vue";
+
+/**
+ * How an approval request ended.
+ *
+ * `timeout` and `cancelled` are both "no answer", kept apart because they have
+ * different causes: `timeout` is this browser's own per-call deadline elapsing,
+ * `cancelled` is the caller pulling the request (an `AbortSignal`, or
+ * {@link UseCapabilityApprovalReturn.reset} on teardown).
+ */
+export type CapabilityApprovalDecision = "approved" | "declined" | "timeout" | "cancelled";
+
+/** Default per-call deadline for an unanswered dialog. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 30_000;
+
+/** What the caller asks the user to confirm. */
+export interface CapabilityApprovalOptions {
+  /** Correlation token of the originating `capability_invoked` event. */
+  callId: string;
+  /** Capability name as invoked — possibly a deprecated alias. */
+  name: string;
+  /** Human-readable label, when the capability declared one. */
+  displayName?: string;
+  /** The capability's own description, shown as the "what this does" line. */
+  description?: string;
+  /**
+   * The **validated** arguments the handler would receive. Validation runs
+   * before the gate, so the user is never asked to approve a call that would
+   * have been rejected anyway, and what the dialog shows is what will run.
+   */
+  input?: unknown;
+  /**
+   * Deadline in ms. `undefined` falls back to
+   * {@link DEFAULT_APPROVAL_TIMEOUT_MS}; `0` or a negative value means no
+   * browser-side deadline (the agent runner's own backstop still applies).
+   */
+  timeoutMs?: number;
+  /** Cancels the request from outside — settles it `"cancelled"`. */
+  signal?: AbortSignal;
+}
+
+/** One entry in the approval queue, as the dialog renders it. */
+export interface CapabilityApprovalRequest {
+  /** Queue-unique id. Distinct from `callId`: the queue owns this one. */
+  id: string;
+  callId: string;
+  name: string;
+  displayName?: string;
+  description?: string;
+  input?: unknown;
+  /** `Date.now()` when the request was enqueued. */
+  requestedAt: number;
+  /** Effective deadline in ms, or `undefined` when there is none. */
+  timeoutMs?: number;
+  /** `requestedAt + timeoutMs`, for a countdown. `undefined` when no deadline. */
+  expiresAt?: number;
+}
+
+export interface UseCapabilityApprovalReturn {
+  /**
+   * The pending queue, oldest first.
+   *
+   * `shallowRef` for the same reason `useAgentCapabilities` uses one: entries
+   * carry arbitrary handler input, and Vue's deep proxy has no business
+   * rewriting values that are about to be handed to application code.
+   */
+  pending: Readonly<ShallowRef<CapabilityApprovalRequest[]>>;
+  /** The request the dialog should show — the oldest pending one, or `null`. */
+  current: ComputedRef<CapabilityApprovalRequest | null>;
+  /**
+   * Ask for confirmation. Resolves — never rejects — when the user answers,
+   * the deadline elapses, or the request is cancelled.
+   */
+  request(options: CapabilityApprovalOptions): Promise<CapabilityApprovalDecision>;
+  /** Answer a request `"approved"`. Returns false if it already settled. */
+  approve(id: string): boolean;
+  /** Answer a request `"declined"`. Returns false if it already settled. */
+  decline(id: string): boolean;
+  /** Withdraw a request `"cancelled"`. Returns false if it already settled. */
+  cancel(id: string): boolean;
+  /** Cancel everything pending — session teardown, tests. */
+  reset(): void;
+}
+
+// ── Module-level singleton ─────────────────────────────────────────────────
+// Same pattern as useAgentCapabilities / useCommandPalette: one queue per
+// browser tab, so the dialog can be mounted once in app.vue while any number
+// of dispatch call sites feed it.
+
+const _pending = shallowRef<CapabilityApprovalRequest[]>([]);
+
+/**
+ * Settlers live OUTSIDE the reactive ref on purpose. The queue is pure data
+ * that a template renders; the functions that resolve the promises are not
+ * something Vue should ever see, proxy, or diff.
+ */
+const _settlers = new Map<string, (decision: CapabilityApprovalDecision) => boolean>();
+
+let _seq = 0;
+
+function nextId(): string {
+  _seq += 1;
+  return `approval-${_seq}`;
+}
+
+const _current = computed<CapabilityApprovalRequest | null>(() => _pending.value[0] ?? null);
+
+function settle(id: string, decision: CapabilityApprovalDecision): boolean {
+  return _settlers.get(id)?.(decision) ?? false;
+}
+
+function request(options: CapabilityApprovalOptions): Promise<CapabilityApprovalDecision> {
+  return new Promise<CapabilityApprovalDecision>((resolve) => {
+    // An already-aborted signal never reaches the queue: showing a dialog that
+    // is dead on arrival would be worse than not showing one.
+    if (options.signal?.aborted) {
+      resolve("cancelled");
+      return;
+    }
+
+    const id = nextId();
+    const requestedAt = Date.now();
+    const configured = options.timeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    const timeoutMs = configured > 0 ? configured : undefined;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled = false;
+
+    const finish = (decision: CapabilityApprovalDecision): boolean => {
+      if (settled) return false;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      _settlers.delete(id);
+      // Removing the entry is what closes the dialog. Do it on EVERY exit,
+      // including timeout — a dialog that outlives its own call is exactly the
+      // leak this gate must not have.
+      _pending.value = _pending.value.filter((entry) => entry.id !== id);
+      resolve(decision);
+      return true;
+    };
+
+    function onAbort() {
+      finish("cancelled");
+    }
+
+    _settlers.set(id, finish);
+
+    if (timeoutMs !== undefined) {
+      timer = setTimeout(() => finish("timeout"), timeoutMs);
+      // Node/Bun timers keep the event loop alive; a pending confirm dialog is
+      // not a reason to hold a process open (matters for SSR and for tests).
+      (timer as unknown as { unref?: () => void }).unref?.();
+    }
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    _pending.value = [
+      ..._pending.value,
+      {
+        id,
+        callId: options.callId,
+        name: options.name,
+        displayName: options.displayName,
+        description: options.description,
+        input: options.input,
+        requestedAt,
+        timeoutMs,
+        expiresAt: timeoutMs === undefined ? undefined : requestedAt + timeoutMs,
+      },
+    ];
+  });
+}
+
+/**
+ * The approval queue behind `requiresApproval`.
+ *
+ * Stateless accessor over a module-level singleton — call it from anywhere.
+ */
+export function useCapabilityApproval(): UseCapabilityApprovalReturn {
+  return {
+    pending: _pending,
+    current: _current,
+    request,
+    approve: (id: string) => settle(id, "approved"),
+    decline: (id: string) => settle(id, "declined"),
+    cancel: (id: string) => settle(id, "cancelled"),
+    reset: () => {
+      for (const id of [..._settlers.keys()]) settle(id, "cancelled");
+      // Belt and braces: settle() already empties the queue entry by entry.
+      _pending.value = [];
+    },
+  };
+}

package/src/runtime/composables/useCapabilityInvocations.ts

@@ -0,0 +1,325 @@
+/**
+ * Browser half of the forge app channel's **invoke** leg.
+ *
+ * `useAgentCapabilities()` announces what the browser can do; this composable
+ * is what happens when the agent takes it up on the offer. One
+ * `capability_invoked` arrives over the app's existing SSE stream and this
+ * module:
+ *
+ *   1. looks the name up in the browser registry (deprecated aliases included,
+ *      because an alias is registered as its own entry sharing the handler),
+ *   2. validates the raw input against the capability's **live zod schema** —
+ *      `inputSchema` on the wire is only a hint to the model, the schema here is
+ *      the enforcement, and it runs BEFORE the handler,
+ *   3. for a capability that declares `requiresApproval`, awaits the user's
+ *      confirmation (spec §3 L7) — declining answers the agent and the handler
+ *      never runs,
+ *   4. runs the handler, where the real `ref()`s live,
+ *   5. POSTs `{ callId, result }` back so Nitro can answer the parked call.
+ *
+ * A thrown handler error becomes `{ error }`, which the agent runner turns into
+ * a rejected tool call — the agent is told the truth, not a silent success.
+ *
+ * See `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.
+ */
+
+import { describeError } from "../internal/describe-error";
+import type {
+  ClientCapabilityContext,
+  ClientCapabilityLogger,
+  DefinedClientCapability,
+} from "../types/client-capability";
+import { type CapabilityAnnounceFetcher, useAgentCapabilities } from "./useAgentCapabilities";
+import { DEFAULT_APPROVAL_TIMEOUT_MS, useCapabilityApproval } from "./useCapabilityApproval";
+
+/**
+ * The agent → browser event, as it arrives on the SSE stream. Consumer apps tag
+ * it with their own routing fields (forge-workspace adds `_mode`); those are
+ * ignored here.
+ */
+export interface CapabilityInvokedEvent {
+  type: "capability_invoked";
+  /** Correlation token to answer with. */
+  callId: string;
+  /** Capability name as invoked — possibly a deprecated alias. */
+  name: string;
+  /** Raw, unvalidated arguments from the model. */
+  input?: unknown;
+  /**
+   * Spec §L4 — the one subscriber this invocation is addressed to, as elected
+   * by `ClientCapabilityBridge.routeTo()`. Present only when the app forwards
+   * it; absent (or `null`) means "whoever is listening", the pre-05 behaviour.
+   *
+   * A tab whose own `useAgentCapabilities().subscriberId` does not match is the
+   * *incumbent*: it stays connected and simply ignores the frame.
+   */
+  ownerId?: string | null;
+  /**
+   * Apps tag their SSE frames with their own routing fields — forge-workspace
+   * adds `_mode`. They are passed through untouched, and kept on the type so a
+   * caller can still read its own tag after the guard has narrowed the frame.
+   */
+  [key: string]: unknown;
+}
+
+export interface HandleInvocationOptions {
+  /**
+   * The upward POST endpoint that answers a parked call, e.g.
+   * `/api/agent/capability-result`. The consuming app owns this route —
+   * forge-app-actions never assumes a path.
+   */
+  endpoint: string;
+  /**
+   * Extra fields merged into the JSON body, identifying the session to the
+   * app's own route (e.g. `{ mode: "work" }`). The session key
+   * itself is derived server-side; never send it from the browser.
+   */
+  body?: Record<string, unknown>;
+  /**
+   * Opaque session key for the handler's {@link ClientCapabilityContext}.
+   * Informational only — the browser does not get to name its own session.
+   */
+  sessionKey?: string;
+  /** Override the fetcher. Defaults to `globalThis.fetch`. */
+  fetcher?: CapabilityAnnounceFetcher;
+  /** Logger handed to the handler and used for this module's own warnings. */
+  log?: ClientCapabilityLogger;
+  /**
+   * Deadline for an unanswered approval dialog, in ms. Only consulted for a
+   * capability that declares `requiresApproval`, and only when the capability
+   * itself declares no `callTimeoutMs`. Defaults to
+   * {@link DEFAULT_APPROVAL_TIMEOUT_MS}; `0` disables the browser-side deadline
+   * and leaves the agent runner's own backstop as the only limit.
+   */
+  approvalTimeoutMs?: number;
+  /**
+   * Cancels a pending approval dialog from outside — session teardown, a mode
+   * switch, a route change. An aborted signal settles the dialog as
+   * `approval-cancelled`; it does **not** interrupt a handler that has already
+   * started.
+   */
+  signal?: AbortSignal;
+}
+
+/** Why an invocation failed, when it did. */
+export type InvocationFailure =
+  /** No capability of that name is registered in this browser. */
+  | "unknown-capability"
+  /** The input did not satisfy the declared zod schema. The handler never ran. */
+  | "invalid-input"
+  /**
+   * The capability declared `requiresApproval` and the user said no. The
+   * handler never ran and nothing was mutated.
+   */
+  | "declined"
+  /**
+   * An approval dialog went unanswered past the per-call deadline. The dialog
+   * was closed and the handler never ran.
+   */
+  | "approval-timeout"
+  /**
+   * A pending approval dialog was withdrawn — `options.signal` aborted, or
+   * `useCapabilityApproval().reset()` ran on teardown. The handler never ran.
+   */
+  | "approval-cancelled"
+  /** The handler itself threw. */
+  | "handler-error";
+
+/** What {@link UseCapabilityInvocationsReturn.handle} did with one event. */
+export interface InvocationOutcome {
+  callId: string;
+  name: string;
+  ok: boolean;
+  /** The handler's return value, when `ok`. */
+  result?: unknown;
+  /** The message sent back to the agent, when not `ok`. */
+  error?: string;
+  /** Present when not `ok`. */
+  failure?: InvocationFailure;
+  /** Whether the answering POST succeeded. */
+  posted: boolean;
+}
+
+export interface UseCapabilityInvocationsReturn {
+  /** Narrowing type-guard for an SSE frame. */
+  isInvocation(event: unknown): event is CapabilityInvokedEvent;
+  /**
+   * Handle one SSE frame. Returns `null` — and does nothing — when the frame is
+   * not a `capability_invoked`, so a caller can use it as the first line of its
+   * event switch and fall through. Also `null` when the frame names a different
+   * tab as its §L4 owner: this tab is the inert incumbent for that call.
+   *
+   * Never throws: every failure path ends in an `{ error }` answer to the agent.
+   */
+  handle(event: unknown, options: HandleInvocationOptions): Promise<InvocationOutcome | null>;
+}
+
+const defaultLog: ClientCapabilityLogger = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args),
+};
+
+function isInvocationEvent(event: unknown): event is CapabilityInvokedEvent {
+  if (!event || typeof event !== "object") return false;
+  const e = event as Record<string, unknown>;
+  return (
+    e.type === "capability_invoked" &&
+    typeof e.callId === "string" &&
+    e.callId.length > 0 &&
+    typeof e.name === "string" &&
+    e.name.length > 0
+  );
+}
+
+async function postResult(
+  options: HandleInvocationOptions,
+  callId: string,
+  result: unknown,
+  log: ClientCapabilityLogger,
+): Promise<boolean> {
+  const fetcher =
+    options.fetcher ?? (globalThis as { fetch?: CapabilityAnnounceFetcher }).fetch ?? undefined;
+  if (!fetcher) {
+    log.warn("[useCapabilityInvocations] no fetch implementation available");
+    return false;
+  }
+  try {
+    const res = await fetcher(options.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ...options.body, callId, result }),
+    });
+    if (!res.ok) {
+      log.warn(`[useCapabilityInvocations] capability-result POST failed: HTTP ${res.status}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    log.warn(`[useCapabilityInvocations] capability-result POST failed: ${describeError(err)}`);
+    return false;
+  }
+}
+
+/**
+ * Inbound dispatcher for agent-invoked browser capabilities.
+ *
+ * Stateless — the registry it dispatches against is
+ * `useAgentCapabilities()`'s module-level singleton.
+ */
+export function useCapabilityInvocations(): UseCapabilityInvocationsReturn {
+  async function handle(
+    event: unknown,
+    options: HandleInvocationOptions,
+  ): Promise<InvocationOutcome | null> {
+    if (!isInvocationEvent(event)) return null;
+
+    const log = options.log ?? defaultLog;
+    const { callId, name } = event;
+    const registry = useAgentCapabilities();
+
+    // Spec §L4 — single owner, last-writer-wins. Two tabs on one session both
+    // announce, both stay connected, but only the most recently announced one
+    // runs handlers. Apps are expected to filter their fan-out server-side as
+    // well; this is the second line of defence for fan-outs that cannot, and it
+    // is what stops a side effect from happening twice. The incumbent answers
+    // nothing — the owner's POST is the single answer to this callId.
+    if (typeof event.ownerId === "string" && event.ownerId !== registry.subscriberId) {
+      log.info(
+        `[useCapabilityInvocations] ${name} (${callId}) is addressed to another tab; ignoring`,
+      );
+      return null;
+    }
+    const capability: DefinedClientCapability | undefined = registry.get(name);
+
+    const fail = async (failure: InvocationFailure, error: string): Promise<InvocationOutcome> => {
+      log.warn(`[useCapabilityInvocations] ${name} (${callId}) ${failure}: ${error}`);
+      const posted = await postResult(options, callId, { error }, log);
+      return { callId, name, ok: false, error, failure, posted };
+    };
+
+    if (!capability) {
+      return fail(
+        "unknown-capability",
+        `No capability named "${name}" is registered in this browser.`,
+      );
+    }
+
+    // Validate BEFORE the handler runs. `inputSchema` on the wire only shapes
+    // what the model tries to send; this is what actually enforces it.
+    let input: unknown;
+    try {
+      input = capability.inputZod.parse(event.input ?? {});
+    } catch (err) {
+      return fail("invalid-input", `Invalid input for "${name}": ${describeError(err)}`);
+    }
+
+    // The approval gate (spec §3 L7). It sits AFTER validation on purpose: the
+    // user is shown the arguments that would actually run, and an invocation
+    // the schema would have rejected never interrupts them.
+    //
+    // A capability that does not declare `requiresApproval` skips this branch
+    // entirely — no dialog, no extra await, no behaviour change.
+    if (capability.requiresApproval) {
+      const decision = await useCapabilityApproval().request({
+        callId,
+        name,
+        displayName: capability.displayName,
+        description: capability.description,
+        input,
+        // The capability's own per-call timeout governs its dialog, so the gate
+        // cannot outlive the call the bridge parked for it.
+        timeoutMs:
+          capability.callTimeoutMs ?? options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+        signal: options.signal,
+      });
+      if (decision === "declined") {
+        return fail("declined", `The user declined "${name}".`);
+      }
+      if (decision === "timeout") {
+        return fail(
+          "approval-timeout",
+          `Approval for "${name}" was not answered in time; the action did not run.`,
+        );
+      }
+      if (decision !== "approved") {
+        return fail(
+          "approval-cancelled",
+          `Approval for "${name}" was cancelled; the action did not run.`,
+        );
+      }
+    }
+
+    const ctx: ClientCapabilityContext = {
+      sessionKey: options.sessionKey ?? "",
+      callId,
+      name,
+      log,
+    };
+
+    let result: unknown;
+    try {
+      result = await capability.handler(input, ctx);
+    } catch (err) {
+      return fail("handler-error", describeError(err));
+    }
+
+    // Output validation is advisory. A handler that returns the wrong shape is
+    // an app bug, not an agent-visible failure, and turning it into one would
+    // invent a new way for a working action to report failure.
+    if (capability.outputZod) {
+      const check = capability.outputZod.safeParse(result);
+      if (!check.success) {
+        log.warn(
+          `[useCapabilityInvocations] ${name} returned a value that does not match its ` +
+            `declared output schema: ${describeError(check.error)}`,
+        );
+      }
+    }
+
+    const posted = await postResult(options, callId, result, log);
+    return { callId, name, ok: true, result, posted };
+  }
+
+  return { isInvocation: isInvocationEvent, handle };
+}

package/src/runtime/composables/useCommandPalette.ts

@@ -0,0 +1,97 @@
+import { readonly, ref } from "vue";
+import type { DeepReadonly, Ref } from "vue";
+import type { PaletteAction } from "../types/command-palette";
+
+// ── Module-level singleton ─────────────────────────────────────────────────
+// Survives component unmounts — same pattern as capabilityRegistry.
+const _actions = ref<PaletteAction[]>([]);
+const _isOpen = ref(false);
+
+// ── Public API types ───────────────────────────────────────────────────────
+
+export interface UseCommandPaletteReturn {
+  /** Register an action. Idempotent by id — replaces existing if same id. */
+  registerAction(action: PaletteAction): void;
+  /** Remove a previously registered action. No-op if id not found. */
+  unregisterAction(id: string): void;
+  /**
+   * Fuzzy-filter registered actions by search string.
+   * Matches against label, description, and keywords.
+   * Returns all actions when search is empty or whitespace-only.
+   * Results are sorted: exact-label-start matches first, then substring.
+   */
+  queryActions(search: string): PaletteAction[];
+  /** Reactive list of all currently registered actions. */
+  actions: DeepReadonly<Ref<PaletteAction[]>>;
+  /** Open/close state (read-only — toggled by ForgeCommandPalette). */
+  isOpen: Readonly<Ref<boolean>>;
+  /** Programmatically open the palette. */
+  open(): void;
+  /** Programmatically close the palette. */
+  close(): void;
+}
+
+// ── Implementation ─────────────────────────────────────────────────────────
+
+/**
+ * Global command palette registry.
+ * Components call registerAction() to expose actions in the Cmd+K palette.
+ */
+export function useCommandPalette(): UseCommandPaletteReturn {
+  function registerAction(action: PaletteAction): void {
+    const idx = _actions.value.findIndex((a) => a.id === action.id);
+    if (idx !== -1) {
+      // Replace existing — idempotent
+      _actions.value = [..._actions.value.slice(0, idx), action, ..._actions.value.slice(idx + 1)];
+    } else {
+      _actions.value = [..._actions.value, action];
+    }
+  }
+
+  function unregisterAction(id: string): void {
+    const idx = _actions.value.findIndex((a) => a.id === id);
+    if (idx === -1) return; // no-op
+    _actions.value = _actions.value.filter((a) => a.id !== id);
+  }
+
+  function queryActions(search: string): PaletteAction[] {
+    const trimmed = search.trim().toLowerCase();
+    if (!trimmed) return [..._actions.value];
+
+    const matches = _actions.value.filter((action) => {
+      const haystack = [action.label, action.description ?? "", ...(action.keywords ?? [])]
+        .join(" ")
+        .toLowerCase();
+      return haystack.includes(trimmed);
+    });
+
+    // Sort: exact-label-start matches first, then remaining substring matches
+    matches.sort((a, b) => {
+      const aStarts = a.label.toLowerCase().startsWith(trimmed);
+      const bStarts = b.label.toLowerCase().startsWith(trimmed);
+      if (aStarts && !bStarts) return -1;
+      if (!aStarts && bStarts) return 1;
+      return 0;
+    });
+
+    return matches;
+  }
+
+  function open(): void {
+    _isOpen.value = true;
+  }
+
+  function close(): void {
+    _isOpen.value = false;
+  }
+
+  return {
+    registerAction,
+    unregisterAction,
+    queryActions,
+    actions: readonly(_actions),
+    isOpen: readonly(_isOpen),
+    open,
+    close,
+  };
+}