@vurb/core 3.2.0

package/dist/presenter/ZodDescriptionExtractor.js

@@ -0,0 +1,131 @@
+/**
+ * ZodDescriptionExtractor — Automatic Prompt Extraction from Zod .describe()
+ *
+ * Walks a Zod schema's AST and collects `.describe()` annotations from
+ * every field. These descriptions are injected as system rules via
+ * Context Tree-Shaking, eliminating the need for manual `systemRules`
+ * when the Zod schema already carries domain-specific constraints.
+ *
+ * This ensures documentation never drifts from the actual data shape:
+ * the single source of truth is the Zod `.describe()` annotation.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *   status: z.enum(['paid', 'pending']).describe('Always display with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: in CENTS. Divide by 100.',
+ * //    'status: Always display with emoji']
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+// ── Extraction Logic ─────────────────────────────────────
+/**
+ * Recursively unwrap wrapper Zod nodes (optional, nullable, default, branded,
+ * readonly, effects, lazy, catches, pipes) to reach the inner schema.
+ * @internal
+ */
+function unwrap(node) {
+    const def = node._def;
+    if (!def)
+        return node;
+    const typeName = def.typeName ?? '';
+    const wrapperTypes = [
+        'ZodOptional', 'ZodNullable', 'ZodDefault', 'ZodBranded',
+        'ZodReadonly', 'ZodEffects', 'ZodLazy', 'ZodCatch', 'ZodPipeline',
+    ];
+    if (wrapperTypes.includes(typeName)) {
+        const inner = def.innerType ?? def.type ?? def.schema ?? def['in'];
+        if (inner)
+            return unwrap(inner);
+    }
+    return node;
+}
+/**
+ * Get the shape record from a Zod object node.
+ * Supports both v3 (`_def.shape()`) and v4 (`_def.shape`) patterns.
+ * @internal
+ */
+function getShape(node) {
+    const def = node._def;
+    if (!def)
+        return undefined;
+    if (typeof def.shape === 'function') {
+        return def.shape();
+    }
+    if (typeof def.shape === 'object' && def.shape !== null) {
+        return def.shape;
+    }
+    return undefined;
+}
+/**
+ * Extract `.describe()` annotations from a Zod schema's fields.
+ *
+ * Walks the top-level `z.object()` shape and retrieves the description
+ * string from each field (after unwrapping wrappers like `z.optional()`,
+ * `z.nullable()`, `z.default()`, etc.).
+ *
+ * Returns an array of human-readable `"fieldName: description"` strings,
+ * ready to be injected as system rules.
+ *
+ * @param schema - A Zod schema (typically z.object, but safely handles non-objects)
+ * @returns Array of `"fieldName: description"` strings (empty if no descriptions found)
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: value is in CENTS. Divide by 100.'),
+ *   currency: z.string(), // No .describe() → skipped
+ *   status: z.enum(['paid', 'pending']).describe('Show with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: value is in CENTS. Divide by 100.',
+ * //    'status: Show with emoji']
+ * ```
+ */
+export function extractZodDescriptions(schema) {
+    const node = schema;
+    const shape = getShape(node);
+    if (!shape)
+        return [];
+    const descriptions = [];
+    for (const [key, fieldNode] of Object.entries(shape)) {
+        const desc = resolveDescription(fieldNode);
+        if (desc) {
+            descriptions.push(`${key}: ${desc}`);
+        }
+    }
+    return descriptions;
+}
+/**
+ * Resolve the description from a field node by unwrapping wrappers.
+ *
+ * Priority:
+ * 1. Outermost `.description` (Zod v4 style)
+ * 2. `_def.description` (Zod v3 style)
+ * 3. Unwrapped inner node's description
+ * @internal
+ */
+function resolveDescription(node) {
+    // Check outermost description first
+    if (node.description)
+        return node.description;
+    if (node._def?.description)
+        return node._def.description;
+    // Unwrap and check inner
+    const inner = unwrap(node);
+    if (inner !== node) {
+        if (inner.description)
+            return inner.description;
+        if (inner._def?.description)
+            return inner._def.description;
+    }
+    return undefined;
+}
+//# sourceMappingURL=ZodDescriptionExtractor.js.map

