@promptbook/core/umd/src/utils/agents/terminalAgentAvatarVisual.d.ts

Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action

import { type CreateCanvasForAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
import type { string_book } from '../../book-2.0/agent-source/string_book';
import type { AsciiArtColorDepth } from '../ascii-art/convertImageDataToAsciiArt';
/**
 * Output width of the terminal agent avatar visual in character cells.
 *
 * @private shared helper for terminal avatar rendering
 */
export declare const TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS = 48;
/**
 * Output height of the terminal agent avatar visual in character cells.
 *
 * @private shared helper for terminal avatar rendering
 */
export declare const TERMINAL_AGENT_AVATAR_VISUAL_ROWS = 12;
/**
 * Refresh cadence used while a terminal agent avatar visual is animated.
 *
 * @private shared helper for terminal avatar rendering
 */
export declare const TERMINAL_AGENT_AVATAR_VISUAL_REFRESH_INTERVAL_MS = 300;
/**
 * Options passed when rendering one animated terminal avatar frame.
 *
 * @private shared helper for terminal avatar rendering
 */
export type TerminalAgentAvatarVisualFrameOptions = {
    /**
     * Current animation time forwarded to the shared avatar renderer.
     */
    readonly animationTimeMs: number;
};
/**
 * Runtime renderer for an agent avatar visual shown in a terminal.
 *
 * @private shared helper for terminal avatar rendering
 */
export type TerminalAgentAvatarVisual = {
    /**
     * Whether the selected built-in visual changes over time.
     */
    readonly isAnimated: boolean;
    /**
     * Renders one ANSI ASCII-art frame for the current terminal timestamp.
     */
    readonly renderFrame: (options: TerminalAgentAvatarVisualFrameOptions) => ReadonlyArray<string>;
};
/**
 * Options for creating a terminal avatar visual renderer from an agent book source.
 *
 * @private shared helper for terminal avatar rendering
 */
export type CreateTerminalAgentAvatarVisualOptions = {
    /**
     * Source of the agent book whose metadata controls avatar identity.
     */
    readonly agentSource: string_book;
    /**
     * Built-in avatar visual used when the agent does not declare `META AVATAR` or `META VISUAL`.
     */
    readonly defaultAvatarVisualId?: AvatarVisualId;
    /**
     * Color depth of the emitted ANSI escape codes.
     */
    readonly colorDepth?: AsciiArtColorDepth;
    /**
     * Platform-specific canvas factory used to rasterize the visual.
     */
    readonly createCanvas: CreateCanvasForAsciiArt;
};
/**
 * Resolves the built-in avatar visual selected for terminal rendering of one agent source.
 *
 * @param agentSource Source of the agent book.
 * @param defaultAvatarVisualId Built-in fallback used when the source does not declare an avatar visual.
 * @returns Supported built-in avatar visual id.
 *
 * @private shared helper for terminal avatar rendering
 */
export declare function resolveTerminalAgentAvatarVisualId(agentSource: string_book, defaultAvatarVisualId?: AvatarVisualId): AvatarVisualId;
/**
 * Creates an ANSI ASCII-art avatar renderer for terminal UIs.
 *
 * The agent's avatar visual is resolved the same way as on the website: `META AVATAR`
 * / `META VISUAL` wins, then the provided fallback visual, then the shared default visual.
 * The terminal variant uses a transparent horizontal canvas instead of the website's framed square surface.
 *
 * @param options Agent source, canvas factory, and optional terminal color settings.
 * @returns Runtime terminal avatar visual renderer.
 *
 * @private shared helper for terminal avatar rendering
 */
export declare function createTerminalAgentAvatarVisual(options: CreateTerminalAgentAvatarVisualOptions): TerminalAgentAvatarVisual;