@revealui/ai 0.1.0

package/dist/observability/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @revealui/ai - Observability Types
+ *
+ * Event types for tracking agent operations, decisions, tool calls, and LLM usage.
+ */
+/**
+ * Base event type for all agent operations
+ */
+export interface AgentEvent {
+    timestamp: number;
+    eventType: 'decision' | 'tool_call' | 'llm_call' | 'error';
+    agentId: string;
+    sessionId: string;
+    taskId?: string;
+}
+/**
+ * Decision event - tracks agent reasoning and tool selection
+ */
+export interface DecisionEvent extends AgentEvent {
+    eventType: 'decision';
+    reasoning: string;
+    chosenTool?: string;
+    confidence?: number;
+    context?: Record<string, unknown>;
+}
+/**
+ * Tool call event - tracks tool invocations
+ */
+export interface ToolCallEvent extends AgentEvent {
+    eventType: 'tool_call';
+    toolName: string;
+    params: Record<string, unknown>;
+    result?: unknown;
+    durationMs: number;
+    success: boolean;
+    errorMessage?: string;
+}
+/**
+ * LLM call event - tracks language model usage
+ */
+export interface LLMCallEvent extends AgentEvent {
+    eventType: 'llm_call';
+    provider: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    durationMs: number;
+    cost?: number;
+    cacheHit?: boolean;
+}
+/**
+ * Error event - tracks failures and exceptions
+ */
+export interface ErrorEvent extends AgentEvent {
+    eventType: 'error';
+    message: string;
+    stack?: string;
+    recoverable: boolean;
+    errorCode?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Union type of all event types
+ */
+export type AnyAgentEvent = DecisionEvent | ToolCallEvent | LLMCallEvent | ErrorEvent;
+/**
+ * Event filter for querying events
+ */
+export interface EventFilter {
+    agentId?: string;
+    sessionId?: string;
+    taskId?: string;
+    eventType?: AgentEvent['eventType'];
+    startTime?: number;
+    endTime?: number;
+}
+/**
+ * Tool-specific metrics
+ */
+export interface ToolMetrics {
+    totalCalls: number;
+    successCount: number;
+    failureCount: number;
+    averageDurationMs: number;
+    lastUsed: number;
+}
+/**
+ * LLM-specific metrics
+ */
+export interface LLMMetrics {
+    totalCalls: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalCost: number;
+    averageDurationMs: number;
+    cacheHitRate: number;
+    modelUsage: Record<string, number>;
+}
+/**
+ * Aggregated agent metrics
+ */
+export interface AgentMetrics {
+    totalDecisions: number;
+    totalToolCalls: number;
+    totalLLMCalls: number;
+    totalErrors: number;
+    averageDecisionTime: number;
+    successRate: number;
+    errorRate: number;
+    toolMetrics: Map<string, ToolMetrics>;
+    llmMetrics: LLMMetrics;
+    uptime: number;
+    lastActivity: number;
+}
+/**
+ * Metrics summary for display
+ */
+export interface MetricsSummary {
+    totalEvents: number;
+    eventsByType: Record<string, number>;
+    activeAgents: number;
+    activeSessions: number;
+    totalTokensUsed: number;
+    totalCost: number;
+    averageSuccessRate: number;
+    timeRange: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Storage backend interface
+ */
+export interface EventStorage {
+    save(events: AnyAgentEvent[]): Promise<void>;
+    load(filter?: EventFilter): Promise<AnyAgentEvent[]>;
+    clear(): Promise<void>;
+    count(filter?: EventFilter): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"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"}

package/dist/observability/types.js

@@ -0,0 +1,6 @@
+/**
+ * @revealui/ai - Observability Types
+ *
+ * Event types for tracking agent operations, decisions, tool calls, and LLM usage.
+ */
+export {};

package/dist/orchestration/agent.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent Interface
+ *
+ * Defines the structure for AI agents
+ */
+import type { EpisodicMemory } from '../memory/stores/episodic-memory.js';
+import type { Tool, ToolResult } from '../tools/base.js';
+import type { WebSearchProvider } from '../tools/web/types.js';
+/**
+ * Per-agent configuration. Extends the base Agent interface with optional
+ * provider overrides and capability declarations.
+ *
+ * Pass as `agent.config` to opt into pluggable search backends (P4-3) and
+ * capability-based task routing (A3).
+ */
+export interface AgentConfig {
+    /**
+     * Pluggable web search backend.
+     * Defaults to DuckDuckGo (zero-config) when not set.
+     * Set to a TavilyProvider or ExaProvider for higher-quality BYOK search.
+     */
+    webSearchProvider?: WebSearchProvider;
+    /**
+     * Capability tags used by AgentOrchestrator.findBestAgent() for routing.
+     * Example: ['cms', 'search', 'ticket', 'summarize']
+     */
+    capabilities?: string[];
+}
+export interface Task {
+    id: string;
+    type: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    priority?: number;
+    deadline?: Date;
+    /**
+     * Capability tags required to handle this task.
+     * AgentOrchestrator.findBestAgent() prefers agents whose
+     * AgentConfig.capabilities intersect with this set.
+     * Falls back to tool-name matching when no intersection is found.
+     */
+    requiredCapabilities?: string[];
+}
+export interface AgentResult {
+    success: boolean;
+    output?: string;
+    toolResults?: ToolResult[];
+    error?: string;
+    metadata?: {
+        executionTime?: number;
+        tokensUsed?: number;
+        cost?: number;
+    };
+}
+export interface Agent {
+    /**
+     * Unique agent ID
+     */
+    id: string;
+    /**
+     * Agent name
+     */
+    name: string;
+    /**
+     * Agent instructions (system prompt)
+     */
+    instructions: string;
+    /**
+     * Available tools
+     */
+    tools: Tool[];
+    /**
+     * Memory system (optional — agents without memory skip episodic recall)
+     */
+    memory?: EpisodicMemory;
+    /**
+     * Per-agent configuration (provider overrides, capability declarations).
+     */
+    config?: AgentConfig;
+    /**
+     * Get agent context
+     */
+    getContext(): AgentContext;
+}
+export interface AgentContext {
+    agentId: string;
+    userId?: string;
+    sessionId?: string;
+    currentTask?: Task;
+    recentActions?: AgentAction[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentAction {
+    type: 'tool_call' | 'memory_read' | 'memory_write' | 'llm_call';
+    timestamp: Date;
+    details: Record<string, unknown>;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IAErC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,IAAI,CAAA;IACf;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE;QACT,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IAEV;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,KAAK,EAAE,IAAI,EAAE,CAAA;IAEb;;OAEG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;IAEvB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;OAEG;IACH,UAAU,IAAI,YAAY,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,aAAa,CAAC,EAAE,WAAW,EAAE,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,GAAG,aAAa,GAAG,cAAc,GAAG,UAAU,CAAA;IAC/D,SAAS,EAAE,IAAI,CAAA;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC"}

package/dist/orchestration/agent.js

@@ -0,0 +1,6 @@
+/**
+ * Agent Interface
+ *
+ * Defines the structure for AI agents
+ */
+export {};

package/dist/orchestration/defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Default Tool Sets for Agent Types
+ *
+ * Defines the default tools available to standard agent configurations.
+ * Consumers extend these by pushing to agent.tools or by passing
+ * additionalTools to getWorkspaceAgentTools().
+ *
+ * MCP-discovered tools are merged at runtime by MCPHypervisor (P3-3).
+ */
+import type { Tool } from '../tools/base.js';
+/**
+ * Default tools for the WORKSPACE_AGENT profile.
+ * Includes web search (DuckDuckGo, zero-config).
+ */
+export declare const WORKSPACE_AGENT_DEFAULT_TOOLS: Tool[];
+/**
+ * Returns the workspace agent default tool set, optionally merged with
+ * additional tools (e.g. CMS tools, MCP-discovered tools).
+ */
+export declare function getWorkspaceAgentTools(additionalTools?: Tool[]): Tool[];
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/orchestration/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAG5C;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,IAAI,EAAoB,CAAA;AAEpE;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,GAAE,IAAI,EAAO,GAAG,IAAI,EAAE,CAE3E"}

package/dist/orchestration/defaults.js

@@ -0,0 +1,22 @@
+/**
+ * Default Tool Sets for Agent Types
+ *
+ * Defines the default tools available to standard agent configurations.
+ * Consumers extend these by pushing to agent.tools or by passing
+ * additionalTools to getWorkspaceAgentTools().
+ *
+ * MCP-discovered tools are merged at runtime by MCPHypervisor (P3-3).
+ */
+import { webSearchTool } from '../tools/web/index.js';
+/**
+ * Default tools for the WORKSPACE_AGENT profile.
+ * Includes web search (DuckDuckGo, zero-config).
+ */
+export const WORKSPACE_AGENT_DEFAULT_TOOLS = [webSearchTool];
+/**
+ * Returns the workspace agent default tool set, optionally merged with
+ * additional tools (e.g. CMS tools, MCP-discovered tools).
+ */
+export function getWorkspaceAgentTools(additionalTools = []) {
+    return [...WORKSPACE_AGENT_DEFAULT_TOOLS, ...additionalTools];
+}

package/dist/orchestration/memory-integration.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Memory Integration
+ *
+ * Connects agents to the existing memory system
+ */
+import type { AgentMemory } from '@revealui/contracts/agents';
+import type { EpisodicMemory } from '../memory/stores/episodic-memory.js';
+import type { Agent, AgentContext } from './agent.js';
+/**
+ * Configuration for AgentMemoryIntegration.
+ */
+export interface AgentMemoryIntegrationConfig {
+    /**
+     * When true (default), episodic memory can only be written via the explicit
+     * `store_memory` tool. Automatic writes from storeContext() and
+     * updateMemoryFromAction() are blocked.
+     *
+     * Set to false for backward-compatible auto-store behavior.
+     *
+     * GDPR rationale: Requiring explicit intent aligns with the data minimisation
+     * principle (GDPR Art. 5(1)(c)) and purpose limitation (Art. 5(1)(b)).
+     * Agents should only persist what they actively decide to remember.
+     */
+    requireExplicitStore?: boolean;
+}
+/**
+ * Integrate agent with memory system
+ */
+export declare class AgentMemoryIntegration {
+    /**
+     * Store agent context in memory.
+     *
+     * Blocked when `requireExplicitStore: true` (default). In that mode agents
+     * must call the `store_memory` tool explicitly. Use createStoreMemoryTool()
+     * to attach the explicit-store tool to the agent.
+     */
+    static storeContext(agent: Agent, memory: EpisodicMemory, context: AgentContext, config?: AgentMemoryIntegrationConfig): Promise<void>;
+    /**
+     * Retrieve relevant memories for agent
+     */
+    static retrieveMemories(agent: Agent, memory: EpisodicMemory, query?: string, limit?: number): Promise<AgentMemory[]>;
+    /**
+     * Update memory from agent action.
+     *
+     * Blocked when `requireExplicitStore: true` (default). In that mode agents
+     * must call the `store_memory` tool explicitly.
+     */
+    static updateMemoryFromAction(agent: Agent, memory: EpisodicMemory, action: {
+        type: string;
+        result: unknown;
+        metadata?: Record<string, unknown>;
+    }, config?: AgentMemoryIntegrationConfig): Promise<void>;
+    /**
+     * Get agent context from memory
+     */
+    static getContext(agent: Agent, memory: EpisodicMemory): Promise<AgentContext | null>;
+}
+//# sourceMappingURL=memory-integration.d.ts.map

package/dist/orchestration/memory-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-integration.d.ts","sourceRoot":"","sources":["../../src/orchestration/memory-integration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAMD;;GAEG;AAEH,qBAAa,sBAAsB;IACjC;;;;;;OAMG;WACU,YAAY,CACvB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,4BAA4C,GACnD,OAAO,CAAC,IAAI,CAAC;IA+BhB;;OAEG;WACU,gBAAgB,CAC3B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,SAAK,GACT,OAAO,CAAC,WAAW,EAAE,CAAC;IA0BzB;;;;;OAKG;WACU,sBAAsB,CACjC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EACD,MAAM,GAAE,4BAA4C,GACnD,OAAO,CAAC,IAAI,CAAC;IAsChB;;OAEG;WACU,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAc5F"}

package/dist/orchestration/memory-integration.js

@@ -0,0 +1,130 @@
+/**
+ * Memory Integration
+ *
+ * Connects agents to the existing memory system
+ */
+const defaultConfig = {
+    requireExplicitStore: true,
+};
+/**
+ * Integrate agent with memory system
+ */
+// biome-ignore lint/complexity/noStaticOnlyClass: Provides a namespaced API.
+export class AgentMemoryIntegration {
+    /**
+     * Store agent context in memory.
+     *
+     * Blocked when `requireExplicitStore: true` (default). In that mode agents
+     * must call the `store_memory` tool explicitly. Use createStoreMemoryTool()
+     * to attach the explicit-store tool to the agent.
+     */
+    static async storeContext(agent, memory, context, config = defaultConfig) {
+        if (config.requireExplicitStore ?? true) {
+            // Blocked: agents must use the store_memory tool for explicit persistence.
+            return;
+        }
+        const memoryEntry = {
+            id: `context-${agent.id}-${Date.now()}`,
+            version: 1,
+            content: JSON.stringify(context),
+            type: 'fact', // Use 'fact' type since context is a learned fact about the agent state
+            source: {
+                type: 'agent',
+                id: agent.id,
+                confidence: 1,
+            },
+            metadata: {
+                importance: 0.5,
+                agentId: agent.id,
+                sessionId: context.sessionId,
+                custom: context.metadata,
+            },
+            createdAt: new Date().toISOString(),
+            accessedAt: new Date().toISOString(),
+            accessCount: 0,
+            verified: false,
+        };
+        await memory.add(memoryEntry);
+        await memory.save();
+    }
+    /**
+     * Retrieve relevant memories for agent
+     */
+    static async retrieveMemories(agent, memory, query, limit = 10) {
+        const allMemories = await memory.getAll();
+        // Filter by agent ID (check metadata.agentId or source.id)
+        const agentMemories = allMemories.filter((m) => m.metadata?.agentId === agent.id || m.source.id === agent.id);
+        // If query provided, filter by content (simplified - would use semantic search in production)
+        if (query) {
+            const queryLower = query.toLowerCase();
+            return agentMemories
+                .filter((m) => m.content.toLowerCase().includes(queryLower))
+                .slice(0, limit);
+        }
+        // Return most recent
+        return agentMemories
+            .sort((a, b) => {
+            const aTime = new Date(a.accessedAt).getTime();
+            const bTime = new Date(b.accessedAt).getTime();
+            return bTime - aTime;
+        })
+            .slice(0, limit);
+    }
+    /**
+     * Update memory from agent action.
+     *
+     * Blocked when `requireExplicitStore: true` (default). In that mode agents
+     * must call the `store_memory` tool explicitly.
+     */
+    static async updateMemoryFromAction(agent, memory, action, config = defaultConfig) {
+        if (config.requireExplicitStore ?? true) {
+            // Blocked: agents must use the store_memory tool for explicit persistence.
+            return;
+        }
+        const memoryEntry = {
+            id: `action-${agent.id}-${Date.now()}`,
+            version: 1,
+            content: JSON.stringify({
+                type: action.type,
+                result: action.result,
+                timestamp: new Date().toISOString(),
+            }),
+            type: 'decision', // Use 'decision' type since actions represent decisions made
+            source: {
+                type: 'agent',
+                id: agent.id,
+                confidence: 1,
+            },
+            metadata: {
+                importance: 0.5,
+                agentId: agent.id,
+                custom: {
+                    actionType: action.type,
+                    ...action.metadata,
+                },
+            },
+            createdAt: new Date().toISOString(),
+            accessedAt: new Date().toISOString(),
+            accessCount: 0,
+            verified: false,
+        };
+        await memory.add(memoryEntry);
+        await memory.save();
+    }
+    /**
+     * Get agent context from memory
+     */
+    static async getContext(agent, memory) {
+        const memories = await AgentMemoryIntegration.retrieveMemories(agent, memory, 'context', 1);
+        if (memories.length === 0 || !memories[0]) {
+            return null;
+        }
+        try {
+            const context = JSON.parse(memories[0].content);
+            return context;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/orchestration/orchestrator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent Orchestrator
+ *
+ * Coordinates multiple agents for complex tasks.
+ * Requires an LLM client to execute agent tasks via the runtime.
+ */
+import type { LLMClient } from '../llm/client.js';
+import type { Agent, AgentResult, Task } from './agent.js';
+export interface OrchestrationConfig {
+    maxConcurrentAgents?: number;
+    taskTimeout?: number;
+    retryOnFailure?: boolean;
+}
+export declare class AgentOrchestrator {
+    private agents;
+    private config;
+    private runtime;
+    private llmClient;
+    constructor(config?: OrchestrationConfig);
+    /**
+     * Set the LLM client used for task execution.
+     * Must be called before delegateTask() or coordinateAgents().
+     */
+    setLLMClient(client: LLMClient): void;
+    /**
+     * Get the current LLM client (if configured)
+     */
+    getLLMClient(): LLMClient | null;
+    /**
+     * Register an agent
+     */
+    registerAgent(agent: Agent): void;
+    /**
+     * Unregister an agent
+     */
+    unregisterAgent(agentId: string): void;
+    /**
+     * Get an agent by ID
+     */
+    getAgent(agentId: string): Agent | undefined;
+    /**
+     * Get all registered agents
+     */
+    getAllAgents(): Agent[];
+    /**
+     * Delegate a task to the most appropriate agent.
+     * Uses the runtime's agentic loop (LLM chat → tool calls → repeat).
+     */
+    delegateTask(task: Task, preferredAgentId?: string): Promise<AgentResult>;
+    /**
+     * 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
+     */
+    private findBestAgent;
+    /**
+     * Coordinate multiple agents for a complex task.
+     * Executes in batches up to maxConcurrentAgents, each agent receiving a subtask.
+     */
+    coordinateAgents(task: Task, agentIds: string[]): Promise<Map<string, AgentResult>>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestration/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAG1D,MAAM,WAAW,mBAAmB;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,MAAM,GAAE,mBAAwB;IAW5C;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIrC;;OAEG;IACH,YAAY,IAAI,SAAS,GAAG,IAAI;IAIhC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAOjC;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAItC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAI5C;;OAEG;IACH,YAAY,IAAI,KAAK,EAAE;IAIvB;;;OAGG;IACG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA6B/E;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IA+BrB;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAoD1F"}