@revealui/ai 0.8.0 → 0.8.1

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"}

package/dist/observability/storage.js

@@ -0,0 +1,184 @@
+/**
+ * @revealui/ai - Event Storage Implementations
+ *
+ * Storage backends for persisting agent events.
+ */
+/**
+ * In-memory storage (no persistence)
+ */
+export class MemoryEventStorage {
+    events = [];
+    async save(events) {
+        this.events = [...events];
+    }
+    async load(filter) {
+        if (!filter) {
+            return [...this.events];
+        }
+        let filtered = [...this.events];
+        if (filter.agentId) {
+            filtered = filtered.filter((e) => e.agentId === filter.agentId);
+        }
+        if (filter.sessionId) {
+            filtered = filtered.filter((e) => e.sessionId === filter.sessionId);
+        }
+        if (filter.taskId) {
+            filtered = filtered.filter((e) => e.taskId === filter.taskId);
+        }
+        if (filter.eventType) {
+            filtered = filtered.filter((e) => e.eventType === filter.eventType);
+        }
+        if (filter.startTime) {
+            const startTime = filter.startTime;
+            filtered = filtered.filter((e) => e.timestamp >= startTime);
+        }
+        if (filter.endTime) {
+            const endTime = filter.endTime;
+            filtered = filtered.filter((e) => e.timestamp <= endTime);
+        }
+        return filtered;
+    }
+    async clear() {
+        this.events = [];
+    }
+    async count(filter) {
+        const events = await this.load(filter);
+        return events.length;
+    }
+}
+/**
+ * Local storage (browser)
+ */
+export class LocalStorageEventStorage {
+    key;
+    constructor(key = 'revealui:agent:events') {
+        this.key = key;
+    }
+    async save(events) {
+        if (typeof window === 'undefined' || !window.localStorage) {
+            throw new Error('LocalStorage not available');
+        }
+        window.localStorage.setItem(this.key, JSON.stringify(events));
+    }
+    async load(filter) {
+        if (typeof window === 'undefined' || !window.localStorage) {
+            return [];
+        }
+        try {
+            const data = window.localStorage.getItem(this.key);
+            if (!data) {
+                return [];
+            }
+            const events = JSON.parse(data);
+            if (!filter) {
+                return events;
+            }
+            let filtered = events;
+            if (filter.agentId) {
+                filtered = filtered.filter((e) => e.agentId === filter.agentId);
+            }
+            if (filter.sessionId) {
+                filtered = filtered.filter((e) => e.sessionId === filter.sessionId);
+            }
+            if (filter.taskId) {
+                filtered = filtered.filter((e) => e.taskId === filter.taskId);
+            }
+            if (filter.eventType) {
+                filtered = filtered.filter((e) => e.eventType === filter.eventType);
+            }
+            if (filter.startTime) {
+                const startTime = filter.startTime;
+                filtered = filtered.filter((e) => e.timestamp >= startTime);
+            }
+            if (filter.endTime) {
+                const endTime = filter.endTime;
+                filtered = filtered.filter((e) => e.timestamp <= endTime);
+            }
+            return filtered;
+        }
+        catch (error) {
+            // Return empty array on error - graceful degradation
+            void (error instanceof Error ? error.message : String(error)); // Query failed  -  graceful degradation
+            return [];
+        }
+    }
+    async clear() {
+        if (typeof window === 'undefined' || !window.localStorage) {
+            return;
+        }
+        window.localStorage.removeItem(this.key);
+    }
+    async count(filter) {
+        const events = await this.load(filter);
+        return events.length;
+    }
+}
+/**
+ * File system storage (Node.js)
+ */
+export class FileSystemEventStorage {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async save(events) {
+        const fs = await import('node:fs/promises');
+        const path = await import('node:path');
+        const dir = path.dirname(this.filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(events, null, 2), 'utf-8');
+    }
+    async load(filter) {
+        const fs = await import('node:fs/promises');
+        try {
+            const data = await fs.readFile(this.filePath, 'utf-8');
+            const events = JSON.parse(data);
+            if (!filter) {
+                return events;
+            }
+            let filtered = events;
+            if (filter.agentId) {
+                filtered = filtered.filter((e) => e.agentId === filter.agentId);
+            }
+            if (filter.sessionId) {
+                filtered = filtered.filter((e) => e.sessionId === filter.sessionId);
+            }
+            if (filter.taskId) {
+                filtered = filtered.filter((e) => e.taskId === filter.taskId);
+            }
+            if (filter.eventType) {
+                filtered = filtered.filter((e) => e.eventType === filter.eventType);
+            }
+            if (filter.startTime) {
+                const startTime = filter.startTime;
+                filtered = filtered.filter((e) => e.timestamp >= startTime);
+            }
+            if (filter.endTime) {
+                const endTime = filter.endTime;
+                filtered = filtered.filter((e) => e.timestamp <= endTime);
+            }
+            return filtered;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async clear() {
+        const fs = await import('node:fs/promises');
+        try {
+            await fs.unlink(this.filePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    async count(filter) {
+        const events = await this.load(filter);
+        return events.length;
+    }
+}

package/dist/orchestration/runtime.d.ts

@@ -8,6 +8,7 @@ import type { ReasoningEffort } from '../llm/providers/base.js';
 import type { AgentSkillProvider } from '../skills/integration/agent-skill-provider.js';
 import type { ApprovalCallback } from '../tools/base.js';
 import type { MCPToolSource, McpClientLike } from '../tools/mcp-adapter.js';
+import type { McpToolCallEvent } from '../tools/mcp-events.js';
 import type { Agent, AgentResult, Task } from './agent.js';
 /**
  * Reasoning-depth hint for a task. Alias of the neutral `ReasoningEffort` — the agnostic
@@ -64,6 +65,12 @@ export interface RuntimeConfig {
         name: string;
         client: McpClientLike;
     }>;
+    /**
+     * GAP-355 integrity audit for MCP tools discovered at run time.
+     * Passed into `createToolsFromMcpClient` and `discoverMCPTools` so library
+     * consumers (not only agent-stream) fail closed when a receipt cannot land.
+     */
+    onToolAudit?: (event: McpToolCallEvent) => void | Promise<void>;
     /**
      * Optional skill provider. When set, activated skills are injected into the
      * system prompt before the first LLM call, giving the agent contextual

package/dist/orchestration/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG5E,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACpE;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,gCAAgC,EAAE,SAAS,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,cAAc,CAAgD;IACtE,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,aAAkB;IA0BtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IA8OrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI7B;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9E;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B9B;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACpE;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,gCAAgC,EAAE,SAAS,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,cAAc,CAAgD;IACtE,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,aAAkB;IA2BtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IAsPrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI7B;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9E;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B9B;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}

package/dist/orchestration/runtime.js

@@ -23,6 +23,7 @@ export class AgentRuntime {
             enableCache: config.enableCache ?? true, // Enable by default for cost savings
             mcpToolSource: config.mcpToolSource,
             mcpClients: config.mcpClients,
+            onToolAudit: config.onToolAudit,
             skillProvider: config.skillProvider,
             thinkingLevel: config.thinkingLevel,
             modelTier: config.modelTier,
@@ -64,13 +65,19 @@ export class AgentRuntime {
         //   - Standard `McpClient` instances (Stage 5.1a, preferred)
         //   - `MCPToolSource` / hypervisor (legacy, deprecated but supported)
         const mcpTools = [];
+        const onToolAudit = this.config.onToolAudit;
         if (this.config.mcpToolSource) {
-            mcpTools.push(...discoverMCPTools(this.config.mcpToolSource));
+            mcpTools.push(...discoverMCPTools(this.config.mcpToolSource, {
+                ...(onToolAudit !== undefined ? { onToolAudit } : {}),
+            }));
         }
         if (this.config.mcpClients && this.config.mcpClients.length > 0) {
             for (const { name, client } of this.config.mcpClients) {
                 try {
-                    const fromClient = await createToolsFromMcpClient(client, { namespace: name });
+                    const fromClient = await createToolsFromMcpClient(client, {
+                        namespace: name,
+                        ...(onToolAudit !== undefined ? { onToolAudit } : {}),
+                    });
                     mcpTools.push(...fromClient);
                 }
                 catch {

package/dist/orchestration/ticket-agent.d.ts

@@ -15,6 +15,7 @@ import type { Database } from '@revealui/db/client';
 import type { LLMClient } from '../llm/client.js';
 import type { EpisodicMemory } from '../memory/stores/episodic-memory.js';
 import type { AdminAPIClient, CollectionMetadata, GlobalMetadata } from '../tools/admin/factory.js';
+import type { Tool } from '../tools/base.js';
 import type { TicketMutationClient } from '../tools/ticket-tools.js';
 import type { AgentResult } from './agent.js';
 export interface TicketInput {
@@ -51,6 +52,15 @@ export interface TicketAgentConfig {
     maxIterations?: number;
     /** Timeout in ms (default: 120_000) */
     timeout?: number;
+    /**
+     * Optional tool transform after the tool set is assembled (GAP-355 S6-4).
+     * Server injects pre-authorize wraps without `@revealui/ai` importing server.
+     * Called once per dispatch with the ticket id and optional dispatchId.
+     */
+    wrapTools?: (tools: Tool[], ctx: {
+        ticketId: string;
+        dispatchId?: string;
+    }) => Tool[];
 }
 export declare class TicketAgentDispatcher {
     private config;

package/dist/orchestration/ticket-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ticket-agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/ticket-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,OAAO,KAAK,EAAS,WAAW,EAAQ,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;IAErB,2DAA2D;IAC3D,SAAS,EAAE,cAAc,CAAC;IAE1B,wEAAwE;IACxE,YAAY,EAAE,oBAAoB,CAAC;IAEnC,yEAAyE;IACzE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAEnC,yCAAyC;IACzC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAE3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwDD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,YAAY,CAAoB;gBAE5B,MAAM,EAAE,iBAAiB;IAUrC;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CA0DjG"}
+{"version":3,"file":"ticket-agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/ticket-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,OAAO,KAAK,EAAS,WAAW,EAAQ,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;IAErB,2DAA2D;IAC3D,SAAS,EAAE,cAAc,CAAC;IAE1B,wEAAwE;IACxE,YAAY,EAAE,oBAAoB,CAAC;IAEnC,yEAAyE;IACzE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAEnC,yCAAyC;IACzC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAE3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,EAAE,CAAC;CACvF;AAwDD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,YAAY,CAAoB;gBAE5B,MAAM,EAAE,iBAAiB;IAUrC;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CAgEjG"}

package/dist/orchestration/ticket-agent.js

@@ -113,7 +113,13 @@ export class TicketAgentDispatcher {
         const extraTools = db
             ? [webScraperTool, createDocumentSummarizerTool(db, this.config.llmClient)]
             : [webScraperTool];
-        const tools = [...cmsTools, ...ticketTools, ...extraTools];
+        let tools = [...cmsTools, ...ticketTools, ...extraTools];
+        if (this.config.wrapTools) {
+            tools = this.config.wrapTools(tools, {
+                ticketId: ticket.id,
+                ...(options.dispatchId !== undefined ? { dispatchId: options.dispatchId } : {}),
+            });
+        }
         // The runtime does not call agent.memory  -  satisfy the interface with a stub when no
         // shared memory instance is provided. Cast is safe: only runtime touches this field.
         const memory = (sharedMemory ?? {});