ultra11y 2.22.0

package/src/mcp/http.ts

@@ -0,0 +1,260 @@
+import { createServer as createHttpServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { createServer as createMcpServer, type JsonRpcMessage, type ServerOptions } from "./server.js";
+import { ASSUMED_HTTP_PROTOCOL, isOriginAllowed, isProtocolVersion, type ProtocolVersion } from "./protocol.js";
+
+// The Streamable HTTP transport, in its stateless form: one endpoint, POST,
+// JSON in and JSON out.
+//
+// No Mcp-Session-Id is issued, and that is a decision rather than an omission.
+// Every ultra11y tool call is self-contained — it carries its own `repo` and
+// arguments — so there is nothing for a session to hold. Issuing one would buy
+// a class of interop bugs (echo-back, expiry, 404-then-reinitialize, DELETE
+// semantics) for no capability. Revisit only when something genuinely spans
+// calls.
+//
+// No SSE either: nothing here sends server-initiated messages, and the spec's
+// answer for a server with no stream to offer is 405 on GET, which is what this
+// does. server.ts already routes replies through a callback, so adding a stream
+// later is a change to this file alone.
+
+const MCP_PATH = "/mcp";
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const CORS_HEADERS = "content-type, accept, mcp-protocol-version, mcp-session-id, authorization, last-event-id";
+
+export interface HttpOptions extends ServerOptions {
+  port?: number;
+  bind?: string;
+  allowOrigin?: string[];
+  // Bind somewhere other than loopback. Off by default and loud when used:
+  // this server clones arbitrary git URLs and reads files off disk, so an
+  // exposed port is a fetch-anything primitive for whoever finds it.
+  allowRemote?: boolean;
+}
+
+export interface RunningHttpServer {
+  server: Server;
+  port: number;
+  url: string;
+  close(): Promise<void>;
+}
+
+const LOOPBACK_BIND = new Set(["127.0.0.1", "::1", "localhost"]);
+
+export function startHttpServer(opts: HttpOptions = {}): Promise<RunningHttpServer> {
+  const bind = opts.bind ?? "127.0.0.1";
+  if (!LOOPBACK_BIND.has(bind) && !opts.allowRemote) {
+    return Promise.reject(
+      new Error(
+        `refusing to bind ${bind}: ultra11y's MCP server clones arbitrary git URLs and reads local files. Pass --allow-remote if that is really what you want.`,
+      ),
+    );
+  }
+
+  const server = createHttpServer((req, res) => {
+    void route(req, res, opts).catch((e) => {
+      // Only if nothing was written yet: a throw after the response started
+      // (a client that hung up mid-write) must not become a second writeHead.
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      sendJson(res, 500, { jsonrpc: "2.0", id: null, error: { code: -32603, message: e instanceof Error ? e.message : String(e) } });
+    });
+  });
+
+  // A cold `ultra11y_doc` runs for minutes. Node's default 300s request timeout
+  // would cut the socket with no JSON-RPC error, which the client reports as a
+  // crashed server rather than a slow tool.
+  server.requestTimeout = 0;
+  server.headersTimeout = 60_000;
+  server.keepAliveTimeout = 120_000;
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port ?? 0, bind, () => {
+      server.removeListener("error", reject);
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : (opts.port ?? 0);
+      const host = bind.includes(":") ? `[${bind}]` : bind;
+      resolve({
+        server,
+        port,
+        url: `http://${host}:${port}${MCP_PATH}`,
+        close: () =>
+          new Promise<void>((done) => {
+            server.closeAllConnections?.();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}
+
+async function route(req: IncomingMessage, res: ServerResponse, opts: HttpOptions): Promise<void> {
+  const path = (req.url ?? "").split("?")[0];
+  const origin = header(req, "origin");
+
+  // DNS-rebinding defense first, before anything reads the body: a page the
+  // user happens to have open must not be able to drive this server.
+  if (!isOriginAllowed(origin, opts.allowOrigin)) {
+    sendJson(res, 403, { error: "origin not allowed", origin });
+    return;
+  }
+
+  if (req.method === "OPTIONS") {
+    res.writeHead(204, {
+      ...corsHeaders(origin),
+      "access-control-allow-methods": "POST, GET, DELETE, OPTIONS",
+      "access-control-allow-headers": CORS_HEADERS,
+      "access-control-max-age": "86400",
+    });
+    res.end();
+    return;
+  }
+
+  if (path !== MCP_PATH) {
+    sendJson(res, 404, { error: `not found: ${path} (the MCP endpoint is ${MCP_PATH})` }, origin);
+    return;
+  }
+
+  // GET would open the server→client SSE stream; there isn't one, and 405 is
+  // the spec's way of saying so. DELETE terminates a session; there are none.
+  if (req.method === "GET" || req.method === "DELETE") {
+    res.writeHead(405, { allow: "POST, OPTIONS", ...corsHeaders(origin) });
+    res.end(JSON.stringify({ error: `${req.method} is not supported: this server is stateless and offers no server-initiated stream` }));
+    return;
+  }
+
+  if (req.method !== "POST") {
+    res.writeHead(405, { allow: "POST, OPTIONS", ...corsHeaders(origin) });
+    res.end(JSON.stringify({ error: `${req.method} is not supported` }));
+    return;
+  }
+
+  const contentType = (header(req, "content-type") ?? "").split(";")[0]!.trim().toLowerCase();
+  if (contentType && contentType !== "application/json") {
+    sendJson(res, 415, { error: `unsupported content-type "${contentType}" — send application/json` }, origin);
+    return;
+  }
+
+  // Lenient on Accept: the spec asks clients for
+  // "application/json, text/event-stream", but rejecting the ones that send
+  // something narrower breaks real integrations and protects nothing.
+  const accept = (header(req, "accept") ?? "").toLowerCase();
+  if (accept && !/application\/json|text\/event-stream|\*\/\*/.test(accept)) {
+    sendJson(res, 406, { error: "this endpoint replies with application/json" }, origin);
+    return;
+  }
+
+  const declared = header(req, "mcp-protocol-version");
+  if (declared !== undefined && !isProtocolVersion(declared)) {
+    sendJson(res, 400, { error: `unsupported MCP-Protocol-Version: ${declared}` }, origin);
+    return;
+  }
+  // Absent means a client written against the previous revision, which never
+  // sent the header. The spec says assume, not reject.
+  const protocol: ProtocolVersion = (declared as ProtocolVersion | undefined) ?? ASSUMED_HTTP_PROTOCOL;
+
+  let raw: string;
+  try {
+    raw = await readBody(req);
+  } catch (e) {
+    if ((e as Error).message === "too large") {
+      sendJson(res, 413, { error: `request body exceeds ${MAX_BODY_BYTES} bytes` }, origin);
+      return;
+    }
+    sendJson(res, 400, { error: `could not read request body: ${(e as Error).message}` }, origin);
+    return;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    sendJson(res, 200, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }, origin);
+    return;
+  }
+
+  // A server instance per request. Stateless means the negotiated version
+  // cannot live on the server object: two overlapping requests on different
+  // protocol versions would otherwise read each other's.
+  const mcp = createMcpServer(opts);
+  mcp.setProtocolVersion(protocol);
+
+  const out: JsonRpcMessage[] = [];
+  const collect = (m: JsonRpcMessage) => void out.push(m);
+  const messages: JsonRpcMessage[] = Array.isArray(parsed) ? (parsed as JsonRpcMessage[]) : [parsed as JsonRpcMessage];
+  for (const m of messages) await mcp.handle(m, collect);
+
+  // Nothing to answer means the body held only notifications or responses —
+  // `notifications/initialized` arrives exactly this way, and a 200 with a body
+  // here is what trips strict clients.
+  if (out.length === 0) {
+    res.writeHead(202, corsHeaders(origin));
+    res.end();
+    return;
+  }
+
+  sendJson(res, 200, Array.isArray(parsed) ? out : out[0]!, origin);
+}
+
+function header(req: IncomingMessage, name: string): string | undefined {
+  const v = req.headers[name];
+  return Array.isArray(v) ? v[0] : v;
+}
+
+function corsHeaders(origin: string | undefined): Record<string, string> {
+  return origin ? { "access-control-allow-origin": origin, vary: "origin" } : {};
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown, origin?: string, extra: Record<string, string> = {}): void {
+  const text = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": String(Buffer.byteLength(text, "utf8")),
+    ...corsHeaders(origin),
+    ...extra,
+  });
+  res.end(text);
+}
+
+// How much we will read past the cap purely to reach the end of an oversized
+// request. Answering a 413 while the client is still writing reaches it as a
+// connection reset, not as our explanation — so we stop buffering, keep
+// reading, and reply once the request is actually over. Past this ceiling the
+// body is not a mistake and we stop humouring it.
+const DRAIN_LIMIT = MAX_BODY_BYTES * 8;
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let over = false;
+
+    const declared = Number(req.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) over = true;
+
+    req.on("data", (c: Buffer) => {
+      size += c.length;
+      if (over) {
+        if (size > DRAIN_LIMIT) {
+          req.destroy();
+          reject(new Error("too large"));
+        }
+        return;
+      }
+      if (size > MAX_BODY_BYTES) {
+        over = true;
+        chunks.length = 0;
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      if (over) reject(new Error("too large"));
+      else resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+    req.on("aborted", () => reject(new Error("client aborted the request")));
+  });
+}

package/src/mcp/prompts.ts

@@ -0,0 +1,183 @@
+import { TOOLS, WRITE_TOOLS } from "./tools.js";
+
+// The workflows, as MCP prompts.
+//
+// Tools are the half of this skill a client can discover on its own. The other
+// half is the coverage arithmetic: of the 55 WCAG 2.2 AA success criteria, the
+// static engine decides a handful, a real browser decides fourteen, and the
+// remaining thirty-eight are judgment calls only the model can make. A client
+// handed the audit tool and no protocol runs it, sees no errors, and reports
+// the page as accessible — which is a false conformance claim, the one output
+// an accessibility tool must never produce.
+//
+// Each prompt says three things, in this order: the contract, the exact tool
+// sequence, and what the gate does on failure.
+
+export interface PromptArgument {
+  name: string;
+  description: string;
+  required?: boolean;
+}
+
+export interface PromptDecl {
+  name: string;
+  title?: string;
+  description: string;
+  arguments: PromptArgument[];
+}
+
+export interface PromptMessage {
+  role: "user" | "assistant";
+  content: { type: "text"; text: string };
+}
+
+export interface PromptResult {
+  description: string;
+  messages: PromptMessage[];
+}
+
+export class PromptError extends Error {}
+
+const cwdArg: PromptArgument = { name: "cwd", description: "Absolute path to the project root.", required: true };
+
+export const PROMPTS: PromptDecl[] = [
+  {
+    name: "audit_wcag",
+    title: "Audit a project against WCAG 2.2 AA",
+    description:
+      "The full conformance workflow: run the static engine, adjudicate the criteria it cannot decide, name the ones only a browser can settle, and produce " +
+      "a dated report whose coverage is stated rather than implied.",
+    arguments: [
+      cwdArg,
+      { name: "globs", description: "What to audit, comma-separated (default: the project's markup).", required: false },
+      { name: "standard", description: "wcag (default) or rgaa.", required: false },
+    ],
+  },
+  {
+    name: "adjudicate_criteria",
+    title: "Decide the criteria the engine cannot",
+    description:
+      "The judgment workflow: work the adjudication queue — alt-text relevance, link purpose in context, heading structure, reading order — by reading the " +
+      "real markup, not by pattern-matching the element.",
+    arguments: [cwdArg, { name: "standard", description: "wcag (default) or rgaa.", required: false }],
+  },
+  {
+    name: "review_diff_a11y",
+    title: "Review a diff for accessibility",
+    description:
+      "The review workflow: audit exactly the code under change, refute the false positives, and report what this diff introduces — not the project's whole " +
+      "accessibility backlog.",
+    arguments: [cwdArg, { name: "since", description: "The git ref to diff against (default: the staged changes).", required: false }],
+  },
+];
+
+export function getPrompt(name: string, args: Record<string, unknown> = {}): PromptResult {
+  const decl = PROMPTS.find((p) => p.name === name);
+  if (!decl) throw new PromptError(`unknown prompt: ${name || "(none given)"}`);
+
+  for (const arg of decl.arguments) {
+    if (arg.required && !str(args[arg.name])) throw new PromptError(`\`${arg.name}\` is required for prompt "${name}"`);
+  }
+
+  const text = name === "audit_wcag" ? auditWcag(args) : name === "adjudicate_criteria" ? adjudicateCriteria(args) : reviewDiff(args);
+  return { description: decl.description, messages: [{ role: "user", content: { type: "text", text } }] };
+}
+
+// The rule every workflow here rests on. Stated once, quoted into each prompt,
+// so the two can never drift apart.
+const CORE_RULE = `A criterion nobody tested is UNTESTED, never conformant. The static engine decides only a handful of the 55 WCAG 2.2 AA criteria; fourteen need a real browser and thirty-eight need your judgment. Never write that a criterion passes because the tool did not flag it, and never invent a non-conformity the evidence does not show.`;
+
+const GATE = `\`ultra11y_check\` returning \`ok: false\` is a VERDICT, not a tool failure. It means the report claims more than the evidence carries — usually a criterion asserted conformant that was never actually tested. Fix the claim, not the gate.`;
+
+function auditWcag(args: Record<string, unknown>): string {
+  const cwd = str(args.cwd)!;
+  const globs = str(args.globs);
+  const standard = str(args.standard);
+
+  return `Audit \`${cwd}\` against ${standard === "rgaa" ? "RGAA" : "WCAG 2.2 AA"}${globs ? `, over \`${globs}\`` : ""}.
+
+${CORE_RULE}
+
+**Sequence:**
+
+1. \`ultra11y_audit\`${globs ? ` with \`globs: ["${globs}"]\`` : ""} — the static pass. Add \`graph: true\` for a component codebase, where a label is routinely defined in a different file from the input it names.
+2. \`ultra11y_adjudicate\` — the queue of criteria the engine cannot decide. This is most of WCAG, and skipping it is what turns an audit into a lint run.
+3. For each item: \`ultra11y_read\` the real markup around it and rule on it. \`ultra11y_criteria\` when you need the criterion's exact wording — look it up rather than recalling it, which is how invented non-conformities get written.
+4. \`ultra11y_report\`${standard ? ` with \`standard: "${standard}"\`` : ""} for the dated conformance report.
+5. \`ultra11y_check\` on what you wrote.
+
+**Say what you did not test.** The rendering criteria — contrast, focus visibility, zoom, reflow, hover, target size — cannot be decided from source. They need \`ultra11y scan\` in a real browser, from the CLI. A report that omits them silently reads as a clean bill of health for the very criteria most likely to fail.
+
+**Then \`ultra11y_prd\`** to turn the non-conformities into work a team can pick up, with the fix and the effort per unit.
+
+${GATE}`;
+}
+
+function adjudicateCriteria(args: Record<string, unknown>): string {
+  const cwd = str(args.cwd)!;
+  const standard = str(args.standard);
+
+  return `Work the adjudication queue for \`${cwd}\`${standard ? ` against ${standard}` : ""}.
+
+${CORE_RULE}
+
+**Sequence:**
+
+1. \`ultra11y_adjudicate\` — the items, each naming the criterion and the element it turns on.
+2. For each: \`ultra11y_read\` the file around that element. You are deciding what the markup MEANS in context, and context is exactly what an excerpt drops.
+3. \`ultra11y_criteria\` for the criterion's exact test, whenever you are about to rule from memory.
+4. Rule on each item, then \`ultra11y_check\` your write-up.
+
+**What these criteria actually ask.**
+
+- **Alt text** — does it convey what the image contributes HERE? A correct-looking alt on a decorative image is a failure; so is "chart" on a chart carrying the paragraph's only data.
+- **Link purpose in context** — could a user reading links out of context tell where this one goes? "Read more" fails unless its context is programmatically associated.
+- **Heading structure** — do the headings describe the real outline of the page, or the visual size someone wanted?
+- **Reading order** — does the DOM order match the meaning, independent of CSS placement?
+- **Label in name** — does the accessible name start with the visible label, so a speech user can say what they see?
+
+**When the evidence does not settle it, say so.** "Needs a human with the design context" is a legitimate verdict and a useful one. A confident wrong ruling is neither.`;
+}
+
+function reviewDiff(args: Record<string, unknown>): string {
+  const cwd = str(args.cwd)!;
+  const since = str(args.since);
+
+  return `Review the ${since ? `changes since \`${since}\`` : "staged changes"} in \`${cwd}\` for accessibility.
+
+${CORE_RULE}
+
+**Sequence:**
+
+1. \`ultra11y_audit\` with ${since ? `\`since: "${since}"\`` : "`staged: true`"} and \`graph: true\` — scoped to exactly the code under change, but able to see across files.
+2. \`ultra11y_read\` each flagged element in its real context before writing anything about it.
+3. \`ultra11y_criteria\` for any criterion you are about to cite.
+4. Report, ranked: blocking → major → minor.
+
+**Review the diff, not the project.** A pre-existing non-conformity in a file this branch merely touched is not this branch's finding — mention it once as context, never as a blocker.
+
+**Refute the false positives yourself.** Findings inside library source, generated output, or a single-file component the engine could not fully resolve are PRELIMINARY. Check each against the real markup and drop the ones that do not survive; a review that forwards the engine's output unfiltered wastes the author's time and teaches them to ignore the next one.
+
+**Name the residual risks.** Contrast, focus visibility and zoom cannot be judged from source — say that they were not assessed rather than letting silence imply they passed.`;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() !== "" ? v : undefined;
+}
+
+// Every tool a prompt tells the model to call must actually be declared —
+// otherwise a prompt survives a tool rename as a set of instructions that
+// cannot be followed. Exported so the test can assert it.
+const DECLARED = new Set([...TOOLS, ...WRITE_TOOLS].map((t) => t.name));
+
+export function toolNamesReferencedBy(text: string): string[] {
+  const found = new Set<string>();
+  for (const m of text.matchAll(/ultra11y_[a-z_]+/g)) if (DECLARED.has(m[0])) found.add(m[0]);
+  return [...found].sort();
+}
+
+export function unknownToolNamesIn(text: string): string[] {
+  const bad = new Set<string>();
+  for (const m of text.matchAll(/ultra11y_[a-z_]+/g)) if (!DECLARED.has(m[0])) bad.add(m[0]);
+  return [...bad].sort();
+}

