@promptbook/cli 0.114.0-5 → 0.114.0-7

package/src/utils/agent-message-runtime/resolveAgentMessageRuntimeActivity.ts

@@ -5,6 +5,72 @@
  */
 const MAX_RUNTIME_ACTIVITY_LENGTH = 160;
 
+/**
+ * One safe, concrete category of a command emitted by the Codex runtime.
+ *
+ * @private internal type of agent-message runtime activity
+ */
+type CodexCommandActivity = {
+    readonly pattern: RegExp;
+    readonly running: string;
+    readonly completed: string;
+};
+
+/**
+ * Ordered command categories that can be described truthfully without showing raw commands,
+ * arguments, file names, or other private runtime details.
+ *
+ * The local runner can execute on either Unix or Windows. Keeping the variants together here
+ * ensures that equivalent shell commands yield the same concise status in the chat.
+ *
+ * @private internal constant of agent-message runtime activity
+ */
+const CODEX_COMMAND_ACTIVITIES: ReadonlyArray<CodexCommandActivity> = [
+    {
+        pattern:
+            /(^|\s)(npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|jest|vitest|pytest)\b/u,
+        running: 'Running tests.',
+        completed: 'Finished running tests.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|next\s+build)\b/u,
+        running: 'Building the project.',
+        completed: 'Finished building the project.',
+    },
+    {
+        pattern: /(^|\s)(npm|pnpm|yarn)\s+(?:install|add)\b/u,
+        running: 'Installing dependencies.',
+        completed: 'Finished installing dependencies.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+(?:run\s+)?lint|pnpm\s+(?:run\s+)?lint|yarn\s+lint|eslint|prettier)\b/u,
+        running: 'Checking the implementation.',
+        completed: 'Finished checking the implementation.',
+    },
+    {
+        pattern: /(^|\s)git\s+(?:status|diff|log|show)\b/u,
+        running: 'Reviewing changes.',
+        completed: 'Finished reviewing changes.',
+    },
+    {
+        pattern:
+            /(^|\s)(apply_patch|set-content|add-content|out-file|new-item|copy-item|move-item|set-item)\b/u,
+        running: 'Updating relevant files.',
+        completed: 'Finished updating relevant files.',
+    },
+    {
+        pattern:
+            /(^|\s)(ls|find|rg|grep|sed|cat|head|tail|get-content|get-childitem|get-item|select-string|findstr|type)\b/u,
+        running: 'Inspecting relevant files.',
+        completed: 'Finished inspecting relevant files.',
+    },
+    {
+        pattern: /(^|\s)(curl|wget|invoke-webrequest)\b/u,
+        running: 'Looking up information.',
+        completed: 'Finished looking up information.',
+    },
+];
+
 /**
  * Minimal shape of one coding-harness `stream-json` event relevant to progress extraction.
  *
@@ -35,9 +101,9 @@ type RuntimeLogEvent = {
  * Claude Code `--output-format stream-json`) into a live runtime log file next to the queued
  * message. This helper extracts the most recent natural-language assistant narration so the
  * durable chat can show what the agent is doing right now instead of a generic thinking
- * placeholder. Only plain assistant text is surfaced; raw tool payloads, JSON envelopes and
- * other technical details are intentionally ignored, and harnesses that do not stream
- * structured text simply resolve to `null` so the caller keeps its existing behavior.
+ * placeholder. Only concrete, safe activity is surfaced; raw tool payloads, JSON envelopes,
+ * and private reasoning are intentionally ignored. When no concrete activity is known, this
+ * resolves to `null` so the caller keeps the browser's rotating generic thinking state.
  *
  * @param logText - Raw runtime log content.
  * @returns Latest human-readable activity snippet, or `null` when none can be resolved.
@@ -118,6 +184,9 @@ function resolveRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
  *
  * Codex reasoning and raw command text deliberately remain private. The event type tells us
  * enough to report a useful action without exposing the internal trace or a command payload.
+ * Reasoning events are intentionally not a progress update: while they are the only signal,
+ * the chat retains its configured generic thinking rotation. Once a concrete action arrives,
+ * it becomes the latest user-facing status instead.
  *
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
@@ -130,7 +199,7 @@ function resolveCodexRuntimeLogEventActivity(event: RuntimeLogEvent): string | n
 
     switch (event.item.type) {
         case 'reasoning':
-            return isCompleted ? 'Considered the request.' : 'Considering the request.';
+            return null;
         case 'command_execution':
             return resolveCodexCommandActivity(event.item.command, isCompleted, event.item.exit_code);
         case 'file_change':
@@ -164,12 +233,16 @@ function resolveCodexCommandActivity(
     command: string | undefined,
     isCompleted: boolean,
     exitCode: number | null | undefined,
-): string {
+): string | null {
     if (isCompleted && exitCode !== undefined && exitCode !== null && exitCode !== 0) {
         return 'A command needs attention.';
     }
 
     const activity = resolveCodexCommandActivityLabel(command);
+    if (!activity) {
+        return null;
+    }
+
     return isCompleted ? activity.completed : activity.running;
 }
 
@@ -178,30 +251,10 @@ function resolveCodexCommandActivity(
  *
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
-function resolveCodexCommandActivityLabel(command: string | undefined): { running: string; completed: string } {
+function resolveCodexCommandActivityLabel(command: string | undefined): CodexCommandActivity | null {
     const normalizedCommand = command?.toLowerCase() || '';
 
-    if (/(^|\s)(npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|jest|vitest|pytest)\b/u.test(normalizedCommand)) {
-        return { running: 'Running tests.', completed: 'Finished running tests.' };
-    }
-
-    if (/(^|\s)(npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|next\s+build)\b/u.test(normalizedCommand)) {
-        return { running: 'Building the project.', completed: 'Finished building the project.' };
-    }
-
-    if (/(^|\s)(npm|pnpm|yarn)\s+(?:install|add)\b/u.test(normalizedCommand)) {
-        return { running: 'Installing dependencies.', completed: 'Finished installing dependencies.' };
-    }
-
-    if (/(^|\s)git\s+(?:status|diff|log|show)\b/u.test(normalizedCommand)) {
-        return { running: 'Reviewing changes.', completed: 'Finished reviewing changes.' };
-    }
-
-    if (/(^|\s)(ls|find|rg|grep|sed|cat|head|tail)\b/u.test(normalizedCommand)) {
-        return { running: 'Inspecting relevant files.', completed: 'Finished inspecting relevant files.' };
-    }
-
-    return { running: 'Running a task.', completed: 'Finished a task.' };
+    return CODEX_COMMAND_ACTIVITIES.find((activity) => activity.pattern.test(normalizedCommand)) ?? null;
 }
 
 /**

package/src/utils/agents/terminalAgentAvatarVisual.ts

@@ -6,6 +6,7 @@ import type { ResolvedAvatarRenderDefinition } from '../../avatars/renderAvatarV
 import { resolveAvatarRenderDefinition } from '../../avatars/renderAvatarVisual';
 import type { CreateCanvasForAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
 import { renderAvatarVisualAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
+import { renderAvatarVisualTerminalTextLines } from '../../avatars/renderAvatarVisualTerminalText';
 import type { AvatarDefinition } from '../../avatars/types/AvatarDefinition';
 import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
 import { resolveAvatarVisualId } from '../../avatars/visuals/avatarVisualRegistry';
@@ -127,9 +128,12 @@ export type CreateTerminalAgentAvatarVisualOptions = {
     readonly colorDepth?: AsciiArtColorDepth;
 
     /**
-     * Platform-specific canvas factory used to rasterize the visual.
+     * Platform-specific canvas factory used to rasterize pixel-based visuals.
+     *
+     * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, so they
+     * render without any canvas; a pixel-based visual renders an empty frame when it is missing.
      */
