@icen.ai/ui 0.9.0 → 0.11.0

package/dist/behaviors/ai-tools.d.mts

@@ -1,15 +1,38 @@
+/** run 第三参：执行上下文（AbortSignal + 活动流追加口） */
+interface AiToolRunContext {
+    /** 执行中止信号：超时、卡片被移除/淘汰/清空、unregister 下架时 abort */
+    signal: AbortSignal;
+    /** 活动流：一行一行追加进挂载卡的活动流区域（.icen-ai-tools-item-stream） */
+    progress(line: string): void;
+}
 /** 一个 UI 工具：模型可调用的可视化/交互能力 */
 interface AiToolDef<TInput = unknown> {
     /** 工具名（模型侧 function name；建议 snake_case） */
     name: string;
-    /** 给模型看的一段说明（何时用、返回什么） */
+    /** 给模型看的一段说明（何时用、返回什么）；requiresApproval 时也作为审批区原因行 */
     description: string;
-    /** 输入 JSON Schema（OpenAI function.parameters / MCP inputSchema 兼容） */
+    /** 输入 JSON Schema（OpenAI parameters / MCP inputSchema 兼容；校验见 validateToolArgs） */
     inputSchema: Record<string, unknown>;
-    /** 执行：input → 在 mount 上渲染；返回值作为工具结果（进回执/审计） */
-    run: (input: TInput, mount: HTMLElement) => unknown;
+    /**
+     * 执行：input → 在 mount 上渲染；返回值作为工具结果（同步直返，或 Promise——
+     * area 落定后写 record.icen-result）。第三参 ctx 可选消费。
+     */
+    run: (input: TInput, mount: HTMLElement, ctx: AiToolRunContext) => unknown;
     /** 结果呈现：'mount'（默认，渲染即呈现）/ 'data'（run 返回值为准，不占挂载位） */
     present?: 'mount' | 'data';
+    /**
+     * 超时毫秒数：超时 → 结果 { ok:false, error:{ code:'timeout' } }，卡片错误态，signal abort。
+     * 只作用于返回 Promise 的 run（同步 run 在单线程内无法中断，诚实注明）；缺省 = 永不超时。
+     */
+    timeoutMs?: number;
+    /**
+     * 执行前需宿主审批：call 时挂载卡先呈审批区（原因行 = description + 输入预览，批准/拒绝按钮）。
+     * 批准 → 派 icen:ai-tool-approve 并执行；拒绝 → 派 icen:ai-tool-reject，卡片 .is-cancelled，
+     * 结果 { ok:false, error:{ code:'rejected' } }。仅 'mount' 模式生效（'data' 模式无卡可审批）。
+     */
+    requiresApproval?: boolean;
+    /** 幂等：同名 + JSON.stringify(归一 input) 相同的在途调用复用同一条记录（不重复挂载、不重复执行） */
+    idempotent?: boolean;
 }
 interface AiToolRecord {
     def: AiToolDef;
@@ -17,6 +40,11 @@ interface AiToolRecord {
     el?: HTMLElement;
     ts: number;
     input: unknown;
+    /**
+     * 结果：run 返回值（Promise 型在落定后写入）。失败统一为诚实信封
+     * { ok:false, error:{ code:'validation'|'exec'|'timeout'|'rejected', … } }；
+     * 事件 icen:ai-tool-result 的 error 字段按 events.ts 契约为 string，机器可读细节在此。
+     */
     result: unknown;
 }
 /** 注册（或覆盖同名）一个工具；第三方扩展入口 */
@@ -28,37 +56,68 @@ declare function registerAiTool(def: AiToolDef): void;
 declare function unregisterAiTool(name: string): void;
 /** 按名查已注册工具（call/can 内部同走此口；未注册返回 undefined） */
 declare function getAiTool(name: string): AiToolDef | undefined;
-/** 全部已注册工具的快照数组（aiToolsToOpenAI / aiToolsToMcp / aiToolsManifest 的底座） */
+/** 全部已注册工具的快照数组（模型侧导出四族共享的归一管线底座） */
 declare function listAiTools(): AiToolDef[];
+interface AiToolValidationError {
+    /** 出错参数路径（JSON-pointer 风：'$' 为根；'$.tags[1]'、'$.series[2].name'） */
+    path: string;
+    message: string;
+}
+interface AiToolValidationResult {
+    ok: boolean;
+    errors: AiToolValidationError[];
+    /** 本次未生效的 schema 关键字清单（schema 路径：'$.email.format'、'$.matrix.items.items'）——校验器不猜 */
+    unvalidated: string[];
+}
+/**
+ * 工具参数校验：支持 type / required / properties / enum / items（一层）/ minimum / maximum /
+ * minLength / maxLength。不支持的 schema 关键字（oneOf/anyOf/allOf/$ref/format/pattern/
+ * additionalProperties/minItems……）不猜不静默——记入 unvalidated 清单（schema 路径）。
+ * 只检查实际出现的节点；缺省可选字段不做任何断言。
+ */
+declare function validateToolArgs(schema: Record<string, unknown>, args: unknown): AiToolValidationResult;
 interface AiToolAreaOptions {
     /** 工具白名单（精确名或 'chart-*' 通配；缺省 = 全部已注册工具） */
     tools?: string[];
-    /** 最多同时挂载数（超出 FIFO 淘汰最旧挂载；缺省不限） */
+    /** 最多同时挂载数（超出 LRU 淘汰最旧挂载；缺省不限） */
     max?: number;
     /** 挂载项的最小高度提示（px，默认 240） */
     itemMinHeight?: number;
 }
+interface AiToolCallOptions {
+    /**
+     * 执行前用 validateToolArgs 校验参数（默认 true）：失败 → 挂载卡错误态列出 errors +
+     * 派 icen:ai-tool-result {ok:false}，不执行 run。校验是诚实纪律——关闭即退回模型输入裸执行。
+     */
+    validate?: boolean;
+}
 interface AiToolArea {
     el: HTMLElement;
-    /** 当前挂载数 */
+    /** 当前挂载数（含执行中/待审批的挂载卡） */
     readonly count: number;
-    /** 调用一个工具（模型 tool_call 的落地入口）：白名单外或未注册返回 null */
-    call(name: string, input: unknown): AiToolRecord | null;
-    /** 白名单内且未注册？ */
+    /**
+     * 调用一个工具（模型 tool_call 的落地入口）：白名单外或未注册返回 null。
+     * 校验（可关）→ 幂等复用 → 挂载卡 → 审批（requiresApproval 时挂起等待）→ 执行。
+     * 同步 run 落定后返回；Promise 型 run 在落定后写 record.icen-result 并补派 result 事件。
+     */
+    call(name: string, input: unknown, opts?: AiToolCallOptions): AiToolRecord | null;
+    /** 白名单内且已注册？ */
     can(name: string): boolean;
     /** 运行时改白名单 / 上限 */
     setTools(tools: string[] | undefined): void;
     setMax(max: number | undefined): void;
-    /** 清空全部挂载 */
+    /** 清空全部挂载（在途执行 signal abort） */
     clear(): void;
-    /** 挂载变化回调（call/evict/clear 后触发） */
+    /** 挂载变化回调（call 挂载时与每次 result 落定时各触发一次；evict/clear 后触发） */
     onChange(fn: (records: AiToolRecord[]) => void): () => void;
 }
 /**
  * 创建 AI 工具挂载区：宿主声明「这块区域归 AI 用」——可白名单工具、限数量
- * （超出上限 FIFO 淘汰最旧挂载）。每次 call 渲染为一个 .ai-tools-item 卡（标题行 = 工具名 +
- * 时间 + 移除钮，体 = 工具自己的渲染）。事件 icen:ai-tool-call / -result /
- * -evict（bubbles），area 上也可原生 addEventListener。
+ * （超出上限 LRU 淘汰最旧挂载）。每次 call 渲染为一个 .icen-ai-tools-item 卡
+ * （标题行 = 折叠钮 + 工具名 + 时间 + 状态点 + 移除钮；体 = 审批区（仅审批态）+
+ * 错误清单（仅失败态）+ 工具自己的渲染 + 活动流（progress 追加））。
+ * 事件 icen:ai-tool-call / -result / -evict / -approve / -reject（bubbles），
+ * area 上也可原生 addEventListener。
  */
 declare function createAiToolArea(el: HTMLElement, opts?: AiToolAreaOptions): AiToolArea;
 /** 导出为 OpenAI chat.completions tools 参数格式（可传 names / 通配过滤） */
@@ -70,15 +129,29 @@ declare function aiToolsToOpenAI(names?: string[]): Array<{
         parameters: Record<string, unknown>;
     };
 }>;
