@moikapy/lich 0.3.0

package/docs/architecture/overview.md

@@ -0,0 +1,188 @@
+# Architecture Overview
+
+Lich v0.2.0 is a small TypeScript AI agent harness: it drives a chat model in a
+think-act-observe loop, lets the model call tools, compresses history when the
+context budget demands it, and persists transcripts. It runs on Bun, is ESM
+with NodeNext resolution, and its only runtime dependencies are `zod` (config
+validation) and `ink` (the TUI). Everything else is Node/Bun built-ins.
+
+This page is the map. The follow-up pages go deep on each area:
+[agent loop](./agent-loop.md), [providers](./providers.md),
+[tools](./tools.md), and [extending](./extending.md).
+
+## Layer diagram
+
+```mermaid
+flowchart TB
+    subgraph entry["Entry surfaces"]
+        CLI["src/cli.ts<br/>one-shot and chat"]
+        TUI["src/tui/app.tsx<br/>ink TUI"]
+        GW["src/gateway/runner.ts<br/>webhook, telegram,<br/>discord, twitch"]
+        LIB["src/index.ts<br/>library exports"]
+    end
+    AGENT["Agent<br/>(src/agent/agent.ts)<br/>wiring, sessions, usage"]
+    LOOP["run_conversation<br/>(src/agent/loop.ts)"]
+    CHATFN["chat : ChatFn"]
+    TOOLFN["tools : ToolRunner"]
+    ROUTER["ProviderRouter + failover<br/>(src/providers/router.ts)"]
+    CLIENTS["openai_compat / anthropic / ollama<br/>HTTP clients"]
+    EXEC["ToolExecutor<br/>(src/tools/executor.ts)"]
+    REG["ToolRegistry<br/>(src/tools/registry.ts)"]
+    BUILTIN["12 builtin tools<br/>(src/tools/builtin/*)"]
+    COMP["ContextCompressor<br/>(src/context/compressor.ts)"]
+    SESSION["SessionStore<br/>(src/session/store.ts)"]
+
+    CLI --> AGENT
+    TUI --> AGENT
+    GW --> AGENT
+    LIB --> AGENT
+    AGENT --> LOOP
+    LOOP --> CHATFN
+    LOOP --> TOOLFN
+    CHATFN --> ROUTER
+    ROUTER --> CLIENTS
+    TOOLFN --> EXEC
+    EXEC --> REG
+    REG --> BUILTIN
+    LOOP -.-> COMP
+    AGENT -.-> SESSION
+```
+
+Solid edges are direct calls; dashed edges are side services the loop and the
+agent use between turns.
+
+## The dependency-inversion story
+
+The loop is the heart of the system, and it deliberately imports **no**
+concrete router and **no** concrete executor. It defines two narrow
+structural interfaces ([`src/agent/loop.ts`](../../src/agent/loop.ts)):
+
+- `ChatFn` - `(messages, tools, options?) => Promise<ChatResult>` (declared in
+  `src/context/compressor.ts`, since compression needs the same shape).
+- `ToolRunner` - `{ execute(name, args) => Promise<ToolResult> }`.
+
+`run_conversation` receives a `LoopDeps` object holding a `ChatFn`, a
+`ToolRunner`, a `definitions()` callback for tool schemas, and an optional
+emitter. The `Agent` class (`src/agent/agent.ts`) is the composition root: its
+`loop_deps()` method wires the real implementations -
+
+```ts
+chat: (messages, tools, chat_options) => this.router.chat_with_failover(messages, tools, chat_options),
+tools: this.executor,
+definitions: () => this.registry.definitions(),
+emitter: this.events,
+```
+
+(src/agent/agent.ts, `loop_deps()`)
+
+Why this matters:
+
+- **Testability.** The loop tests (`test/loop.test.ts`) run against a queued
+  fake `ChatFn` and a recording `ToolRunner`. No provider code, no HTTP, no
+  file system is touched, yet every event-ordering and stopping-condition
+  behavior is verified.
+- **Swap-ability.** Compression reuses `ChatFn` to call the same model with a
+  summarization prompt, so compression automatically benefits from the same
+  failover chain as normal chat.
+- **Small surface.** The loop cannot reach into provider configs, registries,
+  or session state even by accident; the compiler enforces the boundary.
+
+## Data flow of one user message
+
+Walkthrough of a single `Agent.run({ input })` call
+([`src/agent/agent.ts`](../../src/agent/agent.ts)):
+
+1. **Usage collector attached.** `run()` subscribes a `collect_usage` handler
+   on `agent.events`; every `llm_end` event adds the call's token usage into a
+   per-run `Usage` total. The subscription is removed in a `finally` block.
+2. **Seed messages.** The caller's `history` (if any) is copied into a fresh
+   array and the new user message is appended. The caller's array is never
+   mutated.
+3. **Loop starts.** `run_conversation(deps, seed, params)` first applies the
+   system prompt via `seed_system_prompt` (prepend, or replace an existing
+   system message if its content differs) and then enters the turn loop
+   described in [agent loop](./agent-loop.md).
+4. **Each turn.** Abort check at the top of the turn, optional compression
+   check, then one LLM call through the router (`chat_with_failover`, which
+   walks providers with bounded in-place retries). The assistant message is
+   pushed onto the history.
+5. **Tools.** If the assistant message carries `tool_calls`, each call runs
+   through the `ToolExecutor` (30 s timeout, abort linking, output clamping)
+   and a `tool` message is appended per call. The loop then starts the next
+   turn. A turn with no tool calls is the final turn.
+6. **Outcome.** The loop returns a `LoopOutcome`: the full `messages` array,
+   the final assistant message (or the last one seen), the last `ChatResult`
+   on a real final, `turns_used`, and a `stopped_reason` of `final`, `budget`,
+   or `aborted`.
+7. **Session persist.** `persist_session()` appends one `meta` record
+   (`run_start`), then one `message` record per outcome message, then a
+   `budget_exhausted` meta record if the budget stopped the run, to a JSONL
+   file under `session_dir` (default `<work_dir>/.lich/sessions`). Persistence
+   is best-effort: failures are logged and the run still succeeds with
+   `session_path: undefined`.
+8. **Return.** `AgentRunResult` bundles the outcome, the full transcript
+   (prior history plus the new exchange), the collected `usage_total`, and the
+   session path.
+
+## Concurrency model
+
+- **One `Agent` instance, one conversation at a time per call.** `Agent.run()`
+  is stateless across runs except for the shared, frozen `AgentConfig`: each
+  run builds its own history array and its own usage total.
+- **Gateway serialization.** `GatewayBus` (`src/gateway/bus.ts`) keeps a
+  per-conversation promise chain (`chains` map keyed by `platform:chat_id`).
+  Concurrent messages for the same conversation are serialized; different
+  conversations run in parallel but share one `Agent`. Histories are capped
+  (40 messages, 200 conversations, oldest-first eviction).
+- **No shared mutable state across conversations.** The bus never shares a
+  history array between keys; `Agent.run` copies what it is given. The TUI
+  serializes naturally: submissions are ignored while a run is in flight.
+- **Aborts flow down.** Every layer accepts an `AbortSignal` (`AgentRunOptions`
+  -> `LoopParams` -> `ChatOptions` -> fetch signal; executor signal -> tool
+  signal). See [agent loop](./agent-loop.md#abort-semantics) and
+  [tools](./tools.md#executor-semantics).
+
+## Directory map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/index.ts` | Public library surface; pure re-exports plus `LICH_VERSION`. |
+| `src/cli.ts` | Zero-dependency CLI: one-shot, `chat`, `tui`, `gateway`, `config`. |
+| `src/cli_config.ts` | Config file discovery, loading, flag overrides, template. |
+| `src/agent/agent.ts` | `Agent`: wires router, registry, executor; sessions; usage. |
+| `src/agent/loop.ts` | `run_conversation`: the think-act-observe loop. |
+| `src/agent/config.ts` | Zod config schema, defaults, derived `session_dir`, freeze. |
+| `src/agent/events.ts` | `AgentEmitter` and the `AgentEvent` discriminated union. |
+| `src/context/compressor.ts` | `compress_messages`, `should_compress`, `ChatFn`. |
+| `src/context/tokens.ts` | chars/4 token estimator used for budget decisions. |
+| `src/session/store.ts` | Append-only JSONL transcripts; `read_session_messages`. |
+| `src/providers/types.ts` | `Message`, `LLMProvider`, `ProviderConfig`, `ProviderError`. |
+| `src/providers/openai.ts` | OpenAI-compatible chat-completions client. |
+| `src/providers/anthropic.ts` | Anthropic Messages API client. |
+| `src/providers/ollama.ts` | Ollama `/api/chat` client. |
+| `src/providers/router.ts` | Provider registry, lazy construction, failover walk. |
+| `src/providers/failover.ts` | Retry classification, deterministic backoff. |
+| `src/tools/types.ts` | `Tool`, `ToolResult`, `ToolContext`, `Toolset`. |
+| `src/tools/guard.ts` | Path confinement, timeouts, clamping, arg coercion. |
+| `src/tools/registry.ts` | Name-keyed tool registry; duplicate rejection. |
+| `src/tools/executor.ts` | Never-throw execution with timeout and abort. |
+| `src/tools/builtin/*` | The 12 builtin tools (see [tools](./tools.md)). |
+| `src/gateway/bus.ts` | Conversation-keyed runner over one shared `Agent`. |
+| `src/gateway/runner.ts` | Adapter construction, signal handling, process lifetime. |
+| `src/gateway/{telegram,discord,twitch,webhook}.ts` | Platform adapters. |
+| `src/tui/state.ts` | Pure TUI state machine (no ink imports). |
+| `src/tui/app.tsx` | Ink components wiring events into the state machine. |
+| `src/util/*` | `safe_json_parse`/`safe_stringify`/`truncate_text`, `sleep`, logger, JSON Schema types. |
+
+## Design trade-offs
+
+- **No token streaming in the TUI.** Providers return complete messages; the
+  TUI shows phase (`thinking`/`tool`) rather than streaming text. This keeps
+  every provider client a simple request/response mapping.
+- **chars/4 token estimate** (`src/context/tokens.ts`). Budget decisions do
+  not need exact token counts; a coarse estimator avoids per-provider
+  tokenizer dependencies at the cost of ~10-20% error.
+- **Per-run history, capped in the gateway.** Long gateway conversations keep
+  the newest 40 messages; compression further protects the context budget.
+- **One shared agent in the gateway.** Simpler than one agent per conversation;
+  isolation comes from per-conversation histories and the bus promise chains.

package/docs/architecture/plugins.md

@@ -0,0 +1,91 @@
+# Plugin architecture
+
+How the plugin system loads user modules, merges tools into the registry, and intercepts tool calls with hooks. Source: [`src/plugins/`](../../src/plugins).
+
+## Loader flow
+
+`create_agent_with_plugins` parses the config, loads every entry from `config.plugins`, then hands `LoadedPlugin[]` to the `Agent` constructor. Each entry is resolved against `work_dir`, dynamically imported, and validated by shape; failures accumulate as error strings instead of throwing.
+
+```mermaid
+flowchart LR
+    A["config.plugins entries"] --> B{"entry empty?"}
+    B -- yes --> S["skip"]
+    B -- no --> C["path.resolve(work_dir, entry)"]
+    C --> D{"has module\nextension?"}
+    D -- no --> E["error: plugin_entry_not_a_module"]
+    D -- yes --> F["import(pathToFileURL(abs))"]
+    F --> G{"import ok?"}
+    G -- no --> H["error entry\n(import failure)"]
+    G -- yes --> I{"shape: default /\nplugin export /\nmodule itself"}
+    I -- none --> J["error: no plugin export"]
+    I -- ok --> K{"name unique?"}
+    K -- no --> L["error: duplicate_plugin_name"]
+    K -- yes --> M["LoadedPlugin collected"]
+    M --> N["Agent constructor"]
+    N --> O["registry merge:\nplugin tools appended\n(dup tool name → warn+skip)"]
+    N --> P["hook concat:\nPluginHooks[] in config order"]
+    P --> Q["HookedToolRunner wraps\nToolExecutor when hooks exist"]
+    E --> R["warn + continue"]
+    H --> R
+    J --> R
+    L --> R
+```
+
+Three export shapes are accepted, checked in order: `default` export, a named `plugin` export, or the module object itself (top-level `name` plus `tools`/`hooks`). A bare object with just a `name` is rejected as a module-shape plugin (the `tools`/`hooks` surface must be present) to avoid treating arbitrary objects as plugins.
+
+## HookedToolRunner interception
+
+When any plugin provides hooks, `Agent` wraps the `ToolExecutor` in a `HookedToolRunner` and the loop's `ToolRunner` dependency points at the wrapper instead. The loop is unchanged — it still calls `execute(name, args, context)`.
+
+```mermaid
+sequenceDiagram
+    participant L as loop (run_tool_calls)
+    participant H as HookedToolRunner
+    participant B as before_tool_call hooks
+    participant E as ToolExecutor
+    participant A as after_tool_call hooks
+
+    L->>H: execute(name, args, context?)
+    H->>B: await hook(info, ctx) in order
+    B-->>H: {block: true, reason}?
+    alt first blocker wins
+        H-->>L: {ok: false, output: "", error: "blocked_by_plugin: reason"}
+    else no blocker
+        H->>E: execute(name, args, context?)
+        E-->>H: ToolResult
+        H->>A: await hook({...info, result_summary}, ctx)
+        note over A: summary = 300 chars of output/error
+        H-->>L: ToolResult unchanged
+    end
+```
+
+Lifecycle fan-outs live on the same wrapper: `Agent.run` calls `call_run_start({input_chars})` before `run_conversation` and `call_run_end({stopped_reason, turns_used})` after it (including the abort/throw path, via `finally`). Both are best-effort: hook throws are logged at `warn` and the run proceeds.
+
+## Design decisions
+
+- **Explicit entries, no directory scan.** v1 loads only the files you list in `config.plugins`. Directory scanning would make runs depend on whatever happens to sit in a folder — non-reproducible, and a footgun for tools that write into `.lich/`. Explicit entries make the agent's tool surface a function of the config alone.
+- **Observe-then-veto, not middleware.** `before_tool_call` may allow or veto but not rewrite args or results. Full middleware (argument rewriting, result transforms, ordering control) is a much larger design surface; v1 ships the 90% use case — guarding and auditing — with semantics simple enough to reason about: hooks run in config order and the first blocker wins.
+- **Sync constructor + async factory.** `new Agent(config, plugins)` stays synchronous so existing callers and tests are untouched; the async work (dynamic imports) lives in `create_agent_with_plugins`. The trade-off: callers who construct `Agent` directly must load plugins themselves — documented in the library guide.
+- **Errors as data.** The loader returns `{plugins, errors}` and `plugin_errors_summary` renders one warn line. Startup never crashes because one entry is broken, but misconfiguration is still visible in logs.
+
+## Extension surface
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `Plugin` | type | `{name, version?, tools?, hooks?}` — what a plugin module exports. |
+| `PluginHooks` | type | The four optional lifecycle hooks with their signatures. |
+| `HookContext` | type | `{work_dir}` passed to every hook. |
+| `LoadedPlugin` | type | `{plugin, entry}` — a loaded plugin and its source path. |
+| `load_plugins` | function | `(entries, base_dir) => {plugins, errors}` — dynamic import + shape validation. |
+| `plugin_errors_summary` | function | Joins error entries into one warn-able string. |
+| `HookedToolRunner` | class | Wraps any `{execute}` runner with before/after interception. |
+| `create_agent_with_plugins` | function | Parse config → load plugins → build `Agent` (warns on errors). |
+| `config.plugins` | config | `string[]` of entry module specifiers relative to `work_dir`. |
+
+## Invariants
+
+1. A bad plugin never crashes startup: import failures, missing exports, and duplicate names all become error entries.
+2. Hooks and tools from later plugins cannot break earlier ones — every hook call is wrapped in try/catch with a `warn`.
+3. Plugin tools cannot shadow builtin or other plugin tools: duplicate registration is a warn + skip, so the visible tool set is deterministic given a config.
+4. The `ToolRunner` interface (`execute(name, args, context?)`) is structural — `HookedToolRunner` satisfies it without importing the loop.
+5. No new dependencies: loading uses `import()` + `node:url`, registration uses the existing `ToolRegistry`.

package/docs/architecture/providers.md

@@ -0,0 +1,273 @@
+# Providers
+
+Providers are the LLM adapters. Each one implements the same narrow interface
+([`src/providers/types.ts`](../../src/providers/types.ts)) and knows nothing
+about the agent loop; the router and failover layer above them know nothing
+about any individual provider's wire format.
+
+## The `LLMProvider` contract
+
+```ts
+export interface LLMProvider {
+  readonly name: string;
+  readonly model: string;
+  chat(
+    messages: readonly Message[],
+    tools: readonly ToolDefinition[],
+    options?: ChatOptions,
+  ): Promise<ChatResult>;
+}
+```
+
+(src/providers/types.ts)
+
+- **`Message`** is a union of four shapes: `system` and `user` (plain text
+  `content`), `assistant` (text plus optional `tool_calls`), and `tool` (a
+  result keyed by `tool_call_id` and `name`, with optional `is_error`).
+- **`ToolDefinition`** is `{ name, description, parameters }` where
+  `parameters` is a JSON Schema object - passed through to providers verbatim.
+- **`ChatResult`** carries the parsed `AssistantMessage`, token `Usage`, a
+  `finish_reason`, and the resolved `model` / `provider_name`.
+- **`ChatOptions`** are `temperature`, `max_tokens`, `signal`, and one
+  ollama-only hint (`think`). Providers ignore what they do not support.
+
+Every provider maps its HTTP/JSON wire dialect onto this contract and maps
+every failure onto `ProviderError` with a `kind` from a fixed taxonomy. A
+provider either resolves with a `ChatResult` or throws `ProviderError` (or a
+raw `TypeError` from fetch, which the failover layer classifies as
+`network`).
+
+### Finish-reason philosophy
+
+`FinishReason` is `"stop" | "tool_calls" | "length" | "error" | "unknown"`.
+The mapping philosophy: **`tool_calls` is derived from tool-call presence, not
+from the provider's done/stop reason.** The reason string is informational;
+the loop only branches on `message.tool_calls` (see
+[agent loop](./agent-loop.md)).
+
+This is load-bearing because of an ollama quirk: Ollama reports
+`done_reason: "stop"` even when the response contains tool calls. The ollama
+client documents this inline as "load-bearing":
+
+```ts
+/**
+ * Load-bearing mapping: Ollama reports done_reason "stop" even when tool
+ * calls are present, so presence of tool_calls wins over done_reason.
+ */
+function map_done_reason(done_reason: string | undefined, has_tool_calls: boolean): FinishReason {
+  if (has_tool_calls === true) {
+    return "tool_calls";
+  }
+  ...
+}
+```
+
+(src/providers/ollama.ts)
+
+## Client walkthroughs
+
+All three clients share the same skeleton: resolve auth, build endpoint and
+JSON body from typed DTOs, fetch (injectable `fetch_fn`), throw `ProviderError`
+on non-OK or unparseable bodies, parse the success body into `ChatResult`.
+They differ in wire mapping.
+
+### OpenAI-compatible (`src/providers/openai.ts`)
+
+Endpoint: `POST {base_url}/chat/completions`, header `authorization: Bearer`.
+Roles map 1:1; there is no message restructuring at all.
+
+| Our `Message` | Wire format |
+| --- | --- |
+| `system` / `user` | `{ role, content }` verbatim |
+| `assistant` | `{ role: "assistant", content, tool_calls?: [{ id, type: "function", function: { name, arguments } }] }` - **`arguments` is JSON-stringified** via `safe_stringify` |
+| `tool` | `{ role: "tool", tool_call_id, content }` - 1:1, one wire message per tool message |
+| `ToolDefinition` | `{ type: "function", function: { name, description, parameters } }` |
+
+Response parsing: `choices[0].message`, string `arguments` parsed with
+`safe_json_parse` (unparseable args become `{}` plus a
+`[unparseable tool arguments]` note appended to the content), `finish_reason`
+mapped `stop`/`tool_calls`/`length` verbatim, missing total tokens recomputed
+as prompt + completion.
+
+### Anthropic (`src/providers/anthropic.ts`)
+
+Endpoint: `POST {base_url}/v1/messages`, headers `x-api-key` and
+`anthropic-version: 2023-06-01`. Two structural differences from our model:
+
+| Our `Message` | Wire format |
+| --- | --- |
+| `system` (any position, any count) | Hoisted to top-level `system` string; all system contents joined with `\n`. Not part of `messages`. |
+| `assistant` | `{ role: "assistant", content: blocks }` - a `text` block plus one `tool_use { id, name, input }` block per call; `input` is a **JSON object** |
+| consecutive `tool` messages | **Merged into one `user` turn** whose content is the `tool_result` blocks (`tool_use_id`, text content, `is_error` passthrough) |
+| `ToolDefinition` | `{ name, description, input_schema: parameters }` |
+
+Why the merge: the Messages API requires strictly alternating user/assistant
+roles, and tool results must be delivered as `tool_result` blocks inside a
+`user` turn. The loop naturally produces several `tool` messages after one
+assistant turn (one per call), so `to_anthropic_turns` buffers them
+(`pending_tool_results`) and flushes them as a single user turn when the next
+non-tool message arrives.
+
+`max_tokens` is **required** by the API, so it defaults to 4096 when
+`options.max_tokens` is absent. `stop_reason` maps: `end_turn` -> `stop`,
+`tool_use` -> `tool_calls`, `max_tokens` -> `length`.
+
+### Ollama (`src/providers/ollama.ts`)
+
+Endpoint: `POST {base_url}/api/chat`. Quirks, each deliberate:
+
+| Aspect | Behavior |
+| --- | --- |
+| Streaming | `stream: false` is always sent; the client wants one complete JSON body. |
+| Tool-call arguments | **JSON objects both ways**: requests send `function.arguments` as an object; responses accept an object, tolerate a JSON string (some proxies send one), and fall back to `{}` with a `[unparseable tool arguments]` note. |
+| Tool results | Ollama has no tool-call ids: tool messages are sent 1:1 with `tool_name` (not `tool_call_id` / `name`). Correlation is positional. |
+| Tool-call ids | Ollama returns none, so the client synthesizes `ollama_<base36 time>_<counter>` per call. |
+| `done_reason` | Reports `"stop"` even with tool calls; tool-call presence wins (above). |
+| 200 with error | Ollama can return HTTP 200 with `{ "error": "..." }`; the client checks `dto.error` first and throws `bad_request`. A 200 without `message` is also `bad_request`. |
+| Generation caps | `max_tokens` maps to `options.num_predict`; `temperature` also lives under `options`. |
+| Extras | Config `think: true` adds `think: true`; `keep_alive` (e.g. `"10m"`) is forwarded. |
+
+Usage comes from `prompt_eval_count` / `eval_count`.
+
+## Error taxonomy
+
+`ProviderErrorKind` and the mapping rules are identical across clients
+(`status_to_error_kind` in each client), with one anthropic addition:
+
+| Kind | Meaning | OpenAI mapping | Anthropic mapping | Ollama mapping |
+| --- | --- | --- | --- | --- |
+| `auth` | Missing/invalid credentials | 401, 403; missing key for api.openai.com (thrown before HTTP) | 401, 403; missing key (thrown before HTTP) | 401, 403 |
+| `rate_limit` | Retryable throttling/instability | 429 and **any 5xx** | 429, **529 (overloaded)**, and any 5xx | 429 and any 5xx (529 falls under >= 500) |
+| `overflow` | Context window exceeded | 400 whose body matches `/context\|token\|length/i` | 400 matching `/context\|token\|maximum/i` | 400 matching `/context\|token\|maximum\|too long/i` |
+| `bad_request` | Everything else non-ok | 4xx not above; unparseable 2xx bodies | same | same, plus 200-with-error bodies |
+| `network` | Fetch failed / aborted / timed out | fetch throws; body read failures; abort-like errors (`AbortError`, `TimeoutError`) | same | same |
+| `unknown` | Anything else | non-`ProviderError` throwers get wrapped by the router with kind `unknown` | same | same |
+
+Additional mapping details shared by all clients:
+
+- `Retry-After` is parsed (seconds, floored at 0) into `retry_after_ms` on the
+  error; the retry layer honors it as a delay floor.
+- Error bodies are truncated to 500 chars in the message.
+- `classify_error` (`src/providers/failover.ts`) maps non-`ProviderError`
+  throwers: abort-like or `TypeError` (fetch's network failure signature)
+  become `network`; everything else `unknown`.
+
+## Router and failover
+
+`ProviderRouter` (`src/providers/router.ts`) holds the config list and
+constructs providers **lazily**: `get(name)` builds a client on first use and
+caches it in a `Map`; `build_provider` is a small kind map
+(`anthropic` -> `AnthropicProvider`, `ollama` -> `create_ollama_provider`,
+everything else -> `OpenAICompatProvider`). Construction is cheap and side
+effect free, so lazy vs eager is only an optimization - but it keeps
+construction failures (there are none today; even missing keys throw at chat
+time) out of config parsing.
+
+`chat_with_failover` walks providers **in config order**:
+
+```mermaid
+flowchart TD
+    START["chat_with_failover"] --> ABORT0{"caller signal<br/>already aborted?"}
+    ABORT0 -->|yes| THROWABORT["throw last error<br/>or router abort error"]
+    ABORT0 -->|no| P1["attempt provider n<br/>run_with_retries max 3"]
+    P1 -->|ok| DONE["return ChatResult"]
+    P1 -->|ProviderError| KIND{"error kind?"}
+    KIND -->|"rate_limit or network"| RETRIED["already retried in place<br/>with backoff (max 3 attempts)"]
+    KIND -->|"auth, overflow, bad_request"| NEXT["fail over immediately"]
+    RETRIED --> NEXT
+    NEXT --> MORE{"more providers?"}
+    MORE -->|yes| ABORT0
+    MORE -->|no| THROWLAST["throw last ProviderError"]
+```
+
+`run_with_retries` (`src/providers/failover.ts`) retries only `rate_limit` and
+`network` kinds, up to `max_attempts` (the router passes 3). Everything else
+rethrows immediately, so auth/overflow/bad_request fail over to the next
+provider on the first attempt.
+
+**Backoff.** `compute_backoff_ms` is deterministic (no `Math.random`, per repo
+convention):
+
+```text
+exponential = floor(500 * 2**attempt)        // attempt is 1-based
+jitter      = floor((500 * attempt) / 2)
+delay       = min(exponential + jitter, 8000)
+```
+
+Attempt 1 waits 1250 ms, attempt 2 waits 2500 ms. The fixed jitter term
+spreads simultaneous callers without nondeterminism (tests assert exact
+values).
+
+**`Retry-After` floor.** If the failed call produced `retry_after_ms` larger
+than the computed backoff, the server value wins (`delay_for_error`).
+
+**Abort semantics.** A caller abort is checked in three places: before each
+provider in the router walk, after each failed attempt in the retry loop, and
+during the backoff sleep itself (`sleep` rejects on abort, and the abort is
+re-checked right after). Aborts rethrow immediately - they never trigger a
+retry and never advance to the next provider. The router rethrows the last
+provider error when the caller had already aborted mid-walk.
+
+The retry loop is a `while` loop, never recursion (repo convention).
+
+## `ProviderConfig` reference
+
+| Field | Applies to | Meaning |
+| --- | --- | --- |
+| `kind` | all | `"openai_compat" \| "anthropic" \| "ollama"` - selects the client. |
+| `name` | all | Router key and `provider_name` on results/errors. |
+| `model` | all | Model identifier sent to the API. |
+| `base_url` | all | API root; per-kind default (`api.openai.com/v1`, `api.anthropic.com`, `localhost:11434`). |
+| `api_key` | all (used by all three) | Direct key. Ollama treats it as optional proxy auth. |
+| `api_key_env` | all | Env var to read the key from; per-kind default below. |
+| `timeout_ms` | all | Per-call `AbortSignal.timeout`, merged with the caller signal. |
+| `think` | ollama | Adds `think: true` to the request (thinking mode). |
+| `keep_alive` | ollama | Model residency hint forwarded verbatim (e.g. `"10m"`). |
+| `fetch_fn` | all | Injectable fetch for tests; defaults to global `fetch`. |
+
+Env resolution rules per kind (who needs a key, and fallback order):
+
+| Kind | Key required? | Resolution order |
+| --- | --- | --- |
+| `openai_compat` | Only for the well-known host `api.openai.com` | `api_key` -> `api_key_env` -> `OPENAI_API_KEY` (well-known host only) |
+| `anthropic` | Always | `api_key` -> `api_key_env` -> `ANTHROPIC_API_KEY` |
+| `ollama` | Never | `api_key` -> `api_key_env`; if one resolves, a `Bearer` header is sent for cloud proxies |
+
+The openai rule is host-based on purpose: custom `base_url`s (LM Studio,
+vLLM, OpenRouter-style gateways) may not want a key, so a missing key is only
+fatal for `api.openai.com`, where it is guaranteed to fail. A missing
+required key throws `auth` before any HTTP request is made.
+
+## Testing pattern
+
+Provider tests inject a `fetch_fn` and assert on captured requests with
+canned `Response` bodies - no network, no mocking library
+(`test/providers.test.ts`):
+
+```ts
+function mock_fetch(responder: (request: CapturedRequest) => MockReply): {
+  fetch_fn: typeof fetch;
+  requests: CapturedRequest[];
+} {
+  const requests: CapturedRequest[] = [];
+  const fetch_fn: typeof fetch = (input, init) => {
+    const request: CapturedRequest = { url: String(input), init: init ?? {} };
+    requests.push(request);
+    const reply = responder(request);
+    const body_text = reply.text_body ?? JSON.stringify(reply.body ?? {});
+    return Promise.resolve(new Response(body_text, { status: reply.status, headers: reply.headers }));
+  };
+  return { fetch_fn, requests };
+}
+```
+
+(test/providers.test.ts)
+
+Each test constructs the provider with `{ ...config, fetch_fn }`, calls
+`chat`, then asserts on `requests[i].url`, parsed `init.body` (wire mapping)
+and the returned `ChatResult` (response mapping). Error paths return canned
+non-200 statuses or malformed bodies and assert the resulting
+`ProviderError.kind`. The same pattern drives the ollama quirk tests
+(`test/providers_ollama.test.ts`, including a 200-with-error body) and the
+failover walk (`test/failover.test.ts`). See
+[extending](./extending.md#add-a-provider) for the full recipe.