auto-model-router 0.20.0 → 0.22.0

package/src/config/redaction.ts

@@ -0,0 +1,265 @@
+/**
+ * Redaction rules: the guard that decides which patterns are allowed to run,
+ * and the compiler that turns a rule set into regular expressions once.
+ *
+ * A rule is configuration meeting text from a user, which is exactly the 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 the constructs with exponential worst cases are REFUSED rather
+ * than trusted — the same view `src/context/scope.ts` takes of regular
+ * expressions anywhere near the turn path.
+ *
+ * The refusal happens here, in config, so a bad rule is a startup error naming
+ * the rule and the reason, never a rule the router quietly skipped while the
+ * operator believed it was removing something. `src/server/redact.ts` applies
+ * what this compiles.
+ */
+
+import type { RedactionConfig, RedactionRule } from "./types.ts";
+
+/** One rule with its pattern already compiled. */
+export interface CompiledRedactionRule {
+	name: string;
+	/** Global; `replace` owns `lastIndex`. */
+	regex: RegExp;
+	replacement: string;
+}
+
+/**
+ * Bounds on a rule, all deliberately small. A redaction rule describes the
+ * SHAPE OF A SECRET — an API key prefix, an account number, an internal
+ * hostname — and every real one is short and literal. A pattern that needs
+ * more than this is doing something a redaction rule should not.
+ */
+const MAX_PATTERN_CHARS = 512;
+export const MAX_REDACTION_RULES = 64;
+
+/** A rule name: it is echoed into the prompt as `[redacted:<name>]`, so it stays boring. */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/;
+
+/** The replacement a rule without one gets. Names the rule, never the match. */
+export function defaultReplacement(name: string): string {
+	return `[redacted:${name}]`;
+}
+
+/** Is `source[i]` an unbounded quantifier (`*`, `+`, `{n,}`)? Returns its length, or 0. */
+function unboundedQuantifierAt(source: string, i: number): number {
+	const c = source[i];
+	if (c === "*" || c === "+") return 1;
+	if (c !== "{") return 0;
+	const close = source.indexOf("}", i);
+	if (close < 0) return 0;
+	// `{n,}` is unbounded; `{n}` and `{n,m}` are not.
+	return /^\{\d+,\}$/.test(source.slice(i, close + 1)) ? close + 1 - i : 0;
+}
+
+/**
+ * Walks a pattern source once, character by character, honouring escapes and
+ * character classes, and reports the first construct we refuse to run.
+ *
+ * Two are refused, and they are the two that make a backtracking engine
+ * exponential rather than merely slow:
+ *
+ *  - **A backreference** (`\1`, `\k<name>`). It takes the pattern outside the
+ *    regular languages, so no linear-time strategy exists for it at all.
+ *  - **An unbounded quantifier over a group that itself repeats without bound
+ *    or offers a choice** — `(a+)+`, `(?:a|a)*`. These are the textbook
+ *    catastrophic shapes: the number of ways to split the same input across
+ *    the two quantifiers (or the two branches) grows exponentially with its
+ *    length, so a single non-matching tool result can pin a core for minutes.
+ *    A bounded outer quantifier is fine, which is why `(?:\d{1,3}\.){3}` — the
+ *    shape real rules actually use — still loads.
+ */
+function refusedConstruct(source: string): string | null {
+	const groupStarts: number[] = [];
+	let inClass = false;
+	for (let i = 0; i < source.length; i++) {
+		const c = source[i]!;
+		if (c === "\\") {
+			const next = source[i + 1];
+			if (!inClass && next !== undefined && (/[1-9]/.test(next) || next === "k")) {
+				return "backreferences (\\1, \\k<name>) are not allowed: they take the pattern outside the regular languages, where no bound on matching time exists";
+			}
+			i++;
+			continue;
+		}
+		if (inClass) {
+			if (c === "]") inClass = false;
+			continue;
+		}
+		if (c === "[") {
+			inClass = true;
+			continue;
+		}
+		if (c === "(") {
+			groupStarts.push(i);
+			continue;
+		}
+		if (c !== ")") continue;
+		const start = groupStarts.pop();
+		// Unbalanced: `new RegExp` reports it far better than we could.
+		if (start === undefined) continue;
+		if (unboundedQuantifierAt(source, i + 1) === 0) continue;
+		const body = source.slice(start + 1, i);
+		if (containsUnbounded(body)) {
+			return `nested unbounded quantifiers ("${source.slice(start, i + 2)}"): a group that repeats without bound must not repeat without bound inside, or matching can take exponential time`;
+		}
+		if (containsAlternation(body)) {
+			return `an alternation inside an unbounded quantifier ("${source.slice(start, i + 2)}"): the branches can match the same input many ways, so matching can take exponential time`;
+		}
+	}
+	return null;
+}
+
+/** Does this fragment contain an unbounded quantifier outside a class or escape? */
+function containsUnbounded(fragment: string): boolean {
+	let inClass = false;
+	for (let i = 0; i < fragment.length; i++) {
+		const c = fragment[i]!;
+		if (c === "\\") {
+			i++;
+			continue;
+		}
+		if (inClass) {
+			if (c === "]") inClass = false;
+			continue;
+		}
+		if (c === "[") inClass = true;
+		else if (unboundedQuantifierAt(fragment, i) > 0) return true;
+	}
+	return false;
+}
+
+/** Does this fragment contain an alternation outside a class or escape? */
+function containsAlternation(fragment: string): boolean {
+	let inClass = false;
+	for (let i = 0; i < fragment.length; i++) {
+		const c = fragment[i]!;
+		if (c === "\\") {
+			i++;
+			continue;
+		}
+		if (inClass) {
+			if (c === "]") inClass = false;
+			continue;
+		}
+		if (c === "[") inClass = true;
+		else if (c === "|") return true;
+	}
+	return false;
+}
+
+/**
+ * Compiles one pattern under the guard, or returns why it was refused.
+ *
+ * Unicode first: `u` rejects sloppy escapes and malformed quantifiers at load
+ * rather than silently meaning something else, and it makes `.` and classes
+ * operate on code points, so a rule cannot be defeated by an astral character
+ * splitting a surrogate pair. A legacy pattern that only `u` rejects (an
+ * unescaped `{`, an octal escape) still loads without it — an operator's
+ * working rule should not break on an upgrade — so `u` is a preference, not a
+ * requirement.
+ *
+ * Exported so a front door (the team edition's dashboard) can tell an operator
+ * a rule is bad while they are typing it, with the same message the router
+ * would refuse it with.
+ */
+export function compileRedactionPattern(source: string): { regex: RegExp } | { error: string } {
+	if (source === "") return { error: "pattern must not be empty" };
+	if (source.length > MAX_PATTERN_CHARS) {
+		return { error: `pattern is ${source.length} characters; the limit is ${MAX_PATTERN_CHARS}` };
+	}
+	const refused = refusedConstruct(source);
+	if (refused !== null) return { error: refused };
+	let regex: RegExp | null = null;
+	let unicode = true;
+	try {
+		regex = new RegExp(source, "gu");
+	} catch {
+		unicode = false;
+	}
+	if (regex === null) {
+		try {
+			regex = new RegExp(source, "g");
+		} catch (err) {
+			return { error: `pattern does not compile: ${err instanceof Error ? err.message : String(err)}` };
+		}
+	}
+	// A pattern that matches the empty string would replace at every position,
+	// turning the prompt into replacement text. Cheaper to refuse than to
+	// special-case. Tested on a non-global copy so `lastIndex` stays untouched.
+	if (new RegExp(source, unicode ? "u" : "").test("")) {
+		return { error: "pattern matches the empty string, which would replace every position in the prompt" };
+	}
+	return { regex };
+}
+
+/** The reason a pattern is refused, or null when it is fine. */
+export function validateRedactionPattern(source: string): string | null {
+	const result = compileRedactionPattern(source);
+	return "error" in result ? result.error : null;
+}
+
+/**
+ * The reason a rule is refused, or null. Checks the name too, since it is
+ * echoed into the prompt. Takes the two fields it reads rather than a whole
+ * `RedactionRule`, so the config schema can hand it a parsed input object.
+ */
+export function validateRedactionRule(rule: { name: string; pattern: string }): string | null {
+	if (!NAME_RE.test(rule.name)) {
+		return "name must be 1-64 characters of letters, digits, spaces, dot, underscore or dash";
+	}
+	return validateRedactionPattern(rule.pattern);
+}
+
+/**
+ * Compiles a whole rule set. Throws on the first bad rule, naming it: a
+ * redaction rule that does not load is a hole in the guard, so the router
+ * refuses to start rather than quietly forwarding what the operator believed
+ * was being removed.
+ */
+export function compileRedactionRules(rules: readonly RedactionRule[]): CompiledRedactionRule[] {
+	if (rules.length > MAX_REDACTION_RULES) {
+		throw new Error(`redaction.rules has ${rules.length} rules; the limit is ${MAX_REDACTION_RULES}`);
+	}
+	const out: CompiledRedactionRule[] = [];
+	for (const rule of rules) {
+		const compiled = compileRedactionPattern(rule.pattern);
+		if ("error" in compiled) throw new Error(`redaction rule "${rule.name}": ${compiled.error}`);
+		if (!NAME_RE.test(rule.name)) {
+			throw new Error(`redaction rule "${rule.name}": name must be 1-64 characters of letters, digits, spaces, dot, underscore or dash`);
+		}
+		out.push({
+			name: rule.name,
+			regex: compiled.regex,
+			replacement: rule.replacement ?? defaultReplacement(rule.name),
+		});
+	}
+	return out;
+}
+
+/**
+ * Compiled rules for a config, memoised on the rules themselves.
+ *
+ * The turn path must not recompile a pattern per turn, and the live config is
+ * MUTATED in place by hot reload and by an embedder's `reconfigure`, so a
+ * reference check would miss an edit. The signature is the rules' own text —
+ * a few short strings, joined — so an edited rule set compiles once more and
+ * an unedited one is a map lookup.
+ */
+const compiledCache = new Map<string, CompiledRedactionRule[]>();
+
+export function redactionRulesFor(cfg: RedactionConfig): CompiledRedactionRule[] {
+	if (!cfg.enabled || cfg.rules.length === 0) return [];
+	// NUL-separated so no rule text can forge another rule's boundary.
+	const signature = cfg.rules.map((r) => [r.name, r.pattern, r.replacement ?? ""].join("\u0000")).join("\u0001");
+	const hit = compiledCache.get(signature);
+	if (hit !== undefined) return hit;
+	const compiled = compileRedactionRules(cfg.rules);
+	// One process can host several routers (the team edition restarts an
+	// embedded one on the same port); keep the map from growing with them.
+	if (compiledCache.size >= 16) compiledCache.clear();
+	compiledCache.set(signature, compiled);
+	return compiled;
+}

