@skaile/forge-app-actions 0.3.0 → 0.4.0

package/src/runtime/server/mcp/create-handler.ts

@@ -8,17 +8,18 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import * as z from "zod";
 import { toolNameOf } from "../../internal/tool-name";
-import type { ServerAction, ServerActionContext } from "../utils/server-actions";
+import { invokeAction } from "../utils/invoke-action";
+import type { ServerAction, ServerActionScope } from "../utils/server-actions";
 
 export { toolNameOf };
 
 export interface ActionsMcpServerOptions {
-  actions: ServerAction[];
+  /** Served as given; narrow them with `forAudience(actions, "llm")` first to honor audiences. */
+  actions: readonly ServerAction[];
   serverInfo: { name: string; version: string };
-  /** `principal` and `event` handed to every action as `ctx`; `name` is set per call. */
-  context: Omit<ServerActionContext, "name">;
+  /** `principal`, `event` and `deps` handed to every action as `ctx`; its `name` is derived per action. */
+  context: ServerActionScope;
 }
 
 type ToolInputSchema = { type: "object"; [key: string]: unknown };
@@ -27,33 +28,11 @@ const text = (value: string) => [{ type: "text" as const, text: value }];
 
 const failure = (message: string) => ({ isError: true as const, content: text(message) });
 
-/**
- * A ZodError by shape, not `instanceof`: the schema belongs to the app, whose
- * zod instance may differ from the one bundled with this package.
- */
-function isZodError(error: unknown): error is z.core.$ZodError {
-  const candidate = error as { name?: unknown; issues?: unknown } | null;
-  return (
-    typeof candidate?.name === "string" &&
-    /^\$?ZodError$/.test(candidate.name) &&
-    Array.isArray(candidate.issues)
-  );
-}
-
-/** The message to show the model: an H3 error carries it in `statusMessage`. */
-function messageOf(error: unknown): string {
-  if (error && typeof error === "object") {
-    const { statusMessage, message } = error as { statusMessage?: unknown; message?: unknown };
-    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
-    if (typeof message === "string") return message;
-  }
-  return String(error);
-}
-
 /**
  * An MCP server whose tools are the given server actions, named
- * `toolNameOf(action.name)`. Every call runs the action with
- * `{ ...context, name: action.name }`.
+ * `toolNameOf(action.name)`. Every call goes through `invokeAction` with `context`;
+ * a failed call (invalid input, denied by the action's `authorize`, handler error)
+ * is an `isError` result carrying the outcome's message, never an HTTP error.
  */
 export function createActionsMcpServer(options: ActionsMcpServerOptions): Server {
   const byTool = new Map<string, ServerAction>();
@@ -81,20 +60,14 @@ export function createActionsMcpServer(options: ActionsMcpServerOptions): Server
   server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
     const action = byTool.get(params.name);
     if (!action) return failure(`unknown tool: ${params.name}`);
-    try {
-      const result = await action.run(params.arguments ?? {}, {
-        ...options.context,
-        name: action.name,
-      });
-      const content = text(JSON.stringify(result) ?? "null");
-      if (result !== null && typeof result === "object" && !Array.isArray(result)) {
-        return { content, structuredContent: result as Record<string, unknown> };
-      }
-      return { content };
-    } catch (error) {
-      if (isZodError(error)) return failure(`invalid input: ${z.prettifyError(error)}`);
-      return failure(messageOf(error));
+    const outcome = await invokeAction(action, params.arguments ?? {}, options.context);
+    if (!outcome.ok) return failure(outcome.message);
+    const { result } = outcome;
+    const content = text(JSON.stringify(result) ?? "null");
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+      return { content, structuredContent: result as Record<string, unknown> };
     }
+    return { content };
   });
 
   return server;

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

@@ -12,7 +12,8 @@ import {
   setResponseStatus,
 } from "h3";
 import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
-import { serverActionRegistry } from "../utils/server-actions";
+import { bearerOf } from "../../internal/bearer";
+import { forAudience, serverActionRegistry } from "../utils/server-actions";
 import { createActionsMcpHttpHandler } from "./create-handler";
 
 /** What the `forge-app-actions:mcp:authorize` hook receives and may change. */
@@ -24,13 +25,8 @@ export interface McpAuthorizeDecision {
   allowed: boolean;
   /** What the actions see as `ctx.principal`. */
   principal?: unknown;
-}
-
-const BEARER = /^Bearer\s+(\S.*)$/i;
-
-function bearerOf(event: H3Event): string | null {
-  const header = getRequestHeader(event, "authorization");
-  return header?.match(BEARER)?.[1]?.trim() || null;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
 }
 
 /** The Streamable HTTP MCP endpoint over the registered server actions. */