package/dist/presenter/ZodDescriptionExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZodDescriptionExtractor.js","sourceRoot":"","sources":["../../src/presenter/ZodDescriptionExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAgB,MAAM,KAAK,CAAC;AAwBnC,4DAA4D;AAE5D;;;;GAIG;AACH,SAAS,MAAM,CAAC,IAAa;IACzB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;IACtB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,MAAM,YAAY,GAAG;QACjB,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY;QACxD,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa;KACpE,CAAC;IAEF,IAAI,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,IAAK,GAA+B,CAAC,IAAI,CAAC,CAAC;QAChG,IAAI,KAAK;YAAE,OAAO,MAAM,CAAC,KAAgB,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAa;IAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;IACtB,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,GAAG,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAe;IAClD,MAAM,IAAI,GAAG,MAA4B,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,IAAI,EAAE,CAAC;YACP,YAAY,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACL,CAAC;IAED,OAAO,YAAY,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,IAAa;IACrC,oCAAoC;IACpC,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAC9C,IAAI,IAAI,CAAC,IAAI,EAAE,WAAW;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;IAEzD,yBAAyB;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjB,IAAI,KAAK,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC,WAAW,CAAC;QAChD,IAAI,KAAK,CAAC,IAAI,EAAE,WAAW;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;IAC/D,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/presenter/definePresenter.d.ts

