@blade-hq/agent-client 2610.0.0-beta.50 → 2610.0.0-beta.51

package/README.md

@@ -174,6 +174,41 @@ await client.sessions.getSessionTurnsPage(id, { before: page.nextBefore! })
 会话插件可通过 `client.sessions.listSessionPlugins(id)` 查询，并用
 `client.sessions.setSessionPluginActivation(id, name, active)` 切换当前会话。列表项为 `SessionPlugin`；修改结果为 `SessionPluginActivation`，只返回选择和准备状态，安装事实需从列表获取。
 
+插件可以在包内 `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。
+
 ### 会话回放（演示 / 彩排）
 
 拿一个已经聊完的会话当素材，重现当时的回复和工具调用，**完全不调用模型**。
@@ -596,6 +631,38 @@ 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", content } | null
+
+// 实例去重键：uri 卡片按内容、html 卡片按 toolCallId，与 toolPreview 事件、内置侧栏一致
+const key = buildToolUiCardKey(toolCallId, resolved.type, resolved.content)
+```
+
+单个 block 判有效用 `isToolUiCard`（严格守卫：`target`/`height` 缺失、archived 无留档
+HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进度」卡片（不对用户展示），
+`isAppDevToolUiCard` 识别应用开发会话的预览卡。相关类型：`ToolUiCard`、
+`ToolUiCardContentType`、`InlineToolUiCardEntry`、`PreviewToolUiCardEntry`。
+
 ## 常见问题
 
 | 现象 | 原因与解法 |
@@ -622,6 +689,12 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **会话状态机**：`SessionHub`、`SessionConnectOptions`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
 - **页面协作**：`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`
+- **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`、`AuthBusyReconnect`、`authBusyRetryDelayMs`、`ClientProjectionBuilder`、`RawEvent`、`acknowledgeTurnEvents`、`hasChatRunEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`、`reconcileHistoricalUserTurns`
+### MCP App 留档
+
+`McpAppArchive` 是 `client.sessions.getMcpApp(sessionId, sourceId)` 经鉴权返回的归档，包含保存的 HTML 与最新留档输入/结果。`callMcpApp` 在会话 sandbox 内调用该卡片的归档能力；`onMcpAppChanged` 订阅结果变化，返回取消订阅函数。
+
+最新调用失败或完成状态未知时，归档同时提供 `previousToolInput` / `previousToolResult`，用于先恢复最后成功的界面再展示错误。读取这些留档不会重新执行工具。

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { AttachAppOptions, SendOptions } from "./session/agent-session";
 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, reconcileHistoricalUserTurns, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
@@ -29,6 +31,7 @@ export { ModelsResource } from "./resources/models";
 export type { ModelCatalog, ModelOption } from "./resources/models";
 export type { SessionsResource } from "./resources/sessions";
 export type { SessionPlugin, SessionPluginActivation } from "./resources/sessions";
+export type { SessionPluginConfigError, SessionPluginConfigSet, SessionPluginConfigState, SessionPluginConfigStateName, SessionPluginConfigSummary, SessionPluginConfigUpdate, } from "./resources/sessions";
 export { ChatProjectsResource } from "./resources/chat-projects";
 export type { ChatProject } from "./resources/chat-projects";
 export { hasChatRunEvent } from "./shared/projection";
@@ -40,6 +43,8 @@ export type { ContextAction, ContextDisplayState, ContextGroupDisplayState, Cont
 export type { ParsedTextAttachment, ParsedTextContext, SkillMentionAvailability, } from "./schemas/message-utils";
 export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PostChatFollowup, 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";

package/dist/index.js

@@ -2541,6 +2541,36 @@ var SessionsResource = class {
     this.client = client;
   }
   client;
+  getMcpApp(sessionId, sourceId, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/mcp-apps/${encodeURIComponent(sourceId)}`, init);
+  }
+  onMcpAppChanged(sessionId, sourceId, listener) {
+    let socket = this.client.socket();
+    const changed = (payload) => {
+      if (payload.session_id === sessionId && payload.source_id === sourceId) listener();
+    };
+    socket.on("mcp-app:changed", changed);
+    socket.on("connect", listener);
+    const off = this.client.onSocketReplaced(() => {
+      socket.off("mcp-app:changed", changed);
+      socket.off("connect", listener);
+      socket = this.client.socket();
+      socket.on("mcp-app:changed", changed);
+      socket.on("connect", listener);
+    });
+    return () => {
+      off();
+      socket.off("mcp-app:changed", changed);
+      socket.off("connect", listener);
+    };
+  }
+  callMcpApp(sessionId, sourceId, request, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/mcp-apps/${encodeURIComponent(sourceId)}/calls`, {
+      ...init,
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+  }
   /**
    * 连接一个已存在的会话，返回实时会话对象 AgentSession
    * （自动完成历史加载、Socket.IO 订阅、断线重连补数）。
@@ -2554,6 +2584,38 @@ var SessionsResource = class {
   setSessionPluginActivation(sessionId, name, active, init) {
     return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}:activation`, { method: "POST", body: JSON.stringify({ active }), ...init });
   }
