goatchain 0.0.2

package/README.md

@@ -0,0 +1,526 @@
+# GoatChain 🐐
+
+> A lightweight, extensible 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)
+
+## ✨ 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
+```
+
+## 📖 Documentation
+
+完整的文档请查看 [docs/](./docs/) 目录：
+
+- [快速开始](./docs/getting-started.md) - 创建你的第一个 Agent Loop
+- [文档索引](./docs/README.md) - 所有文档的完整列表
+
+## 🧰 CLI
+
+After installing `goatchain-cli` globally (or using `pnpm -s cli` in this repo), run:
+
+```bash
+goatchain
+```
+
+Common options:
+
+- `-k, --api-key <key>` (or set `OPENAI_API_KEY`)
+- `-m, --model <id>`
+- `--base-url <url>`
+- `--max-tokens <n>`
+- `--temperature <n>`
+
+Commands:
+
+- `/help` help
+- `/model <id>` switch model id (OpenAI)
+- `/set <k> <v>` set request params (e.g. `temperature`, `maxTokens`, `topP`)
+- `/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)
+- `/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)
+- `/save` persist current config/session
+- `/status` show current model/session info
+- `/new` start a new conversation (clears history)
+
+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.
+- You can also set it in `./.goatchain/config.json` (workspace-scoped, gitignored):
+  - `{"tools":{"webSearch":{"apiKey":"...","apiEndpoint":"...","numResults":10}}}`
+
+Local persistence (workspace-scoped):
+
+- Config and sessions are saved under `./.goatchain/` (auto-created).
+- `.goatchain/` is gitignored to avoid accidentally committing secrets.
+
+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`.
+
+## 🏗️ Architecture
+
+```mermaid
+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 StateStore {
+        <<interface>>
+        +savePoint: string
+        +deleteOnComplete: boolean
+        +saveCheckpoint(checkpoint): Promise~void~
+        +loadCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
+        +deleteCheckpoint(sessionId): Promise~void~
+        +listCheckpoints(agentId): Promise~AgentLoopCheckpoint[]~
+    }
+
+    class BaseTool {
+        <<abstract>>
+        +name: string
+        +description: string
+        +parameters: JSONSchema
+      +execute(args, ctx?): Promise~unknown~
+    }
+
+    class ToolRegistry {
+        +register(tool): void
+        +unregister(name): boolean
+        +get(name): BaseTool
+        +list(): BaseTool[]
+        +toOpenAIFormat(): OpenAITool[]
+    }
+
+    class BaseSession {
+        <<abstract>>
+        +id: string
+        +agentId: string
+        +status: SessionStatus
+        +messages: Message[]
+        +usage: Usage
+        +configOverride: SessionConfigOverride
+        +addMessage(message): void
+        +save(): Promise~void~
+        +toSnapshot(): SessionSnapshot
+        +restoreFromSnapshot(snapshot): void
+    }
+
+    class BaseSessionManager {
+        <<abstract>>
+        +create(agentId, metadata): Promise~BaseSession~
+        +get(sessionId): Promise~BaseSession~
+        +list(agentId): Promise~BaseSession[]~
+        +destroy(sessionId): Promise~void~
+    }
+
+    class Middleware {
+        <<function>>
+        (ctx: AgentLoopState, next: NextFunction) => Promise~void~
+    }
+
+    class AgentLoopState {
+        +sessionId: string
+        +agentId: string
+        +messages: Message[]
+        +iteration: number
+        +pendingToolCalls: ToolCallWithResult[]
+        +currentResponse: string
+        +shouldContinue: boolean
+        +usage: Usage
+    }
+
+    Agent --> BaseModel : uses
+    Agent --> ToolRegistry : uses
+    Agent --> StateStore : uses
+    Agent --> BaseSessionManager : uses
+    Agent ..> Middleware : applies
+    Agent ..> AgentLoopState : manages
+    ToolRegistry --> BaseTool : contains
+    BaseSessionManager --> BaseSession : manages
+```
+
+## 🚀 Quick Start
+
+最简单的 Agent Loop 示例：
+
+```typescript
+import process from 'node:process'
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
+
+// 创建模型
+const model = createModel({
+  adapters: [
+    createOpenAIAdapter({
+      defaultModelId: 'gpt-4o',
+      apiKey: process.env.OPENAI_API_KEY!,
+    }),
+  ],
+})
+
+// 创建 Agent
+const agent = new Agent({
+  name: 'Simple Assistant',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+})
+
+// 流式处理响应
+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)
+  }
+}
+```
+
+📖 **详细文档**: 查看 [docs/getting-started.md](./docs/getting-started.md) 了解更多示例和完整指南。
+
+## 🧅 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
+```
+
+```typescript
+// Logging middleware
+agent.use(async (state, next) => {
+  const start = Date.now()
+  console.log(`[${state.iteration}] Before model call`)
+
+  await next() // Execute model stream
+
+  console.log(`[${state.iteration}] After model call (${Date.now() - start}ms)`)
+})
+
+// Error handling middleware
+agent.use(async (state, next) => {
+  try {
+    await next()
+  } catch (error) {
+    state.shouldContinue = false
+    state.stopReason = 'error'
+    state.error = error
+  }
+})
+
+// Rate limiting middleware
+agent.use(async (state, next) => {
+  await rateLimiter.acquire()
+  await next()
+})
+```
+
+## 📡 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
+}
+```
+
+`iteration_end` and `done` events include optional `usage: Usage` with cumulative token counts.
+
+## 💾 Checkpoint & Resume
+
+Built-in checkpoint support for resuming interrupted agent executions:
+
+```typescript
+import { Agent, FileStateStore } from 'goatchain'
+
+// Create state store with configuration
+const stateStore = new FileStateStore({
+  dir: './checkpoints',
+  savePoint: 'before', // Save before each iteration
+  deleteOnComplete: true, // Clean up after successful completion
+})
+
+// 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)
+}
+
+// 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)
+  }
+}
+```
+
+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
+
+| 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 |
+
+### Session
+
+| Method                  | Description                                  |
+| ----------------------- | -------------------------------------------- |
+| `send(input, options?)` | Queue input for the session                  |
+| `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)