@danypops/jittor 0.9.0 → 0.11.0

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

package/src/cli-commands/support.ts

@@ -0,0 +1,33 @@
+import { HUMAN_TEXT_FIELD_MAX_CHARACTERS } from "../constants.ts";
+import type { JittorClient } from "../client.ts";
+import type { OperationInputs, OperationName, OperationOutputs } from "../service.ts";
+
+export interface CliDependencies {
+	client: Pick<JittorClient, "call">;
+	stdout(line: string): void;
+	stderr(line: string): void;
+	systemctl(...args: string[]): void;
+	installService(): void;
+	serve(): void;
+}
+
+export function humanField(value: string): string {
+	return value.length <= HUMAN_TEXT_FIELD_MAX_CHARACTERS ? value : `${value.slice(0, HUMAN_TEXT_FIELD_MAX_CHARACTERS - 1)}…`;
+}
+
+export 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;
+	}
+}