@vurb/core 3.2.0

package/dist/prompt/PromptMessage.d.ts

@@ -0,0 +1,133 @@
+/**
+ * PromptMessage — Factory Helpers for Prompt Messages
+ *
+ * Provides ergonomic factory methods for creating `PromptMessagePayload`
+ * objects used in `PromptResult.messages`.
+ *
+ * These helpers encode the MCP wire format so developers never deal
+ * with `{ role: 'user', content: { type: 'text', text: '...' } }`
+ * manually.
+ *
+ * @example
+ * ```typescript
+ * import { PromptMessage } from 'vurb';
+ *
+ * return {
+ *     messages: [
+ *         PromptMessage.system('You are a Senior Auditor.'),
+ *         PromptMessage.user('Begin the audit.'),
+ *         PromptMessage.assistant('Analyzing invoices...'),
+ *     ],
+ * };
+ * ```
+ *
+ * @module
+ */
+import { type PromptMessagePayload } from './types.js';
+import { type ResponseBuilder } from '../presenter/ResponseBuilder.js';
+/**
+ * Factory for creating MCP prompt messages.
+ *
+ * **Note on `system()`:** The MCP protocol only supports `user` and
+ * `assistant` roles in `PromptMessage`. System instructions are encoded
+ * as a `user` message (the first message) by convention — the MCP client
+ * prepends it to the conversation context.
+ */
+export declare const PromptMessage: {
+    /**
+     * Create a system instruction message.
+     *
+     * Encoded as `role: 'user'` per MCP spec (MCP does not have
+     * a `system` role in PromptMessage — system instructions are
+     * conveyed as the first `user` message by convention).
+     *
+     * @param text - System instruction text
+     */
+    readonly system: (text: string) => PromptMessagePayload;
+    /**
+     * Create a user message.
+     *
+     * @param text - User message text
+     */
+    readonly user: (text: string) => PromptMessagePayload;
+    /**
+     * Create an assistant message (for multi-turn seeding).
+     *
+     * Use this to pre-seed the assistant's initial response,
+     * guiding the LLM's first reasoning step.
+     *
+     * @param text - Assistant message text
+     */
+    readonly assistant: (text: string) => PromptMessagePayload;
+    /**
+     * Create a message with an embedded image.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param data - Base64-encoded image data
+     * @param mimeType - MIME type (e.g., 'image/png', 'image/jpeg')
+     */
+    readonly image: (role: "user" | "assistant", data: string, mimeType: string) => PromptMessagePayload;
+    /**
+     * Create a message with embedded audio.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param data - Base64-encoded audio data
+     * @param mimeType - MIME type (e.g., 'audio/wav', 'audio/mp3')
+     */
+    readonly audio: (role: "user" | "assistant", data: string, mimeType: string) => PromptMessagePayload;
+    /**
+     * Create a message with an embedded resource reference.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param uri - Resource URI
+     * @param options - Optional mime type, text, or blob data
+     */
+    readonly resource: (role: "user" | "assistant", uri: string, options?: {
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    }) => PromptMessagePayload;
+    /**
+     * Decompose a Presenter view into prompt messages.
+     *
+     * MVA-Driven Prompts — the bridge between the Presenter layer
+     * (MVA View for Tools) and the Prompt Engine. Extracts system rules,
+     * data, UI blocks, and action suggestions from a `ResponseBuilder`
+     * into composable `PromptMessagePayload[]` messages.
+     *
+     * Uses XML-tagged semantic blocks (`<domain_rules>`, `<dataset>`,
+     * `<visual_context>`, `<system_guidance>`) optimized for frontier
+     * LLM context handling — prevents context leakage between layers.
+     *
+     * **Single Source of Truth**: If a Presenter's `systemRules()` change,
+     * both Tools and Prompts update automatically — zero duplication.
+     *
+     * @param builder - A `ResponseBuilder` from `Presenter.make()` or `response()`
+     * @returns Array of prompt messages, ready to spread into `messages: [...]`
+     *
+     * @example
+     * ```typescript
+     * import { definePrompt, PromptMessage } from 'vurb';
+     * import { InvoicePresenter } from './presenters';
+     *
+     * const AuditPrompt = definePrompt<AppContext>('audit', {
+     *     args: { invoiceId: 'string' } as const,
+     *     handler: async (ctx, { invoiceId }) => {
+     *         const invoice = await ctx.db.getInvoice(invoiceId);
+     *         return {
+     *             messages: [
+     *                 PromptMessage.system('You are a Senior Financial Auditor.'),
+     *                 ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+     *                 PromptMessage.user('Begin the audit for this invoice.'),
+     *             ],
+     *         };
+     *     },
+     * });
+     * ```
+     *
+     * @see {@link Presenter} for the MVA View layer
+     * @see {@link ResponseBuilder} for the data source
+     */
+    readonly fromView: (builder: ResponseBuilder) => PromptMessagePayload[];
+};
+//# sourceMappingURL=PromptMessage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PromptMessage.d.ts","sourceRoot":"","sources":["../../src/prompt/PromptMessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACtB;;;;;;;;OAQG;4BACU,MAAM,KAAG,oBAAoB;IAI1C;;;;OAIG;0BACQ,MAAM,KAAG,oBAAoB;IAIxC;;;;;;;OAOG;+BACa,MAAM,KAAG,oBAAoB;IAI7C;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;8BAEO,MAAM,GAAG,WAAW,OACrB,MAAM,YACD;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9D,oBAAoB;IAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;iCACe,eAAe,KAAG,oBAAoB,EAAE;CA4CpD,CAAC"}

