sidekick-shared 0.24.3 → 0.24.5

package/dist/writers/atomic.js

@@ -35,11 +35,42 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.atomicWriteJson = atomicWriteJson;
 exports.atomicWriteJsonSync = atomicWriteJsonSync;
+exports.atomicWriteFileSync = atomicWriteFileSync;
 exports.updateJsonStoreAtomic = updateJsonStoreAtomic;
+exports.withFileLockSync = withFileLockSync;
+exports.updateJsonStoreAtomicSync = updateJsonStoreAtomicSync;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const LOCK_STALE_MS = 10_000;
+/**
+ * How long to wait for a lock that is making no progress.
+ *
+ * This budget detects a wedged holder, not a long queue. It is measured from the
+ * last time the lock changed hands rather than from the first attempt, because a
+ * writer queued behind other healthy writers is waiting, not failing — see
+ * {@link acquireLock}.
+ */
+const LOCK_NO_PROGRESS_MS = 3_000;
+/**
+ * A live async holder heartbeats every LOCK_STALE_MS / 3; an mtime frozen this
+ * long means the heartbeat timer is gone — the owner is dead (possibly with its
+ * PID recycled by the OS) or wedged beyond recovery. Reclaim regardless of the
+ * PID probe, which cannot tell a recycled PID from a live owner. Sync holders
+ * have no heartbeat; they usually hold locks for milliseconds, and even the
+ * slowest (a keychain read through `security` behind the auth-swap lock, up to
+ * a few seconds) stays far under this ceiling.
+ */
+const LOCK_ABANDONED_MS = 120_000;
+/**
+ * Hard ceiling on how long a synchronous waiter blocks, regardless of queue
+ * progress. Progress resets are correct for async waiters, but a sync waiter
+ * blocks its process's event loop while queued, so healthy-queue churn must not
+ * extend the block indefinitely.
+ */
+const SYNC_LOCK_MAX_WAIT_MS = 15_000;
+const LOCK_WAIT_INTERVAL_MS = 15;
+const lockSleepView = new Int32Array(new SharedArrayBuffer(4));
 async function syncDirectory(directory) {
     let handle;
     try {
@@ -91,12 +122,16 @@ async function atomicWriteJson(filePath, value) {
     }
 }
 function atomicWriteJsonSync(filePath, value) {
+    atomicWriteFileSync(filePath, JSON.stringify(value, null, 2));
+}
+/** Raw-string sibling of {@link atomicWriteJsonSync} for non-JSON payloads. */
+function atomicWriteFileSync(filePath, content, mode = 0o600) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
     const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`;
     let descriptor;
     try {
-        descriptor = fs.openSync(tempPath, 'wx', 0o600);
-        fs.writeFileSync(descriptor, JSON.stringify(value, null, 2), { encoding: 'utf8' });
+        descriptor = fs.openSync(tempPath, 'wx', mode);
+        fs.writeFileSync(descriptor, content, { encoding: 'utf8' });
         fs.fsyncSync(descriptor);
         fs.closeSync(descriptor);
         descriptor = undefined;
@@ -142,8 +177,22 @@ async function updateJsonStoreAtomic(filePath, createEmpty, update) {
         await releaseLock(lockPath, lock);
     }
 }
+/**
+ * Waits for exclusive ownership of `lockPath`.
+ *
+ * The wait budget is reset every time the lock changes hands. A flat budget from
+ * the first attempt conflated two unrelated conditions — a wedged holder and a
+ * queue of healthy writers — so under real contention the writers at the back of
+ * the queue failed even though every lock was being acquired and released
+ * correctly. Each cycle costs three fsyncs (lock file, temp file, directory), so
+ * on slow storage a burst of concurrent captures drained slower than the budget.
+ *
+ * A stuck holder keeps the same token, so it makes no progress and still trips
+ * the timeout; the stale-reclaim path below still handles an owner that died.
+ */
 async function acquireLock(lockPath) {
-    const deadline = Date.now() + 3000;
+    let deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+    let observedOwner = null;
     while (true) {
         try {
             const handle = await fs.promises.open(lockPath, 'wx', 0o600);
@@ -159,29 +208,27 @@ async function acquireLock(lockPath) {
         catch (error) {
             if (error.code !== 'EEXIST')
                 throw error;
+            // The token identifies the current holder. mtime cannot stand in for it:
+            // the heartbeat keeps touching the file, so even a wedged holder looks
+            // fresh. A different token means the queue advanced.
+            const currentOwner = await fs.promises.readFile(lockPath, 'utf8').catch(() => null);
+            if (currentOwner !== null && currentOwner !== observedOwner) {
+                observedOwner = currentOwner;
+                deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+            }
             try {
                 const stat = await fs.promises.stat(lockPath);
-                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-                    const owner = await fs.promises.readFile(lockPath, 'utf8').catch(() => '');
-                    const ownerPid = Number.parseInt(owner.split(':', 1)[0], 10);
-                    let ownerAlive = Number.isInteger(ownerPid) && ownerPid > 0;
-                    if (ownerAlive) {
-                        try {
-                            process.kill(ownerPid, 0);
-                        }
-                        catch (ownerError) {
-                            ownerAlive = ownerError.code === 'EPERM';
-                        }
-                    }
-                    if (!ownerAlive)
-                        await fs.promises.rm(lockPath, { force: true });
+                const frozenMs = Date.now() - stat.mtimeMs;
+                if (frozenMs > LOCK_STALE_MS && !lockOwnerAlive(currentOwner, frozenMs)) {
+                    await fs.promises.rm(lockPath, { force: true });
                 }
             }
             catch {
                 // The other writer released between checks.
             }
-            if (Date.now() >= deadline)
-                throw new Error(`Timed out waiting for store lock: ${lockPath}`);
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (no progress for ${LOCK_NO_PROGRESS_MS}ms)`);
+            }
             await new Promise((resolve) => setTimeout(resolve, 15));
         }
     }
