@promptbook/cli 0.114.0-2 → 0.114.0-21

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

@@ -0,0 +1,46 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export declare const ANSI_RESET = "\u001B[0m";
+/**
+ * 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 declare function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;
+/**
+ * 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 declare function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;

package/esm/src/utils/misc/createLazyModuleLoader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Creates a loader which imports one module on the first call and reuses the very same module afterwards
+ *
+ * Note: [🐌] Heavy third-party dependencies are imported lazily to keep the startup of the Promptbook CLI fast.
+ *       A statically imported dependency is loaded every single time the bundle is loaded, even when the running
+ *       command never touches it. A lazily imported dependency is loaded only when the feature is really used.
+ *
+ * @example
+ * const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+ * const { JSDOM } = await loadJsdomModule();
+ *
+ * @private internal utility of Promptbook
+ */
+export declare function createLazyModuleLoader<TModule>(importModule: () => Promise<TModule>): () => Promise<TModule>;

package/esm/src/utils/misc/debounce.d.ts

@@ -1,7 +1,9 @@
 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 declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

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.1-0`).
+ * It follows semantic versioning (e.g., `0.114.0-20`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-2",
+    "version": "0.114.0-21",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/_packages/components.index.ts

@@ -75,8 +75,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
@@ -170,8 +172,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

package/src/_packages/components.readme.md

@@ -80,7 +80,7 @@ interface BookEditorProps {
     onChange?: (value: string) => void;
 
     // Explicit list of commitment keywords to highlight (case-insensitive).
-    // If omitted, a default set (PERSONA, KNOWLEDGE, MEMORY, STYLE, RULE, RULES, WRITING SAMPLE, WRITING RULES, SAMPLE, EXAMPLE, FORMAT, MODEL, ACTION, META IMAGE, META LINK, NOTE, GOAL, MESSAGE, SCENARIO, DELETE, CANCEL, DISCARD, REMOVE, EXPECT, SCENARIOS, BEHAVIOUR, BEHAVIOURS, AVOID, AVOIDANCE, GOALS, CONTEXT) is used.
+    // If omitted, a default set (PERSONA, KNOWLEDGE, STYLE, RULE, RULES, WRITING SAMPLE, WRITING RULES, SAMPLE, EXAMPLE, FORMAT, MODEL, ACTION, META IMAGE, META LINK, NOTE, GOAL, MESSAGE, SCENARIO, DELETE, CANCEL, DISCARD, REMOVE, EXPECT, SCENARIOS, BEHAVIOUR, BEHAVIOURS, AVOID, AVOIDANCE, GOALS, CONTEXT) is used.
     commitmentTypes?: string[];
 }
 ```

package/src/_packages/types.index.ts

@@ -65,8 +65,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
@@ -516,8 +518,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

package/src/avatars/renderAvatarVisualTerminalText.ts

