@danypops/jittor 0.6.0 → 0.8.0

package/src/daemon.ts

@@ -1,9 +1,11 @@
-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";
 import { OpenRouterBenchmarkIndexSource } from "./adapters/openrouter-benchmark-index-source.ts";
 import { OpenRouterBenchmarkSource } from "./adapters/openrouter-benchmark-source.ts";
+import { OpenRouterDesignArenaSource } from "./adapters/openrouter-design-arena-source.ts";
 import { openJittorDb } from "./db.ts";
 import { BenchmarkCatalog } from "./domain/benchmark.ts";
 import { EvidenceModelRanker } from "./domain/model-ranking-service.ts";
@@ -11,25 +13,26 @@ 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[] {
 	if (env["JITTOR_OPENROUTER_BENCHMARKS"] !== "1") return [];
 	const sources: BenchmarkSource[] = [new OpenRouterBenchmarkSource()];
-	if (env["OPENROUTER_API_KEY"]) sources.push(new OpenRouterBenchmarkIndexSource(env["OPENROUTER_API_KEY"]));
+	if (env["OPENROUTER_API_KEY"]) {
+		sources.push(new OpenRouterBenchmarkIndexSource(env["OPENROUTER_API_KEY"]));
+		sources.push(new OpenRouterDesignArenaSource(env["OPENROUTER_API_KEY"]));
+	}
 	return sources;
 }
 
@@ -39,9 +42,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 +82,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) }],
+	});
 }

package/src/domain/metric.ts

@@ -1,6 +1,6 @@
 import { METRIC_ATTRIBUTES_MAX_DEPTH, METRIC_ATTRIBUTES_MAX_SERIALIZED_CHARACTERS, METRIC_IDENTITY_MAX_CHARACTERS } from "../constants.ts";
 
