@vurb/core 3.2.0

package/dist/core/execution/ExecutionPipeline.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ExecutionPipeline — Orchestrates MCP Tool Execution Steps
+ *
+ * Breaks the monolithic execute() flow into discrete, testable steps
+ * using the Result monad for railway-oriented error handling.
+ *
+ * Each step either succeeds (passes data to the next step) or fails
+ * (short-circuits with an error response).
+ *
+ * Pipeline: ensureBuilt → parseDiscriminator → resolveAction → validateArgs → runChain
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type ToolResponse } from '../response.js';
+import { type Result } from '../result.js';
+import { type InternalAction } from '../types.js';
+import { type CompiledChain } from './MiddlewareCompiler.js';
+import { type ProgressSink } from './ProgressHelper.js';
+import { type PostProcessTelemetry } from '../../presenter/PostProcessor.js';
+/** Pre-built runtime context needed for execution */
+export interface ExecutionContext<TContext> {
+    readonly actionMap: Map<string, InternalAction<TContext>>;
+    readonly compiledChain: CompiledChain<TContext>;
+    readonly validationSchemaCache: Map<string, ZodObject<ZodRawShape> | null>;
+    readonly actionKeysString: string;
+    readonly discriminator: string;
+    readonly toolName: string;
+}
+/** Resolved action with its discriminator value */
+interface ResolvedAction<TContext> {
+    readonly action: InternalAction<TContext>;
+    readonly discriminatorValue: string;
+}
+/** Step 1: Parse discriminator value from raw args */
+export declare function parseDiscriminator<TContext>(execCtx: ExecutionContext<TContext>, args: Record<string, unknown>): Result<string>;
+/** Step 2: Resolve the action by discriminator value — O(1) lookup */
+export declare function resolveAction<TContext>(execCtx: ExecutionContext<TContext>, discriminatorValue: string): Result<ResolvedAction<TContext>>;
+/** Step 3: Validate and strip args using pre-cached Zod schema */
+export declare function validateArgs<TContext>(execCtx: ExecutionContext<TContext>, resolved: ResolvedAction<TContext>, args: Record<string, unknown>): Result<{
+    validated: Record<string, unknown>;
+    selectFields: string[] | undefined;
+}>;
+/**
+ * Step 4: Run pre-compiled middleware chain → handler.
+ *
+ * @param rethrow - When `true`, handler exceptions propagate to the caller
+ *   instead of being caught and converted to error responses. Used by the
+ *   traced execution path so that `_executeTraced` can classify system errors
+ *   (`SpanStatusCode.ERROR` + `recordException`). Default: `false`.
+ * @param signal - Optional AbortSignal for cooperative cancellation.
+ *   Checked before handler execution. If already aborted, returns an
+ *   immediate error response without invoking the handler chain.
+ * @param selectFields - Optional `_select` field names extracted from the
+ *   AI's input. Forwarded to `postProcessResult()` → `Presenter.make()`
+ *   for Late Guillotine filtering.
+ */
+export declare function runChain<TContext>(execCtx: ExecutionContext<TContext>, resolved: ResolvedAction<TContext>, ctx: TContext, args: Record<string, unknown>, progressSink?: ProgressSink, rethrow?: boolean, signal?: AbortSignal, selectFields?: string[], telemetry?: PostProcessTelemetry): Promise<ToolResponse>;
+/**
+ * An envelope that wraps an async generator from a handler.
+ * The middleware compiler detects generator handlers and wraps
+ * their return value in this envelope so the pipeline can drain them.
+ */
+export interface GeneratorResultEnvelope {
+    readonly __brand: 'GeneratorResultEnvelope';
+    readonly generator: AsyncGenerator<unknown, ToolResponse, undefined>;
+}
+export {};
+//# sourceMappingURL=ExecutionPipeline.d.ts.map

