@skaile/forge-app-actions 0.3.0 → 0.4.0

package/dist/runtime/client/index.js

@@ -0,0 +1,60 @@
+export class ActionsClientError extends Error {
+  statusCode;
+  statusMessage;
+  data;
+  constructor(statusCode, statusMessage, message, data) {
+    super(message);
+    this.name = "ActionsClientError";
+    this.statusCode = statusCode;
+    this.statusMessage = statusMessage;
+    this.data = data;
+  }
+}
+function decode(text) {
+  if (text === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+const nativeFetch = async (url, init) => {
+  const hasBody = init.body !== void 0;
+  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) : void 0
+  });
+  const data = decode(await response.text());
+  if (!response.ok) {
+    const body = typeof data === "object" && data !== null ? data : {};
+    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 function createActionsClient(options = {}) {
+  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, url, body) => {
+    const headers = await headersOf();
+    return transport(url, {
+      method,
+      ...body === void 0 ? {} : { body },
+      ...headers ? { headers } : {}
+    });
+  };
+  return {
+    call: (id, input) => send("POST", `${base}/${encodeURIComponent(id)}`, input ?? {}),
+    manifest: () => send("GET", base)
+  };
+}

package/dist/runtime/internal/bearer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function bearerOf(header: string | string[] | null | undefined): string | null;

package/dist/runtime/internal/bearer.js

@@ -0,0 +1,5 @@
+const BEARER = /^Bearer\s+(\S.*)$/i;
+export function bearerOf(header) {
+  const value = Array.isArray(header) ? header[0] : header;
+  return value?.match(BEARER)?.[1]?.trim() || null;
+}

package/dist/runtime/internal/manifest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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/dist/runtime/server/http/create-handler.d.ts

@@ -0,0 +1,50 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type ServerAction } from "../utils/server-actions.js";
+/** 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>;
+}
+/**
+ * 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 declare function createActionsHttpHandler(options: ActionsHttpHandlerOptions): (req: IncomingMessage, res: ServerResponse, input?: ActionsHttpRequestInput) => Promise<void>;

package/dist/runtime/server/http/create-handler.js

@@ -0,0 +1,135 @@
+import { bearerOf } from "../../internal/bearer.js";
+import { invokeAction } from "../utils/invoke-action.js";
+import { forAudience } from "../utils/server-actions.js";
+const MAX_BODY_BYTES = 1024 * 1024;
+function errorBody(statusCode, message, data) {
+  return {
+    statusCode,
+    statusMessage: message,
+    message,
+    ...data === void 0 ? {} : { data }
+  };
+}
+function send(res, status, body, headers = {}) {
+  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) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    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");
+}
+function actionIdOf(url, route) {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  if (pathname !== route && !pathname.startsWith(`${route}/`)) return void 0;
+  const rest = pathname.slice(route.length).replace(/^\/+/, "");
+  if (rest === "") return null;
+  if (rest.includes("/")) return void 0;
+  try {
+    return decodeURIComponent(rest);
+  } catch {
+    return void 0;
+  }
+}
+function manifestOf(actions) {
+  return {
+    actions: actions.map(
+      (action) => ({
+        id: action.id,
+        name: action.name,
+        description: action.description,
+        kind: action.kind,
+        inputSchema: action.inputSchema
+      })
+    )
+  };
+}
+export function createActionsHttpHandler(options) {
+  const route = `/${options.route.replace(/^\/+|\/+$/g, "")}`;
+  const actions = forAudience(options.actions, "user");
+  const byId = /* @__PURE__ */ new Map();
+  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 === void 0) {
+      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 = {
+      event,
+      req,
+      bearer: bearerOf(req.headers.authorization),
+      allowed: false,
+      principal: void 0,
+      deps: void 0
+    };
+    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;
+    try {
+      raw = await (input.readBody ? input.readBody() : readStream(req));
+    } catch (error) {
+      const tooLarge = error?.tooLarge === true;
+      return send(res, tooLarge ? 413 : 400, errorBody(tooLarge ? 413 : 400, "Unreadable body"));
+    }
+    let body = {};
+    if (raw !== void 0 && 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 === void 0 ? void 0 : { issues: outcome.issues }
+      )
+    );
+  };
+}

package/dist/runtime/server/http/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.js";
+export * from "./create-handler.js";
+export type { HttpAuthorizeDecision } from "./route.js";

package/dist/runtime/server/http/index.js

@@ -0,0 +1 @@
+export * from "./create-handler.js";

