@revealui/ai 0.8.0 → 0.9.0

package/dist/tools/integrity-audit.js

@@ -0,0 +1,64 @@
+/**
+ * Tool integrity audit wrapper (GAP-355 Stage 5 S5-4).
+ *
+ * Same fail-closed contract as `createToolsFromMcpClient({ onToolAudit })`:
+ * after a successful tool execution, await the audit hook and rethrow so an
+ * unrecorded success cannot complete. On tool failure, prefer the tool error
+ * if a secondary audit write fails.
+ *
+ * Used for admin CMS + coding tools that are not MCP server tools.
+ */
+/**
+ * Wrap a tool so each `execute` emits an integrity audit event.
+ * Returns a new tool object; does not mutate the input.
+ */
+export function wrapToolWithIntegrityAudit(tool, onToolAudit) {
+    return {
+        ...tool,
+        async execute(params) {
+            const started = Date.now();
+            let result;
+            try {
+                result = await tool.execute(params);
+            }
+            catch (error) {
+                const errorText = error instanceof Error ? error.message : String(error);
+                try {
+                    await onToolAudit({
+                        toolName: tool.name,
+                        success: false,
+                        duration_ms: Date.now() - started,
+                        error: errorText,
+                    });
+                }
+                catch {
+                    // Prefer the original tool exception over a secondary audit failure.
+                }
+                throw error;
+            }
+            const event = {
+                toolName: tool.name,
+                success: result.success,
+                duration_ms: Date.now() - started,
+                ...(result.error !== undefined ? { error: result.error } : {}),
+            };
+            if (result.success) {
+                await onToolAudit(event);
+                return result;
+            }
+            try {
+                await onToolAudit(event);
+            }
+            catch {
+                // Prefer the tool failure over a secondary audit failure.
+            }
+            return result;
+        },
+    };
+}
+/** Map over a tool list when a handler is provided; otherwise return as-is. */
+export function maybeWrapToolsWithIntegrityAudit(tools, onToolAudit) {
+    if (!onToolAudit)
+        return tools;
+    return tools.map((tool) => wrapToolWithIntegrityAudit(tool, onToolAudit));
+}

package/dist/tools/mcp-adapter.d.ts

@@ -21,7 +21,7 @@
  * `McpClientLike` / `MCPToolSource` with whichever client they construct.
  */
 import type { Tool } from './base.js';