+/** 导出为 Anthropic messages tools 格式（name / description / input_schema） */
+declare function aiToolsToAnthropic(names?: string[]): Array<{
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}>;
 /** 导出为 MCP tools 格式（name / description / inputSchema） */
 declare function aiToolsToMcp(names?: string[]): Array<{
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
 }>;
+/**
+ * 导出为 Vercel AI SDK v5 的 tool() 描述表：{ [name]: { description, inputSchema } }——
+ * 纯 JSON 描述可直接喂 tool()；不携带 execute（执行在宿主侧经 createAiToolArea 挂载）。
+ */
+declare function aiToolsToAiSdk(names?: string[]): Record<string, {
+    description: string;
+    inputSchema: Record<string, unknown>;
+}>;
 /** 能力清单文本（贴 system prompt：可用工具 × 数据形态一览） */
 declare function aiToolsManifest(names?: string[]): string;
 /** 模型 tool_call 参数容错解析（JSON 字符串 / 对象直给 / 坏 JSON 返回 {}） */
 declare function parseAiToolArgs(raw: unknown): Record<string, unknown>;
 
-export { type AiToolArea, type AiToolAreaOptions, type AiToolDef, type AiToolRecord, aiToolsManifest, aiToolsToMcp, aiToolsToOpenAI, createAiToolArea, getAiTool, listAiTools, parseAiToolArgs, registerAiTool, unregisterAiTool };
+export { type AiToolArea, type AiToolAreaOptions, type AiToolCallOptions, type AiToolDef, type AiToolRecord, type AiToolRunContext, type AiToolValidationError, type AiToolValidationResult, aiToolsManifest, aiToolsToAiSdk, aiToolsToAnthropic, aiToolsToMcp, aiToolsToOpenAI, createAiToolArea, getAiTool, listAiTools, parseAiToolArgs, registerAiTool, unregisterAiTool, validateToolArgs };