@vurb/core 3.2.0

package/dist/presenter/ui.js

@@ -0,0 +1,222 @@
+/**
+ * UI Block Helpers — Server-Side Rendering for AI Agents
+ *
+ * Deterministic helpers that wrap structured content into fenced
+ * code blocks (or raw markup) for LLM pass-through rendering.
+ *
+ * Today these produce `text` blocks with fenced syntax.
+ * If MCP adds native UI content types in the future, only
+ * the internal `fence()` wrapper needs to change — all Presenters
+ * and consumers stay intact.
+ *
+ * @example
+ * ```typescript
+ * import { ui } from 'vurb';
+ *
+ * ui.echarts({ title: { text: 'Burndown' }, series: [...] });
+ * ui.mermaid('graph TD; A-->B');
+ * ui.markdown('| Col | Val |');
+ * ui.table(['ID', 'Status'], [['INV-1', '✅ Paid']]);
+ * ui.list(['Deploy', 'Migrate', 'Verify']);
+ * ui.json({ key: 'value' });
+ * ui.summary('3 items found. 2 active, 1 archived.');
+ * ```
+ *
+ * @module
+ */
+// ── Internal Helpers ─────────────────────────────────────
+/**
+ * Wrap content in a fenced code block.
+ *
+ * Single point of change for the fencing format. If MCP adds
+ * native block types in the future, only this function needs updating.
+ *
+ * @internal
+ */
+function fence(lang, body) {
+    return `\`\`\`${lang}\n${body}\n\`\`\``;
+}
+// ── Core 4 Helpers ───────────────────────────────────────
+/**
+ * Generate an ECharts UI block from a configuration object.
+ *
+ * The config is serialized with `JSON.stringify(config, null, 2)` for
+ * deterministic, hallucination-free chart rendering.
+ *
+ * @param config - A valid ECharts option object
+ * @returns A {@link UiBlock} with fenced `echarts` code block
+ *
+ * @example
+ * ```typescript
+ * ui.echarts({
+ *     title: { text: 'Sprint Burndown' },
+ *     xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
+ *     series: [{ type: 'line', data: [5, 3, 1] }]
+ * });
+ * ```
+ */
+function echarts(config) {
+    return { type: 'echarts', content: fence('echarts', JSON.stringify(config, null, 2)) };
+}
+/**
+ * Generate a Mermaid diagram UI block.
+ *
+ * @param diagram - Raw Mermaid diagram syntax
+ * @returns A {@link UiBlock} with fenced `mermaid` code block
+ *
+ * @example
+ * ```typescript
+ * ui.mermaid('graph TD; A["Start"] --> B["Process"] --> C["End"]');
+ * ```
+ */
+function mermaid(diagram) {
+    return { type: 'mermaid', content: fence('mermaid', diagram) };
+}
+/**
+ * Generate a raw Markdown UI block.
+ *
+ * Unlike other helpers, markdown content is **not** fenced —
+ * it's returned as-is for direct rendering.
+ *
+ * @param md - Raw Markdown string
+ * @returns A {@link UiBlock} with raw markdown content
+ *
+ * @example
+ * ```typescript
+ * ui.markdown('| Task | Status |\n|---|---|\n| Deploy | ✅ Done |');
+ * ```
+ */
+function markdown(md) {
+    return { type: 'markdown', content: md };
+}
+/**
+ * Generate a generic fenced code block UI block.
+ *
+ * Fallback helper for structured content (logs, XML, raw JSON)
+ * that needs explicit language tagging.
+ *
+ * @param lang - Language identifier for syntax highlighting
+ * @param code - Code content
+ * @returns A {@link UiBlock} with fenced code block
+ *
+ * @example
+ * ```typescript
+ * ui.codeBlock('json', JSON.stringify(config, null, 2));
+ * ui.codeBlock('xml', '<root><item>value</item></root>');
+ * ```
+ */
+function codeBlock(lang, code) {
+    return { type: lang, content: fence(lang, code) };
+}
+// ── DX Helpers ───────────────────────────────────────────
+/**
+ * Generate a Markdown table UI block from headers and row data.
+ *
+ * The **#1 most common pattern** in data tools. Automatically
+ * generates a fully formatted markdown table with alignment
+ * separators — zero manual string concatenation needed.
+ *
+ * @param headers - Column header labels
+ * @param rows - Array of row arrays (each inner array = one row)
+ * @returns A {@link UiBlock} with formatted markdown table
+ *
+ * @example
+ * ```typescript
+ * ui.table(
+ *     ['Invoice', 'Amount', 'Status'],
+ *     [
+ *         ['INV-001', '$4,500.00', '✅ Paid'],
+ *         ['INV-002', '$1,200.00', '⚠️ Pending'],
+ *     ],
+ * );
+ * ```
+ */
+function table(headers, rows) {
+    const headerRow = `| ${headers.join(' | ')} |`;
+    const separator = `| ${headers.map(() => '---').join(' | ')} |`;
+    const bodyRows = rows.map(row => `| ${row.join(' | ')} |`).join('\n');
+    return { type: 'markdown', content: `${headerRow}\n${separator}\n${bodyRows}` };
+}
+/**
+ * Generate a Markdown bullet list UI block.
+ *
+ * Perfect for action items, checklists, or enumerated results.
+ *
+ * @param items - Array of list items (strings)
+ * @returns A {@link UiBlock} with markdown list content
+ *
+ * @example
+ * ```typescript
+ * ui.list(['Deploy API server', 'Run database migrations', 'Verify health checks']);
+ * // → "- Deploy API server\n- Run database migrations\n- Verify health checks"
+ * ```
+ */
+function list(items) {
+    return { type: 'markdown', content: items.map(item => `- ${item}`).join('\n') };
+}
+/**
+ * Generate a fenced JSON code block UI block.
+ *
+ * Shorthand for `ui.codeBlock('json', JSON.stringify(data, null, 2))`.
+ * Most developers reach for this pattern constantly.
+ *
+ * @param data - Any JSON-serializable value
+ * @returns A {@link UiBlock} with fenced `json` code block
+ *
+ * @example
+ * ```typescript
+ * ui.json({ host: 'api.example.com', port: 3000, ssl: true });
+ * ```
+ */
+function json(data) {
+    return { type: 'json', content: fence('json', JSON.stringify(data, null, 2)) };
+}
+/**
+ * Generate a summary UI block for collection overviews.
+ *
+ * Placed at the top of collection responses to give the LLM
+ * quick context about the dataset without parsing the full array.
+ *
+ * @param text - Human-readable summary of the collection
+ * @returns A {@link UiBlock} with summary content
+ *
+ * @example
+ * ```typescript
+ * ui.summary('3 invoices totaling $5,700.00. 2 paid, 1 pending.');
+ * ```
+ */
+function summary(text) {
+    return { type: 'summary', content: `📊 **Summary**: ${text}` };
+}
+// ── Public Namespace ─────────────────────────────────────
+/**
+ * UI block helpers for Server-Side Rendering (SSR) in Presenters.
+ *
+ * **Core helpers**: `echarts`, `mermaid`, `markdown`, `codeBlock`
+ * **DX helpers**: `table`, `list`, `json`, `summary`
+ *
+ * @example
+ * ```typescript
+ * import { ui } from 'vurb';
+ *
+ * // Quick table from arrays
+ * ui.table(['Name', 'Status'], [['Alice', 'Active'], ['Bob', 'Inactive']]);
+ *
+ * // Quick list
+ * ui.list(['Step 1: Deploy', 'Step 2: Verify']);
+ *
+ * // Quick JSON viewer
+ * ui.json({ config: { debug: true } });
+ *
+ * // Charts and diagrams
+ * ui.echarts(chartConfig);
+ * ui.mermaid('graph TD; A-->B');
+ * ```
+ */
+export const ui = {
+    // Core 4
+    echarts, mermaid, markdown, codeBlock,
+    // DX helpers
+    table, list, json, summary,
+};
+//# sourceMappingURL=ui.js.map

