akanjs 3.0.0-alpha.99 → 3.0.0-beta.1

package/client/csrTypes.ts

@@ -3,6 +3,7 @@ import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/sr
 import type { PromiseOrObject } from "akanjs/base";
 import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
+import type { RouteDefinition } from "./route/RouteDefinition";
 import type { RouterInstance } from "./router";
 import { sharedContext } from "./sharedContext";
 import type { ReactFont } from "./types";
@@ -134,6 +135,8 @@ export interface RouteRender {
   resolveHead?: ResolveHead;
   getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
+  /** The `page()` chain behind a page render, when it was declared as one — what a page prompt is read off. */
+  getRouteDefinition?: () => PromiseOrObject<RouteDefinition | undefined>;
 }
 export interface WebAppManifestIcon {
   src: string;

package/client/index.ts

@@ -9,6 +9,7 @@ export * from "./frameConfig";
 export * from "./frameDebug";
 export * from "./locale";
 export * from "./makePageProto";
+export * from "./route";
 export * from "./router";
 export * from "./rscNavigation";
 export * from "./sharedContext";

package/client/route/LayoutDefinition.ts

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import type { LayoutErrorRender, LayoutModule, LayoutNotFoundRender, PageModule } from "../csrTypes";
+import { type RouteArgsShape, RouteDefinition, type RouteKind } from "./RouteDefinition";
+import type { RouteArgOption, RouteArgType, RouteArgValue, RouteSearchType } from "./routeArgs";
+
+export interface LayoutExtra {
+  children: ReactNode;
+}
+
+export class LayoutDefinition<Args extends RouteArgsShape = Record<never, never>> extends RouteDefinition<
+  Args,
+  LayoutExtra
+> {
+  readonly kind: RouteKind = "layout";
+  #notFound?: LayoutNotFoundRender;
+  #error?: LayoutErrorRender;
+
+  param<Name extends string, Type extends RouteArgType>(name: Name, type: Type, option: RouteArgOption = {}) {
+    this.declare({ kind: "param", name, type, list: false, desc: option.desc });
+    return this as unknown as LayoutDefinition<Args & { [Key in Name]: RouteArgValue<Type> }>;
+  }
+
+  search<Name extends string, Type extends RouteSearchType>(name: Name, type: Type, option: RouteArgOption = {}) {
+    const list = Array.isArray(type);
+    this.declare({ kind: "search", name, type: (list ? type[0] : type) as RouteArgType, list, desc: option.desc });
+    return this as unknown as LayoutDefinition<Args & { [Key in Name]?: RouteArgValue<Type> }>;
+  }
+
+  notFound(render: LayoutNotFoundRender) {
+    this.#notFound = render;
+    return this;
+  }
+
+  error(render: LayoutErrorRender) {
+    this.#error = render;
+    return this;
+  }
+
+  protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
+    return {
+      ...module,
+      ...(this.#notFound ? { NotFound: this.#notFound } : {}),
+      ...(this.#error ? { Error: this.#error } : {}),
+    };
+  }
+}

package/client/route/PageDefinition.ts

@@ -0,0 +1,53 @@
+import { type RouteArgsShape, RouteDefinition } from "./RouteDefinition";
+import type {
+  RouteArgOption,
+  RouteArgType,
+  RouteArgValue,
+  RoutePromptArgument,
+  RoutePromptMeta,
+  RouteSearchType,
+} from "./routeArgs";
+
+interface PagePrompt {
+  name: string;
+  description: string;
+}
+
+export class PageDefinition<Args extends RouteArgsShape = Record<never, never>> extends RouteDefinition<Args> {
+  /** MCP names an entry by `^[A-Za-z0-9_-]{1,64}$`; a prompt name outside it never reaches a client's slash menu. */
+  static readonly promptName = /^[A-Za-z0-9_-]{1,64}$/;
+  /** Appended to a list argument's description: the flat string map of `prompts/get` has no other spelling. */
+  static readonly commaSeparated = "Comma-separated list.";
+
+  readonly kind = "page" as const;
+  #prompt?: PagePrompt;
+
+  param<Name extends string, Type extends RouteArgType>(name: Name, type: Type, option: RouteArgOption = {}) {
+    this.declare({ kind: "param", name, type, list: false, desc: option.desc });
+    return this as unknown as PageDefinition<Args & { [Key in Name]: RouteArgValue<Type> }>;
+  }
+
+  search<Name extends string, Type extends RouteSearchType>(name: Name, type: Type, option: RouteArgOption = {}) {
+    const list = Array.isArray(type);
+    this.declare({ kind: "search", name, type: (list ? type[0] : type) as RouteArgType, list, desc: option.desc });
+    return this as unknown as PageDefinition<Args & { [Key in Name]?: RouteArgValue<Type> }>;
+  }
+
+  /** Publishes this screen as an MCP prompt: the description is the whole instruction a model receives. English. */
+  prompt(name: string, description: string) {
+    if (!PageDefinition.promptName.test(name))
+      throw new Error(`[route-convention] prompt name "${name}" must match ${PageDefinition.promptName}`);
+    if (!description.trim()) throw new Error(`[route-convention] prompt "${name}" needs a description`);
+    this.#prompt = { name, description };
+    return this;
+  }
+
+  get promptMeta(): RoutePromptMeta | undefined {
+    if (!this.#prompt) return undefined;
+    const args: RoutePromptArgument[] = this.args.map((arg) => {
+      const description = [arg.desc, arg.list ? PageDefinition.commaSeparated : undefined].filter(Boolean).join(" ");
+      return { name: arg.name, ...(description ? { description } : {}), required: arg.kind === "param" };
+    });
+    return { ...this.#prompt, arguments: args };
+  }
+}

package/client/route/RootLayoutDefinition.ts

@@ -0,0 +1,58 @@
+import type { LayoutModule, PageModule, WebAppManifest } from "../csrTypes";
+import type { ReactFont } from "../types";
+import { LayoutDefinition } from "./LayoutDefinition";
+import type { RouteArgsShape, RouteKind } from "./RouteDefinition";
+
+/** What only the root `_layout.tsx` of an app (or of a basePath) may set — the generated root layout reads it. */
+export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, never>> extends LayoutDefinition<Args> {
+  override readonly kind: RouteKind = "rootLayout";
+  #fonts?: ReactFont[];
+  #manifest?: WebAppManifest;
+  #theme?: string;
+  #reconnect?: boolean;
+  #wsConnect?: boolean;
+  #layoutStyle?: "mobile" | "web";
+  #gaTrackingId?: string;
+
+  fonts(fonts: ReactFont[]) {
+    this.#fonts = fonts;
+    return this;
+  }
+  manifest(manifest: WebAppManifest) {
+    this.#manifest = manifest;
+    return this;
+  }
+  theme(theme: string) {
+    this.#theme = theme;
+    return this;
+  }
+  reconnect(on = true) {
+    this.#reconnect = on;
+    return this;
+  }
+  wsConnect(on = true) {
+    this.#wsConnect = on;
+    return this;
+  }
+  layoutStyle(style: "mobile" | "web") {
+    this.#layoutStyle = style;
+    return this;
+  }
+  gaTrackingId(id: string) {
+    this.#gaTrackingId = id;
+    return this;
+  }
+
+  protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
+    return {
+      ...super.extendModule(module),
+      ...(this.#fonts ? { fonts: this.#fonts } : {}),
+      ...(this.#manifest ? { manifest: this.#manifest } : {}),
+      ...(this.#theme !== undefined ? { theme: this.#theme } : {}),
+      ...(this.#reconnect !== undefined ? { reconnect: this.#reconnect } : {}),
+      ...(this.#wsConnect !== undefined ? { wsConnect: this.#wsConnect } : {}),
+      ...(this.#layoutStyle ? { layoutStyle: this.#layoutStyle } : {}),
+      ...(this.#gaTrackingId ? { gaTrackingId: this.#gaTrackingId } : {}),
+    };
+  }
+}

package/client/route/RouteDefinition.ts

@@ -0,0 +1,204 @@
+import {
+  type Cls,
+  type EnumInstance,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+  type PromiseOrObject,
+} from "akanjs/base";
+import { parseAkanI18nEnv } from "akanjs/common";
+import { deserialize } from "akanjs/constant";
+import type { ReactNode } from "react";
+import type { AkanMetadata, Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
+import { AkanNotFoundError } from "../router";
+import { RouteArgError, type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs";
+
+export type RouteArgsShape = Record<string, unknown>;
+export type RouteKind = "page" | "layout" | "rootLayout";
+/** Interned: a definition built inside the pages bundle must be recognised by a loader bundled apart from it. */
+export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
+
+type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
+type MetadataStage<Args> = AkanMetadata | ((args: Args) => PromiseOrObject<AkanMetadata | null | undefined>);
+
+interface RouteRenderProps {
+  params: Record<string, string>;
+  searchParams?: Record<string, string | string[]>;
+  children?: ReactNode;
+}
+
+export interface RouteArgResolveOption {
+  /** A prompt's arguments are strings a person typed: a list is comma-separated and a bad value is refused. */
+  strict?: boolean;
+}
+
+/**
+ * What a route file declares in place of named exports. The chain is the only surface — the module exports the
+ * finished definition and the loader turns it back into the module shape every renderer already reads.
+ */
+export abstract class RouteDefinition<
+  Args extends RouteArgsShape = Record<never, never>,
+  Extra extends object = Record<never, never>,
+> {
+  readonly [routeDefinitionMarker] = true;
+  abstract readonly kind: RouteKind;
+  readonly args: RouteArgInfo[] = [];
+  #config?: PageConfig;
+
+  #head?: HeadStage<never>;
+  #metadata?: MetadataStage<never>;
+  #loading?: (args: never) => PromiseOrObject<ReactNode>;
+  #render?: (args: never) => PromiseOrObject<ReactNode>;
+
+  config(config: PageConfig) {
+    this.#config = config;
+    return this;
+  }
+  head(head: HeadStage<RouteBaseArgs & Args>) {
+    this.#head = head as HeadStage<never>;
+    return this;
+  }
+  metadata(metadata: MetadataStage<RouteBaseArgs & Args>) {
+    this.#metadata = metadata as MetadataStage<never>;
+    return this;
+  }
+  loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
+    this.#loading = render as (args: never) => PromiseOrObject<ReactNode>;
+    return this;
+  }
+  render(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
+    this.#render = render as (args: never) => PromiseOrObject<ReactNode>;
+    return this;
+  }
+
+  get pageConfig() {
+    return this.#config;
+  }
+
+  protected declare(arg: RouteArgInfo) {
+    if (arg.name === "lang")
+      throw new Error(`[route-convention] ${this.kind}() receives "lang" on every route; it is never declared`);
+    if (this.args.some((existing) => existing.name === arg.name))
+      throw new Error(`[route-convention] ${this.kind}() declares "${arg.name}" twice`);
+    this.args.push(arg);
+  }
+
+  /**
+   * Typed values out of the URL halves the router matched. A path value the declared type refuses is a URL that
+   * matched the pattern and nothing under it, so a page answers not-found; a search value that fails is dropped
+   * the way an absent one is. Under `strict` both are refused by name, which is what a prompt caller can act on.
+   */
+  resolveArgs(input: RouteArgInput, { strict = false }: RouteArgResolveOption = {}): Record<string, unknown> {
+    const resolved: Record<string, unknown> = {};
+    for (const arg of this.args) {
+      const raw = arg.kind === "param" ? input.params[arg.name] : input.searchParams[arg.name];
+      if (raw === undefined || raw === "") {
+        if (arg.kind === "param") throw new RouteArgError(arg, `Missing required argument "${arg.name}".`);
+        continue;
+      }
+      const value = RouteDefinition.#lift(arg, raw, strict);
+      try {
+        resolved[arg.name] = RouteDefinition.#parse(arg, value);
+      } catch {
+        if (strict) throw new RouteArgError(arg, RouteDefinition.#invalidMessage(arg));
+        if (arg.kind === "param") throw new AkanNotFoundError();
+      }
+    }
+    return resolved;
+  }
+
+  /**
+   * The `[x]` segments of the file's path against the `.param()` stages. A page must name every segment it sits
+   * under, so nothing reaches its body undeclared; a layout may name a subset, since most read none of them.
+   */
+  assertPattern(pattern: string, key: string) {
+    const inPath = pattern
+      .split("/")
+      .filter((part) => part.startsWith(":"))
+      .map((part) => part.slice(1))
+      .filter((name) => name !== "lang");
+    const declared = this.args.filter((arg) => arg.kind === "param").map((arg) => arg.name);
+    const unknown = declared.find((name) => !inPath.includes(name));
+    if (unknown)
+      throw new Error(
+        `[route-convention] ${key} declares .param("${unknown}") but no [${unknown}] segment is in its path`,
+      );
+    const undeclared = inPath.find((name) => !declared.includes(name));
+    if (this.kind === "page" && undeclared)
+      throw new Error(
+        `[route-convention] ${key} sits under [${undeclared}] but declares no .param("${undeclared}") — a page reads only what it declares`,
+      );
+  }
+
+  /** The module shape every route loader reads, so a chain and a legacy module walk one path from here on. */
+  toRouteModule(): PageModule & LayoutModule {
+    const render = this.#render;
+    if (!render)
+      throw new Error(`[route-convention] a ${this.kind}() chain ends with .render(), and this one has none`);
+    const head = this.#head;
+    const metadata = this.#metadata;
+    const loading = this.#loading;
+    const module: PageModule & LayoutModule = {
+      default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
+      ...(this.#config ? { pageConfig: this.#config } : {}),
+      ...(head === undefined
+        ? {}
+        : typeof head === "function"
+          ? { generateHead: async (props: RouteRenderProps) => await head(this.#argsOf(props) as never) }
+          : { head }),
+      ...(metadata === undefined
+        ? {}
+        : typeof metadata === "function"
+          ? { generateMetadata: async (props: RouteRenderProps) => await metadata(this.#argsOf(props) as never) }
+          : { metadata }),
+      ...(loading
+        ? {
+            Loading: ((props: RouteRenderProps) =>
+              loading(this.#argsOf({ ...props, searchParams: {} }) as never)) as never,
+          }
+        : {}),
+    };
+    return this.extendModule(module);
+  }
+
+  protected extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
+    return module;
+  }
+
+  #argsOf(props: RouteRenderProps): RouteBaseArgs & Args & Extra {
+    const { lang = parseAkanI18nEnv().defaultLocale } = props.params;
+    const resolved = this.resolveArgs({ params: props.params, searchParams: props.searchParams ?? {} });
+    const args = { lang, ...resolved };
+    return (this.kind === "page" ? args : { ...args, children: props.children }) as RouteBaseArgs & Args & Extra;
+  }
+
+  /**
+   * A single value where a list was declared is a one-item list: the URL spells `?tags=a` for one tag. A prompt
+   * argument is one string whatever it holds, so under `strict` a list is read comma-separated.
+   */
+  static #lift(arg: RouteArgInfo, raw: string | string[], strict: boolean): unknown {
+    if (!arg.list) return Array.isArray(raw) ? raw[0] : raw;
+    if (Array.isArray(raw)) return raw;
+    return strict
+      ? raw
+          .split(",")
+          .map((item) => item.trim())
+          .filter(Boolean)
+      : [raw];
+  }
+
+  static #parse(arg: RouteArgInfo, value: unknown): unknown {
+    const enumRef = isEnum(arg.type as Cls) ? (arg.type as EnumInstance) : undefined;
+    const scalar = (enumRef ? enumRef.type : arg.type) as typeof PrimitiveScalar;
+    return deserialize(scalar as never, arg.list ? 1 : 0, value, { key: arg.name, enum: enumRef });
+  }
+
+  static #invalidMessage(arg: RouteArgInfo): string {
+    if (isEnum(arg.type as Cls))
+      return `Invalid argument "${arg.name}": expected one of ${(arg.type as EnumInstance).values.join(", ")}.`;
+    const name = PrimitiveRegistry.has(arg.type as Cls)
+      ? PrimitiveRegistry.getName(arg.type as typeof PrimitiveScalar)
+      : "a value";
+    return `Invalid argument "${arg.name}": expected ${name}${arg.list ? "[]" : ""}.`;
+  }
+}

package/client/route/index.ts

@@ -0,0 +1,7 @@
+export * from "./LayoutDefinition";
+export * from "./PageDefinition";
+export * from "./RootLayoutDefinition";
+export * from "./RouteDefinition";
+export * from "./resolveRouteModule";
+export * from "./routeArgs";
+export * from "./routeBuilders";

package/client/route/resolveRouteModule.ts

@@ -0,0 +1,46 @@
+import type { RouteModule } from "../csrTypes";
+import { type RouteDefinition, routeDefinitionMarker } from "./RouteDefinition";
+
+export interface ResolveRouteModuleOption {
+  /** The file kind the route convention derived from the path, so `page()` in a `_layout.tsx` is caught here. */
+  kind?: "page" | "layout" | "overrides";
+  /** The matched route pattern (`/:lang/project/:projectId`), checked against the chain's `.param()` stages. */
+  pattern?: string;
+}
+
+/** What a route file's module may be: the named-export shape, or one default export holding a chain. */
+export type RouteModuleSource = RouteModule | { default: RouteDefinition };
+
+export interface ResolvedRouteModule {
+  module: RouteModule;
+  /** Present when the module's default export was a `page()` / `layout()` / `rootLayout()` chain. */
+  definition?: RouteDefinition;
+}
+
+export const isRouteDefinition = (value: unknown): value is RouteDefinition =>
+  typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[routeDefinitionMarker] === true;
+
+/**
+ * Every loader — the RSC worker, the CSR boot, the generated root layout — reads route modules by their named
+ * exports. A chain module has one export, so it is unfolded into that shape here and nothing downstream learns
+ * which of the two it was reading; a legacy module passes through untouched.
+ */
+export const resolveRouteModule = (
+  mod: RouteModuleSource,
+  key: string,
+  { kind, pattern }: ResolveRouteModuleOption = {},
+): ResolvedRouteModule => {
+  const definition: unknown = mod.default;
+  if (!isRouteDefinition(definition)) return { module: mod as RouteModule };
+  const named = Object.keys(mod).filter((name) => name !== "default");
+  if (named.length)
+    throw new Error(
+      `[route-convention] ${key} exports ${named.join(", ")} beside its ${definition.kind}() chain — every route setting is a stage of the chain`,
+    );
+  if (kind === "page" && definition.kind !== "page")
+    throw new Error(`[route-convention] ${key} is a page file but exports ${definition.kind}()`);
+  if (kind === "layout" && definition.kind === "page")
+    throw new Error(`[route-convention] ${key} is a layout file but exports page()`);
+  if (pattern) definition.assertPattern(pattern, key);
+  return { module: definition.toRouteModule(), definition };
+};

package/client/route/routeArgs.ts

@@ -0,0 +1,51 @@
+import type { FieldToValue, ParamFieldType } from "akanjs/constant";
+
+/** A scalar (`ID`, `String`, `Int`, `Float`, `Boolean`, `Date`) or an `enumOf` class — what a URL segment can carry. */
+export type RouteArgType = ParamFieldType;
+/** A search argument may also be a flat list, written `[String]`; the URL repeats the key or comma-separates it. */
+export type RouteSearchType = RouteArgType | [RouteArgType];
+export type RouteArgValue<T> = T extends [infer Item] ? FieldToValue<Item>[] : FieldToValue<T>;
+
+export interface RouteArgOption {
+  /** What the value is, read by the person filling the MCP prompt form in — so English. */
+  desc?: string;
+}
+
+/** Every route sits under `/:lang`, so the locale segment reaches each stage as `lang` with no `.param()` for it. */
+export interface RouteBaseArgs {
+  lang: string;
+}
+
+export interface RouteArgInfo {
+  kind: "param" | "search";
+  name: string;
+  type: RouteArgType;
+  list: boolean;
+  desc?: string;
+}
+
+export interface RouteArgInput {
+  params: Record<string, string>;
+  searchParams: Record<string, string | string[]>;
+}
+
+/** What the page prompt catalogue publishes for one declared argument. */
+export interface RoutePromptArgument {
+  name: string;
+  description?: string;
+  required: boolean;
+}
+
+export interface RoutePromptMeta {
+  name: string;
+  description: string;
+  arguments: RoutePromptArgument[];
+}
+
+export class RouteArgError extends Error {
+  readonly arg: RouteArgInfo;
+  constructor(arg: RouteArgInfo, message: string) {
+    super(message);
+    this.arg = arg;
+  }
+}

package/client/route/routeBuilders.ts

@@ -0,0 +1,10 @@
+import { LayoutDefinition } from "./LayoutDefinition";
+import { PageDefinition } from "./PageDefinition";
+import { RootLayoutDefinition } from "./RootLayoutDefinition";
+
+/** `export default page().param(…).search(…).config(…).prompt(…).render(async (args) => …)` in a route page file. */
+export const page = () => new PageDefinition();
+/** `export default layout().render(({ children }) => …)` in a `_layout.tsx`. */
+export const layout = () => new LayoutDefinition();
+/** The app's (or a basePath's) root `_layout.tsx`: `layout()` plus fonts, manifest, theme and the socket switches. */
+export const rootLayout = () => new RootLayoutDefinition();

package/common/TrustedProxy.ts

@@ -51,9 +51,14 @@ export class TrustedProxy {
   /**
    * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
    * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
+   *
+   * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
+   * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
+   * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
+   * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
    */
   static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
-    if (TrustedProxy.isTrusted(peerAddress)) {
+    if (peerAddress === null || TrustedProxy.isTrusted(peerAddress)) {
       const realIp = headers.get("x-real-ip")?.trim();
       if (realIp) return normalizeIpAddress(realIp);
       const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
@@ -62,6 +67,23 @@ export class TrustedProxy {
     return peerAddress ? normalizeIpAddress(peerAddress) : null;
   }
 
+  /**
+   * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
+   * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
+   * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
+   * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
+   */
+  static isPrivateAddress(address: string): boolean {
+    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    if (!bytes) return true;
+    if (TrustedProxy.#isLocalRange(bytes)) return true;
+    if (bytes.length === 4) {
+      const [a = 0, b = 0] = bytes;
+      return a === 0 || (a === 100 && b >= 64 && b <= 127) || a >= 224;
+    }
+    return bytes.every((byte) => byte === 0) || bytes[0] === 0xff;
+  }
+
   /** `10/8`, `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, and their IPv6 counterparts `::1`, `fc00::/7`, `fe80::/10`. */
   static #isLocalRange(bytes: Uint8Array): boolean {
     if (bytes.length === 4) {

package/common/index.ts

@@ -71,7 +71,6 @@ export {
   type McpExposureOption,
   mcpBaseVerbOf,
   mcpHintsOf,
-  mcpPromptRefusalOf,
   mcpRefusalOf,
 } from "./mcpExposure";
 export { mergeVersion } from "./mergeVersion";

package/common/mcpExposure.ts

@@ -17,6 +17,8 @@ export interface McpExposureEndpoint {
   guards?: string[];
   fileUpload?: boolean;
   mcp?: boolean;
+  /** `false` when a guard declares `static agents = false`: no model may ever pass, whatever else the guards say. */
+  agents?: boolean;
 }
 
 export interface McpExposureOption {
@@ -68,12 +70,14 @@ export const mcpRefusalOf = (
   if (endpoint.mcp === false)
     return "it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.";
 
+  if (endpoint.agents === false)
+    return `its guards (${(endpoint.guards ?? []).join(", ")}) admit no agent — an act reserved for a person, so it is off the agent shelf. HTTP still serves it.`;
+
   if (!endpoint.guards?.length)
     return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
 
   if (key === `light${capitalize(refName)}`)
     return `it reads the same document as \`${refName}\` in a smaller shape — call \`${refName}\` instead.`;
-  if (endpoint.type === "prompt") return mcpPromptRefusalOf(endpoint);
   if (endpoint.type === "pubsub" || endpoint.type === "message")
     return `\`${endpoint.type}\` rides the websocket, and its internal arguments read a socket an MCP request does not have.`;
   if (readOnly && endpoint.type !== "query")
@@ -91,24 +95,3 @@ export const mcpRefusalOf = (
     return `its required argument \`${opaque.name}\` is typed \`Any\`, which is left out of the published schema — expose a named filter slice instead.`;
   return null;
 };
-
-/**
- * A prompt is a read exposed on the same terms as a query, so every rejection here is one thing: an argument
- * `prompts/get` cannot carry. Its `arguments` is a flat string map — one string per name, and no schema beside it
- * — which rules out the argument *kinds* the builder already refuses and, just as surely, two argument *types* it
- * accepts. A tool escapes both because it publishes a real JSON Schema.
- */
-export const mcpPromptRefusalOf = (endpoint: McpExposureEndpoint): string | null => {
-  const carried = endpoint.args.find((arg) => arg.type === "body" || arg.type === "msg" || arg.type === "room");
-  if (carried)
-    return `a prompt's arguments travel as a flat string map, so its \`${carried.type}\` argument \`${carried.name}\` cannot be carried.`;
-
-  const list = endpoint.args.find((arg) => arg.arrDepth);
-  if (list)
-    return `a prompt argument is one string, so its list argument \`${list.name}\` could never carry more than one value.`;
-
-  const opaque = endpoint.args.find((arg) => !isMcpDescribableArg(arg));
-  if (opaque)
-    return `its argument \`${opaque.name}\` is typed \`Any\`, and a prompt has no schema in which to describe one.`;
-  return null;
-};