@blade-hq/agent-react 2610.0.0-beta.30 → 2610.0.0-beta.32

package/README.md

@@ -57,6 +57,7 @@ const client = useBladeClient() // 当前 Provider 的 BladeClient
 const { session, state, error } = useAgentSession(sessionId, {
   createOptions,        // 不传 sessionId 时的建会话配置（UseAgentSessionOptions）
   onSessionCreated: (id) => saveSomewhere(id),
+  onSessionConnected: (session) => session.on("toolResult", handleResult),
 })
 
 state?.messages     // ChatMessage[]，直接渲染
@@ -70,6 +71,7 @@ await session?.send("你好")
 
 - 优先级：`sessionId`（连接既有会话）> `createOptions`（按配置新建）> 默认新建。
 - 自动创建只发生一次（含 React StrictMode 双跑）；创建出的 id 通过 `onSessionCreated` 交还，重挂载时把它作为 `sessionId` 传回即可复用会话。
+- 必须覆盖连接窗口内事件时，用 `onSessionConnected` 在历史加载和房间订阅开始前完成订阅，并返回取消订阅函数。
 - 同一 `sessionId` 的多次调用复用同一 `AgentSession` 实例（引用计数）；卸载后延迟释放，路由抖动不会断连。
 
 ## useReplay
@@ -156,7 +158,12 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 
 全部 props 见 `ChatViewProps`。样式说明：
 
-`ChatView` 的普通展示模式不显示只供诊断的项目说明、可用能力和当前工作环境。需要自建诊断界面时，可直接使用独立的 `ContextCard`，属性见 `ContextCardProps`；状态到文案的映射来自 agent-client 的 `getContextDisplayState`，不需要接入方重复判断。底层数据类型为 `ContextProjectionData` / `ContextProjectionFields`，展示结果为 `ContextDisplayState`，并保留 `ContextAction`、`ContextSourceInfo` 和 `contextProjectionData` 给 headless 消费方。
+智能体调用 `update_plan` 新增或更新任务时，`ChatView` 会在输入框上方自动展开最新任务进度，
+5 秒后平滑收起；连续更新会重新计时，用户手动展开或收起后以用户选择为准。自建聊天布局可直接
+使用 `CurrentPlanPanel` / `PlanUpdateBlock`，或用 `getPlanUpdateDisplayState`、
+`parsePlanUpdate` 和 `pickCurrentPlanStep` 复用同一套判定。
+
+`ChatView` 的普通展示模式不显示只供诊断的项目说明、可用能力和当前工作环境。需要自建诊断界面时，可直接使用独立的 `ContextCard`，属性见 `ContextCardProps`；状态到文案的映射来自 agent-client 的 `getContextDisplayState`，不需要接入方重复判断。一次输入通常会同时注入十几项上下文，把渲染序列里连续的几项用 `ContextGroupCard`（属性见 `ContextGroupCardProps`）折成一行更合适；哪几项算一组由 agent-client 的 `groupAdjacentContextRuns` 判定，折叠行文案来自 `getContextGroupDisplayState` / `ContextGroupDisplayState`。底层数据类型为 `ContextProjectionData` / `ContextProjectionFields`，展示结果为 `ContextDisplayState`，并保留 `ContextAction`、`ContextSourceInfo` 和 `contextProjectionData` 给 headless 消费方。
 
 记忆引用提示可通过 `MemoryRefsHint` 展示，`collectMemoryRefs` 用于从一轮消息中聚合引用，保证宿主自定义消息布局与 SDK 默认界面保持一致。
 