package/dist/core/execution/ExecutionPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionPipeline.d.ts","sourceRoot":"","sources":["../../../src/core/execution/ExecutionPipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,EAAE,KAAK,YAAY,EAA+B,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAIhG,qDAAqD;AACrD,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACtC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,QAAQ,CAAC,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED,mDAAmD;AACnD,UAAU,cAAc,CAAC,QAAQ;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACvC;AAID,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,QAAQ,EACvC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,CAAC,CAyBhB;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,EAClC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACnC,kBAAkB,EAAE,MAAM,GAC3B,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAalC;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,QAAQ,EACjC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACnC,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAAE,CAAC,CA2CpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EACnC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACnC,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAClC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,CAAC,EAAE,YAAY,EAC3B,OAAO,UAAQ,EACf,MAAM,CAAC,EAAE,WAAW,EACpB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,SAAS,CAAC,EAAE,oBAAoB,GACjC,OAAO,CAAC,YAAY,CAAC,CA8BvB;AAQD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;CACxE"}

package/dist/core/execution/ExecutionPipeline.js

@@ -0,0 +1,176 @@
+/**
+ * ExecutionPipeline — Orchestrates MCP Tool Execution Steps
+ *
+ * Breaks the monolithic execute() flow into discrete, testable steps
+ * using the Result monad for railway-oriented error handling.
+ *
+ * Each step either succeeds (passes data to the next step) or fails
+ * (short-circuits with an error response).
+ *
+ * Pipeline: ensureBuilt → parseDiscriminator → resolveAction → validateArgs → runChain
+ */
+import {} from 'zod';
+import { error, escapeXml, toolError } from '../response.js';
+import { formatValidationError } from './ValidationErrorFormatter.js';
+import { succeed, fail } from '../result.js';
+import {} from '../types.js';
+import {} from './MiddlewareCompiler.js';
+import { isProgressEvent } from './ProgressHelper.js';
+import { postProcessResult } from '../../presenter/PostProcessor.js';
+// ── Pipeline Steps (pure functions) ──────────────────────
+/** Step 1: Parse discriminator value from raw args */
+export function parseDiscriminator(execCtx, args) {
+    const raw = args[execCtx.discriminator];
+    // Bug #116 fix: distinguish missing from wrong-type discriminator.
+    if (raw !== undefined && typeof raw !== 'string') {
+        const text = [
+            `<tool_error code="INVALID_DISCRIMINATOR">`,
+            `<message>Discriminator field "${escapeXml(execCtx.discriminator)}" must be a string, got ${typeof raw}.</message>`,
+            `<available_actions>${escapeXml(execCtx.actionKeysString)}</available_actions>`,
+            `<recovery>Set "${escapeXml(execCtx.discriminator)}" to one of the available actions as a string.</recovery>`,
+            `</tool_error>`,
+        ].join('\n');
+        return fail({ content: [{ type: 'text', text }], isError: true });
+    }
+    const value = typeof raw === 'string' ? raw : undefined;
+    if (!value) {
+        const text = [
+            `<tool_error code="MISSING_DISCRIMINATOR">`,
+            `<message>The required field "${escapeXml(execCtx.discriminator)}" is missing.</message>`,
+            `<available_actions>${escapeXml(execCtx.actionKeysString)}</available_actions>`,
+            `<recovery>Add the "${escapeXml(execCtx.discriminator)}" field as a string and call the tool again.</recovery>`,
+            `</tool_error>`,
+        ].join('\n');
+        return fail({ content: [{ type: 'text', text }], isError: true });
+    }
+    return succeed(value);
+}
+/** Step 2: Resolve the action by discriminator value — O(1) lookup */
+export function resolveAction(execCtx, discriminatorValue) {
+    const action = execCtx.actionMap.get(discriminatorValue);
+    if (!action) {
+        const text = [
+            `<tool_error code="UNKNOWN_ACTION">`,
+            `<message>The ${escapeXml(execCtx.discriminator)} "${escapeXml(discriminatorValue)}" does not exist.</message>`,
+            `<available_actions>${escapeXml(execCtx.actionKeysString)}</available_actions>`,
+            `<recovery>Choose a valid action from available_actions and call the tool again.</recovery>`,
+            `</tool_error>`,
+        ].join('\n');
+        return fail({ content: [{ type: 'text', text }], isError: true });
+    }
+    return succeed({ action, discriminatorValue });
+}
+/** Step 3: Validate and strip args using pre-cached Zod schema */
+export function validateArgs(execCtx, resolved, args) {
+    const validationSchema = execCtx.validationSchemaCache.get(resolved.action.key);
+    // Extract _select before validation — it's a framework-level field
+    // that must NOT reach the .strict() Zod schema.
+    const rawSelect = args['_select'];
+    const selectFields = (Array.isArray(rawSelect) && rawSelect.every(v => typeof v === 'string'))
+        ? rawSelect
+        : undefined;
+    if (!validationSchema) {
+        // No schema — strip _select (framework field) but preserve discriminator
+        // (handlers rely on it). Re-inject with resolved value like the with-schema path.
+        const { _select: _sel, ...cleaned } = args;
+        return succeed({ validated: cleaned, selectFields });
+    }
+    // Remove discriminator AND _select before validation
+    const { [execCtx.discriminator]: _, _select: _unused, ...argsToValidate } = args;
+    const result = validationSchema.safeParse(argsToValidate);
+    if (!result.success) {
+        const text = formatValidationError(result.error.issues, `${execCtx.toolName}/${resolved.discriminatorValue}`, argsToValidate);
+        // formatValidationError already produces complete XML — bypass error() to avoid double-wrapping
+        return fail({ content: [{ type: 'text', text }], isError: true });
+    }
+    // Mutate directly — zero-copy re-injection of discriminator
+    const validated = result.data;
+    // Guard against prototype-pollution via poisoned discriminator names
+    const disc = execCtx.discriminator;
+    if (disc === '__proto__' || disc === 'constructor' || disc === 'prototype') {
+        return fail({
+            content: [{ type: 'text', text: `Invalid discriminator name: "${disc}".` }],
+            isError: true,
+        });
+    }
+    validated[disc] = resolved.discriminatorValue;
+    return succeed({ validated, selectFields });
+}
+/**
+ * Step 4: Run pre-compiled middleware chain → handler.
+ *
+ * @param rethrow - When `true`, handler exceptions propagate to the caller
+ *   instead of being caught and converted to error responses. Used by the
+ *   traced execution path so that `_executeTraced` can classify system errors
+ *   (`SpanStatusCode.ERROR` + `recordException`). Default: `false`.
+ * @param signal - Optional AbortSignal for cooperative cancellation.
+ *   Checked before handler execution. If already aborted, returns an
+ *   immediate error response without invoking the handler chain.
+ * @param selectFields - Optional `_select` field names extracted from the
+ *   AI's input. Forwarded to `postProcessResult()` → `Presenter.make()`
+ *   for Late Guillotine filtering.
+ */
+export async function runChain(execCtx, resolved, ctx, args, progressSink, rethrow = false, signal, selectFields, telemetry) {
+    const chain = execCtx.compiledChain.get(resolved.action.key);
+    if (!chain) {
+        return error(`No compiled chain for action "${resolved.action.key}".`);
+    }
+    // Cancellation gate: abort before starting the handler chain
+    if (signal?.aborted) {
+        return error(`[${execCtx.toolName}/${resolved.discriminatorValue}] Request cancelled.`);
+    }
+    try {
+        const result = await chain(ctx, args);
+        // If the middleware chain returned a generator result envelope, drain it
+        if (isGeneratorResultEnvelope(result)) {
+            const drained = await drainGenerator(result.generator, progressSink, signal);
+            return postProcessResult(drained, resolved.action.returns, ctx, selectFields, telemetry);
+        }
+        return postProcessResult(result, resolved.action.returns, ctx, selectFields, telemetry);
+    }
+    catch (err) {
+        if (rethrow)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        return toolError('INTERNAL_ERROR', {
+            message: `[${execCtx.toolName}/${resolved.discriminatorValue}] ${message}`,
+            suggestion: 'This may be a transient error. Retry the same call with identical parameters.',
+            severity: 'error',
+        });
+    }
+}
+/** @internal */
+function isGeneratorResultEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__brand' in value &&
+        value.__brand === 'GeneratorResultEnvelope');
+}
+/**
+ * Drain an async generator, forwarding ProgressEvents to the sink
+ * and returning the final ToolResponse.
+ *
+ * Checks the AbortSignal before each iteration. If cancelled, the
+ * generator is returned (cleanup runs) and an error response is returned.
+ * This prevents zombie generators from continuing to execute after
+ * the user cancels the request.
+ *
+ * @internal
+ */
+async function drainGenerator(gen, progressSink, signal) {
+    let result = await gen.next();
+    while (!result.done) {
+        // Cancellation check: abort generator if signal fired
+        if (signal?.aborted) {
+            // Return the generator to trigger finally {} cleanup
+            await gen.return(error('Request cancelled.'));
+            return error('Request cancelled.');
+        }
+        if (progressSink && isProgressEvent(result.value)) {
+            progressSink(result.value);
+        }
+        result = await gen.next();
+    }
+    return result.value;
+}
+//# sourceMappingURL=ExecutionPipeline.js.map

