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

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

@@ -0,0 +1,82 @@
+/**
+ * `defineForgeAction` — one declaration for Cmd+K and the agent.
+ *
+ * Spec: `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.3,
+ * which adopts the platform's rule verbatim — *"All user-facing functionality is
+ * a command-palette action; register it so it is discoverable via Cmd+K **and**
+ * usable by the AI agent"*.
+ *
+ * ```ts
+ * export const openFile = defineForgeAction({
+ *   id: "workspace.open_file",           // → capability `app.workspace.open_file`
+ *   label: "Open file…",
+ *   description: "Open a file in the user's file viewer.",
+ *   input: z.object({ path: z.string().min(1) }),
+ *   arg: { placeholder: "path/to/file", toInput: (path) => ({ path }) },
+ *   run: async ({ path }) => { await useFileViewer().openFile(path); return { opened: true, path } },
+ * })
+ * ```
+ *
+ * `audience` defaults to `['user', 'llm']`. That default is the whole point:
+ * a new UI feature is agent-controllable unless its author opts out, instead of
+ * agent-controllability being a bespoke per-feature integration.
+ *
+ * ## No third registry
+ *
+ * This does not store anything. It *projects* one declaration into the two
+ * registries forge already had — `useCommandPalette()` (idempotent by id) and
+ * `useAgentCapabilities()` (idempotent by name) — and `useForgeActions()`
+ * writes through to both. Those remain the single sources of truth for "what is
+ * in the palette" and "what may the agent call", so nothing can drift.
+ *
+ * ## The id/name seam
+ *
+ * The palette has always used bare ids (`workspace.open_file`); the platform
+ * **rejects** capability registrations outside the `app.` namespace (spec §2.2).
+ * The rule is therefore: **author the palette id, and the capability name is
+ * `app.<id>`.** An id that already carries the prefix is a mistake and throws,
+ * because otherwise `app.app.workspace.open_file` would ship silently.
+ */
+import * as z from "zod";
+import type { DefineForgeActionArgs, ForgeAction, ForgeActionAudience } from "../types/forge-action.js";
+/** The default when `audience` is omitted: reachable from both surfaces. */
+export declare const DEFAULT_FORGE_ACTION_AUDIENCE: ForgeActionAudience[];
+/**
+ * Build a {@link ForgeAction} from one declaration.
+ *
+ * Throws — at define time, i.e. on the first import in dev — for the four
+ * declarations that could only fail later and further away:
+ *  - an `id` that already starts with `app.` (see the id/name seam above),
+ *  - an llm-audience action with no `description` (the model reads nothing),
+ *  - an llm-audience `id` that is not `<sector>.<verb>` (spec §2.2's namespace),
+ *  - a user-audience action whose input needs arguments but declares no `arg`
+ *    (a palette row that exists only to fail on Enter).
+ */
+export declare function defineForgeAction<T extends z.ZodType = z.ZodObject<Record<string, never>>>(args: DefineForgeActionArgs<T>): ForgeAction;
+export interface UseForgeActionsReturn {
+    /**
+     * Write one action through to the registries its audience names. Idempotent:
+     * the palette replaces by id and the capability registry replaces by name,
+     * exactly as they already did, so re-registering on HMR or a remount is a
+     * no-op rather than a duplicate.
+     */
+    register(action: ForgeAction): ForgeAction;
+    /** Register several, in order. */
+    registerAll(actions: ForgeAction[]): void;
+    /**
+     * Remove an action from both registries, aliases included. Takes the action
+     * itself rather than an id — the aliases it owns cannot be derived from one.
+     */
+    unregister(action: ForgeAction): void;
+}
+/**
+ * Register forge actions into the palette and the agent capability registry.
+ *
+ * ```ts
+ * export default defineNuxtPlugin(() => {
+ *   useForgeActions().registerAll([openFile, toggleSidebar])
+ *   // then announce upward once — see the app-channel wiring
+ * })
+ * ```
+ */
+export declare function useForgeActions(): UseForgeActionsReturn;

package/dist/runtime/composables/defineForgeAction.js

