@webskill/sdk 0.9.0 → 0.11.0

package/dist/{index-znZjobkr.d.ts → index-D3mONFHD.d.ts}

@@ -1,4 +1,4 @@
-import { C as UiSpecDrafts, D as UiSurfaceActionRequest, F as DiscoveryResult, H as Page, L as FileSystemProvider, U as PageQuery, _ as MemoryStore, at as SkillDocument, d as LlmContentPart, f as LlmMessage, g as LlmToolSpec, h as LlmToolCall, i as FormField, it as SkillDiscovery, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, nt as SkillCatalog, o as InteractionPolicy, ot as SkillInstallSource, p as LlmResponse, r as ChartSpec, rt as SkillCatalogEntry, s as InteractionRequest, t as Artifact, u as LlmCompleteInput, ut as SkillManifest, v as RenderBlock, w as UiSpecEvent, wt as WebSkillErrorCode, x as UiBridge, xt as ValidationReport, y as RenderResultRequest, yt as UiSpecNode, z as JsonSchema } from "./types-B3n0cMZu-BDhheIhX.js";
+import { B as JsonSchema, G as RemoteUrlPolicy, I as DiscoveryResult, O as UiSurfaceActionRequest, R as FileSystemProvider, S as UiBridge, St as ValidationReport, T as UiSpecEvent, Tt as WebSkillErrorCode, U as Page, W as PageQuery, _ as LlmToolSpec, at as SkillDiscovery, b as RenderResultRequest, bt as UiSpecNode, d as LlmContentPart, dt as SkillManifest, f as LlmMessage, g as LlmToolCall, h as LlmTokenUsage, i as FormField, it as SkillCatalogEntry, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, o as InteractionPolicy, ot as SkillDocument, p as LlmResponse, r as ChartSpec, rt as SkillCatalog, s as InteractionRequest, st as SkillInstallSource, t as Artifact, u as LlmCompleteInput, v as MemoryStore, w as UiSpecDrafts, y as RenderBlock } from "./types-C26b05fW-CdrRCRDb.js";
 //#region ../runtime/dist/index.d.ts
 //#region src/llm/parts.d.ts
 /** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
@@ -22,6 +22,45 @@ type TextualToolContent = {
   text?: string;
   data?: unknown;
 };
+/**
+ * 参与 `toolResultMaxBytes` 截断的分片类型（FR-23.3）。**判据的单一来源。**
+ *
+ * 白名单而不是黑名单：黑名单式下新加的分片默认「参与截断」，
+ * 漏改一处就会把一份 PDF 截成坏文件、把 docx 文本腰斩，而且没有任何报错。
+ * 白名单式下新分片默认**不参与**，要受文本预算约束必须显式加进来。
+ * @experimental
+ */
+declare const TEXT_BUDGETED_CONTENT_TYPES: ReadonlySet<string>;
+/**
+ * `file` 分片的上限（FR-23.4），量的是**实际上线的 base64 长度**而不是解码后的字节——
+ * provider 的限额算的是请求载荷。
+ *
+ * 2026-08-14 查证的三家上限：
+ * | provider  | 上限                                    | 出处                    |
+ * | --------- | --------------------------------------- | ----------------------- |
+ * | Anthropic | **32 MB**（**整个请求载荷**）、600 页   | PDF support / 请求大小  |
+ * | OpenAI    | 单文件 50 MB，全部文件合计 50 MB        | File inputs / 使用须知  |
+ * | Gemini    | 50 MB 或 1000 页（内联与 Files API 同） | 文档理解 / 技术详情     |
+ *
+ * 取最小值 Anthropic 的 32 MB。它是**整个请求**的额度，不是文档单独的额度，
+ * 所以再留出余量给系统提示词、catalog（约 34 KB）、历史消息与其余分片。
+ * 25 000 KB base64 ≈ 18.75 MB 原始 PDF。取 1024 的整数倍：设置界面按 KB 展示，
+ * 十进制的 24 000 000 会显示成 23437.5 这种读不出来的数。
+ */
+declare const DEFAULT_MAX_DOCUMENT_BYTES = 25600000;
+/**
+ * `document-text` 分片的上限（FR-23.4）。
+ *
+ * 约束来自**上下文窗口**而不是请求大小：抽出来的文本要整段进上下文。
+ * 按英文约 4 字节/token 折算，500 KB ≈ 128K token，占 200K 窗口的多半，
+ * 给历史消息与模型的回答留下其余。
+ */
+declare const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 512000;
+/**
+ * 单次 fetchData 结果的字节上限（分册 16，FR-16.6）：1000 KB。
+ * 结构化数据不是文档，量级差一个数量级；超出**只拒不截**——截断的 JSON 解不出来。
+ */
+declare const DEFAULT_MAX_DATA_SOURCE_BYTES = 1024000;
 /**
  * 工具结果的内容分片（0.6.0 §1.1）。
  * `image` 分片不参与 `toolResultMaxBytes` 截断——那份预算是给文本的，
@@ -35,6 +74,27 @@ type ToolContent = TextualToolContent | {
   data: string;
   id: string;
   text?: undefined;
+} |
+/** 原样直通给模型的文档（PDF 等），受 `maxDocumentBytes` 约束 @experimental */
+{
+  type: 'file';
+  mimeType: string;
+  data: string;
+  name?: string;
+  id: string;
+  text?: undefined;
+} |
+/**
+ * 从文档里抽出来的文本（docx 等），受 `maxDocumentTextBytes` 约束。
+ * 它**就是**文本，但与普通工具文本分开计预算：混算会出现
+ * 「PDF 读全了、Word 只读了一半」这种无法解释的差异。
+ * @experimental
+ */
+{
+  type: 'document-text';
+  text: string;
+  name?: string;
+  id: string;
 };
 interface ToolResult {
   ok: boolean;
@@ -51,9 +111,19 @@ interface ScriptExecutionContext {
   skillName: string;
   runId: string;
   readReference(relativePath: string): Promise<string>;
+  /** 读技能自己的 `assets/`；与 readReference 共用路径断言，不得跨目录 @experimental */
+  readAsset?(relativePath: string): Promise<string>;
+  /** `assets/` 的典型内容是图片/字体/数据包，纯文本出口不够 @experimental */
+  readAssetBinary?(relativePath: string): Promise<Uint8Array>;
   writeArtifact(path: string, content: string | Uint8Array, options?: {
     mimeType?: string;
   }): Promise<Artifact>;
+  /**
+   * 按**宿主声明的 sourceId** 取数（FR-16.1）。脚本给不了 URL——
+   * 目标由宿主在 `DataSourceDef.target` 里写死，这就是「唯一授权面」。
+   * 宿主未装配即不存在（同 readAsset / confirm）。 @experimental
+   */
+  fetchData?(sourceId: string, params?: Record<string, unknown>): Promise<unknown>;
   /** 脚本主动请求人在环确认；策略见 InteractionPolicy.confirmations */
   confirm?(message: string): Promise<boolean>;
   /** 宿主侧降级 warning 出口（网络阻断等；引擎接线到 run.warning trace） */
@@ -148,6 +218,19 @@ interface AnthropicClientConfig {
   requestTimeoutMs?: number;
   /** max_tokens（Messages API 必填），默认 4096 */
   maxTokens?: number;
+  /**
+   * Extended thinking 开关（预算 token 数）。语义（0.10.0 复核后固化的分层口径）：
+   * - 不设置 ⇒ 完全不请求思考能力（**直连客户端的缺省**）；
+   * - `> 0` 的正整数 ⇒ 启用并透传 `budget_tokens`；
+   * - `<= 0` / 非整数 / 非有限数 ⇒ 一律视为关闭（不发出 thinking 参数，避免供应商 400）。
+   * 经 `createLlmClient` 装配时由工厂层按 `?? 10_000` 默认开启（0.10.0 #40.4），
+   * 与直连客户端的「默认关闭」是同一字段的两层缺省，不互相冲突。
+   * 开启后响应里的 thinking block 解析进 `LlmResponse.thinking`，
+   * 流式路径的 thinking_delta 映射为 `thinking-delta` 事件。
+   * 注意：Anthropic 要求 thinking 开启时不传 temperature（只允许默认值 1），
+   * 本客户端在开启时自动省略 temperature。
+   */
+  thinkingBudgetTokens?: number;
   /**
    * 浏览器直调 opt-in：true 时发送 anthropic-dangerous-direct-browser-access 头
    * （默认 false 不发——仅在明确运行于浏览器且无服务端代理时开启）
@@ -316,14 +399,18 @@ declare const READ_SKILL_FILE_TOOL: ToolDefinition;
 //#endregion
 //#region src/tools/askUserTool.d.ts
 declare const ASK_USER_TOOL_NAME = "ask_user";
+/** 一次 `ask_user` 能收的字段数上限（FR-11.3 裁决值），可由 `AgentLoopConfig` 覆盖 */
+declare const ASK_USER_MAX_FIELDS = 20;
+/** `fields[].type`：`FormField['type']` 的八种。`multi-select` 不在其中——它的值是数组（FR-11.1b） */
+declare const ASK_USER_FIELD_TYPES: readonly ["text", "number", "boolean", "select", "textarea", "file", "password", "date"];
 declare const ASK_USER_INPUT_SCHEMA: JsonSchema;
 /** 内建工具：LLM 信息不足时主动向用户提问；仅当配置了 UiBridge 时注册 */
 declare const ASK_USER_TOOL: ToolDefinition;
 //#endregion
 //#region src/tools/scriptContext.d.ts
 /**
- * 脚本执行上下文：只暴露 readReference / writeArtifact 两个显式能力，
- * 不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
+ * 脚本执行上下文：只暴露 readReference / readAsset / readAssetBinary / writeArtifact
+ * 四个显式能力，不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
  */
 declare function createScriptContext(deps: {
   fs: FileSystemProvider;
@@ -333,6 +420,12 @@ declare function createScriptContext(deps: {
   runId: string;
   /** 提供时暴露 context.confirm（由引擎按交互策略实现） */
   confirm?: (message: string) => Promise<boolean>;
+  /**
+   * 提供时暴露 context.fetchData（引擎按 DataSourcePolicy 实现，FR-16.1）。
+   * 宿主没声明数据源就整个键不存在——脚本 `typeof context.fetchData` 即可探测，
+   * 不给「存在但永远失败」的假出口。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
   /** 宿主侧降级 warning 出口（网络阻断等；引擎接线到 run.warning trace） */
   onWarning?: (message: string) => void;
   /** writeArtifact 创建产物后的回调（引擎记录新产物 ID，执行后单次 listArtifacts 过滤） */
@@ -375,6 +468,11 @@ type ExecuteLifecycleData = {
 } | {
   kind: 'llm-delta';
   delta: string;
+} |
+/** 思考增量（0.10.0 UI-UX5 #32）：流式思考逐段透出；非流式路径一次性补发整段 */
+{
+  kind: 'thinking-delta';
+  delta: string;
 } | {
   kind: 'interaction-resumed';
   interactionId: string;
@@ -398,6 +496,11 @@ type InteractLifecycleData = {
 /** complete / fail：终态原因 */
 interface TerminalLifecycleData {
   reason: RunTerminationReason;
+  /**
+   * 失败时的具体说明（`RuntimeRun.error.message`）。`reason` 只有七种取值，
+   * 说不出「哪个上限、哪个模型、本轮带了文档」这类唯一能指导下一步的信息。
+   */
+  detail?: string;
 }
 interface LifecycleEventBase {
   runId: string;
@@ -444,7 +547,11 @@ type LifecycleHook = (ctx: LifecycleHookContext) => Promise<void | {
 }>;
 //#endregion
 //#region src/trace/types.d.ts
-type TraceEventType = 'skill.routed' | 'skill.activated' | 'skill.integrity-failed' | 'llm.request' | 'llm.response' | 'tool.started' | 'tool.completed' | 'tool.failed' | 'tool.denied' | 'artifact.created' | 'ui.requested' | 'ui.resumed' | 'ui.surface-action.requested' | 'ui.surface-action.resolved' | 'ui.rendered' | 'ui.degraded' | 'todo.created' | 'todo.updated' | 'todo.cleared' | 'run.warning' | 'run.completed' | 'run.cancelled' | 'run.failed' | 'run.resumed';
+type TraceEventType = 'skill.routed' | 'skill.activated' | 'skill.integrity-failed' | 'llm.request' | 'llm.response' |
+/** 一轮模型调用产出的一段思考正文（data.text；每轮至多一条，UI-UX5 #32） */
+'llm.thinking' |
+/** 一轮模型调用的 token 用量（data.inputTokens/outputTokens；上游不回报则无此事件，UI-UX5 #47） */
+'llm.usage' | 'tool.started' | 'tool.completed' | 'tool.failed' | 'tool.denied' | 'artifact.created' | 'ui.requested' | 'ui.resumed' | 'ui.surface-action.requested' | 'ui.surface-action.resolved' | 'ui.rendered' | 'ui.degraded' | 'todo.created' | 'todo.updated' | 'todo.cleared' | 'run.warning' | 'run.completed' | 'run.cancelled' | 'run.failed' | 'run.resumed';
 interface TraceEvent {
   id: string;
   runId: string;
@@ -465,7 +572,7 @@ interface AgentLoopConfig {
   temperature?: number;
   /** 设为 'off' 时完成 run 不调用 uiBridge.renderResult */
   renderResult?: 'off';
-  /** 工具结果回喂上限（字节，默认 100_000；超长头尾保留 + 完整内容落 artifact） */
+  /** 工具结果回喂上限（字节，默认 256_000；超长头尾保留 + 完整内容落 artifact） */
   toolResultMaxBytes?: number;
   /** session paramHistory 保留条数上限（默认 50，超出裁最旧） */
   paramHistoryLimit?: number;
@@ -480,6 +587,23 @@ interface AgentLoopConfig {
    * 不设上限的话，模型会一路猜到 maxTurns 用完，用户等到最后拿到的还是一句失败。
    */
   maxUnknownToolRetries?: number;
+  /**
+   * 一次 `ask_user` 能收的字段数上限（默认 20，FR-11.3）。超出即拒绝整次调用，
+   * **不截断**——截断会让模型以为字段全收到了。
+   */
+  askUserMaxFields?: number;
+  /**
+   * `file` 分片的 base64 长度上限（默认 `DEFAULT_MAX_DOCUMENT_BYTES`，FR-23.4）。
+   * 超出即**拒绝并说明**：截断一份 PDF 等于给模型一份坏文件。
+   */
+  maxDocumentBytes?: number;
+  /**
+   * `document-text` 分片的字节上限（默认 `DEFAULT_MAX_DOCUMENT_TEXT_BYTES`，FR-23.4）。
+   * 同样拒绝而不截断：截半份内容给模型，而它不知道自己少看了什么。
+   */
+  maxDocumentTextBytes?: number;
+  /** `read_linked_document` 的出站准入策略；与脚本取数共用同一个判定（AC-G23） */
+  remoteUrl?: RemoteUrlPolicy;
 }
 /** 技能状态拦截 port（治理装配；无注入默认全放行） */
 interface SkillStateGuard {
@@ -977,6 +1101,16 @@ type BridgeRequest = {
   kind: 'readReference';
   id: string;
   path: string;
+} | {
+  kind: 'readAsset';
+  id: string;
+  path: string;
+} |
+/** 回值走 `number[]`：进程沙箱的桥是 JSON stdio，与 writeArtifact 同口径 */
+{
+  kind: 'readAssetBinary';
+  id: string;
+  path: string;
 } | {
   kind: 'writeArtifact';
   id: string;
@@ -987,6 +1121,13 @@ type BridgeRequest = {
   kind: 'confirm';
   id: string;
   message: string;
+} |
+/** 取数只传宿主声明的 sourceId；**脚本给不了 URL**（FR-16.2 的唯一授权面） */
+{
+  kind: 'fetchData';
+  id: string;
+  sourceId: string;
+  params?: Record<string, unknown>;
 };
 interface BridgeResponse {
   id: string;
@@ -1004,11 +1145,18 @@ interface BridgeResponse {
 type CapabilityMode = boolean | 'require-approval';
 /** 授权粒度：'once-per-run'（默认，run 内同类能力批准一次）/ 'every-call'（每次调用都问） */
 type ApprovalScope = 'once-per-run' | 'every-call';
-/** 三能力独立开关；缺省全开，显式 false 即关闭（TOOL_UNSUPPORTED） */
+/** 能力独立开关；缺省全开，显式 false 即关闭（TOOL_UNSUPPORTED） */
 interface BridgeCapabilities {
   readReference?: CapabilityMode;
+  /** 同时管 readAsset 与 readAssetBinary；与 readReference 分开是为了审计可区分 */
+  readAsset?: CapabilityMode;
   writeArtifact?: CapabilityMode;
   confirm?: CapabilityMode;
+  /**
+   * 脚本取数（FR-16.1）。**缺省关**——与其余能力相反：
+   * 它会出网，缺省开等于让任何技能默认拥有出站能力。
+   */
+  fetchData?: CapabilityMode;
 }
 /** 入站校验：非法 kind / 缺 id / 缺字段 → undefined（调用方忽略并记 warning） */
 declare function parseBridgeRequest(data: unknown): BridgeRequest | undefined;
@@ -1064,8 +1212,8 @@ declare function normalizeToolError(code: unknown, message: string): {
 };
 //#endregion
 //#region src/sandbox/approval.d.ts
-/** 桥消息对应的三类能力 */
-type BridgeCapability = 'readReference' | 'writeArtifact' | 'confirm';
+/** 桥消息对应的四类能力（readAsset 同时覆盖文本与二进制读取） */
+type BridgeCapability = 'readReference' | 'readAsset' | 'writeArtifact' | 'confirm' | 'fetchData';
 /** allowed 放行；denied 用户拒绝/无法询问；disabled 能力关闭（两者都回 TOOL_UNSUPPORTED，仅消息不同） */
 type ApprovalDecision = 'allowed' | 'denied' | 'disabled';
 /**
@@ -1121,6 +1269,52 @@ interface TodoTraceEvent {
  */
 declare function extractTodoTraceEvents(data: unknown): TodoTraceEvent[];
 //#endregion
+//#region src/tools/linkedDocument.d.ts
+/**
+ * 读取页面上链接指向的文档（分册 22）。
+ *
+ * 与脚本侧的 `fetchData` **分工明确**，两者不得互相蚕食：
+ * - `fetchData`：技能脚本按宿主声明的 sourceId 取**业务数据**，目标宿主写死；
+ * - 本工具：模型读**页面上出现的链接**指向的文档，目标来自感知结果。
+ *
+ * 共同点是准入判定必须共用 `assertRemoteUrlAllowed`（AC-G23），不得各写一套。
+ */
+/** 宿主提供的文档取数实现；不注入即整个工具不注册 @experimental */
+interface LinkedDocumentReader {
+  /**
+   * 宿主页面的 origin，用于同源判定。
+   *
+   * **缺省即一律按跨源处理**（DV-10）：拿不到 origin 时保守到「每次都问」，
+   * 而不是保守到「都不问」。Node 宿主没有页面 origin，因此总是要确认。
+   */
+  readonly origin?: string;
+  read(url: string): Promise<{
+    mimeType: string;
+    bytes: Uint8Array;
+  }>;
+}
+declare const READ_LINKED_DOCUMENT_TOOL_NAME = "read_linked_document";
+/**
+ * 能直接给模型用的 MIME。其余一律拒绝并列出这份清单——
+ * 「尽力而为地猜格式」会让模型收到乱码却以为读成功了。
+ */
+declare const SUPPORTED_DOCUMENT_MIME: {
+  readonly pdf: "application/pdf";
+  readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+};
+/** docx 抽取实现由宿主注入（`DOMParser` 是浏览器 API，Node 没有；备案 D55） */
+type DocxTextExtractor = (bytes: Uint8Array) => Promise<string>;
+/** 引擎侧固定流程（§2.3）用到的错误文案，集中一处便于判据引用 */
+declare const UNSUPPORTED_DOCUMENT_MESSAGE: string;
+/**
+ * 内建工具：读页面链接指向的文档。
+ *
+ * **始终注册**（只要宿主装配了 reader）：docx 与纯文本这条路对所有模型成立。
+ * PDF 目标在模型不支持文档时**取数后拒绝**，而不是入口就拦 ——
+ * 入口拦会误伤 docx，它抽成文本后根本不需要文档能力。
+ */
+declare const READ_LINKED_DOCUMENT_TOOL: ToolDefinition;
+//#endregion
 //#region src/engine/external.d.ts
 /**
  * 外部工具来源（runtime 扩展点，mcp 包实现并插入）。
@@ -1256,6 +1450,27 @@ interface AgentLoopDeps {
   schemaInferer?: SchemaInferer;
   /** 缺省 MemoryArtifactStore */
   artifactStore?: ArtifactStore;
+  /**
+   * 宿主声明的数据源取数入口（分册 16）。注入后脚本上下文才有 `fetchData`。
+   * 策略本体（`DataSourcePolicy`）住在 `@webskill/agent`，它依赖 runtime，
+   * 所以这里只收一个函数，不收策略对象——否则依赖方向反了。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * 页面链接文档的读取实现（分册 22）。不注入即 `read_linked_document` 不注册——
+   * 模型连这个工具的存在都看不到，而不是看得到再被拒。
+   */
+  linkedDocuments?: LinkedDocumentReader;
+  /** docx → 文本；`DOMParser` 是浏览器 API，因此由宿主注入（Node 侧无此能力，备案 D55） */
+  docxExtractor?: DocxTextExtractor;
+  /** 文档读取留痕出口（FR-22.6）；不注入即不留痕，装配方要自己承担这个选择 */
+  documentAudit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
   fs: FileSystemProvider;
   /** name → skillRoot（来自发现结果） */
   skillIndex: Map<string, string>;
@@ -1336,8 +1551,8 @@ declare class AgentLoop {
  */
 declare const DEFAULT_LOOP_LIMITS: {
   readonly maxTurns: 10;
-  readonly totalTimeoutMs: 120000;
-  readonly toolTimeoutMs: 30000;
+  readonly totalTimeoutMs: 3600000;
+  readonly toolTimeoutMs: 600000;
 };
 /**
  * 触顶类失败（`RUN_TIMEOUT` / `RUN_MAX_TURNS_EXCEEDED`）记进 `run.failed`
@@ -1401,6 +1616,26 @@ interface WebSkillRuntimeDeps {
   skillIntegrityGuard?: SkillIntegrityGuard;
   /** F1 技能执行失败上报 port（治理 SkillStatePolicy.toSkillOutcomeReporter 装配；无注入即关闭） */
   skillOutcomeReporter?: SkillOutcomeReporter;
+  /**
+   * 宿主声明的数据源取数入口（分册 16）；注入后脚本上下文才有 `fetchData`。
+   * 通常由 `@webskill/agent` 的 `DataSourcePolicy.fetchData` 绑定过来。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * 读页面链接指向的文档（分册 22）；不注入即 `read_linked_document` 不注册。
+   * 实现住在 `@webskill/browser`（docx 抽取要 `DOMParser`），由宿主装配。
+   */
+  linkedDocuments?: LinkedDocumentReader;
+  /** docx → 文本；不注入即 Word 文档明确报「本环境不支持」（FR-23.8） */
+  docxExtractor?: DocxTextExtractor;
+  /** 文档读取留痕出口（FR-22.6） */
+  documentAudit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
 }
 /**
  * runtime 门面：组合 discovery / router / agent loop / lifecycle
@@ -1493,6 +1728,12 @@ interface RunTraceSummary {
   turnCount: number;
   /** endedAt - startedAt，无 endedAt 或时间戳不可解析时缺省 */
   durationMs?: number;
+  /**
+   * 本 run 各轮 `llm.usage` 事件的 token 聚合（0.10.0 UI-UX5 #47）。
+   * 全 run 无 usage 上报（旧 trace、不支持统计的上游）时缺省——
+   * 消费方据「有没有」决定要不要展示，不显示假数据。
+   */
+  usage?: LlmTokenUsage;
 }
 /** @stable */
 interface RunTraceFilter {
@@ -1566,6 +1807,11 @@ interface RunToolCall {
   args?: string;
   /** 执行耗时 ms */
   durationMs?: number;
+  /**
+   * 开始时刻（trace `tool.started` 的 ts，ISO）。思考卡片与工具卡片按时间
+   * 穿插（UI-UX5 #32）需要一个共同时钟；旧 trace 没有 started 事件时缺省。
+   */
+  startedAt?: string;
   /**
    * failed 时的结构化错误码（如 `TOOL_NOT_ALLOWED`）。
    * 消费方据此区分「被策略拒绝」与「执行出错」，不必解析 message 文案。
@@ -1585,6 +1831,30 @@ interface RunToolCall {
  */
 declare function summarizeToolCalls(run: RuntimeRun): RunToolCall[];
 //#endregion
+//#region src/engine/usage.d.ts
+/**
+ * 一次 run 的大模型用量聚合（0.10.0 UI-UX5 #47）。
+ * 从 trace 事件推导，不落第二份数据：llm.request 计请求次数，llm.usage 计 token。
+ * @stable
+ */
+interface RunUsageSummary {
+  /** llm.request 事件数：本 run 向大模型发送请求的次数（与 RunTraceSummary.turnCount 同源） */
+  llmCalls: number;
+  /**
+   * 各轮 llm.usage 的输入 token 合计。全 run 没有任何 usage 上报时缺省——
+   * 「上游不支持统计」与「恰好为零」必须可区分，消费方缺省时不显示假数据。
+   */
+  inputTokens?: number;
+  /** 各轮 llm.usage 的输出 token 合计；缺省语义同 inputTokens */
+  outputTokens?: number;
+}
+/**
+ * 从 run 的 trace 聚合大模型用量（请求次数 + 输入/输出 token）。
+ * 与 `summarizeToolCalls` 同型：消费方不再各自遍历 trace。
+ * @stable
+ */
+declare function summarizeRunUsage(trace: readonly TraceEvent[]): RunUsageSummary;
+//#endregion
 //#region src/engine/session.d.ts
 declare const SESSION_SCHEMA_VERSION = 1;
 /** `FsSessionStore` 的缺省页长。缺省值属于实现，不属于调用方——否则「下推」只推了一半 */
@@ -1697,4 +1967,4 @@ declare class FsSessionStore<TMessage = unknown> implements SessionStore<TMessag
   delete(id: string): Promise<void>;
 }
 //#endregion
-export { READ_SKILL_FILE_INPUT_SCHEMA as $, scriptToolName as $n, TraceRecorder as $t, FS_SESSION_PAGE_SIZE as A, interruptedToolResult as An, SerializingMemoryStore as At, HookRunnerOptions as B, normalizeToolError as Bn, SkillScriptSchemaSource as Bt, DEFAULT_LOOP_LIMITS as C, extractChartSpec as Cn, SESSION_SCHEMA_VERSION as Ct, ExecuteLifecycleData as D, formatSkillScriptManifest as Dn, SealOptions as Dt, EventBus as E, findUnpairedToolCalls as En, ScriptExecutor as Et, FsSessionStore as F, mergeProfileEntries as Fn, SkillFailureReport as Ft, LifecycleEventInit as G, readProfileEntries as Gn, TodoTraceEvent as Gt, IntegrityVerdict as H, parseUserProfileExport as Hn, SkillSuccessReport as Ht, FullDisclosureRouter as I, networkPolicyLibSource as In, SkillIntegrityGuard as It, LifecycleListener as J, renderUserProfileContext as Jn, ToolResolution as Jt, LifecycleHook as K, readUserProfile as Kn, ToolContent as Kt, GoogleGenAiClient as L, networkUrlHost as Ln, SkillOutcomeReporter as Lt, FsMemoryStore as M, isUnsupportedRunSnapshot as Mn, SessionMeta as Mt, FsRunSnapshotStore as N, listSkillScripts as Nn, SessionRecord as Nt, ExternalSkillProvider as O, fromVercelResult as On, SealRecord as Ot, FsRunTraceStore as P, mergeCatalogEntries as Pn, SessionStore as Pt, ProgressiveRouter as Q, schemaToForm as Qn, TraceEventType as Qt, GoogleGenAiClientConfig as R, normalizeErrorCode as Rn, SkillRouter as Rt, CapabilityMode as S, exportUserProfile as Sn, RuntimeSessionHandle as St, EMPTY_USER_PROFILE as T, extractUiSpecEvents as Tn, ScriptExecutionContext as Tt, InteractLifecycleData as U, partsToText as Un, TerminalLifecycleData as Ut, InstalledSkillManifest as V, parseBridgeRequest as Vn, SkillStateGuard as Vt, LifecycleEvent as W, readBehaviorRecords as Wn, TextualToolContent as Wt, OpenAiCompatibleClient as X, sampleBehaviorRecords as Xn, TraceClock as Xt, NetworkPolicy as Y, resolveToolName as Yn, ToolResult as Yt, OpenAiCompatibleClientConfig as Z, schemaSourceLabel as Zn, TraceEvent as Zt, BridgeCapabilities as _, bridgeError as _n, RunTraceStore as _t, ActivateLifecycleData as a, UnsupportedRunSnapshot as an, toVercelToolSpecs as ar, RouteLifecycleData as at, BridgeResponse as b, createWebSkillApi as bn, RuntimeRun as bt, AgentLoopDeps as c, UserProfileExport as cn, RunResult as ct, ApprovalDecision as d, VercelToolSpec as dn, RunSnapshotStore as dt, USER_PROFILE_EXPORT_VERSION as en, sealToolCallPairs as er, READ_SKILL_FILE_TOOL as et, ApprovalScope as f, WebSkillApi as fn, RunTerminationReason as ft, BehaviorScene as g, applyUserProfileImport as gn, RunTraceMetrics as gt, BehaviorRecordKind as h, appendBehaviorRecords as hn, RunTraceFilter as ht, ASK_USER_TOOL_NAME as i, USER_PROFILE_REFINE_PROMPT as in, toRecordDigests as ir, RefineUserProfileInput as it, FsArtifactStore as j, isNetworkAllowed as jn, SessionListPage as jt, ExternalToolSource as k, fromVercelStreamPart as kn, SealResult as kt, AnthropicClient as l, UserProfileImportDiff as ln, RunSnapshot as lt, BehaviorRecord as m, WebSkillRuntimeDeps as mn, RunTraceFile as mt, ASK_USER_INPUT_SCHEMA as n, USER_PROFILE_NO_INVENTION_RULE as nn, textParts as nr, RUN_SNAPSHOT_SCHEMA_VERSION as nt, AgentLoop as o, UserProfile as on, validateUiSpecEvent as or, RouteResult as ot, BEHAVIOR_RECORDS_KEY as p, WebSkillRuntime as pn, RunToolCall as pt, LifecycleHookContext as q, refineUserProfile as qn, ToolDefinition as qt, ASK_USER_TOOL as r, USER_PROFILE_PROMPT_HEADER as rn, toLlmToolSpec as rr, RUN_TRACE_SCHEMA_VERSION as rt, AgentLoopConfig as s, UserProfileEntry as sn, validateUiSpecNode as sr, RunLimitErrorDetails as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, USER_PROFILE_KEY as tn, summarizeToolCalls as tr, READ_SKILL_FILE_TOOL_NAME as tt, AnthropicClientConfig as u, UserProfileLimits as un, RunSnapshotListEntry as ut, BridgeCapability as v, buildRenderResult as vn, RunTraceSummary as vt, DEFAULT_USER_PROFILE_LIMITS as w, extractTodoTraceEvents as wn, SchemaInferer as wt, CapabilityApproval as x, diffUserProfile as xn, RuntimeSession as xt, BridgeRequest as y, createScriptContext as yn, RuntimePhase as yt, HookRunner as z, normalizeToolContent as zn, SkillScriptDescriptor as zt };
+export { LifecycleHookContext as $, normalizeToolError as $n, SkillSuccessReport as $t, DocxTextExtractor as A, bridgeError as An, RuntimeRun as At, FsRunTraceStore as B, formatSkillScriptManifest as Bn, SealResult as Bt, CapabilityApproval as C, UserProfileLimits as Cn, RunTraceFile as Ct, DEFAULT_MAX_DOCUMENT_BYTES as D, WebSkillRuntimeDeps as Dn, RunTraceSummary as Dt, DEFAULT_MAX_DATA_SOURCE_BYTES as E, WebSkillRuntime as En, RunTraceStore as Et, ExternalToolSource as F, exportUserProfile as Fn, SchemaInferer as Ft, HookRunner as G, isUnsupportedRunSnapshot as Gn, SessionStore as Gt, FullDisclosureRouter as H, fromVercelStreamPart as Hn, SessionListPage as Ht, FS_SESSION_PAGE_SIZE as I, extractChartSpec as In, ScriptExecutionContext as It, IntegrityVerdict as J, mergeProfileEntries as Jn, SkillOutcomeReporter as Jt, HookRunnerOptions as K, listSkillScripts as Kn, SkillFailureReport as Kt, FsArtifactStore as L, extractTodoTraceEvents as Ln, ScriptExecutor as Lt, EventBus as M, createScriptContext as Mn, RuntimeSessionHandle as Mt, ExecuteLifecycleData as N, createWebSkillApi as Nn, SESSION_SCHEMA_VERSION as Nt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as O, appendBehaviorRecords as On, RunUsageSummary as Ot, ExternalSkillProvider as P, diffUserProfile as Pn, SUPPORTED_DOCUMENT_MIME as Pt, LifecycleHook as Q, normalizeToolContent as Qn, SkillStateGuard as Qt, FsMemoryStore as R, extractUiSpecEvents as Rn, SealOptions as Rt, BridgeResponse as S, UserProfileImportDiff as Sn, RunToolCall as St, DEFAULT_LOOP_LIMITS as T, WebSkillApi as Tn, RunTraceMetrics as Tt, GoogleGenAiClient as U, interruptedToolResult as Un, SessionMeta as Ut, FsSessionStore as V, fromVercelResult as Vn, SerializingMemoryStore as Vt, GoogleGenAiClientConfig as W, isNetworkAllowed as Wn, SessionRecord as Wt, LifecycleEvent as X, networkUrlHost as Xn, SkillScriptDescriptor as Xt, InteractLifecycleData as Y, networkPolicyLibSource as Yn, SkillRouter as Yt, LifecycleEventInit as Z, normalizeErrorCode as Zn, SkillScriptSchemaSource as Zt, BehaviorRecordKind as _, USER_PROFILE_REFINE_PROMPT as _n, toLlmToolSpec as _r, RunResult as _t, ASK_USER_TOOL as a, ToolDefinition as an, readUserProfile as ar, ProgressiveRouter as at, BridgeCapability as b, UserProfileEntry as bn, validateUiSpecEvent as br, RunSnapshotStore as bt, AgentLoop as c, TraceClock as cn, resolveToolName as cr, READ_SKILL_FILE_INPUT_SCHEMA as ct, AnthropicClient as d, TraceRecorder as dn, schemaToForm as dr, RUN_SNAPSHOT_SCHEMA_VERSION as dt, TEXT_BUDGETED_CONTENT_TYPES as en, parseBridgeRequest as er, LifecycleListener as et, AnthropicClientConfig as f, UNSUPPORTED_DOCUMENT_MESSAGE as fn, scriptToolName as fr, RUN_TRACE_SCHEMA_VERSION as ft, BehaviorRecord as g, USER_PROFILE_PROMPT_HEADER as gn, textParts as gr, RunLimitErrorDetails as gt, BEHAVIOR_RECORDS_KEY as h, USER_PROFILE_NO_INVENTION_RULE as hn, summarizeToolCalls as hr, RouteResult as ht, ASK_USER_MAX_FIELDS as i, ToolContent as in, readProfileEntries as ir, OpenAiCompatibleClientConfig as it, EMPTY_USER_PROFILE as j, buildRenderResult as jn, RuntimeSession as jt, DEFAULT_USER_PROFILE_LIMITS as k, applyUserProfileImport as kn, RuntimePhase as kt, AgentLoopConfig as l, TraceEvent as ln, sampleBehaviorRecords as lr, READ_SKILL_FILE_TOOL as lt, ApprovalScope as m, USER_PROFILE_KEY as mn, summarizeRunUsage as mr, RouteLifecycleData as mt, ASK_USER_FIELD_TYPES as n, TextualToolContent as nn, partsToText as nr, NetworkPolicy as nt, ASK_USER_TOOL_NAME as o, ToolResolution as on, refineUserProfile as or, READ_LINKED_DOCUMENT_TOOL as ot, ApprovalDecision as p, USER_PROFILE_EXPORT_VERSION as pn, sealToolCallPairs as pr, RefineUserProfileInput as pt, InstalledSkillManifest as q, mergeCatalogEntries as qn, SkillIntegrityGuard as qt, ASK_USER_INPUT_SCHEMA as r, TodoTraceEvent as rn, readBehaviorRecords as rr, OpenAiCompatibleClient as rt, ActivateLifecycleData as s, ToolResult as sn, renderUserProfileContext as sr, READ_LINKED_DOCUMENT_TOOL_NAME as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, TerminalLifecycleData as tn, parseUserProfileExport as tr, LinkedDocumentReader as tt, AgentLoopDeps as u, TraceEventType as un, schemaSourceLabel as ur, READ_SKILL_FILE_TOOL_NAME as ut, BehaviorScene as v, UnsupportedRunSnapshot as vn, toRecordDigests as vr, RunSnapshot as vt, CapabilityMode as w, VercelToolSpec as wn, RunTraceFilter as wt, BridgeRequest as x, UserProfileExport as xn, validateUiSpecNode as xr, RunTerminationReason as xt, BridgeCapabilities as y, UserProfile as yn, toVercelToolSpecs as yr, RunSnapshotListEntry as yt, FsRunSnapshotStore as z, findUnpairedToolCalls as zn, SealRecord as zt };