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

package/dist/polling-backoff.d.ts

@@ -0,0 +1,11 @@
+/** Scheduling policy for read-only polling; never sends or replays a request. */
+export declare class PollingBackoff {
+    private readonly intervalMs;
+    private failures;
+    private nextAt;
+    constructor(intervalMs: number);
+    reset(): void;
+    failed(error: unknown): void;
+    /** Zero means ready, false means stop, otherwise wait at least this many ms. */
+    waitMs(): number | false;
+}

package/dist/resources/chat-groups.d.ts

@@ -0,0 +1,31 @@
+import type { BladeClient } from "../blade-client";
+export interface ChatGroup {
+    id: string;
+    name: string;
+    instructions: string;
+    created_at: string;
+    updated_at: string;
+    session_count: number;
+    initiator: "ui" | "sdk" | null;
+    workspace_path: string;
+}
+export declare class ChatGroupsResource {
+    private readonly client;
+    constructor(client: BladeClient);
+    list(): Promise<ChatGroup[]>;
+    create(payload: {
+        name: string;
+        instructions?: string;
+        initiator?: "ui" | "sdk";
+    }): Promise<ChatGroup>;
+    update(groupId: string, payload: {
+        name?: string;
+        instructions?: string;
+    }): Promise<ChatGroup>;
+    delete(groupId: string, options?: {
+        deleteWorkspace?: boolean;
+    }): Promise<{
+        deleted: boolean;
+        deleted_sessions: number;
+    }>;
+}

package/dist/resources/computers.d.ts

@@ -26,6 +26,29 @@ export interface SessionComputer {
 export interface SessionComputerList {
     computers: SessionComputer[];
 }
+/**
+ * 账号级电脑目录里的一台机器。
+ *
+ * 只有「这台机器登记过、此刻在不在线」这类账号事实，**没有**会话授权状态——
+ * 「本次会话能不能用它」是另一件事，由会话接口回答。两者混在一起说，用户就会
+ * 把「在线」当成「已授权」，或者反过来。
+ */
+export interface AccountComputer {
+    id: string;
+    label: string;
+    hostname?: string | null;
+    os?: string | null;
+    arch?: string | null;
+    blade_home?: string | null;
+    workspace?: string | null;
+    daemon_version?: string | null;
+    created_at: string;
+    last_seen_at?: string | null;
+    online: boolean;
+}
+export interface AccountComputerList {
+    computers: AccountComputer[];
+}
 /**
  * 一台电脑在界面上该显示成什么状态。
  *
@@ -39,17 +62,46 @@ export interface SessionComputerList {
  */
 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);
+    /**
+     * 列出当前账号登记过的全部电脑及其在线状态。
+     *
+     * 首页还没有会话，也要能看到同一份清单——判定各写一份必然分叉，一边的兜底会把
+     * 另一边的错误盖住（#1597）。所以账号事实只从这一个接口读。
+     */
+    listAccount(): Promise<AccountComputerList>;
     /**
      * 列出当前用户的全部电脑，带上"在不在线"和"这次会话能不能用"。
      * 服务端只查库，电脑离线时同样返回，所以拿得到"它离线了"这个结论。

package/dist/resources/plugins.d.ts

@@ -0,0 +1,43 @@
+import type { BladeClient } from "../blade-client";
+/**
+ * 一个插件在当前用户眼里的展示信息，**与会话无关**。
+ *
+ * 连接器面板在首页（还没有 sessionId）也要显示插件名称和图标，所以这份目录
+ * 只能依赖用户身份：它不激活任何插件、不启动沙盒、不读用户配置。
+ */
+export interface PluginCatalogEntry {
+    /** 技术 ID：路径、授权、缓存与调用一律用它。 */
+    name: string;
+    /** 包声明的业务名称；null 时界面回退到 `name`。 */
+    display_name: string | null;
+    /**
+     * 包内图标的 opaque token，没有可用图标时为 null。
+     * 交给 `fetchPluginIcon`，**不是**路径，也不能直接当 URL 用。
+     */
+    icon: string | null;
+    /** 当前用户是否安装了它。 */
+    installed: boolean;
+}
+/**
+ * 按用户读取的插件目录（无会话）。
+ *
+ * 图标只能通过带凭据的请求取字节，再转成 object URL——把 `<img>` 指向 API
+ * 路径要靠 cookie，token 用户会拿到 401/403。
+ */
+export declare class PluginsResource {
+    private client;
+    constructor(client: BladeClient);
+    /**
+     * 列出当前用户安装的插件及其展示信息。
+     *
+     * 服务端可能为了补齐名称/图标惰性获取包内容，但绝不激活插件、不连 MCP；
+     * 单个插件的展示信息读不出来只会降级成占位，不会让整份目录失败。
+     */
+    catalog(init?: RequestInit): Promise<{
+        plugins: PluginCatalogEntry[];
+    }>;
+    /** 取一个插件的包内图标字节（用户级，不需要会话）。 */
+    fetchIcon(name: string): Promise<Blob>;
+    /** 带凭据的图标地址；能直接用 blob URL 的地方优先用 `fetchIcon`。 */
+    iconUrl(name: string): string;
+}

