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

package/dist/resources/sessions.d.ts

@@ -204,6 +204,32 @@ export interface SessionTurnsPage {
     nextBefore: string | null;
     currentMode: "planning" | "executing";
 }
+/** `getSessionTurnsPage` 的取数参数：向后翻页（before）或从某条发言定位（fromEntryId）。 */
+export interface SessionTurnsQuery {
+    limit?: number;
+    before?: string;
+    /**
+     * 从这条用户发言开始、一直到最新。服务端按当前分支校验它，命中不了不会回空页
+     * （`entry_not_found` / `entry_not_in_branch`），窗口首条就是这条发言，它的
+     * `nextBefore` 可以继续当 `before` 往上翻。
+     */
+    fromEntryId?: string;
+}
+/**
+ * 服务端明确说这条发言不在当前分支上（`entry_not_found` / `entry_not_in_branch`），
+ * 和"这次没取到"（网络 / 5xx / 鉴权）分开：前者说明这个定位目标已经没了，后者只说明这次失败。
+ */
+export declare function isEntryGoneError(error: unknown): boolean;
+/** 侧栏「消息历史」的一条：只有 id、标题和时间，没有消息体。 */
+export interface SessionTurnIndexItem {
+    entryId: string;
+    preview: string;
+    createdAt: string | null;
+}
+export interface SessionTurnIndex {
+    sessionId: string;
+    items: SessionTurnIndexItem[];
+}
 export interface HistoricalCommand {
     deliveryId: string;
     toolCallId?: string;
@@ -407,10 +433,14 @@ export declare class SessionsResource {
     getSharedSession(token: string): Promise<TurnProjection[]>;
     getSessionTasks(sessionId: string): Promise<Task[]>;
     getSessionTurns(sessionId: string): Promise<TurnProjection[]>;
-    getSessionTurnsPage(sessionId: string, options?: {
-        limit?: number;
-        before?: string;
-    }): Promise<SessionTurnsPage>;
+    getSessionTurnsPage(sessionId: string, options?: SessionTurnsQuery, init?: RequestInit): Promise<SessionTurnsPage>;
+    /**
+     * 当前分支上可导航的用户发言目录（消息导航侧栏）。
+     *
+     * 只回 id、标题和时间：侧栏要列的是**整条会话**的发言，而窗口外的发言 id 只能
+     * 从服务端拿；消息体仍然走 `/turns`。
+     */
+    getSessionTurnIndex(sessionId: string): Promise<SessionTurnIndex>;
     getMcpAppContext(sessionId: string, sourceId: string, init?: RequestInit): Promise<McpAppContextState>;
     updateMcpAppContext(sessionId: string, sourceId: string, body: McpAppContextUpdate, init?: RequestInit): Promise<{
         status: "accepted";

package/dist/schemas/message-utils.d.ts

@@ -5,6 +5,14 @@ export declare function normalizeMessageContent(content: unknown): MessageConten
 export declare function getTextContent(content: MessageContent): string;
 export declare function isSystemReminderText(text: string): boolean;
 export declare function isLegacyForkContextText(text: string): boolean;
+/**
+ * 平台自己写进去、不该露给用户的内部提示。
+ *
+ * 服务端的消息导航目录有一份同名同语义的 Python 实现
+ * （`server/.../routes/sessions.py` 的 `_is_hidden_internal_message`）：客户端靠它决定
+ * 渲染不渲染，服务端靠它决定进不进目录。改这里必须同时改那边，否则目录会列出没有对应
+ * 行的死条目，或者把内部提示原文当标题露出去。
+ */
 export declare function isHiddenInternalMessage(message: Pick<ChatMessage, "role" | "content">, options?: {
     includeLegacyForkContext?: boolean;
 }): boolean;

package/dist/session/agent-session.d.ts

@@ -4,7 +4,7 @@ import type { PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
 import { type CommandHandler } from "../commands/registry";
 import { type AgentSessionEvents } from "./events";
-import type { AppCliAttachment, AppCliDefinition, FileEntry, HistoricalCommand, SessionTurnsPage } from "../resources/sessions";
+import type { AppCliAttachment, AppCliDefinition, FileEntry, HistoricalCommand, SessionTurnIndex, SessionTurnIndexItem, SessionTurnsPage, SessionTurnsQuery } from "../resources/sessions";
 import { type QueueOperationResult } from "./queue";
 import { type ConnectionStatus, type SessionState } from "./state";
 /** SessionHub 注入给 AgentSession 的运行时依赖（socket 收发 + REST 补数）。 */
@@ -12,7 +12,8 @@ export interface SessionRuntime {
     emitEvent(event: string, data: unknown): void;
     emitWithAck(event: string, data: unknown, timeoutMs: number): Promise<Record<string, unknown> | undefined>;
     ensureConnected(): void;
-    fetchTurnsPage(sessionId: string, before?: string): Promise<SessionTurnsPage>;
+    fetchTurnsPage(sessionId: string, query?: SessionTurnsQuery, init?: RequestInit): Promise<SessionTurnsPage>;
+    fetchTurnIndex(sessionId: string): Promise<SessionTurnIndex>;
     fetchCommands(sessionId: string): Promise<HistoricalCommand[]>;
     /** 会话详情，目前只用来取回放状态。 */
     fetchSessionInfo(sessionId: string): Promise<{
@@ -54,7 +55,7 @@ export interface SendOptions {
         deprecate_entry_ids: string[];
     };
     replayDecision?: "keep_replay" | "continue_replay";
-    /** 用户 @ 的知识库 id：后端先用原话在这些库里预检索，本轮 kb_search 也默认限定在这些库。 */
+    /** 用户显式选择的知识库 id；后端将元信息作为 once Context 提供给模型。 */
     kbIds?: number[];
     /**
      * 声明"会话在跑就把这条消息放进等待队列"。默认不排队、运行中直接报错：
@@ -86,6 +87,10 @@ export declare class AgentSession {
     private subscriptionQueue;
     private replaceQueue;
     private timelineEpoch;
+    /** 定位请求的流水号：被后一次选择取代的那次定位不再提交窗口（见 locateEntry）。 */
+    private locateToken;
+    /** 在途那次定位的请求句柄。**只**服务定位：权威刷新不共用它（见 cancelPendingLocate）。 */
+    private locateAbort;
     private pagingGeneration;
     private liveRevision;
     private modeRevision;
@@ -114,7 +119,16 @@ export declare class AgentSession {
     private readonly seenToolCallIds;
     private readonly finishedToolCallIds;
     private readonly emittedMessageTurnIds;
-    constructor(sessionId: string, runtime: SessionRuntime, connection: ConnectionStatus);
+    constructor(sessionId: string, runtime: SessionRuntime, connection: ConnectionStatus, options?: {
+        staticHistory?: boolean;
+    });
+    /**
+     * 静态历史（分享页 / `fromTurns`）：没有目录接口，也**没有**"目录还没到位"这个中间态。
+     *
+     * 宿主据此决定要不要拿已加载窗口当兜底条目——真实会话在 timeline 被重写后，窗口里还是
+     * 旧分支的发言，拿它兜底会把已经失效的 entry id 重新摆到轨道上，点了必然找不到。
+     */
+    readonly isStatic: boolean;
     /** 从一份静态 turn 快照构造只展示历史的会话（例如公开分享页）。 */
     static fromTurns(sessionId: string, turns: TurnProjection[]): AgentSession;
     /** 返回当前会话快照。引用稳定：状态未变化时返回同一对象。 */
@@ -124,6 +138,36 @@ export declare class AgentSession {
     loadOlderHistory(options?: {
         beforeCommit?: () => void;
     }): Promise<void>;
+    /**
+     * 定位到一条窗口外的历史发言：请服务端返回"从这条发言到最新"的窗口并整窗替换。
+     *
+     * 返回 false 表示这次定位没有落地（请求失败，或期间 timeline 被重写、会话已释放），
+     * 当前窗口保持不变，调用方可以原样重试。已加载的发言不要走这里——宿主直接滚动，
+     * 一次网络请求都不该发。
+     */
+    locateEntry(entryId: string): Promise<boolean>;
+    /**
+     * 取消在途定位：用户改选了另一条发言（哪怕那条已经加载、不需要请求），
+     * 先前那次定位既不该再落地，也不该继续占着替换队列——排队中的下一次定位
+     * 不然要等它跑完（用户看到的是"点了新目标一直转圈"）。
+     *
+     * **只**中止定位自己的请求：权威刷新（运行结束 / 重连补数）不共用这个 controller，
+     * 否则"运行刚结束时点一下侧栏"就会把终态对账一起中止，流式与历史对不上。
+     */
+    cancelPendingLocate(): void;
+    /**
+     * timeline 被整体改写（rewind / checkout / 释放）：推进纪元，并把在途定位请求一并中止
+     * ——它已经属于旧 timeline，却还占着替换队列，会让改写后的权威窗口排在后面等它跑完。
+     * 作废号仍然保留：中止只是让它更早结束。
+     */
+    private invalidateTimeline;
+    /**
+     * 拉取当前分支的用户发言目录（消息导航侧栏用）。
+     *
+     * 不在这里缓存：什么时候该刷新只有调用方知道（会话切换、历史被替换、新发言），
+     * 缓存只会让旧条目在 rewind 之后继续可点。
+     */
+    loadTurnIndex(): Promise<SessionTurnIndexItem[]>;
     /** 订阅状态变化。返回取消订阅函数。 */
     subscribe(listener: () => void): () => void;
     private setState;
@@ -289,6 +333,15 @@ export declare class AgentSession {
     private deliverCommand;
     private deliverCommandNow;
     private notifySandboxOom;
+    /**
+     * 权威刷新（运行结束 / 重连补数）：**按当前窗口第一条发言取窗口**，不再另记"用户想看哪段"。
+     *
+     * 窗口本身就是"用户在看哪段"：首屏就是最新一页，向上翻页 / 定位之后首条就是用户滚到的位置。
+     * 直接拿 `from_entry_id = 当前窗口第一条 turn_id` 去取，运行结束、重连补数、翻页之后的对账
+     * 是同一条规则，不需要意图、锚点、已落地锚点这些状态；窗口首条已经不在分支上（404 / 409）时
+     * 回落到最新一页。
+     */
+    private refreshAuthoritativeHistory;
     private replaceFromHistory;
     private invalidateOlderPaging;
     private beginCommandRecovery;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blade-hq/agent-client",
-  "version": "2610.0.0-beta.70",
+  "version": "2610.0.0-beta.71",
   "description": "Blade Agent 框架无关客户端：会话实时状态机、REST 通道、弹窗登录、页面协作。浏览器与 Node.js 通用。",
   "repository": {
     "type": "git",

package/public-api.md

@@ -3,7 +3,7 @@
 > 本文件由 `scripts/public-api-report.mjs` 生成，请勿手改。
 > 公共面变更时重新生成本报告，并同步更新 README 对应章节——CI 会校验两者。
 
-共 223 个公开声明。
+共 244 个公开声明。
 
 ## `acceptedPostChatFollowupCompletesLatestRun` (function)
 
@@ -71,6 +71,7 @@ toolCallId: string
 ```ts
 attach: (label: string, data: unknown) => void
 attachApp: (options: AttachAppOptions) => Promise<AppCliAttachment | null>
+cancelPendingLocate: () => void
 cancelQueuedMessage: (itemId: string, expectedVersion?: number) => Promise<QueueOperationResult>
 compact: () => Promise<Record<string, unknown>>
 countFiles: (dirPath?: string) => Promise<number>
@@ -82,8 +83,11 @@ getState: () => SessionState
 hasOlderHistory: boolean
 insertText: (text: string) => void
 isDisposed: boolean
+isStatic: boolean
 listDir: (dirPath?: string) => Promise<FileEntry[]>
 loadOlderHistory: (options?: { beforeCommit?: () => void; }) => Promise<void>
+loadTurnIndex: () => Promise<SessionTurnIndexItem[]>
+locateEntry: (entryId: string) => Promise<boolean>
 off: <K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void) => void
 on: <K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void) => () => void
 onCommand: (action: string, handler: CommandHandler) => () => void
@@ -341,6 +345,13 @@ canEditQueuedMessage: (item: QueuedMessage) => boolean
 canToggleComputer: (computer: SessionComputer) => boolean
 ```
 
+## `ChatEnd` (interface)
+
+```ts
+duration_ms: number
+status: string
+```
+
 ## `chatErrorForDisplay` (function)
 
 ```ts
@@ -508,6 +519,13 @@ tool_name: string | null | undefined
 type: "text" | "thinking" | "tool_use" | "tool_result" | "tool_ui" | "tool_bridge" | "system_notification" | "mode_change" | "plan_status" | "ask_user_answer"
 ```
 
+## `ContentDelta` (interface)
+
+```ts
+content: string
+loop_name: string | undefined
+```
+
 ## `contentPreview` (function)
 
 ```ts
@@ -840,6 +858,12 @@ direction: "host-to-agent"
 payload: unknown
 ```
 
+## `inferToolStatus` (function)
+
+```ts
+inferToolStatus: (resultStr: string) => "done" | "error" | "cancelled"
+```
+
 ## `InlineToolUiCardEntry` (interface)
 
 ```ts
@@ -860,6 +884,12 @@ isAppDevToolUiCard: (card: ToolUiCard, isAppDev: boolean) => boolean
 isCommandEnvelope: (value: unknown) => value is CommandEnvelope
 ```
 
+## `isEntryGoneError` (function)
+
+```ts
+isEntryGoneError: (error: unknown) => boolean
+```
+
 ## `isHiddenInternalMessage` (function)
 
 ```ts
@@ -925,6 +955,16 @@ byTurnId: ReadonlyMap<string, number>
 current: number
 ```
 
+## `LlmResponseDone` (interface)
+
+```ts
+content: string | null | undefined
+loop_name: string | undefined
+reasoning: string | null | undefined
+role: string
+tool_calls: { id: string; function: { name: string; arguments: string; }; }[] | undefined
+```
+
 ## `loadPlatformEndpoints` (function)
 
 ```ts
@@ -1102,6 +1142,14 @@ sequence: number
 turn_id: string
 ```
 
+## `PendingQuestionRef` (interface)
+
+```ts
+child_loop_name: string
+child_tool_call_id: string
+description: string | null | undefined
+```
+
 ## `PlatformEndpoints` (interface)
 
 ```ts
@@ -1204,6 +1252,21 @@ title: string
 version: number
 ```
 
+## `PrimarySkillStageSpec` (interface)
+
+```ts
+id: string
+name: string
+steps: PrimarySkillStepSpec[]
+```
+
+## `PrimarySkillStepSpec` (interface)
+
+```ts
+label: string
+n: number
+```
+
 ## `ProvidersResponse` (interface)
 
 ```ts
@@ -1390,6 +1453,17 @@ result: unknown
 sessionId: string
 ```
 
+## `RunTiming` (interface)
+
+```ts
+duration_ms: number | null | undefined
+loop_id: string
+run_id: string
+scope: "chat" | "subagent"
+started_at: string | null | undefined
+status: "completed" | "paused" | "failed" | "cancelled" | "incomplete"
+```
+
 ## `RunTrace` (interface)
 
 ```ts
@@ -1691,6 +1765,13 @@ revision: number
 session_id: string
 ```
 
+## `SessionSearchMatch` (interface)
+
+```ts
+field: "title" | "content"
+snippet: { role: string; text: string; } | null
+```
+
 ## `SessionSetupError` (class)
 
 ```ts
@@ -1739,8 +1820,9 @@ getSessionHistory: (sessionId: string, init?: RequestInit) => Promise<SessionHis
 getSessionPluginConfig: (sessionId: string, name: string, init?: RequestInit) => Promise<{ plugin: string; config: SessionPluginConfigState; }>
 getSessionTasks: (sessionId: string) => Promise<Task[]>
 getSessionTurnCommands: (sessionId: string) => Promise<HistoricalCommand[]>
+getSessionTurnIndex: (sessionId: string) => Promise<SessionTurnIndex>
 getSessionTurns: (sessionId: string) => Promise<TurnProjection[]>
-getSessionTurnsPage: (sessionId: string, options?: { limit?: number; before?: string; }) => Promise<SessionTurnsPage>
+getSessionTurnsPage: (sessionId: string, options?: SessionTurnsQuery, init?: RequestInit) => Promise<SessionTurnsPage>
 getSharedSession: (token: string) => Promise<TurnProjection[]>
 importSession: (file: File, name?: string, solutionOverride?: string | null | ImportSessionOptions) => Promise<{ session_id: string; }>
 listBackgroundTasks: (sessionId: string, init?: RequestInit) => Promise<BackgroundTask[]>
@@ -1808,6 +1890,28 @@ SessionStatus = type(
 )
 ```
 
+## `SessionStatusEvent` (interface)
+
+```ts
+session_id: string
+status: string
+```
+
+## `SessionTurnIndex` (interface)
+
+```ts
+items: SessionTurnIndexItem[]
+sessionId: string
+```
+
+## `SessionTurnIndexItem` (interface)
+
+```ts
+createdAt: string | null
+entryId: string
+preview: string
+```
+
 ## `SessionTurnsPage` (interface)
 
 ```ts
@@ -1816,6 +1920,14 @@ nextBefore: string | null
 turns: TurnProjection[]
 ```
 
+## `SessionTurnsQuery` (interface)
+
+```ts
+before: string | undefined
+fromEntryId: string | undefined
+limit: number | undefined
+```
+
 ## `ShareLinkResult` (interface)
 
 ```ts
@@ -1855,6 +1967,12 @@ files: TextFile[]
 name: string
 ```
 
+## `SkillEditorTemplateId` (type)
+
+```ts
+export type SkillEditorTemplateId = "skill_editor"
+```
+
 ## `SkillMentionAvailability` (interface)
 
 ```ts
@@ -1938,6 +2056,12 @@ export type SolutionRef = ExistingSolutionRef | PreparedSolutionAsset
 sortComputers: (computers: SessionComputer[]) => SessionComputer[]
 ```
 
+## `SystemError` (interface)
+
+```ts
+message: string
+```
+
 ## `Task` (type)
 
 ```ts
@@ -1998,6 +2122,25 @@ action: string
 payload: unknown
 ```
 
+## `ToolCallArgumentsDelta` (interface)
+
+```ts
+arguments_delta: string
+function: { name: string; }
+id: string
+index: number
+loop_name: string | undefined
+```
+
+## `ToolCallCreated` (interface)
+
+```ts
+function: { name: string; arguments: string; }
+id: string
+index: number
+loop_name: string | undefined
+```
+
 ## `ToolCallInfo` (interface)
 
 ```ts
@@ -2011,6 +2154,40 @@ result: unknown
 status: "done" | "error" | "cancelled" | "awaiting_answer" | "pending" | undefined
 ```
 
+## `ToolCallProjection` (interface)
+
+```ts
+arguments: string
+display_name: string
+duration_ms: number | null | undefined
+id: string
+pending_question_ref: PendingQuestionRef | null | undefined
+ran_in_parallel: boolean | undefined
+result: unknown
+started_at: string | null | undefined
+status: string
+subagent_runs: RunTiming[] | undefined
+tool_name: string
+```
+
+## `ToolResultDelta` (interface)
+
+```ts
+content: string
+loop_name: string | undefined
+stream: "stdout" | "stderr" | undefined
+tool_call_id: string
+```
+
+## `ToolResultDone` (interface)
+
+```ts
+content: string
+function: { name: string; }
+loop_name: string | undefined
+tool_call_id: string
+```
+
 ## `ToolUiCard` (interface)
 
 ```ts