@@ -0,0 +1,193 @@
+/**
+ * definePresenter() — Declarative Presenter Definition
+ *
+ * Zero-friction object-config API for creating Presenters.
+ * Replaces the fluent builder pattern with a single object literal
+ * that enables instant Ctrl+Space autocomplete and zero generic noise.
+ *
+ * The `schema` field drives type inference: the `ui`, `rules`, and
+ * `suggestActions` callbacks automatically receive the inferred type,
+ * so the developer never writes a generic parameter manually.
+ *
+ * @example
+ * ```typescript
+ * import { definePresenter, ui } from 'vurb';
+ * import { z } from 'zod';
+ *
+ * export const InvoicePresenter = definePresenter({
+ *   name: 'Invoice',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *     status: z.enum(['paid', 'pending']),
+ *   }),
+ *   rules: ['CRITICAL: Divide amount_cents by 100 before displaying.'],
+ *   ui: (inv) => [ui.echarts({ series: [{ type: 'gauge', data: [{ value: inv.amount_cents / 100 }] }] })],
+ *   suggestActions: (inv) =>
+ *     inv.status === 'pending'
+ *       ? [{ tool: 'billing.pay', reason: 'Offer immediate payment' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @module
+ */
+import { type ZodType } from 'zod';
+import { Presenter, type ActionSuggestion } from './Presenter.js';
+import { type UiBlock } from './ui.js';
+/**
+ * Agent limit configuration for cognitive guardrails.
+ */
+export interface AgentLimitDef {
+    /** Maximum items to keep when data is an array */
+    readonly max: number;
+    /** Callback that produces a warning block when items are truncated */
+    readonly onTruncate: (omittedCount: number) => UiBlock;
+}
+/**
+ * Embedded child Presenter definition for relational composition.
+ */
+export interface EmbedDef {
+    /** Property key in the parent data that contains the nested data */
+    readonly key: string;
+    /** The child Presenter to apply to the nested data */
+    readonly presenter: Presenter<unknown>;
+}
+/**
+ * Full declarative configuration for `definePresenter()`.
+ *
+ * @typeParam T - Inferred from the `schema` field's output type
+ */
+export interface PresenterConfig<T> {
+    /** Human-readable domain name (for debugging and introspection) */
+    readonly name: string;
+    /** Zod schema for data validation and field filtering */
+    readonly schema?: ZodType<any, any, any>;
+    /**
+     * System rules that travel with the data.
+     *
+     * - **Static**: `string[]` — always injected
+     * - **Dynamic**: `(data, ctx?) => (string | null)[]` — context-aware (RBAC, DLP, locale)
+     *
+     * Return `null` from dynamic rules to conditionally exclude them.
+     */
+    readonly rules?: readonly string[] | ((data: T, ctx?: unknown) => (string | null)[]);
+    /**
+     * UI blocks for a **single data item**.
+     *
+     * Return `null` for conditional blocks (filtered automatically).
+     */
+    readonly ui?: (item: T, ctx?: unknown) => (UiBlock | null)[];
+    /**
+     * Aggregated UI blocks for a **collection** (array) of items.
+     *
+     * Called once with the entire validated array. Prevents N individual
+     * charts from flooding the LLM's context.
+     */
+    readonly collectionUi?: (items: T[], ctx?: unknown) => (UiBlock | null)[];
+    /**
+     * Cognitive guardrail that truncates large collections.
+     *
+     * Protects against context DDoS by limiting returned array length
+     * and injecting a summary block.
+     */
+    readonly agentLimit?: AgentLimitDef;
+    /**
+     * HATEOAS-style next-action suggestions based on data state.
+     *
+     * Eliminates routing hallucinations by providing explicit next-step hints.
+     */
+    readonly suggestActions?: (data: T, ctx?: unknown) => ActionSuggestion[];
+    /**
+     * Embedded child Presenters for nested relational data.
+     *
+     * Define once, embed everywhere. Each embed's `key` is looked up on
+     * the parent data, and the child Presenter renders its own blocks/rules.
+     */
+    readonly embeds?: readonly EmbedDef[];
+    /**
+     * Automatically extract `.describe()` annotations from the Zod schema
+     * and merge them with `rules` as system rules.
+     *
+     * When `true` (the default), field-level `.describe()` annotations
+     * become system rules, ensuring documentation never drifts from the
+     * actual data shape. Set to `false` to opt out.
+     *
+     * @default true
+     */
+    readonly autoRules?: boolean;
+    /**
+     * PII redaction paths for DLP compliance.
+     *
+     * Compiles object paths into V8-optimized masking functions
+     * using `fast-redact`. Masked data reaches the LLM, while
+     * UI blocks and system rules see the full unmasked data.
+     *
+     * Requires `fast-redact` as an optional peer dependency.
+     *
+     * @example
+     * ```typescript
+     * redactPII: {
+     *     paths: ['*.ssn', 'credit_card.number', 'patients[*].diagnosis'],
+     *     censor: '[REDACTED]',
+     * }
+     * ```
+     */
+    readonly redactPII?: {
+        readonly paths: string[];
+        readonly censor?: string | ((value: unknown) => string);
+    };
+}
+/**
+ * Define a domain-level Presenter using a declarative config object.
+ *
+ * This is the recommended, zero-friction API. The `schema` field drives
+ * full type inference — `ui`, `rules`, and `suggestActions` callbacks
+ * all receive correctly-typed parameters without any explicit generics.
+ *
+ * @typeParam TSchema - Zod type (inferred from the `schema` field)
+ * @param config - Declarative presenter configuration
+ * @returns A fully-configured {@link Presenter} ready for use
+ *
+ * @example
+ * ```typescript
+ * // Minimal
+ * const TaskPresenter = definePresenter({
+ *   name: 'Task',
+ *   schema: z.object({ id: z.string(), title: z.string(), done: z.boolean() }),
+ *   rules: ['Use ✅ for done, 🔄 for in-progress.'],
+ *   ui: (task) => [ui.markdown(`**${task.title}**: ${task.done ? '✅' : '🔄'}`)],
+ * });
+ *
+ * // With embeds, agent limit, and dynamic rules
+ * const OrderPresenter = definePresenter({
+ *   name: 'Order',
+ *   schema: orderSchema,
+ *   rules: (order, ctx) => [
+ *     ctx?.locale === 'pt-BR' ? 'Formate datas em DD/MM/YYYY' : null,
+ *   ],
+ *   agentLimit: { max: 100, onTruncate: (n) => ui.summary(`⚠️ ${n} orders hidden`) },
+ *   embeds: [{ key: 'customer', presenter: CustomerPresenter }],
+ *   suggestActions: (order) =>
+ *     order.status === 'pending'
+ *       ? [{ tool: 'orders.approve', reason: 'Ready for approval' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @see {@link createPresenter} for the legacy fluent builder API
+ * @see {@link Presenter} for the full Presenter class documentation
+ */
+export declare function definePresenter<TSchema extends ZodType<any, any, any>>(config: Omit<PresenterConfig<TSchema['_output']>, 'schema'> & {
+    schema: TSchema;
+}): Presenter<TSchema['_output']>;
+/**
+ * Define a Presenter without a schema (untyped data passthrough).
+ *
+ * @param config - Configuration without a schema field
+ * @returns A Presenter that passes data through without validation
+ */
+export declare function definePresenter(config: PresenterConfig<unknown> & {
+    schema?: undefined;
+}): Presenter<unknown>;
+//# sourceMappingURL=definePresenter.d.ts.map

package/dist/presenter/definePresenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePresenter.d.ts","sourceRoot":"","sources":["../../src/presenter/definePresenter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACrB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IAErF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAE7D;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,gBAAgB,EAAE,CAAC;IAEzE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAEtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;KAC3D,CAAC;CACL;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAClE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAClF,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1D,SAAS,CAAC,OAAO,CAAC,CAAC"}

package/dist/presenter/definePresenter.js

