@danypops/jittor 0.16.3 → 0.18.0

package/src/cli-commands/cache.ts

@@ -0,0 +1,120 @@
+import type {
+	CacheEconomicsAggregateTotals,
+	CacheEconomicsModelSummary,
+	CacheEconomicsStablePrefixPoint,
+	CacheEconomicsSummary,
+	CacheEconomicsTaskSummary,
+	CacheEconomicsUnattributedActivity,
+} from "../observability/cache-economics.ts";
+import { type CliDependencies, callAndPrint, humanField } from "./support.ts";
+
+export const CACHE_USAGE_LINES = ["  cache economics --since <ms> --until <ms> [--json]"];
+
+interface CacheEconomicsArgs {
+	since: number;
+	until: number;
+	json: boolean;
+}
+
+function parseCacheArgs(action: string | undefined, args: string[]): CacheEconomicsArgs | null {
+	if (action !== "economics") return 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 (argument !== "--since" && argument !== "--until") return null;
+		const raw = args[++index];
+		const value = raw === undefined ? Number.NaN : Number(raw);
+		if (!Number.isSafeInteger(value) || value < 0) return null;
+		if (argument === "--since") since = value;
+		else until = value;
+	}
+	if (since === undefined || until === undefined || until < since) return null;
+	return { since, until, json };
+}
+
+function formatUsdAmount(amount: number): string {
+	return `$${amount.toFixed(Math.abs(amount) < 0.01 && amount !== 0 ? 4 : 2)}`;
+}
+
+function basisSuffix(basis: "provider-reported" | "catalog-estimate" | "unknown"): string {
+	return basis === "provider-reported" ? "" : basis === "catalog-estimate" ? " (catalog estimate)" : "";
+}
+
+function formatCostField(amountUsd: number | null, basis: "provider-reported" | "catalog-estimate" | "unknown"): string {
+	return amountUsd === null ? "unknown" : `${formatUsdAmount(amountUsd)}${basisSuffix(basis)}`;
+}
+
+function formatAggregateFields(totals: CacheEconomicsAggregateTotals): string {
+	const payback = totals.paybackAchieved === null ? "n/a" : totals.paybackAchieved ? "yes" : "not yet";
+	return [
+		`read ${totals.cacheReadTokens.toLocaleString()} tok (${formatCostField(totals.cacheReadCostUsd, totals.cacheReadCostBasis)})`,
+		`write ${totals.cacheWriteTokens.toLocaleString()} tok (${formatCostField(totals.cacheWriteCostUsd, totals.cacheWriteCostBasis)})`,
+		`savings ${totals.savingsUsd === null ? "unknown" : formatUsdAmount(totals.savingsUsd)}`,
+		`premium ${totals.cacheWritePremiumUsd === null ? "unknown" : formatUsdAmount(totals.cacheWritePremiumUsd)}`,
+		`break-even ${totals.breakEvenReadTokens === null ? "unknown" : `${totals.breakEvenReadTokens.toLocaleString()} tok`}`,
+		`payback ${payback}`,
+	].join(" · ");
+}
+
+function formatFreshnessSuffix(catalogFreshness: "fresh" | "stale" | null): string {
+	return catalogFreshness === "stale" ? " (stale catalog snapshot used for the estimate(s) above)" : "";
+}
+
+function formatModelLine(model: CacheEconomicsModelSummary): string {
+	return `- ${humanField(model.provider)}/${humanField(model.model)}: ${formatAggregateFields(model)}${formatFreshnessSuffix(model.catalogFreshness)}`;
+}
+
+function formatTaskLine(task: CacheEconomicsTaskSummary): string {
+	return `- ${humanField(task.taskId)}: ${formatAggregateFields(task)}${formatFreshnessSuffix(task.catalogFreshness)}`;
+}
+
+function formatUnattributedLine(activity: CacheEconomicsUnattributedActivity): string {
+	return [
+		`Unattributed cache activity (no Papyrus task focused):`,
+		`read ${activity.cacheReadTokens.toLocaleString()} tok (${formatCostField(activity.cacheReadCostUsd, activity.cacheReadCostBasis)})`,
+		`write ${activity.cacheWriteTokens.toLocaleString()} tok (${formatCostField(activity.cacheWriteCostUsd, activity.cacheWriteCostBasis)})`,
+	].join(" · ");
+}
+
+function formatChurnPoint(point: CacheEconomicsStablePrefixPoint): string {
+	return `- ${new Date(point.observedAt).toISOString()} session ${humanField(point.sessionId)}: ${point.stablePrefixTokens.toLocaleString()} tok${point.resetReason === null ? "" : ` (${point.resetReason} reset)`}`;
+}
+
+export function formatCacheEconomics(summary: CacheEconomicsSummary): string {
+	const lines = [
+		`Cache economics: ${summary.models.length.toLocaleString()} model(s)${summary.truncated ? " (query limit reached; totals are a lower bound)" : ""}`,
+		...summary.models.map(formatModelLine),
+		`By task: ${summary.tasks.length.toLocaleString()} task(s)`,
+		...summary.tasks.map(formatTaskLine),
+		formatUnattributedLine(summary.unattributedCacheActivity),
+		...(summary.stablePrefixChurn.length > 0
+			? [
+					`Stable-prefix churn (${summary.stablePrefixChurn.length.toLocaleString()} snapshot(s), oldest first):`,
+					...summary.stablePrefixChurn.map(formatChurnPoint),
+				]
+			: []),
+		`Candidate missed-cache opportunities: ${summary.missedOpportunities.length.toLocaleString()}`,
+		...summary.missedOpportunities.map(
+			(candidate) =>
+				`- session ${humanField(candidate.sessionId)}: ${candidate.resetReason} reset, then ${candidate.cacheWriteTokens.toLocaleString()} cache-write tok${candidate.cacheWriteCostUsd === null ? "" : ` (${formatUsdAmount(candidate.cacheWriteCostUsd)})`} -- ${candidate.note}`,
+		),
+	];
+	return lines.join("\n");
+}
+
+export async function runCacheCommand(
+	action: string | undefined,
+	rest: string[],
+	deps: CliDependencies,
+	usage: () => number,
+): Promise<number> {
+	const parsed = parseCacheArgs(action, rest);
+	if (!parsed) return usage();
+	return callAndPrint(deps, "cache.economics", { since: parsed.since, until: parsed.until }, parsed.json, formatCacheEconomics);
+}

