@samrahimi/smol-js 0.2.0 → 0.4.0

package/README.md

@@ -1,17 +1,24 @@
 # smol-js
 
-A TypeScript port of the [smolagents](https://github.com/huggingface/smolagents) agentic framework. This library provides a CodeAgent that can solve tasks by generating and executing JavaScript code in a sandboxed environment.
+**A TypeScript port of the [smolagents](https://github.com/huggingface/smolagents) agentic framework.**
+
+Build AI agents that solve tasks by writing and executing JavaScript code. The agent reasons about problems, generates code, executes it in a sandbox, observes results, and iterates until it finds the answer.
+
+[![npm version](https://img.shields.io/npm/v/@samrahimi/smol-js.svg)](https://www.npmjs.com/package/@samrahimi/smol-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **CodeAgent**: An LLM-powered agent that generates JavaScript code to solve tasks
-- **Multi-step execution**: Variables persist between steps for complex workflows
-- **Tool system**: Extensible tools that the agent can use as functions
-- **Dynamic imports**: Import npm packages on-the-fly via CDN
-- **OpenAI-compatible API**: Works with OpenRouter, OpenAI, Azure, and local servers
-- **Streaming support**: Real-time output streaming from the LLM
-- **Color-coded logging**: Beautiful terminal output with syntax highlighting
-- **Error recovery**: Agent can recover from errors and try different approaches
+- **ReAct Framework**: Reasoning + Acting loop (Thought → Code → Observation → repeat)
+- **Sandboxed Execution**: JavaScript runs in Node's vm module with state persistence
+- **Tool System**: Extensible tools that agents can call as functions
+- **Nested Agents**: Use agents as tools for hierarchical task delegation
+- **Dynamic Imports**: Import npm packages on-the-fly via jsdelivr CDN
+- **Built-in fetch()**: Agents can make HTTP requests directly in generated code
+- **OpenAI-Compatible**: Works with OpenRouter, OpenAI, Azure, Anthropic, and local servers
+- **Streaming**: Real-time output streaming from the LLM
+- **Color-Coded Logging**: Beautiful terminal output with session logging to disk
+- **Error Recovery**: Agent can recover from errors and try different approaches
 
 ## Installation
 
@@ -19,20 +26,15 @@ A TypeScript port of the [smolagents](https://github.com/huggingface/smolagents)
 npm install @samrahimi/smol-js
 ```
 
-Or with yarn:
-
-```bash
-yarn add @samrahimi/smol-js
-```
-
 ## Quick Start
 
 ```typescript
+import 'dotenv/config';
 import { CodeAgent, OpenAIModel } from '@samrahimi/smol-js';
 
-// Create the model (uses OPENAI_API_KEY env var)
+// Create the model (defaults to Claude via OpenRouter)
 const model = new OpenAIModel({
-  modelId: 'anthropic/claude-sonnet-4.5', // default, via OpenRouter
+  modelId: 'anthropic/claude-sonnet-4.5',
 });
 
 // Create the agent
@@ -43,7 +45,6 @@ const agent = new CodeAgent({
 
 // Run a task
 const result = await agent.run('Calculate the first 10 prime numbers');
-
 console.log(result.output); // [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
 ```
 
@@ -52,23 +53,23 @@ console.log(result.output); // [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
 ### Environment Variables
 
 ```bash
-# Required: API key for LLM provider
-OPENAI_API_KEY=your-api-key
+# API key for LLM provider (OpenRouter by default)
+OPENAI_API_KEY=sk-or-v1-your-openrouter-key
 
-# Or use OpenRouter specifically
-OPENROUTER_API_KEY=your-openrouter-key
+# Or for OpenAI directly
+OPENAI_API_KEY=sk-your-openai-key
 ```
 
 ### Model Configuration
 
 ```typescript
 const model = new OpenAIModel({
-  modelId: 'gpt-4',                    // Model identifier
-  apiKey: 'sk-...',                    // API key (or use env var)
-  baseUrl: 'https://api.openai.com/v1', // API endpoint
-  maxTokens: 4096,                      // Max tokens to generate
-  temperature: 0.7,                     // Generation temperature
-  timeout: 120000,                      // Request timeout in ms
+  modelId: 'anthropic/claude-sonnet-4.5', // Model identifier
+  apiKey: 'sk-...',                        // API key (or use env var)
+  baseUrl: 'https://openrouter.ai/api/v1', // API endpoint (default: OpenRouter)
+  maxTokens: 4096,                          // Max tokens to generate
+  temperature: 0.7,                         // Generation temperature
+  timeout: 120000,                          // Request timeout in ms
 });
 ```
 
@@ -77,20 +78,22 @@ const model = new OpenAIModel({
 ```typescript
 const agent = new CodeAgent({
   model,
-  tools: [myTool],              // Custom tools
-  maxSteps: 20,                 // Max iterations (default: 20)
-  codeExecutionDelay: 5000,     // Delay before execution in ms (default: 5000)
-  customInstructions: '...',    // Additional prompt instructions
-  verboseLevel: LogLevel.INFO,  // Logging level
-  streamOutputs: true,          // Stream LLM output
-  additionalAuthorizedImports: ['lodash', 'dayjs'], // Allowed npm packages
-  workingDirectory: '/path/to/dir', // Working dir for fs operations
+  tools: [myTool],                          // Custom tools
+  maxSteps: 20,                             // Max iterations (default: 20)
+  codeExecutionDelay: 5000,                 // Safety delay before execution (default: 5000ms)
+  customInstructions: '...',                // Additional system prompt instructions
+  verboseLevel: LogLevel.INFO,              // Logging level (OFF, ERROR, INFO, DEBUG)
+  streamOutputs: true,                      // Stream LLM output in real-time
+  additionalAuthorizedImports: ['lodash'],  // npm packages the agent can import
+  workingDirectory: '/path/to/dir',         // Working dir for fs operations
 });
 ```
 
 ## Creating Tools
 
-Tools extend the agent's capabilities. Create a tool by extending the `Tool` class:
+Tools extend the agent's capabilities. The agent sees tools as async functions it can call.
+
+### Class-Based Tools
 
 ```typescript
 import { Tool } from '@samrahimi/smol-js';
@@ -110,115 +113,164 @@ class WeatherTool extends Tool {
 
   async execute(args: Record<string, unknown>): Promise<unknown> {
     const city = args.city as string;
-    // Fetch weather data...
-    return { city, temperature: 22, condition: 'sunny' };
+    const response = await fetch(`https://api.weather.com/${city}`);
+    return response.json();
   }
 }
 
-// Use with agent
 const agent = new CodeAgent({
   model,
   tools: [new WeatherTool()],
 });
 ```
 
-Or use the `createTool` helper:
+### Functional Tools
 
 ```typescript
 import { createTool } from '@samrahimi/smol-js';
 
-const addNumbers = createTool({
-  name: 'add',
-  description: 'Adds two numbers',
+const calculator = createTool({
+  name: 'calculate',
+  description: 'Evaluate a math expression',
   inputs: {
-    a: { type: 'number', description: 'First number' },
-    b: { type: 'number', description: 'Second number' },
+    expression: { type: 'string', description: 'Math expression to evaluate', required: true },
   },
   outputType: 'number',
-  execute: async (args) => (args.a as number) + (args.b as number),
+  execute: async (args) => {
+    return new Function('Math', `return ${args.expression}`)(Math);
+  },
 });
 ```
 
-## Dynamic Imports
+## Nested Agents (Agent as Tool)
 
-The agent can import npm packages dynamically using `importPackage()`:
+Use agents as tools for hierarchical task delegation. A "manager" agent can delegate specialized tasks to "worker" agents.
 
 ```typescript
-const agent = new CodeAgent({
+import { CodeAgent, OpenAIModel, AgentTool, agentAsTool } from '@samrahimi/smol-js';
+
+// Create a specialized worker agent
+const mathAgent = new CodeAgent({
   model,
-  additionalAuthorizedImports: ['lodash', 'dayjs', 'uuid'],
+  tools: [calculatorTool],
+  maxSteps: 5,
+  verboseLevel: LogLevel.OFF, // Quiet - manager reports results
 });
 
-// The agent can now use:
-// const _ = await importPackage('lodash');
-// const dayjs = await importPackage('dayjs');
+// Wrap it as a tool
+const mathExpert = new AgentTool({
+  agent: mathAgent,
+  name: 'math_expert',
+  description: 'Delegate math problems to a specialized math agent',
+});
+
+// Or use the helper function
+const mathExpert = agentAsTool(mathAgent, {
+  name: 'math_expert',
+  description: 'Delegate math problems to a specialized math agent',
+});
+
+// Create manager that uses the worker
+const manager = new CodeAgent({
+  model,
+  tools: [mathExpert, researchExpert], // Agents as tools!
+  maxSteps: 10,
+});
+
+await manager.run('Research Tokyo population and calculate water consumption');
 ```
 
-Packages are fetched from [esm.sh](https://esm.sh) CDN.
+## Using fetch() Directly
 
-## Built-in Capabilities
+Agents can make HTTP requests directly in their code without needing a tool:
+
+```typescript
+const agent = new CodeAgent({
+  model,
+  tools: [], // No tools needed!
+  customInstructions: `You can use fetch() directly to make HTTP requests.
+Example: const data = await fetch('https://api.example.com').then(r => r.json());`,
+});
 
-The agent has access to:
+await agent.run('Fetch users from https://jsonplaceholder.typicode.com/users');
+```
 
-- `console.log()` / `print()` - Output logging
-- `fs` - File system operations (read, write, mkdir, etc.)
-- `path` - Path utilities
-- `fetch()` - HTTP requests
-- `JSON`, `Math`, `Date` - Standard JavaScript globals
-- `final_answer(value)` - Return the final result
+## Dynamic npm Imports
 
-## Log Levels
+The agent can import npm packages dynamically:
 
 ```typescript
-import { LogLevel } from '@samrahimi/smol-js';
+const agent = new CodeAgent({
+  model,
+  additionalAuthorizedImports: ['lodash', 'dayjs', 'uuid'],
+});
 
-LogLevel.OFF    // No output
-LogLevel.ERROR  // Errors only
-LogLevel.INFO   // Normal output (default)
-LogLevel.DEBUG  // Detailed debugging
+// The agent can now write:
+// const _ = await importPackage('lodash');
+// const dayjs = await importPackage('dayjs');
 ```
 
-## Session Logging
+Packages are fetched from [jsdelivr CDN](https://www.jsdelivr.com/) and cached locally in `~/.smol-js/packages/`.
 
-All sessions are logged to `~/.smol-js/session-<timestamp>.log`.
+## Built-in Capabilities
 
-## Examples
+The agent's sandbox includes:
 
-See the `examples/` folder for complete examples:
+| Category | Available |
+|----------|-----------|
+| **Output** | `console.log()`, `console.error()`, `print()` |
+| **HTTP** | `fetch()`, `URL`, `URLSearchParams` |
+| **File System** | `fs.readFileSync()`, `fs.writeFileSync()`, `fs.existsSync()`, etc. |
+| **Path** | `path.join()`, `path.resolve()`, `path.dirname()`, etc. |
+| **Data** | `JSON`, `Buffer`, `TextEncoder`, `TextDecoder` |
+| **Math** | `Math.*`, `parseInt()`, `parseFloat()` |
+| **Types** | `Object`, `Array`, `Map`, `Set`, `Date`, `RegExp`, `Promise` |
+| **Timers** | `setTimeout()`, `setInterval()` |
+| **Final** | `final_answer(value)` - Return the result |
 
-1. **01-simple-math.ts** - Basic calculation task
-2. **02-dynamic-imports.ts** - Using npm packages dynamically
-3. **03-variable-persistence.ts** - Multi-step state management
-4. **04-research-with-tools.ts** - Custom tools for research tasks
-5. **05-error-recovery.ts** - Handling and recovering from errors
+## Examples
 
-Run all examples:
+The `examples/` folder contains complete, runnable examples:
 
-```bash
-npm run run-examples
-```
+| Example | Description |
+|---------|-------------|
+| **01-simple-math.ts** | Basic calculation task |
+| **02-dynamic-imports.ts** | Using npm packages dynamically |
+| **03-variable-persistence.ts** | Multi-step state management |
+| **04-research-with-tools.ts** | Custom tools for research tasks |
+| **05-error-recovery.ts** | Handling and recovering from errors |
+| **06-deep-research.ts** | Real API calls with DuckDuckGo/Wikipedia |
+| **07-npm-package-import.ts** | Importing from the published npm package |
+| **08-fetch-agent.ts** | Agent using fetch() directly (no tools) |
+| **09-nested-agents.ts** | Manager agent delegating to worker agents |
 
-Or run a specific example:
+Run an example:
 
 ```bash
-npx tsx examples/01-simple-math.ts
+npx tsx examples/08-fetch-agent.ts
 ```
 
 ## API Reference
 
 ### CodeAgent
 
-Main agent class that generates and executes JavaScript code.
-
 ```typescript
 class CodeAgent {
   constructor(config: CodeAgentConfig)
+
+  // Run a task
   run(task: string, reset?: boolean): Promise<RunResult>
+
+  // Control
   stop(): void
   reset(): void
+
+  // Tools
   addTool(tool: Tool): void
   removeTool(name: string): boolean
   getTools(): Map<string, Tool>
+
+  // State
   getMemory(): AgentMemory
   getExecutor(): LocalExecutor
 }
@@ -228,10 +280,10 @@ class CodeAgent {
 
 ```typescript
 interface RunResult {
-  output: unknown;           // Final answer
-  steps: MemoryStep[];       // All execution steps
-  tokenUsage: TokenUsage;    // Total token usage
-  duration: number;          // Total time in ms
+  output: unknown;        // Final answer
+  steps: MemoryStep[];    // Execution history
+  tokenUsage: TokenUsage; // Token counts
+  duration: number;       // Total time in ms
 }
 ```
 
@@ -245,10 +297,30 @@ abstract class Tool {
   abstract readonly outputType: string;
 
   abstract execute(args: Record<string, unknown>): Promise<unknown>;
-  setup(): Promise<void>;
+
+  setup(): Promise<void>;          // Optional async initialization
   call(args: Record<string, unknown>): Promise<unknown>;
-  toCodePrompt(): string;
+  toCodePrompt(): string;          // Generate function signature for prompt
+}
+```
+
+### AgentTool
+
+```typescript
+class AgentTool extends Tool {
+  constructor(config: AgentToolConfig)
+}
+
+interface AgentToolConfig {
+  agent: Agent;              // The agent to wrap
+  name?: string;             // Tool name (default: 'managed_agent')
+  description?: string;      // Tool description
+  additionalContext?: string; // Extra context for the agent
+  returnFullResult?: boolean; // Return full result vs just output
 }
+
+// Helper function
+function agentAsTool(agent: Agent, options?: Omit<AgentToolConfig, 'agent'>): AgentTool
 ```
 
 ### LocalExecutor
@@ -256,35 +328,77 @@ abstract class Tool {
 ```typescript
 class LocalExecutor {
   constructor(config?: ExecutorConfig)
+
   execute(code: string): Promise<CodeExecutionOutput>
   sendTools(tools: Record<string, Tool>): void
   sendVariables(variables: Record<string, unknown>): void
   reset(): void
   getState(): Record<string, unknown>
 }
+
+interface ExecutorConfig {
+  timeout?: number;              // Execution timeout (default: 30000ms)
+  authorizedImports?: string[];  // Allowed npm packages
+  allowFs?: boolean;             // Enable fs access (default: true)
+  workingDirectory?: string;     // Working dir for fs operations
+}
+```
+
+### LogLevel
+
+```typescript
+enum LogLevel {
+  OFF = 0,    // No output
+  ERROR = 1,  // Errors only
+  INFO = 2,   // Normal output (default)
+  DEBUG = 3,  // Detailed debugging
+}
 ```
 
-## Architectural Differences from Python smolagents
+## Session Logging
+
+All sessions are logged to `~/.smol-js/`:
+- `session-<timestamp>.log` - Full session transcript
+- `packages/` - Cached npm packages
+
+## Comparison with Python smolagents
 
 | Feature | Python smolagents | smol-js |
 |---------|------------------|---------|
 | Code execution | Python interpreter | Node.js vm module |
 | Imports | `import` statement | `await importPackage()` |
 | Tool definition | `@tool` decorator | Class extending `Tool` |
+| Nested agents | `ManagedAgent` | `AgentTool` |
 | Async support | Optional | All tools are async |
+| HTTP requests | Requires tool | Built-in `fetch()` |
 | Remote executors | E2B, Docker, etc. | Local only (for now) |
-| Agent types | CodeAgent, ToolCallingAgent | CodeAgent only (for now) |
+| Agent types | CodeAgent, ToolCallingAgent | CodeAgent only |
+| Multi-agent | Yes | Yes (via AgentTool) |
 
 ## Security Considerations
 
-- Code executes in a sandboxed vm context
-- Only authorized npm packages can be imported
-- File system access is restricted to working directory
-- Configurable execution delay allows user interruption
+- **Sandboxed Execution**: Code runs in Node's vm module, isolated from the main process
+- **Authorized Imports**: Only explicitly allowed npm packages can be imported
+- **File System Isolation**: fs operations are restricted to the configured working directory
+- **Execution Delay**: Configurable delay before code execution allows user interruption (Ctrl+C)
+- **Timeout Protection**: Code execution has a configurable timeout (default: 30s)
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or PR.
+Contributions are welcome! Please open an issue or PR on GitHub.
+
+```bash
+# Clone and install
+git clone https://github.com/samrahimi/smol-js
+cd smol-js
+npm install
+
+# Run tests
+npm test
+
+# Run examples
+npx tsx examples/01-simple-math.ts
+```
 
 ## License
 

package/dist/index.js

@@ -228,7 +228,7 @@ var import_chalk = __toESM(require("chalk"));
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 var os = __toESM(require("os"));
-var LOG_DIR = path.join(os.homedir(), ".smol-js");
+var LOG_DIR = path.join(os.homedir(), ".smol-js/logs");
 var AgentLogger = class {
   level;
   logFile;
@@ -1342,7 +1342,7 @@ Thought: [Your reasoning about what to do]
 
 1. **Always use final_answer()**: When you have the complete answer, call \`final_answer(yourResult)\` to return it.
 
-2. **One action per step**: Execute one logical action per code block. Don't try to do everything at once.
+2. **One action per step**: Execute one logical action per code block and one code block per inference step. You will be given additional steps to complete your work if it cannot be done safely in one step. Don't try to do everything at once because you need to make sure that your tools returned valid, useful data before going on to make use of that data. In particular, if you are a Manager agent who is invoking Sub-Agents as tools, do not script the entire workflow in one step, make sure that you get to review the work of your subagents at critical points before going on to the next step.
 
 3. **Handle errors gracefully**: If something fails, explain what went wrong and try a different approach.
 
@@ -1356,6 +1356,8 @@ Thought: [Your reasoning about what to do]
 
 8. **No require()**: Use \`await importPackage('name')\` for npm packages instead of require().
 
+9. **Internet Access**: You can use fetch() to get data from the web as needed. However, if you have access to specialized tools for browsing / searching / retrieving information, use those first and fall back to fetch if they don't work
+
 ## Examples
 
 ### Example 1: Simple calculation
@@ -1651,8 +1653,8 @@ var import_openai = __toESM(require("openai"));
 var DEFAULT_CONFIG = {
   modelId: "anthropic/claude-sonnet-4.5",
   baseUrl: "https://openrouter.ai/api/v1",
-  maxTokens: 4096,
-  temperature: 0.7,
+  maxTokens: 65e3,
+  temperature: 1,
   timeout: 12e4
 };
 var OpenAIModel = class extends Model {