@blade-hq/agent-client 2610.0.0-beta.70 → 2610.0.0-beta.71

package/README.md

@@ -169,8 +169,16 @@ 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`，只返回选择和准备状态，安装事实需从列表获取。
 
@@ -736,12 +744,16 @@ HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进
 - **插件目录（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`
+- **会话资源（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`

package/dist/blade-client.d.ts

@@ -99,6 +99,14 @@ export declare class BladeClient {
     private isSameBackendUrl;
     private shouldRefreshFor401;
     private hasExplicitBearerToken;
+    /**
+     * 等一次令牌刷新，但调用方中止请求时不再等下去。
+     *
+     * 刷新本身是共享的（`refreshPromise`，别的请求也在等它），这里只是让这次已被取消的
+     * 请求尽早结束——否则它会一直挂在调用方（定位）的串行队列里，用户改选的新目标要等到
+     * 刷新结束才轮得到。
+     */
+    private tryRefreshUnlessAborted;
     private tryRefresh;
     private resolveTokenForUrl;
     private resolveRestToken;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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";
@@ -40,13 +41,15 @@ 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, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+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 { 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 { 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";
@@ -54,7 +57,7 @@ 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";

package/dist/index.js

@@ -2596,6 +2596,10 @@ function findLatestAssistant(turns, loopId) {
 }
 
 // src/resources/sessions.ts
+function isEntryGoneError(error) {
+  const status = error?.status;
+  return status === 404 || status === 409;
+}
 function toCreateSessionPayload(request) {
   const solutionRef = request.solution_ref ?? externalSolutionRef(request.solution_id);
   return {
@@ -2932,18 +2936,36 @@ var SessionsResource = class {
     );
     return projectHistory(entries);
   }
-  async getSessionTurnsPage(sessionId, options = {}) {
+  async getSessionTurnsPage(sessionId, options = {}, init = {}) {
     const query = new URLSearchParams();
     if (options.limit !== void 0) query.set("limit", String(options.limit));
     if (options.before !== void 0) query.set("before", options.before);
+    if (options.fromEntryId !== void 0) query.set("from_entry_id", options.fromEntryId);
     const suffix = query.size ? `?${query}` : "";
-    const page = await this.client.json("GET", `/api/sessions/${encodeURIComponent(sessionId)}/turns${suffix}`);
+    const page = await this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/turns${suffix}`, init);
     return {
       turns: page.turns,
       nextBefore: page.next_before,
       currentMode: page.current_mode
     };
   }
