goatchain 0.0.2 → 0.0.3

package/README.md

@@ -5,6 +5,8 @@
 [![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
@@ -21,12 +23,42 @@
 pnpm add goatchain
 ```
 
-## 📖 Documentation
+## 🚀 Quick Start
+
+Simple Agent Loop example:
 
-完整的文档请查看 [docs/](./docs/) 目录：
+```typescript
+import process from 'node:process'
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
 
-- [快速开始](./docs/getting-started.md) - 创建你的第一个 Agent Loop
-- [文档索引](./docs/README.md) - 所有文档的完整列表
+// Create model
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+// Create Agent
+const agent = new Agent({
+  name: 'Simple Assistant',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+})
+
+// Stream responses
+const session = await agent.createSession()
+session.send('Hello!')
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  } else if (event.type === 'done') {
+    console.log('\nDone:', event.stopReason)
+  }
+}
+```
+
+📖 **Full Documentation**: See [docs/getting-started.md](./docs/getting-started.md) for more examples and complete guide.
 
 ## 🧰 CLI
 
@@ -48,11 +80,14 @@ Commands:
 
 - `/help` help
 - `/model <id>` switch model id (OpenAI)
-- `/set <k> <v>` set request params (e.g. `temperature`, `maxTokens`, `topP`)
+- `/plan [on|off|toggle]` toggle plan mode (plan → confirm → execute)
+- `/approvals` select approval mode (interactive)
+- `/set <k> <v>` set request params (e.g. `temperature`, `maxTokens`)
 - `/unset <k>` clear a request param
 - `/params` show current request params
 - `/base-url <url>` set base URL
 - `/api-key <key>` set API key (not printed)
+- `/web-search-key <key>` set Serper API key for WebSearch tool (not printed)
 - `/tools` list enabled tools (Read/Write/Edit/Glob/Grep/WebSearch*)
 - `/sessions` list and pick a saved session
 - `/use <sessionId>` restore a saved session (prints recent history)
@@ -65,9 +100,21 @@ Requires `OPENAI_API_KEY` in the environment.
 Web search (optional):
 
 - Set `SERPER_API_KEY` (or `GOATCHAIN_SERPER_API_KEY`) to enable the builtin `WebSearch` tool for up-to-date info like weather.
+- In interactive mode, you can also run `/web-search-key <key>` to persist the key into the workspace config.
 - You can also set it in `./.goatchain/config.json` (workspace-scoped, gitignored):
   - `{"tools":{"webSearch":{"apiKey":"...","apiEndpoint":"...","numResults":10}}}`
 
+Plan mode (interactive planning):
+
+- Enable with `/plan on` to enter a plan-first workflow:
+  1. Agent explores the codebase and researches your request
+  2. Agent may ask clarifying questions using the `AskUserQuestion` tool to understand your preferences (e.g., library choices, architectural decisions)
+  3. Agent creates a structured plan using `TodoPlan` (3-8 steps)
+  4. You review and approve the plan
+  5. Agent executes the approved plan
+- During planning, file modifications are blocked (read-only phase)
+- Set `GOATCHAIN_PLAN_MODE=1` or configure in `.goatchain/config.json` to enable by default
+
 Local persistence (workspace-scoped):
 
 - Config and sessions are saved under `./.goatchain/` (auto-created).
@@ -76,7 +123,42 @@ Local persistence (workspace-scoped):
 DeepSeek thinking mode compatibility:
 
 - Some OpenAI-compatible gateways (e.g. DeepSeek thinking mode) require `reasoning_content` to be present on assistant messages that contain `tool_calls` (and may reject empty strings). GoatChain will attach the accumulated thinking content when available.
-- If you use DeepSeek via a proxy where GoatChain can't detect it from `baseUrl`/`modelId`, set `openai.compat.requireReasoningContentForToolCalls=true` in `./.goatchain/config.json`.
+- If you use DeepSeek via a proxy where GoatChain can't detect it from `baseUrl`/`modelId`, you can enable this explicitly:
+  - Interactive: Run `/settings` and toggle "Interleaved Thinking"
+  - Config file: Set `openai.compat.interleavedThinking=true` in `./.goatchain/config.json`
+
+## 🔌 ACP Server
+
+GoatChain can be exposed as an ACP (Agent Client Protocol) server for integration with editors like Zed.
+
+```bash
+pnpm acp-server
+```
+
+**Configuration for Zed** (`settings.json`):
+
+```json
+{
+  "agent_servers": {
+    "goatchain": {
+      "command": "pnpm",
+      "args": ["--dir", "/path/to/GoatChain", "acp-server"]
+    }
+  }
+}
+```
+
+**Features:**
+- File operations (read, write, edit)
+- Search tools (glob, grep, ast-grep)
+- Web search and task management
+- Same tool set as CLI agent mode
+
+**Available servers:**
+- `pnpm acp-server` - Simple agent (recommended)
+- `pnpm acp-server:plan` - With plan mode (experimental)
+
+📖 **Full Documentation**: See [docs/acp-server.md](./docs/acp-server.md) for configuration and troubleshooting.
 
 ## 🏗️ Architecture
 
@@ -84,27 +166,27 @@ DeepSeek thinking mode compatibility:
 classDiagram
     direction TB
 
-    class Agent {
-        +id: string
-        +name: string
-        +systemPrompt: string
-        +model: BaseModel
-        +tools: ToolRegistry
-        +stateStore: StateStore
-        +sessionManager: BaseSessionManager
-        +stats: AgentStats
-        +use(middleware): this
-        +createSession(options): BaseSession
-        +resumeSession(sessionId, options): BaseSession
-        +setModel(modelOrRef): void
-    }
-
-    class BaseModel {
-        <<abstract>>
-        +modelId: string
-      +invoke(messages, options): Promise~ChatResponse~
-      +stream(messages, options): AsyncIterable~StreamEvent~
-    }
+	    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~
+	    }
 
     class StateStore {
         <<interface>>
@@ -113,7 +195,7 @@ classDiagram
         +saveCheckpoint(checkpoint): Promise~void~
         +loadCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
         +deleteCheckpoint(sessionId): Promise~void~
-        +listCheckpoints(agentId): Promise~AgentLoopCheckpoint[]~
+        +listCheckpoints(): Promise~AgentLoopCheckpoint[]~
     }
 
     class BaseTool {
@@ -135,7 +217,6 @@ classDiagram
     class BaseSession {
         <<abstract>>
         +id: string
-        +agentId: string
         +status: SessionStatus
         +messages: Message[]
         +usage: Usage
@@ -148,9 +229,9 @@ classDiagram
 
     class BaseSessionManager {
         <<abstract>>
-        +create(agentId, metadata): Promise~BaseSession~
+        +create(sessionId?): Promise~BaseSession~
         +get(sessionId): Promise~BaseSession~
-        +list(agentId): Promise~BaseSession[]~
+        +list(): Promise~BaseSession[]~
         +destroy(sessionId): Promise~void~
     }
 
@@ -161,7 +242,6 @@ classDiagram
 
     class AgentLoopState {
         +sessionId: string
-        +agentId: string
         +messages: Message[]
         +iteration: number
         +pendingToolCalls: ToolCallWithResult[]
@@ -170,7 +250,7 @@ classDiagram
         +usage: Usage
     }
 
-    Agent --> BaseModel : uses
+    Agent --> ModelClient : uses
     Agent --> ToolRegistry : uses
     Agent --> StateStore : uses
     Agent --> BaseSessionManager : uses
@@ -180,80 +260,98 @@ classDiagram
     BaseSessionManager --> BaseSession : manages
 ```
 
