@danypops/jittor 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
@@ -22,6 +22,10 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "@danypops/daemon-kit": "^0.3.1",
+    "google-auth-library": "^10.9.0"
+  },
   "devDependencies": {
     "bun-types": "latest"
   },

package/src/adapters/openrouter-benchmark-index-source.ts

@@ -83,7 +83,8 @@ export class OpenRouterBenchmarkIndexSource implements BenchmarkSource {
 			return [
 				validateBenchmarkObservation({ ...common, dimension: "quality-coding", value: requiredNumber(row["coding_index"], "coding index"), unit: "ratio", methodology }),
 				validateBenchmarkObservation({ ...common, dimension: "quality-general", value: requiredNumber(row["intelligence_index"], "intelligence index"), unit: "ratio", methodology }),
-				validateBenchmarkObservation({ ...common, dimension: "quality-planning", value: requiredNumber(row["agentic_index"], "agentic index"), unit: "ratio", methodology }),
+				// agentic_index measures tool-use/agentic execution style, an activity (type), not a subject-matter domain.
+				validateBenchmarkObservation({ ...common, dimension: "quality-type-planning", value: requiredNumber(row["agentic_index"], "agentic index"), unit: "ratio", methodology }),
 				validateBenchmarkObservation({ ...common, dimension: "price-input", value: price(pricing["prompt"], "prompt pricing"), unit: "usd", methodology: { ...methodology, basis: "OpenRouter USD per input token" } }),
 				validateBenchmarkObservation({ ...common, dimension: "price-output", value: price(pricing["completion"], "completion pricing"), unit: "usd", methodology: { ...methodology, basis: "OpenRouter USD per output token" } }),
 			];

package/src/adapters/openrouter-design-arena-source.ts

@@ -0,0 +1,105 @@
+import {
+	BENCHMARK_MAX_MODELS_PER_SOURCE,
+	BENCHMARK_REFRESH_INTERVAL_MS,
+	BENCHMARK_SOURCE_MAX_RESPONSE_BYTES,
+} from "../constants.ts";
+import { normalizeModelIdentity, validateBenchmarkObservation, type BenchmarkObservation, type BenchmarkSourceSnapshot } from "../domain/benchmark.ts";
+import type { BenchmarkSource } from "../ports/benchmark-source.ts";
+import { contractRecord } from "../providers/openrouter-contracts.ts";
+import type { OpenRouterBenchmarkTransport } from "./openrouter-benchmark-source.ts";
+
+const SOURCE_ID = "openrouter-design-arena";
+const BASE_URL = `https://openrouter.ai/api/v1/benchmarks?source=design-arena&max_results=${BENCHMARK_MAX_MODELS_PER_SOURCE}`;
+
+/**
+ * Design Arena publishes rankings across dozens of arena/category pairs (music, video, TTS,
+ * ASCII art, ...) -- most of them have nothing to do with a text coding agent's model choice.
+ * This is a deliberate, bounded allowlist of the categories that measure frontend/UI-generation
+ * skill, the one facet of "design" quality relevant to routing a coding agent. Extending this
+ * list is a data curation decision (does the category's skill actually predict something a
+ * coding agent needs), not a mechanical one.
+ */
+const RELEVANT_CATEGORIES = ["codecategories", "website", "uicomponent", "dataviz", "svg"] as const;
+
+function requiredText(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > 500) throw new Error(`OpenRouter Design Arena benchmark ${name} schema changed`);
+	return value;
+}
+
+function requiredNumber(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`OpenRouter Design Arena benchmark ${name} schema changed`);
+	return value;
+}
+
+function identityFromOpenRouterId(openRouterId: string): { provider: string; model: string } {
+	const separator = openRouterId.indexOf("/");
+	if (separator <= 0 || separator === openRouterId.length - 1) throw new Error("OpenRouter Design Arena model identity schema changed");
+	return { provider: openRouterId.slice(0, separator), model: openRouterId.slice(separator + 1) };
+}
+
+export class OpenRouterDesignArenaSource implements BenchmarkSource {
+	readonly id = SOURCE_ID;
+
+	constructor(
+		private readonly apiKey: string,
+		private readonly transport: OpenRouterBenchmarkTransport = fetch,
+		private readonly clock: () => number = Date.now,
+	) {
+		if (apiKey.length === 0) throw new Error("OpenRouter API key is required for Design Arena benchmark evidence");
+	}
+
+	async fetch(): Promise<BenchmarkSourceSnapshot> {
+		const retrievedAt = this.clock();
+		if (!Number.isSafeInteger(retrievedAt) || retrievedAt <= 0) throw new Error("benchmark retrieval time is invalid");
+		const perCategory = await Promise.all(RELEVANT_CATEGORIES.map((category) => this.fetchCategory(category, retrievedAt)));
+		const revisions = new Set(perCategory.map((page) => page.revision));
+		const observations = perCategory.flatMap((page) => page.observations);
+		return { sourceId: this.id, snapshotId: `${this.id}:${[...revisions].sort().join(",")}`, retrievedAt, observations };
+	}
+
+	private async fetchCategory(category: string, retrievedAt: number): Promise<{ revision: string; observations: BenchmarkObservation[] }> {
+		const url = `${BASE_URL}&task_type=${category}`;
+		const response = await this.transport(new Request(url, { headers: { authorization: `Bearer ${this.apiKey}` } }));
+		if (!response.ok) throw new Error(`OpenRouter Design Arena benchmarks failed with HTTP ${response.status}`);
+		const text = await response.text();
+		if (new TextEncoder().encode(text).byteLength > BENCHMARK_SOURCE_MAX_RESPONSE_BYTES) throw new Error("OpenRouter Design Arena benchmark response exceeds the size limit");
+		let payload: unknown;
+		try { payload = JSON.parse(text); } catch { throw new Error("OpenRouter Design Arena benchmark response is not valid JSON"); }
+		const root = contractRecord(payload, "benchmark response");
+		const meta = contractRecord(root["meta"], "benchmark metadata");
+		if (!Array.isArray(root["data"]) || root["data"].length > BENCHMARK_MAX_MODELS_PER_SOURCE) throw new Error("OpenRouter Design Arena benchmark result count is invalid");
+		if (requiredText(meta["source"], "source") !== "design-arena") throw new Error("OpenRouter Design Arena benchmark source schema changed");
+		const asOf = requiredText(meta["as_of"], "as-of date");
+		const publishedAt = Date.parse(asOf);
+		if (!Number.isSafeInteger(publishedAt) || publishedAt <= 0) throw new Error("OpenRouter Design Arena benchmark publication date schema changed");
+		const revision = `${category}:${asOf}`;
+		const observations = root["data"].flatMap((value): BenchmarkObservation[] => {
+			const row = contractRecord(value, "benchmark row");
+			if (requiredText(row["source"], "row source") !== "design-arena") throw new Error("OpenRouter Design Arena benchmark row source schema changed");
+			// A null open_router_id means the model isn't reachable through OpenRouter at all
+			// (proprietary platform, image/video generator, deprecated model) -- not evidence
+			// Jittor can ever route against, so the row is skipped rather than rejected.
+			const openRouterId = row["open_router_id"];
+			if (openRouterId === null) return [];
+			const { provider, model } = identityFromOpenRouterId(requiredText(openRouterId, "open_router_id"));
+			const identity = normalizeModelIdentity(provider, model, [`openrouter/${provider}/${model}`]);
+			const provenance = {
+				sourceId: SOURCE_ID,
+				sourceType: "independent" as const,
+				publisher: "Design Arena via OpenRouter",
+				url: BASE_URL,
+				revision,
+				publishedAt,
+				retrievedAt,
+				freshUntil: retrievedAt + BENCHMARK_REFRESH_INTERVAL_MS,
+				license: "OpenRouter API terms; Design Arena terms apply",
+				confidence: 0.7,
+			};
+			const methodology = { basis: "Design Arena Elo rating via OpenRouter", category, asOf };
+			return [validateBenchmarkObservation({
+				model: identity, dimension: "quality-design", value: requiredNumber(row["elo"], "elo rating"), unit: "elo", provenance, methodology,
+			})];
+		});
+		return { revision, observations };
+	}
+}

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

