@skaile/forge-app-actions 0.2.1 → 0.4.0

package/dist/runtime/server/utils/invoke-action.js

@@ -0,0 +1,32 @@
+import * as z from "zod";
+function isZodError(error) {
+  const candidate = error;
+  return typeof candidate?.name === "string" && /^\$?ZodError$/.test(candidate.name) && Array.isArray(candidate.issues);
+}
+function messageOf(error) {
+  if (error && typeof error === "object") {
+    const { statusMessage, message } = error;
+    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
+function statusOf(error) {
+  const { statusCode } = error ?? {};
+  return typeof statusCode === "number" && Number.isInteger(statusCode) && statusCode >= 400 && statusCode < 600 ? statusCode : void 0;
+}
+export async function invokeAction(action, input, ctx) {
+  try {
+    return { ok: true, result: await action.run(input, ctx) };
+  } catch (error) {
+    if (isZodError(error)) {
+      return {
+        ok: false,
+        status: 400,
+        message: `invalid input: ${z.prettifyError(error)}`,
+        issues: error.issues
+      };
+    }
+    return { ok: false, status: statusOf(error) ?? 500, message: messageOf(error) };
+  }
+}

package/dist/runtime/server/utils/server-actions.d.ts

@@ -0,0 +1,87 @@
+import * as z from "zod";
+/** Who may be offered an action: people/CLIs (`user`) and/or models (`llm`). Exposure control, not authorization. */
+export type ServerActionAudience = "user" | "llm";
+/**
+ * What an action sees. The core fixes no principal shape: `P` is whatever the
+ * app's transport hook resolved, `D` whatever dependencies it injects.
+ */
+export interface ServerActionContext<P = unknown, D = unknown> {
+    /** Canonical capability name `app.<id>`, derived by `run`; never taken from the caller. */
+    name: string;
+    /** What the transport's authorize hook set as `principal` (MCP: `forge-app-actions:mcp:authorize`). */
+    principal: P;
+    /** Host event (under Nitro an `H3Event`); apps pass it on to their server utils. */
+    event: unknown;
+    /** What the transport's authorize hook set as `deps`, e.g. injected service clients. */
+    deps: D;
+}
+/**
+ * The caller-supplied part of a context. `run` derives `name` itself and
+ * ignores one passed here.
+ */
+export type ServerActionScope<P = unknown, D = unknown> = Omit<ServerActionContext<P, D>, "name">;
+export interface DefineServerActionArgs<Id extends string, T extends z.ZodType, P = unknown, D = unknown, R = unknown> {
+    /** Without the `app.` prefix, e.g. `trainings.create`; the name becomes `app.<id>`. An id starting with `app.` throws. */
+    id: Id;
+    /** Description the model reads. Required; empty throws. */
+    description: string;
+    /** Zod schema of the input. Defaults to `z.object({})`. */
+    input?: T;
+    /** Documentation only, as with `defineForgeAction`. Defaults to `"effect"`. */
+    kind?: "effect" | "query";
+    /** Who is offered the action. Defaults to both; an empty array throws. */
+    audience?: readonly ServerActionAudience[];
+    /**
+     * Runs after the input parsed and before the handler, with the canonical
+     * context. Throw to deny (an error with a numeric `statusCode` keeps it);
+     * the handler then does not run. Read the current authority here, not from a
+     * value captured earlier.
+     */
+    authorize?: (input: z.infer<T>, ctx: ServerActionContext<P, D>) => void | Promise<void>;
+    run: (input: z.infer<T>, ctx: ServerActionContext<P, D>) => R;
+}
+export interface ServerAction<Id extends string = string, I = unknown, O = unknown> {
+    id: Id;
+    name: string;
+    description: string;
+    kind: "effect" | "query";
+    readonly audience: readonly ServerActionAudience[];
+    readonly inputZod: z.ZodType;
+    /** `z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })` without `$schema`. */
+    inputSchema: Record<string, unknown>;
+    /** Type-level only: never set at runtime. Read it through `ActionInput` / `ActionOutput`. */
+    readonly types?: {
+        input: I;
+        output: O;
+    };
+    /**
+     * Parses `input` through `inputZod` once (a `ZodError` propagates), awaits
+     * `authorize` (a rejection propagates and nothing ran), then calls the handler.
+     * The context's `name` is always `app.<id>`; a `name` in `ctx` is ignored.
+     */
+    run(input: unknown, ctx: ServerActionScope & {
+        name?: string;
+    }): Promise<unknown>;
+}
+/** The input type an action accepts (`z.input` of its schema). */
+export type ActionInput<A> = A extends ServerAction<string, infer I, unknown> ? I : never;
+/** The output type an action resolves to. */
+export type ActionOutput<A> = A extends ServerAction<string, unknown, infer O> ? O : never;
+export declare function defineServerAction<const Id extends string, T extends z.ZodType = z.ZodObject<Record<string, never>>, P = unknown, D = unknown, R = unknown>(args: DefineServerActionArgs<Id, T, P, D, R>): ServerAction<Id, z.input<T>, Awaited<R>>;
+/**
+ * `defineServerAction` with the app's principal and deps types bound once, so
+ * handlers and `authorize` callbacks are typed without annotating every definition.
+ */
+export declare function createServerActionDefiner<P = unknown, D = unknown>(): <const Id extends string, T extends z.ZodType = z.ZodObject<Record<string, never>>, R = unknown>(args: DefineServerActionArgs<Id, T, P, D, R>) => ServerAction<Id, z.input<T>, Awaited<R>>;
+/** The actions offered to `audience`, in order. Element types are kept, so a typed catalogue stays typed. */
+export declare function forAudience<A extends ServerAction>(actions: readonly A[], audience: ServerActionAudience): A[];
+export declare class ServerActionRegistry {
+    private readonly actions;
+    register(action: ServerAction): void;
+    registerAll(actions: readonly ServerAction[]): void;
+    /** In registration order. */
+    list(): ServerAction[];
+    get(name: string): ServerAction | undefined;
+}
+/** Process-wide singleton, like `capabilityRegistry`. */
+export declare const serverActionRegistry: ServerActionRegistry;

package/dist/runtime/server/utils/server-actions.js

@@ -0,0 +1,75 @@
+import * as z from "zod";
+const AUDIENCES = ["user", "llm"];
+function withoutSchemaKey(schema) {
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+}
+export function defineServerAction(args) {
+  const { id } = args;
+  if (!id || id.trim().length === 0) {
+    throw new Error("defineServerAction: an action needs a non-empty id.");
+  }
+  if (id.startsWith("app.")) {
+    throw new Error(
+      `defineServerAction("${id}"): the id must not carry the \`app.\` prefix \u2014 it is added automatically to derive the action name. Use "${id.slice(4)}".`
+    );
+  }
+  if (!args.description || args.description.trim().length === 0) {
+    throw new Error(
+      `defineServerAction("${id}"): a server action must declare a description \u2014 the model reads it.`
+    );
+  }
+  const requested = args.audience ?? AUDIENCES;
+  if (requested.length === 0 || requested.some((entry) => !AUDIENCES.includes(entry))) {
+    throw new Error(
+      `defineServerAction("${id}"): audience must be a non-empty subset of ${JSON.stringify(AUDIENCES)}.`
+    );
+  }
+  const audience = Object.freeze([...new Set(requested)]);
+  const inputZod = args.input ?? z.object({});
+  const inputSchema = withoutSchemaKey(
+    z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })
+  );
+  const name = `app.${id}`;
+  return {
+    id,
+    name,
+    description: args.description,
+    kind: args.kind ?? "effect",
+    audience,
+    inputZod,
+    inputSchema,
+    async run(input, ctx) {
+      const parsed = inputZod.parse(input);
+      const context = { ...ctx, name };
+      await args.authorize?.(parsed, context);
+      return await args.run(parsed, context);
+    }
+  };
+}
+export function createServerActionDefiner() {
+  return (args) => defineServerAction(args);
+}
+export function forAudience(actions, audience) {
+  return actions.filter((action) => action.audience.includes(audience));
+}
+export class ServerActionRegistry {
+  actions = /* @__PURE__ */ new Map();
+  register(action) {
+    if (this.actions.has(action.name)) {
+      throw new Error(`Server action already registered: ${action.name}`);
+    }
+    this.actions.set(action.name, action);
+  }
+  registerAll(actions) {
+    for (const action of actions) this.register(action);
+  }
+  /** In registration order. */
+  list() {
+    return [...this.actions.values()];
+  }
+  get(name) {
+    return this.actions.get(name);
+  }
+}
+export const serverActionRegistry = new ServerActionRegistry();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-app-actions",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "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",
@@ -23,18 +23,38 @@
       "types": "./dist/runtime/chat/server.d.ts",
       "import": "./dist/runtime/chat/server.js"
     },
