@promptbook/node 0.113.0-10 → 0.113.0-11

package/esm/scripts/run-codex-prompts/common/waitUntilWorldTimeDeadline.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Callback called before each short sleep while waiting for a wall-clock deadline.
+ */
+export type WorldTimeDeadlineTick = (remainingDurationMs: number) => void | Promise<void>;
+/**
+ * Waits until one wall-clock deadline has passed.
+ *
+ * The remaining time is recalculated from `Date.now()` after every poll and after every tick callback.
+ * This makes waits elapse while the process is paused at a checkpoint or the computer is asleep.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function waitUntilWorldTimeDeadline(options: {
+    readonly deadlineTimeMs: number;
+    readonly pollIntervalMs: number;
+    readonly onTick?: WorldTimeDeadlineTick;
+}): Promise<void>;

package/esm/src/utils/agents/terminalAgentAvatarVisual.d.ts

@@ -0,0 +1,94 @@
+import { type CreateCanvasForAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
+import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { AsciiArtColorDepth } from '../ascii-art/convertImageDataToAsciiArt';
+/**
+ * Output width of the terminal agent avatar visual in character cells.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export declare const TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS = 48;
+/**
+ * Output height of the terminal agent avatar visual in character cells.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export declare const TERMINAL_AGENT_AVATAR_VISUAL_ROWS = 12;
+/**
+ * Refresh cadence used while a terminal agent avatar visual is animated.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export declare const TERMINAL_AGENT_AVATAR_VISUAL_REFRESH_INTERVAL_MS = 300;
+/**
+ * Options passed when rendering one animated terminal avatar frame.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type TerminalAgentAvatarVisualFrameOptions = {
+    /**
+     * Current animation time forwarded to the shared avatar renderer.
+     */
+    readonly animationTimeMs: number;
+};
+/**
+ * Runtime renderer for an agent avatar visual shown in a terminal.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type TerminalAgentAvatarVisual = {
+    /**
+     * Whether the selected built-in visual changes over time.
+     */
+    readonly isAnimated: boolean;
+    /**
+     * Renders one ANSI ASCII-art frame for the current terminal timestamp.
+     */
+    readonly renderFrame: (options: TerminalAgentAvatarVisualFrameOptions) => ReadonlyArray<string>;
+};
+/**
+ * Options for creating a terminal avatar visual renderer from an agent book source.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type CreateTerminalAgentAvatarVisualOptions = {
+    /**
+     * Source of the agent book whose metadata controls avatar identity.
+     */
+    readonly agentSource: string_book;
+    /**
+     * Built-in avatar visual used when the agent does not declare `META AVATAR` or `META VISUAL`.
+     */
+    readonly defaultAvatarVisualId?: AvatarVisualId;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+/**
+ * Resolves the built-in avatar visual selected for terminal rendering of one agent source.
+ *
+ * @param agentSource Source of the agent book.
+ * @param defaultAvatarVisualId Built-in fallback used when the source does not declare an avatar visual.
+ * @returns Supported built-in avatar visual id.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export declare function resolveTerminalAgentAvatarVisualId(agentSource: string_book, defaultAvatarVisualId?: AvatarVisualId): AvatarVisualId;
+/**
+ * Creates an ANSI ASCII-art avatar renderer for terminal UIs.
+ *
+ * The agent's avatar visual is resolved the same way as on the website: `META AVATAR`
+ * / `META VISUAL` wins, then the provided fallback visual, then the shared default visual.
+ * The terminal variant uses a transparent horizontal canvas instead of the website's framed square surface.
+ *
+ * @param options Agent source, canvas factory, and optional terminal color settings.
+ * @returns Runtime terminal avatar visual renderer.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export declare function createTerminalAgentAvatarVisual(options: CreateTerminalAgentAvatarVisualOptions): TerminalAgentAvatarVisual;

package/esm/src/utils/agents/terminalAgentAvatarVisual.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.113.0-9`).
+ * It follows semantic versioning (e.g., `0.113.0-10`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/node",
-    "version": "0.113.0-10",
+    "version": "0.113.0-11",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -97,7 +97,7 @@
     "types": "./esm/src/_packages/node.index.d.ts",
     "typings": "./esm/src/_packages/node.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.113.0-10"
+        "@promptbook/core": "0.113.0-11"
     },
     "dependencies": {
         "@mozilla/readability": "0.6.0",

package/umd/index.umd.js

@@ -51,7 +51,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-10';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-11';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3076,6 +3076,47 @@
         });
     }
 
+    /**
+     * Minimum timer duration used to avoid a zero-millisecond polling loop.
+     */
+    const MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS = 1;
+    /**
+     * Waits until one wall-clock deadline has passed.
+     *
+     * The remaining time is recalculated from `Date.now()` after every poll and after every tick callback.
+     * This makes waits elapse while the process is paused at a checkpoint or the computer is asleep.
+     *
+     * @private internal utility of `ptbk coder` wait handling
+     */
+    async function waitUntilWorldTimeDeadline(options) {
+        const { deadlineTimeMs, pollIntervalMs, onTick } = options;
+        const normalizedPollIntervalMs = Math.max(MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS, pollIntervalMs);
+        while (true) {
+            const remainingDurationMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationMs <= 0) {
+                return;
+            }
+            await (onTick === null || onTick === void 0 ? void 0 : onTick(remainingDurationMs));
+            const remainingDurationAfterTickMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationAfterTickMs <= 0) {
+                return;
+            }
+            await waitForMilliseconds(Math.min(normalizedPollIntervalMs, remainingDurationAfterTickMs));
+        }
+    }
+    /**
+     * Returns the remaining wall-clock duration until a timestamp.
+     */
+    function getRemainingDurationMs(deadlineTimeMs) {
+        return Math.max(0, deadlineTimeMs - Date.now());
+    }
+    /**
+     * Waits for one short polling interval.
+     */
+    async function waitForMilliseconds(durationMs) {
+        await new Promise((resolve) => setTimeout(resolve, durationMs));
+    }
+
     /**
      * Base delimiter used for passing large prompts through stdin.
      */