@@ -47,9 +43,10 @@ export default defineEventHandler(async (event) => {
 
   const decision: McpAuthorizeDecision = {
     event,
-    bearer: bearerOf(event),
+    bearer: bearerOf(getRequestHeader(event, "authorization")),
     allowed: false,
     principal: undefined,
+    deps: undefined,
   };
   try {
     // The hook's typing comes from the module's type template, which is absent
@@ -86,8 +83,8 @@ export default defineEventHandler(async (event) => {
   };
   // The handler writes the response itself; h3 sees `res.writableEnded` and sends nothing more.
   await createActionsMcpHttpHandler({
-    actions: serverActionRegistry.list(),
+    actions: forAudience(serverActionRegistry.list(), "llm"),
     serverInfo: { name: mcp.name, version: mcp.version },
-    context: { principal: decision.principal, event },
+    context: { principal: decision.principal, event, deps: decision.deps },
   })(event.node.req, event.node.res, parsed);
 });

package/src/runtime/server/utils/invoke-action.ts

@@ -0,0 +1,71 @@
+// server/utils/invoke-action.ts
+//
+// Directly in `runtime/server/utils/` for the same reason as `server-actions.ts`.
+// Transport-neutral: no H3, MCP or AI SDK import, so every projection (MCP, HTTP,
+// chat tools) classifies failures the same way.
+
+import * as z from "zod";
+import type { ServerAction, ServerActionScope } from "./server-actions";
+
+/** What a projection maps to its own error shape: `status` is HTTP-style, whatever the transport. */
+export type ActionOutcome =
+  | { ok: true; result: unknown }
+  | { ok: false; status: number; message: string; issues?: unknown[] };
+
+/**
+ * A ZodError by shape, not `instanceof`: the schema belongs to the app, whose
+ * zod instance may differ from the one bundled with this package.
+ */
+function isZodError(error: unknown): error is z.core.$ZodError {
+  const candidate = error as { name?: unknown; issues?: unknown } | null;
+  return (
+    typeof candidate?.name === "string" &&
+    /^\$?ZodError$/.test(candidate.name) &&
+    Array.isArray(candidate.issues)
+  );
+}
+
+/** The message to show the caller: an H3 error carries it in `statusMessage`. */
+function messageOf(error: unknown): string {
+  if (error && typeof error === "object") {
+    const { statusMessage, message } = error as { statusMessage?: unknown; message?: unknown };
+    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
+
+/** An explicit HTTP-style status on the error (H3 errors carry `statusCode`), if it is a valid one. */
+function statusOf(error: unknown): number | undefined {
+  const { statusCode } = (error ?? {}) as { statusCode?: unknown };
+  return typeof statusCode === "number" && Number.isInteger(statusCode) && statusCode >= 400 && statusCode < 600
+    ? statusCode
+    : undefined;
+}
+
+/**
+ * Runs `action` and classifies the result: schema error → 400 with
+ * `invalid input: …` and its `issues`; an error with a numeric `statusCode` →
+ * that status; anything else → 500. Calls `action.run` only: parsing and the
+ * action's `authorize` happen there, exactly once, so this never reparses or
+ * authorizes a second time.
+ */
+export async function invokeAction(
+  action: ServerAction,
+  input: unknown,
+  ctx: ServerActionScope,
+): Promise<ActionOutcome> {
+  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/src/runtime/server/utils/server-actions.ts

@@ -11,39 +11,84 @@
 
 import * as z from "zod";
 
-export interface ServerActionContext<P = unknown> {
-  /** Capability name as invoked, e.g. `app.trainings.create`. */
+/** Who may be offered an action: people/CLIs (`user`) and/or models (`llm`). Exposure control, not authorization. */
+export type ServerActionAudience = "user" | "llm";
+
+const AUDIENCES: readonly 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 `forge-app-actions:mcp:authorize` hook set as `principal`. */
+  /** 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;
 }
 
-export interface DefineServerActionArgs<T extends z.ZodType, P = unknown> {
+/**
+ * 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: string;
+  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";
-  run: (input: z.infer<T>, ctx: ServerActionContext<P>) => unknown | Promise<unknown>;
+  /** 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: string;
+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>;
-  /** Parses `input` through `inputZod` (a `ZodError` propagates), then calls the handler. */
-  run(input: unknown, ctx: ServerActionContext): Promise<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;
+
 /** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
 function withoutSchemaKey(schema: Record<string, unknown>): Record<string, unknown> {
   const { $schema: _draft, ...rest } = schema;
@@ -51,9 +96,12 @@ function withoutSchemaKey(schema: Record<string, unknown>): Record<string, unkno
 }
 
 export function defineServerAction<
+  const Id extends string,
   T extends z.ZodType = z.ZodObject<Record<string, never>>,
   P = unknown,
->(args: DefineServerActionArgs<T, P>): ServerAction {
+  D = unknown,
+  R = unknown,
+>(args: DefineServerActionArgs<Id, T, P, D, R>): ServerAction<Id, z.input<T>, Awaited<R>> {
   const { id } = args;
   if (!id || id.trim().length === 0) {
     throw new Error("defineServerAction: an action needs a non-empty id.");
@@ -69,26 +117,59 @@ export function defineServerAction<
       `defineServerAction("${id}"): a server action must declare a description — 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: z.ZodType = args.input ?? z.object({});
   const inputSchema = withoutSchemaKey(
     z.toJSONSchema(inputZod, { target: "draft-07", io: "input" }) as Record<string, unknown>,
   );
+  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) as z.infer<T>;
-      return await args.run(parsed, ctx as ServerActionContext<P>);
+      const context = { ...ctx, name } as ServerActionContext<P, D>;
+      await args.authorize?.(parsed, context);
+      return await args.run(parsed, context);
     },
   };
 }
 
+/**
+ * `defineServerAction` with the app's principal and deps types bound once, so
+ * handlers and `authorize` callbacks are typed without annotating every definition.
+ */
+export function createServerActionDefiner<P = unknown, D = unknown>() {
+  return <
+    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>> => defineServerAction<Id, T, P, D, R>(args);
+}
+
+/** The actions offered to `audience`, in order. Element types are kept, so a typed catalogue stays typed. */
+export function forAudience<A extends ServerAction>(
+  actions: readonly A[],
+  audience: ServerActionAudience,
+): A[] {
+  return actions.filter((action) => action.audience.includes(audience));
+}
+
 export class ServerActionRegistry {
   private readonly actions = new Map<string, ServerAction>();
 
@@ -99,7 +180,7 @@ export class ServerActionRegistry {
     this.actions.set(action.name, action);
   }
 
-  registerAll(actions: ServerAction[]): void {
+  registerAll(actions: readonly ServerAction[]): void {
     for (const action of actions) this.register(action);
   }