+    "./chat/ai-sdk": {
+      "types": "./dist/runtime/chat/ai-sdk.d.ts",
+      "import": "./dist/runtime/chat/ai-sdk.js"
+    },
     "./server": {
       "types": "./dist/runtime/server/index.d.ts",
       "import": "./dist/runtime/server/index.js"
     },
+    "./mcp": {
+      "types": "./dist/runtime/server/mcp/index.d.ts",
+      "import": "./dist/runtime/server/mcp/index.js"
+    },
+    "./http": {
+      "types": "./dist/runtime/server/http/index.d.ts",
+      "import": "./dist/runtime/server/http/index.js"
+    },
+    "./client": {
+      "types": "./dist/runtime/client/index.d.ts",
+      "import": "./dist/runtime/client/index.js"
+    },
     "./types": {
       "types": "./dist/runtime/types/index.d.ts",
       "import": "./dist/runtime/types/index.js"
     }
   },
+  "bin": {
+    "forge-actions": "./bin/forge-actions.mjs"
+  },
   "files": [
     "dist",
     "src/runtime",
+    "bin",
     "README.md"
   ],
   "repository": {
@@ -60,7 +80,8 @@
     "@skaile/forge-chat": "^0.2.0",
     "@skaile/workspaces": "^6.0.0",
     "nuxt": ">=3.0.0",
-    "vue": ">=3.0.0"
+    "vue": ">=3.0.0",
+    "ai": "^7.0.124"
   },
   "peerDependenciesMeta": {
     "@skaile/forge-chat": {
@@ -68,9 +89,13 @@
     },
     "@skaile/workspaces": {
       "optional": true
+    },
+    "ai": {
+      "optional": true
     }
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@nuxt/kit": "^4.0.0",
     "zod": "^4.4.3"
   },
