@xpert-ai/chatkit-types 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -36,6 +36,46 @@ export declare interface ApprovalHostReference {
     expiresAt: number;
 }
 
+/** IDs are resource identifiers, not a closed list of bundled presets. */
+export declare type AssistantAppearance = {
+    version: 1;
+    kind: 'image';
+} | {
+    version: 1;
+    kind: 'character';
+    id: string;
+    color: string;
+    config?: AssistantCharacterConfig;
+} | {
+    version: 1;
+    kind: 'pet';
+    id: string;
+    /** Sprite layout version; omitted by legacy v1 avatars. */
+    spriteVersionNumber?: 1 | 2;
+    asset?: {
+        type: 'sprite-atlas' | 'animated-image';
+        url: string;
+    };
+};
+
+export declare type AssistantCharacterConfig = {
+    shape: 'round' | 'pebble' | 'pill' | 'drop' | 'flame' | 'triangle' | 'square' | 'bag' | 'star' | 'heart' | 'cloud' | 'clover';
+    eyes: 'oval' | 'toon' | 'pill' | 'dot' | 'ring' | 'happy' | 'sleepy' | 'wink' | 'plus' | 'slash' | 'squint';
+    mouth: 'none' | 'smile' | 'open' | 'neutral' | 'o';
+    motion: 'float' | 'bounce' | 'sway' | 'none';
+    eyeSize: number;
+    eyeSpacing: number;
+    brows?: 'none' | 'flat' | 'angry' | 'worried' | 'raised';
+    ink?: 'auto' | 'dark' | 'light';
+    tilt?: number;
+    speed?: number;
+    blink?: boolean;
+};
+
+export declare type AssistantCustomizeEffect = {
+    assistantId: string;
+};
+
 /**
  * strategies to host files before attaching them to messages.
  */
@@ -220,6 +260,8 @@ export declare type ChatFileChange = {
     updatedAt?: string;
 };
 
