@astral-mcp/projection 0.5.1 → 0.7.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { CallToolResult, ContentBlock, ElicitRequestFormParams, HandlerResultTypeMap, Implementation, InputRequest, InputRequests, InputRequiredResult, InputResponse, InputResponseView, InputResponses, InputResponses as InputResponses$1, McpServer, McpServerFactory, ProtocolEra, ProtocolEra as ProtocolEra$1, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from "@modelcontextprotocol/server";
 import "@sebastianwessel/quickjs";
+import { CallToolResult, ContentBlock, ElicitRequestFormParams, HandlerResultTypeMap, Implementation, InputRequest, InputRequests, InputRequiredResult, InputResponse, InputResponseView, InputResponses, InputResponses as InputResponses$1, McpServer, McpServerFactory, ProtocolEra, ProtocolEra as ProtocolEra$1, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from "@modelcontextprotocol/server";
 import { Client } from "@modelcontextprotocol/client";
 //#region src/types.d.ts
 /**
@@ -46,11 +46,19 @@ interface ServerCatalog {
  * 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.
+ * {@link dedupeTools} (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.
  */
 declare function findTool(catalog: ServerCatalog, name: string): ToolCatalogEntry | undefined;
+/**
+ * Drop tools whose name repeats an earlier one; the first occurrence wins.
+ *
+ * The single dedupe rule for every consumer of the catalog (typegen, the
+ * catalog projection), so they all agree with {@link findTool} on which
+ * entry a name denotes (S5).
+ */
+declare function dedupeTools(tools: ToolCatalogEntry[]): ToolCatalogEntry[];
 /** Narrow to a non-null, non-array object. */
 declare function isRecord(value: unknown): value is Record<string, unknown>;
 /** Executes a tool call against the wrapped server. Implemented by the introspector. */
@@ -98,7 +106,9 @@ type HostEvent = {
   callId: string;
   reason?: string;
 };
-type ErrorPhase = 'transpile' | 'validate' | 'runtime' | 'cap_exceeded' | 'blob_verification' | 'protocol' | 'terminal';
+type ErrorPhase = 'transpile' | 'validate' | 'runtime' | 'cap_exceeded' | 'blob_verification' | 'protocol' |
+/** An `isError` result or transport failure from the wrapped tool, surfaced by `call_tool` (R25). */
+'upstream' | 'terminal';
 interface Diagnostic {
   message: string;
   /** Optional source location within the submitted code. */
@@ -149,14 +159,22 @@ declare const MAX_CAPS: ResourceCaps;
 /** Clamp requested caps into [MIN_CAPS, MAX_CAPS] (R12). */
 declare function clampCaps(requested: Partial<ResourceCaps>): ResourceCaps;
 declare const BLOB_SCHEMA_VERSION = 1;
+/** Which tool minted a blob (R36): a blob opened by the other tool is rejected. */
+type BlobKind = 'machine' | 'call';
 interface BlobPayload {
   /** Blob schema version; unknown versions are rejected. */
   v: number;
+  /** Minting tool (R36). */
+  kind: BlobKind;
   /** Library version that produced the snapshot. */
   libv: string;
   /** Exact XState version that produced the snapshot. */
   xstatev: string;
-  /** SHA-256 (hex) of the original `code` argument. */
+  /**
+   * Binding hash (S4): SHA-256 (hex) of the original `code` for `machine`
+   * blobs, of the canonical `{ kind: "call", name, args }` request for
+   * `call` blobs (R36).
+   */
   codeHash: string;
   /** Server identity the blob was minted against (R30). */
   serverIdentity: string;
@@ -186,11 +204,38 @@ interface BlobSealerConfig {
   key: Uint8Array;
   /** Previous keys accepted for decryption during rotation (R22). */
   previousKeys?: Uint8Array[];
-  /** Blob TTL in ms. Default 15 minutes. */
+  /** Blob TTL in ms for `machine` blobs. Default 15 minutes. */
   ttlMs?: number;
+  /**
+   * Blob TTL in ms for `call` blobs (R38). Default 5 minutes: an approved
+   * `call` blob has no forward step, so it is a standing capability until
+   * it expires (D4, D9).
+   */
+  callTtlMs?: number;
   /** Sealed+compressed size ceiling in bytes. Default 128 KB (R23). */
   maxBlobBytes?: number;
 }
+/**
+ * Optional shared replay cache (R38). When configured, the adapter consults
+ * it after blob verification and before executing any gated call, for both
+ * blob kinds. No default ships: an in-memory one would silently break
+ * horizontal scaling (G4), so the integrator supplies a shared store.
+ */
+interface ReplayCache {
+  /**
+   * Record `nonce` until `exp` (Unix ms) and resolve `true` when it had
+   * already been recorded — i.e. this approval is being replayed.
+   *
+   * Contract: this MUST be an atomic test-and-set across every instance that
+   * can serve a retry (a SETNX-style primitive, not a read followed by a
+   * write), or two concurrent replays of one approval both execute. The
+   * nonce is recorded on FIRST SIGHT, before the verdict is read and
+   * regardless of what follows — a decline, a policy denial, an upstream
+   * failure — so a blob is single-use whatever happens to the call it
+   * carried. A retry that fails verification never reaches this method.
+   */
+  seen(nonce: string, exp: number): Promise<boolean>;
+}
 /** Verdict delivered on retry for a pending gated call. */
 type ApprovalVerdict = {
   kind: 'approved';
@@ -242,21 +287,34 @@ interface ProjectionConfig {
   blob: BlobSealerConfig;
   /** Redaction hook for elicitation copy (R16). */
   redact?: RedactionHook;
-  /** Override the code-mode preamble appended to instructions (R29). */
+  /**
+   * Replaces the whole R29 preamble appended to `instructions`, whichever
+   * projections are on (code mode, catalog, or the routing copy for both).
+   */
   codeModePreamble?: string;
 }
 //#endregion
 //#region src/blob/sealer.d.ts
 /** Envelope format version prefix. Bump (proj2, …) on any wire-format change. */
 declare const ENVELOPE_PREFIX = "proj1";
-/** Default blob TTL: 15 minutes (R20). */
+/** Default blob TTL for `machine` blobs: 15 minutes (R20). */
 declare const DEFAULT_TTL_MS: number;
+/**
+ * Default TTL for `call` blobs: 5 minutes (R38). An approved `call` blob has
+ * no forward step, so it is a standing capability until it expires (D4, D9).
+ */
+declare const DEFAULT_CALL_TTL_MS: number;
 /** Default sealed-blob size ceiling: 128 KB (R23). */
 declare const DEFAULT_MAX_BLOB_BYTES: number;
 /** SHA-256 hex digest of a code argument (S4 binding — R20 `codeHash`). */
 declare function hashCode(code: string): string;
 interface BuildBlobPayloadInput {
-  /** The original `code` argument; hashed into `codeHash` (S4). */
+  /** Minting tool (R36). Default `machine`. */
+  kind?: BlobKind | undefined;
+  /**
+   * The text the blob is bound to (S4): the original `code` argument for a
+   * `machine` blob, the canonical request for a `call` blob (R36).
+   */
   code: string;
   /** Identity of the wrapped server this blob is minted against (R30). */
   serverIdentity: string;
@@ -288,7 +346,12 @@ declare function buildBlobPayload(input: BuildBlobPayloadInput): BlobPayload;
  */
 declare function sealBlob(payload: BlobPayload, config: BlobSealerConfig): string;
 interface OpenBlobOptions {
-  /** The `code` argument re-sent with the retried call (S4). */
+  /** The tool opening the blob (R36). Default `machine`. */
+  expectedKind?: BlobKind | undefined;
+  /**
+   * The text re-sent with the retry (S4): the `code` argument for
+   * `execute_machine`, the canonical request for `call_tool`.
+   */
   code: string;
   /** Identity of the wrapped server handling the retry (R30). */
   serverIdentity: string;
@@ -326,7 +389,7 @@ declare function openBlob(blob: string, options: OpenBlobOptions): BlobPayload;
  * CI instead of silently minting blobs with a stale version stamp.
  */
 /** `@astral-mcp/projection` package version (must match packages/projection/package.json). */
-declare const LIB_VERSION = "0.5.1";
+declare const LIB_VERSION = "0.7.0";
 /** Pinned XState version (must match the exact pin in package.json — D2). */
 declare const XSTATE_VERSION = "5.32.5";
 //#endregion
@@ -389,6 +452,17 @@ declare const MRTR_PROTOCOL_REVISION = "2026-07-28";
 declare function supportsMrtr(era: ProtocolEra$1 | undefined): boolean;
 //#endregion
 //#region src/mrtr/adapter.d.ts
+/**
+ * `execute_machine` arguments plus the MRTR retry envelope.
+ *
+ * **Security (S2):** `requestState` and `inputResponses` are the retry
+ * envelope — siblings of `arguments` in a `tools/call` that the SDK lifts off
+ * the request params onto the handler context. They are NOT tool arguments.
+ * A direct caller of `executeMachine` MUST populate them only from the
+ * transport's retry fields, never from model-authored tool arguments: a
+ * model that has seen a `requestState` could otherwise echo it back with a
+ * fabricated `accept` and approve its own gated call.
+ */
 interface ExecuteMachineArgs extends RetryEnvelope {
   /** The authored module source (R2). */
   code: string;
@@ -396,9 +470,14 @@ interface ExecuteMachineArgs extends RetryEnvelope {
   /** Passed to the machine as its input. */
   input?: unknown;
 }
-interface ExecuteMachineDeps {
+/**
+ * What every gated entry point needs: the catalog and executor of the wrapped
+ * server, the blob sealer, and the per-facade policy, redaction, caps,
+ * protocol-era and replay settings. `execute_machine` adds the sandbox
+ * bridge; `call_tool` needs nothing more (R35, R38).
+ */
+interface ApprovalGateDeps {
   catalog: ServerCatalog;
-  bridgeSource: string;
   executor: ToolExecutor;
   blob: BlobSealerConfig;
   caps?: Partial<ResourceCaps>;
@@ -423,6 +502,20 @@ interface ExecuteMachineDeps {
    * session affinity over legacy HTTP). Default false: fail fast per R28.
    */
   legacyElicitation?: boolean;
+  /**
+   * Whether the connected client declared the MCP `elicitation` capability.
+   * Only consulted on the legacy path with `legacyElicitation` on: the SDK
+   * shim cannot deliver an approval to a client without it, and its own
+   * failure surfaces as an unstructured error. `undefined` (the caller does
+   * not know) leaves the shim to decide.
+   */
+  clientCanElicit?: boolean;
+  /** Optional shared replay cache (R38); consulted after verification, before execution. */
+  replayCache?: ReplayCache;
+}
+interface ExecuteMachineDeps extends ApprovalGateDeps {
+  /** The `@astral-mcp/tools` bridge module source the sandbox loads (R2). */
+  bridgeSource: string;
 }
 /**
  * Run `execute_machine` for one `tools/call`, whether it is a first attempt
@@ -432,6 +525,319 @@ interface ExecuteMachineDeps {
  * so any instance can serve any retry. Nothing is held between calls.
  */
 declare function executeMachine(args: ExecuteMachineArgs, deps: ExecuteMachineDeps): Promise<ToolCallResult>;
+/** Every failure is a normal result with `isError: true` and a structured body (R25). */
+declare function errorResult(error: StructuredError): CallToolResult;
+//#endregion
+//#region src/catalog/call.d.ts
+/**
+ * `call_tool` arguments plus the MRTR retry envelope.
+ *
+ * **Security (S2):** `requestState` and `inputResponses` are the retry
+ * envelope — siblings of `arguments` in a `tools/call` that the SDK lifts off
+ * the request params onto the handler context. They are NOT tool arguments.
+ * A direct caller of `callTool` MUST populate them only from the transport's
+ * retry fields, never from model-authored tool arguments: a model that has
+ * seen a `requestState` could otherwise echo it back with a fabricated
+ * `accept` and approve its own write.
+ */
+interface CallToolArgs extends RetryEnvelope {
+  /** Tool name as listed by `search_tools`. */
+  name: string;
+  /** Arguments for the tool; absent means `{}`. */
+  args?: unknown;
+}
+/** `call_tool` needs exactly the dependencies every gated tool shares (R35, R38). */
+type CallToolDeps = ApprovalGateDeps;
+/** `structuredContent` of a completed `call_tool` (R35.5). */
+type CallToolOutcome = {
+  status: 'ok';
+  tool: string;
+  /**
+   * The wrapped tool's result — or, when its JSON exceeded
+   * `caps.maxResultBytes`, a string preview of that JSON. The call ran
+   * either way; see `truncated`.
+   */
+  output: unknown;
+  /** Present and `true` when `output` is a preview, not the full result. */
+  truncated?: true;
+  /** Byte length of the full result's JSON, when truncated. */
+  outputBytes?: number;
+} | {
+  status: 'declined';
+  tool: string;
+  reason?: string;
+} | {
+  status: 'denied_by_policy';
+  tool: string;
+  reason: string;
+};
+/** The single inputRequest / pending key of a `call` blob (R36). */
+declare const CALL_KEY = "call";
+/** Run `call_tool` for one `tools/call`, first attempt or MRTR retry. */
+declare function callTool(args: CallToolArgs, deps: CallToolDeps): Promise<ToolCallResult>;
+//#endregion
+//#region src/catalog/canonical.d.ts
+/**
+ * Canonical JSON for the `call_tool` binding hash (PRD R36).
+ *
+ * A `call` blob is bound to the request that produced it by hashing the
+ * canonical text of `{ kind: "call", name, args }`: object keys sorted by
+ * UTF-16 code unit order (JavaScript's default sort), array order kept,
+ * no whitespace. Both sides canonicalize the *parsed* request, so `1` and
+ * `1.0`, `-0` and `0`, escaped and literal characters, and duplicate keys
+ * (last wins at parse time) all canonicalize identically. No Unicode
+ * normalization is applied — NFC and NFD differ, deliberately failing
+ * closed. Values JSON cannot represent (`undefined`, functions, symbols,
+ * bigint, non-finite numbers) throw a `validate` error rather than being
+ * dropped: the facade is callable outside the SDK (R27), so they can occur.
+ * Non-plain objects (`Date`, `Map`, class instances) canonicalize by their
+ * own enumerable keys, i.e. typically to `{}` — JSON over the wire never
+ * produces them, so this too is reachable only by a direct caller.
+ *
+ * The hash is a coherence check, not the approval binding — S2 is carried
+ * by the blob's `pending` entry alone (R36, D9).
+ */
+/** Canonical JSON text of a plain JSON value. Throws `validate` on non-JSON. */
+declare function canonicalJson(value: unknown): string;
+/** The text a `call` blob is bound to (R36): `{ kind: "call", name, args }`. */
+declare function canonicalRequest(name: string, args: Record<string, unknown>): string;
+//#endregion
+//#region src/catalog/validate-args.d.ts
+/**
+ * Structural argument validation for `call_tool` (PRD R35.1).
+ *
+ * Deliberately shallow: required properties present, top-level property
+ * types match, enum membership for top-level primitives, and no unknown
+ * top-level properties when the schema forbids them. It exists so a human
+ * is never asked to approve a call the wrapped server would reject on
+ * shape, and so the model gets a `validate` hint naming the property. Full
+ * JSON Schema validation would run twice — the wrapped server is the
+ * authority — for nothing but a nicer error message (D9).
+ *
+ * Own-property semantics throughout: `__proto__` or `constructor` as an
+ * argument name is ordinary data (S5/S6).
+ */
+/** Throws a `validate`-phase {@link ProjectionError} naming the offending property. */
+declare function validateArgsShape(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): void;
+//#endregion
+//#region src/typegen/generate.d.ts
+/**
+ * Module specifier authored machines import the tools surface from (R4).
+ * The sandbox component mounts {@link GeneratedToolTypes.bridgeSource} here.
+ */
+declare 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).
+ */
+declare const TOOL_CALL_HOST_GLOBAL = "__projection_toolcall";
+/** Output of {@link generateToolTypes}. */
+interface GeneratedToolTypes {
+  /** `.d.ts` text for the `@astral-mcp/tools` surface (serve via discover_apis, R3). */
+  dts: string;
+  /** ESM source of the runtime bridge to mount at `@astral-mcp/tools` in the sandbox. */
+  bridgeSource: string;
+  /** Compact per-tool overview block for inline embedding by discover_apis (R3). */
+  overview: string;
+  /**
+   * Per-tool slice of `dts`, keyed by tool name (R34): the alias
+   * declarations and the `tools.<name>` member signature exactly as they
+   * appear in the full file, so `describe_tool` output type-checks against
+   * the `projection://types/tools.d.ts` resource.
+   */
+  toolTypes: Map<string, ToolTypeText>;
+}
+/** The generated types for one tool, as served by `describe_tool` (R34). */
+interface ToolTypeText {
+  /** `<Pascal>Input` alias name, unique within the `.d.ts`. */
+  inputAlias: string;
+  /** `<Pascal>Output` alias name, when the tool declares an `outputSchema`. */
+  outputAlias?: string;
+  /**
+   * The alias declarations verbatim from the `.d.ts`, then the member
+   * signature verbatim modulo indentation: the `tools` member is re-indented
+   * to column 0 under a `// Member of the \`tools\` surface:` line.
+   */
+  dts: string;
+}
+/**
+ * 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.
+ */
+declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog): GeneratedToolTypes;
+//#endregion
+//#region src/typegen/json-schema.d.ts
+/**
+ * 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.
+ */
+declare function schemaToTsType(schema: unknown, indent?: string): string;
+/**
+ * True when the schema requires at least one argument property — used to
+ * decide whether the generated tool function's `args` parameter is optional.
+ */
+declare function schemaRequiresArgs(schema: unknown): boolean;
+//#endregion
+//#region src/catalog/search.d.ts
+interface SearchToolsArgs {
+  /** Plain substring filter over name and description (case-insensitive). */
+  query?: string;
+  /** Opaque cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+}
+interface SearchToolsOptions {
+  /** Per-tool policy overrides (R14); decides the rendered posture. */
+  policy?: PolicyOverrides;
+  /** Tools per page. Default {@link DEFAULT_SEARCH_PAGE_SIZE}, clamped to [1, 200]. */
+  pageSize?: number;
+}
+/** Page size — a transport bound, independent of the R37 inline threshold. */
+declare const DEFAULT_SEARCH_PAGE_SIZE = 50;
+/** `query` is capped (R33): it is matched as a plain substring, never a regex. */
+declare const MAX_QUERY_CHARS = 200;
+/** The three normative posture strings (R33) — models match on these. */
+type ToolPosture = 'runs immediately' | 'asks for approval' | 'blocked by policy';
+/** One entry of a `search_tools` page (R33). */
+interface ToolSummary {
+  name: string;
+  purpose: string;
+  posture: ToolPosture;
+  destructive: boolean;
+}
+interface SearchToolsPage {
+  tools: ToolSummary[];
+  /** Matching tools across all pages. */
+  total: number;
+  nextCursor?: string;
+}
+/** Map a policy decision to its plain-words posture (R33). */
+declare function postureOf(decision: PolicyDecision): ToolPosture;
+/** Summarize one catalog entry (R33). */
+declare function summarizeTool(entry: ToolCatalogEntry, policy?: PolicyOverrides): ToolSummary;
+/**
+ * Run `search_tools`. Throws a `validate`-phase {@link ProjectionError} for a
+ * malformed cursor, one issued for a different query, or one pointing past
+ * the end of the results (R33).
+ */
+declare function searchTools(catalog: ServerCatalog, args: SearchToolsArgs, options?: SearchToolsOptions): CallToolResult;
+//#endregion
+//#region src/catalog/describe.d.ts
+interface DescribeToolArgs {
+  name: string;
+}
+interface DescribeToolOptions {
+  /** Per-tool policy overrides (R14); decides the rendered posture. */
+  policy?: PolicyOverrides;
+  /** Per-tool generated types from typegen (R34). */
+  toolTypes?: ReadonlyMap<string, ToolTypeText>;
+}
+/** `structuredContent` of a `describe_tool` result (R34). */
+interface ToolDescription {
+  name: string;
+  /** Neutralized, capped description; `undefined` when the server gave none. */
+  description?: string;
+  posture: ToolPosture;
+  destructive: boolean;
+  /** The server's annotations, as untrusted hints (S5); `title` neutralized. */
+  annotations: ToolAnnotations;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  /** True when either schema had to be reduced to fit the R34 cap. */
+  schemaTruncated: boolean;
+  /** Generated TypeScript for this tool, as in `projection://types/tools.d.ts`. */
+  types?: string;
+}
+/**
+ * Run `describe_tool`. Throws a `validate`-phase {@link ProjectionError}
+ * when the wrapped server declares no such tool (R34).
+ */
+declare function describeTool(catalog: ServerCatalog, args: DescribeToolArgs, options?: DescribeToolOptions): CallToolResult;
+//#endregion
+//#region src/catalog/schema-safety.d.ts
+/**
+ * JSON Schema sanitizer for `describe_tool` (PRD R34, S5).
+ *
+ * The wrapped server's schemas are the injection surface of the catalog
+ * projection: beyond `description`, a server controls free text in
+ * `title`, nested descriptions, `examples`, `default`, `$comment`, `x-*`
+ * vendor keys, `enum` members and `pattern`. Before a schema reaches the
+ * model it passes through:
+ *
+ * 1. a key allowlist — only the keywords a model needs to build arguments
+ *    survive; everything else (examples, defaults, comments, vendor keys)
+ *    is dropped;
+ * 2. string neutralization — every string VALUE has control and bidi
+ *    characters replaced and is length-capped. Property NAMES and
+ *    `required` entries are kept verbatim: they are the keys the model must
+ *    send back, and `JSON.stringify` already renders them inert. A name
+ *    longer than the string cap is dropped outright (with its `required`
+ *    entry) — unusable as a key, and otherwise a way around the size cap;
+ * 3. a size cap — the rendered schema is bounded per tool, degrading in
+ *    deterministic stages (drop prose → prune deep subtrees → keep the
+ *    top-level shape → the marker alone) and flagging truncation explicitly
+ *    so the model knows the wrapped server enforces more than it can see.
+ *
+ * Pure and total: never throws, never returns anything but plain JSON.
+ */
+/** Keywords that survive sanitization (R34). */
+declare const SCHEMA_KEY_ALLOWLIST: ReadonlySet<string>;
+/** Rendered-schema cap per tool, in characters of its JSON text (R34). */
+declare const MAX_SCHEMA_CHARS: number;
+interface SanitizedSchema {
+  /** The sanitized schema, always a plain JSON object. */
+  schema: Record<string, unknown>;
+  /** True when anything the server declared was cut: by the size cap, the depth cap or the name cap (R34). */
+  truncated: boolean;
+}
+/**
+ * Sanitize a tool schema for the model (R34).
+ *
+ * Non-object input (a server declaring `inputSchema: true`, or garbage)
+ * sanitizes to `{}`.
+ */
+declare function sanitizeSchema(schema: unknown, maxChars?: number): SanitizedSchema;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error carrying the structured `isError` body every failure returns (R25).
+ */
+declare class ProjectionError extends Error {
+  readonly phase: ErrorPhase;
+  readonly diagnostics: Diagnostic[];
+  readonly hint: string;
+  logs: LogEntry[];
+  constructor(phase: ErrorPhase, message: string, options?: {
+    diagnostics?: Diagnostic[];
+    hint?: string;
+    logs?: LogEntry[];
+    cause?: unknown;
+  });
+  toStructured(): StructuredError;
+}
+/** Convert any thrown value into a StructuredError, defaulting to `runtime` phase. */
+declare function toStructuredError(err: unknown, logs?: LogEntry[]): StructuredError;
 //#endregion
 //#region src/mrtr/discover.d.ts
 /** Stable URIs the server serves via `resources/read` (R3). */
@@ -451,21 +857,50 @@ interface ProjectionResource {
   /** Resource-level metadata (e.g. the MCP Apps `ui` object). */
   _meta?: Record<string, unknown>;
 }
-declare const EXAMPLE_HAPPY_PATH = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Read a file and return its contents. Read-only calls run immediately,\n// so this whole machine completes in one round trip.\nexport default setup({}).createMachine({\n  id: 'readNotes',\n  context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),\n  initial: 'reading',\n  states: {\n    reading: {\n      entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n      on: {\n        TOOL_RESULT: {\n          target: 'done',\n          actions: assign({ text: ({ event }) => event.result }),\n        },\n        TOOL_ERROR: {\n          target: 'failed',\n          actions: assign({ text: ({ event }) => `error: ${event.error.message}` }),\n        },\n      },\n    },\n    done: { type: 'final' },\n    failed: { type: 'final' },\n  },\n  output: ({ context }) => ({ text: context.text }),\n});\n";
-declare const EXAMPLE_DENIAL_FALLBACK = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Write a file, but keep going if the user declines. TOOL_DENIED is an\n// ordinary transition — denial is never an automatic abort.\nexport default setup({}).createMachine({\n  id: 'writeWithFallback',\n  context: { status: 'pending', note: null },\n  initial: 'writing',\n  states: {\n    writing: {\n      entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),\n      on: {\n        TOOL_RESULT: {\n          target: 'summarizing',\n          actions: assign({ status: 'written' }),\n        },\n        TOOL_DENIED: {\n          // The user said no: record it and carry on with the read-only\n          // part of the work instead of failing the whole workflow.\n          target: 'summarizing',\n          actions: assign({\n            status: 'skipped',\n            note: ({ event }) => event.reason ?? 'declined by user',\n          }),\n        },\n        TOOL_ERROR: {\n          target: 'summarizing',\n          actions: assign({ status: 'failed' }),\n        },\n      },\n    },\n    summarizing: {\n      entry: toolCall('list_dir', () => ({ path: '/' })),\n      on: {\n        TOOL_RESULT: { target: 'done' },\n        TOOL_ERROR: { target: 'done' },\n      },\n    },\n    done: { type: 'final' },\n  },\n  output: ({ context }) => ({ status: context.status, note: context.note }),\n});\n";
+declare const EXAMPLE_HAPPY_PATH = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Read a file and return the tool's result. Read-only calls run immediately,\n// so this whole machine completes in one round trip.\n//\n// Run it with input: { path } — paths are server-specific, so take them\n// from the input or from an earlier read-only listing call, never guess.\nexport default setup({}).createMachine({\n  id: 'readOne',\n  context: ({ input }) => ({ path: input.path, result: null, error: null }),\n  initial: 'reading',\n  states: {\n    reading: {\n      entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n      on: {\n        TOOL_RESULT: {\n          target: 'done',\n          // event.result is the tool's structuredContent when the server\n          // returns one (see its Output type in tools.d.ts); otherwise the\n          // text of its single text block, null when empty, or the raw\n          // content array. isError results arrive as TOOL_ERROR instead.\n          actions: assign({ result: ({ event }) => event.result }),\n        },\n        TOOL_ERROR: {\n          target: 'failed',\n          actions: assign({ error: ({ event }) => event.error.message }),\n        },\n      },\n    },\n    done: { type: 'final' },\n    failed: { type: 'final' },\n  },\n  output: ({ context }) => ({ result: context.result, error: context.error }),\n});\n";
+declare const EXAMPLE_DENIAL_FALLBACK = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Write a file, but keep going if the user declines. TOOL_DENIED is an\n// ordinary transition — denial is never an automatic abort.\n//\n// Run it with input: { path, dir } — both are server-specific.\nexport default setup({}).createMachine({\n  id: 'writeWithFallback',\n  context: ({ input }) => ({ path: input.path, dir: input.dir, status: 'pending', note: null }),\n  initial: 'writing',\n  states: {\n    writing: {\n      entry: toolCall('write_file', ({ context }) => ({ path: context.path, content: 'hello' })),\n      on: {\n        TOOL_RESULT: {\n          target: 'summarizing',\n          actions: assign({ status: 'written' }),\n        },\n        TOOL_DENIED: {\n          // The user said no: record it and carry on with the read-only\n          // part of the work instead of failing the whole workflow.\n          target: 'summarizing',\n          actions: assign({\n            status: 'skipped',\n            note: ({ event }) => event.reason ?? 'declined by user',\n          }),\n        },\n        TOOL_ERROR: {\n          target: 'summarizing',\n          actions: assign({ status: 'failed' }),\n        },\n      },\n    },\n    summarizing: {\n      entry: toolCall('list_dir', ({ context }) => ({ path: context.dir })),\n      on: {\n        TOOL_RESULT: { target: 'done' },\n        TOOL_ERROR: { target: 'done' },\n      },\n    },\n    done: { type: 'final' },\n  },\n  output: ({ context }) => ({ status: context.status, note: context.note }),\n});\n";
 /** Build the resources Projection serves for a wrapped server (R3). */
 declare function buildResources(catalog: ServerCatalog, dts: string): ProjectionResource[];
+/** R37: above this many tools, `discover_apis` defers the per-tool list to the catalog tools. */
+declare const DEFAULT_INLINE_TOOL_THRESHOLD = 40;
+interface DiscoverApisOptions {
+  /** Whether the catalog projection (`search_tools` / `describe_tool`) is served (R37). */
+  catalog?: boolean;
+  /**
+   * Tool count above which the inline per-tool list is omitted. Default
+   * {@link DEFAULT_INLINE_TOOL_THRESHOLD}; a finite value is floored and
+   * clamped at 0, anything else falls back to the default.
+   */
+  inlineThreshold?: number;
+}
 /**
  * The `discover_apis` result: an inline overview sufficient to author a
  * simple machine unaided, plus resource links for the full artifacts.
+ *
+ * R37: when the catalog projection is on and the catalog is large, the
+ * per-tool overview is replaced by the tool count and a pointer to
+ * `search_tools` / `describe_tool` — the `.d.ts` resource stays complete.
  */
-declare function discoverApis(catalog: ServerCatalog, overview: string): CallToolResult;
+declare function discoverApis(catalog: ServerCatalog, overview: string, options?: DiscoverApisOptions): CallToolResult;
+/** Which projections a facade serves (R1, R32). */
+interface ProjectionSelection {
+  codeMode: boolean;
+  catalog: boolean;
+}
 /**
- * The wrapped server's `instructions`, followed by the code-mode preamble
- * (R29). The preamble is library copy the integrating developer can replace.
+ * The wrapped server's `instructions`, followed by the preamble for the
+ * projections in service (R29). The preamble is library copy the
+ * integrating developer can replace wholesale.
  */
+declare function buildInstructions(catalog: ServerCatalog, preamble?: string, projections?: ProjectionSelection): string;
+/** Preamble when only code mode is on (R29). */
 declare 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.";
-declare function buildInstructions(catalog: ServerCatalog, preamble?: string): string;
+/** Preamble when only the catalog projection is on (R29, R32). */
+declare const DEFAULT_CATALOG_PREAMBLE = "This server exposes its tools through a catalog: call search_tools to find a tool, describe_tool to see its arguments, then call_tool to run it. Any tool that is not read-only pauses and asks the user to approve that specific action before it runs.";
+/** Preamble when both projections are on: the routing rule (R29). */
+declare const DEFAULT_ROUTING_PREAMBLE = "This server offers two ways to use its tools. For a single action, call search_tools to find the tool, describe_tool to see its arguments, then call_tool to run it. For several steps, branching on results, or a workflow worth saving, author an XState v5 state machine and run it with execute_machine (call discover_apis first for the tool types, the authoring contract, and worked examples). Either way, any action that is not read-only pauses and asks the user to approve that specific action before it runs.";
+/** The R29 preamble variant for a projection selection. */
+declare function defaultPreamble(projections: ProjectionSelection): string;
 //#endregion
 //#region src/wrap.d.ts
 interface WrapOptions {
@@ -477,7 +912,10 @@ interface WrapOptions {
   policy?: PolicyOverrides;
   /** Masks sensitive argument fields before they reach an approval prompt (R16). */
   redact?: RedactionHook;
-  /** Replaces the library's code-mode preamble (R29). */
+  /**
+   * Replaces the whole R29 preamble, whichever projections are on (the
+   * code-mode, catalog or routing copy).
+   */
   codeModePreamble?: string;
   /** Compatibility switches for pre-2026-07-28 clients. */
   compat?: {
@@ -492,8 +930,32 @@ interface WrapOptions {
   };
   /** Identity the servers built by `createServer` advertise. */
   serverInfo?: Implementation;
+  /**
+   * R37: above this many tools, `discover_apis` omits the per-tool list and
+   * points at `search_tools` / `describe_tool` (only when the catalog
+   * projection is on). Default 40.
+   */
+  catalogInlineThreshold?: number;
+  /**
+   * Shared replay cache (R38). Consulted after blob verification and before
+   * any gated execution, for both `execute_machine` and `call_tool`. None
+   * ships by default; supply a store shared across instances.
+   */
+  replayCache?: ReplayCache;
+  /**
+   * Which projections the facade serves (R1, R32): code mode
+   * (`execute_machine`, `discover_apis`) and the catalog projection
+   * (`search_tools`, `describe_tool`, `call_tool`). Both default on;
+   * disabling both is an error at wrap time.
+   */
+  projections?: ProjectionsOptions;
 }
-/** Options for registering the code-mode surface on a server the caller built. */
+/** Per-projection on/off switches (R1, R32). */
+interface ProjectionsOptions {
+  codeMode?: boolean;
+  catalog?: boolean;
+}
+/** Options for registering the projections on a server the caller built. */
 interface RegisterOptions {
   /**
    * The protocol era this server instance serves (R28). Omitted means
@@ -513,24 +975,44 @@ interface ProjectionFacade {
   readonly resources: ProjectionResource[];
   /**
    * Server factory to hand to `createMcpHandler` or `serveStdio` (R28, R29).
-   * Every instance it builds carries the code-mode `instructions` and knows
-   * the era it is serving.
+   * Every instance it builds carries the `instructions` and knows the era it
+   * is serving.
    */
   readonly serverFactory: McpServerFactory;
-  /** Run `execute_machine` for one `tools/call`, first attempt or retry. */
-  executeMachine(args: ExecuteMachineArgs, era?: ProtocolEra): Promise<ToolCallResult>;
+  /**
+   * Run `execute_machine` for one `tools/call`, first attempt or retry.
+   * `clientCanElicit` reports whether the connected client declared the
+   * `elicitation` capability (legacy compat only; omit when unknown).
+   */
+  executeMachine(args: ExecuteMachineArgs, era?: ProtocolEra, clientCanElicit?: boolean): Promise<ToolCallResult>;
   /** Run `discover_apis`. */
   discoverApis(): CallToolResult;
-  /** Build an `McpServer` carrying the instructions, both tools and the resources. */
+  /** Run `search_tools` (R33). Failures come back as R25 structured error results. */
+  searchTools(args: {
+    query?: string;
+    cursor?: string;
+  }): CallToolResult;
+  /** Run `describe_tool` (R34). Failures come back as R25 structured error results. */
+  describeTool(args: {
+    name: string;
+  }): CallToolResult;
+  /**
+   * Run `call_tool` (R35) for one `tools/call`, first attempt or retry.
+   * `era` / `clientCanElicit` as for `executeMachine`.
+   */
+  callTool(args: CallToolArgs, era?: ProtocolEra, clientCanElicit?: boolean): Promise<ToolCallResult>;
+  /** The projections this facade serves (R32). Frozen: fixed at wrap time. */
+  readonly projections: Readonly<ProjectionSelection>;
+  /** Build an `McpServer` carrying the instructions, the enabled projections' tools and the resources. */
   createServer(ctx?: RegisterOptions): McpServer;
-  /** Register both tools and the resources on an `McpServer` the caller built. */
+  /** Register the enabled projections' tools and the resources on an `McpServer` the caller built. */
   registerOn(server: McpServer, options?: RegisterOptions): void;
   /** Close the connection to the wrapped server. */
   close(): Promise<void>;
 }
 /**
  * Wrap an MCP server (an in-process instance or a connected client) into a
- * code-mode facade.
+ * Projection facade.
  */
 declare function wrapMcpServer(source: McpServer | Client, options: WrapOptions): Promise<ProjectionFacade>;
 //#endregion
@@ -584,26 +1066,6 @@ declare const SAVE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
 declare const VISUALIZE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
 declare const WORKFLOW_PROMPTS: readonly WorkflowPromptDefinition[];
 //#endregion
-//#region src/errors.d.ts
-/**
- * Error carrying the structured `isError` body every failure returns (R25).
- */
-declare class ProjectionError extends Error {
-  readonly phase: ErrorPhase;
-  readonly diagnostics: Diagnostic[];
-  readonly hint: string;
-  logs: LogEntry[];
-  constructor(phase: ErrorPhase, message: string, options?: {
-    diagnostics?: Diagnostic[];
-    hint?: string;
-    logs?: LogEntry[];
-    cause?: unknown;
-  });
-  toStructured(): StructuredError;
-}
-/** Convert any thrown value into a StructuredError, defaulting to `runtime` phase. */
-declare function toStructuredError(err: unknown, logs?: LogEntry[]): StructuredError;
-//#endregion
 //#region src/introspector/introspector.d.ts
 /** A wrapped-server source: an in-process instance or a connected client. */
 type ServerSource = McpServer | Client;
@@ -651,66 +1113,6 @@ declare class Introspector implements ToolExecutor {
  */
 declare function createIntrospector(sources: IntrospectorSources): Promise<Introspector>;
 //#endregion
-//#region src/typegen/generate.d.ts
-/**
- * Module specifier authored machines import the tools surface from (R4).
- * The sandbox component mounts {@link GeneratedToolTypes.bridgeSource} here.
- */
-declare 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).
- */
-declare const TOOL_CALL_HOST_GLOBAL = "__projection_toolcall";
-/** Output of {@link generateToolTypes}. */
-interface GeneratedToolTypes {
-  /** `.d.ts` text for the `@astral-mcp/tools` surface (serve via discover_apis, R3). */
-  dts: string;
-  /** ESM source of the runtime bridge to mount at `@astral-mcp/tools` in the sandbox. */
-  bridgeSource: string;
-  /** Compact per-tool overview block for inline embedding by discover_apis (R3). */
-  overview: string;
-}
-/**
- * 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.
- */
-declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog): GeneratedToolTypes;
-//#endregion
-//#region src/typegen/json-schema.d.ts
-/**
- * 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.
- */
-declare function schemaToTsType(schema: unknown, indent?: string): string;
-/**
- * True when the schema requires at least one argument property — used to
- * decide whether the generated tool function's `args` parameter is optional.
- */
-declare function schemaRequiresArgs(schema: unknown): boolean;
-//#endregion
 //#region src/text-safety.d.ts
 /**
  * Rendering untrusted strings inertly (S5, S6).
@@ -786,7 +1188,7 @@ declare function policyDeniedReason(toolName?: string): string;
 //#region src/policy/elicitation.d.ts
 /** Structured approval copy for one gated call (input to the MRTR adapter). */
 interface ElicitationCopy {
-  /** Short title, e.g. `Approval required: delete_file`. */
+  /** Short action title, e.g. `Approve: delete file`. */
   title: string;
   /** Full human-readable summary (plain text with an indented JSON block). */
   message: string;
@@ -802,17 +1204,33 @@ interface ElicitationCopy {
 interface ElicitationCopyOptions {
   /** Redaction hook applied to args before any rendering (R16). */
   redact?: RedactionHook;
-  /** Cap on the rendered args JSON, in characters. Default 4096. */
+  /**
+   * Who asked: a machine state (default) or a direct `call_tool` request
+   * (R35). Selects the footer; nothing else differs.
+   */
+  origin?: 'machine' | 'direct';
+  /**
+   * Backstop cap on the whole rendered args JSON, in characters. Default
+   * 4096. Each string leaf is independently capped at 512 characters first.
+   */
   maxArgsChars?: number;
 }
 /**
  * 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.
+ * `resolveCallPolicy`); the copy takes the tool name, title and description
+ * from it, never from the pending call or its arguments.
  */
 declare function buildElicitationCopy(call: PendingToolCall, entry: ToolCatalogEntry, options?: ElicitationCopyOptions): ElicitationCopy;
+/**
+ * The one-line human purpose: the first sentence of the server's
+ * description, neutralized and capped. Runs of replacement characters
+ * (neutralized control bytes) are collapsed so a hostile or malformed
+ * description does not render as a wall of `�`. Undefined when the server
+ * gave no usable description.
+ */
+declare function purposeSentence(description: string | undefined): string | undefined;
 //#endregion
 //#region src/sandbox/session.d.ts
 /** A tool call surfaced from the `@astral-mcp/tools` bridge inside the VM. */
@@ -932,7 +1350,7 @@ declare function runSegment(options: RunSegmentOptions): Promise<SegmentOutcome>
  * Human-readable authoring contract. `discover_apis` publishes this inline
  * (R3) so a model can author a valid machine without fetching resources.
  */
-declare const AUTHORING_CONTRACT = "Projection authoring contract (execute_machine)\n\nWrite ONE module whose only top-level statements are imports and a single\ndefault-exported XState v5 machine. The module is re-evaluated on every\napproval round trip, so top-level side effects are rejected.\n\n  import { setup } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({ /* ... */ });\n\nRules:\n1. Default-export a machine built with XState v5 setup(...).createMachine(...).\n   XState v4 Machine(...) is rejected.\n2. Machine context must be JSON-serializable at all times. No Map, Set, Date,\n   class instances, functions, undefined, bigint or symbols in context.\n3. Request tools with the toolCall action. NEVER wrap a tool call in\n   fromPromise/invoke — restored snapshots restart invoked actors, which\n   would re-execute an approved write. Machines using invoke are rejected.\n4. After a toolCall, wait in a state for one of these events:\n     TOOL_RESULT { callId, result }   the call succeeded\n     TOOL_ERROR  { callId, error }    the call failed\n     TOOL_DENIED { callId, reason }   the user declined, or policy denies it\n   Denial is not an abort: handle TOOL_DENIED and continue or finish.\n   IMPORTANT: if your machine has more than one call outstanding at the same\n   time (parallel regions), give each toolCall an explicit id and guard every\n   waiting state with whenCall(id) — events reach every region that can\n   handle them, so an unguarded region will consume another call's result:\n\n     import { toolCall, whenCall } from '@astral-mcp/tools';\n     entry: toolCall('write_file', () => ({ path: '/a' }), { id: 'a' }),\n     on: { TOOL_RESULT: { guard: whenCall('a'), target: 'done' } },\n5. Read-only tools run immediately. Every other tool pauses the machine for\n   user approval; the arguments captured at that moment are the arguments\n   that execute.\n6. Only 'xstate' and '@astral-mcp/tools' resolve as imports. There is no\n   filesystem, no network, no fetch. All working state lives in context.\n7. Finish by reaching a final state. Use the machine's output for the result.\n\nExample — happy path with a read-only call:\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'readNotes',\n    context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),\n    initial: 'reading',\n    states: {\n      reading: {\n        entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ text: ({ event }) => event.result }) },\n          TOOL_ERROR: 'failed',\n        },\n      },\n      done: { type: 'final' },\n      failed: { type: 'final' },\n    },\n    output: ({ context }) => ({ text: context.text }),\n  });\n\nExample — handling a denied approval:\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'writeNotes',\n    context: { status: 'pending' },\n    initial: 'writing',\n    states: {\n      writing: {\n        entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ status: 'written' }) },\n          TOOL_DENIED: { target: 'done', actions: assign({ status: 'skipped' }) },\n          TOOL_ERROR: { target: 'done', actions: assign({ status: 'failed' }) },\n        },\n      },\n      done: { type: 'final' },\n    },\n    output: ({ context }) => ({ status: context.status }),\n  });\n";
+declare const AUTHORING_CONTRACT = "Projection authoring contract (execute_machine)\n\nWrite ONE module whose only top-level statements are imports and a single\ndefault-exported XState v5 machine. The module is re-evaluated on every\napproval round trip, so top-level side effects are rejected.\n\n  import { setup } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({ /* ... */ });\n\nRules:\n1. Default-export a machine built with XState v5 setup(...).createMachine(...).\n   XState v4 Machine(...) is rejected.\n2. Machine context must be JSON-serializable at all times. No Map, Set, Date,\n   class instances, functions, undefined, bigint or symbols in context.\n3. Request tools with the toolCall action. NEVER wrap a tool call in\n   fromPromise/invoke — restored snapshots restart invoked actors, which\n   would re-execute an approved write. Machines using invoke are rejected.\n4. After a toolCall, wait in a state for one of these events:\n     TOOL_RESULT { callId, result }   the call succeeded\n     TOOL_ERROR  { callId, error }    the call failed\n     TOOL_DENIED { callId, reason }   the user declined, or policy denies it\n   Denial is not an abort: handle TOOL_DENIED and continue or finish.\n   IMPORTANT: if your machine has more than one call outstanding at the same\n   time (parallel regions), give each toolCall an explicit id and guard every\n   waiting state with whenCall(id) — events reach every region that can\n   handle them, so an unguarded region will consume another call's result:\n\n     import { toolCall, whenCall } from '@astral-mcp/tools';\n     entry: toolCall('write_file', () => ({ path: '/a' }), { id: 'a' }),\n     on: { TOOL_RESULT: { guard: whenCall('a'), target: 'done' } },\n5. Read-only tools run immediately. Every other tool pauses the machine for\n   user approval; the arguments captured at that moment are the arguments\n   that execute.\n6. Only 'xstate' and '@astral-mcp/tools' resolve as imports. There is no\n   filesystem, no network, no fetch. All working state lives in context.\n7. Finish by reaching a final state. Use the machine's output for the result.\n8. TOOL_RESULT.result is the tool's structuredContent when the server returns\n   one (see its Output type in tools.d.ts); otherwise the text of its single\n   text block, null for an empty result, or the raw content array for\n   anything else. A tool that returns isError arrives as TOOL_ERROR. Tools\n   without an Output type are typed unknown — usually a string.\n9. Tool inputs such as paths, ids and names are server-specific. Do not guess\n   them: take them from the machine's input, or discover them first with a\n   read-only call (a list/search tool) and keep what you learn in context.\n\nExample — happy path with a read-only call (run with input: { path }):\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'readOne',\n    context: ({ input }) => ({ path: input.path, result: null }),\n    initial: 'reading',\n    states: {\n      reading: {\n        entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ result: ({ event }) => event.result }) },\n          TOOL_ERROR: 'failed',\n        },\n      },\n      done: { type: 'final' },\n      failed: { type: 'final' },\n    },\n    output: ({ context }) => ({ result: context.result }),\n  });\n\nExample — handling a denied approval (run with input: { path }):\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'writeOne',\n    context: ({ input }) => ({ path: input.path, status: 'pending' }),\n    initial: 'writing',\n    states: {\n      writing: {\n        entry: toolCall('write_file', ({ context }) => ({ path: context.path, content: 'hello' })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ status: 'written' }) },\n          TOOL_DENIED: { target: 'done', actions: assign({ status: 'skipped' }) },\n          TOOL_ERROR: { target: 'done', actions: assign({ status: 'failed' }) },\n        },\n      },\n      done: { type: 'final' },\n    },\n    output: ({ context }) => ({ status: context.status }),\n  });\n";
 //#endregion
-export { APPROVAL_SCHEMA, AUTHORING_CONTRACT, ApprovalVerdict, AuditEntry, BLOB_SCHEMA_VERSION, BlobPayload, BlobSealerConfig, type CallToolResult, type ContentBlock, DASHBOARD_HTML, DASHBOARD_RESOURCE_URI, DEFAULT_CAPS, DEFAULT_CODE_MODE_PREAMBLE, DEFAULT_MAX_BLOB_BYTES, DEFAULT_SERVER_ALIAS, DEFAULT_TTL_MS, Diagnostic, ENVELOPE_PREFIX, EXAMPLE_DENIAL_FALLBACK, EXAMPLE_HAPPY_PATH, type ElicitationCopy, type ElicitationCopyOptions, ErrorPhase, type ExecuteMachineArgs, type ExecuteMachineDeps, type GeneratedToolTypes, HostEvent, type InputRequest, type InputRequests, type InputRequiredResult, type InputResponse, type InputResponseView, type InputResponses, Introspector, LIB_VERSION, LogEntry, LogLevel, MAX_CAPS, MCP_APP_MIME_TYPE, MRTR_PROTOCOL_REVISION, type OpenBlobOptions, POLICY_DENIED_REASON, PendingToolCall, PolicyDecision, PolicyOverrides, ProjectionConfig, ProjectionError, type ProjectionFacade, type ProjectionResource, type ProtocolEra, RESOURCE_URIS, RedactionHook, type RegisterOptions, type ResolvedCallPolicy, ResourceCaps, type RetryEnvelope, type RunSegmentOptions, SAVE_WORKFLOW_PROMPT, type SandboxSession, type SandboxSessionOptions, type SandboxToolCall, type SandboxToolCallHandler, SegmentOutcome, ServerAlias, ServerCatalog, StructuredError, TOOLS_MODULE_SPECIFIER, TOOL_CALL_HOST_GLOBAL, ToolAnnotations, ToolCallOutcome, type ToolCallResult, ToolCatalog, ToolCatalogEntry, ToolExecutor, VISUALIZE_WORKFLOW_PROMPT, WORKFLOW_PROMPTS, type WorkflowPromptDefinition, type WrapOptions, 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 };
+export { APPROVAL_SCHEMA, AUTHORING_CONTRACT, type ApprovalGateDeps, ApprovalVerdict, AuditEntry, BLOB_SCHEMA_VERSION, BlobKind, BlobPayload, BlobSealerConfig, CALL_KEY, type CallToolArgs, type CallToolDeps, type CallToolOutcome, type CallToolResult, type ContentBlock, DASHBOARD_HTML, DASHBOARD_RESOURCE_URI, DEFAULT_CALL_TTL_MS, DEFAULT_CAPS, DEFAULT_CATALOG_PREAMBLE, DEFAULT_CODE_MODE_PREAMBLE, DEFAULT_INLINE_TOOL_THRESHOLD, DEFAULT_MAX_BLOB_BYTES, DEFAULT_ROUTING_PREAMBLE, DEFAULT_SEARCH_PAGE_SIZE, DEFAULT_SERVER_ALIAS, DEFAULT_TTL_MS, type DescribeToolArgs, type DescribeToolOptions, Diagnostic, type DiscoverApisOptions, ENVELOPE_PREFIX, EXAMPLE_DENIAL_FALLBACK, EXAMPLE_HAPPY_PATH, type ElicitationCopy, type ElicitationCopyOptions, ErrorPhase, type ExecuteMachineArgs, type ExecuteMachineDeps, type GeneratedToolTypes, HostEvent, type InputRequest, type InputRequests, type InputRequiredResult, type InputResponse, type InputResponseView, type InputResponses, Introspector, LIB_VERSION, LogEntry, LogLevel, MAX_CAPS, MAX_QUERY_CHARS, MAX_SCHEMA_CHARS, MCP_APP_MIME_TYPE, MRTR_PROTOCOL_REVISION, type OpenBlobOptions, POLICY_DENIED_REASON, PendingToolCall, PolicyDecision, PolicyOverrides, ProjectionConfig, ProjectionError, type ProjectionFacade, type ProjectionResource, type ProjectionSelection, type ProjectionsOptions, type ProtocolEra, RESOURCE_URIS, RedactionHook, type RegisterOptions, ReplayCache, type ResolvedCallPolicy, ResourceCaps, type RetryEnvelope, type RunSegmentOptions, SAVE_WORKFLOW_PROMPT, SCHEMA_KEY_ALLOWLIST, type SandboxSession, type SandboxSessionOptions, type SandboxToolCall, type SandboxToolCallHandler, type SanitizedSchema, type SearchToolsArgs, type SearchToolsOptions, type SearchToolsPage, SegmentOutcome, ServerAlias, ServerCatalog, StructuredError, TOOLS_MODULE_SPECIFIER, TOOL_CALL_HOST_GLOBAL, ToolAnnotations, ToolCallOutcome, type ToolCallResult, ToolCatalog, ToolCatalogEntry, type ToolDescription, ToolExecutor, type ToolPosture, type ToolSummary, type ToolTypeText, VISUALIZE_WORKFLOW_PROMPT, WORKFLOW_PROMPTS, type WorkflowPromptDefinition, type WrapOptions, XSTATE_VERSION, acceptedContent, buildBlobPayload, buildElicitationCopy, buildInstructions, buildResources, callTool, canonicalJson, canonicalRequest, capLength, clampCaps, createIntrospector, createSandboxSession, decidePolicy, dedupeTools, defaultPreamble, describeTool, discoverApis, errorResult, executeMachine, findTool, generateToolTypes, hashCode, inputRequired, inputResponse, isInputRequiredResult, isRecord, neutralizeControlChars, openBlob, policyDeniedReason, postureOf, purposeSentence, resolveCallPolicy, runSegment, sanitizeSchema, schemaRequiresArgs, schemaToTsType, sealBlob, searchTools, summarizeTool, supportsMrtr, toStructuredError, validateArgsShape, wrapMcpServer };
 //# sourceMappingURL=index.d.mts.map