goatchain 0.0.11 → 0.0.13

package/README.md

@@ -1,37 +1,37 @@
-# GoatChain 🐐
+# GoatChain SDK Developer Guide 🐐
 
-> A lightweight, extensible TypeScript SDK for building AI agents with streaming support, tool calling, and middleware pattern.
+> 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)
 
-[中文文档 (Chinese Documentation)](README.zh.md)
-
-## ✨ Features
-
-- **🔄 Agentic Loop** - Automatic tool calling loop with configurable max iterations
-- **📡 Streaming First** - Real-time streaming responses with detailed events
-- **🧅 Middleware Pattern** - Koa-style onion model for extensible hooks
-- **🔧 Tool System** - Easy-to-use tool registration and execution
-- **💾 State Management** - Two-level state store (Agent + Session level)
-- **📸 Snapshot/Restore** - Full persistence support for agents and sessions
-- **🎯 TypeScript Native** - Full type safety with comprehensive type exports
-
 ## 📦 Installation
 
 ```bash
 pnpm add goatchain
+# or
+npm install goatchain
+# or
+bun add goatchain
 ```
 
+## 🎯 Core Concepts
+
+GoatChain SDK is built around three core components:
+
+- **Agent** - The main orchestrator that manages the agent loop, middleware, and tools
+- **Session** - A conversation context that handles message history and streaming
+- **ModelClient** - Abstraction layer for LLM providers (OpenAI, Anthropic, etc.)
+
 ## 🚀 Quick Start
 
-Simple Agent Loop example:
+### Basic Usage
 
 ```typescript
 import process from 'node:process'
 import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
 
-// Create model
+// 1. Create model client
 const model = createModel({
   adapter: createOpenAIAdapter({
     defaultModelId: 'gpt-4o',
@@ -39,16 +39,18 @@ const model = createModel({
   }),
 })
 
-// Create Agent
+// 2. Create agent
 const agent = new Agent({
   name: 'Simple Assistant',
   systemPrompt: 'You are a helpful assistant.',
   model,
 })
 
-// Stream responses
+// 3. Create session and interact
 const session = await agent.createSession()
 session.send('Hello!')
+
+// 4. Stream responses
 for await (const event of session.receive()) {
   if (event.type === 'text_delta') {
     process.stdout.write(event.delta)
@@ -58,182 +60,381 @@ for await (const event of session.receive()) {
 }
 ```
 
-📖 **Full Documentation**: See [docs/getting-started.md](./docs/getting-started.md) for more examples and complete guide.
+## 📡 Session Management
 
-## 🧰 CLI
+Session is the core component for managing conversations. It handles message history, state persistence, and event streaming.
 
-GoatChain CLI is a terminal UI (TUI) built on `@simon_he/vue-tui`.
+### Creating Sessions
 
-### Installation
+```typescript
+// Create a new session
+const session = await agent.createSession()
 
-**Global installation (recommended):**
+// Create session with custom ID
+const session = await agent.createSession({ id: 'my-session-id' })
 
-```bash
-npm install -g goatchain-cli@latest
+// Create session with configuration overrides
+const session = await agent.createSession({
+  configOverride: {
+    maxIterations: 10,
+    maxConcurrentToolCalls: 3,
+  },
+})
 ```
 
-**Or use npx without installation:**
+### Session Configuration Options
 
-```bash
-npx goatchain-cli@latest
+```typescript
+interface SessionConfigOverride {
+  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
+}
 ```
 
-### Usage
+### Sending Messages
 
-After installation, simply run:
-
-```bash
-goatchain
+```typescript
+// Simple text message
+session.send('What is the weather today?')
+
+// Multiple messages in sequence
+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,
+})
 ```
 
-Inside the TUI:
+### Receiving Events
 
-- `Ctrl+P` opens the command palette (Sessions / New Session / Settings / Tool Approvals; Chat also has Theme)
-- Slash commands in the input: `/settings`, `/approvals`, `/sessions`, `/new` (Chat also supports `/redo`)
+The `receive()` method returns an async generator that streams events:
 
-### Development
+```typescript
+for await (const event of session.receive()) {
+  switch (event.type) {
+    case 'text_delta':
+      // 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
+  }
+}
+```
 
-Run it from this repo:
+### 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` |
+
+### Session State Management
 
