@moikapy/lich 0.3.0

package/docs/index.md

@@ -0,0 +1,68 @@
+---
+outline: [2, 3]
+---
+
+# Lich documentation
+
+> What you'll learn: what Lich is, what it ships, and which page to read next — plus a 60-second quickstart.
+
+Lich is a TypeScript AI agent harness: a library and a CLI that run a chat model inside a Think-Act-Observe loop. A chat wrapper forwards one prompt and prints one completion. A harness keeps going: the model plans (think), calls tools such as `read_file` or `terminal` (act), reads the tool results (observe), and repeats until it can produce a final answer. Lich wraps that loop with the machinery real deployments need: provider failover with bounded retries, path confinement and output clamps on every tool, context compression when the transcript grows past a token budget, and append-only JSONL session transcripts.
+
+One package, four ways to drive the same agent: a one-shot CLI, an interactive chat REPL, an ink-based terminal UI, and a long-running messaging gateway that bridges Telegram, Discord, Twitch, and a zero-config HTTP webhook. All four share the same twelve builtin tools, the same provider configuration, and the same session store.
+
+## Feature overview
+
+| Capability | What it gives you |
+| --- | --- |
+| Providers | `openai_compat`, `anthropic`, and `ollama` with automatic failover between configured providers; 429/5xx and network errors retry with backoff before failing over. |
+| Tools | Twelve builtins (file read/write/edit, directory listing, shell, grep, HTTP fetch/request, web search, process list, disk usage, env inspection), all confined to the working directory. |
+| Context compression | Transcript summarized in place when estimated tokens cross `compress_threshold` of `context_budget_tokens`; the 8 most recent turns always stay verbatim. |
+| Sessions | Every run persists a `.jsonl` transcript under `.lich/sessions/`, labeled by origin (`tui`, `gw:<platform>:<chat>`). |
+| CLI | One-shot tasks, chat REPL, TUI, gateway, and a `config` template command, all with flag/env/config-file configuration. |
+| TUI | Live ink transcript with tool-call rows, status bar (model, turns, tokens, session path), and slash commands. |
+| Gateway | One shared agent behind webhook/Telegram/Discord/Twitch with per-conversation memory (40-message history cap) and per-platform message splitting. |
+| Library | `create_agent` / `run_agent` with typed events (`AgentEmitter`), multi-turn history, and `ProviderError` kinds for error handling. |
+| Plugins | User-supplied tools and lifecycle hooks (`before_tool_call` veto, run lifecycle) loaded at startup from explicit module paths. |
+
+## Page map
+
+| Page | Read it to |
+| --- | --- |
+| [Getting started](getting-started.md) | Install, configure a provider, and get your first reply in any mode. |
+| [CLI reference](user-guide/cli.md) | Master all four modes, flags, provider resolution, and config files. |
+| [TUI guide](user-guide/tui.md) | Run the terminal UI and use slash commands and the status bar. |
+| [Gateway guide](user-guide/gateway.md) | Wire Telegram, Discord, Twitch, and the HTTP webhook to one agent. |
+| [Library guide](user-guide/library.md) | Embed the agent in TypeScript with events and multi-turn history. |
+| [Plugins guide](user-guide/plugins.md) | Add your own tools and lifecycle hooks to the agent. |
+| [Architecture overview](architecture/overview.md) | Understand how the harness works inside. |
+
+## How it works
+
+For the internals — the agent loop, provider failover, tool guardrails, and how to extend each layer — read the architecture track: [overview](architecture/overview.md), [agent loop](architecture/agent-loop.md), [providers](architecture/providers.md), [tools](architecture/tools.md), [plugins](architecture/plugins.md), and [extending](architecture/extending.md).
+
+## 60-second quickstart
+
+Requires Node >= 20 (or Bun) and access to one model endpoint (local Ollama, OpenAI, Anthropic, or any OpenAI-compatible API such as OpenRouter).
+
+```sh
+# from a clone of the repository
+bun install
+
+# generate a starter config, then edit the model name
+mkdir -p .lich && bun src/cli.ts config > .lich/config.json
+
+# chat TUI (exit with /exit or Ctrl+C)
+bun src/cli.ts tui
+
+# or a one-shot task
+bun src/cli.ts "list the files in this repo and summarize it"
+
+# or a messaging gateway on http://localhost:8089
+bun src/cli.ts gateway webhook
+```
+
+After `npm install`-ing the built package the same commands work as `lich tui`, `lich "task"`, and `lich gateway webhook`.
+
+## Version compatibility
+
+Documented for **v0.3.0**. Requires Node >= 20 (`engines` in `package.json`); Bun is the recommended runtime for development (`bun src/cli.ts ...`) and Node 20+ works for the built `dist/cli.js`. The TUI needs a TTY; the gateway and library run headless on both runtimes.

