goatchain 0.0.14 → 0.0.16

package/README.md

@@ -3,7 +3,6 @@
 > A TypeScript SDK for building AI agents with streaming support, tool calling, and middleware pattern.
 
 [![npm version](https://badge.fury.io/js/goatchain.svg)](https://badge.fury.io/js/goatchain)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## 📦 Installation
 
@@ -86,11 +85,11 @@ const session = await agent.createSession({
 
 ```typescript
 interface SessionConfigOverride {
-  maxIterations?: number          // Max agent loop iterations (default: 5)
+  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
+  temperature?: number // Model temperature
+  maxTokens?: number // Max output tokens
+  topP?: number // Nucleus sampling parameter
 }
 ```
 
@@ -123,25 +122,25 @@ for await (const event of session.receive()) {
       // Partial text from LLM
       process.stdout.write(event.delta)
       break
-    
+
     case 'tool_call_start':
       console.log(`\nCalling tool: ${event.name}`)
       break
-    
+
     case 'tool_result':
       console.log(`Tool result: ${event.result}`)
       break
-    
+
     case 'iteration_end':
       console.log(`\nIteration ${event.iteration} complete`)
       console.log(`Tokens used: ${event.usage?.totalTokens}`)
       break
-    
+
     case 'done':
       console.log(`\nConversation done: ${event.stopReason}`)
       console.log(`Total tokens: ${event.usage?.totalTokens}`)
       break
-    
+
     case 'error':
       console.error(`Error: ${event.error}`)
       break
@@ -151,20 +150,20 @@ for await (const event of session.receive()) {
 
 ### Session Event Types
 
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `iteration_start` | Agent loop iteration begins | `iteration` |
-| `text_delta` | Partial text response | `delta` |
-| `thinking_start` | Reasoning phase begins | - |
-| `thinking_delta` | Reasoning content | `delta` |
-| `thinking_end` | Reasoning phase ends | - |
-| `tool_call_start` | Tool invocation begins | `name`, `id` |
-| `tool_call_delta` | Tool arguments stream | `delta` |
-| `tool_call_end` | Tool call complete | `name`, `args` |
-| `tool_result` | Tool execution result | `result`, `error` |
-| `iteration_end` | Iteration complete | `usage`, `iteration` |
-| `done` | Stream finished | `stopReason`, `usage` |
-| `error` | Error occurred | `error` |
+| Event Type        | Description                 | Key Fields            |
+| ----------------- | --------------------------- | --------------------- |
+| `iteration_start` | Agent loop iteration begins | `iteration`           |
+| `text_delta`      | Partial text response       | `delta`               |
+| `thinking_start`  | Reasoning phase begins      | -                     |
+| `thinking_delta`  | Reasoning content           | `delta`               |
+| `thinking_end`    | Reasoning phase ends        | -                     |
+| `tool_call_start` | Tool invocation begins      | `name`, `id`          |
+| `tool_call_delta` | Tool arguments stream       | `delta`               |
+| `tool_call_end`   | Tool call complete          | `name`, `args`        |
+| `tool_result`     | Tool execution result       | `result`, `error`     |
+| `iteration_end`   | Iteration complete          | `usage`, `iteration`  |
+| `done`            | Stream finished             | `stopReason`, `usage` |
+| `error`           | Error occurred              | `error`               |
 
 ### Session State Management
 
@@ -184,7 +183,7 @@ console.log(session.usage)
 // }
 
 // Session metadata
-console.log(session.id)        // Session ID
+console.log(session.id) // Session ID
 console.log(session.createdAt) // Creation timestamp
 console.log(session.updatedAt) // Last update timestamp
 ```
@@ -303,14 +302,14 @@ const agent = new Agent({
 
 ```typescript
 interface AgentOptions {
-  name: string                      // Agent name
-  systemPrompt: string              // System instructions
-  model: ModelClient | ModelRef     // LLM client or reference
-  tools?: BaseTool[]                // Custom tools
-  stateStore?: StateStore           // Persistence layer
-  maxIterations?: number            // Max agent loop iterations (default: 5)
-  maxConcurrentToolCalls?: number   // Max parallel tool calls (default: 5)
-  modelSwapWhitelist?: string[]     // Allowed model IDs for runtime switching
+  name: string // Agent name
+  systemPrompt: string // System instructions
+  model: ModelClient | ModelRef // LLM client or reference
+  tools?: BaseTool[] // Custom tools
+  stateStore?: StateStore // Persistence layer
+  maxIterations?: number // Max agent loop iterations (default: 5)
+  maxConcurrentToolCalls?: number // Max parallel tool calls (default: 5)
+  modelSwapWhitelist?: string[] // Allowed model IDs for runtime switching
 }
 ```
 
@@ -348,10 +347,10 @@ await sessionManager.destroy('session-id')
 GoatChain includes 23 built-in tools:
 
 ```typescript
-import { 
-  ReadTool, 
-  WriteTool, 
-  EditTool, 
+import {
+  ReadTool,
+  WriteTool,
+  EditTool,
   BashTool,
   GrepTool,
   GlobTool,
@@ -384,7 +383,7 @@ import { BaseTool } from 'goatchain'
 class MyCustomTool extends BaseTool {
   name = 'my_tool'
   description = 'Does something useful'
-  
+
   parameters = {
     type: 'object',
     properties: {
@@ -395,7 +394,7 @@ class MyCustomTool extends BaseTool {
     },
     required: ['input'],
   }
-  
+
   async execute(args: { input: string }) {
     // Your tool logic here
     return `Processed: ${args.input}`
@@ -449,9 +448,9 @@ outer:before → inner:before → exec (model.stream) → inner:after → outer:
 agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
-  
+
   const nextState = await next(state) // Execute next middleware/model
-  
+
   console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
   return nextState
 }, 'logging')
@@ -480,10 +479,12 @@ import { createPlanModeMiddleware } from 'goatchain'
 agent.use(createPlanModeMiddleware())
 
 // With custom configuration
-agent.use(createPlanModeMiddleware({
-  name: 'my-plan', // Custom name
-  planPrompt: 'Create a detailed plan...', // Custom prompt
-}))
+agent.use(
+  createPlanModeMiddleware({
+    name: 'my-plan', // Custom name
+    planPrompt: 'Create a detailed plan...', // Custom prompt
+  }),
+)
 ```
 
 #### Context Compression Middleware
@@ -494,17 +495,19 @@ Automatically compresses context when token limit is reached using a two-stage s
 import { createContextCompressionMiddleware } from 'goatchain'
 
 // Automatically named 'context-compression'
-agent.use(createContextCompressionMiddleware({
-  maxTokens: 128000,
-  protectedTurns: 2,  // Keep last 2 conversation turns
-  model: model,
-  stateStore: agent.stateStore,
-  toolCompressionTarget: 0.45,  // Compress to 45% of maxTokens
-  minKeepToolResults: 5,  // Keep last 5 tool results
-  // Optional: Enable detailed logging
-  enableLogging: true,
-  logFilePath: 'compression-logs.jsonl',
-}))
+agent.use(
+  createContextCompressionMiddleware({
+    maxTokens: 128000,
+    protectedTurns: 2, // Keep last 2 conversation turns
+    model: model,
+    stateStore: agent.stateStore,
+    toolCompressionTarget: 0.45, // Compress to 45% of maxTokens
+    minKeepToolResults: 5, // Keep last 5 tool results
+    // Optional: Enable detailed logging
+    enableLogging: true,
+    logFilePath: 'compression-logs.jsonl',
+  }),
+)
 ```
 
 See [Context Compression Logging Guide](./docs/context-compression-logging.md) for details on monitoring compression behavior.
@@ -519,14 +522,14 @@ agent.use(async (state, next) => {
     messages: state.messages.length,
     pendingTools: state.pendingToolCalls.length,
   })
-  
+
   const result = await next(state)
-  
+
   console.log(`Completed iteration ${state.iteration}:`, {
     shouldContinue: result.shouldContinue,
     usage: result.usage,
   })
-  
+
   return result
 }, 'logger')
 ```
@@ -565,19 +568,19 @@ agent.use(async (state, next) => {
 ```typescript
 agent.use(async (state, next) => {
   let retries = 3
-  
+
   while (retries > 0) {
     try {
       return await next(state)
     } catch (error) {
       retries--
       if (retries === 0) throw error
-      
+
       console.log(`Retrying... (${retries} attempts left)`)
-      await new Promise(resolve => setTimeout(resolve, 1000))
+      await new Promise((resolve) => setTimeout(resolve, 1000))
     }
   }
-  
+
   return state
 }, 'retry')
 ```
@@ -588,15 +591,15 @@ The `AgentLoopState` object passed to middleware:
 
 ```typescript
 interface AgentLoopState {
-  sessionId: string                  // Current session ID
-  messages: Message[]                // Conversation history
-  iteration: number                  // Current iteration number
+  sessionId: string // Current session ID
+  messages: Message[] // Conversation history
+  iteration: number // Current iteration number
   pendingToolCalls: ToolCallWithResult[] // Pending tool executions
-  currentResponse: string            // Current LLM response
-  shouldContinue: boolean            // Whether to continue loop
-  stopReason?: string                // Reason for stopping
-  usage?: Usage                      // Token usage
-  error?: Error                      // Error if any
+  currentResponse: string // Current LLM response
+  shouldContinue: boolean // Whether to continue loop
+  stopReason?: string // Reason for stopping
+  usage?: Usage // Token usage
+  error?: Error // Error if any
 }
 ```
 
@@ -621,13 +624,13 @@ const model = createModel({
 
 ```typescript
 interface OpenAIAdapterOptions {
-  defaultModelId?: string      // Default model ID
-  apiKey?: string              // OpenAI API key
-  baseURL?: string             // Custom API endpoint
-  organization?: string        // OpenAI organization ID
+  defaultModelId?: string // Default model ID
+  apiKey?: string // OpenAI API key
+  baseURL?: string // Custom API endpoint
+  organization?: string // OpenAI organization ID
   defaultHeaders?: Record<string, string> // Custom headers
-  timeout?: number             // Request timeout (ms)
-  maxRetries?: number          // Max retry attempts (default: 2)
+  timeout?: number // Request timeout (ms)
+  maxRetries?: number // Max retry attempts (default: 2)
 }
 ```
 
@@ -659,10 +662,10 @@ Implement custom model adapters:
 ```typescript
 interface ModelClient {
   modelId: string
-  
+
   // Streaming API (required)
   stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>
-  
+
   // Non-streaming API (optional)
   run?(request: ModelRequest): Promise<ModelRunResult>
 }
@@ -687,8 +690,8 @@ Persist agent state to filesystem:
 import { FileStateStore } from 'goatchain'
 
 const stateStore = new FileStateStore({
-  dir: './checkpoints',           // Storage directory
-  deleteOnComplete: true,         // Auto-delete successful completions
+  dir: './checkpoints', // Storage directory
+  deleteOnComplete: true, // Auto-delete successful completions
 })
 
 const agent = new Agent({
@@ -718,7 +721,7 @@ Implement custom state stores:
 ```typescript
 interface StateStore {
   deleteOnComplete: boolean
-  
+
   saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>
   loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | null>
   deleteCheckpoint(sessionId: string): Promise<void>
@@ -792,9 +795,9 @@ for await (const event of session.receive()) {
 ### Example 2: Agent with Tools
 
 ```typescript
-import { 
-  Agent, 
-  createModel, 
+import {
+  Agent,
+  createModel,
   createOpenAIAdapter,
   ReadTool,
   WriteTool,
@@ -812,11 +815,7 @@ const agent = new Agent({
   name: 'File Assistant',
   systemPrompt: 'You help users manage their files.',
   model,
-  tools: [
-    new ReadTool(),
-    new WriteTool(),
-    new BashTool(),
-  ],
+  tools: [new ReadTool(), new WriteTool(), new BashTool()],
 })
 
 const session = await agent.createSession()
@@ -836,9 +835,9 @@ for await (const event of session.receive()) {
 ### Example 3: Persistent Sessions
 
 ```typescript
-import { 
-  Agent, 
-  createModel, 
+import {
+  Agent,
+  createModel,
   createOpenAIAdapter,
   FileStateStore,
 } from 'goatchain'
@@ -886,9 +885,9 @@ for await (const event of session.receive()) {
 ### Example 4: Session with Middleware
 
 ```typescript
-import { 
-  Agent, 
-  createModel, 
+import {
+  Agent,
+  createModel,
   createOpenAIAdapter,
   createPlanModeMiddleware,
 } from 'goatchain'
@@ -950,15 +949,15 @@ const session = await agent.createSession()
 async function chat(message: string) {
   console.log(`\nUser: ${message}`)
   console.log('Assistant: ')
-  
+
   session.send(message)
-  
+
   for await (const event of session.receive()) {
     if (event.type === 'text_delta') {
       process.stdout.write(event.delta)
     }
   }
-  
+
   console.log('\n')
 }
 
@@ -983,6 +982,7 @@ new Agent(options: AgentOptions)
 ```
 
 **Options:**
+
 - `name: string` - Agent name (required)
 - `systemPrompt: string` - System instructions (required)
 - `model: ModelClient | ModelRef` - LLM client (required)
@@ -1000,8 +1000,9 @@ Create a new session.
 
 ```typescript
 const session = await agent.createSession({
-  id: 'custom-id',           // Optional custom ID
-  configOverride: {          // Optional config overrides
+  id: 'custom-id', // Optional custom ID
+  configOverride: {
+    // Optional config overrides
     maxIterations: 10,
     temperature: 0.7,
   },
@@ -1133,7 +1134,7 @@ session.restoreFromSnapshot(snapshot)
 interface Message {
   role: 'system' | 'user' | 'assistant' | 'tool'
   content: string | ToolCall[] | ToolResult[]
-  name?: string       // For tool messages
+  name?: string // For tool messages
   toolCallId?: string // For tool messages
 }
 ```
@@ -1151,7 +1152,7 @@ interface Usage {
 ### AgentEvent Types
 
 ```typescript
-type AgentEvent = 
+type AgentEvent =
   | TextDeltaEvent
   | ToolCallStartEvent
   | ToolCallDeltaEvent
@@ -1278,6 +1279,7 @@ dim
 ```
 
 **Features:**
+
 - Interactive chat interface
 - Session management
 - Tool approval system
@@ -1314,11 +1316,3 @@ See [docs/acp-server.md](./docs/acp-server.md) for details.
 - [CLI Documentation](./docs/cli.md) - Terminal UI features and usage
 - [ACP Server Guide](./docs/acp-server.md) - Editor integration setup
 - [Examples](./examples/) - Sample implementations
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
-
-## 📄 License
-
-MIT © [Simon He](https://github.com/Simon-He95)

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { FileStateStore, InMemoryStateStore, StateKeys, StateStore, } from './st
 export type { CompressionState, FileStateStoreOptions, StateKey, StateStoreOptions, } from './state';
 export * from './subagent';
 export { BaseTool, errorContent, FilteredToolRegistry, imageContent, textContent, ToolRegistry } from './tool';
-export { AskUserTool, AstGrepReplaceTool, AstGrepSearchTool, BashTool, EditTool, GlobTool, GrepTool, ReadTool, TodoPlanTool, TodoWriteTool, WebSearchTool, WriteTool, } from './tool';
+export { AskUserTool, AstGrepReplaceTool, AstGrepSearchTool, BashTool, EditTool, GlobTool, GrepTool, ReadTool, TodoPlanTool, TodoWriteTool, WebFetchTool, WebSearchTool, WriteTool, } from './tool';
 export type { BashArgs, BashResult, RiskLevel, ToolApprovalResult, ToolApprovalSettings, ToolApprovalStrategy, ToolExecutionContext, ToolExecutionContextInput, ToolRunUsage, } from './tool';
-export type { AskUserArgs, AskUserResult, AstGrepMatch, AstGrepReplaceArgs, AstGrepReplaceResult, AstGrepSearchArgs, AstGrepSearchResult, EditArgs, EditResult, GlobArgs, GlobResult, GrepArgs, GrepOutputMode, GrepResult, Question, QuestionOption, ReadArgs, ReadResult, TodoItem, TodoPlanArgs, TodoPlanResult, TodoStatus, TodoWriteArgs, TodoWriteResult, WebSearchArgs, WebSearchResult, WriteArgs, WriteResult, } from './tool';
+export type { AskUserArgs, AskUserResult, AstGrepMatch, AstGrepReplaceArgs, AstGrepReplaceResult, AstGrepSearchArgs, AstGrepSearchResult, EditArgs, EditResult, FetchFormat, GlobArgs, GlobResult, GrepArgs, GrepOutputMode, GrepResult, Question, QuestionOption, ReadArgs, ReadResult, TodoItem, TodoPlanArgs, TodoPlanResult, TodoStatus, TodoWriteArgs, TodoWriteResult, WebFetchArgs, WebFetchResult, WebSearchArgs, WebSearchResult, WriteArgs, WriteResult, } from './tool';
 export type { AgentEvent, AgentEventType, AgentLoopCheckpoint, AssistantMessage, BaseEvent, CallToolResult, ContentBlock, DoneEvent, ImageContent, IterationEndEvent, IterationStartEvent, JSONSchemaProperty, Message, MessageContent, MessageRole, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';