stitchkit 0.93.0 → 0.94.1

package/dist/tools/mcp/catalog.d.ts

@@ -0,0 +1,68 @@
+import type { PreparedMcpServerSurface } from './prepare.js';
+/**
+ * The `_meta` key carrying the catalog stamp, on every advertised tool and on
+ * every tool result.
+ *
+ * Namespaced, because `_meta` is shared ground: a host, the official SDK and
+ * the application all write into it, and a bare `catalog` would eventually mean
+ * two things at once.
+ */
+export declare const MCP_CATALOG_META_KEY = "stitchkit/catalog";
+/**
+ * What the server says its advertised catalog currently is.
+ *
+ * `digest` changes whenever any advertised tool's name, description, input
+ * schema, output schema or annotations change — and only then. `tools` is the
+ * count, carried because it makes a mismatch legible without a second lookup
+ * ("they advertise 41, I hold 39").
+ */
+export interface McpCatalogStamp {
+    digest: string;
+    tools: number;
+}
+/**
+ * Fingerprint one advertised MCP catalog.
+ *
+ * The problem this answers is not a broken server — it is a **consumer holding
+ * an old idea of the contract and unable to find out**. A long-lived session
+ * lists the tools once; the server is redeployed with a renamed field; every
+ * later call is refused, and the refusal looks to the consumer like a fault in
+ * the source, because a stale catalog is invisible from inside. The fix has to
+ * ride on responses the consumer is already receiving, so it can compare what
+ * it holds against what is live without asking anything extra.
+ *
+ * `notifications/tools/list_changed` is the push-shaped answer, and this
+ * framework's MCP HTTP handler cannot send it: it is stateless by construction
+ * (`createMcpHandler` builds a fresh server per request and keeps no session),
+ * so there is no retained stream to notify. The stamp works precisely because
+ * it needs no session.
+ */
+export declare function mcpCatalogStamp(surface: PreparedMcpServerSurface): McpCatalogStamp;
+/** The `_meta` fragment a stamped tool or result carries. */
+export declare function mcpCatalogMeta(stamp: McpCatalogStamp): Record<string, unknown>;
+/**
+ * Read a catalog stamp out of a peer's `_meta`, or `null` when there is none.
+ *
+ * Parsed, not trusted: this arrives over the wire from another process, and the
+ * fact that it describes a catalog does not exempt it from being validated.
+ */
+export declare function readMcpCatalogStamp(meta: unknown): McpCatalogStamp | null;
+/**
+ * Attach the stamp to a tool registration, so `tools/list` carries the catalog
+ * the listing came from — the value a consumer stores alongside the tools.
+ */
+export declare function stampToolRegistration<TConfig extends {
+    _meta?: Record<string, unknown>;
+}>(config: TConfig, stamp: McpCatalogStamp | undefined): TConfig;
+/**
+ * Attach the stamp to a tool result.
+ *
+ * This is the half that matters. A consumer compares it against the stamp it
+ * stored at listing time, on a response it was going to receive anyway, and so
+ * learns its catalog is stale WITHOUT asking — including on the refusal that a
+ * stale catalog causes, which is exactly when the question gets asked.
+ */
+export declare function stampToolResult<TResult extends {
+    _meta?: Record<string, unknown>;
+}>(result: TResult, stamp: McpCatalogStamp | undefined): TResult;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/tools/mcp/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAmB,MAAM,WAAW,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CAclF;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACvF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACjF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT"}

package/dist/tools/mcp/handler.d.ts

