@danypops/jittor 0.1.0

package/src/daemon.ts

@@ -0,0 +1,88 @@
+import { LOOPBACK_HOST, MAINTENANCE_INTERVAL_MS, TELEMETRY_POLL_INTERVAL_MS } from "./constants.ts";
+import { DEFAULT_POLICY, UNCONFIGURED_ROUTE } from "./config.ts";
+import { SQLiteMetricStore } from "./adapters/sqlite-metric-store.ts";
+import { openJittorDb } from "./db.ts";
+import { createApp, JittorService } from "./service.ts";
+import { JittorRouter } from "./router.ts";
+import type { TelemetrySource } from "./ports/telemetry-source.ts";
+import { CodexTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
+import {
+	ensureAuthToken,
+	removeDaemonHandle,
+	resolveJittorPaths,
+	writeDaemonHandle,
+	type JittorPaths,
+} from "./state.ts";
+
+export interface RunningDaemon {
+	host: typeof LOOPBACK_HOST;
+	port: number;
+	stop(): Promise<void>;
+}
+
+export function telemetrySourcesFromEnvironment(env: Record<string, string | undefined> = process.env): TelemetrySource[] {
+	const sources: TelemetrySource[] = [];
+	const codexAuthFile = env["JITTOR_CODEX_AUTH_FILE"];
+	if (codexAuthFile) sources.push(new CodexTelemetrySource(codexAuthFile));
+	const openRouterKey = env["OPENROUTER_API_KEY"];
+	if (openRouterKey) sources.push(new OpenRouterTelemetrySource(openRouterKey));
+	return sources;
+}
+
+export function startDaemon(
+	paths: JittorPaths = resolveJittorPaths(),
+	env: Record<string, string | undefined> = process.env,
+): RunningDaemon {
+	const token = ensureAuthToken(paths);
+	const metrics = new SQLiteMetricStore(openJittorDb(paths.database));
+	const sources = telemetrySourcesFromEnvironment(env);
+	const router = new JittorRouter({
+		metrics,
+		sources,
+		policy: DEFAULT_POLICY,
+		routes: [],
+		currentRoute: UNCONFIGURED_ROUTE,
+	});
+	const service = new JittorService(metrics, router);
+	const app = createApp({ service, token });
+	const server = Bun.serve({
+		hostname: LOOPBACK_HOST,
+		port: 0,
+		fetch: (request) => app.fetch(request),
+	});
+	const port = server.port;
+	if (port === undefined) {
+		server.stop(true);
+		service.close();
+		throw new Error("Jittor daemon failed to bind a loopback port");
+	}
+	writeDaemonHandle(paths, { host: LOOPBACK_HOST, port, pid: process.pid });
+	const maintenance = setInterval(() => { void service.execute("service.checkpoint", {}); }, MAINTENANCE_INTERVAL_MS);
+	const poll = setInterval(() => { void router.poll(); }, TELEMETRY_POLL_INTERVAL_MS);
+	if (sources.length > 0) void router.poll();
+	let stopped = false;
+	return {
+		host: LOOPBACK_HOST,
+		port,
+		async stop(): Promise<void> {
+			if (stopped) return;
+			stopped = true;
+			clearInterval(maintenance);
+			clearInterval(poll);
+			await server.stop(true);
+			service.close();
+			removeDaemonHandle(paths);
+		},
+	};
+}
+
+export function serveMain(): void {
+	const daemon = startDaemon();
+	console.error(`[jittor] listening on ${daemon.host}:${daemon.port}`);
+	const stop = async (): Promise<void> => {
+		await daemon.stop();
+		process.exit(0);
+	};
+	process.once("SIGTERM", stop);
+	process.once("SIGINT", stop);
+}

package/src/db.ts

@@ -0,0 +1,50 @@
+import { Database } from "bun:sqlite";
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
+
+const INITIAL_SCHEMA = `
+CREATE TABLE metric_observations (
+	id          INTEGER PRIMARY KEY AUTOINCREMENT,
+	source      TEXT NOT NULL,
+	scope       TEXT NOT NULL,
+	metric      TEXT NOT NULL,
+	value       REAL,
+	unit        TEXT NOT NULL,
+	observed_at INTEGER NOT NULL CHECK(observed_at >= 0),
+	attributes  TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(attributes))
+);
+CREATE INDEX metric_observations_series_time_idx
+	ON metric_observations(source, scope, metric, observed_at);
+CREATE INDEX metric_observations_time_idx
+	ON metric_observations(observed_at);
+`;
+
+function migrate(db: Database): void {
+	const row = db.query("PRAGMA user_version").get() as { user_version: number };
+	if (row.user_version > SQLITE_SCHEMA_VERSION) {
+		throw new Error(`database schema ${row.user_version} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
+	}
+	if (row.user_version < 1) {
+		const migration = db.transaction(() => {
+			db.exec(INITIAL_SCHEMA);
+			db.exec("PRAGMA user_version = 1");
+		});
+		migration.immediate();
+	}
+	const migrated = db.query("PRAGMA user_version").get() as { user_version: number };
+	if (migrated.user_version !== SQLITE_SCHEMA_VERSION) {
+		throw new Error(`missing migration from schema ${migrated.user_version} to ${SQLITE_SCHEMA_VERSION}`);
+	}
+}
+
+export function openJittorDb(path: string): Database {
+	if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+	const db = new Database(path, { create: true, strict: true });
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
+	migrate(db);
+	db.exec("PRAGMA optimize=0x10002");
+	return db;
+}

package/src/domain/metric.ts

@@ -0,0 +1,54 @@
+export const METRIC_UNITS = ["ratio", "usd", "tokens", "requests", "milliseconds", "count"] as const;
+export type MetricUnit = typeof METRIC_UNITS[number];
+
+export interface MetricObservation {
+	source: string;
+	scope: string;
+	metric: string;
+	value: number | null;
+	unit: MetricUnit;
+	observedAt: number;
+	attributes?: Record<string, unknown>;
+}
+
+export interface StoredMetricObservation extends MetricObservation {
+	id: number;
+	attributes: Record<string, unknown>;
+}
+
+export interface MetricQuery {
+	source?: string;
+	scope?: string;
+	metric?: string;
+	since?: number;
+	until?: number;
+	limit?: number;
+	order?: "asc" | "desc";
+}
+
+export function validateMetricObservation(value: unknown): MetricObservation {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("metric observation must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of ["source", "scope", "metric", "unit"] as const) {
+		if (typeof input[key] !== "string" || input[key].trim().length === 0) throw new Error(`${key} is required`);
+	}
+	if (!METRIC_UNITS.includes(input["unit"] as MetricUnit)) throw new Error("unit is not supported");
+	if (input["value"] !== null && (typeof input["value"] !== "number" || !Number.isFinite(input["value"]))) {
+		throw new Error("value must be finite or null");
+	}
+	if (typeof input["observedAt"] !== "number" || !Number.isSafeInteger(input["observedAt"]) || input["observedAt"] < 0) {
+		throw new Error("observedAt must be a non-negative integer timestamp");
+	}
+	if (input["attributes"] !== undefined && (typeof input["attributes"] !== "object" || input["attributes"] === null || Array.isArray(input["attributes"]))) {
+		throw new Error("attributes must be an object");
+	}
+	return {
+		source: input["source"] as string,
+		scope: input["scope"] as string,
+		metric: input["metric"] as string,
+		value: input["value"] as number | null,
+		unit: input["unit"] as MetricUnit,
+		observedAt: input["observedAt"] as number,
+		attributes: (input["attributes"] as Record<string, unknown> | undefined) ?? {},
+	};
+}

package/src/domain/usage.ts

@@ -0,0 +1,112 @@
+import type { StoredMetricObservation } from "./metric.ts";
+
+export const USAGE_RANGES = ["24h", "7d", "30d", "90d"] as const;
+export type UsageRange = typeof USAGE_RANGES[number];
+
+export interface UsageSeries {
+	key: string;
+	provider: string;
+	model: string;
+	total: number;
+}
+
+export interface UsageBucket {
+	start: number;
+	end: number;
+	total: number;
+	series: Record<string, number>;
+}
+
+export interface UsageBreakdown {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+export interface UsageHistogram {
+	range: UsageRange;
+	start: number;
+	end: number;
+	buckets: UsageBucket[];
+	series: UsageSeries[];
+	totalTokens: number;
+	breakdown: UsageBreakdown;
+}
+
+export interface UsageHistogramOptions {
+	range: UsageRange;
+	now: number;
+	bucketCount?: number;
+}
+
+const RANGE_MILLISECONDS: Record<UsageRange, number> = {
+	"24h": 24 * 60 * 60 * 1_000,
+	"7d": 7 * 24 * 60 * 60 * 1_000,
+	"30d": 30 * 24 * 60 * 60 * 1_000,
+	"90d": 90 * 24 * 60 * 60 * 1_000,
+};
+
+const DEFAULT_BUCKETS: Record<UsageRange, number> = { "24h": 24, "7d": 28, "30d": 30, "90d": 30 };
+
+const BREAKDOWN_KEYS = {
+	"input-tokens": "input",
+	"output-tokens": "output",
+	"cache-read-tokens": "cacheRead",
+	"cache-write-tokens": "cacheWrite",
+} as const satisfies Record<string, keyof UsageBreakdown>;
+
+export function usageRangeStart(range: UsageRange, now: number): number {
+	return Math.max(0, now - RANGE_MILLISECONDS[range]);
+}
+
+function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
+	const separator = row.scope.indexOf(":");
+	const fallbackProvider = separator >= 0 ? row.scope.slice(0, separator) : row.scope;
+	const fallbackModel = separator >= 0 ? row.scope.slice(separator + 1) : "unknown";
+	const provider = typeof row.attributes["provider"] === "string" ? row.attributes["provider"] : fallbackProvider;
+	const model = typeof row.attributes["model"] === "string" ? row.attributes["model"] : fallbackModel;
+	return { key: `${provider}/${model}`, provider, model };
+}
+
+export function buildUsageHistogram(rows: StoredMetricObservation[], options: UsageHistogramOptions): UsageHistogram {
+	const end = options.now;
+	const start = usageRangeStart(options.range, end);
+	const requestedBuckets = options.bucketCount ?? DEFAULT_BUCKETS[options.range];
+	const bucketCount = Math.max(1, Math.min(120, Math.floor(requestedBuckets)));
+	const bucketSize = Math.max(1, (end - start) / bucketCount);
+	const buckets: UsageBucket[] = Array.from({ length: bucketCount }, (_, index) => ({
+		start: start + index * bucketSize,
+		end: index === bucketCount - 1 ? end : start + (index + 1) * bucketSize,
+		total: 0,
+		series: {},
+	}));
+	const breakdown: UsageBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+	const identities = new Map<string, UsageSeries>();
+
+	for (const row of rows) {
+		const breakdownKey = BREAKDOWN_KEYS[row.metric as keyof typeof BREAKDOWN_KEYS];
+		if (row.source !== "pi" || row.unit !== "tokens" || !breakdownKey || typeof row.value !== "number" || row.value < 0) continue;
+		if (row.observedAt < start || row.observedAt > end) continue;
+		const bucketIndex = Math.min(bucketCount - 1, Math.floor((row.observedAt - start) / bucketSize));
+		const bucket = buckets[bucketIndex]!;
+		const series = identity(row);
+		bucket.total += row.value;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
+		breakdown[breakdownKey] += row.value;
+		const current = identities.get(series.key) ?? { ...series, total: 0 };
+		current.total += row.value;
+		identities.set(series.key, current);
+	}
+
+	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
+	return {
+		range: options.range,
+		start,
+		end,
+		buckets,
+		series,
+		totalTokens: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
+		breakdown,
+	};
+}

package/src/policy.ts

@@ -0,0 +1,220 @@
+export type PolicyAction = "continue" | "throttle" | "lower-thinking" | "switch-model" | "switch-provider" | "halt";
+export type TelemetryFreshness = "fresh" | "stale" | "failed";
+
+export interface BudgetWindow {
+	id: string;
+	source: string;
+	scope: string;
+	usedFraction: number;
+	windowSeconds: number;
+	resetsAt: number;
+	observedAt: number;
+	freshness: TelemetryFreshness;
+	confidence: number;
+	observedBurnPerSecond?: number;
+}
+
+export interface Route {
+	provider: string;
+	model: string;
+	thinking: string;
+}
+
+export interface PolicyThresholds {
+	throttle: number;
+	lowerThinking: number;
+	switchModel: number;
+	switchProvider: number;
+	halt: number;
+}
+
+export interface PolicyConfig {
+	maxTelemetryAgeMs: number;
+	cooldownMs: number;
+	hysteresisFraction: number;
+	thresholds: PolicyThresholds;
+	maxThrottleMs: number;
+	hardStopUsedFraction: number;
+	minimumConfidence?: number;
+}
+
+export interface PreviousDecision {
+	action: PolicyAction;
+	decidedAt: number;
+	pressure: number;
+	route?: Route;
+}
+
+export interface PolicyInput {
+	now: number;
+	windows: BudgetWindow[];
+	currentRoute: Route;
+	routes: Route[];
+	config: PolicyConfig;
+	previousDecision?: PreviousDecision;
+}
+
+export interface PolicyDecision {
+	action: PolicyAction;
+	pressure: number;
+	reason: string;
+	route?: Route;
+	delayMs?: number;
+	windowId?: string;
+	decidedAt: number;
+	trace: string[];
+}
+
+const ACTION_SEVERITY: Record<PolicyAction, number> = {
+	continue: 0,
+	throttle: 1,
+	"lower-thinking": 2,
+	"switch-model": 3,
+	"switch-provider": 4,
+	halt: 5,
+};
+
+function actionThreshold(action: PolicyAction, thresholds: PolicyThresholds): number {
+	switch (action) {
+		case "continue": return 0;
+		case "throttle": return thresholds.throttle;
+		case "lower-thinking": return thresholds.lowerThinking;
+		case "switch-model": return thresholds.switchModel;
+		case "switch-provider": return thresholds.switchProvider;
+		case "halt": return thresholds.halt;
+	}
+}
+
+function desiredAction(pressure: number, thresholds: PolicyThresholds): PolicyAction {
+	if (pressure > thresholds.halt) return "halt";
+	if (pressure > thresholds.switchProvider) return "switch-provider";
+	if (pressure > thresholds.switchModel) return "switch-model";
+	if (pressure > thresholds.lowerThinking) return "lower-thinking";
+	if (pressure > thresholds.throttle) return "throttle";
+	return "continue";
+}
+
+function sameRoute(left: Route, right: Route): boolean {
+	return left.provider === right.provider && left.model === right.model && left.thinking === right.thinking;
+}
+
+function alternativesAfter(input: PolicyInput): Route[] {
+	const currentIndex = input.routes.findIndex((route) => sameRoute(route, input.currentRoute));
+	return input.routes.slice(currentIndex >= 0 ? currentIndex + 1 : 0);
+}
+
+function routeFor(action: PolicyAction, input: PolicyInput): Route | undefined {
+	const alternatives = alternativesAfter(input);
+	if (action === "lower-thinking") {
+		return alternatives.find((route) => route.provider === input.currentRoute.provider && route.model === input.currentRoute.model);
+	}
+	if (action === "switch-model") {
+		return alternatives.find((route) => route.provider === input.currentRoute.provider && route.model !== input.currentRoute.model);
+	}
+	if (action === "switch-provider") return alternatives.find((route) => route.provider !== input.currentRoute.provider);
+	return undefined;
+}
+
+function pressureFor(window: BudgetWindow, now: number): number {
+	const remainingSeconds = (window.resetsAt - now) / 1_000;
+	if (remainingSeconds <= 0) return Number.POSITIVE_INFINITY;
+	const remainingFraction = Math.max(0, 1 - window.usedFraction);
+	if (remainingFraction === 0) return Number.POSITIVE_INFINITY;
+	const elapsedSeconds = Math.max(0, window.windowSeconds - remainingSeconds);
+	const observedBurn = window.observedBurnPerSecond ?? (elapsedSeconds > 0 ? window.usedFraction / elapsedSeconds : 0);
+	const sustainableBurn = remainingFraction / remainingSeconds;
+	return observedBurn / sustainableBurn;
+}
+
+function holdPrevious(input: PolicyInput, pressure: number, trace: string[]): PolicyDecision | undefined {
+	const previous = input.previousDecision;
+	if (!previous) return undefined;
+	const candidate = desiredAction(pressure, input.config.thresholds);
+	if (ACTION_SEVERITY[candidate] >= ACTION_SEVERITY[previous.action]) return undefined;
+	const elapsed = input.now - previous.decidedAt;
+	if (elapsed < input.config.cooldownMs) {
+		trace.push(`cooldown holds ${previous.action} for ${input.config.cooldownMs - elapsed}ms`);
+		return decisionFromPrevious(previous, pressure, trace, "cooldown prevents recovery");
+	}
+	const recoveryThreshold = actionThreshold(previous.action, input.config.thresholds) * (1 - input.config.hysteresisFraction);
+	if (pressure > recoveryThreshold) {
+		trace.push(`hysteresis holds ${previous.action}: ${pressure.toFixed(3)} > ${recoveryThreshold.toFixed(3)}`);
+		return decisionFromPrevious(previous, pressure, trace, "hysteresis prevents recovery");
+	}
+	trace.push(`recovery allowed below ${recoveryThreshold.toFixed(3)} after cooldown`);
+	return undefined;
+}
+
+function decisionFromPrevious(
+	previous: PreviousDecision,
+	pressure: number,
+	trace: string[],
+	reason: string,
+): PolicyDecision {
+	return {
+		action: previous.action,
+		pressure,
+		reason,
+		...(previous.route ? { route: previous.route } : {}),
+		decidedAt: previous.decidedAt,
+		trace,
+	};
+}
+
+function failClosed(input: PolicyInput, reason: string, trace: string[], windowId?: string): PolicyDecision {
+	trace.push(`fail closed: ${reason}`);
+	return { action: "halt", pressure: Number.POSITIVE_INFINITY, reason, windowId, decidedAt: input.now, trace };
+}
+
+export function evaluateRoutingPolicy(input: PolicyInput): PolicyDecision {
+	const trace: string[] = [];
+	if (input.windows.length === 0) return failClosed(input, "required budget telemetry is missing", trace);
+	for (const window of input.windows) {
+		if (window.freshness !== "fresh") return failClosed(input, `telemetry ${window.id} is ${window.freshness}`, trace, window.id);
+		if (input.now - window.observedAt > input.config.maxTelemetryAgeMs) return failClosed(input, `telemetry ${window.id} is stale`, trace, window.id);
+		if (window.confidence < (input.config.minimumConfidence ?? 0)) return failClosed(input, `telemetry ${window.id} confidence is too low`, trace, window.id);
+		if (window.usedFraction < 0 || window.usedFraction > 1) return failClosed(input, `telemetry ${window.id} has invalid utilization`, trace, window.id);
+		if (window.usedFraction >= input.config.hardStopUsedFraction) return failClosed(input, `hard stop reached for ${window.id}`, trace, window.id);
+	}
+
+	const pressures = input.windows.map((window) => ({ window, pressure: pressureFor(window, input.now) }));
+	for (const { window, pressure } of pressures) trace.push(`${window.id}: pressure=${pressure.toFixed(3)} sustainable=${pressure <= 1}`);
+	const binding = pressures.reduce((worst, candidate) => candidate.pressure > worst.pressure ? candidate : worst);
+	const held = holdPrevious(input, binding.pressure, trace);
+	if (held) return { ...held, windowId: binding.window.id };
+
+	let action = desiredAction(binding.pressure, input.config.thresholds);
+	let route = routeFor(action, input);
+	if (action === "lower-thinking" && !route) {
+		trace.push("lower-thinking route unavailable; escalating");
+		action = "switch-model";
+		route = routeFor(action, input);
+	}
+	if (action === "switch-model" && !route) {
+		trace.push("switch-model route unavailable; escalating");
+		action = "switch-provider";
+		route = routeFor(action, input);
+	}
+	if (action === "switch-provider" && !route) {
+		trace.push("switch-provider route unavailable; escalating");
+		action = "halt";
+	}
+
+	const reason = `${binding.window.id} pressure ${binding.pressure.toFixed(3)} selected ${action}`;
+	trace.push(reason);
+	const decision: PolicyDecision = {
+		action,
+		pressure: binding.pressure,
+		reason,
+		windowId: binding.window.id,
+		decidedAt: input.now,
+		trace,
+	};
+	if (route) decision.route = route;
+	if (action === "throttle") {
+		const span = input.config.thresholds.lowerThinking - input.config.thresholds.throttle;
+		const fraction = span > 0 ? (binding.pressure - input.config.thresholds.throttle) / span : 1;
+		decision.delayMs = Math.max(0, Math.min(input.config.maxThrottleMs, Math.round(fraction * input.config.maxThrottleMs)));
+	}
+	return decision;
+}

package/src/ports/metric-store.ts

@@ -0,0 +1,9 @@
+import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../domain/metric.ts";
+
+export interface MetricStore {
+	record(observation: MetricObservation): StoredMetricObservation;
+	query(filter?: MetricQuery): StoredMetricObservation[];
+	pruneBefore(cutoff: number): number;
+	checkpoint(): void;
+	close(): void;
+}

package/src/ports/router-controller.ts

@@ -0,0 +1,42 @@
+import type { PolicyDecision, Route } from "../policy.ts";
+
+export interface TelemetrySourceStatus {
+	id: string;
+	provider: string;
+	ok: boolean;
+	metrics: number;
+	observedAt?: number;
+	error?: string;
+}
+
+export interface TelemetryPollResult {
+	sources: TelemetrySourceStatus[];
+	observedAt: number;
+}
+
+export interface RouteOverride {
+	route: Route;
+	expiresAt: number | null;
+}
+
+export interface RouterStatus {
+	ready: boolean;
+	paused: boolean;
+	sources: TelemetrySourceStatus[];
+	lastDecision: PolicyDecision | null;
+	override: RouteOverride | null;
+	currentRoute: Route | null;
+	availableRoutes: Route[];
+}
+
+export interface RouterController {
+	poll(): Promise<TelemetryPollResult>;
+	status(): RouterStatus;
+	decide(): PolicyDecision;
+	pause(): RouterStatus;
+	resume(): RouterStatus;
+	setOverride(override?: RouteOverride): RouterStatus;
+	clearOverride(): RouterStatus;
+	setCurrentRoute(route: Route): RouterStatus;
+	setAvailableRoutes(routes: Route[]): RouterStatus;
+}

package/src/ports/telemetry-source.ts

@@ -0,0 +1,15 @@
+import type { MetricObservation } from "../domain/metric.ts";
+import type { BudgetWindow } from "../policy.ts";
+
+export interface TelemetryBatch {
+	observedAt: number;
+	metrics: MetricObservation[];
+	windows: BudgetWindow[];
+}
+
+export interface TelemetrySource {
+	id: string;
+	provider: string;
+	required: boolean;
+	poll(): Promise<TelemetryBatch>;
+}