sidekick-shared 0.21.0 → 0.21.1

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/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 {};

package/dist/zaiQuotaWatcher.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZaiQuotaWatcher = void 0;
+/**
+ * Event-driven watcher that derives a z.ai coding-plan `QuotaState` from
+ * observed OpenCode assistant turns.
+ *
+ * z.ai does not expose a quota API, so this watcher maintains rolling
+ * 5-hour / 7-day windows in memory and recomputes an estimated `QuotaState`
+ * whenever a new turn arrives. The consumer is responsible for feeding it
+ * z.ai-routed assistant turns (and any trapped error events) — typically
+ * by subscribing to `SessionMonitor.onSessionEvent` and filtering on
+ * `providerID ∈ {zai, zai-coding-plan}`.
+ *
+ * Optionally writes snapshots + history samples for cross-session cache
+ * and trend visualisation, mirroring `CodexQuotaWatcher`.
+ */
+const quotaHistory_1 = require("./quotaHistory");
+const quotaSnapshots_1 = require("./quotaSnapshots");
+const zaiQuota_1 = require("./zaiQuota");
+const DEFAULT_ACCOUNT_ID = 'default';
+const DEFAULT_RECOMPUTE_DEBOUNCE_MS = 1_000;
+const DEFAULT_PRUNE_INTERVAL_MS = 60_000;
+const SEVEN_DAY_MS = 7 * 86_400_000;
+function enrichZaiState(state) {
+    return {
+        ...state,
+        runtimeProvider: 'zai',
+        providerId: 'zai',
+    };
+}
+/**
+ * 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`.
+ */
+class ZaiQuotaWatcher {
+    tier;
+    resolveTier;
+    readSnapshot;
+    writeSnapshot;
+    appendHistorySample;
+    workspaceId;
+    accountId;
+    recomputeDebounceMs;
+    pruneIntervalMs;
+    now;
+    listeners = [];
+    /** In-memory rolling 7-day buffer of observed turns. */
+    turns = [];
+    /** Most recent authoritative 5h reset (parsed from a z.ai error event). */
+    authoritativeFiveHourResetAt;
+    /** Most recent authoritative weekly reset (parsed from a z.ai error event). */
+    authoritativeWeeklyResetAt;
+    /** Most recent trapped error (so consumers can show "rate-limited until X"). */
+    lastError = null;
+    lastEmissionKey = null;
+    pendingRecomputeTimer;
+    pruneTimer;
+    running = false;
+    constructor(options = {}) {
+        this.tier = options.tier ?? 'auto';
+        this.resolveTier = options.resolveTier ?? zaiQuota_1.resolveZaiTier;
+        this.readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
+        this.writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
+        this.appendHistorySample = options.appendHistorySample ?? quotaHistory_1.appendQuotaHistorySample;
+        this.workspaceId = options.workspaceId;
+        this.accountId = options.accountId ?? DEFAULT_ACCOUNT_ID;
+        this.recomputeDebounceMs = options.recomputeDebounceMs ?? DEFAULT_RECOMPUTE_DEBOUNCE_MS;
+        this.pruneIntervalMs = options.pruneIntervalMs ?? DEFAULT_PRUNE_INTERVAL_MS;
+        this.now = options.now ?? Date.now;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Emit cached state immediately so consumers don't show "unavailable"
+        // during the gap before the first z.ai turn arrives.
+        this.emitCachedOrUnavailable();
+        this.pruneTimer = setInterval(() => this.pruneOldTurns(), this.pruneIntervalMs);
+    }
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.pendingRecomputeTimer) {
+            clearTimeout(this.pendingRecomputeTimer);
+            this.pendingRecomputeTimer = undefined;
+        }
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = undefined;
+        }
+    }
+    dispose() {
+        this.stop();
+        this.listeners.splice(0, this.listeners.length);
+    }
+    onUpdate(cb) {
+        this.listeners.push(cb);
+        return {
+            dispose: () => {
+                const index = this.listeners.indexOf(cb);
+                if (index >= 0)
+                    this.listeners.splice(index, 1);
+            },
+        };
+    }
+    onQuotaUpdate(cb) {
+        return this.onUpdate(cb);
+    }
+    /** Feed an observed z.ai assistant turn. Schedules a debounced recompute. */
+    ingestAssistantTurn(turn) {
+        this.turns.push(turn);
+        this.scheduleRecompute();
+    }
+    /**
+     * Feed multiple turns at once (used for cold-start seeding from the DB).
+     * Schedules a single debounced recompute.
+     */
+    ingestAssistantTurns(turns) {
+        for (const turn of turns)
+            this.turns.push(turn);
+        this.scheduleRecompute();
+    }
+    /** Feed a z.ai error event. Triggers an immediate recompute + emit. */
+    ingestError(error) {
+        const parsed = (0, zaiQuota_1.parseZaiQuotaError)(error);
+        if (!parsed)
+            return false;
+        this.lastError = parsed;
+        if (parsed.resetsAt) {
+            // The first observed error after the user crosses a threshold tells
+            // us the authoritative window boundary. Apply to whichever window
+            // the kind maps to.
+            if (parsed.kind === 'exhausted') {
+                this.authoritativeFiveHourResetAt = parsed.resetsAt;
+                // 1310 is "weekly/monthly exhausted" — also pin the weekly window.
+                if (String(parsed.code) === '1310') {
+                    this.authoritativeWeeklyResetAt = parsed.resetsAt;
+                }
+            }
+        }
+        this.scheduleRecompute();
+        return true;
+    }
+    /** Force a recompute+emit now (skipping the debounce). Used by tests. */
+    refresh() {
+        this.recomputeAndEmit();
+    }
+    /** Current in-memory turn count (testing/diagnostics). */
+    get bufferedTurnCount() {
+        return this.turns.length;
+    }
+    // ── internals ──
+    scheduleRecompute() {
+        if (!this.running)
+            return;
+        if (this.pendingRecomputeTimer)
+            clearTimeout(this.pendingRecomputeTimer);
+        this.pendingRecomputeTimer = setTimeout(() => {
+            this.pendingRecomputeTimer = undefined;
+            this.recomputeAndEmit();
+        }, this.recomputeDebounceMs);
+    }
+    recomputeAndEmit() {
+        const nowMs = this.now();
+        const accumulated = (0, zaiQuota_1.accumulateZaiUsage)(this.turns, nowMs);
+        const tier = this.resolveTier(this.tier, accumulated);
+        const state = accumulated.fiveHourTurns > 0 || accumulated.weeklyTurns > 0
+            ? (0, zaiQuota_1.inferZaiQuotaState)(accumulated, tier, {
+                capturedAt: new Date(nowMs).toISOString(),
+                stale: false,
+                authoritativeFiveHourResetAt: this.authoritativeFiveHourResetAt,
+                authoritativeWeeklyResetAt: this.authoritativeWeeklyResetAt,
+            })
+            : (0, zaiQuota_1.makeUnavailableZaiQuotaState)(undefined, tier, new Date(nowMs).toISOString());
+        // If we recently saw an error, override availability so the UI shows it.
+        if (this.lastError) {
+            state.error = this.lastError.message;
+            state.failureKind = this.lastError.kind === 'expired' ? 'auth' : 'rate_limit';
+            state.rateLimitReachedType = this.lastError.kind;
+        }
+        this.writeSnapshot('zai', this.accountId, state);
+        this.maybeAppendHistory(state);
+        this.emitState(enrichZaiState(state));
+    }
+    maybeAppendHistory(state) {
+        if (!this.workspaceId)
+            return;
+        const sample = {
+            timestamp: state.capturedAt ?? new Date(this.now()).toISOString(),
+            runtimeProvider: 'zai',
+            providerId: this.accountId,
+            workspaceId: this.workspaceId,
+            fiveHour: { utilization: state.fiveHour.utilization, resetsAt: state.fiveHour.resetsAt },
+            sevenDay: { utilization: state.sevenDay.utilization, resetsAt: state.sevenDay.resetsAt },
+            available: state.available,
+            error: state.error,
+            source: 'session',
+            stale: state.stale,
+        };
+        try {
+            const result = this.appendHistorySample(sample);
+            if (result && typeof result.catch === 'function') {
+                result.catch(() => {
+                    // History append must never break the live emission path.
+                });
+            }
+        }
+        catch {
+            // Synchronous errors swallowed for the same reason.
+        }
+    }
+    emitCachedOrUnavailable() {
+        const cached = this.readSnapshot('zai', this.accountId);
+        if (cached) {
+            this.emitState(enrichZaiState({
+                ...cached,
+                providerId: 'zai',
+                source: 'cache',
+                stale: true,
+                fiveHourLabel: cached.fiveHourLabel ?? '5-Hour',
+                sevenDayLabel: cached.sevenDayLabel ?? 'Weekly',
+            }));
+            return;
+        }
+        // Initial state with no observations yet.
+        const tier = this.tier === 'auto' ? 'lite' : this.tier;
+        this.emitState(enrichZaiState((0, zaiQuota_1.makeUnavailableZaiQuotaState)(undefined, tier)));
+    }
+    emitState(state) {
+        const nextKey = JSON.stringify(state);
+        if (this.lastEmissionKey === nextKey)
+            return;
+        this.lastEmissionKey = nextKey;
+        for (const listener of this.listeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                // Listener failures must not stop the watcher.
+            }
+        }
+    }
+    pruneOldTurns() {
+        const cutoff = this.now() - SEVEN_DAY_MS;
+        if (this.turns.length === 0)
+            return;
+        const next = this.turns.filter(turn => turn.timestampMs >= cutoff);
+        if (next.length !== this.turns.length) {
+            this.turns = next;
+        }
+    }
+}
+exports.ZaiQuotaWatcher = ZaiQuotaWatcher;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",