@@ -0,0 +1,46 @@
+import { type ProtectedResourceConfig } from '../../server/oauth/metadata.js';
+import type { RawRoute } from '../../server/types.js';
+import { type McpServerBuildConfig } from './mount.js';
+import { type McpSurfaceRegistry } from './prepare.js';
+/** Compatibility posture for protocol revisions predating 2026-07-28. */
+export type McpLegacyPolicy = 'serve' | 'reject';
+/** DNS-rebinding policy applied before authentication and SDK dispatch. */
+export interface McpHttpSecurityConfig {
+    /** Allowed `Host` header hostnames. Defaults to loopback hostnames only. */
+    allowedHosts?: readonly string[];
+    /** Allowed browser `Origin` hostnames. Defaults to loopback hostnames only. */
+    allowedOrigins?: readonly string[];
+}
+export interface McpHttpConfig<TAuth> {
+    /** Resolve an incoming request to an identity. Return `null` → 401. */
+    auth: (req: Request) => TAuth | null | Promise<TAuth | null>;
+    /** OAuth 2.0 Protected Resource metadata used by the 401 challenge. */
+    protectedResource?: ProtectedResourceConfig;
+    /** Serve legacy stateless requests or reject them. Default: `serve`. */
+    legacy?: McpLegacyPolicy;
+    /** Optional Fetch-boundary Host and Origin policy. */
+    security?: McpHttpSecurityConfig;
+    /** Observe a protocol/security rejection without entering lifecycle or tool hooks. */
+    onTransportRejected?: (event: {
+        request: Request;
+        response: Response;
+    }) => void | Promise<void>;
+}
+export type McpHandlerConfig<TAuth, TSurfaces extends McpSurfaceRegistry = McpSurfaceRegistry> = McpServerBuildConfig<TAuth, TSurfaces> & McpHttpConfig<TAuth>;
+/** Framework-owned Fetch face for one stateless dual-era MCP endpoint. */
+export interface McpHttpHandler {
+    fetch(request: Request): Promise<Response>;
+    close(): Promise<void>;
+}
+/**
+ * Build a stateless MCP HTTP handler on the official SDK v2 request factory.
+ * Every request gets a fresh SDK server and a fresh Stitchkit tool context;
+ * no protocol session, event store or `Mcp-Session-Id` exists in this layer.
+ */
+export declare function createMcpHandler<TAuth, const TSurfaces extends McpSurfaceRegistry = McpSurfaceRegistry>(config: McpHandlerConfig<TAuth, TSurfaces>): McpHttpHandler;
+/** Mount an MCP handler as an ordinary framework-owned raw HTTP route. */
+export declare function createMcpHttpRoute(config: {
+    path: string;
+    handler: McpHttpHandler;
+}): RawRoute;
+//# sourceMappingURL=handler.d.ts.map

package/dist/tools/mcp/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/handler.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,WAAW,CAAC;AAEnB,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC7D,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;KACpB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,CAC1B,KAAK,EACL,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;AAElE,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAgFD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EACL,KAAK,CAAC,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,EAC/D,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,cAAc,CAkF5D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,QAAQ,CAMX"}

package/dist/tools/mcp/mount.d.ts

