goatchain 0.0.18 → 0.0.20

package/README.md

@@ -70,7 +70,7 @@ Session is the core component for managing conversations. It handles message his
 const session = await agent.createSession()
 
 // Create session with custom ID
-const session = await agent.createSession({ id: 'my-session-id' })
+const session = await agent.createSession({ sessionId: 'my-session-id' })
 
 // Create session with configuration overrides
 const session = await agent.createSession({
@@ -86,8 +86,10 @@ const session = await agent.createSession({
 
 ```typescript
 interface CreateSessionOptions {
-  id?: string // Custom session ID
-  maxIterations?: number // Max agent loop iterations (default: 5)
+  sessionId?: string // Custom session ID
+  model?: ModelRef // Optional model override
+  maxIterations?: number // Max agent loop iterations (default: 1000)
+  cwd?: string // Working directory for file operations
   requestParams?: {
     temperature?: number // Model temperature
     maxTokens?: number // Max output tokens
@@ -96,6 +98,33 @@ interface CreateSessionOptions {
 }
 ```
 
+### Working Directory (CWD) Configuration
+
+You can set a working directory for the session, which will be automatically applied to all file operation tools (Read, Write, Edit, Glob, Grep, Bash, AstGrepSearch, AstGrepReplace):
+
+```typescript
+// Set CWD when creating a session
+const session = await agent.createSession({
+  cwd: '/path/to/project',
+})
+
+// Get the current working directory
+const cwd = session.getCwd()
+console.log('Current directory:', cwd)
+
+// Change the working directory at runtime
+session.setCwd('/path/to/another/project')
+
+// All file operations now use the new directory
+session.send('Read the README.md file')
+```
+
+**Benefits:**
+- Automatically sets the working directory for all tools that support it
+- Persisted across session saves and restores
+- Can be changed at runtime with `session.setCwd()`
+- Simplifies file path management in multi-project environments
+
 ### Sending Messages
 
 ```typescript
@@ -108,6 +137,40 @@ session.send('First question')
 session.send('Follow-up question')
 ```
 
+#### Send Options
+
+You can pass options to `send()` to control tool execution, approval, and more:
+
+```typescript
+// Auto-approve all tools for this request
+session.send('Create files and search the web', {
+  toolContext: {
+    approval: {
+      autoApprove: true, // Skip approval for all tools
+    },
+  },
+})
+
+// Require approval only for high-risk tools
+session.send('Analyze the codebase', {
+  toolContext: {
+    approval: {
+      strategy: 'high_risk', // Only prompt for high/critical risk tools
+    },
+  },
+})
+
+// Combine with session-level CWD
+session.setCwd('/path/to/project')
+session.send('Read and analyze all TypeScript files', {
+  toolContext: {
+    approval: { autoApprove: true },
+  },
+})
+// Tools will use /path/to/project as working directory
+// and execute without requiring approval
+```
+
 ### Receiving Events
 
 The `receive()` method returns an async generator that streams events:
@@ -187,7 +250,7 @@ console.log(session.updatedAt) // Last update timestamp
 
 ### Session Persistence
 
-Sessions can be saved and restored:
+Sessions can be saved and restored. All session state including message history, configuration, and working directory (cwd) are preserved:
 
 ```typescript
 // Save session to snapshot
@@ -200,6 +263,12 @@ session.restoreFromSnapshot(snapshot)
 // Or create a new session from snapshot
 const restored = await agent.createSession()
 restored.restoreFromSnapshot(snapshot)
+
+// The restored session maintains all state including:
+// - Message history
+// - Configuration overrides
+// - Working directory (cwd)
+// - Usage statistics
 ```
 
 ### Multi-turn Conversations
@@ -248,7 +317,7 @@ const agent = new Agent({
 })
 
 // Start session (automatically checkpointed)
-const session = await agent.createSession({ id: 'session-123' })
+const session = await agent.createSession({ sessionId: 'session-123' })
 session.send('Start a long task')
 for await (const event of session.receive()) {
   // Process events...
@@ -376,6 +445,36 @@ const agent = new Agent({
 })
 ```
 
+### MCP Servers (HTTP + stdio)
+
+GoatChain can connect MCP servers and register their remote tools automatically:
+
+```typescript
+const agent = new Agent({
+  name: 'MCP Assistant',
+  systemPrompt: 'You are helpful.',
+  model,
+  mcpServers: [
+    {
+      id: 'weather',
+      name: 'Weather API',
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      auth: { type: 'bearer', token: process.env.WEATHER_API_KEY! },
+    },
+    {
+      id: 'local-tools',
+      name: 'Local Tools',
+      transport: 'stdio',
+      command: 'node',
+      args: ['./mcp-servers/tools.js'],
+    },
+  ],
+})
+```
+
+See `docs/mcp.md` for details.
+
 ### Configuring File Tool Working Directory
 
 File-related tools (`ReadTool`, `WriteTool`, `EditTool`, `GlobTool`, `GrepTool`, `BashTool`) support configuring the working directory:
@@ -397,24 +496,29 @@ 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
-}))
+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' }` |
+| 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
@@ -480,6 +584,324 @@ const allTools = registry.list()
 const openaiTools = registry.toOpenAIFormat()
 ```
 
+## 🎣 Tool Approval & Hooks
+
+Sessions support lifecycle hooks that let you intercept tool calls for approval, logging, or custom logic.
+
+### Key Concepts
+
+GoatChain has two separate mechanisms for controlling tool execution:
+
+1. **preToolUse Hook** - For programmatic auto-approval/blocking
+   - `allow: true` → Tool executes immediately, **skips approval flow**
+   - `allow: false` → Tool is blocked
+   - Use this for automated scenarios where you want to programmatically approve/deny tools
+
+2. **Approval System** (via `toolContext.approval`) - For interactive user approval
+   - Pauses execution on high-risk tools
+   - Shows `requires_action` event
+   - Resumes with user's approval decisions
+   - Use this for interactive UIs where users manually approve tools
+
+**These are independent**: If you use `preToolUse` with `allow: true`, the approval system is bypassed entirely.
+
+### Hook Types
+
+```typescript
+interface ToolHooks {
+  // Called before tool execution
+  // - If allow: true, tool executes immediately and skips approval flow
+  // - If allow: false, tool is blocked
+  // - Can modify tool call with modifiedToolCall
+  preToolUse?: (ctx: HookContext) => Promise<PreToolUseResult>
+  
+  // Called after successful tool execution
+  postToolUse?: (ctx: HookContext, result: unknown) => Promise<void>
+  
+  // Called after tool execution failure
+  postToolUseFailure?: (ctx: HookContext, error: Error) => Promise<void>
+}
+
+interface HookContext {
+  sessionId: string
+  toolCall: {
+    id: string
+    type: 'function'
+    function: {
+      name: string
+      arguments: string
+    }
+  }
+  toolContext: ToolExecutionContext
+}
+
+interface PreToolUseResult {
+  // If true, allows tool to execute and skips approval flow
+  // If false, blocks tool execution immediately
+  allow: boolean
+  // Optional: Modify the tool call before execution
+  modifiedToolCall?: ToolCall
+}
+```
+
+### Basic Hook Usage
+
+```typescript
+import { Agent, ToolRegistry, ReadTool, WriteTool } from 'goatchain'
+
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are helpful.',
+  model,
+  tools: new ToolRegistry()
+    .register(new ReadTool())
+    .register(new WriteTool()),
+})
+
+// Create session with hooks
+const session = await agent.createSession({
+  hooks: {
+    preToolUse: async (ctx) => {
+      const toolName = ctx.toolCall.function.name
+      console.log(`Tool requested: ${toolName}`)
+      
+      // Returning { allow: true } skips approval flow and executes tool immediately
+      // Returning { allow: false } blocks tool execution
+      return { allow: true }
+    },
+    
+    postToolUse: async (ctx, result) => {
+      console.log(`Tool ${ctx.toolCall.function.name} completed successfully`)
+    },
+    
+    postToolUseFailure: async (ctx, error) => {
+      console.error(`Tool ${ctx.toolCall.function.name} failed:`, error)
+    },
+  },
+})
+```
+
+### Auto-Approval with preToolUse Hook
+
+The `preToolUse` hook is powerful because `allow: true` **bypasses the approval flow entirely**, even for high-risk tools. This is useful for automated scenarios:
+
+```typescript
+import type { RiskLevel } from 'goatchain'
+
+// Define auto-approval policy
+function shouldAutoApprove(toolName: string, riskLevel: RiskLevel): boolean {
+  // Auto-approve safe and low risk tools
+  if (riskLevel === 'safe' || riskLevel === 'low') {
+    return true
+  }
+  
+  // Block critical tools
+  if (riskLevel === 'critical') {
+    return false
+  }
+  
+  // For medium/high risk, you can implement custom logic
+  // e.g., check environment, user permissions, etc.
+  return process.env.AUTO_APPROVE_ALL === 'true'
+}
+
+const session = await agent.createSession({
+  hooks: {
+    preToolUse: async (ctx) => {
+      const tool = agent.tools.get(ctx.toolCall.function.name)
+      const riskLevel = tool?.riskLevel ?? 'safe'
+      const allow = shouldAutoApprove(ctx.toolCall.function.name, riskLevel)
+      
+      if (allow) {
+        console.log(`✓ Auto-approved: ${ctx.toolCall.function.name}`)
+      } else {
+        console.log(`✗ Blocked: ${ctx.toolCall.function.name}`)
+      }
+      
+      return { allow }
+    },
+  },
+})
+```
+
+### Auto-Approve All Tools with toolContext
+
+The simplest way to bypass approval for a specific request is using `toolContext.approval.autoApprove`:
+
+```typescript
+// Auto-approve all tools for this specific send() call
+session.send('Create a file and search the web', {
+  toolContext: {
+    approval: {
+      autoApprove: true, // Bypasses approval for ALL tools in this request
+    },
+  },
+})
+
+for await (const event of session.receive()) {
+  // All tools execute without requiring approval
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+**Use cases:**
+- **Automated workflows**: Scripts that run without user interaction
+- **Testing**: E2E tests that need tools to execute automatically
+- **Trusted environments**: When you trust the agent's tool usage completely
+
+**Approval strategies:**
+
+```typescript
+session.send('Your task', {
+  toolContext: {
+    approval: {
+      autoApprove: true, // Approve all tools automatically
+      // OR
+      strategy: 'high_risk', // Only require approval for high/critical risk tools
+      // OR
+      strategy: 'all', // Require approval for every tool call
+    },
+  },
+})
+```
+
+### Interactive Approval with Pause/Resume
+
+**Important**: The `preToolUse` hook with `allow: true` **skips approval**. For interactive approval flows where you want to pause and ask the user, use `toolContext.approval` instead:
+
+```typescript
+import type { AgentLoopCheckpoint } from 'goatchain'
+
+// Step 1: Start session WITHOUT preToolUse hook (to use approval system)
+const session = await agent.createSession()
+
+let checkpoint: AgentLoopCheckpoint | undefined
+
+session.send('Create a file and delete it', {
+  toolContext: {
+    approval: { strategy: 'high_risk' }, // Pause on high-risk tools for user approval
+  },
+})
+
+// Collect checkpoint when requires_action event is emitted
+for await (const event of session.receive()) {
+  if (event.type === 'requires_action') {
+    // Save checkpoint
+    checkpoint = event.checkpoint || 
+      await agent.stateStore?.loadCheckpoint(event.checkpointRef?.sessionId)
+    break // Pause here
+  }
+}
+
+// Step 2: Resume with approval decisions
+if (checkpoint) {
+  // Build approval decisions for pending tools
+  const decisions = Object.fromEntries(
+    checkpoint.pendingToolCalls.map((pending) => {
+      const toolName = pending.toolCall.function.name
+      const approved = confirm(`Approve ${toolName}?`)
+      
+      return [
+        pending.toolCall.id,
+        { approved, reason: approved ? undefined : 'User denied' },
+      ]
+    })
+  )
+
+  // Resume session with decisions
+  for await (const event of session.receive({
+    toolContext: {
+      approval: { decisions },
+    },
+  })) {
+    // Process events...
+  }
+}
+```
+
+### Complete Example: Interactive Approval System
+
+See `examples/tool-approval-session.ts` for a full example demonstrating:
+
+- **Sync approval** - Real-time approval during tool execution
+- **Async approval** - Pause/resume pattern for user interaction
+- **Blocked tools** - Denying high-risk tools automatically
+- **Risk-based policies** - Different approval rules per risk level
+
+```bash
+# Run the example
+bun run examples/tool-approval-session.ts
+```
+
+**Key features shown:**
+- Creating custom tools with risk levels
+- Implementing approval hooks with async delays
+- Pausing execution on `requires_action` events
+- Resuming sessions with approval decisions
+- Pretty-printed logging with colors and symbols
+
+### Modifying Tool Calls with preToolUse
+
+The `preToolUse` hook can also modify tool calls before execution:
+
+```typescript
+const session = await agent.createSession({
+  hooks: {
+    preToolUse: async (ctx) => {
+      const toolName = ctx.toolCall.function.name
+      
+      // Example: Add safety constraints to file writes
+      if (toolName === 'Write') {
+        const args = JSON.parse(ctx.toolCall.function.arguments)
+        
+        // Modify the tool call to add restrictions
+        const modifiedToolCall = {
+          ...ctx.toolCall,
+          function: {
+            ...ctx.toolCall.function,
+            arguments: JSON.stringify({
+              ...args,
+              // Force files to be written in a safe directory
+              file_path: `/safe-dir/${args.file_path}`,
+            }),
+          },
+        }
+        
+        return {
+          allow: true,
+          modifiedToolCall,
+        }
+      }
+      
+      return { allow: true }
+    },
+  },
+})
+```
+
+### Tool Context
+
+The `toolContext` parameter in `send()` and `receive()` allows passing additional context:
+
+```typescript
+session.send('Do something risky', {
+  toolContext: {
+    approval: {
+      strategy: 'high_risk', // Pause on high-risk tools
+      // or
+      decisions: {
+        'tool_call_id_123': { approved: true },
+        'tool_call_id_456': { approved: false, reason: 'Too dangerous' },
+      },
+    },
+    // Your custom context
+    custom: { userId: '123', environment: 'production' },
+  },
+})
+```
+
 ## 🧅 Middleware System
 
 GoatChain uses a Koa-style onion model for middleware. Each middleware wraps around the core execution:
@@ -922,7 +1344,7 @@ try {
   session = await agent.resumeSession(sessionId)
   console.log('Resumed existing session')
 } catch {
-  session = await agent.createSession({ id: sessionId })
+  session = await agent.createSession({ sessionId })
   console.log('Created new session')
 }
 
@@ -1024,7 +1446,74 @@ console.log(`Total messages: ${session.messages.length}`)
 console.log(`Total tokens: ${session.usage.totalTokens}`)
 ```
 
-### Example 6: File Operations with Directory Configuration
+### Example 6: Working Directory with Auto-Approval
+
+Combine session-level working directory with auto-approval for automated file operations:
+
+```typescript
+import { Agent, createModel, createOpenAIAdapter, createBuiltinTools } from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const agent = new Agent({
+  name: 'File Agent',
+  systemPrompt: 'You are a file management assistant.',
+  model,
+  tools: createBuiltinTools(), // All file tools included
+})
+
+// Set working directory at session creation
+const session = await agent.createSession({
+  cwd: '/path/to/project',
+})
+
+// Auto-approve all file operations for automated workflow
+session.send('List all TypeScript files, then create a summary.md file', {
+  toolContext: {
+    approval: {
+      autoApprove: true, // No approval prompts - fully automated
+    },
+  },
+})
+
+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(`\nExecuting: ${event.toolName}`)
+  }
+}
+
+// Change directory and continue with auto-approval
+session.setCwd('/path/to/another/project')
+session.send('Analyze the project structure and create a report', {
+  toolContext: {
+    approval: { autoApprove: true },
+  },
+})
+
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+**Perfect for:**
+- CI/CD pipelines that need file analysis
+- Automated code review bots
+- Project documentation generators
+- Bulk file operations without manual intervention
+
+### Example 7: Tool-level Working Directory (Advanced)
+
+For more control, you can configure individual tools with specific directories and restrictions:
 
 ```typescript
 import path from 'node:path'
@@ -1051,14 +1540,18 @@ 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 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 }))
 
@@ -1072,7 +1565,7 @@ You can create, read, and modify files within this sandbox.`,
 })
 
 const session = await agent.createSession()
