goatchain 0.0.29 → 0.0.31

package/README.md

@@ -28,6 +28,7 @@ hooks: {
 ```
 
 If you need both, use:
+
 - `preToolUse` to rewrite tool arguments/tool call
 - `permissionRequest` to allow or block execution
 
@@ -115,19 +116,25 @@ const session = await agent.createSession({
 interface CreateSessionOptions {
   sessionId?: string // Custom session ID
   model?: ModelRef // Optional model override
+  variants?: ModelRef[] // Optional fallback model refs
   maxIterations?: number // Max agent loop iterations (default: 1000)
   cwd?: string // Working directory for file operations
+  messageQueueConfig?: {
+    autoProcessQueue?: boolean // Auto-process queued messages (default: true)
+    maxQueueSize?: number // Optional queue length limit
+  }
   requestParams?: {
     temperature?: number // Model temperature
     maxTokens?: number // Max output tokens
-    topP?: number // Nucleus sampling parameter
+    stop?: string[] // Optional stop sequences
+    [key: string]: unknown // Provider-specific request params
   }
 }
 ```
 
 ### Working Directory (CWD) Configuration
 
-You can set a working directory for the session, which will be automatically applied to all file operation tools (Read, Write, Edit, Glob, Grep, Bash, AstGrepSearch, AstGrepReplace):
+You can set a working directory for the session, which will be automatically applied to tools that support `setCwd()` (for example `Read`, `Write`, `Edit`, `Glob`, `Grep`, and `Bash`):
 
 ```typescript
 // Set CWD when creating a session
@@ -161,13 +168,70 @@ session.send('What is the weather today?')
 
 // Multiple messages in sequence
 session.send('First question')
-// Wait for response...
 session.send('Follow-up question')
 ```
 
 #### Send Options
 
-You can pass options to `send()` to control tool execution, approval, and more:
+You can pass options to `send()` to control priority, tool execution, approval, and more:
+
+```typescript
+// Higher priority messages are processed first (smaller number = higher priority)
+session.send('Low priority', { priority: 10 })
+session.send('High priority', { priority: 1 })
+```
+
+`send()` returns a message ID that can be used for queue management:
+
+```typescript
+const messageId = session.send('Can be cancelled later')
+session.cancelQueuedMessage(messageId)
+```
+
+#### Message Queue
+
+Session now supports queue-based messaging by default. You can enqueue multiple messages safely even while a previous `receive()` is running.
+
+```typescript
+const session = await agent.createSession()
+
+session.send('First message')
+session.send('Second message')
+
+// Batch enqueue with priority
+session.sendBatch([
+  { input: 'Task A', priority: 2 },
+  { input: 'Task B', priority: 1 },
+])
+
+// Inspect queue state
+const queue = session.getQueueStatus()
+console.log(queue.length, queue.isProcessing)
+
+// Remove queued messages
+session.clearQueue()
+```
+
+Manual queue mode:
+
+```typescript
+const session = await agent.createSession({
+  messageQueueConfig: { autoProcessQueue: false },
+})
+
+session.send('Message 1')
+session.send('Message 2')
+
+for await (const event of session.receive()) {
+  // only Message 1
+}
+
+for await (const event of session.receive()) {
+  // Message 2
+}
+```
+
+Tool context and approval options still work as before:
 
 ```typescript
 // Auto-approve all tools for this request
@@ -212,7 +276,7 @@ for await (const event of session.receive()) {
       break
 
     case 'tool_call_start':
-      console.log(`\nCalling tool: ${event.name}`)
+      console.log(`\nCalling tool: ${event.toolName ?? event.callId}`)
       break
 
     case 'tool_result':
@@ -228,30 +292,28 @@ for await (const event of session.receive()) {
       console.log(`\nConversation done: ${event.stopReason}`)
       console.log(`Total tokens: ${event.usage?.totalTokens}`)
       break
-
-    case 'error':
-      console.error(`Error: ${event.error}`)
-      break
   }
 }
 ```
 
 ### Session Event Types
 
-| Event Type        | Description                 | Key Fields            |
-| ----------------- | --------------------------- | --------------------- |
-| `iteration_start` | Agent loop iteration begins | `iteration`           |
-| `text_delta`      | Partial text response       | `delta`               |
-| `thinking_start`  | Reasoning phase begins      | -                     |
-| `thinking_delta`  | Reasoning content           | `delta`               |
-| `thinking_end`    | Reasoning phase ends        | -                     |
-| `tool_call_start` | Tool invocation begins      | `name`, `id`          |
-| `tool_call_delta` | Tool arguments stream       | `delta`               |
-| `tool_call_end`   | Tool call complete          | `name`, `args`        |
-| `tool_result`     | Tool execution result       | `result`, `error`     |
-| `iteration_end`   | Iteration complete          | `usage`, `iteration`  |
-| `done`            | Stream finished             | `stopReason`, `usage` |
-| `error`           | Error occurred              | `error`               |
+| Event Type                                              | Description                                      | Key Fields                                         |
+| ------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| `session_created`                                       | New session stream starts                        | `sessionId`                                        |
+| `text_start` / `text_delta` / `text_end`                | Assistant text stream                            | `delta`, `content`                                 |
+| `thinking_start` / `thinking_delta` / `thinking_end`    | Model reasoning stream                           | `delta`, `content`                                 |
+| `tool_call_start` / `tool_call_delta` / `tool_call_end` | Tool call lifecycle                              | `callId`, `toolName`, `toolCall`                   |
+| `tool_output_start` / `tool_output_delta`               | Live tool stdout/stderr stream                   | `tool_call_id`, `delta`, `isStderr`                |
+| `tool_result`                                           | Tool execution result                            | `tool_call_id`, `result`, `isError`                |
+| `tool_approval_requested`                               | High-risk tool needs approval                    | `tool_call_id`, `toolName`, `riskLevel`, `args`    |
+| `requires_action`                                       | Execution paused for approval or AskUser answers | `kind`, `checkpoint`, `checkpointRef`, `questions` |
+| `tool_skipped`                                          | Tool execution skipped                           | `tool_call_id`, `toolName`, `reason`               |
+| `iteration_start` / `iteration_end`                     | Agent loop iteration lifecycle                   | `iteration`, `usage`                               |
+| `subagent_event`                                        | Forwarded subagent status                        | `subagentId`, `subagentType`, `phase`              |
+| `compression_start` / `compression_end`                 | Context compression lifecycle                    | `tokensBefore`, `tokensAfter`, `strategy`          |
+| `hook_evaluation`                                       | Prompt-hook evaluation lifecycle                 | `hookName`, `phase`, `status`                      |
+| `done`                                                  | Stream finished                                  | `stopReason`, `modelStopReason`, `error`, `usage`  |
 
 ### Session State Management
 
@@ -260,7 +322,7 @@ for await (const event of session.receive()) {
 console.log(session.messages) // Message[]
 
 // Check session status
-console.log(session.status) // 'idle' | 'running' | 'completed' | 'error'
+console.log(session.status) // 'active' | 'paused' | 'completed' | 'error' | 'archived'
 
 // Get token usage
 console.log(session.usage)
@@ -320,8 +382,8 @@ for await (const event of session.receive()) {
   }
 }
 
-// Session now contains full conversation history
-console.log(session.messages.length) // 4 (2 user, 2 assistant)
+// Session now contains the full conversation history plus the system prompt
+console.log(session.messages.length) // 5 (system + 2 user + 2 assistant)
 ```
 
 ### Resuming Sessions
@@ -358,7 +420,7 @@ for await (const event of resumed.receive()) {
 }
 ```
 
-### Session Lifecycle Hooks
+### Session Utilities
 
 ```typescript
 // Add message manually
@@ -370,8 +432,9 @@ session.addMessage({
 // Save session state manually
 await session.save()
 
-// Clear session history
-session.messages = []
+// Advanced: direct message mutation is allowed, but prefer snapshots/checkpoints
+// when you need reproducible restore flows.
+session.messages.push({ role: 'assistant', content: 'Synthetic entry' })
 ```
 
 ## 🤖 Agent Configuration
@@ -416,7 +479,9 @@ interface AgentOptions {
 agent.setModel({ provider: 'openai', modelId: 'gpt-4o-mini' })
 
 // Switch to another concrete model client instance
-const otherModelClient = createModel({ adapter: createOpenAIAdapter({ defaultModelId: 'gpt-4o' }) })
+const otherModelClient = createModel({
+  adapter: createOpenAIAdapter({ defaultModelId: 'gpt-4o' }),
+})
 agent.setModel(otherModelClient)
 ```
 
@@ -443,21 +508,22 @@ await sessionManager.destroy('session-id')
 
 GoatChain SDK exports the following built-in tools:
 
-| Tool Class | Runtime Name | Category | Purpose |
-| --- | --- | --- | --- |
-| `ReadTool` | `Read` | File | Read file content (text, binary metadata, and selected converted formats) |
-| `WriteTool` | `Write` | File | Create or overwrite files |
-| `EditTool` | `Edit` | File | In-place text replacement edits |
-| `GlobTool` | `Glob` | File/Search | Find files by glob pattern |
-| `GrepTool` | `Grep` | File/Search | Search file contents by pattern |
-| `BashTool` | `Bash` | Command | Execute shell commands |
-| `WebSearchTool` | `WebSearch` | Web | Search the web (e.g. via Serper API) |
-| `WebFetchTool` | `WebFetch` | Web | Fetch and extract content from a specific URL |
-| `TodoWriteTool` | `TodoWrite` | Planning | Manage structured todo lists |
-| `TodoPlanTool` | `TodoPlan` | Planning | Create/update planning todos for plan flows |
-| `AskUserTool` | `AskUserQuestion` | Interaction | Ask the user structured follow-up questions |
-| `EnterPlanModeTool` | `EnterPlanMode` | Mode | Enter plan mode |
-| `ExitPlanModeTool` | `ExitPlanMode` | Mode | Exit plan mode |
+| Tool Class          | Runtime Name      | Category    | Purpose                                                                   |
+| ------------------- | ----------------- | ----------- | ------------------------------------------------------------------------- |
+| `ReadTool`          | `Read`            | File        | Read file content (text, binary metadata, and selected converted formats) |
+| `WriteTool`         | `Write`           | File        | Create or overwrite files                                                 |
+| `EditTool`          | `Edit`            | File        | In-place text replacement edits                                           |
+| `GlobTool`          | `Glob`            | File/Search | Find files by glob pattern                                                |
+| `GrepTool`          | `Grep`            | File/Search | Search file contents by pattern                                           |
+| `BashTool`          | `Bash`            | Command     | Execute shell commands                                                    |
+| `WebSearchTool`     | `WebSearch`       | Web         | Search the web (e.g. via Serper API)                                      |
+| `WebFetchTool`      | `WebFetch`        | Web         | Fetch and extract content from a specific URL                             |
+| `TaskTool`          | `Task`            | Subagent    | Run a registered subagent task (for example Explore)                      |
+| `TodoWriteTool`     | `TodoWrite`       | Planning    | Manage structured todo lists                                              |
+| `TodoPlanTool`      | `TodoPlan`        | Planning    | Create/update planning todos for plan flows                               |
+| `AskUserTool`       | `AskUserQuestion` | Interaction | Ask the user structured follow-up questions                               |
+| `EnterPlanModeTool` | `EnterPlanMode`   | Mode        | Enter plan mode                                                           |
+| `ExitPlanModeTool`  | `ExitPlanMode`    | Mode        | Exit plan mode                                                            |
 
 ```typescript
 import {
@@ -560,14 +626,14 @@ tools.register(
 
 **How each file tool uses `cwd`:**
 
-| Tool | What it does | How `cwd` is applied | Per-call override | Extra sandbox options |
-| --- | --- | --- | --- | --- |
-| `ReadTool` | Reads files (and some converted formats) | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
-| `WriteTool` | Writes/overwrites files | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
-| `EditTool` | Replaces `old_string` with `new_string` in a file | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `fileBlacklist`, `disableBlacklist` |
-| `GlobTool` | Finds files by pattern | Search root defaults to `cwd` | `path` argument can change search root | `fileBlacklist`, `disableBlacklist` |
-| `GrepTool` | Searches text content in files | Search runs under `cwd` | `path` argument narrows search scope | `fileBlacklist`, `disableBlacklist` |
-| `BashTool` | Runs shell commands | Commands execute in `cwd` | `workdir` argument overrides per call | None |
+| Tool        | What it does                                      | How `cwd` is applied                     | Per-call override                      | Extra sandbox options                                   |
+| ----------- | ------------------------------------------------- | ---------------------------------------- | -------------------------------------- | ------------------------------------------------------- |
+| `ReadTool`  | Reads files (and some converted formats)          | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
+| `WriteTool` | Writes/overwrites files                           | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
+| `EditTool`  | Replaces `old_string` with `new_string` in a file | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `fileBlacklist`, `disableBlacklist`                     |
+| `GlobTool`  | Finds files by pattern                            | Search root defaults to `cwd`            | `path` argument can change search root | `fileBlacklist`, `disableBlacklist`                     |
+| `GrepTool`  | Searches text content in files                    | Search runs under `cwd`                  | `path` argument narrows search scope   | `fileBlacklist`, `disableBlacklist`                     |
+| `BashTool`  | Runs shell commands                               | Commands execute in `cwd`                | `workdir` argument overrides per call  | None                                                    |
 
 **Directory & Protection Options:**
 
@@ -677,23 +743,63 @@ interface AgentHooks {
   sessionStart?: (ctx: SessionStartContext) => Promise<void>
   sessionEnd?: (ctx: SessionEndContext) => Promise<void>
   stop?: (ctx: StopContext) => Promise<void>
-  userPromptSubmit?: (ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>
+  userPromptSubmit?:
+    | ((ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>)
+    | PromptHookEntry
+    | Array<
+        | ((ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>)
+        | PromptHookEntry
+      >
 
   // Tool lifecycle
   // - Can modify tool call with modifiedToolCall
-  preToolUse?: (ctx: ToolHookContext) => Promise<PreToolUseResult | void>
-  permissionRequest?: (ctx: ToolHookContext) => Promise<PermissionRequestResult>
-  postToolUse?: (ctx: ToolHookContext, result: unknown) => Promise<void>
-  postToolUseFailure?: (ctx: ToolHookContext, error: Error) => Promise<void>
+  preToolUse?:
+    | ((ctx: ToolHookContext) => Promise<PreToolUseResult | void>)
+    | PromptHookEntry
+    | Array<
+        | ((ctx: ToolHookContext) => Promise<PreToolUseResult | void>)
+        | PromptHookEntry
+      >
+  permissionRequest?:
+    | ((ctx: ToolHookContext) => Promise<PermissionRequestResult>)
+    | PromptHookEntry
+    | Array<
+        | ((ctx: ToolHookContext) => Promise<PermissionRequestResult>)
+        | PromptHookEntry
+      >
+  postToolUse?:
+    | ((ctx: ToolHookContext, result: unknown) => Promise<void>)
+    | PromptHookEntry
+    | Array<
+        | ((ctx: ToolHookContext, result: unknown) => Promise<void>)
+        | PromptHookEntry
+      >
+  postToolUseFailure?:
+    | ((ctx: ToolHookContext, error: Error) => Promise<void>)
+    | PromptHookEntry
+    | Array<
+        | ((ctx: ToolHookContext, error: Error) => Promise<void>)
+        | PromptHookEntry
+      >
 
   // Subagent lifecycle (used by parallel task/subagent middleware)
   subagentStart?: (ctx: SubagentStartContext) => Promise<void>
-  subagentStop?: (ctx: SubagentStopContext) => Promise<void>
+  subagentStop?:
+    | ((ctx: SubagentStopContext) => Promise<void>)
+    | PromptHookEntry
+    | Array<((ctx: SubagentStopContext) => Promise<void>) | PromptHookEntry>
 }
 
 // Backward-compatible alias
 type ToolHooks = AgentHooks
 
+interface PromptHookEntry {
+  type: 'prompt'
+  prompt: string // use $ARGUMENTS to inject serialized input
+  model?: { provider: string; modelId: string }
+  timeoutMs?: number // default: 30000
+}
+
 interface BaseHookContext {
   sessionId: string
 }
@@ -782,6 +888,113 @@ interface SubagentStopContext extends BaseHookContext {
 }
 ```
 
+### Prompt Hook Evaluation
+
+Prompt hooks are evaluation-only in current SDK behavior:
+
+- Prompt evaluation does not change execution decisions or mutate input/tool calls
+- Supported prompt hooks: `userPromptSubmit`, `preToolUse`, `permissionRequest`, `postToolUse`, `postToolUseFailure`, `subagentStop`
+- `permissionRequest` prompt evaluation only runs when the approval path is entered
+- Each evaluation is persisted in `session.metadata._hookEvaluations`
+
+Prompt evaluation emits `hook_evaluation` stream events with `phase`:
+
+- `start`
+- `stream` (text delta)
+- `end` (status/result/error)
+
+`hook_evaluation` event shape:
+
+```typescript
+interface HookEvaluationEvent extends BaseEvent {
+  type: 'hook_evaluation'
+  evaluationId: string
+  hookName:
+    | 'permissionRequest'
+    | 'preToolUse'
+    | 'postToolUse'
+    | 'postToolUseFailure'
+    | 'subagentStop'
+    | 'userPromptSubmit'
+  phase: 'start' | 'stream' | 'end'
+  prompt?: string
+  input?: unknown
+  delta?: string
+  rawResponse?: string
+  result?: unknown
+  usage?: Usage
+  durationMs?: number
+  status?: 'success' | 'error' | 'timeout'
+  error?: { code?: string; message: string }
+  toolCallId?: string
+}
+```
+
+Metadata persistence shape:
+
+```typescript
+session.metadata._hookEvaluations = {
+  preToolUse: [
+    {
+      evaluationId: '...',
+      timestamp: 1730000000000,
+      hookName: 'preToolUse',
+      prompt: '...',
+      input: { ... },
+      status: 'success',
+      durationMs: 120,
+      rawResponse: '{"ok":true}',
+      result: { ok: true },
+      usage: { promptTokens: 100, completionTokens: 20, totalTokens: 120 },
+      toolCallId: 'call_123',
+    },
+  ],
+}
+```
+
+Complete prompt hook example (function hook + prompt hook + event handling):
+
+```typescript
+import { Agent } from 'goatchain'
+import type { HookEvaluationEvent } from 'goatchain'
+
+const session = await agent.createSession({
+  hooks: {
+    preToolUse: [
+      async (ctx) => {
+        // normal behavior hook
+        return undefined
+      },
+      {
+        type: 'prompt',
+        prompt: 'Analyze this tool call: $ARGUMENTS',
+      },
+    ],
+    permissionRequest: {
+      type: 'prompt',
+      prompt: 'Review approval context: $ARGUMENTS',
+    },
+  },
+})
+
+session.send('Do the task', {
+  toolContext: {
+    approval: { strategy: 'high_risk' },
+  },
+})
+
+for await (const event of session.receive()) {
+  if (event.type === 'hook_evaluation') {
+    const ev = event as HookEvaluationEvent
+    if (ev.phase === 'end') {
+      console.log('hook evaluation done:', ev.hookName, ev.status, ev.result)
+    }
+  }
+}
+
+console.log(session.metadata?._hookEvaluations)
+```
+
 ### Hook Execution Order
 
 Typical order in one run:
@@ -804,7 +1017,12 @@ const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
-  tools: new ToolRegistry().register(new ReadTool()).register(new WriteTool()),
+  tools: (() => {
+    const tools = new ToolRegistry()
+    tools.register(new ReadTool())
+    tools.register(new WriteTool())
+    return tools
+  })(),
 })
 
 // Create session with hooks
@@ -1039,7 +1257,7 @@ const session = await agent.createSession({
 
 ### Tool Context
 
-The `toolContext` parameter in `send()` and `receive()` allows passing additional context:
+The `toolContext` parameter in `send()` and `receive()` is used for approval state and AskUser resume data:
 
 ```typescript
 session.send('Do something risky', {
@@ -1052,8 +1270,14 @@ session.send('Do something risky', {
         tool_call_id_456: { approved: false, reason: 'Too dangerous' },
       },
     },
-    // Your custom context
-    custom: { userId: '123', environment: 'production' },
+    askUser: {
+      answers: {
+        tool_call_id_789: {
+          framework: 'React',
+          styling: 'Tailwind CSS',
+        },
+      },
+    },
   },
 })
 ```
@@ -1070,7 +1294,7 @@ outer:before → inner:before → exec (model.stream) → inner:after → outer:
 
 ```typescript
 // Add named middleware (recommended)
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
 
@@ -1087,7 +1311,7 @@ agent.removeMiddleware('logging')
 console.log(agent.middlewareNames) // ['logging', 'compression', ...]
 
 // Use unsubscribe function
-const unsubscribe = agent.use(middleware, 'temp')
+const unsubscribe = await agent.use(middleware, 'temp')
 unsubscribe() // Remove middleware
 ```
 
@@ -1101,10 +1325,10 @@ Adds planning phase before execution:
 import { createPlanModeMiddleware } from 'goatchain'
 
 // Automatically named 'plan_mode'
-agent.use(createPlanModeMiddleware())
+await agent.use(createPlanModeMiddleware())
 
 // With custom configuration
-agent.use(
+await agent.use(
   createPlanModeMiddleware({
     name: 'my-plan', // Custom name
     planPrompt: 'Create a detailed plan...', // Custom prompt
@@ -1114,35 +1338,36 @@ agent.use(
 
 #### Context Compression Middleware
 
-Automatically compresses context when token limit is reached using a two-stage strategy:
+Automatically compresses context from the full raw transcript when the prompt approaches the model context window. The middleware now:
+
+- reuses any persisted rolling summary first
+- removes old `tool` messages before touching the current round
+- preserves the last user round
+- performs at most one AI summary pass per overflow event
+- guarantees the final prompt stays within `contextLength` or fails locally before the model call
+- can emit per-stage snapshots in the large E2E example for inspection
 
 ```typescript
 import { createContextCompressionMiddleware } from 'goatchain'
 
 // Automatically named 'context_compression'
-agent.use(
+await agent.use(
   createContextCompressionMiddleware({
-    maxTokens: 128000,
-    protectedTurns: 2, // Keep last 2 conversation turns
-    model: model,
-    stateStore: agent.stateStore,
-    toolCompressionTarget: 0.45, // Compress to 45% of maxTokens
-    minKeepToolResults: 5, // Keep last 5 tool results
-    // Optional: Enable detailed logging
-    enableLogging: true,
-    logFilePath: 'compression-logs.jsonl',
+    contextLength: 128000,
   }),
 )
 ```
 
-See [Context Compression Logging Guide](./docs/context-compression-logging.md) for details on monitoring compression behavior.
+The large E2E example writes `round-N/stage1.json` through `stage4.json` under `examples/output/context-compression-large-e2e/` by default, so you can inspect each compression step directly.
+
+See [`src/spec/middleware.md`](./src/spec/middleware.md) for the full middleware and compression spec.
 
 ### Custom Middleware Examples
 
 #### Logging Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   console.log(`Iteration ${state.iteration}:`, {
     messages: state.messages.length,
     pendingTools: state.pendingToolCalls.length,
@@ -1162,7 +1387,7 @@ agent.use(async (state, next) => {
 #### Error Handling Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   try {
     return await next(state)
   } catch (error) {
@@ -1182,7 +1407,7 @@ import { RateLimiter } from 'some-rate-limiter'
 
 const limiter = new RateLimiter({ requestsPerMinute: 60 })
 
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   await limiter.acquire()
   return next(state)
 }, 'rate-limiter')
@@ -1191,7 +1416,7 @@ agent.use(async (state, next) => {
 #### Custom Retry Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   let retries = 3
 
   while (retries > 0) {
@@ -1221,10 +1446,12 @@ interface AgentLoopState {
   iteration: number // Current iteration number
   pendingToolCalls: ToolCallWithResult[] // Pending tool executions
   currentResponse: string // Current LLM response
+  currentThinking?: string // Current reasoning content, if the model emits it
   shouldContinue: boolean // Whether to continue loop
   stopReason?: string // Reason for stopping
-  usage?: Usage // Token usage
+  usage: Usage // Cumulative token usage
   error?: Error // Error if any
+  metadata: Record<string, unknown> // Middleware/hook shared runtime data
 }
 ```
 
@@ -1347,8 +1574,15 @@ Implement custom state stores:
 interface StateStore {
   deleteOnComplete: boolean
 
+  save<T>(sessionId: string, key: string, data: T): Promise<void>
+  load<T>(sessionId: string, key: string): Promise<T | undefined>
+  delete(sessionId: string, key: string): Promise<void>
+  listKeys(sessionId: string): Promise<string[]>
+  listSessions(): Promise<string[]>
+
+  // Checkpoint helpers
   saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>
-  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | null>
+  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>
   deleteCheckpoint(sessionId: string): Promise<void>
   listCheckpoints(): Promise<AgentLoopCheckpoint[]>
 }
@@ -1366,17 +1600,8 @@ interface AgentLoopCheckpoint {
 ### Manual Checkpoint Management
 
 ```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
+// Prefer SDK-managed checkpoints during session.receive().
+// You can still inspect or clean them up manually:
 const checkpoint = await stateStore.loadCheckpoint('session-id')
 
 // List all checkpoints
@@ -1456,7 +1681,7 @@ 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}`)
+    console.log(`\nCalling: ${event.toolName}`)
   } else if (event.type === 'tool_result') {
     console.log(`Result: ${JSON.stringify(event.result).slice(0, 100)}...`)
   }
@@ -1537,7 +1762,7 @@ const agent = new Agent({
 })
 
 // Add logging middleware
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   console.log(`\n=== Iteration ${state.iteration} ===`)
   const result = await next(state)
   console.log(`Tokens used: ${result.usage?.totalTokens || 0}`)
@@ -1545,7 +1770,7 @@ agent.use(async (state, next) => {
 }, 'logger')
 
 // Add plan mode
-agent.use(createPlanModeMiddleware())
+await agent.use(createPlanModeMiddleware())
 
 const session = await agent.createSession()
 session.send('Create a todo list app with React and TypeScript')
@@ -1611,7 +1836,12 @@ import {
   Agent,
   createModel,
   createOpenAIAdapter,
-  createBuiltinTools,
+  ToolRegistry,
+  ReadTool,
+  WriteTool,
+  EditTool,
+  GlobTool,
+  GrepTool,
 } from 'goatchain'
 
 const model = createModel({
@@ -1621,11 +1851,18 @@ const model = createModel({
   }),
 })
 
+const tools = new ToolRegistry()
+tools.register(new ReadTool())
+tools.register(new WriteTool())
+tools.register(new EditTool())
+tools.register(new GlobTool())
+tools.register(new GrepTool())
+
 const agent = new Agent({
   name: 'File Agent',
   systemPrompt: 'You are a file management assistant.',
   model,
-  tools: createBuiltinTools(), // All file tools included
+  tools,
 })
 
 // Set working directory at session creation
@@ -1732,7 +1969,7 @@ 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(`\n[Tool] ${event.name}`)
+    console.log(`\n[Tool] ${event.toolName}`)
   }
 }
 ```
@@ -1824,12 +2061,39 @@ agent.setModel({ provider: 'openai', modelId: 'gpt-4o-mini' })
 
 #### Methods
 
-**`send(input): void`**
+**`send(input, options?): string`**
 
-Send a message to the session.
+Enqueue a message and return its queue message ID.
 
 ```typescript
-session.send('Hello!')
+const id = session.send('Hello!')
+```
+
+**`sendBatch(messages): string[]`**
+
+Batch enqueue messages and return queue message IDs.
+
+```typescript
+const ids = session.sendBatch([
+  { input: 'task-1', priority: 1 },
+  { input: 'task-2', priority: 2 },
+])
+```
+
+**`cancelQueuedMessage(messageId): boolean`**
+
+Cancel a queued message by ID.
+
+```typescript
+session.cancelQueuedMessage(id)
+```
+
+**`getQueueStatus(): MessageQueueStatus`**
+
+Query queue length, preview list, processing status, and config.
+
+```typescript
+console.log(session.getQueueStatus())
 ```
 
 **`receive(options?): AsyncGenerator<AgentEvent>`**
@@ -1894,7 +2158,7 @@ session.setCwd('/path/to/project')
 #### Properties
 
 - `id: string` - Session ID
-- `status: SessionStatus` - Session status ('idle' | 'running' | 'completed' | 'error')
+- `status: SessionStatus` - Session status (`'active' | 'paused' | 'completed' | 'error' | 'archived'`)
 - `messages: Message[]` - Message history
 - `usage: Usage` - Token usage statistics
 - `createdAt: number` - Creation timestamp
@@ -1905,9 +2169,12 @@ session.setCwd('/path/to/project')
 ```typescript
 interface Message {
   role: 'system' | 'user' | 'assistant' | 'tool'
-  content: string | ToolCall[] | ToolResult[]
-  name?: string // For tool messages
-  toolCallId?: string // For tool messages
+  content: MessageContent
+  reasoning_content?: string // Assistant messages
+  tool_calls?: ToolCall[] // Assistant messages
+  tool_call_id?: string // Tool messages
+  name?: string
+  isError?: boolean // Tool messages
 }
 ```
 
@@ -1925,10 +2192,17 @@ interface Usage {
 
 ```typescript
 type AgentEvent =
+  | TextStartEvent
   | TextDeltaEvent
+  | TextEndEvent
   | ToolCallStartEvent
   | ToolCallDeltaEvent
   | ToolCallEndEvent
+  | ToolOutputStartEvent
+  | ToolOutputDeltaEvent
+  | ToolApprovalRequestedEvent
+  | RequiresActionEvent
+  | ToolSkippedEvent
   | ToolResultEvent
   | ThinkingStartEvent
   | ThinkingDeltaEvent
@@ -1936,7 +2210,6 @@ type AgentEvent =
   | IterationStartEvent
   | IterationEndEvent
   | DoneEvent
-  | ErrorEvent
 
 interface TextDeltaEvent {
   type: 'text_delta'
@@ -1945,8 +2218,15 @@ interface TextDeltaEvent {
 
 interface ToolCallStartEvent {
   type: 'tool_call_start'
-  id: string
-  name: string
+  callId: string
+  toolName?: string
+}
+
+interface RequiresActionEvent {
+  type: 'requires_action'
+  kind: 'tool_approval' | 'ask_user'
+  checkpoint?: AgentLoopCheckpoint
+  checkpointRef?: { sessionId: string }
 }
 
 interface ToolResultEvent {
@@ -1958,6 +2238,7 @@ interface ToolResultEvent {
 
 interface DoneEvent {
   type: 'done'
+  finalResponse?: string
   stopReason:
     | 'max_iterations'
     | 'final_response'
@@ -1965,6 +2246,13 @@ interface DoneEvent {
     | 'cancelled'
     | 'approval_required'
     | 'max_follow_ups'
+  modelStopReason?: 'tool_call' | 'final' | 'length' | 'error' | 'cancelled'
+  error?: {
+    code?: string
+    message: string
+    status?: number
+    retryable?: boolean
+  }
   usage?: Usage
 }
 ```
@@ -2023,7 +2311,7 @@ classDiagram
         +status: SessionStatus
         +messages: Message[]
         +usage: Usage
-        +send(input): void
+        +send(input, options?): string
         +receive(): AsyncGenerator~AgentEvent~
         +save(): Promise~void~
     }
@@ -2075,7 +2363,13 @@ See [docs/cli.md](./docs/cli.md) and [docs/server.md](./docs/server.md) for deta
 Expose DimCode as an Agent Client Protocol server for editor integrations:
 
 ```bash
-bun run acp-server
+dim acp
+```
+
+For source checkouts, use a cwd-independent command:
+
+```bash
+node /absolute/path/to/GoatChain/scripts/acpx-agent.mjs
 ```
 
 **Configuration for Zed** (`settings.json`):
@@ -2084,13 +2378,16 @@ bun run acp-server
 {
   "agent_servers": {
     "dimcode": {
-      "command": "pnpm",
-      "args": ["--dir", "/path/to/DimCode", "acp-server"]
+      "command": "/absolute/path/to/dim",
+      "args": ["acp"]
     }
   }
 }
 ```
 
+For OpenClaw `acpx`, use either `/absolute/path/to/dim acp` or `node /absolute/path/to/GoatChain/scripts/acpx-agent.mjs`.
+Do not use `bun run acp-server` there; it depends on the launcher cwd being the GoatChain repo root.
+
 See [docs/acp-server.md](./docs/acp-server.md) for details.
 
 ## 📚 Documentation