package/src/mcp/protocol.ts

@@ -0,0 +1,187 @@
+// The MCP wire rules, with no knowledge of what the tools do and no I/O. Kept
+// separate from tools.ts and server.ts so the parts that are pure functions of
+// their input stay directly testable.
+//
+// Written by hand rather than pulled from @modelcontextprotocol/sdk: the shipped
+// bundle has zero runtime dependencies (design principle 2), and the surface an
+// ultra11y server needs — initialize, ping, tools/list, tools/call — is a few
+// hundred lines. The vendored codeindex engine ships the same shape at
+// src/vendor/codeindex-engine.mjs:10468; this is that shape, retargeted.
+
+// Oldest first. We answer on whichever of these the client asks for, and fall
+// back to the newest when it asks for something we don't know — the spec's
+// rule is that the server replies with a version it supports and the client
+// then decides whether it can live with it.
+export const PROTOCOL_VERSIONS = ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"] as const;
+export type ProtocolVersion = (typeof PROTOCOL_VERSIONS)[number];
+
+export const LATEST_PROTOCOL: ProtocolVersion = PROTOCOL_VERSIONS[PROTOCOL_VERSIONS.length - 1]!;
+
+// What an HTTP request without an `MCP-Protocol-Version` header means. The spec
+// (2025-06-18) says to assume this version for backwards compatibility rather
+// than reject, because clients written against the previous revision never send
+// the header at all.
+export const ASSUMED_HTTP_PROTOCOL: ProtocolVersion = "2025-03-26";
+
+// Tool `annotations` arrived in 2025-03-26; `title`, `outputSchema` and
+// `structuredContent` in 2025-06-18. Sending them to an older client is not
+// fatal but is noise it never asked for, so they are gated.
+export const ANNOTATIONS_SINCE = "2025-03-26";
+export const RICH_TOOLS_SINCE = "2025-06-18";
+
+// A tool result larger than this is withheld rather than sent as a truncated
+// payload — see capResponse.
+export const DEFAULT_MAX_RESPONSE_BYTES = 1_000_000;
+
+export function isProtocolVersion(v: unknown): v is ProtocolVersion {
+  return typeof v === "string" && (PROTOCOL_VERSIONS as readonly string[]).includes(v);
+}
+
+// Echo the client's version when we speak it, otherwise offer the newest we do.
+export function negotiateProtocol(requested: unknown): ProtocolVersion {
+  return isProtocolVersion(requested) ? requested : LATEST_PROTOCOL;
+}
+
+// --------------------------------------------------------------------------
+// Argument validation
+// --------------------------------------------------------------------------
+
+export interface JsonSchemaProp {
+  type?: "string" | "number" | "boolean" | "array" | "object";
+  items?: { type?: string };
+  enum?: readonly string[];
+  description?: string;
+}
+
+export interface JsonSchema {
+  type: "object";
+  properties: Record<string, JsonSchemaProp>;
+  required: string[];
+}
+
+// Check a tool call's arguments against its declared schema. Returns a message
+// naming the offending property, or undefined when the args are usable.
+//
+// Deliberately shallow: it enforces required-ness, scalar types, string-array
+// shape and enum membership, and it accepts a numeric string for a number
+// (several clients stringify every argument). Anything subtler is the handler's
+// job, where the error message can be about the domain rather than the schema.
+export function validateArgs(schema: JsonSchema, args: Record<string, unknown>): string | undefined {
+  for (const key of schema.required) {
+    const v = args[key];
+    if (v === undefined || v === null || v === "") return `\`${key}\` is required`;
+  }
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null) continue;
+    const spec = schema.properties[key];
+    // Unknown keys are ignored, not rejected: a client that sends an extra
+    // field should not have its call fail.
+    if (!spec?.type) continue;
+    const actual = Array.isArray(value) ? "array" : typeof value;
+
+    if (spec.type === "number") {
+      if (actual === "number") continue;
+      if (actual === "string" && (value as string).trim() !== "" && Number.isFinite(Number(value))) continue;
+      return `\`${key}\` must be a number, got ${actual === "string" ? JSON.stringify(value) : actual}`;
+    }
+
+    if (spec.type === "array") {
+      if (actual !== "array") return `\`${key}\` must be an array, got ${actual}`;
+      const arr = value as unknown[];
+      if (spec.items?.type === "string" && !arr.every((x) => typeof x === "string")) {
+        return `\`${key}\` must be an array of strings`;
+      }
+      if (spec.enum) {
+        const bad = arr.find((x) => typeof x === "string" && !spec.enum!.includes(x));
+        if (bad !== undefined) return `\`${key}\` contains "${String(bad)}" — allowed: ${spec.enum.join(", ")}`;
+      }
+      continue;
+    }
+
+    if (actual !== spec.type) return `\`${key}\` must be a ${spec.type}, got ${actual}`;
+
+    if (spec.enum && typeof value === "string" && !spec.enum.includes(value)) {
+      return `\`${key}\` must be one of: ${spec.enum.join(", ")}`;
+    }
+  }
+  return undefined;
+}
+
+// --------------------------------------------------------------------------
+// Response size
+// --------------------------------------------------------------------------
+
+// How to ask for less, per tool. A cap that only says "too big" makes the model
+// retry the same call; one that names the narrowing argument gets a smaller
+// second call.
+const NARROWER: Record<string, string> = {
+  ultra11y_audit: "narrow the globs, or pass `max_files`; `changed: true` audits only what the diff touched",
+  ultra11y_report: "report one standard at a time, or read the file at the returned path",
+  ultra11y_prd: 'split per criterion with `split: "criterion"`',
+  ultra11y_criteria: "ask for one success criterion instead of the whole reference",
+  ultra11y_verify: "lower `max_verify`",
+  ultra11y_scan: "scan one page instead of a crawl",
+  ultra11y_read: "pass `start_line`/`end_line` to read a window instead of the whole file",
+};
+
+// Withhold an oversized payload instead of sending a partial one. A truncated
+// JSON body is worse than no body: the model cannot tell a clipped result from
+// a complete one, so it reasons over half the evidence and says nothing about
+// it. The replacement is small, structured, and says exactly how to ask again.
+export function capResponse(text: string, tool: string, maxBytes: number, artifact?: string): string {
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= maxBytes) return text;
+  return (
+    JSON.stringify(
+      {
+        truncated: true,
+        tool,
+        bytes,
+        maxBytes,
+        reason: "This response exceeds the configured limit and was withheld rather than sent as an unusable partial payload.",
+        narrower: NARROWER[tool] ?? "narrow the request and call again",
+        ...(artifact ? { artifact, artifactNote: "The full result is on disk here — read it directly if you need all of it." } : {}),
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+// `structuredContent` mirrors the text body as a typed object. Only sent when
+// the client is new enough, the tool declares an outputSchema, nothing was
+// capped, and the body really is a JSON object — a mismatch here is worse than
+// the field's absence, because clients validate it.
+export function structuredContentFor(text: string, capped: boolean, hasSchema: boolean): Record<string, unknown> | undefined {
+  if (capped || !hasSchema) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  return parsed as Record<string, unknown>;
+}
+
+// --------------------------------------------------------------------------
+// Origin checking (HTTP transport)
+// --------------------------------------------------------------------------
+
+const LOOPBACK_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+
+// DNS-rebinding defense, required by the spec's security section for a local
+// HTTP server. Without it any web page the user visits can POST to
+// 127.0.0.1:<port> and drive this server — which clones arbitrary git URLs and
+// reads files off disk.
+//
+// An absent Origin is allowed: non-browser clients (Claude Code, Cursor, curl)
+// don't send one, and a browser always does, so absence is not something an
+// attacker can use.
+export function isOriginAllowed(origin: string | undefined, allowed: string[] = []): boolean {
+  if (origin === undefined) return true;
+  const o = origin.trim();
+  if (o === "" || o === "null") return true;
+  if (LOOPBACK_ORIGIN.test(o)) return true;
+  return allowed.some((a) => a === "*" || a.toLowerCase() === o.toLowerCase());
+}