akanjs 3.1.0-rc.21 → 3.1.0-rc.23

package/common/authToken.ts

@@ -1,20 +1,9 @@
 import { getEnv } from "akanjs/base";
+import { legacyAuthTokenKey } from "./authCookie";
 import { decodeJwtPayload } from "./jwtDecode";
 
-/** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
-export const legacyAuthTokenKey = "jwt";
-
 export const authTokenKey = (): string => `${legacyAuthTokenKey}:${getEnv().appName}`;
 
-/** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
-export const isAuthTokenKey = (key: string): boolean =>
-  key === legacyAuthTokenKey || key.startsWith(`${legacyAuthTokenKey}:`);
-
-const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
-
-export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
-  !!cookieHeader && authCookiePattern.test(cookieHeader);
-
 export const isOwnAuthToken = (jwt: string): boolean => {
   const { appName, environment } = getEnv();
   try {

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!", "문제가 생겼어요!"],
@@ -92,6 +100,8 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     cancel: ["Cancel", "취소"],
     retry: ["Try again", "다시 시도"],
     pageLoadFailed: ["This page could not be loaded.", "이 화면을 불러오지 못했습니다."],
+    pageNotFound: ["This page does not exist.", "없는 화면입니다."],
+    goBack: ["Go back", "돌아가기"],
     unauthorized: ["Unauthorized", "권한 없음"],
     agent: ["Agent", "에이전트"],
     agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],

package/document/documentQuery.ts

@@ -144,6 +144,27 @@ export type DocumentQuery<T = any> =
       [K in DocumentPath<T>]?: DocumentQueryValue;
     };
 
+export const isDocumentQueryNode = (value: unknown): value is DocumentQueryNode => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const node = value as Record<string, unknown>;
+  const fits = (...keys: string[]) => Object.keys(node).every((key) => key === "kind" || keys.includes(key));
+  switch (node.kind) {
+    case "all":
+    case "any":
+      return Array.isArray(node.queries) && fits("queries");
+    case "not":
+      return !!node.query && typeof node.query === "object" && fits("query");
+    case "op":
+      return typeof node.op === "string" && queryOperatorKeys.has(node.op) && fits("op", "value");
+    case "raw":
+      return typeof node.sql === "string" && Array.isArray(node.params) && fits("sql", "params");
+    case "search":
+      return typeof node.text === "string" && fits("text", "columns", "prefix", "weights");
+    default:
+      return false;
+  }
+};
+
 export interface SqlFragment {
   sql: string;
   params: unknown[];

package/document/liveRowScope.ts

@@ -1,7 +1,7 @@
 import {
   type DocumentQuery,
-  type DocumentQueryNode,
   type DocumentQueryOperator,
+  isDocumentQueryNode,
   queryOperatorKeys,
 } from "./documentQuery";
 
@@ -14,7 +14,7 @@ type RemovedAtTest = "isNull" | "isNotNull" | "value";
 export class LiveRowScope {
   static conflictOf(query: DocumentQuery | undefined, negated = false): string | null {
     if (!query || typeof query !== "object") return null;
-    if (LiveRowScope.#isNode(query)) {
+    if (isDocumentQueryNode(query)) {
       if (query.kind === "all" || query.kind === "any")
         return query.queries.reduce<string | null>(
           (found, sub) => found ?? LiveRowScope.conflictOf(sub, negated),
@@ -30,7 +30,7 @@ export class LiveRowScope {
   }
 
   static #fieldConflict(path: string, value: unknown, negated: boolean): string | null {
-    if (LiveRowScope.#isNode(value) && value.kind !== "op") return LiveRowScope.conflictOf(value, negated);
+    if (isDocumentQueryNode(value) && value.kind !== "op") return LiveRowScope.conflictOf(value, negated);
     if (path !== "removedAt") return null;
     for (const [test, spelled] of LiveRowScope.#testsOf(value)) {
       const named = negated ? `not(removedAt ${spelled})` : `removedAt ${spelled}`;
@@ -44,7 +44,7 @@ export class LiveRowScope {
   static #testsOf(value: unknown): [RemovedAtTest, string][] {
     if (value === undefined) return [];
     if (value === null) return [["isNull", "null"]];
-    if (LiveRowScope.#isNode(value) && value.kind === "op") {
+    if (isDocumentQueryNode(value) && value.kind === "op") {
       const test = LiveRowScope.#testOf(value.op, value.value);
       return test ? [test] : [];
     }
@@ -72,8 +72,4 @@ export class LiveRowScope {
     if ((op === "oneOf" || op === "notOneOf") && !(operand as unknown[] | undefined)?.length) return null;
     return ["value", op];
   }
-
-  static #isNode(value: unknown): value is DocumentQueryNode {
-    return !!value && typeof value === "object" && "kind" in value;
-  }
 }

package/document/queryEvaluator.ts

@@ -4,6 +4,7 @@ import {
   type DocumentQueryNode,
   type DocumentQueryOperator,
   encodeDocumentValue,
+  isDocumentQueryNode,
   queryOperatorKeys,
   sanitizeJson,
 } from "./documentQuery";
@@ -49,7 +50,7 @@ export class DocumentQueryEvaluator {
    */
   static unevaluableReason(query: DocumentQuery | undefined): string | null {
     if (!query || typeof query !== "object") return null;
-    if (DocumentQueryEvaluator.#isNode(query)) {
+    if (isDocumentQueryNode(query)) {
       if (query.kind === "raw") return "q.raw() carries SQL that only the database can run";
       if (query.kind === "search") return "q.search() compiles to a full-text JOIN with no in-memory equivalent";
       if (query.kind === "all" || query.kind === "any")
@@ -70,7 +71,7 @@ export class DocumentQueryEvaluator {
     if (!value || typeof value !== "object") return null;
     if (baseDocumentColumns.has(path)) return null;
     const keyAbsence = `${path}: exists/missing asks whether the key is in the stored JSON, which a document in hand cannot answer — use q.empty()`;
-    if (DocumentQueryEvaluator.#isNode(value)) {
+    if (isDocumentQueryNode(value)) {
       if (value.kind === "op") return value.op === "exists" || value.op === "missing" ? keyAbsence : null;
       return DocumentQueryEvaluator.unevaluableReason(value as DocumentQuery);
     }
@@ -94,7 +95,7 @@ export class DocumentQueryEvaluator {
 
   evaluate(query: DocumentQuery | undefined, row: DocumentRowView): boolean {
     if (!query || typeof query !== "object") return true;
-    if (DocumentQueryEvaluator.#isNode(query)) return this.#node(query, row);
+    if (isDocumentQueryNode(query)) return this.#node(query, row);
     const entries = Object.entries(query);
     if (!entries.length) return true;
     return entries.every(([path, value]) => this.#field(path, value, row));
@@ -118,7 +119,7 @@ export class DocumentQueryEvaluator {
   }
 
   #field(path: string, value: unknown, row: DocumentRowView): boolean {
-    if (DocumentQueryEvaluator.#isNode(value)) {
+    if (isDocumentQueryNode(value)) {
       if (value.kind !== "op") return this.evaluate({ [path]: value } as DocumentQuery, row);
       return this.#operator(path, value.op, value.value, row);
     }
@@ -290,8 +291,4 @@ export class DocumentQueryEvaluator {
   static #foldAscii(text: string) {
     return text.replace(/[A-Z]/g, (char) => char.toLowerCase());
   }
-
-  static #isNode(value: unknown): value is DocumentQueryNode {
-    return !!value && typeof value === "object" && "kind" in value;
-  }
 }

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.23",
   "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 }]));
   }