@webskill/sdk 0.5.0 → 0.7.0

package/dist/{index-Bsqg4ftU.d.ts → index-BwsK9lGk.d.ts}

@@ -1,11 +1,11 @@
-import { I as JsonSchema, T as UiSpecSnapshot, b as UiBridge, c as InteractionResponse, mt as UiSpecNode, r as ChartSpec, s as InteractionRequest, v as RenderBlock, x as UiSpecActionCapability, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
-import { x as ExternalToolSource } from "./index-vBz_FC9w.js";
+import { E as UiSpecSnapshot, R as JsonSchema, S as UiSpecActionCapability, c as InteractionResponse, gt as UiSpecNode, r as ChartSpec, s as InteractionRequest, v as RenderBlock, x as UiBridge, y as RenderResultRequest } from "./types-CcxRLdJG-DCXyw1US.js";
+import { k as ExternalToolSource } from "./index-DkbABR43.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
 //#region ../ui/dist/index.d.ts
 //#region src/model/formModel.d.ts
 interface FormModel {
-  kind: 'ask' | 'confirm' | 'form' | 'select' | 'authorize';
+  kind: 'ask' | 'confirm' | 'form' | 'select' | 'authorize' | 'file-pick';
   title?: string;
   message?: string;
   controls: ControlModel[];
@@ -15,7 +15,7 @@ interface FormModel {
 interface ControlModel {
   name: string;
   label: string;
-  control: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  control: 'text' | 'number' | 'boolean' | 'select' | 'textarea' | 'file';
   required?: boolean;
   description?: string;
   defaultValue?: unknown;
@@ -23,14 +23,17 @@ interface ControlModel {
     label: string;
     value: unknown;
   }>;
+  /** 传给 `input.accept` 的类型列表（仅 file 控件） */
+  accept?: readonly string[];
+  multiple?: boolean;
   /**
-   * 上次填写值（FR-5.9）。与 `defaultValue` 严格分开：渲染器只能把它展示为建议，
+   * 建议值（FR-19.4）。与 `defaultValue` 严格分开：渲染器只能把它展示为建议，
    * 用户主动采纳后才能进控件。
    * @experimental
    */
   suggestion?: {
     value: unknown;
-    ts: number;
+    reason?: string;
   };
 }
 /** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
@@ -67,7 +70,10 @@ declare function applySuggestion(control: ControlModel, container: ParentNode):
 declare function renderMiniMarkdown(text: string, doc: Document): HTMLElement;
 //#endregion
 //#region src/chart/miniChart.d.ts
-/** 固定 8 色循环调色板 */
+/**
+ * 固定 8 色循环调色板。这是**数据编码**（区分序列），不是主题色；
+ * 图表的轴线与文字等“外壳”颜色走 currentColor，跟随宿主容器的主题。
+ */
 declare const CHART_PALETTE: readonly ["#4e79a7", "#f28e2b", "#e15759", "#76b7b2", "#59a14f", "#edc948", "#b07aa1", "#ff9da7"];
 /**
  * ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）

package/dist/{index-vBz_FC9w.d.ts → index-DkbABR43.d.ts}

@@ -1,4 +1,4 @@
-import { $ as SkillDiscovery, B as PageQuery, C as UiSpecEvent, E as UiSurfaceActionRequest, I as JsonSchema, M as DiscoveryResult, P as FileSystemProvider, Q as SkillCatalogEntry, S as UiSpecDrafts, Z as SkillCatalog, _ as MemoryStore, at as SkillManifest, b as UiBridge, d as LlmContentPart, et as SkillDocument, f as LlmMessage, g as LlmToolSpec, gt as ValidationReport, i as FormField, l as LlmClient, m as LlmStreamEvent, mt as UiSpecNode, n as ArtifactStore, o as InteractionPolicy, p as LlmResponse, r as ChartSpec, s as InteractionRequest, t as Artifact, tt as SkillInstallSource, u as LlmCompleteInput, v as RenderBlock, y as RenderResultRequest, yt as WebSkillErrorCode, z as Page } from "./types-D_hoCri8-BnNPiZCi.js";
+import { $ as SkillCatalog, C as UiSpecDrafts, D as UiSurfaceActionRequest, H as PageQuery, I as FileSystemProvider, P as DiscoveryResult, R as JsonSchema, V as Page, _ as MemoryStore, d as LlmContentPart, et as SkillCatalogEntry, f as LlmMessage, g as LlmToolSpec, gt as UiSpecNode, i as FormField, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, nt as SkillDocument, o as InteractionPolicy, p as LlmResponse, r as ChartSpec, rt as SkillInstallSource, s as InteractionRequest, st as SkillManifest, t as Artifact, tt as SkillDiscovery, u as LlmCompleteInput, v as RenderBlock, vt as ValidationReport, w as UiSpecEvent, x as UiBridge, xt as WebSkillErrorCode, y as RenderResultRequest } from "./types-CcxRLdJG-DCXyw1US.js";
 //#region ../runtime/dist/index.d.ts
 //#region src/llm/parts.d.ts
 /** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
@@ -130,16 +130,34 @@ interface ToolDefinition {
   source: 'script' | 'mcp' | 'webmcp' | 'builtin';
   skillName?: string;
 }
+/** 文本型分片（参与 `toolResultMaxBytes` 截断） @experimental */
+type TextualToolContent = {
+  type: 'text' | 'json';
+  text?: string;
+  data?: unknown;
+};
+/**
+ * 工具结果的内容分片（0.6.0 §1.1）。
+ * `image` 分片不参与 `toolResultMaxBytes` 截断——那份预算是给文本的，
+ * base64 图像另有 `maxImageBytes` / `maxImagesPerMessage` 预算，混算会让任一方失效。
+ * `text?: undefined` 是故意的：图像分片没有文本，但让调用方能直接读 `part.text` 而不用先窄化。
+ * @experimental
+ */
+type ToolContent = TextualToolContent | {
+  type: 'image';
+  mimeType: string;
+  data: string;
+  id: string;
+  text?: undefined;
+};
 interface ToolResult {
   ok: boolean;
-  content: Array<{
-    type: 'text' | 'json';
-    text?: string;
-    data?: unknown;
-  }>;
+  content: ToolContent[];
+  /** `data` 供宿主编程处理；`message` 是模型实际会读的那一份，两者都要写全 */
   error?: {
     code: string;
     message: string;
+    data?: Record<string, unknown>;
   };
   artifacts?: Artifact[];
 }
@@ -185,6 +203,9 @@ type ToolResolution = {
   kind: 'not-found';
   code: 'TOOL_NOT_FOUND';
   message: string;
+  data: {
+    availableTools: string[];
+  };
 };
 /**
  * 工具名解析规则（单一实现，Agent 循环使用）：
@@ -193,16 +214,55 @@ type ToolResolution = {
  * 3. `mcp#` 前缀 → TOOL_UNSUPPORTED（WebMCP 阶段实现）
  * 4. 其余 → TOOL_NOT_FOUND
  */
-declare function resolveToolName(name: string, activatedSkills: ReadonlySet<string>): ToolResolution;
+declare function resolveToolName(name: string, activatedSkills: ReadonlySet<string>, activatedTools?: Iterable<string>): ToolResolution;
 /** ToolDefinition → LLM 工具 spec；缺 schema 时用宽松 object 兜底并在描述中标记 */
 declare function toLlmToolSpec(tool: ToolDefinition): LlmToolSpec;
 //#endregion
+//#region src/tools/skillScripts.d.ts
+/**
+ * 技能脚本清单（0.6.0 FR-18.1）。
+ * 同一份数据两处用：`AgentLoop` 激活技能时喂给模型，console 技能详情展示给人。
+ * 两处各写一份的话，模型看到的和作者看到的会慢慢对不上，而这正是「反复猜错脚本名」的来源。
+ * 纯函数（入参是技能根目录下的相对路径清单），因此宿主端不需要 FileSystemProvider 也能复用。
+ */
+/** 入参 schema 的来源；`unknown` 表示尚未加载脚本定义（console 只看目录，不执行脚本） */
+type SkillScriptSchemaSource = 'module-export' | 'sidecar' | 'inferred' | 'unavailable' | 'unknown';
+interface SkillScriptDescriptor {
+  /** 技能根目录下的相对路径，如 `scripts/parse.ts` */
+  path: string;
+  /** 去掉目录与扩展名的脚本名，也是工具名的后半段 */
+  scriptName: string;
+  /** 暴露为工具时的工具名；未暴露时为 undefined */
+  toolName?: string;
+  schemaSource: SkillScriptSchemaSource;
+  /** 未暴露为工具的原因（allowed-tools 排除 / 定义加载失败） */
+  unexposedReason?: string;
+}
+/** 工具名规则：技能**目录名**加双下划线加脚本名，与 frontmatter 的 name 无关 */
+declare function scriptToolName(skillName: string, scriptName: string): string;
+/** 展示用的 schema 来源文案（console 与模型清单共用一套措辞） */
+declare function schemaSourceLabel(source: SkillScriptSchemaSource): string;
+/** allowed-tools 排除的脚本对模型不可见；清单里必须写明原因，否则作者只会看到工具凭空消失 */
+declare const ALLOWED_TOOLS_EXCLUSION_REASON = "excluded by the allowed-tools list in SKILL.md";
+/**
+ * 从技能文件清单中挑出脚本并给出工具名映射。
+ * @param files 技能根目录下的相对路径（如 `scripts/parse.ts`、`SKILL.md`）
+ * @param allowedTools SKILL.md 声明的 allowed-tools；未声明传 undefined（全部暴露）
+ */
+declare function listSkillScripts(skillName: string, files: readonly string[], allowedTools?: readonly string[]): SkillScriptDescriptor[];
+/**
+ * 清单 → 喂给模型的文本（FR-18.1）。
+ * 「authoritative」这句是给模型的信号：以目录为准，别照 SKILL.md 的描述猜文件名。
+ */
+declare function formatSkillScriptManifest(descriptors: readonly SkillScriptDescriptor[]): string;
+//#endregion
 //#region src/tools/normalizeContent.d.ts
 /**
  * 脚本返回值归一到 MCP content 格式：数组沿用（逐项归一），
  * 字符串包装为 text，其他值序列化包装。Node/浏览器执行器共享。
+ * 产出只有文本型分片：脚本侧没有下发图像的通道（图像只来自页面取像）。
  */
-declare function normalizeToolContent(value: unknown): ToolResult['content'];
+declare function normalizeToolContent(value: unknown): TextualToolContent[];
 //#endregion
 //#region src/tools/readSkillFileTool.d.ts
 declare const READ_SKILL_FILE_TOOL_NAME = "read_skill_file";
@@ -365,8 +425,17 @@ interface AgentLoopConfig {
   toolResultMaxBytes?: number;
   /** session paramHistory 保留条数上限（默认 50，超出裁最旧） */
   paramHistoryLimit?: number;
-  /** 跨会话表单填写值的字段数上限（默认 100，超出裁最旧） */
-  formValueLimit?: number;
+  /**
+   * 模型不支持原生工具调用时置 true（0.6.0 FR-14.3）：不注入任何工具定义、
+   * 不收集外部来源的系统提示，并换成精简提示。不这么做的话，不会调工具的模型
+   * 会照着提示词里的语法“演”一个工具调用出来。
+   */
+  toolCallingDisabled?: boolean;
+  /**
+   * 单次 run 内允许的「调用不存在的工具」次数（默认 2，超出即终止 run，0.6.0 FR-18.3）。
+   * 不设上限的话，模型会一路猜到 maxTurns 用完，用户等到最后拿到的还是一句失败。
+   */
+  maxUnknownToolRetries?: number;
 }
 /** 技能状态拦截 port（治理装配；无注入默认全放行） */
 interface SkillStateGuard {
@@ -403,6 +472,11 @@ interface SkillFailureReport {
   /** 英文失败说明；上报方须能据此向用户解释，不要传空串 */
   message: string;
 }
+/** 技能脚本执行成功的上报负载 */
+interface SkillSuccessReport {
+  skillName: string;
+  runId: string;
+}
 /**
  * 技能执行结果上报 port（治理 `SkillStatePolicy.toSkillOutcomeReporter` 装配；**不注入即关闭**）。
  *
@@ -419,12 +493,19 @@ interface SkillFailureReport {
  */
 interface SkillOutcomeReporter {
   onSkillFailed?(report: SkillFailureReport): Promise<void>;
+  /**
+   * 成功上报（0.7.0 新增，可选；裁决 D-5）。没有它，失败计数只能单调递增，
+   * 「连续三次失败」实际退化成「累计三次」——一个长期正常的技能迟早会被隔离。
+   */
+  onSkillSucceeded?(report: SkillSuccessReport): Promise<void>;
 }
 interface RuntimeSession {
   id: string;
   createdAt: string;
 }
-type RunTerminationReason = 'final-answer' | 'max-turns' | 'timeout' | 'llm-error' | 'interaction-timeout' | 'user-cancelled' | 'hook-error';
+type RunTerminationReason = 'final-answer' | 'max-turns' | 'timeout' | 'llm-error' | 'interaction-timeout' | 'user-cancelled' | 'hook-error' |
+/** 反复调用不存在的工具，提前止损（0.6.0 FR-18.3） */
+'tool-resolution-exhausted';
 interface RuntimeRun {
   id: string;
   sessionId: string;
@@ -448,7 +529,7 @@ interface RunResult {
 }
 /** createSession 返回的会话句柄：跨 run 延续消息历史 */
 interface RuntimeSessionHandle extends RuntimeSession {
-  run(prompt: string): Promise<RunResult>;
+  run(prompt: string | readonly LlmContentPart[]): Promise<RunResult>;
 }
 //#endregion
 //#region src/interaction/renderResult.d.ts
@@ -460,6 +541,7 @@ declare function extractChartSpec(data: unknown): ChartSpec | undefined;
 /**
  * 默认的结果渲染构造：run 内收集的 renderBlocks（chart 等）在前，
  * LLM 最终输出 → markdown block，run.artifacts → file blocks 在后；summary 取 terminationReason。
+ * 注入 output block 时一并记下它的下标（S7），供消费方按来源去重。
  */
 declare function buildRenderResult(run: RuntimeRun, output: string, renderBlocks?: RenderBlock[]): RenderResultRequest;
 //#endregion
@@ -476,11 +558,8 @@ declare function extractUiSpecEvents(data: unknown): UiSpecEvent[];
  * JsonSchema → 表单模型：按 properties 生成字段，required 标记必填；
  * providedArgs 已有的值作为 defaultValue 预填（表单只为补齐缺失项服务）。
  * type 映射：string→text、number/integer→number、boolean→boolean、enum→select、其余→textarea。
- * 传入 skillName 时给每个字段带上跨会话稳定的 `fieldKey`（FR-5.6）。
  */
-declare function schemaToForm(schema: JsonSchema, providedArgs?: Record<string, unknown>, options?: {
-  skillName?: string;
-}): FormField[];
+declare function schemaToForm(schema: JsonSchema, providedArgs?: Record<string, unknown>): FormField[];
 //#endregion
 //#region src/facade/types.d.ts
 /**
@@ -612,35 +691,198 @@ declare class SerializingMemoryStore implements MemoryStore {
   transaction<T>(scope: string, fn: (inner: MemoryStore) => Promise<T>): Promise<T>;
 }
 //#endregion
-//#region src/memory/formValues.d.ts
-/** 跨会话表单填写值在 `user:{userId}` scope 下的 key（FR-5.7） @experimental */
-declare const FORM_VALUES_KEY = "formValues";
+//#region src/profile/types.d.ts
+/**
+ * 用户画像（0.6.0 需求 19）。行为记录是原始事实，画像是模型提炼出的结论——
+ * 只有后者会进入后续对话的上下文（FR-19.3）。
+ */
+/** @experimental */
+type BehaviorRecordKind = 'question' | 'choice' | 'text-input' | 'stated-preference';
+/**
+ * 记录发生时的场景。没有场景的记录对提炼没有价值：
+ * 「选了 A」不带候选集与字段语义，模型无从判断这代表什么偏好（FR-19.2）。
+ * @experimental
+ */
+interface BehaviorScene {
+  readonly sessionId: string;
+  readonly skillName?: string;
+  readonly interactionId?: string;
+  readonly fieldName?: string;
+  /** 字段语义（label / description），供提炼时理解字段含义 */
+  readonly fieldSemantics?: string;
+  /** 下拉候选集：理解「用户在什么范围里选了什么」 */
+  readonly options?: readonly string[];
+}
+/** @experimental */
+interface BehaviorRecord {
+  readonly id: string;
+  readonly kind: BehaviorRecordKind;
+  /** epoch ms */
+  readonly at: number;
+  readonly scene: BehaviorScene;
+  readonly value: string;
+  /** 用户是否显式确认过（采样维度之一） */
+  readonly confirmed?: boolean;
+}
+/** 一条自然语言结论。条目化而不是整段文本，才谈得上逐条查看与删除（FR-19.3） @experimental */
+interface UserProfileEntry {
+  readonly id: string;
+  readonly text: string;
+  readonly confidence: 'high' | 'low';
+  /** epoch ms */
+  readonly updatedAt: number;
+  readonly sourceKinds: readonly BehaviorRecordKind[];
+}
+/** @experimental */
+interface UserProfile {
+  readonly version: 1;
+  readonly entries: readonly UserProfileEntry[];
+  /** epoch ms；从未提炼过时为 0 */
+  readonly refinedAt: number;
+}
+/** @experimental */
+interface UserProfileLimits {
+  /** 行为记录容量上限，超出淘汰最旧 */
+  recordLimit: number;
+  /** 单条 value 的字符上限（用户输入需保留语义，故远大于感知截断） */
+  valueMaxChars: number;
+  /** 送入一次提炼的记录条数上限 */
+  sampleLimit: number;
+  /** 画像注入系统提示的字节上限 */
+  injectMaxBytes: number;
+  /** 画像条目数上限，超出按 updatedAt 淘汰 */
+  entryLimit: number;
+}
+/** @experimental */
+declare const DEFAULT_USER_PROFILE_LIMITS: UserProfileLimits;
+/** @experimental */
+declare const EMPTY_USER_PROFILE: UserProfile;
+//#endregion
+//#region src/profile/records.d.ts
+/** `user:{id}` scope 下的行为记录 key @experimental */
+declare const BEHAVIOR_RECORDS_KEY = "behaviorRecords";
+/** `user:{id}` scope 下的画像 key @experimental */
+declare const USER_PROFILE_KEY = "userProfile";
+/** 存储里的形状不受控（宿主可能手改文件），逐条筛而不是整体信任 @experimental */
+declare function readBehaviorRecords(raw: unknown): BehaviorRecord[];
 /**
- * 跨会话稳定的字段标识（FR-5.6）。必须带技能名：
- * 只有字段名时，两个技能各自的 `email` 会互相串号。
+ * 追加并按容量淘汰最旧（FR-19.2）。`value` 同时截断：
+ * 一条被粘贴进来的长文本能把整个 JSON 撑爆，而提炼只需要语义。
  * @experimental
  */
-declare function formFieldKey(skillName: string, fieldName: string): string;
-/** 某个字段最近一次的填写值 @experimental */
-interface FormValueRecord {
-  value: unknown;
-  /** 写入时刻（epoch ms）；超上限裁剪时按它排序 */
-  ts: number;
-}
-/** fieldKey → 最近一次填写值（**只留最近一次**，不是历史序列） @experimental */
-type FormValueMap = Record<string, FormValueRecord>;
-/** memory 里的原始值形状不受控（宿主可能手改文件），逐条过滤而不是整体信任 @experimental */
-declare function readFormValues(raw: unknown): FormValueMap;
-/** 合并本次提交并按上限裁剪最旧（FR-5.12） @experimental */
-declare function putFormValues(current: FormValueMap, updates: FormValueMap, limit: number): FormValueMap;
-/** 清除单个字段；不传 fieldKey 即全部清除（FR-5.11） @experimental */
-declare function clearFormValues(current: FormValueMap, fieldKey?: string): FormValueMap;
+declare function appendBehaviorRecords(current: readonly BehaviorRecord[], incoming: readonly BehaviorRecord[], limits?: UserProfileLimits): BehaviorRecord[];
+/** @experimental */
+declare function readUserProfile(raw: unknown): UserProfile;
+/** @experimental */
+declare function readProfileEntries(raw: unknown): UserProfileEntry[];
+/**
+ * 合并提炼结果：同 id 更新，新 id 追加，超上限按 `updatedAt` 淘汰最旧（设计 09 §1.4）。
+ * @experimental
+ */
+declare function mergeProfileEntries(current: UserProfile, incoming: readonly UserProfileEntry[], options: {
+  now: number;
+  limits?: UserProfileLimits;
+}): UserProfile;
+/**
+ * 提炼采样（FR-19.3）：最近的 + 高频的 + 被用户显式确认过的，去重后截到上限。
+ * 三个维度缺一不可——只取最近会让长期偏好被一次突发淹没，只取高频则学不到新变化。
+ * @experimental
+ */
+declare function sampleBehaviorRecords(records: readonly BehaviorRecord[], limits?: UserProfileLimits): BehaviorRecord[];
+//#endregion
+//#region src/profile/refine.d.ts
+/**
+ * 提炼提示词。要求返回结论列表而不是散文：条目化是「可见、可编辑、可删除」的前提（FR-19.3）。
+ * `id` 由模型给出稳定 slug，才能在下一次提炼时更新同一条而不是无限追加。
+ */
+declare const USER_PROFILE_REFINE_PROMPT = "You summarize what a single user is like, based on records of what they did in a chat application.\n\nReturn ONLY a JSON object with this shape, and nothing else:\n\n{\n  \"entries\": [\n    { \"id\": \"slug-case-stable-id\", \"text\": \"One sentence about the user.\", \"confidence\": \"high\" | \"low\" }\n  ]\n}\n\nRules:\n- Each entry is one durable, reusable fact or preference about the user — how they like answers, what they work on, values they keep entering, languages they use.\n- Reuse the same \"id\" across runs for the same conclusion so it can be updated instead of duplicated. Use lowercase words joined by hyphens.\n- Use \"high\" only when several records agree. A single record is \"low\".\n- Do not restate individual records. Do not include secrets, credentials, or full personal identifiers.\n- Do not invent anything the records do not support. If the records say nothing useful, return {\"entries\": []}.";
+/** @experimental */
+interface RefineUserProfileInput {
+  llm: LlmClient;
+  records: readonly BehaviorRecord[];
+  /** 当前画像；提炼结果与它合并（同 id 更新） */
+  profile?: UserProfile;
+  model?: string;
+  limits?: UserProfileLimits;
+  /** epoch ms 时钟，默认 `Date.now` */
+  now?: () => number;
+  signal?: AbortSignal;
+}
+/** 送模型的记录形态：只保留提炼用得上的字段，会话 id 之类的内部标识不外发 */
+interface RecordDigest {
+  kind: string;
+  at: string;
+  value: string;
+  skill?: string;
+  field?: string;
+  meaning?: string;
+  options?: readonly string[];
+  confirmed?: boolean;
+}
+/** 采样后的记录 → 送模型的摘要。导出供测试与宿主复核实际请求内容（AC-19.6） @experimental */
+declare function toRecordDigests(records: readonly BehaviorRecord[]): RecordDigest[];
 /**
- * 宿主侧的清除入口（FR-5.11）：设置面板的「清除填写历史」直接调它，
- * 不必自己知道 scope 与 key 的约定。
+ * 一次提炼（FR-19.3）。调用方负责持久化返回值；本函数不碰存储，
+ * 也不吞异常——「失败不影响会话结束」由调用点的 fire-and-forget 保证，
+ * 在这里吞掉会让手动提炼入口无法报错。
  * @experimental
  */
-declare function clearStoredFormValues(memory: MemoryStore, userId: string, fieldKey?: string): Promise<void>;
+declare function refineUserProfile(input: RefineUserProfileInput): Promise<UserProfile>;
+//#endregion
+//#region src/profile/inject.d.ts
+/** 注入段的标题。宿主/测试要判断「有没有注入画像」时对它取子串，不要自己再拼一份 @experimental */
+declare const USER_PROFILE_PROMPT_HEADER = "## About this user (inferred from past behavior; may be outdated)";
+/**
+ * 无画像时也要下发的约束（AC-19.11）：没有依据就把字段留空，
+ * 不写这一句时模型会把「建议值」当成必填项去编。
+ * @experimental
+ */
+declare const USER_PROFILE_NO_INVENTION_RULE = "Only offer a suggested value for a question when the profile above actually supports it. With no relevant profile entry, omit the suggestion and leave the field empty; never invent one.";
+/**
+ * 画像 → 系统提示片段，按 confidence + updatedAt 优先级排序后逐条累加，
+ * 超出字节上限的部分丢弃并标注（FR-19.4 / AC-19.9）。
+ * 空画像返回空串：只有标题的空段落白占 token，还会诱导模型编造。
+ * @experimental
+ */
+declare function renderUserProfileContext(profile?: UserProfile, maxBytes?: number): string;
+//#endregion
+//#region src/profile/transfer.d.ts
+/** 导出文件的版本；导入时逐字校验，不做向前兼容猜测 @experimental */
+declare const USER_PROFILE_EXPORT_VERSION = 1;
+/**
+ * 导出物（FR-19.7）。**结构上只有 entries**：原始行为记录与凭据没有容身之处，
+ * 这是「导出不泄露」的类型层保证，运行时另有一道断言兜底。
+ * @experimental
+ */
+interface UserProfileExport {
+  readonly kind: 'webskill.user-profile';
+  readonly version: typeof USER_PROFILE_EXPORT_VERSION;
+  /** 来源标识（站点 origin），用于导入时说明这份画像来自哪里 */
+  readonly origin: string;
+  /** epoch ms */
+  readonly exportedAt: number;
+  readonly entries: readonly UserProfileEntry[];
+}
+/**
+ * 导出画像（FR-19.7）。`excludeIds` 来自导出前的审阅界面：用户勾掉的条目不进文件。
+ * @experimental
+ */
+declare function exportUserProfile(profile: UserProfile, options: {
+  origin: string;
+  excludeIds?: readonly string[];
+  now?: () => number;
+}): UserProfileExport;
+/** 解析并校验导入内容（FR-19.7）。含凭据是**拒绝**而不是忽略 @experimental */
+declare function parseUserProfileExport(raw: unknown): UserProfileExport;
+/** 导入前给用户看的差异（FR-19.7）：新增哪些、覆盖哪些 @experimental */
+declare function diffUserProfile(current: UserProfile, incoming: UserProfileExport): {
+  added: readonly UserProfileEntry[];
+  updated: readonly UserProfileEntry[];
+};
+/** 确认后落库：同 id 覆盖，其余保留；不触碰模型配置与凭据 @experimental */
+declare function applyUserProfileImport(current: UserProfile, incoming: UserProfileExport, options?: {
+  now?: () => number;
+}): UserProfile;
 //#endregion
 //#region src/artifacts/fsArtifactStore.d.ts
 /**
@@ -974,12 +1216,13 @@ interface AgentLoopDeps {
     userId: string;
   };
   /**
-   * 跨会话表单自动填充（FR-5.7）；**不注入即关闭**，关闭时不查也不写。
-   * 与 `longTerm` 分开：后者存的是技能使用统计，本项存的是用户亲手填的内容，
-   * 两者的开关语义不同（AC-5.7）。
+   * 用户画像（FR-19.2/19.4）；**不注入即关闭**，关闭时既不记录也不注入。
+   * 与 `longTerm` 分开：后者存的是技能使用统计，本项存的是用户行为与对其的推断，
+   * 两者的隐私含义不同（FR-19.6）。
    */
-  formAutofill?: {
+  userProfile?: {
     userId: string;
+    limits?: UserProfileLimits;
   };
   /** 外部工具来源（mcp 插件等）；specs 在 run 开始时并入每轮 tools */
   externalTools?: ExternalToolSource[];
@@ -1007,12 +1250,12 @@ declare class AgentLoop {
   /**
    * 取消进行中的 run：触发该 run 的 AbortController（与 totalTimeout 硬期限同一通道），
    * run 以 cancelled（RUN_CANCELLED）终止；未找到（已终态或不属于本实例）返回 false。
-   * 取消在下一个中断点生效（LLM complete/stream 调用；交互等待不强制中断）。
+   * 取消在下一个中断点生效；LLM 调用与交互等待都监听同一个 signal，因此等表单时也能立即停。
    */
   cancel(runId: string): boolean;
   run(input: {
     sessionId: string;
-    userPrompt: string;
+    userPrompt: string | readonly LlmContentPart[];
     route: RouteResult;
     runId?: string;
     /** 多会话历史延续：插入 system 与本轮 user 之间（不含 system 消息） */
@@ -1025,6 +1268,33 @@ declare class AgentLoop {
   resume(snapshot: RunSnapshot): Promise<RunResult>;
 }
 //#endregion
+//#region src/engine/limits.d.ts
+/**
+ * Agent loop 的运行上限默认值。**全仓唯一来源**（S8）。
+ *
+ * 在 0.7.0 之前这三个数字在 `AgentLoop` 的构造与 ui-kit 的 `defaultRuntimeConfig()`
+ * 里各写了一遍。两份值今天恰好相等，所以不出事；一旦其中一处被改，
+ * 「恢复默认值」会恢复到 agent loop 根本不用的值——验收绿、行为错。
+ * @stable
+ */
+declare const DEFAULT_LOOP_LIMITS: {
+  readonly maxTurns: 10;
+  readonly totalTimeoutMs: 120000;
+  readonly toolTimeoutMs: 30000;
+};
+/**
+ * 触顶类失败（`RUN_TIMEOUT` / `RUN_MAX_TURNS_EXCEEDED`）记进 `run.failed`
+ * 轨迹事件 `data` 的结构化细节：程序化消费方据此判断是哪个上限、当时的生效值，
+ * 而不必去解析英文 message。
+ * @stable
+ */
+interface RunLimitErrorDetails {
+  /** 触顶的上限字段名，与 `RuntimeLoopConfig` 的键一致 */
+  limit: 'totalTimeoutMs' | 'toolTimeoutMs' | 'maxTurns';
+  /** 触顶时该上限的生效值 */
+  value: number;
+}
+//#endregion
 //#region src/engine/runtime.d.ts
 interface WebSkillRuntimeDeps {
   fs: FileSystemProvider;
@@ -1050,9 +1320,10 @@ interface WebSkillRuntimeDeps {
     enabled: true;
     userId: string;
   };
-  /** 跨会话表单自动填充（FR-5.7）；不注入即关闭，关闭时不查也不写 */
-  formAutofill?: {
+  /** 用户画像（FR-19.2/19.4）；不注入即关闭，关闭时既不记录也不注入 */
+  userProfile?: {
     userId: string;
+    limits?: UserProfileLimits;
   };
   /** 外部工具来源（mcp 插件等） */
   externalTools?: ExternalToolSource[];
@@ -1102,9 +1373,10 @@ declare class WebSkillRuntime {
     maxHistoryMessages?: number;
   }): RuntimeSessionHandle;
   discover(): Promise<DiscoveryResult>;
-  run(userPrompt: string, options?: {
+  run(userPrompt: string | readonly LlmContentPart[], options?: {
     sessionId?: string;
     history?: LlmMessage[];
+    skillName?: string;
   }): Promise<RunResult>;
   /** D3：列出 interrupted run（供 UI 展示"未完成任务"）；版本不受支持的项带 unsupported 标记 */
   listInterruptedRuns(): Promise<RunSnapshotListEntry[]>;
@@ -1213,8 +1485,10 @@ declare class FsRunTraceStore implements RunTraceStore {
   constructor(deps: {
     root: string;
     fs: FileSystemProvider;
-    /** 落盘失败的降级处理；默认 console.warn，保持「写失败不阻断对话」的产品语义 */
+    /** 正文落盘失败的降级处理；默认 console.warn，保持「写失败不阻断对话」的产品语义 */
     onError?: (error: unknown, run: RuntimeRun) => void;
+    /** 索引追加失败的降级处理；与 onError 分开是因为它可自愈（FR-21.7） */
+    onIndexError?: (error: unknown, run: RuntimeRun) => void;
   });
   put(run: RuntimeRun): Promise<void>;
   get(runId: string): Promise<RunTraceFile>;
@@ -1277,6 +1551,16 @@ interface SessionRecord<TMessage = unknown> extends SessionMeta {
   schemaVersion: number;
   messages: TMessage[];
 }
+/**
+ * `list()` 的返回页。空列表有两种成因，UI 必须能分辨：
+ * 真的没有会话，和根目录压根不存在（多半是 chatRoot 配错）。
+ */
+interface SessionListPage extends Page<SessionMeta> {
+  /** `'ok'` = 正常列举；`'missing-root'` = 根目录不存在 */
+  readonly source: 'ok' | 'missing-root';
+  /** 解析失败被跳过的文件名，供 UI 提示与定位 */
+  readonly skipped: readonly string[];
+}
 /**
  * 会话持久化端口。消息载荷对 runtime 不透明——`ChatMessage` 是 chatbot 的 UI 类型，
  * runtime 不能认识它，所以泛型默认 `unknown`（只读消费方直接用默认参数即可）。
@@ -1288,7 +1572,7 @@ interface SessionStore<TMessage = unknown> {
    */
   list(options?: {
     includeArchived?: boolean;
-  } & PageQuery): Promise<Page<SessionMeta>>;
+  } & PageQuery): Promise<SessionListPage>;
   get(id: string): Promise<SessionRecord<TMessage> | undefined>;
   /**
    * 消息分页读。与 `list()` 同方向：无游标时给**最后**一页（最新的 `limit` 条），
@@ -1325,7 +1609,7 @@ declare class FsSessionStore<TMessage = unknown> implements SessionStore<TMessag
   });
   list(options?: {
     includeArchived?: boolean;
-  } & PageQuery): Promise<Page<SessionMeta>>;
+  } & PageQuery): Promise<SessionListPage>;
   /**
    * 整文件读后切片。磁盘 I/O 复杂度没有改善（备案 D25），
    * 但**跨出端口的记录数**已是常量——这正是分页对上层的意义。
@@ -1345,4 +1629,4 @@ declare class FsSessionStore<TMessage = unknown> implements SessionStore<TMessag
   delete(id: string): Promise<void>;
 }
 //#endregion
-export { RouteLifecycleData as $, fromVercelResult as $t, FsSessionStore as A, TodoTraceEvent as At, LifecycleEventInit as B, WebSkillApi as Bt, FS_SESSION_PAGE_SIZE as C, SessionStore as Ct, FsMemoryStore as D, SkillRouter as Dt, FsArtifactStore as E, SkillOutcomeReporter as Et, HookRunnerOptions as F, TraceEvent as Ft, OpenAiCompatibleClient as G, clearFormValues as Gt, LifecycleHookContext as H, WebSkillRuntimeDeps as Ht, InstalledSkillManifest as I, TraceEventType as It, READ_SKILL_FILE_INPUT_SCHEMA as J, createWebSkillApi as Jt, OpenAiCompatibleClientConfig as K, clearStoredFormValues as Kt, IntegrityVerdict as L, TraceRecorder as Lt, GoogleGenAiClient as M, ToolResolution as Mt, GoogleGenAiClientConfig as N, ToolResult as Nt, FsRunSnapshotStore as O, SkillStateGuard as Ot, HookRunner as P, TraceClock as Pt, RUN_TRACE_SCHEMA_VERSION as Q, formFieldKey as Qt, InteractLifecycleData as R, UnsupportedRunSnapshot as Rt, FORM_VALUES_KEY as S, SessionRecord as St, FormValueRecord as T, SkillIntegrityGuard as Tt, LifecycleListener as U, bridgeError as Ut, LifecycleHook as V, WebSkillRuntime as Vt, NetworkPolicy as W, buildRenderResult as Wt, READ_SKILL_FILE_TOOL_NAME as X, extractTodoTraceEvents as Xt, READ_SKILL_FILE_TOOL as Y, extractChartSpec as Yt, RUN_SNAPSHOT_SCHEMA_VERSION as Z, extractUiSpecEvents as Zt, CapabilityMode as _, toLlmToolSpec as _n, SchemaInferer as _t, AgentLoop as a, networkUrlHost as an, RunTerminationReason as at, ExternalSkillProvider as b, validateUiSpecNode as bn, SerializingMemoryStore as bt, AnthropicClient as c, normalizeToolError as cn, RunTraceFilter as ct, ApprovalScope as d, putFormValues as dn, RunTraceSummary as dt, fromVercelStreamPart as en, RouteResult as et, BridgeCapabilities as f, readFormValues as fn, RuntimePhase as ft, CapabilityApproval as g, textParts as gn, SESSION_SCHEMA_VERSION as gt, BridgeResponse as h, summarizeToolCalls as hn, RuntimeSessionHandle as ht, ActivateLifecycleData as i, networkPolicyLibSource as in, RunSnapshotStore as it, FullDisclosureRouter as j, ToolDefinition as jt, FsRunTraceStore as k, TerminalLifecycleData as kt, AnthropicClientConfig as l, parseBridgeRequest as ln, RunTraceMetrics as lt, BridgeRequest as m, schemaToForm as mn, RuntimeSession as mt, ASK_USER_TOOL as n, isUnsupportedRunSnapshot as nn, RunSnapshot as nt, AgentLoopConfig as o, normalizeErrorCode as on, RunToolCall as ot, BridgeCapability as p, resolveToolName as pn, RuntimeRun as pt, ProgressiveRouter as q, createScriptContext as qt, ASK_USER_TOOL_NAME as r, mergeCatalogEntries as rn, RunSnapshotListEntry as rt, AgentLoopDeps as s, normalizeToolContent as sn, RunTraceFile as st, ASK_USER_INPUT_SCHEMA as t, isNetworkAllowed as tn, RunResult as tt, ApprovalDecision as u, partsToText as un, RunTraceStore as ut, EventBus as v, toVercelToolSpecs as vn, ScriptExecutionContext as vt, FormValueMap as w, SkillFailureReport as wt, ExternalToolSource as x, SessionMeta as xt, ExecuteLifecycleData as y, validateUiSpecEvent as yn, ScriptExecutor as yt, LifecycleEvent as z, VercelToolSpec as zt };
+export { READ_SKILL_FILE_INPUT_SCHEMA as $, validateUiSpecEvent as $n, USER_PROFILE_NO_INVENTION_RULE as $t, FS_SESSION_PAGE_SIZE as A, networkPolicyLibSource as An, SessionRecord as At, HookRunnerOptions as B, readUserProfile as Bn, TerminalLifecycleData as Bt, DEFAULT_LOOP_LIMITS as C, fromVercelResult as Cn, SESSION_SCHEMA_VERSION as Ct, ExecuteLifecycleData as D, listSkillScripts as Dn, SerializingMemoryStore as Dt, EventBus as E, isUnsupportedRunSnapshot as En, ScriptExecutor as Et, FsSessionStore as F, parseBridgeRequest as Fn, SkillRouter as Ft, LifecycleEventInit as G, schemaSourceLabel as Gn, ToolResolution as Gt, IntegrityVerdict as H, renderUserProfileContext as Hn, TodoTraceEvent as Ht, FullDisclosureRouter as I, parseUserProfileExport as In, SkillScriptDescriptor as It, LifecycleListener as J, summarizeToolCalls as Jn, TraceEvent as Jt, LifecycleHook as K, schemaToForm as Kn, ToolResult as Kt, GoogleGenAiClient as L, partsToText as Ln, SkillScriptSchemaSource as Lt, FsMemoryStore as M, normalizeErrorCode as Mn, SkillFailureReport as Mt, FsRunSnapshotStore as N, normalizeToolContent as Nn, SkillIntegrityGuard as Nt, ExternalSkillProvider as O, mergeCatalogEntries as On, SessionListPage as Ot, FsRunTraceStore as P, normalizeToolError as Pn, SkillOutcomeReporter as Pt, ProgressiveRouter as Q, toVercelToolSpecs as Qn, USER_PROFILE_KEY as Qt, GoogleGenAiClientConfig as R, readBehaviorRecords as Rn, SkillStateGuard as Rt, CapabilityMode as S, formatSkillScriptManifest as Sn, RuntimeSessionHandle as St, EMPTY_USER_PROFILE as T, isNetworkAllowed as Tn, ScriptExecutionContext as Tt, InteractLifecycleData as U, resolveToolName as Un, ToolContent as Ut, InstalledSkillManifest as V, refineUserProfile as Vn, TextualToolContent as Vt, LifecycleEvent as W, sampleBehaviorRecords as Wn, ToolDefinition as Wt, OpenAiCompatibleClient as X, toLlmToolSpec as Xn, TraceRecorder as Xt, NetworkPolicy as Y, textParts as Yn, TraceEventType as Yt, OpenAiCompatibleClientConfig as Z, toRecordDigests as Zn, USER_PROFILE_EXPORT_VERSION as Zt, BridgeCapabilities as _, diffUserProfile as _n, RunTraceStore as _t, ActivateLifecycleData as a, UserProfileExport as an, RouteLifecycleData as at, BridgeResponse as b, extractTodoTraceEvents as bn, RuntimeRun as bt, AgentLoopDeps as c, WebSkillApi as cn, RunResult as ct, ApprovalDecision as d, appendBehaviorRecords as dn, RunSnapshotStore as dt, USER_PROFILE_PROMPT_HEADER as en, validateUiSpecNode as er, READ_SKILL_FILE_TOOL as et, ApprovalScope as f, applyUserProfileImport as fn, RunTerminationReason as ft, BehaviorScene as g, createWebSkillApi as gn, RunTraceMetrics as gt, BehaviorRecordKind as h, createScriptContext as hn, RunTraceFilter as ht, ASK_USER_TOOL_NAME as i, UserProfileEntry as in, RefineUserProfileInput as it, FsArtifactStore as j, networkUrlHost as jn, SessionStore as jt, ExternalToolSource as k, mergeProfileEntries as kn, SessionMeta as kt, AnthropicClient as l, WebSkillRuntime as ln, RunSnapshot as lt, BehaviorRecord as m, buildRenderResult as mn, RunTraceFile as mt, ASK_USER_INPUT_SCHEMA as n, UnsupportedRunSnapshot as nn, RUN_SNAPSHOT_SCHEMA_VERSION as nt, AgentLoop as o, UserProfileLimits as on, RouteResult as ot, BEHAVIOR_RECORDS_KEY as p, bridgeError as pn, RunToolCall as pt, LifecycleHookContext as q, scriptToolName as qn, TraceClock as qt, ASK_USER_TOOL as r, UserProfile as rn, RUN_TRACE_SCHEMA_VERSION as rt, AgentLoopConfig as s, VercelToolSpec as sn, RunLimitErrorDetails as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, USER_PROFILE_REFINE_PROMPT as tn, READ_SKILL_FILE_TOOL_NAME as tt, AnthropicClientConfig as u, WebSkillRuntimeDeps as un, RunSnapshotListEntry as ut, BridgeCapability as v, exportUserProfile as vn, RunTraceSummary as vt, DEFAULT_USER_PROFILE_LIMITS as w, fromVercelStreamPart as wn, SchemaInferer as wt, CapabilityApproval as x, extractUiSpecEvents as xn, RuntimeSession as xt, BridgeRequest as y, extractChartSpec as yn, RuntimePhase as yt, HookRunner as z, readProfileEntries as zn, SkillSuccessReport as zt };