@revealui/ai 0.1.0

package/dist/orchestration/orchestrator.js

@@ -0,0 +1,174 @@
+/**
+ * Agent Orchestrator
+ *
+ * Coordinates multiple agents for complex tasks.
+ * Requires an LLM client to execute agent tasks via the runtime.
+ */
+import { AgentRuntime } from './runtime.js';
+export class AgentOrchestrator {
+    agents = new Map();
+    config;
+    runtime;
+    llmClient = null;
+    constructor(config = {}) {
+        this.config = {
+            maxConcurrentAgents: config.maxConcurrentAgents ?? 5,
+            taskTimeout: config.taskTimeout ?? 60000,
+            retryOnFailure: config.retryOnFailure ?? true,
+        };
+        this.runtime = new AgentRuntime({
+            timeout: this.config.taskTimeout || 60000,
+        });
+    }
+    /**
+     * Set the LLM client used for task execution.
+     * Must be called before delegateTask() or coordinateAgents().
+     */
+    setLLMClient(client) {
+        this.llmClient = client;
+    }
+    /**
+     * Get the current LLM client (if configured)
+     */
+    getLLMClient() {
+        return this.llmClient;
+    }
+    /**
+     * Register an agent
+     */
+    registerAgent(agent) {
+        if (this.agents.has(agent.id)) {
+            throw new Error(`Agent with ID "${agent.id}" is already registered`);
+        }
+        this.agents.set(agent.id, agent);
+    }
+    /**
+     * Unregister an agent
+     */
+    unregisterAgent(agentId) {
+        this.agents.delete(agentId);
+    }
+    /**
+     * Get an agent by ID
+     */
+    getAgent(agentId) {
+        return this.agents.get(agentId);
+    }
+    /**
+     * Get all registered agents
+     */
+    getAllAgents() {
+        return Array.from(this.agents.values());
+    }
+    /**
+     * Delegate a task to the most appropriate agent.
+     * Uses the runtime's agentic loop (LLM chat → tool calls → repeat).
+     */
+    async delegateTask(task, preferredAgentId) {
+        if (!this.llmClient) {
+            throw new Error('LLM client not configured. Call setLLMClient() before delegating tasks.');
+        }
+        let agent;
+        if (preferredAgentId) {
+            agent = this.agents.get(preferredAgentId);
+            if (!agent) {
+                throw new Error(`Agent "${preferredAgentId}" not found`);
+            }
+        }
+        else {
+            agent = this.findBestAgent(task);
+            if (!agent) {
+                throw new Error(`No suitable agent found for task type "${task.type}"`);
+            }
+        }
+        const result = await this.runtime.executeTask(agent, task, this.llmClient);
+        // Retry once on failure if configured
+        if (!result.success && this.config.retryOnFailure) {
+            return this.runtime.executeTask(agent, task, this.llmClient);
+        }
+        return result;
+    }
+    /**
+     * Find the best agent for a task.
+     *
+     * Routing priority:
+     * 1. Capability intersection — agent whose AgentConfig.capabilities overlaps
+     *    with task.requiredCapabilities (highest-overlap agent wins)
+     * 2. Tool-name substring match — agent has a tool whose name includes the
+     *    task type string (legacy fallback)
+     * 3. First registered agent — last-resort fallback
+     */
+    findBestAgent(task) {
+        // 1. Capability-based routing
+        if (task.requiredCapabilities && task.requiredCapabilities.length > 0) {
+            const required = new Set(task.requiredCapabilities);
+            let bestAgent;
+            let bestScore = 0;
+            for (const agent of this.agents.values()) {
+                const caps = agent.config?.capabilities ?? [];
+                const score = caps.filter((c) => required.has(c)).length;
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestAgent = agent;
+                }
+            }
+            if (bestAgent)
+                return bestAgent;
+        }
+        // 2. Tool-name substring fallback
+        for (const agent of this.agents.values()) {
+            const hasRelevantTool = agent.tools.some((tool) => tool.name.toLowerCase().includes(task.type.toLowerCase()));
+            if (hasRelevantTool)
+                return agent;
+        }
+        // 3. First agent
+        return this.agents.values().next().value;
+    }
+    /**
+     * Coordinate multiple agents for a complex task.
+     * Executes in batches up to maxConcurrentAgents, each agent receiving a subtask.
+     */
+    async coordinateAgents(task, agentIds) {
+        if (!this.llmClient) {
+            throw new Error('LLM client not configured. Call setLLMClient() before coordinating agents.');
+        }
+        const llmClient = this.llmClient;
+        const results = new Map();
+        const maxConcurrent = this.config.maxConcurrentAgents || 5;
+        for (let i = 0; i < agentIds.length; i += maxConcurrent) {
+            const batch = agentIds.slice(i, i + maxConcurrent);
+            const batchPromises = [];
+            for (const agentId of batch) {
+                const agent = this.agents.get(agentId);
+                if (!agent) {
+                    results.set(agentId, {
+                        success: false,
+                        error: `Agent "${agentId}" not found`,
+                    });
+                    continue;
+                }
+                // Create agent-specific subtask
+                const subtask = {
+                    ...task,
+                    id: `${task.id}-${agentId}`,
+                    description: `[Agent: ${agent.name}] ${task.description}`,
+                };
+                batchPromises.push(this.runtime
+                    .executeTask(agent, subtask, llmClient)
+                    .then((result) => [agentId, result])
+                    .catch((error) => [
+                    agentId,
+                    {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                ]));
+            }
+            const batchResults = await Promise.all(batchPromises);
+            for (const [agentId, result] of batchResults) {
+                results.set(agentId, result);
+            }
+        }
+        return results;
+    }
+}