package/src/cli-commands/catalog.ts

@@ -0,0 +1,123 @@
+import { MODEL_CATALOG_MAX_QUERY_LIMIT } from "../constants.ts";
+import type { ModelCatalogQuery, ModelCatalogQueryResult, ModelCatalogStatus } from "../optimization/model-selection/catalog.ts";
+import { type CliDependencies, humanField } from "./support.ts";
+
+export const CATALOG_USAGE_LINES = [
+	"  catalog <status|refresh|list> [--provider <id>] [--model <id>] [--limit <n>] [--context-tokens <n>] [--input-tokens <n>] [--output-tokens <n>] [--input-price <usd-per-million>] [--output-price <usd-per-million>] [--force] [--json]",
+];
+
+interface CatalogArgs {
+	action: "status" | "refresh" | "list";
+	json: boolean;
+	force: boolean;
+	query: ModelCatalogQuery;
+}
+
+function parsePositive(raw: string, integer: boolean): number | null {
+	const value = Number(raw);
+	if (!Number.isFinite(value) || value < 0 || (integer && !Number.isSafeInteger(value))) return null;
+	return value;
+}
+
+function parseCatalogArgs(action: string | undefined, args: string[]): CatalogArgs | null {
+	if (action !== "status" && action !== "refresh" && action !== "list") return null;
+	let json = false;
+	let force = false;
+	const query: ModelCatalogQuery = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") {
+			json = true;
+			continue;
+		}
+		if (argument === "--force" && action === "refresh") {
+			force = true;
+			continue;
+		}
+		if (action !== "list") return null;
+		if (
+			!argument ||
+			![
+				"--provider",
+				"--model",
+				"--limit",
+				"--context-tokens",
+				"--input-tokens",
+				"--output-tokens",
+				"--input-price",
+				"--output-price",
+			].includes(argument)
+		)
+			return null;
+		const raw = args[++index];
+		if (!raw) return null;
+		if (argument === "--provider") query.provider = raw;
+		else if (argument === "--model") query.model = raw;
+		else if (argument === "--limit") {
+			const value = parsePositive(raw, true);
+			if (value === null || value < 1 || value > MODEL_CATALOG_MAX_QUERY_LIMIT) return null;
+			query.limit = value;
+		} else {
+			const integer = argument.endsWith("-tokens");
+			const value = parsePositive(raw, integer);
+			if (value === null) return null;
+			const key = {
+				"--context-tokens": "contextTokens",
+				"--input-tokens": "inputTokens",
+				"--output-tokens": "outputTokens",
+				"--input-price": "inputPrice",
+				"--output-price": "outputPrice",
+			}[argument] as "contextTokens" | "inputTokens" | "outputTokens" | "inputPrice" | "outputPrice";
+			if (!query.overrides) query.overrides = {};
+			query.overrides[key] = value;
+		}
+	}
+	return { action, json, force, query };
+}
+
+export function formatCatalogStatus(status: ModelCatalogStatus): string {
+	if (!status.configured && !status.hasSnapshot) return "Model catalog: not configured (set JITTOR_MODELS_DEV_CATALOG=1)";
+	const state = status.ok === null ? "not refreshed" : status.ok ? "ready" : "refresh failed; last-good snapshot retained";
+	return `Model catalog: ${state} · ${status.entries.toLocaleString()} entries · revision ${status.revision ?? "unknown"}`;
+}
+
+export function formatCatalogQuery(result: ModelCatalogQueryResult): string {
+	return [
+		`Model catalog: ${result.completeness} · ${result.freshness} · ${result.entries.length.toLocaleString()} entries · ${humanField(result.provenance.revision)}`,
+		...result.entries.map((entry) => {
+			const cost = entry.pricing
+				? ` · $${entry.pricing.input ?? "unknown"}/$${entry.pricing.output ?? "unknown"} input/output per 1M`
+				: " · pricing unknown";
+			return `- ${humanField(entry.canonical)} · context ${entry.limits.context.toLocaleString()} · output ${entry.limits.output.toLocaleString()}${cost} · ${entry.status}`;
+		}),
+	].join("\n");
+}
+
+export async function runCatalogCommand(
+	action: string | undefined,
+	rest: string[],
+	deps: CliDependencies,
+	usage: () => number,
+): Promise<number> {
+	const parsed = parseCatalogArgs(action, rest);
+	if (!parsed) return usage();
+	try {
+		const result =
+			parsed.action === "list"
+				? await deps.client.call("catalog.query", parsed.query)
+				: parsed.action === "refresh"
+					? await deps.client.call("catalog.refresh", { force: parsed.force })
+					: await deps.client.call("catalog.status", {});
+		deps.stdout(
+			parsed.json
+				? JSON.stringify(result)
+				: parsed.action === "list"
+					? formatCatalogQuery(result as ModelCatalogQueryResult)
+					: formatCatalogStatus(result as ModelCatalogStatus),
+		);
+		return 0;
+	} catch (error) {
+		deps.stderr(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli-commands/compaction.ts

@@ -1,4 +1,4 @@
-import type { CompactionDurationEstimate } from "../domain/context-telemetry.ts";
+import type { CompactionDurationEstimate } from "../observability/context-telemetry.ts";
 import { parseJsonOnlyArgs } from "./router.ts";
 import { type CliDependencies, callAndPrint } from "./support.ts";
 

package/src/cli-commands/context.ts

@@ -1,7 +1,12 @@
-import type { ContextAssessment } from "../domain/context-telemetry.ts";
+import type { ContextDelta, ContextSnapshot } from "../observability/context-delta.ts";
+import type { ContextAssessment } from "../observability/context-telemetry.ts";
 import type { CliDependencies } from "./support.ts";
 
-export const CONTEXT_USAGE_LINES = ["  context [--since <ms>] [--until <ms>] [--json]"];
+export const CONTEXT_USAGE_LINES = [
+	"  context [--since <ms>] [--until <ms>] [--json]",
+	"  context delta --session-id <opaque-id> [--json]",
+	"  context snapshot --snapshot <json> [--json]",
+];
 
 function parseContextArgs(args: string[]): { input: { since?: number; until?: number }; json: boolean } | null {
 	const input: { since?: number; until?: number } = {};
@@ -34,19 +39,87 @@ export function formatContextAssessment(summary: ContextAssessment): string {
 		`Injection mix: rules ${summary.injection.ruleCharacters.toLocaleString()} chars · tasks ${summary.injection.taskCharacters.toLocaleString()} chars · estimated ${summary.injection.estimatedTokens.toLocaleString()} tokens · unchanged ${summary.injection.unchangedRate === null ? "unknown" : `${(summary.injection.unchangedRate * 100).toFixed(1)}%`}`,
 		`Compactions: ${summary.compaction.completed} completed · ${summary.compaction.aborted} aborted · avg ${value(summary.compaction.averageDurationMs, "ms")} · ${summary.compaction.perRun === null ? "unknown" : summary.compaction.perRun.toFixed(3)} per agent run · ${summary.compaction.perTurn === null ? "unknown" : summary.compaction.perTurn.toFixed(3)} per turn`,
 		`Between compactions: ${value(summary.compaction.averageTurnsBetween, " turns")} · ${value(summary.compaction.averageProviderTokensBetween, " provider tokens")} · ${value(summary.compaction.averageCacheReadTokensBetween, " cache-read tokens")}`,
+		`Effectiveness: ${summary.compaction.effectivenessSamples} samples · avg reduction ${value(summary.compaction.averageReductionRatio === null ? null : summary.compaction.averageReductionRatio * 100, "%")} · pre ${value(summary.compaction.averagePreContextTokens, " tokens")} · post ${value(summary.compaction.averagePostContextTokens, " tokens")}`,
+		`Regrowth: 50% ${summary.compaction.regrowth["50"] ? `${value(summary.compaction.regrowth["50"].averageTurns, " turns")} / ${value(summary.compaction.regrowth["50"].averageElapsedMs, "ms")}` : "unknown"} · 80% ${summary.compaction.regrowth["80"] ? `${value(summary.compaction.regrowth["80"].averageTurns, " turns")} / ${value(summary.compaction.regrowth["80"].averageElapsedMs, "ms")}` : "unknown"} · 100% ${summary.compaction.regrowth["100"] ? `${value(summary.compaction.regrowth["100"].averageTurns, " turns")} / ${value(summary.compaction.regrowth["100"].averageElapsedMs, "ms")}` : "unknown"}`,
+		`Mechanisms: Pi ${summary.compaction.mechanisms["pi-native"]} · provider ${summary.compaction.mechanisms["provider-side"]} · extension ${summary.compaction.mechanisms.extension}`,
 		`Reasons: threshold ${summary.compaction.reasons.threshold} · overflow ${summary.compaction.reasons.overflow} · manual ${summary.compaction.reasons.manual}`,
 	].join("\n");
 }
 
+export function formatContextDelta(delta: ContextDelta | null): string {
+	if (!delta) return "Context delta: unavailable (no snapshot recorded for this session)";
+	const first = delta.firstChangedSegment;
+	const lifecycle = new Map<string, number>();
+	for (const change of delta.changes) lifecycle.set(change.lifecycle, (lifecycle.get(change.lifecycle) ?? 0) + 1);
+	const lifecycleText = [...lifecycle.entries()].map(([name, count]) => `${name} ${count}`).join(" · ") || "none";
+	const growth = delta.growthBySource
+		.filter((item) => item.deltaTokens !== 0)
+		.map((item) => `${item.source} ${item.deltaTokens > 0 ? "+" : ""}${item.deltaTokens.toLocaleString()} tokens`)
+		.join(" · ");
+	return [
+		`Context delta: ${new Date(delta.capturedAt).toISOString()}`,
+		`Stable prefix: ${delta.stablePrefixTokens.toLocaleString()} tokens${
+			first ? ` · first change ${first.source} at request position ${first.requestPosition ?? "historical"}` : " · unchanged"
+		}`,
+		`Lifecycle: ${lifecycleText}`,
+		`Growth: ${growth || "none"}`,
+		"Stable-prefix correlation is structural evidence, not proof of provider cache behavior.",
+	].join("\n");
+}
+
+function parseDeltaArgs(args: string[]): { input: { session_id: string }; json: boolean } | null {
+	let sessionId: string | undefined;
+	let json = false;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index];
+		if (argument === "--json") json = true;
+		else if (argument === "--session-id") sessionId = args[++index];
+		else return null;
+	}
+	if (!sessionId || !/^[A-Za-z0-9_-]{32,64}$/.test(sessionId)) return null;
+	return { input: { session_id: sessionId }, json };
+}
+
+function parseSnapshotArgs(args: string[]): { input: ContextSnapshot; json: boolean } | null {
+	let snapshotValue: string | undefined;
+	let json = false;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index];
+		if (argument === "--json") json = true;
+		else if (argument === "--snapshot") snapshotValue = args[++index];
+		else return null;
+	}
+	if (!snapshotValue) return null;
+	try {
+		return { input: JSON.parse(snapshotValue) as ContextSnapshot, json };
+	} catch {
+		return null;
+	}
+}
+
 export async function runContextCommand(
 	action: string | undefined,
 	rest: string[],
 	deps: CliDependencies,
 	usage: () => number,
 ): Promise<number> {
-	const parsed = parseContextArgs([...(action === undefined ? [] : [action]), ...rest]);
-	if (!parsed) return usage();
 	try {
+		if (action === "delta") {
+			const parsed = parseDeltaArgs(rest);
+			if (!parsed) return usage();
+			const delta = await deps.client.call("context.delta", parsed.input);
+			deps.stdout(parsed.json ? JSON.stringify(delta) : formatContextDelta(delta));
+			return 0;
+		}
+		if (action === "snapshot") {
+			const parsed = parseSnapshotArgs(rest);
+			if (!parsed) return usage();
+			const delta = await deps.client.call("context.snapshot", parsed.input);
+			deps.stdout(parsed.json ? JSON.stringify(delta) : formatContextDelta(delta));
+			return 0;
+		}
+		const parsed = parseContextArgs([...(action === undefined ? [] : [action]), ...rest]);
+		if (!parsed) return usage();
 		const summary = await deps.client.call("context.assess", parsed.input);
 		deps.stdout(parsed.json ? JSON.stringify(summary) : formatContextAssessment(summary));
 		return 0;

package/src/cli-commands/export.ts

@@ -0,0 +1,30 @@
+import type { ObservationExportStatus } from "../telemetry-export/exporter.ts";
+import type { CliDependencies } from "./support.ts";
+
+export const EXPORT_USAGE_LINES = ["  export <status|flush> [--json]"];
+
+export function formatExportStatus(status: ObservationExportStatus): string {
+	if (!status.enabled) return "OTLP export: disabled";
+	return [
+		`OTLP export: enabled · semantic conventions ${status.semanticConventions}`,
+		`Queue: ${status.queued.toLocaleString()} queued · ${status.exported.toLocaleString()} exported · ${status.dropped.toLocaleString()} dropped · ${status.failures.toLocaleString()} failed batches`,
+	].join("\n");
+}
+
+export async function runExportCommand(
+	action: string | undefined,
+	rest: string[],
+	deps: CliDependencies,
+	usage: () => number,
+): Promise<number> {
+	if ((action !== "status" && action !== "flush") || rest.some((argument) => argument !== "--json")) return usage();
+	const json = rest.includes("--json");
+	try {
+		const status = await deps.client.call(action === "flush" ? "export.flush" : "export.status", {});
+		deps.stdout(json ? JSON.stringify(status) : formatExportStatus(status));
+		return 0;
+	} catch (error) {
+		deps.stderr(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli-commands/metrics.ts

@@ -5,8 +5,14 @@ import {
 	METRIC_BATCH_MAX_OBSERVATIONS,
 	USAGE_MAX_DISTINCT_SCOPES,
 } from "../constants.ts";
-import { METRIC_UNITS, type MetricObservation, type MetricQuery, type MetricUnit, type StoredMetricObservation } from "../domain/metric.ts";
-import type { TaskCostSummary } from "../domain/task-cost.ts";
+import {
+	METRIC_UNITS,
+	type MetricObservation,
+	type MetricQuery,
+	type MetricUnit,
+	type StoredMetricObservation,
+} from "../observability/metric.ts";
+import type { TaskCostSummary } from "../observability/task-cost.ts";
 import { type CliDependencies, callAndPrint, humanField } from "./support.ts";
 
 export const METRICS_USAGE_LINES = [

package/src/cli-commands/op.ts

@@ -1,4 +1,4 @@
-import { EXPECTED_OPERATION_NAMES, type OperationName } from "../service.ts";
+import { EXPECTED_OPERATION_NAMES, type OperationName } from "../vehicle/service.ts";
 import type { CliDependencies } from "./support.ts";
 
 export const OP_USAGE_LINES = ["  op <operation> [--input <json>]"];

package/src/cli-commands/route-args.ts

@@ -1,5 +1,5 @@
-import type { ModelCandidate } from "../domain/model-ranking.ts";
-import type { Route } from "../policy.ts";
+import type { ModelCandidate } from "../optimization/model-selection/ranking.ts";
+import type { Route } from "../optimization/routing/policy.ts";
 
 /** Shared `provider/model@thinking` parsing for router and benchmark CLI arguments -- a Route and a ModelCandidate are structurally identical at this boundary. */
 export function parseCandidate(raw: string): ModelCandidate | null {

package/src/cli-commands/router.ts

@@ -1,6 +1,6 @@
 import { CLI_AVAILABLE_ROUTES_MAX } from "../constants.ts";
-import type { PolicyDecision, Route } from "../policy.ts";
-import type { RouteOverride, RouterStatus, TelemetryPollResult } from "../ports/router-controller.ts";
+import type { RouteOverride, RouterStatus, TelemetryPollResult } from "../optimization/routing/controller.ts";
+import type { PolicyDecision, Route } from "../optimization/routing/policy.ts";
 import { parseRoute } from "./route-args.ts";
 import { type CliDependencies, callAndPrint, humanField } from "./support.ts";
 

package/src/cli-commands/support.ts

@@ -1,6 +1,6 @@
-import type { JittorClient } from "../client.ts";
 import { HUMAN_TEXT_FIELD_MAX_CHARACTERS } from "../constants.ts";
-import type { OperationInputs, OperationName, OperationOutputs } from "../service.ts";
+import type { JittorClient } from "../vehicle/client.ts";
+import type { OperationInputs, OperationName, OperationOutputs } from "../vehicle/service.ts";
 
 export interface CliDependencies {
 	client: Pick<JittorClient, "call">;

package/src/cli.ts

@@ -1,21 +1,38 @@
 #!/usr/bin/env bun
 import { fileURLToPath } from "node:url";
+import { BACKFILL_USAGE_LINES, formatUsageImportResult, formatUsageImportStatus, runBackfillCommand } from "./cli-commands/backfill.ts";
 import { BENCHMARKS_USAGE_LINES, runBenchmarksCommand } from "./cli-commands/benchmarks.ts";
+import { CACHE_USAGE_LINES, formatCacheEconomics, runCacheCommand } from "./cli-commands/cache.ts";
+import { CATALOG_USAGE_LINES, formatCatalogQuery, formatCatalogStatus, runCatalogCommand } from "./cli-commands/catalog.ts";
 import { runCompactionCommand } from "./cli-commands/compaction.ts";
-import { CONTEXT_USAGE_LINES, formatContextAssessment, runContextCommand } from "./cli-commands/context.ts";
+import { CONTEXT_USAGE_LINES, formatContextAssessment, formatContextDelta, runContextCommand } from "./cli-commands/context.ts";
+import { EXPORT_USAGE_LINES, formatExportStatus, runExportCommand } from "./cli-commands/export.ts";
 import { formatCostByTask, formatMetricsQuery, METRICS_USAGE_LINES, runMetricsCommand } from "./cli-commands/metrics.ts";
 import { OP_USAGE_LINES, runOpCommand } from "./cli-commands/op.ts";
 import { formatRouterStatus, ROUTER_USAGE_LINES, runRouterCommand, runTelemetryCommand } from "./cli-commands/router.ts";
 import { installService, renderSystemdUnit, runServiceCommand, SERVICE_USAGE_LINES, systemctl } from "./cli-commands/service-daemon.ts";
 import { runSessionCommand, SESSION_USAGE_LINES } from "./cli-commands/session.ts";
 import type { CliDependencies } from "./cli-commands/support.ts";
-import { connectJittorClient } from "./client.ts";
 import { serveMain } from "./daemon.ts";
+import { connectJittorClient } from "./vehicle/client.ts";
 
 // Re-exported for external callers (tests, daemon.ts's systemd-unit test) that import these
 // directly from cli.ts rather than reaching into src/cli-commands/*.
 export type { CliDependencies };
-export { formatContextAssessment, formatCostByTask, formatMetricsQuery, formatRouterStatus, renderSystemdUnit };
+export {
+	formatCacheEconomics,
+	formatCatalogQuery,
+	formatCatalogStatus,
+	formatContextAssessment,
+	formatContextDelta,
+	formatCostByTask,
+	formatExportStatus,
+	formatMetricsQuery,
+	formatRouterStatus,
+	formatUsageImportResult,
+	formatUsageImportStatus,
+	renderSystemdUnit,
+};
 
 const DEFAULT_DEPENDENCIES: CliDependencies = {
 	get client() {
@@ -34,8 +51,12 @@ function usage(stderr: (line: string) => void): number {
 			"Usage: jittor <command> [options]",
 			"  serve",
 			...SERVICE_USAGE_LINES,
+			...BACKFILL_USAGE_LINES,
+			...EXPORT_USAGE_LINES,
 			...CONTEXT_USAGE_LINES,
 			...BENCHMARKS_USAGE_LINES,
+			...CATALOG_USAGE_LINES,
+			...CACHE_USAGE_LINES,
 			...METRICS_USAGE_LINES,
 			...ROUTER_USAGE_LINES,
 			...SESSION_USAGE_LINES,
@@ -47,29 +68,46 @@ function usage(stderr: (line: string) => void): number {
 
 /**
  * Composes one command dispatcher per capability module (metrics, router+telemetry+compaction,
- * session identity, benchmarks, context, service lifecycle, the raw op escape hatch) instead of
- * a single switch that used to combine every command's own argument parsing, validation, and
- * presentation in one place. Each module owns its own usage lines and command handler; this
- * function only routes the top-level command word and forwards `usage` for the shared "not
- * recognized" fallback.
+ * session identity, benchmarks, context, service lifecycle, the raw op escape hatch). Each module
+ * owns its own argument parsing, validation, presentation, and usage lines; this function's switch
+ * only routes the top-level command word and forwards `usage` for the shared fallback.
  */
 export async function runCli(args: string[], deps: CliDependencies = DEFAULT_DEPENDENCIES): Promise<number> {
 	const [command, action, ...rest] = args;
 	const fail = () => usage(deps.stderr);
-	if (command === "serve") {
-		await deps.serve();
-		return 0;
+	switch (command) {
+		case "serve":
+			await deps.serve();
+			return 0;
+		case "session":
+			return runSessionCommand(action, rest, deps, fail);
+		case "backfill":
+			return runBackfillCommand(action, rest, deps, fail);
+		case "export":
+			return runExportCommand(action, rest, deps, fail);
+		case "metrics":
+			return runMetricsCommand(action, rest, deps, fail);
+		case "telemetry":
+			return runTelemetryCommand(action, rest, deps, fail);
+		case "compaction":
+			return runCompactionCommand(action, rest, deps, fail);
+		case "router":
+			return runRouterCommand(action, rest, deps, fail);
+		case "op":
+			return runOpCommand(action, rest, deps, fail);
+		case "benchmarks":
+			return runBenchmarksCommand(action, rest, deps, fail);
+		case "catalog":
+			return runCatalogCommand(action, rest, deps, fail);
+		case "cache":
+			return runCacheCommand(action, rest, deps, fail);
+		case "context":
+			return runContextCommand(action, rest, deps, fail);
+		case "service":
+			return runServiceCommand(action, rest, deps, fail);
+		default:
+			return fail();
 	}
-	if (command === "session") return runSessionCommand(action, rest, deps, fail);
-	if (command === "metrics") return runMetricsCommand(action, rest, deps, fail);
-	if (command === "telemetry") return runTelemetryCommand(action, rest, deps, fail);
-	if (command === "compaction") return runCompactionCommand(action, rest, deps, fail);
-	if (command === "router") return runRouterCommand(action, rest, deps, fail);
-	if (command === "op") return runOpCommand(action, rest, deps, fail);
-	if (command === "benchmarks") return runBenchmarksCommand(action, rest, deps, fail);
-	if (command === "context") return runContextCommand(action, rest, deps, fail);
-	if (command === "service") return runServiceCommand(action, rest, deps, fail);
-	return fail();
 }
 
 export async function main(args: string[] = process.argv.slice(2)): Promise<void> {

package/src/{providers/codex-contracts.ts → codex/contracts.ts}

@@ -1,4 +1,4 @@
-import type { MetricObservation } from "../domain/metric.ts";
+import type { MetricObservation } from "../observability/metric.ts";
 
 export interface CodexWindow {
 	usedPercent: number;

package/src/codex/source.ts

@@ -0,0 +1,53 @@
+import type { BudgetWindow } from "../observability/budget.ts";
+import type { TelemetryBatch, TelemetrySource } from "../observability/telemetry-source.ts";
+import {
+	type CodexRateLimitSnapshot,
+	CodexSubscriptionTelemetryAdapter,
+	type CodexTransport,
+	type CodexWindow,
+	loadCodexFileCredentials,
+} from "./telemetry.ts";
+
+function budgetWindow(limit: CodexRateLimitSnapshot, name: "primary" | "secondary", window: CodexWindow | null): BudgetWindow | null {
+	if (!window || window.windowSeconds === null || window.resetsAt === null) return null;
+	return {
+		id: `${limit.limitId}:${name}@${limit.observedAt}`,
+		source: "codex-subscription",
+		scope: limit.limitId === "codex" ? `codex:${name}` : `${limit.limitId}:${name}`,
+		usedFraction: window.usedPercent / 100,
+		windowSeconds: window.windowSeconds,
+		resetsAt: window.resetsAt * 1_000,
+		observedAt: limit.observedAt,
+		freshness: "fresh",
+		confidence: 0.8,
+	};
+}
+
+function windowsFromLimit(limit: CodexRateLimitSnapshot): BudgetWindow[] {
+	return [budgetWindow(limit, "primary", limit.primary), budgetWindow(limit, "secondary", limit.secondary)].filter(
+		(window): window is BudgetWindow => window !== null,
+	);
+}
+
+export class CodexTelemetrySource implements TelemetrySource {
+	readonly id = "codex-subscription";
+	readonly provider = "openai-codex";
+	readonly required = true;
+
+	constructor(
+		private readonly authFile: string,
+		private readonly transport: CodexTransport = fetch,
+		private readonly clock: () => number = Date.now,
+	) {}
+
+	async poll(): Promise<TelemetryBatch> {
+		const observedAt = this.clock();
+		const adapter = new CodexSubscriptionTelemetryAdapter(loadCodexFileCredentials(this.authFile), this.transport);
+		const snapshot = await adapter.readUsage(observedAt);
+		return {
+			observedAt,
+			metrics: snapshot.metrics,
+			windows: [snapshot.defaultLimit, ...snapshot.additionalLimits].flatMap(windowsFromLimit),
+		};
+	}
+}

package/src/{providers/codex.ts → codex/telemetry.ts}

@@ -1,5 +1,5 @@
 import { readFileSync, statSync } from "node:fs";
-import { type CodexRateLimitSnapshot, type CodexUsageSnapshot, parseCodexRateLimitHeaders, parseCodexUsage } from "./codex-contracts.ts";
+import { type CodexRateLimitSnapshot, type CodexUsageSnapshot, parseCodexRateLimitHeaders, parseCodexUsage } from "./contracts.ts";
 
 export {
 	type CodexCredits,
@@ -11,7 +11,7 @@ export {
 	parseCodexRateLimitHeaders,
 	parseCodexUsage,
 	rateLimitMetrics,
-} from "./codex-contracts.ts";
+} from "./contracts.ts";
 
 const CHATGPT_BACKEND_BASE_URL = "https://chatgpt.com/backend-api";