@promptbook/cli 0.112.0-131 → 0.112.0-133

package/esm/index.es.js

@@ -6,7 +6,7 @@ import { join, resolve, dirname, relative, basename, delimiter, isAbsolute, extn
 import { spawn } from 'child_process';
 import { createHash, randomBytes } from 'crypto';
 import * as fs from 'fs';
-import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync } from 'fs';
+import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
 import * as dotenv from 'dotenv';
 import moment from 'moment';
 import { forTime, forEver } from 'waitasecond';
@@ -38,6 +38,7 @@ import ignore from 'ignore';
 import * as readline from 'readline';
 import { emitKeypressEvents, clearLine, cursorTo, createInterface } from 'readline';
 import { EventEmitter } from 'events';
+import { tmpdir } from 'os';
 import { lookup, extension } from 'mime-types';
 import papaparse from 'papaparse';
 import { pathToFileURL } from 'url';
@@ -58,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-131';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-133';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1718,28 +1719,6 @@ function $initializeAboutCommand(program) {
 // TODO: [🗽] Unite branding and make single place for it
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * Supported thinking-level CLI values for coding-agent runners with configurable reasoning effort.
- *
- * @private internal shared utility of `ptbk coder run`
- */
-const THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'];
-/**
- * Parses and validates an optional thinking-level option value.
- *
- * @private internal shared utility of `ptbk coder run`
- */
-function parseThinkingLevel(thinkingLevelValue) {
-    if (thinkingLevelValue === undefined) {
-        return undefined;
-    }
-    if (THINKING_LEVEL_VALUES.includes(thinkingLevelValue)) {
-        return thinkingLevelValue;
-    }
-    throw new Error(`Invalid thinking level "${thinkingLevelValue}". Use one of: ${THINKING_LEVEL_VALUES.join(', ')}.`);
-}
-// Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
-
 // Note: [💞] Ignore a discrepancy between file name and entity name
 /**
  * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
@@ -1754,6 +1733,12 @@ const CLI_AGENT_HARNESS_NAMES = [
     'opencode',
     'gemini',
 ];
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+const CLI_AGENT_THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh', 'max'];
 /**
  * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
  *
@@ -1776,6 +1761,28 @@ const PTBK_MODEL_ENV = 'PTBK_MODEL';
  */
 const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
 
+/**
+ * Supported thinking-level CLI values for coding-agent runners with configurable reasoning effort.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+const THINKING_LEVEL_VALUES = CLI_AGENT_THINKING_LEVEL_VALUES;
+/**
+ * Parses and validates an optional thinking-level option value.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+function parseThinkingLevel(thinkingLevelValue) {
+    if (thinkingLevelValue === undefined) {
+        return undefined;
+    }
+    if (THINKING_LEVEL_VALUES.includes(thinkingLevelValue)) {
+        return thinkingLevelValue;
+    }
+    throw new Error(`Invalid thinking level "${thinkingLevelValue}". Use one of: ${THINKING_LEVEL_VALUES.join(', ')}.`);
+}
+// Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Runner identifiers supported by Promptbook CLI agent orchestration commands.
  *
@@ -4561,14 +4568,16 @@ function formatPromptCount$1(count) {
 
 /**
  * Calendar formats used when displaying the estimated completion time.
+ *
+ * Uses 24-hour format (`HH:mm`) so estimates are unambiguous (for example `17:30` instead of `5:30`).
  */
 const ESTIMATED_DONE_CALENDAR_FORMATS = {
-    sameDay: '[Today] h:mm',
-    nextDay: '[Tomorrow] h:mm',
-    nextWeek: 'dddd h:mm',
-    lastDay: '[Yesterday] h:mm',
-    lastWeek: 'dddd h:mm',
-    sameElse: 'MMM D h:mm',
+    sameDay: '[Today] HH:mm',
+    nextDay: '[Tomorrow] HH:mm',
+    nextWeek: 'dddd HH:mm',
+    lastDay: '[Yesterday] HH:mm',
+    lastWeek: 'dddd HH:mm',
+    sameElse: 'MMM D HH:mm',
 };
 /**
  * Formats a duration into a compact string such as "3h 12m" or "45s".
@@ -4596,8 +4605,12 @@ function formatDurationBrief(duration) {
 
 /**
  * Builds a session-scoped progress snapshot from prompt stats and elapsed active time.
+ *
+ * When the current session has not finished any prompt yet but a `cachedAveragePromptDurationMs` is
+ * provided (loaded from the per-config estimate cache stored in the temp folder), the snapshot uses
+ * that historical average to project the remaining work instead of waiting for the first completion.
  */
-function buildCoderRunProgressSnapshot(stats, elapsedDuration, initialDone) {
+function buildCoderRunProgressSnapshot(stats, elapsedDuration, initialDone, cachedAveragePromptDurationMs) {
     const totalPrompts = stats.done + stats.forAgent + stats.toBeWritten;
     const sessionDone = Math.max(0, stats.done - initialDone);
     const sessionRemaining = stats.forAgent;
@@ -4605,12 +4618,22 @@ function buildCoderRunProgressSnapshot(stats, elapsedDuration, initialDone) {
     const currentPromptIndex = sessionTotal > 0 ? Math.min(sessionDone + 1, sessionTotal) : 0;
     const percentage = sessionTotal > 0 ? Math.round((sessionDone / sessionTotal) * 100) : 0;
     const elapsedText = formatDurationBrief(elapsedDuration);
+    const elapsedMs = elapsedDuration.asMilliseconds();
     let estimatedTotalText = 'estimating...';
     let estimatedLabel = 'after first completion';
     let isEstimatedTotalKnown = false;
+    let estimatedTotalMs;
     if (sessionTotal > 0 && sessionDone > 0) {
-        const estimatedTotalMs = (elapsedDuration.asMilliseconds() * sessionTotal) / sessionDone;
-        const estimatedRemainingMs = Math.max(0, estimatedTotalMs - elapsedDuration.asMilliseconds());
+        estimatedTotalMs = (elapsedMs * sessionTotal) / sessionDone;
+    }
+    else if (sessionTotal > 0 &&
+        cachedAveragePromptDurationMs !== undefined &&
+        cachedAveragePromptDurationMs > 0) {
+        const projectedRemainingMs = sessionRemaining * cachedAveragePromptDurationMs;
+        estimatedTotalMs = elapsedMs + projectedRemainingMs;
+    }
+    if (estimatedTotalMs !== undefined) {
+        const estimatedRemainingMs = Math.max(0, estimatedTotalMs - elapsedMs);
         const estimatedTotalDuration = moment.duration(estimatedTotalMs);
         const estimatedCompletion = moment().add(estimatedRemainingMs, 'milliseconds');
         estimatedTotalText = formatDurationBrief(estimatedTotalDuration);
@@ -4744,12 +4767,21 @@ class CoderRunUiState extends EventEmitter {
         this.stats = stats;
         this.emitChange();
     }
+    /**
+     * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
+     *
+     * Used to project completion estimates before the first prompt of the current session finishes.
+     */
+    setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs) {
+        this.cachedAveragePromptDurationMs = cachedAveragePromptDurationMs;
+        this.emitChange();
+    }
     /**
      * Computes a progress snapshot on demand so elapsed time ticks with periodic re-renders.
      */
     getProgress() {
         var _a;
-        return buildCoderRunProgressSnapshot(this.stats, this.timer.getElapsedDuration(), (_a = this.initialDone) !== null && _a !== void 0 ? _a : this.stats.done);
+        return buildCoderRunProgressSnapshot(this.stats, this.timer.getElapsedDuration(), (_a = this.initialDone) !== null && _a !== void 0 ? _a : this.stats.done, this.cachedAveragePromptDurationMs);
     }
     /**
      * Sets the label of the prompt currently being processed and resets per-prompt state.
@@ -27456,17 +27488,21 @@ async function $runGoScriptWithOutput(options) {
     });
 }
 
+/**
+ * Base delimiter used for passing large prompts through stdin.
+ */
+const CLAUDE_PROMPT_DELIMITER = 'CLAUDE_PROMPT';
 /**
  * Builds the shell script that runs Claude Code with the prompt and coding context.
  */
 function buildClaudeScript(options) {
-    const delimiter = 'CLAUDE_PROMPT';
+    const THINKING_LEVEL_ARGUMENT = options.thinkingLevel ? ` --effort ${options.thinkingLevel}` : '';
     return spaceTrim((block) => `
-            claude --allowedTools "Bash,Read,Edit,Write" --output-format json --print <<'${delimiter}'
+            claude --allowedTools "Bash,Read,Edit,Write"${THINKING_LEVEL_ARGUMENT} --output-format json --print <<'${CLAUDE_PROMPT_DELIMITER}'
 
             ${block(options.prompt)}
 
-            ${delimiter}
+            ${CLAUDE_PROMPT_DELIMITER}
         `);
 }
 
@@ -27602,7 +27638,8 @@ class ClaudeCodeRunner {
     /**
      * Creates a new Claude Code runner.
      */
-    constructor() {
+    constructor(options = {}) {
+        this.options = options;
         this.name = 'claude-code';
     }
     /**
@@ -27611,6 +27648,7 @@ class ClaudeCodeRunner {
     async runPrompt(options) {
         const scriptContent = buildClaudeScript({
             prompt: options.prompt,
+            thinkingLevel: this.options.thinkingLevel,
         });
         const output = await $runGoScriptWithOutput({
             scriptPath: options.scriptPath,
@@ -28783,7 +28821,9 @@ function resolvePromptRunner(options) {
         }), actualRunnerModel);
     }
     if (agentName === 'claude-code') {
-        return createRunnerResolution(options, new ClaudeCodeRunner());
+        return createRunnerResolution(options, new ClaudeCodeRunner({
+            thinkingLevel: options.thinkingLevel,
+        }));
     }
     if (agentName === 'opencode') {
         return createRunnerResolution(options, new OpencodeRunner({
@@ -37857,7 +37897,7 @@ Array.from(new Set(SERVER_LIMIT_DEFINITIONS.flatMap((definition) => definition.l
  *
  * @private internal constant of `ptbk agents-server`
  */
-const USER_CHAT_JOB_WORKER_POLL_INTERVAL_MS = 2000;
+const USER_CHAT_JOB_WORKER_POLL_INTERVAL_MS = 10000;
 /**
  * Number of identical worker failures suppressed before logging a repeated summary.
  *
@@ -69682,6 +69722,15 @@ class CliProgressDisplay {
         this.render();
         this.interval = setInterval(() => this.render(), PROGRESS_REFRESH_INTERVAL_MS);
     }
+    /**
+     * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
+     *
+     * Used to project completion estimates before the first prompt of the current session finishes.
+     */
+    setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs) {
+        this.cachedAveragePromptDurationMs = cachedAveragePromptDurationMs;
+        this.render();
+    }
     /**
      * Updates the progress statistics shown in the header.
      */
@@ -69752,7 +69801,7 @@ class CliProgressDisplay {
      */
     buildProgressLines() {
         var _a, _b;
-        const snapshot = buildCoderRunProgressSnapshot(this.stats, this.timer.getElapsedDuration(), (_a = this.initialDone) !== null && _a !== void 0 ? _a : this.stats.done);
+        const snapshot = buildCoderRunProgressSnapshot(this.stats, this.timer.getElapsedDuration(), (_a = this.initialDone) !== null && _a !== void 0 ? _a : this.stats.done, this.cachedAveragePromptDurationMs);
         const columns = Math.max(40, (_b = process.stdout.columns) !== null && _b !== void 0 ? _b : 80);
         const workingLine = snapshot.sessionTotal > 0
             ? [
@@ -69810,6 +69859,118 @@ function formatPromptCount(count) {
     return `${count} prompt${count === 1 ? '' : 's'}`;
 }
 
+/**
+ * Sub-directory of the OS temp folder where per-config estimate caches are stored.
+ *
+ * @private internal constant of `coderRunEstimateCache`
+ */
+const ESTIMATE_CACHE_DIRECTORY_NAME = 'ptbk-coder-estimates';
+/**
+ * Absolute path to the directory where estimate caches are persisted.
+ *
+ * @private internal utility of `coderRunEstimateCache`
+ */
+function getEstimateCacheDirectory() {
+    return join(tmpdir(), ESTIMATE_CACHE_DIRECTORY_NAME);
+}
+/**
+ * Sanitizes a single identifier component so that it is safe to use as a filename segment.
+ *
+ * @private internal utility of `coderRunEstimateCache`
+ */
+function sanitizeFileNameSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+/**
+ * Builds the cache filename for a given runner configuration.
+ *
+ * @private internal utility of `coderRunEstimateCache`
+ */
+function buildEstimateCacheFileName(key) {
+    var _a, _b;
+    const harnessSegment = sanitizeFileNameSegment(key.harness);
+    const modelSegment = sanitizeFileNameSegment((_a = key.model) !== null && _a !== void 0 ? _a : 'default');
+    const thinkingLevelSegment = sanitizeFileNameSegment((_b = key.thinkingLevel) !== null && _b !== void 0 ? _b : 'default');
+    return `${harnessSegment}__${modelSegment}__${thinkingLevelSegment}.json`;
+}
+/**
+ * Reads the previously persisted cache entry for a configuration if available.
+ *
+ * @private internal utility of `coderRunEstimateCache`
+ */
+async function readEstimateCacheEntry(filePath) {
+    try {
+        const content = await promises.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed.averagePromptDurationMs !== 'number' ||
+            !Number.isFinite(parsed.averagePromptDurationMs) ||
+            parsed.averagePromptDurationMs <= 0 ||
+            typeof parsed.sampleCount !== 'number' ||
+            !Number.isFinite(parsed.sampleCount) ||
+            parsed.sampleCount <= 0) {
+            return undefined;
+        }
+        return {
+            averagePromptDurationMs: parsed.averagePromptDurationMs,
+            sampleCount: parsed.sampleCount,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+        };
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Loads the cached average prompt duration for the given runner configuration.
+ *
+ * Returns `undefined` when no usable cache entry exists. Cache failures must never break the run, so this
+ * function swallows IO and parsing errors instead of throwing.
+ *
+ * @public exported for use by the coder run progress displays
+ */
+async function loadCachedAveragePromptDurationMs(key) {
+    const filePath = join(getEstimateCacheDirectory(), buildEstimateCacheFileName(key));
+    const entry = await readEstimateCacheEntry(filePath);
+    return entry === null || entry === void 0 ? void 0 : entry.averagePromptDurationMs;
+}
+/**
+ * Records a new prompt-duration sample for the given runner configuration into the temp folder cache.
+ *
+ * Updates a running average so future `ptbk coder run` / `ptbk coder server` invocations can show
+ * meaningful estimates immediately, before the first prompt of the new session has completed.
+ *
+ * Cache failures are swallowed because the next-run estimate is best-effort and must not affect the
+ * current run.
+ *
+ * @public exported for use by the prompt round finalizer
+ */
+async function recordPromptDurationSample(key, promptDurationMs) {
+    var _a, _b;
+    if (!Number.isFinite(promptDurationMs) || promptDurationMs <= 0) {
+        return;
+    }
+    try {
+        const cacheDirectory = getEstimateCacheDirectory();
+        await promises.mkdir(cacheDirectory, { recursive: true });
+        const filePath = join(cacheDirectory, buildEstimateCacheFileName(key));
+        const previousEntry = await readEstimateCacheEntry(filePath);
+        const previousSampleCount = (_a = previousEntry === null || previousEntry === void 0 ? void 0 : previousEntry.sampleCount) !== null && _a !== void 0 ? _a : 0;
+        const previousTotalMs = ((_b = previousEntry === null || previousEntry === void 0 ? void 0 : previousEntry.averagePromptDurationMs) !== null && _b !== void 0 ? _b : 0) * previousSampleCount;
+        const nextSampleCount = previousSampleCount + 1;
+        const nextAveragePromptDurationMs = (previousTotalMs + promptDurationMs) / nextSampleCount;
+        const nextEntry = {
+            averagePromptDurationMs: nextAveragePromptDurationMs,
+            sampleCount: nextSampleCount,
+            updatedAt: new Date().toISOString(),
+        };
+        await promises.writeFile(filePath, JSON.stringify(nextEntry, null, 4), 'utf-8');
+    }
+    catch (_c) {
+        // Note: Persisting the estimate cache is best-effort. Failures must not affect the current run.
+    }
+}
+// Note: [🟡] Code in this file is only used from `@promptbook/cli` orchestration scripts and is not shipped to other consumers.
+
 /**
  * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
  *
@@ -71777,6 +71938,11 @@ async function finalizeSuccessfulPromptRound(options) {
     markPromptDone(nextPrompt.file, nextPrompt.section, result.usage, runnerMetadata.runnerName, runnerMetadata.modelName, promptExecutionStartedDate, result.attemptCount);
     await writePromptFile(nextPrompt.file);
     await normalizeLineEndingsForCurrentRound(runOptions, roundChangedFilesSnapshot);
+    await recordPromptDurationInEstimateCache({
+        options: runOptions,
+        runnerMetadata,
+        promptExecutionStartedDate,
+    });
     if (!runOptions.noCommit) {
         await waitForCommitConfirmationIfNeeded({
             options: runOptions,
@@ -71878,6 +72044,24 @@ async function runPostPromptAutoMigrationIfEnabled(options) {
         logger: console,
     });
 }
+/**
+ * Persists the duration of one successful prompt round into the per-config estimate cache so the
+ * next `ptbk coder run` / `ptbk coder server` invocation can show a meaningful completion estimate
+ * before its own first prompt has finished.
+ */
+async function recordPromptDurationInEstimateCache(options) {
+    var _a;
+    const { options: runOptions, runnerMetadata, promptExecutionStartedDate } = options;
+    if (!runOptions.agentName) {
+        return;
+    }
+    const promptDurationMs = moment().diff(promptExecutionStartedDate);
+    await recordPromptDurationSample({
+        harness: runOptions.agentName,
+        model: (_a = runnerMetadata.modelName) !== null && _a !== void 0 ? _a : runOptions.model,
+        thinkingLevel: runOptions.thinkingLevel,
+    }, promptDurationMs);
+}
 /**
  * Normalizes line endings in files modified during the current coding round.
  */
@@ -71927,6 +72111,12 @@ async function runCodexPrompts(providedOptions) {
         const { runner, actualRunnerModel, runnerMetadata } = resolvePromptRunner(options);
         console.info(colors.green(`Running prompts with ${runner.name}`));
         initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
+        await seedCachedAveragePromptDuration({
+            options,
+            actualRunnerModel,
+            progressDisplay,
+            uiHandle,
+        });
         let hasShownUpcomingTasks = false;
         let hasWaitedForStart = false;
         let previousRoundStartTime;
@@ -72288,6 +72478,27 @@ async function waitBetweenPromptRoundsIfNeeded(options) {
     progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.resumeTimer();
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
 }
+/**
+ * Loads the cached average prompt duration for the current runner configuration and seeds both
+ * progress displays with it so estimates are shown immediately, even before the first prompt of
+ * the current session completes.
+ */
+async function seedCachedAveragePromptDuration(options) {
+    const { options: runOptions, actualRunnerModel, progressDisplay, uiHandle } = options;
+    if (!runOptions.agentName) {
+        return;
+    }
+    const cachedAveragePromptDurationMs = await loadCachedAveragePromptDurationMs({
+        harness: runOptions.agentName,
+        model: actualRunnerModel !== null && actualRunnerModel !== void 0 ? actualRunnerModel : runOptions.model,
+        thinkingLevel: runOptions.thinkingLevel,
+    });
+    if (cachedAveragePromptDurationMs === undefined) {
+        return;
+    }
+    progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs);
+    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs);
+}
 /**
  * Stops active displays and prints the git identity tip for real runs.
  */