jeopi-ai 16.2.13

package/src/usage/zai.ts

@@ -0,0 +1,321 @@
+import { toNumber } from "jeopi-catalog/utils";
+import type {
+	UsageAmount,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+	UsageStatus,
+	UsageWindow,
+} from "../usage";
+import { isRecord } from "../utils";
+
+const DEFAULT_ENDPOINT = "https://api.z.ai";
+const QUOTA_PATH = "/api/monitor/usage/quota/limit";
+const MODEL_USAGE_PATH = "/api/monitor/usage/model-usage";
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const WEEK_MS = 7 * DAY_MS;
+const MONTH_MS = 30 * DAY_MS;
+
+interface ZaiUsageDetail {
+	modelCode?: string;
+	usage?: number;
+}
+
+function normalizeZaiBaseUrl(baseUrl?: string): string {
+	if (!baseUrl?.trim()) return DEFAULT_ENDPOINT;
+	try {
+		return new URL(baseUrl.trim()).origin;
+	} catch {
+		return DEFAULT_ENDPOINT;
+	}
+}
+
+interface ZaiUsageLimitItem {
+	type?: string;
+	usage?: number;
+	currentValue?: number;
+	percentage?: number;
+	remaining?: number;
+	nextResetTime?: number;
+	unit?: number;
+	number?: number;
+	usageDetails?: ZaiUsageDetail[];
+}
+
+interface ZaiQuotaPayload {
+	success?: boolean;
+	code?: number;
+	msg?: string;
+	data?: {
+		limits?: ZaiUsageLimitItem[];
+	};
+}
+
+function parseMillis(value: unknown): number | undefined {
+	const parsed = toNumber(value);
+	if (parsed === undefined) return undefined;
+	return parsed > 1_000_000_000_000 ? parsed : parsed * 1000;
+}
+
+function parseUsageDetails(value: unknown): ZaiUsageDetail[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const details: ZaiUsageDetail[] = [];
+	for (const item of value) {
+		if (!isRecord(item)) continue;
+		const modelCode = typeof item.modelCode === "string" && item.modelCode ? item.modelCode : undefined;
+		const usage = toNumber(item.usage);
+		details.push({
+			...(modelCode !== undefined ? { modelCode } : {}),
+			...(usage !== undefined ? { usage } : {}),
+		});
+	}
+	return details.length > 0 ? details : undefined;
+}
+
+function parseLimitItem(value: unknown): ZaiUsageLimitItem | null {
+	if (!isRecord(value)) return null;
+	const type = typeof value.type === "string" ? value.type : undefined;
+	if (!type) return null;
+	return {
+		type,
+		usage: toNumber(value.usage),
+		currentValue: toNumber(value.currentValue),
+		percentage: toNumber(value.percentage),
+		remaining: toNumber(value.remaining),
+		nextResetTime: parseMillis(value.nextResetTime),
+		unit: toNumber(value.unit),
+		number: toNumber(value.number),
+		usageDetails: parseUsageDetails(value.usageDetails),
+	};
+}
+
+function buildUsageAmount(args: {
+	used: number | undefined;
+	limit: number | undefined;
+	remaining: number | undefined;
+	unit: UsageAmount["unit"];
+	percentage?: number;
+}): UsageAmount {
+	const usedFraction =
+		args.percentage !== undefined
+			? Math.min(Math.max(args.percentage / 100, 0), 1)
+			: args.used !== undefined && args.limit !== undefined && args.limit > 0
+				? Math.min(args.used / args.limit, 1)
+				: undefined;
+	const remainingFraction = usedFraction !== undefined ? Math.max(1 - usedFraction, 0) : undefined;
+	return {
+		used: args.used,
+		limit: args.limit,
+		remaining: args.remaining,
+		usedFraction,
+		remainingFraction,
+		unit: args.unit,
+	};
+}
+
+function getUsageStatus(usedFraction: number | undefined): UsageStatus | undefined {
+	if (usedFraction === undefined) return undefined;
+	if (usedFraction >= 1) return "exhausted";
+	if (usedFraction >= 0.9) return "warning";
+	return "ok";
+}
+
+function formatDate(value: Date): string {
+	const pad = (input: number) => String(input).padStart(2, "0");
+	return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}+${pad(value.getHours())}:${pad(
+		value.getMinutes(),
+	)}:${pad(value.getSeconds())}`;
+}
+
+function formatCountedUnit(count: number, singular: string): string {
+	const suffix = count === 1 ? "" : "s";
+	return `${count} ${singular}${suffix}`;
+}
+
+function buildZaiWindow(parsed: ZaiUsageLimitItem): UsageWindow {
+	const count = parsed.number !== undefined && parsed.number > 0 ? parsed.number : 1;
+	let id: string;
+	let label: string;
+	let durationMs: number | undefined;
+	switch (parsed.unit) {
+		case 3:
+			id = `${count}h`;
+			label = formatCountedUnit(count, "Hour");
+			durationMs = count * HOUR_MS;
+			break;
+		case 4:
+			id = `${count}d`;
+			label = formatCountedUnit(count, "Day");
+			durationMs = count * DAY_MS;
+			break;
+		case 5:
+			id = `${count}mo`;
+			label = count === 1 ? "Monthly" : formatCountedUnit(count, "Month");
+			durationMs = count * MONTH_MS;
+			break;
+		case 6:
+			id = "1w";
+			label = "Weekly";
+			durationMs = WEEK_MS;
+			break;
+		default:
+			id = parsed.unit !== undefined ? `${count}u${parsed.unit}` : "quota";
+			label = "Quota";
+			break;
+	}
+	return {
+		id,
+		label,
+		...(durationMs !== undefined ? { durationMs } : {}),
+		...(parsed.nextResetTime !== undefined ? { resetsAt: parsed.nextResetTime } : {}),
+	};
+}
+
+function requestQuotaLabel(parsed: ZaiUsageLimitItem): string {
+	const detailCodes =
+		parsed.usageDetails?.map(detail => detail.modelCode).filter((code): code is string => !!code) ?? [];
+	if (detailCodes.includes("search-prime") && detailCodes.includes("web-reader") && detailCodes.includes("zread")) {
+		return "ZAI Web Search / Reader / Zread Quota";
+	}
+	return "ZAI Request Quota";
+}
+
+function buildModelUsageUrl(baseUrl: string, now: Date): string {
+	const start = new Date(now.getTime() - SEVEN_DAYS_MS);
+	const startTime = formatDate(start);
+	const endTime = formatDate(now);
+	return `${baseUrl}${MODEL_USAGE_PATH}?startTime=${encodeURIComponent(startTime)}&endTime=${encodeURIComponent(endTime)}`;
+}
+
+async function fetchZaiUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+	if (params.provider !== "zai") return null;
+	const credential = params.credential;
+	if (credential.type !== "api_key" || !credential.apiKey) return null;
+
+	const baseUrl = normalizeZaiBaseUrl(params.baseUrl);
+	const url = `${baseUrl}${QUOTA_PATH}`;
+	const headers: Record<string, string> = {
+		Authorization: credential.apiKey,
+		"Content-Type": "application/json",
+		"User-Agent": "OpenCode-Status-Plugin/1.0",
+	};
+
+	let payload: ZaiQuotaPayload | null = null;
+	try {
+		const response = await ctx.fetch(url, {
+			headers,
+			signal: params.signal,
+		});
+		if (!response.ok) {
+			ctx.logger?.warn("ZAI usage fetch failed", { status: response.status, statusText: response.statusText });
+			return null;
+		}
+		payload = (await response.json()) as ZaiQuotaPayload;
+	} catch (error) {
+		ctx.logger?.warn("ZAI usage fetch error", { error: String(error) });
+		return null;
+	}
+
+	if (!payload) return null;
+	if (payload.success !== true) {
+		ctx.logger?.warn("ZAI usage response invalid", { code: payload.code, message: payload.msg });
+		return null;
+	}
+
+	const limitsPayload = Array.isArray(payload.data?.limits) ? payload.data?.limits : [];
+	const limits: UsageLimit[] = [];
+
+	for (const rawLimit of limitsPayload) {
+		const parsed = parseLimitItem(rawLimit);
+		if (!parsed) continue;
+		if (parsed.type === "TOKENS_LIMIT") {
+			const amount = buildUsageAmount({
+				used: parsed.currentValue,
+				limit: parsed.usage,
+				remaining: parsed.remaining,
+				percentage: parsed.percentage,
+				unit: "tokens",
+			});
+			const window = buildZaiWindow(parsed);
+			limits.push({
+				id: `zai:tokens:${window.id}`,
+				label: `ZAI ${window.label} Token Quota`,
+				scope: {
+					provider: params.provider,
+					windowId: window.id,
+					shared: true,
+				},
+				window,
+				amount,
+				status: getUsageStatus(amount.usedFraction),
+			});
+		}
+		if (parsed.type === "TIME_LIMIT") {
+			const window = buildZaiWindow(parsed);
+			const amount = buildUsageAmount({
+				used: parsed.currentValue,
+				limit: parsed.usage,
+				remaining: parsed.remaining,
+				percentage: parsed.percentage,
+				unit: "requests",
+			});
+			limits.push({
+				id: `zai:requests:${window.id}`,
+				label: requestQuotaLabel(parsed),
+				scope: {
+					provider: params.provider,
+					windowId: window.id,
+					shared: true,
+				},
+				window,
+				amount,
+				status: getUsageStatus(amount.usedFraction),
+			});
+		}
+	}
+
+	if (limits.length === 0) return null;
+
+	const report: UsageReport = {
+		provider: params.provider,
+		fetchedAt: Date.now(),
+		limits,
+		metadata: {
+			endpoint: url,
+			accountId: credential.accountId,
+			email: credential.email,
+		},
+		raw: payload,
+	};
+
+	const modelUsageUrl = buildModelUsageUrl(baseUrl, new Date());
+	try {
+		const response = await ctx.fetch(modelUsageUrl, {
+			headers,
+			signal: params.signal,
+		});
+		if (response.ok) {
+			const modelUsagePayload = (await response.json()) as unknown;
+			if (isRecord(modelUsagePayload)) {
+				report.metadata = {
+					...report.metadata,
+					modelUsage: modelUsagePayload,
+				};
+			}
+		}
+	} catch (error) {
+		ctx.logger?.debug("ZAI model usage fetch failed", { error: String(error) });
+	}
+
+	return report;
+}
+
+export const zaiUsageProvider: UsageProvider = {
+	id: "zai",
+	fetchUsage: fetchZaiUsage,
+	supports: params => params.provider === "zai" && params.credential.type === "api_key",
+};

package/src/usage.ts

@@ -0,0 +1,333 @@
+/**
+ * Usage reporting types for provider quota/limit endpoints.
+ *
+ * Provides a normalized schema to represent multiple limit windows, model tiers,
+ * and shared quotas across providers.
+ */
+import { type } from "arktype";
+import type { FetchImpl, Provider } from "./types";
+export type UsageUnit = "percent" | "tokens" | "requests" | "usd" | "minutes" | "bytes" | "unknown";
+
+export type UsageStatus = "ok" | "warning" | "exhausted" | "unknown";
+
+/** Time window for a limit (e.g. 5h, 7d, monthly). */
+export interface UsageWindow {
+	/** Stable identifier (e.g. "5h", "7d", "monthly"). */
+	id: string;
+	/** Human label (e.g. "5 Hour", "7 Day"). */
+	label: string;
+	/** Window duration in milliseconds, when known. */
+	durationMs?: number;
+	/** Absolute reset timestamp in milliseconds since epoch. */
+	resetsAt?: number;
+}
+
+/** Quantitative usage data. */
+export interface UsageAmount {
+	/** Amount used in the given unit. */
+	used?: number;
+	/** Maximum limit in the given unit. */
+	limit?: number;
+	/** Remaining amount in the given unit. */
+	remaining?: number;
+	/** Fraction used (0..1). */
+	usedFraction?: number;
+	/** Fraction remaining (0..1). */
+	remainingFraction?: number;
+	/** Unit for the amounts (percent, tokens, etc.). */
+	unit: UsageUnit;
+}
+
+/** Scope metadata describing what the limit applies to. */
+export interface UsageScope {
+	provider: Provider;
+	accountId?: string;
+	projectId?: string;
+	orgId?: string;
+	modelId?: string;
+	tier?: string;
+	windowId?: string;
+	shared?: boolean;
+}
+
+/** Normalized limit entry for a single window or quota bucket. */
+export interface UsageLimit {
+	/** Stable identifier for this limit entry. */
+	id: string;
+	/** Human label for display. */
+	label: string;
+	scope: UsageScope;
+	window?: UsageWindow;
+	amount: UsageAmount;
+	status?: UsageStatus;
+	notes?: string[];
+}
+
+/**
+ * Per-credit detail for a saved/banked rate-limit reset.
+ *
+ * Populated when the provider's listing endpoint returns individual credit
+ * metadata (e.g. OpenAI Codex `wham/rate-limit-reset-credits`). Callers that
+ * only need the count can ignore this; display layers use `expiresAt` to show
+ * when banked resets expire ([#3339](https://github.com/can1357/oh-my-pi/issues/3339)).
+ */
+export interface UsageResetCreditDetail {
+	/** ISO timestamp when the credit was granted. */
+	grantedAt?: string;
+	/** ISO timestamp when the credit expires and can no longer be redeemed. */
+	expiresAt?: string;
+	/** Backend status, e.g. `available`, `redeemed`. */
+	status?: string;
+}
+
+/**
+ * Saved/banked rate-limit resets an account can redeem on demand.
+ *
+ * Surfaced by providers that let users defer a usage-window reset and spend it
+ * later (OpenAI Codex "saved rate limit resets"). The redeem itself is a
+ * separate, provider-specific action; this is the read-only count for display.
+ */
+export interface UsageResetCredits {
+	/** Number of resets available to redeem right now. */
+	availableCount: number;
+	/** Individual credit details (expiry dates, etc.) when the provider exposes them. */
+	credits?: UsageResetCreditDetail[];
+}
+
+/** Aggregated usage report for a provider. */
+export interface UsageReport {
+	provider: Provider;
+	fetchedAt: number;
+	limits: UsageLimit[];
+	/** Saved rate-limit resets the account can redeem, when the provider reports them. */
+	resetCredits?: UsageResetCredits;
+	/**
+	 * Provider-wide disclaimers shown once above per-account sections.
+	 * Use this for caveats that apply to every limit (e.g. "OMP-observed
+	 * spend only"). Per-limit notes that differ per window (e.g. "Overage
+	 * requests: N") stay on {@link UsageLimit.notes}.
+	 */
+	notes?: string[];
+	metadata?: Record<string, unknown>;
+	raw?: unknown;
+}
+
+/**
+ * Resolve a limit's used fraction (0..1; >1 means overage) from whichever
+ * amount fields the provider populated. Precedence mirrors the usage UIs:
+ * explicit fraction > used/limit > percent-unit used > inverted remaining.
+ */
+export function resolveUsedFraction(limit: UsageLimit): number | undefined {
+	const amount = limit.amount;
+	if (amount.usedFraction !== undefined) return amount.usedFraction;
+	if (amount.used !== undefined && amount.limit !== undefined && amount.limit > 0) {
+		return amount.used / amount.limit;
+	}
+	if (amount.unit === "percent" && amount.used !== undefined) return amount.used / 100;
+	if (amount.remainingFraction !== undefined) return Math.max(0, 1 - amount.remainingFraction);
+	return undefined;
+}
+
+/**
+ * One recorded usage-limit snapshot: a single limit window of one account at
+ * a point in time. The usage cache itself is latest-snapshot-only; history
+ * rows are appended by the auth storage layer whenever a fresh report is
+ * fetched, so limit utilization stays inspectable over time.
+ */
+export interface UsageHistoryEntry {
+	/** Epoch ms the report was fetched. */
+	recordedAt: number;
+	provider: Provider;
+	/** Stable credential identity key (account/email/project derived). */
+	accountKey: string;
+	email?: string;
+	accountId?: string;
+	/** {@link UsageLimit.id} of the recorded window. */
+	limitId: string;
+	/** Human label of the limit. */
+	label: string;
+	windowLabel?: string;
+	/** Used fraction (0..1) when resolvable. */
+	usedFraction?: number;
+	status?: UsageStatus;
+	/** Epoch ms the window resets, when known. */
+	resetsAt?: number;
+}
+
+/** Filter for reading recorded usage history. */
+export interface UsageHistoryQuery {
+	provider?: string;
+	/** Inclusive lower bound on {@link UsageHistoryEntry.recordedAt} (epoch ms). */
+	sinceMs?: number;
+}
+/** One observed provider request cost, attributed to the credential that made it. */
+export interface UsageCostHistoryEntry {
+	/** Epoch ms the request completed. */
+	recordedAt: number;
+	provider: Provider;
+	/** Stable credential identity key (account/email/project/secret derived). */
+	accountKey: string;
+	/** Estimated request cost in USD. */
+	costUsd: number;
+}
+
+/** Filter for reading observed request costs. */
+export interface UsageCostHistoryQuery {
+	provider?: string;
+	accountKey?: string;
+	/** Inclusive lower bound on {@link UsageCostHistoryEntry.recordedAt} (epoch ms). */
+	sinceMs?: number;
+}
+
+// ─── Zod schemas (wire-shape validation for the broker `/v1/usage` endpoint) ─
+
+export const usageUnitSchema = type("'percent' | 'tokens' | 'requests' | 'usd' | 'minutes' | 'bytes' | 'unknown'");
+export const usageStatusSchema = type("'ok' | 'warning' | 'exhausted' | 'unknown'");
+
+export const usageWindowSchema = type({
+	id: "string",
+	label: "string",
+	"durationMs?": "number",
+	"resetsAt?": "number",
+});
+
+export const usageAmountSchema = type({
+	"used?": "number",
+	"limit?": "number",
+	"remaining?": "number",
+	"usedFraction?": "number",
+	"remainingFraction?": "number",
+	unit: usageUnitSchema,
+});
+
+export const usageScopeSchema = type({
+	provider: "string",
+	"accountId?": "string",
+	"projectId?": "string",
+	"orgId?": "string",
+	"modelId?": "string",
+	"tier?": "string",
+	"windowId?": "string",
+	"shared?": "boolean",
+});
+
+export const usageLimitSchema = type({
+	id: "string",
+	label: "string",
+	scope: usageScopeSchema,
+	"window?": usageWindowSchema,
+	amount: usageAmountSchema,
+	"status?": usageStatusSchema,
+	"notes?": "string[]",
+});
+
+export const usageResetCreditDetailSchema = type({
+	"grantedAt?": "string",
+	"expiresAt?": "string",
+	"status?": "string",
+});
+
+export const usageResetCreditsSchema = type({
+	availableCount: "number",
+	"credits?": usageResetCreditDetailSchema.array(),
+});
+
+export const usageReportSchema = type({
+	provider: "string",
+	fetchedAt: "number",
+	limits: usageLimitSchema.array(),
+	"resetCredits?": usageResetCreditsSchema,
+	"notes?": "string[]",
+	"metadata?": { "[string]": "unknown" },
+	// `raw` is provider-specific and may be anything; the broker strips it before
+	// sending the report over the wire, so accept-but-ignore here.
+	"raw?": "unknown",
+});
+
+/** Optional logger for usage fetchers. */
+export interface UsageLogger {
+	debug(message: string, meta?: Record<string, unknown>): void;
+	warn(message: string, meta?: Record<string, unknown>): void;
+}
+
+/** Credential bundle for usage endpoints. */
+export interface UsageCredential {
+	type: "api_key" | "oauth";
+	apiKey?: string;
+	accessToken?: string;
+	refreshToken?: string;
+	expiresAt?: number;
+	accountId?: string;
+	projectId?: string;
+	email?: string;
+	enterpriseUrl?: string;
+	metadata?: Record<string, unknown>;
+	apiEndpoint?: string;
+}
+
+/** Parameters provided to a usage fetcher. */
+export interface UsageFetchParams {
+	provider: Provider;
+	credential: UsageCredential;
+	/** Stable credential identity key derived by the auth storage layer. */
+	accountKey?: string;
+	baseUrl?: string;
+	signal?: AbortSignal;
+}
+
+/** Shared runtime utilities for fetchers. */
+export interface UsageFetchContext {
+	fetch: FetchImpl;
+	logger?: UsageLogger;
+	retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+	/** Observed request-cost history for providers without upstream usage APIs. */
+	listUsageCosts?: (query?: UsageCostHistoryQuery) => UsageCostHistoryEntry[];
+}
+
+/** Provider implementation for fetching usage information. */
+export interface UsageProvider {
+	id: Provider;
+	fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null>;
+	/** Parse provider rate-limit response headers (lowercased keys) into a usage report, if supported. */
+	parseRateLimitHeaders?(headers: Record<string, string>, now?: number): UsageReport | null;
+	supports?(params: UsageFetchParams): boolean;
+	/** True when fetchUsage contacts upstream and can authenticate the credential for health checks. */
+	validatesCredentials?: boolean;
+}
+
+/** Request context used when ranking usage for a specific model. */
+export interface CredentialRankingContext {
+	/** Provider model id, when the caller is selecting a credential for one model. */
+	modelId?: string;
+}
+
+/** Strategy for usage-based credential ranking. Providers implement this to opt into smart credential selection. */
+export interface CredentialRankingStrategy {
+	/** Extract the primary (short) and secondary (long) window limits from a usage report. */
+	findWindowLimits(
+		report: UsageReport,
+		context?: CredentialRankingContext,
+	): {
+		primary?: UsageLimit;
+		secondary?: UsageLimit;
+	};
+	/**
+	 * Restrict limits to the ones relevant for the requested model before
+	 * credential-wide exhaustion checks and ranking. Providers with shared
+	 * account-wide quotas can omit this and use all limits.
+	 */
+	scopeLimits?(report: UsageReport, context?: CredentialRankingContext): UsageLimit[];
+	/**
+	 * Return a provider-local backoff scope for the requested model. Providers
+	 * with backend-specific quotas use this so one exhausted model family does
+	 * not block unrelated families on the same OAuth credential.
+	 */
+	blockScope?(context?: CredentialRankingContext): string | undefined;
+	/** Fallback window durations (ms) when limits don't specify durationMs. */
+	windowDefaults: {
+		primaryMs: number;
+		secondaryMs: number;
+	};
+	/** Optional: priority boost for specific credential states (e.g., fresh 5h ticker start). */
+	hasPriorityBoost?(primary: UsageLimit | undefined): boolean;
+}