auto-model-router 0.18.0 → 0.20.0

package/src/cli/harnesses.ts

@@ -0,0 +1,277 @@
+/**
+ * The harness configurations `connect` writes beyond the five it has always
+ * written (omp, Hermes, Codex, Aider, Claude Code), and the snippets it prints
+ * for the ones it deliberately does not write.
+ *
+ * The line between the two is confidence, not effort. A harness whose config
+ * FILE and keys are documented — and, where the harness could be run here, seen
+ * to read them — gets an automated path: a pure merge over the file's text, so
+ * `connect` edits its own keys and leaves every other one alone. A harness
+ * whose provider settings live in application state (an editor's `globalState`
+ * database, a vendor's web account page) has no file to edit honestly, so it
+ * gets a snippet the user pastes into its settings UI instead. An invented key
+ * writes a file that silently does nothing and then reports success, which is
+ * worse for the user than a printed instruction that works.
+ *
+ * Every merge returns `null` when nothing changes — so a second `connect` is a
+ * no-op — and also when the file cannot be parsed: a file we do not understand
+ * is not ours to rewrite, and the caller says so rather than guessing.
+ */
+
+import { isMap, isScalar, isSeq, parseDocument, type Document, type YAMLSeq } from "yaml";
+
+import { SCOPE_ENV } from "../context/scope.ts";
+
+/** The provider id every automated harness registers the router under. */
+export const PROVIDER_ID = "auto-model-router";
+
+/** The virtual models a router serves; `auto` is the one each harness is pointed at. */
+export const PROFILE_IDS = ["auto", "auto-cheap", "auto-max"] as const;
+
+/**
+ * The headers a harness's provider entry sends on every turn.
+ *
+ * `X-Omp-Harness` is what splits budgets, reports and toasts per harness, so it
+ * is always here. The agentdox scope is not: these files hold LITERAL header
+ * values — unlike omp's models.yml, none of these harnesses resolves a value
+ * that names an environment variable — so a machine-wide file could only pin one
+ * project onto every workspace. It is written only when `connect --scope` asked
+ * for exactly that; otherwise the scope is left to the remote's own default.
+ */
+export function harnessHeaders(harness: string, scope: string): Record<string, string> {
+	return { "X-Omp-Harness": harness, ...(scope !== "" && scope !== SCOPE_ENV ? { "X-Agentdox-Scope": scope } : {}) };
+}
+
+/** A harness `connect` will not write a file for: what to set, and where. */
+export interface ManualSnippet {
+	/** The harness's display name, as it appears in the report. */
+	harness: string;
+	/** Why there is no file to write — one line, shown beside the name. */
+	reason: string;
+	/** The instruction lines, already formatted for a terminal. */
+	lines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode — automated
+// ---------------------------------------------------------------------------
+
+/**
+ * Merges the router into OpenCode's `opencode.json`.
+ *
+ * OpenCode reaches any OpenAI-compatible endpoint through a `provider` entry
+ * backed by the `@ai-sdk/openai-compatible` npm package, which it installs
+ * itself; `options` is handed to that package verbatim, which is where the base
+ * URL, the key and the per-request headers go. This is the shape the README
+ * documents, verified live against opencode 1.18 — the captured request,
+ * `test/fixtures/harness/opencode.json`, carries the `X-Omp-Harness` header
+ * that `options.headers` put there.
+ *
+ * `model` is pointed at our `auto` so the harness comes up on the router rather
+ * than leaving the user to find it in the picker; every other key in the file —
+ * `$schema`, the theme, MCP servers, other providers — is carried through.
+ */
+export function mergeOpenCodeConfig(before: string, url: string, key: string, scope = ""): string | null {
+	const root = parseJsonObject(before);
+	if (root === null) return null;
+	const providers = { ...((root.provider as Record<string, unknown> | undefined) ?? {}) };
+	providers[PROVIDER_ID] = {
+		npm: "@ai-sdk/openai-compatible",
+		name: "auto-model-router",
+		options: { baseURL: `${url}/v1`, apiKey: key, headers: harnessHeaders("opencode", scope) },
+		models: Object.fromEntries(PROFILE_IDS.map((id) => [id, { name: id }])),
+	};
+	const next = { ...root, provider: providers, model: `${PROVIDER_ID}/auto` };
+	const after = `${JSON.stringify(next, null, 2)}\n`;
+	return after === before ? null : after;
+}
+
+// ---------------------------------------------------------------------------
+// Cline — automated
+// ---------------------------------------------------------------------------
+
+/** The provider id Cline files an OpenAI-compatible endpoint under; `cline auth -p openai` resolves to it. */
+const CLINE_PROVIDER = "openai-compatible";
+
+/**
+ * Merges the router into Cline's `~/.cline/data/settings/providers.json`.
+ *
+ * The shape was captured by running `cline auth -p openai -b <base> -k <key> -m
+ * auto` — the command the README documents — against an isolated `--data-dir`
+ * on cline 3.0.61: a `version`, the `lastUsedProvider`, and one entry per
+ * provider holding `settings`, an `updatedAt` stamp and a `tokenSource`. One
+ * file serves the CLI and, since the extension's settings migration, the VS
+ * Code extension too, which is also how Cline reaches the router inside an
+ * editor that has no provider settings of its own (see windsurfSnippet).
+ *
+ * Writing the keys rather than shelling out to `cline auth` buys two things
+ * the command cannot give: `--dry-run` can show the change, and `settings.headers`
+ * gets written. That map is in the on-disk schema but has no CLI flag, and it is
+ * what finally gives Cline a harness id — verified live by pointing cline 3.0.61
+ * at a recording server, whose capture is `test/fixtures/harness/cline-cli-connected.json`.
+ *
+ * `updatedAt` is deliberately NOT refreshed when the settings already match: a
+ * stamp that moved on every run would make `connect` write a different file each
+ * time, which is the one thing every path here promises not to do.
+ */
+export function mergeClineProviders(before: string, url: string, key: string, nowIso: string, scope = ""): string | null {
+	const root = parseJsonObject(before);
+	if (root === null) return null;
+	const providers = { ...((root.providers as Record<string, unknown> | undefined) ?? {}) };
+	const entry = (providers[CLINE_PROVIDER] as Record<string, unknown> | undefined) ?? {};
+	const settings = { provider: CLINE_PROVIDER, apiKey: key, model: "auto", baseUrl: `${url}/v1`, headers: harnessHeaders("cline", scope) };
+	if (JSON.stringify(entry.settings) === JSON.stringify(settings) && root.lastUsedProvider === CLINE_PROVIDER) return null;
+	providers[CLINE_PROVIDER] = { ...entry, settings, updatedAt: nowIso, tokenSource: entry.tokenSource ?? "manual" };
+	// `version` leads the file cline writes; spreading root after it keeps that order on a file that has one.
+	const next = { version: 1, ...root, lastUsedProvider: CLINE_PROVIDER, modes: root.modes ?? {}, providers };
+	return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Continue — automated
+// ---------------------------------------------------------------------------
+
+/** The `name:` our model entries carry in Continue's config, and how they are found again on a re-run. */
+const CONTINUE_PREFIX = PROVIDER_ID;
+
+/**
+ * Merges the router's three profiles into Continue's `~/.continue/config.yaml`.
+ *
+ * Continue's documented assistant file is a YAML map with `name`, `version` and
+ * `schema` at the top and a `models:` list under it; an OpenAI-compatible
+ * endpoint is a model entry with `provider: openai` and `apiBase`, `apiKey`,
+ * `roles` and `requestOptions.headers` — the last is what carries the harness
+ * id. Continue was not run here, so this is the documented shape rather than an
+ * observed one; it is automated because the file, its location and its keys are
+ * all published, which is the bar (nothing about it is inferred).
+ *
+ * The edit goes through the YAML *document*, not a re-serialisation of parsed
+ * data, so a hand-written config keeps its comments, key order and quoting and
+ * only our own entries move. Entries are matched by `name`, so a re-run with a
+ * new key replaces them in place instead of appending a second copy.
+ */
+export function mergeContinueConfig(before: string, url: string, key: string, scope = ""): string | null {
+	let doc: Document.Parsed;
+	try {
+		doc = parseDocument(before);
+	} catch {
+		return null;
+	}
+	if (doc.errors.length > 0) return null;
+	// A new file is seeded in the schema's own order rather than assembled key by
+	// key, which would leave the three required fields trailing the model list.
+	if (before.trim() === "") doc = parseDocument(`name: ${PROVIDER_ID}\nversion: 0.0.1\nschema: v1\nmodels:\n`);
+	if (!isMap(doc.contents)) return null;
+	// Required by the schema, and only supplied when the file does not already say otherwise.
+	if (doc.get("name") === undefined) doc.set("name", PROVIDER_ID);
+	if (doc.get("version") === undefined) doc.set("version", "0.0.1");
+	if (doc.get("schema") === undefined) doc.set("schema", "v1");
+	const models = doc.get("models", true);
+	// `models:` with nothing under it parses to a null SCALAR node, not to null itself.
+	if (models === undefined || models === null || (isScalar(models) && models.value === null)) doc.set("models", doc.createNode([]));
+	else if (!isSeq(models)) return null;
+	const seq = doc.get("models", true) as YAMLSeq<unknown>;
+	seq.flow = false; // an empty seq is created in flow style, which would drag every entry onto one line
+	const wanted = PROFILE_IDS.map((id) =>
+		doc.createNode({
+			name: id === "auto" ? CONTINUE_PREFIX : `${CONTINUE_PREFIX}-${id.replace("auto-", "")}`,
+			provider: "openai",
+			model: id,
+			apiBase: `${url}/v1`,
+			apiKey: key,
+			roles: ["chat", "edit", "apply", "summarize"],
+			capabilities: ["tool_use", "image_input"],
+			requestOptions: { headers: harnessHeaders("continue", scope) },
+		}),
+	);
+	const nameOf = (item: unknown): string => (isMap(item) ? String(item.get("name") ?? "") : "");
+	for (const node of wanted) {
+		const name = nameOf(node);
+		const at = seq.items.findIndex((item) => nameOf(item) === name);
+		if (at >= 0) seq.items[at] = node;
+		else seq.items.push(node);
+	}
+	const after = doc.toString();
+	return after === before ? null : after;
+}
+
+// ---------------------------------------------------------------------------
+// Manual paths
+// ---------------------------------------------------------------------------
+
+/**
+ * The values every OpenAI-compatible settings form asks for, as lines.
+ *
+ * Shared by the manual harnesses because the substance is identical in each —
+ * a base URL, a key and a model id — and only the form differs. One renderer
+ * means the three recipes cannot drift apart from each other or from what the
+ * automated paths write.
+ */
+function providerFields(url: string, key: string): string[] {
+	return [`base URL: ${url}/v1`, `API key:  ${key}`, `model:    auto  (also auto-cheap, auto-max)`];
+}
+
+/**
+ * Cursor.
+ *
+ * Cursor's OpenAI override is an application setting in the editor's own state
+ * database, not a documented file: what lives under `~/.cursor` is MCP servers
+ * and rules, and the official key documentation describes only the settings
+ * pane. So the values are printed instead of written.
+ *
+ * The second line is the one that saves an afternoon: Cursor routes chat
+ * through its own servers with the key attached, so the override only works
+ * against a router the internet can reach. A loopback or LAN router cannot
+ * serve Cursor however it is configured — which is worth saying plainly, since
+ * every other harness here is happy with `127.0.0.1`.
+ */
+export function cursorSnippet(url: string, key: string): ManualSnippet {
+	const reachable = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\]|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(url);
+	return {
+		harness: "Cursor",
+		reason: "its OpenAI override lives in the editor's settings, not a file",
+		lines: [
+			"Cursor Settings → Models → OpenAI API Key: enable the base-URL override, then",
+			...providerFields(url, key),
+			"Add `auto` as a custom model and select it. Cursor sends no custom header,",
+			"so its turns carry no X-Omp-Harness id and share the unnamed budget.",
+			...(reachable ? ["WARNING: Cursor proxies chat through its own servers, so this URL must be", "reachable from the internet — a loopback or LAN router will never answer it."] : []),
+		],
+	};
+}
+
+/**
+ * Windsurf.
+ *
+ * Windsurf's own files under `~/.codeium/<channel>` cover MCP servers, rules
+ * and skills; the model provider is not among them, and its bring-your-own-key
+ * page takes first-party provider keys rather than an arbitrary base URL —
+ * there is no field for one to write. So the useful answer is not a snippet of
+ * Windsurf settings at all but the extension route: Windsurf is a VS Code fork,
+ * and the Cline extension reads the same `providers.json` `connect` has already
+ * written, so installing it is the whole configuration.
+ */
+export function windsurfSnippet(clineConfigured: boolean): ManualSnippet {
+	return {
+		harness: "Windsurf",
+		reason: "it has no custom base-URL field; reach the router through an extension",
+		lines: [
+			"Windsurf's own provider settings take first-party keys, not a base URL.",
+			"Install the Cline extension in Windsurf: it reads the same providers.json",
+			clineConfigured ? "this connect just wrote, so it needs no further setup." : "connect writes — re-run `connect --harness cline` once Cline is installed.",
+			"The Continue extension works the same way against ~/.continue/config.yaml.",
+		],
+	};
+}
+
+/** Parses a JSON object file, treating an empty file as `{}` and anything else as not ours. */
+function parseJsonObject(before: string): Record<string, unknown> | null {
+	if (before.trim() === "") return {};
+	try {
+		const parsed = JSON.parse(before) as unknown;
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		return parsed as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}

package/src/cost/ledger.ts

@@ -99,6 +99,7 @@ export interface LedgerRow {
 	upstream_generation_id: string | null;
 	error: string | null;
 	prompt_tokens_saved: number | null;
+	scope: string | null;
 }
 
 interface TrustRow {
@@ -274,6 +275,9 @@ export function toEntry(row: LedgerRow): LedgerEntry {
 		upstreamGenerationId: row.upstream_generation_id,
 		error: row.error,
 		promptTokensSaved: row.prompt_tokens_saved ?? 0,
+		// 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 }),
 	};
 }
 
@@ -319,8 +323,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
-		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			error_kind, features, score, confidence, task, classifier_reasons, explored_from, hold_arm, prompt_tokens_saved, scope
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 	);
 	const calibrationStmt = db.query(
 		`INSERT INTO token_calibration (tokenizer, est_bytes, actual_tokens, samples) VALUES (?, ?, ?, 1)
@@ -473,6 +477,9 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 				entry.exploredFrom,
 				entry.holdArm,
 				entry.promptTokensSaved,
+				// 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,
 			);
 			// 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

package/src/cost/types.ts

@@ -146,6 +146,13 @@ export interface LedgerEntry {
 	error: string | null;
 	/** Prompt tokens removed by compaction before dispatch. 0 when none. NULL before v12. */
 	promptTokensSaved: number;
+	/**
+	 * The agentdox context scope this turn carried — what the bridge resolved
+	 * for it (the request's `X-Agentdox-Scope`, or `context.defaultScope`).
+	 * Absent, or empty, when the turn carried none, and stored as NULL; a front
+	 * door charges the row's spend back to that project with it. NULL before v18.
+	 */
+	scope?: string;
 	/**
 	 * 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

package/src/cost/views.ts

@@ -44,6 +44,8 @@ export interface ExportRow {
 	day: string;
 	harnessId: string;
 	slug: string;
+	/** The agentdox context scope the turns carried; "" for rows that carried none (every row before v18). */
+	scope: string;
 	provider: string;
 	dispatches: number;
 	promptTokens: number;
@@ -125,12 +127,21 @@ export function decisionEntries(db: Database, filter: DecisionFilter): DecisionE
 	return entries.map((e) => ({ ...e, feedback: verdicts.get(e.id) ?? [] }));
 }
 
-/** Spend (reported where present, predicted otherwise) since `sinceMs`, digest calls included as the ledger counts them. */
-export function spendUsdSince(db: Database, sinceMs: number, harness: HarnessScope): number {
+/**
+ * Spend (reported where present, predicted otherwise) since `sinceMs`, digest calls included
+ * as the ledger counts them. `contextScope`, when given, narrows to the turns that carried
+ * exactly that agentdox scope — what a front door charges back to one project.
+ */
+export function spendUsdSince(db: Database, sinceMs: number, harness: HarnessScope, contextScope?: string): number {
 	const s = scope(harness, "harness_id");
 	if (s === null) return 0;
-	const where = ["created_at_ms >= $since", ...s.sql].join(" AND ");
-	const row = db.query(`SELECT COALESCE(SUM(${USD}), 0) AS usd FROM ledger WHERE ${where}`).get({ $since: sinceMs, ...s.bind }) as { usd: number };
+	const where = ["created_at_ms >= $since", ...s.sql];
+	const bind: Record<string, string | number> = { $since: sinceMs, ...s.bind };
+	if (contextScope !== undefined && contextScope !== "") {
+		where.push("scope = $scope");
+		bind.$scope = contextScope;
+	}
+	const row = db.query(`SELECT COALESCE(SUM(${USD}), 0) AS usd FROM ledger WHERE ${where.join(" AND ")}`).get(bind) as { usd: number };
 	return row.usd;
 }
 
@@ -163,14 +174,19 @@ export function feedbackView(db: Database, sinceMs: number, harness: HarnessScop
 	return { byModel, recent };
 }
 
-/** One row per UTC day, harness and served model since `sinceMs`; digest calls are excluded as in the report. */
+/**
+ * One row per UTC day, harness, served model and context scope since `sinceMs`; digest calls
+ * are excluded as in the report. The scope splits a harness's day by project, so a front door
+ * can charge each project its own share; rows from before v18 (and turns that carried no
+ * scope) group under "".
+ */
 export function exportRows(db: Database, sinceMs: number, harness: HarnessScope): ExportRow[] {
 	const s = scope(harness, "harness_id");
 	if (s === null) return [];
 	const where = ["created_at_ms >= $since", "requested_model <> 'digest'", ...s.sql].join(" AND ");
 	const rows = db
 		.query(
-			`SELECT strftime('%Y-%m-%d', created_at_ms / 1000, 'unixepoch') AS day, harness_id, COALESCE(served_slug, slug) AS slug,
+			`SELECT strftime('%Y-%m-%d', created_at_ms / 1000, 'unixepoch') AS day, harness_id, COALESCE(served_slug, slug) AS slug, COALESCE(scope, '') AS scope,
 				COUNT(*) AS dispatches,
 				COALESCE(SUM(json_extract(usage, '$.promptTokens')), 0) AS prompt_tokens,
 				COALESCE(SUM(json_extract(usage, '$.cachedTokens')), 0) AS cached_tokens,
@@ -178,13 +194,14 @@ export function exportRows(db: Database, sinceMs: number, harness: HarnessScope)
 				COALESCE(SUM(${USD}), 0) AS spend,
 				SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END) AS escalations,
 				SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) AS errors
-			 FROM ledger WHERE ${where} GROUP BY day, harness_id, slug ORDER BY day ASC, harness_id ASC, spend DESC`,
+			 FROM ledger WHERE ${where} GROUP BY day, harness_id, slug, scope ORDER BY day ASC, harness_id ASC, spend DESC`,
 		)
-		.all({ $since: sinceMs, ...s.bind }) as { day: string; harness_id: string; slug: string; dispatches: number; prompt_tokens: number; cached_tokens: number; completion_tokens: number; spend: number; escalations: number; errors: number }[];
+		.all({ $since: sinceMs, ...s.bind }) as { day: string; harness_id: string; slug: string; scope: string; dispatches: number; prompt_tokens: number; cached_tokens: number; completion_tokens: number; spend: number; escalations: number; errors: number }[];
 	return rows.map((r) => ({
 		day: r.day,
 		harnessId: r.harness_id,
 		slug: r.slug,
+		scope: r.scope,
 		provider: providerOfSlug(r.slug),
 		dispatches: r.dispatches,
 		promptTokens: r.prompt_tokens,
@@ -196,7 +213,7 @@ export function exportRows(db: Database, sinceMs: number, harness: HarnessScope)
 	}));
 }
 
-export const EXPORT_COLUMNS = ["day", "harness", "model", "provider", "dispatches", "prompt_tokens", "cached_tokens", "completion_tokens", "spend_usd", "escalations", "errors"] as const;
+export const EXPORT_COLUMNS = ["day", "harness", "model", "provider", "dispatches", "prompt_tokens", "cached_tokens", "completion_tokens", "spend_usd", "escalations", "errors", "scope"] as const;
 
 export function csvCell(v: string | number): string {
 	const s = String(v);
@@ -206,7 +223,7 @@ export function csvCell(v: string | number): string {
 /** CSV of export rows; spend to 6 decimals so sub-cent rows survive. */
 export function exportCsv(rows: readonly ExportRow[]): string {
 	const lines = [EXPORT_COLUMNS.join(",")];
-	for (const r of rows) lines.push([r.day, r.harnessId, r.slug, r.provider, r.dispatches, r.promptTokens, r.cachedTokens, r.completionTokens, r.spendUsd.toFixed(6), r.escalations, r.errors].map(csvCell).join(","));
+	for (const r of rows) lines.push([r.day, r.harnessId, r.slug, r.provider, r.dispatches, r.promptTokens, r.cachedTokens, r.completionTokens, r.spendUsd.toFixed(6), r.escalations, r.errors, r.scope].map(csvCell).join(","));
 	return `${lines.join("\n")}\n`;
 }
 

package/src/index.ts

@@ -29,6 +29,7 @@ Usage: auto-model-router <command> [options]
   report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   export     One row per day, harness and model as CSV (--json for rows)
   connect    Point this machine at a remote router (--url with --key[, --refresh-token] or --setup-token <one-time token from a team>; --scope pins one project for the whole machine (default: each workspace's own); --profile persists the environment and, from the compiled executable, PATH; the remote's skills and its MCP endpoint are installed for Claude Code and omp)
+             --harness omp,hermes,codex,aider,claude,opencode,cline,continue,cursor,windsurf restricts it; cursor and windsurf are printed, not written
   refresh    Trade the refresh token for a new access key and re-write every harness config (--force: even when not near expiry)
   token      Print an access key that is good right now, refreshing first if needed (for a harness key-helper)
   models     Show what each complexity tier would consider, and why

package/src/server/http.ts

@@ -527,7 +527,9 @@ export function startServer(cfg: RouterConfig): StartedServer {
 					// budget check needs when it cannot read the ledger file.
 					const since = Number.parseInt(url.searchParams.get("sinceMs") ?? "", 10);
 					if (!Number.isFinite(since)) return wireErrorResponse({ status: 400, code: "invalid_request_error", message: "sinceMs required" });
-					return json({ sinceMs: since, usd: spendUsdSince(db, since, harnessScopeParam(url.searchParams.get("harness"))) });
+					// `scope` narrows to one agentdox context scope: a project's own spend.
+					const contextScope = url.searchParams.get("scope") ?? "";
+					return json({ sinceMs: since, usd: spendUsdSince(db, since, harnessScopeParam(url.searchParams.get("harness")), contextScope), ...(contextScope === "" ? {} : { scope: contextScope }) });
 				}
 				if (req.method === "GET" && url.pathname === "/v1/router/feedback") {
 					const days = clampDays(url.searchParams.get("days"), 30);

package/src/server/turn.ts

@@ -304,6 +304,10 @@ export async function runTurn(
 				turn: turnNumber,
 				requestedModel: req.requestedModel,
 				harnessId: req.harnessId,
+				// The context scope this turn carried, so a front door can charge the
+				// row back to a project. The resolved one the bridge used, header or
+				// configured default; "" stores as NULL.
+				scope: doxScope,
 				ompSessionId: req.ompSessionId,
 				slug: decision.slug,
 				servedSlug,

package/src/util/sqlite.ts

@@ -18,7 +18,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Bump when a migration is added; guarded below so reopening never regresses it. */
-const USER_VERSION = 17;
+const USER_VERSION = 18;
 
 const MIGRATIONS = `
 CREATE TABLE IF NOT EXISTS catalog_cache (
@@ -286,6 +286,16 @@ const MIGRATE_V17 = `
 ALTER TABLE conversations ADD COLUMN upgrade_deferred_tier TEXT;
 `;
 
+// v18: ledger records the agentdox context scope the turn carried — the scope
+// the bridge resolved for it (the request header, or the configured default).
+// A front door charges spend back to a project with it: the team edition names
+// a project's scope on every turn, so `scope` is the only column that says
+// which project a row belongs to. NULL on every row written before this, and
+// on any turn that carried no scope at all; there is nothing to backfill from.
+const MIGRATE_V18 = `
+ALTER TABLE ledger ADD COLUMN scope TEXT;
+`;
+
 // v9: benchmark_cache holds the external benchmark feeds (Artificial Analysis,
 // BenchLM) that backfill quality scores OpenRouter leaves unpublished. It is a
 // whole new table, created idempotently by the MIGRATIONS block above, so there
@@ -327,6 +337,7 @@ export function openDb(path: string): Database {
 		if (!ledgerCols.some((c) => c.name === "explored_from")) db.exec(MIGRATE_V7);
 		if (!ledgerCols.some((c) => c.name === "hold_arm")) db.exec(MIGRATE_V8);
 		if (!ledgerCols.some((c) => c.name === "prompt_tokens_saved")) db.exec(MIGRATE_V12);
+		if (!ledgerCols.some((c) => c.name === "scope")) db.exec(MIGRATE_V18);
 		const convCols = db.query("PRAGMA table_info(conversations)").all() as { name: string }[];
 		if (!convCols.some((c) => c.name === "context_version")) db.exec(MIGRATE_V11);
 		if (!convCols.some((c) => c.name === "compaction_plan")) db.exec(MIGRATE_V13);