@narumitw/pi-usage 0.50.0 → 0.51.0

package/README.md

@@ -2,13 +2,14 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-usage)](https://www.npmjs.com/package/@narumitw/pi-usage) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-usage` is a native [Pi coding agent](https://pi.dev) extension that adds one interactive `/usage` command for reading usage from the account Pi is actually using. It supports OpenAI Codex ChatGPT subscription windows, GitHub Copilot allowances, and OpenRouter API-key spend limits without pretending those limits have the same semantics.
+`@narumitw/pi-usage` is a native [Pi coding agent](https://pi.dev) extension that adds an interactive `/usage` command for reading usage from the account Pi is actually using and a `/fast` shortcut for supported OpenAI Codex models. It supports Codex ChatGPT subscription windows, GitHub Copilot allowances, and OpenRouter API-key spend limits without pretending those limits have the same semantics.
 
 ## ✨ Features
 
 - Opens one interactive `/usage` menu with current state and next actions.
 - Automatically queries the selected model provider and active runtime account.
 - Supports OpenAI Codex subscription windows, resets, credits, and model-specific buckets.
+- Toggles persistent Codex Fast routing through `/fast` or the contextual `/usage` action.
 - Redeems earned Codex usage-limit resets for the active, matching Pi OAuth account with fresh availability, explicit confirmation, and idempotent retry.
 - Supports GitHub Copilot AI Credits, legacy premium requests, Free chat quota, additional usage, percentage, and reset time.
 - Supports OpenRouter per-key credit limits plus daily, weekly, monthly, and all-time spend.
@@ -52,6 +53,7 @@ with these actions:
 
 ```text
 Refresh current usage
+Turn Fast mode on/off       # Supported current Codex models only
 Redeem usage limit reset…   # Current Codex OAuth accounts only
 View another configured provider…
 View all configured providers…
@@ -73,6 +75,25 @@ same redemption request ID so the backend can treat an uncertain retry idempoten
 already-completed, not-needed, and no-credit outcomes are reported separately, then usage and the
 statusline are refreshed for the still-current account.
 
+### Codex Fast mode
+
+Run bare `/fast` to toggle Fast for the active supported Codex model, or use **Turn Fast mode on/off** in `/usage`.
+
+Fast is about 1.5× faster and uses more of your plan allowance.
+The preference defaults to Off and is saved as `codexFastMode` in Pi's user agent directory as `pi-usage.json`, normally `~/.pi/agent/pi-usage.json`.
+The extension reloads this file at every session start and does not create it until the first successful toggle.
+
+Fast currently applies only to official `openai-codex-responses` requests for `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna` at `https://chatgpt.com`.
+It sends `service_tier: "priority"` while enabled and explicit `service_tier: "default"` otherwise.
+The statusline adds `fast` only while the preference is effective, for example `codex fast 59% 5h`.
+Unsupported models and custom or proxy origins are left unchanged.
+
+`/fast` supports TUI and RPC mode, accepts no arguments, and rejects print or JSON mode before mutation.
+A toggle affects provider requests whose payload hook starts after the save; a request already sent is unchanged.
+Settings operations are serialized inside one Pi process, but separate Pi processes are not mutually locked.
+Unknown JSON fields are preserved, writes use a private temporary file plus rename, and a malformed or invalid file is never overwritten.
+Repair or remove an invalid file, then run `/reload` before trying the toggle again.
+
 ## 📋 Provider semantics
 
 ### OpenAI Codex
@@ -82,7 +103,7 @@ statusline are refreshed for the still-current account.
 - Source: the Codex usage and earned-reset endpoints using Pi's resolved runtime authorization
 - Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets
 - Reset mutation: `POST /wham/rate-limit-reset-credits/consume` with a unique redemption request ID and, when available, the selected opaque credit ID
-- Statusline examples: `codex 59% 5h 61% wk` or `codex spark 100% 5h`
+- Statusline examples: `codex 59% 5h 61% wk`, `codex fast 59% 5h`, or `codex spark 100% 5h`
 
 The statusline selects a returned bucket that matches the current Codex model when one is available. Unlike `pi-codex-usage`, this successor intentionally has no Codex CLI fallback because the CLI may be logged into a different account than Pi's active runtime account.
 
@@ -138,7 +159,7 @@ Remove the deprecated package rather than loading both usage extensions together
 
 Behavior changes:
 
-- Use `/usage` as the only entry point; `/codex-status` is no longer registered.
+- Use `/usage` for usage management; `/codex-status` is no longer registered.
 - Refresh and cross-provider operations are menu actions rather than flags.
 - Codex CLI fallback is removed to preserve active-runtime-account correctness.
 - The status key changes from `codex-usage` to `usage`.
@@ -153,6 +174,8 @@ Behavior changes:
 - OpenRouter successful inference responses do not expose proactive request-rate counters; `/usage` reports the documented per-key credit/spend fields instead.
 - A provider may not return a safe human-readable account identity. In that case the provider and runtime credential state remain visible without exposing secrets.
 - Immediate account-change events are not available from Pi; auth is re-resolved before commands, turns, and scheduled refreshes.
+- Fast model support is intentionally conservative and may require an extension update when Codex adds or removes service tiers.
+- Another later-loaded extension can replace the final provider payload, so arbitrary third-party payload-rewrite conflicts cannot be prevented.
 
 ## 🗂️ Package layout
 
@@ -160,7 +183,11 @@ Behavior changes:
 packages/pi-usage/
 ├── src/
 │   ├── index.ts       # Pi package entrypoint and helper export barrel
-│   ├── usage.ts       # Menu, cache, and lifecycle orchestration
+│   ├── usage.ts       # Menu, cache, and usage lifecycle orchestration
+│   ├── codex-fast.ts  # Fast eligibility, request tier, and cost correction
+│   ├── codex-fast-runtime.ts # Fast command, persistence lifecycle, and request hooks
+│   ├── settings.ts    # Validated user settings and atomic persistence
+│   ├── usage-helpers.ts # Small orchestration helpers
 │   ├── query.ts       # Runtime auth resolution and bounded provider queries
 │   ├── codex-resets.ts # Codex reset auth, API contracts, and normalization
 │   ├── format.ts      # Provider-aware notifications and statusline text

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.50.0",
+	"version": "0.51.0",
 	"description": "Pi extension that shows current-account usage for Codex, GitHub Copilot, and OpenRouter.",
 	"type": "module",
 	"license": "MIT",
@@ -34,10 +34,12 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.7",
+		"@earendil-works/pi-ai": "0.84.1",
 		"@earendil-works/pi-coding-agent": "0.84.1",
 		"@types/node": "26.1.2",
 		"typescript": "7.0.2"

package/src/codex-fast-runtime.ts

@@ -0,0 +1,212 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	codexFastAvailability,
+	codexFastIsEffective,
+	codexFastStatusLabel,
+	correctCodexFastMessageCost,
+	rewriteCodexFastPayload,
+} from "./codex-fast.js";
+import { errorMessage } from "./core.js";
+import { isStaleExtensionContextError } from "./query.js";
+import type { UsageSettingsRuntime, UsageSettingsState } from "./settings.js";
+import type { PiModel } from "./types.js";
+
+const NO_FAST_REQUEST = Symbol("no-fast-request");
+type PendingFastRequest = { fastRequested: boolean; model: PiModel };
+
+export const FAST_USAGE_WARNING = "Fast is about 1.5× faster and uses more of your plan allowance.";
+
+export function registerCodexFastMode(
+	pi: ExtensionAPI,
+	settingsRuntime: UsageSettingsRuntime,
+	refreshStatus: (ctx: ExtensionContext) => void,
+) {
+	let sessionController = new AbortController();
+	let generation = 0;
+	const pendingFastRequests = new Map<string, PendingFastRequest>();
+
+	const toggle = async (
+		ctx: ExtensionCommandContext,
+		enabled: boolean,
+		callerSignal?: AbortSignal,
+	): Promise<boolean> => {
+		const ownerGeneration = generation;
+		const sessionId = ctx.sessionManager.getSessionId();
+		const signal = callerSignal
+			? AbortSignal.any([callerSignal, sessionController.signal])
+			: sessionController.signal;
+		try {
+			await settingsRuntime.update({ codexFastMode: enabled }, signal);
+		} catch (error) {
+			if (isAbortError(error) || isStaleExtensionContextError(error)) return false;
+			ctx.ui.notify(`Could not save pi-usage.json: ${errorMessage(error)}`, "error");
+			return false;
+		}
+		if (
+			signal.aborted ||
+			ownerGeneration !== generation ||
+			ctx.sessionManager.getSessionId() !== sessionId
+		) {
+			return false;
+		}
+		refreshStatus(ctx);
+		ctx.ui.notify(
+			enabled
+				? `Codex Fast mode enabled. ${FAST_USAGE_WARNING}`
+				: "Codex Fast mode disabled; standard routing will be used.",
+			"info",
+		);
+		return true;
+	};
+
+	pi.registerCommand("fast", {
+		description: "Toggle Codex Fast mode",
+		handler: async (args, ctx) => {
+			if (args.trim()) {
+				if (!ctx.hasUI) throw new Error("/fast does not accept arguments.");
+				ctx.ui.notify("/fast does not accept arguments.", "warning");
+				return;
+			}
+			if (!ctx.hasUI) throw new Error("/fast requires TUI or RPC mode.");
+			const availability = codexFastAvailability(
+				ctx.model,
+				settingsRuntime.get().settings.codexFastMode,
+			);
+			if (availability.kind === "not-codex") {
+				ctx.ui.notify("/fast is available only for the active OpenAI Codex model.", "warning");
+				return;
+			}
+			if (availability.kind === "unavailable") {
+				ctx.ui.notify(availability.reason, "warning");
+				return;
+			}
+			if (settingsRuntime.get().kind === "invalid") {
+				ctx.ui.notify(
+					"pi-usage.json is invalid; repair it and run /reload before changing Fast mode.",
+					"error",
+				);
+				return;
+			}
+			await toggle(ctx, !availability.enabled);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		generation += 1;
+		sessionController.abort();
+		pendingFastRequests.clear();
+		sessionController = new AbortController();
+		const ownerGeneration = generation;
+		const sessionId = ctx.sessionManager.getSessionId();
+		let state: Readonly<UsageSettingsState>;
+		try {
+			state = await settingsRuntime.reload(sessionController.signal);
+		} catch (error) {
+			if (sessionController.signal.aborted || ownerGeneration !== generation) return;
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					`Could not load pi-usage.json; using defaults. ${errorMessage(error)}`,
+					"warning",
+				);
+			}
+			return;
+		}
+		if (
+			sessionController.signal.aborted ||
+			ownerGeneration !== generation ||
+			ctx.sessionManager.getSessionId() !== sessionId
+		) {
+			return;
+		}
+		if (ctx.hasUI && state.kind === "invalid") {
+			ctx.ui.notify(
+				`Invalid pi-usage.json; using defaults without overwriting it. ${state.issue}`,
+				"warning",
+			);
+		}
+		refreshStatus(ctx);
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const rewritten = rewriteCodexFastPayload(
+			event.payload,
+			ctx.model,
+			settingsRuntime.get().settings.codexFastMode,
+		);
+		const key = activeRequestKey(ctx);
+		if (key && ctx.model) {
+			pendingFastRequests.set(key, {
+				fastRequested: isRecord(rewritten) && rewritten.service_tier === "priority",
+				model: ctx.model,
+			});
+		}
+		return rewritten;
+	});
+	pi.on("message_end", (event, ctx) => {
+		const request = consumeFastRequest(ctx, event.message, pendingFastRequests);
+		if (request === NO_FAST_REQUEST) return undefined;
+		const message = correctCodexFastMessageCost(
+			event.message,
+			request.model,
+			request.fastRequested,
+		);
+		return message ? { message: message as never } : undefined;
+	});
+	pi.on("session_shutdown", async () => {
+		generation += 1;
+		sessionController.abort();
+		pendingFastRequests.clear();
+		await settingsRuntime.flush();
+	});
+
+	return {
+		availability(model: PiModel | undefined) {
+			return codexFastAvailability(model, settingsRuntime.get().settings.codexFastMode);
+		},
+		decorateStatus(model: PiModel | undefined, status: string) {
+			return codexFastStatusLabel(
+				status,
+				codexFastIsEffective(model, settingsRuntime.get().settings.codexFastMode),
+			);
+		},
+		toggle,
+	};
+}
+
+function activeRequestKey(ctx: ExtensionContext): string | undefined {
+	const model = ctx.model;
+	return model ? `${ctx.sessionManager.getSessionId()}:${model.provider}/${model.id}` : undefined;
+}
+
+function consumeFastRequest(
+	ctx: ExtensionContext,
+	message: unknown,
+	pending: Map<string, PendingFastRequest>,
+): PendingFastRequest | typeof NO_FAST_REQUEST {
+	if (!isRecord(message) || message.role !== "assistant") return NO_FAST_REQUEST;
+	const key = messageRequestKey(ctx, message);
+	if (!key) return NO_FAST_REQUEST;
+	const request = pending.get(key);
+	pending.delete(key);
+	return request ?? NO_FAST_REQUEST;
+}
+
+function messageRequestKey(
+	ctx: ExtensionContext,
+	message: Record<string, unknown>,
+): string | undefined {
+	if (typeof message.provider !== "string" || typeof message.model !== "string") return undefined;
+	return `${ctx.sessionManager.getSessionId()}:${message.provider}/${message.model}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}

package/src/codex-fast.ts

@@ -0,0 +1,124 @@
+import { calculateCost, hasApi } from "@earendil-works/pi-ai";
+import type { PiModel } from "./types.js";
+
+export const CODEX_FAST_SERVICE_TIER = "priority";
+export const CODEX_STANDARD_SERVICE_TIER = "default";
+
+export const CODEX_FAST_MODEL_IDS: ReadonlySet<string> = new Set([
+	"gpt-5.4",
+	"gpt-5.5",
+	"gpt-5.6-luna",
+	"gpt-5.6-sol",
+	"gpt-5.6-terra",
+]);
+
+export type CodexFastAvailability =
+	| { kind: "available"; enabled: boolean }
+	| { kind: "not-codex" }
+	| { kind: "unavailable"; reason: string };
+
+export function codexFastAvailability(
+	model: PiModel | undefined,
+	enabled: boolean,
+): CodexFastAvailability {
+	if (model?.provider !== "openai-codex") return { kind: "not-codex" };
+	if (!isOfficialCodexModel(model)) {
+		return {
+			kind: "unavailable",
+			reason: "Fast mode requires the official OpenAI Codex Responses endpoint.",
+		};
+	}
+	if (!CODEX_FAST_MODEL_IDS.has(model.id)) {
+		return {
+			kind: "unavailable",
+			reason: `${model.id} does not advertise Codex Fast support.`,
+		};
+	}
+	return { kind: "available", enabled };
+}
+
+export function codexFastIsEffective(model: PiModel | undefined, enabled: boolean): boolean {
+	return codexFastAvailability(model, enabled).kind === "available" && enabled;
+}
+
+export function codexFastRequestTier(
+	model: PiModel | undefined,
+	enabled: boolean,
+): typeof CODEX_FAST_SERVICE_TIER | typeof CODEX_STANDARD_SERVICE_TIER | undefined {
+	if (!isOfficialCodexModel(model)) return undefined;
+	return enabled && CODEX_FAST_MODEL_IDS.has(model.id)
+		? CODEX_FAST_SERVICE_TIER
+		: CODEX_STANDARD_SERVICE_TIER;
+}
+
+export function rewriteCodexFastPayload(
+	payload: unknown,
+	model: PiModel | undefined,
+	enabled: boolean,
+): unknown | undefined {
+	const serviceTier = codexFastRequestTier(model, enabled);
+	if (!serviceTier || !isRecord(payload)) return undefined;
+	return { ...payload, service_tier: serviceTier };
+}
+
+export function correctCodexFastMessageCost(
+	message: unknown,
+	model: PiModel | undefined,
+	fastRequested: boolean,
+): unknown | undefined {
+	if (
+		!codexFastIsEffective(model, fastRequested) ||
+		!isRecord(message) ||
+		message.role !== "assistant" ||
+		message.provider !== model?.provider ||
+		message.model !== model?.id
+	) {
+		return undefined;
+	}
+	const usage = isRecord(message.usage) ? message.usage : undefined;
+	const cost = usage && isRecord(usage.cost) ? usage.cost : undefined;
+	if (!usage || !cost || !hasCompleteUsage(usage) || !isOfficialCodexModel(model)) return undefined;
+	const correctedUsage = structuredClone(usage) as typeof usage;
+	calculateCost(model, correctedUsage as never);
+	const multiplier = model.id === "gpt-5.5" ? 2.5 : 2;
+	const correctedCost = correctedUsage.cost as Record<string, number>;
+	for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+		correctedCost[key] *= multiplier;
+	}
+	if (costsEqual(cost, correctedCost)) return undefined;
+	return { ...message, usage: correctedUsage };
+}
+
+export function codexFastStatusLabel(status: string, enabled: boolean): string {
+	if (!enabled || !/^codex(?:\s|$)/u.test(status)) return status;
+	return status === "codex" ? "codex fast" : `codex fast${status.slice("codex".length)}`;
+}
+
+function isOfficialCodexModel(
+	model: PiModel | undefined,
+): model is PiModel & { api: "openai-codex-responses" } {
+	if (model?.provider !== "openai-codex" || !hasApi(model, "openai-codex-responses")) {
+		return false;
+	}
+	try {
+		return new URL(model.baseUrl).origin === "https://chatgpt.com";
+	} catch {
+		return false;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasCompleteUsage(value: Record<string, unknown>): boolean {
+	return ["input", "output", "cacheRead", "cacheWrite"].every(
+		(key) => typeof value[key] === "number" && Number.isFinite(value[key]),
+	);
+}
+
+function costsEqual(left: Record<string, unknown>, right: Record<string, number>): boolean {
+	return ["input", "output", "cacheRead", "cacheWrite", "total"].every(
+		(key) => left[key] === right[key],
+	);
+}

package/src/index.ts

@@ -1,3 +1,14 @@
+export {
+	CODEX_FAST_MODEL_IDS,
+	CODEX_FAST_SERVICE_TIER,
+	CODEX_STANDARD_SERVICE_TIER,
+	codexFastAvailability,
+	codexFastIsEffective,
+	codexFastRequestTier,
+	codexFastStatusLabel,
+	correctCodexFastMessageCost,
+	rewriteCodexFastPayload,
+} from "./codex-fast.js";
 export type {
 	CodexResetAvailability,
 	CodexResetOption,
@@ -32,6 +43,18 @@ export {
 	resolveUsageAuth,
 	SUPPORTED_ADAPTERS,
 } from "./query.js";
+export type {
+	UsageSettings,
+	UsageSettingsRuntime,
+	UsageSettingsState,
+} from "./settings.js";
+export {
+	createUsageSettingsRuntime,
+	DEFAULT_USAGE_SETTINGS,
+	loadUsageSettings,
+	normalizeUsageSettings,
+	usageSettingsPath,
+} from "./settings.js";
 export type {
 	ProviderUsageState,
 	ResolvedUsageAuth,

package/src/settings.ts

@@ -0,0 +1,208 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const USAGE_SETTINGS_FILE = "pi-usage.json";
+export const MAX_USAGE_SETTINGS_BYTES = 64 * 1024;
+
+export interface UsageSettings {
+	codexFastMode: boolean;
+}
+
+export const DEFAULT_USAGE_SETTINGS: Readonly<UsageSettings> = Object.freeze({
+	codexFastMode: false,
+});
+
+export interface UsageSettingsState {
+	kind: "missing" | "loaded" | "invalid";
+	path: string;
+	settings: UsageSettings;
+	document?: Record<string, unknown>;
+	issue?: string;
+}
+
+export interface UsageSettingsRuntime {
+	get(): Readonly<UsageSettingsState>;
+	reload(signal?: AbortSignal): Promise<Readonly<UsageSettingsState>>;
+	update(
+		patch: Partial<UsageSettings>,
+		signal?: AbortSignal,
+	): Promise<Readonly<UsageSettingsState>>;
+	flush(): Promise<void>;
+}
+
+interface UsageSettingsFileOperations {
+	rename: typeof rename;
+	writeFile: typeof writeFile;
+}
+
+interface UsageSettingsRuntimeOptions {
+	operations?: Partial<UsageSettingsFileOperations>;
+	path?: string;
+}
+
+export function usageSettingsPath(): string {
+	return join(getAgentDir(), USAGE_SETTINGS_FILE);
+}
+
+export function normalizeUsageSettings(value: unknown): UsageSettings | undefined {
+	if (!isRecord(value)) return undefined;
+	if (Object.hasOwn(value, "codexFastMode") && typeof value.codexFastMode !== "boolean") {
+		return undefined;
+	}
+	return {
+		codexFastMode:
+			typeof value.codexFastMode === "boolean"
+				? value.codexFastMode
+				: DEFAULT_USAGE_SETTINGS.codexFastMode,
+	};
+}
+
+export async function loadUsageSettings(
+	path = usageSettingsPath(),
+	signal?: AbortSignal,
+): Promise<UsageSettingsState> {
+	throwIfAborted(signal);
+	try {
+		const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+		let text: string;
+		try {
+			const stats = await handle.stat();
+			throwIfAborted(signal);
+			if (!stats.isFile()) throw new Error("settings path is not a regular file");
+			if (stats.size > MAX_USAGE_SETTINGS_BYTES) {
+				throw new Error("settings file exceeds 64 KiB");
+			}
+			text = await handle.readFile("utf8");
+		} finally {
+			await handle.close();
+		}
+		throwIfAborted(signal);
+		const document = JSON.parse(text) as unknown;
+		const settings = normalizeUsageSettings(document);
+		if (!settings || !isRecord(document)) throw new Error("invalid settings shape");
+		return { kind: "loaded", path, settings, document };
+	} catch (error) {
+		if (signal?.aborted) throw error;
+		if (isNodeError(error) && error.code === "ENOENT") {
+			return {
+				kind: "missing",
+				path,
+				settings: { ...DEFAULT_USAGE_SETTINGS },
+				document: {},
+			};
+		}
+		return {
+			kind: "invalid",
+			path,
+			settings: { ...DEFAULT_USAGE_SETTINGS },
+			issue:
+				isNodeError(error) && error.code === "ELOOP"
+					? "symbolic links are not accepted"
+					: error instanceof Error
+						? error.message
+						: String(error),
+		};
+	}
+}
+
+export function createUsageSettingsRuntime(
+	options: UsageSettingsRuntimeOptions | string = {},
+): UsageSettingsRuntime {
+	const path = typeof options === "string" ? options : (options.path ?? usageSettingsPath());
+	const operations: UsageSettingsFileOperations = {
+		rename,
+		writeFile,
+		...(typeof options === "string" ? undefined : options.operations),
+	};
+	let state: UsageSettingsState = {
+		kind: "missing",
+		path,
+		settings: { ...DEFAULT_USAGE_SETTINGS },
+		document: {},
+	};
+	let queue = Promise.resolve();
+	const enqueue = <T>(operation: () => Promise<T>): Promise<T> => {
+		const result = queue.then(operation, operation);
+		queue = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		return result;
+	};
+	return {
+		get: () => structuredClone(state),
+		reload: (signal) =>
+			enqueue(async () => {
+				const loaded = await loadUsageSettings(path, signal);
+				state = loaded;
+				return structuredClone(state);
+			}),
+		update: (patch, signal) =>
+			enqueue(async () => {
+				const saved = await saveUsageSettingsPatch(path, patch, operations, signal);
+				state = saved;
+				return structuredClone(state);
+			}),
+		flush: () => queue,
+	};
+}
+
+async function saveUsageSettingsPatch(
+	path: string,
+	patch: Partial<UsageSettings>,
+	operations: UsageSettingsFileOperations,
+	signal?: AbortSignal,
+): Promise<UsageSettingsState> {
+	const latest = await loadUsageSettings(path, signal);
+	if (latest.kind === "invalid") {
+		throw new Error("Cannot overwrite an invalid pi-usage.json; repair it and reload first");
+	}
+	const document = { ...latest.document, ...patch };
+	const settings = normalizeUsageSettings(document);
+	if (!settings) throw new Error("Refusing to save invalid pi-usage settings");
+	const directory = dirname(path);
+	const temporaryPath = join(directory, `.${basename(path)}.${randomUUID()}.tmp`);
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	throwIfAborted(signal);
+	try {
+		await operations.writeFile(temporaryPath, `${JSON.stringify(document, null, 2)}\n`, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 0o600,
+		});
+		if (process.platform !== "win32") await chmodPrivate(temporaryPath);
+		throwIfAborted(signal);
+		const current = await loadUsageSettings(path, signal);
+		if (
+			current.kind === "invalid" ||
+			current.kind !== latest.kind ||
+			JSON.stringify(current.document) !== JSON.stringify(latest.document)
+		) {
+			throw new Error("pi-usage.json changed while saving; retry the action");
+		}
+		throwIfAborted(signal);
+		await operations.rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+	return { kind: "loaded", path, settings, document };
+}
+
+async function chmodPrivate(path: string): Promise<void> {
+	await chmod(path, 0o600);
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw new DOMException("Settings operation aborted", "AbortError");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}

package/src/usage-helpers.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sanitizeDisplayText } from "./core.js";
+import { providerIsConfigured, SUPPORTED_ADAPTERS } from "./query.js";
+import type { PiModel, UsageProviderAdapter } from "./types.js";
+
+export function configuredAdapters(ctx: ExtensionContext): UsageProviderAdapter[] {
+	return SUPPORTED_ADAPTERS.filter(
+		(adapter) => adapter.id === ctx.model?.provider || providerIsConfigured(ctx, adapter.id),
+	);
+}
+
+export function providerDisplayName(ctx: ExtensionContext, providerId: string): string {
+	try {
+		return sanitizeDisplayText(ctx.modelRegistry.getProviderDisplayName(providerId), 80);
+	} catch {
+		return sanitizeDisplayText(providerId, 80);
+	}
+}
+
+export function setBoundedMap<T>(map: Map<string, T>, key: string, value: T, limit: number): void {
+	map.delete(key);
+	while (map.size >= limit) {
+		const oldest = map.keys().next().value;
+		if (oldest === undefined) break;
+		map.delete(oldest);
+	}
+	map.set(key, value);
+}
+
+export function modelIdentity(model: PiModel | undefined): string | undefined {
+	return model ? `${model.provider}/${model.id}` : undefined;
+}
+
+export function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}
+
+export function isTimeoutError(error: unknown): boolean {
+	return error instanceof Error && error.name === "TimeoutError";
+}

package/src/usage.ts

@@ -4,6 +4,7 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { FAST_USAGE_WARNING, registerCodexFastMode } from "./codex-fast-runtime.js";
 import {
 	type CodexResetAvailability,
 	type CodexResetOption,
@@ -19,22 +20,15 @@ import {
 	resetOptionExpiration,
 	resolveCodexResetAuth,
 } from "./codex-resets.js";
-import {
-	awaitWithDeadline,
-	errorMessage,
-	runWithConcurrency,
-	sanitizeDisplayText,
-	UsageCache,
-} from "./core.js";
+import { awaitWithDeadline, errorMessage, runWithConcurrency, UsageCache } from "./core.js";
 import { formatProviderStates, formatUsageStatusline } from "./format.js";
 import {
 	adapterForProvider,
 	isStaleExtensionContextError,
-	providerIsConfigured,
 	queryProviderUsage,
 	resolveUsageAuth,
-	SUPPORTED_ADAPTERS,
 } from "./query.js";
+import { createUsageSettingsRuntime, type UsageSettingsRuntime } from "./settings.js";
 import type {
 	PiModel,
 	ProviderUsageState,
@@ -42,6 +36,14 @@ import type {
 	UsageDisplayState,
 	UsageProviderAdapter,
 } from "./types.js";
+import {
+	configuredAdapters,
+	isAbortError,
+	isTimeoutError,
+	modelIdentity,
+	providerDisplayName,
+	setBoundedMap,
+} from "./usage-helpers.js";
 
 const CACHE_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 15_000;
@@ -59,6 +61,7 @@ const REDEEM_CODEX_RESET = "Redeem usage limit reset…";
 type UsageExtensionDependencies = {
 	credentialReader?: (providerId: string) => unknown;
 	createRedemptionId?: () => string;
+	settingsRuntime?: UsageSettingsRuntime;
 };
 
 type QueryOutcome = {
@@ -78,6 +81,7 @@ export default function usageExtension(
 ) {
 	const credentialReader = dependencies.credentialReader;
 	const createRedemptionId = dependencies.createRedemptionId ?? randomUUID;
+	const settingsRuntime = dependencies.settingsRuntime ?? createUsageSettingsRuntime();
 	const cache = new UsageCache(CACHE_TTL_MS);
 	const failureBackoff = new Map<string, { until: number; message: string }>();
 	const latestQueries = new Map<string, number>();
@@ -88,6 +92,7 @@ export default function usageExtension(
 	let statusGeneration = 0;
 	let statusRefreshTimer: ReturnType<typeof setTimeout> | undefined;
 	let statusController: AbortController | undefined;
+	let fastRuntime: ReturnType<typeof registerCodexFastMode>;
 
 	const clearStatusTimer = () => {
 		if (statusRefreshTimer) clearTimeout(statusRefreshTimer);
@@ -145,7 +150,8 @@ export default function usageExtension(
 			}
 			return;
 		}
-		const value = formatUsageStatusline(outcome.state.report, model);
+		const rawValue = formatUsageStatusline(outcome.state.report, model);
+		const value = rawValue ? fastRuntime.decorateStatus(model, rawValue) : undefined;
 		if (!safeSetStatus(ctx, value)) return;
 		if (shouldSchedule && sessionActive) scheduleStatusRefresh(ctx, model);
 	};
@@ -497,6 +503,7 @@ export default function usageExtension(
 			publishStableCurrent(ctx, stableCurrent);
 			let current = stableCurrent.outcome;
 			let visibleStates: ProviderUsageState[] = [current.state];
+			let fastState = settingsRuntime.get();
 			let resetAvailability: CodexResetAvailability | undefined;
 			let selectedReset: CodexResetOption | undefined;
 			let resetAuthFingerprint: string | undefined;
@@ -515,6 +522,7 @@ export default function usageExtension(
 				| "reset-error";
 			type Action =
 				| "refresh"
+				| "toggle-fast"
 				| "another"
 				| "all"
 				| "provider"
@@ -527,29 +535,54 @@ export default function usageExtension(
 			const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
 				start: "main",
 				screens: {
-					main: () => ({
-						kind: "actions",
-						title: "Provider usage",
-						lines: formatProviderStates(visibleStates).split("\n"),
-						items: [
-							{ id: "refresh", label: REFRESH_CURRENT, action: "refresh" },
-							...(current.state.status === "ready" && current.state.providerId === "openai-codex"
-								? [
-										{
-											id: "open-resets",
-											label: REDEEM_CODEX_RESET,
-											description: codexResetActionDescription(current.state.report),
-											disabled: codexResetCount(current.state.report) === 0,
-											action: "open-resets" as const,
-										},
-									]
-								: []),
-							{ id: "another", label: VIEW_ANOTHER, action: "another" },
-							{ id: "all", label: VIEW_ALL, action: "all" },
-							{ id: "close", label: CLOSE, close: true },
-						],
-						hint: "close",
-					}),
+					main: () => {
+						const fastAvailability = fastRuntime.availability(ctx.model);
+						const fastLines =
+							fastAvailability.kind === "available"
+								? [`Fast mode: ${fastAvailability.enabled ? "On" : "Off"}`, FAST_USAGE_WARNING]
+								: fastAvailability.kind === "unavailable"
+									? [`Fast mode: Unavailable · ${fastAvailability.reason}`]
+									: [];
+						return {
+							kind: "actions",
+							title: "Provider usage",
+							lines: [...formatProviderStates(visibleStates).split("\n"), ...fastLines],
+							items: [
+								{ id: "refresh", label: REFRESH_CURRENT, action: "refresh" },
+								...(fastAvailability.kind === "available"
+									? [
+											{
+												id: "toggle-fast",
+												label: fastAvailability.enabled
+													? "Turn Fast mode off"
+													: "Turn Fast mode on",
+												description:
+													fastState.kind === "invalid"
+														? "Repair pi-usage.json and reload before changing Fast mode."
+														: FAST_USAGE_WARNING,
+												disabled: fastState.kind === "invalid",
+												action: "toggle-fast" as const,
+											},
+										]
+									: []),
+								...(current.state.status === "ready" && current.state.providerId === "openai-codex"
+									? [
+											{
+												id: "open-resets",
+												label: REDEEM_CODEX_RESET,
+												description: codexResetActionDescription(current.state.report),
+												disabled: codexResetCount(current.state.report) === 0,
+												action: "open-resets" as const,
+											},
+										]
+									: []),
+								{ id: "another", label: VIEW_ANOTHER, action: "another" },
+								{ id: "all", label: VIEW_ALL, action: "all" },
+								{ id: "close", label: CLOSE, close: true },
+							],
+							hint: "close",
+						};
+					},
 					providers: () => ({
 						kind: "actions",
 						title: "Select a configured provider",
@@ -621,6 +654,16 @@ export default function usageExtension(
 					}),
 				},
 				actions: {
+					"toggle-fast": async () => {
+						const availability = fastRuntime.availability(ctx.model);
+						if (availability.kind !== "available" || fastState.kind === "invalid") {
+							return { kind: "rejected" };
+						}
+						const changed = await fastRuntime.toggle(ctx, !availability.enabled, controller.signal);
+						if (!changed) return { kind: "rejected" };
+						fastState = settingsRuntime.get();
+						return { kind: "stay" };
+					},
 					"open-resets": async () => {
 						const summaryCount =
 							current.state.status === "ready" && current.state.providerId === "openai-codex"
@@ -891,24 +934,24 @@ export default function usageExtension(
 		}
 	};
 
-	const commandHandler = async (args: string, ctx: ExtensionCommandContext) => {
-		if (args.trim()) {
-			ctx.ui.notify("/usage does not accept arguments; choose an action from its menu.", "warning");
-			return;
-		}
-		try {
-			await showMenu(ctx);
-		} catch (error) {
-			if (isStaleExtensionContextError(error) || isAbortError(error)) return;
-			throw error;
-		}
-	};
-
 	pi.registerCommand("usage", {
 		description: "Show usage for the current runtime account",
-		handler: commandHandler,
+		handler: async (args, ctx) => {
+			if (args.trim()) {
+				ctx.ui.notify(
+					"/usage does not accept arguments; choose an action from its menu.",
+					"warning",
+				);
+				return;
+			}
+			try {
+				await showMenu(ctx);
+			} catch (error) {
+				if (isStaleExtensionContextError(error) || isAbortError(error)) return;
+				throw error;
+			}
+		},
 	});
-
 	pi.on("session_start", (_event, ctx) => {
 		statusGeneration += 1;
 		clearStatusTimer();
@@ -940,40 +983,8 @@ export default function usageExtension(
 		activeCurrentIdentity = undefined;
 		safeSetStatus(ctx, undefined);
 	});
-}
 
-function configuredAdapters(ctx: ExtensionContext): UsageProviderAdapter[] {
-	return SUPPORTED_ADAPTERS.filter(
-		(adapter) => adapter.id === ctx.model?.provider || providerIsConfigured(ctx, adapter.id),
+	fastRuntime = registerCodexFastMode(pi, settingsRuntime, (ctx) =>
+		startStatusRefresh(ctx, ctx.model, false),
 	);
 }
-
-function providerDisplayName(ctx: ExtensionContext, providerId: string): string {
-	try {
-		return sanitizeDisplayText(ctx.modelRegistry.getProviderDisplayName(providerId), 80);
-	} catch {
-		return sanitizeDisplayText(providerId, 80);
-	}
-}
-
-function setBoundedMap<T>(map: Map<string, T>, key: string, value: T, limit: number): void {
-	map.delete(key);
-	while (map.size >= limit) {
-		const oldest = map.keys().next().value;
-		if (oldest === undefined) break;
-		map.delete(oldest);
-	}
-	map.set(key, value);
-}
-
-function modelIdentity(model: PiModel | undefined): string | undefined {
-	return model ? `${model.provider}/${model.id}` : undefined;
-}
-
-function isAbortError(error: unknown): boolean {
-	return error instanceof Error && error.name === "AbortError";
-}
-
-function isTimeoutError(error: unknown): boolean {
-	return error instanceof Error && error.name === "TimeoutError";
-}