@@ -0,0 +1,152 @@
+import { McpServer, type ServerOptions } from '@modelcontextprotocol/server';
+import type { ServiceDef, StitchLogger } from '../../server/types.js';
+import type { ErrorHintFn, ToolCallHooks, ToolLifecycle } from '../execute-hooks.js';
+import { type ToolExtend } from '../mount.js';
+import type { RuntimeToolDefinition } from '../runtime-tool.js';
+import { type McpResourceDef } from './app.js';
+import { type McpCatalogStamp } from './catalog.js';
+import { type McpSchemaValidationConfig, type McpSurfaceRegistry, type PreparedMcpServerSurface, type PreparedMcpSurface, type ValidateMcpSchemasConfig } from './prepare.js';
+import type { McpRoundRuntime } from './round.js';
+export interface McpMountConfig {
+    context?: Record<string, unknown>;
+    /** Tool-call observability hooks. */
+    hooks?: ToolCallHooks;
+    /**
+     * Auth / scope gate and result transform for every tool call — the tool-side
+     * twin of `createServer`'s `beforeHandle` / `afterHandle`. Pass the same
+     * `createAuthHook` result here as on the HTTP server to guard tools too;
+     * without it a tool call bypasses the HTTP `beforeHandle` auth gate.
+     */
+    lifecycle?: ToolLifecycle;
+    extend?: ToolExtend;
+    /** Validation policy applied to the exact advertised MCP schemas. */
+    schemaValidation?: McpSchemaValidationConfig;
+    /** Logger for the `'warn'` policy — defaults to `console`. */
+    logger?: StitchLogger;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object. Default: false. */
+    flattenUnionInput?: boolean;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: ErrorHintFn;
+    /** Report output keys the contract schema removed — → ADR 0037. */
+    onOutputStrip?: (toolName: string, paths: string[]) => void;
+}
+interface PreparedMcpMountConfig extends McpMountConfig {
+    multiRoundRuntime?: McpRoundRuntime;
+    /** The catalog this surface advertises, stamped onto listings and results. */
+    catalog?: McpCatalogStamp;
+}
+/**
+ * Validate that every contract tool in `services` can be advertised on the MCP
+ * surface — object-shaped, JSON Schema-compatible input / output, no tool-name
+ * collision across services. The build-time check behind `mountMcp` — also
+ * callable on its own (a startup assertion, a test) to fail a deploy before
+ * the first request.
+ */
+export declare function validateMcpSchemas(config: ValidateMcpSchemasConfig): void;
+export declare function mountMcp(mcpServer: McpServer, services: ServiceDef | ServiceDef[], config?: McpMountConfig): void;
+/** Register a prepared immutable surface onto one fresh server/runtime. */
+export declare function mountPreparedMcp(mcpServer: McpServer, prepared: PreparedMcpSurface, config?: PreparedMcpMountConfig): void;
+/**
+ * Transport-neutral build config for an MCP server — everything needed to turn
+ * contract services into a live `McpServer`, minus how the identity is
+ * resolved. `createMcpHandler` (HTTP) and `createStdioMcpServer` (stdio) each
+ * add their own `auth` on top.
+ */
+export interface McpServerSharedConfig<TAuth> {
+    /** MCP server identity (name + version). */
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /** Context merged into every contract handler (`mountMcp` context). */
+    context?: (auth: TAuth) => Record<string, unknown>;
+    /** Tool-call observability hooks — `afterToolCall` fires for every result
+     *  (success and error), so the consuming app can log MCP tool outcomes;
+     *  `onToolError` adds the raw thrown value behind a failed one. */
+    hooks?: ToolCallHooks;
+    /** Auth / scope gate and result transform for every tool call — pass the
+     *  same `createAuthHook` result used for the HTTP `beforeHandle` to guard
+     *  tools with the identical rules. */
+    lifecycle?: ToolLifecycle;
+    /** Add extra tool arguments resolved into handler context (e.g. a `tenantId`
+     *  for one API key serving many tenants). Same `ToolExtend` accepted by
+     *  `mountMcp` — without this, the batteries-path (`createMcpHandler`) could not
+     *  reach it and a consumer had to hand-wrap every service. */
+    extend?: ToolExtend;
+    /** Validation policy applied to the exact advertised MCP schemas. */
+    schemaValidation?: McpSchemaValidationConfig;
+    /** Logger for schema-incompatibility warnings — defaults to `console`. */
+    logger?: StitchLogger;
+    /** Explicit unprotected SDK escape hatch. Prefer `runtimeTools`; registrations
+     *  here do not receive stitchkit validation, lifecycle, context or hooks. */
+    rawTools?: (server: McpServer, auth: TAuth) => void;
+    /** MCP Apps UI resources (`ui://…`) served for tools that declare `ui`. */
+    resources?: McpResourceDef[];
+    /** Server instructions — a short (≤2KB) hint to the host on when and how to
+     *  use these tools. Surfaced to MCP tool-search. */
+    instructions?: string;
+    /** Explicit modern MCP cache policy. Omitted operations stay zero/private. */
+    cache?: {
+        operations?: NonNullable<ServerOptions['cacheHints']>;
+    };
+    /** Signed multi-round continuation policy for tools declaring `mcp.inputRequired`. */
+    multiRound?: {
+        state: {
+            /** Shared HMAC key, at least 32 bytes. */
+            key: Uint8Array | string;
+            /** Continuation lifetime. Default 10 minutes. */
+            ttlSeconds?: number;
+            /** Stable authenticated principal bound into every continuation. */
+            principal: (auth: TAuth) => string;
+        };
+        /** Legacy stdio shim and round limits owned by the official SDK. */
+        serving?: NonNullable<ServerOptions['inputRequired']>;
+    };
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object. Default: false. */
+    flattenUnionInput?: boolean;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: ErrorHintFn;
+    /** Report output keys the contract schema removed — → ADR 0037. */
+    onOutputStrip?: (toolName: string, paths: string[]) => void;
+}
+export interface DirectMcpSurfaceConfig<TAuth> {
+    /** Contract services exposed as MCP tools — may depend on the identity. */
+    services: ServiceDef[] | ((auth: TAuth) => ServiceDef[]);
+    /** Framework-managed runtime tools — may depend on the identity. */
+    runtimeTools?: readonly RuntimeToolDefinition[] | ((auth: TAuth) => readonly RuntimeToolDefinition[]);
+    surfaces?: never;
+    selectSurface?: never;
+}
+export interface FiniteMcpSurfaceConfig<TAuth, TSurfaces extends McpSurfaceRegistry> {
+    /** Finite immutable surfaces, all prepared eagerly exactly once. */
+    surfaces: TSurfaces;
+    /** Select one declared surface for the resolved identity. */
+    selectSurface: (auth: TAuth) => Extract<keyof TSurfaces, string>;
+    services?: never;
+    runtimeTools?: never;
+}
+/**
+ * Transport-neutral MCP build config. Use direct services for a static or truly
+ * identity-dynamic surface; use `surfaces` for a bounded role/plan registry.
+ */
+export type McpServerBuildConfig<TAuth, TSurfaces extends McpSurfaceRegistry = McpSurfaceRegistry> = McpServerSharedConfig<TAuth> & (DirectMcpSurfaceConfig<TAuth> | FiniteMcpSurfaceConfig<TAuth, TSurfaces>);
+/**
+ * Build an `McpServer` from contract services for a resolved identity.
+ * Transport-agnostic — the shared core behind every MCP transport.
+ */
+export declare function buildMcpServer(config: McpServerBuildConfig<undefined>): McpServer;
+export declare function buildMcpServer<TAuth>(config: McpServerBuildConfig<TAuth>, auth: TAuth): McpServer;
+/** Build one fresh server from a deterministic surface prepared by its owner. */
+export declare function buildMcpServerFromPrepared<TAuth>(config: McpServerBuildConfig<TAuth>, auth: TAuth, prepared: PreparedMcpServerSurface): McpServer;
+/**
+ * Register one MCP Apps UI resource on an `McpServer`. The `read` callback's
+ * HTML is served under the resource `uri` with the apps MIME type; any `ui`
+ * metadata (CSP, border, domain) is attached to the content's `_meta.ui`.
+ */
+export declare function mountMcpResource(server: McpServer, resource: McpResourceDef): void;
+export {};
+//# sourceMappingURL=mount.d.ts.map