@@ -0,0 +1,99 @@
+/**
+ * definePresenter() — Declarative Presenter Definition
+ *
+ * Zero-friction object-config API for creating Presenters.
+ * Replaces the fluent builder pattern with a single object literal
+ * that enables instant Ctrl+Space autocomplete and zero generic noise.
+ *
+ * The `schema` field drives type inference: the `ui`, `rules`, and
+ * `suggestActions` callbacks automatically receive the inferred type,
+ * so the developer never writes a generic parameter manually.
+ *
+ * @example
+ * ```typescript
+ * import { definePresenter, ui } from 'vurb';
+ * import { z } from 'zod';
+ *
+ * export const InvoicePresenter = definePresenter({
+ *   name: 'Invoice',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *     status: z.enum(['paid', 'pending']),
+ *   }),
+ *   rules: ['CRITICAL: Divide amount_cents by 100 before displaying.'],
+ *   ui: (inv) => [ui.echarts({ series: [{ type: 'gauge', data: [{ value: inv.amount_cents / 100 }] }] })],
+ *   suggestActions: (inv) =>
+ *     inv.status === 'pending'
+ *       ? [{ tool: 'billing.pay', reason: 'Offer immediate payment' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import { Presenter } from './Presenter.js';
+import {} from './ui.js';
+import { extractZodDescriptions } from './ZodDescriptionExtractor.js';
+/**
+ * Implementation
+ * @internal
+ */
+export function definePresenter(config) {
+    const presenter = new Presenter(config.name);
+    if (config.schema) {
+        presenter.schema(config.schema);
+    }
+    // ── Zod-Driven Prompts: auto-extract .describe() annotations ──
+    const autoRules = config.autoRules !== false; // default: true
+    const zodDescriptions = (autoRules && config.schema)
+        ? extractZodDescriptions(config.schema)
+        : [];
+    if (config.rules) {
+        if (typeof config.rules === 'function') {
+            // Dynamic rules — wrap to prepend Zod descriptions
+            if (zodDescriptions.length > 0) {
+                const dynamicFn = config.rules;
+                presenter.systemRules((data, ctx) => [
+                    ...zodDescriptions,
+                    ...dynamicFn(data, ctx),
+                ]);
+            }
+            else {
+                presenter.systemRules(config.rules);
+            }
+        }
+        else {
+            // Static rules — merge with Zod descriptions
+            const merged = [...zodDescriptions, ...config.rules];
+            presenter.systemRules(merged);
+        }
+    }
+    else if (zodDescriptions.length > 0) {
+        // No explicit rules — use Zod descriptions alone
+        presenter.systemRules(zodDescriptions);
+    }
+    if (config.ui) {
+        presenter.uiBlocks(config.ui);
+    }
+    if (config.collectionUi) {
+        presenter.collectionUiBlocks(config.collectionUi);
+    }
+    if (config.agentLimit) {
+        presenter.agentLimit(config.agentLimit.max, config.agentLimit.onTruncate);
+    }
+    if (config.suggestActions) {
+        presenter.suggestActions(config.suggestActions);
+    }
+    if (config.embeds) {
+        for (const embed of config.embeds) {
+            presenter.embed(embed.key, embed.presenter);
+        }
+    }
+    if (config.redactPII) {
+        presenter.redactPII(config.redactPII.paths, config.redactPII.censor);
+    }
+    return presenter;
+}
+//# sourceMappingURL=definePresenter.js.map

package/dist/presenter/definePresenter.js.map

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

package/dist/presenter/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Presenter Module — Barrel Export
+ *
+ * Public API for the MVA (Model-View-Agent) presenter system.
+ */
+export { ResponseBuilder, response, isResponseBuilder } from './ResponseBuilder.js';
+export type { ActionSuggestion } from './ResponseBuilder.js';
+export { ui } from './ui.js';
+export type { UiBlock } from './ui.js';
+export { Presenter, createPresenter, isPresenter } from './Presenter.js';
+export { definePresenter } from './definePresenter.js';
+export type { PresenterConfig, AgentLimitDef, EmbedDef } from './definePresenter.js';
+export { extractZodDescriptions } from './ZodDescriptionExtractor.js';
+export { PresenterValidationError } from './PresenterValidationError.js';
+export { t } from './typeHelpers.js';
+export { suggest } from './suggest.js';
+export { postProcessResult, isToolResponse } from './PostProcessor.js';
+export { extractZodKeys, pickFields, applySelectFilter } from './SelectUtils.js';
+export { compileRedactor, initRedactEngine } from './RedactEngine.js';
+export type { RedactConfig, RedactFn } from './RedactEngine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/presenter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAGrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGvE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/presenter/index.js

