@astral-mcp/projection 0.7.0 → 0.9.0

package/dist/index.d.mts

@@ -1,7 +1,142 @@
+import { Client } from "@modelcontextprotocol/client";
 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
+/**
+ * Token residence (PRD R59, S1): the {@link TokenStore} contract, its keys,
+ * the in-memory store, and the default store — the OS credential store
+ * through the optional native library `@napi-rs/keyring` (macOS Keychain,
+ * Linux Secret Service, Windows Credential Manager), with an in-memory
+ * fallback.
+ *
+ * A store holds opaque strings. What Projection stores under a `tokens:`
+ * key is its own serialization of a token set (`token-record.ts`); a store
+ * never parses it.
+ *
+ * Nothing in this module logs, rethrows or embeds a stored value or an
+ * error from the keyring library: a store failure is reported in fixed
+ * library copy.
+ */
+/**
+ * Where upstream credentials live (R59). `WrapOptions.tokenStore` replaces
+ * the default OS-credential-store one; a horizontally scaled deployment
+ * supplies a shared store (R27).
+ *
+ * Keys and values are opaque strings. A key is `<kind>:<JSON array>`; the
+ * kind before the first `:` says what the value is, so a store can route
+ * or label entries without parsing anything else:
+ *
+ * - `tokens:["<canonical resource URL>","<client id>","<principal>"]` — a
+ *   token set ({@link tokenStoreKey});
+ * - `registration:…` — reserved for dynamic client registrations (phase 1b).
+ *
+ * Values are Projection's serialization (ASCII JSON) and must be returned
+ * byte for byte.
+ *
+ * - `get` returns the value stored under `key`, or `undefined`.
+ * - `set` replaces it.
+ * - `delete` removes it and reports whether it removed anything. With
+ *   `expected`, it is a compare-and-delete (R58): it deletes only when the
+ *   stored value is still exactly `expected`, so a value another process
+ *   has just stored survives.
+ *
+ * Implementations must never log or surface a value.
+ */
+interface TokenStore {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string, expected?: string): Promise<boolean>;
+}
+/**
+ * The process-local store: the fallback, and what tests and single-process
+ * deployments that want no persistence can pass as `tokenStore`.
+ */
+export declare class MemoryTokenStore implements TokenStore {
+  #private;
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string, expected?: string): Promise<boolean>;
+}
+/**
+ * Upstream sources given by URL (PRD §6.10, R51, R60): the `UpstreamSpec`
+ * shape, how it is told apart from the other source kinds, and its
+ * validation and canonical form.
+ *
+ * Every mistake here is a `validate` {@link ProjectionError} raised at wrap
+ * time, before anything connects (R39's rule). Messages never echo a value
+ * that could be a secret: the client secret is never quoted, and a URL is
+ * quoted only after it parsed without userinfo.
+ */
+/**
+ * OAuth settings of an {@link UpstreamSpec} (R51, R52, R53, R61). Phase 1
+ * needs a client the integrator registered beforehand: `clientId`, and a
+ * discouraged `clientSecret`. `clientMetadataUrl` and
+ * `authorizationEndpoint` arrive with phase 1b and are `validate` errors
+ * until then.
+ */
+interface UpstreamOAuthOptions {
+  /** The OAuth client id the integrator registered with the server's authorization server (R52). */
+  clientId: string;
+  /** Client secret for a confidential client. Discouraged: the device flow needs none (R52). */
+  clientSecret?: string;
+  /** Scopes to request, replacing the SDK's selection from metadata (R53). */
+  scopes?: string[];
+  /**
+   * Extra hosts the user may be sent to for sign-in, beyond the
+   * authorization server's own (R61). Bare lowercase ASCII hostnames, not IP addresses.
+   */
+  signInHosts?: string[];
+  /** Token endpoint override for servers with incomplete metadata (R53). `https:` only. */
+  tokenEndpoint?: string;
+  /** Device authorization endpoint override (R53). `https:` only. */
+  deviceAuthorizationEndpoint?: string;
+}
+/**
+ * A remote MCP server given by its URL (R51). Projection builds the
+ * Streamable HTTP transport itself, installs its own OAuth client provider
+ * on it, owns the resulting connection and closes it in `close()`.
+ */
+interface UpstreamSpec {
+  /** The server's Streamable HTTP endpoint. `https:`, or `http:` on a loopback host. */
+  url: string | URL;
+  oauth?: UpstreamOAuthOptions;
+}
+/** A validated {@link UpstreamOAuthOptions}, frozen at wrap time. */
+interface ResolvedOAuth {
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly scopes?: readonly string[];
+  readonly signInHosts?: readonly string[];
+  readonly tokenEndpoint?: string;
+  readonly deviceAuthorizationEndpoint?: string;
+}
+/** A validated {@link UpstreamSpec}. */
+interface ResolvedUpstream {
+  /** The parsed URL the transport connects to. */
+  readonly url: URL;
+  /** The canonical URL (R51): the resource's identity, token-store key and blob binding. */
+  readonly canonicalUrl: string;
+  /** The R60 per-server identity, `url:<canonical url>`. */
+  readonly identity: string;
+  /** The URL's hostname as the parser gives it (ASCII, punycode for IDNs). */
+  readonly host: string;
+  readonly oauth?: ResolvedOAuth;
+}
+/**
+ * Why an upstream auth step failed, in library terms:
+ *
+ * - `sign_in_required`: no usable token (none stored, none that refreshes).
+ * - `no_client`: the server requires sign-in and no `oauth.clientId` is configured (R52).
+ * - `insufficient_scope`: the granted scopes do not cover the request (R58).
+ * - `refresh_failed`: a refresh could not complete for a transient reason
+ *   (a 5xx, a malformed response, a network failure); the stored record is kept.
+ * - `client_rejected`: the authorization server refused the OAuth client
+ *   (`invalid_client` / `unauthorized_client`); the stored record is kept.
+ * - `insecure_endpoint`: an authorization-server endpoint is not `https:` (R61).
+ * - `oauth_error`: the authorization server refused (its `error` code, when valid, rides along).
+ * - `token_store`: the token store failed.
+ * - `failed`: anything else in the auth machinery (invalid metadata, for example).
+ */
+type UpstreamAuthReason = 'sign_in_required' | 'no_client' | 'insufficient_scope' | 'refresh_failed' | 'client_rejected' | 'insecure_endpoint' | 'oauth_error' | 'token_store' | 'failed';
 /**
  * Shared core types for Projection.
  *
@@ -11,16 +146,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 +165,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;
@@ -50,7 +185,7 @@ interface ServerCatalog {
  * 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;
+export declare function findTool(catalog: ServerCatalog, name: string): ToolCatalogEntry | undefined;
 /**
  * Drop tools whose name repeats an earlier one; the first occurrence wins.
  *
@@ -58,30 +193,173 @@ declare function findTool(catalog: ServerCatalog, name: string): ToolCatalogEntr
  * catalog projection), so they all agree with {@link findTool} on which
  * entry a name denotes (S5).
  */
-declare function dedupeTools(tools: ToolCatalogEntry[]): ToolCatalogEntry[];
+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>;
+/** A plain object (prototype `Object.prototype` or `null`): what a configuration value must be. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * One wrapped-server progress report (MCP `notifications/progress`), as the
+ * upstream sent it: `message` is server-authored text (S5), not yet
+ * neutralized.
+ */
+export interface UpstreamProgress {
+  progress: number;
+  total?: number;
+  message?: string;
+}
+/**
+ * Host-side options for one upstream call: never model-authored. `signal`
+ * cancels the upstream request (MCP `notifications/cancelled`) when the
+ * facade's own request is cancelled; `onProgress` receives the upstream's
+ * progress reports, and its presence asks the upstream for them.
+ */
+export interface UpstreamCallOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: UpstreamProgress) => void;
+  /**
+   * Re-issue a call whose upstream asked for input (G1, DECISIONS D24): the
+   * answers keyed by the upstream's own keys, and the upstream's own
+   * `requestState` echoed verbatim. Read only from a verified blob and the
+   * human's responses, never from tool arguments.
+   */
+  input?: UpstreamInputResume;
+}
+/**
+ * What a wrapped server asked for when its tool answered `input_required`
+ * (MCP 2026-07-28 MRTR), as received: untrusted server data (S5), not yet
+ * sanitized. Present only for a box that forwards upstream elicitation.
+ */
+export interface UpstreamInputRequest {
+  /** The upstream's embedded requests, keyed by its own keys. */
+  requests: Record<string, unknown>;
+  /** The upstream's opaque state, to be echoed back verbatim. */
+  requestState?: string;
+}
+/**
+ * Whether a box passes its server's own questions (MCP elicitation, form or
+ * URL mode) on to the human (G1, DECISIONS D24). `'refuse'` (the default)
+ * declares no elicitation capability to the server, and a question fails the
+ * call with a result that says so. `'forward'` declares the capability and
+ * relays each question over MRTR, attributed to the box and never shaped
+ * like an approval. Sampling and roots are never forwarded.
+ */
+export type UpstreamElicitationMode = 'forward' | 'refuse';
+/** The answers and state that re-issue a call whose upstream asked for input. */
+export interface UpstreamInputResume {
+  /** Bare `ElicitResult`s keyed by the upstream's own request keys. */
+  responses: Record<string, unknown>;
+  requestState?: string;
+}
 /** 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>;
+export interface ToolExecutor {
+  callTool(alias: ServerAlias, name: string, args: Record<string, unknown>, options?: UpstreamCallOptions): Promise<ToolCallOutcome>;
 }
-type ToolCallOutcome = {
+export type ToolCallOutcome = {
   ok: true;
   result: unknown;
+  /**
+   * Set when `result` is the upstream's raw `content` array (no
+   * `structuredContent`, not a single text block), so a renderer can
+   * tell content blocks from structured data that happens to be an
+   * array.
+   */
+  rawContent?: true;
+  /**
+   * Short text the server sent beside its `structuredContent` that is
+   * not a JSON mirror of it (a warning such as "returning 10 of 40"),
+   * raw but redacted like the result (S1). Shown to the model only as
+   * a neutralized, quoted result note (D29, `catalog/result-notes.ts`).
+   */
+  serverNote?: string;
 } | {
   ok: false;
   error: {
     message: string;
     detail?: unknown;
   };
+  /**
+   * Set when the call failed because upstream authorization failed (a
+   * source given by URL, R51): `call_tool` reports it in the R25 `auth`
+   * phase with this library-copy hint, not as an `upstream` failure.
+   */
+  auth?: {
+    hint: string;
+  };
+  /**
+   * The upstream asked the user for input and its box forwards upstream
+   * elicitation (G1): the gated entry points turn this into their own
+   * `input_required`. A consumer that does not handle it sees an
+   * ordinary failure, so nothing is ever forwarded by accident.
+   */
+  upstreamInput?: UpstreamInputRequest;
+  /**
+   * The upstream asked the user for input that is not forwarded (its
+   * box refuses upstream elicitation, or it asked for sampling or
+   * roots). `error.message` says so; the arguments were not the problem.
+   */
+  inputRefused?: true;
 };
