goatchain 0.0.1

package/README.md

@@ -0,0 +1,529 @@
+# 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/agent-loop.svg)](https://badge.fury.io/js/agent-loop)
+[![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 agent-loop
+# or
+npm install agent-loop
+# or
+yarn add agent-loop
+```
+
+## 🧰 CLI
+
+After installing this package 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)
+- `/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.
+
+Local persistence (workspace-scoped):
+
+- Config and sessions are saved under `./.goatchain/` (auto-created).
+- `.goatchain/` is gitignored to avoid accidentally committing secrets.
+
+## 🏗️ Architecture
+
+```mermaid
+classDiagram
+    direction TB
+
+    class Agent {
+        +id: string
+        +name: string
+        +systemPrompt: string
+        +model: BaseModel
+        +tools: ToolRegistry
+        +checkpointStore: CheckpointStore
+        +sessionManager: BaseSessionManager
+        +stats: AgentStats
+        +use(middleware): this
+        +stream(input): AsyncIterable~AgentEvent~
+        +setModel(model): void
+        +toSnapshot(): AgentSnapshot
+        +restoreFromSnapshot(snapshot): void
+    }
+
+    class BaseModel {
+        <<abstract>>
+        +modelId: string
+      +invoke(messages, options): Promise~ChatResponse~
+      +stream(messages, options): AsyncIterable~StreamEvent~
+    }
+
+    class CheckpointStore {
+        <<interface>>
+        +savePoint: string
+        +deleteOnComplete: boolean
+        +saveLoopCheckpoint(checkpoint): Promise~void~
+        +loadLoopCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
+        +deleteLoopCheckpoint(sessionId): Promise~void~
+        +listLoopCheckpoints(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
+        +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 --> CheckpointStore : uses
+    Agent --> BaseSessionManager : uses
+    Agent ..> Middleware : applies
+    Agent ..> AgentLoopState : manages
+    ToolRegistry --> BaseTool : contains
+    BaseSessionManager --> BaseSession : manages
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { Agent, BaseModel, BaseTool, ToolRegistry, createModel, createOpenAIAdapter } from 'agent-loop'
+
+// 1. Create model with built-in adapters (recommended)
+const model = createModel({
+  adapters: [
+    createOpenAIAdapter({
+      defaultModelId: 'gpt-4o',  // Set default model
+      apiKeySecretName: 'OPENAI_API_KEY',
+    }),
+  ],
+})
+
+// 2. Create tools
+class WeatherTool extends BaseTool {
+  name = 'get_weather'
+  description = 'Get current weather for a location'
+  parameters = {
+    type: 'object',
+    properties: {
+      location: { type: 'string', description: 'City name' },
+    },
+    required: ['location'],
+  }
+
+  async execute(args) {
+    return { temperature: 22, condition: 'sunny' }
+  }
+}
+
+// 3. Setup tool registry
+const tools = new ToolRegistry()
+tools.register(new WeatherTool())
+
+// 4. Create agent
+const agent = new Agent({
+  name: 'Weather Assistant',
+  systemPrompt: 'You are a helpful weather assistant.',
+  model,
+  tools,
+})
+
+// 5. Add middleware (optional)
+agent.use(async (state, next) => {
+  console.log(`Iteration ${state.iteration} starting...`)
+  await next()
+  console.log(`Iteration ${state.iteration} complete`)
+})
+
+// 6. Stream responses
+for await (const event of agent.stream({
+  sessionId: 'session-1',
+  input: 'What is the weather in Tokyo?',
+})) {
+  switch (event.type) {
+    case 'text_delta':
+      process.stdout.write(event.delta)
+      break
+    case 'tool_call_end':
+      console.log('Calling tool:', event.toolCall.function.name)
+      break
+    case 'tool_result':
+      console.log('Tool result:', event.result)
+      break
+    case 'done':
+      console.log('\nDone:', event.stopReason)
+      break
+  }
+}
+```
+
+## 🧅 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 agent 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                 |
+| `usage`           | Token consumption stats                  |
+| `iteration_end`   | End of a loop iteration                  |
+| `done`            | Stream completed                         |
+| `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'
+    | 'usage'
+    | 'error'
+    | 'done'
+    | 'iteration_start'
+    | 'iteration_end'
+  // ... event-specific fields
+}
+```
+
+## 💾 Checkpoint & Resume
+
+Built-in checkpoint support for resuming interrupted agent executions:
+
+```typescript
+import { Agent, FileCheckpointStore } from 'agent-loop'
+
+// Create checkpoint store with configuration
+const checkpointStore = new FileCheckpointStore({
+  dir: './checkpoints',
+  savePoint: 'before',      // Save before each iteration
+  deleteOnComplete: true,   // Clean up after successful completion
+})
+
+// Agent automatically saves checkpoints when checkpointStore is provided
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are helpful.',
+  model,
+  checkpointStore,
+})
+
+// Run agent - checkpoints are saved automatically
+for await (const event of agent.stream({
+  sessionId: 'session-1',
+  input: 'Hello',
+})) {
+  console.log(event)
+}
+
+// If interrupted, resume from checkpoint
+const checkpoint = await checkpointStore.loadLoopCheckpoint('session-1')
+if (checkpoint) {
+  for await (const event of agent.streamFromCheckpoint({ checkpoint })) {
+    console.log(event)
+  }
+}
+```
+
+Available checkpoint stores:
+- `FileCheckpointStore` - File-based persistence
+- `InMemoryCheckpointStore` - 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
+│   ├── checkpointStore.ts       # CheckpointStore interface
+│   ├── FileCheckpointStore.ts   # File-based checkpoint storage
+│   └── InMemoryCheckpointStore.ts  # In-memory checkpoint 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 'agent-loop'
+
+// Cancellation support
+const controller = new AbortController()
+
+try {
+  for await (const event of agent.stream({
+    sessionId: 'session-1',
+    input: 'Hello',
+    signal: controller.signal,
+    maxIterations: 5,
+  })) {
+    // 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          |
+| `stream(input)`                 | Stream agent execution  |
+| `setModel(model)`               | Switch model at runtime |
+| `toSnapshot()`                  | Create agent snapshot   |
+| `restoreFromSnapshot(snapshot)` | Restore from snapshot   |
+
+### AgentInput
+
+| Property         | Type          | Description                       |
+| ---------------- | ------------- | --------------------------------- |
+| `sessionId`      | `string`      | Session identifier                |
+| `input`          | `string`      | User input message                |
+| `messages?`      | `Message[]`   | Optional conversation history     |
+| `model?`         | `ModelRef`    | Optional model override for this request |
+| `signal?`        | `AbortSignal` | Cancellation support              |
+| `maxIterations?` | `number`      | Max loop iterations (default: 10) |
+
+## 🔄 Model Switching
+
+### Per-Request Model Override
+
+Temporarily use a different model for a single request:
+
+```typescript
+for await (const event of agent.stream({
+  sessionId: 'session-1',
+  input: 'Explain quantum physics',
+  model: { provider: 'openai', modelId: 'gpt-4' },  // Use GPT-4 for this request only
+})) {
+  // ...
+}
+```
+
+### 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
+for await (const event of agent.stream({
+  sessionId: 'session-1',
+  input: 'Hello',
+})) {
+  // Uses 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)

package/cli/args.mjs

@@ -0,0 +1,113 @@
+import { Command, InvalidArgumentError } from 'commander'
+
+export function getReplHelpText() {
+  return [
+    '',
+    'Interactive slash commands:',
+    '  /help                     Show help',
+    '  /model [id]               Show/set model id',
+    '  /workspace                Switch workspace root (interactive)',
+    '  /files                    Attach file(s) (interactive)',
+    '  /images                   Attach image(s) (interactive)',
+    '  /settings                 Base URL / API key / tokens',
+    '  /output                   Output & UX options',
+    '  /diag                     Show diagnostics for last turn',
+    '  /edit                     Compose a message in $EDITOR',
+    '  /multiline                Start multiline input (.send/.cancel)',
+    '  /set <k> <v>              Set request param (maxTokens/temperature/topP/...)',
+    '  /unset <k>                Clear request param',
+    '  /params                   Show current request params',
+    '  /base-url <url>           Set base URL (recreates client if needed)',
+    '  /api-key <key>            Set API key for this process (not printed)',
+    '  /tools                    List enabled tools',
+    '  /sessions                 List/pick/delete sessions',
+    '  /use <sessionId>          Switch session (restore history)',
+    '  /rm <sessionId...>        Delete session(s)',
+    '  /save                     Save current session/config',
+    '  /status                   Show current session/model info',
+    '  /new                      Start a new conversation (clears history)',
+    '  /exit                     Exit',
+    '',
+    'Mentions:',
+    '  @                         Open quick actions (clack if installed)',
+    '  @clear                    Clear pending attachments',
+    '  @file                     Attach file(s) to the next prompt',
+    '  @image/@img               Attach image(s) to the next prompt',
+    '  @workspace                Switch workspace root (interactive)',
+    '',
+    'Keybindings:',
+    '  Ctrl+K                    Open command palette',
+    '  Ctrl+O                    Manage attachments',
+    '  Ctrl+G                    Clear attachments',
+    '',
+  ].join('\n')
+}
+
+function parseFiniteNumber(name) {
+  return (v) => {
+    const n = Number(v)
+    if (!Number.isFinite(n))
+      throw new InvalidArgumentError(`Invalid ${name}: ${v}`)
+    return n
+  }
+}
+
+function parseFiniteInt(name) {
+  return (v) => {
+    const n = Number.parseInt(v, 10)
+    if (!Number.isFinite(n))
+      throw new InvalidArgumentError(`Invalid ${name}: ${v}`)
+    return n
+  }
+}
+
+export function buildProgram(version) {
+  return new Command()
+    .name('goatchain')
+    .description('A tiny interactive chat CLI built on agent-loop')
+    .argument('[prompt...]', 'one-shot prompt (omit to start interactive mode)')
+    .option('-k, --api-key <key>', 'OpenAI API key (or set OPENAI_API_KEY)')
+    .option('-m, --model <id>', 'Default model id (OpenAI)')
+    .option('--system <prompt>', 'System prompt')
+    .option('--base-url <url>', 'Override OpenAI base URL (proxy)')
+    .option('--max-tokens <n>', 'Max completion tokens', parseFiniteInt('max-tokens'))
+    .option('--temperature <n>', 'Temperature (0-2)', parseFiniteNumber('temperature'))
+    .option('--top-p <n>', 'Top-p (0-1)', parseFiniteNumber('top-p'))
+    .option('--presence-penalty <n>', 'Presence penalty (-2..2)', parseFiniteNumber('presence-penalty'))
+    .option('--frequency-penalty <n>', 'Frequency penalty (-2..2)', parseFiniteNumber('frequency-penalty'))
+    .option('--seed <n>', 'Random seed', parseFiniteInt('seed'))
+    .option('--timeout-ms <n>', 'Request timeout in ms', parseFiniteInt('timeout-ms'))
+    .option('--session <id>', 'Use a saved session id (optional)')
+    .version(version, '-v, --version', 'Show version')
+    .helpOption('-h, --help', 'Show help')
+    .showHelpAfterError()
+    .showSuggestionAfterError()
+    .addHelpText('after', getReplHelpText())
+}
+
+export function parseCliArgs(argv, version) {
+  const program = buildProgram(version)
+  program.parse(argv, { from: 'user' })
+
+  const opts = program.opts()
+  const prompt = Array.isArray(program.args) ? program.args.join(' ').trim() : ''
+
+  const normalizeFiniteNumber = (n) => (typeof n === 'number' && Number.isFinite(n) ? n : undefined)
+  const normalizeFiniteInt = (n) => (typeof n === 'number' && Number.isFinite(n) ? Math.trunc(n) : undefined)
+
+  return {
+    apiKey: typeof opts.apiKey === 'string' && opts.apiKey.trim() ? opts.apiKey : undefined,
+    modelId: typeof opts.model === 'string' && opts.model.trim() ? opts.model : undefined,
+    system: typeof opts.system === 'string' && opts.system.trim() ? opts.system : undefined,
+    baseUrl: typeof opts.baseUrl === 'string' && opts.baseUrl.trim() ? opts.baseUrl : undefined,
+    maxTokens: normalizeFiniteInt(opts.maxTokens),
+    temperature: normalizeFiniteNumber(opts.temperature),
+    topP: normalizeFiniteNumber(opts.topP),
+    presencePenalty: normalizeFiniteNumber(opts.presencePenalty),
+    frequencyPenalty: normalizeFiniteNumber(opts.frequencyPenalty),
+    seed: normalizeFiniteInt(opts.seed),
+    timeoutMs: normalizeFiniteInt(opts.timeoutMs),
+    sessionId: typeof opts.session === 'string' && opts.session.trim() ? opts.session : undefined,
+    prompt,
+  }
+}