@samrahimi/smol-js 0.5.0 → 0.6.0

package/dist/index.js

@@ -35,18 +35,29 @@ __export(index_exports, {
   AgentMemory: () => AgentMemory,
   AgentTool: () => AgentTool,
   CodeAgent: () => CodeAgent,
+  CurlTool: () => CurlTool,
+  ExaGetContentsTool: () => ExaGetContentsTool,
+  ExaResearchTool: () => ExaResearchTool,
+  ExaSearchTool: () => ExaSearchTool,
   FINAL_ANSWER_PROMPT: () => FINAL_ANSWER_PROMPT,
   FinalAnswerTool: () => FinalAnswerTool,
   LocalExecutor: () => LocalExecutor,
   LogLevel: () => LogLevel,
   Model: () => Model,
   OpenAIModel: () => OpenAIModel,
+  Orchestrator: () => Orchestrator,
+  ReadFileTool: () => ReadFileTool,
   Tool: () => Tool,
+  ToolUseAgent: () => ToolUseAgent,
   UserInputTool: () => UserInputTool,
+  WriteFileTool: () => WriteFileTool,
+  YAMLLoader: () => YAMLLoader,
   agentAsTool: () => agentAsTool,
   createTool: () => createTool,
   finalAnswerTool: () => finalAnswerTool,
+  formatToolDescriptions: () => formatToolDescriptions,
   generateSystemPrompt: () => generateSystemPrompt,
+  generateToolUseSystemPrompt: () => generateToolUseSystemPrompt,
   getErrorRecoveryPrompt: () => getErrorRecoveryPrompt
 });
 module.exports = __toCommonJS(index_exports);
@@ -61,31 +72,43 @@ var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
 })(LogLevel || {});
 
 // src/memory/AgentMemory.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function estimateMessagesTokens(messages) {
