@agentionai/agents 0.6.0 → 0.6.1

package/dist/agents/AgentConfig.d.ts

@@ -6,24 +6,43 @@ export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini";
  * Common configuration shared by all agents
  */
 export interface CommonAgentConfig {
+    /** Unique identifier for the agent instance */
     id: string;
+    /** Human-readable name for the agent */
     name: string;
+    /** Description of the agent's purpose and capabilities */
     description: string;
+    /** API key for authenticating with the LLM provider */
     apiKey: string;
+    /** Enable debug logging for troubleshooting (default: false) */
     debug?: boolean;
+    /** Maximum number of messages to retain in conversation history */
     maxHistoryLength?: number;
+    /** Model identifier (e.g., "claude-3-5-sonnet-20241022", "gpt-4") */
     model?: string;
+    /** Array of tools the agent can use during execution */
     tools?: Tool<unknown>[];
+    /** Array of sub-agents this agent can delegate tasks to */
     agents?: BaseAgent[];
+    /** Maximum number of tokens to generate in the response */
     maxTokens?: number;
+    /** Sampling temperature (0.0-1.0). Higher values increase randomness */
     temperature?: number;
+    /** Nucleus sampling threshold (0.0-1.0). Considers tokens with top cumulative probability */
     topP?: number;
+    /** Top-K sampling. Only considers the K most likely tokens (Anthropic, Gemini) */
     topK?: number;
+    /** Sequences that will stop generation when encountered */
     stopSequences?: string[];
+    /** Request timeout in milliseconds */
     timeout?: number;
+    /** Maximum number of retry attempts on API failures */
     maxRetries?: number;
+    /** Random seed for deterministic outputs (when supported by vendor) */
     seed?: number;
+    /** Penalty for using tokens that already appear in the text (-2.0 to 2.0) */
     presencePenalty?: number;
+    /** Penalty based on token frequency in the text (-2.0 to 2.0) */
     frequencyPenalty?: number;
 }
 /**

package/dist/agents/BaseAgent.d.ts

@@ -4,6 +4,11 @@ import { History, HistoryEntry, MessageRole, MessageContent } from "../history/H
 import { AgentVendor, CommonAgentConfig, VendorSpecificConfig } from "./AgentConfig";
 export type { HistoryEntry, MessageRole, MessageContent };
 export type { AgentVendor };
+/**
+ * Parses a `retry-after` header value (seconds as string) into milliseconds.
+ */
+declare function parseRetryAfterHeader(header: string | undefined): number | undefined;
+export { parseRetryAfterHeader };
 /**
  * Agent config as used across all agents
  * @deprecated Use CommonAgentConfig with vendorConfig instead
@@ -33,6 +38,16 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
     protected vendor: AgentVendor;
     /** The model identifier for this agent */
     protected model: string;
+    /** Token usage from the last execution (for metrics tracking) */
+    lastTokenUsage?: TokenUsage;
+    /** Maximum number of retry attempts (0 = disabled) */
+    protected maxRetries: number;
+    /** Initial backoff delay in ms */
+    private retryDelayMs;
+    /** Multiplier applied to delay after each attempt */
+    private retryBackoffFactor;
+    /** Maximum backoff delay cap in ms */
+    private retryMaxDelayMs;
     /**
      * An Agent is the primary LLM entity.
      *
@@ -68,6 +83,30 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
      * Add a message with content blocks to history
      */
     protected addMessageToHistory(role: MessageRole, content: MessageContent[]): void;
+    /**
+     * Enable retry with exponential backoff for this agent.
+     * @param options.maxRetries - Number of retry attempts (default: 3)
+     * @param options.initialDelay - Initial backoff delay in ms (default: 1000)
+     * @param options.backoffFactor - Multiplier per attempt (default: 2)
+     * @param options.maxDelay - Maximum delay cap in ms (default: 30000)
+     */
+    withRetry(options?: {
+        maxRetries?: number;
+        initialDelay?: number;
+        backoffFactor?: number;
+        maxDelay?: number;
+    }): this;
+    /**
+     * Executes a function with retry and exponential backoff.
+     *
+     * Retries on 429 (rate limit) and 5xx (server error) responses.
+     * Never retries on MaxTokensExceededError or 4xx client errors.
+     * Throws MaxRetriesExceededError when all attempts are exhausted.
+     *
+     * @param fn - The async function to execute
+     * @param getRetryAfterMs - Optional extractor for retry-after header (returns ms to wait)
+     */
+    protected executeWithRetry<T>(fn: () => Promise<T>, getRetryAfterMs?: (error: unknown) => number | undefined): Promise<T>;
     addTools(tools: Tool<unknown>[]): void;
     getId(): string;
     getName(): string;

