sidekick-shared 0.21.0 → 0.21.2

package/dist/zaiQuota.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZAI_PROVIDER_IDS = exports.ZAI_PROMPT_INVOCATIONS = exports.ZAI_TIER_BUDGETS = void 0;
+exports.isZaiProviderId = isZaiProviderId;
+exports.turnTokenWeight = turnTokenWeight;
+exports.accumulateZaiUsage = accumulateZaiUsage;
+exports.resolveZaiTier = resolveZaiTier;
+exports.inferZaiQuotaState = inferZaiQuotaState;
+exports.parseZaiQuotaError = parseZaiQuotaError;
+exports.extractNextFlushTime = extractNextFlushTime;
+exports.makeUnavailableZaiQuotaState = makeUnavailableZaiQuotaState;
+exports.rowsToZaiTurnsAndErrors = rowsToZaiTurnsAndErrors;
+// ── Tier budgets ──
+/**
+ * Published z.ai coding-plan prompt budgets.
+ *
+ * Source: https://docs.z.ai/devpack/overview & /devpack/faq.
+ * "One prompt ≈ one query; each prompt is estimated to invoke the model
+ * 15–20 times." We use the midpoint (17.5) when converting observed
+ * assistant turns into prompt equivalents.
+ */
+exports.ZAI_TIER_BUDGETS = {
+    lite: { fiveHour: 80, weekly: 400 },
+    pro: { fiveHour: 400, weekly: 2000 },
+    max: { fiveHour: 1600, weekly: 8000 },
+};
+/**
+ * Midpoint of z.ai's documented "15–20 model invocations per prompt" range.
+ * Used to convert accumulated assistant turns into prompt equivalents.
+ * Calibration note: this constant may need per-tier adjustment after
+ * real-world validation against the z.ai web UI.
+ */
+exports.ZAI_PROMPT_INVOCATIONS = 17.5;
+const FIVE_HOUR_MS = 5 * 3_600_000;
+const SEVEN_DAY_MS = 7 * 86_400_000;
+/**
+ * Provider IDs that OpenCode tags on z.ai-routed messages.
+ * `zai-coding-plan` is the Coding Plan key; `zai` is the bare API key.
+ */
+exports.ZAI_PROVIDER_IDS = ['zai', 'zai-coding-plan'];
+function isZaiProviderId(value) {
+    return value === 'zai' || value === 'zai-coding-plan';
+}
+/**
+ * Sums the token fields of a single turn into a scalar.
+ * Cache reads are weighted at 0.1× (Anthropic convention) to avoid
+ * over-counting repeated context. Output and reasoning tokens are weighted 1×.
+ */
+function turnTokenWeight(turn) {
+    return (turn.inputTokens +
+        turn.outputTokens +
+        Math.round(turn.cacheReadTokens * 0.1) +
+        turn.cacheWriteTokens +
+        (turn.reasoningTokens || 0));
+}
+/**
+ * Reduces a stream of z.ai-routed assistant turns into rolling-window usage.
+ *
+ * Pure & stateless: the caller is responsible for passing the relevant turns.
+ * Turns outside the 7-day window are ignored; turns inside the 7-day window
+ * but outside the 5-hour window still count toward weekly usage.
+ */
+function accumulateZaiUsage(turns, nowMs = Date.now()) {
+    const fiveHourCutoff = nowMs - FIVE_HOUR_MS;
+    const weeklyCutoff = nowMs - SEVEN_DAY_MS;
+    let fiveHourTurns = 0;
+    let weeklyTurns = 0;
+    let fiveHourTokens = 0;
+    let weeklyTokens = 0;
+    let fiveHourStartedAtMs = null;
+    let weeklyStartedAtMs = null;
+    for (const turn of turns) {
+        if (turn.timestampMs < weeklyCutoff)
+            continue;
+        weeklyTurns += 1;
+        weeklyTokens += turnTokenWeight(turn);
+        if (weeklyStartedAtMs === null || turn.timestampMs < weeklyStartedAtMs) {
+            weeklyStartedAtMs = turn.timestampMs;
+        }
+        if (turn.timestampMs >= fiveHourCutoff) {
+            fiveHourTurns += 1;
+            fiveHourTokens += turnTokenWeight(turn);
+            if (fiveHourStartedAtMs === null || turn.timestampMs < fiveHourStartedAtMs) {
+                fiveHourStartedAtMs = turn.timestampMs;
+            }
+        }
+    }
+    return {
+        fiveHourTurns,
+        weeklyTurns,
+        fiveHourTokens,
+        weeklyTokens,
+        fiveHourPrompts: fiveHourTurns / exports.ZAI_PROMPT_INVOCATIONS,
+        weeklyPrompts: weeklyTurns / exports.ZAI_PROMPT_INVOCATIONS,
+        fiveHourStartedAtMs,
+        weeklyStartedAtMs,
+    };
+}
+// ── Tier resolution ──
+/**
+ * Resolves the effective z.ai tier when the user has selected `'auto'`.
+ *
+ * Heuristic: if accumulated weekly prompts already exceed a tier's budget,
+ * the user must be on a higher tier. This under-detects at the start of a
+ * weekly cycle (a Max user looks identical to a Lite user until they cross
+ * 400 prompts/week), so callers should still expose an explicit override.
+ */
+function resolveZaiTier(configured, accumulated) {
+    if (configured !== 'auto')
+        return configured;
+    if (accumulated.weeklyPrompts > exports.ZAI_TIER_BUDGETS.pro.weekly)
+        return 'max';
+    if (accumulated.weeklyPrompts > exports.ZAI_TIER_BUDGETS.lite.weekly)
+        return 'pro';
+    return 'lite';
+}
+/**
+ * Converts accumulated usage into a shared `QuotaState`.
+ *
+ * The two windows reuse the `fiveHour` / `sevenDay` field names for cross-
+ * provider compatibility, but are labeled "5-Hour" and "Weekly" via
+ * `fiveHourLabel` / `sevenDayLabel` — mirroring how Codex relabels its
+ * generic primary/secondary windows.
+ *
+ * Reset timestamps are best-effort because z.ai does not expose them:
+ *   - `fiveHour.resetsAt` ← first turn in window + 5h, unless an error
+ *     event supplied an authoritative reset.
+ *   - `sevenDay.resetsAt` ← first turn in window + 7d (documented as
+ *     "7 days from order time" — order time is unknown, so this is a
+ *     lower bound at best).
+ */
+function inferZaiQuotaState(accumulated, tier, options = {}) {
+    const budget = exports.ZAI_TIER_BUDGETS[tier];
+    const capturedAt = options.capturedAt ?? new Date().toISOString();
+    const fiveHourUtil = budget.fiveHour > 0
+        ? Math.min((accumulated.fiveHourPrompts / budget.fiveHour) * 100, 200)
+        : 0;
+    const weeklyUtil = budget.weekly > 0
+        ? Math.min((accumulated.weeklyPrompts / budget.weekly) * 100, 200)
+        : 0;
+    const fiveHourResetsAt = options.authoritativeFiveHourResetAt
+        ?? (accumulated.fiveHourStartedAtMs !== null
+            ? new Date(accumulated.fiveHourStartedAtMs + FIVE_HOUR_MS).toISOString()
+            : '');
+    const sevenDayResetsAt = options.authoritativeWeeklyResetAt
+        ?? (accumulated.weeklyStartedAtMs !== null
+            ? new Date(accumulated.weeklyStartedAtMs + SEVEN_DAY_MS).toISOString()
+            : '');
+    const fiveHour = {
+        utilization: Math.round(fiveHourUtil * 10) / 10,
+        resetsAt: fiveHourResetsAt,
+    };
+    const sevenDay = {
+        utilization: Math.round(weeklyUtil * 10) / 10,
+        resetsAt: sevenDayResetsAt,
+    };
+    const hasAnyData = accumulated.fiveHourTurns > 0 || accumulated.weeklyTurns > 0;
+    return {
+        fiveHour,
+        sevenDay,
+        available: hasAnyData,
+        providerId: 'zai',
+        source: 'session',
+        capturedAt,
+        stale: options.stale ?? !hasAnyData,
+        fiveHourLabel: '5-Hour',
+        sevenDayLabel: 'Weekly',
+        planType: tier,
+        limitId: `zai-${tier}`,
+        limitName: `z.ai ${tier.charAt(0).toUpperCase() + tier.slice(1)}`,
+    };
+}
+/**
+ * z.ai business error codes that signal quota/plan state.
+ * Source: https://docs.z.ai/api-reference/api-code
+ */
+const ZAI_ERROR_CODES = {
+    '1308': 'exhausted', // Usage limit reached for `{number} {unit}` (includes next_flush_time)
+    '1310': 'exhausted', // Weekly/Monthly limit exhausted (resets at next_flush_time)
+    '1313': 'fup', // Fair-Use-Policy violation — request rate restricted
+    '1309': 'expired', // GLM Coding Plan package has expired
+};
+/**
+ * Extracts a z.ai quota error from a message-error payload, if present.
+ *
+ * The reset timestamp is embedded inside the human-readable `message` text
+ * as `${next_flush_time}`. z.ai's docs interpolate the value into the
+ * message string; we parse ISO datetimes, epoch seconds, and the literal
+ * `YYYY-MM-DD HH:mm:ss` form defensively.
+ *
+ * Returns `null` when the code is not a quota-related business error.
+ */
+function parseZaiQuotaError(error) {
+    if (!error)
+        return null;
+    const code = String(error.code ?? '');
+    const kind = ZAI_ERROR_CODES[code];
+    if (!kind)
+        return null;
+    const message = error.message ?? '';
+    const resetsAt = extractNextFlushTime(message);
+    return { kind, resetsAt, code, message };
+}
+/**
+ * Parses `${next_flush_time}` out of a z.ai error message.
+ *
+ * Handles ISO 8601 (`2025-01-31T14:00:00Z`), space-separated
+ * (`2025-01-31 14:00:00`), and epoch-seconds (1234567890) forms.
+ * Returns undefined when no parseable timestamp is found.
+ */
+function extractNextFlushTime(message) {
+    if (!message)
+        return undefined;
+    // ISO 8601 with optional timezone.
+    const isoMatch = message.match(/(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)/);
+    if (isoMatch) {
+        const ms = Date.parse(isoMatch[1]);
+        if (Number.isFinite(ms))
+            return new Date(ms).toISOString();
+    }
+    // `YYYY-MM-DD HH:mm:ss` (no T separator) — z.ai's likely interpolated form.
+    const spaceMatch = message.match(/(\d{4}-\d{2}-\d{2}[ ]\d{2}:\d{2}:\d{2})/);
+    if (spaceMatch) {
+        const normalised = spaceMatch[1].replace(' ', 'T');
+        const ms = Date.parse(`${normalised}Z`);
+        if (Number.isFinite(ms))
+            return new Date(ms).toISOString();
+    }
+    // Epoch seconds — 10-digit integer in a plausible range.
+    const epochMatch = message.match(/(?<!\d)(\d{10})(?!\d)/);
+    if (epochMatch) {
+        const seconds = Number(epochMatch[1]);
+        if (seconds > 1_700_000_000 && seconds < 2_000_000_000) {
+            return new Date(seconds * 1000).toISOString();
+        }
+    }
+    return undefined;
+}
+// ── Unavailable state helper ──
+/**
+ * Builds an unavailable z.ai `QuotaState` for the cold-start case where
+ * no z.ai traffic has been observed yet.
+ */
+function makeUnavailableZaiQuotaState(error = 'No z.ai usage observed yet', tier = 'lite', capturedAt = new Date().toISOString()) {
+    return {
+        fiveHour: { utilization: 0, resetsAt: '' },
+        sevenDay: { utilization: 0, resetsAt: '' },
+        available: false,
+        error,
+        providerId: 'zai',
+        source: 'session',
+        capturedAt,
+        stale: true,
+        fiveHourLabel: '5-Hour',
+        sevenDayLabel: 'Weekly',
+        planType: tier,
+    };
+}
+/**
+ * Converts raw OpenCode DB rows (filtered to z.ai providerIDs by the caller)
+ * into the watcher's `ZaiAssistantTurn` shape, and surfaces any trapped
+ * business errors.
+ *
+ * Returns `{ turns, errors }` so callers can replay them through
+ * `ZaiQuotaWatcher.ingestAssistantTurns` and `ingestError`.
+ */
+function rowsToZaiTurnsAndErrors(rows) {
+    const turns = [];
+    const errors = [];
+    for (const row of rows) {
+        turns.push({
+            timestampMs: row.timeCreated,
+            model: row.modelId,
+            inputTokens: row.inputTokens || 0,
+            outputTokens: row.outputTokens || 0,
+            cacheReadTokens: row.cacheReadTokens || 0,
+            cacheWriteTokens: row.cacheWriteTokens || 0,
+            reasoningTokens: row.reasoningTokens || 0,
+        });
+        if (row.errorCode != null || row.errorMessage) {
+            const parsed = parseZaiQuotaError({
+                code: row.errorCode ?? undefined,
+                message: row.errorMessage ?? undefined,
+            });
+            if (parsed)
+                errors.push(parsed);
+        }
+    }
+    return { turns, errors };
+}

