@blade-hq/agent-react 1.1.1

package/README.md

@@ -0,0 +1,142 @@
+# @blade-hq/agent-react
+
+Blade Agent 的 React 绑定：`BladeProvider` + `useAgentSession` + 开箱即用的 `ChatView` 聊天界面。支持 React 18 与 19（CI 两个版本 matrix 验证）。
+
+```bash
+pnpm add @blade-hq/agent-client @blade-hq/agent-react
+```
+
+> 注意两个包都要装：`agent-client` 是运行时依赖，只装 `agent-react` 在 pnpm 下会直接报错。
+
+## 快速开始
+
+```tsx
+import { BladeClient } from "@blade-hq/agent-client"
+import { BladeProvider, ChatView } from "@blade-hq/agent-react"
+import "@blade-hq/agent-react/style.css"
+
+const client = new BladeClient({ baseUrl: "https://blade.example.com" })
+
+export function App() {
+  return (
+    <BladeProvider client={client}>
+      <ChatView />
+    </BladeProvider>
+  )
+}
+```
+
+- 不传 `sessionId` 自动创建新会话；未登录时 `ChatView` 自己渲染登录按钮（弹窗授权，见 agent-client 的 `client.auth.login()`）。
+- 同一 `BladeProvider` 下可以放多个 `ChatView`，各自独立会话、互不干扰。
+- SDK 与 Server 版本不匹配时（见 agent-client「版本握手」），`ChatView` 会渲染可读的版本提示卡，而不是空白或报错堆栈。
+
+## BladeProvider
+
+只负责 client 级共享（一条 Socket 连接、一份鉴权），不含任何全局状态。
+
+```tsx
+<BladeProvider client={client}>{children}</BladeProvider>
+```
+
+Props 见 `BladeProviderProps`；在 Provider 外调用本包任何 hook 都会抛错。
+
+## useBladeClient
+
+```tsx
+const client = useBladeClient() // 当前 Provider 的 BladeClient
+```
+
+## useAgentSession
+
+自建 UI 的入口：连接（或创建）会话并订阅其状态，内部使用 `useSyncExternalStore`。
+
+```tsx
+const { session, state, error } = useAgentSession(sessionId, {
+  createOptions,        // 不传 sessionId 时的建会话配置（UseAgentSessionOptions）
+  onSessionCreated: (id) => saveSomewhere(id),
+})
+
+state?.messages     // ChatMessage[]，直接渲染
+state?.isStreaming  // 是否正在流式回复
+await session?.send("你好")
+```
+
+返回值见 `UseAgentSessionResult`。语义要点：
+
+- 优先级：`sessionId`（连接既有会话）> `createOptions`（按配置新建）> 默认新建。
+- 自动创建只发生一次（含 React StrictMode 双跑）；创建出的 id 通过 `onSessionCreated` 交还，重挂载时把它作为 `sessionId` 传回即可复用会话。
+- 同一 `sessionId` 的多次调用复用同一 `AgentSession` 实例（引用计数）；卸载后延迟释放，路由抖动不会断连。
+
+## ChatView
+
+完整聊天界面：消息列表（Markdown、代码高亮、工具调用、提问卡片）+ 输入框 + 连接状态条 + 登录引导。
+
+```tsx
+<ChatView
+  sessionId={id}                       // 可选；不传自动建会话
+  createOptions={{ intent: "..." }}    // 自动建会话时的配置
+  onSessionCreated={(id) => ...}       // 自动创建的会话 id 交还调用方
+  onSessionReady={(session) => ...}    // 会话实例就绪（页面协作高级用法）
+  commands={{ "map.highlight": (data) => map.highlight(data) }}  // 智能体 → 页面指令
+  placeholder="输入消息..."
+  classNames={{ root: "...", banner: "...", messages: "...", input: "..." }}  // ChatViewClassNames
+  renderers={{ toolCall: (info) => <MyToolCard info={info} /> }}              // ChatViewRenderers
+  slots={{ header: <MyHeader />, emptyState: <MyEmpty />, footer: <MyTip /> }} // ChatViewSlots
+/>
+```
+
+全部 props 见 `ChatViewProps`。样式说明：
+
+- 必须引入 `@blade-hq/agent-react/style.css`。组件自带 `.blade-chat-*` 前缀的自包含样式，宿主没装 Tailwind 也开箱可用；颜色走 CSS 变量，可整体换肤/暗色。
+- `renderers.toolCall` 返回 `null` 时回落到默认工具卡片。
+
+## MarkdownContent
+
+单独渲染一段智能体消息 Markdown（含代码复制按钮、XSS 消毒，不支持 raw HTML）：
+
+```tsx
+<MarkdownContent content={markdownText} />
+```
+
+## 选择模型
+
+SDK 的 ChatView / `<blade-chat>` 不内置模型选择器（默认用后端配置的模型）。指定模型有两种方式：
+
+- **建会话时指定**（React）：`<ChatView createOptions={{ model: "..." }} />`
+- **`<blade-chat>` 属性**（纯 HTML / Vue）：`<blade-chat base-url="..." model="..."></blade-chat>`
+- **自建 UI 时逐条覆盖**：`chat.send(text, { model: "..." })`
+
+可用模型清单由后端提供，接入方对照后端 Swagger（`<baseUrl>/docs`）自行获取。
+
+## 样式定制
+
+三个层次，按需选用：
+
+1. **CSS 变量换肤**（React 与 `<blade-chat>` 通用）：所有颜色走 `--primary`、`--background`、`--muted` 等变量（完整清单见 style.css 开头）。页面直接覆盖即可穿透 Shadow DOM：
+
+```css
+blade-chat { --primary: 262 83% 58%; height: 640px; }
+```
+
+2. **classNames props**（React）：`ChatView` 的 `classNames` 把自定义 class（含你自己构建的 Tailwind 工具类）挂到根节点、消息区、输入区等关键节点上，见 `ChatViewClassNames`。
+
+3. **内嵌 `<style>`（纯 HTML / Vue）**：`<blade-chat>` 的直接 `<style>` 子元素会被注入 Shadow DOM、排在内置样式之后，可用 `.blade-chat-*` 类名做任意深度定制：
+
+```html
+<blade-chat base-url="...">
+  <style>
+    .blade-chat-user-bubble { background: #eef2ff; }
+    .blade-chat-thinking { font-size: 15px; }
+  </style>
+</blade-chat>
+```
+
+## 纯静态 HTML / Vue？
+
+不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致；详见 agent-client README 与接入文档。
+
+## 附录：re-export 自 @blade-hq/agent-client
+
+为方便单包引入，本包 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`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。

package/dist/components/AgentLoopBlock.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCallInfo } from "@blade-hq/agent-client";
+interface Props {
+    toolCall: ToolCallInfo;
+}
+/**
+ * 子智能体（fork Agent）状态块的 SDK 简化版：只展示描述、状态与最终结果，
+ * 不再嵌套渲染子循环的完整消息流（那是第一方界面的能力）。
+ */
+export declare function AgentLoopBlock({ toolCall }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/AskUserQuestionBlock.d.ts

@@ -0,0 +1,31 @@
+import type { AskUserAnswerData } from "@blade-hq/agent-client";
+interface OptionItem {
+    label: string;
+    description: string;
+}
+interface QuestionItem {
+    question: string;
+    options: OptionItem[];
+    multiSelect?: boolean;
+}
+interface SourceLoopInfo {
+    loop_name: string;
+    description: string;
+}
+export interface AskUserQuestionData {
+    questions: QuestionItem[];
+    source_loop?: SourceLoopInfo | null;
+}
+interface Props {
+    data: AskUserQuestionData;
+    answered: boolean;
+    toolCallId: string;
+    sessionStatus: string;
+    answerData?: AskUserAnswerData | undefined;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+}
+/** 提问选项卡片：单选/多选 + 自定义输入，回答通过 onAnswer 回调交还 ChatView。 */
+export declare function AskUserQuestionBlock({ data, answered, toolCallId, sessionStatus, answerData, onAnswer, }: Props): import("react/jsx-runtime").JSX.Element;
+/** 解析 AskUserQuestion 的工具结果/参数，容错 LLM 把 questions 输出为字符串的情况。 */
+export declare function parseAskUserQuestion(toolResult: string | null | undefined): AskUserQuestionData | null;
+export {};

package/dist/components/AssistantTurnBlock.d.ts

@@ -0,0 +1,16 @@
+import type { AskUserAnswerData, ChatMessage } from "@blade-hq/agent-client";
+import { type ToolCallRenderer } from "./ToolCallBlock";
+interface Props {
+    messages: ChatMessage[];
+    isStreaming?: boolean;
+    askAnswers?: Record<string, AskUserAnswerData>;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    sessionStatus?: string;
+    toolCallRenderer?: ToolCallRenderer;
+}
+/**
+ * 一轮助手回复：按消息顺序渲染 thinking 折叠块、正文 Markdown 与工具调用。
+ * 相比第一方版本去掉了紧凑/详细模式切换、文件交付卡片与内联资源 iframe。
+ */
+export declare function AssistantTurnBlock({ messages, isStreaming, askAnswers, onAnswer, sessionStatus, toolCallRenderer, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChatInput.d.ts

@@ -0,0 +1,18 @@
+interface Props {
+    /** 受控输入内容（由 ChatView 持有，便于 attach/insertText 注入）。 */
+    value: string;
+    onValueChange: (value: string) => void;
+    onSend: (text: string) => void;
+    onStop: () => void;
+    isStreaming: boolean;
+    isStopping?: boolean;
+    placeholder?: string;
+    className?: string;
+}
+/**
+ * 轻量聊天输入框：textarea（Enter 发送 / Shift+Enter 换行）+ 发送/停止按钮。
+ * 不含第一方版本的富文本编辑、@ 补全、技能菜单、语音输入与模型选择。
+ * 内容受控，session.attach() / insertText() 通过 ChatView 注入到这里。
+ */
+export declare function ChatInput({ value, onValueChange, onSend, onStop, isStreaming, isStopping, placeholder, className, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChatView.d.ts

@@ -0,0 +1,41 @@
+import type { AgentSession, CreateSessionRequest } from "@blade-hq/agent-client";
+import { type ReactNode } from "react";
+import type { ToolCallRenderer } from "./ToolCallBlock";
+export interface ChatViewClassNames {
+    root?: string;
+    banner?: string;
+    messageList?: string;
+    chatInput?: string;
+}
+export interface ChatViewRenderers {
+    /** 自定义工具调用渲染；返回 null 走默认渲染。 */
+    toolCall?: ToolCallRenderer;
+}
+export interface ChatViewSlots {
+    /** 消息列表上方的自定义区域。 */
+    header?: ReactNode;
+    /** 无消息时的空状态。 */
+    emptyState?: ReactNode;
+    /** 输入框下方的自定义区域。 */
+    footer?: ReactNode;
+}
+export interface ChatViewProps {
+    /** 连接既有会话；不传则按 createOptions 自动新建。 */
+    sessionId?: string;
+    createOptions?: CreateSessionRequest;
+    /** 自动创建出的 sessionId 通过此回调交还调用方持有。 */
+    onSessionCreated?: (sessionId: string) => void;
+    /** 会话连接完成后回调（页面协作场景拿 AgentSession 实例用）。 */
+    onSessionReady?: (session: AgentSession) => void;
+    /** 智能体下发给宿主页面的指令处理器（action → handler）。 */
+    commands?: Record<string, (data: unknown) => void>;
+    classNames?: ChatViewClassNames;
+    renderers?: ChatViewRenderers;
+    slots?: ChatViewSlots;
+    placeholder?: string;
+}
+/**
+ * 开箱即用的聊天界面：连接（或新建）一个会话，渲染消息流与输入框。
+ * 状态全部来自 useAgentSession，不依赖任何全局 store。
+ */
+export declare function ChatView(props: ChatViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ConnectionBanner.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectionStatus } from "@blade-hq/agent-client";
+interface Props {
+    connection: ConnectionStatus;
+    className?: string;
+}
+/** 连接状态提示条：数据来自 SessionState.connection，正常连接时不渲染。 */
+export declare function ConnectionBanner({ connection, className }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/MarkdownContent.d.ts

@@ -0,0 +1,16 @@
+import { type ComponentProps } from "react";
+import { Streamdown } from "streamdown";
+type StreamdownProps = ComponentProps<typeof Streamdown>;
+export interface MarkdownContentProps {
+    children: string;
+    className?: string;
+    /** 流式渲染传 "streaming"，历史静态内容默认 "static"。 */
+    mode?: StreamdownProps["mode"];
+}
+/**
+ * SDK 版 Markdown 渲染：Streamdown 默认转义/消毒（不开启任何 raw HTML），
+ * 附带代码块复制按钮；相比第一方版本去掉了 mermaid、外链确认弹窗、
+ * 会话文件卡片等第一方能力。
+ */
+export declare function MarkdownContent({ children, className, mode }: MarkdownContentProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/MessageList.d.ts

@@ -0,0 +1,19 @@
+import type { AskUserAnswerData, ChatMessage } from "@blade-hq/agent-client";
+import { type ReactNode } from "react";
+import type { ToolCallRenderer } from "./ToolCallBlock";
+interface Props {
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    sessionStatus?: string;
+    askAnswers?: Record<string, AskUserAnswerData>;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    toolCallRenderer?: ToolCallRenderer;
+    emptyState?: ReactNode;
+    className?: string;
+}
+/**
+ * 消息列表：use-stick-to-bottom 自动滚动 + 按轮次分组渲染。
+ * 相比第一方版本去掉了轮次导航栏、吸顶状态条与规划摘要卡片。
+ */
+export declare function MessageList({ messages, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, emptyState, className, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/RenderErrorBoundary.d.ts

@@ -0,0 +1,20 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+interface Props {
+    label: string;
+    details?: string;
+    resetKey?: string;
+    children: ReactNode;
+}
+interface State {
+    componentStack: string;
+    error: Error | null;
+}
+/** 消息级渲染错误边界：单条消息渲染崩溃时降级为提示卡片，不拖垮整个列表。 */
+export declare class RenderErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(prevProps: Props): void;
+    render(): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+}
+export {};

package/dist/components/Shimmer.d.ts

@@ -0,0 +1,7 @@
+interface ShimmerProps {
+    children?: string;
+    className?: string;
+}
+/** 流式等待时的呼吸文字效果（样式见 style.css 的 .blade-shimmer-text）。 */
+export declare function Shimmer({ children, className }: ShimmerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ToolCallBlock.d.ts

@@ -0,0 +1,18 @@
+import type { AskUserAnswerData, ToolCallInfo } from "@blade-hq/agent-client";
+import { type ReactNode } from "react";
+/** 接入方自定义渲染器：返回 null 时回落到默认渲染。 */
+export type ToolCallRenderer = (info: ToolCallInfo) => ReactNode | null;
+interface Props {
+    toolCall: ToolCallInfo;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    answered?: boolean;
+    answerData?: AskUserAnswerData;
+    sessionStatus?: string;
+    renderer?: ToolCallRenderer;
+}
+/**
+ * 极简工具调用块：状态 + 展示名一行，点开后是参数/结果的 <pre> 折叠展示。
+ * AskUserQuestion 特殊处理为提问选项卡片。
+ */
+export declare function ToolCallBlock({ toolCall, onAnswer, answered, answerData, sessionStatus, renderer, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/UserMessageBubble.d.ts

@@ -0,0 +1,21 @@
+import type { ChatMessage } from "@blade-hq/agent-client";
+export type UserChatMessage = ChatMessage & {
+    role: "user";
+};
+export type ErrorChatMessage = ChatMessage & {
+    role: "error";
+};
+export declare function isUserMessage(message: ChatMessage): message is UserChatMessage;
+export declare function isErrorMessage(message: ChatMessage): message is ErrorChatMessage;
+interface UserMessageProps {
+    message: UserChatMessage;
+    className?: string;
+}
+/** 用户消息气泡：文本 + 图片/文件附件展示（不含第一方的预览弹窗与 what-if 徽章）。 */
+export declare function UserMessageBubble({ message, className }: UserMessageProps): import("react/jsx-runtime").JSX.Element;
+/** 错误消息：居中红色提示条。 */
+export declare function ErrorMessageBlock({ message, className, }: {
+    message: ErrorChatMessage;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/display-utils.d.ts

@@ -0,0 +1,16 @@
+import type { ToolCallInfo } from "@blade-hq/agent-client";
+export type ToolTone = "emerald" | "blue" | "amber" | "red";
+/** 归一化工具名：去掉命名空间前缀并映射到别名表（如 "fork:Agent" → "Agent"）。 */
+export declare function formatToolName(name: string): string;
+/**
+ * 返回工具调用的中文展示标签：优先取参数里的 description，
+ * 其次取后端下发的 display_name / 系统工具中文名。
+ */
+export declare function getToolDisplayLabel(toolCall: ToolCallInfo): string;
+export declare function getToolTone(status?: ToolCallInfo["status"]): ToolTone;
+export declare function getToolStatusLabel(status?: ToolCallInfo["status"]): string;
+export declare function formatToolDuration(ms: number): string;
+/** 参数 JSON 美化：无法解析时按原文展示。 */
+export declare function formatToolArgs(args: string): string;
+/** 工具结果的文本化 + 截断：长结果只在折叠面板里展示前若干字符。 */
+export declare function formatToolResult(result: unknown): string;

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+import { type ReactNode } from "react";
+export interface BladeProviderProps {
+    client: BladeClient;
+    children: ReactNode;
+}
+/**
+ * 提供 client 级共享（一条连接、一份鉴权）。不含任何全局状态：
+ * 同一 Provider 下多个 ChatView / useAgentSession 各自独立。
+ */
+export declare function BladeProvider({ client, children }: BladeProviderProps): import("react/jsx-runtime").JSX.Element;
+/** 读取当前 BladeProvider 提供的 client。不在 Provider 内使用时抛错。 */
+export declare function useBladeClient(): BladeClient;

package/dist/embed/blade-chat-element.d.ts

@@ -0,0 +1,33 @@
+import { type AgentSession } from "@blade-hq/agent-client";
+/**
+ * `<blade-chat base-url="https://..." session-id="可选">`
+ *
+ * 纯静态页面的聊天入口：Shadow DOM 内渲染完整 ChatView，
+ * 未登录时组件自带登录引导，不传 session-id 自动建会话。
+ */
+export declare class BladeChatElement extends HTMLElement {
+    static observedAttributes: string[];
+    private root;
+    private shadow;
+    private mountPoint;
+    /** 当前会话（连接完成后可用）；BladeAgent.getChat() 依赖它。 */
+    session: AgentSession | null;
+    private sessionWaiters;
+    /** 自动创建的会话 id：attribute 变化触发的重渲染要继续用它，避免重复建会话。 */
+    private autoCreatedSessionId;
+    connectedCallback(): void;
+    /**
+     * 自定义样式口子：<blade-chat> 的直接 <style> 子元素会被拷入 Shadow DOM，
+     * 排在内置样式之后（同优先级时后者胜）。配合内置的 .blade-chat-* 类名
+     * 与 CSS 变量（--primary / --background 等，页面直接对 blade-chat 元素
+     * 设置即可穿透），无需构建工具即可深度定制。
+     */
+    private adoptUserStyles;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** 等待会话就绪（页面协作用）。 */
+    waitForSession(): Promise<AgentSession>;
+    private handleSessionReady;
+    private render;
+}
+export declare function registerBladeChatElement(): void;

package/dist/embed/entry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * blade-agent.js（IIFE）入口：纯静态 HTML 的接入方式。
+ *
+ * ```html
+ * <script src="https://blade.example.com/sdk/blade-agent.js"></script>
+ * <blade-chat base-url="https://blade.example.com"></blade-chat>
+ * <script>
+ *   const chat = await BladeAgent.getChat(document.querySelector("blade-chat"))
+ *   chat.onCommand("map.highlight", (data) => { ... })
+ * </script>
+ * ```
+ */
+import * as agentClient from "@blade-hq/agent-client";
+import type { AgentSession } from "@blade-hq/agent-client";
+import { BladeChatElement } from "./blade-chat-element";
+/** 取某个 `<blade-chat>` 元素背后的会话对象（等待连接就绪）。 */
+declare function getChat(element: Element | null): Promise<AgentSession>;
+declare const BladeAgent: {
+    BladeClient: typeof agentClient.BladeClient;
+    BladeApiError: typeof agentClient.BladeApiError;
+    VersionMismatchError: typeof agentClient.VersionMismatchError;
+    SDK_NAME: "agent-client";
+    SDK_VERSION: "2.0.0";
+    MIN_SERVER_VERSION: "1.1.1";
+    AgentSession: typeof AgentSession;
+    SessionHub: typeof agentClient.SessionHub;
+    createInitialSessionState: typeof agentClient.createInitialSessionState;
+    connectEmbedded: typeof agentClient.connectEmbedded;
+    isCommandEnvelope: typeof agentClient.isCommandEnvelope;
+    isInboundEnvelope: typeof agentClient.isInboundEnvelope;
+    buildMessageContent: typeof agentClient.buildMessageContent;
+    contentPreview: typeof agentClient.contentPreview;
+    extractTextAttachments: typeof agentClient.extractTextAttachments;
+    getFileParts: typeof agentClient.getFileParts;
+    getImageParts: typeof agentClient.getImageParts;
+    getTextContent: typeof agentClient.getTextContent;
+    groupMessagesByLoop: typeof agentClient.groupMessagesByLoop;
+    isHiddenInternalMessage: typeof agentClient.isHiddenInternalMessage;
+    normalizeMessageContent: typeof agentClient.normalizeMessageContent;
+    transformSlashCommand: typeof agentClient.transformSlashCommand;
+    SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{
+        id: string;
+        intent: string;
+        status: "completed" | "created" | "failed" | "interrupted" | "running" | "waiting_for_input";
+        created_at: string;
+        updated_at: string;
+        shared?: boolean | undefined;
+        memory_enabled?: boolean | undefined;
+        is_persistent?: boolean | undefined;
+        is_headless?: boolean | undefined;
+        viewer_role?: "owner" | "viewer" | undefined;
+        template_id?: string | null | undefined;
+        model?: string | null | undefined;
+        enable_thinking?: boolean | null | undefined;
+        solution_id?: string | null | undefined;
+        biz_role_id?: string | null | undefined;
+        solution?: unknown;
+        plan_summary?: string | null | undefined;
+        primary_skill_id?: string | null | undefined;
+        bound_skill_id?: string | null | undefined;
+        replay_state?: unknown;
+        is_pinned?: boolean | undefined;
+        pinned_at?: string | null | undefined;
+        is_example?: boolean | undefined;
+        ports?: unknown;
+        disable_tools?: string[] | undefined;
+        runtime_type?: string | null | undefined;
+        daemon_id?: string | null | undefined;
+        match?: unknown;
+    }, {}>;
+    SessionStatus: import("arktype/internal/variants/string.ts").StringType<"completed" | "created" | "failed" | "interrupted" | "running" | "waiting_for_input", {}>;
+    LayoutType: typeof agentClient.LayoutType;
+    Task: import("arktype/internal/variants/object.ts").ObjectType<{
+        id: string;
+        goal: string;
+        skills: string[];
+        depends_on: string[];
+        status: "done" | "failed" | "in_progress" | "pending" | "skipped";
+        result_summary: string;
+        number: string;
+    }, {}>;
+    TaskStatus: import("arktype/internal/variants/string.ts").StringType<"done" | "failed" | "in_progress" | "pending" | "skipped", {}>;
+    ClientProjectionBuilder: typeof agentClient.ClientProjectionBuilder;
+    createSocket: typeof agentClient.createSocket;
+    getChat: typeof getChat;
+    BladeChatElement: typeof BladeChatElement;
+};
+declare global {
+    interface Window {
+        BladeAgent: typeof BladeAgent;
+    }
+}
+export type { AgentSession };
+export { BladeAgent };

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

@@ -0,0 +1,29 @@
+import type { AgentSession, CreateSessionRequest, SessionState } from "@blade-hq/agent-client";
+export interface UseAgentSessionOptions {
+    /** 不传 sessionId 时按此配置新建会话；两者都不传则新建默认对话。 */
+    createOptions?: CreateSessionRequest;
+    /** 自动创建出的 sessionId 通过此回调交还调用方持有（重挂载复用的依据）。 */
+    onSessionCreated?: (sessionId: string) => void;
+}
+export interface UseAgentSessionResult {
+    /** 连接/创建完成前为 null。 */
+    session: AgentSession | null;
+    /** 会话状态快照；session 未就绪时为 null。 */
+    state: SessionState | null;
+    /** 连接或创建失败的错误（含 VersionMismatchError）。 */
+    error: Error | null;
+}
+/**
+ * 连接（或创建）一个会话并订阅其状态。
+ *
+ * - 优先级：sessionId（连接既有会话）> createOptions（按配置新建）> 默认新建。
+ * - 同一 sessionId 重复调用复用同一 AgentSession 实例（SessionHub 引用计数）。
+ * - 自动创建只发生一次（含 StrictMode 双跑）；创建出的 id 经 onSessionCreated
+ *   交还调用方。
+ *
+ * **连接与 sessionId 变更分离**：连接在挂载时建立、仅在卸载时释放；只有
+ * 当 sessionId 明确切到一个「与当前已连接会话不同」的 id 时才重连。这样宿主
+ * （如 Vue 把自动创建的 id 写回 `session-id` 属性）回填同一个 id 不会触发
+ * 拆–重连——否则会把正在流式的会话换成新实例、当前渲染整个丢失。
+ */
+export declare function useAgentSession(sessionId?: string, options?: UseAgentSessionOptions): UseAgentSessionResult;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { BladeProvider, useBladeClient } from "./context";
+export type { BladeProviderProps } from "./context";
+export { useAgentSession } from "./hooks/use-agent-session";
+export type { UseAgentSessionOptions, UseAgentSessionResult } from "./hooks/use-agent-session";
+export { ChatView } from "./components/ChatView";
+export type { ChatViewClassNames, ChatViewProps, ChatViewRenderers, ChatViewSlots, } from "./components/ChatView";
+export { MarkdownContent } from "./components/MarkdownContent";
+export type { MarkdownContentProps } from "./components/MarkdownContent";
+export type { ToolCallRenderer } from "./components/ToolCallBlock";
+export * from "@blade-hq/agent-client";