@xinghunm/ai-chat 1.3.2 → 1.4.0

package/README.md

@@ -39,6 +39,53 @@ export const App = () => <AiChat transport={transport} />
 <AiChat transport={transport} showConversationList />
 ```
 
+接入历史会话列表时，`ai-chat` 不请求后端 API。宿主应用负责分页获取会话列表，并把已加载的数据传给组件；列表滚动到底部时，组件会触发 `onLoadMoreSessions`：
+
+```tsx
+import { useState } from 'react'
+import type { ChatMessage, ChatSession } from '@xinghunm/ai-chat'
+
+const [sessions, setSessions] = useState<ChatSession[]>([])
+const [isLoading, setIsLoading] = useState(false)
+const [cursor, setCursor] = useState<string | null>(null)
+
+const loadMoreSessions = async () => {
+  if (isLoading) return
+
+  setIsLoading(true)
+  const response = await fetch(`/chat/sessions?cursor=${cursor ?? ''}`)
+  const data = (await response.json()) as {
+    sessions: ChatSession[]
+    nextCursor: string | null
+  }
+
+  setSessions((current) => [...current, ...data.sessions])
+  setCursor(data.nextCursor)
+  setIsLoading(false)
+}
+
+const loadSessionMessages = async (session: ChatSession): Promise<ChatMessage[]> => {
+  const response = await fetch(`/chat/sessions/${session.sessionId}/messages`)
+  const data = (await response.json()) as { messages: ChatMessage[] }
+  return data.messages
+}
+
+export const App = () => (
+  <AiChat
+    transport={transport}
+    showConversationList
+    historySessionList={{
+      sessions,
+      isLoading,
+      hasMore: cursor !== null,
+      error: null,
+    }}
+    onLoadMoreSessions={loadMoreSessions}
+    onSelectHistorySession={loadSessionMessages}
+  />
+)
+```
+
 如果你还在使用内置默认协议，也可以继续传 `apiBaseUrl` 和 `authToken`。`AiChatProvider` 会在内部自动创建默认 transport，属于兼容模式。
 
 如果只是路径不同，也不需要自己重写整个 transport，可以只覆盖默认 adapter 的 endpoints：
@@ -155,16 +202,19 @@ export const CustomChat = () => (
 
 一体化 `AiChat` 组件的 Props，继承全部 `AiChatProviderProps`（不含 `children`）。
 
-| 属性                     | 类型                     | 默认值           | 说明                                                                                                      |
-| ------------------------ | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
-| `transport`              | `ChatTransport`          | —                | 推荐。由接入方提供的传输适配器。                                                                          |
-| `apiBaseUrl`             | `string`                 | —                | 兼容模式。创建默认内置 transport。                                                                        |
-| `authToken`              | `string`                 | —                | 兼容模式下默认 transport 使用的鉴权头。                                                                   |
-| `defaultMode`            | `ChatAgentMode`          | `"agent"`        | 新会话的初始 Agent 模式。                                                                                 |
-| `labels`                 | `AiChatLabels`           | —                | 可选的 UI 文案覆盖。                                                                                      |
-| `showConversationList`   | `boolean`                | `false`          | 为 `true` 时渲染会话列表侧边栏。                                                                          |
-| `messageRenderOrder`     | `ChatMessageRenderOrder` | `"blocks-first"` | 混合纯文本与结构化 block 时的渲染顺序。默认结构化卡片在前；设为 `"timeline"` 时按时间线优先保留文本在前。 |
-| `enableImageAttachments` | `boolean`                | `true`           | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。           |
+| 属性                     | 类型                                                                   | 默认值           | 说明                                                                                                      |
+| ------------------------ | ---------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `transport`              | `ChatTransport`                                                        | —                | 推荐。由接入方提供的传输适配器。                                                                          |
+| `apiBaseUrl`             | `string`                                                               | —                | 兼容模式。创建默认内置 transport。                                                                        |
+| `authToken`              | `string`                                                               | —                | 兼容模式下默认 transport 使用的鉴权头。                                                                   |
+| `defaultMode`            | `ChatAgentMode`                                                        | `"agent"`        | 新会话的初始 Agent 模式。                                                                                 |
+| `labels`                 | `AiChatLabels`                                                         | —                | 可选的 UI 文案覆盖。                                                                                      |
+| `showConversationList`   | `boolean`                                                              | `false`          | 为 `true` 时渲染会话列表侧边栏。                                                                          |
+| `historySessionList`     | `ChatHistorySessionListState`                                          | —                | 受控历史会话列表状态。宿主应用负责请求后端并传入已加载会话。                                              |
+| `onLoadMoreSessions`     | `() => void \| Promise<void>`                                          | —                | 会话列表滚动到底部且 `hasMore` 为 `true` 时触发，由宿主应用加载下一页。                                   |
+| `onSelectHistorySession` | `(session) => ChatMessage[] \| void \| Promise<ChatMessage[] \| void>` | —                | 点击未加载过的历史会话时触发。返回消息数组时组件会写入内部 store；返回 `void` 时宿主自行控制。            |
+| `messageRenderOrder`     | `ChatMessageRenderOrder`                                               | `"blocks-first"` | 混合纯文本与结构化 block 时的渲染顺序。默认结构化卡片在前；设为 `"timeline"` 时按时间线优先保留文本在前。 |
+| `enableImageAttachments` | `boolean`                                                              | `true`           | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。           |
 
 ### `AiChatProviderProps`
 
@@ -172,29 +222,35 @@ export const CustomChat = () => (
 
 `AiChatProvider` 有两种接入方式，二选一：
 
-| 属性                     | 类型                       | 必填 | 说明                                                                                                         |
-| ------------------------ | -------------------------- | ---- | ------------------------------------------------------------------------------------------------------------ |
-| `transport`              | `ChatTransport`            | 是   | 推荐。完全自定义的传输层。                                                                                   |
-| `defaultMode`            | `ChatAgentMode`            | 否   | 新会话的初始 Agent 模式。                                                                                    |
-| `labels`                 | `AiChatLabels`             | 否   | 可选的 UI 文案覆盖。                                                                                         |
-| `renderMessageBlock`     | `ChatMessageBlockRenderer` | 否   | 自定义消息 block 渲染器，用于承接 `type: "custom"` 等扩展。                                                  |
-| `messageRenderOrder`     | `ChatMessageRenderOrder`   | 否   | 混合纯文本与结构化 block 时的渲染顺序。默认 `"blocks-first"`，设为 `"timeline"` 可按时间线优先渲染文本片段。 |
-| `enableImageAttachments` | `boolean`                  | 否   | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。默认 `true`。 |
-| `children`               | `ReactNode`                | 是   | Provider 内部渲染的子元素。                                                                                  |
+| 属性                     | 类型                                                                   | 必填 | 说明                                                                                                         |
+| ------------------------ | ---------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------ |
+| `transport`              | `ChatTransport`                                                        | 是   | 推荐。完全自定义的传输层。                                                                                   |
+| `defaultMode`            | `ChatAgentMode`                                                        | 否   | 新会话的初始 Agent 模式。                                                                                    |
+| `labels`                 | `AiChatLabels`                                                         | 否   | 可选的 UI 文案覆盖。                                                                                         |
+| `renderMessageBlock`     | `ChatMessageBlockRenderer`                                             | 否   | 自定义消息 block 渲染器，用于承接 `type: "custom"` 等扩展。                                                  |
+| `messageRenderOrder`     | `ChatMessageRenderOrder`                                               | 否   | 混合纯文本与结构化 block 时的渲染顺序。默认 `"blocks-first"`，设为 `"timeline"` 可按时间线优先渲染文本片段。 |
+| `historySessionList`     | `ChatHistorySessionListState`                                          | 否   | 受控历史会话列表状态。                                                                                       |
+| `onLoadMoreSessions`     | `() => void \| Promise<void>`                                          | 否   | 会话列表滚动到底部且仍有下一页时触发。                                                                       |
+| `onSelectHistorySession` | `(session) => ChatMessage[] \| void \| Promise<ChatMessage[] \| void>` | 否   | 点击未加载过的历史会话时触发。                                                                               |
+| `enableImageAttachments` | `boolean`                                                              | 否   | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。默认 `true`。 |
+| `children`               | `ReactNode`                                                            | 是   | Provider 内部渲染的子元素。                                                                                  |
 
 兼容模式：
 
-| 属性                     | 类型                        | 必填 | 说明                                                                                                         |
-| ------------------------ | --------------------------- | ---- | ------------------------------------------------------------------------------------------------------------ |
-| `apiBaseUrl`             | `string`                    | 是   | 默认 adapter 的基础 URL。                                                                                    |
-| `authToken`              | `string`                    | 是   | 默认 adapter 使用的 Authorization 请求头值。                                                                 |
-| `transformStreamPacket`  | `TransformChatStreamPacket` | 否   | 默认 adapter 的流式包归一化扩展点。                                                                          |
-| `defaultMode`            | `ChatAgentMode`             | 否   | 新会话的初始 Agent 模式。                                                                                    |
-| `labels`                 | `AiChatLabels`              | 否   | 可选的 UI 文案覆盖。                                                                                         |
-| `renderMessageBlock`     | `ChatMessageBlockRenderer`  | 否   | 自定义消息 block 渲染器，用于承接 `type: "custom"` 等扩展。                                                  |
-| `messageRenderOrder`     | `ChatMessageRenderOrder`    | 否   | 混合纯文本与结构化 block 时的渲染顺序。默认 `"blocks-first"`，设为 `"timeline"` 可按时间线优先渲染文本片段。 |
-| `enableImageAttachments` | `boolean`                   | 否   | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。默认 `true`。 |
-| `children`               | `ReactNode`                 | 是   | Provider 内部渲染的子元素。                                                                                  |
+| 属性                     | 类型                                                                   | 必填 | 说明                                                                                                         |
+| ------------------------ | ---------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------ |
+| `apiBaseUrl`             | `string`                                                               | 是   | 默认 adapter 的基础 URL。                                                                                    |
+| `authToken`              | `string`                                                               | 是   | 默认 adapter 使用的 Authorization 请求头值。                                                                 |
+| `transformStreamPacket`  | `TransformChatStreamPacket`                                            | 否   | 默认 adapter 的流式包归一化扩展点。                                                                          |
+| `defaultMode`            | `ChatAgentMode`                                                        | 否   | 新会话的初始 Agent 模式。                                                                                    |
+| `labels`                 | `AiChatLabels`                                                         | 否   | 可选的 UI 文案覆盖。                                                                                         |
+| `renderMessageBlock`     | `ChatMessageBlockRenderer`                                             | 否   | 自定义消息 block 渲染器，用于承接 `type: "custom"` 等扩展。                                                  |
+| `messageRenderOrder`     | `ChatMessageRenderOrder`                                               | 否   | 混合纯文本与结构化 block 时的渲染顺序。默认 `"blocks-first"`，设为 `"timeline"` 可按时间线优先渲染文本片段。 |
+| `historySessionList`     | `ChatHistorySessionListState`                                          | 否   | 受控历史会话列表状态。                                                                                       |
+| `onLoadMoreSessions`     | `() => void \| Promise<void>`                                          | 否   | 会话列表滚动到底部且仍有下一页时触发。                                                                       |
+| `onSelectHistorySession` | `(session) => ChatMessage[] \| void \| Promise<ChatMessage[] \| void>` | 否   | 点击未加载过的历史会话时触发。                                                                               |
+| `enableImageAttachments` | `boolean`                                                              | 否   | 为 `false` 时隐藏上传按钮、禁用粘贴图片，并使程序化调用 `pickImages`/`pasteImages` 变为 no-op。默认 `true`。 |
+| `children`               | `ReactNode`                                                            | 是   | Provider 内部渲染的子元素。                                                                                  |
 
 ### `ChatTransport`
 

package/dist/index.d.mts

@@ -33,6 +33,43 @@ interface ChatSession {
     model: string;
     mode?: ChatAgentMode;
 }
+/**
+ * Loading states for externally hydrated historical session messages.
+ */
+type ChatSessionMessageLoadStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * A page of historical messages for a selected chat session.
+ */
+interface ChatHistorySessionMessagesPage {
+    messages: ChatMessage[];
+    previousCursor: string | null;
+    hasMorePrevious?: boolean;
+}
+/**
+ * Arguments passed when host applications load older messages for a session.
+ */
+interface ChatHistorySessionMessageLoadArgs {
+    session: ChatSession;
+    cursor?: string | null;
+    limit?: number;
+}
+/**
+ * Controlled historical session list state provided by host applications.
+ */
+interface ChatHistorySessionListState {
+    sessions: ChatSession[];
+    isLoading?: boolean;
+    hasMore?: boolean;
+    error?: string | null;
+}
+/**
+ * Host-provided callbacks used by the controlled historical session list.
+ */
+interface ChatHistorySessionListHandlers {
+    onLoadMoreSessions?: () => void | Promise<void>;
+    onSelectHistorySession?: (session: ChatSession) => Promise<ChatHistorySessionMessagesPage | ChatMessage[] | void> | ChatHistorySessionMessagesPage | ChatMessage[] | void;
+    onLoadMoreHistoryMessages?: (args: ChatHistorySessionMessageLoadArgs) => Promise<ChatHistorySessionMessagesPage | void> | ChatHistorySessionMessagesPage | void;
+}
 /**
  * Client-side image attachment metadata kept in chat messages.
  */
@@ -447,6 +484,9 @@ interface AiChatLabels {
     skillLoading?: string;
     skillEmpty?: string;
     removeSkillAriaLabel?: string;
+    sessionHistoryLoading?: string;
+    sessionHistoryLoadFailed?: string;
+    sessionHistoryEmpty?: string;
 }
 /**
  * State and actions exposed to custom new-chat trigger renderers.
@@ -477,6 +517,14 @@ interface AiChatProviderBaseProps {
     handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
+    /** Controlled historical session list state provided by the host application. */
+    historySessionList?: ChatHistorySessionListState;
+    /** Optional callback used when the conversation list needs another page. */
+    onLoadMoreSessions?: ChatHistorySessionListHandlers['onLoadMoreSessions'];
+    /** Optional callback used when selecting a historical session that needs messages. */
+    onSelectHistorySession?: ChatHistorySessionListHandlers['onSelectHistorySession'];
+    /** Optional callback used when the active historical session needs older messages. */
+    onLoadMoreHistoryMessages?: ChatHistorySessionListHandlers['onLoadMoreHistoryMessages'];
     /**
      * Whether to enable image attachment uploads. Defaults to `true`.
      * Set to `false` to hide the upload button, disable paste-image handling,
@@ -687,6 +735,15 @@ interface ChatState {
     isStreamingBySession: Record<string, boolean>;
     isStoppingBySession: Record<string, boolean>;
     errorBySession: Record<string, string | null>;
+    sessionMessageLoadStatusBySession: Record<string, ChatSessionMessageLoadStatus>;
+    sessionMessageLoadErrorBySession: Record<string, string | null>;
+    historyMessagePaginationBySession: Record<string, ChatHistoryMessagePaginationState>;
+}
+interface ChatHistoryMessagePaginationState {
+    previousCursor: string | null;
+    hasMorePrevious: boolean;
+    isLoadingPrevious: boolean;
+    error: string | null;
 }
 interface ChatActions {
     createSession: (session: ChatSession) => void;
@@ -695,7 +752,13 @@ interface ChatActions {
     replaceSessionId: (previousSessionId: string, nextSessionId: string) => void;
     setPreferredMode: (mode: ChatAgentMode) => void;
     setSessionMode: (sessionId: string, mode: ChatAgentMode) => void;
+    hydrateHistorySessions: (sessions: ChatSession[]) => void;
     appendMessage: (sessionId: string, message: ChatMessage) => void;
+    hydrateHistorySessionMessages: (sessionId: string, messages: ChatMessage[]) => void;
+    hydrateHistorySessionMessagesPage: (sessionId: string, page: ChatHistorySessionMessagesPage) => void;
+    prependHistorySessionMessagesPage: (sessionId: string, page: ChatHistorySessionMessagesPage) => void;
+    setHistorySessionPreviousMessagesLoadStatus: (sessionId: string, isLoading: boolean, error?: string | null) => void;
+    setHistorySessionMessageLoadStatus: (sessionId: string, status: ChatSessionMessageLoadStatus, error?: string | null) => void;
     startStreamingMessage: (sessionId: string, message: ChatMessage) => void;
     updateStreamingMessage: (sessionId: string, content: string) => void;
     patchStreamingMessage: (sessionId: string, patch: ChatStreamMessagePatch) => void;
@@ -746,6 +809,14 @@ interface ChatContextValue {
     transformStreamPacket?: TransformChatStreamPacket;
     /** Whether image attachments are enabled. Defaults to true. */
     enableImageAttachments: boolean;
+    /** Controlled historical session list state provided by the host application. */
+    historySessionList?: ChatHistorySessionListState;
+    /** Host callback triggered when the conversation list needs another page. */
+    onLoadMoreSessions?: ChatHistorySessionListHandlers['onLoadMoreSessions'];
+    /** Host callback triggered when a historical session needs messages. */
+    onSelectHistorySession?: ChatHistorySessionListHandlers['onSelectHistorySession'];
+    /** Host callback triggered when a historical session needs older messages. */
+    onLoadMoreHistoryMessages?: ChatHistorySessionListHandlers['onLoadMoreHistoryMessages'];
 }
 
 /**
@@ -762,4 +833,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatHistorySessionListHandlers, type ChatHistorySessionListState, type ChatHistorySessionMessageLoadArgs, type ChatHistorySessionMessagesPage, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatSessionMessageLoadStatus, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };

package/dist/index.d.ts

@@ -33,6 +33,43 @@ interface ChatSession {
     model: string;
     mode?: ChatAgentMode;
 }
+/**
+ * Loading states for externally hydrated historical session messages.
+ */
+type ChatSessionMessageLoadStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * A page of historical messages for a selected chat session.
+ */
+interface ChatHistorySessionMessagesPage {
+    messages: ChatMessage[];
+    previousCursor: string | null;
+    hasMorePrevious?: boolean;
+}
+/**
+ * Arguments passed when host applications load older messages for a session.
+ */
+interface ChatHistorySessionMessageLoadArgs {
+    session: ChatSession;
+    cursor?: string | null;
+    limit?: number;
+}
+/**
+ * Controlled historical session list state provided by host applications.
+ */
+interface ChatHistorySessionListState {
+    sessions: ChatSession[];
+    isLoading?: boolean;
+    hasMore?: boolean;
+    error?: string | null;
+}
+/**
+ * Host-provided callbacks used by the controlled historical session list.
+ */
+interface ChatHistorySessionListHandlers {
+    onLoadMoreSessions?: () => void | Promise<void>;
+    onSelectHistorySession?: (session: ChatSession) => Promise<ChatHistorySessionMessagesPage | ChatMessage[] | void> | ChatHistorySessionMessagesPage | ChatMessage[] | void;
+    onLoadMoreHistoryMessages?: (args: ChatHistorySessionMessageLoadArgs) => Promise<ChatHistorySessionMessagesPage | void> | ChatHistorySessionMessagesPage | void;
+}
 /**
  * Client-side image attachment metadata kept in chat messages.
  */
@@ -447,6 +484,9 @@ interface AiChatLabels {
     skillLoading?: string;
     skillEmpty?: string;
     removeSkillAriaLabel?: string;
+    sessionHistoryLoading?: string;
+    sessionHistoryLoadFailed?: string;
+    sessionHistoryEmpty?: string;
 }
 /**
  * State and actions exposed to custom new-chat trigger renderers.
@@ -477,6 +517,14 @@ interface AiChatProviderBaseProps {
     handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
+    /** Controlled historical session list state provided by the host application. */
+    historySessionList?: ChatHistorySessionListState;
+    /** Optional callback used when the conversation list needs another page. */
+    onLoadMoreSessions?: ChatHistorySessionListHandlers['onLoadMoreSessions'];
+    /** Optional callback used when selecting a historical session that needs messages. */
+    onSelectHistorySession?: ChatHistorySessionListHandlers['onSelectHistorySession'];
+    /** Optional callback used when the active historical session needs older messages. */
+    onLoadMoreHistoryMessages?: ChatHistorySessionListHandlers['onLoadMoreHistoryMessages'];
     /**
      * Whether to enable image attachment uploads. Defaults to `true`.
      * Set to `false` to hide the upload button, disable paste-image handling,
@@ -687,6 +735,15 @@ interface ChatState {
     isStreamingBySession: Record<string, boolean>;
     isStoppingBySession: Record<string, boolean>;
     errorBySession: Record<string, string | null>;
+    sessionMessageLoadStatusBySession: Record<string, ChatSessionMessageLoadStatus>;
+    sessionMessageLoadErrorBySession: Record<string, string | null>;
+    historyMessagePaginationBySession: Record<string, ChatHistoryMessagePaginationState>;
+}
+interface ChatHistoryMessagePaginationState {
+    previousCursor: string | null;
+    hasMorePrevious: boolean;
+    isLoadingPrevious: boolean;
+    error: string | null;
 }
 interface ChatActions {
     createSession: (session: ChatSession) => void;
@@ -695,7 +752,13 @@ interface ChatActions {
     replaceSessionId: (previousSessionId: string, nextSessionId: string) => void;
     setPreferredMode: (mode: ChatAgentMode) => void;
     setSessionMode: (sessionId: string, mode: ChatAgentMode) => void;
+    hydrateHistorySessions: (sessions: ChatSession[]) => void;
     appendMessage: (sessionId: string, message: ChatMessage) => void;
+    hydrateHistorySessionMessages: (sessionId: string, messages: ChatMessage[]) => void;
+    hydrateHistorySessionMessagesPage: (sessionId: string, page: ChatHistorySessionMessagesPage) => void;
+    prependHistorySessionMessagesPage: (sessionId: string, page: ChatHistorySessionMessagesPage) => void;
+    setHistorySessionPreviousMessagesLoadStatus: (sessionId: string, isLoading: boolean, error?: string | null) => void;
+    setHistorySessionMessageLoadStatus: (sessionId: string, status: ChatSessionMessageLoadStatus, error?: string | null) => void;
     startStreamingMessage: (sessionId: string, message: ChatMessage) => void;
     updateStreamingMessage: (sessionId: string, content: string) => void;
     patchStreamingMessage: (sessionId: string, patch: ChatStreamMessagePatch) => void;
@@ -746,6 +809,14 @@ interface ChatContextValue {
     transformStreamPacket?: TransformChatStreamPacket;
     /** Whether image attachments are enabled. Defaults to true. */
     enableImageAttachments: boolean;
+    /** Controlled historical session list state provided by the host application. */
+    historySessionList?: ChatHistorySessionListState;
+    /** Host callback triggered when the conversation list needs another page. */
+    onLoadMoreSessions?: ChatHistorySessionListHandlers['onLoadMoreSessions'];
+    /** Host callback triggered when a historical session needs messages. */
+    onSelectHistorySession?: ChatHistorySessionListHandlers['onSelectHistorySession'];
+    /** Host callback triggered when a historical session needs older messages. */
+    onLoadMoreHistoryMessages?: ChatHistorySessionListHandlers['onLoadMoreHistoryMessages'];
 }
 
 /**
@@ -762,4 +833,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatHistorySessionListHandlers, type ChatHistorySessionListState, type ChatHistorySessionMessageLoadArgs, type ChatHistorySessionMessagesPage, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatSessionMessageLoadStatus, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };