@epam/ai-dial-chat-hooks 1.1.0-dev.383 → 1.1.0-dev.390

package/conversation.d.ts

@@ -0,0 +1,907 @@
+import { Attachment } from '@epam/ai-dial-chat-shared';
+import { AttachmentDto } from '@epam/ai-dial-chat-api-client';
+import { ChangeEvent } from 'react';
+import { Conversation } from '@epam/ai-dial-chat-shared';
+import { ConversationListItemDto } from '@epam/ai-dial-chat-api-client';
+import { ConversationsApi } from '@epam/ai-dial-chat-api-client';
+import { DeploymentConfigurationSchema } from '@epam/ai-dial-chat-shared';
+import { DeploymentFeatures } from '@epam/ai-dial-chat-shared';
+import { DeploymentItemDto } from '@epam/ai-dial-chat-api-client';
+import { Dispatch } from 'react';
+import { DisplayAttachment } from '@epam/ai-dial-chat-shared';
+import { FilesApi } from '@epam/ai-dial-chat-api-client';
+import { FilterTab } from '@epam/ai-dial-chat-shared';
+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';
+import { RefObject } from 'react';
+import { ResponseFormat } from '@epam/ai-dial-chat-shared';
+import { SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
+import { SetStateAction } from 'react';
+import { StarterOption } from '@epam/ai-dial-chat-shared';
+import { StatusMessage } from '@epam/ai-dial-chat-shared';
+import { StreamChunk } from '@epam/ai-dial-chat-shared';
+import { ToolMenuItem } from '@epam/ai-dial-chat-shared';
+
+/** Structured announcement banner content. */
+export declare interface AnnouncementContent {
+    title: string | null;
+    description: string | null;
+    html: string | null;
+}
+
+/** State and controls returned by `useAsyncConfirmDialog`. */
+export declare interface AsyncConfirmDialogControls<T> {
+    /**
+     * The value currently awaiting confirmation, or `null` when no dialog is
+     * open.
+     */
+    pending: T | null;
+    /** `true` when `pending` is not `null`. */
+    isPending: boolean;
+    /** `true` while the async operation started by `confirm` is in-flight. */
+    isRunning: boolean;
+    /** Error message set when the last `confirm` run threw, or `null` otherwise. */
+    error: string | null;
+    /**
+     * Opens the dialog by setting `pending` to `value` and clearing any prior
+     * error.
+     *
+     * Pass `returnFocusTo` when the control that opened the dialog will not
+     * survive it — a row menu item, for instance, unmounts with its menu, so
+     * restoring focus to it is impossible and the caller should name a stable
+     * element such as the menu's own trigger. When omitted, whatever held focus
+     * at the moment of the call is used.
+     */
+    open: (value: T, returnFocusTo?: HTMLElement | null) => void;
+    /** Closes the dialog by resetting `pending`, `error`, and `isRunning` to their initial values. */
+    close: () => void;
+    /**
+     * Runs `run(pending)` while enforcing a re-entry guard.
+     *
+     * - No-op when `isRunning` is already `true` or `pending` is `null`.
+     * - On success: calls `close()` to reset all state.
+     * - On failure: sets `error` to `onError(caughtError)` and leaves `pending`
+     *   set so the caller may retry.
+     */
+    confirm: (run: (value: T) => Promise<void>, onError: (error: unknown) => string) => Promise<void>;
+}
+
+/** Maps a list of already-uploaded attachments to DTOs, or `undefined` when the list is empty. */
+export declare const attachmentsToDtos: (attachments: Attachment[]) => AttachmentDto[] | undefined;
+
+/** Maps an already-uploaded attachment to its DTO shape. Throws if the attachment has no `url` yet. */
+export declare const attachmentToDto: (attachment: Attachment) => AttachmentDto;
+
+/**
+ * Builds the value persisted under `StorageKey.TextOfClosedAnnouncement` when
+ * the user dismisses the banner. Dismissal is content-keyed: the banner stays
+ * hidden only while the current announcement produces the same signature, so
+ * editing any part of it brings the banner back with no version counter.
+ *
+ * A legacy-only announcement returns the raw HTML string — byte-identical to
+ * what shipped before the structured fields existed — so dismissals recorded
+ * by older builds keep working without a storage migration.
+ */
+export declare const buildAnnouncementSignature: (content: AnnouncementContent) => string;
+
+/**
+ * Translatable strings the chat-settings form surfaces. Every field defaults
+ * to an English fallback inside the hook; pass translated values from the
+ * consuming app (e.g. via a `useTranslation`-backed labels hook).
+ */
+export declare interface ChatSettingsFormLabels {
+    /** Dropdown item label and modal title. */
+    settings: string;
+    /** Toast/message text announced after a successful save. */
+    savedNotification: string;
+    /** Label for the response-format field. */
+    responseFormatLabel: string;
+    /** Helper text shown below the response-format field. */
+    responseFormatHint: string;
+    /** Label for the Markdown radio option. */
+    responseFormatMarkdown: string;
+    /** Label for the plain-text radio option. */
+    responseFormatPlainText: string;
+    /** Label for the system-prompt field. */
+    systemPromptLabel: string;
+    /** Tooltip for the system-prompt field. */
+    systemPromptTooltip: string;
+    /** Label for the temperature field. */
+    temperatureLabel: string;
+    /** Label for the precise end of the temperature slider. */
+    temperaturePrecise: string;
+    /** Label for the neutral midpoint of the temperature slider. */
+    temperatureNeutral: string;
+    /** Label for the creative end of the temperature slider. */
+    temperatureCreative: string;
+    /** Hint text shown below the temperature field. */
+    temperatureHint: string;
+    /** Save button label. */
+    saveLabel: string;
+    /** Tooltip shown on the disabled Save button. */
+    saveDisabledTooltip: string;
+}
+
+/** Values emitted by the chat-settings modal when the user clicks Save. */
+export declare interface ChatSettingsValues {
+    /** Updated response format, present when the response-format field was shown. */
+    responseFormat?: ResponseFormat;
+    /** Updated system prompt, present when the system-prompt field was shown. */
+    systemPrompt?: string;
+    /** Updated temperature, present when the temperature field was shown. */
+    temperature?: number;
+}
+
+/** DIAL Core completion streaming transport produced by {@link createChatStreamApi}. */
+export declare interface ChatStreamApi {
+    streamCompletion: (path: string, message: string | undefined, model: string, options: ChatStreamCompletionOptions, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum, messageIndex?: number, clientChannelId?: string) => void;
+    stopCompletion: (dto: {
+        generationId: string;
+        path: string;
+    }) => Promise<void>;
+}
+
+/** Callbacks {@link streamCompletion} reports streamed completion events through. */
+export declare interface ChatStreamCompletionOptions {
+    onChunk: (chunk: StreamChunk) => void;
+    onComplete: () => void;
+    onError: (error: Error) => void;
+    signal?: AbortSignal;
+}
+
+/** Host-owned generation lifecycle, backing cross-navigation `AbortController` ownership. */
+export declare interface ConversationGenerationLifecycle {
+    /** Starts (or replaces) tracking for a generation on `path`, returning its `AbortController`. */
+    startGeneration: (path: string, generationId: string) => AbortController;
+    /** Marks the generation identified by `path`/`generationId` complete, if it is still the active one. */
+    completeGeneration: (path: string, generationId: string) => void;
+}
+
+/** Stable reverse-lookup maps returned by `useConversationLookupMaps`. */
+export declare interface ConversationLookupMaps {
+    /** Returns the raw context id for a panel-space conversation id, or `undefined` when not found. */
+    toContextId: (panelId: string) => string | undefined;
+    /** Returns the raw `ConversationListItemDto` for a panel-space conversation id, or `undefined` when not found. */
+    getRawItem: (panelId: string) => ConversationListItemDto | undefined;
+}
+
+declare interface ConversationModeParams {
+    mode: 'conversation';
+    conversation: Conversation;
+    onConversationChange: (conversation: Conversation) => void;
+    deploymentFeatures?: DeploymentFeatures;
+    /** True when the conversation's deployment is a Quick App. Its orchestrator sets its own fixed temperature, so the temperature field is forced off regardless of `deploymentFeatures`. */
+    isQuickApp?: boolean;
+}
+
+/** Distilled row-action state for a single conversation item. */
+export declare interface ConversationRowActionState {
+    /** `true` when the item is read-only (shared-with-me, published-with-me, or explicitly readonly). */
+    isReadonly: boolean;
+    /**
+     * Deduplicated list of folder paths (as joined slash-delimited strings)
+     * to which this conversation has been published. Empty when the conversation
+     * is unowned, readonly, or publish history is unavailable.
+     */
+    publishedFolders: string[];
+    /**
+     * `true` when the revoke-access action should be shown: either the
+     * recipient count is unknown (lookup pending/failed) or at least one
+     * recipient exists.
+     */
+    isRevokeVisible: boolean;
+    /** `true` when publish is applicable (no published folders yet). */
+    isPublishApplicable: boolean;
+    /** `true` when unpublish is applicable (at least one published folder exists). */
+    isUnpublishApplicable: boolean;
+}
+
+/** Shared mutable channel through which the displayed conversation's state is read/written. */
+export declare interface ConversationStateAccessor {
+    setConversation: Dispatch<SetStateAction<Conversation | null>>;
+    conversationRef: MutableRefObject<Conversation | null>;
+}
+
+/** Optional host-owned client-channel connection, used to nudge tool-signin delivery. */
+export declare interface ConversationStreamChannel {
+    channelId: string | null;
+    ensureConnected: () => void;
+    /** Resolves with a channel id, waiting for an in-flight subscribe if one isn't established yet, so a completion sent immediately after mount can still carry it. */
+    waitForChannel: (timeoutMs?: number) => Promise<string | null>;
+}
+
+/** Optional host-owned overlay generation-lifecycle notifications. Each method is independently optional. */
+export declare interface ConversationStreamOverlayNotifier {
+    notifyGenerationStart?: () => void;
+    notifyGenerationEnd?: () => void;
+    notifyStopGenerating?: () => void;
+}
+
+/** The exact `startStream` shape `useConversationStream` returns. */
+export declare type ConversationStreamStarter = (conversationPath: string, userContent: string, messageIndex: number, model: string, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum) => void;
+
+/**
+ * Host-owned transport for the DIAL Core completion protocol. Implemented at
+ * the app edge — never hardcodes an `/api` path, CSRF handling, or a
+ * `server-api` import; the library only depends on this interface's shape.
+ */
+export declare interface ConversationStreamTransport {
+    /** Starts a completion; delivers chunks/completion/error through `options`, aborted via `options.signal`. */
+    streamCompletion(path: string, message: string | undefined, model: string, options: StreamCompletionOptions, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum, messageIndex?: number, clientChannelId?: string): void;
+    /** Requests the backend stop an active generation. */
+    stopCompletion(params: {
+        generationId: string;
+        path: string;
+    }): Promise<void>;
+    /** Opens a stream of resource-update events for `path`, until aborted via `signal`. */
+    watchConversation(path: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Attaches to an active generation's live replay: a `snapshot` event
+     * carrying the assistant message as assembled so far, then a `chunk` event
+     * per subsequent delta, then exactly one terminal event (`done`/`error`/
+     * `stopped`), until aborted via `signal`. Rejects when no active
+     * generation exists for `path` — including one that already finished —
+     * so the caller can fall back to `watchConversation`.
+     */
+    attachToGeneration(path: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    /** Reloads the persisted conversation by its full (bucket-qualified) id. */
+    getConversation(conversationId: string, signal?: AbortSignal): Promise<Conversation>;
+}
+
+/**
+ * Builds the streamed-completion transport `apps/chat/src/server-api/chat-stream.api.ts`
+ * exposes today: SSE parsing across partial chunks, CSRF header attachment
+ * and rotation, and an optional timezone header, backed by an injected
+ * `fetch` implementation and base path.
+ */
+export declare const createChatStreamApi: (deps: CreateChatStreamApiDeps) => ChatStreamApi;
+
+/** Host capabilities {@link createChatStreamApi} needs to stream and stop completions. */
+export declare interface CreateChatStreamApiDeps {
+    /** Returns the currently held CSRF token, or `null` when none is set. */
+    getCsrfToken: () => string | null;
+    /** Stores a CSRF token captured from a response header. */
+    setCsrfToken: (token: string | null) => void;
+    /** Base path for the completion/stop endpoints, e.g. `/api/v1/conversations`. */
+    completionsBasePath: string;
+    /** Resolves the caller's current timezone, attached as `X-Timezone` when non-empty. */
+    getTimezone?: () => string | undefined;
+    /** `fetch` implementation to issue requests through. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+
+/**
+ * Creates a status message recording a deployment change in the conversation timeline.
+ * Status messages are never forwarded to DIAL Core.
+ */
+export declare const createDeploymentChangedMessage: (previousDeploymentId: string | null, newDeploymentId: string) => StatusMessage;
+
+/** Builds a user message and its empty assistant placeholder, both timestamped `now`. */
+export declare const createMessagePair: (content: string, customContent?: MessageCustomContent, deploymentId?: string | null) => MessagePair;
+
+/**
+ * Derives the row-action visibility state for a single conversation item.
+ *
+ * Extracted from `getActions` in `ConversationPanelView` to isolate the
+ * readonly / publish / unpublish / revoke decision logic from the
+ * `DropdownItem` construction and `t()` calls that remain in the app.
+ *
+ * @param item - Conversation DTO fields relevant to ownership classification.
+ * @param publishHistory - Resolved publish-history entries, or `undefined`
+ *   when history is unavailable or should be treated as empty (e.g. while
+ *   loading or when the item is readonly).
+ * @param recipients - Current share-recipients count entry for this item.
+ */
+export declare const deriveConversationRowActionState: (item: Pick<ConversationListItemDto, "sharedWithMe" | "publishedWithMe" | "isReadonly">, publishHistory: PublishHistoryEntry[] | undefined, recipients: RecipientsCountEntry) => ConversationRowActionState;
+
+/**
+ * Normalises a version string for display. The server falls back to a bare
+ * `package.json` version (`0.45.0`), while a CI-supplied `CHAT_VERSION` is
+ * often already tagged (`v0.45.0`) — prefixing unconditionally would render
+ * `vv0.45.0`.
+ */
+export declare const formatAppVersion: (version: string) => string;
+
+/**
+ * Strips the leading bucket segment from a conversation id and decodes any
+ * already-percent-encoded remainder back to raw, so callers that re-encode
+ * the result once (e.g. an API client) don't double-encode it on the wire.
+ */
+export declare const getConversationPath: (conversationId: string) => string;
+
+/**
+ * Classifies a conversation's ownership using the shared filter-tab contract.
+ */
+export declare const getConversationSource: (item: Pick<ConversationListItemDto, "sharedWithMe" | "publishedWithMe">) => FilterTab;
+
+/**
+ * Returns the `new_deployment_id` from the last `model_changed` status message
+ * in the list, or `null` if none exists.
+ */
+export declare const getLastDeploymentId: (messages: Message[]) => string | null;
+
+/**
+ * Returns the `configuration_value` stored on the last user message, or
+ * `undefined` if none exists. Used to restore the tools menu toggle state
+ * when a conversation is (re-)loaded, mirroring `getLastDeploymentId`.
+ */
+export declare const getLastUserMessageToolConfiguration: (messages: Message[]) => Record<string, unknown> | undefined;
+
+/**
+ * Extracts the deployment/model ID from a DIAL Core conversation ID.
+ *
+ * The backend builds conversation paths as `{deploymentId}__{title}` then runs
+ * `encodeDialResourcePath` which splits on `/` and encodes each segment. This
+ * means both the deployment ID and the title may introduce extra `/`-separated
+ * URL segments:
+ *
+ *   - Deployment `anthropic/claude-3`, title `My chat`
+ *     → `conversations/bucket/anthropic/claude-3__My%20chat`
+ *
+ *   - Deployment `uuid`, title `calc 6/2/2026` (title contains slashes)
+ *     → `conversations/bucket/uuid__calc%206/2/2026`
+ *
+ * The `__` separator is present in the first filename segment. Versioned
+ * application deployments use `{name}__{version}__{title}`, so the version
+ * suffix still belongs to the deployment ID.
+ *
+ * In regular model conversations, the separator is always present in exactly
+ * one segment — the first one that contains it. Segments before that segment
+ * are deployment ID path prefixes; segments from that point onward are the
+ * title (possibly overflowing into further `/`-separated segments).
+ *
+ * Returns `undefined` when the format is unrecognised.
+ */
+export declare const getModelIdFromConversationId: (id: string) => string | undefined;
+
+/** Parses a Quick App's raw `conversationStarters` schema value into starter options. */
+export declare const getQuickAppConversationStarters: (conversationStarters: unknown) => QuickAppConversationStartersSettings;
+
+/**
+ * Returns the text to start/populate a conversation from a selected starter button.
+ * `description` (the schema property's shared intro/question text) is used only
+ * as a fallback when the starter's own `populateText` is explicitly `null` — it
+ * must never override a starter's own configured prompt.
+ */
+export declare const getStarterConversationText: (starter: StarterOption, description?: string) => string;
+
+/**
+ * Returns the text to populate in the input when a starter button is selected.
+ * Falls back to the button title if `populateText` is empty.
+ */
+export declare const getStarterPopulateText: (starter: StarterOption) => string;
+
+/**
+ * Extracts starter options, the schema property key (`'starter'` or `'button'`),
+ * and the optional description text from a deployment configuration schema.
+ *
+ * - `propertyKey` — `'starter'` or `'button'`; used to build `configuration_value`.
+ * - `description` — human-readable prompt shown above the buttons (only present for `button` properties).
+ *
+ * Returns an empty starters array and `undefined` fields when no matching property is found.
+ */
+export declare const getStartersFromSchema: (schema: DeploymentConfigurationSchema | null | undefined) => {
+    starters: StarterOption[];
+    propertyKey: string | undefined;
+    description: string | undefined;
+};
+
+/**
+ * Returns submitted text for DIAL starter/form buttons.
+ * For submit buttons, `populateText: null` explicitly means "submit no text".
+ */
+export declare const getStarterSubmitText: (starter: StarterOption, description?: string) => string;
+
+/**
+ * Returns a time-of-day greeting string.
+ * Hour ranges: morning 5–11, afternoon 12–16, evening 17–20, night 21–4.
+ * When firstName is provided the with-name variant is returned; otherwise the no-name variant.
+ */
+export declare const getTimeOfDayGreeting: (hour: number, translations: GreetingTranslations, firstName?: string) => string;
+
+/** Pre-translated greeting phrase strings for each time-of-day period. */
+export declare interface GreetingTranslations {
+    morningWithName: string;
+    morningNoName: string;
+    afternoonWithName: string;
+    afternoonNoName: string;
+    eveningWithName: string;
+    eveningNoName: string;
+    nightWithName: string;
+    nightNoName: string;
+}
+
+/** Whether at least one tool toggle in `value` is active. */
+export declare const hasActiveToolConfig: (value: Record<string, boolean> | undefined) => boolean;
+
+/** True when the announcement has any renderable content (structured or legacy HTML). */
+export declare const hasAnnouncementContent: (content: AnnouncementContent) => boolean;
+
+/**
+ * Whether the operator configured the structured banner (title and/or
+ * description) rather than only the legacy HTML message. Drives which of the
+ * two banner layouts renders.
+ */
+export declare const hasStructuredAnnouncement: ({ title, description, }: AnnouncementContent) => boolean;
+
+/**
+ * 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.
+ */
+export declare const isAwaitingGenerationResume: (conversation: Conversation) => boolean;
+
+/**
+ * Returns `true` when the edited text or attachment list differs from the
+ * original message, meaning a regeneration is needed.
+ *
+ * @param originalMessage - The unmodified message stored in the conversation.
+ * @param newText - The text the user submitted from the edit area.
+ * @param keptDisplayAttachments - Attachments the user kept (not removed).
+ * @param newAttachments - Brand-new attachments the user added during editing.
+ */
+export declare const isMessageChanged: (originalMessage: Message, newText: string, keptDisplayAttachments: DisplayAttachment[], newAttachments: Attachment[]) => boolean;
+
+/**
+ * Returns `true` when `message` is the actively-streaming assistant response.
+ * Only the last message in the list can be streaming, and only while
+ * `isAssistantTyping` is `true`.
+ */
+export declare const isMessageStreaming: (message: Message, messageIndex: number, totalMessages: number, isAssistantTyping: boolean) => boolean;
+
+declare interface LocalModeParams {
+    mode: 'local';
+    values: LocalModeValues;
+    onValuesChange: (values: LocalModeValues) => void;
+    deploymentFeatures?: DeploymentFeatures;
+    /** True when the selected deployment is a Quick App. Its orchestrator sets its own fixed temperature, so the temperature field is forced off regardless of `deploymentFeatures`. */
+    isQuickApp?: boolean;
+}
+
+declare interface LocalModeValues {
+    responseFormat: ResponseFormat;
+    systemPrompt: string;
+    temperature: number;
+}
+
+/** True when `message` is an assistant message carrying at least one stage. */
+export declare const messageHasStages: (message: Message) => boolean;
+
+/** A newly-created user message paired with its empty assistant placeholder. */
+export declare interface MessagePair {
+    userMessage: Message;
+    assistantMessage: Message;
+}
+
+/**
+ * Normalises a stored response-format string to the current enum. Legacy data
+ * may contain `'Markdown'` or `'PlainText'` (capital-first) instead of the
+ * current enum values `'markdown'` / `'plain_text'`.
+ */
+export declare const normalizeResponseFormat: (value: string | undefined) => ResponseFormat;
+
+/** Common, host-injected options shared by both modes. */
+declare interface Options {
+    /** Translatable labels. Fields not provided fall back to English defaults. */
+    labels?: Partial<ChatSettingsFormLabels>;
+    /** Called after a successful save so the host can surface its own toast/notification. */
+    onSaved?: () => void;
+}
+
+declare type Params = LocalModeParams | ConversationModeParams;
+
+/** Resolved Quick App conversation-starter settings. */
+export declare interface QuickAppConversationStartersSettings {
+    starters: StarterOption[];
+    introText: string | undefined;
+    isChatMessageInputDisabled: boolean;
+}
+
+/** State of one resource's recipient-count lookup. */
+declare interface RecipientsCountEntry {
+    /** Where the lookup for this resource currently stands. */
+    status: RecipientsCountStatus;
+    /** Number of users holding access; present only once the status is `Resolved`. */
+    count?: number;
+}
+
+/** Lifecycle of an on-demand recipient-count lookup for one resource. */
+declare enum RecipientsCountStatus {
+    /** Nothing requested yet for this resource. */
+    Idle = "idle",
+    /** A lookup is in flight. */
+    Loading = "loading",
+    /** A count came back and is known exactly. */
+    Resolved = "resolved",
+    /** The lookup failed, so the count is unknown. */
+    Unknown = "unknown"
+}
+
+/** Sanitizes announcement HTML to the allowed inline tag/attribute set. */
+export declare const sanitizeAnnouncementHtml: (html: string) => string;
+
+/**
+ * Sanitizes the legacy `ANNOUNCEMENT_HTML_MESSAGE` banner, which permits the
+ * block-level markup the inline pass strips. See
+ * `ANNOUNCEMENT_MESSAGE_SANITIZE_OPTIONS` for why the two lists differ.
+ */
+export declare const sanitizeAnnouncementMessageHtml: (html: string) => string;
+
+/** Sanitizes footer message HTML to the allowed tag/attribute set. */
+export declare const sanitizeFooterHtml: (html: string) => string;
+
+/** True when the first user/assistant exchange is complete and LLM naming may still run. */
+export declare const shouldWatchForDisplayNameUpdate: (conversation: Conversation) => boolean;
+
+/** Options accepted by {@link ConversationStreamTransport.streamCompletion}. */
+export declare interface StreamCompletionOptions {
+    onChunk: (chunk: StreamChunk) => void;
+    onComplete: () => void | Promise<void>;
+    onError: (error: Error) => void;
+    signal: AbortSignal;
+}
+
+/** Maps chat messages to the DIAL Chat Overlay protocol's message shape. */
+export declare const toOverlayMessages: (messages: Message[]) => OverlayChatMessage[];
+
+/**
+ * Synchronises the active conversation with the conversation list and returns
+ * the panel-space id of the active conversation, or `undefined` when none is active.
+ *
+ * Side effects:
+ * 1. If the active conversation is not present in the list, requests a
+ *    refresh. The list and refresh callback are intentionally excluded from
+ *    the dependency array to avoid a refresh-loop on every list update.
+ * 2. Marks the active conversation as viewed whenever it or the list changes.
+ */
+export declare const useActiveConversationSync: ({ activeConversationId, items, refreshConversations, markConversationViewed, conversationIdsMatch, toPanelConversationId, }: UseActiveConversationSyncParams) => string | undefined;
+
+/** Parameters for `useActiveConversationSync`. */
+export declare interface UseActiveConversationSyncParams {
+    /**
+     * The raw context id of the currently active conversation, as tracked by
+     * the host app. `undefined` when no conversation is active.
+     */
+    activeConversationId: string | undefined;
+    /** Raw conversation list from the API. */
+    items: ConversationListItemDto[];
+    /** Refetches the full conversation list. */
+    refreshConversations: () => Promise<void>;
+    /** Marks a scheduler-created conversation as viewed by raw context id. */
+    markConversationViewed: (id: string) => Promise<void>;
+    /**
+     * Returns `true` when two ids refer to the same conversation despite
+     * possible encoding differences. App-specific.
+     */
+    conversationIdsMatch: (a: string, b: string) => boolean;
+    /** Converts a raw context id to the panel-space id. App-specific. */
+    toPanelConversationId: (id: string) => string;
+}
+
+/**
+ * Generic single-slot pending / loading / error state machine for
+ * confirmation dialogs that trigger an async operation.
+ *
+ * Replaces the `[pendingXxx, setXxx] / [isXxxing, setIsXxxing] / [xxxError,
+ * setXxxError]` triads that previously appeared inline at each call site in
+ * `ConversationPanelView` and `ConversationPanelMenu`.
+ */
+export declare const useAsyncConfirmDialog: <T>() => AsyncConfirmDialogControls<T>;
+
+/**
+ * Uploads an attachment's file to DIAL Core storage against an
+ * already-configured `FilesApi` instance, coalescing a burst of
+ * offline/network upload failures into a single debounced callback rather
+ * than firing one notification per failed file.
+ */
+export declare const useAttachmentUpload: ({ filesApi, bucket, onNetworkError, debounceMs, }: UseAttachmentUploadParams) => UseAttachmentUploadResult;
+
+/** Parameters for {@link useAttachmentUpload}. */
+export declare interface UseAttachmentUploadParams {
+    /** Already-configured generated-client instance used to upload the file. */
+    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** DIAL Core bucket the file is uploaded into. */
+    bucket: string | undefined;
+    /** Called with batched filenames after a burst of network-error upload failures. */
+    onNetworkError?: (filenames: string[]) => void;
+    /** Debounce window, in ms, for coalescing offline-failure batches. Defaults to `700`. */
+    debounceMs?: number;
+}
+
+/** Return value of {@link useAttachmentUpload}. */
+export declare interface UseAttachmentUploadResult {
+    /** Uploads the given attachment's file and resolves to its DIAL Core file URL. */
+    handleUploadAttachment: (attachment: Attachment) => Promise<string>;
+}
+
+/**
+ * Assembles the chat-settings form config (feature flags, current values, save
+ * handler, labels) for either an in-flight local composer or a persisted
+ * conversation. Headless: translation and notifications are the host's
+ * responsibility, supplied via `labels` and `onSaved`.
+ */
+export declare const useChatSettingsFormConfig: (params: Params & Options) => UseChatSettingsFormConfigResult;
+
+/** Configuration the chat-settings popover/modal consumes. */
+export declare type UseChatSettingsFormConfigResult = {
+    /** Feature flags controlling which fields appear. */
+    features: {
+        systemPrompt: boolean;
+        temperature: boolean;
+        responseFormat: boolean;
+    };
+    /** Current response format pre-selected in the modal. */
+    responseFormat: ResponseFormat;
+    /** Current system prompt pre-populated in the modal. */
+    systemPrompt: string;
+    /** Current temperature pre-populated in the modal. */
+    temperature: number;
+    /** Called with updated values when the user clicks Save. */
+    onSave: (values: ChatSettingsValues) => void;
+    /** Label for the dropdown menu item. */
+    menuItemLabel: string;
+    /** Modal title. */
+    title: string;
+    /** Label for the response-format field. */
+    responseFormatLabel: string;
+    /** Helper text shown below the response-format field. */
+    responseFormatHint: string;
+    /** Label for the Markdown radio option. */
+    responseFormatMarkdownLabel: string;
+    /** Label for the plain-text radio option. */
+    responseFormatPlainTextLabel: string;
+    /** Label for the system-prompt field. */
+    systemPromptLabel: string;
+    /** Tooltip for the system-prompt field. */
+    systemPromptTooltip: string;
+    /** Label for the temperature field. */
+    temperatureLabel: string;
+    /** Slider endpoint labels, in `[precise, neutral, creative]` order. */
+    temperatureLabels: [string, string, string];
+    /** Hint text shown below the temperature field. */
+    temperatureHint: string;
+    /** Save button label. */
+    saveLabel: string;
+    /** Tooltip shown on the disabled Save button. */
+    saveDisabledTooltip: string;
+};
+
+/**
+ * Composes send/regenerate/edit/delete/rate/starter-submission orchestration
+ * on top of the library's own `useAttachmentUpload` and the injected
+ * `startStream` (from `useConversationStream`). Optimistic message-pair
+ * insertion, delete confirmation, and rate revert-on-failure all mutate the
+ * shared `state` channel directly, in lockstep with the streaming hook.
+ */
+export declare const useConversationHandlers: ({ conversation, conversationId, bucket, isStreaming, startStream, state: { setConversation, conversationRef }, filesApi, conversationsApi, rateApi, resolveModelId, onConversationDeleted, showNetworkError, toolConfigurationValue, }: UseConversationHandlersParams) => UseConversationHandlersResult;
+
+/** Parameters for {@link useConversationHandlers}. */
+export declare interface UseConversationHandlersParams {
+    conversation: Conversation | null;
+    conversationId: string | undefined;
+    bucket: string | undefined;
+    isStreaming: boolean;
+    /** The `startStream` function returned by `useConversationStream`. */
+    startStream: ConversationStreamStarter;
+    /** Shared mutable channel for the displayed conversation — the same one passed to `useConversationStream`. */
+    state: ConversationStateAccessor;
+    /** Already-configured generated-client instance used to upload attachments. */
+    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** Already-configured generated-client instance used to save/delete the conversation. */
+    conversationsApi: Pick<ConversationsApi, 'saveConversation' | 'deleteConversation'>;
+    /** Already-configured generated-client instance used to rate a message. */
+    rateApi: Pick<RateApi, 'rateMessage'>;
+    /** Resolves the model id to send with the next completion. Re-evaluated on every call — never cached. */
+    resolveModelId: () => string;
+    /** Called when deleting the last message also deletes the whole conversation. */
+    onConversationDeleted?: () => void;
+    /** Called with batched filenames after a burst of network-error upload failures. */
+    showNetworkError?: (filenames: string[]) => void;
+    /** Tool toggle configuration values merged into every outgoing completion request. */
+    toolConfigurationValue?: Record<string, boolean>;
+}
+
+/** Return value of {@link useConversationHandlers}. */
+export declare interface UseConversationHandlersResult {
+    handleSend: (message: string, attachments: Attachment[]) => Promise<void>;
+    handleUploadAttachment: (attachment: Attachment) => Promise<string>;
+    handleRegenerateMessage: (messageIndex: number) => void;
+    handleDeleteMessage: (messageIndex: number) => void;
+    handleConfirmDelete: () => void;
+    handleRateMessage: (messageIndex: number, rating: MessageRating | null, comment?: string) => Promise<boolean>;
+    handleButtonSelect: (starter: StarterOption, propertyKey?: string, description?: string) => void;
+    handleConfirmStarter: () => void;
+    handleStartEdit: (messageIndex: number) => void;
+    handleCancelEdit: (messageIndex: number) => void;
+    handleEditMessage: (messageIndex: number, text: string, keptDisplayAttachments: DisplayAttachment[], newAttachments: Attachment[]) => Promise<void>;
+    editingMessageIndexes: Set<number>;
+    pendingDeleteIndex: number | null;
+    setPendingDeleteIndex: (index: number | null) => void;
+    pendingStarterContext: {
+        starter: StarterOption;
+        propertyKey?: string;
+        description?: string;
+    } | null;
+    setPendingStarterContext: (context: {
+        starter: StarterOption;
+        propertyKey?: string;
+        description?: string;
+    } | null) => void;
+}
+
+/**
+ * Builds two memoised reverse-lookup maps from the raw conversation list:
+ * panel-space id → context id and panel-space id → raw DTO.
+ *
+ * Replaces the inlined `panelToContextId` map and `items.find` calls that
+ * previously appeared at each row-action call site in `ConversationPanelView`.
+ */
+export declare const useConversationLookupMaps: ({ items, toPanelConversationId, }: UseConversationLookupMapsParams) => ConversationLookupMaps;
+
+/** Parameters for `useConversationLookupMaps`. */
+export declare interface UseConversationLookupMapsParams {
+    /** Raw conversation list from the API. */
+    items: ConversationListItemDto[];
+    /** Converts a raw conversation id to the panel-space id. App-specific. */
+    toPanelConversationId: (id: string) => string;
+}
+
+/**
+ * Maps raw `ConversationListItemDto[]` to panel-compatible conversation items.
+ *
+ * Returns a memoised array whose shape is compatible with the conversation
+ * 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;
+    isUnread?: boolean | undefined;
+    id: string;
+    title: string;
+    isPinned: boolean;
+    iconUrl: string | undefined;
+    iconTooltip: string | undefined;
+    isIconLoading: boolean;
+    source: FilterTab;
+    href: string;
+}[];
+
+/** Parameters accepted by `useConversationPanelItems`. */
+export declare interface UseConversationPanelItemsParams extends UseConversationPanelItemsResolvers {
+    /** Raw conversation list from the API. */
+    items: ConversationListItemDto[];
+    /** Available deployments used to resolve icons and tooltips. */
+    deployments: DeploymentItemDto[];
+    /** Whether the deployments list is still loading (drives `isIconLoading`). */
+    isDeploymentsLoading: boolean;
+}
+
+/** Resolver callbacks injected by the host app into `useConversationPanelItems`. */
+export declare interface UseConversationPanelItemsResolvers {
+    /** Converts a raw conversation id to the panel-space id. App-specific. */
+    toPanelConversationId: (id: string) => string;
+    /** Resolves the icon URL for a deployment. Returns `undefined` when not available. */
+    resolveIconUrl: (deployment: DeploymentItemDto | undefined) => string | undefined;
+    /**
+     * Resolves the icon tooltip text. Receives the matched deployment (or
+     * `undefined`) and a decoded fallback string derived from the model path.
+     */
+    resolveIconTooltip: (deployment: DeploymentItemDto | undefined, fallback: string) => string | undefined;
+    /** 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.
+     */
+    resolveTaskBadge?: (item: ConversationListItemDto) => {
+        label: string;
+        isUnread: boolean;
+    } | undefined;
+}
+
+/**
+ * Owns completion-streaming state: per-path streaming/stoppable tracking,
+ * stale-chunk rejection, cross-navigation live-message buffering,
+ * reload-after-complete, backend-driven stop, and hard-refresh resume
+ * detection — all driven through the injected
+ * `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, }: UseConversationStreamParams) => UseConversationStreamResult;
+
+/** Parameters for {@link useConversationStream}. */
+export declare interface UseConversationStreamParams {
+    conversationId: string | undefined;
+    state: ConversationStateAccessor;
+    transport: ConversationStreamTransport;
+    generation: ConversationGenerationLifecycle;
+    channel?: ConversationStreamChannel;
+    overlay?: ConversationStreamOverlayNotifier;
+    onStopError?: (error: Error) => void;
+}
+
+/** Return value of {@link useConversationStream}. */
+export declare interface UseConversationStreamResult {
+    startStream: (conversationId: string, userContent: string, messageIndex: number, model: string, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum) => void;
+    handleStop: () => void;
+    resumeIfAwaitingGeneration: (currentConversationId: string, conversation: Conversation) => void;
+    /** Restores the accumulated live assistant message when its conversation is loaded again before completion. */
+    restoreBufferedGeneration: (currentConversationId: string, conversation: Conversation) => Conversation;
+    isStreaming: boolean;
+    canStopStreaming: boolean;
+}
+
+/**
+ * Manages the hidden `<input type="file">` pattern used to trigger a native
+ * file-picker without a visible control.
+ *
+ * The host renders `<input ref={inputRef} type="file" onChange={handleFileChange} />`
+ * and calls `triggerImport()` when the user initiates an import action. The
+ * hook sets the `accept` attribute via a layout effect so re-selecting the
+ * same file always fires `onChange` (the value is reset after each selection).
+ */
+export declare const useImportFilePicker: ({ accept, onFileSelected, }: UseImportFilePickerParams) => UseImportFilePickerResult;
+
+/** Parameters for `useImportFilePicker`. */
+export declare interface UseImportFilePickerParams {
+    /**
+     * MIME types / file-extension filter string passed to the hidden input's
+     * `accept` attribute. The host resolves any platform-specific policy before
+     * passing this value.
+     */
+    accept?: string;
+    /** Called with the selected `File` after the user confirms their choice. */
+    onFileSelected: (file: File) => void;
+}
+
+/** Controls returned by `useImportFilePicker`. */
+export declare interface UseImportFilePickerResult {
+    /** Ref to attach to the hidden `<input type="file">` element. */
+    inputRef: RefObject<HTMLInputElement | null>;
+    /** Programmatically opens the native file picker by clicking the hidden input. */
+    triggerImport: () => void;
+    /** `onChange` handler for the hidden input; calls `onFileSelected` and resets the value. */
+    handleFileChange: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+/**
+ * Derives the tools submenu from the active deployment's configuration schema:
+ * every boolean property becomes a toggle. Manages toggle state locally, resets
+ * on deployment change, and exposes a stable `toolConfigurationValue` record for
+ * inclusion in completion requests. Headless: the tool icon is the host's
+ * responsibility, supplied via `toolIcon`.
+ */
+export declare const useToolsMenu: (params: UseToolsMenuParams) => UseToolsMenuResult;
+
+/** Host-supplied inputs to {@link useToolsMenu}. */
+export declare interface UseToolsMenuParams {
+    /** Id of the currently selected deployment, or `null` when none is selected. */
+    selectedItemId: string | null;
+    /** JSON-schema configuration for the selected deployment, or `null` when none. */
+    selectedDeploymentConfiguration: DeploymentConfigurationSchema | null;
+    /** Icon element rendered on every tool menu item. Defaults to `null`. */
+    toolIcon?: ReactNode;
+}
+
+/** Result returned by {@link useToolsMenu}. */
+export declare type UseToolsMenuResult = {
+    /** One item per boolean property of the deployment configuration schema, in schema order. */
+    toolsMenuItems: ToolMenuItem[];
+    /** Toggles the tool with the given id; ignores unknown ids. */
+    onToolToggle: (id: string) => void;
+    /** Stable record of tool ids to their current on/off state, for completion requests. */
+    toolConfigurationValue: Record<string, boolean>;
+    /** Restores toggle state from a persisted tool configuration record. */
+    restoreToolConfiguration: (configurationValue: Record<string, unknown> | undefined) => void;
+};
+
+export { }