stitchkit 0.93.0 → 0.94.1

package/dist/tools/execute.d.ts

@@ -1,29 +1,10 @@
 import type { ZodType, z } from 'zod';
-import { AppError, type McpCallContext, type RuntimeContext, type TransportSource } from '../contract/index.js';
+import type { TransportSource } from '../contract/define.js';
+import type { RuntimeContext } from '../contract/runtime-context.js';
+import type { EndpointToolView } from '../contract/tool-view.js';
 import type { OperationIdentity } from '../server/types.js';
-export type ToolResult = {
-    ok: true;
-    data: unknown;
-} | {
-    ok: false;
-    code: string;
-    details?: unknown;
-    hint?: string;
-    /**
-     * A declared retry class, carried so it survives a process hop.
-     *
-     * The normalized `AppError` lives in a `WeakMap` keyed by the result
-     * object, which a serialized failure crossing MCP or the CLI cannot take
-     * with it — `toolErrorFromResult` rebuilds from `{code, details, hint}`
-     * and resolves the status from the code. A declaration that contradicts
-     * its status class would be lost exactly there, which is the failure
-     * already recorded for coding-tool refusals.
-     */
-    retryable?: boolean;
-};
-type ToolFailure = Extract<ToolResult, {
-    ok: false;
-}>;
+import type { ToolCallContext, ToolCallHooks, ToolLifecycle } from './execute-hooks.js';
+import { type ToolResult } from './execute-result.js';
 export type ToolExecutionControlReason = 'stale_run' | 'run_interrupted';
 /** Internal control flow that must never be converted into a model-facing tool failure. */
 export declare class ToolExecutionControlError extends Error {
@@ -31,147 +12,13 @@ export declare class ToolExecutionControlError extends Error {
     constructor(reason: ToolExecutionControlReason);
 }
 export declare function isToolExecutionControlError(value: unknown): value is ToolExecutionControlError;
-export interface ToolCallContext {
-    source: TransportSource;
-    /** Validated metadata for an MCP call; absent on every other transport. */
-    mcp?: McpCallContext;
-    /**
-     * The provider's id for this tool call, on a surface that has one — today
-     * `mountAgent`, where it is the AI SDK's `toolCallId`.
-     *
-     * Without it a consumer running its own agent loop could see the outcome of a
-     * call through `afterToolCall` and had no way to say WHICH call it belonged
-     * to, so it reconstructed the answer from the serialised error text instead.
-     * That reconstruction is the defect: it is written once per consumer and
-     * disagrees silently.
-     */
-    toolCallId?: string;
-    [key: string]: unknown;
-}
-export interface BeforeToolCallOptions {
-    toolName: string;
-    args: Record<string, unknown>;
-    context: ToolCallContext;
-    endpoint: OperationIdentity;
-}
-export interface AfterToolCallOptions extends BeforeToolCallOptions {
-    result: ToolResult;
-    durationMs: number;
-    /** The value as thrown; absent for failures that did not throw. */
-    error?: unknown;
-    /**
-     * The arguments the call actually ran on, when `beforeToolCall` replaced
-     * them. Absent when nothing rewrote them — so `args` alone stays the honest
-     * record of what the caller sent, and a rewrite is visible as a rewrite
-     * rather than by overwriting the evidence.
-     */
-    effectiveArgs?: Record<string, unknown>;
-}
-export interface ToolErrorOptions {
-    toolName: string;
-    error: unknown;
-    context: ToolCallContext;
-    endpoint: OperationIdentity;
-}
-export interface ToolCallHooks {
-    /**
-     * Before the arguments are validated — and the one place they can still be
-     * changed.
-     *
-     * Returning a record replaces the arguments for this call; returning
-     * `undefined`, `null` or nothing leaves them exactly as they arrived. The
-     * replacement is validated by the contract schema like any other input, so
-     * this is a way to shape a call, never a way around the schema: a hook that
-     * returns something the schema refuses produces an ordinary
-     * `VALIDATION_ERROR`.
-     *
-     * This exists because the pipeline was asymmetric. `lifecycle.afterHandle`
-     * could already transform the OUTPUT, while the only way to affect the input
-     * was to throw — so a caller wanting to expand a reference into a value
-     * before validation had nowhere to stand: this hook sees the raw arguments
-     * and could not change them, and `lifecycle.beforeHandle` runs after the
-     * schemas have already refused.
-     *
-     * The audit trail is unaffected: `afterToolCall` still reports `args` as they
-     * arrived from the caller, and reports the replacement separately as
-     * `effectiveArgs`.
-     *
-     * Typed `unknown` for the same reason `lifecycle.afterHandle` is — the twin
-     * this mirrors. Every hook written against the old `void` signature still
-     * assigns, which is the whole compatibility claim, and a narrower union here
-     * would break exactly the hooks that exist today. What the value must BE is
-     * enforced where it is used, not where it is declared: anything that is not a
-     * record, `null` or `undefined` is refused by name at the call.
-     */
-    beforeToolCall?: (options: BeforeToolCallOptions) => unknown | Promise<unknown>;
-    /**
-     * Every finished call, success and failure alike — the record of the call.
-     *
-     * `error` is the value **as thrown**, present only when the call failed by
-     * throwing (never for an argument-validation failure, an output-schema
-     * mismatch or a `beforeToolCall` rejection — those never had a raw value).
-     * It is the same value `onToolError` receives, handed here too so a single
-     * hook can build one row that names the cause: the `result` alone cannot,
-     * because an unexpected throw is scrubbed to a bare `INTERNAL_SERVER_ERROR`.
-     */
-    afterToolCall?: (options: AfterToolCallOptions) => void | Promise<void>;
-    /**
-     * The tool execution path threw — the value **as thrown**, before it is normalised
-     * into a `ToolResult`. The tool-side answer to HTTP's `hooks.onError`, and the
-     * only place the real cause of an unexpected failure is reachable: an error
-     * that is not an `AppError` is scrubbed to a bare `INTERNAL_SERVER_ERROR` with
-     * no details, so by the time `afterToolCall` sees the result, the stack, the
-     * `cause` chain and the message are gone.
-     *
-     * Fires for a throw from executable input parsing (`ToolExtend`, params or
-     * input), extension resolution, `lifecycle.beforeHandle`, the handler, or
-     * `lifecycle.afterHandle` — every span where the raw cause would otherwise be
-     * destroyed. It does **not** fire for a normal validation result, a
-     * `beforeToolCall` rejection or an output-schema mismatch: each is already
-     * described in full by the `ToolResult` that `afterToolCall` receives.
-     *
-     * This is observation, not an error handler — the tool envelope is always
-     * `toolResultFromError`, so the return value is ignored and a throw from the
-     * hook itself is reported and swallowed rather than replacing the failure it
-     * was called to observe. Awaited before `afterToolCall`, so anything the hook
-     * records (a request-context error, say) is already in place when the audit
-     * hook reads it.
-     */
-    onToolError?: (options: ToolErrorOptions) => void | Promise<void>;
-}
-/**
- * A per-tool hint appended to a failed tool result — given the tool name and the
- * error code, return extra guidance for the model (or `null` for none). Shared
- * by every tool mount (`mountMcp` / `mountAgent` / `createCli`), so a project
- * writes one recovery-hint policy and it reaches all three transports.
- */
-export type ErrorHintFn = (toolName: string, errorCode: string) => string | null;
-/**
- * The tool-side twin of the HTTP server's `beforeHandle` / `afterHandle`. A
- * tool call runs the same handler an HTTP request would — `ToolLifecycle` makes
- * it run the same gate. Pass a `createAuthHook` result as `beforeHandle` here
- * and tools are scope-guarded exactly as HTTP routes are; without it a tool
- * call bypasses the auth a `createServer` `beforeHandle` enforces.
- *
- * Structurally a subset of `LifecycleHooks` — the same hook object used for
- * `createServer({ hooks })` is assignable here.
- *
- * There is deliberately no `onError` twin: `LifecycleHooks.onError` returns a
- * `Response`, which the tool path has no use for, and narrowing the return type
- * here would break the assignability above. Observing a thrown tool error is
- * `ToolCallHooks.onToolError`.
- */
-export interface ToolLifecycle {
-    /** Auth / scope gate — throw to reject the call. */
-    beforeHandle?: (ctx: RuntimeContext, endpoint: OperationIdentity) => void | Promise<void>;
-    /** Transform the handler result before it is returned. */
-    afterHandle?: (ctx: RuntimeContext, result: unknown, endpoint: OperationIdentity) => unknown | Promise<unknown>;
-}
 /** Executable tool operation; contract methods and native tools share this runner shape. */
 export interface ToolOperation extends OperationIdentity {
     paramsSchema?: ZodType;
     inputSchema?: ZodType;
     outputSchema?: ZodType;
+    /** Applied only by a runner built for the tool surface. → ADR 0196. */
+    toolView?: EndpointToolView;
     handler(ctx: RuntimeContext): unknown | Promise<unknown>;
 }
 /** Executable extension parsed once inside the shared runner before resolution. */
@@ -179,38 +26,30 @@ export interface ToolArgumentExtension {
     schema: z.ZodObject;
     resolve: (args: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
-/**
- * Normalise any thrown value into a failed `ToolResult` — the one place an
- * `AppError` becomes a tool error. Shared by `executeToolMethod` and both
- * transport mounts so every tool error has one shape.
- */
-/** What one tool call's arguments parse to — or why they did not. */
-export type ParsedToolCallArguments = {
-    ok: true;
-    params: unknown;
-    input: unknown;
-} | {
-    ok: false;
-    message: string;
-    thrown?: unknown;
-};
-/**
- * Split and validate a flat tool-argument object exactly as a call does.
- *
- * Exported so the ONE thing that needs the parsed value without running the
- * call — an elicitation resolver choosing this call's questions — gets the same
- * value the handler will get, rather than a second parse written beside this
- * one that drifts on the next coercion change. It is pure: no lifecycle, no
- * hooks, no audit row, so asking what the arguments mean costs nothing that a
- * gate would charge for.
- */
-export declare function parseToolCallArguments(method: ToolOperation, callArgs: Record<string, unknown>, coerceJson: boolean): ParsedToolCallArguments;
-export declare function toolResultFromError(err: unknown): ToolFailure;
-/** Recover the normalized AppError behind one canonical failed tool result. */
-export declare function toolErrorFromResult(result: ToolFailure): AppError;
-/** Original in-process failure; never part of the serialized tool envelope. */
-export declare function toolCauseFromResult(result: ToolFailure): unknown;
-export declare function executeToolMethod(method: ToolOperation, toolName: string, rawArgs: Record<string, unknown>, context: ToolCallContext, hooks?: ToolCallHooks, lifecycle?: ToolLifecycle, coerceJson?: boolean, onOutputStrip?: (paths: string[]) => void, extension?: ToolArgumentExtension, finalizeOutput?: (data: unknown) => unknown | Promise<unknown>): Promise<ToolResult>;
+/** What one tool call is: the name it was called by, its raw arguments, its context. */
+export interface ToolCall {
+    toolName: string;
+    rawArgs: Record<string, unknown>;
+    context: ToolCallContext;
+}
+/** How a call is run — every knob optional, named, and off unless set. */
+export interface ToolExecutionOptions {
+    /** Tool-call observability hooks. */
+    hooks?: ToolCallHooks;
+    /** Auth / scope gate and result transform. */
+    lifecycle?: ToolLifecycle;
+    /** Coerce JSON-stringified arrays/objects in the arguments (LLM double-serialization). */
+    coerceJson?: boolean;
+    /** Report handler-output keys the contract schema removed. → ADR 0037. */
+    onOutputStrip?: (paths: string[]) => void;
+    /** Extend arguments resolved, then stripped, before the parse. */
+    extension?: ToolArgumentExtension;
+    /** Last transformation of validated output — a runtime tool's presenter. */
+    finalizeOutput?: (data: unknown) => unknown | Promise<unknown>;
+    /** Answer as the tool surface: apply the endpoint's `toolView`. → ADR 0196. */
+    toolSurface?: boolean;
+}
+export declare function executeToolMethod(method: ToolOperation, call: ToolCall, options?: ToolExecutionOptions): Promise<ToolResult>;
 /**
  * Run `body` in a request context forked for one tool call — the shared rule,
  * so every entry point isolates the same way. A mount uses it around
@@ -226,5 +65,4 @@ export declare function inToolCallContext<T>(call: {
     toolName: string;
     method: OperationIdentity;
 }, body: () => Promise<T>): Promise<T>;
-export {};
 //# sourceMappingURL=execute.d.ts.map

package/dist/tools/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EACL,QAAQ,EAGR,KAAK,cAAc,EACnB,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAKrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAIzD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEN,KAAK,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAEtD,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEzE,2FAA2F;AAC3F,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAE5C,YAAY,MAAM,EAAE,0BAA0B,EAI7C;CACF;AAaD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,yBAAyB,CAEpC;AAaD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,iBAAiB,KACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjE;AAED;;;;GAIG;AAEH,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,UAAU,EAAE,OAAO,GAClB,uBAAuB,CAkDzB;AAKD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAkB7D;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAgBjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEhE;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,aAAa,EACzB,UAAU,UAAQ,EAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,EACzC,SAAS,CAAC,EAAE,qBAAqB,EACjC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC7D,OAAO,CAAC,UAAU,CAAC,CA0BrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE;IACJ,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,EACD,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"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"}

package/dist/tools/internal/surface-projector.d.ts

@@ -1,8 +1,8 @@
 import { type ZodObject, type ZodType } from 'zod';
-import type { EndpointMcpPolicy, EndpointToolAnnotations, EndpointUiMeta, HttpMethod } from '../../contract/index.js';
+import type { HttpMethod, ToolTransport } from '../../contract/define.js';
+import type { EndpointMcpPolicy, EndpointToolAnnotations, EndpointUiMeta } from '../../contract/tool-options.js';
 import type { MethodDef, ServiceDef, StitchLogger } from '../../server/types.js';
-import type { ToolPresentationSchema } from '../flatten.js';
-export type ProjectedToolTransport = 'MCP' | 'AGENT' | 'CLI';
+import type { ToolPresentationSchema } from '../schema/flatten.js';
 /** Non-executable runtime-tool shape needed to project names and advertised schemas. */
 export interface SurfaceRuntimeToolDefinition {
     name: string;
@@ -16,7 +16,7 @@ export interface SurfaceRuntimeToolDefinition {
     };
     input: ZodObject;
     output?: ZodType;
-    transports?: readonly ProjectedToolTransport[];
+    transports?: readonly ToolTransport[];
     annotations?: EndpointToolAnnotations;
     ui?: EndpointUiMeta;
     mcp?: EndpointMcpPolicy;
@@ -69,9 +69,9 @@ export interface ProjectedRuntimeTool<TRuntime extends SurfaceRuntimeToolDefinit
 export type ProjectedTool<TRuntime extends SurfaceRuntimeToolDefinition = SurfaceRuntimeToolDefinition> = ProjectedContractTool | ProjectedRuntimeTool<TRuntime>;
 /** Canonical runtime descriptor projection, independent of one transport's exposure filter. */
 export declare function projectRuntimeTool<TRuntime extends SurfaceRuntimeToolDefinition>(definition: TRuntime, assertName?: boolean): ProjectedRuntimeTool<TRuntime>;
-export declare function projectedRuntimeToolSupports(definition: SurfaceRuntimeToolDefinition, transport: ProjectedToolTransport): boolean;
+export declare function projectedRuntimeToolSupports(definition: SurfaceRuntimeToolDefinition, transport: ToolTransport): boolean;
 /** Canonical name/exposure/presentation projection shared by mounts and manifests. */
-export declare function projectToolSurface<TRuntime extends SurfaceRuntimeToolDefinition>(surface: ToolSurfaceProjection<TRuntime>, transport: ProjectedToolTransport, config?: ToolPresentationProjectionConfig): ProjectedTool<TRuntime>[];
+export declare function projectToolSurface<TRuntime extends SurfaceRuntimeToolDefinition>(surface: ToolSurfaceProjection<TRuntime>, transport: ToolTransport, config?: ToolPresentationProjectionConfig): ProjectedTool<TRuntime>[];
 export type IncompatibleSchemaPolicy = 'throw' | 'skip' | 'warn';
 export interface McpSchemaValidationConfig {
     policy?: IncompatibleSchemaPolicy;
@@ -93,6 +93,9 @@ export interface McpProjectionCandidate<TTool> {
     name: string;
     paramsSchema?: ZodType;
     inputSchema?: ZodType;
+    /** A tool view's input defaults, stated in the advertised input schema. */
+    inputDefaults?: Readonly<Record<string, unknown>>;
+    /** The tool-surface answer's schema — a tool view's, when one is declared. */
     outputSchema?: ZodType;
     shouldExtend: boolean;
     mcp?: EndpointMcpPolicy;

package/dist/tools/internal/surface-projector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-projector.d.ts","sourceRoot":"","sources":["../../../src/tools/internal/surface-projector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface-projector.d.ts","sourceRoot":"","sources":["../../../src/tools/internal/surface-projector.ts"],"names":[],"mappings":"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"}

package/dist/tools/internal/tool-view.d.ts

@@ -0,0 +1,41 @@
+import type { ZodType } from 'zod';
+import type { TransportSource } from '../../contract/define.js';
+import type { EndpointToolView } from '../../contract/tool-view.js';
+/** The schema a tool-surface answer is validated and advertised against. */
+export declare function toolSurfaceOutputSchema(operation: {
+    outputSchema?: ZodType;
+    toolView?: EndpointToolView;
+}): ZodType | undefined;
+/**
+ * Fill the keys a tool call did not pass with the view's defaults — before the
+ * endpoint's own `input` parses them, so there is one parser and the handler
+ * cannot tell a default from a value the model chose. A key the caller passed,
+ * `null` included, is the caller's.
+ */
+export declare function applyToolViewDefaults(inputArgs: Record<string, unknown>, defaults: Readonly<Record<string, unknown>> | undefined): Record<string, unknown>;
+/**
+ * Turn a validated full result into the tool answer: `project` when declared,
+ * otherwise the full value, then validated against the view's schema.
+ *
+ * A throwing or asynchronous `project` is a server fault whatever it threw —
+ * the handler already succeeded, so a `NOT_FOUND` escaping the projection would
+ * tell the model something about the call that is not true.
+ */
+export declare function projectToolView(options: {
+    view: EndpointToolView;
+    fullSchema: ZodType;
+    full: unknown;
+    call: {
+        input: unknown;
+        source: TransportSource;
+    };
+    operation: string;
+    onStripped?: (paths: string[]) => void;
+}): {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=tool-view.d.ts.map

package/dist/tools/internal/tool-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../../src/tools/internal/tool-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,SAAS,EAAE;IACjD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B,GAAG,OAAO,GAAG,SAAS,CAKtB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GACtD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACxC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA+C/D"}

package/dist/tools/invoker.d.ts

@@ -1,17 +1,26 @@
-import { type Transport, type TransportSource } from '../contract/index.js';
+import type { ToolTransport, TransportSource } from '../contract/define.js';
 import type { ServiceDef } from '../server/types.js';
-import { type ToolCallContext, type ToolCallHooks, type ToolLifecycle, type ToolResult } from './execute.js';
+import type { ToolCallContext, ToolCallHooks, ToolLifecycle } from './execute-hooks.js';
+import { type ToolResult } from './execute-result.js';
 import { type ToolExtend } from './mount.js';
-export type ToolInvokerTransport = Exclude<Transport, 'HTTP'>;
 /** Configuration for a compiled in-process contract-tool dispatcher. */
 export interface ToolInvokerConfig {
     /** Existing exposure policy to honour. Required: there is no bypass-all mode. */
-    transport: ToolInvokerTransport;
+    transport: ToolTransport;
     extend?: ToolExtend;
     /** Compiles the same presentation surface as the chosen mount. */
     flattenUnionInput?: boolean;
     /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
     coerceJsonArgs?: boolean;
+    /**
+     * Answer as the tool surface — each endpoint's `toolView` defaults and
+     * projected answer, exactly as the MCP, agent and CLI mounts do. Default
+     * `false`: the invoker's caller is code and gets the full answer, as HTTP
+     * does. Set it when the invoker backs a transport a model reads, because the
+     * schemas `collectTools` and `buildToolManifest` advertise are the tool
+     * surface's. → ADR 0196.
+     */
+    toolSurface?: boolean;
 }
 /** Runtime state for one in-process invocation; never retained by the registry. */
 export interface ToolInvocationOptions {

package/dist/tools/invoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/tools/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAsD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG9F,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAE9D,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,SAAS,EAAE,oBAAoB,CAAC;IAChC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,yDAAyD;IACzD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC7D;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,EAC5C,MAAM,EAAE,iBAAiB,GACxB,WAAW,CA2Db"}
+{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/tools/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAsD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG9F,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,yDAAyD;IACzD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC7D;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,EAC5C,MAAM,EAAE,iBAAiB,GACxB,WAAW,CA4Db"}

package/dist/tools/lifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { ToolLifecycle } from './execute.js';
+import type { ToolLifecycle } from './execute-hooks.js';
 /** Compose tool lifecycle hooks without inventing HTTP-only phases. */
 export declare function composeToolLifecycle(...hooks: readonly (ToolLifecycle | undefined)[]): ToolLifecycle;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/tools/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,uEAAuE;AACvE,wBAAgB,oBAAoB,CAClC,GAAG,KAAK,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,EAAE,GAC/C,aAAa,CAcf"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,uEAAuE;AACvE,wBAAgB,oBAAoB,CAClC,GAAG,KAAK,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,EAAE,GAC/C,aAAa,CAcf"}

package/dist/tools/list-names.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool-name baseline — the final mounted name of every tool across the tool
  * transports, with its `(service, method)` identity. Tool names are partly
- * derived (`toolName` override, else `toToolName(service, method)`), so a
+ * derived (`tool.name`, else `toToolName(service, method)`), so a
  * consumer pins them with a snapshot test / CI diff: an upgrade that would
  * shift a derived name — and silently break MCP client configs — fails the
  * consumer's build instead. Also the mechanical "what changed" diff when
@@ -10,13 +10,13 @@
  * Built on the mixed-surface collector used by the mounts — the listing cannot
  * drift when pathless runtime tools sit beside contract operations.
  */
-import type { ContractDef, Transport } from '../contract/index.js';
+import type { ContractDef, Transport } from '../contract/define.js';
 import { type ToolSurfaceDefinition } from './surface.js';
 /** One mounted tool name and where it comes from. */
 export interface ToolNameEntry {
     /** Whether the operation comes from a contract or a pathless runtime definition. */
     kind: 'contract' | 'runtime';
-    /** Final tool name — the `toolName` override, else derived from service + method. */
+    /** Final tool name — the `tool.name`, else derived from service + method. */
     name: string;
     /** Owning service (`ServiceDef.name` — the contract's prefix). */
     service: string;

package/dist/tools/list-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-names.d.ts","sourceRoot":"","sources":["../../src/tools/list-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,WAAW,CAAC;AAEnB,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,EAAE,CA6B7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CAExF"}
+{"version":3,"file":"list-names.d.ts","sourceRoot":"","sources":["../../src/tools/list-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGjE,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE3E,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,EAAE,CA6B7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CAExF"}

package/dist/tools/manifest.d.ts

@@ -1,5 +1,5 @@
+import type { ToolTransport } from '../contract/define.js';
 import type { CollectToolsConfig } from './mount.js';
-import type { RuntimeToolTransport } from './runtime-tool.js';
 import { type ToolSurfaceDefinition } from './surface.js';
 export interface ToolManifestEntry {
     name: string;
@@ -8,7 +8,7 @@ export interface ToolManifestEntry {
 }
 export interface ToolManifestConfig extends ToolSurfaceDefinition {
     /** Model-facing surface whose exposure rules the manifest must mirror. */
-    transport: RuntimeToolTransport;
+    transport: ToolTransport;
     extend?: CollectToolsConfig['extend'];
     flattenUnionInput?: boolean;
 }

package/dist/tools/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,0EAA0E;IAC1E,SAAS,EAAE,oBAAoB,CAAC;IAChC,MAAM,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,MAAM,EAAE;QAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,CA2BjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,EAAE,CAWjF"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,0EAA0E;IAC1E,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,MAAM,EAAE;QAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,CA2BjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,EAAE,CAWjF"}

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

@@ -0,0 +1,62 @@
+import type { CacheHint } from '@modelcontextprotocol/server';
+/**
+ * MIME type a host uses to recognise an MCP Apps UI resource — it renders the
+ * HTML as an interactive sandboxed iframe rather than displaying the source.
+ */
+export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** Placeholder a widget HTML file carries where the ext-apps runtime is inlined. */
+export declare const EXT_APPS_BUNDLE_PLACEHOLDER = "/*__EXT_APPS_BUNDLE__*/";
+/**
+ * Content-Security-Policy allowlists a widget declares so the host's iframe can
+ * reach external origins (maps to the host's CSP directives). Default is
+ * block-all, so any external image / fetch origin must be listed.
+ */
+export interface McpAppCsp {
+    /** `connect-src` — fetch / XHR / WebSocket origins. */
+    connectDomains?: string[];
+    /** `img-src` / `script-src` / `style-src` / `font-src` / `media-src` origins. */
+    resourceDomains?: string[];
+    /** `frame-src` — nested iframe origins (currently restricted in some hosts). */
+    frameDomains?: string[];
+    /** `base-uri` origins. */
+    baseUriDomains?: string[];
+}
+/** UI metadata attached to a served resource's content (`_meta.ui`). */
+export interface McpAppResourceMeta {
+    csp?: McpAppCsp;
+    /** Drop the host's outer card border (mobile). */
+    prefersBorder?: boolean;
+    /** Stable origin for external-API CORS allowlists. */
+    domain?: string;
+}
+/**
+ * A UI resource served over MCP. `read` returns the widget HTML (already
+ * bundle-inlined). The default `mimeType` is the apps MIME type, so a plain
+ * widget needs only `uri`, `name` and `read`.
+ */
+export interface McpResourceDef {
+    /** `ui://…` uri — must match a tool's `ui.resourceUri`. */
+    uri: string;
+    /** Human-readable name (shown in `resources/list`). */
+    name: string;
+    /** MIME type — defaults to `RESOURCE_MIME_TYPE`. */
+    mimeType?: string;
+    /** Modern MCP freshness for this resource; absent means zero/private. */
+    cacheHint?: CacheHint;
+    /** Optional UI metadata (CSP, border, domain) applied to the content. */
+    ui?: McpAppResourceMeta;
+    /** Return the resource body — the widget HTML for an apps resource. */
+    read: () => string | Promise<string>;
+}
+/**
+ * Inline the `@modelcontextprotocol/ext-apps` browser runtime into a widget's
+ * HTML, replacing `EXT_APPS_BUNDLE_PLACEHOLDER`. The iframe CSP blocks CDN
+ * script fetches, so the runtime must be inlined at startup rather than
+ * imported. `ext-apps` is an optional peer — a clear error is thrown if the
+ * widget needs the bundle but the peer is not installed.
+ *
+ * The bundle's trailing `export{…}` is rewritten to `globalThis.ExtApps = {…}`
+ * so an inline `<script type="module">` can read `globalThis.ExtApps`.
+ */
+export declare function inlineMcpAppBundle(html: string): string;
+//# sourceMappingURL=app.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/app.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oFAAoF;AACpF,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,0BAA0B;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,kDAAkD;IAClD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,yEAAyE;IACzE,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkCvD"}