@promptbook/cli 0.113.0-4 → 0.113.0-5

package/esm/index.es.js

@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-4';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-5';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4543,7 +4543,7 @@ function buildCoderRunUiFrame(options) {
     const visibleOutputLines = buildVisibleOutputLines(options.agentOutputLines);
     const controls = buildControlPills(pausePresentation.pauseControl, options.pendingEnterLabel).join('  ');
     const frame = [
-        ...buildCoderRunOctopusVisual({ totalWidth, animationFrame: octopusAnimationFrame }),
+        ...buildFrameHeaderVisual(options, totalWidth, octopusAnimationFrame),
         '',
         ...renderBox('Session', sessionLines, totalWidth, colors.yellow.bold),
         ...renderBox(options.currentPromptLabel ? 'Current task' : 'Queue', currentTaskLines, totalWidth, colors.magenta.bold),
@@ -4555,6 +4555,18 @@ function buildCoderRunUiFrame(options) {
     frame.push(...renderBox('Controls', [controls], totalWidth, colors.white.bold));
     return frame;
 }
+/**
+ * Builds the header visual above the dashboard boxes.
+ *
+ * Shows the ASCII-art `--agent` avatar visual when one is available and
+ * falls back to the default brand banner otherwise.
+ */
+function buildFrameHeaderVisual(options, totalWidth, octopusAnimationFrame) {
+    if (options.agentVisualLines !== undefined && options.agentVisualLines.length > 0) {
+        return options.agentVisualLines.map((agentVisualLine) => centerAnsiText(agentVisualLine, totalWidth));
+    }
+    return buildCoderRunOctopusVisual({ totalWidth, animationFrame: octopusAnimationFrame });
+}
 /**
  * Builds the structured session lines that combine state, runner, queue, and timing metadata.
  */
@@ -4855,6 +4867,13 @@ class CoderRunUiState extends EventEmitter {
         this.config = config;
         this.emitChange();
     }
+    /**
+     * Replaces the ASCII-art agent visual shown instead of the default brand banner.
+     */
+    setAgentVisualLines(agentVisualLines) {
+        this.agentVisualLines = agentVisualLines === undefined ? undefined : [...agentVisualLines];
+        this.emitChange();
+    }
     /**
      * Feeds new prompt statistics from the main loop so the progress bar updates.
      */
@@ -5190,6 +5209,7 @@ function renderCoderRunUi(startTime, options = {}) {
             pauseState: getPauseState(),
             pauseTargetLabel: getPauseTargetLabel(),
             config: state.config,
+            agentVisualLines: state.agentVisualLines,
             phase: state.phase,
             currentPromptLabel: state.currentPromptLabel,
             currentScriptPaths: state.currentScriptPaths,
@@ -9831,12 +9851,150 @@ function darken(amount) {
 }
 
 /* eslint-disable no-magic-numbers */
+// Note: [💞] Ignore a discrepancy between file name and entity name
+/**
+ * Default square size used by avatar renderers.
+ *
+ * @private utility of the avatar rendering system
+ */
+const DEFAULT_AVATAR_SIZE = 192;
+/**
+ * Default fallback hash used when no explicit hash is provided.
+ *
+ * @private utility of the avatar rendering system
+ */
+const DEFAULT_AVATAR_HASH = '0000000000000000000000000000000000000000000000000000000000000000';
+/**
+ * Default fallback name used when no explicit name is provided.
+ *
+ * @private utility of the avatar rendering system
+ */
+const DEFAULT_AVATAR_NAME = 'Anonymous Agent';
 /**
  * Corner radius ratio used for the common rounded card frame.
  *
  * @private utility of the avatar rendering system
  */
 const FRAME_RADIUS_RATIO = 0.18;
+/**
+ * Normalizes arbitrary agent colors into a stable non-empty color list.
+ *
+ * @param colors Raw color list.
+ * @returns Stable list of usable colors.
+ *
+ * @private utility of the avatar rendering system
+ */
+function normalizeAvatarColors(colors) {
+    const normalizedColors = colors
+        .map((color) => String(color).trim())
+        .filter((color) => color !== '')
+        .map((color) => Color.fromSafe(color).toHex());
+    if (normalizedColors.length > 0) {
+        return normalizedColors;
+    }
+    return [PROMPTBOOK_COLOR.toHex()];
+}
+/**
+ * Normalizes the avatar input so visuals can rely on consistent data.
+ *
+ * @param avatarDefinition Raw avatar input.
+ * @returns Normalized avatar definition.
+ *
+ * @private utility of the avatar rendering system
+ */
+function normalizeAvatarDefinition(avatarDefinition) {
+    return {
+        agentName: (avatarDefinition.agentName || DEFAULT_AVATAR_NAME).trim() || DEFAULT_AVATAR_NAME,
+        agentHash: (avatarDefinition.agentHash || DEFAULT_AVATAR_HASH).trim() || DEFAULT_AVATAR_HASH,
+        colors: normalizeAvatarColors(avatarDefinition.colors),
+    };
+}
+/**
+ * Extracts avatar colors from the flexible `META COLOR` agent field.
+ *
+ * @param colorValue Raw `META COLOR` value.
+ * @returns Parsed avatar colors.
+ *
+ * @private utility of the avatar rendering system
+ */
+function parseAvatarColors(colorValue) {
+    if (!colorValue) {
+        return [];
+    }
+    const colors = [];
+    let currentColor = '';
+    let bracketDepth = 0;
+    for (const character of colorValue) {
+        if (character === '(') {
+            bracketDepth++;
+            currentColor += character;
+            continue;
+        }
+        if (character === ')') {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            currentColor += character;
+            continue;
+        }
+        if (bracketDepth === 0 && [',', ';', '|', '\n'].includes(character)) {
+            const normalizedColor = currentColor.trim();
+            if (normalizedColor !== '') {
+                colors.push(normalizedColor);
+            }
+            currentColor = '';
+            continue;
+        }
+        currentColor += character;
+    }
+    const lastColor = currentColor.trim();
+    if (lastColor !== '') {
+        colors.push(lastColor);
+    }
+    return colors;
+}
+/**
+ * Creates a reusable avatar definition from parsed agent information.
+ *
+ * @param agentBasicInformation Parsed agent information.
+ * @returns Avatar definition ready for canvas rendering.
+ *
+ * @private shared helper for app-level avatar previews
+ */
+function createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation) {
+    return normalizeAvatarDefinition({
+        agentName: agentBasicInformation.agentName,
+        agentHash: agentBasicInformation.agentHash,
+        colors: parseAvatarColors(agentBasicInformation.meta.color),
+    });
+}
+/**
+ * Creates the shared derived palette used by every avatar visual.
+ *
+ * @param avatarDefinition Stable avatar definition.
+ * @param surface Surface style used by the parent UI.
+ * @returns Derived palette.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createAvatarPalette(avatarDefinition, surface = 'framed') {
+    const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
+    const primaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[0] || PROMPTBOOK_COLOR);
+    const secondaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[1] || primaryColor.then(lighten(0.12)).then(saturate(0.16)));
+    const accentColor = Color.fromSafe(normalizedAvatarDefinition.colors[2] || primaryColor.then(saturate(0.32)).then(lighten(0.22)));
+    const backgroundColor = Color.fromSafe(primaryColor.then(darken(0.34)).then(saturate(-0.1)));
+    const backgroundSecondaryColor = Color.fromSafe(secondaryColor.then(darken(0.42)).then(saturate(-0.16)).then(lighten(0.04)));
+    const highlightColor = Color.fromSafe(accentColor.then(lighten(0.22)).then(saturate(0.08)));
+    const shadowColor = Color.fromSafe(primaryColor.then(darken(0.46)).then(saturate(0.14)));
+    return {
+        background: surface === 'transparent' ? 'transparent' : backgroundColor.toHex(),
+        backgroundSecondary: surface === 'transparent' ? 'transparent' : backgroundSecondaryColor.toHex(),
+        primary: primaryColor.toHex(),
+        secondary: secondaryColor.toHex(),
+        accent: accentColor.toHex(),
+        highlight: highlightColor.toHex(),
+        shadow: shadowColor.toHex(),
+        ink: createInkColor(primaryColor),
+    };
+}
 /**
  * Draws the common rounded background frame used by most visuals.
  *
@@ -9887,6 +10045,67 @@ function createRoundedRectPath(context, x, y, width, height, radius) {
     context.arcTo(x, y, x + width, y, normalizedRadius);
     context.closePath();
 }
+/**
+ * Creates a stable pseudo-random number generator from a string seed.
+ *
+ * @param seedSource String seed.
+ * @returns Generator producing values in `[0, 1)`.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createSeededRandom(seedSource) {
+    let state = hashStringToUint32(seedSource) || 0x9e3779b9;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let hash = Math.imul(state ^ (state >>> 15), 1 | state);
+        hash ^= hash + Math.imul(hash ^ (hash >>> 7), 61 | hash);
+        return ((hash ^ (hash >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Creates a deterministic random factory scoped to the avatar definition.
+ *
+ * @param avatarDefinition Stable avatar definition.
+ * @returns Random factory that can be re-seeded per visual part.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createAvatarRandomFactory(avatarDefinition) {
+    const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
+    const seedBase = `${normalizedAvatarDefinition.agentName}|${normalizedAvatarDefinition.agentHash}|${normalizedAvatarDefinition.colors.join('|')}`;
+    return (salt) => createSeededRandom(`${seedBase}|${salt}`);
+}
+/**
+ * Clears and scales the canvas for crisp avatar rendering on high DPI displays.
+ *
+ * @param canvas Canvas element to prepare.
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param devicePixelRatio Device pixel ratio.
+ *
+ * @private utility of the avatar rendering system
+ */
+function prepareAvatarCanvas(canvas, context, size, devicePixelRatio) {
+    const normalizedDevicePixelRatio = Math.max(1, Math.round(devicePixelRatio * 100) / 100);
+    const nextCanvasWidth = Math.round(size * normalizedDevicePixelRatio);
+    const nextCanvasHeight = Math.round(size * normalizedDevicePixelRatio);
+    const nextCanvasStyleWidth = `${size}px`;
+    const nextCanvasStyleHeight = `${size}px`;
+    if (canvas.width !== nextCanvasWidth) {
+        canvas.width = nextCanvasWidth;
+    }
+    if (canvas.height !== nextCanvasHeight) {
+        canvas.height = nextCanvasHeight;
+    }
+    if (canvas.style.width !== nextCanvasStyleWidth) {
+        canvas.style.width = nextCanvasStyleWidth;
+    }
+    if (canvas.style.height !== nextCanvasStyleHeight) {
+        canvas.style.height = nextCanvasStyleHeight;
+    }
+    context.setTransform(normalizedDevicePixelRatio, 0, 0, normalizedDevicePixelRatio, 0, 0);
+    context.clearRect(0, 0, size, size);
+}
 /**
  * Picks one deterministic element from a non-empty collection.
  *
@@ -9899,6 +10118,37 @@ function createRoundedRectPath(context, x, y, width, height, radius) {
 function pickRandomItem(items, random) {
     return items[Math.floor(random() * items.length)];
 }
+/**
+ * Creates a readable ink color from the given base color.
+ *
+ * @param color Base color.
+ * @returns High-contrast ink color.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createInkColor(color) {
+    const perceivedBrightness = color.red * 0.299 + color.green * 0.587 + color.blue * 0.114;
+    if (perceivedBrightness > 150) {
+        return '#172033';
+    }
+    return '#f8fbff';
+}
+/**
+ * Hashes an arbitrary string into a 32-bit unsigned integer.
+ *
+ * @param value Arbitrary input.
+ * @returns 32-bit unsigned integer hash.
+ *
+ * @private utility of the avatar rendering system
+ */
+function hashStringToUint32(value) {
+    let hash = 2166136261;
+    for (const character of value) {
+        hash ^= character.charCodeAt(0);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
 
 /* eslint-disable no-magic-numbers */
 /**
@@ -15886,6 +16136,21 @@ function normalizeAvatarVisualLookupKey(value) {
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '');
 }
+/**
+ * Returns one avatar visual by its identifier.
+ *
+ * @param visualId Requested visual identifier.
+ * @returns Matching visual definition.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+function getAvatarVisualById(visualId) {
+    const avatarVisual = AVATAR_VISUALS.find((candidateAvatarVisual) => candidateAvatarVisual.id === visualId);
+    if (!avatarVisual) {
+        throw new Error(`Unknown avatar visual "${visualId}".`);
+    }
+    return avatarVisual;
+}
 /**
  * Resolves a user-facing avatar visual value to a supported built-in visual id.
  *
@@ -28466,7 +28731,7 @@ function buildClaudeScript(options) {
     const MODEL_ARGUMENT = options.model ? ` --model ${options.model}` : '';
     const THINKING_LEVEL_ARGUMENT = options.thinkingLevel ? ` --effort ${options.thinkingLevel}` : '';
     return spaceTrim((block) => `
-            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format json --print <<'${CLAUDE_PROMPT_DELIMITER}'
+            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
 
             ${block(options.prompt)}
 
@@ -71222,7 +71487,7 @@ async function recordPromptDurationSample(key, promptDurationMs) {
  *
  * Returns `undefined` when no agent path is provided.
  */
-async function resolveAgentSystemMessage(agentPath, currentWorkingDirectory) {
+async function resolveCoderAgent(agentPath, currentWorkingDirectory) {
     if (!agentPath) {
         return undefined;
     }
@@ -71237,7 +71502,10 @@ async function resolveAgentSystemMessage(agentPath, currentWorkingDirectory) {
         }
         throw error;
     });
-    return createAgentRunnerSystemMessage(agentSource);
+    return {
+        agentSource: agentSource,
+        systemMessage: await createAgentRunnerSystemMessage(agentSource),
+    };
 }
 
 /**
@@ -71435,6 +71703,498 @@ async function waitForPromptStart(file, section, isFirstPrompt) {
     await waitForEnter(colors.bgWhite(`Press Enter to start the ${label}...`));
 }
 
+/**
+ * Default alpha channel value below which a half-cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+const DEFAULT_ALPHA_THRESHOLD = 32;
+/**
+ * Number of channels per pixel in an RGBA buffer.
+ *
+ * @private within the repository
+ */
+const RGBA_CHANNEL_COUNT = 4;
+/**
+ * Upper half block character - foreground paints the top pixel, background paints the bottom pixel.
+ *
+ * @private within the repository
+ */
+const UPPER_HALF_BLOCK = '▀'; // <- ▀
+/**
+ * Lower half block character - foreground paints the bottom pixel while the top pixel stays transparent.
+ *
+ * @private within the repository
+ */
+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;
+/**
+ * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
+ *
+ * This is the universal image-to-terminal technique used across the repository:
+ * every output character cell covers a rectangular region of source pixels which is
+ * split into a top and bottom half; each half is area-averaged and rendered with
+ * half-block characters (`▀` / `▄`) so one character shows two "pixels" vertically.
+ * Transparent halves keep the terminal background so non-rectangular images
+ * (for example rounded avatar cards) compose naturally into any terminal UI.
+ *
+ * @param options Source pixels, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, each ending with a color reset.
+ *
+ * @private within the repository
+ */
+function convertImageDataToAsciiArt(options) {
+    const { imageData, columns, rows, colorDepth = 'TRUE_COLOR', alphaThreshold = DEFAULT_ALPHA_THRESHOLD } = options;
+    if (!Number.isInteger(columns) || columns <= 0 || !Number.isInteger(rows) || rows <= 0) {
+        throw new UnexpectedError(spaceTrim$1(`
+                ASCII-art grid size is invalid.
+
+                Both \`columns\` and \`rows\` must be positive integers but \`${columns}\` × \`${rows}\` was requested.
+            `));
+    }
+    if (imageData.width <= 0 ||
+        imageData.height <= 0 ||
+        imageData.data.length < imageData.width * imageData.height * RGBA_CHANNEL_COUNT) {
+        throw new UnexpectedError(spaceTrim$1(`
+                ASCII-art source image data is invalid.
+
+                Expected a RGBA buffer of at least \`${imageData.width} × ${imageData.height} × ${RGBA_CHANNEL_COUNT}\` bytes
+                but got \`${imageData.data.length}\` bytes.
+            `));
+    }
+    const halfCellRowCount = rows * 2;
+    const asciiArtLines = [];
+    for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+        let line = '';
+        let currentForegroundCode = undefined;
+        let currentBackgroundCode = undefined;
+        for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
+            const topHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2, columns, halfCellRowCount, alphaThreshold);
+            const bottomHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2 + 1, columns, halfCellRowCount, alphaThreshold);
+            let character;
+            let nextForegroundCode;
+            let nextBackgroundCode;
+            if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
+                character = UPPER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+            }
+            else if (topHalfColor.isOpaque) {
+                character = UPPER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = undefined;
+            }
+            else if (bottomHalfColor.isOpaque) {
+                character = LOWER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                nextBackgroundCode = undefined;
+            }
+            else {
+                character = ' ';
+                nextForegroundCode = undefined;
+                nextBackgroundCode = undefined;
+            }
+            if (nextForegroundCode !== currentForegroundCode || nextBackgroundCode !== currentBackgroundCode) {
+                // Note: A reset is required whenever a previously set color must be cleared,
+                //       otherwise stale background color would bleed into transparent cells.
+                const isResetNeeded = (currentForegroundCode !== undefined && nextForegroundCode === undefined) ||
+                    (currentBackgroundCode !== undefined && nextBackgroundCode === undefined);
+                if (isResetNeeded) {
+                    line += ANSI_RESET;
+                    currentForegroundCode = undefined;
+                    currentBackgroundCode = undefined;
+                }
+                if (nextForegroundCode !== undefined && nextForegroundCode !== currentForegroundCode) {
+                    line += nextForegroundCode;
+                }
+                if (nextBackgroundCode !== undefined && nextBackgroundCode !== currentBackgroundCode) {
+                    line += nextBackgroundCode;
+                }
+                currentForegroundCode = nextForegroundCode;
+                currentBackgroundCode = nextBackgroundCode;
+            }
+            line += character;
+        }
+        if (currentForegroundCode !== undefined || currentBackgroundCode !== undefined) {
+            line += ANSI_RESET;
+        }
+        asciiArtLines.push(line);
+    }
+    return asciiArtLines;
+}
+/**
+ * Computes the area-averaged color of one half-cell of the output grid.
+ *
+ * Color channels are alpha-weighted so semi-transparent edge pixels do not darken towards black.
+ *
+ * @private helper of `convertImageDataToAsciiArt`
+ */
+function computeHalfCellColor(imageData, columnIndex, halfCellRowIndex, columns, halfCellRowCount, alphaThreshold) {
+    const startX = Math.floor((columnIndex * imageData.width) / columns);
+    const endX = Math.max(startX + 1, Math.floor(((columnIndex + 1) * imageData.width) / columns));
+    const startY = Math.floor((halfCellRowIndex * imageData.height) / halfCellRowCount);
+    const endY = Math.max(startY + 1, Math.floor(((halfCellRowIndex + 1) * imageData.height) / halfCellRowCount));
+    let redSum = 0;
+    let greenSum = 0;
+    let blueSum = 0;
+    let alphaSum = 0;
+    let sampledPixelCount = 0;
+    for (let y = startY; y < endY && y < imageData.height; y++) {
+        for (let x = startX; x < endX && x < imageData.width; x++) {
+            const pixelOffset = (y * imageData.width + x) * RGBA_CHANNEL_COUNT;
+            const alpha = imageData.data[pixelOffset + 3];
+            redSum += imageData.data[pixelOffset] * alpha;
+            greenSum += imageData.data[pixelOffset + 1] * alpha;
+            blueSum += imageData.data[pixelOffset + 2] * alpha;
+            alphaSum += alpha;
+            sampledPixelCount++;
+        }
+    }
+    const averageAlpha = sampledPixelCount === 0 ? 0 : alphaSum / sampledPixelCount;
+    if (averageAlpha < alphaThreshold || alphaSum === 0) {
+        return { red: 0, green: 0, blue: 0, isOpaque: false };
+    }
+    return {
+        red: Math.round(redSum / alphaSum),
+        green: Math.round(greenSum / alphaSum),
+        blue: Math.round(blueSum / alphaSum),
+        isOpaque: true,
+    };
+}
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @private helper of `convertImageDataToAsciiArt`
+ */
+function createForegroundColorCode(color, colorDepth) {
+    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, colorDepth) {
+    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) {
+    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;
+}
+
+/**
+ * Stable zeroed interaction state used by non-interactive render paths.
+ *
+ * @private utility of the avatar rendering system
+ */
+const IDLE_AVATAR_INTERACTION_STATE = {
+    gazeX: 0,
+    gazeY: 0,
+    bodyOffsetX: 0,
+    bodyOffsetY: 0,
+    intensity: 0,
+    isPointerActive: false,
+    pointerType: 'idle',
+};
+/**
+ * Returns the neutral interaction state used by static/server-side renders.
+ *
+ * @returns Zeroed interaction state.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createIdleAvatarInteractionState() {
+    return IDLE_AVATAR_INTERACTION_STATE;
+}
+
+/**
+ * Resolves the stable avatar render inputs reused across multiple frames.
+ *
+ * @param options Avatar identity and visual selection.
+ * @returns Stable render data ready to be used by `renderAvatarVisual`.
+ *
+ * @private shared helper for canvas avatar rendering
+ */
+function resolveAvatarRenderDefinition(options) {
+    const avatarDefinition = normalizeAvatarDefinition(options.avatarDefinition);
+    const surface = options.surface || 'framed';
+    return {
+        avatarDefinition,
+        avatarVisual: getAvatarVisualById(options.visualId),
+        surface,
+        palette: createAvatarPalette(avatarDefinition, surface),
+        createRandom: createAvatarRandomFactory(avatarDefinition),
+    };
+}
+/**
+ * Renders one deterministic avatar frame into the provided canvas.
+ *
+ * @param options Rendering options.
+ * @param resolvedAvatarRenderDefinition Optional stable render data reused between frames.
+ *
+ * @private shared helper for canvas avatar rendering
+ */
+function renderAvatarVisual(options, resolvedAvatarRenderDefinition) {
+    const resolvedRenderDefinition = resolvedAvatarRenderDefinition ||
+        resolveAvatarRenderDefinition({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+        });
+    const context = options.canvas.getContext('2d');
+    if (!context) {
+        throw new Error('2D canvas rendering context is unavailable.');
+    }
+    prepareAvatarCanvas(options.canvas, context, options.size, options.devicePixelRatio || 1);
+    resolvedRenderDefinition.avatarVisual.render({
+        canvas: options.canvas,
+        context,
+        size: options.size,
+        devicePixelRatio: options.devicePixelRatio || 1,
+        timeMs: options.timeMs,
+        avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+        palette: resolvedRenderDefinition.palette,
+        createRandom: resolvedRenderDefinition.createRandom,
+        surface: resolvedRenderDefinition.surface,
+        interaction: options.interaction || createIdleAvatarInteractionState(),
+    });
+}
+
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+/**
+ * Stable animation timestamp used when rasterizing animated avatar visuals into a static ASCII frame.
+ *
+ * @private within the repository
+ */
+const STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS = 840;
+/**
+ * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+ *
+ * This is the universal bridge between the canvas avatar visuals shown on the website and
+ * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+ * pipeline the web uses, then the resulting pixels are converted into colored half-block
+ * characters by `convertImageDataToAsciiArt`.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+ * @returns One ANSI-colored string per output row.
+ *
+ * @private within the repository
+ */
+function renderAvatarVisualAsciiArt(options) {
+    var _a, _b, _c;
+    const columns = (_a = options.columns) !== null && _a !== void 0 ? _a : DEFAULT_AVATAR_ASCII_ART_COLUMNS;
+    const rows = (_b = options.rows) !== null && _b !== void 0 ? _b : Math.round(columns / 2);
+    const canvas = options.createCanvas(DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+    if (!canvas.style) {
+        // Note: `renderAvatarVisual` expects a browser canvas shape; Node.js canvases only need this tiny compatibility shim.
+        canvas.style = {};
+    }
+    renderAvatarVisual({
+        canvas,
+        avatarDefinition: options.avatarDefinition,
+        visualId: options.visualId,
+        size: DEFAULT_AVATAR_SIZE,
+        timeMs: (_c = options.timeMs) !== null && _c !== void 0 ? _c : STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
+        devicePixelRatio: 1,
+    });
+    const context = canvas.getContext('2d');
+    if (!context) {
+        throw new EnvironmentMismatchError(spaceTrim$1(`
+                2D canvas rendering context is unavailable while converting the avatar visual to ASCII art.
+
+                Provide a \`createCanvas\` factory whose canvases support \`getContext('2d')\`,
+                for example \`createCanvas\` of \`@napi-rs/canvas\` in Node.js.
+            `));
+    }
+    const imageData = context.getImageData(0, 0, DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+    return convertImageDataToAsciiArt({
+        imageData,
+        columns,
+        rows,
+        colorDepth: options.colorDepth,
+    });
+}
+
+/**
+ * Default built-in avatar visual used when an agent does not define `META IMAGE`.
+ *
+ * @private shared avatar contract
+ */
+const DEFAULT_AGENT_AVATAR_VISUAL_ID = 'octopus3d4';
+/**
+ * Resolves the avatar visual preferred by an agent, then falls back to a federated server default
+ * and finally to the caller/server default.
+ *
+ * @param agent Agent metadata and optional remote-profile visual id.
+ * @param defaultAvatarVisualId Optional metadata-resolved server default.
+ * @returns Supported avatar visual id.
+ *
+ * @private shared avatar contract
+ */
+function resolveAgentAvatarVisualId(agent, defaultAvatarVisualId = DEFAULT_AGENT_AVATAR_VISUAL_ID) {
+    var _a;
+    return (resolveAvatarVisualId((_a = agent.meta) === null || _a === void 0 ? void 0 : _a.avatar) ||
+        agent.avatarVisualId ||
+        agent.defaultAgentAvatarVisualId ||
+        defaultAvatarVisualId);
+}
+
+/**
+ * Detects the ANSI color depth supported by the current terminal.
+ *
+ * Prefers 24-bit true color when the environment advertises it (modern terminals such as
+ * Windows Terminal, ConEmu, VS Code, mintty, iTerm2, and WezTerm) and falls back to the
+ * portable 256-color palette otherwise.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the process environment
+ *
+ * @returns Color depth usable by `convertImageDataToAsciiArt`
+ *
+ * @private within the repository
+ */
+function $detectTerminalAnsiColorDepth() {
+    if (typeof process === 'undefined' || !process.env) {
+        return 'ANSI_256';
+    }
+    const colorTerm = (process.env.COLORTERM || '').toLowerCase();
+    if (colorTerm.includes('truecolor') || colorTerm.includes('24bit')) {
+        return 'TRUE_COLOR';
+    }
+    if (process.env.WT_SESSION !== undefined) {
+        return 'TRUE_COLOR'; // <- Note: Windows Terminal always supports true color but does not set COLORTERM
+    }
+    if (process.env.ConEmuANSI === 'ON') {
+        return 'TRUE_COLOR';
+    }
+    const termProgram = process.env.TERM_PROGRAM || '';
+    if (['vscode', 'iTerm.app', 'WezTerm', 'ghostty', 'Hyper'].includes(termProgram)) {
+        return 'TRUE_COLOR';
+    }
+    const term = (process.env.TERM || '').toLowerCase();
+    if (term.includes('truecolor') || term.includes('24bit') || term.includes('direct')) {
+        return 'TRUE_COLOR';
+    }
+    return 'ANSI_256';
+}
+
+/**
+ * Output width of the coder-run agent visual in terminal character cells.
+ *
+ * @private internal constant of coder run UI
+ */
+const CODER_RUN_AGENT_VISUAL_COLUMNS = 24;
+/**
+ * Output height of the coder-run agent visual in terminal character cells.
+ *
+ * Half of the columns keeps the square avatar visually square in a common terminal font.
+ *
+ * @private internal constant of coder run UI
+ */
+const CODER_RUN_AGENT_VISUAL_ROWS = 12;
+/**
+ * Builds the ANSI ASCII-art visual of the `--agent` book shown above the coder-run dashboard.
+ *
+ * The agent's avatar visual is resolved the same way as on the website - the `META AVATAR`
+ * commitment wins, then the `META VISUAL` commitment, then the shared default visual - and is
+ * rendered dynamically through the shared canvas avatar pipeline into terminal ASCII art.
+ *
+ * The visual is decorative, so any failure (for example when the optional `@napi-rs/canvas`
+ * module is not installed) returns `null` and the caller keeps the default brand banner.
+ *
+ * @param agentSource Source of the `--agent` book file.
+ * @returns ANSI-colored ASCII-art lines or `null` when the visual cannot be rendered.
+ */
+async function buildCoderRunAgentVisual(agentSource) {
+    try {
+        // Note: `@napi-rs/canvas` is an optional native module, so it is imported dynamically and lazily
+        const { createCanvas } = await import('@napi-rs/canvas');
+        const agentBasicInformation = parseAgentSource(agentSource);
+        const avatarDefinition = createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation);
+        const avatarVisualId = resolveAgentAvatarVisualId(agentBasicInformation, resolveAvatarVisualId(agentBasicInformation.meta.visual) || DEFAULT_AGENT_AVATAR_VISUAL_ID);
+        return renderAvatarVisualAsciiArt({
+            avatarDefinition,
+            visualId: avatarVisualId,
+            columns: CODER_RUN_AGENT_VISUAL_COLUMNS,
+            rows: CODER_RUN_AGENT_VISUAL_ROWS,
+            colorDepth: $detectTerminalAnsiColorDepth(),
+            createCanvas: (width, height) => createCanvas(width, height),
+        });
+    }
+    catch (error) {
+        return null;
+    }
+}
+
 /**
  * Formats commit message lines for console display.
  */
@@ -73351,13 +74111,15 @@ async function runCodexPrompts(providedOptions) {
     startPauseListenerIfNeeded(isRichUiEnabled);
     try {
         const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
-        const resolvedAgentSystemMessage = await resolveAgentSystemMessage(options.agent, process.cwd());
+        const resolvedCoderAgent = await resolveCoderAgent(options.agent, process.cwd());
+        const resolvedAgentSystemMessage = resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.systemMessage;
         if (await runDryRunIfRequested(options)) {
             return;
         }
         const { runner, actualRunnerModel, runnerMetadata } = resolvePromptRunner(options);
         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 seedCachedAveragePromptDuration({
             options,
             actualRunnerModel,
@@ -73595,6 +74357,20 @@ function initializeRunUi(uiHandle, runnerName, actualRunnerModel, options) {
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Running prompts with ${runnerName}`);
 }
+/**
+ * Renders the `--agent` book avatar as ASCII art and shows it instead of the default brand banner.
+ *
+ * Keeps the default banner when no agent is selected, the UI is disabled, or the visual cannot be rendered.
+ */
+async function initializeRunUiAgentVisual(uiHandle, agentSource) {
+    if (!uiHandle || !agentSource) {
+        return;
+    }
+    const agentVisualLines = await buildCoderRunAgentVisual(agentSource);
+    if (agentVisualLines) {
+        uiHandle.state.setAgentVisualLines(agentVisualLines);
+    }
+}
 /**
  * Loads prompt files, updates progress displays, and selects the next runnable prompt.
  */