-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;
 }
+/**
+ * Approvals mode (R49). `'every-write'` (the default) asks before every tool
+ * that is not read-only; `'destructive-only'` also lets a non-read-only tool
+ * run without approval when its annotations declare `destructiveHint: false`
+ * exactly. That extends the trust placed in `readOnlyHint` to
+ * `destructiveHint: false` (S5): enable it only for servers you trust.
+ */
+export type ApprovalsMode = 'every-write' | 'destructive-only';
+/**
+ * Everything a policy decision reads besides the tool itself (R14, R49):
+ * the per-tool overrides and the resolved approvals mode, both frozen at
+ * wrap time. Every surface decides through `decidePolicy` with one of these
+ * (build it with `policyContext`), so the posture a model is shown is the
+ * decision the gate makes.
+ *
+ * `approvals` is required — the context is *resolved* — so a bare
+ * {@link PolicyOverrides} object cannot be passed where a context is
+ * expected and silently lose its overrides. A multi-server facade adds its
+ * per-source modes as `toolApprovals`, resolved per qualified tool (they
+ * take precedence over `approvals`, R49), without changing `decidePolicy`'s
+ * signature.
+ */
+export interface PolicyContext {
+  /** Per-tool overrides (R14); an override always wins. */
+  overrides?: PolicyOverrides | undefined;
+  /** The approvals mode (R49) that applies when no override does. */
+  approvals: ApprovalsMode;
+  /**
+   * A multi-server facade's per-source approvals modes (R49), resolved at
+   * wrap time to one entry per qualified tool name (`fs.write_file`) from
+   * the boxed view's members — so the box is never re-derived by splitting
+   * a name. A tool with an entry decides with that mode instead of
+   * `approvals`. Absent on single-server facades.
+   */
+  toolApprovals?: ReadonlyMap<string, ApprovalsMode> | undefined;
+}
+/**
+ * The policy options every deciding surface takes (R14, R49) — the gate
+ * deps, `searchTools`, `describeTool`, the machine host and typegen — in one
+ * shape, turned into a {@link PolicyContext} by `policyContext`. Absent
+ * options mean no overrides and `'every-write'`.
+ */
+export interface PolicyOptions {
+  /** Per-tool policy overrides (R14). */
+  policy?: PolicyOverrides | undefined;
+  /** Approvals mode (R49), decided with `policy`. */
+  approvals?: ApprovalsMode | undefined;
+  /**
+   * Per-source approvals modes of a multi-server facade, resolved per
+   * qualified tool name (R49; see {@link PolicyContext.toolApprovals}).
+   */
+  toolApprovals?: ReadonlyMap<string, ApprovalsMode> | undefined;
+}
 /** 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;
@@ -90,13 +368,23 @@ 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;
+  /** The call's own arguments — as sealed, for an approved call (S2). */
+  args: Record<string, unknown>;
   result: unknown;