package/dist/tools/mcp/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,EAET,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,OAAO,CAAC;AAChE,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,WAAW,CAAC;AAClE,OAAO,EAEL,KAAK,yBAAyB,EAE9B,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EAGvB,KAAK,wBAAwB,EAC9B,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,SAAS,CAAC;AAG9D,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;IAC7C,8DAA8D;IAC9D,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC7D;AAED,UAAU,sBAAuB,SAAQ,cAAc;IACrD,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAOzE;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,cAAmB,GAC1B,IAAI,CAWN;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,GAAE,sBAA2B,GAClC,IAAI,CAgCN;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB,CAAC,KAAK;IAC1C,4CAA4C;IAC5C,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD;;uEAEmE;IACnE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;0CAEsC;IACtC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;kEAG8D;IAC9D,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;IAC7C,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC;IACpD,2EAA2E;IAC3E,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B;wDACoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;KACvD,CAAC;IACF,sFAAsF;IACtF,UAAU,CAAC,EAAE;QACX,KAAK,EAAE;YACL,0CAA0C;YAC1C,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;YACzB,iDAAiD;YACjD,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,oEAAoE;YACpE,SAAS,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC;SACpC,CAAC;QACF,oEAAoE;QACpE,OAAO,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;KACvD,CAAC;IACF,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,sBAAsB,CAAC,KAAK;IAC3C,2EAA2E;IAC3E,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,EAAE,CAAC,CAAC;IACzD,oEAAoE;IACpE,YAAY,CAAC,EACT,SAAS,qBAAqB,EAAE,GAChC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,qBAAqB,EAAE,CAAC,CAAC;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB,CAAC,KAAK,EAAE,SAAS,SAAS,kBAAkB;IACjF,oEAAoE;IACpE,QAAQ,EAAE,SAAS,CAAC;IACpB,6DAA6D;IAC7D,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,SAAS,EAAE,MAAM,CAAC,CAAC;IACjE,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,YAAY,CAAC,EAAE,KAAK,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,KAAK,EACL,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,qBAAqB,CAAC,KAAK,CAAC,GAC9B,CAAC,sBAAsB,CAAC,KAAK,CAAC,GAAG,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;AAE7E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,KAAK,GACV,SAAS,CAAC;AAwCb,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,KAAK,EAC9C,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,KAAK,EACX,QAAQ,EAAE,wBAAwB,GACjC,SAAS,CAqEX;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAmBlF"}

package/dist/tools/mcp/prepare.d.ts

