@blade-hq/agent-client 2610.0.0-rc.0 → 2610.0.0

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

@@ -4,14 +4,17 @@ 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 } 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 补数）。 */
 export interface SessionRuntime {
     emitEvent(event: string, data: unknown): void;
     emitWithAck(event: string, data: unknown, timeoutMs: number): Promise<Record<string, unknown> | undefined>;
     ensureConnected(): void;
-    fetchTurns(sessionId: string): Promise<TurnProjection[]>;
+    fetchTurnsPage(sessionId: string, query?: SessionTurnsQuery, init?: RequestInit): Promise<SessionTurnsPage>;
+    fetchTurnIndex(sessionId: string): Promise<SessionTurnIndex>;
+    fetchCommands(sessionId: string): Promise<HistoricalCommand[]>;
     /** 会话详情，目前只用来取回放状态。 */
     fetchSessionInfo(sessionId: string): Promise<{
         replay_state?: ReplayState | null;
@@ -52,8 +55,13 @@ export interface SendOptions {
         deprecate_entry_ids: string[];
     };
     replayDecision?: "keep_replay" | "continue_replay";
-    /** 用户 @ 的知识库 id：后端先用原话在这些库里预检索，本轮 kb_search 也默认限定在这些库。 */
+    /** 用户显式选择的知识库 id；后端将元信息作为 once Context 提供给模型。 */
     kbIds?: number[];
+    /**
+     * 声明"会话在跑就把这条消息放进等待队列"。默认不排队、运行中直接报错：
+     * 是否真的入队由服务端按运行状态判定（等待回答时发送即作答，不会被误排队）。
+     */
+    queueWhenRunning?: boolean;
 }
 export declare function sessionStatusFromChatEnd(status: string | undefined): SessionStatus;
 /**
@@ -77,11 +85,43 @@ export declare class AgentSession {
     private joined;
     private joinPending;
     private subscriptionQueue;
+    private replaceQueue;
+    private timelineEpoch;
+    /** 定位请求的流水号：被后一次选择取代的那次定位不再提交窗口（见 locateEntry）。 */
+    private locateToken;
+    /** 在途那次定位的请求句柄。**只**服务定位：权威刷新不共用它（见 cancelPendingLocate）。 */
+    private locateAbort;
+    private pagingGeneration;
+    private liveRevision;
+    private modeRevision;
+    private readonly liveRevisions;
+    private readonly pendingOptimisticTurnIds;
+    private olderPending;
+    private replaceInFlight;
     private replayQueue;
+    private commandRestoreQueue;
+    private commandRecoveryGeneration;
+    private commandRestoreRetryAttempt;
+    private commandRestoreRetryHandle;
+    private bufferedCommandDeliveries;
     private pendingReplayMessage;
     private pendingReplayMode;
     private pendingReplayKbIds;
     private recentChatEndAt;
+    /**
+     * 最近一次已经通过 `error` 事件投递过的服务端失败（`message` + `code`）。
+     *
+     * `chat:send` 被代理时服务端会先发 `system:error`、再用同一条失败回 ack，两条
+     * 通道都会到达这里：前者走 `_handleSystemError`，后者走发送失败的回滚。不去重
+     * 的话调用方会收到两次同一个 `error`（重复提示、重试逻辑跑两遍）。
+     *
+     * 带代际边界，只认「本次 `emitWithAck` 等待期间」投递的那一条：否则队列/停止
+     * 失败留下的标记会一直挂着，之后一次无关的订阅失败只是文案码相同就被当成
+     * 重复而静音。用单调递增的代际号而不是时间戳，同一毫秒内的两条也不会混淆。
+     */
+    private lastDeliveredSystemError;
+    /** 每次投递 `system:error` 递增，用于判定某条失败是否属于本次等待。 */
+    private systemErrorGeneration;
     private subscriptionReplaySource;
     private disposed;
     private getAppContext;
@@ -93,11 +133,55 @@ 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;
     /** 返回当前会话快照。引用稳定：状态未变化时返回同一对象。 */
     getState(): SessionState;
+    get hasOlderHistory(): boolean;
+    /** Load the page immediately preceding the current display window. */
+    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;
@@ -120,10 +204,44 @@ export declare class AgentSession {
     attachApp(options: AttachAppOptions): Promise<AppCliAttachment | null>;
     /** 发送一条消息。字符串或多模态内容均可。 */
     send(content: MessageContent, options?: SendOptions): Promise<boolean>;
+    /**
+     * 入队一条等待消息（运行中排队 / 暂停期间照常入队）。
+     *
+     * ack 超时或传输失败时结果未知：用**同一个** `client_request_id` 重试一次，
+     * 服务端按 `(session_id, client_request_id)` 幂等，不会制造第二条。
+     */
+    queueMessage(content: string): Promise<QueueOperationResult>;
+    /** 修改一条等待消息的正文；`expectedVersion` 是客户端看到的条目版本。 */
+    updateQueuedMessage(itemId: string, expectedVersion: number, content: string): Promise<QueueOperationResult>;
+    /**
+     * 重排等待消息。`orderedIds` 必须是当前 pending 条目 id 的**完整集合**（顺序任意），
+     * 服务端按 `expectedRevision` 校验后整体替换顺序。
+     *
+     * 拖动排序就该像本地操作一样落地：版本冲突（运行中的任务刚领走一条 / 另一个端也在
+     * 动队列）不甩给用户「刷新后重试」，而是拿冲突响应里那份**最新快照**重算一次再提交
+     * ——掉队的条目（已经被领取执行的）从顺序里剔除，剩下的保持用户拖出来的相对次序。
+     * 最多补两次；仍旧冲突才把结果交回调用方。
+     */
+    reorderQueuedMessages(expectedRevision: number, orderedIds: string[]): Promise<QueueOperationResult>;
+    /** 删除一条等待消息；不传版本时由服务端自行判定。 */
+    cancelQueuedMessage(itemId: string, expectedVersion?: number): Promise<QueueOperationResult>;
+    /** 立即补充：把等待消息交给当前运行，在下一个接收点消费，不停止也不另起一轮。 */
+    deliverQueuedMessage(itemId: string, expectedVersion: number): Promise<QueueOperationResult>;
+    /** 继续执行：清除暂停，并按当前顺序恢复逐条接续。 */
+    resumeQueue(): Promise<QueueOperationResult>;
+    /** 拉取一份权威队列快照。首次连接与每次重连后由实例自动调用，也可以手动刷新。 */
+    refreshQueue(): Promise<QueueOperationResult>;
+    /**
+     * 发出一条队列命令并安装 ack 里的快照。
+     * 传输层失败（超时 / 断线）会 reject，由调用方决定是否重试。
+     */
+    private requestQueueAck;
+    /** 队列命令的对外入口：传输失败只体现为失败结果，不向调用方抛异常。 */
+    private runQueueCommand;
     private sendUnlocked;
     private rollbackOptimisticSend;
-    /** 智能体运行期间追加补充说明（不打断当前回复）。 */
-    append(text: string): void;
+    /** 撤回一次乐观提交：移除乐观消息、恢复提问作答、清掉回放草稿。 */
+    private discardOptimisticSend;
     /** 停止当前回复。 */
     stop(): Promise<Record<string, unknown>>;
     /** 手动触发上下文压缩。 */
@@ -150,6 +268,11 @@ export declare class AgentSession {
     get isDisposed(): boolean;
     /** @internal 连接状态变化（同 client 下所有会话共享一条连接）。 */
     _setConnection(connection: ConnectionStatus): void;
+    /**
+     * @internal 服务端广播的权威队列快照。
+     * 结构不合法或 revision 不新的一律丢弃，绝不用旧快照覆盖新状态。
+     */
+    _handleQueueUpdated(payload: unknown): void;
     /** @internal socket 重连后由 Hub 调用：重新加入房间并补数。 */
     _rejoinAfterReconnect(): Promise<void>;
     /** @internal 首次连接：加载历史 + 加入房间。 */
@@ -179,13 +302,15 @@ export declare class AgentSession {
     /** @internal */
     _handleChatEnd(status: string): void;
     /** @internal */
-    _handleSystemError(message: string): void;
+    _handleSystemError(message: string, code?: string): void;
     /** @internal */
     _handleTaskUpdated(tasks: unknown[]): void;
     /** @internal */
     _handleWorkspaceFilesChanged(filePath?: string): void;
     /** @internal */
     _handleSessionUpdated(data: {
+        workspace_path?: string;
+        chat_group_id?: string | null;
         intent?: string;
         status?: SessionStatus;
         model?: string | null;
@@ -206,10 +331,13 @@ export declare class AgentSession {
     /** @internal */
     _handleArtifact(event: AgentSessionEvents["artifact"]): void;
     /** @internal 加入房间的应答里带 is_running，据此校准流式状态。 */
-    _applyRunningState(isRunning: boolean): void;
+    _applyRunningState(isRunning: boolean, liveRevisionAtJoin?: number): void;
     private markRunningIfIdle;
     private finishStreaming;
     private completeChat;
+    private markTurnFresh;
+    private markOptimisticTurnPending;
+    private pruneOptimisticLiveRevisions;
     private applyTurn;
     private schedulePatchFlush;
     private cancelPatchFlush;
@@ -217,20 +345,26 @@ export declare class AgentSession {
     /** turn 数据落地后统一派生语义事件（指令 / 工具调用 / 消息 / 模式 / 预览 / OOM）。 */
     private emitTurnDerivedEvents;
     private dispatchCommand;
+    private dispatchRawCommands;
+    private deliverCommand;
+    private deliverCommandNow;
     private notifySandboxOom;
-    private syncTurnsFromHistory;
-    /** 首次订阅前的 REST 历史建立语义事件基线，随后同一工具的订阅回放不再投递。 */
-    private seedToolCallDeliveryBaseline;
     /**
-     * 把历史里的指令补投给宿主页面。
+     * 权威刷新（运行结束 / 重连补数）：**按当前窗口第一条发言取窗口**，不再另记"用户想看哪段"。
      *
-     * 重开会话、断线补数时，地图高亮这类"页面当前状态"必须能恢复——
-     * 否则刷新一次页面，之前智能体让页面做的事就全丢了。
-     * 只回放指令：toolCall / message 这些事件如果按历史全量重放，
-     * 监听器会在挂载瞬间收到几百条陈年事件。
-     * dispatch 内部按 deliveredCommandKeys 去重，重复调用安全。
+     * 窗口本身就是"用户在看哪段"：首屏就是最新一页，向上翻页 / 定位之后首条就是用户滚到的位置。
+     * 直接拿 `from_entry_id = 当前窗口第一条 turn_id` 去取，运行结束、重连补数、翻页之后的对账
+     * 是同一条规则，不需要意图、锚点、已落地锚点这些状态；窗口首条已经不在分支上（404 / 409）时
+     * 回落到最新一页。
      */
-    private replayCommandsFromTurns;
+    private refreshAuthoritativeHistory;
+    private replaceFromHistory;
+    private invalidateOlderPaging;
+    private beginCommandRecovery;
+    private scheduleHistoricalCommandRestore;
+    private flushBufferedCommands;
+    /** 首次订阅前的 REST 历史建立语义事件基线，随后同一工具的订阅回放不再投递。 */
+    private seedToolCallDeliveryBaseline;
     private ensureJoined;
     private ensureIdleBeforeSend;
 }

package/dist/session/definition.d.ts

@@ -11,11 +11,16 @@ export type SolutionDefinition = {
     files: TextFile[];
     role?: string;
 };
+export type SkillFile = TextFile & {
+    /** 二进制内容使用 base64；省略时为 UTF-8 文本。 */
+    encoding?: "utf-8" | "base64";
+    executable?: boolean;
+};
 export interface SkillDefinition {
     /** 会话内安装名，格式为 `组织/名称`。 */
     name: string;
     /** 必须包含根目录的 SKILL.md。 */
-    files: TextFile[];
+    files: SkillFile[];
 }
 export interface SessionConfig {
     /** Server 模型目录中的 model ID。 */

package/dist/session/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 一次会话操作的失败。
+ *
+ * `code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken`），
+ * 调用方据此决定要不要重试；`message` 是可以直接展示的业务文案，不要当协议解析。
+ */
+export declare class AgentSessionError extends Error {
+    readonly name = "AgentSessionError";
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}

package/dist/session/events.d.ts

@@ -1,4 +1,5 @@
 import type { ChatMessage, ToolCallInfo } from "../schemas/message";
+import type { McpAppData } from "../schemas/mcp-app";
 import type { TurnProjection } from "../schemas/projection";
 import type { SessionStatus } from "../schemas/session";
 /**
@@ -30,9 +31,15 @@ export interface AgentSessionEvents {
     chatEnd: {
         status: string;
     };
-    /** 运行错误（system:error、发送失败等）。 */
+    /**
+     * 运行错误（system:error、发送失败等）。
+     *
+     * `code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken`），
+     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
+     */
     error: {
         message: string;
+        code?: string;
     };
     /** planning / executing 模式切换。 */
     modeChange: {
@@ -76,10 +83,13 @@ export interface AgentSessionEvents {
     };
     /** 工具返回值带 _meta.ui 的可视化预览（resource HTML / URI）。 */
     toolPreview: {
+        /** Source file identity when the preview comes from a local HTML file. */
+        sourcePath?: string;
         toolCallId: string;
-        type: "resource-html" | "resource-uri";
+        type: "resource-html" | "resource-uri" | "resource-file";
         content: string;
         title: string;
+        mcpApp?: McpAppData;
     };
     /** 任务清单（TaskCreate 等）更新。 */
     taskListUpdated: {
@@ -108,6 +118,8 @@ export interface AgentSessionEvents {
     };
     /** 会话属性（名称、状态、绑定技能等）被服务端更新。 */
     sessionUpdated: {
+        workspacePath?: string;
+        chatGroupId?: string | null;
         intent?: string;
         status?: SessionStatus;
         model?: string | null;

package/dist/session/history-page.d.ts

@@ -0,0 +1,9 @@
+import type { TurnProjection } from "../schemas/projection";
+export interface LiveRevisionState {
+    current: number;
+    byTurnId: ReadonlyMap<string, number>;
+}
+/** Add an older authoritative slice without allowing it to roll back live content. */
+export declare function prependOlder(current: TurnProjection[], page: TurnProjection[]): TurnProjection[];
+/** Install a new authoritative window, retaining only live writes newer than the request. */
+export declare function replaceWindow(current: TurnProjection[], page: TurnProjection[], liveRevisionAtStart: number, liveRevisions: LiveRevisionState): TurnProjection[];

package/dist/session/hub.d.ts

@@ -22,6 +22,7 @@ export declare class SessionHub {
     private readonly connectionListeners;
     private bound;
     private hasConnected;
+    private readonly authBusyReconnect;
     constructor(client: BladeClient);
     /** 当前 Socket.IO 连接状态。 */
     getConnection(): ConnectionStatus;

package/dist/session/queue.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 会话消息队列的共享领域模型：类型、快照合并规则与中文文案。
+ *
+ * 这里是**单一定义处**：AgentSession 的状态机、agent-react 与内置 Web 的队列 UI
+ * 都只用这一份判定，避免"能不能编辑 / 旧快照要不要覆盖"各写一遍后各自演进。
+ * 服务端语义见 issue #2529 与 local://frontend-queue-contract.md。
+ */
+/** 等待消息的服务端生命周期状态。 */
+export type QueuedMessageStatus = "pending" | "delivering" | "claimed" | "consumed" | "cancelled";
+/** 队列里的一条等待消息；权威快照只包含 pending（等待执行）与 delivering（等待接收）。 */
+export interface QueuedMessage {
+    id: string;
+    content: string;
+    position: number;
+    version: number;
+    status: QueuedMessageStatus;
+    created_at: string;
+    updated_at: string;
+    /** 立即补充指向的当前运行 id；普通等待条目没有。 */
+    target_run_id?: string;
+    /** 领取或投递失败的原因。 */
+    error?: string;
+}
+/** 服务端权威队列快照。`revision` 单调递增，客户端据此丢弃过期快照。 */
+export interface SessionQueueSnapshot {
+    session_id: string;
+    revision: number;
+    paused: boolean;
+    pause_reason: string | null;
+    items: QueuedMessage[];
+}
+/**
+ * 还没有拿到服务端快照时的占位。
+ *
+ * `session_id` 为空表示"身份未知"：`shouldApplySnapshot` 会跳过会话身份校验、
+ * 只比较 revision，这样第一份快照（哪怕 revision 为 0 的暂停态）也能装进来。
+ */
+export declare const EMPTY_SESSION_QUEUE: SessionQueueSnapshot;
+/**
+ * 队列命令的 ack 线格式。
+ *
+ * `conflict` 表示乐观并发或状态校验失败，此时快照字段是服务端最新值，客户端必须
+ * 据此刷新本地并保留用户草稿；`error` 时快照字段可能缺失（如鉴权失败），此时只报错、
+ * 不改动本地队列。
+ */
+export interface QueueAck {
+    /** `queued` 只出现在 `chat:send` 的运行中改道：消息已进等待队列，不是失败。 */
+    status: "ok" | "conflict" | "error" | "queued";
+    /**
+     * 只有 `queued` 会带：服务端判定这次改道时该会话是否有运行。
+     * 客户端据此对齐流式标记，不用自己的猜测。
+     */
+    running?: boolean;
+    message?: string | null;
+    session_id?: string;
+    revision?: number;
+    paused?: boolean;
+    pause_reason?: string | null;
+    items?: QueuedMessage[];
+}
+/** 解析后的队列操作结果；UI 只看这一个结构。 */
+export interface QueueOperationResult {
+    ok: boolean;
+    conflict: boolean;
+    /** 服务端快照；缺失时为 null，调用方不得据此清空本地队列。 */
+    snapshot: SessionQueueSnapshot | null;
+    message: string | null;
+    /**
+     * 服务端给的机器可读失败原因（如 `owner_timeout` / `route_broken` / `owner_busy`），
+     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
+     */
+    code?: string;
+}
+/** 判定一份载荷是不是完整的权威队列快照（广播事件用）。 */
+export declare function isSessionQueueSnapshot(value: unknown): value is SessionQueueSnapshot;
+/**
+ * 是否用 `next` 覆盖 `current`。
+ *
+ * 规则只有两条：会话身份必须一致（还没拿到过快照时不校验），且 revision 必须严格
+ * 更新——相等或更旧一律不采纳，乱序到达的旧快照不会把新状态顶回去。
+ */
+export declare function shouldApplySnapshot(current: SessionQueueSnapshot | undefined, next: SessionQueueSnapshot): boolean;
+/**
+ * 解析 `emitWithAck` 的返回值。
+ *
+ * - `ok` / `queued` / `conflict` 且能解析成快照 → `snapshot` 有值；
+ * - `queued` → `ok=true`：`chat:send` 在运行中改道进了等待队列，调用方要撤掉乐观消息；
+ * - `conflict` → `ok=false, conflict=true`（快照可能仍缺失，调用方按 null 处理）；
+ * - `error` 或结构不合法 → `ok=false, conflict=false`，`message` 为服务端文案或兜底。
+ */
+export declare function parseQueueAck(response: unknown, fallbackSessionId: string): QueueOperationResult;
+/** 等待中的条目才能改正文；已经交给运行或开始执行的条目不再可编辑。 */
+export declare function canEditQueuedMessage(item: QueuedMessage): boolean;
+/** 等待中的条目才能删除。 */
+export declare function canCancelQueuedMessage(item: QueuedMessage): boolean;
+/**
+ * 能否立即补充。条目本身必须是等待中的；"会话是否正在运行"由调用方判断——
+ * 服务端会在没有可接收补充的任务时返回冲突。
+ */
+export declare function canDeliverQueuedMessage(item: QueuedMessage): boolean;
+/** 面向前端展示的状态文案；已离开队列视图的状态没有文案。 */
+export declare function queuedMessageStatusLabel(status: QueuedMessageStatus): string;
+/** 暂停原因文案；未知原因原样透出，没有原因返回 null。 */
+export declare function queuePauseReasonLabel(reason: string | null | undefined): string | null;

package/dist/session/state.d.ts

@@ -1,6 +1,7 @@
 import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/message";
 import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
+import { type SessionQueueSnapshot } from "./queue";
 /** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入 + 可选补充）。 */
 export interface AskUserAnswerData {
     selections: Record<number, number[]>;
@@ -43,8 +44,13 @@ export interface SessionState {
     activeCompaction: ActiveCompactionState | null;
     /** 回放（演示 / 彩排）状态；不是回放会话时为 null。 */
     replay: ReplaySnapshot | null;
+    /** 服务端持久化的等待消息队列快照；只在 revision 更新时替换。 */
+    queue: SessionQueueSnapshot;
     /** 当前身份对这个会话的权限；"viewer" 表示只读（分享链接打开的）。 */
     viewerRole: "owner" | "viewer" | null;
+    /** Stable anchor for the next older projected page. */
+    nextBefore: string | null;
+    loadingOlder: boolean;
 }
 /** 回放会话的快照视图，由服务端的 replay_state 归一化而来。 */
 export interface ReplaySnapshot {
@@ -58,6 +64,9 @@ export declare function toReplaySnapshot(raw: ReplayState | null | undefined): R
 export declare function createInitialSessionState(sessionId: string): SessionState;
 export declare function extractModeFromBlocks(blocks: ContentBlock[]): "planning" | "executing" | null;
 export declare function reconcileOptimisticUserTurns(currentTurns: TurnProjection[], incomingTurns: TurnProjection[]): TurnProjection[];
+/** Reconcile a bulk authoritative window only by an echoed request identity.
+ * Positional fallback is reserved for a single live turn from an older server. */
+export declare function reconcileHistoricalUserTurns(currentTurns: TurnProjection[], incomingTurns: TurnProjection[]): TurnProjection[];
 /**
  * 用一份新的 turn 列表重建会话状态。
  * addErrorMessage 注入的 role==="error" 消息不在 turns 里，默认会被物化过程抹掉；
@@ -65,7 +74,12 @@ export declare function reconcileOptimisticUserTurns(currentTurns: TurnProjectio
  * turn 推进（新消息 / rewind / 重连）时旧错误自动消失。
  */
 export declare function withTurns(state: SessionState, turns: TurnProjection[]): SessionState;
-export declare function addUserMessage(state: SessionState, content: MessageContent): SessionState;
+/**
+ * 安装一份服务端权威队列快照。旧 revision、别的会话或结构不合法的快照一律不采纳，
+ * 直接返回原 state——引用不变，订阅者不会收到多余通知。
+ */
+export declare function withQueue(state: SessionState, snapshot: SessionQueueSnapshot): SessionState;
+export declare function addUserMessage(state: SessionState, content: MessageContent, clientRequestId?: string): SessionState;
 export declare function upsertTurn(state: SessionState, turn: TurnProjection): SessionState;
 export declare function applyTurnPatch(state: SessionState, patch: PatchEnvelope): SessionState;
 export declare function addErrorMessage(state: SessionState, content: string): SessionState;

package/dist/shared/auth-busy.d.ts

@@ -0,0 +1,9 @@
+/** Return the server-requested delay for a typed temporary auth rejection. */
+export declare function authBusyRetryDelayMs(error: unknown): number | null;
+/** One pending manual reconnect for Socket.IO CONNECT_ERROR auth overloads. */
+export declare class AuthBusyReconnect {
+    private timer;
+    get pending(): boolean;
+    schedule(error: unknown, reconnect: () => void): boolean;
+    cancel(): void;
+}

package/dist/shared/projection/builder.d.ts

@@ -3,6 +3,8 @@ export interface RawEvent {
     type: string;
     payload: Record<string, unknown>;
 }
+/** 在任何事件处理前确认 Socket.IO 批次已到达客户端。 */
+export declare function acknowledgeTurnEvents(acknowledge?: () => void): void;
 export type ProjectionUpdate = {
     kind: "upsert";
     turn: TurnProjection;
@@ -13,6 +15,8 @@ export type ProjectionUpdate = {
     toolName?: string;
     workspacePath?: string;
 };
+/** 是否包含会改变聊天运行生命周期的事件。纯观测/整理事件不启动新一轮。 */
+export declare function hasChatRunEvent(events: RawEvent[]): boolean;
 /**
  * 缺失 chat:end 时的终态兜底。只有被投影接受到当前 assistant turn 的 followup
  * 才能结束流式态；陈旧 followup 或其后已有新轮事件时均返回 false。
@@ -22,7 +26,10 @@ export declare class ClientProjectionBuilder {
     private activeTurns;
     private lastTurnIds;
     private latestTurns;
+    private turnsById;
     private loopDescriptions;
+    /** loop_name → 正在运行的子智能体起点，agent:end 结算并挂到父工具调用上。 */
+    private activeSubagentRuns;
     private pendingChildPauses;
     private pendingMemoryRefs;
     private activeCompactions;
@@ -52,6 +59,8 @@ export declare class ClientProjectionBuilder {
     private onToolCallCreated;
     private onToolCallArgumentsDelta;
     private onResponseDone;
+    private applyFirstTokenDelivery;
+    private applyStreamTiming;
     private onToolResultDone;
     private onToolResultDelta;
     private onToolUi;
@@ -60,6 +69,7 @@ export declare class ClientProjectionBuilder {
     private onChildPause;
     private onChatEnd;
     private onAgentEnd;
+    private settleSubagentRun;
     private dropIncompleteToolCalls;
     private onCompaction;
     private syncPatch;

package/dist/shared/projection/helpers.d.ts

@@ -1,10 +1,10 @@
 import type { ContentBlock, PendingQuestionRef, ToolCallProjection, TurnProjection } from "../../schemas/projection";
 import type { TurnState } from "./state";
 export declare function upsertToolCall(state: TurnState, toolCallId: string, toolName: string, displayName: string, args: string): void;
-export declare function applyToolResult(state: TurnState, toolCallId: string, result: unknown, status: ToolCallProjection["status"], durationMs: number | null, sourceLoop: {
+export declare function applyToolResult(state: TurnState, toolCallId: string, result: unknown, status: ToolCallProjection["status"], durationMs: number | null, ranInParallel: boolean | null, sourceLoop: {
     loop_name: string;
     description: string;
-} | null): void;
+} | null, startedAt?: string | null): void;
 export declare function appendToolResultDelta(state: TurnState, toolCallId: string, delta: string, reset?: boolean): void;
 export declare function appendTextBlock(state: TurnState, blockType: ContentBlock["type"], content: unknown): void;
 export declare function appendToolCallArguments(state: TurnState, toolCallId: string, delta: string): void;

package/dist/shared/projection/index.d.ts

@@ -1,4 +1,4 @@
-export { acceptedPostChatFollowupCompletesLatestRun, ClientProjectionBuilder, type RawEvent, type ProjectionUpdate, } from "./builder";
+export { acceptedPostChatFollowupCompletesLatestRun, acknowledgeTurnEvents, ClientProjectionBuilder, hasChatRunEvent, type RawEvent, type ProjectionUpdate, } from "./builder";
 export { type TurnState, createTurnState, snapshot, PAUSE_TOOL_NAMES } from "./state";
 export { projectHistory, type RawHistoryEntry } from "./history";
 export { buildContextTurn } from "./context";

package/dist/shared/projection/state.d.ts

@@ -10,6 +10,13 @@ export interface TurnState {
     toolCalls: ToolCallProjection[];
     usage: Record<string, unknown> | null;
     responseDone: boolean;
+    firstTokenMs: number | null;
+    streamDurationMs: number | null;
+    firstTokenDeliveryMs: number | null;
+    /** 生产者上报的模型请求时序；缺失时保持 null，不用浏览器时间补（#2581 A1/I1）。 */
+    modelStartedAt: string | null;
+    modelDurationMs: number | null;
+    modelStartedAtReported: boolean;
     memoryRefs: MemoryRef[] | null;
     parentForkToolCallId: string | null;
 }