@webskill/chatbot 0.22.0 → 0.24.0

package/README.md

@@ -132,6 +132,121 @@ newest-first. This is a behavioural contract that the type system cannot check:
 a store that still returns ascending order will render the oldest session at the
 top.
 
+## Which session opens on mount
+
+Mounting `<Chatbot>` (opening the web dialog, opening the extension side panel)
+lands on a **new conversation**, not on an old one:
+
+- If the newest **non-archived** session on the first page is empty
+  (`ChatSessionMeta.messageCount === 0`, for example one made with **New chat**),
+  that session opens — no second empty session is created.
+- Otherwise nothing is selected: the message area is empty and the list shows a
+  "new chat" placeholder. **Nothing is written to storage** until the first
+  message is sent, so opening and closing the panel repeatedly never piles up
+  empty sessions.
+- A missing `messageCount` (a custom list that does not provide it) counts as
+  non-empty.
+- If the engine is rebuilt while the component stays mounted (a config prop
+  changes identity), the conversation you have open stays open.
+- Resuming an interrupted run from the banner first switches to the session the
+  run belongs to. If you render `InterruptedBanner` yourself, pass
+  `onBeforeResume` to do the same.
+
+## Host components
+
+A **host component** is a capability your app registers and the model triggers
+as a tool — for example "send this summary to WeChat user alice". Each component
+brings its own confirmation card, credential form and result card. This is the
+only way a host can add its own tool _and_ get an in-conversation form, a
+confirmation with "don't ask again", and a persisted result — tools behind an
+in-process MCP endpoint get none of those.
+
+This surface is `@experimental`: `createHttpMessageComponent` and the
+`ChatComponent*` types are exported from `@webskill/chatbot`, but their shape may
+still change, so they are not shown with an `import` line like the stable API.
+
+```ts
+// createHttpMessageComponent comes from '@webskill/chatbot' (experimental)
+const adapter = {
+  storage,
+  skillRoots,
+  navigation,
+  components: [
+    createHttpMessageComponent({
+      name: 'wechat',
+      label: { zh: '微信', en: 'WeChat' },
+      endpoint: 'https://wechat.example.com/send',
+      tips: {
+        zh: '请向小鲁班发送“获取发送token”',
+        en: 'Send "获取发送token" to XiaoLuban to get the send token.'
+      }
+    })
+  ]
+};
+```
+
+`createHttpMessageComponent` gives the model two tools: `wechat` (arguments
+`receiver` and `content` only) and `wechat_update_credentials`. A send goes:
+confirmation card → token form (first time only) → one `POST` → a result card in
+the conversation. If you set `tips` (a string, or `{ zh, en }` like `label`), the
+token form shows it the first time the token is collected — typically how to
+obtain one; it is not shown again when the user updates a saved token. The
+request body is exactly:
+
+```json
+{ "content": "<h2>…</h2><p><b>…</b></p>", "receiver": "alice", "auth": "<token>" }
+```
+
+- `content` is always converted from Markdown (GFM) to HTML first; HTML already
+  in the text is kept as-is. The converter (`marked`) is loaded only when a
+  message is actually sent.
+- `receiver` must come from the user — the tool description tells the model never
+  to guess one.
+- `auth` is the component's credential. The model can neither see nor fill it: it
+  is not in the tool's input schema, and it appears only in the credential store
+  and the request body. It is never put in a session file, trace, snapshot,
+  `ChatEvent`, or LLM request.
+- The endpoint comes only from your configuration. A confirmation card shows the
+  receiver, a plain-text preview of what will be sent and the target host (with
+  an "unencrypted" warning for `http:` outside loopback). Tick **Don't ask again**
+  and the card is skipped for that component **and that receiver** only.
+- Every call leaves a result card on the assistant message (`componentCalls`),
+  independent of what the model says afterwards, and it survives a reload.
+
+**Where credentials live.** By default in `localStorage`, read on every call (so
+a token updated in another tab is used on the next send):
+
+| Key                                     | Value                                            |
+| --------------------------------------- | ------------------------------------------------ |
+| `webskill.component.<name>.credentials` | `{"auth":"…"}`                                   |
+| `webskill.component.<name>.consent`     | `["alice","bob"]` — receivers that skip the card |
+
+A record that cannot be parsed counts as missing: the token is collected again
+and the card is shown again. Where `localStorage` is unavailable (an extension
+sandbox page, for example) and you did not inject a store, a call fails with
+`TOOL_UNSUPPORTED` — it never silently falls back to memory. Inject
+`ChatbotHostAdapter.componentStore` to keep credentials elsewhere.
+
+**Things to know.**
+
+- `localStorage` is readable by any script on the same origin. Inject your own
+  `componentStore` if that is not acceptable.
+- From a web page the browser sends a CORS preflight for a JSON `POST`; the
+  service must allow your page's origin (and `content-type`). An `https:` page
+  cannot call an `http:` endpoint at all. Both show up as a failed result card
+  ("Failed to fetch"). Extension pages with `host_permissions` for the endpoint
+  are not subject to CORS.
+- The HTML is sent as converted and is **not sanitised** — it goes to your
+  service, not into this page. Sanitise on the receiving side before rendering it.
+- A component name must match `^[a-z][a-z0-9_]{0,39}$` and not contain `__`; an
+  invalid or duplicate name makes `new ChatEngine(...)` throw
+  `VALIDATION_FAILED`. A name that collides with a built-in tool fails on the
+  first send with the same code.
+- For anything other than an HTTP message, implement `ChatComponent` yourself
+  (`inputSchema`, optional `credentials`, `confirm`, `invoke`). Each credential
+  field may carry `description` (shown on every form) and `tips` (shown only
+  while that field has not been saved yet).
+
 ## Embedding models
 
 - **As a component** inside an existing web app — mount `<Chatbot>` in your own

