@blade-hq/agent-client 2610.0.0-beta.4 → 2610.0.0-beta.41

package/dist/platform-endpoints.d.ts

@@ -0,0 +1,14 @@
+export declare const PLATFORM_SERVICE_NAMES: readonly ["os", "hub", "agent", "oauth", "llmGateway", "gitea", "tile"];
+export type PlatformServiceName = (typeof PLATFORM_SERVICE_NAMES)[number];
+export interface PlatformEndpoints {
+    services: Partial<Record<PlatformServiceName, string>>;
+}
+export declare const EMPTY_PLATFORM_ENDPOINTS: PlatformEndpoints;
+export interface LoadPlatformEndpointsOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare function parsePlatformEndpoints(value: unknown): PlatformEndpoints | null;
+export declare function loadPlatformEndpoints(options?: LoadPlatformEndpointsOptions): Promise<PlatformEndpoints>;
+export declare function resolveServiceUrl(endpoints: PlatformEndpoints, name: PlatformServiceName, path?: string): string | null;

package/dist/resources/computers.d.ts

@@ -0,0 +1,85 @@
+import type { BladeClient } from "../blade-client";
+/** 一台远程电脑在某个会话眼里的样子。 */
+export interface SessionComputer {
+    id: string;
+    label: string;
+    hostname?: string | null;
+    os?: string | null;
+    arch?: string | null;
+    /** 那台机器的用户主目录，命令默认在这里执行。 */
+    home?: string | null;
+    /** daemon 启动时所在的目录。 */
+    workspace?: string | null;
+    blade_home?: string | null;
+    allowed_paths?: string[];
+    agent_runtimes?: unknown[];
+    daemon_version?: string | null;
+    created_at: string;
+    last_seen_at?: string | null;
+    /** 这台电脑此刻连着后端。由服务端读心跳时间判定，不做实时探测。 */
+    online: boolean;
+    /** 这次会话已经启动了它。和 `online` 互相独立。 */
+    enabled: boolean;
+    /** 这次会话本身就跑在这台电脑上。 */
+    is_primary: boolean;
+}
+export interface SessionComputerList {
+    computers: SessionComputer[];
+}
+/**
+ * 一台电脑在界面上该显示成什么状态。
+ *
+ * - `primary` 会话自己就住在这台机器上，恒为可用且不能停用
+ * - `enabled` 本次会话已启动
+ * - `offline` 没启动且当前离线
+ * - `idle` 没启动，在线
+ *
+ * 判定只写这一份，界面只管样式和排版——两边各写一份必然会分叉，
+ * 然后其中一边的兜底会把另一边的错误盖住。
+ */
+export type ComputerState = "primary" | "enabled" | "offline" | "idle";
+export declare function computerState(computer: SessionComputer): ComputerState;
+/**
+ * 这台电脑跑的是哪一类系统。
+ *
+ * 判定放这里、图标映射留给界面：`os` 是 daemon 上报的 `runtime.GOOS`，
+ * 各处自己 `startsWith` 一遍必然会分叉。
+ */
+export type ComputerOS = "macos" | "windows" | "linux" | "unknown";
+export declare function computerOS(computer: SessionComputer): ComputerOS;
+/** 系统与架构，例如 `darwin/arm64`。信息不全时尽量给出已知的那部分。 */
+export declare function computerPlatformLabel(computer: SessionComputer): string;
+/**
+ * 那台电脑上 blade daemon 的版本。
+ *
+ * 服务端存的就是 daemon 上报的完整串（dev 构建带 commit），这里原样用，
+ * 不在前端另拼一套格式——拼两份迟早对不上。
+ */
+export declare function computerDaemonVersion(computer: SessionComputer): string;
+/** 这台电脑的勾选框能不能动。主运行时不能停用——那是会话自己的工作目录所在。 */
+export declare function canToggleComputer(computer: SessionComputer): boolean;
+/**
+ * 列表顺序：按接入时间，稳定不变。
+ *
+ * **刻意不按在线/可用排序。** 那样排看着"手边的在前面"，代价是电脑上下线、
+ * 勾选状态一变，整个列表就重排——用户正要点的那一项会在手指底下跑掉。
+ * 一个会自己动的列表比一个排序不那么聪明的列表难用得多。
+ *
+ * 用 `created_at` 而不是名字：改名不会让位置变，新接入的稳定排在末尾。
+ */
+export declare function sortComputers(computers: SessionComputer[]): SessionComputer[];
+/** 会话可以操作哪些远程电脑。 */
+export declare class ComputersResource {
+    private client;
+    constructor(client: BladeClient);
+    /**
+     * 列出当前用户的全部电脑，带上"在不在线"和"这次会话能不能用"。
+     * 服务端只查库，电脑离线时同样返回，所以拿得到"它离线了"这个结论。
+     */
+    list(sessionId: string): Promise<SessionComputerList>;
+    /**
+     * 启动或停止一台电脑。只改这次会话的可用范围，不会碰远程机器，
+     * 电脑离线时同样能登记，等它上线就直接可用。
+     */
+    setEnabled(sessionId: string, computer: string, enabled: boolean): Promise<SessionComputer>;
+}

