@blade-hq/agent-react 2612.0.0-beta.0 → 2612.0.0-beta.10

package/dist/chat/message-list-blocks.d.ts

@@ -0,0 +1,92 @@
+import type { ChatMessage } from "@blade-hq/agent-client/internal";
+export declare const RECENT_RESIDENT_TURNS = 8;
+type RenderBlockBase = {
+    key: string;
+    persistentId: string | null;
+    isStreaming: boolean;
+};
+export type AssistantTurnRenderBlock = RenderBlockBase & {
+    type: "assistant_turn";
+    messages: ChatMessage[];
+    anchorId: string;
+    railTitle: string;
+    /**
+     * 本轮对应的用户发言 entry_id。导航条以用户发言命名，跳转也应落在用户
+     * 发言上而不是智能体回复上；只给紧跟用户发言的第一个回复块，同一发言
+     * 后的第二个回复块（被压缩卡/规划分隔线切开）回退到自身锚点。
+     */
+    userEntryId: string | null;
+};
+export type RenderBlock = (RenderBlockBase & {
+    type: "message";
+    message: ChatMessage;
+    anchorId: string | null;
+}) | AssistantTurnRenderBlock | (RenderBlockBase & {
+    type: "context_group";
+    messages: ChatMessage[];
+}) | (RenderBlockBase & {
+    type: "context_divider";
+}) | (RenderBlockBase & {
+    type: "compaction";
+    message: ChatMessage;
+}) | (RenderBlockBase & {
+    type: "planning_divider";
+    kind: "enter" | "exit";
+    message: ChatMessage;
+});
+export declare function shouldAppendPendingAssistantTurn(sessionIsStreaming: boolean, lastMessage: ChatMessage | undefined): boolean;
+/** 从同一份消息序列生成唯一的渲染计划，流式和历史加载都复用它。 */
+export declare function buildMessageListBlocks({ messages, agentLoopNames, sessionIsStreaming, showContexts, }: {
+    messages: ChatMessage[];
+    agentLoopNames: ReadonlySet<string>;
+    sessionIsStreaming: boolean;
+    showContexts?: boolean;
+}): RenderBlock[];
+export declare function getRenderBlockPersistentId(block: RenderBlock): string | null;
+/**
+ * 完整 turn 从上一个 assistant turn 之后开始，到当前已完成 assistant turn 结束。
+ * 返回最近 N 个完整 turn 的起点；更靠后的流式/pending 内容自然落入常驻尾部。
+ */
+export declare function startIndexOfLastNCompleteTurns(blocks: RenderBlock[], count: number): number;
+export declare function findStablePrefixEnd(blocks: RenderBlock[], recentResidentTurns?: number): number;
+/**
+ * 目录刷新信号：窗口里**最后一条**用户发言的稳定 entry id。
+ *
+ * 与 SDK 的 `latestUserSpeechEntryId`（agent-react 的 use-turn-navigation.ts）同一
+ * 判据、同一名称，输入不同：那边拿投影轮，这边拿渲染好的消息。两边都只认"最新
+ * 一条"，因为往前翻页补进的更早发言不改变目录的结尾，用"窗口里全部发言"当信号
+ * 会把正在进行的定位判成过期。
+ *
+ * AskUserQuestion 的回答在列表里也渲染成用户发言（entry id 就是它自己），所以算一条。
+ */
+export declare function latestUserSpeechEntryId(messages: ChatMessage[]): string | null;
+export declare function buildMessageListBlockIndexes(blocks: RenderBlock[]): {
+    entryIdToBlockIndex: Map<string, number>;
+    turnIdToBlockIndex: Map<string, number>;
+};
+export type VisibleTurnRect = {
+    turnId: string;
+    top: number;
+    bottom: number;
+};
+/** 判定“已滚到底”的容差：浏览器 scrollTop 按物理像素取整会留 1-2px 残差。 */
+export declare const NAV_AT_BOTTOM_EPSILON_PX = 4;
+/** 按原有 viewport 15% 位置语义，从已相交的 turn 中选择导航高亮项。 */
+export declare function selectActiveTurnAtViewportPosition({ visibleTurns, containerTop, containerBottom, fallbackTurnId, currentTurnId, atBottom, }: {
+    visibleTurns: Iterable<VisibleTurnRect>;
+    containerTop: number;
+    containerBottom: number;
+    fallbackTurnId: string | null;
+    currentTurnId?: string | null;
+    /** 滚动容器已到底。 */
+    atBottom?: boolean;
+}): string | null;
+/** 测试双通道最终渲染计划时忽略仅影响布局的 wrapper。 */
+export declare function snapshotMessageListRenderPlan(blocks: RenderBlock[]): {
+    type: "assistant_turn" | "compaction" | "context_divider" | "context_group" | "message" | "planning_divider";
+    persistentId: string | null;
+    globalIndex: number;
+    messages: ChatMessage[];
+    isStreaming: boolean;
+}[];
+export {};