package/dist/orchestration/runtime.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Agent Runtime
+ *
+ * Executes agent tasks with tool execution, memory management, and error handling
+ */
+import type { LLMClient } from '../llm/client.js';
+import type { AgentSkillProvider } from '../skills/integration/agent-skill-provider.js';
+import type { MCPToolSource } from '../tools/mcp-adapter.js';
+import type { Agent, AgentResult, Task } from './agent.js';
+/**
+ * Controls how much of the model's token budget is allocated to internal reasoning.
+ * Applies to Anthropic Claude only — ignored by other providers.
+ *
+ * | Level   | Budget (tokens) | Use case                          |
+ * |---------|-----------------|-----------------------------------|
+ * | off     | 0               | Disabled (default)                |
+ * | minimal | 512             | Simple tasks, cost-sensitive      |
+ * | low     | 2 048           | Moderate complexity               |
+ * | medium  | 8 000           | Multi-step reasoning              |
+ * | high    | 16 000          | Complex planning                  |
+ * | xhigh   | 31 999          | Maximum depth (expensive)         |
+ */
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export interface RuntimeConfig {
+    maxIterations?: number;
+    timeout?: number;
+    retryOnError?: boolean;
+    maxRetries?: number;
+    /** Enable prompt caching for Anthropic (90% cost reduction on cache hits) */
+    enableCache?: boolean;
+    /**
+     * Extended thinking depth (Anthropic only).
+     * Allocates token budget for internal reasoning before each response.
+     * Defaults to 'off'. Trade cost for quality on complex tasks.
+     */
+    thinkingLevel?: ThinkingLevel;
+    /**
+     * Optional MCP Hypervisor (or any MCPToolSource). When provided, tools from
+     * all healthy MCP servers are merged into the agent's tool set before each
+     * task execution. Pass an MCPHypervisor from @revealui/mcp.
+     */
+    mcpToolSource?: MCPToolSource;
+    /**
+     * Optional skill provider. When set, activated skills are injected into the
+     * system prompt before the first LLM call, giving the agent contextual
+     * instructions from the matching skill packages.
+     */
+    skillProvider?: AgentSkillProvider;
+}
+export declare class AgentRuntime {
+    protected config: RuntimeConfig;
+    private taskQueue;
+    private executingTasks;
+    private isShuttingDown;
+    constructor(config?: RuntimeConfig);
+    /**
+     * Execute a task with an agent
+     */
+    executeTask(agent: Agent, task: Task, llmClient: LLMClient): Promise<AgentResult>;
+    private runTask;
+    /**
+     * Add task to queue
+     */
+    enqueueTask(task: Task): void;
+    /**
+     * Process task queue
+     */
+    processQueue(agent: Agent, llmClient: LLMClient): Promise<AgentResult[]>;
+    /**
+     * Cleanup runtime resources - cancel executing tasks and clear queue
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get runtime status
+     */
+    getStatus(): {
+        isShuttingDown: boolean;
+        queuedTasks: number;
+        executingTasks: number;
+    };
+}
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +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,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAA;AAGvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAG5D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAA;AAWnF,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAA;CACnC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAA;IAC/B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,cAAc,CAAQ;gBAElB,MAAM,GAAE,aAAkB;IAmBtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IAoKrB;;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,CAAA;QACvB,WAAW,EAAE,MAAM,CAAA;QACnB,cAAc,EAAE,MAAM,CAAA;KACvB;CAOF"}

package/dist/orchestration/runtime.js

@@ -0,0 +1,251 @@
+/**
+ * Agent Runtime
+ *
+ * Executes agent tasks with tool execution, memory management, and error handling
+ */
+import { registerCleanupHandler } from '@revealui/core/monitoring';
+import { z } from 'zod/v4';
+import { ToolCallDeduplicator } from '../tools/deduplicator.js';
+import { discoverMCPTools } from '../tools/mcp-adapter.js';
+import { createWebSearchTool } from '../tools/web/duck-duck-go.js';
+const THINKING_BUDGETS = {
+    off: 0,
+    minimal: 512,
+    low: 2048,
+    medium: 8000,
+    high: 16000,
+    xhigh: 31999,
+};
+export class AgentRuntime {
+    config;
+    taskQueue = [];
+    executingTasks = new Map();
+    isShuttingDown = false;
+    constructor(config = {}) {
+        this.config = {
+            maxIterations: config.maxIterations ?? 10,
+            timeout: config.timeout ?? 60000, // 60 seconds
+            retryOnError: config.retryOnError ?? true,
+            maxRetries: config.maxRetries ?? 3,
+            enableCache: config.enableCache ?? true, // Enable by default for cost savings
+            mcpToolSource: config.mcpToolSource,
+        };
+        // Register cleanup handler
+        registerCleanupHandler(`ai-runtime-${Date.now()}`, () => this.cleanup(), 'Cleanup AI agent runtime tasks', 80);
+    }
+    /**
+     * Execute a task with an agent
+     */
+    async executeTask(agent, task, llmClient) {
+        const startTime = Date.now();
+        // Check if task is already executing
+        const existingExecution = this.executingTasks.get(task.id);
+        if (existingExecution) {
+            return existingExecution;
+        }
+        // Create execution promise
+        const execution = this.runTask(agent, task, llmClient, startTime);
+        this.executingTasks.set(task.id, execution);
+        try {
+            const result = await execution;
+            return result;
+        }
+        finally {
+            this.executingTasks.delete(task.id);
+        }
+    }
+    async runTask(agent, task, llmClient, startTime) {
+        const toolResults = [];
+        const deduplicator = new ToolCallDeduplicator();
+        let iterations = 0;
+        // Merge MCP-discovered tools (from healthy servers) into the agent's tool set
+        const mcpTools = this.config.mcpToolSource ? discoverMCPTools(this.config.mcpToolSource) : [];
+        // Swap in a custom WebSearchProvider if the agent config specifies one (P4-3)
+        const customProvider = agent.config?.webSearchProvider;
+        let baseTools;
+        if (customProvider) {
+            const customSearchTool = createWebSearchTool(customProvider);
+            baseTools = agent.tools.map((t) => (t.name === 'web_search' ? customSearchTool : t));
+        }
+        else {
+            baseTools = agent.tools;
+        }
+        const allTools = mcpTools.length > 0 ? [...baseTools, ...mcpTools] : baseTools;
+        let messages = [
+            {
+                role: 'system',
+                content: agent.instructions,
+                // Cache agent instructions for cost savings (Anthropic only)
+                cacheControl: this.config.enableCache ? { type: 'ephemeral' } : undefined,
+            },
+            {
+                role: 'user',
+                content: task.description,
+            },
+        ];
+        // Inject activated skill instructions into the system prompt.
+        if (this.config.skillProvider) {
+            const { messages: augmented } = await this.config.skillProvider.injectSkillInstructions(messages, { taskDescription: task.description });
+            messages = augmented;
+        }
+        try {
+            while (iterations < (this.config.maxIterations || 10)) {
+                iterations++;
+                // Check timeout
+                if (Date.now() - startTime > (this.config.timeout || 60000)) {
+                    return {
+                        success: false,
+                        error: 'Task execution timeout',
+                        toolResults,
+                        metadata: {
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
+                }
+                // Resolve thinking budget if a level is configured
+                const thinkingBudget = this.config.thinkingLevel && this.config.thinkingLevel !== 'off'
+                    ? THINKING_BUDGETS[this.config.thinkingLevel]
+                    : undefined;
+                // Get LLM response (with caching for agent instructions and tools)
+                const response = await llmClient.chat(messages, {
+                    tools: allTools.map((tool) => ({
+                        type: 'function',
+                        function: {
+                            name: tool.name,
+                            description: tool.description,
+                            parameters: z.toJSONSchema(tool.parameters),
+                        },
+                    })),
+                    enableCache: this.config.enableCache,
+                    thinkingBudget,
+                });
+                // Add assistant response to messages
+                messages.push({
+                    role: 'assistant',
+                    content: response.content,
+                    toolCalls: response.toolCalls || [],
+                });
+                // If no tool calls, task is complete
+                if (!response.toolCalls || response.toolCalls.length === 0) {
+                    return {
+                        success: true,
+                        output: response.content,
+                        toolResults,
+                        metadata: {
+                            executionTime: Date.now() - startTime,
+                            tokensUsed: response.usage?.totalTokens || 0,
+                        },
+                    };
+                }
+                // Execute tool calls
+                for (const toolCall of response.toolCalls) {
+                    const tool = allTools.find((t) => t.name === toolCall.function.name);
+                    if (!tool) {
+                        toolResults.push({
+                            success: false,
+                            error: `Tool "${toolCall.function.name}" not found`,
+                        });
+                        continue;
+                    }
+                    try {
+                        const params = JSON.parse(toolCall.function.arguments);
+                        // Return cached result for duplicate tool calls within this run
+                        const cached = deduplicator.isDuplicate(tool.name, params)
+                            ? deduplicator.getResult(tool.name, params)
+                            : undefined;
+                        const result = cached ?? (await tool.execute(params));
+                        if (!cached)
+                            deduplicator.record(tool.name, params, result);
+                        toolResults.push(result);
+                        // Add tool result to messages.
+                        // Use result.content (LLM-optimized summary) when available;
+                        // otherwise serialize the full result so the model has context.
+                        messages.push({
+                            role: 'tool',
+                            content: result.content ?? JSON.stringify(result.data ?? result),
+                            toolCallId: toolCall.id,
+                        });
+                    }
+                    catch (error) {
+                        toolResults.push({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+            return {
+                success: false,
+                error: 'Maximum iterations reached',
+                toolResults,
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                toolResults,
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                },
+            };
+        }
+    }
+    /**
+     * Add task to queue
+     */
+    enqueueTask(task) {
+        this.taskQueue.push(task);
+    }
+    /**
+     * Process task queue
+     */
+    async processQueue(agent, llmClient) {
+        const results = [];
+        while (this.taskQueue.length > 0) {
+            const task = this.taskQueue.shift();
+            if (task) {
+                const result = await this.executeTask(agent, task, llmClient);
+                results.push(result);
+            }
+        }
+        return results;
+    }
+    /**
+     * Cleanup runtime resources - cancel executing tasks and clear queue
+     */
+    async cleanup() {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        // Clear task queue
+        this.taskQueue = [];
+        // Wait for executing tasks to complete (with timeout)
+        if (this.executingTasks.size > 0) {
+            const timeout = new Promise((resolve) => {
+                setTimeout(() => resolve(), 10_000); // 10 second timeout
+            });
+            const allTasks = Promise.all(Array.from(this.executingTasks.values()).map((task) => task.catch(() => {
+                /* Ignore errors during cleanup */
+            }))).then(() => {
+                // All tasks completed
+            });
+            await Promise.race([allTasks, timeout]);
+        }
+        // Clear executing tasks map
+        this.executingTasks.clear();
+    }
+    /**
+     * Get runtime status
+     */
+    getStatus() {
+        return {
+            isShuttingDown: this.isShuttingDown,
+            queuedTasks: this.taskQueue.length,
+            executingTasks: this.executingTasks.size,
+        };
+    }
+}

package/dist/orchestration/streaming-runtime.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Streaming Agent Runtime
+ *
+ * Extends AgentRuntime with SSE-compatible streaming via LLMClient.stream().
+ * Each yielded AgentStreamChunk maps to one SSE event.
+ *
+ * AnythingLLM lesson: SSE is the correct approach for unidirectional LLM output.
+ * EventSource is not used client-side because it doesn't support POST — use fetch + ReadableStream.
+ */
+import type { LLMClient } from '../llm/client.js';
+import type { ToolResult } from '../tools/base.js';
+import type { Agent, Task } from './agent.js';
+import { AgentRuntime, type RuntimeConfig } from './runtime.js';
+export interface AgentStreamChunk {
+    type: 'text' | 'tool_call_start' | 'tool_call_result' | 'error' | 'done';
+    content?: string;
+    toolCall?: {
+        name: string;
+        arguments: string;
+    };
+    toolResult?: ToolResult;
+    error?: string;
+    metadata?: {
+        tokensUsed?: number;
+        executionTime?: number;
+    };
+}
+export declare class StreamingAgentRuntime extends AgentRuntime {
+    constructor(config?: RuntimeConfig);
+    /**
+     * Stream a task execution, yielding typed events as they occur.
+     * Accepts an AbortSignal — on abort, emits an error event and stops.
+     */
+    streamTask(agent: Agent, task: Task, llmClient: LLMClient, signal?: AbortSignal): AsyncGenerator<AgentStreamChunk>;
+}
+//# sourceMappingURL=streaming-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/streaming-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAA;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,aAAa,CAAC,EAAE,MAAM,CAAA;KACvB,CAAA;CACF;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,GAAE,aAAkB;IAItC;;;OAGG;IACI,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,gBAAgB,CAAC;CA+KpC"}