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

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 = [];
+    }
+  };
+}

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,118 @@
+import { describeError } from "../internal/describe-error.js";
+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;
+}
+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;