sidekick-shared 0.21.1 → 0.21.2

package/README.md

@@ -40,13 +40,13 @@ npm install sidekick-shared
 | **Assistant Turns** | Browser-safe timeline/process/answer projection for provider-normalized assistant turns (`segmentAssistantTurn()`, `assistantTurnEventsFromSessionEvents()`), including interleaved reasoning, compact tool groups, and Claude `Task` subagent refs without prompt leakage |
 | **Report** | Self-contained HTML session report generation |
 | **Credentials** | Claude Max OAuth credential reading from `~/.claude/.credentials.json` |
-| **Quota** | Claude Max subscription quota fetching (5-hour and 7-day windows), Codex rate-limit extraction from event streams, and **estimated** z.ai Coding Plan quota derivation from observed OpenCode traffic (`accumulateZaiUsage()`, `inferZaiQuotaState()`, `parseZaiQuotaError()`, `resolveZaiTier()`, `ZAI_TIER_BUDGETS`) — z.ai exposes no usage API, so this is a best-effort estimate, not authoritative |
+| **Quota** | Claude Max subscription quota fetching (5-hour and 7-day windows), Codex rate-limit extraction from event streams, and authoritative z.ai Coding Plan quota fetching via `resolveZaiQuota()` / `fetchZaiQuotaFromApi()` (reads z.ai's `api/monitor/usage/quota/limit` endpoint with cached-snapshot fallback). The deprecated observed-traffic z.ai estimator helpers remain exported for backward compatibility only |
 | **Provider Status** | API health checking via status.claude.com and status.openai.com (indicator, components, incidents) |
 | **Schemas** | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, quota, account status, and quota history — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath |
 | **Extractors** | Pure functions for single-event processing: `extractTokenUsage()`, `extractToolCall()` (top-level `tool_use`), `extractToolCalls()` (assistant content blocks), plus Node-only session asset extraction (`gatherAssetsForCwd()`, `readClaudeAssets()`, `readCodexAssets()`) for URLs, file paths, commands, and plans |
 | **Model Info & Pricing** | Model family parsing (Anthropic / OpenAI / Google, including legacy `claude-3-opus-…` and `claude-3-5-sonnet-…` IDs), context-window lookup (including Fable 5 / Opus 4.8 / Opus 4.7 / Sonnet 4.7 1M and GPT-5.x variants), pricing tables with optional LiteLLM hydration, null-aware cost (`calculateCost()`), provenance-preserving cost (`calculateCostWithProvenance()`, `mergeCostSources()`), and display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`) |
 | **Quota Polling** | `QuotaPoller` class with exponential backoff, active/idle intervals, and cached fallback |
-| **Multi-Provider Quota** | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex/z.ai quota updates behind one typed event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback; `ZaiQuotaWatcher` derives an estimated z.ai Coding Plan quota from observed OpenCode turns (event-driven, snapshot + history) |
+| **Multi-Provider Quota** | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex/z.ai quota updates behind one typed event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback; z.ai quota uses the API resolver with snapshot fallback |
 | **Accounts** | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for first-run bootstrap of the active system Claude/Codex credentials as a "Default" saved account, and `getActiveAccountStatus()` for a single-pass active-account read across providers |
 | **Account Management 2.0** | Provider-neutral acquisition + switching: `beginAccountLogin()` / `getAccountLoginStatus()` / `finalizeAccountLogin()` / `spawnAccountLogin()` drive a TTY-less, profile-isolated login that doesn't disturb the active account until finalization; `listAllAccounts()` and `switchAccount()` expose a shared switcher across Claude and Codex. Claude accounts get canonical profile homes with account-scoped macOS keychain suffixes and startup migration from legacy flat backups |
 | **Terminal sync & auto-switch** | Opt-in terminal profile pointers, shell-hook/launcher helpers, and a default-off `AutoSwitchController` (`decideAutoSwitch()`) that moves to a healthier saved account when quota crosses a configured threshold |

package/dist/index.d.ts

@@ -125,6 +125,8 @@ export { accumulateZaiUsage, extractNextFlushTime, inferZaiQuotaState, isZaiProv
 export type { ZaiAccumulatedUsage, ZaiAssistantTurn, ZaiOpenCodeRow, ZaiProviderId, ZaiQuotaError, ZaiQuotaErrorKind, ZaiTier, InferZaiQuotaStateOptions, } from './zaiQuota';
 export { ZaiQuotaWatcher } from './zaiQuotaWatcher';
 export type { ZaiQuotaWatcherOptions } from './zaiQuotaWatcher';
+export { fetchZaiQuotaFromApi, quotaStateFromZaiQuotaLimitPayload, readZaiCredentials, resolveZaiQuota, } from './zaiQuotaApi';
+export type { ReadZaiCredentialsOptions, ZaiCredentialSource, ZaiCredentials, ZaiPlatform, ZaiQuotaApiOptions, ZaiQuotaResolveOptions, } from './zaiQuotaApi';
 export { MultiProviderQuotaService } from './multiProviderQuotaService';
 export type { MultiProviderQuotaServiceOptions } from './multiProviderQuotaService';
 export type { ProviderQuotaMap, ProviderQuotaState, RuntimeQuotaProvider } from './providerQuota';

package/dist/index.js

@@ -7,8 +7,8 @@ exports.discoverSessionDirectory = exports.getClaudeSessionDirectory = exports.e
 exports.highlightEvent = exports.formatSessionJson = exports.formatSessionMarkdown = exports.formatSessionText = exports.classifyNoise = exports.shouldMergeWithPrevious = exports.classifyFollowEvent = exports.classifyMessage = exports.getSoftNoiseReason = exports.isHardNoiseFollowEvent = exports.isHardNoise = exports.formatToolSummary = exports.formatTokenCount = exports.formatDurationMs = exports.createJsonlTail = exports.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.readSessionContextSnapshot = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.composeContext = exports.FilterEngine = exports.searchSessions = exports.CodexDatabase = exports.OpenCodeDatabase = exports.discoverDebugLogs = exports.collapseDuplicates = exports.filterByLevel = exports.parseDebugLog = exports.scanSubagentTraces = exports.findAllSessionsWithWorktrees = exports.discoverWorktreeSiblings = exports.resolveWorktreeMainRepo = exports.getAllClaudeProjectFolders = exports.decodeEncodedPath = exports.getMostRecentlyActiveSessionDir = exports.findSubdirectorySessionDirs = exports.findSessionsInDirectory = exports.findAllClaudeSessions = exports.findActiveClaudeSession = void 0;
 exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.resolveClaudeLoginCommand = exports.listAllAccounts = exports.switchAccount = exports.spawnAccountLogin = exports.finalizeAccountLogin = exports.getAccountLoginStatus = exports.beginAccountLogin = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.reconcileClaudeAuthState = exports.applyActiveClaudeToLiveHome = exports.resolveActiveClaudeHome = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscriptFromEvents = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.PHRASE_CATEGORIES = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = void 0;
 exports.isZaiProviderId = exports.inferZaiQuotaState = exports.extractNextFlushTime = exports.accumulateZaiUsage = exports.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = exports.fetchCodexQuotaFromApi = exports.getWorkspaceIdFromPath = exports.pruneQuotaHistory = exports.readQuotaHistoryDailyBuckets = exports.readQuotaHistoryRange = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.fetchQuota = exports.AutoSwitchController = exports.decideAutoSwitch = exports.DEFAULT_AUTO_SWITCH_CONFIG = exports.removeLauncher = exports.writeLauncher = exports.isShellHookInstalled = exports.uninstallShellHook = exports.installShellHook = exports.setTerminalActiveProfile = exports.removeCodexAccount = exports.switchToCodexAccount = exports.finalizeCodexAccount = exports.prepareCodexAccount = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.getActiveCodexAccount = exports.listCodexAccounts = exports.getSystemCodexHome = exports.getCodexMonitoringHomes = exports.getCodexProfileHome = exports.getCodexProfilesDir = exports.readClaudeProfileIdentity = exports.isClaudeProfileAuthenticated = exports.claudeKeychainService = exports.claudeKeychainSuffix = exports.getClaudeProfileHome = exports.getClaudeProfilesDir = exports.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = void 0;
-exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.gatherAssetsForCwd = exports.codexSessions = exports.readCodexAssets = exports.claudeSessions = exports.readClaudeAssets = exports.extractCommands = exports.extractFilePaths = exports.extractUrls = exports.extractToolCalls = exports.extractToolCall = exports.extractTokenUsage = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = exports.MultiProviderQuotaService = exports.ZaiQuotaWatcher = exports.ZAI_TIER_BUDGETS = exports.ZAI_PROVIDER_IDS = exports.ZAI_PROMPT_INVOCATIONS = exports.turnTokenWeight = exports.rowsToZaiTurnsAndErrors = exports.resolveZaiTier = exports.parseZaiQuotaError = exports.makeUnavailableZaiQuotaState = void 0;
-exports.scopePeakHoursToSessionProvider = exports.isClaudeCodeSessionProvider = exports.fetchPeakHoursStatus = exports.createPeakHoursNotApplicableState = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = void 0;
+exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.gatherAssetsForCwd = exports.codexSessions = exports.readCodexAssets = exports.claudeSessions = exports.readClaudeAssets = exports.extractCommands = exports.extractFilePaths = exports.extractUrls = exports.extractToolCalls = exports.extractToolCall = exports.extractTokenUsage = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = exports.MultiProviderQuotaService = exports.resolveZaiQuota = exports.readZaiCredentials = exports.quotaStateFromZaiQuotaLimitPayload = exports.fetchZaiQuotaFromApi = exports.ZaiQuotaWatcher = exports.ZAI_TIER_BUDGETS = exports.ZAI_PROVIDER_IDS = exports.ZAI_PROMPT_INVOCATIONS = exports.turnTokenWeight = exports.rowsToZaiTurnsAndErrors = exports.resolveZaiTier = exports.parseZaiQuotaError = exports.makeUnavailableZaiQuotaState = void 0;
+exports.scopePeakHoursToSessionProvider = exports.isClaudeCodeSessionProvider = exports.fetchPeakHoursStatus = exports.createPeakHoursNotApplicableState = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = void 0;
 var taskPersistence_1 = require("./types/taskPersistence");
 Object.defineProperty(exports, "TASK_PERSISTENCE_SCHEMA_VERSION", { enumerable: true, get: function () { return taskPersistence_1.TASK_PERSISTENCE_SCHEMA_VERSION; } });
 Object.defineProperty(exports, "normalizeTaskStatus", { enumerable: true, get: function () { return taskPersistence_1.normalizeTaskStatus; } });
@@ -311,6 +311,11 @@ Object.defineProperty(exports, "ZAI_PROVIDER_IDS", { enumerable: true, get: func
 Object.defineProperty(exports, "ZAI_TIER_BUDGETS", { enumerable: true, get: function () { return zaiQuota_1.ZAI_TIER_BUDGETS; } });
 var zaiQuotaWatcher_1 = require("./zaiQuotaWatcher");
 Object.defineProperty(exports, "ZaiQuotaWatcher", { enumerable: true, get: function () { return zaiQuotaWatcher_1.ZaiQuotaWatcher; } });
+var zaiQuotaApi_1 = require("./zaiQuotaApi");
+Object.defineProperty(exports, "fetchZaiQuotaFromApi", { enumerable: true, get: function () { return zaiQuotaApi_1.fetchZaiQuotaFromApi; } });
+Object.defineProperty(exports, "quotaStateFromZaiQuotaLimitPayload", { enumerable: true, get: function () { return zaiQuotaApi_1.quotaStateFromZaiQuotaLimitPayload; } });
+Object.defineProperty(exports, "readZaiCredentials", { enumerable: true, get: function () { return zaiQuotaApi_1.readZaiCredentials; } });
+Object.defineProperty(exports, "resolveZaiQuota", { enumerable: true, get: function () { return zaiQuotaApi_1.resolveZaiQuota; } });
 var multiProviderQuotaService_1 = require("./multiProviderQuotaService");
 Object.defineProperty(exports, "MultiProviderQuotaService", { enumerable: true, get: function () { return multiProviderQuotaService_1.MultiProviderQuotaService; } });
 // Model Context

package/dist/providers/openCode.d.ts

@@ -93,10 +93,10 @@ export declare class OpenCodeProvider implements SessionProviderBase {
      * Derives a z.ai coding-plan `QuotaState` from OpenCode assistant turns
      * tagged with `providerID ∈ {zai, zai-coding-plan}`.
      *
-     * z.ai does not expose a quota API (verified vs. docs.z.ai/openapi.json),
-     * so this method accumulates observed per-turn tokens from OpenCode's DB
-     * into 5-hour / 7-day rolling windows and infers utilization against the
-     * configured tier budget. Returns null when no z.ai routing is detected.
+     * This compatibility estimator predates the authoritative z.ai quota API.
+     * New product code should use `zaiQuotaApi.ts`; this method remains for
+     * consumers that still want a local OpenCode DB-derived estimate. Returns
+     * null when no z.ai routing is detected.
      *
      * @param tier  Plan tier; `'auto'` infers from observed weekly volume.
      *              When the caller has no opinion, the heuristic falls back to

package/dist/providers/openCode.js

@@ -1572,15 +1572,15 @@ class OpenCodeProvider {
         this.sessionMetaCache.clear();
         this.dynamicContextWindowLimit = null;
     }
-    // --- z.ai (GLM Coding Plan) quota derivation ---
+    // --- z.ai (GLM Coding Plan) compatibility quota derivation ---
     /**
      * Derives a z.ai coding-plan `QuotaState` from OpenCode assistant turns
      * tagged with `providerID ∈ {zai, zai-coding-plan}`.
      *
-     * z.ai does not expose a quota API (verified vs. docs.z.ai/openapi.json),
-     * so this method accumulates observed per-turn tokens from OpenCode's DB
-     * into 5-hour / 7-day rolling windows and infers utilization against the
-     * configured tier budget. Returns null when no z.ai routing is detected.
+     * This compatibility estimator predates the authoritative z.ai quota API.
+     * New product code should use `zaiQuotaApi.ts`; this method remains for
+     * consumers that still want a local OpenCode DB-derived estimate. Returns
+     * null when no z.ai routing is detected.
      *
      * @param tier  Plan tier; `'auto'` infers from observed weekly volume.
      *              When the caller has no opinion, the heuristic falls back to

package/dist/quotaSnapshots.d.ts

@@ -3,7 +3,7 @@ import type { AccountProviderId } from './accountRegistry';
 /**
  * Storage key for a quota snapshot. Extends `AccountProviderId` with `'zai'`
  * because z.ai has no full account-management surface in v1, but the snapshot
- * store still needs a stable key for the derived z.ai quota cache.
+ * store still needs a stable key for the z.ai quota cache.
  */
 export type QuotaSnapshotProviderId = AccountProviderId | 'zai';
 export declare function writeQuotaSnapshot(providerId: QuotaSnapshotProviderId, accountId: string, quota: QuotaState): void;

package/dist/zaiQuota.d.ts

@@ -1,9 +1,9 @@
 /**
- * Stateless quota accumulator for z.ai coding plans.
+ * Deprecated stateless quota accumulator for z.ai coding plans.
  *
- * z.ai (GLM Coding Plan) does not expose an HTTP quota/usage API (verified
- * against the canonical OpenAPI spec at https://docs.z.ai/openapi.json).
- * The only programmatic signals are:
+ * This estimator is kept for compatibility with consumers that imported the
+ * old helpers directly. Product code should use `zaiQuotaApi.ts`, which calls
+ * z.ai's authoritative quota endpoint. The legacy estimator only uses:
  *
  *   1. Per-call token `usage` returned inline on each chat completion —
  *      which OpenCode persists into `opencode.db` message rows tagged with
@@ -13,8 +13,8 @@
  *      in the human-readable message text.
  *
  * This module is therefore a **derivation** rather than a fetcher: callers
- * feed it observed assistant turns (and any error events), and it computes
- * an estimated `QuotaState` keyed against the published per-tier budgets.
+ * feed it observed assistant turns (and any error events), and it computes a
+ * compatibility `QuotaState` keyed against the published per-tier budgets.
  *
  * Polling / eventing / persistence are the caller's responsibility —
  * see `ZaiQuotaWatcher` for the bundled watcher.

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.js

@@ -2,15 +2,16 @@
 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.
+ * Deprecated 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}`.
+ * This watcher is retained for compatibility. Product code now uses
+ * `zaiQuotaApi.ts` to call z.ai's authoritative quota endpoint. The legacy
+ * watcher maintains rolling 5-hour / 7-day windows in memory and recomputes a
+ * derived `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`.

package/package.json

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