package/dist/presenter/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../src/presenter/ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiBH,4DAA4D;AAE5D;;;;;;;GAOG;AACH,SAAS,KAAK,CAAC,IAAY,EAAE,IAAY;IACrC,OAAO,SAAS,IAAI,KAAK,IAAI,UAAU,CAAC;AAC5C,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,OAAO,CAAC,MAA+B;IAC5C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,OAAO,CAAC,OAAe;IAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,QAAQ,CAAC,EAAU;IACxB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,IAAY;IACzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,KAAK,CAAC,OAA0B,EAAE,IAAoC;IAC3E,MAAM,SAAS,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC/C,MAAM,SAAS,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,SAAS,KAAK,SAAS,KAAK,QAAQ,EAAE,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,IAAI,CAAC,KAAwB;IAClC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,IAAI,CAAC,IAAa;IACvB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,OAAO,CAAC,IAAY;IACzB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,IAAI,EAAE,EAAE,CAAC;AACnE,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG;IACd,SAAS;IACT,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS;IACrC,aAAa;IACb,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO;CACpB,CAAC"}

package/dist/prompt/CursorCodec.d.ts

@@ -0,0 +1,43 @@
+export interface CursorPayload {
+    after: string;
+}
+export type CursorMode = 'signed' | 'encrypted';
+export interface CursorCodecOptions {
+    /**
+     * 'signed' (default): HMAC signature appended to base64 payload. Payload is visible but tamper-proof.
+     * 'encrypted': AES-GCM encryption. Payload is completely hidden and tamper-proof.
+     */
+    mode?: CursorMode;
+    /**
+     * Optional 32-byte secret key.
+     * If not provided, a random ephemeral key is generated per process.
+     */
+    secret?: string;
+}
+/**
+ * Stateless Cryptographic Cursor for pagination using Web Crypto API.
+ *
+ * Works in Node >= 16, Deno, Bun, and Cloudflare Workers.
+ */
+export declare class CursorCodec {
+    private readonly _mode;
+    private _secretBytes;
+    private _secretPromise;
+    private readonly _providedSecret;
+    private _hmacKey?;
+    private _aesKey?;
+    constructor(options?: CursorCodecOptions);
+    private ensureSecret;
+    private getHmacKey;
+    private getAesKey;
+    /**
+     * Asynchronously encodes a payload into a URL-safe cursor string.
+     */
+    encode(payload: CursorPayload): Promise<string>;
+    /**
+     * Asynchronously decodes and verifies a cursor string back into its payload.
+     * Returns undefined if the cursor is invalid, tampered with, or from a different process/key.
+     */
+    decode(cursor: string): Promise<CursorPayload | undefined>;
+}
+//# sourceMappingURL=CursorCodec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CursorCodec.d.ts","sourceRoot":"","sources":["../../src/prompt/CursorCodec.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAyDD;;;;GAIG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAY;gBAEhB,OAAO,CAAC,EAAE,kBAAkB;YAe1B,YAAY;YAYZ,UAAU;YAeV,SAAS;IAevB;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BrD;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;CAsDnE"}

