@danypops/jittor 0.10.0 → 0.11.0

package/src/cli.ts

@@ -1,100 +1,28 @@
 #!/usr/bin/env bun
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import {
-	BENCHMARK_MAX_QUERY_LIMIT,
-	CLI_AVAILABLE_ROUTES_MAX,
-	CLI_METRICS_HUMAN_MAX_ROWS,
-	HUMAN_TEXT_FIELD_MAX_CHARACTERS,
-	MAX_QUERY_LIMIT,
-	MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
-	MODEL_RANKING_DEFAULT_COST_WEIGHT,
-	MODEL_RANKING_DEFAULT_LATENCY_WEIGHT,
-	MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
-	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
-	MODEL_RANKING_MAX_SOURCES,
-	SYSTEMD_UNIT_NAME,
-	MAX_USAGE_BUCKETS,
-	USAGE_MAX_DISTINCT_SCOPES,
-} from "./constants.ts";
-import { connectJittorClient, type JittorClient } from "./client.ts";
+import { connectJittorClient } from "./client.ts";
 import { serveMain } from "./daemon.ts";
-import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "./domain/benchmark.ts";
-import type { ModelRecommendationInput } from "./domain/model-ranking-service.ts";
-import type { ModelCandidate, ModelRankingResult, ScopeAuthority, UtilityWeights } from "./domain/model-ranking.ts";
-import { TASK_DOMAINS, TASK_TYPES, type ModelTaskDomain, type ModelTaskType } from "./domain/model-observation.ts";
-import type { ContextAssessment } from "./domain/context-telemetry.ts";
-import { METRIC_UNITS, type MetricObservation, type MetricQuery, type MetricUnit, type StoredMetricObservation } from "./domain/metric.ts";
-import type { CompactionDurationEstimate } from "./domain/context-telemetry.ts";
-import type { TaskCostSummary } from "./domain/task-cost.ts";
-import type { PolicyDecision, Route } from "./policy.ts";
-import type { RouteOverride, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
-import { EXPECTED_OPERATION_NAMES, type OperationInputs, type OperationName, type OperationOutputs } from "./service.ts";
-import { resolveJittorPaths } from "./state.ts";
-
-export interface SystemdUnitOptions {
-	bunBin: string;
-	cliPath: string;
-	codexAuthFile?: string;
-	openRouterBenchmarks?: boolean;
-}
-
-export function renderSystemdUnit(options: SystemdUnitOptions): string {
-	return `[Unit]
-Description=Jittor token optimizing router
-After=default.target network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=${options.bunBin} ${options.cliPath} serve
-${options.codexAuthFile ? `Environment="JITTOR_CODEX_AUTH_FILE=${options.codexAuthFile.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"\n` : ""}${options.openRouterBenchmarks ? "Environment=JITTOR_OPENROUTER_BENCHMARKS=1\n" : ""}Restart=always
-RestartSec=2
-NoNewPrivileges=true
-PrivateTmp=true
-
-[Install]
-WantedBy=default.target
-`;
-}
-
-export interface CliDependencies {
-	client: Pick<JittorClient, "call">;
-	stdout(line: string): void;
-	stderr(line: string): void;
-	systemctl(...args: string[]): void;
-	installService(): void;
-	serve(): void;
-}
-
-function systemctl(...args: string[]): void {
-	execFileSync("systemctl", ["--user", ...args], { stdio: "inherit" });
-}
-
-function installService(): void {
-	const unitPath = resolveJittorPaths().systemdUnit;
-	mkdirSync(dirname(unitPath), { recursive: true });
-	const codexAuthFile = join(process.env["CODEX_HOME"] ?? join(homedir(), ".codex"), "auth.json");
-	writeFileSync(unitPath, renderSystemdUnit({
-		bunBin: process.execPath,
-		cliPath: fileURLToPath(import.meta.url),
-		...(existsSync(codexAuthFile) ? { codexAuthFile } : {}),
-		openRouterBenchmarks: process.env["JITTOR_OPENROUTER_BENCHMARKS"] === "1",
-	}));
-	systemctl("daemon-reload");
-	systemctl("enable", SYSTEMD_UNIT_NAME);
-	systemctl("restart", SYSTEMD_UNIT_NAME);
-}
+import type { CliDependencies } from "./cli-commands/support.ts";
+import { installService, renderSystemdUnit, systemctl, runServiceCommand, SERVICE_USAGE_LINES } from "./cli-commands/service-daemon.ts";
+import { runSessionCommand, SESSION_USAGE_LINES } from "./cli-commands/session.ts";
+import { runMetricsCommand, METRICS_USAGE_LINES, formatMetricsQuery, formatCostByTask } from "./cli-commands/metrics.ts";
+import { runTelemetryCommand, runRouterCommand, ROUTER_USAGE_LINES, formatRouterStatus } from "./cli-commands/router.ts";
+import { runCompactionCommand } from "./cli-commands/compaction.ts";
+import { runOpCommand, OP_USAGE_LINES } from "./cli-commands/op.ts";
+import { runBenchmarksCommand, BENCHMARKS_USAGE_LINES } from "./cli-commands/benchmarks.ts";
+import { runContextCommand, CONTEXT_USAGE_LINES, formatContextAssessment } from "./cli-commands/context.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 { renderSystemdUnit, formatMetricsQuery, formatCostByTask, formatRouterStatus, formatContextAssessment };
 
 const DEFAULT_DEPENDENCIES: CliDependencies = {
 	get client() { return connectJittorClient(); },
 	stdout: console.log,
 	stderr: console.error,
 	systemctl,
-	installService,
+	installService: () => installService(fileURLToPath(import.meta.url)),
 	serve: serveMain,
 };
 
@@ -102,694 +30,39 @@ function usage(stderr: (line: string) => void): number {
 	stderr([
 		"Usage: jittor <command> [options]",
 		"  serve",
-		"  service <install|start|stop|restart|status|checkpoint>",
-		"  context [--since <ms>] [--until <ms>] [--json]",
-		"  benchmarks <status|refresh|list|rank> [options] [--json]",
-		"  metrics record --source <s> --scope <s> --metric <s> --value <number|null> --unit <unit> [--observed-at <ms>] [--attributes <json>] [--json]",
-		"  metrics query [--source <s>] [--scope <s>] [--metric <s>] [--since <ms>] [--until <ms>] [--limit <n>] [--order asc|desc] [--json]",
-		"  metrics prune --before <ms> [--force] [--json] (force required if before is newer than 24h ago)",
-		`  metrics distinct-scopes --source <s> --since <ms> --until <ms> [--limit 1..${USAGE_MAX_DISTINCT_SCOPES}] [--json]`,
-		`  metrics usage-series --source <s> --since <ms> --until <ms> --bucket-size-ms <ms> --bucket-count 1..${MAX_USAGE_BUCKETS} [--scope-limit 1..${USAGE_MAX_DISTINCT_SCOPES}] [--json]`,
-		"  metrics cost-by-task --since <ms> --until <ms> [--json]",
-		"  telemetry poll [--json]",
-		"  compaction estimate [--json]",
-		"  router <status|decide|pause|resume|clear-override> [--json]",
-		"  router override --route <provider/model@thinking> [--expires-at <ms>] [--json]",
-		"  router current-route --route <provider/model@thinking> [--json]",
-		"  router available-routes [--route <provider/model@thinking> ...] [--json]",
-		"  op <operation> [--input <json>]",
+		...SERVICE_USAGE_LINES,
+		...CONTEXT_USAGE_LINES,
+		...BENCHMARKS_USAGE_LINES,
+		...METRICS_USAGE_LINES,
+		...ROUTER_USAGE_LINES,
+		...SESSION_USAGE_LINES,
+		...OP_USAGE_LINES,
 	].join("\n"));
 	return 2;
 }
 
-function parseContextArgs(args: string[]): { input: { since?: number; until?: number }; json: boolean } | null {
-	const input: { since?: number; until?: number } = {};
-	let json = false;
-	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") input.since = value;
-		else input.until = value;
-	}
-	if (input.since !== undefined && input.until !== undefined && input.until < input.since) return null;
-	return { input, json };
-}
-
-function parseRoute(raw: string | undefined): Route | null {
-	if (raw === undefined) return null;
-	return parseCandidate(raw);
-}
-
-interface MetricsRecordArgs { input: MetricObservation; json: boolean }
-
-function parseMetricsRecordArgs(args: string[]): MetricsRecordArgs | null {
-	let json = false;
-	let source: string | undefined;
-	let scope: string | undefined;
-	let metric: string | undefined;
-	let value: number | null | undefined;
-	let unit: MetricUnit | undefined;
-	let observedAt: number | undefined;
-	let attributes: Record<string, unknown> | undefined;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!["--source", "--scope", "--metric", "--value", "--unit", "--observed-at", "--attributes"].includes(argument ?? "")) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (argument === "--source") source = raw;
-		else if (argument === "--scope") scope = raw;
-		else if (argument === "--metric") metric = raw;
-		else if (argument === "--value") {
-			if (raw.toLowerCase() === "null") value = null;
-			else {
-				const parsed = Number(raw);
-				if (!Number.isFinite(parsed)) return null;
-				value = parsed;
-			}
-		} else if (argument === "--unit") {
-			if (!METRIC_UNITS.includes(raw as MetricUnit)) return null;
-			unit = raw as MetricUnit;
-		} else if (argument === "--observed-at") {
-			const parsed = Number(raw);
-			if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-			observedAt = parsed;
-		} else {
-			try {
-				const parsed = JSON.parse(raw);
-				if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-				attributes = parsed as Record<string, unknown>;
-			} catch {
-				return null;
-			}
-		}
-	}
-	if (source === undefined || scope === undefined || metric === undefined || value === undefined || unit === undefined) return null;
-	return {
-		json,
-		input: {
-			source, scope, metric, value, unit,
-			observedAt: observedAt ?? Date.now(),
-			...(attributes ? { attributes } : {}),
-		},
-	};
-}
-
-interface MetricsQueryArgs { input: MetricQuery; json: boolean }
-
-function parseMetricsQueryArgs(args: string[]): MetricsQueryArgs | null {
-	let json = false;
-	const input: MetricQuery = {};
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!["--source", "--scope", "--metric", "--since", "--until", "--limit", "--order"].includes(argument ?? "")) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (argument === "--source") input.source = raw;
-		else if (argument === "--scope") input.scope = raw;
-		else if (argument === "--metric") input.metric = raw;
-		else if (argument === "--order") {
-			if (raw !== "asc" && raw !== "desc") return null;
-			input.order = raw;
-		} else {
-			const parsed = Number(raw);
-			if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-			if (argument === "--since") input.since = parsed;
-			else if (argument === "--until") input.until = parsed;
-			else {
-				if (parsed < 1 || parsed > MAX_QUERY_LIMIT) return null;
-				input.limit = parsed;
-			}
-		}
-	}
-	if (input.since !== undefined && input.until !== undefined && input.until < input.since) return null;
-	return { input, json };
-}
-
-interface MetricsDistinctScopesArgs { input: { source: string; since: number; until: number; limit?: number }; json: boolean }
-
-function parseMetricsDistinctScopesArgs(args: string[]): MetricsDistinctScopesArgs | null {
-	let json = false;
-	let source: string | undefined;
-	let since: number | undefined;
-	let until: number | undefined;
-	let limit: number | undefined;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!["--source", "--since", "--until", "--limit"].includes(argument ?? "")) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (argument === "--source") { source = raw; continue; }
-		const parsed = Number(raw);
-		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-		if (argument === "--since") since = parsed;
-		else if (argument === "--until") until = parsed;
-		else {
-			if (parsed < 1 || parsed > USAGE_MAX_DISTINCT_SCOPES) return null;
-			limit = parsed;
-		}
-	}
-	if (source === undefined || since === undefined || until === undefined || until < since) return null;
-	return { input: { source, since, until, ...(limit === undefined ? {} : { limit }) }, json };
-}
-
-interface MetricsUsageSeriesArgs { input: { source: string; since: number; until: number; bucketSizeMs: number; bucketCount: number; scopeLimit?: number }; json: boolean }
-
-function parseMetricsUsageSeriesArgs(args: string[]): MetricsUsageSeriesArgs | null {
-	let json = false;
-	let source: string | undefined;
-	let since: number | undefined;
-	let until: number | undefined;
-	let bucketSizeMs: number | undefined;
-	let bucketCount: number | undefined;
-	let scopeLimit: number | undefined;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!(["--source", "--since", "--until", "--bucket-size-ms", "--bucket-count", "--scope-limit"].includes(argument ?? ""))) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (argument === "--source") { source = raw; continue; }
-		const parsed = Number(raw);
-		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-		if (argument === "--since") since = parsed;
-		else if (argument === "--until") until = parsed;
-		else if (argument === "--bucket-size-ms") { if (parsed < 1) return null; bucketSizeMs = parsed; }
-		else if (argument === "--bucket-count") { if (parsed < 1 || parsed > MAX_USAGE_BUCKETS) return null; bucketCount = parsed; }
-		else { if (parsed < 1 || parsed > USAGE_MAX_DISTINCT_SCOPES) return null; scopeLimit = parsed; }
-	}
-	if (source === undefined || since === undefined || until === undefined || until < since || bucketSizeMs === undefined || bucketCount === undefined) return null;
-	return { input: { source, since, until, bucketSizeMs, bucketCount, ...(scopeLimit === undefined ? {} : { scopeLimit }) }, json };
-}
-
-interface CostByTaskArgs { input: { since: number; until: number }; json: boolean }
-
-function parseCostByTaskArgs(args: string[]): CostByTaskArgs | null {
-	let json = false;
-	let since: number | undefined;
-	let until: number | undefined;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!["--since", "--until"].includes(argument ?? "")) return null;
-		const raw = args[++index];
-		const parsed = Number(raw);
-		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-		if (argument === "--since") since = parsed;
-		else until = parsed;
-	}
-	if (since === undefined || until === undefined || until < since) return null;
-	return { input: { since, until }, json };
-}
-
-interface MetricsPruneArgs { input: { before: number; force?: boolean }; json: boolean }
-
-function parseMetricsPruneArgs(args: string[]): MetricsPruneArgs | null {
-	let json = false;
-	let force = false;
-	let before: number | undefined;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (argument === "--force") { force = true; continue; }
-		if (argument !== "--before") return null;
-		const raw = args[++index];
-		const parsed = Number(raw);
-		if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-		before = parsed;
-	}
-	if (before === undefined) return null;
-	return { input: { before, ...(force ? { force } : {}) }, json };
-}
-
-interface RouterOverrideArgs { input: RouteOverride; json: boolean }
-
-function parseRouterOverrideArgs(args: string[]): RouterOverrideArgs | null {
-	let json = false;
-	let route: Route | null = null;
-	let expiresAt: number | null = null;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (!["--route", "--expires-at"].includes(argument ?? "")) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (argument === "--route") {
-			route = parseRoute(raw);
-			if (!route) return null;
-		} else {
-			const parsed = Number(raw);
-			if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-			expiresAt = parsed;
-		}
-	}
-	if (!route) return null;
-	return { input: { route, expiresAt }, json };
-}
-
-interface RouterRouteArgs { input: Route; json: boolean }
-
-function parseRouterRouteArgs(args: string[]): RouterRouteArgs | null {
-	let json = false;
-	let route: Route | null = null;
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (argument !== "--route") return null;
-		const raw = args[++index];
-		if (raw === undefined) return null;
-		route = parseRoute(raw);
-		if (!route) return null;
-	}
-	if (!route) return null;
-	return { input: route, json };
-}
-
-interface RouterAvailableRoutesArgs { input: { routes: Route[] }; json: boolean }
-
-function parseRouterAvailableRoutesArgs(args: string[]): RouterAvailableRoutesArgs | null {
-	let json = false;
-	const routes: Route[] = [];
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--json") { json = true; continue; }
-		if (argument !== "--route") return null;
-		const raw = args[++index];
-		if (raw === undefined) return null;
-		const route = parseRoute(raw);
-		if (!route) return null;
-		if (routes.length >= CLI_AVAILABLE_ROUTES_MAX) return null;
-		routes.push(route);
-	}
-	return { input: { routes }, json };
-}
-
-function parseJsonOnlyArgs(args: string[]): { json: boolean } | null {
-	let json = false;
-	for (const argument of args) {
-		if (argument !== "--json") return null;
-		json = true;
-	}
-	return { json };
-}
-
-function parseOpArgs(args: string[]): { operation: OperationName; input: Record<string, unknown> } | null {
-	const [operation, ...rest] = args;
-	if (operation === undefined || !EXPECTED_OPERATION_NAMES.includes(operation as OperationName)) return null;
-	let input: Record<string, unknown> = {};
-	for (let index = 0; index < rest.length; index += 1) {
-		if (rest[index] !== "--input") return null;
-		const raw = rest[++index];
-		if (raw === undefined) return null;
-		try {
-			const parsed = JSON.parse(raw);
-			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-			input = parsed as Record<string, unknown>;
-		} catch {
-			return null;
-		}
-	}
-	return { operation: operation as OperationName, input };
-}
-
-interface BenchmarkArgs {
-	action: "status" | "refresh" | "list" | "rank";
-	json: boolean;
-	force: boolean;
-	query?: BenchmarkQuery;
-	recommendation?: ModelRecommendationInput;
-}
-
-function parseCandidate(raw: string): ModelCandidate | null {
-	const separator = raw.indexOf("/");
-	const thinkingSeparator = raw.lastIndexOf("@");
-	if (separator <= 0 || thinkingSeparator <= separator + 1 || thinkingSeparator === raw.length - 1) return null;
-	return { provider: raw.slice(0, separator), model: raw.slice(separator + 1, thinkingSeparator), thinking: raw.slice(thinkingSeparator + 1) };
-}
-
-function parseBenchmarkArgs(action: string | undefined, args: string[]): BenchmarkArgs | null {
-	if (action !== "status" && action !== "refresh" && action !== "list" && action !== "rank") return null;
-	let json = false;
-	let force = false;
-	const query: Partial<BenchmarkQuery> = {};
-	const candidates: ModelCandidate[] = [];
-	const sourceIds: string[] = [];
-	let scopeAuthority: ScopeAuthority = "available-models";
-	let domain: ModelTaskDomain = "general";
-	let type: ModelTaskType = "general";
-	let budgetPressure = 0;
-	const weights: UtilityWeights = {
-		quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT, cost: MODEL_RANKING_DEFAULT_COST_WEIGHT,
-		latency: MODEL_RANKING_DEFAULT_LATENCY_WEIGHT, context: MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT,
-		reliability: MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
-	};
-	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; }
-		const allowed = action === "list" ? ["--source", "--model", "--dimension", "--limit"]
-			: action === "rank" ? ["--candidate", "--source", "--domain", "--type", "--scope", "--budget", "--weight-quality", "--weight-cost", "--weight-latency", "--weight-context", "--weight-reliability"] : [];
-		if (!allowed.includes(argument ?? "")) return null;
-		const raw = args[++index];
-		if (raw === undefined || raw.length === 0) return null;
-		if (action === "list") {
-			if (argument === "--limit") {
-				const limit = Number(raw);
-				if (!Number.isSafeInteger(limit) || limit < 1 || limit > BENCHMARK_MAX_QUERY_LIMIT) return null;
-				query.limit = limit;
-			} else if (argument === "--source") query.sourceId = raw;
-			else if (argument === "--model") query.model = raw;
-			else query.dimension = raw;
-			continue;
-		}
-		if (argument === "--candidate") {
-			const candidate = parseCandidate(raw);
-			if (!candidate) return null;
-			candidates.push(candidate);
-		} else if (argument === "--source") sourceIds.push(raw);
-		else if (argument === "--domain") {
-			if (!TASK_DOMAINS.includes(raw as ModelTaskDomain)) return null;
-			domain = raw as ModelTaskDomain;
-		} else if (argument === "--type") {
-			if (!TASK_TYPES.includes(raw as ModelTaskType)) return null;
-			type = raw as ModelTaskType;
-		} else if (argument === "--scope") {
-			if (raw !== "exact-session" && raw !== "available-models") return null;
-			scopeAuthority = raw;
-		} else if (argument === "--budget") budgetPressure = Number(raw);
-		else {
-			const weight = Number(raw);
-			if (!Number.isFinite(weight) || weight < 0 || weight > 10) return null;
-			weights[argument!.slice("--weight-".length) as keyof UtilityWeights] = weight;
-		}
-	}
-	if (action === "list" && query.sourceId === undefined) return null;
-	if (action === "rank" && (candidates.length === 0 || sourceIds.length > MODEL_RANKING_MAX_SOURCES || !Number.isFinite(budgetPressure) || budgetPressure < 0 || budgetPressure > 2)) return null;
-	return {
-		action, json, force,
-		...(action === "list" ? { query: query as BenchmarkQuery } : {}),
-		...(action === "rank" ? { recommendation: { candidates, sourceIds: [...new Set(sourceIds)], scopeAuthority, domain, type, budgetPressure, weights } } : {}),
-	};
-}
-
-function value(value: number | null, suffix = ""): string {
-	return value === null ? "unknown" : `${Math.round(value).toLocaleString()}${suffix}`;
-}
-
-export function formatBenchmarkStatus(result: BenchmarkRefreshResult): string {
-	if (result.sources.length === 0) return "Benchmark sources: none configured";
-	return ["Benchmark sources:", ...result.sources.map((source) => {
-		const state = source.ok === null ? "not refreshed" : source.ok ? "ready" : "refresh failed";
-		return `- ${source.id}: ${state} · ${source.observations.toLocaleString()} observations · ${source.hasEvidence ? "evidence retained" : "no evidence"}`;
-	})].join("\n");
-}
-
-function humanField(value: string): string {
-	return value.length <= HUMAN_TEXT_FIELD_MAX_CHARACTERS ? value : `${value.slice(0, HUMAN_TEXT_FIELD_MAX_CHARACTERS - 1)}…`;
-}
-
-export function formatBenchmarkQuery(result: BenchmarkQueryResult): string {
-	return [
-		`Benchmark evidence: ${humanField(result.sourceId)} · ${result.completeness} · ${result.freshness} · ${result.observations.length.toLocaleString()} observations`,
-		...result.observations.map((observation) => `- ${humanField(observation.model.canonical)} · ${humanField(observation.dimension)} ${observation.value.toLocaleString()} ${observation.unit} · ${humanField(observation.provenance.publisher)} · confidence ${(observation.provenance.confidence * 100).toFixed(0)}%`),
-	].join("\n");
-}
-
-export function formatModelRanking(result: ModelRankingResult): string {
-	return [
-		`Model ranking: ${result.completeness} · scope ${result.scopeAuthority}${result.scopeWarning ? " · advisory only" : ""}`,
-		...result.ranked.map((item, index) => `${index + 1}. ${humanField(item.identity)} · utility ${item.utility === null ? "unknown" : item.utility.toFixed(3)} · confidence ${(item.confidence * 100).toFixed(0)}%`),
-		...(result.scopeWarning ? [result.scopeWarning] : []),
-	].join("\n");
-}
-
-export function formatContextAssessment(summary: ContextAssessment): string {
-	return [
-		`Context assessment: ${summary.completeness}`,
-		`Papyrus injection: ${summary.injection.runs} runs · avg ${value(summary.injection.averageCharacters, " chars")} · p95 ${value(summary.injection.p95Characters, " chars")} · max ${value(summary.injection.maxCharacters, " chars")}`,
-		`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")}`,
-		`Reasons: threshold ${summary.compaction.reasons.threshold} · overflow ${summary.compaction.reasons.overflow} · manual ${summary.compaction.reasons.manual}`,
-	].join("\n");
-}
-
-function formatRoute(route: Route): string {
-	return `${humanField(route.provider)}/${humanField(route.model)} · ${humanField(route.thinking)}`;
-}
-
-export function formatMetricsQuery(rows: StoredMetricObservation[]): string {
-	if (rows.length === 0) return "Metrics: no observations matched";
-	const shown = rows.slice(0, CLI_METRICS_HUMAN_MAX_ROWS);
-	const lines = [
-		`Metrics: ${rows.length.toLocaleString()} observation(s)${rows.length > shown.length ? ` (showing first ${shown.length})` : ""}`,
-		...shown.map((row) => `- ${humanField(row.source)}/${humanField(row.scope)}/${humanField(row.metric)} = ${row.value === null ? "null" : row.value} ${row.unit} @ ${new Date(row.observedAt).toISOString()}`),
-	];
-	return lines.join("\n");
-}
-
-export function formatMetricsDistinctScopes(scopes: string[]): string {
-	if (scopes.length === 0) return "Scopes: none matched";
-	return [`Scopes: ${scopes.length.toLocaleString()}`, ...scopes.map((scope) => `- ${humanField(scope)}`)].join("\n");
-}
-
-export function formatMetricsUsageSeries(result: { rows: Array<{ scope: string; metric: string; bucketIndex: number; sum: number }>; truncated: boolean }): string {
-	if (result.rows.length === 0) return `Usage series: no data${result.truncated ? " (scope limit reached)" : ""}`;
-	const lines = [`Usage series: ${result.rows.length.toLocaleString()} bucket(s)${result.truncated ? " (scope limit reached)" : ""}`];
-	for (const row of result.rows) lines.push(`- ${humanField(row.scope)}/${humanField(row.metric)} bucket ${row.bucketIndex}: ${row.sum.toLocaleString()}`);
-	return lines.join("\n");
-}
-
-function formatUsdAmount(amount: number): string {
-	return `$${amount.toFixed(Math.abs(amount) < 0.01 && amount !== 0 ? 4 : 2)}`;
-}
-
-export function formatCostByTask(summary: TaskCostSummary): string {
-	const lines = [
-		`Cost by task: ${summary.entries.length.toLocaleString()} task(s)${summary.truncated ? " (query limit reached; totals are a lower bound)" : ""}`,
-		...summary.entries.flatMap((entry) => [
-			`- ${humanField(entry.taskId)}: ${formatUsdAmount(entry.costUsd)} · ↑${entry.inputTokens.toLocaleString()} ↓${entry.outputTokens.toLocaleString()} R${entry.cacheReadTokens.toLocaleString()} W${entry.cacheWriteTokens.toLocaleString()}`,
-			...entry.byModel.map((model) => `    · ${humanField(model.provider)}/${humanField(model.model)} (${humanField(model.thinking)}): ${formatUsdAmount(model.costUsd)} · ↑${model.inputTokens.toLocaleString()} ↓${model.outputTokens.toLocaleString()} R${model.cacheReadTokens.toLocaleString()} W${model.cacheWriteTokens.toLocaleString()}`),
-		]),
-		`Unattributed spend (no task was focused): ${formatUsdAmount(summary.unattributedCostUsd)}`,
-	];
-	return lines.join("\n");
-}
-
-export function formatTelemetryPoll(result: TelemetryPollResult): string {
-	if (result.sources.length === 0) return "Telemetry: no sources configured";
-	return ["Telemetry:", ...result.sources.map((source) => {
-		const freshness = !source.ok ? `failed${source.error ? ` (${humanField(source.error)})` : ""}` : "ok";
-		return `- ${humanField(source.id)} (${humanField(source.provider)}): ${freshness} · ${source.metrics} metric(s)`;
-	})].join("\n");
-}
-
-export function formatRouterStatus(status: RouterStatus): string {
-	const lines = [
-		`Router: ${status.ready ? "ready" : "not ready"}${status.paused ? " · paused" : ""}`,
-		`Current route: ${status.currentRoute ? formatRoute(status.currentRoute) : "none"}`,
-		`Available routes: ${status.availableRoutes.length.toLocaleString()}`,
-		`Override: ${status.override ? `${formatRoute(status.override.route)}${status.override.expiresAt === null ? "" : ` (expires ${new Date(status.override.expiresAt).toISOString()})`}` : "none"}`,
-	];
-	if (status.lastDecision) lines.push(`Last decision: ${status.lastDecision.action} · pressure ${Number.isFinite(status.lastDecision.pressure) ? status.lastDecision.pressure.toFixed(3) : "∞"} · ${humanField(status.lastDecision.reason)}`);
-	lines.push(formatTelemetryPoll({ sources: status.sources, observedAt: Date.now() }));
-	return lines.join("\n");
-}
-
-export function formatCompactionEstimate(estimate: CompactionDurationEstimate): string {
-	if (estimate.confidence === "cold-start" || estimate.ms === null) {
-		return `Compaction duration: cold-start (${estimate.sampleSize.toLocaleString()} sample(s), not enough evidence yet)`;
-	}
-	return `Compaction duration: ~${estimate.ms.toLocaleString()}ms learned from ${estimate.sampleSize.toLocaleString()} sample(s)`;
-}
-
-export function formatPolicyDecision(decision: PolicyDecision): string {
-	const lines = [`Decision: ${decision.action} · pressure ${Number.isFinite(decision.pressure) ? decision.pressure.toFixed(3) : "∞"} · ${humanField(decision.reason)}`];
-	if (decision.route) lines.push(`Route: ${formatRoute(decision.route)}`);
-	if (decision.delayMs !== undefined) lines.push(`Delay: ${decision.delayMs}ms`);
-	return lines.join("\n");
-}
-
-async function callAndPrint<Name extends OperationName>(
-	deps: CliDependencies,
-	operation: Name,
-	input: OperationInputs[Name],
-	json: boolean,
-	formatHuman: (result: OperationOutputs[Name]) => string,
-): Promise<number> {
-	try {
-		const result = await deps.client.call(operation, input);
-		deps.stdout(json ? JSON.stringify(result) : formatHuman(result));
-		return 0;
-	} catch (error) {
-		deps.stderr(error instanceof Error ? error.message : String(error));
-		return 1;
-	}
-}
-
+/**
+ * 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.
+ */
 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") { deps.serve(); return 0; }
