akanjs 3.0.0-beta.8 → 3.0.0

package/server/mcp/McpRouter.ts

@@ -1,7 +1,7 @@
 import { type BackendEnv, getEnv } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { DictionaryLookup } from "akanjs/dictionary";
-import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import { CacheAdaptorRole, type InjectRegistry, type LiveRegistry } from "akanjs/service";
 import {
   MCP_LEGACY_VERSION,
   MCP_META_CLIENT_CAPABILITIES,
@@ -26,47 +26,26 @@ import type { HttpRoutes } from "../types";
 import { McpAuth, type McpAuthOption } from "./McpAuth";
 import { McpAuthRequiredError, McpDispatcher } from "./McpDispatcher";
 import { McpEventStream } from "./McpEventStream";
-import { McpRateLimiter, type McpRateLimitOption } from "./McpRateLimiter";
+import { McpRateLimiter, type McpRateLimitOption, type McpSharedCounter } from "./McpRateLimiter";
 import { PagePromptComposer } from "./PagePromptComposer";
 
 export interface McpRouterProps {
   registry: InjectRegistry;
-  /** Spread into every `SignalContext` this router's dispatcher builds; middleware reads it. */
   env: BackendEnv;
   live: LiveRegistry;
   middleware: Map<string, MiddlewareCls>;
   path?: string;
   version?: string;
-  /** Free-text usage guidance handed to the model alongside the tool list. */
   instructions?: string;
-  /** Extra origins allowed past the DNS-rebinding check, beyond the server's own host. */
   allowedOrigins?: string[];
   readOnly?: boolean;
-  /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
   pageSize?: number;
-  /**
-   * The one language every title, description and domain error text is resolved in. The catalogue is built once
-   * at boot and cached by clients, so it is a server-wide choice rather than a per-request one: `Accept-Language`
-   * would mean a document per language, re-deriving every tool schema, for a surface a model reads and a human
-   * rarely sees. Defaults to `en`, falling back to the first registered language when the app has no `en`.
-   */
   language?: string;
-  /** Whether a structured result also ships as serialized JSON in the text block. Default `true`. */
   legacyTextBlock?: boolean;
-  /**
-   * Where `prompts/list` and `prompts/get` are answered from: the pages, through the RSC worker. Absent on an
-   * API-only build, which then publishes no prompts at all.
-   */
   pagePrompts?: PagePromptSource;
-  /** Characters of screen data one prompt may attach before its lists are cut; see `PagePromptComposer`. */
   promptBudget?: number;
   outputSchema?: McpOutputSchemaMode;
   auth?: McpAuthOption;
-  /**
-   * Budget per caller for the methods that execute an endpoint (`tools/call`, `resources/read`, `prompts/get`).
-   * On by default at `McpRateLimiter.defaults`; `false` takes it off. Listings are not counted — they are served
-   * from memory and a client polls them.
-   */
   rateLimit?: McpRateLimitOption | false;
 }
 
@@ -91,31 +70,15 @@ interface McpCacheHint {
 
 const notAllowed = () => new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST" } });
 const defaultPageSize = 100;
-/**
- * Named rather than left to `DictionaryLookup`'s own fallback, which is whichever language registered first —
- * true today only because dictionaries are written `[en, ko]`, and nothing keeps it true.
- */
+
 const defaultLanguage = "en";
-/**
- * The catalogue is fixed for the life of the process, so the ceiling is how long a client may keep serving a
- * list from a server that has since been redeployed. `private` because the listing is filtered per credential
- * (`filterForAccount`): a shared cache would hand one caller another's view of the shelf.
- */
+
 const listCache: McpCacheHint = { ttlMs: 300_000, cacheScope: "private" };
-/** Capabilities name what this build implements — they do not vary by caller and change only with the binary. */
+
 const discoverCache: McpCacheHint = { ttlMs: 3_600_000, cacheScope: "public" };
 
-/**
- * Serves the app's signals as one MCP endpoint.
- *
- * Answers both protocol eras from the same stateless handler. `2026-07-28` is stateless by design; the legacy
- * revisions only *offer* sessions — a server may decline to issue `Mcp-Session-Id`, and a client that never
- * receives one neither sends one back nor asks to resume a stream. So the legacy era costs an `initialize` reply
- * and a laxer `_meta` check, not a session store. (Measured against Claude Code 2.1.226, which speaks it.)
- */
 export class McpRouter {
   static readonly logger = new Logger("McpRouter");
-  /** Past this a listing is a meaningful slice of a model's window, which is where it becomes worth saying so. */
   static readonly listingWarnBytes = 1000 * 1024;
 
   readonly #props: McpRouterProps;
@@ -126,11 +89,18 @@ export class McpRouter {
 
   constructor(props: McpRouterProps) {
     this.#props = props;
-
+    
     const legacyTextBlock = props.outputSchema === "none" ? undefined : props.legacyTextBlock;
+    
     this.#dispatcher = new McpDispatcher({ ...props, legacyTextBlock, language: props.language ?? defaultLanguage });
     this.#auth = new McpAuth({ ...props.auth, path: props.path ?? "/mcp" });
-    this.#limiter = props.rateLimit === false ? null : new McpRateLimiter(props.rateLimit);
+    this.#limiter =
+      props.rateLimit === false
+        ? null
+        : new McpRateLimiter(
+            props.rateLimit,
+            (props.registry.adaptor.get(CacheAdaptorRole) as McpSharedCounter | undefined) ?? null,
+          );
   }
 
   createRoutes(): HttpRoutes {
@@ -138,7 +108,7 @@ export class McpRouter {
       [this.#props.path ?? "/mcp"]: {
         POST: async (req: Request) => this.#cors(req, await this.#post(req)),
         OPTIONS: (req: Request) => this.#preflight(req),
-
+        
         GET: (req: Request) => this.#cors(req, notAllowed()),
         DELETE: (req: Request) => this.#cors(req, notAllowed()),
       },
@@ -146,22 +116,6 @@ export class McpRouter {
     };
   }
 
-  /**
-   * Says once, at boot, what this build actually published — and names every endpoint that was kept out.
-   *
-   * The rejections are fail-closed by design: an endpoint MCP cannot carry, or whose guards do not admit it, is
-   * simply not in the catalogue. That is the right default and the wrong silence, and it matters more now that
-   * exposure follows the guards — nobody wrote an opt-in whose absence would explain a missing tool, so this log
-   * is the only place the answer exists. A refusal turns on a resolved return type and a resolved guard list, so
-   * it reads only from here.
-   *
-   * An entry published with no description rides here for the same reason: the text every generated entry borrows
-   * is a *model* `.desc()`, which no source rule would read as that entry's description. This holds the resolved
-   * catalogue, so it can simply look.
-   *
-   * Called by whatever mounts the router rather than from `createRoutes`, so building a router to answer one
-   * request — which tests and tooling do — does not narrate a catalogue nobody asked about.
-   */
   report() {
     try {
       const document = this.#getDocument();
@@ -173,7 +127,6 @@ export class McpRouter {
       if (cost.bySignal.length) McpRouter.logger.debug(`MCP catalogue cost: ${McpRouter.#costLine(cost.bySignal)}`);
       if (this.#limiter) McpRouter.logger.debug(`MCP rate limit: ${this.#limiter.describe()}`);
       else McpRouter.logger.warn("MCP rate limit is off: an authenticated agent may call tools as fast as it likes.");
-
       if (cost.bytes > McpRouter.listingWarnBytes)
         McpRouter.logger.warn(
           `MCP listing is ${McpRouter.#kb(cost.bytes)}, which every agent that connects pays before its first turn. Narrow it with \`mcp: false\` on an endpoint or the \`mcp\` map on \`slice()\`.`,
@@ -182,7 +135,6 @@ export class McpRouter {
         McpRouter.logger.warn(
           '`outputSchema: "none"` keeps the text block on: a client reads `structuredContent` only against a declared schema, so `legacyTextBlock: false` would hand it nothing.',
         );
-
       if (!tools.length)
         McpRouter.logger.warn(
           "MCP is enabled but published nothing. Every candidate was refused; see the reasons below.",
@@ -193,18 +145,13 @@ export class McpRouter {
       for (const { key, reason } of undescribed)
         McpRouter.logger.warn(`MCP exposed "${key}" with no description: ${reason}`);
     } catch (error) {
-
+      
       McpRouter.logger.warn(
         `MCP catalogue could not be built at boot: ${error instanceof Error ? error.message : error}`,
       );
     }
   }
 
-  /**
-   * A guarded tool is only reachable with a credential, and this server can neither issue one nor check one unless
-   * something configured `auth`. Left silent, the shelf lists tools no client can ever call and a forged token
-   * reads as anonymous — so it is said once at boot, and said louder anywhere but a developer's machine.
-   */
   #reportUnverifiable(toolNames: string[]) {
     const { verify, authorizationServers } = this.#props.auth ?? {};
     if (verify || authorizationServers?.length) return;
@@ -222,7 +169,6 @@ export class McpRouter {
     return bytes < 1024 ? `${bytes}B` : `${Math.round(bytes / 1024)}KB`;
   }
 
-  /** The heaviest signals first, capped: a fleet of forty models would otherwise wrap the line off the screen. */
   static #costLine(bySignal: McpSignalCost[]) {
     const shown = bySignal.slice(0, 8);
     const rest = bySignal.length - shown.length;
@@ -232,7 +178,6 @@ export class McpRouter {
     return rest > 0 ? `${line} · +${rest} more` : line;
   }
 
-  /** Rebuilding per request would re-derive every tool schema on a list agents poll; the set is fixed at boot. */
   #getDocument() {
     if (this.#document) return this.#document;
     const lookup = new DictionaryLookup(this.#props.language ?? defaultLanguage);
@@ -264,7 +209,7 @@ export class McpRouter {
     if (method.startsWith("notifications/")) return new Response(null, { status: 202 });
 
     const params = (body.params ?? {}) as Record<string, unknown>;
-
+    
     const meta = McpRouter.#meta(params);
     const era: McpEra = method !== "initialize" && meta && MCP_META_PROTOCOL_VERSION in meta ? "modern" : "legacy";
     const rejection = era === "modern" ? McpRouter.#validateModern(req, method, params, meta ?? {}, id) : null;
@@ -312,38 +257,27 @@ export class McpRouter {
       case "resources/templates/list":
         return await this.#list(call, "resourceTemplates", document.resourceTemplates);
       case "prompts/list":
-        return await this.#list(call, "prompts", (await this.#pagePromptEntries()).map(McpRouter.#promptOf));
+        return await this.#list(
+          call,
+          "prompts",
+          ((await this.#props.pagePrompts?.list()) ?? []).map(McpRouter.#promptOf),
+        );
       case "tools/call": {
-        const slot = this.#acquire(call);
+        const slot = await this.#acquire(call);
         return "refused" in slot ? slot.refused : await this.#toolsCall(call, document, slot.release);
       }
-      case "prompts/get": {
-        const slot = this.#acquire(call);
-        if ("refused" in slot) return slot.refused;
-        try {
-          return await this.#promptsGet(call, document);
-        } finally {
-          slot.release();
-        }
-      }
-      case "resources/read": {
-        const slot = this.#acquire(call);
-        if ("refused" in slot) return slot.refused;
-        try {
-          return await this.#resourcesRead(call, document);
-        } finally {
-          slot.release();
-        }
-      }
+      case "prompts/get":
+        return await this.#limited(call, () => this.#promptsGet(call, document));
+      case "resources/read":
+        return await this.#limited(call, () => this.#resourcesRead(call, document));
       default:
-
+        
         return McpRouter.#error(call.id, McpErrorCode.methodNotFound, McpRouter.#methodNotFound(call.method), {
           status: call.era === "modern" ? 404 : 200,
         });
     }
   }
 
-  /** Filter first, then page: an offset has to address the list the caller can actually see. */
   async #list<T extends { name: string }>(call: McpCall, key: string, items: T[]) {
     const visible = await this.#dispatcher.filterForAccount(items, call.req);
     const page = McpRouter.#page(visible, call.params.cursor, this.#props.pageSize ?? defaultPageSize);
@@ -352,14 +286,19 @@ export class McpRouter {
     return this.#result(call, result, listCache);
   }
 
-  /**
-   * Counted before the tool is even looked up, so a loop over an unknown name is a loop this stops too. The 429
-   * carries a JSON-RPC body like every other envelope-level refusal, and `Retry-After` because a client that
-   * backs off by that header is the one behaviour a limit is asking for.
-   */
-  #acquire(call: McpCall): { refused: Response } | { release: () => void } {
+  async #limited(call: McpCall, run: () => Promise<Response>): Promise<Response> {
+    const slot = await this.#acquire(call);
+    if ("refused" in slot) return slot.refused;
+    try {
+      return await run();
+    } finally {
+      slot.release();
+    }
+  }
+
+  async #acquire(call: McpCall): Promise<{ refused: Response } | { release: () => void }> {
     if (!this.#limiter) return { release: () => {} };
-    const verdict = this.#limiter.acquire(McpAuth.callerKey(call.req));
+    const verdict = await this.#limiter.acquire(McpAuth.callerKey(call.req));
     if (verdict.ok) return { release: verdict.release };
     const seconds = Math.max(1, Math.ceil(verdict.retryAfterMs / 1000));
     const message =
@@ -374,14 +313,13 @@ export class McpRouter {
     };
   }
 
-  /** `release` frees the caller's in-flight slot: at the answer here, or when a streamed call settles. */
   async #toolsCall(call: McpCall, document: McpDocument, release: () => void) {
     let streaming = false;
     try {
       const name = call.params.name;
       if (typeof name !== "string") return McpRouter.#error(call.id, McpErrorCode.invalidParams, "Missing tool name.");
       const exposed = document.findTool(name);
-
+      
       if (!exposed) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown tool: ${name}.`);
       const args = McpRouter.#arguments(call.params);
       if (!args) return McpRouter.#error(call.id, McpErrorCode.invalidParams, McpRouter.#badArguments);
@@ -394,14 +332,6 @@ export class McpRouter {
     }
   }
 
-  /**
-   * Runs the tool and only commits to a stream once it actually reports progress.
-   *
-   * Deciding late is what keeps the failure modes intact: an HTTP status is fixed the moment the response is
-   * returned, so a call that opened a stream up front could no longer answer 401 with a `WWW-Authenticate`
-   * challenge. Guards run before an endpoint body can report anything, so by the time this switches to SSE the
-   * authorization decision has already been made — which is why the streamed path below need not carry one.
-   */
   async #streamedToolCall(
     call: McpCall,
     exposed: McpExposedEndpoint,
@@ -426,7 +356,6 @@ export class McpRouter {
       return this.#result(call, outcome.result);
     }
     const stream = new McpEventStream(() => channel.abort());
-    
     void this.#pump(call, channel, settled, stream, progressToken).catch((error: unknown) => {
       McpRouter.logger.error(`MCP stream for ${exposed.key} failed: ${error instanceof Error ? error.stack : error}`);
     });
@@ -444,7 +373,7 @@ export class McpRouter {
       for await (const report of channel.reports())
         stream.write({ jsonrpc: "2.0", method: "notifications/progress", params: { progressToken, ...report } });
       const outcome = await settled;
-
+      
       stream.write(
         "error" in outcome
           ? McpRouter.#errorBody(call.id, McpErrorCode.internal, "Internal server error.")
@@ -457,13 +386,6 @@ export class McpRouter {
 
   static readonly #badArguments = "`arguments` must be an object of named values.";
 
-  /**
-   * `arguments` is an object or it is not there at all; anything else is the caller's own mistake and is reported
-   * as one. Coercing it to `{}` ran the call with every argument missing — a tool that takes none then simply
-   * succeeded, and one that takes some answered "Missing required argument", which sends a model looking for a
-   * value it did send. An array is refused with the rest: MCP names its arguments, and positional ones would
-   * silently be read as the properties `0`, `1`, `2`.
-   */
   static #arguments(params: Record<string, unknown>) {
     const args = params.arguments;
     if (args === undefined || args === null) return {};
@@ -471,12 +393,6 @@ export class McpRouter {
     return args as Record<string, unknown>;
   }
 
-  /**
-   * Derived from the catalogue rather than fixed, so a server with nothing to list does not invite a listing that
-   * can only come back empty. Read from the unfiltered document on purpose: a capability says what this build
-   * implements, and one that narrowed per credential would contradict itself across a cached handshake. Prompts
-   * are the pages', so the capability follows whether there are pages to ask — the RSC worker answers the count.
-   */
   #capabilities(document: McpDocument) {
     return {
       ...(document.tools.length ? { tools: {} } : {}),
@@ -485,10 +401,6 @@ export class McpRouter {
     };
   }
 
-  /**
-   * Pages load lazily in the RSC worker, so the prompt catalogue is read once the worker is up rather than built
-   * here at boot; the line lands in the same log a little after the tool counts.
-   */
   #reportPagePrompts() {
     const source = this.#props.pagePrompts;
     if (!source) return;
@@ -505,36 +417,21 @@ export class McpRouter {
       });
   }
 
-  async #pagePromptEntries(): Promise<PagePromptEntry[]> {
-    return (await this.#props.pagePrompts?.list()) ?? [];
-  }
-
   static #promptOf({ name, description, arguments: args }: PagePromptEntry): McpPrompt {
     return { name, description, ...(args.length ? { arguments: args } : {}) };
   }
 
-  /** Only the credential travels into the page run: the page decides with it exactly as a browser tab would. */
   static #forwardedHeaders(req: Request): [string, string][] {
     const authorization = req.headers.get("authorization");
     return authorization ? [["authorization", authorization]] : [];
   }
 
-  /**
-   * A client asks for progress by naming a token, and can only receive it over a stream — so both have to be
-   * true. Only `tools/call` is offered one: a listing is served from memory, and a prompt is a user-triggered
-   * read that a client renders as a slash command rather than something it watches run.
-   */
   static #progressToken(call: McpCall) {
     if (!call.req.headers.get("accept")?.includes("text/event-stream")) return undefined;
     const token = McpRouter.#meta(call.params)?.progressToken;
     return typeof token === "string" || typeof token === "number" ? token : undefined;
   }
 
-  /**
-   * A prompt is a screen: the page named by `page().prompt()` runs in the RSC worker with the caller's token, and
-   * what it fetched comes back as the messages. A missing required argument is answered with a pointer to the tool
-   * that finds the id rather than with a guess — a prompt cannot re-run itself, so a guess would go unused.
-   */
   async #promptsGet(call: McpCall, document: McpDocument) {
     const name = call.params.name;
     if (typeof name !== "string") return McpRouter.#error(call.id, McpErrorCode.invalidParams, "Missing prompt name.");
@@ -590,10 +487,10 @@ export class McpRouter {
     const resolved = document.resolveResource(uri);
     if (!resolved) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown resource: ${uri}.`);
     const result = await this.#dispatcher.call(resolved.exposed, resolved.args, call.req);
-
+    
     if (result.isError)
       return McpRouter.#error(call.id, McpErrorCode.invalidParams, result.content[0]?.text ?? "Read failed.");
-
+    
     const text =
       result.structuredContent === undefined
         ? (result.content[0]?.text ?? "null")
@@ -601,35 +498,18 @@ export class McpRouter {
     return this.#result(call, { contents: [{ uri, mimeType: "application/json", text }] });
   }
 
-  /**
-   * Cross-origin gate. MCP clients are not browsers and normally send no `Origin` at all, so absence is allowed;
-   * a present one has to name this server or an explicitly configured peer.
-   *
-   * Matching against our own host stops a page served from somewhere else, and that is all it stops — a rebinding
-   * attack points its *own* name at this server, so the `Origin` it sends and the host it arrives on agree and it
-   * passes. `allowedOrigins` is the list that actually decides who may drive this server from a browser; leave it
-   * unset unless a browser-hosted client needs it.
-   */
   #originAllowed(req: Request) {
     const origin = req.headers.get("origin");
     if (!origin) return true;
     if ((this.#props.allowedOrigins ?? []).includes(origin)) return true;
     try {
-
+      
       return new URL(origin).host === new URL(this.#auth.publicOrigin(req)).host;
     } catch {
       return false;
     }
   }
 
-  /**
-   * Answers the preflight a browser-hosted client is forced to make. `content-type: application/json` and the
-   * `mcp-*` mirror headers each put the call past the simple-request bar, so without this the request never
-   * leaves the browser and `allowedOrigins` grants nothing it can use.
-   *
-   * The requested header list is echoed rather than fixed: the decision that matters is the origin, and a fixed
-   * list only breaks clients that send one more header than we predicted.
-   */
   #preflight(req: Request) {
     if (!req.headers.get("origin") || !this.#originAllowed(req)) return new Response("Forbidden", { status: 403 });
     return this.#cors(
@@ -646,12 +526,6 @@ export class McpRouter {
     );
   }
 
-  /**
-   * Grants the one origin that already passed `#originAllowed`, so the rebinding defence stays exactly as wide
-   * as it was. Never `access-control-allow-credentials`: an MCP client presents its bearer token in a header it
-   * sets deliberately, and allowing ambient cookies is what would turn a permitted origin into one that can ride
-   * a signed-in user's session.
-   */
   #cors(req: Request, res: Response) {
     const origin = req.headers.get("origin");
     if (!origin || !this.#originAllowed(req)) return res;
@@ -670,7 +544,7 @@ export class McpRouter {
   }
 
   #envelope(call: McpCall, result: object, cache?: McpCacheHint) {
-
+    
     const meta =
       call.era === "modern"
         ? { resultType: "complete", _meta: { [MCP_META_SERVER_INFO]: this.#serverInfo() }, ...cache }
@@ -678,12 +552,6 @@ export class McpRouter {
     return { jsonrpc: "2.0", id: call.id, result: { ...meta, ...result } };
   }
 
-  /**
-   * The cursor is an offset into the filtered list, base64url-wrapped so a client treats it as opaque rather
-   * than arithmetic it may do itself. The catalogue is built once at boot, so an offset stays meaningful for the
-   * life of the process; one minted by an earlier process may address a position that no longer exists, and that
-   * is refused rather than clamped — a silently shortened page reads as "the list ends here".
-   */
   static #page<T>(items: T[], cursor: unknown, size: number) {
     const offset = McpRouter.#offset(cursor);
     if (offset === null || offset > items.length) return null;
@@ -698,7 +566,7 @@ export class McpRouter {
     if (cursor === undefined || cursor === null) return 0;
     if (typeof cursor !== "string") return null;
     const decoded = Buffer.from(cursor, "base64url").toString("utf8");
-
+    
     if (!decoded) return null;
     const offset = Number(decoded);
     return Number.isInteger(offset) && offset >= 0 ? offset : null;
@@ -709,16 +577,6 @@ export class McpRouter {
     return meta && typeof meta === "object" ? (meta as Record<string, unknown>) : null;
   }
 
-  /**
-   * Legacy clients propose a version; answer with theirs when we speak it, and otherwise with whichever end of our
-   * list they are likelier to accept.
-   *
-   * A client proposes the newest revision *it* speaks, so an unknown proposal is either newer than everything here
-   * — in which case the newest we have is the closest thing it may still know — or older than everything here, in
-   * which case the newest is hopeless and the oldest is the only candidate. The spec's "SHOULD be the latest
-   * version supported by the server" covers the first case and would strand the second, which is the one an old
-   * client is actually in. Revision names are ISO dates, so they order as strings.
-   */
   static #negotiate(requested: unknown) {
     if (typeof requested !== "string") return MCP_LEGACY_VERSION;
     if (MCP_SUPPORTED_VERSIONS.includes(requested as (typeof MCP_SUPPORTED_VERSIONS)[number])) return requested;
@@ -726,17 +584,10 @@ export class McpRouter {
     return requested > newest ? newest : MCP_SUPPORTED_VERSIONS[MCP_SUPPORTED_VERSIONS.length - 1];
   }
 
-  /** Legacy clients have no way to fall forward, so the one diagnostic they get is this message. */
   static #methodNotFound(method: string) {
     return `Method not found: ${method}. This server speaks MCP ${MCP_SUPPORTED_VERSIONS.join(", ")}.`;
   }
 
-  /**
-   * Modern requests mirror parts of the body into headers so a proxy can route and audit without parsing JSON.
-   * A mismatch is rejected rather than resolved in the body's favour: whatever a gateway in front of us allowed
-   * was decided from the header, so honouring a body that disagrees is how that check gets bypassed. A mirror
-   * that is simply absent is refused on the same ground — see `#headerMismatch`.
-   */
   static #validateModern(
     req: Request,
     method: string,
@@ -762,26 +613,16 @@ export class McpRouter {
 
   static #headerMismatch(req: Request, header: string, expected: string) {
     const raw = req.headers.get(header);
-
+    
     if (raw === null) return `Header \`${header}\` is required by this protocol version and was not sent.`;
     return McpRouter.#decodeHeader(raw) === expected ? undefined : `Header \`${header}\` does not match the body.`;
   }
 
-  /** Values that are not ASCII-safe travel wrapped in a lowercase base64 sentinel: `=?base64?…?=`. */
   static #decodeHeader(value: string) {
     if (!value.startsWith("=?base64?") || !value.endsWith("?=")) return value;
-    try {
-      return Buffer.from(value.slice(9, -2), "base64").toString("utf8");
-    } catch {
-      return value;
-    }
+    return Buffer.from(value.slice(9, -2), "base64").toString("utf8");
   }
 
-  /**
-   * A JSON-RPC error body is what tells a client that a 400 or 404 came from an MCP server rather than from a
-   * proxy in front of it, so the status never travels alone. Tool-level failures stay at 200 and are carried in
-   * the JSON-RPC error itself; only envelope problems escalate to an HTTP status.
-   */
   static #error(
     id: string | number | null,
     code: number,

package/server/mcp/PagePromptComposer.ts

@@ -1,12 +1,13 @@
+import { PrimitiveRegistry } from "akanjs/base";
 import { Logger } from "akanjs/common";
-import { ConstantRegistry, type ConstantType, type MaskModel } from "akanjs/constant";
+import { agentRead, ConstantRegistry, type ConstantType, type MaskModel } from "akanjs/constant";
 import type { McpDocument } from "../../signal/mcp/McpDocument";
 import { Msg, type PromptMessage } from "../../signal/mcp/Msg";
 import type { PagePromptEntry, PagePromptRecord, PagePromptRun } from "../../signal/mcp/pagePrompt";
 
 interface PagePromptComposerProps {
   document: McpDocument;
-  /** Characters of attached data one prompt may carry; the largest list is cut first and the cut is said. */
+  /** Characters of attached data one prompt may carry. */
   budget: number;
   /** The tool names this caller may see, so the tools line offers nothing the listing would not. */
   visibleTools: (names: string[]) => Promise<string[]>;
@@ -19,13 +20,6 @@ interface Attachment {
   model?: MaskModel;
 }
 
-/**
- * Turns what a page fetched into the messages `prompts/get` answers.
- *
- * The instruction is the page's own description and nothing more: the screen's data rides as embedded resources
- * masked by the model each endpoint declares, and the tools named at the end are the published ones of the same
- * modules — a model that reads a ticket board is told the ticket tools, not all three hundred.
- */
 export class PagePromptComposer {
   static readonly logger = new Logger("PagePromptComposer");
   static readonly defaultBudget = 60_000;
@@ -36,11 +30,6 @@ export class PagePromptComposer {
     this.#props = props;
   }
 
-  /**
-   * A required argument nobody filled in gets one message pointing at the tool that finds the id, not a guess.
-   * A prompt cannot re-run itself, so pre-filled context would never be used; the model finds the id with the
-   * search tool and proceeds with the tools from there.
-   */
   missing(entry: PagePromptEntry, names: string[]): PromptMessage[] {
     return names.map((name) => {
       const finder = this.#finderFor(name);
@@ -73,11 +62,6 @@ export class PagePromptComposer {
     return messages;
   }
 
-  /**
-   * One document in two shapes — a layout's `project` and a page's `lightProject` — travels once, as the larger.
-   * `light<Model>` is refused from the tool shelf for reading the same document as `<Model>`, and attaching both
-   * spent the budget on the same rows twice.
-   */
   static #dedupe(records: PagePromptRecord[]): PagePromptRecord[] {
     const kept: PagePromptRecord[] = [];
     const byDocument = new Map<string, number>();
@@ -105,7 +89,10 @@ export class PagePromptComposer {
   #attachmentOf(record: PagePromptRecord): Attachment | null {
     const { key, args, returns } = record;
     const uri = this.#props.document.resourceUri(key, args) ?? PagePromptComposer.#callUri(key, args);
-    if (!returns.modelType) return { key, uri, value: record.value };
+    if (!returns.modelType) {
+      const primitive = PrimitiveRegistry.hasName(returns.refName) ? PrimitiveRegistry.get(returns.refName) : null;
+      return { key, uri, value: agentRead(primitive, record.value, returns.arrDepth ?? 0) };
+    }
     try {
       return {
         key,
@@ -122,12 +109,6 @@ export class PagePromptComposer {
     }
   }
 
-  /**
-   * Keeps the attachments inside the budget by shortening lists, largest first, and says what was cut. A page
-   * with `{ limit: 0 }` is right for a screen and a disaster for a model's window, so the cap is the framework's.
-   * Only a list is cut: a single document rides whole, so the budget is what the lists are trimmed to fit under
-   * and a screen of large documents can still exceed it.
-   */
   #fit(attachments: Attachment[]): PromptMessage[] {
     const items = attachments.map((attachment) => ({
       attachment,
@@ -154,7 +135,6 @@ export class PagePromptComposer {
     return [...items.map((item) => item.message), ...notes];
   }
 
-  /** The published tools of the modules the screen fetched from, minus the reads whose answers are attached above. */
   async #toolsFor(keys: string[], attached: Set<string>): Promise<string[]> {
     const document = this.#props.document;
     const refNames = new Set(
@@ -167,7 +147,6 @@ export class PagePromptComposer {
     return await this.#props.visibleTools(names);
   }
 
-  /** `projectId` → the published list tool of `project`, a search slice first — what a person would use to find one. */
   #finderFor(argName: string): string | undefined {
     const refName = argName.replace(/Id$/, "");
     if (!refName || refName === argName) return undefined;
@@ -191,7 +170,6 @@ export class PagePromptComposer {
     return content.type === "resource" ? content.resource.text.length : 0;
   }
 
-  /** A tool with no `akan://` template still gets an address a reader can trace back to the call that made it. */
   static #callUri(key: string, args: Record<string, unknown>): string {
     const search = new URLSearchParams();
     for (const [name, value] of Object.entries(args)) {