@@ -0,0 +1,76 @@
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import type { z } from 'zod';
+import type { ServiceDef, StitchLogger } from '../../server/types.js';
+import type { ErrorHintFn } from '../execute-hooks.js';
+import type { ToolResult } from '../execute-result.js';
+import { type McpProjectionPreparationConfig, type McpSchemaValidationConfig } from '../internal/surface-projector.js';
+import { type MountableTool, type ToolExtend } from '../mount.js';
+import type { RuntimeToolDefinition } from '../runtime-tool.js';
+import type { ToolPresentationSchema } from '../schema/flatten.js';
+import { type ToolSurfaceDefinition } from '../surface.js';
+/**
+ * What to do when a tool's schema cannot be advertised on the MCP surface — a
+ * union / discriminated-union input (MCP needs an object), or a construct
+ * JSON Schema cannot represent (`z.date()`, `z.map()`, …):
+ * - `throw` (default) — fail the build loudly, listing every bad tool. Better
+ *   a failed deploy than a tool that silently vanishes from the MCP surface.
+ * - `warn` — log and drop the tool.
+ * - `skip` — drop the tool silently.
+ */
+/** One schema policy shared by validation, mounting and every MCP transport. */
+export type { IncompatibleSchemaPolicy, McpSchemaValidationConfig, } from '../internal/surface-projector.js';
+/** Standalone schema-validation input, including the exact surface-shaping options. */
+export interface ValidateMcpSchemasConfig extends McpSchemaValidationConfig {
+    services: ServiceDef[];
+    logger?: StitchLogger;
+    extend?: ToolExtend;
+    flattenUnionInput?: boolean;
+}
+/** How a tool's result maps to MCP `structuredContent`. */
+export type StructuredMode = 'none' | 'direct';
+/**
+ * Shape a `ToolResult` into an MCP tool response. Always emits a text `content`
+ * block for declared output (the model reads it). Emits `structuredContent`
+ * in the exact validated JSON shape whenever the tool declared an
+ * `outputSchema`. The official SDK owns any protocol-era wire adaptation.
+ */
+export declare function formatMcpResult(result: ToolResult, mode: StructuredMode, toolName?: string, errorHint?: ErrorHintFn): CallToolResult;
+/** One immutable descriptor cleared to register on any fresh MCP server. */
+export interface PreparedMcpTool {
+    mountable: MountableTool;
+    inputSchema: ToolPresentationSchema;
+    outputSchema?: z.ZodType;
+    outputMode: StructuredMode;
+}
+export type PreparedMcpSurface = readonly PreparedMcpTool[];
+export interface McpSurfacePreparationConfig extends McpProjectionPreparationConfig {
+    extend?: ToolExtend;
+    logger?: StitchLogger;
+}
+/**
+ * Prepare the deterministic MCP surface once. No auth, context, hooks,
+ * lifecycle closures, server or transport enters this value.
+ */
+export declare function prepareMcpSurface(services: ServiceDef | ServiceDef[], config?: McpSurfacePreparationConfig): PreparedMcpSurface;
+/** One immutable, framework-managed MCP surface selected as a unit. */
+export interface McpSurfaceDefinition extends ToolSurfaceDefinition {
+    services: ServiceDef[];
+}
+/** A finite set of surfaces known when the server/handler is constructed. */
+export type McpSurfaceRegistry = Record<string, McpSurfaceDefinition>;
+/** A runtime definition paired with its already validated MCP descriptor. */
+export interface PreparedRuntimeMcpTool {
+    definition: RuntimeToolDefinition;
+    descriptor: PreparedMcpTool;
+}
+/** Complete immutable tool descriptors for one fresh MCP server runtime. */
+export interface PreparedMcpServerSurface {
+    contractTools: PreparedMcpSurface;
+    runtimeTools: readonly PreparedRuntimeMcpTool[];
+}
+/**
+ * Prepare contracts and framework runtime tools as one collision-checked unit.
+ * No auth, request context, lifecycle, hooks, SDK server or transport is stored.
+ */
+export declare function prepareMcpServerSurface(surface: McpSurfaceDefinition, config?: McpSurfacePreparationConfig): PreparedMcpServerSurface;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/tools/mcp/prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/prepare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAE/B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC9F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;GAQG;AACH,gFAAgF;AAChF,YAAY,EACV,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,+BAA+B,CAAC;AAEvC,uFAAuF;AACvF,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAOD,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,cAAc,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,WAAW,GACtB,cAAc,CAyBhB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,sBAAsB,CAAC;IACpC,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAAG,SAAS,eAAe,EAAE,CAAC;AAE5D,MAAM,WAAW,2BAA4B,SAAQ,8BAA8B;IACjF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,2BAAgC,GACvC,kBAAkB,CAIpB;AA0CD,uEAAuE;AACvE,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,qBAAqB,CAAC;IAClC,UAAU,EAAE,eAAe,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,kBAAkB,CAAC;IAClC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,MAAM,GAAE,2BAAgC,GACvC,wBAAwB,CAoC1B"}

