@narumitw/pi-usage 0.60.4 → 0.60.7

package/docs/providers.md

@@ -259,6 +259,13 @@ The extension classifies both forms by the provider's window unit and does not l
 The quota monitor expects a raw API key without a `Bearer` prefix.
 The extension removes that prefix from resolved authorization before sending it to the monitor endpoint.
 Fingerprinting and redaction keep using the original resolved credential.
-A credential with no coding plan answers HTTP 200 without a data object; that is reported as `Unsupported` rather than a query failure, so the statusline stays empty.
+Quota errors use fixed English hints for the [documented Z.AI business error codes](https://docs.z.ai/api-reference/api-code), accepting nested `error.code` and the monitor endpoint's top-level `code` as strings or numbers.
+An explicit nested code takes precedence; when it is absent, the top-level code is used.
+For example, `1113` reports insufficient balance or no resource package, and `1309` reports an expired GLM Coding Plan.
+When a failed HTTP response has no business error code, the hint uses its HTTP status; unknown business codes use a generic API failure message.
+The monitor's top-level `code: 500` is not a documented business code and is not treated as HTTP 500 or proof that the credential has no Coding Plan.
+Error classification never matches or echoes provider `msg` or `error.message` text, which may contain credentials.
+Quota errors and missing or malformed quota data remain query failures with a statusline error hint, a 30-second request backoff, and scheduled retries; they no longer clear the statusline as unsupported.
+An accepted Z.AI query failure discards the matching cached report, so the next turn after backoff expires retries instead of restoring stale usage.
 The plan endpoint only contributes the plan name and renewal date; when it is unavailable or fails, the quota windows remain reported and the plan note falls back to the quota response's plan level.
 Only the official `api.z.ai` and `open.bigmodel.cn` origins are queried; other origins fail before sending the credential.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.60.4",
+	"version": "0.60.7",
 	"description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
 	"type": "module",
 	"license": "MIT",
@@ -71,6 +71,6 @@
 		"directory": "packages/pi-usage"
 	},
 	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.59.0"
+		"@narumitw/pi-tui-kit": "^0.61.0"
 	}
 }

package/src/core.ts

@@ -36,6 +36,10 @@ export class UsageCache {
 		this.entries.set(key, { createdAt: now, report });
 	}
 