@@ -0,0 +1,249 @@
+import type { string_color } from '../types/string_person_fullname';
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import { DEFAULT_ALPHA_THRESHOLD } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AnsiRgbColor } from '../utils/ascii-art/createAnsiColorCode';
+import { ANSI_RESET, createAnsiForegroundColorCode } from '../utils/ascii-art/createAnsiColorCode';
+import { Color } from '../utils/color/Color';
+import { createIdleAvatarInteractionState } from './avatarInteractionUtils';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import { resolveAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type {
+    AvatarSurfaceStyle,
+    AvatarVisualId,
+    AvatarVisualTerminalTextCell,
+    AvatarVisualTerminalTextGrid,
+} from './types/AvatarVisualDefinition';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * Height of one terminal character cell relative to its width.
+ *
+ * Terminal fonts are roughly twice as tall as they are wide, so a square avatar needs
+ * twice as many columns as rows to keep its proportions.
+ *
+ * @private within the repository
+ */
+const TERMINAL_CHARACTER_CELL_ASPECT_RATIO = 2;
+
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextGrid(
+    options: RenderAvatarVisualTerminalTextOptions,
+): AvatarVisualTerminalTextGrid | null {
+    const resolvedRenderDefinition =
+        options.resolvedAvatarRenderDefinition ||
+        resolveAvatarRenderDefinition({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+        });
+    const { renderTerminalText } = resolvedRenderDefinition.avatarVisual;
+
+    if (renderTerminalText === undefined) {
+        return null;
+    }
+
+    const avatarColumnCount = Math.min(options.columns, options.rows * TERMINAL_CHARACTER_CELL_ASPECT_RATIO);
+    const avatarRowCount = Math.min(options.rows, Math.round(options.columns / TERMINAL_CHARACTER_CELL_ASPECT_RATIO));
+
+    if (avatarColumnCount <= 0 || avatarRowCount <= 0) {
+        return null;
+    }
+
+    const avatarGrid = renderTerminalText({
+        columns: avatarColumnCount,
+        rows: avatarRowCount,
+        timeMs: options.timeMs,
+        avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+        palette: resolvedRenderDefinition.palette,
+        createRandom: resolvedRenderDefinition.createRandom,
+        interaction: createIdleAvatarInteractionState(),
+    });
+
+    return centerAvatarVisualTerminalTextGrid(avatarGrid, options.columns, options.rows);
+}
+
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextLines(
+    options: RenderAvatarVisualTerminalTextLinesOptions,
+): ReadonlyArray<string> | null {
+    const terminalTextGrid = renderAvatarVisualTerminalTextGrid(options);
+
+    if (terminalTextGrid === null) {
+        return null;
+    }
+
+    return terminalTextGrid.map((terminalTextRow) =>
+        buildAvatarVisualTerminalTextLine(terminalTextRow, options.colorDepth || 'TRUE_COLOR'),
+    );
+}
+
+/**
+ * Converts one avatar cell color into the opaque terminal color it is painted with.
+ *
+ * Terminal cells cannot be blended, so the cell alpha is composited onto the dark terminal
+ * background and fully transparent cells keep the terminal background instead.
+ *
+ * @param color Cell color as a CSS color string, optionally with an alpha channel.
+ * @returns Opaque terminal color or `null` when the cell should stay empty.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function resolveAvatarVisualTerminalTextColor(color: string_color): AnsiRgbColor | null {
+    const parsedColor = Color.fromSafe(color);
+
+    if (parsedColor.alpha < DEFAULT_ALPHA_THRESHOLD) {
+        return null;
+    }
+
+    const opacity = parsedColor.alpha / 255;
+
+    return {
+        red: Math.round(parsedColor.red * opacity),
+        green: Math.round(parsedColor.green * opacity),
+        blue: Math.round(parsedColor.blue * opacity),
+    };
+}
+
+/**
+ * Places the square avatar grid into the center of the requested terminal grid.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextGrid`
+ */
+function centerAvatarVisualTerminalTextGrid(
+    avatarGrid: AvatarVisualTerminalTextGrid,
+    columns: number,
+    rows: number,
+): AvatarVisualTerminalTextGrid {
+    const avatarRowCount = avatarGrid.length;
+    const avatarColumnCount = avatarGrid[0]?.length || 0;
+    const leftCellCount = Math.floor((columns - avatarColumnCount) / 2);
+    const topRowCount = Math.floor((rows - avatarRowCount) / 2);
+
+    return Array.from({ length: rows }, (_, rowIndex) => {
+        const avatarRow = avatarGrid[rowIndex - topRowCount];
+
+        return Array.from({ length: columns }, (__, columnIndex) => avatarRow?.[columnIndex - leftCellCount] || null);
+    });
+}
+
+/**
+ * Builds one ANSI-colored terminal line from resolved character cells.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function buildAvatarVisualTerminalTextLine(
+    terminalTextRow: ReadonlyArray<AvatarVisualTerminalTextCell | null>,
+    colorDepth: AsciiArtColorDepth,
+): string {
+    let line = '';
+    let currentForegroundCode: string | undefined = undefined;
+
+    for (const terminalTextCell of terminalTextRow) {
+        const cellColor =
+            terminalTextCell === null ? null : resolveAvatarVisualTerminalTextColor(terminalTextCell.color);
+        const nextForegroundCode =
+            cellColor === null ? undefined : createAnsiForegroundColorCode(cellColor, colorDepth);
+
+        if (nextForegroundCode !== currentForegroundCode) {
+            // Note: A reset is required whenever a previously set color must be cleared,
+            //       otherwise a stale color would bleed into the following empty cells.
+            if (nextForegroundCode === undefined) {
+                line += ANSI_RESET;
+            } else {
+                line += nextForegroundCode;
+            }
+
+            currentForegroundCode = nextForegroundCode;
+        }
+
+        line += cellColor === null || terminalTextCell === null ? ' ' : terminalTextCell.character;
+    }
+
+    if (currentForegroundCode !== undefined) {
+        line += ANSI_RESET;
+    }
+
+    return line;
+}

package/src/avatars/types/AvatarVisualDefinition.ts

@@ -93,6 +93,57 @@ export type AvatarVisualRenderContext = {
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
 
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
+
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -105,6 +156,15 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 
 /**