+  /**
+   * Fetch a plugin's package-local icon as bytes.
+   *
+   * The request carries the client's own bearer credentials, so callers turn
+   * the blob into an object URL instead of pointing `<img>` at an API path and
+   * hoping the request is authenticated.
+   */
+  fetchSessionPluginIcon(sessionId, name) {
+    return this.client.blob("GET", `/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/icon`);
+  }
+  /** Authenticated URL for the icon; useful where a blob URL cannot be used. */
+  sessionPluginIconUrl(sessionId, name) {
+    return this.client.buildAuthedUrl(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/icon`);
+  }
+  /**
+   * Read a plugin's configuration contract and the user's stored values.
+   *
+   * Secrets are never returned: `write_only` lists the pointers that hold one.
+   */
+  getSessionPluginConfig(sessionId, name, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config`, init);
+  }
+  /**
+   * Publish explicit set/remove operations to the user's keychain file.
+   *
+   * Fields absent from both lists keep their stored value, so a form never has
+   * to round-trip a secret. Rejections leave the previous file untouched; the
+   * call never restarts MCP servers.
+   */
+  updateSessionPluginConfig(sessionId, name, update, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config`, { method: "PUT", body: JSON.stringify(update), ...init });
+  }
   /** 创建新会话并直接连接，返回可收发消息的 AgentSession。 */
   async create(request = {}) {
     if (isSessionDefinition(request)) {
@@ -2767,6 +2829,16 @@ var SessionsResource = class {
       currentMode: page.current_mode
     };
   }
+  getMcpAppContext(sessionId, sourceId, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/mcp-apps/${encodeURIComponent(sourceId)}/context`, init);
+  }
+  updateMcpAppContext(sessionId, sourceId, body, init) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/mcp-apps/${encodeURIComponent(sourceId)}/context`, {
+      ...init,
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
   async getSessionTurnCommands(sessionId) {
     const commands = await this.client.json("GET", `/api/sessions/${encodeURIComponent(sessionId)}/turn-commands`);
     return commands.map((command) => ({
@@ -3238,6 +3310,97 @@ function replaceWindow(current, page, liveRevisionAtStart, liveRevisions) {
   ]);
 }
 
+// src/schemas/mcp-app.ts
+function isMcpAppData(value) {
+  return isRecord(value) && typeof value.sourceId === "string" && value.sourceId.length > 0 && typeof value.resourceUri === "string" && value.resourceUri.startsWith("ui://") && typeof value.mimeType === "string" && isRecord(value.resourceMeta) && isRecord(value.toolInput) && isRecord(value.toolResult);
+}
+
+// src/shared/tool-ui-card.ts
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isToolUiCard(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const raw = value;
+  if (raw.target !== "inline" && raw.target !== "preview") {
+    return false;
+  }
+  if (!isPositiveNumber(raw.height)) {
+    return false;
+  }
+  if (raw.archived === true && !isNonEmptyString(raw.resourceHTML)) {
+    return false;
+  }
+  if (!isNonEmptyString(raw.resourceHTML) && !isNonEmptyString(raw.resourceUri) && !isNonEmptyString(raw.resourceURI)) {
+    return false;
+  }
+  if (raw.title != null && !isNonEmptyString(raw.title)) {
+    return false;
+  }
+  if (raw.mcpApp !== void 0 && !isMcpAppData(raw.mcpApp)) {
+    return false;
+  }
+  return true;
+}
+function resolveToolUiCardContent(card) {
+  if (isNonEmptyString(card.resourceHTML)) {
+    return { type: "resource-html", content: card.resourceHTML };
+  }
+  if (card.archived) return null;
+  const uri = isNonEmptyString(card.resourceUri) ? card.resourceUri : card.resourceURI;
+  return isNonEmptyString(uri) ? { type: "resource-uri", content: uri } : null;
+}
+function buildToolUiCardKey(toolCallId, type3, content) {
+  if (type3 === "resource-uri") {
+    return `tool-preview-uri:${content}`;
+  }
+  return `tool-preview:${toolCallId}`;
+}
+function isInternalStatusToolUiCard(card) {
+  return card?.title?.trim() === "\u9636\u6BB5\u8FDB\u5EA6";
+}
+function isAppDevToolUiCard(card, isAppDev) {
+  return isAppDev && card.target === "preview" && !card.resourceHTML && Boolean(card.resourceUri || card.resourceURI);
+}
+function collectInlineToolUiCards(messages) {
+  return messages.flatMap(
+    (message) => (message.blocks ?? []).flatMap(
+      (block, index) => block.type === "tool_ui" && block.tool_call_id && isToolUiCard(block.content) && block.content.target === "inline" ? [
+        {
+          key: `${message.entry_id ?? message.timestamp ?? "message"}-${block.tool_call_id}-${index}`,
+          toolCallId: block.tool_call_id,
+          card: block.content
+        }
+      ] : []
+    )
+  );
+}
+function collectPreviewToolUiCards(messages) {
+  return messages.flatMap(
+    (message) => (message.blocks ?? []).flatMap((block, index) => {
+      if (block.type !== "tool_ui" || !block.tool_call_id || !isToolUiCard(block.content) || block.content.target !== "preview") {
+        return [];
+      }
+      const toolCall = (message.tool_calls ?? []).find(
+        (candidate) => candidate.id === block.tool_call_id
+      );
+      return toolCall ? [
+        {
+          key: `${message.entry_id ?? message.timestamp ?? "message"}-${block.tool_call_id}-${index}`,
+          toolCall,
+          card: block.content,
+          blocks: message.blocks ?? []
+        }
+      ] : [];
+    })
+  );
+}
+
 // src/schemas/message-utils.ts
 var SYSTEM_REMINDER_PATTERN = /^<system-reminder>\s*[\s\S]*?\s*<\/system-reminder>$/i;
 var SYSTEM_NOTIFICATION_PATTERN = /^<system-notification>\s*[\s\S]*?\s*<\/system-notification>$/i;
@@ -3993,9 +4156,6 @@ function extractTerminalChatEndStatus(events) {
   }
   return null;
 }
-function isUiMetaLike(value) {
-  return isRecord(value) && ("resourceHTML" in value || "resourceUri" in value || "resourceURI" in value);
-}
 var AgentSession = class _AgentSession {
   sessionId;
   state;
@@ -4854,21 +5014,21 @@ ${text}` } : block
         this.dispatchCommand(turn, block);
         continue;
       }