-    readonly createCanvas: CreateCanvasForAsciiArt;
+    readonly createCanvas?: CreateCanvasForAsciiArt;
 };
 
 /**
@@ -251,15 +255,39 @@ function resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(
 /**
  * Renders one terminal avatar frame through the shared avatar-to-ASCII pipeline.
  *
+ * Visuals which are made of characters themselves, for example `AsciiOctopus`, paint the terminal
+ * character grid directly, because rasterizing them into half-block ASCII art averages every glyph
+ * away and makes them indistinguishable from the other blob-shaped visuals.
+ *
  * @private shared helper for terminal avatar rendering
  */
 function renderTerminalAgentAvatarVisualFrame(
     options: TerminalAgentAvatarVisualRenderInputs & {
         readonly animationTimeMs: number;
         readonly colorDepth?: AsciiArtColorDepth;
-        readonly createCanvas: CreateCanvasForAsciiArt;
+        readonly createCanvas?: CreateCanvasForAsciiArt;
     },
 ): ReadonlyArray<string> {
+    const terminalTextLines = renderAvatarVisualTerminalTextLines({
+        avatarDefinition: options.avatarDefinition,
+        visualId: options.avatarVisualId,
+        surface: 'transparent',
+        columns: TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS,
+        rows: TERMINAL_AGENT_AVATAR_VISUAL_ROWS,
+        colorDepth: options.colorDepth,
+        timeMs: options.animationTimeMs,
+        resolvedAvatarRenderDefinition: options.resolvedAvatarRenderDefinition,
+    });
+
+    if (terminalTextLines !== null) {
+        return terminalTextLines;
+    }
+
+    if (options.createCanvas === undefined) {
+        // Note: A pixel-based visual cannot be rasterized without a canvas, so the caller keeps its default banner
+        return [];
+    }
+
     return renderAvatarVisualAsciiArt({
         avatarDefinition: options.avatarDefinition,
         visualId: options.avatarVisualId,

package/src/utils/ascii-art/convertImageDataToAsciiArt.ts

@@ -1,5 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../errors/UnexpectedError';
+import type { AnsiRgbColor } from './createAnsiColorCode';
+import { ANSI_RESET, createAnsiBackgroundColorCode, createAnsiForegroundColorCode } from './createAnsiColorCode';
 
 /**
  * Color depth of the ANSI escape codes emitted by the ASCII-art conversion.
@@ -75,11 +77,11 @@ export type ConvertImageDataToAsciiArtOptions = {
 };
 
 /**
- * Default alpha channel value below which a half-cell is rendered as terminal background.
+ * Default alpha channel value below which a cell is rendered as terminal background.
  *
  * @private within the repository
  */
-const DEFAULT_ALPHA_THRESHOLD = 32;
+export const DEFAULT_ALPHA_THRESHOLD = 32;
 
 /**
  * Number of channels per pixel in an RGBA buffer.
@@ -102,57 +104,12 @@ const UPPER_HALF_BLOCK = '▀'; // <- ▀
  */
 const LOWER_HALF_BLOCK = '▄'; // <- ▄
 
-/**
- * ANSI escape sequence that resets all colors and attributes.
- *
- * @private within the repository
- */
-const ANSI_RESET = '\u001b[0m';
-
-/**
- * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
- *
- * @private within the repository
- */
-const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
-
-/**
- * Gray level above which an achromatic color maps to the pure white color-cube entry.
- *
- * @private within the repository
- */
-const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
-
-/**
- * Index of pure white inside the 6×6×6 ANSI color cube.
- *
- * @private within the repository
- */
-const ANSI_256_WHITE_INDEX = 231;
-
-/**
- * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
-
-/**
- * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
-
 /**
  * Area-averaged color of one half of a character cell.
  *
  * @private helper of `convertImageDataToAsciiArt`
  */
-type HalfCellColor = {
-    readonly red: number;
-    readonly green: number;
-    readonly blue: number;
+type HalfCellColor = AnsiRgbColor & {
     readonly isOpaque: boolean;
 };
 
@@ -231,15 +188,15 @@ export function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOp
 
             if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = createAnsiBackgroundColorCode(bottomHalfColor, colorDepth);
             } else if (topHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else if (bottomHalfColor.isOpaque) {
                 character = LOWER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(bottomHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else {
                 character = ' ';
@@ -337,60 +294,3 @@ function computeHalfCellColor(
         isOpaque: true,
     };
 }
-
-/**
- * Creates the ANSI escape code that sets the foreground color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createForegroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Creates the ANSI escape code that sets the background color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createBackgroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
- *
- * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function mapColorToAnsi256(color: HalfCellColor): number {
-    const { red, green, blue } = color;
-
-    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
-    const maxChannel = Math.max(red, green, blue);
-    const minChannel = Math.min(red, green, blue);
-    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
-        const gray = Math.round((red + green + blue) / 3);
-        if (gray < 4) {
-            return 16; // <- Note: Pure black lives in the color cube
-        }
-        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
-            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
-        }
-        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
-    }
-
-    const redIndex = Math.round((red / 255) * 5);
-    const greenIndex = Math.round((green / 255) * 5);
-    const blueIndex = Math.round((blue / 255) * 5);
-
-    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
-}

package/src/utils/ascii-art/createAnsiColorCode.ts

@@ -0,0 +1,132 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export const ANSI_RESET = '\u001b[0m';
+
+/**
+ * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
+ *
+ * @private within the repository
+ */
+const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
+
+/**
+ * Gray level above which an achromatic color maps to the pure white color-cube entry.
+ *
+ * @private within the repository
+ */
+const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
+
+/**
+ * Index of pure white inside the 6×6×6 ANSI color cube.
+ *
+ * @private within the repository
+ */
+const ANSI_256_WHITE_INDEX = 231;
+
+/**
+ * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
+
+/**
+ * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
+
+/**
+ * One opaque 24-bit color which should be written into an ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export type AnsiRgbColor = {
+    /**
+     * Red channel in the range `[0, 255]`.
+     */
+    readonly red: number;
+
+    /**
+     * Green channel in the range `[0, 255]`.
+     */
+    readonly green: number;
+
+    /**
+     * Blue channel in the range `[0, 255]`.
+     */
+    readonly blue: number;
+};
+
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @param color Color painted onto the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * Creates the ANSI escape code that sets the background color of following characters.
+ *
+ * @param color Color painted behind the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
+ *
+ * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
+ *
+ * @private helper of `createAnsiForegroundColorCode` and `createAnsiBackgroundColorCode`
+ */
+function mapColorToAnsi256(color: AnsiRgbColor): number {
+    const { red, green, blue } = color;
+
+    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
+    const maxChannel = Math.max(red, green, blue);
+    const minChannel = Math.min(red, green, blue);
+    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
+        const gray = Math.round((red + green + blue) / 3);
+        if (gray < 4) {
+            return 16; // <- Note: Pure black lives in the color cube
+        }
+        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
+            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
+        }
+        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
+    }
+
+    const redIndex = Math.round((red / 255) * 5);
+    const greenIndex = Math.round((green / 255) * 5);
+    const blueIndex = Math.round((blue / 255) * 5);
+
+    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+}

package/src/utils/misc/debounce.ts

@@ -1,14 +1,35 @@
 import type { TODO_any } from '../organization/TODO_any';
 
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
-export function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number) {
+export function debounce<T extends (...args: TODO_any[]) => void>(
+    fn: T,
+    delay: number,
+): ((...args: Parameters<T>) => void) & { cancel: () => void } {
     let timeout: ReturnType<typeof setTimeout> | null = null;
-    return (...args: Parameters<T>) => {
-        if (timeout) clearTimeout(timeout);
-        timeout = setTimeout(() => fn(...args), delay);
+
+    const cancel = () => {
+        if (timeout === null) {
+            return;
+        }
+
+        clearTimeout(timeout);
+        timeout = null;
     };
+
+    const debounced = (...args: Parameters<T>) => {
+        cancel();
+
+        timeout = setTimeout(() => {
+            timeout = null;
+            fn(...args);
+        }, delay);
+    };
+
+    debounced.cancel = cancel;
+
+    return debounced;
 }

package/src/version.ts

@@ -16,11 +16,11 @@ export const BOOK_LANGUAGE_VERSION: string_semantic_version = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.114.0-5';
+export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.114.0-7';
 
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-4`).
+ * It follows semantic versioning (e.g., `0.114.0-6`).
  *
  * @generated
  */

package/src/versions.txt

@@ -1183,3 +1183,5 @@
 0.114.0-3
 0.114.0-4
 0.114.0-5
+0.114.0-6
+0.114.0-7