@promptbook/cli 0.114.0-21 → 0.114.0-22

package/esm/index.es.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
 import * as dotenv from 'dotenv';
 import * as readline from 'readline';
-import { emitKeypressEvents, createInterface, cursorTo, clearLine } from 'readline';
+import { createInterface, emitKeypressEvents, cursorTo, clearLine } from 'readline';
 import { forTime, forEver } from 'waitasecond';
 import hexEncoder from 'crypto-js/enc-hex';
 import sha256 from 'crypto-js/sha256';
@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-21';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-22';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -25547,6 +25547,29 @@ async function waitForSkippableWorldTimeDeadline(options) {
     }
 }
 
+/**
+ * Merges a newly reported subset of subscription windows into the latest complete snapshot.
+ *
+ * Some harnesses emit an update only for the limit whose state changed. Keeping the previous windows means a
+ * five-hour update cannot make a still-valid weekly limit disappear from the dashboard. Existing order is preserved
+ * and newly discovered windows are appended, which keeps the terminal presentation stable between refreshes.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+function mergeHarnessSubscriptionUsage(previousSubscriptionUsage, latestSubscriptionUsage) {
+    if (previousSubscriptionUsage === undefined) {
+        return latestSubscriptionUsage;
+    }
+    const latestLimitsByLabel = new Map(latestSubscriptionUsage.limits.map((latestLimit) => [latestLimit.label, latestLimit]));
+    const previousLimitLabels = new Set(previousSubscriptionUsage.limits.map((previousLimit) => previousLimit.label));
+    return {
+        limits: [
+            ...previousSubscriptionUsage.limits.map((previousLimit) => { var _a; return (_a = latestLimitsByLabel.get(previousLimit.label)) !== null && _a !== void 0 ? _a : previousLimit; }),
+            ...latestSubscriptionUsage.limits.filter((latestLimit) => !previousLimitLabels.has(latestLimit.label)),
+        ],
+    };
+}
+
 /**
  * Base delimiter used for passing large prompts through stdin.
  */
@@ -25880,6 +25903,122 @@ function parseClaudeCodeJsonOutput(output) {
     }
 }
 
