@danypops/jittor 0.1.2 → 0.2.1

package/README.md

@@ -39,6 +39,21 @@ The native Pi extension preflights input and every provider turn, applies model/
 
 Blocking always has a daemon-independent escape hatch. `/jittor off` immediately enters persisted monitor-only mode and never blocks provider requests. The informational footer is independently controlled with `/jittor footer on` and `/jittor footer off`, so showing status never enables enforcement. `/jittor on` only enables enforcement after telemetry polling and available-route synchronization succeed. Every fail-closed error includes these recovery commands plus the daemon restart command.
 
+### Opt-in Codex settled-turn recovery
+
+Transient Codex recovery is securely off by default and controlled through the existing Jittor command surface:
+
+```text
+/jittor recovery status
+/jittor recovery on
+/jittor recovery off
+/jittor recovery cancel
+```
+
+The on/off choice persists privately in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`). Status reports only enabled state, cooldown, bounded attempt/window counters, and the normalized failure class. `cancel` clears the current cooldown and attempt window without changing the persisted on/off choice.
+
+Jittor observes finalized Codex assistant errors through Pi's public message lifecycle, classifies only bounded error metadata, and waits for `agent_settled` before acting. That boundary guarantees Pi's built-in retry, compaction retry, and queued follow-up work has finished. A transient concurrency, rate-limit, overload, or transport failure then schedules one hidden follow-up with Retry-After-aware capped jitter. Recovery is limited to three attempts per ten-minute window, never overlaps pending Pi messages, resets after success, and is canceled by human input or session shutdown. Quota, authentication, invalid-request, unknown, and aborted failures remain terminal. Raw provider payloads are never retained or injected.
+
 Run `/jittor usage` for a colored Unicode token histogram with X/Y axes, provider/model series, input/output/cache totals, refresh, and `24h`, `7d`, `30d`, or `90d` ranges. Left/Right changes range and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
 
 See [`docs/CALIBRATION.md`](docs/CALIBRATION.md) for thresholds and rollback, and [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.

package/extension/src/index.ts

@@ -1,12 +1,23 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { FOOTER_COMPACTION_RENDER_INTERVAL_MS, MAX_DYNAMIC_ROUTES } from "../../src/constants.ts";
+import {
+	CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+	CODEX_RECOVERY_BASE_DELAY_MS,
+	CODEX_RECOVERY_JITTER_RATIO,
+	CODEX_RECOVERY_MAX_ATTEMPTS,
+	CODEX_RECOVERY_MAX_DELAY_MS,
+	FOOTER_COMPACTION_RENDER_INTERVAL_MS,
+	MAX_DYNAMIC_ROUTES,
+	MILLISECONDS_PER_MINUTE,
+	MILLISECONDS_PER_SECOND,
+} from "../../src/constants.ts";
+import { CodexRecoveryPolicy, classifyCodexFailure, type CodexFailureKind, type CodexFailureMetadata } from "../../src/domain/codex-recovery.ts";
 import type { MetricObservation, StoredMetricObservation } from "../../src/domain/metric.ts";
 import type { PolicyDecision, Route } from "../../src/policy.ts";
 import type { RouterStatus } from "../../src/ports/router-controller.ts";
 import { parseCodexRateLimitHeaders } from "../../src/providers/codex.ts";
 import { installIntegratedFooter, type IntegratedFooterState } from "./footer.ts";
 import { callJittor } from "./service-client.ts";
-import { persistentEnforcementControl, type EnforcementControl } from "./settings.ts";
+import { persistentEnforcementControl, type CodexRecoveryControl, type EnforcementControl } from "./settings.ts";
 import { buildFooterBudget, formatFooterStatus, showJittorPanel } from "./tui.ts";
 import { showUsagePanel } from "./usage.ts";
 
@@ -23,6 +34,36 @@ const daemonClient: JittorExtensionClient = {
 	call: (operation, input) => callJittor(operation as Parameters<typeof callJittor>[0], input as never),
 };
 
+export interface CodexRecoveryRuntime {
+	now(): number;
+	random(): number;
+	setTimeout(callback: () => void | Promise<void>, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+const SYSTEM_RECOVERY_RUNTIME: CodexRecoveryRuntime = {
+	now: Date.now,
+	random: Math.random,
+	setTimeout(callback, delayMs) { return setTimeout(() => { void callback(); }, delayMs); },
+	clearTimeout(handle) { clearTimeout(handle as ReturnType<typeof setTimeout>); },
+};
+
+function recoveryControl(enforcement: EnforcementControl): CodexRecoveryControl {
+	const candidate = enforcement as EnforcementControl & Partial<CodexRecoveryControl>;
+	const set = (candidate as Partial<CodexRecoveryControl>).setCodexRecoveryEnabled;
+	return typeof candidate.isCodexRecoveryEnabled === "function" && typeof set === "function"
+		? {
+			isCodexRecoveryEnabled: () => candidate.isCodexRecoveryEnabled!(),
+			setCodexRecoveryEnabled: (enabled) => set.call(candidate, enabled),
+		}
+		: { isCodexRecoveryEnabled: () => false, setCodexRecoveryEnabled() {} };
+}
+
+function header(headers: Record<string, string>, name: string): string | undefined {
+	const expected = name.toLowerCase();
+	return Object.entries(headers).find(([key]) => key.toLowerCase() === expected)?.[1];
+}
+
 async function recordMetrics(client: JittorExtensionClient, metrics: MetricObservation[]): Promise<void> {
 	for (const metric of metrics) await client.call("metrics.record", metric);
 }
@@ -169,8 +210,69 @@ export function registerJittorExtension(
 	pi: ExtensionAPI,
 	client: JittorExtensionClient = daemonClient,
 	enforcement: EnforcementControl = persistentEnforcementControl(),
+	codexRecovery: CodexRecoveryControl = recoveryControl(enforcement),
+	recoveryRuntime: CodexRecoveryRuntime = SYSTEM_RECOVERY_RUNTIME,
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
+	const recoveryPolicy = new CodexRecoveryPolicy({
+		baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
+		maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
+		maxAttempts: CODEX_RECOVERY_MAX_ATTEMPTS,
+		attemptWindowMs: CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+		jitterRatio: CODEX_RECOVERY_JITTER_RATIO,
+	}, recoveryRuntime.random);
+	let recoveryTimer: unknown;
+	let recoveryCooldown: { until: number; attempt: number; failureKind: CodexFailureKind } | undefined;
+	let lastCodexResponse: CodexFailureMetadata = {};
+	const cancelRecovery = (resetPolicy: boolean): void => {
+		if (recoveryTimer !== undefined) recoveryRuntime.clearTimeout(recoveryTimer);
+		recoveryTimer = undefined;
+		recoveryCooldown = undefined;
+		if (resetPolicy) recoveryPolicy.cancel();
+	};
+	const recoveryStatusText = (): string => {
+		const now = recoveryRuntime.now();
+		const state = recoveryPolicy.state(now);
+		const enabled = codexRecovery.isCodexRecoveryEnabled();
+		const attempt = recoveryCooldown?.attempt ?? (state.pending ? state.attempts + 1 : state.attempts);
+		const phase = recoveryCooldown
+			? `cooldown ${Math.ceil(Math.max(0, recoveryCooldown.until - now) / MILLISECONDS_PER_SECOND)}s`
+			: state.pending ? "pending"
+				: state.attempts >= CODEX_RECOVERY_MAX_ATTEMPTS ? "exhausted"
+					: state.attempts > 0 ? "waiting" : "idle";
+		const failureKind = recoveryCooldown?.failureKind ?? state.lastFailureKind;
+		return [
+			`Codex recovery: ${enabled ? "on" : "off"}`,
+			phase,
+			`attempt ${attempt}/${CODEX_RECOVERY_MAX_ATTEMPTS}`,
+			`window ${CODEX_RECOVERY_ATTEMPT_WINDOW_MS / MILLISECONDS_PER_MINUTE}m`,
+			...(failureKind ? [failureKind] : []),
+		].join(" · ");
+	};
+	const scheduleCodexRecovery = (ctx: ExtensionContext): void => {
+		if (!codexRecovery.isCodexRecoveryEnabled() || recoveryTimer !== undefined || !ctx.isIdle() || ctx.hasPendingMessages()) return;
+		const plan = recoveryPolicy.plan(recoveryRuntime.now());
+		if (plan.action === "exhausted") {
+			recoveryPolicy.abandonFailure();
+			if (ctx.hasUI) ctx.ui.notify(`Jittor Codex recovery stopped: ${plan.reason}.`, "warning");
+			return;
+		}
+		if (plan.action !== "schedule") return;
+		recoveryCooldown = { until: recoveryRuntime.now() + plan.delayMs, attempt: plan.attempt, failureKind: plan.failureKind };
+		recoveryTimer = recoveryRuntime.setTimeout(async () => {
+			recoveryTimer = undefined;
+			recoveryCooldown = undefined;
+			if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+			const attempt = recoveryPolicy.recordAttempt(recoveryRuntime.now());
+			if (!attempt) return;
+			pi.sendMessage({
+				customType: "jittor-codex-recovery",
+				content: `Retry the previous Codex request after a transient ${attempt.failureKind} failure. Automatic recovery attempt ${attempt.attempt} of ${CODEX_RECOVERY_MAX_ATTEMPTS}.`,
+				display: false,
+				details: { attempt: attempt.attempt, failureKind: attempt.failureKind },
+			}, { triggerTurn: true, deliverAs: "followUp" });
+		}, plan.delayMs);
+	};
 	let compactionTimer: ReturnType<typeof setInterval> | undefined;
 	const finishCompaction = (): void => {
 		if (compactionTimer) clearInterval(compactionTimer);
@@ -223,6 +325,26 @@ export function registerJittorExtension(
 		description: "Inspect or control Jittor routing, budgets, and usage",
 		handler: async (args, ctx) => {
 			const action = args.trim().toLowerCase();
+			if (action === "recovery" || action === "recovery status") {
+				ctx.ui.notify(recoveryStatusText(), "info");
+				return;
+			}
+			if (action === "recovery on" || action === "recovery enable") {
+				codexRecovery.setCodexRecoveryEnabled(true);
+				ctx.ui.notify("Jittor Codex recovery enabled; bounded retries begin only after transient failures fully settle.", "info");
+				return;
+			}
+			if (action === "recovery off" || action === "recovery disable") {
+				cancelRecovery(true);
+				codexRecovery.setCodexRecoveryEnabled(false);
+				ctx.ui.notify("Jittor Codex recovery disabled and pending recovery cleared.", "info");
+				return;
+			}
+			if (action === "recovery cancel") {
+				cancelRecovery(true);
+				ctx.ui.notify(`Jittor Codex recovery cooldown and attempt window cleared; recovery remains ${codexRecovery.isCodexRecoveryEnabled() ? "on" : "off"}.`, "info");
+				return;
+			}
 			if (action === "off" || action === "disable") { disable(ctx); return; }
 			if (action === "on" || action === "enable") { await enable(ctx); return; }
 			if (action === "footer off" || action === "footer disable") {
@@ -252,6 +374,8 @@ export function registerJittorExtension(
 
 	pi.on("session_start", async (_event, ctx) => {
 		finishCompaction();
+		cancelRecovery(true);
+		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);
 		showFooter(ctx);
 		try {
@@ -273,11 +397,22 @@ export function registerJittorExtension(
 		finishCompaction();
 	});
 
-	pi.on("agent_settled", () => {
+	pi.on("agent_settled", async (_event, ctx) => {
 		if (footerState.compaction) finishCompaction();
+		scheduleCodexRecovery(ctx);
+		if (!enforcement.isFooterEnabled()) return;
+		try {
+			await syncCurrentRoute(pi, client, ctx);
+			await syncAvailableRoutes(pi, client, ctx);
+			await refreshFooter(client, footerState);
+		} catch {
+			footerState.providerBudget = null;
+			footerState.requestRender?.();
+		}
 	});
 
 	pi.on("input", async (event, ctx) => {
+		if (event.source !== "extension") cancelRecovery(true);
 		if (event.source === "extension" || !enforcement.isEnabled()) return { action: "continue" as const };
 		try {
 			const next = await client.call("router.decide", {}) as PolicyDecision;
@@ -302,6 +437,7 @@ export function registerJittorExtension(
 	});
 
 	pi.on("turn_start", async (_event, ctx) => {
+		lastCodexResponse = {};
 		if (!enforcement.isEnabled()) return;
 		try {
 			await syncCurrentRoute(pi, client, ctx);
@@ -314,6 +450,9 @@ export function registerJittorExtension(
 	});
 
 	pi.on("after_provider_response", async (event, ctx) => {
+		if (ctx.model?.provider === "openai-codex") {
+			lastCodexResponse = { status: event.status, ...(header(event.headers, "retry-after") ? { retryAfter: header(event.headers, "retry-after") } : {}) };
+		}
 		if (!Object.keys(event.headers).some((name) => name.toLowerCase().startsWith("x-codex-"))) return;
 		try {
 			const updates = parseCodexRateLimitHeaders(new Headers(event.headers), Date.now());
@@ -325,6 +464,16 @@ export function registerJittorExtension(
 	});
 
 	pi.on("message_end", async (event, _ctx) => {
+		if (event.message.role === "assistant" && event.message.provider === "openai-codex") {
+			if (event.message.stopReason === "error") {
+				const failure = classifyCodexFailure(event.message.errorMessage, lastCodexResponse);
+				if (codexRecovery.isCodexRecoveryEnabled() && failure.transient) recoveryPolicy.observeFailure(failure, recoveryRuntime.now());
+				else cancelRecovery(true);
+			} else if (event.message.stopReason !== "aborted") {
+				cancelRecovery(true);
+			}
+			lastCodexResponse = {};
+		}
 		const metrics = assistantUsageMetrics(event.message, Date.now());
 		if (metrics.length > 0) await recordMetrics(client, metrics).catch(() => undefined);
 		if (enforcement.isFooterEnabled()) await refreshFooter(client, footerState).catch(() => undefined);
@@ -332,6 +481,8 @@ export function registerJittorExtension(
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		finishCompaction();
+		cancelRecovery(true);
+		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);
 		ctx.ui.setFooter(undefined);
 	});

package/extension/src/settings.ts

@@ -9,9 +9,19 @@ export interface EnforcementControl {
 	setFooterEnabled(enabled: boolean): void;
 }
 
+export interface CodexRecoveryControl {
+	isCodexRecoveryEnabled(): boolean;
+	setCodexRecoveryEnabled(enabled: boolean): void;
+}
+
+export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl {
+	setCodexRecoveryEnabled(enabled: boolean): void;
+}
+
 interface ExtensionSettings {
 	enforcementEnabled: boolean;
 	footerEnabled: boolean;
+	codexRecoveryEnabled: boolean;
 }
 
 function settingsPath(env: Record<string, string | undefined> = process.env): string {
@@ -22,14 +32,15 @@ function settingsPath(env: Record<string, string | undefined> = process.env): st
 function loadSettings(path: string): ExtensionSettings {
 	try {
 		const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
-		if (typeof value !== "object" || value === null || Array.isArray(value)) return { enforcementEnabled: true, footerEnabled: true };
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false };
 		const record = value as Record<string, unknown>;
 		return {
 			enforcementEnabled: record["enforcementEnabled"] !== false,
 			footerEnabled: record["footerEnabled"] !== false,
+			codexRecoveryEnabled: record["codexRecoveryEnabled"] === true,
 		};
 	} catch {
-		return { enforcementEnabled: true, footerEnabled: true };
+		return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false };
 	}
 }
 
@@ -41,7 +52,7 @@ function persistSettings(path: string, settings: ExtensionSettings): void {
 	renameSync(temporary, path);
 }
 
-export function persistentEnforcementControl(env: Record<string, string | undefined> = process.env): EnforcementControl {
+export function persistentEnforcementControl(env: Record<string, string | undefined> = process.env): PersistentExtensionControl {
 	const path = settingsPath(env);
 	const settings = loadSettings(path);
 	return {
@@ -55,5 +66,10 @@ export function persistentEnforcementControl(env: Record<string, string | undefi
 			settings.footerEnabled = value;
 			persistSettings(path, settings);
 		},
+		isCodexRecoveryEnabled: () => settings.codexRecoveryEnabled,
+		setCodexRecoveryEnabled(value: boolean): void {
+			settings.codexRecoveryEnabled = value;
+			persistSettings(path, settings);
+		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],

package/src/constants.ts

@@ -1,4 +1,3 @@
-export const VERSION = "0.1.2";
 export const SQLITE_SCHEMA_VERSION = 1;
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
 export const DEFAULT_QUERY_LIMIT = 1_000;
@@ -30,3 +29,10 @@ export const USAGE_CHART_HEIGHT = 8;
 export const USAGE_Y_AXIS_WIDTH = 7;
 export const USAGE_TOKEN_QUERY_LIMIT = 10_000;
 export const MAX_DYNAMIC_ROUTES = 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;
+export const CODEX_RECOVERY_MAX_DELAY_MS = CODEX_RETRY_AFTER_MAX_MS;
+export const CODEX_RECOVERY_MAX_ATTEMPTS = 3;
+export const CODEX_RECOVERY_ATTEMPT_WINDOW_MS = 10 * MILLISECONDS_PER_MINUTE;
+export const CODEX_RECOVERY_JITTER_RATIO = 0.2;

package/src/domain/codex-recovery.ts

@@ -0,0 +1,205 @@
+import {
+	CODEX_ERROR_MESSAGE_LIMIT,
+	CODEX_RETRY_AFTER_MAX_MS,
+	MILLISECONDS_PER_SECOND,
+} from "../constants.ts";
+
+export type CodexFailureKind =
+	| "concurrency"
+	| "rate-limit"
+	| "overload"
+	| "transport"
+	| "quota"
+	| "authentication"
+	| "invalid-request"
+	| "unknown";
+
+export interface CodexFailure {
+	kind: CodexFailureKind;
+	transient: boolean;
+	code?: string;
+	source?: string;
+	message?: string;
+	retryAfterMs?: number;
+}
+
+export interface CodexFailureMetadata {
+	status?: number;
+	retryAfter?: string;
+}
+
+export interface CodexRecoveryOptions {
+	baseDelayMs: number;
+	maxDelayMs: number;
+	maxAttempts: number;
+	attemptWindowMs: number;
+	jitterRatio: number;
+}
+
+export type CodexRecoveryPlan =
+	| { action: "schedule"; attempt: number; delayMs: number; failureKind: CodexFailureKind }
+	| { action: "wait"; reason: string }
+	| { action: "exhausted"; reason: string };
+
+export interface CodexRecoveryAttempt {
+	attempt: number;
+	failureKind: CodexFailureKind;
+}
+
+export class CodexRecoveryPolicy {
+	private pendingFailure: CodexFailure | undefined;
+	private attempts = 0;
+	private windowStartedAt: number | undefined;
+	private lastFailureKind: CodexFailureKind | undefined;
+
+	constructor(
+		private readonly options: CodexRecoveryOptions,
+		private readonly random: () => number = Math.random,
+	) {
+		if (!Number.isFinite(options.baseDelayMs) || options.baseDelayMs < 0) throw new Error("baseDelayMs must be non-negative");
+		if (!Number.isFinite(options.maxDelayMs) || options.maxDelayMs < options.baseDelayMs) throw new Error("maxDelayMs must be at least baseDelayMs");
+		if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) throw new Error("maxAttempts must be a positive integer");
+		if (!Number.isFinite(options.attemptWindowMs) || options.attemptWindowMs <= 0) throw new Error("attemptWindowMs must be positive");
+		if (!Number.isFinite(options.jitterRatio) || options.jitterRatio < 0 || options.jitterRatio > 1) throw new Error("jitterRatio must be between 0 and 1");
+	}
+
+	observeFailure(failure: CodexFailure, now: number): void {
+		this.normalizeWindow(now);
+		this.pendingFailure = failure.transient ? failure : undefined;
+		this.lastFailureKind = failure.transient ? failure.kind : undefined;
+	}
+
+	observeSuccess(): void {
+		this.cancel();
+	}
+
+	cancel(): void {
+		this.pendingFailure = undefined;
+		this.attempts = 0;
+		this.windowStartedAt = undefined;
+		this.lastFailureKind = undefined;
+	}
+
+	abandonFailure(): void {
+		this.pendingFailure = undefined;
+	}
+
+	plan(now: number): CodexRecoveryPlan {
+		this.normalizeWindow(now);
+		if (!this.pendingFailure) return { action: "wait", reason: "no transient Codex failure is pending" };
+		if (this.attempts >= this.options.maxAttempts) {
+			return { action: "exhausted", reason: `${this.options.maxAttempts} recovery attempts reached within ${this.options.attemptWindowMs}ms` };
+		}
+		const base = this.pendingFailure.retryAfterMs
+			?? this.options.baseDelayMs * (2 ** this.attempts);
+		const sample = this.random();
+		const unit = Number.isFinite(sample) ? Math.min(1, Math.max(0, sample)) : 0;
+		const multiplier = 1 + ((unit * 2) - 1) * this.options.jitterRatio;
+		const jittered = Math.max(0, Math.round(base * multiplier));
+		const delayMs = this.pendingFailure.retryAfterMs === undefined ? jittered : Math.max(base, jittered);
+		return {
+			action: "schedule",
+			attempt: this.attempts + 1,
+			delayMs: Math.min(this.options.maxDelayMs, delayMs),
+			failureKind: this.pendingFailure.kind,
+		};
+	}
+
+	recordAttempt(now: number): CodexRecoveryAttempt | undefined {
+		this.normalizeWindow(now);
+		if (!this.pendingFailure || this.attempts >= this.options.maxAttempts) return undefined;
+		if (this.windowStartedAt === undefined) this.windowStartedAt = now;
+		this.attempts += 1;
+		const attempt = { attempt: this.attempts, failureKind: this.pendingFailure.kind };
+		this.pendingFailure = undefined;
+		return attempt;
+	}
+
+	state(now?: number): { attempts: number; pending: boolean; lastFailureKind?: CodexFailureKind; windowStartedAt?: number } {
+		if (now !== undefined) this.normalizeWindow(now);
+		return {
+			attempts: this.attempts,
+			pending: this.pendingFailure !== undefined,
+			...(this.lastFailureKind ? { lastFailureKind: this.lastFailureKind } : {}),
+			...(this.windowStartedAt !== undefined ? { windowStartedAt: this.windowStartedAt } : {}),
+		};
+	}
+
+	private normalizeWindow(now: number): void {
+		if (this.windowStartedAt !== undefined && now - this.windowStartedAt >= this.options.attemptWindowMs) {
+			this.attempts = 0;
+			this.windowStartedAt = undefined;
+			if (!this.pendingFailure) this.lastFailureKind = undefined;
+		}
+	}
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: undefined;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+	for (const value of values) {
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+function retryAfterMs(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value.trim());
+	if (!Number.isFinite(seconds) || seconds < 0) return undefined;
+	return Math.min(CODEX_RETRY_AFTER_MAX_MS, Math.round(seconds * MILLISECONDS_PER_SECOND));
+}
+
+function matches(value: string, patterns: readonly string[]): boolean {
+	return patterns.some((pattern) => value.includes(pattern));
+}
+
+export function classifyCodexFailure(value: unknown, metadata: CodexFailureMetadata = {}): CodexFailure {
+	const root = asRecord(value);
+	const detail = asRecord(root?.["detail"]);
+	const nestedError = asRecord(root?.["error"]);
+	const code = firstString(detail?.["code"], detail?.["error_code"], nestedError?.["code"], root?.["code"]);
+	const source = firstString(detail?.["source"], nestedError?.["source"], root?.["source"]);
+	const rawMessage = firstString(
+		detail?.["message"],
+		typeof root?.["error"] === "string" ? root["error"] : undefined,
+		nestedError?.["message"],
+		root?.["message"],
+		typeof value === "string" ? value : undefined,
+	);
+	const message = rawMessage?.slice(0, CODEX_ERROR_MESSAGE_LIMIT);
+	const evidence = [code, source, message].filter(Boolean).join(" ").toLowerCase();
+	const base = {
+		...(code ? { code } : {}),
+		...(source ? { source } : {}),
+		...(message ? { message } : {}),
+		...(retryAfterMs(metadata.retryAfter) !== undefined ? { retryAfterMs: retryAfterMs(metadata.retryAfter) } : {}),
+	};
+
+	if (matches(evidence, ["insufficient_quota", "quota exceeded", "out of credits", "billing"])) {
+		return { kind: "quota", transient: false, ...base };
+	}
+	if (metadata.status === 401 || metadata.status === 403 || matches(evidence, ["invalid_api_key", "authentication", "unauthorized", "permission_denied"])) {
+		return { kind: "authentication", transient: false, ...base };
+	}
+	if (matches(evidence, ["invalid_prompt", "invalid_request", "context_length_exceeded"]) || metadata.status === 400 || metadata.status === 422) {
+		return { kind: "invalid-request", transient: false, ...base };
+	}
+	if (matches(evidence, ["concurrency_limit", "too many concurrent requests", "throttled"])) {
+		return { kind: "concurrency", transient: true, ...base };
+	}
+	if (matches(evidence, ["server_is_overloaded", "slow_down", "service unavailable", "overloaded"]) || (metadata.status !== undefined && metadata.status >= 500 && metadata.status <= 599)) {
+		return { kind: "overload", transient: true, ...base };
+	}
+	if (metadata.status === 429 || matches(evidence, ["rate_limit_exceeded", "rate limit", "too many requests"])) {
+		return { kind: "rate-limit", transient: true, ...base };
+	}
+	if (matches(evidence, ["timeout", "timed out", "network", "connection", "websocket", "fetch failed"])) {
+		return { kind: "transport", transient: true, ...base };
+	}
+	return { kind: "unknown", transient: false, ...base };
+}

package/src/service.ts

@@ -1,4 +1,5 @@
-import { SERVICE_MAX_BODY_BYTES, VERSION } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { VERSION } from "./version.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";

package/src/version.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+function packageVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as unknown;
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		throw new Error("Jittor package manifest must be an object");
+	}
+	const version = (manifest as Record<string, unknown>)["version"];
+	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+		throw new Error("Jittor package manifest has an invalid version");
+	}
+	return version;
+}
+
+/** Runtime package version; package.json is the single release source of truth. */
+export const VERSION = packageVersion();