@blade-hq/agent-client 2610.0.0-beta.9 → 2610.0.0-beta.90

package/dist/schemas/message.d.ts

@@ -1,4 +1,5 @@
 import type { ContentBlock, PendingQuestionRef, ToolBridgeContent } from "./projection";
+import type { ContextProjectionData } from "./context";
 export interface TextContentPart {
     type: "text";
     text: string;
@@ -7,6 +8,9 @@ export interface ImageUrlContentPart {
     type: "image_url";
     image_url: {
         url: string;
+        source_path?: string;
+        width?: number;
+        height?: number;
     };
 }
 export interface FileContentPart {
@@ -82,4 +86,6 @@ export interface ChatMessage {
     blocks?: ContentBlock[];
     /** Compaction metadata for compaction turns. */
     compaction?: CompactionInfo;
+    /** Sourced Context metadata for rendering or headless consumers. */
+    context?: ContextProjectionData;
 }

package/dist/schemas/projection.d.ts

@@ -5,6 +5,8 @@ export interface ToolBridgeContent {
 export interface ContentBlock {
     type: "text" | "thinking" | "tool_use" | "tool_result" | "tool_ui" | "tool_bridge" | "system_notification" | "mode_change" | "plan_status" | "ask_user_answer";
     content: unknown;
+    /** Stable history-entry identity for a tool_bridge delivery. */
+    delivery_id?: string | null;
     tool_call_id?: string | null;
     tool_name?: string | null;
     display_name?: string | null;
@@ -14,6 +16,15 @@ export interface PendingQuestionRef {
     child_tool_call_id: string;
     description?: string | null;
 }
+/** 一次运行（用户轮或子智能体）的实际墙钟区间。 */
+export interface RunTiming {
+    run_id: string;
+    scope: "chat" | "subagent";
+    loop_id: string;
+    started_at?: string | null;
+    duration_ms?: number | null;
+    status: "completed" | "failed" | "cancelled" | "paused" | "incomplete";
+}
 export interface ToolCallProjection {
     id: string;
     tool_name: string;
@@ -22,6 +33,11 @@ export interface ToolCallProjection {
     status: "pending" | "done" | "error" | "cancelled" | "awaiting_answer" | string;
     result?: unknown;
     duration_ms?: number | null;
+    /** 工具真正进入执行的墙钟起点；排队/待审批的调用没有该值。 */
+    started_at?: string | null;
+    ran_in_parallel?: boolean;
+    /** 该工具派生的子智能体运行区间，仅作外层展示。 */
+    subagent_runs?: RunTiming[];
     pending_question_ref?: PendingQuestionRef | null;
 }
 export interface MemoryRef {
@@ -47,20 +63,39 @@ export interface TurnProjection {
     sequence: number;
     turn_id: string;
     loop_id: string;
-    kind?: "message" | "compaction";
+    kind?: "message" | "context" | "compaction";
     role: "user" | "assistant" | "system";
     status: "streaming" | "completed" | "paused" | "failed" | "interrupted";
     blocks: ContentBlock[];
     tool_calls: ToolCallProjection[];
     model?: string | null;
     usage?: Record<string, unknown> | null;
-    duration_ms?: number;
+    /** 模型请求区间（不含后续工具）；未知时为 null，不用 0 冒充。 */
+    duration_ms?: number | null;
+    first_token_ms?: number | null;
+    stream_duration_ms?: number | null;
+    first_token_delivery_ms?: number | null;
     started_at?: string | null;
+    /** started_at 是否来自生产者上报（而非旧会话的落盘回落）。瀑布只承认前者。 */
+    has_reported_timing?: boolean;
     context_window?: number;
     memory_refs?: MemoryRef[] | null;
     parent_fork_tool_call_id?: string | null;
+    context_kind?: string | null;
+    context_key?: string | null;
+    context_name?: string | null;
+    context_order?: number | null;
+    context_action?: import("./context").ContextAction | null;
+    context_revision?: string | null;
+    /** 原始 Context 内容仅供开发者模式诊断；常规消息投影不消费。 */
+    context_content?: unknown;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources?: import("./context").ContextSourceInfo[] | null;
     /** Client-only stable identity for reconciling an optimistic user turn. */
     client_render_id?: string | null;
+    /** Send identity echoed by the server for exact optimistic reconciliation. */
+    client_request_id?: string | null;
     compaction_id?: string | null;
     summary_preview?: string | null;
     summary_full?: string | null;

package/dist/schemas/session.d.ts

@@ -62,6 +62,7 @@ export declare const SessionInfo: import("arktype/internal/variants/object.ts").
     shared?: boolean | undefined;
     memory_enabled?: boolean | undefined;
     is_persistent?: boolean | undefined;
+    initiator?: "sdk" | "ui" | "unknown" | null | undefined;
     is_headless?: boolean | undefined;
     viewer_role?: "owner" | "viewer" | undefined;
     template_id?: string | null | undefined;
@@ -82,7 +83,11 @@ export declare const SessionInfo: import("arktype/internal/variants/object.ts").
     disable_tools?: string[] | undefined;
     runtime_type?: string | null | undefined;
     daemon_id?: string | null | undefined;
+    agent_runtime_id?: string | null | undefined;
     workspace_path?: string | null | undefined;
+    ba_version?: string | null | undefined;
+    sandbox_version?: string | null | undefined;
+    chat_group_id?: string | null | undefined;
     match?: unknown;
 }, {}>;
 export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "solution" | "ports" | "match"> & {
@@ -106,9 +111,13 @@ export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "soluti
     is_example?: boolean;
     ports?: SessionPortMapping[];
     disable_tools?: string[];
-    runtime_type?: "sandbox" | "daemon" | string | null;
+    runtime_type?: "sandbox" | "daemon" | "native" | string | null;
     daemon_id?: string | null;
+    agent_runtime_id?: string | null;
     workspace_path?: string | null;
+    ba_version?: string | null;
+    sandbox_version?: string | null;
+    chat_group_id?: string | null;
     /** 仅在带 q 搜索的列表响应中出现；普通列表里此字段缺省。 */
     match?: SessionSearchMatch | null;
 };

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

@@ -4,15 +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 {
-    streamTokens: boolean;
     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;
@@ -53,6 +55,13 @@ export interface SendOptions {
         deprecate_entry_ids: string[];
     };
     replayDecision?: "keep_replay" | "continue_replay";
+    /** 用户显式选择的知识库 id；后端将元信息作为 once Context 提供给模型。 */
+    kbIds?: number[];
+    /**
+     * 声明"会话在跑就把这条消息放进等待队列"。默认不排队、运行中直接报错：
+     * 是否真的入队由服务端按运行状态判定（等待回答时发送即作答，不会被误排队）。
+     */
+    queueWhenRunning?: boolean;
 }
 export declare function sessionStatusFromChatEnd(status: string | undefined): SessionStatus;
 /**
@@ -75,10 +84,45 @@ export declare class AgentSession {
     private patchFlushCancel;
     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;
     private sendPending;
@@ -89,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;
@@ -116,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>>;
     /** 手动触发上下文压缩。 */
@@ -146,10 +268,17 @@ 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 首次连接：加载历史 + 加入房间。 */
     _bootstrap(): Promise<void>;
+    /** 订阅生命周期串行执行；一次失败只由自己的调用方观察，不截断后续重连。 */
+    private enqueueSubscription;
     /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
     private get canControlReplay();
     /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
@@ -167,19 +296,21 @@ export declare class AgentSession {
     /** @internal */
     _handleTurnEnd(turn: TurnProjection): void;
     /** @internal 历史回放通道（event_format: raw）。 */
-    _handleTurnEvents(events: RawEvent[]): void;
+    _handleTurnEvents(events: RawEvent[], replayed?: boolean): void;
     /** @internal */
     _handleChatStart(): void;
     /** @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;
@@ -200,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;
@@ -211,18 +345,26 @@ export declare class AgentSession {
     /** turn 数据落地后统一派生语义事件（指令 / 工具调用 / 消息 / 模式 / 预览 / OOM）。 */
     private emitTurnDerivedEvents;
     private dispatchCommand;
+    private dispatchRawCommands;
+    private deliverCommand;
+    private deliverCommandNow;
     private notifySandboxOom;
-    private syncTurnsFromHistory;
     /**
-     * 把历史里的指令补投给宿主页面。
+     * 权威刷新（运行结束 / 重连补数）：**按当前窗口第一条发言取窗口**，不再另记"用户想看哪段"。
      *
-     * 重开会话、断线补数时，地图高亮这类"页面当前状态"必须能恢复——
-     * 否则刷新一次页面，之前智能体让页面做的事就全丢了。
-     * 只回放指令：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";
 /**
@@ -23,14 +24,22 @@ export interface AgentSessionEvents {
     toolResult: {
         toolCall: ToolCallInfo;
         turn: TurnProjection;
+        /** 实时到达，或首次连接/断线重连时由服务端回放。 */
+        source: "live" | "bootstrap_replay" | "reconnect_replay";
     };
     /** 一轮回复结束。status: completed / paused / interrupted / failed。 */
     chatEnd: {
         status: string;
     };
-    /** 运行错误（system:error、发送失败等）。 */
+    /**
+     * 运行错误（system:error、发送失败等）。
+     *
+     * `code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken`），
+     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
+     */
     error: {
         message: string;
+        code?: string;
     };
     /** planning / executing 模式切换。 */
     modeChange: {
@@ -74,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: {
@@ -106,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

@@ -1,6 +1,13 @@
 import type { BladeClient } from "../blade-client";
 import { AgentSession } from "./agent-session";
 import type { ConnectionStatus } from "./state";
+export interface SessionConnectOptions {
+    /**
+     * 在会话进入事件路由后、历史加载与房间订阅开始前同步执行。
+     * 适合安装不能漏掉 bootstrap 回放事件的监听器。
+     */
+    setup?: (session: AgentSession) => void;
+}
 /**
  * 每个 BladeClient 一个：管理一条 Socket.IO 连接，按 session_id 把事件
  * 路由给各 AgentSession 实例。多会话共享连接、状态互不干扰。
@@ -15,6 +22,7 @@ export declare class SessionHub {
     private readonly connectionListeners;
     private bound;
     private hasConnected;
+    private readonly authBusyReconnect;
     constructor(client: BladeClient);
     /** 当前 Socket.IO 连接状态。 */
     getConnection(): ConnectionStatus;
@@ -27,7 +35,7 @@ export declare class SessionHub {
      * 只有最后一份归还才退订房间——否则 StrictMode 双跑、路由抖动这类"连两次
      * 只释放一次"的场景会把仍在用的会话退订掉，之后所有 turn/chat 事件静默丢失。
      */
-    connect(sessionId: string): Promise<AgentSession>;
+    connect(sessionId: string, options?: SessionConnectOptions): Promise<AgentSession>;
     /** 已有实例则返回，不触发网络请求。 */
     peek(sessionId: string): AgentSession | undefined;
     /** 手动重连（例如登录态变化后）。 */

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;