@promptbook/cli 0.112.0-46 → 0.112.0-47

package/esm/scripts/run-codex-prompts/common/waitForPause.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Pause lifecycle of `ptbk coder run`.
+ */
+export type CoderRunPauseState = 'RUNNING' | 'PAUSING' | 'PAUSED';
+/**
+ * Result of toggling the pause hotkey state.
+ */
+export type CoderRunPauseToggleResult = 'REQUESTED_PAUSE' | 'CANCELLED_PAUSE' | 'RESUMED';
+/**
+ * Applies the same three-state toggle used by the `P` hotkey.
+ */
+export declare function togglePauseState(): CoderRunPauseToggleResult;
 /**
  * Listens for the "p" key to pause and resume.
  */
@@ -17,7 +29,7 @@ export declare function checkPause(options?: {
 /**
  * Returns the current pause state for external consumers such as the terminal UI.
  */
-export declare function getPauseState(): 'RUNNING' | 'PAUSING' | 'PAUSED';
+export declare function getPauseState(): CoderRunPauseState;
 /**
  * Requests a pause from an external controller (e.g. the Ink UI).
  */

package/esm/scripts/run-codex-prompts/ui/buildCoderRunOctopusVisual.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for the horizontal octopus brand illustration.
+ */
+export type BuildCoderRunOctopusVisualOptions = {
+    readonly totalWidth: number;
+    readonly animationFrame: number;
+};
+/**
+ * Builds the horizontal octopus illustration shown above the coder-run dashboard.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function buildCoderRunOctopusVisual(options: BuildCoderRunOctopusVisualOptions): readonly string[];

package/esm/scripts/run-codex-prompts/ui/buildCoderRunUiFrame.d.ts

@@ -1,13 +1,15 @@
+import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunConfig, CoderRunPhase, CoderRunProgressSnapshot } from './CoderRunUiState';
 /**
  * Shared pause-state shape between the renderer and the frame builder.
  */
-export type CoderRunPauseState = 'RUNNING' | 'PAUSING' | 'PAUSED';
+export type { CoderRunPauseState };
 /**
  * Snapshot consumed by the pure coder-run frame builder.
  */
 export type BuildCoderRunUiFrameOptions = {
     readonly terminalWidth: number;
+    readonly animationFrame: number;
     readonly spinner: string;
     readonly pauseState: CoderRunPauseState;
     readonly config: CoderRunConfig;

package/esm/scripts/run-codex-prompts/ui/coderRunUiRefresh.d.ts

@@ -1,11 +1,17 @@
-import type { CoderRunPauseState } from './buildCoderRunUiFrame';
+import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunPhase } from './CoderRunUiState';
 /**
  * Refresh cadence used only while the rich coder UI needs animated updates.
  *
  * @private internal constant of coder run UI
  */
-export declare const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 1000;
+export declare const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 300;
+/**
+ * Returns whether the rich coder UI should keep animating on its own.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function isCoderRunUiAutoRefreshing(phase: CoderRunPhase, pauseState: CoderRunPauseState): boolean;
 /**
  * Returns the automatic refresh interval for the current UI state.
  *

package/esm/scripts/run-codex-prompts/ui/coderRunUiText.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Centers an ANSI-colored line within the available frame width.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function centerAnsiText(text: string, width: number): string;
+/**
+ * Pads or truncates a possibly ANSI-colored line to the target visible width.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function padAnsiText(text: string, width: number): string;
+/**
+ * Truncates a possibly ANSI-colored line to the target visible width.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function fitAnsiText(text: string, width: number): string;
+/**
+ * Truncates a plain-text line to the target width with an ellipsis.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function fitPlainText(text: string, width: number): string;
+/**
+ * Measures visible string width by stripping ANSI escape codes.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function visibleLength(text: string): number;
+/**
+ * Strips ANSI escape codes from a string.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function stripAnsi(text: string): string;

package/esm/scripts/utils/emojiTags/scanEmojiTagUsage.d.ts

@@ -0,0 +1,51 @@
+import type { string_char_emoji } from '../../../src/types/typeAliasEmoji';
+/**
+ * Options controlling one repository emoji-tag scan.
+ */
+export type EmojiTagScanOptions = {
+    /**
+     * Candidate emojis that may appear inside bracketed tags.
+     */
+    readonly candidateEmojis: ReadonlySet<string_char_emoji>;
+    /**
+     * Root directory to scan (defaults to `process.cwd()`).
+     */
+    readonly rootDir?: string;
+    /**
+     * Glob patterns to include when scanning for tags.
+     */
+    readonly includeGlobs?: ReadonlyArray<string>;
+    /**
+     * Glob patterns to ignore when scanning for tags.
+     */
+    readonly ignoreGlobs?: ReadonlyArray<string>;
+    /**
+     * Exact prefix expected before the emoji inside the brackets.
+     */
+    readonly tagPrefix?: string;
+    /**
+     * Optional error handler for best-effort scans that should skip unreadable files.
+     */
+    readonly onFileError?: (error: Error, filePath: string) => void;
+};
+/**
+ * Result of one repository emoji-tag scan.
+ */
+export type EmojiTagScanResult = {
+    /**
+     * Emojis already used inside matching bracketed tags.
+     */
+    readonly usedEmojis: ReadonlySet<string_char_emoji>;
+    /**
+     * Number of files whose content had to be read during this run.
+     */
+    readonly scannedFileCount: number;
+    /**
+     * Number of files satisfied purely from the persisted cache.
+     */
+    readonly reusedFileCount: number;
+};
+/**
+ * Scans repository files for bracketed emoji tags while reusing per-file cache entries for unchanged files.
+ */
+export declare function scanEmojiTagUsage(options: EmojiTagScanOptions): Promise<EmojiTagScanResult>;

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

@@ -0,0 +1,45 @@
+import type { CSSProperties } from 'react';
+import type { string_css_class, string_url_image } from '../types/typeAliases';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Shared avatar-rendering props for places that may receive either an image URL or a deterministic avatar visual.
+ *
+ * @private shared component for avatar media rendering
+ */
+export type AvatarOrImageProps = {
+    /**
+     * Explicit image URL to render.
+     */
+    readonly imageUrl?: string_url_image | null;
+    /**
+     * Deterministic avatar definition used by built-in visuals.
+     */
+    readonly avatarDefinition?: AvatarDefinition | null;
+    /**
+     * Selected built-in visual id used with `avatarDefinition`.
+     */
+    readonly visualId?: AvatarVisualId | null;
+    /**
+     * Output size in CSS pixels.
+     */
+    readonly size: number;
+    /**
+     * Accessible label used for the rendered media.
+     */
+    readonly alt: string;
+    /**
+     * Optional CSS class name applied to the rendered element.
+     */
+    readonly className?: string_css_class;
+    /**
+     * Optional inline styles forwarded to the rendered element.
+     */
+    readonly style?: CSSProperties;
+};
+/**
+ * Renders either a static image or a deterministic canvas avatar using one common prop shape.
+ *
+ * @private shared component for avatar media rendering
+ */
+export declare function AvatarOrImage(props: AvatarOrImageProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,4 +1,5 @@
 export { Avatar } from './Avatar';
+export { AvatarOrImage } from './AvatarOrImage';
 export { renderAvatarVisual } from './renderAvatarVisual';
 export { createAvatarDefinitionFromAgentBasicInformation } from './avatarRenderingUtils';
 export { AVATAR_VISUALS, getAvatarVisualById } from './visuals/avatarVisualRegistry';

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

@@ -1,3 +1,4 @@
+import type { CSSProperties } from 'react';
 import type { string_color, string_css_class } from '../../types/typeAliases';
 import type { AvatarDefinition } from './AvatarDefinition';
 /**
@@ -5,7 +6,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'minecraft' | 'fractal';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'ascii-octopus' | 'minecraft' | 'fractal';
 /**
  * Derived color palette used by avatar visuals.
  *
@@ -80,6 +81,10 @@ export type AvatarProps = {
      * Optional CSS class name applied to the canvas.
      */
     readonly className?: string_css_class;
+    /**
+     * Optional inline style applied to the canvas.
+     */
+    readonly style?: CSSProperties;
 };
 /**
  * Low-level rendering options for a single canvas frame.

package/esm/src/avatars/visuals/asciiOctopusAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * AsciiOctopus avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const asciiOctopusAvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/octopus3AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus3 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3AvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/octopusAvatarVisualShared.d.ts

@@ -0,0 +1,125 @@
+/**
+ * One 2D point used by the shared organic octopus geometry helpers.
+ *
+ * @private helper of octopus avatar visuals
+ */
+type Point = {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * Shape parameters for the smooth octopus silhouette generator.
+ *
+ * @private helper of octopus avatar visuals
+ */
+type CreateOrganicOctopusBodyPointsOptions = {
+    readonly centerX: number;
+    readonly centerY: number;
+    readonly bodyRadius: number;
+    readonly horizontalStretch: number;
+    readonly verticalStretch: number;
+    readonly mantleLift: number;
+    readonly lowerDrop: number;
+    readonly tentacleDepth: number;
+    readonly wobbleAmplitude: number;
+    readonly lobeCount: number;
+    readonly shapePhase: number;
+    readonly timeMs: number;
+    readonly pointCount?: number;
+};
+/**
+ * One deterministic ribbon tentacle attached to an organic octopus mantle.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export type OrganicTentacleShape = {
+    readonly startPoint: Point;
+    readonly controlPointOne: Point;
+    readonly controlPointTwo: Point;
+    readonly endPoint: Point;
+    readonly baseWidth: number;
+    readonly tipWidth: number;
+    readonly colorBias: number;
+    readonly highlightBias: number;
+    readonly sampleCount: number;
+};
+/**
+ * Options for generating deterministic organic octopus tentacles.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+type CreateOrganicOctopusTentacleShapesOptions = {
+    readonly size: number;
+    readonly centerX: number;
+    readonly centerY: number;
+    readonly bodyRadius: number;
+    readonly horizontalStretch: number;
+    readonly tentacleCount: number;
+    readonly shapePhase: number;
+    readonly createRandom: (salt: string) => () => number;
+    readonly timeMs: number;
+    readonly saltPrefix: string;
+};
+/**
+ * One sampled ribbon point on an organic octopus tentacle.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export type OrganicTentacleRibbonPoint = {
+    readonly x: number;
+    readonly y: number;
+    readonly normalX: number;
+    readonly normalY: number;
+    readonly width: number;
+    readonly progress: number;
+};
+/**
+ * Builds a smoothly morphing octopus-like silhouette from deterministic parameters.
+ *
+ * @param options Shape construction options.
+ * @returns Closed-loop body points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+export declare function createOrganicOctopusBodyPoints(options: CreateOrganicOctopusBodyPointsOptions): Array<Point>;
+/**
+ * Traces a smooth closed path through the provided points.
+ *
+ * @param context Canvas 2D context.
+ * @param points Closed-loop points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+export declare function traceSmoothClosedPath(context: CanvasRenderingContext2D, points: ReadonlyArray<Point>): void;
+/**
+ * Creates deterministic ribbon tentacles for the organic octopus visuals.
+ *
+ * @param options Tentacle construction options.
+ * @returns Tentacle descriptors.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export declare function createOrganicOctopusTentacleShapes(options: CreateOrganicOctopusTentacleShapesOptions): Array<OrganicTentacleShape>;
+/**
+ * Samples the cubic tentacle centerline and offsets normals to build a filled ribbon.
+ *
+ * @param tentacleShape Deterministic tentacle descriptor.
+ * @returns Sampled ribbon points.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export declare function sampleOrganicTentacleRibbonPoints(tentacleShape: OrganicTentacleShape): Array<OrganicTentacleRibbonPoint>;
+/**
+ * Samples one point on a cubic Bezier curve.
+ *
+ * @param startPoint Curve start point.
+ * @param controlPointOne First control point.
+ * @param controlPointTwo Second control point.
+ * @param endPoint Curve end point.
+ * @param progress Sampling progress in the range `[0, 1]`.
+ * @returns Sampled point.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+export declare function getCubicBezierPoint(startPoint: Point, controlPointOne: Point, controlPointTwo: Point, endPoint: Point, progress: number): Point;
+export {};

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

@@ -75,7 +75,7 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
     /**
      * Controls whether assistant replies render as bubbles or article blocks.
      */
-    CHAT_VISUAL_MODE?: ChatProps['CHAT_VISUAL_MODE'];
+    visualMode?: ChatProps['visualMode'];
     /**
      * Called when a tool call chiplet is clicked.
      */

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

@@ -46,7 +46,7 @@ export type ChatMessageListProps = {
     toolTitles?: Record<string, string>;
     teammates?: ChatProps['teammates'];
     teamAgentProfiles?: ChatProps['teamAgentProfiles'];
-    CHAT_VISUAL_MODE?: ChatProps['CHAT_VISUAL_MODE'];
+    visualMode?: ChatProps['visualMode'];
     onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
     onCitationClick?: (citation: ParsedCitation) => void;
     soundSystem?: ChatProps['soundSystem'];

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

@@ -747,7 +747,7 @@ export type ChatProps = {
      *
      * @default 'ARTICLE_MODE'
      */
-    readonly CHAT_VISUAL_MODE?: ChatVisualMode;
+    readonly visualMode?: ChatVisualMode;
     /**
      * Visual style of the chat component
      */

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

@@ -1,4 +1,6 @@
 import { type ReactNode } from 'react';
+import type { AvatarDefinition } from '../../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../../avatars/types/AvatarVisualDefinition';
 /**
  * Props for a team modal header profile badge.
  *
@@ -7,6 +9,8 @@ import { type ReactNode } from 'react';
 export type TeamHeaderProfileProps = {
     label: string;
     avatarSrc?: string | null;
+    avatarDefinition?: AvatarDefinition;
+    avatarVisualId?: AvatarVisualId;
     href?: string;
     fallbackColor?: string;
 };
@@ -15,7 +19,7 @@ export type TeamHeaderProfileProps = {
  *
  * @private component of `<Chat/>`
  */
-export declare function TeamHeaderProfile({ label, avatarSrc, href, fallbackColor }: TeamHeaderProfileProps): import("react/jsx-runtime").JSX.Element;
+export declare function TeamHeaderProfile({ label, avatarSrc, avatarDefinition, avatarVisualId, href, fallbackColor, }: TeamHeaderProfileProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Props for a self-learning modal avatar.
  *
@@ -24,6 +28,8 @@ export declare function TeamHeaderProfile({ label, avatarSrc, href, fallbackColo
 export type SelfLearningAvatarProps = {
     label: string;
     avatarSrc?: string | null;
+    avatarDefinition?: AvatarDefinition;
+    avatarVisualId?: AvatarVisualId;
     fallbackColor?: string;
     className?: string;
     children?: ReactNode;
@@ -33,4 +39,4 @@ export type SelfLearningAvatarProps = {
  *
  * @private component of `<Chat/>`
  */
-export declare function SelfLearningAvatar({ label, avatarSrc, fallbackColor, className, children, }: SelfLearningAvatarProps): import("react/jsx-runtime").JSX.Element;
+export declare function SelfLearningAvatar({ label, avatarSrc, avatarDefinition, avatarVisualId, fallbackColor, className, children, }: SelfLearningAvatarProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/Chat/hooks/useChatCompleteNotification.d.ts

@@ -8,6 +8,8 @@ import type { ChatMessage } from '../types/ChatMessage';
  * - Every streaming chunk / intermediate content update
  * - `message_typing` lifecycle events before the message is finalized
  * - Re-renders of an already-notified completed message (idempotent)
+ * - Initial mount hydration with preloaded completed chat history
+ * - Switching to another chat thread that already contains completed history
  * - User-originated messages
  *
  * @param messages - Current list of chat messages

package/esm/src/book-components/Chat/types/ChatParticipant.d.ts

@@ -1,6 +1,8 @@
 import type { string_book } from '../../../book-2.0/agent-source/string_book';
 import type { id, string_color, string_person_fullname, string_url_image } from '../../../types/typeAliases';
 import { Color } from '../../../utils/color/Color';
+import type { AvatarDefinition } from '../../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../../avatars/types/AvatarVisualDefinition';
 /**
  * A participant in the chat
  *
@@ -23,6 +25,14 @@ export type ChatParticipant = {
      * Profile picture
      */
     avatarSrc?: string_url_image;
+    /**
+     * Deterministic avatar definition used when no static image should be shown.
+     */
+    avatarDefinition?: AvatarDefinition;
+    /**
+     * Built-in avatar visual id used with `avatarDefinition`.
+     */
+    avatarVisualId?: AvatarVisualId;
     /**
      * Color associated with the participant
      */

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

@@ -1,6 +1,6 @@
 import type { InitializationStatus } from './boilerplateTemplates';
 /**
- * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+ * Ensures `.gitignore` contains the standalone Promptbook coder temp and cache entries.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */

package/esm/src/config.d.ts

@@ -41,7 +41,7 @@ export declare const ADMIN_GITHUB_NAME: string_name;
  *
  * @public exported from `@promptbook/core`
  */
-export declare const CLAIM = "Turn your company's scattered knowledge into AI ready books";
+export declare const CLAIM = "Create persistent AI agents that turn your company's scattered knowledge into action";
 /**
  * Color of the Promptbook
  *
@@ -89,7 +89,7 @@ export declare const USER_CHAT_COLOR: import("./utils/take/interfaces/ITakeChain
  *
  * @public exported from `@promptbook/core`
  */
-export declare const DEFAULT_BOOK_TITLE = "\u2728 Untitled Book";
+export declare const DEFAULT_BOOK_TITLE = "\uD83D\uDC19 Untitled agent";
 /**
  * When the title of task is not provided, the default title is used
  *

package/esm/src/llm-providers/agent/RemoteAgent.d.ts

@@ -2,6 +2,7 @@ import type { CallChatModelStreamOptions } from '../../execution/LlmExecutionToo
 import type { ChatPromptResult } from '../../execution/PromptResult';
 import type { Prompt } from '../../types/Prompt';
 import type { string_agent_hash, string_agent_name } from '../../types/typeAliases';
+import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
 import { Agent } from './Agent';
 import type { RemoteAgentOptions } from './RemoteAgentOptions';
 /**
@@ -28,6 +29,8 @@ export declare class RemoteAgent extends Agent {
     toolTitles: Record<string, string>;
     private _isVoiceCallingEnabled;
     private _isVoiceTtsSttEnabled;
+    isMetaImageExplicit: boolean;
+    avatarVisualId: AvatarVisualId | undefined;
     /**
      * Indicates whether the remote server allows text-to-speech and speech-to-text.
      *

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

@@ -1,3 +1,5 @@
+import type { AvatarDefinition } from '../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
 import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
 import type { string_url, string_url_image } from '../../types/typeAliases';
 /**
@@ -5,25 +7,67 @@ import type { string_url, string_url_image } from '../../types/typeAliases';
  *
  * @private utility of `<Chat/>`
  */
-export type ResolveAgentAvatarImageUrlOptions = {
+export type ResolveAgentAvatarOptions = {
     /**
      * Agent metadata used for avatar resolution.
      */
-    readonly agent: Pick<AgentBasicInformation, 'agentName' | 'permanentId' | 'meta'>;
+    readonly agent: Pick<AgentBasicInformation, 'agentName' | 'agentHash' | 'permanentId' | 'meta'> & {
+        /**
+         * Optional explicit marker coming from remote profile payloads.
+         * When `false`, `meta.image` is treated as the generated static fallback rather than a user-defined `META IMAGE`.
+         */
+        readonly isMetaImageExplicit?: boolean;
+        /**
+         * Optional preferred avatar visual id coming from remote profile payloads.
+         */
+        readonly avatarVisualId?: AvatarVisualId;
+    };
     /**
      * Optional base URL used to resolve relative meta images and placeholders.
      */
     readonly baseUrl?: string_url;
 };
+/**
+ * Backward-compatible alias kept for callers that only need image URLs.
+ *
+ * @private utility of `<Chat/>`
+ */
+export type ResolveAgentAvatarImageUrlOptions = ResolveAgentAvatarOptions;
+/**
+ * Default built-in avatar visual used when an agent does not define `META IMAGE`.
+ *
+ * @private shared avatar contract
+ */
+export declare const DEFAULT_AGENT_AVATAR_VISUAL_ID: AvatarVisualId;
+/**
+ * Resolved avatar descriptor used by interactive UIs to pick either an image or a live canvas visual.
+ *
+ * @private shared avatar contract
+ */
+export type ResolvedAgentAvatar = {
+    readonly type: 'image';
+    readonly imageUrl: string_url_image;
+} | {
+    readonly type: 'visual';
+    readonly avatarDefinition: AvatarDefinition;
+    readonly visualId: AvatarVisualId;
+};
 /**
  * Resolve the fallback avatar URL for an agent.
  *
  * @private utility of `<Chat/>`
  */
-export declare function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarImageUrlOptions): string_url_image | null;
+export declare function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarOptions): string_url_image | null;
+/**
+ * Resolve the best avatar representation for an agent, preferring explicit `META IMAGE`
+ * and otherwise returning the default deterministic canvas visual.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function resolveAgentAvatar(options: ResolveAgentAvatarOptions): ResolvedAgentAvatar | null;
 /**
- * Resolve the best avatar URL for an agent, preferring META IMAGE and falling back to placeholders.
+ * Resolve the best avatar URL for an agent, preferring `META IMAGE` and falling back to the static placeholder route.
  *
  * @private utility of `<Chat/>`
  */
-export declare function resolveAgentAvatarImageUrl(options: ResolveAgentAvatarImageUrlOptions): string_url_image | null;
+export declare function resolveAgentAvatarImageUrl(options: ResolveAgentAvatarOptions): string_url_image | null;

package/esm/src/utils/agents/resolveAgentAvatarImageUrl.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.112.0-45`).
+ * It follows semantic versioning (e.g., `0.112.0-46`).
  *
  * @generated
  */

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-46",
-    "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
+    "version": "0.112.0-47",
+    "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
     "repository": {
@@ -102,6 +102,7 @@
         "@azure/openai": "1.0.0-beta.13",
         "@mozilla/readability": "0.6.0",
         "@openai/agents": "0.4.12",
+        "@supabase/supabase-js": "2.81.1",
         "bottleneck": "2.19.5",
         "colors": "1.4.0",
         "commander": "12.0.0",
@@ -121,6 +122,7 @@
         "pg": "8.16.3",
         "prompts": "2.4.2",
         "react": "18.2.0",
+        "react-dom": "18.2.0",
         "rxjs": "7.8.2",
         "showdown": "2.1.0",
         "socket.io": "4.8.3",