sidekick-shared 0.18.0 → 0.18.2

package/README.md

@@ -22,8 +22,8 @@ npm install sidekick-shared
 | **Readers** | Read tasks, decisions, notes, history, handoff, and plans from `~/.config/sidekick/` |
 | **Providers** | Session provider abstraction with Claude Code, OpenCode, and Codex implementations; auto-detection via filesystem |
 | **Parsers** | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing |
-| **Watchers** | Live session file watching with event bridging |
-| **Formatters** | Tool summary, noise classification, session dump (text/markdown/JSON), event highlighting |
+| **Watchers** | Live session file watching with event bridging, plus `createJsonlTail()` for raw incremental JSONL consumers |
+| **Formatters** | Display helpers (`formatTokenCount()`, `formatDurationMs()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting |
 | **Search** | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date) |
 | **Aggregation** | Event aggregation, frequency tracking, activity heatmaps, pattern extraction |
 | **Report** | Self-contained HTML session report generation |
@@ -52,6 +52,7 @@ npm install sidekick-shared
 | `sidekick-shared/phrases`         | Any runtime                 | Phrase arrays + `getRandomPhrase()`.                               |
 | `sidekick-shared/modelContext`    | Any runtime                 | Direct access to the context-window module.                        |
 | `sidekick-shared/modelInfo`       | Any runtime                 | Direct access to model parsing and cost math.                      |
+| `sidekick-shared/formatting`      | Any runtime                 | Direct access to pure token and duration display helpers.           |
 
 ### Browser / webview runtimes
 
@@ -64,6 +65,8 @@ import {
   parseModelId,
   calculateCost,
   formatCost,
+  formatTokenCount,
+  formatDurationMs,
 } from 'sidekick-shared/browser';
 ```
 
@@ -177,6 +180,16 @@ const tools = extractToolCalls(event);           // ToolCall[]    — assistant
 const toolFromEvent = extractToolCall(event);    // ToolCall | null — top-level `tool_use` events
 ```
 
+### Format shared dashboard values
+
+```typescript
+import { formatTokenCount, formatDurationMs, formatCost } from 'sidekick-shared';
+
+console.log(formatTokenCount(15_000)); // "15.0k"
+console.log(formatDurationMs(330_000)); // "5m 30s"
+console.log(formatCost(0.0045)); // "$0.0045"
+```
+
 ### Validate JSONL events with Zod schemas
 
 ```typescript
@@ -186,7 +199,25 @@ const parser = new JsonlParser(
   { onEvent: (e) => console.log(e), onError: (e) => console.warn(e) },
   { schema: sessionEventSchema },
 );
-parser.addChunk(rawData);
+parser.processChunk(rawData);
+```
+
+### Tail raw JSONL events incrementally
+
+Use `createJsonlTail()` when a consumer needs raw parsed events and owns its own aggregation lifecycle. `onBatchComplete` fires once after each drained byte chunk, which lets callers defer expensive UI or metrics updates until parsing for that chunk is complete.
+
+```typescript
+import { createJsonlTail, sessionEventSchema } from 'sidekick-shared';
+
+const tail = createJsonlTail({
+  path: '/path/to/session.jsonl',
+  schema: sessionEventSchema,
+  onEvent: event => aggregator.processEvent(event),
+  onBatchComplete: () => renderMetrics(aggregator.getMetrics()),
+  onError: error => console.warn(error.message),
+});
+
+tail.start();
 ```
 
 ### Poll quota with backoff
@@ -220,6 +251,7 @@ service.onUpdate(({ claude, codex }) => {
 
 service.startPolling();
 // service.setPollingMode('active'); // tighter cadence while a session is live
+// service.updateProviderQuota('codex', codexQuota); // externally push Codex quota snapshots
 // service.dispose();
 ```
 
@@ -264,6 +296,10 @@ const totalSource = mergeCostSources(a.source, b.source); // 'unpriced' wins (le
 console.log(formatCost(total), totalSource);
 ```
 
+### Deferred Contextful adoption note
+
+`sidekick-shared@0.18.x` already exposes the quota primitives Contextful needs: `MultiProviderQuotaService`, `ProviderQuotaMap`, `ProviderQuotaState`, and `CodexQuotaWatcher`. Contextful should keep its local integration unchanged until a newer `sidekick-shared` release is published to npm, then migrate thin wrappers to these public APIs plus `formatTokenCount()`, `formatDurationMs()`, and `createJsonlTail()`.
+
 ## Building
 
 ```bash

package/dist/browser.d.ts

@@ -8,5 +8,7 @@
  * For pricing hydration (LiteLLM catalog refresh), use `sidekick-shared/node`.
  */
 export { getModelContextWindowSize, DEFAULT_CONTEXT_WINDOW } from './modelContext';
+export { formatDurationMs, formatTokenCount } from './formatting';
+export type { FormatDurationMsOptions, FormatTokenCountOptions } from './formatting';
 export { parseModelId, getModelPricing, getModelInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, shortModelName, getModelDisplayInfo, compareModelIds, sortModelIds, formatCost, } from './modelInfo';
 export type { ModelPricing, CostTokenUsage, CostSource, CostProvenanceInput, CostWithProvenance, ModelProvider, ParsedModelId, ModelInfo, ModelDisplayInfo, } from './modelInfo';

package/dist/browser.js

@@ -9,10 +9,13 @@
  * For pricing hydration (LiteLLM catalog refresh), use `sidekick-shared/node`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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 = void 0;
+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.formatTokenCount = exports.formatDurationMs = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = void 0;
 var modelContext_1 = require("./modelContext");
 Object.defineProperty(exports, "getModelContextWindowSize", { enumerable: true, get: function () { return modelContext_1.getModelContextWindowSize; } });
 Object.defineProperty(exports, "DEFAULT_CONTEXT_WINDOW", { enumerable: true, get: function () { return modelContext_1.DEFAULT_CONTEXT_WINDOW; } });
+var formatting_1 = require("./formatting");
+Object.defineProperty(exports, "formatDurationMs", { enumerable: true, get: function () { return formatting_1.formatDurationMs; } });
+Object.defineProperty(exports, "formatTokenCount", { enumerable: true, get: function () { return formatting_1.formatTokenCount; } });
 var modelInfo_1 = require("./modelInfo");
 Object.defineProperty(exports, "parseModelId", { enumerable: true, get: function () { return modelInfo_1.parseModelId; } });
 Object.defineProperty(exports, "getModelPricing", { enumerable: true, get: function () { return modelInfo_1.getModelPricing; } });

package/dist/codexQuota.d.ts

@@ -1,3 +1,43 @@
 import type { QuotaState } from './quota';
+import { CodexProvider } from './providers/codex';
+import type { ProviderQuotaState } from './providerQuota';
+import type { SavedAccountProfile } from './accountRegistry';
 import type { CodexRateLimits } from './types/codex';
-export declare function quotaFromCodexRateLimits(rateLimits: CodexRateLimits | null | undefined, source?: 'session' | 'cache', capturedAt?: string): QuotaState | null;
+type SnapshotReader = (providerId: 'codex', accountId: string) => QuotaState | null;
+type SnapshotWriter = (providerId: 'codex', accountId: string, quota: QuotaState) => void;
+export type CodexQuotaResolveSource = 'local' | 'api' | 'auto';
+export interface CodexQuotaCreditsSnapshot {
+    hasCredits?: boolean;
+    unlimited?: boolean;
+    balance?: string;
+}
+export interface CodexQuotaResolveOptions {
+    workspacePath?: string;
+    source?: CodexQuotaResolveSource;
+    codexHome?: string;
+    provider?: CodexProvider;
+    activeAccount?: SavedAccountProfile | null;
+    readSnapshot?: SnapshotReader;
+    writeSnapshot?: SnapshotWriter;
+    maxTailBytes?: number;
+    maxSessionFiles?: number;
+    fetchImpl?: typeof fetch;
+    accessToken?: string;
+}
+export interface CodexQuotaApiOptions {
+    codexHome?: string;
+    accessToken?: string;
+    fetchImpl?: typeof fetch;
+    usageUrl?: string;
+    capturedAt?: string;
+}
+export declare function quotaFromCodexRateLimits(rateLimits: CodexRateLimits | null | undefined, source?: 'api' | 'session' | 'cache', capturedAt?: string): QuotaState | null;
+export declare function readLatestCodexQuotaFromRollouts(sessionPaths: string[], options?: {
+    source?: 'session' | 'cache';
+    maxTailBytes?: number;
+    maxSessionFiles?: number;
+}): QuotaState | null;
+export declare function resolveCodexQuotaFromLocalSources(options?: CodexQuotaResolveOptions): ProviderQuotaState<'codex'> | null;
+export declare function resolveCodexQuota(options?: CodexQuotaResolveOptions): Promise<ProviderQuotaState<'codex'>>;
+export declare function fetchCodexQuotaFromApi(options?: CodexQuotaApiOptions): Promise<QuotaState>;
+export {};

package/dist/codexQuota.js

@@ -1,6 +1,153 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.quotaFromCodexRateLimits = quotaFromCodexRateLimits;
+exports.readLatestCodexQuotaFromRollouts = readLatestCodexQuotaFromRollouts;
+exports.resolveCodexQuotaFromLocalSources = resolveCodexQuotaFromLocalSources;
+exports.resolveCodexQuota = resolveCodexQuota;
+exports.fetchCodexQuotaFromApi = fetchCodexQuotaFromApi;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const codexProfiles_1 = require("./codexProfiles");
+const quotaSnapshots_1 = require("./quotaSnapshots");
+const codex_1 = require("./providers/codex");
+const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_SESSION_FILES = 50;
+const CHATGPT_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+function normalizePercent(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function timestampToIso(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+        return '';
+    }
+    return new Date(seconds * 1000).toISOString();
+}
+function accountEmail(account) {
+    return account?.email ?? account?.metadata?.email;
+}
+function enrichCodexQuota(state, account) {
+    return {
+        ...state,
+        runtimeProvider: 'codex',
+        providerId: 'codex',
+        accountLabel: account?.label,
+        accountDetail: accountEmail(account),
+    };
+}
+function unavailableCodexQuota(error, account, meta = {}) {
+    return enrichCodexQuota({
+        fiveHour: { utilization: 0, resetsAt: '' },
+        sevenDay: { utilization: 0, resetsAt: '' },
+        available: false,
+        error,
+        providerId: 'codex',
+        fiveHourLabel: 'Primary',
+        sevenDayLabel: 'Secondary',
+        ...meta,
+    }, account);
+}
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (Number.isNaN(retryAt))
+        return undefined;
+    return Math.max(retryAt - Date.now(), 0);
+}
+function firstString(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function normalizeCredits(credits) {
+    if (!credits)
+        return undefined;
+    return {
+        hasCredits: credits.has_credits ?? credits.hasCredits,
+        unlimited: credits.unlimited,
+        balance: credits.balance ?? undefined,
+    };
+}
+function normalizeRateLimitReachedType(value) {
+    if (typeof value === 'string')
+        return value;
+    return firstString(value?.kind);
+}
+function normalizeApiWindow(window) {
+    if (!window)
+        return undefined;
+    const windowMinutes = typeof window.window_minutes === 'number' || window.window_minutes === null
+        ? window.window_minutes
+        : typeof window.limit_window_seconds === 'number'
+            ? Math.round(window.limit_window_seconds / 60)
+            : undefined;
+    const resetsAt = typeof window.resets_at === 'number' || window.resets_at === null
+        ? window.resets_at
+        : window.reset_at;
+    return {
+        used_percent: normalizePercent(window.used_percent),
+        window_minutes: windowMinutes,
+        resets_at: resetsAt,
+    };
+}
+function rateLimitsFromUsagePayload(payload) {
+    if (payload.primary || payload.secondary) {
+        return {
+            limit_id: payload.limit_id ?? 'codex',
+            limit_name: payload.limit_name ?? null,
+            primary: payload.primary,
+            secondary: payload.secondary,
+            credits: normalizeCredits(payload.credits),
+            plan_type: payload.plan_type ?? undefined,
+            rate_limit_reached_type: normalizeRateLimitReachedType(payload.rate_limit_reached_type),
+        };
+    }
+    const preferred = payload.rate_limit;
+    return {
+        limit_id: 'codex',
+        limit_name: null,
+        primary: normalizeApiWindow(preferred?.primary_window),
+        secondary: normalizeApiWindow(preferred?.secondary_window),
+        credits: normalizeCredits(payload.credits),
+        plan_type: payload.plan_type ?? undefined,
+        rate_limit_reached_type: normalizeRateLimitReachedType(payload.rate_limit_reached_type),
+    };
+}
 function quotaFromCodexRateLimits(rateLimits, source = 'session', capturedAt = new Date().toISOString()) {
     const primary = rateLimits?.primary;
     const secondary = rateLimits?.secondary;
@@ -8,10 +155,10 @@ function quotaFromCodexRateLimits(rateLimits, source = 'session', capturedAt = n
         return null;
     return {
         fiveHour: primary
-            ? { utilization: primary.used_percent, resetsAt: new Date(primary.resets_at * 1000).toISOString() }
+            ? { utilization: normalizePercent(primary.used_percent), resetsAt: timestampToIso(primary.resets_at) }
             : { utilization: 0, resetsAt: '' },
         sevenDay: secondary
-            ? { utilization: secondary.used_percent, resetsAt: new Date(secondary.resets_at * 1000).toISOString() }
+            ? { utilization: normalizePercent(secondary.used_percent), resetsAt: timestampToIso(secondary.resets_at) }
             : { utilization: 0, resetsAt: '' },
         available: true,
         providerId: 'codex',
@@ -20,5 +167,267 @@ function quotaFromCodexRateLimits(rateLimits, source = 'session', capturedAt = n
         stale: source === 'cache',
         fiveHourLabel: 'Primary',
         sevenDayLabel: 'Secondary',
+        limitId: rateLimits?.limit_id,
+        limitName: rateLimits?.limit_name ?? undefined,
+        credits: rateLimits?.credits,
+        planType: rateLimits?.plan_type,
+        rateLimitReachedType: rateLimits?.rate_limit_reached_type,
     };
 }
+function readLatestCodexQuotaFromRollouts(sessionPaths, options = {}) {
+    const maxSessionFiles = options.maxSessionFiles ?? DEFAULT_MAX_SESSION_FILES;
+    const maxTailBytes = options.maxTailBytes ?? DEFAULT_TAIL_BYTES;
+    for (const sessionPath of sessionPaths.slice(0, maxSessionFiles)) {
+        const hit = readLatestQuotaFromRollout(sessionPath, maxTailBytes, options.source ?? 'session');
+        if (hit)
+            return hit.quota;
+    }
+    return null;
+}
+function resolveCodexQuotaFromLocalSources(options = {}) {
+    const account = options.activeAccount !== undefined ? options.activeAccount : (0, codexProfiles_1.getActiveCodexAccount)();
+    const readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
+    const writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
+    const maxTailBytes = options.maxTailBytes ?? DEFAULT_TAIL_BYTES;
+    const maxSessionFiles = options.maxSessionFiles ?? DEFAULT_MAX_SESSION_FILES;
+    let ownProvider = false;
+    const provider = options.provider ?? (() => {
+        ownProvider = true;
+        return new codex_1.CodexProvider();
+    })();
+    try {
+        const workspaceSessions = options.workspacePath ? provider.findAllSessions(options.workspacePath) : [];
+        const workspaceQuota = readLatestCodexQuotaFromRollouts(workspaceSessions, { maxTailBytes, maxSessionFiles });
+        if (workspaceQuota) {
+            if (account)
+                writeSnapshot('codex', account.id, workspaceQuota);
+            return enrichCodexQuota(workspaceQuota, account);
+        }
+        const codexHome = options.codexHome ?? (0, codexProfiles_1.resolveSidekickCodexHome)();
+        const accountSessions = findRolloutFiles(path.join(codexHome, 'sessions'));
+        const accountQuota = readLatestCodexQuotaFromRollouts(accountSessions, { maxTailBytes, maxSessionFiles });
+        if (accountQuota) {
+            if (account)
+                writeSnapshot('codex', account.id, accountQuota);
+            return enrichCodexQuota(accountQuota, account);
+        }
+        const cached = account ? readSnapshot('codex', account.id) : null;
+        if (cached) {
+            return enrichCodexQuota({
+                ...cached,
+                providerId: 'codex',
+                source: 'cache',
+                stale: true,
+                fiveHourLabel: cached.fiveHourLabel ?? 'Primary',
+                sevenDayLabel: cached.sevenDayLabel ?? 'Secondary',
+            }, account);
+        }
+    }
+    finally {
+        if (ownProvider)
+            provider.dispose();
+    }
+    return null;
+}
+async function resolveCodexQuota(options = {}) {
+    const source = options.source ?? 'local';
+    const account = options.activeAccount !== undefined ? options.activeAccount : (0, codexProfiles_1.getActiveCodexAccount)();
+    const writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
+    if (source === 'api') {
+        const apiQuota = await fetchCodexQuotaFromApi(options);
+        if (apiQuota.available) {
+            if (account)
+                writeSnapshot('codex', account.id, apiQuota);
+            return enrichCodexQuota(apiQuota, account);
+        }
+        const fallback = resolveCodexQuotaFromLocalSources(options);
+        return fallback ?? enrichCodexQuota(apiQuota, account);
+    }
+    const local = resolveCodexQuotaFromLocalSources(options);
+    if (local)
+        return local;
+    if (source === 'auto') {
+        const apiQuota = await fetchCodexQuotaFromApi(options);
+        if (apiQuota.available && account) {
+            writeSnapshot('codex', account.id, apiQuota);
+        }
+        return enrichCodexQuota(apiQuota, account);
+    }
+    return unavailableCodexQuota(account
+        ? `No Codex rate-limit data is available for "${account.label ?? account.id}".`
+        : 'No Codex rate-limit data is available.', account, { source: 'session' });
+}
+async function fetchCodexQuotaFromApi(options = {}) {
+    const capturedAt = options.capturedAt ?? new Date().toISOString();
+    const accessToken = options.accessToken ?? readCodexAccessToken(options.codexHome ?? (0, codexProfiles_1.resolveSidekickCodexHome)());
+    if (!accessToken) {
+        return {
+            fiveHour: { utilization: 0, resetsAt: '' },
+            sevenDay: { utilization: 0, resetsAt: '' },
+            available: false,
+            error: 'Codex API refresh requires a ChatGPT login.',
+            failureKind: 'auth',
+            providerId: 'codex',
+            source: 'api',
+            capturedAt,
+            fiveHourLabel: 'Primary',
+            sevenDayLabel: 'Secondary',
+        };
+    }
+    try {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const response = await fetchImpl(options.usageUrl ?? CHATGPT_USAGE_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return {
+                fiveHour: { utilization: 0, resetsAt: '' },
+                sevenDay: { utilization: 0, resetsAt: '' },
+                available: false,
+                error: `Codex usage API error: ${response.status}`,
+                failureKind: response.status === 401 || response.status === 403
+                    ? 'auth'
+                    : response.status === 429
+                        ? 'rate_limit'
+                        : response.status >= 500 && response.status <= 599
+                            ? 'server'
+                            : 'unknown',
+                httpStatus: response.status,
+                retryAfterMs: response.status === 429 ? parseRetryAfterMs(response.headers.get('retry-after')) : undefined,
+                providerId: 'codex',
+                source: 'api',
+                capturedAt,
+                fiveHourLabel: 'Primary',
+                sevenDayLabel: 'Secondary',
+            };
+        }
+        const payload = await response.json();
+        const quota = quotaFromCodexRateLimits(rateLimitsFromUsagePayload(payload), 'api', capturedAt);
+        if (!quota) {
+            return {
+                fiveHour: { utilization: 0, resetsAt: '' },
+                sevenDay: { utilization: 0, resetsAt: '' },
+                available: false,
+                error: 'Codex usage API returned no rate-limit windows.',
+                failureKind: 'unknown',
+                providerId: 'codex',
+                source: 'api',
+                capturedAt,
+                fiveHourLabel: 'Primary',
+                sevenDayLabel: 'Secondary',
+            };
+        }
+        return quota;
+    }
+    catch {
+        return {
+            fiveHour: { utilization: 0, resetsAt: '' },
+            sevenDay: { utilization: 0, resetsAt: '' },
+            available: false,
+            error: 'Codex usage API network error',
+            failureKind: 'network',
+            providerId: 'codex',
+            source: 'api',
+            capturedAt,
+            fiveHourLabel: 'Primary',
+            sevenDayLabel: 'Secondary',
+        };
+    }
+}
+function readCodexAccessToken(codexHome) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(codexHome, 'auth.json'), 'utf8'));
+        if (parsed.OPENAI_API_KEY || parsed.auth_mode === 'api_key')
+            return null;
+        return parsed.tokens?.access_token || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLatestQuotaFromRollout(sessionPath, maxTailBytes, source) {
+    let fd = null;
+    try {
+        const stat = fs.statSync(sessionPath);
+        if (!stat.isFile() || stat.size <= 0)
+            return null;
+        const start = Math.max(0, stat.size - maxTailBytes);
+        const bytesToRead = stat.size - start;
+        const buffer = Buffer.alloc(bytesToRead);
+        fd = fs.openSync(sessionPath, 'r');
+        const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, start);
+        fs.closeSync(fd);
+        fd = null;
+        let text = buffer.toString('utf8', 0, bytesRead);
+        if (start > 0) {
+            const firstNewline = text.indexOf('\n');
+            text = firstNewline >= 0 ? text.slice(firstNewline + 1) : '';
+        }
+        const lines = text.split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (!line || !line.includes('rate_limits'))
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.type !== 'event_msg' || parsed.payload?.type !== 'token_count')
+                    continue;
+                const quota = quotaFromCodexRateLimits(parsed.payload.rate_limits, source, parsed.timestamp ?? new Date(stat.mtime).toISOString());
+                if (quota)
+                    return { quota, filePath: sessionPath };
+            }
+            catch {
+                // Ignore malformed or partial lines.
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return null;
+}
+function findRolloutFiles(sessionsDir) {
+    const results = [];
+    function visit(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(fullPath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.startsWith('rollout-') || !entry.name.endsWith('.jsonl'))
+                continue;
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.size > 0) {
+                    results.push({ path: fullPath, mtime: stat.mtime.getTime() });
+                }
+            }
+            catch {
+                // Skip inaccessible files.
+            }
+        }
+    }
+    visit(sessionsDir);
+    results.sort((a, b) => b.mtime - a.mtime);
+    return results.map(item => item.path);
+}