@@ -3485,36 +3526,32 @@
      * Waits until the Claude Code session can be resumed, keeping terminal status clear.
      */
     async function waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options) {
-        var _a, _b, _c;
+        var _a, _b;
         const delayMs = getClaudeCodeSessionLimitDelayMs(sessionLimit);
+        const resetDeadlineTimeMs = Date.now() + delayMs;
         const sessionLabel = formatClaudeCodeSessionIdForDisplay(sessionLimit.sessionId);
         const resetSummary = formatClaudeCodeSessionLimitForDisplay(sessionLimit);
         if ((_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true) {
             console.warn(colors__default["default"].yellow(`[claude-code] Session limit detected for ${sessionLimit.sessionId}. Resurrection #${resurrectionCount} will resume with --resume after ${formatDurationMs(delayMs)}. ${resetSummary}`));
         }
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
-                checkpointLabel: 'the Claude Code session limit reset',
-                phase: 'waiting',
-                statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(remainingDelayMs)}`,
-            }));
-            const currentDelayMs = Math.min(CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS, remainingDelayMs);
-            await waitFor$1(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
-        await ((_c = options.waitForPauseCheckpoint) === null || _c === void 0 ? void 0 : _c.call(options, {
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: resetDeadlineTimeMs,
+            pollIntervalMs: CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
+                    checkpointLabel: 'the Claude Code session limit reset',
+                    phase: 'waiting',
+                    statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(Math.min(remainingDelayMs, delayMs))}`,
+                }));
+            },
+        });
+        await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
             checkpointLabel: 'resurrecting the Claude Code session with --resume',
             phase: 'running',
             statusMessage: `Resurrecting Claude Code session ${sessionLabel} with --resume`,
         }));
     }
-    /**
-     * Waits for a fixed amount of milliseconds.
-     */
-    async function waitFor$1(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a Claude Code session id for compact terminal status lines.
      */
@@ -4475,12 +4512,6 @@
      * Randomized delay proportion added/subtracted for retry jitter.
      */
     const RATE_LIMIT_BACKOFF_JITTER_RATIO = 0.15;
-    /**
-     * Waits for one given amount of milliseconds.
-     */
-    async function waitFor(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a delay value into a concise `xh ym zs` style label.
      */
@@ -4570,13 +4601,18 @@
                         throw error;
                     }
                     const delayMs = this.rateLimitBackoff.nextDelayMs();
-                    const retryAt = new Date(Date.now() + delayMs).toISOString();
+                    const retryDeadlineTimeMs = Date.now() + delayMs;
+                    const retryAt = new Date(retryDeadlineTimeMs).toISOString();
                     const retryIndex = this.rateLimitBackoff.retryCount;
                     const summary = extractFailureSummary(details);
                     if ((_b = options.shouldPrintLiveOutput) !== null && _b !== void 0 ? _b : true) {
                         console.warn(colors__default["default"].yellow(`[codex] Rate limit/quota detected (${summary}). Retry #${retryIndex} in ${formatDelay(delayMs)} at ${retryAt}.`));
                     }
-                    await waitForRetryDelay(delayMs, options);
+                    await waitForRetryDelay({
+                        delayMs,
+                        retryDeadlineTimeMs,
+                        promptRunOptions: options,
+                    });
                 }
             }
         }
@@ -4584,20 +4620,21 @@
     /**
      * Waits for the next Codex retry while polling for requested pause checkpoints.
      */
-    async function waitForRetryDelay(delayMs, options) {
-        var _a;
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            const remainingDelayLabel = formatDelay(remainingDelayMs);
-            await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
-                checkpointLabel: 'the next OpenAI Codex retry after rate limit',
-                phase: 'running',
-                statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
-            }));
-            const currentDelayMs = Math.min(RATE_LIMIT_BACKOFF_POLL_MS, remainingDelayMs);
-            await waitFor(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
+    async function waitForRetryDelay(options) {
+        const { delayMs, retryDeadlineTimeMs, promptRunOptions } = options;
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: retryDeadlineTimeMs,
+            pollIntervalMs: RATE_LIMIT_BACKOFF_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                const remainingDelayLabel = formatDelay(Math.min(remainingDelayMs, delayMs));
+                await ((_a = promptRunOptions.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(promptRunOptions, {
+                    checkpointLabel: 'the next OpenAI Codex retry after rate limit',
+                    phase: 'running',
+                    statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
+                }));
+            },
+        });
     }
 
     /**