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

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @skaile/forge-app-actions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-declared app actions for Skaile forge apps, as a Nuxt module.
+
+One `defineForgeAction` declaration is both a command-palette row and an agent capability. The package ships
+
+- `defineForgeAction`, `useForgeActions`, `defineClientCapability` (auto-imported in a Nuxt app, or imported from `@skaile/forge-app-actions/client-capabilities`),
+- `useAgentCapabilities` (announce) and `useCapabilityInvocations` (handle `capability_invoked` from the app's SSE and post the result),
+- `useCapabilityApproval` + `<ForgeCapabilityApproval />` (approval dialog),
+- `useCommandPalette` + `<ForgeCommandPalette />`,
+- the Nitro-side bridge (`clientCapabilityBridge`, `capabilityRegistry`) via `@skaile/forge-app-actions/server`.
+
+## Install
+
+```ts
+// nuxt.config.ts — @nuxt/ui must come first
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@skaile/forge-app-actions'],
+})
+```
+
+Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional peer (type-only imports from `@skaile/workspaces/sdk/types`).
+
+`@skaile/forge-common` installs this module for you.
+
+## Exports
+
+| Subpath | Contents |
+|---|---|
+| `.` | the Nuxt module (`forgeAppActions` config key) |
+| `./client-capabilities` | browser-side API, explicit-import entry for tests and non-auto-import contexts |
+| `./chat` | `useChatActions`, `toolNameOf` — forge actions as forge-chat client tools (browser) |
+| `./chat/server` | `clientToolsFromBody` — validates the `clientTools` request field (no Vue) |
+| `./server` | `clientCapabilityBridge`, `capabilityRegistry`, `routeCapabilityInvocation`, … |
+| `./types` | `ClientCapability*`, `ForgeAction*`, `Palette*` types |
+
+Moved here from `@skaile-ai/forge-common` 9.x (`./client-capabilities` and the capability parts of `./server` and `./types`).
+
+## Using actions from an AI-SDK chat
+
+A plain Nuxt app with an AI-SDK route (no Skaile platform, no SSE agent session) can let the model call the browser's actions through `@skaile/forge-chat` ≥ 0.2 client tools. Every action whose `audience` includes `'llm'` becomes a tool; `requiresApproval` actions wait for the user's confirmation first.
+
+**Tool names.** Model providers reject dots in tool names (Anthropic `^[a-zA-Z0-9_-]{1,64}$`, OpenAI `^[a-zA-Z0-9_-]+$`), so the tool name is `toolNameOf(capabilityName)`: every character outside `[A-Za-z0-9_-]` becomes `_`, truncated to 64. Action `doc.read` (capability `app.doc.read`) is the tool `app_doc_read`. Name tools in prompts with `toolNameOf('app.doc.read')` (exported from `@skaile/forge-app-actions/chat`). Two actions that map to the same tool name make `descriptors()` and the handler lookup throw. The handler still runs the action under its real capability name (`ctx.name === 'app.doc.read'`). Descriptor schemas are the zod-derived JSON Schema without the top-level `$schema` key.
+
+```ts
+// app/pages/index.vue
+const chatActions = useChatActions({ actions: () => actions })   // from '@skaile/forge-app-actions/chat'
+const transport = createAiSdkTransport({ url: '/api/chat', body: () => ({ clientTools: chatActions.descriptors() }) })
+const session = createChatSession({ transport, tools: chatActions.handlers })
+// app/app.vue: <ForgeCapabilityApproval />   — mount once
+
+// server/api/chat.post.ts
+import { clientToolsFromBody } from '@skaile/forge-app-actions/chat/server'
+export default defineEventHandler((event) =>
+  createAiSdkChatHandler({ model, clientTools: (ctx) => clientToolsFromBody(ctx.body) })(toWebRequest(event)))
+```
+
+Round trip: the model emits a tool call → the handler ends the turn with `turn-end` reason `tool-calls` → the session runs `chatActions.handlers[name]` → the result is pushed and the turn resumes. A handler validates the input against the action's zod schema first (invalid → the model gets `invalid input: <issues>`), then asks for approval when required (`declined` → the model gets `declined`), then runs the action with `source: 'llm'`.
+
+`clientToolsFromBody` returns `undefined` when the body has no `clientTools`, and throws an error with `statusCode: 400` (`clientTools: <issues>`) for a bad tool name, an over-long description or a non-object schema — `createAiSdkChatHandler` answers such an error with that status.
+
+Peer: `@skaile/forge-chat ^0.2.0` (optional; type-only imports).

package/dist/module.d.mts

@@ -0,0 +1,23 @@
+import { NuxtModule } from '@nuxt/schema';
+
+interface ForgeAppActionsOptions {
+    /** Disable server-side auto-imports (use explicit imports via the `./server` subpath instead). */
+    serverAutoImport?: boolean;
+    /** Disable component auto-registration. */
+    componentAutoRegister?: boolean;
+    /** Disable composable auto-imports. */
+    composableAutoImport?: boolean;
+}
+/**
+ * Nuxt module for browser-declared app actions: `defineForgeAction` /
+ * `defineClientCapability`, the agent capability bridge, the command palette
+ * and the approval dialog.
+ *
+ * Requires `@nuxt/ui` (^4.11) registered BEFORE this module in `modules`; the
+ * components render Nuxt UI primitives (<UModal>, <UButton>, <UInput>) and the
+ * host root must be wrapped in `<UApp>`.
+ */
+declare const forgeAppActionsModule: NuxtModule<ForgeAppActionsOptions>;
+
+export { forgeAppActionsModule as default };
+export type { ForgeAppActionsOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skaile/forge-app-actions",
+  "configKey": "forgeAppActions",
+  "version": "0.2.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,37 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerImportsDir, addComponentsDir, addImportsDir } from '@nuxt/kit';
+
+const forgeAppActionsModule = defineNuxtModule({
+  meta: {
+    name: "@skaile/forge-app-actions",
+    configKey: "forgeAppActions"
+  },
+  defaults: {
+    serverAutoImport: true,
+    componentAutoRegister: true,
+    composableAutoImport: true
+  },
+  async setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    if (!nuxt.options._prepare && !hasNuxtModule("@nuxt/ui", nuxt)) {
+      throw new Error(
+        "[@skaile/forge-app-actions] requires the '@nuxt/ui' module, but it was not registered before '@skaile/forge-app-actions'. Add '@nuxt/ui' to the `modules` array in your nuxt.config *before* '@skaile/forge-app-actions' (and install it as a dependency): the command palette and approval dialog render Nuxt UI primitives (<UModal>, <UButton>, \u2026)."
+      );
+    }
+    if (options.serverAutoImport) {
+      addServerImportsDir(resolve("./runtime/server/utils"));
+    }
+    if (options.componentAutoRegister) {
+      addComponentsDir({
+        path: resolve("./runtime/components-nuxt-ui"),
+        prefix: "Forge",
+        global: false,
+        pathPrefix: false
+      });
+    }
+    if (options.composableAutoImport) {
+      addImportsDir(resolve("./runtime/composables"));
+    }
+  }
+});
+
+export { forgeAppActionsModule as default };

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

@@ -0,0 +1,52 @@
+/**
+ * Browser half of the AI-SDK chat binding (`@skaile/forge-app-actions/chat`).
+ *
+ * Turns registered {@link ForgeAction}s into forge-chat **client tools**:
+ *
+ * - `descriptors()` — what the model may call. Goes into the chat request body
+ *   (`createAiSdkTransport({ body })`); the server validates it with
+ *   `clientToolsFromBody` from `@skaile/forge-app-actions/chat/server`.
+ * - `handlers` — what runs when the model calls one. Pass as
+ *   `createChatSession({ tools })`. Same contract as the SSE bridge's
+ *   `useCapabilityInvocations().handle`: validate against the live zod schema,
+ *   ask for approval (`<ForgeCapabilityApproval />`) when the action declares
+ *   `requiresApproval`, then run the handler with a `ClientCapabilityContext`.
+ *
+ * Only actions whose audience includes `'llm'` are exposed. Tools are named
+ * {@link toolNameOf}(capability name) — `app.<id>` becomes `app_<id>` — because
+ * model providers reject dots in tool names.
+ */
+import type { ClientCapabilityLogger } from "../types/client-capability.js";
+import type { ForgeAction } from "../types/forge-action.js";
+import type { ClientToolDecls, ClientToolHandlers } from "./types.js";
+export type { ClientToolDecls, ClientToolHandlers } from "./types.js";
+export interface UseChatActionsOptions {
+    /**
+     * The actions to expose, read on every use — the list may change over the
+     * lifetime of the chat (an editor that mounts later, a route-scoped action).
+     */
+    actions: () => readonly ForgeAction[];
+    /** Opaque session key for the handler's {@link ClientCapabilityContext}. Informational. */
+    sessionKey?: string;
+    /** Logger handed to handlers. Defaults to `console`. */
+    log?: ClientCapabilityLogger;
+    /**
+     * Deadline for an unanswered approval dialog, in ms; the action's own
+     * `callTimeoutMs` wins. Defaults to {@link DEFAULT_APPROVAL_TIMEOUT_MS}; `0`
+     * disables the deadline.
+     */
+    approvalTimeoutMs?: number;
+}
+export interface UseChatActionsReturn {
+    /** Tool descriptors for the request body: one per LLM-audience action. */
+    descriptors(): ClientToolDecls;
+    /** Tool handlers for `createChatSession({ tools })`, resolved against `actions()` at call time. */
+    handlers: ClientToolHandlers;
+}
+/**
+ * The provider-safe tool name of a capability name: every character outside
+ * `[A-Za-z0-9_-]` becomes `_` (Anthropic and OpenAI reject others), truncated
+ * to 64. `app.doc.read` → `app_doc_read`. Hosts use it to name tools in prompts.
+ */
+export declare function toolNameOf(capabilityName: string): string;
+export declare function useChatActions(options: UseChatActionsOptions): UseChatActionsReturn;

package/dist/runtime/chat/index.js

@@ -0,0 +1,100 @@
+import {
+  DEFAULT_APPROVAL_TIMEOUT_MS,
+  useCapabilityApproval
+} from "../composables/useCapabilityApproval.js";
+import { describeError } from "../internal/describe-error.js";
+const defaultLog = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+const TOOL_NAME_MAX = 64;
+export function toolNameOf(capabilityName) {
+  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
+}
+function withoutSchemaKey(schema) {
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+}
+export function useChatActions(options) {
+  const log = options.log ?? defaultLog;
+  function exposed() {
+    const byTool = /* @__PURE__ */ new Map();
+    for (const action of options.actions()) {
+      const capability = action.capability;
+      if (!capability || !action.audience.includes("llm")) continue;
+      const toolName = toolNameOf(capability.name);
+      const other = byTool.get(toolName);
+      if (other && other.name !== capability.name) {
+        throw new Error(
+          `[useChatActions] "${other.name}" and "${capability.name}" both map to the tool name "${toolName}"; rename one action.`
+        );
+      }
+      byTool.set(toolName, capability);
+    }
+    return byTool;
+  }
+  function descriptors() {
+    const decls = {};
+    for (const [toolName, capability] of exposed()) {
+      decls[toolName] = {
+        description: capability.description,
+        // Derived by `defineClientCapability` via `z.toJSONSchema()`; the
+        // draft marker is dropped, providers do not take it.
+        inputSchema: withoutSchemaKey(capability.inputSchema)
+      };
+    }
+    return decls;
+  }
+  function handlerFor(toolName) {
+    const capability = exposed().get(toolName);
+    if (!capability) return void 0;
+    const name = capability.name;
+    return async (rawInput, { toolCallId, signal }) => {
+      if (signal.aborted) throw new Error("aborted");
+      const checked = capability.inputZod.safeParse(rawInput ?? {});
+      if (!checked.success) throw new Error(`invalid input: ${describeError(checked.error)}`);
+      const input = checked.data;
+      if (capability.requiresApproval) {
+        const decision = await useCapabilityApproval().request({
+          callId: toolCallId,
+          name,
+          displayName: capability.displayName,
+          description: capability.description,
+          input,
+          timeoutMs: capability.callTimeoutMs ?? options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+          signal
+        });
+        if (decision === "declined") throw new Error("declined");
+        if (decision === "timeout") throw new Error("approval timed out");
+        if (decision !== "approved") throw new Error("approval cancelled");
+      }
+      const ctx = {
+        sessionKey: options.sessionKey ?? "",
+        callId: toolCallId,
+        name,
+        log
+      };
+      const result = await capability.handler(input, ctx);
+      if (capability.outputZod) {
+        const check = capability.outputZod.safeParse(result);
+        if (!check.success) {
+          log.warn(
+            `[useChatActions] ${name} returned a value that does not match its declared output schema: ${describeError(check.error)}`
+          );
+        }
+      }
+      return result ?? null;
+    };
+  }
+  const handlers = new Proxy({}, {
+    get: (_target, key) => typeof key === "string" ? handlerFor(key) : void 0,
+    has: (_target, key) => typeof key === "string" && exposed().has(key),
+    ownKeys: () => [...exposed().keys()],
+    getOwnPropertyDescriptor: (_target, key) => {
+      const handler = typeof key === "string" ? handlerFor(key) : void 0;
+      return handler ? { value: handler, enumerable: true, configurable: true, writable: false } : void 0;
+    }
+  });
+  return { descriptors, handlers };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Server half of the AI-SDK chat binding (`@skaile/forge-app-actions/chat/server`).
+ *
+ * The browser sends the descriptors of its LLM-audience actions in the chat
+ * request body (`clientTools`). This module validates that untrusted blob so a
+ * host can hand it straight to `createAiSdkChatHandler`:
+ *
+ * ```ts
+ * createAiSdkChatHandler({ clientTools: (ctx) => clientToolsFromBody(ctx.body), … })
+ * ```
+ *
+ * No Vue, no Nuxt, no `ai` import — safe for any Nitro route.
+ */
+import type { ClientToolDecls } from "./types.js";
+/** Same pattern forge-chat's handler enforces; checked here first for a precise message. */
+export declare const CLIENT_TOOL_NAME_PATTERN: RegExp;
+/** Upper bound on a tool description — descriptors come from an untrusted browser. */
+export declare const CLIENT_TOOL_DESCRIPTION_MAX = 2000;
+/**
+ * Thrown for a malformed `clientTools` body field. Carries `statusCode: 400`, so
+ * `createAiSdkChatHandler` answers with that status when it is thrown from an
+ * option callback.
+ */
+export declare class ClientToolsBodyError extends Error {
+    readonly statusCode = 400;
+    constructor(message: string);
+}
+/**
+ * Read and validate `body.clientTools`.
+ *
+ * - absent (`undefined`) → `undefined`
+ * - valid → the descriptors, unchanged
+ * - malformed → throws {@link ClientToolsBodyError} (`statusCode` 400,
+ *   message `clientTools: <path>: <issue>; …`)
+ */
+export declare function clientToolsFromBody(body: Record<string, unknown>): ClientToolDecls | undefined;

package/dist/runtime/chat/server.js

@@ -0,0 +1,27 @@
+import * as z from "zod";
+import { describeError } from "../internal/describe-error.js";
+export const CLIENT_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_.-]{0,63}$/i;
+export const CLIENT_TOOL_DESCRIPTION_MAX = 2e3;
+const clientToolsSchema = z.record(
+  z.string().regex(CLIENT_TOOL_NAME_PATTERN, "invalid tool name"),
+  z.object({
+    description: z.string().max(CLIENT_TOOL_DESCRIPTION_MAX),
+    inputSchema: z.record(z.string(), z.unknown())
+  })
+);
+export class ClientToolsBodyError extends Error {
+  statusCode = 400;
+  constructor(message) {
+    super(message);
+    this.name = "ClientToolsBodyError";
+  }
+}
+export function clientToolsFromBody(body) {
+  const raw = body.clientTools;
+  if (raw === void 0) return void 0;
+  const parsed = clientToolsSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ClientToolsBodyError(`clientTools: ${describeError(parsed.error)}`);
+  }
+  return parsed.data;
+}

package/dist/runtime/chat/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The two forge-chat contracts this binding speaks. Type-only, so
+ * `@skaile/forge-chat` stays an optional peer.
+ *
+ * `ClientToolHandlers` is derived from `ChatSessionOptions['tools']` because
+ * forge-chat does not export the alias by name.
+ */
+import type { ChatSessionOptions } from "@skaile/forge-chat/core";
+export type { ClientToolDecls } from "@skaile/forge-chat/server/ai-sdk";
+export type ClientToolHandlers = NonNullable<ChatSessionOptions["tools"]>;

package/dist/runtime/client-capabilities.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Explicit entry point for the browser-side agent capability API.
+ *
+ * In a Nuxt consumer both symbols are auto-imported (the module's
+ * `addImportsDir` on `runtime/composables`), so application code needs no
+ * import at all. This subpath exists for the contexts auto-imports do not
+ * reach: vitest specs, plain `.ts` modules outside the Nuxt app dir, and
+ * non-Nuxt consumers.
+ *
+ *   import { defineClientCapability } from "@skaile/forge-app-actions/client-capabilities"
+ *
+ * Since ticket 07 this is also where the *unified* action API lives —
+ * `defineForgeAction` / `useForgeActions`, plus `useCommandPalette` itself, so a
+ * consumer's tests can reach both halves of one declaration without relying on
+ * Nuxt's auto-imports.
+ *
+ * The Nitro-side counterpart (`ClientCapabilityBridge`) is server-only and
+ * ships through the `./server` subpath instead.
+ */
+export { defineClientCapability, deprecatedClientCapabilityAlias, } from "./composables/defineClientCapability.js";
+export { DEFAULT_FORGE_ACTION_AUDIENCE, defineForgeAction, type UseForgeActionsReturn, useForgeActions, } from "./composables/defineForgeAction.js";
+export { type AnnounceOptions, type AnnounceResult, type CapabilityAnnounceFetcher, type UseAgentCapabilitiesReturn, useAgentCapabilities, } from "./composables/useAgentCapabilities.js";
+export { type CapabilityApprovalDecision, type CapabilityApprovalOptions, type CapabilityApprovalRequest, DEFAULT_APPROVAL_TIMEOUT_MS, type UseCapabilityApprovalReturn, useCapabilityApproval, } from "./composables/useCapabilityApproval.js";
+export { type CapabilityInvokedEvent, type HandleInvocationOptions, type InvocationFailure, type InvocationOutcome, type UseCapabilityInvocationsReturn, useCapabilityInvocations, } from "./composables/useCapabilityInvocations.js";
+export { type UseCommandPaletteReturn, useCommandPalette, } from "./composables/useCommandPalette.js";
+export { type UsePaletteArgStepReturn, usePaletteArgStep, } from "./composables/usePaletteArgStep.js";
+export type { ClientCapabilityAnnouncement, ClientCapabilityContext, ClientCapabilityDescriptor, ClientCapabilityLogger, ClientCapabilityOrigin, DefineClientCapabilityArgs, DefinedClientCapability, } from "./types/client-capability.js";
+export type { PaletteAction, PaletteArgOption, PaletteArgPrompt, } from "./types/command-palette.js";
+export type { DefineForgeActionArgs, ForgeAction, ForgeActionArg, ForgeActionAudience, ForgeActionContext, } from "./types/forge-action.js";

package/dist/runtime/client-capabilities.js

@@ -0,0 +1,25 @@
+export {
+  defineClientCapability,
+  deprecatedClientCapabilityAlias
+} from "./composables/defineClientCapability.js";
+export {
+  DEFAULT_FORGE_ACTION_AUDIENCE,
+  defineForgeAction,
+  useForgeActions
+} from "./composables/defineForgeAction.js";
+export {
+  useAgentCapabilities
+} from "./composables/useAgentCapabilities.js";
+export {
+  DEFAULT_APPROVAL_TIMEOUT_MS,
+  useCapabilityApproval
+} from "./composables/useCapabilityApproval.js";
+export {
+  useCapabilityInvocations
+} from "./composables/useCapabilityInvocations.js";
+export {
+  useCommandPalette
+} from "./composables/useCommandPalette.js";
+export {
+  usePaletteArgStep
+} from "./composables/usePaletteArgStep.js";

package/dist/runtime/components-nuxt-ui/ForgeCapabilityApproval.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/components-nuxt-ui/ForgeCapabilityApproval.vue

@@ -0,0 +1,125 @@
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from "vue";
+import { useCapabilityApproval } from "../composables/useCapabilityApproval";
+const { current, approve, decline } = useCapabilityApproval();
+const title = computed(() => current.value?.displayName || current.value?.name || "");
+const argumentRows = computed(() => {
+  const input = current.value?.input;
+  if (input === void 0 || input === null) return [];
+  if (typeof input === "object" && !Array.isArray(input)) {
+    return Object.entries(input).map(([key, value]) => ({
+      key,
+      value: format(value)
+    }));
+  }
+  return [{ key: "", value: format(input) }];
+});
+function format(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+const now = ref(Date.now());
+let ticker;
+onMounted(() => {
+  ticker = setInterval(() => {
+    now.value = Date.now();
+  }, 500);
+});
+onUnmounted(() => clearInterval(ticker));
+const secondsLeft = computed(() => {
+  const request = current.value;
+  if (request?.expiresAt === void 0) return null;
+  const remaining = Math.min(
+    request.expiresAt - now.value,
+    request.timeoutMs ?? Number.MAX_SAFE_INTEGER
+  );
+  return Math.max(0, Math.ceil(remaining / 1e3));
+});
+function onApprove() {
+  const id = current.value?.id;
+  if (id) approve(id);
+}
+function onDecline() {
+  const id = current.value?.id;
+  if (id) decline(id);
+}
+</script>
+
+<template>
+  <UModal
+    :open="current !== null"
+    title="Allow this action?"
+    :ui="{ content: 'max-w-[480px] w-[95vw]' }"
+    @update:open="(v) => !v && onDecline()"
+  >
+    <template #content>
+      <div class="forge-capability-approval" data-testid="capability-approval" @keydown.esc.prevent="onDecline">
+        <h2 class="forge-capability-approval__heading">Allow this action?</h2>
+
+        <template v-if="current">
+          <p class="forge-capability-approval__intro">
+            The agent wants to run
+            <strong data-testid="capability-approval-title">{{ title }}</strong>
+          </p>
+
+          <code class="forge-capability-approval__name" data-testid="capability-approval-name">{{
+            current.name
+          }}</code>
+
+          <p
+            v-if="current.description"
+            class="forge-capability-approval__description"
+            data-testid="capability-approval-description"
+          >
+            {{ current.description }}
+          </p>
+
+          <div class="forge-capability-approval__args" data-testid="capability-approval-args">
+            <div class="forge-capability-approval__args-label">Arguments</div>
+            <div v-if="argumentRows.length === 0" class="forge-capability-approval__arg-empty">
+              none
+            </div>
+            <div
+              v-for="row in argumentRows"
+              :key="row.key"
+              class="forge-capability-approval__arg"
+            >
+              <span v-if="row.key" class="forge-capability-approval__arg-key">{{ row.key }}</span>
+              <span class="forge-capability-approval__arg-value">{{ row.value }}</span>
+            </div>
+          </div>
+
+          <p
+            v-if="secondsLeft !== null"
+            class="forge-capability-approval__countdown"
+            data-testid="capability-approval-countdown"
+          >
+            Expires in {{ secondsLeft }}s if unanswered.
+          </p>
+        </template>
+
+        <div class="forge-capability-approval__actions">
+          <!-- Decline is focused first on purpose: this dialog can appear while
+               the user is typing, and a stray Enter must not approve an action. -->
+          <UButton
+            label="Decline"
+            color="neutral"
+            variant="subtle"
+            autofocus
+            data-testid="capability-approval-decline"
+            @click="onDecline"
+          />
+          <UButton label="Allow" data-testid="capability-approval-approve" @click="onApprove" />
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>
+
+<style scoped>
+.forge-capability-approval{display:flex;flex-direction:column;font-size:.9rem;gap:10px;padding:16px}.forge-capability-approval__heading{font-size:1rem;font-weight:600;margin:0}.forge-capability-approval__intro{margin:0}.forge-capability-approval__name{align-self:flex-start;background:#f1f5f9;border-radius:4px;color:#475569;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;padding:2px 6px}.forge-capability-approval__description{color:#64748b;margin:0}.forge-capability-approval__args{background:#f8fafc;border:1px solid #e2e8f0;border-radius:6px;display:flex;flex-direction:column;gap:4px;padding:8px 10px}.forge-capability-approval__args-label{color:#94a3b8;font-size:.7rem;font-weight:700;letter-spacing:.08em;text-transform:uppercase}.forge-capability-approval__arg{align-items:baseline;display:flex;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;gap:8px;word-break:break-all}.forge-capability-approval__arg-key{color:#64748b;flex-shrink:0}.forge-capability-approval__arg-key:after{content:":"}.forge-capability-approval__arg-empty{color:#94a3b8;font-size:.8rem}.forge-capability-approval__countdown{color:#94a3b8;font-size:.75rem;margin:0}.forge-capability-approval__actions{display:flex;gap:8px;justify-content:flex-end;margin-top:4px}
+</style>

package/dist/runtime/components-nuxt-ui/ForgeCapabilityApproval.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/components-nuxt-ui/ForgeCommandPalette.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;