package/dist/chatbot.css

@@ -1294,6 +1294,9 @@
   .break-words {
     overflow-wrap: break-word;
   }
+  .break-all {
+    word-break: break-all;
+  }
   .whitespace-nowrap {
     white-space: nowrap;
   }
@@ -1934,8 +1937,8 @@
     .lg\:flex {
       display: flex;
     }
-    .lg\:grid-cols-\[minmax\(0\,1fr\)_0\.625rem_minmax\(18rem\,var\(--webskill-secondary-size\)\)\] {
-      grid-template-columns: minmax(0,1fr) 0.625rem minmax(18rem,var(--webskill-secondary-size));
+    .lg\:grid-cols-\[minmax\(var\(--webskill-primary-min\,0px\)\,1fr\)_0\.625rem_minmax\(18rem\,var\(--webskill-secondary-size\)\)\] {
+      grid-template-columns: minmax(var(--webskill-primary-min,0px),1fr) 0.625rem minmax(18rem,var(--webskill-secondary-size));
     }
   }
   .dark\:bg-subtle:where(.dark, .dark *, [data-theme='dark'], [data-theme='dark'] *) {

package/dist/config.d.ts

@@ -17,6 +17,24 @@ declare class WebSkillConfigError extends Error {
   constructor(code: WebSkillConfigErrorCode, path: string, message: string);
 }
 //#endregion
+//#region ../ui-kit/src/runtime-config/siteAccess.d.ts
+/**
+ * 站点白名单的匹配规则（`RuntimeConfig.siteAccess.allowedHosts`）。
+ *
+ * 放在配置字段旁边而不是宿主里：规则一旦有第二份手抄，「配了却不生效」
+ * 和「以为拦住了其实没拦」就会同时存在，而后者是安全问题。
+ */
+/**
+ * 地址是否落在白名单内。**空清单一律放行**——它表示「宿主没有设限」，
+ * 而不是「谁都不许」；把空当成全拒会让没配过的宿主整个瘫掉。
+ *
+ * 解析不出主机名的地址（`about:blank`、畸形串）在有清单时**拒绝**：
+ * 认不出来就不该当成自己人。
+ *
+ * @experimental
+ */
+declare function isAllowedSite(url: string | undefined, allowedHosts: readonly string[]): boolean;
+//#endregion
 //#region src/config/merge.d.ts
 /**
  * 三方合并：宿主缺省值 · 用户存储 · 上次应用过的缺省值快照。
@@ -104,4 +122,4 @@ interface ConfigDefaultsStoreOptions {
  */
 declare function createConfigDefaultsStore(store: RuntimeConfigStore, options: ConfigDefaultsStoreOptions): RuntimeConfigStore;
 //#endregion
-export { type AppliedConfigDefaults, type ApplyConfigDefaultsInput, BAKED_KEY_SENTINEL, type BakedSecretLoader, CONFIGURED_RUNTIME_PATHS, CONFIG_FIELDS, CONFIG_TOP_LEVEL_SECTIONS, type ConfigDefaultsSnapshotStore, type ConfigDefaultsStoreOptions, type ConfigFieldSpec, type ConfigLeafKind, NON_CONFIGURABLE_RUNTIME_PATHS, type ParseWebSkillConfigOptions, type ParsedWebSkillConfig, type WebSkillConfigDefaults, WebSkillConfigError, type WebSkillConfigErrorCode, applyConfigDefaults, createConfigDefaultsStore, parseWebSkillConfig };
+export { type AppliedConfigDefaults, type ApplyConfigDefaultsInput, BAKED_KEY_SENTINEL, type BakedSecretLoader, CONFIGURED_RUNTIME_PATHS, CONFIG_FIELDS, CONFIG_TOP_LEVEL_SECTIONS, type ConfigDefaultsSnapshotStore, type ConfigDefaultsStoreOptions, type ConfigFieldSpec, type ConfigLeafKind, NON_CONFIGURABLE_RUNTIME_PATHS, type ParseWebSkillConfigOptions, type ParsedWebSkillConfig, type WebSkillConfigDefaults, WebSkillConfigError, type WebSkillConfigErrorCode, applyConfigDefaults, createConfigDefaultsStore, isAllowedSite, parseWebSkillConfig };

package/dist/config.js

@@ -1,6 +1,61 @@
 import { r as mergeRuntimeConfigDefaults } from "./types-DzBMgDa6.js";
 import { a as NON_CONFIGURABLE_RUNTIME_PATHS, i as CONFIG_FIELDS, n as parseWebSkillConfig, o as WebSkillConfigError, r as CONFIGURED_RUNTIME_PATHS, t as CONFIG_TOP_LEVEL_SECTIONS } from "./parse-BaIF8Nm5.js";
 
+//#region ../ui-kit/src/runtime-config/siteAccess.ts
+/**
+* 站点白名单的匹配规则（`RuntimeConfig.siteAccess.allowedHosts`）。
+*
+* 放在配置字段旁边而不是宿主里：规则一旦有第二份手抄，「配了却不生效」
+* 和「以为拦住了其实没拦」就会同时存在，而后者是安全问题。
+*/
+/** 把用户写的模式归一：去空白、小写、去掉前导点与结尾点 */
+function normalizePattern(pattern) {
+	return pattern.trim().toLowerCase().replace(/^\.+/, "").replace(/\.+$/, "");
+}
+/**
+* 单条模式是否命中主机名。
+*
+* - `*` 命中一切。
+* - `*.example.com` 命中 `a.example.com`、`a.b.example.com`，**也命中** `example.com`
+*   本体——与 Chrome 的 match pattern 同口径。用户写通配是为了「这个站」，
+*   让主域漏网只会制造一条谁也想不到的缝。
+* - `example.com` 只命中它自己。
+*
+* 端口与协议一律不参与：用户写的是域名。
+*/
+function matchesPattern(host, pattern) {
+	const p = normalizePattern(pattern);
+	if (p === "") return false;
+	if (p === "*") return true;
+	if (p.startsWith("*.")) {
+		const base = p.slice(2);
+		return base !== "" && (host === base || host.endsWith(`.${base}`));
+	}
+	return host === p;
+}
+/**
+* 地址是否落在白名单内。**空清单一律放行**——它表示「宿主没有设限」，
+* 而不是「谁都不许」；把空当成全拒会让没配过的宿主整个瘫掉。
+*
+* 解析不出主机名的地址（`about:blank`、畸形串）在有清单时**拒绝**：
+* 认不出来就不该当成自己人。
+*
+* @experimental
+*/
+function isAllowedSite(url, allowedHosts) {
+	if (allowedHosts.length === 0) return true;
+	if (url === void 0) return false;
+	let host;
+	try {
+		host = new URL(url).hostname.toLowerCase().replace(/\.+$/, "");
+	} catch {
+		return false;
+	}
+	if (host === "") return false;
+	return allowedHosts.some((pattern) => matchesPattern(host, pattern));
+}
+
+//#endregion
 //#region src/config/merge.ts
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -197,4 +252,4 @@ function createConfigDefaultsStore(store, options) {
 }
 
 //#endregion
-export { BAKED_KEY_SENTINEL, CONFIGURED_RUNTIME_PATHS, CONFIG_FIELDS, CONFIG_TOP_LEVEL_SECTIONS, NON_CONFIGURABLE_RUNTIME_PATHS, WebSkillConfigError, applyConfigDefaults, createConfigDefaultsStore, parseWebSkillConfig };
+export { BAKED_KEY_SENTINEL, CONFIGURED_RUNTIME_PATHS, CONFIG_FIELDS, CONFIG_TOP_LEVEL_SECTIONS, NON_CONFIGURABLE_RUNTIME_PATHS, WebSkillConfigError, applyConfigDefaults, createConfigDefaultsStore, isAllowedSite, parseWebSkillConfig };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { a as RuntimeRendererId, c as RuntimeQuickPrompt, d as TranslateFn, i as RuntimeLlmEntry, l as Locale, n as RuntimeConfig, o as QuickPrompt, r as RuntimeConfigStore, s as QuickPromptIconName, t as RuntimeAppearanceConfig, u as LocalizedText } from "./index-6TE6MWZ2.js";
+import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocumentSurfaceHost, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, JsonSchema, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, PptxTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, VisionDelegate, VisionDelegateRequest, VisionDelegateResult, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
 import "react";
-import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocumentSurfaceHost, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, PptxTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, VisionDelegate, VisionDelegateRequest, VisionDelegateResult, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
 import { PageImageHost, RemoteImageHost, SandboxMode, TypeScriptSupportOptions, WebOfficeConsent, WebOfficeHost } from "@webskill/sdk/browser";
 import { CustomSurfaceActionEvent, ReactBridgeState, SpecInteractionChannel, SurfaceRegistry, UiSurfaceActionEvent } from "@webskill/sdk/ui-react";
-import { ConsentUi, DocxDocumentReader, DocxTemplateEngine, DownloadedFileConsent, DownloadedFileReader, DwgDocumentContent, DwgProjection, PageActionPolicy, PagePerceptionPolicy, PdfDocumentReader, PerceptionPagingBudget, PerceptionRecord, PptxDocumentReader, SkillCandidateSink, TabWorksetPolicy, TemplateFileSource, TodoItem, XlsxDocumentReader, XlsxTemplateEngine } from "@webskill/sdk/agent";
+import { ConsentUi, DocxDocumentReader, DocxTemplateEngine, DownloadedFileConsent, DownloadedFileReader, DwgDocumentContent, DwgProjection, PageActionPolicy, PagePerceptionPolicy, PdfDocumentReader, PerceptionPagingBudget, PerceptionRecord, PptxDocumentReader, SkillCandidateSink, TabWorksetPolicy, TemplateFileSource, TodoItem, XlsxDocumentReader, XlsxTableReader, XlsxTemplateEngine } from "@webskill/sdk/agent";
 //#region ../core/src/attachment/kind.d.ts
 /**
  * 附件类型判据与文本形态。0.14.0 分册 20 从 `@webskill/chatbot` 迁入：
@@ -82,6 +82,116 @@ declare function createLocalStorageRuntimeConfigStore(options?: LocalStorageRunt
 /** 内存实现：测试、SSR、以及宿主明确不想持久化时使用。 @experimental */
 declare function createMemoryRuntimeConfigStore(initial?: Partial<RuntimeConfig>): RuntimeConfigStore;
 //#endregion
+//#region src/core/components/types.d.ts
+/**
+ * 显示文本：不分语言的一个串，或中英两份。
+ * @experimental
+ */
+type ChatComponentText = string | {
+  readonly zh: string;
+  readonly en: string;
+};
+/**
+ * 组件要用户提供、并长期保存的一项凭据。表单里一律是 password 字段。
+ * @experimental
+ */
+interface ChatComponentCredentialField {
+  /** 存储与执行入参里的键名，如 `auth` */
+  readonly name: string;
+  readonly label: ChatComponentText;
+  /** 每次弹表单都显示 */
+  readonly description?: ChatComponentText;
+  /** 只在存储里还没有这一项时显示：告诉用户去哪里拿 */
+  readonly tips?: ChatComponentText;
+}
+/**
+ * 执行前确认卡上要说清的东西。
+ * @experimental
+ */
+interface ChatComponentConfirmation {
+  /** 本次的目标；「不再询问」按（组件，target）记 */
+  readonly target: string;
+  /** 将发出内容的纯文本；卡上取前 2 000 字符 */
+  readonly preview?: string;
+  /** 目标服务地址；卡上显示主机名，并据协议决定是否加未加密提示 */
+  readonly endpoint?: string;
+}
+/** @experimental */
+interface ChatComponentInvokeContext {
+  readonly credentials: Readonly<Record<string, string>>;
+  /** run 的取消信号 */
+  readonly signal?: AbortSignal;
+}
+/** @experimental */
+interface ChatComponentOutcome {
+  readonly ok: boolean;
+  /** 结果卡上的细节，语言中立或英文，如 `HTTP 200` */
+  readonly detail?: string;
+  /** 回给模型的英文说明，不得含凭据 */
+  readonly message: string;
+  /** 服务明确拒绝了凭据（如 401/403）：模型说明里会点名更新工具 */
+  readonly credentialsRejected?: boolean;
+}
+/**
+ * 宿主组件：宿主在接入时注册、模型以工具调用触发的一项能力。
+ * @experimental
+ */
+interface ChatComponent {
+  /** 工具名，`^[a-z][a-z0-9_]{0,39}$`，不含 `__` */
+  readonly name: string;
+  readonly label: ChatComponentText;
+  /** 确认卡与结果卡上的动作名；缺省为「执行 / Run」 */
+  readonly actionLabel?: ChatComponentText;
+  /** 给模型看的英文说明：何时调用、参数怎么填 */
+  readonly description: string;
+  /** 模型填的入参；凭据字段不得出现在这里 */
+  readonly inputSchema: JsonSchema;
+  readonly credentials?: readonly ChatComponentCredentialField[];
+  /** 返回 undefined 表示这一次不需要确认 */
+  confirm?(args: Readonly<Record<string, unknown>>): ChatComponentConfirmation | undefined;
+  invoke(args: Readonly<Record<string, unknown>>, context: ChatComponentInvokeContext): Promise<ChatComponentOutcome>;
+}
+/**
+ * 凭据与「不再询问」的存放处。缺省实现在 localStorage。
+ * @experimental
+ */
+interface ChatComponentStore {
+  readCredentials(component: string): Promise<Readonly<Record<string, string>> | undefined>;
+  writeCredentials(component: string, values: Readonly<Record<string, string>>): Promise<void>;
+  isConsentRemembered(component: string, target: string): Promise<boolean>;
+  rememberConsent(component: string, target: string): Promise<void>;
+}
+/**
+ * 一次组件调用在会话里留下的记录。只存结构化结果，不存成句的文案。
+ * @experimental
+ */
+interface ChatComponentCallRecord {
+  readonly component: string;
+  readonly label: ChatComponentText;
+  readonly actionLabel?: ChatComponentText;
+  readonly action: 'invoke' | 'update-credentials';
+  readonly outcome: 'succeeded' | 'failed' | 'declined' | 'cancelled';
+  readonly target?: string;
+  readonly detail?: string;
+  /** epoch ms */
+  readonly at: number;
+}
+/** @experimental */
+interface HttpMessageComponentOptions {
+  readonly name: string;
+  readonly label: ChatComponentText;
+  /** 只由宿主配置；模型改不了 */
+  readonly endpoint: string;
+  /** 覆盖给模型的说明 */
+  readonly description?: string;
+  /** 首次收集凭据时显示的获取提示；挂到 `auth` 字段的 `tips` 上 */
+  readonly tips?: ChatComponentText;
+  /** 扩展宿主传带 host_permissions 的那一个；缺省取全局 fetch */
+  readonly fetch?: typeof fetch;
+  /** 缺省 30 000 */
+  readonly timeoutMs?: number;
+}
+//#endregion
 //#region src/core/visionDelegate.d.ts
 /**
  * 委派目标端点的可辨识标识；告知卡与审计都只用这三项（FR-17.6a / FR-17.7a）
@@ -229,6 +339,12 @@ interface ChatbotHostAdapter {
   docxDocumentReader?: DocxDocumentReader;
   /** xlsx → 行流（`createXlsxBlockReader`）；不注入即 `read_document` 读不了 Excel @experimental */
   xlsxDocumentReader?: XlsxDocumentReader;
+  /**
+   * xlsx → 单元格网格（`createXlsxTableReader`）。注入后，估算超过阈值的 xlsx 附件只以画像进消息，
+   * 统计交给 `query_table` 在本机对全表计算（整张表不进上下文）；不注入则两者都不发生。
+   * @experimental
+   */
+  xlsxTableReader?: XlsxTableReader;
   /**
    * pptx → 逐页的块序列（`createPptxBlockReader`）；不注入即 `read_document` 读不了演示文稿。
    * 给的是页上的字与图，**不是页面渲染图**——要版式只能退到截屏。
@@ -338,6 +454,19 @@ interface ChatbotHostAdapter {
    * @experimental
    */
   documentSurface?: DocumentSurfaceHost;
+  /**
+   * 宿主组件（0.26.0 分册 14）：宿主注册、模型以工具调用触发的能力，例如「把汇总发到微信」。
+   * 每个组件带自己的确认、凭据与结果卡；不注入（或空数组）即工具表与系统提示逐字不变。
+   * 名字不合规或重名时 `new ChatEngine` 抛 `VALIDATION_FAILED`。
+   * @experimental
+   */
+  components?: readonly ChatComponent[];
+  /**
+   * 组件凭据与「不再询问」的存放处。缺省在 `localStorage`（键名见 README）；
+   * 没有可用的 `localStorage`（如扩展的 sandbox 页）且没注入时，组件调用回 `TOOL_UNSUPPORTED`。
+   * @experimental
+   */
+  componentStore?: ChatComponentStore;
 }
 /**
  * DWG 图纸的宿主出口（0.22.0 分册 19）。
@@ -807,6 +936,12 @@ interface ChatMessage {
    * @experimental
    */
   perceptions?: PerceptionRecord[];
