@blade-hq/agent-client 2610.0.0-rc.0 → 2610.0.0

package/README.md

@@ -85,6 +85,10 @@ new BladeClient({
 })
 ```
 
+高级宿主可通过 `BladeClientOptions.commandTransport(event, payload, send)` 接管带回执的命令传输，例如浏览器插件让后台持有发送请求，面板关闭后仍能等待请求结束并停止任务。返回原始服务端 ack，失败时抛错；不接管的命令调用 `send()` 使用默认 Socket.IO。事件订阅仍使用原 socket。`client.requestCommand(event, payload, timeoutMs)` 是同一通道的低层入口，普通应用继续使用类型化的 `AgentSession` 方法。
+
+底层 `createSocket` 允许指定 `transports`；MV3 service worker 没有 XMLHttpRequest，可使用 `["websocket"]`。不指定时保持 Socket.IO 默认选择。
+
 SDK 会固定订阅普通聊天所需的完整实时事件。产品内置 Web 的精简/开发者展示模式不属于
 公共 SDK 契约，也没有对应的构造参数或 Socket.IO 字段。
 
@@ -153,6 +157,8 @@ const chat = await client.sessions.create({
 
 Solution 和 Skill 都声明为 `{ path, content }[]` 文本文件；SDK 负责准备资源、创建会话和安装 Skill，成功返回时 `chat` 已可使用。已有 Solution 改传 `solution: { id, role }`。模型值是 Server 模型目录中的 ID，LLM 地址与密钥应由 Server 管理。
 
+`SkillDefinition.files` 使用 `SkillFile[]`：文本文件仍填写 `path` 和 `content`；二进制文件将内容编码为 base64，并设置 `encoding: "base64"`。自带可执行文件另设 `executable: true`。这两个可选字段适用于沙盒会话，不扩展 Solution 的 `TextFile` 格式。
+
 > **`sessionId` 从哪来？** 三种，按需选：
 > 1. **不用管它** —— 首次接入最省事：`client.sessions.create()` 直接建一个新会话，用不着 ID。React 的 `<ChatView />` 不传 `sessionId` 也一样。
 > 2. **自己建、自己存**：`const { session_id } = await client.sessions.createSessionWithRequest({ intent: "季度报表分析" })`。把返回的 `session_id`（后端是蛇形命名）存进你的数据库或 URL，用户下次进来传给 `connect(sessionId)`（前端参数是驼峰），就能接着上次的对话。
@@ -167,7 +173,81 @@ await client.sessions.getSession(id)                  // 会话详情
 await client.sessions.updateSession(id, { intent: "新标题" })
 await client.sessions.deleteSession(id)
 await client.sessions.getSessionTurns(id)             // 历史消息（投影格式，与实时流同构）
-```
+const page = await client.sessions.getSessionTurnsPage(id) // 聊天首屏 recent page
+await client.sessions.getSessionTurnsPage(id, { before: page.nextBefore! })
+// 从某条用户发言定位到最新（消息导航点窗口外的发言）：调用参数是 SessionTurnsQuery
+await client.sessions.getSessionTurnsPage(id, { fromEntryId: "entry-id" })
+// 当前分支上全部可导航的用户发言目录（entry_id + 标题 + 时间，不含消息体）
+const index = await client.sessions.getSessionTurnIndex(id) // SessionTurnIndex
+const first = index.items[0] // SessionTurnIndexItem
+```
+
+`SessionTurnsQuery` 的 `before` 与 `fromEntryId` 互斥；定位命中不了当前分支时服务端返回
+404 / 409，而不是空窗口。目录的 `entryId` 与 `/turns` 的 `turn_id` 同源，可直接当 `before` 游标。
+
+会话插件可通过 `client.sessions.listSessionPlugins(id)` 查询，并用
+`client.sessions.setSessionPluginActivation(id, name, active)` 切换当前会话。列表项为 `SessionPlugin`；修改结果为 `SessionPluginActivation`，只返回选择和准备状态，安装事实需从列表获取。
+
+账号级目录是 `client.plugins.catalog()`（`PluginsResource` 是 `client.plugins`
+的类型）。它**不依赖任何会话**，返回 `PluginCatalogEntry[]`：`name`、`display_name`、
+`icon`、`installed`。没有会话也要展示插件名称与图标的界面（例如首页的输入框连接器）
+用它，而不是先建一个会话。
+
+`icon` 是不透明的缓存 token（当前是包内容摘要），**不是路径**：把它交给
+`client.plugins.fetchIcon(name)` 取字节再转 object URL，不要拿它拼 URL，也不要把
+`<img>` 指向接口路径（token 用户会拿到 401/403）。
+
+```ts
+const { plugins } = await client.plugins.catalog()
+// plugins: PluginCatalogEntry[]
+//   name          技术 ID：路径、授权、缓存与调用一律用它
+//   display_name  包声明的业务名；null 时界面回退到 name
+//   icon          包内图标的 opaque token；null 表示没有可用图标
+//   installed     当前用户是否安装了它
+
+const blob = await client.plugins.fetchIcon(plugins[0].name)
+const url = URL.createObjectURL(blob)
+```
+
+账号电脑目录是 `client.computers.listAccount()`，返回 `AccountComputerList`。它只回答
+账号事实（登记过哪些电脑、此刻在不在线，`AccountComputer`），**不含**"本次会话能不能
+用它"——那是会话接口 (`client.computers.list`) 的回答。两者混着说，用户就会把在线当成
+已授权。
+
+插件可以在包内 `cn.com.bladeai.agent/config.schema.json` 用标准 JSON Schema
+（Draft 2020-12）声明账号、token 或任意业务配置。声明了配置的插件用
+`client.sessions.getSessionPluginConfig(id, name)` 读取声明与当前值，用
+`client.sessions.updateSessionPluginConfig(id, name, { expected_revision, set, remove })`
+保存；两者都要等到插件包已准备（即已激活过）才有内容，没有声明的插件返回
+`state: "not_required"`。
+
+```ts
+const { config } = await client.sessions.getSessionPluginConfig(id, "crm")
+// config: SessionPluginConfigState
+//   state       "not_required" | "required" | "configured" | "error"
+//   schema      包内声明的 JSON Schema（Draft 2020-12）
+//   values      已存值，writeOnly 字段已被平台剔除
+//   write_only  当前有值的秘密字段 JSON Pointer
+//   revision    乐观并发用的版本号
+//   errors      SessionPluginConfigError[]，逐条 { path, message }，不含用户输入
+// 列表项 SessionPlugin.config 是 SessionPluginConfigSummary
+// （SessionPluginConfigStateName 之外多一个 "unchecked"：列表只报本地已知事实，
+// 不伪报已配置）
+
+await client.sessions.updateSessionPluginConfig(id, "crm", {
+  expected_revision: config.revision,
+  set: [{ path: "/login/password", value: password }], // SessionPluginConfigSet[]
+  remove: [],
+} satisfies SessionPluginConfigUpdate)
+```
+
+图标用 `client.sessions.fetchSessionPluginIcon(id, name)` 取 `Blob`（自带凭据），
+或 `client.sessions.sessionPluginIconUrl(id, name)` 取已鉴权 URL。
+
+`set`/`remove` 只表达显式改动：没出现的字段保持原值，因此表单不需要回传秘密；
+`null` 是一个合法值，不是删除。校验不通过或版本过期时请求被拒绝，磁盘上的旧
+配置保持不变。平台只写用户 Home 下的 `~/.plugin/<plugin_id>/config.json`，不会
+重启 MCP、清缓存或刷新 token。
 
 ### 会话回放（演示 / 彩排）
 
@@ -314,13 +394,30 @@ await client.computers.setEnabled(sessionId, computer.id, false)  // 停用
 做电脑选择器时用这几个纯函数，别自己重算状态：
 
 ```ts
