@promptbook/google 0.112.0-46 → 0.112.0-47

package/README.md

@@ -1,8 +1,8 @@
 <!-- ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten -->
 
-# ✨ Promptbook: AI Agents
+# 🐙 Promptbook: Invisible AI Agents
 
-Create persistent AI agents that turn your company's scattered knowledge into action — powered by the [Agents Server](https://gallery.ptbk.io/)
+Create persistent AI agents that turn your company's scattered knowledge into action - powered by the [Agents Server](https://gallery.ptbk.io/)
 
 
 
@@ -253,13 +253,13 @@ Rest of the documentation is common for **entire promptbook ecosystem**:
 
 ## 📖 The Book Whitepaper
 
-Promptbook lets you create **persistent AI agents** that work on real goals for your company. The [**Agents Server**](https://gallery.ptbk.io/) is the heart of the project — a place where your AI agents live, remember context, collaborate in teams, and get things done.
+Promptbook lets you create **persistent AI agents** that work on real goals for your company. The [**Agents Server**](https://gallery.ptbk.io/) is the heart of the project - a place where your AI agents live, remember context, collaborate in teams, and get things done.
 
 Nowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as GPT-5.2 and Claude-4.5 are incredibly capable.
 
 The main challenge lies in **managing the context**, providing rules and knowledge, and narrowing the personality.
 
-In Promptbook, you define your agents **using simple Books** — a human-readable language that is explicit, easy to understand and write, reliable, and highly portable. You then deploy them to the **Agents Server**, where they run persistently and work toward their goals.
+In Promptbook, you define your agents **using simple Books** - a human-readable language that is explicit, easy to understand and write, reliable, and highly portable. You then deploy them to the **Agents Server**, where they run persistently and work toward their goals.
 
 <table style="border: 1px solid #777; border-radius: 10px;"><tr><td>
 
@@ -360,7 +360,7 @@ Your job is to provide legal advice and support to the company and its employees
 
 #### `Use` commitments
 
-Use commitments grant the agent real capabilities — tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
+Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
 
 These are what turn a chatbot into a persistent agent that actually does work.
 
@@ -409,7 +409,7 @@ Your job is to provide legal advice and support to the company and its employees
 
 ### Promptbook Ecosystem
 
-Promptbook is an ecosystem of tools centered around the **Agents Server** — a production-ready platform for running persistent AI agents.
+Promptbook is an ecosystem of tools centered around the **Agents Server** - a production-ready platform for running persistent AI agents.
 
 #### Agents Server
 
@@ -431,7 +431,7 @@ The [Promptbook Engine](https://github.com/webgptorg/promptbook) is the open-sou
 
 ## 💜 The Promptbook Project
 
-Promptbook project is an ecosystem centered around the **Agents Server** — a platform for creating, deploying, and running persistent AI agents. Following is a list of the most important pieces of the project:
+Promptbook project is an ecosystem centered around the **Agents Server** - a platform for creating, deploying, and running persistent AI agents. Following is a list of the most important pieces of the project:
 
 <table>
   <thead>
@@ -444,7 +444,7 @@ Promptbook project is an ecosystem centered around the **Agents Server** — a p
     <tr>
       <td><a href="https://gallery.ptbk.io/"><strong>⭐ Agents Server</strong></a></td>
       <td>
-          The primary way to use Promptbook. A production-ready platform where your AI agents live — create, manage, deploy, and interact with persistent agents that work on goals. Available as a hosted service or <a href="https://hub.docker.com/r/hejny/promptbook/">self-hosted via Docker</a>.
+          The primary way to use Promptbook. A production-ready platform where your AI agents live - create, manage, deploy, and interact with persistent agents that work on goals. Available as a hosted service or <a href="https://hub.docker.com/r/hejny/promptbook/">self-hosted via Docker</a>.
       </td>
     </tr>
     <tr>
@@ -534,8 +534,8 @@ For information on reporting security vulnerabilities, see our [Security Policy]
 
 The fastest way to get started is with the **Agents Server**:
 
--   🐋 **[Docker image](https://hub.docker.com/r/hejny/promptbook/)** — Self-host the Agents Server with full control over your data
--   ☁️ **[Hosted Agents Server](https://gallery.ptbk.io/)** — Start creating agents immediately, no setup required
+-   🐋 **[Docker image](https://hub.docker.com/r/hejny/promptbook/)** - Self-host the Agents Server with full control over your data
+-   ☁️ **[Hosted Agents Server](https://gallery.ptbk.io/)** - Start creating agents immediately, no setup required
 
 ### NPM Packages _(for developers embedding the Engine)_
 
@@ -680,7 +680,7 @@ npx ptbk coder verify
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.tmp`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                  |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                             |
+| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                           |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                  | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                             |
 
@@ -691,7 +691,7 @@ npx ptbk coder verify
 | `--agent <name>`           | Selects the coding backend.                                                                        |
 | `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.    |
+| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
 | `--no-wait`                | Skips interactive pauses between prompts for unattended execution.                                 |
 | `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
@@ -794,8 +794,8 @@ _Note: This section is not a complete dictionary, more list of general AI / LLM
 
 The **[Agents Server](https://gallery.ptbk.io/)** is the primary way to use Promptbook. It is a production-ready platform where you create, deploy, and manage persistent AI agents that work toward goals. Agents remember context across conversations, collaborate in teams, and follow the rules and knowledge you define in the Book language.
 
--   **Hosted** at [gallery.ptbk.io](https://gallery.ptbk.io/) — start creating agents immediately
--   **Self-hosted** via [Docker](https://hub.docker.com/r/hejny/promptbook/) — full control over your data and infrastructure
+-   **Hosted** at [gallery.ptbk.io](https://gallery.ptbk.io/) - start creating agents immediately
+-   **Self-hosted** via [Docker](https://hub.docker.com/r/hejny/promptbook/) - full control over your data and infrastructure
 -   **API** for integrating agents into your own applications
 
 ## 🚂 Promptbook Engine
@@ -813,7 +813,7 @@ The Engine is the open-source core that powers the Agents Server. If you need to
 -   When you want agents that **collaborate in teams** and consult each other
 -   When you need to **integrate AI agents into your existing applications** via API
 -   When you want to **self-host** your AI agents with full control over data and infrastructure
--   When you are writing an app that generates complex things via LLM — like **websites, articles, presentations, code, stories, songs**,...
+-   When you are writing an app that generates complex things via LLM - like **websites, articles, presentations, code, stories, songs**,...
 -   When you want to **version** your agent definitions and **test multiple versions**
 -   When you want to **log** agent execution and backtrace issues
 
@@ -825,7 +825,7 @@ The Engine is the open-source core that powers the Agents Server. If you need to
 -   When [OpenAI Assistant (GPTs)](https://help.openai.com/en/articles/8673914-gpts-vs-assistants) is enough for you
 -   When you need streaming _(this may be implemented in the future, [see discussion](https://github.com/webgptorg/promptbook/discussions/102))_
 -   When you need to use something other than JavaScript or TypeScript _(other languages are on the way, [see the discussion](https://github.com/webgptorg/promptbook/discussions/101))_
--   When your main focus is on something other than text — like images, audio, video, spreadsheets _(other media types may be added in the future, [see discussion](https://github.com/webgptorg/promptbook/discussions/103))_
+-   When your main focus is on something other than text - like images, audio, video, spreadsheets _(other media types may be added in the future, [see discussion](https://github.com/webgptorg/promptbook/discussions/103))_
 -   When you need to use recursion _([see the discussion](https://github.com/webgptorg/promptbook/discussions/38))_
 
 [See more](https://github.com/webgptorg/promptbook/discussions/112)

package/esm/index.es.js

@@ -16,7 +16,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-46';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-47';
 /**
  * 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/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/google",
-    "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": {
@@ -99,7 +99,7 @@
     "types": "./esm/src/_packages/google.index.d.ts",
     "typings": "./esm/src/_packages/google.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.112.0-46"
+        "@promptbook/core": "0.112.0-47"
     },
     "dependencies": {
         "@ai-sdk/google": "1.0.17",

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-46';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-47';
     /**
      * 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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/src/utils/agents/resolveAgentAvatarImageUrl.test.d.ts

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

package/umd/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
  */