@samrahimi/smol-js 0.6.4 → 0.7.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import OpenAI from 'openai';
+import OpenAI from 'openai/index.mjs';
 
 /**
  * Core types for smol-js
@@ -207,6 +207,136 @@ interface OrchestratorEvent {
     data: unknown;
     timestamp: number;
 }
+type JSONEventType = 'run_start' | 'workflow_loaded' | 'agent_start' | 'agent_step' | 'agent_thinking' | 'agent_tool_call' | 'agent_tool_result' | 'agent_observation' | 'agent_end' | 'run_end' | 'error' | 'log';
+interface JSONEventBase {
+    runId: string;
+    timestamp: number;
+    type: JSONEventType;
+}
+interface JSONRunStartEvent extends JSONEventBase {
+    type: 'run_start';
+    data: {
+        workflowPath: string;
+        task: string;
+        cwd?: string;
+    };
+}
+interface JSONWorkflowLoadedEvent extends JSONEventBase {
+    type: 'workflow_loaded';
+    data: {
+        name: string;
+        description?: string;
+        agents: string[];
+        tools: string[];
+        entrypoint: string;
+    };
+}
+interface JSONRunEndEvent extends JSONEventBase {
+    type: 'run_end';
+    data: {
+        success: boolean;
+        output: unknown;
+        totalDuration: number;
+        totalTokens: number;
+        totalSteps: number;
+    };
+}
+interface JSONAgentStartEvent extends JSONEventBase {
+    type: 'agent_start';
+    agentName: string;
+    depth: number;
+    data: {
+        task: string;
+        agentType: 'CodeAgent' | 'ToolUseAgent';
+        maxSteps: number;
+    };
+}
+interface JSONAgentEndEvent extends JSONEventBase {
+    type: 'agent_end';
+    agentName: string;
+    depth: number;
+    data: {
+        output: unknown;
+        totalSteps: number;
+        tokenUsage: TokenUsage;
+        duration: number;
+        success: boolean;
+    };
+}
+interface JSONAgentStepEvent extends JSONEventBase {
+    type: 'agent_step';
+    agentName: string;
+    depth: number;
+    data: {
+        stepNumber: number;
+        maxSteps: number;
+        phase: 'start' | 'thinking' | 'acting' | 'complete';
+    };
+}
+interface JSONAgentThinkingEvent extends JSONEventBase {
+    type: 'agent_thinking';
+    agentName: string;
+    depth: number;
+    data: {
+        stepNumber: number;
+        content: string;
+        isPartial?: boolean;
+    };
+}
+interface JSONAgentToolCallEvent extends JSONEventBase {
+    type: 'agent_tool_call';
+    agentName: string;
+    depth: number;
+    data: {
+        stepNumber: number;
+        toolCallId: string;
+        toolName: string;
+        arguments: Record<string, unknown>;
+    };
+}
+interface JSONAgentToolResultEvent extends JSONEventBase {
+    type: 'agent_tool_result';
+    agentName: string;
+    depth: number;
+    data: {
+        stepNumber: number;
+        toolCallId: string;
+        toolName: string;
+        result: unknown;
+        error?: string;
+        duration: number;
+    };
+}
+interface JSONAgentObservationEvent extends JSONEventBase {
+    type: 'agent_observation';
+    agentName: string;
+    depth: number;
+    data: {
+        stepNumber: number;
+        observation: string;
+        codeAction?: string;
+        logs?: string;
+    };
+}
+interface JSONErrorEvent extends JSONEventBase {
+    type: 'error';
+    agentName?: string;
+    depth?: number;
+    data: {
+        message: string;
+        stack?: string;
+        stepNumber?: number;
+    };
+}
+interface JSONLogEvent extends JSONEventBase {
+    type: 'log';
+    data: {
+        level: 'info' | 'warn' | 'error' | 'debug';
+        message: string;
+    };
+}
+type JSONEvent = JSONRunStartEvent | JSONWorkflowLoadedEvent | JSONRunEndEvent | JSONAgentStartEvent | JSONAgentEndEvent | JSONAgentStepEvent | JSONAgentThinkingEvent | JSONAgentToolCallEvent | JSONAgentToolResultEvent | JSONAgentObservationEvent | JSONErrorEvent | JSONLogEvent;
+type OutputFormat = 'text' | 'json';
 
 /**
  * Tool base class for smol-js
@@ -592,6 +722,15 @@ declare abstract class Agent {
     removeTool(name: string): boolean;
     /** Get agent name */
     getName(): string;
+    /** Get agent type identifier */
+    getType(): string;
+    /** Get max steps configuration */
+    getMaxSteps(): number;
+    /** Set the event callback (useful for orchestration) */
+    setOnEvent(callback: (event: {
+        type: string;
+        data: unknown;
+    }) => void): void;
     /** Sleep for a specified duration */
     protected sleep(ms: number): Promise<void>;
 }
