@astral-mcp/projection 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -2,6 +2,8 @@ import { createRequire } from "node:module";
 import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
 import { deflateRawSync, inflateRawSync } from "node:zlib";
 import { getModuleLoader, getTypescriptSupport, loadQuickJs } from "@sebastianwessel/quickjs";
+import { readFile } from "node:fs/promises";
+import { newVariant } from "quickjs-emscripten-core";
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { InMemoryTransport, McpServer, ProtocolError, ProtocolErrorCode, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from "@modelcontextprotocol/server";
@@ -131,7 +133,7 @@ const MAX_CAPS = {
 */
 const MIN_CAPS = {
 	segmentWallClockMs: 100,
-	wasmMemoryBytes: 1048576,
+	wasmMemoryBytes: 16777216,
 	maxCodeBytes: 1024,
 	maxInputBytes: 1024,
 	maxReadCallsPerSegment: 1,
@@ -165,9 +167,15 @@ const BLOB_SCHEMA_VERSION = 1;
 * CI instead of silently minting blobs with a stale version stamp.
 */
 /** `@astral-mcp/projection` package version (must match packages/projection/package.json). */
-const LIB_VERSION = "0.7.0";
+const LIB_VERSION = "0.8.0";
 /** Pinned XState version (must match the exact pin in package.json — D2). */
 const XSTATE_VERSION = "5.32.5";
+/**
+* Exact pin of `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
+* (must match package.json). Not a blob stamp: the introspector names it when
+* a wrapped `McpServer` comes from a second, different copy of the SDK.
+*/
+const MCP_SDK_VERSION = "2.3.1";
 //#endregion
 //#region src/blob/sealer.ts
 /**
@@ -411,7 +419,7 @@ function openBlob(blob, options) {
 	}
 	if (!isRecord(payload)) throw verificationError("blob payload malformed: not a JSON object", HINT_CORRUPT);
 	if (payload["v"] !== 1) throw verificationError(`unknown blob schema version ${JSON.stringify(payload["v"])} (this library expects 1)`, HINT_VERSION);
-	if (payload["libv"] !== "0.7.0") throw verificationError(`library version mismatch: blob was sealed by @astral-mcp/projection ${JSON.stringify(payload["libv"])}, this instance runs ${LIB_VERSION}`, HINT_VERSION);
+	if (payload["libv"] !== "0.8.0") throw verificationError(`library version mismatch: blob was sealed by @astral-mcp/projection ${JSON.stringify(payload["libv"])}, this instance runs ${LIB_VERSION}`, HINT_VERSION);
 	if (payload["xstatev"] !== "5.32.5") throw verificationError(`xstate version mismatch: blob snapshot was produced under xstate ${JSON.stringify(payload["xstatev"])}, this instance runs ${XSTATE_VERSION}`, HINT_VERSION);
 	assertPayloadShape(payload);
 	const verified = payload;
@@ -638,24 +646,171 @@ const SANDBOX_GLOBAL = "__projection";
 * module calls `env.__projection_toolCall(name, args)` and receives a promise.
 */
 const TOOL_CALL_BINDING = "__projection_toolCall";
-let quickJsPromise;
+let variantPromise;
+let wasmModulePromise;
 let tsSupportPromise;
 const QUICKJS_VARIANT = "@jitl/quickjs-ng-wasmfile-release-sync";
-function getQuickJs() {
-	quickJsPromise ??= (async () => {
+/** WebAssembly page size (bytes); memory limits are expressed in pages. */
+const WASM_PAGE_BYTES = 65536;
+/**
+* Pages the variant's emscripten build starts with (`INITIAL_MEMORY`,
+* 16 MB). An imported memory must be at least this large, so the cap can
+* never bound the heap below it — `MIN_CAPS.wasmMemoryBytes` matches.
+*/
+const WASM_INITIAL_PAGES = 256;
+function getQuickJsVariant() {
+	variantPromise ??= (async () => {
 		let variant;
 		try {
 			variant = await import(QUICKJS_VARIANT);
 		} catch (cause) {
-			quickJsPromise = void 0;
+			variantPromise = void 0;
 			throw new ProjectionError("runtime", `QuickJS WASM variant '${QUICKJS_VARIANT}' is not installed`, {
 				hint: `Add ${QUICKJS_VARIANT} to the @astral-mcp/projection package dependencies`,
 				cause
 			});
 		}
-		return loadQuickJs(variant.default);
+		return variant.default;
 	})();
-	return quickJsPromise;
+	return variantPromise;
+}
+/**
+* Instances whose heap never grew, kept for reuse, keyed by `maximumPages`.
+* See `releaseBoundedRuntime` for what qualifies.
+*/
+const idleRuntimes = /* @__PURE__ */ new Map();
+let idleRuntimeCount = 0;
+/** Idle instances kept across all caps; each holds ~16 MB of address space. */
+const IDLE_RUNTIMES_MAX = 8;
+/**
+* The memory `maximum` (pages) for a cap. This is what makes `wasmMemoryBytes`
+* a bound on real bytes. QuickJS's own `setMemoryLimit` cannot be: it charges
+* each allocation `malloc_usable_size + overhead`, and the emscripten build
+* returns 0 for `malloc_usable_size`, so the running total counts bookkeeping
+* only and a loop of sub-cap allocations grows the heap to the module's 2 GB
+* ceiling before "out of memory" fires (measured: ~2 GB under an 8 MB cap).
+* The engine, by contrast, enforces a memory's `maximum` on every `grow`: the
+* emscripten glue catches the failed grow, `malloc` returns NULL, and QuickJS
+* throws its ordinary "out of memory" InternalError — which `classifyEvalError`
+* reports as the memory `cap_exceeded`.
+*
+* Because the bound is a property of the memory, every session needs its own
+* module instance rather than a share of one process-wide linear memory: a
+* hoarding machine cannot starve its neighbours, the bound holds under
+* concurrency without any per-runtime accounting, and a heap that grew can be
+* reclaimed by dropping the instance (WebAssembly memories never shrink). The
+* 16 MB `initial` is dictated by the WASM module's import.
+*/
+function maximumPagesFor(capBytes) {
+	return Math.max(WASM_INITIAL_PAGES, Math.ceil(capBytes / WASM_PAGE_BYTES));
+}
+/**
+* Compile the variant's WebAssembly binary once and share the compiled
+* module across instances. Only instantiation has to happen per instance
+* (that is what gives each its own memory); letting the emscripten glue read
+* and compile the file every time costs ~2 ms more per instance with a
+* ~25 ms tail. The binary sits next to the glue module. Where it cannot be
+* located — no `import.meta.resolve` (bundler-transformed builds), or a
+* bundler that moved the file — the glue's own loader is used instead:
+* slower, otherwise equivalent.
+*/
+function getCompiledWasm() {
+	wasmModulePromise ??= (async () => {
+		if (typeof import.meta.resolve !== "function") return void 0;
+		try {
+			const glueUrl = import.meta.resolve(`${QUICKJS_VARIANT}/emscripten-module`);
+			const bytes = await readFile(new URL("emscripten-module.wasm", glueUrl));
+			return await WebAssembly.compile(bytes);
+		} catch {
+			return;
+		}
+	})();
+	return wasmModulePromise;
+}
+/**
+* Take an idle instance for this cap, or instantiate a fresh one whose heap
+* can never exceed `capBytes`.
+*/
+async function acquireBoundedRuntime(capBytes) {
+	const maximumPages = maximumPagesFor(capBytes);
+	const idle = idleRuntimes.get(maximumPages)?.pop();
+	if (idle !== void 0) {
+		idleRuntimeCount--;
+		return idle;
+	}
+	const memory = new WebAssembly.Memory({
+		initial: WASM_INITIAL_PAGES,
+		maximum: maximumPages
+	});
+	const [variant, wasmModule] = await Promise.all([getQuickJsVariant(), getCompiledWasm()]);
+	const runtime = await loadQuickJs(newVariant(variant, {
+		wasmMemory: memory,
+		...wasmModule !== void 0 ? { wasmModule } : {}
+	}));
+	guardHostMalloc(runtime.module);
+	return {
+		runtime,
+		memory,
+		maximumPages
+	};
+}
+/**
+* Make the instance's `_malloc` export throw when the heap is full instead
+* of returning NULL. quickjs-emscripten copies every string and buffer it
+* hands the VM — `evalCode` sources included, and the machine host delivers
+* tool results as JSON inside evaluate source — through `_malloc` without
+* checking the result, so under a bounded heap a NULL would make it write
+* the copy at address 0 onward, corrupting the instance's static data
+* (traps, assertion aborts, a poisoned pooled instance). Thrown instead, the
+* error reaches `@sebastianwessel/quickjs`'s `handleEvalError` with the
+* message "out of memory", which `classifyEvalError` reports as the memory
+* `cap_exceeded`, and nothing is written. Only host-side allocations go
+* through this export; QuickJS's own allocations stay inside the WASM module
+* and fail the ordinary way.
+*/
+function guardHostMalloc(wasmModule) {
+	const emscripten = wasmModule.getFFI().module;
+	const malloc = emscripten._malloc;
+	emscripten._malloc = (size) => {
+		const ptr = malloc(size);
+		if (ptr === 0 && size > 0) {
+			const error = /* @__PURE__ */ new Error("out of memory");
+			error.stack = "";
+			throw error;
+		}
+		return ptr;
+	};
+}
+/**
+* Return an instance whose session has ended. An instance is kept only when
+* its session was clean — every `evaluate`, the two boot evaluates included,
+* returned ok — and its heap is still at its initial size. Such an instance's
+* QuickJS runtime has been freed, so for the next session it is as good as
+* new — and reusing it is what keeps segment start-up at the cost of the old
+* shared singleton (instantiating per session doubled the resume leg under
+* parallel load). Anything else is dropped: an instance that grew (a machine
+* that hoarded, whether or not it hit the cap) so its memory is reclaimed,
+* and an instance whose session saw any failure — cap exceeded, an in-VM
+* exception, a thrown error — because a failure is the one place it might
+* have been left inconsistent. The rule is deliberately that blunt rather
+* than classifying failures: re-instantiation costs ~3-5 ms and failures are
+* the exceptional path. (The heap-size check alone is not enough: at the
+* 16 MB floor `maximum` equals `initial`, so a session that exhausted the
+* heap never changes its size.) Sharing an instance across sessions in
+* sequence is the same trust the shared singleton always placed in QuickJS's
+* memory safety.
+*/
+function releaseBoundedRuntime(bounded, clean) {
+	if (!clean) return;
+	if (bounded.memory.buffer.byteLength !== WASM_INITIAL_PAGES * WASM_PAGE_BYTES) return;
+	if (idleRuntimeCount >= IDLE_RUNTIMES_MAX) return;
+	let bucket = idleRuntimes.get(bounded.maximumPages);
+	if (bucket === void 0) {
+		bucket = [];
+		idleRuntimes.set(bounded.maximumPages, bucket);
+	}
+	bucket.push(bounded);
+	idleRuntimeCount++;
 }
 /**
 * Environment-class transpile failure: the TypeScript transpiler itself is
@@ -836,16 +991,19 @@ async function createSandboxSession(options) {
 			clear: silent
 		}
 	};
-	const runtime = await getQuickJs();
+	const bounded = await acquireBoundedRuntime(caps.wasmMemoryBytes);
+	const runtime = bounded.runtime;
 	const deadlineAt = Date.now() + caps.segmentWallClockMs;
 	const ready = deferred();
 	const hold = deferred();
 	let disposed = false;
+	/** False once any evaluate fails; see `releaseBoundedRuntime`. */
+	let clean = true;
 	const runPromise = runtime.runSandboxed(async ({ evalCode }) => {
 		ready.resolve({ evalCode });
 		await hold.promise;
 	}, sandboxOptions);
-	runPromise.catch(() => {});
+	runPromise.then(() => releaseBoundedRuntime(bounded, clean), () => {});
 	const { evalCode } = await Promise.race([ready.promise, runPromise.then(() => {
 		throw new ProjectionError("runtime", "QuickJS sandbox terminated during startup", {
 			hint: "This is a sandbox runtime bug; check the host logs",
@@ -873,7 +1031,11 @@ async function createSandboxSession(options) {
 			if (!result.ok) throw classifyEvalError(result, caps, logs.snapshot());
 			return result.data;
 		};
-		const run = queue.then(task, task);
+		const tracked = () => task().catch((error) => {
+			clean = false;
+			throw error;
+		});
+		const run = queue.then(tracked, tracked);
 		queue = run.then(() => void 0, () => void 0);
 		return run;
 	};
@@ -951,6 +1113,29 @@ function indentBlock(text, indent = BLOCK_INDENT) {
 function inertIdentity$1(identity) {
 	return JSON.stringify(neutralizeControlChars(capLength(identity, 200)));
 }
+/** Longest one-line tool purpose rendered anywhere (approval copy, overview, `search_tools`). */
+const MAX_PURPOSE_CHARS = 200;
+const MAX_RAW_DESCRIPTION_CHARS = 2e3;
+/**
+* The one-line human purpose: the first sentence of the server's
+* description, neutralized and capped. Runs of replacement characters
+* (neutralized control bytes) are collapsed so a hostile or malformed
+* description does not render as a wall of `�`. Undefined when the server
+* gave no usable description.
+*
+* One rule, three consumers — the approval copy (R16), the `discover_apis`
+* overview and `search_tools` (R33) — so every projection describes a tool
+* identically.
+*/
+function purposeSentence(description) {
+	if (description === void 0) return void 0;
+	description = capLength(description, MAX_RAW_DESCRIPTION_CHARS);
+	const firstLine = description.split(/\r?\n/, 1)[0]?.trim() ?? "";
+	if (firstLine.length === 0) return void 0;
+	const match = /^.*?[.!?](\s|$)/.exec(firstLine);
+	const neutralized = neutralizeControlChars((match ? match[0] : firstLine).trim()).replace(/�{2,}/g, "�").trim();
+	return neutralized.length > 0 ? capLength(neutralized, MAX_PURPOSE_CHARS) : void 0;
+}
 //#endregion
 //#region src/policy/decision.ts
 /**
@@ -989,6 +1174,14 @@ function decidePolicy(entry, overrides) {
 	}
 	return entry.annotations?.readOnlyHint === true ? "auto" : "ask";
 }
+/** Map a policy decision to its plain-words posture (R33). Shared by every surface that names one. */
+function postureOf(decision) {
+	switch (decision) {
+		case "auto": return "runs immediately";
+		case "ask": return "asks for approval";
+		case "deny": return "blocked by policy";
+	}
+}
 /**
 * Resolve a machine-requested tool call against the server catalog and
 * decide its policy.
@@ -1066,9 +1259,7 @@ const DEFAULT_MAX_ARGS_CHARS = 4096;
 const MAX_STRING_LEAF_CHARS = 512;
 const MAX_STATE_NAME_CHARS = 200;
 const MAX_TOOL_NAME_CHARS = 200;
-const MAX_PURPOSE_CHARS = 200;
-const MAX_RAW_DESCRIPTION_CHARS = 2e3;
-const DESTRUCTIVE_WARNING = "⚠ This can permanently change or delete data. Review the details before approving.";
+const DESTRUCTIVE_WARNING = "This can permanently change or delete data. Review the details before approving.";
 const REDACTION_FAILED = "[redaction failed]";
 /**
 * Build the approval summary for a gated call.
@@ -1089,13 +1280,15 @@ function buildElicitationCopy(call, entry, options = {}) {
 	const safeName = neutralizeControlChars(capLength(entry.name, MAX_TOOL_NAME_CHARS));
 	const friendly = friendlyAction(entry, safeName);
 	const purpose = purposeSentence(entry.description);
-	const title = destructive ? `⚠ Approve: ${friendly}` : `Approve: ${friendly}`;
+	const method = dispatchMethod(call.args, entry);
+	const action = method !== void 0 ? `${friendly} — ${method}` : friendly;
+	const title = destructive ? `⚠ Approve: ${action}` : `Approve: ${action}`;
 	const lines = [];
 	if (destructive) lines.push(DESTRUCTIVE_WARNING, "");
 	if (purpose !== void 0) lines.push(`What the server says it does: ${JSON.stringify(purpose)}`, "");
 	lines.push("Details:", indentBlock(neutralizeControlChars(renderedArgs, { allowNewline: true })));
 	const safeState = neutralizeControlChars(capLength(call.stateName, MAX_STATE_NAME_CHARS));
-	lines.push("", options.origin === "direct" ? `Tool ${safeName} · requested directly by the model` : `Tool ${safeName} · requested by step ${JSON.stringify(safeState)}`);
+	lines.push("", options.origin === "direct" ? `Tool: ${safeName}` : `Tool: ${safeName} · workflow step ${JSON.stringify(safeState)}`);
 	return {
 		title,
 		message: lines.join("\n"),
@@ -1105,6 +1298,31 @@ function buildElicitationCopy(call, entry, options = {}) {
 		destructive
 	};
 }
+/** Top-level argument names that conventionally select a tool's sub-action. */
+const DISPATCH_ARGS = ["method", "action"];
+/**
+* The dispatch value of a method-style tool, when the call carries one and
+* the schema constrains it: a top-level `method` / `action` string argument
+* whose schema property has an `enum` listing that exact value. Only
+* enum-listed values qualify, so the suffix is server-defined vocabulary
+* (neutralized and capped like every other S5 string), never free text
+* the model typed. Every dispatch key the call carries must pass: one that
+* is present but not enum-listed means no suffix at all, so a rejected
+* `method` cannot be routed around with an `action` the model added.
+*/
+function dispatchMethod(args, entry) {
+	const properties = entry.inputSchema["properties"];
+	if (typeof properties !== "object" || properties === null || Array.isArray(properties)) return;
+	let suffix;
+	for (const key of DISPATCH_ARGS) {
+		if (!Object.hasOwn(args, key)) continue;
+		const value = args[key];
+		const property = properties[key];
+		if (typeof value !== "string" || typeof property !== "object" || property === null || !Array.isArray(property["enum"]) || !property["enum"].includes(value)) return;
+		suffix ??= neutralizeControlChars(capLength(value, MAX_TOOL_NAME_CHARS));
+	}
+	return suffix;
+}
 /**
 * Plain-English action label: the server's annotation title when present,
 * otherwise the tool id humanized (namespace prefix dropped, separators to
@@ -1117,22 +1335,6 @@ function friendlyAction(entry, safeName) {
 	return humanized.length > 0 ? humanized : safeName;
 }
 /**
-* The one-line human purpose: the first sentence of the server's
-* description, neutralized and capped. Runs of replacement characters
-* (neutralized control bytes) are collapsed so a hostile or malformed
-* description does not render as a wall of `�`. Undefined when the server
-* gave no usable description.
-*/
-function purposeSentence(description) {
-	if (description === void 0) return void 0;
-	description = capLength(description, MAX_RAW_DESCRIPTION_CHARS);
-	const firstLine = description.split(/\r?\n/, 1)[0]?.trim() ?? "";
-	if (firstLine.length === 0) return void 0;
-	const match = /^.*?[.!?](\s|$)/.exec(firstLine);
-	const neutralized = neutralizeControlChars((match ? match[0] : firstLine).trim()).replace(/�{2,}/g, "�").trim();
-	return neutralized.length > 0 ? capLength(neutralized, MAX_PURPOSE_CHARS) : void 0;
-}
-/**
 * A deep copy of the arguments for the redaction hook. `structuredClone`
 * rejects functions and symbols, which only a direct (non-wire) caller can
 * put in args; fall back to the original there and let the fail-closed
@@ -1859,10 +2061,33 @@ var SegmentRunner = class {
 	* The arguments executed are the ones sealed in `pending` — the approval
 	* authorized those exact arguments, not whatever the restored machine
 	* might ask for now (S2).
+	*
+	* Policy outranks a stale approval (D9): a tool flipped to `deny` while
+	* its blob was outstanding is denied here even if the human approved it —
+	* "flip to deny" is the incident-response move, and the integrator's
+	* policy must win over an approval minted under the old one.
 	*/
 	async applyVerdicts(pending, verdicts) {
 		const events = [];
 		for (const [key, call] of Object.entries(pending)) {
+			const resolved = resolveCallPolicy(call, this.deps.catalog, this.deps.policy);
+			if (!resolved.ok) throw resolved.error;
+			if (resolved.decision === "deny") {
+				const reason = policyDeniedReason(call.name);
+				events.push({
+					type: "TOOL_DENIED",
+					callId: call.id,
+					reason
+				});
+				this.deps.audit.push({
+					callId: call.id,
+					tool: call.name,
+					args: call.args,
+					decision: "denied_by_policy",
+					reason
+				});
+				continue;
+			}
 			const verdict = Object.hasOwn(verdicts, key) ? verdicts[key] : void 0;
 			if (verdict === void 0 || verdict.kind === "declined") {
 				const reason = verdict?.kind === "declined" ? verdict.reason : void 0;
@@ -2279,6 +2504,221 @@ function invalid(path, why) {
 	return new ProjectionError("validate", `call_tool args: ${path} ${why}`, { hint: "Pass args as plain JSON: objects, arrays, strings, finite numbers, booleans and null only." });
 }
 //#endregion
+//#region src/catalog/search.ts
+/**
+* `search_tools` — the catalog projection's discovery tool (PRD R33, S5).
+*
+* Returns one page of the wrapped server's tools — name, a one-line
+* purpose, the policy posture in plain words, and whether the server marks
+* the tool destructive — optionally matched against a query. It is the lazy
+* alternative to `discover_apis`' inline overview: O(tools the model looks
+* at), not O(tools the server has).
+*
+* Matching is token-based (DECISIONS D10): the query is split into words on
+* anything that is not a letter, combining mark, or digit, and a tool
+* matches when ANY word is a case-insensitive substring of its name, its
+* annotation title, or its full description. Each word scores +2 when it is
+* in the name and, independently, +1 when it is in the title or description
+* (a word in both scores 3); matches are ranked by score, ties in catalog
+* order, so a guessed name like `create_issue` finds `issue_write` instead
+* of nothing. A title hit counts like a description hit — it catches words
+* the description lacks — but never outweighs a name hit, so "pull request"
+* lists the `*pull_request*` tools before a tool whose title merely mentions
+* them. No regex is ever built from the query (S5: descriptions are hostile
+* input).
+*
+* Everything rendered comes from the S5-untrusted catalog, so names and
+* purposes are neutralized in the text rendering. `structuredContent.tools[].name`
+* stays verbatim: it is the key the model hands back to `describe_tool` and
+* `call_tool`, and JSON escaping already renders it inert there.
+*/
+/** Page size — a transport bound, independent of the R37 inline threshold. */
+const DEFAULT_SEARCH_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+/** `query` is capped (R33): its words are matched as plain substrings, never a regex. */
+const MAX_QUERY_CHARS = 200;
+/** Summarize one catalog entry (R33). */
+function summarizeTool(entry, policy) {
+	return {
+		name: entry.name,
+		purpose: purposeSentence(entry.description) ?? "(no description)",
+		posture: postureOf(decidePolicy(entry, policy)),
+		destructive: entry.annotations?.destructiveHint === true
+	};
+}
+/**
+* Run `search_tools`. Throws a `validate`-phase {@link ProjectionError} for a
+* malformed cursor, one issued for a different query, or one pointing past
+* the end of the results (R33).
+*/
+function searchTools(catalog, args, options = {}) {
+	const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, options.pageSize ?? 50));
+	const rawQuery = args.query ?? "";
+	const query = rawQuery.slice(0, 200);
+	const queryTruncated = rawQuery.length > 200;
+	const offset = decodeCursor(args.cursor, query);
+	const matches = rankTools(dedupeTools(catalog.tools), query);
+	if (offset > 0 && offset >= matches.length) throw cursorError("cursor is past the end of the results");
+	const slice = matches.slice(offset, offset + pageSize);
+	const tools = slice.map((entry) => summarizeTool(entry, options.policy));
+	const end = offset + slice.length;
+	const page = {
+		tools,
+		total: matches.length,
+		...end < matches.length ? { nextCursor: encodeCursor(query, end) } : {}
+	};
+	return {
+		content: [{
+			type: "text",
+			text: renderPage(catalog, page, query, offset, queryTruncated)
+		}],
+		structuredContent: { ...page }
+	};
+}
+/**
+* The declared tools closest to a name the catalog does not have: the
+* name's tokens (`create_issue` → `create`, `issue`) ranked exactly as a
+* `search_tools` query is (D10), kept only when at least one token hit the
+* tool's NAME — a description-only hit (`directory` → `list_dir`) is too
+* loose to put in front of the model as "did you mean" — top `limit`.
+* Empty when nothing qualifies.
+*
+* The name is cut at `MAX_QUERY_CHARS` before ranking, the same R33 cap
+* `searchTools` applies to its query, so an unknown-name `call_tool` costs
+* what a `search_tools` call costs however long the guessed name is (the
+* catalog lookup it failed was an O(1) map miss; this is the first thing
+* that scans the catalog with the name).
+*/
+function suggestTools(catalog, name, limit = 3) {
+	const query = name.slice(0, 200);
+	if (tokenize(query).length === 0) return [];
+	return scoreTools(dedupeTools(catalog.tools), query).filter((item) => item.nameHits > 0).slice(0, Math.max(0, limit)).map((item) => item.entry.name);
+}
+/** A tool name — the caller's or the catalog's — quoted for an error (S5). */
+function inertName(text) {
+	return JSON.stringify(capLength(neutralizeControlChars(text), 200));
+}
+/** `"a"`, `"a" or "b"`, `"a", "b" or "c"`. */
+function listNames(names) {
+	if (names.length <= 1) return names.join("");
+	return `${names.slice(0, -1).join(", ")} or ${names[names.length - 1] ?? ""}`;
+}
+/**
+* The `validate` error for a tool name the catalog does not declare, from
+* `call_tool` or `describe_tool` (R34, R35): names the closest declared
+* tools when there are any, then points at `search_tools`. A model that
+* guessed `create_issue` learns `issue_write` in the same turn instead of
+* three turns later. Every name shown is S5-untrusted: neutralized, capped
+* and quoted.
+*/
+function unknownToolError(catalog, name, via) {
+	const suggestions = suggestTools(catalog, name).map(inertName);
+	const didYouMean = suggestions.length === 0 ? "" : `Did you mean ${listNames(suggestions)}? `;
+	return new ProjectionError("validate", `Unknown tool ${inertName(name)}: the wrapped server does not declare it`, { hint: `${didYouMean}Call search_tools to list the tools this server declares, then ${via} with one of those names exactly.` });
+}
+/**
+* Tokens of a query: lowercased, NFC-normalized, split on anything that is
+* not a letter, combining mark, or digit — so a decomposed `é` stays inside
+* its word and matches a precomposed one in the catalog. Tokens under two
+* characters are dropped; when nothing survives, the whole trimmed query is
+* the one token.
+*/
+function tokenize(query) {
+	const lowered = query.toLowerCase().normalize("NFC");
+	const tokens = lowered.split(/[^\p{L}\p{M}\p{N}]+/u).filter((token) => token.length >= 2);
+	if (tokens.length > 0) return tokens;
+	const whole = lowered.trim();
+	return whole.length > 0 ? [whole] : [];
+}
+/**
+* Filter and rank the catalog for a query (D10). An empty query returns
+* every tool in catalog order; a query with no token at all (whitespace
+* only) matches nothing.
+*/
+function rankTools(tools, query) {
+	if (query.length === 0) return tools;
+	return scoreTools(tools, query).map((item) => item.entry);
+}
+/**
+* The tools a query matches, best first (D10): a token scores +2 in the
+* name and, independently, +1 in the title or description. The sort is
+* stable, so equal scores keep catalog order and paging stays deterministic
+* for a given query. A query with no token matches nothing.
+*/
+function scoreTools(tools, query) {
+	const tokens = new Set(tokenize(query));
+	if (tokens.size === 0) return [];
+	const scored = [];
+	for (const entry of tools) {
+		const name = entry.name.toLowerCase();
+		const title = (entry.annotations?.title ?? "").toLowerCase();
+		const description = (entry.description ?? "").toLowerCase();
+		let nameHits = 0;
+		let score = 0;
+		for (const token of tokens) {
+			if (name.includes(token)) {
+				nameHits += 1;
+				score += 2;
+			}
+			if (title.includes(token) || description.includes(token)) score += 1;
+		}
+		if (score > 0) scored.push({
+			entry,
+			score,
+			nameHits
+		});
+	}
+	return scored.sort((a, b) => b.score - a.score);
+}
+function renderPage(catalog, page, query, offset, queryTruncated) {
+	const lines = [];
+	if (queryTruncated) lines.push(`(query truncated to its first 200 characters)`, "");
+	const scope = query.length > 0 ? ` matching ${JSON.stringify(neutralizeControlChars(query))}` : "";
+	if (page.tools.length === 0) lines.push(`No tools${scope} on server ${inertIdentity$1(catalog.identity)}.`);
+	else {
+		lines.push(`Tools ${offset + 1}–${offset + page.tools.length} of ${page.total}${scope} (server ${inertIdentity$1(catalog.identity)}):`);
+		for (const tool of page.tools) {
+			const name = capLength(neutralizeControlChars(tool.name), 200);
+			const flags = tool.destructive ? `${tool.posture}, destructive` : tool.posture;
+			lines.push(`- ${name} — ${tool.purpose} [${flags}]`);
+		}
+	}
+	if (page.nextCursor !== void 0) lines.push("", `More tools follow: call search_tools again with cursor ${JSON.stringify(page.nextCursor)}.`);
+	lines.push("", "Call describe_tool with a name before calling a tool whose arguments you have not seen.");
+	return lines.join("\n");
+}
+function encodeCursor(query, offset) {
+	const payload = {
+		q: query,
+		o: offset
+	};
+	return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function cursorError(why) {
+	return new ProjectionError("validate", `search_tools cursor is not usable: ${why}`, { hint: "Pass a cursor exactly as a previous search_tools result returned it, with the same query; or omit it to start from the first page." });
+}
+/**
+* Decode a cursor to its offset. Only the fields read (`q`, `o`) are
+* validated: a payload carrying extra keys is accepted, since the cursor is
+* opaque data and nothing else in it is consumed. The offset's upper bound
+* is checked by the caller once the match count is known.
+*/
+function decodeCursor(cursor, query) {
+	if (cursor === void 0 || cursor.length === 0) return 0;
+	if (cursor.length > 1024) throw cursorError("too long");
+	let payload;
+	try {
+		payload = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+	} catch {
+		throw cursorError("malformed");
+	}
+	if (typeof payload !== "object" || payload === null || typeof payload.q !== "string" || typeof payload.o !== "number") throw cursorError("malformed");
+	const { q, o } = payload;
+	if (!Number.isInteger(o) || o < 0) throw cursorError("malformed");
+	if (q !== query) throw cursorError("it was issued for a different query");
+	return o;
+}
+//#endregion
 //#region src/catalog/validate-args.ts
 /**
 * Structural argument validation for `call_tool` (PRD R35.1).
@@ -2378,7 +2818,7 @@ async function callTool(args, deps) {
 		const toolArgs = normalizeArgs(args.args, caps);
 		if (args.requestState !== void 0) return await resume(args, toolArgs, deps, caps);
 		const entry = findTool(deps.catalog, args.name);
-		if (entry === void 0) throw unknownTool(args.name);
+		if (entry === void 0) throw unknownToolError(deps.catalog, args.name, "call_tool");
 		validateArgsShape(entry.name, toolArgs, entry.inputSchema);
 		const request = canonicalRequest(entry.name, toolArgs);
 		switch (decidePolicy(entry, deps.policy)) {
@@ -2407,9 +2847,6 @@ function normalizeArgs(raw, caps) {
 	if (size > caps.maxInputBytes) throw new ProjectionError("cap_exceeded", `call_tool args serialize to ${size} bytes, exceeding the limit of ${caps.maxInputBytes}`, { hint: `Shrink the arguments to at most ${caps.maxInputBytes} bytes of JSON.` });
 	return raw;
 }
-function unknownTool(name) {
-	return new ProjectionError("validate", `Unknown tool ${inert(name)}: the wrapped server does not declare it`, { hint: "Call search_tools to list the tools this server declares, then call_tool with one of those names exactly." });
-}
 function suspend(entry, toolArgs, request, deps) {
 	const gate = legacySuspendError(deps, {
 		subject: "this call",
@@ -2463,7 +2900,7 @@ async function resume(args, toolArgs, deps, caps) {
 	await assertNotReplayed(payload, deps.replayCache);
 	const recorded = payload.pending[CALL_KEY];
 	const entry = findTool(deps.catalog, recorded.name);
-	if (entry === void 0) throw unknownTool(recorded.name);
+	if (entry === void 0) throw unknownToolError(deps.catalog, recorded.name, "call_tool");
 	if (decidePolicy(entry, deps.policy) === "deny") return denied(entry);
 	const view = inputResponse(args.inputResponses, CALL_KEY);
 	if (view.kind !== "elicit" || view.action !== "accept") {
@@ -2526,7 +2963,12 @@ function outcome(value) {
 }
 function renderOutcome(value) {
 	switch (value.status) {
-		case "ok": return value.truncated === true ? `${JSON.stringify(value, null, 2)}\n\nThe call ran, but its result is ${value.outputBytes} bytes, over this server's result limit; output is a preview of the first ${RESULT_PREVIEW_CHARS} characters of its JSON. Retrying returns the same preview — work from it, or call the tool with arguments that return less.` : JSON.stringify(value, null, 2);
+		case "ok": {
+			const head = `call_tool ${inert(value.tool)}: ok`;
+			const body = neutralizeControlChars(typeof value.output === "string" ? value.output : JSON.stringify(value.output, null, 2) ?? "null", { allowNewline: true });
+			if (value.truncated === true) return `${head} (result truncated)\n\n${body}\n\nThe call ran, but its result is ${value.outputBytes} bytes, over this server's result limit; the output above is the first ${RESULT_PREVIEW_CHARS} characters of its JSON. Retrying returns the same preview — work from it, or call the tool with arguments that return less.`;
+			return `${head}\n\n${body}`;
+		}
 		case "declined": return `The user declined ${inert(value.tool)}${value.reason !== void 0 ? ` — ${JSON.stringify(value.reason)}` : ""}. Nothing was executed. Do not retry this call unless the user asks for it.`;
 		case "denied_by_policy": return `${inert(value.tool)} is blocked by this server's policy. Nothing was executed; the policy is not something you can change.`;
 	}
@@ -2771,119 +3213,6 @@ function neutralize(text) {
 	return neutralizeControlChars(capLength(text, MAX_STRING_CHARS), { allowNewline: true });
 }
 //#endregion
-//#region src/catalog/search.ts
-/**
-* `search_tools` — the catalog projection's discovery tool (PRD R33, S5).
-*
-* Returns one page of the wrapped server's tools in catalog order — name,
-* a one-line purpose, the policy posture in plain words, and whether the
-* server marks the tool destructive — optionally filtered by a plain
-* substring. It is the lazy alternative to `discover_apis`' inline
-* overview: O(tools the model looks at), not O(tools the server has).
-*
-* Everything rendered comes from the S5-untrusted catalog, so names and
-* purposes are neutralized in the text rendering. `structuredContent.tools[].name`
-* stays verbatim: it is the key the model hands back to `describe_tool` and
-* `call_tool`, and JSON escaping already renders it inert there.
-*/
-/** Page size — a transport bound, independent of the R37 inline threshold. */
-const DEFAULT_SEARCH_PAGE_SIZE = 50;
-const MAX_PAGE_SIZE = 200;
-/** `query` is capped (R33): it is matched as a plain substring, never a regex. */
-const MAX_QUERY_CHARS = 200;
-/** Map a policy decision to its plain-words posture (R33). */
-function postureOf(decision) {
-	switch (decision) {
-		case "auto": return "runs immediately";
-		case "ask": return "asks for approval";
-		case "deny": return "blocked by policy";
-	}
-}
-/** Summarize one catalog entry (R33). */
-function summarizeTool(entry, policy) {
-	return {
-		name: entry.name,
-		purpose: purposeSentence(entry.description) ?? "(no description)",
-		posture: postureOf(decidePolicy(entry, policy)),
-		destructive: entry.annotations?.destructiveHint === true
-	};
-}
-/**
-* Run `search_tools`. Throws a `validate`-phase {@link ProjectionError} for a
-* malformed cursor, one issued for a different query, or one pointing past
-* the end of the results (R33).
-*/
-function searchTools(catalog, args, options = {}) {
-	const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, options.pageSize ?? 50));
-	const query = (args.query ?? "").slice(0, 200);
-	const offset = decodeCursor(args.cursor, query);
-	const needle = query.toLowerCase();
-	const matches = dedupeTools(catalog.tools).filter((entry) => needle.length === 0 || entry.name.toLowerCase().includes(needle) || (entry.description ?? "").toLowerCase().includes(needle));
-	if (offset > 0 && offset >= matches.length) throw cursorError("cursor is past the end of the results");
-	const slice = matches.slice(offset, offset + pageSize);
-	const tools = slice.map((entry) => summarizeTool(entry, options.policy));
-	const end = offset + slice.length;
-	const page = {
-		tools,
-		total: matches.length,
-		...end < matches.length ? { nextCursor: encodeCursor(query, end) } : {}
-	};
-	return {
-		content: [{
-			type: "text",
-			text: renderPage(catalog, page, query, offset)
-		}],
-		structuredContent: { ...page }
-	};
-}
-function renderPage(catalog, page, query, offset) {
-	const lines = [];
-	const scope = query.length > 0 ? ` matching ${JSON.stringify(neutralizeControlChars(query))}` : "";
-	if (page.tools.length === 0) lines.push(`No tools${scope} on server ${inertIdentity$1(catalog.identity)}.`);
-	else {
-		lines.push(`Tools ${offset + 1}–${offset + page.tools.length} of ${page.total}${scope} (server ${inertIdentity$1(catalog.identity)}):`);
-		for (const tool of page.tools) {
-			const name = capLength(neutralizeControlChars(tool.name), 200);
-			const flags = tool.destructive ? `${tool.posture}, destructive` : tool.posture;
-			lines.push(`- ${name} — ${tool.purpose} [${flags}]`);
-		}
-	}
-	if (page.nextCursor !== void 0) lines.push("", `More tools follow: call search_tools again with cursor ${JSON.stringify(page.nextCursor)}.`);
-	lines.push("", "Call describe_tool with a name before calling a tool whose arguments you have not seen.");
-	return lines.join("\n");
-}
-function encodeCursor(query, offset) {
-	const payload = {
-		q: query,
-		o: offset
-	};
-	return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
-}
-function cursorError(why) {
-	return new ProjectionError("validate", `search_tools cursor is not usable: ${why}`, { hint: "Pass a cursor exactly as a previous search_tools result returned it, with the same query; or omit it to start from the first page." });
-}
-/**
-* Decode a cursor to its offset. Only the fields read (`q`, `o`) are
-* validated: a payload carrying extra keys is accepted, since the cursor is
-* opaque data and nothing else in it is consumed. The offset's upper bound
-* is checked by the caller once the match count is known.
-*/
-function decodeCursor(cursor, query) {
-	if (cursor === void 0 || cursor.length === 0) return 0;
-	if (cursor.length > 1024) throw cursorError("too long");
-	let payload;
-	try {
-		payload = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
-	} catch {
-		throw cursorError("malformed");
-	}
-	if (typeof payload !== "object" || payload === null || typeof payload.q !== "string" || typeof payload.o !== "number") throw cursorError("malformed");
-	const { q, o } = payload;
-	if (!Number.isInteger(o) || o < 0) throw cursorError("malformed");
-	if (q !== query) throw cursorError("it was issued for a different query");
-	return o;
-}
-//#endregion
 //#region src/catalog/describe.ts
 /**
 * `describe_tool` — everything the model needs to call one tool (PRD R34).
@@ -2908,12 +3237,12 @@ const MAX_DESCRIPTION_CHARS = 2e3;
 */
 function describeTool(catalog, args, options = {}) {
 	const entry = findTool(catalog, args.name);
-	if (entry === void 0) throw new ProjectionError("validate", `Unknown tool ${JSON.stringify(capLength(neutralizeControlChars(args.name), 200))}: the wrapped server does not declare it`, { hint: "Call search_tools to list the tools this server declares, then describe_tool with one of those names exactly." });
+	if (entry === void 0) throw unknownToolError(catalog, args.name, "describe_tool");
 	const input = sanitizeSchema(entry.inputSchema);
 	const output = entry.outputSchema !== void 0 ? sanitizeSchema(entry.outputSchema) : void 0;
 	const annotations = sanitizeAnnotations(entry.annotations);
 	const description = entry.description !== void 0 && entry.description.trim().length > 0 ? neutralizeControlChars(capLength(entry.description.trim(), MAX_DESCRIPTION_CHARS), { allowNewline: true }) : void 0;
-	const types = options.toolTypes?.get(entry.name)?.dts;
+	const types = args.types === true ? options.toolTypes?.get(entry.name)?.dts : void 0;
 	const described = {
 		name: entry.name,
 		...description !== void 0 ? { description } : {},
@@ -3339,7 +3668,7 @@ function clampInlineThreshold(raw) {
 function discoverApis(catalog, overview, options = {}) {
 	const threshold = clampInlineThreshold(options.inlineThreshold);
 	const toolCount = dedupeTools(catalog.tools).length;
-	const toolsSection = options.catalog === true && toolCount > threshold ? `Tools: ${toolCount} on this server — too many to list here. Call search_tools to find tools by name or purpose and describe_tool for a tool's arguments and types; the full definitions are in ${RESOURCE_URIS.toolTypes}.` : overview;
+	const toolsSection = options.catalog === true && toolCount > threshold ? `Tools: ${toolCount} on this server — too many to list here. Call search_tools to find tools by name or purpose and describe_tool for a tool's arguments (types: true adds its TypeScript); the full definitions are in ${RESOURCE_URIS.toolTypes}.` : overview;
 	const inline = [
 		`Projection code mode over ${inertIdentity$1(catalog.identity)}.`,
 		"",
@@ -3573,39 +3902,67 @@ function toCatalogEntry(tool) {
 }
 /**
 * Bounds on `tools/list` introspection. A wrapped server is untrusted (S5)
-* and could return an endless chain of `nextCursor` pages, or a tool count
-* large enough to blow up the generated artifacts; either would hang or
-* exhaust the process before any workflow runs.
+* and could return an endless chain of `nextCursor` pages, a cursor that
+* repeats, or a tool count large enough to blow up the generated artifacts;
+* any of these would hang or exhaust the process before any workflow runs.
+*
+* Projection walks the pages itself and enforces these bounds as each page
+* arrives (D12). It does not use the SDK's no-cursor `listTools()`, which
+* aggregates every page before returning and is bounded only by the
+* caller's `listMaxPages` client option (0 = unlimited).
 */
 const MAX_TOOL_LIST_PAGES = 100;
 const MAX_TOOLS = 2e3;
+function limitError(alias, detail) {
+	return new ProjectionError("protocol", `wrapped server "${alias}" exceeded introspection limits (${detail})`, { hint: `Projection reads at most ${MAX_TOOL_LIST_PAGES} tools/list pages and ${MAX_TOOLS} tools, and rejects a repeated cursor. Wrap a server with a bounded tool surface whose tools/list pagination terminates.` });
+}
+async function fetchToolsPage(client, cursor) {
+	if (cursor === void 0) return client.request({
+		method: "tools/list",
+		params: {}
+	});
+	return client.listTools({ cursor });
+}
 async function listAllTools(client, alias) {
+	if (client.getServerCapabilities()?.tools === void 0) return [];
 	const tools = [];
+	const cursors = /* @__PURE__ */ new Set();
 	let cursor;
 	let pages = 0;
-	try {
-		do {
-			const page = await client.listTools(cursor !== void 0 ? { cursor } : void 0);
-			tools.push(...page.tools);
-			cursor = page.nextCursor;
-			pages += 1;
-			if (pages >= MAX_TOOL_LIST_PAGES || tools.length >= MAX_TOOLS) {
-				if (cursor !== void 0) throw new ProjectionError("protocol", `wrapped server "${alias}" exceeded introspection limits (${pages} pages, ${tools.length} tools)`, { hint: `Projection reads at most ${MAX_TOOL_LIST_PAGES} tools/list pages and ${MAX_TOOLS} tools. Wrap a server with a bounded tool surface.` });
-				break;
-			}
-		} while (cursor !== void 0);
-	} catch (err) {
-		if (err instanceof ProjectionError) throw err;
-		if (err instanceof ProtocolError && err.code === ProtocolErrorCode.MethodNotFound) return [];
-		if (err instanceof Error && /does not support tools/i.test(err.message)) return [];
-		throw new ProjectionError("protocol", `tools/list failed for wrapped server "${alias}": ${err instanceof Error ? err.message : String(err)}`, {
-			hint: "Check that the wrapped server is running, connected, and supports the tools capability.",
-			cause: err
-		});
-	}
+	do {
+		let page;
+		try {
+			page = await fetchToolsPage(client, cursor);
+		} catch (err) {
+			if (pages === 0 && err instanceof ProtocolError && err.code === ProtocolErrorCode.MethodNotFound) return [];
+			throw new ProjectionError("protocol", `tools/list failed for wrapped server "${alias}": ${err instanceof Error ? err.message : String(err)}`, {
+				hint: "Check that the wrapped server is running, connected, and supports the tools capability.",
+				cause: err
+			});
+		}
+		pages += 1;
+		tools.push(...page.tools);
+		if (tools.length > MAX_TOOLS) throw limitError(alias, `declares at least ${tools.length} tools, over the cap of ${MAX_TOOLS}`);
+		cursor = page.nextCursor;
+		if (cursor === void 0) break;
+		if (cursors.has(cursor)) throw limitError(alias, `tools/list pagination loops: page ${pages} returned cursor ${JSON.stringify(cursor.slice(0, 64))} a second time`);
+		if (pages >= MAX_TOOL_LIST_PAGES) throw limitError(alias, `tools/list still returns nextCursor after ${pages} pages, over the cap of ${MAX_TOOL_LIST_PAGES}`);
+		cursors.add(cursor);
+	} while (cursor !== void 0);
 	return tools;
 }
-async function buildServerCatalog(alias, client) {
+/**
+* True when `source` is shaped like an `McpServer` (a `server` property plus
+* `connect`/`registerTool`, and no `listTools`, which a `Client` has) yet
+* failed the `instanceof McpServer` check: the caller's project resolved a
+* second copy of `@modelcontextprotocol/server`.
+*/
+function looksLikeForeignMcpServer(source) {
+	if (typeof source !== "object" || source === null) return false;
+	const candidate = source;
+	return "server" in candidate && (typeof candidate["connect"] === "function" || typeof candidate["registerTool"] === "function") && typeof candidate["listTools"] !== "function";
+}
+async function introspectServer(alias, client) {
 	const tools = await listAllTools(client, alias);
 	const info = client.getServerVersion();
 	const catalog = {
@@ -3615,7 +3972,10 @@ async function buildServerCatalog(alias, client) {
 	};
 	const instructions = client.getInstructions();
 	if (instructions !== void 0) catalog.instructions = instructions;
-	return catalog;
+	return {
+		catalog,
+		definitions: new Map(tools.map((tool) => [tool.name, tool]))
+	};
 }
 /** Extract a one-line error message from an `isError` tool result's content. */
 function errorTextFromContent(content) {
@@ -3644,9 +4004,17 @@ function pickResultValue(result) {
 var Introspector = class Introspector {
 	#connections;
 	#catalog;
-	constructor(connections, catalog) {
+	#definitions;
+	constructor(connections, introspected) {
 		this.#connections = connections;
-		this.#catalog = catalog;
+		this.#catalog = Introspector.#catalogOf(introspected);
+		this.#definitions = Introspector.#definitionsOf(introspected);
+	}
+	static #catalogOf(introspected) {
+		return { servers: new Map([...introspected].map(([alias, server]) => [alias, server.catalog])) };
+	}
+	static #definitionsOf(introspected) {
+		return new Map([...introspected].map(([alias, server]) => [alias, server.definitions]));
 	}
 	static async create(sources) {
 		const aliases = Object.keys(sources);
@@ -3658,13 +4026,13 @@ var Introspector = class Introspector {
 			if (source === void 0) return;
 			const connection = await Introspector.#connect(alias, source);
 			connections.set(alias, connection);
-			servers.set(alias, await buildServerCatalog(alias, connection.client));
+			servers.set(alias, await introspectServer(alias, connection.client));
 		}))).find((result) => result.status === "rejected");
 		if (failed !== void 0) {
 			await Introspector.#closeConnections(connections);
 			throw failed.reason;
 		}
-		return new Introspector(connections, { servers });
+		return new Introspector(connections, servers);
 	}
 	static async #connect(alias, source) {
 		if (source instanceof McpServer) {
@@ -3678,6 +4046,7 @@ var Introspector = class Introspector {
 				owned: true
 			};
 		}
+		if (looksLikeForeignMcpServer(source)) throw new ProjectionError("protocol", `Wrapped server "${alias}" looks like an McpServer from a second copy of @modelcontextprotocol/server, not the one Projection uses.`, { hint: `Projection pins @modelcontextprotocol/server ${MCP_SDK_VERSION} exactly. Depend on that exact version so your package manager installs a single copy (check with \`npm ls @modelcontextprotocol/server\` or \`pnpm why @modelcontextprotocol/server\`).` });
 		return {
 			client: source,
 			owned: false
@@ -3692,8 +4061,9 @@ var Introspector = class Introspector {
 	}
 	/** Re-read `tools/list` from every wrapped server and rebuild the catalog. */
 	async refresh() {
-		const rebuilt = await Promise.all([...this.#connections].map(async ([alias, connection]) => [alias, await buildServerCatalog(alias, connection.client)]));
-		this.#catalog = { servers: new Map(rebuilt) };
+		const rebuilt = new Map(await Promise.all([...this.#connections].map(async ([alias, connection]) => [alias, await introspectServer(alias, connection.client)])));
+		this.#catalog = Introspector.#catalogOf(rebuilt);
+		this.#definitions = Introspector.#definitionsOf(rebuilt);
 		return this.#catalog;
 	}
 	/**
@@ -3710,11 +4080,12 @@ var Introspector = class Introspector {
 	async callTool(alias, name, args) {
 		const connection = this.#connections.get(alias);
 		if (connection === void 0) throw new ProjectionError("protocol", `Unknown wrapped-server alias "${alias}".`, { hint: `Known aliases: ${[...this.#connections.keys()].join(", ")}. v1 wraps exactly one server under the "default" alias.` });
+		const toolDefinition = this.#definitions.get(alias)?.get(name);
 		try {
 			const result = await connection.client.callTool({
 				name,
 				arguments: args
-			});
+			}, toolDefinition !== void 0 ? { toolDefinition } : void 0);
 			if (result.isError === true) return {
 				ok: false,
 				error: {
@@ -4000,18 +4371,35 @@ function pascalBase(toolName, taken) {
 	taken.add(base);
 	return base;
 }
-function approvalNote(tool) {
-	if (tool.annotations?.readOnlyHint === true) return "Read-only: executes immediately, no user approval required.";
-	if (tool.annotations?.destructiveHint === true) return "DESTRUCTIVE write: pauses the machine for user approval before executing.";
-	return "Write (or unannotated): pauses the machine for user approval before executing.";
+/**
+* One posture vocabulary for every surface (R33): the same words
+* `search_tools` and `describe_tool` use, so a model never sees
+* "[read-only]" on one surface and "runs immediately" on another.
+*/
+function postureNote(posture) {
+	switch (posture) {
+		case "runs immediately": return "Runs immediately: no user approval required.";
+		case "asks for approval": return "Asks for approval: pauses for the user to approve this exact call before it runs.";
+		case "blocked by policy": return "Blocked by policy: calls to this tool are refused.";
+	}
+}
+/**
+* The posture sentence plus, whatever the posture, the server's destructive
+* marker: an `auto` or `deny` override does not make a destructive tool any
+* less so, and `search_tools` / `describe_tool` show the flag on every
+* posture too.
+*/
+function approvalNote(tool, policy) {
+	const note = postureNote(postureOf(decidePolicy(tool, policy)));
+	return tool.annotations?.destructiveHint === true ? `${note} The server marks this tool destructive.` : note;
 }
-function toolDoc(tool) {
+function toolDoc(tool, policy) {
 	const lines = [];
 	if (tool.description !== void 0 && tool.description.length > 0) lines.push(tool.description.trim(), "");
-	lines.push(approvalNote(tool));
+	lines.push(approvalNote(tool, policy));
 	return lines.join("\n");
 }
-function generateDts(server) {
+function generateDts(server, policy) {
 	const taken = /* @__PURE__ */ new Set();
 	const sections = [];
 	const memberLines = [];
@@ -4039,11 +4427,11 @@ function generateDts(server) {
 		const optional = schemaRequiresArgs(tool.inputSchema) ? "" : "?";
 		const returnType = typeNames.output ?? "unknown";
 		const signature = `${propertyKey(tool.name)}: (args${optional}: ${typeNames.input}) => Promise<${returnType}>;`;
-		memberLines.push(docComment(toolDoc(tool), "  "), `  ${signature}`);
+		memberLines.push(docComment(toolDoc(tool, policy), "  "), `  ${signature}`);
 		toolTypes.set(tool.name, {
 			inputAlias: typeNames.input,
 			...typeNames.output !== void 0 ? { outputAlias: typeNames.output } : {},
-			dts: [...aliasSections, `// Member of the \`tools\` surface:\n${docComment(toolDoc(tool), "")}\n${signature}`].join("\n\n")
+			dts: [...aliasSections, `// Member of the \`tools\` surface:\n${docComment(toolDoc(tool, policy), "")}\n${signature}`].join("\n\n")
 		});
 	}
 	const surfaceDoc = docComment(`Namespaced tool surface of wrapped server ${commentSafe(server.identity)}.`, "");
@@ -4091,24 +4479,25 @@ function generateBridgeSource(server) {
 		""
 	].join("\n");
 }
-function overviewFlags(tool) {
-	if (tool.annotations?.readOnlyHint === true) return "[read-only]";
-	if (tool.annotations?.destructiveHint === true) return "[approval, destructive]";
-	return "[approval]";
+function overviewFlags(tool, policy) {
+	const posture = postureOf(decidePolicy(tool, policy));
+	return tool.annotations?.destructiveHint === true ? `[${posture}, destructive]` : `[${posture}]`;
 }
-function firstLine(text) {
-	if (text === void 0) return "(no description)";
-	const line = (text.split("\n")[0] ?? "").trim();
-	if (line.length === 0) return "(no description)";
-	return line.length > 100 ? `${line.slice(0, 97)}...` : line;
+/**
+* The one-line purpose shown per tool: the first sentence of the
+* description, neutralized and capped — the same rule `search_tools` uses
+* (R33), so both projections describe a tool identically.
+*/
+function purposeLine(text) {
+	return purposeSentence(text) ?? "(no description)";
 }
-function generateOverview(server) {
+function generateOverview(server, policy) {
 	const lines = [`Tools (server: ${inertIdentity$1(server.identity)}):`];
 	if (server.tools.length === 0) lines.push("  (none)");
 	for (const tool of server.tools) {
 		const name = capLength(neutralizeControlChars(tool.name), 200);
-		const description = neutralizeControlChars(firstLine(tool.description));
-		lines.push(`- ${name} ${overviewFlags(tool)} — ${description}`);
+		const description = purposeLine(tool.description);
+		lines.push(`- ${name} ${overviewFlags(tool, policy)} — ${description}`);
 	}
 	return `${lines.join("\n")}\n`;
 }
@@ -4128,13 +4517,13 @@ function resolveSingleServer(catalog) {
 * exactly one server in v1, per R30's single-instance instantiation) or a
 * {@link ServerCatalog} directly.
 */
-function generateToolTypes(catalog) {
+function generateToolTypes(catalog, options = {}) {
 	const server = dedupeToolNames(resolveSingleServer(catalog));
-	const { dts, toolTypes } = generateDts(server);
+	const { dts, toolTypes } = generateDts(server, options.policy);
 	return {
 		dts,
 		bridgeSource: generateBridgeSource(server),
-		overview: generateOverview(server),
+		overview: generateOverview(server, options.policy),
 		toolTypes
 	};
 }
@@ -4168,9 +4557,9 @@ Author a module that default-exports a machine built with XState v5 setup(...).c
 
 Call discover_apis first for the tool types, the full authoring contract, and worked examples.`;
 const DISCOVER_APIS_DESCRIPTION = `Return this server's tool type definitions, the machine authoring contract, and worked examples. Call this before authoring a machine for execute_machine.`;
-const SEARCH_TOOLS_DESCRIPTION = `List this server's tools, one page at a time, optionally filtered by a plain substring on name and description. Each entry gives the tool's name, a one-line purpose, whether it runs immediately or asks the user for approval, and whether the server marks it destructive. Call describe_tool before calling a tool whose arguments you have not seen.`;
+const SEARCH_TOOLS_DESCRIPTION = `List this server's tools, one page at a time, optionally matched against a query: the query is split into words, a tool matches if any word appears in its name, title or description, and matches are ranked (name hits weigh more), so a guessed name like create_issue or a phrase like "comment on a pull request" works. Each entry gives the tool's name, a one-line purpose, whether it runs immediately, asks the user for approval, or is blocked by policy, and whether the server marks it destructive. Call describe_tool before calling a tool whose arguments you have not seen.`;
 const CALL_TOOL_DESCRIPTION = `Run one of this server's tools by name with a JSON object of arguments. Call describe_tool first to see the tool's arguments. Read-only tools run immediately. Any other tool first asks the user to approve this exact call; a result with status "declined" means the user said no — nothing ran, and you must not retry the same call unless the user asks for it. Status "denied_by_policy" means the server's policy blocks the tool. For several steps, branching on results, or a workflow worth saving, author a machine and use execute_machine instead.`;
-const DESCRIBE_TOOL_DESCRIPTION = `Return one tool's description, its input and output JSON Schemas, its approval posture, and its generated TypeScript types. Call this before call_tool, or when authoring a machine that uses the tool.`;
+const DESCRIBE_TOOL_DESCRIPTION = `Return one tool's description, its input and output JSON Schemas, and its approval posture. Call this before call_tool. Pass types: true to also get the tool's generated TypeScript when authoring a machine for execute_machine.`;
 /**
 * Wrap an MCP server (an in-process instance or a connected client) into a
 * Projection facade.
@@ -4180,7 +4569,8 @@ async function wrapMcpServer(source, options) {
 	const introspector = await createIntrospector({ [DEFAULT_SERVER_ALIAS]: source });
 	const catalog = introspector.catalog.servers.get(DEFAULT_SERVER_ALIAS);
 	if (catalog === void 0) throw new ProjectionError("protocol", "introspection produced no catalog for the wrapped server", { hint: "Check that the wrapped server initialized successfully." });
-	const { dts, bridgeSource, overview, toolTypes } = generateToolTypes(catalog);
+	const policy = options.policy !== void 0 ? Object.freeze({ ...options.policy }) : void 0;
+	const { dts, bridgeSource, overview, toolTypes } = generateToolTypes(catalog, { policy });
 	return new Facade({
 		introspector,
 		catalog,
@@ -4191,6 +4581,7 @@ async function wrapMcpServer(source, options) {
 		resources: buildResources(catalog, dts),
 		instructions: buildInstructions(catalog, options.codeModePreamble, projections),
 		options,
+		...policy !== void 0 ? { policy } : {},
 		projections
 	});
 }
@@ -4239,13 +4630,13 @@ var Facade = class {
 	* `exactOptionalPropertyTypes`: absent options stay absent.
 	*/
 	gateDeps(era, clientCanElicit) {
-		const { options } = this.deps;
+		const { options, policy } = this.deps;
 		return {
 			catalog: this.deps.catalog,
 			executor: this.deps.introspector,
 			blob: options.blob,
 			...options.caps !== void 0 ? { caps: options.caps } : {},
-			...options.policy !== void 0 ? { policy: options.policy } : {},
+			...policy !== void 0 ? { policy } : {},
 			...options.redact !== void 0 ? { redact: options.redact } : {},
 			...era !== void 0 ? { protocolEra: era } : {},
 			...options.compat?.legacyElicitation === true ? { legacyElicitation: true } : {},
@@ -4279,7 +4670,7 @@ var Facade = class {
 	}
 	/** `exactOptionalPropertyTypes`: an absent policy must stay absent. */
 	policyOption() {
-		const { policy } = this.deps.options;
+		const { policy } = this.deps;
 		return policy !== void 0 ? { policy } : {};
 	}
 	/**
@@ -4319,7 +4710,7 @@ var Facade = class {
 			title: "Search the tool catalog",
 			description: SEARCH_TOOLS_DESCRIPTION,
 			inputSchema: z.object({
-				query: z.string().optional().describe("Plain substring to match on name and description."),
+				query: z.string().optional().describe("Words to match against tool names, titles and descriptions; any word matches, name hits weigh more."),
 				cursor: z.string().optional().describe("nextCursor from a previous page.")
 			}),
 			annotations: { readOnlyHint: true }
@@ -4330,9 +4721,15 @@ var Facade = class {
 		server.registerTool("describe_tool", {
 			title: "Describe one tool",
 			description: DESCRIBE_TOOL_DESCRIPTION,
-			inputSchema: z.object({ name: z.string().describe("Tool name as listed by search_tools.") }),
+			inputSchema: z.object({
+				name: z.string().describe("Tool name as listed by search_tools."),
+				types: z.boolean().optional().describe("Also return the generated TypeScript for this tool (for authoring a machine).")
+			}),
 			annotations: { readOnlyHint: true }
-		}, (args) => this.describeTool({ name: args.name }));
+		}, (args) => this.describeTool({
+			name: args.name,
+			...args.types !== void 0 ? { types: args.types } : {}
+		}));
 		server.registerTool("call_tool", {
 			title: "Call one tool",
 			description: CALL_TOOL_DESCRIPTION,