@danypops/jittor 0.2.0 → 0.3.0

package/README.md

@@ -41,17 +41,22 @@ 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.
+Run `/jittor usage` for a colored Unicode cumulative token graph with X/Y axes, provider/model series, input/output/cache totals, refresh, and explicit **Hourly**, **Daily**, **Weekly**, and **Monthly** periods. Left/Right changes period and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
+
+Token-budget thresholds are optional and must be configured by the user; Jittor never infers a token allowance from Codex or another provider's subscription percentage. Configure or clear one period with `/jittor usage budget <hourly|daily|weekly|monthly> <positive-tokens|off>`, and inspect all four with `/jittor usage budget`. A configured budget appears as a horizontal threshold on the cumulative graph with explicit remaining or **OVER BUDGET** state. These private settings persist in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`).
 
 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

@@ -7,15 +7,18 @@ 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 { USAGE_PERIODS, type UsagePeriod } from "../../src/domain/usage.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 CodexRecoveryControl, type EnforcementControl } from "./settings.ts";
+import { persistentEnforcementControl, type CodexRecoveryControl, type EnforcementControl, type UsageBudgetControl } from "./settings.ts";
 import { buildFooterBudget, formatFooterStatus, showJittorPanel } from "./tui.ts";
 import { showUsagePanel } from "./usage.ts";
 
@@ -46,11 +49,25 @@ const SYSTEM_RECOVERY_RUNTIME: CodexRecoveryRuntime = {
 	clearTimeout(handle) { clearTimeout(handle as ReturnType<typeof setTimeout>); },
 };
 
