@epam/ai-dial-chat-hooks 1.2.0-dev.14 → 1.2.0-dev.142

package/conversation/useConversationStream/useConversationStream.js

@@ -1,152 +1,195 @@
 import { safeDecodeURI as e } from "../../shared/string-utils.js";
-import { DEFAULT_GENERATION_CONFLICT_MESSAGE as t, GenerationConflictError as n } from "../create-chat-stream-api.js";
-import { getConversationPath as r } from "./conversation-path.js";
-import { applyChunkToMessages as i } from "./apply-chunk.js";
-import { restoreBufferedMessage as a } from "./buffered-generation.js";
-import { createResumeIfAwaitingGeneration as o } from "./generation-resume.js";
-import { generateUUID as s } from "@epam/ai-dial-chat-shared";
-import { useCallback as c, useEffect as l, useMemo as u, useRef as d, useState as f } from "react";
-import { SendCompletionDtoModeEnum as p } from "@epam/ai-dial-chat-api-client";
+import { DEFAULT_GENERATION_CONFLICT_MESSAGE as t, DEFAULT_GENERATION_PERSISTENCE_ERROR_MESSAGE as n, GenerationConflictError as r, GenerationPersistenceError as i, StreamUpstreamError as a } from "../create-chat-stream-api.js";
+import { getConversationPath as o } from "./conversation-path.js";
+import { applyChunkToMessages as s } from "./apply-chunk.js";
+import { restoreBufferedMessage as c } from "./buffered-generation.js";
+import { createResumeIfAwaitingGeneration as l, hasGeneratedPayload as u, isAwaitingGenerationResume as d } from "./generation-resume.js";
+import { generateUUID as f } from "@epam/ai-dial-chat-shared";
+import { useCallback as p, useEffect as m, useMemo as h, useRef as g, useState as _ } from "react";
+import { SendCompletionDtoModeEnum as v } from "@epam/ai-dial-chat-api-client";
 //#region src/conversation/useConversationStream/useConversationStream.ts
