@danypops/jittor 0.10.0 → 0.11.0

package/extension/src/tui.ts

@@ -1,15 +1,26 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { HUMAN_STATUS_MAX_SOURCES, HUMAN_TEXT_FIELD_MAX_CHARACTERS } from "../../src/constants.ts";
-import type { StoredMetricObservation } from "../../src/domain/metric.ts";
+import type { MetricQuery, StoredMetricObservation } from "../../src/domain/metric.ts";
 import type { PolicyAction, Route } from "../../src/policy.ts";
 import type { RouterStatus } from "../../src/ports/router-controller.ts";
 import type { ProviderBudget } from "./footer.ts";
+import { sessionSecretField } from "./session-identity.ts";
 
 export interface JittorPanelClient {
 	call(operation: string, input: unknown): Promise<any>;
 }
 
+export function providerBudgetMetricQuery(status: RouterStatus): MetricQuery | null {
+	switch (status.currentRoute?.provider) {
+		case "openai-codex": return { source: "codex-subscription", metric: "used-fraction", order: "desc", limit: 100 };
+		case "openrouter": return { source: "openrouter", order: "desc", limit: 20 };
+		case "anthropic": return { source: "anthropic", metric: "used-fraction", order: "desc", limit: 20 };
+		case "anthropic-vertex": return { source: "anthropic-vertex", metric: "used-fraction", order: "desc", limit: 20 };
+		default: return null;
+	}
+}
+
 type PanelAction = "pause" | "resume" | "refresh" | "override" | "clear-override" | "close";
 
 function latest(rows: StoredMetricObservation[], predicate: (row: StoredMetricObservation) => boolean): StoredMetricObservation | undefined {
@@ -200,12 +211,9 @@ export function buildStatusView(status: RouterStatus, metrics: StoredMetricObser
 	return lines;
 }
 
-async function snapshot(client: JittorPanelClient): Promise<{ status: RouterStatus; metrics: StoredMetricObservation[] }> {
-	const status = await client.call("router.status", {}) as RouterStatus;
-	const provider = status.currentRoute?.provider;
-	const query = provider === "openai-codex"
-		? { source: "codex-subscription", metric: "used-fraction", order: "desc", limit: 100 }
-		: provider === "openrouter" ? { source: "openrouter", order: "desc", limit: 20 } : null;
+async function snapshot(client: JittorPanelClient, sessionId: string): Promise<{ status: RouterStatus; metrics: StoredMetricObservation[] }> {
+	const status = await client.call("router.status", { session_id: sessionId }) as RouterStatus;
+	const query = providerBudgetMetricQuery(status);
 	const metrics = query ? await client.call("metrics.query", query) as StoredMetricObservation[] : [];
 	return { status, metrics };
 }
@@ -219,8 +227,9 @@ async function chooseOverride(ctx: ExtensionCommandContext, routes: Route[]): Pr
 }
 
 export async function showJittorPanel(ctx: ExtensionCommandContext, client: JittorPanelClient): Promise<void> {
+	const session_id = ctx.sessionManager.getSessionId();
 	for (;;) {
-		const current = await snapshot(client);
+		const current = await snapshot(client, session_id);
 		if (ctx.mode !== "tui") {
 			ctx.ui.notify(buildStatusView(current.status, current.metrics).join("\n"), "info");
 			return;
@@ -254,17 +263,17 @@ export async function showJittorPanel(ctx: ExtensionCommandContext, client: Jitt
 		if (action === "refresh") { await client.call("telemetry.poll", {}); continue; }
 		if (action === "pause" || action === "resume") {
 			if (await ctx.ui.confirm(action === "pause" ? "Emergency-halt provider requests?" : "Release emergency halt?", "This changes provider-request enforcement. Use /jittor off to disable blocking entirely.")) {
-				await client.call(action === "pause" ? "router.pause" : "router.resume", {});
+				await client.call(action === "pause" ? "router.pause" : "router.resume", { session_id, ...sessionSecretField(session_id) });
 			}
 			continue;
 		}
 		if (action === "clear-override") {
-			if (await ctx.ui.confirm("Clear route override?", "Policy-controlled routing will resume.")) await client.call("router.clear_override", {});
+			if (await ctx.ui.confirm("Clear route override?", "Policy-controlled routing will resume.")) await client.call("router.clear_override", { session_id, ...sessionSecretField(session_id) });
 			continue;
 		}
 		const route = await chooseOverride(ctx, current.status.availableRoutes);
 		if (route && await ctx.ui.confirm("Apply route override?", `${routeText(route)} for one hour`)) {
-			await client.call("router.override", { route, expiresAt: Date.now() + 60 * 60 * 1_000 });
+			await client.call("router.override", { route, expiresAt: Date.now() + 60 * 60 * 1_000, session_id, ...sessionSecretField(session_id) });
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],

package/src/adapters/sqlite-metric-store.ts

@@ -34,7 +34,17 @@ export class SQLiteMetricStore implements MetricStore {
 
 	record(input: MetricObservation): StoredMetricObservation {
 		const observation = validateMetricObservation(input);
-		const result = this.db.query(`
+		const result = this.insert(observation);
+		return this.get(Number(result.lastInsertRowid));
+	}
+
+	recordBatch(inputs: MetricObservation[]): StoredMetricObservation[] {
+		const observations = inputs.map((input) => validateMetricObservation(input));
+		return this.db.transaction((rows: typeof observations) => rows.map((observation) => this.get(Number(this.insert(observation).lastInsertRowid))))(observations);
+	}
+
+	private insert(observation: MetricObservation): { lastInsertRowid: number | bigint } {
+		return this.db.query(`
 			INSERT INTO metric_observations (source, scope, metric, value, unit, observed_at, attributes)
 			VALUES (?, ?, ?, ?, ?, ?, ?)
 		`).run(
@@ -46,7 +56,6 @@ export class SQLiteMetricStore implements MetricStore {
 			observation.observedAt,
 			JSON.stringify(observation.attributes ?? {}),
 		);
-		return this.get(Number(result.lastInsertRowid));
 	}
 
 	query(filter: MetricQuery = {}): StoredMetricObservation[] {

package/src/adapters/sqlite-session-identity-store.ts

@@ -0,0 +1,45 @@
+import type { Database } from "bun:sqlite";
+import { SESSION_IDENTITY_MAX_ROWS } from "../constants.ts";
+import type { SessionIdentityRecord, SessionIdentityStore } from "../ports/session-identity-store.ts";
+
+export class SQLiteSessionIdentityStore implements SessionIdentityStore {
+	constructor(private readonly db: Database) {}
+
+	find(sessionId: string): SessionIdentityRecord | undefined {
+		const row = this.db.query("SELECT session_id, secret_hash, registered_at, last_seen_at FROM session_identities WHERE session_id = ?").get(sessionId) as
+			| { session_id: string; secret_hash: string; registered_at: string; last_seen_at: string }
+			| null;
+		return row ? { sessionId: row.session_id, secretHash: row.secret_hash, registeredAt: row.registered_at, lastSeenAt: row.last_seen_at } : undefined;
+	}
+
+	upsert(record: SessionIdentityRecord): void {
+		this.db.transaction(() => {
+			this.evictOldestBeyondCap(record.sessionId);
+			this.db.query(`
+				INSERT INTO session_identities (session_id, secret_hash, registered_at, last_seen_at)
+				VALUES (?, ?, ?, ?)
+				ON CONFLICT(session_id) DO UPDATE SET secret_hash = excluded.secret_hash, registered_at = excluded.registered_at, last_seen_at = excluded.last_seen_at
+			`).run(record.sessionId, record.secretHash, record.registeredAt, record.lastSeenAt);
+		})();
+	}
+
+	remove(sessionId: string): void {
+		this.db.query("DELETE FROM session_identities WHERE session_id = ?").run(sessionId);
+	}
+
+	touch(sessionId: string, lastSeenAt: string): void {
+		this.db.query("UPDATE session_identities SET last_seen_at = ? WHERE session_id = ?").run(lastSeenAt, sessionId);
+	}
+
+	count(): number {
+		return (this.db.query("SELECT COUNT(*) AS count FROM session_identities").get() as { count: number }).count;
+	}
+
+	/** Bounds distinct registered session identities; evicts the least-recently-seen beyond the cap. */
+	private evictOldestBeyondCap(sessionId: string): void {
+		const exists = this.db.query("SELECT 1 FROM session_identities WHERE session_id = ?").get(sessionId);
+		if (exists) return;
+		if (this.count() < SESSION_IDENTITY_MAX_ROWS) return;
+		this.db.exec("DELETE FROM session_identities WHERE session_id = (SELECT session_id FROM session_identities ORDER BY last_seen_at ASC LIMIT 1)");
+	}
+}

package/src/cli-commands/benchmarks.ts

@@ -0,0 +1,140 @@
+import {
+	BENCHMARK_MAX_QUERY_LIMIT,
+	MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
+	MODEL_RANKING_DEFAULT_COST_WEIGHT,
+	MODEL_RANKING_DEFAULT_LATENCY_WEIGHT,
+	MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
+	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
+	MODEL_RANKING_MAX_SOURCES,
+} from "../constants.ts";
+import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "../domain/benchmark.ts";
+import type { ModelRecommendationInput } from "../domain/model-ranking-service.ts";
+import type { ModelCandidate, ModelRankingResult, ScopeAuthority, UtilityWeights } from "../domain/model-ranking.ts";
+import { TASK_DOMAINS, TASK_TYPES, type ModelTaskDomain, type ModelTaskType } from "../domain/model-observation.ts";
+import { humanField, type CliDependencies } from "./support.ts";
+import { parseCandidate } from "./route-args.ts";
+
+export const BENCHMARKS_USAGE_LINES = ["  benchmarks <status|refresh|list|rank> [options] [--json]"];
+
+interface BenchmarkArgs {
+	action: "status" | "refresh" | "list" | "rank";
+	json: boolean;
+	force: boolean;
+	query?: BenchmarkQuery;
+	recommendation?: ModelRecommendationInput & { session_id?: string; session_secret?: string };
+}
+
+function parseBenchmarkArgs(action: string | undefined, args: string[]): BenchmarkArgs | null {
+	if (action !== "status" && action !== "refresh" && action !== "list" && action !== "rank") return null;
+	let json = false;
+	let force = false;
+	const query: Partial<BenchmarkQuery> = {};
+	const candidates: ModelCandidate[] = [];
+	const sourceIds: string[] = [];
+	let scopeAuthority: ScopeAuthority = "available-models";
+	let domain: ModelTaskDomain = "general";
+	let type: ModelTaskType = "general";
+	let budgetPressure = 0;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	const weights: UtilityWeights = {
+		quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT, cost: MODEL_RANKING_DEFAULT_COST_WEIGHT,
+		latency: MODEL_RANKING_DEFAULT_LATENCY_WEIGHT, context: MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
+		reliability: MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
+	};
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument === "--force" && action === "refresh") { force = true; continue; }
+		const allowed = action === "list" ? ["--source", "--model", "--dimension", "--limit"]
+			: action === "rank" ? ["--candidate", "--source", "--domain", "--type", "--scope", "--budget", "--weight-quality", "--weight-cost", "--weight-latency", "--weight-context", "--weight-reliability", "--session-id", "--session-secret"] : [];
+		if (!allowed.includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (action === "list") {
+			if (argument === "--limit") {
+				const limit = Number(raw);
+				if (!Number.isSafeInteger(limit) || limit < 1 || limit > BENCHMARK_MAX_QUERY_LIMIT) return null;
+				query.limit = limit;
+			} else if (argument === "--source") query.sourceId = raw;
+			else if (argument === "--model") query.model = raw;
+			else query.dimension = raw;
+			continue;
+		}
+		if (argument === "--candidate") {
+			const candidate = parseCandidate(raw);
+			if (!candidate) return null;
+			candidates.push(candidate);
+		} else if (argument === "--source") sourceIds.push(raw);
+		else if (argument === "--domain") {
+			if (!TASK_DOMAINS.includes(raw as ModelTaskDomain)) return null;
+			domain = raw as ModelTaskDomain;
+		} else if (argument === "--type") {
+			if (!TASK_TYPES.includes(raw as ModelTaskType)) return null;
+			type = raw as ModelTaskType;
+		} else if (argument === "--scope") {
+			if (raw !== "exact-session" && raw !== "available-models") return null;
+			scopeAuthority = raw;
+		} else if (argument === "--budget") budgetPressure = Number(raw);
+		else if (argument === "--session-id") sessionId = raw;
+		else if (argument === "--session-secret") sessionSecret = raw;
+		else {
+			const weight = Number(raw);
+			if (!Number.isFinite(weight) || weight < 0 || weight > 10) return null;
+			weights[argument!.slice("--weight-".length) as keyof UtilityWeights] = weight;
+		}
+	}
+	if (action === "list" && query.sourceId === undefined) return null;
+	if (action === "rank" && (candidates.length === 0 || sourceIds.length > MODEL_RANKING_MAX_SOURCES || !Number.isFinite(budgetPressure) || budgetPressure < 0 || budgetPressure > 2)) return null;
+	return {
+		action, json, force,
+		...(action === "list" ? { query: query as BenchmarkQuery } : {}),
+		...(action === "rank" ? { recommendation: { candidates, sourceIds: [...new Set(sourceIds)], scopeAuthority, domain, type, budgetPressure, weights, ...(sessionId ? { session_id: sessionId } : {}), ...(sessionSecret ? { session_secret: sessionSecret } : {}) } } : {}),
+	};
+}
+
+export function formatBenchmarkStatus(result: BenchmarkRefreshResult): string {
+	if (result.sources.length === 0) return "Benchmark sources: none configured";
+	return ["Benchmark sources:", ...result.sources.map((source) => {
+		const state = source.ok === null ? "not refreshed" : source.ok ? "ready" : "refresh failed";
+		return `- ${source.id}: ${state} · ${source.observations.toLocaleString()} observations · ${source.hasEvidence ? "evidence retained" : "no evidence"}`;
+	})].join("\n");
+}
+
+export function formatBenchmarkQuery(result: BenchmarkQueryResult): string {
+	return [
+		`Benchmark evidence: ${humanField(result.sourceId)} · ${result.completeness} · ${result.freshness} · ${result.observations.length.toLocaleString()} observations`,
+		...result.observations.map((observation) => `- ${humanField(observation.model.canonical)} · ${humanField(observation.dimension)} ${observation.value.toLocaleString()} ${observation.unit} · ${humanField(observation.provenance.publisher)} · confidence ${(observation.provenance.confidence * 100).toFixed(0)}%`),
+	].join("\n");
+}
+
+export function formatModelRanking(result: ModelRankingResult): string {
+	return [
+		`Model ranking: ${result.completeness} · scope ${result.scopeAuthority}${result.scopeWarning ? " · advisory only" : ""}`,
+		...result.ranked.map((item, index) => `${index + 1}. ${humanField(item.identity)} · utility ${item.utility === null ? "unknown" : item.utility.toFixed(3)} · confidence ${(item.confidence * 100).toFixed(0)}%`),
+		...(result.scopeWarning ? [result.scopeWarning] : []),
+	].join("\n");
+}
+
+export async function runBenchmarksCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	const parsed = parseBenchmarkArgs(action, rest);
+	if (!parsed) return usage();
+	try {
+		if (parsed.action === "list") {
+			const result = await deps.client.call("benchmark.query", parsed.query!);
+			deps.stdout(parsed.json ? JSON.stringify(result) : formatBenchmarkQuery(result));
+		} else if (parsed.action === "rank") {
+			const result = await deps.client.call("models.rank", parsed.recommendation!);
+			deps.stdout(parsed.json ? JSON.stringify(result) : formatModelRanking(result));
+		} else {
+			const result = parsed.action === "refresh"
+				? await deps.client.call("benchmark.refresh", { force: parsed.force })
+				: await deps.client.call("benchmark.status", {});
+			deps.stdout(parsed.json ? JSON.stringify(result) : formatBenchmarkStatus(result));
+		}
+		return 0;
+	} catch (error) {
+		deps.stderr(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli-commands/compaction.ts

@@ -0,0 +1,17 @@
+import type { CompactionDurationEstimate } from "../domain/context-telemetry.ts";
+import { callAndPrint, type CliDependencies } from "./support.ts";
+import { parseJsonOnlyArgs } from "./router.ts";
+
+export function formatCompactionEstimate(estimate: CompactionDurationEstimate): string {
+	if (estimate.confidence === "cold-start" || estimate.ms === null) {
+		return `Compaction duration: cold-start (${estimate.sampleSize.toLocaleString()} sample(s), not enough evidence yet)`;
+	}
+	return `Compaction duration: ~${estimate.ms.toLocaleString()}ms learned from ${estimate.sampleSize.toLocaleString()} sample(s)`;
+}
+
+export async function runCompactionCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	if (action !== "estimate") return usage();
+	const parsed = parseJsonOnlyArgs(rest);
+	if (!parsed) return usage();
+	return callAndPrint(deps, "compaction.estimate", {}, parsed.json, formatCompactionEstimate);
+}

package/src/cli-commands/context.ts

@@ -0,0 +1,49 @@
+import type { ContextAssessment } from "../domain/context-telemetry.ts";
+import type { CliDependencies } from "./support.ts";
+
+export const CONTEXT_USAGE_LINES = ["  context [--since <ms>] [--until <ms>] [--json]"];
+
+function parseContextArgs(args: string[]): { input: { since?: number; until?: number }; json: boolean } | null {
+	const input: { since?: number; until?: number } = {};
+	let json = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument !== "--since" && argument !== "--until") return null;
+		const raw = args[++index];
+		const value = raw === undefined ? Number.NaN : Number(raw);
+		if (!Number.isSafeInteger(value) || value < 0) return null;
+		if (argument === "--since") input.since = value;
+		else input.until = value;
+	}
+	if (input.since !== undefined && input.until !== undefined && input.until < input.since) return null;
+	return { input, json };
+}
+
+function value(value: number | null, suffix = ""): string {
+	return value === null ? "unknown" : `${Math.round(value).toLocaleString()}${suffix}`;
+}
+
+export function formatContextAssessment(summary: ContextAssessment): string {
+	return [
+		`Context assessment: ${summary.completeness}`,
+		`Papyrus injection: ${summary.injection.runs} runs · avg ${value(summary.injection.averageCharacters, " chars")} · p95 ${value(summary.injection.p95Characters, " chars")} · max ${value(summary.injection.maxCharacters, " chars")}`,
+		`Injection mix: rules ${summary.injection.ruleCharacters.toLocaleString()} chars · tasks ${summary.injection.taskCharacters.toLocaleString()} chars · estimated ${summary.injection.estimatedTokens.toLocaleString()} tokens · unchanged ${summary.injection.unchangedRate === null ? "unknown" : `${(summary.injection.unchangedRate * 100).toFixed(1)}%`}`,
+		`Compactions: ${summary.compaction.completed} completed · ${summary.compaction.aborted} aborted · avg ${value(summary.compaction.averageDurationMs, "ms")} · ${summary.compaction.perRun === null ? "unknown" : summary.compaction.perRun.toFixed(3)} per agent run · ${summary.compaction.perTurn === null ? "unknown" : summary.compaction.perTurn.toFixed(3)} per turn`,
+		`Between compactions: ${value(summary.compaction.averageTurnsBetween, " turns")} · ${value(summary.compaction.averageProviderTokensBetween, " provider tokens")} · ${value(summary.compaction.averageCacheReadTokensBetween, " cache-read tokens")}`,
+		`Reasons: threshold ${summary.compaction.reasons.threshold} · overflow ${summary.compaction.reasons.overflow} · manual ${summary.compaction.reasons.manual}`,
+	].join("\n");
+}
+
+export async function runContextCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	const parsed = parseContextArgs([...(action === undefined ? [] : [action]), ...rest]);
+	if (!parsed) return usage();
+	try {
+		const summary = await deps.client.call("context.assess", parsed.input);
+		deps.stdout(parsed.json ? JSON.stringify(summary) : formatContextAssessment(summary));
+		return 0;
+	} catch (error) {
+		deps.stderr(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli-commands/metrics.ts

@@ -0,0 +1,296 @@
+import { CLI_METRICS_HUMAN_MAX_ROWS, MAX_QUERY_LIMIT, MAX_USAGE_BUCKETS, METRIC_BATCH_MAX_OBSERVATIONS, USAGE_MAX_DISTINCT_SCOPES } from "../constants.ts";
+import { METRIC_UNITS, type MetricObservation, type MetricQuery, type MetricUnit, type StoredMetricObservation } from "../domain/metric.ts";
+import type { TaskCostSummary } from "../domain/task-cost.ts";
+import { callAndPrint, humanField, type CliDependencies } from "./support.ts";
+
+export const METRICS_USAGE_LINES = [
+	"  metrics record --source <s> --scope <s> --metric <s> --value <number|null> --unit <unit> [--observed-at <ms>] [--attributes <json>] [--json]",
+	`  metrics record-batch --observations <json-array, max ${METRIC_BATCH_MAX_OBSERVATIONS}> [--json]`,
+	"  metrics query [--source <s>] [--scope <s>] [--metric <s>] [--since <ms>] [--until <ms>] [--limit <n>] [--order asc|desc] [--json]",
+	"  metrics prune --before <ms> [--force] [--json] (force required if before is newer than 24h ago)",
+	`  metrics distinct-scopes --source <s> --since <ms> --until <ms> [--limit 1..${USAGE_MAX_DISTINCT_SCOPES}] [--json]`,
+	`  metrics usage-series --source <s> --since <ms> --until <ms> --bucket-size-ms <ms> --bucket-count 1..${MAX_USAGE_BUCKETS} [--scope-limit 1..${USAGE_MAX_DISTINCT_SCOPES}] [--json]`,
+	"  metrics cost-by-task --since <ms> --until <ms> [--json]",
+];
+
+interface MetricsRecordArgs { input: MetricObservation; json: boolean }
+
+function parseMetricsRecordArgs(args: string[]): MetricsRecordArgs | null {
+	let json = false;
+	let source: string | undefined;
+	let scope: string | undefined;
+	let metric: string | undefined;
+	let value: number | null | undefined;
+	let unit: MetricUnit | undefined;
+	let observedAt: number | undefined;
+	let attributes: Record<string, unknown> | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--source", "--scope", "--metric", "--value", "--unit", "--observed-at", "--attributes"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--source") source = raw;
+		else if (argument === "--scope") scope = raw;
+		else if (argument === "--metric") metric = raw;
+		else if (argument === "--value") {
+			if (raw.toLowerCase() === "null") value = null;
+			else {
+				const parsed = Number(raw);
+				if (!Number.isFinite(parsed)) return null;
+				value = parsed;
+			}
+		} else if (argument === "--unit") {
+			if (!METRIC_UNITS.includes(raw as MetricUnit)) return null;
+			unit = raw as MetricUnit;
+		} else if (argument === "--observed-at") {
+			const parsed = Number(raw);
+			if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+			observedAt = parsed;
+		} else {
+			try {
+				const parsed = JSON.parse(raw);
+				if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+				attributes = parsed as Record<string, unknown>;
+			} catch {
+				return null;
+			}
+		}
+	}
+	if (source === undefined || scope === undefined || metric === undefined || value === undefined || unit === undefined) return null;
+	return {
+		json,
+		input: {
+			source, scope, metric, value, unit,
+			observedAt: observedAt ?? Date.now(),
+			...(attributes ? { attributes } : {}),
+		},
+	};
+}
+
+interface MetricsRecordBatchArgs { input: { observations: MetricObservation[] }; json: boolean }
+
+function parseMetricsRecordBatchArgs(args: string[]): MetricsRecordBatchArgs | null {
+	let json = false;
+	let observations: unknown;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument !== "--observations") return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		try {
+			observations = JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	}
+	if (!Array.isArray(observations) || observations.length === 0 || observations.length > METRIC_BATCH_MAX_OBSERVATIONS) return null;
+	return { input: { observations: observations as MetricObservation[] }, json };
+}
+
+interface MetricsQueryArgs { input: MetricQuery; json: boolean }
+
+function parseMetricsQueryArgs(args: string[]): MetricsQueryArgs | null {
+	let json = false;
+	const input: MetricQuery = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--source", "--scope", "--metric", "--since", "--until", "--limit", "--order"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--source") input.source = raw;
+		else if (argument === "--scope") input.scope = raw;
+		else if (argument === "--metric") input.metric = raw;
+		else if (argument === "--order") {
+			if (raw !== "asc" && raw !== "desc") return null;
+			input.order = raw;
+		} else {
+			const parsed = Number(raw);
+			if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+			if (argument === "--since") input.since = parsed;
+			else if (argument === "--until") input.until = parsed;
+			else {
+				if (parsed < 1 || parsed > MAX_QUERY_LIMIT) return null;
+				input.limit = parsed;
+			}
+		}
+	}
+	if (input.since !== undefined && input.until !== undefined && input.until < input.since) return null;
+	return { input, json };
+}
+
+interface MetricsDistinctScopesArgs { input: { source: string; since: number; until: number; limit?: number }; json: boolean }
+
+function parseMetricsDistinctScopesArgs(args: string[]): MetricsDistinctScopesArgs | null {
+	let json = false;
+	let source: string | undefined;
+	let since: number | undefined;
+	let until: number | undefined;
+	let limit: number | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--source", "--since", "--until", "--limit"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--source") { source = raw; continue; }
+		const parsed = Number(raw);
+		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+		if (argument === "--since") since = parsed;
+		else if (argument === "--until") until = parsed;
+		else {
+			if (parsed < 1 || parsed > USAGE_MAX_DISTINCT_SCOPES) return null;
+			limit = parsed;
+		}
+	}
+	if (source === undefined || since === undefined || until === undefined || until < since) return null;
+	return { input: { source, since, until, ...(limit === undefined ? {} : { limit }) }, json };
+}
+
+interface MetricsUsageSeriesArgs { input: { source: string; since: number; until: number; bucketSizeMs: number; bucketCount: number; scopeLimit?: number }; json: boolean }
+
+function parseMetricsUsageSeriesArgs(args: string[]): MetricsUsageSeriesArgs | null {
+	let json = false;
+	let source: string | undefined;
+	let since: number | undefined;
+	let until: number | undefined;
+	let bucketSizeMs: number | undefined;
+	let bucketCount: number | undefined;
+	let scopeLimit: number | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!(["--source", "--since", "--until", "--bucket-size-ms", "--bucket-count", "--scope-limit"].includes(argument ?? ""))) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--source") { source = raw; continue; }
+		const parsed = Number(raw);
+		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+		if (argument === "--since") since = parsed;
+		else if (argument === "--until") until = parsed;
+		else if (argument === "--bucket-size-ms") { if (parsed < 1) return null; bucketSizeMs = parsed; }
+		else if (argument === "--bucket-count") { if (parsed < 1 || parsed > MAX_USAGE_BUCKETS) return null; bucketCount = parsed; }
+		else { if (parsed < 1 || parsed > USAGE_MAX_DISTINCT_SCOPES) return null; scopeLimit = parsed; }
+	}
+	if (source === undefined || since === undefined || until === undefined || until < since || bucketSizeMs === undefined || bucketCount === undefined) return null;
+	return { input: { source, since, until, bucketSizeMs, bucketCount, ...(scopeLimit === undefined ? {} : { scopeLimit }) }, json };
+}
+
+interface CostByTaskArgs { input: { since: number; until: number }; json: boolean }
+
+function parseCostByTaskArgs(args: string[]): CostByTaskArgs | null {
+	let json = false;
+	let since: number | undefined;
+	let until: number | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--since", "--until"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		const parsed = Number(raw);
+		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+		if (argument === "--since") since = parsed;
+		else until = parsed;
+	}
+	if (since === undefined || until === undefined || until < since) return null;
+	return { input: { since, until }, json };
+}
+
+interface MetricsPruneArgs { input: { before: number; force?: boolean }; json: boolean }
+
+function parseMetricsPruneArgs(args: string[]): MetricsPruneArgs | null {
+	let json = false;
+	let force = false;
+	let before: number | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument === "--force") { force = true; continue; }
+		if (argument !== "--before") return null;
+		const raw = args[++index];
+		const parsed = Number(raw);
+		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+		before = parsed;
+	}
+	if (before === undefined) return null;
+	return { input: { before, ...(force ? { force } : {}) }, json };
+}
+
+export function formatMetricsQuery(rows: StoredMetricObservation[]): string {
+	if (rows.length === 0) return "Metrics: no observations matched";
+	const shown = rows.slice(0, CLI_METRICS_HUMAN_MAX_ROWS);
+	const lines = [
+		`Metrics: ${rows.length.toLocaleString()} observation(s)${rows.length > shown.length ? ` (showing first ${shown.length})` : ""}`,
+		...shown.map((row) => `- ${humanField(row.source)}/${humanField(row.scope)}/${humanField(row.metric)} = ${row.value === null ? "null" : row.value} ${row.unit} @ ${new Date(row.observedAt).toISOString()}`),
+	];
+	return lines.join("\n");
+}
+
+export function formatMetricsDistinctScopes(scopes: string[]): string {
+	if (scopes.length === 0) return "Scopes: none matched";
+	return [`Scopes: ${scopes.length.toLocaleString()}`, ...scopes.map((scope) => `- ${humanField(scope)}`)].join("\n");
+}
+
+export function formatMetricsUsageSeries(result: { rows: Array<{ scope: string; metric: string; bucketIndex: number; sum: number }>; truncated: boolean }): string {
+	if (result.rows.length === 0) return `Usage series: no data${result.truncated ? " (scope limit reached)" : ""}`;
+	const lines = [`Usage series: ${result.rows.length.toLocaleString()} bucket(s)${result.truncated ? " (scope limit reached)" : ""}`];
+	for (const row of result.rows) lines.push(`- ${humanField(row.scope)}/${humanField(row.metric)} bucket ${row.bucketIndex}: ${row.sum.toLocaleString()}`);
+	return lines.join("\n");
+}
+
+function formatUsdAmount(amount: number): string {
+	return `$${amount.toFixed(Math.abs(amount) < 0.01 && amount !== 0 ? 4 : 2)}`;
+}
+
+export function formatCostByTask(summary: TaskCostSummary): string {
+	const lines = [
+		`Cost by task: ${summary.entries.length.toLocaleString()} task(s)${summary.truncated ? " (query limit reached; totals are a lower bound)" : ""}`,
+		...summary.entries.flatMap((entry) => [
+			`- ${humanField(entry.taskId)}: ${formatUsdAmount(entry.costUsd)} · ↑${entry.inputTokens.toLocaleString()} ↓${entry.outputTokens.toLocaleString()} R${entry.cacheReadTokens.toLocaleString()} W${entry.cacheWriteTokens.toLocaleString()}`,
+			...entry.byModel.map((model) => `    · ${humanField(model.provider)}/${humanField(model.model)} (${humanField(model.thinking)}): ${formatUsdAmount(model.costUsd)} · ↑${model.inputTokens.toLocaleString()} ↓${model.outputTokens.toLocaleString()} R${model.cacheReadTokens.toLocaleString()} W${model.cacheWriteTokens.toLocaleString()}`),
+		]),
+		`Unattributed spend (no task was focused): ${formatUsdAmount(summary.unattributedCostUsd)}`,
+	];
+	return lines.join("\n");
+}
+
+export async function runMetricsCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	if (action === "record") {
+		const parsed = parseMetricsRecordArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.record", parsed.input, parsed.json, (row) => formatMetricsQuery([row]));
+	}
+	if (action === "record-batch") {
+		const parsed = parseMetricsRecordBatchArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.record_batch", parsed.input, parsed.json, formatMetricsQuery);
+	}
+	if (action === "query") {
+		const parsed = parseMetricsQueryArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.query", parsed.input, parsed.json, formatMetricsQuery);
+	}
+	if (action === "prune") {
+		const parsed = parseMetricsPruneArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.prune", parsed.input, parsed.json, (result) => `Pruned ${result.deleted.toLocaleString()} observation(s)`);
+	}
+	if (action === "distinct-scopes") {
+		const parsed = parseMetricsDistinctScopesArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.distinct_scopes", parsed.input, parsed.json, formatMetricsDistinctScopes);
+	}
+	if (action === "usage-series") {
+		const parsed = parseMetricsUsageSeriesArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.usage_series", parsed.input, parsed.json, formatMetricsUsageSeries);
+	}
+	if (action === "cost-by-task") {
+		const parsed = parseCostByTaskArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.cost_by_task", parsed.input, parsed.json, formatCostByTask);
+	}
+	return usage();
+}