package/dist/tools/mcp/progress.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Progress for a call that is still running.
+ *
+ * A tool that takes ten minutes tells a text host nothing today: the call is
+ * made, and the next thing the host sees is the answer. The protocol has the
+ * channel for this — the host sends a `progressToken` in the request's `_meta`
+ * and the server relates `notifications/progress` to that request — and the
+ * framework simply never read the token.
+ *
+ * Both places that can report live here, so there is one implementation of
+ * "what a progress update is": the contract-tool path (`mcp-round.ts`, which
+ * hands `reportProgress` to the handler) and the native wait tool
+ * (`mount-wait.ts`, which reports its own poll ticks).
+ */
+import type { ServerContext } from '@modelcontextprotocol/server';
+import type { McpReportProgress } from '../../contract/runtime-context.js';
+/**
+ * The host's progress token, or `undefined` when it asked for none.
+ *
+ * It rides in the request's own `_meta`, beside the trace keys, and survives
+ * the SDK's envelope lift because it is not an envelope key. `_meta` itself can
+ * be absent entirely — the SDK drops it when the lift empties it — so "no
+ * `_meta`" and "`_meta` without a token" have to mean the same thing here.
+ */
+export declare function mcpProgressToken(context: ServerContext): string | number | undefined;
+/**
+ * Build the reporter for one call.
+ *
+ * Without a token it is a no-op, so nothing upstream has to ask whether the
+ * host is listening. With one, every update is a `notifications/progress`
+ * related to this request.
+ *
+ * `progress` is required by the protocol and is often the one thing a handler
+ * does not know — it has a stage to name and no scale to name it on. An
+ * omitted one becomes the ordinal of this update, which is a fact about what
+ * happened; a synthesised percentage would be a claim nobody measured. `total`
+ * stays absent in that case, so a host renders an unbounded counter rather
+ * than a bar stuck at 3%.
+ *
+ * Nothing here can fail the call. A transport that refuses the notification
+ * leaves the host without progress, which is exactly the state of every host
+ * that never asked for it — and a message about work must not be able to kill
+ * the work it describes.
+ */
+export declare function createMcpProgressReporter(context: ServerContext): McpReportProgress;
+//# sourceMappingURL=progress.d.ts.map

package/dist/tools/mcp/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAE3F;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAGpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,GAAG,iBAAiB,CA4BnF"}

package/dist/tools/mcp/register.d.ts

@@ -0,0 +1,36 @@
+import { type CallToolResult, type McpServer } from '@modelcontextprotocol/server';
+import type { EndpointToolAnnotations, EndpointUiMeta } from '../../contract/tool-options.js';
+import type { ToolExecutionOptions } from '../execute.js';
+import { type ToolResult } from '../execute-result.js';
+import type { MountableTool } from '../mount.js';
+import { type McpCatalogStamp } from './catalog.js';
+import type { PreparedMcpTool } from './prepare.js';
+import { type McpRoundRuntime } from './round.js';
+/** What the host is told about a tool — contract endpoints and runtime tools alike. */
+export interface McpToolPresentation {
+    name: string;
+    description: string;
+    annotations?: EndpointToolAnnotations;
+    ui?: EndpointUiMeta;
+    /** A runtime tool's own MCP answer, built from its validated output. */
+    present?: (data: unknown) => unknown | Promise<unknown>;
+}
+/** The runner every registered tool calls through — `createToolRunner`'s. */
+export type McpToolRunner = (tool: MountableTool, rawArgs: Record<string, unknown>, context?: Record<string, unknown>, options?: Pick<ToolExecutionOptions, 'finalizeOutput'>) => Promise<ToolResult>;
+export interface McpToolRegistrationConfig {
+    runTool: McpToolRunner;
+    formatResult: (result: ToolResult, mode: PreparedMcpTool['outputMode'], toolName: string) => CallToolResult;
+    catalog?: McpCatalogStamp;
+    multiRoundRuntime?: McpRoundRuntime;
+}
+/**
+ * Register one prepared tool on one MCP server — the only place a tool's
+ * listing, `_meta`, catalog stamp, request context and elicitation rounds are
+ * assembled. Contract endpoints and runtime tools differ in where their
+ * description and hints come from and in whether a presenter shapes the answer;
+ * they never differ in protocol. A failure thrown anywhere in the call answers
+ * as an `isError` tool result: MCP reserves JSON-RPC errors for the protocol, and
+ * a tool's own failure is a result the model can read.
+ */
+export declare function registerMcpTool(server: McpServer, presentation: McpToolPresentation, descriptor: PreparedMcpTool, config: McpToolRegistrationConfig): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/mcp/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/register.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,EAAE,KAAK,eAAe,EAA0C,MAAM,WAAW,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,SAAS,CAAC;AAGhE,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,KACnD,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,eAAe,CAAC,YAAY,CAAC,EACnC,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,iBAAiB,CAAC,EAAE,eAAe,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,mBAAmB,EACjC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAoGN"}