-import { canToggleComputer, computerState, sortComputers } from "@blade-hq/agent-client"
+import {
+  canToggleComputer, computerState, sortComputers,
+  computerOS, computerPlatformLabel, computerDaemonVersion,
+} from "@blade-hq/agent-client"
+
+sortComputers(computers)         // 按接入时间，顺序稳定不随状态变化
+computerState(computer)          // ComputerState: "primary" | "enabled" | "offline" | "idle"
+canToggleComputer(computer)      // 主运行时返回 false
 
-sortComputers(computers)      // 可用的在前，其次在线的，最后按名字
-computerState(computer)       // ComputerState: "primary" | "enabled" | "offline" | "idle"
-canToggleComputer(computer)   // 主运行时返回 false
+computerOS(computer)             // ComputerOS: "macos" | "windows" | "linux" | "unknown"
+computerPlatformLabel(computer)  // "darwin/arm64"
+computerDaemonVersion(computer)  // "dev (bc3ad71d1)"，未知时是空串
 ```
 
+`sortComputers` **刻意不按在线/可用排序**：那样排看着"手边的在前面"，代价是电脑
+上下线、勾选状态一变整个列表就重排，用户正要点的那一项会在手指底下跑掉。改名也
+不会挪位置，新接入的稳定排在末尾。
+
+`computerOS` 判定的是 daemon 上报的 `runtime.GOOS`，各处自己 `startsWith` 一遍必然会分叉；
+图标怎么画交给界面，这里只回答"是哪一类系统"。
+
+`computerDaemonVersion` 返回的是服务端存的完整串——dev 构建带 commit，
+因为 dev 的版本号全都是 `dev`，光看它分不出是哪次构建的二进制。**不要在前端另拼一套格式。**
+
 `ComputersResource` 是 `client.computers` 的类型。
 
 ## AgentSession
@@ -340,7 +437,9 @@ chat.getState()
 //   connection,      连接状态："connected" | "connecting" | "reconnecting" | "disconnected"
 //   errorMessage,    最近一次运行错误
 //   replay,          回放状态：{ isReplay, speed, sourceSessionId } | null
+//   queue,           等待消息队列快照：{ session_id, revision, paused, pause_reason, items }
 //   viewerRole,      "owner" | "viewer" | null（只读身份改不动会话）
+//   nextBefore, loadingOlder,  历史分页游标与加载状态
 //   turns, askAnswers, agentLoops, activeCompaction   进阶字段
 // }
 
@@ -354,9 +453,10 @@ const unsubscribe = chat.subscribe(() => rerender(chat.getState()))
 ```ts
 const accepted = await chat.send("你好")         // 服务端接受后为 true；拒绝时为 false
 await chat.send("换个方案", { mode: "planning" }) // 指定模式/模型等选项
