@samrahimi/smol-js 0.7.0 → 0.7.2

package/dist/index.d.mts

@@ -165,7 +165,7 @@ interface GenerateOptions {
 }
 interface YAMLAgentDefinition {
     name: string;
-    type: 'ToolUseAgent' | 'CodeAgent';
+    type: 'ToolUseAgent' | 'CodeAgent' | 'TerminalAgent';
     description?: string;
     model?: YAMLModelDefinition;
     tools?: string[];
@@ -926,6 +926,78 @@ declare class ToolUseAgent extends Agent {
     addTool(tool: Tool): void;
 }
 
+/**
+ * TerminalAgent - Accomplishes tasks by reasoning about and executing shell commands.
+ *
+ * Unlike CodeAgent (sandboxed JS VM) or ToolUseAgent (structured function calls),
+ * TerminalAgent operates by having the LLM emit shell commands in fenced ```sh
+ * blocks. Each block is executed on the user's real macOS terminal with full
+ * stdout/stderr streaming.
+ *
+ * Key behaviours:
+ *   - Verbose logging is always on. The user sees reasoning, pending commands,
+ *     and live output.
+ *   - A 5-second delay fires before every command batch so the user can read
+ *     what is about to run and abort with Ctrl+C.
+ *   - User-assigned tools are stripped. The agent always has final_answer and
+ *     any AgentTools (sub-agent delegation) that were wired in via YAML.
+ *   - Commands run via child_process with stdio piped so output is captured
+ *     and streamed back to the agent as observations.
+ */
+
+interface TerminalAgentConfig extends AgentConfig {
+    /**
+     * Seconds to wait before executing each command batch.
+     * Gives the user time to read pending commands and Ctrl+C.
+     * Default: 5
+     */
+    commandDelay?: number;
+    /**
+     * Maximum characters of command output to feed back to the LLM per batch.
+     * Very long outputs are truncated (head + tail preserved) to keep context
+     * manageable. Default: 8000
+     */
+    maxOutputLength?: number;
+}
+declare class TerminalAgent extends Agent {
+    private readonly commandDelay;
+    private readonly maxOutputLength;
+    constructor(config: TerminalAgentConfig);
+    /**
+     * Build the system prompt. Includes delegation info if sub-agents are present.
+     */
+    protected initializeSystemPrompt(): string;
+    /**
+     * Execute one step of the ReAct loop:
+     *   1. Send messages to LLM (with tool defs for final_answer / delegation)
+     *   2. Extract reasoning and ```sh blocks from the response
+     *   3. If tool calls present (final_answer or delegation), process them
+     *   4. Otherwise execute shell commands with the pre-execution delay
+     *   5. Feed stdout/stderr/exit-code back as observation
+     */
+    protected executeStep(memoryStep: ActionStep): Promise<ActionOutput>;
+    /**
+     * Run a single shell command, capture stdout/stderr, return structured result.
+     */
+    private runCommand;
+    /**
+     * Truncate long output, preserving head and tail so context stays useful.
+     */
+    private truncateOutput;
+    /**
+     * Generate response, with streaming if available.
+     */
+    private generateResponse;
+    /**
+     * Process tool calls (final_answer or AgentTool delegation).
+     */
+    private processToolCalls;
+    /**
+     * Override: force final answer via tool call format when max steps hit.
+     */
+    protected provideFinalAnswer(task: string): Promise<unknown>;
+}
+
 /**
  * OpenAI-compatible Model implementation
  *
@@ -1191,27 +1263,31 @@ declare class ExaResearchTool extends Tool {
 
 /**
  * ProxyTool - Bridges the smol-js agent runtime to an external standalone tool
- * executed in an isolated Bun process.
+ * executed in an isolated Bun process via the toolHarness adapter.
+ *
+ * The tool file is never imported into the main Node.js process. When an agent
+ * invokes this proxy, it spawns:
+ *
+ *   bun run <toolHarness.ts> <toolPath> <argsJson>
  *
- * 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.
+ * The harness is the ONLY place that speaks the stdout protocol. The tool
+ * itself simply exports { TOOL_METADATA, execute } and knows nothing about
+ * how it is being called.
  *
- * Protocol (stdout of child):
- *   - Lines prefixed with `[TOOL_OUTPUT]` are streaming log lines from the tool.
+ * Protocol (stdout of harness/child):
  *   - 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.
+ *   - Any other stdout line (e.g. console.log inside execute()) is streaming output.
  *
- * 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.
+ * Extensibility: The spawn+stdio transport is fully encapsulated here. A future
+ * variant (HTTP, gRPC, IPC) only needs to replace execute() — the tool file and
+ * YAML definition stay identical.
  */
 
 interface ProxyToolConfig {
     /** Absolute path to the .ts or .js tool file */
     toolPath: string;
-    /** Tool name (must match the class name inside the file) */
+    /** Tool name (must match the file's base name) */
     name: string;
     /** Human-readable description exposed to agents */
     description: string;
@@ -1230,14 +1306,16 @@ declare class ProxyTool extends Tool {
     private readonly toolPath;
     private readonly timeout;
     private bunPath;
+    private harnessPath;
     constructor(config: ProxyToolConfig);
     /**
-     * Ensure Bun is available before first invocation.
+     * Ensure Bun is available and locate the harness 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.
+     * Spawn the harness in a Bun child process. The harness imports the tool,
+     * calls execute(args), and writes the protocol lines. Any console.log from
+     * the tool flows through stdout as plain lines.
      */
     execute(args: Record<string, unknown>): Promise<unknown>;
     private processLine;
@@ -1508,4 +1586,4 @@ declare class Orchestrator {
     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, 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 };
+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, TerminalAgent, type TerminalAgentConfig, 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 };

package/dist/index.d.ts

@@ -165,7 +165,7 @@ interface GenerateOptions {
 }
 interface YAMLAgentDefinition {
     name: string;
-    type: 'ToolUseAgent' | 'CodeAgent';
+    type: 'ToolUseAgent' | 'CodeAgent' | 'TerminalAgent';
     description?: string;
     model?: YAMLModelDefinition;
     tools?: string[];
@@ -926,6 +926,78 @@ declare class ToolUseAgent extends Agent {
     addTool(tool: Tool): void;
 }
 
+/**
+ * TerminalAgent - Accomplishes tasks by reasoning about and executing shell commands.
+ *
+ * Unlike CodeAgent (sandboxed JS VM) or ToolUseAgent (structured function calls),
+ * TerminalAgent operates by having the LLM emit shell commands in fenced ```sh
+ * blocks. Each block is executed on the user's real macOS terminal with full
+ * stdout/stderr streaming.
+ *
+ * Key behaviours:
+ *   - Verbose logging is always on. The user sees reasoning, pending commands,
+ *     and live output.
+ *   - A 5-second delay fires before every command batch so the user can read
+ *     what is about to run and abort with Ctrl+C.
+ *   - User-assigned tools are stripped. The agent always has final_answer and
+ *     any AgentTools (sub-agent delegation) that were wired in via YAML.
+ *   - Commands run via child_process with stdio piped so output is captured
+ *     and streamed back to the agent as observations.
+ */
+
+interface TerminalAgentConfig extends AgentConfig {
+    /**
+     * Seconds to wait before executing each command batch.
+     * Gives the user time to read pending commands and Ctrl+C.
+     * Default: 5
+     */
+    commandDelay?: number;
+    /**
+     * Maximum characters of command output to feed back to the LLM per batch.
+     * Very long outputs are truncated (head + tail preserved) to keep context
+     * manageable. Default: 8000
+     */
+    maxOutputLength?: number;
+}
+declare class TerminalAgent extends Agent {
+    private readonly commandDelay;
+    private readonly maxOutputLength;
+    constructor(config: TerminalAgentConfig);
+    /**
+     * Build the system prompt. Includes delegation info if sub-agents are present.
+     */
+    protected initializeSystemPrompt(): string;
+    /**
+     * Execute one step of the ReAct loop:
+     *   1. Send messages to LLM (with tool defs for final_answer / delegation)
+     *   2. Extract reasoning and ```sh blocks from the response
+     *   3. If tool calls present (final_answer or delegation), process them
+     *   4. Otherwise execute shell commands with the pre-execution delay
+     *   5. Feed stdout/stderr/exit-code back as observation
+     */
+    protected executeStep(memoryStep: ActionStep): Promise<ActionOutput>;
+    /**
+     * Run a single shell command, capture stdout/stderr, return structured result.
+     */
+    private runCommand;
+    /**
+     * Truncate long output, preserving head and tail so context stays useful.
+     */
+    private truncateOutput;
+    /**
+     * Generate response, with streaming if available.
+     */
+    private generateResponse;
+    /**
+     * Process tool calls (final_answer or AgentTool delegation).
+     */
+    private processToolCalls;
+    /**
+     * Override: force final answer via tool call format when max steps hit.
+     */
+    protected provideFinalAnswer(task: string): Promise<unknown>;
+}
+
 /**
  * OpenAI-compatible Model implementation
  *
@@ -1191,27 +1263,31 @@ declare class ExaResearchTool extends Tool {
 
 /**
  * ProxyTool - Bridges the smol-js agent runtime to an external standalone tool
- * executed in an isolated Bun process.
+ * executed in an isolated Bun process via the toolHarness adapter.
+ *
+ * The tool file is never imported into the main Node.js process. When an agent
+ * invokes this proxy, it spawns:
+ *
+ *   bun run <toolHarness.ts> <toolPath> <argsJson>
  *
- * 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.
+ * The harness is the ONLY place that speaks the stdout protocol. The tool
+ * itself simply exports { TOOL_METADATA, execute } and knows nothing about
+ * how it is being called.
  *
- * Protocol (stdout of child):
- *   - Lines prefixed with `[TOOL_OUTPUT]` are streaming log lines from the tool.
+ * Protocol (stdout of harness/child):
  *   - 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.
+ *   - Any other stdout line (e.g. console.log inside execute()) is streaming output.
  *
- * 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.
+ * Extensibility: The spawn+stdio transport is fully encapsulated here. A future
+ * variant (HTTP, gRPC, IPC) only needs to replace execute() — the tool file and
+ * YAML definition stay identical.
  */
 
 interface ProxyToolConfig {
     /** Absolute path to the .ts or .js tool file */
     toolPath: string;
-    /** Tool name (must match the class name inside the file) */
+    /** Tool name (must match the file's base name) */
     name: string;
     /** Human-readable description exposed to agents */
     description: string;
@@ -1230,14 +1306,16 @@ declare class ProxyTool extends Tool {
     private readonly toolPath;
     private readonly timeout;
     private bunPath;
+    private harnessPath;
     constructor(config: ProxyToolConfig);
     /**
-     * Ensure Bun is available before first invocation.
+     * Ensure Bun is available and locate the harness 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.
+     * Spawn the harness in a Bun child process. The harness imports the tool,
+     * calls execute(args), and writes the protocol lines. Any console.log from
+     * the tool flows through stdout as plain lines.
      */
     execute(args: Record<string, unknown>): Promise<unknown>;
     private processLine;
@@ -1508,4 +1586,4 @@ declare class Orchestrator {
     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, 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 };
+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, TerminalAgent, type TerminalAgentConfig, 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 };