package/dist/tools/mcp/round-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The per-round pieces of an MCP input round: the transport context a round
+ * runs under, the operation identity a continuation is bound to, and the two
+ * shapes a round pass takes through the tool pipeline — a guard pass that
+ * returns nothing, and a refusal that reports through the pipeline's own
+ * failure path.
+ */
+import { type CallToolResult, type ServerContext } from '@modelcontextprotocol/server';
+import type { McpCallContext, McpReportProgress, McpRoundOutcome } from '../../contract/runtime-context.js';
+import type { ToolResult } from '../execute-result.js';
+import type { MountableTool } from '../mount.js';
+import type { McpRoundResolution } from './round.js';
+export interface RoundOperationIdentity {
+    toolName: string;
+    serviceName: string;
+    action: string;
+    method: string;
+    scope?: string;
+}
+export type ToolRunner = (tool: MountableTool, rawArgs: Record<string, unknown>, context?: Record<string, unknown>) => Promise<ToolResult>;
+export declare function transportContext(context: ServerContext, toolName: string, outcome?: McpRoundOutcome, round?: number): {
+    signal: AbortSignal;
+    mcp: McpCallContext;
+    reportProgress: McpReportProgress;
+};
+export declare function operationIdentity(tool: MountableTool): RoundOperationIdentity;
+export declare function sameIdentity(left: RoundOperationIdentity, right: RoundOperationIdentity): boolean;
+export declare function runRoundSuccess(tool: MountableTool, rawArgs: Record<string, unknown>, runTool: ToolRunner, context: Record<string, unknown>): Promise<ToolResult>;
+export declare function failedResolution(options: {
+    tool: MountableTool;
+    rawArgs: Record<string, unknown>;
+    runTool: ToolRunner;
+    context: Record<string, unknown>;
+    code: string;
+    message: string;
+    formatFailure: (result: ToolResult) => CallToolResult;
+}): Promise<McpRoundResolution>;
+//# sourceMappingURL=round-context.d.ts.map

package/dist/tools/mcp/round-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-context.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/round-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EAChB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,CACvB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,cAAc,CAAC;IAAC,cAAc,EAAE,iBAAiB,CAAA;CAAE,CA8BjF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,sBAAsB,CAQ7E;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,sBAAsB,EAC5B,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAQT;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,UAAU,CAAC,CAarB;AA0BD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,cAAc,CAAC;CACvD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAU9B"}

package/dist/tools/mcp/round-policy.d.ts

@@ -0,0 +1,33 @@
+import type { EndpointMcpInputRequired, EndpointMcpPolicy } from '../../contract/tool-options.js';
+/**
+ * The declared rounds, when the declaration is a fixed list.
+ *
+ * A resolver has nothing to read at declaration time — that is the whole point
+ * of it — so everything that inspects a policy statically (surface projection,
+ * the surface fingerprint, mount-time validation) asks this first and treats
+ * `undefined` as "known only per call".
+ */
+export declare function staticInputRounds(policy: EndpointMcpPolicy): readonly EndpointMcpInputRequired[] | undefined;
+/** Validate declarative multi-round policy without importing the optional MCP SDK. */
+export declare function validateMcpRoundPolicy(tool: {
+    name: string;
+}, policy: EndpointMcpPolicy, runtime?: {
+    stateConfigured: boolean;
+    maxRounds: number;
+}): void;
+/**
+ * Validate what a resolver actually returned, on the call that returned it.
+ *
+ * The same two rules the static list is held to — unique keys, no more rounds
+ * than the runtime allows — because a resolver can break both, and a policy
+ * that is only checked when it happens to be written down is not checked.
+ *
+ * An empty list is legal here and only here: for a resolver it means "this call
+ * needs nothing", which is the answer the feature exists to allow. Declaring
+ * zero rounds statically still means the author wrote a policy that can never
+ * ask anything, and that stays an error.
+ */
+export declare function validateResolvedInputRounds(tool: {
+    name: string;
+}, resolved: readonly EndpointMcpInputRequired[], maxRounds: number): void;
+//# sourceMappingURL=round-policy.d.ts.map

package/dist/tools/mcp/round-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-policy.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/round-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAE/F;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB,SAAS,wBAAwB,EAAE,GAAG,SAAS,CAEjD;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxD,IAAI,CAqBN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtB,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAC7C,SAAS,EAAE,MAAM,GAChB,IAAI,CAEN"}

