@samrahimi/smol-js 0.6.4 → 0.7.0

package/dist/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -25,8 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
-var fs6 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs8 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
 var readline = __toESM(require("readline"));
 var import_chalk3 = __toESM(require("chalk"));
 var import_dotenv = __toESM(require("dotenv"));
@@ -742,9 +741,21 @@ Total time: ${(duration / 1e3).toFixed(2)}s`);
   getName() {
     return this.config.name;
   }
+  /** Get agent type identifier */
+  getType() {
+    return this.constructor.name;
+  }
+  /** Get max steps configuration */
+  getMaxSteps() {
+    return this.config.maxSteps;
+  }
+  /** Set the event callback (useful for orchestration) */
+  setOnEvent(callback) {
+    this.config.onEvent = callback;
+  }
   /** Sleep for a specified duration */
   sleep(ms) {
-    return new Promise((resolve6) => setTimeout(resolve6, ms));
+    return new Promise((resolve7) => setTimeout(resolve7, ms));
   }
 };
 
@@ -1847,6 +1858,10 @@ Please try a different approach.`
     memoryStep.tokenUsage = response.tokenUsage;
     if (response.content && response.content.trim()) {
       this.logger.reasoning(response.content.trim());
+      this.emitEvent("agent_thinking", {
+        step: this.currentStep,
+        content: response.content.trim()
+      });
     }
     if (!response.toolCalls || response.toolCalls.length === 0) {
       this.logger.warn("No tool calls in response. Prompting model to use tools.");
@@ -1879,42 +1894,84 @@ Please try a different approach.`
   async processToolCalls(toolCalls) {
     const results = [];
     const executeTool = async (tc) => {
+      const startTime = Date.now();
       const toolName = tc.function.name;
       const tool = this.tools.get(toolName);
       if (!tool) {
+        const error = `Unknown tool: ${toolName}. Available tools: ${Array.from(this.tools.keys()).join(", ")}`;
+        this.emitEvent("agent_tool_result", {
+          step: this.currentStep,
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error,
+          duration: Date.now() - startTime
+        });
         return {
           toolCallId: tc.id,
           toolName,
           result: null,
-          error: `Unknown tool: ${toolName}. Available tools: ${Array.from(this.tools.keys()).join(", ")}`
+          error
         };
       }
       let args;
       try {
         args = typeof tc.function.arguments === "string" ? JSON.parse(tc.function.arguments) : tc.function.arguments;
       } catch {
+        const error = `Failed to parse tool arguments: ${tc.function.arguments}`;
+        this.emitEvent("agent_tool_result", {
+          step: this.currentStep,
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error,
+          duration: Date.now() - startTime
+        });
         return {
           toolCallId: tc.id,
           toolName,
           result: null,
-          error: `Failed to parse tool arguments: ${tc.function.arguments}`
+          error
         };
       }
       this.logger.info(`  Calling tool: ${toolName}(${JSON.stringify(args).slice(0, 100)}...)`);
-      this.emitEvent("agent_tool_call", { tool: toolName, args });
+      this.emitEvent("agent_tool_call", {
+        step: this.currentStep,
+        toolCallId: tc.id,
+        toolName,
+        arguments: args
+      });
       try {
         const result = await tool.call(args);
+        const duration = Date.now() - startTime;
+        this.emitEvent("agent_tool_result", {
+          step: this.currentStep,
+          toolCallId: tc.id,
+          toolName,
+          result,
+          duration
+        });
         return {
           toolCallId: tc.id,
           toolName,
           result
         };
       } catch (error) {
+        const errorMsg = `Tool execution error: ${error.message}`;
+        const duration = Date.now() - startTime;
+        this.emitEvent("agent_tool_result", {
+          step: this.currentStep,
+          toolCallId: tc.id,
+          toolName,
+          result: null,
+          error: errorMsg,
+          duration
+        });
         return {
           toolCallId: tc.id,
           toolName,
           result: null,
-          error: `Tool execution error: ${error.message}`
+          error: errorMsg
         };
       }
     };
@@ -2037,7 +2094,7 @@ async function ${this.name}(task: string): Promise<string> { ... }
 };
 
 // src/models/OpenAIModel.ts
-var import_openai = __toESM(require("openai"));
+var import_openai = __toESM(require("openai/index.mjs"));
 
 // src/models/Model.ts
 var Model = class {
@@ -2580,40 +2637,35 @@ var ExaGetContentsTool = class extends Tool {
 // 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.";
+  description = "Perform comprehensive web research using Exa.ai's agentic research system. Provide natural-language instructions about what to research, and the AI research agent will plan searches, gather sources, extract facts, and synthesize findings into a detailed markdown report with citations. Ideal for deep research on any topic. Results typically complete in 20-90 seconds.";
   inputs = {
-    topic: {
+    instructions: {
       type: "string",
-      description: "The research topic or question to investigate",
+      description: "Natural-language task description of what to research (max 4096 characters). Be clear about what information you want, how research should be conducted, and what the output should contain.",
       required: true
     },
-    numSources: {
-      type: "number",
-      description: "Number of primary sources to retrieve (default: 5, max: 10)",
-      required: false,
-      default: 5
-    },
-    category: {
+    model: {
       type: "string",
-      description: 'Optional category: "research paper", "news", "blog", "company"',
-      required: false
-    },
-    includeDomains: {
-      type: "array",
-      description: "Only include results from these domains",
+      description: 'Research model: "exa-research-fast" (faster, cheaper), "exa-research" (balanced, default), or "exa-research-pro" (most thorough)',
       required: false
     },
-    startPublishedDate: {
-      type: "string",
-      description: "Only include results published after this date (ISO 8601)",
+    outputSchema: {
+      type: "object",
+      description: "Optional JSON Schema to enforce structured output format (max 8 root fields, 5 levels deep). If omitted, returns markdown report.",
       required: false
     }
   };
   outputType = "string";
   apiKey;
+  defaultModel;
+  pollInterval;
+  maxPollTime;
   constructor(config) {
     super();
     this.apiKey = config?.apiKey ?? process.env.EXA_API_KEY ?? "";
+    this.defaultModel = config?.model ?? "exa-research";
+    this.pollInterval = config?.pollInterval ?? 2e3;
+    this.maxPollTime = config?.maxPollTime ?? 3e5;
   }
   async setup() {
     if (!this.apiKey) {
@@ -2622,91 +2674,87 @@ var ExaResearchTool = class extends Tool {
     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 }
+    const instructions = args.instructions;
+    const model = args.model ?? this.defaultModel;
+    const outputSchema = args.outputSchema;
+    if (!instructions || instructions.length > 4096) {
+      throw new Error("Instructions are required and must be <= 4096 characters");
+    }
+    const createBody = {
+      instructions,
+      model
     };
-    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", {
+    if (outputSchema) {
+      createBody.outputSchema = outputSchema;
+    }
+    const createResponse = await fetch("https://api.exa.ai/research/v1", {
       method: "POST",
       headers: {
         "x-api-key": this.apiKey,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify(searchBody)
+      body: JSON.stringify(createBody)
     });
-    if (!searchResponse.ok) {
-      const errorText = await searchResponse.text();
-      throw new Error(`Exa research search failed (${searchResponse.status}): ${errorText}`);
+    if (!createResponse.ok) {
+      const errorText = await createResponse.text();
+      throw new Error(`Failed to create research task (${createResponse.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 ?? [];
+    const createData = await createResponse.json();
+    const researchId = createData.researchId;
+    console.log(`Research task created: ${researchId}. Polling for results...`);
+    const startTime = Date.now();
+    let attempts = 0;
+    while (Date.now() - startTime < this.maxPollTime) {
+      attempts++;
+      if (attempts > 1) {
+        await new Promise((resolve7) => setTimeout(resolve7, this.pollInterval));
+      }
+      const statusResponse = await fetch(`https://api.exa.ai/research/v1/${researchId}`, {
+        method: "GET",
+        headers: {
+          "x-api-key": this.apiKey
         }
-      } catch {
+      });
+      if (!statusResponse.ok) {
+        const errorText = await statusResponse.text();
+        throw new Error(`Failed to check research status (${statusResponse.status}): ${errorText}`);
       }
-    }
-    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}`);
+      const statusData = await statusResponse.json();
+      if (statusData.status === "completed") {
+        const output = statusData.output;
+        if (!output) {
+          throw new Error("Research completed but no output was returned");
+        }
+        const sections = [];
+        if (outputSchema && output.parsed) {
+          sections.push("# Research Results (Structured)\n");
+          sections.push(JSON.stringify(output.parsed, null, 2));
+        } else {
+          sections.push(output.content);
+        }
+        if (statusData.costDollars) {
+          const cost = statusData.costDollars;
+          sections.push("\n---\n");
+          sections.push("## Research Metrics\n");
+          sections.push(`- **Cost**: $${cost.total.toFixed(4)}`);
+          sections.push(`- **Searches**: ${cost.numSearches}`);
+          sections.push(`- **Pages analyzed**: ${cost.numPages}`);
+          sections.push(`- **Reasoning tokens**: ${cost.reasoningTokens.toLocaleString()}`);
+        }
+        console.log(`Research completed in ${attempts} polls (${((Date.now() - startTime) / 1e3).toFixed(1)}s)`);
+        return sections.join("\n");
       }
-      if ("author" in source && source.author) {
-        sections.push(`Author: ${source.author}`);
+      if (statusData.status === "failed") {
+        throw new Error(`Research failed: ${statusData.error ?? "Unknown error"}`);
       }
-      if (source.text) {
-        sections.push(`
-Content:
-${source.text.slice(0, 2e3)}`);
+      if (statusData.status === "canceled") {
+        throw new Error("Research was canceled");
+      }
+      if (attempts % 10 === 0) {
+        console.log(`Still researching... (${attempts} polls, ${((Date.now() - startTime) / 1e3).toFixed(0)}s elapsed)`);
       }
-      sections.push("");
     }
-    sections.push("## Source URLs\n");
-    uniqueSources.forEach((s, i) => {
-      sections.push(`${i + 1}. ${s.url}`);
-    });
-    return sections.join("\n");
+    throw new Error(`Research timed out after ${this.maxPollTime / 1e3}s. Task ID: ${researchId}`);
   }
 };
 
@@ -2722,12 +2770,21 @@ var TOOL_REGISTRY = {
 };
 var YAMLLoader = class {
   customTools = /* @__PURE__ */ new Map();
+  toolInstances = /* @__PURE__ */ new Map();
   /**
-   * Register a custom tool type for use in YAML definitions.
+   * Register a custom tool type (class) for use in YAML definitions.
    */
   registerToolType(typeName, toolClass) {
     this.customTools.set(typeName, toolClass);
   }
+  /**
+   * Register a pre-built tool instance for use in YAML definitions.
+   * Used by the custom tool system to register ProxyTool instances
+   * that are created by the scanner rather than by class instantiation.
+   */
+  registerToolInstance(typeName, tool) {
+    this.toolInstances.set(typeName, tool);
+  }
   /**
    * Load a workflow from a YAML file path.
    */
@@ -2811,9 +2868,16 @@ var YAMLLoader = class {
    * Build a tool instance from a type name and config.
    */
   buildTool(name, type, config) {
+    const existingInstance = this.toolInstances.get(type);
+    if (existingInstance) {
+      if (name !== type && name !== existingInstance.name) {
+        Object.defineProperty(existingInstance, "name", { value: name, writable: false });
+      }
+      return existingInstance;
+    }
     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(", ")}`);
+      throw new Error(`Unknown tool type: ${type}. Available types: ${[...Object.keys(TOOL_REGISTRY), ...this.customTools.keys(), ...this.toolInstances.keys()].join(", ")}`);
     }
     const tool = new ToolClass(config);
     if (name !== type && name !== tool.name) {
@@ -2841,11 +2905,16 @@ var YAMLLoader = class {
         if (tool) {
           agentTools.push(tool);
         } else {
-          const ToolClass = TOOL_REGISTRY[toolName] ?? this.customTools.get(toolName);
-          if (ToolClass) {
-            agentTools.push(new ToolClass());
+          const instance = this.toolInstances.get(toolName);
+          if (instance) {
+            agentTools.push(instance);
           } else {
-            throw new Error(`Tool "${toolName}" not found for agent "${name}"`);
+            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}"`);
+            }
           }
         }
       }
@@ -2894,40 +2963,116 @@ var YAMLLoader = class {
   }
 };
 
+// src/output/JSONOutputHandler.ts
+var JSONOutputHandler = class {
+  runId;
+  startTime;
+  constructor(config) {
+    this.runId = config.runId;
+    this.startTime = Date.now();
+  }
+  emit(type, data, extra = {}) {
+    console.log(JSON.stringify({
+      runId: this.runId,
+      timestamp: Date.now(),
+      type,
+      ...extra,
+      data
+    }));
+  }
+  emitRunStart(workflowPath, task, cwd) {
+    this.emit("run_start", { workflowPath, task, cwd });
+  }
+  emitWorkflowLoaded(name, description, agents, tools, entrypoint) {
+    this.emit("workflow_loaded", { name, description, agents, tools, entrypoint });
+  }
+  emitRunEnd(success, output, totalTokens, totalSteps) {
+    this.emit("run_end", {
+      success,
+      output,
+      totalDuration: Date.now() - this.startTime,
+      totalTokens,
+      totalSteps
+    });
+  }
+  emitAgentStart(agentName, depth, task, agentType, maxSteps) {
+    this.emit("agent_start", { task, agentType, maxSteps }, { agentName, depth });
+  }
+  emitAgentEnd(agentName, depth, output, totalSteps, tokenUsage, duration, success) {
+    this.emit("agent_end", { output, totalSteps, tokenUsage, duration, success }, { agentName, depth });
+  }
+  emitAgentStep(agentName, depth, stepNumber, maxSteps, phase) {
+    this.emit("agent_step", { stepNumber, maxSteps, phase }, { agentName, depth });
+  }
+  emitAgentThinking(agentName, depth, stepNumber, content, isPartial) {
+    this.emit("agent_thinking", { stepNumber, content, isPartial }, { agentName, depth });
+  }
+  emitToolCall(agentName, depth, stepNumber, toolCallId, toolName, args) {
+    this.emit("agent_tool_call", { stepNumber, toolCallId, toolName, arguments: args }, { agentName, depth });
+  }
+  emitToolResult(agentName, depth, stepNumber, toolCallId, toolName, result, error, duration) {
+    this.emit("agent_tool_result", { stepNumber, toolCallId, toolName, result, error, duration }, { agentName, depth });
+  }
+  emitObservation(agentName, depth, stepNumber, observation, codeAction, logs) {
+    this.emit("agent_observation", { stepNumber, observation, codeAction, logs }, { agentName, depth });
+  }
+  emitError(message, stack, agentName, depth, stepNumber) {
+    this.emit("error", { message, stack, stepNumber }, {
+      ...agentName ? { agentName } : {},
+      ...depth !== void 0 ? { depth } : {}
+    });
+  }
+};
+
 // src/orchestrator/Orchestrator.ts
 var Orchestrator = class {
   loader;
   config;
   activeAgents = /* @__PURE__ */ new Map();
   eventLog = [];
+  jsonOutput = null;
+  isJsonMode = false;
   constructor(config = {}) {
     this.loader = new YAMLLoader();
+    this.isJsonMode = config.outputFormat === "json";
     this.config = {
       verbose: config.verbose ?? true,
-      onEvent: config.onEvent
+      onEvent: config.onEvent,
+      outputFormat: config.outputFormat ?? "text",
+      runId: config.runId,
+      cwd: config.cwd
     };
+    if (this.isJsonMode) {
+      if (!config.runId) {
+        throw new Error("runId is required for JSON output mode");
+      }
+      this.jsonOutput = new JSONOutputHandler({
+        runId: config.runId,
+        verbose: config.verbose ?? true
+      });
+    }
   }
   /**
    * Load a workflow from a YAML file.
    */
   loadWorkflow(filePath) {
     const workflow = this.loader.loadFromFile(filePath);
-    this.displayWorkflowInfo(workflow);
+    this.displayWorkflowInfo(workflow, filePath);
     return workflow;
   }
   /**
    * Load a workflow from YAML string.
    */
-  loadWorkflowFromString(yamlContent) {
+  loadWorkflowFromString(yamlContent, sourcePath) {
     const workflow = this.loader.loadFromString(yamlContent);
-    this.displayWorkflowInfo(workflow);
+    this.displayWorkflowInfo(workflow, sourcePath);
     return workflow;
   }
   /**
    * Run a loaded workflow with a task.
    */
-  async runWorkflow(workflow, task) {
-    this.displayRunStart(workflow.name, task);
+  async runWorkflow(workflow, task, workflowPath) {
+    this.displayRunStart(workflow.name, task, workflowPath);
     this.instrumentAgent(workflow.entrypointAgent, workflow.entrypointAgent.getName(), 0);
     for (const [name, agent] of workflow.agents) {
       if (agent !== workflow.entrypointAgent) {
@@ -2936,10 +3081,13 @@ var Orchestrator = class {
     }
     try {
       const result = await workflow.entrypointAgent.run(task);
-      this.displayRunEnd(result);
+      this.displayRunEnd(result, true);
       return result;
     } catch (error) {
       this.displayError(error);
+      if (this.isJsonMode && this.jsonOutput) {
+        this.jsonOutput.emitRunEnd(false, null, 0, 0);
+      }
       throw error;
     }
   }
@@ -2956,11 +3104,128 @@ var Orchestrator = class {
    */
   instrumentAgent(agent, name, depth) {
     this.activeAgents.set(name, { agent, depth });
+    agent.setOnEvent((event) => {
+      const orchestratorEvent = {
+        type: event.type,
+        agentName: name,
+        depth,
+        data: event.data,
+        timestamp: Date.now()
+      };
+      this.logEvent(orchestratorEvent);
+      if (this.isJsonMode && this.jsonOutput) {
+        this.emitAgentEventAsJSON(event, name, depth);
+      }
+    });
+  }
+  /**
+   * Emit an agent event as JSON.
+   */
+  emitAgentEventAsJSON(event, agentName, depth) {
+    if (!this.jsonOutput) return;
+    const data = event.data;
+    switch (event.type) {
+      case "agent_start":
+        this.jsonOutput.emitAgentStart(
+          agentName,
+          depth,
+          data.task,
+          data.name ? "ToolUseAgent" : "CodeAgent",
+          // Will be improved
+          20
+          // Default maxSteps, could be passed
+        );
+        break;
+      case "agent_step":
+        this.jsonOutput.emitAgentStep(
+          agentName,
+          depth,
+          data.step,
+          data.maxSteps,
+          "start"
+        );
+        break;
+      case "agent_thinking":
+        this.jsonOutput.emitAgentThinking(
+          agentName,
+          depth,
+          data.step,
+          data.content,
+          false
+        );
+        break;
+      case "agent_tool_call":
+        this.jsonOutput.emitToolCall(
+          agentName,
+          depth,
+          data.step,
+          data.toolCallId,
+          data.toolName,
+          data.arguments
+        );
+        break;
+      case "agent_tool_result":
+        this.jsonOutput.emitToolResult(
+          agentName,
+          depth,
+          data.step,
+          data.toolCallId,
+          data.toolName,
+          data.result,
+          data.error,
+          data.duration
+        );
+        break;
+      case "agent_observation":
+        this.jsonOutput.emitObservation(
+          agentName,
+          depth,
+          data.step,
+          data.observation,
+          data.codeAction,
+          data.logs
+        );
+        break;
+      case "agent_error":
+        this.jsonOutput.emitError(
+          data.error,
+          void 0,
+          agentName,
+          depth,
+          data.step
+        );
+        break;
+      case "agent_end":
+        this.jsonOutput.emitAgentEnd(
+          agentName,
+          depth,
+          data.output,
+          0,
+          // totalSteps - would need to track
+          data.tokenUsage,
+          data.duration,
+          true
+        );
+        break;
+    }
   }
   /**
    * Display workflow info at startup.
    */
-  displayWorkflowInfo(workflow) {
+  displayWorkflowInfo(workflow, _sourcePath) {
+    const agents = Array.from(workflow.agents.keys());
+    const tools = Array.from(workflow.tools.keys());
+    const entrypoint = workflow.entrypointAgent.getName();
+    if (this.isJsonMode && this.jsonOutput) {
+      this.jsonOutput.emitWorkflowLoaded(
+        workflow.name,
+        workflow.description,
+        agents,
+        tools,
+        entrypoint
+      );
+      return;
+    }
     if (!this.config.verbose) return;
     const line = "\u2550".repeat(70);
     console.log(import_chalk2.default.cyan(line));
@@ -2968,16 +3233,20 @@ var Orchestrator = class {
     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(`  Agents: ${agents.join(", ")}`));
+    console.log(import_chalk2.default.cyan(`  Tools: ${tools.join(", ") || "(none defined at workflow level)"}`));
+    console.log(import_chalk2.default.cyan(`  Entrypoint: ${entrypoint}`));
     console.log(import_chalk2.default.cyan(line));
     console.log();
   }
   /**
    * Display run start info.
    */
-  displayRunStart(workflowName, task) {
+  displayRunStart(workflowName, task, workflowPath) {
+    if (this.isJsonMode && this.jsonOutput) {
+      this.jsonOutput.emitRunStart(workflowPath || workflowName, task, this.config.cwd);
+      return;
+    }
     if (!this.config.verbose) return;
     console.log(import_chalk2.default.green.bold(`
 \u25B6 Running workflow "${workflowName}"`));
@@ -2987,7 +3256,16 @@ var Orchestrator = class {
   /**
    * Display run completion info.
    */
-  displayRunEnd(result) {
+  displayRunEnd(result, success = true) {
+    if (this.isJsonMode && this.jsonOutput) {
+      this.jsonOutput.emitRunEnd(
+        success,
+        result.output,
+        result.tokenUsage.totalTokens,
+        result.steps.length
+      );
+      return;
+    }
     if (!this.config.verbose) return;
     console.log(import_chalk2.default.gray("\n" + "\u2500".repeat(70)));
     console.log(import_chalk2.default.green.bold(`
@@ -3005,6 +3283,10 @@ var Orchestrator = class {
    * Display an error.
    */
   displayError(error) {
+    if (this.isJsonMode && this.jsonOutput) {
+      this.jsonOutput.emitError(error.message, error.stack);
+      return;
+    }
     if (!this.config.verbose) return;
     console.error(import_chalk2.default.red.bold(`
 \u274C Workflow failed: ${error.message}`));
@@ -3033,8 +3315,321 @@ var Orchestrator = class {
   getLoader() {
     return this.loader;
   }
+  /**
+   * Get the JSON output handler (if in JSON mode).
+   */
+  getJSONOutputHandler() {
+    return this.jsonOutput;
+  }
+  /**
+   * Check if in JSON output mode.
+   */
+  isJSONOutputMode() {
+    return this.isJsonMode;
+  }
+  /**
+   * Get the run ID.
+   */
+  getRunId() {
+    return this.config.runId;
+  }
 };
 
+// src/tools/CustomToolScanner.ts
+var fs7 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
+
+// src/tools/ProxyTool.ts
+var import_child_process2 = require("child_process");
+
+// src/utils/bunInstaller.ts
+var import_child_process = require("child_process");
+var path6 = __toESM(require("path"));
+var fs6 = __toESM(require("fs"));
+var os3 = __toESM(require("os"));
+var cachedBunPath = null;
+async function ensureBunAvailable() {
+  if (cachedBunPath) return cachedBunPath;
+  const fromPath = whichBun();
+  if (fromPath) {
+    cachedBunPath = fromPath;
+    return fromPath;
+  }
+  const localPath = path6.join(os3.homedir(), ".bun", "bin", "bun");
+  if (fs6.existsSync(localPath)) {
+    cachedBunPath = localPath;
+    return localPath;
+  }
+  console.log(
+    "\n[smol-js] Bun is required to run custom tools but was not found. Installing Bun automatically...\n"
+  );
+  try {
+    (0, import_child_process.execSync)("curl --proto =https --tlsv1.2 -sSf https://bun.sh | bash", {
+      stdio: "inherit",
+      shell: "/bin/bash",
+      env: { ...process.env, HOME: os3.homedir() }
+    });
+  } catch (err) {
+    throw new Error(
+      `[smol-js] Failed to auto-install Bun. Please install it manually: https://bun.sh
+Details: ${err.message}`
+    );
+  }
+  const afterInstall = whichBun() || (fs6.existsSync(localPath) ? localPath : null);
+  if (!afterInstall) {
+    throw new Error(
+      "[smol-js] Bun installation appeared to succeed but the binary was not found. Please install manually: https://bun.sh"
+    );
+  }
+  console.log(`[smol-js] Bun installed successfully at: ${afterInstall}
+`);
+  cachedBunPath = afterInstall;
+  return afterInstall;
+}
+function whichBun() {
+  try {
+    const cmd = process.platform === "win32" ? "where bun" : "which bun";
+    const result = (0, import_child_process.execSync)(cmd, { encoding: "utf8", stdio: "pipe" }).trim();
+    const first = result.split("\n")[0]?.trim();
+    if (first && fs6.existsSync(first)) return first;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/tools/ProxyTool.ts
+var TOOL_OUTPUT_PREFIX = "[TOOL_OUTPUT]";
+var TOOL_RESULT_PREFIX = "[TOOL_RESULT]";
+var TOOL_ERROR_PREFIX = "[TOOL_ERROR]";
+var DEFAULT_TOOL_TIMEOUT_MS = 6e4;
+var ProxyTool = class extends Tool {
+  name;
+  description;
+  inputs;
+  outputType;
+  toolPath;
+  timeout;
+  bunPath = null;
+  constructor(config) {
+    super();
+    this.name = config.name;
+    this.description = config.description;
+    this.inputs = config.inputs;
+    this.outputType = config.outputType;
+    this.toolPath = config.toolPath;
+    this.timeout = config.timeout ?? DEFAULT_TOOL_TIMEOUT_MS;
+  }
+  /**
+   * Ensure Bun is available before first invocation.
+   */
+  async setup() {
+    this.bunPath = await ensureBunAvailable();
+    this.isSetup = true;
+  }
+  /**
+   * Spawn the tool in a Bun child process, pass serialized args via CLI,
+   * stream stdout back as log lines, and parse the final result.
+   */
+  async execute(args) {
+    if (!this.bunPath) {
+      await this.setup();
+    }
+    const serializedArgs = JSON.stringify(args);
+    return new Promise((resolve7, reject) => {
+      const child = (0, import_child_process2.spawn)(this.bunPath, ["run", this.toolPath, serializedArgs], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env }
+      });
+      let result = void 0;
+      let resultReceived = false;
+      let errorMessage = null;
+      const logBuffer = [];
+      let stderr = "";
+      let partialLine = "";
+      child.stdout.on("data", (chunk) => {
+        partialLine += chunk.toString("utf8");
+        const lines = partialLine.split("\n");
+        partialLine = lines.pop();
+        for (const line of lines) {
+          this.processLine(line, {
+            onOutput: (msg) => logBuffer.push(msg),
+            onResult: (value) => {
+              result = value;
+              resultReceived = true;
+            },
+            onError: (msg) => {
+              errorMessage = msg;
+            }
+          });
+        }
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+      });
+      const timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        reject(new Error(
+          `Custom tool "${this.name}" timed out after ${this.timeout}ms. The process was terminated. Check the tool for infinite loops or slow operations.`
+        ));
+      }, this.timeout);
+      timer.unref();
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        if (partialLine.trim()) {
+          this.processLine(partialLine, {
+            onOutput: (msg) => logBuffer.push(msg),
+            onResult: (value) => {
+              result = value;
+              resultReceived = true;
+            },
+            onError: (msg) => {
+              errorMessage = msg;
+            }
+          });
+        }
+        if (errorMessage) {
+          reject(new Error(
+            `Custom tool "${this.name}" reported an error: ${errorMessage}`
+          ));
+          return;
+        }
+        if (resultReceived) {
+          if (logBuffer.length > 0) {
+            const logPrefix = `[Tool output logs]
+${logBuffer.join("\n")}
+
+[Tool result]
+`;
+            if (typeof result === "string") {
+              resolve7(logPrefix + result);
+            } else {
+              resolve7({ logs: logBuffer.join("\n"), result });
+            }
+          } else {
+            resolve7(result);
+          }
+          return;
+        }
+        const combined = (logBuffer.join("\n") + "\n" + stderr).trim();
+        if (code !== 0) {
+          reject(new Error(
+            `Custom tool "${this.name}" exited with code ${code}. Output: ${combined || "(none)"}`
+          ));
+        } else {
+          resolve7(combined || `Tool "${this.name}" produced no output.`);
+        }
+      });
+      child.on("error", (err) => {
+        clearTimeout(timer);
+        reject(new Error(
+          `Failed to spawn custom tool "${this.name}": ${err.message}`
+        ));
+      });
+    });
+  }
+  // --- internal line parser ---
+  processLine(line, handlers) {
+    const trimmed = line.trimEnd();
+    if (!trimmed) return;
+    if (trimmed.startsWith(TOOL_RESULT_PREFIX)) {
+      const json = trimmed.slice(TOOL_RESULT_PREFIX.length).trim();
+      try {
+        handlers.onResult(JSON.parse(json));
+      } catch {
+        handlers.onResult(json);
+      }
+    } else if (trimmed.startsWith(TOOL_ERROR_PREFIX)) {
+      handlers.onError(trimmed.slice(TOOL_ERROR_PREFIX.length).trim());
+    } else if (trimmed.startsWith(TOOL_OUTPUT_PREFIX)) {
+      handlers.onOutput(trimmed.slice(TOOL_OUTPUT_PREFIX.length).trim());
+    } else {
+      handlers.onOutput(trimmed);
+    }
+  }
+};
+
+// src/tools/CustomToolScanner.ts
+var METADATA_REGEX = /export\s+const\s+TOOL_METADATA\s*=\s*(\{[\s\S]*?\});\s*$/m;
+function scanCustomTools(folderPath) {
+  if (!fs7.existsSync(folderPath)) {
+    throw new Error(
+      `Custom tools folder not found: ${folderPath}. Create the directory or check your --custom-tools-folder path.`
+    );
+  }
+  const entries = fs7.readdirSync(folderPath, { withFileTypes: true });
+  const discovered = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) continue;
+    const ext = path7.extname(entry.name).toLowerCase();
+    if (ext !== ".ts" && ext !== ".js") continue;
+    const filePath = path7.resolve(folderPath, entry.name);
+    const baseName = path7.basename(entry.name, ext);
+    let metadata;
+    try {
+      metadata = extractMetadata(filePath);
+    } catch (err) {
+      throw new Error(
+        `Failed to extract TOOL_METADATA from "${entry.name}": ${err.message}
+Ensure the file exports \`export const TOOL_METADATA = { name, description, inputs, outputType };\``
+      );
+    }
+    if (metadata.name !== baseName) {
+      throw new Error(
+        `Tool metadata name mismatch in "${entry.name}": file is "${baseName}" but TOOL_METADATA.name is "${metadata.name}". They must match (Convention over Configuration).`
+      );
+    }
+    discovered.push({ filePath, metadata });
+  }
+  return discovered;
+}
+function extractMetadata(filePath) {
+  const source = fs7.readFileSync(filePath, "utf8");
+  const match = source.match(METADATA_REGEX);
+  if (!match) {
+    throw new Error(
+      "No `export const TOOL_METADATA = { ... };` block found. Add the metadata export at the bottom of your tool file."
+    );
+  }
+  let parsed;
+  try {
+    parsed = new Function(`"use strict"; return (${match[1]});`)();
+  } catch (err) {
+    throw new Error(
+      `Could not parse TOOL_METADATA object: ${err.message}. Ensure it is a valid JavaScript object literal.`
+    );
+  }
+  if (!parsed.name || typeof parsed.name !== "string") {
+    throw new Error("TOOL_METADATA.name must be a non-empty string.");
+  }
+  if (!parsed.description || typeof parsed.description !== "string") {
+    throw new Error("TOOL_METADATA.description must be a non-empty string.");
+  }
+  if (!parsed.inputs || typeof parsed.inputs !== "object") {
+    throw new Error("TOOL_METADATA.inputs must be an object mapping parameter names to their schemas.");
+  }
+  if (!parsed.outputType || typeof parsed.outputType !== "string") {
+    throw new Error("TOOL_METADATA.outputType must be a non-empty string.");
+  }
+  return parsed;
+}
+function loadCustomTools(folderPath) {
+  const discovered = scanCustomTools(folderPath);
+  const tools = /* @__PURE__ */ new Map();
+  for (const { filePath, metadata } of discovered) {
+    const config = {
+      toolPath: filePath,
+      name: metadata.name,
+      description: metadata.description,
+      inputs: metadata.inputs,
+      outputType: metadata.outputType,
+      timeout: metadata.timeout
+    };
+    tools.set(metadata.name, new ProxyTool(config));
+  }
+  return tools;
+}
+
 // src/cli.ts
 import_dotenv.default.config();
 async function main() {
@@ -3064,14 +3659,20 @@ function printUsage() {
   console.log("  smol-js validate <workflow.yaml>          Validate a workflow file");
   console.log("");
   console.log("Options:");
-  console.log("  --task, -t <task>    Task description (prompted if not provided)");
-  console.log("  --quiet, -q          Reduce output verbosity");
-  console.log("  --help, -h           Show this help message");
+  console.log("  --task, -t <task>         Task description (prompted if not provided)");
+  console.log("  --quiet, -q               Reduce output verbosity");
+  console.log("  --output-format <format>  Output format: text (default) or json");
+  console.log("  --verbose                 Include full step details in output");
+  console.log("  --run-id <id>             Unique run identifier (auto-generated if not provided)");
+  console.log("  --cwd <dir>               Working directory for agent file operations");
+  console.log("  --custom-tools-folder <path>  Path to folder containing standalone custom tool files");
+  console.log("  --help, -h                Show this help message");
   console.log("");
   console.log("Examples:");
   console.log('  npx @samrahimi/smol-js workflow.yaml --task "Research AI safety"');
   console.log('  smol-js research-agent.yaml -t "Write a summary of quantum computing"');
   console.log("  smol-js validate my-workflow.yaml");
+  console.log('  smol-js workflow.yaml --task "Task" --output-format json --run-id abc123');
 }
 async function runCommand(args) {
   if (args.length === 0) {
@@ -3081,39 +3682,130 @@ async function runCommand(args) {
   const filePath = args[0];
   let task = "";
   let quiet = false;
+  let outputFormat = "text";
+  let verbose = false;
+  let runId = "";
+  let cwd = "";
+  let customToolsFolder = "";
   for (let i = 1; i < args.length; i++) {
     if (args[i] === "--task" || args[i] === "-t") {
       task = args[i + 1] ?? "";
       i++;
     } else if (args[i] === "--quiet" || args[i] === "-q") {
       quiet = true;
+    } else if (args[i] === "--output-format") {
+      const format = args[i + 1];
+      if (format === "json" || format === "text") {
+        outputFormat = format;
+      } else {
+        console.error(import_chalk3.default.red(`Invalid output format: ${format}. Use 'text' or 'json'.`));
+        process.exit(1);
+      }
+      i++;
+    } else if (args[i] === "--verbose") {
+      verbose = true;
+    } else if (args[i] === "--run-id") {
+      runId = args[i + 1] ?? "";
+      i++;
+    } else if (args[i] === "--cwd") {
+      cwd = args[i + 1] ?? "";
+      i++;
+    } else if (args[i] === "--custom-tools-folder") {
+      customToolsFolder = args[i + 1] ?? "";
+      i++;
     }
   }
-  const resolvedPath = path6.isAbsolute(filePath) ? filePath : path6.resolve(process.cwd(), filePath);
-  if (!fs6.existsSync(resolvedPath)) {
-    console.error(import_chalk3.default.red(`Error: file not found: ${resolvedPath}`));
+  if (outputFormat === "json" && !runId) {
+    runId = `run-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+  }
+  const resolvedPath = path8.isAbsolute(filePath) ? filePath : path8.resolve(process.cwd(), filePath);
+  if (!fs8.existsSync(resolvedPath)) {
+    if (outputFormat === "json") {
+      console.log(JSON.stringify({
+        runId: runId || "unknown",
+        timestamp: Date.now(),
+        type: "error",
+        data: { message: `File not found: ${resolvedPath}` }
+      }));
+    } else {
+      console.error(import_chalk3.default.red(`Error: file not found: ${resolvedPath}`));
+    }
     process.exit(1);
   }
   if (!task) {
+    if (outputFormat === "json") {
+      console.log(JSON.stringify({
+        runId: runId || "unknown",
+        timestamp: Date.now(),
+        type: "error",
+        data: { message: "Task is required in JSON output mode. Use --task flag." }
+      }));
+      process.exit(1);
+    }
     task = await promptUser("Enter your task: ");
     if (!task.trim()) {
       console.error(import_chalk3.default.red("Error: task cannot be empty"));
       process.exit(1);
     }
   }
-  const orchestrator = new Orchestrator({ verbose: !quiet });
+  if (cwd) {
+    const resolvedCwd = path8.isAbsolute(cwd) ? cwd : path8.resolve(process.cwd(), cwd);
+    if (!fs8.existsSync(resolvedCwd)) {
+      fs8.mkdirSync(resolvedCwd, { recursive: true });
+    }
+    process.chdir(resolvedCwd);
+  }
+  const orchestrator = new Orchestrator({
+    verbose: outputFormat === "json" ? verbose : !quiet,
+    outputFormat,
+    runId: runId || void 0,
+    cwd: cwd || void 0
+  });
+  if (customToolsFolder) {
+    const resolvedToolsFolder = path8.isAbsolute(customToolsFolder) ? customToolsFolder : path8.resolve(process.cwd(), customToolsFolder);
+    if (outputFormat !== "json") {
+      console.log(import_chalk3.default.gray(`
+Scanning custom tools in: ${resolvedToolsFolder}
+`));
+    }
+    const customTools = loadCustomTools(resolvedToolsFolder);
+    const loader = orchestrator.getLoader();
+    for (const [toolName, proxyTool] of customTools) {
+      loader.registerToolInstance(toolName, proxyTool);
+      if (outputFormat !== "json") {
+        console.log(import_chalk3.default.green(`  + Registered custom tool: ${toolName}`));
+      }
+    }
+  }
   try {
-    console.log(import_chalk3.default.gray(`
+    if (outputFormat !== "json") {
+      console.log(import_chalk3.default.gray(`
 Loading workflow from: ${resolvedPath}
 `));
+    }
     const workflow = orchestrator.loadWorkflow(resolvedPath);
-    await orchestrator.runWorkflow(workflow, task);
+    await orchestrator.runWorkflow(workflow, task, resolvedPath);
     process.exit(0);
   } catch (error) {
-    console.error(import_chalk3.default.red(`
+    if (outputFormat === "json") {
+      const jsonHandler = orchestrator.getJSONOutputHandler();
+      if (jsonHandler) {
+        jsonHandler.emitError(error.message, error.stack);
+        jsonHandler.emitRunEnd(false, null, 0, 0);
+      } else {
+        console.log(JSON.stringify({
+          runId: runId || "unknown",
+          timestamp: Date.now(),
+          type: "error",
+          data: { message: error.message, stack: error.stack }
+        }));
+      }
+    } else {
+      console.error(import_chalk3.default.red(`
 Error: ${error.message}`));
-    if (process.env.DEBUG) {
-      console.error(error.stack);
+      if (process.env.DEBUG) {
+        console.error(error.stack);
+      }
     }
     process.exit(1);
   }
@@ -3124,8 +3816,8 @@ async function validateCommand(args) {
     process.exit(1);
   }
   const filePath = args[0];
-  const resolvedPath = path6.isAbsolute(filePath) ? filePath : path6.resolve(process.cwd(), filePath);
-  if (!fs6.existsSync(resolvedPath)) {
+  const resolvedPath = path8.isAbsolute(filePath) ? filePath : path8.resolve(process.cwd(), filePath);
+  if (!fs8.existsSync(resolvedPath)) {
     console.error(import_chalk3.default.red(`Error: file not found: ${resolvedPath}`));
     process.exit(1);
   }
@@ -3148,10 +3840,10 @@ function promptUser(question) {
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     rl.question(import_chalk3.default.cyan(question), (answer) => {
       rl.close();
-      resolve6(answer);
+      resolve7(answer);
     });
   });
 }