package/dist/zaiQuotaApi.d.ts

@@ -0,0 +1,33 @@
+import type { QuotaState } from './quota';
+import type { ProviderQuotaState } from './providerQuota';
+type ZaiSnapshotProvider = 'zai';
+type SnapshotReader = (providerId: ZaiSnapshotProvider, accountId: string) => QuotaState | null;
+type SnapshotWriter = (providerId: ZaiSnapshotProvider, accountId: string, quota: QuotaState) => void;
+export type ZaiPlatform = 'ZAI' | 'ZHIPU';
+export type ZaiCredentialSource = 'opencode' | 'env';
+export interface ZaiCredentials {
+    authToken: string;
+    baseUrl: string;
+    platform: ZaiPlatform;
+    source: ZaiCredentialSource;
+}
+export interface ReadZaiCredentialsOptions {
+    openCodeDataDir?: string;
+    env?: Record<string, string | undefined>;
+}
+export interface ZaiQuotaApiOptions extends ReadZaiCredentialsOptions {
+    credentials?: ZaiCredentials | null;
+    fetchImpl?: typeof fetch;
+    capturedAt?: string;
+    timeoutMs?: number;
+}
+export interface ZaiQuotaResolveOptions extends ZaiQuotaApiOptions {
+    accountId?: string;
+    readSnapshot?: SnapshotReader;
+    writeSnapshot?: SnapshotWriter;
+}
+export declare function readZaiCredentials(options?: ReadZaiCredentialsOptions): ZaiCredentials | null;
+export declare function quotaStateFromZaiQuotaLimitPayload(payload: unknown, capturedAt?: string): QuotaState;
+export declare function fetchZaiQuotaFromApi(options?: ZaiQuotaApiOptions): Promise<QuotaState>;
+export declare function resolveZaiQuota(options?: ZaiQuotaResolveOptions): Promise<ProviderQuotaState<'zai'>>;
+export {};