+/**
+ * Human-readable labels for known Claude Code rolling subscription-limit windows.
+ */
+const CLAUDE_CODE_RATE_LIMIT_LABELS = {
+    five_hour: '5h',
+    seven_day: '7d',
+    seven_day_opus: '7d Opus',
+    seven_day_sonnet: '7d Sonnet',
+    overage: 'Overage',
+};
+/**
+ * Fallback label used when a newer Claude Code release adds a rate-limit window unknown to Promptbook.
+ */
+const UNKNOWN_CLAUDE_CODE_RATE_LIMIT_LABEL = 'Limit';
+/**
+ * Converts Claude Code stream-json rate-limit events into the shared subscription-usage snapshot.
+ *
+ * Claude Code can emit one event for each applicable limit, so the parser preserves every distinct window instead of
+ * assuming the familiar 5-hour and seven-day pair. This lets a new vendor-side limit appear in the dashboard without
+ * changing its renderer.
+ *
+ * @private internal utility of the Claude Code runner
+ */
+function parseClaudeCodeSubscriptionUsage(output) {
+    const limitsByType = new Map();
+    for (const event of parseClaudeCodeOutputEvents(output)) {
+        const limit = parseClaudeCodeSubscriptionUsageLimit(event);
+        if (limit) {
+            limitsByType.set(resolveClaudeCodeRateLimitType(event), limit);
+        }
+    }
+    const limits = [...limitsByType.values()];
+    return limits.length === 0 ? undefined : { limits };
+}
+/**
+ * Parses one Claude Code stream event when it contains a usable subscription-limit update.
+ *
+ * @private helper of `parseClaudeCodeSubscriptionUsage`
+ */
+function parseClaudeCodeSubscriptionUsageLimit(event) {
+    if (event.type !== 'rate_limit_event' || !event.rate_limit_info) {
+        return undefined;
+    }
+    const rateLimitType = resolveClaudeCodeRateLimitType(event);
+    const usedPercentage = resolveClaudeCodeUsedPercentage(event.rate_limit_info);
+    if (usedPercentage === undefined) {
+        return undefined;
+    }
+    const resetsAt = resolveClaudeCodeResetTimestamp(event.rate_limit_info);
+    return {
+        label: formatClaudeCodeRateLimitTypeLabel(rateLimitType),
+        usedPercentage,
+        ...(resetsAt !== undefined && { resetsAt }),
+    };
+}
+/**
+ * Formats known and newly introduced Claude Code rate-limit types for a stable terminal label.
+ *
+ * A newer limit type remains distinct in the dashboard instead of making several unrelated windows all appear as
+ * a generic `Limit` row.
+ *
+ * @private helper of `parseClaudeCodeSubscriptionUsage`
+ */
+function formatClaudeCodeRateLimitTypeLabel(rateLimitType) {
+    const knownLabel = CLAUDE_CODE_RATE_LIMIT_LABELS[rateLimitType];
+    if (knownLabel) {
+        return knownLabel;
+    }
+    const words = rateLimitType.split(/[\s_-]+/u).filter(Boolean);
+    if (words.length === 0) {
+        return UNKNOWN_CLAUDE_CODE_RATE_LIMIT_LABEL;
+    }
+    return words.map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(' ');
+}
+/**
+ * Resolves the stable rate-limit type key emitted by Claude Code across camel- and snake-case payload versions.
+ *
+ * @private helper of `parseClaudeCodeSubscriptionUsage`
+ */
+function resolveClaudeCodeRateLimitType(event) {
+    var _a;
+    const rateLimitInfo = event.rate_limit_info;
+    const rateLimitType = (_a = rateLimitInfo === null || rateLimitInfo === void 0 ? void 0 : rateLimitInfo.rateLimitType) !== null && _a !== void 0 ? _a : rateLimitInfo === null || rateLimitInfo === void 0 ? void 0 : rateLimitInfo.rate_limit_type;
+    return typeof rateLimitType === 'string' && rateLimitType.trim() !== ''
+        ? rateLimitType.trim()
+        : UNKNOWN_CLAUDE_CODE_RATE_LIMIT_LABEL;
+}
+/**
+ * Converts Claude's fractional utilization value to a displayed percentage.
+ *
+ * A rejected limit event may omit utilization, but it still conveys a precise zero-remaining state and is therefore
+ * rendered as 100 percent consumed.
+ *
+ * @private helper of `parseClaudeCodeSubscriptionUsage`
+ */
+function resolveClaudeCodeUsedPercentage(rateLimitInfo) {
+    const utilization = rateLimitInfo.utilization;
+    if (typeof utilization === 'number' && Number.isFinite(utilization)) {
+        const usedPercentage = utilization <= 1 ? utilization * 100 : utilization;
+        if (usedPercentage >= 0 && usedPercentage <= 100) {
+            return usedPercentage;
+        }
+    }
+    return rateLimitInfo.status === 'rejected' ? 100 : undefined;
+}
+/**
+ * Reads Claude's optional Unix reset timestamp from either current or earlier stream payload naming.
+ *
+ * @private helper of `parseClaudeCodeSubscriptionUsage`
+ */
+function resolveClaudeCodeResetTimestamp(rateLimitInfo) {
+    var _a;
+    const resetsAt = (_a = rateLimitInfo.resetsAt) !== null && _a !== void 0 ? _a : rateLimitInfo.resets_at;
+    return typeof resetsAt === 'number' && Number.isFinite(resetsAt) && resetsAt > 0 ? resetsAt : undefined;
+}
+
 /**
  * Polling interval used while waiting for Claude Code session limits to reset.
  */
@@ -25895,6 +26034,14 @@ class ClaudeCodeRunner {
         this.options = options;
         this.name = 'claude-code';
     }
+    /**
+     * Returns the latest subscription-limit snapshot emitted by this Claude Code session.
+     *
+     * Claude exposes these values in the normal stream after a response, so no separate quota-only model call is made.
+     */
+    async getSubscriptionUsage() {
+        return this.subscriptionUsage;
+    }
     /**
      * Runs the prompt using Claude Code and parses usage output.
      */
