@epam/ai-dial-chat-hooks 1.1.6 → 1.1.8

package/conversation.d.ts

@@ -327,6 +327,12 @@ export declare interface CreateChatStreamApiDeps {
     getTimezone?: () => string | undefined;
     /** `fetch` implementation to issue requests through. Defaults to the global `fetch`. */
     fetchImpl?: typeof fetch;
+    /**
+     * How long an open completion stream may go without receiving a byte
+     * (keepalive comments included) before it is reported as a
+     * {@link StreamInterruptedError}. Defaults to {@link DEFAULT_STREAM_IDLE_TIMEOUT_MS}.
+     */
+    idleTimeoutMs?: number;
 }
 
 /**
@@ -341,6 +347,11 @@ 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.";
+
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 45000;
+
 /**
  * Derives the row-action visibility state for a single conversation item.
  *
@@ -375,6 +386,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
@@ -387,6 +404,21 @@ export declare const getConversationPath: (conversationId: string) => string;
  */
 export declare const getConversationSource: (item: Pick<ConversationListItemDto, "sharedWithMe" | "publishedWithMe">) => FilterTab;
 
+/**
+ * Returns the tool values the conversation's last message sets through its
+ * `form_schema`, restricted to `toolIds`, plus a key identifying that exact
+ * application. `undefined` when the last message is not an assistant message
+ * or sets no known tool.
+ *
+ * Streamed chunks and reloads re-create an identical `form_schema`; comparing
+ * keys rather than object identity applies an app's value once and leaves a
+ * later user toggle alone until the app sends a different value.
+ */
+export declare const getFormSchemaToolSyncKey: (conversationId: string, messages: Message[], toolIds: readonly string[]) => {
+    key: string;
+    values: Record<string, boolean>;
+} | undefined;
+
 /**
  * Returns the deployment the conversation was last running on: scanning
  * backwards, the `new_deployment_id` of a `model_changed` status message or
@@ -410,6 +442,15 @@ export declare const getLastDeploymentId: (messages: Message[]) => string | null
  */
 export declare const getLastUserMessageToolConfiguration: (messages: Message[]) => Record<string, unknown> | undefined;
 
+/**
+ * Returns the tool configuration a (re-)loaded conversation should show: the
+ * last user message's `configuration_value`, overlaid in order by the
+ * `form_schema` values of the assistant messages after it. An app that turned
+ * a toggle off in its final response must not see it re-armed on reload just
+ * because the user message that started the run had it on.
+ */
+export declare const getLatestToolConfiguration: (messages: Message[]) => Record<string, unknown> | undefined;
+
 /**
  * Extracts the deployment/model ID from a DIAL Core conversation ID.
  *
@@ -493,6 +534,15 @@ export declare const getStarterSubmitText: (starter: StarterOption, description?
  */
 export declare const getTimeOfDayGreeting: (hour: number, translations: GreetingTranslations, firstName?: string) => string;
 
