akanjs 3.1.0-rc.21 → 3.1.0-rc.22

package/common/index.ts

@@ -1,12 +1,6 @@
 export { applyMixins, getAllPropertyDescriptors } from "./applyMixins";
-export {
-  authTokenKey,
-  cookieHeaderHasAuthToken,
-  isAuthTokenKey,
-  isOwnAuthToken,
-  legacyAuthTokenKey,
-  readAuthToken,
-} from "./authToken";
+export { cookieHeaderHasAuthToken, isAuthTokenKey, legacyAuthTokenKey } from "./authCookie";
+export { authTokenKey, isOwnAuthToken, readAuthToken } from "./authToken";
 export { Backoff, type BackoffPolicy } from "./backoff";
 export { bearerTokenOf } from "./bearerTokenOf";
 export { CodeAgentClient, type CodeAgentTransport } from "./CodeAgentClient";

package/common/routeConvention.ts

@@ -16,6 +16,7 @@ export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "head",
   "generateHead",
   "Loading",
+  "guard",
 ]);
 export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
 export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
@@ -27,6 +28,7 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "wsConnect",
   "layoutStyle",
   "viewport",
+  "McpAppRoot",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(

package/constant/inputParser.ts

@@ -45,12 +45,12 @@ export class InputParser {
   ]);
 
   static parse(argRef: Cls, arrDepth: number, value: unknown, option: ParseOption) {
-    if (PrimitiveRegistry.has(argRef)) return deserialize(argRef, arrDepth, value, option);
     const { key, nullable = false } = option;
     if (value === null || value === undefined) {
       if (nullable) return null;
       throw new InvalidInputError(key, null);
     }
+    if (PrimitiveRegistry.has(argRef)) return deserialize(argRef, arrDepth, value, option);
     return InputParser.#walk(value, arrDepth, key, (item, path) => InputParser.#value(argRef, item, path));
   }
 

package/dictionary/base.dictionary.ts

@@ -65,6 +65,14 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "{endpoint} is closed: the slice's guards name none that allows it.",
       "{endpoint}이(가) 닫혀 있습니다. 슬라이스 guards에 이 동작을 허용하는 guard를 지정해야 합니다.",
     ],
+    mutationInApp: [
+      "The {app} app called {endpoint} while it loads, and an app may load with queries only.",
+      "{app} 앱이 불러오는 중에 {endpoint}을(를) 호출했습니다. 앱은 쿼리로만 불러올 수 있습니다.",
+    ],
+    readOnlyDeployment: [
+      "This server is read-only, so {endpoint} cannot run here.",
+      "읽기 전용 서버라 {endpoint}을(를) 실행할 수 없습니다.",
+    ],
   })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],

package/fetch/appScope.ts

@@ -0,0 +1,54 @@
+interface AppScopeStorage {
+  run<T>(app: string, load: () => T): T;
+  getStore(): string | undefined;
+}
+
+declare global {
+  var __AKAN_APP_SCOPE__: AppScopeStorage | undefined;
+}
+
+/**
+ * Marks the run of a page's `.app()` load, which may only query: an MCP view replays those queries from the tool
+ * result's snapshot, so a write in the load would run once for the tool call and again when the view draws.
+ */
+export class AppScope {
+  static readonly #storage: AppScopeStorage = AppScope.#shared();
+
+  static run<T>(app: string, load: () => T): T {
+    return AppScope.#storage.run(app, load);
+  }
+
+  /** The app whose load is running here, if any. */
+  static current(): string | undefined {
+    return AppScope.#storage.getStore();
+  }
+
+  static #shared(): AppScopeStorage {
+    globalThis.__AKAN_APP_SCOPE__ ??= AppScope.#createStorage();
+    return globalThis.__AKAN_APP_SCOPE__;
+  }
+
+  static #createStorage(): AppScopeStorage {
+    if (typeof window === "undefined") {
+      try {
+        const { AsyncLocalStorage } = require("node:async_hooks") as typeof import("node:async_hooks");
+        const als = new AsyncLocalStorage<string>();
+        return { run: (app, load) => als.run(app, load), getStore: () => als.getStore() };
+      } catch {}
+    }
+    
+    let current: string | undefined;
+    return {
+      run(app, load) {
+        const previous = current;
+        current = app;
+        try {
+          return load();
+        } finally {
+          current = previous;
+        }
+      },
+      getStore: () => current,
+    };
+  }
+}