-## 🚀 Quick Start
+## 🧅 Middleware Pattern
+
+GoatChain uses a Koa-style onion model for middleware. Each middleware wraps around the core execution:
+
+```
+outer:before → inner:before → exec (model.stream) → inner:after → outer:after
+```
 
-最简单的 Agent Loop 示例：
+### Named Middleware
+
+Middlewares can be named for easier management and removal:
 
 ```typescript
-import process from 'node:process'
-import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
+// 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)
+  console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
+  return nextState
+}, 'logging')
 
-// 创建模型
-const model = createModel({
-  adapters: [
-    createOpenAIAdapter({
-      defaultModelId: 'gpt-4o',
-      apiKey: process.env.OPENAI_API_KEY!,
-    }),
-  ],
-})
+// Remove by name
+agent.removeMiddleware('logging')
 
-// 创建 Agent
-const agent = new Agent({
-  name: 'Simple Assistant',
-  systemPrompt: 'You are a helpful assistant.',
-  model,
-})
+// View all middleware names
+console.log(agent.middlewareNames) // ['logging', 'compression', ...]
 
-// 流式处理响应
-const session = await agent.createSession()
-session.send('Hello!')
-for await (const event of session.receive()) {
-  if (event.type === 'text_delta') {
-    process.stdout.write(event.delta)
-  } else if (event.type === 'done') {
-    console.log('\n完成:', event.stopReason)
-  }
-}
+// Use unsubscribe function
+const unsubscribe = agent.use(middleware, 'temp')
+unsubscribe() // Remove middleware
 ```
 