@@ -198,3 +245,127 @@ async function releaseLock(lockPath, lock) {
         // The lock was already released or replaced; never delete another owner's lock.
     }
 }
+/**
+ * Whether the recorded owner of a stale lock should still be treated as alive.
+ * An mtime frozen past {@link LOCK_ABANDONED_MS} overrides the PID probe — see
+ * the constant for why the probe alone cannot be trusted at that age.
+ */
+function lockOwnerAlive(owner, frozenMs) {
+    if (frozenMs > LOCK_ABANDONED_MS)
+        return false;
+    const ownerPid = Number.parseInt((owner ?? '').split(':', 1)[0], 10);
+    if (!Number.isInteger(ownerPid) || ownerPid <= 0)
+        return false;
+    try {
+        process.kill(ownerPid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Synchronous counterpart of {@link acquireLock}, sharing its lock-file
+ * protocol so sync and async waiters exclude each other across processes.
+ *
+ * Two timeout rules apply instead of one: the same progress-based budget as the
+ * async path (a token that never changes trips it in LOCK_NO_PROGRESS_MS), plus
+ * an absolute {@link SYNC_LOCK_MAX_WAIT_MS} ceiling, because a sync waiter
+ * blocks its event loop while queued. Sync holders take no heartbeat — their
+ * critical sections must stay well under LOCK_STALE_MS (in-repo users are
+ * local-filesystem read-modify-writes, plus keychain reads behind the
+ * auth-swap locks that can take a few seconds).
+ *
+ * The caller must ensure `dirname(lockPath)` exists — a missing parent
+ * surfaces as a raw ENOENT, not a timeout.
+ */
+function withFileLockSync(lockPath, operation) {
+    const token = acquireLockSync(lockPath);
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            if (fs.readFileSync(lockPath, 'utf8') === token)
+                fs.rmSync(lockPath, { force: true });
+        }
+        catch {
+            // The lock was already released or replaced; never delete another owner's lock.
+        }
+    }
+}
+function acquireLockSync(lockPath) {
+    const start = Date.now();
+    let deadline = start + LOCK_NO_PROGRESS_MS;
+    let observedOwner = null;
+    while (true) {
+        try {
+            const descriptor = fs.openSync(lockPath, 'wx', 0o600);
+            const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+            fs.writeFileSync(descriptor, token, 'utf8');
+            fs.fsyncSync(descriptor);
+            fs.closeSync(descriptor);
+            return token;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let currentOwner = null;
+            try {
+                currentOwner = fs.readFileSync(lockPath, 'utf8');
+            }
+            catch {
+                // The other writer released between checks.
+            }
+            if (currentOwner !== null && currentOwner !== observedOwner) {
+                observedOwner = currentOwner;
+                deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+            }
+            try {
+                const stat = fs.statSync(lockPath);
+                const frozenMs = Date.now() - stat.mtimeMs;
+                if (frozenMs > LOCK_STALE_MS && !lockOwnerAlive(currentOwner, frozenMs)) {
+                    fs.rmSync(lockPath, { force: true });
+                }
+            }
+            catch {
+                // The other writer released between checks.
+            }
+            const now = Date.now();
+            if (now >= deadline) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (no progress for ${LOCK_NO_PROGRESS_MS}ms)`);
+            }
+            if (now - start >= SYNC_LOCK_MAX_WAIT_MS) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (blocked synchronously for ${SYNC_LOCK_MAX_WAIT_MS}ms)`);
+            }
+            Atomics.wait(lockSleepView, 0, 0, LOCK_WAIT_INTERVAL_MS);
+        }
+    }
+}
+/** Synchronous mirror of {@link updateJsonStoreAtomic}. */
+function updateJsonStoreAtomicSync(filePath, createEmpty, update) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    return withFileLockSync(`${filePath}.lock`, () => {
+        let latest = createEmpty();
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (raw !== undefined) {
+            try {
+                latest = JSON.parse(raw);
+            }
+            catch {
+                const corruptPath = `${filePath}.corrupt-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+                fs.renameSync(filePath, corruptPath);
+            }
+        }
+        const next = update(latest);
+        atomicWriteJsonSync(filePath, next);
+        return next;
+    });
+}

package/dist/zaiQuota.d.ts

@@ -27,6 +27,10 @@ import type { QuotaState } from './quota';
  * "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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_TIER_BUDGETS: {
     readonly lite: {
@@ -42,20 +46,43 @@ export declare const ZAI_TIER_BUDGETS: {
         readonly weekly: 8000;
     };
 };
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiTier = 'lite' | 'pro' | 'max';
 /**
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_PROMPT_INVOCATIONS = 17.5;
 /**
  * Provider IDs that OpenCode tags on z.ai-routed messages.
  * `zai-coding-plan` is the Coding Plan key; `zai` is the bare API key.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_PROVIDER_IDS: readonly ["zai", "zai-coding-plan"];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiProviderId = (typeof ZAI_PROVIDER_IDS)[number];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export declare function isZaiProviderId(value: unknown): value is ZaiProviderId;
 /**
  * Minimal description of a z.ai-routed assistant turn needed to accumulate
@@ -64,6 +91,10 @@ export declare function isZaiProviderId(value: unknown): value is ZaiProviderId;
  * provider comparability; cost is omitted (always 0 for z.ai).
  *
  * `timestampMs` is when the assistant turn completed (epoch milliseconds).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export interface ZaiAssistantTurn {
     timestampMs: number;
@@ -74,6 +105,11 @@ export interface ZaiAssistantTurn {
     cacheWriteTokens: number;
     reasoningTokens: number;
 }
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface ZaiAccumulatedUsage {
     /** Number of z.ai assistant turns inside the 5-hour window. */
     fiveHourTurns: number;
@@ -96,6 +132,10 @@ export interface ZaiAccumulatedUsage {
  * 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×.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function turnTokenWeight(turn: Pick<ZaiAssistantTurn, 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens'>): number;
 /**
@@ -104,6 +144,10 @@ export declare function turnTokenWeight(turn: Pick<ZaiAssistantTurn, 'inputToken
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function accumulateZaiUsage(turns: readonly ZaiAssistantTurn[], nowMs?: number): ZaiAccumulatedUsage;
 /**
@@ -113,8 +157,17 @@ export declare function accumulateZaiUsage(turns: readonly ZaiAssistantTurn[], n
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function resolveZaiTier(configured: ZaiTier | 'auto', accumulated: ZaiAccumulatedUsage): ZaiTier;
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface InferZaiQuotaStateOptions {
     /** ISO timestamp to stamp on the sample. Default: now. */
     capturedAt?: string;
@@ -138,9 +191,23 @@ export interface InferZaiQuotaStateOptions {
  *   - `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).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function inferZaiQuotaState(accumulated: ZaiAccumulatedUsage, tier: ZaiTier, options?: InferZaiQuotaStateOptions): QuotaState;
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiQuotaErrorKind = 'exhausted' | 'fup' | 'expired' | 'invalid';
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface ZaiQuotaError {
     kind: ZaiQuotaErrorKind;
     /** ISO timestamp parsed from `${next_flush_time}` in the error message, if present. */
@@ -159,6 +226,10 @@ export interface ZaiQuotaError {
  * `YYYY-MM-DD HH:mm:ss` form defensively.
  *
  * Returns `null` when the code is not a quota-related business error.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function parseZaiQuotaError(error: {
     code?: string | number;
@@ -171,17 +242,29 @@ export declare function parseZaiQuotaError(error: {
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function extractNextFlushTime(message: string): string | undefined;
 /**
  * Builds an unavailable z.ai `QuotaState` for the cold-start case where
  * no z.ai traffic has been observed yet.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function makeUnavailableZaiQuotaState(error?: string, tier?: ZaiTier, capturedAt?: string): QuotaState;
 /**
  * Shape of a row returned by `OpenCodeDatabase.getAssistantMessagesByProviderId`.
  * Defined here to keep the sidekick-shared helper self-contained without
  * leaking the OpenCode db module into the public quota surface.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export interface ZaiOpenCodeRow {
     timeCreated: number;
@@ -202,6 +285,10 @@ export interface ZaiOpenCodeRow {
  *
  * Returns `{ turns, errors }` so callers can replay them through
  * `ZaiQuotaWatcher.ingestAssistantTurns` and `ingestError`.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function rowsToZaiTurnsAndErrors(rows: readonly ZaiOpenCodeRow[]): {
     turns: ZaiAssistantTurn[];

package/dist/zaiQuota.js

@@ -18,6 +18,10 @@ exports.rowsToZaiTurnsAndErrors = rowsToZaiTurnsAndErrors;
  * "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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_TIER_BUDGETS = {
     lite: { fiveHour: 80, weekly: 400 },
@@ -29,6 +33,10 @@ exports.ZAI_TIER_BUDGETS = {
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_PROMPT_INVOCATIONS = 17.5;
 const FIVE_HOUR_MS = 5 * 3_600_000;
@@ -36,8 +44,17 @@ 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_PROVIDER_IDS = ['zai', 'zai-coding-plan'];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 function isZaiProviderId(value) {
     return value === 'zai' || value === 'zai-coding-plan';
 }
@@ -45,6 +62,10 @@ function isZaiProviderId(value) {
  * 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×.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function turnTokenWeight(turn) {
     return (turn.inputTokens +
@@ -59,6 +80,10 @@ function turnTokenWeight(turn) {
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function accumulateZaiUsage(turns, nowMs = Date.now()) {
     const fiveHourCutoff = nowMs - FIVE_HOUR_MS;
@@ -104,6 +129,10 @@ function accumulateZaiUsage(turns, nowMs = Date.now()) {
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function resolveZaiTier(configured, accumulated) {
     if (configured !== 'auto')
@@ -128,6 +157,10 @@ function resolveZaiTier(configured, accumulated) {
  *   - `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).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function inferZaiQuotaState(accumulated, tier, options = {}) {
     const budget = exports.ZAI_TIER_BUDGETS[tier];
@@ -185,6 +218,10 @@ const ZAI_ERROR_CODES = {
  * `YYYY-MM-DD HH:mm:ss` form defensively.
  *
  * Returns `null` when the code is not a quota-related business error.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function parseZaiQuotaError(error) {
     if (!error)
@@ -203,6 +240,10 @@ function parseZaiQuotaError(error) {
  * 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.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function extractNextFlushTime(message) {
     if (!message)
@@ -236,6 +277,10 @@ function extractNextFlushTime(message) {
 /**
  * Builds an unavailable z.ai `QuotaState` for the cold-start case where
  * no z.ai traffic has been observed yet.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function makeUnavailableZaiQuotaState(error = 'No z.ai usage observed yet', tier = 'lite', capturedAt = new Date().toISOString()) {
     return {
@@ -259,6 +304,10 @@ function makeUnavailableZaiQuotaState(error = 'No z.ai usage observed yet', tier
  *
  * Returns `{ turns, errors }` so callers can replay them through
  * `ZaiQuotaWatcher.ingestAssistantTurns` and `ingestError`.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function rowsToZaiTurnsAndErrors(rows) {
     const turns = [];

package/dist/zaiQuotaWatcher.d.ts

@@ -10,6 +10,10 @@ type TierResolver = (configured: ZaiTier | 'auto', accumulated: ZaiAccumulatedUs
 type SnapshotReader = (providerId: ZaiSnapshotProvider, accountId: string) => QuotaState | null;
 type SnapshotWriter = (providerId: ZaiSnapshotProvider, accountId: string, quota: QuotaState) => void;
 type HistoryAppender = (sample: QuotaHistorySample) => void | Promise<void>;
+/**
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
+ */
 export interface ZaiQuotaWatcherOptions {
     /** Configured tier. Default: `'auto'` (heuristic from observed usage). */
     tier?: ZaiTier | 'auto';
@@ -39,6 +43,9 @@ export interface ZaiQuotaWatcherOptions {
  * 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`.
+ *
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
  */
 export declare class ZaiQuotaWatcher implements Disposable {
     private readonly tier;

package/dist/zaiQuotaWatcher.js

@@ -37,6 +37,9 @@ function enrichZaiState(state) {
  * 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`.
+ *
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
  */
 class ZaiQuotaWatcher {
     tier;

package/package.json

@@ -1,7 +1,35 @@
 {
   "name": "sidekick-shared",
-  "version": "0.24.3",
+  "version": "0.24.5",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
+  "keywords": [
+    "claude-code",
+    "codex-cli",
+    "opencode",
+    "session-monitor",
+    "token-usage",
+    "quota",
+    "jsonl",
+    "ai-coding-assistant",
+    "agent-hub",
+    "zod-schemas"
+  ],
+  "homepage": "https://cesarandreslopez.github.io/sidekick-agent-hub/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cesarandreslopez/sidekick-agent-hub",
+    "directory": "sidekick-shared"
+  },
+  "bugs": {
+    "url": "https://github.com/cesarandreslopez/sidekick-agent-hub/issues"
+  },
+  "author": {
+    "name": "Cesar Andres Lopez",
+    "email": "cesarandreslopez@gmail.com"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -47,8 +75,38 @@
     },
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "dist/browser.d.ts"
+      ],
+      "node": [
+        "dist/node.d.ts"
+      ],
+      "schemas": [
+        "dist/schemas/index.d.ts"
+      ],
+      "phrases": [
+        "dist/phrases.d.ts"
+      ],
+      "modelContext": [
+        "dist/modelContext.d.ts"
+      ],
+      "modelInfo": [
+        "dist/modelInfo.d.ts"
+      ],
+      "formatting": [
+        "dist/formatting.d.ts"
+      ],
+      "statusline": [
+        "dist/statusline/index.d.ts"
+      ]
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "sideEffects": false,
   "publishConfig": {