-session.send('Create a report.md file with a summary of today\'s tasks')
+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') {
@@ -1224,8 +1717,22 @@ const snapshot = session.toSnapshot()
 
 Restore session from snapshot.
 
+**`getCwd(): string | undefined`**
+
+Get the current working directory for this session.
+
 ```typescript
-session.restoreFromSnapshot(snapshot)
+const cwd = session.getCwd()
+console.log('Working directory:', cwd)
+```
+
+**`setCwd(cwd: string): void`**
+
+Set the current working directory for this session. This automatically syncs the new directory to all tools that support it.
+
+```typescript
+session.setCwd('/path/to/project')
+// All file operation tools now use this directory
 ```
 
 #### Properties

package/dist/agent/agent.d.ts

@@ -1,10 +1,11 @@
 import type { ModelClient, ModelRef } from '../model';
 import type { BaseSessionManager } from '../session';
 import type { StateStore } from '../state';
-import type { ToolRegistry } from '../tool';
 import type { Middleware, NamedMiddleware } from './middleware';
 import type { AgentLoopState, AgentOptions, CreateSessionOptions, SessionHandleOptions } from './types';
+import { McpServerManager } from '../mcp-client';
 import { Session } from '../session';
+import { ToolRegistry } from '../tool';
 /**
  * Agent class - the main orchestrator.
  *
@@ -29,12 +30,15 @@ export declare class Agent {
     private _enableLogging;
     private _initializationPromise;
     private _initialized;
+    private _mcpManager?;
     constructor(options: AgentOptions);
     /**
      * Initialize middleware asynchronously (internal helper for constructor)
      * @private
      */
     private _initializeMiddleware;
+    private _initializeMcpServers;
+    private _initializeAll;
     /**
      * Ensure agent is initialized (all middleware registered)
      * @private
@@ -64,6 +68,10 @@ export declare class Agent {
      * Get the tool registry
      */
     get tools(): ToolRegistry | undefined;
+    /**
+     * Get MCP server manager, if configured.
+     */
+    get mcpManager(): McpServerManager | undefined;
     /**
      * Get the state store
      */