@vurb/core 3.2.0

package/dist/prompt/FluentPromptBuilder.js

@@ -0,0 +1,195 @@
+/**
+ * FluentPromptBuilder — Chainable Prompt Definition API
+ *
+ * Provides a builder-pattern alternative to the config-bag `definePrompt()`.
+ * Follows the same architectural pattern as `FluentToolBuilder`.
+ *
+ * @example
+ * ```typescript
+ * const greet = f.prompt('greet')
+ *     .describe('Greet a user by name')
+ *     .input({ name: f.string() })
+ *     .handler(async (ctx, { name }) => ({
+ *         messages: [PromptMessage.user(`Hello ${name}!`)],
+ *     }));
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import {} from './types.js';
+import {} from '../core/types.js';
+import { definePrompt } from './definePrompt.js';
+// ============================================================================
+// FluentPromptBuilder
+// ============================================================================
+/**
+ * Chainable builder for MCP Prompts.
+ *
+ * Each setter returns `this` for chaining. Finalisation happens lazily
+ * when the `PromptBuilder` interface methods are accessed — this means
+ * you can pass a `FluentPromptBuilder` directly to `PromptRegistry.register()`.
+ *
+ * @typeParam TContext - Application context type (inherited from `initVurb`)
+ * @typeParam TArgs - Inferred argument type from the schema
+ */
+export class FluentPromptBuilder {
+    _name;
+    _title;
+    _description;
+    _icons;
+    _tags = [];
+    _middlewares = [];
+    _args;
+    _hydrationTimeout;
+    _handler;
+    /** @internal Cached delegate built on first access to PromptBuilder methods */
+    _delegate;
+    constructor(name) {
+        this._name = name;
+    }
+    // ── Chainable Setters ────────────────────────────────
+    /**
+     * Set a human-readable title for UI display.
+     *
+     * @param title - The prompt title
+     * @returns `this` for chaining
+     */
+    title(title) {
+        this._title = title;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the prompt description shown in the slash command palette.
+     *
+     * @param description - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(description) {
+        this._description = description;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set icons for light/dark themes.
+     *
+     * @param icons - Icon paths for light and/or dark themes
+     * @returns `this` for chaining
+     */
+    icons(icons) {
+        this._icons = icons;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set capability tags for selective exposure.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags) {
+        // Bug #113 fix: append instead of replace, matching FluentToolBuilder’s
+        // accumulative .tags() semantics.
+        this._tags.push(...tags);
+        this._delegate = undefined;
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input(schemaOrParams) {
+        this._args = schemaOrParams;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Add middleware to the prompt's execution pipeline.
+     *
+     * Middleware runs in registration order around the handler
+     * (same onion model as tool middleware).
+     *
+     * @param fns - Middleware functions
+     * @returns `this` for chaining
+     */
+    use(...fns) {
+        this._middlewares.push(...fns);
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the maximum hydration time in milliseconds.
+     *
+     * If the handler doesn't complete within this time,
+     * the framework returns a graceful SYSTEM ALERT.
+     *
+     * @param ms - Timeout in milliseconds
+     * @returns `this` for chaining
+     */
+    timeout(ms) {
+        this._hydrationTimeout = ms;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the hydration handler.
+     *
+     * This is the terminal method — after calling `.handler()`,
+     * the builder is ready to be registered.
+     *
+     * @param fn - Handler function receiving `(ctx, args)` → `PromptResult`
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * .handler(async (ctx, { name }) => ({
+     *     messages: [PromptMessage.user(`Hello ${name}!`)],
+     * }))
+     * ```
+     */
+    handler(fn) {
+        this._handler = fn;
+        this._delegate = undefined;
+        return this;
+    }
+    // ── PromptBuilder Interface (delegation) ─────────────
+    /** @internal Build the underlying PromptBuilder delegate lazily */
+    _build() {
+        if (this._delegate)
+            return this._delegate;
+        if (!this._handler) {
+            throw new Error(`FluentPromptBuilder('${this._name}'): .handler() must be called before the prompt can be used.`);
+        }
+        this._delegate = definePrompt(this._name, {
+            title: this._title,
+            description: this._description,
+            icons: this._icons,
+            tags: this._tags.length > 0 ? this._tags : undefined,
+            middleware: this._middlewares.length > 0 ? this._middlewares : undefined,
+            args: this._args,
+            hydrationTimeout: this._hydrationTimeout,
+            handler: this._handler,
+        });
+        return this._delegate;
+    }
+    getName() {
+        return this._name;
+    }
+    getDescription() {
+        return this._description;
+    }
+    getTags() {
+        return this._tags;
+    }
+    hasMiddleware() {
+        return this._middlewares.length > 0;
+    }
+    getHydrationTimeout() {
+        return this._hydrationTimeout;
+    }
+    buildPromptDefinition() {
+        return this._build().buildPromptDefinition();
+    }
+    execute(ctx, args) {
+        return this._build().execute(ctx, args);
+    }
+}
+//# sourceMappingURL=FluentPromptBuilder.js.map

package/dist/prompt/FluentPromptBuilder.js.map

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

package/dist/prompt/HydrationSandbox.d.ts

@@ -0,0 +1,55 @@
+/**
+ * HydrationSandbox — Structured Deadline for Prompt Server-Side Hydration
+ *
+ * When a user invokes `/morning_briefing`, the prompt handler performs
+ * server-side hydration: fetching Jira tickets, Stripe invoices, database
+ * queries. If any external source hangs (15s Jira timeout, API 500),
+ * the user stares at a frozen UI.
+ *
+ * This sandbox wraps the handler in a strict `Promise.race` deadline:
+ *
+ *   ┌─────────────────────────────────────────────────┐
+ *   │  Promise.race([                                 │
+ *   │    handler(ctx, args),     ← the real work      │
+ *   │    deadlinePromise(3s),   ← the safety net      │
+ *   │  ])                                             │
+ *   │                                                 │
+ *   │  Winner:                                        │
+ *   │    handler  → return result (happy path)        │
+ *   │    deadline → return SYSTEM ALERT (graceful)    │
+ *   │    handler throws → return ERROR ALERT (catch)  │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Three guarantees:
+ *   1. The UI unblocks within `deadlineMs` — always.
+ *   2. Handler errors become graceful alerts, not -32603 crashes.
+ *   3. Timers are cleaned via `finally` — no resource leaks.
+ *
+ * Design influenced by:
+ *   - Go's `context.WithDeadline` (structured cancellation)
+ *   - gRPC deadline propagation (strict, per-call)
+ *   - Resilience4j's TimeLimiter (JVM circuit breaker pattern)
+ *
+ * @module
+ * @internal
+ */
+import { type PromptResult } from './types.js';
+/**
+ * Execute a prompt hydration function within a strict deadline.
+ *
+ * Uses `Promise.race` between the handler and a timeout promise.
+ * Three scenarios:
+ *
+ * 1. **Handler wins** (completes before deadline) → returns result
+ * 2. **Deadline wins** (handler too slow) → returns TIMEOUT alert
+ * 3. **Handler throws** (API error, crash) → returns ERROR alert
+ *
+ * In ALL cases, the caller receives a valid `PromptResult`.
+ * The UI never freezes. The user never sees `-32603`.
+ *
+ * @param fn - The prompt hydration function to execute
+ * @param deadlineMs - Maximum time in milliseconds (must be > 0)
+ * @returns Always returns a valid PromptResult
+ */
+export declare function runWithHydrationDeadline(fn: () => Promise<PromptResult>, deadlineMs: number): Promise<PromptResult>;
+//# sourceMappingURL=HydrationSandbox.d.ts.map

package/dist/prompt/HydrationSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HydrationSandbox.d.ts","sourceRoot":"","sources":["../../src/prompt/HydrationSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAmE/C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC1C,EAAE,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EAC/B,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,YAAY,CAAC,CAwBvB"}

package/dist/prompt/HydrationSandbox.js

@@ -0,0 +1,122 @@
+/**
+ * HydrationSandbox — Structured Deadline for Prompt Server-Side Hydration
+ *
+ * When a user invokes `/morning_briefing`, the prompt handler performs
+ * server-side hydration: fetching Jira tickets, Stripe invoices, database
+ * queries. If any external source hangs (15s Jira timeout, API 500),
+ * the user stares at a frozen UI.
+ *
+ * This sandbox wraps the handler in a strict `Promise.race` deadline:
+ *
+ *   ┌─────────────────────────────────────────────────┐
+ *   │  Promise.race([                                 │
+ *   │    handler(ctx, args),     ← the real work      │
+ *   │    deadlinePromise(3s),   ← the safety net      │
+ *   │  ])                                             │
+ *   │                                                 │
+ *   │  Winner:                                        │
+ *   │    handler  → return result (happy path)        │
+ *   │    deadline → return SYSTEM ALERT (graceful)    │
+ *   │    handler throws → return ERROR ALERT (catch)  │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Three guarantees:
+ *   1. The UI unblocks within `deadlineMs` — always.
+ *   2. Handler errors become graceful alerts, not -32603 crashes.
+ *   3. Timers are cleaned via `finally` — no resource leaks.
+ *
+ * Design influenced by:
+ *   - Go's `context.WithDeadline` (structured cancellation)
+ *   - gRPC deadline propagation (strict, per-call)
+ *   - Resilience4j's TimeLimiter (JVM circuit breaker pattern)
+ *
+ * @module
+ * @internal
+ */
+import {} from './types.js';
+// ── Alert Formatters ─────────────────────────────────────
+/**
+ * Build an XML-structured SYSTEM ALERT for the LLM.
+ *
+ * Uses XML semantic boundaries so the LLM can parse the
+ * alert deterministically — same pattern as our self-healing
+ * tool errors (`<tool_error>`, `<validation_error>`).
+ */
+function formatHydrationAlert(status, deadlineMs, errorMessage) {
+    const parts = ['<hydration_alert>'];
+    parts.push(`  <status>${status}</status>`);
+    parts.push(`  <deadline_ms>${deadlineMs}</deadline_ms>`);
+    if (status === 'TIMEOUT') {
+        parts.push(`  <message>Prompt hydration did not complete within ${(deadlineMs / 1000).toFixed(1)}s. ` +
+            `External data sources (APIs, databases) did not respond within the deadline.</message>`);
+    }
+    else {
+        parts.push(`  <message>Prompt hydration failed: ${errorMessage ?? 'Unknown error'}.</message>`);
+    }
+    parts.push('  <guidance>Proceed with the conversation using available context. ' +
+        'The user\'s request is still valid — answer with your general knowledge ' +
+        'and inform the user that live data could not be fetched at this time. ' +
+        'Do NOT retry the same prompt automatically.</guidance>');
+    parts.push('</hydration_alert>');
+    return parts.join('\n');
+}
+/**
+ * Wrap a hydration alert as a valid `PromptResult`.
+ *
+ * Returns a single `user` message with the XML alert.
+ * MCP `PromptMessage` only supports `user`|`assistant` roles.
+ */
+function alertAsPromptResult(status, deadlineMs, errorMessage) {
+    return {
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: formatHydrationAlert(status, deadlineMs, errorMessage),
+                },
+            }],
+    };
+}
+// ── Sandbox Execution ────────────────────────────────────
+/**
+ * Execute a prompt hydration function within a strict deadline.
+ *
+ * Uses `Promise.race` between the handler and a timeout promise.
+ * Three scenarios:
+ *
+ * 1. **Handler wins** (completes before deadline) → returns result
+ * 2. **Deadline wins** (handler too slow) → returns TIMEOUT alert
+ * 3. **Handler throws** (API error, crash) → returns ERROR alert
+ *
+ * In ALL cases, the caller receives a valid `PromptResult`.
+ * The UI never freezes. The user never sees `-32603`.
+ *
+ * @param fn - The prompt hydration function to execute
+ * @param deadlineMs - Maximum time in milliseconds (must be > 0)
+ * @returns Always returns a valid PromptResult
+ */
+export async function runWithHydrationDeadline(fn, deadlineMs) {
+    let timer;
+    // Deadline promise: resolves with TIMEOUT alert after deadline
+    const deadlinePromise = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(alertAsPromptResult('TIMEOUT', deadlineMs));
+        }, deadlineMs);
+    });
+    // Handler promise: wraps fn() to catch errors → ERROR alert
+    const handlerPromise = fn().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        return alertAsPromptResult('ERROR', deadlineMs, message);
+    });
+    try {
+        // First to finish wins. UI unblocks immediately.
+        return await Promise.race([handlerPromise, deadlinePromise]);
+    }
+    finally {
+        // Always clean up the timer — prevents resource leaks
+        // and keeps Node.js from staying alive unnecessarily.
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=HydrationSandbox.js.map

package/dist/prompt/HydrationSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HydrationSandbox.js","sourceRoot":"","sources":["../../src/prompt/HydrationSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAqB,MAAM,YAAY,CAAC;AAE/C,4DAA4D;AAE5D;;;;;;GAMG;AACH,SAAS,oBAAoB,CACzB,MAA2B,EAC3B,UAAkB,EAClB,YAAqB;IAErB,MAAM,KAAK,GAAa,CAAC,mBAAmB,CAAC,CAAC;IAE9C,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,WAAW,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,kBAAkB,UAAU,gBAAgB,CAAC,CAAC;IAEzD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CACN,uDAAuD,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;YAC1F,wFAAwF,CAC3F,CAAC;IACN,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CACN,uCAAuC,YAAY,IAAI,eAAe,aAAa,CACtF,CAAC;IACN,CAAC;IAED,KAAK,CAAC,IAAI,CACN,qEAAqE;QACrE,0EAA0E;QAC1E,wEAAwE;QACxE,wDAAwD,CAC3D,CAAC;IAEF,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CACxB,MAA2B,EAC3B,UAAkB,EAClB,YAAqB;IAErB,OAAO;QACH,QAAQ,EAAE,CAAC;gBACP,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC;iBAC/D;aACJ,CAAC;KACL,CAAC;AACN,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC1C,EAA+B,EAC/B,UAAkB;IAElB,IAAI,KAAgD,CAAC;IAErD,+DAA+D;IAC/D,MAAM,eAAe,GAAG,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,EAAE;QAC1D,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACpB,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;QACxD,CAAC,EAAE,UAAU,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,4DAA4D;IAC5D,MAAM,cAAc,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAgB,EAAE;QACpD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACD,iDAAiD;QACjD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IACjE,CAAC;YAAS,CAAC;QACP,sDAAsD;QACtD,sDAAsD;QACtD,IAAI,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;AACL,CAAC"}

package/dist/prompt/PromptExecutionPipeline.d.ts

@@ -0,0 +1,61 @@
+/**
+ * PromptExecutionPipeline — Prompt Hydration Pipeline
+ *
+ * Handles the complete lifecycle of a `prompts/get` request:
+ *
+ *   1. Schema-Informed Coercion (string → typed values)
+ *   2. Zod Validation (.strict() + coaching errors)
+ *   3. Middleware Chain execution
+ *   4. Handler invocation
+ *
+ * Key feature: **Schema-Informed Boundary Coercion**
+ * MCP transmits ALL prompt arguments as `Record<string, string>`.
+ * This module reads the Zod schema AST to determine expected types
+ * and coerces string values deterministically — no guessing.
+ *
+ * @module
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type PromptResult } from './types.js';
+import { type MiddlewareFn } from '../core/types.js';
+/**
+ * Assert that a Zod schema only contains flat primitive fields.
+ *
+ * Throws a descriptive error if any field uses arrays, objects,
+ * tuples, records, maps, or sets — types that MCP clients cannot
+ * render as visual form fields.
+ *
+ * Called at **definition time** (in `definePrompt()`) to fail fast
+ * and prevent runtime surprises.
+ *
+ * @param schema - The Zod schema to validate
+ * @throws Error with coaching message if nested types are found
+ */
+export declare function assertFlatSchema(schema: ZodObject<ZodRawShape>): void;
+/**
+ * Schema-Informed Boundary Coercion.
+ *
+ * Reads the Zod schema AST to determine expected types,
+ * then coerces string values from the MCP wire format.
+ *
+ * This is NOT guessing. The coercion is derived from the
+ * developer's declared schema — it's deterministic.
+ *
+ * @param rawArgs - Raw string arguments from the MCP client
+ * @param zodSchema - The validated Zod schema for this prompt
+ * @returns Coerced argument values ready for Zod validation
+ */
+export declare function coercePromptArgs(rawArgs: Record<string, string>, zodSchema: ZodObject<ZodRawShape>): Record<string, unknown>;
+/**
+ * Execute the full prompt hydration pipeline.
+ *
+ * Steps:
+ * 1. Coerce string args to typed values using schema AST
+ * 2. Validate with Zod (.strict() enforced)
+ * 3. Run middleware chain
+ * 4. Execute handler
+ *
+ * @returns Either a `PromptResult` or an error `PromptResult` with coaching
+ */
+export declare function executePromptPipeline<TContext>(ctx: TContext, rawArgs: Record<string, string>, schema: ZodObject<ZodRawShape> | undefined, middlewares: readonly MiddlewareFn<TContext>[], handler: (ctx: TContext, args: Record<string, unknown>) => Promise<PromptResult>): Promise<PromptResult>;
+//# sourceMappingURL=PromptExecutionPipeline.d.ts.map

package/dist/prompt/PromptExecutionPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromptExecutionPipeline.d.ts","sourceRoot":"","sources":["../../src/prompt/PromptExecutionPipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAmB,MAAM,KAAK,CAAC;AACxE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsCrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,IAAI,CAYrE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiCzB;AA0BD;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAChD,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,EAC1C,WAAW,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,EAC9C,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,GACjF,OAAO,CAAC,YAAY,CAAC,CAgCvB"}

package/dist/prompt/PromptExecutionPipeline.js

@@ -0,0 +1,177 @@
+/**
+ * PromptExecutionPipeline — Prompt Hydration Pipeline
+ *
+ * Handles the complete lifecycle of a `prompts/get` request:
+ *
+ *   1. Schema-Informed Coercion (string → typed values)
+ *   2. Zod Validation (.strict() + coaching errors)
+ *   3. Middleware Chain execution
+ *   4. Handler invocation
+ *
+ * Key feature: **Schema-Informed Boundary Coercion**
+ * MCP transmits ALL prompt arguments as `Record<string, string>`.
+ * This module reads the Zod schema AST to determine expected types
+ * and coerces string values deterministically — no guessing.
+ *
+ * @module
+ */
+import {} from 'zod';
+import {} from './types.js';
+import {} from '../core/types.js';
+import { escapeXml, escapeXmlAttr } from '../core/response.js';
+import { wrapChain } from '../core/execution/MiddlewareCompiler.js';
+// ── Flat Schema Guard ────────────────────────────────────
+/** Zod type names that are NOT allowed in prompt argument schemas */
+const FORBIDDEN_ZOD_TYPES = new Set([
+    'ZodArray', 'ZodObject', 'ZodTuple', 'ZodRecord', 'ZodMap', 'ZodSet',
+]);
+/**
+ * Get the base Zod type name, unwrapping Optional/Default/Nullable wrappers.
+ * @internal
+ */
+function getZodBaseTypeName(schema) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const def = schema._def;
+    if (def === undefined || def === null)
+        return 'Unknown';
+    const typeName = def.typeName ?? '';
+    // Unwrap Optional, Default, Nullable, Effects to find the inner type
+    if (typeName === 'ZodOptional' ||
+        typeName === 'ZodDefault' ||
+        typeName === 'ZodNullable') {
+        return getZodBaseTypeName(def.innerType);
+    }
+    if (typeName === 'ZodEffects') {
+        return getZodBaseTypeName(def.schema);
+    }
+    return typeName;
+}
+/**
+ * Assert that a Zod schema only contains flat primitive fields.
+ *
+ * Throws a descriptive error if any field uses arrays, objects,
+ * tuples, records, maps, or sets — types that MCP clients cannot
+ * render as visual form fields.
+ *
+ * Called at **definition time** (in `definePrompt()`) to fail fast
+ * and prevent runtime surprises.
+ *
+ * @param schema - The Zod schema to validate
+ * @throws Error with coaching message if nested types are found
+ */
+export function assertFlatSchema(schema) {
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const typeName = getZodBaseTypeName(field);
+        if (FORBIDDEN_ZOD_TYPES.has(typeName)) {
+            throw new Error(`[definePrompt] Argument '${key}' uses type '${typeName}', which is not supported ` +
+                `in MCP prompt arguments. MCP clients render prompt args as visual forms — only ` +
+                `flat primitives (string, number, boolean, enum) are supported.\n` +
+                `💡 If you need complex data, fetch it server-side inside the handler instead.`);
+        }
+    }
+}
+// ── Schema-Informed Coercion ─────────────────────────────
+/**
+ * Schema-Informed Boundary Coercion.
+ *
+ * Reads the Zod schema AST to determine expected types,
+ * then coerces string values from the MCP wire format.
+ *
+ * This is NOT guessing. The coercion is derived from the
+ * developer's declared schema — it's deterministic.
+ *
+ * @param rawArgs - Raw string arguments from the MCP client
+ * @param zodSchema - The validated Zod schema for this prompt
+ * @returns Coerced argument values ready for Zod validation
+ */
+export function coercePromptArgs(rawArgs, zodSchema) {
+    const coerced = {};
+    const shape = zodSchema.shape;
+    for (const [key, value] of Object.entries(rawArgs)) {
+        const fieldSchema = shape[key];
+        if (!fieldSchema) {
+            // Unknown field — pass through, let Zod .strict() reject it
+            coerced[key] = value;
+            continue;
+        }
+        const typeName = getZodBaseTypeName(fieldSchema);
+        switch (typeName) {
+            case 'ZodBoolean':
+                coerced[key] = typeof value === 'string'
+                    ? value.toLowerCase() === 'true' || value === '1'
+                    : Boolean(value);
+                break;
+            case 'ZodNumber':
+                if (value === '')
+                    break; // leave missing — let Zod reject
+                coerced[key] = Number(value);
+                break;
+            case 'ZodEnum':
+            case 'ZodString':
+            default:
+                coerced[key] = value;
+                break;
+        }
+    }
+    return coerced;
+}
+// ── Validation ───────────────────────────────────────────
+/**
+ * Format a Zod validation error into a coaching prompt.
+ *
+ * Returns a human+LLM readable error that guides the agent
+ * (or the user via the MCP client) to correct the input.
+ */
+function formatPromptValidationError(issues) {
+    const parts = ['<validation_error>'];
+    for (const issue of issues) {
+        const field = issue.path.join('.') || '(root)';
+        parts.push(`<field name="${escapeXmlAttr(field)}">${escapeXml(issue.message)}</field>`);
+    }
+    parts.push('<recovery>Check the prompt definition for valid argument types and values.</recovery>');
+    parts.push('</validation_error>');
+    return parts.join('\n');
+}
+// ── Middleware ──────────────────────────────────────────
+// Uses the canonical wrapChain from MiddlewareCompiler (DRY).
+// ── Pipeline ─────────────────────────────────────────────
+/**
+ * Execute the full prompt hydration pipeline.
+ *
+ * Steps:
+ * 1. Coerce string args to typed values using schema AST
+ * 2. Validate with Zod (.strict() enforced)
+ * 3. Run middleware chain
+ * 4. Execute handler
+ *
+ * @returns Either a `PromptResult` or an error `PromptResult` with coaching
+ */
+export async function executePromptPipeline(ctx, rawArgs, schema, middlewares, handler) {
+    // Step 1 + 2: Coerce and validate
+    let validatedArgs = rawArgs;
+    if (schema) {
+        const coerced = coercePromptArgs(rawArgs, schema);
+        const result = schema.strict().safeParse(coerced);
+        if (!result.success) {
+            // Return a validation error as a user message
+            return {
+                messages: [{
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: formatPromptValidationError(result.error.issues),
+                        },
+                    }],
+            };
+        }
+        validatedArgs = result.data;
+    }
+    // Step 3 + 4: Middleware chain → handler
+    if (middlewares.length > 0) {
+        const chain = wrapChain(handler, middlewares);
+        const result = await chain(ctx, validatedArgs);
+        return result;
+    }
+    return handler(ctx, validatedArgs);
+}
+//# sourceMappingURL=PromptExecutionPipeline.js.map

package/dist/prompt/PromptExecutionPipeline.js.map

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