@astral-mcp/projection 0.6.0 → 0.8.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
 /**
@@ -11,16 +11,16 @@ import { Client } from "@modelcontextprotocol/client";
  * nothing inside the package.
  */
 /** Alias identifying a wrapped server. v1 instantiates exactly one. */
-type ServerAlias = string;
-declare const DEFAULT_SERVER_ALIAS: ServerAlias;
+export type ServerAlias = string;
+export declare const DEFAULT_SERVER_ALIAS: ServerAlias;
 /** MCP tool annotations we care about (untrusted hints — S5). */
-interface ToolAnnotations {
+export interface ToolAnnotations {
   readOnlyHint?: boolean;
   destructiveHint?: boolean;
   idempotentHint?: boolean;
   title?: string;
 }
-interface ToolCatalogEntry {
+export interface ToolCatalogEntry {
   /** Tool name as declared by the wrapped server. */
   name: string;
   description?: string;
@@ -30,11 +30,11 @@ interface ToolCatalogEntry {
   outputSchema?: Record<string, unknown>;
   annotations?: ToolAnnotations;
 }
-interface ToolCatalog {
+export interface ToolCatalog {
   /** Keyed by server alias (R30). v1 has exactly one entry. */
   servers: Map<ServerAlias, ServerCatalog>;
 }
-interface ServerCatalog {
+export interface ServerCatalog {
   alias: ServerAlias;
   /** Stable identity string recorded into blobs (R30). */
   identity: string;
@@ -46,18 +46,26 @@ 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.
+ */
+export 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 findTool(catalog: ServerCatalog, name: string): ToolCatalogEntry | undefined;
+export declare function dedupeTools(tools: ToolCatalogEntry[]): ToolCatalogEntry[];
 /** Narrow to a non-null, non-array object. */
-declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /** Executes a tool call against the wrapped server. Implemented by the introspector. */
-interface ToolExecutor {
+export interface ToolExecutor {
   callTool(alias: ServerAlias, name: string, args: Record<string, unknown>): Promise<ToolCallOutcome>;
 }
-type ToolCallOutcome = {
+export type ToolCallOutcome = {
   ok: true;
   result: unknown;
 } | {
@@ -67,13 +75,13 @@ type ToolCallOutcome = {
     detail?: unknown;
   };
 };
-type PolicyDecision = 'auto' | 'ask' | 'deny';
-interface PolicyOverrides {
+export type PolicyDecision = 'auto' | 'ask' | 'deny';
+export interface PolicyOverrides {
   /** Per-tool decision override, keyed by tool name (v1: single server). */
   [toolName: string]: PolicyDecision;
 }
 /** A tool call requested by the machine via the `toolCall` action creator. */
-interface PendingToolCall {
+export interface PendingToolCall {
   /** Unique id for this call within the workflow (also the inputRequest key). */
   id: string;
   name: string;
@@ -82,7 +90,7 @@ interface PendingToolCall {
   stateName: string;
 }
 /** Events the host injects into the machine. The machine never performs I/O itself. */
-type HostEvent = {
+export type HostEvent = {
   type: 'TOOL_RESULT';
   callId: string;
   result: unknown;
@@ -98,14 +106,16 @@ type HostEvent = {
   callId: string;
   reason?: string;
 };
-type ErrorPhase = 'transpile' | 'validate' | 'runtime' | 'cap_exceeded' | 'blob_verification' | 'protocol' | 'terminal';
-interface Diagnostic {
+export 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';
+export interface Diagnostic {
   message: string;
   /** Optional source location within the submitted code. */
   line?: number;
   column?: number;
 }
-interface StructuredError {
+export interface StructuredError {
   phase: ErrorPhase;
   message: string;
   diagnostics: Diagnostic[];
@@ -113,8 +123,8 @@ interface StructuredError {
   hint: string;
   logs: LogEntry[];
 }
-type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
-interface LogEntry {
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+export interface LogEntry {
   level: LogLevel;
   message: string;
   /** Milliseconds since segment start. */
@@ -122,7 +132,7 @@ interface LogEntry {
   /** Zero-based MRTR segment index this entry was captured in. */
   segment: number;
 }
-interface ResourceCaps {
+export interface ResourceCaps {
   /** Wall-clock per execution segment, ms. */
   segmentWallClockMs: number;
   /** WASM memory, bytes. */
@@ -144,19 +154,27 @@ interface ResourceCaps {
   /** Captured console output per segment, bytes. */
   maxConsoleBytes: number;
 }
-declare const DEFAULT_CAPS: ResourceCaps;
-declare const MAX_CAPS: ResourceCaps;
+export declare const DEFAULT_CAPS: ResourceCaps;
+export 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;
-interface BlobPayload {
+export declare function clampCaps(requested: Partial<ResourceCaps>): ResourceCaps;
+export declare const BLOB_SCHEMA_VERSION = 1;
+/** Which tool minted a blob (R36): a blob opened by the other tool is rejected. */
+export type BlobKind = 'machine' | 'call';
+export 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;
@@ -181,25 +199,52 @@ interface BlobPayload {
   /** Expiry, Unix ms (default TTL 15 min). */
   exp: number;
 }
-interface BlobSealerConfig {
+export interface BlobSealerConfig {
   /** Current encryption key (32 bytes). */
   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.
+ */
+export 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 = {
+export type ApprovalVerdict = {
   kind: 'approved';
 } | {
   kind: 'declined';
   reason?: string;
 };
 /** Outcome of running one execution segment. */
-type SegmentOutcome = {
+export type SegmentOutcome = {
   status: 'completed';
   /** Final machine output/context to return to the client. */
   output: unknown;
@@ -219,21 +264,21 @@ type SegmentOutcome = {
   status: 'error';
   error: StructuredError;
 };
-interface AuditEntry {
+export interface AuditEntry {
   callId: string;
   tool: string;
   args: Record<string, unknown>;
   decision: 'auto' | 'approved' | 'declined' | 'denied_by_policy' | 'error';
   reason?: string;
 }
-interface RedactionHook {
+export interface RedactionHook {
   /**
    * Mask sensitive argument fields before they appear in elicitation copy
    * (R16). Receives the tool name and resolved args; returns args to display.
    */
   (toolName: string, args: Record<string, unknown>): Record<string, unknown>;
 }
-interface ProjectionConfig {
+export interface ProjectionConfig {
   /** Resource cap overrides, clamped at maxima (R12). */
   caps?: Partial<ResourceCaps>;
   /** Per-tool policy overrides (R14). */
@@ -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). */
-declare const DEFAULT_TTL_MS: number;
+export declare const ENVELOPE_PREFIX = "proj1";
+/** Default blob TTL for `machine` blobs: 15 minutes (R20). */
+export 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).
+ */
+export declare const DEFAULT_CALL_TTL_MS: number;
 /** Default sealed-blob size ceiling: 128 KB (R23). */
-declare const DEFAULT_MAX_BLOB_BYTES: number;
+export 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;
+export 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;
@@ -277,7 +335,7 @@ interface BuildBlobPayloadInput {
  * Construct a fully populated {@link BlobPayload}: stamps the schema and
  * library/XState versions, hashes the code, and fills nonce/iat/exp.
  */
-declare function buildBlobPayload(input: BuildBlobPayloadInput): BlobPayload;
+export declare function buildBlobPayload(input: BuildBlobPayloadInput): BlobPayload;
 /**
  * Seal a payload into an opaque `proj1.` envelope string (R19, R23).
  *
@@ -286,9 +344,14 @@ declare function buildBlobPayload(input: BuildBlobPayloadInput): BlobPayload;
  * the sealed envelope exceeds `maxBlobBytes` (default 128 KB) or the config
  * keys are malformed.
  */
-declare function sealBlob(payload: BlobPayload, config: BlobSealerConfig): string;
+export 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;
@@ -311,7 +374,7 @@ interface OpenBlobOptions {
  * failed check (never key material or plaintext). A payload is only
  * returned once every check has passed.
  */
-declare function openBlob(blob: string, options: OpenBlobOptions): BlobPayload;
+export declare function openBlob(blob: string, options: OpenBlobOptions): BlobPayload;
 //#endregion
 //#region src/blob/versions.d.ts
 /**
@@ -326,9 +389,9 @@ 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.6.0";
+export declare const LIB_VERSION = "0.8.0";
 /** Pinned XState version (must match the exact pin in package.json — D2). */
-declare const XSTATE_VERSION = "5.32.5";
+export declare const XSTATE_VERSION = "5.32.5";
 //#endregion
 //#region src/mrtr/protocol.d.ts
 /**
@@ -364,7 +427,7 @@ interface RetryEnvelope {
  * an approval prompt whose only payload is an optional decline reason is our
  * product decision (R16/R17), not a protocol shape.
  */
-declare const APPROVAL_SCHEMA: ElicitRequestFormParams['requestedSchema'];
+export declare const APPROVAL_SCHEMA: ElicitRequestFormParams['requestedSchema'];
 /**
  * Protocol revision that introduced MRTR.
  *
@@ -375,7 +438,7 @@ declare const APPROVAL_SCHEMA: ElicitRequestFormParams['requestedSchema'];
  * `'modern'` rather than as a version string. We keep the literal purely so
  * error copy can name the revision a client must speak (R28).
  */
-declare const MRTR_PROTOCOL_REVISION = "2026-07-28";
+export declare const MRTR_PROTOCOL_REVISION = "2026-07-28";
 /**
  * Whether the era a request is being served on can carry MRTR (R28).
  *
@@ -386,9 +449,20 @@ declare const MRTR_PROTOCOL_REVISION = "2026-07-28";
  * no `extra.protocolVersion` to read, and reading one was the bug this
  * migration fixes (docs/DECISIONS.md D1).
  */
-declare function supportsMrtr(era: ProtocolEra$1 | undefined): boolean;
+export 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>;
@@ -431,6 +510,12 @@ interface ExecuteMachineDeps {
    * 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
@@ -439,11 +524,460 @@ interface ExecuteMachineDeps {
  * Statelessness (R27): everything needed to resume rides in `requestState`,
  * so any instance can serve any retry. Nothing is held between calls.
  */
-declare function executeMachine(args: ExecuteMachineArgs, deps: ExecuteMachineDeps): Promise<ToolCallResult>;
+export declare function executeMachine(args: ExecuteMachineArgs, deps: ExecuteMachineDeps): Promise<ToolCallResult>;
+/** Every failure is a normal result with `isError: true` and a structured body (R25). */
+export 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). */
+export declare const CALL_KEY = "call";
+/** Run `call_tool` for one `tools/call`, first attempt or MRTR retry. */
+export 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. */
+export declare function canonicalJson(value: unknown): string;
+/** The text a `call` blob is bound to (R36): `{ kind: "call", name, args }`. */
+export 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. */
+export declare function validateArgsShape(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): void;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error carrying the structured `isError` body every failure returns (R25).
+ */
+export 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. */
+export declare function toStructuredError(err: unknown, logs?: LogEntry[]): StructuredError;
+//#endregion
+//#region src/policy/decision.d.ts
+/**
+ * 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.
+ */
+export declare function decidePolicy(entry: ToolCatalogEntry, overrides?: PolicyOverrides): PolicyDecision;
+/** The three normative posture strings (R33) — models match on these. */
+type ToolPosture = 'runs immediately' | 'asks for approval' | 'blocked by policy';
+/** Map a policy decision to its plain-words posture (R33). Shared by every surface that names one. */
+export declare function postureOf(decision: PolicyDecision): ToolPosture;
+/** Result of resolving a pending call against a server catalog. */
+type ResolvedCallPolicy = {
+  ok: true;
+  decision: PolicyDecision;
+  entry: ToolCatalogEntry;
+} | {
+  ok: false;
+  error: ProjectionError;
+};
+/**
+ * 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.
+ */
+export declare function resolveCallPolicy(call: PendingToolCall, catalog: ServerCatalog, overrides?: PolicyOverrides): ResolvedCallPolicy;
+/**
+ * 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.
+ */
+export declare 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.
+ */
+export declare function policyDeniedReason(toolName?: string): string;
+//#endregion
+//#region src/policy/elicitation.d.ts
+/** Structured approval copy for one gated call (input to the MRTR adapter). */
+interface ElicitationCopy {
+  /** Short action title, e.g. `Approve: delete file`. */
+  title: string;
+  /** Full human-readable summary (plain text with an indented JSON block). */
+  message: string;
+  /** Tool name, taken from the catalog entry. */
+  toolName: string;
+  /** Machine state path that requested the call (raw; render with care). */
+  stateName: string;
+  /** The redacted arguments as rendered in `message` (JSON text, possibly truncated). */
+  args: string;
+  /** True when the catalog entry carries `destructiveHint: true`. */
+  destructive: boolean;
+}
+interface ElicitationCopyOptions {
+  /** Redaction hook applied to args before any rendering (R16). */
+  redact?: RedactionHook;
+  /**
+   * 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, title and description
+ * from it, never from the pending call or its arguments.
+ */
+export declare function buildElicitationCopy(call: PendingToolCall, entry: ToolCatalogEntry, options?: ElicitationCopyOptions): ElicitationCopy;
+//#endregion
+//#region src/text-safety.d.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.
+ */
+/**
+ * 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).
+ */
+export declare function neutralizeControlChars(text: string, options?: {
+  allowNewline?: boolean;
+}): string;
+/** Truncate to `maxChars`, appending an ellipsis when shortened. */
+export declare function capLength(text: string, maxChars: number): string;
+/**
+ * The one-line human purpose: the first sentence of the server's
+ * description, neutralized and capped. Runs of replacement characters
+ * (neutralized control bytes) are collapsed so a hostile or malformed
+ * description does not render as a wall of `�`. Undefined when the server
+ * gave no usable description.
+ *
+ * One rule, three consumers — the approval copy (R16), the `discover_apis`
+ * overview and `search_tools` (R33) — so every projection describes a tool
+ * identically.
+ */
+export declare function purposeSentence(description: string | undefined): string | undefined;
+//#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.
+ */
+export 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).
+ */
+export 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.
+ */
+export declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog, options?: GenerateToolTypesOptions): GeneratedToolTypes;
+interface GenerateToolTypesOptions {
+  /** Per-tool policy overrides (R14): decide the posture wording in docs and overview. */
+  policy?: PolicyOverrides | undefined;
+}
+//#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.
+ */
+export 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.
+ */
+export declare function schemaRequiresArgs(schema: unknown): boolean;
+//#endregion
+//#region src/catalog/describe.d.ts
+interface DescribeToolArgs {
+  name: string;
+  /**
+   * Include the generated TypeScript for the tool (R34). Off by default:
+   * the JSON Schema already carries the shape, and the types double the
+   * payload — ask for them when authoring a machine.
+   */
+  types?: boolean;
+}
+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).
+ */
+export 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). */
+export declare const SCHEMA_KEY_ALLOWLIST: ReadonlySet<string>;
+/** Rendered-schema cap per tool, in characters of its JSON text (R34). */
+export 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 `{}`.
+ */
+export declare function sanitizeSchema(schema: unknown, maxChars?: number): SanitizedSchema;
+//#endregion
+//#region src/catalog/search.d.ts
+interface SearchToolsArgs {
+  /**
+   * Words to match against tool names, titles and descriptions; any word
+   * matches, name hits weigh more (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. */
+export declare const DEFAULT_SEARCH_PAGE_SIZE = 50;
+/** `query` is capped (R33): its words are matched as plain substrings, never a regex. */
+export declare const MAX_QUERY_CHARS = 200;
+/** 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;
+}
+/** Summarize one catalog entry (R33). */
+export 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).
+ */
+export declare function searchTools(catalog: ServerCatalog, args: SearchToolsArgs, options?: SearchToolsOptions): CallToolResult;
 //#endregion
 //#region src/mrtr/discover.d.ts
 /** Stable URIs the server serves via `resources/read` (R3). */
-declare const RESOURCE_URIS: {
+export declare const RESOURCE_URIS: {
   readonly toolTypes: "projection://types/tools.d.ts";
   readonly contract: "projection://docs/authoring-contract.md";
   readonly happyPath: "projection://examples/happy-path.ts";
@@ -459,21 +993,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 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";
+export 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";
+export 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[];
+export declare function buildResources(catalog: ServerCatalog, dts: string): ProjectionResource[];
+/** R37: above this many tools, `discover_apis` defers the per-tool list to the catalog tools. */
+export 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;
+export 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 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;
+export declare function buildInstructions(catalog: ServerCatalog, preamble?: string, projections?: ProjectionSelection): string;
+/** Preamble when only code mode is on (R29). */
+export 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.";
+/** Preamble when only the catalog projection is on (R29, R32). */
+export 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). */
+export 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. */
+export declare function defaultPreamble(projections: ProjectionSelection): string;
 //#endregion
 //#region src/wrap.d.ts
 interface WrapOptions {
@@ -481,11 +1044,17 @@ interface WrapOptions {
   blob: BlobSealerConfig;
   /** Resource cap overrides, clamped at the hard maxima (R12). */
   caps?: Partial<ResourceCaps>;
-  /** Per-tool policy overrides (R14). */
+  /**
+   * Per-tool policy overrides (R14). Read once, at wrap time: the facade
+   * keeps its own frozen copy, so later changes to this object are not seen.
+   */
   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?: {
@@ -500,8 +1069,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
@@ -521,8 +1114,8 @@ 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;
   /**
@@ -533,18 +1126,35 @@ interface ProjectionFacade {
   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;
+    types?: boolean;
+  }): 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>;
+export declare function wrapMcpServer(source: McpServer | Client, options: WrapOptions): Promise<ProjectionFacade>;
 //#endregion
 //#region src/apps/dashboard.d.ts
 /**
@@ -575,10 +1185,10 @@ declare function wrapMcpServer(source: McpServer | Client, options: WrapOptions)
  *   `{ phase, message, hint, logs }`.
  */
 /** URI the dashboard is served under. MCP Apps mandates the ui:// scheme. */
-declare const DASHBOARD_RESOURCE_URI = "ui://projection/dashboard.html";
+export declare const DASHBOARD_RESOURCE_URI = "ui://projection/dashboard.html";
 /** MIME type the MCP Apps spec mandates for app HTML resources. */
-declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
-declare const DASHBOARD_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\" />\n<title>Projection workflow dashboard</title>\n<style>\n  :root {\n    color-scheme: light dark;\n    --bg: #ffffff; --fg: #1a1a2e; --muted: #6b7280; --line: #e5e7eb;\n    --ok: #047857; --ok-bg: #ecfdf5; --err: #b91c1c; --err-bg: #fef2f2;\n    --chip: #eef2ff; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;\n  }\n  @media (prefers-color-scheme: dark) {\n    :root {\n      --bg: #111318; --fg: #e5e7eb; --muted: #9ca3af; --line: #2a2f3a;\n      --ok: #34d399; --ok-bg: #06281f; --err: #f87171; --err-bg: #2d1215;\n      --chip: #1e2433;\n    }\n  }\n  html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg);\n    font: 14px/1.5 system-ui, sans-serif; }\n  main { padding: 16px; max-width: 720px; }\n  h1 { font-size: 15px; margin: 0 0 12px; display: flex; gap: 8px; align-items: center; }\n  .chip { font-size: 12px; padding: 2px 10px; border-radius: 999px; background: var(--chip); }\n  .chip.ok { color: var(--ok); background: var(--ok-bg); }\n  .chip.err { color: var(--err); background: var(--err-bg); }\n  section { margin: 14px 0; }\n  section > h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .06em;\n    color: var(--muted); margin: 0 0 6px; }\n  pre { margin: 0; padding: 10px; background: var(--chip); border-radius: 8px;\n    font-family: var(--mono); font-size: 12px; overflow-x: auto; white-space: pre-wrap; }\n  table { border-collapse: collapse; width: 100%; font-size: 13px; }\n  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line);\n    vertical-align: top; }\n  th { color: var(--muted); font-weight: 500; }\n  td.args { font-family: var(--mono); font-size: 12px; }\n  .log { font-family: var(--mono); font-size: 12px; padding: 2px 0; }\n  .log .level { color: var(--muted); margin-right: 6px; }\n  .hint { color: var(--muted); font-size: 13px; margin-top: 6px; }\n  .hidden { display: none; }\n  #waiting { color: var(--muted); }\n</style>\n</head>\n<body>\n<main>\n  <h1>Projection workflow <span id=\"status\" class=\"chip\">waiting…</span></h1>\n  <p id=\"waiting\">Waiting for the workflow result from the host…</p>\n  <section id=\"output-section\" class=\"hidden\"><h2>Output</h2><pre id=\"output\"></pre></section>\n  <section id=\"error-section\" class=\"hidden\"><h2>Error</h2>\n    <pre id=\"error\"></pre><p id=\"error-hint\" class=\"hint\"></p></section>\n  <section id=\"approvals-section\" class=\"hidden\"><h2>Approval audit trail</h2>\n    <table><thead><tr><th>Tool</th><th>Decision</th><th>Arguments</th></tr></thead>\n    <tbody id=\"approvals\"></tbody></table></section>\n  <section id=\"logs-section\" class=\"hidden\"><h2>Console</h2><div id=\"logs\"></div></section>\n</main>\n<script>\n'use strict';\n(function () {\n  var nextId = 1;\n  var pending = new Map();\n\n  function post(message) { window.parent.postMessage(message, '*'); }\n  function request(method, params) {\n    return new Promise(function (resolve, reject) {\n      var id = nextId++;\n      pending.set(id, { resolve: resolve, reject: reject });\n      post({ jsonrpc: '2.0', id: id, method: method, params: params });\n    });\n  }\n  function notify(method, params) {\n    var message = { jsonrpc: '2.0', method: method };\n    if (params !== undefined) message.params = params;\n    post(message);\n  }\n\n  function byId(id) { return document.getElementById(id); }\n  function show(id) { byId(id).classList.remove('hidden'); }\n  function setStatus(text, cls) {\n    var chip = byId('status');\n    chip.textContent = text;\n    chip.className = 'chip' + (cls ? ' ' + cls : '');\n    byId('waiting').classList.add('hidden');\n  }\n  function pretty(value) {\n    try { return JSON.stringify(value, null, 2); } catch (e) { return String(value); }\n  }\n\n  // All model-controlled data enters the DOM via textContent only.\n  function renderResult(result) {\n    var structured = (result && result.structuredContent) || {};\n    if (result && result.isError) {\n      setStatus('failed: ' + String(structured.phase || 'error'), 'err');\n      byId('error').textContent =\n        String(structured.message || 'unknown error');\n      byId('error-hint').textContent = String(structured.hint || '');\n      show('error-section');\n    } else {\n      setStatus('completed', 'ok');\n      byId('output').textContent = pretty(\n        structured.output === undefined ? null : structured.output,\n      );\n      show('output-section');\n    }\n    var approvals = Array.isArray(structured.approvals) ? structured.approvals : [];\n    if (approvals.length > 0) {\n      var tbody = byId('approvals');\n      approvals.forEach(function (entry) {\n        var row = document.createElement('tr');\n        var tool = document.createElement('td');\n        tool.textContent = String(entry.tool || '');\n        var decision = document.createElement('td');\n        decision.textContent = String(entry.decision || '');\n        var args = document.createElement('td');\n        args.className = 'args';\n        args.textContent = pretty(entry.args || {});\n        row.appendChild(tool); row.appendChild(decision); row.appendChild(args);\n        tbody.appendChild(row);\n      });\n      show('approvals-section');\n    }\n    var logs = Array.isArray(structured.logs) ? structured.logs : [];\n    if (logs.length > 0) {\n      var list = byId('logs');\n      logs.forEach(function (entry) {\n        var line = document.createElement('div');\n        line.className = 'log';\n        var level = document.createElement('span');\n        level.className = 'level';\n        level.textContent = '[' + String(entry.level || 'log') + ']';\n        line.appendChild(level);\n        line.appendChild(document.createTextNode(String(entry.message || '')));\n        list.appendChild(line);\n      });\n      show('logs-section');\n    }\n  }\n\n  window.addEventListener('message', function (event) {\n    // Only the embedding host may speak: forged tool-results from a hostile\n    // embedder could otherwise spoof the displayed audit trail.\n    if (event.source !== window.parent) return;\n    var message = event.data;\n    if (!message || message.jsonrpc !== '2.0') return;\n    if (message.id !== undefined && message.method === undefined) {\n      var waiter = pending.get(message.id);\n      if (waiter) {\n        pending.delete(message.id);\n        if (message.error) waiter.reject(message.error);\n        else waiter.resolve(message.result);\n      }\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-input') {\n      setStatus('running…');\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-result') {\n      renderResult(message.params);\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-cancelled') {\n      var reason = message.params && message.params.reason;\n      setStatus('cancelled', 'err');\n      byId('error').textContent = String(reason || 'cancelled by the host');\n      show('error-section');\n      return;\n    }\n    // Host -> app REQUESTS (id + method) get an empty result: answers ping\n    // and ui/resource-teardown so hosts don't stall on their SHOULD-wait.\n    if (message.id !== undefined && message.method !== undefined) {\n      post({ jsonrpc: '2.0', id: message.id, result: {} });\n    }\n  });\n\n  // Handshake: initialize, then signal readiness. The host MUST NOT push\n  // tool data before ui/notifications/initialized.\n  request('ui/initialize', { appCapabilities: {} }).then(function () {\n    notify('ui/notifications/initialized');\n  });\n})();\n</script>\n</body>\n</html>\n";
+export declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+export declare const DASHBOARD_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\" />\n<title>Projection workflow dashboard</title>\n<style>\n  :root {\n    color-scheme: light dark;\n    --bg: #ffffff; --fg: #1a1a2e; --muted: #6b7280; --line: #e5e7eb;\n    --ok: #047857; --ok-bg: #ecfdf5; --err: #b91c1c; --err-bg: #fef2f2;\n    --chip: #eef2ff; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;\n  }\n  @media (prefers-color-scheme: dark) {\n    :root {\n      --bg: #111318; --fg: #e5e7eb; --muted: #9ca3af; --line: #2a2f3a;\n      --ok: #34d399; --ok-bg: #06281f; --err: #f87171; --err-bg: #2d1215;\n      --chip: #1e2433;\n    }\n  }\n  html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg);\n    font: 14px/1.5 system-ui, sans-serif; }\n  main { padding: 16px; max-width: 720px; }\n  h1 { font-size: 15px; margin: 0 0 12px; display: flex; gap: 8px; align-items: center; }\n  .chip { font-size: 12px; padding: 2px 10px; border-radius: 999px; background: var(--chip); }\n  .chip.ok { color: var(--ok); background: var(--ok-bg); }\n  .chip.err { color: var(--err); background: var(--err-bg); }\n  section { margin: 14px 0; }\n  section > h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .06em;\n    color: var(--muted); margin: 0 0 6px; }\n  pre { margin: 0; padding: 10px; background: var(--chip); border-radius: 8px;\n    font-family: var(--mono); font-size: 12px; overflow-x: auto; white-space: pre-wrap; }\n  table { border-collapse: collapse; width: 100%; font-size: 13px; }\n  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line);\n    vertical-align: top; }\n  th { color: var(--muted); font-weight: 500; }\n  td.args { font-family: var(--mono); font-size: 12px; }\n  .log { font-family: var(--mono); font-size: 12px; padding: 2px 0; }\n  .log .level { color: var(--muted); margin-right: 6px; }\n  .hint { color: var(--muted); font-size: 13px; margin-top: 6px; }\n  .hidden { display: none; }\n  #waiting { color: var(--muted); }\n</style>\n</head>\n<body>\n<main>\n  <h1>Projection workflow <span id=\"status\" class=\"chip\">waiting…</span></h1>\n  <p id=\"waiting\">Waiting for the workflow result from the host…</p>\n  <section id=\"output-section\" class=\"hidden\"><h2>Output</h2><pre id=\"output\"></pre></section>\n  <section id=\"error-section\" class=\"hidden\"><h2>Error</h2>\n    <pre id=\"error\"></pre><p id=\"error-hint\" class=\"hint\"></p></section>\n  <section id=\"approvals-section\" class=\"hidden\"><h2>Approval audit trail</h2>\n    <table><thead><tr><th>Tool</th><th>Decision</th><th>Arguments</th></tr></thead>\n    <tbody id=\"approvals\"></tbody></table></section>\n  <section id=\"logs-section\" class=\"hidden\"><h2>Console</h2><div id=\"logs\"></div></section>\n</main>\n<script>\n'use strict';\n(function () {\n  var nextId = 1;\n  var pending = new Map();\n\n  function post(message) { window.parent.postMessage(message, '*'); }\n  function request(method, params) {\n    return new Promise(function (resolve, reject) {\n      var id = nextId++;\n      pending.set(id, { resolve: resolve, reject: reject });\n      post({ jsonrpc: '2.0', id: id, method: method, params: params });\n    });\n  }\n  function notify(method, params) {\n    var message = { jsonrpc: '2.0', method: method };\n    if (params !== undefined) message.params = params;\n    post(message);\n  }\n\n  function byId(id) { return document.getElementById(id); }\n  function show(id) { byId(id).classList.remove('hidden'); }\n  function setStatus(text, cls) {\n    var chip = byId('status');\n    chip.textContent = text;\n    chip.className = 'chip' + (cls ? ' ' + cls : '');\n    byId('waiting').classList.add('hidden');\n  }\n  function pretty(value) {\n    try { return JSON.stringify(value, null, 2); } catch (e) { return String(value); }\n  }\n\n  // All model-controlled data enters the DOM via textContent only.\n  function renderResult(result) {\n    var structured = (result && result.structuredContent) || {};\n    if (result && result.isError) {\n      setStatus('failed: ' + String(structured.phase || 'error'), 'err');\n      byId('error').textContent =\n        String(structured.message || 'unknown error');\n      byId('error-hint').textContent = String(structured.hint || '');\n      show('error-section');\n    } else {\n      setStatus('completed', 'ok');\n      byId('output').textContent = pretty(\n        structured.output === undefined ? null : structured.output,\n      );\n      show('output-section');\n    }\n    var approvals = Array.isArray(structured.approvals) ? structured.approvals : [];\n    if (approvals.length > 0) {\n      var tbody = byId('approvals');\n      approvals.forEach(function (entry) {\n        var row = document.createElement('tr');\n        var tool = document.createElement('td');\n        tool.textContent = String(entry.tool || '');\n        var decision = document.createElement('td');\n        decision.textContent = String(entry.decision || '');\n        var args = document.createElement('td');\n        args.className = 'args';\n        args.textContent = pretty(entry.args || {});\n        row.appendChild(tool); row.appendChild(decision); row.appendChild(args);\n        tbody.appendChild(row);\n      });\n      show('approvals-section');\n    }\n    var logs = Array.isArray(structured.logs) ? structured.logs : [];\n    if (logs.length > 0) {\n      var list = byId('logs');\n      logs.forEach(function (entry) {\n        var line = document.createElement('div');\n        line.className = 'log';\n        var level = document.createElement('span');\n        level.className = 'level';\n        level.textContent = '[' + String(entry.level || 'log') + ']';\n        line.appendChild(level);\n        line.appendChild(document.createTextNode(String(entry.message || '')));\n        list.appendChild(line);\n      });\n      show('logs-section');\n    }\n  }\n\n  window.addEventListener('message', function (event) {\n    // Only the embedding host may speak: forged tool-results from a hostile\n    // embedder could otherwise spoof the displayed audit trail.\n    if (event.source !== window.parent) return;\n    var message = event.data;\n    if (!message || message.jsonrpc !== '2.0') return;\n    if (message.id !== undefined && message.method === undefined) {\n      var waiter = pending.get(message.id);\n      if (waiter) {\n        pending.delete(message.id);\n        if (message.error) waiter.reject(message.error);\n        else waiter.resolve(message.result);\n      }\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-input') {\n      setStatus('running…');\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-result') {\n      renderResult(message.params);\n      return;\n    }\n    if (message.method === 'ui/notifications/tool-cancelled') {\n      var reason = message.params && message.params.reason;\n      setStatus('cancelled', 'err');\n      byId('error').textContent = String(reason || 'cancelled by the host');\n      show('error-section');\n      return;\n    }\n    // Host -> app REQUESTS (id + method) get an empty result: answers ping\n    // and ui/resource-teardown so hosts don't stall on their SHOULD-wait.\n    if (message.id !== undefined && message.method !== undefined) {\n      post({ jsonrpc: '2.0', id: message.id, result: {} });\n    }\n  });\n\n  // Handshake: initialize, then signal readiness. The host MUST NOT push\n  // tool data before ui/notifications/initialized.\n  request('ui/initialize', { appCapabilities: {} }).then(function () {\n    notify('ui/notifications/initialized');\n  });\n})();\n</script>\n</body>\n</html>\n";
 //#endregion
 //#region src/prompts/workflow-prompts.d.ts
 interface WorkflowPromptDefinition {
@@ -592,29 +1202,9 @@ interface WorkflowPromptDefinition {
   }>;
   build(args: Record<string, string | undefined>, catalog: ServerCatalog): string;
 }
-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;
+export declare const SAVE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
+export declare const VISUALIZE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
+export declare const WORKFLOW_PROMPTS: readonly WorkflowPromptDefinition[];
 //#endregion
 //#region src/introspector/introspector.d.ts
 /** A wrapped-server source: an in-process instance or a connected client. */
@@ -630,7 +1220,7 @@ type IntrospectorSources = Record<ServerAlias, ServerSource>;
  * {@link ToolCatalog}, and executes tool calls (implements
  * {@link ToolExecutor}). Construct with {@link createIntrospector}.
  */
-declare class Introspector implements ToolExecutor {
+export declare class Introspector implements ToolExecutor {
   #private;
   private constructor();
   static create(sources: IntrospectorSources): Promise<Introspector>;
@@ -661,170 +1251,7 @@ declare class Introspector implements ToolExecutor {
  *
  * v1 usage: `createIntrospector({ [DEFAULT_SERVER_ALIAS]: serverOrClient })`.
  */
-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).
- *
- * 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.
- */
-/**
- * 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).
- */
-declare function neutralizeControlChars(text: string, options?: {
-  allowNewline?: boolean;
-}): string;
-/** Truncate to `maxChars`, appending an ellipsis when shortened. */
-declare function capLength(text: string, maxChars: number): string;
-//#endregion
-//#region src/policy/decision.d.ts
-/**
- * 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.
- */
-declare function decidePolicy(entry: ToolCatalogEntry, overrides?: PolicyOverrides): PolicyDecision;
-/** Result of resolving a pending call against a server catalog. */
-type ResolvedCallPolicy = {
-  ok: true;
-  decision: PolicyDecision;
-  entry: ToolCatalogEntry;
-} | {
-  ok: false;
-  error: ProjectionError;
-};
-/**
- * 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.
- */
-declare function resolveCallPolicy(call: PendingToolCall, catalog: ServerCatalog, overrides?: PolicyOverrides): ResolvedCallPolicy;
-/**
- * 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.
- */
-declare 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.
- */
-declare function policyDeniedReason(toolName?: string): string;
-//#endregion
-//#region src/policy/elicitation.d.ts
-/** Structured approval copy for one gated call (input to the MRTR adapter). */
-interface ElicitationCopy {
-  /** Short action title, e.g. `Approve: delete file`. */
-  title: string;
-  /** Full human-readable summary (plain text with an indented JSON block). */
-  message: string;
-  /** Tool name, taken from the catalog entry. */
-  toolName: string;
-  /** Machine state path that requested the call (raw; render with care). */
-  stateName: string;
-  /** The redacted arguments as rendered in `message` (JSON text, possibly truncated). */
-  args: string;
-  /** True when the catalog entry carries `destructiveHint: true`. */
-  destructive: boolean;
-}
-interface ElicitationCopyOptions {
-  /** Redaction hook applied to args before any rendering (R16). */
-  redact?: RedactionHook;
-  /** Cap on the rendered args JSON, in characters. Default 4096. */
-  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, title and description
- * from it, never from the pending call or its arguments.
- */
-declare function buildElicitationCopy(call: PendingToolCall, entry: ToolCatalogEntry, options?: ElicitationCopyOptions): ElicitationCopy;
+export declare function createIntrospector(sources: IntrospectorSources): Promise<Introspector>;
 //#endregion
 //#region src/sandbox/session.d.ts
 /** A tool call surfaced from the `@astral-mcp/tools` bridge inside the VM. */
@@ -887,7 +1314,7 @@ interface SandboxSession {
  * bridge, evaluate the authored module, and return a handle for driving it.
  * See ./index.ts for the full boundary contract.
  */
-declare function createSandboxSession(options: SandboxSessionOptions): Promise<SandboxSession>;
+export declare function createSandboxSession(options: SandboxSessionOptions): Promise<SandboxSession>;
 //#endregion
 //#region src/machine-host/host.d.ts
 interface RunSegmentOptions {
@@ -937,14 +1364,14 @@ interface RunSegmentOptions {
  * check of its own — `executeMachine` enforces `maxInputBytes` before calling
  * it. Callers invoking `runSegment` directly must bound `input` themselves.
  */
-declare function runSegment(options: RunSegmentOptions): Promise<SegmentOutcome>;
+export declare function runSegment(options: RunSegmentOptions): Promise<SegmentOutcome>;
 //#endregion
 //#region src/machine-host/contract.d.ts
 /**
  * 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.\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";
+export 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 { type ApprovalGateDeps, type CallToolArgs, type CallToolDeps, type CallToolOutcome, type CallToolResult, type ContentBlock, type DescribeToolArgs, type DescribeToolOptions, type DiscoverApisOptions, type ElicitationCopy, type ElicitationCopyOptions, type ExecuteMachineArgs, type ExecuteMachineDeps, type GeneratedToolTypes, type InputRequest, type InputRequests, type InputRequiredResult, type InputResponse, type InputResponseView, type InputResponses, type OpenBlobOptions, type ProjectionFacade, type ProjectionResource, type ProjectionSelection, type ProjectionsOptions, type ProtocolEra, type RegisterOptions, type ResolvedCallPolicy, type RetryEnvelope, type RunSegmentOptions, type SandboxSession, type SandboxSessionOptions, type SandboxToolCall, type SandboxToolCallHandler, type SanitizedSchema, type SearchToolsArgs, type SearchToolsOptions, type SearchToolsPage, type ToolCallResult, type ToolDescription, type ToolPosture, type ToolSummary, type ToolTypeText, type WorkflowPromptDefinition, type WrapOptions, acceptedContent, inputRequired, inputResponse, isInputRequiredResult };
 //# sourceMappingURL=index.d.mts.map