-📖 **详细文档**: 查看 [docs/getting-started.md](./docs/getting-started.md) 了解更多示例和完整指南。
-
-## 🧅 Middleware Pattern
+### Built-in Middleware Default Names
 
-GoatChain uses a Koa-style onion model for middleware. Each middleware wraps around the core execution:
+GoatChain's built-in middleware factories automatically provide default names:
 
-```
-outer:before → inner:before → exec (model.stream) → inner:after → outer:after
+```typescript
+// Plan mode middleware - automatically named 'plan-mode'
+agent.use(createPlanModeMiddleware())
+
+// Context compression middleware - automatically named 'context-compression'
+agent.use(createContextCompressionMiddleware({
+  maxTokens: 128000,
+}))
+
+// View all middleware
+console.log(agent.middlewareNames)
+// Output: ['plan-mode', 'context-compression']
+
+// Remove by default name
+agent.removeMiddleware('plan-mode')
+
+// Or customize the name
+agent.use(createPlanModeMiddleware({ name: 'my-plan' }))
+agent.use(createContextCompressionMiddleware({
+  maxTokens: 128000,
+}), 'my-compression') // Override default name
 ```
 
+### Middleware Examples
+
 ```typescript
 // Logging middleware
 agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
 
-  await next() // Execute model stream
+  const nextState = await next(state) // Execute model stream
 
   console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
