goatchain 0.0.16 → 0.0.18

package/README.md

@@ -74,9 +74,10 @@ const session = await agent.createSession({ id: 'my-session-id' })
 
 // Create session with configuration overrides
 const session = await agent.createSession({
-  configOverride: {
-    maxIterations: 10,
-    maxConcurrentToolCalls: 3,
+  maxIterations: 10,
+  requestParams: {
+    temperature: 0.7,
+    maxTokens: 2000,
   },
 })
 ```
@@ -84,12 +85,14 @@ const session = await agent.createSession({
 ### Session Configuration Options
 
 ```typescript
-interface SessionConfigOverride {
+interface CreateSessionOptions {
+  id?: string // Custom session ID
   maxIterations?: number // Max agent loop iterations (default: 5)
-  maxConcurrentToolCalls?: number // Max parallel tool calls (default: 5)
-  temperature?: number // Model temperature
-  maxTokens?: number // Max output tokens
-  topP?: number // Nucleus sampling parameter
+  requestParams?: {
+    temperature?: number // Model temperature
+    maxTokens?: number // Max output tokens
+    topP?: number // Nucleus sampling parameter
+  }
 }
 ```
 
@@ -103,12 +106,6 @@ session.send('What is the weather today?')
 session.send('First question')
 // Wait for response...
 session.send('Follow-up question')
-
-// Message with options
-session.send('Analyze this data', {
-  temperature: 0.7,
-  maxTokens: 2000,
-})
 ```
 
 ### Receiving Events
@@ -291,7 +288,7 @@ const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are a helpful assistant.',
   model,
-  tools: [], // Optional: custom tools
+  tools, // Optional: ToolRegistry instance
   stateStore, // Optional: for persistence
   maxIterations: 5, // Optional: max loop iterations
   maxConcurrentToolCalls: 5, // Optional: parallel tool calls
@@ -305,7 +302,7 @@ interface AgentOptions {
   name: string // Agent name
   systemPrompt: string // System instructions
   model: ModelClient | ModelRef // LLM client or reference
-  tools?: BaseTool[] // Custom tools
+  tools?: ToolRegistry // Tool registry (not an array)
   stateStore?: StateStore // Persistence layer
   maxIterations?: number // Max agent loop iterations (default: 5)
   maxConcurrentToolCalls?: number // Max parallel tool calls (default: 5)
@@ -348,6 +345,8 @@ GoatChain includes 23 built-in tools:
 
 ```typescript
 import {
+  Agent,
+  ToolRegistry,
   ReadTool,
   WriteTool,
   EditTool,
@@ -358,27 +357,72 @@ import {
   WebFetchTool,
 } from 'goatchain'
 
+// Create a tool registry and register tools
+const tools = new ToolRegistry()
+tools.register(new ReadTool())
+tools.register(new WriteTool())
+tools.register(new EditTool())
+tools.register(new BashTool())
+tools.register(new GrepTool())
+tools.register(new GlobTool())
+tools.register(new WebSearchTool({ apiKey: process.env.SERPER_API_KEY }))
+tools.register(new WebFetchTool())
+
 const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
-  tools: [
-    new ReadTool(),
-    new WriteTool(),
-    new EditTool(),
-    new BashTool(),
-    new GrepTool(),
-    new GlobTool(),
-    new WebSearchTool({ apiKey: process.env.SERPER_API_KEY }),
-    new WebFetchTool(),
-  ],
+  tools,
 })
 ```
 
+### Configuring File Tool Working Directory
+
+File-related tools (`ReadTool`, `WriteTool`, `EditTool`, `GlobTool`, `GrepTool`, `BashTool`) support configuring the working directory:
+
+```typescript
+import path from 'node:path'
+
+// Define output directory
+const OUTPUT_DIR = path.resolve(import.meta.dirname, 'output')
+
+// Option 1: Set working directory only
+const tools = new ToolRegistry()
+tools.register(new ReadTool({ cwd: OUTPUT_DIR }))
+tools.register(new WriteTool({ cwd: OUTPUT_DIR }))
+tools.register(new GlobTool({ cwd: OUTPUT_DIR }))
+tools.register(new GrepTool({ cwd: OUTPUT_DIR }))
+tools.register(new BashTool({ cwd: OUTPUT_DIR }))
+
+// Option 2: Restrict to specific directory (security sandbox)
+// This prevents access to files outside the allowed directory
+const tools = new ToolRegistry()
+tools.register(new ReadTool({ 
+  cwd: OUTPUT_DIR, 
+  allowedDirectory: OUTPUT_DIR  // Only allow reads within OUTPUT_DIR
+}))
+tools.register(new WriteTool({ 
+  cwd: OUTPUT_DIR, 
+  allowedDirectory: OUTPUT_DIR  // Only allow writes within OUTPUT_DIR
+}))
+```
+
+**Directory Configuration Options:**
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `cwd` | Working directory for resolving relative paths | `{ cwd: '/app/output' }` |
+| `allowedDirectory` | Restrict file access to this directory only (blocks path traversal) | `{ allowedDirectory: '/app/output' }` |
+
+**When to use `allowedDirectory`:**
+- When you want to sandbox the agent to a specific directory
+- To prevent accidental access to sensitive files
+- For production environments with security requirements
+
 ### Creating Custom Tools
 
 ```typescript
-import { BaseTool } from 'goatchain'
+import { BaseTool, ToolRegistry } from 'goatchain'
 
 class MyCustomTool extends BaseTool {
   name = 'my_tool'
@@ -402,11 +446,14 @@ class MyCustomTool extends BaseTool {
 }
 
 // Use it
+const tools = new ToolRegistry()
+tools.register(new MyCustomTool())
+
 const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
-  tools: [new MyCustomTool()],
+  tools,
 })
 ```
 
@@ -614,7 +661,7 @@ const model = createModel({
   adapter: createOpenAIAdapter({
     defaultModelId: 'gpt-4o',
     apiKey: process.env.OPENAI_API_KEY!,
-    baseURL: 'https://api.openai.com/v1', // Optional
+    baseUrl: 'https://api.openai.com/v1', // Optional
     organization: 'org-xxx', // Optional
   }),
 })
@@ -626,7 +673,7 @@ const model = createModel({
 interface OpenAIAdapterOptions {
   defaultModelId?: string // Default model ID
   apiKey?: string // OpenAI API key
-  baseURL?: string // Custom API endpoint
+  baseUrl?: string // Custom API endpoint (note: lowercase 'u')
   organization?: string // OpenAI organization ID
   defaultHeaders?: Record<string, string> // Custom headers
   timeout?: number // Request timeout (ms)
@@ -650,7 +697,7 @@ const deepseek = createModel({
   adapter: createOpenAIAdapter({
     defaultModelId: 'deepseek-chat',
     apiKey: process.env.DEEPSEEK_API_KEY!,
-    baseURL: 'https://api.deepseek.com/v1',
+    baseUrl: 'https://api.deepseek.com/v1',
   }),
 })
 ```
@@ -799,6 +846,7 @@ import {
   Agent,
   createModel,
   createOpenAIAdapter,
+  ToolRegistry,
   ReadTool,
   WriteTool,
   BashTool,
@@ -811,11 +859,16 @@ const model = createModel({
   }),
 })
 
+const tools = new ToolRegistry()
+tools.register(new ReadTool())
+tools.register(new WriteTool())
+tools.register(new BashTool())
+
 const agent = new Agent({
   name: 'File Assistant',
   systemPrompt: 'You help users manage their files.',
   model,
-  tools: [new ReadTool(), new WriteTool(), new BashTool()],
+  tools,
 })
 
 const session = await agent.createSession()
@@ -971,6 +1024,65 @@ console.log(`Total messages: ${session.messages.length}`)
 console.log(`Total tokens: ${session.usage.totalTokens}`)
 ```
 
+### Example 6: File Operations with Directory Configuration
+
+```typescript
+import path from 'node:path'
+import {
+  Agent,
+  createModel,
+  createOpenAIAdapter,
+  ToolRegistry,
+  ReadTool,
+  WriteTool,
+  GlobTool,
+  GrepTool,
+} from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+// Define output directory for agent's file operations
+const OUTPUT_DIR = path.resolve(process.cwd(), 'output')
+
+// Configure tools with working directory and restrictions
+const tools = new ToolRegistry()
+tools.register(new ReadTool({ 
+  cwd: OUTPUT_DIR, 
+  allowedDirectory: OUTPUT_DIR  // Sandbox: only allow reads in OUTPUT_DIR
+}))
+tools.register(new WriteTool({ 
+  cwd: OUTPUT_DIR, 
+  allowedDirectory: OUTPUT_DIR  // Sandbox: only allow writes in OUTPUT_DIR
+}))
+tools.register(new GlobTool({ cwd: OUTPUT_DIR }))
+tools.register(new GrepTool({ cwd: OUTPUT_DIR }))
+
+const agent = new Agent({
+  name: 'Sandboxed File Agent',
+  systemPrompt: `You are a file management assistant.
+All your file operations are restricted to the output directory.
+You can create, read, and modify files within this sandbox.`,
+  model,
+  tools,
+})
+
+const session = await agent.createSession()
+session.send('Create a report.md file with a summary of today\'s tasks')
+
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  } else if (event.type === 'tool_call_start') {
+    console.log(`\n[Tool] ${event.name}`)
+  }
+}
+```
+
 ## 📖 API Reference
 
 ### Agent Class
@@ -986,7 +1098,7 @@ new Agent(options: AgentOptions)
 - `name: string` - Agent name (required)
 - `systemPrompt: string` - System instructions (required)
 - `model: ModelClient | ModelRef` - LLM client (required)
-- `tools?: BaseTool[]` - Custom tools
+- `tools?: ToolRegistry` - Tool registry (not an array)
 - `stateStore?: StateStore` - Persistence layer
 - `maxIterations?: number` - Max loop iterations (default: 5)
 - `maxConcurrentToolCalls?: number` - Max parallel tools (default: 5)
@@ -1001,10 +1113,11 @@ Create a new session.
 ```typescript
 const session = await agent.createSession({
   id: 'custom-id', // Optional custom ID
-  configOverride: {
-    // Optional config overrides
-    maxIterations: 10,
+  maxIterations: 10, // Optional max iterations
+  requestParams: {
+    // Optional request parameters
     temperature: 0.7,
+    maxTokens: 2000,
   },
 })
 ```
@@ -1062,15 +1175,12 @@ agent.setModel({ type: 'ref', ref: 'the-model' })
 
 #### Methods
 
-**`send(input, options?): void`**
+**`send(input): void`**
 
 Send a message to the session.
 
 ```typescript
-session.send('Hello!', {
-  temperature: 0.8,
-  maxTokens: 1000,
-})
+session.send('Hello!')
 ```
 
 **`receive(options?): AsyncGenerator<AgentEvent>`**
@@ -1124,7 +1234,6 @@ session.restoreFromSnapshot(snapshot)
 - `status: SessionStatus` - Session status ('idle' | 'running' | 'completed' | 'error')
 - `messages: Message[]` - Message history
 - `usage: Usage` - Token usage statistics
-- `configOverride?: SessionConfigOverride` - Config overrides
 - `createdAt: number` - Creation timestamp
 - `updatedAt: number` - Last update timestamp