@danypops/jittor 0.1.0

package/src/providers/openrouter.ts

@@ -0,0 +1,71 @@
+import {
+	parseOpenRouterAnalytics,
+	parseOpenRouterGeneration,
+	parseOpenRouterKey,
+	parseOpenRouterModels,
+	type OpenRouterAnalyticsResult,
+	type OpenRouterGeneration,
+	type OpenRouterKeySnapshot,
+	type OpenRouterModel,
+} from "./openrouter-contracts.ts";
+
+export {
+	openRouterUsageMetrics,
+	parseOpenRouterUsage,
+	type OpenRouterAnalyticsResult,
+	type OpenRouterGeneration,
+	type OpenRouterKeySnapshot,
+	type OpenRouterModel,
+	type OpenRouterUsage,
+	type OpenRouterUsageContext,
+} from "./openrouter-contracts.ts";
+
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export type OpenRouterTransport = (request: Request) => Promise<Response>;
+
+export class OpenRouterTelemetryAdapter {
+	private managementCapability: boolean | undefined;
+
+	constructor(
+		private readonly apiKey: string,
+		private readonly transport: OpenRouterTransport = fetch,
+		private readonly baseUrl = OPENROUTER_BASE_URL,
+	) {
+		if (apiKey.length === 0) throw new Error("OpenRouter API key is required");
+	}
+
+	async readKey(observedAt = Date.now()): Promise<OpenRouterKeySnapshot> {
+		const snapshot = parseOpenRouterKey(await this.request("/key"), observedAt);
+		this.managementCapability = snapshot.management;
+		return snapshot;
+	}
+
+	async listModels(): Promise<OpenRouterModel[]> {
+		return parseOpenRouterModels(await this.request("/models"));
+	}
+
+	async getGeneration(id: string): Promise<OpenRouterGeneration> {
+		if (id.length === 0) throw new Error("generation id is required");
+		return parseOpenRouterGeneration(await this.request(`/generation?id=${encodeURIComponent(id)}`));
+	}
+
+	async queryAnalytics(query: Record<string, unknown>): Promise<OpenRouterAnalyticsResult> {
+		if (this.managementCapability !== true) throw new Error("OpenRouter analytics requires a detected management key");
+		return parseOpenRouterAnalytics(await this.request("/analytics/query", {
+			method: "POST",
+			body: JSON.stringify(query),
+		}));
+	}
+
+	private async request(path: string, init: RequestInit = {}): Promise<unknown> {
+		const response = await this.transport(new Request(`${this.baseUrl}${path}`, {
+			...init,
+			headers: { authorization: `Bearer ${this.apiKey}`, "content-type": "application/json", ...init.headers },
+		}));
+		if (!response.ok) {
+			const retryAfter = response.headers.get("retry-after");
+			throw new Error(`OpenRouter ${path.split("?")[0]} failed with HTTP ${response.status}${retryAfter ? `; retry after ${retryAfter}` : ""}`);
+		}
+		return response.json();
+	}
+}

package/src/providers/telemetry-sources.ts

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

package/src/router.ts