@@ -84,13 +109,19 @@
     "@types/bun": "^1.2.0",
     "@types/node": "^22.0.0",
     "@vitejs/plugin-vue": "^6.0.5",
+    "ai": "^7.0.155",
     "bun-types": "^1.3.11",
+    "h3": "^1.15.11",
     "happy-dom": "^20.9.0",
+    "nitropack": "^2.13.4",
     "nuxt": "^4.0.0",
     "typescript": "^5.0.0",
     "unbuild": "^3.6.0",
     "vitest": "^3.2.0",
     "vue": "^3.5.28",
     "vue-tsc": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/src/runtime/chat/ai-sdk.ts

@@ -0,0 +1,53 @@
+/**
+ * AI SDK projection of server actions (`@skaile/forge-app-actions/chat/ai-sdk`).
+ *
+ * The only module of this package that imports `ai`, which is an optional peer:
+ * hosts that never serve actions to an AI SDK chat never load it.
+ */
+
+import { jsonSchema, type ToolSet, tool } from "ai";
+import { toolNameOf } from "../internal/tool-name";
+import { invokeAction } from "../server/utils/invoke-action";
+import type { ServerAction, ServerActionScope } from "../server/utils/server-actions";
+
+/**
+ * The given server actions as AI SDK tools, named `toolNameOf(action.name)` like
+ * their MCP counterparts, with the action's description and JSON input schema.
+ * Narrow with `forAudience(actions, "llm")` first to honor audiences.
+ *
+ * Every execution goes through `invokeAction` with `scope`: input is parsed and the
+ * action's own `authorize` runs inside `action.run`, once, at call time. Fresh
+ * authority therefore comes from that callback reading the app's current store,
+ * never from `scope`, which is captured when the tool set is built. A failed call
+ * (invalid input, denied, handler error) throws an `Error` carrying the outcome's
+ * message, which the AI SDK reports to the model as a tool error.
+ *
+ * @throws when two different action names map to one tool name.
+ */
+export function serverActionToolSet(
+  actions: readonly ServerAction[],
+  scope: ServerActionScope,
+): ToolSet {
+  const tools: ToolSet = Object.create(null);
+  const owners = new Map<string, string>();
+
+  for (const action of actions) {
+    const toolName = toolNameOf(action.name);
+    const other = owners.get(toolName);
+    if (other !== undefined) {
+      throw new Error(`Tool name collision: ${other} and ${action.name} both map to ${toolName}`);
+    }
+    owners.set(toolName, action.name);
+
+    tools[toolName] = tool({
+      description: action.description,
+      inputSchema: jsonSchema(action.inputSchema as Parameters<typeof jsonSchema>[0]),
+      execute: async (input: unknown) => {
+        const outcome = await invokeAction(action, input, scope);
+        if (!outcome.ok) throw new Error(outcome.message);
+        return outcome.result ?? null;
+      },
+    });
+  }
+  return tools;
+}

