stitchkit 0.2.0 → 0.4.0

package/dist/tools/cli-wait.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `--wait` polling — block on an async tool result until it reaches a terminal
+ * state. The headline CLI feature (a `Bash(run_in_background)` generation that
+ * notifies when done), kept strictly generic per ADR 0002: the core knows
+ * nothing about generations or statuses. The consumer supplies how to read the
+ * poll target from the first result (`poll`), which tool to re-call (`tool`)
+ * and when it is done (`done`).
+ */
+import type { ToolResult } from './execute';
+export interface CliWaitConfig {
+    /**
+     * Extract the poll-tool arguments from the initial result (e.g. `{ id }` from
+     * a `generate` response). Return `null` when there is nothing to wait on.
+     */
+    poll: (result: unknown) => Record<string, unknown> | null;
+    /** The tool/command name to call on each poll tick (e.g. `get_generation`). */
+    tool: string;
+    /** Done when this returns `true` for a poll result. */
+    done: (result: unknown) => boolean;
+    /** Backoff schedule in seconds; the last entry repeats. Default `[2,3,5,5,8,10]`. */
+    backoff?: number[];
+    /** Max seconds before giving up. Default `600`. */
+    timeout?: number;
+}
+export interface PollParams {
+    /** The result of the initial (non-poll) call. */
+    initial: ToolResult;
+    wait: CliWaitConfig;
+    /** Run a tool by name — the CLI binds this to its tool map + runner. */
+    call: (toolName: string, args: Record<string, unknown>) => Promise<ToolResult>;
+    /** Override `wait.timeout` (from `--wait-timeout`). */
+    timeoutSec?: number;
+    /** Progress callback — the CLI logs ticks to stderr unless `--quiet`. */
+    onTick?: (attempt: number, elapsedSec: number) => void;
+    /** Injectable sleep for tests. */
+    sleepFn?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll `wait.tool` until `wait.done` or the timeout. Returns the last poll
+ * result; returns the initial result untouched when the initial call failed,
+ * already satisfies `done`, or yields no poll target. A timeout produces a
+ * `TIMEOUT` failed `ToolResult`.
+ */
+export declare function pollUntilDone(params: PollParams): Promise<ToolResult>;
+//# sourceMappingURL=cli-wait.d.ts.map

package/dist/tools/cli-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-wait.d.ts","sourceRoot":"","sources":["../../src/tools/cli-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACnC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,wEAAwE;IACxE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/E,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CA0B3E"}

package/dist/tools/cli.d.ts

@@ -0,0 +1,77 @@
+import type { ServiceDef, StitchLogger } from '../server/types';
+import { type ExitCodeMap } from './cli-format';
+import { type CliWaitConfig } from './cli-wait';
+import { type ToolCallHooks, type ToolLifecycle } from './execute';
+export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /** Program name — shown in help and unknown-command messages. */
+    name: string;
+    /** Program version — printed by `--version`. */
+    version: string;
+    /** Contract services exposed as commands — may depend on the resolved identity. */
+    services: ServiceDef[] | ((auth: Awaited<TAuth> | undefined) => ServiceDef[]);
+    /**
+     * Identity for the single CLI invocation — resolved ONCE at startup (from an
+     * env var / token file), like a stdio MCP server, not per call. A value or a
+     * promise of one.
+     */
+    auth?: TAuth | Promise<TAuth>;
+    /**
+     * Context merged into every handler. Typed against the app's context shape
+     * when the CLI is built via `createToolkit<AppContext>()`.
+     */
+    context?: (auth: Awaited<TAuth> | undefined) => TContext;
+    /** Tool-call observability hooks — `afterToolCall` fires for every result. */
+    hooks?: ToolCallHooks;
+    /**
+     * Auth / scope gate — pass the same `createAuthHook` result used for the HTTP
+     * server's `beforeHandle` so a CLI command is guarded identically. Without it
+     * a scoped command bypasses the gate.
+     */
+    lifecycle?: ToolLifecycle;
+    /** Logger for diagnostics — defaults to stderr-safe `console.error`. */
+    logger?: StitchLogger;
+    /** Coerce JSON-stringified arrays/objects in arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Global error hint appended to every failed command's error. */
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+    /** Override exit codes per `ToolResult.code`, merged over the defaults. */
+    exitCodes?: ExitCodeMap;
+    /**
+     * Route a command's unknown `--flags` into a freeform object field, keyed by
+     * command name → field. Lets `generate <model> --prompt … --aspect_ratio 16:9`
+     * fill the model's `parameters` directly, instead of a `--parameters '{json}'`
+     * blob. Values are loosely coerced (`"30"` → `30`, `"true"` → `true`).
+     */
+    passthrough?: Record<string, string>;
+    /** Per-command `--wait` polling behaviour, keyed by command name. */
+    wait?: Record<string, CliWaitConfig>;
+    /** Extract downloadable media URLs from a result for `--output-dir`. */
+    download?: (result: unknown) => Array<{
+        url: string;
+        name: string;
+    }>;
+    /**
+     * Allow `--output-dir` downloads from private / internal / loopback hosts.
+     * Default `false` — the SSRF guard, since the URLs come from handler output.
+     */
+    allowPrivateDownloadHosts?: boolean;
+    /** Max bytes per `--output-dir` download before aborting. Default 100 MB. */
+    maxDownloadBytes?: number;
+    /** argv to parse — default `process.argv.slice(2)`; injectable for tests. */
+    argv?: string[];
+    /** stdout sink — default `process.stdout`; injectable for tests. */
+    stdout?: (text: string) => void;
+    /** stderr sink — default `process.stderr`; injectable for tests. */
+    stderr?: (text: string) => void;
+    /** Exit hook — default `process.exit`; injectable for tests. */
+    exit?: (code: number) => void;
+    /** Read piped stdin — default reads when not a TTY; injectable for tests. */
+    stdin?: () => Promise<string | null>;
+}
+/**
+ * Build and run a CLI from contract services, then exit. Parses `process.argv`
+ * (or `config.argv`), routes to a command, executes it through the shared tool
+ * pipeline and writes the result. Resolves identity once up front.
+ */
+export declare function createCli<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>>(config: CliConfig<TAuth, TContext>): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAsB,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,WAAW,CAAC;AAKnB,MAAM,WAAW,SAAS,CACxB,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,KAAK,UAAU,EAAE,CAAC,CAAC;IAC9E;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,KAAK,QAAQ,CAAC;IACzD,8EAA8E;IAC9E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,wEAAwE;IACxE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnE,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC;AAyLD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkInD"}

