@danypops/jittor 0.10.0 → 0.12.0

package/src/cli-commands/metrics.ts

@@ -0,0 +1,296 @@
+import { CLI_METRICS_HUMAN_MAX_ROWS, MAX_QUERY_LIMIT, MAX_USAGE_BUCKETS, 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 { callAndPrint, humanField, type CliDependencies } from "./support.ts";
+
+export const METRICS_USAGE_LINES = [
+	"  metrics record --source <s> --scope <s> --metric <s> --value <number|null> --unit <unit> [--observed-at <ms>] [--attributes <json>] [--json]",
+	`  metrics record-batch --observations <json-array, max ${METRIC_BATCH_MAX_OBSERVATIONS}> [--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]",
+];
+
+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 MetricsRecordBatchArgs { input: { observations: MetricObservation[] }; json: boolean }
+
+function parseMetricsRecordBatchArgs(args: string[]): MetricsRecordBatchArgs | null {
+	let json = false;
+	let observations: unknown;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument !== "--observations") return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		try {
+			observations = JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	}
+	if (!Array.isArray(observations) || observations.length === 0 || observations.length > METRIC_BATCH_MAX_OBSERVATIONS) return null;
+	return { input: { observations: observations as MetricObservation[] }, json };
+}
+
+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 };
+}
+
+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 async function runMetricsCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	if (action === "record") {
+		const parsed = parseMetricsRecordArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.record", parsed.input, parsed.json, (row) => formatMetricsQuery([row]));
+	}
+	if (action === "record-batch") {
+		const parsed = parseMetricsRecordBatchArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.record_batch", parsed.input, parsed.json, formatMetricsQuery);
+	}
+	if (action === "query") {
+		const parsed = parseMetricsQueryArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.query", parsed.input, parsed.json, formatMetricsQuery);
+	}
+	if (action === "prune") {
+		const parsed = parseMetricsPruneArgs(rest);
+		if (!parsed) return usage();
+		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();
+		return callAndPrint(deps, "metrics.distinct_scopes", parsed.input, parsed.json, formatMetricsDistinctScopes);
+	}
+	if (action === "usage-series") {
+		const parsed = parseMetricsUsageSeriesArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.usage_series", parsed.input, parsed.json, formatMetricsUsageSeries);
+	}
+	if (action === "cost-by-task") {
+		const parsed = parseCostByTaskArgs(rest);
+		if (!parsed) return usage();
+		return callAndPrint(deps, "metrics.cost_by_task", parsed.input, parsed.json, formatCostByTask);
+	}
+	return usage();
+}

package/src/cli-commands/op.ts

@@ -0,0 +1,40 @@
+import { EXPECTED_OPERATION_NAMES, type OperationName } from "../service.ts";
+import type { CliDependencies } from "./support.ts";
+
+export const OP_USAGE_LINES = ["  op <operation> [--input <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 };
+}
+
+export async function runOpCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	const parsed = parseOpArgs(action === undefined ? [] : [action, ...rest]);
+	if (!parsed) return usage();
+	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;
+	}
+}

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

@@ -0,0 +1,15 @@
+import type { ModelCandidate } from "../domain/model-ranking.ts";
+import type { Route } from "../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 {
+	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) };
+}
+
+export function parseRoute(raw: string | undefined): Route | null {
+	if (raw === undefined) return null;
+	return parseCandidate(raw);
+}

package/src/cli-commands/router.ts

@@ -0,0 +1,207 @@
+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 { callAndPrint, humanField, type CliDependencies } from "./support.ts";
+import { parseRoute } from "./route-args.ts";
+
+export const ROUTER_USAGE_LINES = [
+	"  telemetry poll [--json]",
+	"  compaction estimate [--json]",
+	"  router <status|decide|pause|resume|clear-override> [--session-id <id>] [--session-secret <secret>] [--json]",
+	"  router override --route <provider/model@thinking> [--expires-at <ms>] [--session-id <id>] [--session-secret <secret>] [--json]",
+	"  router current-route --route <provider/model@thinking> [--session-id <id>] [--session-secret <secret>] [--json]",
+	"  router available-routes [--route <provider/model@thinking> ...] [--session-id <id>] [--session-secret <secret>] [--json]",
+];
+
+interface SessionScope { session_id?: string; session_secret?: string }
+
+function sessionScopeInput(sessionId: string | undefined, sessionSecret: string | undefined): SessionScope {
+	return { ...(sessionId ? { session_id: sessionId } : {}), ...(sessionSecret ? { session_secret: sessionSecret } : {}) };
+}
+
+interface RouterOverrideArgs { input: RouteOverride & SessionScope; json: boolean }
+
+function parseRouterOverrideArgs(args: string[]): RouterOverrideArgs | null {
+	let json = false;
+	let route: Route | null = null;
+	let expiresAt: number | null = null;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--route", "--expires-at", "--session-id", "--session-secret"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--session-id") sessionId = raw;
+		else if (argument === "--session-secret") sessionSecret = raw;
+		else 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, ...sessionScopeInput(sessionId, sessionSecret) }, json };
+}
+
+interface RouterRouteArgs { input: Route & SessionScope; json: boolean }
+
+function parseRouterRouteArgs(args: string[]): RouterRouteArgs | null {
+	let json = false;
+	let route: Route | null = null;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--route", "--session-id", "--session-secret"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--session-id") sessionId = raw;
+		else if (argument === "--session-secret") sessionSecret = raw;
+		else {
+			route = parseRoute(raw);
+			if (!route) return null;
+		}
+	}
+	if (!route) return null;
+	return { input: { ...route, ...sessionScopeInput(sessionId, sessionSecret) }, json };
+}
+
+interface RouterAvailableRoutesArgs { input: { routes: Route[] } & SessionScope; json: boolean }
+
+function parseRouterAvailableRoutesArgs(args: string[]): RouterAvailableRoutesArgs | null {
+	let json = false;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	const routes: Route[] = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--route", "--session-id", "--session-secret"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--session-id") sessionId = raw;
+		else if (argument === "--session-secret") sessionSecret = raw;
+		else {
+			const route = parseRoute(raw);
+			if (!route) return null;
+			if (routes.length >= CLI_AVAILABLE_ROUTES_MAX) return null;
+			routes.push(route);
+		}
+	}
+	return { input: { routes, ...sessionScopeInput(sessionId, sessionSecret) }, json };
+}
+
+function parseRouterScopeArgs(args: string[]): { input: SessionScope; json: boolean } | null {
+	let json = false;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--session-id", "--session-secret"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--session-id") sessionId = raw;
+		else sessionSecret = raw;
+	}
+	return { input: sessionScopeInput(sessionId, sessionSecret), json };
+}
+
+export 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 formatRoute(route: Route): string {
+	return `${humanField(route.provider)}/${humanField(route.model)} · ${humanField(route.thinking)}`;
+}
+
+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 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");
+}
+
+export async function runTelemetryCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	if (action !== "poll") return usage();
+	const parsed = parseJsonOnlyArgs(rest);
+	if (!parsed) return usage();
+	return callAndPrint(deps, "telemetry.poll", {}, parsed.json, formatTelemetryPoll);
+}
+
+export async function runRouterCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	switch (action) {
+		case "status": {
+			const parsed = parseRouterScopeArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.status", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "decide": {
+			const parsed = parseRouterScopeArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.decide", parsed.input, parsed.json, formatPolicyDecision);
+		}
+		case "pause": {
+			const parsed = parseRouterScopeArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.pause", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "resume": {
+			const parsed = parseRouterScopeArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.resume", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "clear-override": {
+			const parsed = parseRouterScopeArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.clear_override", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "override": {
+			const parsed = parseRouterOverrideArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.override", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "current-route": {
+			const parsed = parseRouterRouteArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.current_route", parsed.input, parsed.json, formatRouterStatus);
+		}
+		case "available-routes": {
+			const parsed = parseRouterAvailableRoutesArgs(rest);
+			if (!parsed) return usage();
+			return callAndPrint(deps, "router.available_routes", parsed.input, parsed.json, formatRouterStatus);
+		}
+		default: return usage();
+	}
+}

package/src/cli-commands/service-daemon.ts

@@ -0,0 +1,72 @@
+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 { SYSTEMD_UNIT_NAME } from "../constants.ts";
+import { resolveJittorPaths } from "../state.ts";
+import { callAndPrint, type CliDependencies } from "./support.ts";
+import { parseJsonOnlyArgs } from "./router.ts";
+
+export const SERVICE_USAGE_LINES = ["  service <install|start|stop|restart|status|checkpoint>"];
+
+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 function systemctl(...args: string[]): void {
+	execFileSync("systemctl", ["--user", ...args], { stdio: "inherit" });
+}
+
+/** cliPath is the caller's own entrypoint file -- resolved from the real CLI script's `import.meta.url`, never this module's own, so the installed unit's ExecStart always points at the actual runnable CLI. */
+export function installService(cliPath: string): 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,
+		...(existsSync(codexAuthFile) ? { codexAuthFile } : {}),
+		openRouterBenchmarks: process.env["JITTOR_OPENROUTER_BENCHMARKS"] === "1",
+	}));
+	systemctl("daemon-reload");
+	systemctl("enable", SYSTEMD_UNIT_NAME);
+	systemctl("restart", SYSTEMD_UNIT_NAME);
+}
+
+export async function runServiceCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	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();
+			return callAndPrint(deps, "service.checkpoint", {}, parsed.json, () => "Checkpoint complete");
+		}
+		default: return usage();
+	}
+}

package/src/cli-commands/session.ts

@@ -0,0 +1,42 @@
+import { callAndPrint, humanField, type CliDependencies } from "./support.ts";
+
+export const SESSION_USAGE_LINES = [
+	"  session register --session-id <id> [--json]",
+	"  session release --session-id <id> [--session-secret <secret>] [--json]",
+];
+
+interface SessionArgs { input: { session_id: string; session_secret?: string }; json: boolean }
+
+function parseSessionArgs(args: string[]): SessionArgs | null {
+	let json = false;
+	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (!["--session-id", "--session-secret"].includes(argument ?? "")) return null;
+		const raw = args[++index];
+		if (raw === undefined || raw.length === 0) return null;
+		if (argument === "--session-id") sessionId = raw;
+		else sessionSecret = raw;
+	}
+	if (sessionId === undefined) return null;
+	return { input: { session_id: sessionId, ...(sessionSecret ? { session_secret: sessionSecret } : {}) }, json };
+}
+
+export function formatSessionRegistration(result: { sessionId: string; secret: string }): string {
+	return `Session registered: ${humanField(result.sessionId)} · secret ${humanField(result.secret)} (shown once; keep it to mutate this session's router state)`;
+}
+
+export function formatSessionRelease(result: { released: boolean }): string {
+	return result.released ? "Session released" : "Session was not registered, or the secret did not match";
+}
+
+export async function runSessionCommand(action: string | undefined, rest: string[], deps: CliDependencies, usage: () => number): Promise<number> {
+	if (action !== "register" && action !== "release") return usage();
+	const parsed = parseSessionArgs(rest);
+	if (!parsed) return usage();
+	return action === "register"
+		? callAndPrint(deps, "session.register", parsed.input, parsed.json, formatSessionRegistration)
+		: callAndPrint(deps, "session.release", parsed.input, parsed.json, formatSessionRelease);
+}