@revealui/ai 0.1.0

package/dist/tools/mcp-adapter.js

@@ -0,0 +1,152 @@
+/**
+ * MCP Tool Adapter
+ *
+ * Bridges MCP (Model Context Protocol) servers to the tool system
+ */
+import { z } from 'zod/v4';
+/**
+ * Create a Tool from an MCP tool definition
+ */
+export function createToolFromMCP(mcpTool, mcpClient) {
+    // Convert JSON Schema to Zod schema (simplified)
+    const zodSchema = jsonSchemaToZod(mcpTool.inputSchema);
+    return {
+        name: mcpTool.name,
+        description: mcpTool.description,
+        parameters: zodSchema,
+        execute: async (params) => {
+            try {
+                const result = await mcpClient.callTool(mcpTool.name, params);
+                return {
+                    success: true,
+                    data: result,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+/**
+ * Register all MCP tools in the registry
+ */
+export async function registerMCPTools(mcpClient, registry) {
+    const tools = await mcpClient.listTools();
+    for (const mcpTool of tools) {
+        const tool = createToolFromMCP(mcpTool, mcpClient);
+        registry.register(tool);
+    }
+}
+/**
+ * Serialize an MCP tool result safely:
+ * - bigint values → string (JSON.stringify fails on bigint)
+ * - Circular references → replaced with "[Circular]"
+ */
+export function serializeMCPResult(value) {
+    const seen = new WeakSet();
+    function replacer(_key, val) {
+        if (typeof val === 'bigint')
+            return val.toString();
+        if (typeof val === 'object' && val !== null) {
+            if (seen.has(val))
+                return '[Circular]';
+            seen.add(val);
+        }
+        return val;
+    }
+    return JSON.parse(JSON.stringify(value, replacer));
+}
+/**
+ * Discover all tools from a running MCPHypervisor (or any MCPToolSource)
+ * and return them as RevealUI Tool instances.
+ *
+ * Tool names use the hypervisor's namespacing (@@mcp_{server}_{tool}) so
+ * collisions across servers are impossible.
+ *
+ * @example
+ * ```typescript
+ * import { MCPHypervisor } from '@revealui/mcp'
+ * import { discoverMCPTools } from '@revealui/ai'
+ *
+ * const hypervisor = MCPHypervisor.getInstance()
+ * const tools = discoverMCPTools(hypervisor)
+ * agent.tools.push(...tools)
+ * ```
+ */
+export function discoverMCPTools(source) {
+    return source.getAllTools().map(({ namespacedName, serverName, tool }) => {
+        const zodSchema = jsonSchemaToZod(tool.inputSchema);
+        const agentTool = {
+            name: namespacedName,
+            description: tool.description,
+            parameters: zodSchema,
+            async execute(params) {
+                // Validate params against the schema
+                const validated = zodSchema.parse(params);
+                try {
+                    const callResult = await source.callTool(serverName, tool.name, validated);
+                    return {
+                        success: true,
+                        data: serializeMCPResult(callResult),
+                    };
+                }
+                catch (error) {
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+            getMetadata() {
+                return { category: 'mcp', version: '1.0.0' };
+            },
+        };
+        return agentTool;
+    });
+}
+/**
+ * Convert JSON Schema to Zod schema (simplified version)
+ * For production, use a proper library like json-schema-to-zod
+ */
+function jsonSchemaToZod(schema) {
+    if (schema.type !== 'object') {
+        return z.unknown();
+    }
+    const shape = {};
+    if (schema.properties) {
+        for (const [key, prop] of Object.entries(schema.properties)) {
+            const propSchema = prop;
+            let zodType;
+            switch (propSchema.type) {
+                case 'string':
+                    zodType = z.string();
+                    break;
+                case 'number':
+                case 'integer':
+                    zodType = z.number();
+                    break;
+                case 'boolean':
+                    zodType = z.boolean();
+                    break;
+                case 'array':
+                    zodType = z.array(z.unknown());
+                    break;
+                case 'object':
+                    zodType = z.record(z.string(), z.unknown());
+                    break;
+                default:
+                    zodType = z.unknown();
+            }
+            // Make optional if not in required array
+            if (!schema.required?.includes(key)) {
+                zodType = zodType.optional();
+            }
+            shape[key] = zodType;
+        }
+    }
+    return z.object(shape);
+}

package/dist/tools/memory/index.d.ts

@@ -0,0 +1,3 @@
+export type { StoreMemoryParams } from './store-memory.js';
+export { createStoreMemoryTool } from './store-memory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/memory/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/tools/memory/index.js

@@ -0,0 +1 @@
+export { createStoreMemoryTool } from './store-memory.js';

package/dist/tools/memory/store-memory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Store Memory Tool
+ *
+ * Explicit memory storage tool that agents must call to persist information
+ * to long-term episodic memory. Agents are never auto-enrolled into memory
+ * writes — they must invoke this tool with a clear reason.
+ *
+ * GDPR rationale: Requiring explicit intent aligns with the data minimisation
+ * principle (GDPR Art. 5(1)(c)) and purpose limitation principle (Art. 5(1)(b)).
+ * Only information an agent actively decides to store is persisted.
+ *
+ * See AgentMemoryIntegrationConfig.requireExplicitStore for the gate that
+ * blocks auto-writes at the integration layer.
+ */
+import { z } from 'zod/v4';
+import type { EpisodicMemory } from '../../memory/stores/episodic-memory.js';
+import type { Tool } from '../base.js';
+declare const StoreMemoryParamsSchema: z.ZodObject<{
+    content: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type StoreMemoryParams = z.infer<typeof StoreMemoryParamsSchema>;
+/**
+ * Create an explicit store-memory tool bound to an EpisodicMemory instance.
+ *
+ * Agents must call this tool to persist information. Auto-store via
+ * AgentMemoryIntegration.storeContext() is blocked when
+ * `requireExplicitStore: true` (default).
+ *
+ * @example
+ * ```typescript
+ * const tool = createStoreMemoryTool(episodicMemory, agent.id)
+ * agent.tools.push(tool)
+ * ```
+ */
+export declare function createStoreMemoryTool(memory: EpisodicMemory, agentId: string): Tool;
+export {};
+//# sourceMappingURL=store-memory.d.ts.map

package/dist/tools/memory/store-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-memory.d.ts","sourceRoot":"","sources":["../../../src/tools/memory/store-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAA;AAC5E,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,YAAY,CAAA;AAElD,QAAA,MAAM,uBAAuB;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkEnF"}

package/dist/tools/memory/store-memory.js

@@ -0,0 +1,94 @@
+/**
+ * Store Memory Tool
+ *
+ * Explicit memory storage tool that agents must call to persist information
+ * to long-term episodic memory. Agents are never auto-enrolled into memory
+ * writes — they must invoke this tool with a clear reason.
+ *
+ * GDPR rationale: Requiring explicit intent aligns with the data minimisation
+ * principle (GDPR Art. 5(1)(c)) and purpose limitation principle (Art. 5(1)(b)).
+ * Only information an agent actively decides to store is persisted.
+ *
+ * See AgentMemoryIntegrationConfig.requireExplicitStore for the gate that
+ * blocks auto-writes at the integration layer.
+ */
+import { z } from 'zod/v4';
+const StoreMemoryParamsSchema = z.object({
+    content: z.string().min(1).describe('The information to store in long-term memory'),
+    tags: z.array(z.string()).optional().describe('Optional tags to categorize the memory'),
+    reason: z.string().min(1).describe('Why this information should be remembered across sessions'),
+});
+/**
+ * Create an explicit store-memory tool bound to an EpisodicMemory instance.
+ *
+ * Agents must call this tool to persist information. Auto-store via
+ * AgentMemoryIntegration.storeContext() is blocked when
+ * `requireExplicitStore: true` (default).
+ *
+ * @example
+ * ```typescript
+ * const tool = createStoreMemoryTool(episodicMemory, agent.id)
+ * agent.tools.push(tool)
+ * ```
+ */
+export function createStoreMemoryTool(memory, agentId) {
+    return {
+        name: 'store_memory',
+        description: 'Explicitly store important information in long-term memory for future sessions. ' +
+            'Only call this when information is genuinely valuable to retain. ' +
+            'Provide a clear reason — this is required for privacy compliance.',
+        parameters: StoreMemoryParamsSchema,
+        async execute(params) {
+            const { content, tags, reason } = StoreMemoryParamsSchema.parse(params);
+            try {
+                const memoryId = `explicit-${agentId}-${Date.now()}`;
+                const memoryEntry = {
+                    id: memoryId,
+                    version: 1,
+                    content,
+                    type: 'fact',
+                    source: {
+                        type: 'agent',
+                        id: agentId,
+                        confidence: 1,
+                    },
+                    metadata: {
+                        importance: 0.7,
+                        agentId,
+                        storeReason: reason,
+                        explicit: true,
+                        ...(tags && tags.length > 0 && { tags }),
+                    },
+                    createdAt: new Date().toISOString(),
+                    accessedAt: new Date().toISOString(),
+                    accessCount: 0,
+                    verified: false,
+                };
+                await memory.add(memoryEntry);
+                await memory.save();
+                return {
+                    success: true,
+                    data: {
+                        stored: true,
+                        memoryId,
+                        message: `Memory stored: "${content.length > 80 ? `${content.substring(0, 80)}…` : content}"`,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to store memory: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+        getMetadata() {
+            return {
+                category: 'memory',
+                version: '1.0.0',
+                author: 'RevealUI',
+                gdprAligned: true,
+            };
+        },
+    };
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition } from '../llm/providers/base.js';
+import type { Tool, ToolResult } from './base.js';
+export declare class ToolRegistry {
+    private tools;
+    register(tool: Tool): void;
+    unregister(name: string): void;
+    get(name: string): Tool | undefined;
+    getAll(): Tool[];
+    has(name: string): boolean;
+    getToolDefinitions(): ToolDefinition[];
+    execute(name: string, params: unknown): Promise<ToolResult>;
+}
+export declare const globalToolRegistry: ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEjD,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA+B;IAE5C,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAO1B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAInC,MAAM,IAAI,IAAI,EAAE;IAIhB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,kBAAkB,IAAI,cAAc,EAAE;IAWhC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CAgBlE;AAED,eAAO,MAAM,kBAAkB,cAAqB,CAAA"}

package/dist/tools/registry.js

@@ -0,0 +1,48 @@
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool with name "${tool.name}" is already registered`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+    unregister(name) {
+        this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    getToolDefinitions() {
+        return Array.from(this.tools.values()).map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters.toJSONSchema(), // Native Zod v4 method
+            },
+        }));
+    }
+    async execute(name, params) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return { success: false, error: `Tool "${name}" not found` };
+        }
+        try {
+            const validatedParams = tool.parameters.parse(params);
+            return await tool.execute(validatedParams);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Parameter validation failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}
+export const globalToolRegistry = new ToolRegistry();

package/dist/tools/ticket-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ticket Mutation Tools
+ *
+ * Tools that allow an agent to update ticket state as it works —
+ * closing a ticket when done, moving it between columns, and writing
+ * its results back as a comment.
+ *
+ * These are injected by createTicketTools() and are always paired with
+ * CMS tools so agents can act on content AND report back through the ticket.
+ */
+import type { Tool } from './base.js';
+/**
+ * Minimal interface for ticket mutations an agent can perform.
+ * Matches the subset of ticketQueries used in the tickets route.
+ */
+export interface TicketMutationClient {
+    updateTicket(ticketId: string, data: {
+        status?: string;
+        columnId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        status: string;
+    } | null>;
+    createComment(ticketId: string, body: Record<string, unknown>): Promise<{
+        id: string;
+        ticketId: string;
+    } | null | undefined>;
+}
+export declare function createTicketTools(ticketId: string, client: TicketMutationClient): Tool[];
+//# sourceMappingURL=ticket-tools.d.ts.map

package/dist/tools/ticket-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-tools.d.ts","sourceRoot":"","sources":["../../src/tools/ticket-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAA;AAEjD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,GACA,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IAEjD,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;CAChE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,EAAE,CAgExF"}

package/dist/tools/ticket-tools.js

@@ -0,0 +1,74 @@
+/**
+ * Ticket Mutation Tools
+ *
+ * Tools that allow an agent to update ticket state as it works —
+ * closing a ticket when done, moving it between columns, and writing
+ * its results back as a comment.
+ *
+ * These are injected by createTicketTools() and are always paired with
+ * CMS tools so agents can act on content AND report back through the ticket.
+ */
+import { z } from 'zod/v4';
+export function createTicketTools(ticketId, client) {
+    const updateStatusTool = {
+        name: 'update_ticket_status',
+        description: 'Update the status of the current ticket. Call this when work is complete (status="done") or if you cannot proceed (status="blocked"). Valid statuses: open, in_progress, done, blocked, cancelled.',
+        parameters: z.object({
+            status: z.enum(['open', 'in_progress', 'done', 'blocked', 'cancelled']),
+            reason: z.string().optional().describe('Brief reason for the status change'),
+        }),
+        async execute(params) {
+            const { status, reason } = params;
+            try {
+                const metadata = reason ? { agentStatusReason: reason } : {};
+                const ticket = await client.updateTicket(ticketId, { status, metadata });
+                if (!ticket) {
+                    return { success: false, error: `Ticket ${ticketId} not found` };
+                }
+                return {
+                    success: true,
+                    data: { ticketId: ticket.id, status: ticket.status },
+                    metadata: { message: `Ticket status updated to "${status}"` },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to update ticket status: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+    };
+    const addCommentTool = {
+        name: 'add_ticket_comment',
+        description: 'Write a comment on the current ticket. Use this to report what you did, what changed in the CMS, or why you could not complete the task.',
+        parameters: z.object({
+            text: z.string().min(1).describe('The comment text to add to the ticket'),
+        }),
+        async execute(params) {
+            const { text } = params;
+            try {
+                const body = {
+                    type: 'doc',
+                    content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
+                };
+                const comment = await client.createComment(ticketId, body);
+                if (!comment) {
+                    return { success: false, error: 'Failed to create comment' };
+                }
+                return {
+                    success: true,
+                    data: { commentId: comment.id, ticketId: comment.ticketId },
+                    metadata: { message: 'Comment added to ticket' },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to add comment: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+    };
+    return [updateStatusTool, addCommentTool];
+}

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

@@ -0,0 +1,52 @@
+/**
+ * DuckDuckGo Web Search Tool
+ *
+ * Uses the DuckDuckGo Instant Answer API (no API key required).
+ * Returns structured results suitable for agent consumption.
+ *
+ * Part of the WebSearch skill family — see types.ts for the
+ * WebSearchProvider interface used by future Tavily/Exa backends (P4-3).
+ */
+import type { Tool } from '../base.js';
+import type { WebSearchProvider, WebSearchResponse } from './types.js';
+/**
+ * DuckDuckGo search provider — zero-config, no API key required.
+ *
+ * Uses the DuckDuckGo Instant Answer API to retrieve the abstract summary
+ * and related topics for a query.
+ */
+export declare class DuckDuckGoProvider implements WebSearchProvider {
+    readonly name = "duckduckgo";
+    search(query: string, maxResults: number): Promise<WebSearchResponse>;
+}
+/**
+ * Factory that creates a `web_search` tool backed by any WebSearchProvider.
+ *
+ * The singleton `webSearchTool` uses DuckDuckGo. Pass a TavilyProvider or
+ * ExaProvider here to get the same tool with a premium BYOK backend.
+ *
+ * @example
+ * ```typescript
+ * import { createWebSearchTool, TavilyProvider } from '@revealui/ai'
+ *
+ * const tool = createWebSearchTool(new TavilyProvider(apiKey))
+ * agent.tools.push(tool)
+ * ```
+ */
+export declare function createWebSearchTool(provider: WebSearchProvider): Tool;
+/**
+ * Web search tool backed by DuckDuckGo (zero-config).
+ *
+ * Register this on any agent that needs live web access. Requires no
+ * API key — backed by the DuckDuckGo Instant Answer API.
+ *
+ * @example
+ * ```typescript
+ * import { webSearchTool } from '@revealui/ai'
+ *
+ * agent.tools.push(webSearchTool)
+ * // Agent can now call web_search({ query: '...', maxResults: 5 })
+ * ```
+ */
+export declare const webSearchTool: Tool;
+//# sourceMappingURL=duck-duck-go.d.ts.map

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

@@ -0,0 +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,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAA;AAiCvF;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,QAAQ,CAAC,IAAI,gBAAe;IAEtB,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,CAAA"}