+/**
+ * Returns the boolean values an assistant message's `form_schema` sets, keyed
+ * by property name, or `undefined` when no property resolves to a boolean.
+ * Lets a DIAL app switch a tools-menu toggle (e.g. `deep_research`) per
+ * message — on while a run is in progress, off once its result is delivered.
+ * Not filtered by tool id: `restoreToolConfiguration` ignores unknown ids.
+ */
+export declare const getToolConfigurationFromFormSchema: (formSchema: DeploymentConfigurationSchema | undefined) => Record<string, boolean> | undefined;
+
 /** Pre-translated greeting phrase strings for each time-of-day period. */
 export declare interface GreetingTranslations {
     morningWithName: string;
@@ -529,8 +579,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;
 
@@ -661,6 +711,29 @@ export declare interface StreamCompletionOptions {
     signal: AbortSignal;
 }
 
+/**
+ * Reported through `onError` when the network connection carrying a
+ * completion stream is lost (a rejected `fetch`, or a read that fails after a
+ * 2xx response) or goes silent past the idle timeout — what a laptop sleep or
+ * a phone lock mid-generation produces. The backend-owned generation may
+ * still be running, so the caller can recover it rather than treat the
+ * response as failed. `cause` holds the original error, when there is one.
+ */
+export declare class StreamInterruptedError extends Error {
+    constructor(cause?: unknown);
+}
+
+/**
+ * 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);
+}
+
 /** Request shape the host's selected-deployment recognition call accepts. */
 export declare interface TranscribeWithDeploymentParams {
     audioUrl: string;
@@ -934,7 +1007,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 {
@@ -952,6 +1025,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,30 +1,30 @@
 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 { getQuickAppConversationStarters as y } from "./conversation/quick-app-conversation-starters.js";
-import { getStarterPopulateText as b, getStartersFromSchema as x } from "./conversation/starter-option.js";
-import { deriveConversationRowActionState as S } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
-import { useActiveConversationSync as C } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
-import { useAsyncConfirmDialog as w } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
-import { useConversationLookupMaps as T } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
-import { getConversationSource as E, useConversationPanelItems as D } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
-import { useImportFilePicker as O } from "./conversation/useImportFilePicker/useImportFilePicker.js";
-import { useAttachmentUpload as k } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
-import { AudioTranscriptionError as A, AudioTranscriptionErrorReason as j } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
-import { useTranscribeAudio as M } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
-import { attachmentToDto as N, attachmentsToDtos as P } from "./conversation/useConversationHandlers/attachment-to-dto.js";
-import { createMessagePair as F } from "./conversation/useConversationHandlers/message-factory.js";
-import { hasActiveToolConfig as I, isAnswerIncomplete as L, isMessageChanged as R, shouldRerunGenerationOnEdit as z } from "./conversation/useConversationHandlers/message-utils.js";
-import { getStarterConversationText as B, getStarterDisplayText as V, getStarterSubmitText as H } from "./conversation/useConversationHandlers/starter-option.js";
-import { getConversationPath as U } from "./conversation/useConversationStream/conversation-path.js";
-import { useConversationHandlers as W } from "./conversation/useConversationHandlers/useConversationHandlers.js";
-import { isAwaitingGenerationResume as G } from "./conversation/useConversationStream/generation-resume.js";
-import { useConversationStream as K } from "./conversation/useConversationStream/useConversationStream.js";
-import { useChatSettingsFormConfig as q } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
-import { useToolsMenu as J } from "./useToolsMenu/useToolsMenu.js";
-export { A as AudioTranscriptionError, j as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, N as attachmentToDto, P as attachmentsToDtos, e as buildAnnouncementSignature, s as createChatStreamApi, p as createDeploymentChangedMessage, F as createMessagePair, S as deriveConversationRowActionState, l as formatAppVersion, U as getConversationPath, E as getConversationSource, m as getLastDeploymentId, h as getLastUserMessageToolConfiguration, d as getModelIdFromConversationId, y as getQuickAppConversationStarters, B as getStarterConversationText, V as getStarterDisplayText, b as getStarterPopulateText, H as getStarterSubmitText, x as getStartersFromSchema, f as getTimeOfDayGreeting, I as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, L as isAnswerIncomplete, G as isAwaitingGenerationResume, R as isMessageChanged, g as isMessageStreaming, _ as messageHasStages, v as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, u as sanitizeFooterHtml, z as shouldRerunGenerationOnEdit, c as shouldWatchForDisplayNameUpdate, C as useActiveConversationSync, w as useAsyncConfirmDialog, k as useAttachmentUpload, q as useChatSettingsFormConfig, W as useConversationHandlers, T as useConversationLookupMaps, D as useConversationPanelItems, K as useConversationStream, O as useImportFilePicker, J as useToolsMenu, M as useTranscribeAudio };
+import { DEFAULT_GENERATION_CONFLICT_MESSAGE as a, DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE as o, DEFAULT_STREAM_IDLE_TIMEOUT_MS as s, GenerationConflictError as c, GenerationPersistenceError as l, StreamInterruptedError as u, StreamUpstreamError as d, createChatStreamApi as f } from "./conversation/create-chat-stream-api.js";
+import { shouldWatchForDisplayNameUpdate as p } from "./conversation/display-name-watch.js";
+import { formatAppVersion as m, sanitizeFooterHtml as h } from "./conversation/footer-message.js";
+import { getModelIdFromConversationId as g } from "./conversation/get-model-id-from-conversation-id.js";
+import { getTimeOfDayGreeting as _ } from "./conversation/greeting.js";
+import { createDeploymentChangedMessage as v } from "./conversation/message-factory.js";
+import { getFormSchemaToolSyncKey as y, getLastDeploymentId as b, getLastUserMessageToolConfiguration as x, getLatestToolConfiguration as S, getToolConfigurationFromFormSchema as C, isMessageStreaming as w, messageHasStages as T, normalizeResponseFormat as E } from "./conversation/message-utils.js";
+import { getQuickAppConversationStarters as D } from "./conversation/quick-app-conversation-starters.js";
+import { getStarterPopulateText as O, getStartersFromSchema as k } from "./conversation/starter-option.js";
+import { deriveConversationRowActionState as A } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
+import { useActiveConversationSync as j } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
+import { useAsyncConfirmDialog as M } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
+import { useConversationLookupMaps as N } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
+import { getConversationSource as P, useConversationPanelItems as F } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
+import { useImportFilePicker as I } from "./conversation/useImportFilePicker/useImportFilePicker.js";
+import { useAttachmentUpload as L } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
+import { AudioTranscriptionError as R, AudioTranscriptionErrorReason as z } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
+import { useTranscribeAudio as B } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
+import { attachmentToDto as V, attachmentsToDtos as H } from "./conversation/useConversationHandlers/attachment-to-dto.js";
+import { createMessagePair as U } from "./conversation/useConversationHandlers/message-factory.js";
+import { hasActiveToolConfig as W, isAnswerIncomplete as G, isMessageChanged as K, shouldRerunGenerationOnEdit as q } from "./conversation/useConversationHandlers/message-utils.js";
+import { getStarterConversationText as J, getStarterDisplayText as Y, getStarterSubmitText as X } from "./conversation/useConversationHandlers/starter-option.js";
+import { getConversationPath as Z } from "./conversation/useConversationStream/conversation-path.js";
+import { useConversationHandlers as Q } from "./conversation/useConversationHandlers/useConversationHandlers.js";
+import { isAwaitingGenerationResume as $ } from "./conversation/useConversationStream/generation-resume.js";
+import { useConversationStream as ee } from "./conversation/useConversationStream/useConversationStream.js";
+import { useChatSettingsFormConfig as te } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
+import { useToolsMenu as ne } from "./useToolsMenu/useToolsMenu.js";
+export { R as AudioTranscriptionError, z as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE, s as DEFAULT_STREAM_IDLE_TIMEOUT_MS, c as GenerationConflictError, l as GenerationPersistenceError, u as StreamInterruptedError, d as StreamUpstreamError, V as attachmentToDto, H as attachmentsToDtos, e as buildAnnouncementSignature, f as createChatStreamApi, v as createDeploymentChangedMessage, U as createMessagePair, A as deriveConversationRowActionState, m as formatAppVersion, Z as getConversationPath, P as getConversationSource, y as getFormSchemaToolSyncKey, b as getLastDeploymentId, x as getLastUserMessageToolConfiguration, S as getLatestToolConfiguration, g as getModelIdFromConversationId, D as getQuickAppConversationStarters, J as getStarterConversationText, Y as getStarterDisplayText, O as getStarterPopulateText, X as getStarterSubmitText, k as getStartersFromSchema, _ as getTimeOfDayGreeting, C as getToolConfigurationFromFormSchema, W as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, G as isAnswerIncomplete, $ as isAwaitingGenerationResume, K as isMessageChanged, w as isMessageStreaming, T as messageHasStages, E as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, h as sanitizeFooterHtml, q as shouldRerunGenerationOnEdit, p as shouldWatchForDisplayNameUpdate, j as useActiveConversationSync, M as useAsyncConfirmDialog, L as useAttachmentUpload, te as useChatSettingsFormConfig, Q as useConversationHandlers, N as useConversationLookupMaps, F as useConversationPanelItems, ee as useConversationStream, I as useImportFilePicker, ne as useToolsMenu, B as useTranscribeAudio };