@danypops/jittor 0.2.1 → 0.4.0

package/README.md

@@ -54,7 +54,15 @@ The on/off choice persists privately in `$XDG_CONFIG_HOME/jittor/extension.json`
 
 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.
+### Settings
+
+Run `/jittor settings` for one keyboard-navigable TUI covering routing enforcement, the informational footer, Codex recovery, and all four token-budget thresholds. It uses explicit ON/OFF and configured/not-configured labels, remains bounded on narrow terminals, confirms weaker enforcement and recovery changes, and applies enforcement enablement through the same readiness checks as `/jittor on`. Existing non-TUI commands remain available for automation.
+
+### Usage graphs
+
+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

@@ -12,12 +12,14 @@ import {
 } 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 { 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 { showSettingsPanel } from "./settings-tui.ts";
 import { buildFooterBudget, formatFooterStatus, showJittorPanel } from "./tui.ts";
 import { showUsagePanel } from "./usage.ts";
 
@@ -48,6 +50,16 @@ 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>;
 	const set = (candidate as Partial<CodexRecoveryControl>).setCodexRecoveryEnabled;
@@ -214,6 +226,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,
@@ -360,8 +373,49 @@ export function registerJittorExtension(
 				ctx.ui.notify("Jittor informational footer enabled; routing enforcement is unchanged.", "info");
 				return;
 			}
+			if (action === "settings") {
+				await showSettingsPanel(ctx, enforcement, codexRecovery, usageBudgets, {
+					setEnforcement: async (enabled) => enabled ? enable(ctx) : disable(ctx),
+					setFooter: async (enabled) => {
+						enforcement.setFooterEnabled(enabled);
+						showFooter(ctx);
+						if (enabled) await refreshFooter(client, footerState).catch(() => undefined);
+					},
+					setRecovery: (enabled) => {
+						if (!enabled) cancelRecovery(true);
+						codexRecovery.setCodexRecoveryEnabled(enabled);
+					},
+				});
+				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-tui.ts

@@ -0,0 +1,153 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { USAGE_PERIODS, type UsagePeriod } from "../../src/domain/usage.ts";
+import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+
+export interface SettingsSnapshot {
+	enforcementEnabled: boolean;
+	footerEnabled: boolean;
+	codexRecoveryEnabled: boolean;
+	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+}
+
+interface SettingsTheme {
+	fg(color: "accent" | "success" | "warning" | "error" | "muted" | "dim" | "borderMuted", text: string): string;
+	bold(text: string): string;
+}
+
+type SettingsKey = "enforcement" | "footer" | "recovery" | `budget-${UsagePeriod}`;
+type SettingsAction = { kind: "activate"; key: SettingsKey } | { kind: "close" };
+
+export interface SettingsEffects {
+	setEnforcement(enabled: boolean): void | Promise<void>;
+	setFooter(enabled: boolean): void | Promise<void>;
+	setRecovery(enabled: boolean): void | Promise<void>;
+}
+
+const SETTINGS_KEYS: SettingsKey[] = [
+	"enforcement",
+	"footer",
+	"recovery",
+	...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const),
+];
+
+function state(enabled: boolean, theme: SettingsTheme): string {
+	return enabled ? theme.fg("success", "ON") : theme.fg("muted", "OFF");
+}
+
+function budgetLabel(period: UsagePeriod, snapshot: SettingsSnapshot): string {
+	const value = snapshot.usageTokenBudgets[period];
+	return value === undefined ? "not configured" : `${value.toLocaleString()} tokens`;
+}
+
+function rowText(key: SettingsKey, snapshot: SettingsSnapshot, theme: SettingsTheme): string {
+	if (key === "enforcement") return `Routing enforcement  ${state(snapshot.enforcementEnabled, theme)}`;
+	if (key === "footer") return `Informational footer  ${state(snapshot.footerEnabled, theme)}`;
+	if (key === "recovery") return `Codex recovery  ${state(snapshot.codexRecoveryEnabled, theme)}`;
+	const period = key.slice("budget-".length) as UsagePeriod;
+	return `${USAGE_PERIODS.find((candidate) => candidate.id === period)!.label} token budget  ${budgetLabel(period, snapshot)}`;
+}
+
+export function settingsSnapshot(
+	enforcement: EnforcementControl,
+	recovery: CodexRecoveryControl,
+	budgets: UsageBudgetControl,
+): SettingsSnapshot {
+	return {
+		enforcementEnabled: enforcement.isEnabled(),
+		footerEnabled: enforcement.isFooterEnabled(),
+		codexRecoveryEnabled: recovery.isCodexRecoveryEnabled(),
+		usageTokenBudgets: Object.fromEntries(USAGE_PERIODS.map(({ id }) => [id, budgets.getUsageTokenBudget(id)])),
+	};
+}
+
+export function renderSettingsView(snapshot: SettingsSnapshot, selected: number, width: number, theme: SettingsTheme): string[] {
+	const safeWidth = Math.max(20, width);
+	const lines = [
+		theme.bold("Jittor Settings"),
+		theme.fg("dim", "Token budgets are user values; provider quotas remain separate."),
+		"",
+	];
+	for (let index = 0; index < SETTINGS_KEYS.length; index += 1) {
+		const selectedRow = index === selected;
+		const prefix = selectedRow ? theme.fg("accent", "› ") : "  ";
+		lines.push(`${prefix}${rowText(SETTINGS_KEYS[index]!, snapshot, theme)}`);
+	}
+	lines.push("", theme.fg("dim", "↑/↓ select · Enter edit · Esc close"));
+	return lines.map((line) => visibleWidth(line) <= safeWidth ? line : truncateToWidth(line, safeWidth, "…"));
+}
+
+function plainTheme(): SettingsTheme {
+	return { fg: (_color, text) => text, bold: (text) => text };
+}
+
+async function editBudget(ctx: ExtensionCommandContext, budgets: UsageBudgetControl, period: UsagePeriod): Promise<void> {
+	const label = USAGE_PERIODS.find((candidate) => candidate.id === period)!.label;
+	const current = budgets.getUsageTokenBudget(period);
+	const input = await ctx.ui.input(`${label} token budget`, current?.toLocaleString() ?? "positive token count or off");
+	if (input === undefined) return;
+	const normalized = input.trim().toLowerCase();
+	if (normalized === "off" || normalized === "clear") {
+		budgets.setUsageTokenBudget(period, undefined);
+		ctx.ui.notify(`${label} token budget cleared.`, "info");
+		return;
+	}
+	const tokens = Number(normalized.replaceAll(",", ""));
+	if (!Number.isFinite(tokens) || tokens <= 0) {
+		ctx.ui.notify("Enter a positive token count, or `off` to clear this threshold.", "warning");
+		return;
+	}
+	budgets.setUsageTokenBudget(period, tokens);
+	ctx.ui.notify(`${label} token budget set to ${tokens.toLocaleString()} tokens.`, "info");
+}
+
+export async function showSettingsPanel(
+	ctx: ExtensionCommandContext,
+	enforcement: EnforcementControl,
+	recovery: CodexRecoveryControl,
+	budgets: UsageBudgetControl,
+	effects: SettingsEffects = {
+		setEnforcement: (enabled) => enforcement.setEnabled(enabled),
+		setFooter: (enabled) => enforcement.setFooterEnabled(enabled),
+		setRecovery: (enabled) => recovery.setCodexRecoveryEnabled(enabled),
+	},
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(renderSettingsView(settingsSnapshot(enforcement, recovery, budgets), -1, 100, plainTheme()).slice(0, -2).join("\n"), "info");
+		return;
+	}
+	for (;;) {
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const action = await ctx.ui.custom<SettingsAction>((tui, theme, _keybindings, done) => {
+			let selected = 0;
+			return {
+				invalidate() {},
+				render(width: number): string[] { return renderSettingsView(snapshot, selected, width, theme); },
+				handleInput(data: string): void {
+					if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "q") done({ kind: "close" });
+					else if (matchesKey(data, "up")) { selected = (selected - 1 + SETTINGS_KEYS.length) % SETTINGS_KEYS.length; tui.requestRender(); }
+					else if (matchesKey(data, "down")) { selected = (selected + 1) % SETTINGS_KEYS.length; tui.requestRender(); }
+					else if (matchesKey(data, "return") || matchesKey(data, "enter") || matchesKey(data, "space")) done({ kind: "activate", key: SETTINGS_KEYS[selected]! });
+				},
+			};
+		});
+		if (!action || action.kind === "close") return;
+		if (action.key === "enforcement") {
+			if (enforcement.isEnabled()) {
+				if (await ctx.ui.confirm("Disable routing enforcement?", "Jittor will remain monitor-only and will no longer block unsafe provider requests.")) await effects.setEnforcement(false);
+			} else await effects.setEnforcement(true);
+			continue;
+		}
+		if (action.key === "footer") {
+			await effects.setFooter(!enforcement.isFooterEnabled());
+			continue;
+		}
+		if (action.key === "recovery") {
+			if (!recovery.isCodexRecoveryEnabled()) {
+				if (await ctx.ui.confirm("Enable Codex recovery?", "Jittor may start bounded hidden retries only after transient Codex failures fully settle.")) await effects.setRecovery(true);
+			} else await effects.setRecovery(false);
+			continue;
+		}
+		await editBudget(ctx, budgets, action.key.slice("budget-".length) as UsagePeriod);
+	}
+}

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;
@@ -14,14 +15,31 @@ export interface CodexRecoveryControl {
 	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 {
@@ -32,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();
 	}
 }
 
@@ -71,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.1",
+  "version": "0.4.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/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,
 	};
 }