package/dist/core/execution/ExecutionPipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionPipeline.js","sourceRoot":"","sources":["../../../src/core/execution/ExecutionPipeline.ts"],"names":[],"mappings":"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"}

package/dist/core/execution/MiddlewareCompiler.d.ts

@@ -0,0 +1,35 @@
+import { type InternalAction, type MiddlewareFn } from '../types.js';
+export type CompiledChain<TContext> = Map<string, (ctx: TContext, args: Record<string, unknown>) => Promise<unknown>>;
+/** Generic handler function signature used in middleware chains. */
+type ChainFn<TContext> = (ctx: TContext, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Wrap a handler with a middleware stack (right-to-left composition).
+ *
+ * This is the single canonical implementation of the middleware
+ * wrapping pattern. No other file should duplicate this loop.
+ *
+ * Includes a runtime guard: if a middleware returns `undefined`,
+ * a one-time warning is emitted. This catches the common junior
+ * mistake of forgetting `return next()`, which silently prevents
+ * the handler from executing.
+ *
+ * @param handler - The innermost function to wrap
+ * @param middlewares - Middleware stack (outermost first, applied right-to-left)
+ * @returns The compiled chain function
+ */
+export declare function wrapChain<TContext>(handler: ChainFn<TContext>, middlewares: readonly MiddlewareFn<TContext>[]): ChainFn<TContext>;
+/**
+ * Pre-compile middleware chains for all actions in a builder.
+ *
+ * For each action:
+ * 1. Wraps generator handlers in a GeneratorResultEnvelope
+ * 2. Applies per-action middlewares (innermost)
+ * 3. Applies global middlewares (outermost)
+ *
+ * @param actions - Registered actions with their handlers and local middleware
+ * @param middlewares - Global middleware stack
+ * @returns Map from action key to compiled chain
+ */
+export declare function compileMiddlewareChains<TContext>(actions: readonly InternalAction<TContext>[], middlewares: readonly MiddlewareFn<TContext>[]): CompiledChain<TContext>;
+export {};
+//# sourceMappingURL=MiddlewareCompiler.d.ts.map

package/dist/core/execution/MiddlewareCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiddlewareCompiler.d.ts","sourceRoot":"","sources":["../../../src/core/execution/MiddlewareCompiler.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAIrE,MAAM,MAAM,aAAa,CAAC,QAAQ,IAAI,GAAG,CACrC,MAAM,EACN,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CACrE,CAAC;AAEF,oEAAoE;AACpE,KAAK,OAAO,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AA4B5F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAC9B,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,WAAW,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,GAC/C,OAAO,CAAC,QAAQ,CAAC,CAsBnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAC5C,OAAO,EAAE,SAAS,cAAc,CAAC,QAAQ,CAAC,EAAE,EAC5C,WAAW,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,GAC/C,aAAa,CAAC,QAAQ,CAAC,CA4BzB"}

package/dist/core/execution/MiddlewareCompiler.js

@@ -0,0 +1,111 @@
+/**
+ * MiddlewareCompiler — Middleware Chain Pre-Compilation Strategy
+ *
+ * Wraps middlewares right-to-left around each action handler,
+ * producing a ready-to-execute chain per action key.
+ *
+ * Supports both regular async handlers and async generator handlers.
+ * Generator handlers are wrapped in a {@link GeneratorResultEnvelope}
+ * so the pipeline can drain progress events from them.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from '../response.js';
+import {} from '../types.js';
+/**
+ * Check if a function is an async generator function.
+ * Uses Symbol.toStringTag which survives minification (unlike constructor.name).
+ * @internal
+ */
+function isAsyncGeneratorFunction(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    // Symbol.toStringTag is set by the engine on async generator functions
+    if (fn[Symbol.toStringTag] === 'AsyncGeneratorFunction')
+        return true;
+    if (fn.constructor?.name === 'AsyncGeneratorFunction')
+        return true;
+    // Duck-type fallback for transpiled code: check the prototype
+    if (typeof fn.prototype === 'object' && fn.prototype !== null
+        && Symbol.asyncIterator in fn.prototype) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Set of middleware functions that have already triggered the
+ * "forgot return next()" warning. Keyed by function identity
+ * to ensure each middleware warns at most once across all chains.
+ * @internal
+ */
+const _warnedMiddlewares = new WeakSet();
+/**
+ * Wrap a handler with a middleware stack (right-to-left composition).
+ *
+ * This is the single canonical implementation of the middleware
+ * wrapping pattern. No other file should duplicate this loop.
+ *
+ * Includes a runtime guard: if a middleware returns `undefined`,
+ * a one-time warning is emitted. This catches the common junior
+ * mistake of forgetting `return next()`, which silently prevents
+ * the handler from executing.
+ *
+ * @param handler - The innermost function to wrap
+ * @param middlewares - Middleware stack (outermost first, applied right-to-left)
+ * @returns The compiled chain function
+ */
+export function wrapChain(handler, middlewares) {
+    let chain = handler;
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+        const mw = middlewares[i];
+        if (!mw)
+            continue;
+        const nextFn = chain;
+        chain = async (ctx, args) => {
+            const result = await mw(ctx, args, () => nextFn(ctx, args));
+            if (result === undefined && !_warnedMiddlewares.has(mw)) {
+                _warnedMiddlewares.add(mw);
+                console.warn(`[vurb] Middleware "${mw.name || '(anonymous)'}" returned undefined. ` +
+                    `Did you forget "return next()"? Without it, the handler never executes ` +
+                    `and the tool silently returns an empty response.`);
+            }
+            return result;
+        };
+    }
+    return chain;
+}
+/**
+ * Pre-compile middleware chains for all actions in a builder.
+ *
+ * For each action:
+ * 1. Wraps generator handlers in a GeneratorResultEnvelope
+ * 2. Applies per-action middlewares (innermost)
+ * 3. Applies global middlewares (outermost)
+ *
+ * @param actions - Registered actions with their handlers and local middleware
+ * @param middlewares - Global middleware stack
+ * @returns Map from action key to compiled chain
+ */
+export function compileMiddlewareChains(actions, middlewares) {
+    const compiled = new Map();
+    for (const action of actions) {
+        // Step 1: Resolve the base handler (regular or generator-wrapped)
+        let handler;
+        if (isAsyncGeneratorFunction(action.handler)) {
+            handler = (ctx, args) => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const gen = action.handler(ctx, args);
+                return Promise.resolve({ __brand: 'GeneratorResultEnvelope', generator: gen });
+            };
+        }
+        else {
+            handler = action.handler;
+        }
+        // Step 2: Wrap with per-action middleware (innermost), then global (outermost)
+        const actionMws = action.middlewares ?? [];
+        const chain = wrapChain(wrapChain(handler, actionMws), middlewares);
+        compiled.set(action.key, chain);
+    }
+    return compiled;
+}
+//# sourceMappingURL=MiddlewareCompiler.js.map