-```bash
-bun run cli
+```typescript
+// Access message history
+console.log(session.messages) // Message[]
+
+// Check session status
+console.log(session.status) // 'idle' | 'running' | 'completed' | 'error'
+
+// Get token usage
+console.log(session.usage)
+// {
+//   promptTokens: 150,
+//   completionTokens: 80,
+//   totalTokens: 230
+// }
+
+// Session metadata
+console.log(session.id)        // Session ID
+console.log(session.createdAt) // Creation timestamp
+console.log(session.updatedAt) // Last update timestamp
 ```
 
-See `docs/cli.md` for the full feature list and flowcharts.
+### Session Persistence
 
-## 🔌 ACP Server
+Sessions can be saved and restored:
 
-GoatChain can be exposed as an ACP (Agent Client Protocol) server for integration with editors like Zed.
+```typescript
+// Save session to snapshot
+const snapshot = session.toSnapshot()
+// Store snapshot to database, file, etc.
 
-```bash
-bun run acp-server
+// Restore session from snapshot
+session.restoreFromSnapshot(snapshot)
+
+// Or create a new session from snapshot
+const restored = await agent.createSession()
+restored.restoreFromSnapshot(snapshot)
 ```
 
-**Configuration for Zed** (`settings.json`):
+### Multi-turn Conversations
 
-```json
-{
-  "agent_servers": {
-    "goatchain": {
-      "command": "pnpm",
-      "args": ["--dir", "/path/to/GoatChain", "acp-server"]
-    }
+```typescript
+const session = await agent.createSession()
+
+// Turn 1
+session.send('What is 2 + 2?')
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+
+// Turn 2 (maintains context)
+session.send('What about multiplying that by 3?')
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
   }
 }
+
+// Session now contains full conversation history
+console.log(session.messages.length) // 4 (2 user, 2 assistant)
 ```
 
-**Features:**
-- File operations (read, write, edit)
-- Search tools (glob, grep, ast-grep)
-- Web search and task management
-- Same tool set as CLI agent mode
+### Resuming Sessions
 
-**Available servers:**
-- `pnpm acp-server` - Simple agent (recommended)
-- `pnpm acp-server:plan` - With plan mode (experimental)
+Resume interrupted sessions using checkpoints:
 
-📖 **Full Documentation**: See [docs/acp-server.md](./docs/acp-server.md) for configuration and troubleshooting.
+```typescript
+import { FileStateStore } from 'goatchain'
 
-## 🏗️ Architecture
+// Create agent with state store
+const stateStore = new FileStateStore({
+  dir: './checkpoints',
+  deleteOnComplete: true,
+})
 
-```mermaid
-classDiagram
-    direction TB
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are helpful.',
+  model,
+  stateStore,
+})
+
+// Start session (automatically checkpointed)
+const session = await agent.createSession({ id: 'session-123' })
+session.send('Start a long task')
+for await (const event of session.receive()) {
+  // Process events...
+}
 
-	    class Agent {
-	        +id: string
-	        +name: string
-	        +systemPrompt: string
-	        +model: ModelClient
-	        +tools: ToolRegistry
-	        +stateStore: StateStore
-	        +sessionManager: BaseSessionManager
-	        +stats: AgentStats
-	        +use(middleware): this
-	        +createSession(options): BaseSession
-	        +resumeSession(sessionId, options): BaseSession
-	        +setModel(modelOrRef): void
-	    }
-
-	    class ModelClient {
-	        <<interface>>
-	        +modelId: string
-	      +stream(request): AsyncIterable~ModelStreamEvent~
-	      +run?(request): Promise~ModelRunResult~
-	    }
+// Later, resume from checkpoint
+const resumed = await agent.resumeSession('session-123')
+for await (const event of resumed.receive()) {
+  // Continue from where it left off
+}
+```
 
-    class StateStore {
-        <<interface>>
-        +deleteOnComplete: boolean
-        +saveCheckpoint(checkpoint): Promise~void~
-        +loadCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
-        +deleteCheckpoint(sessionId): Promise~void~
-        +listCheckpoints(): Promise~AgentLoopCheckpoint[]~
-    }
+### Session Lifecycle Hooks
 
