@tbox.cn/app-agent-sdk-server 0.1.0

package/dist/server/index.d.ts

@@ -0,0 +1,2282 @@
+import { HandlerRegistry, ServerContext, HandlerResult, LocalSkill, PreToolDef, RegistryTool, PreToolHistoryTurn, PreToolRouting, WsAuthenticator, ScopeSessionRegistry, AuthRuntime, TboxTtsClient } from '@tbox.cn/app-sdk-server';
+export * from '@tbox.cn/app-sdk-server';
+export { TtsVoiceConfig } from '@tbox.cn/app-sdk-server';
+export { InferModuleCards } from '@tbox.cn/app-sdk-core';
+import * as _tbox_cn_app_contracts from '@tbox.cn/app-contracts';
+import { SendMessageMediaItem, SkillRecord, ServerEvent, PreToolRecord, MemoryKind, MemoryRecord, MemoryStore, MemoryStoreCapabilities, MemoryErrorCode, RequestContext as RequestContext$1, CardMeta, CardSnapshot, Identity, ExternalCredentials, HelloAckChatConfig, TboxCardPayload } from '@tbox.cn/app-contracts';
+import * as _mastra_core_tools from '@mastra/core/tools';
+import { Tool } from '@mastra/core/tools';
+export { Tool, createTool } from '@mastra/core/tools';
+import { ObservabilityExporter, TracingEvent, SpanType } from '@mastra/core/observability';
+import { ModelMessage, LanguageModel } from 'ai';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ZodTypeAny, z } from 'zod';
+import { SkillInput } from '@mastra/core/skills';
+import { RequestContext } from '@mastra/core/request-context';
+import * as ws from 'ws';
+import { WebSocket } from 'ws';
+import * as http from 'http';
+import * as _mastra_core_schema from '@mastra/core/schema';
+import * as node_modules__tbox_cn_app_sdk_server_src_upstream from 'node_modules/@tbox.cn/app-sdk-server/src/upstream';
+import { Router, Express } from 'express';
+import * as _tbox_cn_agent_plugin from '@tbox.cn/agent-plugin';
+import { ConfiguredPluginToolReference, PluginRunResult } from '@tbox.cn/agent-plugin';
+
+declare class TboxTraceExporter implements ObservabilityExporter {
+    name: string;
+    private seq;
+    private correlationByTraceId;
+    exportTracingEvent(event: TracingEvent): Promise<void>;
+    emitCustomSpan(opts: {
+        spanId: string;
+        traceId: string;
+        parentSpanId?: string;
+        type: SpanType;
+        name: string;
+        startTime: Date;
+        endTime: Date;
+        input?: unknown;
+        output?: unknown;
+        metadata?: Record<string, unknown>;
+        errorInfo?: {
+            message: string;
+            type?: string;
+            stack?: string;
+        };
+        requestId: string;
+        conversationId?: string;
+        sessionId?: string;
+    }): void;
+    emitErrorSpan(opts: {
+        requestId: string;
+        conversationId?: string;
+        sessionId?: string;
+        name?: string;
+        error: unknown;
+        metadata?: Record<string, unknown>;
+    }): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private resolveCorrelation;
+}
+/** 模块级单例：让 presenter 等业务代码能 emit 自定义 span。 */
+declare const tboxTraceExporter: TboxTraceExporter;
+
+/**
+ * intent-framework：意图识别框架（003 §3.3，hybrid 模式）。
+ * SDK 提供框架（路由/匹配），意图表由应用源码提供（业务域轴）。
+ */
+
+interface IntentRoute {
+    /** 意图唯一标识 */
+    id: string;
+    /** 关键词（BM25 分词打分）；空数组表示仅 LLM 分类 */
+    keywords: string[];
+    /** 命中的 handlerId */
+    handlerId: string;
+    /** 默认 action */
+    action: string;
+    /**
+     * 匹配语义（洋葱路由 L1/L3 分层）：
+     * - 'exact'：整句全等命中（trim 后 ===）且优先于 BM25——适用于按钮/选择器发出的
+     *   固定整句值（如会员偏好按钮）；此类值绝不进入 BM25 词袋（相似查询误命中，F3）。
+     * - 'prefix'：模板句头前缀命中（trim 后 startsWith）且优先于 BM25——适用于模块生成的
+     *   动态模板句（如卡片导航「查看「X」…」），头全等 + handler 内模板全等校验双层把关；
+     *   与 exact 同不入 BM25 词袋，prefix 误延展由 handler 洋葱守卫放行（不吞轮）。
+     * - 'bm25'（缺省）：关键词词袋模糊命中。**顶层语义分类职责归 skill 路由与 LLM 工具编排**
+     *   （BM25 单标签 + handler 硬短路会截断复合句）——顶层声明_bm25 为 legacy，装配期 warn；
+     *   合法存续域 = handler 内部二层 action 分辨（域内、带兜底、无跨域截断面）。
+     */
+    match?: 'exact' | 'prefix' | 'bm25';
+}
+/**
+ * 意图匹配（统一检索层，无 LLM 依赖的确定性路径）：确定性档优先——L1 exact 整句全等、
+ * prefix 模板句头前缀（均 trim 容差、不入 BM25 索引）；L3 BM25 打分 + 命中规则从严
+ * （长词 OR ≥2 token），取规则通过的首个 score top（并列 id 字典序，确定性）。
+ * 未命中 → undefined（调用方走 LLM）。空 keywords route 不参与（仅 LLM 分类）。
+ */
+declare function matchIntent(routes: IntentRoute[], text: string): IntentRoute | undefined;
+/**
+ * 意图分发器：命中关键词 → HandlerRegistry.dispatch。
+ * 未命中返回空结果（由调用方走 LLM 自由回复）。
+ */
+declare function createIntentDispatcher(routes: IntentRoute[], handlers: HandlerRegistry): (text: string, ctx: ServerContext, payload?: unknown) => Promise<HandlerResult | undefined>;
+
+/**
+ * 加载本地 skill 目录（009 D7）：
+ * `dir/<skill-name>/SKILL.md`（frontmatter：name/description/metadata.routingTerms）+ `references/**​/*.md`（递归）。
+ * - dir 不存在（ENOENT——应用级/模块级 skills 目录均为可选形态）→ [] + info 静默跳过；
+ *   无权限等意外 IO → [] + warn。
+ * - 逐 skill try/catch：单个目录异常（缺 SKILL.md / IO 失败）跳过 + warn，不阻断其余。
+ * - 穿越防护：references 解析后相对路径以 `..` 开头或为绝对路径 → 跳过 + warn。
+ * - name 校验失败 → 跳过 + warn（防 reminder 解析注入）。
+ */
+declare function loadLocalSkills(dir: string): Promise<LocalSkill[]>;
+/**
+ * 唯一转换点（009 D5）：LocalSkill → mastra InlineSkill。
+ * 仅 progressive 注册路径使用；accelerated 模式不触达 mastra skill 层。
+ * references 内存化（__referenceContents），运行期零文件系统暴露。
+ */
+declare function toMastraSkill(skill: LocalSkill): SkillInput;
+/**
+ * 模块包级文件 skill 加载（009 模块文件化能力，底层下沉）：
+ * 包名解析定位模块包根 → 包根/skills 目录（SKILL.md 格式，复用 loadLocalSkills）。
+ * dev / dist / 发布态 / 应用 bundle 形态路径恒等（单一策略，零包名形态约定）：
+ * - createRequire 以调用方文件为基准向上解析消费方 node_modules——
+ *   dev（workspace link）、模块 dist、应用 build dist（bundle 内联后仍从 bundle
+ *   位置向上解析）、发布态（node_modules 内模块位置）均命中；
+ * - 前置：目标模块 package.json exports 须含 `"./package.json"`（标准惯例，
+ *   doctor pack-exports 兼容；codegen 展开与本地骨架已默认保留）。
+ * - 恒 resolve（失败降级 [] + 可行动诊断 warn，不 throw）：模块顶层 await 调用时
+ *   不会因加载失败中断应用启动链。
+ */
+declare function loadModuleSkills(packageName: string, importMetaUrl: string): Promise<LocalSkill[]>;
+
+/** 默认文件 URL 前缀（可被 createChatEngine 的 fileUrlPrefix 覆盖） */
+declare const DEFAULT_FILE_URL_PREFIX = "https://mdn.alipayobjects.com/tcmarket/afts/file/";
+type ImagePart = {
+    type: 'image';
+    image: URL;
+    mimeType?: string;
+};
+type TextPart = {
+    type: 'text';
+    text: string;
+};
+type ContentPart = ImagePart | TextPart;
+/**
+ * 将用户输入文本 + 媒体附件组装为 LLM 可用的 content。
+ * - 图片 → image URL part（多模态）
+ * - 其他文件 → 文字占位符
+ * - 无媒体 → 纯文本
+ */
+declare function buildUserContent(text: string, mediaItems?: SendMessageMediaItem[], fileUrlPrefix?: string): string | ContentPart[];
+/**
+ * 轮级注入块组（composeTurnUserContent 输入）。
+ * 块语义见 platform-instructions 注入块协议节（四类块清单）。
+ */
+interface TurnReminderBlocks {
+    /** card-decision 决策提醒块（modelEnabled 轮恒注入） */
+    cardDecision?: string;
+    /** pre-tool 预执行数据块（每 done 工具一个，按完成序） */
+    preToolBlocks?: string[];
+    /** memory 背景数据块（recall 命中轮） */
+    memoryBlock?: string;
+    /** skill 块（完整 SOP 注入或去重轮 recap） */
+    skillBlock?: string;
+}
+/**
+ * 轮级 user 内容统一组装（W3，2026-09-01；顺序契约唯一真源）：
+ * `[card-decision → preTool₁..n → memory → skill → userText]`。
+ * 分组逻辑：协议指令 → 本轮数据族（前景 preTool + 背景 memory 相邻）→ 域规程（紧邻正文，
+ * 注意力就近）→ 正文。chat() 与 submitForm 单点共用；与 buildInjectedUserContent 字节级同构
+ * （仅传 skillBlock 时产物恒等——测试钉死）。
+ * 无块时 string 原样返回（handler 直出轮 history 形态不变）；空 string → 无正文 part
+ * （submitForm reminder 消息形态）。
+ */
+declare function composeTurnUserContent(blocks: TurnReminderBlocks, userContent: string | ContentPart[]): string | ContentPart[];
+/**
+ * 从媒体附件中提取图片的完整 URL 列表。
+ * 用于保存消息时记录 multiModalInputs。
+ */
+declare function extractImageUrls(mediaItems?: SendMessageMediaItem[], fileUrlPrefix?: string): string[];
+
+/**
+ * 宽泛路由词（公开导出，skill-router re-export 保持公开面）：
+ * 词素展开（词 + 拆字）后整体不入索引——高频泛词不参与路由（原降权语义升级为排除）。
+ */
+declare const BROAD_ROUTING_TERMS: ReadonlySet<string>;
+
+/**
+ * 本地 skill 双模式（009 D2）：accelerated（默认，本地路由注入）/ progressive（原生渐进）。
+ * 全局配置、运行期恒定——非每轮动态，保证 Agent 构造（system prompt + 工具列表）恒态 → 前缀缓存稳定。
+ */
+declare const DEFAULT_SKILL_MODE: "accelerated";
+type SkillMode = 'accelerated' | 'progressive';
+/** 解析环境变量（TBOX_SKILL_MODE）；非法值 → 默认 + warn（确定性：静默降级为默认） */
+declare function resolveSkillMode(value?: string): SkillMode;
+/**
+ * 公开路由入口（纯函数）：BM25 全量打分 + 命中规则（长词 OR ≥2 token）取最高分。
+ * bigram 全切分下词目 ⊆ 查询 ⇒ 词目内相邻二字恒为查询 token（长词规则直过），
+ * 原词目原文直命中兜底通道已无必要（2026-08-26 统一检索层移除）。空文本/空 skills → undefined。
+ */
+declare function selectSkill(text: string, skills: LocalSkill[]): LocalSkill | undefined;
+declare function scanInjectedSkills(history: ModelMessage[]): Set<string>;
+/** 构建 reminder 块（SOP 全文 + references，一次到位 → 零 skill_read 轮次） */
+declare function buildSkillReminder(skill: LocalSkill): string;
+/**
+ * 注入决策单点（纯函数，供日志/诊断与 applySkillReminder 共用）：
+ * - injected：BM25 最高分 skill 未注入过且命中规则 → 注入；
+ * - duplicate：BM25 最高分 skill 已注入过（同域多轮）→ 去重拦截，不寻次高分——
+ *   防止主 skill 已注入后次高分 skill 趁虚误注入（跨域劫持 bug 修复）；
+ * - none：全量路由未命中（正常闲聊，日志层静默）。
+ *
+ * 注意：复合场景（本轮文本同时命中两个不同域的词，如「帮我找个停车场然后领张优惠券」）
+ * 仅注入最高分 skill；第二域在下一轮再次命中时才注入——这与旧行为一致（旧逻辑在首轮也只能注入一个）。
+ */
+type SkillInjectionDecision = {
+    action: 'injected';
+    skill: LocalSkill;
+} | {
+    action: 'duplicate';
+    skill: LocalSkill;
+} | {
+    action: 'none';
+};
+declare function decideSkillInjection(input: {
+    /** 原始用户文本（selectSkill 打分输入） */
+    text: string;
+    /** 会话历史（不含本轮） */
+    history: ModelMessage[];
+    /** 可用 skills */
+    skills: LocalSkill[];
+}): SkillInjectionDecision;
+/**
+ * 注入组装（纯函数，009 D3 提取）：reminder 块恒前置 + userContent 双形态归一化
+ * （string → [{type:'text',text}]）。chat() 与 applySkillReminder 同源共用（字节级同构红线）。
+ */
+declare function buildInjectedUserContent(skill: LocalSkill, userContent: string | ContentPart[]): ContentPart[];
+/** 构建 recap 块（去重轮注入；短于完整 SOP，会话级恒定文案 + skill 名） */
+declare function buildSkillRecapReminder(skill: LocalSkill): string;
+/**
+ * 去重重申组装（纯函数）：recap 块恒前置 + 双形态归一化。
+ * chat() 与 applySkillReminder 同源共用（与 buildInjectedUserContent 字节级同构红线对齐）。
+ */
+declare function buildRecapUserContent(skill: LocalSkill, userContent: string | ContentPart[]): ContentPart[];
+/**
+ * 加速模式注入组合（纯函数，不 push）：
+ * - 调用契约：history 不含本轮（调用方保证在 history.push 前调用）；
+ * - 决策经 decideSkillInjection 单点（候选集排除已注入 skill 后再路由：主 skill 已注入时，
+ *   复合文本中次高分未注入 skill 仍可命中注入）；
+ * - injected → buildInjectedUserContent（完整 SOP reminder 恒前置）；
+ * - duplicate → buildRecapUserContent（会话级恒真约束重申块前置——完整 SOP 去重，
+ *   恒真约束不塌陷；recap 块同标签形状 → 后续轮仍稳定判重）；
+ * - none → 原样返回。
+ */
+declare function applySkillReminder(input: {
+    /** 原始用户文本（selectSkill 打分输入，与 buildUserContent 同源） */
+    text: string;
+    /** buildUserContent 产物 */
+    userContent: string | ContentPart[];
+    /** 会话历史（不含本轮） */
+    history: ModelMessage[];
+    /** 可用 skills */
+    skills: LocalSkill[];
+}): string | ContentPart[];
+/**
+ * 前端 skill 加载表达事件序列（009 D9，纯函数，不发射）：
+ * - 合成 tool-call 序列 [START, ARGS, END, RESULT]，toolCallName = SKILL_TOOL_CALL_NAME；
+ * - args/result 经 contracts buildSkillToolCallPayload 单点序列化（与历史表达字节级同构）；
+ * - 调用契约：RUN_STARTED 之后、模型流之前发射（前端 isGenerating 门控满足；
+ *   thinking 气泡承载，TEXT_MESSAGE_START 的 id 替换保留 toolCalls）；
+ * - toolCallId 由调用方生成传入（可测性）；RESULT.messageId 为 AG-UI 必填字段。
+ */
+declare function buildSkillToolCallEvents(skill: SkillRecord, toolCallId: string, messageId: string): ServerEvent[];
+
+/**
+ * 尽早工具执行管线（PR-2）：模型流中工具参数完整即预执行（fire-and-forget），
+ * mastra foreach 执行工具时经 take-once 缓存命中返回。
+ *
+ * 机制链：模型装饰器（Object.create 原型委托 + doStream 流 TransformStream 只观测透传）
+ * → 边界封板（tool-input-start（前序槽）/ tool-input-end（同 id 槽）/ flush + JSON.parse
+ * 验证——禁「闭合即 fire」：嵌套前缀歧义，裁定 1）→ fire 预执行（hardened Tool 层 execute，
+ * 校验/sanitize/context 重组/output 校验与 foreach 同构，裁定 3）→
+ * Map<toolCallId, Promise> take-once 缓存 → mastra foreach 命中（tool-cards hit 点）。
+ *
+ * 正确性安全网：args 漂移（交错流尾巴 / 终态 input ≠ 快照）→ invalidate 作废 →
+ * 纯丢弃（hit 点在 capture 层，drift 错误参数永不进卡池，INV4）→ mastra 原样执行（现状路径）。
+ *
+ * 不变量：INV1 单向降级（任何异常/无 scope/白名单外 → 字节级现状）· INV2 执行上界
+ * （同 toolCallId 预执行 ≤1 + 生效执行 =1）· INV3 正确性>缓存（漂移恒作废）·
+ * INV5 作废先于查找（装饰器 flush 在上游关流时触发，先于 foreach）。
+ * ⚠ mastra 内部契约依赖（升级哨兵测试锁定）：AISDKV6LanguageModel 纯委托 doStream /
+ * toolOptions 携带 toolCallId / foreach 并发语义 / Tool 校验层。全部依赖的判定过程见 Agent Note
+ * （2026-09-04-parallel-tool-execution）。
+ *
+ * 观测（2026-09-05 强化）：tool_preexec 事件 outcome × trigger × reason 归因——
+ * fired/hit/invalidated/skip × next-start/input-end/flush；hit 为区间行
+ * （startedAt=fire 时刻，durMs=advance）。双窗正交：preexec 窗 [fire, hit] 与
+ * agent 窗（tool_call/tool_result，_toolStarts 计时）互不覆写；联窗指标
+ * （execDur/saved/coverage）离线经 audit-toolcall-stream.mjs 计算。
+ */
+
+/**
+ * 尽早执行白名单标记（symbol 经 getOwnPropertyDescriptors 穿透 harden/capture 两层浅克隆；
+ * 不进 JSON 序列化面）。定义单源在本文件（tool-cards hit 点与本管线同源，避免
+ * tool-cards ← → create-module-tool 模块环）；模块侧 API（withEarlyExecution）经
+ * create-module-tool 转出。
+ */
+declare const EARLY_EXECUTION_MARKER: unique symbol;
+
+/**
+ * 模块侧工具创建封装（P3 评审 P0-1 修复）。
+ * 模块（module-* 与 scenario-* 模块）创建 LLM 工具时经此入口引用 @mastra/core，
+ * 避免模块直接 import 框架内部包导致 pnpm 解析出第二个 @mastra/core 实例
+ * （单例铁律，002 §10.1）。@mastra/core 由 app-sdk 唯一持有（dependencies），
+ * 经本文件 re-export，模块只需依赖 @tbox.cn/app-sdk。
+ */
+
+/**
+ * 任意具体化实例的 Mastra Tool（泛型擦除别名，agent 侧专用）。
+ * Tool 泛型参数（input/output/context/id...）在各业务工具间反变，用 unknown 默认值
+ * 无法接受具体工具实例；统一用 any 擦除泛型差异，具体 schema 由工具自身约束。
+ * 结构兼容通用侧 RegistryTool（@tbox.cn/app-sdk-server）——注册表存储面按结构接收。
+ */
+type AnyTool = Tool<any, any, any, any, any, string, any>;
+/** internalTool 标记（symbol 经 getOwnPropertyDescriptors 穿透 harden/capture 两层浅克隆；不进 JSON 序列化面） */
+declare const INTERNAL_TOOL: unique symbol;
+/**
+ * 内部工具标记（B3）：标记后的工具经 omitInternal 从 Agent 模型工具集中剔除——
+ * 模型看不到（工具列表更短 → 静态前缀更小），但 preTool 预执行路径照常工作
+ * （wrappedPreTools 从**源 map** 取 capture 包装实例，与 Agent 面解耦）。
+ *
+ * ⚠ 原实例标记（不返回新对象）：build-engine D9 实例一致性校验（tools[def.tool.id] === def.tool）
+ * 要求声明、注册、标记三处同一实例——返回新对象会致 preTool 声明静默失配被丢。
+ * description 约定：内部工具 description 须含「模型勿调用」标注（doctor 第 24 条双向校验）。
+ */
+declare function internalTool<T extends object>(tool: T): T;
+
+/**
+ * 尽早执行白名单标记（原实例标记，禁拷贝——normalizePreTools D9 实例一致性
+ * （tools[tool.id] === def.tool）要求引用恒等，返回新对象会致 preTool 声明静默失配被丢）。
+ *
+ * 标记后的工具：模型流中该调用参数文本完整（边界封板 + JSON.parse 验证）即由引擎
+ * **异步预执行**（execCtx 仅含 requestContext + toolCallId + abortSignal），mastra foreach
+ * 消费缓存返回；参数漂移时预执行作废、foreach 原样重执行（正确性由引擎保证）。
+ *
+ * 使用规约（modules.md 同步）：
+ * - 仅标记**只读查询类**工具（幂等、无副作用、同一参数可重复执行）；
+ *   支付/表单提交/internalTool/带 backgroundConfig 或 suspend 的工具禁标记；
+ * - execute 禁依赖 requestContext 之外的 execCtx 字段（messages/llmContext 等预执行态缺席）；
+ * - 预执行的失败/生效语义与 foreach 完全同构（硬化的 Tool 校验层全体生效）。
+ */
+declare function withEarlyExecution<T extends object>(tool: T): T;
+/**
+ * 剔除内部工具（B3）：返回**新 Record**（不变量：源 map 只读——chat-engine wrappedPreTools
+ * 的 capture 包装实例取自源 map，过滤后的副本不影响 preTool 路径工具解析）。
+ * omitInternal(空集) = 恒等（回滚休眠态：不标记任何工具时行为与旧版逐字节一致）。
+ */
+declare function omitInternal<T extends object>(tools: Record<string, T>): Record<string, T>;
+/**
+ * 出卡工具 description 预告知（W2，2026-09-01）：追加单源标准句
+ * 「命中数据时结果附可展示卡片（cards）。」（actions: true 追加「操作入口在卡片上。」）。
+ * 动机：出卡工具 description 零「卡」字样时，模型在调用前无从知晓结果含卡片候选
+ * → 直答不调用 → 候选池空 → 无卡（R3）；一句话预告知在调用决策点建立预期。
+ *
+ * 使用规约（modules.md 同步）：模块创建点**单点 wrap**；工具注册与 definePreTool 声明
+ * 均使用 wrapped 实例（normalizePreTools 实例一致性校验兼容）；禁在 wrap 句之外
+ * 自行描述出卡机制（标签语法/cardType 目录——机制归平台段单源）。
+ * 浅拷贝（getOwnPropertyDescriptors）不改原实例；id/execute/inputSchema 引用保持。
+ */
+declare function withCardEmissionHint<T extends {
+    description?: string;
+}>(tool: T, opts?: {
+    actions?: boolean;
+}): T;
+
+/**
+ * LLM 入参卫生：递归清除对象键值位的 null 与字符串 "null"/"undefined"（trim + 大小写不敏感）。
+ * 刻意不做 JSON.parse——D11 字符串化规范下数字串（page:"1"）必须保持字符串；
+ * 数组元素与其他字符串一律不动（"null" 仅在对象键值位是污染形态）。
+ * 装配期经 build-engine hardenToolsForLlm 以 z.preprocess 注入，模块无感知。
+ */
+declare function sanitizeLlmToolInput(input: unknown): unknown;
+/** sanitize 包装（导出供 harden 与单测共用；非 zod schema 由调用方探测） */
+declare function withLlmInputSanitize<T extends ZodTypeAny>(schema: T): T;
+
+/** 投影截断上限（最近 N 条；10 轮对话决策余量） */
+declare const PRE_TOOL_HISTORY_LIMIT = 20;
+/** 单工具总预算缺省（decide + execute 共享；0 = 整体禁用） */
+declare const DEFAULT_PRE_TOOL_TIMEOUT_MS = 2000;
+/** 单轮预执行工具数上限（常量，非配置项——防上下文/延迟爆炸） */
+/** 单轮预执行截断上限（2026-09-01 4→5：核心路径 preTool 扩容——parking-fee + listCoupons 加入后六族，
+ *  2026-09-03 always 三席（mall-context/floor-shops/customer-service-faq v3）+ keywords 竞争；
+ *  全命中轮仍按序裁至 5） */
+declare const DEFAULT_MAX_PRE_TOOLS_PER_RUN = 5;
+/** 超时错误（与执行失败同语义：不入 LLM 上下文，前端 error 态） */
+declare class PreToolTimeoutError extends Error {
+    constructor();
+}
+/**
+ * 解析 TBOX_PRE_TOOL_TIMEOUT_MS（同 resolveSkillMode 形态）：
+ * '0' → 0（禁用）；非负整数 → 生效；非法/缺省 → 默认 + warn。
+ */
+declare function resolvePreToolTimeout(value?: string): number;
+/**
+ * 键序稳定序列化（B3 session-args dedup 键构造）：
+ * 递归对象键按字典序排序 + 丢弃 undefined 值字段——同参不同键序/undefined 噪声 → 同键。
+ * 数组保序（顺序语义）；循环引用防御性断裂（[Circular]）。
+ * 前提：入参为 JSON round-trip 产物（decide args 已过 JSON 序列化门）——纯树无共享引用，
+ * DAG 共享引用会被误判 [Circular]（对本用例无影响；作通用工具时需知晓）。
+ */
+declare function stableStringify(value: unknown): string;
+/**
+ * mastra 泛型提取版 args 推断（D4，agent 侧专用）：
+ * mastra Tool 首个泛型参数 = inputSchema 的 InferSchema（1.57.0 实证 inputSchema 为
+ * StandardSchemaWithJSON 非 ZodType——不能用 inputSchema 属性推导，必须泛型参数提取）。
+ * 通用侧 InferToolArgs（pre-tool-def.ts）为 standard-schema 兜底版。
+ */
+type InferToolArgsMastra<T extends AnyTool> = T extends Tool<infer In, any, any, any, any, any, any> ? In extends Record<string, unknown> ? In : Record<string, unknown> : Record<string, unknown>;
+/** 强类型构造 helper（D4）：泛型由 tool 实例推断，decide 的 args 类型 = InferToolArgsMastra<typeof tool>。 */
+declare function definePreTool<T extends AnyTool>(tool: T, spec: Omit<PreToolDef<T, InferToolArgsMastra<T>>, 'tool'>): PreToolDef<T, InferToolArgsMastra<T>>;
+/**
+ * 候选选择（零 IO 纯函数）：
+ * - always → 恒候选（score 0）；keywords → BM25 命中（score > 0）且满足命中规则（长词 OR ≥2 token）；
+ * - 同 tool.id 去重：always 优先，同模式保留高分（并列保留先出现者，R12）；
+ * - 排序 key：(isAlways ? 0 : 1, -score, toolId)——always 保底，超限按字典序裁；
+ * - 截断至 DEFAULT_MAX_PRE_TOOLS_PER_RUN。
+ * - 防御（P3a，直调 createChatEngine 路径不经 normalize）：旧形态声明（无 tool 引用 /
+ *   无 routing 字段 / 非法 routing / keywords 空 terms）→ warn 跳过不崩——
+ *   与装配路径「降级不崩」承诺对齐（装配路径声明恒合法，此防御为冗余保险）。
+ */
+declare function selectPreTools(text: string, preTools: PreToolDef[]): PreToolDef[];
+/**
+ * 历史投影（零 IO 纯函数）：ModelMessage[] → PreToolHistoryTurn[]。
+ * - 截断最近 PRE_TOOL_HISTORY_LIMIT 条；仅 user/assistant；
+ * - content 提取：字符串直取 / parts 过滤 text part 拼接（不含 tool-call/tool-result/reasoning）。
+ * - 投影含 user 消息内的 system-reminder 注入块文本（card-decision/pre-tool/memory/skill 恒序
+ *   注入随 history 累积）——当前 decide 零消费 history 内容；未来若加扫描，必须先经
+ *   `stripSystemReminderBlocks` 剥离（注入块文本不得参与路由打分）。
+ */
+declare function projectHistory(history: readonly ModelMessage[]): PreToolHistoryTurn[];
+/**
+ * 数据注入块构建（D5，每 done 工具一个块；server-only、仅内存 LLM 上下文）：
+ * 不随 query 持久化（saveMessage.query = 原始 content）；不进事件载荷 / 路由恢复（三隔离，D7）。
+ * 无 desc 属性（模型已在 availableTools 见 description）。
+ * 纯数据块：块内零指令文本——等价/快照时效语义归平台段「注入块协议」（单源），
+ * 块尾使用规则会随内存 history 跨轮累积泛化（R11 同族缺陷），已删除。
+ */
+declare function buildPreToolDirectives(records: PreToolRecord[]): string[];
+/**
+ * 预执行开始事件（执行前发射——前端立即显示「自动查询中」spinner，感知优化）：
+ * [TOOL_CALL_START, TOOL_CALL_ARGS]，ARGS 载荷经 contracts 单点序列化。
+ */
+declare function buildPreToolCallStartEvents(input: {
+    toolName: string;
+    description?: string;
+    toolArgs?: unknown;
+    toolCallId: string;
+}): ServerEvent[];
+/** 预执行结束事件（执行后发射）：[TOOL_CALL_END, TOOL_CALL_RESULT]，RESULT.messageId 为 AG-UI 必填。 */
+declare function buildPreToolCallEndEvents(input: {
+    toolName: string;
+    status: 'done' | 'error';
+    result?: unknown;
+    error?: string;
+    toolCallId: string;
+    messageId: string;
+}): ServerEvent[];
+/**
+ * 单工具 deadline（decide + execute 共享同一预算，per-tool 流水线）：
+ * 候选并行下墙钟上界 = ms。超时 → PreToolTimeoutError（调用方按 error 降级，不注入）。
+ * 实现：settled 守卫 + then 双分支——超时后底层 fn 的迟到 resolve/reject 均被本 then
+ * 消费（丢弃），避免 Promise.race 形态下迟到 rejection 无处理器导致的 unhandledRejection。
+ */
+declare function withDeadline<T>(ms: number, fn: () => Promise<T>): Promise<T>;
+/** 预执行上下文（mastra 耦合单点收敛面） */
+interface PreToolExecContext {
+    requestContext: RequestContext;
+    observe?: unknown;
+    abortSignal?: AbortSignal;
+}
+/**
+ * 直调工具执行（唯一接触 mastra execute 语义的 helper）：
+ * - 守卫：execute 函数存在（ToolAction.execute 为可选字段）；
+ * - 上下文：per-run requestContext（identity/credentials 并发安全）+ noopObserve + abortSignal；
+ * - JSON 归一：对齐 mastra 模型路径 ensureSerializable，防非 JSON 输出在
+ *   WS 事件与 history ModelMessage 两处断裂；归一失败抛出 → 调用方按 error 降级。
+ */
+declare function executePreTool(tool: RegistryTool, args: Record<string, unknown>, execCtx: PreToolExecContext): Promise<unknown>;
+
+/** importance 基线（W 系列评审冻结）：preference/fact 0.7、episode 0.6 */
+declare const MEMORY_IMPORTANCE_BASE: Record<MemoryKind, number>;
+/** 单用户（userId×scopeKey）记忆容量上限；超限淘汰最低 importance（同分删最旧） */
+declare const MEMORY_MAX_PER_USER = 200;
+/** list 缺省条数 */
+declare const MEMORY_LIST_DEFAULT_LIMIT = 50;
+/** list 上限（与容量上限对齐） */
+declare const MEMORY_LIST_MAX_LIMIT = 200;
+/**
+ * scope → 确定性排序键（INV-6 纯函数）：键字母序 `k1:v1|k2:v2`；无 scope/空对象 → ''。
+ * 值内 `|` `:` `\` 反斜杠转义（双向唯一：不同 scope 恒映射不同 key）。
+ */
+declare function scopeToKey(scope?: Record<string, string>): string;
+/** content → 去重哈希（trim + lowercase 归一后 SHA-256 hex 前 16 位） */
+declare function hashContent(content: string): string;
+/** 生成记录 id：`mem_<8hex>` */
+declare function generateMemoryId(): string;
+/** 治理字段扩展（实现内部，不进契约面） */
+interface StoredMemoryRecord extends MemoryRecord {
+    contentHash: string;
+    scopeKey: string;
+}
+declare function createInMemoryMemoryStore(now?: () => number): MemoryStore;
+
+/**
+ * recall 缓存装饰器（B4，O1+O2 合一）：MemoryStore 的 list 半 TTL 缓存 + 空结果负缓存短路。
+ *
+ * 动机（观测证据，会话 20260904bKa651026049）：knowledge 模式 recall = search + list 双 HTTP
+ * 并发（gap 83-298ms ≈ 单 RTT）；零命中轮照付双请求。零记忆用户（绝大多数）list 半恒空——
+ * 负缓存短路后 recallMs <10ms（第 2 轮起）；有记忆用户 list 半 60s TTL 缓存免重复 RTT。
+ *
+ * 语义（不变量账本）：
+ * - list() → TTL 缓存（键 = userId+scope）；空结果 → empty 标记（负缓存）；
+ * - search() → empty 标记新鲜 → 返回 []（零 HTTP）；否则透传（结果不缓存——query 逐轮不同）；
+ * - save()/delete() → 失效 list 缓存与 empty 标记（同实例写失效）→ 透传；
+ * - 错误不缓存（透传抛出，下轮重试）；
+ * - bounded 状态显式容量（不变量 5）：TTL + LRU 条目双限，防无界增长；
+ * - 组合序（不变量 6）：withRecallCache(gatedStore)——gate 失败穿透装饰器，不污染缓存。
+ *
+ * 观测（N1 显式标记）：getLastRecallCacheState(store) → recall.ts 读入 memory_recall.cache
+ * （'hit' | 'miss' | 'negative'；装饰器缺席 → 'miss' 恒定，零影响）。
+ * 作用域审计：memory 三工具（memory_save/search/list）与 recall 共用同一 store 实例——
+ * save 经装饰器失效钩子保证工具写入后缓存一致；HTTP 管理面接受 ≤60s list staleness。
+ * 多机部署：会话粘同实例（sessions 进程内 Map）→ 写失效覆盖主导路径；跨实例窗口由 TTL 界定。
+ */
+
+interface RecallCacheOptions {
+    /** list 结果 TTL（缺省 60_000ms） */
+    listTtlMs?: number;
+    /** LRU 条目上限（list 缓存与 empty 标记各自独立限；缺省 10_000） */
+    maxEntries?: number;
+}
+declare const DEFAULT_LIST_TTL_MS = 60000;
+declare const DEFAULT_MAX_ENTRIES = 10000;
+/** 命中态观测（N1）：per-store 实例最近一次 recall 相关读的缓存判定 */
+type RecallCacheState = 'hit' | 'miss' | 'negative';
+declare function getLastRecallCacheState(store: MemoryStore): RecallCacheState;
+declare function withRecallCache(store: MemoryStore, opts?: RecallCacheOptions): MemoryStore;
+
+/**
+ * system-reminder 注入块工具（leaf：无依赖，trace-transform 与 memory/recall 共用单源）。
+ *
+ * 独立成模块的动机：trace 层净化不得 import memory/recall（logger 依赖链成环
+ * trace-transform → recall → logger → trace-exporter → trace-transform）。
+ *
+ * 块协议：`<system-reminder …>…</system-reminder>`（skill / preTool / memory /
+ * card-decision 四类注入块统一围栏，属性不限——见 platform-instructions）。
+ */
+/**
+ * 剥离完整 `<system-reminder …>` 块（任意属性——skill/preTool/memory 等注入块）：
+ * submitForm recall 查询清洗 + TBOX_TRACE 展示面净化共用。
+ * 未闭合残片保留（宁留不误删）。
+ */
+declare function stripSystemReminderBlocks(text: string): string;
+
+/**
+ * 记忆召回与注入块构造（017：引擎单点——混合配额检索策略归此，store 不掺配额，F1 正交化）。
+ *
+ * 检索策略（K1 修复形态）：
+ * - search 半（相关性）与 list 半（importance）经 Promise.allSettled 并发，per-half 独立降级
+ *   （半失败 → warn + 贡献空，不摧毁另一半）；
+ * - 孤半存活（另一半 skipped/failed）→ 独占全额 topK 配额；
+ * - 双半皆死（capabilities 门控）→ 返回 []（等价 memory-off，零调用零 warn——L1）；
+ * - 合并：search 结果在前（相关性优先）→ id 去重 → 截断 topK。
+ *
+ * 注入块（单一构造器——双 transport 字节级同构的构造性保证）：
+ * - `<system-reminder memory>` 围栏 + 背景声明（提示注入防御：明示非本轮用户输入）；
+ * - 行格式 `- (id) [kind] content（MM-DD）`——id 供 memory_forget 引用、日期供模型自裁矛盾（W2）；
+ * - 内容区 `<` 转义（INV-5，preTool D5 同款边界：转义记录内容，不动围栏标签自身）；
+ * - 零记录 → 空串（零命中零注入，W4）。
+ */
+
+/** recall topK 缺省（与 memory_search 工具 topK 同值单源） */
+declare const DEFAULT_MEMORY_TOP_K = 5;
+/** 单条记录注入截断缺省（字符） */
+declare const DEFAULT_MEMORY_MAX_CHARS_PER_RECORD = 200;
+/** 归一 topK（undefined → 缺省；非法 → clamp ≥1） */
+declare function clampMemoryTopK(v?: number): number;
+/** 归一 maxCharsPerRecord（undefined → 缺省；非法 → clamp ≥20） */
+declare function clampMemoryMaxChars(v?: number): number;
+/** capabilities 缺省（未声明 = 全真，契约语义单点） */
+declare function memoryStoreCapabilities(store: MemoryStore): MemoryStoreCapabilities;
+/** 引擎 memory 选项（ChatEngineOptions.memory 展开形态；build-engine 透传） */
+interface MemoryEngineOptions {
+    store: MemoryStore;
+    /** run 期 scope 解析（attributes → scope；装配端注入，对齐 deployment.assembly.extractScopeKey 先例） */
+    resolveScope?: (attributes: Record<string, unknown>) => Record<string, string> | undefined;
+    /** 召回条数缺省 5 */
+    topK?: number;
+    /** 单条注入截断缺省 200 字符 */
+    maxCharsPerRecord?: number;
+    /** recall 整体 deadline ms（缺省 = env TBOX_MEMORY_RECALL_TIMEOUT_MS → 200（B4 起，原 600）；0 = 禁用注入） */
+    recallTimeoutMs?: number;
+    /** memory 后端模式（观测字段——memory_recall.mode/run_end 面板归因；缺省 'inmemory'） */
+    mode?: 'inmemory' | 'knowledge';
+}
+/** 归一引擎选项（clamp 单点；构造期一次。recallTimeoutMs 由引擎层解析 env——此处不归一） */
+declare function resolveMemoryEngineOptions(opts: MemoryEngineOptions): {
+    store: MemoryStore;
+    resolveScope?: MemoryEngineOptions['resolveScope'];
+    topK: number;
+    maxCharsPerRecord: number;
+    caps: MemoryStoreCapabilities;
+    mode: 'inmemory' | 'knowledge';
+};
+/** per-half 召回计时（观测面：memory_recall.halves——恒发，零命中轮也可见成本构成） */
+interface RecallHalfTiming {
+    status: 'ok' | 'skipped' | 'failed';
+    durMs: number;
+}
+interface RecallResult {
+    records: MemoryRecord[];
+    halves: {
+        search: RecallHalfTiming;
+        list: RecallHalfTiming;
+    };
+    /** B4 recall 缓存判定（getLastRecallCacheState 透传——negative = 零 HTTP 全短路）。
+     *  双半并发下 state 由最后完成的半写入：负缓存场景两半均写 negative → 恒 negative；
+     *  search 真调用场景（有记忆）→ miss（整体仍有真实 HTTP，语义诚实）。 */
+    cache: RecallCacheState;
+}
+/**
+ * 混合配额召回（纯检索策略单点）：
+ * - search 半：topK = ceil(topK/2)；list 半：limit = topK；
+ * - per-half allSettled 降级 + 孤半独占全额；
+ * - per-half 计时（恒产出——half.status/durMs 随返回上浮，引擎恒发 memory_recall 用）；
+ * - 调用方经 withDeadline 施加整体上界（MemoryStore 接口无 signal 面——abort 由
+ *   deadline 有界等待 + 汇合点丢弃承载，S3 语义等价）。
+ */
+declare function recallMemories(input: {
+    userId: string;
+    scope?: Record<string, string>;
+    query: string;
+}, opts: Pick<MemoryEngineOptions, 'store' | 'topK'>): Promise<RecallResult>;
+/**
+ * 记忆注入块（单一构造器，纯函数）：
+ * - 空记录 → ''（零命中零注入）；
+ * - 行格式 `- (id) [kind] content（MM-DD）`；
+ * - 记录字段（id/content）`<` → `\u003c`（INV-5——转义记录内容区，围栏标签自身为字面量不受影响）。
+ */
+declare function buildMemoryReminder(records: MemoryRecord[], maxChars?: number): string;
+
+/**
+ * 记忆召回前端表达事件序列（018 tool-debug，纯函数，不发射）：
+ * - 合成 tool-call 序列 [START, ARGS, END, RESULT]，toolCallName = MEMORY_TOOL_CALL_NAME；
+ * - args/result 经 contracts buildMemoryToolCallPayload 单点序列化（records text 截断内置）；
+ * - 调用契约：RUN_STARTED 之后、模型流之前发射（前端 isGenerating 门控满足）；
+ *   post-hoc 单点合成（skill 先例）——避开 abort 残患与 RUN_FINISHED sweep 假 error；
+ * - 仅 toolDebug 开启时由调用方发射；不持久化、不进历史重建（隐私边界——debug 期间
+ *   实时可见、历史不可回看）；
+ * - toolCallId 由调用方生成传入（可测性）；RESULT.messageId 为 AG-UI 必填字段。
+ */
+declare function buildMemoryRecallToolCallEvents(input: {
+    toolCallId: string;
+    messageId: string;
+    query: string;
+    status: 'hit' | 'miss' | 'degraded' | 'skipped';
+    records?: MemoryRecord[];
+    reason?: string;
+    error?: string;
+    durMs?: number;
+}): ServerEvent[];
+
+interface MemoryToolDeps {
+    store: MemoryStore;
+    caps: MemoryStoreCapabilities;
+    maxCharsPerRecord: number;
+    /** attributes → scope 解析（装配端注入；与 recall 同源规则） */
+    resolveScope?: (attributes: Record<string, unknown>) => Record<string, string> | undefined;
+}
+/**
+ * 创建记忆三工具（构造期单点；全按 caps 注册——L1 死能力零广告：不注册即不进
+ * 工具列表/提示词目录。SPEC-5「save 恒注册」与 SPEC-7「readonly 段不提 save」组合矛盾，
+ * 按 L1 收敛为按能力注册；匿名/长度校验为运行期分支，恒走优雅错误）。
+ * 返回空对象 = 引擎不合并任何记忆工具。
+ */
+declare function createMemoryTools(deps: MemoryToolDeps): Record<string, AnyTool>;
+
+declare const KNOWLEDGE_DEFAULT_BASE_URL = "https://o.tbox.cn";
+/** 空 scope 哨兵（⚠ ES term 匹配不了空串——scopeKey 列空值写入/过滤均用此值） */
+declare const KB_SCOPE_GLOBAL = "__global__";
+/**
+ * 可过滤列（编译期防 typo——平台对 schema 外列**静默丢弃过滤**（实测），
+ * 列名错 = 跨用户隔离击穿；安全约束进类型系统）。
+ */
+type MemoryFilterColumn = 'id' | 'userId' | 'scopeKey' | 'contentHash';
+interface PreFilterTerm {
+    column: MemoryFilterColumn;
+    value: string;
+}
+interface SortTerm {
+    field: 'importance' | 'createdAt';
+    order: 'asc' | 'desc';
+}
+/** 检索命中（极简面：content = 行 JSON 真源；segmentId = 平台 id（⚠ ≠ mem_id，软删复活会换新 id）） */
+interface SegmentHit {
+    content: string;
+    segmentId: string;
+}
+/** 传输层错误（纯诊断面：retryable 为 callApi 私有——抛出时重试已耗尽） */
+declare class KnowledgeOpenapiError extends Error {
+    readonly detail: {
+        code: string | null;
+        msg: string | null;
+        traceId: string | null;
+        httpStatus: number | null;
+    };
+    constructor(detail: {
+        code: string | null;
+        msg: string | null;
+        traceId: string | null;
+        httpStatus: number | null;
+    }, message?: string);
+}
+interface KnowledgeTransport {
+    /** 语义检索（HYBRID 缺省）。preFilters 恒非空——store 层永不无过滤检索（INV-1）。 */
+    retrieveSemantic(input: {
+        kbId: string;
+        query: string;
+        preFilters: PreFilterTerm[];
+        topK?: number;
+    }): Promise<SegmentHit[]>;
+    /** FIELD_SORT 检索（list/查重/清扫通道）。sorts 省略 = 不依赖排序语义的调用。 */
+    retrieveSorted(input: {
+        kbId: string;
+        preFilters: PreFilterTerm[];
+        sorts?: SortTerm[];
+        limit?: number;
+    }): Promise<{
+        hits: SegmentHit[];
+        total: number;
+    }>;
+    /** ⚠ UPSERT：同 PK 三元组（userId+scopeKey+contentHash）复用既有 segmentId。 */
+    addSegment(input: {
+        documentId: string;
+        rowJson: string;
+    }): Promise<string>;
+    /** false = 不存在（not-exist terminal 归一——store 不见平台错误形态）。 */
+    deleteSegment(input: {
+        segmentId: string;
+    }): Promise<boolean>;
+    /** ⚠ 缺任一 id 整批失败（平台语义）——调用方保证 id 全存在或自兜底。 */
+    batchDeleteSegments(input: {
+        documentId: string;
+        segmentIds: string[];
+    }): Promise<number>;
+    createKnowledgeBase(input: {
+        name: string;
+        tableSchema: unknown;
+        indexColumns: string[];
+        csv: string;
+    }): Promise<{
+        documentId: string;
+    }>;
+    findKnowledgeBasesByName(name: string): Promise<Array<{
+        id: string;
+        name: string;
+        gmtCreate?: string;
+    }>>;
+    getKnowledgeBase(kbId: string): Promise<{
+        type: string;
+        columns: Array<{
+            name: string;
+            dataType?: string;
+            indexed?: boolean;
+        }>;
+        /** KB 下 document 列表（bootstrap 复用路径的 documentId 来源——descIndexedDocuments 响应面） */
+        documents: Array<{
+            id: string;
+        }>;
+    }>;
+    getDocumentPrimaryKeys(documentId: string): Promise<string[]>;
+}
+interface KnowledgeOpenapiTransportOptions {
+    /** 缺省 process.env.TBOX_API_KEY；两者皆无 → 构造期 throw（fail-fast，对齐 knowledge-client 先例） */
+    apiKey?: string;
+    /** 缺省 https://o.tbox.cn；预发联调 https://agtgw-pre.alipay.com */
+    baseUrl?: string;
+    /** 预发 ACE 管控 Cookie 透传（仅预发联调——生产不设） */
+    cookie?: string;
+    /** 单测注入（缺省 globalThis.fetch） */
+    fetchImpl?: typeof fetch;
+}
+declare function createKnowledgeOpenapiTransport(opts: KnowledgeOpenapiTransportOptions): KnowledgeTransport;
+
+/**
+ * 记忆存储实现 B：agtsearch 知识库 adapter（017；TBOX_MEMORY_STORE=knowledge 时启用）。
+ *
+ * 平台缺口 #1/#2 已闭合（agtgw yizhe-memory，预发 7/7 gates 实证 2026-08-30）——
+ * transport 走 agtgw openapi 直连（knowledge-transport.ts），完整四方法实现生效。
+ *
+ * 数据映射（8 列 STRUCTURED，PK = userId+scopeKey+contentHash）：
+ * - 行 JSON = 语义真源（id/userId/scopeKey/kind/content/contentHash/importance/createdAt）；
+ * - scopeKey 列存 scopeToKey 派生键（空 scope 用 '__global__' 哨兵——ES term 匹配不了空串），
+ *   scope 对象经 parseScopeKey 还原；
+ * - createdAt 恒 STRING 列（NUMBER 底层 scaled_float(1e9)，13 位 ms epoch 溢出 ES long）。
+ *
+ * 契约对齐（与实现 A 零漂移）：
+ * - save 读前查重合并：保首见 id/kind/content/createdAt，importance 取大
+ *   （竞态窗口 <2.2s 索引可见性内退化 last-write，PK 保证绝不重复行——Agent Note 备案）；
+ * - search topK 缺省 5；list 排序 importance desc / createdAt desc；
+ * - delete 三列过滤现查真实 segmentId（平台 id ≠ mem_id，软删复活换新 id——实测）。
+ *
+ * 能力门控：四方法入口 × 四契约错误码一一对应——capabilities=false 时结构化拒绝
+ * （HTTP 管理面按同码映射 501；缺省全 false，翻转条件 = 平台发产 + probe 生产复测，
+ * 见 docs/reference/runtime.md 缺口登记）。
+ *
+ * 安全不变量（INV-1）：检索调用恒带非空 preFilters——永不无过滤检索（跨用户泄露面）。
+ */
+
+/** 平台能力缺口/门控错误（结构化错误码；调用方按优雅错误降级） */
+declare class MemoryStoreUnsupportedError extends Error {
+    readonly code: MemoryErrorCode;
+    constructor(code: MemoryErrorCode, message: string);
+}
+/**
+ * 缺省 capabilities 全 true（2026-09-01 翻转——平台侧 agtgw yizhe-memory 已发布生产，
+ * 预发 7/7 gates + live 7/7 + probe 复跑 7/7 实证）。
+ * 语义：knowledge 模式显式启用（KB_ID+DOC_ID+API_KEY 三件套齐备）即全能力可用；
+ * 未启用者零影响（缺省 inmemory 不变）。
+ * 生产启用前建议先跑 probe 生产复测（scripts/probe-memory-kb-pre.mjs，BASE 指
+ * https://o.tbox.cn）确认生产面形态一致；并建议 TBOX_MEMORY_KB_VALIDATE=1 启动校验。
+ * 历史锚点：缺口期全 false 诚实降级（2026-08-24~08-30），见 Agent Note 2026-08-30 系列。
+ */
+declare const DEFAULT_KNOWLEDGE_MEMORY_CAPABILITIES: MemoryStoreCapabilities;
+interface KnowledgeMemoryStoreOptions {
+    /** 传输层唯一注入点（凭证/重试/URL 全封 transport——组合归 resolve.ts） */
+    transport: KnowledgeTransport;
+    /** 记忆专用知识库 ID */
+    knowledgeBaseId: string;
+    /** 记忆 document ID（addSegment/容量淘汰通道入参——平台 doc id 为生成值，必填） */
+    documentId: string;
+    /** 能力覆写（缺省 = 全 false 保守值） */
+    capabilities?: MemoryStoreCapabilities;
+}
+declare function createKnowledgeMemoryStore(opts: KnowledgeMemoryStoreOptions): MemoryStore;
+
+/**
+ * 记忆知识库幂等建库（长期记忆实现 B 生命周期）。
+ *
+ * 流程（probe S1 产品化）：
+ * - existing（env 固化值 kbId+documentId）给定 → schema 校验通过 → 复用；
+ *   不一致 → SCHEMA_MISMATCH fail-fast（不自动重建——误配保护）；
+ * - 未给定 → 按名精确发现（fuzzy 结果 name === kbName 过滤，防近似名串扰）→ 命中取
+ *   gmtCreate 最新 → documentId 取自 KB desc 的 documents 列表（记忆 KB 恒单 doc）→ 校验复用；
+ * - 零命中 → 建库（种子 CSV 哨兵行）→ 再发现 → 校验 → created: true。
+ *
+ * 种子 CSV 含哨兵行：表头-only CSV 存在空 segment 索引缺陷链（probe 实证），
+ * 哨兵行 userId='__system__' 不进任何用户命名空间（残留 1 条无害，运行时清理面恒不触达）。
+ */
+
+/**
+ * 8 列 STRUCTURED schema（PK = userId+scopeKey+contentHash；仅 content indexed；createdAt STRING）。
+ * ⚠ 逐字段对齐 probe MEMORY_SCHEMA（建库请求体真源）：
+ * - createdAt 必须 STRING（NUMBER 底层 scaled_float(1e9)，13 位 ms epoch 溢出 ES long）；
+ * - indexed = 语义语料开关（仅该列值进 embedding/BM25——importance/createdAt 为纯排序列无需索引）。
+ */
+declare const MEMORY_KB_SCHEMA: {
+    readonly name: "agent_memory";
+    readonly description: "tbox agent 长期记忆";
+    readonly columns: readonly [{
+        readonly name: "id";
+        readonly dataType: "STRING";
+        readonly required: true;
+        readonly order: 1;
+    }, {
+        readonly name: "userId";
+        readonly dataType: "STRING";
+        readonly required: true;
+        readonly primaryKey: true;
+        readonly order: 2;
+    }, {
+        readonly name: "scopeKey";
+        readonly dataType: "STRING";
+        readonly primaryKey: true;
+        readonly order: 3;
+    }, {
+        readonly name: "kind";
+        readonly dataType: "STRING";
+        readonly order: 4;
+    }, {
+        readonly name: "content";
+        readonly dataType: "STRING";
+        readonly indexed: true;
+        readonly order: 5;
+    }, {
+        readonly name: "contentHash";
+        readonly dataType: "STRING";
+        readonly primaryKey: true;
+        readonly order: 6;
+    }, {
+        readonly name: "importance";
+        readonly dataType: "NUMBER";
+        readonly order: 7;
+    }, {
+        readonly name: "createdAt";
+        readonly dataType: "STRING";
+        readonly order: 8;
+    }];
+};
+declare const MEMORY_KB_INDEX_COLUMNS: string[];
+/** 种子 CSV（表头 + 哨兵行） */
+declare const MEMORY_KB_SEED_CSV: string;
+declare class KnowledgeBootstrapError extends Error {
+    readonly code: 'SCHEMA_MISMATCH' | 'DISCOVER_FAILED' | 'VALIDATE_TIMEOUT';
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: 'SCHEMA_MISMATCH' | 'DISCOVER_FAILED' | 'VALIDATE_TIMEOUT', message: string, detail?: Record<string, unknown> | undefined);
+}
+interface BootstrapMemoryKbOptions {
+    transport: KnowledgeTransport;
+    /** 缺省 'agent-memory'（多应用同租户时调用方应传应用身份后缀名防串扰） */
+    kbName?: string;
+    /** env 固化值（TBOX_MEMORY_KB_ID/DOC_ID）——跳过发现直接校验复用 */
+    existing?: {
+        kbId: string;
+        documentId: string;
+    };
+}
+interface BootstrapMemoryKbResult {
+    kbId: string;
+    documentId: string;
+    created: boolean;
+}
+/** 启动期校验（TBOX_MEMORY_KB_VALIDATE 时模板装配调用——防 kbId 运行时误配静默击穿 INV-1：
+ *  平台对 schema 外列**静默丢弃过滤**（实测），错配 KB 上过滤失效 = 跨用户泄露面）。
+ *  失败 throw KnowledgeBootstrapError——调用方（guard）决定 fail-fast 或降级。
+ *  timeoutMs 给定 → 整体 deadline：显式 settle race（非 Promise.race——输方 rejection 必然
+ *  被处理）+ timer.unref（防校验挂起时 keep event loop alive 悬挂进程退出）+ 幂等 settle。 */
+declare function validateMemoryKnowledgeBase(opts: {
+    transport: KnowledgeTransport;
+    kbId: string;
+    documentId: string;
+    timeoutMs?: number;
+}): Promise<void>;
+/** 幂等建库：existing 校验复用 / 按名发现复用 / 全新创建，产出 kbId + documentId。 */
+declare function bootstrapMemoryKnowledgeBase(opts: BootstrapMemoryKbOptions): Promise<BootstrapMemoryKbResult>;
+
+/**
+ * 记忆装配解析（017）：env → store 工厂单点（模板装配层消费）。
+ *
+ * TBOX_MEMORY_STORE：
+ * - 未设置 / 'inmemory' → 内存实现（模板缺省开启）；
+ * - 'off' → 逃生舱（完全关闭——工具/recall/提示词段/HTTP 面全部不装配）；
+ * - 'knowledge' → 知识库实现（TBOX_MEMORY_KB_ID + TBOX_MEMORY_KB_DOC_ID + TBOX_API_KEY
+ *   三缺一 → warn 回退 inmemory；建库产出固化值经 scripts/bootstrap-memory-kb.mjs）；
+ * - 非法值 → warn 回退 inmemory。
+ */
+
+/** recall 整体 deadline 缺省（ms）——首字延迟预算的检索上限。
+ *  B4：600 → 200（负缓存短路后零记忆用户 recallMs <10ms；真查询单 RTT 150-300ms——
+ *  200ms 覆盖单 RTT + decode 余量，超时降级跳过不再拖首字）。 */
+declare const DEFAULT_MEMORY_RECALL_TIMEOUT_MS = 200;
+interface ResolvedMemoryStore {
+    enabled: boolean;
+    mode: 'inmemory' | 'knowledge' | 'off';
+    store?: MemoryStore;
+    /** 校验模式（resolveMemoryStoreGuarded 统一填充——诊断零分支；直调 resolveMemoryStore 时缺席） */
+    validateMode?: MemoryValidateMode;
+}
+interface MemoryStoreEnv {
+    store?: string;
+    kbId?: string;
+    /** TBOX_MEMORY_KB_DOC_ID——记忆 document ID（addSegment/容量淘汰通道入参） */
+    kbDocId?: string;
+    /** TBOX_MEMORY_KB_BASE_URL——缺省 https://o.tbox.cn；预发联调 https://agtgw-pre.alipay.com */
+    kbBaseUrl?: string;
+    /** TBOX_MEMORY_KB_COOKIE——预发 ACE 管控透传（仅预发联调） */
+    kbCookie?: string;
+    /** 凭证覆写（缺省 TBOX_API_KEY） */
+    apiKey?: string;
+}
+/**
+ * 解析记忆存储（单点 + 非法值 warn 回退——确定性降级，对齐 resolveSkillMode 先例）。
+ */
+declare function resolveMemoryStore(env: MemoryStoreEnv): ResolvedMemoryStore;
+/**
+ * 解析 recall deadline（TBOX_MEMORY_RECALL_TIMEOUT_MS；缺省 200ms——B4；非法 → 缺省 + warn；
+ * 0 = 无限等待——不推荐，仅供诊断）。确定性：静默降级为缺省。
+ */
+declare function resolveMemoryRecallTimeout(value?: string): number;
+type MemoryValidateMode = 'off' | 'degrade' | 'strict';
+declare const DEFAULT_MEMORY_VALIDATE_TIMEOUT_MS = 10000;
+interface MemoryGuardEnv extends MemoryStoreEnv {
+    /** TBOX_MEMORY_KB_VALIDATE 原始值（resolver 内归一） */
+    validate?: string;
+    /** TBOX_MEMORY_KB_VALIDATE_TIMEOUT_MS 原始值 */
+    validateTimeoutMs?: string;
+}
+interface MemoryGuardDeps {
+    /** 校验函数注入缝（单测 deferred / 未来自定义校验策略；缺省 validateMemoryKnowledgeBase） */
+    validate?: typeof validateMemoryKnowledgeBase;
+}
+/** 解析校验模式（未设置/0/false/off → off；1/true → degrade；strict → strict；非法 → warn + off） */
+declare function resolveMemoryValidateMode(value?: string): MemoryValidateMode;
+/** 解析校验整体超时（缺省 10s；n>=1 且有限才接受，非法 warn 回退——对齐 resolveMemoryRecallTimeout 先例） */
+declare function resolveMemoryValidateTimeout(value?: string): number;
+/**
+ * 统一记忆装配入口（模板单调用点）：resolveMemoryStore + KB 校验三态组合。
+ * - off / 非 knowledge → 直返（零 transport 构造零网络），validateMode 恒填充；
+ * - strict → await 校验（timeoutMs 有界），失败 rethrow（模板顶层 await 拒绝 = 启动失败）；
+ * - degrade → 即返 gated store（listen 零阻塞，INV-D 装配照常），校验后台并发，
+ *   validation 永不 reject（async IIFE catch 归一）。
+ * gate 单次创建：返回的 store 即唯一实例（ctx.memory 与引擎同源——context.ts 同源注释契约）。
+ */
+declare function resolveMemoryStoreGuarded(env: MemoryGuardEnv, deps?: MemoryGuardDeps): Promise<ResolvedMemoryStore>;
+
+/**
+ * 记忆闸门 store（017 M4：KB 校验异步降级 S8 终态）。
+ *
+ * INV-D（装配不变量）：降级只发生在调用执行时；装配面（三工具注册/引擎 recall/mall
+ * guidance/平台提示词段/api/memory 路由/ctx.memory）在任何校验状态下恒定不变——因此本
+ * 装饰器恒返回 store（存在性不变）且 capabilities 透传 inner（构造期门控四消费点依赖其
+ * 值；置 false = 装配期拆工具/路由/提示词段，直接违背 INV-D，禁改）。
+ *
+ * INV-1（安全不变量）：pending 期零 KB 触达（await 挡在 inner 前）；failed 期数据面全禁
+ * （抛 MemoryUnavailableError——不写错配 KB、不在错配 KB 上检索）。
+ *
+ * 降级语义归属消费端（gate 零 fail-value 分支）：引擎 recall catch 跳过注入（既有）；
+ * 三工具结构化错误（既有）；HTTP 管理面 503 + MEMORY_KB_VALIDATION_FAILED。
+ */
+
+/** 校验结果（promise 永不 reject——guard 内 catch 归一，杜绝 unhandledRejection） */
+type MemoryValidationOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+};
+/** 校验失败降级态错误（routes/memory.ts 按 name 匹配 → 503；对齐 MemoryStoreUnsupportedError 先例） */
+declare class MemoryUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code: "MEMORY_KB_VALIDATION_FAILED";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** 闸门包装：四方法同构——await validation → ok 委托 inner / failed 抛 MemoryUnavailableError */
+declare function createGatedMemoryStore(inner: MemoryStore, validation: Promise<MemoryValidationOutcome>): MemoryStore;
+
+interface EngineRunInput {
+    runId: string;
+    threadKey: string;
+    requestContext?: Readonly<RequestContext$1>;
+    abortSignal: AbortSignal;
+}
+interface EngineStepControlInput extends EngineRunInput {
+    requestId: string;
+    sessionId: string;
+    question: string;
+    availableToolIds: readonly string[];
+    maxSteps: number;
+    /** Epoch milliseconds, measured on entry to the model path. */
+    startedAt: number;
+}
+interface EngineModelStepInput extends EngineRunInput {
+    /** One-based model step number. */
+    stepNumber: number;
+    availableToolIds: readonly string[];
+    maxSteps: number;
+    remainingSteps: number;
+}
+interface EngineToolCallInput extends EngineRunInput {
+    stepNumber: number;
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+interface EngineToolResultInput extends EngineToolCallInput {
+    output?: unknown;
+    error?: unknown;
+}
+interface EngineStepResultInput extends EngineModelStepInput {
+    text: string;
+    toolCalls: readonly {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }[];
+    toolResults: readonly {
+        toolCallId: string;
+        toolName: string;
+        output?: unknown;
+        error?: unknown;
+    }[];
+    isFinal: boolean;
+    finishReason: string;
+}
+interface EngineRunEndInput extends EngineRunInput {
+    status: 'completed' | 'stopped' | 'cancelled' | 'error';
+    reasonCode?: string;
+    /** The transcript could not be safely continued; callers must establish a new session. */
+    quarantine: boolean;
+}
+type EngineStepToolChoice = 'required' | {
+    toolId: string;
+};
+interface EngineStepController {
+    /** Optional hard wall-clock deadline. The SDK aborts the producer at this time. */
+    deadlineAt?: number;
+    beforeModelStep(input: EngineModelStepInput): Promise<{
+        appendHint?: string;
+        activeToolIds: readonly string[];
+        summaryOnly?: boolean;
+        toolChoice?: EngineStepToolChoice;
+    }>;
+    beforeToolCall(input: EngineToolCallInput): Promise<void | {
+        proceed: false;
+        output: unknown;
+    }>;
+    afterToolCall(input: EngineToolResultInput): Promise<void>;
+    afterModelStep(input: EngineStepResultInput): Promise<{
+        action: 'follow-runtime' | 'continue' | 'publish-final' | 'stop';
+        reasonCode?: string;
+    }>;
+    onRunEnd(input: EngineRunEndInput): Promise<void>;
+}
+type EngineStepControlFactory = (input: EngineStepControlInput) => EngineStepController | Promise<EngineStepController>;
+
+interface ChatEngineOptions {
+    instructions: string;
+    model: any;
+    tools: Record<string, Tool>;
+    /** 卡片注册表：cardType → CardMeta（capture 校验 + emit 校验共用） */
+    cardRegistry: Record<string, CardMeta>;
+    /** Optional run-local, domain-neutral model/tool control. Not used by deterministic or form paths. */
+    stepControl?: EngineStepControlFactory;
+    /** trace exporter（默认使用 SDK 内置单例） */
+    traceExporter?: TboxTraceExporter;
+    /** 文件 URL 前缀（content-builder 用） */
+    fileUrlPrefix?: string;
+    /** 模型名（用于日志） */
+    modelName?: string;
+    /**
+     * 意图路由表（B21：业务意图表由应用源码提供，hybrid 模式 003 §3.3）。
+     * 提供时 chat() 先 matchIntent；handler 缺省直接出卡/文字，也可用 continueWith 续接完整 Agent。
+     */
+    intentRoutes?: IntentRoute[];
+    /** 意图命中后的业务分发（由组装端经 ctx.handlers.dispatch 提供） */
+    handlerDispatch?: (route: IntentRoute, content: string, reqCtx?: RequestContext$1) => Promise<HandlerResult | undefined>;
+    /**
+     * 持久化回调：保存消息到外部对话服务。
+     * 返回 savedMessageId（已持久化的标识）。
+     * cards：本轮 run 下发的卡片快照（P3 W1，随消息同源提交，004 D1）。
+     */
+    saveMessage?: (args: {
+        conversationId: string;
+        query: string;
+        answer: string;
+        mediaItems?: SendMessageMediaItem[];
+        outerBusinessId?: string;
+        cards?: CardSnapshot[];
+        /** 009 D10：本轮 injected 的 skill 加载记录（供历史表达重建，随消息持久化 inputs.skills） */
+        skills?: SkillRecord[];
+        /** 010：本轮预执行成功的工具记录（仅 done，供历史表达重建，随消息持久化 inputs.preTools） */
+        preTools?: PreToolRecord[];
+    }) => Promise<string | undefined>;
+    /**
+     * 本地 skill 模式（009 D2）：accelerated（默认）/ progressive。
+     * 全局配置、运行期恒定：accelerated → Agent 不注册 skill 工具，本地路由命中后 reminder 注入
+     * user message（system prompt/工具列表恒定 → 前缀缓存稳定）；progressive → 全量注册 InlineSkill。
+     */
+    skillMode?: SkillMode;
+    /** 可用本地 skills（build-engine 合并模块声明 + 应用加载产物后传入） */
+    skills?: LocalSkill[];
+    /**
+     * 可用前置工具声明（010：build-engine 合并模块声明 + 应用产物并校验 toolId 后传入）。
+     * 空/缺省 → 全链路零开销。
+     */
+    preTools?: PreToolDef[];
+    /** 单工具总预算 ms（resolve + execute 共享；缺省 DEFAULT_PRE_TOOL_TIMEOUT_MS；0 = 整体禁用） */
+    preToolTimeoutMs?: number;
+    /** 前置工具 resolve 入参的模块上下文（build-engine 传入 ctx；直调 createChatEngine 需自备） */
+    preToolContext?: ServerContext;
+    /**
+     * 011 B3：卡片动作 token 签发器（模板装配注入闭包；缺省 = 不签发）。
+     * payload 出卡前调用，按 cardType 匹配注册动作附加 actions/actionTokens；
+     * sessionId 由引擎从 runCtx.scopeSessionId 登记供给。
+     */
+    cardActionAttacher?: (payload: _tbox_cn_app_contracts.TboxCardPayload, sessionId: string) => Promise<_tbox_cn_app_contracts.TboxCardPayload>;
+    /**
+     * 011 S5（runBudget）：agent loop 步数预算。
+     * maxSteps 缺省 8；0 = 禁用（不传 mastra maxSteps）。
+     * 触界语义：不执行新工具调用（mastra maxSteps 语义），工具定义仍全量传入，
+     * 孤儿 tool-call 轮以合成文案收尾（防空轮 + deepseek 空 tool-call 对 400）。
+     */
+    runBudget?: RunBudgetOptions;
+    /**
+     * 单轮出卡上限（缺省 DEFAULT_MAX_CARDS_PER_TURN=3；构造期 clamp ≥1）。
+     * 与平台段提示词目录的 maxCards 构造性同源（build-engine 双喂同一值）。
+     */
+    maxCardsPerTurn?: number;
+    /**
+     * 长期记忆（017）：store + 召回配置。未装配 = 全链路零开销（工具/recall/提示词段均不启用，
+     * 未装配应用字节级回归）。意图命中轮/匿名 run 跳过 recall；注入经 mastra context 通道
+     * （request-only——不进 history/saveMessage/事件流，三隔离）。
+     */
+    memory?: MemoryEngineOptions;
+    /**
+     * 018 tool-debug：工具调试视图（TBOX_TOOL_DEBUG env 单源解析，装配端经 resolveToolDebug
+     * 传入）。开启时：memory 召回/silent preTool 以伪工具事件下发前端（不持久化）、
+     * ws-server HELLO_ACK 携带 toolDebug 旗标解锁客户端 dev 视图。缺省 false = 零行为回归。
+     */
+    toolDebug?: boolean;
+    /**
+     * PR-2 尽早执行管线（缺省 false = 零行为）：模型流中白名单工具参数完整即预执行
+     * （fire-and-forget），mastra foreach 命中缓存返回。env TBOX_EARLY_TOOL_EXECUTION
+     * 单源（装配端经 resolveEarlyToolExecution 解析）。多工具轮收益以 parallelToolCalls
+     * 开启为前提；单工具轮行为等价现状。
+     */
+    earlyToolExecution?: boolean;
+    /**
+     * 流式标签卫生（stream-tag-engine）config 路径（测试注入；缺省与 provider 装配同链
+     * DEFAULT_LLM_PROVIDER_CONFIG_PATH）。每请求热读 contentTagHygiene——off/extraTags
+     * 变更即时生效，不改代码即可止血/回滚。
+     */
+    contentTagConfigPath?: string;
+    /**
+     * 出卡协议标签剥离（装配轴，缺省 true；构造期归一）——cards 收编统一引擎后的
+     * 调试面开关。false = cards 标签可见 + decision 恒空（decideCards 走兜底池末张）；
+     * 卫生族（think/tool-call-text）不经此轴（config 轴 contentTagHygiene 专属）。
+     */
+    cardTagStripping?: boolean;
+}
+/** maxCardsPerTurn 归一（undefined → 缺省；非法值 → clamp ≥1 + warn；NaN/Infinity → 缺省） */
+declare function clampMaxCards(v?: number): number;
+/**
+ * toolDebug 解析（018：TBOX_TOOL_DEBUG env 单源；装配端 app.ts 调用，对齐 resolveSkillMode /
+ * resolvePreToolTimeout 先例）：
+ * - 显式值优先：'1'/'true' → 开；'0'/'false' → 关（本地关/部署态开的逃生舱双向可用）；
+ * - 缺省/非法 → warn（仅非法值）+ 缺省 = NODE_ENV !== 'production'
+ *   （对齐 dev-login 非 production 默认开启先例；容器部署 entrypoint 恒 production → 默认关）。
+ */
+declare function resolveToolDebug(value?: string, nodeEnv?: string): boolean;
+/**
+ * 尽早执行解析（PR-2：TBOX_EARLY_TOOL_EXECUTION env 单源；装配端 app.ts 调用）：
+ * 仅 '1'/'true' 开（显式 opt-in——管线为延迟优化非行为修正，恒缺省关 + 观测先行）；
+ * 其余（'0'/非法/缺席）恒 false。非法值不 warn（对齐 TBOX_LLM_AFFINITY 宽松先例——
+ * env 旋钮家族默错默对，不做告警噪音）。
+ */
+declare function resolveEarlyToolExecution(value?: string): boolean;
+/** runBudget 配置（011 C4：禁用 toolChoice:'none'，截断不用它） */
+interface RunBudgetOptions {
+    /** 模型 loop 最大步数（缺省 8；0 = 禁用） */
+    maxSteps?: number;
+}
+/**
+ * runBudget 步数预算单源解析（对齐 clampMaxCards 装配先例，build-engine 双喂消费）：
+ * undefined → 缺省 8（预算恒生效）；显式值透传（0 = 禁用；负数沿用既有透传语义，不 clamp）。
+ * 双喂 = 平台段预算行（提示词说的数）+ agent.stream maxSteps（引擎执行的数）同值同源。
+ */
+declare function resolveMaxSteps(runBudget?: RunBudgetOptions): number;
+/** 运行上下文（连接级身份 + 外部凭据），经 ws-server 从连接绑定传入 */
+interface RunContext {
+    identity?: Identity;
+    credentials?: ExternalCredentials;
+    /** 011 S5：连接级 attributes（HELLO context 并入，如 mall scope），透传 mastra RequestContext */
+    attributes?: Record<string, unknown>;
+    /** 011 B3：HELLO bootstrap 的 scope 会话 id（卡片动作 token 签发用） */
+    scopeSessionId?: string;
+}
+interface ChatEngine {
+    /**
+     * 对话入口。
+     * @param threadKey 线程键（006 D5）：conversationId（唯一会话键）；匿名无会话时由
+     *                  ws-server 传入连接级 fallback 键（服务端生成）。
+     * @param conversationId 真实会话 ID（用于持久化 saveMessage 与 requestId）；匿名缺省。
+     * @param runCtx 运行上下文（连接级身份 + 外部凭据）。
+     */
+    chat(threadKey: string, content: string, onEvent: (event: ServerEvent) => void, mediaItems?: SendMessageMediaItem[], _inputMethod?: string, conversationId?: string, runCtx?: RunContext): Promise<void>;
+    submitForm(threadKey: string, surfaceId: string, formId: string, formData: Record<string, unknown>, onEvent: (event: ServerEvent) => void, conversationId?: string, runCtx?: RunContext): Promise<void>;
+    cancelRun(threadKey: string, runId?: string): void;
+    /** Prevent unsafe transcript reuse and release this thread's in-memory execution state. */
+    quarantineThread?(threadKey: string): void;
+    emitCard(spec: {
+        cardType: string;
+        data: Record<string, unknown>;
+        conversationId: string;
+        messageId?: string;
+        id?: string;
+    }): void;
+    registerSession(threadKey: string, onEvent: (event: ServerEvent) => void): void;
+    unregisterSession(threadKey: string): void;
+    /** 诊断（009）：当前装配的本地 skills（名称/描述/路由词） */
+    listSkills(): {
+        name: string;
+        description: string;
+        routingTerms: string[];
+    }[];
+    /** 诊断（010）：当前装配的前置工具（toolId/描述/路由形态） */
+    listPreTools(): {
+        toolId: string;
+        description: string;
+        routing: PreToolRouting;
+    }[];
+}
+declare function createChatEngine(opts: ChatEngineOptions): ChatEngine;
+
+/**
+ * 流式标签卫生引擎（stream-tag-engine）——消费侧内容级防护主防线。
+ *
+ * 问题：模型退化（量化损失/网关负载）导致 special token 残缺/变体/同形字符替换，
+ * 服务端协议解析按标准字节匹配漏识别 → think 推理体、tool-call 文本信封整段
+ * 落入 content——泄露到前端正文、saveMessage 落库、TTS。本引擎在 chat-engine
+ * 消费侧流式逐字符处置：匹配即剥（取证），失配即释放（G1 字节恒等）。
+ *
+ * 机制-数据分离：标签族以 TagSpec 声明式注册（构造器工厂 + Trie 编译），行为只由
+ * body 位派生（decision=证据保全 / drop=痕迹清除），spec 不携带行为分支——消除非法
+ * 组合空间。cards 协议（card-decision.ts）经同引擎收编（CARDS_SPEC = xmlTagDecision）。
+ *
+ * 不变量：
+ * - G1 字节恒等：无匹配输出逐字符立即释放、零跨 push 缓冲；正文含 `<`/`<code>` 等
+ *   第 2 字符失配即释放，零影响零观测。
+ * - history 零触碰：rawText/fullReasoning 累加在引擎之外（chat-engine 接线保证），
+ *   agent history 三条入史路径字节不变（LLM 轨道真值原样）。
+ * - 归一化仅比对：normalize 为 1:1 码点映射且恒不映射 `<`；held 恒存原文
+ *   （释放/hits.form 吐原文）。同实例内 specs 共享同一 normalize（trie 边键一致性）。
+ * - 字面量约定：open/close 恒以 `<` 开头且不含空白字符（构造器保证）——
+ *   push 边界死族释放规则与 wait-gt 空白容忍的字节安全性前提。
+ * - 死族透明：drop 族 body 超 DROP_BODY_SOFT_LIMIT 降级后，该族本流全部标签
+ *   透明释放（防吞没失控），其余族不受影响（跨族隔离）。
+ * - 死族 push 边界：push 结束于全死游走路径时立即释放 held——单 push 返回值与
+ *   降级透传语义逐字节一致（cards 收编等价性守护点）。
+ * - leading-zone 门控（仅 content 轨 + 仅 gated 族）：zone 于流首/tool-result/
+ *   tool-error 边界开启，首个非空白可见字符释放时关闭；区内剥离、区外 fail-open
+ *   释放 + hits(released)（开口与孤立闭合对称——防业务字面量「有头无尾」残缺）。
+ */
+type TagBodyPolicy = 'drop' | 'decision';
+type TagTrack = 'content' | 'reasoning';
+type TagSeal = 'gt' | 'self';
+type TagSource = 'builtin' | 'extra';
+interface TagSpec {
+    /** 族 id（'cards' | 'think' | 'tool-call-text' | extra 名）；降级/关停按族整体生效 */
+    readonly family: string;
+    /** 开口字面量（gt-seal 形态不含 '>'；恒以 '<' 开头、不含空白） */
+    readonly open: string;
+    /** 闭合字面量（decision 族含 '>' 字节精确；gt-seal 族不含 '>'） */
+    readonly close: string;
+    /** 唯一行为位：decision=证据保全（出卡）；drop=痕迹清除（think/tool-call 卫生） */
+    readonly body: TagBodyPolicy;
+    /** gt=空白容忍等 '>'；缺省 self（字面量即全形） */
+    readonly openSeal?: TagSeal;
+    readonly closeSeal?: TagSeal;
+    /** 1:1 码点归一（仅比对；恒不映射 '<'）；同实例内 specs 必须共享同一实现 */
+    readonly normalize?: (ch: string) => string;
+    /** 唯一例外：think 族在 reasoning 轨 body 透传（保思考气泡，只剥标签） */
+    readonly reasoningBody?: 'passthrough';
+    /** 激活区门控（仅 content 轨生效）：leading-zone = 流首 ∪ 工具边界后的思考相位 */
+    readonly gate?: 'leading-zone';
+    /** 取证来源标记（config extraTags 注入 = 'extra'） */
+    readonly source?: TagSource;
+}
+interface TagHit {
+    family: string;
+    /** stripped=已剥离；released=区外 fail-open 可见释放（G2 代价专属观测） */
+    action: 'stripped' | 'released';
+    /** 原始变体原文（≤64 字符）——变体名单扩展的唯一输入源 */
+    form: string;
+    /** body 字符数 */
+    chars: number;
+    track: TagTrack;
+    source: TagSource;
+    /** 流末未闭合 */
+    unclosed?: boolean;
+    /** body 上限触发降级 */
+    degraded?: boolean;
+}
+interface TagEngineFinish {
+    /** 流末未闭合残余的可见释放（decision 族现行语义；drop 族恒空串） */
+    tail: string;
+    /** decision 族闭合标签体（按出现序；chat-engine 侧按 family 过滤消费） */
+    closedBodies: Array<{
+        family: string;
+        body: string;
+    }>;
+    /** 双轨取证（stripped/released × unclosed/degraded） */
+    hits: TagHit[];
+}
+interface StreamTagEngine {
+    /** 本段可见输出（可能为空串）；终态后恒返空串 */
+    push(delta: string): string;
+    finish(): TagEngineFinish;
+    /** 重开激活区（content 轨 tool-result/tool-error 边界接线；其余 no-op） */
+    resetZone(): void;
+}
+/** decision 族 hold-back 上限（现行 CARD_DECISION_HOLD_LIMIT 值迁移；card-decision re-export 保 API） */
+declare const DECISION_HOLD_LIMIT = 4096;
+/** drop 族 body 吞没封顶（S1）：超限降级——已吞保持、死族移除、后续正文恢复可见 */
+declare const DROP_BODY_SOFT_LIMIT = 32768;
+/** XML 标签族（drop + 双侧 gt-seal）：`<name ...>` / `</name ...>` 空白容忍 */
+declare function xmlTag(family: string, name: string): TagSpec;
+/** 出卡决策标签族（decision + 开口 gt-seal + 闭合字节精确含 '>'——现行协议语义固化） */
+declare function xmlTagDecision(family: string, name: string): TagSpec;
+/** 词表信封族（drop + 双侧 self-seal + 可选 1:1 归一化）：全/半角同形双容走 normalize */
+declare function envelopeTag(family: string, open: string, close: string, normalize?: (ch: string) => string): TagSpec;
+/** 卫生族同形归一：全角竖线/下标点 → 半角（1:1 码点，仅比对） */
+declare const HYGIENE_TAG_NORMALIZE: (ch: string) => string;
+/** 卫生族 XML 成员工厂：think 族继承 reasoningBody 透传 + leading-zone 门控 */
+declare function hygieneXmlTag(family: 'think' | 'tool-call-text', name: string): TagSpec;
+/** 内建卫生族成员名（resolveTagSpecs 组装 activeNames 单源；off 按族整体关停） */
+declare const BUILTIN_HYGIENE_NAMES: Readonly<Record<'think' | 'tool-call-text', readonly string[]>>;
+/** think 族：思考相位泄露防护（残缺 special token → content 泄露） */
+declare const THINK_SPECS: readonly TagSpec[];
+/**
+ * tool-call 文本族：模型以文本形式输出工具调用信封（Qwen XML 形 + DeepSeek 词表形）。
+ * 信封字面量以 TBOX_LOCAL_LOG=on 生产 .http 存档为核对真源（内嵌全角定界为观测主形）。
+ */
+declare const TOOL_CALL_TEXT_SPECS: readonly TagSpec[];
+declare function createStreamTagEngine(specs: readonly TagSpec[], opts?: {
+    track?: TagTrack;
+}): StreamTagEngine;
+
+/**
+ * 工具出卡协议单源（v2）。
+ *
+ * 作者契约：工具 execute 返回 `{ ...顶层答话事实, cards: [{cardType, data, note?}] }`——
+ * `cards` 字段名为平台保留字（非出卡工具禁用此字段名承载其他语义）。
+ *
+ * capture 后模型可见面（模型上下文 / TOOL_CALL_RESULT 事件 / preTool reminder /
+ * inputs.preTools 落库）四面统一为 stripped 形态：
+ *   `{ ...顶层, cards: [{id:"cN", cardType, note}] }`
+ * 同一工具同一产出，模型 tool-result 与 preTool reminder 两路所见 payload 同构——
+ * 由单点包装（wrapToolsForCardCapture）构造保证：两路执行同一 wrapped execute。
+ *
+ * 两层 id：
+ * - ref（c1..cN）：线程内单调的 occurrence 引用（descriptor.id 即 ref，按设计出现在上述四个
+ *   模型可见面）；不进出卡 payload（CUSTOM tbox:card）与历史快照；
+ * - 实例 id（card_<ts>_<rand>）：emit 时生成（CardEmitter 现状），出卡实例身份与历史快照主键。
+ */
+
+/** 出参 cards 字段名（平台保留字） */
+declare const TOOL_CARDS_FIELD = "cards";
+/** 出卡工具 description 标注关键词（平台段预告句共享——跨文件钉死断言防漂移） */
+declare const CARD_EMISSION_HINT_KEYWORD = "\u53EF\u5C55\u793A\u5361\u7247";
+/** 出卡工具 description 标注句基础形（withCardEmissionHint 单源） */
+declare const CARD_EMISSION_HINT_BASE = "\u547D\u4E2D\u6570\u636E\u65F6\u7ED3\u679C\u9644\u53EF\u5C55\u793A\u5361\u7247\uFF08cards\uFF09\u3002";
+/** 出卡工具 description 标注句动作卡后缀（卡上承载操作入口时追加） */
+declare const CARD_EMISSION_HINT_ACTIONS = "\u64CD\u4F5C\u5165\u53E3\u5728\u5361\u7247\u4E0A\u3002";
+/** descriptor 形状恒定（capture 后模型可见形态；供 outputSchema 组合，可选导出） */
+declare const TOOL_CARD_DESCRIPTOR_SCHEMA: z.ZodObject<{
+    id: z.ZodString;
+    cardType: z.ZodString;
+    note: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    cardType: string;
+    note: string;
+}, {
+    id: string;
+    cardType: string;
+    note: string;
+}>;
+/** 作者侧：工具 execute 出参中的卡条目 */
+interface ToolCardSpec {
+    cardType: string;
+    data: Record<string, unknown>;
+    note?: string;
+}
+/** 模型侧：stripped 出参中的卡描述符 */
+interface ToolCardDescriptor {
+    id: string;
+    cardType: string;
+    note: string;
+}
+/** 池条目（不可变：每个合法 cards occurrence 都是独立候选） */
+interface PoolEntry {
+    ref: string;
+    cardType: string;
+    data: Record<string, unknown>;
+    note: string;
+}
+interface CardPoolOptions {
+    /** ChatEngine 使用线程级单调 ref；缺省时池内从 c1 开始。 */
+    allocateRef?: () => string;
+}
+interface CardPool {
+    /** 校验 + 注入；每个合法 occurrence 都创建独立 ref，校验失败 → null */
+    add(spec: ToolCardSpec, registry: Record<string, CardMeta>): ToolCardDescriptor | null;
+    /** ref 精确查找（大小写不敏感） */
+    byRef(ref: string): PoolEntry | undefined;
+    entries(): readonly PoolEntry[];
+    size(): number;
+}
+/** 候选池工厂（每 run 一个；每个 occurrence 独立 ref） */
+declare function createCardPool(options?: CardPoolOptions): CardPool;
+/**
+ * capture：校验 + 池注入 + 剥离（单函数三合一）。
+ * - raw 非对象或无 cards 字段 → 原样返回（no-op，不出卡工具零开销）；
+ * - cards 非数组 → warn + 原样返回；
+ * - 逐条校验（非对象 / cardType 非 string / 未注册 / dataSchema 失败 → skip + warn）；
+ * - 有效 ≥1 → `{ ...raw, cards: descriptors }`；全无效 → 浅拷贝删除 cards 键；
+ * - 条目数 > CARDS_WARN_LIMIT → warn（不截断）。
+ */
+declare function captureToolCards(raw: unknown, pool: CardPool, registry: Record<string, CardMeta>): unknown;
+/** run 级卡片池 ALS 上下文（chat/submitForm run 开始进入，finally 退出） */
+declare const toolCardScope: AsyncLocalStorage<{
+    pool: CardPool;
+}>;
+/**
+ * 单点包装：浅拷贝每个 tool 仅替换 execute（禁变异原实例）；无 execute 的原样保留。
+ * wrapped execute：双参 + 接收者透传（mastra 契约），产出经 captureToolCards
+ * （ALS 无池 → 引擎外直调原样返回）。模型路径（Agent.tools）与 preTool 路径
+ * （engine 按 id 替换执行体）共用同一 wrapped execute → 两路同构由构造保证。
+ */
+declare function wrapToolsForCardCapture(tools: Record<string, Tool>, registry: Record<string, CardMeta>): Record<string, Tool>;
+
+/**
+ * 出卡决策协议（候选池 → 模型标签决策 → 多卡下发）。
+ *
+ * 工具/preTool 出参经 capture（tool-cards.ts）注入候选池并剥离为 descriptor；
+ * 模型在回复正文末尾输出 `<agent-ui-cards>c1 c2</agent-ui-cards>`（ref 引用，空格序=展示序），
+ * 引擎流式剥离标签（用户不可见）并按 decision 顺序解析出卡。协议仅存在于
+ * server 侧（contracts 不含标签语法——客户端永远见不到标签）。
+ * 出卡唯一触发 = 字节级精确标签（大小写宽容、开口空白容忍；闭合含 '>' 字节精确——
+ * CARDS_SPEC 经 stream-tag-engine 的 xmlTagDecision 固化，闭合空白容忍是 think 族专属
+ * 宽容，不泛化到此）；漂移/信封形态一律普通文本（fail-visible）——观测见 model-dialect.ts
+ * （detect-only；history 卫生已随缓存最大化裁定废除，2026-09-02：标签随 messageList
+ * 真值原样回填，stale id 归 invalid-fallback 兜底）。
+ */
+
+/** 决策标签名（<agent-ui-cards>...</agent-ui-cards>） */
+declare const CARD_DECISION_TAG = "agent-ui-cards";
+/** 单轮出卡上限缺省值（提示词与引擎构造性同源的单一数值源） */
+declare const DEFAULT_MAX_CARDS_PER_TURN = 3;
+/**
+ * stripper hold-back 缓冲上限：开口标签命中后若迟迟不闭合（模型退化性重复），
+ * 释放已 hold 内容为可见文本并降级（本流不再识别标签），防缓冲膨胀与可见流停滞。
+ * 值真源已迁 stream-tag-engine.DECISION_HOLD_LIMIT（cards 收编统一引擎），此处 re-export
+ * 保 public API 面。
+ * 精确边界（实测标定）：held = 开口 + body + 闭合前缀逐字符累积，降级判于未命中字符
+ * 且命中优先——body ≤ 4063 恒正常闭合；body = 4064 于闭合命中点恰达上限仍闭合；
+ * body ≥ 4065 于 close 前缀中途降级。
+ */
+declare const CARD_DECISION_HOLD_LIMIT = 4096;
+/** 出卡协议 spec（协议族唯一真源；chat-engine 统一引擎与适配器共用） */
+declare const CARDS_SPEC: TagSpec;
+/**
+ * 流式标签剥离器（stream-tag-engine 适配器——cards 收编统一引擎后的薄壳；
+ * 签名与行为与收编前状态机逐字节等价，双闸 card-decision.test.ts +
+ * chat-engine-post-reply.test.ts 不改一字通过）。
+ * push 返回本段可见文本（可能为空串）；finish 是唯一解析点，
+ * tail=流结束时未闭合的残余可见文本，decision=全部标签 token 按出现序【不去重】。
+ * token 去重和上限截断由 decideCards 负责。
+ */
+interface CardDecisionStripper {
+    push(delta: string): string;
+    finish(): {
+        tail: string;
+        decision: string[];
+    };
+}
+/** 标签体 token 化：空白/中英文逗号/顿号分隔，trim 后丢弃空项，重复保留 */
+declare function tokenizeTagBody(body: string): string[];
+declare function createCardDecisionStripper(): CardDecisionStripper;
+interface CardDecisionPlan {
+    entries: PoolEntry[];
+    unmatched: string[];
+    rejectedCardType: number;
+    droppedByCap: number;
+    fallback?: 'budget-fallback' | 'pool-fallback' | 'invalid-fallback';
+}
+/**
+ * 纯决策计划：三规则矩阵（2026-09-01 多轮出卡稳定性）——
+ * 1) 任一有效引用 → 出卡（none token 记 unmatched 噪音）；
+ * 2) 归一后恰为 ['none'] → 显式弃权（唯一无歧义免出通道；显式意图压过预算触界）；
+ * 3) 其余一切（零 token / 全 stale id / cardType 名 / none 混杂无效 token / 字面回声）
+ *    → 兜底出池末张。fallback 分型：budget=预算触界且零 token / pool=零 token 遗漏 /
+ *    invalid=有 token 但全无效（stale id、cardType 名、回声、none 混杂）。
+ * 解析严格限当前池 ref（跨轮引用禁令）；显式引用按模型标签序全保留 + ≤maxCardsPerTurn 截断
+ * （同型更新语义由提示词条件引导，机制不做同型收敛——2026-09-02 多意图互补卡并列放宽）。
+ * 失败模式全倒向安全侧：忘标签/垃圾 id/忘 none → 兜底；唯一定向出口是纯 none。
+ * IO、发送和快照由 chat-engine flush 负责。
+ */
+declare function decideCards(args: {
+    decision: readonly string[];
+    pool: CardPool;
+    maxCardsPerTurn: number;
+    budgetExceeded: boolean;
+}): CardDecisionPlan;
+/**
+ * 兜底取卡：池末条（最新产出——与提示词「后出现 = 更新」排序语义一致）。
+ * 空池 → undefined。
+ */
+declare function pickFallbackCard(pool: CardPool): PoolEntry | undefined;
+
+/**
+ * 流式标签卫生 config 缺省路径（真源自 model-providers.ts 迁入单源——chat-engine 卫生
+ * 引擎与 provider 装配同链同文件）。用 process.cwd() 相对路径，避免 import.meta.url
+ * 在 tsup 打包后指向 dist/ 导致路径层级变化；dev/prod 的 cwd 均为 apps/server/。
+ */
+declare const DEFAULT_LLM_PROVIDER_CONFIG_PATH: string;
+/** 卫生族 id（cards 为协议族，恒不参与 config 面——归装配轴 cardTagStripping） */
+type HygieneTagFamily = 'think' | 'tool-call-text';
+/**
+ * 流式标签卫生配置（卫生轴，与出卡装配轴正交）。
+ * off = 族级关停（回滚杠杆，热路径）；extraTags = 字面量扩展（热路径止血——
+ * 新变体名并入对应卫生族，禁任意正则防注入/误伤）。
+ */
+interface ContentTagHygiene {
+    off?: string[];
+    extraTags?: Array<{
+        name: string;
+        family: HygieneTagFamily;
+    }>;
+}
+interface ResolvedTagSpecs {
+    /** 活跃卫生族 specs（cards 协议族恒不参与——归装配轴） */
+    specs: TagSpec[];
+    /** 活跃 XML 标签名（小写）——dialect residue 扫描排除面（N3 防自碰撞） */
+    activeNames: string[];
+}
+type ThinkingControl = boolean | 'auto' | Record<string, unknown>;
+/** 并行工具调用控制（三态同构 thinking）：true/false 注入请求体；'auto' = 不注入（走网关按模型默认） */
+type ParallelToolCallsControl = boolean | 'auto';
+/**
+ * 流式标签卫生 specs 解析（每请求热读，WS 长连接热切——对齐 thinking/parallel 刻度）。
+ * 组合 = 内建卫生族 − off ∪ extraTags；cards 协议族恒不参与（归装配轴 cardTagStripping）。
+ * activeNames 供 dialect residue 扫描排除（N3 防自碰撞：已剥/已放行形态均有 hits 信号）。
+ */
+declare function resolveTagSpecs(configPath: string): ResolvedTagSpecs;
+
+/**
+ * 平台段系统提示词（单源模板，确定性纯函数——同输入恒同输出字节，全业务通用）。
+ *
+ * 系统提示词 = 业务段（置前：agent.jsonc instructions [+ memoryInstructions（memory 装配态）]
+ * 或 SDK 默认 DEFAULT_INSTRUCTIONS）+ 本平台规则段（后置，SDK 生成：通用行为（含安全拒答）[+ 预算行]
+ * + 卡片协议规则 + few-shot 示例 + 注入块协议 [+ 记忆协议段（017，装配 memory 时）] + 冲突裁决）
+ * （createEngineFromContext 拼接；两段以「# 平台规则」标题分界）。
+ *
+ * v2：不内嵌真实卡片目录——候选卡由工具出参 `cards` 字段运行期注入（id 引用），
+ * 平台段对任意装配字节级恒定（参数 maxCards/maxSteps/memory 构造期定形），跨应用提示词/前缀缓存稳定。
+ * 标签字面量经 CARD_DECISION_TAG 内插（单源）。
+ * 跨轮语义（三条事实句，零行为指令）：数据时效（通用行为——重问/追问更多 =
+ * 期望当前时点数据）+ 卡片可见性（卡片协议——历史卡不随本轮重现，本轮出卡需本轮新 id）
+ * + 展示决策按轮独立（只看本轮候选与当前意图，历史轮展示过相同内容不影响判断——
+ * 机制事实：决策解析只看当前池，跨轮零记忆）；共同消除「直答合法 + 出卡需本轮执行」
+ * 组合下的重问不出卡盲区（含「已展示过→省略展示」反向误推），路径无关
+ * （模型自主调用与 preTool 重跑两路径自动正确，答话可用面不受限——回忆类直答合法）。
+ * 017：记忆段为条件拼接——未装配 memory 的应用平台段字节与 016 完全相等（前缀缓存不变）；
+ * 装配态内段字节恒定（caps 三元组构造期定形）。
+ * 预算行：maxSteps 参数化（resolveMaxSteps 单源双喂，构造期定形——随每请求含 loop 每步下发）；
+ * 注入块协议：无条件拼接（「可能出现」措辞兜底无块轮，与记忆段条件拼接动机不同）。
+ * 安全拒答（通用行为首条，2026-09-07）：主语用审核类目词 +「有害内容」上位兜底，禁「底线安全」
+ * 类行话（模型对齐语料无锚定，近邻误读向 InfoSec 安全基线）；三不变式 = 不回答/不调用工具/
+ * 不提供变通做法；居首 = 安全先于一切行为准则；类目为稳定集合，增删只动枚举（测试锚不变式不锚清单）。
+ *
+ * 自定义平台段的唯一定制点 = 绕过 createEngineFromContext 手工装配
+ * （createSdkToolRuntime + createChatEngine 自备全量 instructions）；
+ * 不提供注入/覆写选项（保持协议规则的平台一致性）。
+ */
+
+/** 记忆段构造输入（装配态 capabilities 三元组——save/search/delete 工具可用性） */
+type MemoryPromptCaps = Pick<MemoryStoreCapabilities, 'save' | 'search' | 'delete'>;
+declare function buildPlatformInstructions(opts: {
+    maxCards: number;
+    /** 步数预算（resolveMaxSteps 单源产物；> 0 拼预算行，0 = 显式禁用不拼） */
+    maxSteps?: number;
+    /** 记忆装配态（017）：缺省不拼接（未装配应用字节零变化） */
+    memory?: MemoryPromptCaps;
+}): string;
+/**
+ * 出卡决策轮级提醒块（W3，2026-09-01；v2.1 2026-09-02 因果链补强；v2.2 2026-09-03 空池事实句）：
+ * 每轮注入 user 消息最前部的 card-decision reminder。四分支骨架（结构即扩展面）：
+ * 来源事实 → 取得动作（条件门）→ 空池事实句 → 非空决策协议。
+ * - 构造期 singleton：同 maxCards 输入字节恒定（跨轮/跨会话前缀缓存稳定）；
+ * - 取得动作句修复「数据类问题凭历史直答 → 池空 → 无卡」调用触发缺口（base 模板唯一轮级防线）；
+ *   单一条件对（意图「要展示卡片」∧ 状态「本轮还没有结果」）防过度调用；「（含注入块）」钉死
+ *   preTool 边界（与注入块协议「等价」句对齐）；「仅凭历史内容作答，本轮不会有卡片」为机械真事实句
+ *   （池只从本轮 capture 填充），承接失效语义；
+ * - 空池事实句（2026-09-03）：堵协议盲区——原三句只管标签不管话术，池空轮模型仍可正文声称
+ *   「已出卡/卡片里有」；句式为纯事实+禁声称协议边界（非行为指令——不命令调工具，R11 合规；
+ *   回忆类直答不受限：只禁声称卡片存在）；
+ * - 无 preamble（纯系统文本——与 memory 块前导「（系统提醒，非用户输入）」的非对称是有意的：
+ *   memory 内容受用户影响需防御性声明，本块纯协议重申无需）；
+ * - 禁业务路由词（停车/券/楼层/积分等零出现——防污染 preTool decide 的 history 投影扫描）；
+ * - 不提兜底（防道德风险——模型知道有兜底会降低标签遵从）；tie-break 句教自身判断缺省；
+ * - 形态边界（防退化负向锚）：不得退化为无条件/命令式调用指令——回忆类直答合法。
+ */
+declare function buildCardDecisionReminder(maxCards: number): string;
+
+/**
+ * 插件工具引用（结构与 @tbox.cn/agent-plugin 的 LoadedPluginToolReference 一致，
+ * 避免依赖未公开的 ./references 子路径）。
+ */
+interface PluginToolReference {
+    kind: 'plugin';
+    pluginId: string;
+    toolId: string;
+    runtimeId: string;
+}
+interface SdkToolRuntime {
+    /** LLM 装配工具（harden 后：sanitize preprocess + strict 缺省 false） */
+    tools: Record<string, AnyTool>;
+    /** 加固前合并工具集（注册表原始实例）——normalizePreTools D9 实例一致性校验对象（比对原件，
+     *  禁对 harden 副本校验：副本≠声明原件会全员误报双实例分裂，preTool 静默失效） */
+    rawTools: Record<string, AnyTool>;
+}
+/**
+ * LLM 工具入参加固（装配单点，静态+插件全量覆盖）：
+ * 1. zod inputSchema → sanitize preprocess 包装（null/"null"/"undefined" 校验前清洗）；
+ * 2. strict 缺省 false —— Mastra ≥1.58 显式退出 strict schema 方言改写（OpenAI 层把
+ *    optional 改写为全量 required + 显式 null 的根因层）；1.57 上惰性存留（wire 携带
+ *    缺省等价 false，无害）。已显式声明 strict 的工具不覆盖。
+ * 浅克隆仅替换两字段（v2 wrapToolsForCardCapture 同款惯用法，禁变异原实例）。
+ */
+declare function hardenToolsForLlm(tools: Record<string, AnyTool>): Record<string, AnyTool>;
+interface SdkRuntimeOptions {
+    /**
+     * 插件工具加载（app 注入 pluginIntegration，保留 @tbox.cn/agent-plugin 接入层）。
+     * 返回加载后的工具与插件 runtime id 引用。
+     */
+    loadPlugins?: () => Promise<{
+        tools: Record<string, AnyTool>;
+        references: PluginToolReference[];
+    }>;
+}
+/**
+ * 从 ServerContext 装配工具运行时（静态工具 + 插件工具）。
+ * 供 ChatEngine 构建与 plugin-doctor/inspect 复用。
+ * v2：出卡走工具出参 cards 字段（engine 内 capture），不再装配 tool→card resolver。
+ */
+declare function createSdkToolRuntime(ctx: ServerContext, opts?: SdkRuntimeOptions): Promise<SdkToolRuntime>;
+interface BuildEngineOptions extends SdkRuntimeOptions {
+    /**
+     * 业务段系统提示词（agent.jsonc instructions 或 SDK 默认；首行身份句）。
+     * 最终 instructions = 业务段 [+ memoryInstructions（memory 装配态）] + 平台规则段（SDK 后置生成）。
+     */
+    instructions: string;
+    /**
+     * 记忆域业务措辞（agent.jsonc memoryInstructions；仅 memory 装配态追加到业务段尾部，
+     * 非装配态不拼接——死能力零广告，装配条件构造性归 SDK）。
+     */
+    memoryInstructions?: string;
+    model: unknown;
+    stepControl?: ChatEngineOptions['stepControl'];
+    /** 模型名（日志用） */
+    modelName?: string;
+    /** 文件 URL 前缀（content-builder 用） */
+    fileUrlPrefix?: string;
+    /** trace exporter（默认 SDK 内置单例） */
+    traceExporter?: TboxTraceExporter;
+    /** 持久化回调（同 ChatEngineOptions.saveMessage） */
+    saveMessage?: ChatEngineOptions['saveMessage'];
+    /** 意图路由表（B21）：chat() 先 matchIntent；handler 缺省直出，也可 continueWith 续接 Agent */
+    intentRoutes?: IntentRoute[];
+    /** 011 S5：runBudget 步数预算（透传 ChatEngine + 平台段预算行——resolveMaxSteps 单源双喂） */
+    runBudget?: RunBudgetOptions;
+    /** 011 B3：卡片动作 token 签发器（透传 ChatEngine） */
+    cardActionAttacher?: ChatEngineOptions['cardActionAttacher'];
+    /** 单轮出卡上限（透传 ChatEngine；与平台段 maxCards 构造性同源——同一 clamp 值双喂） */
+    maxCardsPerTurn?: ChatEngineOptions['maxCardsPerTurn'];
+    handlerDispatch?: (route: IntentRoute, content: string, reqCtx?: _tbox_cn_app_contracts.RequestContext) => Promise<HandlerResult | undefined>;
+    /** 本地 skill 模式（009 D2）：accelerated（默认）/ progressive，同 ChatEngineOptions.skillMode */
+    skillMode?: SkillMode;
+    /** 应用级本地 skills（模板 loadLocalSkills 产物；与模块声明合并，应用覆盖模块） */
+    skills?: LocalSkill[];
+    /** 应用级前置工具声明（010；与模块 ctx.preTools 合并，应用覆盖模块） */
+    preTools?: PreToolDef[];
+    /** 单工具总预算 ms（resolve+execute 共享；缺省 2000；0 = 禁用），同 ChatEngineOptions.preToolTimeoutMs */
+    preToolTimeoutMs?: number;
+    /**
+     * 长期记忆（017）：store + 召回配置（透传 ChatEngine；装配端经 resolveMemoryStore 解析 env）。
+     * 未传 = 不装配（平台段零变化、零工具注册、零 recall）。
+     */
+    memory?: MemoryEngineOptions;
+    /** 018 tool-debug：工具调试视图（透传 ChatEngine；装配端经 resolveToolDebug 解析 env） */
+    toolDebug?: boolean;
+    /** PR-2 尽早执行管线（透传 ChatEngine；装配端经 resolveEarlyToolExecution 解析 env；缺省 off） */
+    earlyToolExecution?: boolean;
+}
+/**
+ * 合并 skills（009 D8）：模块声明（ctx.skills）先插、应用级（opts.skills）覆盖 + warn。
+ * Map 按 name 去重 → 传给 ChatEngine 的数组无重名（accelerated 注入/去重以 name 为锚的前提）。
+ */
+declare function mergeSkills(moduleSkills: LocalSkill[], appSkills: LocalSkill[]): LocalSkill[];
+/**
+ * 合并 preTools（010）：模块声明（ctx.preTools）先插、应用级（opts.preTools）覆盖 + warn。
+ * Map 按 tool.id 去重 → 传给 ChatEngine 的数组无重名。
+ */
+declare function mergePreTools(modulePreTools: PreToolDef[], appPreTools: PreToolDef[]): PreToolDef[];
+/**
+ * 校验并归一 preTools（010）：
+ * - tool.id 必须命中合并后工具集（含插件工具），否则 warn 跳过；
+ * - 实例一致性（D9）：tools[id] !== def.tool → warn 跳过（防双实例分裂——005 v0.4.0 教训，
+ *   发布态下 app-sdk 多副本时模块声明的工具引用与工具集实例不同源）。
+ */
+declare function normalizePreTools(preTools: PreToolDef[], tools: Record<string, AnyTool>): PreToolDef[];
+/**
+ * 从 ServerContext 构造 ChatEngine（自注册闭环组装端）。
+ * 静态工具 = ctx.tools.getAll()；卡片 registry = ctx.cards.getAll()；
+ * 插件工具由 app 注入 loadPlugins（apps/server/src/plugins/integration.ts 仍归 app）。
+ * 工具出卡 capture 在 ChatEngine 构造期统一包装（tools/preTools 原始实例传入）。
+ */
+declare function createEngineFromContext(ctx: ServerContext, opts: BuildEngineOptions): Promise<ChatEngine>;
+
+/**
+ * 消息 inputs 组装规则（010 下沉 S3）：平台消息契约的「非空才加」字段规则属框架逻辑，
+ * 模板不应手写。全空 → undefined（调用方省略 inputs 键）；未来新增 inputs 字段只改此处。
+ */
+declare function buildMessageInputs(input: {
+    cards?: CardSnapshot[];
+    skills?: SkillRecord[];
+    preTools?: PreToolRecord[];
+}): Record<string, unknown> | undefined;
+
+/**
+ * WebSocket 网关（006 D6/D12 + 会话 β）：管理连接、心跳、消息路由、鉴权与身份绑定。
+ * - HELLO（携带 token）→ ws-auth 校验 → 连接级身份绑定（含可选外部凭据）；零会话职责；
+ * - 会话 β：conversationId 从客户端协议面退役——NEW_CONVERSATION（bootstrap 新开）/
+ *   RESUME_CONVERSATION（重连续接）由服务端建立会话并绑定为「连接当前会话」；
+ *   RUN/CANCEL_RUN/UI_ACTION 恒取连接当前会话（客户端携带的 conversationId 一律忽略——
+ *   不提供即不可伪造，水平越权面协议级消灭）；裸 RUN 无会话 → RUN_ERROR 严格拒绝；
+ * - 顺序门控：业务事件（SEND_MESSAGE/UI_ACTION/CANCEL_RUN/NEW/RESUME）必须发生在身份绑定之后；
+ * - 条件解绑：close 时仅释放本连接注册过的 emitter 键，防止误删其它连接的旁路通道；
+ * - 多连接：同键后注册者接管 emitter（Map 覆盖，单活动连接语义）；
+ *   广播集合化（多连接推送）为演进预留（见 006 §9）。
+ * - 匿名（optional 模式）：HELLO 无 token → 服务端生成匿名身份绑定；不可建会话、写操作拒绝。
+ * - 011 F2/F4：配置 scopeSessions 时 HELLO 携带 context → bootstrap 会话 + HelloAck 回发
+ *   （mall 白名单校验 + 会话级绑定）；不配置则行为与 006 完全一致。
+ */
+/** 结构化最小形状（会话 β 注入；ConversationService 结构兼容——模板装配懒代理/测试注入 fake） */
+interface WsConversationService {
+    createConversation(agentId: string, userId: string): Promise<string>;
+    getOrCreateConversation(agentId: string, userId: string): Promise<string>;
+}
+interface WsServerOptions {
+    /** WS 鉴权器（由 createAuthRuntime 提供）；不传则降级为匿名直连（仅限测试/自托管非生产） */
+    auth?: WsAuthenticator;
+    /**
+     * 会话 β：会话建立服务（可选；装配端注入 ConversationService 结构化代理）。
+     * 缺席/失败 → NEW/RESUME 走 notice 通道报错，RUN 恒严格拒绝（fail-closed——
+     * 不静默降级为无会话直跑，「无会话即拒」协议不变量恒成立）。
+     */
+    conversationService?: WsConversationService;
+    /** 会话建立用 agentId（缺省读 TBOX_APP_ID env；显式注入便于测试与多应用容器） */
+    conversationAgentId?: string;
+    /** 011 F2：scope 会话注册表（可选；装配时注入 createScopeSessionRegistry） */
+    scopeSessions?: ScopeSessionRegistry;
+    /** 011 F4：HelloAck chatConfig（可选；快捷指令 + settings 由装配端提供，形状真源 = contracts HelloAckChatConfig） */
+    chatConfig?: HelloAckChatConfig;
+    /** 011 E1：模块动作分发器（可选；装配端注入 createModuleActionDispatcher） */
+    moduleActions?: ModuleActionBridge;
+    /**
+     * 默认 HELLO context（可选；装配端注入，如部署默认商圈）。
+     * 仅 HELLO 完全未携带 context 时采用——显式（含部分）context 不覆盖，保形状错误可见性。
+     */
+    defaultContext?: Record<string, unknown>;
+    /**
+     * HELLO context 增强器（域中立注入点；上下文统一化扩展）：
+     * envelope 归一（含 defaultContext 兜底）之后、身份绑定/bootstrap 之前调用。
+     * 返回值参与全链（attributes/scope/HelloAck 回显）；async 支持（如按 mallId 拉取拓扑信息）。
+     * fail-soft 契约：抛错/返回非对象 → 警告并使用原 context 继续（增强是增益不是闸门）。
+     * 时序注意：增强期间的 await 会推迟串行队列中后续业务消息（顺序门控强序），
+     * 实现方应自设有界等待。
+     */
+    enhanceContext?: (context: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * 业务层 keepalive（可选；默认启用 30s 探测 / 90s 回收，timeout=3×interval 派生）。
+     * 仅作用于业务层探测与 capable 连接回收；协议心跳（TCP 存活基线）不受此项影响。
+     * 须在 createWsServer 时注入（连接建立后不重排）；intervalMs 下限 100ms。
+     */
+    keepalive?: {
+        enabled?: boolean;
+        intervalMs?: number;
+    };
+    /**
+     * 018 tool-debug：工具调试视图旗标（TBOX_TOOL_DEBUG env 单源，装配端经 resolveToolDebug
+     * 解析后传入；与 engine.toolDebug 同值同源）。开启时 HELLO_ACK 携带 toolDebug: true
+     * 解锁客户端 dev 工具视图（非 scope 部署亦发送 ack——base dev 视图通道）。
+     * 关闭态：scope 部署行为与现状逐字节一致，非 scope 部署不发 ack。
+     */
+    toolDebug?: boolean;
+}
+/** 模块动作桥（011 E1：ws-server 与 dispatcher 的薄接口，避免 ws 直接依赖完整 dispatcher 类型） */
+interface ModuleActionBridge {
+    dispatch(input: {
+        token: string;
+        actionId: string;
+        sessionId: string;
+        /** 动作来源卡实例 id（P0 原地更新目标；host-effect 回传缺省 ''） */
+        surfaceId?: string;
+        ctx: _tbox_cn_app_contracts.RequestContext;
+        formData?: unknown;
+        emit: (event: ServerEvent) => void;
+    }): Promise<unknown>;
+}
+declare function createWsServer(engine: ChatEngine, opts?: WsServerOptions): ws.Server<typeof WebSocket, typeof http.IncomingMessage>;
+
+/**
+ * 「LLM-driven 出卡型 tool」工厂（v2：出参 cards 契约）。
+ *
+ * 适用场景：tool 的 input 字段 = 卡片要渲染的字段（即数据完全由 LLM 从对话上下文
+ * 提取，tool 不需要查询外部数据源）。
+ *
+ * 工厂强制约束：
+ *   1. 出参 = { summary: input, cards: [{ cardType, data: input, note }] }
+ *      （工具出卡契约样板：顶层答话事实 + cards 数组；capture 后模型可见
+ *      cards 为 descriptor 形态，data 已剥离）
+ *   2. execute 透传 input（agent 无法写错数据）
+ */
+declare function coerceStringifiedFields(input: unknown): unknown;
+interface CreateCardToolOptions<TSchema extends ZodTypeAny> {
+    id: string;
+    description: string;
+    inputSchema: TSchema;
+    /** 目标卡片类型（CARD_REGISTRY key） */
+    cardType: string;
+    /** 卡片说明（模型可见 descriptor.note；缺省回退 meta.displayName） */
+    note?: string;
+}
+declare function createCardTool<TSchema extends ZodTypeAny>(opts: CreateCardToolOptions<TSchema>): _mastra_core_tools.Tool<TSchema extends _mastra_core_schema.PublicSchema<any> ? _mastra_core_schema.InferPublicSchema<TSchema> : unknown, unknown, unknown, unknown, _mastra_core_tools.ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
+
+/**
+ * 表单提交虚拟 tool 的 id。
+ * 单一来源，跨 chat-engine / registry / 客户端过滤逻辑共用。
+ */
+declare const FORM_SUBMIT_TOOL_ID = "__a2uiFormSubmit";
+/**
+ * 内部工具：卡片表单提交虚拟桥。
+ *
+ * 用户在卡片里点提交时，服务端通过 ChatEngine.submitForm() 把表单数据作为此工具的
+ * "虚拟 tool result" 注入会话历史。模型从未主动调用此工具，仅在上下文中读到结果
+ * 并据此继续响应。
+ */
+declare const formSubmitTool: _mastra_core_tools.Tool<{
+    surfaceId: string;
+    formId: string;
+}, Record<string, unknown>, unknown, unknown, _mastra_core_tools.ToolExecutionContext<unknown, unknown, unknown>, "__a2uiFormSubmit", unknown>;
+
+/**
+ * 卡片快照恢复（001 §7.4 / 004 W1）：
+ *   migrate(schemaVersion ?? 0) → dataSchema.safeParse
+ *   失败 → { status: 'error', error: '卡片数据已不兼容' }（不白屏）
+ *   成功 → isHistory: true（历史恢复卡片禁交互）
+ * 由 conversation route 对每条消息的 inputs.cards 调用（服务端恢复，schema 迁移一期即启用）。
+ */
+declare function restoreCardSnapshot(snapshot: CardSnapshot, registry: {
+    resolve(cardType: string): CardMeta | undefined;
+}): TboxCardPayload;
+/** TboxCardPayload → CardSnapshot（写快照用） */
+declare function toCardSnapshot(payload: TboxCardPayload): CardSnapshot;
+
+/**
+ * 卡片持久化后端抽象（004 W1 / D1）。
+ *
+ * 双实现：
+ * - MessageEmbeddedBackend（默认）：卡片随 saveMessage 的 `inputs.cards` 持久化，
+ *   与 query/answer 同源提交（外层 chat-engine 将本轮 run 缓冲折叠进 saveMessage）。
+ *   本实现 save 为 no-op（卡片已随消息落库），load 返回空（恢复走平台消息回传）。
+ * - FileCardPersistenceBackend（兜底）：独立落盘，V1（平台拒绝扩展字段）失败时切换。
+ *
+ * 切换收敛为装配端一行：apps/server/src/app.ts 的 saveMessage handler 选择走 inputs 还是落盘。
+ *
+ * 006 评审 P2-1：`sessionId` 参数名为历史键名，**语义为会话键 = conversationId（006 D5，
+ * 运行+持久化统一）**。接口名保留（第三方实现兼容），调用方传 conversationId/线程键。
+ */
+interface CardPersistenceBackend {
+    save(args: {
+        sessionId: string;
+        runId: string;
+        cards: CardSnapshot[];
+    }): Promise<void>;
+    load(sessionId: string): Promise<CardSnapshot[]>;
+}
+/** MessageEmbedded：卡片折叠进 saveMessage（004 D1 默认策略） */
+declare class MessageEmbeddedBackend implements CardPersistenceBackend {
+    save(_args: {
+        sessionId: string;
+        runId: string;
+        cards: CardSnapshot[];
+    }): Promise<void>;
+    load(_sessionId: string): Promise<CardSnapshot[]>;
+}
+/** FileSnapshot：独立落盘兜底（V1 失败时切换） */
+declare class FileCardPersistenceBackend implements CardPersistenceBackend {
+    private dir;
+    constructor(dir?: string);
+    private fileFor;
+    save(args: {
+        sessionId: string;
+        runId: string;
+        cards: CardSnapshot[];
+    }): Promise<void>;
+    load(sessionId: string): Promise<CardSnapshot[]>;
+}
+
+/** 快捷指令（chat.json quickCommands 元素；独立真源——不再自组件配置面承载） */
+interface QuickCommand {
+    label: string;
+    query: string;
+    [k: string]: unknown;
+}
+interface LoadedChatConfig {
+    enableImageUpload: boolean;
+    enableVideoUpload: boolean;
+    enableTTS: boolean;
+    enableVoiceInput: boolean;
+    defaultInputMode: 'TEXT' | 'VOICE';
+    quickCommands: readonly QuickCommand[];
+}
+declare function loadChatConfig(configDir: string): LoadedChatConfig;
+/** LoadedChatConfig → WS HELLO chatConfig（闭合形状，typecheck 恒守护）：
+ *  query→prompt 映射 + 扩展字段剥离 + settings 五键 pick（白名单单点——演进规则见 contracts 注释）。
+ *  纯函数零日志（build-app-image smoke canary 断言启动日志无 WARN [app-config]）。 */
+declare function toWsChatConfig(cfg: LoadedChatConfig): HelloAckChatConfig;
+
+/** SDK 默认业务段（agent.jsonc 未配置/坏档时的兜底；单行身份句） */
+declare const DEFAULT_INSTRUCTIONS = "\u4F60\u662F\u667A\u80FD\u52A9\u624B\uFF0C\u5E2E\u52A9\u7528\u6237\u5B8C\u6210\u65E5\u5E38\u95EE\u7B54\u4E0E\u4E1A\u52A1\u4E8B\u52A1\u3002";
+interface LoadedAgentPromptConfig {
+    /** 恒有值：配置行数组拼接或 SDK 默认 */
+    instructions: string;
+    /** 可选：记忆域业务措辞（消费方 = build-engine memory 装配态追加；缺席 = 不追加） */
+    memoryInstructions?: string;
+}
+declare function loadAgentPromptConfig(configDir: string): LoadedAgentPromptConfig;
+
+/** 工具 execute 第二参的结构型投影（只声明读取器消费的形状） */
+interface ToolExecContextLike {
+    requestContext?: {
+        get(key: string): unknown;
+    };
+    toolCallId?: string;
+    agent?: {
+        toolCallId?: string;
+    };
+}
+interface ToolRunMetadata {
+    runId: string;
+    threadKey: string;
+    toolCallId: string;
+}
+/** Read trusted producer metadata from the execute context, never from model arguments. */
+declare function getToolRunMetadata(execCtx: ToolExecContextLike | undefined): Readonly<ToolRunMetadata> | undefined;
+/**
+ * 从工具 execute 第二参读取运行上下文（散键组装）。
+ * 返回 undefined 当 requestContext 缺失或 identity 键缺失（引擎外直调/匿名无身份）。
+ */
+declare function getToolRequestContext(execCtx: ToolExecContextLike | undefined): Readonly<RequestContext$1> | undefined;
+/**
+ * 严格变体：运行上下文缺失时抛 AUTH_FORBIDDEN（fail-visible——显式正确性优于静默降级）。
+ * @param toolId 诊断信息（缺失文案指明哪个工具、怎么修）
+ */
+declare function requireToolRequestContext(execCtx: ToolExecContextLike | undefined, toolId?: string): Readonly<RequestContext$1>;
+/**
+ * 测试/直调助手：由 plain RequestContext 构造工具 execute 第二参形态。
+ * 散键写入与引擎 buildRunRequestContext 同构（往返由 context-concurrency.test C2 锁定）。
+ */
+declare function createToolExecContext(reqCtx: RequestContext$1): ToolExecContextLike;
+
+interface SaveMessageParams {
+    conversationId: string;
+    agentId: string;
+    query: string;
+    answer: string;
+    outerBusinessId?: string;
+    multiModalInputs?: Record<string, unknown>;
+    /** 平台消息 inputs（cards/skills/preTools 等）——宽松类型对齐 SDK MessageSaveRequest.inputs
+     *  （P3 W1：卡片快照随消息持久化，004 D1 MessageEmbedded） */
+    inputs?: Record<string, unknown>;
+    /** 兜底：平台拒绝 inputs 时以字符串承载（JSON 序列化卡片） */
+    extraParams?: string;
+}
+interface ListMessagesParams {
+    agentId: string;
+    conversationId?: string;
+    userId?: string;
+    beforeId?: string;
+    pageNo?: number;
+    pageSize?: number;
+}
+declare class ConversationService {
+    private client;
+    constructor(apiKey: string);
+    /** 查找用户已有会话，没有则创建新会话 */
+    getOrCreateConversation(agentId: string, userId: string): Promise<string>;
+    createConversation(agentId: string, userId: string): Promise<string>;
+    saveMessage(params: SaveMessageParams): Promise<string>;
+    listMessages(params: ListMessagesParams): Promise<node_modules__tbox_cn_app_sdk_server_src_upstream.PaginationResult<node_modules__tbox_cn_app_sdk_server_src_upstream.MessageInfo>>;
+}
+
+interface PlatformApiRouterDeps {
+    /** ServerContext：会话路由内部化卡片恢复（restoreCardSnapshot(snap, ctx.cards)） */
+    ctx: ServerContext;
+    /** 统一鉴权运行时（006）：router（login/dev-login/me） */
+    auth: AuthRuntime;
+    /**
+     * 长期记忆存储（017）：传入则挂载 GET/DELETE /api/memory 管理面（与引擎同源实例）。
+     * 缺省不挂载（未装配记忆的应用路由面零变化）。
+     */
+    memory?: MemoryStore;
+}
+/**
+ * 平台 API 路由装配（003/006 平台轴）。
+ * ⚠️ 挂载顺序契约（H2）：本工厂**不挂全局 auth.middleware**——由组装端（apps/server/index.ts）
+ * 先挂 `app.use('/api', auth.middleware)`，再挂 `/api/m`、`/api/action`，最后挂本路由，
+ * 保证模块 API / 动作网关同样受全局鉴权约束，不产生鉴权缺口。
+ * 本工厂只挂业务路由 + 404 兜底。
+ */
+declare function createPlatformApiRouter(deps: PlatformApiRouterDeps): Router;
+
+interface ConversationRouterDeps {
+    /** ServerContext（卡片注册表）：卡片快照恢复内部化——restoreCardSnapshot(snap, ctx.cards)，闭包延迟解析 */
+    ctx: ServerContext;
+}
+declare function createConversationRouter(deps: ConversationRouterDeps): Router;
+
+/**
+ * 记忆管理面 HTTP 路由（017 SPEC-8）：GET/DELETE /api/memory——用户查看/删除自己的长期记忆。
+ *
+ * 设计要点：
+ * - 挂载：createPlatformApiRouter({ ctx, auth, memory? })——memory 缺省不挂载（向后兼容）；
+ * - 鉴权：全局 authMiddleware 已注入身份（H2 挂载顺序契约）；匿名 → 403（INV-3 HTTP 面）；
+ * - 能力门控：caps.list/delete=false → 501 + MEMORY_ERROR_CODES（不触达 store——缺口期诚实降级）；
+ * - scope query 参数：urlencoded JSON 防御解析（malformed → 400）；
+ * - kind 过滤：路由层对结果 filter（管理面分类查询——极简实现，不进契约）；
+ * - 归属校验：store.delete 按 userId+scope+id（INV-2；false → 200 + { deleted: false }）。
+ */
+
+interface MemoryRouterDeps {
+    /** 记忆存储（引擎同源实例——管理面与 run 期读写同一存储） */
+    store: MemoryStore;
+}
+declare function createMemoryRouter(deps: MemoryRouterDeps): Router;
+
+declare const healthRouter: Router;
+
+declare const router: Router;
+
+/**
+ * TTS WebSocket proxy.
+ * Client connects to /ws/tts, server proxies to mediafeature upstream.
+ *
+ * Flow: client START_TTS -> server fetches auth -> connects upstream -> sends init payload
+ *       -> upstream replies start_ack -> server forwards to client
+ *       -> client sends TTS_TEXT -> server forwards to upstream (only after start_ack)
+ */
+declare function createTtsProxy(): ws.Server<typeof WebSocket, typeof http.IncomingMessage>;
+
+/**
+ * Get lazily-initialized TboxTtsClient.
+ *
+ * Uses TboxTtsClient.create() factory which internally calls
+ * TboxAppClient.generateSession() to obtain sessionId + channel,
+ * then constructs the client with proper session credentials
+ * for fetchAuth() to work.
+ */
+declare function getTtsClient(): Promise<TboxTtsClient>;
+/**
+ * Reset cached TTS client so the next getTtsClient() call
+ * creates a fresh one with a new session.
+ */
+declare function resetTtsClient(): void;
+
+interface ModelProviderOptions {
+    /** llm_provider.json 路径（缺省 <cwd>/../../config/llm_provider.json） */
+    configPath?: string;
+}
+interface ModelProvider {
+    getModel(modelName: string): LanguageModel;
+    /** 模型名单点解析（config modelName ?? env APP_AI_MODEL_NAME）——与 getModel 同链，装配端记录用 */
+    resolveModelName(): string;
+}
+declare function createModelProvider(options?: ModelProviderOptions): ModelProvider;
+
+/**
+ * 宿主应用唯一的插件装配入口（平台轴）。公共包负责配置解析、元数据和执行协议；
+ * 组装端只注入自己的配置路径与凭证，不在业务代码中直接创建 SDK client。
+ *
+ * config 路径用 process.cwd() 相对（dev 从 apps/server/ 跑 tsx，prod 从 apps/server/ 跑 node dist/index.js），
+ * 避免 import.meta.url 在 tsup 打包后指向 dist/ 导致路径层级变化。
+ * 扩展点：createPluginIntegration({ configPath, apiKey }) 覆盖配置路径与凭证函数。
+ */
+interface PluginIntegrationOptions {
+    /** plugins.json 路径（缺省 <cwd>/../../config/plugins.json） */
+    configPath?: string;
+    /** TBOX_API_KEY 读取函数（缺省 () => process.env.TBOX_API_KEY） */
+    apiKey?: () => string | undefined;
+}
+interface LoadedPluginTools {
+    tools: Record<string, AnyTool>;
+    references: {
+        kind: 'plugin';
+        pluginId: string;
+        toolId: string;
+        runtimeId: string;
+    }[];
+}
+declare function createPluginIntegration(options?: PluginIntegrationOptions): {
+    /** 底层 @tbox.cn/agent-plugin 集成实例（cli 工具 / 高级场景用） */
+    integration: _tbox_cn_agent_plugin.PluginIntegration;
+    /** 插件配置读取（cli 工具用） */
+    readConfig: () => _tbox_cn_agent_plugin.ParsedPluginsConfig;
+    /** 业务 workflow 主动调用已配置插件工具的稳定入口 */
+    runConfiguredTool: <T = unknown>(reference: ConfiguredPluginToolReference, input: Record<string, unknown>) => Promise<PluginRunResult<T>>;
+    /**
+     * 加载配置插件工具（自注册闭环的 loadPlugins 注入点）。
+     * reservedToolIds 由组装端从 ctx.tools 计算，避免插件与静态工具 id 冲突。
+     */
+    loadTools: (opts: {
+        reservedToolIds: string[];
+    }) => Promise<LoadedPluginTools>;
+};
+
+/** 安装器依赖（auth 只取 middleware——最小面） */
+interface InstallTboxDevDeps {
+    ctx: ServerContext;
+    auth: Pick<AuthRuntime, 'middleware'>;
+}
+declare function installTboxDev(app: Express, deps: InstallTboxDevDeps): void;
+
+/**
+ * dev 卡片预览纯核（零 express 依赖——node 直测前提）。
+ *
+ * - buildCatalog：ctx.cards 注册表真实态 → 预览目录（统一样本模型：初始态恒第一位 +
+ *   逐样本 schema 校验 / shape 断言 / 信封投影，质量问题以 issues/envelopeError 承载不阻断）；
+ * - executePreviewAction：dev 端点直调 action.execute——**镜像 dispatcher 护栏语义，
+ *   刻意跳过 grant/singleUse/幂等**（本地模拟语境下这些护栏无意义：token 由客户端铸造、
+ *   无 WS 会话域）；结果 update/card 经目标卡 dataSchema 校验 + project 重投影后
+ *   返回完整 TboxCardPayload。
+ */
+
+/** dev 预览动作业务失败（安装器映射 HTTP status + code；code 表为页面契约，增删须回规格层） */
+declare class PreviewActionError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+
+/**
+ * 样本 shape 覆盖断言（dev 卡片预览配套）：样本键 ⊆ dataSchema shape。
+ *
+ * 拦截面定位（刻意收窄）：
+ * - zod object 默认 strip 模式会**静默剥离** schema 外的键——safeParse 通过不代表
+ *   样本全量生效；本函数抓「样本含 shape 外键」（BASE-spread 绕过 TS freshness
+ *   检查的惯用漂移 + schema 宽松构造），供模块 samples.test.ts 与 buildCatalog 双消费；
+ * - **不宣称完备**：union/record/intersection/lazy/tuple 及无法识别的节点整子树跳过并计入
+ *   blindSpots 报告（无法机械判定分支选择/开放键集——zod 3.25 起 ZodRecord 亦带 .element，
+ *   以值形态区分：对象值记盲区），类型正确性仍由 TS + safeParse 兜底；
+ * - passthrough object 的开放键会被误报为 violation（zod 3 无公开 duck 面可探测 unknownKeys，
+ *   无法与 strip 区分）——当前全仓 CardMeta dataSchema 无 passthrough 使用面；真出现时以
+ *   safeParse 通过为准豁免该报告。
+ *
+ * 跨包安全（铁律）：节点判定一律**结构探测（duck-typing）**——`'shape' in schema` /
+ * `schema.unwrap?.()` / `schema.element` / `schema.options` / `schema.schema`；
+ * **全禁 `instanceof z.*` 与 `_def` 私有字段**：pnpm 依赖隔离下模块与 SDK 可能各持
+ * 一份 zod 副本（同版本 ≠ 同构造器），instanceof 必然误判；这是平台首个跨包
+ * schema 结构内省，双 zod 实例行为由 sample-shape.test.ts 钉住。
+ */
+
+/** 样本含 shape 外键（会被 strip 静默剥离） */
+interface SampleShapeViolation {
+    /** 样本名（sampleData 记为「初始态」） */
+    label: string;
+    /** 违规键所在路径（根为空串） */
+    path: string;
+    /** 违规键名 */
+    key: string;
+}
+/** 无法机械判定的子树（报告不宣称完备的载体） */
+interface SampleShapeBlindSpot {
+    label: string;
+    path: string;
+    reason: string;
+}
+interface SampleShapeReport {
+    violations: SampleShapeViolation[];
+    blindSpots: SampleShapeBlindSpot[];
+}
+/**
+ * meta 级全样本断言：sampleData（记「初始态」）+ meta.samples 逐样本探测。
+ * 返回 violations（须修）与 blindSpots（如实报告，不算失败）。
+ */
+declare function findSampleShapeViolations(meta: CardMeta): SampleShapeReport;
+
+export { type AnyTool, BROAD_ROUTING_TERMS, BUILTIN_HYGIENE_NAMES, type BootstrapMemoryKbOptions, type BootstrapMemoryKbResult, type BuildEngineOptions, CARDS_SPEC, CARD_DECISION_HOLD_LIMIT, CARD_DECISION_TAG, CARD_EMISSION_HINT_ACTIONS, CARD_EMISSION_HINT_BASE, CARD_EMISSION_HINT_KEYWORD, type CardDecisionPlan, type CardDecisionStripper, type CardPersistenceBackend, type CardPool, type CardPoolOptions, type ChatEngine, type ChatEngineOptions, type ContentPart, type ContentTagHygiene, type ConversationRouterDeps, ConversationService, DECISION_HOLD_LIMIT, DEFAULT_INSTRUCTIONS, DEFAULT_KNOWLEDGE_MEMORY_CAPABILITIES, DEFAULT_LIST_TTL_MS, DEFAULT_LLM_PROVIDER_CONFIG_PATH, DEFAULT_MAX_CARDS_PER_TURN, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_PRE_TOOLS_PER_RUN, DEFAULT_MEMORY_MAX_CHARS_PER_RECORD, DEFAULT_MEMORY_RECALL_TIMEOUT_MS, DEFAULT_MEMORY_TOP_K, DEFAULT_MEMORY_VALIDATE_TIMEOUT_MS, DEFAULT_PRE_TOOL_TIMEOUT_MS, DEFAULT_SKILL_MODE, DROP_BODY_SOFT_LIMIT, EARLY_EXECUTION_MARKER, type EngineModelStepInput, type EngineRunEndInput, type EngineRunInput, type EngineStepControlFactory, type EngineStepControlInput, type EngineStepController, type EngineStepResultInput, type EngineStepToolChoice, type EngineToolCallInput, type EngineToolResultInput, FORM_SUBMIT_TOOL_ID, FileCardPersistenceBackend, HYGIENE_TAG_NORMALIZE, type HygieneTagFamily, INTERNAL_TOOL, type InstallTboxDevDeps, type IntentRoute, KB_SCOPE_GLOBAL, KNOWLEDGE_DEFAULT_BASE_URL, KnowledgeBootstrapError, type KnowledgeMemoryStoreOptions, KnowledgeOpenapiError, type KnowledgeOpenapiTransportOptions, type KnowledgeTransport, type LoadedAgentPromptConfig, type LoadedChatConfig, type LoadedPluginTools, MEMORY_IMPORTANCE_BASE, MEMORY_KB_INDEX_COLUMNS, MEMORY_KB_SCHEMA, MEMORY_KB_SEED_CSV, MEMORY_LIST_DEFAULT_LIMIT, MEMORY_LIST_MAX_LIMIT, MEMORY_MAX_PER_USER, type MemoryEngineOptions, type MemoryFilterColumn, type MemoryGuardDeps, type MemoryGuardEnv, type MemoryPromptCaps, type MemoryRouterDeps, type MemoryStoreEnv, MemoryStoreUnsupportedError, type MemoryToolDeps, MemoryUnavailableError, type MemoryValidateMode, type MemoryValidationOutcome, MessageEmbeddedBackend, type ModelProviderOptions, PRE_TOOL_HISTORY_LIMIT, type ParallelToolCallsControl, type PlatformApiRouterDeps, type PluginIntegrationOptions, type PoolEntry, type PreFilterTerm, type PreToolExecContext, PreToolTimeoutError, PreviewActionError, type QuickCommand, type RecallCacheOptions, type RecallCacheState, type ResolvedTagSpecs, type SampleShapeBlindSpot, type SampleShapeReport, type SampleShapeViolation, type SdkRuntimeOptions, type SdkToolRuntime, type SegmentHit, type SkillInjectionDecision, type SkillMode, type SortTerm, type StoredMemoryRecord, type StreamTagEngine, DEFAULT_FILE_URL_PREFIX as TBOX_FILE_URL_PREFIX, THINK_SPECS, TOOL_CALL_TEXT_SPECS, TOOL_CARDS_FIELD, TOOL_CARD_DESCRIPTOR_SCHEMA, type TagBodyPolicy, type TagEngineFinish, type TagHit, type TagSeal, type TagSource, type TagSpec, type TagTrack, TboxTraceExporter, type ThinkingControl, type ToolCardDescriptor, type ToolCardSpec, type ToolExecContextLike, type ToolRunMetadata, type TurnReminderBlocks, applySkillReminder, bootstrapMemoryKnowledgeBase, buildCardDecisionReminder, buildInjectedUserContent, buildMemoryRecallToolCallEvents, buildMemoryReminder, buildMessageInputs, buildPlatformInstructions, buildPreToolCallEndEvents, buildPreToolCallStartEvents, buildPreToolDirectives, buildRecapUserContent, buildSkillRecapReminder, buildSkillReminder, buildSkillToolCallEvents, buildUserContent, captureToolCards, clampMaxCards, clampMemoryMaxChars, clampMemoryTopK, coerceStringifiedFields, composeTurnUserContent, createCardDecisionStripper, createCardPool, createCardTool, createChatEngine, createConversationRouter, createEngineFromContext, createGatedMemoryStore, createInMemoryMemoryStore, createIntentDispatcher, createKnowledgeMemoryStore, createKnowledgeOpenapiTransport, createMemoryRouter, createMemoryTools, createModelProvider, createPlatformApiRouter, createPluginIntegration, createSdkToolRuntime, createStreamTagEngine, createToolExecContext, createTtsProxy, createWsServer, decideCards, decideSkillInjection, definePreTool, envelopeTag, executePreTool, extractImageUrls, findSampleShapeViolations, formSubmitTool, generateMemoryId, getLastRecallCacheState, getToolRequestContext, getToolRunMetadata, getTtsClient, hardenToolsForLlm, hashContent, healthRouter, hygieneXmlTag, installTboxDev, internalTool, loadAgentPromptConfig, loadChatConfig, loadLocalSkills, loadModuleSkills, matchIntent, memoryStoreCapabilities, mergePreTools, mergeSkills, normalizePreTools, omitInternal, pickFallbackCard, projectHistory, recallMemories, requireToolRequestContext, resetTtsClient, resolveEarlyToolExecution, resolveMaxSteps, resolveMemoryEngineOptions, resolveMemoryRecallTimeout, resolveMemoryStore, resolveMemoryStoreGuarded, resolveMemoryValidateMode, resolveMemoryValidateTimeout, resolvePreToolTimeout, resolveSkillMode, resolveTagSpecs, resolveToolDebug, restoreCardSnapshot, sanitizeLlmToolInput, scanInjectedSkills, scopeToKey, selectPreTools, selectSkill, stableStringify, stripSystemReminderBlocks, router as tboxSessionRouter, tboxTraceExporter, toCardSnapshot, toMastraSkill, toWsChatConfig, tokenizeTagBody, toolCardScope, validateMemoryKnowledgeBase, withCardEmissionHint, withDeadline, withEarlyExecution, withLlmInputSanitize, withRecallCache, wrapToolsForCardCapture, xmlTag, xmlTagDecision };