@danypops/jittor 0.6.0 → 0.7.0

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;

package/src/daemon.ts

@@ -1,4 +1,5 @@
-import { LOOPBACK_HOST, MAINTENANCE_INTERVAL_MS, TELEMETRY_POLL_INTERVAL_MS } from "./constants.ts";
+import { startDaemon as startDaemonKit, type RunningDaemon } from "@danypops/daemon-kit/daemon";
+import { MAINTENANCE_INTERVAL_MS, TELEMETRY_POLL_INTERVAL_MS } from "./constants.ts";
 import { DEFAULT_POLICY, UNCONFIGURED_ROUTE } from "./config.ts";
 import { SQLiteMetricStore } from "./adapters/sqlite-metric-store.ts";
 import { MetricBenchmarkStore } from "./adapters/metric-benchmark-store.ts";
@@ -11,19 +12,17 @@ import { createApp, JittorService } from "./service.ts";
 import { JittorRouter } from "./router.ts";
 import type { BenchmarkSource } from "./ports/benchmark-source.ts";
 import type { TelemetrySource } from "./ports/telemetry-source.ts";
-import { CodexTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
-import {
-	ensureAuthToken,
-	removeDaemonHandle,
-	resolveJittorPaths,
-	writeDaemonHandle,
-	type JittorPaths,
-} from "./state.ts";
+import { CodexTelemetrySource, GoogleVertexBudgetTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
+import { createGoogleAdcTokenProvider } from "./providers/google-adc-auth.ts";
+import { GOOGLE_PUBSUB_READONLY_SCOPE } from "./providers/google-vertex-budget.ts";
+import type { GoogleVertexMetricSource } from "./providers/google-vertex-contracts.ts";
+import { ensureAuthToken, resolveJittorPaths, type JittorPaths } from "./state.ts";
+import { logEvent, logger } from "./log.ts";
 
-export interface RunningDaemon {
-	host: typeof LOOPBACK_HOST;
-	port: number;
-	stop(): Promise<void>;
+export type { RunningDaemon } from "@danypops/daemon-kit/daemon";
+
+export function reportMaintenanceFailure(event: string, error: unknown): void {
+	logEvent("error", event, { message: error instanceof Error ? error.message : String(error) });
 }
 
 export function benchmarkSourcesFromEnvironment(env: Record<string, string | undefined> = process.env): BenchmarkSource[] {
@@ -39,9 +38,27 @@ export function telemetrySourcesFromEnvironment(env: Record<string, string | und
 	if (codexAuthFile) sources.push(new CodexTelemetrySource(codexAuthFile));
 	const openRouterKey = env["OPENROUTER_API_KEY"];
 	if (openRouterKey) sources.push(new OpenRouterTelemetrySource(openRouterKey));
+	// Opt-in only: the Pub/Sub subscription is one-time GCP console/CLI setup outside Jittor (see
+	// docs/PROVIDER_RESEARCH.md), so its absence must never attempt ADC discovery or a network call.
+	const vertexBudgetSubscription = env["JITTOR_GOOGLE_VERTEX_BUDGET_SUBSCRIPTION"];
+	if (vertexBudgetSubscription) {
+		const source = (env["JITTOR_GOOGLE_VERTEX_BUDGET_SOURCE"] ?? "google-vertex") as GoogleVertexMetricSource;
+		const tokenProvider = createGoogleAdcTokenProvider([GOOGLE_PUBSUB_READONLY_SCOPE]);
+		sources.push(new GoogleVertexBudgetTelemetrySource(vertexBudgetSubscription, tokenProvider, Date.now, fetch, source));
+	}
 	return sources;
 }
 
+/**
+ * Composition root, now built on `@danypops/daemon-kit/daemon`'s `startDaemon` for binding,
+ * atomic handle write, maintenance-timer driving, and clean shutdown -- the skeleton that used to
+ * be hand-rolled here (and, byte-identically, in web-spider-daemon's and papyrus's daemon.ts; see
+ * daemon-kit's README). Each maintenance task still catches and classifies its own failure via
+ * `reportMaintenanceFailure` (preserving Jittor's specific `checkpoint_failed`/
+ * `benchmark_refresh_failed`/`telemetry_poll_failed` event taxonomy) rather than relying on
+ * daemon-kit's own generic "maintenance task failed: <name>" catch, which exists as a safety net
+ * for tasks that don't self-classify, not to replace a consumer's own richer classification.
+ */
 export function startDaemon(
 	paths: JittorPaths = resolveJittorPaths(),
 	env: Record<string, string | undefined> = process.env,
@@ -61,40 +78,24 @@ export function startDaemon(
 		currentRoute: UNCONFIGURED_ROUTE,
 	});
 	const service = new JittorService(metrics, router, benchmarks, modelRanker);
-	const app = createApp({ service, token });
-	const server = Bun.serve({
-		hostname: LOOPBACK_HOST,
-		port: 0,
-		fetch: (request) => app.fetch(request),
+
+	const daemon = startDaemonKit({
+		daemonLabel: "Jittor",
+		handlePath: paths.handle,
+		logger,
+		buildApp: () => createApp({ service, token }),
+		maintenanceTasks: [
+			{ name: "checkpoint", intervalMs: MAINTENANCE_INTERVAL_MS, run: async () => { await service.execute("service.checkpoint", {}).catch((error) => reportMaintenanceFailure("checkpoint_failed", error)); } },
+			{ name: "benchmark-refresh", intervalMs: MAINTENANCE_INTERVAL_MS, run: async () => { await benchmarks.refresh().catch((error) => reportMaintenanceFailure("benchmark_refresh_failed", error)); } },
+			{ name: "telemetry-poll", intervalMs: TELEMETRY_POLL_INTERVAL_MS, run: async () => { await router.poll().catch((error) => reportMaintenanceFailure("telemetry_poll_failed", error)); } },
+		],
+		onShutdown: () => { service.close(); },
 	});
-	const port = server.port;
-	if (port === undefined) {
-		server.stop(true);
-		service.close();
-		throw new Error("Jittor daemon failed to bind a loopback port");
-	}
-	writeDaemonHandle(paths, { host: LOOPBACK_HOST, port, pid: process.pid });
-	const maintenance = setInterval(() => {
-		void service.execute("service.checkpoint", {});
-		void benchmarks.refresh();
-	}, MAINTENANCE_INTERVAL_MS);
-	const poll = setInterval(() => { void router.poll(); }, TELEMETRY_POLL_INTERVAL_MS);
-	if (sources.length > 0) void router.poll();
-	if (benchmarkSources.length > 0) void benchmarks.refresh();
-	let stopped = false;
-	return {
-		host: LOOPBACK_HOST,
-		port,
-		async stop(): Promise<void> {
-			if (stopped) return;
-			stopped = true;
-			clearInterval(maintenance);
-			clearInterval(poll);
-			await server.stop(true);
-			service.close();
-			removeDaemonHandle(paths);
-		},
-	};
+
+	if (sources.length > 0) router.poll().catch((error) => reportMaintenanceFailure("telemetry_poll_failed", error));
+	if (benchmarkSources.length > 0) benchmarks.refresh().catch((error) => reportMaintenanceFailure("benchmark_refresh_failed", error));
+
+	return daemon;
 }
 
 export function serveMain(): void {

package/src/db.ts

@@ -1,7 +1,6 @@
-import { Database } from "bun:sqlite";
-import { dirname } from "node:path";
-import { mkdirSync } from "node:fs";
-import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
+import type { Database } from "bun:sqlite";
+import { openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import { SQLITE_BUSY_TIMEOUT_MS } from "./constants.ts";
 
 const INITIAL_SCHEMA = `
 CREATE TABLE metric_observations (
@@ -20,31 +19,15 @@ CREATE INDEX metric_observations_time_idx
 	ON metric_observations(observed_at);
 `;
 
-function migrate(db: Database): void {
-	const row = db.query("PRAGMA user_version").get() as { user_version: number };
-	if (row.user_version > SQLITE_SCHEMA_VERSION) {
-		throw new Error(`database schema ${row.user_version} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
-	}
-	if (row.user_version < 1) {
-		const migration = db.transaction(() => {
-			db.exec(INITIAL_SCHEMA);
-			db.exec("PRAGMA user_version = 1");
-		});
-		migration.immediate();
-	}
-	const migrated = db.query("PRAGMA user_version").get() as { user_version: number };
-	if (migrated.user_version !== SQLITE_SCHEMA_VERSION) {
-		throw new Error(`missing migration from schema ${migrated.user_version} to ${SQLITE_SCHEMA_VERSION}`);
-	}
-}
-
+/**
+ * Delegates bootstrap (pragmas, migration engine) to `@danypops/daemon-kit/storage`, which
+ * generalizes the byte-identical pragma/PRAGMA-user_version skeleton jittor's own db.ts used to
+ * hand-roll (see daemon-kit's README). Jittor's only remaining responsibility is its own schema.
+ */
 export function openJittorDb(path: string): Database {
-	if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
-	const db = new Database(path, { create: true, strict: true });
-	db.exec("PRAGMA foreign_keys = ON");
-	db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
-	migrate(db);
-	db.exec("PRAGMA optimize=0x10002");
-	return db;
+	return openSqliteWithPragmas(path, {
+		databaseOptions: { create: true, strict: true },
+		busyTimeoutMs: SQLITE_BUSY_TIMEOUT_MS,
+		migrations: [{ version: 1, up: (db) => db.exec(INITIAL_SCHEMA) }],
+	});
 }