akanjs 3.0.0-beta.9 → 3.0.1

package/signal/mcp/McpDocument.ts

@@ -1,4 +1,4 @@
-import { isMcpDescribableArg, mcpHintsOf, mcpRefusalOf } from "akanjs/common";
+import { isMcpDescribableArg, lowerlize, mcpHintsOf, mcpRefusalOf } from "akanjs/common";
 import { FetchClient } from "akanjs/fetch";
 import { type AgentCandidate, AgentCatalogue, type AgentRefusal, type AgentUndescribed } from "../agent";
 import { type JsonSchema, JsonSchemaBuilder } from "../schema";
@@ -9,18 +9,11 @@ import type { McpResource, McpResourceTemplate, McpTool, McpToolAnnotations } fr
 export interface McpDocumentOptions {
   resolveDescription?: (key: string) => string | undefined;
   excludeSignals?: string[];
-  /**
-   * Drops every mutation from the catalogue regardless of what it opted into. Off by default: the endpoint's own
-   * an endpoint's guards are the decision, and a second switch that silently unlists a published endpoint gives
-   * its author no way to see why. This is the read-only-deployment valve.
-   */
+  /** Drops every mutation from the catalogue whatever its guards allow. Off by default. */
   readOnly?: boolean;
   /**
-   * How much of a result's shape a tool advertises. `shallow`, the default, publishes the returned model with every
-   * field of its own and names each nested model instead of inlining it: on a fully open catalogue 83% of the bytes
-   * were the same model schemas re-inlined per entry, most of them nested closures. `full` inlines the closure the
-   * way a shared component section would. `none` publishes no `outputSchema` at all — results still ship as
-   * `structuredContent` — for a deployment that would rather spend the bytes per call.
+   * `shallow` (default) names each nested model instead of inlining it, `full` inlines the closure, `none` publishes
+   * no `outputSchema` (results still ship as `structuredContent`).
    */
   outputSchema?: McpOutputSchemaMode;
 }
@@ -35,14 +28,9 @@ export interface McpExposedEndpoint {
   endpoint: SerializedEndpoint;
 }
 
-/**
- * A candidate this catalogue did not publish. The bookkeeping is audience-independent and lives on
- * `AgentCatalogue`; these are the MCP names for it.
- */
 export type McpRefusal = AgentRefusal;
 export type McpUndescribed = AgentUndescribed;
 