-    class BaseTool {
-        <<abstract>>
-        +name: string
-        +description: string
-        +parameters: JSONSchema
-      +execute(args, ctx?): Promise~unknown~
-    }
+```typescript
+// Add message manually
+session.addMessage({
+  role: 'user',
+  content: 'Custom message',
+})
 
-    class ToolRegistry {
-        +register(tool): void
-        +unregister(name): boolean
-        +get(name): BaseTool
-        +list(): BaseTool[]
-        +toOpenAIFormat(): OpenAITool[]
-    }
+// Save session state manually
+await session.save()
 
-    class BaseSession {
-        <<abstract>>
-        +id: string
-        +status: SessionStatus
-        +messages: Message[]
-        +usage: Usage
-        +configOverride: SessionConfigOverride
-        +addMessage(message): void
-        +save(): Promise~void~
-        +toSnapshot(): SessionSnapshot
-        +restoreFromSnapshot(snapshot): void
-    }
+// Clear session history
+session.messages = []
+```
 
-    class BaseSessionManager {
-        <<abstract>>
-        +create(sessionId?): Promise~BaseSession~
-        +get(sessionId): Promise~BaseSession~
-        +list(): Promise~BaseSession[]~
-        +destroy(sessionId): Promise~void~
-    }
+## 🤖 Agent Configuration
 
-    class Middleware {
-        <<function>>
-        (ctx: AgentLoopState, next: NextFunction) => Promise~void~
-    }
+### Creating an Agent
 
-    class AgentLoopState {
-        +sessionId: string
-        +messages: Message[]
-        +iteration: number
-        +pendingToolCalls: ToolCallWithResult[]
-        +currentResponse: string
-        +shouldContinue: boolean
-        +usage: Usage
-    }
+```typescript
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
 
-    Agent --> ModelClient : uses
-    Agent --> ToolRegistry : uses
-    Agent --> StateStore : uses
-    Agent --> BaseSessionManager : uses
-    Agent ..> Middleware : applies
-    Agent ..> AgentLoopState : manages
-    ToolRegistry --> BaseTool : contains
-    BaseSessionManager --> BaseSession : manages
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+  tools: [], // Optional: custom tools
+  stateStore, // Optional: for persistence
+  maxIterations: 5, // Optional: max loop iterations
+  maxConcurrentToolCalls: 5, // Optional: parallel tool calls
+})
+```
+
+### Agent Options
+
+```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
+}
+```
+
+### Runtime Model Switching
+
+```typescript
+// Pin to specific model
+agent.setModel('gpt-4o-mini')
+
+// Allow model to switch back
+agent.setModel({ type: 'ref', ref: 'the-model' })
+```
+
+### Session Manager
+
+Manage multiple sessions:
+
+```typescript
+const sessionManager = agent.sessionManager
+
+// List all sessions
+const sessions = await sessionManager.list()
+
+// Get specific session
+const session = await sessionManager.get('session-id')
+
+// Destroy session
+await sessionManager.destroy('session-id')
+```
+
+## 🔧 Tool System
+
+### Using Built-in Tools
+
+GoatChain includes 23 built-in tools:
+
+```typescript
+import { 
+  ReadTool, 
+  WriteTool, 
+  EditTool, 
+  BashTool,
+  GrepTool,
+  GlobTool,
+  WebSearchTool,
+  WebFetchTool,
+} from 'goatchain'
+
+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(),
+  ],
+})
+```
+
+### Creating Custom Tools
+
+```typescript
+import { BaseTool } from 'goatchain'
+
+class MyCustomTool extends BaseTool {
+  name = 'my_tool'
+  description = 'Does something useful'
+  
+  parameters = {
+    type: 'object',
+    properties: {
+      input: {
+        type: 'string',
+        description: 'Input parameter',
+      },
+    },
+    required: ['input'],
+  }
+  
+  async execute(args: { input: string }) {
+    // Your tool logic here
+    return `Processed: ${args.input}`
+  }
+}
+
+// Use it
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are helpful.',
+  model,
+  tools: [new MyCustomTool()],
+})
+```
+
+### Tool Registry
+
+Dynamically manage tools:
+
+```typescript
+const registry = agent.tools
+
+// Register new tool
+registry.register(new MyCustomTool())
+
+// Unregister tool
+registry.unregister('my_tool')
+
+// Get tool
+const tool = registry.get('my_tool')
+
+// List all tools
+const allTools = registry.list()
+
+// Convert to OpenAI format
+const openaiTools = registry.toOpenAIFormat()
 ```
 