@@ -0,0 +1,158 @@
+import type { MetricStore } from "./ports/metric-store.ts";
+import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult, TelemetrySourceStatus } from "./ports/router-controller.ts";
+import type { TelemetrySource } from "./ports/telemetry-source.ts";
+import {
+	evaluateRoutingPolicy,
+	type BudgetWindow,
+	type PolicyConfig,
+	type PolicyDecision,
+	type Route,
+} from "./policy.ts";
+
+export interface JittorRouterOptions {
+	metrics: MetricStore;
+	sources: TelemetrySource[];
+	policy: PolicyConfig;
+	routes: Route[];
+	currentRoute: Route;
+	clock?: () => number;
+}
+
+function sameRoute(left: Route, right: Route): boolean {
+	return left.provider === right.provider && left.model === right.model && left.thinking === right.thinking;
+}
+
+export class JittorRouter implements RouterController {
+	private readonly clock: () => number;
+	private readonly windows = new Map<string, BudgetWindow[]>();
+	private sourceStatuses: TelemetrySourceStatus[] = [];
+	private lastDecision: PolicyDecision | null = null;
+	private previousPolicyDecision: PolicyDecision | null = null;
+	private paused = false;
+	private override: RouteOverride | null = null;
+	private inFlightPoll: Promise<TelemetryPollResult> | null = null;
+	private currentRoute: Route;
+	private availableRoutes: Route[];
+
+	constructor(private readonly options: JittorRouterOptions) {
+		this.clock = options.clock ?? Date.now;
+		this.currentRoute = options.currentRoute;
+		this.availableRoutes = structuredClone(options.routes);
+	}
+
+	poll(): Promise<TelemetryPollResult> {
+		this.inFlightPoll ??= this.runPoll().finally(() => { this.inFlightPoll = null; });
+		return this.inFlightPoll;
+	}
+
+	status(): RouterStatus {
+		this.expireOverride();
+		return {
+			ready: this.isReady(),
+			paused: this.paused,
+			sources: structuredClone(this.sourceStatuses),
+			lastDecision: this.lastDecision ? structuredClone(this.lastDecision) : null,
+			override: this.override ? structuredClone(this.override) : null,
+			currentRoute: structuredClone(this.currentRoute),
+			availableRoutes: structuredClone(this.availableRoutes),
+		};
+	}
+
+	decide(): PolicyDecision {
+		const now = this.clock();
+		this.expireOverride();
+		if (this.paused) return this.remember({ action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "Jittor is paused", decidedAt: now, trace: ["manual pause"] });
+		if (this.override) {
+			const route = this.override.route;
+			const action = route.provider !== this.currentRoute.provider
+				? "switch-provider"
+				: route.model !== this.currentRoute.model
+					? "switch-model"
+					: route.thinking !== this.currentRoute.thinking ? "lower-thinking" : "continue";
+			return this.remember({ action, route, pressure: 0, reason: "manual route override", decidedAt: now, trace: ["manual override"] });
+		}
+		if (!this.isReady()) return this.remember({ action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "required telemetry is not ready", decidedAt: now, trace: ["fail closed"] });
+		const activeSourceIds = new Set(this.options.sources.filter((source) => source.provider === this.currentRoute.provider).map((source) => source.id));
+		return this.rememberPolicy(evaluateRoutingPolicy({
+			now,
+			windows: [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId)).flatMap(([, windows]) => windows),
+			currentRoute: this.currentRoute,
+			routes: this.availableRoutes,
+			config: this.options.policy,
+			previousDecision: this.previousPolicyDecision ?? undefined,
+		}));
+	}
+
+	pause(): RouterStatus {
+		this.paused = true;
+		return this.status();
+	}
+
+	resume(): RouterStatus {
+		this.paused = false;
+		return this.status();
+	}
+
+	setOverride(override?: RouteOverride): RouterStatus {
+		if (!override || !this.availableRoutes.some((route) => sameRoute(route, override.route))) throw new Error("override route is not available in Pi");
+		if (override.expiresAt !== null && override.expiresAt <= this.clock()) throw new Error("override expiry must be in the future");
+		this.override = structuredClone(override);
+		return this.status();
+	}
+
+	clearOverride(): RouterStatus {
+		this.override = null;
+		return this.status();
+	}
+
+	setCurrentRoute(route: Route): RouterStatus {
+		if (!route.provider || !route.model || !route.thinking) throw new Error("current route is incomplete");
+		this.currentRoute = structuredClone(route);
+		return this.status();
+	}
+
+	setAvailableRoutes(routes: Route[]): RouterStatus {
+		if (!Array.isArray(routes)) throw new Error("available routes must be an array");
+		const valid = routes.filter((route) => typeof route?.provider === "string" && route.provider.length > 0
+			&& typeof route.model === "string" && route.model.length > 0
+			&& typeof route.thinking === "string" && route.thinking.length > 0);
+		this.availableRoutes = valid.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index).map((route) => structuredClone(route));
+		return this.status();
+	}
+
+	private async runPoll(): Promise<TelemetryPollResult> {
+		const statuses = await Promise.all(this.options.sources.map(async (source): Promise<TelemetrySourceStatus> => {
+			try {
+				const batch = await source.poll();
+				for (const observation of batch.metrics) this.options.metrics.record(observation);
+				this.windows.set(source.id, batch.windows);
+				return { id: source.id, provider: source.provider, ok: true, metrics: batch.metrics.length, observedAt: batch.observedAt };
+			} catch {
+				this.windows.delete(source.id);
+				return { id: source.id, provider: source.provider, ok: false, metrics: 0, observedAt: this.clock(), error: "poll failed" };
+			}
+		}));
+		this.sourceStatuses = statuses;
+		return { sources: structuredClone(statuses), observedAt: this.clock() };
+	}
+
+	private isReady(): boolean {
+		const active = this.options.sources.filter((source) => source.provider === this.currentRoute.provider);
+		if (active.length === 0) return false;
+		return active.every((source) => this.sourceStatuses.some((status) => status.id === source.id && status.ok));
+	}
+
+	private expireOverride(): void {
+		if (this.override?.expiresAt !== null && this.override && this.override.expiresAt <= this.clock()) this.override = null;
+	}
+
+	private remember(decision: PolicyDecision): PolicyDecision {
+		this.lastDecision = decision;
+		return structuredClone(decision);
+	}
+
+	private rememberPolicy(decision: PolicyDecision): PolicyDecision {
+		this.previousPolicyDecision = decision;
+		return this.remember(decision);
+	}
+}

