@skaile/forge-app-actions 0.1.0 → 0.2.1

package/README.md

@@ -29,7 +29,34 @@ Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional p
 |---|---|
 | `.` | 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.json

@@ -1,7 +1,7 @@
 {
   "name": "@skaile/forge-app-actions",
   "configKey": "forgeAppActions",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

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/composables/useCapabilityInvocations.js

@@ -1,3 +1,4 @@
+import { describeError } from "../internal/describe-error.js";
 import { useAgentCapabilities } from "./useAgentCapabilities.js";
 import { DEFAULT_APPROVAL_TIMEOUT_MS, useCapabilityApproval } from "./useCapabilityApproval.js";
 const defaultLog = {
@@ -10,18 +11,6 @@ function isInvocationEvent(event) {
   const e = event;
   return e.type === "capability_invoked" && typeof e.callId === "string" && e.callId.length > 0 && typeof e.name === "string" && e.name.length > 0;
 }
-function describeError(err) {
-  if (err && typeof err === "object" && Array.isArray(err.issues)) {
-    const issues = err.issues;
-    const lines = issues.map((issue) => {
-      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
-      return path ? `${path}: ${issue.message}` : String(issue.message);
-    });
-    if (lines.length > 0) return lines.join("; ");
-  }
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
 async function postResult(options, callId, result, log) {
   const fetcher = options.fetcher ?? globalThis.fetch ?? void 0;
   if (!fetcher) {

package/dist/runtime/internal/describe-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Turn a thrown value into the single line the agent (or model) will read.
+ *
+ * A zod v4 error carries the useful part in `issues`; `err.message` alone is a
+ * JSON blob. Flatten it to `path: message` pairs so the model can act on it.
+ *
+ * Lives outside `composables/` on purpose: that directory is auto-imported by
+ * the Nuxt module, and this helper is internal.
+ */
+export declare function describeError(err: unknown): string;

package/dist/runtime/internal/describe-error.js

@@ -0,0 +1,12 @@
+export function describeError(err) {
+  if (err && typeof err === "object" && Array.isArray(err.issues)) {
+    const issues = err.issues;
+    const lines = issues.map((issue) => {
+      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+      return path ? `${path}: ${issue.message}` : String(issue.message);
+    });
+    if (lines.length > 0) return lines.join("; ");
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-app-actions",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Browser-declared app actions for Skaile forge apps: defineForgeAction / defineClientCapability, the agent capability bridge, command palette and approval dialog, as a Nuxt module.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -15,6 +15,14 @@
       "types": "./dist/runtime/client-capabilities.d.ts",
       "import": "./dist/runtime/client-capabilities.js"
     },
+    "./chat": {
+      "types": "./dist/runtime/chat/index.d.ts",
+      "import": "./dist/runtime/chat/index.js"
+    },
+    "./chat/server": {
+      "types": "./dist/runtime/chat/server.d.ts",
+      "import": "./dist/runtime/chat/server.js"
+    },
     "./server": {
       "types": "./dist/runtime/server/index.d.ts",
       "import": "./dist/runtime/server/index.js"
@@ -49,11 +57,15 @@
   },
   "peerDependencies": {
     "@nuxt/ui": "^4.11.1",
+    "@skaile/forge-chat": "^0.2.0",
     "@skaile/workspaces": "^6.0.0",
     "nuxt": ">=3.0.0",
     "vue": ">=3.0.0"
   },
   "peerDependenciesMeta": {
+    "@skaile/forge-chat": {
+      "optional": true
+    },
     "@skaile/workspaces": {
       "optional": true
     }
@@ -67,6 +79,7 @@
     "@nuxt/module-builder": "^1.0.0",
     "@nuxt/schema": "^4.0.0",
     "@nuxt/ui": "^4.11.1",
+    "@skaile/forge-chat": "^0.2.0",
     "@skaile/workspaces": "^6.0.0",
     "@types/bun": "^1.2.0",
     "@types/node": "^22.0.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/composables/useCapabilityInvocations.ts

@@ -23,6 +23,7 @@
  * See `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.
  */
 
+import { describeError } from "../internal/describe-error";
 import type {
   ClientCapabilityContext,
   ClientCapabilityLogger,
@@ -171,25 +172,6 @@ function isInvocationEvent(event: unknown): event is CapabilityInvokedEvent {
   );
 }
 
-/**
- * Turn a thrown value into the single line the agent will read.
- *
- * A zod v4 error carries the useful part in `issues`; `err.message` alone is a
- * JSON blob. Flatten it to `path: message` pairs so the model can act on it.
- */
-function describeError(err: unknown): string {
-  if (err && typeof err === "object" && Array.isArray((err as { issues?: unknown }).issues)) {
-    const issues = (err as { issues: Array<{ path?: unknown[]; message?: string }> }).issues;
-    const lines = issues.map((issue) => {
-      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
-      return path ? `${path}: ${issue.message}` : String(issue.message);
-    });
-    if (lines.length > 0) return lines.join("; ");
-  }
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
-
 async function postResult(
   options: HandleInvocationOptions,
   callId: string,

package/src/runtime/internal/describe-error.ts

@@ -0,0 +1,21 @@
+/**
+ * Turn a thrown value into the single line the agent (or model) will read.
+ *
+ * A zod v4 error carries the useful part in `issues`; `err.message` alone is a
+ * JSON blob. Flatten it to `path: message` pairs so the model can act on it.
+ *
+ * Lives outside `composables/` on purpose: that directory is auto-imported by
+ * the Nuxt module, and this helper is internal.
+ */
+export function describeError(err: unknown): string {
+  if (err && typeof err === "object" && Array.isArray((err as { issues?: unknown }).issues)) {
+    const issues = (err as { issues: Array<{ path?: unknown[]; message?: string }> }).issues;
+    const lines = issues.map((issue) => {
+      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+      return path ? `${path}: ${issue.message}` : String(issue.message);
+    });
+    if (lines.length > 0) return lines.join("; ");
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}