@promptbook/remote-server/esm/src/utils/agents/resolveAgentAvatarImageUrl.d.ts

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

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 } from '../../types/string_url';
import type { string_url_image } from '../../types/string_url_image';
/**
 * Options for resolving agent avatar URLs.
 *
 * @private utility of `<Chat/>`
 */
export type ResolveAgentAvatarOptions = {
    /**
     * Agent metadata used for avatar resolution.
     */
    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 server-wide fallback visual id forwarded by federated server payloads.
         */
        readonly defaultAgentAvatarVisualId?: 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;
};
/**
 * Resolves the avatar visual preferred by an agent, then falls back to a federated server default
 * and finally to the caller/server default.
 *
 * @param agent Agent metadata and optional remote-profile visual id.
 * @param defaultAvatarVisualId Optional metadata-resolved server default.
 * @returns Supported avatar visual id.
 *
 * @private shared avatar contract
 */
export declare function resolveAgentAvatarVisualId(agent: ResolveAgentAvatarOptions['agent'], defaultAvatarVisualId?: AvatarVisualId): AvatarVisualId;
/**
 * Resolve the fallback avatar URL for an agent.
 *
 * @private utility of `<Chat/>`
 */
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 the static placeholder route.
 *
 * @private utility of `<Chat/>`
 */
export declare function resolveAgentAvatarImageUrl(options: ResolveAgentAvatarOptions): string_url_image | null;