package/dist/tools/coerce.d.ts

@@ -1,8 +1,12 @@
 import { z } from 'zod';
 /**
- * Wrap array/object fields with `z.preprocess(jsonCoerce)` — tolerant of
- * LLM double-serialization (sending `"[1,2]"` instead of `[1,2]`).
- * Preserves optional/nullable wrappers so the emitted JSON Schema is identical.
+ * Coerce JSON-stringified array/object arguments — an LLM sometimes
+ * double-serializes a nested value (sends `"[1,2]"` instead of `[1,2]`).
+ *
+ * Only fields the schema declares as an array/object are touched, and only
+ * when the incoming value is a string. The transform operates on the
+ * **arguments**, never the schema — so the advertised tool schema stays
+ * exactly the contract schema (correct types, correct `required`).
  */
-export declare function withJsonCoercion(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+export declare function coerceJsonArgs(args: Record<string, unknown>, schema: z.ZodType | undefined): Record<string, unknown>;
 //# sourceMappingURL=coerce.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/tools/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GACjC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAyB5B"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/tools/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}

package/dist/tools/execute.d.ts

@@ -41,5 +41,5 @@ export interface ToolLifecycle {
 export declare function toolResultFromError(err: unknown): Extract<ToolResult, {
     ok: false;
 }>;
-export declare function executeToolMethod(method: MethodDef<unknown, unknown, unknown>, toolName: string, rawArgs: Record<string, unknown>, context: ToolCallContext, hooks?: ToolCallHooks, lifecycle?: ToolLifecycle): Promise<ToolResult>;
+export declare function executeToolMethod(method: MethodDef<unknown, unknown, unknown>, toolName: string, rawArgs: Record<string, unknown>, context: ToolCallContext, hooks?: ToolCallHooks, lifecycle?: ToolLifecycle, coerceJson?: boolean): Promise<ToolResult>;
 //# 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,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAQpF;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5C,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,GACxB,OAAO,CAAC,UAAU,CAAC,CA8FrB"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAQpF;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5C,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,GACjB,OAAO,CAAC,UAAU,CAAC,CA8GrB"}

package/dist/tools/json-schema.d.ts

@@ -10,9 +10,34 @@ import { z } from 'zod';
 /** Conversion direction — `input` for tool arguments, `output` for results. */
 export type JsonSchemaIo = 'input' | 'output';
 /**
- * Convert a Zod schema to JSON Schema. Throws on a construct JSON Schema cannot
- * represent (`z.date()`, `z.bigint()`, `z.map()`, …). The caller decides what
- * to do with that failure — see `onIncompatibleSchema`.
+ * Convert a Zod schema to JSON Schema (draft-2020-12, the dialect OpenAPI 3.1
+ * uses). `unrepresentable` controls a construct JSON Schema cannot represent
+ * (`z.date()`, `z.bigint()`, `z.map()`, …):
+ *
+ *  - `'throw'` (default) — throws for the whole schema. The tools layer wants
+ *    this: it mirrors what the MCP SDK does, so a build-time probe catches an
+ *    incompatible schema instead of shipping a tool the SDK would later reject.
+ *  - `'any'` — degrades only the offending field to `{}` and keeps the rest.
+ *    The OpenAPI generator wants this: one `z.date()` field must not collapse a
+ *    whole endpoint's schema to `{}`.
+ */
+export declare function toJsonSchema(schema: z.ZodType, io: JsonSchemaIo, unrepresentable?: 'throw' | 'any'): Record<string, unknown>;
+/** One top-level property of an object JSON Schema. */
+export interface JsonSchemaField {
+    /** Property name. */
+    name: string;
+    /** The property's own JSON Schema sub-document. */
+    schema: Record<string, unknown>;
+    /** Whether the property is in the schema's `required` list. */
+    required: boolean;
+    /** `description` (a Zod `.describe()`), when present. */
+    description?: string;
+}
+/**
+ * Extract the top-level object properties of a JSON Schema as a flat field list
+ * — the shared traversal behind CLI `--help` flag tables and OpenAPI
+ * `parameters`. Returns `[]` for a non-object schema (a union, a scalar); the
+ * caller decides how to degrade.
  */
-export declare function toJsonSchema(schema: z.ZodType, io: JsonSchemaIo): Record<string, unknown>;
+export declare function jsonSchemaFields(jsonSchema: Record<string, unknown>): JsonSchemaField[];
 //# sourceMappingURL=json-schema.d.ts.map

package/dist/tools/json-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/tools/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzF"}
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/tools/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,EAAE,EAAE,YAAY,EAChB,eAAe,GAAE,OAAO,GAAG,KAAe,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAqBvF"}

package/dist/tools/manifest.d.ts

@@ -8,6 +8,10 @@ export interface ToolManifestEntry {
  * Build a searchable manifest from collected tools — name, description and
  * JSON Schema for each. Use it to power a `tool_search` native tool: the app
  * decides the search algorithm and the unlock mechanism.
+ *
+ * A tool whose schema cannot be represented as JSON Schema still appears —
+ * with an empty `inputSchema` — so it stays discoverable by name / description
+ * rather than crashing the whole manifest.
  */
 export declare function buildToolManifest(tools: MountableTool[]): ToolManifestEntry[];
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,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;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAM7E"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,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;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAU7E"}

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

@@ -0,0 +1,59 @@
+/**
+ * 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;
+    /** 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=mcp-app.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-app.ts"],"names":[],"mappings":"AAYA;;;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,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4BvD"}

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

@@ -1,7 +1,25 @@
 import { type McpServerBuildConfig } from './mcp';
+import { type ProtectedResourceConfig } from './oauth-metadata';
 export interface McpHandlerConfig<TAuth> extends McpServerBuildConfig<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 (RFC 9728). When set, a `401` carries
+     * a `WWW-Authenticate: Bearer resource_metadata="…"` header so an MCP client
+     * can discover the authorization server. Serve the matching metadata document
+     * with `oauthProtectedResourceRoute(protectedResource)`.
+     */
+    protectedResource?: ProtectedResourceConfig;
+    /**
+     * Stateless mode (default `false`). Each request builds a fresh transport +
+     * server and is handled in isolation — no `Mcp-Session-Id`, no in-memory
+     * session store. A restart / deploy / scale-out therefore never invalidates a
+     * client (no `404 Session not found`), which is what most request/response
+     * tool servers want. The trade-off is no server-initiated messages
+     * (`notifications/progress`, standalone SSE) between requests — fine for
+     * synchronous tools. Leave `false` only when you need that server push.
+     */
+    stateless?: boolean;
 }
 /**
  * Build a Streamable-HTTP MCP request handler (`Request → Response`).

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-handler.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-handler.ts"],"names":[],"mappings":"AASA,OAAO,EAAkB,KAAK,oBAAoB,EAAsB,MAAM,OAAO,CAAC;AAyDtF,MAAM,WAAW,gBAAgB,CAAC,KAAK,CAAE,SAAQ,oBAAoB,CAAC,KAAK,CAAC;IAC1E,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAC9D;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC9B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA+DrC"}
+{"version":3,"file":"mcp-handler.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-handler.ts"],"names":[],"mappings":"AASA,OAAO,EAAkB,KAAK,oBAAoB,EAAsB,MAAM,OAAO,CAAC;AACtF,OAAO,EAAE,KAAK,uBAAuB,EAAyB,MAAM,kBAAkB,CAAC;AAqEvF,MAAM,WAAW,gBAAgB,CAAC,KAAK,CAAE,SAAQ,oBAAoB,CAAC,KAAK,CAAC;IAC1E,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC9B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkHrC"}

package/dist/tools/mcp.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ServiceDef, StitchLogger } from '../server/types';
 import { type ToolCallHooks, type ToolLifecycle } from './execute';
+import { type McpResourceDef } from './mcp-app';
 import { type ToolExtend } from './mount';
 /**
  * What to do when a tool's schema cannot be advertised on the MCP surface — a
@@ -74,6 +75,8 @@ export interface McpServerBuildConfig<TAuth> {
     /** Register native (non-contract) MCP tools — receives the `McpServer`
      *  directly. For tools returning multimodal content, e.g. `mountViewFile`. */
     nativeTools?: (server: McpServer) => 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;
@@ -89,4 +92,10 @@ export interface McpServerBuildConfig<TAuth> {
  * Transport-agnostic — the shared core behind every MCP transport.
  */
 export declare function buildMcpServer<TAuth>(config: McpServerBuildConfig<TAuth>, auth: TAuth): 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;
 //# sourceMappingURL=mcp.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AA8JjE,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,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,wBAAwB,CAAC;IAChD,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,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,EAAE,EACtB,oBAAoB,GAAE,wBAAkC,EACxD,MAAM,CAAC,EAAE,YAAY,GACpB,IAAI,CAWN;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,cAAmB,GAC1B,IAAI,CAsDN;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,4CAA4C;IAC5C,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,EAAE,CAAC,CAAC;IACzD,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD;+EAC2E;IAC3E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;0CAEsC;IACtC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,wBAAwB,CAAC;IAChD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;kFAC8E;IAC9E,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C;wDACoD;IACpD,YAAY,CAAC,EAAE,MAAM,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,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,KAAK,GACV,SAAS,CAoBX"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}

package/dist/tools/mount-download.d.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+export interface DownloadToolConfig {
+    /** Tool name. Default `'download'`. */
+    name?: string;
+    description: string;
+    /** Tool input shape (e.g. `{ url: z.string().optional(), id: z.string().optional() }`). */
+    inputSchema: z.ZodRawShape;
+    /** Resolve the args to a media URL — `null` when there is nothing to download. */
+    resolveUrl: (args: Record<string, unknown>) => Promise<string | null> | string | null;
+    /** Directory to save into by default. */
+    defaultDir: string;
+    /** Read a per-call output directory from the args. */
+    dirFromArgs?: (args: Record<string, unknown>) => string | undefined;
+    /**
+     * Allow downloading from private / internal / loopback hosts. Default `false`
+     * — the SSRF guard, since the URL comes from model-controlled args. Enable
+     * only in a trusted network.
+     */
+    allowPrivateHosts?: boolean;
+    /** Max bytes to read before aborting (memory cap). Default 100 MB. */
+    maxBytes?: number;
+}
+/**
+ * Register a native "download" tool — resolves a URL from the args, fetches it
+ * and writes it to disk with a content-type / URL-derived extension. Returns
+ * the saved path / size / mime.
+ */
+export declare function mountDownload(server: McpServer, config: DownloadToolConfig): void;
+//# sourceMappingURL=mount-download.d.ts.map

package/dist/tools/mount-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-download.d.ts","sourceRoot":"","sources":["../../src/tools/mount-download.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0C7B,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,kFAAkF;IAClF,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACtF,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAkDjF"}

package/dist/tools/mount-upload.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `mountUpload` — a generic native MCP tool that uploads a local file. The app
+ * injects how to read + send the file (`upload`); the tool wiring lives here.
+ * → ADR 0019.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface UploadToolConfig {
+    /** Tool name. Default `'upload'`. */
+    name?: string;
+    description: string;
+    /** Read a local `path` and upload it, returning whatever the upload yields. */
+    upload: (path: string) => Promise<unknown>;
+}
+/**
+ * Register a native "upload" tool — takes a local `path`, hands it to
+ * `config.upload` (which reads + sends it) and returns the result.
+ */
+export declare function mountUpload(server: McpServer, config: UploadToolConfig): void;
+//# sourceMappingURL=mount-upload.d.ts.map

package/dist/tools/mount-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-upload.d.ts","sourceRoot":"","sources":["../../src/tools/mount-upload.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAyB7E"}

package/dist/tools/mount-wait.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `mountWait` — a generic native MCP tool that blocks until an async job
+ * reaches a terminal state. The poll loop is the shared `pollUntil`; the app
+ * injects only the domain bits (what to poll, when it's done). Owns the MCP
+ * wiring so the consumer never imports `@modelcontextprotocol/sdk`. → ADR 0019.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+export interface WaitToolConfig {
+    /** Tool name. Default `'wait'`. */
+    name?: string;
+    description: string;
+    /** Tool input shape (e.g. `{ id: z.string() }`). */
+    inputSchema: z.ZodRawShape;
+    /** Fetch the current state for the call's args — one poll tick. */
+    poll: (args: Record<string, unknown>) => Promise<unknown>;
+    /** Terminal when this returns `true`. */
+    done: (state: unknown) => boolean;
+    /** Read a per-call timeout (seconds) from the args. */
+    timeoutFromArgs?: (args: Record<string, unknown>) => number | undefined;
+    /** Backoff schedule in seconds; the last entry repeats. */
+    backoff?: number[];
+    /** Default timeout in seconds. */
+    defaultTimeout?: number;
+    /** Render the final state. Default: pretty JSON, `isError` on timeout. */
+    render?: (state: unknown, timedOut: boolean) => {
+        text: string;
+        isError: boolean;
+    };
+}
+/**
+ * Register a native "wait" tool — polls `config.poll(args)` with backoff until
+ * `config.done` or the timeout, then returns the final state.
+ */
+export declare function mountWait(server: McpServer, config: WaitToolConfig): void;
+//# sourceMappingURL=mount-wait.d.ts.map

package/dist/tools/mount-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-wait.d.ts","sourceRoot":"","sources":["../../src/tools/mount-wait.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAK7B,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,mEAAmE;IACnE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,yCAAyC;IACzC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACxE,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACpF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CA2BzE"}

package/dist/tools/mount.d.ts

@@ -10,12 +10,16 @@ import { type ToolCallHooks, type ToolLifecycle, type ToolResult } from './execu
 /**
  * Extra arguments folded into a mounted tool's schema — the host supplies them,
  * `resolve` turns them into handler context. Shared by `mountMcp` / `mountAgent`.
+ *
+ * `TContext` is the typed handler context the extension contributes — left as
+ * `Record<string, unknown>` for the untyped mounts, pinned by `createToolkit`
+ * so `resolve` is checked against the app's context shape.
  */
-export interface ToolExtend {
+export interface ToolExtend<TContext extends Record<string, unknown> = Record<string, unknown>> {
     /** Extra Zod fields added to every (matching) tool's input schema. */
     schema: Record<string, z.ZodType>;
     /** Turn the extra arguments into context merged into the handler. */
-    resolve: (args: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    resolve: (args: Record<string, unknown>) => Partial<TContext> | Promise<Partial<TContext>>;
     /** Limit the extension to specific methods — default: every method. */
     filter?: (service: ServiceDef, method: MethodDef) => boolean;
 }
@@ -32,8 +36,6 @@ export interface MountableTool {
 }
 export interface CollectToolsConfig {
     extend?: ToolExtend;
-    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
-    coerceJsonArgs?: boolean;
     /** Flatten discriminated union inputs into a single object for MCP. Default: false. */
     flattenUnionInput?: boolean;
 }
@@ -56,6 +58,8 @@ export interface ToolRunnerConfig {
     lifecycle?: ToolLifecycle;
     /** Global error hint injected into every failed tool result. */
     errorHint?: (toolName: string, errorCode: string) => string | null;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
 }
 /**
  * Build the call executor for a mount — resolve the extend context, strip the

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

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/tools/mount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAKnB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,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;IAChE,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CAC9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAkBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,kBAAuB,GAC9B,aAAa,EAAE,CAuBjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,eAAe,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAqBhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACjE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/tools/mount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAKnB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CACzB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3F,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CAC9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAkBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,kBAAuB,GAC9B,aAAa,EAAE,CA4BjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,eAAe,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnE,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAsBhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACjE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/tools/native-result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The MCP text-content result shape shared by the native tools (`mountWait`,
+ * `mountDownload`, `mountUpload`) — one place so each tool file does not
+ * re-spell the `{ content: [{ type: 'text' }], isError }` envelope.
+ */
+export interface NativeTextResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    /** MCP tool results carry an open `_meta` etc. — the SDK's result type is index-signed. */
+    [key: string]: unknown;
+}
+/** A single text block, optionally flagged as an error. */
+export declare function textResult(text: string, isError?: boolean): NativeTextResult;
+//# sourceMappingURL=native-result.d.ts.map

package/dist/tools/native-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-result.d.ts","sourceRoot":"","sources":["../../src/tools/native-result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2FAA2F;IAC3F,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,gBAAgB,CAG1E"}

package/dist/tools/oauth-metadata.d.ts

@@ -0,0 +1,28 @@
+import type { RawRoute } from '../server/types';
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728). An MCP server acting as a
+ * resource server publishes this so a client, after a `401`, can discover which
+ * authorization server(s) issue tokens for it.
+ */
+export interface ProtectedResourceConfig {
+    /** Canonical resource identifier — the MCP server URL (RFC 8707 audience). */
+    resource: string;
+    /** Issuer URL(s) of the authorization server(s) that mint tokens for it. */
+    authorizationServers: string[];
+    /** Scopes the resource understands — advertised, not enforced here. */
+    scopesSupported?: string[];
+}
+/** Well-known prefix for the protected-resource metadata document (RFC 9728). */
+export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/** Absolute URL of the protected-resource metadata for a given resource. */
+export declare function protectedResourceMetadataUrl(resource: string): string;
+/** The `WWW-Authenticate` header value a protected `401` must carry (RFC 9728 §5.1). */
+export declare function wwwAuthenticateHeader(resource: string): string;
+/**
+ * A `RawRoute` serving the RFC 9728 protected-resource metadata at the path
+ * advertised by `protectedResourceMetadataUrl(config.resource)`. Mount it
+ * alongside the MCP handler; set the matching `protectedResource` on
+ * `createMcpHandler` so the `401` points here.
+ */
+export declare function oauthProtectedResourceRoute(config: ProtectedResourceConfig): RawRoute;
+//# sourceMappingURL=oauth-metadata.d.ts.map

package/dist/tools/oauth-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-metadata.d.ts","sourceRoot":"","sources":["../../src/tools/oauth-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,0CAA0C,CAAC;AAa/E,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AASD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,uBAAuB,GAAG,QAAQ,CAqBrF"}