package/dist/codexQuotaWatcher.d.ts

@@ -11,6 +11,8 @@ type SnapshotWriter = (providerId: 'codex', accountId: string, quota: QuotaState
 type WatchFile = (filename: fs.PathLike, listener: fs.WatchListener<string>) => FSWatcher;
 export interface CodexQuotaWatcherOptions {
     discoveryPollIntervalMs?: number;
+    maxTailBytes?: number;
+    maxSessionFiles?: number;
     providerFactory?: () => CodexProvider;
     getActiveAccount?: CodexAccountReader;
     readSnapshot?: SnapshotReader;
@@ -29,6 +31,8 @@ export declare class CodexQuotaWatcher implements Disposable {
     private readonly readSnapshot;
     private readonly writeSnapshot;
     private readonly watchFile;
+    private readonly maxTailBytes;
+    private readonly maxSessionFiles;
     private readonly listeners;
     private discoveryTimer;
     private provider;

package/dist/codexQuotaWatcher.js

@@ -78,6 +78,8 @@ class CodexQuotaWatcher {
     readSnapshot;
     writeSnapshot;
     watchFile;
+    maxTailBytes;
+    maxSessionFiles;
     listeners = [];
     discoveryTimer;
     provider = null;
@@ -94,6 +96,8 @@ class CodexQuotaWatcher {
         this.readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
         this.writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
         this.watchFile = options.watchFile ?? fs.watch;
+        this.maxTailBytes = options.maxTailBytes;
+        this.maxSessionFiles = options.maxSessionFiles;
     }
     start() {
         if (this.running)
@@ -201,6 +205,29 @@ class CodexQuotaWatcher {
     }
     emitCachedOrUnavailable() {
         const account = this.getActiveAccount();
+        let localProvider = null;
+        try {
+            localProvider = this.providerFactory();
+            const local = (0, codexQuota_1.resolveCodexQuotaFromLocalSources)({
+                workspacePath: this.workspacePath,
+                activeAccount: account,
+                readSnapshot: this.readSnapshot,
+                writeSnapshot: this.writeSnapshot,
+                provider: localProvider,
+                maxTailBytes: this.maxTailBytes,
+                maxSessionFiles: this.maxSessionFiles,
+            });
+            if (local) {
+                this.emitState(local);
+                return;
+            }
+        }
+        catch {
+            // Fall through to account-scoped cache or unavailable state.
+        }
+        finally {
+            localProvider?.dispose();
+        }
         const cached = account ? this.readSnapshot('codex', account.id) : null;
         if (cached) {
             this.emitState(enrichQuotaState({

package/dist/formatters/sessionDump.js

@@ -15,6 +15,7 @@ exports.fmtTokens = fmtTokens;
 exports.fmtCost = fmtCost;
 exports.formatTimestamp = formatTimestamp;
 exports.formatDuration = formatDuration;
+const formatting_1 = require("../formatting");
 // ── JSON output ──
 /**
  * Serialize aggregated metrics as pretty-printed JSON.
@@ -238,11 +239,7 @@ function formatTokenSummary(metrics) {
 }
 /** @internal Exported for tests. */
 function fmtTokens(n) {
-    if (n >= 1_000_000)
-        return `${(n / 1_000_000).toFixed(1)}M`;
-    if (n >= 1_000)
-        return `${(n / 1_000).toFixed(1)}k`;
-    return String(n);
+    return (0, formatting_1.formatTokenCount)(n);
 }
 /** @internal Exported for tests. */
 function fmtCost(cost) {
@@ -273,17 +270,7 @@ function formatDuration(start, end) {
         return 'N/A';
     try {
         const ms = new Date(end).getTime() - new Date(start).getTime();
-        if (ms < 0)
-            return 'N/A';
-        const totalSec = Math.floor(ms / 1000);
-        const hours = Math.floor(totalSec / 3600);
-        const minutes = Math.floor((totalSec % 3600) / 60);
-        const seconds = totalSec % 60;
-        if (hours > 0)
-            return `${hours}h ${minutes}m ${seconds}s`;
-        if (minutes > 0)
-            return `${minutes}m ${seconds}s`;
-        return `${seconds}s`;
+        return (0, formatting_1.formatDurationMs)(ms);
     }
     catch {
         return 'N/A';

package/dist/formatting.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pure display formatting helpers shared by CLI, extension host, webviews,
+ * and downstream apps.
+ *
+ * This module intentionally has no Node-only imports.
+ *
+ * @module formatting
+ */
+export interface FormatTokenCountOptions {
+    /** Suffix casing for thousands. Millions always use `M`. Defaults to `lower`. */
+    suffixCase?: 'lower' | 'upper';
+}
+export interface FormatDurationMsOptions {
+    /** `spaced`: `5m 30s`; `compact`: `5m30s`. Defaults to `spaced`. */
+    style?: 'spaced' | 'compact';
+    /** Render sub-second durations as `123ms` instead of `0.1s`. Defaults to false. */
+    includeMilliseconds?: boolean;
+    /** Decimal places for durations under one minute. Defaults to 0. */
+    secondsFractionDigits?: number;
+    /** Value to return for negative, non-finite, or otherwise invalid durations. */
+    invalid?: string;
+}
+/** Format a token count with compact `k` / `M` suffixes. */
+export declare function formatTokenCount(value: number, options?: FormatTokenCountOptions): string;
+/** Format an elapsed duration in milliseconds. */
+export declare function formatDurationMs(ms: number, options?: FormatDurationMsOptions): string;

package/dist/formatting.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Pure display formatting helpers shared by CLI, extension host, webviews,
+ * and downstream apps.
+ *
+ * This module intentionally has no Node-only imports.
+ *
+ * @module formatting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTokenCount = formatTokenCount;
+exports.formatDurationMs = formatDurationMs;
+/** Format a token count with compact `k` / `M` suffixes. */
+function formatTokenCount(value, options = {}) {
+    if (!Number.isFinite(value))
+        return '0';
+    const n = Math.trunc(value);
+    const sign = n < 0 ? '-' : '';
+    const abs = Math.abs(n);
+    const thousandsSuffix = options.suffixCase === 'upper' ? 'K' : 'k';
+    if (abs >= 1_000_000)
+        return `${sign}${(abs / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${sign}${(abs / 1_000).toFixed(1)}${thousandsSuffix}`;
+    return `${n}`;
+}
+/** Format an elapsed duration in milliseconds. */
+function formatDurationMs(ms, options = {}) {
+    const invalid = options.invalid ?? 'N/A';
+    if (!Number.isFinite(ms) || ms < 0)
+        return invalid;
+    const style = options.style ?? 'spaced';
+    const separator = style === 'compact' ? '' : ' ';
+    const secondsFractionDigits = options.secondsFractionDigits ?? 0;
+    if (ms < 1000) {
+        if (options.includeMilliseconds)
+            return `${Math.round(ms)}ms`;
+        return `${(ms / 1000).toFixed(Math.max(1, secondsFractionDigits))}s`;
+    }
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        if (secondsFractionDigits > 0)
+            return `${seconds.toFixed(secondsFractionDigits)}s`;
+        return `${Math.floor(seconds)}s`;
+    }
+    const totalSeconds = Math.floor(seconds);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const remainingSeconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}h${separator}${minutes}m${separator}${remainingSeconds}s`;
+    }
+    return `${minutes}m${separator}${remainingSeconds}s`;
+}

package/dist/index.d.ts

@@ -58,6 +58,10 @@ export type { FollowEvent, FollowEventType, SessionWatcher, SessionWatcherCallba
 export { createWatcher } from './watchers/factory';
 export type { CreateWatcherOptions } from './watchers/factory';
 export { toFollowEvents } from './watchers/eventBridge';
+export { createJsonlTail } from './watchers/jsonlTail';
+export type { JsonlTail, JsonlTailBatch, JsonlTailOptions } from './watchers/jsonlTail';
+export { formatDurationMs, formatTokenCount } from './formatting';
+export type { FormatDurationMsOptions, FormatTokenCountOptions } from './formatting';
 export { formatToolSummary } from './formatters/toolSummary';
 export { isHardNoise, isHardNoiseFollowEvent, getSoftNoiseReason, classifyMessage, classifyFollowEvent, shouldMergeWithPrevious, classifyNoise, } from './formatters/noiseClassifier';
 export type { MessageClassification, NoiseResult } from './formatters/noiseClassifier';
@@ -100,7 +104,8 @@ export type { QuotaFailureDescriptor } from './quotaPresentation';
 export { QuotaPoller } from './quotaPoller';
 export type { QuotaPollerOptions } from './quotaPoller';
 export { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
-export { quotaFromCodexRateLimits } from './codexQuota';
+export { fetchCodexQuotaFromApi, quotaFromCodexRateLimits, readLatestCodexQuotaFromRollouts, resolveCodexQuota, resolveCodexQuotaFromLocalSources, } from './codexQuota';
+export type { CodexQuotaApiOptions, CodexQuotaCreditsSnapshot, CodexQuotaResolveOptions, CodexQuotaResolveSource, } from './codexQuota';
 export { CodexQuotaWatcher } from './codexQuotaWatcher';
 export type { CodexQuotaWatcherOptions } from './codexQuotaWatcher';
 export { MultiProviderQuotaService } from './multiProviderQuotaService';

package/dist/index.js

@@ -4,9 +4,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findActiveClaudeSession = exports.discoverSessionDirectory = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.detectSessionActivity = exports.extractTaskInfo = exports.scanSubagentDir = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.CodexRolloutParser = exports.parseDbPartData = exports.parseDbMessageData = exports.convertOpenCodeMessage = exports.detectPlanModeFromText = exports.normalizeToolInput = exports.normalizeToolName = exports.TRUNCATION_PATTERNS = exports.JsonlParser = exports.CodexProvider = exports.OpenCodeProvider = exports.ClaudeCodeProvider = exports.getAllDetectedProviders = exports.detectProvider = exports.readClaudeCodePlanFiles = exports.getPlanAnalytics = exports.writePlans = exports.getLatestPlan = exports.readPlans = exports.readLatestHandoff = exports.readHistory = exports.readNotes = exports.readDecisions = exports.readTasks = exports.getProjectSlugRaw = exports.getProjectSlug = exports.encodeWorkspacePath = exports.getGlobalDataPath = exports.getProjectDataPath = exports.getConfigDir = exports.MAX_PLANS_PER_PROJECT = exports.PLAN_SCHEMA_VERSION = exports.createEmptyTokenTotals = exports.HISTORICAL_DATA_SCHEMA_VERSION = exports.STALENESS_THRESHOLDS = exports.IMPORTANCE_DECAY_FACTORS = exports.KNOWLEDGE_NOTE_SCHEMA_VERSION = exports.DECISION_LOG_SCHEMA_VERSION = exports.normalizeTaskStatus = exports.TASK_PERSISTENCE_SCHEMA_VERSION = void 0;
-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 = 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.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = 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 = void 0;
-exports.getModelContextWindowSize = exports.MultiProviderQuotaService = exports.CodexQuotaWatcher = exports.quotaFromCodexRateLimits = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.fetchQuota = 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.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = exports.HeatmapTracker = void 0;
-exports.fetchPeakHoursStatus = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = 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 = void 0;
+exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.PHRASE_CATEGORIES = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = 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.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 = void 0;
+exports.fetchCodexQuotaFromApi = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.fetchQuota = 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.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = void 0;
+exports.fetchPeakHoursStatus = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = 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.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = 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; } });
@@ -130,7 +130,12 @@ var factory_1 = require("./watchers/factory");
 Object.defineProperty(exports, "createWatcher", { enumerable: true, get: function () { return factory_1.createWatcher; } });
 var eventBridge_1 = require("./watchers/eventBridge");
 Object.defineProperty(exports, "toFollowEvents", { enumerable: true, get: function () { return eventBridge_1.toFollowEvents; } });
+var jsonlTail_1 = require("./watchers/jsonlTail");
+Object.defineProperty(exports, "createJsonlTail", { enumerable: true, get: function () { return jsonlTail_1.createJsonlTail; } });
 // Formatters
+var formatting_1 = require("./formatting");
+Object.defineProperty(exports, "formatDurationMs", { enumerable: true, get: function () { return formatting_1.formatDurationMs; } });
+Object.defineProperty(exports, "formatTokenCount", { enumerable: true, get: function () { return formatting_1.formatTokenCount; } });
 var toolSummary_1 = require("./formatters/toolSummary");
 Object.defineProperty(exports, "formatToolSummary", { enumerable: true, get: function () { return toolSummary_1.formatToolSummary; } });
 var noiseClassifier_1 = require("./formatters/noiseClassifier");
@@ -233,7 +238,11 @@ var quotaSnapshots_1 = require("./quotaSnapshots");
 Object.defineProperty(exports, "readQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.readQuotaSnapshot; } });
 Object.defineProperty(exports, "writeQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.writeQuotaSnapshot; } });
 var codexQuota_1 = require("./codexQuota");
+Object.defineProperty(exports, "fetchCodexQuotaFromApi", { enumerable: true, get: function () { return codexQuota_1.fetchCodexQuotaFromApi; } });
 Object.defineProperty(exports, "quotaFromCodexRateLimits", { enumerable: true, get: function () { return codexQuota_1.quotaFromCodexRateLimits; } });
+Object.defineProperty(exports, "readLatestCodexQuotaFromRollouts", { enumerable: true, get: function () { return codexQuota_1.readLatestCodexQuotaFromRollouts; } });
+Object.defineProperty(exports, "resolveCodexQuota", { enumerable: true, get: function () { return codexQuota_1.resolveCodexQuota; } });
+Object.defineProperty(exports, "resolveCodexQuotaFromLocalSources", { enumerable: true, get: function () { return codexQuota_1.resolveCodexQuotaFromLocalSources; } });
 var codexQuotaWatcher_1 = require("./codexQuotaWatcher");
 Object.defineProperty(exports, "CodexQuotaWatcher", { enumerable: true, get: function () { return codexQuotaWatcher_1.CodexQuotaWatcher; } });
 var multiProviderQuotaService_1 = require("./multiProviderQuotaService");

package/dist/providers/codexDatabase.js

@@ -45,7 +45,7 @@ class CodexDatabase {
     dbPath;
     sqlite3Available = null;
     constructor(codexHome) {
-        this.dbPath = path.join(codexHome, 'state.sqlite');
+        this.dbPath = findLatestStateDatabase(codexHome) ?? path.join(codexHome, 'state.sqlite');
     }
     isAvailable() {
         try {
@@ -138,6 +138,31 @@ class CodexDatabase {
     }
 }
 exports.CodexDatabase = CodexDatabase;
+function findLatestStateDatabase(codexHome) {
+    try {
+        const entries = fs.readdirSync(codexHome, { withFileTypes: true });
+        const candidates = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^state(?:_\d+)?\.sqlite$/.test(entry.name))
+                continue;
+            const dbPath = path.join(codexHome, entry.name);
+            try {
+                const stat = fs.statSync(dbPath);
+                if (stat.size > 0) {
+                    candidates.push({ path: dbPath, mtime: stat.mtime.getTime() });
+                }
+            }
+            catch {
+                // Skip inaccessible candidates.
+            }
+        }
+        candidates.sort((a, b) => b.mtime - a.mtime);
+        return candidates[0]?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function normalizePath(input) {
     try {
         return fs.realpathSync(input);

package/dist/providers/detect.js

@@ -58,6 +58,35 @@ function getOpenCodeDataDir() {
 function getCodexHomes() {
     return (0, codexProfiles_1.getCodexMonitoringHomes)();
 }
+function hasCodexStateDb(codexHome) {
+    try {
+        return fs.readdirSync(codexHome).some(entry => /^state(?:_\d+)?\.sqlite$/.test(entry));
+    }
+    catch {
+        return false;
+    }
+}
+function getCodexStateDbMtime(codexHome) {
+    try {
+        let latest = 0;
+        for (const entry of fs.readdirSync(codexHome)) {
+            if (!/^state(?:_\d+)?\.sqlite$/.test(entry))
+                continue;
+            try {
+                const mtime = fs.statSync(path.join(codexHome, entry)).mtime.getTime();
+                if (mtime > latest)
+                    latest = mtime;
+            }
+            catch {
+                // Skip inaccessible files.
+            }
+        }
+        return latest;
+    }
+    catch {
+        return 0;
+    }
+}
 function getMostRecentMtime(dir) {
     try {
         if (!fs.existsSync(dir))
@@ -97,13 +126,9 @@ function getOpenCodeActivityMtime() {
 function getCodexActivityMtime() {
     let latest = 0;
     for (const codexHome of getCodexHomes()) {
-        const dbPath = path.join(codexHome, 'state.sqlite');
-        try {
-            const dbMtime = fs.statSync(dbPath).mtime.getTime();
-            if (dbMtime > latest)
-                latest = dbMtime;
-        }
-        catch { /* no DB */ }
+        const dbMtime = getCodexStateDbMtime(codexHome);
+        if (dbMtime > latest)
+            latest = dbMtime;
         const sessionsMtime = getMostRecentMtime(path.join(codexHome, 'sessions'));
         if (sessionsMtime > latest)
             latest = sessionsMtime;
@@ -129,7 +154,7 @@ function getAllDetectedProviders() {
     const { claudeBase, openCodeDbPath, openCodeStorageDir, codexHomes } = getProviderPaths();
     const hasClaude = fs.existsSync(claudeBase);
     const hasOpenCode = fs.existsSync(openCodeStorageDir) || fs.existsSync(openCodeDbPath);
-    const hasCodex = codexHomes.some(codexHome => fs.existsSync(path.join(codexHome, 'sessions')) || fs.existsSync(path.join(codexHome, 'state.sqlite')));
+    const hasCodex = codexHomes.some(codexHome => fs.existsSync(path.join(codexHome, 'sessions')) || hasCodexStateDb(codexHome));
     const available = [];
     if (hasClaude)
         available.push({ id: 'claude-code', mtime: getMostRecentMtime(claudeBase) });
@@ -150,7 +175,7 @@ function detectProvider(override) {
     const { claudeBase, openCodeDbPath, openCodeStorageDir, codexHomes } = getProviderPaths();
     const hasClaude = fs.existsSync(claudeBase);
     const hasOpenCode = fs.existsSync(openCodeStorageDir) || fs.existsSync(openCodeDbPath);
-    const hasCodex = codexHomes.some(codexHome => fs.existsSync(path.join(codexHome, 'sessions')) || fs.existsSync(path.join(codexHome, 'state.sqlite')));
+    const hasCodex = codexHomes.some(codexHome => fs.existsSync(path.join(codexHome, 'sessions')) || hasCodexStateDb(codexHome));
     const available = [];
     if (hasClaude) {
         available.push({ id: 'claude-code', mtime: getMostRecentMtime(claudeBase) });

package/dist/quota.d.ts

@@ -39,6 +39,16 @@ export interface QuotaState {
     fiveHourLabel?: string;
     /** Provider-specific display label for the second window */
     sevenDayLabel?: string;
+    /** Provider-specific rate-limit identifier */
+    limitId?: string;
+    /** Provider-specific rate-limit display name */
+    limitName?: string;
+    /** Provider-specific credits snapshot */
+    credits?: unknown;
+    /** Provider-specific plan type */
+    planType?: string;
+    /** Provider-specific rate-limit reached reason */
+    rateLimitReachedType?: string;
 }
 /**
  * Fetch current quota utilization from the Anthropic OAuth usage API.

package/dist/types/codex.d.ts

@@ -180,14 +180,17 @@ export interface CodexRateLimits {
     limit_name?: string | null;
     primary?: {
         used_percent: number;
-        window_minutes: number;
-        resets_at: number;
+        window_minutes?: number | null;
+        resets_at?: number | null;
     };
     secondary?: {
         used_percent: number;
-        window_minutes: number;
-        resets_at: number;
+        window_minutes?: number | null;
+        resets_at?: number | null;
     };
+    credits?: unknown;
+    plan_type?: string;
+    rate_limit_reached_type?: string;
 }
 export interface CodexTokenUsage {
     input_tokens: number;

package/dist/watchers/jsonlTail.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Low-level JSONL tail reader for consumers that need raw parsed events plus
+ * their own aggregation lifecycle.
+ */
+import type { ZodType } from 'zod';
+export interface JsonlTailBatch {
+    bytesRead: number;
+    eventsRead: number;
+    offset: number;
+}
+export interface JsonlTailOptions<T> {
+    path: string;
+    schema?: ZodType<T>;
+    startOffset?: number;
+    startAtEnd?: boolean;
+    debounceMs?: number;
+    catchupIntervalMs?: number;
+    onEvent: (event: T) => void;
+    onBatchComplete?: (batch: JsonlTailBatch) => void;
+    onError?: (error: Error, line?: string) => void;
+}
+export interface JsonlTail {
+    readonly isActive: boolean;
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    readNow(): void;
+    getOffset(): number;
+    seekTo(offset: number): void;
+}
+export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail;

package/dist/watchers/jsonlTail.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Low-level JSONL tail reader for consumers that need raw parsed events plus
+ * their own aggregation lifecycle.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJsonlTail = createJsonlTail;
+const fs = __importStar(require("fs"));
+const jsonl_1 = require("../parsers/jsonl");
+const DEFAULT_DEBOUNCE_MS = 100;
+const DEFAULT_CATCHUP_INTERVAL_MS = 30_000;
+function createJsonlTail(options) {
+    return new JsonlTailReader(options);
+}
+class JsonlTailReader {
+    options;
+    active = false;
+    offset;
+    fsWatcher = null;
+    debounceTimer = null;
+    catchupTimer = null;
+    eventsInCurrentBatch = 0;
+    parser;
+    constructor(options) {
+        this.options = options;
+        this.offset = options.startOffset ?? 0;
+        this.parser = new jsonl_1.JsonlParser({
+            onEvent: (event) => {
+                this.eventsInCurrentBatch += 1;
+                this.options.onEvent(event);
+            },
+            onError: (error, line) => this.options.onError?.(error, line),
+        }, { schema: options.schema });
+    }
+    get isActive() {
+        return this.active;
+    }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        if (this.options.startAtEnd && this.options.startOffset === undefined) {
+            try {
+                this.offset = fs.statSync(this.options.path).size;
+            }
+            catch {
+                this.offset = 0;
+            }
+        }
+        this.readNow();
+        this.watchFile();
+        const catchupIntervalMs = this.options.catchupIntervalMs ?? DEFAULT_CATCHUP_INTERVAL_MS;
+        if (catchupIntervalMs > 0) {
+            this.catchupTimer = setInterval(() => this.readNow(), catchupIntervalMs);
+        }
+    }
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.fsWatcher) {
+            this.fsWatcher.close();
+            this.fsWatcher = null;
+        }
+        if (this.catchupTimer) {
+            clearInterval(this.catchupTimer);
+            this.catchupTimer = null;
+        }
+        this.parser.flush();
+    }
+    dispose() {
+        this.stop();
+    }
+    readNow() {
+        let fd = null;
+        try {
+            const stat = fs.statSync(this.options.path);
+            if (stat.size < this.offset) {
+                this.offset = 0;
+                this.parser.reset();
+            }
+            if (stat.size <= this.offset)
+                return;
+            const bytesToRead = stat.size - this.offset;
+            const buffer = Buffer.alloc(bytesToRead);
+            fd = fs.openSync(this.options.path, 'r');
+            const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, this.offset);
+            fs.closeSync(fd);
+            fd = null;
+            if (bytesRead <= 0)
+                return;
+            this.offset += bytesRead;
+            this.eventsInCurrentBatch = 0;
+            this.parser.processChunk(buffer.toString('utf-8', 0, bytesRead));
+            this.options.onBatchComplete?.({
+                bytesRead,
+                eventsRead: this.eventsInCurrentBatch,
+                offset: this.offset,
+            });
+        }
+        catch (error) {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* ignore close errors */ }
+            }
+            this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    getOffset() {
+        return this.offset;
+    }
+    seekTo(offset) {
+        this.offset = Math.max(0, offset);
+        this.parser.reset();
+    }
+    watchFile() {
+        try {
+            this.fsWatcher = fs.watch(this.options.path, { persistent: false }, () => {
+                this.debouncedRead();
+            });
+            this.fsWatcher.on('error', (error) => this.options.onError?.(error));
+        }
+        catch {
+            // Polling still covers filesystems where fs.watch is unavailable.
+        }
+    }
+    debouncedRead() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        const debounceMs = this.options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.debounceTimer = setTimeout(() => this.readNow(), debounceMs);
+    }
+}

package/dist/watchers/jsonlWatcher.js

@@ -398,13 +398,17 @@ class JsonlSessionWatcher {
             if (evtType === 'token_count') {
                 const info = payload?.info;
                 const usage = (info?.last_token_usage || info?.total_token_usage);
-                if (usage) {
-                    const rl = payload?.rate_limits;
-                    const rateLimits = rl ? extractRateLimits(rl) : undefined;
+                const rl = payload?.rate_limits;
+                const rateLimits = rl ? extractRateLimits(rl) : undefined;
+                if (usage || rateLimits) {
                     events.push({
                         providerId: 'codex', type: 'system', timestamp: ts,
-                        summary: `Tokens: ${usage.input_tokens ?? 0} in / ${usage.output_tokens ?? 0} out`,
-                        tokens: { input: usage.input_tokens || 0, output: usage.output_tokens || 0 },
+                        summary: usage
+                            ? `Tokens: ${usage.input_tokens ?? 0} in / ${usage.output_tokens ?? 0} out`
+                            : 'Rate limits updated',
+                        tokens: usage
+                            ? { input: usage.input_tokens || 0, output: usage.output_tokens || 0 }
+                            : undefined,
                         rateLimits,
                         raw,
                     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,6 +29,10 @@
       "types": "./dist/modelInfo.d.ts",
       "default": "./dist/modelInfo.js"
     },
+    "./formatting": {
+      "types": "./dist/formatting.d.ts",
+      "default": "./dist/formatting.js"
+    },
     "./dist/*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"