@icanbwell/baileyai-chat-ui 1.0.15 → 1.0.17

package/dist/index.d.ts

@@ -22,6 +22,30 @@ export declare const BAILEY_TABLE_GRID_ROW_THRESHOLD = 5;
 
 export declare const BAILEYAI_CHAT_UI_VERSION: string;
 
+/**
+ * Typed failure from the Bailey client. The message is a fixed string per kind and never
+ * includes a response body (bodies can carry PHI) or the text of `cause`.
+ *
+ * For kinds `network` and `timeout`, `cause` is the original error the runtime threw (the failed
+ * fetch's error, or the abort reason). It is never set for `http`, `invalid-response` or `aborted`.
+ * Browsers do not say whether a failed fetch was CORS, DNS or offline: all surface as a generic
+ * `TypeError`, so `kind` plus `cause` is all a host can show or log. Do not display `cause.message`
+ * to users without review, and do not log the request URL (it can carry identifiers).
+ */
+export declare class BaileyApiError extends Error {
+    /** HTTP status; 0 when no response was received (network, timeout, aborted). */
+    readonly status: number;
+    readonly kind: BaileyApiErrorKind;
+    constructor(params: {
+        status: number;
+        kind: BaileyApiErrorKind;
+        message?: string;
+        cause?: unknown;
+    });
+}
+
+export declare type BaileyApiErrorKind = 'http' | 'network' | 'timeout' | 'aborted' | 'invalid-response';
+
 export declare interface BaileyChartDataset {
     label: string;
     data: number[] | Array<{
@@ -53,9 +77,9 @@ export declare interface BaileyChatInputMessage {
     titleHint?: string;
 }
 
-export declare function BaileyChatPanel({ chat, placeholder, replyPlaceholder, emptyPlaceholder, suggestions, onHistoryClick, privacyNote, resolveActivityIcon, className, height, width, hideDeveloperDetails, renderMessageActions, renderTable, renderChart, renderMcpApp, labels: labelsProp, formatMessageTime: formatMessageTimeProp, }: BaileyChatPanelProps): JSX_2.Element;
+export declare function BaileyChatPanel({ chat, placeholder, replyPlaceholder, emptyPlaceholder, suggestions, onHistoryClick, history, locale, privacyNote, resolveActivityIcon, className, height, width, hideDeveloperDetails, renderMessageActions, renderTable, renderChart, renderMcpApp, labels: labelsProp, formatMessageTime: formatMessageTimeProp, }: BaileyChatPanelProps): JSX_2.Element;
 
-export declare interface BaileyChatPanelLabels extends ToolStepLabels {
+export declare interface BaileyChatPanelLabels extends ToolStepLabels, Partial<BaileyHistoryLabels> {
     /** Visible text of the "new chat" item in the "..." menu. */
     newChatButtonText: string;
     /** @deprecated No longer applied -- the "New chat" menu item is named by its visible text
@@ -102,6 +126,11 @@ export declare interface BaileyChatPanelLabels extends ToolStepLabels {
      *  McpAppFrame renderer — a host-supplied `renderMcpApp` (BaileyChatPanelProps) owns its
      *  own accessible naming instead. */
     mcpAppDefaultTitle: string;
+    /** Visible text of the control at the top of the transcript that loads older messages of a
+     *  loaded conversation (only rendered while `chat.hasEarlier`). */
+    loadEarlierButtonText?: string;
+    /** Shown beside that control when the last history load failed. Fixed copy: never an error message. */
+    loadEarlierErrorText?: string;
 }
 
 export declare interface BaileyChatPanelProps extends BaileyMarkdownRenderers {
@@ -140,6 +169,17 @@ export declare interface BaileyChatPanelProps extends BaileyMarkdownRenderers {
      *  stay reachable even before the first message. Omit entirely to keep the menu to just
      *  "New chat" (and no menu at all while the conversation is empty). */
     onHistoryClick?: () => void;
+    /** Opt-in default conversation-history drawer. Passing a Bailey client adds the "Chat history"
+     *  menu item and opens a drawer inside the panel (nothing is fetched until it opens). Selecting
+     *  a row calls `chat.loadConversation`, so `chat` must have been created with the same
+     *  `client`. `onHistoryClick`, when also supplied, wins: the host's own UI opens and the drawer
+     *  never mounts. Omit to keep today's behavior. */
+    history?: {
+        client: BaileyClient;
+        pageSize?: number;
+    };
+    /** Locale for the drawer's relative timestamps. Defaults to `navigator.language`. */
+    locale?: string;
     /** A short privacy/compliance note rendered below the input row, as the panel's bottom-most
      *  element — empty state only by default, or every state if `privacyNote.alwaysVisible` is
      *  set. No default — the exact copy/link is host-specific, so nothing is shown unless a host
@@ -147,7 +187,8 @@ export declare interface BaileyChatPanelProps extends BaileyMarkdownRenderers {
     privacyNote?: BaileyPrivacyNote;
     /** Customizes the icon shown next to each tool step — the live "Checking your vitals…" line
      *  while a tool runs, and each entry in the expanded "Used N tools" summary — based on the
-     *  tool name. No icon is shown for a step unless this returns one. */
+     *  tool name. No icon is shown for a step unless this returns one: `null`, `undefined`,
+     *  `false`, `true` and `''` render nothing, and `0` renders as "0". */
     resolveActivityIcon?: (toolName: string | null) => ReactNode;
     className?: string;
     /** Explicit panel height (number is treated as px, e.g. 600 or '600px' or '100vh'). Applied
@@ -188,13 +229,91 @@ export declare interface BaileyChatTransport {
         signal: AbortSignal;
         onChunk: (text: string) => void;
         onRequestId?: (requestId: string) => void;
+        /** Optional. When present, a transport that supports it sends it as the `x-chat-id`
+         *  request header so the backend loads and persists this conversation. Absent means the
+         *  request carries no conversation identity (the behavior of every existing host). */
+        conversationId?: string;
+        /** Optional. Fired with the conversation id the backend reports in the
+         *  `X-Conversation-Id` response header, if the transport can read it. */
+        onConversationId?: (conversationId: string) => void;
+        onMessageId?: (messageId: string) => void;
     }): Promise<{
         status?: number;
         text: string;
         errorMessage?: string;
+        /** Optional. `true` when the connection dropped after the response began, so what was
+         *  delivered through `onChunk` is incomplete. `useBaileyChat` then ends the turn in the
+         *  error state (the partial text stays visible) instead of treating it as a finished
+         *  answer. A transport that never sets it behaves exactly as before. */
+        interrupted?: boolean;
     }>;
 }
 
+/**
+ * A best-effort cleanup step (e.g. cancelling an unread response body) failed. Reported through
+ * the client's `onCleanupError` option and never thrown to the caller. The message is fixed and
+ * carries no response data.
+ */
+export declare class BaileyCleanupError extends Error {
+    readonly operation: 'cancel-response-body' | 'cancel-stream-reader';
+    constructor(params: {
+        operation: BaileyCleanupError['operation'];
+    });
+}
+
+export declare interface BaileyClient extends BaileyChatTransport {
+    listConversations(params?: {
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<BaileyConversationList>;
+    getConversation(params: {
+        conversationId: string;
+        limit?: number;
+        beforeAbsoluteIndex?: number;
+        signal?: AbortSignal;
+    }): Promise<BaileyConversationPage>;
+    deleteConversation(params: {
+        conversationId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    submitFeedback(params: {
+        conversationId: string;
+        messageId: string;
+        rating: 'up' | 'down';
+        reasonCodes?: string[];
+        comment?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    clearFeedback(params: {
+        conversationId: string;
+        messageId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export declare interface BaileyClientOptions {
+    /** Bailey API root. Expected to include the `/bailey/v1` prefix; a trailing slash is tolerated. */
+    baseUrl: string;
+    /** Called before every request. The library never reads or stores tokens itself. */
+    getHeaders: () => Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+    /** Fired once on a 401/403 response, before the call rejects (or the stream call returns). */
+    onAuthError?: (error: BaileyApiError) => void;
+    /** Called when a best-effort cleanup step fails (e.g. cancelling an unread response body).
+     *  Never thrown to the caller; an exception thrown by this callback is also contained. */
+    onCleanupError?: (error: BaileyCleanupError) => void;
+    /** Timeout for non-stream calls. Default 30_000. */
+    requestTimeoutMs?: number;
+    /** Max gap between stream chunks before the stream is aborted. Default 155_000 (a backstop just above `useBaileyChat`'s own 150s idle timeout). */
+    idleTimeoutMs?: number;
+    /** How `streamChat` sends a held conversation id: the legacy `x-chat-id` request header
+     *  (default) or the `conversation` field in the JSON body. Never both. Keep `'header'` until
+     *  the backend release that accepts the body field is deployed wherever the host runs;
+     *  an older backend rejects the unknown field with HTTP 400. */
+    conversationVia?: 'header' | 'body';
+}
+
 export declare type BaileyContentPart = {
     type: 'text';
     text: string;
@@ -213,6 +332,170 @@ export declare type BaileyContentPart = {
     displayMode?: string;
 };
 
+export declare interface BaileyContextLossInfo {
+    /** The id the turn sent. */
+    sentId: string;
+    /** The id the server reported instead; undefined when it reported none. */
+    reportedId?: string;
+}
+
+export declare interface BaileyConversationList {
+    conversations: BaileyConversationSummary[];
+    nextCursor: string | null;
+}
+
+export declare interface BaileyConversationPage {
+    conversation: BaileyConversationSummary;
+    messages: BaileyServerMessage[];
+    hasMoreBefore: boolean;
+    nextBeforeAbsoluteIndex: number | null;
+}
+
+/** Pluggable persistence for the held conversation id. `useBaileyChat` guards every call: an
+ *  implementation that throws is reported through `onStorageError` and the id stays in memory. */
+export declare interface BaileyConversationStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+
+export declare interface BaileyConversationSummary {
+    conversationId: string;
+    title: string | null;
+    status: string;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export declare function BaileyFeedbackButtons(props: BaileyFeedbackButtonsProps): JSX_2.Element | null;
+
+export declare interface BaileyFeedbackButtonsProps {
+    /** The backend's assistant message ID (`BaileyMessage.serverMessageId`). Renders nothing when empty. */
+    messageId: string;
+    /** Create or replace the rating. Any rejection (including a 404) means failure: the selection
+     *  reverts and an error is shown. Nothing is retried automatically; the user retries by hand. */
+    onSubmit: (submission: BaileyFeedbackSubmission) => Promise<void>;
+    /** Remove the rating and comment. Same rejection contract as `onSubmit`. */
+    onClear: (params: {
+        messageId: string;
+    }) => Promise<void>;
+    /** A previously submitted rating to show as selected. */
+    initialRating?: BaileyFeedbackRating;
+    /** Subset (and order) of the backend reason codes to offer. Defaults to all five. */
+    reasonOptions?: BaileyFeedbackReasonCode[];
+    /** Comment length limit; defaults to 2000 and can only be lowered. */
+    maxCommentLength?: number;
+    labels?: Partial<BaileyFeedbackLabels>;
+    className?: string;
+}
+
+export declare interface BaileyFeedbackHandlers {
+    onSubmit: (submission: BaileyFeedbackSubmission) => Promise<void>;
+    onClear: (params: {
+        messageId: string;
+    }) => Promise<void>;
+}
+
+export declare interface BaileyFeedbackLabels {
+    feedbackGroupLabel: string;
+    feedbackThumbsUpAriaLabel: string;
+    feedbackThumbsDownAriaLabel: string;
+    feedbackReasonGroupLabel: string;
+    feedbackCommentLabel: string;
+    feedbackCommentPlaceholder: string;
+    feedbackSubmitText: string;
+    feedbackCancelText: string;
+    feedbackThanksText: string;
+    feedbackUndoText: string;
+    feedbackEditText: string;
+    feedbackAddCommentText: string;
+    feedbackSavingText: string;
+    feedbackErrorText: string;
+    feedbackPrivacyNote: string;
+    feedbackReasonInaccurate: string;
+    feedbackReasonUnhelpful: string;
+    feedbackReasonUnsafe: string;
+    feedbackReasonTooLong: string;
+    feedbackReasonOther: string;
+}
+
+export declare type BaileyFeedbackRating = 'up' | 'down';
+
+/** The backend's reason-code enum. A host may select a subset, never add a code: the backend
+ *  rejects unknown codes with 422, which would fail the whole submit. */
+export declare type BaileyFeedbackReasonCode = 'inaccurate' | 'unhelpful' | 'unsafe' | 'too_long' | 'other';
+
+export declare interface BaileyFeedbackSubmission {
+    messageId: string;
+    rating: BaileyFeedbackRating;
+    /** Omitted when no reason is selected. */
+    reasonCodes?: BaileyFeedbackReasonCode[];
+    /** Omitted when blank. PHI-capable: only ever passed to `onSubmit`. */
+    comment?: string;
+}
+
+/** Owns the conversations list (so nothing is fetched until the drawer is mounted) and wires the
+ *  chat actions into the presentational view. */
+export declare function BaileyHistoryDrawer({ client, pageSize, chat, labels, locale, onClose }: BaileyHistoryDrawerProps): JSX_2.Element;
+
+export declare interface BaileyHistoryDrawerProps {
+    client: BaileyClient;
+    pageSize?: number;
+    chat: Pick<UseBaileyChatResult, 'conversationId' | 'loadConversation' | 'newChat' | 'historyStatus'>;
+    /** Already merged with the defaults by the panel. */
+    labels: BaileyHistoryLabels;
+    locale?: string;
+    onClose: (params: {
+        restoreFocusTo: BaileyHistoryFocusTarget;
+    }) => void;
+}
+
+declare type BaileyHistoryFocusTarget = 'menu' | 'input';
+
+export declare interface BaileyHistoryLabels {
+    /** Reused from the panel's menu: also the drawer's "New chat" control. */
+    newChatButtonText: string;
+    /** Reused from the panel's error banner: the drawer's Retry controls. */
+    retryButtonText: string;
+    historyTitle: string;
+    historyBackAriaLabel: string;
+    historyLoadingText: string;
+    historyLoadingMoreText: string;
+    historyLoadMoreText: string;
+    historyLoadMoreErrorText: string;
+    /** `{count}` is the number of conversations shown. */
+    historyCountTextOne: string;
+    historyCountTextMany: string;
+    historyEmptyTitle: string;
+    historyEmptyDescription: string;
+    historyEmptyCtaText: string;
+    historyErrorTitle: string;
+    historyErrorDescription: string;
+    /** Shown instead of the generic error when the list call fails with a 401/403. The English
+     *  wording is a default for copy review. */
+    historySessionExpiredTitle: string;
+    historySessionExpiredDescription: string;
+    /** Shown when opening the chosen conversation failed. */
+    historySelectErrorText: string;
+    historyUntitledText: string;
+    historyCurrentText: string;
+    historyMessageCountOne: string;
+    historyMessageCountMany: string;
+    /** `{title}` is the conversation title (user-facing only; never logged). */
+    historyDeleteAriaLabel: string;
+    historyDeleteConfirmQuestion: string;
+    historyDeleteConfirmText: string;
+    historyDeleteCancelText: string;
+    historyDeletingText: string;
+    historyDeletedText: string;
+    historyDeleteFailedText: string;
+    historyDeleteRetryText: string;
+    historyDeleteDismissText: string;
+    /** Only used when `Intl.RelativeTimeFormat` is unavailable. */
+    historyJustNowText: string;
+}
+
 export declare interface BaileyLastRequest {
     model: string;
     systemPrompt: string;
@@ -269,6 +552,19 @@ export declare interface BaileyMessage {
      *  never reads or interprets it — it exists purely as a pass-through so a transport/backend
      *  can use it as a conversation-title fallback for a turn whose only content is hidden. */
     titleHint?: string;
+    /** The backend's own ID for this assistant message, from `response.completed.message_id` (or
+     *  the transport's `onMessageId`). Distinct from `id`, which is minted client-side. A host
+     *  needs it to address the message in server APIs such as feedback; undefined on user
+     *  messages and when the backend doesn't report one (older backends). */
+    serverMessageId?: string;
+    /** The rating the user previously gave this assistant message, when the backend reports one
+     *  for a loaded conversation. Feeds `BaileyFeedbackButtons`' `initialRating`. PHI-capable
+     *  (`comment`): never logged or placed in trace events. */
+    feedback?: {
+        rating: BaileyFeedbackRating;
+        reasonCodes?: BaileyFeedbackReasonCode[];
+        comment?: string;
+    };
 }
 
 export declare interface BaileyOutputItem {
@@ -299,6 +595,24 @@ export declare interface BaileyPrivacyNote {
     alwaysVisible?: boolean;
 }
 
+export declare interface BaileyServerFeedback {
+    rating: string;
+    reasonCodes: string[];
+    comment?: string | null;
+    updatedAt?: string;
+}
+
+export declare interface BaileyServerMessage {
+    messageId: string;
+    role: string;
+    content: string;
+    hidden: boolean;
+    createdAt: string;
+    feedback?: BaileyServerFeedback | null;
+}
+
+export declare type BaileyStorageOperation = 'read' | 'write' | 'remove' | 'key';
+
 export declare type BaileyStreamEvent = {
     type: 'response.output_text.delta';
     delta: string;
@@ -316,8 +630,19 @@ export declare type BaileyStreamEvent = {
     message?: string;
 } | {
     type: 'response.created';
+    response?: {
+        conversation?: {
+            id?: unknown;
+        } | null;
+    };
 } | {
     type: 'response.completed';
+    message_id?: string;
+    response?: {
+        conversation?: {
+            id?: unknown;
+        } | null;
+    };
 } | {
     type: 'error';
     message: string;
@@ -440,8 +765,38 @@ export declare interface CopyMarkdownButtonProps {
     tooltipCopiedText?: string;
 }
 
+/** Creates the Bailey HTTP client: streaming chat, conversation list/read/delete and feedback.
+ *  The host supplies `baseUrl` and `getHeaders`; the client never reads or stores tokens and never
+ *  logs request or response bodies. Failures reject with `BaileyApiError` (fixed message, no body). */
+export declare function createBaileyClient(options: BaileyClientOptions): BaileyClient;
+
+/**
+ * Props for `BaileyFeedbackButtons` backed by the Bailey client. Both handlers reject (the
+ * buttons then revert and show their error state; nothing is retried automatically) with
+ * `Error('no conversation id')` when no id is held, without calling the client, and otherwise
+ * propagate the client's `BaileyApiError`. The comment is only ever sent in the request body: it
+ * is never logged and never placed in an error.
+ */
+export declare function createBaileyFeedbackHandlers(params: {
+    client: BaileyClient;
+    /** Read at call time, so it can be `() => chat.conversationId` from a ref or latest value. */
+    getConversationId: () => string | undefined;
+}): BaileyFeedbackHandlers;
+
 export declare function createBaileyMarkdownComponents({ renderTable, renderChart }?: BaileyMarkdownRenderers): Components;
 
+/** In-memory storage, one instance per call; useful for tests and for hosts that want no browser storage. */
+export declare function createMemoryConversationStorage(): BaileyConversationStorage;
+
+/**
+ * sessionStorage-backed storage. Failures (Safari private mode, blocked cookies, quota, or
+ * `window.sessionStorage` itself throwing) propagate to the caller on purpose: `useBaileyChat`
+ * catches them and surfaces them as `persistence: 'degraded'` and `onStorageError`.
+ */
+export declare function createSessionConversationStorage(): BaileyConversationStorage;
+
+export declare const DEFAULT_CONVERSATION_STORAGE_KEY = "baileyai-chat-ui:conversation";
+
 export declare function extractPseudoToolCalls(text: string, options?: ExtractPseudoToolCallsOptions): ExtractPseudoToolCallsResult;
 
 declare interface ExtractPseudoToolCallsOptions {
@@ -465,6 +820,18 @@ export declare const extractTableData: (node: HastNode) => {
     rows: BaileyTableCell[][];
 } | null;
 
+/**
+ * Relative time such as "2 hours ago" via Intl (no dependency). A future time (clock skew) is
+ * clamped to "now"; past 30 days it becomes a medium date. Returns '' for an unparseable time.
+ * `justNowText` is only used when Intl.RelativeTimeFormat does not exist.
+ */
+export declare function formatRelativeTime(params: {
+    iso: string;
+    locale?: string;
+    now?: number;
+    justNowText?: string;
+}): string;
+
 export declare function formatTraceGap(ms: number): string;
 
 export declare function formatTraceTime(at: number): string;
@@ -485,10 +852,34 @@ export declare function HeartIcon({ className }: {
     className?: string;
 }): JSX_2.Element;
 
+/**
+ * True when `conversationId` carries the `<sub>:` prefix the server requires of the caller's ids
+ * (it silently replaces any other id), with a non-empty remainder. A blank `sub` never matches.
+ * This only validates; the library does not create conversation ids.
+ */
+export declare function isConversationIdForSub(params: {
+    conversationId: string;
+    sub: string;
+}): boolean;
+
 export declare const isSafeMarkdownUrl: (href: string) => boolean;
 
 export declare function joinInstructions(...parts: Array<string | undefined | null | false>): string;
 
+/**
+ * Turns a server transcript page into chat messages, oldest-first as given. Drops rows the user
+ * never saw (`hidden`) and any role other than user/assistant. Never logs.
+ */
+export declare function mapTranscript(params: {
+    messages: BaileyServerMessage[];
+}): BaileyMessage[];
+
+/** Prepends an earlier page to the current messages, dropping earlier rows already present. */
+export declare function mergeEarlierPage(params: {
+    current: BaileyMessage[];
+    earlier: BaileyMessage[];
+}): BaileyMessage[];
+
 export declare const parseBaileyChartSpec: (raw: string) => BaileyChartSpec | null;
 
 export declare interface ParsedSseFrames {
@@ -519,6 +910,16 @@ export declare function resolveToolCall(name: string, argsJson: string | undefin
 
 export declare const shouldUseGrid: (rows: BaileyTableCell[][]) => boolean;
 
+export declare function ThumbDownIcon({ className, filled }: {
+    className?: string;
+    filled?: boolean;
+}): JSX_2.Element;
+
+export declare function ThumbUpIcon({ className, filled }: {
+    className?: string;
+    filled?: boolean;
+}): JSX_2.Element;
+
 export declare function toActivityLines(events: BaileyTraceEvent[], turnSentAt: number | undefined): ActivityLine[];
 
 export declare interface ToolStep {
@@ -592,7 +993,7 @@ export declare type TraceSegment = {
 
 export declare function traceSummaryLine(events: BaileyTraceEvent[]): string;
 
-export declare const useBaileyChat: ({ transport, model, instructions, tools, toolChoice, firstUserMessagePrefix, onAssistantMessageComplete, idleTimeoutMs, }: UseBaileyChatConfig) => UseBaileyChatResult;
+export declare const useBaileyChat: ({ transport, model, instructions, tools, toolChoice, firstUserMessagePrefix, onAssistantMessageComplete, idleTimeoutMs, client, conversationId: seedConversationId, sub: rawSub, storage: storageOption, storageKey, sendFullTranscript, onStorageError, onContextLoss, }: UseBaileyChatConfig) => UseBaileyChatResult;
 
 export declare interface UseBaileyChatConfig {
     transport: BaileyChatTransport;
@@ -616,9 +1017,62 @@ export declare interface UseBaileyChatConfig {
      *  hang the UI forever. Resets on every chunk. Defaults to 150s, matching Bailey's own
      *  upstream idle timeout so a well-behaved backend error has a chance to arrive first. */
     idleTimeoutMs?: number;
+    /** Opt-in. Enables `loadConversation` / `loadEarlier` (history loading through the Bailey
+     *  client). Streaming still goes through `transport`; pass the same client for both. */
+    client?: BaileyClient;
+    /** Opt-in. Seeds the held conversation id (e.g. to resume a conversation). Takes precedence
+     *  over an id restored from `storage`. With `sub`, a seed that does not start with `<sub>:`
+     *  is ignored and never sent. Once an id is held it is sent to the transport as
+     *  `conversationId` on every turn. */
+    conversationId?: string;
+    /** Opt-in. The signed-in user's subject, used ONLY to key and validate the stored id: the
+     *  stored value lives under `${storageKey}:${sub}` and is rejected on read (and removed) unless
+     *  it starts with `<sub>:`, so a different user in the same browser session never inherits the
+     *  previous user's id. A seed and any id reported by the transport are validated the same way.
+     *  The library never mints an id and never decodes a token. A blank `sub` is treated as absent.
+     *  Hosts should also clear the stored id on logout through the same `storage`. */
+    sub?: string;
+    /** Persistence for the held conversation id. On by default: sessionStorage (per tab), so a
+     *  reload resumes the conversation. `null` disables it. Without `sub` the stored id is held
+     *  unvalidated (the server rejects an id that is not the caller's and the library then adopts
+     *  the server-reported one); with `sub` it is keyed and validated, see `sub`. Pass your own
+     *  `BaileyConversationStorage` to override. A storage that throws is treated as unavailable.
+     *  Hosts should clear it on logout. */
+    storage?: BaileyConversationStorage | false;
+    /** Storage key base for the held id. Hosts with several chat surfaces append their own surface
+     *  name so surfaces do not share a conversation. With `sub` the key used is
+     *  `${storageKey}:${sub}`. Defaults to DEFAULT_CONVERSATION_STORAGE_KEY. */
+    storageKey?: string;
+    /** By default, once a conversation id is held only the newest message is sent in `input`
+     *  (the server prepends the stored history and does not deduplicate); with no id held the
+     *  full transcript is sent. Set to `true` to always send the full transcript and never the id
+     *  (stateless requests; an escape hatch, e.g. for an environment where the server does not
+     *  persist). The id is withheld because with one the server would prepend its stored history to
+     *  the full transcript. The held id is still tracked, stored and used by `loadConversation`. */
+    sendFullTranscript?: boolean;
+    /** Called when a storage call fails (read, write or remove on `storage`) or when `sub` is
+     *  provided but blank (operation `'key'`). Chat keeps working with the id in memory only and
+     *  `persistence` becomes `'degraded'`. Receives the underlying error; nothing is logged. */
+    onStorageError?: (error: unknown, operation: BaileyStorageOperation) => void;
+    /** Called when a turn that sent a held id came back with no id or a different one: the server
+     *  did not continue that conversation (persistence off, unknown or foreign id, or history that
+     *  could not be loaded). The held id and its stored value are dropped, so the next turn sends
+     *  the full transcript. */
+    onContextLoss?: (info: BaileyContextLossInfo) => void;
 }
 
 export declare interface UseBaileyChatResult {
+    /** `'ok'`: the held id is persisted. `'off'`: the host passed `storage: false`. `'degraded'`: a
+     *  storage call failed or `sub` was blank, so the id lives in memory only. Optional in the type
+     *  so hosts that construct their own result objects still compile. */
+    persistence?: 'ok' | 'degraded' | 'off';
+    /** True from a turn whose reported id was missing or different from the one sent (see
+     *  `onContextLoss`) until the next turn starts or the conversation is replaced. */
+    contextLost?: boolean;
+    /** Read-only. The held conversation id (seeded, restored from `storage`, or reported by the
+     *  transport via `onConversationId`); `undefined` until one exists and after `newChat()`.
+     *  Optional in the type so hosts that construct their own result objects still compile. */
+    conversationId?: string;
     messages: BaileyMessage[];
     traceEvents: BaileyTraceEvent[];
     lastRequest: BaileyLastRequest | null;
@@ -669,6 +1123,45 @@ export declare interface UseBaileyChatResult {
      *  whose `role` isn't `'user'` or `'assistant'` is dropped rather than trusted, since a
      *  restored transcript crosses a service boundary this hook doesn't control. */
     loadMessages: (messages: BaileyMessage[]) => void;
+    /** Loads the newest page of a stored conversation (requires `client`), replaces the messages,
+     *  and holds `conversationId` (so later turns send only the newest message). With `sub`, an id
+     *  without the `<sub>:` prefix rejects with `Error('invalid conversation id')` and no request
+     *  is made. Rejects with the client's `BaileyApiError` on failure (messages are left intact and
+     *  `historyStatus` is `'error'`). A response that arrives after `newChat()`, `loadMessages` or
+     *  another `loadConversation` is discarded. Optional in the type so hosts that construct their
+     *  own result objects still compile; the hook always provides it. */
+    loadConversation?: (params: {
+        conversationId: string;
+    }) => Promise<void>;
+    /** Loads the next-older page of the held conversation and prepends it (deduplicated). No-op
+     *  when `hasEarlier` is false. Rejects like `loadConversation`. */
+    loadEarlier?: () => Promise<void>;
+    /** True while an older page exists for the held conversation. */
+    hasEarlier?: boolean;
+    /** State of the most recent history load. */
+    historyStatus?: 'idle' | 'loading' | 'error';
+}
+
+/** Lists the caller's conversations through `client` (loading, error, refresh, load more, delete with
+ *  rollback on failure). Nothing is fetched while `enabled` is false. Titles are PHI-capable and are
+ *  never logged. */
+export declare function useBaileyConversations(params: {
+    client: BaileyClient;
+    pageSize?: number;
+    enabled?: boolean;
+}): UseBaileyConversationsResult;
+
+export declare interface UseBaileyConversationsResult {
+    conversations: BaileyConversationSummary[];
+    status: 'idle' | 'loading' | 'error';
+    error: BaileyApiError | null;
+    hasMore: boolean;
+    refresh: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    /** Optimistic remove; restores the row and rethrows if the delete fails. */
+    remove: (params: {
+        conversationId: string;
+    }) => Promise<void>;
 }
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icanbwell/baileyai-chat-ui",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Shared React chat UI and streaming logic for Bailey, the icanbwell AI assistant",
   "license": "Apache-2.0",
   "repository": {