package/dist/resources/models.d.ts

@@ -12,6 +12,8 @@ export interface ModelOption {
 export interface ModelCatalog {
     default: string;
     models: ModelOption[];
+    unavailableProviderIds?: string[];
+    unavailableModelIds?: string[];
     /**
      * 平台默认模型服务的 OpenAI 兼容地址（Server ≥ 提供 `baseUrl` 的版本才有，否则为空）。
      * 自建应用可以带用户的 PAT 直接调它，不必让用户自己填地址——网关端口各部署不同，

package/dist/resources/sessions.d.ts

@@ -24,8 +24,10 @@ export interface CreateSessionRequest {
     disable_tools?: string[] | null;
     session_solution_asset_id?: string | null;
     compaction_ratio?: number | null;
-    runtime_type?: "sandbox" | "daemon" | null;
+    runtime_type?: "sandbox" | "daemon" | "native" | null;
     daemon_id?: string | null;
+    /** runtime_type 为 "native" 时必填：daemon 上要用哪个原生智能体（如 rt_codex）。 */
+    agent_runtime_id?: string | null;
 }
 export interface CheckpointNode {
     id: string;
@@ -126,6 +128,17 @@ export interface SessionContextStats {
     context_window: number;
     compaction_ratio: number;
 }
+export interface SessionTurnsPage {
+    turns: TurnProjection[];
+    nextBefore: string | null;
+    currentMode: "planning" | "executing";
+}
+export interface HistoricalCommand {
+    deliveryId: string;
+    toolCallId?: string;
+    action: string;
+    payload?: unknown;
+}
 export type ResultFeedbackReason = "not_solved" | "inaccurate" | "incomplete" | "needs_major_changes" | "too_slow" | "other";
 export interface ResultFeedback {
     session_id: string;
@@ -262,6 +275,11 @@ 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>;
+    getSessionTurnCommands(sessionId: string): Promise<HistoricalCommand[]>;
     listResultFeedback(sessionId: string): Promise<ResultFeedback[]>;
     putResultFeedback(sessionId: string, assistantEntryId: string, feedback: {
         helpful: boolean;

package/dist/schemas/context.d.ts

@@ -0,0 +1,49 @@
+export type ContextAction = "published" | "retained" | "removed";
+/** Safe display-source metadata retained for headless consumers. */
+export type ContextSourceInfo = Record<string, unknown>;
+export interface ContextProjectionData {
+    context_kind: string;
+    context_key: string;
+    context_name: string;
+    context_order: number;
+    context_action: ContextAction;
+    context_revision: string;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources: ContextSourceInfo[];
+}
+export interface ContextProjectionFields {
+    context_kind?: string | null;
+    context_key?: string | null;
+    context_name?: string | null;
+    context_order?: number | null;
+    context_action?: ContextAction | null;
+    context_revision?: string | null;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources?: ContextSourceInfo[] | null;
+}
+export interface ContextDisplayState {
+    title: string;
+    summary: string;
+    detail: string;
+    isRemoved: boolean;
+}
+export interface ContextGroupDisplayState {
+    title: string;
+    summary: string;
+    count: number;
+}
+export declare function contextProjectionData(fields: ContextProjectionFields): ContextProjectionData | null;
+/** The single status-to-display mapping used by both React chat surfaces. */
+export declare function getContextDisplayState(context: ContextProjectionData): ContextDisplayState;
+/**
+ * 把一段渲染序列里连续的 Context 归成组。
+ *
+ * 入参是序列里每一项的 context kind，非 Context 项传 null；返回每一段连续
+ * Context 的下标数组。纯下标运算，不认识任何 UI 类型，所以调试日志、Lite 视图
+ * 和 SDK 卡片可以共用同一份分组判定，各自只管排版。
+ */
+export declare function groupAdjacentContextRuns(kinds: readonly (string | null)[]): readonly (readonly number[])[];
+/** 折叠行的文案。展开后才逐条显示各自的标题与状态。 */
+export declare function getContextGroupDisplayState(contexts: readonly ContextProjectionData[]): ContextGroupDisplayState;

package/dist/schemas/event.d.ts

@@ -11,6 +11,15 @@ export interface ToolCallCreated {
         arguments: string;
     };
 }
+export interface ToolCallArgumentsDelta {
+    index: number;
+    id: string;
+    loop_name?: string;
+    function: {
+        name: string;
+    };
+    arguments_delta: string;
+}
 export interface ToolResultDone {
     tool_call_id: string;
     loop_name?: string;

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

@@ -1,9 +1,13 @@
 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;
+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;

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;
@@ -70,6 +71,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 +83,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;
@@ -22,6 +24,7 @@ export interface ToolCallProjection {
     status: "pending" | "done" | "error" | "cancelled" | "awaiting_answer" | string;
     result?: unknown;
     duration_ms?: number | null;
+    ran_in_parallel?: boolean;
     pending_question_ref?: PendingQuestionRef | null;
 }
 export interface MemoryRef {
@@ -47,7 +50,7 @@ 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[];
@@ -55,10 +58,28 @@ export interface TurnProjection {
     model?: string | null;
     usage?: Record<string, unknown> | null;
     duration_ms?: number;
+    first_token_ms?: number | null;
+    stream_duration_ms?: number | null;
+    first_token_delivery_ms?: number | null;
     started_at?: string | null;
     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

@@ -82,7 +82,10 @@ 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;
     match?: unknown;
 }, {}>;
 export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "solution" | "ports" | "match"> & {
@@ -106,9 +109,12 @@ 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;
     /** 仅在带 q 搜索的列表响应中出现；普通列表里此字段缺省。 */
     match?: SessionSearchMatch | null;
 };

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

@@ -4,15 +4,15 @@ 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, SessionTurnsPage } from "../resources/sessions";
 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, before?: string): Promise<SessionTurnsPage>;
+    fetchCommands(sessionId: string): Promise<HistoricalCommand[]>;
     /** 会话详情，目前只用来取回放状态。 */
     fetchSessionInfo(sessionId: string): Promise<{
         replay_state?: ReplayState | null;
@@ -53,6 +53,8 @@ export interface SendOptions {
         deprecate_entry_ids: string[];
     };
     replayDecision?: "keep_replay" | "continue_replay";
+    /** 用户 @ 的知识库 id：后端先用原话在这些库里预检索，本轮 kb_search 也默认限定在这些库。 */
+    kbIds?: number[];
 }
 export declare function sessionStatusFromChatEnd(status: string | undefined): SessionStatus;
 /**
@@ -75,10 +77,29 @@ export declare class AgentSession {
     private patchFlushCancel;
     private joined;
     private joinPending;
+    private subscriptionQueue;
+    private replaceQueue;
+    private timelineEpoch;
+    private pagingGeneration;
+    private liveRevision;
+    private modeRevision;
+    private readonly liveRevisions;
+    private readonly pendingOptimisticTurnIds;
+    /** Consecutive supplements are persisted as one authoritative user turn. */
+    private pendingAppendTurnId;
+    private olderPending;
+    private replaceInFlight;
     private replayQueue;
+    private commandRestoreQueue;
+    private commandRecoveryGeneration;
+    private commandRestoreRetryAttempt;
+    private commandRestoreRetryHandle;
+    private bufferedCommandDeliveries;
     private pendingReplayMessage;
     private pendingReplayMode;
+    private pendingReplayKbIds;
     private recentChatEndAt;
+    private subscriptionReplaySource;
     private disposed;
     private getAppContext;
     private sendPending;
@@ -94,6 +115,11 @@ export declare class AgentSession {
     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>;
     /** 订阅状态变化。返回取消订阅函数。 */
     subscribe(listener: () => void): () => void;
     private setState;
@@ -116,6 +142,13 @@ export declare class AgentSession {
     attachApp(options: AttachAppOptions): Promise<AppCliAttachment | null>;
     /** 发送一条消息。字符串或多模态内容均可。 */
     send(content: MessageContent, options?: SendOptions): Promise<boolean>;
+    /** Queue a plain-text prompt while a turn is streaming. */
+    queue(content: string): Promise<boolean>;
+    listQueue(): Promise<Array<{
+        id: number;
+        message: string;
+    }>>;
+    cancelQueued(id: number): Promise<boolean>;
     private sendUnlocked;
     private rollbackOptimisticSend;
     /** 智能体运行期间追加补充说明（不打断当前回复）。 */
@@ -150,6 +183,8 @@ export declare class AgentSession {
     _rejoinAfterReconnect(): Promise<void>;
     /** @internal 首次连接：加载历史 + 加入房间。 */
     _bootstrap(): Promise<void>;
+    /** 订阅生命周期串行执行；一次失败只由自己的调用方观察，不截断后续重连。 */
+    private enqueueSubscription;
     /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
     private get canControlReplay();
     /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
@@ -167,7 +202,7 @@ 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 */
@@ -200,10 +235,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 +249,17 @@ export declare class AgentSession {
     /** turn 数据落地后统一派生语义事件（指令 / 工具调用 / 消息 / 模式 / 预览 / OOM）。 */
     private emitTurnDerivedEvents;
     private dispatchCommand;
+    private dispatchRawCommands;
+    private deliverCommand;
+    private deliverCommandNow;
     private notifySandboxOom;
-    private syncTurnsFromHistory;
-    /**
-     * 把历史里的指令补投给宿主页面。
-     *
-     * 重开会话、断线补数时，地图高亮这类"页面当前状态"必须能恢复——
-     * 否则刷新一次页面，之前智能体让页面做的事就全丢了。
-     * 只回放指令：toolCall / message 这些事件如果按历史全量重放，
-     * 监听器会在挂载瞬间收到几百条陈年事件。
-     * dispatch 内部按 deliveredCommandKeys 去重，重复调用安全。
-     */
-    private replayCommandsFromTurns;
+    private replaceFromHistory;
+    private invalidateOlderPaging;
+    private beginCommandRecovery;
+    private scheduleHistoricalCommandRestore;
+    private flushBufferedCommands;
+    /** 首次订阅前的 REST 历史建立语义事件基线，随后同一工具的订阅回放不再投递。 */
+    private seedToolCallDeliveryBaseline;
     private ensureJoined;
     private ensureIdleBeforeSend;
 }

package/dist/session/events.d.ts

@@ -23,6 +23,8 @@ export interface AgentSessionEvents {
     toolResult: {
         toolCall: ToolCallInfo;
         turn: TurnProjection;
+        /** 实时到达，或首次连接/断线重连时由服务端回放。 */
+        source: "live" | "bootstrap_replay" | "reconnect_replay";
     };
     /** 一轮回复结束。status: completed / paused / interrupted / failed。 */
     chatEnd: {

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 实例。多会话共享连接、状态互不干扰。
@@ -27,7 +34,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/state.d.ts

@@ -1,10 +1,12 @@
 import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/message";
 import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
-/** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入）。 */
+/** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入 + 可选补充）。 */
 export interface AskUserAnswerData {
     selections: Record<number, number[]>;
     custom: Record<number, string>;
+    /** 选完选项后的自由补充，空着就是没有。 */
+    note?: string;
 }
 export interface AgentLoopInfo {
     toolCallId: string;
@@ -43,6 +45,9 @@ export interface SessionState {
     replay: ReplaySnapshot | null;
     /** 当前身份对这个会话的权限；"viewer" 表示只读（分享链接打开的）。 */
     viewerRole: "owner" | "viewer" | null;
+    /** Stable anchor for the next older projected page. */
+    nextBefore: string | null;
+    loadingOlder: boolean;
 }
 /** 回放会话的快照视图，由服务端的 replay_state 归一化而来。 */
 export interface ReplaySnapshot {
@@ -55,6 +60,10 @@ export interface ReplaySnapshot {
 export declare function toReplaySnapshot(raw: ReplayState | null | undefined): ReplaySnapshot | null;
 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 里，默认会被物化过程抹掉；
@@ -62,7 +71,7 @@ export declare function extractModeFromBlocks(blocks: ContentBlock[]): "planning
  * turn 推进（新消息 / rewind / 重连）时旧错误自动消失。
  */
 export declare function withTurns(state: SessionState, turns: TurnProjection[]): SessionState;
-export declare function addUserMessage(state: SessionState, content: MessageContent): 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/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,6 +26,7 @@ export declare class ClientProjectionBuilder {
     private activeTurns;
     private lastTurnIds;
     private latestTurns;
+    private turnsById;
     private loopDescriptions;
     private pendingChildPauses;
     private pendingMemoryRefs;
@@ -37,6 +42,7 @@ export declare class ClientProjectionBuilder {
     seedSequence(maxSeq: number): void;
     _seedTurns(turns: TurnProjection[]): void;
     private onMemoryInject;
+    private onContextEntry;
     private onLoopTurn;
     private onModeChange;
     private onPlanStatusUpdate;
@@ -49,7 +55,10 @@ export declare class ClientProjectionBuilder {
     private onPostChatFollowup;
     private onDelta;
     private onToolCallCreated;
+    private onToolCallArgumentsDelta;
     private onResponseDone;
+    private applyFirstTokenDelivery;
+    private applyStreamTiming;
     private onToolResultDone;
     private onToolResultDelta;
     private onToolUi;

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

@@ -0,0 +1,3 @@
+import type { TurnProjection } from "../../schemas/projection";
+/** Build one Context turn from the canonical entry used by live and history paths. */
+export declare function buildContextTurn(entry: Record<string, unknown>, sequence: number): TurnProjection | null;

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

@@ -1,7 +1,7 @@
 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;

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

@@ -4,6 +4,7 @@ export interface RawHistoryEntry {
     kind?: string;
     loop_name?: string;
     message?: Record<string, unknown>;
+    source?: Record<string, unknown>;
     data?: Record<string, unknown>;
     timestamp?: string;
     [key: string]: unknown;

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

@@ -1,3 +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,9 @@ export interface TurnState {
     toolCalls: ToolCallProjection[];
     usage: Record<string, unknown> | null;
     responseDone: boolean;
+    firstTokenMs: number | null;
+    streamDurationMs: number | null;
+    firstTokenDeliveryMs: number | null;
     memoryRefs: MemoryRef[] | null;
     parentForkToolCallId: string | null;
 }