+	delete(providerId: string, fingerprint: string): void {
+		this.entries.delete(cacheKey(providerId, fingerprint));
+	}
+
 	clearProvider(providerId: string): void {
 		for (const key of this.entries.keys()) {
 			if (key.startsWith(`${providerId}:`)) this.entries.delete(key);
@@ -198,10 +202,6 @@ export function errorMessage(error: unknown): string {
 	return sanitizeDisplayText(error instanceof Error ? error.message : String(error), 600);
 }
 
-// A credential the provider cannot meter is not a query failure: it is reported as unsupported, so
-// the statusline stays empty instead of holding an error chip that no retry will clear.
-export class UsageUnsupportedError extends Error {}
-
 export function abortError(): Error {
 	return Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
 }

package/src/providers/zai-errors.ts

@@ -0,0 +1,94 @@
+// Fixed messages from https://docs.z.ai/api-reference/api-code. Never interpolate provider text:
+// error messages and their template parameters can contain credentials or terminal controls.
+const ERROR_MESSAGES: Readonly<Record<string, string>> = {
+	"1000": "Authentication failed. Check your API key.",
+	"1001": "Authentication header missing. Check your API key.",
+	"1003": "Authentication token expired. Obtain a new token.",
+	"1005": "Two-factor authentication required.",
+	"1113": "Insufficient balance or no resource package. Recharge your account.",
+	"1200": "API call error. Try again later.",
+	"1210": "Invalid API parameter. Check the API documentation.",
+	"1211": "Unknown model. Check the model ID.",
+	"1212": "This model does not support the requested method.",
+	"1213": "A required parameter is missing.",
+	"1214": "Invalid parameter. Check the API documentation.",
+	"1215": "Conflicting parameters. Check the API documentation.",
+	"1220": "Access denied. Check your permissions.",
+	"1221": "This API has been taken offline.",
+	"1222": "This API does not exist.",
+	"1230": "API processing error. Try again later.",
+	"1234": "Network error. Try again later.",
+	"1261": "Prompt too long. Reduce the input length.",
+	"1301": "Content rejected by the safety policy.",
+	"1302": "Request rate limit reached. Try again later.",
+	"1305": "Service overloaded. Try again later.",
+	"1308": "Usage limit reached. Wait for the quota reset.",
+	"1309": "GLM Coding Plan expired. Renew your subscription.",
+	"1310": "Weekly or monthly limit exhausted. Wait for the quota reset.",
+	"1311": "Your subscription does not include this model.",
+	"1313": "Request frequency restricted by the Fair Usage Policy. Contact support.",
+	"1314": "Enterprise package expired. Contact your administrator.",
+	"1315": "This API key requires an enterprise coding package scenario. Replace the key.",
+	"1316": "5-hour limit reached; insufficient balance for extra usage. Wait for reset.",
+	"1317": "7-day limit reached; insufficient balance for extra usage. Wait for reset.",
+	"1318": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+	"1319": "7-day limit reached; extra usage blocked by monthly spend limit.",
+	"1320": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+	"1321": "7-day limit reached; extra usage blocked by monthly spend limit.",
+};
+
+const HTTP_MESSAGES: Readonly<Record<number, string>> = {
+	400: "Invalid request. Check the API documentation.",
+	401: "Authentication failed. Check your API key.",
+	403: "Access denied. Check your permissions.",
+	429: "Request or usage limit reached. Try again later.",
+	500: "Internal error. Try again later.",
+};
+
+export function zaiPayloadError(payload: unknown): string | undefined {
+	const object = asObject(payload);
+	if (!object) return undefined;
+	const nested = asObject(object.error);
+	// Missing nested metadata must not hide a top-level code; explicit nested values retain priority.
+	const rawCode = nested?.code === undefined ? object.code : nested.code;
+	const code = errorCode(rawCode);
+	if (
+		object.error === undefined &&
+		object.success !== false &&
+		(rawCode === undefined || code === "0" || code === "200")
+	) {
+		return undefined;
+	}
+	return code && code !== "0" && code !== "200"
+		? `Z.AI ${code}: ${ERROR_MESSAGES[code] ?? "API request failed."}`
+		: "Z.AI: API request failed.";
+}
+
+export function zaiResponseError(status: number, text: string): string | undefined {
+	let payload: unknown;
+	try {
+		payload = JSON.parse(text) as unknown;
+	} catch {
+		// Do not expose JSON parser excerpts, response bodies, or statusText.
+		if (status >= 200 && status < 300) return "Z.AI: Invalid JSON response.";
+	}
+	const error = zaiPayloadError(payload);
+	if (error) return error;
+	if (status < 200 || status >= 300) {
+		return `Z.AI HTTP ${status}: ${HTTP_MESSAGES[status] ?? "API request failed."}`;
+	}
+	return undefined;
+}
+
+function errorCode(value: unknown): string | undefined {
+	if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 9999) {
+		return String(value);
+	}
+	return typeof value === "string" && /^(?:0|[1-9]\d{0,3})$/u.test(value) ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}

package/src/providers/zai.ts

@@ -1,4 +1,4 @@
-import { sanitizeDisplayText, UsageUnsupportedError } from "../core.js";
+import { sanitizeDisplayText } from "../core.js";
 import type {
 	UsageBucket,
 	UsageMetric,
@@ -8,6 +8,8 @@ import type {
 	ZaiSubscriptionPayload,
 } from "../types.js";
 
+import { zaiPayloadError } from "./zai-errors.js";
+
 const FIVE_HOUR_WINDOW_MINUTES = 300;
 const WEEKLY_WINDOW_MINUTES = 10_080;
 
@@ -18,15 +20,10 @@ export function normalizeZaiQuotaPayload(
 	capturedAt: number,
 	plan?: ZaiPlanInfo,
 ): UsageReport {
+	const error = zaiPayloadError(payload);
+	if (error) throw new Error(error);
 	const data = asObject(payload.data);
-	// A credential with no coding plan answers HTTP 200 with no data object:
-	// {"code":500,"msg":"当前用户不存在coding plan","success":false}. API usage is not metered.
-	if (!data) {
-		const reason = asString(payload.msg);
-		throw new UsageUnsupportedError(
-			`No GLM Coding Plan on this Z.AI credential; API usage is not metered.${reason ? ` Z.AI reported: ${reason}` : ""}`,
-		);
-	}
+	if (!data) throw new Error("Z.AI quota response data was not an object.");
 	const limits = Array.isArray(data.limits) ? (data.limits as unknown[]) : [];
 
 	const buckets: UsageBucket[] = [];
@@ -88,10 +85,7 @@ export function normalizeZaiQuotaPayload(
 export function normalizeZaiSubscriptionPayload(
 	payload: ZaiSubscriptionPayload,
 ): ZaiPlanInfo | undefined {
-	if (payload.success === false) return undefined;
-	if (typeof payload.code === "number" && payload.code !== 0 && payload.code !== 200) {
-		return undefined;
-	}
+	if (zaiPayloadError(payload)) return undefined;
 	if (!Array.isArray(payload.data)) return undefined;
 
 	const candidates: Array<{

package/src/query.ts

@@ -2,12 +2,7 @@
 // separating that security boundary would duplicate request and redaction policy across providers.
 import { randomBytes } from "node:crypto";
 import { type ExtensionContext, readStoredCredential } from "@earendil-works/pi-coding-agent";
-import {
-	errorMessage,
-	fingerprintResolvedAuth,
-	redactUsageError,
-	UsageUnsupportedError,
-} from "./core.js";
+import { errorMessage, fingerprintResolvedAuth, redactUsageError } from "./core.js";
 import {
 	fallbackOAuthCredentialCandidates,
 	type OAuthCredentialCandidateReader,
@@ -29,6 +24,7 @@ import { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
 import { normalizeVercelAIGatewayCreditsPayload } from "./providers/vercel-ai-gateway.js";
 import { normalizeXaiBillingPayload } from "./providers/xai.js";
 import { normalizeZaiQuotaPayload, normalizeZaiSubscriptionPayload } from "./providers/zai.js";
+import { zaiResponseError } from "./providers/zai-errors.js";
 import type {
 	BasetenBillingUsagePayload,
 	CodexBackendPayload,
@@ -266,6 +262,7 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 	{
 		id: "zai",
 		displayName: "Z.AI",
+		invalidateCacheOnFailure: true,
 		semantics: { kind: "consumer-subscription", label: "GLM Coding Plan usage" },
 		async query(auth, signal, timeoutMs, guard) {
 			return queryZaiUsage("zai", "Z.AI", auth, signal, timeoutMs, guard);
@@ -274,6 +271,7 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 	{
 		id: "zai-coding-cn",
 		displayName: "Z.AI Coding CN",
+		invalidateCacheOnFailure: true,
 		semantics: { kind: "consumer-subscription", label: "GLM Coding Plan usage" },
 		async query(auth, signal, timeoutMs, guard) {
 			return queryZaiUsage("zai-coding-cn", "Z.AI Coding CN", auth, signal, timeoutMs, guard);
@@ -552,11 +550,7 @@ export async function queryProviderUsage(
 		);
 	} catch (error) {
 		if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
-		const message = redactUsageError(errorMessage(error), auth.secrets);
-		// Redaction rebuilds the error, so the unsupported signal has to be carried across.
-		throw error instanceof UsageUnsupportedError
-			? new UsageUnsupportedError(message)
-			: new Error(message);
+		throw new Error(redactUsageError(errorMessage(error), auth.secrets));
 	}
 }
 
@@ -636,6 +630,7 @@ export async function fetchProviderJson(
 		body?: Record<string, unknown>;
 		redirect?: RequestRedirect;
 		userAgent?: boolean;
+		responseError?: (status: number, text: string) => string | undefined;
 	} = {},
 ): Promise<Record<string, unknown>> {
 	const controller = new AbortController();
@@ -674,6 +669,8 @@ export async function fetchProviderJson(
 		);
 		if (controller.signal.aborted)
 			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+		const responseError = request.responseError?.(response.status, text);
+		if (responseError) throw new Error(responseError);
 		if (!response.ok) {
 			throw new Error(
 				`${description} returned ${response.status} ${response.statusText}: ${redactUsageError(text, auth.secrets)}`,
@@ -1110,6 +1107,7 @@ async function queryZaiUsage(
 		signal,
 		remainingTimeout(timeoutMs, startedAt, `fetching ${providerName} quota`),
 		`${providerName} quota endpoint`,
+		{ responseError: zaiResponseError },
 	)) as ZaiQuotaPayload;
 	await guard();
 	const planTimeoutMs = timeoutMs - (Date.now() - startedAt);
@@ -1134,6 +1132,7 @@ async function fetchZaiPlan(
 			signal,
 			timeoutMs,
 			`${providerName} plan endpoint`,
+			{ responseError: zaiResponseError },
 		)) as ZaiSubscriptionPayload;
 		return normalizeZaiSubscriptionPayload(payload);
 	} catch (error) {

package/src/types.ts

@@ -91,6 +91,8 @@ export interface UsageProviderAdapter {
 	displayName: string;
 	semantics: UsageSemantics;
 	publishesStatusline?: boolean;
+	/** Invalidate the matching ready report when the latest query fails; default preserves it. */
+	invalidateCacheOnFailure?: boolean;
 	targets?: UsageTargetResolver;
 	query(
 		auth: ResolvedUsageAuth,
@@ -191,11 +193,14 @@ export type OpenCodeZenPayload = {
 };
 
 export type ZaiQuotaPayload = {
-	msg?: unknown;
+	error?: unknown;
+	code?: unknown;
+	success?: unknown;
 	data?: unknown;
 };
 
 export type ZaiSubscriptionPayload = {
+	error?: unknown;
 	code?: unknown;
 	success?: unknown;
 	data?: unknown;

package/src/usage-settings-ui.ts

@@ -3,14 +3,7 @@ import {
 	type ExtensionCommandContext,
 	getSettingsListTheme,
 } from "@earendil-works/pi-coding-agent";
-import {
-	Container,
-	Key,
-	matchesKey,
-	type SettingItem,
-	SettingsList,
-	Text,
-} from "@earendil-works/pi-tui";
+import { Key, matchesKey, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
 import { errorMessage } from "./core.js";
 import type { UsageSettingsRuntime } from "./settings.js";
 
@@ -19,26 +12,6 @@ const ON = "On";
 
 type UsageSettingId = "codexFastMode" | "codexStatusResetCountdown";
 
-function fitSettingsRows(lines: string[], maxRows: number): string[] {
-	if (lines.length <= maxRows) return lines;
-	const content = lines.filter((line) => stripVTControlCharacters(line).trim().length > 0);
-	if (content.length <= maxRows) return content;
-	const selectedIndex = content.findIndex((line) =>
-		/^[→›]\s/u.test(stripVTControlCharacters(line)),
-	);
-	if (selectedIndex < 0) return content.slice(0, maxRows);
-	return content
-		.map((line, index) => ({ index, line }))
-		.sort(
-			(left, right) =>
-				Math.abs(left.index - selectedIndex) - Math.abs(right.index - selectedIndex) ||
-				left.index - right.index,
-		)
-		.slice(0, maxRows)
-		.sort((left, right) => left.index - right.index)
-		.map(({ line }) => line);
-}
-
 export async function showUsageSettings(
 	ctx: ExtensionCommandContext,
 	settingsRuntime: UsageSettingsRuntime,
@@ -50,7 +23,7 @@ export async function showUsageSettings(
 		if (ctx.hasUI) ctx.ui.notify(`Edit settings manually: ${settingsRuntime.get().path}`, "info");
 		return false;
 	}
-	const { HorizontalRule } = await import("@narumitw/pi-tui-kit");
+	const { HorizontalRule, renderBoundedFrame } = await import("@narumitw/pi-tui-kit");
 	if (parentSignal.aborted || !isCurrent()) return false;
 	return (
 		(await ctx.ui.custom<boolean>((tui, theme, _keybindings, done) => {
@@ -76,9 +49,7 @@ export async function showUsageSettings(
 					values: [OFF, ON],
 				},
 			];
-			const container = new Container();
 			const rule = new HorizontalRule({ ruleStyle: (text) => theme.fg("border", text) });
-			container.addChild(new Text(theme.fg("accent", theme.bold("pi-usage Settings")), 1, 1));
 
 			let settingsList: SettingsList;
 			const cancel = () => {
@@ -126,23 +97,34 @@ export async function showUsageSettings(
 				},
 				cancel,
 			);
-			container.addChild(settingsList);
 
 			parentSignal.addEventListener("abort", cancel, { once: true });
 			return {
 				render(width: number) {
-					const content = container.render(width);
+					// Compatibility: Kit puts the title directly below the top rule and keeps compact
+					// rules when at least five rows fit; both replace the legacy wrapper layout.
+					const title = new Text(theme.fg("accent", theme.bold("pi-usage Settings")), 1, 0).render(
+						width,
+					);
+					const content = settingsList.render(width);
+					const focusedRow = content.findIndex((line) =>
+						/^[→›]\s/u.test(stripVTControlCharacters(line)),
+					);
 					const terminalRows = Number.isFinite(tui.terminal?.rows)
 						? Math.floor(tui.terminal.rows)
 						: 24;
-					const availableRows = Math.max(1, terminalRows - 3);
-					if (content.length + 2 > availableRows) {
-						return fitSettingsRows(content, availableRows);
-					}
 					const [ruleLine = ""] = rule.render(width);
-					return [ruleLine, ...content, ruleLine];
+					return renderBoundedFrame({
+						width,
+						maxRows: Math.max(1, terminalRows - 3),
+						rule: ruleLine,
+						title,
+						content,
+						priorityRows: focusedRow < 0 ? [] : [focusedRow],
+						focusedRow,
+					});
 				},
-				invalidate: () => container.invalidate(),
+				invalidate: () => settingsList.invalidate(),
 				handleInput(data: string) {
 					if (closing) return;
 					if (matchesKey(data, Key.ctrl("c"))) cancel();

package/src/usage.ts

@@ -28,7 +28,6 @@ import {
 	errorMessage,
 	runWithConcurrency,
 	UsageCache,
-	UsageUnsupportedError,
 } from "./core.js";
 import { formatProviderStates, formatUsageStatusline } from "./format.js";
 import { createOAuthCredentialCandidateReader } from "./oauth-credential-source.js";
@@ -111,10 +110,7 @@ export default function usageExtension(
 	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; status: "query-failed" | "unsupported" }
-	>();
+	const failureBackoff = new Map<string, { until: number; message: string }>();
 	const latestQueries = new Map<string, number>();
 	const activeControllers = new Set<AbortController>();
 	let querySequence = 0;
@@ -363,7 +359,7 @@ export default function usageExtension(
 						providerId: adapter.id,
 						providerName,
 						displayState,
-						status: previousDiscoveryFailure.status,
+						status: "query-failed",
 						message: previousDiscoveryFailure.message,
 					},
 					fingerprint: auth.fingerprint,
@@ -424,7 +420,7 @@ export default function usageExtension(
 						providerId: adapter.id,
 						providerName,
 						displayState,
-						status: previousFailure.status,
+						status: "query-failed",
 						message: previousFailure.message,
 					},
 					fingerprint: auth.fingerprint,
@@ -483,18 +479,16 @@ export default function usageExtension(
 				);
 			}
 			const message = errorMessage(error);
-			const status = error instanceof UsageUnsupportedError ? "unsupported" : "query-failed";
 			const now = Date.now();
 			for (const [key, failure] of failureBackoff) {
 				if (failure.until <= now) failureBackoff.delete(key);
 			}
-			// Unsupported is throttled like a failure, so a credential the provider cannot meter does
-			// not re-query on every turn; the entry carries its status so the replay stays unsupported.
 			if (queryId === undefined || latestQueries.get(failureKey) === queryId) {
+				if (adapter.invalidateCacheOnFailure) cache.delete(adapter.id, queryFingerprint);
 				setBoundedMap(
 					failureBackoff,
 					failureKey,
-					{ until: now + FAILURE_BACKOFF_MS, message, status },
+					{ until: now + FAILURE_BACKOFF_MS, message },
 					MAX_ACCOUNT_STATES,
 				);
 			}
@@ -503,7 +497,7 @@ export default function usageExtension(
 					providerId: adapter.id,
 					providerName,
 					displayState,
-					status,
+					status: "query-failed",
 					message,
 				},
 				fingerprint: auth.fingerprint,