@@ -25908,6 +26055,7 @@ class ClaudeCodeRunner {
                 prompt,
                 resumeSessionId,
             }).catch(async (error) => {
+                this.updateSubscriptionUsage(error instanceof Error ? error.message : String(error));
                 const sessionLimit = extractClaudeCodeSessionLimitFromError(error);
                 if (!sessionLimit) {
                     throw error;
@@ -25922,6 +26070,7 @@ class ClaudeCodeRunner {
                 continue;
             }
             const sessionLimit = extractClaudeCodeSessionLimitFromOutput(output);
+            this.updateSubscriptionUsage(output);
             if (sessionLimit) {
                 resurrectionCount++;
                 await waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options);
@@ -25951,6 +26100,18 @@ class ClaudeCodeRunner {
             preserveArtifactsOnSuccess: options.preserveArtifactsOnSuccess,
         });
     }
+    /**
+     * Keeps the newest usable Claude subscription-limit values reported by the stream.
+     *
+     * A stream can omit these values for API-key users or unsupported plan types; retaining the prior snapshot avoids
+     * a temporary omission erasing a still-valid dashboard value while a long queue is running.
+     */
+    updateSubscriptionUsage(output) {
+        const subscriptionUsage = parseClaudeCodeSubscriptionUsage(output);
+        if (subscriptionUsage) {
+            this.subscriptionUsage = mergeHarnessSubscriptionUsage(this.subscriptionUsage, subscriptionUsage);
+        }
+    }
 }
 /**
  * Waits until the Claude Code session can be resumed, keeping terminal status clear.
@@ -26858,6 +27019,292 @@ function resolveCodexPricing(modelName) {
     return (_c = OPENAI_MODELS.find((model) => model.modelName === CODEX_FALLBACK_PRICING_MODEL)) === null || _c === void 0 ? void 0 : _c.pricing;
 }
 
+/**
+ * Arguments which start the Codex app server over JSON-RPC stdio.
+ */
+const CODEX_APP_SERVER_ARGUMENTS = ['app-server', '--stdio'];
+/**
+ * Maximum time spent waiting for the optional Codex account-rate-limit snapshot.
+ */
+const CODEX_SUBSCRIPTION_USAGE_REQUEST_TIMEOUT_MS = 10 * 1000;
+/**
+ * JSON-RPC request id used for the required app-server initialization handshake.
+ */
+const INITIALIZE_REQUEST_ID = 1;
+/**
+ * JSON-RPC request id used for the Codex account rate-limit snapshot.
+ */
+const RATE_LIMITS_REQUEST_ID = 2;
+/**
+ * Client name sent to the Codex app server while Promptbook reads subscription limits.
+ */
+const PROMPTBOOK_CODEX_APP_SERVER_CLIENT_NAME = 'ptbk-coder';
+/**
+ * Client version sent to the Codex app server while Promptbook reads subscription limits.
+ *
+ * The app-server protocol only requires a non-empty version string, and the CLI's own version is intentionally not
+ * coupled to Promptbook's package version.
+ */
+const PROMPTBOOK_CODEX_APP_SERVER_CLIENT_VERSION = '1';
+/**
+ * Reads the current Codex subscription limit windows through its local app-server protocol.
+ *
+ * Codex versions without this optional protocol, API-key sessions, and transient account failures simply provide no
+ * snapshot. Subscription usage is contextual UI information, so it must never make a coding prompt fail.
+ *
+ * @private internal utility of the OpenAI Codex runner
+ */
+async function getCodexSubscriptionUsage(codexCommand) {
+    try {
+        return await requestCodexSubscriptionUsage(codexCommand);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Performs the small Codex app-server JSON-RPC exchange which reads rate limits.
+ *
+ * The app server requires a completed `initialize` handshake before it accepts account methods. Closing standard input
+ * after the response lets the short-lived helper exit without sharing the lifecycle of the coding process itself.
+ *
+ * @private helper of `getCodexSubscriptionUsage`
+ */
+function requestCodexSubscriptionUsage(codexCommand) {
+    return new Promise((resolve) => {
+        const codexAppServerProcess = spawn(codexCommand, CODEX_APP_SERVER_ARGUMENTS, {
+            shell: process.platform === 'win32',
+            stdio: 'pipe',
+        });
+        const outputReader = createInterface({ input: codexAppServerProcess.stdout });
+        let requestTimeout;
+        let isSettled = false;
+        // Draining stderr prevents a protocol diagnostic from blocking the short-lived child process. The response is
+        // deliberately not surfaced because missing usage must not distract from an otherwise healthy coding run.
+        codexAppServerProcess.stderr.resume();
+        codexAppServerProcess.stdin.on('error', () => undefined);
+        /**
+         * Stops the helper process and settles this optional request exactly once.
+         */
+        const settle = (subscriptionUsage) => {
+            if (isSettled) {
+                return;
+            }
+            isSettled = true;
+            if (requestTimeout) {
+                clearTimeout(requestTimeout);
+            }
+            outputReader.close();
+            codexAppServerProcess.stdin.end();
+            if (codexAppServerProcess.exitCode === null && !codexAppServerProcess.killed) {
+                codexAppServerProcess.kill();
+            }
+            resolve(subscriptionUsage);
+        };
+        /**
+         * Sends one JSON-RPC message to the Codex app server.
+         */
+        const sendJsonRpcMessage = (message) => {
+            try {
+                codexAppServerProcess.stdin.write(`${JSON.stringify(message)}\n`);
+            }
+            catch (_a) {
+                settle(undefined);
+            }
+        };
+        requestTimeout = setTimeout(() => settle(undefined), CODEX_SUBSCRIPTION_USAGE_REQUEST_TIMEOUT_MS);
+        codexAppServerProcess.on('error', () => settle(undefined));
+        codexAppServerProcess.on('close', () => settle(undefined));
+        outputReader.on('line', (line) => {
+            const response = parseJsonRecord(line);
+            if (!response) {
+                return;
+            }
+            if (response.id === INITIALIZE_REQUEST_ID) {
+                if (!isJsonRecord(response.result)) {
+                    settle(undefined);
+                    return;
+                }
+                sendJsonRpcMessage({ jsonrpc: '2.0', method: 'initialized' });
+                sendJsonRpcMessage({
+                    jsonrpc: '2.0',
+                    id: RATE_LIMITS_REQUEST_ID,
+                    method: 'account/rateLimits/read',
+                });
+                return;
+            }
+            if (response.id === RATE_LIMITS_REQUEST_ID) {
+                settle(buildCodexSubscriptionUsage(response.result));
+            }
+        });
+        sendJsonRpcMessage({
+            jsonrpc: '2.0',
+            id: INITIALIZE_REQUEST_ID,
+            method: 'initialize',
+            params: {
+                clientInfo: {
+                    name: PROMPTBOOK_CODEX_APP_SERVER_CLIENT_NAME,
+                    version: PROMPTBOOK_CODEX_APP_SERVER_CLIENT_VERSION,
+                },
+                capabilities: {
+                    experimentalApi: true,
+                },
+            },
+        });
+    });
+}
+/**
+ * Converts the raw Codex app-server rate-limit response into Promptbook's harness-neutral subscription snapshot.
+ *
+ * Modern Codex versions can report several metered buckets, while older versions expose a single compatibility
+ * bucket. In both cases every primary and secondary rolling window is preserved for the terminal dashboard.
+ *
+ * @private internal utility of the OpenAI Codex runner
+ */
+function buildCodexSubscriptionUsage(response) {
+    if (!isJsonRecord(response)) {
+        return undefined;
+    }
+    const snapshots = resolveCodexRateLimitSnapshots(response);
+    const hasMultipleSnapshots = snapshots.length > 1;
+    const limits = snapshots.flatMap(({ identifier, value }) => buildCodexSubscriptionUsageLimits({
+        snapshot: value,
+        identifier,
+        hasMultipleSnapshots,
+    }));
+    return limits.length === 0 ? undefined : { limits };
+}
+/**
+ * Resolves either Codex's multi-bucket rate-limit response or its compatible single-bucket fallback.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function resolveCodexRateLimitSnapshots(response) {
+    const rateLimitsByLimitId = response.rateLimitsByLimitId;
+    if (isJsonRecord(rateLimitsByLimitId)) {
+        const snapshots = Object.entries(rateLimitsByLimitId)
+            .filter(([, value]) => isJsonRecord(value))
+            .map(([identifier, value]) => ({ identifier, value: value }));
+        if (snapshots.length > 0) {
+            return snapshots;
+        }
+    }
+    return isJsonRecord(response.rateLimits) ? [{ value: response.rateLimits }] : [];
+}
+/**
+ * Creates every displayed rolling window from one Codex rate-limit bucket.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function buildCodexSubscriptionUsageLimits(options) {
+    var _a;
+    const { snapshot, identifier, hasMultipleSnapshots } = options;
+    const bucketLabel = hasMultipleSnapshots ? (_a = readString(snapshot.limitName)) !== null && _a !== void 0 ? _a : identifier : undefined;
+    return [
+        buildCodexSubscriptionUsageLimit(snapshot.primary, bucketLabel, 'Primary'),
+        buildCodexSubscriptionUsageLimit(snapshot.secondary, bucketLabel, 'Secondary'),
+    ].filter((limit) => limit !== undefined);
+}
+/**
+ * Converts one raw Codex rate-limit window to a displayable subscription usage limit.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function buildCodexSubscriptionUsageLimit(rawWindow, bucketLabel, fallbackWindowLabel) {
+    var _a;
+    if (!isJsonRecord(rawWindow)) {
+        return undefined;
+    }
+    const usedPercentage = readPercentage(rawWindow.usedPercent);
+    if (usedPercentage === undefined) {
+        return undefined;
+    }
+    const windowLabel = (_a = formatCodexRateLimitWindowDuration(rawWindow.windowDurationMins)) !== null && _a !== void 0 ? _a : fallbackWindowLabel;
+    const label = bucketLabel ? `${bucketLabel} ${windowLabel}` : windowLabel;
+    const resetsAt = readUnixTimestamp(rawWindow.resetsAt);
+    return {
+        label,
+        usedPercentage,
+        ...(resetsAt !== undefined && { resetsAt }),
+    };
+}
+/**
+ * Formats the duration of one Codex rolling rate-limit window for compact terminal display.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function formatCodexRateLimitWindowDuration(value) {
+    const durationMinutes = readNonNegativeFiniteNumber(value);
+    if (durationMinutes === undefined || durationMinutes === 0) {
+        return undefined;
+    }
+    const MINUTES_PER_HOUR = 60;
+    const MINUTES_PER_DAY = 24 * MINUTES_PER_HOUR;
+    if (durationMinutes % MINUTES_PER_DAY === 0) {
+        return `${durationMinutes / MINUTES_PER_DAY}d`;
+    }
+    if (durationMinutes % MINUTES_PER_HOUR === 0) {
+        return `${durationMinutes / MINUTES_PER_HOUR}h`;
+    }
+    return `${durationMinutes}m`;
+}
+/**
+ * Parses one JSON-RPC line when it is an object.
+ *
+ * @private helper of `getCodexSubscriptionUsage`
+ */
+function parseJsonRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        return isJsonRecord(value) ? value : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Checks whether a value is a JSON object.
+ *
+ * @private helper of `getCodexSubscriptionUsage`
+ */
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads one non-empty string from an untrusted JSON object.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function readString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/**
+ * Reads a finite number which cannot be negative.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function readNonNegativeFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Reads a valid percentage from the Codex app-server response.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function readPercentage(value) {
+    const percentage = readNonNegativeFiniteNumber(value);
+    return percentage !== undefined && percentage <= 100 ? percentage : undefined;
+}
+/**
+ * Reads a Unix timestamp in seconds from the Codex app-server response.
+ *
+ * @private helper of `buildCodexSubscriptionUsage`
+ */
+function readUnixTimestamp(value) {
+    const timestamp = readNonNegativeFiniteNumber(value);
+    return timestamp !== undefined && timestamp > 0 ? timestamp : undefined;
+}
+
 /**
  * Detects which login method Codex used from the captured CLI output.
  *
@@ -27045,6 +27492,15 @@ class OpenAiCodexRunner {
             jitterRatio: RATE_LIMIT_BACKOFF_JITTER_RATIO,
         });
     }
+    /**
+     * Reads the current ChatGPT subscription quota snapshot through Codex's local app server.
+     *
+     * API-key sessions and unsupported Codex versions simply return no snapshot, which keeps this optional dashboard
+     * information from affecting the actual prompt execution.
+     */
+    async getSubscriptionUsage() {
+        return await getCodexSubscriptionUsage(this.options.codexCommand);
+    }
     /**
      * Runs the Codex prompt in a temporary script and waits for completion output.
      */
@@ -27624,6 +28080,90 @@ function assertPriorityBoundary(optionName, priority) {
 }
 // Note: [🟡] Code for priority filtering [priorityFilter](scripts/run-codex-prompts/prompts/priorityFilter.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Label shown on the first subscription-usage row in the terminal Session box.
+ */
+const SUBSCRIPTION_USAGE_SESSION_LABEL = 'Usage';
+/**
+ * Number of milliseconds in one calendar-free day used for compact reset countdowns.
+ */
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Builds every available subscription-limit row for the terminal Session box.
+ *
+ * The first row carries the `Usage` label and subsequent rows stay aligned beneath it, allowing a harness to report
+ * any number of windows instead of making the dashboard assume a fixed 5-hour/weekly pair.
+ *
+ * @private internal utility of coder run UI
+ */
+function buildSubscriptionUsageSessionRows(subscriptionUsage, currentTimeMs = Date.now()) {
+    if (!subscriptionUsage || subscriptionUsage.limits.length === 0) {
+        return [];
+    }
+    return subscriptionUsage.limits.map((limit, index) => ({
+        label: index === 0 ? SUBSCRIPTION_USAGE_SESSION_LABEL : '',
+        value: formatSubscriptionUsageLimit(limit, currentTimeMs),
+    }));
+}
+/**
+ * Formats one remaining subscription limit and its optional reset time for the terminal dashboard.
+ *
+ * @private helper of `buildSubscriptionUsageSessionRows`
+ */
+function formatSubscriptionUsageLimit(limit, currentTimeMs) {
+    const remainingPercentage = Math.round(Math.max(0, Math.min(100, 100 - limit.usedPercentage)));
+    const remainingPercentageColor = resolveRemainingPercentageColor(remainingPercentage);
+    const resetText = formatSubscriptionUsageReset(limit.resetsAt, currentTimeMs);
+    const label = limit.label.trim() || SUBSCRIPTION_USAGE_SESSION_LABEL;
+    return [
+        colors.bold(label),
+        remainingPercentageColor(`${remainingPercentage}% remaining`),
+        ...(resetText ? [colors.gray(resetText)] : []),
+    ].join('  ·  ');
+}
+/**
+ * Chooses an attention color for the remaining subscription percentage.
+ *
+ * @private helper of `buildSubscriptionUsageSessionRows`
+ */
+function resolveRemainingPercentageColor(remainingPercentage) {
+    if (remainingPercentage === 0) {
+        return colors.red;
+    }
+    if (remainingPercentage <= 20) {
+        return colors.yellow;
+    }
+    return colors.green;
+}
+/**
+ * Formats the optional future reset timestamp of one subscription limit.
+ *
+ * @private helper of `buildSubscriptionUsageSessionRows`
+ */
+function formatSubscriptionUsageReset(resetsAt, currentTimeMs) {
+    if (resetsAt === undefined) {
+        return undefined;
+    }
+    const remainingDurationMs = resetsAt * 1000 - currentTimeMs;
+    if (remainingDurationMs <= 0) {
+        return 'resets now';
+    }
+    return `resets in ${formatSubscriptionUsageDuration(remainingDurationMs)}`;
+}
+/**
+ * Formats a reset countdown with days when a weekly-style limit is still several days away.
+ *
+ * @private helper of `buildSubscriptionUsageSessionRows`
+ */
+function formatSubscriptionUsageDuration(durationMs) {
+    const dayCount = Math.floor(durationMs / ONE_DAY_MS);
+    if (dayCount === 0) {
+        return formatDurationMs(durationMs);
+    }
+    const remainingDurationMs = durationMs - dayCount * ONE_DAY_MS;
+    return remainingDurationMs === 0 ? `${dayCount}d` : `${dayCount}d ${formatDurationMs(remainingDurationMs)}`;
+}
+
 /**
  * Minimum width used for the rich coder-run frame.
  */
@@ -27729,6 +28269,7 @@ function buildSessionRows(options, bodyWidth, pausePresentation) {
             value: runnerParts.join('  ·  '),
         },
         ...configurationRows,
+        ...buildSubscriptionUsageSessionRows(options.subscriptionUsage),
         ...buildScriptPathSessionRows(options.currentScriptPaths || [], bodyWidth),
         {
             label: 'This run',
@@ -28274,6 +28815,13 @@ class CoderRunUiState extends EventEmitter {
         this.agentStatusTableRows = [...agentStatusTableRows];
         this.emitChange();
     }
+    /**
+     * Replaces the optional harness subscription usage shown in the Session box.
+     */
+    setSubscriptionUsage(subscriptionUsage) {
+        this.subscriptionUsage = subscriptionUsage;
+        this.emitChange();
+    }
     /**
      * Sets or clears the Enter-key action label shown in the controls panel.
      */
@@ -29265,6 +29813,7 @@ function renderCoderRunUi(startTime, options = {}) {
             pauseTargetLabel: getPauseTargetLabel(),
             isEndAfterCurrentPromptRequested: getEndAfterCurrentPromptState(),
             config: state.config,
+            subscriptionUsage: state.subscriptionUsage,
             agentVisual: state.agentVisual,
             phase: state.phase,
             currentPromptLabel: state.currentPromptLabel,
@@ -76410,6 +76959,30 @@ async function writePromptFile(file) {
     await writeFile(file.path, content, 'utf-8');
 }
 
+/**
+ * Refreshes optional harness subscription usage in the shared coder-run UI state.
+ *
+ * Subscription visibility is an enhancement, not a prerequisite for running prompts. A harness which cannot expose a
+ * snapshot, or whose account endpoint is temporarily unavailable, therefore leaves the existing dashboard unchanged.
+ *
+ * @private internal utility of coder run UI
+ */
+async function refreshCoderRunUiSubscriptionUsage(options) {
+    const { runner, uiState } = options;
+    if (!uiState || !runner.getSubscriptionUsage) {
+        return;
+    }
+    try {
+        const subscriptionUsage = await runner.getSubscriptionUsage();
+        if (subscriptionUsage) {
+            uiState.setSubscriptionUsage(subscriptionUsage);
+        }
+    }
+    catch (_a) {
+        // A current subscription snapshot must never interrupt the coding queue.
+    }
+}
+
 /**
  * Maximum number of retry attempts performed after a prompt round throws an error.
  * After this many retries the round is finalized as failed.
@@ -76487,6 +77060,10 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
                     }),
                     waitForPauseCheckpoint: waitForRequestedPause,
                 });
+                await refreshCoderRunUiSubscriptionUsage({
+                    runner,
+                    uiState: uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state,
+                });
                 await finalizeSuccessfulPromptRound({
                     options,
                     nextPrompt,
@@ -77727,6 +78304,10 @@ async function runCodexPrompts(providedOptions) {
         console.info(colors.green(`Running prompts with ${runner.name}`));
         initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
         await initializeRunUiAgentVisual(uiHandle, resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentSource);
+        await refreshCoderRunUiSubscriptionUsage({
+            runner,
+            uiState: uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state,
+        });
         await seedCachedAveragePromptDuration({
             options,
             actualRunnerModel,