tide-commander 1.149.0 → 1.150.0

package/dist/src/packages/server/opencode/json-event-parser.js

@@ -1,6 +1,16 @@
 /**
  * OpenCode JSON Event Parser
- * Maps OpenCode NDJSON events to StandardEvent format
+ * Maps OpenCode NDJSON events to StandardEvent format.
+ *
+ * Streaming model (mirrors Claude/Grok):
+ *  - `message.part.delta` → append delta with isStreaming:true + stable partID uuid
+ *  - progressive `text` / `reasoning` snapshots (same part.id, growing text) →
+ *    emit only the new suffix as a streaming chunk
+ *  - final text (part.time.end set, or step_finish) → isStreaming:false same uuid
+ *
+ * Note: current `opencode run --format json` often emits a single complete `text`
+ * event per turn (no token deltas). This parser still assigns stable uuids and is
+ * ready for delta / progressive events when the CLI surfaces them.
  */
 import { createLogger } from '../utils/logger.js';
 const log = createLogger('OpencodeParser');
@@ -34,6 +44,12 @@ export class OpencodeJsonEventParser {
     textEventEmittedInTurn = false;
     lastThinkingContent;
     thinkingEventEmittedInTurn = false;
+    /** Full text seen so far per part id — used to derive deltas from snapshots. */
+    streamedTextByPart = new Map();
+    streamedThinkingByPart = new Map();
+    /** Open text/thinking stream uuids awaiting isStreaming:false finalize. */
+    openTextStreamUuids = new Set();
+    openThinkingStreamUuids = new Set();
     parseEvent(rawEvent) {
         const event = rawEvent;
         if (!event || typeof event !== 'object' || !event.type) {
@@ -51,42 +67,166 @@ export class OpencodeJsonEventParser {
                 return this.parseToolUse(event);
             case 'step_finish':
                 return this.parseStepFinish(event);
+            // Server/SDK event names — surface token deltas when present.
+            case 'message.part.delta':
+                return this.parseMessagePartDelta(event);
+            case 'message.part.updated':
+                return this.parseMessagePartUpdated(event);
             default:
                 log.log(`parseEvent: unknown event type '${event.type}' - skipping`);
                 return [];
         }
     }
     parseStepStart(event) {
+        // New step — allow streams again.
+        this.openTextStreamUuids.clear();
+        this.openThinkingStreamUuids.clear();
+        this.streamedTextByPart.clear();
+        this.streamedThinkingByPart.clear();
         return [{
                 type: 'init',
                 sessionId: event.sessionID,
             }];
     }
-    parseText(event) {
-        const text = event.part?.text;
-        if (!text)
+    streamUuid(kind, partId, messageId) {
+        if (partId)
+            return `opencode-${kind}-${partId}`;
+        if (messageId)
+            return `opencode-${kind}-msg-${messageId}`;
+        return `opencode-${kind}-anon`;
+    }
+    /**
+     * Emit streaming text from a full snapshot: only the new suffix is sent as a
+     * delta so the client can append. Returns [] when the snapshot is unchanged.
+     */
+    emitProgressive(kind, fullText, partId, messageId, isFinal) {
+        const map = kind === 'text' ? this.streamedTextByPart : this.streamedThinkingByPart;
+        const openSet = kind === 'text' ? this.openTextStreamUuids : this.openThinkingStreamUuids;
+        const key = partId || messageId || 'anon';
+        const prev = map.get(key) || '';
+        const uuid = this.streamUuid(kind, partId, messageId);
+        if (kind === 'text') {
+            this.lastTextContent = fullText;
+            this.textEventEmittedInTurn = true;
+        }
+        else {
+            this.lastThinkingContent = fullText;
+            this.thinkingEventEmittedInTurn = true;
+        }
+        // Unchanged snapshot (common re-broadcast) — only finalize if needed.
+        if (fullText === prev) {
+            if (isFinal && openSet.has(uuid)) {
+                openSet.delete(uuid);
+                return [{
+                        type: kind === 'text' ? 'text' : 'thinking',
+                        text: fullText,
+                        isStreaming: false,
+                        uuid,
+                    }];
+            }
             return [];
-        // Track last text for resultText in step_complete (boss delegation parsing)
-        this.lastTextContent = text;
-        this.textEventEmittedInTurn = true;
+        }
+        map.set(key, fullText);
+        // Growing prefix → emit suffix as streaming chunk.
+        if (fullText.startsWith(prev) && !isFinal) {
+            const delta = fullText.slice(prev.length);
+            if (!delta)
+                return [];
+            openSet.add(uuid);
+            return [{
+                    type: kind === 'text' ? 'text' : 'thinking',
+                    text: delta,
+                    isStreaming: true,
+                    uuid,
+                }];
+        }
+        // Non-prefix rewrite or final: replace with full text.
+        if (isFinal) {
+            openSet.delete(uuid);
+            return [{
+                    type: kind === 'text' ? 'text' : 'thinking',
+                    text: fullText,
+                    isStreaming: false,
+                    uuid,
+                }];
+        }
+        openSet.add(uuid);
+        // Client merge appends when isStreaming; for rewrites send full text with
+        // isStreaming:false then... no, that finalizes early. Prefer replace path:
+        // emit as streaming full text only if prev empty; else finalize+restart.
+        if (!prev) {
+            return [{
+                    type: kind === 'text' ? 'text' : 'thinking',
+                    text: fullText,
+                    isStreaming: true,
+                    uuid,
+                }];
+        }
+        // Rare rewrite: finalize with new full content.
+        openSet.delete(uuid);
         return [{
-                type: 'text',
-                text,
+                type: kind === 'text' ? 'text' : 'thinking',
+                text: fullText,
                 isStreaming: false,
+                uuid,
             }];
     }
+    parseText(event) {
+        const part = event.part;
+        const text = part?.text;
+        if (!text)
+            return [];
+        // CLI format marks completion with time.end; absence → treat as progressive.
+        const isFinal = typeof part?.time?.end === 'number';
+        return this.emitProgressive('text', text, part?.id, part?.messageID, isFinal);
+    }
     parseReasoning(event) {
-        const text = event.part?.text;
+        const part = event.part;
+        const text = part?.text;
         if (!text)
             return [];
-        this.lastThinkingContent = text;
-        this.thinkingEventEmittedInTurn = true;
+        const isFinal = typeof part?.time?.end === 'number';
+        return this.emitProgressive('thinking', text, part?.id, part?.messageID, isFinal);
+    }
+    parseMessagePartDelta(event) {
+        const props = event.properties || {};
+        const delta = props.delta ?? event.part?.delta;
+        const field = props.field || event.part?.field || 'text';
+        const partId = props.partID || event.part?.id;
+        const messageId = props.messageID || event.part?.messageID;
+        if (typeof delta !== 'string' || !delta)
+            return [];
+        const kind = field === 'reasoning' || field === 'thinking' ? 'thinking' : 'text';
+        const map = kind === 'text' ? this.streamedTextByPart : this.streamedThinkingByPart;
+        const openSet = kind === 'text' ? this.openTextStreamUuids : this.openThinkingStreamUuids;
+        const key = partId || messageId || 'anon';
+        const next = (map.get(key) || '') + delta;
+        map.set(key, next);
+        if (kind === 'text') {
+            this.lastTextContent = next;
+            this.textEventEmittedInTurn = true;
+        }
+        else {
+            this.lastThinkingContent = next;
+            this.thinkingEventEmittedInTurn = true;
+        }
+        const uuid = this.streamUuid(kind, partId, messageId);
+        openSet.add(uuid);
         return [{
-                type: 'thinking',
-                text,
-                isStreaming: false,
+                type: kind === 'text' ? 'text' : 'thinking',
+                text: delta,
+                isStreaming: true,
+                uuid,
             }];
     }
+    parseMessagePartUpdated(event) {
+        const part = event.properties?.part || event.part;
+        if (!part?.text)
+            return [];
+        const kind = part.type === 'reasoning' || part.type === 'thinking' ? 'thinking' : 'text';
+        const isFinal = typeof part.time?.end === 'number';
+        return this.emitProgressive(kind, part.text, part.id, part.messageID, isFinal);
+    }
     parseToolUse(event) {
         const part = event.part;
         if (!part)
@@ -103,6 +243,7 @@ export class OpencodeJsonEventParser {
         };
         if (callId) {
             toolStart.toolUseId = callId;
+            toolStart.uuid = callId;
         }
         events.push(toolStart);
         // Emit tool_result if state is present (completed tool)
@@ -114,6 +255,7 @@ export class OpencodeJsonEventParser {
             };
             if (callId) {
                 toolResult.toolUseId = callId;
+                toolResult.uuid = callId;
             }
             events.push(toolResult);
         }
@@ -125,6 +267,31 @@ export class OpencodeJsonEventParser {
             return [];
         const events = [];
         const tokens = part.tokens;
+        // Finalize any open streaming rows so the UI stops the "live" cursor.
+        for (const uuid of this.openTextStreamUuids) {
+            const text = this.lastTextContent || '';
+            if (text) {
+                events.push({
+                    type: 'text',
+                    text,
+                    isStreaming: false,
+                    uuid,
+                });
+            }
+        }
+        this.openTextStreamUuids.clear();
+        for (const uuid of this.openThinkingStreamUuids) {
+            const text = this.lastThinkingContent || '';
+            if (text) {
+                events.push({
+                    type: 'thinking',
+                    text,
+                    isStreaming: false,
+                    uuid,
+                });
+            }
+        }
+        this.openThinkingStreamUuids.clear();
         // Emit usage_snapshot if token info is available
         if (tokens) {
             events.push({
@@ -174,6 +341,8 @@ export class OpencodeJsonEventParser {
         this.textEventEmittedInTurn = false;
         this.lastThinkingContent = undefined;
         this.thinkingEventEmittedInTurn = false;
+        this.streamedTextByPart.clear();
+        this.streamedThinkingByPart.clear();
         return events;
     }
 }

package/dist/src/packages/server/routes/agents.js

@@ -22,6 +22,7 @@ import { getSystemPrompt, setSystemPrompt, clearSystemPrompt, isEchoPromptEnable
 import { markInstructionsDirtyForAll } from '../services/instruction-refresh.js';
 import { startAgentTerminal, stopAgentTerminal } from '../services/agent-terminal-service.js';
 import { buildClaudeUsageByAgentSummary, buildClaudeUsageByDaySummary, buildClaudeUsageSnapshot } from '../services/claude-usage-service.js';
+import { buildGrokUsageSnapshot } from '../services/grok-usage-service.js';
 import { getBackupStatus, setBackupEnabled } from '../services/backup-service.js';
 const log = createLogger('Routes');
 const router = Router();
@@ -948,30 +949,32 @@ router.delete('/:id', (req, res) => {
     }
     res.status(204).end();
 });
-// GET /api/agents/:id/usage - Claude usage snapshot for a single agent
+// GET /api/agents/:id/usage - Claude or Grok usage snapshot for a single agent
 //
-// Mirrors what the Claude CLI's `/usage` slash command surfaces: local agent
-// stats plus the live rate-limit gauges fetched with the CLI's own OAuth
-// credentials. See services/claude-usage-service.ts for the source list.
+// Claude: local agent stats + Anthropic OAuth rate-limit gauges (CLI `/usage`).
+// Grok: local agent stats + CLI chat-proxy billing/credit gauges (CLI `/usage`).
 router.get('/:id/usage', async (req, res) => {
     const agent = agentService.getAgent(req.params.id);
     if (!agent) {
         res.status(404).json({ error: 'Agent not found' });
         return;
     }
-    if (agent.provider !== 'claude') {
+    const provider = agent.provider ?? 'claude';
+    if (provider !== 'claude' && provider !== 'grok') {
         res.status(400).json({
-            error: 'Usage data is only available for Claude agents',
-            provider: agent.provider,
+            error: 'Usage data is only available for Claude and Grok agents',
+            provider,
         });
         return;
     }
     try {
-        const snapshot = await buildClaudeUsageSnapshot(agent);
+        const snapshot = provider === 'grok'
+            ? await buildGrokUsageSnapshot(agent)
+            : await buildClaudeUsageSnapshot(agent);
         res.json(snapshot);
     }
     catch (err) {
-        log.error('Failed to build Claude usage snapshot:', err);
+        log.error(`Failed to build ${provider} usage snapshot:`, err);
         res.status(500).json({ error: err?.message ?? 'Failed to build usage snapshot' });
     }
 });

package/dist/src/packages/server/services/grok-usage-service.js

@@ -0,0 +1,374 @@
+/**
+ * Grok Usage Service
+ *
+ * Surfaces the same plan-limit gauges the Grok CLI's `/usage` command shows,
+ * using the CLI chat-proxy billing endpoints with the OAuth token in
+ * `~/.grok/auth.json`:
+ *
+ *   - `GET /v1/billing?format=credits` — subscription usage percent +
+ *     current weekly/monthly period (what the CLI logs as
+ *     "billing: fetched credits config")
+ *   - `GET /v1/billing` — calendar-month spend/credit allotment
+ *     (`used` / `monthlyLimit`) when the credits payload is weekly-only
+ *
+ * When both are available the snapshot exposes **weekly** and **monthly**
+ * gauges side-by-side, matching the terminal `/usage` panel.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('GrokUsage');
+const AUTH_PATH = path.join(os.homedir(), '.grok', 'auth.json');
+const DEFAULT_BILLING_BASE = 'https://cli-chat-proxy.grok.com/v1/billing';
+const BILLING_TIMEOUT_MS = 5_000;
+// Account-wide gauges — one cache line serves every Grok agent/client poll.
+const RATE_LIMIT_CACHE_TTL_MS = 60_000;
+const RATE_LIMIT_429_BACKOFF_MS = 5 * 60_000;
+const RATE_LIMIT_ERROR_BACKOFF_MS = 30_000;
+function billingBaseUrl() {
+    const base = process.env.GROK_CLI_CHAT_PROXY_BASE_URL?.trim();
+    if (base) {
+        return `${base.replace(/\/+$/, '')}/billing`;
+    }
+    return DEFAULT_BILLING_BASE;
+}
+function readGrokAccessToken() {
+    try {
+        if (!fs.existsSync(AUTH_PATH)) {
+            return { error: 'No Grok CLI credentials found — run `grok login`' };
+        }
+        const raw = JSON.parse(fs.readFileSync(AUTH_PATH, 'utf-8'));
+        // auth.json is keyed by issuer::client_id; pick the first entry with a token.
+        for (const entry of Object.values(raw)) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const token = entry.key;
+            if (typeof token !== 'string' || token === '')
+                continue;
+            const expiresRaw = entry.expires_at ?? entry.expiresAt;
+            if (typeof expiresRaw === 'string' || typeof expiresRaw === 'number') {
+                const expiresMs = typeof expiresRaw === 'number' ? expiresRaw : Date.parse(expiresRaw);
+                if (Number.isFinite(expiresMs) && expiresMs <= Date.now()) {
+                    return {
+                        error: 'Grok CLI OAuth token has expired — run `grok login` or any Grok session to refresh it',
+                    };
+                }
+            }
+            return { token };
+        }
+        return { error: 'Grok CLI credentials are missing an OAuth token' };
+    }
+    catch (err) {
+        log.warn(`Failed to read Grok credentials at ${AUTH_PATH}: ${err}`);
+        return { error: 'Failed to read Grok CLI credentials' };
+    }
+}
+function unwrapVal(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (value && typeof value === 'object' && 'val' in value) {
+        const inner = value.val;
+        if (typeof inner === 'number' && Number.isFinite(inner))
+            return inner;
+    }
+    return null;
+}
+function parseIso(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+function clampPercent(value) {
+    return Math.max(0, Math.min(100, value));
+}
+/** Map API period type strings / date span → weekly | monthly | period. */
+export function classifyPeriodType(typeRaw, startIso, endIso) {
+    if (typeof typeRaw === 'string') {
+        const t = typeRaw.toUpperCase();
+        if (t.includes('WEEK'))
+            return 'weekly';
+        if (t.includes('MONTH'))
+            return 'monthly';
+    }
+    if (!startIso || !endIso)
+        return 'period';
+    const start = Date.parse(startIso);
+    const end = Date.parse(endIso);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start)
+        return 'period';
+    const days = (end - start) / (24 * 60 * 60 * 1000);
+    if (days >= 5 && days <= 10)
+        return 'weekly';
+    if (days >= 25 && days <= 35)
+        return 'monthly';
+    return 'period';
+}
+/** @deprecated use classifyPeriodType — kept for existing tests. */
+export function classifyBillingPeriod(startIso, endIso) {
+    return classifyPeriodType(null, startIso, endIso);
+}
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue)
+        return undefined;
+    const seconds = Number(headerValue);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const dateMs = Date.parse(headerValue);
+    if (Number.isFinite(dateMs))
+        return Math.max(0, dateMs - Date.now());
+    return undefined;
+}
+async function fetchBillingJson(url, token) {
+    const response = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+            'x-grok-client-version': '0.2.93',
+        },
+        signal: AbortSignal.timeout(BILLING_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        return {
+            ok: false,
+            status: response.status,
+            error: `Grok billing endpoint returned ${response.status}`,
+            retryAfterMs: parseRetryAfterMs(response.headers.get('retry-after')),
+        };
+    }
+    const body = (await response.json());
+    return {
+        ok: true,
+        status: response.status,
+        config: body?.config ?? {},
+        retryAfterMs: parseRetryAfterMs(response.headers.get('retry-after')),
+    };
+}
+/**
+ * Parse `/billing?format=credits` — the payload the CLI uses for the
+ * Weekly/Monthly percent gauges in `/usage`.
+ */
+export function parseCreditsConfig(config) {
+    let weekly = null;
+    let monthly = null;
+    let onDemand = null;
+    const percentRaw = config.creditUsagePercent;
+    const percent = typeof percentRaw === 'number' && Number.isFinite(percentRaw)
+        ? clampPercent(percentRaw)
+        : null;
+    const currentPeriod = config.currentPeriod && typeof config.currentPeriod === 'object'
+        ? config.currentPeriod
+        : null;
+    const periodStart = parseIso(currentPeriod?.start) ?? parseIso(config.billingPeriodStart);
+    const periodEnd = parseIso(currentPeriod?.end) ?? parseIso(config.billingPeriodEnd);
+    const kind = classifyPeriodType(currentPeriod?.type, periodStart, periodEnd);
+    if (percent != null && periodEnd) {
+        const window = {
+            utilization: percent,
+            resetsAt: periodEnd,
+        };
+        if (kind === 'weekly')
+            weekly = window;
+        else if (kind === 'monthly')
+            monthly = window;
+        else {
+            // Unknown period type — prefer weekly label when span is short-ish.
+            if (kind === 'period' && periodStart && periodEnd) {
+                const days = (Date.parse(periodEnd) - Date.parse(periodStart)) / (24 * 60 * 60 * 1000);
+                if (days <= 14)
+                    weekly = window;
+                else
+                    monthly = window;
+            }
+            else {
+                weekly = window;
+            }
+        }
+    }
+    // productUsage[] can carry per-product percents (e.g. GrokBuild) — prefer the
+    // primary creditUsagePercent above, but fall back if it was missing.
+    if (percent == null && Array.isArray(config.productUsage)) {
+        for (const entry of config.productUsage) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const p = entry.usagePercent;
+            if (typeof p === 'number' && Number.isFinite(p) && periodEnd) {
+                const window = {
+                    utilization: clampPercent(p),
+                    resetsAt: periodEnd,
+                };
+                if (kind === 'monthly')
+                    monthly = window;
+                else
+                    weekly = window;
+                break;
+            }
+        }
+    }
+    const onDemandCap = unwrapVal(config.onDemandCap);
+    const onDemandUsed = unwrapVal(config.onDemandUsed) ?? 0;
+    if (onDemandCap != null && onDemandCap > 0) {
+        onDemand = {
+            utilization: clampPercent((onDemandUsed / onDemandCap) * 100),
+            resetsAt: periodEnd ?? parseIso(config.billingPeriodEnd) ?? new Date().toISOString(),
+            used: onDemandUsed,
+            limit: onDemandCap,
+        };
+    }
+    return { weekly, monthly, onDemand };
+}
+/**
+ * Parse default `/billing` — absolute used/monthlyLimit spend-style cap.
+ * Used to fill the monthly gauge when the credits payload only has weekly.
+ */
+export function parseSpendConfig(config) {
+    const used = unwrapVal(config.used) ?? unwrapVal(config.includedUsed);
+    const limit = unwrapVal(config.monthlyLimit);
+    const periodEnd = parseIso(config.billingPeriodEnd);
+    if (used == null || limit == null || limit <= 0 || !periodEnd)
+        return null;
+    return {
+        utilization: clampPercent((used / limit) * 100),
+        resetsAt: periodEnd,
+        used,
+        limit,
+    };
+}
+/**
+ * Raw network calls to the CLI chat-proxy billing endpoints. Prefer
+ * `getGrokRateLimits()` which caches + single-flights.
+ */
+async function fetchGrokBillingFromApi() {
+    const creds = readGrokAccessToken();
+    if ('error' in creds) {
+        return { rateLimits: null, error: creds.error };
+    }
+    const base = billingBaseUrl();
+    try {
+        // Parallel: credits format (CLI /usage) + default spend allotment.
+        const [creditsResult, spendResult] = await Promise.all([
+            fetchBillingJson(`${base}?format=credits`, creds.token),
+            fetchBillingJson(base, creds.token),
+        ]);
+        // Prefer status/retry from credits (primary); fall back to spend.
+        if (!creditsResult.ok && !spendResult.ok) {
+            return {
+                rateLimits: null,
+                error: creditsResult.error,
+                status: creditsResult.status,
+                retryAfterMs: creditsResult.retryAfterMs ?? spendResult.retryAfterMs,
+            };
+        }
+        let weekly = null;
+        let monthly = null;
+        let onDemand = null;
+        if (creditsResult.ok) {
+            const parsed = parseCreditsConfig(creditsResult.config);
+            weekly = parsed.weekly;
+            monthly = parsed.monthly;
+            onDemand = parsed.onDemand;
+        }
+        // Fill monthly from spend allotment when credits only gave weekly (the
+        // SuperGrok dual-gauge layout in the CLI /usage panel).
+        if (spendResult.ok) {
+            const spendMonthly = parseSpendConfig(spendResult.config);
+            if (spendMonthly && !monthly) {
+                monthly = spendMonthly;
+            }
+            // On-demand may only appear on the default payload.
+            if (!onDemand) {
+                const onDemandCap = unwrapVal(spendResult.config.onDemandCap);
+                const onDemandUsed = unwrapVal(spendResult.config.onDemandUsed) ?? 0;
+                const periodEnd = parseIso(spendResult.config.billingPeriodEnd);
+                if (onDemandCap != null && onDemandCap > 0 && periodEnd) {
+                    onDemand = {
+                        utilization: clampPercent((onDemandUsed / onDemandCap) * 100),
+                        resetsAt: periodEnd,
+                        used: onDemandUsed,
+                        limit: onDemandCap,
+                    };
+                }
+            }
+        }
+        if (!weekly && !monthly && !onDemand) {
+            return {
+                rateLimits: null,
+                error: creditsResult.ok
+                    ? 'Grok billing response had no usable usage limits'
+                    : creditsResult.error,
+                status: creditsResult.ok ? creditsResult.status : creditsResult.status,
+            };
+        }
+        return {
+            rateLimits: { weekly, monthly, onDemand },
+            error: null,
+            status: creditsResult.ok ? creditsResult.status : spendResult.status,
+        };
+    }
+    catch (err) {
+        log.warn(`Failed to fetch Grok billing: ${err}`);
+        const reason = err?.name === 'TimeoutError' ? 'request timed out' : (err?.message ?? 'request failed');
+        return { rateLimits: null, error: `Could not reach Grok billing endpoint (${reason})` };
+    }
+}
+let rateLimitCache = null;
+let lastGoodRateLimits = null;
+let rateLimitInFlight = null;
+async function getGrokRateLimits() {
+    const now = Date.now();
+    if (rateLimitCache && now < rateLimitCache.validUntil) {
+        return { rateLimits: rateLimitCache.rateLimits, error: rateLimitCache.error };
+    }
+    if (rateLimitInFlight)
+        return rateLimitInFlight;
+    rateLimitInFlight = (async () => {
+        const result = await fetchGrokBillingFromApi();
+        let ttl = RATE_LIMIT_CACHE_TTL_MS;
+        if (result.rateLimits) {
+            lastGoodRateLimits = result.rateLimits;
+        }
+        else if (result.status === 429) {
+            ttl = Math.max(result.retryAfterMs ?? RATE_LIMIT_429_BACKOFF_MS, RATE_LIMIT_CACHE_TTL_MS);
+        }
+        else {
+            ttl = RATE_LIMIT_ERROR_BACKOFF_MS;
+        }
+        const entry = {
+            rateLimits: result.rateLimits ?? lastGoodRateLimits,
+            error: result.error,
+            validUntil: Date.now() + ttl,
+        };
+        rateLimitCache = entry;
+        return { rateLimits: entry.rateLimits, error: entry.error };
+    })();
+    try {
+        return await rateLimitInFlight;
+    }
+    finally {
+        rateLimitInFlight = null;
+    }
+}
+/** Test helper: drop the cached billing result and backoff state. */
+export function resetGrokRateLimitCache() {
+    rateLimitCache = null;
+    lastGoodRateLimits = null;
+    rateLimitInFlight = null;
+}
+export async function buildGrokUsageSnapshot(agent) {
+    const { rateLimits, error: rateLimitsError } = await getGrokRateLimits();
+    return {
+        provider: 'grok',
+        fetchedAt: Date.now(),
+        session: {
+            tokensUsed: agent.tokensUsed ?? 0,
+            contextUsed: agent.contextUsed ?? 0,
+            contextLimit: agent.contextLimit ?? 500_000,
+            taskCount: agent.taskCount ?? 0,
+            lastActivity: agent.lastActivity ?? 0,
+        },
+        rateLimits,
+        rateLimitsError,
+        cliHint: "Run /usage inside this agent's terminal to see live weekly and monthly usage limits.",
+    };
+}