-## 🧅 Middleware Pattern
+## 🧅 Middleware System
 
 GoatChain uses a Koa-style onion model for middleware. Each middleware wraps around the core execution:
 
@@ -241,16 +442,16 @@ GoatChain uses a Koa-style onion model for middleware. Each middleware wraps aro
 outer:before → inner:before → exec (model.stream) → inner:after → outer:after
 ```
 
-### Named Middleware
-
-Middlewares can be named for easier management and removal:
+### Adding Middleware
 
 ```typescript
 // Add named middleware (recommended)
 agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
-  const nextState = await next(state)
+  
+  const nextState = await next(state) // Execute next middleware/model
+  
   console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
   return nextState
 }, 'logging')
@@ -266,169 +467,857 @@ const unsubscribe = agent.use(middleware, 'temp')
 unsubscribe() // Remove middleware
 ```
 
-### Built-in Middleware Default Names
+### Built-in Middleware
 
-GoatChain's built-in middleware factories automatically provide default names:
+#### Plan Mode Middleware
+
+Adds planning phase before execution:
 
 ```typescript
-// Plan mode middleware - automatically named 'plan-mode'
+import { createPlanModeMiddleware } from 'goatchain'
+
+// Automatically named 'plan-mode'
 agent.use(createPlanModeMiddleware())
 
-// Context compression middleware - automatically named 'context-compression'
-agent.use(createContextCompressionMiddleware({
-  maxTokens: 128000,
+// With custom configuration
+agent.use(createPlanModeMiddleware({
+  name: 'my-plan', // Custom name
+  planPrompt: 'Create a detailed plan...', // Custom prompt
 }))
+```
+
+#### Context Compression Middleware
 
-// View all middleware
-console.log(agent.middlewareNames)
-// Output: ['plan-mode', 'context-compression']
+Automatically compresses context when token limit is reached using a two-stage strategy:
 
-// Remove by default name
-agent.removeMiddleware('plan-mode')
+```typescript
+import { createContextCompressionMiddleware } from 'goatchain'
 
-// Or customize the name
-agent.use(createPlanModeMiddleware({ name: 'my-plan' }))
+// Automatically named 'context-compression'
 agent.use(createContextCompressionMiddleware({
   maxTokens: 128000,
-}), 'my-compression') // Override default name
+  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',
+}))
 ```
 
-### Middleware Examples
+See [Context Compression Logging Guide](./docs/context-compression-logging.md) for details on monitoring compression behavior.
+
+### Custom Middleware Examples
+
+#### Logging Middleware
 
 ```typescript
