@blade-hq/agent-client 2610.0.1-alpha.1 → 2610.0.2

package/dist/schemas/mcp-app.d.ts

@@ -0,0 +1,30 @@
+/** Archived MCP App data. Credentials and executable server configuration are excluded. */
+export interface McpAppData {
+    sourceId: string;
+    resourceUri: string;
+    mimeType: string;
+    resourceMeta: Record<string, unknown>;
+    toolInput: Record<string, unknown>;
+    toolResult: Record<string, unknown>;
+}
+export interface McpAppArchive extends McpAppData {
+    html: string;
+    plugin: string;
+    /** Restore the last successful view before delivering a saved failure. */
+    previousToolInput?: Record<string, unknown>;
+    previousToolResult?: Record<string, unknown>;
+}
+export declare function isMcpAppData(value: unknown): value is McpAppData;
+/** Latest model-context state one MCP App saved for its own card. */
+export interface McpAppContextState {
+    revision: string;
+    content: string;
+    plugin: string | null;
+    server_alias: string | null;
+}
+export interface McpAppContextUpdate {
+    request_id: string;
+    /** null on the first save; the server rejects a stale revision. */
+    expected_revision: string | null;
+    content: string;
+}

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

@@ -1,9 +1,21 @@
 import type { ChatMessage, FileContentPart, ImageUrlContentPart, MessageContent } from "./message";
+/** Ordinary chat uses business copy; developer mode may retain diagnostics. */
+export declare function chatErrorForDisplay(message: string, developer?: boolean): string;
 export declare function normalizeMessageContent(content: unknown): MessageContent;
 export declare function getTextContent(content: MessageContent): string;
 export declare function isSystemReminderText(text: string): boolean;
 export declare function isLegacyForkContextText(text: string): boolean;
-export declare function isHiddenInternalMessage(message: Pick<ChatMessage, "role" | "content">): boolean;
+/**
+ * 平台自己写进去、不该露给用户的内部提示。
+ *
+ * 服务端的消息导航目录有一份同名同语义的 Python 实现
+ * （`server/.../routes/sessions.py` 的 `_is_hidden_internal_message`）：客户端靠它决定
+ * 渲染不渲染，服务端靠它决定进不进目录。改这里必须同时改那边，否则目录会列出没有对应
+ * 行的死条目，或者把内部提示原文当标题露出去。
+ */
+export declare function isHiddenInternalMessage(message: Pick<ChatMessage, "role" | "content">, options?: {
+    includeLegacyForkContext?: boolean;
+}): boolean;
 export declare function buildMessageContent(text: string, attachments: Array<{
     kind: "file";
     name: string;
@@ -55,4 +67,6 @@ interface MessageGroup {
     }[];
 }
 export declare function groupMessagesByLoop(messages: ChatMessage[]): MessageGroup[];
+/** A typed wake input stays internal for navigation, but has a visible notice. */
+export declare function isBackgroundWakeMessage(message: Pick<ChatMessage, "blocks">): boolean;
 export {};

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 {
@@ -70,6 +74,8 @@ export interface ChatMessage {
     duration_ms?: number;
     timestamp?: string;
     entry_id?: string;
+    /** Stable React key retained when an optimistic user message is confirmed. */
+    render_id?: string;
     parent_id?: string | null;
     loop_name?: string;
     /** Entry kind from backend -- present for non-message entries like mode changes. */
@@ -80,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-utils.d.ts

@@ -0,0 +1,3 @@
+import type { PostChatFollowup, TurnProjection } from "./projection";
+/** 返回最新根会话轮次的小结；新用户消息到达后旧小结立即失效。 */
+export declare function latestPostChatFollowup(turns: TurnProjection[]): PostChatFollowup | null;

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 {
@@ -29,23 +45,57 @@ export interface MemoryRef {
     content_preview: string;
     skill_name?: string | null;
 }
+export interface FinalArtifact {
+    kind: "file" | "link";
+    target: string;
+    label: string;
+}
+export interface PostChatFollowup {
+    assistant_entry_id: string;
+    recaption?: string;
+    suggestions: string[];
+    final_artifacts?: FinalArtifact[];
+    feedback_eligible: boolean;
+    feedback_scope: "latest_result";
+}
 export interface TurnProjection {
     id: string;
     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;
@@ -58,6 +108,7 @@ export interface TurnProjection {
     trigger?: "auto" | "manual" | "forced_retry" | null;
     failure_reason?: string | null;
     fallback_applied?: boolean | null;
+    post_chat_followup?: PostChatFollowup | null;
 }
 export interface ArchivedFileInfo {
     tool_name?: 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,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,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;
 /**
@@ -74,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;
@@ -88,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;
@@ -115,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>>;
     /** 手动触发上下文压缩。 */
@@ -145,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();
     /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
@@ -166,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;
@@ -199,9 +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;
@@ -209,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;
     /** 手动重连（例如登录态变化后）。 */