@agentionai/agents 0.4.2 → 0.6.1

package/dist/graph/planning/PlanExecutor.js

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanExecutor = void 0;
+const BaseExecutor_1 = require("../BaseExecutor");
+/**
+ * Orchestrates plan-based execution with clear separation of concerns:
+ * 1. Planning Phase: Uses a planning agent to create a plan
+ * 2. Execution Phase: Assigns workers (agents or graph nodes) to execute each step
+ * 3. Completion: Compiles results and returns summary
+ *
+ * The PlanExecutor acts as the orchestrator, tracking progress and delegating
+ * work to specialized workers. Planning and execution are separate phases.
+ *
+ * @example
+ * ```typescript
+ * const planStore = AgentGraph.createPlanStore();
+ * const contextStore = AgentGraph.createContextStore();
+ *
+ * // Planning agent creates the plan
+ * const planner = new ClaudeAgent({
+ *   tools: AgentGraph.createPlanningTools(planStore),
+ *   description: 'You are a planning agent. Create a detailed plan with clear steps.',
+ * });
+ *
+ * // Worker agent executes individual steps
+ * const worker = new ClaudeAgent({
+ *   tools: AgentGraph.createContextTools(contextStore),
+ *   description: 'You execute a single step. Store results in context.',
+ * });
+ *
+ * const executor = new PlanExecutor(planStore, planner, worker, {
+ *   onStepComplete: (step, result, num) => {
+ *     console.log(`Completed step ${num}: ${step.description}`);
+ *   },
+ * });
+ *
+ * const result = await executor.execute('Research and summarize quantum computing');
+ * ```
+ */
+class PlanExecutor extends BaseExecutor_1.BaseExecutor {
+    /**
+     * Create a new PlanExecutor.
+     *
+     * @param planStore - The plan store to track plan state
+     * @param planningAgent - Agent responsible for creating the plan
+     * @param worker - Agent or GraphNode that executes individual steps
+     * @param options - Configuration options
+     */
+    constructor(planStore, planningAgent, worker, options = {}) {
+        super();
+        this.planStore = planStore;
+        this.name = "PlanExecutor";
+        this.nodeType = "pipeline";
+        this.planningAgent = planningAgent;
+        this.worker = worker;
+        this.options = {
+            maxSteps: options.maxSteps ?? 50,
+            concurrency: options.concurrency ?? 1,
+            stopOnFailure: options.stopOnFailure ?? true,
+            maxContextSteps: options.maxContextSteps ?? 0, // Default: no auto context
+            onPlanCreated: options.onPlanCreated,
+            onStepStart: options.onStepStart,
+            onStepComplete: options.onStepComplete,
+            onStepFailed: options.onStepFailed,
+        };
+    }
+    /**
+     * Execute the plan:
+     * 1. Planning Phase: Ask planning agent to create a plan
+     * 2. Execution Phase: Execute each step with the worker
+     * 3. Completion: Return finalOutput (for chaining)
+     *
+     * Returns the finalOutput string for easy chaining in pipelines.
+     * Use getLastResult() to access the full PlanExecutionResult with details.
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "pipeline", input);
+        try {
+            // Phase 1: Planning
+            await this.planningPhase(input, collector);
+            // Phase 2: Execution
+            const stepResults = await this.executionPhase(collector);
+            // Phase 3: Compile results
+            const result = this.compileResult(stepResults);
+            // Store for getLastResult()
+            this.lastResult = result;
+            if (execId) {
+                collector?.endExecution(execId, result.success, result.finalOutput);
+            }
+            // Return finalOutput for chaining
+            return result.finalOutput;
+        }
+        catch (error) {
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get the detailed result from the last execution.
+     * Contains full plan details, step results, and metadata.
+     */
+    getLastResult() {
+        return this.lastResult;
+    }
+    /**
+     * Phase 1: Planning
+     * Instructs the planning agent to create a plan based on the task.
+     */
+    async planningPhase(task, collector) {
+        const planExecId = collector?.startExecution("Planning Phase", "agent", task);
+        try {
+            const planningPrompt = this.createPlanningPrompt(task);
+            const planningResult = (await this.planningAgent.execute(planningPrompt));
+            // Extract token usage
+            const tokenUsage = this.extractTokenUsage(this.planningAgent);
+            if (planExecId) {
+                collector?.endExecution(planExecId, true, planningResult, tokenUsage);
+            }
+            // Verify plan was created
+            const plan = this.planStore.getActivePlan();
+            if (!plan || plan.steps.length === 0) {
+                throw new Error("Planning agent failed to create a plan. Please ensure the agent has planning tools.");
+            }
+            // Enforce maxSteps limit
+            if (plan.steps.length > this.options.maxSteps) {
+                throw new Error(`Planning agent created ${plan.steps.length} steps, which exceeds the maximum of ${this.options.maxSteps}. ` +
+                    `Please reduce the plan size or increase maxSteps option.`);
+            }
+            // Notify plan creation
+            this.options.onPlanCreated?.(plan.goal, plan.steps);
+        }
+        catch (error) {
+            if (planExecId) {
+                collector?.endExecution(planExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Phase 2: Execution
+     * Executes each step in the plan using the worker.
+     */
+    async executionPhase(collector) {
+        const plan = this.planStore.getActivePlan();
+        if (!plan) {
+            throw new Error("No active plan found");
+        }
+        const results = [];
+        let stepNumber = 0;
+        const activePromises = new Map();
+        let stopError;
+        while (stepNumber < this.options.maxSteps) {
+            // Wait if we've reached concurrency limit
+            if (activePromises.size >= this.options.concurrency) {
+                await Promise.race(activePromises.values());
+            }
+            // If a step failed and stopOnFailure is set, drain remaining promises then throw
+            if (stopError) {
+                break;
+            }
+            const nextStep = this.planStore.getNextStep();
+            if (!nextStep) {
+                // No more pending steps
+                break;
+            }
+            stepNumber++;
+            // Notify step start
+            this.options.onStepStart?.(nextStep, stepNumber, plan.steps.length);
+            // Mark step as in_progress
+            this.planStore.updateStep(nextStep.id, "in_progress");
+            const stepExecId = collector?.startExecution(`Step ${stepNumber}: ${nextStep.description}`, this.isAgent(this.worker) ? "agent" : "custom", nextStep.description);
+            // Wrap step execution in an async function
+            const executeStep = async () => {
+                try {
+                    // Execute the step with the worker
+                    const stepInput = this.createStepInput(nextStep, stepNumber);
+                    const rawResult = await this.worker.execute(stepInput);
+                    const stepResult = String(rawResult);
+                    // Extract token usage if worker is an agent
+                    const tokenUsage = this.isAgent(this.worker)
+                        ? this.extractTokenUsage(this.worker)
+                        : undefined;
+                    if (stepExecId) {
+                        collector?.endExecution(stepExecId, true, stepResult, tokenUsage);
+                    }
+                    // Mark step as completed
+                    this.planStore.updateStep(nextStep.id, "completed", stepResult);
+                    results.push({
+                        step: nextStep,
+                        result: stepResult,
+                    });
+                    // Notify step completion
+                    this.options.onStepComplete?.(nextStep, stepResult, stepNumber);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    if (stepExecId) {
+                        collector?.endExecution(stepExecId, false, undefined, undefined, errorMessage);
+                    }
+                    // Mark step as failed
+                    this.planStore.updateStep(nextStep.id, "failed", errorMessage);
+                    results.push({
+                        step: nextStep,
+                        error: errorMessage,
+                    });
+                    // Notify step failure
+                    this.options.onStepFailed?.(nextStep, error instanceof Error ? error : new Error(errorMessage), stepNumber);
+                    // Record error to stop after in-flight steps complete
+                    if (this.options.stopOnFailure) {
+                        stopError = new Error(`Step ${stepNumber} failed: ${errorMessage}`);
+                    }
+                }
+                finally {
+                    // Remove from active promises when complete
+                    activePromises.delete(nextStep.id);
+                }
+            };
+            // Store the promise in activePromises
+            const promise = executeStep();
+            activePromises.set(nextStep.id, promise);
+            // For sequential execution (concurrency=1), await immediately
+            if (this.options.concurrency === 1) {
+                await promise;
+            }
+        }
+        // Always wait for all in-flight promises to finish before returning/throwing
+        if (activePromises.size > 0) {
+            await Promise.allSettled(activePromises.values());
+        }
+        if (stopError) {
+            throw stopError;
+        }
+        if (stepNumber >= this.options.maxSteps) {
+            const plan = this.planStore.getActivePlan();
+            const remainingSteps = plan?.steps.filter((s) => s.status === "pending").length;
+            if (remainingSteps && remainingSteps > 0) {
+                throw new Error(`Maximum steps (${this.options.maxSteps}) reached with ${remainingSteps} steps remaining`);
+            }
+        }
+        return results;
+    }
+    /**
+     * Create a prompt for the planning agent.
+     */
+    createPlanningPrompt(task) {
+        return `You are a planning agent. Your job is to create a detailed execution plan for the following task.
+
+Task: ${task}
+
+CRITICAL: You can create a maximum of ${this.options.maxSteps} steps. Plan accordingly and prioritize the most important subtasks.
+
+CONTEXT LIMIT WARNING: Each step will be executed independently with limited context. To avoid rate limits and context overflow:
+- Break work into VERY SMALL, ATOMIC steps
+- Each step should process only 1-3 items at a time
+- Never create steps that say "analyze all", "process everything", "read all files", etc.
+- Instead, break into multiple steps: "Read file1", "Read file2", "Read file3"
+
+Use the create_plan tool to create a plan with clear, actionable steps. Each step MUST be:
+
+1. MICRO-SIZED - Can be completed in under 10 seconds with minimal tokens
+2. SINGLE ACTION - Exactly ONE thing to do (read ONE file, list ONE directory, etc.)
+3. SPECIFIC - Mention exact file names, directories, or items (not "all files")
+4. NO BATCH OPERATIONS - Process items one-by-one, not in bulk
+5. SEQUENTIAL - Let each step's output inform the next step
+
+GOOD EXAMPLES (SMALL STEPS):
+✓ "List files in the lib/graph directory"
+✓ "Read the first 50 lines of PlanExecutor.ts"
+✓ "Search for the definition of 'createPlan' function"
+✓ "Summarize the purpose of SequentialExecutor class in 2 sentences"
+
+BAD EXAMPLES (TOO LARGE):
+✗ "Read and analyze all files in lib/graph" (reads too much, use multiple steps)
+✗ "Analyze the entire codebase architecture" (too broad, break into 5+ steps)
+✗ "Review all test files and identify issues" (batch operation, do one at a time)
+✗ "Research best practices and implement them" (vague, multi-step)
+
+STRATEGY FOR AVOIDING RATE LIMITS:
+- If analyzing multiple files: Create one step per file
+- If processing a list: Create one step per item
+- If researching: Create steps for: 1) identify what to research, 2) research item 1, 3) research item 2, etc.
+- If the task seems large: Create 2x as many steps as you initially think
+
+Break down complex tasks into the SMALLEST possible steps. Having ${this.options.maxSteps} small steps is much better than having ${Math.floor(this.options.maxSteps / 2)} larger ones.
+
+After creating the plan, respond with a brief confirmation.`;
+    }
+    /**
+     * Create input for a step execution.
+     *
+     * By default, only includes the current step information.
+     * Workers should use context_get to retrieve data from previous steps.
+     * This prevents token overflow from accumulating context.
+     */
+    createStepInput(step, stepNumber) {
+        const plan = this.planStore.getActivePlan();
+        const completedSteps = plan?.steps.filter((s) => s.status === "completed") || [];
+        // Limit context to prevent token overflow
+        // Only include the most recent N steps based on maxContextSteps option
+        const recentSteps = this.options.maxContextSteps > 0
+            ? completedSteps.slice(-this.options.maxContextSteps)
+            : [];
+        const input = {
+            stepNumber,
+            totalSteps: plan?.steps.length,
+            currentStep: {
+                id: step.id,
+                description: step.description,
+            },
+            planGoal: plan?.goal,
+        };
+        // Only add previous steps if maxContextSteps > 0
+        if (this.options.maxContextSteps > 0 && recentSteps.length > 0) {
+            input.previousSteps = recentSteps.map((s) => ({
+                description: s.description,
+                output: s.output,
+            }));
+            input.contextNote = `Showing last ${recentSteps.length} of ${completedSteps.length} completed steps`;
+        }
+        else {
+            input.contextNote =
+                "Use context_get tool to retrieve data from previous steps if needed";
+        }
+        return JSON.stringify(input, null, 2);
+    }
+    /**
+     * Compile the final result from step results.
+     */
+    compileResult(stepResults) {
+        const plan = this.planStore.getActivePlan();
+        if (!plan) {
+            throw new Error("No active plan found");
+        }
+        const completedSteps = stepResults.filter((r) => r.result).length;
+        const failedSteps = stepResults.filter((r) => r.error).length;
+        // Create consolidated output for chaining
+        const finalOutput = this.createFinalOutput(plan.goal, stepResults);
+        return {
+            success: plan.status === "completed",
+            goal: plan.goal,
+            totalSteps: plan.steps.length,
+            completedSteps,
+            failedSteps,
+            summary: this.planStore.getSummary(),
+            finalOutput,
+            stepResults,
+        };
+    }
+    /**
+     * Create a clean, consolidated output from all step results.
+     * This output is designed for chaining to the next graph node.
+     */
+    createFinalOutput(goal, stepResults) {
+        const completedResults = stepResults
+            .filter((r) => r.result)
+            .map((r) => r.result)
+            .join("\n\n");
+        // If there are any failures, include them
+        const failures = stepResults.filter((r) => r.error);
+        const failureText = failures.length > 0
+            ? `\n\nFailed steps (${failures.length}):\n${failures
+                .map((f) => `- ${f.step.description}: ${f.error}`)
+                .join("\n")}`
+            : "";
+        return `Goal: ${goal}\n\nResults:\n${completedResults}${failureText}`;
+    }
+    /**
+     * Check if a worker is a BaseAgent.
+     */
+    isAgent(worker) {
+        return "getName" in worker;
+    }
+    /**
+     * Extract token usage from an agent if available.
+     */
+    extractTokenUsage(agent) {
+        if (!agent.lastTokenUsage)
+            return undefined;
+        return {
+            inputTokens: agent.lastTokenUsage.input_tokens,
+            outputTokens: agent.lastTokenUsage.output_tokens,
+            totalTokens: agent.lastTokenUsage.total_tokens,
+        };
+    }
+    /**
+     * Get the plan store.
+     */
+    getPlanStore() {
+        return this.planStore;
+    }
+}
+exports.PlanExecutor = PlanExecutor;
+//# sourceMappingURL=PlanExecutor.js.map

package/dist/graph/planning/PlanStore.d.ts

@@ -0,0 +1,81 @@
+import { Plan, PlanStep, PlanStepStatus } from "./types";
+/**
+ * Manages plans within a pipeline execution.
+ * Provides methods to create, update, and track plan progress.
+ *
+ * @example
+ * ```typescript
+ * const planStore = new PlanStore();
+ * const plan = planStore.createPlan('Research AI', ['Search papers', 'Analyze findings', 'Write summary']);
+ *
+ * // Work through steps
+ * const nextStep = planStore.getNextStep();
+ * planStore.updateStep(nextStep.id, 'completed', 'Found 5 relevant papers');
+ * ```
+ */
+export declare class PlanStore {
+    private plans;
+    private activePlanId?;
+    /**
+     * Create a new plan with a goal and list of step descriptions.
+     * @param goal - The overall goal to achieve
+     * @param steps - Array of step descriptions
+     * @returns The created plan
+     */
+    createPlan(goal: string, steps: string[]): Plan;
+    /**
+     * Get the currently active plan.
+     * @returns The active plan or undefined if none
+     */
+    getActivePlan(): Plan | undefined;
+    /**
+     * Get a plan by its ID.
+     * @param id - The plan ID
+     * @returns The plan or undefined if not found
+     */
+    getPlan(id: string): Plan | undefined;
+    /**
+     * Set the active plan by ID.
+     * @param id - The plan ID to set as active
+     * @returns True if the plan exists and was set as active
+     */
+    setActivePlan(id: string): boolean;
+    /**
+     * Update a step's status and optionally its output or error.
+     * @param stepId - The step ID to update
+     * @param status - The new status
+     * @param output - Optional output from the step
+     * @param error - Optional error message
+     */
+    updateStep(stepId: string, status: PlanStepStatus, output?: string, error?: string): void;
+    /**
+     * Get the next pending step that can be executed.
+     * @returns The next pending step or undefined if none
+     */
+    getNextStep(): PlanStep | undefined;
+    /**
+     * Add a new step to the active plan.
+     * @param description - The step description
+     * @returns The created step or undefined if no active plan
+     */
+    addStep(description: string): PlanStep | undefined;
+    /**
+     * Get a human-readable summary of the active plan.
+     * @returns A formatted summary string
+     */
+    getSummary(): string;
+    /**
+     * Get all plans.
+     * @returns Array of all plans
+     */
+    getAllPlans(): Plan[];
+    /**
+     * Clear all plans.
+     */
+    clear(): void;
+    /**
+     * Update the overall plan status based on step statuses.
+     */
+    private updatePlanStatus;
+}
+//# sourceMappingURL=PlanStore.d.ts.map

package/dist/graph/planning/PlanStore.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanStore = void 0;
+/**
+ * Manages plans within a pipeline execution.
+ * Provides methods to create, update, and track plan progress.
+ *
+ * @example
+ * ```typescript
+ * const planStore = new PlanStore();
+ * const plan = planStore.createPlan('Research AI', ['Search papers', 'Analyze findings', 'Write summary']);
+ *
+ * // Work through steps
+ * const nextStep = planStore.getNextStep();
+ * planStore.updateStep(nextStep.id, 'completed', 'Found 5 relevant papers');
+ * ```
+ */
+class PlanStore {
+    constructor() {
+        this.plans = new Map();
+    }
+    /**
+     * Create a new plan with a goal and list of step descriptions.
+     * @param goal - The overall goal to achieve
+     * @param steps - Array of step descriptions
+     * @returns The created plan
+     */
+    createPlan(goal, steps) {
+        const id = `plan_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const now = Date.now();
+        const plan = {
+            id,
+            goal,
+            steps: steps.map((description, index) => ({
+                id: `step_${index + 1}`,
+                description,
+                status: "pending",
+            })),
+            status: "created",
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.plans.set(id, plan);
+        this.activePlanId = id;
+        return plan;
+    }
+    /**
+     * Get the currently active plan.
+     * @returns The active plan or undefined if none
+     */
+    getActivePlan() {
+        return this.activePlanId ? this.plans.get(this.activePlanId) : undefined;
+    }
+    /**
+     * Get a plan by its ID.
+     * @param id - The plan ID
+     * @returns The plan or undefined if not found
+     */
+    getPlan(id) {
+        return this.plans.get(id);
+    }
+    /**
+     * Set the active plan by ID.
+     * @param id - The plan ID to set as active
+     * @returns True if the plan exists and was set as active
+     */
+    setActivePlan(id) {
+        if (this.plans.has(id)) {
+            this.activePlanId = id;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Update a step's status and optionally its output or error.
+     * @param stepId - The step ID to update
+     * @param status - The new status
+     * @param output - Optional output from the step
+     * @param error - Optional error message
+     */
+    updateStep(stepId, status, output, error) {
+        const plan = this.getActivePlan();
+        if (!plan)
+            return;
+        const step = plan.steps.find((s) => s.id === stepId);
+        if (!step)
+            return;
+        step.status = status;
+        if (output !== undefined)
+            step.output = output;
+        if (error !== undefined)
+            step.error = error;
+        plan.updatedAt = Date.now();
+        // Update plan status based on steps
+        this.updatePlanStatus(plan);
+    }
+    /**
+     * Get the next pending step that can be executed.
+     * @returns The next pending step or undefined if none
+     */
+    getNextStep() {
+        const plan = this.getActivePlan();
+        if (!plan || plan.status === "completed" || plan.status === "failed") {
+            return undefined;
+        }
+        // Mark plan as executing if it was just created
+        if (plan.status === "created") {
+            plan.status = "executing";
+            plan.updatedAt = Date.now();
+        }
+        return plan.steps.find((step) => step.status === "pending");
+    }
+    /**
+     * Add a new step to the active plan.
+     * @param description - The step description
+     * @returns The created step or undefined if no active plan
+     */
+    addStep(description) {
+        const plan = this.getActivePlan();
+        if (!plan)
+            return undefined;
+        const maxIndex = plan.steps.reduce((max, s) => {
+            const match = s.id.match(/^step_(\d+)$/);
+            return match ? Math.max(max, parseInt(match[1], 10)) : max;
+        }, 0);
+        const newStep = {
+            id: `step_${maxIndex + 1}`,
+            description,
+            status: "pending",
+        };
+        plan.steps.push(newStep);
+        plan.updatedAt = Date.now();
+        return newStep;
+    }
+    /**
+     * Get a human-readable summary of the active plan.
+     * @returns A formatted summary string
+     */
+    getSummary() {
+        const plan = this.getActivePlan();
+        if (!plan)
+            return "No active plan";
+        const statusEmoji = {
+            pending: "[ ]",
+            in_progress: "[~]",
+            completed: "[x]",
+            failed: "[!]",
+            skipped: "[-]",
+        };
+        const lines = [
+            `Plan: ${plan.goal}`,
+            `Status: ${plan.status}`,
+            `Steps:`,
+            ...plan.steps.map((step) => `  ${statusEmoji[step.status]} ${step.id}: ${step.description}`),
+        ];
+        return lines.join("\n");
+    }
+    /**
+     * Get all plans.
+     * @returns Array of all plans
+     */
+    getAllPlans() {
+        return Array.from(this.plans.values());
+    }
+    /**
+     * Clear all plans.
+     */
+    clear() {
+        this.plans.clear();
+        this.activePlanId = undefined;
+    }
+    /**
+     * Update the overall plan status based on step statuses.
+     */
+    updatePlanStatus(plan) {
+        const allCompleted = plan.steps.every((s) => s.status === "completed" || s.status === "skipped");
+        const anyFailed = plan.steps.some((s) => s.status === "failed");
+        const anyInProgress = plan.steps.some((s) => s.status === "in_progress");
+        let newStatus;
+        if (allCompleted) {
+            newStatus = "completed";
+        }
+        else if (anyFailed) {
+            newStatus = "failed";
+        }
+        else if (anyInProgress || plan.steps.some((s) => s.status === "completed")) {
+            newStatus = "executing";
+        }
+        else {
+            newStatus = plan.status;
+        }
+        if (plan.status !== newStatus) {
+            plan.status = newStatus;
+            plan.updatedAt = Date.now();
+        }
+    }
+}
+exports.PlanStore = PlanStore;
+//# sourceMappingURL=PlanStore.js.map