package/src/config/schema.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MAX_REDACTION_RULES, validateRedactionRule } from "./redaction.ts";
 
 /**
  * Input schema for `$AUTO_MODEL_ROUTER_HOME/config.yml`: a deep partial of
@@ -269,7 +270,29 @@ const ledger = z.strictObject({
 	blendMinSamples: z.number().int().nonnegative().optional(),
 	fallbackBlend: fallbackBlend.optional(),
 	conversationTtlMs: z.number().positive().optional(),
-	retentionDays: z.number().int().nonnegative().optional(),
+	// `null` and 0 both mean "keep everything"; null is the default.
+	retentionDays: z.number().int().nonnegative().nullable().optional(),
+});
+
+/**
+ * Redaction rules are compiled at load, and a pattern that cannot be run
+ * safely is rejected HERE, with the reason, rather than at the first turn:
+ * a rule an operator believes is removing something must never be a rule the
+ * router quietly skipped.
+ */
+const redactionRule = z.strictObject({
+	name: z.string().min(1),
+	pattern: z.string().min(1),
+	replacement: z.string().optional(),
+}).superRefine((rule, ctx) => {
+	const reason = validateRedactionRule(rule);
+	if (reason !== null) ctx.addIssue({ code: "custom", message: reason });
+});
+
+const redaction = z.strictObject({
+	enabled: z.boolean().optional(),
+	rules: z.array(redactionRule).max(MAX_REDACTION_RULES).optional(),
+	scanTools: z.boolean().optional(),
 });
 
 // Complete entries: arrays replace wholesale, so a partial profile would
