faberwright 0.3.1 → 0.4.1

package/README.md

@@ -1,96 +1,216 @@
 # Faber
 
-**An agentic AI coding assistant for your terminal.** Give it a task in plain English; it explores your repository, edits files with your approval, runs your tests, and remembers your project across sessions.
+**A cost and performance efficient agentic AI coding assistant for your terminal.** Give it a task in plain English; it explores your repository, edits files with your approval, runs your tests, and remembers your project across sessions.
 
 *Faber — Latin for craftsman. Yours lives at `faber`.*
+* Read: [Faber Medium](https://medium.com/@jshial25/why-should-an-ai-coding-agent-read-hundreds-of-files-to-answer-one-question-d6369d29dfa5?postPublishedType=repub)
+## Code Graph
+<img width="636" height="573" alt="Screenshot 2026-08-09 at 2 58 30 PM" src="https://github.com/user-attachments/assets/176e5093-8e29-452f-a749-d06a561c583a" />
+
+## Demo 
+<img width="1240" height="700" alt="terminal_demo_compressed" src="https://github.com/user-attachments/assets/f78a8f68-130e-4f37-90f2-7a7089fa2653" />
 
-```
-$ faber "add input validation to the signup endpoint and cover it with tests"
-  ⚙ trace_path (from=main, to=handleSignup)
-  ⚙ read_file (path=app/routes/auth.ts)
-
-Proposed change to app/routes/auth.ts:
-@@ -12,6 +12,9 @@
-+  if (!isEmail(req.body.email)) return res.status(400)...
-Apply?   ↑/↓ then Enter
-❯ Yes
-  No
-  Always this session
-
-  ⚙ run_shell (command=npm test)
-─ result ────────────────────────────
-Added email/password validation to /signup, verified with 4 new passing tests.
-─────────────────────────────────────
-tokens: 31.2k in (78% cached) / 1.9k out · 7 calls
-```
 
 ## Your first session (2 minutes)
 
 ```bash
-cd your-project     # any repo — Faber works on the folder you're in
+cd your-project     # any repo; Faber works on the folder you're in
 faber               # start the REPL (approval mode is on by default)
 ```
 
-1. **Give it a real task** — `add a comment explaining what the main entry file does`
-2. **Approve the diff** — arrow keys, Enter. Cursor starts on Yes; "Always this session" grants trust. Shell commands ask too.
-3. **See the safety net** — `/history` lists every task with the files it touched.
-4. **Undo it** — `/undo` reverts the task; changed your mind? `/redo` brings it back. Nothing is ever lost in either direction.
-5. **Come back tomorrow** — `faber --resume` continues the conversation, or just ask *"what did we do last time?"* — it searches past sessions itself.
+1. **Give it a real task.** Try `add a comment explaining what the main entry file does`
+2. **Approve the diff** with the arrow keys and Enter. Cursor starts on Yes; "Always this session" grants trust. Shell commands ask too.
+3. **See the safety net.** `/history` lists every task with the files it touched.
+4. **Undo it.** `/undo` reverts the task, and if you change your mind changed your mind? `/redo` brings it back. Nothing is ever lost in either direction.
+5. **Come back tomorrow.** `faber --resume` continues the conversation, or just ask *"what did we do last time?"* — it searches past sessions itself.
 
-That loop — **task, approve, inspect, revert** — is the whole trust model. Everything else is detail.
+That loop of task, approve, inspect, revert is the whole trust model. Everything else is detail.
 
 ## Why Faber
 
 **It has a map, not just eyes.** The code graph stores call and import *edges*, incrementally updated in milliseconds. One ~50-token query (`trace_path(main, saveUser)` → `main → startServer → handleSignup → saveUser`) replaces reading thousands of tokens of files. `/map main` prints the call tree — the "trace it from main" ritual every programmer does, automated.
 
-**It's honest about money.** Prompt caching marks the stable prefix of every request, so repeat loop iterations pay ~10% for tokens already sent. And after every task you see exactly what happened: `tokens: 31.2k in (78% cached) / 1.9k out · 7 calls`.
+**Every model you can reach, including the coding ones.** Claude through the Anthropic API or your own AWS account, OpenAI through both of its APIs — chat completions and the Responses API that the codex family requires — plus anything OpenAI-compatible, and local models through Ollama for no key and no cost. Faber reads which endpoint each model needs and routes there itself, so `gpt-5.3-codex` and `claude-opus-5` are both just entries in the same list, priced side by side.
+
+**It's honest about money.** Prompt caching marks the stable prefix of every request, so repeat loop iterations pay ~10% for tokens already sent. Every task is costed and recorded as it runs, so `/usage` is a ledger of what you actually spent rather than an estimate — broken down by time window and by model, with the cheapest option always visible next to the one you're using.
 
 **Nothing is irreversible.** Every task is checkpointed before it touches a file. Undo is undoable. Approvals gate both edits *and* shell commands. Rejecting a change tells the model to change course, not retry.
 
 **It remembers.** Facts, decisions, and gotchas persist per-project in SQLite. Sessions survive crashes (append-only JSONL). New sessions start with a digest of the last one, and the agent searches past conversations when you reference them.
 
-**You can steer it mid-flight.** See it going the wrong way? Just type — `use TypeScript, not JavaScript` — and your guidance is injected at the next loop iteration. No cancelling, no wasted tokens.
-
-## Upgrading from Codewright
-
-Faber is Codewright renamed (the npm name was taken between build and release). Existing projects keep working untouched: an existing `.codewright/` state directory is adopted as-is, so memory, code graph, sessions, and usage history all survive. `CW_*` environment variables still work alongside the canonical `FABER_*` names. New projects get `.faber/`.
+**You can steer it mid-flight.** See it going the wrong way? Just type `use TypeScript, not JavaScript` — and your guidance is injected at the next loop iteration. No cancelling, no wasted tokens.
 
 ## Requirements & install
 
-Node.js ≥ 22.5 (uses built-in `node:sqlite` — **zero native dependencies**; installs never fail on compilation). Two pure-JS runtime deps: `diff`, `picocolors`.
+You need Node.js 22.5 or newer. Faber uses Node's built-in SQLite, so there are no native dependencies to compile and installs don't fail on a missing toolchain. The only runtime dependencies are two small pure-JS packages.
 
 ```bash
 npm install -g faberwright
-export ANTHROPIC_API_KEY=sk-ant-...       # add to ~/.zshrc to persist
-faber                                     # you're in
+faber
+```
+
+The first time you run it, Faber asks three questions and remembers the answers:
+
+```
+Welcome to Faber.
+Let's pick where your model comes from. You can change this any time with /route or /model.
+
+Who provides the model?
+❯ Anthropic
+  OpenAI
+  Local
+  Other
+
+How should Faber reach it?
+❯ Anthropic API                  direct, pay per token with your own key
+  Amazon Bedrock                 your AWS account owns auth and billing
+  Google Vertex AI               your GCP project owns auth and billing  (not yet wired)
+
+Faber needs an API key for Anthropic API.
+  Get one at https://console.anthropic.com/settings/keys
+  ANTHROPIC_API_KEY (hidden): ••••••••••••
+
+Default model
+❯ sonnet   balanced, a good default for daily work
+  opus     most capable, for complex multi-step work
+  haiku    fastest and cheapest, for simple tasks
+```
+
+Nothing is written until setup finishes. Quit halfway through and the next run starts over from the first question, so you can never end up half-configured. Every later launch checks that your setup can actually reach a model before it opens the prompt, which means a missing key gets caught at startup rather than surfacing as a confusing error partway through a task.
+
+If a key is already in your environment, Faber says so and asks what to do with it: use it and remember it, use it without saving, or replace it with a different one. A key you deliberately paste wins over the environment variable, because an explicit choice shouldn't be silently overridden.
+
+Your key never leaves your machine. Faber has no server and no account of its own, and it talks only to the model provider you pick. Keys you give it are written to `~/.faber/credentials.json` with owner-only permissions, never into your project folder, where a stray `git add` could publish them.
+
+Environment variables still work and still take precedence, so existing setups and CI keep running unchanged:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+faber
 ```
 
-Any OpenAI-compatible provider: `FABER_PROVIDER=openai`, `OPENAI_API_KEY`, `FABER_BASE_URL`, `FABER_MODEL`.
+Setup is skipped entirely when there's no terminal attached, so scripts and CI never block on a prompt. And if you don't have an API key at all, pick **Local → Ollama** during setup and Faber runs against a model on your own machine, no key and no cost.
 
 ## Features
 
-| | |
+| Feature|Description |
 |---|---|
 | **Streaming agent loop** | Text renders as generated, with a live heartbeat (`✳ Working… 14s`) that never interleaves with output and ends in `✳ Worked for 14s`. Plan → tool → observe → adjust, until done. Hard iteration cap. |
 | **Code graph** | Symbols *and* call/import edges, incrementally maintained (only changed files re-parse). Agent tools: `who_calls` (blast radius), `calls_from` (dependencies), `trace_path` (workflow chain). A compact repo map of the most-connected symbols orients every task. Edges are static hints — dynamic dispatch/DI/events aren't captured; the agent reads code where precision matters. |
-| **Approval by default** | Arrow-key menu on every file edit (colored diff) and every shell command. `--auto` / `/auto` / `FABER_APPROVAL=auto` opts into autonomy. |
-| **Interactive choices** | Genuinely ambiguous request? The agent presents 2–4 options plus "Chat more about this instead" before writing code. |
-| **Mid-task steering** | Type while it works; guidance is injected at the next loop boundary. If the model finishes while steering is queued, the task continues instead. Steering markers carry a per-task nonce, so hostile file contents can't impersonate you. |
-| **Paste as chips** | Raw-mode composer: pasting a 50-line block renders only a chip — `[pasted #1 +50 lines]` — never the code itself, while the full text is expanded into the message on Enter. Paste the same block again to expand it visibly. Paste, type, paste again: one submission. Full line editing: arrows, Home/End, forward-delete, Ctrl-A/E/K/U, Up/Down history; long drafts wrap across rows with exact cursor tracking — backspace and arrows travel across wrap boundaries. Chips are atomic — one arrow step, one backspace.  Works at the prompt and while steering. |
-| **Reversible history** | `/history` lists tasks with files touched; `/restore <id>` jumps anywhere; `/undo` / `/redo` — restores are never destructive. |
 | **Git-aware** | Warns about uncommitted changes at startup. Optional `FABER_GIT=commit`: one commit per completed *task* (never per edit). The agent never commits by default. |
 | **Two-layer memory** | Short-term: token-budgeted window, auto-summarized past 60k (tool pairs never split). Long-term: SQLite+FTS5 facts/decisions/gotchas + per-file notes, with full lifecycle (`/forget`, `/archive`, `/prune`). |
 | **Sessions** | Crash-safe JSONL transcripts; `--resume`; last-session digest injected at startup; `recall_sessions` keyword search across history. |
 | **Prompt caching** | Cache breakpoints on system prompt, tools, and sliding conversation history. Typical tasks: 60–90% of input from cache. |
 | **Output discipline** | Research-informed brevity (Chain-of-Draft style): short prose answers, shorthand inter-tool notes, no postamble — with an explicit exception that code correctness and completeness are never sacrificed for token count. `/verbose` toggles full-depth explanations. `FABER_WEAK_MODEL` routes internal summarization (compaction, digests) to a cheap model. |
 | **Token transparency** | Per-task footer with cache rate. Set `FABER_PRICE_IN` / `FABER_PRICE_OUT` ($/Mtok) for cost estimates. |
-| **Usage dashboard** | `/usage` shows a persistent ledger: tasks, tokens, cache rate, cost, and cache *savings* — for this session, today, and all time, plus totals across every project on the machine. Records live in `.faber/usage.db` per project and survive restarts. |
+| **Usage dashboard** | `/usage` shows a persistent ledger: tasks, tokens, cache rate, cost, and cache *savings* — for this session, today, and all time, plus totals across every project on the machine. Costs use each model's own rates, including its exact cache read/write prices, so a history spanning a model switch stays accurate. Prices ship built in and update with `/usage --refresh-prices`. Records live in `.faber/usage.db` per project and survive restarts. |
 | **Error recovery** | Transient API errors: backoff + jitter, honors Retry-After. Tool errors return to the model to self-correct. Identical call failing twice → warning; three times → clean abort. Ctrl-C aborts streams *and* running commands; checkpoints survive. |
 | **Safety rails** | Symlink-resolved path jail, shell denylist, timeouts, output truncation, atomic writes (temp+rename), stale-edit guard. Guardrails, not a sandbox — use a container for untrusted code. |
+| **Approval by default** | Arrow-key menu on every file edit (colored diff) and every shell command. `--auto` / `/auto` / `FABER_APPROVAL=auto` opts into autonomy. |
+| **Guided setup** | First run walks through vendor, route, credential and model, then remembers it. Later launches verify the setup can reach a model before opening the prompt. Nothing is saved until setup finishes, so an interrupted run leaves no half-configured state. |
+| **Credentials** | Keys live in `~/.faber/credentials.json`, owner-only, outside every repository. Faber checks that what you paste looks like a key before storing it, hides it as you type, and never prints more than a masked fragment. Environment variables keep working and take precedence. |
+| **Mid-task steering** | Type while it works; guidance is injected at the next loop boundary. If the model finishes while steering is queued, the task continues instead. Steering markers carry a per-task nonce, so hostile file contents can't impersonate you. |
+| **Reversible history** | `/history` lists tasks with files touched; `/restore <id>` jumps anywhere; `/undo` / `/redo` — restores are never destructive. |
+
+## Vendors, routes, and models
+
+Faber separates three choices, so you can change one without redoing the others:
+
+| Level | What it decides | How you set it |
+|---|---|---|
+| **Vendor** | who makes the model | `/route` |
+| **Route** | how you reach it and who owns auth | `/route` |
+| **Model** | which model on that route | `/model` (searchable model options) |
+
+Routes available today: **Anthropic API**, **Amazon Bedrock**, **OpenAI API**, **Ollama** (local, no key and no cost), and any **OpenAI-compatible endpoint** (OpenRouter, Groq, Together, vLLM, a gateway). Google Vertex is defined but not yet wired up, and `/route` says so rather than failing at request time.
+
+On OpenAI, Faber speaks both APIs. Chat completions for most models, and the **Responses API** for the ones that require it, which includes the codex family — the coding-tuned models a coding agent actually wants. You don't choose: each model's endpoint is recorded in the price dataset Faber already downloads, so `gpt-5.3-codex` routes to `/v1/responses` and `gpt-5.5` to `/v1/chat/completions` automatically. If a model is too new to appear in that dataset and the API says it belongs elsewhere, Faber retries on the endpoint it names rather than failing.
+
+### Amazon Bedrock
+
+Faber authenticates two ways, and tries them in this order.
+
+**With an IAM role, which needs no key at all.** In SageMaker Studio, on EC2, in ECS or Lambda, or on a laptop where you've run `aws configure`, Faber finds your AWS credentials the same way the SDKs do and signs each request with SigV4. Pick Amazon Bedrock during setup, give it a region, and that's the whole configuration. The signing is implemented directly against Node's crypto module rather than pulling in the AWS SDK, so the zero-dependency install still holds, and it's verified against the signature AWS publishes for its own worked example.
+
+**With a Bedrock API key**, if you'd rather use one:
+
+```bash
+export BEDROCK_API_KEY=...
+```
+
+Model ids on Bedrock differ by region and deployment, so pin them per alias in your profile instead of relying on the built-in names:
+
+```json
+{ "route": "bedrock", "region": "us-west-2",
+  "modelPins": { "sonnet": "anthropic.claude-sonnet-4-6-v1" },
+  "apiKeyEnv": "BEDROCK_API_KEY" }
+```
+
+### Costs
+
+`/usage` is a ledger, not an estimate. Every task's cost is worked out and written down when the task runs, at the rates in effect then, and never recalculated. If a vendor raises prices next month, last month's tasks still show what they actually cost.
+
+`/usage` breaks spend down across seven rolling windows — today, 7 days, 14 days, 30 days, 3 months, 6 months, all time — each showing tasks, tokens, cache rate, cost and savings, with a per-model table underneath showing where the money actually goes.
+
+Windows are rolling rather than calendar, so "last 30 days" always means thirty days instead of resetting to one on the first of the month. All seven are shown even when they hold identical numbers: a missing row would read as "no data" when it actually means "nothing new since," and that distinction is the whole point for someone coming back after a break.
+
+The two columns nobody can interpret unaided are defined in the panel itself. **Cached** is the share of input served from a cache rather than billed at full price. **Saved** is the counterfactual: what those same tasks would have cost without prompt caching. The by-model table is the actionable part, since switching routine work to a cheaper model is usually the largest saving available.
+
+**Where prices come from**, best source first: whatever you set explicitly, then the provider's own published rates (OpenRouter publishes per-token prices including cache reads and writes, and needs no key for it), then a community dataset covering everyone else, then a small table built into Faber so it works offline. Anthropic and OpenAI don't publish prices through their APIs at all, which is why the last two exist.
+
+Keeping those rates current matters more than it sounds, precisely because costs are frozen when recorded: a stale table would bake a wrong number into your history permanently. So Faber fetches prices during setup and re-checks on every launch with a conditional request. When nothing has changed the server answers `304` with no body — about 70ms in the background — so there's no window where an out-of-date rate can enter your records. The full download happens only when the list actually changes, and after a failed attempt Faber waits a day before retrying so an offline machine isn't making a doomed request on every start.
+
+Turn the automatic refresh off with `FABER_AUTO_PRICES=0` or `"autoRefreshPrices": false` in your profile. This is the only network request Faber makes that isn't an inference call; it fetches a public price list and sends nothing about you.
+
+Costs use each model's own input, output, cache-read and cache-write rates rather than a flat multiplier, and cloud model ids like `us.anthropic.claude-sonnet-5` normalise onto the same entry as the direct one. `FABER_PRICE_IN` and `FABER_PRICE_OUT`, or `priceIn` and `priceOut` in a profile, override everything. A model with no known price shows a dash rather than a guess.
+
+**What gets recorded.** One row per task in `<project>/.faber/usage.db`:
+
+```
+ts           1785979475047     when it ran
+input        27000             fresh input tokens
+cache_read   46000             served from cache
+cache_write  500               stored into the cache for reuse
+output       3600              generated
+calls        3                 API round-trips inside that task
+model        gpt-5.3-codex     which model ran it
+cost         0.0412            dollars, frozen at run time
+saved        0.0231            what caching avoided
+```
+**Cost metrics `/usage`:
+
+<img width="636" height="388" alt="Screenshot 2026-08-10 at 12 25 57 AM" src="https://github.com/user-attachments/assets/33ba06ce-69ad-4afe-afcc-6119a897e67a" />
+
+
+Counters and a timestamp. No prompts, no code, no file contents. Around 80 bytes a row, so a year of heavy use is roughly a megabyte, and nothing is ever pruned.
+
+Keeping the raw rows rather than rolling them into running totals is deliberate: any question you think of later can still be answered about the past. Spend for a particular month, which model a given week ran on, cost per task before and after a prompt change. It's a plain SQLite file, so `sqlite3 .faber/usage.db` will answer anything Faber doesn't print — including an expense report of your own shape.
+
+Settings live in `~/.faber/settings.json` as named **profiles**:
+
+```json
+{
+  "activeProfile": "work",
+  "profiles": {
+    "work":  { "route": "anthropic-api", "model": "sonnet", "apiKeyEnv": "ANTHROPIC_API_KEY_WORK" },
+    "local": { "route": "ollama", "model": "qwen2.5-coder" }
+  }
+}
+```
+
+Profiles store the name of the environment variable holding your credential, never the credential itself, so the file is safe to sync between machines or keep in a dotfiles repo. Switch between them with `/profile local`.
+
+Settings resolve in this order, highest first: environment variables, then a project's `.faber/config.json`, then the active profile, then defaults. So a repo can pin its own model while your machine default stays whatever you picked, and an environment variable still overrides both.
 
 ## Commands
 
 ```
+/setup              run setup again (vendor, route, credential, model)
+/route              choose a vendor and route
+/model [id]         switch model; lists what your key can use, with prices
+/key [set|rm]       show, save or remove an API key
+/profile [name]     list or switch saved profiles
+/usage              cost ledger by time window and model (--refresh-prices)
 /index              rebuild the code graph (symbols + call edges)
 /map <symbol>       print the call tree from any entry point
 /memory [archived]  long-term memories (+ file notes)
@@ -101,6 +221,7 @@ Any OpenAI-compatible provider: `FABER_PROVIDER=openai`, `OPENAI_API_KEY`, `FABE
 /history            task checkpoints         /restore <id>
 /undo  /redo        revert last task / bring it back
 /ask  /auto         toggle approval mode
+/verbose /concise   full-depth answers, or short ones (default concise)
 /clear  /help  /exit
 ```
 
@@ -115,19 +236,23 @@ Flags: `faber [task] [--workspace|-w <dir>] [--resume] [--ask|--auto] [--version
 | `FABER_MODEL`, `FABER_BASE_URL` | model + endpoint overrides |
 | `FABER_APPROVAL` | `ask` \| `auto` (ask) |
 | `FABER_GIT` | `commit` = one commit per task (off) |
-| `FABER_PRICE_IN`, `FABER_PRICE_OUT` | $/Mtok → cost estimate in footer |
+| `FABER_PRICE_IN`, `FABER_PRICE_OUT` | $/Mtok, overrides the built-in price table |
 | `FABER_WEAK_MODEL` | cheap model for internal summarization (e.g. a Haiku-class model) |
 | `FABER_MAX_ITERATIONS` | loop cap (40) |
 | `FABER_CONTEXT_BUDGET` | compaction threshold, tokens (60000) |
 | `FABER_SHELL_TIMEOUT` | ms (120000) |
+| `FABER_ROUTE`, `FABER_REGION` | route id and region, overriding the profile |
+| `FABER_AUTO_PRICES` | `0` disables the background price refresh |
+| `BEDROCK_API_KEY` | Bedrock, when you'd rather use a key than an IAM role |
+| `AWS_ACCESS_KEY_ID` etc. | picked up automatically for Bedrock's SigV4 signing |
 
-Per-project overrides: `.faber/config.json`.
+Faber keeps three files. `~/.faber/settings.json` holds your profiles, which is the route, model and which environment variable a credential comes from. `~/.faber/credentials.json` holds the keys themselves, owner-only and outside every repository. A project can override the profile with its own `.faber/config.json`, which is useful when one repo should use a cheaper model than the rest.
 
-**Commit protection is automatic:** on startup in a git repo, Faber writes `.faber/` into `.git/info/exclude` (a local-only ignore — no diff, nothing committed), so state can never reach GitHub even if you forget `.gitignore`. If `.faber/` was already committed in the past, you get a loud red warning with the exact `git rm --cached` fix. Sessions and checkpoints can contain file contents — this protection exists so they never leak with production code. Teams: also add `.faber/` to the shared `.gitignore` so teammates are covered from their first run.
+Commit protection happens on its own. When Faber starts inside a git repo it writes `.faber/` into `.git/info/exclude`, a local ignore that produces no diff and is never committed, so project state can't reach GitHub even if you forget your `.gitignore`. If `.faber/` was already committed at some point in the past, you get a loud warning with the exact `git rm --cached` command to fix it. This matters because sessions and checkpoints can contain the contents of files the agent read. If teammates will use Faber too, add `.faber/` to the shared `.gitignore` so they're covered from their first run.
 
-## Failure-mode matrix
+## What happens when things go wrong
 
-| Failure | Behavior |
+| Situation | What Faber does |
 |---|---|
 | API 429/5xx/network drop | retry with backoff+jitter; Retry-After honored; clear fatal after N attempts |
 | Bad API key | immediate fatal naming the env var to set |
@@ -148,13 +273,13 @@ Per-project overrides: `.faber/config.json`.
 ## Testing
 
 ```bash
-npm test          # 30 offline tests — no API key needed
+npm test          # offline test suite, no API key needed
 node selftest.mjs # installation self-check + live agent verification (report file to share)
 ```
 
-The suite covers the awkward stuff on purpose: undo/redo round-trips, checkpoint ID collisions within one millisecond, session files torn mid-write, stopword-polluted recall queries, cyclic call graphs, CRLF + emoji surgical edits, mid-stream cancellation, steering-message role alternation, paste markers split across stream chunks, multi-paste + typed-text composition, doom-loop abort — plus three end-to-end tests that drive the real agent loop (and one that drives the real CLI binary) against a mock streaming API server.
+The suite deliberately covers the awkward cases rather than the easy ones: undo and redo round-trips, checkpoint ids colliding within the same millisecond, session files torn mid-write, cyclic call graphs, surgical edits through CRLF and emoji, cancellation mid-stream, steering messages keeping the API's role alternation valid, paste markers split across stream chunks, AWS signatures checked against the vector AWS publishes, credential files landing with owner-only permissions, a recorded cost staying put when prices later change, Responses-API tool calls assembled from their argument deltas, and usage windows that put a 45-day-old task in "last 3 months" but not "last 30 days". Several tests drive the real agent loop against a mock streaming server, and one drives the actual CLI binary.
 
-CI (`.github/workflows/ci.yml`): Ubuntu / macOS / Windows × Node 22 / 24 — tests, build, and CLI smoke on every push.
+CI runs on Ubuntu, macOS and Windows across Node 22 and 24: tests, build, and CLI smoke on every push.
 
 ## Architecture
 
@@ -163,18 +288,21 @@ CLI/REPL (index.ts)   streaming render · arrow-key approvals · steering captur
    │
 Agent loop (agent.ts) recall memory + repo map → [LLM ⇄ tools] → verify → summarize
    │                  doom-loop breaker · iteration cap · compaction · session log · steering drain
-   ├─ LLM (llm.ts)            Anthropic + OpenAI-compatible · SSE streaming · prompt caching · usage · retry
+   ├─ LLM (llm.ts)            three wires: Anthropic · OpenAI chat · OpenAI Responses · SSE · caching · retry
+   ├─ Routes (routes.ts)      vendor → route → model · SigV4 for Bedrock (sigv4.ts) · live model discovery
+   ├─ Pricing (pricing.ts)    per-model rates, modes and endpoints · conditional refresh · frozen at spend
    ├─ Tools (tools/)          validated dispatch · mutations staged as diffs · shell gated by approval
    ├─ Graph (indexer.ts)      symbols + call/import edges · incremental · who_calls / trace_path / map
    ├─ Memory (memory/)        shortTerm (window+compaction) · longTerm (SQLite+FTS) · sessions (JSONL)
    └─ Checkpoints             snapshot-before-write · /history · reversible restore
 
-All state in <repo>/.faber/   (memory.db, index.db, sessions/, checkpoints/)
+Per project  <repo>/.faber/    memory.db · index.db · usage.db · sessions/ · checkpoints/
+Per machine  ~/.faber/          settings.json (profiles) · credentials.json (0600) · cache/
 ```
 
 ## Roadmap
 
-Tree-sitter edges (compiler-grade graph) · Graphify `graph.json` integration · stale tool-result eviction · secret redaction in session logs · global user profile (~/.faber) · embedding recall · branch-per-task git mode · VS Code extension on this core.
+Google Vertex is defined but not yet wired up, since its OAuth flow is a bigger piece than Bedrock turned out to be. Beyond that: tree-sitter for compiler-grade graph edges, evicting stale tool results from long conversations, redacting secrets in session logs, team-shared project settings that can live in a repo, embedding-based recall, a branch-per-task git mode, a `/usage --all` view comparing every project on the machine, and a VS Code extension built on this core.
 
 ## License
 

package/dist/agent.js

@@ -42,6 +42,9 @@ export class Agent {
     events;
     /** Verbose mode: user asked for full-depth explanations (/verbose). */
     verbose = false;
+    /** Active model. Switching mid-session invalidates the prompt cache, since
+     *  cached prefixes are per-model — the next task pays full price once. */
+    model;
     /** Mid-task steering: lines typed while the agent works, injected at the
      *  next loop boundary so the model course-corrects without cancelling. */
     steerQueue = [];
@@ -57,6 +60,7 @@ export class Agent {
     constructor(config, approve, events = {}, resumeSessionId, askUser) {
         this.config = config;
         this.events = events;
+        this.model = config.model;
         this.llm = new LLMClient(config);
         this.usage = new UsageLedger(config.usageDb, config.workspace);
         this.checkpoints = new CheckpointManager(config.stateDir, config.workspace);
@@ -73,6 +77,21 @@ export class Agent {
                 this.events.onInfo?.(`Resumed session ${resumeSessionId} (${restored.length} messages).`);
         }
     }
+    setModel(id) {
+        this.model = id;
+        this.llm.setModel(id);
+    }
+    /**
+     * Adopt a new configuration in the running session, after /setup or /route
+     * changed the route. Without this the session keeps talking to the old
+     * provider while the settings file says otherwise, so /model would list
+     * models for a route the user thought they had left.
+     */
+    reconfigure(next) {
+        this.config = next;
+        this.model = next.model;
+        this.llm = new LLMClient(next);
+    }
     steer(text) {
         const t = text.trim();
         if (t)
@@ -191,7 +210,7 @@ export class Agent {
         finally {
             this.checkpoints.commit();
             if (total.calls > 0) {
-                this.usage.record(total, this.config.model);
+                this.usage.record(total, this.model, { in: this.config.priceIn, out: this.config.priceOut });
                 this.events.onUsage?.(total);
             }
         }

package/dist/config.js

@@ -7,6 +7,9 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { loadSettings, activeProfile } from "./settings.js";
+import { getRoute, resolveModel, baseUrlFor, ROUTES } from "./routes.js";
+import { resolveCredential, getCredential } from "./credentials.js";
 export const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5";
 export const DEFAULT_OPENAI_MODEL = "gpt-4o";
 /** Accept both FABER_* (canonical) and CW_* (legacy) env var names. */
@@ -42,16 +45,45 @@ export function loadConfig(workspace) {
         catch { /* ignore malformed */ }
     }
     const s = (k) => typeof fileCfg[k] === "string" ? fileCfg[k] : undefined;
-    const provider = (process.env.CW_PROVIDER ?? s("provider") ?? "anthropic").toLowerCase();
+    // Global profile sits below project config and above defaults.
+    const settings = loadSettings();
+    const prof = activeProfile(settings);
+    const route = getRoute(process.env.FABER_ROUTE ?? s("route") ?? prof.route) ?? ROUTES[0];
+    const pins = { ...(prof.modelPins ?? {}), ...(fileCfg["modelPins"] ?? {}) };
+    // The route decides the wire format unless a provider is set explicitly.
+    const provider = (process.env.CW_PROVIDER ?? s("provider") ?? route.wire).toLowerCase();
     const anthropic = provider === "anthropic";
+    const rawModel = process.env.CW_MODEL ?? s("model") ?? prof.model
+        ?? (anthropic ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL);
+    // Env var first, then the 0600 credential store — unless the profile says
+    // the stored key was chosen deliberately, in which case honour that.
+    const keyFromProfile = prof.apiKeyEnv
+        ? (prof.preferStoredKey
+            ? (getCredential(prof.apiKeyEnv) ?? resolveCredential(prof.apiKeyEnv))
+            : resolveCredential(prof.apiKeyEnv))
+        : undefined;
+    const region = process.env.FABER_REGION ?? s("region") ?? prof.region;
+    const routeUrl = baseUrlFor(route, region);
+    // A route-specific credential (e.g. BEDROCK_API_KEY) wins over the generic one.
+    const routeKey = route.keyEnv
+        ? (prof.preferStoredKey ? (getCredential(route.keyEnv) ?? resolveCredential(route.keyEnv))
+            : resolveCredential(route.keyEnv))
+        : undefined;
     return {
         workspace: ws,
         stateDir,
         provider,
-        model: process.env.CW_MODEL ?? s("model") ?? (anthropic ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL),
-        baseUrl: process.env.CW_BASE_URL ?? s("baseUrl") ?? (anthropic ? "https://api.anthropic.com" : "https://api.openai.com/v1"),
-        apiKey: anthropic ? (process.env.ANTHROPIC_API_KEY ?? s("apiKey")) : (process.env.OPENAI_API_KEY ?? s("apiKey")),
-        weakModel: process.env.CW_WEAK_MODEL ?? s("weakModel"),
+        model: resolveModel(rawModel, route, pins),
+        baseUrl: process.env.CW_BASE_URL ?? s("baseUrl") ?? prof.baseUrl ?? routeUrl
+            ?? (anthropic ? "https://api.anthropic.com" : "https://api.openai.com/v1"),
+        // A route that names its own credential (BEDROCK_API_KEY) must NOT fall
+        // back to the generic one: sending an Anthropic key to Bedrock produces a
+        // confusing 401 and hides the fact that AWS signing was available.
+        apiKey: routeKey ?? keyFromProfile ?? s("apiKey")
+            ?? (route.keyEnv
+                ? undefined
+                : resolveCredential(anthropic ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY")),
+        weakModel: process.env.CW_WEAK_MODEL ?? s("weakModel") ?? prof.weakModel,
         maxTokens: 4096,
         maxIterations: Number(process.env.CW_MAX_ITERATIONS ?? fileCfg["maxIterations"] ?? 40),
         contextTokenBudget: Number(process.env.CW_CONTEXT_BUDGET ?? fileCfg["contextTokenBudget"] ?? 60_000),
@@ -64,5 +96,16 @@ export function loadConfig(workspace) {
         indexDb: path.join(stateDir, "index.db"),
         sessionsDir: path.join(stateDir, "sessions"),
         usageDb: path.join(stateDir, "usage.db"),
+        route: route.id,
+        region,
+        modelPins: pins,
+        profileName: settings.activeProfile,
+        priceIn: Number(process.env.FABER_PRICE_IN) || prof.priceIn,
+        // On by default: costs are frozen per task, so silently stale prices would
+        // corrupt history permanently. Opt out with FABER_AUTO_PRICES=0.
+        autoRefreshPrices: process.env.FABER_AUTO_PRICES === "0" ? false
+            : process.env.FABER_AUTO_PRICES === "1" ? true
+                : prof.autoRefreshPrices !== false,
+        priceOut: Number(process.env.FABER_PRICE_OUT) || prof.priceOut,
     };
 }

package/dist/credentials.js

@@ -0,0 +1,134 @@
+/**
+ * Credential storage: ~/.faber/credentials.json, mode 0600.
+ *
+ * Deliberately OUTSIDE any project directory. A key written next to your code
+ * is one `git add -f`, one bad .gitignore, or one shared zip away from being
+ * public — and scanning bots find committed keys in minutes. Every tool that
+ * handles this well (aws, gcloud, npm, git) keeps secrets in the home
+ * directory and lets project config reference them by name.
+ *
+ * Resolution order for a credential:
+ *   1. the environment variable (CI, one-offs, and existing setups keep working)
+ *   2. this file, keyed by the same variable name
+ * Nothing else. Faber never writes a secret into a workspace.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export function credentialsPath() {
+    return path.join(os.homedir(), ".faber", "credentials.json");
+}
+function read(file = credentialsPath()) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(raw)) {
+            if (typeof v === "string")
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Look up a stored credential by the env var name it stands in for. */
+export function getCredential(envName, file = credentialsPath()) {
+    return read(file)[envName];
+}
+/** Env var wins, so CI and existing shells are never overridden by a saved key. */
+export function resolveCredential(envName, file = credentialsPath()) {
+    return process.env[envName] ?? getCredential(envName, file);
+}
+/** Where a credential came from — so Faber can say so instead of using it silently. */
+export function credentialSource(envName, file = credentialsPath()) {
+    const env = process.env[envName];
+    if (env)
+        return { value: env, from: "environment" };
+    const stored = getCredential(envName, file);
+    return stored ? { value: stored, from: "store" } : undefined;
+}
+/**
+ * Save a credential with owner-only permissions. Written to a temp file first
+ * and renamed, so a crash can't leave a half-written store — and chmod happens
+ * before the secret lands, never after.
+ */
+export function saveCredential(envName, value, file = credentialsPath()) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const store = read(file);
+    store[envName] = value;
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch { /* absent is fine */ }
+    fs.renameSync(tmp, file); // rename onto an existing file fails on Windows
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch { /* no-op where modes don't apply */ }
+}
+export function deleteCredential(envName, file = credentialsPath()) {
+    const store = read(file);
+    if (!(envName in store))
+        return false;
+    delete store[envName];
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch { /* absent is fine */ }
+    fs.renameSync(tmp, file);
+    return true;
+}
+/** Names of stored credentials — never the values. */
+export function listCredentialNames(file = credentialsPath()) {
+    return Object.keys(read(file)).sort();
+}
+/**
+ * Does this look like a real key for that variable?
+ * Deliberately loose — formats change, and refusing a valid key is worse than
+ * accepting an odd one. This only catches obvious mistakes: a typo, a pasted
+ * filename, an accidental keystroke. Returns a reason when it looks wrong.
+ */
+export function looksLikeKey(envName, value) {
+    const v = value.trim();
+    if (v.length < 20)
+        return "that looks too short for an API key";
+    if (/\s/.test(v))
+        return "that contains spaces";
+    if (envName === "ANTHROPIC_API_KEY" && !v.startsWith("sk-ant-")) {
+        return "Anthropic keys normally start with sk-ant-";
+    }
+    if (envName === "OPENAI_API_KEY" && !v.startsWith("sk-")) {
+        return "OpenAI keys normally start with sk-";
+    }
+    return undefined;
+}
+/** Show a key without exposing it: sk-ant-…4f2a */
+export function maskCredential(value) {
+    if (value.length <= 12)
+        return "…".repeat(Math.max(1, value.length - 2)) + value.slice(-2);
+    return `${value.slice(0, 7)}…${value.slice(-4)}`;
+}
+/**
+ * True when the file is readable by anyone but the owner.
+ * Windows has no POSIX mode bits — Node reports a synthetic value there, so
+ * checking it would warn every Windows user on every launch. Access control
+ * on that platform comes from NTFS ACLs, which this can't inspect.
+ */
+export function permissionsAreLoose(file = credentialsPath()) {
+    if (process.platform === "win32")
+        return false;
+    try {
+        return (fs.statSync(file).mode & 0o077) !== 0;
+    }
+    catch {
+        return false;
+    }
+}