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

package/README.md

@@ -431,7 +431,7 @@ chat.on("chatEnd",    (e) => console.log("回复结束", e.status))
 chat.on("error",      (e) => console.error(e.message))
 ```
 
-完整事件表见 `AgentSessionEvents` 类型定义（含 `modeChange` / `workspaceChanged` / `artifact` / `notification` / `backgroundTask` / `taskListUpdated` / `rewind` / `replayMismatch` 等）。`on()` 返回取消函数；handler 抛异常只告警，不影响会话。
+完整事件表见 `AgentSessionEvents` 类型定义（含 `modeChange` / `workspaceChanged` / `artifact` / `notification` / `backgroundTask` / `taskListUpdated` / `rewind` / `replayMismatch` 等）。`toolResult.source` 区分实时结果、首次连接回放和断线重连回放；`on()` 返回取消函数，handler 抛异常只告警、不影响会话。
 
 ## iframe 嵌入形态：connectEmbedded
 
@@ -583,9 +583,9 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **模型目录**：`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`
 - **会话回放**：`ReplayState`、`ReplaySpeed`、`ReplayPreview`、`ReplaySnapshot`、`toReplaySnapshot`、`DEFAULT_REPLAY_SPEED`
-- **会话状态机**：`SessionHub`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
+- **会话状态机**：`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`、`ContextAction`、`ContextSourceInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`contextProjectionData`、`getContextDisplayState`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **消息与投影协议**：`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`
 - **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`

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
 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 { SessionSetupError } from "./session/definition";
 export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, TextFile, SolutionDefinition, } from "./session/definition";
@@ -29,8 +30,8 @@ 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 { 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 { contextProjectionData, getContextDisplayState, } from "./schemas/context";
-export type { ContextAction, ContextDisplayState, ContextProjectionData, ContextProjectionFields, ContextSourceInfo, } from "./schemas/context";
+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 { latestPostChatFollowup } from "./schemas/projection-utils";

package/dist/index.js

@@ -1104,12 +1104,47 @@ function contextProjectionData(fields) {
   };
 }
 function getContextDisplayState(context) {
-  const title = BUILTIN_CONTEXT_TITLES[context.context_kind] ?? nonEmptyString(context.display_title) ?? "\u5BF9\u8BDD\u80CC\u666F";
+  const title = nonEmptyString(context.display_title) ?? BUILTIN_CONTEXT_TITLES[context.context_kind] ?? "\u5BF9\u8BDD\u80CC\u666F";
   const isRemoved = context.context_action === "removed";
   const summary = nonEmptyString(context.display_summary) ?? (isRemoved ? "\u5DF2\u505C\u6B62\u7528\u4E8E\u540E\u7EED\u5BF9\u8BDD" : context.context_action === "retained" ? "\u7EE7\u7EED\u7528\u4E8E\u540E\u7EED\u5BF9\u8BDD" : context.context_kind === "agent-instructions" ? "\u5DF2\u66F4\u65B0\u672C\u6B21\u5BF9\u8BDD\u4F7F\u7528\u7684\u9879\u76EE\u8BF4\u660E" : context.context_kind === "skill-catalog" ? "\u5DF2\u66F4\u65B0\u672C\u6B21\u53EF\u7528\u80FD\u529B" : context.context_kind === "runtime-context" ? "\u5DF2\u66F4\u65B0\u672C\u6B21\u5DE5\u4F5C\u73AF\u5883" : context.context_kind === "workspace-context" ? "\u5DF2\u66F4\u65B0\u672C\u6B21\u5DE5\u4F5C\u533A\u73AF\u5883" : "\u5DF2\u66F4\u65B0\u672C\u6B21\u5BF9\u8BDD\u80CC\u666F");
   const detail = isRemoved ? `${title}\u5DF2\u4E0D\u518D\u7528\u4E8E\u540E\u7EED\u5BF9\u8BDD\u3002` : BUILTIN_CONTEXT_DETAILS[context.context_kind] ?? "\u8FD9\u4E9B\u4FE1\u606F\u4F1A\u5E2E\u52A9\u667A\u80FD\u4F53\u7406\u89E3\u5F53\u524D\u4EFB\u52A1\u3002";
   return { title, summary, detail, isRemoved };
 }
+function groupAdjacentContextRuns(kinds) {
+  const runs = [];
+  let current = null;
+  kinds.forEach((kind, index) => {
+    if (kind === null) {
+      current = null;
+      return;
+    }
+    if (current === null) {
+      current = [];
+      runs.push(current);
+    }
+    current.push(index);
+  });
+  return runs;
+}
+function getContextGroupDisplayState(contexts) {
+  const count = contexts.length;
+  if (count === 1) {
+    const single = getContextDisplayState(contexts[0]);
+    return { title: single.title, summary: single.summary, count };
+  }
+  const removed = contexts.filter(
+    (context) => context.context_action === "removed"
+  ).length;
+  const updated = count - removed;
+  const parts = [];
+  if (updated > 0) parts.push(`${updated} \u9879\u5DF2\u66F4\u65B0`);
+  if (removed > 0) parts.push(`${removed} \u9879\u5DF2\u505C\u7528`);
+  return {
+    title: "\u5BF9\u8BDD\u80CC\u666F",
+    summary: parts.join(" \xB7 ") || `${count} \u9879`,
+    count
+  };
+}
 
 // src/shared/projection/context.ts
 function isRecord2(value) {
@@ -2015,7 +2050,11 @@ function projectHistory(entries) {
         model: stringOrNull(message.model),
         usage: isRecord4(message._usage) ? { ...message._usage } : null,
         duration_ms: numberOrZero(message._duration_ms),
-        started_at: typeof entry.timestamp === "string" ? entry.timestamp : void 0
+        started_at: typeof entry.timestamp === "string" ? entry.timestamp : void 0,
+        // fork 子会话的父锚点:历史里落在消息级 _parent_fork_tool_call_id。丢掉它,
+        // 刷新后工作流步骤 fork 就配不回 workflow:run 工具调用(普通 Agent fork 有
+        // root Agent 工具调用兜底配对,工作流 fork 没有,子智能体卡会整体消失)。
+        parent_fork_tool_call_id: stringOrNull(message._parent_fork_tool_call_id)
       };
       const isNativeToolEntry = role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.some(
         (toolCall) => isRecord4(toolCall) && typeof toolCall.provider === "string"
@@ -2990,10 +3029,10 @@ function isLegacyForkContextText(text) {
   const normalized = text.trim();
   return LEGACY_FORK_CONTEXT_MARKERS.every((marker) => normalized.includes(marker));
 }
-function isHiddenInternalMessage(message) {
+function isHiddenInternalMessage(message, options = {}) {
   if (message.role !== "user") return false;
   const text = getTextContent(normalizeMessageContent(message.content));
-  return isSystemReminderText(text) || isSystemNotificationText(text) || isLegacyForkContextText(text);
+  return isSystemReminderText(text) || isSystemNotificationText(text) || (options.includeLegacyForkContext ?? true) && isLegacyForkContextText(text);
 }
 function buildMessageContent(text, attachments) {
   if (attachments.length === 0) return text;
@@ -3673,6 +3712,10 @@ var AgentSession = class _AgentSession {
   patchFlushCancel = null;
   joined = false;
   joinPending = null;
+  // bootstrap 与每次 reconnect 共用一条订阅生命周期队列。它们都会重置 join
+  // 状态并临时设置 replay source，禁止并发，否则较早操作的 finally 会清掉
+  // 较晚操作仍在使用的来源上下文。
+  subscriptionQueue = Promise.resolve();
   // 回放控制请求排成一条队列。连着点"5x"再点"退出回放"时，并发发出去的两个
   // 请求响应可能乱序回来，晚到的旧值会把已经退出的会话又显示成回放中；用
   // 序号丢弃过期响应又会在失败时留下中间态。串行执行就没有这些情况：每个
@@ -3682,6 +3725,7 @@ var AgentSession = class _AgentSession {
   pendingReplayMode;
   pendingReplayKbIds;
   recentChatEndAt = 0;
+  subscriptionReplaySource = null;
   disposed = false;
   getAppContext = null;
   sendPending = false;
@@ -3999,27 +4043,47 @@ var AgentSession = class _AgentSession {
     this.update((s) => ({ ...s, connection }));
   }
   /** @internal socket 重连后由 Hub 调用：重新加入房间并补数。 */
-  async _rejoinAfterReconnect() {
+  _rejoinAfterReconnect() {
     const turnsBeforeRejoin = this.state.turns;
-    this.joined = false;
-    this.joinPending = null;
-    try {
-      await this.ensureJoined();
-      await Promise.all([
-        this.syncTurnsFromHistory({
-          clearOnEmpty: true,
-          preserveChangesSince: turnsBeforeRejoin
-        }),
-        this.syncReplayFromSession()
-      ]);
-    } catch {
-    }
+    return this.enqueueSubscription(async () => {
+      this.joined = false;
+      this.joinPending = null;
+      try {
+        this.subscriptionReplaySource = "reconnect_replay";
+        try {
+          await this.ensureJoined();
+        } finally {
+          this.subscriptionReplaySource = null;
+        }
+        await Promise.all([
+          this.syncTurnsFromHistory({
+            clearOnEmpty: true,
+            preserveChangesSince: turnsBeforeRejoin
+          }),
+          this.syncReplayFromSession()
+        ]);
+      } catch {
+      }
+    });
   }
   /** @internal 首次连接：加载历史 + 加入房间。 */
-  async _bootstrap() {
-    await this.syncTurnsFromHistory({ suppressErrors: false });
-    await this.ensureJoined();
-    await this.syncReplayFromSession();
+  _bootstrap() {
+    return this.enqueueSubscription(async () => {
+      await this.syncTurnsFromHistory({ suppressErrors: false });
+      this.subscriptionReplaySource = "bootstrap_replay";
+      try {
+        await this.ensureJoined();
+      } finally {
+        this.subscriptionReplaySource = null;
+      }
+      await this.syncReplayFromSession();
+    });
+  }
+  /** 订阅生命周期串行执行；一次失败只由自己的调用方观察，不截断后续重连。 */
+  enqueueSubscription(operation) {
+    const run = this.subscriptionQueue.then(operation);
+    this.subscriptionQueue = run.catch(() => void 0);
+    return run;
   }
   /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
   get canControlReplay() {
@@ -4076,7 +4140,7 @@ var AgentSession = class _AgentSession {
     this.applyTurn(turn);
   }
   /** @internal 历史回放通道（event_format: raw）。 */
-  _handleTurnEvents(events) {
+  _handleTurnEvents(events, replayed = false) {
     if (!events.length) return;
     const terminalChatEndStatus = extractTerminalChatEndStatus(events);
     if (!terminalChatEndStatus && hasChatRunEvent2(events) && this.state.status !== "waiting_for_input") {
@@ -4088,7 +4152,10 @@ var AgentSession = class _AgentSession {
     const updates = this.projectionBuilder.processBatch(events);
     for (const update of updates) {
       if (update.kind === "upsert") {
-        this.applyTurn(update.turn);
+        this.applyTurn(
+          update.turn,
+          replayed ? this.subscriptionReplaySource ?? "bootstrap_replay" : "live"
+        );
       } else if (update.kind === "workspace_changed") {
         this.emitter.emit("workspaceChanged", {});
       }
@@ -4257,11 +4324,11 @@ var AgentSession = class _AgentSession {
     void this.syncTurnsFromHistory();
     this.emitter.emit("chatEnd", { status });
   }
-  applyTurn(turn) {
+  applyTurn(turn, source = "live") {
     this.flushPatches();
     const previous = this.state;
     this.update((s) => upsertTurn(s, turn));
-    this.emitTurnDerivedEvents(previous, turn);
+    this.emitTurnDerivedEvents(previous, turn, source);
   }
   schedulePatchFlush() {
     if (this.patchFlushHandle != null) return;
@@ -4307,7 +4374,7 @@ var AgentSession = class _AgentSession {
     }
   }
   /** turn 数据落地后统一派生语义事件（指令 / 工具调用 / 消息 / 模式 / 预览 / OOM）。 */
-  emitTurnDerivedEvents(previous, turn) {
+  emitTurnDerivedEvents(previous, turn, source = "live") {
     const mode = extractModeFromBlocks(turn.blocks);
     if (mode && previous.mode !== mode) {
       this.emitter.emit("modeChange", { mode });
@@ -4356,7 +4423,7 @@ var AgentSession = class _AgentSession {
       const finished = toolCall.status === "done" || toolCall.status === "error" || toolCall.status === "cancelled";
       if (finished && !this.finishedToolCallIds.has(toolCall.id)) {
         this.finishedToolCallIds.add(toolCall.id);
-        this.emitter.emit("toolResult", { toolCall: info, turn });
+        this.emitter.emit("toolResult", { toolCall: info, turn, source });
         if (isOomResult(toolCall.result)) {
           this.notifySandboxOom(toolCall.id);
         }
@@ -4398,6 +4465,7 @@ var AgentSession = class _AgentSession {
     try {
       const turns = await this.runtime.fetchTurns(this.sessionId);
       if (turns.length === 0 && !clearOnEmpty) return;
+      if (!this.joined) this.seedToolCallDeliveryBaseline(turns);
       this.update((state) => {
         const mergeBaseline = preserveChangesSince ?? turnsAtRequestStart;
         if (state.turns === mergeBaseline) return withTurns(state, turns);
@@ -4416,6 +4484,17 @@ var AgentSession = class _AgentSession {
       if (!suppressErrors) throw error;
     }
   }
+  /** 首次订阅前的 REST 历史建立语义事件基线，随后同一工具的订阅回放不再投递。 */
+  seedToolCallDeliveryBaseline(turns) {
+    for (const turn of turns) {
+      for (const toolCall of turn.tool_calls) {
+        this.seenToolCallIds.add(toolCall.id);
+        if (toolCall.status === "done" || toolCall.status === "error" || toolCall.status === "cancelled") {
+          this.finishedToolCallIds.add(toolCall.id);
+        }
+      }
+    }
+  }
   /**
    * 把历史里的指令补投给宿主页面。
    *
@@ -4515,16 +4594,28 @@ var SessionHub = class {
    * 只有最后一份归还才退订房间——否则 StrictMode 双跑、路由抖动这类"连两次
    * 只释放一次"的场景会把仍在用的会话退订掉，之后所有 turn/chat 事件静默丢失。
    */
-  async connect(sessionId) {
+  async connect(sessionId, options = {}) {
     const existing = this.sessions.get(sessionId);
     if (existing && !existing.isDisposed) {
       this.hold(sessionId);
+      try {
+        options.setup?.(existing);
+      } catch (error) {
+        existing.dispose();
+        throw error;
+      }
       return this.bootstrapPending.get(sessionId) ?? existing;
     }
     this.ensureBound();
     const session = new AgentSession(sessionId, this.runtimeFor(), this.connection);
     this.sessions.set(sessionId, session);
     this.hold(sessionId);
+    try {
+      options.setup?.(session);
+    } catch (error) {
+      session.dispose();
+      throw error;
+    }
     this.ensureConnected();
     const bootstrap = session._bootstrap().then(() => session);
     this.bootstrapPending.set(sessionId, bootstrap);
@@ -4686,9 +4777,14 @@ var SessionHub = class {
     socket.on("turn:end", (data) => {
       for (const session of this.route(data.session_id)) session._handleTurnEnd(data);
     });
-    socket.on("turn:events", (data) => {
-      for (const session of this.route(data.session_id)) session._handleTurnEvents(data.events ?? []);
-    });
+    socket.on(
+      "turn:events",
+      (data) => {
+        for (const session of this.route(data.session_id)) {
+          session._handleTurnEvents(data.events ?? [], data.replayed === true);
+        }
+      }
+    );
     socket.on("chat:start", (data) => {
       for (const session of this.route(data?.session_id)) session._handleChatStart();
     });
@@ -4818,7 +4914,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.30" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.32" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {
@@ -5424,9 +5520,11 @@ export {
   createSocket,
   extractTextAttachments,
   getContextDisplayState,
+  getContextGroupDisplayState,
   getFileParts,
   getImageParts,
   getTextContent,
+  groupAdjacentContextRuns,
   groupMessagesByLoop,
   isCommandEnvelope,
   isHiddenInternalMessage,