+  /**
+   * 当前分支上可导航的用户发言目录（消息导航侧栏）。
+   *
+   * 只回 id、标题和时间：侧栏要列的是**整条会话**的发言，而窗口外的发言 id 只能
+   * 从服务端拿；消息体仍然走 `/turns`。
+   */
+  async getSessionTurnIndex(sessionId) {
+    const index = await this.client.json("GET", `/api/sessions/${encodeURIComponent(sessionId)}/turn-index`);
+    return {
+      sessionId: index.session_id,
+      items: index.items.map((item) => ({
+        entryId: item.entry_id,
+        preview: item.preview,
+        createdAt: item.created_at
+      }))
+    };
+  }
   getMcpAppContext(sessionId, sourceId, init) {
     return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/mcp-apps/${encodeURIComponent(sourceId)}/context`, init);
   }
@@ -4209,12 +4231,12 @@ function orderTurns(turns) {
   return turns;
 }
 function reconcileOptimisticUserTurns(currentTurns, incomingTurns) {
-  return reconcileUserTurns(currentTurns, incomingTurns, true);
+  return reconcileUserTurns(currentTurns, incomingTurns, true, false);
 }
 function reconcileHistoricalUserTurns(currentTurns, incomingTurns) {
-  return reconcileUserTurns(currentTurns, incomingTurns, false);
+  return reconcileUserTurns(currentTurns, incomingTurns, false, true);
 }
-function reconcileUserTurns(currentTurns, incomingTurns, allowLiveFallback) {
+function reconcileUserTurns(currentTurns, incomingTurns, allowLiveFallback, keepUnclaimedOptimistic) {
   const preservedTurns = preserveClientRenderIds(currentTurns, incomingTurns);
   const optimisticUserTurns = currentTurns.filter(
     (turn) => turn.role === "user" && (turn.kind ?? "message") === "message" && turn.turn_id.startsWith("local-user-")
@@ -4242,7 +4264,13 @@ function reconcileUserTurns(currentTurns, incomingTurns, allowLiveFallback) {
     }
     return turn;
   });
-  return claimedOptimisticIds.size === 0 ? reconciled : reconciled.filter((turn) => !claimedOptimisticIds.has(turn.turn_id));
+  const result = claimedOptimisticIds.size === 0 ? reconciled : reconciled.filter((turn) => !claimedOptimisticIds.has(turn.turn_id));
+  if (!keepUnclaimedOptimistic) return result;
+  const resultIds = new Set(result.map((turn) => turn.turn_id));
+  const unclaimedOptimisticTurns = optimisticUserTurns.filter(
+    (turn) => !claimedOptimisticIds.has(turn.turn_id) && !resultIds.has(turn.turn_id)
+  );
+  return unclaimedOptimisticTurns.length === 0 ? result : orderTurns([...result, ...unclaimedOptimisticTurns]);
 }
 function isUserConfirmation(turn) {
   return turn.role === "user" && (turn.kind ?? "message") === "message" || turn.blocks.some((block) => block.type === "ask_user_answer");
@@ -4350,7 +4378,7 @@ function upsertTurn(state, turn) {
   } else {
     existing.push(nextTurn);
   }
-  return withTurns(state, existing);
+  return withTurns({ ...state, turns: existing }, existing);
 }
 function applyTurnPatch(state, patch) {
   const turn = patch.data.turn;
@@ -4487,6 +4515,10 @@ var AgentSession = class _AgentSession {
   subscriptionQueue = Promise.resolve();
   replaceQueue = Promise.resolve();
   timelineEpoch = 0;
+  /** 定位请求的流水号：被后一次选择取代的那次定位不再提交窗口（见 locateEntry）。 */
+  locateToken = 0;
+  /** 在途那次定位的请求句柄。**只**服务定位：权威刷新不共用它（见 cancelPendingLocate）。 */
+  locateAbort = null;
   pagingGeneration = 0;
   liveRevision = 0;
   modeRevision = 0;
@@ -4522,11 +4554,19 @@ var AgentSession = class _AgentSession {
   seenToolCallIds = /* @__PURE__ */ new Set();
   finishedToolCallIds = /* @__PURE__ */ new Set();
   emittedMessageTurnIds = /* @__PURE__ */ new Set();
-  constructor(sessionId, runtime, connection) {
+  constructor(sessionId, runtime, connection, options = {}) {
     this.sessionId = sessionId;
     this.runtime = runtime;
     this.state = { ...createInitialSessionState(sessionId), connection };
+    this.isStatic = options.staticHistory === true;
   }
+  /**
+   * 静态历史（分享页 / `fromTurns`）：没有目录接口，也**没有**"目录还没到位"这个中间态。
+   *
+   * 宿主据此决定要不要拿已加载窗口当兜底条目——真实会话在 timeline 被重写后，窗口里还是
+   * 旧分支的发言，拿它兜底会把已经失效的 entry id 重新摆到轨道上，点了必然找不到。
+   */
+  isStatic;
   /** 从一份静态 turn 快照构造只展示历史的会话（例如公开分享页）。 */
   static fromTurns(sessionId, turns) {
     const readonlyError = () => {
@@ -4539,6 +4579,8 @@ var AgentSession = class _AgentSession {
         emitWithAck: async () => readonlyError(),
         ensureConnected: readonlyError,
         fetchTurnsPage: async () => ({ turns, nextBefore: null, currentMode: "executing" }),
+        // 静态会话（分享页）没有会话目录接口，宿主用已加载的历史兜底条目。
+        fetchTurnIndex: async () => ({ sessionId, items: [] }),
         fetchCommands: async () => [],
         // 静态历史没有回放身份可言，给个空详情即可，不要抛错——_bootstrap
         // 不会跑到这里，但保持只读语义一致。
@@ -4550,7 +4592,8 @@ var AgentSession = class _AgentSession {
         attachAppCli: async () => readonlyError(),
         onDispose: () => true
       },
-      "connected"
+      "connected",
+      { staticHistory: true }
     );
     session.state = {
       ...withTurns(session.state, turns),
@@ -4578,7 +4621,7 @@ var AgentSession = class _AgentSession {
     const epoch = this.timelineEpoch;
     const generation = this.pagingGeneration;
     this.update((state) => ({ ...state, loadingOlder: true }));
-    const request = this.runtime.fetchTurnsPage(this.sessionId, before).then((page) => {
+    const request = this.runtime.fetchTurnsPage(this.sessionId, { before }).then((page) => {
       if (epoch !== this.timelineEpoch || generation !== this.pagingGeneration || this.state.nextBefore !== before) return;
       options.beforeCommit?.();
       this.update((state) => ({
@@ -4586,10 +4629,11 @@ var AgentSession = class _AgentSession {
         nextBefore: page.nextBefore,
         loadingOlder: false
       }));
-    }).catch((error) => {
+    }).catch(async (error) => {
       if (isCursorInvalidError(error) && epoch === this.timelineEpoch && generation === this.pagingGeneration && this.state.nextBefore === before) {
-        this.timelineEpoch += 1;
-        return this.replaceFromHistory();
+        this.invalidateTimeline();
+        await this.replaceFromHistory();
+        return;
       }
     }).finally(() => {
       if (this.olderPending !== request) return;
@@ -4599,6 +4643,64 @@ var AgentSession = class _AgentSession {
     this.olderPending = request;
     return request;
   }
+  /**
+   * 定位到一条窗口外的历史发言：请服务端返回"从这条发言到最新"的窗口并整窗替换。
+   *
+   * 返回 false 表示这次定位没有落地（请求失败，或期间 timeline 被重写、会话已释放），
+   * 当前窗口保持不变，调用方可以原样重试。已加载的发言不要走这里——宿主直接滚动，
+   * 一次网络请求都不该发。
+   */
+  async locateEntry(entryId) {
+    const token = ++this.locateToken;
+    const controller = new AbortController();
+    this.locateAbort?.abort();
+    this.locateAbort = controller;
+    try {
+      return await this.replaceFromHistory({
+        suppressErrors: false,
+        fromEntryId: entryId,
+        signal: controller.signal,
+        isStale: () => this.locateToken !== token
+      });
+    } catch {
+      return false;
+    } finally {
+      if (this.locateAbort === controller) this.locateAbort = null;
+    }
+  }
+  /**
+   * 取消在途定位：用户改选了另一条发言（哪怕那条已经加载、不需要请求），
+   * 先前那次定位既不该再落地，也不该继续占着替换队列——排队中的下一次定位
+   * 不然要等它跑完（用户看到的是"点了新目标一直转圈"）。
+   *
+   * **只**中止定位自己的请求：权威刷新（运行结束 / 重连补数）不共用这个 controller，
+   * 否则"运行刚结束时点一下侧栏"就会把终态对账一起中止，流式与历史对不上。
+   */
+  cancelPendingLocate() {
+    this.locateToken += 1;
+    this.locateAbort?.abort();
+    this.locateAbort = null;
+  }
+  /**
+   * timeline 被整体改写（rewind / checkout / 释放）：推进纪元，并把在途定位请求一并中止
+   * ——它已经属于旧 timeline，却还占着替换队列，会让改写后的权威窗口排在后面等它跑完。
+   * 作废号仍然保留：中止只是让它更早结束。
+   */
+  invalidateTimeline() {
+    this.timelineEpoch += 1;
+    this.locateAbort?.abort();
+    this.locateAbort = null;
+  }
+  /**
+   * 拉取当前分支的用户发言目录（消息导航侧栏用）。
+   *
+   * 不在这里缓存：什么时候该刷新只有调用方知道（会话切换、历史被替换、新发言），
+   * 缓存只会让旧条目在 rewind 之后继续可点。
+   */
+  async loadTurnIndex() {
+    const index = await this.runtime.fetchTurnIndex(this.sessionId);
+    return index.items;
+  }
   /** 订阅状态变化。返回取消订阅函数。 */
   subscribe(listener) {
     this.listeners.add(listener);
@@ -4847,7 +4949,7 @@ var AgentSession = class _AgentSession {
       whatif: options.whatif,
       replay_decision: options.replayDecision,
       app_context: appContext,
-      kb_ids: options.kbIds && options.kbIds.length > 0 ? options.kbIds : void 0,
+      kb_ids: options.kbIds,
       // 运行中提交不必由客户端挑命令：服务端按会话运行状态决定直接执行还是入队。
       queue_when_running: options.queueWhenRunning === true
     };
@@ -4912,10 +5014,8 @@ var AgentSession = class _AgentSession {
     this.pendingReplayMode = void 0;
     this.pendingReplayKbIds = void 0;
     this.update((current) => {
-      let next = optimisticTurnId ? withTurns(
-        current,
-        current.turns.filter((turn) => turn.turn_id !== optimisticTurnId)
-      ) : current;
+      const filtered = optimisticTurnId ? current.turns.filter((turn) => turn.turn_id !== optimisticTurnId) : current.turns;
+      let next = optimisticTurnId ? withTurns({ ...current, turns: filtered }, filtered) : current;
       const toolCallId = askUserAnswer && typeof askUserAnswer.tool_call_id === "string" ? askUserAnswer.tool_call_id : null;
       if (toolCallId && next.askAnswers[toolCallId] === optimisticAskAnswer) {
         const askAnswers = { ...next.askAnswers };
@@ -5001,7 +5101,7 @@ var AgentSession = class _AgentSession {
     if (this.disposed) return;
     if (!this.runtime.onDispose(this)) return;
     this.disposed = true;
-    this.timelineEpoch += 1;
+    this.invalidateTimeline();
     this.invalidateOlderPaging();
     this.state = { ...this.state, nextBefore: null, loadingOlder: false };
     this.cancelPatchFlush();
@@ -5036,7 +5136,6 @@ var AgentSession = class _AgentSession {
   }
   /** @internal socket 重连后由 Hub 调用：重新加入房间并补数。 */
   _rejoinAfterReconnect() {
-    this.timelineEpoch += 1;
     this.invalidateOlderPaging();
     this.update((state) => ({ ...state, nextBefore: null, loadingOlder: false }));
     const reconnectLiveRevision = this.liveRevision;
@@ -5054,7 +5153,7 @@ var AgentSession = class _AgentSession {
           this.scheduleHistoricalCommandRestore(commandRecoveryGeneration);
         }
         await Promise.all([
-          this.replaceFromHistory({
+          this.refreshAuthoritativeHistory({
             liveRevisionAtStart: reconnectLiveRevision,
             modeRevisionAtStart: reconnectModeRevision
           }),
@@ -5216,7 +5315,7 @@ var AgentSession = class _AgentSession {
   }
   /** @internal */
   _handleRewind(checkpointId) {
-    this.timelineEpoch += 1;
+    this.invalidateTimeline();
     this.invalidateOlderPaging();
     this.update((s) => ({
       ...s,
@@ -5244,7 +5343,7 @@ var AgentSession = class _AgentSession {
           message,
           mode,
           replay_decision: decision,
-          kb_ids: kbIds && kbIds.length > 0 ? kbIds : void 0
+          kb_ids: kbIds
         },
         3e4
       ).then((response) => {
@@ -5314,7 +5413,7 @@ var AgentSession = class _AgentSession {
       this.update((s) => ({ ...s, status: "running", isStreaming: true }));
     } else if (this.state.isStreaming) {
       this.update((s) => ({ ...s, isStreaming: false }));
-      void this.replaceFromHistory({ liveRevisionAtStart: liveRevisionAtJoin });
+      void this.refreshAuthoritativeHistory({ liveRevisionAtStart: liveRevisionAtJoin });
     }
   }
   // ---------------------------------------------------------------- 内部实现
@@ -5335,7 +5434,7 @@ var AgentSession = class _AgentSession {
   completeChat(status) {
     this.finishStreaming(status);
     this.recentChatEndAt = Date.now();
-    void this.replaceFromHistory();
+    void this.refreshAuthoritativeHistory();
     this.emitter.emit("chatEnd", { status });
   }
   markTurnFresh(turnId) {
@@ -5519,8 +5618,32 @@ var AgentSession = class _AgentSession {
     this.update((s) => addErrorMessage(s, OOM_MESSAGE));
     this.emitter.emit("sandboxOom", { toolCallId: key });
   }
+  /**
+   * 权威刷新（运行结束 / 重连补数）：**按当前窗口第一条发言取窗口**，不再另记"用户想看哪段"。
+   *
+   * 窗口本身就是"用户在看哪段"：首屏就是最新一页，向上翻页 / 定位之后首条就是用户滚到的位置。
+   * 直接拿 `from_entry_id = 当前窗口第一条 turn_id` 去取，运行结束、重连补数、翻页之后的对账
+   * 是同一条规则，不需要意图、锚点、已落地锚点这些状态；窗口首条已经不在分支上（404 / 409）时
+   * 回落到最新一页。
+   */
+  refreshAuthoritativeHistory(options = {}) {
+    let entryGone = false;
+    const locateTokenAtStart = this.locateToken;
+    return this.replaceFromHistory({
+      ...options,
+      // 锚点在**这次操作真正开始**时采样：排队期间用户可能刚定位过，那时窗口首条才是他要的。
+      fromEntryId: () => this.state.turns[0]?.turn_id,
+      onError: (error) => {
+        entryGone = isEntryGoneError(error);
+      }
+    }).then((located) => {
+      if (located || !entryGone) return located;
+      if (this.locateToken !== locateTokenAtStart) return false;
+      return this.replaceFromHistory(options);
+    });
+  }
   replaceFromHistory(options = {}) {
-    if (this.disposed) return Promise.resolve();
+    if (this.disposed) return Promise.resolve(false);
     const operationEpoch = this.timelineEpoch;
     const liveRevisionAtStart = options.liveRevisionAtStart ?? this.liveRevision;
     const modeRevisionAtStart = options.modeRevisionAtStart ?? this.modeRevision;
@@ -5528,13 +5651,35 @@ var AgentSession = class _AgentSession {
     this.replaceInFlight += 1;
     const operation = async () => {
       let previousNextBefore = null;
+      const restoreCursor = () => {
+        if (this.disposed || previousNextBefore === null) return;
+        this.update((state) => ({
+          ...state,
+          nextBefore: previousNextBefore,
+          loadingOlder: false
+        }));
+      };
       try {
-        if (this.disposed || operationEpoch !== this.timelineEpoch) return;
+        if (this.disposed || operationEpoch !== this.timelineEpoch) return false;
+        if (options.isStale?.()) return false;
         this.invalidateOlderPaging();
         previousNextBefore = this.state.nextBefore;
         this.update((state) => ({ ...state, nextBefore: null, loadingOlder: false }));
-        const page = await this.runtime.fetchTurnsPage(this.sessionId);
-        if (this.disposed || operationEpoch !== this.timelineEpoch) return;
+        const signal = options.signal;
+        const fromEntryId = typeof options.fromEntryId === "function" ? options.fromEntryId() : options.fromEntryId;
+        const page = await this.runtime.fetchTurnsPage(
+          this.sessionId,
+          fromEntryId ? { fromEntryId } : void 0,
+          signal ? { signal } : void 0
+        );
+        if (this.disposed || operationEpoch !== this.timelineEpoch) {
+          restoreCursor();
+          return false;
+        }
+        if (options.isStale?.()) {
+          restoreCursor();
+          return false;
+        }
         if (!this.joined) this.seedToolCallDeliveryBaseline(page.turns);
         this.update((state) => {
           const next = withTurns(
@@ -5553,7 +5698,9 @@ var AgentSession = class _AgentSession {
         });
         this.pruneOptimisticLiveRevisions();
         this.projectionBuilder._seedTurns(this.state.turns);
+        return true;
       } catch (error) {
+        options.onError?.(error);
         if (!this.disposed && operationEpoch === this.timelineEpoch) {
           this.update((state) => ({
             ...state,
@@ -5562,6 +5709,7 @@ var AgentSession = class _AgentSession {
           }));
         }
         if (options.suppressErrors === false) throw error;
+        return false;
       } finally {
         this.replaceInFlight -= 1;
       }
@@ -5836,7 +5984,8 @@ var SessionHub = class {
         });
       }),
       ensureConnected: () => this.ensureConnected(),
-      fetchTurnsPage: (sessionId, before) => this.client.sessions.getSessionTurnsPage(sessionId, { before }),
+      fetchTurnsPage: (sessionId, query, init) => this.client.sessions.getSessionTurnsPage(sessionId, query, init),
+      fetchTurnIndex: (sessionId) => this.client.sessions.getSessionTurnIndex(sessionId),
       fetchCommands: (sessionId) => this.client.sessions.getSessionTurnCommands(sessionId),
       fetchSessionInfo: (sessionId) => this.client.sessions.getSession(sessionId),
       updateReplay: (sessionId, payload) => this.client.sessions.updateReplaySession(sessionId, payload).then((result) => result.replay_state ?? null),
@@ -6309,7 +6458,7 @@ var BladeClient = class {
       signal: init.signal
     });
     if (response.status === 401 && !isRetry && this.shouldRefreshFor401(url)) {
-      const refreshed = await this.tryRefresh();
+      const refreshed = await this.tryRefreshUnlessAborted(init.signal);
       if (refreshed) {
         return this.fetch(method, path, init, true);
       }
@@ -6363,6 +6512,27 @@ var BladeClient = class {
   hasExplicitBearerToken() {
     return Boolean(this.resolveRestToken());
   }
+  /**
+   * 等一次令牌刷新，但调用方中止请求时不再等下去。
+   *
+   * 刷新本身是共享的（`refreshPromise`，别的请求也在等它），这里只是让这次已被取消的
+   * 请求尽早结束——否则它会一直挂在调用方（定位）的串行队列里，用户改选的新目标要等到
+   * 刷新结束才轮得到。
+   */
+  async tryRefreshUnlessAborted(signal) {
+    if (!signal) return this.tryRefresh();
+    if (signal.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+      onAbort = () => reject(new DOMException("The operation was aborted.", "AbortError"));
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+      return await Promise.race([this.tryRefresh(), aborted]);
+    } finally {
+      if (onAbort) signal.removeEventListener("abort", onAbort);
+    }
+  }
   async tryRefresh() {
     if (this.refreshPromise) {
       return this.refreshPromise;
@@ -6618,7 +6788,7 @@ function resolveServiceUrl(endpoints, name, path = "") {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.70" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.71" : "1.1.1";
 
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
@@ -6771,8 +6941,10 @@ export {
   groupAdjacentContextRuns,
   groupMessagesByLoop,
   hasChatRunEvent,
+  inferToolStatus,
   isAppDevToolUiCard,
   isCommandEnvelope,
+  isEntryGoneError,
   isHiddenInternalMessage,
   isInboundEnvelope,
   isInternalStatusToolUiCard,