package/dist/resources/sessions.d.ts

@@ -1,11 +1,81 @@
 import type { BackgroundTask, BackgroundTaskStopResult } from "../schemas/background";
 import type { TurnProjection } from "../schemas/projection";
+import type { McpAppArchive } from "../schemas/mcp-app";
 import type { PublishedSolutionRef, ReplayPreview, ReplaySpeed, SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
+import type { McpAppContextState, McpAppContextUpdate } from "../schemas/mcp-app";
 import type { Task } from "../schemas/task";
 import type { BladeClient, UploadProgress } from "../blade-client";
 import type { AgentSession } from "../session/agent-session";
 import { type SessionDefinition } from "../session/definition";
 import type { SessionProfile } from "../types/sdk-profile";
+export interface SessionPlugin {
+    /** Technical ID: always used for paths, authorization, caching and calls. */
+    name: string;
+    /** Business name declared by the package; null falls back to `name`. */
+    display_name?: string | null;
+    /**
+     * Opaque content token for the package-local icon, or null when the plugin
+     * ships none. Pass it to `fetchSessionPluginIcon`; never used as a path.
+     */
+    icon?: string | null;
+    /** Whether BH lists this plugin for the current user; null means BH was unavailable. */
+    installed: boolean | null;
+    /**
+     * Configuration standing as the list could determine it without reading the
+     * user's Home: `unchecked` means nobody has looked yet, never "configured".
+     */
+    config?: SessionPluginConfigSummary;
+    /** Persisted session choice, independent of preparation success. */
+    active: boolean;
+    /** Previously prepared skills may remain after deselection. */
+    projected: boolean;
+    projection_source?: string | null;
+    status: string;
+    reason?: string | null;
+}
+/** Selection/preparation result; installed facts are obtained from the BH-backed list. */
+export type SessionPluginActivation = Pick<SessionPlugin, "name" | "active" | "status" | "reason">;
+/**
+ * How a plugin's user configuration stands.
+ *
+ * `not_required` — the package ships no config schema, the plugin keeps its old
+ * behaviour. `required` — a schema exists but the stored configuration is
+ * missing or does not validate. `configured` — stored configuration validates.
+ * `error` — the declaration itself is unusable.
+ */
+export type SessionPluginConfigStateName = "not_required" | "required" | "configured" | "error";
+/** List-level view: `unchecked` means nobody has read this user's file yet. */
+export type SessionPluginConfigSummary = SessionPluginConfigStateName | "unchecked";
+export interface SessionPluginConfigError {
+    /** JSON Pointer of the offending field. */
+    path: string;
+    /** Value-free message; the platform never echoes submitted secrets. */
+    message: string;
+}
+export interface SessionPluginConfigState {
+    state: SessionPluginConfigStateName;
+    reason: string | null;
+    /** The package-declared JSON Schema (Draft 2020-12), or null. */
+    schema: Record<string, unknown> | null;
+    /** Stored values with `writeOnly` properties removed. */
+    values: Record<string, unknown>;
+    /** JSON Pointers of `writeOnly` properties that currently hold a value. */
+    write_only: string[];
+    /** Opaque revision for optimistic concurrency; null when nothing is stored. */
+    revision: string | null;
+    errors: SessionPluginConfigError[];
+}
+export interface SessionPluginConfigSet {
+    /** JSON Pointer; arrays are replaced as a whole. */
+    path: string;
+    value: unknown;
+}
+export interface SessionPluginConfigUpdate {
+    /** Omit (or pass null) to publish unconditionally. */
+    expected_revision?: string | null;
+    set?: SessionPluginConfigSet[];
+    remove?: string[];
+}
 export interface CreateSessionRequest {
     intent?: string;
     template_id?: TemplateId;
@@ -28,6 +98,7 @@ export interface CreateSessionRequest {
     daemon_id?: string | null;
     /** runtime_type 为 "native" 时必填：daemon 上要用哪个原生智能体（如 rt_codex）。 */
     agent_runtime_id?: string | null;
+    chat_group_id?: string | null;
 }
 export interface CheckpointNode {
     id: string;
@@ -128,6 +199,43 @@ export interface SessionContextStats {
     context_window: number;
     compaction_ratio: number;
 }
+export interface SessionTurnsPage {
+    turns: TurnProjection[];
+    nextBefore: string | null;
+    currentMode: "planning" | "executing";
+}
+/** `getSessionTurnsPage` 的取数参数：向后翻页（before）或从某条发言定位（fromEntryId）。 */
+export interface SessionTurnsQuery {
+    limit?: number;
+    before?: string;
+    /**
+     * 从这条用户发言开始、一直到最新。服务端按当前分支校验它，命中不了不会回空页
+     * （`entry_not_found` / `entry_not_in_branch`），窗口首条就是这条发言，它的
+     * `nextBefore` 可以继续当 `before` 往上翻。
+     */
+    fromEntryId?: string;
+}
+/**
+ * 服务端明确说这条发言不在当前分支上（`entry_not_found` / `entry_not_in_branch`），
+ * 和"这次没取到"（网络 / 5xx / 鉴权）分开：前者说明这个定位目标已经没了，后者只说明这次失败。
+ */
+export declare function isEntryGoneError(error: unknown): boolean;
+/** 侧栏「消息历史」的一条：只有 id、标题和时间，没有消息体。 */
+export interface SessionTurnIndexItem {
+    entryId: string;
+    preview: string;
+    createdAt: string | null;
+}
+export interface SessionTurnIndex {
+    sessionId: string;
+    items: SessionTurnIndexItem[];
+}
+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;
@@ -196,12 +304,77 @@ export interface ImportSessionOptions {
 }
 export declare class SessionsResource {
     private client;
+    private readonly pendingImages;
+    /** Fetch an immutable message image using this client's authenticated identity. */
+    fetchImage(sessionId: string, assetId: string, preview?: boolean): Promise<Blob>;
+    /** Fetch a public-share image; the server validates the share token on every request. */
+    fetchSharedImage(token: string, assetId: string, preview?: boolean): Promise<Blob>;
+    private fetchImagePath;
     constructor(client: BladeClient);
+    getMcpApp(sessionId: string, sourceId: string, init?: RequestInit): Promise<McpAppArchive>;
+    onMcpAppChanged(sessionId: string, sourceId: string, listener: () => void): () => void;
+    callMcpApp(sessionId: string, sourceId: string, request: {
+        request_id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }, init?: RequestInit): Promise<{
+        response: Record<string, unknown>;
+        replayed: boolean;
+    }>;
     /**
      * 连接一个已存在的会话，返回实时会话对象 AgentSession
      * （自动完成历史加载、Socket.IO 订阅、断线重连补数）。
      */
     connect(sessionId: string): Promise<AgentSession>;
+    listSessionPlugins(sessionId: string, init?: RequestInit): Promise<{
+        plugins: SessionPlugin[];
+        sync_version: number;
+        sync_pending: boolean;
+    }>;
+    setSessionPluginActivation(sessionId: string, name: string, active: boolean, init?: RequestInit): Promise<{
+        plugin: SessionPluginActivation;
+        sync_version: number;
+    }>;
+    /**
+     * Fetch a plugin's package-local icon as bytes.
+     *
+     * The request carries the client's own bearer credentials, so callers turn
+     * the blob into an object URL instead of pointing `<img>` at an API path and
+     * hoping the request is authenticated.
+     */
+    fetchSessionPluginIcon(sessionId: string, name: string): Promise<Blob>;
+    /** Authenticated URL for the icon; useful where a blob URL cannot be used. */
+    sessionPluginIconUrl(sessionId: string, name: string): string;
+    /**
+     * 准备一个插件的配置：把包准备好并读出用户的配置契约，**不启用**它。
+     *
+     * 开启插件前必须先走这一步：缺配置时用户只会看到配置表单，服务端不会先把
+     * active 持久化成 true 再靠补偿关掉。它不修改会话的插件选择、不连接 MCP。
+     */
+    prepareSessionPluginConfig(sessionId: string, name: string, init?: RequestInit): Promise<{
+        plugin: string;
+        config: SessionPluginConfigState;
+    }>;
+    /**
+     * Read a plugin's configuration contract and the user's stored values.
+     *
+     * Secrets are never returned: `write_only` lists the pointers that hold one.
+     */
+    getSessionPluginConfig(sessionId: string, name: string, init?: RequestInit): Promise<{
+        plugin: string;
+        config: SessionPluginConfigState;
+    }>;
+    /**
+     * Publish explicit set/remove operations to the user's keychain file.
+     *
+     * Fields absent from both lists keep their stored value, so a form never has
+     * to round-trip a secret. Rejections leave the previous file untouched; the
+     * call never restarts MCP servers.
+     */
+    updateSessionPluginConfig(sessionId: string, name: string, update: SessionPluginConfigUpdate, init?: RequestInit): Promise<{
+        plugin: string;
+        config: SessionPluginConfigState;
+    }>;
     /** 创建新会话并直接连接，返回可收发消息的 AgentSession。 */
     create(request?: CreateSessionRequest | SessionDefinition): Promise<AgentSession>;
     private createDeclared;
@@ -216,6 +389,7 @@ export declare class SessionsResource {
         solution_id?: string;
         solution_registry_id?: string;
         q?: string;
+        chat_group_id?: string;
     }): Promise<PaginatedSessionsResult>;
     listSessionsWithSkillData(): Promise<SkillDevSession[]>;
     searchOwnedContent(params: {
@@ -237,6 +411,7 @@ export declare class SessionsResource {
     getSession(sessionId: string, init?: RequestInit): Promise<SessionDetail>;
     updateSession(sessionId: string, payload: {
         intent?: string;
+        chat_group_id?: string | null;
     }): Promise<SessionDetail>;
     setSessionEnv(sessionId: string, env: Record<string, string>): Promise<SessionDetail>;
     pinSession(sessionId: string, pinned: boolean): Promise<SessionInfo>;
@@ -264,6 +439,20 @@ export declare class SessionsResource {
     getSharedSession(token: string): Promise<TurnProjection[]>;
     getSessionTasks(sessionId: string): Promise<Task[]>;
     getSessionTurns(sessionId: string): Promise<TurnProjection[]>;
+    getSessionTurnsPage(sessionId: string, options?: SessionTurnsQuery, init?: RequestInit): Promise<SessionTurnsPage>;
+    /**
+     * 当前分支上可导航的用户发言目录（消息导航侧栏）。
+     *
+     * 只回 id、标题和时间：侧栏要列的是**整条会话**的发言，而窗口外的发言 id 只能
+     * 从服务端拿；消息体仍然走 `/turns`。
+     */
+    getSessionTurnIndex(sessionId: string): Promise<SessionTurnIndex>;
+    getMcpAppContext(sessionId: string, sourceId: string, init?: RequestInit): Promise<McpAppContextState>;
+    updateMcpAppContext(sessionId: string, sourceId: string, body: McpAppContextUpdate, init?: RequestInit): Promise<{
+        status: "accepted";
+        revision: string;
+    }>;
+    getSessionTurnCommands(sessionId: string): Promise<HistoricalCommand[]>;
     listResultFeedback(sessionId: string): Promise<ResultFeedback[]>;
     putResultFeedback(sessionId: string, assistantEntryId: string, feedback: {
         helpful: boolean;
@@ -311,7 +500,7 @@ export declare class SessionsResource {
         reachable: boolean;
         requires_proxy: boolean;
     }>;
-    listDir(sessionId: string, dirPath: string): Promise<FileEntry[]>;
+    listDir(sessionId: string, dirPath: string, showHidden?: boolean): Promise<FileEntry[]>;
     countFiles(sessionId: string, dirPath?: string): Promise<number>;
     /** 在浏览器中下载一个会话文件。 */
     downloadFile(sessionId: string, filePath: string, downloadName?: string): Promise<void>;

package/dist/resources/site-visits.d.ts

@@ -0,0 +1,32 @@
+import type { BladeClient } from "../blade-client";
+/** 全站访问统计快照。每个数字都来自真实请求，没有基数、系数或回填。 */
+export interface SiteVisitsSummary {
+    /** 统计日期，按北京时间切日（`YYYY-MM-DD`）。 */
+    date: string;
+    /** 统计时区，固定为 `Asia/Shanghai`。 */
+    timezone: string;
+    /** 当天出现过的匿名访客数：按天去重，不是实时在线人数。 */
+    today_uv: number;
+    /** 当天的页面访问次数。 */
+    today_pv: number;
+    /** 功能上线以来累计的页面访问次数。 */
+    total_pv: number;
+    /** 快照生成时间（RFC3339 UTC）。并发响应可能倒序到达，用它丢弃旧快照。 */
+    as_of: string;
+}
+/**
+ * 全站访问统计（内置 Web 的匿名计数）。
+ *
+ * 这两个操作刻意走独立传输：不带 bearer、不触发 401 登录刷新，也不读登录
+ * Cookie——计数只依赖匿名访客 Cookie，因此登录态失效时统计依然可用。它们
+ * 只在同源的内置 Web 里使用，不是给第三方宿主页面用的。
+ */
+export declare class SiteVisitsResource {
+    private readonly client;
+    constructor(client: BladeClient);
+    /** 上报一次页面访问，返回当前快照；不承诺本次已计入或已落盘。 */
+    record(): Promise<SiteVisitsSummary>;
+    /** 只读快照：不设置访客 Cookie，也不增加任何计数。 */
+    summary(): Promise<SiteVisitsSummary>;
+    private request;
+}

package/dist/rest.d.ts

@@ -19,3 +19,11 @@ export interface BladeFetchInit {
     headers?: HeadersInit;
     signal?: AbortSignal | null;
 }
+/**
+ * 按客户端规则把后端路径拼成绝对 URL：`baseUrl` 自带路径前缀时保留前缀，
+ * 路径里的前导 `/` 只表示"从后端根开始"，不会被解释成站点根目录。
+ *
+ * 单独放在传输层，是为了让不走 `fetch()` 鉴权通道的资源（例如匿名的站点统计）
+ * 落到同一个后端地址上，不必各自再写一份 URL 规则。
+ */
+export declare function buildBackendUrl(baseUrl: string, path: string): URL;

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

@@ -5,6 +5,14 @@ export declare function normalizeMessageContent(content: unknown): MessageConten
 export declare function getTextContent(content: MessageContent): string;
 export declare function isSystemReminderText(text: string): boolean;
 export declare function isLegacyForkContextText(text: string): boolean;
+/**
+ * 平台自己写进去、不该露给用户的内部提示。
+ *
+ * 服务端的消息导航目录有一份同名同语义的 Python 实现
+ * （`server/.../routes/sessions.py` 的 `_is_hidden_internal_message`）：客户端靠它决定
+ * 渲染不渲染，服务端靠它决定进不进目录。改这里必须同时改那边，否则目录会列出没有对应
+ * 行的死条目，或者把内部提示原文当标题露出去。
+ */
 export declare function isHiddenInternalMessage(message: Pick<ChatMessage, "role" | "content">, options?: {
     includeLegacyForkContext?: boolean;
 }): boolean;
@@ -59,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

@@ -8,6 +8,9 @@ export interface ImageUrlContentPart {
     type: "image_url";
     image_url: {
         url: string;
+        source_path?: string;
+        width?: number;
+        height?: number;
     };
 }
 export interface FileContentPart {

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 {
@@ -54,8 +70,14 @@ export interface TurnProjection {
     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;
@@ -72,6 +94,8 @@ export interface TurnProjection {
     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;
@@ -84,6 +85,9 @@ export declare const SessionInfo: import("arktype/internal/variants/object.ts").
     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"> & {
@@ -111,6 +115,9 @@ export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "soluti
     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;
 };