-chat.append("补充：预算不超过 5 万")              // 智能体运行中追加说明
-await chat.stop()                                // 停止当前回复
+await chat.queueMessage("补充：预算不超过 5 万")   // 运行中入队；返回服务端确认结果与冲突原因
+await chat.stop()                                // 停止当前回复（同时暂停队列，需 resumeQueue 继续）
 await chat.compact()                             // 手动压缩上下文
+if (chat.hasOlderHistory) await chat.loadOlderHistory()
 chat.dispose()                                   // 彻底释放（什么时候该调见下方说明）
 ```
 
@@ -364,6 +464,28 @@ chat.dispose()                                   // 彻底释放（什么时候
 > 1. 用户明确关闭或删除了这个会话，之后不会再回来；
 > 2. 页面长期开着并且会不断创建一次性会话（比如批量任务面板），需要主动回收。
 
+### 等待消息队列
+
+队列由服务端持久化：运行中发送、暂停期间发送都进入队尾，按顺序逐条执行；关掉页面不影响已确认的入队，重新打开恢复真实状态。等待消息**不会**提前伪装成聊天记录——它只在队列区域展示，真正被接收后才进入消息流。
+
+```ts
+const result = await chat.queueMessage("顺便看下这个报错") // 入队（运行中排队 / 暂停期间照常入队）
+// result: { ok, conflict, snapshot, message }
+
+await chat.updateQueuedMessage(item.id, item.version, "改好的正文")
+await chat.reorderQueuedMessages(queue.revision, pendingIdsInNewOrder) // ordered_ids 必须是当前 pending 条目 id 的完整集合
+await chat.cancelQueuedMessage(item.id, item.version)
+await chat.deliverQueuedMessage(item.id, item.version) // 立即补充：交给当前运行在下一个接收点消费
+await chat.resumeQueue()   // 暂停后继续执行
+await chat.refreshQueue()  // 手动拉一份权威快照（首次连接与每次重连已自动拉取）
+```
+
+`chat.getState().queue` 是 `SessionQueueSnapshot`：`{ session_id, revision, paused, pause_reason, items }`。它只会被 revision 更新的快照替换——乱序到达的旧广播不会把新状态顶回去。`items` 只包含 `pending`（待执行）与 `delivering`（等待接收）。
+
+- **冲突处理**：`conflict` 表示乐观并发或状态校验失败，服务端快照已自动刷新到本地，此时保留用户草稿并说明原因即可；`ok=false` 且 `snapshot` 为 null（例如鉴权失败）时不要改动本地队列。`queueMessage` 结果未知（ack 超时）时会用同一个 `client_request_id` 重试一次，不会制造第二条。
+- **可操作性判定**：`canEditQueuedMessage` / `canCancelQueuedMessage` / `canDeliverQueuedMessage` 只对 `pending` 返回 true；文案用 `queuedMessageStatusLabel` 与 `queuePauseReasonLabel`。
+- **自己处理广播**：需要绕过状态机时用 `isSessionQueueSnapshot` + `shouldApplySnapshot` + `EMPTY_SESSION_QUEUE`；解析自定义 ack 用 `parseQueueAck`，返回统一的 `QueueOperationResult`（`QueueAck` 是 ack 的线格式；`code` 是路由失败原因，供调用方决定是否重试）。
+
 ### 页面协作：让智能体和你的页面互动
 
 **页面状态与业务后端 → 智能体**：
@@ -428,11 +550,15 @@ chat.on("toolCall",   (e) => console.log("调用工具", e.toolCall.name))
 chat.on("toolResult", (e) => console.log("工具结果", e.toolCall.result))
 chat.on("message",    (e) => console.log("新消息", e.message))
 chat.on("chatEnd",    (e) => console.log("回复结束", e.status))
-chat.on("error",      (e) => console.error(e.message))
+chat.on("error",      (e) => console.error(e.message, e.code))
 ```
 