package/dist/core/execution/MiddlewareCompiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiddlewareCompiler.js","sourceRoot":"","sources":["../../../src/core/execution/MiddlewareCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAqB,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAA0C,MAAM,aAAa,CAAC;AAYrE;;;;GAIG;AACH,SAAS,wBAAwB,CAAC,EAAW;IACzC,IAAI,OAAO,EAAE,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC3C,uEAAuE;IACvE,IAAK,EAAwC,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,wBAAwB;QAAE,OAAO,IAAI,CAAC;IAC5G,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,wBAAwB;QAAE,OAAO,IAAI,CAAC;IACnE,8DAA8D;IAC9D,IAAI,OAAO,EAAE,CAAC,SAAS,KAAK,QAAQ,IAAI,EAAE,CAAC,SAAS,KAAK,IAAI;WACtD,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAY,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACrB,OAA0B,EAC1B,WAA8C;IAE9C,IAAI,KAAK,GAAG,OAAO,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,MAAM,MAAM,GAAG,KAAK,CAAC;QACrB,KAAK,GAAG,KAAK,EAAE,GAAa,EAAE,IAA6B,EAAE,EAAE;YAC3D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAC5D,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACtD,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CACR,sBAAsB,EAAE,CAAC,IAAI,IAAI,aAAa,wBAAwB;oBACtE,yEAAyE;oBACzE,kDAAkD,CACrD,CAAC;YACN,CAAC;YACD,OAAO,MAAM,CAAC;QAClB,CAAC,CAAC;IACN,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACnC,OAA4C,EAC5C,WAA8C;IAE9C,MAAM,QAAQ,GAA4B,IAAI,GAAG,EAAE,CAAC;IAEpD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC3B,kEAAkE;QAClE,IAAI,OAA0B,CAAC;QAE/B,IAAI,wBAAwB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,OAAO,GAAG,CAAC,GAAa,EAAE,IAA6B,EAAoB,EAAE;gBACzE,8DAA8D;gBAC9D,MAAM,GAAG,GAAI,MAAM,CAAC,OAAe,CAAC,GAAG,EAAE,IAAI,CAAqD,CAAC;gBACnG,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,GAAG,EAAa,CAAC,CAAC;YAC9F,CAAC,CAAC;QACN,CAAC;aAAM,CAAC;YACJ,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC7B,CAAC;QAED,+EAA+E;QAC/E,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,SAAS,CACnB,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,EAC7B,WAAW,CACd,CAAC;QAEF,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,QAAQ,CAAC;AACpB,CAAC"}