package/dist/agents/BaseAgent.js

@@ -4,9 +4,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseAgent = void 0;
+exports.parseRetryAfterHeader = parseRetryAfterHeader;
 const events_1 = __importDefault(require("events"));
 const Tool_1 = require("../tools/Tool");
 const History_1 = require("../history/History");
+const AgentEvent_1 = require("./AgentEvent");
+const AgentError_1 = require("./errors/AgentError");
+/**
+ * Extracts an HTTP status code from a raw SDK error of any vendor shape.
+ */
+function extractStatusCode(error) {
+    if (error instanceof AgentError_1.ApiError)
+        return error.statusCode;
+    const e = error;
+    return typeof e.status === "number" ? e.status : undefined;
+}
+/**
+ * Parses a `retry-after` header value (seconds as string) into milliseconds.
+ */
+function parseRetryAfterHeader(header) {
+    if (!header)
+        return undefined;
+    const seconds = parseFloat(header);
+    return isNaN(seconds) ? undefined : Math.ceil(seconds * 1000);
+}
 /**
  * The base agent is what the other agents are inheriting from
  * Handles the BaseConfig
@@ -24,7 +45,15 @@ class BaseAgent extends events_1.default {
     constructor(config, history = new History_1.History([], { transient: true })) {
         super();
         this.history = history;
-        this.debug = true;
+        this.debug = false;
+        /** Maximum number of retry attempts (0 = disabled) */
+        this.maxRetries = 0;
+        /** Initial backoff delay in ms */
+        this.retryDelayMs = 1000;
+        /** Multiplier applied to delay after each attempt */
+        this.retryBackoffFactor = 2;
+        /** Maximum backoff delay cap in ms */
+        this.retryMaxDelayMs = 30000;
         this.id = config.id;
         this.debug = config.debug || false;
         this.name = config.name;
@@ -41,6 +70,7 @@ class BaseAgent extends events_1.default {
         }
         this.tools = new Map((config.tools || []).map((tool) => [tool.name, tool]));
         this.maxHistoryLength = config.maxHistoryLength || 100;