-import { type McpEventSink } from './mcp-events.js';
+import { type McpEventSink, type McpToolCallEvent } from './mcp-events.js';
 export interface MCPTool {
     name: string;
     description: string;
@@ -176,6 +176,14 @@ export interface CreateToolsFromMcpClientOptions {
      * Safe to pass a throwing sink — adapter swallows sink errors.
      */
     onEvent?: McpEventSink;
+    /**
+     * Integrity audit hook (GAP-355 Stage 5). Fires once per server tool **and**
+     * resource/prompt meta-tool call with the `mcp.tool.call` summary shape
+     * (`toolName` is the bare primitive name, e.g. `read_resource`). Unlike
+     * `onEvent`, this is **awaited** and **rethrows** so a failed audit write
+     * fails the tool execution (fail-closed).
+     */
+    onToolAudit?: (event: McpToolCallEvent) => void | Promise<void>;
 }
 /** Spec-shaped `Progress` notification subset. */
 export interface McpProgressLike {
@@ -236,6 +244,15 @@ export declare function registerMCPTools(mcpClient: MCPClient, registry: {
  * - Circular references → replaced with "[Circular]"
  */
 export declare function serializeMCPResult(value: unknown): unknown;
+/** Options for the legacy hypervisor discovery path (GAP-355 integrity). */
+export interface DiscoverMCPToolsOptions {
+    /**
+     * Integrity audit hook (awaited, fail-closed on success). Same contract as
+     * `createToolsFromMcpClient({ onToolAudit })`. `namespace` on the event is
+     * the MCP server name from the hypervisor source.
+     */
+    onToolAudit?: (event: McpToolCallEvent) => void | Promise<void>;
+}
 /**
  * Discover all tools from a running MCPHypervisor (or any MCPToolSource)
  * and return them as RevealUI Tool instances.
@@ -243,15 +260,18 @@ export declare function serializeMCPResult(value: unknown): unknown;
  * Tool names use the hypervisor's namespacing (@@mcp_{server}_{tool}) so
  * collisions across servers are impossible.
  *
+ * @deprecated Prefer `createToolsFromMcpClient` (Stage 5.1a). Kept for
+ *   AgentRuntime `mcpToolSource` compatibility.
+ *
  * @example
  * ```typescript
  * import { MCPHypervisor } from '@revealui/mcp'
  * import { discoverMCPTools } from '@revealui/ai'
  *
  * const hypervisor = MCPHypervisor.getInstance()
- * const tools = discoverMCPTools(hypervisor)
+ * const tools = discoverMCPTools(hypervisor, { onToolAudit })
  * agent.tools.push(...tools)
  * ```
  */
-export declare function discoverMCPTools(source: MCPToolSource): Tool[];
+export declare function discoverMCPTools(source: MCPToolSource, options?: DiscoverMCPToolsOptions): Tool[];
 //# sourceMappingURL=mcp-adapter.d.ts.map

package/dist/tools/mcp-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAC;AAClD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,IAAI,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACxE,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,qBAAqB,CAAC,CAAC,CAAC;IACjF,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC9F;;;OAGG;IACH,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAC7E,SAAS,CAAC,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uFAAuF;AACvF,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,aAAa,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;QACtB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC/C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,EAAE,CAAC,CA0CjB;AAoXD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAuB9E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAa1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,CAkC9D"}
+{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-adapter.ts"],"names":[],"mappings":"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"}

package/dist/tools/mcp-adapter.js

@@ -60,6 +60,7 @@ export async function createToolsFromMcpClient(client, options) {
         ...(options.onProgress !== undefined ? { onProgress: options.onProgress } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+        ...(options.onToolAudit !== undefined ? { onToolAudit: options.onToolAudit } : {}),
     };
     const tools = [];
     // --- Server tools (Stage 5.1a) -----------------------------------------
@@ -81,6 +82,36 @@ export async function createToolsFromMcpClient(client, options) {
     }
     return tools;
 }
+/** Await integrity audit; rethrow so unrecorded tool success cannot complete. */
+async function awaitToolAudit(ctx, event) {
+    if (!ctx.onToolAudit)
+        return;
+    await ctx.onToolAudit(event);
+}
+/**
+ * Build an integrity event and await it. Success path rethrows audit failures;
+ * failure path prefers the original tool/meta-tool error.
+ */
+async function finishToolIntegrity(ctx, toolName, started, success, error) {
+    const event = {
+        kind: 'mcp.tool.call',
+        namespace: ctx.namespace,
+        toolName,
+        duration_ms: Date.now() - started,
+        success,
+        ...(error !== undefined ? { error } : {}),
+    };
+    if (success) {
+        await awaitToolAudit(ctx, event);
+        return;
+    }
+    try {
+        await awaitToolAudit(ctx, event);
+    }
+    catch {
+        // Prefer the tool / meta-tool failure over a secondary audit failure.
+    }
+}
 /**
  * Build the request-options object passed to `client.callTool()` /
  * `readResource()` / etc. Wraps the ctx's `onProgress` with the
@@ -107,42 +138,43 @@ function buildServerTool(client, descriptor, ctx) {
         async execute(params) {
             const validated = zodSchema.parse(params);
             const started = Date.now();
+            let toolSucceeded = false;
+            let errorText;
+            let payload;
             try {
                 const result = await client.callTool(descriptor.name, validated, buildRequestOptions(ctx, descriptor.name));
                 if (result.isError) {
-                    const errorText = extractErrorText(result);
-                    emitMcpEvent(ctx.onEvent, {
-                        kind: 'mcp.tool.call',
-                        namespace: ctx.namespace,
-                        toolName: descriptor.name,
-                        duration_ms: Date.now() - started,
-                        success: false,
-                        error: errorText,
-                    });
-                    return { success: false, error: errorText };
+                    errorText = extractErrorText(result);
+                }
+                else {
+                    toolSucceeded = true;
+                    payload = result.structuredContent ?? result.content;
                 }
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.tool.call',
-                    namespace: ctx.namespace,
-                    toolName: descriptor.name,
-                    duration_ms: Date.now() - started,
-                    success: true,
-                });
-                const payload = result.structuredContent ?? result.content;
-                return { success: true, data: serializeMCPResult(payload) };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.tool.call',
-                    namespace: ctx.namespace,
-                    toolName: descriptor.name,
-                    duration_ms: Date.now() - started,
-                    success: false,
-                    error: message,
-                });
-                return { success: false, error: message };
+                errorText = error instanceof Error ? error.message : String(error);
             }
+            const event = {
+                kind: 'mcp.tool.call',
+                namespace: ctx.namespace,
+                toolName: descriptor.name,
+                duration_ms: Date.now() - started,
+                success: toolSucceeded,
+                ...(errorText !== undefined ? { error: errorText } : {}),
+            };
+            emitMcpEvent(ctx.onEvent, event);
+            if (toolSucceeded) {
+                // Integrity: unrecorded success must not complete as success.
+                await awaitToolAudit(ctx, event);
+                return { success: true, data: serializeMCPResult(payload) };
+            }
+            try {
+                await awaitToolAudit(ctx, event);
+            }
+            catch {
+                // Prefer the tool failure over a secondary audit failure.
+            }
+            return { success: false, error: errorText ?? 'Tool failed' };
         },
         getMetadata() {
             return { category: ctx.category, version: '1.0.0', mcpNamespace: ctx.namespace };
@@ -157,28 +189,29 @@ function buildListResourcesTool(client, ctx) {
         parameters: z.object({}),
         async execute() {
             const started = Date.now();
+            let ok = false;
+            let errorText;
+            let resources = [];
             try {
-                const resources = (await client.listResources?.(buildRequestOptions(ctx, 'list_resources'))) ?? [];
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.resource.list',
-                    namespace: ctx.namespace,
-                    duration_ms: Date.now() - started,
-                    success: true,
-                    resourceCount: resources.length,
-                });
-                return { success: true, data: serializeMCPResult(resources) };
+                resources =
+                    (await client.listResources?.(buildRequestOptions(ctx, 'list_resources'))) ?? [];
+                ok = true;
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.resource.list',
-                    namespace: ctx.namespace,
-                    duration_ms: Date.now() - started,
-                    success: false,
-                    error: message,
-                });
-                return { success: false, error: message };
+                errorText = error instanceof Error ? error.message : String(error);
             }
+            emitMcpEvent(ctx.onEvent, {
+                kind: 'mcp.resource.list',
+                namespace: ctx.namespace,
+                duration_ms: Date.now() - started,
+                success: ok,
+                ...(ok ? { resourceCount: resources.length } : {}),
+                ...(errorText !== undefined ? { error: errorText } : {}),
+            });
+            await finishToolIntegrity(ctx, 'list_resources', started, ok, errorText);
+            if (ok)
+                return { success: true, data: serializeMCPResult(resources) };
+            return { success: false, error: errorText ?? 'list_resources failed' };
         },
         getMetadata() {
             return {
@@ -202,34 +235,34 @@ function buildReadResourceTool(client, ctx) {
         async execute(params) {
             const { uri } = paramsSchema.parse(params);
             const started = Date.now();
+            let ok = false;
+            let errorText;
+            let contents = [];
             try {
-                const contents = (await client.readResource?.(uri, buildRequestOptions(ctx, 'read_resource'))) ?? [];
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.resource.read',
-                    namespace: ctx.namespace,
-                    uri,
-                    duration_ms: Date.now() - started,
-                    success: true,
-                });
-                const joinedText = flattenResourceText(contents);
-                const base = {
-                    success: true,
-                    data: serializeMCPResult(contents),
-                };
-                return joinedText !== undefined ? { ...base, content: joinedText } : base;
+                contents =
+                    (await client.readResource?.(uri, buildRequestOptions(ctx, 'read_resource'))) ?? [];
+                ok = true;
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.resource.read',
-                    namespace: ctx.namespace,
-                    uri,
-                    duration_ms: Date.now() - started,
-                    success: false,
-                    error: message,
-                });
-                return { success: false, error: message };
+                errorText = error instanceof Error ? error.message : String(error);
             }
+            emitMcpEvent(ctx.onEvent, {
+                kind: 'mcp.resource.read',
+                namespace: ctx.namespace,
+                uri,
+                duration_ms: Date.now() - started,
+                success: ok,
+                ...(errorText !== undefined ? { error: errorText } : {}),
+            });
+            await finishToolIntegrity(ctx, 'read_resource', started, ok, errorText);
+            if (!ok)
+                return { success: false, error: errorText ?? 'read_resource failed' };
+            const joinedText = flattenResourceText(contents);
+            const base = {
+                success: true,
+                data: serializeMCPResult(contents),
+            };
+            return joinedText !== undefined ? { ...base, content: joinedText } : base;
         },
         getMetadata() {
             return {
@@ -249,28 +282,28 @@ function buildListPromptsTool(client, ctx) {
         parameters: z.object({}),
         async execute() {
             const started = Date.now();
+            let ok = false;
+            let errorText;
+            let prompts = [];
             try {
-                const prompts = (await client.listPrompts?.(buildRequestOptions(ctx, 'list_prompts'))) ?? [];
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.prompt.list',
-                    namespace: ctx.namespace,
-                    duration_ms: Date.now() - started,
-                    success: true,
-                    promptCount: prompts.length,
-                });
-                return { success: true, data: serializeMCPResult(prompts) };
+                prompts = (await client.listPrompts?.(buildRequestOptions(ctx, 'list_prompts'))) ?? [];
+                ok = true;
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.prompt.list',
-                    namespace: ctx.namespace,
-                    duration_ms: Date.now() - started,
-                    success: false,
-                    error: message,
-                });
-                return { success: false, error: message };
+                errorText = error instanceof Error ? error.message : String(error);
             }
+            emitMcpEvent(ctx.onEvent, {
+                kind: 'mcp.prompt.list',
+                namespace: ctx.namespace,
+                duration_ms: Date.now() - started,
+                success: ok,
+                ...(ok ? { promptCount: prompts.length } : {}),
+                ...(errorText !== undefined ? { error: errorText } : {}),
+            });
+            await finishToolIntegrity(ctx, 'list_prompts', started, ok, errorText);
+            if (ok)
+                return { success: true, data: serializeMCPResult(prompts) };
+            return { success: false, error: errorText ?? 'list_prompts failed' };
         },
         getMetadata() {
             return {
@@ -298,46 +331,39 @@ function buildGetPromptTool(client, ctx) {
         async execute(params) {
             const { name, args } = paramsSchema.parse(params);
             const started = Date.now();
+            let ok = false;
+            let errorText;
+            let result;
             try {
-                const result = await client.getPrompt?.(name, args, buildRequestOptions(ctx, 'get_prompt'));
+                result = await client.getPrompt?.(name, args, buildRequestOptions(ctx, 'get_prompt'));
                 if (!result) {
-                    const msg = 'client does not implement getPrompt';
-                    emitMcpEvent(ctx.onEvent, {
-                        kind: 'mcp.prompt.get',
-                        namespace: ctx.namespace,
-                        promptName: name,
-                        duration_ms: Date.now() - started,
-                        success: false,
-                        error: msg,
-                    });
-                    return { success: false, error: msg };
+                    errorText = 'client does not implement getPrompt';
+                }
+                else {
+                    ok = true;
                 }
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.prompt.get',
-                    namespace: ctx.namespace,
-                    promptName: name,
-                    duration_ms: Date.now() - started,
-                    success: true,
-                });
-                const joinedText = flattenPromptMessages(result.messages);
-                const base = {
-                    success: true,
-                    data: serializeMCPResult(result),
-                };
-                return joinedText !== undefined ? { ...base, content: joinedText } : base;
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                emitMcpEvent(ctx.onEvent, {
-                    kind: 'mcp.prompt.get',
-                    namespace: ctx.namespace,
-                    promptName: name,
-                    duration_ms: Date.now() - started,
-                    success: false,
-                    error: message,
-                });
-                return { success: false, error: message };
+                errorText = error instanceof Error ? error.message : String(error);
             }
+            emitMcpEvent(ctx.onEvent, {
+                kind: 'mcp.prompt.get',
+                namespace: ctx.namespace,
+                promptName: name,
+                duration_ms: Date.now() - started,
+                success: ok,
+                ...(errorText !== undefined ? { error: errorText } : {}),
+            });
+            await finishToolIntegrity(ctx, 'get_prompt', started, ok, errorText);
+            if (!(ok && result)) {
+                return { success: false, error: errorText ?? 'get_prompt failed' };
+            }
+            const joinedText = flattenPromptMessages(result.messages);
+            const base = {
+                success: true,
+                data: serializeMCPResult(result),
+            };
+            return joinedText !== undefined ? { ...base, content: joinedText } : base;
         },
         getMetadata() {
             return {
@@ -476,17 +502,20 @@ export function serializeMCPResult(value) {
  * Tool names use the hypervisor's namespacing (@@mcp_{server}_{tool}) so
  * collisions across servers are impossible.
  *
+ * @deprecated Prefer `createToolsFromMcpClient` (Stage 5.1a). Kept for
+ *   AgentRuntime `mcpToolSource` compatibility.
+ *
  * @example
  * ```typescript
  * import { MCPHypervisor } from '@revealui/mcp'
  * import { discoverMCPTools } from '@revealui/ai'
  *
  * const hypervisor = MCPHypervisor.getInstance()
- * const tools = discoverMCPTools(hypervisor)
+ * const tools = discoverMCPTools(hypervisor, { onToolAudit })
  * agent.tools.push(...tools)
  * ```
  */
-export function discoverMCPTools(source) {
+export function discoverMCPTools(source, options) {
     return source.getAllTools().map(({ namespacedName, serverName, tool }) => {
         const zodSchema = jsonSchemaToZod(tool.inputSchema);
         const agentTool = {
@@ -496,19 +525,47 @@ export function discoverMCPTools(source) {
             async execute(params) {
                 // Validate params against the schema
                 const validated = zodSchema.parse(params);
+                const started = Date.now();
+                let toolSucceeded = false;
+                let payload;
+                let errorText;
                 try {
-                    const callResult = await source.callTool(serverName, tool.name, validated);
-                    return {
-                        success: true,
-                        data: serializeMCPResult(callResult),
-                    };
+                    payload = await source.callTool(serverName, tool.name, validated);
+                    toolSucceeded = true;
                 }
                 catch (error) {
+                    errorText = error instanceof Error ? error.message : String(error);
+                }
+                const event = {
+                    kind: 'mcp.tool.call',
+                    namespace: serverName,
+                    toolName: tool.name,
+                    duration_ms: Date.now() - started,
+                    success: toolSucceeded,
+                    ...(errorText !== undefined ? { error: errorText } : {}),
+                };
+                if (toolSucceeded) {
+                    // Integrity outside the RPC try so audit throws fail closed.
+                    if (options?.onToolAudit) {
+                        await options.onToolAudit(event);
+                    }
                     return {
-                        success: false,
-                        error: error instanceof Error ? error.message : String(error),
+                        success: true,
+                        data: serializeMCPResult(payload),
                     };
                 }
+                if (options?.onToolAudit) {
+                    try {
+                        await options.onToolAudit(event);
+                    }
+                    catch {
+                        // Prefer the tool failure over a secondary audit failure.
+                    }
+                }
+                return {
+                    success: false,
+                    error: errorText ?? 'Tool failed',
+                };
             },
             getMetadata() {
                 return { category: 'mcp', version: '1.0.0' };

package/dist/tools/mcp-sampling.d.ts

@@ -21,7 +21,7 @@
  *
  * const llm = new InferenceSnapsProvider({
  *   baseURL: 'http://localhost:9090/v1',
- *   model: 'gemma3',
+ *   model: 'nemotron-3-nano',
  * });
  *
  * const client = new McpClient({
@@ -29,8 +29,8 @@
  *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
  *   samplingHandler: createSamplingHandler({
  *     llm,
- *     defaultModel: 'gemma3',
- *     allowedModels: ['gemma3', 'deepseek-r1'],
+ *     defaultModel: 'nemotron-3-nano',
+ *     allowedModels: ['nemotron-3-nano', 'gemma4', 'gemma3'],
  *   }),
  * });
  * await client.connect();

package/dist/tools/mcp-sampling.js

@@ -21,7 +21,7 @@
  *
  * const llm = new InferenceSnapsProvider({
  *   baseURL: 'http://localhost:9090/v1',
- *   model: 'gemma3',
+ *   model: 'nemotron-3-nano',
  * });
  *
  * const client = new McpClient({
@@ -29,8 +29,8 @@
  *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
  *   samplingHandler: createSamplingHandler({
  *     llm,
- *     defaultModel: 'gemma3',
- *     allowedModels: ['gemma3', 'deepseek-r1'],
+ *     defaultModel: 'nemotron-3-nano',
+ *     allowedModels: ['nemotron-3-nano', 'gemma4', 'gemma3'],
  *   }),
  * });
  * await client.connect();

package/dist/tools/web/duck-duck-go.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duck-duck-go.d.ts","sourceRoot":"","sources":["../../../src/tools/web/duck-duck-go.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AA0BxF;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,QAAQ,CAAC,IAAI,gBAAgB;IAEvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAwD5E;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CA8CrE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,IA+C3B,CAAC"}
+{"version":3,"file":"duck-duck-go.d.ts","sourceRoot":"","sources":["../../../src/tools/web/duck-duck-go.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAqBxF;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,QAAQ,CAAC,IAAI,gBAAgB;IAEvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAwD5E;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CA8CrE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,IA+C3B,CAAC"}

package/dist/tools/web/duck-duck-go.js

@@ -8,11 +8,8 @@
  * WebSearchProvider interface used by future Tavily/Exa backends (P4-3).
  */
 import { z } from 'zod/v4';
+import { estimateTokens } from '../../internal/token-estimate.js';
 const DDG_API_URL = 'https://api.duckduckgo.com/';
-/** Approximate token count for a string (4 chars ≈ 1 token). */
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
 // =============================================================================
 // Provider
 // =============================================================================

package/dist/tools/web/exa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exa.d.ts","sourceRoot":"","sources":["../../../src/tools/web/exa.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAsBxF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAY,YAAW,iBAAiB;IACnD,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAKpB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA+C5E"}
+{"version":3,"file":"exa.d.ts","sourceRoot":"","sources":["../../../src/tools/web/exa.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAiBxF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAY,YAAW,iBAAiB;IACnD,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAKpB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA+C5E"}

package/dist/tools/web/exa.js

@@ -7,11 +7,8 @@
  *
  * @see https://docs.exa.ai/reference/search
  */
+import { estimateTokens } from '../../internal/token-estimate.js';
 const EXA_API_URL = 'https://api.exa.ai/search';
-/** Approximate token count for a string (4 chars ≈ 1 token). */
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
 /**
  * Exa neural search provider  -  BYOK, requires `EXA_API_KEY`.
  *

package/dist/tools/web/tavily.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../../src/tools/web/tavily.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAsBxF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAKpB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA0C5E"}
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../../src/tools/web/tavily.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAiBxF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAKpB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA0C5E"}

package/dist/tools/web/tavily.js

@@ -7,11 +7,8 @@
  *
  * @see https://docs.tavily.com/docs/tavily-api/rest_api
  */
+import { estimateTokens } from '../../internal/token-estimate.js';
 const TAVILY_API_URL = 'https://api.tavily.com/search';
-/** Approximate token count for a string (4 chars ≈ 1 token). */
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
 /**
  * Tavily search provider  -  BYOK, requires `TAVILY_API_KEY`.
  *