@@ -0,0 +1,28 @@
+/**
+ * Presenter Module — Barrel Export
+ *
+ * Public API for the MVA (Model-View-Agent) presenter system.
+ */
+// ── Response Builder ─────────────────────────────────────
+export { ResponseBuilder, response, isResponseBuilder } from './ResponseBuilder.js';
+// ── UI Helpers ───────────────────────────────────────────
+export { ui } from './ui.js';
+// ── Presenter ────────────────────────────────────────────
+export { Presenter, createPresenter, isPresenter } from './Presenter.js';
+// ── Declarative Presenter ────────────────────────────────
+export { definePresenter } from './definePresenter.js';
+// ── Zod Description Extraction ───────────────────────────
+export { extractZodDescriptions } from './ZodDescriptionExtractor.js';
+// ── Validation Error ─────────────────────────────────────
+export { PresenterValidationError } from './PresenterValidationError.js';
+// ── Type Helpers (Fluent Schema Namespace) ───────────────
+export { t } from './typeHelpers.js';
+// ── Action Suggestion Helper ─────────────────────────────
+export { suggest } from './suggest.js';
+// ── Post-Processing ──────────────────────────────────────
+export { postProcessResult, isToolResponse } from './PostProcessor.js';
+// ── Select Reflection (Context Window Optimization) ──────
+export { extractZodKeys, pickFields, applySelectFilter } from './SelectUtils.js';
+// ── DLP Compliance (PII Redaction) ───────────────────────
+export { compileRedactor, initRedactEngine } from './RedactEngine.js';
+//# sourceMappingURL=index.js.map

package/dist/presenter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGpF,4DAA4D;AAC5D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,4DAA4D;AAC5D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,4DAA4D;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,4DAA4D;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAErC,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE,4DAA4D;AAC5D,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEjF,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/presenter/suggest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * suggest() — Fluent Action Suggestion Helper
+ *
+ * Replaces `{ tool: '...', reason: '...' }` config objects with a
+ * clean function call that reads like English.
+ *
+ * @example
+ * ```typescript
+ * import { suggest } from 'vurb';
+ *
+ * .suggest((invoice) => [
+ *     suggest('invoices.get', 'View invoice details'),
+ *     invoice.status === 'overdue'
+ *         ? suggest('billing.remind', 'Send collection reminder')
+ *         : null,
+ * ])
+ * ```
+ *
+ * @module
+ */
+import { type ActionSuggestion } from './Presenter.js';
+/**
+ * Create an action suggestion for HATEOAS-style agent guidance.
+ *
+ * Fluent alternative to `{ tool: '...', reason: '...' }` config objects.
+ * Reads like `suggest(what, why)` — zero ceremony.
+ *
+ * @param tool - Tool name to suggest (e.g. `'billing.pay'`)
+ * @param reason - Human-readable reason for the suggestion
+ * @returns An {@link ActionSuggestion} object
+ *
+ * @example
+ * ```typescript
+ * suggest('projects.archive', 'Archive this inactive project')
+ * // → { tool: 'projects.archive', reason: 'Archive this inactive project' }
+ * ```
+ */
+export declare function suggest(tool: string, reason: string): ActionSuggestion;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/presenter/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/presenter/suggest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAEtE"}

package/dist/presenter/suggest.js

@@ -0,0 +1,41 @@
+/**
+ * suggest() — Fluent Action Suggestion Helper
+ *
+ * Replaces `{ tool: '...', reason: '...' }` config objects with a
+ * clean function call that reads like English.
+ *
+ * @example
+ * ```typescript
+ * import { suggest } from 'vurb';
+ *
+ * .suggest((invoice) => [
+ *     suggest('invoices.get', 'View invoice details'),
+ *     invoice.status === 'overdue'
+ *         ? suggest('billing.remind', 'Send collection reminder')
+ *         : null,
+ * ])
+ * ```
+ *
+ * @module
+ */
+import {} from './Presenter.js';
+/**
+ * Create an action suggestion for HATEOAS-style agent guidance.
+ *
+ * Fluent alternative to `{ tool: '...', reason: '...' }` config objects.
+ * Reads like `suggest(what, why)` — zero ceremony.
+ *
+ * @param tool - Tool name to suggest (e.g. `'billing.pay'`)
+ * @param reason - Human-readable reason for the suggestion
+ * @returns An {@link ActionSuggestion} object
+ *
+ * @example
+ * ```typescript
+ * suggest('projects.archive', 'Archive this inactive project')
+ * // → { tool: 'projects.archive', reason: 'Archive this inactive project' }
+ * ```
+ */
+export function suggest(tool, reason) {
+    return { tool, reason };
+}
+//# sourceMappingURL=suggest.js.map

package/dist/presenter/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/presenter/suggest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAyB,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,MAAc;IAChD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}