@danypops/jittor 0.10.0 → 0.11.0

package/src/constants.ts

@@ -91,6 +91,13 @@ export const MAX_USAGE_BUCKETS = 120;
 /** Defense-in-depth cap on the SQL-side usage aggregation result: (scopes x metrics x buckets) is already small by construction, but this bounds it explicitly rather than trusting that alone. */
 export const USAGE_AGGREGATE_MAX_ROWS = 25_000;
 export const MAX_DYNAMIC_ROUTES = 100;
+/** Bounds concurrent in-memory Pi router scopes; the least recently used non-global scope is evicted. */
+export const ROUTER_MAX_SESSION_SCOPES = 500;
+export const ROUTER_SESSION_ID_MAX_CHARACTERS = 128;
+/** Hard cap on registered session_identities rows; oldest-seen identity is evicted beyond this. */
+export const SESSION_IDENTITY_MAX_ROWS = 2_000;
+/** Bounds one metrics.record_batch call; a real per-turn event batch (usage, headers, local-run metrics) is a handful of rows, never thousands. */
+export const METRIC_BATCH_MAX_OBSERVATIONS = 100;
 export const CODEX_ERROR_MESSAGE_LIMIT = 160;
 export const CODEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;
 export const CODEX_RECOVERY_BASE_DELAY_MS = 2 * MILLISECONDS_PER_SECOND;

package/src/daemon.ts

@@ -12,6 +12,8 @@ import { BenchmarkCatalog } from "./domain/benchmark.ts";
 import { EvidenceModelRanker } from "./domain/model-ranking-service.ts";
 import { createApp, JittorService } from "./service.ts";
 import { JittorRouter } from "./router.ts";