package/src/runtime/chat/index.ts

@@ -22,6 +22,7 @@ import {
   useCapabilityApproval,
 } from "../composables/useCapabilityApproval";
 import { describeError } from "../internal/describe-error";
+import { toolNameOf } from "../internal/tool-name";
 import type {
   ClientCapabilityContext,
   ClientCapabilityLogger,
@@ -65,16 +66,7 @@ const defaultLog: ClientCapabilityLogger = {
 
 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);
-}
+export { toolNameOf };
 
 /** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
 function withoutSchemaKey(schema: Record<string, unknown>): ClientToolDecls[string]["inputSchema"] {

package/src/runtime/client/index.ts

@@ -0,0 +1,131 @@
+// client/index.ts
+//
+// Browser/Node client of the HTTP projection (`forgeAppActions.http`). Imports
+// types only: no Vue, H3, AI SDK or server code ends up in a client bundle.
+
+import type { ActionManifestEntry, ActionsManifest } from "../internal/manifest";
+import type { ActionInput, ActionOutput, ServerAction } from "../server/utils/server-actions";
+
+export type { ActionManifestEntry, ActionsManifest };
+
+/**
+ * The transport. It resolves to the already decoded response body and rejects
+ * on a non-2xx status, exactly as Nuxt's `$fetch` does, so `$fetch` can be
+ * injected as is. Declared through a method type so its parameters are compared
+ * bivariantly: `$fetch` accepts a narrower `body` type than `unknown`.
+ */
+export type ActionsFetch = {
+  bivarianceHack(
+    url: string,
+    init: { method: "GET" | "POST"; body?: unknown; headers?: Record<string, string> },
+  ): Promise<unknown>;
+}["bivarianceHack"];
+
+export interface ActionsClientOptions {
+  /** Prefix of `route`, e.g. `https://app.example.com`. Defaults to none (same origin). */
+  baseUrl?: string;
+  /** Where the host mounted the HTTP adapter. Defaults to `/api/actions`. */
+  route?: string;
+  /** Defaults to a `fetch`-based transport; Nuxt callers pass `$fetch`. */
+  fetch?: ActionsFetch;
+  /** Sent with every request (e.g. `Authorization`); a function is read per request. */
+  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+
+/**
+ * What the default transport throws for a non-2xx response. Carries the fields
+ * Nuxt's `$fetch` errors do: `statusCode`, `statusMessage` and `data`, the
+ * decoded response body (for an action failure the H3 error body, whose own
+ * `data.issues` lists schema errors).
+ */
+export class ActionsClientError extends Error {
+  readonly statusCode: number;
+  readonly statusMessage: string;
+  readonly data: unknown;
+
+  constructor(statusCode: number, statusMessage: string, message: string, data: unknown) {
+    super(message);
+    this.name = "ActionsClientError";
+    this.statusCode = statusCode;
+    this.statusMessage = statusMessage;
+    this.data = data;
+  }
+}
+
+function decode(text: string): unknown {
+  if (text === "") return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+const nativeFetch: ActionsFetch = async (url, init) => {
+  const hasBody = init.body !== undefined;
+  const response = await globalThis.fetch(url, {
+    method: init.method,
+    headers: {
+      accept: "application/json",
+      ...(hasBody ? { "content-type": "application/json" } : {}),
+      ...init.headers,
+    },
+    body: hasBody ? JSON.stringify(init.body) : undefined,
+  });
+  const data = decode(await response.text());
+  if (!response.ok) {
+    const body = (typeof data === "object" && data !== null ? data : {}) as {
+      statusMessage?: unknown;
+      message?: unknown;
+    };
+    const statusMessage =
+      typeof body.statusMessage === "string" ? body.statusMessage : response.statusText;
+    const message = typeof body.message === "string" ? body.message : statusMessage;
+    throw new ActionsClientError(response.status, statusMessage, message, data);
+  }
+  return data;
+};
+
+export interface ActionsClient<R extends readonly ServerAction[]> {
+  /**
+   * Calls the action and resolves to its result. A failure rejects with the
+   * transport's error, which carries `statusCode`, `statusMessage` and `data`.
+   */
+  call<K extends R[number]["id"]>(
+    id: K,
+    input: ActionInput<Extract<R[number], { id: K }>>,
+  ): Promise<ActionOutput<Extract<R[number], { id: K }>>>;
+  /** The `user`-audience actions the server offers, with their JSON input schemas. */
+  manifest(): Promise<ActionsManifest<R[number]["id"]>>;
+}
+
+/**
+ * A typed client of the HTTP adapter. `R` is the app's action catalogue
+ * (`typeof SERVERAKTIONEN`), so `call` checks ids and inputs and returns the
+ * handler's output type; import the catalogue as a type only.
+ */
+export function createActionsClient<R extends readonly ServerAction[]>(
+  options: ActionsClientOptions = {},
+): ActionsClient<R> {
+  const base = `${(options.baseUrl ?? "").replace(/\/+$/, "")}/${(options.route ?? "/api/actions").replace(/^\/+|\/+$/g, "")}`;
+  const transport = options.fetch ?? nativeFetch;
+
+  const headersOf = async () => {
+    const headers = options.headers;
+    return typeof headers === "function" ? await headers() : headers;
+  };
+  const send = async (method: "GET" | "POST", url: string, body?: unknown) => {
+    const headers = await headersOf();
+    return transport(url, {
+      method,
+      ...(body === undefined ? {} : { body }),
+      ...(headers ? { headers } : {}),
+    });
+  };
+
+  return {
+    call: (id, input) =>
+      send("POST", `${base}/${encodeURIComponent(id)}`, input ?? {}) as Promise<never>,
+    manifest: () => send("GET", base) as Promise<ActionsManifest<R[number]["id"]>>,
+  };
+}

package/src/runtime/internal/bearer.ts

@@ -0,0 +1,11 @@
+const BEARER = /^Bearer\s+(\S.*)$/i;
+
+/**
+ * The credential of an `Authorization: Bearer …` header value, or `null` when
+ * the header is absent, not a bearer scheme, or empty. Shared by the MCP and
+ * HTTP adapters so both read credentials the same way.
+ */
+export function bearerOf(header: string | string[] | null | undefined): string | null {
+  const value = Array.isArray(header) ? header[0] : header;
+  return value?.match(BEARER)?.[1]?.trim() || null;
+}

package/src/runtime/internal/manifest.ts

@@ -0,0 +1,19 @@
+/**
+ * Wire types of the HTTP action manifest. Types only: the client imports them
+ * without pulling any server code.
+ */
+
+/** One action as `GET <route>` lists it. */
+export interface ActionManifestEntry<Id extends string = string> {
+  id: Id;
+  /** Canonical name `app.<id>`. */
+  name: string;
+  description: string;
+  kind: "effect" | "query";
+  /** JSON Schema (draft-07, input side) of the action's input. */
+  inputSchema: Record<string, unknown>;
+}
+
+export interface ActionsManifest<Id extends string = string> {
+  actions: ActionManifestEntry<Id>[];
+}

package/src/runtime/internal/tool-name.ts

@@ -0,0 +1,10 @@
+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);
+}