@promptbook/node 0.114.0-20 → 0.114.0-22

package/esm/index.es.js

@@ -3,6 +3,7 @@ import { unlink, mkdir, appendFile, writeFile, readFile, stat, access, constants
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import colors from 'colors';
 import { spawn, spawnSync } from 'child_process';
+import { createInterface } from 'readline';
 import { fileURLToPath } from 'url';
 import CryptoJS from 'crypto-js';
 import hexEncoder from 'crypto-js/enc-hex';
@@ -29,7 +30,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-20';
+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
@@ -3407,6 +3408,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.
  */
@@ -3740,6 +3764,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.
  */
@@ -3755,6 +3895,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.
      */
@@ -3768,6 +3916,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;
@@ -3782,6 +3931,7 @@ class ClaudeCodeRunner {
                 continue;
             }
             const sessionLimit = extractClaudeCodeSessionLimitFromOutput(output);
+            this.updateSubscriptionUsage(output);
             if (sessionLimit) {
                 resurrectionCount++;
                 await waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options);
@@ -3811,6 +3961,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.
@@ -4777,6 +4939,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.
  *
@@ -4964,6 +5412,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.
      */