-// Logging middleware
 agent.use(async (state, next) => {
-  const start = Date.now()
-  console.log(`[${state.iteration}] Before model call`)
-
-  const nextState = await next(state) // Execute model stream
+  console.log(`Iteration ${state.iteration}:`, {
+    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')
+```
 
-  console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
-  return nextState
-}, 'logging')
+#### Error Handling Middleware
 
-// Error handling middleware
+```typescript
 agent.use(async (state, next) => {
   try {
     return await next(state)
-  }
-  catch (error) {
+  } catch (error) {
+    console.error('Agent error:', error)
     state.shouldContinue = false
     state.stopReason = 'error'
     state.error = error
     return state
   }
 }, 'error-handler')
+```
+
+#### Rate Limiting Middleware
+
+```typescript
+import { RateLimiter } from 'some-rate-limiter'
+
+const limiter = new RateLimiter({ requestsPerMinute: 60 })
 
-// Rate limiting middleware
 agent.use(async (state, next) => {
-  await rateLimiter.acquire()
+  await limiter.acquire()
   return next(state)
 }, 'rate-limiter')
 ```
 
-## 📡 Event Types
-
-The session receive stream emits the following events:
-
-| Event             | Description                           |
-| ----------------- | ------------------------------------- |
-| `iteration_start` | Beginning of a loop iteration         |
-| `text_delta`      | Partial text response from LLM        |
-| `thinking_start`  | Thinking phase begins (if supported)  |
-| `thinking_delta`  | Thinking content delta (if supported) |
-| `thinking_end`    | Thinking phase ends (if supported)    |
-| `tool_call_start` | Tool call begins                      |
-| `tool_call_delta` | Tool call arguments delta             |
-| `tool_call_end`   | Tool call is complete                 |
-| `tool_result`     | Tool execution completed              |
-| `iteration_end`   | End of a loop iteration (includes usage) |
-| `done`            | Stream completed (includes usage)        |
-| `error`           | Error occurred                        |
-
-```typescript
-interface AgentEvent {
-  type:
-    | 'text_delta'
-    | 'tool_call_start'
-    | 'tool_call_delta'
-    | 'tool_call_end'
-    | 'tool_result'
-    | 'thinking_start'
-    | 'thinking_delta'
-    | 'thinking_end'
-    | 'error'
-    | 'done'
-    | 'iteration_start'
-    | 'iteration_end'
-  // ... event-specific fields
+#### Custom Retry Middleware
+
+```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))
+    }
+  }
+  
+  return state
+}, 'retry')
+```
+
+### Middleware State
+
+The `AgentLoopState` object passed to middleware:
+
+```typescript
+interface AgentLoopState {
+  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
+}
+```
+
+## 🔌 Model Client
+
+### Creating a Model Client
+
+```typescript
+import { createModel, createOpenAIAdapter } from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+    baseURL: 'https://api.openai.com/v1', // Optional
+    organization: 'org-xxx', // Optional
+  }),
+})
+```
+
+### OpenAI Adapter Options
+
+```typescript
+interface OpenAIAdapterOptions {
+  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)
+}
+```
+
+### Using Different Models
+
+```typescript
+// OpenAI
+const openai = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+// OpenAI-compatible endpoints
+const deepseek = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'deepseek-chat',
+    apiKey: process.env.DEEPSEEK_API_KEY!,
+    baseURL: 'https://api.deepseek.com/v1',
+  }),
+})
+```
+
+### Model Interface
+
+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>
+}
+
+interface ModelRequest {
+  messages: Message[]
+  tools?: OpenAITool[]
+  temperature?: number
+  maxTokens?: number
+  topP?: number
+  stopSequences?: string[]
 }
 ```
 
-`iteration_end` and `done` events include optional `usage: Usage` with cumulative token counts.
+## 💾 State Management
 
-## 💾 Checkpoint & Resume
+### File State Store
 
-Built-in checkpoint support for resuming interrupted agent executions:
+Persist agent state to filesystem:
 
 ```typescript
-import { Agent, FileStateStore } from 'goatchain'
+import { FileStateStore } from 'goatchain'
 
-// Create state store with configuration
 const stateStore = new FileStateStore({
-  dir: './checkpoints',
-  deleteOnComplete: true, // Clean up after successful completion
+  dir: './checkpoints',           // Storage directory
+  deleteOnComplete: true,         // Auto-delete successful completions
 })
 
-// Agent automatically saves checkpoints when stateStore is provided
 const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
   stateStore,
 })
+```
 
-// Run agent - checkpoints are saved automatically
-const session = await agent.createSession()
-session.send('Hello')
-for await (const event of session.receive()) {
-  console.log(event)
+### In-Memory State Store
+
+For testing or temporary state:
+
+```typescript
+import { InMemoryStateStore } from 'goatchain'
+
+const stateStore = new InMemoryStateStore({
+  deleteOnComplete: false,
+})
+```
+
+### State Store Interface
+
+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>
+  listCheckpoints(): Promise<AgentLoopCheckpoint[]>
 }
 
-// If interrupted, resume from checkpoint
-const checkpoint = await stateStore.loadCheckpoint(session.id)
-if (checkpoint) {
-  const resumed = await agent.resumeSession(session.id)
-  for await (const event of resumed.receive()) {
-    console.log(event)
-  }
+interface AgentLoopCheckpoint {
+  sessionId: string
+  messages: Message[]
+  iteration: number
+  usage: Usage
+  createdAt: number
+  updatedAt: number
 }
 ```
 
-Available state stores:
+### Manual Checkpoint Management
 
-- `FileStateStore` - File-based persistence
-- `InMemoryStateStore` - In-memory (for testing)
+```typescript
+// Save checkpoint manually
+await stateStore.saveCheckpoint({
+  sessionId: session.id,
+  messages: session.messages,
+  iteration: 3,
+  usage: session.usage,
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+})
+
+// Load checkpoint
+const checkpoint = await stateStore.loadCheckpoint('session-id')
+
+// List all checkpoints
+const checkpoints = await stateStore.listCheckpoints()
+
+// Delete checkpoint
+await stateStore.deleteCheckpoint('session-id')
+```
+
+## 📚 Complete Examples
+
+### Example 1: Simple Q&A Bot
+
+```typescript
+import process from 'node:process'
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const agent = new Agent({
+  name: 'Q&A Bot',
+  systemPrompt: 'You are a helpful assistant that answers questions concisely.',
+  model,
+})
+
+const session = await agent.createSession()
+session.send('What is the capital of France?')
+
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+### Example 2: Agent with Tools
+
+```typescript
+import { 
+  Agent, 
+  createModel, 
+  createOpenAIAdapter,
+  ReadTool,
+  WriteTool,
+  BashTool,
+} from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const agent = new Agent({
+  name: 'File Assistant',
+  systemPrompt: 'You help users manage their files.',
+  model,
+  tools: [
+    new ReadTool(),
+    new WriteTool(),
+    new BashTool(),
+  ],
+})
+
+const session = await agent.createSession()
+session.send('Read the package.json file and tell me the version')
+
+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(`\nCalling: ${event.name}`)
+  } else if (event.type === 'tool_result') {
+    console.log(`Result: ${JSON.stringify(event.result).slice(0, 100)}...`)
+  }
+}
+```
+
+### Example 3: Persistent Sessions
+
+```typescript
+import { 
+  Agent, 
+  createModel, 
+  createOpenAIAdapter,
+  FileStateStore,
+} from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const stateStore = new FileStateStore({
+  dir: './agent-state',
+  deleteOnComplete: false, // Keep history
+})
+
+const agent = new Agent({
+  name: 'Persistent Agent',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+  stateStore,
+})
+
+// Create or resume session
+let session
+const sessionId = 'my-conversation'
+
+try {
+  session = await agent.resumeSession(sessionId)
+  console.log('Resumed existing session')
+} catch {
+  session = await agent.createSession({ id: sessionId })
+  console.log('Created new session')
+}
+
+session.send('Remember this: My favorite color is blue')
+
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+### Example 4: Session with Middleware
+
+```typescript
+import { 
+  Agent, 
+  createModel, 
+  createOpenAIAdapter,
+  createPlanModeMiddleware,
+} from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const agent = new Agent({
+  name: 'Planning Agent',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+})
+
+// Add logging middleware
+agent.use(async (state, next) => {
+  console.log(`\n=== Iteration ${state.iteration} ===`)
+  const result = await next(state)
+  console.log(`Tokens used: ${result.usage?.totalTokens || 0}`)
+  return result
+}, 'logger')
+
+// Add plan mode
+agent.use(createPlanModeMiddleware())
+
+const session = await agent.createSession()
+session.send('Create a todo list app with React and TypeScript')
+
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+### Example 5: Multi-turn Conversation
+
+```typescript
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
+
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+const agent = new Agent({
+  name: 'Conversational Agent',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+})
+
+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')
+}
+
+// Multi-turn conversation
+await chat('My name is Alice')
+await chat('What is 2 + 2?')
+await chat('What is my name?') // Should remember "Alice"
+await chat('Multiply the previous result by 3') // Should remember "4"
+
+console.log(`Total messages: ${session.messages.length}`)
+console.log(`Total tokens: ${session.usage.totalTokens}`)
+```
 
 ## 📖 API Reference
 
-### Agent
+### Agent Class
+
+#### Constructor
+
+```typescript
+new Agent(options: AgentOptions)
+```
+
+**Options:**
+- `name: string` - Agent name (required)
+- `systemPrompt: string` - System instructions (required)
+- `model: ModelClient | ModelRef` - LLM client (required)
+- `tools?: BaseTool[]` - Custom tools
+- `stateStore?: StateStore` - Persistence layer
+- `maxIterations?: number` - Max loop iterations (default: 5)
+- `maxConcurrentToolCalls?: number` - Max parallel tools (default: 5)
+- `modelSwapWhitelist?: string[]` - Allowed model IDs
+
+#### Methods
+
+**`createSession(options?): Promise<BaseSession>`**
+
+Create a new session.
+
+```typescript
+const session = await agent.createSession({
+  id: 'custom-id',           // Optional custom ID
+  configOverride: {          // Optional config overrides
+    maxIterations: 10,
+    temperature: 0.7,
+  },
+})
+```
+
+**`resumeSession(sessionId, options?): Promise<BaseSession>`**
+
+Resume an existing session from checkpoint.
+
+```typescript
+const session = await agent.resumeSession('session-123')
+```
+
+**`use(middleware, name?): () => void`**
+
+Add middleware. Returns unsubscribe function.
+
+```typescript
+const unsubscribe = agent.use(myMiddleware, 'my-middleware')
+unsubscribe() // Remove middleware
+```
+
+**`removeMiddleware(name): boolean`**
+
+Remove middleware by name.
+
+```typescript
+agent.removeMiddleware('my-middleware')
+```
+
+**`setModel(modelOrRef): void`**
+
+Switch or pin model at runtime.
+
+```typescript
+// Pin to specific model
+agent.setModel('gpt-4o-mini')
+
+// Use dynamic reference
+agent.setModel({ type: 'ref', ref: 'the-model' })
+```
+
+#### Properties
+
+- `id: string` - Agent ID
+- `name: string` - Agent name
+- `systemPrompt: string` - System prompt
+- `model: ModelClient` - Current model client
+- `tools: ToolRegistry` - Tool registry
+- `stateStore?: StateStore` - State store
+- `sessionManager: BaseSessionManager` - Session manager
+- `middlewareNames: string[]` - List of middleware names
+- `stats: AgentStats` - Usage statistics
+
+### Session Class
+
+#### Methods
+
+**`send(input, options?): void`**
+
+Send a message to the session.
+
+```typescript
+session.send('Hello!', {
+  temperature: 0.8,
+  maxTokens: 1000,
+})
+```
+
+**`receive(options?): AsyncGenerator<AgentEvent>`**
+
+Stream agent events.
+
+```typescript
+for await (const event of session.receive()) {
+  console.log(event)
+}
+```
+
+**`addMessage(message): void`**
+
+Manually add a message.
+
+```typescript
+session.addMessage({
+  role: 'user',
+  content: 'Hello',
+})
+```
+
+**`save(): Promise<void>`**
+
+Manually save session state.
+
+```typescript
+await session.save()
+```
+
+**`toSnapshot(): SessionSnapshot`**
+
+Export session to snapshot.
+
+```typescript
+const snapshot = session.toSnapshot()
+```
+
+**`restoreFromSnapshot(snapshot): void`**
+
+Restore session from snapshot.
+
+```typescript
+session.restoreFromSnapshot(snapshot)
+```
+
+#### Properties
+
+- `id: string` - Session ID
+- `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
+
+### Message Type
+
+```typescript
+interface Message {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string | ToolCall[] | ToolResult[]
+  name?: string       // For tool messages
+  toolCallId?: string // For tool messages
+}
+```
+
+### Usage Type
+
+```typescript
+interface Usage {
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+}
+```
+
+### AgentEvent Types
+
+```typescript
+type AgentEvent = 
+  | TextDeltaEvent
+  | ToolCallStartEvent
+  | ToolCallDeltaEvent
+  | ToolCallEndEvent
+  | ToolResultEvent
+  | ThinkingStartEvent
+  | ThinkingDeltaEvent
+  | ThinkingEndEvent
+  | IterationStartEvent
+  | IterationEndEvent
+  | DoneEvent
+  | ErrorEvent
+
+interface TextDeltaEvent {
+  type: 'text_delta'
+  delta: string
+}
+
+interface ToolCallStartEvent {
+  type: 'tool_call_start'
+  id: string
+  name: string
+}
+
+interface ToolResultEvent {
+  type: 'tool_result'
+  id: string
+  name: string
+  result: unknown
+  error?: string
+}
+
+interface DoneEvent {
+  type: 'done'
+  stopReason: 'stop' | 'max_iterations' | 'error' | 'cancel'
+  usage?: Usage
+}
+```
+
+## 🏗️ Architecture
+
+```mermaid
+classDiagram
+    direction TB
+
+    class Agent {
+        +id: string
+        +name: string
+        +systemPrompt: string
+        +model: ModelClient
+        +tools: ToolRegistry
+        +stateStore: StateStore
+        +sessionManager: BaseSessionManager
+        +use(middleware): this
+        +createSession(): Promise~BaseSession~
+        +resumeSession(id): Promise~BaseSession~
+    }
+
+    class ModelClient {
+        <<interface>>
+        +modelId: string
+        +stream(request): AsyncIterable~ModelStreamEvent~
+    }
+
+    class StateStore {
+        <<interface>>
+        +saveCheckpoint(): Promise~void~
+        +loadCheckpoint(): Promise~Checkpoint~
+        +deleteCheckpoint(): Promise~void~
+        +listCheckpoints(): Promise~Checkpoint[]~
+    }
+
+    class BaseTool {
+        <<abstract>>
+        +name: string
+        +description: string
+        +parameters: JSONSchema
+        +execute(args): Promise~unknown~
+    }
+
+    class ToolRegistry {
+        +register(tool): void
+        +unregister(name): boolean
+        +get(name): BaseTool
+        +list(): BaseTool[]
+    }
+
+    class BaseSession {
+        <<abstract>>
+        +id: string
+        +status: SessionStatus
+        +messages: Message[]
+        +usage: Usage
+        +send(input): void
+        +receive(): AsyncGenerator~AgentEvent~
+        +save(): Promise~void~
+    }
+
+    class Middleware {
+        <<function>>
+        (state, next) => Promise~AgentLoopState~
+    }
+
+    Agent --> ModelClient : uses
+    Agent --> ToolRegistry : uses
+    Agent --> StateStore : uses
+    Agent --> BaseSession : creates
+    Agent ..> Middleware : applies
+    ToolRegistry --> BaseTool : contains
+```
+
+## 🧰 Additional Tools
+
+### CLI
+
+DimCode includes a terminal UI (TUI) for interactive agent sessions:
+
+```bash
+# Install globally
+npm install -g dimcode@latest
+
+# Run
+dim
+```
+
+**Features:**
+- Interactive chat interface
+- Session management
+- Tool approval system
+- Settings configuration
+
+See [docs/cli.md](./docs/cli.md) for details.
+
+### ACP Server
+
+Expose DimCode as an Agent Client Protocol server for editor integrations:
+
+```bash
+bun run acp-server
+```
+
+**Configuration for Zed** (`settings.json`):
+
+```json
+{
+  "agent_servers": {
+    "dimcode": {
+      "command": "pnpm",
+      "args": ["--dir", "/path/to/DimCode", "acp-server"]
+    }
+  }
+}
+```
+
+See [docs/acp-server.md](./docs/acp-server.md) for details.
+
+## 📚 Documentation
 
-| Method                          | Description             |
-| ------------------------------- | ----------------------- |
-| `constructor(options)`          | Create a new agent      |
-| `use(middleware)`               | Add middleware          |
-| `createSession(options)`        | Create a session        |
-| `resumeSession(sessionId, options)` | Resume a session    |
-| `setModel(modelOrRef)`          | Switch/pin model at runtime |
+- [Getting Started Guide](./docs/getting-started.md) - Comprehensive tutorial
+- [CLI Documentation](./docs/cli.md) - Terminal UI features and usage
+- [ACP Server Guide](./docs/acp-server.md) - Editor integration setup
+- [Examples](./examples/) - Sample implementations
 
-### Session
+## 🤝 Contributing
 
-| Method                  | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| `send(input, options?)` | Queue input for the session                  |
-| `receive(options?)`     | Stream events, resuming from checkpoint if present |
-| `messages`              | Conversation history                         |
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
 
 ## 📄 License