@bevel-software/platform-mcp-core 0.25.2 → 0.27.0

package/src/mcp-app.ts

@@ -0,0 +1,194 @@
+/**
+ * The MCP Apps extension (`io.modelcontextprotocol/ui`, specification
+ * 2026-01-26), as much of it as a SERVER has to speak.
+ *
+ * The pattern is two primitives tied together by one URI: a tool whose
+ * `_meta.ui.resourceUri` names a `ui://` resource, and that resource — an HTML
+ * page served under {@link MCP_APP_MIME_TYPE} — which the host renders in an
+ * iframe and then pushes the tool's result into. A host without the extension
+ * sees an ordinary tool with an ordinary text result and ignores the metadata,
+ * which is why the tool's answer must stand on its own.
+ *
+ * Deliberately no dependency: the extension's SDK would be a new package on
+ * both the server and the view, and the wire shape it would hide is the three
+ * literals below (see the Specification's Decision 10). Hexis tracks the
+ * specification by hand instead.
+ *
+ * Lives in `mcp-core` because BOTH surfaces serve the same view: the hosted
+ * proxy from the deployment it runs in, and `hexis-mcp` by fetching it from
+ * the deployment it bridges. One definition, so the two cannot drift.
+ */
+
+/** The `_meta` key the extension's metadata rides under, on a tool and on a resource alike. */
+export const MCP_APP_UI_META_KEY = 'ui';
+
+/**
+ * The media type of an MCP App view. A host that supports the extension
+ * recognises an app by this and nothing else; a non-conforming explicit type
+ * is rejected rather than coerced, so it is spelled once, here.
+ */
+export const MCP_APP_MIME_TYPE = 'text/html;profile=mcp-app';
+
+/** The `ui://` scheme every app resource's URI uses. */
+export const MCP_APP_URI_SCHEME = 'ui://';
+
+/** A tool's UI metadata: which view renders its result. */
+export interface McpAppToolUi {
+  /** The `ui://` URI of the view resource. */
+  resourceUri: string;
+}
+
+/** A view resource's UI metadata: what the host's sandbox may do with it. */
+export interface McpAppResourceUi {
+  /**
+   * What the sandbox may load from outside itself. `frameDomains` are the
+   * origins the view may put in an iframe — for Hexis, exactly the
+   * deployment's own public origin, because the view's whole job is to frame
+   * this deployment's `/embed` page.
+   */
+  csp?: {
+    frameDomains?: string[];
+    connectDomains?: string[];
+    resourceDomains?: string[];
+  };
+  /**
+   * The stable sandbox domain the host gives the view. Stable matters: the
+   * host derives the iframe's opaque origin from it, so a value that changed
+   * per render would throw away the sandbox's storage on every call.
+   */
+  domain?: string;
+  /** Whether the host should draw a border around the view. */
+  prefersBorder?: boolean;
+}
+
+/** One MCP App view, as `resources/list` and `resources/read` answer for it. */
+export interface McpAppResource {
+  /** `ui://…` — the URI a tool's `resourceUri` points at. */
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  /** Always {@link MCP_APP_MIME_TYPE}. */
+  mimeType: string;
+  /** The view's HTML. */
+  text: string;
+  ui: McpAppResourceUi;
+}
+
+/**
+ * Everything a surface needs to serve a deployment's MCP Apps: which tools
+ * carry UI metadata, and the views they name.
+ *
+ * `hexis-mcp` fetches exactly this shape over HTTP from the deployment, so
+ * the local server advertises the same apps as the hosted endpoint without
+ * knowing anything about what they render.
+ */
+export interface McpAppManifest {
+  /** Tool name → its UI metadata. */
+  tools: Record<string, McpAppToolUi>;
+  resources: McpAppResource[];
+}
+
+/** The `_meta` object a tool carrying a view advertises. */
+export function toolUiMeta(ui: McpAppToolUi): Record<string, unknown> {
+  return { [MCP_APP_UI_META_KEY]: { resourceUri: ui.resourceUri } };
+}
+
+/** The `_meta` object a view resource advertises, on both list and read. */
+export function resourceUiMeta(ui: McpAppResourceUi): Record<string, unknown> {
+  return { [MCP_APP_UI_META_KEY]: { ...ui } };
+}
+
+/** A resource's listing entry (no content), as `resources/list` returns it. */
+export function toListedResource(resource: McpAppResource): {
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType: string;
+  _meta: Record<string, unknown>;
+} {
+  return {
+    uri: resource.uri,
+    name: resource.name,
+    ...(resource.title !== undefined ? { title: resource.title } : {}),
+    ...(resource.description !== undefined ? { description: resource.description } : {}),
+    mimeType: resource.mimeType,
+    _meta: resourceUiMeta(resource.ui),
+  };
+}
+
+/**
+ * A resource's content, as `resources/read` returns it. The metadata rides
+ * the CONTENTS entry as well as the listing: a host that preloads a view
+ * straight from a tool's `resourceUri` never saw the listing, and the CSP is
+ * what decides whether its sandbox may frame anything at all.
+ */
+export function toReadResourceResult(resource: McpAppResource): {
+  contents: Array<{ uri: string; mimeType: string; text: string; _meta: Record<string, unknown> }>;
+} {
+  return {
+    contents: [
+      {
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text: resource.text,
+        _meta: resourceUiMeta(resource.ui),
+      },
+    ],
+  };
+}
+
+/**
+ * Parse a manifest off the wire (the local server's fetch from a deployment),
+ * keeping only what is well-formed. A deployment too old to serve one, or one
+ * whose answer is a proxy's HTML, must leave the local server with NO apps
+ * rather than with a half-built one — the tools it bridges still work.
+ */
+export function parseMcpAppManifest(body: unknown): McpAppManifest {
+  const empty: McpAppManifest = { tools: {}, resources: [] };
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return empty;
+  const raw = body as { tools?: unknown; resources?: unknown };
+  const tools: Record<string, McpAppToolUi> = {};
+  if (raw.tools && typeof raw.tools === 'object' && !Array.isArray(raw.tools)) {
+    for (const [name, value] of Object.entries(raw.tools as Record<string, unknown>)) {
+      const uri = (value as { resourceUri?: unknown })?.resourceUri;
+      if (typeof uri === 'string' && uri.startsWith(MCP_APP_URI_SCHEME)) {
+        tools[name] = { resourceUri: uri };
+      }
+    }
+  }
+  const resources: McpAppResource[] = [];
+  if (Array.isArray(raw.resources)) {
+    for (const entry of raw.resources) {
+      if (!entry || typeof entry !== 'object') continue;
+      const r = entry as Partial<McpAppResource>;
+      // A view with no URI or no HTML is nothing a host can render, and a
+      // media type that is not the app one would be rejected downstream
+      // anyway — drop it here, where the reason is still legible.
+      if (typeof r.uri !== 'string' || !r.uri.startsWith(MCP_APP_URI_SCHEME)) continue;
+      if (typeof r.text !== 'string' || r.text === '') continue;
+      if (r.mimeType !== MCP_APP_MIME_TYPE) continue;
+      resources.push({
+        uri: r.uri,
+        name: typeof r.name === 'string' && r.name ? r.name : r.uri,
+        ...(typeof r.title === 'string' ? { title: r.title } : {}),
+        ...(typeof r.description === 'string' ? { description: r.description } : {}),
+        mimeType: MCP_APP_MIME_TYPE,
+        text: r.text,
+        ui:
+          r.ui && typeof r.ui === 'object' && !Array.isArray(r.ui)
+            ? (r.ui as McpAppResourceUi)
+            : {},
+      });
+    }
+  }
+  // Only tools whose view actually arrived: a `resourceUri` pointing at a
+  // resource this surface cannot serve would have a host preload a 404 and
+  // show the reader an empty frame where the text used to be.
+  const served = new Set(resources.map((r) => r.uri));
+  for (const name of Object.keys(tools)) {
+    if (!served.has(tools[name].resourceUri)) delete tools[name];
+  }
+  return { tools, resources };
+}