package/fetch/client/fetchClient.ts

@@ -20,6 +20,7 @@ import type {
   ServiceSignal,
 } from "akanjs/signal";
 import { agentTurnConstant } from "../agentTurn";
+import { AppScope } from "../appScope";
 import type { ClientSignal, FetchClientType, FetchSignalInput, MergeAllFetchTypes, SliceMeta } from "../fetchType";
 import {
   claimRequestQuery,
@@ -30,7 +31,7 @@ import {
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types";
 import { FetchHandle } from "./fetchHandle";
 import { HttpClient } from "./httpClient";
-import type { ErrorConstructor, RestoredError } from "./remoteError";
+import { type ErrorConstructor, type RestoredError, restoreRemoteError } from "./remoteError";
 import { SliceInitHandle } from "./sliceInitHandle";
 import { expandQueryArgs, normalizeQueryArgs } from "./sliceQueryArgs";
 import { WsClient, type WsClientOptions } from "./wsClient";
@@ -440,8 +441,8 @@ export class FetchClient {
           const payload = claim.owned ? response : FetchClient.#deepCopy(response);
           return parseReturn(payload, { crystalize: option?.crystalize ?? true });
         };
-      case "mutation":
-        return async (...argData: unknown[]) => {
+      case "mutation": {
+        const send = async (...argData: unknown[]) => {
           const { option, argMap, url } = requestOf(argData);
           const bridge = this.#bridgeOf(option?.origin);
           if (bridge)
@@ -458,6 +459,12 @@ export class FetchClient {
           });
           return parseReturn(response, { crystalize: option?.crystalize ?? true });
         };
+        
+        return (...argData: unknown[]) => {
+          this.#refuseInApp(key);
+          return send(...argData);
+        };
+      }
       default:
         throw new Error(`Unsupported endpoint type: ${endpoint.type}`);
     }
@@ -476,6 +483,7 @@ export class FetchClient {
           const parseReturn = this.#makeReturnParser(endpoint.returns);
           const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return (...argData: unknown[]) => {
+            this.#refuseInApp(key);
             
             if (FetchClient.bridged) return () => undefined;
             const args = argData.slice(0, roomArgLength);
@@ -507,6 +515,7 @@ export class FetchClient {
           const msgArgLength = msgArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
           return (...argData: unknown[]) => {
+            this.#refuseInApp(key);
             if (FetchClient.bridged) return;
             const args = argData.slice(0, msgArgLength);
             const fetchPolicy = argData[msgArgLength] as FetchPolicy | undefined;
@@ -536,6 +545,12 @@ export class FetchClient {
     }
   }
   
+  #refuseInApp(endpoint: string) {
+    const app = AppScope.current();
+    if (app)
+      throw restoreRemoteError({ error: "base.error.mutationInApp", data: { app, endpoint } }, 400, this.ErrorCls);
+  }
+  
   #bridgeOf(origin?: string) {
     return origin || this.#foreign ? null : FetchClient.bridge;
   }
@@ -707,32 +722,34 @@ export class FetchClient {
       );
     }
 
-    this.#setHandlerFactory(
-      names.addModelFiles,
-      () =>
-        (async (fileList: FileList | File[], parentId?: string, option?: FetchPolicy) => {
-          
-          if (this.#bridgeOf())
-            throw new Error("File upload is unavailable in an MCP App view: its host relays tool calls, not files.");
-          const cap = resolveFileUploadCapability(this.serializedSignal);
-          const endpoint = cap ? this.serializedSignal[cap.refName]?.endpoint[cap.endpointKey] : undefined;
-          if (!cap || !endpoint)
-            throw new Error(
-              "File upload is not configured. Mark an upload mutation with { fileUpload: true } (e.g. shared FileEndpoint.addFiles).",
-            );
-          const { fields, buildMetas } = fileUploadContract;
-          const formData = new FormData();
-          for (let i = 0; i < fileList.length; i++) formData.append(fields.files, fileList[i]);
-          formData.append(fields.metas, JSON.stringify(buildMetas(fileList)));
-          formData.append(fields.type, refName);
-          if (parentId) formData.append(fields.parentId, parentId);
-          const url = FetchClient.makeHttpUrl(cap.endpointKey, endpoint, cap.prefix, new Map());
-          return await this.http.post(url, formData, {
-            headers: this.#makeRequestHeaders(option),
-            baseUrl: this.#baseUrlOf(endpoint),
-          });
-        }) as FetchHandler,
-    );
+    this.#setHandlerFactory(names.addModelFiles, () => {
+      const upload = async (fileList: FileList | File[], parentId?: string, option?: FetchPolicy) => {
+        
+        if (this.#bridgeOf())
+          throw new Error("File upload is unavailable in an MCP App view: its host relays tool calls, not files.");
+        const cap = resolveFileUploadCapability(this.serializedSignal);
+        const endpoint = cap ? this.serializedSignal[cap.refName]?.endpoint[cap.endpointKey] : undefined;
+        if (!cap || !endpoint)
+          throw new Error(
+            "File upload is not configured. Mark an upload mutation with { fileUpload: true } (e.g. shared FileEndpoint.addFiles).",
+          );
+        const { fields, buildMetas } = fileUploadContract;
+        const formData = new FormData();
+        for (let i = 0; i < fileList.length; i++) formData.append(fields.files, fileList[i]);
+        formData.append(fields.metas, JSON.stringify(buildMetas(fileList)));
+        formData.append(fields.type, refName);
+        if (parentId) formData.append(fields.parentId, parentId);
+        const url = FetchClient.makeHttpUrl(cap.endpointKey, endpoint, cap.prefix, new Map());
+        return await this.http.post(url, formData, {
+          headers: this.#makeRequestHeaders(option),
+          baseUrl: this.#baseUrlOf(endpoint),
+        });
+      };
+      return ((fileList: FileList | File[], parentId?: string, option?: FetchPolicy) => {
+        this.#refuseInApp(names.addModelFiles);
+        return upload(fileList, parentId, option);
+      }) as FetchHandler;
+    });
   }
 
   #makeModelObjFn(refName: string, callerKey: string) {