@@ -0,0 +1,147 @@
+import * as z from "zod";
+import { defineClientCapability, deprecatedClientCapabilityAlias } from "./defineClientCapability.js";
+import { useAgentCapabilities } from "./useAgentCapabilities.js";
+import { useCommandPalette } from "./useCommandPalette.js";
+export const DEFAULT_FORGE_ACTION_AUDIENCE = ["user", "llm"];
+const ID_PATTERN = /^[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)+$/;
+const defaultLog = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+function fail(id, message) {
+  throw new Error(`[defineForgeAction] ${id}: ${message}`);
+}
+export function defineForgeAction(args) {
+  const { id } = args;
+  if (!id || id.trim().length === 0) fail("<empty>", "an action needs a non-empty id.");
+  const audience = args.audience ?? DEFAULT_FORGE_ACTION_AUDIENCE;
+  if (audience.length === 0) {
+    fail(id, "audience is empty \u2014 an action nobody can trigger is not an action.");
+  }
+  const forUser = audience.includes("user");
+  const forLlm = audience.includes("llm");
+  if (id.startsWith("app.")) {
+    fail(
+      id,
+      `the id is the PALETTE id and must not carry the \`app.\` prefix \u2014 it is added automatically to derive the capability name. Use "${id.slice(4)}".`
+    );
+  }
+  const name = args.name ?? `app.${id}`;
+  if (forLlm) {
+    if (!args.description) {
+      fail(id, "an action with audience 'llm' must declare a description \u2014 the model reads it.");
+    }
+    if (!args.name && !ID_PATTERN.test(id)) {
+      fail(
+        id,
+        `an agent-visible id must be lowercase \`<sector>.<verb>\` (spec \xA72.2), so the derived capability name lands in the platform's \`app.\` namespace as \`app.${id}\`.`
+      );
+    }
+    if (!name.startsWith("app.")) {
+      fail(
+        id,
+        `capability name "${name}" is outside the \`app.\` namespace, which the platform rejects.`
+      );
+    }
+  }
+  const inputZod = args.input ?? z.object({});
+  const acceptsNoArgs = inputZod.safeParse({}).success;
+  if (forUser && !acceptsNoArgs && !args.arg) {
+    fail(
+      id,
+      "the input schema requires arguments but no `arg` was declared, so the Cmd+K entry could never run. Declare `arg: { placeholder, toInput }` (and optionally `options` for a picker), or narrow the audience to ['llm']."
+    );
+  }
+  async function run(rawInput, ctxIn) {
+    const parsed = inputZod.parse(rawInput ?? {});
+    const ctx = {
+      source: ctxIn?.source ?? "user",
+      name: ctxIn?.name ?? name,
+      sessionKey: ctxIn?.sessionKey ?? "",
+      callId: ctxIn?.callId,
+      log: ctxIn?.log ?? defaultLog
+    };
+    return await args.run(parsed, ctx);
+  }
+  let paletteAction;
+  if (forUser) {
+    paletteAction = {
+      id,
+      label: args.label,
+      // The model's description is written to be exhaustive; a palette row is
+      // one line. `hint` is where an action visible on both surfaces says the
+      // short version.
+      description: args.hint ?? args.description,
+      icon: args.icon,
+      keywords: args.keywords,
+      group: args.group,
+      // `arg` carries `toInput`, which is this module's business, not the
+      // palette's — project down to the prompt half the component consumes.
+      arg: args.arg ? {
+        label: args.arg.label,
+        placeholder: args.arg.placeholder,
+        options: args.arg.options,
+        allowCustom: args.arg.allowCustom
+      } : void 0,
+      handler: async (value) => {
+        const input = args.arg ? args.arg.toInput(value ?? "") : {};
+        await run(input, { source: "user" });
+      }
+    };
+  }
+  const capability = forLlm ? defineClientCapability({
+    name,
+    displayName: args.label,
+    description: args.description,
+    input: inputZod,
+    output: args.output,
+    kind: args.kind,
+    audience,
+    scope: args.scope,
+    requiresApproval: args.requiresApproval,
+    promptFragment: args.promptFragment,
+    callTimeoutMs: args.callTimeoutMs,
+    render: args.render,
+    // Input arrives already parsed by `useCapabilityInvocations`; re-parsing
+    // here would only pay the cost twice.
+    handler: async (input, capCtx) => await args.run(input, {
+      source: "llm",
+      name: capCtx.name,
+      sessionKey: capCtx.sessionKey,
+      callId: capCtx.callId,
+      log: capCtx.log
+    })
+  }) : void 0;
+  const aliases = capability && args.deprecatedNames ? args.deprecatedNames.map((old) => deprecatedClientCapabilityAlias(capability, old)) : [];
+  return {
+    id,
+    name,
+    label: args.label,
+    audience,
+    inputZod,
+    paletteAction,
+    capability,
+    aliases,
+    run
+  };
+}
+export function useForgeActions() {
+  const palette = useCommandPalette();
+  const capabilities = useAgentCapabilities();
+  function register(action) {
+    if (action.paletteAction) palette.registerAction(action.paletteAction);
+    if (action.capability) capabilities.register(action.capability);
+    for (const alias of action.aliases) capabilities.register(alias);
+    return action;
+  }
+  function registerAll(actions) {
+    for (const action of actions) register(action);
+  }
+  function unregister(action) {
+    palette.unregisterAction(action.id);
+    capabilities.unregister(action.name);
+    for (const alias of action.aliases) capabilities.unregister(alias.name);
+  }
+  return { register, registerAll, unregister };
+}

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

