@narumitw/pi-usage 0.49.3 → 0.51.0

package/README.md

@@ -2,13 +2,15 @@
 
 [![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.
 - Provides explicit refresh, another-provider, and all-configured-provider actions.
@@ -35,7 +37,7 @@ pi -e npm:@narumitw/pi-usage
 Try this package locally from the repository root:
 
 ```bash
-pi -e ./extensions/pi-usage
+pi -e ./packages/pi-usage
 ```
 
 ## 🚀 Usage
@@ -51,6 +53,8 @@ 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…
 Close
@@ -62,18 +66,54 @@ and closes the root menu. Print and JSON modes reject `/usage` observably becaus
 interactive flow. The cancellable live-query progress view remains extension-owned because it streams
 provider work and supports in-flight abort rather than presenting a standard menu screen.
 
+For the current OpenAI Codex provider, **Redeem usage limit reset…** checks fresh earned-reset
+details, lets you select a reset when details are available, and shows the exact reset before asking
+for confirmation. **No, go back** is the safe default and cancellation before confirmation sends no
+mutation. After confirmation, the reset operation cannot be cancelled from its progress view; session
+replacement or shutdown still aborts owned work. A transport failure offers **Try again** with the
+same redemption request ID so the backend can treat an uncertain retry idempotently. Successful,
+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
 
 - Provider ID: `openai-codex`
 - Semantics: ChatGPT consumer subscription limits
-- Source: the Codex usage endpoint using Pi's resolved runtime authorization
+- 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
-- Statusline examples: `codex 59% 5h 61% wk` or `codex spark 100% 5h`
+- 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`, `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.
 
+Reset redemption is available only when Codex is the current provider and Pi's freshly resolved access
+token exactly matches its stored OpenAI Codex OAuth credential. `pi-usage` forwards only the bearer
+authorization and matching `chatgpt-account-id` to the official ChatGPT origin. API-key credentials,
+configured-but-not-current Codex accounts, account changes during the flow, and custom/proxy origins
+fail before mutation. Backend-provided titles and descriptions are sanitized for terminal display;
+opaque credit and account IDs are never shown or persisted by the extension.
+
 ### GitHub Copilot
 
 - Provider ID: `github-copilot`
@@ -119,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`.
@@ -127,21 +167,29 @@ Behavior changes:
 ## 🚧 Limitations
 
 - Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
-- GitHub Copilot quota uses an undocumented GitHub endpoint that may change without notice.
+- GitHub Copilot quota and OpenAI Codex reset redemption use undocumented provider endpoints that may change without notice.
+- Codex reset redemption requires a current ChatGPT OAuth login created through Pi; Codex API keys cannot redeem earned subscription resets.
 - Credentials resolved for custom provider base URLs are never forwarded to the providers' official usage endpoints; effective auth origin validation requires Pi 0.81.0 or newer.
 - Provider reports are snapshots and may themselves be delayed by the provider.
 - 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
 
 ```txt
-extensions/pi-usage/
+packages/pi-usage/
 ├── src/
 │   ├── index.ts       # Pi package entrypoint and helper export barrel
-│   ├── usage.ts       # Menu, cache, and lifecycle orchestration
-│   ├── query.ts       # Runtime auth resolution and provider queries
+│   ├── 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
 │   ├── core.ts        # Cache, concurrency, fingerprint, and redaction helpers
 │   ├── providers/     # Codex, GitHub Copilot, and OpenRouter normalization adapters

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.49.3",
+	"version": "0.51.0",
 	"description": "Pi extension that shows current-account usage for Codex, GitHub Copilot, and OpenRouter.",
 	"type": "module",
 	"license": "MIT",
@@ -25,24 +25,29 @@
 			"./src/index.ts"
 		]
 	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
 	"scripts": {
 		"check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json README.md && npm run typecheck",
 		"format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json README.md",
 		"typecheck": "tsc --noEmit"
 	},
 	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.7",
-		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@earendil-works/pi-ai": "0.84.1",
+		"@earendil-works/pi-coding-agent": "0.84.1",
 		"@types/node": "26.1.2",
 		"typescript": "7.0.2"
 	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-usage"
+		"directory": "packages/pi-usage"
 	},
 	"dependencies": {
 		"@narumitw/pi-tui-kit": "^0.49.1"

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],
+	);
+}