@astral-mcp/projection 0.2.0

package/dist/index.mjs

@@ -0,0 +1,2929 @@
+import { createRequire } from "node:module";
+import { InMemoryTransport, McpServer, ProtocolError, ProtocolErrorCode, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { Client } from "@modelcontextprotocol/client";
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+import { getModuleLoader, getTypescriptSupport, loadQuickJs } from "@sebastianwessel/quickjs";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+//#region src/errors.ts
+/**
+* Error carrying the structured `isError` body every failure returns (R25).
+*/
+var ProjectionError = class extends Error {
+	phase;
+	diagnostics;
+	hint;
+	logs;
+	constructor(phase, message, options = {}) {
+		super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "ProjectionError";
+		this.phase = phase;
+		this.diagnostics = options.diagnostics ?? [];
+		this.hint = options.hint ?? "";
+		this.logs = options.logs ?? [];
+	}
+	toStructured() {
+		return {
+			phase: this.phase,
+			message: this.message,
+			diagnostics: this.diagnostics,
+			hint: this.hint,
+			logs: this.logs
+		};
+	}
+};
+/** Convert any thrown value into a StructuredError, defaulting to `runtime` phase. */
+function toStructuredError(err, logs = []) {
+	if (err instanceof ProjectionError) {
+		const structured = err.toStructured();
+		return {
+			...structured,
+			logs: structured.logs.length > 0 ? structured.logs : logs
+		};
+	}
+	return {
+		phase: "runtime",
+		message: err instanceof Error ? err.message : String(err),
+		diagnostics: [],
+		hint: "",
+		logs
+	};
+}
+//#endregion
+//#region src/introspector/introspector.ts
+/**
+* Introspector — connects to the wrapped server(s), reads `tools/list`,
+* annotations, and `instructions`, and maintains the tool catalog (PRD §7,
+* G1, R29, R30). Also implements {@link ToolExecutor}: all tool calls the
+* machine host performs against a wrapped server go through here.
+*
+* Two source kinds are supported (R4):
+*
+* - **In-process instance**: an `McpServer` from `@modelcontextprotocol/server`.
+*   The introspector connects it to an in-memory transport pair and talks to
+*   it with a real MCP client, so introspection and execution exercise the
+*   exact same code path as a remote server. The instance must be dedicated
+*   to Projection (not already connected to another transport) — Projection is
+*   the facade; the wrapped server is never exposed directly (R1).
+* - **Remote connection**: an already-connected SDK `Client`. The caller owns
+*   its lifecycle; `close()` will not touch it.
+*/
+const CLIENT_INFO = {
+	name: "projection-introspector",
+	version: "0.1.0"
+};
+function isTextBlock(block) {
+	return typeof block === "object" && block !== null && block.type === "text" && typeof block.text === "string";
+}
+function mapAnnotations(annotations) {
+	if (annotations === void 0) return void 0;
+	const mapped = {};
+	if (annotations.title !== void 0) mapped.title = annotations.title;
+	if (annotations.readOnlyHint !== void 0) mapped.readOnlyHint = annotations.readOnlyHint;
+	if (annotations.destructiveHint !== void 0) mapped.destructiveHint = annotations.destructiveHint;
+	if (annotations.idempotentHint !== void 0) mapped.idempotentHint = annotations.idempotentHint;
+	return Object.keys(mapped).length > 0 ? mapped : void 0;
+}
+function toCatalogEntry(tool) {
+	const entry = {
+		name: tool.name,
+		inputSchema: tool.inputSchema
+	};
+	if (tool.description !== void 0) entry.description = tool.description;
+	if (tool.outputSchema !== void 0) entry.outputSchema = tool.outputSchema;
+	const annotations = mapAnnotations(tool.annotations);
+	if (annotations !== void 0) entry.annotations = annotations;
+	return entry;
+}
+/**
+* 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.
+*/
+const MAX_TOOL_LIST_PAGES = 100;
+const MAX_TOOLS = 2e3;
+async function listAllTools(client, alias) {
+	const tools = [];
+	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
+		});
+	}
+	return tools;
+}
+async function buildServerCatalog(alias, client) {
+	const tools = await listAllTools(client, alias);
+	const info = client.getServerVersion();
+	const catalog = {
+		alias,
+		identity: info !== void 0 ? `${info.name}@${info.version}` : alias,
+		tools: tools.map(toCatalogEntry)
+	};
+	const instructions = client.getInstructions();
+	if (instructions !== void 0) catalog.instructions = instructions;
+	return catalog;
+}
+/** Extract a one-line error message from an `isError` tool result's content. */
+function errorTextFromContent(content) {
+	if (!Array.isArray(content)) return void 0;
+	const text = content.filter(isTextBlock).map((block) => block.text).join("\n").trim();
+	return text.length > 0 ? text : void 0;
+}
+/**
+* Pick the value delivered to the machine as `TOOL_RESULT` payload:
+* `structuredContent` when the tool declares one, otherwise the text of a
+* single text block, otherwise the raw content array (`null` when empty).
+*/
+function pickResultValue(result) {
+	if (result.structuredContent !== void 0) return result.structuredContent;
+	const content = Array.isArray(result.content) ? result.content : [];
+	const first = content[0];
+	if (content.length === 1 && isTextBlock(first)) return first.text;
+	if (content.length === 0) return null;
+	return content;
+}
+/**
+* Holds one MCP client per wrapped-server alias, exposes the aggregated
+* {@link ToolCatalog}, and executes tool calls (implements
+* {@link ToolExecutor}). Construct with {@link createIntrospector}.
+*/
+var Introspector = class Introspector {
+	#connections;
+	#catalog;
+	constructor(connections, catalog) {
+		this.#connections = connections;
+		this.#catalog = catalog;
+	}
+	static async create(sources) {
+		const aliases = Object.keys(sources);
+		if (aliases.length === 0) throw new ProjectionError("protocol", "No wrapped server was provided.", { hint: "Pass at least one server source, e.g. { default: myMcpServer }." });
+		const connections = /* @__PURE__ */ new Map();
+		const servers = /* @__PURE__ */ new Map();
+		const failed = (await Promise.allSettled(aliases.map(async (alias) => {
+			const source = sources[alias];
+			if (source === void 0) return;
+			const connection = await Introspector.#connect(alias, source);
+			connections.set(alias, connection);
+			servers.set(alias, await buildServerCatalog(alias, connection.client));
+		}))).find((result) => result.status === "rejected");
+		if (failed !== void 0) {
+			await Introspector.#closeConnections(connections);
+			throw failed.reason;
+		}
+		return new Introspector(connections, { servers });
+	}
+	static async #connect(alias, source) {
+		if (source instanceof McpServer) {
+			if (source.isConnected()) throw new ProjectionError("protocol", `Wrapped server "${alias}" is already connected to a transport.`, { hint: "Pass a dedicated McpServer instance — Projection owns the wrapped server's transport and exposes it only through the code-mode facade." });
+			const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+			const client = new Client(CLIENT_INFO, { capabilities: {} });
+			await source.connect(serverTransport);
+			await client.connect(clientTransport);
+			return {
+				client,
+				owned: true
+			};
+		}
+		return {
+			client: source,
+			owned: false
+		};
+	}
+	static async #closeConnections(connections) {
+		await Promise.all([...connections.values()].filter((connection) => connection.owned).map((connection) => connection.client.close().catch(() => void 0)));
+	}
+	/** The aggregated tool catalog, keyed by server alias (R30). */
+	get catalog() {
+		return this.#catalog;
+	}
+	/** 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) };
+		return this.#catalog;
+	}
+	/**
+	* Execute a tool call against the wrapped server identified by `alias`,
+	* mapping the MCP result to a {@link ToolCallOutcome}:
+	*
+	* - success → `{ ok: true, result }` where `result` is the tool's
+	*   `structuredContent` when present, else a single text block's text,
+	*   else the raw content array.
+	* - `isError` result or transport/protocol failure → `{ ok: false, error }`.
+	*
+	* An unknown alias is a wiring bug, not a tool failure, and throws.
+	*/
+	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.` });
+		try {
+			const result = await connection.client.callTool({
+				name,
+				arguments: args
+			});
+			if (result.isError === true) return {
+				ok: false,
+				error: {
+					message: errorTextFromContent(result.content) ?? `Tool "${name}" returned an error result.`,
+					detail: result.structuredContent ?? result.content
+				}
+			};
+			return {
+				ok: true,
+				result: pickResultValue(result)
+			};
+		} catch (err) {
+			return {
+				ok: false,
+				error: {
+					message: `Tool call "${name}" failed: ${err instanceof Error ? err.message : String(err)}`,
+					detail: err instanceof Error ? { name: err.name } : err
+				}
+			};
+		}
+	}
+	/**
+	* Close connections the introspector created (in-process sources).
+	* Caller-provided remote clients are left untouched.
+	*/
+	async close() {
+		await Introspector.#closeConnections(this.#connections);
+		this.#connections.clear();
+	}
+};
+/**
+* Connect to the given wrapped servers and build their tool catalog.
+*
+* v1 usage: `createIntrospector({ [DEFAULT_SERVER_ALIAS]: serverOrClient })`.
+*/
+async function createIntrospector(sources) {
+	return Introspector.create(sources);
+}
+//#endregion
+//#region src/types.ts
+const DEFAULT_SERVER_ALIAS = "default";
+/**
+* Name → entry index, built lazily and cached per catalog object. The
+* catalog is immutable once introspected, so a `WeakMap` keyed on identity
+* lets every consumer look a tool up in O(1) without the catalog having to
+* carry (and every construction site having to build) the index itself.
+*/
+const catalogIndex = /* @__PURE__ */ new WeakMap();
+/**
+* Look up a tool by name in a catalog, O(1) after the first call.
+*
+* Duplicate names resolve to the FIRST occurrence, matching `Array#find` and
+* typegen's `dedupeToolNames` (S5): a hostile server declaring the same name
+* twice must not be able to make the policy gate see a different entry (e.g.
+* a later `readOnlyHint: true` copy) than the one typegen exposed.
+*/
+function findTool(catalog, name) {
+	let index = catalogIndex.get(catalog);
+	if (index === void 0) {
+		index = /* @__PURE__ */ new Map();
+		for (const tool of catalog.tools) if (!index.has(tool.name)) index.set(tool.name, tool);
+		catalogIndex.set(catalog, index);
+	}
+	return index.get(name);
+}
+/** Narrow to a non-null, non-array object. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const DEFAULT_CAPS = {
+	segmentWallClockMs: 3e4,
+	wasmMemoryBytes: 134217728,
+	maxCodeBytes: 131072,
+	maxInputBytes: 131072,
+	maxReadCallsPerSegment: 50,
+	maxRoundTrips: 8,
+	maxEventsPerSegment: 1e4,
+	maxResultBytes: 262144,
+	maxStateNodes: 100,
+	maxConsoleBytes: 65536
+};
+const MAX_CAPS = {
+	segmentWallClockMs: 6e4,
+	wasmMemoryBytes: 268435456,
+	maxCodeBytes: 262144,
+	maxInputBytes: 262144,
+	maxReadCallsPerSegment: 200,
+	maxRoundTrips: 16,
+	maxEventsPerSegment: 5e4,
+	maxResultBytes: 1048576,
+	maxStateNodes: 1e3,
+	maxConsoleBytes: 262144
+};
+/**
+* Smallest value each cap may be configured down to.
+*
+* Caps are "configurable downward" (R12), but zero or negative would brick
+* the flow rather than restrict it — a `maxRoundTrips` of 0 makes every
+* gated workflow terminal, and a `segmentWallClockMs` of 0 fails every
+* execution. Misconfiguration should not look like a library bug.
+*/
+const MIN_CAPS = {
+	segmentWallClockMs: 100,
+	wasmMemoryBytes: 1048576,
+	maxCodeBytes: 1024,
+	maxInputBytes: 1024,
+	maxReadCallsPerSegment: 1,
+	maxRoundTrips: 1,
+	maxEventsPerSegment: 1,
+	maxResultBytes: 1024,
+	maxStateNodes: 1,
+	maxConsoleBytes: 1024
+};
+/** Clamp requested caps into [MIN_CAPS, MAX_CAPS] (R12). */
+function clampCaps(requested) {
+	const caps = { ...DEFAULT_CAPS };
+	for (const key of Object.keys(caps)) {
+		const value = requested[key];
+		if (value !== void 0 && Number.isFinite(value)) caps[key] = Math.max(MIN_CAPS[key], Math.min(value, MAX_CAPS[key]));
+	}
+	return caps;
+}
+const BLOB_SCHEMA_VERSION = 1;
+//#endregion
+//#region src/blob/versions.ts
+/**
+* Version constants recorded into every blob (R20) and strict-matched on
+* open (R21, Q3: no migration — mismatches are rejected).
+*
+* Hardcoded rather than imported from package.json at runtime: JSON import
+* attributes complicate the tsdown/dist story for zero benefit, and both
+* versions are pinned exactly (DECISIONS.md D2). A test in
+* `test/blob/versions.test.ts` asserts these constants match the installed
+* package.json versions, so a version bump that forgets to update them fails
+* 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.2.0";
+/** Pinned XState version (must match the exact pin in package.json — D2). */
+const XSTATE_VERSION = "5.32.5";
+//#endregion
+//#region src/blob/sealer.ts
+/**
+* Suspension blob sealer (PRD §7 "Blob sealer"; R19–R23, S2–S4).
+*
+* Packages a {@link BlobPayload} into an opaque, authenticated, encrypted,
+* compressed envelope string that rides in the MRTR `requestState` field,
+* and verifies/opens it on resume. Clients are honest-but-curious couriers
+* (S3): they must neither read machine context (encryption) nor modify
+* anything (authentication). Every failure mode fails closed with a
+* ProjectionError; a payload is never returned partially verified.
+*
+* ## Envelope format (version `proj1`)
+*
+* ```
+* proj1.<salt>.<iv>.<ciphertext>.<tag>
+* ```
+*
+* Five dot-separated fields; all but the literal `proj1` prefix are
+* unpadded base64url:
+*
+* - `salt` — 16 random bytes, HKDF salt for per-blob key derivation
+* - `iv` — 12 random bytes, AES-GCM nonce
+* - `ciphertext` — AES-256-GCM over deflateRaw(JSON(payload))
+* - `tag` — 16-byte GCM authentication tag
+*
+* AAD is the UTF-8 bytes of the envelope header `proj1.<salt>.<iv>` (the
+* exact base64url text as transmitted), so the version prefix and header
+* fields are covered by the authentication tag. Tampering with any field
+* fails closed: the prefix and header break AAD verification, the salt
+* additionally derives a different key, and the iv/ciphertext/tag break GCM
+* authentication directly.
+*
+* ## Crypto choices
+*
+* - **AES-256-GCM** (R19): AEAD, native in node:crypto.
+* - **HKDF-SHA256** per-blob key derivation: the developer-supplied 32-byte
+*   key is treated as input keying material, never used directly as a
+*   cipher key. A fresh random 16-byte salt per blob means every blob is
+*   encrypted under a distinct derived key, so the 96-bit random GCM nonce
+*   can never repeat *under the same key* even across horizontally scaled
+*   instances sealing concurrently (nonce-reuse would be catastrophic for
+*   GCM). Fixed info string `@astral-mcp/projection/blob/v1` domain-separates the
+*   derivation.
+* - **deflateRaw** compression (R23), not brotli: brotli's default quality
+*   is far too slow for the seal+verify+rehydrate p95 < 100 ms budget
+*   (PRD §10), and at speed-comparable quality settings its ratio edge on
+*   small (< 32 KB typical) JSON payloads is marginal. Raw deflate also
+*   omits the zlib header/adler32 checksum — GCM already guarantees
+*   integrity — saving a few bytes.
+* - **Sync APIs throughout**: payloads are small (128 KB ceiling), so the
+*   sync node:crypto/node:zlib forms are faster than promise overhead and
+*   keep the API non-async.
+*/
+/** Envelope format version prefix. Bump (proj2, …) on any wire-format change. */
+const ENVELOPE_PREFIX = "proj1";
+/** Default blob TTL: 15 minutes (R20). */
+const DEFAULT_TTL_MS = 9e5;
+/** Default sealed-blob size ceiling: 128 KB (R23). */
+const DEFAULT_MAX_BLOB_BYTES = 131072;
+const KEY_BYTES = 32;
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const HKDF_INFO = "@astral-mcp/projection/blob/v1";
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+function verificationError(message, hint) {
+	return new ProjectionError("blob_verification", message, { hint });
+}
+const HINT_CORRUPT = "The requestState blob is corrupt; retry with the exact requestState echoed from the input_required result, or re-run execute_machine to start a new workflow.";
+const HINT_AUTH = "The blob failed authentication — it was modified in transit or sealed under a key this deployment does not accept. Re-run execute_machine to start a new workflow.";
+const HINT_VERSION = "The server was upgraded since this workflow suspended; suspended workflows do not survive version changes. Re-run execute_machine to start a new workflow.";
+const HINT_EXPIRED = "The approval window elapsed before the retry arrived. Re-run execute_machine and respond to approval prompts within the TTL.";
+const HINT_CODE = "Retry the call with the byte-exact original code argument; a blob only resumes the code that produced it.";
+const HINT_SERVER = "This blob was minted against a different wrapped server and cannot be resumed here. Re-run execute_machine against this server.";
+function assertKey(key, label) {
+	if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) throw new ProjectionError("terminal", `blob sealer ${label} must be exactly ${KEY_BYTES} bytes`, { hint: "Provide a 32-byte key (e.g. crypto.randomBytes(32)) shared across all instances." });
+}
+function assertConfigKeys(config) {
+	assertKey(config.key, "key");
+	for (const prev of config.previousKeys ?? []) assertKey(prev, "previousKeys entry");
+}
+/** Derive the actual AES key from developer IKM via HKDF-SHA256 (R19). */
+function deriveKey(ikm, salt) {
+	return Buffer.from(hkdfSync("sha256", ikm, salt, HKDF_INFO, KEY_BYTES));
+}
+function buildAad(saltPart, ivPart) {
+	return Buffer.from(`${ENVELOPE_PREFIX}.${saltPart}.${ivPart}`, "utf8");
+}
+function decodePart(part, field, expectedBytes) {
+	if (part.length === 0 || !BASE64URL.test(part)) throw verificationError(`envelope parse failed: ${field} is not valid base64url`, HINT_CORRUPT);
+	const bytes = Buffer.from(part, "base64url");
+	if (expectedBytes !== void 0 && bytes.length !== expectedBytes) throw verificationError(`envelope parse failed: ${field} has unexpected length`, HINT_CORRUPT);
+	return bytes;
+}
+function parseEnvelope(blob) {
+	const parts = blob.split(".");
+	const [prefix, saltPart, ivPart, ciphertextPart, tagPart] = parts;
+	if (parts.length !== 5 || prefix === void 0 || saltPart === void 0 || ivPart === void 0 || ciphertextPart === void 0 || tagPart === void 0) throw verificationError("envelope parse failed: expected 5 dot-separated fields", HINT_CORRUPT);
+	if (prefix !== "proj1") throw verificationError(`envelope parse failed: unsupported envelope version (expected "${ENVELOPE_PREFIX}")`, HINT_VERSION);
+	return {
+		salt: decodePart(saltPart, "salt", SALT_BYTES),
+		iv: decodePart(ivPart, "iv", IV_BYTES),
+		ciphertext: decodePart(ciphertextPart, "ciphertext"),
+		tag: decodePart(tagPart, "tag", TAG_BYTES),
+		aad: buildAad(saltPart, ivPart)
+	};
+}
+function decryptWith(envelope, ikm) {
+	const key = deriveKey(ikm, envelope.salt);
+	const decipher = createDecipheriv("aes-256-gcm", key, envelope.iv);
+	decipher.setAAD(envelope.aad);
+	decipher.setAuthTag(envelope.tag);
+	return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+}
+/** Try the current key, then each previous key (R22 rotation grace). */
+function decryptWithAnyKey(envelope, config) {
+	const candidates = [config.key, ...config.previousKeys ?? []];
+	for (const ikm of candidates) try {
+		return decryptWith(envelope, ikm);
+	} catch {}
+	throw verificationError("authentication failed: blob could not be decrypted and verified with any configured key", HINT_AUTH);
+}
+function malformed(field) {
+	return verificationError(`blob payload malformed: field "${field}" is missing or mistyped`, HINT_CORRUPT);
+}
+/**
+* Structural check of everything except v/libv/xstatev (already exact-matched
+* by the caller before this runs). The payload is authenticated, so failures
+* here indicate a sealer bug or cross-version confusion — still fail closed.
+*/
+function assertPayloadShape(payload) {
+	if (typeof payload["codeHash"] !== "string" || payload["codeHash"].length === 0) throw malformed("codeHash");
+	if (typeof payload["serverIdentity"] !== "string" || payload["serverIdentity"].length === 0) throw malformed("serverIdentity");
+	if (typeof payload["nonce"] !== "string" || payload["nonce"].length === 0) throw malformed("nonce");
+	if (typeof payload["iat"] !== "number" || !Number.isFinite(payload["iat"])) throw malformed("iat");
+	if (typeof payload["exp"] !== "number" || !Number.isFinite(payload["exp"])) throw malformed("exp");
+	if (typeof payload["trip"] !== "number" || !Number.isInteger(payload["trip"])) throw malformed("trip");
+	if (!("snapshot" in payload)) throw malformed("snapshot");
+	const pending = payload["pending"];
+	if (!isRecord(pending)) throw malformed("pending");
+	for (const [key, call] of Object.entries(pending)) if (!isRecord(call) || typeof call["id"] !== "string" || typeof call["name"] !== "string" || typeof call["stateName"] !== "string" || !isRecord(call["args"])) throw malformed(`pending["${key}"]`);
+	if (!Array.isArray(payload["audit"])) throw malformed("audit");
+}
+/** SHA-256 hex digest of a code argument (S4 binding — R20 `codeHash`). */
+function hashCode(code) {
+	return createHash("sha256").update(code, "utf8").digest("hex");
+}
+/**
+* Construct a fully populated {@link BlobPayload}: stamps the schema and
+* library/XState versions, hashes the code, and fills nonce/iat/exp.
+*/
+function buildBlobPayload(input) {
+	const iat = input.now ?? Date.now();
+	const ttlMs = input.ttlMs ?? 9e5;
+	return {
+		v: 1,
+		libv: LIB_VERSION,
+		xstatev: XSTATE_VERSION,
+		codeHash: hashCode(input.code),
+		serverIdentity: input.serverIdentity,
+		snapshot: input.snapshot,
+		pending: input.pending,
+		audit: input.audit ?? [],
+		trip: input.trip,
+		nonce: randomBytes(16).toString("base64url"),
+		iat,
+		exp: iat + ttlMs
+	};
+}
+/**
+* Seal a payload into an opaque `proj1.` envelope string (R19, R23).
+*
+* JSON → deflateRaw → AES-256-GCM under an HKDF-SHA256 per-blob derived key,
+* with the envelope header as AAD. Throws ProjectionError phase `terminal` if
+* the sealed envelope exceeds `maxBlobBytes` (default 128 KB) or the config
+* keys are malformed.
+*/
+function sealBlob(payload, config) {
+	assertKey(config.key, "key");
+	const compressed = deflateRawSync(Buffer.from(JSON.stringify(payload), "utf8"), { level: 9 });
+	const salt = randomBytes(SALT_BYTES);
+	const iv = randomBytes(IV_BYTES);
+	const saltPart = salt.toString("base64url");
+	const ivPart = iv.toString("base64url");
+	const cipher = createCipheriv("aes-256-gcm", deriveKey(config.key, salt), iv);
+	cipher.setAAD(buildAad(saltPart, ivPart));
+	const ciphertext = Buffer.concat([cipher.update(compressed), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	const blob = `${ENVELOPE_PREFIX}.${saltPart}.${ivPart}.${ciphertext.toString("base64url")}.${tag.toString("base64url")}`;
+	const maxBlobBytes = config.maxBlobBytes ?? 131072;
+	const size = Buffer.byteLength(blob, "utf8");
+	if (size > maxBlobBytes) throw new ProjectionError("terminal", `sealed suspension blob is ${size} bytes, exceeding the ${maxBlobBytes}-byte ceiling`, { hint: "Machine context is too large to suspend. Keep large tool results out of context — store only the fields later states need — then re-run execute_machine." });
+	return blob;
+}
+/**
+* Verify and open a sealed blob (R21 — check order is normative):
+*
+* 1. parse envelope + decrypt/authenticate (current key, then each
+*    `previousKeys` — R22 rotation grace)
+* 2. schema version, then exact `libv`/`xstatev` match (Q3: strict, no
+*    migration)
+* 3. expiry (`exp` strictly in the future relative to `now`)
+* 4. `codeHash` equality against the re-sent code, and `serverIdentity`
+*    match
+*
+* Any failure throws ProjectionError phase `blob_verification` naming the
+* failed check (never key material or plaintext). A payload is only
+* returned once every check has passed.
+*/
+function openBlob(blob, options) {
+	assertConfigKeys(options.config);
+	const maxBlobBytes = options.config.maxBlobBytes ?? 131072;
+	if (blob.length > maxBlobBytes * 2) throw verificationError(`blob rejected: ${blob.length} characters exceeds the acceptance limit for a ${maxBlobBytes}-byte ceiling`, HINT_CORRUPT);
+	const compressed = decryptWithAnyKey(parseEnvelope(blob), options.config);
+	let payload;
+	try {
+		payload = JSON.parse(inflateRawSync(compressed, { maxOutputLength: maxBlobBytes * 64 }).toString("utf8"));
+	} catch {
+		throw verificationError("blob payload is corrupt: decompression or JSON parse failed after authentication", HINT_CORRUPT);
+	}
+	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.2.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;
+	const now = options.now ?? Date.now();
+	if (now >= verified.exp) throw verificationError(`blob expired: exp was ${verified.exp} and it is now ${now}`, HINT_EXPIRED);
+	if (hashCode(options.code) !== verified.codeHash) throw verificationError("code hash mismatch: the retried call's code differs from the code that produced this blob", HINT_CODE);
+	if (options.serverIdentity !== verified.serverIdentity) throw verificationError("server identity mismatch: blob was minted against a different wrapped server", HINT_SERVER);
+	return verified;
+}
+//#endregion
+//#region src/sandbox/logs.ts
+const encoder = new TextEncoder();
+/** UTF-8 byte length of a string (shared cached encoder). */
+function utf8Length(value) {
+	return encoder.encode(value).length;
+}
+/** Truncate a string to at most `maxBytes` UTF-8 bytes, appending a marker. */
+function truncateUtf8(value, maxBytes) {
+	if (utf8Length(value) <= maxBytes) return value;
+	const suffix = "…[truncated]";
+	let end = Math.min(value.length, maxBytes);
+	while (end > 0 && utf8Length(value.slice(0, end)) + utf8Length(suffix) > maxBytes) end = Math.floor(end / 2);
+	return value.slice(0, end) + suffix;
+}
+/** Best-effort single-string rendering of one console argument. */
+function formatParam(param) {
+	if (typeof param === "string") return param;
+	if (param instanceof Error) return `${param.name}: ${param.message}`;
+	if (typeof param === "function") return "[function]";
+	try {
+		const json = JSON.stringify(param);
+		return json === void 0 ? String(param) : json;
+	} catch {
+		return String(param);
+	}
+}
+/** Marker prefix used in the synthetic truncation entry. */
+const TRUNCATION_MARKER_PREFIX = "[@astral-mcp/projection] console output truncated:";
+/**
+* Collects console output for one execution segment, enforcing the
+* `maxConsoleBytes` cap with drop-middle truncation.
+*/
+var LogCollector = class {
+	maxBytes;
+	segment;
+	head = [];
+	tail = [];
+	headBytes = 0;
+	tailBytes = 0;
+	dropped = 0;
+	halfBudget;
+	startedAt = Date.now();
+	constructor(maxBytes, segment) {
+		this.maxBytes = maxBytes;
+		this.segment = segment;
+		this.halfBudget = Math.max(64, Math.floor(maxBytes / 2));
+	}
+	/** Record one console call. `params` are the marshaled console arguments. */
+	push(level, params) {
+		const message = truncateUtf8(params.map(formatParam).join(" "), this.halfBudget);
+		const cost = utf8Length(message);
+		const entry = {
+			level,
+			message,
+			ts: Date.now() - this.startedAt,
+			segment: this.segment
+		};
+		if (this.tail.length === 0 && this.headBytes + cost <= this.halfBudget) {
+			this.head.push(entry);
+			this.headBytes += cost;
+			return;
+		}
+		this.tail.push(entry);
+		this.tailBytes += cost;
+		while (this.tailBytes > this.halfBudget && this.tail.length > 1) {
+			const evicted = this.tail.shift();
+			if (evicted !== void 0) {
+				this.tailBytes -= utf8Length(evicted.message);
+				this.dropped += 1;
+			}
+		}
+	}
+	/**
+	* The captured entries in order. When entries were dropped, a synthetic
+	* `warn` marker entry sits between the kept head and tail.
+	*/
+	snapshot() {
+		if (this.dropped === 0) return [...this.head, ...this.tail];
+		const marker = {
+			level: "warn",
+			message: `${TRUNCATION_MARKER_PREFIX} ${this.dropped} entries dropped (maxConsoleBytes=${this.maxBytes})`,
+			ts: this.tail[0]?.ts ?? Date.now() - this.startedAt,
+			segment: this.segment
+		};
+		return [
+			...this.head,
+			marker,
+			...this.tail
+		];
+	}
+};
+//#endregion
+//#region src/sandbox/mounts.ts
+/**
+* Module mounting and import resolution for the QuickJS sandbox (R8, R9, S1).
+*
+* The sandbox's virtual filesystem contains exactly what module resolution
+* needs and nothing else:
+*
+* - `/src/machine.js`               — the (transpiled) authored module
+* - `/node_modules/xstate/*`        — the pinned XState v5 ESM build
+* - `/node_modules/@astral-mcp/tools/index.js` — the caller-supplied bridge
+*
+* Import resolution is allowlist-based: only `xstate` and `@astral-mcp/tools`
+* resolve for authored code (plus the handful of pure-utility modules the
+* QuickJS runtime itself boots with: `buffer`, `util`, `url` and the
+* `@node_compatibility/*` shims — none of which perform I/O). Every other
+* specifier — including `node:fs`, `node:child_process`, `http`, arbitrary
+* package names — resolves to a sentinel path whose load fails with a
+* structured, model-actionable error message.
+*/
+/** Specifier the authored code uses to import XState (R8). */
+const XSTATE_SPECIFIER = "xstate";
+/** Specifier the authored code uses to import the generated tools bridge (R8). */
+const TOOLS_SPECIFIER = "@astral-mcp/tools";
+/** Sentinel path prefix produced by the normalizer for disallowed imports. */
+const DENIED_PREFIX = "/__projection_denied__/";
+/** Marker embedded in denied-import error messages; used for error classification. */
+const DENIED_IMPORT_MARKER = "cannot be imported inside the sandbox";
+/**
+* Bare specifiers that resolve inside the sandbox. `xstate` and
+* `@astral-mcp/tools` are the authoring contract (R8); the rest are pure
+* utilities required by the QuickJS runtime's own node-compatibility
+* bootstrap (`node:buffer`, `node:util`, `node:url` and the
+* `@node_compatibility/*` shims). None of them expose I/O.
+*/
+const ALLOWED_SPECIFIERS = /* @__PURE__ */ new Set([
+	XSTATE_SPECIFIER,
+	TOOLS_SPECIFIER,
+	"buffer",
+	"util",
+	"url",
+	"@node_compatibility/event-target",
+	"@node_compatibility/headers",
+	"@node_compatibility/request",
+	"@node_compatibility/response"
+]);
+let cachedXStateMount;
+/**
+* Build the virtual `node_modules/xstate` directory from the pinned XState v5
+* package installed on the host: the production ESM entry (`xstate.esm.js`,
+* mounted additionally as `index.js`) plus its sibling ESM chunk files, which
+* it references via relative imports. The chunks are self-contained (no bare
+* imports), so nothing else needs to resolve.
+*/
+function getXStateMount() {
+	if (cachedXStateMount === void 0) {
+		const require = createRequire(import.meta.url);
+		const distDir = join(dirname(require.resolve("xstate/package.json")), "dist");
+		const mount = {};
+		for (const file of readdirSync(distDir)) if (file.endsWith(".esm.js") && !file.includes("development")) mount[file] = readFileSync(join(distDir, file), "utf8");
+		const entry = mount["xstate.esm.js"];
+		if (entry === void 0) throw new Error("xstate package layout not recognized: dist/xstate.esm.js missing");
+		mount["index.js"] = entry;
+		cachedXStateMount = mount;
+	}
+	return cachedXStateMount;
+}
+/** Assemble the sandbox `node_modules` mount: xstate + the tools bridge. */
+function buildNodeModulesMount(bridgeJs) {
+	return {
+		xstate: { ...getXStateMount() },
+		"@astral-mcp": { tools: { "index.js": bridgeJs } }
+	};
+}
+/**
+* Allowlisting module path normalizer (R8/R9). Relative imports resolve
+* against the importing module; allowlisted bare specifiers resolve into
+* `/node_modules`; everything else maps to a denied sentinel path.
+*
+* `xstate` and `@astral-mcp/tools` map directly to their `index.js` files
+* (rather than the package directory) so that the relative chunk imports
+* inside them resolve against the package directory.
+*/
+const modulePathNormalizer = (baseName, requestedName) => {
+	if (requestedName.startsWith(".")) {
+		const parts = baseName.split("/");
+		parts.pop();
+		return resolve(`/${parts.join("/")}`, requestedName);
+	}
+	const name = requestedName.replace(/^node:/, "");
+	if (name === "xstate") return "/node_modules/xstate/index.js";
+	if (name === "@astral-mcp/tools") return "/node_modules/@astral-mcp/tools/index.js";
+	if (ALLOWED_SPECIFIERS.has(name)) return join("/node_modules", name);
+	return `${DENIED_PREFIX}${requestedName}`;
+};
+/**
+* Module loader wrapping the package default: turns denied sentinel paths
+* into a structured, actionable error (R25); defers everything else to the
+* default memfs-backed loader.
+*/
+const getSandboxModuleLoader = (fs, runtimeOptions) => {
+	const defaultLoader = getModuleLoader(fs, runtimeOptions);
+	return (name, context) => {
+		if (name.startsWith(DENIED_PREFIX)) {
+			const specifier = name.slice(23);
+			return { error: /* @__PURE__ */ new Error(`'${specifier}' ${DENIED_IMPORT_MARKER}; only '${XSTATE_SPECIFIER}' and '${TOOLS_SPECIFIER}' are importable`) };
+		}
+		return defaultLoader(name, context);
+	};
+};
+//#endregion
+//#region src/sandbox/session.ts
+/**
+* Sandbox session implementation. See ./index.ts for the boundary contract
+* the machine host builds against.
+*/
+/** Global object the boot script installs inside the VM. */
+const SANDBOX_GLOBAL = "__projection";
+/**
+* Name of the host bridge function on the in-VM `env` object. The bridge
+* module calls `env.__projection_toolCall(name, args)` and receives a promise.
+*/
+const TOOL_CALL_BINDING = "__projection_toolCall";
+let quickJsPromise;
+let tsSupportPromise;
+const QUICKJS_VARIANT = "@jitl/quickjs-ng-wasmfile-release-sync";
+function getQuickJs() {
+	quickJsPromise ??= (async () => {
+		let variant;
+		try {
+			variant = await import(QUICKJS_VARIANT);
+		} catch (cause) {
+			quickJsPromise = 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 quickJsPromise;
+}
+/**
+* Environment-class transpile failure: the TypeScript transpiler itself is
+* missing or incompatible, as opposed to a syntax error in the source being
+* transpiled. `createSandboxSession` lets these pass through unrewrapped so
+* the environment diagnostics (and their hints) reach the consumer instead
+* of being misreported as an invalid-bridgeSource integration bug.
+*/
+var TranspilerUnavailableError = class extends ProjectionError {};
+function getTsSupport() {
+	tsSupportPromise ??= (async () => {
+		const ts = await import("typescript");
+		if (typeof ts.transpile !== "function") throw new TranspilerUnavailableError("transpile", `the installed typescript@${ts.version ?? "unknown"} does not provide ts.transpile`, { hint: "@astral-mcp/projection requires typescript ^5 (TS 6+/7+ removed the transpile API). Pin typescript to ^5.7.0." });
+		const typescriptImportFile = typeof import.meta.resolve === "function" ? import.meta.resolve("typescript") : void 0;
+		return getTypescriptSupport(true, typescriptImportFile);
+	})().catch((cause) => {
+		tsSupportPromise = void 0;
+		if (cause instanceof ProjectionError) throw cause;
+		throw new TranspilerUnavailableError("transpile", "TypeScript transpiler is not available", {
+			hint: "Reinstall dependencies: @astral-mcp/projection depends on typescript ^5 for machine and bridge transpilation.",
+			cause
+		});
+	});
+	return tsSupportPromise;
+}
+function flattenDiagnosticMessage(messageText) {
+	if (typeof messageText === "string") return messageText;
+	const parts = [messageText.messageText];
+	for (const next of messageText.next ?? []) parts.push(flattenDiagnosticMessage(next.messageText));
+	return parts.join(" ");
+}
+/**
+* Transpile the (invariant) tools bridge, memoized by source. Bounded so a
+* process that wraps many distinct servers can't grow the cache unbounded.
+*/
+const bridgeCache = /* @__PURE__ */ new Map();
+const BRIDGE_CACHE_MAX = 32;
+async function transpileBridge(source) {
+	const cached = bridgeCache.get(source);
+	if (cached !== void 0) return cached;
+	const js = await transpileTs(source, "/bridge/index.ts");
+	if (bridgeCache.size >= BRIDGE_CACHE_MAX) {
+		const oldest = bridgeCache.keys().next().value;
+		if (oldest !== void 0) bridgeCache.delete(oldest);
+	}
+	bridgeCache.set(source, js);
+	return js;
+}
+async function transpileTs(source, fileName) {
+	const support = await getTsSupport();
+	const diagnostics = [];
+	const js = support.transpileFile(source, void 0, fileName, diagnostics);
+	const errors = diagnostics.filter((d) => d.category === 1);
+	if (errors.length > 0) throw new ProjectionError("transpile", "TypeScript transpilation failed", {
+		diagnostics: errors.map((d) => {
+			const message = flattenDiagnosticMessage(d.messageText);
+			if (d.file !== void 0 && d.start !== void 0) {
+				const pos = d.file.getLineAndCharacterOfPosition(d.start);
+				return {
+					message,
+					line: pos.line + 1,
+					column: pos.character + 1
+				};
+			}
+			return { message };
+		}),
+		hint: "Fix the syntax error; TypeScript is transpiled without type checking, so only syntax matters"
+	});
+	return js;
+}
+function classifyEvalError(response, caps, logs) {
+	const { name, message, stack } = response.error;
+	const diagnostics = stack !== void 0 && stack.length > 0 ? [{ message: stack }] : [];
+	if (name === "ExecutionTimeout" || message === "interrupted" || message.includes("maximum allowed time limit")) return new ProjectionError("cap_exceeded", `Execution exceeded the wall-clock budget of ${caps.segmentWallClockMs} ms for this segment`, {
+		diagnostics,
+		hint: "Remove long or unbounded loops; heavy work must happen through tool calls, not in-machine computation",
+		logs
+	});
+	if (/out of memory/i.test(message)) return new ProjectionError("cap_exceeded", `Execution exceeded the memory limit of ${caps.wasmMemoryBytes} bytes`, {
+		diagnostics,
+		hint: "Keep machine context small; avoid accumulating large arrays or strings in the sandbox",
+		logs
+	});
+	if (message.includes("cannot be imported inside the sandbox") || message.includes("not installed or available")) return new ProjectionError("validate", message, {
+		diagnostics,
+		hint: `Only '${XSTATE_SPECIFIER}' and '${TOOLS_SPECIFIER}' can be imported; there is no filesystem or network access`,
+		logs
+	});
+	if (response.isSyntaxError === true || name === "SyntaxError") return new ProjectionError("validate", `${name}: ${message}`, {
+		diagnostics,
+		hint: "Fix the JavaScript syntax error shown in diagnostics",
+		logs
+	});
+	return new ProjectionError("runtime", `${name}: ${message}`, {
+		diagnostics,
+		hint: "Uncaught error inside the sandbox; see diagnostics and logs, correct the code, and retry",
+		logs
+	});
+}
+function deferred() {
+	let resolve;
+	let reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+/** No-op sink for console methods that are captured nowhere (R31 covers five levels). */
+const silent = () => {};
+/**
+* Create a sandbox session: boot a fresh QuickJS VM, mount xstate and the
+* bridge, evaluate the authored module, and return a handle for driving it.
+* See ./index.ts for the full boundary contract.
+*/
+async function createSandboxSession(options) {
+	const caps = clampCaps(options.caps ?? {});
+	const segment = options.segment ?? 0;
+	const lang = options.lang ?? "js";
+	const codeBytes = utf8Length(options.code);
+	if (codeBytes > caps.maxCodeBytes) throw new ProjectionError("cap_exceeded", `Submitted code is ${codeBytes} bytes; the maximum is ${caps.maxCodeBytes} bytes`, { hint: "Shrink the machine: remove comments and dead states, and keep large data out of the source" });
+	const machineJs = lang === "ts" ? await transpileTs(options.code, "/src/machine.ts") : options.code;
+	let bridgeJs;
+	try {
+		bridgeJs = await transpileBridge(options.bridgeSource);
+	} catch (error) {
+		if (error instanceof TranspilerUnavailableError) throw error;
+		if (error instanceof ProjectionError && error.phase === "transpile") throw new ProjectionError("runtime", "The @astral-mcp/tools bridge module failed to transpile", {
+			diagnostics: error.diagnostics,
+			hint: "The bridgeSource passed to createSandboxSession is invalid; this is an integration bug, not a model error",
+			cause: error
+		});
+		throw error;
+	}
+	const logs = new LogCollector(caps.maxConsoleBytes, segment);
+	const capture = (level) => (...params) => {
+		logs.push(level, params);
+	};
+	const onToolCall = options.onToolCall;
+	const sandboxOptions = {
+		executionTimeout: caps.segmentWallClockMs,
+		memoryLimit: caps.wasmMemoryBytes,
+		mountFs: { src: { "machine.js": machineJs } },
+		nodeModules: buildNodeModulesMount(bridgeJs),
+		modulePathNormalizer,
+		getModuleLoader: getSandboxModuleLoader,
+		env: { [TOOL_CALL_BINDING]: (name, args) => {
+			const call = {
+				name: typeof name === "string" ? name : String(name),
+				args: typeof args === "object" && args !== null && !Array.isArray(args) ? args : {}
+			};
+			return Promise.resolve(onToolCall(call));
+		} },
+		console: {
+			log: capture("log"),
+			info: capture("info"),
+			warn: capture("warn"),
+			error: capture("error"),
+			debug: capture("debug"),
+			trace: capture("debug"),
+			assert: (condition, ...data) => {
+				if (condition !== true) logs.push("error", ["Assertion failed:", ...data]);
+			},
+			dir: capture("log"),
+			table: capture("log"),
+			count: silent,
+			countReset: silent,
+			dirxml: silent,
+			group: silent,
+			groupCollapsed: silent,
+			groupEnd: silent,
+			time: silent,
+			timeEnd: silent,
+			timeLog: silent,
+			clear: silent
+		}
+	};
+	const runtime = await getQuickJs();
+	const deadlineAt = Date.now() + caps.segmentWallClockMs;
+	const ready = deferred();
+	const hold = deferred();
+	let disposed = false;
+	const runPromise = runtime.runSandboxed(async ({ evalCode }) => {
+		ready.resolve({ evalCode });
+		await hold.promise;
+	}, sandboxOptions);
+	runPromise.catch(() => {});
+	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",
+			logs: logs.snapshot()
+		});
+	})]);
+	const dispose = async () => {
+		if (!disposed) {
+			disposed = true;
+			hold.resolve();
+			await runPromise.catch(() => {});
+		}
+	};
+	let queue = Promise.resolve();
+	let evalCounter = 0;
+	const runInVm = (source) => {
+		const task = async () => {
+			if (disposed) throw new ProjectionError("runtime", "Sandbox session already disposed", { hint: "Create a new session for each execution segment" });
+			if (Date.now() >= deadlineAt) throw new ProjectionError("cap_exceeded", `Execution exceeded the wall-clock budget of ${caps.segmentWallClockMs} ms for this segment`, {
+				hint: "The segment budget is spent; a fresh session (MRTR resume) gets a fresh budget",
+				logs: logs.snapshot()
+			});
+			const filename = `/src/__projection_eval_${evalCounter++}__.js`;
+			const result = await evalCode(source, filename);
+			if (!result.ok) throw classifyEvalError(result, caps, logs.snapshot());
+			return result.data;
+		};
+		const run = queue.then(task, task);
+		queue = run.then(() => void 0, () => void 0);
+		return run;
+	};
+	try {
+		await runInVm(`delete globalThis.fetch; export default null;`);
+		await runInVm(`import * as mod from './machine.js';
+       globalThis.${SANDBOX_GLOBAL} = { module: mod, state: {} };
+       export default null;`);
+	} catch (error) {
+		await dispose();
+		throw error;
+	}
+	return {
+		caps,
+		segment,
+		evaluate: runInVm,
+		getLogs: () => logs.snapshot(),
+		dispose
+	};
+}
+//#endregion
+//#region src/policy/decision.ts
+/**
+* Policy decisions for tool calls (PRD R14, S5).
+*
+* Pure functions: annotation-derived defaults plus developer overrides.
+* Annotations come from a possibly third-party wrapped server and are
+* untrusted hints — they can only ever make the default *stricter* than an
+* explicit developer override, never looser. A developer override always
+* wins, in every combination.
+*/
+const VALID_DECISIONS = /* @__PURE__ */ new Set([
+	"auto",
+	"ask",
+	"deny"
+]);
+/**
+* Decide the policy for a catalog tool (R14).
+*
+* - A developer override (`auto` | `ask` | `deny`) always wins.
+* - With no override, `annotations.readOnlyHint === true` yields `auto`;
+*   an absent or `false` hint yields `ask` (S5: unannotated defaults to ask).
+* - An override entry with an unrecognized value (possible when the config
+*   arrives untyped) fails safe to `ask` — it never grants `auto`.
+*
+* Only own properties of `overrides` are consulted, so tools named like
+* `Object.prototype` members (`toString`, `constructor`, ...) cannot pick up
+* inherited junk as a decision.
+*/
+function decidePolicy(entry, overrides) {
+	if (overrides !== void 0 && Object.hasOwn(overrides, entry.name)) {
+		const override = overrides[entry.name];
+		if (typeof override === "string" && VALID_DECISIONS.has(override)) return override;
+		return "ask";
+	}
+	return entry.annotations?.readOnlyHint === true ? "auto" : "ask";
+}
+/**
+* Resolve a machine-requested tool call against the server catalog and
+* decide its policy.
+*
+* Returns the decision together with the matching catalog entry (the entry
+* is what elicitation copy must be built from — S6), or a structured
+* `validate`-phase {@link ProjectionError} when the machine names a tool the
+* wrapped server does not declare.
+*/
+function resolveCallPolicy(call, catalog, overrides) {
+	const entry = findTool(catalog, call.name);
+	if (entry === void 0) return {
+		ok: false,
+		error: new ProjectionError("validate", `Unknown tool "${call.name}": the wrapped server does not declare it`, {
+			diagnostics: [{ message: `Requested from machine state "${call.stateName}" (call id ${call.id})` }],
+			hint: "Call discover_apis and use only the tool names listed in @astral-mcp/tools."
+		})
+	};
+	return {
+		ok: true,
+		decision: decidePolicy(entry, overrides),
+		entry
+	};
+}
+/**
+* Canonical TOOL_DENIED reason for calls blocked by a `deny` policy
+* decision. A `deny` decision never produces an elicitation — the machine
+* host injects `TOOL_DENIED` with this reason instead.
+*/
+const POLICY_DENIED_REASON = "denied by server policy";
+/**
+* Build the TOOL_DENIED reason string for a policy-denied call. With a tool
+* name it names the denied tool so the machine (and audit trail) can tell
+* which call was blocked.
+*/
+function policyDeniedReason(toolName) {
+	return toolName === void 0 ? POLICY_DENIED_REASON : `${POLICY_DENIED_REASON}: tool "${toolName}" is configured as deny`;
+}
+//#endregion
+//#region src/text-safety.ts
+/**
+* Rendering untrusted strings inertly (S5, S6).
+*
+* Tool names, descriptions, the wrapped server's identity, and machine state
+* names all flow from a possibly third-party server or a model-authored
+* machine. Wherever they are rendered into human-facing prompt copy or into
+* generated source, they must not be able to forge structure with control
+* characters (newlines, ESC for ANSI sequences) or reorder text with Unicode
+* bidi overrides. Centralizing the character class here keeps every call site
+* on the same, complete definition — an earlier divergence let generated
+* `.d.ts`/bridge comments miss the directional-isolate range that the
+* elicitation copy already stripped.
+*/
+/**
+* C0 control characters (incl. ESC and, unless `allowNewline`, `\n`), DEL, C1
+* controls (which `JSON.stringify` does NOT escape), the bidi override marks
+* (LRM/RLM/LRE/RLE/PDF/LRO/RLO), and the directional isolates (LRI/RLI/FSI/
+* PDI).
+*/
+const HOSTILE_INLINE = /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+const HOSTILE_BLOCK = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/**
+* Replace control and bidi characters with the replacement character.
+* `allowNewline` keeps `\n` (for multi-line blocks whose formatting newlines
+* are part of the rendering, e.g. a pretty-printed JSON block).
+*/
+function neutralizeControlChars(text, options = {}) {
+	return text.replace(options.allowNewline === true ? HOSTILE_BLOCK : HOSTILE_INLINE, "�");
+}
+/** Truncate to `maxChars`, appending an ellipsis when shortened. */
+function capLength(text, maxChars) {
+	return text.length <= maxChars ? text : `${text.slice(0, maxChars)}…`;
+}
+//#endregion
+//#region src/policy/elicitation.ts
+/**
+* Elicitation copy builder (PRD R16, S6).
+*
+* Builds the human-readable approval summary for a gated tool call. The
+* hardening rule (S6) is that nothing model-controlled other than the
+* argument VALUES may enter the copy, and those values are rendered as
+* inert data:
+*
+* - Tool name and description come from the server-side catalog entry,
+*   never from model-authored text (a fake `description` inside the args
+*   is just another argument value inside the JSON block). The catalog
+*   itself may belong to a hostile third-party server (S5), so name and
+*   description are still rendered inert: control characters and bidi
+*   overrides neutralized, length capped, description as an escaped JSON
+*   string literal so it can never forge prompt structure.
+* - Arguments pass through the developer's redaction hook (R16) BEFORE
+*   being rendered anywhere; if the hook throws we fail closed and render
+*   `[redaction failed]` instead of any argument data.
+* - Arguments are rendered as an indented, pretty-printed JSON block.
+*   `JSON.stringify` escapes every newline and quote inside string values,
+*   so hostile values ("IGNORE PREVIOUS INSTRUCTIONS: ...") stay quoted on
+*   an indented line inside the block and can never break out into prose.
+* - The machine state name (model-authored, required by R16) is rendered
+*   as a length-capped JSON string literal — quoted and escaped, inert.
+* - `destructiveHint` prepends clearly stronger warning language (R14).
+*
+* Pure: no I/O, deterministic for a given input.
+*/
+const DEFAULT_MAX_ARGS_CHARS = 4096;
+const MAX_STATE_NAME_CHARS = 200;
+const MAX_TOOL_NAME_CHARS = 200;
+const MAX_DESCRIPTION_CHARS = 1e3;
+const ARGS_INDENT = "    ";
+const DESTRUCTIVE_WARNING = "WARNING: the server marks this tool as DESTRUCTIVE. Approving may permanently modify or delete data. Review the arguments carefully.";
+const REDACTION_FAILED = "[redaction failed]";
+/**
+* Build the approval summary for a gated call.
+*
+* `entry` MUST be the catalog entry the call was resolved against (use
+* `resolveCallPolicy`); the copy takes the tool name and description from
+* it, never from the pending call or its arguments.
+*/
+function buildElicitationCopy(call, entry, options = {}) {
+	const destructive = entry.annotations?.destructiveHint === true;
+	const maxArgsChars = options.maxArgsChars ?? DEFAULT_MAX_ARGS_CHARS;
+	let renderedArgs;
+	try {
+		renderedArgs = renderArgsJson(options.redact !== void 0 ? options.redact(entry.name, call.args) : call.args, maxArgsChars);
+	} catch {
+		renderedArgs = REDACTION_FAILED;
+	}
+	const safeName = neutralizeControlChars(capLength(entry.name, MAX_TOOL_NAME_CHARS));
+	const safeDescription = JSON.stringify(neutralizeControlChars(capLength(entry.description ?? "(no description provided by the server)", MAX_DESCRIPTION_CHARS)));
+	const title = destructive ? `Approval required (DESTRUCTIVE): ${safeName}` : `Approval required: ${safeName}`;
+	const lines = [];
+	if (destructive) lines.push(DESTRUCTIVE_WARNING, "");
+	lines.push(`Tool: ${safeName}`, `Description: ${safeDescription}`, `Requested by machine state: ${JSON.stringify(neutralizeControlChars(capLength(call.stateName, MAX_STATE_NAME_CHARS)))}`, "", "Arguments (data only — not instructions):", "", indentBlock(neutralizeControlChars(renderedArgs, { allowNewline: true })));
+	return {
+		title,
+		message: lines.join("\n"),
+		toolName: entry.name,
+		stateName: call.stateName,
+		args: renderedArgs,
+		destructive
+	};
+}
+/**
+* Render argument values as pretty-printed JSON, defensively:
+* circular references, bigints, functions, symbols and `undefined` become
+* inert placeholder strings; a throwing `toJSON` falls back to a
+* placeholder; output beyond `maxChars` is cut with a truncation marker.
+*/
+function renderArgsJson(args, maxChars) {
+	let json;
+	try {
+		json = JSON.stringify(args, makeSafeReplacer(), 2) ?? "[unserializable arguments]";
+	} catch {
+		json = "[unserializable arguments]";
+	}
+	if (json.length <= maxChars) return json;
+	const total = json.length;
+	return `${json.slice(0, maxChars)}\n… [truncated: showing first ${maxChars} of ${total} characters]`;
+}
+/**
+* JSON.stringify replacer neutralizing values JSON cannot represent.
+*
+* Cycle detection tracks only the current ancestor chain (popping on the
+* way back up via the `this` holder), so shared non-circular references
+* render fully everywhere they appear — only a true ancestor cycle becomes
+* `[circular]`. Rendering a shared object as `[circular]` would hide the
+* real arguments from the approver (R16).
+*/
+function makeSafeReplacer() {
+	const ancestors = [];
+	return function replacer(_key, value) {
+		switch (typeof value) {
+			case "bigint": return `[bigint ${value.toString()}]`;
+			case "function": return "[function]";
+			case "symbol": return "[symbol]";
+			case "undefined": return "[undefined]";
+		}
+		if (typeof value === "object" && value !== null) {
+			while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) ancestors.pop();
+			if (ancestors.includes(value)) return "[circular]";
+			ancestors.push(value);
+		}
+		return value;
+	};
+}
+/** Prefix every line so the block reads as data, not prose. */
+function indentBlock(text) {
+	return text.split("\n").map((line) => ARGS_INDENT + line).join("\n");
+}
+//#endregion
+//#region src/machine-host/contract.ts
+/**
+* The authoring contract (PRD R5–R8) — the exact surface an LLM-authored
+* machine module may use, and the in-VM code implementing it.
+*
+* The module source here is appended to the typegen-generated bridge and
+* mounted together at `@astral-mcp/tools`, so an authored module writes:
+*
+* ```ts
+* import { setup } from 'xstate';
+* import { toolCall } from '@astral-mcp/tools';
+* ```
+*
+* `toolCall` is the ONLY supported way to reach a tool (R7). It returns an
+* ordinary XState action function, so the machine never models a tool call
+* as an invoked promise actor — restoring a snapshot restarts invoked
+* actors, which would re-execute an already-approved write.
+*/
+/**
+* Prelude + `toolCall` implementation, appended to the generated bridge.
+*
+* `toolCall` pushes a request onto an in-VM queue that the host drains after
+* the actor settles. It is deliberately synchronous and promise-free: the
+* machine records *that* it wants a call, and the host — never the machine —
+* performs the I/O and injects the result as an event (R7, S1).
+*
+* The generated bridge's `tools.<name>(args)` functions reach the host
+* through the sandbox's `env` binding; the shim below wires the global the
+* bridge expects to that binding. Calling `tools.<name>()` directly also
+* registers a gated request, but the returned promise is never resolved
+* within the segment — awaiting it is the banned pattern. Author with
+* `toolCall`.
+*/
+const TOOL_CALL_MODULE_SOURCE = `
+// --- Projection machine-host prelude -----------------------------------
+// Bind the generated bridge's host hook to the sandbox env binding.
+if (typeof globalThis.__projection_toolcall !== 'function') {
+  globalThis.__projection_toolcall = function (name, args) {
+    return env.__projection_toolCall(name, args);
+  };
+}
+
+function __projQueue() {
+  const state = globalThis.__projection.state;
+  if (!state.queue) state.queue = [];
+  return state.queue;
+}
+
+let __projSeq = 0;
+
+/**
+ * Request a tool call from a machine action.
+ *
+ *   entry: toolCall('write_file', ({ context }) => ({ path: context.path }))
+ *
+ * @param name  Tool name exactly as catalogued.
+ * @param args  Plain object, or a function of the XState action arguments
+ *              ({ context, event }) returning one.
+ * @param options  Optional { id } to correlate the resulting event; a
+ *              stable id is generated when omitted.
+ */
+export function toolCall(name, args, options) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('toolCall(name, args): name must be a non-empty tool name string');
+  }
+  return function projectionToolCall(actionArgs) {
+    let resolved;
+    try {
+      resolved = typeof args === 'function' ? args(actionArgs) : args;
+    } catch (err) {
+      throw new Error('toolCall("' + name + '") argument function threw: ' + String(err));
+    }
+    if (resolved === undefined || resolved === null) resolved = {};
+    if (typeof resolved !== 'object' || Array.isArray(resolved)) {
+      throw new Error('toolCall("' + name + '") arguments must resolve to a plain object');
+    }
+    __projSeq += 1;
+    const id = options && options.id !== undefined ? String(options.id) : name + '#' + __projSeq;
+    __projQueue().push({ id: id, name: name, args: resolved });
+  };
+}
+
+/**
+ * Guard matching the event for one specific call id.
+ *
+ * XState delivers an event to every region that can handle it, so a machine
+ * with two calls outstanding at once (parallel regions) MUST guard each
+ * waiting state — otherwise one region consumes the other's result and the
+ * machine records an approved write against the wrong branch.
+ *
+ *   on: { TOOL_RESULT: { guard: whenCall('a'), target: 'done' } }
+ */
+export function whenCall(id) {
+  const wanted = String(id);
+  return function projectionWhenCall(guardArgs) {
+    const event = guardArgs && guardArgs.event;
+    return Boolean(event) && event.callId === wanted;
+  };
+}
+`;
+/**
+* Human-readable authoring contract. `discover_apis` publishes this inline
+* (R3) so a model can author a valid machine without fetching resources.
+*/
+const AUTHORING_CONTRACT = `Projection authoring contract (execute_machine)
+
+Write ONE module whose only top-level statements are imports and a single
+default-exported XState v5 machine. The module is re-evaluated on every
+approval round trip, so top-level side effects are rejected.
+
+  import { setup } from 'xstate';
+  import { toolCall } from '@astral-mcp/tools';
+
+  export default setup({}).createMachine({ /* ... */ });
+
+Rules:
+1. Default-export a machine built with XState v5 setup(...).createMachine(...).
+   XState v4 Machine(...) is rejected.
+2. Machine context must be JSON-serializable at all times. No Map, Set, Date,
+   class instances, functions, undefined, bigint or symbols in context.
+3. Request tools with the toolCall action. NEVER wrap a tool call in
+   fromPromise/invoke — restored snapshots restart invoked actors, which
+   would re-execute an approved write. Machines using invoke are rejected.
+4. After a toolCall, wait in a state for one of these events:
+     TOOL_RESULT { callId, result }   the call succeeded
+     TOOL_ERROR  { callId, error }    the call failed
+     TOOL_DENIED { callId, reason }   the user declined, or policy denies it
+   Denial is not an abort: handle TOOL_DENIED and continue or finish.
+   IMPORTANT: if your machine has more than one call outstanding at the same
+   time (parallel regions), give each toolCall an explicit id and guard every
+   waiting state with whenCall(id) — events reach every region that can
+   handle them, so an unguarded region will consume another call's result:
+
+     import { toolCall, whenCall } from '@astral-mcp/tools';
+     entry: toolCall('write_file', () => ({ path: '/a' }), { id: 'a' }),
+     on: { TOOL_RESULT: { guard: whenCall('a'), target: 'done' } },
+5. Read-only tools run immediately. Every other tool pauses the machine for
+   user approval; the arguments captured at that moment are the arguments
+   that execute.
+6. Only 'xstate' and '@astral-mcp/tools' resolve as imports. There is no
+   filesystem, no network, no fetch. All working state lives in context.
+7. Finish by reaching a final state. Use the machine's output for the result.
+
+Example — happy path with a read-only call:
+
+  import { setup, assign } from 'xstate';
+  import { toolCall } from '@astral-mcp/tools';
+
+  export default setup({}).createMachine({
+    id: 'readNotes',
+    context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),
+    initial: 'reading',
+    states: {
+      reading: {
+        entry: toolCall('read_file', ({ context }) => ({ path: context.path })),
+        on: {
+          TOOL_RESULT: { target: 'done', actions: assign({ text: ({ event }) => event.result }) },
+          TOOL_ERROR: 'failed',
+        },
+      },
+      done: { type: 'final' },
+      failed: { type: 'final' },
+    },
+    output: ({ context }) => ({ text: context.text }),
+  });
+
+Example — handling a denied approval:
+
+  import { setup, assign } from 'xstate';
+  import { toolCall } from '@astral-mcp/tools';
+
+  export default setup({}).createMachine({
+    id: 'writeNotes',
+    context: { status: 'pending' },
+    initial: 'writing',
+    states: {
+      writing: {
+        entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),
+        on: {
+          TOOL_RESULT: { target: 'done', actions: assign({ status: 'written' }) },
+          TOOL_DENIED: { target: 'done', actions: assign({ status: 'skipped' }) },
+          TOOL_ERROR: { target: 'done', actions: assign({ status: 'failed' }) },
+        },
+      },
+      done: { type: 'final' },
+    },
+    output: ({ context }) => ({ status: context.status }),
+  });
+`;
+//#endregion
+//#region src/machine-host/drivers.ts
+/**
+* Driver module sources evaluated inside the sandbox (PRD R24, R5–R7).
+*
+* The sandbox evaluates an ESM module and marshals its default export back
+* to the host, so each host↔VM step is a small module built here. Values
+* interpolated into these templates are always `JSON.stringify`d — never
+* raw text — so nothing from the model or the wrapped server can extend the
+* driver's own code.
+*/
+/**
+* Static validation of the default-exported machine (R24).
+*
+* Runs without starting an actor: entry actions must not fire during
+* validation, or a `toolCall` in the initial state would register a request
+* before policy has been consulted. `createActor(m).getSnapshot()` yields
+* the initial snapshot with actions resolved but not executed.
+*
+* The caller's `input` is passed to the probe actor exactly as the
+* bootstrap will pass it: a machine whose context factory dereferences
+* `input` (`context: ({ input }) => ({ path: input.path })`) must validate
+* against the input it will actually run with, not against `undefined`.
+*/
+function validationDriver(maxStateNodes, input) {
+	const probeActor = input === void 0 ? "createActor(machine)" : `createActor(machine, { input: ${JSON.stringify(input)} })`;
+	return `
+import { createActor } from 'xstate';
+
+const g = globalThis.__projection;
+const machine = g.module ? g.module.default : undefined;
+const fail = (code, detail) => ({ ok: false, code: code, detail: detail === undefined ? null : detail });
+
+function run() {
+  if (machine === undefined || machine === null) {
+    return fail('no_default_export');
+  }
+  if (typeof machine !== 'object' && typeof machine !== 'function') {
+    return fail('default_export_not_machine', typeof machine);
+  }
+  // XState v5 machines carry __xstatenode and a root state node; a v4
+  // Machine(...) result and every non-machine value lack one or the other.
+  const isV5 =
+    machine.__xstatenode === true &&
+    machine.root !== undefined &&
+    typeof machine.getPersistedSnapshot === 'function';
+  if (!isV5) {
+    const looksV4 =
+      machine.__xstatenode === true ||
+      typeof machine.withConfig === 'function' ||
+      typeof machine.withContext === 'function';
+    return fail(looksV4 ? 'xstate_v4_machine' : 'default_export_not_machine');
+  }
+
+  // (a) State-node count: a tree walk of the instantiated definition (R12).
+  let nodes = 0;
+  const walkNodes = (node) => {
+    nodes += 1;
+    if (nodes > ${JSON.stringify(maxStateNodes)}) return;
+    const states = node.states;
+    if (states) for (const key of Object.keys(states)) walkNodes(states[key]);
+  };
+  walkNodes(machine.root);
+  if (nodes > ${JSON.stringify(maxStateNodes)}) {
+    return fail('too_many_state_nodes', nodes);
+  }
+
+  // (b) Banned invoked actors (R7). Any invoke at all is rejected: a
+  // restored snapshot restarts invoked actors, so an invoked tool call
+  // would re-execute an approved write. Walk the raw config, which is the
+  // authored shape before XState normalizes it.
+  const seen = new Set();
+  let invokeAt = null;
+  const walkConfig = (value, path) => {
+    if (invokeAt !== null) return;
+    if (value === null || typeof value !== 'object') return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (!Array.isArray(value) && value.invoke !== undefined) {
+      invokeAt = path.length > 0 ? path : '(root)';
+      return;
+    }
+    for (const key of Object.keys(value)) {
+      walkConfig(value[key], path.length > 0 ? path + '.' + key : key);
+    }
+  };
+  walkConfig(machine.config, '');
+  if (invokeAt !== null) {
+    return fail('invoke_banned', invokeAt);
+  }
+
+  // (c) Serializability probe (R6). JSON.stringify silently drops functions
+  // and flattens Map/Set, so walk for non-JSON values instead of relying on
+  // a throw, then round-trip to catch anything left (e.g. cycles).
+  let snapshot;
+  try {
+    snapshot = ${probeActor}.getSnapshot();
+  } catch (err) {
+    return fail('machine_init_threw', String(err && err.message ? err.message : err));
+  }
+  const badPath = findNonSerializable(snapshot.context, 'context', new Set());
+  if (badPath !== null) {
+    return fail('context_not_serializable', badPath);
+  }
+  try {
+    JSON.parse(JSON.stringify(snapshot.context));
+  } catch (err) {
+    return fail('context_not_serializable', 'context (' + String(err && err.message ? err.message : err) + ')');
+  }
+  return { ok: true, stateNodes: nodes };
+}
+
+function findNonSerializable(value, path, seen) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'string' || t === 'number' || t === 'boolean') {
+    return t === 'number' && !Number.isFinite(value) ? path + ' (' + String(value) + ')' : null;
+  }
+  if (t === 'undefined') return path + ' (undefined)';
+  if (t === 'function') return path + ' (function)';
+  if (t === 'symbol') return path + ' (symbol)';
+  if (t === 'bigint') return path + ' (bigint)';
+  if (t !== 'object') return path + ' (' + t + ')';
+  if (seen.has(value)) return path + ' (circular reference)';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i += 1) {
+      const bad = findNonSerializable(value[i], path + '[' + i + ']', seen);
+      if (bad !== null) return bad;
+    }
+    return null;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    const name = value.constructor && value.constructor.name ? value.constructor.name : 'non-plain object';
+    return path + ' (' + name + ')';
+  }
+  for (const key of Object.keys(value)) {
+    const bad = findNonSerializable(value[key], path + '.' + key, seen);
+    if (bad !== null) return bad;
+  }
+  return null;
+}
+
+export default run();
+`;
+}
+/** Read the request queue without starting the actor (top-level effects, R5). */
+const TOP_LEVEL_EFFECT_PROBE = `
+const state = globalThis.__projection.state;
+export default { queued: state.queue ? state.queue.length : 0 };
+`;
+/**
+* Create (or restore) the actor and settle it, returning the drained state.
+*
+* `input` and `snapshot` are interpolated as JSON literals. A restored
+* actor resumes exactly where the snapshot left off (R21).
+*/
+function bootstrapDriver(input, snapshot) {
+	return `
+import { createActor } from 'xstate';
+
+const g = globalThis.__projection;
+const machine = g.module.default;
+if (!g.state.queue) g.state.queue = [];
+
+${DRAIN_HELPER}
+
+const actor = ${snapshot !== void 0 ? `createActor(machine, { snapshot: ${JSON.stringify(snapshot)} })` : input === void 0 ? "createActor(machine)" : `createActor(machine, { input: ${JSON.stringify(input)} })`};
+g.state.actor = actor;
+g.state.drain = drain;
+actor.start();
+
+export default drain();
+`;
+}
+/** Send host events into the running actor and return the drained state. */
+function sendDriver(events) {
+	return `
+const g = globalThis.__projection;
+const events = ${JSON.stringify(events)};
+for (const event of events) {
+  g.state.actor.send(event);
+}
+export default g.state.drain();
+`;
+}
+/** Return the persisted snapshot for sealing into the blob (R20). */
+const SNAPSHOT_DRIVER = `
+const g = globalThis.__projection;
+export default { snapshot: g.state.actor.getPersistedSnapshot() };
+`;
+/**
+* Collect everything the host needs after the actor settles: the queued
+* tool requests (cleared as they are read), the machine status, and the
+* final output when it has reached a final state.
+*/
+const DRAIN_HELPER = `
+function drain() {
+  const snapshot = g.state.actor.getSnapshot();
+  const queue = g.state.queue;
+  const requests = queue.splice(0, queue.length);
+  return {
+    status: snapshot.status,
+    value: snapshot.value === undefined ? null : snapshot.value,
+    output: snapshot.output === undefined ? null : snapshot.output,
+    error: snapshot.error === undefined ? null : String(snapshot.error),
+    requests: requests,
+  };
+}
+`;
+//#endregion
+//#region src/machine-host/host.ts
+/**
+* Machine host — evaluates the authored module in the sandbox, enforces the
+* authoring contract, drives the actor, and turns tool requests into
+* host-side execution or an approval suspension (PRD §7 "Machine host").
+*/
+/**
+* Run one execution segment to completion, suspension, or error.
+*
+* A segment is one MRTR round trip: fresh sandbox, fresh wall-clock budget,
+* fresh logs. On the first segment the module is validated (R24) before the
+* actor starts; on a resume the module is re-evaluated from the re-sent code
+* and the actor is restored from the sealed snapshot.
+*
+* Note: `runSegment` interpolates `input` into driver source without a size
+* check of its own — `executeMachine` enforces `maxInputBytes` before calling
+* it. Callers invoking `runSegment` directly must bound `input` themselves.
+*/
+async function runSegment(options) {
+	const caps = clampCaps(options.caps ?? {});
+	const segment = options.segment ?? 0;
+	const audit = [...options.resume?.audit ?? []];
+	let session;
+	const hookRequests = [];
+	let hookSeq = 0;
+	try {
+		session = await createSandboxSession({
+			code: options.code,
+			...options.lang !== void 0 ? { lang: options.lang } : {},
+			caps,
+			bridgeSource: `${options.bridgeSource}\n${TOOL_CALL_MODULE_SOURCE}`,
+			segment,
+			onToolCall: (call) => {
+				hookSeq += 1;
+				hookRequests.push({
+					id: `${call.name}@${hookSeq}`,
+					name: call.name,
+					args: call.args
+				});
+				return null;
+			}
+		});
+		if (((await session.evaluate(TOP_LEVEL_EFFECT_PROBE)).queued ?? 0) > 0 || hookRequests.length > 0) throw new ProjectionError("validate", "the submitted module requests a tool call at top level", { hint: "Move tool calls into machine states: the module is re-evaluated on every approval round trip, so top-level effects would repeat. Use toolCall(...) as a state entry action." });
+		if (options.resume === void 0) await validate(session, caps, options.input);
+		return await new SegmentRunner({
+			session,
+			caps,
+			segment,
+			catalog: options.catalog,
+			executor: options.executor,
+			...options.policy !== void 0 ? { policy: options.policy } : {},
+			audit,
+			hookRequests,
+			trip: options.resume?.trip ?? 0
+		}).run(options);
+	} catch (err) {
+		return {
+			status: "error",
+			error: toStructuredError(err, session?.getLogs() ?? [])
+		};
+	} finally {
+		await session?.dispose();
+	}
+}
+async function validate(session, caps, input) {
+	const result = await session.evaluate(validationDriver(caps.maxStateNodes, input));
+	if (result.ok) return;
+	throw validationError(result, caps);
+}
+const VALIDATION_SPECS = {
+	no_default_export: {
+		phase: "validate",
+		message: () => "the submitted module has no default export",
+		hint: () => "Default-export a machine: `export default setup({}).createMachine({ ... })`. See discover_apis."
+	},
+	xstate_v4_machine: {
+		phase: "validate",
+		message: () => "the default export is an XState v4 machine, not a v5 machine",
+		hint: () => "Rewrite for XState v5: `import { setup } from \"xstate\"` then `setup({}).createMachine({ ... })` — v4 Machine(...) is not supported."
+	},
+	default_export_not_machine: {
+		phase: "validate",
+		message: (detail) => `the default export is not an XState v5 machine${detail ? ` (got ${detail})` : ""}`,
+		hint: () => "Default-export the machine itself, not an actor or a factory: `export default setup({}).createMachine({ ... })`."
+	},
+	too_many_state_nodes: {
+		phase: "cap_exceeded",
+		message: (detail, caps) => `the machine has ${detail} state nodes, exceeding the limit of ${caps.maxStateNodes}`,
+		hint: (caps) => `Simplify the machine to at most ${caps.maxStateNodes} state nodes, or split the work across separate execute_machine calls.`
+	},
+	invoke_banned: {
+		phase: "validate",
+		message: (detail) => `the machine uses invoke (at ${detail || "the machine root"}), which is not allowed`,
+		hint: () => "Tool calls must use the toolCall action, not fromPromise/invoke: restored snapshots restart invoked actors and would re-execute approved writes. See discover_apis."
+	},
+	context_not_serializable: {
+		phase: "validate",
+		message: (detail) => `machine context is not JSON-serializable at ${detail}`,
+		hint: () => "Keep context to plain JSON values — no Map, Set, Date, class instances, functions or undefined. Store a string or number instead."
+	},
+	machine_init_threw: {
+		phase: "validate",
+		message: (detail) => `creating the machine actor threw: ${detail}`,
+		hint: () => "Fix the error thrown while building the machine context or initial state."
+	}
+};
+function validationError(result, caps) {
+	const detail = result.detail === null ? "" : String(result.detail);
+	const spec = VALIDATION_SPECS[result.code];
+	if (spec === void 0) return new ProjectionError("validate", `machine validation failed: ${result.code}`, { hint: "Review the authoring contract from discover_apis and resubmit." });
+	return new ProjectionError(spec.phase, spec.message(detail, caps), { hint: spec.hint(caps) });
+}
+var SegmentRunner = class {
+	deps;
+	readCalls = 0;
+	eventsProcessed = 0;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async run(options) {
+		const { session } = this.deps;
+		const resume = options.resume;
+		let drained;
+		if (resume === void 0) drained = await session.evaluate(bootstrapDriver(options.input, void 0));
+		else {
+			drained = await session.evaluate(bootstrapDriver(void 0, resume.snapshot));
+			const events = await this.applyVerdicts(resume.pending, resume.verdicts);
+			drained = await this.send(events);
+		}
+		const gatedBatch = [];
+		for (;;) {
+			if (drained.status === "error") throw new ProjectionError("runtime", `the machine errored: ${drained.error ?? "unknown"}`, { hint: "Handle the failure in the machine (e.g. a TOOL_ERROR transition) or fix the action that threw." });
+			const requests = this.collectRequests(drained);
+			if (requests.length === 0) {
+				if (gatedBatch.length > 0) return await this.suspend(gatedBatch);
+				if (drained.status === "done" || drained.status === "stopped") return this.complete(drained);
+				throw new ProjectionError("runtime", `the machine is stuck in state ${JSON.stringify(drained.value)} with no pending tool call and no final state`, { hint: "Every non-final state must either request a tool call or transition on an event the host sends. Reach a final state to return a result." });
+			}
+			const { events, gated } = await this.classify(requests, drained.value);
+			gatedBatch.push(...gated);
+			if (events.length === 0) return await this.suspend(gatedBatch);
+			drained = await this.send(events);
+		}
+	}
+	/** Merge queued `toolCall` requests with any that came via the bridge hook. */
+	collectRequests(drained) {
+		const hook = this.deps.hookRequests.splice(0, this.deps.hookRequests.length);
+		return [...drained.requests, ...hook];
+	}
+	/**
+	* Apply the policy to each request: run read-only calls now, deny denied
+	* ones now, and set gated ones aside for approval.
+	*/
+	async classify(requests, stateValue) {
+		const events = [];
+		const gated = [];
+		const stateName = describeState(stateValue);
+		for (const request of requests) {
+			const call = {
+				id: request.id,
+				name: request.name,
+				args: request.args,
+				stateName
+			};
+			const resolved = resolveCallPolicy(call, this.deps.catalog, this.deps.policy);
+			if (!resolved.ok) throw resolved.error;
+			if (resolved.decision === "deny") {
+				const reason = policyDeniedReason(request.name);
+				events.push({
+					type: "TOOL_DENIED",
+					callId: request.id,
+					reason
+				});
+				this.deps.audit.push({
+					callId: request.id,
+					tool: request.name,
+					args: request.args,
+					decision: "denied_by_policy",
+					reason
+				});
+				continue;
+			}
+			if (resolved.decision === "ask") {
+				gated.push(call);
+				continue;
+			}
+			this.readCalls += 1;
+			if (this.readCalls > this.deps.caps.maxReadCallsPerSegment) throw new ProjectionError("cap_exceeded", `the machine made more than ${this.deps.caps.maxReadCallsPerSegment} read-only tool calls in one segment`, { hint: `Batch the work or reduce the number of read-only calls to at most ${this.deps.caps.maxReadCallsPerSegment} per segment.` });
+			events.push(await this.execute(request, "auto"));
+		}
+		return {
+			events,
+			gated
+		};
+	}
+	/** Execute one call against the wrapped server and build its event. */
+	async execute(request, decision) {
+		const outcome = await this.deps.executor.callTool(this.deps.catalog.alias, request.name, request.args);
+		if (outcome.ok) {
+			this.deps.audit.push({
+				callId: request.id,
+				tool: request.name,
+				args: request.args,
+				decision
+			});
+			return {
+				type: "TOOL_RESULT",
+				callId: request.id,
+				result: outcome.result
+			};
+		}
+		this.deps.audit.push({
+			callId: request.id,
+			tool: request.name,
+			args: request.args,
+			decision: "error",
+			reason: outcome.error.message
+		});
+		return {
+			type: "TOOL_ERROR",
+			callId: request.id,
+			error: outcome.error
+		};
+	}
+	/**
+	* Turn the client's verdicts into events (R17).
+	*
+	* 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).
+	*/
+	async applyVerdicts(pending, verdicts) {
+		const events = [];
+		for (const [key, call] of Object.entries(pending)) {
+			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;
+				events.push({
+					type: "TOOL_DENIED",
+					callId: call.id,
+					...reason !== void 0 ? { reason } : {}
+				});
+				this.deps.audit.push({
+					callId: call.id,
+					tool: call.name,
+					args: call.args,
+					decision: "declined",
+					...reason !== void 0 ? { reason } : {}
+				});
+				continue;
+			}
+			events.push(await this.execute({
+				id: call.id,
+				name: call.name,
+				args: call.args
+			}, "approved"));
+		}
+		return events;
+	}
+	/** Send events into the actor, counting them against the segment cap. */
+	async send(events) {
+		this.eventsProcessed += events.length;
+		if (this.eventsProcessed > this.deps.caps.maxEventsPerSegment) throw new ProjectionError("cap_exceeded", `the machine processed more than ${this.deps.caps.maxEventsPerSegment} events in one segment`, { hint: `Reduce the number of transitions; at most ${this.deps.caps.maxEventsPerSegment} events run per segment.` });
+		return await this.deps.session.evaluate(sendDriver(events));
+	}
+	/**
+	* Suspend for approval, sealing the exact calls that were requested.
+	*
+	* Every event the machine could act on has already been delivered by the
+	* settle loop, so the in-VM request queue is empty and the snapshot taken
+	* here is complete.
+	*/
+	async suspend(gated) {
+		const { snapshot } = await this.deps.session.evaluate(SNAPSHOT_DRIVER);
+		const pending = {};
+		for (const call of gated) pending[call.id] = call;
+		return {
+			status: "suspended",
+			pending,
+			snapshot,
+			trip: this.deps.trip + 1,
+			audit: this.deps.audit,
+			logs: this.logs()
+		};
+	}
+	complete(drained) {
+		const output = drained.output;
+		const size = Buffer.byteLength(JSON.stringify(output ?? null), "utf8");
+		if (size > this.deps.caps.maxResultBytes) throw new ProjectionError("cap_exceeded", `the final result is ${size} bytes, exceeding the limit of ${this.deps.caps.maxResultBytes}`, { hint: `Return a summary instead of the full data: the result must be at most ${this.deps.caps.maxResultBytes} bytes.` });
+		return {
+			status: "completed",
+			output,
+			audit: this.deps.audit,
+			logs: this.logs()
+		};
+	}
+	logs() {
+		return this.deps.session.getLogs();
+	}
+};
+/** Render an XState state value as a readable path for elicitation copy (R16). */
+function describeState(value) {
+	if (typeof value === "string") return value;
+	if (value === null || value === void 0) return "(unknown)";
+	const parts = [];
+	const walk = (node, prefix) => {
+		if (typeof node === "string") {
+			parts.push(prefix.length > 0 ? `${prefix}.${node}` : node);
+			return;
+		}
+		if (typeof node === "object" && node !== null) for (const [key, child] of Object.entries(node)) walk(child, prefix.length > 0 ? `${prefix}.${key}` : key);
+	};
+	walk(value, "");
+	return parts.length > 0 ? parts.join(" | ") : JSON.stringify(value);
+}
+//#endregion
+//#region src/mrtr/protocol.ts
+/**
+* The JSON Schema an approval elicitation asks the client to collect, typed
+* as the SDK's restricted elicitation schema so `inputRequired.elicit()`
+* accepts it without a cast.
+*
+* Projection-specific: MRTR carries whatever schema the server asks for, and
+* an approval prompt whose only payload is an optional decline reason is our
+* product decision (R16/R17), not a protocol shape.
+*/
+const APPROVAL_SCHEMA = {
+	type: "object",
+	properties: { reason: {
+		type: "string",
+		description: "Optional note shown to the model when declining."
+	} },
+	additionalProperties: false
+};
+/**
+* Protocol revision that introduced MRTR.
+*
+* The SDK has no exported constant for it: `LATEST_PROTOCOL_VERSION` and
+* `SUPPORTED_PROTOCOL_VERSIONS` cover the *legacy* (`initialize`-negotiated)
+* family only — `2025-11-25` and earlier. The 2026-07-28 era is selected by
+* `server/discover`, and the SDK models it as the `ProtocolEra` value
+* `'modern'` rather than as a version string. We keep the literal purely so
+* error copy can name the revision a client must speak (R28).
+*/
+const MRTR_PROTOCOL_REVISION = "2026-07-28";
+/**
+* Whether the era a request is being served on can carry MRTR (R28).
+*
+* The SDK binds an era to the *serving instance*, not to a per-request
+* header: `createMcpHandler` / `serveStdio` hand the era to the server
+* factory as `McpRequestContext.era`, and a hand-connected `McpServer` is
+* always `'legacy'`. So this takes the era, not a version string — there is
+* no `extra.protocolVersion` to read, and reading one was the bug this
+* migration fixes (docs/DECISIONS.md D1).
+*/
+function supportsMrtr(era) {
+	return era === "modern";
+}
+//#endregion
+//#region src/mrtr/adapter.ts
+/**
+* MRTR adapter — maps segment outcomes to `tools/call` results and parses
+* retries back into verdicts (PRD §7 "MRTR adapter"; R15, R17, R18, R27,
+* R28, S2).
+*/
+/**
+* Run `execute_machine` for one `tools/call`, whether it is a first attempt
+* or an MRTR retry.
+*
+* Statelessness (R27): everything needed to resume rides in `requestState`,
+* so any instance can serve any retry. Nothing is held between calls.
+*/
+async function executeMachine(args, deps) {
+	const caps = clampCaps(deps.caps ?? {});
+	try {
+		assertCodeSize(args.code, caps);
+		assertInputSize(args.input, caps);
+		const resume = args.requestState !== void 0 ? openResume(args, deps, caps) : void 0;
+		return toToolCallResult(await runSegment({
+			code: args.code,
+			...args.lang !== void 0 ? { lang: args.lang } : {},
+			...args.input !== void 0 ? { input: args.input } : {},
+			catalog: deps.catalog,
+			bridgeSource: deps.bridgeSource,
+			executor: deps.executor,
+			caps,
+			...deps.policy !== void 0 ? { policy: deps.policy } : {},
+			segment: resume?.trip ?? 0,
+			...resume !== void 0 ? { resume } : {}
+		}), args, deps, caps);
+	} catch (err) {
+		return errorResult(toStructuredError(err));
+	}
+}
+/**
+* Verify the echoed blob and turn `inputResponses` into verdicts.
+*
+* The blob sealer performs the full R21 check chain (authenticate, version,
+* expiry, codeHash, server identity) and throws on any failure, so nothing
+* gated executes from an unverified blob.
+*/
+function openResume(args, deps, caps) {
+	const payload = openBlob(args.requestState, {
+		code: args.code,
+		serverIdentity: deps.catalog.identity,
+		config: deps.blob
+	});
+	if (payload.trip > caps.maxRoundTrips) throw new ProjectionError("terminal", `this workflow reached the limit of ${caps.maxRoundTrips} approval round trips`, { hint: `Restructure the machine to need at most ${caps.maxRoundTrips} approval round trips, for example by batching writes into fewer states.` });
+	const verdicts = {};
+	for (const key of Object.keys(payload.pending)) {
+		const view = inputResponse(args.inputResponses, key);
+		if (view.kind !== "elicit" || view.action !== "accept") {
+			const reason = view.kind === "elicit" ? readReason(view.content) : void 0;
+			verdicts[key] = reason !== void 0 ? {
+				kind: "declined",
+				reason
+			} : { kind: "declined" };
+			continue;
+		}
+		verdicts[key] = { kind: "approved" };
+	}
+	return {
+		snapshot: payload.snapshot,
+		pending: payload.pending,
+		verdicts,
+		audit: payload.audit,
+		trip: payload.trip
+	};
+}
+function readReason(content) {
+	const reason = content?.["reason"];
+	return typeof reason === "string" && reason.length > 0 ? reason : void 0;
+}
+function toToolCallResult(outcome, args, deps, caps) {
+	switch (outcome.status) {
+		case "completed": return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(outcome.output ?? null, null, 2)
+			}, ...logBlocks(outcome.logs)],
+			structuredContent: {
+				output: outcome.output ?? null,
+				approvals: outcome.audit,
+				logs: outcome.logs
+			}
+		};
+		case "suspended": return suspendResult(outcome, args, deps, caps);
+		case "error": return errorResult(outcome.error);
+	}
+}
+function suspendResult(outcome, args, deps, caps) {
+	const fail = (phase, message, hint) => errorResult({
+		phase,
+		message,
+		diagnostics: [],
+		hint,
+		logs: outcome.logs
+	});
+	if (!supportsMrtr(deps.protocolEra)) return fail("protocol", `this machine needs approval for a non-read-only tool call, which requires MCP protocol revision ${MRTR_PROTOCOL_REVISION} or later (this request is being served on the ${deps.protocolEra ?? "legacy"} protocol era)`, "Author a machine that only calls read-only tools, or connect with a client that negotiates the 2026-07-28 revision (SDK v2: `versionNegotiation: { mode: \"auto\" }`).");
+	if (outcome.trip > caps.maxRoundTrips) return fail("terminal", `this workflow reached the limit of ${caps.maxRoundTrips} approval round trips`, `Restructure the machine to need at most ${caps.maxRoundTrips} approval round trips.`);
+	const inputRequests = {};
+	for (const [key, call] of Object.entries(outcome.pending)) {
+		const entry = findTool(deps.catalog, call.name);
+		if (entry === void 0) return fail("validate", `the machine requested approval for unknown tool "${call.name}"`, "Call only tools listed by discover_apis.");
+		const copy = buildElicitationCopy(call, entry, deps.redact !== void 0 ? { redact: deps.redact } : {});
+		inputRequests[key] = inputRequired.elicit({
+			message: `${copy.title}\n\n${copy.message}`,
+			requestedSchema: APPROVAL_SCHEMA
+		});
+	}
+	const payload = buildBlobPayload({
+		code: args.code,
+		serverIdentity: deps.catalog.identity,
+		snapshot: outcome.snapshot,
+		pending: outcome.pending,
+		audit: outcome.audit,
+		trip: outcome.trip,
+		...deps.blob.ttlMs !== void 0 ? { ttlMs: deps.blob.ttlMs } : {}
+	});
+	let requestState;
+	try {
+		requestState = sealBlob(payload, deps.blob);
+	} catch (err) {
+		return errorResult({
+			...toStructuredError(err, outcome.logs),
+			logs: outcome.logs
+		});
+	}
+	return inputRequired({
+		inputRequests,
+		requestState
+	});
+}
+/** Every failure is a normal result with `isError: true` and a structured body (R25). */
+function errorResult(error) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: JSON.stringify(error, null, 2)
+		}],
+		structuredContent: { ...error }
+	};
+}
+function logBlocks(logs) {
+	if (logs.length === 0) return [];
+	return [{
+		type: "text",
+		text: `Console output:\n${logs.map((log) => `[${log.level}] ${log.message}`).join("\n")}`
+	}];
+}
+function assertCodeSize(code, caps) {
+	const size = Buffer.byteLength(code, "utf8");
+	if (size > caps.maxCodeBytes) throw new ProjectionError("cap_exceeded", `submitted code is ${size} bytes, exceeding the limit of ${caps.maxCodeBytes}`, { hint: `Shorten the machine to at most ${caps.maxCodeBytes} bytes.` });
+}
+/**
+* The input is interpolated into the validation and bootstrap driver sources
+* as a JSON literal, so its serialized size — not the wire size of the raw
+* value — is what the sandbox actually pays for. Bounding it here yields a
+* structured cap_exceeded error instead of an opaque WASM memory failure.
+*/
+function assertInputSize(input, caps) {
+	if (input === void 0) return;
+	let json;
+	try {
+		json = JSON.stringify(input);
+	} catch (err) {
+		throw new ProjectionError("validate", "machine input is not JSON-serializable", {
+			hint: "Remove circular references from the input; it must serialize to plain JSON.",
+			cause: err
+		});
+	}
+	if (json === void 0) return;
+	const size = Buffer.byteLength(json, "utf8");
+	if (size > caps.maxInputBytes) throw new ProjectionError("cap_exceeded", `submitted input serializes to ${size} bytes, exceeding the limit of ${caps.maxInputBytes}`, { hint: `Shrink the machine input to at most ${caps.maxInputBytes} bytes of JSON.` });
+}
+//#endregion
+//#region src/mrtr/discover.ts
+/**
+* `discover_apis` — the tool that teaches the model to author a machine
+* (PRD G6, R3, R29).
+*
+* Returns a compact inline overview that is sufficient on its own, plus a
+* `resource_link` per artifact so a model can pull full contents only when
+* it wants them. Clients with weak resource support still function.
+*/
+/** Stable URIs the server serves via `resources/read` (R3). */
+const RESOURCE_URIS = {
+	toolTypes: "projection://types/tools.d.ts",
+	contract: "projection://docs/authoring-contract.md",
+	happyPath: "projection://examples/happy-path.ts",
+	denialFallback: "projection://examples/denial-fallback.ts"
+};
+const EXAMPLE_HAPPY_PATH = `import { setup, assign } from 'xstate';
+import { toolCall } from '@astral-mcp/tools';
+
+// Read a file and return its contents. Read-only calls run immediately,
+// so this whole machine completes in one round trip.
+export default setup({}).createMachine({
+  id: 'readNotes',
+  context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),
+  initial: 'reading',
+  states: {
+    reading: {
+      entry: toolCall('read_file', ({ context }) => ({ path: context.path })),
+      on: {
+        TOOL_RESULT: {
+          target: 'done',
+          actions: assign({ text: ({ event }) => event.result }),
+        },
+        TOOL_ERROR: {
+          target: 'failed',
+          actions: assign({ text: ({ event }) => \`error: \${event.error.message}\` }),
+        },
+      },
+    },
+    done: { type: 'final' },
+    failed: { type: 'final' },
+  },
+  output: ({ context }) => ({ text: context.text }),
+});
+`;
+const EXAMPLE_DENIAL_FALLBACK = `import { setup, assign } from 'xstate';
+import { toolCall } from '@astral-mcp/tools';
+
+// Write a file, but keep going if the user declines. TOOL_DENIED is an
+// ordinary transition — denial is never an automatic abort.
+export default setup({}).createMachine({
+  id: 'writeWithFallback',
+  context: { status: 'pending', note: null },
+  initial: 'writing',
+  states: {
+    writing: {
+      entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),
+      on: {
+        TOOL_RESULT: {
+          target: 'summarizing',
+          actions: assign({ status: 'written' }),
+        },
+        TOOL_DENIED: {
+          // The user said no: record it and carry on with the read-only
+          // part of the work instead of failing the whole workflow.
+          target: 'summarizing',
+          actions: assign({
+            status: 'skipped',
+            note: ({ event }) => event.reason ?? 'declined by user',
+          }),
+        },
+        TOOL_ERROR: {
+          target: 'summarizing',
+          actions: assign({ status: 'failed' }),
+        },
+      },
+    },
+    summarizing: {
+      entry: toolCall('list_dir', () => ({ path: '/' })),
+      on: {
+        TOOL_RESULT: { target: 'done' },
+        TOOL_ERROR: { target: 'done' },
+      },
+    },
+    done: { type: 'final' },
+  },
+  output: ({ context }) => ({ status: context.status, note: context.note }),
+});
+`;
+/** Build the resources Projection serves for a wrapped server (R3). */
+function buildResources(catalog, dts) {
+	return [
+		{
+			uri: RESOURCE_URIS.toolTypes,
+			name: "tools.d.ts",
+			description: `TypeScript definitions for the tools of ${catalog.identity}.`,
+			mimeType: "text/plain",
+			text: dts
+		},
+		{
+			uri: RESOURCE_URIS.contract,
+			name: "authoring-contract.md",
+			description: "Rules an authored machine must follow.",
+			mimeType: "text/markdown",
+			text: AUTHORING_CONTRACT
+		},
+		{
+			uri: RESOURCE_URIS.happyPath,
+			name: "happy-path.ts",
+			description: "Example machine: read-only work, completes in one call.",
+			mimeType: "text/plain",
+			text: EXAMPLE_HAPPY_PATH
+		},
+		{
+			uri: RESOURCE_URIS.denialFallback,
+			name: "denial-fallback.ts",
+			description: "Example machine: continues gracefully when approval is declined.",
+			mimeType: "text/plain",
+			text: EXAMPLE_DENIAL_FALLBACK
+		}
+	];
+}
+/**
+* The `discover_apis` result: an inline overview sufficient to author a
+* simple machine unaided, plus resource links for the full artifacts.
+*/
+function discoverApis(catalog, overview) {
+	const inline = [
+		`Projection code mode over "${catalog.identity}".`,
+		"",
+		`XState version: ${XSTATE_VERSION} (pinned). Importable modules: 'xstate', '@astral-mcp/tools'. Nothing else resolves; there is no network and no filesystem.`,
+		"",
+		overview,
+		"",
+		AUTHORING_CONTRACT
+	].join("\n");
+	const links = buildResources(catalog, "").map((resource) => ({
+		type: "resource_link",
+		uri: resource.uri,
+		name: resource.name,
+		description: resource.description,
+		mimeType: resource.mimeType
+	}));
+	return { content: [{
+		type: "text",
+		text: inline
+	}, ...links] };
+}
+/**
+* The wrapped server's `instructions`, followed by the code-mode preamble
+* (R29). The preamble is library copy the integrating developer can replace.
+*/
+const DEFAULT_CODE_MODE_PREAMBLE = `This server runs in code mode: instead of calling its tools directly, author an XState v5 state machine and run it with execute_machine, which orchestrates the tool calls for you. Any tool that is not read-only pauses the machine and asks the user to approve that specific action before it runs. Call discover_apis first for the tool types, the authoring contract, and worked examples.`;
+function buildInstructions(catalog, preamble) {
+	const wrapped = catalog.instructions?.trim();
+	const codeMode = preamble ?? DEFAULT_CODE_MODE_PREAMBLE;
+	return wrapped !== void 0 && wrapped.length > 0 ? `${wrapped}\n\n${codeMode}` : codeMode;
+}
+//#endregion
+//#region src/typegen/json-schema.ts
+/**
+* Hand-rolled JSON Schema → TypeScript type-text converter (R4).
+*
+* Deliberately a subset: it covers the constructs MCP tool schemas actually
+* use (objects/properties/required, primitive types, enum/const, arrays and
+* tuples, anyOf/oneOf unions, allOf intersections, in-document $ref,
+* additionalProperties, nested objects, property descriptions as doc
+* comments). Anything it does not understand degrades to `unknown` — never
+* an exception — because generated types are model guidance, not a
+* correctness gate (G5: no host-side type checking in the hot path).
+*/
+const MAX_DEPTH = 24;
+/** Render a JSON literal as a TS literal type; non-primitives become `unknown`. */
+function literalType(value) {
+	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+	return "unknown";
+}
+/** Resolve an in-document JSON pointer like `#/$defs/Foo`. */
+function resolvePointer(root, pointer) {
+	if (!pointer.startsWith("#")) return void 0;
+	const path = pointer.slice(1);
+	if (path === "") return root;
+	if (!path.startsWith("/")) return void 0;
+	let current = root;
+	for (const rawSegment of path.slice(1).split("/")) {
+		const segment = rawSegment.replaceAll("~1", "/").replaceAll("~0", "~");
+		if (Array.isArray(current)) {
+			const index = Number(segment);
+			current = Number.isInteger(index) ? current[index] : void 0;
+		} else if (isRecord(current)) current = current[segment];
+		else return;
+		if (current === void 0) return void 0;
+	}
+	return current;
+}
+/** Wrap a type in parentheses when it is a top-level union/intersection. */
+function parenthesize(type) {
+	return /[|&]/.test(type) ? `(${type})` : type;
+}
+const BARE_KEY_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Quote an object key unless it is a valid bare property name. */
+function propertyKey(name) {
+	return BARE_KEY_RE.test(name) ? name : JSON.stringify(name);
+}
+/** Format a description as a doc comment block at the given indent. */
+function docComment(description, indent) {
+	const lines = description.replaceAll("*/", "*\\/").trimEnd().split("\n");
+	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
+	return [
+		`${indent}/**`,
+		...lines.map((line) => `${indent} * ${line}`.trimEnd()),
+		`${indent} */`
+	].join("\n");
+}
+function renderEnum(values) {
+	if (values.length === 0) return "never";
+	return values.map(literalType).join(" | ");
+}
+function renderArray(schema, ctx) {
+	const prefixItems = Array.isArray(schema["prefixItems"]) ? schema["prefixItems"] : Array.isArray(schema["items"]) ? schema["items"] : void 0;
+	if (prefixItems !== void 0) return `[${prefixItems.map((item) => render(item, deeper(ctx))).join(", ")}]`;
+	const items = schema["items"];
+	if (items === void 0) return "unknown[]";
+	const itemType = render(items, deeper(ctx));
+	return /[|&]/.test(itemType) || itemType.includes("\n") ? `Array<${itemType}>` : `${itemType}[]`;
+}
+function renderObject(schema, ctx) {
+	const properties = isRecord(schema["properties"]) ? schema["properties"] : void 0;
+	const additional = schema["additionalProperties"];
+	const additionalType = isRecord(additional) ? render(additional, deeper(ctx)) : additional === false ? void 0 : "unknown";
+	if (properties === void 0 || Object.keys(properties).length === 0) {
+		if (additional === false) return "Record<string, never>";
+		return `Record<string, ${additionalType ?? "unknown"}>`;
+	}
+	const required = new Set(Array.isArray(schema["required"]) ? schema["required"].filter((name) => typeof name === "string") : []);
+	const childIndent = `${ctx.indent}  `;
+	const lines = ["{"];
+	for (const [name, propSchema] of Object.entries(properties)) {
+		const description = isRecord(propSchema) ? propSchema["description"] : void 0;
+		if (typeof description === "string" && description.length > 0) lines.push(docComment(description, childIndent));
+		const optional = required.has(name) ? "" : "?";
+		const type = render(propSchema, {
+			...deeper(ctx),
+			indent: childIndent
+		});
+		lines.push(`${childIndent}${propertyKey(name)}${optional}: ${type};`);
+	}
+	lines.push(`${ctx.indent}}`);
+	const objectType = lines.join("\n");
+	return isRecord(additional) ? `${objectType} & Record<string, ${additionalType ?? "unknown"}>` : objectType;
+}
+function renderByType(type, schema, ctx) {
+	switch (type) {
+		case "string": return "string";
+		case "number":
+		case "integer": return "number";
+		case "boolean": return "boolean";
+		case "null": return "null";
+		case "array": return renderArray(schema, ctx);
+		case "object": return renderObject(schema, ctx);
+		default: return "unknown";
+	}
+}
+function deeper(ctx) {
+	return {
+		...ctx,
+		depth: ctx.depth + 1
+	};
+}
+function render(schema, ctx) {
+	if (schema === true) return "unknown";
+	if (schema === false) return "never";
+	if (!isRecord(schema)) return "unknown";
+	if (ctx.depth > MAX_DEPTH) return "unknown";
+	const ref = schema["$ref"];
+	if (typeof ref === "string") {
+		if (ctx.refStack.includes(ref)) return "unknown";
+		const resolved = resolvePointer(ctx.root, ref);
+		if (resolved === void 0) return "unknown";
+		return render(resolved, {
+			...deeper(ctx),
+			refStack: [...ctx.refStack, ref]
+		});
+	}
+	const enumValues = schema["enum"];
+	if (Array.isArray(enumValues)) return renderEnum(enumValues);
+	if ("const" in schema) return literalType(schema["const"]);
+	const parts = [];
+	const allOf = schema["allOf"];
+	if (Array.isArray(allOf) && allOf.length > 0) parts.push(...allOf.map((member) => render(member, deeper(ctx))));
+	const unionMembers = Array.isArray(schema["anyOf"]) ? schema["anyOf"] : Array.isArray(schema["oneOf"]) ? schema["oneOf"] : void 0;
+	if (unionMembers !== void 0 && unionMembers.length > 0) parts.push(unionMembers.map((member) => render(member, deeper(ctx))).join(" | "));
+	const type = schema["type"];
+	if (Array.isArray(type)) {
+		const members = type.filter((entry) => typeof entry === "string").map((entry) => renderByType(entry, schema, ctx));
+		if (members.length > 0) parts.push(members.join(" | "));
+	} else if (typeof type === "string") parts.push(renderByType(type, schema, ctx));
+	else if (schema["properties"] !== void 0 || schema["additionalProperties"] !== void 0 || schema["required"] !== void 0) parts.push(renderObject(schema, ctx));
+	else if (schema["items"] !== void 0 || schema["prefixItems"] !== void 0) parts.push(renderArray(schema, ctx));
+	if (parts.length === 0) return "unknown";
+	if (parts.length === 1) return parts[0] ?? "unknown";
+	return parts.map(parenthesize).join(" & ");
+}
+/**
+* Convert a JSON Schema into TypeScript type text.
+*
+* @param schema - The schema (also used as the $ref resolution root).
+* @param indent - Indentation prefix of the line the type is emitted on;
+*   nested object literals indent relative to it.
+*/
+function schemaToTsType(schema, indent = "") {
+	return render(schema, {
+		root: schema,
+		depth: 0,
+		refStack: [],
+		indent
+	});
+}
+/**
+* True when the schema requires at least one argument property — used to
+* decide whether the generated tool function's `args` parameter is optional.
+*/
+function schemaRequiresArgs(schema) {
+	return isRecord(schema) && Array.isArray(schema["required"]) && schema["required"].length > 0;
+}
+//#endregion
+//#region src/typegen/generate.ts
+/**
+* Typegen — produces the `@astral-mcp/tools` artifacts from a ServerCatalog
+* (PRD G6, R3, R4, R30):
+*
+* 1. `.d.ts` text describing the namespaced `tools` API surface,
+* 2. the runtime bridge module source mounted at `@astral-mcp/tools` inside
+*    the QuickJS sandbox, and
+* 3. a compact human-readable overview block for `discover_apis`.
+*/
+/**
+* Module specifier authored machines import the tools surface from (R4).
+* The sandbox component mounts {@link GeneratedToolTypes.bridgeSource} here.
+*/
+const TOOLS_MODULE_SPECIFIER = "@astral-mcp/tools";
+/**
+* Name of the global the sandbox host MUST inject before authored code runs.
+*
+* Contract (for the sandbox / machine-host components):
+*
+* ```js
+* globalThis.__projection_toolcall = (name, args) => <host-defined value>
+* ```
+*
+* - `name` is the wrapped server's tool name exactly as catalogued.
+* - `args` is a plain JSON-serializable object (never `undefined`; the
+*   bridge substitutes `{}` for a missing argument).
+* - The bridge performs no I/O itself and returns the hook's value
+*   verbatim. Per R7, authored machines never consume that value as a
+*   promise inside invoked actors — the library-supplied `toolCall` action
+*   is the intended caller, and results come back as TOOL_RESULT /
+*   TOOL_ERROR / TOOL_DENIED events injected by the host.
+* - If the hook is missing, every tool function throws, keeping the bridge
+*   inert outside a properly initialized sandbox (S1).
+*/
+const TOOL_CALL_HOST_GLOBAL = "__projection_toolcall";
+const PASCAL_FALLBACK = "Tool";
+/**
+* Longest catalog-supplied identity rendered into generated artifacts.
+* A hostile wrapped server controls this string (S5).
+*/
+const MAX_IDENTITY_CHARS = 200;
+/**
+* Render an untrusted catalog string for safe inclusion in a `//` line
+* comment of generated source.
+*
+* The bridge source is EVALUATED (mounted at `@astral-mcp/tools` and imported
+* by every machine that calls a tool), so a newline in a wrapped server's
+* name or version would terminate the comment and inject executable
+* statements into the bridge — a hostile server would then run code inside
+* the sandbox on every `execute_machine`, regardless of what the model
+* authored (S1/S5). The same string lands in the `.d.ts` header the model
+* reads as authoritative guidance.
+*
+* `JSON.stringify` escapes newlines and quotes; the control/bidi pass covers
+* the separators JSON leaves raw, and the length cap bounds the artifact.
+*/
+function commentSafe(text) {
+	return JSON.stringify(neutralizeControlChars(capLength(text, MAX_IDENTITY_CHARS)));
+}
+/** Derive a unique PascalCase type-name base from a tool name. */
+function pascalBase(toolName, taken) {
+	const joined = toolName.split(/[^A-Za-z0-9]+/).filter((segment) => segment.length > 0).map((segment) => (segment[0] ?? "").toUpperCase() + segment.slice(1)).join("");
+	let base = /^[A-Za-z]/.test(joined) ? joined : `${PASCAL_FALLBACK}${joined}`;
+	if (base.length === 0) base = PASCAL_FALLBACK;
+	if (taken.has(base)) {
+		let counter = 2;
+		while (taken.has(`${base}${counter}`)) counter += 1;
+		base = `${base}${counter}`;
+	}
+	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.";
+}
+function toolDoc(tool) {
+	const lines = [];
+	if (tool.description !== void 0 && tool.description.length > 0) lines.push(tool.description.trim(), "");
+	lines.push(approvalNote(tool));
+	return lines.join("\n");
+}
+function generateDts(server) {
+	const taken = /* @__PURE__ */ new Set();
+	const names = /* @__PURE__ */ new Map();
+	const sections = [];
+	sections.push([
+		`// Generated by Projection from wrapped server ${commentSafe(server.identity)}. Do not edit.`,
+		"//",
+		"// Import inside an authored machine module as:",
+		`//   import { tools } from '${TOOLS_MODULE_SPECIFIER}';`,
+		"//",
+		"// Tool functions are the transport used by the library-supplied",
+		"// `toolCall` action. Do NOT wrap them in fromPromise / invoked actors",
+		"// (banned pattern R7) — emit toolCall(name, args) and handle the",
+		"// TOOL_RESULT / TOOL_ERROR / TOOL_DENIED events instead."
+	].join("\n"));
+	for (const tool of server.tools) {
+		const base = pascalBase(tool.name, taken);
+		const typeNames = {
+			input: `${base}Input`,
+			output: tool.outputSchema !== void 0 ? `${base}Output` : void 0
+		};
+		names.set(tool.name, typeNames);
+		sections.push(`${docComment(`Input for tool "${tool.name}".`, "")}\nexport type ${typeNames.input} = ${schemaToTsType(tool.inputSchema)};`);
+		if (typeNames.output !== void 0) sections.push(`${docComment(`Output of tool "${tool.name}".`, "")}\nexport type ${typeNames.output} = ${schemaToTsType(tool.outputSchema)};`);
+	}
+	const memberLines = [];
+	for (const tool of server.tools) {
+		const typeNames = names.get(tool.name);
+		memberLines.push(docComment(toolDoc(tool), "  "));
+		const optional = schemaRequiresArgs(tool.inputSchema) ? "" : "?";
+		const returnType = typeNames.output ?? "unknown";
+		memberLines.push(`  ${propertyKey(tool.name)}: (args${optional}: ${typeNames.input}) => Promise<${returnType}>;`);
+	}
+	const surfaceDoc = docComment(`Namespaced tool surface of wrapped server ${commentSafe(server.identity)}.`, "");
+	const body = memberLines.length > 0 ? `export declare const tools: {\n${memberLines.join("\n")}\n};` : "export declare const tools: Record<string, never>;";
+	sections.push(`${surfaceDoc}\n${body}\n\nexport default tools;`);
+	return `${sections.join("\n\n")}\n`;
+}
+function generateBridgeSource(server) {
+	const memberLines = server.tools.map((tool) => `tools[${JSON.stringify(tool.name)}] = bindTool(${JSON.stringify(tool.name)});`);
+	return [
+		`// ${TOOLS_MODULE_SPECIFIER} — runtime bridge generated by Projection`,
+		`// from wrapped server ${commentSafe(server.identity)}. Do not edit.`,
+		"//",
+		"// Sandbox-host contract:",
+		"//   Before authored code runs, the sandbox host MUST inject:",
+		`//     globalThis.${TOOL_CALL_HOST_GLOBAL} = (name, args) => <host-defined>`,
+		"//   `name` is the catalogued tool name, `args` a plain JSON-serializable",
+		"//   object (the bridge substitutes {} when called without arguments).",
+		"//   This module performs no I/O itself; the injected hook is the only",
+		"//   channel out of the sandbox (S1), and its return value is handed back",
+		"//   verbatim to the caller — the library-supplied `toolCall` action.",
+		"",
+		"function bindTool(name) {",
+		"  return function (args) {",
+		`    const hook = globalThis[${JSON.stringify(TOOL_CALL_HOST_GLOBAL)}];`,
+		"    if (typeof hook !== 'function') {",
+		"      throw new Error(",
+		`        'Projection tools bridge: missing host hook globalThis.${TOOL_CALL_HOST_GLOBAL}. ' +`,
+		"          'The sandbox host must inject it before authored code runs.',",
+		"      );",
+		"    }",
+		"    return hook(name, args === undefined ? {} : args);",
+		"  };",
+		"}",
+		"",
+		"const tools = Object.create(null);",
+		...memberLines,
+		"Object.freeze(tools);",
+		"",
+		"export { tools };",
+		"export default tools;",
+		""
+	].join("\n");
+}
+function overviewFlags(tool) {
+	if (tool.annotations?.readOnlyHint === true) return "[read-only]";
+	if (tool.annotations?.destructiveHint === true) return "[approval, destructive]";
+	return "[approval]";
+}
+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;
+}
+function generateOverview(server) {
+	const lines = [`Tools (server: ${server.identity}):`];
+	if (server.tools.length === 0) lines.push("  (none)");
+	for (const tool of server.tools) lines.push(`- ${tool.name} ${overviewFlags(tool)} — ${firstLine(tool.description)}`);
+	return `${lines.join("\n")}\n`;
+}
+function resolveSingleServer(catalog) {
+	if ("servers" in catalog) {
+		if (catalog.servers.size !== 1) throw new ProjectionError("protocol", `Typegen requires exactly one wrapped server; catalog has ${catalog.servers.size}.`, { hint: "v1 wraps a single server (multi-server namespacing is a stretch goal, PRD 12.2). Pass a single-entry catalog or a ServerCatalog directly." });
+		const server = catalog.servers.values().next().value;
+		if (server === void 0) throw new ProjectionError("protocol", "Tool catalog contains no servers.", { hint: "Build the catalog with createIntrospector before generating types." });
+		return server;
+	}
+	return catalog;
+}
+/**
+* Generate the `@astral-mcp/tools` artifacts for a wrapped server.
+*
+* Accepts either the full aliased {@link ToolCatalog} (which must contain
+* exactly one server in v1, per R30's single-instance instantiation) or a
+* {@link ServerCatalog} directly.
+*/
+function generateToolTypes(catalog) {
+	const server = dedupeToolNames(resolveSingleServer(catalog));
+	return {
+		dts: generateDts(server),
+		bridgeSource: generateBridgeSource(server),
+		overview: generateOverview(server)
+	};
+}
+/**
+* Drop tools whose name repeats an earlier one, first occurrence wins.
+*
+* A wrapped server may return the same tool name twice (S5: the catalog is
+* untrusted). Emitting it twice would produce a duplicate member in the
+* `.d.ts` object type — invalid TypeScript — and a silently last-wins
+* shadowed key in the bridge, so the types and the runtime would disagree
+* about which schema the tool takes. Collapsing to the first occurrence
+* matches what `callTool` reaches on the wrapped server.
+*/
+function dedupeToolNames(server) {
+	const seen = /* @__PURE__ */ new Set();
+	const tools = server.tools.filter((tool) => {
+		if (seen.has(tool.name)) return false;
+		seen.add(tool.name);
+		return true;
+	});
+	return tools.length === server.tools.length ? server : {
+		...server,
+		tools
+	};
+}
+//#endregion
+//#region src/wrap.ts
+const EXECUTE_MACHINE_DESCRIPTION = `Run an LLM-authored XState v5 state machine that orchestrates this server's tools.
+
+Author a module that default-exports a machine built with XState v5 setup(...).createMachine(...), and request tools with the toolCall action from '@astral-mcp/tools'. Read-only tools run immediately; every other tool pauses the machine and asks the user to approve that exact call before it runs, so handle TOOL_RESULT, TOOL_ERROR and TOOL_DENIED. Machine context must stay JSON-serializable, and invoke/fromPromise is rejected.
+
+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.`;
+/**
+* Wrap an MCP server (an in-process instance or a connected client) into a
+* code-mode facade.
+*/
+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 } = generateToolTypes(catalog);
+	return new Facade({
+		introspector,
+		catalog,
+		dts,
+		bridgeSource,
+		overview,
+		resources: buildResources(catalog, dts),
+		instructions: buildInstructions(catalog, options.codeModePreamble),
+		options
+	});
+}
+var Facade = class {
+	catalog;
+	instructions;
+	dts;
+	resources;
+	serverFactory;
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+		this.catalog = deps.catalog;
+		this.instructions = deps.instructions;
+		this.dts = deps.dts;
+		this.resources = deps.resources;
+		this.serverFactory = (ctx) => this.createServer(ctx);
+	}
+	executeMachine(args, era) {
+		const { options } = this.deps;
+		return executeMachine(args, {
+			catalog: this.deps.catalog,
+			bridgeSource: this.deps.bridgeSource,
+			executor: this.deps.introspector,
+			blob: options.blob,
+			...options.caps !== void 0 ? { caps: options.caps } : {},
+			...options.policy !== void 0 ? { policy: options.policy } : {},
+			...options.redact !== void 0 ? { redact: options.redact } : {},
+			...era !== void 0 ? { protocolEra: era } : {}
+		});
+	}
+	discoverApis() {
+		return discoverApis(this.deps.catalog, this.deps.overview);
+	}
+	/**
+	* R29: `Server` accepts `instructions` only in its constructor, so the
+	* code-mode preamble can be delivered from here and nowhere else. This is
+	* also where the era arrives, which is why the factory shape is the
+	* library's recommended entry point.
+	*/
+	createServer(ctx) {
+		const server = new McpServer(this.deps.options.serverInfo ?? {
+			name: `projection-${this.deps.catalog.alias}`,
+			version: "0.1.0"
+		}, { instructions: this.instructions });
+		this.registerOn(server, ctx);
+		return server;
+	}
+	registerOn(server, options) {
+		const era = options?.era;
+		server.registerTool("execute_machine", {
+			title: "Execute a state machine",
+			description: EXECUTE_MACHINE_DESCRIPTION,
+			inputSchema: EXECUTE_MACHINE_INPUT_SCHEMA
+		}, async (args, ctx) => await this.executeMachine({
+			code: args.code,
+			...args.lang !== void 0 ? { lang: args.lang } : {},
+			...args.input !== void 0 ? { input: args.input } : {},
+			...maybeRequestState(ctx.mcpReq.requestState()),
+			...ctx.mcpReq.inputResponses !== void 0 ? { inputResponses: ctx.mcpReq.inputResponses } : {}
+		}, era));
+		server.registerTool("discover_apis", {
+			title: "Discover the tool API",
+			description: DISCOVER_APIS_DESCRIPTION,
+			inputSchema: z.object({})
+		}, () => this.discoverApis());
+		for (const resource of this.resources) server.registerResource(resource.name, resource.uri, {
+			description: resource.description,
+			mimeType: resource.mimeType
+		}, () => ({ contents: [{
+			uri: resource.uri,
+			mimeType: resource.mimeType,
+			text: resource.text
+		}] }));
+	}
+	close() {
+		return this.deps.introspector.close();
+	}
+};
+/**
+* `ctx.mcpReq.requestState()` is typed as a caller-asserted cast, so it is
+* read as `unknown` and narrowed here: without a configured
+* `ServerOptions.requestState.verify` hook the SDK hands back the raw wire
+* string, and anything else means someone wired a decoding hook Projection
+* does not own.
+*/
+function maybeRequestState(state) {
+	return typeof state === "string" ? { requestState: state } : {};
+}
+/**
+* `execute_machine` arguments (R2).
+*
+* The MRTR retry fields are deliberately absent: `requestState` and
+* `inputResponses` are siblings of `arguments` in a `tools/call`, not
+* members of it, and the SDK surfaces them on the handler context.
+*/
+const EXECUTE_MACHINE_INPUT_SCHEMA = z.object({
+	code: z.string().describe("The machine module source: a default-exported XState v5 machine."),
+	lang: z.enum(["ts", "js"]).optional().describe("Language of `code`. Defaults to TypeScript-compatible parsing."),
+	input: z.unknown().optional().describe("Passed to the machine as its `input`.")
+});
+//#endregion
+export { APPROVAL_SCHEMA, AUTHORING_CONTRACT, BLOB_SCHEMA_VERSION, DEFAULT_CAPS, DEFAULT_CODE_MODE_PREAMBLE, DEFAULT_MAX_BLOB_BYTES, DEFAULT_SERVER_ALIAS, DEFAULT_TTL_MS, ENVELOPE_PREFIX, EXAMPLE_DENIAL_FALLBACK, EXAMPLE_HAPPY_PATH, Introspector, LIB_VERSION, MAX_CAPS, MRTR_PROTOCOL_REVISION, POLICY_DENIED_REASON, ProjectionError, RESOURCE_URIS, TOOLS_MODULE_SPECIFIER, TOOL_CALL_HOST_GLOBAL, XSTATE_VERSION, acceptedContent, buildBlobPayload, buildElicitationCopy, buildInstructions, buildResources, capLength, clampCaps, createIntrospector, createSandboxSession, decidePolicy, discoverApis, executeMachine, findTool, generateToolTypes, hashCode, inputRequired, inputResponse, isInputRequiredResult, isRecord, neutralizeControlChars, openBlob, policyDeniedReason, resolveCallPolicy, runSegment, schemaRequiresArgs, schemaToTsType, sealBlob, supportsMrtr, toStructuredError, wrapMcpServer };
+
+//# sourceMappingURL=index.mjs.map