package/dist/prompt/CursorCodec.js

@@ -0,0 +1,171 @@
+/**
+ * Lazily resolves the Web Crypto API.
+ * Works in Node >= 16 (via node:crypto.webcrypto), Node >= 19 (globalThis.crypto),
+ * Deno, Bun, and Cloudflare Workers.
+ */
+let _resolvedCrypto;
+async function getCrypto() {
+    if (_resolvedCrypto)
+        return _resolvedCrypto;
+    // globalThis.crypto.subtle is available in Node >= 19, Deno, Bun, CF Workers
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
+        _resolvedCrypto = globalThis.crypto;
+        return _resolvedCrypto;
+    }
+    // Node.js 16-18 fallback — webcrypto available via node:crypto module
+    // Variable indirection prevents TypeScript from resolving the module statically (no @types/node)
+    try {
+        const mod = 'node:' + 'crypto';
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+        const nodeCrypto = (await import(mod)).webcrypto;
+        if (nodeCrypto?.subtle) {
+            _resolvedCrypto = nodeCrypto;
+            return _resolvedCrypto;
+        }
+    }
+    catch { /* not in Node */ }
+    throw new Error('CursorCodec requires the Web Crypto API. ' +
+        'Ensure globalThis.crypto.subtle is available or use Node >= 16.');
+}
+function base64UrlEncode(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+}
+function base64UrlDecode(base64) {
+    const s = base64.replace(/-/g, '+').replace(/_/g, '/');
+    const b = atob(s);
+    const bytes = new Uint8Array(b.length);
+    for (let i = 0; i < b.length; i++) {
+        bytes[i] = b.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Stateless Cryptographic Cursor for pagination using Web Crypto API.
+ *
+ * Works in Node >= 16, Deno, Bun, and Cloudflare Workers.
+ */
+export class CursorCodec {
+    _mode;
+    _secretBytes;
+    _secretPromise;
+    _providedSecret;
+    _hmacKey;
+    _aesKey;
+    constructor(options) {
+        this._mode = options?.mode ?? 'signed';
+        this._providedSecret = options?.secret;
+        if (options?.secret) {
+            const encoder = new TextEncoder();
+            const buf = encoder.encode(options.secret);
+            if (buf.length !== 32) {
+                throw new Error('CursorCodec secret must be exactly 32 bytes (256 bits)');
+            }
+            this._secretBytes = buf;
+        }
+        // When no secret provided, _secretBytes is deferred to first use (async)
+    }
+    async ensureSecret() {
+        if (this._secretBytes)
+            return this._secretBytes;
+        if (!this._secretPromise) {
+            this._secretPromise = (async () => {
+                const crypto = await getCrypto();
+                this._secretBytes = crypto.getRandomValues(new Uint8Array(32));
+                return this._secretBytes;
+            })();
+        }
+        return this._secretPromise;
+    }
+    async getHmacKey() {
+        if (!this._hmacKey) {
+            const secret = await this.ensureSecret();
+            const crypto = await getCrypto();
+            this._hmacKey = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+        }
+        return this._hmacKey;
+    }
+    async getAesKey() {
+        if (!this._aesKey) {
+            const secret = await this.ensureSecret();
+            const crypto = await getCrypto();
+            this._aesKey = await crypto.subtle.importKey('raw', secret, 'AES-GCM', false, ['encrypt', 'decrypt']);
+        }
+        return this._aesKey;
+    }
+    /**
+     * Asynchronously encodes a payload into a URL-safe cursor string.
+     */
+    async encode(payload) {
+        const data = JSON.stringify(payload);
+        const dataBuffer = new TextEncoder().encode(data);
+        if (this._mode === 'encrypted') {
+            const aesKey = await this.getAesKey();
+            const crypto = await getCrypto();
+            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const encryptedBuf = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, aesKey, dataBuffer);
+            // Web Crypto AES-GCM appends the 16-byte auth tag at the end of the ciphertext
+            return `${base64UrlEncode(iv)}.${base64UrlEncode(encryptedBuf)}`;
+        }
+        else {
+            // Signed HMAC
+            const hmacKey = await this.getHmacKey();
+            const cryptoApi = await getCrypto();
+            const signatureBuf = await cryptoApi.subtle.sign('HMAC', hmacKey, dataBuffer);
+            return `${base64UrlEncode(dataBuffer)}.${base64UrlEncode(signatureBuf)}`;
+        }
+    }
+    /**
+     * Asynchronously decodes and verifies a cursor string back into its payload.
+     * Returns undefined if the cursor is invalid, tampered with, or from a different process/key.
+     */
+    async decode(cursor) {
+        try {
+            if (this._mode === 'encrypted') {
+                const parts = cursor.split('.');
+                if (parts.length !== 2)
+                    return undefined;
+                const [ivStr, encryptedStr] = parts;
+                if (!ivStr || !encryptedStr)
+                    return undefined;
+                const iv = base64UrlDecode(ivStr);
+                const encrypted = base64UrlDecode(encryptedStr);
+                const aesKey = await this.getAesKey();
+                const cryptoApi = await getCrypto();
+                const decryptedBuf = await cryptoApi.subtle.decrypt({ name: 'AES-GCM', iv: iv }, aesKey, encrypted);
+                const decrypted = new TextDecoder().decode(decryptedBuf);
+                return JSON.parse(decrypted);
+            }
+            else {
+                // Signed HMAC
+                const parts = cursor.split('.');
+                if (parts.length !== 2)
+                    return undefined;
+                const [dataB64, signatureB64] = parts;
+                if (!dataB64 || !signatureB64)
+                    return undefined;
+                const dataBuffer = base64UrlDecode(dataB64);
+                const signatureBuf = base64UrlDecode(signatureB64);
+                const hmacKey = await this.getHmacKey();
+                const cryptoApi2 = await getCrypto();
+                const isValid = await cryptoApi2.subtle.verify('HMAC', hmacKey, signatureBuf, dataBuffer);
+                if (!isValid)
+                    return undefined;
+                const decrypted = new TextDecoder().decode(dataBuffer);
+                return JSON.parse(decrypted);
+            }
+        }
+        catch {
+            // Catches Crypto errors (tampering), JSON parsing errors, Base64 errors
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=CursorCodec.js.map

package/dist/prompt/CursorCodec.js.map

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

package/dist/prompt/FluentPromptBuilder.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { type ZodObject, type ZodRawShape } from 'zod';
+import { type PromptBuilder, type PromptResult, type PromptParamsMap, type LoopbackContext } from './types.js';
+import { type MiddlewareFn } from '../core/types.js';
+/**
+ * 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 declare class FluentPromptBuilder<TContext = void, TArgs extends Record<string, unknown> = Record<string, unknown>> implements PromptBuilder<TContext> {
+    private readonly _name;
+    private _title?;
+    private _description?;
+    private _icons?;
+    private _tags;
+    private _middlewares;
+    private _args?;
+    private _hydrationTimeout?;
+    private _handler?;
+    /** @internal Cached delegate built on first access to PromptBuilder methods */
+    private _delegate;
+    constructor(name: string);
+    /**
+     * Set a human-readable title for UI display.
+     *
+     * @param title - The prompt title
+     * @returns `this` for chaining
+     */
+    title(title: string): this;
+    /**
+     * Set the prompt description shown in the slash command palette.
+     *
+     * @param description - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(description: string): this;
+    /**
+     * Set icons for light/dark themes.
+     *
+     * @param icons - Icon paths for light and/or dark themes
+     * @returns `this` for chaining
+     */
+    icons(icons: {
+        light?: string;
+        dark?: string;
+    }): this;
+    /**
+     * Set capability tags for selective exposure.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags: string[]): this;
+    /**
+     * Define the input schema for prompt arguments.
+     *
+     * Accepts the same formats as `FluentToolBuilder.input()`:
+     * - Fluent param descriptors (`f.string()`, `f.number()`, etc.) — zero imports
+     * - Zod schema for power users
+     *
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * // Fluent descriptors (recommended — zero Zod imports)
+     * f.prompt('greet')
+     *     .input({ name: f.string(), age: f.number().optional() })
+     *     .handler(async (ctx, { name, age }) => ({ ... }));
+     *
+     * // Zod schema (advanced)
+     * f.prompt('search')
+     *     .input(z.object({ query: z.string().min(1) }))
+     *     .handler(async (ctx, { query }) => ({ ... }));
+     * ```
+     */
+    input<S extends ZodRawShape>(schema: ZodObject<S>): FluentPromptBuilder<TContext, ZodObject<S>['_output']>;
+    input(params: PromptParamsMap): 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: MiddlewareFn<TContext>[]): 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: number): 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: (ctx: TContext & LoopbackContext, args: TArgs) => Promise<PromptResult>): this;
+    /** @internal Build the underlying PromptBuilder delegate lazily */
+    private _build;
+    getName(): string;
+    getDescription(): string | undefined;
+    getTags(): string[];
+    hasMiddleware(): boolean;
+    getHydrationTimeout(): number | undefined;
+    buildPromptDefinition(): {
+        name: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    };
+    execute(ctx: TContext, args: Record<string, string>): Promise<PromptResult>;
+}
+//# sourceMappingURL=FluentPromptBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FluentPromptBuilder.d.ts","sourceRoot":"","sources":["../../src/prompt/FluentPromptBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,EACH,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOrD;;;;;;;;;GASG;AACH,qBAAa,mBAAmB,CAAC,QAAQ,GAAG,IAAI,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC7G,YAAW,aAAa,CAAC,QAAQ,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAC,CAAoC;IACnD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,KAAK,CAAC,CAA2C;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,CAA0E;IAE3F,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAsC;gBAE3C,IAAI,EAAE,MAAM;IAMxB;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMnC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMrD;;;;;OAKG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1G,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAQpC;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,GAAG,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI;IAM3C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAQ1F,mEAAmE;IACnE,OAAO,CAAC,MAAM;IAuBd,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,OAAO,IAAI,MAAM,EAAE;IAInB,aAAa,IAAI,OAAO;IAIxB,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAIzC,qBAAqB;;;;;uBAQihK,CAAC;oBAA+B,CAAC;;;IAJvkK,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;CAG9E"}