@h-ai/ai 0.1.0-alpha.35 → 0.1.0-alpha.37

package/README.md

@@ -18,13 +18,36 @@ AI 能力模块，提供统一的 `ai` 服务对象，覆盖 LLM 对话、工具
 - `ai.audio`：语音识别（ASR）与语音合成（TTS），支持完整与流式调用，覆盖 OpenAI / MiMo / Qwen / 豆包平台。
 - `ai.a2a`：Agent-to-Agent 请求处理与远端调用。
 - `@h-ai/ai/client`：前端轻量客户端（配合 API 服务）。
-- `AIStoreProvider`：统一存储抽象；默认 DB Provider 基于 reldb + vecdb。
+- `AIStoreProvider`：统一存储抽象；无数据库时默认使用进程内临时 Store，已初始化 reldb + vecdb 时自动使用持久化 DB Provider。
 
 更完整的方法清单、错误码与长示例见 [REFERENCE.md](./REFERENCE.md)。
 
 ## 快速开始
 
-### 默认 DB Provider（reldb + vecdb）
+### LLM-only（零数据库依赖）
+
+```ts
+import { ai } from '@h-ai/ai'
+
+const init = await ai.init({
+  llm: {
+    model: 'gpt-4o-mini',
+    apiKey: process.env.HAI_AI_LLM_API_KEY,
+  },
+})
+if (!init.success)
+  return init
+
+const result = await ai.llm.chat({
+  messages: [{ role: 'user', content: '你好！' }],
+})
+
+await ai.close()
+```
+
+未初始化 reldb/vecdb 时，AI 使用进程内临时 Store 保存会话等运行时状态；`ai.close()`、进程退出或多实例切换后数据不会保留。需要 Memory、Context、Persona 或会话跨重启持久化时，使用下面的 DB Provider。
+
+### 持久化 DB Provider（reldb + vecdb）
 
 ```ts
 import { ai } from '@h-ai/ai'
@@ -76,9 +99,9 @@ await ai.close()
 
 - 对外只通过 `ai` 服务对象和少量独立工厂（如 `createMcpServer`）访问。
 - 生命周期为 `await ai.init(config, options?)` / `await ai.close()`；关闭会等待自定义 `AIStoreProvider.close()`。
-- 公共方法返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`；业务失败通过 `result.success === false` 和 `result.error.code` 表达。
+- 领域方法返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`；业务失败通过 `result.success === false` 和 `result.error.code` 表达。流式 `AsyncIterable`、客户端传输和第三方回调在建立或迭代期间可能抛异常。
 - `ai.tools` 与 `ai.stream` 是纯函数子系统，无需初始化即可使用。
-- 默认 DB Provider 需要 reldb/vecdb 已初始化；自定义 Provider 可隐藏其他存储后端。
+- 未初始化 reldb/vecdb 时默认使用进程内临时 Store；两者均已初始化时自动使用 DB Provider。自定义 Provider 可隐藏其他存储后端。
 
 ## API 概览
 
@@ -115,13 +138,31 @@ const temp = await ai.llm.chat({
 ### 工具调用
 
 ```ts
