stitchkit 0.36.1 → 0.37.0

package/dist/server/types.d.ts

@@ -28,15 +28,25 @@ type RequiredRequest<E> = E extends {
 } ? {
     req: Request;
 } : unknown;
+type RetainedRawBody<E> = E extends {
+    rawBody: true;
+} ? {
+    req: Request;
+    rawBody: string;
+} : unknown;
 export type Handlers<C extends Record<string, EndpointDef>, TCtx extends RuntimeContext = HandlerContext> = {
     [K in keyof C]: (ctx: TCtx & {
         params: InferParams<C[K]>;
         input: InferInput<C[K]>;
-    } & RequiredRequest<C[K]>) => HandlerReturn<C[K]>;
+    } & RequiredRequest<C[K]> & RetainedRawBody<C[K]>) => HandlerReturn<C[K]>;
 };
-export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknown> {
+/**
+ * Stable identity shared by HTTP contract endpoints and pathless native tool
+ * operations. Tool lifecycle/audit consume this shape; only `MethodDef` adds an
+ * HTTP route path and executable contract schemas.
+ */
+export interface OperationIdentity {
     method: HttpMethod;
-    path: string;
     desc: string;
     /**
      * Owning contract's prefix — the "service" half of a stable `(service, action)`
@@ -51,8 +61,21 @@ export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknow
      */
     key: string;
     toolName?: string;
-    expose?: readonly Transport[];
     scope?: string;
+    /** MCP Apps widget metadata — carried onto the MCP tool's `_meta.ui`. */
+    ui?: EndpointUiMeta;
+    /** MCP behavioural hints — carried onto the MCP tool's `annotations`. */
+    annotations?: EndpointToolAnnotations;
+    /**
+     * Opaque app-defined metadata from `EndpointDef.meta` — the core gives it no
+     * meaning. Read it in lifecycle hooks (`endpoint.meta?.X`) or on tool mounts;
+     * the consumer narrows the type. Never serialized to OpenAPI. → ADR 0021.
+     */
+    meta?: Record<string, unknown>;
+}
+export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknown> extends OperationIdentity {
+    path: string;
+    expose?: readonly Transport[];
     paramsSchema?: ZodType<TParams>;
     inputSchema?: ZodType<TInput>;
     outputSchema?: ZodType<TOutput>;
@@ -60,6 +83,8 @@ export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknow
     /** Per-route upload ceiling (bytes) for a multipart endpoint — overrides the
      *  server `maxUploadBytes` default; from `EndpointDef.maxUploadBytes`. */
     maxUploadBytes?: number;
+    /** Per-route JSON body ceiling; enforced before full buffering. */
+    maxJsonBodyBytes?: number;
     /**
      * Whether the operation is safe to call twice with the same input — from
      * `EndpointDef.idempotent`. The core attaches no behaviour; a retrying
@@ -67,22 +92,14 @@ export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknow
      * → ADR 0027.
      */
     idempotent?: boolean;
-    /** MCP Apps widget metadata — carried onto the MCP tool's `_meta.ui`. */
-    ui?: EndpointUiMeta;
-    /** MCP behavioural hints — carried onto the MCP tool's `annotations`. */
-    annotations?: EndpointToolAnnotations;
-    /**
-     * Opaque app-defined metadata from `EndpointDef.meta` — the core gives it no
-     * meaning. Read it in lifecycle hooks (`endpoint.meta?.X`) or on tool mounts;
-     * the consumer narrows the type. Never serialized to OpenAPI. → ADR 0021.
-     */
-    meta?: Record<string, unknown>;
     /**
      * The handler returns the `Response` itself — from `EndpointDef.rawResponse`. Routed
      * and gated like any endpoint, but never serialized, never validated against
      * an output schema and never mounted as a tool. → ADR 0038.
      */
     rawResponse?: true;
+    /** Retain the decoded JSON request text on `ctx.rawBody`. HTTP-only. */
+    rawBody?: true;
     /** Documented response media type of a raw-response endpoint — OpenAPI only. */
     contentType?: string;
     handler: (ctx: RuntimeContext) => Promise<TOutput> | TOutput;
@@ -113,10 +130,8 @@ export interface RouteGroup {
  * but the handler is raw `Request → Response` — no schema parsing and no
  * `beforeHandle` auth gate; the route authorizes itself.
  */
-/** The concrete `Bun.serve` server instance, passed through to raw handlers. */
-export type BunServer = ReturnType<typeof Bun.serve>;
 /** Context passed to a `RawRoute` handler alongside the raw `Request`. */
-export interface RawRouteContext {
+export interface RawRouteContext<TServer = unknown> {
     /**
      * Matched `:param` path segments. A trailing `/*` wildcard also adds its
      * remainder (everything after the prefix) as `params['*']`. Empty for an exact
@@ -124,17 +139,18 @@ export interface RawRouteContext {
      */
     params: Record<string, string>;
     /**
-     * The `Bun.serve` instance — needed for connection upgrades (e.g. WebSocket).
+     * The runtime server instance. It defaults to `unknown` at the Fetch-clean
+     * boundary and is concrete on runtime-owned APIs such as `createServer`.
      * Absent when the handler runs via the bare `createHandler` fetch.
      */
-    server?: BunServer;
+    server?: TServer;
     /**
      * Client IP — the real socket peer, or the `x-forwarded-for` client when
      * `trustProxy` is set. Resolved by the framework; never spoofable by default.
      */
     ipAddress?: string;
 }
-export interface RawRoute {
+export interface RawRoute<TServer = unknown> {
     method: HttpMethod | 'ALL';
     /**
      * Exact path, `:param` segments, or a trailing `/*` prefix wildcard. The
@@ -147,7 +163,7 @@ export interface RawRoute {
      * `ctx` (matched path params, the server). Errors thrown here are caught by
      * the router and run through `hooks.onError` — same shape as contract errors.
      */
-    handler: (req: Request, ctx: RawRouteContext) => Response | Promise<Response>;
+    handler: (req: Request, ctx: RawRouteContext<TServer>) => Response | Promise<Response>;
 }
 export interface StitchLogger {
     info(msg: string, data?: Record<string, unknown>): void;
@@ -210,6 +226,12 @@ export interface LoggingConfig {
      * `status`, `durationMs`, `errorCode` and `ip` in both sinks, plus `ts`,
      * `level` and `msg` on the built-in production line.
      *
+     * One outcome-aware exception: on a `4xx`/`5xx` where the framework derived
+     * no code (for example, a raw route returned an error `Response`), enrichment
+     * may supply `errorCode`. It still cannot forge one on a `2xx`/`3xx` or
+     * replace a framework-derived code. A discarded owned key warns once per
+     * handler instead of failing silently.
+     *
      * Four things to know:
      * - It reaches the structured output only: the production JSON line and a
      *   custom logger's `data`. The development `←` line stays as it is — it is a
@@ -234,12 +256,12 @@ export interface LoggingConfig {
  * the runtime. The optional second argument is the runtime's server handle:
  * Bun passes one (raw routes need it for upgrades), Node adapters never do.
  */
-export type FetchHandler = (req: Request, server?: BunServer) => Promise<Response>;
+export type FetchHandler<TServer = unknown> = (req: Request, server?: TServer) => Promise<Response>;
 /**
  * Runtime-neutral handler config — everything `createHandler` needs.
  * No Bun globals, no Bun types. This is the portability seam.
  */
-export interface HandlerConfig {
+export interface HandlerConfig<TServer = unknown> {
     services?: ServiceDef[];
     groups?: RouteGroup[];
     /**
@@ -253,13 +275,19 @@ export interface HandlerConfig {
      * the core attaches no meaning beyond this lookup. → ADR 0024.
      */
     scopePrefixes?: Record<string, string>;
-    rawRoutes?: RawRoute[];
+    rawRoutes?: RawRoute<TServer>[];
     /**
      * Default upload ceiling (bytes) for every `multipart` endpoint. A per-route
      * `EndpointDef.maxUploadBytes` overrides it; without either, multipart uploads
      * are capped at the 25 MB framework default.
      */
     maxUploadBytes?: number;
+    /**
+     * Default JSON request-body ceiling in bytes. A per-route
+     * `EndpointDef.maxJsonBodyBytes` overrides it. Unset preserves the existing
+     * unbounded JSON-body behaviour.
+     */
+    maxJsonBodyBytes?: number;
     cors?: CorsConfig;
     hooks?: LifecycleHooks;
     logging?: boolean | LoggingConfig;
@@ -292,17 +320,6 @@ export interface HandlerConfig {
      */
     trustProxy?: boolean;
 }
-type BunServeOptions = Parameters<typeof Bun.serve>[0];
-type BunWebSocketHandlers = BunServeOptions extends {
-    websocket?: infer T;
-} ? T : never;
-type BunRoutes = BunServeOptions extends {
-    routes?: infer T;
-} ? T : never;
-type BunDevelopmentOptions = BunServeOptions extends {
-    development?: infer T;
-} ? T : never;
-export type ServerPassthrough = Omit<BunServeOptions, 'fetch' | 'port' | 'hostname' | 'unix' | 'routes' | 'websocket' | 'development'>;
 /**
  * The composition seam shared by the servers that own their own `fetch`.
  *
@@ -318,20 +335,8 @@ export type ServerPassthrough = Omit<BunServeOptions, 'fetch' | 'port' | 'hostna
  * createServer({ services, wrapFetch: (h) => wrapInRequestContext(audit.http(h)) })
  * ```
  */
-export interface FetchComposition {
-    wrapFetch?: (fetch: FetchHandler) => FetchHandler;
-}
-/**
- * Full config for `createServer` — extends `HandlerConfig` with Bun-specific
- * options (`Bun.serve` routes, websocket, development, passthrough).
- */
-export interface BunServerConfig extends HandlerConfig, FetchComposition {
-    port?: number;
-    hostname?: string;
-    routes?: BunRoutes;
-    websocket?: BunWebSocketHandlers;
-    development?: BunDevelopmentOptions;
-    bun?: ServerPassthrough;
+export interface FetchComposition<TServer = unknown> {
+    wrapFetch?: (fetch: FetchHandler<TServer>) => FetchHandler<TServer>;
 }
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3F,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CA8CT"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3F,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAmDT"}

package/dist/tools/execute.d.ts

@@ -1,5 +1,6 @@
+import type { ZodType, z } from 'zod';
 import type { RuntimeContext, TransportSource } from '../contract';
-import type { MethodDef } from '../server/types';
+import type { OperationIdentity } from '../server/types';
 export type ToolResult = {
     ok: true;
     data: unknown;
@@ -13,8 +14,26 @@ export interface ToolCallContext {
     source: TransportSource;
     [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;
+}
+export interface ToolErrorOptions {
+    toolName: string;
+    error: unknown;
+    context: ToolCallContext;
+    endpoint: OperationIdentity;
+}
 export interface ToolCallHooks {
-    beforeToolCall?: (toolName: string, args: Record<string, unknown>, context: ToolCallContext, endpoint: MethodDef) => void | Promise<void>;
+    beforeToolCall?: (options: BeforeToolCallOptions) => void | Promise<void>;
     /**
      * Every finished call, success and failure alike — the record of the call.
      *
@@ -24,23 +43,22 @@ export interface ToolCallHooks {
      * 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`.
-     * A six-parameter hook is unaffected.
      */
-    afterToolCall?: (toolName: string, args: Record<string, unknown>, result: ToolResult, durationMs: number, context: ToolCallContext, endpoint: MethodDef, error?: unknown) => void | Promise<void>;
+    afterToolCall?: (options: AfterToolCallOptions) => void | Promise<void>;
     /**
-     * The handler path threw — the value **as thrown**, before it is normalised
+     * 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 `lifecycle.beforeHandle`, the handler, or
-     * `lifecycle.afterHandle` — the span where information is destroyed. It does
-     * **not** fire for a `beforeToolCall` rejection, an argument-validation
-     * failure or an output-schema mismatch: each of those is already described in
-     * full by the `ToolResult` that `afterToolCall` receives, and a second path to
-     * the same information only invites double-logging.
+     * 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
@@ -49,7 +67,7 @@ export interface ToolCallHooks {
      * records (a request-context error, say) is already in place when the audit
      * hook reads it.
      */
-    onToolError?: (toolName: string, error: unknown, context: ToolCallContext, endpoint: MethodDef) => void | Promise<void>;
+    onToolError?: (options: ToolErrorOptions) => void | Promise<void>;
 }
 /**
  * A per-tool hint appended to a failed tool result — given the tool name and the
@@ -75,9 +93,21 @@ export type ErrorHintFn = (toolName: string, errorCode: string) => string | null
  */
 export interface ToolLifecycle {
     /** Auth / scope gate — throw to reject the call. */
-    beforeHandle?: (ctx: RuntimeContext, endpoint: MethodDef) => void | Promise<void>;
+    beforeHandle?: (ctx: RuntimeContext, endpoint: OperationIdentity) => void | Promise<void>;
     /** Transform the handler result before it is returned. */
-    afterHandle?: (ctx: RuntimeContext, result: unknown, endpoint: MethodDef) => unknown | Promise<unknown>;
+    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;
+    handler(ctx: RuntimeContext): unknown | Promise<unknown>;
+}
+/** Executable extension parsed once inside the shared runner before resolution. */
+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
@@ -87,7 +117,7 @@ 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, coerceJson?: boolean, onOutputStrip?: (paths: string[]) => void): Promise<ToolResult>;
+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): 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
@@ -101,6 +131,6 @@ export declare function executeToolMethod(method: MethodDef<unknown, unknown, un
 export declare function inToolCallContext<T>(call: {
     source: TransportSource;
     toolName: string;
-    method: MethodDef<unknown, unknown, unknown>;
+    method: OperationIdentity;
 }, body: () => Promise<T>): Promise<T>;
 //# 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":"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"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"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"}

package/dist/tools/flatten-join.d.ts

@@ -0,0 +1,8 @@
+import type { ToolPresentationSchema } from './flatten';
+export interface VariantProperty {
+    schema: ToolPresentationSchema;
+    labels: string[];
+    required: boolean;
+}
+export declare function mergePropertySchemas(properties: VariantProperty[]): ToolPresentationSchema;
+//# sourceMappingURL=flatten-join.d.ts.map

package/dist/tools/flatten-join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../src/tools/flatten-join.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAgID,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,sBAAsB,CAuB1F"}

package/dist/tools/flatten.d.ts

@@ -1,47 +1,10 @@
-import { z } from 'zod';
+export type ToolPresentationSchema = Record<string, unknown>;
 /**
- * Flatten a `ZodDiscriminatedUnion` into a single `ZodObject` for LLM transports
- * that cannot represent `oneOf` (MCP / weaker models).
- *
- * The discriminator becomes a `z.enum(...)` of **all** variant values; each
- * variant's fields become optional with a `.describe()` hint naming the variants
- * that require them. When two variants declare the **same key with different
- * shapes**, the advertised field is widened so it accepts every variant's value —
- * never narrowed to one (which would make the losing variant unsatisfiable):
- *
- * - identical across variants → kept as-is.
- * - all string literal/enum → merged into one widened `z.enum`.
- * - otherwise (object vs array, differing object shapes) → `z.unknown()` (accepts
- *   anything; the `.describe()` carries the per-variant shape).
- *
- * This keeps the advertised schema free of `oneOf` / `anyOf` at any depth (→ ADR
- * 0033) **and** a superset of the original union, so a model can always produce a
- * value that passes both the transport SDK and validation.
- *
- * **Key policy is merged, not dropped.** The flat object stands in for every
- * variant, so it takes the policy that cannot remove what any variant would have
- * kept: every variant `.strict()` → strict (sound, because the flat shape is the
- * union of all variant keys); any variant with a catchall → loose; otherwise
- * plain. A *typed* catchall is never copied onto the flat object — it would
- * reject a sibling variant's differently-typed extra key.
- *
- * **Still lossy:** per-variant strictness (a key legal in variant A and illegal
- * in B) is unrepresentable in one flat object, as are object-level refinements.
- * Those stay enforced only by the original union in `executeToolMethod`. What is
- * *not* lossy any more is deletion — the advertised schema can no longer drop a
- * key the contract would have seen. → ADR 0034.
+ * Rebuild a JSON Schema and replace every structurally identifiable
+ * discriminated object `oneOf` with one conservative object-shaped join.
+ * Plain unions remain unions. The source document is never mutated.
  */
-export declare function flattenDiscriminatedUnion(union: z.ZodDiscriminatedUnion): z.ZodObject<z.ZodRawShape>;
-/**
- * Recursively flatten **every** flattenable `ZodDiscriminatedUnion` in a schema —
- * top level and nested inside object fields, array items, plain unions, records,
- * and `optional` / `nullable` / `default` / intersection wrappers — so the
- * advertised JSON Schema carries no `oneOf` / `anyOf` at any depth. A union that
- * cannot be flattened (non-string discriminator, non-object variant) is left
- * untouched rather than crashing the mount (→ ADR 0033).
- *
- * Every object is rebuilt **with its key policy** (`rebuildObject`) — the walk
- * changes union shape, never what an object does with an undeclared key. → ADR 0034.
- */
-export declare function flattenUnionsDeep(schema: z.core.$ZodType): z.ZodType;
+export declare function flattenToolJsonSchema(schema: ToolPresentationSchema): ToolPresentationSchema;
+/** Freeze every JSON object/array in a prepared presentation document. */
+export declare function freezeToolJsonSchema(schema: ToolPresentationSchema): ToolPresentationSchema;
 //# sourceMappingURL=flatten.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AA6TD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA6J7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG5F;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG3F"}

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

@@ -21,7 +21,7 @@ export type JsonSchemaIo = 'input' | 'output';
  *    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>;
+export declare function toJsonSchema(schema: z.ZodType, io: JsonSchemaIo, unrepresentable?: 'throw' | 'any', target?: 'draft-07' | 'draft-2020-12'): Record<string, unknown>;
 /** One top-level property of an object JSON Schema. */
 export interface JsonSchemaField {
     /** Property name. */

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;;;;;;;;;;;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"}
+{"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,EAC1C,MAAM,GAAE,UAAU,GAAG,eAAiC,GACrD,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.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;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAU7E"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AAAA,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,CAM7E"}

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

@@ -10,23 +10,17 @@ export interface McpHandlerConfig<TAuth> extends McpServerBuildConfig<TAuth> {
      * 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;
+    /** HTTP transport state. Default `'stateless'`; opt into `'stateful'` only
+     *  for cross-request progress, server push or resumable SSE sessions. */
+    sessionMode?: McpSessionMode;
 }
+export type McpSessionMode = 'stateful' | 'stateless';
 /**
  * Build a Streamable-HTTP MCP request handler (`Request → Response`).
  *
- * Owns the entire MCP server lifecycle — SSE event store, per-session
- * transports, the `McpServer` instances — so the consuming app never imports
- * `@modelcontextprotocol/sdk` itself. The app only declares WHAT to expose:
+ * Owns the MCP server/transport lifecycle — and, only in explicit stateful
+ * mode, the SSE event/session stores — so the consuming app never imports the
+ * SDK itself. The app only declares WHAT to expose:
  * how to authenticate and which contract services. MCP tools come from
  * contracts; native multimodal tools attach via `nativeTools`.
  *

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;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,CAqHrC"}
+{"version":3,"file":"mcp-handler.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-handler.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,OAAO,CAAC;AACf,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;6EACyE;IACzE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAoBtD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC9B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA2HrC"}