package/fetch/index.ts

@@ -1,4 +1,5 @@
 export * from "./agentTurn";
+export * from "./appScope";
 export * from "./client";
 export * from "./fetchType";
 export * from "./requestStorage";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.0-rc.21",
+  "version": "3.1.0-rc.22",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/mcp/McpApps.ts

@@ -14,23 +14,29 @@ import {
 import type { PagePromptEntry, PagePromptRecord, PagePromptRun } from "../../signal/mcp/pagePrompt";
 import { McpAppShell } from "./McpAppShell";
 
-/** The CSR shell a view boots from: one single-file HTML per basePath, read from the build that serves the web. */
+/** The single-file view each `.app()` boots from, read from the build that serves the web. */
 export interface McpAppShellSource {
-  readonly basePaths: readonly string[];
-  /** `""` is the app without a basePath; `null` when this build has no single-file shell for it. */
-  read(basePath: string): Promise<string | null>;
+  /** `null` when this build has no view for the app. */
+  read(app: string): Promise<string | null>;
+}
+
+interface McpAppsOption {
+  /** Every write the view sends is refused before it leaves, as the deployment lists no write to relay it to. */
+  readOnly?: boolean;
 }
 
 export class McpApps {
   static readonly scheme = "ui://";
-  
-  static readonly rootSegment = "app";
   static readonly #tokenClaims = new Set(["iss", "aud", "exp", "nbf", "iat", "jti", "client_id", "scope"]);
+  
+  static readonly #appUri = /^ui:\/\/([^/]+)\/apps\/([A-Za-z0-9_-]{1,64})$/;
 
   readonly #shell: McpAppShellSource | null;
+  readonly #readOnly: boolean;
 
-  constructor(shell: McpAppShellSource | null) {
+  constructor(shell: McpAppShellSource | null, { readOnly = false }: McpAppsOption = {}) {
     this.#shell = shell;
+    this.#readOnly = readOnly;
   }
 
   get rendersUi() {
@@ -53,18 +59,19 @@ export class McpApps {
       ]),
     );
     const required = entry.arguments.filter((arg) => arg.required).map((arg) => arg.name);
+    const inputSchema = {
+      type: "object" as const,
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    };
+    const tool = { name: entry.name, description: entry.description, inputSchema };
+    
+    if (entry.kind === "prompt") return { ...tool, annotations: { readOnlyHint: false, openWorldHint: false } };
     return {
-      name: entry.name,
-      description: entry.description,
-      inputSchema: {
-        type: "object",
-        properties,
-        ...(required.length ? { required } : {}),
-        additionalProperties: false,
-      },
-      
-      annotations: { readOnlyHint: false, openWorldHint: false },
-      ...(this.#shell ? { _meta: this.#toolMetaOf(this.uriOf(this.#basePathOf(entry.pattern))) } : {}),
+      ...tool,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      ...(this.#shell ? { _meta: this.#toolMetaOf(this.uriOf(entry.name)) } : {}),
     };
   }
 
@@ -74,30 +81,30 @@ export class McpApps {
 
   resourcesOf(entries: PagePromptEntry[]): McpResource[] {
     if (!this.#shell) return [];
-    const { appName } = getEnv();
-    const basePaths = [...new Set(entries.map((entry) => this.#basePathOf(entry.pattern)))];
-    return basePaths.map((basePath) => ({
-      uri: this.uriOf(basePath),
-      name: basePath || appName,
-      description: `The ${basePath || appName} screens, rendered in place of a tool result.`,
-      mimeType: MCP_UI_MIME_TYPE,
-    }));
+    return entries
+      .filter((entry) => entry.kind === "app")
+      .map((entry) => ({
+        uri: this.uriOf(entry.name),
+        name: entry.name,
+        description: entry.description,
+        mimeType: MCP_UI_MIME_TYPE,
+      }));
   }
 
-  uriOf(basePath: string) {
-    const root = `${McpApps.scheme}${getEnv().appName.toLowerCase()}/${McpApps.rootSegment}`;
-    return basePath ? `${root}/${basePath}` : root;
+  uriOf(app: string) {
+    return `${McpApps.scheme}${getEnv().appName.toLowerCase()}/apps/${app}`;
   }
 
   async read(uri: string, origin: string): Promise<McpResourceContents | null> {
-    const shell = this.#shell;
-    const basePath = shell ? this.#basePathOfUri(uri) : null;
-    if (!shell || basePath === null) return null;
-    const html = await shell.read(basePath);
+    const match = McpApps.#appUri.exec(uri);
+    const app = match?.[1]?.toLowerCase() === getEnv().appName.toLowerCase() ? match[2] : undefined;
+    if (!this.#shell || !app) return null;
+    const html = await this.#shell.read(app);
     return html ? McpAppShell.contentsOf(uri, html, origin) : null;
   }
 
   resultOf(
+    entry: PagePromptEntry,
     run: Extract<PagePromptRun, { ok: true }>,
     messages: PromptMessage[],
     webOrigin: string,
@@ -107,14 +114,15 @@ export class McpApps {
     const href = `${url.pathname}${url.search}`;
     const content: PromptContent[] = [
       ...messages.map((message) => message.content),
-      { type: "text", text: `Open this screen in a browser: ${webOrigin}${href}` },
+      { type: "text", text: `Open the full screen: ${webOrigin}${href}` },
     ];
-    if (!this.#shell || !forView) return { content, isError: false };
+    if (entry.kind === "prompt" || !this.#shell || !forView) return { content, isError: false };
     const _meta = {
       [MCP_APP_META.snapshot]: McpApps.#snapshotOf(run.records),
       [MCP_APP_META.account]: forView.account,
+      ...(this.#readOnly ? { [MCP_APP_META.readOnly]: true } : {}),
     };
-    return { content, structuredContent: { href }, _meta, isError: false };
+    return { content, structuredContent: { href, ...run.route }, _meta, isError: false };
   }
 
   static accountOf(req: Request): Record<string, unknown> | null {
@@ -128,20 +136,6 @@ export class McpApps {
     }
   }
 
-  #basePathOf(pattern: string) {
-    const [, , segment] = pattern.split("/");
-    return segment && this.#shell?.basePaths.includes(segment) ? segment : "";
-  }
-
-  #basePathOfUri(uri: string) {
-    const match = /^ui:\/\/([^/]+)\/([^?#]*)$/i.exec(uri);
-    if (!match || match[1]?.toLowerCase() !== getEnv().appName.toLowerCase()) return null;
-    const [root, basePath, ...rest] = (match[2] ?? "").split("/");
-    if (root !== McpApps.rootSegment || rest.length) return null;
-    if (!basePath) return "";
-    return this.#shell?.basePaths.includes(basePath) ? basePath : null;
-  }
-
   static #snapshotOf(records: PagePromptRecord[]): McpAppSnapshotRecord[] {
     return records.flatMap(({ key, args, value }) => (value === undefined ? [] : [{ key, args, value }]));
   }

package/server/mcp/McpPages.ts

@@ -1,5 +1,11 @@
 import type { Logger } from "akanjs/common";
-import { MCP_APP_META, MCP_META_CLIENT_CAPABILITIES, type McpDocument, type McpEra } from "../../signal/mcp";
+import {
+  MCP_APP_META,
+  MCP_META_CLIENT_CAPABILITIES,
+  MCP_SCREEN_REFUSAL,
+  type McpDocument,
+  type McpEra,
+} from "../../signal/mcp";
 import type { PromptMessage } from "../../signal/mcp/Msg";
 import type { McpPrompt } from "../../signal/mcp/mcpProtocol";
 import type { PagePromptEntry, PagePromptRun, PagePromptSource } from "../../signal/mcp/pagePrompt";
@@ -18,6 +24,7 @@ export interface McpPagesProps {
   logger: Logger;
   promptBudget?: number;
   language?: string;
+  readOnly?: boolean;
 }
 
 interface McpPageCall {
@@ -33,10 +40,14 @@ export type McpPageRun =
 
 export class McpPages {
   static readonly listWaitMs = 1_000;
+  static readonly verdictTtlMs = 5_000;
+  static readonly #keptVerdicts = 256;
 
   readonly #props: McpPagesProps;
   #listed: PagePromptEntry[] | null = null;
   #listFailed = false;
+  #guardsFailed = false;
+  readonly #verdicts = new Map<string, { at: number; names: Promise<string[] | null> }>();
 
   constructor(props: McpPagesProps) {
     this.#props = props;
@@ -56,26 +67,36 @@ export class McpPages {
         logger.debug(`MCP page prompts: ${entries.length}${entries.length ? ` (${names})` : ""}`);
         const apps = this.#props.apps;
         if (!apps || !entries.length) return;
-        for (const { name } of entries.filter((entry) => this.#isEndpointName(entry.name)))
+        for (const { kind, name } of entries.filter((entry) => this.#isEndpointName(entry.name)))
           logger.warn(
-            `MCP did not publish page "${name}" as a tool: an endpoint already takes that name, so it stays a prompt only. Rename the prompt.`,
+            kind === "app"
+              ? `MCP did not publish app "${name}": an endpoint already takes that name. Rename the app.`
+              : `MCP did not publish page "${name}" as a tool: an endpoint already takes that name, so it stays a prompt only. Rename the prompt.`,
           );
-        const ui = apps.rendersUi ? "rendered from the CSR shell by an MCP Apps host" : "with no view to render";
-        logger.debug(`MCP page tools: ${ui}`);
+        const appCount = entries.filter((entry) => entry.kind === "app").length;
+        const ui = apps.rendersUi ? "each drawn by its own view in an MCP Apps host" : "with no view to draw them";
+        if (appCount) logger.debug(`MCP apps: ${appCount}, ${ui}`);
       })
       .catch((error: unknown) => {
         logger.warn(`MCP page prompts could not be listed: ${error instanceof Error ? error.message : error}`);
       });
   }
 
-  async prompts(): Promise<McpPrompt[]> {
-    return (await this.#list()).map(McpPages.#promptOf);
+  async prompts(req: Request): Promise<McpPrompt[]> {
+    const listed = await this.#list();
+    const prompts = listed.filter((entry) => entry.kind === "prompt");
+    return (await this.#visibleTo(req, prompts, listed)).map(McpPages.#promptOf);
   }
 
   async entry(name: string) {
     return (await this.#list()).find((candidate) => candidate.name === name);
   }
 
+  async prompt(name: string) {
+    const entry = await this.entry(name);
+    return entry?.kind === "prompt" ? entry : undefined;
+  }
+
   async toolCall(
     call: McpPageCall,
     document: McpDocument,
@@ -89,7 +110,7 @@ export class McpPages {
     if (!page.run || !apps) return { result: { content: page.messages.map((message) => message.content) } };
     const origin = this.#props.publicOrigin(call.req);
     const forView = call.ui ? { account: McpApps.accountOf(call.req) } : null;
-    return { result: apps.resultOf(page.run, page.messages, origin, forView) };
+    return { result: apps.resultOf(entry, page.run, page.messages, origin, forView) };
   }
 
   async run(
@@ -133,10 +154,10 @@ export class McpPages {
         run.reason === "argument" || run.reason === "unknown"
           ? run.message
           : gated
-            ? "This screen is not available to the signed-in account."
+            ? MCP_SCREEN_REFUSAL.gated
             : run.reason === "not-found"
-              ? "No screen exists for these arguments."
-              : "The page failed to load.";
+              ? MCP_SCREEN_REFUSAL.notFound
+              : MCP_SCREEN_REFUSAL.failed;
       return { refusal: message };
     }
     return { run, messages: await composer.compose(entry, run) };
@@ -144,20 +165,23 @@ export class McpPages {
 
   async toolOf(name: unknown) {
     if (!this.#props.apps || typeof name !== "string" || this.#isEndpointName(name)) return undefined;
-    return await this.entry(name).catch(() => undefined);
+    const entry = await this.entry(name).catch(() => undefined);
+    return entry && this.#publishesTool(entry) ? entry : undefined;
   }
 
-  async tools(ui: boolean, document: McpDocument) {
+  async tools(ui: boolean, document: McpDocument, req: Request) {
     const apps = this.#props.apps;
     if (!apps) return [];
-    const pages = (await this.#pageTools()).map((entry) => apps.toolOf(entry));
+    const listed = await this.#listedPages();
+    const pages = (await this.#visibleTo(req, this.#pageToolsOf(listed), listed)).map((entry) => apps.toolOf(entry));
     return ui ? [...document.appTools, ...pages] : pages;
   }
 
-  async resources(ui: boolean) {
+  async resources(ui: boolean, req: Request) {
     const apps = this.#props.apps;
     if (!apps?.rendersUi || !ui) return [];
-    return apps.resourcesOf(await this.#listedPages());
+    const listed = await this.#listedPages();
+    return apps.resourcesOf(await this.#visibleTo(req, this.#pageToolsOf(listed), listed));
   }
 
   async uiCapable(era: McpEra, meta: Record<string, unknown> | null, req: Request) {
@@ -206,12 +230,58 @@ export class McpPages {
   }
 
   async #listedPages(): Promise<PagePromptEntry[]> {
+    return (await McpPages.#withinListWait(this.#pagesOrNone())) ?? this.#listed ?? [];
+  }
+
+  async #visibleTo(req: Request, entries: PagePromptEntry[], listed: PagePromptEntry[]): Promise<PagePromptEntry[]> {
+    if (!this.#props.source || !entries.length) return entries;
+    
+    const names = await McpPages.#withinListWait(this.#verdictOf(req, listed));
+    if (!names) return entries;
+    const admitted = new Set(names);
+    return entries.filter((entry) => admitted.has(entry.name));
+  }
+
+  #verdictOf(req: Request, entries: PagePromptEntry[]): Promise<string[] | null> {
+    const headers = McpPages.#forwardedHeaders(req);
+    const names = entries.map((entry) => entry.name);
+    const key = JSON.stringify([headers, names]);
+    const now = Date.now();
+    const kept = this.#verdicts.get(key);
+    if (kept && now - kept.at < McpPages.verdictTtlMs) return kept.names;
+    const source = this.#props.source;
+    const verdict = (
+      source ? source.visible({ names, headers, language: this.#props.language }) : Promise.resolve(names)
+    )
+      .then((visible) => {
+        this.#guardsFailed = false;
+        return visible;
+      })
+      .catch((error: unknown) => {
+        if (this.#verdicts.get(key)?.names === verdict) this.#verdicts.delete(key);
+        if (!this.#guardsFailed)
+          this.#props.logger.warn(
+            `MCP could not run the route guards of its page prompts, so they are listed unfiltered: ${error instanceof Error ? error.message : error}`,
+          );
+        this.#guardsFailed = true;
+        return null;
+      });
+    this.#verdicts.delete(key);
+    this.#verdicts.set(key, { at: now, names: verdict });
+    for (const [oldest, { at }] of this.#verdicts) {
+      if (this.#verdicts.size <= McpPages.#keptVerdicts && now - at < McpPages.verdictTtlMs) break;
+      this.#verdicts.delete(oldest);
+    }
+    return verdict;
+  }
+
+  static async #withinListWait<T>(work: Promise<T>): Promise<T | null> {
     let timer: ReturnType<typeof setTimeout> | undefined;
     const stalled = new Promise<null>((resolve) => {
       timer = setTimeout(() => resolve(null), McpPages.listWaitMs);
     });
     try {
-      return (await Promise.race([this.#pagesOrNone(), stalled])) ?? this.#listed ?? [];
+      return await Promise.race([work, stalled]);
     } finally {
       clearTimeout(timer);
     }
@@ -236,8 +306,12 @@ export class McpPages {
     return !!this.#props.document().findTool(name) || this.#props.dispatcher.isEndpoint(name);
   }
 
-  async #pageTools() {
+  #pageToolsOf(listed: PagePromptEntry[]) {
     if (!this.#props.apps) return [];
-    return (await this.#listedPages()).filter((entry) => !this.#isEndpointName(entry.name));
+    return listed.filter((entry) => !this.#isEndpointName(entry.name) && this.#publishesTool(entry));
+  }
+
+  #publishesTool(entry: PagePromptEntry) {
+    return entry.kind === "app" || !this.#props.readOnly;
   }
 }