@danypops/jittor 0.5.1 → 0.7.0

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;
+}

package/src/domain/usage.ts

@@ -1,11 +1,11 @@
 import { MAX_USAGE_BUCKETS, MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR } from "../constants.ts";
-import type { StoredMetricObservation } from "./metric.ts";
 
 export const USAGE_PERIODS = [
 	{ id: "hourly", label: "Hourly", windowMs: MILLISECONDS_PER_HOUR, bucketCount: 12 },
 	{ id: "daily", label: "Daily", windowMs: MILLISECONDS_PER_DAY, bucketCount: 24 },
 	{ id: "weekly", label: "Weekly", windowMs: 7 * MILLISECONDS_PER_DAY, bucketCount: 28 },
 	{ id: "monthly", label: "Monthly", windowMs: 30 * MILLISECONDS_PER_DAY, bucketCount: 30 },
+	{ id: "quarterly", label: "Quarterly", windowMs: 90 * MILLISECONDS_PER_DAY, bucketCount: 90 },
 ] as const;
 export type UsagePeriod = typeof USAGE_PERIODS[number]["id"];
 
@@ -13,6 +13,52 @@ export function usagePeriod(period: UsagePeriod): typeof USAGE_PERIODS[number] {
 	return USAGE_PERIODS.find((candidate) => candidate.id === period)!;
 }
 