package/docs/user-guide/cli.md

@@ -0,0 +1,182 @@
+# CLI reference
+
+> What you'll learn: every CLI mode, flag, and default; how provider/model resolution works; the config file schema; session files, exit codes, and log levels; and practical recipes.
+
+## The four modes
+
+```sh
+lich "one shot task"   # run a single task and print the reply
+lich chat              # interactive chat (commands: /exit, /quit)
+lich tui               # interactive terminal UI (ink)
+lich gateway <plat..>  # messaging gateway (webhook|telegram|discord|twitch)
+lich config            # print a starter config template
+lich --help            # usage text
+lich --version         # print 0.2.0
+```
+
+- **One-shot** joins all positional words into a single task, runs the agent loop, prints the final answer to stdout, and exits. Progress (turn numbers, tool results) goes to stderr.
+- **Chat** is a readline REPL over one long-lived agent: each line is a turn, memory persists across lines, and an empty line, `/exit`, or `/quit` ends the session. After each turn it prints a `[turns N | tokens M]` footer.
+- **TUI** launches the ink interface. See the [TUI guide](tui.md).
+- **Gateway** runs platform adapters (defaults to `webhook` when no platform is given). See the [Gateway guide](gateway.md). Unknown platform names are skipped with a warning; if none remain, the CLI exits `1`.
+
+`bun src/cli.ts` and the installed `lich` binary accept identical arguments.
+
+## Flags
+
+Flags work before or after the subcommand. Every value flag can also be set via an environment variable or the config file (precedence below).
+
+| Flag | Meaning | Default |
+| --- | --- | --- |
+| `--config <path>` | JSON config file (must exist). Disables config discovery. | discovery chain |
+| `--work-dir <path>` | Working directory for tools and config/session resolution. | process cwd |
+| `--max-turns <n>` | Turn budget for the agent loop. | `25` |
+| `--model <m>` | Model name for `providers[0]`. | `LICH_MODEL` |
+| `--provider-kind <k>` | `openai_compat` \| `anthropic` \| `ollama`. | `LICH_PROVIDER_KIND`, else `openai_compat` |
+| `--base-url <u>` | Provider base URL for `providers[0]`. | `LICH_BASE_URL`, else per-kind default |
+| `--api-key-env <NAME>` | Env var holding the api key for `providers[0]`. | `LICH_API_KEY_ENV`, else per-kind default |
+| `--system-prompt <s>` | Replaces the default system prompt. | built-in concise-assistant prompt |
+| `--session-dir <path>` | Transcript directory. | `<work_dir>/.lich/sessions` |
+| `--log-level <level>` | `debug` \| `info` \| `warn` \| `error`. | `info` |
+
+Passing `--max-turns 0` or a non-integer fails with `--max-turns must be a positive integer`. Unknown flags fail with `unknown flag: --foo`. A flag missing its value fails with `<flag> requires a value`.
+
+## Provider resolution
+
+The effective provider for a run is decided in this order:
+
+1. If `--config <path>` was passed, that file is the whole configuration (it must exist, or the CLI fails with `config not found`).
+2. Otherwise the discovery chain is walked: `./.lich/config.json`, then `~/.config/lich/config.json`. The first file found becomes the config. `LICH_*` env vars are *not* merged into a discovered file.
+3. If no config file exists, one is built from the environment: `--provider-kind` / `LICH_PROVIDER_KIND` (default `openai_compat`), `--model` / `LICH_MODEL` (required — without it the CLI fails with `no model configured`), `--base-url` / `LICH_BASE_URL`, and `--api-key-env` / `LICH_API_KEY_ENV`, each falling back to the per-kind defaults below.
+4. Provider override flags (`--model`, `--provider-kind`, `--base-url`, `--api-key-env`) always win over the chosen source: with a config file present they patch `providers[0]` in place; without one they seed a fresh provider from the environment.
+
+Per-kind defaults:
+
+| Kind | Default base URL | Default key env | Notes |
+| --- | --- | --- | --- |
+| `openai_compat` | `https://api.openai.com/v1` | `OPENAI_API_KEY` | Works with any OpenAI-shaped `/chat/completions` API. |
+| `anthropic` | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` | |
+| `ollama` | `http://localhost:11434` | none | No key needed; `api_key`/`api_key_env` are sent as a Bearer header for cloud proxies when set. |
+
+## Config file reference
+
+Validated by zod (top-level unknown keys are silently stripped; extra keys inside a `providers[]` entry are passed through). Full example with every field:
+
+```json
+{
+  "providers": [
+    {
+      "kind": "openai_compat",
+      "name": "openrouter",
+      "model": "anthropic/claude-sonnet-4",
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key_env": "OPENROUTER_API_KEY"
+    },
+    {
+      "kind": "ollama",
+      "name": "local",
+      "model": "llama3.2:latest",
+      "base_url": "http://localhost:11434",
+      "keep_alive": "10m"
+    }
+  ],
+  "system_prompt": "You are a careful code reviewer.",
+  "max_turns": 40,
+  "work_dir": "/home/me/project",
+  "tools_enabled": ["read_file", "grep_files", "terminal"],
+  "temperature": 0.2,
+  "max_tokens": 4096,
+  "context_budget_tokens": 100000,
+  "compress_threshold": 0.8,
+  "session_dir": "/home/me/project/.lich/sessions",
+  "terminal_timeout_ms": 60000,
+  "log_level": "info"
+}
+```
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `providers` | array, min 1 | required | Failover chain, tried in order. |
+| `providers[].kind` | `"openai_compat" \| "anthropic" \| "ollama"` | required | Wire protocol. |
+| `providers[].name` | string | required | Label used in logs and `ChatResult.provider_name`. |
+| `providers[].model` | string | required | Model name sent to the provider. |
+| `providers[].base_url` | string | per kind | Endpoint base (see table above). |
+| `providers[].api_key` | string | – | Inline key (prefer `api_key_env`). |
+| `providers[].api_key_env` | string | per kind | Env var to read the key from. |
+| `providers[].timeout_ms` | positive int | none | Per-request abort deadline. |
+| `providers[].think` | boolean | – | Ollama only: request thinking mode. |
+| `providers[].keep_alive` | string | – | Ollama only: model residency (e.g. `"10m"`). |
+| `system_prompt` | string | built-in | Replaces the default system prompt. |
+| `max_turns` | int >= 1 | `25` | Turn budget per run. |
+| `work_dir` | string | cwd | Root for all file tools; paths outside are rejected. |
+| `tools_enabled` | `"all"` or name array | `"all"` | Restrict the registry to these builtin tools. |
+| `temperature` | 0–2 | – | Sampling temperature. |
+| `max_tokens` | positive int | – | Completion cap. |
+| `context_budget_tokens` | positive int | `100000` | Estimated budget before compression triggers. |
+| `compress_threshold` | 0.1–0.95 | `0.8` | Compress when usage >= this fraction of the budget. |
+| `session_dir` | string | `<work_dir>/.lich/sessions` | Transcript directory. |
+| `terminal_timeout_ms` | positive int | `60000` | Default timeout injected into the `terminal` tool. |
+| `log_level` | enum | `info` | Logger verbosity. |
+
+Minimal per-provider examples:
+
+```json
+{ "providers": [{ "kind": "ollama", "name": "local", "model": "llama3.2" }] }
+```
+
+```json
+{ "providers": [{ "kind": "anthropic", "name": "main", "model": "claude-sonnet-4", "api_key_env": "ANTHROPIC_API_KEY" }] }
+```
+
+Listed providers form a failover chain: the router walks them in order, retrying `rate_limit`/`network` errors (bounded backoff) on the current provider before moving on, and failing over immediately on `auth`, `overflow`, and `bad_request`.
+
+## Session files
+
+Each run writes `.lich/sessions/<timestamp36>-<counter>[-label].jsonl` where the label is the run origin: `-tui`, or `-gw-<platform>-<chat_id>` for gateway conversations. One-shot and chat runs get no label. Records are JSON lines of two kinds: `{"ts","kind":"meta","meta":{...}}` (run start, budget exhaustion) and `{"ts","kind":"message","message":{...}}` for each system/user/assistant/tool message.
+
+```sh
+# follow the newest session
+ls -t .lich/sessions/*.jsonl | head -1
+
+# print the conversation
+jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content // "(tool call)")"' .lich/sessions/<file>.jsonl
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success: final answer produced (also `--help`, `--version`, `config`). |
+| `1` | Any failure: unknown flag, missing model, unreadable config, provider error after failover, aborted run, or budget exhaustion (`[lich] budget exhausted after N turns` is printed to stderr). |
+
+## Log levels
+
+`--log-level` / config `log_level` sets the logger: `debug` (tool calls, retries, compression detail), `info` (lifecycle: gateway starts, adapter starts), `warn` (failover, degraded adapters, failed session persistence), `error` (provider and loop failures). Logger output goes to stderr. The one-shot/chat `[lich] turn N` / `tool: ok` progress lines are separate and always shown.
+
+## Recipes
+
+Review a file with a scoped working directory:
+
+```sh
+bun src/cli.ts --work-dir ./myproject --max-turns 15 \
+  "Review src/payments/retry.ts for correctness bugs. List each with a line number and a suggested fix."
+```
+
+Web research (search, then fetch the promising pages):
+
+```sh
+bun src/cli.ts \
+  "Find the current LTS version of Node.js using web_search, fetch the release page with fetch_url, and summarize the support schedule."
+```
+
+Note: `web_search` scrapes DuckDuckGo's HTML endpoint without an api key and can be blocked with `search_failed` errors when rate-limited; retrying later usually works.
+
+Batch one-shots from a script, checking each exit code:
+
+```sh
+#!/usr/bin/env bash
+set -u
+for task in "summarize README.md" "list the largest files with disk_usage" "grep for TODO comments"; do
+  echo "== $task"
+  LICH_PROVIDER_KIND=ollama LICH_MODEL=llama3.2 bun src/cli.ts --max-turns 10 "$task" || echo "FAILED ($?)"
+done
+```

package/docs/user-guide/gateway.md

@@ -0,0 +1,168 @@
+# Gateway guide
+
+> What you'll learn: how `lich gateway` bridges Telegram, Discord, Twitch, and an HTTP webhook into one shared agent, how to set up each platform, and the webhook API reference.
+
+## How it works
+
+`lich gateway <platform...>` runs a long-lived process that forwards inbound chat messages to **one shared agent** and routes replies back. Per-conversation memory is keyed `platform:chat_id` (Telegram/Discord chat ids, Twitch channel names, webhook `chat_id` field): each conversation keeps its own bounded history capped at 40 messages (oldest evicted; conversations beyond 200 are evicted oldest-first). Messages for the same conversation are serialized, so overlapping messages never interleave histories; different conversations can run concurrently. Failures become a safe one-line reply: `agent error: <flattened message, 300 chars max>`.
+
+```mermaid
+flowchart LR
+    A[Webhook / TG / Discord / Twitch] -->|inbound msg| B[platform adapter]
+    B -->|platform, chat_id, user_id, text| C[GatewayBus]
+    C -->|history for platform:chat_id| D[shared Agent]
+    D -->|tools, failover, compression| E[reply text]
+    E -->|split to platform limit| F[adapter send]
+    F --> G[user]
+```
+
+Platforms: `webhook` (HTTP server), `telegram` (long-poll), `discord` (gateway WebSocket), `twitch` (IRC over WebSocket). Pick any combination:
+
+```sh
+bun src/cli.ts gateway webhook                 # http only
+bun src/cli.ts gateway webhook telegram        # http + telegram polling
+bun src/cli.ts gateway telegram discord twitch # no webhook server
+bun src/cli.ts gateway                         # defaults to webhook
+```
+
+The gateway is silent after startup: Telegram/Discord/Twitch respond only in chats, channels, or servers the bot can see or has joined, and the webhook only serves HTTP. Telegram media messages arrive as the placeholder text `media not supported yet`; other non-text events are ignored. Telegram `/start` is answered like a plain "hello".
+
+## Setup: webhook
+
+Zero configuration — the server binds `0.0.0.0:$LICH_GATEWAY_PORT` (default 8089).
+
+```sh
+bun src/cli.ts gateway webhook
+```
+
+```sh
+curl -s -X POST http://localhost:8089/message \
+  -H "content-type: application/json" -d '{"text": "hello"}'
+# -> {"reply":"...","usage":null}
+
+curl -s http://localhost:8089/health
+# -> {"status":"ok"}
+```
+
+With token auth, every POST must carry the exact `x-lich-token` header; mismatched or missing tokens get `401 {"error":"unauthorized"}`:
+
+```sh
+LICH_GATEWAY_TOKEN=s3cret bun src/cli.ts gateway webhook
+curl -s -X POST http://localhost:8089/message \
+  -H "x-lich-token: s3cret" -H "content-type: application/json" -d '{"text": "hello"}'
+```
+
+Payload fields (all optional except `text`): `platform` (default `"webhook"`), `chat_id` (default `"default"`), `user_id` (default `"anonymous"`), `text` (required; missing `text` is a `400`). Use distinct `chat_id` values to keep independent conversation memories.
+
+## Setup: Telegram
+
+1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token.
+2. Export it and run:
+
+```sh
+export LICH_TELEGRAM_BOT_TOKEN=123456:ABC-your-token
+bun src/cli.ts gateway telegram
+```
+
+3. Open your bot in Telegram, send a message, get a reply. Media messages arrive as the text `media not supported yet`; the bot replies from there.
+
+Telegram uses long polling (no public URL needed). Replies split at 4096 chars.
+
+## Setup: Discord
+
+1. Create an application at the [Discord developer portal](https://discord.com/developers/applications), add a **Bot**, and copy the bot token.
+2. Enable the **Message Content Intent** (Bot settings → Privileged Gateway Intents) — the adapter requests intents `512 | 32768`, which includes message content.
+3. Invite the bot with the `bot` scope (OAuth2 → URL Generator; no extra permissions needed beyond sending messages in target channels).
+4. Export the token (and the bot's application/user id, so leading `<@BOT_ID>` mentions are stripped) and run:
+
+```sh
+export LICH_DISCORD_BOT_TOKEN=your-bot-token
+export LICH_DISCORD_BOT_ID=123456789012345678
+bun src.cli.ts gateway discord
+```
+
+5. Send the bot a message (DM or any channel it can read — every non-bot message gets a reply); each channel has its own conversation memory (keyed by `channel_id`). Replies split at 2000 chars. Bot-authored messages are ignored (no loops).
+
+**Known limitation:** the Discord adapter has no reconnect resume. If its gateway WebSocket drops, messages sent while offline are missed permanently; the adapter reconnects fresh after 5s. If guaranteed delivery across disconnects matters, run webhook or Telegram instead.
+
+## Setup: Twitch
+
+1. Generate an OAuth token with the `chat:read` and `chat:edit` scopes (for example via [twitchtokengen](https://twitchtokengen.com)).
+2. Export it, your bot account's nickname, and the channels to join (comma-separated, lowercased by the adapter):
+
+```sh
+export LICH_TWITCH_OAUTH_TOKEN=oauth:abc123...
+export LICH_TWITCH_NICK=mylichbot
+export LICH_TWITCH_CHANNELS=channelone,channeltwo
+bun src/cli.ts gateway twitch
+```
+
+3. The bot joins `#channelone` and `#channeltwo` and replies in chat (own messages are ignored). Replies split at 512 chars; IRC PING/PONG is answered automatically.
+
+All three fields (`token`, `nick`, `channels`) are required — a missing one idles the adapter.
+
+## Running multiple platforms at once
+
+List the platforms in one command; all configured adapters start together and share the agent:
+
+```sh
+LICH_TELEGRAM_BOT_TOKEN=... LICH_DISCORD_BOT_TOKEN=... \
+  bun src/cli.ts gateway webhook telegram discord
+```
+
+Adapters whose credentials are missing start **idle** (a warning is logged, e.g. `gateway discord adapter idle: LICH_DISCORD_BOT_TOKEN not set`) and the rest keep running — so the same command works on machines with partial credentials. If no platform name is valid, the CLI exits `1` with `gateway needs at least one valid platform`.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `LICH_GATEWAY_PORT` | `8089` | Webhook server port (invalid/empty values fall back to 8089). |
+| `LICH_GATEWAY_TOKEN` | unset | If set, POST `/message` requires header `x-lich-token` to match; else 401. |
+| `LICH_TELEGRAM_BOT_TOKEN` | unset | Bot token from BotFather; adapter idles without it. |
+| `LICH_DISCORD_BOT_TOKEN` | unset | Bot token from the developer portal; adapter idles without it. |
+| `LICH_DISCORD_BOT_ID` | unset | Bot user id; strips a leading `<@id>` mention from messages. |
+| `LICH_TWITCH_OAUTH_TOKEN` | unset | IRC oauth token (`oauth:` prefix optional); adapter idles without it. |
+| `LICH_TWITCH_NICK` | unset | Bot account nickname; required with the token. |
+| `LICH_TWITCH_CHANNELS` | unset | Comma-separated channels to join; required. |
+
+Provider/model configuration comes from the same resolution as every mode (`LICH_MODEL` or config file).
+
+## Operational notes
+
+- **Graceful stop:** SIGINT (Ctrl+C) or SIGTERM stops every adapter, then exits `0`. No other signals are handled.
+- **Idle adapters:** any adapter missing its token/credentials logs a warning once and does nothing; the process stays up for the others.
+- **Message splitting:** replies are split per platform — Telegram 4096 chars, Discord 2000, Twitch 512. Telegram/Discord splits prefer whitespace; Twitch hard-cuts at the limit.
+- **One shared agent:** all platforms share one agent instance, tool set, and provider failover chain; only conversation memory is per-chat.
+- **Debugging tool calls:** with `--log-level debug`, completed tool calls are logged as `tool <name> ok|failed`.
+- **Restart loses Discord messages:** see the [Discord note](#setup-discord) — the offline window is not replayed.
+
+## Webhook API reference
+
+### `POST /message`
+
+Request:
+
+```json
+{"text": "hello", "platform": "webhook", "chat_id": "default", "user_id": "anonymous"}
+```
+
+Only `text` is required. Success (`200`):
+
+```json
+{"reply":"Hello! How can I help you today? ...","usage":null}
+```
+
+`reply` is the agent's final answer; `usage` is always `null` on this endpoint (webhook replies are formatted without usage stats, unlike the chat/TUI footers). Errors:
+
+| Status | When |
+| --- | --- |
+| `400` | Body missing or has no `text` field: `{"error":"text is required"}`. |
+| `401` | `LICH_GATEWAY_TOKEN` is set and the `x-lich-token` header does not match. |
+| `404` | Anything other than `POST /message` or `GET /health`. |
+| `500` | Internal dispatch failure: `{"error":"internal error"}`. |
+
+Agent-level failures (e.g. every provider failed) return `200` with `reply` set to a sanitized one-line `agent error: ...` string, so callers always get a deliverable text.
+
+### `GET /health`
+
+`200 {"status":"ok"}` unconditionally — the webhook server itself is alive; it does not reflect platform adapters or provider health.

package/docs/user-guide/library.md

@@ -0,0 +1,181 @@
+# Library guide
+
+> What you'll learn: how to install the package and embed the `Agent` class in TypeScript — basic runs, event subscription, multi-turn history, config, tool filtering, error handling, and session access.
+
+## Install
+
+From a checkout of this repository (or a published tarball):
+
+```sh
+npm install /path/to/lich-0.2.0.tgz    # after `npm run build` in the lich repo
+# or point package.json at the git repo
+npm install git+ssh://example.com/you/lich.git
+```
+
+The package ships ESM (`dist/index.js`, types at `dist/index.d.ts`, binary at `dist/cli.js`); `main`/`types`/`bin` are wired in `package.json`.
+
+## Minimal example
+
+`create_agent(raw_config)` validates the config (zod, defaults applied, frozen result) and returns an `Agent` with a `.run()` loop:
+
+```ts
+import { create_agent } from "lich";
+
+const agent = create_agent({
+  providers: [{ kind: "ollama", name: "local", model: "llama3.2:latest" }],
+});
+
+const result = await agent.run({ input: "Use list_dir to list the files, then summarize." });
+console.log(result.outcome.final?.content);
+console.log(`tokens: ${result.usage_total.total_tokens}`);
+```
+
+The one-liner `run_agent(config, input)` is equivalent when you only need a single run:
+
+```ts
+import { run_agent } from "lich";
+
+const result = await run_agent(
+  { providers: [{ kind: "ollama", name: "local", model: "llama3.2:latest" }] },
+  "Reply with ok",
+);
+```
+
+## Agent class
+
+`new Agent(config)` (or `create_agent(raw)`) builds the provider router, registers the twelve builtin tools (filtered by `tools_enabled`), and exposes:
+
+| Member | Type | Purpose |
+| --- | --- | --- |
+| `run(options)` | `(AgentRunOptions) => Promise<AgentRunResult>` | Run the loop to a final answer, budget exhaustion, or abort. |
+| `events` | `AgentEmitter` | Subscribe with `events.on(handler)`; the returned function unsubscribes. |
+| `config` | `AgentConfig` | Frozen, fully-resolved config (defaults filled in). |
+
+`AgentRunOptions`:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `input` | `string` | Required user message for this run. |
+| `history` | `Message[]` | Prior conversation to continue (multi-turn). |
+| `signal` | `AbortSignal` | Cooperative cancellation; the loop returns `outcome.stopped_reason: "aborted"`. |
+| `label` | `string` | Origin tag for the session filename (e.g. `"tui"`, `"gw:webhook:default"`). |
+
+`AgentRunResult`:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `outcome.final` | `AssistantMessage \| undefined` | The final assistant reply (undefined on abort/budget without content). |
+| `outcome.turns_used` | `number` | Turns consumed this run. |
+| `outcome.stopped_reason` | `"final" \| "budget" \| "aborted"` | Why the loop ended. |
+| `messages` | `Message[]` | Full transcript: your `history` plus the new exchange. |
+| `usage_total` | `Usage` | Summed `{prompt_tokens, completion_tokens, total_tokens}`. |
+| `session_path` | `string \| undefined` | Session JSONL path, or `undefined` if persistence failed (logged warning, never throws). |
+
+## Events
+
+Handlers receive a discriminated `AgentEvent` union; throwing handlers are logged, never fatal:
+
+| Event | Payload |
+| --- | --- |
+| `turn_start` / `turn_end` | `{ turn }` |
+| `llm_start` | `{ turn }` |
+| `llm_end` | `{ turn, result: ChatResult }` — carries `usage` per call. |
+| `tool_call_start` | `{ turn, call: ToolCall }` |
+| `tool_call_end` | `{ turn, call, result: ToolResult }` |
+| `compress_start` | `{ estimated_tokens }` |
+| `compress_end` | `{ summary_chars }` |
+| `final` | `{ message, result }` — the answer that ends the run. |
+| `budget_exhausted` | `{ turns_used }` |
+| `error` | `{ error }` — provider/loop errors; the run may still recover via failover. |
+
+Print every tool call as it happens:
+
+```ts
+const agent = create_agent(config);
+const unsubscribe = agent.events.on((event) => {
+  if (event.type === "tool_call_end") {
+    const status = event.result.ok ? "ok" : `error: ${event.result.error}`;
+    console.log(`[tool] ${event.call.name}(${JSON.stringify(event.call.args)}) -> ${status}`);
+  }
+});
+try {
+  await agent.run({ input: "List the repo and find TODO comments" });
+} finally {
+  unsubscribe();
+}
+```
+
+## Multi-turn conversations
+
+Pass prior `result.messages` back in as `history`:
+
+```ts
+let history: Message[] = [];
+for (const question of ["What files are in the repo?", "Which one is largest?"]) {
+  const result = await agent.run({ input: question, history });
+  console.log(result.outcome.final?.content);
+  history = result.messages;
+}
+```
+
+## Config reference
+
+Same schema as the CLI config file — see the [config file reference](cli.md#config-file-reference) for the full field table. As a library caller you normally construct it directly:
+
+```ts
+const config = {
+  providers: [
+    { kind: "openai_compat", name: "openrouter", model: "meta-llama/llama-3.1-8b-instruct",
+      base_url: "https://openrouter.ai/api/v1", api_key_env: "OPENROUTER_API_KEY" },
+    { kind: "ollama", name: "local", model: "llama3.2" },  // failover target
+  ],
+  max_turns: 25,
+  tools_enabled: ["read_file", "list_dir", "terminal", "web_search", "fetch_url"],
+  session_dir: "./.lich/sessions",
+};
+```
+
+Listed providers form a failover chain tried in order: `rate_limit`/`network` errors retry with backoff (3 attempts) on the current provider before failing over; `auth`, `overflow`, and `bad_request` fail over immediately. The last error is rethrown when all providers fail.
+
+## Custom tool filtering
+
+`tools_enabled` accepts `"all"` (default) or an array of builtin tool names to register; everything else stays unregistered and invisible to the model:
+
+```ts
+const agent = create_agent({
+  providers: [{ kind: "ollama", name: "local", model: "llama3.2" }],
+  tools_enabled: ["read_file", "grep_files", "list_dir"],
+});
+```
+
+## Error handling
+
+Provider failures throw `ProviderError`, an `Error` subclass with `kind`, `provider_name`, optional `status` and `retry_after_ms`:
+
+| `kind` | Meaning | Failover behavior |
+| --- | --- | --- |
+| `auth` | 401/403 or bad credentials. | Immediate failover to the next provider. |
+| `rate_limit` | 429 or 5xx (with `retry_after_ms` when the server sends it). | 3 attempts with backoff, then failover. |
+| `network` | Fetch failed, timeout, or abort while connecting. | 3 attempts with backoff, then failover. |
+| `overflow` | Request exceeded the model's context window. | Immediate failover. |
+| `bad_request` | 400/422 or an unparseable success payload. | Immediate failover. |
+| `unknown` | Non-provider errors (e.g. tool crashes surfaced as strings). | Treated as fatal for the provider. |
+
+```ts
+import { ProviderError } from "lich";
+
+try {
+  await agent.run({ input: "hello" });
+} catch (error) {
+  if (error instanceof ProviderError) {
+    console.error(`${error.provider_name} failed: ${error.kind} — ${error.message}`);
+  }
+  throw error;
+}
+```
+
+When every configured provider fails, the last `ProviderError` is thrown. Tool failures are *not* exceptions: they return `{ ok: false, output, error }` into the loop as tool messages for the model to react to. Cancellation via `signal` ends the run with `stopped_reason: "aborted"` rather than throwing.
+
+## Session access
+
+Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`; read them with `jq` or the exported `read_session_messages(path)` helper from `src/session/store.ts`. Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.