@promptbook/cli 0.114.0-5 → 0.114.0-50

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-5",
+    "version": "0.114.0-50",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -92,12 +92,9 @@
         "node": ">=18.18.0",
         "npm": ">=8.0.0"
     },
-    "overrides": {
-        "zod": "$zod"
-    },
     "dependencies": {
-        "@ai-sdk/deepseek": "0.1.17",
-        "@ai-sdk/google": "1.0.17",
+        "@ai-sdk/deepseek": "1.0.56",
+        "@ai-sdk/google": "2.0.97",
         "@anthropic-ai/sdk": "0.68.0",
         "@azure/openai": "1.0.0-beta.13",
         "@mozilla/readability": "0.6.0",
@@ -106,12 +103,11 @@
         "bottleneck": "2.19.5",
         "colors": "1.4.0",
         "commander": "12.0.0",
-        "crypto": "1.0.1",
         "crypto-js": "4.2.0",
         "dotenv": "16.3.2",
-        "express": "4.21.2",
-        "express-openapi-validator": "5.4.9",
-        "glob-promise": "6.0.7",
+        "express": "4.22.3",
+        "express-openapi-validator": "5.6.2",
+        "glob": "13.0.6",
         "ignore": "^5.3.2",
         "jsdom": "25.0.1",
         "jszip": "3.10.1",
@@ -126,29 +122,29 @@
         "rxjs": "7.8.2",
         "showdown": "2.1.0",
         "socket.io": "4.8.3",
-        "socket.io-client": "4.7.5",
+        "socket.io-client": "4.8.3",
         "spacetrim": "0.11.60",
+        "string-width": "4.2.3",
         "swagger-ui-express": "5.0.1",
-        "type-fest": "4.5.0",
         "userhome": "1.0.1",
         "waitasecond": "1.11.164",
         "zod": "4.3.6",
         "typescript": "5.2.2",
         "ts-node": "10.9.2",
-        "next": "15.4.11",
+        "next": "15.5.25",
         "lucide-react": "0.536.0",
         "raw-loader": "^4.0.2",
         "tailwindcss": "3.4.19",
         "@tailwindcss/typography": "0.5.19",
-        "postcss": "8.5.12",
+        "postcss": "8.5.28",
         "autoprefixer": "10.4.27",
-        "@ai-sdk/openai": "1.0.20",
-        "@aws-sdk/client-s3": "3.936.0",
+        "@ai-sdk/openai": "2.0.127",
+        "@aws-sdk/client-s3": "3.1134.0",
         "@dnd-kit/core": "6.3.1",
         "@dnd-kit/sortable": "10.0.0",
         "@dnd-kit/utilities": "3.2.2",
         "@elevenlabs/react": "0.12.3",
-        "@modelcontextprotocol/sdk": "1.24.3",
+        "@modelcontextprotocol/sdk": "1.26.0",
         "@monaco-editor/react": "4.7.0",
         "@node-saml/node-saml": "^5.1.0",
         "@prisma/studio-core": "0.27.3",
@@ -156,37 +152,36 @@
         "@sentry/nextjs": "^10.57.0",
         "@types/formidable": "3.4.7",
         "@types/mailparser": "3.4.6",
-        "@types/swagger-ui-react": "5.18.0",
         "@types/turndown": "5.0.6",
         "@vercel/blob": "1.1.1",
         "@xmldom/xmldom": "^0.9.10",
         "@xterm/addon-fit": "0.11.0",
         "@xterm/xterm": "6.0.0",
-        "better-sqlite3": "^11.10.0",
+        "better-sqlite3": "^12.11.1",
         "configchecker": "1.5.132",
         "cross-fetch": "4.0.0",
         "destroyable": "0.12.145",
-        "dompurify": "3.4.6",
+        "dompurify": "3.4.15",
         "formidable": "3.5.4",
         "highlight.js": "11.11.1",
         "html-to-image": "1.11.13",
-        "jspdf": "4.1.0",
+        "jspdf": "4.2.1",
         "katex": "0.16.45",
         "leaflet": "1.9.4",
         "localtunnel": "^2.0.2",
         "lorem-ipsum": "2.0.8",
-        "mailparser": "3.9.8",
+        "mailparser": "3.9.20",
         "monaco-editor": "0.54.0",
         "node-gzip": "1.1.2",
-        "nodemailer": "^7.0.13",
+        "nodemailer": "^9.1.1",
         "qrcode": "1.5.4",
-        "swagger-ui-react": "5.31.2",
+        "swagger-ui-dist": "5.32.15",
         "turndown": "7.2.4",
+        "type-fest": "4.5.0",
         "web-push": "^3.6.7",
         "y-monaco": "0.1.6",
         "y-protocols": "1.0.7",
         "y-websocket": "3.0.0",
-        "y-websocket-server": "1.0.2",
         "yjs": "13.6.30",
         "zeptomail": "7.0.2"
     },

package/src/_packages/cli.readme.md

@@ -1,5 +1,20 @@
 CLI utilities for Promptbook that provide command-line tools for building, prettifying, and managing promptbook collections. After installation, you can use the `ptbk` command in your terminal.
 
+## Project commands
+
+`ptbk coder run --harness openai-codex` uses the invocation's current directory, its `agents/developer.book`, and
+the UTF-8 contents of its `AGENTS.md`. The explicit equivalent is
+`ptbk coder run --harness openai-codex --path . --agent ./agents/developer.book --context ./AGENTS.md`.
+`--path` selects an existing project directory; relative Book/context files resolve inside it, even in a nested
+Git project. Explicit context replaces the default; `--context ""` disables additional context. Missing implicit
+AGENTS.md warns and continues, while unreadable files or invalid explicit Book/context references fail clearly.
+
+`ptbk init` and `ptbk coder init` share initialization and preserve custom Books, context, scripts and settings.
+`coder plan` also defaults to Developer, retaining PRD-only permissions; `--agent ./agents/planner.book` selects
+Planner explicitly. `coder list` has no default Book filter. See the
+[command inventory and precedence reference](https://github.com/webgptorg/promptbook/blob/main/scripts/run-codex-prompts/README.md#shared-project-selection-and-command-inventory)
+for execution, authoring, listing, folder-runner, and legacy-command distinctions.
+
 ## 🎯 Purpose and Motivation
 
 The CLI package provides essential command-line tools for Promptbook development workflows. It enables developers to build optimized promptbook libraries, prettify promptbook files, and manage collections efficiently from the command line, making it easier to integrate Promptbook into development and deployment pipelines.

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/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;
 };
 
 /**