+export declare const CHATKIT_ASSISTANT_CUSTOMIZE_EFFECT = "assistant.customize";
+
 export declare const CHATKIT_TASK_SUMMARY_OPEN_RESOURCE_EFFECT: "task_summary.open_resource";
 
 export declare interface ChatKitApprovalsOptions {
@@ -231,6 +273,18 @@ export declare interface ChatKitApprovalsOptions {
     onAction?: (input: ApprovalActionRequest) => Promise<void> | void;
 }
 
+/** Computer shortcuts in the Assistant details dialog. Remote targets use registered View keys. */
+export declare type ChatKitAssistantComputers = {
+    cloud?: {
+        viewKey: string;
+    };
+    /** Host-reported local Shell state; opening emits assistant.computer.open with kind: local. */
+    local?: {
+        name?: string;
+        status: 'loading' | 'unavailable' | 'disabled' | 'ready' | 'connected' | 'error';
+    };
+};
+
 export declare type ChatKitClientSecretObject = {
     secret: string;
     organizationId?: string;
@@ -460,6 +514,14 @@ export declare type ChatKitMessageNavigationOptions = {
     enabled?: boolean;
 };
 
+/** Rendering policy only; never changes messages, execution or model context. */
+export declare type ChatKitMessagePresentationOptions = {
+    /** Defaults to the existing transcript presentation. */
+    mode?: 'transcript' | 'bubbles';
+    /** Collapse the process before the final answer. Only applies to transcript. */
+    collapseProcess?: boolean;
+};
+
 export declare type ChatKitOptions = {
     /**
      * ChatKit iframe URL for web component integrations.
@@ -513,10 +575,7 @@ export declare type ChatKitOptions = {
      */
     messageNavigation?: ChatKitMessageNavigationOptions;
     /** Message presentation only; never changes stored messages or model context. */
-    messagePresentation?: {
-        /** Collapse the process preceding each final assistant answer. Default: false. */
-        collapseProcess?: boolean;
-    };
+    messagePresentation?: ChatKitMessagePresentationOptions;
     /**
      * Optional Xpert Remote Views workbench.
      *
@@ -576,6 +635,15 @@ export declare type ChatKitOptions = {
      */
     header?: {
         enabled?: boolean;
+        /** Center the published Assistant character in bubble mode. Defaults to true. */
+        character?: {
+            enabled?: boolean;
+            /** Shows customization actions, emitted as the assistant.customize public effect. */
+            customizable?: boolean;
+            computers?: ChatKitAssistantComputers;
+            /** Honor an explicit reduced-animation preference in addition to the OS setting. */
+            reducedMotion?: boolean;
+        };
         /** Enable native Electron dragging/OS double-click behavior on unused chat and Workbench header space. Defaults to false. */
         windowDrag?: boolean;
         /**
@@ -791,6 +859,8 @@ export declare type ChatKitPetBoundsPadding = {
 export declare type ChatKitPetCharacter = {
     type: 'sprite-atlas';
     src: string;
+    /** v1: 8 × 9; v2: 8 × 11, with 16 directional poses in the final two rows. */
+    spriteVersionNumber?: 1 | 2;
     atlas?: ChatKitPetSpriteAtlas;
 };
 
@@ -1005,6 +1075,11 @@ export declare type ChatKitThreadReference = {
 };
 
 export declare type ChatKitWorkbenchClientCommandRequest = {
+    /** User-clicked persisted resource; hosts resolve its canonical target from message history. */
+    resourceCard?: {
+        messageId: string;
+        id: string;
+    };
     commandKey: string;
     payload?: unknown;
     hostType: 'agent';
@@ -1034,9 +1109,8 @@ export declare type ChatKitWorkbenchOptions = {
      */
     enabled?: boolean;
     /**
-     * Show a vertical strip of available remote-view icons at the right edge of
-     * chat while the workbench is closed. Clicking an icon opens that view.
-     * Requires `workbench.enabled`. Disabled by default.
+     * @deprecated Views now open from the stacked-tabs button in the chat header.
+     * This option is retained for compatibility and no longer renders a view rail.
      */
     viewRail?: {
         enabled?: boolean;
@@ -1375,9 +1449,25 @@ declare type ControlSize = '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2
 
 declare type ControlVariant = 'solid' | 'soft' | 'outline' | 'ghost';
 
+/** Presentation of a committed business resource; distinct from versioned file Artifacts. */
+export declare interface ConversationResourceCard {
+    resource: {
+        namespace: string;
+        type: string;
+        id: string;
+        artifactId?: string;
+    };
+    title: string;
+    description?: string;
+    icon?: IconDefinition;
+    open: ResourceCardOpenTarget;
+}
+
 /** Exact line LCS with bounded CPU/memory. Unknown text never becomes zero changes. */
 export declare function countFileChangeLines(report: FileChangeReport): FileChangeLineStats;
 
+export declare function createResourceCardContent(card: ConversationResourceCard): TMessageContentResourceCard;
+
 declare type CustomApiConfig = {
     /**
      * The URL (relative or absolute) of the ChatKit API. The configured endpoint
@@ -1409,6 +1499,10 @@ declare type CustomApiConfig = {
     xpertId?: string;
 };
 
+export declare function customCharacterSvg(appearance: Extract<AssistantAppearance, {
+    kind: 'character';
+}>, state?: string, animate?: boolean): string;
+
 export declare type DatePicker = {
     type: 'DatePicker';
     key?: string;
@@ -1440,6 +1534,8 @@ export declare const DEFAULT_PET_SPRITESHEET_URL = "/pets/boba/spritesheet.webp"
 
 export declare const DEFAULT_PET_STORAGE_KEY = "chatkit:pet:position:v1";
 
+export declare const defaultCharacterConfig: AssistantCharacterConfig;
+
 export declare type Divider = {
     type: 'Divider';
     key?: string;
@@ -1871,6 +1967,8 @@ export declare function isLangGraphInterruptPayload(value: unknown): value is La
 
 export declare function isLangGraphInterruptTask(value: unknown): value is LangGraphInterruptTask;
 
+export declare function isResourceCardContent(value: unknown): boolean;
+
 export declare function isToolCallInterrupt(value: unknown): value is ToolCallInterrupt;
 
 export declare function isToolCallInterruptPayload(value: unknown): value is ToolCallInterruptPayload;
@@ -1948,7 +2046,7 @@ export declare function mergeChatSkillUsages(...groups: ReadonlyArray<readonly C
 /** Collapse observed operations to the net change, retaining immutable first/last review references. */
 export declare function mergeFileChanges(items: ChatFileChange[]): ChatFileChange[];
 
-export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas): PetSpriteAtlasDefinition;
+export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas, spriteVersionNumber?: 1 | 2): PetSpriteAtlasDefinition;
 
 export declare type MessageContentImageUrl = {
     type: 'image_url';
@@ -2019,10 +2117,17 @@ export declare function normalizeRequestLanguage(locale?: string | null): string
 
 export declare function normalizeThreadReference(value: unknown): ChatKitThreadReference | null;
 
+export declare function parseAssistantAppearance(value: unknown): AssistantAppearance | undefined;
+
 export declare function parseFileActivityContent(value: unknown): TMessageContentFileActivity | null;
 
 export declare function parseFileChangeReport(value: unknown): FileChangeReport | null;
 
+/** JSON boundary: copy only supported fields, never executable commands or host URLs. */
+export declare function parseResourceCard(value: unknown): ConversationResourceCard | null;
+
+export declare function parseResourceCardContent(value: unknown): TMessageContentResourceCard | null;
+
 export declare const PET_ANIMATION_NAMES: readonly ["idle", "running-right", "running-left", "waving", "jumping", "failed", "waiting", "running", "review"];
 
 export declare type PetFrameAnimationDefinition = {
@@ -2031,6 +2136,12 @@ export declare type PetFrameAnimationDefinition = {
     frameDurations: readonly number[];
 };
 
+/** v2's 16 poses are clockwise from up; a central dead zone restores idle. */
+export declare function petLookFrame(dx: number, dy: number, deadZone?: number): {
+    row: number;
+    column: number;
+} | null;
+
 export declare type PetPosition = {
     x: number;
     y: number;
@@ -2207,6 +2318,21 @@ export declare function resolveLocalizedText(value: unknown, language?: string):
 
 export declare function resolvePetCharacter(character: ChatKitPetCharacter): ResolvedPetCharacter | null;
 
+export declare function resourceCardId(card: ConversationResourceCard): string;
+
+export declare type ResourceCardOpenTarget = {
+    viewKey: string;
+    selectionId?: string;
+    parameters?: Record<string, ResourceCardScalar | ResourceCardScalar[]>;
+} & ({
+    target: 'workbench.view';
+} | {
+    target: 'assistant.project';
+    projectId: string;
+});
+
+export declare type ResourceCardScalar = string | number | boolean | null;
+
 export declare type Row = {
     type: 'Row';
     key?: string;
@@ -2727,7 +2853,7 @@ export declare type TMessageContent = string | TMessageContentComplex[];
 /**
  * Enhance {@link MessageContentComplex} in Langchain.js
  */
-export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentFileActivity | TMessageContentMemory | (Record<string, any> & {
+export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentFileActivity | TMessageContentResourceCard | TMessageContentMemory | (Record<string, any> & {
     type?: 'text' | 'image_url' | string;
 }) | (Record<string, any> & {
     type?: never;
@@ -2790,6 +2916,15 @@ export declare type TMessageContentReasoning = {
     text: string;
 };
 
+export declare interface TMessageContentResourceCard {
+    type: 'resource_card';
+    id: string;
+    data: ConversationResourceCard;
+    /** Bound by the server, never supplied by an emitting plugin. */
+    messageId?: string;
+    executionId?: string;
+}
+
 export declare type TMessageContentText = {
     id?: string;
     xpertName?: string;
@@ -2900,7 +3035,7 @@ export declare type ToolOutputImageAttachment = {
 
 export declare type ToolOutputImageMimeType = 'image/png' | 'image/jpeg' | 'image/webp';
 
-export declare type ToolOutputImageSource = 'knowledge-document' | 'sandbox';
+export declare type ToolOutputImageSource = 'knowledge-document' | 'sandbox' | 'tool';
 
 /**
  * UI-only ToolMessage artifact. ToolMessage content remains the compact
@@ -2992,6 +3127,9 @@ export declare type TXpertChatTarget = {
 /** Receipts are immutable terminal facts; replay replaces by identity, never appends a second operation. */
 export declare function upsertFileActivityContent<T>(content: T[], receipt: TMessageContentFileActivity): (T | TMessageContentFileActivity)[];
 
+/** Identity is local to one reply. Repeat emissions replace the snapshot in place. */
+export declare function upsertResourceCardContent<T>(parts: T[], card: TMessageContentResourceCard): (T | TMessageContentResourceCard)[];
+
 export declare type UserMessageContent = unknown;
 
 export declare type WidgetComponent = TextComponent | Title | Caption | Badge | Markdown | Box | Row | Col | Divider | Icon | Image_2 | Button | Checkbox | Spacer | Select | DatePicker | Form | Input | Label | RadioGroup | Textarea | Transition;