-export const METRIC_UNITS = ["ratio", "usd", "tokens", "tokens-per-second", "requests", "milliseconds", "count"] as const;
+export const METRIC_UNITS = ["ratio", "usd", "tokens", "tokens-per-second", "requests", "milliseconds", "count", "elo"] as const;
 export type MetricUnit = typeof METRIC_UNITS[number];
 
 export interface MetricObservation {

package/src/domain/model-observation.ts

@@ -7,8 +7,19 @@ import {
 import { normalizeModelIdentity } from "./benchmark.ts";
 import type { MetricObservation, MetricUnit, StoredMetricObservation } from "./metric.ts";
 
-export const TASK_CLASSES = ["coding", "research", "planning", "general"] as const;
-export type ModelTaskClass = typeof TASK_CLASSES[number];
+/**
+ * Two independent axes, not one flat class: "coding" is a subject-matter domain (which
+ * benchmark quality evidence applies), while "research"/"planning" are activities that can
+ * happen inside any domain (which predict how much reasoning effort a task needs). The prior
+ * single ModelTaskClass conflated them -- an agentic/tool-use benchmark (a type signal) was
+ * being read as if it were a domain-quality signal. Both axes default to "general" when tool
+ * usage carries no distinguishing signal for that axis; a run can score coding on domain and
+ * research on type simultaneously (e.g. reading a file, then searching the web in one turn).
+ */
+export const TASK_DOMAINS = ["coding", "design", "general"] as const;
+export type ModelTaskDomain = typeof TASK_DOMAINS[number];
+export const TASK_TYPES = ["research", "planning", "general"] as const;
+export type ModelTaskType = typeof TASK_TYPES[number];
 export type ExplicitOutcome = "accepted" | "rejected" | "unknown";
 
 export interface ModelRunObservation {
@@ -16,7 +27,8 @@ export interface ModelRunObservation {
 	provider: string;
 	model: string;
 	thinking: string;
-	taskClass: ModelTaskClass;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
 	startedAt: number;
 	firstTokenAt: number | null;
 	completedAt: number;
@@ -36,7 +48,8 @@ export interface ModelMetricAggregate {
 	provider: string;
 	model: string;
 	thinking: string;
-	taskClass: ModelTaskClass;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
 	dimension: string;
 	unit: MetricUnit;
 	sampleSize: number;
@@ -54,7 +67,7 @@ export interface ModelAggregateOptions {
 }
 
 const ALLOWED_FIELDS = new Set<keyof ModelRunObservation>([
-	"runId", "provider", "model", "thinking", "taskClass", "startedAt", "firstTokenAt", "completedAt",
+	"runId", "provider", "model", "thinking", "domain", "type", "startedAt", "firstTokenAt", "completedAt",
 	"inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "costUsd", "providerResponses",
 	"toolCalls", "toolFailures", "stopReason", "explicitOutcome",
 ]);
@@ -80,7 +93,8 @@ export function validateModelRunObservation(value: unknown): ModelRunObservation
 	const completedAt = nonNegative(input["completedAt"], "completion time", true);
 	const firstTokenAt = input["firstTokenAt"] === null ? null : nonNegative(input["firstTokenAt"], "first-token time", true);
 	if (completedAt < startedAt || (firstTokenAt !== null && (firstTokenAt < startedAt || firstTokenAt > completedAt))) throw new Error("model run timestamps are not ordered");
-	if (!TASK_CLASSES.includes(input["taskClass"] as ModelTaskClass)) throw new Error("task class is invalid");
+	if (!TASK_DOMAINS.includes(input["domain"] as ModelTaskDomain)) throw new Error("task domain is invalid");
+	if (!TASK_TYPES.includes(input["type"] as ModelTaskType)) throw new Error("task type is invalid");
 	if (!STOP_REASONS.has(input["stopReason"] as ModelRunObservation["stopReason"])) throw new Error("stop reason is invalid");
 	if (!OUTCOMES.has(input["explicitOutcome"] as ExplicitOutcome)) throw new Error("explicit outcome is invalid");
 	const providerResponses = nonNegative(input["providerResponses"], "provider response count", true);
@@ -89,7 +103,7 @@ export function validateModelRunObservation(value: unknown): ModelRunObservation
 	if (providerResponses < 1 || toolFailures > toolCalls) throw new Error("model run counters are inconsistent");
 	return {
 		runId: text(input["runId"], "run id"), provider: identity.provider, model: identity.model,
-		thinking: text(input["thinking"], "thinking level"), taskClass: input["taskClass"] as ModelTaskClass,
+		thinking: text(input["thinking"], "thinking level"), domain: input["domain"] as ModelTaskDomain, type: input["type"] as ModelTaskType,
 		startedAt, firstTokenAt, completedAt,
 		inputTokens: nonNegative(input["inputTokens"], "input tokens"),
 		outputTokens: nonNegative(input["outputTokens"], "output tokens"),
@@ -100,18 +114,25 @@ export function validateModelRunObservation(value: unknown): ModelRunObservation
 	};
 }
 
-export function classifyTaskFromTools(toolNames: string[]): ModelTaskClass {
+export interface ModelTaskClassification {
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+}
+
+/** Domain and type are independent: a run can be domain=coding and type=research at once (e.g. reading a file, then searching the web in the same turn). */
+export function classifyTaskFromTools(toolNames: string[]): ModelTaskClassification {
 	const names = new Set(toolNames.slice(0, 100).map((name) => name.toLowerCase()));
-	if (["edit", "write", "read", "bash", "grep", "find", "ls"].some((name) => names.has(name))) return "coding";
-	if (["web_fetch", "web_search"].some((name) => names.has(name))) return "research";
-	if (["tasks", "papyrus_create", "papyrus_graph"].some((name) => names.has(name))) return "planning";
-	return "general";
+	const domain: ModelTaskDomain = ["edit", "write", "read", "bash", "grep", "find", "ls"].some((name) => names.has(name)) ? "coding" : "general";
+	const type: ModelTaskType = ["web_fetch", "web_search"].some((name) => names.has(name))
+		? "research"
+		: ["tasks", "papyrus_create", "papyrus_graph"].some((name) => names.has(name)) ? "planning" : "general";
+	return { domain, type };
 }
 
 export function modelRunMetrics(value: ModelRunObservation): MetricObservation[] {
 	const run = validateModelRunObservation(value);
 	const scope = `${run.provider}/${run.model}`;
-	const attributes = { provider: run.provider, model: run.model, thinking: run.thinking, taskClass: run.taskClass, runId: run.runId };
+	const attributes = { provider: run.provider, model: run.model, thinking: run.thinking, domain: run.domain, type: run.type, runId: run.runId };
 	const metric = (name: string, amount: number, unit: MetricUnit): MetricObservation => ({ source: "local-model", scope, metric: name, value: amount, unit, observedAt: run.completedAt, attributes });
 	const wallMs = run.completedAt - run.startedAt;
 	const totalInput = run.inputTokens + run.cacheReadTokens;
@@ -155,16 +176,17 @@ export function aggregateModelMetrics(input: StoredMetricObservation[], options:
 		const provider = row.attributes["provider"];
 		const model = row.attributes["model"];
 		const thinking = row.attributes["thinking"];
-		const taskClass = row.attributes["taskClass"];
-		if (typeof provider !== "string" || typeof model !== "string" || typeof thinking !== "string" || !TASK_CLASSES.includes(taskClass as ModelTaskClass)) continue;
-		const key = JSON.stringify([provider, model, thinking, taskClass, row.metric, row.unit]);
+		const domain = row.attributes["domain"];
+		const type = row.attributes["type"];
+		if (typeof provider !== "string" || typeof model !== "string" || typeof thinking !== "string" || !TASK_DOMAINS.includes(domain as ModelTaskDomain) || !TASK_TYPES.includes(type as ModelTaskType)) continue;
+		const key = JSON.stringify([provider, model, thinking, domain, type, row.metric, row.unit]);
 		if (!groups.has(key) && groups.size >= MODEL_AGGREGATE_MAX_GROUPS) continue;
 		const rows = groups.get(key) ?? [];
 		rows.push(row);
 		groups.set(key, rows);
 	}
 	return [...groups.entries()].map(([key, rows]) => {
-		const [provider, model, thinking, taskClass, dimension, unit] = JSON.parse(key) as [string, string, string, ModelTaskClass, string, MetricUnit];
+		const [provider, model, thinking, domain, type, dimension, unit] = JSON.parse(key) as [string, string, string, ModelTaskDomain, ModelTaskType, string, MetricUnit];
 		const values = rows.map((row) => row.value as number).sort((left, right) => left - right);
 		const center = median(values);
 		const deviations = values.map((value) => Math.abs(value - center)).sort((left, right) => left - right);
@@ -172,10 +194,10 @@ export function aggregateModelMetrics(input: StoredMetricObservation[], options:
 		const age = Math.max(0, now - latestAt);
 		const recency = Math.max(0, 1 - (age / freshForMs));
 		return {
-			provider, model, thinking, taskClass, dimension, unit,
+			provider, model, thinking, domain, type, dimension, unit,
 			sampleSize: values.length, median: center, p90: percentile(values, 0.9), medianAbsoluteDeviation: median(deviations), latestAt,
 			freshness: age <= freshForMs ? "fresh" as const : "stale" as const,
 			confidence: Math.min(1, Math.sqrt(values.length / 20)) * recency,
 		};
-	}).sort((left, right) => left.provider.localeCompare(right.provider) || left.model.localeCompare(right.model) || left.dimension.localeCompare(right.dimension));
+	}).sort((left, right) => left.provider.localeCompare(right.provider) || left.model.localeCompare(right.model) || left.domain.localeCompare(right.domain) || left.type.localeCompare(right.type) || left.dimension.localeCompare(right.dimension));
 }

package/src/domain/model-ranking-service.ts

@@ -3,12 +3,13 @@ import type { BenchmarkStore } from "../ports/benchmark-store.ts";
 import type { MetricStore } from "../ports/metric-store.ts";
 import { aggregateModelMetrics } from "./model-observation.ts";
 import { rankModelCandidates, type ModelCandidate, type ModelRankingResult, type ScopeAuthority, type UtilityWeights } from "./model-ranking.ts";
-import type { ModelTaskClass } from "./model-observation.ts";
+import type { ModelTaskDomain, ModelTaskType } from "./model-observation.ts";
 
 export interface ModelRecommendationInput {
 	candidates: ModelCandidate[];
 	scopeAuthority: ScopeAuthority;
-	taskClass: ModelTaskClass;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
 	budgetPressure: number;
 	weights: UtilityWeights;
 	sourceIds: string[];

package/src/domain/model-ranking.ts

@@ -1,6 +1,6 @@
 import { BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT, MAX_DYNAMIC_ROUTES, MODEL_AGGREGATE_MAX_ROWS } from "../constants.ts";
 import { normalizeModelIdentity, type BenchmarkObservation } from "./benchmark.ts";
-import { TASK_CLASSES, type ModelMetricAggregate, type ModelTaskClass } from "./model-observation.ts";
+import { TASK_DOMAINS, TASK_TYPES, type ModelMetricAggregate, type ModelTaskDomain, type ModelTaskType } from "./model-observation.ts";
 
 export type ScopeAuthority = "exact-session" | "available-models";
 export type UtilityComponentName = "quality" | "cost" | "latency" | "context" | "reliability";
@@ -22,7 +22,8 @@ export interface UtilityWeights {
 export interface ModelRankingInput {
 	candidates: ModelCandidate[];
 	scopeAuthority: ScopeAuthority;
-	taskClass: ModelTaskClass;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
 	budgetPressure: number;
 	weights: UtilityWeights;
 	externalEvidence: BenchmarkObservation[];
@@ -60,7 +61,8 @@ export interface RankedModel {
 export interface ModelRankingResult {
 	scopeAuthority: ScopeAuthority;
 	scopeWarning: string | null;
-	taskClass: ModelTaskClass;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
 	completeness: "complete" | "partial" | "insufficient-evidence";
 	ranked: RankedModel[];
 	automaticSelection: ModelCandidate | null;
@@ -101,22 +103,37 @@ function externalValues(candidate: ModelCandidate, evidence: BenchmarkObservatio
 	};
 }
 
-function localValues(candidate: ModelCandidate, taskClass: ModelTaskClass, evidence: ModelMetricAggregate[], dimension: string): ModelMetricAggregate[] {
+function localValues(candidate: ModelCandidate, domain: ModelTaskDomain, type: ModelTaskType, evidence: ModelMetricAggregate[], dimension: string): ModelMetricAggregate[] {
 	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
-	return evidence.filter((item) => item.provider === identity.provider && item.model === identity.model && item.thinking === candidate.thinking && item.taskClass === taskClass && item.dimension === dimension);
+	return evidence.filter((item) => item.provider === identity.provider && item.model === identity.model && item.thinking === candidate.thinking && item.domain === domain && item.type === type && item.dimension === dimension);
+}
+
+/**
+ * quality-{domain} is a subject-matter signal (e.g. quality-coding from a coding benchmark);
+ * quality-type-{type} is an activity signal (e.g. quality-type-planning from an agentic/tool-use
+ * benchmark). Both are optional and additive on top of the universal quality-general fallback --
+ * a candidate with no domain- or type-specific evidence still gets ranked on general quality
+ * rather than being treated as having zero evidence.
+ */
+function qualityDimensions(domain: ModelTaskDomain, type: ModelTaskType): string[] {
+	const dimensions: string[] = [];
+	if (domain !== "general") dimensions.push(`quality-${domain}`);
+	if (type !== "general") dimensions.push(`quality-type-${type}`);
+	dimensions.push("quality-general");
+	return dimensions;
 }
 
 function rawComponents(candidate: ModelCandidate, input: ModelRankingInput): { components: Record<UtilityComponentName, RawComponent>; provenance: RankingProvenance[] } {
-	const quality = externalValues(candidate, input.externalEvidence, [`quality-${input.taskClass}`, "quality-general"], input.now);
+	const quality = externalValues(candidate, input.externalEvidence, qualityDimensions(input.domain, input.type), input.now);
 	const priceInput = externalValues(candidate, input.externalEvidence, ["price-input"], input.now);
 	const priceOutput = externalValues(candidate, input.externalEvidence, ["price-output"], input.now);
 	const measuredLatency = externalValues(candidate, input.externalEvidence, ["latency"], input.now);
 	const rankedLatency = externalValues(candidate, input.externalEvidence, ["latency-rank", "throughput-rank"], input.now);
 	const latency = measuredLatency.values.length > 0 ? measuredLatency : rankedLatency;
 	const context = externalValues(candidate, input.externalEvidence, ["context-window"], input.now);
-	const localLatency = localValues(candidate, input.taskClass, input.localEvidence, "wall-latency");
-	const failures = localValues(candidate, input.taskClass, input.localEvidence, "failure");
-	const outcomes = localValues(candidate, input.taskClass, input.localEvidence, "outcome-accepted");
+	const localLatency = localValues(candidate, input.domain, input.type, input.localEvidence, "wall-latency");
+	const failures = localValues(candidate, input.domain, input.type, input.localEvidence, "failure");
+	const outcomes = localValues(candidate, input.domain, input.type, input.localEvidence, "outcome-accepted");
 	const qualityValues = quality.values;
 	const prices = [...priceInput.values, ...priceOutput.values];
 	const latencyValues = localLatency.length > 0 ? localLatency.map((item) => item.median) : latency.values;
@@ -154,7 +171,8 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 	if (!Array.isArray(value.externalEvidence) || value.externalEvidence.length > BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT * 4) throw new Error("external evidence exceeds the supported bound");
 	if (!Array.isArray(value.localEvidence) || value.localEvidence.length > MODEL_AGGREGATE_MAX_ROWS) throw new Error("local evidence exceeds the supported bound");
 	if (value.scopeAuthority !== "exact-session" && value.scopeAuthority !== "available-models") throw new Error("scope authority is invalid");
-	if (!TASK_CLASSES.includes(value.taskClass)) throw new Error("task class is invalid");
+	if (!TASK_DOMAINS.includes(value.domain)) throw new Error("task domain is invalid");
+	if (!TASK_TYPES.includes(value.type)) throw new Error("task type is invalid");
 	if (!Number.isSafeInteger(value.now) || value.now <= 0) throw new Error("ranking time is invalid");
 	const budgetPressure = finiteBound(value.budgetPressure, "budget pressure", 0, 2);
 	const weights = Object.fromEntries(COMPONENTS.map((name) => [name, finiteBound(value.weights[name], `${name} weight`, 0, 10)])) as unknown as UtilityWeights;
@@ -195,7 +213,7 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 			confidence,
 			components,
 			provenance,
-			trace: [`task class ${value.taskClass}`, `budget pressure ${budgetPressure.toFixed(3)} makes cost weight ${effectiveWeights.cost.toFixed(3)}`, `${known.length}/${components.length} utility components have evidence`, `scope authority ${value.scopeAuthority}`],
+			trace: [`domain ${value.domain}, type ${value.type}`, `budget pressure ${budgetPressure.toFixed(3)} makes cost weight ${effectiveWeights.cost.toFixed(3)}`, `${known.length}/${components.length} utility components have evidence`, `scope authority ${value.scopeAuthority}`],
 		};
 	}).sort((left, right) => (right.utility ?? -1) - (left.utility ?? -1) || right.confidence - left.confidence || left.identity.localeCompare(right.identity));
 	const knownComponents = ranked.reduce((sum, item) => sum + item.components.filter((component) => component.score !== null).length, 0);
@@ -205,7 +223,8 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 	return {
 		scopeAuthority: value.scopeAuthority,
 		scopeWarning: exact ? null : "Pi available models are not the exact session scope; automatic selection is disabled",
-		taskClass: value.taskClass,
+		domain: value.domain,
+		type: value.type,
 		completeness,
 		ranked,
 		automaticSelection: exact && ranked[0]?.utility !== null ? ranked[0]!.candidate : null,

package/src/domain/task-cost.ts

@@ -0,0 +1,70 @@
+import type { StoredMetricObservation } from "./metric.ts";
+
+export interface TaskCostEntry {
+	taskId: string;
+	costUsd: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+}
+
+export interface TaskCostSummary {
+	since: number;
+	until: number;
+	entries: TaskCostEntry[];
+	unattributedCostUsd: number;
+	truncated: boolean;
+}
+
+export interface TaskCostSummaryOptions {
+	since: number;
+	until: number;
+	truncated?: boolean;
+}
+
+const TOKEN_METRICS = new Set(["input-tokens", "output-tokens", "cache-read-tokens", "cache-write-tokens"]);
+
+function entryFor(byTask: Map<string, TaskCostEntry>, taskId: string): TaskCostEntry {
+	const existing = byTask.get(taskId);
+	if (existing) return existing;
+	const created: TaskCostEntry = { taskId, costUsd: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+	byTask.set(taskId, created);
+	return created;
+}
+
+/**
+ * Groups already-recorded "pi" source cost/token metrics by the Papyrus task focused when each was
+ * recorded (see the papyrus.task-focus.v1 real-time tagging in the extension), rather than by
+ * provider/model identity. Rows recorded with nothing focused have no attributes.taskId and are
+ * reported separately as unattributedCostUsd -- they are real spend, just not attributable to any
+ * task, and must never be silently dropped or folded into an invented "unknown" task bucket.
+ *
+ * This queries a single bounded time window without per-task fairness partitioning (unlike
+ * buildUsageGraph/buildCostGraph's per-scope fetch): a task's own working period is typically a far
+ * narrower, more targeted window than "the whole usage dashboard, any period", so one task's volume
+ * crowding another out of the same query is a much smaller risk here. If this does become a problem
+ * in practice, the same per-distinct-value fetch strategy applies, keyed by attributes.taskId.
+ */
+export function buildTaskCostSummary(rows: StoredMetricObservation[], options: TaskCostSummaryOptions): TaskCostSummary {
+	const byTask = new Map<string, TaskCostEntry>();
+	let unattributedCostUsd = 0;
+	for (const row of rows) {
+		if (row.source !== "pi" || typeof row.value !== "number" || !Number.isFinite(row.value) || row.value < 0) continue;
+		if (row.observedAt < options.since || row.observedAt > options.until) continue;
+		const taskId = typeof row.attributes["taskId"] === "string" ? row.attributes["taskId"] : undefined;
+		if (row.metric === "cost" && row.unit === "usd") {
+			if (taskId === undefined) { unattributedCostUsd += row.value; continue; }
+			entryFor(byTask, taskId).costUsd += row.value;
+			continue;
+		}
+		if (taskId === undefined || row.unit !== "tokens" || !TOKEN_METRICS.has(row.metric)) continue;
+		const entry = entryFor(byTask, taskId);
+		if (row.metric === "input-tokens") entry.inputTokens += row.value;
+		else if (row.metric === "output-tokens") entry.outputTokens += row.value;
+		else if (row.metric === "cache-read-tokens") entry.cacheReadTokens += row.value;
+		else entry.cacheWriteTokens += row.value;
+	}
+	const entries = [...byTask.values()].sort((left, right) => right.costUsd - left.costUsd || left.taskId.localeCompare(right.taskId));
+	return { since: options.since, until: options.until, entries, unattributedCostUsd, truncated: options.truncated === true };
+}

package/src/domain/task-focus.ts

@@ -0,0 +1,65 @@
+import { PAPYRUS_TASK_FOCUS_SCHEMA, TASK_FOCUS_EVENT_MAX_AGE_MS, TASK_FOCUS_ID_MAX_LENGTH } from "../constants.ts";
+
+export type TaskFocusStatus = "focused" | "paused" | "unpaused" | "cleared";
+
+export interface TaskFocusEvent {
+	schema: typeof PAPYRUS_TASK_FOCUS_SCHEMA;
+	taskId: string | null;
+	sessionId?: string;
+	status: TaskFocusStatus;
+	observedAt: number;
+}
+
+const TOP_LEVEL_FIELDS = new Set(["schema", "taskId", "sessionId", "status", "observedAt"]);
+const STATUSES = new Set<string>(["focused", "paused", "unpaused", "cleared"]);
+
+function record(value: unknown): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("task-focus event must be an object");
+	const result = value as Record<string, unknown>;
+	for (const key of Object.keys(result)) if (!TOP_LEVEL_FIELDS.has(key)) throw new Error(`task-focus event contains unexpected field: ${key}`);
+	return result;
+}
+
+function boundedId(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > TASK_FOCUS_ID_MAX_LENGTH) throw new Error(`${name} must be a non-empty bounded string`);
+	return value;
+}
+
+/**
+ * Validates the papyrus.task-focus.v1 shared-bus payload independently of whatever Papyrus itself
+ * guarantees -- this is a cross-extension trust boundary, so Jittor never trusts an unvalidated
+ * shape. Fails closed (throws) on schema drift, an unrecognized status, or a stale observation,
+ * mirroring validatePapyrusContextInjection's pattern for the same reason: a malformed or
+ * out-of-order cross-extension event must never silently corrupt Jittor's own state.
+ */
+export function validateTaskFocusEvent(value: unknown, now = Date.now()): TaskFocusEvent {
+	const input = record(value);
+	if (input["schema"] !== PAPYRUS_TASK_FOCUS_SCHEMA) throw new Error("task-focus event schema is not supported");
+	const status = input["status"];
+	if (typeof status !== "string" || !STATUSES.has(status)) throw new Error("task-focus event status is not supported");
+	const observedAt = input["observedAt"];
+	if (typeof observedAt !== "number" || !Number.isSafeInteger(observedAt) || observedAt < 0) throw new Error("task-focus event observedAt must be a non-negative integer");
+	if (Math.abs(now - observedAt) > TASK_FOCUS_EVENT_MAX_AGE_MS) throw new Error("task-focus event is stale");
+	const rawTaskId = input["taskId"];
+	const taskId = rawTaskId === null ? null : boundedId(rawTaskId, "taskId");
+	if (taskId === null && status !== "cleared") throw new Error(`task-focus event of status "${status}" requires a taskId`);
+	const rawSessionId = input["sessionId"];
+	const sessionId = rawSessionId === undefined ? undefined : boundedId(rawSessionId, "sessionId");
+	return {
+		schema: PAPYRUS_TASK_FOCUS_SCHEMA,
+		taskId,
+		status: status as TaskFocusStatus,
+		observedAt,
+		...(sessionId === undefined ? {} : { sessionId }),
+	};
+}
+
+/**
+ * Applies a validated event to the currently tracked focused task id. "paused" and "cleared" both
+ * mean "no task is actively being worked on right now" for cost-attribution purposes, even though
+ * Papyrus itself keeps a paused task's focus state around for later resumption -- Jittor only
+ * cares about whether to keep tagging new metrics, not about Papyrus's own pause bookkeeping.
+ */
+export function applyTaskFocusEvent(event: TaskFocusEvent): string | null {
+	return event.status === "focused" || event.status === "unpaused" ? event.taskId : null;
+}