package/src/service.ts

@@ -0,0 +1,158 @@
+import { SERVICE_MAX_BODY_BYTES, VERSION } from "./constants.ts";
+import { validateMetricObservation, type MetricObservation, type MetricQuery, type StoredMetricObservation } from "./domain/metric.ts";
+import type { MetricStore } from "./ports/metric-store.ts";
+import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
+import type { PolicyDecision, Route } from "./policy.ts";
+
+export const EXPECTED_OPERATION_NAMES = [
+	"metrics.record",
+	"metrics.query",
+	"metrics.prune",
+	"service.checkpoint",
+	"telemetry.poll",
+	"router.status",
+	"router.decide",
+	"router.pause",
+	"router.resume",
+	"router.override",
+	"router.clear_override",
+	"router.current_route",
+	"router.available_routes",
+] as const;
+
+export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
+export interface OperationInputs {
+	"metrics.record": MetricObservation;
+	"metrics.query": MetricQuery;
+	"metrics.prune": { before: number };
+	"service.checkpoint": Record<string, never>;
+	"telemetry.poll": Record<string, never>;
+	"router.status": Record<string, never>;
+	"router.decide": Record<string, never>;
+	"router.pause": Record<string, never>;
+	"router.resume": Record<string, never>;
+	"router.override": RouteOverride;
+	"router.clear_override": Record<string, never>;
+	"router.current_route": Route;
+	"router.available_routes": { routes: Route[] };
+}
+export interface OperationOutputs {
+	"metrics.record": StoredMetricObservation;
+	"metrics.query": StoredMetricObservation[];
+	"metrics.prune": { deleted: number };
+	"service.checkpoint": { ok: true };
+	"telemetry.poll": TelemetryPollResult;
+	"router.status": RouterStatus;
+	"router.decide": PolicyDecision;
+	"router.pause": RouterStatus;
+	"router.resume": RouterStatus;
+	"router.override": RouterStatus;
+	"router.clear_override": RouterStatus;
+	"router.current_route": RouterStatus;
+	"router.available_routes": RouterStatus;
+}
+
+export class UnknownOperationError extends Error {}
+
+class UnavailableRouter implements RouterController {
+	private readonly unavailable: RouterStatus = { ready: false, paused: false, sources: [], lastDecision: null, override: null, currentRoute: null, availableRoutes: [] };
+	async poll(): Promise<TelemetryPollResult> { return { sources: [], observedAt: Date.now() }; }
+	status(): RouterStatus { return structuredClone(this.unavailable); }
+	decide(): PolicyDecision { return { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "router is not configured", decidedAt: Date.now(), trace: ["fail closed"] }; }
+	pause(): RouterStatus { return this.status(); }
+	resume(): RouterStatus { return this.status(); }
+	setOverride(): RouterStatus { return this.status(); }
+	clearOverride(): RouterStatus { return this.status(); }
+	setCurrentRoute(): RouterStatus { return this.status(); }
+	setAvailableRoutes(): RouterStatus { return this.status(); }
+}
+
+export class JittorService {
+	constructor(
+		private readonly metrics: MetricStore,
+		private readonly router: RouterController = new UnavailableRouter(),
+	) {}
+
+	operationNames(): OperationName[] {
+		return [...EXPECTED_OPERATION_NAMES];
+	}
+
+	async execute<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]>;
+	async execute(operation: string, input: Record<string, unknown>): Promise<unknown>;
+	async execute(operation: string, input: Record<string, unknown> = {}): Promise<unknown> {
+		switch (operation) {
+			case "metrics.record": return this.metrics.record(validateMetricObservation(input));
+			case "metrics.query": return this.metrics.query(input as MetricQuery);
+			case "metrics.prune": {
+				const before = input["before"];
+				if (typeof before !== "number") throw new Error("before is required");
+				return { deleted: this.metrics.pruneBefore(before) };
+			}
+			case "service.checkpoint": this.metrics.checkpoint(); return { ok: true };
+			case "telemetry.poll": return this.router.poll();
+			case "router.status": return this.router.status();
+			case "router.decide": return this.router.decide();
+			case "router.pause": return this.router.pause();
+			case "router.resume": return this.router.resume();
+			case "router.override": return this.router.setOverride(input as unknown as RouteOverride);
+			case "router.clear_override": return this.router.clearOverride();
+			case "router.current_route": return this.router.setCurrentRoute(input as unknown as Route);
+			case "router.available_routes": return this.router.setAvailableRoutes(Array.isArray(input["routes"]) ? input["routes"] as Route[] : []);
+			default: throw new UnknownOperationError(`unknown operation: ${operation}`);
+		}
+	}
+
+	ready(): boolean {
+		return this.router.status().ready;
+	}
+
+	close(): void {
+		this.metrics.close();
+	}
+}
+
+export interface JittorAppOptions {
+	service: JittorService;
+	token: string;
+	maxBodyBytes?: number;
+}
+
+function authorized(request: Request, token: string): boolean {
+	return request.headers.get("authorization") === `Bearer ${token}`;
+}
+
+function json(value: unknown, status = 200): Response {
+	return Response.json(value, { status });
+}
+
+export function createApp(options: JittorAppOptions): { fetch(request: Request): Promise<Response> } {
+	const maxBodyBytes = options.maxBodyBytes ?? SERVICE_MAX_BODY_BYTES;
+	return {
+		async fetch(request: Request): Promise<Response> {
+			if (!authorized(request, options.token)) return json({ error: "unauthorized" }, 401);
+			const url = new URL(request.url);
+			if (request.method === "GET" && url.pathname === "/health") return json({ ok: true, version: VERSION });
+			if (request.method === "GET" && url.pathname === "/ready") {
+				const ready = options.service.ready();
+				return json({ ready }, ready ? 200 : 503);
+			}
+			if (request.method === "GET" && url.pathname === "/api/v1/ops") return json({ operations: options.service.operationNames() });
+			if (request.method !== "POST" || url.pathname !== "/api/v1/ops") return json({ error: "not found" }, 404);
+			const contentLength = Number(request.headers.get("content-length") ?? 0);
+			if (contentLength > maxBodyBytes) return json({ error: "payload too large" }, 413);
+			const text = await request.text();
+			if (new TextEncoder().encode(text).byteLength > maxBodyBytes) return json({ error: "payload too large" }, 413);
+			try {
+				const body = JSON.parse(text) as { op?: unknown; input?: unknown };
+				if (typeof body.op !== "string") throw new Error("op is required");
+				const input = typeof body.input === "object" && body.input !== null && !Array.isArray(body.input)
+					? body.input as Record<string, unknown>
+					: {};
+				return json({ result: await options.service.execute(body.op, input) });
+			} catch (error) {
+				if (error instanceof UnknownOperationError) return json({ error: error.message }, 404);
+				return json({ error: error instanceof Error ? error.message : String(error) }, 400);
+			}
+		},
+	};
+}

