@blade-hq/agent-client 2610.0.1 → 2612.0.0-beta.1

package/dist/session/hub.d.ts

@@ -1,6 +1,48 @@
 import type { BladeClient } from "../blade-client";
-import { AgentSession } from "./agent-session";
+import { AgentSession, type SessionDetailSnapshot } from "./agent-session";
 import type { ConnectionStatus } from "./state";
+/**
+ * Hub 级事件：服务端推送的会话运行状态，**不论这个会话有没有 AgentSession 实例**都会触发
+ * （完整订阅的会话，以及 `watchStatus` 登记的状态订阅会话）。适合维护会话列表、发任务通知；
+ * 会话内部的状态请用 AgentSession。
+ */
+export interface SessionHubEvents {
+    /** 一轮运行开始（chat:start）。 */
+    runStarted: {
+        sessionId: string;
+    };
+    /** 一轮运行结束（chat:end）。`replayed` 为 true 表示订阅时服务端重发的旧终态，不是新完成。 */
+    runEnded: {
+        sessionId: string;
+        /** 服务端给的终态原文；缺省时按 completed 处理会话状态，但不要当作「新完成」。 */
+        status?: string;
+        queued: boolean;
+        replayed: boolean;
+        chatRunId?: string;
+    };
+    /** 运行错误（system:error）。 */
+    runError: {
+        sessionId: string;
+        message: string;
+        code?: string;
+    };
+    /** 会话属性被服务端更新（session:updated），`data` 是载荷原文。 */
+    sessionUpdated: {
+        sessionId: string;
+        data: Record<string, unknown>;
+    };
+}
+export interface SessionHubOptions {
+    /**
+     * 进入会话 / 重连时是否拉取历史指令（`GET /turns/commands`）补投给 onCommand。默认 true。
+     * 不消费历史指令的宿主可以关掉，省一次请求。
+     */
+    restoreHistoricalCommands: boolean;
+    /** 覆盖会话详情的取数（宿主用自己的缓存去重）。缺省调 `client.sessions.getSession`。 */
+    fetchSessionInfo?: (sessionId: string, options: {
+        fresh: boolean;
+    }) => Promise<SessionDetailSnapshot>;
+}
 export interface SessionConnectOptions {
     /**
      * 在会话进入事件路由后、历史加载与房间订阅开始前同步执行。
@@ -23,7 +65,50 @@ export declare class SessionHub {
     private bound;
     private hasConnected;
     private readonly authBusyReconnect;
+    private readonly hubEmitter;
+    private options;
+    /** token 订阅偏好（第一方 Web 精简模式）；null 表示不设置，订阅时不带字段。 */
+    private streamTokens;
+    /** 状态订阅（mode: "status"）的持有计数。 */
+    private readonly statusWatchCounts;
+    /** 启动连接门控：扣住期间只登记「需要连接」，放开后连一次。 */
+    private connectionHeld;
+    private connectDeferred;
+    /**
+     * 宿主显式要过连接（ensureConnected / reconnect，例如只收产品事件的页面）。有会话、状态订阅或这个需求时，
+     * 鉴权忙碌的临时拒绝都要按服务端建议重试，否则连接会一直停在断开，直到别的动作碰巧重连。
+     */
+    private connectionDemanded;
     constructor(client: BladeClient);
+    /** 调整 Hub 行为（见 SessionHubOptions）。只影响之后创建的会话实例。 */
+    configure(options: Partial<SessionHubOptions>): void;
+    /** 监听 Hub 级事件（见 SessionHubEvents）。返回取消函数。 */
+    on<K extends keyof SessionHubEvents>(name: K, handler: (event: SessionHubEvents[K]) => void): () => void;
+    /**
+     * @internal 第一方 Web 的精简模式传输优化：订阅时是否要 token 级事件。
+     * 空闲会话立即重订阅，运行中的会话等这一轮结束。
+     */
+    setStreamTokens(enabled: boolean): void;
+    /**
+     * 只订阅一个会话的运行状态（chat:start / chat:end / session:updated / system:error），
+     * 不加载历史、不收回合内容。用于后台会话的列表状态与完成通知。引用计数：返回的函数归还一份。
+     * 事件经 Hub 级事件（`on("runEnded")` 等）送达。
+     */
+    watchStatus(sessionId: string): () => void;
+    /**
+     * 启动连接门控：身份确认前扣住连接，`ensureConnected` 只登记需求；`releaseConnection` 后连一次。
+     * 避免用旧凭证连一次、身份确认后又重连一次。不调用则不受影响。
+     */
+    holdConnection(): void;
+    /**
+     * 放开门控。扣住期间登记过连接需求时连一次；`connect: false`（例如身份确认后发现没有登录）只放开、
+     * 丢掉登记的需求，之后的 ensureConnected / reconnect 照常生效。
+     */
+    releaseConnection(options?: {
+        connect?: boolean;
+    }): void;
+    /** 需要实时连接（例如只订阅产品事件、还没有会话时）。已连接或连接中时什么都不做。 */
+    ensureConnected(): void;
     /** 当前 Socket.IO 连接状态。 */
     getConnection(): ConnectionStatus;
     /** 订阅连接状态变化。 */
@@ -58,9 +143,10 @@ export declare class SessionHub {
      * 归零才退订房间并从路由表移除。
      */
     private release;
+    private emitStatusSubscribe;
     /** 不管还有几方持有都立即释放（启动失败、切换身份）。 */
     private forceRelease;
-    private ensureConnected;
+    private needsConnection;
     private setConnection;
     /** 事件带 session_id 时精确路由；缺省时按当前唯一活跃会话兜底。 */
     private route;

package/dist/session/state.d.ts

@@ -2,6 +2,7 @@ import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/mes
 import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
 import { type SessionQueueSnapshot } from "./queue";
+import { type WorkflowRunState } from "./workflow";
 /** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入 + 可选补充）。 */
 export interface AskUserAnswerData {
     selections: Record<number, number[]>;
@@ -13,6 +14,11 @@ export interface AgentLoopInfo {
     toolCallId: string;
     description: string;
     status: "running" | "done" | "error" | "cancelled" | "awaiting_answer";
+    /**
+     * 工作流步骤 fork 出来的子回路：触发它的 workflow:run 工具调用 id。这类回路没有可解析参数的
+     * 父 Agent 工具调用，toolCallId 用回路名合成。普通子智能体没有此字段。
+     */
+    workflowRunId?: string;
 }
 export interface ActiveCompactionState extends CompactionInfo {
     turn_id: string;
@@ -42,15 +48,29 @@ export interface SessionState {
     askAnswers: Record<string, AskUserAnswerData>;
     agentLoops: Record<string, AgentLoopInfo>;
     activeCompaction: ActiveCompactionState | null;
+    /**
+     * 手动整理已被服务端接受、还没收到结束事件。接受应答与真正的开始事件之间有一段准备时间，
+     * 这期间输入框也要保持「正在整理」。
+     */
+    compactionPending: boolean;
     /** 回放（演示 / 彩排）状态；不是回放会话时为 null。 */
     replay: ReplaySnapshot | null;
     /** 服务端持久化的等待消息队列快照；只在 revision 更新时替换。 */
     queue: SessionQueueSnapshot;
     /** 当前身份对这个会话的权限；"viewer" 表示只读（分享链接打开的）。 */
     viewerRole: "owner" | "viewer" | null;
+    /** 工作流运行时间线，按触发它的 workflow:run 工具调用 id 索引（见 workflow.ts）。 */
+    workflowRuns: Record<string, WorkflowRunState>;
     /** Stable anchor for the next older projected page. */
     nextBefore: string | null;
     loadingOlder: boolean;
+    /** 权威历史窗口每提交一次加一（首屏、运行结束 / 重连对账、定位）。向上翻页不算。 */
+    historyRevision: number;
+    /**
+     * timeline 被外部整体改写的次数（rewind、游标失效后的整窗修复、显式重载）。消息导航目录据此
+     * 当场作废：旧条目的 entry id 可能已经不在新的 timeline 上。定位换窗口不算改写。
+     */
+    timelineRevision: number;
 }
 /** 回放会话的快照视图，由服务端的 replay_state 归一化而来。 */
 export interface ReplaySnapshot {
@@ -62,11 +82,18 @@ export interface ReplaySnapshot {
 /** 把服务端的 replay_state 归一化成快照；不是回放会话时返回 null。 */
 export declare function toReplaySnapshot(raw: ReplayState | null | undefined): ReplaySnapshot | null;
 export declare function createInitialSessionState(sessionId: string): SessionState;
+export declare function parentForkToolCallIdFromTurn(turn: TurnProjection): string | null;
 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[];
+/**
+ * 同一条回合换成新版本时保留本地已知、新版本却缺失的字段：
+ * - client_render_id：乐观发言确认后的稳定渲染标识；
+ * - memory_refs：完成投影与历史同步有时不带经验引用（引用只在流式过程中下发一次）。
+ */
+export declare function preserveLocalTurnMetadata(next: TurnProjection, previous: TurnProjection | undefined): TurnProjection;
 /**
  * 用一份新的 turn 列表重建会话状态。
  * addErrorMessage 注入的 role==="error" 消息不在 turns 里，默认会被物化过程抹掉；
@@ -85,3 +112,13 @@ export declare function applyTurnPatch(state: SessionState, patch: PatchEnvelope
 export declare function addErrorMessage(state: SessionState, content: string): SessionState;
 export declare function markInterrupted(state: SessionState): SessionState;
 export declare function markFailed(state: SessionState): SessionState;
+/**
+ * 叠加一条实时 workflow 事件。工具调用已经结束（时间线以工具结果为准）或不在当前 turn 列表里时
+ * 忽略；工作流名固定取工具参数，与历史同源。
+ */
+export declare function withWorkflowEvent(state: SessionState, toolCallId: string, type: string, payload: Record<string, unknown>): SessionState;
+/**
+ * 撤回还没被服务端确认的乐观发言：`clientRequestIds` 给出时只撤回这些请求，否则撤回全部。
+ * 用于排队中断的 chat:end（服务端取消了排队中的发送）。
+ */
+export declare function withoutOptimisticUserTurns(state: SessionState, clientRequestIds?: readonly string[]): SessionState;

package/dist/session/workflow.d.ts

@@ -0,0 +1,57 @@
+import type { TurnProjection } from "../schemas/projection";
+/**
+ * 「工作流运行」的时间线：一次 workflow:run 工具调用执行过程中的步骤与日志。
+ *
+ * 两个来源，规则固定：
+ * - 运行中：服务端流式解析工作流 stdout 后推送的 `workflow:run:start` / `workflow:step` /
+ *   `workflow:log` / `workflow:run:end` 原始事件（不落盘）；
+ * - 工具调用结束后：一律用工具结果里留存的 `[workflow] …` 行重建（落盘，历史也只有这一份）。
+ * 这样实时、历史、重连、回放在运行结束后得到同一份时间线。
+ */
+export type WorkflowRunEntry = {
+    kind: "step";
+    stepId: string;
+    desc: string;
+    stepKind: string;
+} | {
+    kind: "log";
+    text: string;
+};
+export interface WorkflowRunState {
+    /** 触发它的 workflow:run 工具调用 id。 */
+    toolCallId: string;
+    /** 工作流名（工具参数里的 name）；拿不到时为空串，由界面兜底。 */
+    name: string;
+    status: "running" | "done" | "error" | "cancelled";
+    entries: WorkflowRunEntry[];
+}
+/**
+ * workflow:run 工具在 LLM 线上的名字是 `workflow__run`（provider 名与工具名过 LLM 层时用双下划线
+ * 拼接），内部锚点是 `workflow:run`。两种都认；不要先归一化工具名，归一化会把两种都变成 `run`。
+ */
+export declare function isWorkflowRunToolName(name: string): boolean;
+/**
+ * 从工具结果里的 `[workflow] …` 行重建步骤时间线，与后端 parse_workflow_log_line 同词表。
+ * 非前缀行（最终输出 / traceback）不参与，由界面在外层展示。
+ */
+export declare function workflowEntriesFromOutput(output: string): WorkflowRunEntry[];
+/** 工作流名只从工具参数取：历史没有实时事件，两条路径都用这一个来源。 */
+export declare function workflowNameFromArguments(argumentsJson: string): string;
+export declare function isWorkflowEvent(type: string): boolean;
+/**
+ * 把一条实时 workflow 事件叠加到这次运行的时间线上。`current` 为 undefined 表示还没有这次运行。
+ * 返回 null 表示事件不改变时间线。
+ *
+ * `workflow:run:start` 到达 = 事件流从头开始：重连回放会把整个缓冲（含 start 与全部 step/log）
+ * 原样重发，保留旧条目再逐条追加会让时间线每次重连翻一倍；清空重建天然幂等。
+ */
+export declare function applyWorkflowEvent(current: WorkflowRunState | undefined, toolCallId: string, type: string, payload: Record<string, unknown>): WorkflowRunState | null;
+/**
+ * 按当前 turn 列表重建全部工作流运行。
+ * - 工具调用已结束：时间线取工具结果，状态取工具状态（与历史同源）；
+ * - 仍在运行：保留实时事件累积的时间线（没有时为空）。
+ * 只保留当前 turn 列表里还存在的工具调用（rewind 之后旧运行随之消失）。
+ */
+export declare function rebuildWorkflowRuns(turns: readonly TurnProjection[], previous: Readonly<Record<string, WorkflowRunState>>): Record<string, WorkflowRunState>;
+/** 同一次运行里第 n 个子智能体步骤的描述（历史没有 agent:start 通知时给子回路起标题）。 */
+export declare function workflowAgentStepDescription(run: WorkflowRunState | undefined, index: number): string | null;

package/dist/shared/oom.d.ts

@@ -0,0 +1,5 @@
+/** 沙盒因内存超限被杀（退出码 137）时展示给用户的说明。实时 system:error 与历史恢复共用。 */
+export declare const OOM_MESSAGE = "\u6C99\u76D2\u5185\u5B58\u4F7F\u7528\u8D85\u51FA\u9650\u5236\uFF0C\u5DF2\u81EA\u52A8\u91CD\u542F\u3002\u5982\u679C\u7ECF\u5E38\u89E6\u53D1\uFF0C\u53EF\u4EE5\u8054\u7CFB\u7BA1\u7406\u5458\u8C03\u6574\u989D\u5EA6\u3002";
+export declare function isOomText(value: unknown): boolean;
+/** 错误说明的展示文案：内存超限换成友好说明，其余原样。实时与历史两条路径都要经过它，才能对得上。 */
+export declare function userFacingErrorText(message: string): string;

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

@@ -14,6 +14,8 @@ export type ProjectionUpdate = {
     toolCallId?: string;
     toolName?: string;
     workspacePath?: string;
+    /** 本次工具改动的文件（相对工作区）。缺省表示不知道具体文件，按整体变化处理。 */
+    paths?: string[];
 };
 /** 是否包含会改变聊天运行生命周期的事件。纯观测/整理事件不启动新一轮。 */
 export declare function hasChatRunEvent(events: RawEvent[]): boolean;
@@ -31,6 +33,8 @@ export declare class ClientProjectionBuilder {
     /** loop_name → 正在运行的子智能体起点，agent:end 结算并挂到父工具调用上。 */
     private activeSubagentRuns;
     private pendingChildPauses;
+    /** 作答后子回路续跑，最终回复就是随后落盘的父 Agent 工具结果。 */
+    private answeredChildParents;
     private pendingMemoryRefs;
     private activeCompactions;
     private failedCompactions;

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

@@ -21,7 +21,10 @@ export interface ChildPauseInfo {
 }
 export declare function setToolCallStatus(turn: TurnState | TurnProjection | null | undefined, toolCallId: string, status: ToolCallProjection["status"], result: unknown, pendingQuestionRef: PendingQuestionRef | null): void;
 export declare function applyAskUserPauseToTurn(turn: TurnState | TurnProjection | null | undefined, pauseToolData: Record<string, unknown>, toolCallId: string, childLoopName: string, description: string, displayNameResolver: (name: string) => string): void;
+/** Answered questions use the model's compact JSON again in persisted history. */
+export declare function restoreAnsweredAskUserJson(turn: TurnState | TurnProjection | null | undefined, toolCallId: string): void;
 export declare function applyChildPauseToParent(parentTurn: TurnState | TurnProjection | null | undefined, parentToolCallId: string, childLoopName: string, childToolCallId: string, description: string, displayNameResolver: (name: string) => string): void;
+export declare function applyChildResultToParent(parentTurn: TurnState | TurnProjection | null | undefined, parentToolCallId: string, result: string): void;
 export declare function sourceLoopFor(loopId: string, loopDescriptions: Map<string, string>): {
     loop_name: string;
     description: string;

package/dist/types/socket-events.d.ts

@@ -292,8 +292,12 @@ export declare namespace ChatQueueUpdatedPayloadSchema {
 export type ChatQueueUpdatedPayload = ChatQueueUpdatedPayloadSchema.ChatQueueUpdatedPayload;
 export declare namespace SessionCreatedPayloadSchema {
     type SessionId = string;
+    type Session = ({
+        [k: string]: unknown;
+    } | null);
     interface SessionCreatedPayload {
         session_id: SessionId;
+        session?: Session;
         [k: string]: unknown;
     }
 }
@@ -325,9 +329,11 @@ export type SessionUpdatedPayload = SessionUpdatedPayloadSchema.SessionUpdatedPa
 export declare namespace WorkspaceFilesChangedPayloadSchema {
     type SessionId = string;
     type FilePath = (string | null);
+    type FilePaths = (string[] | null);
     interface WorkspaceFilesChangedPayload {
         session_id: SessionId;
         file_path?: FilePath;
+        file_paths?: FilePaths;
         [k: string]: unknown;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blade-hq/agent-client",
-  "version": "2610.0.1",
+  "version": "2612.0.0-beta.1",
   "description": "Blade Agent 框架无关客户端：会话实时状态机、REST 通道、弹窗登录、页面协作。浏览器与 Node.js 通用。",
   "repository": {
     "type": "git",
@@ -13,6 +13,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "files": [