@turmind/halo 1.5.4 → 1.5.6

package/bundled-docs/dev/add-model-provider.md

@@ -19,14 +19,14 @@ Total effort: typically a few hours depending on how weird the upstream API is a
 | Provider ID | Class | File | Notes |
 |---|---|---|---|
 | `aws-bedrock-claude-invoke` | `BedrockAgent` | `bedrock-agent.ts` | Anthropic Messages API via AWS SDK |
-| `kimi` | `KimiAgent` | `kimi-agent.ts` | OpenAI-compatible, streaming via `fetchChatCompletionStream` (usage arrives in its own `choices: []` chunk), thinking (reasoning_content). Two API generations, branched on modelId: **K3** — vision (base64 data URLs only, no public-URL input), thinking always-on server-side, sole knob is top-level `reasoning_effort` (enum currently just `"max"`); **K2.6** — no vision, no `reasoning_effort` field at all, only the `thinking:{type:'enabled'|'disabled'}` toggle. Never send the K2.x `thinking` parameter to K3 |
+| `kimi` | `KimiAgent` | `kimi-agent.ts` | OpenAI-compatible, streaming via `fetchChatCompletionStream` (usage arrives in its own `choices: []` chunk), thinking (reasoning_content). Cached tokens via `cachedPromptTokens` (every known usage key — which one Kimi reports isn't pinned). Two API generations, branched on modelId: **K3** — vision (base64 data URLs only, no public-URL input), thinking always-on server-side, sole knob is top-level `reasoning_effort` (enum currently just `"max"`); **K2.6** — no vision, no `reasoning_effort` field at all, only the `thinking:{type:'enabled'|'disabled'}` toggle. Never send the K2.x `thinking` parameter to K3 |
 | `deepseek` | `DeepSeekAgent` | `deepseek-agent.ts` | OpenAI-compatible, streaming via `fetchChatCompletionStream` (first chunk has `content: null` + `reasoning_content: ''`; the usage chunk still carries `choices`), thinking (reasoning_content). Vision per model: `deepseek-flash` (V4.1-Flash) sees `image_url` data URLs; `deepseek-v4-pro` accepts the block but ignores it (live-probed 2026-09-24 with a 64×64 blue PNG) — registry `image` flag gates it |
 | `minimax` | `MiniMaxAgent` | `minimax-agent.ts` | Anthropic Messages API (x-api-key), streaming via `fetchAnthropicStream` — note `message_start.usage` is all zeros and the real input / cache counts arrive in `message_delta.usage` (the accumulator takes them from there). Two thinking schemes, branched on registry `thinking.mode`: **M3** (default) — vision, thinking off by default and enabled via `thinking:{type:'adaptive'}` (no levels, no budget_tokens), no `promptCaching` in the manifest on purpose (official docs scope `cache_control` to M2.x only; M3 has passive automatic caching); **M2.7** — no vision, thinking always-on (manual budget_tokens), prompt caching (5m, M2.7 doesn't report cache_creation_input_tokens) |
 | `qwen` | `QwenAgent` | `qwen-agent.ts` | Aliyun Bailian Anthropic-compatible API, streaming via `fetchAnthropicStream` (SSE frames come as `data:{…}` with no space after the colon — the reader accepts both), thinking enable/disable both honored, prompt caching (5m only), vision on Plus, max no vision |
 | `hunyuan` | `HunyuanAgent` | `hunyuan-agent.ts` | Tencent Hy3 preview via OpenAI-compatible (tokenhub.tencentmaas.com), streaming via `fetchChatCompletionStream` (`stream_options.include_usage` accepted; usage in its own `choices: []` chunk), reasoning_effort low/high (no_think = omit), automatic prompt caching (cached_tokens), no vision |
 | `doubao` | `DoubaoAgent` | `doubao-agent.ts` | ByteDance Doubao Seed-2.0 (pro/lite/mini/code) on Volcengine Ark, OpenAI-compatible, streaming via `fetchChatCompletionStream` (usage in its own `choices: []` chunk) + `thinking:{type:'enabled'/'disabled'}` (no `auto`), automatic prompt caching, no vision |
 | `zhipu` | `ZhipuAgent` | `zhipu-agent.ts` | Zhipu GLM-5.x on open.bigmodel.cn, OpenAI-compatible, streaming via `fetchChatCompletionStream` (tool-call arguments arrive complete in one fragment; usage chunk carries `choices`). Output cap via `max_tokens` only (`max_completion_tokens` is silently ignored). Thinking branched on modelId: **glm-5.3\*** always thinks — always sends `thinking:{type:'enabled',clear_thinking:false}`, `reasoning_effort` only when low/high/max (`disabled` / other efforts 400); other ids (glm-5.2) honour `thinking:{type:'disabled'}`. Vision per model: `glm-5.3-flash` / `glm-5.3-flashx` see `image_url` data URLs; `glm-5.3` / `glm-5.2` are text-only and 400 on any image part (code 1210, classified `multimodal_4xx` so leftover history images degrade). Automatic caching, `prompt_tokens_details.cached_tokens` (included in `prompt_tokens`, subtracted). |
-| `openai` | `OpenAIAgent` | `openai-agent.ts` | **Generic OpenAI-compatible**. Use for native OpenAI or any third-party OpenAI gateway (incl. Ollama / llama.cpp). User fills endpoint + model id; capabilities openly editable in the form. Streaming via `fetchChatCompletionStream` — always sends `stream: true` + `stream_options: { include_usage: true }` (OpenAI's own field; Ollama ≥ 0.3 / vLLM / LM Studio accept it too). A gateway that rejects unknown fields would 400 — accepted trade-off, no non-streaming fallback. Forgiving about cache field names (`prompt_tokens_details.cached_tokens`, `prompt_cache_hit_tokens`, `cache_read_tokens` all read) and reasoning field names (`reasoning_content` for OpenAI o-series/DeepSeek, `reasoning` for Ollama/llama.cpp). |
+| `openai` | `OpenAIAgent` | `openai-agent.ts` | **Generic OpenAI-compatible**. Use for native OpenAI or any third-party OpenAI gateway (incl. Ollama / llama.cpp). User fills endpoint + model id; capabilities openly editable in the form. Streaming via `fetchChatCompletionStream` — always sends `stream: true` + `stream_options: { include_usage: true }` (OpenAI's own field; Ollama ≥ 0.3 / vLLM / LM Studio accept it too). A gateway that rejects unknown fields would 400 — accepted trade-off, no non-streaming fallback. Forgiving about cache field names (`cachedPromptTokens`: first value > 0 of `prompt_tokens_details.cached_tokens`, top-level `cached_tokens`, `prompt_cache_hit_tokens`, `cache_read_tokens`) and reasoning field names (`reasoning_content` for OpenAI o-series/DeepSeek, `reasoning` for Ollama/llama.cpp). |
 | `anthropic` | `AnthropicAgent` | `anthropic-agent.ts` | **Generic Anthropic Messages**. Use for api.anthropic.com or any Anthropic-compatible gateway. User fills endpoint + model id. Streaming via `fetchAnthropicStream` (the gateway must support `stream: true` SSE — the reference Anthropic behaviour). Standard `cache_control: ephemeral` with optional `ttl: '1h'`. |
 | `mimo-token-plan-china` | `AnthropicAgent` | (reuses `anthropic-agent.ts`) | Xiaomi MiMo (UI name "Xiaomi MiMo"; the id keeps its historical name so existing configs don't break) — Anthropic-compatible gateway, streams like `anthropic` (gateway built for Claude Code, which always streams; not live-probed); no dedicated class, just a default endpoint in `model-runtime.ts` (`token-plan-cn.xiaomimimo.com/anthropic`). The key type picks the endpoint: Token Plan `tp-`/`ttp-` keys only work on `token-plan-{cn,sgp,ams}.xiaomimimo.com/anthropic`, pay-as-you-go `sk-` keys only on `api.xiaomimimo.com/anthropic` — all four ship as `endpointPresets` (pay-as-you-go live-probed 2026-09-24; sgp / ams from the docs only). V2.6 (`mimo-v2.6-pro` / `-flash`, both vision, 1M / 131072) is current; `mimo-v2.5(-pro)` kept in the template until the official 2026-10-21 deprecation, then drop |
 | `aws-bedrock-mantle` | `MantleAgent` | `mantle-agent.ts` | OpenAI GPT-6.1 Sol, GPT-6 (Astra / Sol / Luna) and GPT-5.6 (Sol / Terra / Luna) on Amazon Bedrock via the **OpenAI Responses API** (not Completions/Converse/InvokeModel). Vision, reasoning via `reasoning.effort` (low/med/high/xhigh/max, no budget_tokens; on 5.6 `max` is accepted live but absent from the model's own validation list — measured ~6% more reasoning_tokens than xhigh; on Astra it's on the official list), `text.verbosity` (low/medium/high, same on both generations). **Region split** (live-probed 2026-09-24): us-east-1 serves GPT-6.1 Sol + GPT-6 Sol / Luna + every 5.6 model (404s Astra; GPT-6.1 Sol probed 2026-09-30, us-east-1 only); us-east-2 serves only the 5.6 trio; us-west-2 serves Astra + 5.6 Terra / Luna. Template ships all three as `endpointPresets`, default is now us-east-1 (`openai.gpt-6-sol` default model); Astra agents pick us-west-2 in the form; `extractRegionFromHost` falls back to us-east-1. All GPT-6 variants: 1,050,000 context / 128,000 max output, same effort (none/low/medium/high/xhigh/max) + verbosity surface; input beyond 272K tokens bills at 2x, so cap `context.maxTokens` in agent.yaml unless that's intended. Never surfaces reasoning summaries — `output[].reasoning.summary` stays empty even with `reasoning.summary=detailed` while `reasoning_tokens` counts up (verified live), so no thinking text in the UI is upstream behavior, not a parsing gap. Streams (`stream: true`, Responses API SSE folded by `readResponsesStream` in the same file): `response.output_text.delta` frames go out live, the terminal `response.completed` / `response.incomplete` frame carries the full final response object; this host sends **no** `data: [DONE]` (live-probed 2026-09-29). |
@@ -57,7 +57,7 @@ export interface ModelRuntime {
 }
 ```
 
-`AgentLoop` handles the tool execution loop (call model → execute tools → loop). You only implement `callModel(signal, onDelta?)` — the provider-specific API call. It always returns a `Promise<ModelCallResult>` containing the complete response; the base class `run()` method yields events per loop iteration. **Streaming is optional and per-provider**: if the upstream API streams, call `onDelta({ type: 'text_delta' | 'thinking_delta', text })` per chunk as it arrives — the loop yields those as `text_delta` / `thinking_delta` events during the call and re-arms the per-call timeout on each (so it becomes an idle timeout) — then still return the whole result. For data that arrives but has nothing to show (ping events, tool-argument fragments, empty reasoning chunks, SSE comment frames) call `onDelta(ACTIVITY_DELTA)` (exported from `agent-loop.ts`; `type: 'activity'`, empty text): it only re-arms the idle timer and never reaches the event stream, so a long tool-call argument or a silent reasoning stretch doesn't trip the idle timeout. The shared readers do this for you — `readSseJson`'s per-chunk callback is wired to it in `fetchAnthropicStream` / `fetchChatCompletionStream` / `readResponsesStream`, and the Bedrock agent reports it once per stream event. A non-streaming provider would simply ignore `onDelta`; today every built-in provider streams — Bedrock, the Anthropic-Messages providers (anthropic / mimo / minimax / qwen), the OpenAI-family (openai / deepseek / kimi / zhipu / doubao / hunyuan) and Mantle (aws-bedrock-mantle / aws-bedrock-openai). The fold from Anthropic stream events into a `ModelCallResult` lives in `anthropic-stream.ts` (`AnthropicStreamAccumulator`); for an HTTP gateway speaking Anthropic Messages, `fetchAnthropicStream({ url, headers, body, signal, onDelta, tag })` in the same file is the whole `callModel` body — it posts with `stream: true`, parses the SSE with the generic `readSseJson` reader in `sse.ts` (also skips the OpenAI `[DONE]` terminator), maps a mid-stream `event: error` frame onto the `[tag] <status> <type>: <message>` error shape `classifyModelError` parses, and re-throws `AbortError` if the body ended at the abort instant. For an OpenAI-compatible `chat/completions` endpoint, `fetchChatCompletionStream({ url, headers, body, signal, onDelta, tag })` in `openai-chat-stream.ts` is the transport half of `callModel` — it posts with `stream: true` + `stream_options: { include_usage: true }`, folds the `chat.completion.chunk` frames (text / `reasoning_content` (or the Ollama `reasoning` alias) appended and reported via `onDelta`; `tool_calls[]` fragments matched by `index`, the first fragment carrying `id` + `function.name`, later ones appending `function.arguments`; `finish_reason` / `usage` last-non-null-wins — the usage chunk arrives with `choices` on deepseek / zhipu and as `choices: []` on kimi / doubao / hunyuan) back into the non-streaming `choices[0].message` + `finishReason` + `usage` shape, and throws today's `[<Tag>Agent] API error <status>: <body>` on non-2xx — the agent's existing parse / usage code runs unchanged on the folded result. Mantle's Responses API needs no accumulator at all: `readResponsesStream` (module-level in `mantle-agent.ts`) reports `response.output_text.delta` / `response.reasoning_summary_text.delta` live and keeps the `response` object off the terminal `response.completed` / `response.incomplete` frame, which is the full final response in exactly the non-streaming JSON shape — the existing `output[]` / `incomplete_details` / `usage` parse runs on it unchanged; a stream that ends without a terminal frame throws the same `MantleEmptyResponse` marker as the empty-`output[]` glitch so `classifyModelError`'s `empty_response` retry covers both.
+`AgentLoop` handles the tool execution loop (call model → execute tools → loop). You only implement `callModel(signal, onDelta?)` — the provider-specific API call. It always returns a `Promise<ModelCallResult>` containing the complete response; the base class `run()` method yields events per loop iteration. **Streaming is optional and per-provider**: if the upstream API streams, call `onDelta({ type: 'text_delta' | 'thinking_delta', text })` per chunk as it arrives — the loop yields those as `text_delta` / `thinking_delta` events during the call and re-arms the per-call timeout on each (so it becomes an idle timeout) — then still return the whole result. For data that arrives but has nothing to show (ping events, tool-argument fragments, empty reasoning chunks, SSE comment frames) call `onDelta(ACTIVITY_DELTA)` (exported from `agent-loop.ts`; `type: 'activity'`, empty text): it only re-arms the idle timer and never reaches the event stream, so a long tool-call argument or a silent reasoning stretch doesn't trip the idle timeout. The shared readers do this for you — `readSseJson`'s per-chunk callback is wired to it in `fetchAnthropicStream` / `fetchChatCompletionStream` / `readResponsesStream`, and the Bedrock agent reports it once per stream event. A non-streaming provider would simply ignore `onDelta`; today every built-in provider streams — Bedrock, the Anthropic-Messages providers (anthropic / mimo / minimax / qwen), the OpenAI-family (openai / deepseek / kimi / zhipu / doubao / hunyuan) and Mantle (aws-bedrock-mantle / aws-bedrock-openai). The fold from Anthropic stream events into a `ModelCallResult` lives in `anthropic-stream.ts` (`AnthropicStreamAccumulator`); for an HTTP gateway speaking Anthropic Messages, `fetchAnthropicStream({ url, headers, body, signal, onDelta, tag })` in the same file is the whole `callModel` body — it posts with `stream: true`, parses the SSE with the generic `readSseJson` reader in `sse.ts` (also skips the OpenAI `[DONE]` terminator), maps a mid-stream `event: error` frame onto the `[tag] <status> <type>: <message>` error shape `classifyModelError` parses, and re-throws `AbortError` if the body ended at the abort instant. For an OpenAI-compatible `chat/completions` endpoint, `fetchChatCompletionStream({ url, headers, body, signal, onDelta, tag })` in `openai-chat-stream.ts` is the transport half of `callModel` — it posts with `stream: true` + `stream_options: { include_usage: true }`, folds the `chat.completion.chunk` frames (text / `reasoning_content` (or the Ollama `reasoning` alias) appended and reported via `onDelta`; `tool_calls[]` fragments matched by `index`, the first fragment carrying `id` + `function.name`, later ones appending `function.arguments`; `finish_reason` / `usage` last-non-null-wins — the usage chunk arrives with `choices` on deepseek / zhipu and as `choices: []` on kimi / doubao / hunyuan) back into the non-streaming `choices[0].message` + `finishReason` + `usage` shape, and throws today's `[<Tag>Agent] API error <status>: <body>` on non-2xx — `chatCompletionResult(folded, usage, startTime)` in `openai-chat-format.ts` then turns the folded reply into a `ModelCallResult`, with the usage numbers the agent computed itself. Mantle's Responses API needs no accumulator at all: `readResponsesStream` (module-level in `mantle-agent.ts`) reports `response.output_text.delta` / `response.reasoning_summary_text.delta` live and keeps the `response` object off the terminal `response.completed` / `response.incomplete` frame, which is the full final response in exactly the non-streaming JSON shape — the existing `output[]` / `incomplete_details` / `usage` parse runs on it unchanged; a stream that ends without a terminal frame throws the same `MantleEmptyResponse` marker as the empty-`output[]` glitch so `classifyModelError`'s `empty_response` retry covers both.
 
 Two important constraints:
 
@@ -103,39 +103,48 @@ For providers where the API returns `prompt_tokens` inclusive of cached (e.g. Ki
 Create `packages/server/src/agents/<provider>-agent.ts`. Extend `AgentLoop` and implement `callModel()`.
 
 Reference implementations:
-- OpenAI-compatible: [kimi-agent.ts](../../../packages/server/src/agents/kimi-agent.ts), [deepseek-agent.ts](../../../packages/server/src/agents/deepseek-agent.ts)
+- OpenAI-compatible: [kimi-agent.ts](../../../packages/server/src/agents/kimi-agent.ts), [deepseek-agent.ts](../../../packages/server/src/agents/deepseek-agent.ts) — conversion helpers in [openai-chat-format.ts](../../../packages/server/src/agents/openai-chat-format.ts)
+- Anthropic Messages over HTTP: [qwen-agent.ts](../../../packages/server/src/agents/qwen-agent.ts), [minimax-agent.ts](../../../packages/server/src/agents/minimax-agent.ts) — body helpers in [anthropic-request.ts](../../../packages/server/src/agents/anthropic-request.ts)
 - AWS native: [bedrock-agent.ts](../../../packages/server/src/agents/bedrock-agent.ts)
 
-Rough shape for OpenAI-compatible providers:
+Rough shape for OpenAI-compatible providers — the format conversion is shared (`openai-chat-format.ts`); what the class writes itself is the provider's quirks: the request body (output-cap field, thinking / reasoning knobs), the image mode, the usage mapping and the error tag:
 
 ```ts
 import { AgentLoop } from './agent-loop.js'
-import type { ContentBlock, ModelCallResult, ToolDef } from './agent-loop.js'
+import type { ModelCallResult, ModelDelta, ToolDef } from './agent-loop.js'
+import { fetchChatCompletionStream } from './openai-chat-stream.js'
+import { chatCompletionResult, toChatMessages, toChatTools } from './openai-chat-format.js'
 
 export class MyProviderAgent extends AgentLoop {
   constructor(config: MyConfig) { super(config.tools); ... }
 
   protected async callModel(signal, onDelta?): Promise<ModelCallResult> {
     const startTime = Date.now()
-    const messages = this.buildMessages()  // translate AnthropicMessage[] → provider format
-    const tools = this.buildTools()        // translate ToolDef[] → provider format
+    // AnthropicMessage[] → chat messages; image mode = the provider's vision support:
+    // 'parts' (image_url parts) | 'if-image' (parts only when an image is present) | 'drop' (text only)
+    const messages = toChatMessages(this.config.systemPrompt, this.messages, 'parts')
+    const tools = toChatTools(this.config.tools)   // ToolDef[] → OpenAI function calling format
 
-    // call fetchChatCompletionStream({ url, headers, body, signal, onDelta, tag }) from
-    // openai-chat-stream.ts (see kimi-agent.ts) — it POSTs with stream: true, reports
-    // text / reasoning chunks through onDelta and returns the folded { message, finishReason, usage, ttftMs }
-    // Return ModelCallResult with assistantBlocks, stopReason, text, thinking, toolCalls, usage, durationMs, ttftMs
-  }
+    const body = { model, messages, max_tokens /* or max_completion_tokens */, ...(tools.length > 0 ? { tools } : {}) }
+    // + this provider's thinking / reasoning fields
+
+    // POSTs with stream: true, reports text / reasoning chunks through onDelta,
+    // returns the folded { message, finishReason, usage, ttftMs }
+    const folded = await fetchChatCompletionStream({ url, headers, body, signal, onDelta, tag: 'MyProviderAgent' })
 
-  private buildMessages() { ... }  // system + user/assistant/tool message conversion
-  private buildTools() { ... }     // OpenAI function calling format
+    // Per-provider usage math: which field carries cached tokens, how they're deducted.
+    const cached = ...
+    return chatCompletionResult(folded, { inputTokens: prompt - cached, outputTokens, cacheReadInputTokens: cached }, startTime)
+  }
 }
 ```
 
 **Things that bite**:
 
-- **Tool results format.** Anthropic stores tool results as `{ role: 'user', content: [{ type: 'tool_result', ... }] }`. OpenAI-compatible APIs need separate `{ role: 'tool', tool_call_id, content }` messages. See `convertToolResults()` in kimi-agent.ts.
-- **Thinking/reasoning replay.** If the provider returns `reasoning_content` and requires it in follow-up messages (Kimi, DeepSeek with tool calls), you must store it in `result.assistantBlocks` as a `{ type: 'thinking', thinking: '...' }` block and replay it as `reasoning_content` in `convertAssistantMessage()`.
-- **Reasoning field name varies.** OpenAI o-series/DeepSeek emit reasoning in `message.reasoning_content`; Ollama / llama.cpp's OpenAI-compat layer uses `message.reasoning`. `OpenAIAgent` reads both (`reasoning_content ?? reasoning`). A vendor-specific class should read whichever its API uses.
+- **Tool results format.** Anthropic stores tool results as `{ role: 'user', content: [{ type: 'tool_result', ... }] }`. OpenAI-compatible APIs need separate `{ role: 'tool', tool_call_id, content }` messages, and tool-result images ride in a user message right after them. `toChatMessages()` in openai-chat-format.ts does both.
+- **Thinking/reasoning replay.** If the provider returns `reasoning_content` and requires it in follow-up messages (Kimi, DeepSeek with tool calls), it must be stored in `result.assistantBlocks` as a `{ type: 'thinking', thinking: '...' }` block and replayed as `reasoning_content` — `chatCompletionResult()` stores it and `toChatMessages()` replays it.
+- **Reasoning field name varies.** OpenAI o-series/DeepSeek emit reasoning in `message.reasoning_content`; Ollama / llama.cpp's OpenAI-compat layer uses `message.reasoning`. The shared stream accumulator (`ChatCompletionAccumulator` in `openai-chat-stream.ts`) folds both into one reasoning stream (`reasoning_content ?? reasoning`), so every `fetchChatCompletionStream` provider gets it. A vendor-specific class should read whichever its API uses.
+- **Malformed tool arguments.** Parse tool-call arguments with `parseToolInput(json, toolName)` (`tool-input.ts`) — every built-in path does (Anthropic stream accumulator, `chatCompletionResult`, Mantle). It returns `{ input, error? }` and never throws: empty / missing arguments are `{}` with no error; arguments that aren't valid JSON or aren't a plain JSON object (`null`, an array, a scalar) become `{}` plus an `error` and a `[ToolInput]` warn (tool name and the first 200 chars). Pass the error through as `inputError` on the `toolCalls[]` entry (keep `input: {}` in `assistantBlocks`) — the loop then skips that call and returns an `is_error` result asking the model to resend complete JSON, instead of running the tool with `{}`. A `max_tokens` stop never runs any of the reply's tool calls; the loop answers each with an `is_error` result itself.
 - **Cancellation.** The caller passes `signal`; pass it to `fetch()` directly.
 - **Max tokens.** Use `config.maxTokens ?? resolveMaxOutputTokens(config.modelId)` for consistency.
 - **Prompt caching and thinking** are optional per provider. If unsupported, silently ignore.
@@ -336,7 +345,7 @@ myprovider:
 
 ### Effort labels are Halo-side only
 
-`effortPresets: [low, medium, high]` is purely a UI affordance — it lives on the form and gets translated to `budget_tokens` (or whatever the provider wants) inside the agent class via an effort→budget table. Don't write `effort=medium` directly to the wire. Provider doesn't know what `medium` means.
+`effortPresets: [low, medium, high]` is purely a UI affordance — it lives on the form and gets translated to `budget_tokens` (or whatever the provider wants) inside the agent class via an effort→budget table (for the Anthropic-format providers, `effortToBudget()` in `anthropic-request.ts`). Don't write `effort=medium` directly to the wire. Provider doesn't know what `medium` means.
 
 Probe each preset's actual budget against the model's `maxOutputTokens`. We hit this with MiniMax: `low` (1024 budget) caused `stop=max_tokens` before any thinking completed — left it out of the preset list.
 
@@ -378,7 +387,7 @@ The `MantleEmptyResponse` retry guard in session-manager is unrelated to this an
 
 Keeping it a hard-coded switch is deliberate for now:
 - Each provider has enough quirks (auth, response format, tool calling conventions, thinking replay rules) that a generic "provider interface with fetch client" would leak abstractions
-- Each provider independently extends `AgentLoop` — no shared OpenAI-compatible base class, to avoid coupling when APIs diverge; the shared piece is a transport helper function (`fetchChatCompletionStream`, like `fetchAnthropicStream`), not a base class — each agent still owns its body / message conversion / usage mapping
+- Each provider independently extends `AgentLoop` — no shared OpenAI-compatible base class, to avoid coupling when APIs diverge; the shared pieces are helper functions, not a base class — transport (`fetchChatCompletionStream`, `fetchAnthropicStream`) and format (`openai-chat-format.ts`: message / tool / result conversion; `anthropic-request.ts`: system / tools / `cache_control` placement and the thinking-budget math) — each agent still owns its request body, thinking shape, usage mapping and error tag
 - The Agent management UI reads the manifest directly; a runtime-registered plugin would need to notify the frontend dynamically
 - One provider lands every few months, not every week
 
@@ -393,6 +402,8 @@ If / when Halo has 5+ providers and the switch becomes unwieldy, the next step w
 - Bedrock (Anthropic native): [packages/server/src/agents/bedrock-agent.ts](../../../packages/server/src/agents/bedrock-agent.ts)
 - Kimi (OpenAI-compatible + vision): [packages/server/src/agents/kimi-agent.ts](../../../packages/server/src/agents/kimi-agent.ts)
 - DeepSeek (OpenAI-compatible, no vision): [packages/server/src/agents/deepseek-agent.ts](../../../packages/server/src/agents/deepseek-agent.ts)
+- OpenAI-family format helpers: [packages/server/src/agents/openai-chat-format.ts](../../../packages/server/src/agents/openai-chat-format.ts)
+- Anthropic-family body helpers: [packages/server/src/agents/anthropic-request.ts](../../../packages/server/src/agents/anthropic-request.ts)
 - Manifest examples: [packages/server/templates/models/](../../../packages/server/templates/models/)
 - Models registry loader: [packages/server/src/config.ts](../../../packages/server/src/config.ts) (`getModelsRegistry`)
 - Architecture context: [design/architecture.md#modelruntime](../design/architecture.md#modelruntime--llm-interaction-layer-provider-agnostic)

package/bundled-docs/dev/api.md

@@ -105,13 +105,14 @@ Unified session log API — list + read session files across all agents.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/sessions/logs?projectId=` | List session metadata, keyset-paginated. Default returns each top-level row + all descendants (sidebar tree); `rootOnly=1` returns roots only (chat-panel session tabs). Each row carries `status` (`running` also while a sub-session runs). A `projectId` with no `.halo/` (plain or missing directory) returns `{sessions: [], nextCursor: null}` without scaffolding it — a list never turns a directory into a workspace |
+| GET | `/api/sessions/logs?projectId=` | List session metadata, keyset-paginated. Default returns each top-level row + all descendants (sidebar tree); `rootOnly=1` returns roots only (chat-panel session tabs). A `projectId` with no `.halo/` (plain or missing directory) returns `{sessions: [], nextCursor: null}` without scaffolding it — a list never turns a directory into a workspace |
 | GET | `/api/sessions/logs/:id?projectId=` | Full session log (scans across agent dirs) — the **active** file only; archived history is a separate call |
 | GET | `/api/sessions/logs/:id/archive/:n?projectId=` | One archived UI-log segment — see [detail](#get-apisessionslogsidarchivenprojectidabs) |
-| DELETE | `/api/sessions/logs/:id?projectId=` | Delete the session log (and all of its archive segments) |
-| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only) — updates the log file's title and the mirrored `agent_sessions.title`. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
+| DELETE | `/api/sessions/logs/:id?projectId=` | Permanently delete the session and all its descendants — log files (with archive segments) and `agent_sessions` rows. Returns `{ok, deleted}` |
+| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only; body `{title}`) — updates the log file's title and the mirrored `agent_sessions.title`. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
+| GET | `/api/sessions/goal?projectId=` | Legacy goal binding of the workspace (`{goal: {goalSessionId, workerSessionId, status, round, maxRounds} \| null}`); refresh seed for the goal banner, which only shows when `general.goal_mode_enabled` is on |
 
-The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / exchangeCount / parentSessionId / stoppedAt / contextTokens / totalOutputTokens / goalSessionId — the last is a retained legacy field, non-null only on a goal-bound worker row; existing bindings are unchanged), served from the mirrored `agent_sessions` columns rather than by parsing each session file (rows predating the columns are backfilled from the file on first read). The frontend builds the tree from `parentSessionId`.
+The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / exchangeCount / parentSessionId / stoppedAt / archivedAt / contextTokens / totalOutputTokens / status / goalSessionId — the last is a retained legacy field, non-null only on a goal-bound worker row; existing bindings are unchanged), served from the mirrored `agent_sessions` columns rather than by parsing each session file (rows predating the columns are backfilled from the file on first read). The frontend builds the tree from `parentSessionId`.
 
 The get endpoint returns the full session file. If only `rawMessages` is present (no event-log `messages`), `convertRawMessages()` transforms it into display format on the fly.
 
@@ -261,8 +262,8 @@ Every write except `/api/git/init` is gated on the project being a git work-tree
 | GET | `/api/git/credentials` | List stored HTTPS credentials — `{credentials: [{host, username}]}`. **Never returns the token.** Source of truth is `~/.git-credentials` (one line per host) |
 | POST | `/api/git/credentials` | Body `{host, username, token}`. Upserts the `https://user:token@host` line in `~/.git-credentials` (0600). 400 if any field missing |
 | DELETE | `/api/git/credentials/:host` | Remove the credential line(s) for one host (idempotent). `:host` is sent `encodeURIComponent`'d; Hono decodes it |
-| GET | `/api/git/ssh/keys` | Private keys found in `~/.ssh` + an `encrypted` flag each. Never returns key contents. Returns `{keys: [...]}` |
-| GET | `/api/git/ssh/agent` | ssh-agent reachability + loaded key count |
+| GET | `/api/git/ssh/keys` | Private keys found in `~/.ssh` + an `encrypted` flag each. Never returns key contents. Returns `{keys: [{name, path, encrypted}]}` |
+| GET | `/api/git/ssh/agent` | ssh-agent reachability + loaded keys. Returns `{agentRunning, loadedKeys: string[]}` (`ssh-add -l` lines) |
 | POST | `/api/git/ssh/unlock` | Body `{keyPath, passphrase}`. Loads a passphrase-protected key into the shared ssh-agent. `keyPath` must resolve to a file **directly inside `~/.ssh`** (rejects traversal / arbitrary paths, 400). Passphrase is fed to `ssh-add` via a throwaway `SSH_ASKPASS` helper (never argv / disk / log); the helper is answer-once so a wrong passphrase returns immediately. Returns `{ok}` on success, `{ok:false, error}` (normalized — never ssh-add's raw stderr) on failure |
 | GET | `/api/git/remote/protocol?projectId=` | Current `origin` url + detected protocol. Returns `{url, protocol}` |
 | POST | `/api/git/remote/protocol` | Body `{projectId, to: 'https'\|'ssh'}`. Rewrites `origin` between HTTPS and scp-style SSH. Returns `{ok, url}` |
@@ -301,10 +302,10 @@ gets JSON, and additionally gates on `accessLevel`.
 
 | Method | Path | Purpose |
 |---|---|---|
-| POST | `/api/web/chat` | Send message, receive SSE stream. Body: `{message, images?, workspace?, sessionId?, agentId?}` (overrides also accepted as `?workspace=`/`?sessionId=` query or `x-workspace`/`x-session-id` headers; `workspace` only honored when token has `accessLevel: full`). `sessionId` must be owned by the token unless `accessLevel: full` → otherwise 403. |
+| POST | `/api/web/chat` | Send message, receive SSE stream. Body: `{message, images?, workspace?, sessionId?, agentId?}` (overrides also accepted as `?workspace=`/`?sessionId=` query or `x-workspace`/`x-session-id` headers; `workspace` only honored when token has `accessLevel: full`). `sessionId` must be a safe id segment (else 400) and owned by the token unless `accessLevel: full` → otherwise 403. A client that disconnects ends its stream right away; the turn keeps running (reconnect via `/subscribe`, stop via `/stop`). |
 | POST | `/api/web/sessions` | Mint a root session in the token's own `web_<accountId>_` namespace → `{sessionId}`. Body / query / header: `workspace?` (full tokens only), `agentId?`. Used by the ACP adapter's `session/new`. |
 | POST | `/api/web/stop` | Stop running task → `{stopped: boolean}` |
-| GET | `/api/web/history` | Active session history → `{sessionId, messages[], running}` |
+| GET | `/api/web/history` | Active session history → `{sessionId, messages[], running}`. With an explicit `sessionId` that doesn't exist in the workspace → 404 `{error: "session not found"}` |
 | GET | `/api/web/subscribe` | Reconnect SSE to running session |
 | GET | `/api/web/file?path=` | Inline-serve a workspace-relative file (image / video / pdf etc.). Path-traversal-checked against the token's bound workspace: the lexical check is re-verified against the realpath'd root, so a symlink inside the workspace pointing outside it returns 403; a dangling symlink (target doesn't exist) returns 404. Workspace runtime state (`.halo/sessions`, `.halo/logs`, `.halo/evo`, `halo.db*`) is hidden for every access level → 403 `{error: "path is not accessible"}`, checked on the realpath so symlinks into those dirs are caught too. |
 
@@ -321,7 +322,7 @@ runtime so the frontend can render rooms (workspaces) + characters (sessions).
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/show/state` | `full` or `observer` token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
-| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace, and within it only sessions their own account minted (`web_<accountId>_*`); anything else is 403. |
+| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `totalMessages` / `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace, and within it only sessions their own account minted (`web_<accountId>_*`); anything else is 403. |
 
 `observer` is more than an aggregate-counts role: past `/show/state`, it can also call `/show/session` to read **any workspace's** session transcript (last 40 messages, content truncated to 600 chars, tool input to 200 chars). Mint it knowing it grants cross-workspace transcript read access, not just dashboard counters.
 
@@ -339,20 +340,20 @@ File: `packages/server/src/routes/agent-configs.ts`
 | GET | `/api/agent-configs/tools` | Available workspace tools |
 | GET | `/api/agent-configs/models` | Available model providers and models |
 | POST | `/api/agent-configs` | Create a new agent |
-| GET | `/api/agent-configs/:id/yaml?scope=&projectId=` | Read agent.yaml |
-| PUT | `/api/agent-configs/:id/yaml?scope=&projectId=` | Write agent.yaml |
-| DELETE | `/api/agent-configs/:id?scope=&projectId=` | Delete agent (global has "last one" protection) |
+| GET | `/api/agent-configs/:id/yaml?scope=&projectId=` | Read agent.yaml. `scope=workspace` without `projectId` → 400; `scope` other than `global` / `workspace` (omitted = `global`) → 400 `Invalid scope` |
+| PUT | `/api/agent-configs/:id/yaml?scope=&projectId=` | Write agent.yaml. Same 400s as GET |
+| DELETE | `/api/agent-configs/:id?scope=&projectId=` | Delete agent (global has "last one" protection). Same 400s as GET — never falls back to the same-named global agent or skips the last-one guard |
 | PATCH | `/api/agent-configs/:id/toggle?scope=&projectId=` | Toggle disabled in workspace DB. `projectId` required. Returns `{ ok, disabled }`. |
 | GET | `/api/agent-configs/:id/md/:fileType` | Read an MD file (AGENT.md / INSTRUCTIONS.md / INDEX.md) |
-| PUT | `/api/agent-configs/:id/md/:fileType` | Write an MD file (AGENT.md / INSTRUCTIONS.md) |
-| GET | `/api/agent-configs/:id/md-all` | Read every MD at once |
+| PUT | `/api/agent-configs/:id/md/:fileType` | Write an MD file (AGENT.md / INSTRUCTIONS.md). `scope=workspace` without `projectId` → 400 (never writes the global AGENT.md / INSTRUCTIONS.md) |
+| GET | `/api/agent-configs/:id/md-all` | Read every MD at once. `scope=workspace` without `projectId` → 400 |
 | GET | `/api/agent-configs/:id/sessions?projectId=` | List the agent's session files |
 | GET | `/api/agent-configs/:id/sessions/:sessionId` | Read a session |
 | POST | `/api/agent-configs/:id/sessions` | Save / update a session |
 | DELETE | `/api/agent-configs/:id/sessions/:sessionId` | Delete a session |
 | DELETE | `/api/agent-configs/:id/sessions?all=1` | Delete every session for the agent |
 
-Every `:id` / `:sessionId` route param that becomes a path segment (here and in `DELETE /api/skills/:id`) is validated with `isSafeIdSegment()` (`routes/workspace-path.ts`) before it reaches `path.join` — `.` / `..` rejected outright, everything else must match `/^[\w.:>\u4e00-\u9fff-]+$/` (the union of the real id charsets: slug + CJK agent names, `__internal__`, and session ids embedding `_ - : . >`). Hono decodes `%2F` / `%2e` into params, so a raw `..%2F..%2Fetc` would otherwise arrive as a traversal. A rejected param is **400** (`Invalid agent id` / `Invalid skill id` / `Invalid session id`), distinct from the **404** a well-formed-but-missing session file gets.
+Every `:id` / `:sessionId` route param that becomes a path segment (here and in `DELETE /api/skills/:id`) is validated with `isSafeIdSegment()` (`routes/workspace-path.ts`) before it reaches `path.join` — `.` / `..` rejected outright, everything else must match `/^[\w.:>\u4e00-\u9fff-]+$/` (the union of the real id charsets: slug + CJK agent names, `__internal__`, and session ids embedding `_ - : . >`). Hono decodes `%2F` / `%2e` into params, so a raw `..%2F..%2Fetc` would otherwise arrive as a traversal. A rejected param is **400** (`Invalid agent id` / `Invalid skill id` / `Invalid session id`, or `Invalid id` on the session read / delete routes), distinct from the **404** a well-formed-but-missing session file gets.
 
 ## Skills
 
@@ -409,18 +410,18 @@ In `PUBLIC_PATHS` (no admin cookie). Auth is a web-channel `x-token` (header or
 
 ## Self-Evolution
 
-File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_runs` / `evolution_applies` queues to the admin UI's Evolution tab; see [plans/self-evolution.md](../plans/self-evolution.md) for the full design.
+File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_runs` / `evolution_applies` queues to the admin UI's Evolution tab; see [design/evolution.md](../design/evolution.md) for the full design. Unknown run id → 404 `{error: "not found"}`.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/evolution/runs` | List all evolution runs across workspaces. Carries the latest `apply_id`/`apply_status` per run. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
+| GET | `/api/evolution/runs?archived=0\|1&limit=20&before=<createdAt>` | List evolution runs across workspaces, newest first, cursor-paginated (`limit` 1–300, `before` = previous page's `nextCursor`; `archived=1` lists archived runs instead). Returns `{runs, hasMore, nextCursor}`; each row carries the latest `applyId`/`applyStatus`. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
 | GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `.skip.md` (when `status='skipped'`) + wrapper/sub-cli logs + a snapshot summary (first user message + first assistant reply + message count). Row carries `failureReason` (and `applyFailureReason` from the latest apply) — apply-side values include `phase A': apply cli exited <code>`, `phase A': apply agent aborted: <first line of ABORT.md>`, and `phase A': apply agent didn't produce apply.log`. |
-| POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. |
-| POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`. |
-| POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` with the supplied (required) hint so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |
-| POST | `/api/evolution/runs/:id/hint` `{hint}` | Append text to `user_hint` — memo only, doesn't change status. |
-| DELETE | `/api/evolution/runs/:id` | Delete a finished run: its on-disk artifacts (run dir + archive zip) **and** the DB row. Rejected with 409 for in-flight states (`pending` / `running` / `approved`) so a live wrapper / queued apply isn't pulled out from under. Broadcasts `evolution:run_changed` with `kind:'deleted'`. |
-| GET | `/api/evolution/applies` | List apply rows (used for status badges). |
+| POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. Returns `{ok, applyId}`; 409 when the run isn't `awaiting_review`. |
+| POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`; 409 otherwise. |
+| POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` (attempts cleared) with the supplied hint (required, else 400) so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |
+| POST | `/api/evolution/runs/:id/hint` `{hint}` | Append text to `user_hint` (hint required, else 400) — memo only, doesn't change status. Returns `{ok, userHint}`. |
+| DELETE | `/api/evolution/runs/:id` | Delete a finished run: its on-disk artifacts (run dir + archive zip + wrapper log) **and** the DB row, plus every apply that references it (artifacts + row, `evolution:apply_changed` `kind:'deleted'`). Rejected with 409 for in-flight states (`pending` / `running` / `approved`) so a live wrapper / queued apply isn't pulled out from under. Broadcasts `evolution:run_changed` with `kind:'deleted'`. |
+| GET | `/api/evolution/applies` | List in-flight apply rows (`pending` / `running` / `syncing`, newest 200; used for status badges). Returns `{applies}`. |
 
 ## AgentCore adapter (runtime-mode only)
 
@@ -434,7 +435,7 @@ Bodies and response shapes for the endpoints agents most commonly help users cal
 
 ### POST `/api/auth/login`
 
-Source: [packages/server/src/middleware/auth.ts:123-134](../../../packages/server/src/middleware/auth.ts#L123-L134)
+Source: [packages/server/src/middleware/auth.ts](../../../packages/server/src/middleware/auth.ts)
 
 ```json
 // Request
@@ -492,6 +493,9 @@ Source: [packages/server/src/routes/files.ts](../../../packages/server/src/route
 ```json
 // 200
 {
+  "projectId": "<absPath>",
+  "root": "<project dir name>",
+  "path": "<relPath>",
   "tree": [
     { "name": "packages", "path": "packages", "type": "directory", "hasChildren": true },
     { "name": "README.md", "path": "README.md", "type": "file" }
@@ -499,7 +503,7 @@ Source: [packages/server/src/routes/files.ts](../../../packages/server/src/route
 }
 ```
 
-Skipped entries: dotfiles (except `.halo`), `node_modules`, `__pycache__`.
+Skipped entries: `.git`, `.DS_Store`, `node_modules`, `__pycache__` (other dotfiles — `.halo`, `.gitignore`, `.env` — are listed).
 
 ### GET `/api/files?path=<rel>&projectId=<abs>`
 
@@ -507,7 +511,10 @@ Reads file content. Max 10 MB.
 
 ```json
 // 200
-{ "content": "..." }
+{ "path": "...", "content": "...", "size": 123, "modifiedAt": 1714000000000, "createdAt": 1714000000000 }
+
+// 413 over 10 MB
+{ "error": "File too large (max 10MB)" }
 
 // 404 if path doesn't exist
 { "error": "File not found" }
@@ -515,7 +522,7 @@ Reads file content. Max 10 MB.
 
 ### POST `/api/agent-configs`
 
-Source: [packages/server/src/routes/agent-configs.ts:199-255](../../../packages/server/src/routes/agent-configs.ts#L199-L255)
+Source: [packages/server/src/routes/agent-configs.ts](../../../packages/server/src/routes/agent-configs.ts)
 
 ```json
 // Request
@@ -540,12 +547,18 @@ Source: [packages/server/src/routes/agent-configs.ts:199-255](../../../packages/
   "conflictScope": null            // or "global" / "workspace" to warn of override
 }
 
+// 400 empty id after slugging ("Invalid agent name") or workspace scope without projectId
+{ "error": "Invalid agent name" }
+
+// 403 id `goal` while general.goal_mode_enabled is off
+{ "error": "Goal mode is disabled." }
+
 // 409 already exists
 { "error": "Agent already exists" }
 ```
 
 Files created:
-- `<agentDir>/agent.yaml` — scaffold with `SCAFFOLD_MODEL`, empty tools/skills
+- `<agentDir>/agent.yaml` — scaffold whose `model` block is a copy of the default agent's `model:` mapping (workspace scope: `<projectId>/.halo/agents/default/agent.yaml` if it exists, else the global default agent; global scope: the global one). Missing file / no `model` mapping → derived from the provider registry (`aws-bedrock-claude-invoke` if installed, else the first installed provider). Empty tools/skills; the response's `agent.model` is that block's `id`
 - `<agentDir>/AGENT.md` — `# <name>\n\n<description>\n`
 
 ### PUT `/api/agent-configs/:id/yaml?scope=&projectId=`
@@ -560,6 +573,12 @@ Files created:
 // 400 invalid YAML
 { "error": "Invalid YAML: <parser message>" }
 
+// 400 scope=workspace without projectId
+{ "error": "projectId required for workspace agents" }
+
+// 400 scope other than global / workspace
+{ "error": "Invalid scope" }
+
 // 404
 { "error": "Agent not found" }
 ```
@@ -574,8 +593,7 @@ Source: [packages/server/src/routes/skills.ts](../../../packages/server/src/rout
   "name": "Code Review",
   "description": "Review code for correctness and style",
   "scope": "workspace",
-  "projectId": "/abs/ws",
-  "command": "/review"            // optional — registers as slash command
+  "projectId": "/abs/ws"
 }
 
 // 201
@@ -588,11 +606,16 @@ Source: [packages/server/src/routes/skills.ts](../../../packages/server/src/rout
     "scope": "workspace"
   }
 }
+
+// 409 already exists
+{ "error": "Skill already exists" }
 ```
 
+Also adds the skill's entry to the scope's `settings.yaml`.
+
 ### GET `/api/sessions/logs?projectId=<abs>&rootOnly=0|1&includeArchived=0|1&cursor=<ms>&limit=<n>`
 
-Source: [packages/server/src/routes/sessions.ts:189-258](../../../packages/server/src/routes/sessions.ts#L189-L258)
+Source: [packages/server/src/routes/sessions.ts](../../../packages/server/src/routes/sessions.ts)
 
 Keyset-paginated over `updatedAt` (descending). `limit` defaults to 50 (max 500); the
 response's `nextCursor` (epoch ms of the last row's `updatedAt`, or `null` on
@@ -618,15 +641,14 @@ Two shapes, selected by `rootOnly`:
       "agentId": "default",
       "agentName": "Default",
       "title": "First user message...",
-      "source": "explorer",
-      "createdAt": "2026-04-30T08:00:00Z",
-      "updatedAt": "2026-04-30T08:05:00Z",
+      "createdAt": 1777536000000,
+      "updatedAt": 1777536300000,
       "exchangeCount": 12,
-      "parentSessionId": null,
       "contextTokens": 5975,
       "totalOutputTokens": 6058,
       "stoppedAt": null,
       "archivedAt": null,
+      "goalSessionId": null,
       "status": "idle"
     }
   ],
@@ -636,7 +658,7 @@ Two shapes, selected by `rootOnly`:
 
 Archived sessions are excluded by default; pass `?includeArchived=1` to include them.
 
-`status` is `'running' | 'idle' | 'stopped'`. A root counts as `running` while any of its sub-sessions runs. The admin's chat tab list uses it to show a running mark on a tab that hasn't loaded yet; a loaded tab follows its own stream.
+`status` is `'running' | 'idle' | 'stopped'`. A root counts as `running` while any of its sub-sessions runs. Returned since 1.5.3-alpha; the current admin no longer reads it. `parentSessionId` is present only on sub-sessions (omitted for roots). Timestamps are epoch ms.
 
 Rows are served from the mirrored `agent_sessions` metadata columns (`title` / `exchange_count` / `context_tokens` / `total_output_tokens`) — no session file is opened. A row whose `exchangeCount` is `null` predates those columns: the route reads that one file once, mirrors the values back, and never pays the cost again. `exchangeCount` counts **main user turns over the session's lifetime** (kept + archived), so unlike the file's `messageCount` it doesn't shrink when a compact archives history.
 
@@ -691,7 +713,7 @@ The `n > archiveCount` check is the point, not a formality: `archiveCount` in th
 
 ### GET `/api/settings/schema?projectId=<abs>`
 
-Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/config.yaml`) against current settings, returning per-field source/state and a list of orphan keys. Drives the Settings page.
+Resolves declared schema (from `models/<id>.yaml` `secrets:`, `skills/<id>/config.yaml`, and global `agents/<id>/agent-config.yaml`) against current settings, returning per-field source/state and a list of orphan keys. Drives the Settings page.
 
 ```json
 // 200
@@ -699,8 +721,8 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
   "scope": "global",                              // or "workspace" when projectId set
   "sections": [
     {
-      "namespaceId": "aws-bedrock-claude-invoke", // 'general' | provider id | skill id
-      "source": "provider",                        // 'general' | 'provider' | 'skill'
+      "namespaceId": "aws-bedrock-claude-invoke", // 'general' | provider id | skill id | agent id
+      "source": "provider",                        // 'general' | 'provider' | 'skill' | 'agent'
       "displayName": "AWS Bedrock Claude (Invoke API)",
       "displayName_zh": "AWS Bedrock Claude（Invoke API）",
       "description": "...",
@@ -711,8 +733,11 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
           "kind": "secret",                        // 'param' | 'secret'
           "description": "...",
           "description_zh": "...",
-          "default": null,                         // schema-default placeholder
+          "default": "...",                        // schema-default placeholder; omitted when the schema declares none
           "secret": true,                          // UI masks input + value
+          "globalOnly": false,                     // general.* only: workspace overrides ignored, workspace writes 400
+          "restartRequired": false,                // general.* only: read once at boot — UI shows a restart notice after saving
+          "advanced": false,                       // general.* only: rendered in the collapsed "Advanced" area (all but language / theme)
           "value": "AK****ST",                     // already masked when secret:true; null = unset
           "hasValue": true,                        // any layer has a non-empty value
           "source": "global",                      // 'workspace' | 'global' | 'unset'
@@ -744,18 +769,18 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
 { "ok": true }
 ```
 
-PUT replaces the full scope; DELETE takes `{scope, projectId, key}` and removes the key. The Settings page uses DELETE for both Reset (current scope removed → falls back to lower scope / unset) and orphan Remove.
+PUT replaces the full scope; PUT / PATCH / DELETE with `scope: "workspace"` reject a `globalOnly` key with 400 (`<key> is global-only and cannot be set per workspace`) and an unresolvable `projectId` with 404 `Project not found`. DELETE takes `{scope, projectId, key}` and removes the key. PUT / PATCH / DELETE fire the server's `onSettingsChange` listeners (e.g. the sandbox hidden-paths reload); a DELETE of an already-absent key is a no-op — `{ ok: true }`, no file write, no notify. The Settings page uses DELETE for both Reset (current scope removed → falls back to lower scope / unset) and orphan Remove.
 
 ### POST `/api/wechat/login/start`
 
-Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/src/routes/wechat.ts#L39-L43)
+Source: [packages/server/src/routes/wechat.ts](../../../packages/server/src/routes/wechat.ts)
 
 ```json
 // Request
 { "sessionKey": "optional-resume-key", "force": false }
 
 // 200
-{ "qrcodeUrl": "https://...", "sessionKey": "abc123" }
+{ "qrcodeUrl": "https://...", "message": "...", "sessionKey": "abc123" }
 ```
 
 ### POST `/api/wechat/login/wait`
@@ -766,7 +791,7 @@ Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/sr
   "sessionKey": "abc123",
   "workspacePath": "/abs/path",     // required, must be absolute
   "label": "My Bot",                // optional
-  "accessLevel": "readonly",        // "full" | "readonly", default readonly
+  "accessLevel": "readonly",        // "full" | "workspace" | "readonly", default readonly
   "language": "en",                 // "en" | "zh", default "en" — controls system message language
   "timeoutMs": 120000               // optional, how long to wait for scan
 }
@@ -774,10 +799,11 @@ Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/sr
 // 200 waiting for scan (retry polling)
 { "connected": false, "message": "..." }
 
-// 200 connected — account inserted + long-poll started
-{ "connected": true, "accountId": "abc-im-bot" }
+// 200 connected — account inserted (or updated if it already exists) + long-poll started
+{ "connected": true, "accountId": "abc-im-bot", "message": "..." }
 
-// 400 bad input
+// 400 bad input (sessionKey / workspacePath missing, relative path, bad accessLevel;
+// after a successful scan also "workspace path not found")
 { "error": "workspacePath required" }
 ```
 
@@ -797,17 +823,18 @@ Full WS protocol in [design/ws.md](../design/ws.md). The four high-traffic clien
   "message": "hello",
   "agentId": "default",                                    // optional override
   "clientMsgId": "abc123",                                 // optional — ack/resend dedup id
+  "accessLevel": "workspace",                              // optional — "full" | "workspace" | "readonly", idle session only
   "images": [ { "data": "<base64>", "mimeType": "image/png" } ]  // optional
 }
 ```
 
-Server behaviour ([handler.ts `handleChat`](../../../packages/server/src/ws/handler.ts#L263-L344)):
+Server behaviour (`handleChat` in `ws/handler.ts`; `sessionId`, `projectId` and `message` are all required, else an `error` frame):
 - Creates / reuses a session with the specified agent
-- Persists pasted images to `<ws>/.halo/web/inbound/<date>/`
+- Persists pasted images to `<ws>/.halo/assets/web/inbound/web/<date>/`
 - If the model does not support image input (`capabilities.image: false`), images are filtered out and a text notice is appended instead of sending to the API
-- Queues if busy/compacting; otherwise runs the agent turn
+- Queues if busy/compacting (a `chat:queued` frame is sent only for the compacting case); otherwise runs the agent turn. `accessLevel` applies only on the idle path and is forced to `full` when the host has no OS sandbox
 - When `clientMsgId` is present, replies `{ "type": "chat:ack", "clientMsgId" }` once the message is appended to the session log; resends with an already-acked id are re-acked without re-appending (dedup — see [design/ws.md](../design/ws.md#chat-delivery-ack--resend--dedup))
-- Streams events back via `message`, `tool_call`, `usage`, etc.
+- Streams events back via `chat:stream`, `agent:tool_call`, `chat:usage`, etc. (table below)
 
 ### `subscribe` (C→S)
 
@@ -871,13 +898,15 @@ It does not remove session files. The full delete (rows + JSON + archive segment
 
 | Type | Fields | Purpose |
 |---|---|---|
-| `message` | `content`, `role`, `taskId?` | Text chunk from the agent |
-| `tool_call` | `toolName`, `toolInput`, `taskId?` | Tool invocation card |
-| `tool_result` | `toolName`, `toolOutput`, `durationMs`, `taskId?` | Tool result |
-| `usage` | `usage`, `modelId`, `turnId`, `taskId?` | Token accounting per turn |
-| `complete` | `stopReason`, `taskId?` | Turn finished |
+| `chat:stream` | `text`, `agentName`, `turnId`, `taskId?` | Text chunk from the agent |
+| `chat:thinking` | `text`, `agentName`, `turnId`, `taskId?` | Thinking chunk |
+| `agent:tool_call` | `tool`, `toolUseId`, `input`, `agentName`, `turnId`, `taskId?` | Tool invocation card |
+| `agent:tool_result` | `result`, `toolUseId`, `agentName`, `durationMs`, `taskId?` | Tool result |
+| `chat:usage` | `contextTokens`, `outputTokens`, `usage`, `modelId`, `turnId` | Token accounting per model call (root only) |
+| `chat:complete` | `batchBoundary?` | Turn finished |
 | `error` | `error`, `sessionId?` | Error message |
-| `chat:queued` | `reason`, `message`, `sessionId` | Message queued (compact/busy) |
+| `chat:queued` | `reason: 'compact'`, `message`, `sessionId` | Message queued behind a compact |
+| `chat:ack` | `clientMsgId` | Chat appended to the session log (or re-acked on resend) |
 | `listener:released` | `sessionId` | Event listener reclaimed — re-send `subscribe` (see above) |
 
 Events with `taskId` set belong to sub-agent turns (nested sessions); events without are the root agent's. Session-scoped frames carry `sessionId` (the root session they belong to); the admin routes each one to the tab holding that session, and a frame without one goes to the tab on screen. Full list in [design/ws.md](../design/ws.md).

package/bundled-docs/dev/deploy.md

@@ -47,7 +47,7 @@ Nginx is **not required**. Use it only for domain routing, SSL termination, or w
 ## Prerequisites
 
 - Node.js ≥ 22
-- pnpm ≥ 9
+- pnpm 11 (pinned by the root `packageManager`; `corepack enable` picks it up)
 - AWS credentials configured (`~/.aws/credentials` or env vars) with Bedrock access
 
 ## 1. Install dependencies and build
@@ -63,7 +63,7 @@ pnpm --filter @turmind/halo-admin build   # next build + copy-monaco; never a ba
 
 ## 2. Runtime data locations
 
-No directory needs to be created by hand. SQLite databases are created automatically on first use: per-workspace state at `<workspace>/.halo/halo.db`, plus global queues at `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`.
+No directory needs to be created by hand. SQLite databases are created automatically on first use: per-workspace state at `<workspace>/.halo/halo.db`, plus global queues at `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`, and channel accounts at `~/.halo/secrets/channels/channels.db`.
 
 ## 3. Run `halo setup`
 
@@ -90,7 +90,7 @@ When `HALO_PASSWORD` is set, the password chosen via `halo setup` is ignored at
 
 ## 5. Start the server
 
-> **单实例锁**：server 启动时会写 `~/.halo/global/server.lock`（Linux 用 flock，macOS/Windows 回退到 pid 探测），退出时自动清理。如果 lock 里记录的进程还活着，新 server 会拒绝启动并打印 `kill <pid>` 提示。原因是 WeChat 长轮询循环跟 HTTP server 解耦，多个进程并存会导致同一条微信消息被 fan out 到多个 session。陈旧 lock（进程已不在）会被自动识别并清除。要手动重启先 kill 旧的：`kill $(cat ~/.halo/global/server.lock)`。
+> **单实例锁**：server 启动时会写 `~/.halo/global/server.lock`（有 `flock` 命令时用 flock，没有就回退到 pid 探测），退出时自动清理。如果 lock 里记录的进程还活着，新 server 会拒绝启动并打印 `kill <pid>` 提示。原因是 WeChat 长轮询循环跟 HTTP server 解耦，多个进程并存会导致同一条微信消息被 fan out 到多个 session。陈旧 lock（进程已不在）会被自动识别并清除。要手动重启先 kill 旧的：`kill $(cat ~/.halo/global/server.lock)`。
 
 ### Option A: quick start
 
@@ -155,8 +155,8 @@ server as its child (`packages/cli/src/server-supervisor.ts`). Policy:
   up (exit 1) with a log line telling you to fix the cause and re-run `halo
   server start -d`.
 - **2s pause between attempts**, so an instant-crash loop can't spin the CPU.
-- Every decision lands in the daemon log as `[respawn] …`, on the same fds the
-  server writes to (`~/.halo/global/logs/server.log`).
+- Every decision lands in the daemon log as `[respawn] …` — the stdout/stderr
+  capture `~/.halo/logs/server.log`, which `halo server logs` tails.
 
 `halo server stop` (and `--force`) is not mistaken for a crash: it stamps the
 server pid into a marker file `~/.halo/global/server.stop` *before* signalling,
@@ -219,6 +219,7 @@ This installs the `halo` binary on `$PATH`. Subcommands available:
 | `halo tui` | Interactive TUI client |
 | `halo cli "<prompt>"` | One-shot prompt → reply, exit |
 | `halo agents` / `halo sessions` | List agents / sessions |
+| `halo acp` | Stdio bridge that lets an ACP client (e.g. Claude Code) drive a halo server — see [acp-adapter.md](acp-adapter.md) |
 
 ### Upgrade flow
 
@@ -239,7 +240,7 @@ Use only for a new public release; the retained details here are not extra prepa
 
 **npm token gotcha**: `npm publish` on this package needs a granular access token created with **"Bypass 2FA"** checked — scope / permission alone yields `403 Two-factor authentication or granular access token with bypass 2fa enabled is required`. `npm whoami` and `npm token list` succeed with a non-bypass token, so neither is a valid pre-flight; check `GET https://registry.npmjs.org/-/npm/v1/tokens` (with the token as bearer) and look for `"bypass_2fa": true` on the token in use before starting a release.
 
-The published package contains a single bundled JS entry (~620 KB), all built-in templates (agents / skills / prompts / models), bundled platform docs, and the admin Web UI static export. Total install footprint ≈ 120 MB after npm dedupes shared deps.
+The published package contains a single bundled JS entry (~1.4 MB), all built-in templates (agents / skills / prompts / models), bundled platform docs, and the admin Web UI static export. Total install footprint ≈ 120 MB after npm dedupes shared deps.
 
 ### Non-interactive (Docker / CI) details
 
@@ -247,6 +248,7 @@ The published package contains a single bundled JS entry (~620 KB), all built-in
 
 - Seeds / refreshes `~/.halo/global/` from the bundled templates (per the per-category overwrite policy in `init.ts`)
 - Generates `server.jwt_secret` if missing
+- Binds the built-in agents to the provider named by `HALO_DEFAULT_PROVIDER`, when set (an unknown id only warns)
 - **Does not** set a password — supply one via `HALO_PASSWORD` env
 
 Minimal Dockerfile: