@blade-hq/agent-client 2610.0.0-beta.31 → 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,7 +583,7 @@ 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`、`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`

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";

package/dist/index.js

@@ -3712,6 +3712,10 @@ var AgentSession = class _AgentSession {
   patchFlushCancel = null;
   joined = false;
   joinPending = null;
+  // bootstrap 与每次 reconnect 共用一条订阅生命周期队列。它们都会重置 join
+  // 状态并临时设置 replay source，禁止并发，否则较早操作的 finally 会清掉
+  // 较晚操作仍在使用的来源上下文。
+  subscriptionQueue = Promise.resolve();
   // 回放控制请求排成一条队列。连着点"5x"再点"退出回放"时，并发发出去的两个
   // 请求响应可能乱序回来，晚到的旧值会把已经退出的会话又显示成回放中；用
   // 序号丢弃过期响应又会在失败时留下中间态。串行执行就没有这些情况：每个
@@ -3721,6 +3725,7 @@ var AgentSession = class _AgentSession {
   pendingReplayMode;
   pendingReplayKbIds;
   recentChatEndAt = 0;
+  subscriptionReplaySource = null;
   disposed = false;
   getAppContext = null;
   sendPending = false;
@@ -4038,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() {
@@ -4115,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") {
@@ -4127,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", {});
       }
@@ -4296,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;
@@ -4346,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 });
@@ -4395,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);
         }
@@ -4437,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);
@@ -4455,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);
+        }
+      }
+    }
+  }
   /**
    * 把历史里的指令补投给宿主页面。
    *
@@ -4554,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);
@@ -4725,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();
     });
@@ -4857,7 +4914,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.31" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.32" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {