beth-copilot 1.0.15 → 1.0.16

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Orchestrator — Beth's Brain
+ *
+ * The main agentic loop that ties everything together:
+ *
+ *   User message
+ *      → Route to agent (AgentRouter)
+ *      → Build context (ConversationContext)
+ *      → Inject skills (if triggers match)
+ *      → Send to LLM (Provider)
+ *      → If tool calls → execute tools (ToolRegistry)
+ *         → If subagent request → spawn child conversation
+ *         → Return tool results to LLM → loop
+ *      → If handoff → transfer to new agent (HandoffManager)
+ *      → If text response → return to caller
+ *
+ * The orchestrator supports both streaming and non-streaming modes,
+ * and handles the full tool-calling loop until the model produces
+ * a final text response or a handoff.
+ */
+import type { LLMProviderBase } from '../providers/interface.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ToolContext } from '../tools/types.js';
+import type { AgentLoadResult } from './agents/types.js';
+import type { SkillLoadResult } from './skills/types.js';
+import { ConversationContext } from './context.js';
+import type { ConversationContextOptions } from './context.js';
+import { AgentRouter } from './router.js';
+import type { RouteResult } from './router.js';
+import { HandoffManager } from './handoffs.js';
+import type { HandoffRequest, HandoffResult } from './handoffs.js';
+/**
+ * Configuration for the Orchestrator.
+ */
+export interface OrchestratorConfig {
+    /** Loaded agent definitions */
+    agents: AgentLoadResult;
+    /** Loaded skill definitions */
+    skills: SkillLoadResult;
+    /** LLM provider for chat completions */
+    provider: LLMProviderBase;
+    /** Tool registry with all available tools */
+    toolRegistry: ToolRegistry;
+    /** Tool execution context (working dir, permissions) */
+    toolContext: ToolContext;
+    /** Default agent ID (default: 'beth') */
+    defaultAgentId?: string;
+    /** Maximum tool-calling iterations per turn (default: 25) */
+    maxIterations?: number;
+    /** Maximum subagent depth (default: 3) */
+    maxSubagentDepth?: number;
+    /** Maximum handoff depth (default: 10) */
+    maxHandoffDepth?: number;
+    /** Options for conversation contexts */
+    contextOptions?: ConversationContextOptions;
+}
+/**
+ * The result of processing a single user turn.
+ */
+export interface TurnResult {
+    /** The final text response from the agent */
+    response: string;
+    /** The agent that produced this response */
+    agentId: string;
+    /** How the agent was selected */
+    routeReason: RouteResult['reason'];
+    /** Tool calls that were executed during this turn */
+    toolCallsExecuted: ToolCallRecord[];
+    /** Any handoff that occurred */
+    handoff?: HandoffResult;
+    /** Any subagent results that were collected */
+    subagentResults: SubagentResult[];
+    /** Number of LLM iterations used */
+    iterations: number;
+    /** Skills that were injected for this turn */
+    injectedSkills: string[];
+}
+/**
+ * Record of a tool call execution.
+ */
+export interface ToolCallRecord {
+    /** Tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Whether the tool executed successfully */
+    success: boolean;
+    /** Brief output or error */
+    output: string;
+}
+/**
+ * Result from a subagent invocation.
+ */
+export interface SubagentResult {
+    /** The subagent's ID */
+    agentId: string;
+    /** The prompt sent to the subagent */
+    prompt: string;
+    /** The subagent's response */
+    response: string;
+    /** Whether the subagent completed successfully */
+    success: boolean;
+}
+/**
+ * Callback for observing orchestrator events.
+ * Useful for logging, UI updates, and debugging.
+ */
+export interface OrchestratorObserver {
+    /** Called when routing is decided */
+    onRoute?: (result: RouteResult) => void;
+    /** Called before each LLM call */
+    onLLMCall?: (agentId: string, messageCount: number) => void;
+    /** Called when the LLM responds with text */
+    onLLMResponse?: (agentId: string, content: string) => void;
+    /** Called when a tool call starts */
+    onToolCallStart?: (toolName: string, args: string) => void;
+    /** Called when a tool call completes */
+    onToolCallEnd?: (record: ToolCallRecord) => void;
+    /** Called when a handoff is initiated */
+    onHandoff?: (request: HandoffRequest) => void;
+    /** Called when a subagent starts */
+    onSubagentStart?: (agentId: string, prompt: string) => void;
+    /** Called when a subagent completes */
+    onSubagentEnd?: (result: SubagentResult) => void;
+    /** Called when an iteration completes */
+    onIteration?: (iteration: number, agentId: string) => void;
+}
+/**
+ * The Orchestrator — Beth's brain.
+ *
+ * Manages the full agent loop: routing → LLM → tool calls → response.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new Orchestrator({
+ *   agents: loadAgents('.github/agents'),
+ *   skills: loadSkills('.github/skills'),
+ *   provider: new AzureOpenAIProvider(config),
+ *   toolRegistry: createDefaultRegistry(),
+ *   toolContext: { workingDir: process.cwd(), permissions: { ... } },
+ * });
+ *
+ * const result = await orchestrator.processMessage('Implement the login page');
+ * console.log(result.response);
+ * ```
+ */
+export declare class Orchestrator {
+    private readonly router;
+    private readonly handoffs;
+    private readonly provider;
+    private readonly toolRegistry;
+    private readonly toolContext;
+    private readonly maxIterations;
+    private readonly maxSubagentDepth;
+    private readonly contextOptions?;
+    /** Active conversation contexts by agent ID */
+    private readonly contexts;
+    /** Currently active agent ID */
+    private activeAgentId;
+    /** Observer for event callbacks */
+    private observer?;
+    constructor(config: OrchestratorConfig);
+    /**
+     * Set an observer for orchestrator events.
+     */
+    setObserver(observer: OrchestratorObserver): void;
+    /**
+     * Process a user message through the full agent loop.
+     *
+     * This is the main entry point. It:
+     * 1. Routes the message to the appropriate agent
+     * 2. Injects any matching skills
+     * 3. Runs the agent loop (LLM → tools → LLM → ...)
+     * 4. Returns the final response
+     *
+     * @param userMessage - The user's input
+     * @returns The complete turn result
+     */
+    processMessage(userMessage: string): Promise<TurnResult>;
+    /**
+     * Process a message at a specific subagent depth.
+     * Used internally for subagent chains.
+     */
+    private processMessageAtDepth;
+    /**
+     * Execute a handoff to a different agent.
+     *
+     * @param toAgentId - Target agent ID
+     * @param prompt - Message to the new agent
+     * @returns The handoff result and potentially a new TurnResult
+     */
+    executeHandoff(toAgentId: string, prompt: string): Promise<{
+        handoff: HandoffResult;
+        turnResult?: TurnResult;
+    }>;
+    /**
+     * Get the currently active agent ID.
+     */
+    getActiveAgentId(): string;
+    /**
+     * Get the conversation context for the active agent.
+     */
+    getActiveContext(): ConversationContext | undefined;
+    /**
+     * Get the router for external agent queries.
+     */
+    getRouter(): AgentRouter;
+    /**
+     * Get the handoff manager.
+     */
+    getHandoffManager(): HandoffManager;
+    /**
+     * Reset all conversation state.
+     */
+    reset(): void;
+    /**
+     * Call the LLM and collect the full response.
+     * Uses streaming internally for reliability, collects into a single result.
+     */
+    private callLLM;
+    /**
+     * Execute a single tool call and return a record.
+     */
+    private executeToolCall;
+    /**
+     * Handle a subagent request from a tool call.
+     */
+    private handleSubagentRequest;
+    /**
+     * Run a mini agent loop for a subagent.
+     * Returns the final text response.
+     */
+    private runSubagentLoop;
+    /**
+     * Get or create a ConversationContext for an agent.
+     */
+    private getOrCreateContext;
+    /**
+     * Get tool definitions for an agent based on its allowed tools.
+     *
+     * Filters the full tool registry to only include tools the agent
+     * is allowed to use (from its frontmatter.tools list).
+     */
+    private getToolDefinitions;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

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

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