-})
+  return nextState
+}, 'logging')
 
 // Error handling middleware
 agent.use(async (state, next) => {
   try {
-    await next()
-  } catch (error) {
+    return await next(state)
+  }
+  catch (error) {
     state.shouldContinue = false
     state.stopReason = 'error'
     state.error = error
+    return state
   }
-})
+}, 'error-handler')
 
 // Rate limiting middleware
 agent.use(async (state, next) => {
   await rateLimiter.acquire()
-  await next()
-})
+  return next(state)
+}, 'rate-limiter')
 ```
 
 ## 📡 Event Types
@@ -340,92 +438,6 @@ Available state stores:
 - `FileStateStore` - File-based persistence
 - `InMemoryStateStore` - In-memory (for testing)
 
-## 🔧 Session Management
-
-Sessions represent individual conversations with per-session configuration overrides:
-
-```typescript
-// Create session
-const session = await sessionManager.create(agent.id, {
-  customField: 'value',
-})
-
-// Session-level overrides
-session.setModelOverride({ modelId: 'gpt-4o-mini' })
-session.setSystemPromptOverride('You are a concise assistant.')
-session.disableTools(['dangerous_tool'])
-
-// Track session activity
-session.addMessage({ role: 'user', content: 'Hello!' })
-session.addUsage({ promptTokens: 10, completionTokens: 5, totalTokens: 15 })
-session.recordResponse(1500) // ms
-
-// Get session snapshot for persistence
-const snapshot = session.toSnapshot()
-```
-
-## 📁 Project Structure
-
-```
-src/
-├── index.ts              # Public exports
-├── types/
-│   ├── index.ts          # Re-export all types
-│   ├── message.ts        # Message types (User, Assistant, Tool, System)
-│   ├── event.ts          # Stream event types
-│   ├── common.ts         # Shared types (ToolCall, Usage, JSONSchema)
-│   └── snapshot.ts       # Snapshot types (Agent, Session)
-├── model/
-│   ├── index.ts
-│   ├── base.ts           # BaseModel abstract class
-│   └── types.ts          # Model-specific types
-├── state/
-│   ├── index.ts
-│   ├── stateStore.ts            # StateStore interface
-│   ├── FileStateStore.ts        # File-based state storage
-│   └── InMemoryStateStore.ts    # In-memory state storage
-├── tool/
-│   ├── index.ts
-│   ├── base.ts           # BaseTool abstract class
-│   └── registry.ts       # ToolRegistry class
-├── session/
-│   ├── index.ts
-│   ├── base.ts           # BaseSession abstract class
-│   └── manager.ts        # BaseSessionManager abstract class
-└── agent/
-    ├── index.ts
-    ├── agent.ts          # Agent class
-    ├── types.ts          # Agent types (AgentLoopState, AgentInput, etc.)
-    ├── middleware.ts     # Middleware compose function
-    └── errors.ts         # Agent-specific errors
-```
-
-## 🛡️ Error Handling
-
-```typescript
-import { AgentAbortError, AgentMaxIterationsError } from 'goatchain'
-
-// Cancellation support
-const controller = new AbortController()
-
-try {
-  const session = await agent.createSession({ maxIterations: 5 })
-  session.send('Hello', { signal: controller.signal })
-  for await (const event of session.receive()) {
-    // Handle events...
-  }
-} catch (error) {
-  if (error instanceof AgentAbortError) {
-    console.log('Agent was cancelled')
-  } else if (error instanceof AgentMaxIterationsError) {
-    console.log('Max iterations reached')
-  }
-}
-
-// Cancel from another context
-controller.abort()
-```
-
 ## 📖 API Reference
 
 ### Agent
@@ -446,81 +458,6 @@ controller.abort()
 | `receive(options?)`     | Stream events, resuming from checkpoint if present |
 | `messages`              | Conversation history                         |
 
-### CreateSessionOptions
-
-| Property         | Type          | Description                              |
-| ---------------- | ------------- | ---------------------------------------- |
-| `model?`         | `ModelRef`    | Optional model override for this session |
-| `maxIterations?` | `number`      | Max loop iterations (default: 10)        |
-| `hooks?`         | `ToolHooks`   | Tool execution hooks                     |
-| `requestParams?` | `object`      | Model request parameters                 |
-
-### SendOptions
-
-| Property         | Type          | Description                              |
-| ---------------- | ------------- | ---------------------------------------- |
-| `signal?`        | `AbortSignal` | Cancellation support                     |
-| `toolContext?`   | `object`      | Tool execution context input             |
-
-## 🔄 Model Switching
-
-### Per-Request Model Override
-
-Temporarily use a different model for a single request:
-
-```typescript
-const session = await agent.createSession({
-  model: { provider: 'openai', modelId: 'gpt-4' }, // Use GPT-4 for this session
-})
-session.send('Explain quantum physics')
-for await (const event of session.receive()) {
-  // ...
-}
-```
-
-### Persistent Model Switch
-
-Change the default model for all subsequent requests:
-
-```typescript
-// Switch model at runtime
-model.setModelId('gpt-4')
-
-// All subsequent requests will use the new model
-const session = await agent.createSession()
-session.send('Hello')
-for await (const event of session.receive()) {
-  // Uses gpt-4
-}
-```
-
-### Pin Default Model (Overrides Routing)
-
-If your `ModelClient` supports routing (e.g. created via `createModel()`), you can pin a specific default model at the agent level:
-
-```typescript
-agent.setModel({ provider: 'openai', modelId: 'gpt-4' })
-```
-
-### Multi-Provider Fallback
-
-Configure multiple models with automatic fallback:
-
-```typescript
-const model = createModel({
-  adapters: [
-    createOpenAIAdapter({ defaultModelId: 'gpt-4' }),
-    createAnthropicAdapter({ defaultModelId: 'claude-3' }),
-  ],
-  routing: {
-    fallbackOrder: [
-      { provider: 'openai', modelId: 'gpt-4' }, // Try first
-      { provider: 'anthropic', modelId: 'claude-3' }, // Fallback if first fails
-    ],
-  },
-})
-```
-
 ## 📄 License
 
 MIT © [Simon He](https://github.com/Simon-He95)