+import { SQLiteSessionIdentityStore } from "./adapters/sqlite-session-identity-store.ts";
+import { SessionIdentity } from "./session-identity-service.ts";
 import type { BenchmarkSource } from "./ports/benchmark-source.ts";
 import type { TelemetrySource } from "./ports/telemetry-source.ts";
 import { CodexTelemetrySource, GoogleVertexBudgetTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
@@ -39,6 +41,12 @@ export function benchmarkSourcesFromEnvironment(env: Record<string, string | und
 	return sources;
 }
 
+function googleVertexMetricSource(value: string | undefined): GoogleVertexMetricSource {
+	if (value === undefined || value === "google-vertex") return "google-vertex";
+	if (value === "anthropic-vertex") return "anthropic-vertex";
+	throw new Error("JITTOR_GOOGLE_VERTEX_BUDGET_SOURCE must be google-vertex or anthropic-vertex");
+}
+
 export function telemetrySourcesFromEnvironment(env: Record<string, string | undefined> = process.env): TelemetrySource[] {
 	const sources: TelemetrySource[] = [];
 	const codexAuthFile = env["JITTOR_CODEX_AUTH_FILE"];
@@ -49,7 +57,7 @@ export function telemetrySourcesFromEnvironment(env: Record<string, string | und
 	// docs/PROVIDER_RESEARCH.md), so its absence must never attempt ADC discovery or a network call.
 	const vertexBudgetSubscription = env["JITTOR_GOOGLE_VERTEX_BUDGET_SUBSCRIPTION"];
 	if (vertexBudgetSubscription) {
-		const source = (env["JITTOR_GOOGLE_VERTEX_BUDGET_SOURCE"] ?? "google-vertex") as GoogleVertexMetricSource;
+		const source = googleVertexMetricSource(env["JITTOR_GOOGLE_VERTEX_BUDGET_SOURCE"]);
 		const tokenProvider = createGoogleAdcTokenProvider([GOOGLE_PUBSUB_READONLY_SCOPE]);
 		sources.push(new GoogleVertexBudgetTelemetrySource(vertexBudgetSubscription, tokenProvider, Date.now, fetch, source));
 	}
@@ -71,7 +79,9 @@ export function startDaemon(
 	env: Record<string, string | undefined> = process.env,
 ): RunningDaemon {
 	const token = ensureAuthToken(paths);
-	const metrics = new SQLiteMetricStore(openJittorDb(paths.database));
+	const db = openJittorDb(paths.database);
+	const metrics = new SQLiteMetricStore(db);
+	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
 	const sources = telemetrySourcesFromEnvironment(env);
 	const benchmarkSources = benchmarkSourcesFromEnvironment(env);
 	const benchmarkStore = new MetricBenchmarkStore(metrics);
@@ -84,7 +94,7 @@ export function startDaemon(
 		routes: [],
 		currentRoute: UNCONFIGURED_ROUTE,
 	});
-	const service = new JittorService(metrics, router, benchmarks, modelRanker);
+	const service = new JittorService(metrics, router, benchmarks, modelRanker, sessionIdentity);
 
 	const daemon = startDaemonKit({
 		daemonLabel: "Jittor",

package/src/db.ts

@@ -19,6 +19,17 @@ CREATE INDEX metric_observations_time_idx
 	ON metric_observations(observed_at);
 `;
 
+const SESSION_IDENTITY_SCHEMA = `
+CREATE TABLE session_identities (
+	session_id    TEXT PRIMARY KEY,
+	secret_hash   TEXT NOT NULL,
+	registered_at TEXT NOT NULL,
+	last_seen_at  TEXT NOT NULL
+);
+CREATE INDEX session_identities_last_seen_idx
+	ON session_identities(last_seen_at);
+`;
+
 /**
  * Delegates bootstrap (pragmas, migration engine) to `@danypops/daemon-kit/storage`, which
  * generalizes the byte-identical pragma/PRAGMA-user_version skeleton jittor's own db.ts used to
@@ -28,6 +39,9 @@ export function openJittorDb(path: string): Database {
 	return openSqliteWithPragmas(path, {
 		databaseOptions: { create: true, strict: true },
 		busyTimeoutMs: SQLITE_BUSY_TIMEOUT_MS,
-		migrations: [{ version: 1, up: (db) => db.exec(INITIAL_SCHEMA) }],
+		migrations: [
+			{ version: 1, up: (db) => db.exec(INITIAL_SCHEMA) },
+			{ version: 2, up: (db) => db.exec(SESSION_IDENTITY_SCHEMA) },
+		],
 	});
 }

package/src/operations/benchmark-operations.ts

@@ -0,0 +1,12 @@
+import type { BenchmarkQuery } from "../domain/benchmark.ts";
+import type { BenchmarkController } from "../ports/benchmark-controller.ts";
+import type { OperationHandlerMap } from "./types.ts";
+
+/** benchmark.* -- every operation whose only collaborator is the benchmark-controller port. */
+export function benchmarkOperations(benchmarks: BenchmarkController): OperationHandlerMap {
+	return {
+		"benchmark.refresh": (input) => benchmarks.refresh(input["force"] === true),
+		"benchmark.status": () => benchmarks.status(),
+		"benchmark.query": (input) => benchmarks.query(input as unknown as BenchmarkQuery),
+	};
+}

package/src/operations/context-operations.ts

@@ -0,0 +1,30 @@
+import { COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES, CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS, CONTEXT_ASSESSMENT_QUERY_LIMIT } from "../constants.ts";
+import { assessContextTelemetry, estimateCompactionDuration } from "../domain/context-telemetry.ts";
+import type { MetricStore } from "../ports/metric-store.ts";
+import type { OperationHandlerMap } from "./types.ts";
+
+/** context.assess and compaction.estimate -- both read-only projections of recorded metrics, no router/session involvement. */
+export function contextOperations(metrics: MetricStore): OperationHandlerMap {
+	return {
+		"context.assess": (input) => {
+			const until = input["until"] === undefined ? Date.now() : input["until"];
+			const since = input["since"] === undefined && typeof until === "number" ? Math.max(0, until - CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS) : input["since"];
+			if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) throw new Error("context assessment requires non-negative ordered integer bounds");
+			const query = { since: since as number, until: until as number, order: "asc" as const, limit: CONTEXT_ASSESSMENT_QUERY_LIMIT };
+			const injections = metrics.query({ ...query, source: "papyrus-context", metric: "injected-characters" });
+			const compactions = metrics.query({ ...query, source: "pi-context" });
+			return assessContextTelemetry(injections, compactions, {
+				since: since as number,
+				until: until as number,
+				truncated: injections.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT || compactions.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT,
+			});
+		},
+		"compaction.estimate": () => {
+			const rows = metrics.query({
+				source: "pi-context", scope: "compaction", metric: "compaction-duration",
+				order: "desc", limit: COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES,
+			});
+			return estimateCompactionDuration(rows);
+		},
+	};
+}

package/src/operations/metrics-operations.ts

@@ -0,0 +1,77 @@
+import { MAX_USAGE_BUCKETS, METRIC_BATCH_MAX_OBSERVATIONS, PRUNE_MIN_AGE_MS, TASK_COST_QUERY_LIMIT, USAGE_MAX_DISTINCT_SCOPES } from "../constants.ts";
+import { validateMetricObservation, type MetricQuery } from "../domain/metric.ts";
+import { buildTaskCostSummary } from "../domain/task-cost.ts";
+import type { MetricStore } from "../ports/metric-store.ts";
+import type { OperationHandlerMap } from "./types.ts";
+
+/** metrics.* and service.checkpoint -- every operation whose only collaborator is the metric-store port. */
+export function metricsOperations(metrics: MetricStore): OperationHandlerMap {
+	return {
+		"metrics.record": (input) => metrics.record(validateMetricObservation(input)),
+		"metrics.record_batch": (input) => {
+			const observations = input["observations"];
+			if (!Array.isArray(observations) || observations.length === 0) throw new Error("observations must be a non-empty array");
+			if (observations.length > METRIC_BATCH_MAX_OBSERVATIONS) throw new Error(`observations must contain at most ${METRIC_BATCH_MAX_OBSERVATIONS} entries`);
+			return metrics.recordBatch(observations.map((observation) => validateMetricObservation(observation)));
+		},
+		"metrics.query": (input) => metrics.query(input as MetricQuery),
+		"metrics.distinct_scopes": (input) => {
+			const source = input["source"];
+			const since = input["since"];
+			const until = input["until"];
+			if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
+			if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+				throw new Error("distinct scopes requires non-negative ordered integer bounds");
+			}
+			const requestedLimit = input["limit"];
+			const limit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
+			return metrics.distinctScopes({ source, since: since as number, until: until as number, limit });
+		},
+		"metrics.usage_series": (input) => {
+			const source = input["source"];
+			const since = input["since"];
+			const until = input["until"];
+			const bucketSizeMs = input["bucketSizeMs"];
+			const bucketCount = input["bucketCount"];
+			if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
+			if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+				throw new Error("usage series requires non-negative ordered integer bounds");
+			}
+			if (typeof bucketSizeMs !== "number" || !Number.isFinite(bucketSizeMs) || bucketSizeMs <= 0) throw new Error("bucketSizeMs must be a positive number");
+			if (!Number.isInteger(bucketCount) || (bucketCount as number) <= 0 || (bucketCount as number) > MAX_USAGE_BUCKETS) {
+				throw new Error(`bucketCount must be a positive integer up to ${MAX_USAGE_BUCKETS}`);
+			}
+			const requestedScopeLimit = input["scopeLimit"];
+			const scopeLimit = Number.isFinite(requestedScopeLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedScopeLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
+			const scopes = metrics.distinctScopes({ source, since: since as number, until: until as number, limit: scopeLimit });
+			// More distinct scopes may exist beyond this bounded list -- that is the only remaining
+			// truncation risk once aggregation replaces a per-scope raw-row fetch (see aggregateUsage's
+			// own doc comment for the incident this was built to stop repeating).
+			const truncated = scopes.length >= scopeLimit;
+			const rows = scopes.length === 0 ? [] : metrics.aggregateUsage({
+				source, scopes, since: since as number, until: until as number, bucketSizeMs, bucketCount: bucketCount as number,
+			});
+			return { rows, truncated };
+		},
+		"metrics.cost_by_task": (input) => {
+			const since = input["since"];
+			const until = input["until"];
+			if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+				throw new Error("cost by task requires non-negative ordered integer bounds");
+			}
+			const rows = metrics.query({ source: "pi", since: since as number, until: until as number, order: "desc", limit: TASK_COST_QUERY_LIMIT });
+			return buildTaskCostSummary(rows, { since: since as number, until: until as number, truncated: rows.length >= TASK_COST_QUERY_LIMIT });
+		},
+		"metrics.prune": (input) => {
+			const before = input["before"];
+			if (typeof before !== "number") throw new Error("before is required");
+			const force = input["force"] === true;
+			const minCutoff = Date.now() - PRUNE_MIN_AGE_MS;
+			if (!force && before > minCutoff) {
+				throw new Error(`refusing to prune metrics newer than ${new Date(minCutoff).toISOString()} without force: true (this looked like it could delete recent or live data)`);
+			}
+			return { deleted: metrics.pruneBefore(before) };
+		},
+		"service.checkpoint": () => { metrics.checkpoint(); return { ok: true }; },
+	};
+}

package/src/operations/model-ranking-operations.ts

@@ -0,0 +1,16 @@
+import type { ModelRanker, ModelRecommendationInput } from "../domain/model-ranking-service.ts";
+import type { RouterController } from "../ports/router-controller.ts";
+import type { OperationHandlerMap } from "./types.ts";
+
+/** models.rank -- scores candidates via the model ranker, then, only for an automatic selection, applies it as a router mutation (so it shares the same session-identity authorization as every other router mutation). */
+export function modelRankingOperations(modelRanker: ModelRanker, router: RouterController, authorize: (input: Record<string, unknown>) => string | undefined): OperationHandlerMap {
+	return {
+		"models.rank": (input) => {
+			const result = modelRanker.rank(input as unknown as ModelRecommendationInput);
+			if (result.automaticSelection && router.applyModelRanking) {
+				router.applyModelRanking(result.ranked.map((item) => item.candidate), authorize(input));
+			}
+			return result;
+		},
+	};
+}

package/src/operations/router-operations.ts

@@ -0,0 +1,19 @@
+import type { RouteOverride, RouterController } from "../ports/router-controller.ts";
+import type { Route } from "../policy.ts";
+import type { OperationHandlerMap } from "./types.ts";
+import { routerSessionId } from "./session-scope.ts";
+
+/** telemetry.poll and every router.* operation -- reads pass a bare session_id through; mutations run authorize first, matching the opt-in session-identity armor. */
+export function routerOperations(router: RouterController, authorize: (input: Record<string, unknown>) => string | undefined): OperationHandlerMap {
+	return {
+		"telemetry.poll": () => router.poll(),
+		"router.status": (input) => router.status(routerSessionId(input)),
+		"router.decide": (input) => router.decide(routerSessionId(input)),
+		"router.pause": (input) => router.pause(authorize(input)),
+		"router.resume": (input) => router.resume(authorize(input)),
+		"router.override": (input) => router.setOverride(input as unknown as RouteOverride, authorize(input)),
+		"router.clear_override": (input) => router.clearOverride(authorize(input)),
+		"router.current_route": (input) => router.setCurrentRoute(input as unknown as Route, authorize(input)),
+		"router.available_routes": (input) => router.setAvailableRoutes(Array.isArray(input["routes"]) ? input["routes"] as Route[] : [], authorize(input)),
+	};
+}

package/src/operations/session-identity-operations.ts

@@ -0,0 +1,15 @@
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { OperationHandlerMap } from "./types.ts";
+import { requiredString, routerSessionSecret } from "./session-scope.ts";
+
+/** session.register and session.release -- the only two operations that mutate SessionIdentity itself, distinct from the router mutations it later authorizes. */
+export function sessionIdentityOperations(sessionIdentity: SessionIdentity | undefined): OperationHandlerMap {
+	const require = (): SessionIdentity => {
+		if (!sessionIdentity) throw new Error("session identity is not configured");
+		return sessionIdentity;
+	};
+	return {
+		"session.register": (input) => require().register(requiredString(input, "session_id")),
+		"session.release": (input) => require().release(requiredString(input, "session_id"), routerSessionSecret(input)),
+	};
+}

package/src/operations/session-scope.ts

@@ -0,0 +1,31 @@
+import type { SessionIdentity } from "../session-identity-service.ts";
+
+/** Shared input parsing for every operation that accepts an optional session_id/session_secret pair. */
+export function routerSessionId(input: Record<string, unknown>): string | undefined {
+	const value = input["session_id"];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error("session_id must be a string");
+	return value;
+}
+
+export function routerSessionSecret(input: Record<string, unknown>): string | undefined {
+	const value = input["session_secret"];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error("session_secret must be a string");
+	return value;
+}
+
+export function requiredString(input: Record<string, unknown>, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+/** Opt-in armor: a session_id never registered via session.register mutates exactly as before. Bound once per JittorService instance and shared by every router-mutating operation module. */
+export function routerMutationAuthorizer(sessionIdentity: SessionIdentity | undefined): (input: Record<string, unknown>) => string | undefined {
+	return (input) => {
+		const sessionId = routerSessionId(input);
+		sessionIdentity?.assertAuthorized(sessionId, routerSessionSecret(input));
+		return sessionId;
+	};
+}

package/src/operations/types.ts

@@ -0,0 +1,3 @@
+/** One capability module's contribution to the operation dispatch table: a bounded set of operation names, each backed by a handler that only needs the collaborators its own factory was given. */
+export type OperationHandler = (input: Record<string, unknown>) => unknown | Promise<unknown>;
+export type OperationHandlerMap = Partial<Record<string, OperationHandler>>;

package/src/ports/metric-store.ts

@@ -20,6 +20,8 @@ export interface UsageAggregateFilter {
 
 export interface MetricStore {
 	record(observation: MetricObservation): StoredMetricObservation;
+	/** Validates and writes every observation in one atomic transaction: either all rows land, or none do -- a single-event RPC loop can otherwise leave a partially-persisted event when a later observation in the same event fails validation or the connection drops mid-loop. */
+	recordBatch(observations: MetricObservation[]): StoredMetricObservation[];
 	query(filter?: MetricQuery): StoredMetricObservation[];
 	/** Bounded distinct scope values for a source within a time window, so callers can fetch a fair share per scope instead of one flat query a single heavy scope could monopolize. */
 	distinctScopes(filter: DistinctScopesFilter): string[];

package/src/ports/router-controller.ts

@@ -31,13 +31,13 @@ export interface RouterStatus {
 
 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;
-	applyModelRanking?(candidates: Route[]): RouterStatus;
+	status(sessionId?: string): RouterStatus;
+	decide(sessionId?: string): PolicyDecision;
+	pause(sessionId?: string): RouterStatus;
+	resume(sessionId?: string): RouterStatus;
+	setOverride(override: RouteOverride | undefined, sessionId?: string): RouterStatus;
+	clearOverride(sessionId?: string): RouterStatus;
+	setCurrentRoute(route: Route, sessionId?: string): RouterStatus;
+	setAvailableRoutes(routes: Route[], sessionId?: string): RouterStatus;
+	applyModelRanking?(candidates: Route[], sessionId?: string): RouterStatus;
 }

package/src/ports/session-identity-store.ts

@@ -0,0 +1,5 @@
+import type { SessionIdentityRecord, SessionIdentityStore as DaemonKitSessionIdentityStore } from "@danypops/daemon-kit/session-identity";
+
+/** Jittor's persistence port for daemon-kit's storage-agnostic session-identity primitive. */
+export type SessionIdentityStore = DaemonKitSessionIdentityStore;
+export type { SessionIdentityRecord };

package/src/providers/telemetry-sources.ts

@@ -79,7 +79,7 @@ export class OpenRouterTelemetrySource implements TelemetrySource {
  */
 export class GoogleVertexBudgetTelemetrySource implements TelemetrySource {
 	readonly id: string;
-	readonly provider = "google-vertex";
+	readonly provider: GoogleVertexMetricSource;
 	readonly required = false;
 
 	private readonly adapter: GoogleVertexBudgetTelemetryAdapter;
@@ -92,6 +92,7 @@ export class GoogleVertexBudgetTelemetrySource implements TelemetrySource {
 		source: GoogleVertexMetricSource = "google-vertex",
 	) {
 		this.id = `google-vertex-budget:${source}`;
+		this.provider = source;
 		this.adapter = new GoogleVertexBudgetTelemetryAdapter(subscription, tokenProvider, transport, source);
 	}
 

package/src/router.ts

@@ -1,3 +1,4 @@
+import { ROUTER_MAX_SESSION_SCOPES, ROUTER_SESSION_ID_MAX_CHARACTERS } from "./constants.ts";
 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";
@@ -22,22 +23,37 @@ function sameRoute(left: Route, right: Route): boolean {
 	return left.provider === right.provider && left.model === right.model && left.thinking === right.thinking;
 }
 
+const GLOBAL_ROUTER_SCOPE = "global";
+
+interface RouterSessionState {
+	currentRoute: Route;
+	availableRoutes: Route[];
+	lastDecision: PolicyDecision | null;
+	previousPolicyDecision: PolicyDecision | null;
+	paused: boolean;
+	override: RouteOverride | null;
+	lastAccess: number;
+}
+
+function routerScope(sessionId: string | undefined): string {
+	if (sessionId === undefined) return GLOBAL_ROUTER_SCOPE;
+	if (sessionId.length === 0 || sessionId.length > ROUTER_SESSION_ID_MAX_CHARACTERS) {
+		throw new Error(`session_id must contain 1-${ROUTER_SESSION_ID_MAX_CHARACTERS} characters`);
+	}
+	return sessionId;
+}
+
 export class JittorRouter implements RouterController {
 	private readonly clock: () => number;
 	private readonly windows = new Map<string, BudgetWindow[]>();
+	private readonly sessions = new Map<string, RouterSessionState>();
 	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[];
+	private accessSequence = 0;
 
 	constructor(private readonly options: JittorRouterOptions) {
 		this.clock = options.clock ?? Date.now;
-		this.currentRoute = options.currentRoute;
-		this.availableRoutes = structuredClone(options.routes);
+		this.sessions.set(GLOBAL_ROUTER_SCOPE, this.newSessionState());
 	}
 
 	poll(): Promise<TelemetryPollResult> {
@@ -45,91 +61,102 @@ export class JittorRouter implements RouterController {
 		return this.inFlightPoll;
 	}
 
-	status(): RouterStatus {
-		this.expireOverride();
+	status(sessionId?: string): RouterStatus {
+		const state = this.sessionState(sessionId);
+		this.expireOverride(state);
 		return {
-			ready: this.isReady(),
-			paused: this.paused,
+			ready: this.isReady(state),
+			paused: state.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),
+			lastDecision: state.lastDecision ? structuredClone(state.lastDecision) : null,
+			override: state.override ? structuredClone(state.override) : null,
+			currentRoute: structuredClone(state.currentRoute),
+			availableRoutes: structuredClone(state.availableRoutes),
 		};
 	}
 
-	decide(): PolicyDecision {
+	decide(sessionId?: string): 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
+		const state = this.sessionState(sessionId);
+		this.expireOverride(state);
+		if (state.paused) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "Jittor is paused", decidedAt: now, trace: ["manual pause"] });
+		if (state.override) {
+			const route = state.override.route;
+			const action = route.provider !== state.currentRoute.provider
 				? "switch-provider"
-				: route.model !== this.currentRoute.model
+				: route.model !== state.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"] });
+					: route.thinking !== state.currentRoute.thinking ? "lower-thinking" : "continue";
+			return this.remember(state, { action, route, pressure: 0, reason: "manual route override", decidedAt: now, trace: ["manual override"] });
+		}
+		if (!this.isReady(state)) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "required telemetry is not ready", decidedAt: now, trace: ["fail closed"] });
+		const activeSources = this.options.sources.filter((source) => source.provider === state.currentRoute.provider);
+		const activeSourceIds = new Set(activeSources.map((source) => source.id));
+		const requiredSourceIds = new Set(activeSources.filter((source) => source.required).map((source) => source.id));
+		const activeWindows = [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId));
+		const requiredWindows = activeWindows.filter(([sourceId]) => requiredSourceIds.has(sourceId)).flatMap(([, windows]) => windows);
+		if (requiredSourceIds.size === 0 && activeWindows.every(([, windows]) => windows.length === 0)) {
+			return this.rememberPolicy(state, { action: "continue", pressure: 0, reason: "provider has no enforceable budget window; monitor-only", decidedAt: now, trace: ["monitor-only"] });
 		}
-		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({
+		return this.rememberPolicy(state, evaluateRoutingPolicy({
 			now,
-			windows: [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId)).flatMap(([, windows]) => windows),
-			currentRoute: this.currentRoute,
-			routes: this.availableRoutes,
+			windows: requiredSourceIds.size > 0 && requiredWindows.length === 0 ? [] : activeWindows.flatMap(([, windows]) => windows),
+			currentRoute: state.currentRoute,
+			routes: state.availableRoutes,
 			config: this.options.policy,
-			previousDecision: this.previousPolicyDecision ?? undefined,
+			previousDecision: state.previousPolicyDecision ?? undefined,
 		}));
 	}
 
-	pause(): RouterStatus {
-		this.paused = true;
-		return this.status();
+	pause(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).paused = true;
+		return this.status(sessionId);
 	}
 
-	resume(): RouterStatus {
-		this.paused = false;
-		return this.status();
+	resume(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).paused = false;
+		return this.status(sessionId);
 	}
 
-	setOverride(override?: RouteOverride): RouterStatus {
-		if (!override || !this.availableRoutes.some((route) => sameRoute(route, override.route))) throw new Error("override route is not available in Pi");
+	setOverride(override: RouteOverride | undefined, sessionId?: string): RouterStatus {
+		const state = this.sessionState(sessionId);
+		if (!override || !state.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();
+		state.override = structuredClone(override);
+		return this.status(sessionId);
 	}
 
-	clearOverride(): RouterStatus {
-		this.override = null;
-		return this.status();
+	clearOverride(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).override = null;
+		return this.status(sessionId);
 	}
 
-	setCurrentRoute(route: Route): RouterStatus {
+	setCurrentRoute(route: Route, sessionId?: string): RouterStatus {
 		if (!route.provider || !route.model || !route.thinking) throw new Error("current route is incomplete");
-		this.currentRoute = structuredClone(route);
-		return this.status();
+		this.sessionState(sessionId).currentRoute = structuredClone(route);
+		return this.status(sessionId);
 	}
 
-	setAvailableRoutes(routes: Route[]): RouterStatus {
+	setAvailableRoutes(routes: Route[], sessionId?: string): 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();
+		this.sessionState(sessionId).availableRoutes = valid.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index).map((route) => structuredClone(route));
+		return this.status(sessionId);
 	}
 
-	applyModelRanking(candidates: Route[]): RouterStatus {
+	applyModelRanking(candidates: Route[], sessionId?: string): RouterStatus {
 		if (!Array.isArray(candidates) || candidates.length === 0) throw new Error("model ranking must contain candidates");
+		const state = this.sessionState(sessionId);
 		const ranked = candidates
 			.filter((candidate, index) => candidates.findIndex((other) => sameRoute(other, candidate)) === index)
-			.map((candidate) => this.availableRoutes.find((route) => sameRoute(route, candidate)))
+			.map((candidate) => state.availableRoutes.find((route) => sameRoute(route, candidate)))
 			.filter((route): route is Route => route !== undefined);
-		const current = ranked.find((route) => sameRoute(route, this.currentRoute));
+		const current = ranked.find((route) => sameRoute(route, state.currentRoute));
 		if (!current) throw new Error("model ranking does not contain the current available route");
-		this.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
-		return this.status();
+		state.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
+		return this.status(sessionId);
 	}
 
 	private async runPoll(): Promise<TelemetryPollResult> {
@@ -148,23 +175,53 @@ export class JittorRouter implements RouterController {
 		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 newSessionState(): RouterSessionState {
+		return {
+			currentRoute: structuredClone(this.options.currentRoute),
+			availableRoutes: structuredClone(this.options.routes),
+			lastDecision: null,
+			previousPolicyDecision: null,
+			paused: false,
+			override: null,
+			lastAccess: ++this.accessSequence,
+		};
+	}
+
+	private sessionState(sessionId?: string): RouterSessionState {
+		const scope = routerScope(sessionId);
+		const existing = this.sessions.get(scope);
+		if (existing) {
+			existing.lastAccess = ++this.accessSequence;
+			return existing;
+		}
+		if (this.sessions.size >= ROUTER_MAX_SESSION_SCOPES) {
+			const oldest = [...this.sessions.entries()]
+				.filter(([key]) => key !== GLOBAL_ROUTER_SCOPE)
+				.sort((left, right) => left[1].lastAccess - right[1].lastAccess)[0];
+			if (oldest) this.sessions.delete(oldest[0]);
+		}
+		const created = this.newSessionState();
+		this.sessions.set(scope, created);
+		return created;
+	}
+
+	private isReady(state: RouterSessionState): boolean {
+		if (state.availableRoutes.length === 0) return false;
+		const required = this.options.sources.filter((source) => source.provider === state.currentRoute.provider && source.required);
+		return required.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 expireOverride(state: RouterSessionState): void {
+		if (state.override?.expiresAt !== null && state.override && state.override.expiresAt <= this.clock()) state.override = null;
 	}
 
-	private remember(decision: PolicyDecision): PolicyDecision {
-		this.lastDecision = decision;
+	private remember(state: RouterSessionState, decision: PolicyDecision): PolicyDecision {
+		state.lastDecision = decision;
 		return structuredClone(decision);
 	}
 
-	private rememberPolicy(decision: PolicyDecision): PolicyDecision {
-		this.previousPolicyDecision = decision;
-		return this.remember(decision);
+	private rememberPolicy(state: RouterSessionState, decision: PolicyDecision): PolicyDecision {
+		state.previousPolicyDecision = decision;
+		return this.remember(state, decision);
 	}
 }