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

package/dist/runtime/composables/useCapabilityInvocations.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 type { ClientCapabilityLogger } from "../types/client-capability.js";
+import { type CapabilityAnnounceFetcher } from "./useAgentCapabilities.js";
+/**
+ * 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>;
+}
+/**
+ * Inbound dispatcher for agent-invoked browser capabilities.
+ *
+ * Stateless — the registry it dispatches against is
+ * `useAgentCapabilities()`'s module-level singleton.
+ */
+export declare function useCapabilityInvocations(): UseCapabilityInvocationsReturn;

package/dist/runtime/composables/useCapabilityInvocations.js

@@ -0,0 +1,129 @@
+import { useAgentCapabilities } from "./useAgentCapabilities.js";
+import { DEFAULT_APPROVAL_TIMEOUT_MS, useCapabilityApproval } from "./useCapabilityApproval.js";
+const defaultLog = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+function isInvocationEvent(event) {
+  if (!event || typeof event !== "object") return false;
+  const e = event;
+  return e.type === "capability_invoked" && typeof e.callId === "string" && e.callId.length > 0 && typeof e.name === "string" && e.name.length > 0;
+}
+function describeError(err) {
+  if (err && typeof err === "object" && Array.isArray(err.issues)) {
+    const issues = err.issues;
+    const lines = issues.map((issue) => {
+      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+      return path ? `${path}: ${issue.message}` : String(issue.message);
+    });
+    if (lines.length > 0) return lines.join("; ");
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+async function postResult(options, callId, result, log) {
+  const fetcher = options.fetcher ?? globalThis.fetch ?? void 0;
+  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;
+  }
+}
+export function useCapabilityInvocations() {
+  async function handle(event, options) {
+    if (!isInvocationEvent(event)) return null;
+    const log = options.log ?? defaultLog;
+    const { callId, name } = event;
+    const registry = useAgentCapabilities();
+    if (typeof event.ownerId === "string" && event.ownerId !== registry.subscriberId) {
+      log.info(
+        `[useCapabilityInvocations] ${name} (${callId}) is addressed to another tab; ignoring`
+      );
+      return null;
+    }
+    const capability = registry.get(name);
+    const fail = async (failure, error) => {
+      log.warn(`[useCapabilityInvocations] ${name} (${callId}) ${failure}: ${error}`);
+      const posted2 = await postResult(options, callId, { error }, log);
+      return { callId, name, ok: false, error, failure, posted: posted2 };
+    };
+    if (!capability) {
+      return fail(
+        "unknown-capability",
+        `No capability named "${name}" is registered in this browser.`
+      );
+    }
+    let input;
+    try {
+      input = capability.inputZod.parse(event.input ?? {});
+    } catch (err) {
+      return fail("invalid-input", `Invalid input for "${name}": ${describeError(err)}`);
+    }
+    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 = {
+      sessionKey: options.sessionKey ?? "",
+      callId,
+      name,
+      log
+    };
+    let result;
+    try {
+      result = await capability.handler(input, ctx);
+    } catch (err) {
+      return fail("handler-error", describeError(err));
+    }
+    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/dist/runtime/composables/useCommandPalette.d.ts

@@ -0,0 +1,28 @@
+import type { DeepReadonly, Ref } from "vue";
+import type { PaletteAction } from "../types/command-palette.js";
+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;
+}
+/**
+ * Global command palette registry.
+ * Components call registerAction() to expose actions in the Cmd+K palette.
+ */
+export declare function useCommandPalette(): UseCommandPaletteReturn;

package/dist/runtime/composables/useCommandPalette.js

@@ -0,0 +1,49 @@
+import { readonly, ref } from "vue";
+const _actions = ref([]);
+const _isOpen = ref(false);
+export function useCommandPalette() {
+  function registerAction(action) {
+    const idx = _actions.value.findIndex((a) => a.id === action.id);
+    if (idx !== -1) {
+      _actions.value = [..._actions.value.slice(0, idx), action, ..._actions.value.slice(idx + 1)];
+    } else {
+      _actions.value = [..._actions.value, action];
+    }
+  }
+  function unregisterAction(id) {
+    const idx = _actions.value.findIndex((a) => a.id === id);
+    if (idx === -1) return;
+    _actions.value = _actions.value.filter((a) => a.id !== id);
+  }
+  function queryActions(search) {
+    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);
+    });
+    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() {
+    _isOpen.value = true;
+  }
+  function close() {
+    _isOpen.value = false;
+  }
+  return {
+    registerAction,
+    unregisterAction,
+    queryActions,
+    actions: readonly(_actions),
+    isOpen: readonly(_isOpen),
+    open,
+    close
+  };
+}