@@ -0,0 +1,78 @@
+import { type ShallowRef } from "vue";
+import type { ClientCapabilityDescriptor, DefinedClientCapability } from "../types/client-capability.js";
+/** Minimal `fetch` shape the announce transport needs. Injectable for tests. */
+export type CapabilityAnnounceFetcher = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface AnnounceOptions {
+    /**
+     * The upward POST endpoint, e.g. `/api/agent/capabilities`. The consuming app
+     * owns this route (spec §2) — forge-app-actions never assumes a path.
+     */
+    endpoint: string;
+    /**
+     * Extra fields merged into the JSON body. This is where the app supplies
+     * whatever identifies the session to its own route — a single-session app
+     * sends nothing; a multi-user app would send the parts of its
+     * `userId:slug:mode` key. Never send the derived key from the browser if the
+     * server can derive it itself.
+     */
+    body?: Record<string, unknown>;
+    /** Override the fetcher. Defaults to `globalThis.fetch`. */
+    fetcher?: CapabilityAnnounceFetcher;
+}
+export interface AnnounceResult {
+    ok: boolean;
+    /** How many capability descriptors were sent. `0` for a withdrawal. */
+    sent: number;
+    /** Present when `ok` is false. */
+    error?: string;
+}
+export interface UseAgentCapabilitiesReturn {
+    /** Register a capability. Idempotent by name — replaces an existing entry. */
+    register(capability: DefinedClientCapability): void;
+    /** Register several at once. Idempotent by name, in order. */
+    registerAll(capabilities: DefinedClientCapability[]): void;
+    /** Remove a previously registered capability. No-op if the name is unknown. */
+    unregister(name: string): void;
+    /** Look up one registered capability by name. */
+    get(name: string): DefinedClientCapability | undefined;
+    /** Snapshot of every registered capability (schemas and handlers included). */
+    list(): DefinedClientCapability[];
+    /** The JSON-serialisable projection announced upward. */
+    toWire(): ClientCapabilityDescriptor[];
+    /** Reactive list of registered capabilities. */
+    capabilities: Readonly<ShallowRef<DefinedClientCapability[]>>;
+    /** Stable per-tab token sent with every announcement. */
+    subscriberId: string;
+    /**
+     * POST the whole registry upward. Announcements are never deltas — the bridge
+     * replaces its stored list, so a reconnect re-announce is naturally idempotent
+     * (spec §L5).
+     *
+     * Never throws: a failed announce logs a warning and returns `ok: false`, so a
+     * dead route cannot break app mount.
+     */
+    announce(options: AnnounceOptions): Promise<AnnounceResult>;
+    /**
+     * POST an empty registry upward — the explicit withdrawal seam for spec §L1's
+     * "no browser, no capability". Ticket 05 adds the SSE-disconnect grace period
+     * that calls this from the server side; this is the voluntary client-side path.
+     */
+    withdraw(options: AnnounceOptions): Promise<AnnounceResult>;
+    /** Test-only: empty the singleton. Not for application code. */
+    reset(): void;
+}
+/**
+ * Browser-side agent capability registry.
+ *
+ * Components and plugins call `register()` to declare what the agent may invoke
+ * in this tab, then `announce()` once on mount so Nitro — and through it the
+ * agent's `capability_register` — reflects that a UI actually exists.
+ */
+export declare function useAgentCapabilities(): UseAgentCapabilitiesReturn;

package/dist/runtime/composables/useAgentCapabilities.js

