@epam/ai-dial-chat-hooks 1.2.0-dev.15 → 1.2.0-dev.152

package/conversation.d.ts

@@ -15,7 +15,6 @@ import { Message } from '@epam/ai-dial-chat-shared';
 import { MessageCustomContent } from '@epam/ai-dial-chat-shared';
 import { MessageRating } from '@epam/ai-dial-chat-shared';
 import { MutableRefObject } from 'react';
-import { OverlayChatMessage } from '@epam/ai-dial-chat-overlay';
 import { PublishHistoryEntry } from '@epam/ai-dial-publish-panel';
 import { RateApi } from '@epam/ai-dial-chat-api-client';
 import { ReactNode } from 'react';
@@ -24,6 +23,7 @@ import { RequestSkill } from '@epam/ai-dial-chat-shared';
 import { ResponseFormat } from '@epam/ai-dial-chat-shared';
 import { SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
 import { SetStateAction } from 'react';
+import { Stage } from '@epam/ai-dial-chat-shared';
 import { StarterOption } from '@epam/ai-dial-chat-shared';
 import { StatusMessage } from '@epam/ai-dial-chat-shared';
 import { StreamChunk } from '@epam/ai-dial-chat-shared';
@@ -58,6 +58,25 @@ export declare interface AnnouncementListItemLink {
     href: string;
 }
 
+/**
+ * Applies a single SSE stream chunk to the message list.
+ *
+ *
+ * Attachments are accumulated: each chunk's attachments are appended to the
+ * existing array rather than replacing it.
+ *
+ * Annotations are merged by `index`: partial `body.title` and `body.quote`
+ * strings are concatenated across chunks, matching the same delta-merge
+ * semantics used for stages.
+ *
+ * `state` is overwritten (not merged) by each chunk that carries one,
+ * matching the DIAL stateful-app contract.
+ *
+ * @returns Updated message array, or `null` when the chunk carries no
+ *   actionable data (empty content, no form_schema, and no attachments).
+ */
+export declare const applyChunkToMessages: (messages: Message[], messageIndex: number, chunk: StreamChunk) => Message[] | null;
+
 /** State and controls returned by `useAsyncConfirmDialog`. */
 export declare interface AsyncConfirmDialogControls<T> {
     /**
@@ -342,6 +361,9 @@ export declare const createMessagePair: (content: string, customContent?: Messag
 /** Fallback text of a {@link GenerationConflictError} when no message is supplied. */
 export declare const DEFAULT_GENERATION_CONFLICT_MESSAGE = "A response is already being generated in this conversation. Wait for it to finish or stop it before sending another message.";
 
+/** Safe fallback for hosts that do not supply a translated persistence warning. */
+export declare const DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE = "The response could not be saved. It is still shown here, but may be lost if you reload or leave this page. Copy it before continuing.";
+
 /**
  * Derives the row-action visibility state for a single conversation item.
  *
@@ -376,6 +398,12 @@ export declare class GenerationConflictError extends Error {
     constructor(message?: string);
 }
 
+/** Identifies a failed terminal save independently of the model's generation outcome. */
+export declare class GenerationPersistenceError extends Error {
+    static readonly type = "conversation_save_failed";
+    constructor();
+}
+
 /**
  * Strips the leading bucket segment from a conversation id and decodes any
  * already-percent-encoded remainder back to raw, so callers that re-encode
@@ -530,8 +558,8 @@ export declare const isAnswerIncomplete: (answer: Message | undefined) => boolea
  * True when the conversation's last message is an unresolved assistant
  * placeholder: the backend only persists a conversation at generation start
  * (empty placeholder) and at generation end (final content, or a partial
- * flagged `streamErrorMessage`/`wasStoppedByUser`), so this shape means a
- * generation was still active elsewhere when the conversation was loaded.
+ * flagged `streamErrorMessage`/`wasStoppedByUser`). This can mean generation
+ * is still active elsewhere, or that its terminal save failed.
  */
 export declare const isAwaitingGenerationResume: (conversation: Conversation) => boolean;
 
@@ -573,6 +601,29 @@ declare interface LocalModeValues {
     temperature: number;
 }
 
+/**
+ * Returns the normalized stages of a raw stage array or a message-like
+ * payload (reading `custom_content.stages`, falling back to
+ * `customContent.stages`), or `undefined` when there are none.
+ */
+export declare const mapStages: (source: RawStage[] | RawStageSource | null | undefined) => Stage[] | undefined;
+
+/**
+ * Merges incoming stage deltas into an existing stage list, keyed by `index`.
+ *
+ * Partial `name` and `content` strings are concatenated across chunks;
+ * attachments are merged by their own `index` (concatenating partial `title`
+ * and `data`); every other field on the incoming delta overwrites the
+ * accumulated one. A brand-new stage whose first chunk carries `name: null`
+ * is normalized to `''`.
+ *
+ * Exported for hosts that keep a flattened `Stage[]` on the message instead
+ * of `Message.custom_content.stages` and therefore cannot reuse
+ * {@link applyChunkToMessages}. Prefer `useConversationStream` when the host
+ * can delegate the whole stream loop.
+ */
+export declare const mergeStages: (existing: Stage[], incoming: Stage[]) => Stage[];
+
 /** True when `message` is an assistant message carrying at least one stage. */
 export declare const messageHasStages: (message: Message) => boolean;
 
@@ -606,6 +657,63 @@ export declare interface QuickAppConversationStartersSettings {
     isChatMessageInputDisabled: boolean;
 }
 
+/**
+ * One stage as it arrives from the REST API or the SSE stream, before
+ * normalization. Structurally satisfied by the generated `StageDto` and by a
+ * raw stream delta, both of which omit `index`/`name`/`status` on the chunk
+ * that opens a stage.
+ */
+export declare interface RawStage {
+    /** Ordering key. Defaults to `0` when absent. */
+    index?: number | null;
+    /** Stage title. `null` on the chunk that opens the stage. */
+    name?: string | null;
+    /** Terminal state as a raw wire string; anything other than `'completed'`/`'failed'` means still running. */
+    status?: string | null;
+    /** Additional stage text. */
+    content?: string | null;
+    /** Short source/category label shown beside the stage name. */
+    tag?: string | null;
+    /** Files produced or referenced by this stage. */
+    attachments?: RawStageAttachment[] | null;
+}
+
+/**
+ * One stage attachment as it arrives from the REST API or the SSE stream,
+ * before normalization: every field is optional and may be `null`.
+ */
+export declare interface RawStageAttachment {
+    /** Zero-based position in the attachment list. */
+    index?: number | null;
+    /** MIME type of the attachment content. */
+    type?: string | null;
+    /** Display name shown in the UI. */
+    title?: string | null;
+    /** Inline base-64 encoded content. */
+    data?: string | null;
+    /** Remote URL pointing to the attachment content. */
+    url?: string | null;
+    /** MIME type of the referenced resource. */
+    reference_type?: string | null;
+    /** URL of an alternate reference resource. */
+    reference_url?: string | null;
+}
+
+/**
+ * Message-like payload carrying stages under either the wire's snake_case
+ * `custom_content` or a host's camelCased `customContent`.
+ */
+export declare interface RawStageSource {
+    /** Custom content as the DIAL wire format spells it. */
+    custom_content?: {
+        stages?: RawStage[] | null;
+    } | null;
+    /** Custom content as a camelCasing host spells it. */
+    customContent?: {
+        stages?: RawStage[] | null;
+    } | null;
+}
+
 /** State of one resource's recipient-count lookup. */
 declare interface RecipientsCountEntry {
     /** Where the lookup for this resource currently stands. */
@@ -662,8 +770,23 @@ export declare interface StreamCompletionOptions {
     signal: AbortSignal;
 }
 
-/** Maps chat messages to the DIAL Chat Overlay protocol's message shape. */
-export declare const toOverlayMessages: (messages: Message[]) => OverlayChatMessage[];
+/**
+ * Reported through `onError` when DIAL Core itself signals a failure with an
+ * in-band `{ error: { message } }` SSE chunk. Its `message` is upstream text
+ * intended for the user, unlike a transport failure (failed `fetch`, non-OK
+ * status, broken stream), whose message is technical detail. A custom
+ * transport raises this for any user-facing upstream error text.
+ */
+export declare class StreamUpstreamError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Returns a renderable `Stage` for one raw payload: `index` defaults to `0`,
+ * `name` to `''`, an unrecognized `status` to `null` (still running), and
+ * `content`/`tag`/`attachments` are passed through when present.
+ */
+export declare const toStage: (stage: RawStage) => Stage;
 
 /** Request shape the host's selected-deployment recognition call accepts. */
 export declare interface TranscribeWithDeploymentParams {
@@ -728,8 +851,8 @@ export declare const useAttachmentUpload: ({ filesApi, bucket, onNetworkError, d
 
 /** Parameters for {@link useAttachmentUpload}. */
 export declare interface UseAttachmentUploadParams {
-    /** Already-configured generated-client instance used to upload the file. */
-    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** Already-configured client; optional listing skips stored names after a conflict. */
+    filesApi: Pick<FilesApi, 'uploadFile'> & Partial<Pick<FilesApi, 'listFiles'>>;
     /** DIAL Core bucket the file is uploaded into. */
     bucket: string | undefined;
     /** Called with batched filenames after a burst of network-error upload failures. */
@@ -883,9 +1006,8 @@ export declare interface UseConversationLookupMapsParams {
  * panel's item contract. All app-specific concerns (icon URL resolution,
  * route generation, id normalisation) are injected via resolver callbacks.
  */
-export declare const useConversationPanelItems: ({ items, deployments, isDeploymentsLoading, toPanelConversationId, resolveIconUrl, resolveIconTooltip, resolveHref, resolveTaskBadge, }: UseConversationPanelItemsParams) => {
-    showTaskBadge?: boolean | undefined;
-    taskBadgeLabel?: string | undefined;
+export declare const useConversationPanelItems: ({ items, deployments, isDeploymentsLoading, toPanelConversationId, resolveIconUrl, resolveIconTooltip, resolveHref, resolveTaskPresentation, }: UseConversationPanelItemsParams) => {
+    leadingIcon?: ReactNode;
     isUnread?: boolean | undefined;
     id: string;
     title: string;
@@ -921,11 +1043,12 @@ export declare interface UseConversationPanelItemsResolvers {
     /** Resolves the href to navigate to when the conversation row is clicked. */
     resolveHref: (panelConversationId: string) => string;
     /**
-     * Returns badge metadata for a scheduled-task conversation, or `undefined`
-     * when the item should not show a task badge.
+     * Returns the row presentation for a scheduled-task conversation — a
+     * host-rendered leading icon that replaces the deployment avatar, and the
+     * unread flag — or `undefined` for an ordinary conversation.
      */
-    resolveTaskBadge?: (item: ConversationListItemDto) => {
-        label: string;
+    resolveTaskPresentation?: (item: ConversationListItemDto) => {
+        leadingIcon?: ReactNode;
         isUnread: boolean;
     } | undefined;
 }
@@ -938,7 +1061,7 @@ export declare interface UseConversationPanelItemsResolvers {
  * `transport`/`generation`/`channel`/`overlay` capabilities rather than any
  * app context or `server-api` import.
  */
-export declare const useConversationStream: ({ conversationId, state: { setConversation, conversationRef }, transport, generation: { startGeneration, completeGeneration }, channel, overlay, onStopError, generationConflictMessage, }: UseConversationStreamParams) => UseConversationStreamResult;
+export declare const useConversationStream: ({ conversationId, state: { setConversation, conversationRef }, transport, generation: { startGeneration, completeGeneration }, channel, overlay, onStopError, generationConflictMessage, generationPersistenceErrorMessage, onStreamError, }: UseConversationStreamParams) => UseConversationStreamResult;
 
 /** Parameters for {@link useConversationStream}. */
 export declare interface UseConversationStreamParams {
@@ -956,6 +1079,15 @@ export declare interface UseConversationStreamParams {
      * {@link DEFAULT_GENERATION_CONFLICT_MESSAGE}.
      */
     generationConflictMessage?: string;
+    /** Host-translated warning shown when the received answer could not be saved. */
+    generationPersistenceErrorMessage?: string;
+    /**
+     * Receives the original error of every failed stream. The hook shows only
+     * host-supplied or upstream-supplied text on the message bubble and hides
+     * transport detail (e.g. `Failed to fetch`), so this is where the host can
+     * still log or report the raw error.
+     */
+    onStreamError?: (error: Error) => void;
 }
 
 /** Return value of {@link useConversationStream}. */

package/conversation.js

@@ -1,31 +1,32 @@
 import { buildAnnouncementSignature as e, hasAnnouncementContent as t, hasStructuredAnnouncement as n, sanitizeAnnouncementHtml as r, sanitizeAnnouncementMessageHtml as i } from "./conversation/announcement-message.js";
-import { DEFAULT_GENERATION_CONFLICT_MESSAGE as a, GenerationConflictError as o, createChatStreamApi as s } from "./conversation/create-chat-stream-api.js";
-import { shouldWatchForDisplayNameUpdate as c } from "./conversation/display-name-watch.js";
-import { formatAppVersion as l, sanitizeFooterHtml as u } from "./conversation/footer-message.js";
-import { getModelIdFromConversationId as d } from "./conversation/get-model-id-from-conversation-id.js";
-import { getTimeOfDayGreeting as f } from "./conversation/greeting.js";
-import { createDeploymentChangedMessage as p } from "./conversation/message-factory.js";
-import { getLastDeploymentId as m, getLastUserMessageToolConfiguration as h, isMessageStreaming as g, messageHasStages as _, normalizeResponseFormat as v } from "./conversation/message-utils.js";
-import { toOverlayMessages as y } from "./conversation/overlay-messages.js";
-import { getQuickAppConversationStarters as b } from "./conversation/quick-app-conversation-starters.js";
-import { getStarterPopulateText as x, getStartersFromSchema as S } from "./conversation/starter-option.js";
-import { deriveConversationRowActionState as C } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
-import { useActiveConversationSync as w } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
-import { useAsyncConfirmDialog as T } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
-import { useConversationLookupMaps as E } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
-import { getConversationSource as D, useConversationPanelItems as O } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
-import { useImportFilePicker as k } from "./conversation/useImportFilePicker/useImportFilePicker.js";
-import { useAttachmentUpload as A } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
-import { AudioTranscriptionError as j, AudioTranscriptionErrorReason as M } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
-import { useTranscribeAudio as N } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
-import { attachmentToDto as P, attachmentsToDtos as F } from "./conversation/useConversationHandlers/attachment-to-dto.js";
-import { createMessagePair as I } from "./conversation/useConversationHandlers/message-factory.js";
-import { hasActiveToolConfig as L, isAnswerIncomplete as R, isMessageChanged as z, shouldRerunGenerationOnEdit as B } from "./conversation/useConversationHandlers/message-utils.js";
-import { getStarterConversationText as V, getStarterDisplayText as H, getStarterSubmitText as U } from "./conversation/useConversationHandlers/starter-option.js";
-import { getConversationPath as W } from "./conversation/useConversationStream/conversation-path.js";
-import { useConversationHandlers as G } from "./conversation/useConversationHandlers/useConversationHandlers.js";
-import { isAwaitingGenerationResume as K } from "./conversation/useConversationStream/generation-resume.js";
-import { useConversationStream as q } from "./conversation/useConversationStream/useConversationStream.js";
-import { useChatSettingsFormConfig as J } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
-import { useToolsMenu as Y } from "./useToolsMenu/useToolsMenu.js";
-export { j as AudioTranscriptionError, M as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, P as attachmentToDto, F as attachmentsToDtos, e as buildAnnouncementSignature, s as createChatStreamApi, p as createDeploymentChangedMessage, I as createMessagePair, C as deriveConversationRowActionState, l as formatAppVersion, W as getConversationPath, D as getConversationSource, m as getLastDeploymentId, h as getLastUserMessageToolConfiguration, d as getModelIdFromConversationId, b as getQuickAppConversationStarters, V as getStarterConversationText, H as getStarterDisplayText, x as getStarterPopulateText, U as getStarterSubmitText, S as getStartersFromSchema, f as getTimeOfDayGreeting, L as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, R as isAnswerIncomplete, K as isAwaitingGenerationResume, z as isMessageChanged, g as isMessageStreaming, _ as messageHasStages, v as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, u as sanitizeFooterHtml, B as shouldRerunGenerationOnEdit, c as shouldWatchForDisplayNameUpdate, y as toOverlayMessages, w as useActiveConversationSync, T as useAsyncConfirmDialog, A as useAttachmentUpload, J as useChatSettingsFormConfig, G as useConversationHandlers, E as useConversationLookupMaps, O as useConversationPanelItems, q as useConversationStream, k as useImportFilePicker, Y as useToolsMenu, N as useTranscribeAudio };
+import { DEFAULT_GENERATION_CONFLICT_MESSAGE as a, DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE as o, GenerationConflictError as s, GenerationPersistenceError as c, StreamUpstreamError as l, createChatStreamApi as u } from "./conversation/create-chat-stream-api.js";
+import { shouldWatchForDisplayNameUpdate as d } from "./conversation/display-name-watch.js";
+import { formatAppVersion as f, sanitizeFooterHtml as p } from "./conversation/footer-message.js";
+import { getModelIdFromConversationId as m } from "./conversation/get-model-id-from-conversation-id.js";
+import { getTimeOfDayGreeting as h } from "./conversation/greeting.js";
+import { createDeploymentChangedMessage as g } from "./conversation/message-factory.js";
+import { getLastDeploymentId as _, getLastUserMessageToolConfiguration as v, isMessageStreaming as y, messageHasStages as b, normalizeResponseFormat as x } from "./conversation/message-utils.js";
+import { getQuickAppConversationStarters as S } from "./conversation/quick-app-conversation-starters.js";
+import { mapStages as C, toStage as w } from "./conversation/stage.js";
+import { getStarterPopulateText as T, getStartersFromSchema as E } from "./conversation/starter-option.js";
+import { deriveConversationRowActionState as D } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
+import { useActiveConversationSync as O } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
+import { useAsyncConfirmDialog as k } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
+import { useConversationLookupMaps as A } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
+import { getConversationSource as j, useConversationPanelItems as M } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
+import { useImportFilePicker as N } from "./conversation/useImportFilePicker/useImportFilePicker.js";
+import { useAttachmentUpload as P } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
+import { AudioTranscriptionError as F, AudioTranscriptionErrorReason as I } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
+import { useTranscribeAudio as L } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
+import { attachmentToDto as R, attachmentsToDtos as z } from "./conversation/useConversationHandlers/attachment-to-dto.js";
+import { createMessagePair as B } from "./conversation/useConversationHandlers/message-factory.js";
+import { hasActiveToolConfig as V, isAnswerIncomplete as H, isMessageChanged as U, shouldRerunGenerationOnEdit as W } from "./conversation/useConversationHandlers/message-utils.js";
+import { getStarterConversationText as G, getStarterDisplayText as K, getStarterSubmitText as q } from "./conversation/useConversationHandlers/starter-option.js";
+import { getConversationPath as J } from "./conversation/useConversationStream/conversation-path.js";
+import { useConversationHandlers as Y } from "./conversation/useConversationHandlers/useConversationHandlers.js";
+import { applyChunkToMessages as X, mergeStages as Z } from "./conversation/useConversationStream/apply-chunk.js";
+import { isAwaitingGenerationResume as Q } from "./conversation/useConversationStream/generation-resume.js";
+import { useConversationStream as $ } from "./conversation/useConversationStream/useConversationStream.js";
+import { useChatSettingsFormConfig as ee } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
+import { useToolsMenu as te } from "./useToolsMenu/useToolsMenu.js";
+export { F as AudioTranscriptionError, I as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE, s as GenerationConflictError, c as GenerationPersistenceError, l as StreamUpstreamError, X as applyChunkToMessages, R as attachmentToDto, z as attachmentsToDtos, e as buildAnnouncementSignature, u as createChatStreamApi, g as createDeploymentChangedMessage, B as createMessagePair, D as deriveConversationRowActionState, f as formatAppVersion, J as getConversationPath, j as getConversationSource, _ as getLastDeploymentId, v as getLastUserMessageToolConfiguration, m as getModelIdFromConversationId, S as getQuickAppConversationStarters, G as getStarterConversationText, K as getStarterDisplayText, T as getStarterPopulateText, q as getStarterSubmitText, E as getStartersFromSchema, h as getTimeOfDayGreeting, V as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, H as isAnswerIncomplete, Q as isAwaitingGenerationResume, U as isMessageChanged, y as isMessageStreaming, C as mapStages, Z as mergeStages, b as messageHasStages, x as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, p as sanitizeFooterHtml, W as shouldRerunGenerationOnEdit, d as shouldWatchForDisplayNameUpdate, w as toStage, O as useActiveConversationSync, k as useAsyncConfirmDialog, P as useAttachmentUpload, ee as useChatSettingsFormConfig, Y as useConversationHandlers, A as useConversationLookupMaps, M as useConversationPanelItems, $ as useConversationStream, N as useImportFilePicker, te as useToolsMenu, L as useTranscribeAudio };