package/dist/chat/plan/PlanSummaryCard.d.ts

@@ -0,0 +1,10 @@
+import type { ChatMessage } from "@blade-hq/agent-client/internal";
+interface Props {
+    messages: ChatMessage[];
+    sessionStatus?: string;
+    onConfirmPlan?: (action: "execute" | "revise", text?: string) => void;
+    isHistorical?: boolean;
+    sessionId?: string;
+}
+export declare function PlanSummaryCard({ messages, sessionStatus, onConfirmPlan, isHistorical, sessionId, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/chat/plan/extract-plan-messages.d.ts

@@ -0,0 +1,4 @@
+import type { ChatMessage } from "@blade-hq/agent-client/internal";
+export declare function extractLatestPlanMessages(messages: ChatMessage[]): ChatMessage[];
+/** Keep each card within its submission while retaining the phase's skill context. */
+export declare function extractPlanMessagesForTurn(messages: ChatMessage[], turnLastMessage: ChatMessage): ChatMessage[];

package/dist/chat/plan/parse-plan-messages.d.ts

@@ -0,0 +1,10 @@
+import type { ChatMessage } from "@blade-hq/agent-client/internal";
+import type { PlanData } from "./types";
+/**
+ * Extract structured plan data from planning phase messages.
+ *
+ * Expects messages between planning-mode mode_change markers containing:
+ * - ReadSkill tool calls (技能调研：成功结果 = 选定技能，歧义 candidates = 候选列表)
+ * - Write tool call to PLAN.yaml with plan YAML
+ */
+export declare function parsePlanMessages(allMessages: ChatMessage[]): PlanData;

package/dist/chat/plan/parse-plan-tree.d.ts

@@ -0,0 +1,16 @@
+import type { PlanNode } from "./types";
+interface ParsedPlanResult {
+    plan: {
+        root: PlanNode;
+        notes: string[];
+    } | null;
+    error: string | null;
+}
+export type PlanStatusMap = Record<string, PlanNode["status"]>;
+export declare function parsePlanTree(content: string): {
+    root: PlanNode;
+    notes: string[];
+} | null;
+export declare function applyPlanStatusesById(root: PlanNode, statuses: PlanStatusMap): PlanNode;
+export declare function parsePlanTreeResult(content: string): ParsedPlanResult;
+export {};

package/dist/chat/plan/types.d.ts

@@ -0,0 +1,56 @@
+export interface SkillInfo {
+    skillId: string;
+    displayName?: string;
+    description: string;
+    content?: string;
+    references?: string[];
+}
+export interface SkillCatalogItem {
+    skillId: string;
+    displayName?: string;
+}
+export interface PlanNode {
+    id: string;
+    label: string;
+    skillRef: string | null;
+    children: PlanNode[];
+    depth: number;
+    status: "pending" | "running" | "done" | "failed";
+}
+export type Phase = "discovering" | "analyzing" | "generating";
+export interface PlanData {
+    intent: string;
+    /** All skills returned by search_skills (candidates) */
+    searchResults: SkillInfo[];
+    /** Skills selected via get_skill_content (subset of searchResults, with content populated) */
+    selectedSkills: SkillInfo[];
+    plan: {
+        root: PlanNode;
+        notes: string[];
+    } | null;
+    /** Raw plan YAML content (non-empty even if parsePlanTree yields no plan) */
+    hasPlanContent: boolean;
+    /** PLAN.yaml exists but failed to parse/validate for UI rendering */
+    parseError: string | null;
+    /** AskUserQuestion tool calls found in planning messages */
+    askQuestions: Array<{
+        toolCallId: string;
+        data: {
+            questions: Array<{
+                question: string;
+                options: Array<{
+                    label: string;
+                    description: string;
+                }>;
+                multiSelect?: boolean;
+            }>;
+        };
+    }>;
+    /** File paths from Read tool calls (with status) */
+    readFiles: Array<{
+        path: string;
+        status: "pending" | "done" | "error" | "cancelled" | "awaiting_answer";
+    }>;
+    /** The last pause-triggering tool in this phase: determines what UI to show */
+    lastPauseTool: "AskUserQuestion" | "ExitPlanMode" | null;
+}

package/dist/chat/reasoning-visibility.d.ts

@@ -0,0 +1,2 @@
+import type { ChatMessage } from "@blade-hq/agent-client/internal";
+export declare function findLatestReasoningMessageIndex(messages: readonly ChatMessage[]): number;

package/dist/chat/runtime/actions.d.ts

@@ -0,0 +1,23 @@
+import type { AgentSession, MessageContent, SendOptions, SessionState } from "@blade-hq/agent-client/internal";
+/**
+ * 等待回答时直接在输入框里打字：把这段文字当作最近一个子回路 AskUserQuestion 的自由作答，
+ * 服务端据此恢复运行，而不是另起一轮。
+ */
+export declare function buildPendingAskUserAnswer(state: SessionState, message: MessageContent): Record<string, unknown> | undefined;
+/** 发送附加项（模型、推理档位、知识库等由富输入给出）。 */
+export interface ChatSendExtras {
+    model?: string;
+    thinkingOverride?: boolean;
+    reasoningLevel?: string;
+    refs?: SendOptions["refs"];
+    topicAssetRefs?: SendOptions["topicAssetRefs"];
+    whatif?: SendOptions["whatif"];
+    replayDecision?: SendOptions["replayDecision"];
+    /**
+     * 声明「会话在跑就把这条消息放进等待队列」。只有渲染了队列面板、能展示等待消息的宿主才该传：
+     * 没有面板时排队等于消息凭空消失。
+     */
+    queueWhenRunning?: boolean;
+}
+/** 向会话发送一条消息。返回服务端是否接受（或已改道进等待队列）。 */
+export declare function sendToSession(session: AgentSession, message: MessageContent, mode?: string, askUserAnswer?: Record<string, unknown>, extras?: ChatSendExtras): Promise<boolean>;

package/dist/chat/runtime/background-task-dismissals.d.ts

@@ -0,0 +1,10 @@
+type Dismissed = Record<string, string[]>;
+export declare const backgroundTaskDismissals: {
+    getState: () => Dismissed;
+    subscribe(listener: () => void): () => void;
+    dismiss(sessionId: string, taskId: string): void;
+    /** 换身份：清空。 */
+    reset(): void;
+};
+export declare function useDismissedBackgroundTasks(sessionId: string): string[];
+export {};

package/dist/chat/runtime/composer-channels.d.ts

@@ -0,0 +1,50 @@
+import { type TopicAssetRef } from "@blade-hq/agent-client";
+export interface PendingContextSignal {
+    id: string;
+    label: string;
+    content: string;
+    imageUrl?: string;
+}
+export interface DraftAppendSignal {
+    id: string;
+    text: string;
+    separate?: boolean;
+}
+export interface SendRequestSignal {
+    id: string;
+}
+export interface ComposerChannelsState {
+    topicAssetReferences: Record<string, TopicAssetRef[]>;
+    pendingContexts: Record<string, PendingContextSignal[]>;
+    draftAppends: Record<string, DraftAppendSignal[]>;
+    sendRequests: Record<string, SendRequestSignal[]>;
+    modelDrafts: Record<string, string>;
+    rewindDrafts: Record<string, string>;
+}
+export declare const composerChannels: {
+    getState: () => ComposerChannelsState;
+    addTopicAssetReference(sessionId: string, ref: TopicAssetRef): void;
+    consumeTopicAssetReferences: (sessionId: string) => TopicAssetRef[];
+    subscribe(listener: () => void): () => void;
+    addPendingContext(sessionId: string, context: Omit<PendingContextSignal, "id">): void;
+    removePendingContext(sessionId: string, contextId: string): void;
+    consumePendingContexts: (sessionId: string) => PendingContextSignal[];
+    clearPendingContexts(sessionId: string): void;
+    addDraftAppend(sessionId: string, text: string, separate?: boolean): void;
+    consumeDraftAppends: (sessionId: string) => DraftAppendSignal[];
+    clearDraftAppends(sessionId: string): void;
+    addSendRequest(sessionId: string): void;
+    consumeSendRequests: (sessionId: string) => SendRequestSignal[];
+    clearSendRequests(sessionId: string): void;
+    setModelDraft(sessionId: string, model: string): void;
+    clearModelDraft(sessionId: string): void;
+    /** 回退到某一步后，把那一步的用户原话放回输入框（null 清除）。 */
+    setRewindDraft(sessionId: string, text: string | null): void;
+    /** 会话被关闭 / 删除：清掉它还没被取走的信号。 */
+    clearSession(sessionId: string): void;
+    /** 换身份：清空全部通道。 */
+    reset(): void;
+};
+export type ComposerChannels = typeof composerChannels;
+/** 读通道里的一小块状态；selector 应返回状态里的原值（引用稳定）。 */
+export declare function useComposerChannels<T>(selector: (state: ComposerChannelsState) => T): T;

package/dist/chat/runtime/environment.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 聊天环境（第一方内部）：内置 Web 需要、`<blade-chat>` 不需要的能力。每一项都可选，
+ * 缺省时走轻量实现——重依赖（虚拟列表、代码高亮、mermaid、streamdown、富输入）因此只在
+ * 注入它们的宿主里出现，不会进 blade-agent.js。
+ *
+ * hook 形式的注入点必须是稳定引用（模块常量），组件会无条件调用它们。
+ */
+import type { PostChatFollowup, ResultFeedback, SessionInfo, ToolCallInfo, ToolUiCard, TurnProjection } from "@blade-hq/agent-client/internal";
+import type { AskUserAnswerData } from "../AskUserQuestionBlock";
+import type { ComposerProps } from "../customization";
+import { type ComponentPropsWithoutRef, type ComponentType, type ReactNode } from "react";
+import type { CodeBlockOverrides } from "../../components/markdown";
+export type ChatRenderMode = "normal" | "lite" | "developer";
+/** `@tanstack/react-virtual` 的 `useVirtualizer` 里消息列表用到的那一部分。 */
+export interface ChatVirtualItem {
+    key: string | number | bigint;
+    index: number;
+    start: number;
+    size: number;
+}
+export interface ChatVirtualizer {
+    getVirtualItems(): ChatVirtualItem[];
+    getTotalSize(): number;
+    measureElement(element: Element | null): void;
+    scrollToIndex(index: number, options?: {
+        align?: "start" | "center" | "end" | "auto";
+    }): void;
+    getOffsetForIndex(index: number, align?: "start" | "center" | "end" | "auto"): readonly [number, string] | undefined;
+}
+export interface ChatVirtualizerOptions {
+    count: number;
+    getScrollElement: () => Element | null;
+    getItemKey: (index: number) => string | number;
+    estimateSize: (index: number) => number;
+    overscan?: number;
+    scrollMargin?: number;
+    /** 测量变化回调；`sync` 为 false 表示异步测量结果（不是用户滚动引起的）。 */
+    onChange?: (instance: ChatVirtualizer, sync: boolean) => void;
+}
+export type UseChatVirtualizer = (options: ChatVirtualizerOptions) => ChatVirtualizer;
+export type ChatCodeProps = ComponentPropsWithoutRef<"code"> & {
+    "data-block-offset"?: number;
+};
+/** 开发者视图（只在内置 Web 注入）：按投影原样展示每一轮。 */
+export interface DeveloperMessageListProps {
+    sessionId: string;
+    turns: TurnProjection[];
+    isViewer: boolean;
+    isLoadingHistory: boolean;
+    isStreaming?: boolean;
+    sessionStatus?: string;
+    postChatFollowup?: PostChatFollowup | null;
+    resultFeedbackByEntry?: ReadonlyMap<string, ResultFeedback>;
+    onResultFeedbackSaved?: (feedback: ResultFeedback) => void;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    onLoadOlder?: (beforeCommit?: () => void) => Promise<boolean>;
+    isLoadingOlder?: boolean;
+    historyLoadRevision?: number;
+    isStopping?: boolean;
+    onRevealingChange?: (revealing: boolean) => void;
+    isReplay?: boolean;
+}
+export interface ChatEnvironment {
+    /** 当前渲染模式；不注入时是普通模式。 */
+    renderMode?: ChatRenderMode;
+    /** 开发者视图；不注入时开发者模式按普通模式显示。 */
+    DeveloperMessageList?: ComponentType<DeveloperMessageListProps>;
+    /** 默认输入框（内置 Web 注入富输入）；不注入时用轻输入。 */
+    Composer?: ComponentType<ComposerProps>;
+    /** 虚拟列表；不注入时消息全部按常驻行渲染。 */
+    useVirtualizer?: UseChatVirtualizer;
+    /** 代码高亮（返回 null 时按纯文本显示）。 */
+    useHighlightedCode?: (code: string, language: string | null | undefined) => {
+        highlightedHtml: string | null;
+    };
+    /** Markdown 里 `code` 元素的渲染（内置 Web 用它渲染业务卡片与高亮）。 */
+    MarkdownCode?: ComponentType<ChatCodeProps>;
+    /** Markdown 里按语言整体替换的代码块（如 mermaid）。 */
+    markdownCodeBlocks?: CodeBlockOverrides;
+    /** 思考过程的 Markdown 渲染；不注入时用普通 Markdown。 */
+    ReasoningMarkdown?: ComponentType<{
+        children: string;
+        className?: string;
+    }>;
+    /** 消息里 tool_ui 卡片（MCP 应用、工具界面）的渲染；不注入时用 SDK 的 ToolUiCardView。 */
+    ToolUiCard?: ComponentType<{
+        card: ToolUiCard;
+        sessionId: string;
+    }>;
+    /** 会话详情（标题、方案等）；不注入时只用会话状态里的字段。 */
+    useSessionDetail?: (sessionId: string | null | undefined) => SessionInfo | null | undefined;
+    /** 用户是否关闭了任务进度面板。 */
+    useHideTodo?: () => boolean;
+    /** 普通提示（成功 / 失败 / 说明）；不注入时只打日志。 */
+    notify?: (kind: ChatNoticeKind, message: string, options?: ChatNoticeOptions) => void;
+    /** 打开工具界面卡片的预览页签。 */
+    openToolPreview?: (target: {
+        sessionId: string;
+        toolCall: ToolCallInfo;
+        card: ToolUiCard;
+        title: string;
+    }) => void;
+    /** 打开「计划」侧栏。 */
+    openPlanPanel?: (sessionId: string) => void;
+    /** 在沙盒浏览器里打开链接（本机地址）。 */
+    openInSandboxBrowser?: (sessionId: string, url: string) => void;
+    /** 把文字放进输入框（跟进建议等）；`separate` 为 true 时另起一段。不注入时走 `AgentSession.insertText`。 */
+    appendToComposer?: (sessionId: string, text: string, separate?: boolean) => void;
+    /** 把一段待发送的上下文放进输入框（MCP 应用消息）；不注入时走 `AgentSession.attach`。 */
+    addComposerContext?: (sessionId: string, context: {
+        label: string;
+        content: string;
+    }) => void;
+    /** 记忆页链接；不注入时记忆引用不显示跳转。 */
+    memoriesHref?: string;
+}
+export declare function ChatEnvironmentProvider({ value, children }: {
+    value: ChatEnvironment;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useChatEnvironment(): ChatEnvironment;
+/** 代码高亮：注入时用注入的实现，否则纯文本。 */
+export declare function useHighlightedCode(code: string, language: string | null | undefined): {
+    highlightedHtml: string | null;
+};
+export declare function useChatSessionDetail(sessionId: string | null | undefined): SessionInfo | null | undefined;
+export declare function useHideTodo(): boolean;
+export declare function useChatRenderMode(): ChatRenderMode;
+export type ChatNoticeKind = "success" | "error" | "info";
+export interface ChatNoticeOptions {
+    description?: string;
+    duration?: number;
+}
+export declare function notifyChat(environment: ChatEnvironment, kind: ChatNoticeKind, message: string, options?: ChatNoticeOptions): void;
+/**
+ * 往输入框里放东西（跟进建议、MCP 应用消息）。内置 Web 注入自己的输入框桥接；否则走
+ * `AgentSession.insertText` / `attach`，由聊天面板的输入框接住——两种宿主同一条路径。
+ */
+export declare function useComposerBridge(sessionId: string | null | undefined): {
+    appendText(text: string, separate?: boolean): void;
+    addContext(context: {
+        label: string;
+        content: string;
+    }): void;
+};
+/**
+ * 虚拟列表：注入了就用，没注入时返回空实现，`enabled` 为 false——调用方据此把全部行按常驻行渲染。
+ */
+export declare function useChatVirtualizer(options: ChatVirtualizerOptions): {
+    virtualizer: ChatVirtualizer;
+    enabled: boolean;
+};

package/dist/chat/runtime/input-cache-reset.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 换身份（登出、换账号、换后端）时清掉富输入按 client 缓存的数据（技能菜单、模型目录等），
+ * 新身份不会看到上一个身份的清单。富输入的缓存在这里登记清理函数；宿主在身份变化时调用
+ * `resetInputCaches`。放在 internal 入口，宿主调用它不必引入富输入。
+ */
+import type { BladeClient } from "@blade-hq/agent-client";
+export declare function onInputCachesReset(client: BladeClient, reset: () => void): () => void;
+export declare function resetInputCaches(client: BladeClient): void;

package/dist/chat/runtime/input-history-storage.d.ts

@@ -0,0 +1,2 @@
+export declare function getInputHistoryGeneration(): number;
+export declare function resetInputHistoryStorage(): void;

package/dist/chat/runtime/input-services.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 富输入（`@blade-hq/agent-react/rich-input`）可替换的数据来源与宿主部件。富输入对每一项都有基于
+ * BladeClient 的默认实现（插件侧栏直接用默认）；内置 Web 只在要和自己的 React Query 缓存、
+ * 全局 store 打通的地方覆盖，或补上只有它有的部件（远程电脑、外部账号）。
+ *
+ * 这个上下文放在 internal 入口：内置 Web 在应用根部提供它，不必为此引入富输入的依赖。
+ * hook 形式的注入点必须是稳定引用（模块常量），输入框无条件调用。
+ */
+import type { BackgroundTask, ConnectionStatus, SessionContextStats } from "@blade-hq/agent-client/internal";
+import { type ComponentType, type ReactNode } from "react";
+/** 模型目录（`GET /api/config/models`）。 */
+export interface InputModelOption {
+    id: string;
+    label: string;
+    inputModalities?: string[];
+    supportsImage?: boolean;
+    thinkingAvailable?: boolean;
+    reasoningLevels?: string[];
+    defaultReasoningLevel?: string;
+}
+export interface InputModelCatalog {
+    models: InputModelOption[];
+    defaultModel: string;
+    thinkingAvailable: boolean;
+    unavailableProviderIds: string[];
+    unavailableModelIds: string[];
+    isLoading: boolean;
+    isFetching: boolean;
+    refresh: () => Promise<void>;
+}
+export interface InputModelPreferences {
+    /** 用户上次选的模型（新建会话时优先用）。 */
+    preferredModel: string | null;
+    setPreferredModel: (modelId: string) => void;
+    /** 各模型上次选的推理强度（模型 id → 档位）。 */
+    reasoningLevels: Record<string, string>;
+    setReasoningLevel: (modelId: string, level: string) => void;
+}
+/** 偏好里存的是 JSON 字符串（模型 id → 档位）；坏数据当作没有。 */
+export declare function parseModelReasoningLevels(value: string | null | undefined): Record<string, string>;
+export interface InputSessionSkill {
+    skill_id: string;
+    display_name?: string | null;
+    description: string;
+    local: boolean;
+    builtin?: boolean;
+}
+export interface InputSkillStats {
+    loaded_skill_count: number;
+    loaded_skill_names: string[];
+    remote_configured: boolean;
+    remote_connected: boolean;
+    installed_skill_count: number;
+}
+export interface InputConnection {
+    status: ConnectionStatus;
+    /** 正在第几次重连（0 表示没有在重连）。 */
+    reconnectAttempt: number;
+    hasEverConnected: boolean;
+}
+export interface InputDataState<T> {
+    data: T | undefined;
+    loading: boolean;
+    error: unknown;
+}
+export interface ConnectorComputerSectionProps {
+    sessionId: string | null;
+    query: string;
+    pendingSelection?: string[];
+    onPendingSelectionChange?: (ids: string[]) => void;
+    /** 收起连接器面板（打开设置之类的动作前调用）。 */
+    closePanel: () => void;
+}
+export interface RichInputServices {
+    useModelCatalog?: () => InputModelCatalog;
+    useModelPreferences?: () => InputModelPreferences;
+    /** 知识库清单（`@` 菜单打开时才调用）。 */
+    /** 语音是否可用（部署可以关掉）；默认不可用，不显示麦克风。 */
+    voiceEnabled?: boolean;
+    /** 语音的 AudioWorklet 脚本地址。 */
+    voiceWorkletUrl?: string;
+    /** 连接状态；默认读当前会话的连接状态（没有会话时视为已连接）。 */
+    useConnection?: (sessionId: string | null) => InputConnection;
+    useSessionSkills?: (sessionId: string | null) => InputDataState<InputSessionSkill[]>;
+    useSkillStats?: (sessionId: string | null) => InputDataState<InputSkillStats>;
+    useContextStats?: (sessionId: string | null) => InputDataState<SessionContextStats>;
+    useBackgroundTasks?: (sessionId: string | null) => InputDataState<BackgroundTask[]>;
+    /** 宿主在这些变化后刷新自己的缓存（文件树、技能状态）。 */
+    useSessionDataInvalidation?: () => {
+        filesUploaded: (sessionId: string) => void;
+        pluginsChanged: (sessionId: string) => void;
+    };
+    /** 连接器面板里的「电脑」分区；不提供时不显示。 */
+    ConnectorComputerSection?: ComponentType<ConnectorComputerSectionProps>;
+    /** 连接器面板里的「外部账号」分区；不提供时不显示。 */
+    ConnectorAccountsSection?: ComponentType<{
+        query: string;
+        closePanel: () => void;
+    }>;
+}
+export declare function RichInputServicesProvider({ value, children }: {
+    value: RichInputServices;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useRichInputServices(): RichInputServices;

package/dist/chat/runtime/session-source.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 聊天组件读会话状态的来源。组件只认 `AgentSession`，不关心实例由谁持有：
+ * 内置 Web 用自己的会话登记表（含静态会话、保留区），SDK 的 ChatView / `<blade-chat>` / 插件
+ * 用 `useAgentSession` 持有的那一个实例（`createSingleSessionSource`）。
+ */
+import { type AgentSession, type SessionState } from "@blade-hq/agent-client/internal";
+import { type ReactNode } from "react";
+export interface SessionSource {
+    subscribe(listener: () => void): () => void;
+    getSession(sessionId: string | null | undefined): AgentSession | undefined;
+    /** 首次进入会话、历史还没就绪（刚创建的会话不算）。 */
+    isHistoryLoading(sessionId: string | null | undefined): boolean;
+    /** 计划实时揭示计数：只在实时成功的 update_plan 后递增，任务进度面板据此自动展开。 */
+    planRevealRevision(sessionId: string | null | undefined): number;
+    /**
+     * 在会话就绪（历史与订阅都加载完）后执行动作。来源里的实例可能在首次加载完成前就已可见，
+     * 这时直接发送会拿着空状态判断（比如看不到正在等回答的子提问）。不提供时来源里的实例总是就绪的。
+     */
+    whenReady?<T>(sessionId: string, run: (session: AgentSession) => Promise<T>): Promise<T>;
+}
+export declare function SessionSourceProvider({ source, children }: {
+    source: SessionSource;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useSessionSource(): SessionSource;
+/**
+ * 由单个会话实例组成的来源（SDK 聊天界面、插件用）。实例还没就绪时传 null；
+ * `loading` 表示正在连接或加载历史。
+ */
+export declare function useSingleSessionSource(session: AgentSession | null, loading: boolean): SessionSource;
+/** 会话实例（给动作用），不订阅状态变化。 */
+export declare function useSessionHandle(sessionId: string | null | undefined): AgentSession | null;
+/**
+ * 读一小块会话状态；会话还没有实例时对空状态求值。
+ *
+ * selector 应直接返回 SessionState 里的字段或基本值（引用在未变化时稳定）；需要派生数组 / 对象时
+ * 在组件里用 useMemo 基于返回值派生，否则每次状态变化都会产生新引用、触发重渲染。
+ */
+export declare function useSessionState<T>(sessionId: string | null | undefined, selector: (state: SessionState) => T): T;
+/** 首次进入会话、历史还在加载。 */
+export declare function useIsSessionHistoryLoading(sessionId: string | null | undefined): boolean;
+/** 计划实时揭示计数。 */
+export declare function usePlanRevealRevision(sessionId: string | null | undefined): number;
+/** 当前聊天面板对应的会话；叶子组件没拿到 sessionId prop 时用它兜底。 */
+export declare function CurrentChatSessionProvider({ sessionId, children }: {
+    sessionId: string | null;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useCurrentChatSessionId(): string | null;

package/dist/chat/runtime/use-chat-actions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 聊天面板的动作与交互态：发送（等待回答时自动当作作答）、停止（带「停止中」）、等待消息队列命令
+ * （冲突提示与进行中的条目）。全部直接作用在会话实例上。
+ */
+import type { MessageContent } from "@blade-hq/agent-client/internal";
+import { type ChatSendExtras } from "./actions";
+export declare function useChatActions(sessionId: string): {
+    isStopping: boolean;
+    send: (msg: MessageContent, targetMode?: string, askuserAnswer?: Record<string, unknown>, options?: ChatSendExtras) => Promise<boolean>;
+    stop: () => Promise<void>;
+    queueNotice: string | null;
+    pendingQueueItemId: string | null;
+    queueMessage: (content: string) => Promise<boolean>;
+    updateQueuedMessage: (itemId: string, expectedVersion: number, content: string) => Promise<boolean>;
+    reorderQueuedMessages: (expectedRevision: number, orderedIds: string[]) => Promise<boolean>;
+    cancelQueuedMessage: (itemId: string, expectedVersion?: number) => Promise<boolean>;
+    deliverQueuedMessage: (itemId: string, expectedVersion: number) => Promise<boolean>;
+    resumeQueue: () => Promise<boolean>;
+};

package/dist/chat/runtime/use-session-replay.d.ts

@@ -0,0 +1,16 @@
+import { type ReplaySpeed } from "@blade-hq/agent-client/internal";
+export interface UseSessionReplayResult {
+    isReplay: boolean;
+    /** 能不能改回放（owner 专属）。只读身份仍然看得到"在回放"，但不能操作。 */
+    canControl: boolean;
+    speed: ReplaySpeed;
+    setSpeed: (speed: ReplaySpeed) => Promise<void>;
+    exitToAutonomous: () => Promise<void>;
+}
+/**
+ * 回放会话的状态与控制，只服务于回放条（不接管「输入对不上录制内容」的处理）。
+ *
+ * 状态与控制都来自 AgentSession（`state.replay`、`setReplaySpeed` / `exitReplay`，控制请求在会话实例里
+ * 串行执行，晚到的旧响应不会把已经退出的会话又显示成回放中）。
+ */
+export declare function useSessionReplay(sessionId: string | null | undefined): UseSessionReplayResult;