@@ -1021,26 +1160,141 @@ declare class ExaGetContentsTool extends Tool {
 }
 
 /**
- * ExaResearchTool - Deep research on a topic using Exa.ai
+ * ExaResearchTool - Agentic web research using Exa.ai Research API
+ *
+ * The Research API is an asynchronous, multi-step pipeline that transforms
+ * open-ended questions into grounded reports with citations. The system performs
+ * planning, searching, and reasoning to produce comprehensive research outputs.
  *
- * Performs multi-step research by combining search and content retrieval
- * to produce comprehensive findings on a topic.
+ * See: https://docs.exa.ai/reference/exa-research
  */
 
 interface ExaResearchConfig {
     apiKey?: string;
+    model?: 'exa-research-fast' | 'exa-research' | 'exa-research-pro';
+    pollInterval?: number;
+    maxPollTime?: number;
 }
 declare class ExaResearchTool extends Tool {
     readonly name = "exa_research";
-    readonly 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.";
+    readonly 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.";
     readonly inputs: ToolInputs;
     readonly outputType = "string";
     private apiKey;
+    private defaultModel;
+    private pollInterval;
+    private maxPollTime;
     constructor(config?: ExaResearchConfig);
     setup(): Promise<void>;
     execute(args: Record<string, unknown>): Promise<string>;
 }
 
+/**
+ * ProxyTool - Bridges the smol-js agent runtime to an external standalone tool
+ * executed in an isolated Bun process.
+ *
+ * The tool file is never imported into the main Node.js process. Instead, when
+ * an agent invokes this proxy, it spawns `bun run <toolPath>` and communicates
+ * via a lightweight stdin/stdout JSON protocol.
+ *
+ * Protocol (stdout of child):
+ *   - Lines prefixed with `[TOOL_OUTPUT]` are streaming log lines from the tool.
+ *   - A line prefixed with `[TOOL_RESULT]` contains the JSON-serialized return value.
+ *   - A line prefixed with `[TOOL_ERROR]` means the tool threw; payload is the message.
+ *   - Any other stdout line is treated as a streaming log line.
+ *
+ * Extensibility note: The transport (child_process + stdio) is encapsulated here.
+ * A future subclass or factory could swap this for HTTP, gRPC, or IPC with no change
+ * to the ProxyTool interface visible to agents or YAML definitions.
+ */
+
+interface ProxyToolConfig {
+    /** Absolute path to the .ts or .js tool file */
+    toolPath: string;
+    /** Tool name (must match the class name inside the file) */
+    name: string;
+    /** Human-readable description exposed to agents */
+    description: string;
+    /** Input schema that the LLM will see */
+    inputs: ToolInputs;
+    /** Output type label */
+    outputType: string;
+    /** Max execution time in ms (default 60 s) */
+    timeout?: number;
+}
+declare class ProxyTool extends Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputs: ToolInputs;
+    readonly outputType: string;
+    private readonly toolPath;
+    private readonly timeout;
+    private bunPath;
+    constructor(config: ProxyToolConfig);
+    /**
+     * Ensure Bun is available before first invocation.
+     */
+    setup(): Promise<void>;
+    /**
+     * Spawn the tool in a Bun child process, pass serialized args via CLI,
+     * stream stdout back as log lines, and parse the final result.
+     */
+    execute(args: Record<string, unknown>): Promise<unknown>;
+    private processLine;
+}
+
+/**
+ * CustomToolScanner — discovers standalone tool files in a directory and
+ * extracts their metadata so that ProxyTool instances can be registered
+ * with the YAML loader.
+ *
+ * Convention over Configuration:
+ *   • Each file in the custom-tools folder must export a default metadata
+ *     object conforming to CustomToolMetadata (see standalone tool wrapper docs).
+ *   • The exported class name (or `name` field in metadata) MUST match the
+ *     file's basename (without extension). E.g. `WeatherLookup.ts` → name: "WeatherLookup".
+ *   • The tool is referenced in YAML by that same name.
+ *
+ * Metadata Extraction (zero-import approach):
+ *   We read the file as text and use a lightweight regex to pull the
+ *   `TOOL_METADATA` export block. This keeps the scanner decoupled from
+ *   Bun/ESM and lets it run purely in the Node.js main process.
+ *   The metadata block must be a single JSON object assigned to
+ *   `export const TOOL_METADATA = { ... };`
+ */
+
+interface CustomToolMetadata {
+    /** Must match the file's basename (sans extension) */
+    name: string;
+    /** Human-readable description shown to the LLM */
+    description: string;
+    /** Input schema identical to Tool.inputs */
+    inputs: ToolInputs;
+    /** Output type label */
+    outputType: string;
+    /** Optional execution timeout in ms */
+    timeout?: number;
+}
+interface DiscoveredTool {
+    /** Absolute path to the tool file */
+    filePath: string;
+    /** Parsed metadata */
+    metadata: CustomToolMetadata;
+}
+/**
+ * Scan a directory for custom tool files and extract their metadata.
+ *
+ * @param folderPath Absolute path to the custom-tools directory.
+ * @returns Array of discovered tools with parsed metadata.
+ * @throws If any file fails metadata extraction.
+ */
+declare function scanCustomTools(folderPath: string): DiscoveredTool[];
+/**
+ * Scan a folder and return a Map<toolName, ProxyTool> ready for registration
+ * with YAMLLoader.
+ */
+declare function loadCustomTools(folderPath: string): Map<string, ProxyTool>;
+
 /**
  * System prompts for CodeAgent
  *
@@ -1105,10 +1359,17 @@ interface LoadedWorkflow {
 }
 declare class YAMLLoader {
     private customTools;
+    private toolInstances;
     /**
-     * Register a custom tool type for use in YAML definitions.
+     * Register a custom tool type (class) for use in YAML definitions.
      */
     registerToolType(typeName: string, toolClass: new (config?: Record<string, unknown>) => Tool): void;