package/dist/core/execution/MutationSerializer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MutationSerializer — Per-Action Intent Mutex for Destructive Operations
+ *
+ * When an LLM hallucinates and fires two `delete_user` calls for the same ID
+ * in the same millisecond, this serializer ensures they execute sequentially —
+ * not concurrently. Transactional isolation at the framework level.
+ *
+ * Architecture:
+ *   ┌────────────────────────────────────────────────────┐
+ *   │  delete_user(id: "42")  ──► serialize("delete")   │
+ *   │  delete_user(id: "42")  ──► queue behind first    │
+ *   │  list_users()           ──► pass-through (readOnly)│
+ *   │  create_user(...)       ──► pass-through (not destr)│
+ *   └────────────────────────────────────────────────────┘
+ *
+ * Mechanism:
+ *   Uses promise-chaining per action key. Each destructive call
+ *   awaits the previous call's completion before starting.
+ *   This is the idiomatic async mutex pattern in JavaScript:
+ *   no external locks, no shared memory, no OS primitives.
+ *
+ * Properties:
+ *   - Zero overhead for non-destructive actions (never called)
+ *   - O(1) setup per serialized call (promise chain append)
+ *   - Automatic GC: completed chains are pruned from the map
+ *   - Cooperative with AbortSignal: cancelled while waiting
+ *   - Per action-key isolation: `billing.delete` ≠ `users.delete`
+ *
+ * @module
+ * @internal
+ */
+/**
+ * An async mutex that serializes destructive operations by action key.
+ *
+ * Created once per builder during `buildToolDefinition()` — only when
+ * at least one action is marked `destructive: true`. Otherwise the
+ * field stays `undefined` (zero overhead).
+ *
+ * Used by `_executePipeline()` to wrap `runChain()` for destructive actions.
+ *
+ * @example
+ * ```
+ * // Concurrent calls to `billing.delete`:
+ * //   Call A → executes immediately
+ * //   Call B → waits for A to complete → then executes
+ * //   Call C → waits for B to complete → then executes
+ * //
+ * // Concurrent calls to `billing.list` (readOnly):
+ * //   All execute in parallel (serializer not invoked)
+ * ```
+ */
+export declare class MutationSerializer {
+    /**
+     * Active promise chains keyed by action key.
+     * Each entry represents the "tail" of the serialization queue.
+     * When the tail resolves, the next waiter starts.
+     */
+    private readonly _chains;
+    /**
+     * Serialize execution of `fn` for the given action key.
+     *
+     * Concurrent calls with the **same key** are queued and executed
+     * strictly in FIFO order. Different keys are fully independent.
+     *
+     * @param key - Action key (e.g., `"delete"` or `"billing.refund"`)
+     * @param fn - The async function to serialize (typically `runChain()`)
+     * @param signal - Optional AbortSignal for cooperative cancellation while waiting
+     * @returns The result of `fn()`
+     * @throws Error if the AbortSignal fires while waiting in queue
+     */
+    serialize<T>(key: string, fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Number of action keys with active serialization chains.
+     * Used for testing and debugging — should be 0 when idle.
+     */
+    get activeChains(): number;
+}
+//# sourceMappingURL=MutationSerializer.d.ts.map

package/dist/core/execution/MutationSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MutationSerializer.d.ts","sourceRoot":"","sources":["../../../src/core/execution/MutationSerializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAkB;IAC3B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAI5D;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,CAAC,EACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,CAAC,CAAC;IA+Bb;;;OAGG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;CACJ"}

package/dist/core/execution/MutationSerializer.js

@@ -0,0 +1,106 @@
+/**
+ * MutationSerializer — Per-Action Intent Mutex for Destructive Operations
+ *
+ * When an LLM hallucinates and fires two `delete_user` calls for the same ID
+ * in the same millisecond, this serializer ensures they execute sequentially —
+ * not concurrently. Transactional isolation at the framework level.
+ *
+ * Architecture:
+ *   ┌────────────────────────────────────────────────────┐
+ *   │  delete_user(id: "42")  ──► serialize("delete")   │
+ *   │  delete_user(id: "42")  ──► queue behind first    │
+ *   │  list_users()           ──► pass-through (readOnly)│
+ *   │  create_user(...)       ──► pass-through (not destr)│
+ *   └────────────────────────────────────────────────────┘
+ *
+ * Mechanism:
+ *   Uses promise-chaining per action key. Each destructive call
+ *   awaits the previous call's completion before starting.
+ *   This is the idiomatic async mutex pattern in JavaScript:
+ *   no external locks, no shared memory, no OS primitives.
+ *
+ * Properties:
+ *   - Zero overhead for non-destructive actions (never called)
+ *   - O(1) setup per serialized call (promise chain append)
+ *   - Automatic GC: completed chains are pruned from the map
+ *   - Cooperative with AbortSignal: cancelled while waiting
+ *   - Per action-key isolation: `billing.delete` ≠ `users.delete`
+ *
+ * @module
+ * @internal
+ */
+// ── Serializer Implementation ────────────────────────────
+/**
+ * An async mutex that serializes destructive operations by action key.
+ *
+ * Created once per builder during `buildToolDefinition()` — only when
+ * at least one action is marked `destructive: true`. Otherwise the
+ * field stays `undefined` (zero overhead).
+ *
+ * Used by `_executePipeline()` to wrap `runChain()` for destructive actions.
+ *
+ * @example
+ * ```
+ * // Concurrent calls to `billing.delete`:
+ * //   Call A → executes immediately
+ * //   Call B → waits for A to complete → then executes
+ * //   Call C → waits for B to complete → then executes
+ * //
+ * // Concurrent calls to `billing.list` (readOnly):
+ * //   All execute in parallel (serializer not invoked)
+ * ```
+ */
+export class MutationSerializer {
+    /**
+     * Active promise chains keyed by action key.
+     * Each entry represents the "tail" of the serialization queue.
+     * When the tail resolves, the next waiter starts.
+     */
+    _chains = new Map();
+    // ── Public API ───────────────────────────────────────
+    /**
+     * Serialize execution of `fn` for the given action key.
+     *
+     * Concurrent calls with the **same key** are queued and executed
+     * strictly in FIFO order. Different keys are fully independent.
+     *
+     * @param key - Action key (e.g., `"delete"` or `"billing.refund"`)
+     * @param fn - The async function to serialize (typically `runChain()`)
+     * @param signal - Optional AbortSignal for cooperative cancellation while waiting
+     * @returns The result of `fn()`
+     * @throws Error if the AbortSignal fires while waiting in queue
+     */
+    async serialize(key, fn, signal) {
+        // Append to the chain for this key
+        const prev = this._chains.get(key) ?? Promise.resolve();
+        let releaseLock;
+        const lock = new Promise(resolve => { releaseLock = resolve; });
+        this._chains.set(key, lock);
+        try {
+            // Wait for previous operation on this key to complete
+            await prev;
+            // Check if cancelled while waiting in the serialization queue
+            if (signal?.aborted) {
+                throw new Error('Request cancelled while waiting for mutation lock.');
+            }
+            return await fn();
+        }
+        finally {
+            releaseLock();
+            // GC: if this was the last link in the chain, prune the entry
+            // so the map doesn't grow unboundedly with resolved promises.
+            if (this._chains.get(key) === lock) {
+                this._chains.delete(key);
+            }
+        }
+    }
+    // ── Diagnostics ──────────────────────────────────────
+    /**
+     * Number of action keys with active serialization chains.
+     * Used for testing and debugging — should be 0 when idle.
+     */
+    get activeChains() {
+        return this._chains.size;
+    }
+}
+//# sourceMappingURL=MutationSerializer.js.map

package/dist/core/execution/MutationSerializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MutationSerializer.js","sourceRoot":"","sources":["../../../src/core/execution/MutationSerializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,kBAAkB;IAC3B;;;;OAIG;IACc,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE5D,wDAAwD;IAExD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,SAAS,CACX,GAAW,EACX,EAAoB,EACpB,MAAoB;QAEpB,mCAAmC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAExD,IAAI,WAAwB,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,GAAG,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAE5B,IAAI,CAAC;YACD,sDAAsD;YACtD,MAAM,IAAI,CAAC;YAEX,8DAA8D;YAC9D,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YAC1E,CAAC;YAED,OAAO,MAAM,EAAE,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACP,WAAW,EAAE,CAAC;YAEd,8DAA8D;YAC9D,8DAA8D;YAC9D,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;gBACjC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC;IACL,CAAC;IAED,wDAAwD;IAExD;;;OAGG;IACH,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC7B,CAAC;CACJ"}