+export function usagePeriodStart(period: UsagePeriod, now: number): number {
+	return Math.max(0, now - usagePeriod(period).windowMs);
+}
+
+/**
+ * The bucket boundaries a chart period actually renders. Shared, byte-identical, by both sides of
+ * the wire: the daemon computes the SAME window from the same (period, now[, bucketCount]) before
+ * running its SQL-side GROUP BY, so a pre-aggregated bucket sum always lands in exactly the bucket
+ * the chart expects -- there is no second, independent bucketing pass left to disagree with it.
+ */
+export interface UsageBucketWindow {
+	start: number;
+	end: number;
+	bucketCount: number;
+	bucketSizeMs: number;
+}
+
+export function resolveUsageWindow(period: UsagePeriod, now: number, bucketCount?: number): UsageBucketWindow {
+	const end = now;
+	const start = usagePeriodStart(period, end);
+	const requested = bucketCount ?? usagePeriod(period).bucketCount;
+	const count = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requested)));
+	const bucketSizeMs = Math.max(1, (end - start) / count);
+	return { start, end, bucketCount: count, bucketSizeMs };
+}
+
+/** Mirrors the SQL-side `MIN(CAST((observed_at - start) / bucketSizeMs AS INTEGER), bucketCount - 1)` grouping exactly. */
+export function usageBucketIndex(observedAt: number, window: UsageBucketWindow): number {
+	return Math.min(window.bucketCount - 1, Math.max(0, Math.floor((observedAt - window.start) / window.bucketSizeMs)));
+}
+
+/**
+ * One already-summed (scope, metric, bucket) cell -- what the daemon's SQL-side GROUP BY returns,
+ * replacing a bounded-but-still-truncatable fetch of raw per-observation rows. Result size scales
+ * with (distinct scopes x distinct metrics x bucket count), never with raw event count, so a
+ * heavy scope's full history is represented exactly regardless of how many observations it made
+ * (a real incident: a scope with 49,270 rows in a week had its "weekly" chart built from the 250
+ * most recent rows alone -- 3.3 minutes of real activity mislabeled as a full week).
+ */
+export interface UsageAggregateRow {
+	scope: string;
+	metric: string;
+	bucketIndex: number;
+	sum: number;
+}
+
 export interface UsageSeries {
 	key: string;
 	provider: string;
@@ -47,8 +93,6 @@ export interface UsageGraph {
 
 export interface UsageGraphOptions {
 	period: UsagePeriod;
-	now: number;
-	bucketCount?: number;
 	truncated?: boolean;
 }
 
@@ -59,54 +103,52 @@ const BREAKDOWN_KEYS = {
 	"cache-write-tokens": "cacheWrite",
 } as const satisfies Record<string, keyof UsageBreakdown>;
 
-export function usagePeriodStart(period: UsagePeriod, now: number): number {
-	return Math.max(0, now - usagePeriod(period).windowMs);
-}
-
-function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
-	const separator = row.scope.indexOf(":");
-	const fallbackProvider = separator >= 0 ? row.scope.slice(0, separator) : row.scope;
-	const fallbackModel = separator >= 0 ? row.scope.slice(separator + 1) : "unknown";
-	const provider = typeof row.attributes["provider"] === "string" ? row.attributes["provider"] : fallbackProvider;
-	const model = typeof row.attributes["model"] === "string" ? row.attributes["model"] : fallbackModel;
+/**
+ * Derives provider/model from `scope` alone (`"${provider}:${model}"`, see assistantUsageMetrics),
+ * rather than needing a row's `attributes.provider`/`attributes.model` -- source "pi" always
+ * constructs `scope` from those exact same two values, so the two are equivalent for this source,
+ * and an aggregated bucket sum has no per-row attributes left to read anyway.
+ */
+export function identity(scope: string): { key: string; provider: string; model: string } {
+	const separator = scope.indexOf(":");
+	const provider = separator >= 0 ? scope.slice(0, separator) : scope;
+	const model = separator >= 0 ? scope.slice(separator + 1) : "unknown";
 	return { key: `${provider}/${model}`, provider, model };
 }
 
-export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): UsageGraph {
-	const end = options.now;
-	const start = usagePeriodStart(options.period, end);
-	const requestedBuckets = options.bucketCount ?? usagePeriod(options.period).bucketCount;
-	const bucketCount = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requestedBuckets)));
-	const bucketSize = Math.max(1, (end - start) / bucketCount);
-	const buckets: UsageBucket[] = Array.from({ length: bucketCount }, (_, index) => ({
-		start: start + index * bucketSize,
-		end: index === bucketCount - 1 ? end : start + (index + 1) * bucketSize,
+function emptyBuckets(window: UsageBucketWindow): { start: number; end: number; total: number; series: Record<string, number> }[] {
+	return Array.from({ length: window.bucketCount }, (_, index) => ({
+		start: window.start + index * window.bucketSizeMs,
+		end: index === window.bucketCount - 1 ? window.end : window.start + (index + 1) * window.bucketSizeMs,
 		total: 0,
 		series: {},
 	}));
+}
+
+export function buildUsageGraph(rows: UsageAggregateRow[], window: UsageBucketWindow, options: UsageGraphOptions): UsageGraph {
+	const buckets: UsageBucket[] = emptyBuckets(window);
 	const breakdown: UsageBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 	const identities = new Map<string, UsageSeries>();
 
 	for (const row of rows) {
 		const breakdownKey = BREAKDOWN_KEYS[row.metric as keyof typeof BREAKDOWN_KEYS];
-		if (row.source !== "pi" || row.unit !== "tokens" || !breakdownKey || typeof row.value !== "number" || row.value < 0) continue;
-		if (row.observedAt < start || row.observedAt > end) continue;
-		const bucketIndex = Math.min(bucketCount - 1, Math.floor((row.observedAt - start) / bucketSize));
-		const bucket = buckets[bucketIndex]!;
-		const series = identity(row);
-		bucket.total += row.value;
-		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
-		breakdown[breakdownKey] += row.value;
+		if (!breakdownKey || !Number.isFinite(row.sum) || row.sum < 0) continue;
+		if (!Number.isInteger(row.bucketIndex) || row.bucketIndex < 0 || row.bucketIndex >= buckets.length) continue;
+		const bucket = buckets[row.bucketIndex]!;
+		const series = identity(row.scope);
+		bucket.total += row.sum;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.sum;
+		breakdown[breakdownKey] += row.sum;
 		const current = identities.get(series.key) ?? { ...series, total: 0 };
-		current.total += row.value;
+		current.total += row.sum;
 		identities.set(series.key, current);
 	}
 
 	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
 	return {
 		period: options.period,
-		start,
-		end,
+		start: window.start,
+		end: window.end,
 		buckets,
 		series,
 		totalTokens: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
@@ -114,3 +156,62 @@ export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageG
 		truncated: options.truncated === true,
 	};
 }
+
+export interface CostSeries {
+	key: string;
+	provider: string;
+	model: string;
+	total: number;
+}
+
+export interface CostBucket {
+	start: number;
+	end: number;
+	total: number;
+	series: Record<string, number>;
+}
+
+export interface CostGraph {
+	period: UsagePeriod;
+	start: number;
+	end: number;
+	buckets: CostBucket[];
+	series: CostSeries[];
+	totalUsd: number;
+	truncated: boolean;
+}
+
+/**
+ * Mirrors buildUsageGraph but for the "cost" (unit "usd") metric already recorded content-free on
+ * every finalized Pi assistant message (see assistantUsageMetrics), so this needs no new
+ * instrumentation. Aggregated spend by model/time is one of the metrics LLM usage dashboards
+ * surface from day one (alongside raw token counts), since token counts alone do not reflect that
+ * output tokens and premium models cost disproportionately more per token.
+ */
+export function buildCostGraph(rows: UsageAggregateRow[], window: UsageBucketWindow, options: UsageGraphOptions): CostGraph {
+	const buckets: CostBucket[] = emptyBuckets(window);
+	const identities = new Map<string, CostSeries>();
+
+	for (const row of rows) {
+		if (row.metric !== "cost" || !Number.isFinite(row.sum) || row.sum < 0) continue;
+		if (!Number.isInteger(row.bucketIndex) || row.bucketIndex < 0 || row.bucketIndex >= buckets.length) continue;
+		const bucket = buckets[row.bucketIndex]!;
+		const series = identity(row.scope);
+		bucket.total += row.sum;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.sum;
+		const current = identities.get(series.key) ?? { ...series, total: 0 };
+		current.total += row.sum;
+		identities.set(series.key, current);
+	}
+
+	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
+	return {
+		period: options.period,
+		start: window.start,
+		end: window.end,
+		buckets,
+		series,
+		totalUsd: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
+		truncated: options.truncated === true,
+	};
+}

package/src/log.ts

@@ -0,0 +1,28 @@
+/**
+ * Structured daemon logging, now backed by `@danypops/daemon-kit/logging` (pino) instead of a
+ * hand-rolled `console.error(JSON.stringify(...))` -- daemon-kit's own module doc explains why:
+ * level ordering/filtering/child-scoping is exactly the kind of thing worth one shared,
+ * dependency-backed implementation instead of four independent hand-rolled ones. One deliberate,
+ * disclosed shape change from jittor's old bespoke format: the event name is now pino's `msg`
+ * field rather than a separate `event` field, matching daemon-kit's shared convention across all
+ * four daemons. `component`/`level`/`timestamp` and credential-safety (callers still must pass
+ * only bounded, non-sensitive fields) are unchanged.
+ */
+import { createLogger, type LogLevel as DaemonKitLogLevel, type Logger } from "@danypops/daemon-kit/logging";
+
+export type LogLevel = Extract<DaemonKitLogLevel, "info" | "warn" | "error">;
+
+/**
+ * Also passed directly as `StartDaemonOptions.logger` so daemon-kit's own maintenance-task
+ * failure logging shares this same sink/shape. `destination` is pinned to `console.error` rather
+ * than daemon-kit's own default (a raw fd 2 write via `pino.destination(2)`, which bypasses
+ * `console.error` entirely) so existing tooling/tests that intercept `console.error` keep working.
+ */
+export const logger: Logger = createLogger("jittor-daemon", {
+	destination: { write: (chunk: string) => { console.error(chunk.replace(/\n$/, "")); return true; } },
+});
+
+/** Credential-safe structured daemon event. Callers must pass bounded, non-sensitive fields. */
+export function logEvent(level: LogLevel, event: string, fields: Record<string, unknown> = {}): void {
+	logger[level](event, fields);
+}

package/src/ports/benchmark-controller.ts

@@ -0,0 +1,11 @@
+import type {
+	BenchmarkQuery,
+	BenchmarkQueryResult,
+	BenchmarkRefreshResult,
+} from "../domain/benchmark.ts";
+
+export interface BenchmarkController {
+	refresh(force?: boolean): Promise<BenchmarkRefreshResult>;
+	status(): BenchmarkRefreshResult;
+	query(input: BenchmarkQuery): BenchmarkQueryResult;
+}

package/src/ports/benchmark-source.ts

@@ -0,0 +1,7 @@
+import type { BenchmarkSourceSnapshot } from "../domain/benchmark.ts";
+
+/** External evidence boundary. Implementations validate one source-specific schema. */
+export interface BenchmarkSource {
+	readonly id: string;
+	fetch(): Promise<BenchmarkSourceSnapshot>;
+}

package/src/ports/benchmark-store.ts

@@ -0,0 +1,7 @@
+import type { BenchmarkObservation, BenchmarkSnapshot } from "../domain/benchmark.ts";
+
+/** Immutable evidence snapshot boundary. Only complete snapshots become visible. */
+export interface BenchmarkStore {
+	publish(sourceId: string, snapshotId: string, observations: BenchmarkObservation[]): BenchmarkSnapshot;
+	latest(sourceId: string): BenchmarkSnapshot | null;
+}

package/src/ports/metric-store.ts

@@ -1,8 +1,38 @@
+import type { UsageAggregateRow } from "../domain/usage.ts";
 import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../domain/metric.ts";
 
+export interface DistinctScopesFilter {
+	source: string;
+	since: number;
+	until: number;
+	limit: number;
+}
+
+export interface UsageAggregateFilter {
+	source: string;
+	/** Only these scopes are summed -- callers pass the bounded result of distinctScopes, so a real explosion of distinct scopes truncates honestly instead of this method silently discovering and aggregating an unbounded set on its own. */
+	scopes: string[];
+	since: number;
+	until: number;
+	bucketSizeMs: number;
+	bucketCount: number;
+}
+
 export interface MetricStore {
 	record(observation: MetricObservation): StoredMetricObservation;
 	query(filter?: MetricQuery): StoredMetricObservation[];
+	/** Bounded distinct scope values for a source within a time window, so callers can fetch a fair share per scope instead of one flat query a single heavy scope could monopolize. */
+	distinctScopes(filter: DistinctScopesFilter): string[];
+	/**
+	 * SQL-side (scope, metric, bucket) sums for a bounded scope list -- result size scales with
+	 * (scopes x distinct metrics x buckets), never with raw event count, so a heavy scope's full
+	 * history is represented exactly regardless of how many observations fed it. Replaces fetching
+	 * up to a fixed number of raw rows per scope, which could silently truncate a single heavy
+	 * scope's own older history within the requested window (a real incident: a scope with 49,270
+	 * rows in a week had its "weekly" chart built from the 250 most recent rows alone -- 3.3
+	 * minutes of real activity mislabeled as a full week).
+	 */
+	aggregateUsage(filter: UsageAggregateFilter): UsageAggregateRow[];
 	pruneBefore(cutoff: number): number;
 	checkpoint(): void;
 	close(): void;

package/src/ports/router-controller.ts

@@ -39,4 +39,5 @@ export interface RouterController {
 	clearOverride(): RouterStatus;
 	setCurrentRoute(route: Route): RouterStatus;
 	setAvailableRoutes(routes: Route[]): RouterStatus;
+	applyModelRanking?(candidates: Route[]): RouterStatus;
 }

package/src/providers/anthropic-contracts.ts

@@ -0,0 +1,127 @@
+import type { MetricObservation } from "../domain/metric.ts";
+
+/**
+ * Official Anthropic Messages API rate-limit response headers, verified against
+ * https://platform.claude.com/docs/en/api/rate-limits (fetched 2026-07-21). These headers are
+ * returned on every Messages API response (per-request, not from a standalone polling endpoint —
+ * Anthropic's Admin/Rate Limits API is documented as "unavailable for individual accounts"), so
+ * Jittor observes them from Pi's own `after_provider_response` event rather than daemon-side
+ * polling. Priority Tier buckets are optional and only present for organizations enrolled in it.
+ */
+export interface AnthropicRateLimitWindow {
+	limit: number | null;
+	remaining: number | null;
+	resetsAt: number | null;
+}
+
+export interface AnthropicRateLimitSnapshot {
+	requests: AnthropicRateLimitWindow | null;
+	tokens: AnthropicRateLimitWindow | null;
+	inputTokens: AnthropicRateLimitWindow | null;
+	outputTokens: AnthropicRateLimitWindow | null;
+	priorityInputTokens: AnthropicRateLimitWindow | null;
+	priorityOutputTokens: AnthropicRateLimitWindow | null;
+	retryAfterMs: number | null;
+	observedAt: number;
+	metrics: MetricObservation[];
+}
+
+function metric(
+	source: AnthropicMetricSource,
+	scope: string,
+	name: string,
+	value: number,
+	unit: MetricObservation["unit"],
+	observedAt: number,
+	attributes: Record<string, unknown> = {},
+): MetricObservation {
+	return { source, scope, metric: name, value, unit, observedAt, attributes };
+}
+
+function headerInteger(headers: Headers, name: string): number | null {
+	const raw = headers.get(name);
+	if (raw === null) return null;
+	const value = Number(raw);
+	if (!Number.isFinite(value) || !Number.isSafeInteger(value) || value < 0) throw new Error(`Anthropic rate-limit header schema changed: ${name}`);
+	return value;
+}
+
+function headerResetTime(headers: Headers, name: string): number | null {
+	const raw = headers.get(name);
+	if (raw === null) return null;
+	const parsed = Date.parse(raw);
+	if (!Number.isFinite(parsed)) throw new Error(`Anthropic rate-limit header schema changed: ${name} is not RFC 3339`);
+	return parsed;
+}
+
+function parseWindow(headers: Headers, prefix: string): AnthropicRateLimitWindow | null {
+	const limit = headerInteger(headers, `${prefix}-limit`);
+	const remaining = headerInteger(headers, `${prefix}-remaining`);
+	const resetsAt = headerResetTime(headers, `${prefix}-reset`);
+	if (limit === null && remaining === null && resetsAt === null) return null;
+	return { limit, remaining, resetsAt };
+}
+
+function windowMetrics(source: AnthropicMetricSource, scope: string, window: AnthropicRateLimitWindow | null, observedAt: number): MetricObservation[] {
+	if (!window) return [];
+	const metrics: MetricObservation[] = [];
+	const attributes = { limit: window.limit, remaining: window.remaining, resetsAt: window.resetsAt };
+	if (window.limit !== null && window.limit > 0 && window.remaining !== null) {
+		const remainingFraction = window.remaining / window.limit;
+		if (remainingFraction < 0 || remainingFraction > 1) throw new Error(`Anthropic ${scope} remaining exceeds its configured limit`);
+		metrics.push(metric(source, scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
+		metrics.push(metric(source, scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
+	}
+	return metrics;
+}
+
+/**
+ * Direct Anthropic API calls and Anthropic-on-Vertex passthroughs (e.g. the third-party
+ * `@twogiants/pi-anthropic-vertex` extension, which reuses Pi's built-in Anthropic Messages stream
+ * with Anthropic's own `@anthropic-ai/vertex-sdk` client) may both emit this same header shape, but
+ * they are different accounts against different quota pools -- Anthropic's own org-scoped buckets
+ * vs whatever a Vertex project's passthrough exposes, if anything. Tagging the metric source keeps
+ * them from ever being blended into one budget reading.
+ */
+export type AnthropicMetricSource = "anthropic" | "anthropic-vertex";
+
+export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now(), source: AnthropicMetricSource = "anthropic"): AnthropicRateLimitSnapshot {
+	const requests = parseWindow(headers, "anthropic-ratelimit-requests");
+	const tokens = parseWindow(headers, "anthropic-ratelimit-tokens");
+	const inputTokens = parseWindow(headers, "anthropic-ratelimit-input-tokens");
+	const outputTokens = parseWindow(headers, "anthropic-ratelimit-output-tokens");
+	const priorityInputTokens = parseWindow(headers, "anthropic-priority-input-tokens");
+	const priorityOutputTokens = parseWindow(headers, "anthropic-priority-output-tokens");
+	const retryAfterRaw = headers.get("retry-after");
+	const retryAfterSeconds = retryAfterRaw === null ? null : Number(retryAfterRaw);
+	if (retryAfterRaw !== null && (!Number.isFinite(retryAfterSeconds) || (retryAfterSeconds as number) < 0)) {
+		throw new Error("Anthropic rate-limit header schema changed: retry-after");
+	}
+	return {
+		requests,
+		tokens,
+		inputTokens,
+		outputTokens,
+		priorityInputTokens,
+		priorityOutputTokens,
+		retryAfterMs: retryAfterSeconds === null ? null : Math.round(retryAfterSeconds * 1_000),
+		observedAt,
+		metrics: [
+			...windowMetrics(source, "requests", requests, observedAt),
+			...windowMetrics(source, "tokens", tokens, observedAt),
+			...windowMetrics(source, "input-tokens", inputTokens, observedAt),
+			...windowMetrics(source, "output-tokens", outputTokens, observedAt),
+			...windowMetrics(source, "priority-input-tokens", priorityInputTokens, observedAt),
+			...windowMetrics(source, "priority-output-tokens", priorityOutputTokens, observedAt),
+		],
+	};
+}
+
+/** True when the response carries at least one recognized Anthropic rate-limit header. */
+export function hasAnthropicRateLimitHeaders(headers: Headers): boolean {
+	for (const name of headers.keys()) {
+		const lower = name.toLowerCase();
+		if (lower.startsWith("anthropic-ratelimit-") || lower.startsWith("anthropic-priority-")) return true;
+	}
+	return false;
+}

package/src/providers/google-adc-auth.ts

@@ -0,0 +1,63 @@
+import { GoogleAuth } from "google-auth-library";
+import { GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS } from "../constants.ts";
+
+/**
+ * The only file in Jittor that imports `google-auth-library` (Jittor's first runtime dependency;
+ * see docs/PROVIDER_RESEARCH.md for why ADC token acquisition -- not the Vertex/Budget API
+ * surface itself -- is the one piece worth a mature dependency instead of hand-rolling: it is
+ * security-sensitive OAuth/JWT/metadata-server protocol code, the exact class of thing the
+ * project's own off-the-shelf-modules guidance calls out as worth not reimplementing).
+ *
+ * This matches the individual-GCP-project migration's "passwordless/keyless" model: Application
+ * Default Credentials (a user's own `gcloud auth application-default login` session, a Compute/
+ * Cloud Run metadata identity, or Workload Identity Federation), never a static service-account
+ * key file. `google-auth-library` auto-detects which of those applies to the environment it runs
+ * in; Jittor does not choose or configure a credential type itself.
+ */
+export type GoogleAdcTokenProvider = () => Promise<string>;
+
+/** The minimal shape this module actually calls on an ADC client; matches google-auth-library's real `AuthClient`/`Credentials` fields (verified against its published `.d.ts`), kept narrow so tests can inject a fake without constructing a real `GoogleAuth`. */
+export interface GoogleAdcClient {
+	getAccessToken(): Promise<{ token?: string | null }>;
+	credentials?: { expiry_date?: number | null };
+}
+
+export type GoogleAdcClientFactory = (scopes: readonly string[]) => Promise<GoogleAdcClient>;
+
+async function defaultAdcClientFactory(scopes: readonly string[]): Promise<GoogleAdcClient> {
+	return new GoogleAuth({ scopes: [...scopes] }).getClient();
+}
+
+/**
+ * Wraps ADC token acquisition with the caching every other Jittor provider adapter skips
+ * only because their upstreams don't require an OAuth exchange per call: a fresh Google access
+ * token is valid for roughly an hour, and re-deriving ADC (which may itself make a metadata-server
+ * or token-exchange network call) on every poll would be wasteful and, for some ADC sources,
+ * rate-limited. `GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS` triggers a refresh slightly before Google
+ * itself would consider the cached token invalid.
+ */
+export function createGoogleAdcTokenProvider(
+	scopes: readonly string[],
+	clock: () => number = Date.now,
+	clientFactory: GoogleAdcClientFactory = defaultAdcClientFactory,
+): GoogleAdcTokenProvider {
+	let cachedClient: GoogleAdcClient | undefined;
+	let cachedToken: string | undefined;
+	let cachedExpiryEpochMs = 0;
+
+	return async function getAccessToken(): Promise<string> {
+		const now = clock();
+		if (cachedToken && now < cachedExpiryEpochMs - GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS) return cachedToken;
+		cachedClient ??= await clientFactory(scopes);
+		const { token } = await cachedClient.getAccessToken();
+		if (!token) throw new Error("Google Application Default Credentials did not return an access token");
+		// `credentials.expiry_date` is the verified google-auth-library field (epoch ms). When a
+		// credential type doesn't report one, this deliberately does not fabricate an assumed TTL --
+		// it treats the token as already due for refresh, so the next call re-fetches rather than
+		// caching for a guessed duration.
+		const expiryDate = cachedClient.credentials?.expiry_date;
+		cachedToken = token;
+		cachedExpiryEpochMs = typeof expiryDate === "number" ? expiryDate : now;
+		return token;
+	};
+}