@@ -272,6 +279,22 @@ models.filter((m) => m.serviceModelId)
 <MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
 ```
 
+`normalizeAdjacentUrlFormatting` 可在复用其他 Markdown 渲染器前，保护紧贴行内格式标记的 URL。
+
+## Canonical 引用消息
+
+`ChatView` 会自动识别 ship-attack 会话中的 `[引用]` / `[用户输入]` canonical
+消息，并按原顺序展示引用来源、快照和用户输入。自建消息列表时可用
+`parseWhatIfPrompt` 解析同一格式，再交给 `WhatIfUserBubble` 渲染；
+`onQuoteClick` 可接入宿主的步骤跳转。
+
+```tsx
+const parsed = parseWhatIfPrompt(messageText)
+return parsed ? (
+  <WhatIfUserBubble parsed={parsed} onQuoteClick={jumpToStep} />
+) : null
+```
+
 ## isAgentComputerCommand / isAgentComputerToolCall / classifyAgentComputerLaunchOutcome
 
 判断智能体是否在沙盒里启动了通用 GUI 应用镜像（`computer launch`）——后端 blade-agent 通过 `computer` CLI 驱动一块虚拟屏幕运行任意 GUI 软件，这些函数用于自行接入方判断要不要展示对应的实时画面入口（比如自建一个类似「电脑镜像」的标签页）。当前 SDK 侧还没有内置这块 UI，只导出判定规则，避免各接入方重新猜一遍匹配逻辑。
@@ -340,4 +363,4 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 为方便单包引入，本包 re-export 了 agent-client 的全部公开声明（`BladeClient`、`AgentSession`、`SessionState`、协议类型等），文档一律见 [agent-client 的 README](../agent-client/README.md)。完整签名见 [public-api.md](./public-api.md)。
 
-本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`CurrentPlanPanel`、`PlanUpdateBlock`、`PlanUpdateData`、`PlanUpdateDisplayState`、`PlanStepStatus`、`getPlanUpdateDisplayState`、`isPlanUpdateTool`、`parsePlanUpdate`、`pickCurrentPlanStep`、`PLAN_AUTO_COLLAPSE_MS`、`MarkdownContent`、`MarkdownContentProps`、`parseWhatIfPrompt`、`ParsedWhatIfPrompt`、`WhatIfQuote`、`WhatIfUserBubble`、`WhatIfUserBubbleProps`。

package/dist/components/AssistantTurnBlock.d.ts

@@ -7,6 +7,8 @@ interface Props {
     onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
     sessionStatus?: string;
     toolCallRenderer?: ToolCallRenderer;
+    /** Agent 模式把 update_plan 收口到输入框上方的任务面板；纯 LLM 同名工具照常展示。 */
+    hidePlanUpdateTools?: boolean;
     /** 会话 id；传给 Markdown 渲染的统一上下文。 */
     sessionId?: string;
 }
@@ -22,7 +24,7 @@ export declare function getExecutionDurationMs({ messages, isStreaming, now, }:
     now?: number;
 }): number;
 /** 一轮助手回复：执行过程默认折叠，最终正文始终显示在摘要下方。 */
-export declare function AssistantTurnBlock({ messages, isStreaming, askAnswers, onAnswer, sessionStatus, toolCallRenderer, sessionId, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function AssistantTurnBlock({ messages, isStreaming, askAnswers, onAnswer, sessionStatus, toolCallRenderer, hidePlanUpdateTools, sessionId, }: Props): import("react/jsx-runtime").JSX.Element;
 export declare function collectMemoryRefs(messages: ChatMessage[]): MemoryRefInfo[];
 export declare function MemoryRefsHint({ refs }: {
     refs: MemoryRefInfo[];

package/dist/components/ChatSurface.d.ts

@@ -55,6 +55,10 @@ interface ChatSurfaceProps extends ChatPresentationProps {
     onResultFeedbackSaved?: (feedback: ResultFeedback) => void;
     /** 输入框上方的内部区域（纯 LLM 模式的高级设置用）。不传时不渲染任何节点。 */
     beforeInput?: ReactNode;
+    /** 仅 Agent 模式启用 Blade 的 update_plan 面板。 */
+    showPlanUpdates?: boolean;
+    /** 仅实时成功的 update_plan 递增；历史 hydration 不得改变。 */
+    planRevealRevision?: number;
     /** 连接状态条下方的横幅（回放模式条用）。不传时不渲染任何节点。 */
     banner?: ReactNode;
 }
@@ -64,5 +68,5 @@ interface ChatSurfaceProps extends ChatPresentationProps {
  * 这里的 DOM 结构受 tests/chat-view-compat.test.tsx 的快照保护——接入方拿
  * .blade-chat-* 类名写了自己的样式，结构一动他们的页面就歪。
  */
-export declare function ChatSurface({ theme, classNames, renderers, slots, placeholder, connection, errorMessage, messages, postChatFollowup, isStreaming, isStopping, inputText, onInputChange, onSuggestion, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, isViewer, resultFeedbackByEntry, onResultFeedbackSaved, onFollowupInteraction, beforeInput, banner, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatSurface({ theme, classNames, renderers, slots, placeholder, connection, errorMessage, messages, postChatFollowup, isStreaming, isStopping, inputText, onInputChange, onSuggestion, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, isViewer, resultFeedbackByEntry, onResultFeedbackSaved, onFollowupInteraction, beforeInput, showPlanUpdates, planRevealRevision, banner, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ContextCard.d.ts

@@ -5,3 +5,16 @@ export interface ContextCardProps {
 }
 /** Business-facing Context summary. Native details keeps every card collapsed by default. */
 export declare function ContextCard({ context, className }: ContextCardProps): import("react/jsx-runtime").JSX.Element;
+export interface ContextGroupCardProps {
+    contexts: readonly ContextProjectionData[];
+    className?: string;
+}
+/**
+ * 一批上下文注入折叠成一行。会话首轮会一次注入十几个原子，一条一张卡片会把
+ * 真正的对话挤出屏幕。
+ *
+ * 单条和多条**共用同一个 details 外壳**，不在数量变化时切换组件：流式时第二条
+ * 到达会让这一行从单条变成多条，组件类型一换 React 就重挂 <details>，
+ * 用户刚展开的行会被收起来。同理，key 由调用方按组内第一条给，不能带数量。
+ */
+export declare function ContextGroupCard({ contexts, className }: ContextGroupCardProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/MarkdownContent.d.ts

@@ -1,3 +1,5 @@
+/** Keep inline formatting markers from being consumed by URL autolinking. */
+export declare function normalizeAdjacentUrlFormatting(value: string): string;
 export interface MarkdownContentProps {
     children: string;
     className?: string;

package/dist/components/MessageList.d.ts

@@ -11,6 +11,7 @@ interface Props {
     askAnswers?: Record<string, AskUserAnswerData>;
     onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
     toolCallRenderer?: ToolCallRenderer;
+    hidePlanUpdateTools?: boolean;
     emptyState?: ReactNode;
     className?: string;
     /** 会话 id；传给助手消息的统一上下文。 */
@@ -24,5 +25,5 @@ interface Props {
  * 消息列表：use-stick-to-bottom 自动滚动 + 按轮次分组渲染。
  * 相比第一方版本去掉了轮次导航栏、吸顶状态条与规划摘要卡片。
  */
-export declare function MessageList({ messages, postChatFollowup, onSuggestion, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, emptyState, className, sessionId, isViewer, onFollowupInteraction, resultFeedbackByEntry, onResultFeedbackSaved, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function MessageList({ messages, postChatFollowup, onSuggestion, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, hidePlanUpdateTools, emptyState, className, sessionId, isViewer, onFollowupInteraction, resultFeedbackByEntry, onResultFeedbackSaved, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/PlanUpdateBlock.d.ts

@@ -0,0 +1,31 @@
+import type { ChatMessage, ToolCallInfo } from "@blade-hq/agent-client";
+export type PlanStepStatus = "pending" | "in_progress" | "completed";
+export interface PlanUpdateData {
+    plan: Array<{
+        step: string;
+        status: PlanStepStatus;
+    }>;
+}
+export declare const PLAN_AUTO_COLLAPSE_MS = 5000;
+export declare function isPlanUpdateTool(toolCall: Pick<ToolCallInfo, "name">): boolean;
+export interface PlanUpdateDisplayState {
+    current: ToolCallInfo | null;
+    updating: boolean;
+}
+export declare function getPlanUpdateDisplayState(messages: ChatMessage[]): PlanUpdateDisplayState;
+export declare function parsePlanUpdate(argumentsJson: string): PlanUpdateData | null;
+export declare function pickCurrentPlanStep(plan: PlanUpdateData["plan"]): PlanUpdateData["plan"][number] | null;
+export declare function PlanUpdateBlock({ toolCall, running, autoReveal, }: {
+    toolCall: ToolCallInfo;
+    running?: boolean;
+    /** 实时收到的新进度短暂展开；加载历史时保持默认收起。 */
+    autoReveal?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function CurrentPlanPanel({ messages, running, revealRevision, sessionId, className, }: {
+    messages: ChatMessage[];
+    running?: boolean;
+    /** 仅实时成功的 update_plan 递增；历史 hydration 不得改变。 */
+    revealRevision?: number;
+    sessionId?: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/UserMessageBubble.d.ts

@@ -11,7 +11,7 @@ interface UserMessageProps {
     message: UserChatMessage;
     className?: string;
 }
-/** 用户消息气泡：文本 + 图片/文件附件展示（不含第一方的预览弹窗与 what-if 徽章）。 */
+/** 用户消息气泡：文本、canonical 引用消息与图片/文件附件。 */
 export declare function UserMessageBubble({ message, className }: UserMessageProps): import("react/jsx-runtime").JSX.Element;
 /** 错误消息：居中红色提示条。 */
 export declare function ErrorMessageBlock({ message, className, }: {

package/dist/components/WhatIfUserBubble.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedWhatIfPrompt } from "../lib/whatif-prompt";
+export interface WhatIfUserBubbleProps {
+    parsed: ParsedWhatIfPrompt;
+    onQuoteClick?: (stepNumber: number) => void;
+}
+/** SDK 与内置 Web 共用的 canonical 引用消息渲染。 */
+export declare function WhatIfUserBubble({ parsed, onQuoteClick }: WhatIfUserBubbleProps): import("react/jsx-runtime").JSX.Element;

package/dist/embed/entry.d.ts

@@ -50,6 +50,8 @@ declare const BladeAgent: {
     transformSlashCommand: typeof agentClient.transformSlashCommand;
     contextProjectionData: typeof agentClient.contextProjectionData;
     getContextDisplayState: typeof agentClient.getContextDisplayState;
+    getContextGroupDisplayState: typeof agentClient.getContextGroupDisplayState;
+    groupAdjacentContextRuns: typeof agentClient.groupAdjacentContextRuns;
     latestPostChatFollowup: typeof agentClient.latestPostChatFollowup;
     DEFAULT_REPLAY_SPEED: agentClient.ReplaySpeed;
     SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{

package/dist/hooks/use-agent-session.d.ts

@@ -4,6 +4,11 @@ export interface UseAgentSessionOptions {
     createOptions?: CreateSessionRequest;
     /** 自动创建出的 sessionId 通过此回调交还调用方持有（重挂载复用的依据）。 */
     onSessionCreated?: (sessionId: string) => void;
+    /**
+     * 会话进入实时事件路由后、历史加载与房间订阅开始前同步执行。
+     * 返回的清理函数会在切换会话或卸载时执行。
+     */
+    onSessionConnected?: (session: AgentSession) => () => void;
 }
 export interface UseAgentSessionResult {
     /** 连接/创建完成前为 null。 */

package/dist/index.d.ts

@@ -16,14 +16,21 @@ export { LlmChat } from "./components/LlmChat";
 export type { LlmChatHandle, LlmChatProps } from "./components/LlmChat";
 export type { LlmAdvancedSettings, LlmOverride } from "./components/LlmAdvancedSettings";
 export { MarkdownContent } from "./components/MarkdownContent";
+export { normalizeAdjacentUrlFormatting } from "./components/MarkdownContent";
 export type { MarkdownContentProps } from "./components/MarkdownContent";
+export { WhatIfUserBubble } from "./components/WhatIfUserBubble";
+export type { WhatIfUserBubbleProps } from "./components/WhatIfUserBubble";
+export { parseWhatIfPrompt } from "./lib/whatif-prompt";
+export type { ParsedWhatIfPrompt, WhatIfQuote } from "./lib/whatif-prompt";
 export { ReplayBar } from "./components/ReplayBar";
 export type { ReplayBarProps } from "./components/ReplayBar";
 export { ReplayMismatchPrompt } from "./components/ReplayMismatchPrompt";
 export type { ReplayMismatchPromptProps } from "./components/ReplayMismatchPrompt";
 export type { ToolCallRenderer } from "./components/ToolCallBlock";
-export { ContextCard } from "./components/ContextCard";
-export type { ContextCardProps } from "./components/ContextCard";
+export { CurrentPlanPanel, getPlanUpdateDisplayState, isPlanUpdateTool, PLAN_AUTO_COLLAPSE_MS, parsePlanUpdate, pickCurrentPlanStep, PlanUpdateBlock, } from "./components/PlanUpdateBlock";
+export type { PlanStepStatus, PlanUpdateData, PlanUpdateDisplayState, } from "./components/PlanUpdateBlock";
+export { ContextCard, ContextGroupCard } from "./components/ContextCard";
+export type { ContextCardProps, ContextGroupCardProps } from "./components/ContextCard";
 export { collectMemoryRefs, MemoryRefsHint } from "./components/AssistantTurnBlock";
 export { isAgentComputerCommand, isAgentComputerToolCall, classifyAgentComputerLaunchOutcome, } from "./lib/agent-computer-command";
 export type { AgentComputerLaunchOutcome } from "./lib/agent-computer-command";