-      if (block.type === "tool_ui" && block.tool_call_id && isUiMetaLike(block.content)) {
+      if (block.type === "tool_ui" && block.tool_call_id && isToolUiCard(block.content)) {
         const ui = block.content;
         if (ui.target !== "preview") continue;
-        const previewType = ui.resourceHTML ? "resource-html" : "resource-uri";
-        const previewContent = ui.resourceHTML ?? (ui.archived ? void 0 : ui.resourceUri ?? ui.resourceURI);
-        if (!previewContent) continue;
-        if (!previewContent) continue;
-        const key = `${block.tool_call_id}:${previewType}`;
-        if (this.deliveredToolPreviews.get(key) === previewContent) continue;
-        this.deliveredToolPreviews.set(key, previewContent);
+        const resolved = resolveToolUiCardContent(ui);
+        if (!resolved) continue;
+        const key = buildToolUiCardKey(block.tool_call_id, resolved.type, resolved.content);
+        const fingerprint = JSON.stringify([resolved.content, ui.mcpApp?.sourceId]);
+        if (this.deliveredToolPreviews.get(key) === fingerprint) continue;
+        this.deliveredToolPreviews.set(key, fingerprint);
         this.emitter.emit("toolPreview", {
           toolCallId: block.tool_call_id,
-          type: previewType,
-          content: previewContent,
-          title: ui.title ?? "\u5DE5\u5177\u9884\u89C8"
+          type: resolved.type,
+          content: resolved.content,
+          title: ui.title ?? "\u5DE5\u5177\u9884\u89C8",
+          ...ui.mcpApp ? { mcpApp: ui.mcpApp } : {}
         });
       }
       if (block.type === "system_notification" && isRecord(block.content)) {
@@ -6034,7 +6194,7 @@ function resolveServiceUrl(endpoints, name, path = "") {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.50" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.51" : "1.1.1";
 
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
@@ -6159,8 +6319,11 @@ export {
   acknowledgeTurnEvents,
   authBusyRetryDelayMs,
   buildMessageContent,
+  buildToolUiCardKey,
   canToggleComputer,
   chatErrorForDisplay,
+  collectInlineToolUiCards,
+  collectPreviewToolUiCards,
   computerDaemonVersion,
   computerOS,
   computerPlatformLabel,
@@ -6179,9 +6342,13 @@ export {
   groupAdjacentContextRuns,
   groupMessagesByLoop,
   hasChatRunEvent,
+  isAppDevToolUiCard,
   isCommandEnvelope,
   isHiddenInternalMessage,
   isInboundEnvelope,
+  isInternalStatusToolUiCard,
+  isMcpAppData,
+  isToolUiCard,
   latestPostChatFollowup,
   loadPlatformEndpoints,
   normalizeMessageContent,
@@ -6190,6 +6357,7 @@ export {
   reconcileOptimisticUserTurns,
   replaceWindow,
   resolveServiceUrl,
+  resolveToolUiCardContent,
   sortComputers,
   toReplaySnapshot,
   transformSlashCommand