+    /**
+     * 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: string, tool: Tool): void;
     /**
      * Load a workflow from a YAML file path.
      */
@@ -1131,6 +1392,32 @@ declare class YAMLLoader {
     private buildAgent;
 }
 
+/**
+ * JSONOutputHandler - Emits structured NDJSON events for machine-readable CLI output.
+ */
+
+interface JSONOutputConfig {
+    runId: string;
+    verbose?: boolean;
+}
+declare class JSONOutputHandler {
+    private readonly runId;
+    private readonly startTime;
+    constructor(config: JSONOutputConfig);
+    private emit;
+    emitRunStart(workflowPath: string, task: string, cwd?: string): void;
+    emitWorkflowLoaded(name: string, description: string | undefined, agents: string[], tools: string[], entrypoint: string): void;
+    emitRunEnd(success: boolean, output: unknown, totalTokens: number, totalSteps: number): void;
+    emitAgentStart(agentName: string, depth: number, task: string, agentType: string, maxSteps: number): void;
+    emitAgentEnd(agentName: string, depth: number, output: unknown, totalSteps: number, tokenUsage: TokenUsage | undefined, duration: number, success: boolean): void;
+    emitAgentStep(agentName: string, depth: number, stepNumber: number, maxSteps: number, phase: string): void;
+    emitAgentThinking(agentName: string, depth: number, stepNumber: number, content: string, isPartial: boolean): void;
+    emitToolCall(agentName: string, depth: number, stepNumber: number, toolCallId: string, toolName: string, args: Record<string, unknown>): void;
+    emitToolResult(agentName: string, depth: number, stepNumber: number, toolCallId: string, toolName: string, result: unknown, error: string | undefined, duration: number): void;
+    emitObservation(agentName: string, depth: number, stepNumber: number, observation: string, codeAction: string | undefined, logs: string | undefined): void;
+    emitError(message: string, stack?: string, agentName?: string, depth?: number, stepNumber?: number): void;
+}
+
 /**
  * Orchestrator - Loads, runs, and provides real-time visibility into agent execution
  */
