@promptbook/javascript 0.114.0-4 → 0.114.0-6

package/README.md

@@ -451,7 +451,7 @@ Or you can install them separately:
 
 Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
 
--   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
 -   optional shared repo context loaded from a file such as `AGENTS.md`
 -   automatic `git add`, commit, and push after each successful prompt
@@ -466,11 +466,11 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
-4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind.
 
 #### Features
 

package/esm/index.es.js

@@ -17,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-4';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-6';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/avatars/renderAvatarVisualTerminalText.d.ts

@@ -0,0 +1,80 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId, AvatarVisualTerminalTextGrid } from './types/AvatarVisualDefinition';
+/**
+ * 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 declare function renderAvatarVisualTerminalTextGrid(options: RenderAvatarVisualTerminalTextOptions): AvatarVisualTerminalTextGrid | null;
+/**
+ * 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 declare function renderAvatarVisualTerminalTextLines(options: RenderAvatarVisualTerminalTextLinesOptions): ReadonlyArray<string> | null;

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 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.
  *
@@ -84,6 +130,14 @@ 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;
 };
 /**
  * Props of the shared `<Avatar/>` component.

package/esm/src/book-3.0/AgentTeamConversationWorkspace.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Relative directory for an active TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH: string;
+/**
+ * Relative directory where completed TEAM conversation transcripts are retained.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH: string;
+/**
+ * Name of the JSON manifest that describes one TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME = "team.json";
+/**
+ * Name of the read-only teammate-source directory inside one TEAM workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME = "teammates";
+/**
+ * One primary agent represented in a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationPrimaryAgent = {
+    readonly permanentId: string;
+    readonly agentName: string;
+};
+/**
+ * One local teammate made available to the coding harness for a single user turn.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationTeammate = {
+    readonly permanentId: string;
+    readonly agentName: string;
+    readonly url: string;
+    readonly instructions: string;
+    readonly sourceFileName: string;
+};
+/**
+ * Persisted roster snapshot for the optional TEAM workspace of one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationWorkspaceManifest = {
+    readonly version: 1;
+    readonly primaryAgent: AgentTeamConversationPrimaryAgent;
+    readonly teammates: ReadonlyArray<AgentTeamConversationTeammate>;
+};
+/**
+ * Creates the stable directory name that belongs to one queued `.book` message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamConversationWorkspaceDirectoryName(messageFileName: string): string;
+/**
+ * Creates the relative active workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamConversationWorkspacePath(messageFileName: string): string;
+/**
+ * Creates the relative completed-workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createFinishedAgentTeamConversationWorkspacePath(messageFileName: string): string;
+/**
+ * Creates the source-snapshot file name for one teammate.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamTeammateSourceFileName(teammatePermanentId: string): string;
+/**
+ * Checks whether unknown JSON has the minimum shape required for a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function isAgentTeamConversationWorkspaceManifest(value: unknown): value is AgentTeamConversationWorkspaceManifest;

package/esm/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -591,8 +591,9 @@ export type ChatProps = {
         progress?: number;
     }>;
     /**
-     * Content to be shown inside the chat bar in head
-     * If not provided, the chat bar will not be rendered
+     * Optional content displayed in the chat header above the message list.
+     *
+     * If not provided, the header row is not rendered.
      */
     readonly children?: ReactNode;
     /**

package/esm/src/book-components/Chat/utils/renderMarkdown.d.ts

@@ -26,10 +26,12 @@ export type MarkdownInlineReference = {
      */
     readonly href: string;
     /**
-     * Markdown link destination prefixes that should render as this reference as well.
+     * Optional URL prefixes which also identify this reference in the authored markdown.
      *
-     * This supports legacy links such as an Agents Server project file URL while keeping
-     * `reference` as the canonical `[[project]]` token.
+     * A markdown link or a bare URL pointing to one of these prefixes is rendered as the same chip
+     * as the `[[reference]]` token. Both absolute URLs (for example `https://project.example.com`)
+     * and application paths (for example `/agents/agent/projects/website`) are supported; a path
+     * prefix matches on any host so that both relative and absolute links are recognized.
      */
     readonly sourceHrefPrefixes?: ReadonlyArray<string>;
     /**

package/esm/src/cli/cli-commands/coder/boilerplateCount.d.ts

@@ -12,7 +12,7 @@ export type BoilerplateCount = {
      * Number of prompts written into each generated file.
      *
      * Note: More than one prompt per file is an advanced option - each prompt is one separate
-     *       coding task separated by `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };

package/esm/src/cli/cli-commands/coder/generate-boilerplates.d.ts

@@ -10,7 +10,7 @@ import type { BoilerplateCount } from './boilerplateCount';
  */
 export declare function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect;
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */

package/esm/src/cli/cli-commands/coder/verify.d.ts

@@ -1,4 +1,4 @@
-import type { Command as Program } from 'commander';
+import { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
  * Initializes `coder verify` command for Promptbook CLI utilities

package/esm/src/cli/cli-commands/common/{harness/$askForHarnessInstallationApproval.d.ts → npm/$askForNpmPackageInstallationApproval.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
  * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForHarnessInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;

package/esm/src/cli/cli-commands/common/{harness/$resolveLatestHarnessVersion.d.ts → npm/$resolveLatestNpmPackageVersion.d.ts}

@@ -1,10 +1,9 @@
-import type { HarnessDefinition } from './HarnessDefinition';
 /**
- * Reads the newest version of the harness published to npm.
+ * Reads the newest version of one npm package.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
  *
  * @returns The newest published version or `null` when the registry could not be reached
  * @private internal utility of `promptbookCli`
  */
-export declare function $resolveLatestHarnessVersion(definition: HarnessDefinition): Promise<string | null>;
+export declare function $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null>;

package/esm/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extracts an npm package version from raw command output.
+ *
+ * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+ * npm registry commands can opt into the last matching token because npm warnings commonly precede their JSON output.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export declare function extractNpmPackageVersionFromOutput(output: string, { isLastMatchPreferred }?: {
+    readonly isLastMatchPreferred?: boolean;
+}): string | null;

package/esm/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compares an installed npm package version with the newest published version.
+ *
+ * Only the numeric `major.minor.patch` segments are compared and pre-release suffixes are ignored,
+ * so a package installed from a pre-release build of the newest version is not reported as outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function isNpmPackageVersionOutdated(installedVersion: string, latestVersion: string): boolean;

package/esm/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.d.ts

@@ -0,0 +1,9 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update is approved, the caller must stop the current run and let the user start a fresh process. A local
+ * npm update can modify `package.json` and a lockfile, which would make the coder's working-tree preflight fail;
+ * more importantly, this Node.js process has already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when an update was approved and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $ensurePromptbookCliInstallations(): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.test.d.ts

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

package/esm/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.d.ts

@@ -0,0 +1,12 @@
+import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Finds every locally or globally installed Promptbook CLI package which can be updated.
+ *
+ * A local package must be declared directly in the current project's `package.json`; transitive packages are not
+ * updated because this command must not change dependencies chosen by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.test.d.ts

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

package/esm/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.d.ts

@@ -0,0 +1,10 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Npm packages which provide an executable Promptbook CLI.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES: readonly ["ptbk", "@promptbook/cli"];
+/**
+ * Npm package which provides an executable Promptbook CLI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+/**
+ * One installed Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+    /**
+     * Version from the package's installed `package.json`.
+     */
+    readonly installedVersion: string;
+    /**
+     * Local manifest section or global npm installation containing the package.
+     */
+    readonly installationLocation: PromptbookCliInstallationLocation;
+};

package/esm/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.d.ts

@@ -0,0 +1,26 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Result of comparing one installed Promptbook CLI package with the newest published version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationState = 'up-to-date' | 'outdated' | 'unknown';
+/**
+ * Version status of one Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationStatus = {
+    /**
+     * Installed CLI package being checked.
+     */
+    readonly installation: PromptbookCliInstallation;
+    /**
+     * Result of comparing the installed version with the newest published version.
+     */
+    readonly installationState: PromptbookCliInstallationState;
+    /**
+     * Newest published package version, or `null` when npm could not be reached.
+     */
+    readonly latestVersion: string | null;
+};

package/esm/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.d.ts

@@ -0,0 +1,7 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Builds the npm command that updates one existing Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function buildPromptbookCliInstallCommand(installation: PromptbookCliInstallation): string;

package/esm/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.test.d.ts

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

package/esm/src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.d.ts

@@ -0,0 +1,7 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatPromptbookCliInstallationWarning(statuses: ReadonlyArray<PromptbookCliInstallationStatus>): string;

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

@@ -5,9 +5,9 @@
  * 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.

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

@@ -75,9 +75,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;
 };
 /**
  * Resolves the built-in avatar visual selected for terminal rendering of one agent source.

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

@@ -62,6 +62,12 @@ export type ConvertImageDataToAsciiArtOptions = {
      */
     readonly alphaThreshold?: number;
 };
+/**
+ * Default alpha channel value below which a cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_ALPHA_THRESHOLD = 32;
 /**
  * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
  *

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/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/utils/misc/debounce.test.d.ts

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

package/esm/src/version.d.ts

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