+`error` 的 `message` 是可以直接展示的业务文案；`code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken` / `owner_busy`），调用方据此决定要不要提示重试，不要解析 `message`。同一组原因也以 `AgentSessionError.code` 的形式抛出（`send()` 这类只回布尔值的入口从 `error` 事件拿），队列 API 则通过 `QueueOperationResult.code` 给出。
+
 完整事件表见 `AgentSessionEvents` 类型定义（含 `modeChange` / `workspaceChanged` / `artifact` / `notification` / `backgroundTask` / `taskListUpdated` / `rewind` / `replayMismatch` 等）。`toolResult.source` 区分实时结果、首次连接回放和断线重连回放；`on()` 返回取消函数，handler 抛异常只告警、不影响会话。
 
+分页响应是 `SessionTurnsPage`，其中 `nextBefore: string | null` 是唯一的“还有更早历史”真值。历史页面指令通过独立的 `HistoricalCommand` 日志恢复，不混进展示页。自定义状态容器可复用 `prependOlder`、`replaceWindow` 与 `LiveRevisionState`，但一般直接使用 `AgentSession` 即可。
+
 ## iframe 嵌入形态：connectEmbedded
 
 如果你不是嵌组件，而是把 **Blade 的聊天页面整个用 iframe 嵌进自己系统**，宿主页面用 `connectEmbedded` 拿到同构的协作 API：
@@ -476,6 +602,15 @@ PATCH / query / FormData / AbortSignal 等完整 HTTP 语义（否则不够用
 > **安全约束**：`client.token` 只应发往 `baseUrl` 同源的接口。不要把它附加到
 > 第三方域名的请求上——那等于把用户的访问凭据交给别人。
 