+        this.maxRetries = config.maxRetries ?? 0;
     }
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((tool) => tool.getPrompt());
@@ -81,6 +111,75 @@ class BaseAgent extends events_1.default {
     addMessageToHistory(role, content) {
         this.history.addMessage(role, content);
     }
+    /**
+     * Enable retry with exponential backoff for this agent.
+     * @param options.maxRetries - Number of retry attempts (default: 3)
+     * @param options.initialDelay - Initial backoff delay in ms (default: 1000)
+     * @param options.backoffFactor - Multiplier per attempt (default: 2)
+     * @param options.maxDelay - Maximum delay cap in ms (default: 30000)
+     */
+    withRetry(options) {
+        this.maxRetries = options?.maxRetries ?? 3;
+        if (options?.initialDelay !== undefined)
+            this.retryDelayMs = options.initialDelay;
+        if (options?.backoffFactor !== undefined)
+            this.retryBackoffFactor = options.backoffFactor;
+        if (options?.maxDelay !== undefined)
+            this.retryMaxDelayMs = options.maxDelay;
+        return this;
+    }
+    /**
+     * Executes a function with retry and exponential backoff.
+     *
+     * Retries on 429 (rate limit) and 5xx (server error) responses.
+     * Never retries on MaxTokensExceededError or 4xx client errors.
+     * Throws MaxRetriesExceededError when all attempts are exhausted.
+     *
+     * @param fn - The async function to execute
+     * @param getRetryAfterMs - Optional extractor for retry-after header (returns ms to wait)
+     */
+    async executeWithRetry(fn, getRetryAfterMs) {
+        let attempt = 0;
+        let delayMs = this.retryDelayMs;
+        while (true) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                // MaxTokensExceededError is never retryable
+                if (error instanceof AgentError_1.MaxTokensExceededError)
+                    throw error;
+                const statusCode = extractStatusCode(error);
+                const isRetryable = statusCode === 429 ||
+                    (statusCode !== undefined && statusCode >= 500);
+                if (!isRetryable || attempt >= this.maxRetries) {
+                    if (attempt > 0) {
+                        this.emit(AgentEvent_1.AgentEvent.MAX_RETRIES_EXCEEDED, {
+                            maxRetries: this.maxRetries,
+                            error,
+                        });
+                        throw new AgentError_1.MaxRetriesExceededError(`Max retries (${this.maxRetries}) exceeded`, this.maxRetries);
+                    }
+                    throw error;
+                }
+                attempt++;
+                // Respect retry-after header if the SDK provides it
+                const retryAfter = getRetryAfterMs?.(error);
+                // Add ±10% jitter to avoid thundering herd
+                const jitter = delayMs * 0.1 * (Math.random() * 2 - 1);
+                const waitMs = Math.min(retryAfter ?? delayMs + jitter, this.retryMaxDelayMs);
+                this.emit(AgentEvent_1.AgentEvent.RETRY, {
+                    attempt,
+                    maxRetries: this.maxRetries,
+                    delayMs: waitMs,
+                    statusCode,
+                    error,
+                });
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+                delayMs = Math.min(delayMs * this.retryBackoffFactor, this.retryMaxDelayMs);
+            }
+        }
+    }
     addTools(tools) {
         tools.forEach((tool) => {
             if (!this.tools.has(tool.name)) {

package/dist/agents/anthropic/ClaudeAgent.d.ts

@@ -28,8 +28,6 @@ type AgentConfig = BaseAgentConfig & {
 export declare class ClaudeAgent extends BaseAgent {
     private client;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/anthropic/ClaudeAgent.js

@@ -77,7 +77,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         try {
             const messages = transformers_1.anthropicTransformer.toProvider(this.history.entries);
             const systemMessage = this.history.getSystemMessage();
-            const response = await this.client.messages.create({
+            const response = await this.executeWithRetry(() => this.client.messages.create({
                 model: this.config.model,
                 system: systemMessage,
                 max_tokens: this.config.maxTokens,
@@ -88,7 +88,9 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 top_k: this.config.topK,
                 stop_sequences: this.config.stopSequences,
                 metadata: this.config.metadata,
-            });
+            }), (err) => err instanceof sdk_1.APIError
+                ? (0, BaseAgent_1.parseRetryAfterHeader)(err.headers?.["retry-after"])
+                : undefined);
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
         }
@@ -178,7 +180,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 // Continue conversation with tool results
                 try {
                     const messages = transformers_1.anthropicTransformer.toProvider(this.history.entries);
-                    const newResponse = await this.client.messages.create({
+                    const newResponse = await this.executeWithRetry(() => this.client.messages.create({
                         model: this.config.model,
                         max_tokens: this.config.maxTokens,
                         messages,
@@ -188,7 +190,9 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                         top_k: this.config.topK,
                         stop_sequences: this.config.stopSequences,
                         metadata: this.config.metadata,
-                    });
+                    }), (err) => err instanceof sdk_1.APIError
+                        ? (0, BaseAgent_1.parseRetryAfterHeader)(err.headers?.["retry-after"])
+                        : undefined);
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse);
                 }

package/dist/agents/google/GeminiAgent.d.ts

@@ -29,8 +29,6 @@ export declare class GeminiAgent extends BaseAgent {
     private client;
     private generativeModel;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/google/GeminiAgent.js

@@ -179,7 +179,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             const contents = transformers_1.geminiTransformer.toProvider(this.history.entries);
             const systemMessage = this.history.getSystemMessage();
             const tools = this.getToolDefinitionsForGemini();
-            const response = await this.generativeModel.generateContent({
+            const response = await this.executeWithRetry(() => this.generativeModel.generateContent({
                 contents,
                 systemInstruction: systemMessage,
                 tools: tools ? [tools] : undefined,
@@ -193,7 +193,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                     responseMimeType: this.config.responseMimeType,
                     responseSchema: this.config.responseSchema,
                 },
-            });
+            }));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
         }
@@ -293,7 +293,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                 const newContents = transformers_1.geminiTransformer.toProvider(this.history.entries);
                 const systemMessage = this.history.getSystemMessage();
                 const tools = this.getToolDefinitionsForGemini();
-                const newResponse = await this.generativeModel.generateContent({
+                const newResponse = await this.executeWithRetry(() => this.generativeModel.generateContent({
                     contents: newContents,
                     systemInstruction: systemMessage,
                     tools: tools ? [tools] : undefined,
@@ -307,7 +307,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                         responseMimeType: this.config.responseMimeType,
                         responseSchema: this.config.responseSchema,
                     },
-                });
+                }));
                 this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                 return this.handleResponse(newResponse);
             }

package/dist/agents/mistral/MistralAgent.d.ts

@@ -29,8 +29,6 @@ type AgentConfig = BaseAgentConfig & {
 export declare class MistralAgent extends BaseAgent {
     private client;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/mistral/MistralAgent.js

@@ -87,7 +87,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         this.addTextToHistory("user", input);
         try {
             const messages = transformers_1.mistralTransformer.toProvider(this.history.entries);
-            const response = await this.client.chat.complete({
+            const response = await this.executeWithRetry(() => this.client.chat.complete({
                 model: this.config.model,
                 messages: messages,
                 tools: this.getToolDefinitions(),
@@ -97,7 +97,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
                 randomSeed: this.config.randomSeed,
                 safePrompt: this.config.safePrompt,
                 stop: this.config.stopSequences,
-            });
+            }));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
         }
@@ -203,7 +203,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
                 // Continue conversation
                 try {
                     const messages = transformers_1.mistralTransformer.toProvider(this.history.entries);
-                    const newResponse = await this.client.chat.complete({
+                    const newResponse = await this.executeWithRetry(() => this.client.chat.complete({
                         model: this.config.model,
                         messages: messages,
                         tools: this.getToolDefinitions(),
@@ -213,7 +213,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
                         randomSeed: this.config.randomSeed,
                         safePrompt: this.config.safePrompt,
                         stop: this.config.stopSequences,
-                    });
+                    }));
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse);
                 }

package/dist/agents/openai/OpenAiAgent.d.ts

@@ -30,8 +30,6 @@ type AgentConfig = BaseAgentConfig & {
 export declare class OpenAiAgent extends BaseAgent {
     private client;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/openai/OpenAiAgent.js

@@ -98,7 +98,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         this.addTextToHistory("user", input);
         try {
             const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
-            const response = await this.client.responses.create({
+            const response = await this.executeWithRetry(() => this.client.responses.create({
                 model: this.config.model,
                 max_output_tokens: this.config.maxTokens,
                 input: inputMessages,
@@ -110,7 +110,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 user: this.config.user,
                 ...(this.config.disableReasoning && { reasoning: { effort: null } }),
                 reasoning: { effort: this.config.reasoningEffort },
-            });
+            }));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
         }
@@ -217,7 +217,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 // Continue conversation
                 try {
                     const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
-                    const newResponse = await this.client.responses.create({
+                    const newResponse = await this.executeWithRetry(() => this.client.responses.create({
                         model: this.config.model,
                         max_output_tokens: this.config.maxTokens,
                         input: inputMessages,
@@ -234,7 +234,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                             !this.config.disableReasoning && {
                             reasoning: { effort: this.config.reasoningEffort },
                         }),
-                    });
+                    }));
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse);
                 }

package/dist/embeddings/VoyageAIEmbeddings.js

@@ -103,6 +103,7 @@ class VoyageAIEmbeddings extends Embeddings_1.Embeddings {
             return [];
         }
         // Dynamic import to keep voyageai optional at module load time
+        // @ts-ignore - voyageai is an optional peer dependency
         const { VoyageAIClient } = await Promise.resolve().then(() => __importStar(require("voyageai")));
         const client = new VoyageAIClient({
             apiKey: this.apiKey,

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

@@ -23,6 +23,14 @@ export interface PlanExecutorOptions {
      * @default true
      */
     stopOnFailure?: boolean;
+    /**
+     * Maximum number of previous step results to include in worker context.
+     * This prevents context overflow by limiting how much history is passed to each step.
+     * Set to 0 to include no previous steps (workers should use context_get to retrieve data).
+     * Set to a small number (1-3) to include only recent context.
+     * @default 0 (workers request context explicitly)
+     */
+    maxContextSteps?: number;
     /**
      * Callback invoked when planning phase completes.
      */
@@ -145,6 +153,10 @@ export declare class PlanExecutor extends BaseExecutor<string, string> {
     private createPlanningPrompt;
     /**
      * 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.
      */
     private createStepInput;
     /**

package/dist/graph/planning/PlanExecutor.js

@@ -57,6 +57,7 @@ class PlanExecutor extends BaseExecutor_1.BaseExecutor {
             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,
@@ -150,11 +151,16 @@ class PlanExecutor extends BaseExecutor_1.BaseExecutor {
         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
@@ -202,9 +208,9 @@ class PlanExecutor extends BaseExecutor_1.BaseExecutor {
                     });
                     // Notify step failure
                     this.options.onStepFailed?.(nextStep, error instanceof Error ? error : new Error(errorMessage), stepNumber);
-                    // Stop if configured to do so
+                    // Record error to stop after in-flight steps complete
                     if (this.options.stopOnFailure) {
-                        throw new Error(`Step ${stepNumber} failed: ${errorMessage}`);
+                        stopError = new Error(`Step ${stepNumber} failed: ${errorMessage}`);
                     }
                 }
                 finally {
@@ -220,9 +226,12 @@ class PlanExecutor extends BaseExecutor_1.BaseExecutor {
                 await promise;
             }
         }
-        // Wait for all remaining promises to complete
+        // Always wait for all in-flight promises to finish before returning/throwing
         if (activePromises.size > 0) {
-            await Promise.all(activePromises.values());
+            await Promise.allSettled(activePromises.values());
+        }
+        if (stopError) {
+            throw stopError;
         }
         if (stepNumber >= this.options.maxSteps) {
             const plan = this.planStore.getActivePlan();
@@ -241,34 +250,81 @@ class PlanExecutor extends BaseExecutor_1.BaseExecutor {
 
 Task: ${task}
 
-IMPORTANT: You can create a maximum of ${this.options.maxSteps} steps. Plan accordingly and prioritize the most important subtasks.
+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)
 
-Use the create_plan tool to create a plan with clear, actionable steps. Each step should be:
-- Specific and focused on a single subtask
-- Ordered logically (dependencies should be addressed)
-- Achievable by a worker agent
+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") || [];
-        return JSON.stringify({
+        // 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,
             },
-            previousSteps: completedSteps.map((s) => ({
+            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,
-            })),
-            planGoal: plan?.goal,
-        });
+            }));
+            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.
@@ -321,13 +377,12 @@ After creating the plan, respond with a brief confirmation.`;
      * Extract token usage from an agent if available.
      */
     extractTokenUsage(agent) {
-        const agentWithUsage = agent;
-        if (!agentWithUsage.lastTokenUsage)
+        if (!agent.lastTokenUsage)
             return undefined;
         return {
-            inputTokens: agentWithUsage.lastTokenUsage.input_tokens,
-            outputTokens: agentWithUsage.lastTokenUsage.output_tokens,
-            totalTokens: agentWithUsage.lastTokenUsage.total_tokens,
+            inputTokens: agent.lastTokenUsage.input_tokens,
+            outputTokens: agent.lastTokenUsage.output_tokens,
+            totalTokens: agent.lastTokenUsage.total_tokens,
         };
     }
     /**

package/dist/graph/planning/PlanStore.js

@@ -119,8 +119,12 @@ class PlanStore {
         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_${plan.steps.length + 1}`,
+            id: `step_${maxIndex + 1}`,
             description,
             status: "pending",
         };
@@ -169,7 +173,7 @@ class PlanStore {
      * Update the overall plan status based on step statuses.
      */
     updatePlanStatus(plan) {
-        const allCompleted = plan.steps.every((s) => s.status === "completed");
+        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;

package/dist/history/History.js

@@ -62,6 +62,9 @@ class History extends events_1.default {
             ...entry,
             __metadata,
         });
+        if (this.options.maxLength && this._entries.length > this.options.maxLength) {
+            this._entries = this._entries.slice(this._entries.length - this.options.maxLength);
+        }
         this.emit("entry", entry);
     }
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",