package/dist/prompt/PromptMessage.js

@@ -0,0 +1,182 @@
+/**
+ * PromptMessage — Factory Helpers for Prompt Messages
+ *
+ * Provides ergonomic factory methods for creating `PromptMessagePayload`
+ * objects used in `PromptResult.messages`.
+ *
+ * These helpers encode the MCP wire format so developers never deal
+ * with `{ role: 'user', content: { type: 'text', text: '...' } }`
+ * manually.
+ *
+ * @example
+ * ```typescript
+ * import { PromptMessage } from 'vurb';
+ *
+ * return {
+ *     messages: [
+ *         PromptMessage.system('You are a Senior Auditor.'),
+ *         PromptMessage.user('Begin the audit.'),
+ *         PromptMessage.assistant('Analyzing invoices...'),
+ *     ],
+ * };
+ * ```
+ *
+ * @module
+ */
+import {} from './types.js';
+import {} from '../presenter/ResponseBuilder.js';
+/**
+ * Factory for creating MCP prompt messages.
+ *
+ * **Note on `system()`:** The MCP protocol only supports `user` and
+ * `assistant` roles in `PromptMessage`. System instructions are encoded
+ * as a `user` message (the first message) by convention — the MCP client
+ * prepends it to the conversation context.
+ */
+export const PromptMessage = {
+    /**
+     * Create a system instruction message.
+     *
+     * Encoded as `role: 'user'` per MCP spec (MCP does not have
+     * a `system` role in PromptMessage — system instructions are
+     * conveyed as the first `user` message by convention).
+     *
+     * @param text - System instruction text
+     */
+    system(text) {
+        return { role: 'user', content: { type: 'text', text } };
+    },
+    /**
+     * Create a user message.
+     *
+     * @param text - User message text
+     */
+    user(text) {
+        return { role: 'user', content: { type: 'text', text } };
+    },
+    /**
+     * Create an assistant message (for multi-turn seeding).
+     *
+     * Use this to pre-seed the assistant's initial response,
+     * guiding the LLM's first reasoning step.
+     *
+     * @param text - Assistant message text
+     */
+    assistant(text) {
+        return { role: 'assistant', content: { type: 'text', text } };
+    },
+    /**
+     * Create a message with an embedded image.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param data - Base64-encoded image data
+     * @param mimeType - MIME type (e.g., 'image/png', 'image/jpeg')
+     */
+    image(role, data, mimeType) {
+        return { role, content: { type: 'image', data, mimeType } };
+    },
+    /**
+     * Create a message with embedded audio.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param data - Base64-encoded audio data
+     * @param mimeType - MIME type (e.g., 'audio/wav', 'audio/mp3')
+     */
+    audio(role, data, mimeType) {
+        return { role, content: { type: 'audio', data, mimeType } };
+    },
+    /**
+     * Create a message with an embedded resource reference.
+     *
+     * @param role - Message role ('user' or 'assistant')
+     * @param uri - Resource URI
+     * @param options - Optional mime type, text, or blob data
+     */
+    resource(role, uri, options) {
+        return {
+            role,
+            content: {
+                type: 'resource',
+                resource: { uri, ...options },
+            },
+        };
+    },
+    /**
+     * Decompose a Presenter view into prompt messages.
+     *
+     * MVA-Driven Prompts — the bridge between the Presenter layer
+     * (MVA View for Tools) and the Prompt Engine. Extracts system rules,
+     * data, UI blocks, and action suggestions from a `ResponseBuilder`
+     * into composable `PromptMessagePayload[]` messages.
+     *
+     * Uses XML-tagged semantic blocks (`<domain_rules>`, `<dataset>`,
+     * `<visual_context>`, `<system_guidance>`) optimized for frontier
+     * LLM context handling — prevents context leakage between layers.
+     *
+     * **Single Source of Truth**: If a Presenter's `systemRules()` change,
+     * both Tools and Prompts update automatically — zero duplication.
+     *
+     * @param builder - A `ResponseBuilder` from `Presenter.make()` or `response()`
+     * @returns Array of prompt messages, ready to spread into `messages: [...]`
+     *
+     * @example
+     * ```typescript
+     * import { definePrompt, PromptMessage } from 'vurb';
+     * import { InvoicePresenter } from './presenters';
+     *
+     * const AuditPrompt = definePrompt<AppContext>('audit', {
+     *     args: { invoiceId: 'string' } as const,
+     *     handler: async (ctx, { invoiceId }) => {
+     *         const invoice = await ctx.db.getInvoice(invoiceId);
+     *         return {
+     *             messages: [
+     *                 PromptMessage.system('You are a Senior Financial Auditor.'),
+     *                 ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+     *                 PromptMessage.user('Begin the audit for this invoice.'),
+     *             ],
+     *         };
+     *     },
+     * });
+     * ```
+     *
+     * @see {@link Presenter} for the MVA View layer
+     * @see {@link ResponseBuilder} for the data source
+     */
+    fromView(builder) {
+        const messages = [];
+        // 1. RULES → SYSTEM ROLE (domain directives travel with the data)
+        const rules = builder.getRules();
+        if (rules.length > 0) {
+            messages.push(PromptMessage.system(`<domain_rules>\n${rules.map(r => `- ${r}`).join('\n')}\n</domain_rules>`));
+        }
+        // 2. DATA & UI BLOCKS → USER ROLE (context for the LLM)
+        const data = builder.getData();
+        const uiBlocks = builder.getUiBlocks();
+        let userContent = '';
+        if (data) {
+            userContent += `<dataset>\n\`\`\`json\n${data}\n\`\`\`\n</dataset>\n\n`;
+        }
+        if (uiBlocks.length > 0) {
+            userContent += `<visual_context>\n${uiBlocks.map(b => b.content).join('\n\n')}\n</visual_context>\n\n`;
+        }
+        if (userContent.trim()) {
+            messages.push(PromptMessage.user(userContent.trim()));
+        }
+        // 3. AFFORDANCES → SYSTEM ROLE (hints + HATEOAS suggestions)
+        const hints = builder.getHints();
+        const suggestions = builder.getSuggestions();
+        if (hints.length > 0 || suggestions.length > 0) {
+            let guidance = '<system_guidance>\n';
+            if (hints.length > 0) {
+                guidance += hints.map(h => `Hint: ${h}`).join('\n') + '\n';
+            }
+            if (suggestions.length > 0) {
+                guidance += `Suggested Next Actions: ${suggestions.map(s => `${s.tool} (${s.reason})`).join(', ')}\n`;
+            }
+            guidance += '</system_guidance>';
+            messages.push(PromptMessage.system(guidance));
+        }
+        return messages;
+    },
+};
+//# sourceMappingURL=PromptMessage.js.map

