@danypops/jittor 0.2.0 → 0.2.1

package/README.md

@@ -41,14 +41,17 @@ Blocking always has a daemon-independent escape hatch. `/jittor off` immediately
 
 ### Opt-in Codex settled-turn recovery
 
-Transient Codex recovery is securely off by default. Opt in explicitly through `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`):
+Transient Codex recovery is securely off by default and controlled through the existing Jittor command surface:
 
-```json
-{
-  "codexRecoveryEnabled": true
-}
+```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.

package/extension/src/index.ts

@@ -7,8 +7,10 @@ import {
 	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 CodexFailureMetadata } from "../../src/domain/codex-recovery.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";
@@ -48,9 +50,13 @@ const SYSTEM_RECOVERY_RUNTIME: CodexRecoveryRuntime = {
 
 function recoveryControl(enforcement: EnforcementControl): CodexRecoveryControl {
 	const candidate = enforcement as EnforcementControl & Partial<CodexRecoveryControl>;
-	return typeof candidate.isCodexRecoveryEnabled === "function"
-		? { isCodexRecoveryEnabled: () => candidate.isCodexRecoveryEnabled!() }
-		: { isCodexRecoveryEnabled: () => false };
+	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 {
@@ -216,12 +222,33 @@ export function registerJittorExtension(
 		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());
@@ -231,8 +258,10 @@ export function registerJittorExtension(
 			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;
@@ -296,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") {

package/extension/src/settings.ts

@@ -11,6 +11,7 @@ export interface EnforcementControl {
 
 export interface CodexRecoveryControl {
 	isCodexRecoveryEnabled(): boolean;
+	setCodexRecoveryEnabled(enabled: boolean): void;
 }
 
 export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl {

package/package.json

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

package/src/domain/codex-recovery.ts

@@ -50,6 +50,7 @@ export class CodexRecoveryPolicy {
 	private pendingFailure: CodexFailure | undefined;
 	private attempts = 0;
 	private windowStartedAt: number | undefined;
+	private lastFailureKind: CodexFailureKind | undefined;
 
 	constructor(
 		private readonly options: CodexRecoveryOptions,
@@ -65,6 +66,7 @@ export class CodexRecoveryPolicy {
 	observeFailure(failure: CodexFailure, now: number): void {
 		this.normalizeWindow(now);
 		this.pendingFailure = failure.transient ? failure : undefined;
+		this.lastFailureKind = failure.transient ? failure.kind : undefined;
 	}
 
 	observeSuccess(): void {
@@ -75,6 +77,7 @@ export class CodexRecoveryPolicy {
 		this.pendingFailure = undefined;
 		this.attempts = 0;
 		this.windowStartedAt = undefined;
+		this.lastFailureKind = undefined;
 	}
 
 	abandonFailure(): void {
@@ -112,14 +115,21 @@ export class CodexRecoveryPolicy {
 		return attempt;
 	}
 
-	state(): { attempts: number; pending: boolean } {
-		return { attempts: this.attempts, pending: this.pendingFailure !== undefined };
+	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;
 		}
 	}
 }