-const registry = ai.tools.createRegistry()
-registry.register(ai.tools.define({
+import { z } from 'zod'
+
+const registry = ai.tools.createRegistry({
+  // 统一授权在 Zod 校验后、handler 前执行；false/异常均 fail-closed
+  authorize: ({ toolName, context }) => canExecuteTool(context.objectId, toolName),
+})
+const registered = registry.register(ai.tools.define({
   name: 'get_weather',
   description: '获取天气',
   parameters: z.object({ city: z.string() }),
-  handler: async ({ city }) => ({ city, temperature: 20 }),
+  // handler 第二参为执行上下文：可响应取消（打断/超时）、感知截止时间与交互主体
+  handler: async ({ city }, { signal }) => {
+    const res = await fetch(`https://api.example.com/weather?city=${city}`, { signal })
+    return res.json()
+  },
+  timeoutMs: 10_000, // 本工具默认超时（可被 execute 的 deadline / timeoutMs 覆盖）
 }))
+if (!registered.success)
+  return registered
+
+// 执行时可传入取消信号 / 超时 / 作用域；取消或超时返回 TOOL_TIMEOUT，且不再等待未响应的 handler
+const result = await registry.execute(toolCall, { signal: controller.signal, objectId: 'user-001', timeoutMs: 30_000 })
+
+// 批量调用默认串行，避免副作用工具并发启动；纯读取且确认安全时才显式并行
+const batch = await registry.executeAll(toolCalls)
 
 const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 ```
@@ -130,6 +171,7 @@ const chat = await ai.llm.chat({ messages, tools: registry.getDefinitions() })
 
 ```ts
 import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
+import { z } from 'zod'
 
 const server = createMcpServer({ name: 'my-server', version: '1.0.0' })
 server.registerTool('search', {
@@ -149,6 +191,15 @@ if (!enriched.success) {
   return enriched
 }
 
+// 多租户推荐入口：scoped() 绑定主体与作用域，所有操作自动携带 objectId / scope（含归属校验），杜绝「忘记传 objectId」越权
+const memory = ai.memory.scoped({ objectId: 'user-001', scope: { topicId: 't-1', personaId: 'p-1' } })
+await memory.add({ content: '用户偏好中文', type: 'preference' })
+const recalled = await memory.recall('语言偏好')
+
+// clear 拒绝空过滤（防误清全局）；全局清空只能显式走管理接口
+await memory.clear({ types: ['event'] }) // 仅清该作用域内的 event
+await ai.memory.admin.clearAll({ confirm: true }) // 危险：清空整个记忆后端，需显式确认
+
 const rag = await ai.rag.query('核心架构是什么？', { sources: ['docs'], topK: 5 })
 
 const setup = await ai.knowledge.setup()
@@ -165,8 +216,8 @@ if (setup.success) {
 await ai.init({
   audio: {
     models: [
-      { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime' },
-      { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime' },
+      { id: 'asr', provider: 'qwen', model: 'qwen3-asr-flash-realtime', operations: ['transcribe'] },
+      { id: 'tts', provider: 'qwen', model: 'qwen3-tts-flash-realtime', operations: ['synthesize'] },
     ],
     transcribeModel: 'asr',
     synthesizeModel: 'tts',
@@ -189,16 +240,32 @@ for await (const event of ai.audio.transcribeStream({
     updateTranscript(event.text, event.final)
 }
 
-// 流式合成：可带自然语言风格指令，并直接连接 LLM 文本流边生成边合成；signal 可随时打断
+// 流式合成：调用方为文本段分配稳定 ID，事件可精确关联文本与音频；signal 可随时打断
 const controller = new AbortController()
-for await (const audio of ai.audio.synthesizeStream({ text: ai.llm.askStream(question), voice: 'Cherry', instruction: '用轻快的语气', signal: controller.signal })) {
-  await player.write(audio)
+for await (const event of ai.audio.synthesizeStream({
+  text: { id: 'answer-1', text: '欢迎参加访谈。' },
+  voice: 'Cherry',
+  instruction: '用轻快的语气',
+  signal: controller.signal,
+})) {
+  if (event.type === 'segment_started')
+    prepareDecoder(event.format, event.sampleRate, event.channels) // 真实输出格式来自服务端解析后的 Provider 输出
+  else if (event.type === 'audio')
+    await player.write(event.data)
+  else if (event.type === 'segment_done')
+    markSegmentReadyToCommit(event.segmentId)
 }
+
+// 实时会话启动前按操作校验模型能力
+const caps = ai.audio.getCapabilities({ operation: 'synthesize', model: 'tts' })
+if (caps.success && caps.data.synthesize?.streamingAudioOutput) { /* 可实时 TTS */ }
 ```
 
-取消/超时/连接错误统一为领域错误：`AbortSignal` 触发 → `AUDIO_CANCELLED`（超时 → `AUDIO_TIMEOUT`），连接失败 → `AUDIO_CONNECTION_FAILED`。实时连接时长受 `audio.maxStreamDurationMs`（默认 5 分钟）限制。
+> `synthesizeStream` 严格按 `segment_started → audio* → segment_done` 产出事件。`segment_started` 携带服务端解析 Provider 后的**真实输出音频参数**（`format` / `sampleRate` / `channels`），播放器据此正确解码，不应按请求参数猜测格式。播放器只有在对应音频真正播放完成后才应把该段文本计入 `spokenText`；播放状态仍由应用管理。
 
-浏览器 / 移动端通过 `@h-ai/serv` 暴露的统一语音 WebSocket 入口访问，`@h-ai/ai/client` 提供与 Node 端一致的 `audio.*` API（传输细节内部隐藏）。
+取消/超时/连接错误统一为领域错误：`AbortSignal` 触发 → `AUDIO_CANCELLED`（超时 → `AUDIO_TIMEOUT`），连接失败或 `end` 前异常断连 → `AUDIO_CONNECTION_FAILED`。实时连接时长受 `audio.maxStreamDurationMs`（默认 5 分钟）限制。
+
+浏览器 / 移动端通过 `@h-ai/serv` 暴露的统一语音 WebSocket 入口访问，`@h-ai/ai/client` 提供与 Node 端一致的 `audio.*` API（传输细节内部隐藏）。浏览器客户端严格区分正常结束、取消（`AUDIO_CANCELLED`）与异常断连（`AUDIO_CONNECTION_FAILED`）：取消或在 `end` 前断连会抛出对应领域错误码，`synthesize` 不会把未完成的部分音频当作成功结果返回。
 
 ### Context 管理器
 
@@ -207,32 +274,43 @@ const manager = ai.context.createManager({
   scope: { objectId: 'user-001', sessionId: 'sess-001' },
   compress: { auto: true, strategy: 'hybrid', maxTokens: 8000 },
   memory: { enable: true, enableExtract: true },
+  concurrency: 'reject', // 单活动生成（默认）：活动生成期间的新 chat 返回 CONTEXT_BUSY；'queue' 则排队
 })
 if (manager.success) {
   const reply = await manager.data.chat('你好')
   await manager.data.save()
+  // reset 生命周期完整：终止活动生成、清空消息/摘要/轮次，默认保留系统提示词
+  await manager.data.reset() // 可传 { preserveSystemPrompt, cancelActiveTurn, waitForMemoryTasks }
 }
 ```
 
+同一管理器默认实行**单活动生成**，避免「上一轮 AI 尚未退出，下一轮 user 消息先写入」导致的消息乱序；`reset()` 现为异步并会终止活动生成、释放并发屏障、清空轮次并默认重新写入 Persona/System Prompt。
+
 #### 真实对话状态（Conversation Commit Layer）
 
 默认（`turnCommit: 'auto'`）下，`chat` / `chatStream` 会把**模型生成的完整文本**写入上下文。但在「模型生成 → TTS 合成 → 实际播放」链路中，AI 可能说到一半就被打断——此时进入下一轮所有参与者可见的对话状态，应当是**实际播放出去的部分**，而非模型本想说完的全文。
 
-设置 `turnCommit: 'manual'` 后，生成结果不会自动写入上下文，而是返回一个 `turnId`；由调用方在确定「实际发生了什么」后显式提交真实文本：
+设置 `turnCommit: 'manual'` 后，生成结果不会自动写入上下文，而是返回一个 `turnId`；由调用方在确定「实际发生了什么」后显式提交真实文本。
+
+`chatStream` 在**调用上游模型前**就登记轮次并产出 `turn_started`（事件序列 `turn_started → delta* → done`，中途取消时 `turn_started → delta* → cancelled`）。因此即使生成到一半被 `AbortSignal` 取消，也能拿到 `turnId` 与已生成文本，用真实内容提交：
 
 ```ts
 const m = ai.context.createManager({ turnCommit: 'manual' /* ... */ }).data
+const controller = new AbortController()
 
-for await (const ev of m.chatStream('请展开讲讲')) {
-  if (ev.type === 'delta') {
-    feedTts(ev.text)
-  } // 边生成边合成播放
-  else if (ev.type === 'done') {
+for await (const ev of m.chatStream('请展开讲讲', { signal: controller.signal })) {
+  if (ev.type === 'turn_started') {
     m.markTurnSpeaking(ev.turnId) // 可选：标记进入播放
-    if (interrupted)
-      await m.interruptTurn(ev.turnId, { text: actuallySpokenText }) // 只提交播放出去的部分
-    else
-      await m.commitTurn(ev.turnId) // 完整提交
+  }
+  else if (ev.type === 'delta') {
+    feedTts(ev.text) // 边生成边合成播放
+  }
+  else if (ev.type === 'done') {
+    await m.commitTurn(ev.turnId) // 完整提交
+  }
+  else if (ev.type === 'cancelled') {
+    // 生成被 controller.abort() 取消：轮次保留，只提交实际播放出去的部分
+    await m.interruptTurn(ev.turnId, { text: actuallySpokenText })
   }
 }
 
@@ -243,6 +321,7 @@ const turns = m.getTurns()
 - `commitTurn(turnId, { text? })` — 提交真实文本（缺省用完整生成文本），状态转 `completed`。
 - `interruptTurn(turnId, { text? })` — 只写入实际表达出去的部分（缺省视为未表达，不写入），状态转 `interrupted`。
 - 只有 `committed` 的内容进入上下文与记忆提取；未提交/被打断丢弃的部分不会污染后续轮次。
+- 若轮次在流完成前已被 `interruptTurn` 打断（如主持人抢话，同时上游模型恰好正常结束），`chatStream` **不会再产出 `done`**，避免业务层误判为正常完成后继续提交文本。
 
 #### 会话固化（Memory 生命周期）
 
@@ -333,9 +412,9 @@ memory:
 ```
 
 - **`native`（默认，推荐）**：HAI 原生引擎，复用同一套 vecdb（向量库）、reldb（关系库）、LLM 与 Embedding。`extract` 采用 **Mem0 式批量合并**——一次 LLM 调用对整批抽取事实与相关既有记忆做 ADD / UPDATE / DELETE / NONE 决策，实现增量更新、跨条去重与矛盾删除，并支持 `category` 主题标签。`maxEntriesPerObject`、`maxEntriesGlobal`、`recencyDecay`、`embeddingEnabled`、`writebackRelatedTopK` 均作用于此后端；淘汰按 `objectId` 分区触发，不会因某一主体写入过多而淘汰其他主体的记忆。native 后端的 `scope` 过滤：候选集已被 `objectId` 索引收窄（≤ `maxEntriesPerObject`），PostgreSQL 上还会把 scope 下推为 `data @> '{"scope":...}'::jsonb` 包含查询并命中 JSONB **GIN 索引**（SQLite / MySQL 退回内存匹配，结果一致）。
-- **`mem0`（真·mem0ai/oss）**：直接使用 `mem0ai/oss` 的 `Memory` 引擎（嵌入式，无云服务）。LLM / Embedder 从 `llm` 配置提取（OpenAI 兼容，走 `baseUrl` / `apiKey` / 场景模型）；向量库从底层 vecdb 后端提取——`qdrant` / `pgvector` 直接复用同一后端，`lancedb` / `chroma`（mem0 TS 不支持）则退回 mem0 自带的 in-memory 存储。历史记录默认禁用。需安装 `mem0ai`（已内置为依赖）；复用 qdrant/pgvector 时需对应客户端。
+- **`mem0`（真·mem0ai/oss）**：直接使用 `mem0ai/oss` 的 `Memory` 引擎（嵌入式，无云服务）。LLM / Embedder 从 `llm` 配置提取；`qdrant` / `pgvector` 可复用底层 vecdb。无法映射 `lancedb` / `chroma` 等后端时默认 fail-fast，只有显式设置 `memory.allowEphemeralFallback: true` 才使用 mem0 in-memory，避免重启后静默丢失记忆。历史记录默认禁用。
 
-两个 Provider 对外 `ai.memory.*` API 完全一致（`extract` / `recall` / `injectMemories` / `add` / `update` / `get` / `remove` / `list` / `listPage` / `clear`），均支持 `objectId`（主体隔离）与 `scope`（业务作用域 key-value 过滤，如 `{ topicId, personaId }`）。`recall` / `list` / `listPage` / `clear` 均按 `scope` 严格过滤，`clear` 在传入 `types` / `scope` 时仅删除同时匹配项（避免误删）。一个差异：mem0 后端在 `update` 涉及 type/importance/metadata 时会重建记忆并重新分配 `id`（native 后端保持 id 稳定）。
+两个 Provider 对外 `ai.memory.*` API 完全一致（`extract` / `recall` / `injectMemories` / `add` / `update` / `get` / `remove` / `list` / `listPage` / `clear`），均支持 `objectId`（主体隔离）与 `scope`（业务作用域 key-value 过滤，如 `{ topicId, personaId }`）。`recall` / `list` / `listPage` / `clear` 均按 `scope` 严格过滤，`clear` 在传入 `types` / `scope` 时仅删除同时匹配项（避免误删）。mem0 后端的 `extract` 在框架层用统一提取器完成分类与打分（honor `types` / `model` / `minImportance` / `systemPrompt`）后以 `infer:false` 写入，保留 `hai_type` / `hai_importance`；`recall` 同样支持 `types` 过滤与 `recencyWeight` 时间衰减——二者行为与 native 一致。一个差异：mem0 后端在 `update` 涉及 type/importance/metadata 时会重建记忆并重新分配 `id`（native 后端保持 id 稳定）。
 
 **候选池与 scope 漏召回**：`scope` 过滤在内存中完成，若先按 `topK` 截断再过滤，同一主体下相关度较高的其它主题/角色记忆会把目标 scope 的记忆挤出候选池，导致「明明有却召回 0 条」。为此 `recall` / `injectMemories` 先取回 `topK × candidateMultiplier`（默认 5）条候选，过滤后再截取 `topK`。scope 隔离越细（如按 `topicId` + `personaId`），可将 `candidateMultiplier` 调大：
 
@@ -350,6 +429,13 @@ const memories = await ai.memory.recall('经济发展', {
 
 `ai.config` 返回脱敏后的配置快照；`apiKey`、`privateKey`、URL 内嵌凭证等敏感字段不会原样暴露。
 
+## 安全边界
+
+- Prompt、检索文档和模型输出都按不可信输入处理；不要把用户内容拼进不可覆盖的系统规则。
+- Zod 只校验工具参数形状，不代表调用者有权限。高权限工具必须在 handler 内再次校验身份、租户、资源归属与配额，并只把允许自动执行的工具注册给模型。
+- `callRemoteAgent()` 是独立客户端能力，只依赖 `ai.init()`，不要求配置 Agent Card 或注册本地 executor。它拒绝非 HTTP(S) 和 URL 内嵌凭据，但应用仍必须对远端 origin 配置白名单，并在出口代理处限制 DNS 重绑定、重定向到私网和云元数据地址。
+- 不记录完整 Prompt、工具参数、A2A headers、临时模型凭据或带 query 的远端 URL；确需审计时仅保存脱敏摘要。
+
 ## 错误处理
 
 ```ts
@@ -373,7 +459,8 @@ if (!result.success) {
 - `hai:ai:300-302`：Embedding。
 - `hai:ai:600-701`：Retrieval/RAG。
 - `hai:ai:800-805`：Knowledge。
-- `hai:ai:900-904`：Memory。
+- `hai:ai:050-059`：Audio。
+- `hai:ai:900-905`：Memory。
 - `hai:ai:980-984`：A2A。
 
 ## 测试

package/dist/{ai-audio-ws-protocol-C-V8N8YL.d.ts → ai-audio-ws-protocol-BK5753o1.d.ts}

@@ -1,8 +1,10 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
-import { aC as ChatMessage, aN as InteractionScope, J as MemoryType, bk as RagOptions, bo as ReasoningOptions, bR as ToolRegistryOperations, b6 as MemoryEntry, bB as SessionInfo, b3 as LLMOperations, bc as MemoryOperations, bj as RagOperations, bn as ReasoningOperations, c as AIConfig, d as AIConfigInput, ar as AIStoreProvider, bS as ToolsOperations, bF as StreamOperations, bu as RetrievalOperations, aZ as KnowledgeOperations, al as A2AOperations, o as AudioOperations, k as AudioFormat } from './ai-reasoning-types-BGf-x2Qj.js';
+import { aG as ChatMessage, af as InteractionScope, O as MemoryType, br as RagOptions, bv as ReasoningOptions, c2 as ToolRegistryOperations, bd as MemoryEntry, bK as SessionInfo, b6 as LLMOperations, bj as MemoryOperations, bq as RagOperations, bu as ReasoningOperations, c as AIConfig, d as AIConfigInput, av as AIStoreProvider, c4 as ToolsOperations, bO as StreamOperations, bB as RetrievalOperations, b0 as KnowledgeOperations, ap as A2AOperations, q as AudioOperations, l as AudioFormat } from './ai-reasoning-types-CslaY4xX.js';
+import * as zod from 'zod';
 import { z } from 'zod';
 import { Buffer } from 'node:buffer';
+import * as zod_v4_core from 'zod/v4/core';
 
 /**
  * @h-ai/ai — Compress 子功能类型
@@ -279,6 +281,20 @@ interface ContextManagerOptions {
      * 部分才应进入下一轮所有参与者可见的对话状态，而不是模型本想说完的全文。
      */
     turnCommit?: 'auto' | 'manual';
+    /**
+     * 并发生成策略（默认 `reject`）
+     *
+     * ContextManager 默认实行**单活动生成**：同一管理器同一时刻只允许一个未完成的
+     * `chat` / `chatStream` 轮次，避免「上一轮 AI 尚未退出，下一轮 user 消息先写入」
+     * 导致的消息乱序（user1 → user2 → assistant1）。
+     *
+     * - `reject`：已有活动生成时，新的 `chat` / `chatStream` 立即返回 `CONTEXT_BUSY` 错误。
+     * - `queue`：新请求排队，等待前一轮次进入终态（`completed` / `interrupted`）后再开始。
+     *
+     * `manual` 提交模式下，屏障持续到 `commitTurn` / `interruptTurn` 提交真实文本为止，
+     * 因此「打断当前轮次 → 立即发起下一轮」也能保证顺序正确。
+     */
+    concurrency?: 'reject' | 'queue';
     /**
      * 压缩配置（覆盖全局 compress 配置）
      *
@@ -345,6 +361,32 @@ interface ContextManagerOptions {
      */
     maxToolRounds?: number;
 }
+/**
+ * 重置管理器选项（`ContextManager.reset` 使用）
+ */
+interface ContextResetOptions {
+    /**
+     * 是否保留系统提示词（默认 `true`）
+     *
+     * 系统提示词（Persona / System Prompt）只在创建时追加一次；重置若不保留，
+     * 会连同对话历史一起清空。默认重新写入系统提示词，避免 Persona 语义丢失。
+     */
+    preserveSystemPrompt?: boolean;
+    /**
+     * 是否终止活动轮次（默认 `true`）
+     *
+     * 为 `true` 时：中断内部生成信号，使所有非终态轮次进入 `interrupted` 终态，
+     * 释放并发屏障，并阻止这些旧轮次在重置后被再次 `commitTurn` / `interruptTurn`。
+     */
+    cancelActiveTurn?: boolean;
+    /**
+     * 是否等待后台记忆提取任务完成后再清空（默认 `false`）
+     *
+     * 为 `true` 时先 `flush()` 等待正在运行的记忆提取写入完成；否则不等待
+     * （已在途的提取任务仍会自行写入记忆后端，但其结果不再影响本管理器状态）。
+     */
+    waitForMemoryTasks?: boolean;
+}
 /**
  * 单次 chat/chatStream 请求的覆盖选项
  */
@@ -358,7 +400,7 @@ interface ContextChatOptions {
     /**
      * 请求取消信号
      *
-     * 透传给底层 LLM 调用；主持人打断、用户切换等场景可 `abortController.abort()`
+     * 透传给底层 LLM 调用；打断、用户切换等场景可 `abortController.abort()`
      * 立即停止上游生成与计费。
      */
     signal?: AbortSignal;
@@ -387,8 +429,15 @@ interface ContextChatResult {
 }
 /**
  * chatStream() 产出的事件
+ *
+ * 事件序列：`turn_started` → `delta`* → `done`；中途取消（AbortSignal）时为
+ * `turn_started` → `delta`* → `cancelled`。`cancelled` 保留 turnId 与已生成文本，
+ * 调用方可用真实内容调用 `commitTurn` / `interruptTurn` 提交。
  */
 type ContextStreamEvent = {
+    type: 'turn_started';
+    turnId: string;
+} | {
     type: 'delta';
     text: string;
 } | {
@@ -410,6 +459,10 @@ type ContextStreamEvent = {
         completion_tokens: number;
         total_tokens: number;
     };
+} | {
+    type: 'cancelled';
+    turnId: string;
+    generated: string;
 };
 /**
  * 有状态上下文管理器接口
@@ -496,9 +549,15 @@ interface ContextManager {
      */
     readonly pendingMemoryTasks: number;
     /**
-     * 重置管理器（清空所有消息和摘要）
+     * 重置管理器
+     *
+     * 默认行为：终止活动轮次（进入终态并释放并发屏障）、清空消息 / 摘要 / 轮次 /
+     * 待提交轮次，并重新写入系统提示词。可通过选项调整。
+     *
+     * @param options - 重置选项（保留系统提示词 / 终止活动轮次 / 等待记忆任务）
+     * @returns 成功返回 ok(undefined)
      */
-    reset: () => void;
+    reset: (options?: ContextResetOptions) => Promise<HaiResult<void>>;
     /**
      * 获取对话轮次列表（Conversation Commit Layer）
      *
@@ -563,7 +622,7 @@ interface ContextManager {
     /**
      * 流式发送消息并获取回复（需 deps.llm 可用）
      *
-     * 产出事件序列：delta* → done
+     * 产出事件序列：turn_started → delta* → done（中途取消时 → cancelled）
      *
      * @param message - 用户消息文本
      * @param options - 单次请求覆盖选项
@@ -622,18 +681,18 @@ interface ContextOperations {
     /**
      * 重命名会话
      *
-     * @param sessionId - 会话 ID
+     * @param scope - 交互作用域（objectId + sessionId，用于多租户隔离）
      * @param title - 新标题
      * @returns 成功返回 ok(undefined)
      */
-    renameSession: (sessionId: string, title: string) => Promise<HaiResult<void>>;
+    renameSession: (scope: InteractionScope, title: string) => Promise<HaiResult<void>>;
     /**
      * 删除会话（删除会话元数据和对应的上下文数据）
      *
-     * @param sessionId - 会话 ID
+     * @param scope - 交互作用域（objectId + sessionId，用于多租户隔离）
      * @returns 成功返回 ok(undefined)
      */
-    removeSession: (sessionId: string) => Promise<HaiResult<void>>;
+    removeSession: (scope: InteractionScope) => Promise<HaiResult<void>>;
 }
 
 /**
@@ -1316,6 +1375,8 @@ declare const HaiAIError: {
     readonly TOOL_VALIDATION_FAILED: _h_ai_core.HaiErrorDef;
     readonly TOOL_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
     readonly TOOL_TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly TOOL_ALREADY_REGISTERED: _h_ai_core.HaiErrorDef;
+    readonly TOOL_FORBIDDEN: _h_ai_core.HaiErrorDef;
     readonly REASONING_FAILED: _h_ai_core.HaiErrorDef;
     readonly REASONING_MAX_ROUNDS: _h_ai_core.HaiErrorDef;
     readonly REASONING_STRATEGY_NOT_FOUND: _h_ai_core.HaiErrorDef;
@@ -1357,6 +1418,7 @@ declare const HaiAIError: {
     readonly CONTEXT_BUDGET_EXCEEDED: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_TURN_NOT_FOUND: _h_ai_core.HaiErrorDef;
     readonly CONTEXT_TURN_INVALID_STATE: _h_ai_core.HaiErrorDef;
+    readonly CONTEXT_BUSY: _h_ai_core.HaiErrorDef;
     readonly STORE_FAILED: _h_ai_core.HaiErrorDef;
     readonly STORE_NOT_AVAILABLE: _h_ai_core.HaiErrorDef;
     readonly SESSION_NOT_FOUND: _h_ai_core.HaiErrorDef;
@@ -1377,8 +1439,8 @@ interface AIInitOptions {
     /**
      * 自定义存储 Provider
      *
-     * 提供后 AI 模块将使用此 Provider 而非默认的 reldb+vecdb 实现，
-     * 此时不需要提前初始化 reldb/vecdb。
+     * 提供后 AI 模块将使用此 Provider，而不采用自动选择的存储实现。
+     * 未提供时：reldb + vecdb 已初始化则使用持久化 DB Provider，否则使用进程内临时 Provider。
      */
     storeProvider?: AIStoreProvider;
 }
@@ -1460,15 +1522,6 @@ interface AIFunctions {
     readonly audio: AudioOperations;
 }
 
-/**
- * @h-ai/ai — 统一语音 WebSocket 协议
- *
- * 定义浏览器 / 远程客户端与 `@h-ai/serv` 语音入口之间的统一 WebSocket 消息协议。
- * 客户端与服务端共享此协议，客户端不接收任何厂商原生事件；音频以二进制帧传输，
- * 控制与文本以 JSON 帧传输。
- * @module audio/ai-audio-ws-protocol
- */
-
 /** 统一语音入口的默认路径（相对 API 前缀） */
 declare const AUDIO_WS_PATH = "/ai/audio";
 /**
@@ -1507,6 +1560,8 @@ interface AudioWsStartMessage {
 /** 文本输入帧（合成操作时携带待合成文本） */
 interface AudioWsTextMessage {
     type: 'text';
+    /** 调用方分配的稳定文本段 ID */
+    segmentId: string;
     /** 待合成文本片段 */
     text: string;
 }
@@ -1516,6 +1571,74 @@ interface AudioWsDoneMessage {
 }
 /** 客户端 JSON 控制消息（音频输入以二进制帧发送，不走 JSON） */
 type AudioWsClientMessage = AudioWsStartMessage | AudioWsTextMessage | AudioWsDoneMessage;
+/** 合法音频格式 */
+declare const AudioFormatSchema: zod.ZodEnum<{
+    pcm16: "pcm16";
+    wav: "wav";
+    mp3: "mp3";
+    opus: "opus";
+}>;
+/** 单个字符串控制字段最大长度（model / language / voice / instruction 等） */
+/** 会话起始帧 Schema */
+declare const AudioWsStartMessageSchema: zod.ZodObject<{
+    type: zod.ZodLiteral<"start">;
+    operation: zod.ZodEnum<{
+        transcribe: "transcribe";
+        synthesize: "synthesize";
+    }>;
+    stream: zod.ZodOptional<zod.ZodBoolean>;
+    model: zod.ZodOptional<zod.ZodString>;
+    language: zod.ZodOptional<zod.ZodString>;
+    contextHints: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
+    voice: zod.ZodOptional<zod.ZodString>;
+    instruction: zod.ZodOptional<zod.ZodString>;
+    format: zod.ZodOptional<zod.ZodEnum<{
+        pcm16: "pcm16";
+        wav: "wav";
+        mp3: "mp3";
+        opus: "opus";
+    }>>;
+    sampleRate: zod.ZodOptional<zod.ZodNumber>;
+    channels: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodLiteral<1>, zod.ZodLiteral<2>]>>;
+}, zod_v4_core.$strip>;
+/** 文本输入帧 Schema（segmentId 非空且长度受限） */
+declare const AudioWsTextMessageSchema: zod.ZodObject<{
+    type: zod.ZodLiteral<"text">;
+    segmentId: zod.ZodString;
+    text: zod.ZodString;
+}, zod_v4_core.$strip>;
+/** 输入结束帧 Schema */
+declare const AudioWsDoneMessageSchema: zod.ZodObject<{
+    type: zod.ZodLiteral<"done">;
+}, zod_v4_core.$strip>;
+/** 客户端 JSON 控制消息 Schema（按 type 判别） */
+declare const AudioWsClientMessageSchema: zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+    type: zod.ZodLiteral<"start">;
+    operation: zod.ZodEnum<{
+        transcribe: "transcribe";
+        synthesize: "synthesize";
+    }>;
+    stream: zod.ZodOptional<zod.ZodBoolean>;
+    model: zod.ZodOptional<zod.ZodString>;
+    language: zod.ZodOptional<zod.ZodString>;
+    contextHints: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
+    voice: zod.ZodOptional<zod.ZodString>;
+    instruction: zod.ZodOptional<zod.ZodString>;
+    format: zod.ZodOptional<zod.ZodEnum<{
+        pcm16: "pcm16";
+        wav: "wav";
+        mp3: "mp3";
+        opus: "opus";
+    }>>;
+    sampleRate: zod.ZodOptional<zod.ZodNumber>;
+    channels: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodLiteral<1>, zod.ZodLiteral<2>]>>;
+}, zod_v4_core.$strip>, zod.ZodObject<{
+    type: zod.ZodLiteral<"text">;
+    segmentId: zod.ZodString;
+    text: zod.ZodString;
+}, zod_v4_core.$strip>, zod.ZodObject<{
+    type: zod.ZodLiteral<"done">;
+}, zod_v4_core.$strip>], "type">;
 /** 语音起止事件（识别操作时服务端 VAD 检测到语音开始 / 结束） */
 interface AudioWsSpeechMessage {
     type: 'speech_started' | 'speech_stopped';
@@ -1528,6 +1651,27 @@ interface AudioWsTranscriptMessage {
     /** 是否为该语句的最终结果 */
     final: boolean;
 }
+/**
+ * 合成文本段开始；后续二进制帧均属于该段，直到收到对应的 `segment_done`。
+ *
+ * 携带服务端解析 Provider 后的真实输出音频参数，供浏览器正确标注音频格式。
+ */
+interface AudioWsSegmentStartedMessage {
+    type: 'segment_started';
+    segmentId: string;
+    text: string;
+    /** 真实输出音频格式（来自服务端解析后的 Provider 输出，非客户端请求参数） */
+    format: AudioFormat;
+    /** 采样率（Hz）；pcm16 等裸音频必填 */
+    sampleRate?: number;
+    /** 声道数（默认单声道） */
+    channels?: 1 | 2;
+}
+/** 合成文本段的音频已全部发送。 */
+interface AudioWsSegmentDoneMessage {
+    type: 'segment_done';
+    segmentId: string;
+}
 /** 错误帧（领域语义错误码，不暴露厂商协议细节） */
 interface AudioWsErrorMessage {
     type: 'error';
@@ -1541,6 +1685,6 @@ interface AudioWsEndMessage {
     type: 'end';
 }
 /** 服务端 JSON 消息（合成音频以二进制帧返回，不走 JSON） */
-type AudioWsServerMessage = AudioWsSpeechMessage | AudioWsTranscriptMessage | AudioWsErrorMessage | AudioWsEndMessage;
+type AudioWsServerMessage = AudioWsSpeechMessage | AudioWsTranscriptMessage | AudioWsSegmentStartedMessage | AudioWsSegmentDoneMessage | AudioWsErrorMessage | AudioWsEndMessage;
 
-export { type OutputFormat as $, type AIFunctions as A, type ConversationTurn as B, type CompressionStrategy as C, type ConversationTurnStatus as D, type EmbeddingItem as E, type EmbeddingOperations as F, type EmbeddingProvider as G, HaiAIError as H, type EmbeddingRequest as I, type EmbeddingResponse as J, type FileOperations as K, type FileParseMethod as L, type FileParseOptions as M, type FileParseRequest as N, type FileParseResult as O, type MCPContext as P, type MCPOperations as Q, type MCPPrompt as R, type MCPPromptArgument as S, type MCPPromptContent as T, type MCPPromptMessage as U, type MCPProvider as V, type MCPResource as W, type MCPResourceContent as X, type MCPToolDefinition as Y, type MCPToolHandler as Z, type McpServerOptions as _, type AIInitOptions as a, type PersonaOperations as a0, type PersonaProfile as a1, type PersonaProfileInput as a2, type PersonaProfileUpdate as a3, type PersonaScopeOptions as a4, type RerankDocument as a5, type RerankItem as a6, type RerankOperations as a7, type RerankRequest as a8, type RerankResponse as a9, type SummaryOperations as aa, type SummaryOptions as ab, type SummaryResult as ac, type TokenOperations as ad, AUDIO_WS_PATH as b, type AudioWsClientMessage as c, type AudioWsDoneMessage as d, type AudioWsEndMessage as e, type AudioWsErrorMessage as f, type AudioWsServerMessage as g, type AudioWsSpeechMessage as h, type AudioWsStartMessage as i, type AudioWsTextMessage as j, type AudioWsTranscriptMessage as k, CompressionStrategySchema as l, type AIMCPFunctionsDeps as m, type CommitTurnInput as n, type CompressOperations as o, type CompressOptions as p, type CompressResult as q, type ConsolidateOptions as r, type ConsolidateResult as s, type ContextChatOptions as t, type ContextChatResult as u, type ContextDeps as v, type ContextManager as w, type ContextManagerOptions as x, type ContextOperations as y, type ContextStreamEvent as z };
+export { type MCPPromptArgument as $, type AIFunctions as A, type ContextChatOptions as B, type CompressionStrategy as C, type ContextChatResult as D, type ContextDeps as E, type ContextManager as F, type ContextManagerOptions as G, HaiAIError as H, type ContextOperations as I, type ContextResetOptions as J, type ContextStreamEvent as K, type ConversationTurn as L, type McpServerOptions as M, type ConversationTurnStatus as N, type EmbeddingItem as O, type EmbeddingOperations as P, type EmbeddingProvider as Q, type EmbeddingRequest as R, type EmbeddingResponse as S, type FileOperations as T, type FileParseMethod as U, type FileParseOptions as V, type FileParseRequest as W, type FileParseResult as X, type MCPContext as Y, type MCPOperations as Z, type MCPPrompt as _, type AIInitOptions as a, type MCPPromptContent as a0, type MCPPromptMessage as a1, type MCPProvider as a2, type MCPResource as a3, type MCPResourceContent as a4, type MCPToolDefinition as a5, type MCPToolHandler as a6, type OutputFormat as a7, type PersonaOperations as a8, type PersonaProfile as a9, type PersonaProfileInput as aa, type PersonaProfileUpdate as ab, type PersonaScopeOptions as ac, type RerankDocument as ad, type RerankItem as ae, type RerankOperations as af, type RerankRequest as ag, type RerankResponse as ah, type SummaryOperations as ai, type SummaryOptions as aj, type SummaryResult as ak, type TokenOperations as al, AUDIO_WS_PATH as b, AudioFormatSchema as c, type AudioWsClientMessage as d, AudioWsClientMessageSchema as e, type AudioWsDoneMessage as f, AudioWsDoneMessageSchema as g, type AudioWsEndMessage as h, type AudioWsErrorMessage as i, type AudioWsSegmentDoneMessage as j, type AudioWsSegmentStartedMessage as k, type AudioWsServerMessage as l, type AudioWsSpeechMessage as m, type AudioWsStartMessage as n, AudioWsStartMessageSchema as o, type AudioWsTextMessage as p, AudioWsTextMessageSchema as q, type AudioWsTranscriptMessage as r, CompressionStrategySchema as s, type AIMCPFunctionsDeps as t, type CommitTurnInput as u, type CompressOperations as v, type CompressOptions as w, type CompressResult as x, type ConsolidateOptions as y, type ConsolidateResult as z };