-/** What one signal contributes to a listing, so a catalogue that grew can say where it grew. */
 export interface McpSignalCost {
   refName: string;
   entries: number;
@@ -54,34 +42,21 @@ export interface McpListingCost {
   bySignal: McpSignalCost[];
 }
 
-/**
- * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
- * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
- */
 export class McpDocument {
-  /**
-   * An array cannot be `structuredContent` — the spec types it as an object — so a list result is wrapped under
-   * this key and `outputSchema` is shaped to match. Both halves must agree, which is why they live together.
-   */
+  /** The spec types `structuredContent` as an object, so a list result is wrapped under this key. */
   static readonly listKey = "items";
 
   readonly tools: McpTool[];
   readonly resourceTemplates: McpResourceTemplate[];
   /** Every readable thing is addressed by a template, so there are no fixed resources to enumerate. */
   readonly resources: McpResource[] = [];
-  /**
-   * Every candidate that was not published, with the sentence saying why — the rejections are fail-closed by
-   * design, and an author whose endpoint is missing otherwise has nowhere to look but the framework source.
-   */
   readonly refusals: McpRefusal[];
-  /** What is published with no description of its own, which is the field a model picks a tool by. */
   readonly undescribed: McpUndescribed[];
-  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/", nullable: "type" });
+  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/", nullable: "type", face: "agent" });
   readonly #modelSchemas = new Map<McpSchemaSide, Record<string, JsonSchema>>();
   readonly #options: McpDocumentOptions;
   readonly #catalogue: AgentCatalogue;
   readonly #byToolName = new Map<string, McpExposedEndpoint>();
-  /** Keyed by endpoint key: what is addressable, and by exactly which uri. */
   readonly #templates = new Map<string, string>();
   #cost: McpListingCost | null = null;
 
@@ -99,14 +74,6 @@ export class McpDocument {
     this.undescribed = this.#catalogue.undescribed;
   }
 
-  /**
-   * Roughly what a `tools/list` costs the caller, and which signals it went to.
-   *
-   * Worth reporting because the number is nobody's intuition: MCP has no shared component section and forbids a
-   * `$ref` across entries, so every entry inlines the schema of every model it mentions — under `outputSchema:
-   * "full"` a plain 21-field model with one named slice ships 12KB across its eight entries, three quarters of it
-   * the same four schemas repeated. A catalogue is re-sent whole to every agent that connects, before its first turn.
-   */
   get listingCost(): McpListingCost {
     if (this.#cost) return this.#cost;
     const bySignal = new Map<string, McpSignalCost>();
@@ -126,20 +93,12 @@ export class McpDocument {
     return this.#byToolName.get(name);
   }
 
-  /**
-   * The uri `resources/read` answers for one call of a tool, or undefined for a tool that has no template. What a
-   * page fetched is attached to a prompt under the address an agent can read it back from.
-   */
   resourceUri(key: string, args: Record<string, unknown>): string | undefined {
     const template = this.#templates.get(key);
     return template ? McpUriTemplate.expand(template, args) : undefined;
   }
 
-  /**
-   * Resolves a URI only when the endpoint behind it was published as a template. An endpoint that was never
-   * advertised has to fail here rather than fall through to its guards: opting out of MCP means keeping a thing
-   * off the wire entirely, not merely making it refuse.
-   */
+  /** Only a published template resolves: an opted-out endpoint must be unreachable, not merely refused by guards. */
   resolveResource(uri: string) {
     const target = McpUriTemplate.parse(uri);
     if (!target || !this.#templates.has(target.endpointKey)) return null;
@@ -150,55 +109,34 @@ export class McpDocument {
   static structuredContent(endpoint: SerializedEndpoint, value: unknown) {
     if (!endpoint.returns.modelType) return undefined;
     if (endpoint.returns.arrDepth) return { [McpDocument.listKey]: value };
-
+    
     return value === null || value === undefined ? undefined : value;
   }
 
-  /**
-   * Which of the catalogue's candidates this audience takes, and in what shape.
-   *
-   * The enumeration and the naming policy are `AgentCatalogue`'s — every audience walks the same registry and
-   * holds one name per entry. What is MCP's own is only this: that every candidate is published unless a rule
-   * refuses it, and that a published one becomes a tool and sometimes an addressable uri.
-   */
   #collect(serializedSignal: Record<string, SerializedSignal>): McpExposedEndpoint[] {
     const tools: McpExposedEndpoint[] = [];
     for (const candidate of AgentCatalogue.candidates(serializedSignal, {
       excludeSignals: this.#options.excludeSignals,
     })) {
-      const item: McpExposedEndpoint = {
-        refName: candidate.refName,
-        key: candidate.key,
-        endpoint: candidate.endpoint,
-      };
-      
-      const reason = mcpRefusalOf(item.endpoint, {
-        refName: item.refName,
-        key: item.key,
-        readOnly: this.#options.readOnly,
-      });
+      const { refName, key, endpoint } = candidate;
+      const item: McpExposedEndpoint = { refName, key, endpoint };
+      const reason = mcpRefusalOf(endpoint, { refName, key, readOnly: this.#options.readOnly });
       if (reason) {
-        this.#catalogue.refuse(item.key, reason);
+        this.#catalogue.refuse(key, reason);
         continue;
       }
-      if (!this.#catalogue.claim(item.key)) continue;
-
+      if (!this.#catalogue.claim(key)) continue;
+      
       const uriTemplate = McpDocument.#addressable(candidate)
-        ? McpDocument.#uriTemplate(item.refName, item.key, item.endpoint)
+        ? McpDocument.#uriTemplate(refName, key, endpoint)
         : undefined;
-      this.#byToolName.set(item.key, item);
-      if (uriTemplate) this.#templates.set(item.key, uriTemplate);
+      this.#byToolName.set(key, item);
+      if (uriTemplate) this.#templates.set(key, uriTemplate);
       tools.push(item);
     }
     return tools;
   }
 
-  /**
-   * Whether this candidate is one of the generated reads that has an `akan://` address.
-   *
-   * Only the list side of a slice is addressable; an insight is an aggregate with nothing to point a URI at, and a
-   * custom endpoint has no generated key shape to build one from.
-   */
   static #addressable({ origin, refName, key, baseVerb }: AgentCandidate): boolean {
     if (origin === "base") return baseVerb === "get";
     if (origin === "slice") return key.startsWith(`${refName}List`);
@@ -210,7 +148,7 @@ export class McpDocument {
     
     const args = [...paramArgs, ...searchArgs, ...bodyArgs].filter(isMcpDescribableArg);
     const properties = Object.fromEntries(args.map((arg) => [arg.name, this.#argSchema(refName, key, arg)]));
-
+    
     const required = [...paramArgs, ...bodyArgs]
       .filter((arg) => isMcpDescribableArg(arg) && !arg.nullable)
       .map((arg) => arg.name);
@@ -234,7 +172,6 @@ export class McpDocument {
     if (this.#options.outputSchema === "none") return undefined;
 
     if (!endpoint.returns.modelType) return undefined;
-
     if (endpoint.returns.nullable && !endpoint.returns.arrDepth) return undefined;
     const returns = this.#schema.returns(endpoint.returns);
     const schema = endpoint.returns.arrDepth
@@ -245,22 +182,15 @@ export class McpDocument {
           additionalProperties: false,
         }
       : returns;
-
     return { ...schema, ...this.#defs(schema, "output") };
   }
 
   #defs(seed: unknown, side: McpSchemaSide) {
     const defs = this.#schema.referencedSchemas(seed, this.#modelSchemasOf(side));
-
+    
     return Object.keys(defs).length ? { $defs: defs } : {};
   }
 
-  /**
-   * Every registered model, built once per side for the whole document. Narrowing runs twice per tool — input
-   * schema and output schema — so deriving the full set inside each call rebuilt every model in the app 2N times.
-   * A request side asks for a relation's id, which is what the wire carries; a response side names a nested model
-   * unless `outputSchema: "full"` asked for the closure. Neither repeats the id pattern inside a `$defs`.
-   */
   #modelSchemasOf(side: McpSchemaSide) {
     const cached = this.#modelSchemas.get(side);
     if (cached) return cached;
@@ -268,6 +198,7 @@ export class McpDocument {
       side === "input"
         ? this.#schema.allModelSchemas({ relations: "id", idPattern: false })
         : this.#schema.allModelSchemas({
+            
             readable: true,
             relations: this.#options.outputSchema === "full" ? "inline" : "named",
             idPattern: false,
@@ -303,6 +234,6 @@ export class McpDocument {
     const argNames = endpoint.args
       .filter((arg) => (arg.type === "param" || arg.type === "search") && isMcpDescribableArg(arg))
       .map((arg) => arg.name);
-    return McpUriTemplate.list(refName, suffix ? `${suffix.charAt(0).toLowerCase()}${suffix.slice(1)}` : "", argNames);
+    return McpUriTemplate.list(refName, lowerlize(suffix), argNames);
   }
 }

package/signal/mcp/McpProgress.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
 export interface McpProgressOption {
-  /** Denominator for the ratio a client renders. Omit when the amount of work is not known up front. */
+  /** Omit when the amount of work is not known up front. */
   total?: number;
-  /** One short line describing the current step. Shown to the user, so keep it prose rather than a status code. */
+  /** Shown to the user, so write prose rather than a status code. */
   message?: string;
 }
 
@@ -12,26 +12,17 @@ export interface McpProgressReport extends McpProgressOption {
 }
 
 /**
- * The progress channel for one streamed MCP call.
- *
- * Reached through `AsyncLocalStorage` rather than a parameter so an endpoint reports progress from wherever the
- * work actually happens — a service, an adapter, a loop several frames down — without every signature between
- * here and there growing a channel argument. Outside a streamed call `report` is a no-op, so the same endpoint
- * code runs unchanged over plain HTTP, a websocket, or a test.
+ * Reached through `AsyncLocalStorage` so any frame of the work can report; outside a streamed call `report` is a
+ * no-op, so the same endpoint runs unchanged over HTTP, a websocket or a test.
  */
 export class McpProgress {
   static readonly #storage = new AsyncLocalStorage<McpProgress>();
 
-  /**
-   * Reports progress for the call running on this stack. Silent when nothing is listening, which is every call
-   * that did not ask for a stream.
-   */
   static report(progress: number, option: McpProgressOption = {}) {
     const channel = McpProgress.#storage.getStore();
     if (channel) channel.#push(progress, option);
   }
 
-  /** True while the caller is streaming, so an expensive progress message can be skipped when nobody reads it. */
   static get streaming() {
     return !!McpProgress.#storage.getStore();
   }
@@ -46,7 +37,7 @@ export class McpProgress {
   #start: (() => void) | null = null;
   #ended = false;
 
-  /** Resolves on the first report and never otherwise — a call that reports nothing has nothing to stream. */
+  /** Resolves on the first report, and never for a call that reports nothing. */
   readonly started: Promise<void>;
 
   constructor() {
@@ -55,15 +46,11 @@ export class McpProgress {
     });
   }
 
-  /**
-   * Aborted when the client closes the response stream, which is how cancellation is signalled over this
-   * transport. Long-running work may watch it; the framework cannot force an `exec` already in flight to stop.
-   */
+  /** Aborted when the client closes the response stream; an `exec` already in flight is not forced to stop. */
   get signal() {
     return this.#abort.signal;
   }
 
-  /** Yields every report until the call finishes. Buffered ones come out first, so none is lost to a late reader. */
   async *reports(): AsyncGenerator<McpProgressReport> {
 
     while (!this.#ended || this.#queue.length) {

package/signal/mcp/McpUriTemplate.ts

@@ -5,13 +5,6 @@ export interface McpResourceTarget {
   args: Record<string, string | string[]>;
 }
 
-/**
- * Two-way map between an `akan://` resource URI and the endpoint that answers it.
- *
- * Parsing is done by hand rather than through `URL`: `akan:` is a non-special scheme, and how a runtime
- * normalizes the authority of one (case, percent-decoding) is exactly where a camelCase refName like
- * `agentSession` would quietly stop matching its model.
- */
 export class McpUriTemplate {
   static readonly scheme = "akan";
   /** Reserved second segment: a model id may never take one of these values, and none is a valid ObjectId. */
@@ -20,23 +13,12 @@ export class McpUriTemplate {
   static model(refName: string) {
     return `${McpUriTemplate.scheme}://${refName}/{${refName}Id}`;
   }
-  /**
-   * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
-   * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list
-   * would be one a slice could also be called, and the two would publish the same uri with only one of them
-   * readable. `list` in the *second* segment is already reserved against a model id, so there is nothing to
-   * collide with here.
-   */
+  /** The root list is the bare `…/list`: any third-segment token could also be an author's slice key. */
   static list(refName: string, sliceKey: string, argNames: string[]) {
     const base = `${McpUriTemplate.scheme}://${refName}/list${sliceKey ? `/${sliceKey}` : ""}`;
     return argNames.length ? `${base}{?${argNames.join(",")}}` : base;
   }
 
-  /**
-   * The uri a template names for one call's arguments — the inverse of `parse`, so what a page fetched can be
-   * attached under the address an agent may read it back from. A list argument repeats its key; an absent
-   * optional one is left out.
-   */
   static expand(template: string, args: Record<string, unknown>): string {
     const queryAt = template.indexOf("{?");
     const path = (queryAt === -1 ? template : template.slice(0, queryAt)).replace(/\{([^}]+)\}/g, (_, name: string) =>
@@ -75,13 +57,6 @@ export class McpUriTemplate {
     return null;
   }
 
-  /**
-   * A percent escape the decoder rejects (`akan://banner/%`) makes the uri unreadable, which is the same answer as
-   * a uri naming nothing: `resources/read` says `Unknown resource`. Left to throw, `decodeURIComponent`'s `URIError`
-   * reached the router's catch and became "the server failed" with a stack in the log — on a method an agent may
-   * call with any string it likes, so it was a log-spam path as well as a wrong verdict. The query half needs no
-   * such guard: `URLSearchParams` reads a bad escape as literal text.
-   */
   static #decode(segments: string[]) {
     try {
       return segments.map(decodeURIComponent);
@@ -90,7 +65,6 @@ export class McpUriTemplate {
     }
   }
 
-  /** Repeated keys become an array so an `arrDepth` search arg round-trips through `{?statuses}` form expansion. */
   static #searchArgs(search: URLSearchParams): Record<string, string | string[]> {
     const args: Record<string, string | string[]> = {};
     for (const key of new Set(search.keys())) {

package/signal/mcp/Msg.ts

@@ -3,20 +3,11 @@ import type { JsonSchema } from "../schema";
 
 export type PromptRole = "user" | "assistant";
 
-/**
- * What a client may do with a block when it cannot keep all of them.
- *
- * `priority` is the field that matters here: a prompt this server assembles is often mostly context — a document
- * embedded beside the one line asking for something — and a client with a full window drops blocks by this number
- * rather than by position. Leaving it off means every block is equally droppable, so the instruction can go and
- * the attachment stay.
- */
 export interface PromptAnnotations {
-  /** Who the block is for. A note meant only for the model is `["assistant"]`, so a UI need not render it. */
   audience?: PromptRole[];
-  /** 0 is "drop this first", 1 is "this is the point of the prompt". Anything outside the range is refused. */
+  /** 0 = drop first, 1 = the point of the prompt; omitted = as droppable as any block; outside 0..1 throws. */
   priority?: number;
-  /** ISO 8601. Lets a client tell a re-fetched resource from the copy it already holds. */
+  /** ISO 8601. */
   lastModified?: string;
 }
 
@@ -56,29 +47,18 @@ export interface PromptMessage {
   content: PromptContent;
 }
 
-/** What a `prompt()` exec may return. A bare string is the 80% case and is wrapped into one user message. */
+/** A bare string is wrapped into one user message. */
 export type PromptResult = string | PromptMessage[];
 
-/** Enough of the `File` model to link or inline it, structural so the framework does not depend on the lib. */
+/** Structural, so the framework does not depend on the lib's `File` model. */
 export interface PromptFileSource {
   url: string;
   filename?: string;
   mimetype?: string;
 }
 
-/**
- * A model class, named by the caller so an attachment can be masked by what it *is* rather than by what it still
- * carries at runtime. The same model any other audience masks by — see `mask` in `akanjs/constant`.
- */
 export type PromptModel = MaskModel;
 
-/**
- * The string fields each block type must carry, and the set of legal types at once.
- *
- * A client parses `prompts/get` against a discriminated union, so a block missing one of these is not a thinner
- * block — it matches no member and the whole reply throws on the client. `resource` carries a nested shape instead
- * and is checked on its own.
- */
 const contentFields = new Map<string, readonly string[]>([
   ["text", ["text"]],
   ["image", ["data", "mimeType"]],
@@ -88,23 +68,11 @@ const contentFields = new Map<string, readonly string[]>([
 ]);
 
 /**
- * Builds the messages a `prompt()` endpoint returns.
- *
- * Named `Msg` rather than `msg` because `akanjs/dictionary` already exports a `msg` for toasts.
- *
- * Every attachment builder carries the `user` role. Content the server assembles is context handed *to* the
- * model, which is what the user role means; an assistant-role attachment would be the server putting words in the
- * model's mouth. That is only meaningful for few-shot text, which `Msg.assistant` covers.
+ * Named `Msg` because `akanjs/dictionary` already exports a `msg`. Attachments carry the `user` role: an
+ * assistant-role attachment would put the server's words in the model's mouth.
  */
 export class Msg {
-  /**
-   * What every `prompt()` route answers with, as JSON Schema, for the app's OpenAPI document.
-   *
-   * A prompt declares `Any` on the wire, so the generated response schema was `{}` — a documented `GET` whose body
-   * the document could not describe, which is half of the agreement the HTTP route was mounted for. The shape is
-   * fixed by the protocol rather than by the endpoint, so it is written once, here: the block types and the fields
-   * each must carry come off `contentFields`, so a type added to one cannot describe itself out of the other.
-   */
+  /** JSON Schema of a prompt message for the OpenAPI document, since a prompt declares `Any` on the wire. */
   static readonly schema: JsonSchema = {
     type: "object",
     properties: {
@@ -115,7 +83,6 @@ export class Msg {
           properties: {
             type: { const: type },
             ...Object.fromEntries(fields.map((field) => [field, { type: "string" }])),
-
             ...(type === "resource"
               ? {
                   resource: {
@@ -153,12 +120,8 @@ export class Msg {
   }
 
   /**
-   * Embeds the value itself. The payload travels in the prompt, so prefer `link` for anything large.
-   *
-   * Name the model it is an instance of and the `hidden`/`secret` fields are stripped before it goes out:
-   * `Msg.resource(uri, order, { model: cnst.Order })`. A payload you assembled yourself needs no model and is
-   * embedded as given — but one that still carries a document's secret fields is refused rather than sent, so
-   * the rule is the same either way: a document travels masked, or it does not travel.
+   * Naming the `model` strips its `hidden`/`secret` fields; an unnamed payload that still carries populated ones
+   * throws rather than being sent.
    */
   static resource(
     uri: string,
@@ -176,33 +139,13 @@ export class Msg {
   }
 
   /**
-   * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the
-   * value happens to still carry.
-   *
-   * That distinction is the whole fix. A check that reads the class off the value can only mask what arrives as an
-   * instance, so a `{ ...doc }` spread, a `toJSON()`, or a round-trip through `JSON.stringify` reached the wire
-   * with the metadata already gone and nothing could be done about it. A named model is metadata the value cannot
-   * lose, so a hydrated document and a plain object copied out of one mask identically.
-   *
-   * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every
-   * relation it walks past, which is right for a query's return value and wrong for an attachment, where it would
-   * turn embedding one document into a fan of queries nobody asked for. So a populated relation is masked in
-   * place and one that is still an id is left as an id.
-   *
-   * Public because a payload can be an assembly of several documents — `{ order, customer }` names no single
-   * model, so each piece is masked on its way in.
-   *
-   * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type still
-   * promises. The value's only destination is a JSON payload, so nothing downstream wanted the type anyway.
+   * Masks by the named model rather than the value's class, which a spread or a JSON round-trip loses. Unlike
+   * `resolveReturn` it loads no relation: a populated one is masked in place, an id stays an id.
    */
   static mask(model: PromptModel, value: unknown): unknown {
     return mask(model, value);
   }
 
-  /**
-   * Points at something without paying for it. The client decides whether to fetch, and skips what it already
-   * holds — so a prompt that references twenty documents costs twenty URIs rather than twenty payloads.
-   */
   static link(
     source: string | PromptFileSource,
     { name, description, ...annotations }: { name?: string; description?: string } & PromptAnnotations = {},
@@ -224,13 +167,6 @@ export class Msg {
     };
   }
 
-  /**
-   * Never absent, because the spec's `name` is required and a client SDK parses the block against a union it then
-   * matches nothing in — a link with no name is not a nameless link, it is a `prompts/get` that throws.
-   *
-   * The last path segment is the fallback rather than the whole URI: for `akan://order/42` it is the identifier a
-   * person reading the list would use, and for a file URL it is the filename we would have used anyway.
-   */
   static #linkName(uri: string, name?: string) {
     if (name) return name;
     const segment = uri.split(/[?#]/)[0]?.split("/").filter(Boolean).pop();
@@ -245,11 +181,7 @@ export class Msg {
     return { role: "user", content: Msg.#annotated({ type: "audio", data, mimeType }, annotations) };
   }
 
-  /**
-   * Inlines a file as base64, costing roughly 1.33× its bytes in the prompt. Worth it only when the client
-   * cannot fetch the URL itself — a public asset is cheaper as `Msg.link`. Fetched as this process, so a file
-   * behind a caller-scoped signed URL needs its bytes passed to `Msg.image` instead.
-   */
+  /** Fetched as this process, so a file behind a caller-scoped signed URL needs its bytes passed to `Msg.image`. */
   static async imageOf(file: PromptFileSource, annotations?: PromptAnnotations): Promise<PromptMessage> {
     const response = await fetch(file.url, { signal: AbortSignal.timeout(20_000) });
     if (!response.ok) throw new Error(`Failed to inline ${file.url}: ${response.status}`);
@@ -257,34 +189,11 @@ export class Msg {
     return Msg.image(Buffer.from(await response.arrayBuffer()).toString("base64"), mimeType, annotations);
   }
 
-  /**
-   * Refuses an undeclared payload that still carries a document's secret fields, rather than sending it.
-   *
-   * A warning was the older answer, on the reasoning that masking off the value's own class would reach only the
-   * payloads that still had one — half masked, half not, and an author who believes prompts are masked is worse
-   * off on the unmasked half. `mask` removes that objection by taking the model as an argument instead, so there
-   * is now a way to be right about every payload and this is the shape that did not take it.
-   *
-   * It throws only where it can prove a leak: a value whose class says those fields exist and whose own keys say
-   * they are populated. A `Light<Model>`, or anything assembled by hand, declares no such fields and passes.
-   */
   static #assertMasked(uri: string, value: unknown) {
     for (const sample of Msg.#samples(value)) Msg.#assertSample(uri, sample);
     return value;
   }
 
-  /**
-   * The values a refusal could be about: the payload, and — when the payload is a plain object — one level into it.
-   *
-   * A list is homogeneous in practice, so its first element answers for it; walking every element to decide
-   * whether to refuse would cost more than the thing it is checking.
-   *
-   * The level down is what makes the common assembly reachable. A document rarely travels alone — it arrives as
-   * `{ order }` or `{ order, customer }` — and a plain object's own constructor carries no field metadata, so a
-   * check that stopped at the outer value saw neither the wrapper (which has nothing to show) nor what it wrapped.
-   * It stops there rather than recursing: a payload nested two deep is one somebody assembled deliberately, and no
-   * depth reaches metadata a spread has already thrown away.
-   */
   static #samples(value: unknown): Record<string, unknown>[] {
     const sample = (Array.isArray(value) ? value[0] : value) as Record<string, unknown> | null | undefined;
     if (!sample || typeof sample !== "object") return [];
@@ -304,14 +213,6 @@ export class Msg {
     );
   }
 
-  /**
-   * An empty annotation object is dropped rather than emitted: a block carrying `annotations: {}` reads to a
-   * client as a deliberate "no audience, no priority", which is not the same as saying nothing.
-   *
-   * A `priority` outside 0..1 throws instead of being clamped. The spec's range is what gives the number its
-   * meaning, and a client that meets 5 is free to ignore the field entirely — so a silent clamp would turn a
-   * typo into blocks dropped in an order nobody chose.
-   */
   static #annotated<T extends PromptContent>(content: T, annotations?: PromptAnnotations): T {
     if (!annotations || !Object.keys(annotations).length) return content;
     const { priority } = annotations;
@@ -320,11 +221,7 @@ export class Msg {
     return { ...content, annotations };
   }
 
-  /**
-   * The one runtime check on a prompt's return value. `prompt()` carries `Any` on the wire so the signal
-   * pipeline hands the value back untouched — nothing upstream would notice a malformed message, and the client
-   * would receive it as a valid prompt.
-   */
+  /** The only runtime check on a prompt's value: `prompt()` carries `Any`, so nothing upstream inspects it. */
   static normalize(value: unknown): PromptMessage[] {
     if (typeof value === "string") return [Msg.user(value)];
     if (!Array.isArray(value)) throw new Error(`A prompt must return a string or PromptMessage[], got ${typeof value}`);
@@ -334,10 +231,6 @@ export class Msg {
     return value as PromptMessage[];
   }
 
-  /**
-   * Checked down to the fields, not just the discriminator: the shapes this framework can build wrongly are all
-   * inside a block a client would then reject, and a check that stops at `content.type` cannot see any of them.
-   */
   static #assertMessage(message: unknown, idx: number) {
     const { role, content } = (message ?? {}) as { role?: unknown; content?: unknown };
     if (role !== "user" && role !== "assistant") throw new Error(`Prompt message ${idx} has role "${String(role)}"`);
@@ -350,7 +243,6 @@ export class Msg {
     Msg.#assertPriority(block.annotations, idx);
   }
 
-  /** The one nested block, and the one whose payload may arrive as either `text` or a base64 `blob`. */
   static #assertResource(resource: unknown, idx: number) {
     const { uri, text, blob } = (resource ?? {}) as Record<string, unknown>;
     if (typeof uri !== "string" || !uri) throw new Error(`Prompt message ${idx} (resource) is missing resource.uri`);
@@ -358,7 +250,6 @@ export class Msg {
       throw new Error(`Prompt message ${idx} (resource) has neither resource.text nor resource.blob`);
   }
 
-  /** Same range the builders enforce, for a message an author assembled without them. */
   static #assertPriority(annotations: unknown, idx: number) {
     const priority = (annotations as { priority?: unknown } | null)?.priority;
     if (priority === undefined) return;

package/signal/mcp/mcpProtocol.ts

@@ -1,17 +1,5 @@
-/**
- * Wire vocabulary for the MCP revisions this server answers.
- *
- * `2026-07-28` made the protocol stateless — no `initialize`, no session id, no server-opened stream — which is
- * what makes a single `POST /mcp` route sufficient. Everything before it is the *legacy* era, still what shipping
- * clients speak (measured: Claude Code 2.1.226 negotiates `2025-11-25`), and supporting it costs almost nothing
- * here because a legacy server *may* decline to issue `Mcp-Session-Id`: without one the client sends no session
- * header and never asks to resume a stream, so both eras run over the same stateless handler.
- *
- * `2025-06-18` is listed for the same reason. The surface this server actually implements — POST-only Streamable
- * HTTP, no sessions, no server-initiated requests — is wire-identical between the two legacy revisions, and a
- * client that proposes a version the server does not list is told to disconnect. Naming only the one revision that
- * was measured turned "we tested against this" into "we refuse everything else".
- */
+
+
 export const MCP_MODERN_VERSION = "2026-07-28";
 export const MCP_LEGACY_VERSION = "2025-11-25";
 export const MCP_LEGACY_PRIOR_VERSION = "2025-06-18";
@@ -27,14 +15,6 @@ export const MCP_META_CLIENT_CAPABILITIES = `${MCP_META_PREFIX}clientCapabilitie
 export const MCP_META_CLIENT_INFO = `${MCP_META_PREFIX}clientInfo`;
 export const MCP_META_SERVER_INFO = `${MCP_META_PREFIX}serverInfo`;
 
-/**
- * `-32020`..`-32099` is reserved by the spec, so nothing outside this table may be minted in that band.
- * `-32002` (resource not found) is retired in the modern revision; unknown resources are `invalidParams`.
- *
- * The band also defines `-32021 missingRequiredClientCapability`, which is absent because this server requires
- * none: it never samples, elicits, or reads roots. It belongs here the day one of those appears, not before — a
- * constant nothing emits reads as a check someone forgot to write.
- */
 export const McpErrorCode = {
   parse: -32700,
   invalidRequest: -32600,
@@ -93,10 +73,7 @@ export interface McpPromptArgument {
   required?: boolean;
 }
 
-/**
- * A prompt is user-controlled — the client offers it as a slash command and the model never invokes it — so its
- * `title` and `description` are read by a person, not inferred from a schema the way a tool's are.
- */
+/** User-controlled: a client offers it as a slash command, so a person reads its `title` and `description`. */
 export interface McpPrompt {
   name: string;
   title?: string;