+function usageBudgetControl(enforcement: EnforcementControl): UsageBudgetControl {
+	const candidate = enforcement as EnforcementControl & Partial<UsageBudgetControl>;
+	return typeof candidate.getUsageTokenBudget === "function" && typeof candidate.setUsageTokenBudget === "function"
+		? {
+			getUsageTokenBudget: (period) => candidate.getUsageTokenBudget!(period),
+			setUsageTokenBudget: (period, tokens) => candidate.setUsageTokenBudget!(period, tokens),
+		}
+		: { getUsageTokenBudget: () => undefined, setUsageTokenBudget() {} };
+}
+
 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 {
@@ -208,6 +225,7 @@ export function registerJittorExtension(
 	recoveryRuntime: CodexRecoveryRuntime = SYSTEM_RECOVERY_RUNTIME,
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
+	const usageBudgets = usageBudgetControl(enforcement);
 	const recoveryPolicy = new CodexRecoveryPolicy({
 		baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
 		maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
@@ -216,12 +234,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 +270,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 +337,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") {
@@ -311,8 +372,34 @@ export function registerJittorExtension(
 				ctx.ui.notify("Jittor informational footer enabled; routing enforcement is unchanged.", "info");
 				return;
 			}
+			if (action === "usage budget" || action.startsWith("usage budget ")) {
+				const [, , periodText, valueText] = action.split(/\s+/);
+				const period = USAGE_PERIODS.some((candidate) => candidate.id === periodText) ? periodText as UsagePeriod : undefined;
+				if (!period) {
+					const values = USAGE_PERIODS.map(({ id, label }) => `${label}: ${usageBudgets.getUsageTokenBudget(id)?.toLocaleString() ?? "not configured"}`).join(" · ");
+					ctx.ui.notify(`Token budgets · ${values}`, "info");
+					return;
+				}
+				if (valueText === undefined) {
+					ctx.ui.notify(`${USAGE_PERIODS.find((candidate) => candidate.id === period)!.label} token budget: ${usageBudgets.getUsageTokenBudget(period)?.toLocaleString() ?? "not configured"}`, "info");
+					return;
+				}
+				if (valueText === "off" || valueText === "clear") {
+					usageBudgets.setUsageTokenBudget(period, undefined);
+					ctx.ui.notify(`${USAGE_PERIODS.find((candidate) => candidate.id === period)!.label} token budget cleared.`, "info");
+					return;
+				}
+				const tokens = Number(valueText.replaceAll(",", ""));
+				if (!Number.isFinite(tokens) || tokens <= 0) {
+					ctx.ui.notify("Usage: /jittor usage budget <hourly|daily|weekly|monthly> <positive-tokens|off>", "warning");
+					return;
+				}
+				usageBudgets.setUsageTokenBudget(period, tokens);
+				ctx.ui.notify(`${USAGE_PERIODS.find((candidate) => candidate.id === period)!.label} token budget set to ${tokens.toLocaleString()} tokens.`, "info");
+				return;
+			}
 			if (action === "usage") {
-				await showUsagePanel(ctx, client);
+				await showUsagePanel(ctx, client, usageBudgets);
 				return;
 			}
 			if (!enforcement.isEnabled()) {

package/extension/src/settings.ts

@@ -1,6 +1,7 @@
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { JITTOR_EXTENSION_SETTINGS_FILENAME, JITTOR_STATE_DIRECTORY } from "../../src/constants.ts";
+import { USAGE_PERIODS, type UsagePeriod } from "../../src/domain/usage.ts";
 
 export interface EnforcementControl {
 	isEnabled(): boolean;
@@ -11,16 +12,34 @@ export interface EnforcementControl {
 
 export interface CodexRecoveryControl {
 	isCodexRecoveryEnabled(): boolean;
+	setCodexRecoveryEnabled(enabled: boolean): void;
 }
 
-export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl {
-	setCodexRecoveryEnabled(enabled: boolean): void;
+export interface UsageBudgetControl {
+	getUsageTokenBudget(period: UsagePeriod): number | undefined;
+	setUsageTokenBudget(period: UsagePeriod, tokens: number | undefined): void;
 }
 
+export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl, UsageBudgetControl {}
+
 interface ExtensionSettings {
 	enforcementEnabled: boolean;
 	footerEnabled: boolean;
 	codexRecoveryEnabled: boolean;
+	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+}
+
+function defaultSettings(): ExtensionSettings {
+	return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false, usageTokenBudgets: {} };
+}
+
+function parseUsageTokenBudgets(value: unknown): Partial<Record<UsagePeriod, number>> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	const record = value as Record<string, unknown>;
+	return Object.fromEntries(USAGE_PERIODS.flatMap(({ id }) => {
+		const tokens = record[id];
+		return typeof tokens === "number" && Number.isFinite(tokens) && tokens > 0 ? [[id, tokens]] : [];
+	})) as Partial<Record<UsagePeriod, number>>;
 }
 
 function settingsPath(env: Record<string, string | undefined> = process.env): string {
@@ -31,15 +50,16 @@ 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, codexRecoveryEnabled: false };
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return defaultSettings();
 		const record = value as Record<string, unknown>;
 		return {
 			enforcementEnabled: record["enforcementEnabled"] !== false,
 			footerEnabled: record["footerEnabled"] !== false,
 			codexRecoveryEnabled: record["codexRecoveryEnabled"] === true,
+			usageTokenBudgets: parseUsageTokenBudgets(record["usageTokenBudgets"]),
 		};
 	} catch {
-		return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false };
+		return defaultSettings();
 	}
 }
 
@@ -70,5 +90,14 @@ export function persistentEnforcementControl(env: Record<string, string | undefi
 			settings.codexRecoveryEnabled = value;
 			persistSettings(path, settings);
 		},
+		getUsageTokenBudget(period): number | undefined {
+			return settings.usageTokenBudgets[period];
+		},
+		setUsageTokenBudget(period, tokens): void {
+			if (tokens !== undefined && (!Number.isFinite(tokens) || tokens <= 0)) throw new Error("usage token budget must be a positive finite number");
+			if (tokens === undefined) delete settings.usageTokenBudgets[period];
+			else settings.usageTokenBudgets[period] = tokens;
+			persistSettings(path, settings);
+		},
 	};
 }

package/extension/src/usage.ts

@@ -3,16 +3,18 @@ import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tu
 import { USAGE_CHART_HEIGHT, USAGE_TOKEN_QUERY_LIMIT, USAGE_Y_AXIS_WIDTH } from "../../src/constants.ts";
 import type { StoredMetricObservation } from "../../src/domain/metric.ts";
 import {
-	buildUsageHistogram,
-	USAGE_RANGES,
-	usageRangeStart,
+	buildUsageGraph,
+	USAGE_PERIODS,
+	usagePeriod,
+	usagePeriodStart,
 	type UsageBucket,
-	type UsageHistogram,
-	type UsageRange,
+	type UsageGraph,
+	type UsagePeriod,
 } from "../../src/domain/usage.ts";
+import type { UsageBudgetControl } from "./settings.ts";
 import type { JittorPanelClient } from "./tui.ts";
 
-type UsageAction = "range-prev" | "range-next" | "refresh" | "close";
+type UsageAction = "period-prev" | "period-next" | "refresh" | "close";
 type UsageColor = "accent" | "success" | "warning" | "error" | "thinkingText" | "muted" | "dim" | "borderMuted";
 
 export interface UsageTheme {
@@ -26,7 +28,7 @@ const PARTIAL_BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
 function compact(value: number): string {
 	if (value >= 1_000_000_000) return `${(value / 1_000_000_000).toFixed(value >= 10_000_000_000 ? 0 : 1)}B`;
 	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(value >= 10_000_000 ? 0 : 1)}M`;
-	if (value >= 1_000) return `${(value / 1_000).toFixed(value >= 10_000 ? 0 : 1)}k`;
+	if (value >= 1_000) return `${(value / 1_000).toFixed(value >= 10_000 || value % 1_000 === 0 ? 0 : 1)}k`;
 	return String(Math.round(value));
 }
 
@@ -51,7 +53,7 @@ function mergeBuckets(buckets: UsageBucket[], maximum: number): UsageBucket[] {
 	return result;
 }
 
-function seriesAt(bucket: UsageBucket, chart: UsageHistogram, tokenHeight: number): number {
+function seriesAt(bucket: UsageBucket, chart: UsageGraph, tokenHeight: number): number {
 	let cumulative = 0;
 	for (let index = 0; index < chart.series.length; index += 1) {
 		cumulative += bucket.series[chart.series[index]!.key] ?? 0;
@@ -60,14 +62,14 @@ function seriesAt(bucket: UsageBucket, chart: UsageHistogram, tokenHeight: numbe
 	return Math.max(0, chart.series.length - 1);
 }
 
-function formatRangePoint(value: number, range: UsageRange): string {
+function formatPeriodPoint(value: number, period: UsagePeriod): string {
 	const date = new Date(value);
-	if (range === "24h") return date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+	if (period === "hourly" || period === "daily") return date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
 	return date.toLocaleDateString(undefined, { month: "short", day: "numeric" });
 }
 
-function axisLabels(start: number, end: number, range: UsageRange, width: number): string {
-	const labels = [formatRangePoint(start, range), formatRangePoint(start + (end - start) / 2, range), formatRangePoint(end, range)];
+function axisLabels(start: number, end: number, period: UsagePeriod, width: number): string {
+	const labels = [formatPeriodPoint(start, period), formatPeriodPoint(start + (end - start) / 2, period), formatPeriodPoint(end, period)];
 	const positions = [0, Math.max(0, Math.floor((width - labels[1]!.length) / 2)), Math.max(0, width - labels[2]!.length)];
 	const characters = Array.from({ length: width }, () => " ");
 	for (let labelIndex = 0; labelIndex < labels.length; labelIndex += 1) {
@@ -82,26 +84,51 @@ function plainTheme(): UsageTheme {
 	return { fg: (_color, text) => text, bold: (text) => text };
 }
 
-export function renderUsageHistogram(chart: UsageHistogram, width: number, theme: UsageTheme): string[] {
+export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageTheme, tokenBudget?: number): string[] {
 	const safeWidth = Math.max(20, width);
 	const chartColumns = Math.max(1, Math.floor((safeWidth - USAGE_Y_AXIS_WIDTH - 1) / 2));
-	const buckets = mergeBuckets(chart.buckets, chartColumns);
+	const increments = mergeBuckets(chart.buckets, chartColumns);
+	const runningSeries: Record<string, number> = {};
+	let runningTotal = 0;
+	const buckets = increments.map((bucket) => {
+		runningTotal += bucket.total;
+		for (const [key, value] of Object.entries(bucket.series)) runningSeries[key] = (runningSeries[key] ?? 0) + value;
+		return { ...bucket, total: runningTotal, series: { ...runningSeries } };
+	});
 	const barStep = buckets.length * 2 <= safeWidth - USAGE_Y_AXIS_WIDTH ? 2 : 1;
 	const plotWidth = buckets.length * barStep;
-	const maximum = Math.max(0, ...buckets.map((bucket) => bucket.total));
+	const budget = typeof tokenBudget === "number" && Number.isFinite(tokenBudget) && tokenBudget > 0 ? tokenBudget : undefined;
+	const maximum = Math.max(chart.totalTokens, budget ?? 0);
+	const observed = chart.truncated ? `at least ${compact(chart.totalTokens)}` : compact(chart.totalTokens);
+	const budgetState = budget === undefined
+		? `${observed} tokens · budget not configured${chart.truncated ? " · query limit reached" : ""}`
+		: chart.totalTokens > budget
+			? `${observed} / ${compact(budget)} budget · OVER BUDGET by ${chart.truncated ? "at least " : ""}${compact(chart.totalTokens - budget)}`
+			: chart.truncated
+				? `${observed} / ${compact(budget)} budget · state unknown · query limit reached`
+				: `${observed} / ${compact(budget)} budget · ${compact(budget - chart.totalTokens)} remaining`;
 	const lines = [
-		truncateToWidth(theme.bold(`Tokens over time · ${chart.range}`), safeWidth, ""),
-		truncateToWidth(`${compact(chart.totalTokens)} tokens · input ${compact(chart.breakdown.input)} · output ${compact(chart.breakdown.output)} · cache ${compact(chart.breakdown.cacheRead + chart.breakdown.cacheWrite)}`, safeWidth, "…"),
+		truncateToWidth(theme.bold(`${usagePeriod(chart.period).label} token usage`), safeWidth, ""),
+		truncateToWidth(budgetState, safeWidth, "…"),
+		truncateToWidth(`input ${compact(chart.breakdown.input)} · output ${compact(chart.breakdown.output)} · cache ${compact(chart.breakdown.cacheRead + chart.breakdown.cacheWrite)}`, safeWidth, "…"),
 		"",
 	];
 	if (maximum === 0) {
-		lines.push(theme.fg("dim", "No recorded Pi token usage in this range."));
+		lines.push(theme.fg("dim", "No recorded Pi token usage in this period."));
 		return lines.map((line) => truncateToWidth(line, safeWidth, "…"));
 	}
 
 	for (let row = 0; row < USAGE_CHART_HEIGHT; row += 1) {
 		const fromBottom = USAGE_CHART_HEIGHT - row - 1;
-		const label = row === 0 ? compact(maximum) : row === Math.floor(USAGE_CHART_HEIGHT / 2) ? compact(maximum / 2) : "";
+		const lower = maximum * fromBottom / USAGE_CHART_HEIGHT;
+		const upper = maximum * (fromBottom + 1) / USAGE_CHART_HEIGHT;
+		const thresholdRow = budget !== undefined && budget > lower && budget <= upper;
+		const label = thresholdRow ? compact(budget) : row === 0 ? compact(maximum) : row === Math.floor(USAGE_CHART_HEIGHT / 2) ? compact(maximum / 2) : "";
+		if (thresholdRow) {
+			const color = chart.totalTokens > budget ? "error" : "warning";
+			lines.push(`${label.padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", "│")}${theme.fg(color, "┄".repeat(plotWidth))}`);
+			continue;
+		}
 		let plot = "";
 		for (const bucket of buckets) {
 			const scaled = bucket.total / maximum * USAGE_CHART_HEIGHT;
@@ -118,7 +145,7 @@ export function renderUsageHistogram(chart: UsageHistogram, width: number, theme
 		lines.push(`${label.padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", "│")}${plot}`);
 	}
 	lines.push(`${"0".padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", `└${"─".repeat(plotWidth)}`)}`);
-	lines.push(`${" ".repeat(USAGE_Y_AXIS_WIDTH)}${axisLabels(chart.start, chart.end, chart.range, plotWidth)}`);
+	lines.push(`${" ".repeat(USAGE_Y_AXIS_WIDTH)}${axisLabels(chart.start, chart.end, chart.period, plotWidth)}`);
 	lines.push("");
 	for (let index = 0; index < chart.series.length; index += 1) {
 		const series = chart.series[index]!;
@@ -128,42 +155,48 @@ export function renderUsageHistogram(chart: UsageHistogram, width: number, theme
 	return lines.map((line) => visibleWidth(line) <= safeWidth ? line : truncateToWidth(line, safeWidth, "…"));
 }
 
-async function loadUsage(client: JittorPanelClient, range: UsageRange, now: number): Promise<UsageHistogram> {
+async function loadUsage(client: JittorPanelClient, period: UsagePeriod, now: number): Promise<UsageGraph> {
 	const rows = await client.call("metrics.query", {
 		source: "pi",
-		since: usageRangeStart(range, now),
+		since: usagePeriodStart(period, now),
 		until: now,
 		order: "desc",
 		limit: USAGE_TOKEN_QUERY_LIMIT,
 	}) as StoredMetricObservation[];
-	return buildUsageHistogram(rows, { range, now });
+	return buildUsageGraph(rows, { period, now, truncated: rows.length >= USAGE_TOKEN_QUERY_LIMIT });
 }
 
-export async function showUsagePanel(ctx: ExtensionCommandContext, client: JittorPanelClient, now = Date.now()): Promise<void> {
-	let rangeIndex = 0;
+export async function showUsagePanel(
+	ctx: ExtensionCommandContext,
+	client: JittorPanelClient,
+	budgets: Pick<UsageBudgetControl, "getUsageTokenBudget">,
+	now = Date.now(),
+): Promise<void> {
+	let periodIndex = 0;
 	for (;;) {
-		const range = USAGE_RANGES[rangeIndex]!;
-		const chart = await loadUsage(client, range, now);
+		const period = USAGE_PERIODS[periodIndex]!.id;
+		const chart = await loadUsage(client, period, now);
+		const tokenBudget = budgets.getUsageTokenBudget(period);
 		if (ctx.mode !== "tui") {
-			ctx.ui.notify(renderUsageHistogram(chart, 80, plainTheme()).join("\n"), "info");
+			ctx.ui.notify(renderUsageGraph(chart, 80, plainTheme(), tokenBudget).join("\n"), "info");
 			return;
 		}
 		const action = await ctx.ui.custom<UsageAction>((_tui, theme, _keybindings, done) => ({
 			invalidate() {},
 			render(width: number): string[] {
-				const lines = renderUsageHistogram(chart, width, theme);
-				const controls = theme.fg("dim", "←/→ range · r refresh · Esc close");
+				const lines = renderUsageGraph(chart, width, theme, tokenBudget);
+				const controls = theme.fg("dim", "←/→ period · r refresh · Esc close");
 				return [...lines, "", truncateToWidth(controls, width, "…")];
 			},
 			handleInput(data: string): void {
 				if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "q") done("close");
-				else if (matchesKey(data, "left")) done("range-prev");
-				else if (matchesKey(data, "right")) done("range-next");
+				else if (matchesKey(data, "left")) done("period-prev");
+				else if (matchesKey(data, "right")) done("period-next");
 				else if (data === "r") done("refresh");
 			},
 		}));
 		if (!action || action === "close") return;
-		if (action === "range-prev") rangeIndex = (rangeIndex - 1 + USAGE_RANGES.length) % USAGE_RANGES.length;
-		if (action === "range-next") rangeIndex = (rangeIndex + 1) % USAGE_RANGES.length;
+		if (action === "period-prev") periodIndex = (periodIndex - 1 + USAGE_PERIODS.length) % USAGE_PERIODS.length;
+		if (action === "period-next") periodIndex = (periodIndex + 1) % USAGE_PERIODS.length;
 	}
 }

package/package.json

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

package/src/constants.ts

@@ -28,6 +28,7 @@ export const SYSTEMD_UNIT_NAME = "jittor.service";
 export const USAGE_CHART_HEIGHT = 8;
 export const USAGE_Y_AXIS_WIDTH = 7;
 export const USAGE_TOKEN_QUERY_LIMIT = 10_000;
+export const MAX_USAGE_BUCKETS = 120;
 export const MAX_DYNAMIC_ROUTES = 100;
 export const CODEX_ERROR_MESSAGE_LIMIT = 160;
 export const CODEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;

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;
 		}
 	}
 }

package/src/domain/usage.ts

@@ -1,7 +1,17 @@
+import { MAX_USAGE_BUCKETS, MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR } from "../constants.ts";
 import type { StoredMetricObservation } from "./metric.ts";
 
-export const USAGE_RANGES = ["24h", "7d", "30d", "90d"] as const;
-export type UsageRange = typeof USAGE_RANGES[number];
+export const USAGE_PERIODS = [
+	{ id: "hourly", label: "Hourly", windowMs: MILLISECONDS_PER_HOUR, bucketCount: 12 },
+	{ id: "daily", label: "Daily", windowMs: MILLISECONDS_PER_DAY, bucketCount: 24 },
+	{ id: "weekly", label: "Weekly", windowMs: 7 * MILLISECONDS_PER_DAY, bucketCount: 28 },
+	{ id: "monthly", label: "Monthly", windowMs: 30 * MILLISECONDS_PER_DAY, bucketCount: 30 },
+] as const;
+export type UsagePeriod = typeof USAGE_PERIODS[number]["id"];
+
+export function usagePeriod(period: UsagePeriod): typeof USAGE_PERIODS[number] {
+	return USAGE_PERIODS.find((candidate) => candidate.id === period)!;
+}
 
 export interface UsageSeries {
 	key: string;
@@ -24,31 +34,24 @@ export interface UsageBreakdown {
 	cacheWrite: number;
 }
 
-export interface UsageHistogram {
-	range: UsageRange;
+export interface UsageGraph {
+	period: UsagePeriod;
 	start: number;
 	end: number;
 	buckets: UsageBucket[];
 	series: UsageSeries[];
 	totalTokens: number;
 	breakdown: UsageBreakdown;
+	truncated: boolean;
 }
 
-export interface UsageHistogramOptions {
-	range: UsageRange;
+export interface UsageGraphOptions {
+	period: UsagePeriod;
 	now: number;
 	bucketCount?: number;
+	truncated?: boolean;
 }
 
-const RANGE_MILLISECONDS: Record<UsageRange, number> = {
-	"24h": 24 * 60 * 60 * 1_000,
-	"7d": 7 * 24 * 60 * 60 * 1_000,
-	"30d": 30 * 24 * 60 * 60 * 1_000,
-	"90d": 90 * 24 * 60 * 60 * 1_000,
-};
-
-const DEFAULT_BUCKETS: Record<UsageRange, number> = { "24h": 24, "7d": 28, "30d": 30, "90d": 30 };
-
 const BREAKDOWN_KEYS = {
 	"input-tokens": "input",
 	"output-tokens": "output",
@@ -56,8 +59,8 @@ const BREAKDOWN_KEYS = {
 	"cache-write-tokens": "cacheWrite",
 } as const satisfies Record<string, keyof UsageBreakdown>;
 
-export function usageRangeStart(range: UsageRange, now: number): number {
-	return Math.max(0, now - RANGE_MILLISECONDS[range]);
+export function usagePeriodStart(period: UsagePeriod, now: number): number {
+	return Math.max(0, now - usagePeriod(period).windowMs);
 }
 
 function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
@@ -69,11 +72,11 @@ function identity(row: StoredMetricObservation): { key: string; provider: string
 	return { key: `${provider}/${model}`, provider, model };
 }
 
-export function buildUsageHistogram(rows: StoredMetricObservation[], options: UsageHistogramOptions): UsageHistogram {
+export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): UsageGraph {
 	const end = options.now;
-	const start = usageRangeStart(options.range, end);
-	const requestedBuckets = options.bucketCount ?? DEFAULT_BUCKETS[options.range];
-	const bucketCount = Math.max(1, Math.min(120, Math.floor(requestedBuckets)));
+	const start = usagePeriodStart(options.period, end);
+	const requestedBuckets = options.bucketCount ?? usagePeriod(options.period).bucketCount;
+	const bucketCount = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requestedBuckets)));
 	const bucketSize = Math.max(1, (end - start) / bucketCount);
 	const buckets: UsageBucket[] = Array.from({ length: bucketCount }, (_, index) => ({
 		start: start + index * bucketSize,
@@ -101,12 +104,13 @@ export function buildUsageHistogram(rows: StoredMetricObservation[], options: Us
 
 	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
 	return {
-		range: options.range,
+		period: options.period,
 		start,
 		end,
 		buckets,
 		series,
 		totalTokens: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
 		breakdown,
+		truncated: options.truncated === true,
 	};
 }