@blade-hq/agent-client 2610.0.0-beta.89 → 2610.0.0-beta.90

package/README.md

@@ -157,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)`（前端参数是驼峰），就能接着上次的对话。
@@ -715,12 +717,15 @@ const previewCards = collectPreviewToolUiCards(messages) // [{ key, toolCall, ca
 
 // 渲染前解析实际内容；archived 留档卡片只用留档 HTML，绝不回退 resourceUri
 // （历史恢复/刷新不会因此重放一次 MCP 资源读取）
-const resolved = resolveToolUiCardContent(card) // { type: "resource-html" | "resource-uri", content } | null
+const resolved = resolveToolUiCardContent(card) // { type: "resource-html" | "resource-uri" | "resource-file", content } | null
 
-// 实例去重键：uri 卡片按内容、html 卡片按 toolCallId，与 toolPreview 事件、内置侧栏一致
-const key = buildToolUiCardKey(toolCallId, resolved.type, resolved.content)
+// 文件卡片按 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`、
@@ -744,7 +749,7 @@ HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进
 
 - **客户端与登录**：`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）**：`ChatGroupsResource`、`ChatGroup`（含 `delete` 永久删除）；`client.chatGroups`。旧名 `ChatProjectsResource`、`ChatProject`、`client.chatProjects` 与 `chat_project_id` 字段已随分组改名一并移除，接入方请改用 `chatGroups` 与 `chat_group_id`
@@ -772,3 +777,5 @@ HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进
 最新调用失败或完成状态未知时，归档同时提供 `previousToolInput` / `previousToolResult`，用于先恢复最后成功的界面再展示错误。读取这些留档不会重新执行工具。
 
 会话列表和详情的 `SessionInfo.initiator` 表示首次发起来源：`ui` 为界面，`sdk` 为 SDK；旧会话缺少可靠记录时为 `unknown`，尚未发起会话时为 `null` 或未提供。它不等同于后台运行标记 `is_headless`，后续继续会话不会改变来源。
+
+后台唤醒输入可用 `isBackgroundWakeMessage(message)` 识别，它读取消息的结构化通知 block。自定义 UI 应为这类输入显示说明卡片；`isHiddenInternalMessage` 仍将其视为内部输入，避免作为用户发言或回溯导航点。

package/dist/index.d.ts

@@ -16,7 +16,7 @@ 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 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";
@@ -46,7 +46,7 @@ export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntr
 export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";
 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, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
+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";

package/dist/index.js

@@ -1,3 +1,7 @@
+// src/version.ts
+var SDK_NAME = "agent-client";
+var SDK_VERSION = true ? "2610.0.0-beta.90" : "1.1.1";
+
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
   return typeof value === "object" && value !== null && value.type === "blade-agent:sdk-auth";
@@ -1738,6 +1742,9 @@ var ClientProjectionBuilder = class {
       duration_ms: 0,
       client_request_id: typeof payload.client_request_id === "string" ? payload.client_request_id : null
     };
+    if (payload.start_reason === "background-completion") {
+      turn.blocks.push({ type: "system_notification", content: { notification_type: "bg:wakeup" } });
+    }
     this.latestTurns.set("root", turn);
     return [{ kind: "upsert", turn }];
   }
@@ -2178,6 +2185,101 @@ function toolArgsFromPayload(payload) {
   return "";
 }
 
+// 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) && !(raw.target === "preview" && isNonEmptyString(raw.sourcePath))) {
+    return false;
+  }
+  if (raw.title != null && !isNonEmptyString(raw.title)) {
+    return false;
+  }
+  if (raw.sourcePath != null && !isNonEmptyString(raw.sourcePath)) 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;
+  if (isNonEmptyString(uri)) return { type: "resource-uri", content: uri };
+  return card.target === "preview" && isNonEmptyString(card.sourcePath) ? { type: "resource-file", content: card.sourcePath } : null;
+}
+function buildToolUiCardKey(toolCallId, type3, content, sourcePath) {
+  if (type3 === "resource-uri") {
+    return `tool-preview-uri:${content}`;
+  }
+  if (sourcePath?.trim()) return sourcePath.trim();
+  if (type3 === "resource-file") return 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/shared/projection/history.ts
 function projectHistory(entries) {
   const turns = [];
@@ -2270,6 +2372,9 @@ function projectHistory(entries) {
       if (role !== "user" && role !== "assistant" && role !== "system") continue;
       const toolCalls = role === "assistant" && !message._error ? buildToolCalls(message.tool_calls) : [];
       const blocks = buildBlocks(message, toolCalls);
+      if (role === "user" && message._start_reason === "background-completion") {
+        blocks.push({ type: "system_notification", content: { notification_type: "bg:wakeup" } });
+      }
       const turn = {
         id,
         sequence: ++sequence,
@@ -2384,7 +2489,8 @@ function projectHistory(entries) {
       const toolCallId = String(data.tool_call_id ?? "");
       const owner = kind === "tool_bridge" ? toolCallId ? toolOwners.get(toolCallId) : void 0 : toolOwners.get(toolCallId) ?? findLatestAssistant(turns, loopId);
       const rawContent = kind === "tool_ui" ? data.ui : data.bridge;
-      const content = kind === "tool_ui" && isRecord(rawContent) ? { ...rawContent, archived: true } : rawContent;
+      const fileReference = isToolUiCard(rawContent) && resolveToolUiCardContent(rawContent)?.type === "resource-file";
+      const content = kind === "tool_ui" && isRecord(rawContent) ? { ...rawContent, ...!fileReference ? { archived: true } : {} } : rawContent;
       if (owner && content !== void 0) {
         owner.blocks.push({
           type: kind,
@@ -3671,97 +3777,6 @@ function queuePauseReasonLabel(reason) {
   return QUEUE_PAUSE_REASON_LABELS[reason] ?? reason;
 }
 
-// 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;
@@ -3945,6 +3960,12 @@ function groupMessagesByLoop(messages) {
   }
   return groups;
 }
+function isBackgroundWakeMessage(message) {
+  return message.blocks?.some((block) => {
+    const content = block.content;
+    return block.type === "system_notification" && content !== null && typeof content === "object" && "notification_type" in content && content.notification_type === "bg:wakeup";
+  }) ?? false;
+}
 
 // src/session/state.ts
 function toReplaySnapshot(raw) {
@@ -5653,8 +5674,12 @@ var AgentSession = class _AgentSession {
         if (ui.target !== "preview") continue;
         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]);
+        const key = buildToolUiCardKey(block.tool_call_id, resolved.type, resolved.content, ui.sourcePath);
+        const fingerprint = JSON.stringify([
+          resolved.content,
+          ui.mcpApp?.sourceId,
+          resolved.type === "resource-file" ? block.tool_call_id : void 0
+        ]);
         if (this.deliveredToolPreviews.get(key) === fingerprint) continue;
         this.deliveredToolPreviews.set(key, fingerprint);
         this.emitter.emit("toolPreview", {
@@ -5662,6 +5687,7 @@ var AgentSession = class _AgentSession {
           type: resolved.type,
           content: resolved.content,
           title: ui.title ?? "\u5DE5\u5177\u9884\u89C8",
+          ...ui.sourcePath ? { sourcePath: ui.sourcePath } : {},
           ...ui.mcpApp ? { mcpApp: ui.mcpApp } : {}
         });
       }
@@ -6613,6 +6639,7 @@ var BladeClient = class {
     if (!this.isSameBackendUrl(url)) {
       return result;
     }
+    result.set("X-Blade-Client", `${SDK_NAME}/${SDK_VERSION}`);
     const token = this.resolveRestToken();
     if (token) {
       result.set("Authorization", `Bearer ${token}`);
@@ -6674,7 +6701,9 @@ var BladeClient = class {
           this.buildUrl(REFRESH_PATH).toString(),
           {
             method: "POST",
-            credentials: "include"
+            credentials: "include",
+            // Refresh remains cookie-only; do not attach the REST bearer.
+            headers: { "X-Blade-Client": `${SDK_NAME}/${SDK_VERSION}` }
           }
         );
         if (!response.ok) {
@@ -6917,10 +6946,6 @@ function resolveServiceUrl(endpoints, name, path = "") {
   return target.toString();
 }
 
-// src/version.ts
-var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.89" : "1.1.1";
-
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -7075,6 +7100,7 @@ export {
   hasChatRunEvent,
   inferToolStatus,
   isAppDevToolUiCard,
+  isBackgroundWakeMessage,
   isCommandEnvelope,
   isEntryGoneError,
   isHiddenInternalMessage,