package/dist/prompt/PromptMessage.js.map

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

package/dist/prompt/PromptRegistry.d.ts

@@ -0,0 +1,236 @@
+/**
+ * PromptRegistry — Centralized Prompt Registration & Routing
+ *
+ * The single place where all prompt builders are registered and where
+ * incoming `prompts/list` and `prompts/get` requests are routed.
+ *
+ * Mirrors the design of {@link ToolRegistry} with prompt-specific features:
+ * - O(1) routing via Map lookup
+ * - Tag-based filtering for RBAC exposure
+ * - Lifecycle sync via `notifyChanged()` (→ `notifications/prompts/list_changed`)
+ *
+ * @example
+ * ```typescript
+ * import { PromptRegistry, definePrompt } from 'vurb';
+ *
+ * const promptRegistry = new PromptRegistry<AppContext>();
+ * promptRegistry.register(AuditPrompt);
+ * promptRegistry.register(OnboardingPrompt);
+ *
+ * // Attach alongside tools:
+ * attachToServer(server, {
+ *     tools: toolRegistry,
+ *     prompts: promptRegistry,
+ *     contextFactory: createContext,
+ * });
+ *
+ * // Lifecycle sync (e.g., after RBAC change):
+ * promptRegistry.notifyChanged();
+ * ```
+ *
+ * @see {@link definePrompt} for creating prompt builders
+ * @see {@link PromptBuilder} for the builder contract
+ *
+ * @module
+ */
+import { type PromptBuilder, type PromptResult, type PromptInterceptorFn } from './types.js';
+import { type CursorMode } from './CursorCodec.js';
+/** MCP Prompt definition (for `prompts/list`) */
+export interface McpPromptDef {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+/** Filter options for selective prompt exposure */
+export interface PromptFilter {
+    /** Only include prompts that have ALL these tags (AND logic) */
+    tags?: string[];
+    /** Only include prompts that have at least ONE of these tags (OR logic) */
+    anyTag?: string[];
+    /** Exclude prompts that have ANY of these tags */
+    exclude?: string[];
+}
+/** Options for configuring pagination in PromptRegistry */
+export interface PromptPaginationOptions {
+    /**
+     * Maximum number of prompts to return per page.
+     * Default: 50
+     */
+    pageSize?: number;
+    /**
+     * 'signed' (HMAC) or 'encrypted' (AES-GCM). Default: 'signed'
+     */
+    cursorMode?: CursorMode;
+    /**
+     * 32-byte secret for the cursor codec. If omitted, uses ephemeral keys.
+     */
+    cursorSecret?: string;
+}
+/**
+ * Callback type for sending `notifications/prompts/list_changed`.
+ * Set by ServerAttachment when the registry is attached to a server.
+ */
+export type PromptNotificationSink = () => void;
+export declare class PromptRegistry<TContext = void> {
+    private readonly _builders;
+    private readonly _interceptors;
+    private _notificationSink?;
+    private _notifyDebounceTimer;
+    private _defaultHydrationTimeout;
+    private _cursorCodec;
+    private _pageSize;
+    /**
+     * Configure stateless cursor-based pagination for `prompts/list`.
+     * Overrides the default page size of 50.
+     *
+     * @param options Pagination configuration (pageSize, modes, secrets)
+     */
+    configurePagination(options: PromptPaginationOptions): void;
+    /**
+     * Set a global hydration timeout for ALL prompts in this registry.
+     *
+     * Individual prompts can override with their own `hydrationTimeout`.
+     * If neither is set, no timeout is applied (backward compatible).
+     *
+     * **Enterprise use case**: The platform team sets a 5s global deadline.
+     * Critical prompts like `morning_briefing` set their own 3s deadline.
+     * Simple prompts (no external I/O) inherit the 5s safety net.
+     *
+     * @param ms - Maximum hydration time in milliseconds (must be > 0)
+     *
+     * @example
+     * ```typescript
+     * const promptRegistry = new PromptRegistry<AppContext>();
+     * promptRegistry.setDefaultHydrationTimeout(5000); // 5s global safety net
+     * ```
+     */
+    setDefaultHydrationTimeout(ms: number): void;
+    /**
+     * Register a single prompt builder.
+     *
+     * Validates that the prompt name is unique and triggers
+     * `buildPromptDefinition()` to compile at registration time.
+     *
+     * @param builder - A prompt builder (from `definePrompt()`)
+     * @throws If a prompt with the same name is already registered
+     */
+    register(builder: PromptBuilder<TContext>): void;
+    /**
+     * Register multiple prompt builders at once.
+     */
+    registerAll(...builders: PromptBuilder<TContext>[]): void;
+    /**
+     * Register a global Prompt Interceptor.
+     *
+     * Interceptors run AFTER the handler produces its `PromptResult` and BEFORE
+     * the result is returned to the MCP client. They can prepend/append messages
+     * to inject compliance headers, tenant context, RBAC constraints, or any
+     * global state that should wrap every prompt.
+     *
+     * **Enterprise use case**: The CISO requires every LLM interaction to include
+     * tenant isolation rules. Register one interceptor — it applies to all 50 prompts.
+     *
+     * Multiple interceptors are supported. They execute in registration order.
+     *
+     * @param interceptor - Callback receiving (ctx, builder, promptMeta)
+     *
+     * @example
+     * ```typescript
+     * promptRegistry.useInterceptor(async (ctx, builder, meta) => {
+     *     builder.prependSystem(
+     *         `[ENTERPRISE COMPLIANCE LAYER]\n` +
+     *         `User Role: ${ctx.user.role} (Tenant ID: ${ctx.tenant.id})\n` +
+     *         `Server Time: ${new Date().toISOString()}`
+     *     );
+     * });
+     * ```
+     */
+    useInterceptor(interceptor: PromptInterceptorFn<TContext>): void;
+    /**
+     * Get all registered MCP Prompt definitions.
+     *
+     * Returns the compiled prompt metadata for `prompts/list`.
+     * @deprecated Use `listPrompts({ filter })` instead for pagination support.
+     */
+    getAllPrompts(): McpPromptDef[];
+    /**
+     * Get prompt definitions filtered by tags.
+     *
+     * Uses Set-based lookups for O(1) tag matching.
+     * @deprecated Use `listPrompts({ filter })` instead for pagination support.
+     */
+    getPrompts(filter: PromptFilter): McpPromptDef[];
+    /**
+     * Get paginated prompt definitions for `prompts/list`.
+     *
+     * Applies tag filters and decodes stateless cursors to return
+     * the requested slice of prompts, along with a `nextCursor` if more exist.
+     * Memory consumption is strictly O(1) across connections.
+     *
+     * @param request - Configuration containing optional `filter` and `cursor`.
+     * @returns Object with the array of prompts and an optional `nextCursor`.
+     */
+    listPrompts(request?: {
+        filter?: PromptFilter;
+        cursor?: string;
+    }): Promise<{
+        prompts: McpPromptDef[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Route an incoming `prompts/get` request to the correct builder.
+     *
+     * Looks up the builder by name and delegates to its `execute()` method.
+     * Returns an error prompt result if the prompt is not found.
+     *
+     * @param ctx - Application context (from contextFactory)
+     * @param name - Prompt name from the incoming MCP request
+     * @param args - Raw string arguments from the MCP client
+     * @returns The hydrated prompt result
+     */
+    routeGet(ctx: TContext, name: string, args: Record<string, string>): Promise<PromptResult>;
+    /**
+     * Set the notification sink for `notifications/prompts/list_changed`.
+     *
+     * Called by `ServerAttachment` when attaching the registry to a server.
+     * The sink invokes the MCP SDK's `sendPromptListChanged()` method.
+     *
+     * @internal — not part of the public API
+     */
+    setNotificationSink(sink: PromptNotificationSink): void;
+    /**
+     * Notify all connected clients that the prompt catalog has changed.
+     *
+     * Sends `notifications/prompts/list_changed` to all connected clients,
+     * causing them to re-fetch `prompts/list` and update their UI.
+     *
+     * **Debounced:** Multiple calls within 100ms are coalesced into a single
+     * notification to prevent storms during bulk registration or RBAC updates.
+     *
+     * Use cases:
+     * - RBAC change: user promoted/demoted → visible prompts change
+     * - SOP update: compliance rules changed → prompt logic updated
+     * - Feature flag: new prompt enabled for beta users
+     *
+     * @example
+     * ```typescript
+     * // In your RBAC webhook handler:
+     * app.post('/webhooks/role-changed', async (req) => {
+     *     await db.users.updateRole(req.userId, req.newRole);
+     *     promptRegistry.notifyChanged(); // All clients refresh instantly
+     * });
+     * ```
+     */
+    notifyChanged(): void;
+    /** Check if a prompt with the given name is registered. */
+    has(name: string): boolean;
+    /** Remove all registered prompts, interceptors, and cancel pending timers. */
+    clear(): void;
+    /** Number of registered prompts. */
+    get size(): number;
+}
+//# sourceMappingURL=PromptRegistry.d.ts.map

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

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