+### 只读轮询退避
+
+`new PollingBackoff(3000)` 为轮询维护独立退避状态，参数为正常间隔（大于 0、不超过 60 秒）。
+请求成功后调用 `reset()`，失败后调用 `failed(error)`；`waitMs()` 返回剩余等待毫秒数，
+`0` 表示可以请求，`false` 表示停止。HTTP 错误应传入保留响应头的 `BladeApiError`。
+401/403 等确定性错误停止，网络/5xx 指数退避带抖动且最高 60 秒；`Retry-After`
+可以要求更长等待，超出浏览器定时器范围时停止。策略自身不发送请求，调度器须传递
+AbortSignal、在卸载时停止，并避免将它用于自动重放 POST 等有副作用的操作。
+
 ## headless：一次性问答
 
 ```ts
@@ -561,6 +696,41 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 
 不传第三个参数时按本地已有处理，和不带这个参数的老用法结果一致。
 
+### MCP App 卡片
+
+MCP 工具可以通过 `_meta.ui` 在消息流里产出交互卡片（`tool_ui` block）。卡片的
+实例、守卫、可见性、身份和终态规则全部收敛在这一份共享判定里——内置 Web 与
+SDK 渲染的是同一批卡片，不要自己再写一份判断：
+
+```ts
+import {
+  collectInlineToolUiCards,
+  collectPreviewToolUiCards,
+  resolveToolUiCardContent,
+  buildToolUiCardKey,
+  isToolUiCard,
+} from "@blade-hq/agent-client"
+
+// 按可见性分类：inline 进消息流，preview 交给你的侧栏/面板（也随 toolPreview 事件推送）
+const inlineCards = collectInlineToolUiCards(messages)   // [{ key, toolCallId, card }]
+const previewCards = collectPreviewToolUiCards(messages) // [{ key, toolCall, card, blocks }]
+
+// 渲染前解析实际内容；archived 留档卡片只用留档 HTML，绝不回退 resourceUri
+// （历史恢复/刷新不会因此重放一次 MCP 资源读取）
+const resolved = resolveToolUiCardContent(card) // { type: "resource-html" | "resource-uri" | "resource-file", content } | null
+
+// 文件卡片按 sourcePath、URI 按地址、无来源 HTML 按 toolCallId 去重。
+// 宿主可先按会话 workspace 将 sourcePath 归一，和文件树中的身份对齐。
+const key = buildToolUiCardKey(toolCallId, resolved.type, resolved.content, card.sourcePath)
+```
+
+`resource-file` 来自 `blade ui --html 文件 --preview`：`content`/`sourcePath` 是文件路径，不是 HTML。打开时通过带鉴权的会话文件接口读取当前文件；历史引用也读取最新文件。每次新工具调用都会发 `toolPreview` 通知文件有更新，宿主仍按路径复用一个页签；同次调用的重复事件不重复发送。已打开的 HTML 应保留当前页面和交互状态，提供醒目的“刷新”按钮，让用户决定何时读取最新内容。内联卡片继续使用 HTML 快照。
+
+单个 block 判有效用 `isToolUiCard`（严格守卫：`target`/`height` 缺失、archived 无留档
+HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进度」卡片（不对用户展示），
+`isAppDevToolUiCard` 识别应用开发会话的预览卡。相关类型：`ToolUiCard`、
+`ToolUiCardContentType`、`InlineToolUiCardEntry`、`PreviewToolUiCardEntry`。
+
 ## 常见问题
 
 | 现象 | 原因与解法 |
@@ -579,13 +749,33 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 
 - **客户端与登录**：`BladeClientOptions`、`LoginOptions`、`LoginResult`、`TokenStorageMode`、`UploadProgress`、`BladeApiError`、`AuthResource`、`ProvidersResponse`、`UserInfo`
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
-- **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
+- **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SkillFile`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
+- **会话错误**：`AgentSessionError`（`code` 是服务端路由失败原因，供调用方决定是否重试）
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`GlobalSearchResult`、`GlobalSearchResultItem`、`GlobalSearchConversationResult`、`GlobalSearchFileResult`、`SessionHistory`、`SessionContextStats`、`ResultFeedback`、`ResultFeedbackReason`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
+- **聊天分组资源（REST）**：`ChatGroupsResource`、`ChatGroup`（含 `delete` 永久删除）；`client.chatGroups`。旧名 `ChatProjectsResource`、`ChatProject`、`client.chatProjects` 与 `chat_project_id` 字段已随分组改名一并移除，接入方请改用 `chatGroups` 与 `chat_group_id`
+- **插件目录（REST，无会话）**：`PluginsResource`、`PluginCatalogEntry`（`client.plugins`）。首页这类还没有会话的界面用它读名称、业务名与图标 token
+- **账号电脑目录**：`AccountComputer`、`AccountComputerList`（`client.computers.listAccount()`，只读账号事实，不含会话授权）
+- **全站访问统计（REST）**：`SiteVisitsResource`、`SiteVisitsSummary`（`client.siteVisits.record()` 上报一次页面访问、`client.siteVisits.summary()` 只读快照）。这两个操作走独立匿名传输：不带 bearer、不触发 401 登录刷新，只依赖匿名访客 Cookie，供内置 Web 同源使用。
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`GlobalSearchResult`、`GlobalSearchResultItem`、`GlobalSearchConversationResult`、`GlobalSearchFileResult`、`SessionHistory`、`SessionContextStats`、`ResultFeedback`、`ResultFeedbackReason`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`、`PrimarySkillStageSpec`、`PrimarySkillStepSpec`、`SkillEditorTemplateId`、`SessionSearchMatch`
+- **会话历史取数**：`SessionTurnsQuery`、`SessionTurnsPage`、`SessionTurnIndex`、`SessionTurnIndexItem`、`isEntryGoneError`（`isEntryGoneError` 区分"这条发言已经不在当前分支上"与"这次没取到"：前者说明 `fromEntryId` 定位目标失效，后者只说明本次请求失败）
 - **会话回放**：`ReplayState`、`ReplaySpeed`、`ReplayPreview`、`ReplaySnapshot`、`toReplaySnapshot`、`DEFAULT_REPLAY_SPEED`
 - **会话状态机**：`SessionHub`、`SessionConnectOptions`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
+- **静态历史会话**：`AgentSession.fromTurns(sessionId, turns)` 构造的会话 `isStatic` 为 true——它没有目录接口，宿主拿已加载窗口推导航条目（`turnNavItemsFromMessages`）；真实会话不要这么做，timeline 被重写后窗口里还是旧分支的发言，那些 entry id 已经点不到了
+- **长会话跨页定位**：`AgentSession.locateEntry(entryId)`（按稳定 `entry_id` 取"从它往后"的窗口）、`AgentSession.cancelPendingLocate()`（作废在途的那次定位；它只中止定位自己的请求，不牵动运行结束 / 重连的权威刷新）。权威刷新（运行结束 / 重连补数 / 翻页之后的对账）不另记状态：一律按**当前窗口第一条发言**取窗口，那条已经不在分支上（404 / 409）时回落最新一页；`sessions.getSessionTurnIndex(sessionId)` 给出可导航的用户发言目录（`SessionTurnIndex` / `SessionTurnIndexItem`），`getSessionTurnsPage({ fromEntryId })` 与它共用同一份分支投影
+- **会话消息队列**：`SessionQueueSnapshot`、`QueuedMessage`、`QueuedMessageStatus`、`QueueAck`、`QueueOperationResult`、`EMPTY_SESSION_QUEUE`、`isSessionQueueSnapshot`、`shouldApplySnapshot`、`parseQueueAck`、`canEditQueuedMessage`、`canCancelQueuedMessage`、`canDeliverQueuedMessage`、`queuedMessageStatusLabel`、`queuePauseReasonLabel`
 - **页面协作**：`EmbeddedChat`、`EmbeddedChatOptions`、`CommandHandler`、`CommandEnvelope`、`InboundAction`、`InboundEnvelope`、`isCommandEnvelope`、`isInboundEnvelope`
-- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`ContextProjectionData`、`ContextProjectionFields`、`ContextDisplayState`、`ContextGroupDisplayState`、`ContextAction`、`ContextSourceInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`contextProjectionData`、`getContextDisplayState`、`getContextGroupDisplayState`、`groupAdjacentContextRuns`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **流式 wire 事件（自定义渲染用）**：`ContentDelta`、`ToolCallCreated`、`ToolCallArgumentsDelta`、`ToolResultDelta`、`ToolResultDone`、`LlmResponseDone`、`ChatEnd`、`SystemError`、`SessionStatusEvent`。它们描述 socket 上一帧帧到达的内容，只有自己接管流式拼装时才需要
+- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`ContextProjectionData`、`ContextProjectionFields`、`ContextDisplayState`、`ContextGroupDisplayState`、`ContextAction`、`ContextSourceInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`ToolCallProjection`、`PendingQuestionRef`、`RunTiming`、`inferToolStatus`、`contextProjectionData`、`getContextDisplayState`、`getContextGroupDisplayState`、`groupAdjacentContextRuns`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **MCP Apps 留档与卡片判定**：`McpAppData`、`isMcpAppData`、`McpAppContextState`、`McpAppContextUpdate`、`ToolUiCard`、`ToolUiCardContentType`、`InlineToolUiCardEntry`、`PreviewToolUiCardEntry`、`isToolUiCard`、`resolveToolUiCardContent`、`buildToolUiCardKey`、`isInternalStatusToolUiCard`、`isAppDevToolUiCard`、`collectInlineToolUiCards`、`collectPreviewToolUiCards`（`McpAppContextState` / `McpAppContextUpdate` 配合 `sessions.getMcpAppContext` / `sessions.updateMcpAppContext`：App 保存的状态在下一个新运行才进入模型上下文）
 - **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`PublishedSolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`、`BackgroundTaskStopResult`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
-- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`
+- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`AuthBusyReconnect`、`authBusyRetryDelayMs`、`ClientProjectionBuilder`、`RawEvent`、`acknowledgeTurnEvents`、`hasChatRunEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`、`reconcileHistoricalUserTurns`
+### MCP App 留档
+
+`McpAppArchive` 是 `client.sessions.getMcpApp(sessionId, sourceId)` 经鉴权返回的归档，包含保存的 HTML 与最新留档输入/结果。`callMcpApp` 在会话 sandbox 内调用该卡片的归档能力；`onMcpAppChanged` 订阅结果变化，返回取消订阅函数。
+
+最新调用失败或完成状态未知时，归档同时提供 `previousToolInput` / `previousToolResult`，用于先恢复最后成功的界面再展示错误。读取这些留档不会重新执行工具。
+
+会话列表和详情的 `SessionInfo.initiator` 表示首次发起来源：`ui` 为界面，`sdk` 为 SDK；旧会话缺少可靠记录时为 `unknown`，尚未发起会话时为 `null` 或未提供。它不等同于后台运行标记 `is_headless`，后续继续会话不会改变来源。
+
+后台唤醒输入可用 `isBackgroundWakeMessage(message)` 识别，它读取消息的结构化通知 block。自定义 UI 应为这类输入显示说明卡片；`isHiddenInternalMessage` 仍将其视为内部输入，避免作为用户发言或回溯导航点。