package/dist/zaiQuotaApi.js

@@ -0,0 +1,271 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readZaiCredentials = readZaiCredentials;
+exports.quotaStateFromZaiQuotaLimitPayload = quotaStateFromZaiQuotaLimitPayload;
+exports.fetchZaiQuotaFromApi = fetchZaiQuotaFromApi;
+exports.resolveZaiQuota = resolveZaiQuota;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const quotaSnapshots_1 = require("./quotaSnapshots");
+const DEFAULT_ZAI_BASE_URL = 'https://api.z.ai/api/anthropic';
+const QUOTA_PATH = '/api/monitor/usage/quota/limit';
+const DEFAULT_ACCOUNT_ID = 'default';
+const DEFAULT_TIMEOUT_MS = 10_000;
+function unavailableZaiQuotaState(error, meta = {}, capturedAt = new Date().toISOString()) {
+    return {
+        fiveHour: { utilization: 0, resetsAt: '' },
+        sevenDay: { utilization: 0, resetsAt: '' },
+        available: false,
+        error,
+        providerId: 'zai',
+        source: 'api',
+        capturedAt,
+        fiveHourLabel: '5-Hour',
+        sevenDayLabel: 'Weekly',
+        ...meta,
+    };
+}
+function openCodeDataDirCandidates() {
+    const candidates = [];
+    const xdg = process.env.XDG_DATA_HOME;
+    if (xdg)
+        candidates.push(path_1.default.join(xdg, 'opencode'));
+    candidates.push(path_1.default.join(os_1.default.homedir(), '.local', 'share', 'opencode'));
+    if (process.platform === 'darwin') {
+        candidates.push(path_1.default.join(os_1.default.homedir(), 'Library', 'Application Support', 'opencode'));
+    }
+    else if (process.platform === 'win32') {
+        candidates.push(path_1.default.join(process.env.LOCALAPPDATA || process.env.APPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Local'), 'opencode'));
+    }
+    return Array.from(new Set(candidates));
+}
+function readOpenCodeAuthToken(openCodeDataDir) {
+    const candidates = openCodeDataDir ? [openCodeDataDir] : openCodeDataDirCandidates();
+    for (const dataDir of candidates) {
+        try {
+            const parsed = JSON.parse(fs_1.default.readFileSync(path_1.default.join(dataDir, 'auth.json'), 'utf8'));
+            const codingPlan = parsed['zai-coding-plan'];
+            const zai = parsed.zai;
+            if (typeof codingPlan?.key === 'string' && codingPlan.key.trim())
+                return codingPlan.key.trim();
+            if (typeof zai?.key === 'string' && zai.key.trim())
+                return zai.key.trim();
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return null;
+}
+function platformFromBaseUrl(baseUrl) {
+    if (baseUrl.includes('api.z.ai'))
+        return 'ZAI';
+    if (baseUrl.includes('open.bigmodel.cn') || baseUrl.includes('dev.bigmodel.cn'))
+        return 'ZHIPU';
+    return null;
+}
+function readZaiCredentials(options = {}) {
+    const openCodeToken = readOpenCodeAuthToken(options.openCodeDataDir);
+    if (openCodeToken) {
+        return {
+            authToken: openCodeToken,
+            baseUrl: DEFAULT_ZAI_BASE_URL,
+            platform: 'ZAI',
+            source: 'opencode',
+        };
+    }
+    const env = options.env ?? process.env;
+    const authToken = env.ANTHROPIC_AUTH_TOKEN?.trim();
+    const baseUrl = env.ANTHROPIC_BASE_URL?.trim();
+    if (!authToken || !baseUrl)
+        return null;
+    const platform = platformFromBaseUrl(baseUrl);
+    if (!platform)
+        return null;
+    return {
+        authToken,
+        baseUrl,
+        platform,
+        source: 'env',
+    };
+}
+function quotaLimitUrl(baseUrl) {
+    try {
+        const parsed = new URL(baseUrl);
+        return `${parsed.protocol}//${parsed.host}${QUOTA_PATH}`;
+    }
+    catch {
+        return null;
+    }
+}
+function tokenLimitEntries(payload) {
+    const limits = payload.data?.limits ?? payload.limits ?? [];
+    return limits.filter((item) => item?.type === 'TOKENS_LIMIT' && typeof item.percentage === 'number');
+}
+function isFiveHourLimit(item) {
+    return item.type === 'TOKENS_LIMIT' && item.unit === 3 && item.number === 5;
+}
+function isWeeklyLimit(item) {
+    return item.type === 'TOKENS_LIMIT' && item.unit === 6 && item.number === 1;
+}
+function isoFromEpochMs(value) {
+    if (value == null)
+        return '';
+    const ms = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(ms) || ms <= 0)
+        return '';
+    return new Date(ms).toISOString();
+}
+function displayPlanName(level) {
+    if (!level)
+        return 'z.ai Coding Plan';
+    return `z.ai ${level.charAt(0).toUpperCase()}${level.slice(1)}`;
+}
+function quotaStateFromZaiQuotaLimitPayload(payload, capturedAt = new Date().toISOString()) {
+    const data = payload;
+    const tokenLimits = tokenLimitEntries(data);
+    const fiveHourLimit = tokenLimits.find(isFiveHourLimit) ?? tokenLimits[0];
+    const weeklyLimit = tokenLimits.find(isWeeklyLimit) ?? tokenLimits.find(item => item !== fiveHourLimit);
+    const level = data.data?.level;
+    if (!fiveHourLimit || !weeklyLimit) {
+        return unavailableZaiQuotaState('z.ai quota API returned no token quota windows.', {
+            failureKind: 'unknown',
+        }, capturedAt);
+    }
+    return {
+        fiveHour: {
+            utilization: fiveHourLimit.percentage ?? 0,
+            resetsAt: isoFromEpochMs(fiveHourLimit.nextResetTime),
+        },
+        sevenDay: {
+            utilization: weeklyLimit.percentage ?? 0,
+            resetsAt: isoFromEpochMs(weeklyLimit.nextResetTime),
+        },
+        available: true,
+        providerId: 'zai',
+        source: 'api',
+        capturedAt,
+        fiveHourLabel: '5-Hour',
+        sevenDayLabel: 'Weekly',
+        planType: level,
+        limitId: level ? `zai-${level}` : 'zai-coding-plan',
+        limitName: displayPlanName(level),
+    };
+}
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const dateMs = Date.parse(retryAfter);
+    if (Number.isFinite(dateMs))
+        return Math.max(0, dateMs - Date.now());
+    return undefined;
+}
+function failureKindForStatus(status) {
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 429)
+        return 'rate_limit';
+    if (status >= 500)
+        return 'server';
+    return 'unknown';
+}
+function sanitizeErrorMessage(message, authToken) {
+    let result = message;
+    if (authToken) {
+        result = result.split(authToken).join('<redacted>');
+    }
+    return result.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, 'Bearer <redacted>');
+}
+async function fetchZaiQuotaFromApi(options = {}) {
+    const capturedAt = options.capturedAt ?? new Date().toISOString();
+    const credentials = options.credentials ?? readZaiCredentials(options);
+    if (!credentials) {
+        return unavailableZaiQuotaState('No z.ai credentials found. Sign in to OpenCode with z.ai or set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN.', { failureKind: 'auth' }, capturedAt);
+    }
+    const url = quotaLimitUrl(credentials.baseUrl);
+    if (!url) {
+        return unavailableZaiQuotaState('Invalid z.ai base URL.', { failureKind: 'unknown' }, capturedAt);
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+        const response = await fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                Authorization: credentials.authToken,
+                'Accept-Language': 'en-US,en',
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        const body = await response.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!response.ok) {
+            const failureKind = failureKindForStatus(response.status);
+            const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+            const detail = parsed && typeof parsed === 'object' && 'msg' in parsed
+                ? String(parsed.msg ?? '')
+                : '';
+            const baseMessage = failureKind === 'auth'
+                ? `z.ai quota API rejected credentials (HTTP ${response.status}).`
+                : `z.ai quota API error (HTTP ${response.status}).`;
+            return unavailableZaiQuotaState(sanitizeErrorMessage([baseMessage, detail].filter(Boolean).join(' '), credentials.authToken), { failureKind, httpStatus: response.status, retryAfterMs }, capturedAt);
+        }
+        return quotaStateFromZaiQuotaLimitPayload(parsed, capturedAt);
+    }
+    catch (error) {
+        const isAbort = error instanceof Error && error.name === 'AbortError';
+        return unavailableZaiQuotaState(isAbort ? 'z.ai quota API timed out.' : 'z.ai quota API network error.', { failureKind: 'network' }, capturedAt);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function enrichZaiQuota(state) {
+    return {
+        ...state,
+        runtimeProvider: 'zai',
+        providerId: 'zai',
+        fiveHourLabel: state.fiveHourLabel ?? '5-Hour',
+        sevenDayLabel: state.sevenDayLabel ?? 'Weekly',
+    };
+}
+async function resolveZaiQuota(options = {}) {
+    const accountId = options.accountId ?? DEFAULT_ACCOUNT_ID;
+    const readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
+    const writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
+    const apiQuota = await fetchZaiQuotaFromApi(options);
+    if (apiQuota.available) {
+        writeSnapshot('zai', accountId, apiQuota);
+        return enrichZaiQuota(apiQuota);
+    }
+    const cached = readSnapshot('zai', accountId);
+    if (cached) {
+        return enrichZaiQuota({
+            ...cached,
+            providerId: 'zai',
+            source: 'cache',
+            stale: true,
+            fiveHourLabel: cached.fiveHourLabel ?? '5-Hour',
+            sevenDayLabel: cached.sevenDayLabel ?? 'Weekly',
+        });
+    }
+    return enrichZaiQuota(apiQuota);
+}

package/dist/zaiQuotaWatcher.d.ts

@@ -0,0 +1,97 @@
+import type { QuotaHistorySample } from './quotaHistory';
+import { type ZaiAccumulatedUsage, type ZaiAssistantTurn, type ZaiTier } from './zaiQuota';
+import type { QuotaState } from './quota';
+import type { ProviderQuotaState } from './providerQuota';
+import type { Disposable } from './quotaPoller';
+/** Storage key wider than `AccountProviderId` — z.ai has no full account
+ * management in v1, but we still need a stable key for snapshot/history. */
+type ZaiSnapshotProvider = 'zai';
+type TierResolver = (configured: ZaiTier | 'auto', accumulated: ZaiAccumulatedUsage) => ZaiTier;
+type SnapshotReader = (providerId: ZaiSnapshotProvider, accountId: string) => QuotaState | null;
+type SnapshotWriter = (providerId: ZaiSnapshotProvider, accountId: string, quota: QuotaState) => void;
+type HistoryAppender = (sample: QuotaHistorySample) => void | Promise<void>;
+export interface ZaiQuotaWatcherOptions {
+    /** Configured tier. Default: `'auto'` (heuristic from observed usage). */
+    tier?: ZaiTier | 'auto';
+    /** Override tier resolution (used by tests). Default: `resolveZaiTier`. */
+    resolveTier?: TierResolver;
+    /** Override snapshot read (used by tests). */
+    readSnapshot?: SnapshotReader;
+    /** Override snapshot write (used by tests). */
+    writeSnapshot?: SnapshotWriter;
+    /** Override history append (used by tests). */
+    appendHistorySample?: HistoryAppender;
+    /** Stable workspace identifier — when provided, samples are appended to per-workspace history. */
+    workspaceId?: string;
+    /** Account identifier for snapshot persistence. Default: `'default'`. */
+    accountId?: string;
+    /** Minimum time between recomputes (ms). Default: 1000. */
+    recomputeDebounceMs?: number;
+    /** Time between prunes of in-memory turn buffer (ms). Default: 60000. */
+    pruneIntervalMs?: number;
+    /** Internal clock for tests. */
+    now?: () => number;
+}
+/**
+ * Watches z.ai-routed OpenCode activity and emits derived `QuotaState`.
+ *
+ * The watcher is event-driven (not a poller): call `ingestAssistantTurn`
+ * for every observed z.ai assistant turn, and `ingestError` whenever a
+ * z.ai business error is observed. The watcher debounces recompute and
+ * emits via `onUpdate` / `onQuotaUpdate`.
+ */
+export declare class ZaiQuotaWatcher implements Disposable {
+    private readonly tier;
+    private readonly resolveTier;
+    private readonly readSnapshot;
+    private readonly writeSnapshot;
+    private readonly appendHistorySample;
+    private readonly workspaceId;
+    private readonly accountId;
+    private readonly recomputeDebounceMs;
+    private readonly pruneIntervalMs;
+    private readonly now;
+    private readonly listeners;
+    /** In-memory rolling 7-day buffer of observed turns. */
+    private turns;
+    /** Most recent authoritative 5h reset (parsed from a z.ai error event). */
+    private authoritativeFiveHourResetAt;
+    /** Most recent authoritative weekly reset (parsed from a z.ai error event). */
+    private authoritativeWeeklyResetAt;
+    /** Most recent trapped error (so consumers can show "rate-limited until X"). */
+    private lastError;
+    private lastEmissionKey;
+    private pendingRecomputeTimer;
+    private pruneTimer;
+    private running;
+    constructor(options?: ZaiQuotaWatcherOptions);
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    onUpdate(cb: (state: ProviderQuotaState<'zai'>) => void): Disposable;
+    onQuotaUpdate(cb: (state: ProviderQuotaState<'zai'>) => void): Disposable;
+    /** Feed an observed z.ai assistant turn. Schedules a debounced recompute. */
+    ingestAssistantTurn(turn: ZaiAssistantTurn): void;
+    /**
+     * Feed multiple turns at once (used for cold-start seeding from the DB).
+     * Schedules a single debounced recompute.
+     */
+    ingestAssistantTurns(turns: readonly ZaiAssistantTurn[]): void;
+    /** Feed a z.ai error event. Triggers an immediate recompute + emit. */
+    ingestError(error: {
+        code?: string | number;
+        message?: string;
+        type?: string;
+    }): boolean;
+    /** Force a recompute+emit now (skipping the debounce). Used by tests. */
+    refresh(): void;
+    /** Current in-memory turn count (testing/diagnostics). */
+    get bufferedTurnCount(): number;
+    private scheduleRecompute;
+    private recomputeAndEmit;
+    private maybeAppendHistory;
+    private emitCachedOrUnavailable;
+    private emitState;
+    private pruneOldTurns;
+}
+export {};