-	if (command === "metrics") {
-		if (action === "record") {
-			const parsed = parseMetricsRecordArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.record", parsed.input, parsed.json, (row) => formatMetricsQuery([row]));
-		}
-		if (action === "query") {
-			const parsed = parseMetricsQueryArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.query", parsed.input, parsed.json, formatMetricsQuery);
-		}
-		if (action === "prune") {
-			const parsed = parseMetricsPruneArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.prune", parsed.input, parsed.json, (result) => `Pruned ${result.deleted.toLocaleString()} observation(s)`);
-		}
-		if (action === "distinct-scopes") {
-			const parsed = parseMetricsDistinctScopesArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.distinct_scopes", parsed.input, parsed.json, formatMetricsDistinctScopes);
-		}
-		if (action === "usage-series") {
-			const parsed = parseMetricsUsageSeriesArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.usage_series", parsed.input, parsed.json, formatMetricsUsageSeries);
-		}
-		if (action === "cost-by-task") {
-			const parsed = parseCostByTaskArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "metrics.cost_by_task", parsed.input, parsed.json, formatCostByTask);
-		}
-		return usage(deps.stderr);
-	}
-	if (command === "telemetry") {
-		if (action !== "poll") return usage(deps.stderr);
-		const parsed = parseJsonOnlyArgs(rest);
-		if (!parsed) return usage(deps.stderr);
-		return callAndPrint(deps, "telemetry.poll", {}, parsed.json, formatTelemetryPoll);
-	}
-	if (command === "compaction") {
-		if (action !== "estimate") return usage(deps.stderr);
-		const parsed = parseJsonOnlyArgs(rest);
-		if (!parsed) return usage(deps.stderr);
-		return callAndPrint(deps, "compaction.estimate", {}, parsed.json, formatCompactionEstimate);
-	}
-	if (command === "router") {
-		switch (action) {
-			case "status": {
-				const parsed = parseJsonOnlyArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.status", {}, parsed.json, formatRouterStatus);
-			}
-			case "decide": {
-				const parsed = parseJsonOnlyArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.decide", {}, parsed.json, formatPolicyDecision);
-			}
-			case "pause": {
-				const parsed = parseJsonOnlyArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.pause", {}, parsed.json, formatRouterStatus);
-			}
-			case "resume": {
-				const parsed = parseJsonOnlyArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.resume", {}, parsed.json, formatRouterStatus);
-			}
-			case "clear-override": {
-				const parsed = parseJsonOnlyArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.clear_override", {}, parsed.json, formatRouterStatus);
-			}
-			case "override": {
-				const parsed = parseRouterOverrideArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.override", parsed.input, parsed.json, formatRouterStatus);
-			}
-			case "current-route": {
-				const parsed = parseRouterRouteArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.current_route", parsed.input, parsed.json, formatRouterStatus);
-			}
-			case "available-routes": {
-				const parsed = parseRouterAvailableRoutesArgs(rest);
-				if (!parsed) return usage(deps.stderr);
-				return callAndPrint(deps, "router.available_routes", parsed.input, parsed.json, formatRouterStatus);
-			}
-			default: return usage(deps.stderr);
-		}
-	}
-	if (command === "op") {
-		const parsed = parseOpArgs(action === undefined ? [] : [action, ...rest]);
-		if (!parsed) return usage(deps.stderr);
-		try {
-			// The escape hatch dispatches a dynamically named operation; OperationInputs/OperationOutputs
-			// are only known statically per literal operation name, so this one call site is intentionally
-			// untyped at the boundary. parseOpArgs already restricts `operation` to EXPECTED_OPERATION_NAMES.
-			const call = deps.client.call as (operation: OperationName, input: Record<string, unknown>) => Promise<unknown>;
-			const result = await call(parsed.operation, parsed.input);
-			deps.stdout(JSON.stringify(result));
-			return 0;
-		} catch (error) {
-			deps.stderr(error instanceof Error ? error.message : String(error));
-			return 1;
-		}
-	}
-	if (command === "benchmarks") {
-		const parsed = parseBenchmarkArgs(action, rest);
-		if (!parsed) return usage(deps.stderr);
-		try {
-			if (parsed.action === "list") {
-				const result = await deps.client.call("benchmark.query", parsed.query!);
-				deps.stdout(parsed.json ? JSON.stringify(result) : formatBenchmarkQuery(result));
-			} else if (parsed.action === "rank") {
-				const result = await deps.client.call("models.rank", parsed.recommendation!);
-				deps.stdout(parsed.json ? JSON.stringify(result) : formatModelRanking(result));
-			} else {
-				const result = parsed.action === "refresh"
-					? await deps.client.call("benchmark.refresh", { force: parsed.force })
-					: await deps.client.call("benchmark.status", {});
-				deps.stdout(parsed.json ? JSON.stringify(result) : formatBenchmarkStatus(result));
-			}
-			return 0;
-		} catch (error) {
-			deps.stderr(error instanceof Error ? error.message : String(error));
-			return 1;
-		}
-	}
-	if (command === "context") {
-		const parsed = parseContextArgs([...(action === undefined ? [] : [action]), ...rest]);
-		if (!parsed) return usage(deps.stderr);
-		try {
-			const summary = await deps.client.call("context.assess", parsed.input);
-			deps.stdout(parsed.json ? JSON.stringify(summary) : formatContextAssessment(summary));
-			return 0;
-		} catch (error) {
-			deps.stderr(error instanceof Error ? error.message : String(error));
-			return 1;
-		}
-	}
-	if (command !== "service") return usage(deps.stderr);
-	switch (action) {
-		case "install": deps.installService(); return 0;
-		case "start": deps.systemctl("start", SYSTEMD_UNIT_NAME); return 0;
-		case "stop": deps.systemctl("stop", SYSTEMD_UNIT_NAME); return 0;
-		case "restart": deps.systemctl("restart", SYSTEMD_UNIT_NAME); return 0;
-		case "status": deps.systemctl("status", SYSTEMD_UNIT_NAME); return 0;
-		case "checkpoint": {
-			const parsed = parseJsonOnlyArgs(rest);
-			if (!parsed) return usage(deps.stderr);
-			return callAndPrint(deps, "service.checkpoint", {}, parsed.json, () => "Checkpoint complete");
-		}
-		default: return usage(deps.stderr);
-	}
+	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> {