@@ -1,8 +1,9 @@
 import type { Database } from "bun:sqlite";
-import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT } from "../constants.ts";
+import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, USAGE_AGGREGATE_MAX_ROWS } from "../constants.ts";
 import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../domain/metric.ts";
 import { validateMetricObservation } from "../domain/metric.ts";
-import type { MetricStore } from "../ports/metric-store.ts";
+import type { UsageAggregateRow } from "../domain/usage.ts";
+import type { DistinctScopesFilter, MetricStore, UsageAggregateFilter } from "../ports/metric-store.ts";
 
 interface MetricRow {
 	id: number;
@@ -75,6 +76,46 @@ export class SQLiteMetricStore implements MetricStore {
 		return rows.map(fromRow);
 	}
 
+	distinctScopes(filter: DistinctScopesFilter): string[] {
+		const limit = Math.max(1, Math.min(MAX_QUERY_LIMIT, Math.floor(filter.limit)));
+		const rows = this.db.query(`
+			SELECT DISTINCT scope FROM metric_observations
+			WHERE source = ? AND observed_at >= ? AND observed_at <= ?
+			ORDER BY scope ASC
+			LIMIT ?
+		`).all(filter.source, filter.since, filter.until, limit) as Array<{ scope: string }>;
+		return rows.map((row) => row.scope);
+	}
+
+	aggregateUsage(filter: UsageAggregateFilter): UsageAggregateRow[] {
+		if (filter.scopes.length === 0) return [];
+		if (!Number.isFinite(filter.bucketSizeMs) || filter.bucketSizeMs <= 0) throw new Error("bucketSizeMs must be a positive number");
+		if (!Number.isInteger(filter.bucketCount) || filter.bucketCount <= 0) throw new Error("bucketCount must be a positive integer");
+		const scopePlaceholders = filter.scopes.map(() => "?").join(", ");
+		// MIN(a, b) is SQLite's scalar two-argument form (smallest of the arguments), mirroring
+		// usageBucketIndex's own `Math.min(bucketCount - 1, Math.floor(...))` clamp exactly, so a bucket
+		// this returns always matches the same-indexed bucket the client-side window renders.
+		const rows = this.db.query(`
+			SELECT scope, metric,
+				MIN(CAST((observed_at - ?) AS REAL) / ?, ? - 1) AS bucket_index_raw,
+				SUM(value) AS sum
+			FROM metric_observations
+			WHERE source = ? AND observed_at >= ? AND observed_at <= ? AND value >= 0 AND scope IN (${scopePlaceholders})
+			GROUP BY scope, metric, CAST(bucket_index_raw AS INTEGER)
+			LIMIT ?
+		`).all(
+			filter.since, filter.bucketSizeMs, filter.bucketCount,
+			filter.source, filter.since, filter.until, ...filter.scopes,
+			USAGE_AGGREGATE_MAX_ROWS,
+		) as Array<{ scope: string; metric: string; bucket_index_raw: number; sum: number }>;
+		return rows.map((row) => ({
+			scope: row.scope,
+			metric: row.metric,
+			bucketIndex: Math.max(0, Math.floor(row.bucket_index_raw)),
+			sum: row.sum,
+		}));
+	}
+
 	pruneBefore(cutoff: number): number {
 		if (!Number.isSafeInteger(cutoff) || cutoff < 0) throw new Error("cutoff must be a non-negative integer timestamp");
 		return this.db.query("DELETE FROM metric_observations WHERE observed_at < ?").run(cutoff).changes;

package/src/cli.ts

@@ -17,16 +17,19 @@ import {
 	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
 	MODEL_RANKING_MAX_SOURCES,
 	SYSTEMD_UNIT_NAME,
+	MAX_USAGE_BUCKETS,
+	USAGE_MAX_DISTINCT_SCOPES,
 } from "./constants.ts";
 import { connectJittorClient, type JittorClient } from "./client.ts";
 import { serveMain } from "./daemon.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_CLASSES, type ModelTaskClass } from "./domain/model-observation.ts";
+import { TASK_DOMAINS, TASK_TYPES, type ModelTaskDomain, type ModelTaskType } from "./domain/model-observation.ts";
 import type { ContextAssessment } from "./domain/context-telemetry.ts";
 import { METRIC_UNITS, type MetricObservation, type MetricQuery, type MetricUnit, type StoredMetricObservation } from "./domain/metric.ts";
 import type { CompactionDurationEstimate } from "./domain/context-telemetry.ts";
+import type { TaskCostSummary } from "./domain/task-cost.ts";
 import type { PolicyDecision, Route } from "./policy.ts";
 import type { RouteOverride, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
 import { EXPECTED_OPERATION_NAMES, type OperationInputs, type OperationName, type OperationOutputs } from "./service.ts";
@@ -104,7 +107,10 @@ function usage(stderr: (line: string) => void): number {
 		"  benchmarks <status|refresh|list|rank> [options] [--json]",
 		"  metrics record --source <s> --scope <s> --metric <s> --value <number|null> --unit <unit> [--observed-at <ms>] [--attributes <json>] [--json]",
 		"  metrics query [--source <s>] [--scope <s>] [--metric <s>] [--since <ms>] [--until <ms>] [--limit <n>] [--order asc|desc] [--json]",
-		"  metrics prune --before <ms> [--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]",
 		"  telemetry poll [--json]",
 		"  compaction estimate [--json]",
 		"  router <status|decide|pause|resume|clear-override> [--json]",
@@ -225,14 +231,93 @@ function parseMetricsQueryArgs(args: string[]): MetricsQueryArgs | null {
 	return { input, json };
 }
 
-interface MetricsPruneArgs { input: { before: number }; json: boolean }
+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);
@@ -240,7 +325,7 @@ function parseMetricsPruneArgs(args: string[]): MetricsPruneArgs | null {
 		before = parsed;
 	}
 	if (before === undefined) return null;
-	return { input: { before }, json };
+	return { input: { before, ...(force ? { force } : {}) }, json };
 }
 
 interface RouterOverrideArgs { input: RouteOverride; json: boolean }
@@ -356,7 +441,8 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 	const candidates: ModelCandidate[] = [];
 	const sourceIds: string[] = [];
 	let scopeAuthority: ScopeAuthority = "available-models";
-	let taskClass: ModelTaskClass = "general";
+	let domain: ModelTaskDomain = "general";
+	let type: ModelTaskType = "general";
 	let budgetPressure = 0;
 	const weights: UtilityWeights = {
 		quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT, cost: MODEL_RANKING_DEFAULT_COST_WEIGHT,
@@ -368,7 +454,7 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 		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", "--task", "--scope", "--budget", "--weight-quality", "--weight-cost", "--weight-latency", "--weight-context", "--weight-reliability"] : [];
+			: action === "rank" ? ["--candidate", "--source", "--domain", "--type", "--scope", "--budget", "--weight-quality", "--weight-cost", "--weight-latency", "--weight-context", "--weight-reliability"] : [];
 		if (!allowed.includes(argument ?? "")) return null;
 		const raw = args[++index];
 		if (raw === undefined || raw.length === 0) return null;
@@ -387,9 +473,12 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 			if (!candidate) return null;
 			candidates.push(candidate);
 		} else if (argument === "--source") sourceIds.push(raw);
-		else if (argument === "--task") {
-			if (!TASK_CLASSES.includes(raw as ModelTaskClass)) return null;
-			taskClass = raw as ModelTaskClass;
+		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;
@@ -405,7 +494,7 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 	return {
 		action, json, force,
 		...(action === "list" ? { query: query as BenchmarkQuery } : {}),
-		...(action === "rank" ? { recommendation: { candidates, sourceIds: [...new Set(sourceIds)], scopeAuthority, taskClass, budgetPressure, weights } } : {}),
+		...(action === "rank" ? { recommendation: { candidates, sourceIds: [...new Set(sourceIds)], scopeAuthority, domain, type, budgetPressure, weights } } : {}),
 	};
 }
 
@@ -465,6 +554,31 @@ export function formatMetricsQuery(rows: StoredMetricObservation[]): string {
 	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.map((entry) => `- ${humanField(entry.taskId)}: ${formatUsdAmount(entry.costUsd)} · ↑${entry.inputTokens.toLocaleString()} ↓${entry.outputTokens.toLocaleString()} R${entry.cacheReadTokens.toLocaleString()} W${entry.cacheWriteTokens.toLocaleString()}`),
+		`Unattributed spend (no task was focused): ${formatUsdAmount(summary.unattributedCostUsd)}`,
+	];
+	return lines.join("\n");
+}
+
 export function formatTelemetryPoll(result: TelemetryPollResult): string {
 	if (result.sources.length === 0) return "Telemetry: no sources configured";
 	return ["Telemetry:", ...result.sources.map((source) => {
@@ -535,6 +649,21 @@ export async function runCli(args: string[], deps: CliDependencies = DEFAULT_DEP
 			if (!parsed) return usage(deps.stderr);
 			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(deps.stderr);
+			return callAndPrint(deps, "metrics.distinct_scopes", parsed.input, parsed.json, formatMetricsDistinctScopes);
+		}
+		if (action === "usage-series") {
+			const parsed = parseMetricsUsageSeriesArgs(rest);
+			if (!parsed) return usage(deps.stderr);
+			return callAndPrint(deps, "metrics.usage_series", parsed.input, parsed.json, formatMetricsUsageSeries);
+		}
+		if (action === "cost-by-task") {
+			const parsed = parseCostByTaskArgs(rest);
+			if (!parsed) return usage(deps.stderr);
+			return callAndPrint(deps, "metrics.cost_by_task", parsed.input, parsed.json, formatCostByTask);
+		}
 		return usage(deps.stderr);
 	}
 	if (command === "telemetry") {

package/src/client.ts

@@ -1,51 +1,19 @@
+import { AuthenticatedRpcClient, type FetchTransport } from "@danypops/daemon-kit/rpc-client";
 import type { OperationInputs, OperationName, OperationOutputs } from "./service.ts";
 import { ensureAuthToken, readDaemonHandle, resolveJittorPaths, type JittorPaths } from "./state.ts";
 
-export type FetchTransport = (request: Request) => Promise<Response>;
+export type { FetchTransport };
 
-export class JittorClient {
-	constructor(
-		private readonly baseUrl: string,
-		private readonly token: string,
-		private readonly transport: FetchTransport = fetch,
-	) {}
-
-	async call<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]> {
-		const response = await this.transport(new Request(`${this.baseUrl}/api/v1/ops`, {
-			method: "POST",
-			headers: { authorization: `Bearer ${this.token}`, "content-type": "application/json" },
-			body: JSON.stringify({ op: operation, input }),
-		}));
-		const body = await response.json() as { result?: OperationOutputs[Name]; error?: string };
-		if (!response.ok) throw new Error(body.error ?? `Jittor operation failed with HTTP ${response.status}`);
-		return body.result as OperationOutputs[Name];
-	}
-
-	async operations(): Promise<OperationName[]> {
-		const response = await this.transport(new Request(`${this.baseUrl}/api/v1/ops`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		const body = await response.json() as { operations?: OperationName[]; error?: string };
-		if (!response.ok) throw new Error(body.error ?? `Jittor discovery failed with HTTP ${response.status}`);
-		return body.operations ?? [];
-	}
-
-	async ready(): Promise<boolean> {
-		const response = await this.transport(new Request(`${this.baseUrl}/ready`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		if (response.status === 503) return false;
-		if (!response.ok) throw new Error(`Jittor readiness check failed with HTTP ${response.status}`);
-		return true;
-	}
-
-	async health(): Promise<{ ok: true; version: string }> {
-		const response = await this.transport(new Request(`${this.baseUrl}/health`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		const body = await response.json() as { ok?: boolean; version?: string; error?: string };
-		if (!response.ok || body.ok !== true || typeof body.version !== "string") throw new Error(body.error ?? "Jittor health check failed");
-		return { ok: true, version: body.version };
+/**
+ * Jittor's typed authenticated RPC client, now a thin named subclass of
+ * `@danypops/daemon-kit/rpc-client`'s `AuthenticatedRpcClient` -- the shared substrate factored
+ * out after jittor's own client.ts and web-spider-daemon's were found byte-identical (see
+ * daemon-kit's README). Keeps the old 3-positional-argument constructor so every existing call
+ * site is untouched by this migration.
+ */
+export class JittorClient extends AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs> {
+	constructor(baseUrl: string, token: string, transport: FetchTransport = fetch) {
+		super(baseUrl, token, { label: "Jittor", transport });
 	}
 }
 

package/src/constants.ts

@@ -1,4 +1,3 @@
-export const SQLITE_SCHEMA_VERSION = 1;
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
 export const DEFAULT_QUERY_LIMIT = 1_000;
 export const MAX_QUERY_LIMIT = 10_000;
@@ -39,7 +38,6 @@ export const FOOTER_BAR_MIN_WIDTH = 4;
 export const FOOTER_BAR_MAX_WIDTH = 8;
 export const FOOTER_WIDE_TERMINAL_WIDTH = 100;
 export const FOOTER_COMPACTION_RENDER_INTERVAL_MS = 500;
-export const FOOTER_COMPACTION_DRAIN_STEP_MS = 3_000;
 /** Half-period of the compacting liveness indicator; equal to the render tick so it visibly alternates every repaint. */
 export const FOOTER_COMPACTION_BLINK_HALF_PERIOD_MS = 500;
 export const MILLISECONDS_PER_SECOND = 1_000;
@@ -47,13 +45,20 @@ export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
 export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
 export const PAPYRUS_CONTEXT_INJECTION_CHANNEL = "papyrus.context-injection.v1";
 export const PAPYRUS_CONTEXT_INJECTION_SCHEMA = "papyrus.context-injection/v1";
+/** Matches Papyrus's own constants by convention; Jittor does not depend on the Papyrus package. */
+export const PAPYRUS_TASK_FOCUS_CHANNEL = "papyrus.task-focus.v1";
+export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
+export const TASK_FOCUS_EVENT_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
+export const TASK_FOCUS_ID_MAX_LENGTH = 200;
+export const TASK_COST_QUERY_LIMIT = 10_000;
+/** A `metrics prune --before` cutoff newer than this must pass `force: true`. Guards against accidentally wiping recent/live data with a too-recent cutoff (e.g. "now"), while still allowing routine cleanup of genuinely old rows without ceremony. */
+export const PRUNE_MIN_AGE_MS = 24 * MILLISECONDS_PER_HOUR;
 export const CONTEXT_OBSERVATION_MAX_CHARACTERS = 10_000_000;
 export const CONTEXT_OBSERVATION_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
 export const CONTEXT_ASSESSMENT_QUERY_LIMIT = 10_000;
 export const CONTEXT_EVENT_DEDUP_LIMIT = 1_000;
 export const CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS = 24 * MILLISECONDS_PER_HOUR;
 export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
-export const LOOPBACK_HOST = "127.0.0.1";
 export const JITTOR_STATE_DIRECTORY = "jittor";
 export const JITTOR_EXTENSION_SETTINGS_FILENAME = "extension.json";
 export const DATABASE_FILENAME = "jittor.db";
@@ -62,7 +67,17 @@ export const HANDLE_FILENAME = "daemon.json";
 export const SYSTEMD_UNIT_NAME = "jittor.service";
 export const USAGE_CHART_HEIGHT = 8;
 export const USAGE_Y_AXIS_WIDTH = 7;
-export const USAGE_TOKEN_QUERY_LIMIT = 10_000;
+/**
+ * A single flat "most recent N rows" query lets one heavy provider/model monopolize the entire
+ * budget within the query window, silently starving every other series out of the chart no matter
+ * which time frame is selected (a real bug: a single long, heavy session can fill 10k rows within
+ * a few hours, hiding a whole other provider's usage from a day earlier even in the Monthly view).
+ * The usage/cost dashboard instead fetches per distinct scope (see distinctScopes), bounded by
+ * these two limits; the worst-case total row volume (40 * 250 = 10,000) matches the old flat cap,
+ * but is now fairly distributed across every active series instead of claimable by just one.
+ */
+export const USAGE_MAX_DISTINCT_SCOPES = 40;
+export const USAGE_PER_SCOPE_QUERY_LIMIT = 250;
 export const USAGE_RENDER_MAX_SERIES = 20;
 export const HUMAN_STATUS_MAX_SOURCES = 20;
 export const HUMAN_TEXT_FIELD_MAX_CHARACTERS = 160;
@@ -73,6 +88,8 @@ export const COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES = 20;
 /** Below this many samples the estimate stays explicit cold-start uncertainty rather than a guess. */
 export const COMPACTION_DURATION_ESTIMATE_MIN_SAMPLES = 3;
 export const MAX_USAGE_BUCKETS = 120;
+/** Defense-in-depth cap on the SQL-side usage aggregation result: (scopes x metrics x buckets) is already small by construction, but this bounds it explicitly rather than trusting that alone. */
+export const USAGE_AGGREGATE_MAX_ROWS = 25_000;
 export const MAX_DYNAMIC_ROUTES = 100;
 export const CODEX_ERROR_MESSAGE_LIMIT = 160;
 export const CODEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;
@@ -81,3 +98,13 @@ export const CODEX_RECOVERY_MAX_DELAY_MS = CODEX_RETRY_AFTER_MAX_MS;
 export const CODEX_RECOVERY_MAX_ATTEMPTS = 3;
 export const CODEX_RECOVERY_ATTEMPT_WINDOW_MS = 10 * MILLISECONDS_PER_MINUTE;
 export const CODEX_RECOVERY_JITTER_RATIO = 0.2;
+export const GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS = 160;
+/** Bounded per-poll pull size; a budget subscription realistically holds at most a few pending notifications. */
+export const GOOGLE_VERTEX_BUDGET_MAX_MESSAGES_PER_PULL = 20;
+/**
+ * Lower than Codex's header-derived 0.8: this is Google's own documented "estimated ... subject to
+ * change until your invoice is finalized" data, delivered at-least-once and possibly out of order,
+ * multiple times per day rather than on every response.
+ */
+export const GOOGLE_VERTEX_BUDGET_CONFIDENCE = 0.6;
+export const GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS = 60_000;