package/dist/tools/mcp/round.d.ts

@@ -0,0 +1,53 @@
+import { type CallToolResult, type InputRequiredResult, type RequestStateCodec, type ServerContext } from '@modelcontextprotocol/server';
+import type { EndpointMcpPolicy } from '../../contract/tool-options.js';
+import type { ToolResult } from '../execute-result.js';
+import type { MountableTool } from '../mount.js';
+import { type RoundOperationIdentity, type ToolRunner } from './round-context.js';
+/** Signed continuation payload. It is authenticated, not encrypted. */
+export interface McpRoundState {
+    identity: RoundOperationIdentity;
+    argumentsDigest: string;
+    round: number;
+    accepted: Record<string, unknown>;
+    /**
+     * Fingerprint of the question plan this conversation started with.
+     *
+     * `argumentsDigest` proves the ARGUMENTS did not change; it says nothing
+     * about the questions, and those are now allowed to be computed. Between two
+     * rounds there is a full round trip to the host, and a resolver that reads
+     * anything outside its arguments — which is exactly the case this feature
+     * exists for — can answer differently the second time. Every other check
+     * would still pass: same principal, same operation, same digest, `round`
+     * still in range. Round 2's question would be asked under round 1's key, the
+     * answer would be accepted if the schemas happened to be compatible, and the
+     * handler would receive an answer to a question nobody asked.
+     *
+     * So the plan is fingerprinted when it is minted and re-checked on every
+     * round. A plan that moved is a refusal, not a different question.
+     */
+    planDigest: string;
+}
+export interface McpRoundRuntime {
+    codec: RequestStateCodec<McpRoundState>;
+    maxRounds: number;
+}
+export type McpRoundResolution = {
+    kind: 'continue';
+    context?: Record<string, unknown>;
+} | {
+    kind: 'response';
+    response: CallToolResult | InputRequiredResult;
+};
+/** Resolve an ordered opt-in MRTR sequence before the canonical handler executes. */
+export declare function resolveMcpRound(options: {
+    tool: MountableTool;
+    rawArgs: Record<string, unknown>;
+    context: ServerContext;
+    policy?: EndpointMcpPolicy;
+    runtime?: McpRoundRuntime;
+    runTool: ToolRunner;
+    formatFailure: (result: ToolResult) => CallToolResult;
+    /** The mount's JSON-coercion setting, so the resolver parses as the call does. */
+    coerceJsonArgs?: boolean;
+}): Promise<McpRoundResolution>;
+//# sourceMappingURL=round.d.ts.map

package/dist/tools/mcp/round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/round.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAGxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,6BAA6B,CAAC;AAIrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAGL,KAAK,sBAAsB,EAG3B,KAAK,UAAU,EAEhB,MAAM,iBAAiB,CAAC;AAOzB,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,mBAAmB,CAAA;CAAE,CAAC;AAyIzE,qFAAqF;AACrF,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,cAAc,CAAC;IACtD,kFAAkF;IAClF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqL9B"}

package/dist/tools/mcp/runtime-tools.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
+import type { ToolCallHooks, ToolLifecycle } from '../execute-hooks.js';
+import type { ToolResult } from '../execute-result.js';
+import type { McpCatalogStamp } from './catalog.js';
+import type { PreparedRuntimeMcpTool } from './prepare.js';
+import type { McpRoundRuntime } from './round.js';
+interface NativeMcpRuntimeConfig {
+    context?: Record<string, unknown>;
+    hooks?: ToolCallHooks;
+    lifecycle?: ToolLifecycle;
+    coerceJsonArgs?: boolean;
+    onOutputStrip?: (toolName: string, paths: string[]) => void;
+    multiRoundRuntime?: McpRoundRuntime;
+    /** The catalog this surface advertises, stamped onto listings and results. */
+    catalog?: McpCatalogStamp;
+    formatResult: (result: ToolResult, mode: PreparedRuntimeMcpTool['descriptor']['outputMode'], toolName: string) => CallToolResult;
+}
+/**
+ * Mount immutable runtime-tool descriptors onto one fresh MCP server/runtime —
+ * through the same runner and the same registration as contract endpoints; a
+ * runtime tool only brings its own description, hints and MCP presenter.
+ */
+export declare function mountPreparedRuntimeMcp(server: McpServer, tools: readonly PreparedRuntimeMcpTool[], config: NativeMcpRuntimeConfig): void;
+export {};
+//# sourceMappingURL=runtime-tools.d.ts.map

package/dist/tools/mcp/runtime-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/runtime-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,UAAU,sBAAsB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,EACxD,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CA8BN"}