+  /**
+   * 该 run 内的宿主组件调用记录（0.26.0 分册 14）。结果卡读它，不依赖模型复述；
+   * 凭据永不进入这里。
+   * @experimental
+   */
+  componentCalls?: ChatComponentCallRecord[];
   /**
    * 该 run 的大模型用量（0.10.0 UI-UX5 #47）：消息操作区图标右侧显示
    * 输入输出合计 tokens（千分位）。上游不回报用量时缺省，不显示假数据。
@@ -851,6 +986,12 @@ interface ChatSessionMeta {
   archived?: boolean;
   /** 用户已手动重命名：后续 send 不再用首条消息覆盖标题 */
   titleLocked?: boolean;
+  /**
+   * 已落盘的消息条数（新会话为 0）。打开面板时用它判断最新会话是不是空的（分册 12）。
+   * 缺省表示来源没给，按非空处理。
+   * @experimental
+   */
+  messageCount?: number;
 }
 /**
  * 会话列表页：除了数据，还得告诉 UI「为什么是空的」（FR-21.4 / FR-21.11）。 @experimental
@@ -976,6 +1117,10 @@ type ChatEvent =
   type: 'page-perceived';
   runId: string;
   record: PerceptionRecord;
+} | {
+  type: 'component-called';
+  runId: string;
+  record: ChatComponentCallRecord;
 } | {
   type: 'interaction-requested';
   id: string;
@@ -1100,6 +1245,17 @@ interface ChatbotConfig {
   executorFactory?: (deps: SandboxExecutorDeps) => ScriptExecutor;
 }
 //#endregion
+//#region src/core/components/httpMessage.d.ts
+/**
+ * 「向外部服务发一条消息」的现成组件：`POST` JSON `{ content, receiver, auth }`。
+ *
+ * - `content` 一律先经 Markdown → HTML 转换；原文里的 HTML 原样保留。
+ * - `auth` 是组件的唯一凭据：首次发送时向用户收集，存进组件存储后复用。
+ * - 地址只由宿主配置，模型改不了。
+ * @experimental
+ */
+declare function createHttpMessageComponent(options: HttpMessageComponentOptions): ChatComponent;
+//#endregion
 //#region src/core/interactionBridge.d.ts
 /** 单个渲染档的能力集（复合桥判定该不该回落 native 的唯一数据源） @experimental */
 interface RendererCapability {
@@ -1260,6 +1416,8 @@ declare const chatbotDictionary: {
     'message.deleted.description': string;
     'message.viewTrace': string;
     'message.tokens': string;
+    'message.time.sent': string;
+    'message.time.replied': string;
     'message.skillsUsed': string;
     'message.skill': string;
     'message.edit': string;
@@ -1418,6 +1576,26 @@ declare const chatbotDictionary: {
     'interaction.allow': string;
     'interaction.deny': string;
     'interaction.required': string;
+    'interaction.component.body': string;
+    'interaction.component.endpoint': string;
+    'interaction.component.insecure': string;
+    'interaction.component.previewTruncated': string;
+    'interaction.component.remember': string;
+    'component.locale': string;
+    'component.action.invoke': string;
+    'component.httpMessage.action': string;
+    'component.httpMessage.credential': string;
+    'component.httpMessage.credentialHint': string;
+    'component.credentials.title': string;
+    'component.credentials.updateTitle': string;
+    'component.credentials.saved': string;
+    'component.credentials.missing': string;
+    'component.credentials.updated': string;
+    'component.credentials.cancelled': string;
+    'component.outcome.succeeded': string;
+    'component.outcome.failed': string;
+    'component.outcome.declined': string;
+    'component.outcome.cancelled': string;
     'surface.addItem': string;
     'surface.removeItem': string;
     'surface.arrayFirstItemOnly': string;
@@ -1480,6 +1658,7 @@ declare const chatbotDictionary: {
     'attachment.pdfRefused': string;
     'attachment.pdfNoExtractor': string;
     'attachment.textTooLong': string;
+    'attachment.tableAsQuery': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -1700,6 +1879,8 @@ declare const chatbotDictionary: {
     'message.deleted.description': string;
     'message.viewTrace': string;
     'message.tokens': string;
+    'message.time.sent': string;
+    'message.time.replied': string;
     'message.skillsUsed': string;
     'message.skill': string;
     'capability.tools.on': string;
@@ -1855,6 +2036,26 @@ declare const chatbotDictionary: {
     'interaction.allow': string;
     'interaction.deny': string;
     'interaction.required': string;
+    'interaction.component.body': string;
+    'interaction.component.endpoint': string;
+    'interaction.component.insecure': string;
+    'interaction.component.previewTruncated': string;
+    'interaction.component.remember': string;
+    'component.locale': string;
+    'component.action.invoke': string;
+    'component.httpMessage.action': string;
+    'component.httpMessage.credential': string;
+    'component.httpMessage.credentialHint': string;
+    'component.credentials.title': string;
+    'component.credentials.updateTitle': string;
+    'component.credentials.saved': string;
+    'component.credentials.missing': string;
+    'component.credentials.updated': string;
+    'component.credentials.cancelled': string;
+    'component.outcome.succeeded': string;
+    'component.outcome.failed': string;
+    'component.outcome.declined': string;
+    'component.outcome.cancelled': string;
     'surface.addItem': string;
     'surface.removeItem': string;
     'surface.arrayFirstItemOnly': string;
@@ -1917,6 +2118,7 @@ declare const chatbotDictionary: {
     'attachment.pdfRefused': string;
     'attachment.pdfNoExtractor': string;
     'attachment.textTooLong': string;
+    'attachment.tableAsQuery': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -2137,6 +2339,8 @@ declare const useT: () => TranslateFn<{
     'message.deleted.description': string;
     'message.viewTrace': string;
     'message.tokens': string;
+    'message.time.sent': string;
+    'message.time.replied': string;
     'message.skillsUsed': string;
     'message.skill': string;
     'message.edit': string;
@@ -2295,6 +2499,26 @@ declare const useT: () => TranslateFn<{
     'interaction.allow': string;
     'interaction.deny': string;
     'interaction.required': string;
+    'interaction.component.body': string;
+    'interaction.component.endpoint': string;
+    'interaction.component.insecure': string;
+    'interaction.component.previewTruncated': string;
+    'interaction.component.remember': string;
+    'component.locale': string;
+    'component.action.invoke': string;
+    'component.httpMessage.action': string;
+    'component.httpMessage.credential': string;
+    'component.httpMessage.credentialHint': string;
+    'component.credentials.title': string;
+    'component.credentials.updateTitle': string;
+    'component.credentials.saved': string;
+    'component.credentials.missing': string;
+    'component.credentials.updated': string;
+    'component.credentials.cancelled': string;
+    'component.outcome.succeeded': string;
+    'component.outcome.failed': string;
+    'component.outcome.declined': string;
+    'component.outcome.cancelled': string;
     'surface.addItem': string;
     'surface.removeItem': string;
     'surface.arrayFirstItemOnly': string;
@@ -2357,6 +2581,7 @@ declare const useT: () => TranslateFn<{
     'attachment.pdfRefused': string;
     'attachment.pdfNoExtractor': string;
     'attachment.textTooLong': string;
+    'attachment.tableAsQuery': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -2577,6 +2802,8 @@ declare const useT: () => TranslateFn<{
     'message.deleted.description': string;
     'message.viewTrace': string;
     'message.tokens': string;
+    'message.time.sent': string;
+    'message.time.replied': string;
     'message.skillsUsed': string;
     'message.skill': string;
     'capability.tools.on': string;
@@ -2732,6 +2959,26 @@ declare const useT: () => TranslateFn<{
     'interaction.allow': string;
     'interaction.deny': string;
     'interaction.required': string;
+    'interaction.component.body': string;
+    'interaction.component.endpoint': string;
+    'interaction.component.insecure': string;
+    'interaction.component.previewTruncated': string;
+    'interaction.component.remember': string;
+    'component.locale': string;
+    'component.action.invoke': string;
+    'component.httpMessage.action': string;
+    'component.httpMessage.credential': string;
+    'component.httpMessage.credentialHint': string;
+    'component.credentials.title': string;
+    'component.credentials.updateTitle': string;
+    'component.credentials.saved': string;
+    'component.credentials.missing': string;
+    'component.credentials.updated': string;
+    'component.credentials.cancelled': string;
+    'component.outcome.succeeded': string;
+    'component.outcome.failed': string;
+    'component.outcome.declined': string;
+    'component.outcome.cancelled': string;
     'surface.addItem': string;
     'surface.removeItem': string;
     'surface.arrayFirstItemOnly': string;
@@ -2794,6 +3041,7 @@ declare const useT: () => TranslateFn<{
     'attachment.pdfRefused': string;
     'attachment.pdfNoExtractor': string;
     'attachment.textTooLong': string;
+    'attachment.tableAsQuery': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -3204,13 +3452,19 @@ interface InterruptedBannerProps {
   engine: ChatEngine;
   /** 会话切换时重新检查（值变化即触发重新 listInterrupted） */
   sessionId?: string;
+  /**
+   * 点「继续」后、`engine.resume` 之前调用，参数是快照所属的会话 id，用来把界面切到那个会话。
+   * 不传则不切，行为与 0.25.0 相同；回调失败不阻断恢复。
+   * @experimental
+   */
+  onBeforeResume?(sessionId: string): void | Promise<void>;
 }
 /**
  * 未完成对话提示条：挂载/会话切换时检查 interrupted 快照，非空则顶部 banner
  * + Resume（engine.resume 后等待中的表单重新进入 bridge.pending）。
  * @stable
  */
-declare function InterruptedBanner({ engine, sessionId }: InterruptedBannerProps): import("react").JSX.Element | null;
+declare function InterruptedBanner({ engine, sessionId, onBeforeResume }: InterruptedBannerProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/react/ErrorCard.d.ts
 /** @stable */
@@ -3240,6 +3494,6 @@ declare function ErrorCard({ code, message, loopLimits, onOpenSettings, onDismis
  * Version of the published `@webskill/chatbot` package, injected at build time.
  * @stable
  */
-declare const CHATBOT_VERSION = "0.22.0";
+declare const CHATBOT_VERSION = "0.24.0";
 //#endregion
-export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, ChatbotVisionDelegate, type ChatbotVisionDelegateOptions, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, type DwgHost, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, type VisionDelegationConsent, type VisionDelegationEndpoint, WEB_OFFICE_TEMPLATE_PREFIX, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };
+export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatComponent, type ChatComponentCallRecord, type ChatComponentConfirmation, type ChatComponentCredentialField, type ChatComponentInvokeContext, type ChatComponentOutcome, type ChatComponentStore, type ChatComponentText, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, ChatbotVisionDelegate, type ChatbotVisionDelegateOptions, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, type DwgHost, ErrorCard, type ErrorCardProps, type HttpMessageComponentOptions, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, type VisionDelegationConsent, type VisionDelegationEndpoint, WEB_OFFICE_TEMPLATE_PREFIX, chatbotDictionary, configureA2uiMarkdown, createHttpMessageComponent, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };