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

package/src/runtime/chat/index.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 {
+  DEFAULT_APPROVAL_TIMEOUT_MS,
+  useCapabilityApproval,
+} from "../composables/useCapabilityApproval";
+import { describeError } from "../internal/describe-error";
+import type {
+  ClientCapabilityContext,
+  ClientCapabilityLogger,
+  DefinedClientCapability,
+} from "../types/client-capability";
+import type { ForgeAction } from "../types/forge-action";
+import type { ClientToolDecls, ClientToolHandlers } from "./types";
+
+export type { ClientToolDecls, ClientToolHandlers } from "./types";
+
+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;
+}
+
+const defaultLog: ClientCapabilityLogger = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args),
+};
+
+type ToolHandler = ClientToolHandlers[string];
+
+const TOOL_NAME_MAX = 64;
+
+/**
+ * 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 function toolNameOf(capabilityName: string): string {
+  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
+}
+
+/** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
+function withoutSchemaKey(schema: Record<string, unknown>): ClientToolDecls[string]["inputSchema"] {
+  const { $schema: _draft, ...rest } = schema;
+  return rest as ClientToolDecls[string]["inputSchema"];
+}
+
+export function useChatActions(options: UseChatActionsOptions): UseChatActionsReturn {
+  const log = options.log ?? defaultLog;
+
+  /** The LLM projection of every exposed action, keyed by provider-safe tool name. */
+  function exposed(): Map<string, DefinedClientCapability> {
+    const byTool = new Map<string, DefinedClientCapability>();
+    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(): ClientToolDecls {
+    const decls: ClientToolDecls = {};
+    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: string): ToolHandler | undefined {
+    const capability = exposed().get(toolName);
+    if (!capability) return undefined;
+    const name = capability.name;
+
+    return async (rawInput, { toolCallId, signal }) => {
+      if (signal.aborted) throw new Error("aborted");
+
+      // Validate BEFORE anything else: `inputSchema` on the wire only shapes
+      // what the model tries to send; the live zod schema is the enforcement.
+      const checked = capability.inputZod.safeParse(rawInput ?? {});
+      if (!checked.success) throw new Error(`invalid input: ${describeError(checked.error)}`);
+      const input = checked.data;
+
+      // The approval gate sits after validation: the user sees the arguments
+      // that would actually run.
+      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: ClientCapabilityContext = {
+        sessionKey: options.sessionKey ?? "",
+        callId: toolCallId,
+        name,
+        log,
+      };
+      const result = await capability.handler(input, ctx);
+
+      // Output validation is advisory, as in `useCapabilityInvocations`.
+      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)}`,
+          );
+        }
+      }
+      // forge-chat replays the result to the model on the next request, so it
+      // must be JSON-serialisable; `undefined` is not.
+      return result ?? null;
+    };
+  }
+
+  // A Proxy rather than a snapshot: the session looks handlers up by name at
+  // call time, and `actions()` may have changed since `useChatActions` ran.
+  const handlers = new Proxy({} as ClientToolHandlers, {
+    get: (_target, key) => (typeof key === "string" ? handlerFor(key) : undefined),
+    has: (_target, key) => typeof key === "string" && exposed().has(key),
+    ownKeys: () => [...exposed().keys()],
+    getOwnPropertyDescriptor: (_target, key) => {
+      const handler = typeof key === "string" ? handlerFor(key) : undefined;
+      return handler
+        ? { value: handler, enumerable: true, configurable: true, writable: false }
+        : undefined;
+    },
+  });
+
+  return { descriptors, handlers };
+}

package/src/runtime/chat/server.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 * as z from "zod";
+import { describeError } from "../internal/describe-error";
+import type { ClientToolDecls } from "./types";
+
+/** Same pattern forge-chat's handler enforces; checked here first for a precise message. */
+export const CLIENT_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_.-]{0,63}$/i;
+
+/** Upper bound on a tool description — descriptors come from an untrusted browser. */
+export const CLIENT_TOOL_DESCRIPTION_MAX = 2000;
+
+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()),
+  }),
+);
+
+/**
+ * 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 class ClientToolsBodyError extends Error {
+  readonly statusCode = 400;
+  constructor(message: string) {
+    super(message);
+    this.name = "ClientToolsBodyError";
+  }
+}
+
+/**
+ * Read and validate `body.clientTools`.
+ *
+ * - absent (`undefined`) → `undefined`
+ * - valid → the descriptors, unchanged
+ * - malformed → throws {@link ClientToolsBodyError} (`statusCode` 400,
+ *   message `clientTools: <path>: <issue>; …`)
+ */
+export function clientToolsFromBody(body: Record<string, unknown>): ClientToolDecls | undefined {
+  const raw = body.clientTools;
+  if (raw === undefined) return undefined;
+  const parsed = clientToolsSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ClientToolsBodyError(`clientTools: ${describeError(parsed.error)}`);
+  }
+  // The schema fixes names, description and an object-shaped inputSchema; a
+  // JSON-Schema document itself is the model provider's to judge.
+  return parsed.data as ClientToolDecls;
+}

package/src/runtime/chat/types.ts

@@ -0,0 +1,13 @@
+/**
+ * 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/src/runtime/client-capabilities.ts

@@ -0,0 +1,82 @@
+/**
+ * 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";
+export {
+  DEFAULT_FORGE_ACTION_AUDIENCE,
+  defineForgeAction,
+  type UseForgeActionsReturn,
+  useForgeActions,
+} from "./composables/defineForgeAction";
+export {
+  type AnnounceOptions,
+  type AnnounceResult,
+  type CapabilityAnnounceFetcher,
+  type UseAgentCapabilitiesReturn,
+  useAgentCapabilities,
+} from "./composables/useAgentCapabilities";
+export {
+  type CapabilityApprovalDecision,
+  type CapabilityApprovalOptions,
+  type CapabilityApprovalRequest,
+  DEFAULT_APPROVAL_TIMEOUT_MS,
+  type UseCapabilityApprovalReturn,
+  useCapabilityApproval,
+} from "./composables/useCapabilityApproval";
+export {
+  type CapabilityInvokedEvent,
+  type HandleInvocationOptions,
+  type InvocationFailure,
+  type InvocationOutcome,
+  type UseCapabilityInvocationsReturn,
+  useCapabilityInvocations,
+} from "./composables/useCapabilityInvocations";
+export {
+  type UseCommandPaletteReturn,
+  useCommandPalette,
+} from "./composables/useCommandPalette";
+export {
+  type UsePaletteArgStepReturn,
+  usePaletteArgStep,
+} from "./composables/usePaletteArgStep";
+export type {
+  ClientCapabilityAnnouncement,
+  ClientCapabilityContext,
+  ClientCapabilityDescriptor,
+  ClientCapabilityLogger,
+  ClientCapabilityOrigin,
+  DefineClientCapabilityArgs,
+  DefinedClientCapability,
+} from "./types/client-capability";
+export type {
+  PaletteAction,
+  PaletteArgOption,
+  PaletteArgPrompt,
+} from "./types/command-palette";
+export type {
+  DefineForgeActionArgs,
+  ForgeAction,
+  ForgeActionArg,
+  ForgeActionAudience,
+  ForgeActionContext,
+} from "./types/forge-action";

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

@@ -0,0 +1,240 @@
+<script setup lang="ts">
+/**
+ * ForgeCapabilityApproval — the confirm gate for `requiresApproval`
+ * capabilities, built on UModal + UButton.
+ *
+ * No props, no emits. All state lives in the `useCapabilityApproval` singleton,
+ * which `useCapabilityInvocations().handle()` feeds. Mount once in `app.vue`.
+ *
+ * Closing without choosing (Escape, backdrop) counts as a decline. The safe
+ * default for "should this thing touch your workspace?" is no.
+ */
+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 || "");
+
+/**
+ * The arguments, as rows. An object becomes one row per key; anything else
+ * (a bare string, a number) becomes a single unnamed row. The user is
+ * approving a specific call, so the specific values have to be on screen.
+ */
+const argumentRows = computed<Array<{ key: string; value: string }>>(() => {
+  const input = current.value?.input;
+  if (input === undefined || input === null) return [];
+  if (typeof input === "object" && !Array.isArray(input)) {
+    return Object.entries(input as Record<string, unknown>).map(([key, value]) => ({
+      key,
+      value: format(value),
+    }));
+  }
+  return [{ key: "", value: format(input) }];
+});
+
+function format(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+// ── Countdown ──────────────────────────────────────────────────────────────
+// A gate with an invisible deadline is a trap: the user needs to know the
+// dialog will answer for them if they walk away.
+const now = ref(Date.now());
+// Started on mount: the component renders on the server too, where an
+// interval would never be cleared.
+let ticker: ReturnType<typeof setInterval> | undefined;
+onMounted(() => {
+  ticker = setInterval(() => {
+    now.value = Date.now();
+  }, 500);
+});
+onUnmounted(() => clearInterval(ticker));
+
+const secondsLeft = computed<number | null>(() => {
+  const request = current.value;
+  if (request?.expiresAt === undefined) return null;
+  // Clamped to the declared window: `now` only ticks twice a second and is
+  // seeded at mount, which is earlier than any request it will ever show.
+  const remaining = Math.min(
+    request.expiresAt - now.value,
+    request.timeoutMs ?? Number.MAX_SAFE_INTEGER,
+  );
+  return Math.max(0, Math.ceil(remaining / 1000));
+});
+
+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: boolean) => !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;
+  gap: 10px;
+  padding: 16px;
+  font-size: 0.9rem;
+}
+
+.forge-capability-approval__heading {
+  margin: 0;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.forge-capability-approval__intro {
+  margin: 0;
+}
+
+.forge-capability-approval__name {
+  align-self: flex-start;
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: #f1f5f9;
+  font-size: 0.8rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: #475569;
+}
+
+.forge-capability-approval__description {
+  margin: 0;
+  color: #64748b;
+}
+
+.forge-capability-approval__args {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 8px 10px;
+  border-radius: 6px;
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+}
+
+.forge-capability-approval__args-label {
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: #94a3b8;
+}
+
+.forge-capability-approval__arg {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.8rem;
+  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: 0.8rem;
+}
+
+.forge-capability-approval__countdown {
+  margin: 0;
+  font-size: 0.75rem;
+  color: #94a3b8;
+}
+
+.forge-capability-approval__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 4px;
+}
+</style>