@@ -342,6 +365,7 @@ export const configInputSchema = z.strictObject({
 		})
 		.optional(),
 	ledger: ledger.optional(),
+	redaction: redaction.optional(),
 	adaptiveTierFloors: z.boolean().optional(),
 	adaptivePriceCeilings: z.boolean().optional(),
 	logLevel: logLevel.optional(),

package/src/config/types.ts

@@ -710,12 +710,58 @@ export interface LedgerConfig {
 	/** Drop conversation state untouched for longer than this, ms. */
 	conversationTtlMs: number;
 	/**
-	 * Delete ledger rows older than this many days (checked hourly). 0 keeps
-	 * everything. The ledger grows ~2.5 MB a day under steady use; trust,
-	 * reports and replay only read windows well inside a year. Freed pages
-	 * are reused, so the file stops growing rather than shrinking.
+	 * Delete ledger rows — and the feedback keyed to them — older than this
+	 * many days, checked at most hourly. `null` (the default) and 0 both keep
+	 * everything.
+	 *
+	 * The default is to keep, because how long a record of what people asked a
+	 * model is retained is a decision an operator makes, not one a default
+	 * should make for them: deleting is the irreversible direction. The ledger
+	 * grows ~2.5 MB a day under steady use, and trust, reports and replay only
+	 * read windows well inside a year, so a deployment that wants a window
+	 * loses nothing by setting one. Freed pages are reused (and released where
+	 * the engine can), so the file mostly stops growing rather than shrinking.
+	 */
+	retentionDays: number | null;
+}
+
+/** One redaction rule: a name, the pattern it matches, and what replaces a match. */
+export interface RedactionRule {
+	/**
+	 * Identifies the rule in errors and in the default replacement. Echoed into
+	 * the prompt as `[redacted:<name>]`, so it must not itself be a secret.
+	 */
+	name: string;
+	/**
+	 * Regular-expression SOURCE (no delimiters, no flags), compiled once at
+	 * load under a guard that refuses the shapes with exponential worst cases —
+	 * see `validateRedactionPattern` in `src/server/redact.ts` for exactly what
+	 * is refused and why.
+	 */
+	pattern: string;
+	/** What a match becomes. Defaults to `[redacted:<name>]`. */
+	replacement?: string;
+}
+
+/**
+ * Keep strings out of every request that leaves the process.
+ *
+ * Off by default. Enabled, each rule is applied to the rendered upstream body
+ * just before dispatch — the one shape every front end normalises to and every
+ * provider client renders from — so a new upstream cannot bypass it. The
+ * ledger row records HOW MANY matches were removed and never what they were;
+ * nothing logs the matched text at any level.
+ */
+export interface RedactionConfig {
+	enabled: boolean;
+	rules: RedactionRule[];
+	/**
+	 * Also scan tool-call arguments and tool results. Off by default: tool
+	 * results are most of a turn's prompt bytes, so this is most of the cost —
+	 * and, for an operator worried about a secret in a file the agent read,
+	 * most of the point.
 	 */
-	retentionDays: number;
+	scanTools: boolean;
 }
 
 /**
@@ -929,6 +975,7 @@ export interface RouterConfig {
 	anthropic: AnthropicConfig;
 	profiles: ProfileConfig[];
 	ledger: LedgerConfig;
+	redaction: RedactionConfig;
 	/**
 	 * Relax a tier's quality floor to a catalog-derived band when the configured
 	 * floor is met by fewer than three available models (never tightening it).

package/src/cost/ledger.ts

@@ -27,6 +27,7 @@ import type {
 	ModelCacheReliability,
 	ModelLatency,
 	ModelTrust,
+	PruneResult,
 	SoftFailureSpike,
 	UsageCounts,
 } from "./types.ts";
@@ -100,6 +101,7 @@ export interface LedgerRow {
 	error: string | null;
 	prompt_tokens_saved: number | null;
 	scope: string | null;
+	redactions: number | null;
 }
 
 interface TrustRow {
@@ -278,6 +280,9 @@ export function toEntry(row: LedgerRow): LedgerEntry {
 		// Optional under exactOptionalPropertyTypes: an old row (or a scopeless
 		// turn) simply has no `scope`, rather than an explicit undefined.
 		...(row.scope === null || row.scope === undefined ? {} : { scope: row.scope }),
+		// Likewise a row from before v19, or a turn with redaction off: absent,
+		// which is a different fact from 0 (the rules ran and matched nothing).
+		...(row.redactions === null || row.redactions === undefined ? {} : { redactions: row.redactions }),
 	};
 }
 
@@ -323,8 +328,8 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			id, created_at_ms, conversation_key, session_id, turn, requested_model, harness_id, omp_session_id, slug, served_slug,
 			tier, classification_source, reasons, predicted_usd, reported_usd, usage, cost_breakdown,
 			attempt, escalation_signal, latency_ms, ttft_ms, finish_reason, wasted, upstream_generation_id, error,
-			error_kind, features, score, confidence, task, classifier_reasons, explored_from, hold_arm, prompt_tokens_saved, scope
-		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			error_kind, features, score, confidence, task, classifier_reasons, explored_from, hold_arm, prompt_tokens_saved, scope, redactions
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 	);
 	const calibrationStmt = db.query(
 		`INSERT INTO token_calibration (tokenizer, est_bytes, actual_tokens, samples) VALUES (?, ?, ?, 1)
@@ -380,9 +385,17 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
 	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
 	const pruneStmt = db.query("DELETE FROM ledger WHERE created_at_ms < ?");
+	// Feedback is a verdict ON a ledger row; keeping it past the turn it judges
+	// would leave a note about a conversation the operator asked us to forget.
+	// Matched by the row it points at AND by its own age, so verdicts orphaned
+	// by a prune that ran before v0.21.0 are swept up too.
+	const pruneFeedbackStmt = db.query(
+		"DELETE FROM feedback WHERE created_at_ms < ? OR ledger_id IN (SELECT id FROM ledger WHERE created_at_ms < ?)",
+	);
 	// Ollama meter samples (one per usage poll) only matter for the current
 	// billing cycle's calibration; they age out with the ledger rows.
 	const pruneMeterStmt = db.query("DELETE FROM ollama_meter_samples WHERE at_ms < ?");
+	const oldestStmt = db.query("SELECT MIN(created_at_ms) AS oldest FROM ledger");
 	const wasteStmt = db.query("UPDATE ledger SET wasted = 1 WHERE id = ?");
 	const providerSpendStmt = db.query(
 		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE created_at_ms >= ? AND COALESCE(served_slug, slug) LIKE ?",
@@ -480,6 +493,8 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 				// A turn that carried no scope stores NULL, exactly as every row
 				// written before v18 did; "" and absent are the same fact.
 				entry.scope === undefined || entry.scope === "" ? null : entry.scope,
+				// NULL when redaction was off for this turn; 0 says the rules ran.
+				entry.redactions ?? null,
 			);
 			// Always consume the pending estimate, even when the turn failed, so a
 			// dead turn's bytes can never pair with a later turn's tokens. Only
@@ -635,11 +650,30 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			const row = providerSpendStmt.get(sinceMs, `${slugPrefix}%`) as { total: number } | null;
 			return row?.total ?? 0;
 		},
-		prune(retentionDays: number, nowMs = Date.now()): number {
-			if (retentionDays <= 0) return 0;
+		prune(retentionDays: number | null, nowMs = Date.now()): PruneResult {
+			const oldestKeptMs = (): number | null => (oldestStmt.get() as { oldest: number | null } | null)?.oldest ?? null;
+			// null and 0 are the same instruction: keep everything. Still reports
+			// how far back the ledger goes, which is what the caller asked.
+			if (retentionDays === null || retentionDays <= 0) return { deleted: 0, oldestKeptMs: oldestKeptMs() };
 			const cutoff = nowMs - retentionDays * DAY_MS;
+			// Dependants first: the feedback statement reads the rows being deleted.
+			pruneFeedbackStmt.run(cutoff, cutoff);
 			pruneMeterStmt.run(cutoff);
-			return pruneStmt.run(cutoff).changes;
+			const deleted = pruneStmt.run(cutoff).changes;
+			// Hand the freed pages back where the engine can (a ledger created at
+			// v0.21.0 or later is auto_vacuum=INCREMENTAL; an older file reuses
+			// them instead), then fold the WAL back so the space is real on disk.
+			// Best-effort by design: a full ledger that could not shrink is a far
+			// smaller problem than a prune that throws.
+			if (deleted > 0) {
+				try {
+					db.exec("PRAGMA incremental_vacuum");
+					db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+				} catch {
+					/* freed pages stay in the file, to be reused by later rows */
+				}
+			}
+			return { deleted, oldestKeptMs: oldestKeptMs() };
 		},
 		markWasted(id: string): void {
 			wasteStmt.run(id);

package/src/cost/report.ts

@@ -36,6 +36,14 @@ export interface ReportTotals {
 	digestInputTokens: number;
 	/** Digests the agent went back on: the same tool re-run with the same primary argument afterwards (row marked wasted). */
 	digestReruns: number;
+	/**
+	 * Strings redaction removed from outgoing requests in the window, and how
+	 * many turns at least one was removed from — "N turns had something
+	 * removed", which is the sentence an operator has to be able to say. Both 0
+	 * when redaction is off, and rows written before v0.21.0 count as 0.
+	 */
+	redactions: number;
+	redactedTurns: number;
 	/** Forecast accuracy over clean kept rows with a reported cost: mean |predicted − reported| ÷ reported, and the share over-predicted. */
 	forecastSamples: number;
 	forecastMeanError: number;
@@ -253,6 +261,8 @@ export function buildUsageReport(
 				COALESCE(SUM(CASE WHEN requested_model = 'digest' THEN ${USD} ELSE 0 END), 0) AS digest_spend,
 				COALESCE(SUM(CASE WHEN requested_model = 'digest' THEN ${PT} ELSE 0 END), 0) AS digest_input,
 				SUM(CASE WHEN requested_model = 'digest' AND wasted = 1 THEN 1 ELSE 0 END) AS digest_reruns,
+				COALESCE(SUM(redactions), 0) AS redactions,
+				SUM(CASE WHEN redactions > 0 THEN 1 ELSE 0 END) AS redacted_rows,
 				SUM(CASE WHEN ${FORECASTABLE} THEN 1 ELSE 0 END) AS fc_n,
 				COALESCE(SUM(CASE WHEN ${FORECASTABLE} THEN ABS(predicted_usd - reported_usd) / reported_usd END), 0) AS fc_err,
 				SUM(CASE WHEN ${FORECASTABLE} AND predicted_usd > reported_usd THEN 1 ELSE 0 END) AS fc_over,
@@ -276,6 +286,8 @@ export function buildUsageReport(
 		digest_spend: number;
 		digest_input: number;
 		digest_reruns: number | null;
+		redactions: number;
+		redacted_rows: number | null;
 		fc_n: number | null;
 		fc_err: number;
 		fc_over: number | null;
@@ -402,6 +414,8 @@ export function buildUsageReport(
 			digestSpendUsd: t.digest_spend,
 			digestInputTokens: t.digest_input,
 			digestReruns: t.digest_reruns ?? 0,
+			redactions: t.redactions,
+			redactedTurns: t.redacted_rows ?? 0,
 			forecastSamples: t.fc_n ?? 0,
 			forecastMeanError: (t.fc_n ?? 0) > 0 ? t.fc_err / (t.fc_n ?? 1) : 0,
 			forecastOverShare: (t.fc_n ?? 0) > 0 ? (t.fc_over ?? 0) / (t.fc_n ?? 1) : 0,
@@ -477,6 +491,11 @@ export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): R
 	if (t.forecastSamples > 0) {
 		summary.push(`forecast: mean error ${pct(t.forecastMeanError)} of reported cost over ${num(t.forecastSamples)} turns · ${pct(t.forecastOverShare)} over-predicted`);
 	}
+	if (t.redactedTurns > 0) {
+		// Counts only: the report is read out loud in front of people, and the
+		// whole point of the feature is that the matched strings are gone.
+		summary.push(`redaction: ${num(t.redactedTurns)} turns had something removed (${num(t.redactions)} strings)`);
+	}
 	if (t.subagentDispatches > 0) {
 		summary.push(`subagents: ${num(t.subagentDispatches)} dispatches, ${usd(t.subagentSpendUsd)} (${pct(t.spendUsd > 0 ? t.subagentSpendUsd / t.spendUsd : 0)} of spend)`);
 	}

package/src/cost/retention.ts

@@ -0,0 +1,58 @@
+/**
+ * Ledger retention: how long turns are kept, and who is allowed to say so.
+ *
+ * The rule lives here rather than in the server's timer callback for two
+ * reasons. The interval has to be enforced in ONE place — the housekeeping
+ * timer ticks every minute, the boot path runs early, and `POST
+ * /v1/router/prune` can arrive at any moment, and a delete over the whole
+ * ledger is not something that should be able to run on every one of those.
+ * And a front door of the team edition must never delete from the ledger
+ * itself (it holds a read-only handle by design), so the route is the only way
+ * it can ask, which makes the once-an-hour gate part of the contract rather
+ * than a detail of the caller.
+ */
+
+import type { Ledger, PruneResult } from "./types.ts";
+
+/** Floor between two scheduled prunes. A retention window is measured in days; an hour is fine grain for it. */
+export const RETENTION_INTERVAL_MS = 3_600_000;
+
+export interface RetentionRunner {
+	/** Prunes when the interval has elapsed since the last run; null when it was skipped. */
+	maybeRun(nowMs?: number): PruneResult | null;
+	/** Prunes regardless (the route), and satisfies the schedule for the next hour. */
+	runNow(nowMs?: number): PruneResult;
+	/** The configured window this runner would apply, for a caller that reports it. */
+	retentionDays(): number | null;
+}
+
+/**
+ * Builds the runner over a live config read.
+ *
+ * `retentionDays` is read through a function, not captured, so a hot reload or
+ * an embedder's `reconfigure` changes the window without restarting anything —
+ * and so lowering it takes effect on the next tick rather than the next boot.
+ */
+export function createRetentionRunner(opts: {
+	ledger: Ledger;
+	retentionDays: () => number | null;
+	intervalMs?: number;
+}): RetentionRunner {
+	const intervalMs = opts.intervalMs ?? RETENTION_INTERVAL_MS;
+	// Never run: the first call is always due, so a lowered window applies at boot.
+	let lastRunMs: number | null = null;
+	const run = (nowMs: number): PruneResult => {
+		lastRunMs = nowMs;
+		return opts.ledger.prune?.(opts.retentionDays(), nowMs) ?? { deleted: 0, oldestKeptMs: null };
+	};
+	return {
+		maybeRun(nowMs = Date.now()) {
+			if (lastRunMs !== null && nowMs - lastRunMs < intervalMs) return null;
+			return run(nowMs);
+		},
+		runNow(nowMs = Date.now()) {
+			return run(nowMs);
+		},
+		retentionDays: opts.retentionDays,
+	};
+}

package/src/cost/types.ts

@@ -153,6 +153,14 @@ export interface LedgerEntry {
 	 * door charges the row's spend back to that project with it. NULL before v18.
 	 */
 	scope?: string;
+	/**
+	 * How many strings redaction removed from this turn's outgoing request
+	 * (`redaction` in the config). A COUNT and nothing else — the matched text
+	 * is precisely what must not exist outside the client, so the evidence that
+	 * the guard ran must not reintroduce it. Absent when redaction is off, and
+	 * on every row written before v19; 0 means the rules ran and matched nothing.
+	 */
+	redactions?: number;
 	/**
 	 * The catalog model that served, for the cost split. The ledger can price
 	 * OpenRouter slugs from its own cached catalog payload; a model from another
@@ -161,6 +169,18 @@ export interface LedgerEntry {
 	priceModel?: CatalogModel;
 }
 
+/**
+ * What one retention prune did. `oldestKeptMs` is the timestamp of the oldest
+ * row still in the ledger afterwards (null when it is empty) — the honest
+ * answer to "how far back does this ledger go now", which is what an operator
+ * asked the question for, and what a front door shows instead of computing a
+ * cutoff of its own.
+ */
+export interface PruneResult {
+	deleted: number;
+	oldestKeptMs: number | null;
+}
+
 /** Rolling blended rate used to keep omp's cost display honest. */
 export interface BlendedRate {
 	/** USD per million prompt tokens, spend-weighted over the window. */
@@ -310,8 +330,12 @@ export interface Ledger {
 	latestForSession?(ompSessionId: string): LedgerEntry | null;
 	/** Newest entries for an omp session, newest first. Optional. */
 	entriesForSession?(ompSessionId: string, limit: number): LedgerEntry[];
-	/** Deletes rows older than `retentionDays` (0 ⇒ none); returns how many. Optional. */
-	prune?(retentionDays: number, nowMs?: number): number;
+	/**
+	 * Deletes ledger rows past the retention window, and the feedback keyed to
+	 * them (`null` or 0 ⇒ nothing is deleted). Optional so fakes need not
+	 * implement it.
+	 */
+	prune?(retentionDays: number | null, nowMs?: number): PruneResult;
 	/** Marks one row wasted after the fact (a digest the agent went back on). Optional. */
 	markWasted?(id: string): void;
 }

package/src/lib.ts

@@ -15,7 +15,10 @@
 export { startServer, type ReconfigureResult, type StartedServer } from "./server/http.ts";
 export { loadConfig, apiKeySource } from "./config/load.ts";
 export { DEFAULT_CONFIG } from "./config/defaults.ts";
-export type { RouterConfig, UpstreamEntry, UpstreamKind, UpstreamModelConfig } from "./config/types.ts";
+export type { RedactionConfig, RedactionRule, RouterConfig, UpstreamEntry, UpstreamKind, UpstreamModelConfig } from "./config/types.ts";
+// A front door that lets an operator type a redaction rule validates it with
+// the same guard the router refuses it with, before the rule is ever saved.
+export { validateRedactionPattern, validateRedactionRule, defaultReplacement, MAX_REDACTION_RULES } from "./config/redaction.ts";
 export { RESERVED_UPSTREAM_IDS } from "./config/schema.ts";
 export { setKnownUpstreamIds, providerOfSlug } from "./cost/report.ts";
 export type { DeepPartial } from "./config/load.ts";
@@ -29,4 +32,7 @@ export { buildExecutable, collectPackageFiles, executableFileName, hostTarget, i
 export { parseSkillsBundle, type SkillsBundle } from "./cli/skills.ts";
 export type { RequestPolicy } from "./wire/types.ts";
 export type { CatalogView, CatalogViewModel } from "./server/catalog-view.ts";
-export type { Ledger, LedgerEntry } from "./cost/types.ts";
+export type { Ledger, LedgerEntry, PruneResult } from "./cost/types.ts";
+// Retention: a front door asks through `POST /v1/router/prune` rather than
+// deleting from the ledger itself. The interval is exported so it can say when.
+export { RETENTION_INTERVAL_MS } from "./cost/retention.ts";