@revealui/ai 0.7.0 → 0.8.1

package/dist/observability/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/observability/export.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EAAE,EACvB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GACA,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAyD3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EAAE,EACvB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,IAAI,CAoBN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,IAAI,CAgBN;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,gBAAgB;IAIpC;;OAEG;IACH,SAAS,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAa7D;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAgBvF;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;IAKhB;;OAEG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,IAAI;IAKP;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAU3F;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAIlF;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAItF;;OAEG;IACH,YAAY,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAIhE;;OAEG;IACH,cAAc,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;CAGnE"}

package/dist/observability/export.js

@@ -0,0 +1,229 @@
+/**
+ * @revealui/ai - Export Utilities
+ *
+ * Export agent events to various formats (JSON, CSV, NDJSON).
+ */
+/**
+ * Export events to JSON format
+ */
+export function exportToJSON(events, options) {
+    const data = options?.metadata
+        ? {
+            metadata: {
+                exportedAt: new Date().toISOString(),
+                eventCount: events.length,
+                ...options.metadata,
+            },
+            events,
+        }
+        : events;
+    return options?.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}
+/**
+ * Export events to CSV format
+ */
+export function exportToCSV(events) {
+    if (events.length === 0) {
+        return '';
+    }
+    // Define common columns
+    const columns = [
+        'timestamp',
+        'eventType',
+        'agentId',
+        'sessionId',
+        'taskId',
+        // Decision-specific
+        'reasoning',
+        'chosenTool',
+        'confidence',
+        // Tool call-specific
+        'toolName',
+        'success',
+        'durationMs',
+        'errorMessage',
+        // LLM call-specific
+        'provider',
+        'model',
+        'promptTokens',
+        'completionTokens',
+        'cost',
+        'cacheHit',
+        // Error-specific
+        'message',
+        'recoverable',
+        'errorCode',
+    ];
+    // Create CSV header
+    const header = columns.join(',');
+    // Create CSV rows
+    const rows = events.map((event) => {
+        const row = [];
+        for (const column of columns) {
+            const value = event[column];
+            if (value === undefined || value === null) {
+                row.push('');
+            }
+            else if (typeof value === 'string' && (value.includes(',') || value.includes('"'))) {
+                // Escape strings with commas or quotes
+                row.push(`"${value.replace(/"/g, '""')}"`);
+            }
+            else {
+                row.push(String(value));
+            }
+        }
+        return row.join(',');
+    });
+    return [header, ...rows].join('\n');
+}
+/**
+ * Export events to NDJSON format (newline-delimited JSON)
+ */
+export function exportToNDJSON(events) {
+    return events.map((event) => JSON.stringify(event)).join('\n');
+}
+/**
+ * Export events to a file (Node.js)
+ */
+export async function exportToFile(events, filePath, format = 'json') {
+    const fs = await import('node:fs/promises');
+    let content;
+    switch (format) {
+        case 'json':
+            content = exportToJSON(events, { pretty: true });
+            break;
+        case 'csv':
+            content = exportToCSV(events);
+            break;
+        case 'ndjson':
+            content = exportToNDJSON(events);
+            break;
+    }
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Create a downloadable file blob (Browser)
+ */
+export function createDownloadableBlob(events, format = 'json') {
+    let content;
+    let mimeType;
+    switch (format) {
+        case 'json':
+            content = exportToJSON(events, { pretty: true });
+            mimeType = 'application/json';
+            break;
+        case 'csv':
+            content = exportToCSV(events);
+            mimeType = 'text/csv';
+            break;
+        case 'ndjson':
+            content = exportToNDJSON(events);
+            mimeType = 'application/x-ndjson';
+            break;
+    }
+    return new Blob([content], { type: mimeType });
+}
+/**
+ * Trigger download in browser
+ */
+export function downloadEvents(events, filename, format = 'json') {
+    if (typeof window === 'undefined') {
+        throw new Error('downloadEvents can only be used in browser environments');
+    }
+    const blob = createDownloadableBlob(events, format);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+/**
+ * Export helper class with logger integration
+ */
+export class EventExporter {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Export all events
+     */
+    exportAll(format = 'json') {
+        const events = this.logger.getEvents();
+        switch (format) {
+            case 'json':
+                return exportToJSON(events, { pretty: true });
+            case 'csv':
+                return exportToCSV(events);
+            case 'ndjson':
+                return exportToNDJSON(events);
+        }
+    }
+    /**
+     * Export filtered events
+     */
+    exportFiltered(filter, format = 'json') {
+        const events = this.logger.getEvents(filter);
+        switch (format) {
+            case 'json':
+                return exportToJSON(events, {
+                    pretty: true,
+                    metadata: { filter },
+                });
+            case 'csv':
+                return exportToCSV(events);
+            case 'ndjson':
+                return exportToNDJSON(events);
+        }
+    }
+    /**
+     * Export to file (Node.js)
+     */
+    async exportToFile(filePath, format = 'json', filter) {
+        const events = filter ? this.logger.getEvents(filter) : this.logger.getEvents();
+        await exportToFile(events, filePath, format);
+    }
+    /**
+     * Download in browser
+     */
+    download(filename, format = 'json', filter) {
+        const events = filter ? this.logger.getEvents(filter) : this.logger.getEvents();
+        downloadEvents(events, filename, format);
+    }
+    /**
+     * Export by time range
+     */
+    exportTimeRange(start, end, format = 'json') {
+        return this.exportFiltered({
+            startTime: start.getTime(),
+            endTime: end.getTime(),
+        }, format);
+    }
+    /**
+     * Export by agent
+     */
+    exportByAgent(agentId, format = 'json') {
+        return this.exportFiltered({ agentId }, format);
+    }
+    /**
+     * Export by session
+     */
+    exportBySession(sessionId, format = 'json') {
+        return this.exportFiltered({ sessionId }, format);
+    }
+    /**
+     * Export errors only
+     */
+    exportErrors(format = 'json') {
+        return this.exportFiltered({ eventType: 'error' }, format);
+    }
+    /**
+     * Export LLM calls only
+     */
+    exportLLMCalls(format = 'json') {
+        return this.exportFiltered({ eventType: 'llm_call' }, format);
+    }
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @revealui/ai - Observability
+ *
+ * **INCUBATING (fleet-redundancy C11 / ADR-007).** Agent event/metrics helpers
+ * are available as a library. No RevealUI app currently mounts this surface as
+ * the product observability path; prefer explicit wiring under a WIRE ticket.
+ *
+ * Agent operation tracking, logging, and metrics collection.
+ */
+export { createDownloadableBlob, downloadEvents, EventExporter, exportToCSV, exportToFile, exportToJSON, exportToNDJSON, } from './export.js';
+export type { LLMCallOptions, LLMResponse } from './instrumentation.js';
+export { instrumentAgent, instrumentLLMCall, instrumentTaskExecution, instrumentTool, LLMCostCalculators, logTaskDelegation, } from './instrumentation.js';
+export { AgentEventLogger } from './logger.js';
+export { AgentMetricsCollector } from './metrics.js';
+export { AgentEventQuery } from './query.js';
+export { FileSystemEventStorage, LocalStorageEventStorage, MemoryEventStorage, } from './storage.js';
+export type { AgentEvent, AgentMetrics, DecisionEvent, ErrorEvent, EventFilter, EventStorage, LLMCallEvent, MetricsSummary, ToolCallEvent, } from './types.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,cAAc,YAAY,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,16 @@
+/**
+ * @revealui/ai - Observability
+ *
+ * **INCUBATING (fleet-redundancy C11 / ADR-007).** Agent event/metrics helpers
+ * are available as a library. No RevealUI app currently mounts this surface as
+ * the product observability path; prefer explicit wiring under a WIRE ticket.
+ *
+ * Agent operation tracking, logging, and metrics collection.
+ */
+export { createDownloadableBlob, downloadEvents, EventExporter, exportToCSV, exportToFile, exportToJSON, exportToNDJSON, } from './export.js';
+export { instrumentAgent, instrumentLLMCall, instrumentTaskExecution, instrumentTool, LLMCostCalculators, logTaskDelegation, } from './instrumentation.js';
+export { AgentEventLogger } from './logger.js';
+export { AgentMetricsCollector } from './metrics.js';
+export { AgentEventQuery } from './query.js';
+export { FileSystemEventStorage, LocalStorageEventStorage, MemoryEventStorage, } from './storage.js';
+export * from './types.js';

package/dist/observability/instrumentation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @revealui/ai - Instrumentation Utilities
+ *
+ * Helper functions and wrappers for instrumenting agent operations with observability.
+ */
+import type { Agent, AgentResult, Task } from '../orchestration/agent.js';
+import type { Tool } from '../tools/base.js';
+import type { AgentEventLogger } from './logger.js';
+/**
+ * Wrap a tool execution with observability logging
+ */
+export declare function instrumentTool(tool: Tool, logger: AgentEventLogger, agentId: string, sessionId: string): Tool;
+/**
+ * Wrap an agent with observability logging
+ */
+export declare function instrumentAgent(agent: Agent, logger: AgentEventLogger): Agent & {
+    logger: AgentEventLogger;
+};
+/**
+ * Instrument a task delegation decision
+ */
+export declare function logTaskDelegation(logger: AgentEventLogger, task: Task, selectedAgent: Agent, reasoning: string, confidence?: number): void;
+/**
+ * Instrument task execution
+ */
+export declare function instrumentTaskExecution<T extends AgentResult>(logger: AgentEventLogger, task: Task, agentId: string, executor: () => Promise<T>): Promise<T>;
+/**
+ * Instrument LLM call with token counting
+ */
+export interface LLMCallOptions {
+    provider: string;
+    model: string;
+    agentId: string;
+    sessionId: string;
+    taskId?: string;
+}
+export interface LLMResponse {
+    content: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    cacheHit?: boolean;
+}
+export declare function instrumentLLMCall<T extends LLMResponse>(logger: AgentEventLogger, options: LLMCallOptions, executor: () => Promise<T>, costCalculator?: (usage: T['usage']) => number): Promise<T>;
+/**
+ * Cost calculators for popular LLM providers
+ */
+export declare const LLMCostCalculators: {
+    /**
+     * OpenAI cost calculator
+     * Prices as of 2024 (per 1M tokens)
+     */
+    openai: (model: string, usage: {
+        promptTokens: number;
+        completionTokens: number;
+    }) => number;
+    /**
+     * Anthropic cost calculator
+     * Prices as of 2024 (per 1M tokens)
+     */
+    anthropic: (model: string, usage: {
+        promptTokens: number;
+        completionTokens: number;
+    }) => number;
+};
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/observability/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/observability/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,IAAI,CAuDN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,gBAAgB,GACvB,KAAK,GAAG;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAOtC;AA4BD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,KAAK,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAcN;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,WAAW,EACjE,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CA2CZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAC3D,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,MAAM,GAC7C,OAAO,CAAC,CAAC,CAAC,CA4CZ;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;OAGG;oBACa,MAAM,SAAS;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE;IAcjF;;;OAGG;uBACgB,MAAM,SAAS;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE;CAarF,CAAC"}

package/dist/observability/instrumentation.js

@@ -0,0 +1,219 @@
+/**
+ * @revealui/ai - Instrumentation Utilities
+ *
+ * Helper functions and wrappers for instrumenting agent operations with observability.
+ */
+/**
+ * Wrap a tool execution with observability logging
+ */
+export function instrumentTool(tool, logger, agentId, sessionId) {
+    return {
+        ...tool,
+        execute: async (params) => {
+            const startTime = Date.now();
+            try {
+                const result = await tool.execute(params);
+                const durationMs = Date.now() - startTime;
+                // Log tool call
+                logger.logToolCall({
+                    timestamp: Date.now(),
+                    agentId,
+                    sessionId,
+                    toolName: tool.name,
+                    params: params,
+                    result: result.data,
+                    durationMs,
+                    success: result.success,
+                    errorMessage: result.error,
+                });
+                return result;
+            }
+            catch (error) {
+                const durationMs = Date.now() - startTime;
+                // Log failed tool call
+                logger.logToolCall({
+                    timestamp: Date.now(),
+                    agentId,
+                    sessionId,
+                    toolName: tool.name,
+                    params: params,
+                    durationMs,
+                    success: false,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
+                // Log error event
+                logger.logError({
+                    timestamp: Date.now(),
+                    agentId,
+                    sessionId,
+                    message: `Tool execution failed: ${tool.name}`,
+                    stack: error instanceof Error ? error.stack : undefined,
+                    recoverable: true,
+                    errorCode: 'TOOL_EXECUTION_ERROR',
+                    context: { toolName: tool.name, params },
+                });
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Wrap an agent with observability logging
+ */
+export function instrumentAgent(agent, logger) {
+    return {
+        ...agent,
+        logger,
+        // Agent interface methods would be instrumented here
+        // This is a placeholder as the Agent interface may vary
+    };
+}
+function taskSessionId(task) {
+    const sessionId = task.sessionId;
+    return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'session';
+}
+function taskInputParams(task) {
+    const extended = task;
+    if (extended.input !== undefined &&
+        extended.input !== null &&
+        typeof extended.input === 'object' &&
+        !Array.isArray(extended.input)) {
+        return extended.input;
+    }
+    return (task.parameters ?? {});
+}
+/**
+ * Instrument a task delegation decision
+ */
+export function logTaskDelegation(logger, task, selectedAgent, reasoning, confidence) {
+    logger.logDecision({
+        timestamp: Date.now(),
+        agentId: selectedAgent.id,
+        sessionId: taskSessionId(task),
+        taskId: task.id,
+        reasoning,
+        chosenTool: selectedAgent.name,
+        confidence,
+        context: {
+            taskType: task.type,
+            taskDescription: task.description,
+        },
+    });
+}
+/**
+ * Instrument task execution
+ */
+export async function instrumentTaskExecution(logger, task, agentId, executor) {
+    const startTime = Date.now();
+    const sessionId = taskSessionId(task);
+    try {
+        const result = await executor();
+        const durationMs = Date.now() - startTime;
+        // Log as a tool call (task execution is essentially a tool)
+        logger.logToolCall({
+            timestamp: Date.now(),
+            agentId,
+            sessionId,
+            taskId: task.id,
+            toolName: `task:${task.type}`,
+            params: taskInputParams(task),
+            result: result.output,
+            durationMs,
+            success: result.success,
+            errorMessage: result.error,
+        });
+        return result;
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        logger.logError({
+            timestamp: Date.now(),
+            agentId,
+            sessionId,
+            taskId: task.id,
+            message: `Task execution failed: ${task.type}`,
+            stack: error instanceof Error ? error.stack : undefined,
+            recoverable: false,
+            errorCode: 'TASK_EXECUTION_ERROR',
+            context: {
+                taskType: task.type,
+                durationMs,
+            },
+        });
+        throw error;
+    }
+}
+export async function instrumentLLMCall(logger, options, executor, costCalculator) {
+    const startTime = Date.now();
+    try {
+        const response = await executor();
+        const durationMs = Date.now() - startTime;
+        const cost = costCalculator ? costCalculator(response.usage) : undefined;
+        logger.logLLMCall({
+            timestamp: Date.now(),
+            agentId: options.agentId,
+            sessionId: options.sessionId,
+            taskId: options.taskId,
+            provider: options.provider,
+            model: options.model,
+            promptTokens: response.usage.promptTokens,
+            completionTokens: response.usage.completionTokens,
+            durationMs,
+            cost,
+            cacheHit: response.cacheHit,
+        });
+        return response;
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        logger.logError({
+            timestamp: Date.now(),
+            agentId: options.agentId,
+            sessionId: options.sessionId,
+            taskId: options.taskId,
+            message: `LLM call failed: ${options.provider}/${options.model}`,
+            stack: error instanceof Error ? error.stack : undefined,
+            recoverable: true,
+            errorCode: 'LLM_CALL_ERROR',
+            context: {
+                provider: options.provider,
+                model: options.model,
+                durationMs,
+            },
+        });
+        throw error;
+    }
+}
+/**
+ * Cost calculators for popular LLM providers
+ */
+export const LLMCostCalculators = {
+    /**
+     * OpenAI cost calculator
+     * Prices as of 2024 (per 1M tokens)
+     */
+    openai: (model, usage) => {
+        const prices = {
+            'gpt-4-turbo': { input: 10, output: 30 },
+            'gpt-4': { input: 30, output: 60 },
+            'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+        };
+        const price = prices[model] ?? prices['gpt-3.5-turbo'] ?? { input: 0.5, output: 1.5 };
+        return ((usage.promptTokens / 1_000_000) * price.input +
+            (usage.completionTokens / 1_000_000) * price.output);
+    },
+    /**
+     * Anthropic cost calculator
+     * Prices as of 2024 (per 1M tokens)
+     */
+    anthropic: (model, usage) => {
+        const prices = {
+            'claude-3-opus': { input: 15, output: 75 },
+            'claude-3-sonnet': { input: 3, output: 15 },
+            'claude-3-haiku': { input: 0.25, output: 1.25 },
+        };
+        const price = prices[model] ?? prices['claude-3-sonnet'] ?? { input: 3, output: 15 };
+        return ((usage.promptTokens / 1_000_000) * price.input +
+            (usage.completionTokens / 1_000_000) * price.output);
+    },
+};

package/dist/observability/storage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @revealui/ai - Event Storage Implementations
+ *
+ * Storage backends for persisting agent events.
+ */
+import type { AnyAgentEvent, EventFilter, EventStorage } from './types.js';
+/**
+ * In-memory storage (no persistence)
+ */
+export declare class MemoryEventStorage implements EventStorage {
+    private events;
+    save(events: AnyAgentEvent[]): Promise<void>;
+    load(filter?: EventFilter): Promise<AnyAgentEvent[]>;
+    clear(): Promise<void>;
+    count(filter?: EventFilter): Promise<number>;
+}
+/**
+ * Local storage (browser)
+ */
+export declare class LocalStorageEventStorage implements EventStorage {
+    private key;
+    constructor(key?: string);
+    save(events: AnyAgentEvent[]): Promise<void>;
+    load(filter?: EventFilter): Promise<AnyAgentEvent[]>;
+    clear(): Promise<void>;
+    count(filter?: EventFilter): Promise<number>;
+}
+/**
+ * File system storage (Node.js)
+ */
+export declare class FileSystemEventStorage implements EventStorage {
+    private filePath;
+    constructor(filePath: string);
+    save(events: AnyAgentEvent[]): Promise<void>;
+    load(filter?: EventFilter): Promise<AnyAgentEvent[]>;
+    clear(): Promise<void>;
+    count(filter?: EventFilter): Promise<number>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/observability/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/observability/storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3E;;GAEG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,MAAM,CAAuB;IAE/B,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoCpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAInD;AAED;;GAEG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,GAAG,CAAS;gBAER,GAAG,SAA0B;IAInC,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAqDpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAInD;AAED;;GAEG;AACH,qBAAa,sBAAuB,YAAW,YAAY;IACzD,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAItB,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5C,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAgDpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAYtB,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAInD"}