package/dist/runtime/composables/usePaletteArgStep.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The command palette's **argument step**.
+ *
+ * A `PaletteAction` that declares `arg` needs one string before it can run
+ * (`defineForgeAction`'s `arg.toInput` turns that string into the action's
+ * typed input). Selecting such an action does not close the palette: it swaps
+ * the list for the action's candidates and waits for a second Enter.
+ *
+ * This holds the per-component state for that step. It lives here rather than
+ * inline in the components because both UI-kit variants of
+ * `ForgeCommandPalette` run it and are kept in deliberate lock-step — one copy
+ * cannot drift from the other if there is only one copy.
+ *
+ * Not a singleton: `useCommandPalette()` owns the shared registry, this owns
+ * one palette instance's transient step.
+ */
+import { type ComputedRef, type Ref, type ShallowRef } from "vue";
+import type { PaletteAction, PaletteArgOption, PaletteArgPrompt } from "../types/command-palette.js";
+export interface UsePaletteArgStepReturn {
+    /** The action awaiting its argument, or `null` when the step is not active. */
+    action: ShallowRef<PaletteAction | null>;
+    /** Candidates for the current query. Empty for a free-text argument. */
+    options: ShallowRef<PaletteArgOption[]>;
+    /** Whether a candidate lookup is in flight. */
+    loading: Ref<boolean>;
+    /** Whether the palette is currently collecting an argument. */
+    active: ComputedRef<boolean>;
+    /** The active action's prompt declaration. */
+    prompt: ComputedRef<PaletteArgPrompt | null>;
+    /**
+     * Enter the argument step for `action`. Returns `false` — and changes
+     * nothing — when the action takes no argument, so a caller can use it as
+     * `if (!begin(a)) { close(); run(a) }`.
+     */
+    begin(action: PaletteAction): boolean;
+    /** Recompute the candidates for `query`. Stale responses are discarded. */
+    query(query: string): Promise<void>;
+    /** Leave the step without running anything. */
+    cancel(): void;
+    /**
+     * The string the action should run with, given what is typed and which row is
+     * highlighted — or `null` when the step cannot complete yet (nothing typed
+     * and nothing highlighted, or a typed value the prompt does not accept).
+     */
+    valueFor(typed: string, index: number): string | null;
+}
+export declare function usePaletteArgStep(): UsePaletteArgStepReturn;

package/dist/runtime/composables/usePaletteArgStep.js