package/dist/auth.d.ts

@@ -1,7 +1,6 @@
 export interface AuthOptions {
     token?: string | (() => string | null | undefined);
 }
-export declare function buildAuthHeaders(options: AuthOptions): Record<string, string>;
 export declare function buildSocketAuth(options: AuthOptions): {
     token: string;
 } | undefined;

package/dist/blade-client.d.ts

@@ -5,6 +5,9 @@ import { HeadlessResource } from "./resources/headless";
 import { ComputersResource } from "./resources/computers";
 import { ModelsResource } from "./resources/models";
 import { SessionsResource } from "./resources/sessions";
+import { PluginsResource } from "./resources/plugins";
+import { ChatGroupsResource } from "./resources/chat-groups";
+import { SiteVisitsResource } from "./resources/site-visits";
 import { SessionHub } from "./session/hub";
 import { type TypedSocket } from "./socket";
 export interface BladeClientOptions {
@@ -22,6 +25,8 @@ export interface BladeClientOptions {
     socketToken?: string | (() => string | null | undefined);
     /** login() 取得的令牌存放位置，默认 "local"（localStorage，刷新页面不掉登录）。 */
     tokenStorage?: TokenStorageMode;
+    /** Host-owned command transport; event subscriptions stay on the normal socket. */
+    commandTransport?: (event: string, payload: Record<string, unknown>, send: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
     fetchImpl?: typeof fetch;
     onRefreshSuccess?: () => void | Promise<void>;
 }
@@ -37,6 +42,14 @@ export declare class BladeClient {
     readonly computers: ComputersResource;
     readonly models: ModelsResource;
     readonly sessions: SessionsResource;
+    /** 按用户读取的插件目录与图标；没有会话时也能用。 */
+    readonly plugins: PluginsResource;
+    readonly chatGroups: ChatGroupsResource;
+    /**
+     * 全站访问统计：匿名读写，不带 bearer 也不触发登录刷新。
+     * 只有内置 Web 的同源页面使用，第三方宿主页面不会被自动统计。
+     */
+    readonly siteVisits: SiteVisitsResource;
     /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
     readonly hub: SessionHub;
     constructor(options: BladeClientOptions);
@@ -70,6 +83,7 @@ export declare class BladeClient {
     /** 底层 Socket.IO 实例因后端地址变化而被替换时通知高级集成层。 */
     onSocketReplaced(listener: () => void): () => void;
     socket(): TypedSocket;
+    requestCommand(event: string, payload: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>>;
     json<T>(method: HttpMethod, path: string, body?: unknown): Promise<T>;
     jsonFromInit<T>(path: string, init?: RequestInit): Promise<T>;
     text(method: HttpMethod, path: string): Promise<string>;
@@ -85,10 +99,17 @@ export declare class BladeClient {
     private buildHeaders;
     private buildUrl;
     private baseUrlWithTrailingSlash;
-    private toBaseRelativePath;
     private isSameBackendUrl;
     private shouldRefreshFor401;
     private hasExplicitBearerToken;
+    /**
+     * 等一次令牌刷新，但调用方中止请求时不再等下去。
+     *
+     * 刷新本身是共享的（`refreshPromise`，别的请求也在等它），这里只是让这次已被取消的
+     * 请求尽早结束——否则它会一直挂在调用方（定位）的串行队列里，用户改选的新目标要等到
+     * 刷新结束才轮得到。
+     */
+    private tryRefreshUnlessAborted;
     private tryRefresh;
     private resolveTokenForUrl;
     private resolveRestToken;

package/dist/index.d.ts

@@ -1,19 +1,26 @@
 export { BladeClient } from "./blade-client";
 export type { BladeClientOptions, UploadProgress } from "./blade-client";
 export { BladeApiError } from "./rest";
+export { isEntryGoneError } from "./resources/sessions";
+export { PollingBackoff } from "./polling-backoff";
 export type { LoginOptions, LoginResult, TokenStorageMode } from "./auth-login";
 export { EMPTY_PLATFORM_ENDPOINTS, loadPlatformEndpoints, resolveServiceUrl, } from "./platform-endpoints";
 export type { LoadPlatformEndpointsOptions, PlatformEndpoints, PlatformServiceName, } from "./platform-endpoints";
 export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
 export type { AttachAppOptions, SendOptions } from "./session/agent-session";
+export { AgentSessionError } from "./session/errors";
 export { SessionHub } from "./session/hub";
 export type { SessionConnectOptions } from "./session/hub";
 export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";
+export { isMcpAppData } from "./schemas/mcp-app";
+export type { McpAppArchive, McpAppContextState, McpAppContextUpdate, McpAppData, } from "./schemas/mcp-app";
 export { SessionSetupError } from "./session/definition";
-export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, TextFile, SolutionDefinition, } from "./session/definition";
-export { createInitialSessionState, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
+export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, SkillFile, TextFile, SolutionDefinition, } from "./session/definition";
+export { createInitialSessionState, reconcileHistoricalUserTurns, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
 export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, ReplaySnapshot, SessionState, } from "./session/state";
+export { EMPTY_SESSION_QUEUE, canCancelQueuedMessage, canDeliverQueuedMessage, canEditQueuedMessage, isSessionQueueSnapshot, parseQueueAck, queuePauseReasonLabel, queuedMessageStatusLabel, shouldApplySnapshot, } from "./session/queue";
+export type { QueueAck, QueueOperationResult, QueuedMessage, QueuedMessageStatus, SessionQueueSnapshot, } from "./session/queue";
 export { connectEmbedded } from "./commands/embedded";
 export type { EmbeddedChat, EmbeddedChatOptions } from "./commands/embedded";
 export type { CommandHandler } from "./commands/registry";
@@ -22,28 +29,43 @@ export { isCommandEnvelope, isInboundEnvelope } from "./commands/protocol";
 export type { AuthResource, ExchangeCodeParams, ExchangeCodeResult, ProvidersResponse, UserInfo, } from "./resources/auth";
 export type { HeadlessResource } from "./resources/headless";
 export { ComputersResource } from "./resources/computers";
-export { canToggleComputer, computerState, sortComputers, } from "./resources/computers";
-export type { ComputerState, SessionComputer, SessionComputerList, } from "./resources/computers";
+export { canToggleComputer, computerDaemonVersion, computerOS, computerPlatformLabel, computerState, sortComputers, } from "./resources/computers";
+export type { AccountComputer, AccountComputerList, ComputerOS, ComputerState, SessionComputer, SessionComputerList, } from "./resources/computers";
 export { ModelsResource } from "./resources/models";
 export type { ModelCatalog, ModelOption } from "./resources/models";
 export type { SessionsResource } from "./resources/sessions";
-export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, ResultFeedback, ResultFeedbackReason, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+export type { SessionPlugin, SessionPluginActivation } from "./resources/sessions";
+export type { SessionPluginConfigError, SessionPluginConfigSet, SessionPluginConfigState, SessionPluginConfigStateName, SessionPluginConfigSummary, SessionPluginConfigUpdate, } from "./resources/sessions";
+export { ChatGroupsResource } from "./resources/chat-groups";
+export type { ChatGroup } from "./resources/chat-groups";
+export { PluginsResource } from "./resources/plugins";
+export type { PluginCatalogEntry } from "./resources/plugins";
+export type { SiteVisitsResource, SiteVisitsSummary } from "./resources/site-visits";
+export { hasChatRunEvent } from "./shared/projection";
+export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, ResultFeedback, ResultFeedbackReason, HistoricalCommand, SessionContextStats, SessionHistory, SessionTurnsPage, SessionTurnsQuery, SessionTurnIndex, SessionTurnIndexItem, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
 export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";
-export { buildMessageContent, chatErrorForDisplay, contentPreview, extractTextAttachments, getFileParts, getImageParts, getTextContent, groupMessagesByLoop, isHiddenInternalMessage, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
+export { inferToolStatus } from "./schemas/message";
+export type { ChatEnd, ContentDelta, LlmResponseDone, SessionStatusEvent, SystemError, ToolCallArgumentsDelta, ToolCallCreated, ToolResultDelta, ToolResultDone, } from "./schemas/event";
+export { buildMessageContent, chatErrorForDisplay, contentPreview, extractTextAttachments, getFileParts, getImageParts, getTextContent, groupMessagesByLoop, isHiddenInternalMessage, isBackgroundWakeMessage, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
 export { contextProjectionData, getContextDisplayState, getContextGroupDisplayState, groupAdjacentContextRuns, } from "./schemas/context";
 export type { ContextAction, ContextDisplayState, ContextGroupDisplayState, ContextProjectionData, ContextProjectionFields, ContextSourceInfo, } from "./schemas/context";
 export type { ParsedTextAttachment, ParsedTextContext, SkillMentionAvailability, } from "./schemas/message-utils";
-export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PostChatFollowup, TurnProjection, } from "./schemas/projection";
+export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PendingQuestionRef, PostChatFollowup, RunTiming, ToolCallProjection, TurnProjection, } from "./schemas/projection";
 export { latestPostChatFollowup } from "./schemas/projection-utils";
+export { buildToolUiCardKey, collectInlineToolUiCards, collectPreviewToolUiCards, isAppDevToolUiCard, isInternalStatusToolUiCard, isToolUiCard, resolveToolUiCardContent, } from "./shared/tool-ui-card";
+export type { InlineToolUiCardEntry, PreviewToolUiCardEntry, ToolUiCard, ToolUiCardContentType, } from "./shared/tool-ui-card";
+export { prependOlder, replaceWindow } from "./session/history-page";
+export type { LiveRevisionState } from "./session/history-page";
 export { DEFAULT_REPLAY_SPEED } from "./schemas/session";
 export { SessionInfo, SessionStatus } from "./schemas/session";
-export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, ReplayPreview, ReplaySpeed, ReplayState, SessionDetail, SessionPortMapping, PublishedSolutionRef, TemplateId, } from "./schemas/session";
+export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, PrimarySkillStageSpec, PrimarySkillStepSpec, PublishedSolutionRef, ReplayPreview, ReplaySpeed, ReplayState, SessionDetail, SessionPortMapping, SessionSearchMatch, SkillEditorTemplateId, TemplateId, } from "./schemas/session";
 export { LayoutType } from "./schemas/solution";
 export type { BizRole, Solution, SolutionAppField, SolutionAppState, SolutionAppUiConfig, } from "./schemas/solution";
 export { Task, TaskStatus } from "./schemas/task";
 export type { BackgroundTask, BackgroundTaskStopResult } from "./schemas/background";
-export { acceptedPostChatFollowupCompletesLatestRun, ClientProjectionBuilder } from "./shared/projection";
+export { acceptedPostChatFollowupCompletesLatestRun, acknowledgeTurnEvents, ClientProjectionBuilder, } from "./shared/projection";
 export type { RawEvent } from "./shared/projection";
+export { AuthBusyReconnect, authBusyRetryDelayMs } from "./shared/auth-busy";
 export { createSocket } from "./socket";
 export type { CreateSocketOptions, TypedSocket } from "./socket";
 export type { AsrAudioPayload } from "./types/socket-events";