@astral-mcp/projection 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,862 @@
+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";
+import "@sebastianwessel/quickjs";
+//#region src/types.d.ts
+/**
+ * Shared core types for Projection.
+ *
+ * These types are the contract between the seven components (introspector,
+ * typegen, sandbox runtime, machine host, policy engine, blob sealer, MRTR
+ * adapter). Component implementations depend on this module; it depends on
+ * nothing inside the package.
+ */
+/** Alias identifying a wrapped server. v1 instantiates exactly one. */
+type ServerAlias = string;
+declare const DEFAULT_SERVER_ALIAS: ServerAlias;
+/** MCP tool annotations we care about (untrusted hints — S5). */
+interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  title?: string;
+}
+interface ToolCatalogEntry {
+  /** Tool name as declared by the wrapped server. */
+  name: string;
+  description?: string;
+  /** JSON Schema for the tool's input. */
+  inputSchema: Record<string, unknown>;
+  /** JSON Schema for the tool's output, when declared. */
+  outputSchema?: Record<string, unknown>;
+  annotations?: ToolAnnotations;
+}
+interface ToolCatalog {
+  /** Keyed by server alias (R30). v1 has exactly one entry. */
+  servers: Map<ServerAlias, ServerCatalog>;
+}
+interface ServerCatalog {
+  alias: ServerAlias;
+  /** Stable identity string recorded into blobs (R30). */
+  identity: string;
+  /** The wrapped server's `instructions` field, verbatim (R29). */
+  instructions?: string;
+  tools: ToolCatalogEntry[];
+}
+/**
+ * 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.
+ */
+declare function findTool(catalog: ServerCatalog, name: string): ToolCatalogEntry | undefined;
+/** Narrow to a non-null, non-array object. */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Executes a tool call against the wrapped server. Implemented by the introspector. */
+interface ToolExecutor {
+  callTool(alias: ServerAlias, name: string, args: Record<string, unknown>): Promise<ToolCallOutcome>;
+}
+type ToolCallOutcome = {
+  ok: true;
+  result: unknown;
+} | {
+  ok: false;
+  error: {
+    message: string;
+    detail?: unknown;
+  };
+};
+type PolicyDecision = 'auto' | 'ask' | 'deny';
+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 {
+  /** Unique id for this call within the workflow (also the inputRequest key). */
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  /** Machine state path that requested the call (for elicitation copy — R16). */
+  stateName: string;
+}
+/** Events the host injects into the machine. The machine never performs I/O itself. */
+type HostEvent = {
+  type: 'TOOL_RESULT';
+  callId: string;
+  result: unknown;
+} | {
+  type: 'TOOL_ERROR';
+  callId: string;
+  error: {
+    message: string;
+    detail?: unknown;
+  };
+} | {
+  type: 'TOOL_DENIED';
+  callId: string;
+  reason?: string;
+};
+type ErrorPhase = 'transpile' | 'validate' | 'runtime' | 'cap_exceeded' | 'blob_verification' | 'protocol' | 'terminal';
+interface Diagnostic {
+  message: string;
+  /** Optional source location within the submitted code. */
+  line?: number;
+  column?: number;
+}
+interface StructuredError {
+  phase: ErrorPhase;
+  message: string;
+  diagnostics: Diagnostic[];
+  /** One-line actionable fix (R25). */
+  hint: string;
+  logs: LogEntry[];
+}
+type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  /** Milliseconds since segment start. */
+  ts: number;
+  /** Zero-based MRTR segment index this entry was captured in. */
+  segment: number;
+}
+interface ResourceCaps {
+  /** Wall-clock per execution segment, ms. */
+  segmentWallClockMs: number;
+  /** WASM memory, bytes. */
+  wasmMemoryBytes: number;
+  /** Submitted code size, bytes. */
+  maxCodeBytes: number;
+  /** Submitted machine input, bytes of its JSON serialization. */
+  maxInputBytes: number;
+  /** Read-only tool calls per segment. */
+  maxReadCallsPerSegment: number;
+  /** MRTR round trips per workflow. */
+  maxRoundTrips: number;
+  /** Machine events processed per segment. */
+  maxEventsPerSegment: number;
+  /** Final result payload, bytes. */
+  maxResultBytes: number;
+  /** Machine state nodes (static count at validation). */
+  maxStateNodes: number;
+  /** Captured console output per segment, bytes. */
+  maxConsoleBytes: number;
+}
+declare const DEFAULT_CAPS: ResourceCaps;
+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 {
+  /** Blob schema version; unknown versions are rejected. */
+  v: number;
+  /** 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. */
+  codeHash: string;
+  /** Server identity the blob was minted against (R30). */
+  serverIdentity: string;
+  /** `getPersistedSnapshot()` output of the machine actor. */
+  snapshot: unknown;
+  /** inputRequest key -> gated tool call awaiting a verdict (S2). */
+  pending: Record<string, PendingToolCall>;
+  /**
+   * Approval audit accumulated in earlier segments (PRD §8).
+   *
+   * Carried in the blob because the library holds no cross-request state
+   * (R27): without it a completed workflow would report only the approvals
+   * of its final segment.
+   */
+  audit: AuditEntry[];
+  /** Round-trip counter (R18). */
+  trip: number;
+  /** Random nonce for replay scoping. */
+  nonce: string;
+  /** Issued-at, Unix ms. */
+  iat: number;
+  /** Expiry, Unix ms (default TTL 15 min). */
+  exp: number;
+}
+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. */
+  ttlMs?: number;
+  /** Sealed+compressed size ceiling in bytes. Default 128 KB (R23). */
+  maxBlobBytes?: number;
+}
+/** Verdict delivered on retry for a pending gated call. */
+type ApprovalVerdict = {
+  kind: 'approved';
+} | {
+  kind: 'declined';
+  reason?: string;
+};
+/** Outcome of running one execution segment. */
+type SegmentOutcome = {
+  status: 'completed';
+  /** Final machine output/context to return to the client. */
+  output: unknown;
+  /** Per-call approval audit trail. */
+  audit: AuditEntry[];
+  logs: LogEntry[];
+} | {
+  status: 'suspended';
+  /** Gated calls awaiting approval, keyed by inputRequest key. */
+  pending: Record<string, PendingToolCall>;
+  /** Actor snapshot to seal into the blob. */
+  snapshot: unknown;
+  trip: number;
+  audit: AuditEntry[];
+  logs: LogEntry[];
+} | {
+  status: 'error';
+  error: StructuredError;
+};
+interface AuditEntry {
+  callId: string;
+  tool: string;
+  args: Record<string, unknown>;
+  decision: 'auto' | 'approved' | 'declined' | 'denied_by_policy' | 'error';
+  reason?: string;
+}
+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 {
+  /** Resource cap overrides, clamped at maxima (R12). */
+  caps?: Partial<ResourceCaps>;
+  /** Per-tool policy overrides (R14). */
+  policy?: PolicyOverrides;
+  /** Blob sealing configuration (required for any gated flow). */
+  blob: BlobSealerConfig;
+  /** Redaction hook for elicitation copy (R16). */
+  redact?: RedactionHook;
+  /** Override the code-mode preamble appended to instructions (R29). */
+  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;
+/** Default sealed-blob size ceiling: 128 KB (R23). */
+declare const DEFAULT_MAX_BLOB_BYTES: number;
+/** SHA-256 hex digest of a code argument (S4 binding — R20 `codeHash`). */
+declare function hashCode(code: string): string;
+interface BuildBlobPayloadInput {
+  /** The original `code` argument; hashed into `codeHash` (S4). */
+  code: string;
+  /** Identity of the wrapped server this blob is minted against (R30). */
+  serverIdentity: string;
+  /** `getPersistedSnapshot()` output of the machine actor. */
+  snapshot: unknown;
+  /** inputRequest key -> gated tool call awaiting a verdict (S2). */
+  pending: Record<string, PendingToolCall>;
+  /** Approval audit accumulated so far in this workflow (PRD §8). */
+  audit?: AuditEntry[] | undefined;
+  /** Round-trip counter (R18). */
+  trip: number;
+  /** Blob TTL in ms. Default {@link DEFAULT_TTL_MS} (15 minutes). */
+  ttlMs?: number | undefined;
+  /** Clock override for testability, Unix ms. Default `Date.now()`. */
+  now?: number | undefined;
+}
+/**
+ * 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;
+/**
+ * Seal a payload into an opaque `proj1.` envelope string (R19, R23).
+ *
+ * JSON → deflateRaw → AES-256-GCM under an HKDF-SHA256 per-blob derived key,
+ * with the envelope header as AAD. Throws ProjectionError phase `terminal` if
+ * the sealed envelope exceeds `maxBlobBytes` (default 128 KB) or the config
+ * keys are malformed.
+ */
+declare function sealBlob(payload: BlobPayload, config: BlobSealerConfig): string;
+interface OpenBlobOptions {
+  /** The `code` argument re-sent with the retried call (S4). */
+  code: string;
+  /** Identity of the wrapped server handling the retry (R30). */
+  serverIdentity: string;
+  config: BlobSealerConfig;
+  /** Clock override for testability, Unix ms. Default `Date.now()`. */
+  now?: number | undefined;
+}
+/**
+ * Verify and open a sealed blob (R21 — check order is normative):
+ *
+ * 1. parse envelope + decrypt/authenticate (current key, then each
+ *    `previousKeys` — R22 rotation grace)
+ * 2. schema version, then exact `libv`/`xstatev` match (Q3: strict, no
+ *    migration)
+ * 3. expiry (`exp` strictly in the future relative to `now`)
+ * 4. `codeHash` equality against the re-sent code, and `serverIdentity`
+ *    match
+ *
+ * Any failure throws ProjectionError phase `blob_verification` naming the
+ * failed check (never key material or plaintext). A payload is only
+ * returned once every check has passed.
+ */
+declare function openBlob(blob: string, options: OpenBlobOptions): BlobPayload;
+//#endregion
+//#region src/blob/versions.d.ts
+/**
+ * Version constants recorded into every blob (R20) and strict-matched on
+ * open (R21, Q3: no migration — mismatches are rejected).
+ *
+ * Hardcoded rather than imported from package.json at runtime: JSON import
+ * attributes complicate the tsdown/dist story for zero benefit, and both
+ * versions are pinned exactly (DECISIONS.md D2). A test in
+ * `test/blob/versions.test.ts` asserts these constants match the installed
+ * package.json versions, so a version bump that forgets to update them fails
+ * CI instead of silently minting blobs with a stale version stamp.
+ */
+/** `@astral-mcp/projection` package version (must match packages/projection/package.json). */
+declare const LIB_VERSION = "0.2.0";
+/** Pinned XState version (must match the exact pin in package.json — D2). */
+declare const XSTATE_VERSION = "5.32.5";
+//#endregion
+//#region src/mrtr/protocol.d.ts
+/**
+ * What a `tools/call` handler may return on the 2026-07-28 era: a finished
+ * result, or the input-required suspension. This is the SDK's own
+ * handler-return type for the method, not a shape of ours.
+ */
+type ToolCallResult = HandlerResultTypeMap['tools/call'];
+/**
+ * The MRTR retry fields the client re-sends alongside the original
+ * arguments. The SDK lifts them off the params into `ctx.mcpReq`, so a
+ * handler never reads them from `args`; Projection still names them because
+ * `executeMachine` is callable outside an SDK handler (R27 — the facade is
+ * plain functions).
+ *
+ * `inputResponses` is deliberately widened the same way the SDK's own
+ * `inputResponse()` / `acceptedContent()` readers widen it: the values come
+ * from the client and are never validated by the SDK, so a caller may hand
+ * over whatever the wire carried.
+ */
+interface RetryEnvelope {
+  /** The `requestState` echoed back unchanged. */
+  requestState?: string;
+  /** Answers keyed by the same keys as `inputRequests`. */
+  inputResponses?: InputResponses$1 | Record<string, unknown>;
+}
+/**
+ * The JSON Schema an approval elicitation asks the client to collect, typed
+ * as the SDK's restricted elicitation schema so `inputRequired.elicit()`
+ * accepts it without a cast.
+ *
+ * Projection-specific: MRTR carries whatever schema the server asks for, and
+ * an approval prompt whose only payload is an optional decline reason is our
+ * product decision (R16/R17), not a protocol shape.
+ */
+declare const APPROVAL_SCHEMA: ElicitRequestFormParams['requestedSchema'];
+/**
+ * Protocol revision that introduced MRTR.
+ *
+ * The SDK has no exported constant for it: `LATEST_PROTOCOL_VERSION` and
+ * `SUPPORTED_PROTOCOL_VERSIONS` cover the *legacy* (`initialize`-negotiated)
+ * family only — `2025-11-25` and earlier. The 2026-07-28 era is selected by
+ * `server/discover`, and the SDK models it as the `ProtocolEra` value
+ * `'modern'` rather than as a version string. We keep the literal purely so
+ * error copy can name the revision a client must speak (R28).
+ */
+declare const MRTR_PROTOCOL_REVISION = "2026-07-28";
+/**
+ * Whether the era a request is being served on can carry MRTR (R28).
+ *
+ * The SDK binds an era to the *serving instance*, not to a per-request
+ * header: `createMcpHandler` / `serveStdio` hand the era to the server
+ * factory as `McpRequestContext.era`, and a hand-connected `McpServer` is
+ * always `'legacy'`. So this takes the era, not a version string — there is
+ * no `extra.protocolVersion` to read, and reading one was the bug this
+ * migration fixes (docs/DECISIONS.md D1).
+ */
+declare function supportsMrtr(era: ProtocolEra$1 | undefined): boolean;
+//#endregion
+//#region src/mrtr/adapter.d.ts
+interface ExecuteMachineArgs extends RetryEnvelope {
+  /** The authored module source (R2). */
+  code: string;
+  lang?: 'ts' | 'js';
+  /** Passed to the machine as its input. */
+  input?: unknown;
+}
+interface ExecuteMachineDeps {
+  catalog: ServerCatalog;
+  bridgeSource: string;
+  executor: ToolExecutor;
+  blob: BlobSealerConfig;
+  caps?: Partial<ResourceCaps>;
+  policy?: PolicyOverrides;
+  redact?: RedactionHook;
+  /**
+   * Protocol era this request is being served on, for down-negotiation
+   * (R28). The SDK hands it to the server factory as
+   * `McpRequestContext.era`; `undefined` is treated as legacy.
+   */
+  protocolEra?: ProtocolEra;
+}
+/**
+ * Run `execute_machine` for one `tools/call`, whether it is a first attempt
+ * or an MRTR retry.
+ *
+ * Statelessness (R27): everything needed to resume rides in `requestState`,
+ * so any instance can serve any retry. Nothing is held between calls.
+ */
+declare function executeMachine(args: ExecuteMachineArgs, deps: ExecuteMachineDeps): Promise<ToolCallResult>;
+//#endregion
+//#region src/mrtr/discover.d.ts
+/** Stable URIs the server serves via `resources/read` (R3). */
+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";
+  readonly denialFallback: "projection://examples/denial-fallback.ts";
+};
+/** One resource Projection serves, ready to register on the MCP server. */
+interface ProjectionResource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+  text: string;
+}
+declare const EXAMPLE_HAPPY_PATH = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Read a file and return its contents. Read-only calls run immediately,\n// so this whole machine completes in one round trip.\nexport default setup({}).createMachine({\n  id: 'readNotes',\n  context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),\n  initial: 'reading',\n  states: {\n    reading: {\n      entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n      on: {\n        TOOL_RESULT: {\n          target: 'done',\n          actions: assign({ text: ({ event }) => event.result }),\n        },\n        TOOL_ERROR: {\n          target: 'failed',\n          actions: assign({ text: ({ event }) => `error: ${event.error.message}` }),\n        },\n      },\n    },\n    done: { type: 'final' },\n    failed: { type: 'final' },\n  },\n  output: ({ context }) => ({ text: context.text }),\n});\n";
+declare const EXAMPLE_DENIAL_FALLBACK = "import { setup, assign } from 'xstate';\nimport { toolCall } from '@astral-mcp/tools';\n\n// Write a file, but keep going if the user declines. TOOL_DENIED is an\n// ordinary transition — denial is never an automatic abort.\nexport default setup({}).createMachine({\n  id: 'writeWithFallback',\n  context: { status: 'pending', note: null },\n  initial: 'writing',\n  states: {\n    writing: {\n      entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),\n      on: {\n        TOOL_RESULT: {\n          target: 'summarizing',\n          actions: assign({ status: 'written' }),\n        },\n        TOOL_DENIED: {\n          // The user said no: record it and carry on with the read-only\n          // part of the work instead of failing the whole workflow.\n          target: 'summarizing',\n          actions: assign({\n            status: 'skipped',\n            note: ({ event }) => event.reason ?? 'declined by user',\n          }),\n        },\n        TOOL_ERROR: {\n          target: 'summarizing',\n          actions: assign({ status: 'failed' }),\n        },\n      },\n    },\n    summarizing: {\n      entry: toolCall('list_dir', () => ({ path: '/' })),\n      on: {\n        TOOL_RESULT: { target: 'done' },\n        TOOL_ERROR: { target: 'done' },\n      },\n    },\n    done: { type: 'final' },\n  },\n  output: ({ context }) => ({ status: context.status, note: context.note }),\n});\n";
+/** Build the resources Projection serves for a wrapped server (R3). */
+declare function buildResources(catalog: ServerCatalog, dts: string): ProjectionResource[];
+/**
+ * The `discover_apis` result: an inline overview sufficient to author a
+ * simple machine unaided, plus resource links for the full artifacts.
+ */
+declare function discoverApis(catalog: ServerCatalog, overview: string): CallToolResult;
+/**
+ * The wrapped server's `instructions`, followed by the code-mode preamble
+ * (R29). The preamble is library copy the integrating developer can replace.
+ */
+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;
+//#endregion
+//#region src/wrap.d.ts
+interface WrapOptions {
+  /** Blob sealing configuration; required for any gated flow (R22). */
+  blob: BlobSealerConfig;
+  /** Resource cap overrides, clamped at the hard maxima (R12). */
+  caps?: Partial<ResourceCaps>;
+  /** Per-tool policy overrides (R14). */
+  policy?: PolicyOverrides;
+  /** Masks sensitive argument fields before they reach an approval prompt (R16). */
+  redact?: RedactionHook;
+  /** Replaces the library's code-mode preamble (R29). */
+  codeModePreamble?: string;
+  /** Identity the servers built by `createServer` advertise. */
+  serverInfo?: Implementation;
+}
+/** Options for registering the code-mode surface on a server the caller built. */
+interface RegisterOptions {
+  /**
+   * The protocol era this server instance serves (R28). Omitted means
+   * `'legacy'`: a hand-connected `McpServer` never negotiates 2026-07-28, so
+   * defaulting to legacy is the honest — and fail-safe — reading.
+   */
+  era?: ProtocolEra;
+}
+interface ProjectionFacade {
+  /** Catalog of the wrapped server. */
+  readonly catalog: ServerCatalog;
+  /** Instructions to advertise: the wrapped server's, then the preamble (R29). */
+  readonly instructions: string;
+  /** Generated `.d.ts` for the wrapped server's tools. */
+  readonly dts: string;
+  /** Resources served at stable `projection://` URIs (R3). */
+  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.
+   */
+  readonly serverFactory: McpServerFactory;
+  /** Run `execute_machine` for one `tools/call`, first attempt or retry. */
+  executeMachine(args: ExecuteMachineArgs, era?: ProtocolEra): Promise<ToolCallResult>;
+  /** Run `discover_apis`. */
+  discoverApis(): CallToolResult;
+  /** Build an `McpServer` carrying the instructions, both tools and the resources. */
+  createServer(ctx?: RegisterOptions): McpServer;
+  /** Register both 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.
+ */
+declare function wrapMcpServer(source: McpServer | Client, options: WrapOptions): Promise<ProjectionFacade>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error carrying the structured `isError` body every failure returns (R25).
+ */
+declare class ProjectionError extends Error {
+  readonly phase: ErrorPhase;
+  readonly diagnostics: Diagnostic[];
+  readonly hint: string;
+  logs: LogEntry[];
+  constructor(phase: ErrorPhase, message: string, options?: {
+    diagnostics?: Diagnostic[];
+    hint?: string;
+    logs?: LogEntry[];
+    cause?: unknown;
+  });
+  toStructured(): StructuredError;
+}
+/** Convert any thrown value into a StructuredError, defaulting to `runtime` phase. */
+declare function toStructuredError(err: unknown, logs?: LogEntry[]): StructuredError;
+//#endregion
+//#region src/introspector/introspector.d.ts
+/** A wrapped-server source: an in-process instance or a connected client. */
+type ServerSource = McpServer | Client;
+/**
+ * Aliased server sources (R30). v1 instantiates exactly one entry, but the
+ * interface accepts a set so the multi-server stretch goal (PRD §12.2) needs
+ * no signature break.
+ */
+type IntrospectorSources = Record<ServerAlias, ServerSource>;
+/**
+ * Holds one MCP client per wrapped-server alias, exposes the aggregated
+ * {@link ToolCatalog}, and executes tool calls (implements
+ * {@link ToolExecutor}). Construct with {@link createIntrospector}.
+ */
+declare class Introspector implements ToolExecutor {
+  #private;
+  private constructor();
+  static create(sources: IntrospectorSources): Promise<Introspector>;
+  /** The aggregated tool catalog, keyed by server alias (R30). */
+  get catalog(): ToolCatalog;
+  /** Re-read `tools/list` from every wrapped server and rebuild the catalog. */
+  refresh(): Promise<ToolCatalog>;
+  /**
+   * Execute a tool call against the wrapped server identified by `alias`,
+   * mapping the MCP result to a {@link ToolCallOutcome}:
+   *
+   * - success → `{ ok: true, result }` where `result` is the tool's
+   *   `structuredContent` when present, else a single text block's text,
+   *   else the raw content array.
+   * - `isError` result or transport/protocol failure → `{ ok: false, error }`.
+   *
+   * An unknown alias is a wiring bug, not a tool failure, and throws.
+   */
+  callTool(alias: ServerAlias, name: string, args: Record<string, unknown>): Promise<ToolCallOutcome>;
+  /**
+   * Close connections the introspector created (in-process sources).
+   * Caller-provided remote clients are left untouched.
+   */
+  close(): Promise<void>;
+}
+/**
+ * Connect to the given wrapped servers and build their tool catalog.
+ *
+ * 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 title, e.g. `Approval required: 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 and description from
+ * it, never from the pending call or its arguments.
+ */
+declare function buildElicitationCopy(call: PendingToolCall, entry: ToolCatalogEntry, options?: ElicitationCopyOptions): ElicitationCopy;
+//#endregion
+//#region src/sandbox/session.d.ts
+/** A tool call surfaced from the `@astral-mcp/tools` bridge inside the VM. */
+interface SandboxToolCall {
+  name: string;
+  args: Record<string, unknown>;
+}
+/**
+ * Host callback invoked for every bridge tool call made inside the VM.
+ *
+ * The returned value (or resolved promise value) is marshaled back into the
+ * VM as the bridge call's result; a thrown error / rejected promise rejects
+ * the in-VM promise. Values must be JSON-serializable. The sandbox attaches
+ * no semantics to the payload — result/error/denial encoding is the machine
+ * host's protocol.
+ */
+type SandboxToolCallHandler = (call: SandboxToolCall) => unknown | Promise<unknown>;
+interface SandboxSessionOptions {
+  /** The submitted module source (R2). */
+  code: string;
+  /** Language of `code`. TypeScript is transpiled without type checking (R10). */
+  lang?: 'ts' | 'js';
+  /** Resource cap overrides; clamped at the hard maxima via `clampCaps` (R12). */
+  caps?: Partial<ResourceCaps>;
+  /**
+   * Source text of the module mounted at `@astral-mcp/tools` (R8). Generated
+   * by the typegen component. May be TypeScript or JavaScript; must be a
+   * single module (relative imports do not resolve outside the mount).
+   */
+  bridgeSource: string;
+  /** Host callback for bridge tool calls. */
+  onToolCall: SandboxToolCallHandler;
+  /** Zero-based MRTR segment index, recorded on every log entry (R31). */
+  segment?: number;
+}
+/**
+ * A live sandbox holding the evaluated authored module. One session is one
+ * execution segment: it owns a fresh wall-clock budget (R13) and a fresh log
+ * collector (R31). Sessions are single-threaded — `evaluate` calls are
+ * serialized internally.
+ */
+interface SandboxSession {
+  /** The effective (clamped) caps this session enforces. */
+  readonly caps: ResourceCaps;
+  /** Zero-based MRTR segment index this session was created for. */
+  readonly segment: number;
+  /**
+   * Evaluate an ESM driver module inside the VM and return its default
+   * export marshaled to the host (promises are awaited). Rejects with
+   * {@link ProjectionError} on failure. See ./index.ts for the contract.
+   */
+  evaluate(source: string): Promise<unknown>;
+  /** Logs captured so far this segment, truncated per `maxConsoleBytes`. */
+  getLogs(): LogEntry[];
+  /** Tear down the VM. Idempotent. Pending bridge promises are rejected. */
+  dispose(): Promise<void>;
+}
+/**
+ * Create a sandbox session: boot a fresh QuickJS VM, mount xstate and the
+ * bridge, evaluate the authored module, and return a handle for driving it.
+ * See ./index.ts for the full boundary contract.
+ */
+declare function createSandboxSession(options: SandboxSessionOptions): Promise<SandboxSession>;
+//#endregion
+//#region src/machine-host/host.d.ts
+interface RunSegmentOptions {
+  /** Submitted module source (R2). */
+  code: string;
+  lang?: 'ts' | 'js';
+  /** Machine input, passed as the machine's `input` on a fresh run. */
+  input?: unknown;
+  /** Catalog of the wrapped server whose tools the machine may call. */
+  catalog: ServerCatalog;
+  /** Generated `@astral-mcp/tools` bridge source (from typegen). */
+  bridgeSource: string;
+  /** Executes approved/auto tool calls against the wrapped server. */
+  executor: ToolExecutor;
+  /** Resource caps; clamped at the hard maxima (R12). */
+  caps?: Partial<ResourceCaps>;
+  /** Per-tool policy overrides (R14). */
+  policy?: PolicyOverrides;
+  /** Zero-based MRTR segment index — stamps logs (R31). */
+  segment?: number;
+  /**
+   * Resume state. Present on every segment after the first: the verified
+   * snapshot and the pending calls sealed alongside it, plus the verdicts
+   * the client returned for those calls.
+   */
+  resume?: {
+    snapshot: unknown;
+    /** Gated calls as sealed into the blob — the approved name+args (S2). */
+    pending: Record<string, PendingToolCall>;
+    /** Verdict per pending key; a missing entry counts as declined (R17). */
+    verdicts: Record<string, ApprovalVerdict>;
+    /** Audit entries accumulated in earlier segments. */
+    audit?: AuditEntry[];
+    /** Round-trip counter carried in the blob (R18). */
+    trip: number;
+  };
+}
+/**
+ * Run one execution segment to completion, suspension, or error.
+ *
+ * A segment is one MRTR round trip: fresh sandbox, fresh wall-clock budget,
+ * fresh logs. On the first segment the module is validated (R24) before the
+ * actor starts; on a resume the module is re-evaluated from the re-sent code
+ * and the actor is restored from the sealed snapshot.
+ *
+ * Note: `runSegment` interpolates `input` into driver source without a size
+ * check of its own — `executeMachine` enforces `maxInputBytes` before calling
+ * it. Callers invoking `runSegment` directly must bound `input` themselves.
+ */
+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.\n\nExample — happy path with a read-only call:\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'readNotes',\n    context: ({ input }) => ({ path: input?.path ?? '/notes.txt', text: null }),\n    initial: 'reading',\n    states: {\n      reading: {\n        entry: toolCall('read_file', ({ context }) => ({ path: context.path })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ text: ({ event }) => event.result }) },\n          TOOL_ERROR: 'failed',\n        },\n      },\n      done: { type: 'final' },\n      failed: { type: 'final' },\n    },\n    output: ({ context }) => ({ text: context.text }),\n  });\n\nExample — handling a denied approval:\n\n  import { setup, assign } from 'xstate';\n  import { toolCall } from '@astral-mcp/tools';\n\n  export default setup({}).createMachine({\n    id: 'writeNotes',\n    context: { status: 'pending' },\n    initial: 'writing',\n    states: {\n      writing: {\n        entry: toolCall('write_file', () => ({ path: '/notes.txt', content: 'hello' })),\n        on: {\n          TOOL_RESULT: { target: 'done', actions: assign({ status: 'written' }) },\n          TOOL_DENIED: { target: 'done', actions: assign({ status: 'skipped' }) },\n          TOOL_ERROR: { target: 'done', actions: assign({ status: 'failed' }) },\n        },\n      },\n      done: { type: 'final' },\n    },\n    output: ({ context }) => ({ status: context.status }),\n  });\n";
+//#endregion
+export { APPROVAL_SCHEMA, AUTHORING_CONTRACT, ApprovalVerdict, AuditEntry, BLOB_SCHEMA_VERSION, BlobPayload, BlobSealerConfig, type CallToolResult, type ContentBlock, 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, 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, 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, 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 };
+//# sourceMappingURL=index.d.mts.map