@@ -0,0 +1,51 @@
+import { computed, ref, shallowRef } from "vue";
+export function usePaletteArgStep() {
+  const action = shallowRef(null);
+  const options = shallowRef([]);
+  const loading = ref(false);
+  let ticket = 0;
+  const active = computed(() => action.value !== null);
+  const prompt = computed(() => action.value?.arg ?? null);
+  function begin(next) {
+    if (!next.arg) return false;
+    action.value = next;
+    options.value = [];
+    void query("");
+    return true;
+  }
+  async function query(text) {
+    const arg = action.value?.arg;
+    if (!arg?.options) {
+      options.value = [];
+      return;
+    }
+    const mine = ++ticket;
+    loading.value = true;
+    try {
+      const found = await arg.options(text);
+      if (mine !== ticket) return;
+      options.value = found;
+    } catch {
+      if (mine === ticket) options.value = [];
+    } finally {
+      if (mine === ticket) loading.value = false;
+    }
+  }
+  function cancel() {
+    ticket++;
+    action.value = null;
+    options.value = [];
+    loading.value = false;
+  }
+  function valueFor(typed, index) {
+    const arg = action.value?.arg;
+    if (!arg) return null;
+    const picked = options.value[index];
+    if (picked) return picked.value;
+    const allowCustom = arg.allowCustom ?? !arg.options;
+    const trimmed = typed.trim();
+    if (allowCustom && trimmed.length > 0) return trimmed;
+    return null;
+  }
+  return { action, options, loading, active, prompt, begin, query, cancel, valueFor };
+}

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Explicit entry point for the server-side client-capability bridge, via the
+ * `./server` subpath. In a Nuxt consumer the same symbols are auto-imported
+ * (the module's `addServerImportsDir` on `runtime/server/utils`).
+ */
+export * from "./utils/capability-registry.js";
+export * from "./utils/client-capability-bridge.js";

package/dist/runtime/server/index.js

@@ -0,0 +1,2 @@
+export * from "./utils/capability-registry.js";
+export * from "./utils/client-capability-bridge.js";

package/dist/runtime/server/utils/capability-registry.d.ts

@@ -0,0 +1,35 @@
+import type { AgentEvent, Capability } from "@skaile/workspaces/sdk/types";
+/** Event sink handed to a capability handler when it runs. */
+export interface CapabilityHandlerCtx {
+    /** Emit a synthetic AgentEvent into the app's SSE stream. */
+    emitEvent: (event: AgentEvent) => void;
+}
+export type CapabilityHandler = (input: Record<string, unknown>, ctx: CapabilityHandlerCtx) => Promise<unknown>;
+export interface CapabilityEntry {
+    capability: Capability;
+    handler: CapabilityHandler;
+}
+/**
+ * Plain-TS capability registry for the forge app — holds client-side v2
+ * capabilities and routes `capability_invoked` calls to their handlers.
+ */
+export declare class CapabilityRegistry {
+    private entries;
+    register(entry: CapabilityEntry): void;
+    list(): Capability[];
+    dispatch(name: string, input: Record<string, unknown>, ctx: CapabilityHandlerCtx): Promise<unknown | {
+        error: string;
+    }>;
+}
+/** Dispatch a `capability_invoked` event and send back its `capability_result`. */
+export declare function handleCapabilityInvoked(event: {
+    callId: string;
+    name: string;
+    input: unknown;
+}, deps: {
+    registry: CapabilityRegistry;
+    ctx: CapabilityHandlerCtx;
+    sendResult: (callId: string, result: unknown) => Promise<void> | void;
+}): Promise<void>;
+/** Process-wide singleton — capabilities are registered once at module load. */
+export declare const capabilityRegistry: CapabilityRegistry;

package/dist/runtime/server/utils/capability-registry.js

@@ -0,0 +1,24 @@
+export class CapabilityRegistry {
+  entries = /* @__PURE__ */ new Map();
+  register(entry) {
+    this.entries.set(entry.capability.name, entry);
+  }
+  list() {
+    return [...this.entries.values()].map((e) => e.capability);
+  }
+  async dispatch(name, input, ctx) {
+    const entry = this.entries.get(name);
+    if (!entry) return { error: `Unknown capability: ${name}` };
+    try {
+      return await entry.handler(input, ctx);
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+export async function handleCapabilityInvoked(event, deps) {
+  const input = event.input && typeof event.input === "object" ? event.input : {};
+  const result = await deps.registry.dispatch(event.name, input, deps.ctx);
+  await deps.sendResult(event.callId, result);
+}
+export const capabilityRegistry = new CapabilityRegistry();