@gajae-code/ai 0.1.1

package/src/usage/zai.ts

@@ -0,0 +1,247 @@
+import type {
+	UsageAmount,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+	UsageStatus,
+	UsageWindow,
+} from "../usage";
+import { isRecord, toNumber } 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;
+
+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;
+}
+
+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 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),
+	};
+}
+
+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 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: UsageWindow = {
+				id: "quota",
+				label: "Quota",
+				durationMs: SEVEN_DAYS_MS,
+				resetsAt: parsed.nextResetTime,
+			};
+			limits.push({
+				id: "zai:tokens",
+				label: "ZAI Token Quota",
+				scope: {
+					provider: params.provider,
+					windowId: window?.id ?? "quota",
+					shared: true,
+				},
+				window,
+				amount,
+				status: getUsageStatus(amount.usedFraction),
+			});
+		}
+		if (parsed.type === "TIME_LIMIT") {
+			const window: UsageWindow = {
+				id: "quota",
+				label: "Quota",
+				durationMs: SEVEN_DAYS_MS,
+				resetsAt: parsed.nextResetTime,
+			};
+			const amount = buildUsageAmount({
+				used: parsed.currentValue,
+				limit: parsed.usage,
+				remaining: parsed.remaining,
+				percentage: parsed.percentage,
+				unit: "requests",
+			});
+			limits.push({
+				id: "zai:requests",
+				label: "ZAI Request Quota",
+				scope: {
+					provider: params.provider,
+					windowId: "quota",
+					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,183 @@
+/**
+ * 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 * as z from "zod/v4";
+import type { 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[];
+}
+
+/** Aggregated usage report for a provider. */
+export interface UsageReport {
+	provider: Provider;
+	fetchedAt: number;
+	limits: UsageLimit[];
+	metadata?: Record<string, unknown>;
+	raw?: unknown;
+}
+
+// ─── Zod schemas (wire-shape validation for the broker `/v1/usage` endpoint) ─
+
+export const usageUnitSchema = z.enum(["percent", "tokens", "requests", "usd", "minutes", "bytes", "unknown"]);
+export const usageStatusSchema = z.enum(["ok", "warning", "exhausted", "unknown"]);
+
+export const usageWindowSchema = z.object({
+	id: z.string(),
+	label: z.string(),
+	durationMs: z.number().optional(),
+	resetsAt: z.number().optional(),
+});
+
+export const usageAmountSchema = z.object({
+	used: z.number().optional(),
+	limit: z.number().optional(),
+	remaining: z.number().optional(),
+	usedFraction: z.number().optional(),
+	remainingFraction: z.number().optional(),
+	unit: usageUnitSchema,
+});
+
+export const usageScopeSchema = z.object({
+	provider: z.string(),
+	accountId: z.string().optional(),
+	projectId: z.string().optional(),
+	orgId: z.string().optional(),
+	modelId: z.string().optional(),
+	tier: z.string().optional(),
+	windowId: z.string().optional(),
+	shared: z.boolean().optional(),
+});
+
+export const usageLimitSchema = z.object({
+	id: z.string(),
+	label: z.string(),
+	scope: usageScopeSchema,
+	window: usageWindowSchema.optional(),
+	amount: usageAmountSchema,
+	status: usageStatusSchema.optional(),
+	notes: z.array(z.string()).optional(),
+});
+
+export const usageReportSchema = z.object({
+	provider: z.string(),
+	fetchedAt: z.number(),
+	limits: z.array(usageLimitSchema),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	// `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: z.unknown().optional(),
+});
+
+/** 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>;
+}
+
+/** Parameters provided to a usage fetcher. */
+export interface UsageFetchParams {
+	provider: Provider;
+	credential: UsageCredential;
+	baseUrl?: string;
+	signal?: AbortSignal;
+}
+
+/** Shared runtime utilities for fetchers. */
+export interface UsageFetchContext {
+	fetch: typeof fetch;
+	logger?: UsageLogger;
+	retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/** Provider implementation for fetching usage information. */
+export interface UsageProvider {
+	id: Provider;
+	fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null>;
+	supports?(params: UsageFetchParams): boolean;
+}
+
+/** 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): {
+		primary?: UsageLimit;
+		secondary?: UsageLimit;
+	};
+	/** 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;
+}

package/src/utils/abort.ts

@@ -0,0 +1,51 @@
+export interface AbortSourceTracker {
+	requestAbortController: AbortController;
+	requestSignal: AbortSignal;
+	abortLocally(reason: Error): Error;
+	getLocalAbortReason(): Error | undefined;
+	wasCallerAbort(): boolean;
+}
+
+/**
+ * Tracks whether a merged request signal was aborted by the caller or by provider-local logic.
+ *
+ * Caller aborts always take priority. When both the caller and a local watchdog fire near
+ * each other, the merged `requestSignal.reason` reflects whichever AbortController called
+ * `.abort()` first — but ordering is racy and not meaningful for upstream consumers. What
+ * matters is intent: if the caller's signal aborted, the request was cancelled by the
+ * caller, and any local watchdog reason is incidental and **MUST NOT** be surfaced as a
+ * retryable transient error (which would cause auto-retry to re-enter streaming and leave
+ * the UI showing a spinner the user already tried to cancel).
+ */
+export function createAbortSourceTracker(callerSignal?: AbortSignal): AbortSourceTracker {
+	const requestAbortController = new AbortController();
+	const requestSignal = callerSignal
+		? AbortSignal.any([callerSignal, requestAbortController.signal])
+		: requestAbortController.signal;
+	let localAbortReason: Error | undefined;
+
+	return {
+		requestAbortController,
+		requestSignal,
+		abortLocally(reason) {
+			localAbortReason = reason;
+			requestAbortController.abort(reason);
+			return reason;
+		},
+		getLocalAbortReason() {
+			// Caller intent dominates. Surface a local reason only when the caller did not
+			// abort, so timeout/idle-watchdog errors don't masquerade as the user's cancel.
+			if (!localAbortReason || callerSignal?.aborted) return undefined;
+			return requestSignal.reason === localAbortReason ? localAbortReason : undefined;
+		},
+		wasCallerAbort() {
+			// If the caller signal aborted, treat it as a caller abort regardless of which
+			// AbortController won the race to set `requestSignal.reason`. The previous
+			// `requestSignal.reason !== localAbortReason` heuristic flipped the result to
+			// `false` when a local watchdog fired microseconds before the user's ESC, which
+			// then routed user-initiated cancels through the auto-retry transient-error
+			// path.
+			return callerSignal?.aborted === true;
+		},
+	};
+}

package/src/utils/anthropic-auth.ts

@@ -0,0 +1,87 @@
+/**
+ * Anthropic Authentication
+ *
+ * Thin helper for turning an already-resolved API key into the request-shaping
+ * config consumed by {@link buildAnthropicSearchHeaders} / {@link buildAnthropicUrl}.
+ *
+ * Credential storage and refresh live in `AuthStorage` — call
+ * `authStorage.getApiKey("anthropic", sessionId)` first, then pass the result
+ * through {@link buildAnthropicAuthConfig} for header/URL shaping.
+ */
+import { $env } from "@gajae-code/utils";
+import {
+	buildAnthropicHeaders as buildProviderAnthropicHeaders,
+	normalizeAnthropicBaseUrl,
+} from "../providers/anthropic";
+import { isFoundryEnabled } from "./foundry";
+
+/** Auth configuration for Anthropic */
+export interface AnthropicAuthConfig {
+	apiKey: string;
+	baseUrl: string;
+	isOAuth: boolean;
+}
+
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+
+function normalizeBaseUrl(baseUrl: string | undefined): string | undefined {
+	const trimmed = baseUrl?.trim();
+	return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
+}
+
+export function resolveAnthropicBaseUrlFromEnv(): string | undefined {
+	if (isFoundryEnabled()) {
+		const foundryBaseUrl = normalizeBaseUrl($env.FOUNDRY_BASE_URL);
+		if (foundryBaseUrl) return foundryBaseUrl;
+	}
+	const anthropicBaseUrl = normalizeBaseUrl($env.ANTHROPIC_BASE_URL);
+	return anthropicBaseUrl || undefined;
+}
+
+/**
+ * Checks if a token is an OAuth token by looking for sk-ant-oat prefix.
+ */
+export function isOAuthToken(apiKey: string): boolean {
+	return apiKey.includes("sk-ant-oat");
+}
+
+/**
+ * Build an {@link AnthropicAuthConfig} from an already-resolved API key.
+ *
+ * `apiKey` is whatever the caller chose for `Authorization`/`x-api-key` —
+ * usually `authStorage.getApiKey("anthropic")`. `baseUrl` overrides the
+ * env-derived base; pass `undefined` to fall back to FOUNDRY/ANTHROPIC env
+ * resolution and finally `DEFAULT_BASE_URL`.
+ *
+ * `isOAuth` is derived from the token prefix so the helper stays pure: callers
+ * never have to thread the OAuth flag through their own resolution logic.
+ */
+export function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig {
+	return {
+		apiKey,
+		baseUrl: normalizeBaseUrl(baseUrl) ?? resolveAnthropicBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
+		isOAuth: isOAuthToken(apiKey),
+	};
+}
+
+/**
+ * Builds HTTP headers for Anthropic API requests (search variant).
+ */
+export function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string> {
+	return buildProviderAnthropicHeaders({
+		apiKey: auth.apiKey,
+		baseUrl: auth.baseUrl,
+		isOAuth: auth.isOAuth,
+		extraBetas: ["web-search-2025-03-05"],
+		stream: false,
+	});
+}
+
+/**
+ * Builds the full API URL for Anthropic messages endpoint.
+ */
+export function buildAnthropicUrl(auth: AnthropicAuthConfig): string {
+	const normalizedBaseUrl = normalizeAnthropicBaseUrl(auth.baseUrl);
+	const base = `${normalizedBaseUrl}/v1/messages`;
+	return `${base}?beta=true`;
+}