@@ -1140,12 +1427,20 @@ interface OrchestratorConfig {
     verbose?: boolean;
     /** Callback for orchestrator events */
     onEvent?: (event: OrchestratorEvent) => void;
+    /** Output format: 'text' for chalk-formatted console, 'json' for NDJSON streaming */
+    outputFormat?: OutputFormat;
+    /** Unique run identifier (required for JSON output) */
+    runId?: string;
+    /** Working directory for agent file operations */
+    cwd?: string;
 }
 declare class Orchestrator {
     private loader;
     private config;
     private activeAgents;
     private eventLog;
+    private jsonOutput;
+    private isJsonMode;
     constructor(config?: OrchestratorConfig);
     /**
      * Load a workflow from a YAML file.
@@ -1154,11 +1449,11 @@ declare class Orchestrator {
     /**
      * Load a workflow from YAML string.
      */
-    loadWorkflowFromString(yamlContent: string): LoadedWorkflow;
+    loadWorkflowFromString(yamlContent: string, sourcePath?: string): LoadedWorkflow;
     /**
      * Run a loaded workflow with a task.
      */
-    runWorkflow(workflow: LoadedWorkflow, task: string): Promise<RunResult>;
+    runWorkflow(workflow: LoadedWorkflow, task: string, workflowPath?: string): Promise<RunResult>;
     /**
      * Run a standalone agent with a task.
      */
@@ -1167,6 +1462,10 @@ declare class Orchestrator {
      * Instrument an agent with orchestrator event tracking.
      */
     private instrumentAgent;
+    /**
+     * Emit an agent event as JSON.
+     */
+    private emitAgentEventAsJSON;
     /**
      * Display workflow info at startup.
      */
@@ -1195,6 +1494,18 @@ declare class Orchestrator {
      * Get the YAML loader for registering custom tools.
      */
     getLoader(): YAMLLoader;
+    /**
+     * Get the JSON output handler (if in JSON mode).
+     */
+    getJSONOutputHandler(): JSONOutputHandler | null;
+    /**
+     * Check if in JSON output mode.
+     */
+    isJSONOutputMode(): boolean;
+    /**
+     * Get the run ID.
+     */
+    getRunId(): string | undefined;
 }
 
-export { type ActionOutput, type ActionStep, Agent, type AgentConfig, type AgentConfig$1 as AgentConfigType, AgentLogger, AgentMemory, AgentTool, type AgentToolConfig, type ChatMessage, CodeAgent, type CodeAgentConfig, type CodeExecutionOutput, CurlTool, ExaGetContentsTool, ExaResearchTool, ExaSearchTool, type ExecutorConfig, FINAL_ANSWER_PROMPT, type FinalAnswerStep, FinalAnswerTool, type GenerateOptions, type LoadedWorkflow, LocalExecutor, LogLevel, type MemoryStep, type MemoryStrategy, type MessageRole, Model, type ModelConfig, OpenAIModel, type OpenAIModelConfig, type OpenAIToolDefinition, Orchestrator, type OrchestratorConfig, type OrchestratorEvent, type PromptVariables, ReadFileTool, type RunResult, type StreamEvent, type SystemPromptStep, type TaskStep, type Timing, type TokenUsage, Tool, type ToolCall, type ToolCallResult, type ToolInput, type ToolInputType, type ToolInputs, ToolUseAgent, type ToolUseAgentConfig, type ToolUsePromptVariables, UserInputTool, WriteFileTool, type YAMLAgentDefinition, YAMLLoader, type YAMLModelDefinition, type YAMLToolDefinition, type YAMLWorkflowDefinition, agentAsTool, createTool, finalAnswerTool, formatToolDescriptions, generateSystemPrompt, generateToolUseSystemPrompt, getErrorRecoveryPrompt };
+export { type ActionOutput, type ActionStep, Agent, type AgentConfig, type AgentConfig$1 as AgentConfigType, AgentLogger, AgentMemory, AgentTool, type AgentToolConfig, type ChatMessage, CodeAgent, type CodeAgentConfig, type CodeExecutionOutput, CurlTool, type CustomToolMetadata, type DiscoveredTool, ExaGetContentsTool, ExaResearchTool, ExaSearchTool, type ExecutorConfig, FINAL_ANSWER_PROMPT, type FinalAnswerStep, FinalAnswerTool, type GenerateOptions, type JSONAgentEndEvent, type JSONAgentObservationEvent, type JSONAgentStartEvent, type JSONAgentStepEvent, type JSONAgentThinkingEvent, type JSONAgentToolCallEvent, type JSONAgentToolResultEvent, type JSONErrorEvent, type JSONEvent, type JSONEventBase, type JSONEventType, type JSONLogEvent, type JSONOutputConfig, JSONOutputHandler, type JSONRunEndEvent, type JSONRunStartEvent, type JSONWorkflowLoadedEvent, type LoadedWorkflow, LocalExecutor, LogLevel, type MemoryStep, type MemoryStrategy, type MessageRole, Model, type ModelConfig, OpenAIModel, type OpenAIModelConfig, type OpenAIToolDefinition, Orchestrator, type OrchestratorConfig, type OrchestratorEvent, type OutputFormat, type PromptVariables, ProxyTool, type ProxyToolConfig, ReadFileTool, type RunResult, type StreamEvent, type SystemPromptStep, type TaskStep, type Timing, type TokenUsage, Tool, type ToolCall, type ToolCallResult, type ToolInput, type ToolInputType, type ToolInputs, ToolUseAgent, type ToolUseAgentConfig, type ToolUsePromptVariables, UserInputTool, WriteFileTool, type YAMLAgentDefinition, YAMLLoader, type YAMLModelDefinition, type YAMLToolDefinition, type YAMLWorkflowDefinition, agentAsTool, createTool, finalAnswerTool, formatToolDescriptions, generateSystemPrompt, generateToolUseSystemPrompt, getErrorRecoveryPrompt, loadCustomTools, scanCustomTools };