package/src/state.ts

@@ -0,0 +1,81 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import {
+	DATABASE_FILENAME,
+	HANDLE_FILENAME,
+	JITTOR_STATE_DIRECTORY,
+	LOOPBACK_HOST,
+	SYSTEMD_UNIT_NAME,
+	TOKEN_FILENAME,
+} from "./constants.ts";
+
+export interface JittorPaths {
+	database: string;
+	token: string;
+	handle: string;
+	systemdUnit: string;
+}
+
+export interface DaemonHandle {
+	host: typeof LOOPBACK_HOST;
+	port: number;
+	pid: number;
+}
+
+export interface PathEnvironment {
+	env?: Record<string, string | undefined>;
+	home?: string;
+	uid?: number;
+}
+
+export function resolveJittorPaths(options: PathEnvironment = {}): JittorPaths {
+	const env = options.env ?? process.env;
+	const home = options.home ?? homedir();
+	const uid = options.uid ?? process.getuid?.() ?? 0;
+	const dataHome = env["XDG_DATA_HOME"] ?? join(home, ".local", "share");
+	const stateHome = env["XDG_STATE_HOME"] ?? join(home, ".local", "state");
+	const runtimeHome = env["XDG_RUNTIME_DIR"] ?? join("/run", "user", String(uid));
+	const configHome = env["XDG_CONFIG_HOME"] ?? join(home, ".config");
+	return {
+		database: join(dataHome, JITTOR_STATE_DIRECTORY, DATABASE_FILENAME),
+		token: join(stateHome, JITTOR_STATE_DIRECTORY, TOKEN_FILENAME),
+		handle: join(runtimeHome, JITTOR_STATE_DIRECTORY, HANDLE_FILENAME),
+		systemdUnit: join(configHome, "systemd", "user", SYSTEMD_UNIT_NAME),
+	};
+}
+
+export function ensureAuthToken(paths: JittorPaths = resolveJittorPaths()): string {
+	mkdirSync(dirname(paths.token), { recursive: true, mode: 0o700 });
+	if (existsSync(paths.token)) {
+		chmodSync(paths.token, 0o600);
+		const token = readFileSync(paths.token, "utf8").trim();
+		if (!/^[a-f0-9]{64}$/.test(token)) throw new Error("invalid Jittor authentication token");
+		return token;
+	}
+	const token = randomBytes(32).toString("hex");
+	writeFileSync(paths.token, `${token}\n`, { mode: 0o600 });
+	return token;
+}
+
+export function writeDaemonHandle(paths: JittorPaths, handle: DaemonHandle): void {
+	mkdirSync(dirname(paths.handle), { recursive: true, mode: 0o700 });
+	const temporary = `${paths.handle}.${process.pid}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(handle)}\n`, { mode: 0o600 });
+	renameSync(temporary, paths.handle);
+}
+
+export function readDaemonHandle(paths: JittorPaths = resolveJittorPaths()): DaemonHandle | null {
+	try {
+		const value = JSON.parse(readFileSync(paths.handle, "utf8")) as Partial<DaemonHandle>;
+		if (value.host !== LOOPBACK_HOST || !Number.isInteger(value.port) || value.port! < 1 || value.port! > 65_535 || !Number.isInteger(value.pid)) return null;
+		return value as DaemonHandle;
+	} catch {
+		return null;
+	}
+}
+
+export function removeDaemonHandle(paths: JittorPaths = resolveJittorPaths()): void {
+	rmSync(paths.handle, { force: true });
+}