+  let total = 0;
+  for (const msg of messages) {
+    total += estimateTokens(msg.content ?? "");
+    if (msg.toolCalls) {
+      total += estimateTokens(JSON.stringify(msg.toolCalls));
+    }
+    total += 4;
+  }
+  return total;
+}
 var AgentMemory = class {
-  /**
-   * System prompt step (always first)
-   */
+  /** System prompt step (always first) */
   systemPrompt;
-  /**
-   * All execution steps
-   */
+  /** All execution steps */
   steps = [];
-  constructor(systemPrompt) {
+  maxContextLength;
+  memoryStrategy;
+  model;
+  constructor(systemPrompt, config) {
     this.systemPrompt = {
       type: "system",
       content: systemPrompt,
       timestamp: Date.now()
     };
+    this.maxContextLength = config?.maxContextLength ?? 1e5;
+    this.memoryStrategy = config?.memoryStrategy ?? "truncate";
+    this.model = config?.model;
   }
-  /**
-   * Reset memory, keeping only the system prompt.
-   */
+  /** Reset memory, keeping only the system prompt */
   reset() {
     this.steps = [];
   }
-  /**
-   * Add a task step.
-   */
+  /** Add a task step */
   addTask(task) {
     const step = {
       type: "task",
@@ -95,25 +118,19 @@ var AgentMemory = class {
     this.steps.push(step);
     return step;
   }
-  /**
-   * Create a new action step.
-   */
+  /** Create a new action step */
   createActionStep(stepNumber) {
     const step = {
       type: "action",
       stepNumber,
-      timing: {
-        startTime: Date.now()
-      },
+      timing: { startTime: Date.now() },
       modelInputMessages: [],
       timestamp: Date.now()
     };
     this.steps.push(step);
     return step;
   }
-  /**
-   * Add a final answer step.
-   */
+  /** Add a final answer step */
   addFinalAnswer(answer) {
     const step = {
       type: "final",
@@ -123,20 +140,17 @@ var AgentMemory = class {
     this.steps.push(step);
     return step;
   }
-  /**
-   * Get the last step.
-   */
+  /** Get the last step */
   getLastStep() {
     return this.steps[this.steps.length - 1];
   }
-  /**
-   * Get all action steps.
-   */
+  /** Get all action steps */
   getActionSteps() {
     return this.steps.filter((s) => s.type === "action");
   }
   /**
    * Convert memory to messages for LLM context.
+   * Handles both CodeAgent (observation-based) and ToolUseAgent (tool_call-based) patterns.
    */
   toMessages() {
     const messages = [];
@@ -153,23 +167,40 @@ var AgentMemory = class {
           });
           break;
         case "action":
-          if (step.modelOutputMessage) {
+          if (step.toolCalls && step.toolCalls.length > 0) {
             messages.push({
               role: "assistant",
-              content: step.modelOutputMessage.content
-            });
-          }
-          if (step.observation) {
-            messages.push({
-              role: "user",
-              content: step.observation
-            });
-          }
-          if (step.error) {
-            messages.push({
-              role: "user",
-              content: `Error: ${step.error.message}`
+              content: step.modelOutputMessage?.content ?? null,
+              toolCalls: step.toolCalls
             });
+            if (step.toolResults) {
+              for (const result of step.toolResults) {
+                messages.push({
+                  role: "tool",
+                  content: result.error ? `Error: ${result.error}` : typeof result.result === "string" ? result.result : JSON.stringify(result.result, null, 2),
+                  toolCallId: result.toolCallId
+                });
+              }
+            }
+          } else {
+            if (step.modelOutputMessage) {
+              messages.push({
+                role: "assistant",
+                content: step.modelOutputMessage.content
+              });
+            }
+            if (step.observation) {
+              messages.push({
+                role: "user",
+                content: step.observation
+              });
+            }
+            if (step.error && !step.observation) {
+              messages.push({
+                role: "user",
+                content: `Error: ${step.error.message}`
+              });
+            }
           }
           break;
         case "final":
@@ -179,8 +210,90 @@ var AgentMemory = class {
     return messages;
   }
   /**
-   * Get total token usage across all steps.
+   * Manage context length - truncate or compact if exceeded.
+   */
+  async manageContext() {
+    const messages = this.toMessages();
+    const tokenCount = estimateMessagesTokens(messages);
+    if (tokenCount <= this.maxContextLength) {
+      return;
+    }
+    if (this.memoryStrategy === "truncate") {
+      this.truncateOlderMessages();
+    } else if (this.memoryStrategy === "compact") {
+      await this.compactMessages();
+    }
+  }
+  /**
+   * Truncate older action steps to fit within context.
+   */
+  truncateOlderMessages() {
+    const actionSteps = this.getActionSteps();
+    if (actionSteps.length <= 2) return;
+    const targetTokens = this.maxContextLength * 0.75;
+    let currentTokens = estimateMessagesTokens(this.toMessages());
+    while (currentTokens > targetTokens && this.steps.length > 2) {
+      const idx = this.steps.findIndex((s) => s.type === "action");
+      if (idx === -1) break;
+      this.steps.splice(idx, 1);
+      currentTokens = estimateMessagesTokens(this.toMessages());
+    }
+  }
+  /**
+   * Compact older messages into a summary.
    */
+  async compactMessages() {
+    if (!this.model) {
+      this.truncateOlderMessages();
+      return;
+    }
+    const actionSteps = this.getActionSteps();
+    if (actionSteps.length <= 2) return;
+    const stepsToSummarize = actionSteps.slice(0, -2);
+    const summaryContent = stepsToSummarize.map((step) => {
+      const parts = [];
+      if (step.modelOutputMessage?.content) {
+        parts.push(`Action: ${step.modelOutputMessage.content.slice(0, 200)}`);
+      }
+      if (step.observation) {
+        parts.push(`Observation: ${step.observation.slice(0, 200)}`);
+      }
+      if (step.toolResults) {
+        for (const r of step.toolResults) {
+          const resultStr = typeof r.result === "string" ? r.result : JSON.stringify(r.result);
+          parts.push(`Tool ${r.toolName}: ${resultStr.slice(0, 200)}`);
+        }
+      }
+      return parts.join("\n");
+    }).join("\n---\n");
+    try {
+      const summaryResponse = await this.model.generate([
+        {
+          role: "system",
+          content: "Summarize the following agent execution history concisely, preserving key findings and results. Be brief but complete."
+        },
+        {
+          role: "user",
+          content: summaryContent
+        }
+      ]);
+      const recentSteps = this.steps.filter(
+        (s) => s.type === "task" || s.type === "final" || s.type === "action" && actionSteps.indexOf(s) >= actionSteps.length - 2
+      );
+      this.steps = [
+        {
+          type: "task",
+          task: `[Context Summary from previous steps]
+${summaryResponse.content}`,
+          timestamp: Date.now()
+        },
+        ...recentSteps
+      ];
+    } catch {
+      this.truncateOlderMessages();
+    }
+  }
+  /** Get total token usage across all steps */
   getTotalTokenUsage() {
     let inputTokens = 0;
     let outputTokens = 0;
@@ -196,9 +309,11 @@ var AgentMemory = class {
       totalTokens: inputTokens + outputTokens
     };
   }
-  /**
-   * Get a summary of the memory for logging.
-   */
+  /** Get current estimated token count */
+  getEstimatedTokenCount() {
+    return estimateMessagesTokens(this.toMessages());
+  }
+  /** Get a summary of the memory for logging */
   getSummary() {
     const actionSteps = this.getActionSteps();
     const lines = [
@@ -212,9 +327,7 @@ var AgentMemory = class {
     }
     return lines.join("\n");
   }
-  /**
-   * Serialize memory to JSON.
-   */
+  /** Serialize memory to JSON */
   toJSON() {
     return {
       systemPrompt: this.systemPrompt,
@@ -503,35 +616,24 @@ ${"\u2550".repeat(60)}
 };
 
 // src/agents/Agent.ts
+var DEFAULT_MAX_CONTEXT_LENGTH = 1e5;
 var Agent = class {
-  /**
-   * The LLM model for generation
-   */
+  /** The LLM model for generation */
   model;
-  /**
-   * Available tools mapped by name
-   */
+  /** Available tools mapped by name */
   tools = /* @__PURE__ */ new Map();
-  /**
-   * Agent memory tracking all steps
-   */
+  /** Agent memory tracking all steps */
   memory;
-  /**
-   * Logger for formatted output
-   */
+  /** Logger for formatted output */
   logger;
-  /**
-   * Configuration options
-   */
+  /** Configuration options */
   config;
-  /**
-   * Current step number
-   */
+  /** Current step number */
   currentStep = 0;
-  /**
-   * Whether the agent is currently running
-   */
+  /** Whether the agent is currently running */
   isRunning = false;
+  /** Whether the agent has been initialized at least once */
+  initialized = false;
   constructor(config) {
     this.model = config.model;
     this.logger = new AgentLogger(config.verboseLevel ?? 1 /* INFO */);
@@ -540,7 +642,14 @@ var Agent = class {
       codeExecutionDelay: config.codeExecutionDelay ?? 5e3,
       customInstructions: config.customInstructions ?? "",
       verboseLevel: config.verboseLevel ?? 1 /* INFO */,
-      streamOutputs: config.streamOutputs ?? true
+      streamOutputs: config.streamOutputs ?? true,
+      persistent: config.persistent ?? false,
+      maxContextLength: config.maxContextLength ?? DEFAULT_MAX_CONTEXT_LENGTH,
+      memoryStrategy: config.memoryStrategy ?? "truncate",
+      maxTokens: config.maxTokens,
+      temperature: config.temperature,
+      name: config.name ?? "Agent",
+      onEvent: config.onEvent
     };
     if (config.tools) {
       for (const tool of config.tools) {
@@ -550,27 +659,31 @@ var Agent = class {
   }
   /**
    * Run the agent on a task.
-   *
-   * @param task - The task description
-   * @param reset - Whether to reset memory before running
-   * @returns The final result
    */
   async run(task, reset = true) {
     const startTime = Date.now();
-    if (reset || !this.memory) {
+    const shouldReset = !this.config.persistent ? reset || !this.memory : !this.initialized;
+    if (shouldReset) {
       const systemPrompt = this.initializeSystemPrompt();
-      this.memory = new AgentMemory(systemPrompt);
+      this.memory = new AgentMemory(systemPrompt, {
+        maxContextLength: this.config.maxContextLength,
+        memoryStrategy: this.config.memoryStrategy,
+        model: this.model
+      });
       this.currentStep = 0;
+      this.initialized = true;
     }
     this.memory.addTask(task);
     this.isRunning = true;
-    this.logger.header(`\u{1F680} Starting Agent: ${task.slice(0, 50)}${task.length > 50 ? "..." : ""}`);
+    this.emitEvent("agent_start", { task, name: this.config.name });
+    this.logger.header(`Starting ${this.config.name}: ${task.slice(0, 80)}${task.length > 80 ? "..." : ""}`);
     let finalOutput = null;
     let isFinalAnswer = false;
     try {
       while (this.currentStep < this.config.maxSteps && this.isRunning) {
         this.currentStep++;
         this.logger.stepProgress(this.currentStep, this.config.maxSteps);
+        this.emitEvent("agent_step", { step: this.currentStep, maxSteps: this.config.maxSteps });
         const memoryStep = this.memory.createActionStep(this.currentStep);
         try {
           const actionOutput = await this.executeStep(memoryStep);
@@ -589,7 +702,9 @@ var Agent = class {
           memoryStep.timing.endTime = Date.now();
           memoryStep.timing.duration = memoryStep.timing.endTime - memoryStep.timing.startTime;
           this.logger.error("Step execution failed", error);
+          this.emitEvent("agent_error", { error: error.message, step: this.currentStep });
         }
+        await this.memory.manageContext();
       }
       if (!isFinalAnswer && this.currentStep >= this.config.maxSteps) {
         this.logger.warn(`Max steps (${this.config.maxSteps}) reached without final answer`);
@@ -601,13 +716,10 @@ var Agent = class {
     const duration = Date.now() - startTime;
     const tokenUsage = this.memory.getTotalTokenUsage();
     this.memory.addFinalAnswer(finalOutput);
+    this.emitEvent("agent_end", { output: finalOutput, duration, tokenUsage });
     this.logger.info(`
-\u23F1\uFE0F Total time: ${(duration / 1e3).toFixed(2)}s`);
-    this.logger.info(`\u{1F4CA} Total tokens: ${tokenUsage.totalTokens}`);
-    const logPath = this.logger.getLogPath();
-    if (logPath) {
-      this.logger.info(`\u{1F4C1} Log file: ${logPath}`);
-    }
+Total time: ${(duration / 1e3).toFixed(2)}s`);
+    this.logger.info(`Total tokens: ${tokenUsage.totalTokens}`);
     return {
       output: finalOutput,
       steps: this.memory.steps,
@@ -623,49 +735,48 @@ var Agent = class {
     const messages = this.memory.toMessages();
     messages.push({
       role: "user",
-      content: `You have reached the maximum number of steps. Based on your work so far, provide the best answer you can for the original task: "${task}"
-
-Summarize what you accomplished and provide a final answer. Call final_answer() with your response.`
+      content: `You have reached the maximum number of steps. Based on your work so far, provide the best answer you can for the original task: "${task}". Summarize what you accomplished and provide a final answer.`
+    });
+    const response = await this.model.generate(messages, {
+      maxTokens: this.config.maxTokens,
+      temperature: this.config.temperature
     });
-    const response = await this.model.generate(messages);
     return response.content;
   }
-  /**
-   * Stop the agent.
-   */
+  /** Emit an orchestration event */
+  emitEvent(type, data) {
+    if (this.config.onEvent) {
+      this.config.onEvent({ type, data });
+    }
+  }
+  /** Stop the agent */
   stop() {
     this.isRunning = false;
     this.logger.info("Agent stopped by user");
   }
-  /**
-   * Get the current memory.
-   */
+  /** Get the current memory */
   getMemory() {
     return this.memory;
   }
-  /**
-   * Get registered tools.
-   */
+  /** Get registered tools */
   getTools() {
     return this.tools;
   }
-  /**
-   * Add a tool to the agent.
-   */
+  /** Add a tool to the agent */
   addTool(tool) {
     this.tools.set(tool.name, tool);
   }
-  /**
-   * Remove a tool from the agent.
-   */
+  /** Remove a tool from the agent */
   removeTool(name) {
     return this.tools.delete(name);
   }
-  /**
-   * Sleep for a specified duration.
-   */
+  /** Get agent name */
+  getName() {
+    return this.config.name;
+  }
+  /** Sleep for a specified duration */
   sleep(ms) {
-    return new Promise((resolve2) => setTimeout(resolve2, ms));
+    return new Promise((resolve5) => setTimeout(resolve5, ms));
   }
 };
 
@@ -1149,9 +1260,6 @@ var Tool = class {
       }
       providedKeys.delete(key);
     }
-    if (providedKeys.size > 0) {
-      console.warn(`Unknown arguments provided to ${this.name}: ${[...providedKeys].join(", ")}`);
-    }
   }
   /**
    * Check if a value matches the expected type.
@@ -1194,6 +1302,62 @@ ${argsDoc}
 async function ${this.name}(${argsSignature}): Promise<${this.typeToJsType(this.outputType)}> { ... }
 `.trim();
   }
+  /**
+   * Generate an OpenAI-compatible tool definition for function calling.
+   */
+  toOpenAITool() {
+    const properties = {};
+    const required = [];
+    for (const [key, input] of Object.entries(this.inputs)) {
+      const prop = {
+        type: this.typeToJsonSchemaType(input.type),
+        description: input.description
+      };
+      if (input.enum) {
+        prop.enum = input.enum;
+      }
+      if (input.default !== void 0) {
+        prop.default = input.default;
+      }
+      properties[key] = prop;
+      if (input.required !== false) {
+        required.push(key);
+      }
+    }
+    return {
+      type: "function",
+      function: {
+        name: this.name,
+        description: this.description,
+        parameters: {
+          type: "object",
+          properties,
+          ...required.length > 0 && { required }
+        }
+      }
+    };
+  }
+  /**
+   * Convert tool input type to JSON Schema type.
+   */
+  typeToJsonSchemaType(type) {
+    switch (type) {
+      case "string":
+        return "string";
+      case "number":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "array":
+        return "array";
+      case "object":
+        return "object";
+      case "any":
+        return "string";
+      default:
+        return "string";
+    }
+  }
   /**
    * Convert tool input type to JS/TS type string.
    */
@@ -1281,12 +1445,12 @@ var UserInputTool = class extends Tool {
       input: process.stdin,
       output: process.stdout
     });
-    return new Promise((resolve2) => {
+    return new Promise((resolve5) => {
       rl.question(`
 [Agent asks]: ${question}
 Your response: `, (answer) => {
         rl.close();
-        resolve2(answer);
+        resolve5(answer);
       });
     });
   }
@@ -1551,7 +1715,9 @@ ${result.error.message}`;
       this.logger.subheader("Agent thinking...");
       let fullContent = "";
       const generator = this.model.generateStream(messages, {
-        stopSequences: ["Observation:", "Observation:\n"]
+        stopSequences: ["Observation:", "Observation:\n"],
+        maxTokens: this.config.maxTokens,
+        temperature: this.config.temperature
       });
       for await (const chunk of generator) {
         this.logger.streamChar(chunk);
@@ -1565,7 +1731,9 @@ ${result.error.message}`;
     } else {
       this.logger.subheader("Agent thinking...");
       return this.model.generate(messages, {
-        stopSequences: ["Observation:", "Observation:\n"]
+        stopSequences: ["Observation:", "Observation:\n"],
+        maxTokens: this.config.maxTokens,
+        temperature: this.config.temperature
       });
     }
   }
@@ -1621,6 +1789,263 @@ ${parts.join("\n\n")}`;
   }
 };
 
+// src/prompts/toolUseAgent.ts
+function generateToolUseSystemPrompt(variables) {
+  const { tools, customInstructions, hasSubAgents, hasFileTools } = variables;
+  let contentGuidelines = "";
+  if (hasFileTools) {
+    contentGuidelines += `
+## Content Output Guidelines
+
+When you produce long-form content (reports, articles, analyses, or any output longer than a few paragraphs):
+1. **Save to file**: Use \`write_file\` to save the full content to a descriptively-named file (e.g., \`research_report.md\`, \`analysis_results.md\`).
+2. **Return summary + filename**: In your \`final_answer\`, provide a brief summary of what you produced AND the filename where the full content is saved. Example: "Completed the research report covering X, Y, Z. Full report saved to: research_report.md"
+
+This ensures managing agents can access your full output via \`read_file\` without it being truncated in message passing.
+`;
+  }
+  if (hasSubAgents) {
+    contentGuidelines += `
+## Working with Sub-Agents
+
+When you delegate tasks to sub-agents:
+- Sub-agents return a **summary and filename** rather than the full content of long-form outputs.
+- To access the full content a sub-agent produced, use \`read_file\` with the filename they provide.
+- **Do NOT re-invoke a sub-agent to retrieve content it already created.** Instead, read the file directly.
+- When composing your own final output from sub-agent results, read their files as needed and synthesize.
+`;
+  }
+  if (hasSubAgents && hasFileTools) {
+    contentGuidelines += `
+## When You Are Both a Manager and a Sub-Agent
+
+If you manage sub-agents AND are yourself delegated tasks by a parent agent:
+- Follow the sub-agent content guidelines: save your own long-form output to a file, return summary + filename.
+- Follow the manager guidelines: read sub-agent output files rather than re-calling them.
+`;
+  }
+  return `You are an expert assistant and problem-solving agent. You solve tasks by reasoning step by step and using the tools available to you.
+
+## How You Work
+
+You follow a ReAct (Reasoning + Acting) framework:
+1. **Think**: Analyze the current situation and decide what to do next
+2. **Act**: Call one or more tools to perform actions
+3. **Observe**: Review the results of your tool calls
+4. Repeat until you have the final answer
+
+## Available Tools
+
+${tools}
+
+## Rules
+
+1. **Always use final_answer**: When you have the complete answer, call the \`final_answer\` tool to return it. This is mandatory - you must always end by calling final_answer.
+
+2. **Think before acting**: Provide your reasoning in the content of your response before making tool calls. This helps track your thought process.
+
+3. **One logical action per step**: Focus on one logical action per step. You may call multiple tools in a single step if they are independent, but avoid chaining dependent operations without reviewing intermediate results.
+
+4. **Handle errors gracefully**: If a tool call fails, analyze the error and try a different approach.
+
+5. **Be concise**: Keep your reasoning brief and focused. Don't over-explain.
+
+6. **Use the right tool**: Choose the most appropriate tool for each action. Don't try to accomplish something a tool can do through other means.
+${contentGuidelines}
+${customInstructions ? `## Additional Instructions
+
+${customInstructions}` : ""}
+
+Now, let's solve the task step by step. Think carefully about what tools to use and in what order.`;
+}
+function formatToolDescriptions(tools) {
+  return tools.map((tool) => {
+    const params = Object.entries(tool.inputs).map(([name, input]) => {
+      const req = input.required !== false ? " (required)" : " (optional)";
+      return `  - ${name}${req}: ${input.description}`;
+    }).join("\n");
+    return `### ${tool.name}
+${tool.description}
+Parameters:
+${params}`;
+  }).join("\n\n");
+}
+
+// src/agents/ToolUseAgent.ts
+var ToolUseAgent = class extends Agent {
+  parallelToolCalls;
+  constructor(config) {
+    super(config);
+    this.parallelToolCalls = config.parallelToolCalls ?? true;
+    if (!this.tools.has("final_answer")) {
+      this.tools.set("final_answer", new FinalAnswerTool());
+    }
+  }
+  /**
+   * Initialize the system prompt with tool descriptions.
+   */
+  initializeSystemPrompt() {
+    const toolList = Array.from(this.tools.values());
+    const toolDescriptions = formatToolDescriptions(
+      toolList.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputs: t.inputs
+      }))
+    );
+    const toolNames = new Set(Array.from(this.tools.keys()));
+    const hasSubAgents = toolList.some((t) => t.constructor.name === "AgentTool");
+    const hasFileTools = toolNames.has("read_file") || toolNames.has("write_file") || toolNames.has("read") || toolNames.has("write");
+    return generateToolUseSystemPrompt({
+      tools: toolDescriptions,
+      customInstructions: this.config.customInstructions,
+      hasSubAgents,
+      hasFileTools
+    });
+  }
+  /**
+   * Execute a single step: send messages with tool definitions, process tool calls.
+   */
+  async executeStep(memoryStep) {
+    const messages = this.memory.toMessages();
+    memoryStep.modelInputMessages = [...messages];
+    const actionSteps = this.memory.getActionSteps();
+    const prevStep = actionSteps.length >= 2 ? actionSteps[actionSteps.length - 2] : void 0;
+    if (prevStep?.error) {
+      messages.push({
+        role: "user",
+        content: `Your previous action encountered an error: ${prevStep.error.message}
+Please try a different approach.`
+      });
+    }
+    const toolDefinitions = Array.from(this.tools.values()).map((t) => t.toOpenAITool());
+    this.logger.subheader("Agent thinking...");
+    const response = await this.model.generate(messages, {
+      toolDefinitions,
+      maxTokens: this.config.maxTokens,
+      temperature: this.config.temperature
+    });
+    memoryStep.modelOutputMessage = response;
+    memoryStep.tokenUsage = response.tokenUsage;
+    if (response.content && response.content.trim()) {
+      this.logger.reasoning(response.content.trim());
+    }
+    if (!response.toolCalls || response.toolCalls.length === 0) {
+      this.logger.warn("No tool calls in response. Prompting model to use tools.");
+      memoryStep.observation = "You must use tools to complete the task. Please call the appropriate tool(s). When you have the final answer, call the final_answer tool.";
+      return { output: null, isFinalAnswer: false };
+    }
+    memoryStep.toolCalls = response.toolCalls;
+    const toolResults = await this.processToolCalls(response.toolCalls);
+    memoryStep.toolResults = toolResults;
+    for (const result of toolResults) {
+      if (result.toolName === "final_answer") {
+        return { output: result.result, isFinalAnswer: true };
+      }
+    }
+    for (const result of toolResults) {
+      if (result.error) {
+        this.logger.error(`Tool ${result.toolName} failed: ${result.error}`);
+        this.emitEvent("agent_error", { tool: result.toolName, error: result.error });
+      } else {
+        const resultStr = typeof result.result === "string" ? result.result : JSON.stringify(result.result, null, 2);
+        this.logger.output(`[${result.toolName}]: ${resultStr.slice(0, 500)}${resultStr.length > 500 ? "..." : ""}`);
+        this.emitEvent("agent_observation", { tool: result.toolName, result: resultStr.slice(0, 500) });
+      }
+    }
+    return { output: null, isFinalAnswer: false };
+  }
+  /**
+   * Process tool calls from the model response.
+   */
+  async processToolCalls(toolCalls) {
+    const results = [];
+    const executeTool = async (tc) => {
+      const toolName = tc.function.name;
+      const tool = this.tools.get(toolName);
+      if (!tool) {
+        return {
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error: `Unknown tool: ${toolName}. Available tools: ${Array.from(this.tools.keys()).join(", ")}`
+        };
+      }
+      let args;
+      try {
+        args = typeof tc.function.arguments === "string" ? JSON.parse(tc.function.arguments) : tc.function.arguments;
+      } catch {
+        return {
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error: `Failed to parse tool arguments: ${tc.function.arguments}`
+        };
+      }
+      this.logger.info(`  Calling tool: ${toolName}(${JSON.stringify(args).slice(0, 100)}...)`);
+      this.emitEvent("agent_tool_call", { tool: toolName, args });
+      try {
+        const result = await tool.call(args);
+        return {
+          toolCallId: tc.id,
+          toolName,
+          result
+        };
+      } catch (error) {
+        return {
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error: `Tool execution error: ${error.message}`
+        };
+      }
+    };
+    if (this.parallelToolCalls) {
+      const promises = toolCalls.map((tc) => executeTool(tc));
+      const resolvedResults = await Promise.all(promises);
+      results.push(...resolvedResults);
+    } else {
+      for (const tc of toolCalls) {
+        results.push(await executeTool(tc));
+      }
+    }
+    return results;
+  }
+  /**
+   * Override provideFinalAnswer to use tool calling format.
+   */
+  async provideFinalAnswer(task) {
+    this.logger.subheader("Generating final answer from accumulated context");
+    const messages = this.memory.toMessages();
+    messages.push({
+      role: "user",
+      content: `You have reached the maximum number of steps. Based on your work so far, provide the best answer for the task: "${task}". Call the final_answer tool with your response.`
+    });
+    const toolDefinitions = [new FinalAnswerTool().toOpenAITool()];
+    const response = await this.model.generate(messages, {
+      toolDefinitions,
+      maxTokens: this.config.maxTokens,
+      temperature: this.config.temperature
+    });
+    if (response.toolCalls && response.toolCalls.length > 0) {
+      const tc = response.toolCalls[0];
+      try {
+        const args = typeof tc.function.arguments === "string" ? JSON.parse(tc.function.arguments) : tc.function.arguments;
+        return args.answer;
+      } catch {
+        return response.content;
+      }
+    }
+    return response.content;
+  }
+  /**
+   * Add a tool, which can also be an Agent instance (auto-wraps with AgentTool).
+   */
+  addTool(tool) {
+    super.addTool(tool);
+  }
+};
+
 // src/models/Model.ts
 var Model = class {
   /**
@@ -1650,25 +2075,18 @@ var Model = class {
 
 // src/models/OpenAIModel.ts
 var import_openai = __toESM(require("openai"));
-var DEFAULT_CONFIG = {
-  modelId: "anthropic/claude-sonnet-4.5",
-  baseUrl: "https://openrouter.ai/api/v1",
-  maxTokens: 65e3,
-  temperature: 1,
-  timeout: 12e4
-};
+var DEFAULT_MODEL_ID = "anthropic/claude-sonnet-4.5";
+var DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+var DEFAULT_TIMEOUT = 12e4;
 var OpenAIModel = class extends Model {
   modelId;
   client;
   config;
   constructor(config = {}) {
     super();
-    this.config = {
-      ...DEFAULT_CONFIG,
-      ...config
-    };
-    this.modelId = this.config.modelId ?? DEFAULT_CONFIG.modelId;
-    const apiKey = this.config.apiKey ?? process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY;
+    this.config = config;
+    this.modelId = config.modelId ?? DEFAULT_MODEL_ID;
+    const apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY;
     if (!apiKey) {
       throw new Error(
         "API key is required. Set OPENAI_API_KEY or OPENROUTER_API_KEY environment variable, or pass apiKey in config."
@@ -1676,22 +2094,40 @@ var OpenAIModel = class extends Model {
     }
     this.client = new import_openai.default({
       apiKey,
-      baseURL: this.config.baseUrl,
-      timeout: this.config.timeout,
-      defaultHeaders: this.config.defaultHeaders
+      baseURL: config.baseUrl ?? DEFAULT_BASE_URL,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT,
+      defaultHeaders: config.defaultHeaders
     });
   }
   /**
-   * Generate a response from the model.
+   * Generate a response from the model (supports tool calling).
    */
   async generate(messages, options = {}) {
     const formattedMessages = this.formatMessages(messages);
+    const requestParams = {
+      model: this.modelId,
+      messages: formattedMessages
+    };
+    const maxTokens = options.maxTokens ?? this.config.maxTokens;
+    if (maxTokens !== void 0) {
+      requestParams.max_tokens = maxTokens;
+    }
+    const temperature = options.temperature ?? this.config.temperature;
+    if (temperature !== void 0) {
+      requestParams.temperature = temperature;
+    }
+    if (options.stopSequences) {
+      requestParams.stop = options.stopSequences;
+    }
+    if (options.toolDefinitions && options.toolDefinitions.length > 0) {
+      requestParams.tools = options.toolDefinitions;
+    } else if (options.tools && options.tools.length > 0) {
+      requestParams.tools = options.tools.map((t) => t.toOpenAITool());
+    }
     const response = await this.client.chat.completions.create({
+      ...requestParams,
       model: this.modelId,
-      messages: formattedMessages,
-      max_tokens: options.maxTokens ?? this.config.maxTokens,
-      temperature: options.temperature ?? this.config.temperature,
-      ...options.stopSequences && { stop: options.stopSequences }
+      messages: formattedMessages
     });
     const choice = response.choices[0];
     const message = choice?.message;
@@ -1700,12 +2136,21 @@ var OpenAIModel = class extends Model {
     }
     const tokenUsage = response.usage ? {
       inputTokens: response.usage.prompt_tokens,
-      outputTokens: response.usage.completion_tokens,
+      outputTokens: response.usage.completion_tokens ?? 0,
       totalTokens: response.usage.total_tokens
     } : void 0;
+    const toolCalls = message.tool_calls?.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: {
+        name: tc.function.name,
+        arguments: tc.function.arguments
+      }
+    }));
     return {
       role: "assistant",
       content: message.content ?? "",
+      toolCalls,
       tokenUsage
     };
   }
@@ -1714,12 +2159,26 @@ var OpenAIModel = class extends Model {
    */
   async *generateStream(messages, options = {}) {
     const formattedMessages = this.formatMessages(messages);
+    const requestParams = {
+      model: this.modelId,
+      messages: formattedMessages,
+      stream: true
+    };
+    const maxTokens = options.maxTokens ?? this.config.maxTokens;
+    if (maxTokens !== void 0) {
+      requestParams.max_tokens = maxTokens;
+    }
+    const temperature = options.temperature ?? this.config.temperature;
+    if (temperature !== void 0) {
+      requestParams.temperature = temperature;
+    }
+    if (options.stopSequences) {
+      requestParams.stop = options.stopSequences;
+    }
     const stream = await this.client.chat.completions.create({
+      ...requestParams,
       model: this.modelId,
       messages: formattedMessages,
-      max_tokens: options.maxTokens ?? this.config.maxTokens,
-      temperature: options.temperature ?? this.config.temperature,
-      ...options.stopSequences && { stop: options.stopSequences },
       stream: true
     });
     let fullContent = "";
@@ -1736,16 +2195,37 @@ var OpenAIModel = class extends Model {
     };
   }
   /**
-   * Format messages for the OpenAI API.
+   * Format messages for the OpenAI API, including tool call/response messages.
    */
   formatMessages(messages) {
     return messages.map((msg) => {
+      if (msg.role === "tool" && msg.toolCallId) {
+        return {
+          role: "tool",
+          content: msg.content ?? "",
+          tool_call_id: msg.toolCallId
+        };
+      }
       if (msg.role === "tool") {
         return {
           role: "user",
           content: msg.content ?? ""
         };
       }
+      if (msg.role === "assistant" && msg.toolCalls && msg.toolCalls.length > 0) {
+        return {
+          role: "assistant",
+          content: msg.content || null,
+          tool_calls: msg.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: {
+              name: tc.function.name,
+              arguments: typeof tc.function.arguments === "string" ? tc.function.arguments : JSON.stringify(tc.function.arguments)
+            }
+          }))
+        };
+      }
       return {
         role: msg.role,
         content: msg.content ?? ""
@@ -1828,6 +2308,819 @@ async function ${this.name}(task: string): Promise<string> { ... }
 function agentAsTool(agent, options) {
   return new AgentTool({ agent, ...options });
 }
+
+// src/tools/ReadFileTool.ts
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var ReadFileTool = class extends Tool {
+  name = "read_file";
+  description = "Read the contents of a file at the specified path. Returns the file content as a string.";
+  inputs = {
+    path: {
+      type: "string",
+      description: "The file path to read (absolute or relative to working directory)",
+      required: true
+    },
+    encoding: {
+      type: "string",
+      description: "File encoding (default: utf-8)",
+      required: false,
+      default: "utf-8"
+    }
+  };
+  outputType = "string";
+  workingDirectory;
+  constructor(config) {
+    super();
+    this.workingDirectory = config?.workingDirectory ?? process.cwd();
+  }
+  async execute(args) {
+    const filePath = args.path;
+    const encoding = args.encoding ?? "utf-8";
+    const resolvedPath = path3.isAbsolute(filePath) ? filePath : path3.resolve(this.workingDirectory, filePath);
+    if (!fs3.existsSync(resolvedPath)) {
+      throw new Error(`File not found: ${resolvedPath}`);
+    }
+    const stat = fs3.statSync(resolvedPath);
+    if (stat.isDirectory()) {
+      throw new Error(`Path is a directory, not a file: ${resolvedPath}`);
+    }
+    const content = fs3.readFileSync(resolvedPath, encoding);
+    const maxLength = 1e5;
+    if (content.length > maxLength) {
+      return content.slice(0, maxLength) + `
+
+[... truncated, file is ${content.length} characters total]`;
+    }
+    return content;
+  }
+};
+
+// src/tools/WriteFileTool.ts
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var WriteFileTool = class extends Tool {
+  name = "write_file";
+  description = "Write content to a file at the specified path. Creates the file if it does not exist, and creates parent directories as needed. Overwrites existing content by default.";
+  inputs = {
+    path: {
+      type: "string",
+      description: "The file path to write to (absolute or relative to working directory)",
+      required: true
+    },
+    content: {
+      type: "string",
+      description: "The content to write to the file",
+      required: true
+    },
+    append: {
+      type: "boolean",
+      description: "If true, append to the file instead of overwriting (default: false)",
+      required: false,
+      default: false
+    }
+  };
+  outputType = "string";
+  workingDirectory;
+  constructor(config) {
+    super();
+    this.workingDirectory = config?.workingDirectory ?? process.cwd();
+  }
+  async execute(args) {
+    const filePath = args.path;
+    const content = args.content;
+    const append = args.append ?? false;
+    const resolvedPath = path4.isAbsolute(filePath) ? filePath : path4.resolve(this.workingDirectory, filePath);
+    const dir = path4.dirname(resolvedPath);
+    if (!fs4.existsSync(dir)) {
+      fs4.mkdirSync(dir, { recursive: true });
+    }
+    if (append) {
+      fs4.appendFileSync(resolvedPath, content, "utf-8");
+      return `Successfully appended ${content.length} characters to ${resolvedPath}`;
+    } else {
+      fs4.writeFileSync(resolvedPath, content, "utf-8");
+      return `Successfully wrote ${content.length} characters to ${resolvedPath}`;
+    }
+  }
+};
+
+// src/tools/CurlTool.ts
+var CurlTool = class extends Tool {
+  name = "curl";
+  description = "Make HTTP requests to any URL. Supports GET and POST methods with custom headers and body. Returns the response body as text.";
+  inputs = {
+    url: {
+      type: "string",
+      description: "The URL to request",
+      required: true
+    },
+    method: {
+      type: "string",
+      description: "HTTP method: GET or POST (default: GET)",
+      required: false,
+      default: "GET",
+      enum: ["GET", "POST"]
+    },
+    headers: {
+      type: "object",
+      description: 'Optional HTTP headers as key-value pairs (e.g., {"Content-Type": "application/json"})',
+      required: false
+    },
+    body: {
+      type: "string",
+      description: "Request body for POST requests (typically JSON string)",
+      required: false
+    }
+  };
+  outputType = "string";
+  timeout;
+  constructor(config) {
+    super();
+    this.timeout = config?.timeout ?? 3e4;
+  }
+  async execute(args) {
+    const url = args.url;
+    const method = (args.method ?? "GET").toUpperCase();
+    const headers = args.headers ?? {};
+    const body = args.body;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const fetchOptions = {
+        method,
+        headers,
+        signal: controller.signal
+      };
+      if (method === "POST" && body) {
+        fetchOptions.body = body;
+        if (!headers["Content-Type"] && !headers["content-type"]) {
+          fetchOptions.headers["Content-Type"] = "application/json";
+        }
+      }
+      const response = await fetch(url, fetchOptions);
+      const responseText = await response.text();
+      const statusLine = `HTTP ${response.status} ${response.statusText}`;
+      const maxLength = 5e4;
+      const truncatedBody = responseText.length > maxLength ? responseText.slice(0, maxLength) + `
+
+[... truncated, response is ${responseText.length} characters total]` : responseText;
+      return `${statusLine}
+
+${truncatedBody}`;
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new Error(`Request timed out after ${this.timeout}ms: ${url}`);
+      }
+      throw new Error(`HTTP request failed: ${error.message}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/tools/ExaSearchTool.ts
+var ExaSearchTool = class extends Tool {
+  name = "exa_search";
+  description = "Search the web using Exa.ai semantic search. Returns relevant web pages with titles, URLs, and optionally content snippets. Use this for finding information, research, and fact-checking.";
+  inputs = {
+    query: {
+      type: "string",
+      description: "The search query. Be specific and descriptive for best results.",
+      required: true
+    },
+    numResults: {
+      type: "number",
+      description: "Number of results to return (default: 10, max: 30)",
+      required: false,
+      default: 10
+    },
+    type: {
+      type: "string",
+      description: 'Search type: "auto" (default), "neural" (embeddings-based), or "keyword"',
+      required: false,
+      default: "auto",
+      enum: ["auto", "neural", "keyword"]
+    },
+    category: {
+      type: "string",
+      description: 'Optional category filter: "research paper", "news", "pdf", "github", "tweet", "company", "blog"',
+      required: false
+    },
+    includeDomains: {
+      type: "array",
+      description: 'Only include results from these domains (e.g., ["arxiv.org", "github.com"])',
+      required: false
+    },
+    excludeDomains: {
+      type: "array",
+      description: "Exclude results from these domains",
+      required: false
+    },
+    startPublishedDate: {
+      type: "string",
+      description: 'Filter results published after this ISO 8601 date (e.g., "2024-01-01")',
+      required: false
+    }
+  };
+  outputType = "string";
+  apiKey;
+  constructor(config) {
+    super();
+    this.apiKey = config?.apiKey ?? process.env.EXA_API_KEY ?? "";
+  }
+  async setup() {
+    if (!this.apiKey) {
+      throw new Error("EXA_API_KEY is required. Set it as an environment variable or pass it in the config.");
+    }
+    this.isSetup = true;
+  }
+  async execute(args) {
+    const query = args.query;
+    const numResults = Math.min(args.numResults ?? 10, 30);
+    const type = args.type ?? "auto";
+    const requestBody = {
+      query,
+      numResults,
+      type,
+      text: { maxCharacters: 1e3 }
+    };
+    if (args.category) requestBody.category = args.category;
+    if (args.includeDomains) requestBody.includeDomains = args.includeDomains;
+    if (args.excludeDomains) requestBody.excludeDomains = args.excludeDomains;
+    if (args.startPublishedDate) requestBody.startPublishedDate = args.startPublishedDate;
+    const response = await fetch("https://api.exa.ai/search", {
+      method: "POST",
+      headers: {
+        "x-api-key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(requestBody)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Exa search failed (${response.status}): ${errorText}`);
+    }
+    const data = await response.json();
+    if (!data.results || data.results.length === 0) {
+      return "No results found for the query.";
+    }
+    const formattedResults = data.results.map((result, i) => {
+      const parts = [`[${i + 1}] ${result.title ?? "Untitled"}`];
+      parts.push(`    URL: ${result.url}`);
+      if (result.publishedDate) parts.push(`    Date: ${result.publishedDate}`);
+      if (result.author) parts.push(`    Author: ${result.author}`);
+      if (result.text) {
+        const snippet = result.text.slice(0, 300).trim();
+        parts.push(`    Snippet: ${snippet}${result.text.length > 300 ? "..." : ""}`);
+      }
+      return parts.join("\n");
+    }).join("\n\n");
+    return `Search results for "${query}" (${data.results.length} results):
+
+${formattedResults}`;
+  }
+};
+
+// src/tools/ExaGetContentsTool.ts
+var ExaGetContentsTool = class extends Tool {
+  name = "exa_get_contents";
+  description = "Get the full text content of one or more web pages using Exa.ai. Returns cleaned, readable text extracted from the HTML. Use this to read articles, documentation, or any web page content.";
+  inputs = {
+    urls: {
+      type: "array",
+      description: "Array of URLs to fetch content from (max 10)",
+      required: true
+    },
+    maxCharacters: {
+      type: "number",
+      description: "Maximum characters of content to return per page (default: 10000)",
+      required: false,
+      default: 1e4
+    },
+    livecrawl: {
+      type: "string",
+      description: 'Crawl strategy: "fallback" (use cache, fetch live if unavailable), "always" (always fetch live), "never" (cache only). Default: "fallback"',
+      required: false,
+      default: "fallback",
+      enum: ["fallback", "always", "never"]
+    }
+  };
+  outputType = "string";
+  apiKey;
+  constructor(config) {
+    super();
+    this.apiKey = config?.apiKey ?? process.env.EXA_API_KEY ?? "";
+  }
+  async setup() {
+    if (!this.apiKey) {
+      throw new Error("EXA_API_KEY is required. Set it as an environment variable or pass it in the config.");
+    }
+    this.isSetup = true;
+  }
+  async execute(args) {
+    const urls = args.urls.slice(0, 10);
+    const maxCharacters = args.maxCharacters ?? 1e4;
+    const livecrawl = args.livecrawl ?? "fallback";
+    const requestBody = {
+      urls,
+      text: { maxCharacters },
+      livecrawl
+    };
+    const response = await fetch("https://api.exa.ai/contents", {
+      method: "POST",
+      headers: {
+        "x-api-key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(requestBody)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Exa get contents failed (${response.status}): ${errorText}`);
+    }
+    const data = await response.json();
+    if (!data.results || data.results.length === 0) {
+      return "No content could be retrieved from the provided URLs.";
+    }
+    const formattedResults = data.results.map((result) => {
+      const parts = [`## ${result.title ?? result.url}`];
+      parts.push(`URL: ${result.url}`);
+      if (result.author) parts.push(`Author: ${result.author}`);
+      if (result.publishedDate) parts.push(`Date: ${result.publishedDate}`);
+      parts.push("");
+      if (result.text) {
+        parts.push(result.text);
+      } else {
+        parts.push("[No text content available]");
+      }
+      return parts.join("\n");
+    }).join("\n\n---\n\n");
+    return formattedResults;
+  }
+};
+
+// src/tools/ExaResearchTool.ts
+var ExaResearchTool = class extends Tool {
+  name = "exa_research";
+  description = "Perform deep research on a single topic using Exa.ai. Searches for relevant sources, retrieves their content, and finds similar pages for comprehensive coverage. Returns a structured research summary with sources. Use this for thorough research on any topic.";
+  inputs = {
+    topic: {
+      type: "string",
+      description: "The research topic or question to investigate",
+      required: true
+    },
+    numSources: {
+      type: "number",
+      description: "Number of primary sources to retrieve (default: 5, max: 10)",
+      required: false,
+      default: 5
+    },
+    category: {
+      type: "string",
+      description: 'Optional category: "research paper", "news", "blog", "company"',
+      required: false
+    },
+    includeDomains: {
+      type: "array",
+      description: "Only include results from these domains",
+      required: false
+    },
+    startPublishedDate: {
+      type: "string",
+      description: "Only include results published after this date (ISO 8601)",
+      required: false
+    }
+  };
+  outputType = "string";
+  apiKey;
+  constructor(config) {
+    super();
+    this.apiKey = config?.apiKey ?? process.env.EXA_API_KEY ?? "";
+  }
+  async setup() {
+    if (!this.apiKey) {
+      throw new Error("EXA_API_KEY is required. Set it as an environment variable or pass it in the config.");
+    }
+    this.isSetup = true;
+  }
+  async execute(args) {
+    const topic = args.topic;
+    const numSources = Math.min(args.numSources ?? 5, 10);
+    const searchBody = {
+      query: topic,
+      numResults: numSources,
+      type: "auto",
+      text: { maxCharacters: 3e3 }
+    };
+    if (args.category) searchBody.category = args.category;
+    if (args.includeDomains) searchBody.includeDomains = args.includeDomains;
+    if (args.startPublishedDate) searchBody.startPublishedDate = args.startPublishedDate;
+    const searchResponse = await fetch("https://api.exa.ai/search", {
+      method: "POST",
+      headers: {
+        "x-api-key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(searchBody)
+    });
+    if (!searchResponse.ok) {
+      const errorText = await searchResponse.text();
+      throw new Error(`Exa research search failed (${searchResponse.status}): ${errorText}`);
+    }
+    const searchData = await searchResponse.json();
+    if (!searchData.results || searchData.results.length === 0) {
+      return `No research sources found for topic: "${topic}"`;
+    }
+    let similarResults = [];
+    if (searchData.results.length > 0) {
+      try {
+        const similarBody = {
+          url: searchData.results[0].url,
+          numResults: 3,
+          text: { maxCharacters: 2e3 }
+        };
+        const similarResponse = await fetch("https://api.exa.ai/findSimilar", {
+          method: "POST",
+          headers: {
+            "x-api-key": this.apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(similarBody)
+        });
+        if (similarResponse.ok) {
+          const similarData = await similarResponse.json();
+          similarResults = similarData.results ?? [];
+        }
+      } catch {
+      }
+    }
+    const allSources = [...searchData.results, ...similarResults];
+    const seenUrls = /* @__PURE__ */ new Set();
+    const uniqueSources = allSources.filter((s) => {
+      if (seenUrls.has(s.url)) return false;
+      seenUrls.add(s.url);
+      return true;
+    });
+    const sections = [];
+    sections.push(`# Research: ${topic}
+`);
+    sections.push(`Found ${uniqueSources.length} sources.
+`);
+    sections.push("## Key Sources\n");
+    for (let i = 0; i < uniqueSources.length; i++) {
+      const source = uniqueSources[i];
+      sections.push(`### ${i + 1}. ${source.title ?? "Untitled"}`);
+      sections.push(`URL: ${source.url}`);
+      if ("publishedDate" in source && source.publishedDate) {
+        sections.push(`Date: ${source.publishedDate}`);
+      }
+      if ("author" in source && source.author) {
+        sections.push(`Author: ${source.author}`);
+      }
+      if (source.text) {
+        sections.push(`
+Content:
+${source.text.slice(0, 2e3)}`);
+      }
+      sections.push("");
+    }
+    sections.push("## Source URLs\n");
+    uniqueSources.forEach((s, i) => {
+      sections.push(`${i + 1}. ${s.url}`);
+    });
+    return sections.join("\n");
+  }
+};
+
+// src/orchestrator/YAMLLoader.ts
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+var import_yaml = __toESM(require("yaml"));
+var TOOL_REGISTRY = {
+  read_file: ReadFileTool,
+  write_file: WriteFileTool,
+  curl: CurlTool,
+  exa_search: ExaSearchTool,
+  exa_get_contents: ExaGetContentsTool,
+  exa_research: ExaResearchTool,
+  final_answer: FinalAnswerTool
+};
+var YAMLLoader = class {
+  customTools = /* @__PURE__ */ new Map();
+  /**
+   * Register a custom tool type for use in YAML definitions.
+   */
+  registerToolType(typeName, toolClass) {
+    this.customTools.set(typeName, toolClass);
+  }
+  /**
+   * Load a workflow from a YAML file path.
+   */
+  loadFromFile(filePath) {
+    const absolutePath = path5.isAbsolute(filePath) ? filePath : path5.resolve(process.cwd(), filePath);
+    if (!fs5.existsSync(absolutePath)) {
+      throw new Error(`Workflow file not found: ${absolutePath}`);
+    }
+    const content = fs5.readFileSync(absolutePath, "utf-8");
+    return this.loadFromString(content);
+  }
+  /**
+   * Load a workflow from a YAML string.
+   */
+  loadFromString(yamlContent) {
+    const definition = import_yaml.default.parse(yamlContent);
+    return this.buildWorkflow(definition);
+  }
+  /**
+   * Build a runnable workflow from a parsed definition.
+   */
+  buildWorkflow(definition) {
+    if (!definition.name) {
+      throw new Error("Workflow must have a name");
+    }
+    if (!definition.entrypoint) {
+      throw new Error("Workflow must have an entrypoint agent");
+    }
+    if (!definition.agents) {
+      throw new Error("Workflow must define at least one agent");
+    }
+    const tools = /* @__PURE__ */ new Map();
+    if (definition.tools) {
+      for (const [name, toolDef] of Object.entries(definition.tools)) {
+        const tool = this.buildTool(name, toolDef.type, toolDef.config);
+        tools.set(name, tool);
+      }
+    }
+    const agents = /* @__PURE__ */ new Map();
+    const agentDefs = definition.agents;
+    const resolved = /* @__PURE__ */ new Set();
+    const maxIterations = Object.keys(agentDefs).length * 2;
+    let iterations = 0;
+    while (resolved.size < Object.keys(agentDefs).length && iterations < maxIterations) {
+      iterations++;
+      for (const [agentName, agentDef] of Object.entries(agentDefs)) {
+        if (resolved.has(agentName)) continue;
+        const agentDeps = agentDef.agents ?? [];
+        const allDepsResolved = agentDeps.every((dep) => resolved.has(dep));
+        if (allDepsResolved) {
+          const agent = this.buildAgent(
+            agentName,
+            agentDef,
+            definition.model,
+            tools,
+            agents,
+            definition.globalMaxContextLength
+          );
+          agents.set(agentName, agent);
+          resolved.add(agentName);
+        }
+      }
+    }
+    if (resolved.size < Object.keys(agentDefs).length) {
+      const unresolved = Object.keys(agentDefs).filter((n) => !resolved.has(n));
+      throw new Error(`Circular or unresolvable agent dependencies: ${unresolved.join(", ")}`);
+    }
+    const entrypointAgent = agents.get(definition.entrypoint);
+    if (!entrypointAgent) {
+      throw new Error(`Entrypoint agent "${definition.entrypoint}" not found in agents`);
+    }
+    return {
+      name: definition.name,
+      description: definition.description,
+      entrypointAgent,
+      agents,
+      tools
+    };
+  }
+  /**
+   * Build a tool instance from a type name and config.
+   */
+  buildTool(name, type, config) {
+    const ToolClass = TOOL_REGISTRY[type] ?? this.customTools.get(type);
+    if (!ToolClass) {
+      throw new Error(`Unknown tool type: ${type}. Available types: ${[...Object.keys(TOOL_REGISTRY), ...this.customTools.keys()].join(", ")}`);
+    }
+    const tool = new ToolClass(config);
+    if (name !== type && name !== tool.name) {
+      Object.defineProperty(tool, "name", { value: name, writable: false });
+    }
+    return tool;
+  }
+  /**
+   * Build an agent instance from a YAML definition.
+   */
+  buildAgent(name, definition, globalModel, availableTools, resolvedAgents, globalMaxContextLength) {
+    const modelConfig = definition.model ?? globalModel;
+    const model = new OpenAIModel({
+      modelId: modelConfig?.modelId,
+      apiKey: modelConfig?.apiKey,
+      baseUrl: modelConfig?.baseUrl,
+      maxTokens: definition.maxTokens ?? modelConfig?.maxTokens,
+      temperature: definition.temperature ?? modelConfig?.temperature,
+      timeout: modelConfig?.timeout
+    });
+    const agentTools = [];
+    if (definition.tools && availableTools) {
+      for (const toolName of definition.tools) {
+        const tool = availableTools.get(toolName);
+        if (tool) {
+          agentTools.push(tool);
+        } else {
+          const ToolClass = TOOL_REGISTRY[toolName] ?? this.customTools.get(toolName);
+          if (ToolClass) {
+            agentTools.push(new ToolClass());
+          } else {
+            throw new Error(`Tool "${toolName}" not found for agent "${name}"`);
+          }
+        }
+      }
+    }
+    if (definition.agents && resolvedAgents) {
+      for (const subAgentName of definition.agents) {
+        const subAgent = resolvedAgents.get(subAgentName);
+        if (!subAgent) {
+          throw new Error(`Sub-agent "${subAgentName}" not found for agent "${name}"`);
+        }
+        agentTools.push(new AgentTool({
+          agent: subAgent,
+          name: subAgentName,
+          description: definition.description ? `Sub-agent: ${subAgentName}` : `Delegate tasks to the ${subAgentName} agent`
+        }));
+      }
+    }
+    const maxContextLength = definition.maxContextLength ?? globalMaxContextLength;
+    if (definition.type === "CodeAgent") {
+      return new CodeAgent({
+        model,
+        tools: agentTools,
+        maxSteps: definition.maxSteps,
+        customInstructions: definition.customInstructions,
+        persistent: definition.persistent,
+        maxContextLength,
+        memoryStrategy: definition.memoryStrategy,
+        maxTokens: definition.maxTokens,
+        temperature: definition.temperature,
+        name
+      });
+    } else {
+      return new ToolUseAgent({
+        model,
+        tools: agentTools,
+        maxSteps: definition.maxSteps,
+        customInstructions: definition.customInstructions,
+        persistent: definition.persistent,
+        maxContextLength,
+        memoryStrategy: definition.memoryStrategy,
+        maxTokens: definition.maxTokens,
+        temperature: definition.temperature,
+        name
+      });
+    }
+  }
+};
+
+// src/orchestrator/Orchestrator.ts
+var import_chalk2 = __toESM(require("chalk"));
+var Orchestrator = class {
+  loader;
+  config;
+  activeAgents = /* @__PURE__ */ new Map();
+  eventLog = [];
+  constructor(config = {}) {
+    this.loader = new YAMLLoader();
+    this.config = {
+      verbose: config.verbose ?? true,
+      onEvent: config.onEvent
+    };
+  }
+  /**
+   * Load a workflow from a YAML file.
+   */
+  loadWorkflow(filePath) {
+    const workflow = this.loader.loadFromFile(filePath);
+    this.displayWorkflowInfo(workflow);
+    return workflow;
+  }
+  /**
+   * Load a workflow from YAML string.
+   */
+  loadWorkflowFromString(yamlContent) {
+    const workflow = this.loader.loadFromString(yamlContent);
+    this.displayWorkflowInfo(workflow);
+    return workflow;
+  }
+  /**
+   * Run a loaded workflow with a task.
+   */
+  async runWorkflow(workflow, task) {
+    this.displayRunStart(workflow.name, task);
+    this.instrumentAgent(workflow.entrypointAgent, workflow.entrypointAgent.getName(), 0);
+    for (const [name, agent] of workflow.agents) {
+      if (agent !== workflow.entrypointAgent) {
+        this.instrumentAgent(agent, name, 1);
+      }
+    }
+    try {
+      const result = await workflow.entrypointAgent.run(task);
+      this.displayRunEnd(result);
+      return result;
+    } catch (error) {
+      this.displayError(error);
+      throw error;
+    }
+  }
+  /**
+   * Run a standalone agent with a task.
+   */
+  async runAgent(agent, task) {
+    this.instrumentAgent(agent, agent.getName(), 0);
+    const result = await agent.run(task);
+    return result;
+  }
+  /**
+   * Instrument an agent with orchestrator event tracking.
+   */
+  instrumentAgent(agent, name, depth) {
+    this.activeAgents.set(name, { agent, depth });
+  }
+  /**
+   * Display workflow info at startup.
+   */
+  displayWorkflowInfo(workflow) {
+    if (!this.config.verbose) return;
+    const line = "\u2550".repeat(70);
+    console.log(import_chalk2.default.cyan(line));
+    console.log(import_chalk2.default.cyan.bold(`  Workflow: ${workflow.name}`));
+    if (workflow.description) {
+      console.log(import_chalk2.default.cyan(`  ${workflow.description}`));
+    }
+    console.log(import_chalk2.default.cyan(`  Agents: ${Array.from(workflow.agents.keys()).join(", ")}`));
+    console.log(import_chalk2.default.cyan(`  Tools: ${Array.from(workflow.tools.keys()).join(", ") || "(none defined at workflow level)"}`));
+    console.log(import_chalk2.default.cyan(`  Entrypoint: ${workflow.entrypointAgent.getName()}`));
+    console.log(import_chalk2.default.cyan(line));
+    console.log();
+  }
+  /**
+   * Display run start info.
+   */
+  displayRunStart(workflowName, task) {
+    if (!this.config.verbose) return;
+    console.log(import_chalk2.default.green.bold(`
+\u25B6 Running workflow "${workflowName}"`));
+    console.log(import_chalk2.default.green(`  Task: ${task}`));
+    console.log(import_chalk2.default.gray("\u2500".repeat(70)));
+  }
+  /**
+   * Display run completion info.
+   */
+  displayRunEnd(result) {
+    if (!this.config.verbose) return;
+    console.log(import_chalk2.default.gray("\n" + "\u2500".repeat(70)));
+    console.log(import_chalk2.default.green.bold(`
+\u2705 Workflow complete`));
+    console.log(import_chalk2.default.green(`  Duration: ${(result.duration / 1e3).toFixed(2)}s`));
+    console.log(import_chalk2.default.green(`  Tokens: ${result.tokenUsage.totalTokens}`));
+    console.log(import_chalk2.default.green(`  Steps: ${result.steps.length}`));
+    const outputStr = typeof result.output === "string" ? result.output : JSON.stringify(result.output, null, 2);
+    console.log(import_chalk2.default.magenta.bold("\n  Final Output:"));
+    const indentedOutput = outputStr.split("\n").map((line) => `  ${line}`).join("\n");
+    console.log(import_chalk2.default.magenta(indentedOutput));
+    console.log();
+  }
+  /**
+   * Display an error.
+   */
+  displayError(error) {
+    if (!this.config.verbose) return;
+    console.error(import_chalk2.default.red.bold(`
+\u274C Workflow failed: ${error.message}`));
+    if (error.stack) {
+      console.error(import_chalk2.default.red.dim(error.stack));
+    }
+  }
+  /**
+   * Log an orchestration event.
+   */
+  logEvent(event) {
+    this.eventLog.push(event);
+    if (this.config.onEvent) {
+      this.config.onEvent(event);
+    }
+  }
+  /**
+   * Get the event log.
+   */
+  getEventLog() {
+    return [...this.eventLog];
+  }
+  /**
+   * Get the YAML loader for registering custom tools.
+   */
+  getLoader() {
+    return this.loader;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Agent,
@@ -1835,18 +3128,29 @@ function agentAsTool(agent, options) {
   AgentMemory,
   AgentTool,
   CodeAgent,
+  CurlTool,
+  ExaGetContentsTool,
+  ExaResearchTool,
+  ExaSearchTool,
   FINAL_ANSWER_PROMPT,
   FinalAnswerTool,
   LocalExecutor,
   LogLevel,
   Model,
   OpenAIModel,
+  Orchestrator,
+  ReadFileTool,
   Tool,
+  ToolUseAgent,
   UserInputTool,
+  WriteFileTool,
+  YAMLLoader,
   agentAsTool,
   createTool,
   finalAnswerTool,
+  formatToolDescriptions,
   generateSystemPrompt,
+  generateToolUseSystemPrompt,
   getErrorRecoveryPrompt
 });
 //# sourceMappingURL=index.js.map