auto-model-router 0.20.0 → 0.21.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.20.0",
+      "version": "0.21.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -762,9 +762,10 @@ virtual profile it picked. Every routed response carries
 
 The ledger records every dispatch: model decided and served, tier, provider,
 tokens (including cached), reported cost, time to first token, total latency,
-escalation signal, error, and the agentdox context scope the turn carried (the
+escalation signal, error, the agentdox context scope the turn carried (the
 project it belongs to; NULL for a turn that carried none, and for every row
-written before v0.19.0). Three views aggregate it, all from the same
+written before v0.19.0) and how many strings redaction removed from the request
+(NULL when redaction was off, and for every row written before v0.21.0). Three views aggregate it, all from the same
 `buildUsageReport` in `src/cost/report.ts`:
 
 - `/router report` in omp — a fullscreen hub with the `/models` look: views
@@ -802,6 +803,8 @@ written before v0.19.0). Three views aggregate it, all from the same
   a comma-separated set of ids, for a group).
 - `GET /v1/router/summary?harness=<id>` — the daily summary as JSON (`auto=1`
   applies the once-a-day gate and returns `due: false` when nothing is due).
+- `POST /v1/router/prune` — applies `ledger.retentionDays` now and answers
+  `{ deleted, oldestKeptMs, retentionDays }`. See [Data governance](#data-governance).
 
 What it shows, for the window:
 
@@ -1160,7 +1163,28 @@ task needed, and `digest.maxOutputTokens` or `digest.model` is the lever.
 | `blendMinSamples` | `25` | Turns before the measured blend replaces the fallback. |
 | `fallbackBlend` | input `1.5`, output `7.5` | Pre-measurement blend (USD/Mtok) for omp's cost display. |
 | `conversationTtlMs` | `604800000` (7 d) | Drop conversation state untouched this long. |
-| `retentionDays` | `365` | Delete ledger rows older than this, checked hourly; `0` keeps everything. The ledger grows about 2.5 MB a day under steady use. Freed pages are reused, so the file stops growing rather than shrinking. |
+| `retentionDays` | `null` | Delete ledger rows — and the feedback keyed to them — older than this many days, checked at most hourly; `null` (the default) and `0` keep everything. The ledger grows about 2.5 MB a day under steady use. See [Data governance](#data-governance). |
+
+### `redaction` — keep configured strings out of every request
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Apply the rules to every outgoing request. Off means the router never touches the prompt. |
+| `rules` | `[]` | `{ name, pattern, replacement? }` entries. `pattern` is a regular-expression source compiled once at load under a guard (see [Data governance](#data-governance)); `replacement` defaults to `[redacted:<name>]`. At most 64 rules. |
+| `scanTools` | `false` | Also scan tool-call arguments and tool results, not just message text. |
+
+```yaml
+# ~/.auto-model-router/config.yml
+redaction:
+  enabled: true
+  scanTools: true
+  rules:
+    - name: api key
+      pattern: "sk-live-[A-Za-z0-9]{16,}"
+    - name: customer id
+      pattern: "(?:acct|customer)-\\d{6}"
+      replacement: "<customer>"
+```
 
 ### Top-level
 
@@ -1372,6 +1396,92 @@ ignored rather than failing the turn. The decision trail records what the
 policy changed (`policy: …`), and `GET /v1/router/catalog?policy=…` shows what a
 policy admits, model by model, without routing a turn.
 
+## Data governance
+
+Two things an operator with a compliance obligation needs from a router: that
+certain strings never reach a provider, and that they can say how long a record
+of the traffic is kept. Both are off by default — the router does not touch a
+prompt or delete a row unless it is told to. Design notes:
+[`docs/data-governance.md`](docs/data-governance.md).
+
+### Redaction, before a provider sees the prompt
+
+With `redaction.enabled`, every rule is applied to the outgoing request
+**immediately after it is rendered and before anything can dispatch it**. That
+is one place, deliberately: all three front ends (chat completions, Responses,
+Anthropic Messages) normalise to the same request shape, and every upstream
+client — OpenRouter, Ollama, a named OpenAI/Anthropic/vLLM upstream — renders
+its own protocol from it. A provider added later is covered without being told.
+
+Message text is always scanned, including the system prompt and the injected
+agentdox block. With `scanTools`, tool-call arguments and tool results are too
+— which is where the bytes are (a turn's prompt is mostly file content), and
+also where the secret an agent just read from disk actually is. Tool names, ids
+and schemas are never rewritten: they are the harness's vocabulary, and editing
+one would break the call/result pairing the model needs. A match becomes
+`[redacted:<name>]`, or the rule's own `replacement`. Nothing else about the
+turn changes — same routing, same cache breakpoints, same bytes otherwise.
+
+**The pattern guard.** A rule is configuration meeting text from a user, run
+against megabytes of tool output on every turn, which is exactly the shape that
+backtracks. So a pattern is compiled ONCE at load and these are refused, with
+the reason and the rule's name, rather than trusted:
+
+| Refused | Why |
+| --- | --- |
+| A nested unbounded quantifier — `(a+)+`, `(\d{2,})*` | The classic catastrophic shape: the ways to split one input across both quantifiers grow exponentially with its length. A **bounded** outer quantifier is fine, so `(?:\d{1,3}\.){3}\d{1,3}` still loads. |
+| An alternation under an unbounded quantifier — `(?:a\|a)*` | The other one: branches that can match the same input many ways. An alternation not under one (`(?:acct\|customer)-\d{6}`) is fine. |
+| A backreference — `\1`, `\k<name>` | Takes the pattern outside the regular languages, where no bound on matching time exists at all. |
+| A pattern that matches the empty string | It would replace at every position, turning the prompt into replacement text. |
+| A pattern over 512 characters, or a set over 64 rules | A rule describes the shape of a secret. Every real one is short. |
+| A pattern that does not compile | Reported with the engine's own message. |
+
+Patterns compile with the `u` flag where possible — it rejects sloppy escapes
+at load rather than letting them mean something else, and makes matching work
+on code points — falling back to no flag for a legacy pattern that only `u`
+rejects, so an operator's working rule does not break on an upgrade. A refused
+rule is a **startup error**, not a warning: a rule the operator believes is
+removing something must never be a rule the router quietly skipped. The same
+guard is exported as `validateRedactionPattern`, so a front door can reject a
+rule while an operator is typing it, with the message the router would use.
+
+**The evidence, without the secret.** Every ledger row carries `redactions`,
+the number of strings removed from that turn's request — a count and nothing
+else, because the matched text is precisely what must not exist outside the
+client. Nothing logs a match at any level. `GET /v1/router/report` totals it as
+`redactions` with `redactedTurns` beside it, so a front door can show "N turns
+had something removed", and the rendered report prints the same line. A row
+written before v0.21.0, or a turn with redaction off, stores NULL, which is a
+different fact from `0` (the rules ran and matched nothing).
+
+### Ledger retention
+
+`ledger.retentionDays` says how long turns are kept. `null` — the default — and
+`0` keep everything; a number deletes ledger rows older than that many days,
+along with the user verdicts (`/router good|bad`) keyed to them and the Ollama
+meter samples that calibrate them. Keeping is the default because deleting is
+the direction that cannot be undone, and how long a record of what people asked
+a model lives is an operator's decision, not a default's.
+
+The prune runs on the router's own housekeeping schedule, **at most once an
+hour** however often it is asked, and once shortly after boot so a lowered
+window applies without waiting. Freed pages are handed back to the filesystem
+where the engine can (a ledger created at v0.21.0 or later is
+`auto_vacuum=INCREMENTAL`; an older file reuses them instead), and the WAL is
+folded back so the space is real on disk.
+
+```
+POST /v1/router/prune        →  { "deleted": 12043, "oldestKeptMs": 1782720000000, "retentionDays": 365 }
+```
+
+`oldestKeptMs` is the timestamp of the oldest row still in the ledger — how far
+back it now goes, which is what the question was actually about; `null` when it
+is empty. The route exists because a front door of the team edition holds a
+**read-only** handle on the ledger file by design and must never delete from it
+itself: it triggers the router's own prune and reads the counts back. It obeys
+the same hourly floor, so calling it in a loop is harmless, and it needs
+`server.apiKey` like every other route.
+
 ## Using a remote router
 
 `auto-model-router connect --url <router> --key <key>` points this machine at a router

package/docs/data-governance.md

@@ -0,0 +1,210 @@
+# Data governance: redaction and ledger retention
+
+Design notes for the two controls an operator with a compliance obligation
+needs from the router — keeping strings out of every request, and saying how
+long the record of a turn is kept. The README section
+([Data governance](../README.md#data-governance)) is the operator's view; this
+is where the decisions and their reasons live.
+
+Both ship **off**. A router that has not been told otherwise does not touch a
+prompt and does not delete a row.
+
+---
+
+## 1. Redaction
+
+### Where it sits, and why there
+
+```
+wire in                       core                          wire out
+─────────────────────────────────────────────────────────────────────────────
+POST /v1/chat/completions ─┐
+POST /v1/responses ────────┼─► parseChatRequest ─► route ─► renderUpstreamBody
+POST /v1/messages ─────────┘        (NormRequest)                    │
+                                                                     ▼
+                                                      ┌──── REDACTION ────┐
+                                                      │ redactUpstreamBody│
+                                                      └─────────┬─────────┘
+                                                                ▼
+                                                        upstream.dispatch
+                                                 ┌──────────────┼──────────────┐
+                                            OpenRouter       Ollama      named upstream
+                                                                        (openai/anthropic/vllm)
+```
+
+`src/server/turn.ts` calls `redactUpstreamBody` between
+`req.renderUpstreamBody(...)` and `upstream.dispatch({ body, ... })`. That is
+the only choke point that covers everything, and it covers it by construction:
+
+- **Every wire in** ends up in the same shape. The Responses wire
+  (`responsesToChatBody`) and the Anthropic Messages wire (`messagesToChatBody`)
+  both translate into the chat-completions body before `parseChatRequest` sees
+  it, and `renderUpstreamBody` has exactly one implementation
+  (`src/wire/openai/request.ts`).
+- **Every provider out** renders its own protocol *from* that body —
+  `src/upstream/openrouter.ts`, `ollama.ts`, `anthropic.ts`, `compat.ts`. A
+  provider added later inherits the guard without being told about it.
+
+Redacting the `NormRequest` instead would not work: `NormMessage.text` is a
+lossy concatenation used only for classification, and nothing is ever
+dispatched from it. Redacting inside each upstream client would work and would
+be wrong — it is four places today and five tomorrow.
+
+Ordering inside the turn also matters. Redaction runs *after* compaction edits,
+the agentdox context block and the cache breakpoints have been applied, so the
+injected project context is scanned too and a rewritten text part keeps its
+`cache_control` marker.
+
+### What is scanned
+
+| Field | Scanned |
+| --- | --- |
+| `messages[].content` (string, and `type: "text"` parts) for every non-tool role | always |
+| `messages[].content` for `role: "tool"` (tool results) | `scanTools` |
+| `messages[].tool_calls[].function.arguments` | `scanTools` |
+| tool names, tool-call ids, `tools[]` schemas, `model` | never |
+
+Tool results and arguments are gated because they are most of a turn's prompt
+bytes, so scanning them is most of the CPU — and, for an operator who cares
+about a secret in a file the agent just read, most of the point. Names and ids
+are never touched because rewriting one breaks the call/result pairing the
+model needs; a model slug is the router's own vocabulary, not conversation
+content.
+
+An `image_url` part is skipped: it carries a data URI that no redaction rule
+can meaningfully read and that every rule would be slow over.
+
+### The pattern guard
+
+`src/config/redaction.ts`. A rule is configuration meeting text from a user,
+which is the exact shape that backtracks — a pattern an operator wrote once,
+run against megabytes of tool output on every turn of every conversation. A
+redaction rule that hangs a request is worse than no rule at all, so the
+pattern is compiled once at load and these are refused:
+
+1. **A nested unbounded quantifier.** `(a+)+`, `(\d{2,})*`, `([a-z]*)+`. The
+   number of ways to split one input across two unbounded quantifiers grows
+   exponentially with its length, so a single non-matching tool result can pin
+   a core for minutes. Detected by walking the source once, tracking group
+   spans (honouring escapes and character classes) and checking the body of any
+   group that carries `*`, `+` or `{n,}`. A **bounded** outer quantifier is
+   fine, which is why `(?:\d{1,3}\.){3}\d{1,3}` — the shape real rules use —
+   still loads.
+2. **An alternation under an unbounded quantifier.** `(?:a|a)*`. The other
+   textbook exponential shape. An alternation that is not under one is fine.
+3. **A backreference** (`\1`, `\k<name>`). It takes the pattern outside the
+   regular languages, so no bound on matching time exists for it at all.
+4. **A pattern that matches the empty string.** It would replace at every
+   position and turn the prompt into replacement text.
+5. **A pattern over 512 characters, or a set over 64 rules.** A rule describes
+   the shape of a secret; every real one is short and literal.
+6. **A pattern that does not compile**, reported with the engine's message.
+
+Compilation prefers the `u` flag: it rejects sloppy escapes and malformed
+quantifiers at load rather than letting them silently mean something else, and
+it makes matching operate on code points, so a rule cannot be defeated by an
+astral character splitting a surrogate pair. A pattern that only `u` rejects
+(an unescaped `{`, an octal escape) falls back to no flag — an operator's
+working rule must not break on an upgrade — so `u` is a preference, not a
+requirement.
+
+Refusal happens in two places, deliberately. The config schema
+(`configInputSchema`) rejects a file rule with the path and reason, so
+`config.yml` fails at load; `startServer` compiles the rule set again before
+the listener exists, which is where an embedder's programmatic overrides — they
+never pass through the schema — are caught. Either way a bad rule is an error,
+never a warning: a rule the operator believes is removing something must never
+be a rule the router quietly skipped.
+
+Compiled rules are memoised on the rules' own text (`redactionRulesFor`), not
+on the config object's identity, because hot reload and `reconfigure` mutate
+the live config **in place** — a reference check would miss an edit. So an
+edited rule set compiles once more and an unedited one is a map lookup on the
+turn path.
+
+### The evidence
+
+`LedgerEntry.redactions` → `ledger.redactions INTEGER`, schema **v19**, added
+the way `scope` was at v18: a guarded `ALTER TABLE ... ADD COLUMN` on open plus
+a `USER_VERSION` bump, so an old ledger opens and gains the column with its
+rows NULL. Three states, all meaningful:
+
+| Value | Means |
+| --- | --- |
+| `NULL` | redaction was off for this turn (or the row predates v19) |
+| `0` | the rules ran and matched nothing |
+| `n` | `n` strings were removed from this turn's request |
+
+`buildUsageReport` totals it as `redactions` with `redactedTurns`
+(`COUNT(redactions > 0)`) beside it, and the rendered report prints one line
+when there is something to say. Nothing anywhere records the matched text: the
+turn logs a debug line with a count, and the startup line lists rule *names*
+only. A redaction log that quotes the secret is just a second copy of the
+secret.
+
+---
+
+## 2. Ledger retention
+
+### The window
+
+`ledger.retentionDays: number | null`. `null` is the default and `0` means the
+same thing: keep everything. Keeping is the default because deleting is the
+direction that cannot be undone, and because how long a record of what people
+asked a model lives is a decision an operator makes for their deployment, not
+one a library default should make for them. (Before v0.21.0 the default was
+365 days.)
+
+### What goes
+
+`createLedger(...).prune(retentionDays, nowMs)` deletes, in this order:
+
+1. `feedback` rows — the user verdicts from `/router good|bad` — matched by
+   *both* their own age and the ledger rows about to go
+   (`ledger_id IN (SELECT id FROM ledger WHERE created_at_ms < ?)`), so
+   verdicts orphaned by a prune from an older version are swept up too. First,
+   because the subquery needs the rows that are about to be deleted.
+2. `ollama_meter_samples` past the cutoff. They only calibrate the ledger's own
+   Ollama estimate, so they age out with the rows they calibrate.
+3. `ledger` rows past the cutoff.
+
+Then, when anything was deleted, `PRAGMA incremental_vacuum` hands freed pages
+back to the filesystem and `PRAGMA wal_checkpoint(TRUNCATE)` folds the WAL so
+the space is real on disk. Both are best-effort inside a `try`: a ledger that
+could not shrink is a far smaller problem than a prune that throws.
+`openDb` sets `PRAGMA auto_vacuum = INCREMENTAL` before the journal mode, which
+SQLite honours only for a **new** database — an existing ledger keeps its mode
+and reuses freed pages instead of releasing them, which is the pre-v0.21.0
+behaviour and is fine.
+
+`PruneResult` is `{ deleted, oldestKeptMs }`. `oldestKeptMs` is
+`MIN(created_at_ms)` over what remains (null when the ledger is empty) — the
+honest answer to "how far back does this ledger go now", which is what the
+question was actually about, and it is reported even when nothing was deleted.
+
+### The schedule, and the route
+
+`createRetentionRunner` (`src/cost/retention.ts`) owns the once-an-hour floor.
+Three callers share it and none of them can bypass it:
+
+- the server's one-minute housekeeping timer, which calls `maybeRun()`;
+- a `setTimeout` five seconds after boot, so a lowered window applies without
+  waiting out an hour (the first call is always due);
+- `POST /v1/router/prune`, which calls `runNow()` — always doing the work,
+  because the caller wants the counts, and marking the schedule satisfied for
+  the next hour, because a prune that just ran is a prune that just ran.
+
+The window is read through a function rather than captured, so a hot reload or
+an embedder's `reconfigure` changes it without restarting anything.
+
+The route exists for one reason: a front door of the team edition holds a
+**read-only** handle on the ledger file by design and must never delete from
+it. It asks the router, and gets back:
+
+```json
+{ "deleted": 12043, "oldestKeptMs": 1782720000000, "retentionDays": 365 }
+```
+
+It is guarded by `server.apiKey` like every other route, and it is safe to call
+in a loop: the second call inside the hour still returns the counts, having
+found nothing left to delete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/config-wizard.ts

@@ -362,7 +362,17 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "ledger.fallbackBlend.inputPerMtok", label: "Fallback blend input $/Mtok", kind: "number", min: 0 },
 			{ path: "ledger.fallbackBlend.outputPerMtok", label: "Fallback blend output $/Mtok", kind: "number", min: 0 },
 			{ path: "ledger.conversationTtlMs", label: "Conversation TTL", kind: "number", min: 1, hint: "ms" },
-			{ path: "ledger.retentionDays", label: "Ledger retention", kind: "number", min: 0, hint: "days; 0 keeps everything" },
+			{ path: "ledger.retentionDays", label: "Ledger retention", kind: "number", min: 0, optional: true, hint: "days; 0 or cleared keeps everything" },
+		],
+	},
+	{
+		title: "Redaction",
+		fields: [
+			{ path: "redaction.enabled", label: "Remove configured strings from outgoing requests", kind: "boolean" },
+			{ path: "redaction.scanTools", label: "Also scan tool arguments and tool results", kind: "boolean" },
+			// `redaction.rules` is a list of name/pattern records, edited in the
+			// config file (or by a front door) rather than one prompt at a time —
+			// the same treatment `profiles` and `upstreams` get.
 		],
 	},
 	{

package/src/config/defaults.ts

@@ -385,8 +385,14 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// so early cost reporting never underreports.
 		fallbackBlend: { inputPerMtok: 1.5, outputPerMtok: 7.5 },
 		conversationTtlMs: 7 * 24 * 60 * 60 * 1000,
-		retentionDays: 365,
+		// Keep everything until an operator says otherwise: how long a record of
+		// what people asked a model lives is their decision, and deleting is the
+		// direction that cannot be undone. `POST /v1/router/prune` and the hourly
+		// scheduler both do nothing while this is null.
+		retentionDays: null,
 	},
+	// Off, with no rules: redaction only ever removes what an operator names.
+	redaction: { enabled: false, rules: [], scanTools: false },
 	// On by default: an absolute floor that no available model meets is how the
 	// router ends up serving every turn from the cheapest tier.
 	adaptiveTierFloors: true,

package/src/config/hot-reload.ts

@@ -95,8 +95,9 @@ export interface WatchConfigOptions {
  * Config paths captured at construction, so a file edit cannot reach the
  * running process: the socket, the upstream clients, the agentdox bridge, the
  * ledger file. Everything else, including `ollama.costBias`,
- * `ollama.biasUntilUsage`, `server.subagentProfile` and `ledger.retentionDays`,
- * is read at call time and hot-reloads. A bare block name pins the whole
+ * `ollama.biasUntilUsage`, `server.subagentProfile`, `ledger.retentionDays` and
+ * the whole `redaction` block (rules recompile when their text changes), is
+ * read at call time and hot-reloads. A bare block name pins the whole
  * block; `block.key` pins one key and lets its siblings through.
  */
 /**