package/dist/runtime/server/http/route.d.ts

@@ -0,0 +1,16 @@
+import type { H3Event } from "h3";
+/** 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. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/http/route.js

@@ -0,0 +1,28 @@
+import { defineEventHandler, readRawBody } from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions.js";
+import { createActionsHttpHandler } from "./create-handler.js";
+export default defineEventHandler(async (event) => {
+  const { http } = useRuntimeConfig(event).forgeAppActions;
+  await createActionsHttpHandler({
+    actions: serverActionRegistry.list(),
+    route: http.route,
+    authorize: async (inner) => {
+      const decision = {
+        event,
+        bearer: inner.bearer,
+        allowed: false,
+        principal: void 0,
+        deps: void 0
+      };
+      const { hooks } = useNitroApp();
+      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/dist/runtime/server/index.d.ts

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

package/dist/runtime/server/index.js

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

package/dist/runtime/server/mcp/create-handler.d.ts

@@ -1,21 +1,23 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { toolNameOf } from "../../internal/tool-name.js";
-import type { ServerAction, ServerActionContext } from "../utils/server-actions.js";
+import type { ServerAction, ServerActionScope } from "../utils/server-actions.js";
 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;
 }
 /**
  * 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 declare function createActionsMcpServer(options: ActionsMcpServerOptions): Server;
 export type ActionsMcpHttpHandlerOptions = ActionsMcpServerOptions;

package/dist/runtime/server/mcp/create-handler.js

@@ -1,23 +1,11 @@
 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.js";
+import { invokeAction } from "../utils/invoke-action.js";
 export { toolNameOf };
 const text = (value) => [{ type: "text", text: value }];
 const failure = (message) => ({ isError: true, content: text(message) });
-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);
-}
 export function createActionsMcpServer(options) {
   const byTool = /* @__PURE__ */ new Map();
   for (const action of options.actions) {
@@ -41,20 +29,14 @@ export function createActionsMcpServer(options) {
   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 };
-      }
-      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 };
     }
+    return { content };
   });
   return server;
 }

package/dist/runtime/server/mcp/route.d.ts

@@ -8,6 +8,8 @@ export interface McpAuthorizeDecision {
     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;
 }
 /** The Streamable HTTP MCP endpoint over the registered server actions. */
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<unknown>>;

package/dist/runtime/server/mcp/route.js

@@ -6,13 +6,9 @@ import {
   setResponseStatus
 } from "h3";
 import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
-import { serverActionRegistry } from "../utils/server-actions.js";
+import { bearerOf } from "../../internal/bearer.js";
+import { forAudience, serverActionRegistry } from "../utils/server-actions.js";
 import { createActionsMcpHttpHandler } from "./create-handler.js";
-const BEARER = /^Bearer\s+(\S.*)$/i;
-function bearerOf(event) {
-  const header = getRequestHeader(event, "authorization");
-  return header?.match(BEARER)?.[1]?.trim() || null;
-}
 export default defineEventHandler(async (event) => {
   const reply = (status, body, headers = {}) => {
     setResponseStatus(event, status);
@@ -24,9 +20,10 @@ export default defineEventHandler(async (event) => {
   }
   const decision = {
     event,
-    bearer: bearerOf(event),
+    bearer: bearerOf(getRequestHeader(event, "authorization")),
     allowed: false,
-    principal: void 0
+    principal: void 0,
+    deps: void 0
   };
   try {
     const { hooks } = useNitroApp();
@@ -53,8 +50,8 @@ export default defineEventHandler(async (event) => {
   }
   const { mcp } = useRuntimeConfig(event).forgeAppActions;
   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/dist/runtime/server/utils/invoke-action.d.ts

@@ -0,0 +1,19 @@
+import type { ServerAction, ServerActionScope } from "./server-actions.js";
+/** 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[];
+};
+/**
+ * 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 declare function invokeAction(action: ServerAction, input: unknown, ctx: ServerActionScope): Promise<ActionOutcome>;

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

@@ -1,39 +1,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";
+/**
+ * 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>;
 }
-export declare function defineServerAction<T extends z.ZodType = z.ZodObject<Record<string, never>>, P = unknown>(args: DefineServerActionArgs<T, P>): ServerAction;
+/** 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: ServerAction[]): void;
+    registerAll(actions: readonly ServerAction[]): void;
     /** In registration order. */
     list(): ServerAction[];
     get(name: string): ServerAction | undefined;