@samrahimi/smol-js 0.7.1 → 0.7.3

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
  *
@@ -1514,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
  *
@@ -1514,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.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   Orchestrator: () => Orchestrator,
   ProxyTool: () => ProxyTool,
   ReadFileTool: () => ReadFileTool,
+  TerminalAgent: () => TerminalAgent,
   Tool: () => Tool,
   ToolUseAgent: () => ToolUseAgent,
   UserInputTool: () => UserInputTool,
@@ -2108,6 +2109,369 @@ Please try a different approach.`
   }
 };
 
+// src/agents/TerminalAgent.ts
+var import_child_process = require("child_process");
+
+// src/prompts/terminalAgent.ts
+function generateTerminalAgentSystemPrompt(variables) {
+  const { customInstructions, hasSubAgents, subAgentDescriptions } = variables;
+  let delegationSection = "";
+  if (hasSubAgents) {
+    delegationSection = `
+## Delegation to Sub-Agents
+
+You can delegate tasks to specialized sub-agents when terminal commands alone
+are not sufficient. Available sub-agents:
+
+${subAgentDescriptions}
+
+To delegate, call the sub-agent tool with a clear task description. Wait for
+its result before continuing. Sub-agents handle their own tool calls internally.
+`;
+  }
+  return `You are a terminal operations agent running on macOS. You accomplish tasks
+by reasoning about what shell commands to run and executing them one or more at
+a time.
+
+## How You Work
+
+You follow a ReAct (Reasoning + Acting) loop:
+1. **Think**: Analyze the task and decide what commands to run next.
+2. **Act**: Emit one or more shell commands inside a fenced code block.
+3. **Observe**: Review the command output (stdout, stderr, exit code) that the
+   framework feeds back to you.
+4. Repeat until the task is complete, then signal your final answer (see below).
+
+## Emitting Commands
+
+Place your shell commands inside a fenced sh code block. You may include
+multiple commands separated by newlines. Each command is executed
+sequentially in its own shell invocation on the user's macOS terminal:
+
+\`\`\`sh
+echo "hello"
+\`\`\`
+
+\`\`\`sh
+ls -la ~/Documents
+pwd
+\`\`\`
+
+**Important**: Each code block is treated as a batch. Commands within a single
+block run sequentially. The output of the entire block is returned as one
+observation. If you need to inspect intermediate output before proceeding,
+use separate blocks across steps.
+
+## Rules
+
+1. **Safety first**: Before running anything destructive (rm, mv on important
+   files, format commands, etc.), explain what you are about to do in your
+   reasoning so the user can read it during the 5-second delay and abort with
+   Ctrl+C if needed.
+
+2. **Signalling completion**: When the task is done, do NOT emit any more
+   \`\`\`sh blocks. Instead, write your summary on a line that starts with
+   the exact marker:
+
+   FINAL_ANSWER: <your summary here>
+
+   Everything after "FINAL_ANSWER: " (including multiple lines) is captured
+   as your final answer. This is how you tell the framework you are finished.
+
+3. **Handle errors**: If a command fails (non-zero exit code or stderr output),
+   analyze what went wrong and try a corrective approach. Do not repeat the
+   exact same command.
+
+4. **Be explicit about paths**: Use absolute paths or \`cd\` explicitly. Do not
+   assume the working directory persists between steps (it does not).
+
+5. **macOS conventions**: Use macOS / BSD variants of commands (e.g. \`gstat\`
+   may not exist; use \`stat\` with the right flags). Prefer Homebrew paths
+   (\`/opt/homebrew/bin\`) for installed tools. Use \`sw_vers\` for OS info.
+
+6. **Prefer streaming-friendly commands**: Avoid commands that buffer all output
+   until completion. Prefer tools that print as they go.
+
+7. **No interactive prompts**: Do not run commands that wait for user input
+   (e.g. \`ssh\` without key auth, interactive installers). If a command would
+   prompt, pass flags to make it non-interactive or use \`yes |\` piping.
+${delegationSection}
+${customInstructions ? `## Additional Instructions
+
+${customInstructions}` : ""}
+
+Begin. Think about the task, then emit your first shell command(s).`;
+}
+
+// src/agents/TerminalAgent.ts
+var SH_BLOCK_REGEX = /```(?:sh|bash|shell|zsh)\n([\s\S]*?)```/g;
+var THOUGHT_REGEX2 = /(?:Thought|Reasoning|Think):\s*([\s\S]*?)(?=```|FINAL_ANSWER:|$)/i;
+var FINAL_ANSWER_MARKER = /^FINAL_ANSWER:\s*([\s\S]*)$/m;
+var NEWLINE = "\n";
+var TerminalAgent = class extends Agent {
+  commandDelay;
+  maxOutputLength;
+  constructor(config) {
+    super({ ...config, verboseLevel: 2 /* DEBUG */ });
+    this.commandDelay = config.commandDelay ?? 5;
+    this.maxOutputLength = config.maxOutputLength ?? 8e3;
+    const keepTools = /* @__PURE__ */ new Map();
+    for (const [name, tool] of this.tools) {
+      if (tool.constructor.name === "AgentTool") {
+        keepTools.set(name, tool);
+      }
+    }
+    this.tools = keepTools;
+    if (!this.tools.has("final_answer")) {
+      this.tools.set("final_answer", new FinalAnswerTool());
+    }
+  }
+  /**
+   * Build the system prompt. Includes delegation info if sub-agents are present.
+   */
+  initializeSystemPrompt() {
+    const agentTools = Array.from(this.tools.values()).filter(
+      (t) => t.constructor.name === "AgentTool"
+    );
+    const hasSubAgents = agentTools.length > 0;
+    const subAgentDescriptions = agentTools.map((t) => `- **${t.name}**: ${t.description}`).join("\n");
+    return generateTerminalAgentSystemPrompt({
+      customInstructions: this.config.customInstructions,
+      hasSubAgents,
+      subAgentDescriptions
+    });
+  }
+  /**
+   * 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
+   */
+  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 delegationTools = Array.from(this.tools.values()).filter((t) => t.constructor.name === "AgentTool");
+    const toolDefinitions = delegationTools.map((t) => t.toOpenAITool());
+    this.logger.subheader("Agent thinking...");
+    const response = await this.generateResponse(messages, toolDefinitions);
+    memoryStep.modelOutputMessage = response;
+    memoryStep.tokenUsage = response.tokenUsage;
+    const content = response.content ?? "";
+    const thoughtMatch = content.match(THOUGHT_REGEX2);
+    if (thoughtMatch) {
+      this.logger.reasoning(thoughtMatch[1].trim());
+      this.emitEvent("agent_thinking", { step: this.currentStep, content: thoughtMatch[1].trim() });
+    }
+    const finalMatch = content.match(FINAL_ANSWER_MARKER);
+    if (finalMatch) {
+      const answer = finalMatch[1].trim();
+      this.logger.finalAnswer(answer);
+      return { output: answer, isFinalAnswer: true };
+    }
+    if (response.toolCalls && response.toolCalls.length > 0) {
+      memoryStep.toolCalls = response.toolCalls;
+      const results = await this.processToolCalls(response.toolCalls);
+      memoryStep.toolResults = results;
+      for (const result of results) {
+        if (result.error) {
+          this.logger.error(`Tool ${result.toolName} failed: ${result.error}`);
+        } else {
+          const str = typeof result.result === "string" ? result.result : JSON.stringify(result.result, null, 2);
+          this.logger.output(`[${result.toolName}]: ${str.slice(0, 500)}${str.length > 500 ? "..." : ""}`);
+        }
+      }
+      const obs = results.map((r) => r.error ? `[${r.toolName}] Error: ${r.error}` : `[${r.toolName}] Result: ${typeof r.result === "string" ? r.result : JSON.stringify(r.result)}`).join("\n");
+      memoryStep.observation = `Observation:
+${obs}`;
+      return { output: null, isFinalAnswer: false };
+    }
+    const blocks = [];
+    let match;
+    const regex = new RegExp(SH_BLOCK_REGEX.source, "g");
+    while ((match = regex.exec(content)) !== null) {
+      blocks.push(match[1].trim());
+    }
+    if (blocks.length === 0) {
+      this.logger.warn("No shell commands or tool calls in response.");
+      memoryStep.observation = "No shell command block was found in your response. Emit commands inside a ```sh code block, or call final_answer if the task is complete.";
+      return { output: null, isFinalAnswer: false };
+    }
+    const allCommands = blocks.join("\n---\n");
+    this.logger.code(allCommands, "sh");
+    this.emitEvent("agent_observation", {
+      step: this.currentStep,
+      observation: `Pending commands:
+${allCommands}`
+    });
+    this.logger.waiting(this.commandDelay);
+    await this.sleep(this.commandDelay * 1e3);
+    const observations = [];
+    let hitError = false;
+    for (let i = 0; i < blocks.length; i++) {
+      const block = blocks[i];
+      const commands = block.split(NEWLINE).filter((l) => l.trim() && !l.trim().startsWith("#"));
+      this.logger.subheader(`Executing command block ${blocks.length > 1 ? `${i + 1}/${blocks.length}` : ""}...`);
+      for (const cmd of commands) {
+        this.logger.info(`  $ ${cmd}`);
+        const result = this.runCommand(cmd);
+        if (result.stdout) {
+          this.logger.logs(result.stdout);
+        }
+        if (result.stderr) {
+          this.logger.error(`stderr: ${result.stderr}`);
+        }
+        observations.push(
+          `$ ${cmd}
+` + (result.stdout ? `stdout:
+${result.stdout}` : "") + (result.stderr ? `stderr:
+${result.stderr}` : "") + `exit code: ${result.exitCode}`
+        );
+        if (result.exitCode !== 0) {
+          hitError = true;
+          break;
+        }
+      }
+      if (hitError) break;
+    }
+    const observation = observations.join("\n\n");
+    memoryStep.observation = `Observation:
+${observation}`;
+    if (hitError) {
+      memoryStep.error = new Error("Command exited with non-zero status. See observation for details.");
+    }
+    return { output: observation, isFinalAnswer: false };
+  }
+  /**
+   * Run a single shell command, capture stdout/stderr, return structured result.
+   */
+  runCommand(cmd) {
+    try {
+      const stdout = (0, import_child_process.execSync)(cmd, {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: "/bin/zsh",
+        timeout: 12e4,
+        // 2-minute per-command timeout
+        maxBuffer: 50 * 1024 * 1024
+        // 50 MB
+      });
+      return { stdout: this.truncateOutput(stdout), stderr: "", exitCode: 0 };
+    } catch (err) {
+      const e = err;
+      return {
+        stdout: this.truncateOutput(e.stdout ?? ""),
+        stderr: this.truncateOutput(e.stderr ?? e.message),
+        exitCode: e.status ?? 1
+      };
+    }
+  }
+  /**
+   * Truncate long output, preserving head and tail so context stays useful.
+   */
+  truncateOutput(output) {
+    if (output.length <= this.maxOutputLength) return output;
+    const half = Math.floor(this.maxOutputLength / 2);
+    const head = output.slice(0, half);
+    const tail = output.slice(output.length - half);
+    const omitted = output.length - this.maxOutputLength;
+    return `${head}
+
+... [${omitted} characters omitted] ...
+
+${tail}`;
+  }
+  /**
+   * Generate response, with streaming if available.
+   */
+  async generateResponse(messages, toolDefinitions) {
+    if (this.config.streamOutputs && this.model.supportsStreaming() && this.model.generateStream) {
+      let fullContent = "";
+      const generator = this.model.generateStream(messages, {
+        toolDefinitions,
+        maxTokens: this.config.maxTokens,
+        temperature: this.config.temperature
+      });
+      for await (const chunk of generator) {
+        this.logger.streamChar(chunk);
+        fullContent += chunk;
+      }
+      this.logger.streamEnd();
+      return { role: "assistant", content: fullContent };
+    }
+    return this.model.generate(messages, {
+      toolDefinitions,
+      maxTokens: this.config.maxTokens,
+      temperature: this.config.temperature
+    });
+  }
+  /**
+   * Process tool calls (final_answer or AgentTool delegation).
+   */
+  async processToolCalls(toolCalls) {
+    const results = [];
+    for (const tc of toolCalls) {
+      const toolName = tc.function.name;
+      const tool = this.tools.get(toolName);
+      if (!tool) {
+        results.push({ toolCallId: tc.id, toolName, result: null, error: `Unknown tool: ${toolName}` });
+        continue;
+      }
+      let args;
+      try {
+        args = typeof tc.function.arguments === "string" ? JSON.parse(tc.function.arguments) : tc.function.arguments;
+      } catch {
+        results.push({ toolCallId: tc.id, toolName, result: null, error: "Failed to parse tool arguments" });
+        continue;
+      }
+      this.logger.info(`  Calling tool: ${toolName}(${JSON.stringify(args).slice(0, 100)}...)`);
+      this.emitEvent("agent_tool_call", { step: this.currentStep, toolCallId: tc.id, toolName, arguments: args });
+      try {
+        const result = await tool.call(args);
+        this.emitEvent("agent_tool_result", { step: this.currentStep, toolCallId: tc.id, toolName, result, duration: 0 });
+        results.push({ toolCallId: tc.id, toolName, result });
+      } catch (error) {
+        const msg = `Tool execution error: ${error.message}`;
+        this.emitEvent("agent_tool_result", { step: this.currentStep, toolCallId: tc.id, toolName, result: null, error: msg, duration: 0 });
+        results.push({ toolCallId: tc.id, toolName, result: null, error: msg });
+      }
+    }
+    return results;
+  }
+  /**
+   * Override: force final answer via tool call format when max steps hit.
+   */
+  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) {
+      try {
+        const args = typeof response.toolCalls[0].function.arguments === "string" ? JSON.parse(response.toolCalls[0].function.arguments) : response.toolCalls[0].function.arguments;
+        return args.answer;
+      } catch {
+        return response.content;
+      }
+    }
+    return response.content;
+  }
+};
+
 // src/models/Model.ts
 var Model = class {
   /**
@@ -2847,11 +3211,11 @@ var ExaResearchTool = class extends Tool {
 };
 
 // src/tools/ProxyTool.ts
-var import_child_process2 = require("child_process");
+var import_child_process3 = require("child_process");
 var path6 = __toESM(require("path"));
 
 // src/utils/bunInstaller.ts
-var import_child_process = require("child_process");
+var import_child_process2 = require("child_process");
 var path5 = __toESM(require("path"));
 var fs5 = __toESM(require("fs"));
 var os3 = __toESM(require("os"));
@@ -2872,7 +3236,7 @@ async function ensureBunAvailable() {
     "\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", {
+    (0, import_child_process2.execSync)("curl --proto =https --tlsv1.2 -sSf https://bun.sh | bash", {
       stdio: "inherit",
       shell: "/bin/bash",
       env: { ...process.env, HOME: os3.homedir() }
@@ -2897,7 +3261,7 @@ Details: ${err.message}`
 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 result = (0, import_child_process2.execSync)(cmd, { encoding: "utf8", stdio: "pipe" }).trim();
     const first = result.split("\n")[0]?.trim();
     if (first && fs5.existsSync(first)) return first;
     return null;
@@ -2950,7 +3314,7 @@ var ProxyTool = class extends Tool {
     }
     const serializedArgs = JSON.stringify(args);
     return new Promise((resolve7, reject) => {
-      const child = (0, import_child_process2.spawn)(this.bunPath, ["run", this.harnessPath, this.toolPath, serializedArgs], {
+      const child = (0, import_child_process3.spawn)(this.bunPath, ["run", this.harnessPath, this.toolPath, serializedArgs], {
         stdio: ["pipe", "pipe", "pipe"],
         env: { ...process.env }
       });
@@ -3321,32 +3685,24 @@ var YAMLLoader = class {
       }
     }
     const maxContextLength = definition.maxContextLength ?? globalMaxContextLength;
+    const sharedConfig = {
+      model,
+      tools: agentTools,
+      maxSteps: definition.maxSteps,
+      customInstructions: definition.customInstructions,
+      persistent: definition.persistent,
+      maxContextLength,
+      memoryStrategy: definition.memoryStrategy,
+      maxTokens: definition.maxTokens,
+      temperature: definition.temperature,
+      name
+    };
     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
-      });
+      return new CodeAgent(sharedConfig);
+    } else if (definition.type === "TerminalAgent") {
+      return new TerminalAgent(sharedConfig);
     } 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
-      });
+      return new ToolUseAgent(sharedConfig);
     }
   }
 };
@@ -3746,6 +4102,7 @@ var Orchestrator = class {
   Orchestrator,
   ProxyTool,
   ReadFileTool,
+  TerminalAgent,
   Tool,
   ToolUseAgent,
   UserInputTool,