-var m = 2e4, h = ({ conversationId: h, state: { setConversation: g, conversationRef: _ }, transport: v, generation: { startGeneration: y, completeGeneration: b }, channel: x, overlay: S, onStopError: C, generationConflictMessage: w = t }) => {
-	let [T, E] = f(() => /* @__PURE__ */ new Set()), [D, O] = f(null), k = d(null), A = d(null), j = d(/* @__PURE__ */ new Set()), M = d(/* @__PURE__ */ new Map()), N = d(/* @__PURE__ */ new Set()), P = d(/* @__PURE__ */ new Map()), F = d(h);
-	l(() => {
-		F.current = h;
-	}, [h]);
-	let I = c((e) => r(F.current ?? "") === e, []), L = c((e) => {
-		E((t) => {
+var y = 2e4, b = (e, t, n) => e instanceof i ? n : e instanceof r ? t : e instanceof a ? e.message : "", x = ({ conversationId: r, state: { setConversation: a, conversationRef: x }, transport: S, generation: { startGeneration: C, completeGeneration: w }, channel: T, overlay: E, onStopError: D, generationConflictMessage: O = t, generationPersistenceErrorMessage: k = n, onStreamError: A }) => {
+	let j = g(A);
+	m(() => {
+		j.current = A;
+	}, [A]);
+	let [M, N] = _(() => /* @__PURE__ */ new Set()), [P, F] = _(null), I = g(null), L = g(null), R = g(/* @__PURE__ */ new Set()), z = g(/* @__PURE__ */ new Map()), B = g(/* @__PURE__ */ new Set()), V = g(/* @__PURE__ */ new Map()), H = g(r);
+	m(() => {
+		H.current = r;
+	}, [r]);
+	let U = p((e) => o(H.current ?? "") === e, []), W = p((e) => {
+		N((t) => {
 			if (t.has(e)) return t;
 			let n = new Set(t);
 			return n.add(e), n;
 		});
-	}, []), R = c((e) => {
-		E((t) => {
+	}, []), G = p((e) => {
+		N((t) => {
 			if (!t.has(e)) return t;
 			let n = new Set(t);
 			return n.delete(e), n;
 		});
-	}, []), z = c((t, o, c, l, u, d, f = p.Append) => {
-		let h = d ?? s(), C = r(t);
-		k.current = h, A.current = C, P.current.set(C, h), O(C);
-		let T;
-		f === p.Regenerate ? T = c : f === p.Edit && (T = c - 1);
-		let E = () => P.current.get(C) !== h, D = y(C, h), j = _.current?.messages[c];
-		j ? M.current.set(C, {
-			generationId: h,
-			messageIndex: c,
-			message: j
-		}) : M.current.delete(C), L(C), S?.notifyGenerationStart?.(), x?.ensureConnected();
-		let F = {
-			signal: D.signal,
+	}, []), K = p((t, n, r, l, p, m, h = v.Append) => {
+		let g = m ?? f(), _ = o(t);
+		R.current.delete(_), I.current = g, L.current = _, V.current.set(_, g), F(_);
+		let D;
+		h === v.Regenerate ? D = r : h === v.Edit && (D = r - 1);
+		let A = () => V.current.get(_) !== g, M = C(_, g), N = x.current?.messages[r];
+		N ? z.current.set(_, {
+			generationId: g,
+			messageIndex: r,
+			message: N
+		}) : z.current.delete(_), W(_), E?.notifyGenerationStart?.(), T?.ensureConnected();
+		let P = () => {
+			if (A()) return;
+			let e = z.current.get(_);
+			!e || e.generationId !== g || (e.message = {
+				...e.message,
+				streamErrorMessage: k
+			}, j.current?.(new i()), U(_) && a((t) => {
+				if (!t || A() || !U(_)) return t;
+				let n = c(t, e);
+				return x.current = n, n;
+			}));
+		}, H = {
+			signal: M.signal,
 			onChunk: (e) => {
-				if (k.current !== h) return;
-				let t = M.current.get(C);
-				if (t?.generationId === h) {
-					let n = i([t.message], 0, e);
+				if (I.current !== g) return;
+				let t = z.current.get(_);
+				if (t?.generationId === g) {
+					let n = s([t.message], 0, e);
 					n && (t.message = n[0]);
 				}
-				I(C) && g((t) => {
+				U(_) && a((t) => {
 					if (!t) return t;
-					let n = M.current.get(C), r;
-					if (n?.generationId === h) r = a(t, n);
+					let n = z.current.get(_), i;
+					if (n?.generationId === g) i = c(t, n);
 					else {
-						let n = i(t.messages, c, e);
+						let n = s(t.messages, r, e);
 						if (!n) return t;
-						r = {
+						i = {
 							...t,
 							messages: n
 						};
 					}
-					return _.current = r, r;
+					return x.current = i, i;
 				});
 			},
 			onComplete: async () => {
-				if (M.current.get(C)?.generationId === h && M.current.delete(C), E() || R(C), k.current === h && (k.current = null, A.current = null, O(null)), b(C, h), x?.notifyGenerationSettled?.(), N.current.has(h) ? N.current.delete(h) : E() || S?.notifyGenerationEnd?.(), !E() && I(C)) try {
-					let n = await v.getConversation(e(t));
-					if (E() || !I(C)) return;
-					g(n), _.current = n;
-				} catch {}
+				let n = z.current.get(_), r = n?.generationId === g ? n : void 0;
+				if (A() || G(_), I.current === g && (I.current = null, L.current = null, F(null)), w(_, g), T?.notifyGenerationSettled?.(), B.current.has(g) ? B.current.delete(g) : A() || E?.notifyGenerationEnd?.(), !A()) {
+					if (!U(_)) {
+						r && z.current.delete(_);
+						return;
+					}
+					try {
+						let n = await S.getConversation(e(t));
+						if (A()) return;
+						if (!U(_)) {
+							r && z.current.delete(_);
+							return;
+						}
+						if (r && r.messageIndex === n.messages.length - 1 && d(n) && u(r.message)) {
+							P();
+							return;
+						}
+						r && z.current.delete(_), a(n), x.current = n;
+					} catch {
+						A() || P();
+					}
+				}
 			},
 			onError: (e) => {
-				let t = M.current.get(C), r = t?.generationId === h ? t : void 0;
-				if (r && M.current.delete(C), E() || R(C), k.current === h && (k.current = null, A.current = null, O(null)), b(C, h), x?.notifyGenerationSettled?.(), E() || !I(C)) return;
-				let i = e instanceof n ? w : e.message;
-				g((e) => {
-					if (!e) return e;
-					let t = r?.generationId === h ? a(e, r) : e, n = {
+				j.current?.(e);
+				let t = z.current.get(_), n = t?.generationId === g ? t : void 0;
+				if (n && (e instanceof i ? n.message = {
+					...n.message,
+					streamErrorMessage: k
+				} : z.current.delete(_)), A() || G(_), I.current === g && (I.current = null, L.current = null, F(null)), w(_, g), T?.notifyGenerationSettled?.(), A() || !U(_)) return;
+				let o = b(e, O, k);
+				a((e) => {
+					if (!e || A() || !U(_)) return e;
+					let t = n?.generationId === g ? c(e, n) : e, i = {
 						...t,
-						messages: t.messages.map((e, t) => t === c ? {
+						messages: t.messages.map((e, t) => t === r ? {
 							...e,
-							streamErrorMessage: i
+							streamErrorMessage: o
 						} : e)
 					};
-					return _.current = n, n;
+					return x.current = i, i;
 				});
 			}
 		};
 		(async () => {
 			try {
-				let e = x?.channelId ?? await x?.waitForChannel(m) ?? void 0;
-				v.streamCompletion(C, o, l, F, u, h, f, T, e);
+				let e = T?.channelId ?? await T?.waitForChannel(y) ?? void 0, t = B.current.has(g);
+				if (M.signal.aborted || A() || t) {
+					z.current.get(_)?.generationId === g && z.current.delete(_), A() || G(_), I.current === g && (I.current = null, L.current = null, F(null)), w(_, g), T?.notifyGenerationSettled?.(), t ? B.current.delete(g) : A() || E?.notifyGenerationEnd?.();
+					return;
+				}
+				S.streamCompletion(_, n, l, H, p, g, h, D, e);
 			} catch (e) {
-				F.onError(e instanceof Error ? e : Error(String(e)));
+				H.onError(e instanceof Error ? e : Error(String(e)));
 			}
 		})();
 	}, [
-		y,
-		b,
-		L,
-		R,
-		I,
-		x?.channelId,
-		x?.ensureConnected,
-		x?.waitForChannel,
-		x?.notifyGenerationSettled,
+		C,
+		w,
+		W,
+		G,
+		U,
+		T?.channelId,
+		T?.ensureConnected,
+		T?.waitForChannel,
+		T?.notifyGenerationSettled,
+		E,
 		S,
-		v,
-		w
-	]), B = c((e, t) => {
-		let n = r(e), i = M.current.get(n);
-		return i ? a(t, i) : t;
-	}, []), V = c(() => {
-		let e = k.current;
-		if (!e || !h) return;
-		let t = r(h);
-		A.current === t && (N.current.add(e), S?.notifyStopGenerating?.(), v.stopCompletion({
+		O,
+		k
+	]), q = p((e, t) => {
+		let n = o(e), r = z.current.get(n);
+		return r ? c(t, r) : t;
+	}, []), J = p(() => {
+		let e = I.current;
+		if (!e || !r) return;
+		let t = o(r);
+		L.current === t && (B.current.add(e), E?.notifyStopGenerating?.(), S.stopCompletion({
 			generationId: e,
 			path: t
 		}).catch((e) => {
 			let t = e instanceof Error ? e : Error(String(e));
-			C?.(t);
+			D?.(t);
 		}));
 	}, [
-		h,
-		C,
-		S,
-		v
-	]), H = u(() => o({
-		transport: v,
-		setConversation: g,
-		conversationRef: _,
-		resumingPathsRef: j,
-		bufferedGenerationsRef: M,
-		addStreamingPath: L,
-		removeStreamingPath: R,
-		isPathDisplayed: I
+		r,
+		D,
+		E,
+		S
+	]), Y = h(() => l({
+		transport: S,
+		setConversation: a,
+		conversationRef: x,
+		resumingPathsRef: R,
+		bufferedGenerationsRef: z,
+		addStreamingPath: W,
+		removeStreamingPath: G,
+		isPathDisplayed: U,
+		generationPersistenceErrorMessage: k
 	}), [
-		L,
-		R,
-		I,
-		v
-	]), U = h != null && T.has(r(h)), W = h == null ? null : r(h);
+		W,
+		G,
+		U,
+		S,
+		k
+	]), X = r != null && M.has(o(r)), Z = r == null ? null : o(r);
 	return {
-		startStream: z,
-		handleStop: V,
-		resumeIfAwaitingGeneration: H,
-		restoreBufferedGeneration: B,
-		isStreaming: U,
-		canStopStreaming: W != null && D === W
+		startStream: K,
+		handleStop: J,
+		resumeIfAwaitingGeneration: Y,
+		restoreBufferedGeneration: q,
+		isStreaming: X,
+		canStopStreaming: Z != null && P === Z
 	};
 };
 //#endregion
-export { h as useConversationStream };
+export { x as useConversationStream };

package/conversation-overlay.d.ts

@@ -0,0 +1,7 @@
+import { Message } from '@epam/ai-dial-chat-shared';
+import { OverlayChatMessage } from '@epam/ai-dial-chat-overlay';
+
+/** Maps chat messages to the DIAL Chat Overlay protocol's message shape. */
+export declare const toOverlayMessages: (messages: Message[]) => OverlayChatMessage[];
+
+export { }

package/conversation-overlay.js

@@ -0,0 +1,2 @@
+import { toOverlayMessages as e } from "./conversation/overlay-messages.js";
+export { e as toOverlayMessages };

package/conversation-sources/useConversationSources/useConversationSources.js

@@ -1,35 +1,42 @@
 import { MessageRole as e, messageAttachmentToDisplayAttachment as t } from "@epam/ai-dial-chat-shared";
-import { isReferenceOnlyAttachment as n, resolveMessageAnnotations as r } from "@epam/ai-dial-quotations";
-import { useMemo as i } from "react";
+import { getAnnotationPdfPage as n, isReferenceOnlyAttachment as r, parsePdfPageReference as i, resolveMessageAnnotations as a } from "@epam/ai-dial-quotations";
+import { useMemo as o } from "react";
 //#region src/conversation-sources/useConversationSources/useConversationSources.ts
-var a = {}, o = (o, s = a) => i(() => {
-	let i = [], a = [], c = [], l = /* @__PURE__ */ new Set(), u = /* @__PURE__ */ new Set(), d = /* @__PURE__ */ new Set();
-	for (let f of o) {
-		let o = f.custom_content?.attachments;
-		if (f.role === e.User) for (let e of o ?? []) {
-			let n = t(e, s);
-			u.has(n.id) || (u.add(n.id), i.push(n));
+var s = {}, c = (e, t) => {
+	let r = n(e);
+	if (r == null) return t;
+	let a = i(t);
+	return a == null || a.page != null ? t : `${t}#page=${r}`;
+}, l = (n, i = s) => o(() => {
+	let o = [], s = [], l = [], u = /* @__PURE__ */ new Set(), d = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Set();
+	for (let p of n) {
+		let n = p.custom_content?.attachments;
+		if (p.role === e.User) for (let e of n ?? []) {
+			let n = t(e, i);
+			d.has(n.id) || (d.add(n.id), o.push(n));
 		}
-		else if (f.role === e.Assistant) {
-			let e = o?.filter((e) => !n(e));
+		else if (p.role === e.Assistant) {
+			let e = n?.filter((e) => !r(e));
 			for (let n of e ?? []) {
-				let e = t(n, s);
-				d.has(e.id) || (d.add(e.id), a.push(e));
+				let e = t(n, i);
+				f.has(e.id) || (f.add(e.id), s.push(e));
 			}
-			for (let e of o ?? []) {
-				if (!n(e)) continue;
+			for (let e of n ?? []) {
+				if (!r(e)) continue;
 				let t = e.reference_url;
-				l.has(t) || (l.add(t), c.push({
+				u.has(t) || (u.add(t), l.push({
 					url: t,
 					title: e.title ?? t,
 					contentType: e.reference_type ?? e.type ?? "",
 					quote: e.data
 				}));
 			}
-			for (let e of r(f)) {
+			for (let e of a(p)) {
 				let t = e?.body?.source?.attachment, n = t?.url;
-				!n || l.has(n) || (l.add(n), c.push({
-					url: n,
+				if (!n) continue;
+				let r = c(e, n);
+				u.has(r) || (u.add(r), l.push({
+					url: r,
 					title: t?.title ?? n.split("/").pop() ?? n,
 					contentType: t?.type ?? "",
 					quote: e.body?.quote
@@ -38,10 +45,10 @@ var a = {}, o = (o, s = a) => i(() => {
 		}
 	}
 	return {
-		uploaded: i,
-		generated: a,
-		sources: c
+		uploaded: o,
+		generated: s,
+		sources: l
 	};
-}, [o, s]);
+}, [n, i]);
 //#endregion
-export { o as useConversationSources };
+export { l as useConversationSources };

package/conversation-sources.d.ts

@@ -18,7 +18,7 @@ export declare interface UseConversationSourcesResult {
     uploaded: DisplayAttachment[];
     /** Deduplicated attachments the assistant generated across the conversation. */
     generated: DisplayAttachment[];
-    /** Quotation sources referenced by assistant messages, deduplicated by URL. */
+    /** Quotation sources referenced by assistant messages, deduplicated by URL; PDF sources are qualified with `#page=N`. */
     sources: QuotationSource[];
 }
 

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. */
@@ -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}. */