@skaile/forge-app-actions 0.3.0 → 0.4.0

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

@@ -1,4 +1,5 @@
 import * as z from "zod";
+const AUDIENCES = ["user", "llm"];
 function withoutSchemaKey(schema) {
   const { $schema: _draft, ...rest } = schema;
   return rest;
@@ -18,23 +19,40 @@ export function defineServerAction(args) {
       `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: `app.${id}`,
+    name,
     description: args.description,
     kind: args.kind ?? "effect",
+    audience,
     inputZod,
     inputSchema,
     async run(input, ctx) {
       const parsed = inputZod.parse(input);
-      return await args.run(parsed, ctx);
+      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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-app-actions",
-  "version": "0.3.0",
+  "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,6 +23,10 @@
       "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"
@@ -31,14 +35,26 @@
       "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": {
@@ -64,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": {
@@ -72,6 +89,9 @@
     },
     "@skaile/workspaces": {
       "optional": true
+    },
+    "ai": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -89,6 +109,7 @@
     "@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",
@@ -99,5 +120,8 @@
     "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/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/server/http/create-handler.ts

@@ -0,0 +1,220 @@
+// server/http/create-handler.ts
+//
+// Projects server actions as a plain JSON-over-HTTP API. Deliberately outside
+// `runtime/server/utils/` (like the MCP adapter) so the Nuxt module's auto-import
+// of that directory never pulls it in, and written against `node:http` only:
+// no H3, Vue or AI SDK import, so Express/Vite hosts can mount it too.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { bearerOf } from "../../internal/bearer";
+import type { ActionManifestEntry, ActionsManifest } from "../../internal/manifest";
+import { invokeAction } from "../utils/invoke-action";
+import { forAudience, type ServerAction } from "../utils/server-actions";
+
+/** What the `authorize` callback receives and may change. */
+export interface ActionsHttpAuthorizeDecision {
+  /** The host event (under Nitro an `H3Event`), or the Node request when the host passed none. */
+  event: unknown;
+  req: IncomingMessage;
+  /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+  bearer: string | null;
+  /** Defaults to `false`; both the manifest and every call answer 401 unless the callback sets it. */
+  allowed: boolean;
+  /** What the actions see as `ctx.principal`. */
+  principal?: unknown;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
+}
+
+export interface ActionsHttpHandlerOptions {
+  /** Narrowed to the `user` audience by the handler itself; the rest answer 404. */
+  actions: readonly ServerAction[];
+  /** Mount path, e.g. `/api/actions`. The manifest is `GET <route>`, a call `POST <route>/<id>`. */
+  route: string;
+  /**
+   * Asked once per request, before any action id is looked up or any body is
+   * read. Set `decision.allowed = true` to let it in. An error thrown here
+   * denies. A host that authenticates by cookie MUST also check the request's
+   * origin here before allowing a `POST`: this adapter performs no CSRF defence.
+   */
+  authorize: (decision: ActionsHttpAuthorizeDecision) => void | Promise<void>;
+}
+
+/** Per-request inputs a host may supply instead of the handler deriving them from `req`. */
+export interface ActionsHttpRequestInput {
+  /** Passed to `authorize` and to the actions as `ctx.event`. Defaults to `req`. */
+  event?: unknown;
+  /** The raw request body, for hosts whose framework already consumed the stream. Called only after authorization. */
+  readBody?: () => Promise<string | undefined>;
+}
+
+/** Bodies above this answer 413. */
+const MAX_BODY_BYTES = 1024 * 1024;
+
+/** The body shape an H3 error serializes to, so Nuxt clients decode it like any other error. */
+function errorBody(statusCode: number, message: string, data?: unknown) {
+  return {
+    statusCode,
+    statusMessage: message,
+    message,
+    ...(data === undefined ? {} : { data }),
+  };
+}
+
+function send(
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = {},
+) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    ...headers,
+  });
+  res.end(JSON.stringify(body) ?? "null");
+}
+
+async function readStream(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer);
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw Object.assign(new Error("body too large"), { tooLarge: true });
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Where `req.url` points relative to `route`: the manifest (`null`), an action
+ * id (already decoded), or outside the API (`undefined`).
+ */
+function actionIdOf(url: string | undefined, route: string): string | null | undefined {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  if (pathname !== route && !pathname.startsWith(`${route}/`)) return undefined;
+  const rest = pathname.slice(route.length).replace(/^\/+/, "");
+  if (rest === "") return null;
+  if (rest.includes("/")) return undefined;
+  try {
+    return decodeURIComponent(rest);
+  } catch {
+    return undefined;
+  }
+}
+
+function manifestOf(actions: readonly ServerAction[]): ActionsManifest {
+  return {
+    actions: actions.map(
+      (action): ActionManifestEntry => ({
+        id: action.id,
+        name: action.name,
+        description: action.description,
+        kind: action.kind,
+        inputSchema: action.inputSchema,
+      }),
+    ),
+  };
+}
+
+/**
+ * A Node `(req, res, input?)` handler for the HTTP projection of server actions.
+ *
+ * - `GET <route>`: `{ actions: [{ id, name, description, kind, inputSchema }] }` of the
+ *   `user`-audience actions, `cache-control: no-store`.
+ * - `POST <route>/<id>`: the JSON body is the action's input; the response is its raw
+ *   result. A failure is an H3-shaped error body (`statusCode`, `statusMessage`, `message`,
+ *   `data.issues` for schema errors) with the outcome's status.
+ *
+ * Both routes deny by default (401) until `authorize` sets `decision.allowed`.
+ * Unknown and non-`user` actions answer 404, malformed JSON 400. Input parsing and
+ * the action's own `authorize` happen inside `action.run`, once, via `invokeAction`.
+ */
+export function createActionsHttpHandler(
+  options: ActionsHttpHandlerOptions,
+): (req: IncomingMessage, res: ServerResponse, input?: ActionsHttpRequestInput) => Promise<void> {
+  const route = `/${options.route.replace(/^\/+|\/+$/g, "")}`;
+  const actions = forAudience(options.actions, "user");
+  const byId = new Map<string, ServerAction>();
+  for (const action of actions) {
+    const other = byId.get(action.id);
+    if (other) throw new Error(`Duplicate action id: ${action.id} (${other.name}, ${action.name})`);
+    byId.set(action.id, action);
+  }
+
+  return async (req, res, input = {}) => {
+    const id = actionIdOf(req.url, route);
+    if (id === undefined) {
+      return send(res, 404, errorBody(404, "Not found"));
+    }
+    const method = req.method ?? "GET";
+    const allowedMethod = id === null ? "GET" : "POST";
+    if (method !== allowedMethod && !(id === null && method === "HEAD")) {
+      return send(
+        res,
+        405,
+        errorBody(405, `Use ${allowedMethod} here`),
+        { allow: allowedMethod },
+      );
+    }
+
+    const event = input.event ?? req;
+    const decision: ActionsHttpAuthorizeDecision = {
+      event,
+      req,
+      bearer: bearerOf(req.headers.authorization),
+      allowed: false,
+      principal: undefined,
+      deps: undefined,
+    };
+    try {
+      await options.authorize(decision);
+    } catch {
+      decision.allowed = false;
+    }
+    if (decision.allowed !== true) {
+      return send(res, 401, errorBody(401, "Invalid or missing credential"), {
+        "www-authenticate": "Bearer",
+      });
+    }
+
+    if (id === null) return send(res, 200, manifestOf(actions));
+
+    const action = byId.get(id);
+    if (!action) return send(res, 404, errorBody(404, `Unknown action: ${id}`));
+
+    let raw: string | undefined;
+    try {
+      raw = await (input.readBody ? input.readBody() : readStream(req));
+    } catch (error) {
+      const tooLarge = (error as { tooLarge?: boolean } | null)?.tooLarge === true;
+      return send(res, tooLarge ? 413 : 400, errorBody(tooLarge ? 413 : 400, "Unreadable body"));
+    }
+    let body: unknown = {};
+    if (raw !== undefined && raw.trim() !== "") {
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        return send(res, 400, errorBody(400, "Malformed JSON body"));
+      }
+    }
+
+    const outcome = await invokeAction(action, body, {
+      principal: decision.principal,
+      event,
+      deps: decision.deps,
+    });
+    if (outcome.ok) return send(res, 200, outcome.result);
+    return send(
+      res,
+      outcome.status,
+      errorBody(
+        outcome.status,
+        outcome.message,
+        outcome.issues === undefined ? undefined : { issues: outcome.issues },
+      ),
+    );
+  };
+}

package/src/runtime/server/http/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Explicit entry point for the HTTP projection of server actions, via the
+ * `./http` subpath. The Nuxt module mounts the routes itself when
+ * `forgeAppActions.http` is set; use these to serve actions from elsewhere.
+ */
+
+export type { ActionManifestEntry, ActionsManifest } from "../../internal/manifest";
+export * from "./create-handler";
+export type { HttpAuthorizeDecision } from "./route";

package/src/runtime/server/http/route.ts

@@ -0,0 +1,54 @@
+// server/http/route.ts
+//
+// The Nitro handler `forgeAppActions.http` mounts. Not importable from app code;
+// apps reach the same projection through `@skaile/forge-app-actions/http`.
+
+import type { H3Event } from "h3";
+import { defineEventHandler, readRawBody } from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions";
+import { createActionsHttpHandler } from "./create-handler";
+
+/** What the `forge-app-actions:http:authorize` hook receives and may change. */
+export interface HttpAuthorizeDecision {
+  event: H3Event;
+  /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+  bearer: string | null;
+  /** Defaults to `false`; manifest and calls answer 401 unless the hook sets it. */
+  allowed: boolean;
+  /** What the actions see as `ctx.principal`. */
+  principal?: unknown;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
+}
+
+/** `GET <route>` (manifest) and `POST <route>/:id` over the registered server actions. */
+export default defineEventHandler(async (event) => {
+  const { http } = useRuntimeConfig(event).forgeAppActions as { http: { route: string } };
+  // The handler writes the response itself; h3 sees `res.writableEnded` and sends nothing more.
+  await createActionsHttpHandler({
+    actions: serverActionRegistry.list(),
+    route: http.route,
+    authorize: async (inner) => {
+      const decision: HttpAuthorizeDecision = {
+        event,
+        bearer: inner.bearer,
+        allowed: false,
+        principal: undefined,
+        deps: undefined,
+      };
+      // The hook's typing comes from the module's type template, which is absent
+      // when this package is type-checked on its own.
+      const { hooks } = useNitroApp() as unknown as {
+        hooks: { callHook(name: string, decision: HttpAuthorizeDecision): Promise<void> };
+      };
+      await hooks.callHook("forge-app-actions:http:authorize", decision);
+      inner.allowed = decision.allowed === true;
+      inner.principal = decision.principal;
+      inner.deps = decision.deps;
+    },
+  })(event.node.req, event.node.res, {
+    event,
+    readBody: () => readRawBody(event, "utf8"),
+  });
+});

package/src/runtime/server/index.ts

@@ -7,3 +7,4 @@
 export * from "./utils/capability-registry";
 export * from "./utils/client-capability-bridge";
 export * from "./utils/server-actions";
+export * from "./utils/invoke-action";