+  /**
+   * The upstream's text, when `result` is that text parsed: a single
+   * text block holding JSON for an object or an array (D29).
+   */
+  text?: string;
+  /** The facade's notes on the result (R35.6, D29); absent when there are none. */
+  notes?: string[];
 } | {
   type: 'TOOL_ERROR';
   callId: string;
+  args: Record<string, unknown>;
   error: {
     message: string;
     detail?: unknown;
@@ -104,18 +392,24 @@ type HostEvent = {
 } | {
   type: 'TOOL_DENIED';
   callId: string;
+  args: Record<string, unknown>;
   reason?: string;
 };
-type ErrorPhase = 'transpile' | 'validate' | 'runtime' | 'cap_exceeded' | 'blob_verification' | 'protocol' |
+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';
-interface Diagnostic {
+'upstream' |
+/**
+ * An upstream sign-in is required or could not complete (R25, R57):
+ * library copy only, plus at most the OAuth `error` code.
+ */
+'auth' | '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[];
@@ -123,8 +417,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. */
@@ -132,7 +426,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. */
@@ -154,14 +448,19 @@ 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;
-/** Which tool minted a blob (R36): a blob opened by the other tool is rejected. */
-type BlobKind = 'machine' | 'call';
-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. `upstream_input` is minted by `call_tool` when the wrapped
+ * tool's own server asked the human a question (G1, D24); `call_tool`
+ * opens both of its kinds.
+ */
+export type BlobKind = 'machine' | 'call' | 'upstream_input';
+export interface BlobPayload {
   /** Blob schema version; unknown versions are rejected. */
   v: number;
   /** Minting tool (R36). */
@@ -190,8 +489,27 @@ interface BlobPayload {
    * of its final segment.
    */
   audit: AuditEntry[];
+  /**
+   * How this suspension was put to the person (R15): present, and
+   * `'batched'`, only when it was one batched elicitation; absent means
+   * one elicitation per pending call. Sealed so the resume answers the
+   * prompt that was actually shown, whatever the resuming instance's
+   * option (D25). Only on `machine` blobs with two or more pending calls;
+   * never on `call` or `upstream_input` blobs (both minted by `call_tool`,
+   * which never batches).
+   */
+  prompts?: 'batched';
   /** Round-trip counter (R18). */
   trip: number;
+  /**
+   * Calls that already ran under the gate and are waiting on their own
+   * server's question (G1, D24), keyed by call id: the call, how it was
+   * authorized, the server's sealed `requestState`, and the questions.
+   * Never part of `pending` (S2): an answer re-issues the recorded call
+   * and approves nothing. Exactly one entry keyed `call` for an
+   * `upstream_input` blob; absent from `call` blobs.
+   */
+  upstreamInput?: Record<string, UpstreamHold>;
   /** Random nonce for replay scoping. */
   nonce: string;
   /** Issued-at, Unix ms. */
@@ -199,7 +517,39 @@ interface BlobPayload {
   /** Expiry, Unix ms (default TTL 15 min). */
   exp: number;
 }
-interface BlobSealerConfig {
+/** A sanitized MCP elicitation schema: a flat object of primitive fields (G1). */
+export interface ElicitationSchema {
+  type: 'object';
+  properties: Record<string, Record<string, unknown>>;
+  required?: string[];
+}
+/** One forwarded question as sealed: enough to map and check the answer (G1). */
+export interface ForwardedQuestion {
+  /** The server's own key for this request. */
+  key: string;
+  /**
+   * `form`: the human filled the sanitized form in `schema`. `url`: the
+   * human was shown a link (as URL mode, or as a form with the link as inert
+   * text when the client cannot open links); accepting sends no content.
+   */
+  mode: 'form' | 'url';
+  /** The sanitized schema the human answered (`form` only). */
+  schema?: ElicitationSchema;
+}
+/**
+ * A call that ran under the gate and is waiting on its server's question
+ * (G1, D24), sealed in the blob's `upstreamInput` — never in the S2
+ * `pending` map: an answer re-issues the recorded call, it approves nothing.
+ */
+export interface UpstreamHold extends PendingToolCall {
+  /** How the call was authorized when it first ran. */
+  decision: 'auto' | 'approved';
+  /** The server's own opaque state, echoed verbatim on the re-issue. */
+  requestState?: string;
+  /** The questions, keyed by the facade's keys. */
+  questions: Record<string, ForwardedQuestion>;
+}
+export interface BlobSealerConfig {
   /** Current encryption key (32 bytes). */
   key: Uint8Array;
   /** Previous keys accepted for decryption during rotation (R22). */
@@ -221,7 +571,7 @@ interface BlobSealerConfig {
  * blob kinds. No default ships: an in-memory one would silently break
  * horizontal scaling (G4), so the integrator supplies a shared store.
  */
-interface ReplayCache {
+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.
@@ -237,24 +587,37 @@ interface ReplayCache {
   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 = {
+/** Most result notes a completed segment reports (D29). */
+export declare const MAX_SEGMENT_NOTES = 10;
+export type SegmentOutcome = {
   status: 'completed';
   /** Final machine output/context to return to the client. */
   output: unknown;
   /** Per-call approval audit trail. */
   audit: AuditEntry[];
   logs: LogEntry[];
+  /**
+   * The result notes of this segment's tool calls (R35.6, D29), each
+   * prefixed with its tool's name, at most {@link MAX_SEGMENT_NOTES};
+   * absent when there are none.
+   */
+  notes?: string[];
 } | {
   status: 'suspended';
   /** Gated calls awaiting approval, keyed by inputRequest key. */
   pending: Record<string, PendingToolCall>;
+  /**
+   * Calls that ran and whose server asked the human a question (G1):
+   * the adapter forwards each question and seals the hold.
+   */
+  held: HeldCall[];
   /** Actor snapshot to seal into the blob. */
   snapshot: unknown;
   trip: number;
@@ -263,22 +626,36 @@ type SegmentOutcome = {
 } | {
   status: 'error';
   error: StructuredError;
+  /**
+   * The workflow's audit trail up to the failure (earlier segments'
+   * included), so the result can say which approved calls already ran
+   * and which were refused. Absent when nothing was audited.
+   */
+  audit?: AuditEntry[];
 };
-interface AuditEntry {
+/** A call whose server answered `input_required` on a box that forwards (G1). */
+export interface HeldCall {
+  call: PendingToolCall;
+  decision: 'auto' | 'approved';
+  input: UpstreamInputRequest;
+}
+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.
+   * (R16). Receives the tool name — qualified (`<alias>.<tool>`) on a
+   * multi-server facade — and a copy of the 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). */
@@ -293,21 +670,111 @@ interface ProjectionConfig {
    */
   codeModePreamble?: string;
 }
-//#endregion
-//#region src/blob/sealer.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;
+/**
+ * An upstream auth failure of a source given by URL (R25 `auth`, R57):
+ * library copy naming the source, plus at most the OAuth `error` code; the
+ * typed {@link reason} is what callers branch on (just-in-time sign-in
+ * re-locks a box on it).
+ */
+declare class UpstreamAuthProjectionError extends ProjectionError {
+  readonly reason: UpstreamAuthReason;
+  readonly oauthCode?: string;
+  constructor(reason: UpstreamAuthReason, oauthCode: string | undefined, message: string, hint: string);
+}
+/**
+ * One `UpstreamSpec` source, validated and bound to its token store. The
+ * introspector opens it like any other source; Projection owns the client.
+ */
+declare class UpstreamConnector {
+  #private;
+  readonly upstream: ResolvedUpstream;
+  /** How messages name the source: `source "github"`, or `the wrapped server`. */
+  readonly label: string;
+  constructor(upstream: ResolvedUpstream, store: TokenStore, label: string);
+  /** The R60 identity, `url:<canonical url>`. */
+  get identity(): string;
+  /** The source and its host, for messages: `source "github" (api.github.com)`. */
+  get where(): string;
+  /**
+   * Connect (R51): Streamable HTTP with Projection's auth provider and
+   * guarded fetch, `onInsufficientScope: 'throw'` and the SDK's default
+   * `redirectPolicy` (never `'follow'`, R58, R61). Aborting `signal` closes
+   * the half-open connection. Any failure is {@link toError}'s.
+   */
+  open(signal?: AbortSignal, options?: {
+    forwardElicitation?: boolean;
+  }): Promise<Client>;
+  /** `text` from this source, inert, with every credential it presented redacted, and bounded. */
+  redactText(text: string): string;
+  /**
+   * `value` from this source with every credential it presented redacted.
+   * Throws a {@link ProjectionError} when the value cannot be checked (fail
+   * closed, `SecretSet.scrubValue`).
+   */
+  redact<T>(value: T): T;
+  /**
+   * Abort every auth request this connection's runs have in flight (a
+   * refresh, its discovery), so a facade that closes leaves no refresh
+   * behind for another facade over the same store to wait on.
+   */
+  close(): void;
+  /** The typed `auth` error for `err`, when it is an upstream auth failure. */
+  authFailure(err: unknown): UpstreamAuthProjectionError | undefined;
+  /**
+   * Any failure to connect to or introspect this source, as a
+   * {@link ProjectionError}: an auth failure as the typed `auth` error; a
+   * refused request in fixed copy; anything else a `protocol` error (R47)
+   * whose text is redacted and bounded — never the raw error, whose
+   * message, data or cause may quote a server body that echoes the token.
+   */
+  toError(err: unknown): ProjectionError;
+  /** A tool call to this source that threw, as the outcome `call_tool` and a machine see (R25). */
+  callFailure(name: string, err: unknown): Extract<ToolCallOutcome, {
+    ok: false;
+  }>;
+  /**
+   * Delete the stored tokens of this source (R59). No revocation yet (phase
+   * 1b). A store that cannot delete is an `auth` error: a sign-out must not
+   * silently leave the token behind.
+   */
+  signOut(): Promise<void>;
+}
 /** Envelope format version prefix. Bump (proj2, …) on any wire-format change. */
-declare const ENVELOPE_PREFIX = "proj1";
+export declare const ENVELOPE_PREFIX = "proj1";
 /** Default blob TTL for `machine` blobs: 15 minutes (R20). */
-declare const DEFAULT_TTL_MS: number;
+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).
  */
-declare const DEFAULT_CALL_TTL_MS: number;
+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;
+/**
+ * Which facade kind a blob belongs to (R41): `single` for `wrapMcpServer`,
+ * `multi` for `wrapMcpServers`. Selects the HKDF info string; nothing else.
+ */
+type BlobKeyDomain = 'single' | 'multi';
 /** 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 {
   /** Minting tool (R36). Default `machine`. */
   kind?: BlobKind | undefined;
@@ -324,10 +791,20 @@ interface BuildBlobPayloadInput {
   pending: Record<string, PendingToolCall>;
   /** Approval audit accumulated so far in this workflow (PRD §8). */
   audit?: AuditEntry[] | undefined;
+  /** `'batched'` when the suspension was one batched prompt (R15, D25). */
+  prompts?: 'batched' | undefined;
   /** Round-trip counter (R18). */
   trip: number;
+  /** Calls waiting on their own server's question (G1); see `BlobPayload.upstreamInput`. */
+  upstreamInput?: Record<string, UpstreamHold> | undefined;
   /** Blob TTL in ms. Default {@link DEFAULT_TTL_MS} (15 minutes). */
   ttlMs?: number | undefined;
+  /**
+   * Latest allowed `exp`, Unix ms: the blob expires at `iat + ttlMs` or this,
+   * whichever is earlier. A blob minted to continue an earlier one carries
+   * that blob's `exp` here, so a chain of round trips never extends it (R38).
+   */
+  notAfter?: number | undefined;
   /** Clock override for testability, Unix ms. Default `Date.now()`. */
   now?: number | undefined;
 }
@@ -335,19 +812,23 @@ 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).
  *
  * 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.
+ * keys are malformed. `domain` selects the facade kind's key domain (R41);
+ * it defaults to `single`, the only domain before multi-server facades.
  */
-declare function sealBlob(payload: BlobPayload, config: BlobSealerConfig): string;
+export declare function sealBlob(payload: BlobPayload, config: BlobSealerConfig, domain?: BlobKeyDomain): string;
 interface OpenBlobOptions {
-  /** The tool opening the blob (R36). Default `machine`. */
-  expectedKind?: BlobKind | undefined;
+  /**
+   * The kind(s) the opening tool accepts (R36). Default `machine`.
+   * `call_tool` opens `call` and `upstream_input` blobs.
+   */
+  expectedKind?: BlobKind | readonly BlobKind[] | undefined;
   /**
    * The text re-sent with the retry (S4): the `code` argument for
    * `execute_machine`, the canonical request for `call_tool`.
@@ -356,6 +837,11 @@ interface OpenBlobOptions {
   /** Identity of the wrapped server handling the retry (R30). */
   serverIdentity: string;
   config: BlobSealerConfig;
+  /**
+   * Key domain of the facade opening the blob (R41). Default `single`. A
+   * blob sealed in the other domain fails authentication.
+   */
+  domain?: BlobKeyDomain | undefined;
   /** Clock override for testability, Unix ms. Default `Date.now()`. */
   now?: number | undefined;
 }
@@ -374,9 +860,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;
-//#endregion
-//#region src/blob/versions.d.ts
+export declare function openBlob(blob: string, options: OpenBlobOptions): BlobPayload;
 /**
  * Version constants recorded into every blob (R20) and strict-matched on
  * open (R21, Q3: no migration — mismatches are rejected).
@@ -389,11 +873,175 @@ 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.7.0";
+export declare const LIB_VERSION = "0.9.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
+export declare const XSTATE_VERSION = "5.32.5";
+/**
+ * Decide the policy for a catalog tool (R14, R49). Precedence, strongest
+ * first:
+ *
+ * 1. A developer override (`auto` | `ask` | `deny`) always wins. An override
+ *    entry with an unrecognized value (possible when the config arrives
+ *    untyped) fails safe to `ask` — it never grants `auto`.
+ * 2. `annotations.readOnlyHint === true` yields `auto` in every mode.
+ * 3. Under `approvals: 'destructive-only'`, a tool whose annotations declare
+ *    `destructiveHint === false` exactly yields `auto`; a missing hint or any
+ *    other value still asks (the MCP default reads a non-read-only tool as
+ *    destructive).
+ * 4. Otherwise `ask` (S5: unannotated defaults to ask).
+ *
+ * A context whose `approvals` is not one of the two modes throws a
+ * `TypeError` — fail closed, never decide on a malformed context (the wrap
+ * rejects malformed modes up front with a `validate` error — see
+ * {@link assertApprovalsMode}).
+ *
+ * Only own properties of `context.overrides` and of `entry.annotations` are
+ * consulted, so tools named like `Object.prototype` members (`toString`,
+ * `constructor`, ...) cannot pick up inherited junk as a decision, and an
+ * annotations object cannot inherit a relaxing hint from its prototype.
+ */
+export declare function decidePolicy(entry: ToolCatalogEntry, context?: PolicyContext): PolicyDecision;
+/**
+ * Build the {@link PolicyContext} for a set of {@link PolicyOptions} — the
+ * per-tool `policy` overrides (R14), the `approvals` mode and a multi-server
+ * facade's per-tool `toolApprovals` (R49), the shape the gate deps, the
+ * catalog tools, the machine host and typegen all take. An absent mode
+ * resolves to `'every-write'`.
+ */
+export declare function policyContext(options?: PolicyOptions): PolicyContext;
+/**
+ * Validate an `approvals` option (R49): absent, or one of the two modes. A
+ * malformed value is a `validate`-phase {@link ProjectionError} — the mode
+ * is one deploy-time switch, so a typo fails the wrap instead of silently
+ * changing who gets asked (DECISIONS D17). `wrapMcpServer` calls it; call
+ * it yourself when passing `approvals` to `executeMachine` or
+ * `generateToolTypes` directly.
+ */
+export declare function assertApprovalsMode(value: unknown): ApprovalsMode | undefined;
+/** 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, context?: PolicyContext): 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;
+/** 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; qualified with `box` when given. */
+  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';
+  /**
+   * Multi-server facades (R40, R46): the alias of the box the tool lives
+   * in. `entry` is then the box's own catalog entry (bare name) and the
+   * call's name is qualified. The copy names the box (R46): the title reads
+   * `Approve (fs): …` (`⚠ Approve (fs): …` when destructive), the purpose
+   * line `What fs says it does: "…"` — always rendered, `(no description)`
+   * when the server gives none — and the footer `Tool: fs.write_file`, or
+   * `Tool: fs › "github.delete_repo"` when the bare name has a dot, so it
+   * never reads as another box's tool. The redaction hook receives the
+   * qualified name. The alias is the host's, never a server-reported name
+   * (S6).
+   */
+  box?: string;
+  /**
+   * 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;
+/**
+ * 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); `allowTab`
+ * also keeps `\t`, for text printed verbatim between fences (D35), where a
+ * tab is the text's own (a Makefile recipe, a TSV row) and cannot start a
+ * line. `allowTab` takes effect only with `allowNewline`.
+ */
+export declare function neutralizeControlChars(text: string, options?: {
+  allowNewline?: boolean;
+  allowTab?: 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;
 /**
  * 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
@@ -427,7 +1075,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.
  *
@@ -438,7 +1086,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).
  *
@@ -449,9 +1097,13 @@ 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;
-//#endregion
-//#region src/mrtr/adapter.d.ts
+export declare function supportsMrtr(era: ProtocolEra$1 | undefined): boolean;
+/** How a suspension with several gated calls is put to the person. */
+type ApprovalPrompts = 'per-call' | 'batched';
+/** The single inputRequests key of a batched prompt (reserved namespace). */
+export declare const BATCH_KEY = "projection:approvals";
+/** The boolean field that carries the verdict of the call at 0-based position `i`. */
+export declare function batchField(i: number): string;
 /**
  * `execute_machine` arguments plus the MRTR retry envelope.
  *
@@ -476,12 +1128,18 @@ interface ExecuteMachineArgs extends RetryEnvelope {
  * protocol-era and replay settings. `execute_machine` adds the sandbox
  * bridge; `call_tool` needs nothing more (R35, R38).
  */
-interface ApprovalGateDeps {
+interface ApprovalGateDeps extends PolicyOptions {
   catalog: ServerCatalog;
   executor: ToolExecutor;
   blob: BlobSealerConfig;
+  /**
+   * The key domain of the facade kind serving this gate (R41): `single` for
+   * `wrapMcpServer`, `multi` for `wrapMcpServers`. Checked against the
+   * catalog, failing closed on a mismatch (`blobKeyDomain`). Omitted, it is
+   * derived from the catalog alone.
+   */
+  blobDomain?: BlobKeyDomain;
   caps?: Partial<ResourceCaps>;
-  policy?: PolicyOverrides;
   redact?: RedactionHook;
   /**
    * Protocol era this request is being served on, for down-negotiation
@@ -510,8 +1168,21 @@ interface ApprovalGateDeps {
    * not know) leaves the shim to decide.
    */
   clientCanElicit?: boolean;
+  /**
+   * Whether the connected client declared URL-mode elicitation. A forwarded
+   * server question that is a link (G1) is sent in URL mode only then;
+   * otherwise the link is shown as inert text in a form.
+   */
+  clientUrlElicitation?: boolean;
   /** Optional shared replay cache (R38); consulted after verification, before execution. */
   replayCache?: ReplayCache;
+  /**
+   * How a suspension holding several gated calls is put to the person
+   * (`WrapOptions.approvalPrompts`, batch.ts): one elicitation per call
+   * (default) or one batched elicitation for all of them. Only machine
+   * suspensions can hold several; a `call_tool` suspension holds one.
+   */
+  approvalPrompts?: ApprovalPrompts;
 }
 interface ExecuteMachineDeps extends ApprovalGateDeps {
   /** The `@astral-mcp/tools` bridge module source the sandbox loads (R2). */
@@ -524,11 +1195,9 @@ interface ExecuteMachineDeps extends ApprovalGateDeps {
  * 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). */
-declare function errorResult(error: StructuredError): CallToolResult;
-//#endregion
-//#region src/catalog/call.d.ts
+export declare function errorResult(error: StructuredError): CallToolResult;
 /**
  * `call_tool` arguments plus the MRTR retry envelope.
  *
@@ -545,6 +1214,12 @@ interface CallToolArgs extends RetryEnvelope {
   name: string;
   /** Arguments for the tool; absent means `{}`. */
   args?: unknown;
+  /**
+   * Host-side options for the upstream call this request runs, if it runs
+   * one: the facade request's cancellation signal and a progress sink.
+   * Never populated from tool arguments.
+   */
+  upstream?: UpstreamCallOptions;
 }
 /** `call_tool` needs exactly the dependencies every gated tool shares (R35, R38). */
 type CallToolDeps = ApprovalGateDeps;
@@ -562,6 +1237,12 @@ type CallToolOutcome = {
   truncated?: true;
   /** Byte length of the full result's JSON, when truncated. */
   outputBytes?: number;
+  /**
+   * The facade's remarks on the result, when it looks partial or the
+   * server sent a note beside its structured result (R35.6, D29):
+   * single neutralized lines, at most three, printed under the head.
+   */
+  notes?: string[];
 } | {
   status: 'declined';
   tool: string;
@@ -572,11 +1253,9 @@ type CallToolOutcome = {
   reason: string;
 };
 /** The single inputRequest / pending key of a `call` blob (R36). */
-declare const CALL_KEY = "call";
+export declare const CALL_KEY = "call";
 /** Run `call_tool` for one `tools/call`, first attempt or MRTR retry. */
-declare function callTool(args: CallToolArgs, deps: CallToolDeps): Promise<ToolCallResult>;
-//#endregion
-//#region src/catalog/canonical.d.ts
+export declare function callTool(args: CallToolArgs, deps: CallToolDeps): Promise<ToolCallResult>;
 /**
  * Canonical JSON for the `call_tool` binding hash (PRD R36).
  *
@@ -598,11 +1277,9 @@ declare function callTool(args: CallToolArgs, deps: CallToolDeps): Promise<ToolC
  * by the blob's `pending` entry alone (R36, D9).
  */
 /** Canonical JSON text of a plain JSON value. Throws `validate` on non-JSON. */
-declare function canonicalJson(value: unknown): string;
+export declare function canonicalJson(value: unknown): string;
 /** The text a `call` blob is bound to (R36): `{ kind: "call", name, args }`. */
-declare function canonicalRequest(name: string, args: Record<string, unknown>): string;
-//#endregion
-//#region src/catalog/validate-args.d.ts
+export declare function canonicalRequest(name: string, args: Record<string, unknown>): string;
 /**
  * Structural argument validation for `call_tool` (PRD R35.1).
  *
@@ -610,7 +1287,8 @@ declare function canonicalRequest(name: string, args: Record<string, unknown>):
  * 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
+ * shape, and so the model gets a `validate` hint naming the property and
+ * showing the tool's call signature (D32). Full
  * JSON Schema validation would run twice — the wrapped server is the
  * authority — for nothing but a nicer error message (D9).
  *
@@ -618,14 +1296,12 @@ declare function canonicalRequest(name: string, args: Record<string, unknown>):
  * argument name is ordinary data (S5/S6).
  */
 /** Throws a `validate`-phase {@link ProjectionError} naming the offending property. */
-declare function validateArgsShape(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): void;
-//#endregion
-//#region src/typegen/generate.d.ts
+export declare function validateArgsShape(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>, caller?: 'call_tool' | 'toolCall'): void;
 /**
  * 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";
+export declare const TOOLS_MODULE_SPECIFIER = "@astral-mcp/tools";
 /**
  * Name of the global the sandbox host MUST inject before authored code runs.
  *
@@ -646,7 +1322,7 @@ declare const TOOLS_MODULE_SPECIFIER = "@astral-mcp/tools";
  * - 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";
+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). */
@@ -656,36 +1332,45 @@ interface GeneratedToolTypes {
   /** 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.
+   * Per-tool slice of `dts`, keyed by tool name (R34) — the qualified
+   * `<alias>.<name>` on a multi-server view (R45): the alias declarations
+   * and the `tools.<name>` (`tools.<alias>.<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`. */
+  /**
+   * `<Pascal>Input` alias name, unique within the `.d.ts` —
+   * `<alias>_<Pascal>Input` on a multi-server view (R45).
+   */
   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.
+   * to column 0 under a `// Member of the \`tools\` surface:` line
+   * (`// Member of tools.<alias>:` on a multi-server view, R45).
    */
   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.
+ * Accepts the full aliased {@link ToolCatalog} (exactly one server: R30's
+ * single-instance instantiation), a {@link ServerCatalog} directly, or the
+ * multi-server view of a `wrapMcpServers` facade, which gets one
+ * `tools.<alias>` object type per box and qualified names throughout (R45).
+ */
+export declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog, options?: GenerateToolTypesOptions): GeneratedToolTypes;
+/**
+ * The policy options (R14, R49) decide the posture wording in the doc
+ * comments and the overview.
  */
-declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog): GeneratedToolTypes;
-//#endregion
-//#region src/typegen/json-schema.d.ts
+type GenerateToolTypesOptions = PolicyOptions;
 /**
  * Convert a JSON Schema into TypeScript type text.
  *
@@ -693,63 +1378,23 @@ declare function generateToolTypes(catalog: ToolCatalog | ServerCatalog): Genera
  * @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;
+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.
  */
-declare function schemaRequiresArgs(schema: unknown): boolean;
-//#endregion
-//#region src/catalog/search.d.ts
-interface SearchToolsArgs {
-  /** Plain substring filter over name and description (case-insensitive). */
-  query?: string;
-  /** Opaque cursor from a previous page's `nextCursor`. */
-  cursor?: string;
-}
-interface SearchToolsOptions {
-  /** Per-tool policy overrides (R14); decides the rendered posture. */
-  policy?: PolicyOverrides;
-  /** Tools per page. Default {@link DEFAULT_SEARCH_PAGE_SIZE}, clamped to [1, 200]. */
-  pageSize?: number;
-}
-/** Page size — a transport bound, independent of the R37 inline threshold. */
-declare const DEFAULT_SEARCH_PAGE_SIZE = 50;
-/** `query` is capped (R33): it is matched as a plain substring, never a regex. */
-declare const MAX_QUERY_CHARS = 200;
-/** The three normative posture strings (R33) — models match on these. */
-type ToolPosture = 'runs immediately' | 'asks for approval' | 'blocked by policy';
-/** One entry of a `search_tools` page (R33). */
-interface ToolSummary {
-  name: string;
-  purpose: string;
-  posture: ToolPosture;
-  destructive: boolean;
-}
-interface SearchToolsPage {
-  tools: ToolSummary[];
-  /** Matching tools across all pages. */
-  total: number;
-  nextCursor?: string;
-}
-/** Map a policy decision to its plain-words posture (R33). */
-declare function postureOf(decision: PolicyDecision): ToolPosture;
-/** Summarize one catalog entry (R33). */
-declare function summarizeTool(entry: ToolCatalogEntry, policy?: PolicyOverrides): ToolSummary;
-/**
- * Run `search_tools`. Throws a `validate`-phase {@link ProjectionError} for a
- * malformed cursor, one issued for a different query, or one pointing past
- * the end of the results (R33).
- */
-declare function searchTools(catalog: ServerCatalog, args: SearchToolsArgs, options?: SearchToolsOptions): CallToolResult;
-//#endregion
-//#region src/catalog/describe.d.ts
+export declare function schemaRequiresArgs(schema: unknown): boolean;
 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;
+/** The policy options (R14, R49) decide the rendered posture. */
+interface DescribeToolOptions extends PolicyOptions {
   /** Per-tool generated types from typegen (R34). */
   toolTypes?: ReadonlyMap<string, ToolTypeText>;
 }
@@ -773,9 +1418,7 @@ interface ToolDescription {
  * Run `describe_tool`. Throws a `validate`-phase {@link ProjectionError}
  * when the wrapped server declares no such tool (R34).
  */
-declare function describeTool(catalog: ServerCatalog, args: DescribeToolArgs, options?: DescribeToolOptions): CallToolResult;
-//#endregion
-//#region src/catalog/schema-safety.d.ts
+export declare function describeTool(catalog: ServerCatalog, args: DescribeToolArgs, options?: DescribeToolOptions): CallToolResult;
 /**
  * JSON Schema sanitizer for `describe_tool` (PRD R34, S5).
  *
@@ -786,8 +1429,11 @@ declare function describeTool(catalog: ServerCatalog, args: DescribeToolArgs, op
  * 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;
+ *    survive; everything else (examples, comments, vendor keys) is dropped.
+ *    `default` survives only as a scalar the model can act on (a number, a
+ *    boolean, `null`, or a short plain string — {@link safeDefault}): an
+ *    omitted argument silently takes it, and a model that cannot see a
+ *    default page size reads a page as the whole set (D29);
  * 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
@@ -802,9 +1448,9 @@ declare function describeTool(catalog: ServerCatalog, args: DescribeToolArgs, op
  * Pure and total: never throws, never returns anything but plain JSON.
  */
 /** Keywords that survive sanitization (R34). */
-declare const SCHEMA_KEY_ALLOWLIST: ReadonlySet<string>;
+export declare const SCHEMA_KEY_ALLOWLIST: ReadonlySet<string>;
 /** Rendered-schema cap per tool, in characters of its JSON text (R34). */
-declare const MAX_SCHEMA_CHARS: number;
+export declare const MAX_SCHEMA_CHARS: number;
 interface SanitizedSchema {
   /** The sanitized schema, always a plain JSON object. */
   schema: Record<string, unknown>;
@@ -817,31 +1463,311 @@ interface SanitizedSchema {
  * Non-object input (a server declaring `inputSchema: true`, or garbage)
  * sanitizes to `{}`.
  */
-declare function sanitizeSchema(schema: unknown, maxChars?: number): SanitizedSchema;
-//#endregion
-//#region src/errors.d.ts
+export declare function sanitizeSchema(schema: unknown, maxChars?: number): SanitizedSchema;
 /**
- * Error carrying the structured `isError` body every failure returns (R25).
+ * Compact call signatures (DECISIONS D32): a tool's top-level arguments on
+ * one line, so a model can `call_tool` straight from a search hit or a
+ * `validate` error instead of spending a turn on `describe_tool`.
+ *
+ *   {owner: string, repo: string, state?: "open"|"closed", perPage?: number = 30}
+ *
+ * Required arguments first (in declaration order), then optional ones
+ * (`?`), each with its type: JSON Schema types, `T[]` for arrays, the
+ * literal members of an `enum` or `const`, and a scalar default (`= 30`)
+ * when the sanitizer kept one (D29). Only the top level is rendered: an
+ * object or array-of-objects argument shows as `object` / `object[]` and
+ * the signature says `describe_tool` has the full schema; so does one cut
+ * to fit {@link MAX_SIGNATURE_CHARS}.
+ *
+ * S5: built from the SANITIZED schema only ({@link sanitizeSchema}), so
+ * every enum string and default already passed the allowlist and the
+ * default rule. Property names stay server data: a name that is a plain
+ * identifier prints bare, any other is JSON-quoted after neutralization,
+ * and a name too long to print whole is left out (and the signature marked
+ * incomplete) rather than shown cut — a cut name is a wrong key. Type words
+ * outside the JSON Schema vocabulary print as `any`. The result is one
+ * line: nothing a server writes can open a line of its own.
  */
-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;
+/** A tool's compact call signature. */
+interface CallSignature {
+  /** One line: `{a: string, b?: number = 1}`; `{}` for a tool that takes no arguments. */
+  text: string;
+  /**
+   * True when the line shows the whole input schema's top level: no
+   * nested object fields, no argument cut for length, no enum cut short,
+   * no schema the sanitizer truncated. Copy otherwise says `describe_tool`
+   * has the full schema.
+   */
+  complete: boolean;
+  /**
+   * True when a call can be built from the line alone: the top level is a
+   * plain object of properties and every required argument is shown with
+   * a flat type. What is missing, if anything, is optional. Copy otherwise
+   * says to call `describe_tool` first.
+   */
+  callable: boolean;
 }
-/** Convert any thrown value into a StructuredError, defaulting to `runtime` phase. */
-declare function toStructuredError(err: unknown, logs?: LogEntry[]): StructuredError;
-//#endregion
-//#region src/mrtr/discover.d.ts
+/**
+ * Where optional arguments stop, in characters (required ones go on to
+ * twice this). Sized on the eval
+ * fixtures (D32): it keeps every argument of 93 of the 95 GitHub tools,
+ * all 21 MongoDB and all 14 filesystem tools; the cut ones say so.
+ */
+export declare const MAX_SIGNATURE_CHARS = 480;
+/**
+ * The compact signature of a tool's input schema; never throws. With
+ * `shared` (D34), a required argument the box's shared-args line already
+ * shows with the same type, and that has no default, is written by name
+ * alone (`{connectionId, database, newName: string}`): copy that renders
+ * this text must show that line on the same page. `complete` and
+ * `callable` are unchanged.
+ */
+export declare function callSignature(inputSchema: unknown, options?: {
+  shared?: readonly SharedArg[];
+}): CallSignature;
+/**
+ * One argument's meaning, from its description (D33): what a signature's
+ * `name: type` cannot say, such as where a `connectionId` comes from or
+ * that a `sha` may also be a branch name.
+ */
+interface ArgGloss {
+  /** The argument's name, as the schema declares it. */
+  name: string;
+  /** Its description on one line: whitespace collapsed, invisible characters gone, neutralized, capped. */
+  text: string;
+}
+/**
+ * Longest gloss on a search page, in characters, before `…`. Sized on the
+ * eval fixtures (D33): it holds the median informative GitHub description
+ * whole (48 characters) and keeps the instruction in the first sentences
+ * of a longer one (Sentry's median is 124, MongoDB's `connectionId` 173);
+ * past it are option lists and examples that `describe_tool` serves.
+ */
+export declare const MAX_GLOSS_CHARS = 120;
+/**
+ * The glosses of a tool's arguments (D33): by default its required ones (a
+ * call cannot go without them, and a model that cannot tell what one means
+ * invents a value), or the `names` given (the arguments a rejected call
+ * sent). An argument gets a gloss when the SANITIZED schema (S5) gives it a
+ * description that says something its name does not: one made only of
+ * filler words and words of the tool's or its arguments' names is skipped,
+ * and so is an `enum` or `const` argument, whose values the signature
+ * already lists (on the GitHub fixture its descriptions were a third of
+ * the gloss text and said "The method to execute" or listed the options
+ * again). Each gloss is one line cut at a word to `maxChars` (default
+ * {@link MAX_GLOSS_CHARS}), and a tool's glosses stop at twice that.
+ * Never throws.
+ */
+export declare function argGlosses(toolName: string, inputSchema: unknown, options?: {
+  names?: readonly string[];
+  maxChars?: number;
+}): ArgGloss[];
+/**
+ * A required argument most of a box's tools share (D34): `connectionId` in
+ * the MongoDB box, `owner` and `repo` in GitHub's.
+ */
+interface SharedArg {
+  /** The argument's name, as the schemas declare it. */
+  name: string;
+  /** Its type as a signature prints it, the same in every tool counted. */
+  type: string;
+  /** How many of the box's tools require it with that type. */
+  tools: number;
+  /** Its gloss (D33), when most of those tools give it the same one. */
+  gloss?: string;
+}
+/**
+ * Share of a box's tools that must require an argument (same name, same
+ * rendered type) for it to be shared (D34). Sized on the offline catalogs:
+ * the arguments that recur are required by 58–95 % of their box's tools
+ * (GitHub `repo` 58 %, `owner` 66 %; MongoDB `collection` 71 %, `database`
+ * 90 %, `connectionId` 95 %; filesystem `path` 79 %; Sentry
+ * `organizationSlug` 70 %; Slack `channel_id` 63 %), and the next ones by at
+ * most 25 % (Notion `page_id`, Slack `thread_ts`, GitHub `method` 16 %).
+ */
+export declare const SHARED_ARG_SHARE = 0.5;
+/** Fewest tools an argument is shared by: two tools agreeing is not a pattern. */
+export declare const MIN_SHARED_ARG_TOOLS = 3;
+/** Most shared arguments a box's line shows (MongoDB has three). */
+export declare const MAX_SHARED_ARGS = 4;
+/**
+ * The shared arguments of a box's tools (D34): required arguments, with a
+ * flat type (no nested shape, no cut enum) and no default, that at least
+ * {@link SHARED_ARG_SHARE} of `tools` (and {@link MIN_SHARED_ARG_TOOLS})
+ * require under the same name and the same rendered type; most shared
+ * first, then in order of first appearance, at most
+ * {@link MAX_SHARED_ARGS}. An argument whose name differs in type across
+ * tools counts only the tools of its most common type. Each carries the
+ * D33 gloss that at least half of the tools counted give it, if one does.
+ * Built from the sanitized schemas (S5). `tools` should be deduplicated by
+ * name. Never throws.
+ */
+export declare function sharedArgs(tools: readonly {
+  name: string;
+  inputSchema: unknown;
+}[]): SharedArg[];
+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;
+}
+/** The policy options (R14, R49) decide the rendered posture. */
+interface SearchToolsOptions extends PolicyOptions {
+  /**
+   * Tools per page, for listings and queries alike. Default {@link DEFAULT_SEARCH_PAGE_SIZE}
+   * for a listing (no query) and {@link DEFAULT_QUERY_PAGE_SIZE} for a
+   * query; clamped to [1, 200].
+   */
+  pageSize?: number;
+}
+/** Page size of a listing — a transport bound, independent of the R37 inline threshold. */
+export declare const DEFAULT_SEARCH_PAGE_SIZE = 50;
+/**
+ * Page size of a ranked (queried) search (D32). On the offline search
+ * corpus (1,173 cases, D22) the gold tool is in the top 15 in 96.6 % of
+ * cases and in the top 50 in 97.7 %, while every row past the 15th costs
+ * about 30 tokens on every search that has it: "create issue" in the
+ * GitHub box matched 25. The rest stay a cursor away.
+ */
+export declare const DEFAULT_QUERY_PAGE_SIZE = 15;
+/**
+ * How many of a query's best hits carry their call signature (D32). On the
+ * offline corpus the gold tool ranks 1st in 75.5 % of cases, top 3 in
+ * 89.9 % (93.4 % of the queries models actually sent) and top 5 in 92.8 %:
+ * the 4th and 5th signatures would buy 2.9 points for two more lines on
+ * every search. A signature's optional arguments are cut at 480
+ * characters (`MAX_SIGNATURE_CHARS`); over the GitHub tools the median is
+ * 109 (~27 tokens), so the three typically cost ~80 tokens, against
+ * ~800–1,400 for one `describe_tool` answer plus the turn that fetches it.
+ */
+export declare const SIGNATURE_HITS = 3;
+/**
+ * How many of a query's best hits also gloss their required arguments
+ * (D33): all of the signed ones. A page shows a gloss once; a later hit
+ * with the same argument and the same words leaves it out.
+ */
+export declare const GLOSS_HITS = 3;
+/** `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;
+  /**
+   * The tool's compact call signature (D32): on the first
+   * {@link SIGNATURE_HITS} hits of a query, unless the tool is blocked.
+   */
+  signature?: CallSignature;
+  /**
+   * What the tool's required arguments mean, where the name alone does not
+   * say (D33): on the first {@link GLOSS_HITS} signed hits, when any
+   * required argument has such a description.
+   */
+  glosses?: ArgGloss[];
+}
+interface SearchToolsPage {
+  tools: ToolSummary[];
+  /** Matching tools across all pages. */
+  total: number;
+  nextCursor?: string;
+}
+/**
+ * Summarize one catalog entry (R33); `context` decides its posture (R14,
+ * R49). With `withSignature`, a tool that is not blocked also carries its
+ * call signature (D32): there is no point showing how to call a tool the
+ * gate refuses. With `withGlosses` too, it carries its required
+ * arguments' glosses (D33), when it has any.
+ */
+export declare function summarizeTool(entry: ToolCatalogEntry, context?: PolicyContext, withSignature?: boolean, withGlosses?: boolean): 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;
+/** One entry of a multi-server search page (R43): the R33 entry plus its box. */
+interface BoxedToolSummary extends ToolSummary {
+  /** The box (alias) the tool lives in; `name` is qualified with it. */
+  box: string;
+}
+interface BoxedSearchPage {
+  /**
+   * The box overview (R43): the server's full `instructions`, neutralized
+   * and capped. Only on the first page of an empty-query `search_<alias>`
+   * whose server sends instructions.
+   */
+  overview?: string;
+  tools: BoxedToolSummary[];
+  /** Matching tools across all pages. */
+  total: number;
+  nextCursor?: string;
+}
+/** The policy options (R14, R49) are decided at the gate and on resume. */
+interface RunSegmentOptions extends PolicyOptions {
+  /** 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>;
+  /** 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;
+    /**
+     * Calls held on their server's question (G1), keyed by call id, with
+     * the server's answers to send back, keyed like the hold's questions'
+     * own keys. Re-issued as recorded; no verdict applies to them.
+     */
+    held?: Record<string, {
+      hold: UpstreamHold;
+      responses: Record<string, unknown>;
+    }>;
+  };
+}
+/**
+ * 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.
+ */
+export declare function runSegment(options: RunSegmentOptions): Promise<SegmentOutcome>;
+/** The single-server authoring contract (R3). */
+export declare const AUTHORING_CONTRACT: string;
 /** 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";
@@ -857,12 +1783,18 @@ 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";
-/** Build the resources Projection serves for a wrapped server (R3). */
-declare function buildResources(catalog: ServerCatalog, dts: string): ProjectionResource[];
+export declare const EXAMPLE_HAPPY_PATH: string;
+export declare const EXAMPLE_DENIAL_FALLBACK: string;
+/**
+ * Build the code-mode resources Projection serves for a wrapped server (R3).
+ * On a multi-server view the descriptions name the boxes and the contract
+ * and the examples call qualified names from its first box, picked under
+ * `policy` (R45, {@link toolSamples}); the box overview resources are the
+ * multi-server facade's own (`catalog/box-guidance.ts`).
+ */
+export declare function buildResources(catalog: ServerCatalog, dts: string, policy?: PolicyOptions, maxRoundTrips?: number): ProjectionResource[];
 /** R37: above this many tools, `discover_apis` defers the per-tool list to the catalog tools. */
-declare const DEFAULT_INLINE_TOOL_THRESHOLD = 40;
+export declare const DEFAULT_INLINE_TOOL_THRESHOLD = 40;
 interface DiscoverApisOptions {
   /** Whether the catalog projection (`search_tools` / `describe_tool`) is served (R37). */
   catalog?: boolean;
@@ -872,6 +1804,32 @@ interface DiscoverApisOptions {
    * clamped at 0, anything else falls back to the default.
    */
   inlineThreshold?: number;
+  /**
+   * How the R37 pointer names the search tools a multi-server facade serves
+   * (R43, R45): `searchToolsPhrase` of the view. Default `search_tools`.
+   */
+  searchPhrase?: string;
+  /**
+   * Direct listing (`projections.direct`): the full sentence(s) telling the
+   * model where tools are, replacing the R37 pointer's "Call <search tools>
+   * to find tools …" — the served search tools and the boxes listed
+   * directly, so the pointer never names a search tool the facade does not
+   * serve.
+   */
+  findTools?: string;
+  /**
+   * The resources the facade serves, when they go beyond
+   * {@link buildResources} (a multi-server facade's box overviews, R45):
+   * every one but the `ui://` dashboard is linked.
+   */
+  resources?: readonly ProjectionResource[];
+  /**
+   * The facade's policy (R14, R49), which picks the sample tool names on a
+   * multi-server view (R45, {@link toolSamples}).
+   */
+  policy?: PolicyOptions;
+  /** The facade's clamped `caps.maxRoundTrips` (R12), quoted by the contract's rule 5. */
+  maxRoundTrips?: number;
 }
 /**
  * The `discover_apis` result: an inline overview sufficient to author a
@@ -881,37 +1839,79 @@ interface DiscoverApisOptions {
  * 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, options?: DiscoverApisOptions): 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;
+  /**
+   * Whether the wrapped tools are also listed directly, as mediated aliases
+   * of `call_tool` (`projections.direct`, resolved at wrap time). Absent
+   * means not listed.
+   */
+  direct?: boolean;
+  /**
+   * Multi-server facade under direct listing: the boxes listed directly, in
+   * sorted alias order (the others keep the catalog path).
+   */
+  directBoxes?: readonly string[];
 }
 /**
  * The wrapped server's `instructions`, followed by the preamble for the
  * projections in service (R29). The preamble is library copy the
  * integrating developer can replace wholesale.
  */
-declare function buildInstructions(catalog: ServerCatalog, preamble?: string, projections?: ProjectionSelection): string;
+export declare function buildInstructions(catalog: ServerCatalog, preamble?: string, projections?: ProjectionSelection): string;
 /** Preamble when only code mode is on (R29). */
-declare const DEFAULT_CODE_MODE_PREAMBLE = "This server runs in code mode: instead of calling its tools directly, author an XState v5 state machine and run it with execute_machine, which orchestrates the tool calls for you. Any tool that is not read-only pauses the machine and asks the user to approve that specific action before it runs. Call discover_apis first for the tool types, the authoring contract, and worked examples.";
+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. Tools that change something may pause the machine and ask the user to approve that specific action before it runs; each tool's listing says whether it runs immediately or asks for approval. Call discover_apis first for the tool types, the authoring contract, and worked examples.";
 /** Preamble when only the catalog projection is on (R29, R32). */
-declare const DEFAULT_CATALOG_PREAMBLE = "This server exposes its tools through a catalog: call search_tools to find a tool, describe_tool to see its arguments, then call_tool to run it. Any tool that is not read-only pauses and asks the user to approve that specific action before it runs.";
+export declare const DEFAULT_CATALOG_PREAMBLE = "This server exposes its tools through a catalog: call search_tools to find a tool, then call_tool to run it, with the args its search hit shows (describe_tool gives any other tool's). Tools that change something may pause and ask the user to approve that specific action before it runs; each tool's listing says whether it runs immediately or asks for approval.";
 /** Preamble when both projections are on: the routing rule (R29). */
-declare const DEFAULT_ROUTING_PREAMBLE = "This server offers two ways to use its tools. For a single action, call search_tools to find the tool, describe_tool to see its arguments, then call_tool to run it. For several steps, branching on results, or a workflow worth saving, author an XState v5 state machine and run it with execute_machine (call discover_apis first for the tool types, the authoring contract, and worked examples). Either way, any action that is not read-only pauses and asks the user to approve that specific action before it runs.";
+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, then call_tool to run it, with the args its search hit shows (describe_tool gives any other tool's). For several steps, branching on results, computing over a list (counting, filtering, summing, comparing or checking every item), 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, tools that change something may pause and ask the user to approve that specific action before it runs; each tool's listing says whether it runs immediately or asks for approval.";
 /** The R29 preamble variant for a projection selection. */
-declare function defaultPreamble(projections: ProjectionSelection): string;
-//#endregion
-//#region src/wrap.d.ts
+export declare function defaultPreamble(projections: ProjectionSelection): string;
 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). */
+  /**
+   * 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). */
+  /**
+   * Approvals mode (R49). `'every-write'` (default) asks before every tool
+   * that is not read-only. `'destructive-only'` also runs, without approval,
+   * a non-read-only tool whose annotations declare `destructiveHint: false`
+   * exactly; a missing or any other `destructiveHint` still asks. A per-tool
+   * `policy` override wins over the mode. This extends the trust placed in
+   * `readOnlyHint` to `destructiveHint: false` — a hostile server can
+   * mislabel a damaging tool, so enable it only for servers you trust.
+   * Read once, at wrap time; any other value fails the wrap (`validate`).
+   */
+  approvals?: ApprovalsMode;
+  /**
+   * Masks sensitive argument fields before they reach an approval prompt
+   * (R16). It receives the tool name and a copy of the arguments. On a
+   * `wrapMcpServers` facade the name is the qualified `<alias>.<tool>`
+   * (`fs.write_file`), so one hook can tell the boxes' same-named tools
+   * apart; on `wrapMcpServer` it is the server's own tool name.
+   */
   redact?: RedactionHook;
+  /**
+   * How a machine suspension holding several gated calls is put to the
+   * person (R15 amendment; DECISIONS D25). `'per-call'` (default) sends one
+   * elicitation per call. `'batched'` sends one elicitation listing every
+   * call in its full approval copy, with one unticked boolean per call (no
+   * default): each call still runs only if its own box comes back ticked,
+   * on the arguments sealed for it (S2). A client that answers the form
+   * without the booleans declines every call. The layout is sealed in the
+   * blob; a batch is capped at 10 calls and 20 000 characters, falling back
+   * to per-call prompts above that. Read once, at wrap time; any other
+   * value fails the wrap (`validate`).
+   */
+  approvalPrompts?: ApprovalPrompts;
   /**
    * Replaces the whole R29 preamble, whichever projections are on (the
    * code-mode, catalog or routing copy).
@@ -949,12 +1949,68 @@ interface WrapOptions {
    * disabling both is an error at wrap time.
    */
   projections?: ProjectionsOptions;
+  /**
+   * Where upstream tokens for sources given by URL live (R59). Default: the
+   * OS credential store through the optional `@napi-rs/keyring` dependency,
+   * falling back to memory (with one stderr warning) when it is absent or
+   * the store is unavailable. A horizontally scaled deployment supplies a
+   * shared store (R27). Unused by pre-built `McpServer` / `Client` sources.
+   */
+  tokenStore?: TokenStore;
+  /**
+   * Whether the wrapped server's own questions reach the human (G1,
+   * DECISIONS D24). `'refuse'` (default): Projection declares no
+   * elicitation capability to the server, and a tool that asks anyway fails
+   * with a result saying it needs the user's input. `'forward'`: the
+   * capability is declared, and each question — a form, or a link to open —
+   * is relayed to the human over MRTR in Projection's own prompt, headed
+   * `Question from <box> (not an approval)` with the server's words quoted,
+   * after the call itself passed the approval gate. Enable it only for
+   * servers you trust to ask your users things: a hostile server can still
+   * word a phishing question. On `wrapMcpServers` this is the default for
+   * every box, and a source configuration can override it per box.
+   * Read once, at wrap time; any other value fails the wrap (`validate`).
+   */
+  upstreamElicitation?: UpstreamElicitationMode;
+  /**
+   * Bound, in milliseconds, on each wrapped source's connect and `tools/list`
+   * introspection at wrap time (R47). A source that has not finished in time
+   * fails the wrap with a `protocol` error, and every connection Projection
+   * opened is closed (a `Client` you passed in stays open). Default 30 000.
+   */
+  introspectTimeoutMs?: number;
 }
 /** Per-projection on/off switches (R1, R32). */
 interface ProjectionsOptions {
   codeMode?: boolean;
   catalog?: boolean;
+  /**
+   * Direct listing (see `facade/direct.ts`): also register one
+   * **mediated** facade tool per wrapped tool, a thin alias of
+   * `call_tool({ name, args })` under exactly the same gate, so the model
+   * sees every tool's name, description and schema without searching.
+   * `true` always lists them; `'auto'` lists them when their estimated
+   * definitions fit `directBudgetTokens` (on a multi-server facade box by
+   * box, smallest box first; the other boxes keep the catalog path);
+   * `false` never. Default `'auto'` (DECISIONS D28). Needs the
+   * catalog projection: `true` with `catalog: false` fails the wrap
+   * (`validate`); `'auto'` then stays off.
+   */
+  direct?: 'auto' | boolean;
+  /**
+   * `direct: 'auto'`: the largest estimated size, in tokens, of all mediated
+   * tool definitions (name, description, input schema; characters / 3.5)
+   * that is still listed directly. Default {@link DEFAULT_DIRECT_BUDGET_TOKENS}.
+   */
+  directBudgetTokens?: number;
 }
+/**
+ * Default `projections.directBudgetTokens`: about 8k estimated tokens of
+ * tool definitions. Measured (explore/adaptive-surface.md): listing wins
+ * clearly at 2k and 5.4k estimated tokens and breaks even on Sonnet 5.5 at
+ * about 11k, whose tokenizer counts ~1.3–1.4× the estimate.
+ */
+export declare const DEFAULT_DIRECT_BUDGET_TOKENS = 8000;
 /** Options for registering the projections on a server the caller built. */
 interface RegisterOptions {
   /**
@@ -982,9 +2038,11 @@ interface ProjectionFacade {
   /**
    * Run `execute_machine` for one `tools/call`, first attempt or retry.
    * `clientCanElicit` reports whether the connected client declared the
-   * `elicitation` capability (legacy compat only; omit when unknown).
+   * `elicitation` capability (legacy compat only; omit when unknown), and
+   * `clientUrlElicitation` whether it declared URL mode (a forwarded
+   * server link, G1, is otherwise shown as text in a form).
    */
-  executeMachine(args: ExecuteMachineArgs, era?: ProtocolEra, clientCanElicit?: boolean): Promise<ToolCallResult>;
+  executeMachine(args: ExecuteMachineArgs, era?: ProtocolEra, clientCanElicit?: boolean, clientUrlElicitation?: boolean): Promise<ToolCallResult>;
   /** Run `discover_apis`. */
   discoverApis(): CallToolResult;
   /** Run `search_tools` (R33). Failures come back as R25 structured error results. */
@@ -995,95 +2053,111 @@ interface ProjectionFacade {
   /** 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`.
+   * `era`, `clientCanElicit` and `clientUrlElicitation` as for `executeMachine`.
    */
-  callTool(args: CallToolArgs, era?: ProtocolEra, clientCanElicit?: boolean): Promise<ToolCallResult>;
+  callTool(args: CallToolArgs, era?: ProtocolEra, clientCanElicit?: boolean, clientUrlElicitation?: 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 the enabled projections' tools and the resources on an `McpServer` the caller built. */
   registerOn(server: McpServer, options?: RegisterOptions): void;
+  /**
+   * Delete the stored upstream tokens (R59) of the sources given by URL:
+   * on a single-server facade, its source (call it without an alias); on a
+   * multi-server facade, the box named by `alias`, or every such box
+   * without one. No revocation yet. A facade or box not built from an
+   * `UpstreamSpec`, or an unknown alias, is a `validate` error.
+   */
+  signOut(alias?: string): Promise<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
- * Projection facade.
+ * Wrap an MCP server — an in-process instance, a connected client, or a
+ * remote server given by URL (`{ url, oauth? }`, R51) — into a Projection
+ * facade.
  */
-declare function wrapMcpServer(source: McpServer | Client, options: WrapOptions): Promise<ProjectionFacade>;
-//#endregion
-//#region src/apps/dashboard.d.ts
-/**
- * MCP Apps workflow dashboard (PRD §12.1, second fenced use case).
- *
- * A static, library-authored HTML app that renders an `execute_machine`
- * result — output, approval audit trail, console logs, or the structured
- * error — inside the host's sandboxed iframe, per the MCP Apps extension
- * (SEP-1865, spec 2026-01-26).
- *
- * Security posture (the §12.1 design constraint, satisfied by construction):
- * - The HTML is a compile-time constant. No model-authored code, no
- *   template interpolation, no VM: UI rendering can never reach the tools
- *   bridge because nothing dynamic executes server-side at all.
- * - Model-controlled data (outputs, audit args, log lines, error text)
- *   enters the DOM exclusively through `textContent` — the app never uses
- *   innerHTML — so hostile strings render inert (S6 extended to the app).
- * - The app requests no host capabilities: `appCapabilities: {}`. It cannot
- *   call tools, open links, or write context; it only listens.
- *
- * Wire contract implemented (app side):
- * - `ui/initialize` request → await result → `ui/notifications/initialized`.
- * - Listens for `ui/notifications/tool-input`, `ui/notifications/tool-result`
- *   and `ui/notifications/tool-cancelled`; ignores everything else.
- * - The result payload is the standard `CallToolResult` from
- *   `execute_machine`: `structuredContent` is either
- *   `{ output, approvals, logs }` or (with `isError`) the structured error
- *   `{ 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";
-/** 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";
-//#endregion
-//#region src/prompts/workflow-prompts.d.ts
-interface WorkflowPromptDefinition {
+export declare function wrapMcpServer(source: McpServer | Client | UpstreamSpec, options: WrapOptions): Promise<ProjectionFacade>;
+/** Separator between a box alias and its tool in a mapped name (`fs__read_file`). */
+export declare const DIRECT_BOX_SEPARATOR = "__";
+/** One mediated tool, as listed. */
+interface DirectTool {
+  /** The facade tool name, `[A-Za-z0-9_-]{1,64}`. */
   name: string;
-  title: string;
+  /** The catalog name `call_tool` is called with (qualified on a multi-server facade). */
+  target: string;
+  /** The box the tool lives in (multi-server facade only). */
+  alias?: string;
+  title?: string;
   description: string;
-  /** Argument names → { description, required }. All MCP prompt args are strings. */
-  args: Record<string, {
-    description: string;
-    required: boolean;
-  }>;
-  build(args: Record<string, string | undefined>, catalog: ServerCatalog): string;
+  /** The R34-sanitized input schema, always `type: "object"` at the root. */
+  inputSchema: Record<string, unknown>;
+  /** What the listing advertises: Projection's own, see {@link advertisedAnnotations}. */
+  annotations: ToolAnnotations;
+  posture: ToolPosture;
+}
+/** What {@link planDirectTools} needs besides the catalog. */
+interface DirectPlanOptions extends PolicyOptions {
+  /** Names the facade already serves (Projection's own tools): never shadowed. */
+  reserved: ReadonlySet<string>;
 }
-declare const SAVE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
-declare const VISUALIZE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
-declare const WORKFLOW_PROMPTS: readonly WorkflowPromptDefinition[];
-//#endregion
-//#region src/introspector/introspector.d.ts
+/**
+ * The mediated tools of a catalog, in catalog order. On a multi-server view
+ * each is named `<alias>__<tool>`; on a single-server facade, the tool's own
+ * name when it is legal and free. A name that is not legal is mapped
+ * (illegal characters become `_`, an over-long name is cut and hashed); a
+ * name that collides with a reserved one or an earlier mapped one gets
+ * `_<8 hex of the catalog name>`. A tool whose name still collides is not
+ * listed — it stays reachable through `call_tool`.
+ */
+export declare function planDirectTools(catalog: ServerCatalog, options: DirectPlanOptions): DirectTool[];
+/** Map `raw` onto the host name rule, deterministically. */
+export declare function directToolName(raw: string): string;
+/**
+ * Estimated tokens of the listed definitions: name + title + description +
+ * input schema JSON, at {@link CHARS_PER_TOKEN} characters per token.
+ */
+export declare function estimateDirectTokens(tools: readonly DirectTool[]): number;
 /** 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.
+ * Aliased server sources (R30): one per alias. An {@link UpstreamConnector}
+ * is a source given by URL (R51), validated by the facade: the introspector
+ * opens it, owns the resulting client, and records its `url:` identity
+ * (R60).
  */
-type IntrospectorSources = Record<ServerAlias, ServerSource>;
+type IntrospectorSources = Record<ServerAlias, ServerSource | UpstreamConnector>;
+/** How {@link Introspector.create} connects. */
+interface IntrospectOptions {
+  /**
+   * Bound on each source's connect and introspection (R47). A source that
+   * has not finished in time fails the whole introspection with a
+   * `protocol` error. Default {@link DEFAULT_INTROSPECT_TIMEOUT_MS}.
+   */
+  timeoutMs?: number;
+  /** How the timeout error names a source. Default: `wrapped server "<alias>"`. */
+  describe?: (alias: ServerAlias) => string;
+  /**
+   * The aliases whose boxes forward their server's questions to the human
+   * (`upstreamElicitation: 'forward'`, G1). Their owned clients declare the
+   * elicitation capability; every other box declares none.
+   */
+  forwardElicitation?: ReadonlySet<ServerAlias>;
+}
 /**
  * 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 {
+export declare class Introspector implements ToolExecutor {
   #private;
   private constructor();
-  static create(sources: IntrospectorSources): Promise<Introspector>;
+  static create(sources: IntrospectorSources, options?: IntrospectOptions): 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. */
@@ -1098,8 +2172,12 @@ declare class Introspector implements ToolExecutor {
    * - `isError` result or transport/protocol failure → `{ ok: false, error }`.
    *
    * An unknown alias is a wiring bug, not a tool failure, and throws.
+   *
+   * `options` are host-side: `signal` cancels the upstream request, and
+   * `onProgress` asks the upstream for progress and receives each report
+   * (redacted first for a source given by URL, S1).
    */
-  callTool(alias: ServerAlias, name: string, args: Record<string, unknown>): Promise<ToolCallOutcome>;
+  callTool(alias: ServerAlias, name: string, args: Record<string, unknown>, options?: UpstreamCallOptions): Promise<ToolCallOutcome>;
   /**
    * Close connections the introspector created (in-process sources).
    * Caller-provided remote clients are left untouched.
@@ -1111,128 +2189,133 @@ declare class Introspector implements ToolExecutor {
  *
  * v1 usage: `createIntrospector({ [DEFAULT_SERVER_ALIAS]: serverOrClient })`.
  */
-declare function createIntrospector(sources: IntrospectorSources): Promise<Introspector>;
-//#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";
+export declare function createIntrospector(sources: IntrospectorSources, options?: IntrospectOptions): Promise<Introspector>;
+/** One source with its per-box settings (R39). */
+interface ServerSourceConfig {
+  /**
+   * The server to wrap: an in-process `McpServer`, a connected `Client`, or
+   * a remote server given by URL (`{ url, oauth? }`, R51).
+   */
+  source: McpServer | Client | UpstreamSpec;
+  /**
+   * Host-trusted text naming the box's purpose, shown to the model on the
+   * shelf (R44). Neutralized (control and bidi characters) and capped at 200
+   * characters.
+   */
+  description?: string;
+  /**
+   * Approvals mode for this box (R49); takes precedence over
+   * `WrapServersOptions.approvals`. A per-tool `policy` override still wins.
+   */
+  approvals?: ApprovalsMode;
+  /**
+   * Whether this box's server may ask the human questions (G1, DECISIONS
+   * D24); takes precedence over `WrapServersOptions.upstreamElicitation`.
+   * Default `'refuse'`.
+   */
+  upstreamElicitation?: UpstreamElicitationMode;
+  /**
+   * R47 (skip this source instead of failing the wrap) is not supported yet:
+   * `true` fails the wrap with a `validate` error. Wrapping is fail-closed.
+   */
+  optional?: boolean;
+}
+/** Options of a multi-server facade (R39). */
+interface WrapServersOptions extends WrapOptions {
+  catalog?: {
+    /**
+     * Serve the global `search_tools` across every box next to the per-box
+     * `search_<alias>` tools (R43). Default `true`; `false` leaves only the
+     * per-box tools, and every piece of copy that names a search tool names
+     * those instead.
+     */
+    globalSearch?: boolean;
+  };
+}
 /**
- * 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.
+ * A multi-server facade (R39): every {@link ProjectionFacade} member, with
+ * `catalog` the alias-keyed catalog of the wrapped boxes (bare names),
+ * `skipped` the optional sources that were skipped (R47), `searchTools`
+ * taking an optional alias, and `describeTool` / `callTool` taking
+ * qualified names.
  */
-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;
+interface MultiProjectionFacade extends Omit<ProjectionFacade, 'catalog' | 'searchTools'> {
+  /** The wrapped boxes' catalogs, keyed by alias, with the servers' own tool names (R30). */
+  readonly catalog: ToolCatalog;
   /**
-   * Who asked: a machine state (default) or a direct `call_tool` request
-   * (R35). Selects the footer; nothing else differs.
+   * Optional sources skipped at wrap time (R47). Always empty for now:
+   * optional sources are not supported yet, so every source is wrapped or
+   * the wrap fails.
    */
-  origin?: 'machine' | 'direct';
+  readonly skipped: readonly {
+    alias: string;
+    error: StructuredError;
+  }[];
   /**
-   * Backstop cap on the whole rendered args JSON, in characters. Default
-   * 4096. Each string leaf is independently capped at 512 characters first.
+   * Run `search_<alias>` when `alias` is given, `search_tools` otherwise
+   * (R43). A search tool the facade does not serve — an unknown alias, or
+   * `search_tools` under `catalog.globalSearch: false` — comes back as an
+   * R25 `validate` error result.
    */
-  maxArgsChars?: number;
+  searchTools(args: {
+    query?: string;
+    cursor?: string;
+  }, alias?: string): CallToolResult;
 }
 /**
- * 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.
+ * Wrap several MCP servers (in-process instances, connected clients, or
+ * `{ source, … }` configurations) into one Projection facade, each under
+ * its alias (R39). Configuration mistakes are `validate` errors raised
+ * before anything connects; a source that fails to connect or introspect
+ * fails the wrap and closes every connection Projection opened (R47).
  */
-declare function buildElicitationCopy(call: PendingToolCall, entry: ToolCatalogEntry, options?: ElicitationCopyOptions): ElicitationCopy;
+export declare function wrapMcpServers(sources: Record<string, McpServer | Client | UpstreamSpec | ServerSourceConfig>, options: WrapServersOptions): Promise<MultiProjectionFacade>;
 /**
- * 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.
+ * MCP Apps workflow dashboard (PRD §12.1, second fenced use case).
+ *
+ * A static, library-authored HTML app that renders an `execute_machine`
+ * result — output, approval audit trail, console logs, or the structured
+ * error — inside the host's sandboxed iframe, per the MCP Apps extension
+ * (SEP-1865, spec 2026-01-26).
+ *
+ * Security posture (the §12.1 design constraint, satisfied by construction):
+ * - The HTML is a compile-time constant. No model-authored code, no
+ *   template interpolation, no VM: UI rendering can never reach the tools
+ *   bridge because nothing dynamic executes server-side at all.
+ * - Model-controlled data (outputs, audit args, log lines, error text)
+ *   enters the DOM exclusively through `textContent` — the app never uses
+ *   innerHTML — so hostile strings render inert (S6 extended to the app).
+ * - The app requests no host capabilities: `appCapabilities: {}`. It cannot
+ *   call tools, open links, or write context; it only listens.
+ *
+ * Wire contract implemented (app side):
+ * - `ui/initialize` request → await result → `ui/notifications/initialized`.
+ * - Listens for `ui/notifications/tool-input`, `ui/notifications/tool-result`
+ *   and `ui/notifications/tool-cancelled`; ignores everything else.
+ * - The result payload is the standard `CallToolResult` from
+ *   `execute_machine`: `structuredContent` is either
+ *   `{ output, approvals, logs }` or (with `isError`) the structured error
+ *   `{ phase, message, hint, logs }`.
  */
-declare function purposeSentence(description: string | undefined): string | undefined;
-//#endregion
-//#region src/sandbox/session.d.ts
+/** URI the dashboard is served under. MCP Apps mandates the ui:// scheme. */
+export declare const DASHBOARD_RESOURCE_URI = "ui://projection/dashboard.html";
+/** MIME type the MCP Apps spec mandates for app HTML resources. */
+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";
+interface WorkflowPromptDefinition {
+  name: string;
+  title: string;
+  description: string;
+  /** Argument names → { description, required }. All MCP prompt args are strings. */
+  args: Record<string, {
+    description: string;
+    required: boolean;
+  }>;
+  build(args: Record<string, string | undefined>, catalog: ServerCatalog): string;
+}
+export declare const SAVE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
+export declare const VISUALIZE_WORKFLOW_PROMPT: WorkflowPromptDefinition;
+export declare const WORKFLOW_PROMPTS: readonly WorkflowPromptDefinition[];
 /** A tool call surfaced from the `@astral-mcp/tools` bridge inside the VM. */
 interface SandboxToolCall {
   name: string;
@@ -1293,64 +2376,6 @@ 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>;
-//#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.\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, type ApprovalGateDeps, ApprovalVerdict, AuditEntry, BLOB_SCHEMA_VERSION, BlobKind, BlobPayload, BlobSealerConfig, CALL_KEY, type CallToolArgs, type CallToolDeps, type CallToolOutcome, type CallToolResult, type ContentBlock, DASHBOARD_HTML, DASHBOARD_RESOURCE_URI, DEFAULT_CALL_TTL_MS, DEFAULT_CAPS, DEFAULT_CATALOG_PREAMBLE, DEFAULT_CODE_MODE_PREAMBLE, DEFAULT_INLINE_TOOL_THRESHOLD, DEFAULT_MAX_BLOB_BYTES, DEFAULT_ROUTING_PREAMBLE, DEFAULT_SEARCH_PAGE_SIZE, DEFAULT_SERVER_ALIAS, DEFAULT_TTL_MS, type DescribeToolArgs, type DescribeToolOptions, Diagnostic, type DiscoverApisOptions, ENVELOPE_PREFIX, EXAMPLE_DENIAL_FALLBACK, EXAMPLE_HAPPY_PATH, type ElicitationCopy, type ElicitationCopyOptions, ErrorPhase, type ExecuteMachineArgs, type ExecuteMachineDeps, type GeneratedToolTypes, HostEvent, type InputRequest, type InputRequests, type InputRequiredResult, type InputResponse, type InputResponseView, type InputResponses, Introspector, LIB_VERSION, LogEntry, LogLevel, MAX_CAPS, MAX_QUERY_CHARS, MAX_SCHEMA_CHARS, MCP_APP_MIME_TYPE, MRTR_PROTOCOL_REVISION, type OpenBlobOptions, POLICY_DENIED_REASON, PendingToolCall, PolicyDecision, PolicyOverrides, ProjectionConfig, ProjectionError, type ProjectionFacade, type ProjectionResource, type ProjectionSelection, type ProjectionsOptions, type ProtocolEra, RESOURCE_URIS, RedactionHook, type RegisterOptions, ReplayCache, type ResolvedCallPolicy, ResourceCaps, type RetryEnvelope, type RunSegmentOptions, SAVE_WORKFLOW_PROMPT, SCHEMA_KEY_ALLOWLIST, type SandboxSession, type SandboxSessionOptions, type SandboxToolCall, type SandboxToolCallHandler, type SanitizedSchema, type SearchToolsArgs, type SearchToolsOptions, type SearchToolsPage, SegmentOutcome, ServerAlias, ServerCatalog, StructuredError, TOOLS_MODULE_SPECIFIER, TOOL_CALL_HOST_GLOBAL, ToolAnnotations, ToolCallOutcome, type ToolCallResult, ToolCatalog, ToolCatalogEntry, type ToolDescription, ToolExecutor, type ToolPosture, type ToolSummary, type ToolTypeText, VISUALIZE_WORKFLOW_PROMPT, WORKFLOW_PROMPTS, type WorkflowPromptDefinition, type WrapOptions, XSTATE_VERSION, acceptedContent, buildBlobPayload, buildElicitationCopy, buildInstructions, buildResources, callTool, canonicalJson, canonicalRequest, capLength, clampCaps, createIntrospector, createSandboxSession, decidePolicy, dedupeTools, defaultPreamble, describeTool, discoverApis, errorResult, executeMachine, findTool, generateToolTypes, hashCode, inputRequired, inputResponse, isInputRequiredResult, isRecord, neutralizeControlChars, openBlob, policyDeniedReason, postureOf, purposeSentence, resolveCallPolicy, runSegment, sanitizeSchema, schemaRequiresArgs, schemaToTsType, sealBlob, searchTools, summarizeTool, supportsMrtr, toStructuredError, validateArgsShape, wrapMcpServer };
+export declare function createSandboxSession(options: SandboxSessionOptions): Promise<SandboxSession>;
+export { type ApprovalGateDeps, type ApprovalPrompts, type ArgGloss, type BlobKeyDomain, type BoxedSearchPage, type BoxedToolSummary, type CallSignature, type CallToolArgs, type CallToolDeps, type CallToolOutcome, type CallToolResult, type ContentBlock, type DescribeToolArgs, type DescribeToolOptions, type DirectTool, 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 MultiProjectionFacade, 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 ServerSourceConfig, type SharedArg, type TokenStore, type ToolCallResult, type ToolDescription, type ToolPosture, type ToolSummary, type ToolTypeText, type UpstreamOAuthOptions, type UpstreamSpec, type WorkflowPromptDefinition, type WrapOptions, type WrapServersOptions, acceptedContent, inputRequired, inputResponse, isInputRequiredResult };
 //# sourceMappingURL=index.d.mts.map