akanjs 3.0.0-beta.3 → 3.0.0-beta.30

package/server/logging/logForwarder.ts

@@ -9,30 +9,22 @@ export interface LogForwarderOptions {
   maxMessageChars?: number;
 }
 
-/**
- * The child side of the log channel: a Logger sink that batches records over IPC to whoever owns the hub.
- * Installed only while the owner has asked for a level (`log.level`), so a process nobody is watching sends
- * nothing; `AKAN_LOG_STREAM=1` keeps it on regardless.
- */
 export class LogForwarder {
   static readonly defaultFlushMs = 20;
   static readonly defaultMaxRecords = 64;
-  /**
-   * Bun IPC loses a message outright when the sender exits soon after and the payload is large — measured from
-   * 16KB for one long string — and a small message queued behind it dies with it. Batches stay well under that.
-   */
   static readonly defaultMaxBytes = 32 * 1024;
   static readonly defaultMaxQueue = 1_000;
   static readonly defaultMaxMessageChars = 16 * 1024;
+  static readonly #closeTimeoutMs = 1_000;
 
-  readonly #send: (message: AkanIpcMessage) => void;
+  readonly #send: (message: AkanIpcMessage, onSent?: () => void) => void;
   readonly #flushMs: number;
   readonly #maxRecords: number;
   readonly #maxBytes: number;
   readonly #maxQueue: number;
   readonly #maxMessageChars: number;
   readonly #alwaysOn = process.env.AKAN_LOG_STREAM === "1";
-  /** In an ndjson deployment this process writes nothing itself, so what the stdout level admits must go up. */
+  
   readonly #baseSev: number | null = Logger.isNdjson ? logSeverity[Logger.level] : null;
   #queue: LogRecord[] = [];
   #dropped = 0;
@@ -40,7 +32,7 @@ export class LogForwarder {
   #removeSink: (() => void) | null = null;
   #minSev: number | null = null;
 
-  constructor(send: (message: AkanIpcMessage) => void, options: LogForwarderOptions = {}) {
+  constructor(send: (message: AkanIpcMessage, onSent?: () => void) => void, options: LogForwarderOptions = {}) {
     this.#send = send;
     this.#flushMs = options.flushMs ?? LogForwarder.defaultFlushMs;
     this.#maxRecords = options.maxRecords ?? LogForwarder.defaultMaxRecords;
@@ -50,7 +42,6 @@ export class LogForwarder {
     if (this.minSev !== null) this.setMinSev(null);
   }
 
-  /** The severity floor in force, or `null` when nothing is forwarded. */
   get minSev(): number | null {
     const base = this.#alwaysOn ? 0 : this.#baseSev;
     if (base === null) return this.#minSev;
@@ -61,10 +52,6 @@ export class LogForwarder {
     return this.#removeSink !== null;
   }
 
-  get dropped() {
-    return this.#dropped;
-  }
-
   setMinSev(minSev: number | null) {
     this.#minSev = minSev;
     const floor = this.minSev;
@@ -79,7 +66,6 @@ export class LogForwarder {
     });
   }
 
-  /** Enqueues a record this process produced or relays for one below it; dropped when nobody is listening. */
   push(record: LogRecord) {
     const floor = this.minSev;
     if (floor === null) return;
@@ -97,9 +83,10 @@ export class LogForwarder {
     for (const record of records) this.push(record);
   }
 
-  flush() {
+  flush(onSent?: () => void) {
     if (this.#timer) clearTimeout(this.#timer);
     this.#timer = null;
+    if (!this.#queue.length) onSent?.();
     while (this.#queue.length) {
       const batch: LogRecord[] = [];
       let bytes = 0;
@@ -113,14 +100,24 @@ export class LogForwarder {
       }
       const dropped = this.#dropped;
       this.#dropped = 0;
-      this.#send({ type: "log.records", records: batch, ...(dropped ? { dropped } : {}), pid: process.pid });
+      this.#send(
+        { type: "log.records", records: batch, ...(dropped ? { dropped } : {}), pid: process.pid },
+        this.#queue.length ? undefined : onSent,
+      );
     }
   }
 
-  close() {
+  close(): Promise<void> {
     this.#removeSink?.();
     this.#removeSink = null;
-    this.flush();
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, LogForwarder.#closeTimeoutMs);
+      timer.unref?.();
+      this.flush(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
   }
 
   #clip(record: LogRecord): LogRecord {

package/server/logging/logQuery.ts

@@ -1,6 +1,6 @@
 import { Logger, type LogLevelInput, type LogRecord, logSeverity } from "akanjs/common";
 
-/** Fields AND together; a list inside a field is an OR. One shape serves live tail, history and the SSE query string. */
+/** Fields AND together; a list inside a field is an OR. */
 export interface LogQuery {
   minSev?: number;
   text?: string;
@@ -30,7 +30,7 @@ export class LogQueryMatcher {
 
   matches(record: LogRecord): boolean {
     const q = this.query;
-
+    
     if (q.minSev !== undefined && (record.level === null || (record.sev < q.minSev && !Logger.isPromoted(record))))
       return false;
     if (q.text !== undefined && !record.message.includes(q.text)) return false;
@@ -49,7 +49,7 @@ export class LogQueryMatcher {
     return true;
   }
 
-  /** `*` is the only wildcard: `mutation:*`, `*:userList`. Everything else is literal. */
+  /** `*` is the only wildcard (`mutation:*`, `*:userList`); everything else is literal. */
   static compileGlob(pattern: string): RegExp {
     const source = pattern
       .split("*")
@@ -75,10 +75,7 @@ export class LogQueryMatcher {
     return level in logSeverity ? logSeverity[level] : undefined;
   }
 
-  /**
-   * Reads a query off `URLSearchParams` or a parsed JSON object. Lists accept repeated keys and comma-separated
-   * values; `level=warn` is sugar for `minSev`; `since` accepts a duration.
-   */
+  /** Lists take repeated keys or comma-separated values; `level` is sugar for `minSev`; `since` takes a duration. */
   static parse(input: URLSearchParams | Record<string, unknown>, now = Date.now()): LogQuery {
     const list = (key: string): string[] => {
       const raw =

package/server/logging/logStdoutWriter.ts

@@ -5,25 +5,15 @@ export interface LogStdoutWriterOptions {
   write?: (line: string) => void;
 }
 
-/**
- * The container's stdout in an ndjson deployment: one JSON record per line for everything the hub sees at or
- * above the stdout level, from this process and every one it fronts. It is the only writer — `Logger.consoleOutput`
- * is off in every server process — so a collector's parser is `json` and nothing else.
- */
 export class LogStdoutWriter {
   readonly #write: (line: string) => void;
   #subscription: { unsubscribe(): void } | null;
 
   constructor(hub: LogHub, { minSev, write }: LogStdoutWriterOptions) {
-    this.#write =
-      write ??
-      ((line) => {
-        process.stdout.write(line);
-      });
+    this.#write = write ?? ((line) => void process.stdout.write(line));
     this.#subscription = hub.subscribe({ minSev }, (entry) => this.#write(LogStdoutWriter.line(entry)));
   }
 
-  /** `seq` rides along: `at` comes from several clocks, so it is what orders records from different processes. */
   static json(entry: LogHubEntry) {
     return { seq: entry.seq, ...entry.record };
   }

package/server/logging/logStreamRoute.ts

@@ -1,18 +1,9 @@
 import { timingSafeEqual } from "node:crypto";
-import { EventStream } from "../routing/eventStream";
+import { EventStream } from "akanjs/common";
 import type { LogHub, LogHubEntry } from "./logHub";
 import { LogQueryMatcher } from "./logQuery";
 import { LogStdoutWriter } from "./logStdoutWriter";
 
-/**
- * `GET /_akan/app/logs?level=warn&endpoint=mutation:*` — the hub as a `text/event-stream`, for a monitor watching
- * one process from outside the pod. Every event carries the hub `seq` as its `id:`, so a client that reconnects
- * with `Last-Event-ID` gets what it missed while the ring still holds it, and an explicit gap event when it does
- * not — never a silent skip a monitor would read as a quiet interval.
- *
- * The route exists only when `AKAN_LOG_STREAM_TOKEN` is set, and answers only a matching bearer token. It logs
- * nothing itself: a stream that logged its own subscriptions at the level it delivers would feed on itself.
- */
 export class LogStreamRoute {
   static readonly path = "/_akan/app/logs";
   static readonly retryMs = 2_000;
@@ -37,8 +28,7 @@ export class LogStreamRoute {
       return new Response("Unauthorized", { status: 401, headers: { "www-authenticate": "Bearer" } });
     const hub = this.#hub();
     if (!hub) return new Response("Log hub is not running", { status: 503 });
-    const url = new URL(req.url);
-    const query = LogQueryMatcher.parse(url.searchParams);
+    const query = LogQueryMatcher.parse(new URL(req.url).searchParams);
     const matcher = new LogQueryMatcher(query);
     let subscription: { unsubscribe(): void } | null = null;
     const stream = new EventStream(
@@ -49,8 +39,8 @@ export class LogStreamRoute {
       { keepAliveMs: LogStreamRoute.heartbeatMs, keepAliveChunk: ": heartbeat\n\n" },
     );
     stream.retry(LogStreamRoute.retryMs);
-    const lastEventId = LogStreamRoute.#lastEventId(req);
-    if (lastEventId !== null) LogStreamRoute.#resume(hub, stream, matcher, lastEventId);
+    const lastEventId = req.headers.get("last-event-id")?.trim();
+    if (lastEventId && /^\d+$/.test(lastEventId)) LogStreamRoute.#resume(hub, stream, matcher, Number(lastEventId));
     subscription = hub.subscribe(query, (entry) => LogStreamRoute.#send(stream, entry));
     return stream.response();
   }
@@ -63,13 +53,6 @@ export class LogStreamRoute {
     return presented.length === this.#token.length && timingSafeEqual(presented, this.#token);
   }
 
-  static #lastEventId(req: Request): number | null {
-    const value = req.headers.get("last-event-id");
-    if (value === null || !/^\d+$/.test(value.trim())) return null;
-    return Number(value.trim());
-  }
-
-  /** What arrived after `lastEventId`, preceded by a gap event when the ring no longer reaches back that far. */
   static #resume(hub: LogHub, stream: EventStream, matcher: LogQueryMatcher, lastEventId: number) {
     if (lastEventId > hub.seq) {
       

package/server/logging/logTailClient.ts

@@ -8,8 +8,6 @@ export interface LogTailHandlers {
   onClose?: () => void;
 }
 
-type Pending = { resolve: (response: LogControlResponse) => void; reject: (error: Error) => void };
-
 /** Says the app is not running at all, as opposed to a request that failed once connected. */
 export class LogControlUnavailableError extends Error {
   readonly socketPath: string;
@@ -20,11 +18,6 @@ export class LogControlUnavailableError extends Error {
   }
 }
 
-/**
- * The client half of `LogControlSocket`: `akan logs` and the console's `.tail` both speak through it. Records
- * stream to `onRecord`; every other line answers the oldest request still waiting, in order, because the
- * socket answers in order.
- */
 export class LogTailClient {
   static socketPath(runtimeDir: string) {
     return LogControlSocket.pathIn(runtimeDir);
@@ -63,7 +56,7 @@ export class LogTailClient {
   }
 
   readonly #handlers: LogTailHandlers;
-  readonly #pending: Pending[] = [];
+  readonly #pending: { resolve: (response: LogControlResponse) => void; reject: (error: Error) => void }[] = [];
   #socket: Bun.Socket<undefined> | null = null;
   #inbox = "";
   #closed = false;

package/server/logging/rotatingLogWriter.ts

@@ -122,12 +122,10 @@ export class RotatingLogWriter {
   async #createState(processKey: string, date: string): Promise<RotatingLogWriterState> {
     const sequence = await this.#getNextSequence(processKey, date);
     const filePath = this.#getFilePath(processKey, date, sequence);
-    let sizeBytes = 0;
-    try {
-      sizeBytes = (await stat(filePath)).size;
-    } catch {
-      sizeBytes = 0;
-    }
+    const sizeBytes = await stat(filePath).then(
+      (file) => file.size,
+      () => 0,
+    );
     return { date, sequence, sizeBytes };
   }
 

package/server/mcp/McpAuth.ts

@@ -4,26 +4,17 @@ import { clientAddressFromHeaders } from "akanjs/common";
 import type { HttpRoutes } from "../types";
 
 export interface McpAuthOption {
-  /**
-   * Where a client may obtain a token, published in the metadata document for it to discover. Naming one also
-   * makes a credential mandatory: an MCP client begins its OAuth flow only on a 401, so a server that let an
-   * anonymous `initialize` succeed would leave it connected to the anonymous shelf and never asking.
-   */
+  /** Naming any makes a credential mandatory: an MCP client starts its OAuth flow only on a 401. */
   authorizationServers?: string[];
-  /** Scopes every call must carry. Declaring any turns `insufficient_scope` enforcement on. */
+  /** Declaring any turns `insufficient_scope` enforcement on. */
   scopes?: string[];
   /** Overrides the resource identifier when the public URL differs from what the request reports. */
   resource?: string;
-  /**
-   * Verifies a bearer token's signature and returns its claims, or `null` for one this server did not mint. The
-   * framework holds no signing key, so the module that issues tokens supplies this through `option.setMcp`; without
-   * it the claims are read unverified and a forged token degrades to an anonymous caller instead of being refused.
-   */
+  /** Claims, or `null` to refuse. Unset: claims are read unverified, so a forged token degrades to anonymous. */
   verify?: (token: string) => PromiseOrObject<Record<string, unknown> | null>;
 }
 
 export interface McpAuthProps extends McpAuthOption {
-  /** Path the MCP endpoint is mounted at. Its absolute URL is this server's OAuth resource identifier. */
   path: string;
 }
 
@@ -33,13 +24,6 @@ interface McpAuthFailure {
   description: string;
 }
 
-/**
- * The OAuth 2.1 protected-resource half of the MCP authorization spec: the RFC 9728 metadata document, the
- * `WWW-Authenticate` challenge that points at it, and the token checks that can be made without an issuer.
- *
- * The authorization server itself is a separate project. What lives here is what a resource server owes a
- * client regardless of who mints the tokens, so wiring one up later needs no change on this side.
- */
 export class McpAuth {
   static readonly wellKnownPath = "/.well-known/oauth-protected-resource";
 
@@ -49,10 +33,6 @@ export class McpAuth {
     this.#props = props;
   }
 
-  /**
-   * Both spellings of the metadata path. RFC 9728 inserts the resource's path into the well-known URL, and MCP
-   * clients try that form first and the bare one second; serving only one leaves half the clients at a 404.
-   */
   createRoutes(): HttpRoutes {
     const handler = { GET: (req: Request) => this.#metadata(req) };
     return {
@@ -61,11 +41,6 @@ export class McpAuth {
     };
   }
 
-  /**
-   * A request that carried no credential at all gets a challenge with no `error` code — RFC 6750 §3.1 reserves
-   * the code for a credential that was presented and found wanting — so a client reads it as "authenticate",
-   * not as "your token is bad".
-   */
   unauthorized(req: Request, failure?: McpAuthFailure) {
     const status = failure?.status ?? 401;
     const description = failure?.description ?? "Authentication is required to use this MCP server.";
@@ -75,16 +50,6 @@ export class McpAuth {
     );
   }
 
-  /**
-   * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
-   *
-   * With a `verify` hook the token is checked end to end and one that fails is refused outright. Without one the
-   * claims are read **without verifying the signature**, which is sound only because every branch below can deny
-   * and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst a
-   * crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
-   * foreign token otherwise degrades to an anonymous caller, and the agent is told a tool does not exist rather
-   * than that it needs to authenticate.
-   */
   async reject(req: Request): Promise<Response | null> {
     const token = McpAuth.#bearer(req);
     if (!token) return null;
@@ -101,17 +66,11 @@ export class McpAuth {
     return failure ? this.unauthorized(req, failure) : null;
   }
 
-  /**
-   * The 401 a credential-less request gets once an authorization server is named. A server naming none keeps
-   * anonymous access, which is what a public catalogue wants; the public tools of a server naming one are still
-   * reachable, with the token the challenge sends the client off to obtain.
-   */
   challengeAnonymous(req: Request): Response | null {
     if (!this.#props.authorizationServers?.length || McpAuth.#bearer(req)) return null;
     return this.unauthorized(req);
   }
 
-  /** A verifier that throws has said no: the token is refused, never let through as an anonymous caller. */
   async #verified(token: string): Promise<Record<string, unknown> | null> {
     try {
       return (await this.#props.verify?.(token)) ?? null;
@@ -139,10 +98,6 @@ export class McpAuth {
     return null;
   }
 
-  /**
-   * Enforced only when `scopes` is configured, because this server's own tokens carry no scope claim at all —
-   * declaring one is how a deployment says its issuer mints them.
-   */
   #missingScopes(claims: Record<string, unknown>) {
     const required = this.#props.scopes ?? [];
     if (!required.length) return [];
@@ -183,12 +138,6 @@ export class McpAuth {
     return this.#props.resource ?? new URL(this.#props.path, this.publicOrigin(req)).href;
   }
 
-  /**
-   * The origin this server is known by. A configured `resource` settles it — that URL is what an authorization
-   * server issued `aud` for, so nothing a request says can be more authoritative — and only a server with none
-   * falls back to what the request reports. Every place that names the server to a client reads this: the
-   * resource identifier, the `resource_metadata` URL in the challenge, and `McpRouter`'s same-origin check.
-   */
   publicOrigin(req: Request) {
     if (this.#props.resource) {
       try {
@@ -199,19 +148,6 @@ export class McpAuth {
     return McpAuth.origin(req);
   }
 
-  /**
-   * The public origin as the request reports it, not the one the request arrived on. Behind a proxy `req.url`
-   * names the internal host the proxy dialed, and publishing that as the resource identifier is not cosmetic: an
-   * authorization server issues `aud` for the URL the *client* used, so every correctly-issued token would then
-   * fail the audience check.
-   *
-   * `x-forwarded-host` is a request header, so this is exactly as trustworthy as the edge that overwrites it, and
-   * a deployment whose edge merely appends leaves both the same-origin comparison and the audience a token is
-   * checked against to the caller. A browser cannot reach it — a custom header is not on a preflight, and the
-   * `OPTIONS` is judged on the real host — but a direct caller can. That is why `publicOrigin` prefers a
-   * configured `resource` (`AKAN_MCP_RESOURCE`, or what `libs/shared` derives from its issuer) and reads this only
-   * for a server that pinned nothing.
-   */
   static origin(req: Request) {
     const url = new URL(req.url);
     const forwarded = (header: string) => req.headers.get(header)?.split(",")[0]?.trim();
@@ -219,15 +155,6 @@ export class McpAuth {
     return `${forwarded("x-forwarded-proto") ?? url.protocol.replace(":", "")}://${host}`;
   }
 
-  /**
-   * Who a rate limit counts. A bearer token is one caller however many connections it opens: its session id,
-   * failing that its token id or subject, failing that the token itself hashed — an opaque token has nothing else.
-   * With no token the caller is the address a proxy recorded, and callers with no recorded address share one
-   * bucket, which is the right shape for a server that nothing fronts and that admits anonymous calls.
-   *
-   * Read unverified on purpose: this runs after `reject`, so a token that reaches it has already passed whatever
-   * verification the server has, and a key needs no more than that.
-   */
   static callerKey(req: Request): string {
     const token = McpAuth.#bearer(req);
     if (!token) return `ip:${clientAddressFromHeaders(req.headers) ?? "anonymous"}`;
@@ -237,13 +164,12 @@ export class McpAuth {
   }
 
   static #bearer(req: Request): string | null {
-    const [scheme, token] = (req.headers.get("authorization") ?? "").split(" ");
-    return scheme === "Bearer" && token ? token : null;
+    return /^Bearer +([^ ]+)/i.exec(req.headers.get("authorization") ?? "")?.[1] ?? null;
   }
 
   static #claims(token: string): Record<string, unknown> | null {
     const segments = token.split(".");
-
+    
     if (segments.length !== 3) return null;
     try {
       const claims: unknown = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));

package/server/mcp/McpDispatcher.ts

@@ -1,6 +1,6 @@
-import { type BackendEnv, ENDPOINT_META } from "akanjs/base";
+import { type BackendEnv, ENDPOINT_META, PrimitiveRegistry } from "akanjs/base";
 import { interpolateTranslation, Logger } from "akanjs/common";
-import { ConstantRegistry, mask } from "akanjs/constant";
+import { agentRead, ConstantRegistry, mask } from "akanjs/constant";
 import { DictionaryLookup } from "akanjs/dictionary";
 import { NoDocumentError } from "akanjs/document";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
@@ -8,53 +8,30 @@ import type { Endpoint, EndpointCls } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
 import { Exception } from "../../signal/exception";
 import type { GuardCls } from "../../signal/guard";
-import { McpDocument, McpErrorCode, type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp";
+import { McpDocument, type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp";
 import type { MiddlewareCls } from "../../signal/middleware";
 import { SignalContext } from "../../signal/signalContext";
 import { McpExecutionContext } from "./McpExecutionContext";
 
-/** Raised when the caller presented no credential at all, so the client should be told to authenticate. */
 export class McpAuthRequiredError extends Error {}
 
-/**
- * A prompt failure whose message has already been through `#message` and is safe to put on the wire.
- *
- * It carries its JSON-RPC code because a prompt has no `isError` result to put a refusal in, so the code is the
- * only place left to say whose fault it was. Without it a mistyped argument reads as `-32603 internal error`,
- * while the *missing*-argument check `prompts/get` does itself answers `-32602` — the same mistake, two codes.
- */
-
 interface McpDispatcherProps {
   registry: InjectRegistry;
   env: BackendEnv;
   live: LiveRegistry;
   middleware: Map<string, MiddlewareCls>;
-  /** The one language error text is resolved in, matching the catalogue the client was handed. */
   language?: string;
-  /**
-   * Whether a structured result also ships as serialized JSON in the text block. `true` by default, which is what
-   * the spec asks for; `false` halves what every model-returning tool costs.
-   */
   legacyTextBlock?: boolean;
 }
 
-/** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
 export class McpDispatcher {
   static readonly logger = new Logger("McpDispatcher");
 
-  /** What the text block says when the serialized duplicate is off. Read by a model, so English. */
   static readonly structuredNote = "The result is in this call's structuredContent.";
 
   readonly #props: McpDispatcherProps;
   #endpoints: Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }> | null = null;
-  /**
-   * Built on first use and then held: the merge behind it is not free, a server whose calls all succeed never
-   * needs it, and a caller that types an argument wrong drives that path as often as it likes.
-   *
-   * Not deferred for the reason the endpoint index below is. Dictionaries register at module evaluation, before
-   * any route exists — `McpRouter` builds one at boot to resolve the catalogue's own text — so a lookup made in
-   * the constructor would be correct, just paid for by every process whether or not a call ever fails.
-   */
+  
   #lookup: DictionaryLookup | null = null;
 
   constructor(props: McpDispatcherProps) {
@@ -74,20 +51,12 @@ export class McpDispatcher {
       };
     } catch (error) {
       const status = McpDispatcher.#statusOf(error);
-
+      
       if ((status === 401 || status === 403) && !req.headers.get("authorization")) throw new McpAuthRequiredError();
       return McpDispatcher.#failure(this.#message(error, status, exposed.refName));
     }
   }
 
-  /**
-   * Drops catalogue entries whose account-scoped guards refuse this caller — an anonymous agent should not be
-   * offered a shelf of admin tools it can only fail at. Entries with no such guard are kept and stopped at call
-   * time instead, so the listing is a UX filter and never the access decision.
-   *
-   * The context is deliberately not `init()`-ed: parsing arguments that a listing does not have would throw,
-   * and a resource guard reached here reads `undefined` and fails closed, which is the behaviour we want.
-   */
   async filterForAccount<T extends { name: string }>(items: T[], req: Request): Promise<T[]> {
     const index = this.#index();
 
@@ -133,7 +102,7 @@ export class McpDispatcher {
     args: Record<string, unknown>,
     req: Request,
   ) {
-
+    
     return await SignalContext.run(endpoint, endpointInfo, key, "mcp", async () => {
       const context = await new SignalContext(key, req as Bun.BunRequest, {
         ...this.#props,
@@ -146,13 +115,6 @@ export class McpDispatcher {
     });
   }
 
-  /**
-   * Built on first use and kept: nothing before a `tools/call` needs it, and a router constructed to answer one
-   * request — which tests and tooling do — should not walk the whole registry to do it. Not an ordering
-   * workaround; DI has finished filling the registry long before any route is created.
-   *
-   * Keyed by endpoint key, which is globally unique and is what MCP names a tool by.
-   */
   #index() {
     if (this.#endpoints) return this.#endpoints;
     const endpoints = new Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }>();
@@ -165,87 +127,48 @@ export class McpDispatcher {
   }
 
   #message(error: unknown, status: number | undefined, refName: string): string {
-
+    
     if (error instanceof NoDocumentError) return `No ${refName} found for the arguments given.`;
     if (status && status < 500) {
-
+      
       if (status === 401 || status === 403) return "You are not permitted to perform this action.";
       const raw = error instanceof Error ? error.message : String(error);
       
       this.#lookup ??= new DictionaryLookup(this.#props.language);
       const text = this.#lookup.text(raw);
-
       if (text) return interpolateTranslation(text, (error as { data?: Record<string, unknown> }).data);
       return raw;
     }
-
+    
     if (!SignalContext.wasReported(error))
       McpDispatcher.logger.error(`MCP call failed: ${error instanceof Error ? (error.stack ?? error.message) : error}`);
     return "The server failed to complete this request.";
   }
 
-  /**
-   * Anything without a status is treated as a crash, so the two failures an agent can trigger at will carry one:
-   * `McpArgumentError` (400) and `NoDocumentError` (404). Without them a mistyped id logged a stack and answered
-   * "the server failed", which is both a lie and a log-spam path any caller could drive.
-   */
   static #statusOf(error: unknown): number | undefined {
     const status = (error as { statusCode?: unknown } | null)?.statusCode;
     return typeof status === "number" ? status : undefined;
   }
 
-  /**
-   * The same split `#message` makes, in the currency a prompt reports failures in. `-32602` covers a not-found
-   * as well as a bad argument: this revision retired `-32002` and points resource-does-not-exist at invalid
-   * params, so the two caller mistakes share one code by the spec's own choice rather than for want of another.
-   */
-  static #codeOf(status: number | undefined) {
-    return status && status < 500 ? McpErrorCode.invalidParams : McpErrorCode.internal;
-  }
-
-  /**
-   * A structured result rides twice by default: once as `structuredContent`, once as the same JSON here, which is
-   * what the spec asks of a server for clients that predate the structured field. Every model return therefore
-   * costs the model twice what it carries, and `legacyTextBlock: false` is the deployment that has decided its
-   * clients read the structured half — the pointer keeps `content` non-empty, since a client that renders
-   * `content[0].text` and finds nothing shows an empty answer rather than a missing one.
-   */
   #content(structuredContent: unknown, value: unknown): McpToolResult["content"] {
     if (structuredContent !== undefined && this.#props.legacyTextBlock === false)
       return [{ type: "text", text: McpDispatcher.structuredNote }];
     return [{ type: "text", text: McpDispatcher.#text(structuredContent, value) }];
   }
 
-  /**
-   * The text block every result carries, whether or not a structured one goes with it.
-   *
-   * A structured result is mirrored as its JSON, which is what the spec asks for so a client with no structured
-   * support still reads the payload. A scalar return has no structured half to mirror, and encoding one as JSON
-   * spent the block on syntax: a tool returning an id answered `"507f…"`, quotes included, which a model then has
-   * to know to strip. Numbers and booleans read the same either way; only a string differs.
-   *
-   * `JSON.stringify(undefined)` is `undefined` rather than a string, so a void return would otherwise ship a
-   * content block with no `text` at all.
-   */
   static #text(structuredContent: unknown, value: unknown) {
     if (structuredContent === undefined && typeof value === "string") return value;
     return JSON.stringify(structuredContent ?? value) ?? "null";
   }
 
-  /**
-   * Strips what the return model marks `visual` — a field the page renders and no question is answered from.
-   *
-   * Done here rather than in `resolveReturn`, which every ordinary HTTP response also passes through: the point of
-   * a `visual` field is that a browser still receives it. MCP results reach an agent and nothing else, so this is
-   * where the model's own declaration is honoured, and it is the same `mask` the in-page agent's reads use.
-   */
   static #readable(exposed: McpExposedEndpoint, value: unknown): unknown {
-    const { refName, modelType } = exposed.endpoint.returns;
-    if (!modelType) return value;
+    const { refName, modelType, arrDepth = 0 } = exposed.endpoint.returns;
+    if (!modelType)
+      return PrimitiveRegistry.hasName(refName) ? agentRead(PrimitiveRegistry.get(refName), value, arrDepth) : value;
     try {
       return mask(ConstantRegistry.getModelRef(refName, modelType), value);
     } catch (error) {
-
+      
       McpDispatcher.logger.error(
         `MCP could not mask a "${refName}" (${modelType}) result, so it was not sent: ${
           error instanceof Error ? error.message : String(error)