@@ -0,0 +1,94 @@
+import { shallowRef } from "vue";
+const _capabilities = shallowRef([]);
+const _subscriberId = mintSubscriberId();
+function mintSubscriberId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  return `sub-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+function toDescriptor(capability) {
+  const {
+    inputZod: _inputZod,
+    outputZod: _outputZod,
+    handler: _handler,
+    ...descriptor
+  } = capability;
+  return descriptor;
+}
+async function post(options, payload) {
+  const sent = payload.capabilities.length;
+  const fetcher = options.fetcher ?? globalThis.fetch ?? void 0;
+  if (!fetcher) {
+    return { ok: false, sent, error: "no fetch implementation available" };
+  }
+  try {
+    const res = await fetcher(options.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ...options.body, ...payload })
+    });
+    if (!res.ok) {
+      const error = `announce failed: HTTP ${res.status}`;
+      console.warn(`[useAgentCapabilities] ${error}`);
+      return { ok: false, sent, error };
+    }
+    return { ok: true, sent };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    console.warn(`[useAgentCapabilities] announce failed: ${error}`);
+    return { ok: false, sent, error };
+  }
+}
+export function useAgentCapabilities() {
+  function register(capability) {
+    const idx = _capabilities.value.findIndex((c) => c.name === capability.name);
+    if (idx !== -1) {
+      _capabilities.value = [
+        ..._capabilities.value.slice(0, idx),
+        capability,
+        ..._capabilities.value.slice(idx + 1)
+      ];
+    } else {
+      _capabilities.value = [..._capabilities.value, capability];
+    }
+  }
+  function registerAll(capabilities) {
+    for (const capability of capabilities) register(capability);
+  }
+  function unregister(name) {
+    const idx = _capabilities.value.findIndex((c) => c.name === name);
+    if (idx === -1) return;
+    _capabilities.value = _capabilities.value.filter((c) => c.name !== name);
+  }
+  function get(name) {
+    return _capabilities.value.find((c) => c.name === name);
+  }
+  function list() {
+    return [..._capabilities.value];
+  }
+  function toWire() {
+    return _capabilities.value.map(toDescriptor);
+  }
+  function announce(options) {
+    return post(options, { subscriberId: _subscriberId, capabilities: toWire() });
+  }
+  function withdraw(options) {
+    return post(options, { subscriberId: _subscriberId, capabilities: [] });
+  }
+  function reset() {
+    _capabilities.value = [];
+  }
+  return {
+    register,
+    registerAll,
+    unregister,
+    get,
+    list,
+    toWire,
+    capabilities: _capabilities,
+    subscriberId: _subscriberId,
+    announce,
+    withdraw,
+    reset
+  };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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, type 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 declare const DEFAULT_APPROVAL_TIMEOUT_MS = 30000;
+/** 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;
+}
+/**
+ * The approval queue behind `requiresApproval`.
+ *
+ * Stateless accessor over a module-level singleton — call it from anywhere.
+ */
+export declare function useCapabilityApproval(): UseCapabilityApprovalReturn;

package/dist/runtime/composables/useCapabilityApproval.js

@@ -0,0 +1,74 @@
+import { computed, shallowRef } from "vue";
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 3e4;
+const _pending = shallowRef([]);
+const _settlers = /* @__PURE__ */ new Map();
+let _seq = 0;
+function nextId() {
+  _seq += 1;
+  return `approval-${_seq}`;
+}
+const _current = computed(() => _pending.value[0] ?? null);
+function settle(id, decision) {
+  return _settlers.get(id)?.(decision) ?? false;
+}
+function request(options) {
+  return new Promise((resolve) => {
+    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 : void 0;
+    let timer;
+    let settled = false;
+    const finish = (decision) => {
+      if (settled) return false;
+      settled = true;
+      if (timer !== void 0) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      _settlers.delete(id);
+      _pending.value = _pending.value.filter((entry) => entry.id !== id);
+      resolve(decision);
+      return true;
+    };
+    function onAbort() {
+      finish("cancelled");
+    }
+    _settlers.set(id, finish);
+    if (timeoutMs !== void 0) {
+      timer = setTimeout(() => finish("timeout"), timeoutMs);
+      timer.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 === void 0 ? void 0 : requestedAt + timeoutMs
+      }
+    ];
+  });
+}
+export function useCapabilityApproval() {
+  return {
+    pending: _pending,
+    current: _current,
+    request,
+    approve: (id) => settle(id, "approved"),
+    decline: (id) => settle(id, "declined"),
+    cancel: (id) => settle(id, "cancelled"),
+    reset: () => {
+      for (const id of [..._settlers.keys()]) settle(id, "cancelled");
+      _pending.value = [];
+    }
+  };
+}