package/src/meta-tools.ts

@@ -4,6 +4,7 @@ import { utcpNameToTsInterfaceName, findToolsByNames, sanitizeIdentifier } from
 import { chainExample, type ChainExample, type ChainExampleTool } from './chain-example.js';
 import { toCallToolResult, toolError, describeToolFailure, withTransportDetail, omitImagePayloads } from './results.js';
 import { retiredToolInFailure } from './retired-tools.js';
+import { withCallExample } from './tool-interface.js';
 import {
   CHAIN_TIMEOUT_DEFAULT_MS,
   CHAIN_TIMEOUT_MAX_MS,
@@ -25,7 +26,7 @@ import {
  *
  * What a chain DOES, though — to a failure, to a large result, to an image —
  * is true of every call, and those rules are stated once, in the handshake
- * instructions and in the platform-managed agent guide, rather than on each
+ * instructions and in the platform's agent guide, rather than on each
  * tool they cover. So on a surface that has those rules the chain description
  * ends with the same pointer sentence every file tool ends with, composed
  * where the tool is served and the guide's configured name is known
@@ -119,7 +120,8 @@ function callToolChainDescription(example: ChainExample, sharedRulesPointer?: st
   // A name the catalog really has, or no name: see `ChainExample.name`.
   const forInstance = name ? ` (e.g. \`${name}\`)` : '';
   const howToWriteOne = [
-    `Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as \`${ns}.<tool>({ body: { ...args } })\` with NO \`await\` (results are already resolved), and \`return\` the final value.${worked} Every argument a tool declares REQUIRED must be present — \`tools_info\` gives the exact shapes, and for the knowledge-base tools that includes \`branch\`. The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax), plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser. There is no \`Buffer\`, no \`fetch\` and no \`require\`.`,
+    `Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function, with NO \`await\` (results are already resolved), and \`return\` the final value.${worked} The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax), plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser. There is no \`Buffer\`, no \`fetch\` and no \`require\`.`,
+    `There is NO single calling shape: call each tool as the \`Call:\` line atop its description shows; every tool in \`${ns}\` has one. Mismatched arguments are refused before anything runs.`,
     `Discover first: \`list_tools\` lists every tool in callable form${forInstance}; \`tools_info\` returns their exact argument + return shapes — do not guess. Batch multiple tool calls into one chain to avoid a round-trip per call. The chain runs with your own connection key, so it can only reach the tools you can already call directly.`,
   ];
   if (sharedRulesPointer !== undefined) return `${howToWriteOne.join('\n\n')}${sharedRulesPointer}`;
@@ -158,7 +160,7 @@ export function codeModeMetaTools(
 ): McpTool[] {
   const example = chainExample(namespace, tools);
   const { name } = example;
-  return [
+  return withCallExamples([
     {
       name: 'list_tools',
       description: `List every UTCP tool currently registered, in TypeScript-accessible form${name ? ` (e.g. \`${name}\`)` : ''} for use inside \`call_tool_chain\`.`,
@@ -196,7 +198,20 @@ export function codeModeMetaTools(
         additionalProperties: false,
       } as McpTool['inputSchema'],
     },
-  ];
+  ]);
+}
+
+/**
+ * Each of the three with its call example ahead of its description, from the
+ * same generator every other tool's comes from — so "every description opens
+ * with its call" holds with no exception an agent has to learn.
+ *
+ * These three are called DIRECTLY over MCP rather than from inside a chain, so
+ * the example shows that shape: the tool's name and its required arguments,
+ * with no namespace in front.
+ */
+function withCallExamples(tools: McpTool[]): McpTool[] {
+  return tools.map((t) => ({ ...t, description: withCallExample(t.description, t.name, t.inputSchema) }));
 }
 
 /**
@@ -267,8 +282,18 @@ export async function dispatchMetaTool(
       const resolved = await findToolsByNames(client, names);
       for (const n of names) {
         const found = resolved.get(n);
-        if (found) interfaces.push(client.toolToTypeScriptInterface(found.tool));
-        else notFound.push(n);
+        // The call example travels with the interface too: `tools_info` is
+        // where an agent writing a chain reads the shape, and reading it there
+        // without the example is how a flat tool's arguments end up in a
+        // `body`. Added to a COPY — the repository's tool is not ours to edit.
+        if (found) {
+          interfaces.push(
+            client.toolToTypeScriptInterface({
+              ...found.tool,
+              description: withCallExample(found.tool.description, found.utcpName, found.tool.inputs),
+            }),
+          );
+        } else notFound.push(n);
       }
       return toCallToolResult({ interfaces: interfaces.join('\n\n'), not_found: notFound });
     }

package/src/proxied-tool.ts

@@ -1,5 +1,7 @@
 import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
 import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+import { withCallExample } from './tool-interface.js';
+import { toolUiMeta, type McpAppToolUi } from './mcp-app.js';
 
 /** A tool discovered from a UTCP manual, flattened into what an MCP surface advertises. */
 export interface ProxiedTool {
@@ -10,6 +12,16 @@ export interface ProxiedTool {
   /** The UTCP manual this tool came from (the `<manual>` in `<manual>.<tool>`),
    * used to look up the manual's declared per-user credentials before dispatch. */
   manualName: string;
+  /**
+   * The MCP Apps view this tool's result renders in, when it carries one.
+   *
+   * Not part of the UTCP manual a tool is discovered from — UTCP has no place
+   * for it — so a surface attaches it by tool NAME from the deployment's app
+   * manifest (`McpAppManifest.tools`) after flattening. `toListedTool` turns
+   * it into the `_meta` an MCP client reads; a client without the extension
+   * ignores the field, so carrying it costs nothing.
+   */
+  ui?: McpAppToolUi;
 }
 
 /**
@@ -72,11 +84,84 @@ export function toListedTool(tool: ProxiedTool): McpTool | null {
   }
   return {
     name: tool.mcpName,
-    description: tool.description,
+    // Every tool an agent can see opens with the one line that shows how it is
+    // called — generated from this tool's own input schema, so the platform's
+    // tools, a deployment's and a connected server's all get one and none of
+    // them can drift from the shape the tool really takes.
+    // From the schema as it is LISTED (sanitized, local `$ref`s inlined), so
+    // the example and the interface the client is shown agree.
+    description: withCallExample(tool.description, tool.utcpName, inputSchema),
     inputSchema: inputSchema as McpTool['inputSchema'],
+    // The MCP Apps view, when this tool carries one. `_meta` is an open map
+    // every client is required to tolerate, so a client without the
+    // extension reads the tool exactly as it did before.
+    ...(tool.ui ? { _meta: toolUiMeta(tool.ui) } : {}),
   };
 }
 
+/**
+ * How deep {@link sanitizeInputSchema} descends before it stops walking and
+ * passes the remainder through untouched. Generous on purpose: a real schema
+ * costs two levels per nesting (the `properties` keyword, then the field name),
+ * and the whole reason for this constant is the call stack, not the schema.
+ */
+const MAX_SANITIZE_DEPTH = 200;
+
+/**
+ * How many nodes one schema's `$ref` inlining may produce before a `$ref`
+ * stops being expanded.
+ *
+ * The recursion guard tracks only the pointers on the ACTIVE path, which is
+ * what `$ref` recursion means — but it does not make expansion cheap. A
+ * schema whose references form a DAG rather than a tree (two `allOf` branches
+ * pointing at one `$defs` entry, that entry doing the same) expands its target
+ * once per branch, and that doubles per level: a few hundred bytes on the wire
+ * can ask `tools/list` for a reply no amount of memory will hold. Past this
+ * budget a `$ref` degrades to the same permissive `{}` a recursive one does,
+ * which stands at a schema position and leaves the result valid JSON Schema.
+ */
+const MAX_INLINED_NODES = 20_000;
+
+/**
+ * The stand-in for a subtree past {@link MAX_SANITIZE_DEPTH}: every plain
+ * object becomes `{}`, while arrays and scalars keep their shape. Iterative,
+ * because the whole reason for being here is that the recursion has to stop.
+ *
+ * `{}` is legal exactly where a SCHEMA stands, and an object this deep inside a
+ * schema is at a schema position. The positions the old cap destroyed were an
+ * `anyOf` LIST, a `required` entry and a `type` STRING — none of them an
+ * object, all of them handed back as they came. And because no object survives,
+ * nothing past the cap can carry a `$ref` left dangling by the `$defs` block
+ * this walk drops, or a `format` the Anthropic validator refuses.
+ */
+function stripPastDepth(node: unknown): unknown {
+  if (!node || typeof node !== 'object') return node;
+  if (!Array.isArray(node)) return {};
+  const out: unknown[] = [];
+  const queue: Array<{ from: readonly unknown[]; to: unknown[] }> = [{ from: node, to: out }];
+  for (let i = 0; i < queue.length; i += 1) {
+    const { from, to } = queue[i];
+    for (const item of from) {
+      if (!item || typeof item !== 'object') to.push(item);
+      else if (!Array.isArray(item)) to.push({});
+      else {
+        const nested: unknown[] = [];
+        to.push(nested);
+        queue.push({ from: item, to: nested });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Keywords whose value is INSTANCE DATA rather than a schema. A schema says
+ * what a value may be; these carry values themselves, so nothing in them is a
+ * construct for the sanitizer to touch — and nothing in them is a place where
+ * `{}` would mean "any value" either.
+ */
+const DATA_VALUED_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
+
 /** JSON-Schema string `format` values the Anthropic tool validator accepts. */
 const SUPPORTED_SCHEMA_FORMATS = new Set([
   'date-time',
@@ -99,9 +184,28 @@ const SUPPORTED_SCHEMA_FORMATS = new Set([
  *  - drop non-standard `format` values (OpenAPI's `int32`/`byte`/… — only the
  *    JSON-Schema-standard formats above are accepted; `format` is advisory, so
  *    dropping it doesn't change tool behavior).
- * Depth-bounded so a recursive schema degrades to a permissive `{}` node instead
- * of hanging or emitting the unsupported recursion; non-local/external refs
- * degrade the same way. Exported for direct testing.
+ * Everything else is passed through UNCHANGED, and both recursion guards are
+ * built so that hitting one cannot change a schema either:
+ *
+ *  - a `$ref` that resolves back onto a schema we are already inlining is
+ *    recursive, and inlining has no finite answer for it. It degrades to a
+ *    permissive `{}` — which is legal, because a `$ref` only ever stands where
+ *    a SCHEMA is expected and `{}` there means "any value". Non-local and
+ *    unresolvable refs degrade the same way, and so does one past
+ *    {@link MAX_INLINED_NODES}.
+ *  - the depth cap keeps the rest of the subtree's shape, replacing only the
+ *    objects in it with `{}` — see {@link stripPastDepth}. It cannot reach
+ *    inside instance data, because the walk never descends into a
+ *    {@link DATA_VALUED_KEYWORDS} value in the first place.
+ *
+ * That second rule is the fix for three tools AI clients silently dropped. The
+ * cap used to return `{}` at WHATEVER position it stopped at, and most
+ * positions in a schema are not schema positions: a tool nested deeper than
+ * the cap reached clients with `anyOf: {}`, `required: [{}]` or `type: {}` in
+ * it. None of those is valid JSON Schema, so the client refused the tool — and
+ * said so about a server that had sent a perfectly good schema.
+ *
+ * Exported for direct testing.
  */
 export function sanitizeInputSchema(schema: unknown): unknown {
   const root = schema;
@@ -111,30 +215,131 @@ export function sanitizeInputSchema(schema: unknown): unknown {
     for (const partRaw of pointer.slice(2).split('/')) {
       const part = partRaw.replace(/~1/g, '/').replace(/~0/g, '~');
       if (!node || typeof node !== 'object') return undefined;
+      // Own members only: `#/constructor` names nothing, not `Object`.
+      if (!Object.prototype.hasOwnProperty.call(node, part)) return undefined;
       node = (node as Record<string, unknown>)[part];
     }
     return node;
   };
-  // `isPropertyMap` marks the value of `properties`/`patternProperties`: its
-  // keys are the tool's OWN field names, not schema keywords, so a field
-  // literally named `format`, `$ref` or `definitions` must survive untouched
-  // (its VALUE is still a schema and is walked as one).
+  // The pointers currently being inlined, on THIS path. A `$ref` that points
+  // at a schema we are already inside is recursive: JSON Schema says that with
+  // the reference, and an inlined copy has no finite form.
+  const inlining = new Set<string>();
+  // Nodes charged to the expansion budget so far, against MAX_INLINED_NODES.
+  let inlined = 0;
+  // The size of each referenced target — objects, arrays, their entries and
+  // scalars, one count per pointer — stopped early past the budget, since
+  // past it the exact number no longer matters.
+  const costs = new Map<string, number>();
+  const costOf = (pointer: string): number => {
+    const known = costs.get(pointer);
+    if (known !== undefined) return known;
+    // Counted with a bounded frontier: children are pushed one at a time and
+    // only while the count is under the cap, so a target wider than the
+    // budget costs the cap in work and in memory, never its own width.
+    let count = 0;
+    const stack: unknown[] = [resolvePointer(pointer)];
+    const over = () => count + stack.length > MAX_INLINED_NODES;
+    while (stack.length > 0 && !over()) {
+      const item = stack.pop();
+      count += 1;
+      if (!item || typeof item !== 'object') continue;
+      if (Array.isArray(item)) {
+        for (let i = 0; i < item.length && !over(); i += 1) stack.push(item[i]);
+      } else {
+        for (const key in item as Record<string, unknown>) {
+          if (over()) break;
+          if (Object.prototype.hasOwnProperty.call(item, key)) stack.push((item as Record<string, unknown>)[key]);
+        }
+      }
+    }
+    const cost = over() ? MAX_INLINED_NODES + 1 : count;
+    costs.set(pointer, cost);
+    return cost;
+  };
+  // `isPropertyMap` marks the value of `properties`/`patternProperties`, and
+  // of `dependentSchemas`/`dependencies`: its keys are the tool's OWN field
+  // names, not schema keywords, so a field literally named `format`, `$ref`,
+  // `definitions` or `default` must survive untouched (its VALUE is still a
+  // schema and is walked as one).
   const walk = (node: unknown, depth: number, isPropertyMap = false): unknown => {
-    if (depth > 20) return {}; // recursion/cycle guard — permissive fallback
-    if (Array.isArray(node)) return node.map((item) => walk(item, depth + 1));
+    // Stack guard, not a schema rule: `$ref` recursion is caught below, so
+    // nothing a server legitimately sends reaches this. Stopping must never
+    // make a schema INVALID — which is exactly what the old cap did, by
+    // returning `{}` at whatever position it had reached.
+    if (depth > MAX_SANITIZE_DEPTH) return stripPastDepth(node);
     if (!node || typeof node !== 'object') return node;
+    if (Array.isArray(node)) return node.map((item) => walk(item, depth + 1));
     const obj = node as Record<string, unknown>;
-    if (!isPropertyMap && typeof obj.$ref === 'string') {
-      const target = resolvePointer(obj.$ref);
+    // `$dynamicRef` is a reference like `$ref` (2020-12's late-bound form):
+    // resolved the same way when it is a local pointer, degraded the same way
+    // when it is not — never left standing, because the `$defs` block it
+    // reaches into is dropped below and a dangling reference is what clients
+    // reject. Both at once is legal and both apply, so both are inlined, as
+    // the `allOf` they amount to.
+    const references = (['$ref', '$dynamicRef'] as const)
+      .map((keyword) => obj[keyword])
+      .filter((value): value is string => typeof value === 'string');
+    if (!isPropertyMap && references.length > 0) {
       // JSON Schema allows siblings next to $ref; keep them, target wins ties.
       const siblings: Record<string, unknown> = { ...obj };
       delete siblings.$ref;
-      const resolved = walk(target ?? {}, depth + 1);
-      return resolved && typeof resolved === 'object' && !Array.isArray(resolved)
-        ? { ...siblings, ...(resolved as Record<string, unknown>) }
-        : Object.keys(siblings).length
-          ? siblings
-          : resolved ?? {};
+      delete siblings.$dynamicRef;
+      // Sanitized ONCE, here, because every path below can return them: the
+      // siblings are schema keywords in their own right, and an unsupported
+      // `format` or a nested `$ref` left in them is precisely what this
+      // function exists to keep out of a listing. (`siblings` no longer holds
+      // a `$ref`, so this cannot re-enter this branch at this node; deeper
+      // ones terminate on `inlining` or on the depth cap.)
+      const kept = Object.keys(siblings).length ? (walk(siblings, depth + 1) as Record<string, unknown>) : null;
+      // Recursive, or past the expansion budget: `{}` ("any value") is the only
+      // finite answer, and a `$ref` stands at a schema position, so `{}` there
+      // is valid JSON Schema. The reference itself has to go — the `$defs`
+      // block it points into is dropped below, and a dangling `$ref` is what
+      // clients reject.
+      //
+      // The budget is charged AT THE REFERENCE, by the whole size of what it
+      // would copy — every object, array, array entry and scalar in the
+      // target, counted once per pointer — before a byte of it is copied. A
+      // target that does not fit the remaining budget is `{}` whole, never a
+      // partial copy: the only thing a copy can cost is what the reference
+      // multiplies, and that is the target's full size whatever shapes it is
+      // made of (a `required` list of ten thousand names as much as ten
+      // thousand properties).
+      const resolveOne = (pointer: string): unknown => {
+        if (inlining.has(pointer)) return {};
+        const cost = costOf(pointer);
+        if (inlined + cost > MAX_INLINED_NODES) return {};
+        inlined += cost;
+        inlining.add(pointer);
+        try {
+          return walk(resolvePointer(pointer) ?? {}, depth + 1);
+        } finally {
+          inlining.delete(pointer);
+        }
+      };
+      const asObject = (value: unknown): Record<string, unknown> =>
+        value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+      if (references.length === 1) {
+        const resolved = resolveOne(references[0]!);
+        // An object target merges over the siblings; a boolean target is a
+        // schema in its own right (`false` rejects everything) and stands
+        // alone, or under `allOf` beside siblings; anything else a pointer
+        // can land on — a string, a number, an array — is not a schema and
+        // becomes `{}`, never the raw value.
+        if (typeof resolved === 'boolean') {
+          return kept ? { ...kept, allOf: [...(Array.isArray(kept.allOf) ? kept.allOf : []), resolved] } : resolved;
+        }
+        return { ...(kept ?? {}), ...asObject(resolved) };
+      }
+      // A boolean target is a schema too (`false` rejects everything) and is
+      // kept as it is; anything that is not an object schema is `{}`.
+      const targets = references.map((pointer) => {
+        const resolved = resolveOne(pointer);
+        return typeof resolved === 'boolean' ? resolved : asObject(resolved);
+      });
+      const allOf = Array.isArray(kept?.allOf) ? (kept!.allOf as unknown[]) : [];
+      return { ...(kept ?? {}), allOf: [...allOf, ...targets] };
     }
     const out: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(obj)) {
@@ -143,12 +348,25 @@ export function sanitizeInputSchema(schema: unknown): unknown {
         continue;
       }
       if (key === '$defs' || key === 'definitions') continue; // inlined above
+      // Instance DATA, not a schema: handed back exactly as it came. A `default`
+      // or an `enum` entry that happens to carry a key named `format` or `$ref`
+      // is a value the tool expects, not a construct to rewrite — and since the
+      // walk never descends into one, the depth cap cannot reach inside it
+      // either.
+      if (DATA_VALUED_KEYWORDS.has(key)) {
+        out[key] = value;
+        continue;
+      }
       // Drop a non-standard `format` (OpenAPI `int32`/`byte`/…) — the validator
       // only allows the JSON-Schema-standard set; the annotation is non-load-bearing.
       if (key === 'format' && (typeof value !== 'string' || !SUPPORTED_SCHEMA_FORMATS.has(value))) {
         continue;
       }
-      out[key] = walk(value, depth + 1, key === 'properties' || key === 'patternProperties');
+      out[key] = walk(
+        value,
+        depth + 1,
+        key === 'properties' || key === 'patternProperties' || key === 'dependentSchemas' || key === 'dependencies',
+      );
     }
     return out;
   };