@tbox.cn/app-sdk-server 0.21.0

package/dist/server/index.d.ts

@@ -0,0 +1,2179 @@
+import * as _tbox_cn_app_contracts from '@tbox.cn/app-contracts';
+import { CardMeta, Identity, ExternalCredentials, TboxCardPayload, RequestContext, ServerEvent, AuthenticatedTransport, ProviderCredential, IdentityExchange, ProviderErrorCode, ProviderInstance, ProviderTemplateDeclaration, DeploymentInstance, ProviderInstanceDeclarations, IntegrationsConfig, ProviderCatalog, CardActionResult, ScopeAssemblyContract, MemoryStore, TboxNoticePayload, AuthErrorCode, TokenPayload, ModuleConfig, ExchangeRequest, ExchangeResult } from '@tbox.cn/app-contracts';
+export { HostEffect, SKILL_NAME_PATTERN, assertNoInlineSecrets, parseIntegrationsConfig } from '@tbox.cn/app-contracts';
+import { Router, Request, RequestHandler } from 'express';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { TboxLogger, LogContext } from '@tbox.cn/app-sdk-core';
+export { InferModuleCards, LogContext, LogLevel, TboxLogger, createLogger } from '@tbox.cn/app-sdk-core';
+import { z } from 'zod';
+export { buildOwnershipMap, loadProviderCatalog } from '@tbox.cn/app-toolkit';
+
+type EventMap = Record<string, unknown>;
+interface TypedBus<TMap extends EventMap> {
+    on<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void): () => void;
+    /** 同步派发（fire-and-forget；异步 handler 不阻塞） */
+    emit<K extends keyof TMap>(event: K, payload: TMap[K]): void;
+    off<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void): void;
+    clear(): void;
+    /** publish = async emit（B1：Promise.allSettled 聚合，await 全部异步 handler） */
+    publish<K extends keyof TMap>(event: K, payload: TMap[K]): Promise<void>;
+    /** subscribe = on，返回取消订阅函数 */
+    subscribe<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void | Promise<void>): () => void;
+}
+declare function createTypedBus<TMap extends EventMap>(): TypedBus<TMap>;
+
+declare class ServiceRegistry {
+    private services;
+    register<T>(id: string, impl: T): void;
+    resolve<T>(id: string): T | undefined;
+    clear(): void;
+    getAll(): Record<string, unknown>;
+}
+declare function registerService<T>(id: string, impl: T): void;
+declare function resolveService<T>(id: string): T | undefined;
+declare function clearServices(): void;
+
+/**
+ * 注册表工具结构类型（通用侧，零 mastra）：
+ * agent 工具工厂（mastra createTool 等）产出物结构兼容本接口——存储/协议面只认结构，
+ * marker（INTERNAL_TOOL/EARLY_EXECUTION_MARKER 等 symbol 键）经 Map 原样透传，类型面不声明。
+ * mastra 泛型擦除别名 AnyTool 在 agent 包（app-agent-sdk-server create-module-tool.ts）。
+ */
+interface RegistryTool {
+    id: string;
+    description?: string;
+    /** standard schema（zod 等；由 agent 工具工厂产出；mastra 1.59 Tool 上为可选属性） */
+    inputSchema?: unknown;
+    /**
+     * 存储面（注册表/装配校验）从不调用执行；签名用方法双变 + never 参数声明，
+     * 兼容 mastra 具体签名（真实调用在 agent 侧执行段，直调具体 tool 实例）。
+     */
+    execute?(args: never, context: never): unknown;
+}
+/**
+ * ToolRegistry：LLM function calling 工具注册（无状态）。
+ * 模块在 registerServer(ctx) 内 ctx.tools.register(tool)，
+ * ChatEngine 构建时经 getAll() 聚合（agent 侧负责向 mastra 形状收敛）。
+ */
+declare class ToolRegistry {
+    private tools;
+    private disabled;
+    /** 禁止某工具进入运行时工具集；由 provider 在模块注册前声明能力边界。 */
+    disable(toolId: string): void;
+    register(tool: RegistryTool): void;
+    registerAll(tools: RegistryTool[]): void;
+    resolve(id: string): RegistryTool | undefined;
+    getAll(): Record<string, RegistryTool>;
+    has(id: string): boolean;
+    get size(): number;
+}
+
+/**
+ * CardRegistry：卡片元数据注册（cardType → CardMeta，无状态）。
+ * 模块在 registerServer(ctx) 内 ctx.cards.register(meta) 注册数据契约。
+ */
+declare class CardRegistry {
+    private cards;
+    private disabled;
+    /** 属主记账（cardType → moduleId；registerServerModules 逐模块写入） */
+    private owners;
+    /** 禁止某卡型进入服务端候选池；可由 provider 在模块注册前声明能力边界。 */
+    disable(cardType: string): void;
+    register(meta: CardMeta): void;
+    registerAll(metas: CardMeta[]): void;
+    /**
+     * 按 map 批量注册（模块 serverModule.cards 形态）。
+     * key 约定 = meta.cardType；不一致时告警并仍按 meta.cardType 注册
+     * （doctor 规则 card-type-consistent 会对 key !== cardType 报 error，此处仅运行时兜底）。
+     */
+    registerMap(metas: Record<string, CardMeta>): void;
+    resolve(cardType: string): CardMeta | undefined;
+    /**
+     * 属主记账（dev 卡片预览页消费）：键 = meta.cardType（与 registerMap 同语义——
+     * key≠cardType 时仍按 meta.cardType 注册，此处必须对齐否则属主错位）。
+     * 幂等覆盖（同 cardType 后写胜出，与 register 覆盖语义对齐）；disable 不清表
+     * （disabled 卡不进 getAll，无消费面）。
+     */
+    recordOwner(cardType: string, moduleId: string): void;
+    /** 读取属主模块 id（未记账返回 undefined；消费端兜底 '(未声明)'） */
+    ownerOf(cardType: string): string | undefined;
+    getAll(): Record<string, CardMeta>;
+    has(cardType: string): boolean;
+    get size(): number;
+}
+
+/**
+ * Skill 领域类型面（通用侧，零 mastra / 零 IO）：
+ * LocalSkill / 资源限额 / 名称强校验同源 re-export。
+ * 自 skill-loader.ts 拆出（agent-sdk 拆分准备）：模块系统（ServerContext.skills、
+ * SkillRegistry、module-assembly 校验）仅依赖本类型面；文件加载与 mastra 转换
+ * （loadLocalSkills/toMastraSkill/loadModuleSkills）留 skill-loader.ts（agent 侧）。
+ */
+
+/**
+ * 本地 Skill 领域类型（009：LocalSkill 一统文件 loader 与模块声明产出）。
+ * mastra 类型（InlineSkill/SkillInput）完全封在 skill-loader 模块，模块/模板零感知。
+ */
+interface LocalSkill {
+    /** skill 名（^[a-z0-9-]{1,64}$，reminder 开标签解析安全锚） */
+    name: string;
+    /** 描述（≤ SKILL_LIMITS.description） */
+    description: string;
+    /** 本地打分路由词（accelerated 模式命中依据；空 → warn，不可命中） */
+    routingTerms: string[];
+    /** SKILL.md 正文（SOP；超 SKILL_LIMITS.instructions → warn） */
+    instructions: string;
+    /** 参考资料（key = 相对 references/ 的路径，以 .md 结尾；随 skill 内存化加载） */
+    references: Record<string, string>;
+}
+/** 资源限额（超限 warn 不阻断；运行期恒等加载，与路径无关） */
+declare const SKILL_LIMITS: {
+    readonly description: 1024;
+    readonly instructions: number;
+    readonly references: 64;
+    readonly referenceSize: number;
+};
+
+/**
+ * SkillRegistry：本地 skill 注册表（模块声明式主通道 009 D6，与 CardRegistry 对齐）。
+ * - name 非法（非 ^[a-z0-9-]{1,64}$）→ warn 跳过（reminder 解析安全锚）；
+ * - 重名 → warn 覆盖（模块先插、应用覆盖由 build-engine 合并保证，此处仅兜底）；
+ * - references key 非 .md 结尾 → warn（skill_read 引用键约定）。
+ */
+declare class SkillRegistry {
+    private skills;
+    register(skill: LocalSkill): void;
+    registerAll(skills: LocalSkill[]): void;
+    /** 按 map 批量注册（模块 serverModule.skills 形态；key 约定 = skill.name） */
+    registerMap(skills: Record<string, LocalSkill>): void;
+    getAll(): LocalSkill[];
+    has(name: string): boolean;
+    get size(): number;
+}
+
+/**
+ * 前置工具声明类型面（通用侧，零 mastra）：
+ * PreToolDef / 路由 / 决策 / decide 入参 / 历史投影 / 用户与地理位置扩展。
+ * 自 pre-tool-router.ts 拆出（agent-sdk 拆分准备）：模块系统（ServerContext.preTools、
+ * PreToolRegistry、module-assembly 校验）仅依赖本类型面；score/decide/execute 执行段
+ * 留 pre-tool-router.ts（agent 侧）。
+ *
+ * args 类型参数化（TArgs）：mastra 泛型提取版推断在 agent 侧 definePreTool
+ * （pre-tool-router.ts InferToolArgsMastra——1.57 实证不能走 inputSchema 属性推导）；
+ * 手写 PreToolDef 场景缺省 Record<string, unknown>。
+ */
+
+/**
+ * 前置工具声明（模块 serverModule.preTools / 应用级 BuildEngineOptions.preTools）。
+ * tool 引用工具实例 = 单一真源（id/description 派生，D1）；key 约定 = tool.id（与 cards key=cardType 对齐）。
+ */
+interface PreToolDef<T extends RegistryTool = RegistryTool, TArgs extends Record<string, unknown> = Record<string, unknown>> {
+    /** 工具实例引用（build-engine 校验 tools[def.tool.id] === def.tool 实例一致性，D9） */
+    tool: T;
+    /**
+     * 结构化路由（D2）：
+     * - { mode: 'always' }：必选候选（每轮进入 decide；执行与否由 decide 门控——慎用，防噪音）；
+     * - { mode: 'keywords'; terms }: 宽召回词表（与 skill 同源打分），命中 score > 0 才候选。
+     */
+    routing: PreToolRouting;
+    /**
+     * 决策即构造（D3）：返回 { decision: 'run', args } → 预执行该工具；
+     * { decision: 'skip', reason? } → 本轮不生效（reason 仅 span 观测，不刷日志）。
+     * 运行期（run 窗口内）调用；不得抛（SDK 兜底 warn + skip）；args 必须 JSON 可序列化；
+     * 坏形状返回（非对象/run 缺 args）→ warn + skip（D10）。
+     */
+    decide: (input: PreToolDecideInput) => PreToolDecision<TArgs> | Promise<PreToolDecision<TArgs>>;
+    /**
+     * 静默前置工具（011 D2/D9，FAQ 检索通道）：
+     * - 不发 START/ARGS/END 前端事件（无「自动查询中」spinner）；
+     * - 结果不落 inputs.preTools（历史不重建 tool-call 表达）；
+     * - 仅本轮 `<system-reminder pre-tool="...">` 数据块注入 LLM 上下文。
+     */
+    silent?: boolean;
+    /**
+     * 会话内入参去重（B3，session-args dedup）：
+     * - 键 = `${tool.id}\u0000${stableStringify(args)}`（decide 产出 args 序列化——**按入参去重，
+     *   出参不进键**；mallId 等上下文入参化后「结果由入参决定」是去重前提不变量）；
+     * - 同 thread 会话内已落键 → decide 照跑（保留 span 观测）但 execute 跳过（journal
+     *   outcome='skip' reason='session-dedup'）；
+     * - 落键时点 = history.push 之后（不变量：preToolDone 键集 ⊆ history 实际注入块——
+     *   注入前 abort 不落键，重试语义干净）；
+     * - accepts（可选）：落键前对 stripped result 验收（如空结果 false 不落键 → 下轮重试）。
+     *   只影响落键，不影响本轮注入（空结果照常注入，模型按注入块协议降级）。
+     * - 适用前提（文档契约）：结果会话级稳定的字典类数据（mall-context 等）；时效敏感工具禁配。
+     *   staleness 边界 = 会话时长 + provider 缓存 TTL（显式接受，无 TTL 兜底）。
+     * - 并发假设：同 thread 单活跃 run（abortControllers 单条目/线程）——无锁 check→set 安全。
+     */
+    dedup?: {
+        accepts?: (result: unknown) => boolean;
+    };
+}
+/** 路由判别联合（D2）：字符串字面量，非 enum */
+type PreToolRouting = {
+    mode: 'always';
+} | {
+    mode: 'keywords';
+    terms: string[];
+};
+/** 决策结果判别联合（D3）：skip = 不执行（reason 仅 span 观测）；run = 执行 + 强类型参数 */
+type PreToolDecision<Args extends Record<string, unknown>> = {
+    decision: 'skip';
+    reason?: string;
+} | {
+    decision: 'run';
+    args: Args;
+};
+/**
+ * 从工具类型提取输入参数类型（通用兜底版，standard-schema 协议）：
+ * mastra 泛型参数提取版在 agent 侧（pre-tool-router.ts InferToolArgsMastra）——
+ * 1.57.0 实证 inputSchema 属性推导不可靠，本版仅服务 standard-schema 形状的工具。
+ */
+type InferToolArgs<T extends RegistryTool> = T['inputSchema'] extends {
+    '~types': {
+        output: infer O;
+    };
+} ? O extends Record<string, unknown> ? O : Record<string, unknown> : Record<string, unknown>;
+/** 决策入参（运行期，与 handle 同级） */
+interface PreToolDecideInput {
+    /** 原始用户文本（与打分同源） */
+    text: string;
+    /**
+     * 多轮对话历史投影（只读、不含本轮）：text part 过滤拼接 + 截断
+     * PRE_TOOL_HISTORY_LIMIT（decide 工程化决策上下文，非模型上下文）。
+     */
+    history: readonly PreToolHistoryTurn[];
+    /** 会话标识（threadKey；匿名连接 fallback） */
+    conversationId?: string;
+    /**
+     * 模块上下文（build-engine 装配路径恒有）；ctx.auth 已拆除（0.11.0）——
+     * 身份类决策用 identity、领域属性用 attributes；createChatEngine 直调路径可不传
+     * （decide 内对 ctx 使用需自行判空）。
+     */
+    ctx?: ServerContext;
+    /** per-run 显式身份（并发安全首选） */
+    identity?: Identity;
+    /** 外部凭据（同 runCtx 透传） */
+    credentials?: ExternalCredentials;
+    /**
+     * 连接级领域属性（上下文统一化 Stage 1，源自 runCtx.attributes）：decide 内经
+     * 领域 slot 读取（如 mallSlot.read(input.attributes)）——替代旧 ctx.auth 全局读取。
+     */
+    attributes?: Record<string, unknown>;
+    /** 当前用户信息（平台注入扩展点；缺省 undefined） */
+    user?: PreToolUserContext;
+    /** 地理位置（平台注入扩展点；缺省 undefined） */
+    location?: PreToolLocationContext;
+}
+/** 当前用户信息（平台注入扩展点；形状由平台方定义，模块按需读取） */
+interface PreToolUserContext {
+    userId: string;
+    [key: string]: unknown;
+}
+/** 地理位置（平台注入扩展点；形状由平台方定义，模块按需读取） */
+interface PreToolLocationContext {
+    city?: string;
+    [key: string]: unknown;
+}
+/** 历史投影单轮（轻量文本化：role + content，不含工具 part） */
+interface PreToolHistoryTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+
+/**
+ * PreToolRegistry：前置工具声明注册表（010，与 SkillRegistry 对齐）。
+ * - tool.id 非法（非 ^[A-Za-z0-9_-]{1,64}$）→ warn 跳过；
+ * - keywords 路由空 terms → warn 跳过（恒不命中，声明错误早暴露）；
+ * - 重名（tool.id）→ warn 覆盖（模块先插、应用覆盖由 build-engine 合并保证，此处兜底）。
+ */
+declare class PreToolRegistry {
+    private preTools;
+    register(def: PreToolDef): void;
+    registerAll(defs: PreToolDef[]): void;
+    /** 按 map 批量注册（模块 serverModule.preTools 形态；key 约定 = tool.id） */
+    registerMap(map: Record<string, PreToolDef>): void;
+    getAll(): PreToolDef[];
+    has(toolId: string): boolean;
+    get size(): number;
+}
+
+/**
+ * ApiRouteRegistry：后端 HTTP API 路由注册。
+ * 模块注册的 basePath 强制落在 `/api/m/<moduleId>/` 命名空间（001 §4.2）。
+ *
+ * register() 直接写入内部共享 root Router——组装端可在 registerAll 前先
+ * app.use('/api/m', ctx.routes.mount())，模块随后注册仍即时生效（无需动态分发）。
+ */
+declare class ApiRouteRegistry {
+    private root;
+    private moduleIds;
+    /** moduleId 如 "member" / "points-parking"，router 内定义 `/xxx` 子路径 */
+    register(moduleId: string, router: Router): void;
+    /** 挂载到应用：app.use('/api/m', ctx.routes.mount())。返回共享 root，后续注册即时生效。 */
+    mount(): Router;
+    getModuleIds(): string[];
+}
+
+/**
+ * CardSnapshotStore 接口：卡片快照持久化。
+ * 业务模块可提供实现，SDK 默认提供内存实现。
+ * 006 评审 P2-1：`sessionId` 键语义 = 会话键（conversationId，006 D5）；接口名保留兼容。
+ */
+interface CardSnapshotStore {
+    save(sessionId: string, card: TboxCardPayload): Promise<void>;
+    load(sessionId: string): Promise<TboxCardPayload[]>;
+    clear(sessionId: string): Promise<void>;
+}
+/** 内存实现（默认） */
+declare class InMemoryCardSnapshotStore implements CardSnapshotStore {
+    private store;
+    save(sessionId: string, card: TboxCardPayload): Promise<void>;
+    load(sessionId: string): Promise<TboxCardPayload[]>;
+    clear(sessionId: string): Promise<void>;
+}
+
+/**
+ * 幂等存储（004 W2 C3）。
+ * 接口化 + InMemory（键 → 结果缓存，TTL + LRU 上限），可换 Redis。
+ * 语义：幂等 = "写几次"（业务一致性）；幂等键命中且 payload 一致 → 返回首次结果（200-cached）。
+ */
+interface IdempotencyStore {
+    /** 尝试占位幂等键：不存在则占位成功（返回 undefined）；存在则返回已缓存结果 */
+    tryAcquire(key: string, payloadHash: string): Promise<{
+        acquired: true;
+    } | {
+        acquired: false;
+        result: unknown;
+    }>;
+    /** 完成后写入结果 */
+    commit(key: string, result: unknown): Promise<void>;
+    /** 检查键当前占位的 payloadHash（网关 409 判定用；可选能力） */
+    getPayloadHash?(key: string): string | undefined;
+    /** 释放占位（校验失败时回滚；可选能力） */
+    release?(key: string): void;
+}
+declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private store;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    constructor(opts?: {
+        ttlMs?: number;
+        maxEntries?: number;
+    });
+    tryAcquire(key: string, payloadHash: string): Promise<{
+        acquired: true;
+    } | {
+        acquired: false;
+        result: unknown;
+    }>;
+    commit(key: string, result: unknown): Promise<void>;
+    /** 检查键当前占位的 payloadHash（网关 409 判定用） */
+    getPayloadHash(key: string): string | undefined;
+    /** 释放占位（校验失败时回滚） */
+    release(key: string): void;
+    private evict;
+    clear(): void;
+}
+declare function hashPayload(payload: unknown): string;
+
+/**
+ * 业务动作网关（004 D3 / W2 C2）：卡片/业务写操作的全局分发器。
+ * - POST /api/action：SDK 黑盒唯一写入口（新增写动作自动进入校验链，不可绕过）
+ * - 校验链槽位化、策略随动作注册：幂等槽 P3 落地；签名/时效槽 P4 填（API 预留不破坏）
+ * - 匿名写拒绝（006 D11）：identity.source=anonymous 的写操作一律 403，**不随 AUTH_MODE 变**
+ * - 工厂形态（消灭 P2 模块级单例）：多实例/测试互不污染
+ *
+ * 错误语义：400（缺参）/ 403（校验失败 / 匿名写）/ 404（未知 action）/ 409（幂等键被不同 payload 复用）/
+ *           500（handler 异常）/ 幂等键命中且 payload 一致 → 200 返回缓存结果（非 403）
+ */
+type ActionHandler = (payload: unknown, ctx: ActionContext) => Promise<ActionResult>;
+interface ActionContext {
+    sessionId: string;
+    /** 006 D8：当前请求的运行上下文（authMiddleware 注入；未鉴权为 undefined） */
+    requestContext?: RequestContext;
+    emit: (event: ServerEvent) => void;
+}
+interface ActionResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+/** 校验链槽位（签名/时效/主体槽 P4 填） */
+interface ActionCheck {
+    check: (req: Request) => Promise<{
+        ok: boolean;
+        code: number;
+        message: string;
+    }>;
+}
+interface ActionPolicy {
+    /** 是否写操作（true 时幂等槽生效：缺 idempotencyKey → 400） */
+    write?: boolean;
+    /** 幂等槽（P3 落地）：命中且 payload 一致 → 200-cached；不同 payload → 409 */
+    idempotent?: boolean;
+    /** 校验槽（P4 填签名/时效/主体） */
+    checks?: ActionCheck[];
+}
+interface ActionGateway {
+    registerAction(action: string, handler: ActionHandler, policy?: ActionPolicy): void;
+    /** POST /api/action 中间件（组装端一次挂载） */
+    middleware(): RequestHandler;
+    /** 可组合校验链（供模块 REST 端点按需挂载：webhook/上传/demo） */
+    validateAction(policy?: ActionPolicy): RequestHandler;
+    /** 服务端内部分发（demo 路由 / 测试复用；幂等语义同 middleware） */
+    dispatch(action: string, payload: unknown, opts?: {
+        sessionId?: string;
+        idempotencyKey?: string;
+        identity?: _tbox_cn_app_contracts.Identity;
+        /**
+         * 完整运行上下文（上下文统一化 Stage 1）：identity 超集——HTTP 路由直接透传
+         * getRequestContext(req)（含 credentials/attributes）；提供时优先于 identity。
+         */
+        requestContext?: _tbox_cn_app_contracts.RequestContext;
+    }): Promise<ActionResult>;
+    getActions(): ReadonlyMap<string, {
+        handler: ActionHandler;
+        policy: ActionPolicy;
+    }>;
+}
+declare function createActionGateway(opts?: {
+    idempotencyStore?: IdempotencyStore;
+}): ActionGateway;
+
+/**
+ * 服务端日志壳：run 级 ALS 上下文 + ServerLogger（span 经 ServerSpanSink 出口，通用侧零 mastra）
+ * + recordCall 计时原语 + withCallLog 外部传输观测。
+ *
+ * 上下文传播：chat()/submitForm()（引擎 run）与 auth.middleware（HTTP 请求）各自
+ * runWithLogContext 开作用域 → 作用域内所有日志行自动携带 req=/conv= 尾缀；
+ * requestId === TBOX_TRACE 的 requestId === runId（单一 trace 锚点，一次 grep 串全）。
+ * 作用域外（启动期/注册期）日志照常输出，无尾缀。
+ *
+ * span 出口倒置（agent-sdk 拆分准备）：通用侧仅构造 ServerSpanPayload 调 spanSink
+ * （缺省 no-op）；agent 侧 trace-exporter 模块顶层 setServerSpanSink 注册 mastra
+ * emitCustomSpan（type: SpanType.GENERIC 由注册方注入）——H5 等纯通用消费者零 mastra。
+ */
+
+interface ServerLogScope extends LogContext {
+    threadKey?: string;
+}
+/** run 级日志作用域（toolCardScope 同款 ALS 模式；emit 时读取——跨请求复用安全） */
+declare const runLogScope: AsyncLocalStorage<ServerLogScope>;
+declare function runWithLogContext<T>(scope: ServerLogScope, fn: () => Promise<T>): Promise<T>;
+/** 结构化 span 载荷（通用侧形状；mastra type 字段由 agent 侧 sink 注册方注入） */
+interface ServerSpanPayload {
+    spanId: string;
+    traceId: string;
+    name: string;
+    startTime: Date;
+    endTime: Date;
+    metadata?: Record<string, unknown>;
+    errorInfo?: {
+        message: string;
+        type?: string;
+        stack?: string;
+    };
+    requestId: string;
+    conversationId?: string;
+    sessionId?: string;
+}
+/** span 出口（缺省 no-op；agent 侧 trace-exporter 顶层注册接管） */
+type ServerSpanSink = (payload: ServerSpanPayload) => void;
+/** 注册 span 出口（agent 侧装配期调用；重复注册以最后一次为准） */
+declare function setServerSpanSink(sink: ServerSpanSink): void;
+interface ServerLogger extends TboxLogger {
+    /** 结构化 span（→ ServerSpanSink 出口；req/conv 经 ALS 自动关联） */
+    span(name: string, payload?: {
+        metadata?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+}
+/** 服务端 logger（SDK 内部 + ctx.logger 注入共用出口）；模块侧经 register 期 ctx 获取 */
+declare function createServerLogger(tag: string): ServerLogger;
+/** 外部调用慢阈值（毫秒）：响应行升 WARN——info 档一眼定位慢厂商 */
+declare const EXTERNAL_SLOW_MS = 3000;
+type CallKind = 'tool' | 'external' | 'op';
+/**
+ * 统一计时原语：计时 → ok/fail 行（含 durMs）→ 按需 span → 失败原样 rethrow（控制流零变化）。
+ * kind 决定行形态：tool 附 args/result 详情；external 由 withCallLog 自管行序；op 仅 durMs。
+ */
+declare function recordCall<T>(kind: CallKind, name: string, fn: () => Promise<T>, opts?: {
+    logger?: TboxLogger;
+    detail?: {
+        args?: unknown;
+    };
+    emitSpan?: boolean;
+    onDone?: (durMs: number) => void;
+}): Promise<T>;
+/**
+ * 外部接口传输观测（单方法包装）：请求行先于 await（调用挂起可见"只出不进"），
+ * 响应行带 durMs（>EXTERNAL_SLOW_MS 升 WARN），body 脱敏+截断；logger 缺席直通（单测路径）。
+ * run 作用域内额外发 external-call span（D2 纪律：trace 平面只属引擎 run——作用域外只发行不发 span）。
+ */
+declare function withCallLog(logger: TboxLogger | undefined, transport: AuthenticatedTransport): AuthenticatedTransport;
+
+/**
+ * 组件状态存储基元（011 H1/H2）：
+ * get / put / compareAndSet / consume + TTL + 深冻结。
+ *
+ * - 默认 memory 实现（单实例边界明示：多副本需 shared 实现，等真实需求，011 H2）；
+ * - CAS revision 从 1 递增，用于 ActionGrant 签发竞态与幂等；
+ * - consume 原子读删（single-use token 消费语义）。
+ */
+
+interface StoredEntry<T> {
+    value: Readonly<T>;
+    revision: number;
+    /** 过期时间（ms epoch）；缺省永不过期 */
+    expiresAt?: number;
+}
+interface ComponentStateStore {
+    get<T>(namespace: string, ref: string): Promise<Readonly<T> | null>;
+    /** 读取条目（含 revision/expiresAt；CAS 前置读取用） */
+    getEntry<T>(namespace: string, ref: string): Promise<Readonly<StoredEntry<T>> | null>;
+    put<T>(namespace: string, ref: string, value: T, ttlMs: number): Promise<boolean>;
+    compareAndSet<T>(namespace: string, ref: string, expectedRevision: number, value: T, ttlMs: number): Promise<boolean>;
+    consume<T>(namespace: string, ref: string): Promise<Readonly<T> | null>;
+}
+declare function createInMemoryStateStore(now?: () => Date): ComponentStateStore;
+/** 幂等键 hash（011：跨模块写操作幂等键规范化，与现有 hashPayload 对齐） */
+declare function hashStateRef(input: string): string;
+
+/**
+ * Provider 认证策略（011 G7）：credentialType → apply 注册点。
+ * - SDK 内置 'static-headers-v1'（静态头注入）；
+ * - 模块自定义（如 joycity 签名算法）经注册点注入，SDK 不 import 模块。
+ */
+
+interface ProviderAuthStrategyInput {
+    method: string;
+    url: string;
+    body?: unknown;
+    credential: Readonly<ProviderCredential>;
+    /** 请求附加头（gateway 经 extraHeaders 注入，如 token/memberId/appId）——参与签名的头签名侧读取 */
+    headers?: Readonly<Record<string, string>>;
+}
+interface ProviderAuthStrategy {
+    /** 匹配 ProviderTemplateDeclaration.credentialType */
+    credentialType: string;
+    /**
+     * 认证产出放置（缺省 'header'）：'query' = 追加到 URL query（GET 携签厂商，如 wanda
+     * sign/timestamp）；apply 输入 url 不含认证参数——签名基于业务参数计算后再追加。
+     */
+    readonly placement?: 'header' | 'query' | 'body';
+    /**
+     * 产出认证参数（键值对；按 placement 放 header / URL query / JSON Body）；抛错 = 认证构造失败（计入熔断）。
+     * 'body' 语义（万达 C 端网关对齐）：POST/PUT → 合并进 JSON Body（业务字段前置，sign/timestamp 追加末尾——
+     * 服务端按字段出现顺序重组 dataStr，与签名侧一致）；GET/DELETE → 追加 URL query。
+     */
+    apply(input: ProviderAuthStrategyInput): Record<string, string>;
+}
+declare const STATIC_HEADERS_CREDENTIAL_TYPE = "static-headers-v1";
+/** 内置静态头策略：credential.value 原样映射为请求头 */
+declare const staticHeadersStrategy: ProviderAuthStrategy;
+/** 011 B2：可变认证策略注册表——模块 register 期注册（如 joycity-c-signed-v1），transportFactory 动态查 */
+interface AuthStrategyRegistry {
+    get(credentialType: string): ProviderAuthStrategy | undefined;
+    /** 重复注册同名策略 → 后者覆盖 + warn（模块双装配场景） */
+    register(strategy: ProviderAuthStrategy): void;
+    /** 快照（诊断用） */
+    list(): readonly ProviderAuthStrategy[];
+}
+declare function createAuthStrategyRegistry(strategies?: readonly ProviderAuthStrategy[]): AuthStrategyRegistry;
+
+/**
+ * 换码器注册表（provider 拆包 F0）：可变 + 惰性查找。
+ *
+ * 背景（第五轮评审发现）：options.exchanges 静态注入在 createAuthRuntime 构造期展开——
+ * provider 包 register（registerServerModules 内）晚于构造，其 authExchanges.register
+ * 静默断裂。本注册表持引用惰性查找：登录请求期才 get(platform)，register 晚于构造仍生效。
+ *
+ * 三层解析（F2 模板中立化）：get(platform, context?) 按「注册通道」分层归属（非谓词形态）——
+ * ① 显式 scoped 候选：register 注册且声明 matches，注册序 first-match；
+ * ② 显式无条件候选：register 注册且无 matches（兜底位），最早注册者优先；
+ * ③ 构造期 initial 填充（内置 alipay/weapp）恒最后——内置永不遮蔽显式候选。
+ * 显式层内分槽：无条件候选（无 matches）每 provider 键至多一条，重复注册原位替换
+ * （保序 + 旧覆盖语义）；scoped 候选（有 matches）同 provider 多条共存（first-match，
+ * 多厂商按 mall 等域并存的前提）。层归属由注册通道决定：构造期内置声明 matches
+ * 也不会升入显式层。
+ *
+ * 接线链（模板装配职责）：authRuntime.exchanges → createServerContext({ authExchanges }) →
+ * 模块/provider register 期 ctx.authExchanges.register(...) → 登录请求期 login 路由惰性命中
+ * （context 为归一化登录上下文，供 scoped 谓词做 mall 等域路由决策）。
+ */
+
+interface ScopedIdentityExchange extends IdentityExchange {
+    /**
+     * 谓词路由（F2）：纯函数——只读归一化 context、零 IO、不得抛；返回 false = 本候选不命中。
+     * 缺省 = 无条件候选（落第②层兜底位）。
+     *
+     * 统一范式（商圈 provider 候选）：业务域依赖缺失（如未选择商场/未指定作用域）时
+     * 应命中自身换码器（返回 true），由 exchangeByCode 显性抛配置/选择错误——否则未命中
+     * 会落第③层内置候选（本地 alipay/weapp），其缺 env 报错会误导部署面排查。
+     * 仅当域值在场但本候选不绑定时才返回 false（继续 fallback，多厂商并存语义）。
+     */
+    matches?(context?: Readonly<Record<string, unknown>>): boolean;
+    /**
+     * mock 物料口（可选）：返回本厂商 mock 场景外部凭证（config 物料经集成配置求值注入，
+     * env/实例配置于调用期懒读——测试可变、运行期可控）。
+     * 契约：接收与 matches/exchangeByCode 相同的归一化 context，可同步或异步返回；
+     * 返回 undefined = 本厂商声明无物料——调用方不得回退其他厂商；
+     * token/provider/attributes 形状归厂商包自持（本 SDK 零 vendor 知识）。
+     */
+    mockCredentials?(context?: Readonly<Record<string, unknown>>): ExternalCredentials | undefined | Promise<ExternalCredentials | undefined>;
+    /**
+     * guest 登录声明口（可选）：browser 轴 auto 档是否允许签发随机访客身份（guest_<32hex>）。
+     * 纯函数/同步；违约视为 false（fail-safe）。缺省 = 不开放（auto 档落 mock/off 判定）。
+     * mock provider 与内置换码器声明 true（裸跑即完整演示）；真实厂商默认不声明。
+     */
+    allowsGuestLogin?(context?: Readonly<Record<string, unknown>>): boolean;
+    /**
+     * browser 轴档位口（可选）：browser 登录互斥链档位——'auto' | 'guest' | 'mock' | 'off'。
+     * 典型实现 = 读登录槽 config（支持 ${VAR:-default} 展开）；违约/缺席视为 'auto'。
+     */
+    browserLoginMode?(context?: Readonly<Record<string, unknown>>): 'auto' | 'guest' | 'mock' | 'off' | undefined;
+}
+interface AuthExchangeRegistry {
+    /**
+     * 注册显式候选（key = exchange.provider）：scoped 候选（有 matches）多条共存；
+     * 无条件候选同键原位替换保序。
+     */
+    register(exchange: ScopedIdentityExchange): void;
+    /** 惰性查找（登录请求期调用）；context = 归一化登录上下文（scoped 谓词路由输入）。
+     * 返回收宽为 ScopedIdentityExchange：可选能力口成员（matches/mockCredentials/
+     * allowsGuestLogin/browserLoginMode）在内置候选上可缺席——调用方以
+     * `typeof x.m === 'function'` 守卫，缺席即无该能力。 */
+    get(platform: string, context?: Readonly<Record<string, unknown>>): ScopedIdentityExchange | undefined;
+    /** 快照（诊断用）：explicit 在前、builtins 在后拍平 */
+    list(): readonly IdentityExchange[];
+}
+declare function createAuthExchangeRegistry(initial?: Record<string, IdentityExchange>): AuthExchangeRegistry;
+
+/**
+ * 环境机密解析（011 G5）：credentialRef → ProviderCredential。
+ * - credentialRef 形态 'secret://{env}/{seg...}'（{env} 为部署环境键，剩余为分段路径）；
+ * - 生产 credentialRef 缺失 → fail-fast（PROVIDER_CREDENTIAL_REF_MISSING）；
+ * - scope 严格匹配（凭证 scope 与实例 scope 键值一致才可用）；
+ * - 头名白名单（应用后即弃，禁止落日志）。
+ */
+
+declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    constructor(code: ProviderErrorCode, message: string);
+}
+/** 机密来源：环境键 → 值（模板注入 process.env 快照） */
+type SecretSource = Readonly<Record<string, string | undefined>>;
+interface EnvironmentSecretProvider {
+    resolve(credentialRef: string, expectedScope: Record<string, string>): Readonly<ProviderCredential>;
+}
+interface EnvironmentSecretProviderOptions {
+    /** 环境键快照（禁止直接读 process.env——测试可注入） */
+    source: SecretSource;
+    /**
+     * 凭证文件目录（可选；文件 > env 优先）：credentialRef 键 → 文件名派生
+     * （小写、'-'→'_'、追加 .json——与 .real-env README 派生公式互逆）。命中即读文件内容
+     * （JSON 文本），miss 回退 source。镜像场景：凭据文件挂载直读，免 env 展开。
+     */
+    files?: string;
+    /** 头名白名单（静态头注入凭证）。缺省空 = 拒绝静态头 */
+    allowedHeaderNames?: readonly string[];
+    /** 生产标志：true 时 credentialRef 缺失 fail-fast；false 时可用 dev fixture 兜底 */
+    production?: boolean;
+}
+declare function createEnvironmentSecretProvider(opts: EnvironmentSecretProviderOptions): EnvironmentSecretProvider;
+
+/**
+ * 认证传输层工厂（011 G2/G4）：熔断 + 超时 + 1MB 上限 + 强制 HTTPS + X-Trace-Id。
+ *
+ * 缓存责任在 registry（key = templateId + stable(scope) + credentialVersion），
+ * 本工厂产出单实例 transport（credentialVersion 变更 → registry 重建）。
+ */
+
+interface CircuitBreakerConfig {
+    /** 连续失败阈值（缺省 3） */
+    failureThreshold?: number;
+    /** 开闸时长 ms（缺省 30s） */
+    openMs?: number;
+}
+interface TransportFactoryOptions {
+    strategies: AuthStrategyRegistry;
+    secretProvider: EnvironmentSecretProvider;
+    circuitBreaker?: CircuitBreakerConfig;
+    /** 响应体上限字节（缺省 1MB） */
+    maxResponseBytes?: number;
+    /** 超时上限（缺省 15s；opts.timeoutMs 不覆盖此上限） */
+    maxTimeoutMs?: number;
+    /** 时钟注入（测试用） */
+    now?: () => number;
+    /** 观测 logger：在场时 [transport] 最终请求预览走 logger.debug（统一行格式+级别控制）；
+     *  缺席静默（直构/测试路径零输出，原 console.log 行为移除）。 */
+    logger?: TboxLogger;
+}
+interface TransportFactory {
+    create(instance: ProviderInstance, template: ProviderTemplateDeclaration): AuthenticatedTransport;
+}
+declare function createAuthenticatedTransportFactory(opts: TransportFactoryOptions): TransportFactory;
+
+/**
+ * Integrations 注册表（integrations v6）：service slot → (provider, implementation) → binding 解析轴。
+ *
+ * 旧 ProviderRegistry（templateId + scope 双键）已删除（全仓零消费实证）——本轴是唯一解析面；
+ * 原旁路消费（换码器 transport 直连）已迁本轴：
+ * - resolveLoginExchange：换码 transport 级解析（无请求上下文/无 adapter 语义）；
+ * - hasProviderBinding：presence 点查（路由谓词——effective 求值后比对 provider+implementation）。
+ * 声明式槽解析主链：
+ * - 配置真源 integrations.json（IntegrationsConfig：root → modules[owner] → service → instance；
+ *   v6 所有权模型——ownerOf 归属表由装配期显式注入，domains 键已退役）；
+ * - effective 求值单源 = contracts resolveEffectiveService（绑定组最特异层整组取
+ *   inst > slot > modules[owner] > root；组内 implementation 缺席经 supplies 派生；
+ *   enabled 缺省 true；层序优先于 scope 特异度）；
+ * - 供给真源 provider catalog（嵌套 providers[vendor][impl]；loadProviderCatalog 聚合；
+ *   构造期 buildSupplyLookup 展平为派生查表——求值期 O(1)）；
+ * - adapter 可变注册表（(provider, implementation) 双键；provider 包 register 期注册，
+ *   晚于本工厂构造——惰性查找）；
+ * - 实例级绑定组覆盖（instance.provider/implementation 成组；implementation 缺席 = 组内派生，
+ *   按 mall 差异化，不算槽冲突）；
+ * - local 短路（catalog 条目 local:true → InMemory transport，免凭据/认证/credentialRef）；
+ * - transport 缓存键 = service + instanceId + provider + implementation（派生 impl 自动入键；
+ *   换绑后旧 transport 留存复用——熔断半开自恢复；integrations 配置无热轮换，重载即重启进程）；
+ * - provider 实例声明通道（declareProviderInstances——COW 拷贝冻结快照；域中立存储，
+ *   SDK 不解释实例内容，域装配惰性融合消费）。
+ *
+ * SDK 零领域语义铁律：instanceId 提取器注入（instanceIdOf；mall 场景模板层注入
+ * (scope) => scope.mallId），缺省 stableSerializeScope。错误上下文统一 `service@instanceId`。
+ */
+
+/** adapter 构造输入（provider 包 factory 的唯一依赖面） */
+interface ServiceAdapterInput {
+    transport: AuthenticatedTransport;
+    config: Readonly<Record<string, unknown>>;
+    credentialRef?: string;
+    scope: Readonly<Record<string, string>>;
+    instanceId: string;
+    request: RequestContext;
+    /** 本次解析的 service 槽 id（017 槽位原子化）：guide 等多槽共享工厂按此分支返回
+     *  单 Port 产物；其余工厂忽略。 */
+    service: string;
+    /**
+     * 惰性凭据 getter（v2 T2.4 起）：调用才解析（ref → 文件/环境），未调用零成本
+     * （local 短路/无凭据槽 factory 不触）。返回 ProviderCredential（含 value 机密）。
+     * credentialRef 缺席 → undefined（调用方按自身语义降级）。
+     */
+    credential?: () => Readonly<ProviderCredential>;
+}
+/** adapter 工厂（provider 包 register 期注册；产物请求级——模块 service 请求级构造模式） */
+type ServiceAdapterFactory = (input: ServiceAdapterInput) => unknown;
+/** 换码解析产物（resolveLoginExchange）：transport 级——登录换码器直接消费认证 transport。
+ *  providerId 字段 = effective implementation（'id@version'；展示/诊断用途，模块不消费）。 */
+interface LoginExchangeResolution {
+    transport: AuthenticatedTransport;
+    config: Readonly<Record<string, unknown>>;
+    providerId: string;
+}
+interface IntegrationsRegistry {
+    /** 注册 adapter（provider 包 register 期；双键 = provider 厂商名 + implementation 'id@version'；
+     *  重复后者覆盖 + warn） */
+    registerAdapter(provider: string, implementation: string, factory: ServiceAdapterFactory): void;
+    /** 槽解析（模块 ports 运行期调用；错误上下文 service@instanceId） */
+    resolveService(input: {
+        service: string;
+        scope: Record<string, string>;
+        request: RequestContext;
+    }): Promise<unknown>;
+    /** 换码 transport 级解析（登录场景专用：无请求上下文/无 adapter 语义）。
+     *  错误码族与 resolveService 同源（SERVICE_NOT_CONFIGURED/INSTANCE_NOT_FOUND/
+     *  INSTANCE_DISABLED/BINDING_UNRESOLVED/PROVIDER_NOT_FOUND）；调用方（provider 包换码器）按域转译。
+     *  transport 缓存与 resolveService 共池（同 service@instanceId@provider@impl 键）。 */
+    resolveLoginExchange(input: {
+        service: string;
+        scope: Record<string, string>;
+    }): Promise<LoginExchangeResolution>;
+    /** presence 点查：该槽该 scope 的有效 (provider, implementation)（effective 求值后）
+     *  === 入参双字段。内联声明形态恒 false（无实现可比）；纯配置读取，无 transport/凭据副作用。 */
+    hasProviderBinding(service: string, scope: Record<string, string>, provider: string, implementation: string): boolean;
+    /** 声明 provider 的隐式部署实例（provider 包 register 期调用；域中立存储——SDK 只存取
+     *  DeploymentInstance 通用类型，不解释实例内容；融合规则归 TIER1 投影器如 mallControlPlaneOf）。
+     *  空数组 no-op；结构非法 fail-fast（id 非空、禁 '*' 通配保留字、name 须非空 string）；
+     *  同 provider 重复声明覆盖 + warn（对齐 registerAdapter 先例）。
+     *  存入前拷贝并冻结快照（调用方后续原地改写不影响已声明内容——ref 不变即声明未变）。 */
+    declareProviderInstances(provider: string, instances: readonly DeploymentInstance[]): void;
+    /** 当前声明快照（COW 冻结拷贝；无声明 = 共享冻结空记录常量）。域装配惰性融合消费——
+     *  快照引用变更即「声明发生变化」信号（调用方据此失效投影缓存）。 */
+    providerInstanceDeclarations(): ProviderInstanceDeclarations;
+    /** 诊断快照（doctor/调试用） */
+    listAdapters(): readonly string[];
+    /**
+     * 原始装载产物（W1-④ 中立通道）：zod 解析产物 + 源定位原样透传——
+     * 装配消费（app-config modules 资源节自动装配；域装配投影如 mallControlPlaneOf(raw.config)）。
+     * SDK 零域语义：不解释 config 内容，只透传。
+     */
+    readonly raw: IntegrationsRaw;
+}
+/** integrations 原始装载产物（raw 通道形状）。 */
+interface IntegrationsRaw {
+    /** zod 解析产物（域投影/资源节消费；占位展开已完成） */
+    readonly config: IntegrationsConfig;
+    /** 配置源路径（同源旅行锚：dirname 派生台账目录等；直构缺省 undefined） */
+    readonly source?: string;
+}
+interface IntegrationsRegistryOptions {
+    integrations: IntegrationsConfig;
+    catalog: ProviderCatalog;
+    authStrategies: AuthStrategyRegistry;
+    secretProvider: EnvironmentSecretProvider;
+    /** transport 工厂注入（缺省经 authStrategies + secretProvider 构造 authenticated 工厂） */
+    transportFactory?: TransportFactory;
+    /** instanceId 提取器（缺省 stableSerializeScope；mall 场景模板层注入 (scope) => scope.mallId） */
+    instanceIdOf?: (scope: Record<string, string>) => string;
+    /** 日志器（缺省静默；在场时 factory 收到的 transport 包 withCallLog 外部调用观测） */
+    logger?: TboxLogger;
+    /** 配置源路径（W1-④ raw 通道：装配消费如 app-config 台账目录派生；缺省 undefined） */
+    source?: string;
+    /**
+     * v6 服务归属表（service → moduleId；buildOwnershipMap 产物——装配期显式注入）。
+     * 缺席 = 无模块层语义（≡ v5 文件形态；文件含 modules 级绑定/配置时 resolveEffectiveService
+     * 显式 fail-visible，不静默跳过）。服务无主 → 级联跳过 modules 层（平台槽语义）。
+     */
+    ownerOf?: Record<string, string>;
+}
+declare function createIntegrationsRegistry(opts: IntegrationsRegistryOptions): IntegrationsRegistry;
+
+/**
+ * Scope 会话注册表（011 F2/F3/F5）：
+ * 会话 id 生成 + scope 键绑定 + 请求匹配护栏。
+ *
+ * SDK 参数化（011 B3）：extractScopeKey/validateScope 由装配层注入
+ * （mall 场景经 contracts-mall createMallRuntimeAssembly），本文件零领域语义。
+ *
+ * 实现说明：连接级短命状态（TTL 30min，重启即连接全断），
+ * 自持同步内存 Map + 可注入时钟（测试用）；不做跨实例共享（多副本场景等真实需求）。
+ */
+
+interface ScopeSession {
+    sessionId: string;
+    /** scope 键（extractScopeKey 产物，如 mallId） */
+    scopeKey: string;
+    /** 完整 attributes 快照（审计用） */
+    scope: Record<string, unknown>;
+    /** 011 D1：领域扁平 scope（HelloAck 回显 + ActionGrant 签发/校验的单一来源） */
+    scopeFlat: Record<string, string>;
+    createdAt: number;
+    expiresAt: number;
+}
+interface ScopeSessionRegistry {
+    /** HELLO 后引导会话：校验 scope → 生成 sessionId → 绑定 */
+    bootstrap(ctx: RequestContext): ScopeSession;
+    /** 按 sessionId 读取（过期返回 null） */
+    get(sessionId: string): Readonly<ScopeSession> | null;
+    /** 断言当前会话：sessionId 不存在 / scopeKey 不匹配 → 抛错（WS 层转「会话已失效」） */
+    assertCurrent(sessionId: string, scopeKey: string): Readonly<ScopeSession>;
+    /** 测试/运维辅助：过期条目清理 */
+    sweep(): void;
+}
+interface ScopeSessionRegistryOptions {
+    /** scope 键提取（如 mallId）；缺失 → 抛错 */
+    extractScopeKey(ctx: RequestContext): string;
+    /** scope 白名单校验（接收 ctx.attributes 原样；注入方自行解析，如 parseMallScope） */
+    validateScope(attributes: Record<string, unknown>): boolean;
+    /** 011 D1：领域扁平 scope 构建（如 { miniAppId, mallId }；回显 + grant 校验单一来源） */
+    buildScope(attributes: Record<string, unknown>): Record<string, string>;
+    /** 会话 TTL（缺省 30min） */
+    ttlMs?: number;
+    /** 时钟注入（测试用） */
+    now?: () => number;
+}
+declare class ScopeSessionError extends Error {
+    readonly code: 'SCOPE_INVALID' | 'SESSION_NOT_FOUND' | 'SESSION_SCOPE_MISMATCH';
+    constructor(message: string, code: 'SCOPE_INVALID' | 'SESSION_NOT_FOUND' | 'SESSION_SCOPE_MISMATCH');
+}
+declare function createScopeSessionRegistry(opts: ScopeSessionRegistryOptions): ScopeSessionRegistry;
+
+interface ActionGrantService {
+    issue(input: {
+        moduleId: string;
+        actionId: string;
+        cardType: string;
+        /** 目标卡实例 id（P0 原地更新授权锚定：token 只能作用于该卡；hidden 回调签发缺省） */
+        cardId?: string;
+        sessionId: string;
+        scope: Record<string, string>;
+        input?: unknown;
+        singleUse?: boolean;
+        ttlMs?: number;
+    }): Promise<string>;
+    authorize(token: string, expected: {
+        actionId: string;
+        sessionId: string;
+        scope: Record<string, string>;
+        /** 期望目标卡实例 id（P0：undefined 表示签发时未锚定——hidden 回调路径） */
+        cardId?: string;
+    }): Promise<Readonly<GrantRecord>>;
+    /** 失败（execute 抛错）后恢复 single-use 令牌（业务可重试） */
+    restore(token: string): Promise<void>;
+}
+interface GrantRecord {
+    /** 011 I5 修复：grant 唯一 id（同参数重签互不覆盖消费标记） */
+    grantId: string;
+    moduleId: string;
+    actionId: string;
+    cardType: string;
+    /** 目标卡实例 id（P0 原地更新授权锚定；进 HMAC 规范串防篡改） */
+    cardId?: string;
+    sessionId: string;
+    scope: Record<string, string>;
+    input?: unknown;
+    singleUse: boolean;
+    expiresAt: number;
+}
+declare class ActionGrantError extends Error {
+    readonly code: 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'GRANT_MISMATCH' | 'TOKEN_CONSUMED';
+    constructor(code: 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'GRANT_MISMATCH' | 'TOKEN_CONSUMED', message: string);
+}
+declare const ACTION_GRANT_MAX_TTL_MS: number;
+interface ActionGrantOptions {
+    store: ComponentStateStore;
+    /** 主密钥（≥32 字节；缺省走统一密钥链：ACTION_TOKEN_SECRET → AUTH_TOKEN_SECRET → TBOX_API_KEY → dev 随机） */
+    secret?: Uint8Array;
+    now?: () => number;
+}
+declare function deriveActionGrantKey(secret: Uint8Array): Uint8Array;
+declare function createActionGrantService(opts: ActionGrantOptions): ActionGrantService;
+
+/**
+ * 宿主效果运行时（011 E5/E6；015 P3 纯化）：
+ * - 类型封闭集合 + navigation 白名单；协议单源 import 自 contracts（015 P1）
+ * - 纯投影：效果 → tbox:effect CUSTOM 事件下行，无宿主处理器（011 占位 handler 已删，015 G1）
+ * - payment/authorization 回调补签在 dispatcher step7（component-action.ts，015 P2）
+ * 无 custom 槽位（011 I14）——新效果类型须走提案扩展 contracts 联合。
+ */
+
+interface EffectRuntime {
+    /** 动作结果 → 宿主效果事件（纯函数：白名单/形状校验 + 下行投影，无副作用） */
+    project(result: {
+        effects?: unknown[];
+    }): ServerEvent[];
+}
+interface EffectRuntimeOptions {
+    /** navigation 路由白名单（模块注册集合；015：本期零发射者，协议词汇保留） */
+    routeWhitelist?: ReadonlySet<string>;
+}
+declare class EffectError extends Error {
+    constructor(message: string);
+}
+declare function createEffectRuntime(opts?: EffectRuntimeOptions): EffectRuntime;
+
+/**
+ * 模块动作域错误类型（单点定义）：component-action 与 notice-text 双向消费，
+ * 独立成文件避免循环导入（notice-text 的错误文案映射需要 instanceof 判别）。
+ */
+declare class ModuleActionError extends Error {
+    readonly code: 'ACTION_NOT_FOUND' | 'SESSION_INVALID' | 'GRANT_INVALID' | 'INPUT_INVALID' | 'RESULT_INVALID' | 'CALLBACK_INVALID';
+    constructor(code: 'ACTION_NOT_FOUND' | 'SESSION_INVALID' | 'GRANT_INVALID' | 'INPUT_INVALID' | 'RESULT_INVALID' | 'CALLBACK_INVALID', message: string);
+}
+
+interface RegisteredModuleAction {
+    actionId: string;
+    moduleId: string;
+    /** 声明此动作的卡片类型（dispatch 时核对授权记录的 cardType） */
+    cardType: string;
+    /** 按钮文案（payload.actions[].label） */
+    label?: string;
+    /** 按钮呈现（P1：kind/style/enabled 等透传 payload.actions；缺省 kind=moduleAction） */
+    kind?: 'moduleAction' | 'sendMessage' | 'openLink';
+    value?: string;
+    visible?: boolean;
+    url?: string;
+    style?: 'primary' | 'secondary' | 'link';
+    enabled?: boolean;
+    disabledReason?: string;
+    /** 效果回调动作（015 P5）：不进按钮条；grant 由 dispatcher 补签 */
+    hidden?: boolean;
+    inputSchema?: z.ZodTypeAny;
+    singleUse?: boolean;
+    /**
+     * 服务端执行体。moduleAction 动作必填（register 断言拦截缺失）；
+     * 纯客户端 kind（sendMessage/openLink）按钮点击不进 dispatch（客户端本地语义），
+     * execute 可省——类型正解替代 unreachable stub。
+     */
+    execute?(input: unknown, ctx: RequestContext): Promise<CardActionResult>;
+}
+interface ModuleActionDispatcher {
+    register(action: RegisteredModuleAction): void;
+    get(actionId: string): Readonly<RegisteredModuleAction> | undefined;
+    dispatch(input: {
+        token: string;
+        actionId: string;
+        /** WS 连接绑定的 scope 会话 id（HELLO bootstrap 产物） */
+        sessionId: string;
+        /** 动作来源卡实例 id（P0 原地更新目标；host-effect 回传缺省 ''） */
+        surfaceId?: string;
+        ctx: RequestContext;
+        formData?: unknown;
+        emit: (event: ServerEvent) => void;
+    }): Promise<CardActionResult>;
+}
+interface ModuleActionDispatcherOptions {
+    grants: ActionGrantService;
+    sessions: ScopeSessionRegistry;
+    state: ComponentStateStore;
+    effects: EffectRuntime;
+    /** 卡片动作注册表（011 B3：结果卡签发 token 用） */
+    actions: CardActionRegistry;
+    /** 卡片 meta 注册表（CardEmitter 校验 schema 用） */
+    cardRegistry: Record<string, _tbox_cn_app_contracts.CardMeta>;
+    /** scope 键提取（与 sessions 同源注入，如 mallId） */
+    extractScopeKey(ctx: RequestContext): string;
+}
+declare function createModuleActionDispatcher(opts: ModuleActionDispatcherOptions): ModuleActionDispatcher;
+
+/**
+ * 域装配注册表（单一模板统一化 W1-③）：域模块 register 期注册、消费点运行期惰性查表。
+ *
+ * 消费点（全部运行期查表——register 顺序无关：registerAll 先于 listen；
+ * authExchanges 同款「晚于构造仍生效」先例）：
+ * - SDK ctx.scopeDefaults 读取视图（scopeAssembly().scopeDefaults——SDK 唯一直接消费面）；
+ * - 模板装配点：validateContext / scopeSessions / instanceIdOf 等由域装配消费方按
+ *   TIER1 具体形状（如 contracts-mall 装配组合）resolve 读取。
+ *
+ * SDK 零域语义：本注册表不 import 任何 TIER1；kind 词汇经 TIER0 contracts
+ * （SCOPE_ASSEMBLY_KIND）。
+ */
+
+declare class DomainAssemblyRegistry {
+    private assemblies;
+    register(kind: string, assembly: unknown): void;
+    resolve<T = unknown>(kind: string): T | undefined;
+    /** scope-assembly 便捷读取（ctx.scopeDefaults 视图消费；缺失 → undefined）。 */
+    scopeAssembly(): ScopeAssemblyContract | undefined;
+    get size(): number;
+}
+
+interface FlowStateStore {
+    get<T>(sessionId: string, key: string): T | undefined;
+    set(sessionId: string, key: string, value: unknown): void;
+    clear(sessionId: string): void;
+}
+/**
+ * 卡片动作注册表（011 E7：模块声明式 CardAction 收集处）。
+ * 装配端把 cardActions.getAll() 交给 ModuleActionDispatcher + 卡片出卡时签发 token。
+ */
+interface CardActionRegistry {
+    register(action: RegisteredModuleAction): void;
+    get(actionId: string): Readonly<RegisteredModuleAction> | undefined;
+    getAll(): ReadonlyMap<string, RegisteredModuleAction>;
+}
+/**
+ * ServerContext：模块 registerServer(ctx) / Handler.handle(ctx) 共用的上下文。
+ *
+ * 注册期（registerServer 内）：只能 register / registerService / bus.subscribe / 路由挂载，
+ * 不得 resolveService（doctor 注册期纯净规则）。
+ * 运行期（handle / 事件回调内）：可 resolveService、读 flowStates；运行身份经显式
+ * 通道（handle 第四参 reqCtx / 工具 execute 第二参读取器——上下文统一化 0.11.0）。
+ */
+interface ServerContext {
+    /** Handler 注册表（无状态路由） */
+    handlers: HandlerRegistry;
+    /** LLM function calling 工具注册表 */
+    tools: ToolRegistry;
+    /** 卡片元数据注册表（cardType → CardMeta） */
+    cards: CardRegistry;
+    /** 本地 skill 注册表（009：模块声明式主通道，build-engine 合并进 ChatEngine） */
+    skills: SkillRegistry;
+    /** 前置工具声明注册表（010：模块声明式主通道，build-engine 合并进 ChatEngine） */
+    preTools: PreToolRegistry;
+    /** HTTP API 路由注册表（/api/m/<moduleId>/） */
+    routes: ApiRouteRegistry;
+    /** Service 注册表（Port 接口实现） */
+    services: ServiceRegistry;
+    /** 类型化事件总线（跨模块异步通知） */
+    bus: TypedBus<EventMap>;
+    /** 卡片快照存储 */
+    snapshotStore: CardSnapshotStore;
+    /** 业务动作网关（004 D3/C2）：registerAction(action, handler, policy)；组装端一次挂载 POST /api/action */
+    actions: ActionGateway;
+    /** 结构类型子集接口查找（= services.resolve；参数 = 服务 id——v7 词汇统一） */
+    resolveService<T>(id: string): T | undefined;
+    /** 业务自管的分会话状态（ALS DeviceContext 简化版） */
+    flowStates: FlowStateStore;
+    /** 组件状态存储基元（011 H1）：CAS/TTL/consume；默认内存单实例边界 */
+    state: ComponentStateStore;
+    /**
+     * Agent 长期记忆存储（017，可选装配）。应用引擎与业务模块共享同一实例，模块仅在运行期
+     * 按可信身份与 scope 读写；未装配或 memory-off 时为 undefined。
+     */
+    memory?: MemoryStore;
+    /** 卡片写动作注册表（011 E7）：模块 CardAction 声明收集 */
+    cardActions: CardActionRegistry;
+    /** 011 B2：Provider 认证策略注册表（模块 register 期注册；与 transportFactory 同引用） */
+    authStrategies: AuthStrategyRegistry;
+    /**
+     * 换码器注册表（provider 拆包 F0 惰性查找）：模块/provider register 期注册登录换码器
+     * （key = exchange.provider，如 alipay）。模板装配应传 authRuntime.exchanges 同引用——
+     * 缺省独立空注册表（直构 ctx 不炸，但注册不达登录路由）。
+     */
+    authExchanges: AuthExchangeRegistry;
+    /**
+     * 域事实中立注入件读取视图（F2 模板中立化；W1-③ getter 化）：域装配注册表
+     * （scope-assembly.scopeDefaults）惰性读取优先，装配 opts.scopeDefaults 静态回落。
+     * provider 包经 getter 登录期求值读取（register 期零读——域模块注册晚于 provider
+     * register 仍生效，F1 反例修复）；缺省空视图（读取 undefined）。
+     */
+    scopeDefaults?: Readonly<Record<string, unknown>>;
+    /**
+     * 域装配注册表（W1-③）：域模块 register 期注册（如
+     * `ctx.domainAssemblies.register(SCOPE_ASSEMBLY_KIND, assembly)`），消费点运行期
+     * 惰性查表（register 顺序无关）。SDK 只消费 scopeDefaults 成员（scopeDefaults 视图）；
+     * 其余成员由模板装配点按 TIER1 形状读取。
+     */
+    domainAssemblies: DomainAssemblyRegistry;
+    /**
+     * Integrations 注册表（provider 拆包 F2 槽位解析轴）：provider 包 register 期注册 adapter
+     * （ctx.integrations.registerAdapter），模块 ports 运行期 resolveService({service, scope, request})。
+     * 模板装配应传 createIntegrationsRegistry 产物同引用；缺省 undefined（探测链回退——旧链路兼容）。
+     */
+    integrations?: IntegrationsRegistry;
+    /**
+     * 模块日志器（registerServerModules 逐模块注入，tag=module:<moduleId>；可选——
+     * 旧 SDK 混装/直构 ctx 时缺省，模块侧用可选链 ctx.logger?.warn(...)）。
+     * 规范见 docs/reference/modules.md「模块日志规范」：只经 register 期 ctx 闭包获取，禁顶层 createLogger。
+     */
+    logger?: ServerLogger;
+}
+/**
+ * 模块注册函数签名：模块包 server 入口 export 的 registerServer（兼容老形态）。
+ */
+type ModuleServerRegister = (ctx: ServerContext) => void | Promise<void>;
+/**
+ * 模块描述对象（服务端）：模块包 server 入口 export 的 serverModule。
+ *
+ * - cards：卡片 meta 声明 map（key 约定 = meta.cardType；数据 + 类型源，
+ *   供 `InferModuleCards` 从装配数组自动推导 app 端 CardType）。
+ * - register(ctx)：注册期自注册（tools/cards/handlers/services/bus/路由/事件），
+ *   只注册不解析（resolveService 仅 handle/事件回调内调用）。
+ *
+ * 与客户端 `ClientModule` 逐行对称；组装端遍历 modules 调 register(ctx)。
+ * register 为函数签名声明：method shorthand 经 `satisfies` 检查（TS 方法 bivariance——
+ * 放行比契约更窄的参数，运行时无危害；缺字段的过宽参数会被拦截）。
+ * cards 为必填属性：无卡片模块写 `cards: {}`（keyof = never，不污染装配类型）。
+ */
+interface ServerModule<C extends Record<string, CardMeta> = Record<string, CardMeta>> {
+    cards: C;
+    /**
+     * 模块声明（011 K：moduleId；014 起能力门控移除——能力 = 模块 add/remove，代码即事实）。
+     */
+    declaration?: {
+        moduleId: string;
+    };
+    /**
+     * 模块 skill 声明（009 D6，与 cards 对齐）：key 约定 = skill.name（纯数据，零 mastra 依赖）。
+     * 装配端 registerAll 自动注册（ctx.skills.registerAll），register 内无需代码；
+     * 命令式 ctx.skills.register(...) 兜底。
+     */
+    skills?: Record<string, LocalSkill>;
+    /**
+     * 模块前置工具声明（010，与 skills/cards 对齐）：key 约定 = tool.id（纯数据 + 一个 decide 函数，
+     * 零 mastra 依赖）。装配端 registerServerModules 自动注册，register 内无需代码。
+     * 铁律：仅只读/幂等工具；tool 引用工具实例（单一真源）；decide 决策即构造
+     * （{ decision:'run', args } = 预执行 / { decision:'skip' } = 不生效）、不得抛、
+     * args 必须 JSON 可序列化；身份经入参 identity 显式获取（per-run 并发安全）。
+     */
+    preTools?: Record<string, PreToolDef>;
+    register: (ctx: ServerContext) => void | Promise<void>;
+}
+/**
+ * 创建 ServerContext（组装端调用一次）。
+ * 注入件（011 S2）：state（缺省 memory）。
+ */
+declare function createServerContext(opts?: {
+    snapshotStore?: CardSnapshotStore;
+    idempotencyStore?: IdempotencyStore;
+    state?: ComponentStateStore;
+    /** Agent 长期记忆存储；应与 createEngineFromContext 的 memory.store 传入同一实例 */
+    memory?: MemoryStore;
+    authStrategies?: AuthStrategyRegistry;
+    /** 换码器注册表（模板装配传 authRuntime.exchanges 同引用；缺省独立空注册表） */
+    authExchanges?: AuthExchangeRegistry;
+    /** 域事实中立注入件（F2）：控制面域默认值（如 { defaultMallId }）；缺省 undefined */
+    scopeDefaults?: Readonly<Record<string, unknown>>;
+    /** Integrations 注册表（模板装配传 createIntegrationsRegistry 产物；缺省 undefined 探测链回退） */
+    integrations?: IntegrationsRegistry;
+}): ServerContext;
+
+/**
+ * Handler：平台统一执行单元（001 §3.2）。
+ * 平台不区分"Service Flow"和"Agent Skill"，业务以 Handler 形式注册，
+ * 由 HandlerRegistry.dispatch 无状态路由到 handle。
+ */
+interface HandlerResult {
+    cards: CardEmit[];
+    text?: string;
+    /**
+     * 确定性 handler 完成写操作后，继续进入本轮完整 Agent 流程。
+     * content 仅作为服务端续问进入模型上下文；用户消息与持久化 query 仍保留原始输入。
+     * text 为即时回显文案：进前端事件流与 answer 落库（显示一致性），不进 LLM 上下文
+     * （方案 B，2026-09-02——非 LLM token 入 history 会破坏前缀缓存）。
+     */
+    continueWith?: {
+        content: string;
+    };
+}
+interface CardEmit {
+    cardType: string;
+    data: Record<string, unknown>;
+    messageId?: string;
+    id?: string;
+}
+interface HandlerDefinition {
+    /** 业务唯一标识，如 "rental" / "purchase" / "points-parking" */
+    id: string;
+    /**
+     * 意图声明（011 D7/D8：意图与处理器同处定义）。
+     * 装配端从注册 handlers 收集构造 intentRoutes（chat 先 matchIntent——确定性档
+     * exact/prefix 优先，BM25 语义档兜底；缺省零 LLM，continueWith 可续接 Agent；
+     * match:'exact' 整句全等 / 'prefix' 模板句头前缀（均不入 BM25 词袋）；
+     * **顶层意图声明只允许确定性档（exact/prefix）**——BM25 语义分类职责归 skill 路由与
+     * LLM 工具编排（单标签硬短路截断复合句），缺省 bm25 为 legacy 装配期 warn；
+     * 重叠 = doctor warning，不阻断）。
+     */
+    intents?: {
+        patterns: string[];
+        match?: 'exact' | 'prefix' | 'bm25';
+    }[];
+    /**
+     * 处理 action，返回要下发的卡片 / 文字。
+     * @param reqCtx 运行上下文（上下文统一化 Stage 1：chat-engine run 内分发时传入；
+     *               意图路径身份/凭据/attributes 的显式来源——替代旧 ctx.auth 全局读取）。
+     */
+    handle(action: string, payload: unknown, ctx: ServerContext, reqCtx?: RequestContext): Promise<HandlerResult>;
+}
+/** 从已注册 handlers 收集意图路由（011 D7：装配端调用；match 透传——exact/prefix 走洋葱确定性档） */
+declare function collectIntentRoutes(handlers: ReadonlyMap<string, HandlerDefinition> | Record<string, HandlerDefinition>): {
+    id: string;
+    keywords: string[];
+    handlerId: string;
+    action: string;
+    match?: 'exact' | 'prefix' | 'bm25';
+}[];
+/**
+ * HandlerRegistry：无状态路由表（001 §3.4）。
+ * - 无实例池 / 无 sessionId 参数 / 无 createInstance / destroy —— 状态归业务（ctx.flowStates）
+ */
+declare class HandlerRegistry {
+    private handlers;
+    register(def: HandlerDefinition): void;
+    resolve(id: string): HandlerDefinition | undefined;
+    getAll(): Record<string, HandlerDefinition>;
+    has(id: string): boolean;
+    get size(): number;
+    dispatch(handlerId: string, action: string, payload: unknown, ctx: ServerContext, reqCtx?: RequestContext): Promise<HandlerResult>;
+}
+
+interface EmitCardSpec {
+    cardType: string;
+    data: Record<string, unknown>;
+    /** 目标会话（006 D5：conversationId 唯一会话键） */
+    conversationId: string;
+    messageId?: string;
+    id?: string;
+}
+/**
+ * CardEmitter：卡片下发机制（001 §2.4 / 003 §4.2 独立化）。
+ * - emit：按 CardRegistry 校验 data schema 后下发 CUSTOM('tbox:card') 事件；
+ *   填充 schemaVersion + meta.createdAt（P3 W1，供快照持久化与迁移使用）。
+ * - 返回下发后的 TboxCardPayload（含填充字段），chat-engine 据此写入本轮 run 的卡片缓冲
+ *   （004 W1：写入缓冲而非即时落库）。
+ */
+declare class CardEmitter {
+    private cardRegistry;
+    constructor(cardRegistry: Record<string, CardMeta>);
+    emit(spec: EmitCardSpec, onEvent: (event: ServerEvent) => void): TboxCardPayload | undefined;
+    /** 011 B3：两段式——只校验 + 构造 payload（不发送）；token 签发等预处理后经 send 下发 */
+    build(spec: EmitCardSpec): TboxCardPayload | undefined;
+    /** 发送 CUSTOM('tbox:card') 事件（build 产物；dispatcher 直发同用） */
+    send(payload: TboxCardPayload, onEvent: (event: ServerEvent) => void): TboxCardPayload;
+}
+
+/**
+ * 防重放存储（004 W2 C3）。
+ * 接口化 + InMemory LRU（TTL + 上限），可换 Redis。
+ * 语义：时间窗内同一 key 的重复请求视为重放。
+ */
+interface ReplayStore {
+    /** 记录 key（TTL 窗口内有效），窗口内重复返回 true */
+    checkAndSet(key: string, ttlMs?: number): Promise<boolean>;
+}
+/** InMemory LRU：Map 迭代序即插入序（近似 LRU），超过上限时淘汰最旧 */
+declare class InMemoryLruReplayStore implements ReplayStore {
+    private store;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    constructor(opts?: {
+        ttlMs?: number;
+        maxEntries?: number;
+    });
+    checkAndSet(key: string, ttlMs?: number): Promise<boolean>;
+    private evict;
+    clear(): void;
+}
+
+/**
+ * 服务端模块装配框架（010 下沉 S1）：遍历模块 + 声明式字段自动注册 + register。
+ * - skills（009）/ preTools（010）声明式字段在此自动注册，模块 register 内无需代码；
+ * - 未来新增声明式字段只在此处加一行，模板装配零改动；
+ * - `await m.register(ctx)`：模块 register 可为 async——模板旧装配为 sync 循环不等待
+ *   （隐性缺陷），下沉时顺带修正（sync 模块行为不变）。
+ * - 模块级 logger 注入：每模块浅拷贝 ctx（注册表共享引用不变）挂 logger
+ *   （tag=module:<moduleId>）；模块闭包捕获即获 tag + req/conv 关联（对象注入
+ *   免疫多 SDK 副本，模块不 import SDK 单例——与"禁 import SDK 全局单例"铁律一致）。
+ * - app-config 自动装配（W1-④）：模块资源消费入口无条件注册（与控制面正交——防无控制面
+ *   启动静默丢失；参数经 ctx.integrations.raw 派生：modules 资源节 + 源目录台账锚，
+ *   registry 缺席 → 空资源零 IO）。显式注册优先（过渡期模板自注册在位不拆）。
+ */
+declare function registerServerModules(ctx: ServerContext, modules: readonly ServerModule[]): Promise<void>;
+
+/** 服务端统一响应封装 */
+interface SdkResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 错误码 */
+    errorCode?: string;
+    /** 错误信息 */
+    errorMsg?: string;
+    /** 链路追踪 ID */
+    traceId?: string;
+}
+/** C端 Session 鉴权信息（generateSession 获取） */
+interface SessionAuth {
+    /** 会话 ID（通过 generateSession 获取） */
+    sessionId: string;
+    /** 登录渠道（通过 generateSession 获取） */
+    channel: string;
+    /** 百宝箱应用 ID */
+    appId: string;
+}
+/** C端客户端配置（通过 Session 鉴权） */
+interface TboxSessionClientConfig {
+    /** C端 Session 鉴权信息 */
+    session: SessionAuth;
+    /** 自定义 base URL（可选，默认 TBOX_BASE_URL） */
+    baseUrl?: string;
+    /** 请求超时时间（毫秒，可选） */
+    timeout?: number;
+}
+/** B端客户端配置（通过 apiKey 鉴权） */
+interface TboxApiKeyClientConfig {
+    /** API Key（通过 Authorization 头传递） */
+    apiKey: string;
+    /** 自定义 base URL（可选，默认 TBOX_BASE_URL） */
+    baseUrl?: string;
+    /** 请求超时时间（毫秒，可选） */
+    timeout?: number;
+}
+/** 用户信息条目（key-value 形式） */
+interface UserInfo {
+    /** 信息类型，枚举值如：name、phone、email 等 */
+    infoType: string;
+    /** 信息值 */
+    infoValue: string;
+}
+/** 设备信息 */
+interface DeviceInfo {
+    productType?: string;
+    appName?: string;
+    appVersion?: string;
+    platform?: string;
+    system?: string;
+    deviceId?: string;
+    deviceName?: string;
+    deviceModel?: string;
+    deviceBrand?: string;
+}
+/** 生成 Session 请求 */
+interface AppGenerateSessionRequest {
+    /** 百宝箱应用 ID */
+    appId: string;
+    /** 用户 ID */
+    userId: string;
+    /** 请求来源（可选） */
+    source?: string;
+    /** 发布渠道（可选） */
+    fromSource?: string;
+    /** 请求的链接类型（可选） */
+    type?: string;
+    /** 用户信息列表（可选） */
+    userInfo?: UserInfo[];
+    /** 设备信息（可选） */
+    deviceInfo?: DeviceInfo;
+}
+/** 生成 Session 响应 */
+interface AppSessionResult {
+    /** 会话 ID，用于免登录访问百宝箱应用 */
+    sessionId?: string;
+    /** 登录渠道，固定值 third_platform_sdk_login */
+    channel?: string;
+}
+/** 分页查询结果 */
+interface PaginationResult<T> {
+    /** 数据列表（服务端字段名：data） */
+    data?: T[];
+    /** 总条数（服务端字段名：totalCount） */
+    totalCount?: number;
+    /** 当前页码（服务端字段名：currentPage） */
+    currentPage?: number;
+    /** 每页条数 */
+    pageSize?: number;
+}
+/** 创建会话请求 */
+interface ConversationCreateRequest {
+    /** 百宝箱应用 ID（agentId） */
+    agentId: string;
+    /** 用户 ID */
+    userId: string;
+}
+/** 查询会话列表请求 */
+interface ConversationQueryRequest {
+    agentId?: string;
+    userId?: string;
+    fromSource?: string;
+    pageNum?: number;
+    pageSize?: number;
+    [key: string]: unknown;
+}
+/** 会话信息 */
+interface ConversationInfo {
+    /** 会话 ID（服务端字段名：id） */
+    id?: string;
+    appId?: string;
+    fromEndUserId?: string;
+    fromSource?: string;
+    gmtCreate?: string;
+    [key: string]: unknown;
+}
+/** 查询消息列表请求 */
+interface MessageQueryRequest {
+    conversationId?: string;
+    /** 百宝箱应用 ID（必填，服务端校验非空） */
+    agentId: string;
+    userId?: string;
+    fromSource?: string;
+    beforeId?: string;
+    pageNo?: number;
+    pageSize?: number;
+}
+/** 消息信息 */
+interface MessageInfo {
+    messageId?: string;
+    conversationId?: string;
+    query?: string;
+    answer?: string;
+    mediaType?: string;
+    generateState?: string;
+    outerBusinessId?: string;
+    createTime?: number;
+    [key: string]: unknown;
+}
+/** 保存会话消息请求 */
+interface MessageSaveRequest {
+    /** 百宝箱应用 ID（必填，服务端鉴权需要） */
+    agentId: string;
+    /** 会话 ID */
+    conversationId: string;
+    query?: string;
+    answer?: string;
+    mediaType?: string;
+    generateState?: string;
+    outerBusinessId?: string;
+    inputs?: Record<string, unknown>;
+    multiModalInputs?: Record<string, unknown>;
+    extraParams?: string;
+}
+/** C端语音识别请求 */
+interface AsrRecognizeRequest {
+    /** Base64 编码的音频数据（必填） */
+    base64_audio: string;
+    /** 采样率，默认 '16000' */
+    sample_rate?: string;
+    /** 音频格式，默认 'webm' */
+    audio_format?: string;
+}
+/** C端语音识别响应 */
+interface AsrRecognizeResponse {
+    /** 识别出的文本 */
+    text: string;
+}
+/** 文件类型 */
+type FileType = 'image' | 'video' | 'audio' | 'file';
+/** C端文件上传请求（POST /api/files/afts/upload，FormData） */
+interface FileUploadRequest {
+    /** 文件 Blob 或 File 对象 */
+    file: Blob | File;
+    /** 文件类型 */
+    fileType: FileType;
+    /** 文件名（可选，默认 'upload'） */
+    fileName?: string;
+}
+/** C端文件上传响应 */
+interface FileUploadResponse {
+    /** 上传后的文件 ID */
+    fileId: string;
+    /** 是否通过安全审核 */
+    safed: boolean;
+}
+/** 反馈类型 */
+type FeedbackValue = 'LIKE' | 'DISLIKE' | 'CANCEL';
+/** C端反馈请求（POST /agent/v1/plugin/proxy） */
+interface FeedbackRequest {
+    /** 消息请求 ID（来自对话事件的 chat_id） */
+    requestId: string;
+    /** 反馈类型 */
+    feedback: FeedbackValue;
+}
+/** C端反馈响应 */
+interface FeedbackResponse {
+    success: boolean;
+}
+/** TTS 语音/音频配置 */
+interface TtsVoiceConfig {
+    /** 发音人代码，默认 'lingyue' */
+    voiceCode?: string;
+    /** 发音人类型，默认 'SYSTEM' */
+    voiceType?: string;
+    /** 采样率（Hz），默认 24000 */
+    sampleRate?: number;
+    /** 音量（0-100），默认 50 */
+    volume?: number;
+    /** 语速调节，默认 0 */
+    speechRate?: number;
+    /** 音调调节，默认 0 */
+    pitchRate?: number;
+}
+/** TTS 鉴权结果（fetchAuth 返回 data） */
+interface TtsAuthResult {
+    /** 服务端时间戳 */
+    timestamp: string;
+    /** HMAC 签名摘要 */
+    digest: string;
+}
+/** TboxTtsClient 配置（TTS 鉴权走 C端 Session 体系） */
+interface TboxTtsClientConfig {
+    /** 百宝箱应用 ID（对应 X-Tbox-AppId 请求头） */
+    appId: string;
+    /** TTS 服务的 appkey */
+    appkey: string;
+    /** TTS 鉴权接口完整 URL */
+    authUrl: string;
+    /** C端会话 ID（对应 TBOXSESSIONID 请求头） */
+    sessionId?: string;
+    /** 登录渠道（对应 X-Tbox-Channel 请求头） */
+    channel?: string;
+    /** 上游 TTS WebSocket 地址（可选，默认 wss://mediafeature.alipay.com:443/tts_stream） */
+    upstreamUrl?: string;
+    /** 自定义 base URL（可选，默认 TBOX_BASE_URL） */
+    baseUrl?: string;
+    /** 请求超时时间（毫秒，可选） */
+    timeout?: number;
+}
+/** TboxTtsClient.create() 便捷工厂参数（B端 apiKey 自动获取 session） */
+interface CreateTtsClientOptions {
+    /** B端 API Key（用于调用 generateSession） */
+    apiKey: string;
+    /** 百宝箱应用 ID */
+    appId: string;
+    /** 用户 ID */
+    userId: string;
+    /** TTS 服务的 appkey */
+    appkey: string;
+    /** TTS 鉴权接口完整 URL */
+    authUrl: string;
+    /** 登录渠道（可选，未提供时从 session 获取） */
+    channel?: string;
+    /** 上游 TTS WebSocket 地址（可选） */
+    upstreamUrl?: string;
+    /** 自定义 base URL（可选） */
+    baseUrl?: string;
+    /** 请求超时时间（毫秒，可选） */
+    timeout?: number;
+}
+
+/**
+ * 百宝箱应用服务客户端（/openapi/v1/app）
+ */
+declare class TboxAppClient {
+    private http;
+    constructor(config: TboxApiKeyClientConfig);
+    /**
+     * 根据用户信息生成 sessionId 和 channel
+     * 接口：POST /openapi/v1/app/generate_session
+     */
+    generateSession(request: AppGenerateSessionRequest): Promise<SdkResponse<AppSessionResult>>;
+}
+
+/**
+ * 百宝箱会话管理客户端
+ */
+declare class TboxConversationClient {
+    private http;
+    constructor(config: TboxApiKeyClientConfig);
+    /** 创建新会话：POST /openapi/v1/conversation/create */
+    createConversation(request: ConversationCreateRequest): Promise<SdkResponse<string>>;
+    /** 查询会话列表（分页）：POST /openapi/v1/conversation/list */
+    listConversations(request: ConversationQueryRequest): Promise<SdkResponse<PaginationResult<ConversationInfo>>>;
+    /** 查询消息列表（分页）：POST /openapi/v1/conversation/message/list */
+    listMessages(request: MessageQueryRequest): Promise<SdkResponse<PaginationResult<MessageInfo>>>;
+    /** 新增会话消息：POST /openapi/v1/conversation/message/save */
+    saveMessage(request: MessageSaveRequest): Promise<SdkResponse<string>>;
+}
+
+/**
+ * 百宝箱 C端文件上传客户端（/api/files/afts/upload；C端鉴权三头）
+ */
+declare class TboxUploadClient {
+    private http;
+    /** 使用 C端 Session 鉴权构造 */
+    constructor(config: TboxSessionClientConfig);
+    /** C端文件上传：POST /api/files/afts/upload（FormData） */
+    upload(request: FileUploadRequest): Promise<SdkResponse<FileUploadResponse>>;
+}
+
+/** TTS 语音/音频默认配置 */
+declare const TTS_DEFAULTS: {
+    readonly voiceCode: "lingyue";
+    readonly voiceType: "SYSTEM";
+    readonly sampleRate: 24000;
+    readonly volume: 50;
+    readonly speechRate: 0;
+    readonly pitchRate: 0;
+};
+/**
+ * 百宝箱 C端文字转语音客户端
+ *
+ * TTS 使用 WebSocket 与上游 Alipay TTS 服务通信，客户端负责：
+ * 1. 鉴权（fetchAuth → timestamp + digest）
+ * 2. 构建上游 WSS URL（带 HMAC 签名参数）
+ * 3. 构建 WS 消息 payload（start / text / stop）
+ *
+ * WebSocket 连接本身由消费者管理。
+ */
+declare class TboxTtsClient {
+    appId: string;
+    appkey: string;
+    authUrl: string;
+    sessionId?: string;
+    channel?: string;
+    upstreamUrl: string;
+    timeout?: number;
+    constructor(config: TboxTtsClientConfig);
+    /** 便捷工厂方法：通过 B端 apiKey 自动获取 session，提取 channel 后构造 TTS 客户端 */
+    static create(options: CreateTtsClientOptions): Promise<TboxTtsClient>;
+    /**
+     * 获取 TTS 鉴权信息（timestamp + digest），用于连接上游 WebSocket
+     * POST {authUrl}；Headers: TBOXSESSIONID + X-Tbox-Channel + X-Tbox-AppId；Body: { appkey }
+     */
+    fetchAuth(): Promise<SdkResponse<TtsAuthResult>>;
+    /** 构建上游 TTS WebSocket URL（带 Alipay HMAC 签名参数） */
+    buildUpstreamUrl(auth: TtsAuthResult): string;
+    /** 构建上游 WS 初始化 payload（start action） */
+    static buildPayload(voiceConfig?: TtsVoiceConfig): Record<string, unknown>;
+    /** 构建发送文本的上游 payload（JSON 字符串，直接通过 WS 发送） */
+    static buildTextPayload(text: string): string;
+    /** 构建停止 TTS 流的上游 payload */
+    static buildStopPayload(): string;
+    /** 生成 32 位十六进制任务 ID */
+    static generateTaskId(): string;
+}
+
+/**
+ * 百宝箱 C端语音识别客户端
+ */
+declare class TboxAsrClient {
+    private http;
+    /** 使用 C端 Session 鉴权构造 */
+    constructor(config: TboxSessionClientConfig);
+    /**
+     * C端语音识别（Base64 音频输入）：POST /agent/v1/plugin/asrBase64
+     */
+    recognize(request: AsrRecognizeRequest): Promise<SdkResponse<AsrRecognizeResponse>>;
+}
+
+/**
+ * 百宝箱 C端反馈客户端（点赞/点踩/取消；/agent/v1/plugin/proxy；C端鉴权三头）
+ */
+declare class TboxFeedbackClient {
+    private http;
+    /** 使用 C端 Session 鉴权构造 */
+    constructor(config: TboxSessionClientConfig);
+    /** 点赞/点踩/取消反馈：POST /agent/v1/plugin/proxy */
+    addTag(request: FeedbackRequest): Promise<SdkResponse<FeedbackResponse>>;
+}
+
+/** notice 文案上限（超长截断，防 toast 刷屏） */
+declare const NOTICE_TEXT_MAX_LEN = 200;
+/** 截断至上限（dispatcher text 补位与本文件错误映射共用单源） */
+declare function truncateNoticeText(text: string): string;
+declare function toNoticeText(err: unknown): TboxNoticePayload;
+
+/**
+ * 鉴权错误（006 错误码体系）。status 由 authCodeToStatus 映射。
+ */
+
+declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly status: number;
+    constructor(code: AuthErrorCode, message?: string);
+    static unauthorized(message?: string): AuthError;
+    static tokenExpired(message?: string): AuthError;
+    static forbidden(message?: string): AuthError;
+    static methodRequired(message?: string): AuthError;
+    static browserLoginDisabled(message?: string): AuthError;
+    static externalError(message?: string): AuthError;
+    static missingSecret(message?: string): AuthError;
+}
+
+interface TokenServiceOptions {
+    /** HS256 共享密钥（至少 32 字节；来自 AUTH_TOKEN_SECRET → TBOX_API_KEY → dev 临时） */
+    secret: string;
+    issuer?: string;
+    ttlMs?: number;
+    clockToleranceSec?: number;
+    /** 是否允许签发携带 external claim（AUTH_EMBED_EXTERNAL_TOKEN，默认开） */
+    embedExternalToken?: boolean;
+    /**
+     * external 原始 token 上限（bytes，评审 P1-H）。
+     * external claim 使自有 JWT 膨胀 ~1.4x（base64url），大 token 会逼近网关/代理 header 上限
+     * （nginx 单 header 默认 8KB；Node http 默认 16KB）。超限拒签（防发出必败请求 + 网关日志泄漏）。
+     * 默认 16KB，可经 AUTH_EXTERNAL_TOKEN_MAX_BYTES 调整。
+     */
+    maxExternalTokenBytes?: number;
+}
+interface IssueOptions {
+    /** 外部原始凭据（门控 embedExternalToken） */
+    external?: ExternalCredentials;
+    /** 测试注入时间（ms epoch） */
+    now?: number;
+}
+interface TokenService {
+    issue(identity: Identity, opts?: IssueOptions): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /** 校验并返回 payload；非法/过期抛 AuthError（AUTH_UNAUTHORIZED / AUTH_TOKEN_EXPIRED） */
+    verify(token: string): Promise<TokenPayload>;
+    /**
+     * 续签校验（previousToken 轨）：忽略过期（仍验签名/issuer/alg 白名单/sub/source/前缀一致性）。
+     * 仅登录路由续签使用——重签窗（30d）判定归调用方，本方法不裁窗。
+     */
+    verifyIgnoringExpiration(token: string): Promise<TokenPayload>;
+}
+declare function createTokenService(opts: TokenServiceOptions): TokenService;
+
+/**
+ * 共享身份/上下文解析内核（上下文统一化 Stage 1）。
+ *
+ * HTTP 中间件与 WS HELLO 鉴权的共同提取：resolveBearerAuth 统一 Bearer token 三态
+ * （合法 / optional 缺失 → 匿名 / required 缺失或非法 → AuthError），消除双实现漂移；
+ * normalizeContextEnvelope 统一 context 信封归一（plain object + ≤4KB），三入口共用
+ * （WS HELLO / HTTP body.context / login body.context）——超限丢弃走 warn（防静默 scope 交换）。
+ */
+
+/** 身份解析结果（HTTP 中间件与 WS HELLO 共用形态） */
+interface ResolvedAuth {
+    identity: Identity;
+    credentials?: ExternalCredentials;
+}
+/**
+ * 统一 Bearer 身份解析（middleware.ts 与 ws-auth.ts 的共同内核）：
+ * - token 非法 → AuthError（HTTP 层转 401；WS 层转 close 4001）
+ * - token 缺失 + optional → 匿名身份（服务端生成，不签发 JWT）
+ * - token 缺失 + required → AuthError.unauthorized
+ */
+declare function resolveBearerAuth(tokenService: TokenService, token: string | undefined, mode: 'required' | 'optional'): Promise<ResolvedAuth>;
+/** context 信封上限（与 login/HELLO context 体积约束同数量级，UTF-8 字节） */
+declare const CONTEXT_ENVELOPE_MAX_BYTES = 4096;
+/**
+ * 统一 context 信封归一：plain object 且序列化 ≤4KB（UTF-8）才透传，否则
+ * undefined（fail-soft——非法 context 不阻断主链路）+ 丢弃 warn（可观测：
+ * 客户端意图 scope 不被静默替换）。
+ */
+declare function normalizeContextEnvelope(raw: unknown): Record<string, unknown> | undefined;
+
+/**
+ * HTTP 鉴权中间件（006 D7）。
+ * - 读取 `Authorization: Bearer <token>`，校验后把 RequestContext 挂到 req（tboxAuthContext）。
+ * - AUTH_MODE=optional 时缺失 token → 服务端生成匿名身份（不签发 JWT）。
+ * - 白名单路径（登录/健康等）直接放行。
+ * - [HTTP] 访问日志（006 日志轴）：reqId 锚点（入站 X-Request-ID 清洗后优先）+ 回写响应头
+ *   + runLogScope ALS（请求内全部日志行自动带 req= 尾缀）+ finish 访问行。挂载于 /api 最前，
+ *   单点覆盖全部 API face（含 404）；健康探测降 debug。HTTP 面不发 TBOX_TRACE span
+ *   （trace 平面只属引擎 run——平台按 conv/req 拉取语义不被污染）。
+ */
+
+type AuthMode = 'required' | 'optional';
+interface AuthMiddlewareOptions {
+    mode?: AuthMode;
+    /** 放行路径前缀（如 /api/auth/login、/api/auth/dev-login、/api/health） */
+    publicPaths?: string[];
+    /**
+     * 域校验钩子（上下文统一化 Stage 1）：装配端注入（如 mall 白名单——
+     * createAuthRuntime validateContext 转发）。仅当请求携带 context（POST body.context
+     * 归一通过）时调用；拒绝 → 403 AUTH_FORBIDDEN（scope 伪冒防线）。
+     */
+    validateContext?: (attributes: Record<string, unknown>) => boolean;
+}
+declare function setRequestContext(req: Request, ctx: RequestContext): void;
+/** 读取当前请求的运行上下文（authMiddleware 之后可用；未鉴权为 undefined） */
+declare function getRequestContext(req: Request): RequestContext | undefined;
+/** 匿名身份（optional 模式 / 缺失 token 时服务端生成；不签发 JWT） */
+declare function createAnonymousIdentity(now?: number): Identity;
+declare function createAuthMiddleware(tokenService: TokenService, opts?: AuthMiddlewareOptions): RequestHandler;
+
+/**
+ * WebSocket 鉴权（006 D6/D7/D12）。
+ * - HELLO 消息体携带 token（不拼 URL，防日志/Referer 泄漏）。
+ * - 校验成功后返回连接级身份（Identity + 可选外部凭据），由 ws-server 绑定到连接。
+ * - optional 模式：无 token 的 HELLO → 匿名身份（服务端生成，不签发 JWT）。
+ * - 身份解析统一走 resolveBearerAuth（与 HTTP 中间件共享内核，消除双实现漂移）。
+ */
+
+interface AuthenticatedAuth {
+    identity: Identity;
+    credentials?: ExternalCredentials;
+}
+interface WsAuthenticator {
+    /** token 校验；缺失/非法抛 AuthError（optional 下缺失 → 匿名身份） */
+    authenticate(token?: string): Promise<AuthenticatedAuth>;
+}
+interface WsAuthOptions {
+    mode?: 'required' | 'optional';
+}
+declare function createWsAuthenticator(tokenService: TokenService, opts?: WsAuthOptions): WsAuthenticator;
+
+/**
+ * Provider dev fixture + 内存传输测试工具（011 G6）：
+ * - registerDevProviderFixture：非生产挂载点（模块注册假数据处理器）；
+ * - createInMemoryTransport：测试工具（脚本化响应/请求记录/故障注入）。
+ */
+
+interface FixtureHandler {
+    (req: {
+        path: string;
+        body?: unknown;
+    }): unknown;
+}
+declare function registerDevProviderFixture(templateId: string, handler: FixtureHandler): void;
+declare function clearDevProviderFixtures(): void;
+declare function hasDevProviderFixture(templateId: string): boolean;
+declare function runDevProviderFixture(templateId: string, req: {
+    path: string;
+    body?: unknown;
+}): unknown;
+/** fixture 传输工厂：命中 fixture 的 templateId 走 fixture，其余走真实工厂 */
+declare function createFixtureTransportFactory(real: TransportFactory): TransportFactory;
+/** 内存传输测试工具：脚本化响应 / 请求记录 / 故障注入（011 G6） */
+interface InMemoryTransport extends AuthenticatedTransport {
+    mock(path: string, respond: (body: unknown) => unknown): void;
+    requests(): Array<{
+        path: string;
+        body?: unknown;
+    }>;
+    failNext(error: Error): void;
+}
+declare function createInMemoryTransport(): InMemoryTransport;
+
+/**
+ * 卡片动作 token 签发（011 E7/B3 修复）：出卡时按 cardType 匹配注册动作，
+ * 附加 payload.actions（声明）与 payload.actionTokens（HMAC 授权 token）。
+ * - 单一签发点：chat-engine 出卡与 dispatcher 结果卡/原地更新共用本函数；
+ * - 无匹配动作 → 原样返回（零开销）；
+ * - 签发失败（如密钥缺失）→ warn + 跳过该动作（不阻断出卡）；
+ * - P1 富形状：kind/style/enabled 等呈现字段透传 payload.actions；仅 moduleAction
+ *   （含缺省）签发 token——sendMessage/openLink 为纯客户端语义，不进授权链。
+ */
+
+interface AttachCardActionTokensInput {
+    payload: TboxCardPayload;
+    actions: CardActionRegistry;
+    grants: ActionGrantService;
+    sessionId: string;
+    scope: Record<string, string>;
+}
+declare function attachCardActionTokens(input: AttachCardActionTokensInput): Promise<TboxCardPayload>;
+
+interface KnowledgeHit {
+    content: string;
+    score: number;
+    /** 来源文件名 */
+    originFileName?: string;
+    documentId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeClient {
+    search(input: {
+        datasetId: string;
+        query: string;
+        topK?: number;
+        scoreThreshold?: number;
+    }): Promise<KnowledgeHit[]>;
+}
+interface KnowledgeClientOptions {
+    apiKey?: string;
+    appId?: string;
+    /** 缺省绑定 datasetId（search 未传时使用） */
+    datasetId?: string;
+    topK?: number;
+}
+declare class KnowledgeError extends Error {
+    readonly code: 'MISSING_CREDENTIAL' | 'API_ERROR' | 'EMPTY_RESULT';
+    constructor(code: 'MISSING_CREDENTIAL' | 'API_ERROR' | 'EMPTY_RESULT', message: string);
+}
+declare function createKnowledgeClient(opts?: KnowledgeClientOptions): KnowledgeClient;
+
+/**
+ * 平台支付客户端（011 A3：首期纳入支付，SDK 通道层，业务闭环二期）。
+ * 支付宝收银台薄客户端：创建收银台 + 结果查询。
+ * 平台支付 API 未就绪前 createCashier 抛「未装配」；就绪后经平台接口对接。
+ */
+interface CashierResult {
+    cashierUrl: string;
+}
+type PaymentStatus = 'PAID' | 'PENDING' | 'FAILED' | 'UNKNOWN';
+interface PaymentClient {
+    createCashier(input: {
+        orderRef: string;
+        amountCents: number;
+        subject: string;
+    }): Promise<CashierResult>;
+    queryResult(input: {
+        orderRef: string;
+    }): Promise<{
+        status: PaymentStatus;
+    }>;
+}
+interface PaymentClientOptions {
+    /** 宿主注入处理器（模板装配点）：对接平台收银台 API */
+    createCashierHandler?: (input: {
+        orderRef: string;
+        amountCents: number;
+        subject: string;
+    }) => Promise<CashierResult>;
+    queryResultHandler?: (input: {
+        orderRef: string;
+    }) => Promise<{
+        status: PaymentStatus;
+    }>;
+}
+declare class PaymentError extends Error {
+    readonly code: 'NOT_CONFIGURED' | 'API_ERROR';
+    constructor(code: 'NOT_CONFIGURED' | 'API_ERROR', message: string);
+}
+declare function createPaymentClient(opts?: PaymentClientOptions): PaymentClient;
+
+/**
+ * 模块资源 resolver（integrations v5：modules 节内存源求值）。
+ * 分层归位：wire 类型 = contracts（ResourceSpec/ModuleConfig）；zod = integrations-config.ts；
+ * 本文件只做 IO 密封——knowledge.json 台账 ref 展开（锚 = integrations.json 所在目录，与数据同源旅行）。
+ * 预计算模型：构造期一次算清（ref-miss/参数问题 warn 一次打在启动日志），调用期纯 Map 查表。
+ * 资源级 fail-soft：miss → 资源缺席（模块占位回退，与缺键同语义）。
+ */
+
+/** 求值产物（ref 已展开；datasetId 必填——resolver/占位常量保证） */
+type ResolvedResource = {
+    type: 'knowledge';
+    datasetId: string;
+    topK?: number;
+    scoreThreshold?: number;
+};
+/** resolver 服务契约（app-config 服务注册物；键 = 模块 install id） */
+type ModuleResourceResolver = (moduleId: string) => Readonly<Record<string, ResolvedResource>>;
+/** 占位 datasetId 哨兵单源（模块占位常量 + smoke R1 判定共用；'faq'/'mall-knowledge' 历史值） */
+declare const KNOWLEDGE_PLACEHOLDER_DATASET_IDS: readonly ["faq", "mall-knowledge"];
+/**
+ * 预计算工厂。modules 缺席（裸跑态/无资源应用）→ 空 resolver 零 IO；
+ * 无 ref 声明 → 跳过台账读（模板态/直填态零额外 IO）。
+ * knowledgeDir = integrations.json 所在目录（ref 台账与数据同源——TBOX_INTEGRATIONS_FILE 逃生舱防 split-brain）。
+ */
+declare function createModuleResourceResolver(modules: Record<string, ModuleConfig> | undefined, knowledgeDir: string): ModuleResourceResolver;
+
+interface KnowledgeBaseEntry {
+    datasetId: string;
+    topK?: number;
+    scoreThreshold?: number;
+}
+interface KnowledgeRegistry {
+    /** name → 展平条目（retrieve_config 已并入） */
+    bases: Readonly<Record<string, KnowledgeBaseEntry>>;
+    /** 台账全局缺省参数（仅 ref 展开期参与兜底） */
+    defaults: {
+        topK?: number;
+        scoreThreshold?: number;
+    };
+}
+/**
+ * 读取 config/knowledge.json（configDir 与组件 json 同目录）。
+ * 缺文件静默空（模板态常态）；解析/校验失败 warn + 空（fail-soft）。
+ */
+declare function loadKnowledgeRegistry(configDir: string): KnowledgeRegistry;
+
+interface EnvExpansionErrorInfo {
+    file: string;
+    missing: string[];
+}
+/** 展开配置文本；缺失变量 → throw（信息含文件 + 缺失清单 + source 指引，不含值） */
+declare function expandEnvVars(text: string, env?: Readonly<Record<string, string | undefined>>, file?: string): string;
+
+type Environment = Readonly<Record<string, string | undefined>>;
+interface AlipayAuthorizedUserProfile {
+    readonly userId: string;
+    readonly mobile?: string;
+    readonly displayName?: string;
+    readonly avatarUrl?: string;
+    readonly gender?: 'male' | 'female' | 'unknown';
+    readonly birthday?: string;
+}
+interface AlipayUserAuthorization {
+    authorizeUserProfile(authCode: string): Promise<AlipayAuthorizedUserProfile>;
+}
+declare function createAlipayUserAuthorization(environment?: Environment, fetchImplementation?: typeof fetch): AlipayUserAuthorization;
+declare function formatAlipayTimestamp(date: Date): string;
+declare function toPem(raw: string, kind: 'PRIVATE' | 'PUBLIC'): string;
+declare function signAlipayParams(params: Readonly<Record<string, string>>, privateKey: string): string;
+
+interface AuthConfig {
+    secret: string;
+    /** HS256 密钥链来源（日志/提醒用）：platform | apiKey | dev-temp */
+    secretSource: 'platform' | 'apiKey' | 'dev-temp';
+    /** required=强制鉴权；optional=缺失 token 时匿名（降级，不放开写通道） */
+    mode: 'required' | 'optional';
+    issuer?: string;
+    ttlMs?: number;
+    /** 是否内嵌外部原始 token（external claim） */
+    embedExternalToken: boolean;
+    /** external 原始 token 上限（bytes，防 header 膨胀；缺省 16KB） */
+    externalTokenMaxBytes?: number;
+    /** 外部 provider 配置（换发用），未配置则走本地换码 */
+    external?: {
+        exchangeUrl: string;
+        secret: string;
+        provider: string;
+        timeoutMs: number;
+        /** 外部已签 JWT 验签公钥（PEM, RS256）：`{ jwt }` 响应无 identity 时解 sub */
+        jwtPublicKey?: string;
+    };
+}
+declare function readAuthConfig(env?: NodeJS.ProcessEnv): AuthConfig;
+/** 由配置装配 TokenService（单一装配点：createAuthRuntime(readAuthConfig())） */
+declare function createTokenServiceFromConfig(config: AuthConfig): TokenService;
+
+/**
+ * 统一鉴权装配点（006 §2 平台轴 + 业务轴）：createAuthRuntime(readAuthConfig())。
+ * 产出：tokenService（签发/校验）+ middleware（HTTP Bearer）+ router（login/me）
+ *       + wsAuth（WS HELLO 鉴权）。
+ * 扩展点（B4）：options.exchanges 注入自定义/覆盖本地换码器（注入优先于内置 alipay/weapp）。
+ */
+
+interface AuthRuntime {
+    config: AuthConfig;
+    tokenService: TokenService;
+    /** HTTP Bearer 鉴权中间件（全局 /api，白名单放行 login/health） */
+    middleware: RequestHandler;
+    /** 登录/身份路由（POST /api/auth/login、GET /api/auth/me） */
+    router: Router;
+    /** WS HELLO 鉴权器 */
+    wsAuth: WsAuthenticator;
+    /** 是否启用外部 provider 换发 */
+    externalEnabled: boolean;
+    /**
+     * 换码器注册表（F0 惰性查找）：登录请求期 get(platform)。模板装配应将其传入
+     * createServerContext({ authExchanges })——模块/provider register 期注册晚于本构造仍生效。
+     */
+    exchanges: AuthExchangeRegistry;
+}
+interface AuthRuntimeOptions {
+    /** 自定义/覆盖本地换码器（key = platform，如 alipay/weapp；注入优先于内置） */
+    exchanges?: Record<string, IdentityExchange>;
+    /**
+     * 域校验钩子（上下文统一化 Stage 1）：转发给全局 HTTP 中间件的 validateContext
+     * （POST body.context 归一通过后调用；拒绝 → 403）。只注入全局面——login/dev-login
+     * 的 body.context 有独立归一化（login-routes）+ 换码器 scoped 路由语义，不重复治理。
+     */
+    validateContext?: (attributes: Record<string, unknown>) => boolean;
+}
+declare function createAuthRuntime(envOrConfig?: NodeJS.ProcessEnv | AuthConfig, options?: AuthRuntimeOptions): AuthRuntime;
+
+/** 微信 jscode2session：code → openid */
+declare class LocalWeappExchange implements IdentityExchange {
+    readonly provider = "weapp";
+    /** 裸/demo 域默认开放 guest 登录（browser 轴 auto 档 → guest 签发） */
+    allowsGuestLogin(): boolean;
+    exchangeByCode({ code }: ExchangeRequest): Promise<ExchangeResult>;
+}
+/** 支付宝 alipay.system.oauth.token：code → userId */
+declare class LocalAlipayExchange implements IdentityExchange {
+    readonly provider = "alipay";
+    /** 裸/demo 域默认开放 guest 登录（browser 轴 auto 档 → guest 签发） */
+    allowsGuestLogin(): boolean;
+    exchangeByCode({ code }: ExchangeRequest): Promise<ExchangeResult>;
+}
+
+/**
+ * 外部身份字段映射（006 D4 修订）：外部返回的原始身份对象 → 自有 Identity。
+ * - **userId 原样保留**（不加 ext_ 前缀、不做前缀归一化——外部系统自管命名空间，
+ *   平台不改造外部 id，便于与外部体系直接对应）；
+ * - source 恒为 'external'（来源由 source 字段区分，不依赖 userId 前缀）；
+ * - displayName/avatar 可选透传；
+ * - 字段名覆盖常见外部语义（userId/openId/uid/id/unionId），自定义映射由业务方扩展。
+ */
+
+interface ExternalRawIdentity {
+    userId?: string;
+    openId?: string;
+    openid?: string;
+    uid?: string;
+    id?: string;
+    unionId?: string;
+    displayName?: string;
+    nickname?: string;
+    name?: string;
+    avatar?: string;
+    avatarUrl?: string;
+    [k: string]: unknown;
+}
+declare function mapExternalIdentity(raw: ExternalRawIdentity): Identity;
+
+interface ExternalExchangeOptions {
+    exchangeUrl: string;
+    secret: string;
+    provider: string;
+    timeoutMs?: number;
+    /** 自定义外部响应 → 身份映射（缺省 mapExternalIdentity） */
+    mapIdentity?: (raw: ExternalRawIdentity) => Identity;
+    /** 外部已签 JWT 验签器（配置 AUTH_EXTERNAL_JWT_PUBLIC_KEY 时由 runtime 装配）；解出 payload 后提取 sub */
+    verifyJwt?: (jwt: string) => Promise<{
+        sub: string;
+        displayName?: string;
+        avatar?: string;
+    }>;
+}
+declare class ExternalIdentityExchange implements IdentityExchange {
+    private readonly opts;
+    readonly provider: string;
+    constructor(opts: ExternalExchangeOptions);
+    exchangeByCode({ code, platform }: ExchangeRequest): Promise<ExchangeResult>;
+    private postOnce;
+    /**
+     * 重试语义（评审 P0-1 修复）：HTTP 4xx 不重试（外部业务拒绝）；
+     * HTTP 5xx / 网络错误（fetch reject）/ 超时（AbortError）→ 单次重试。
+     * 换码幂等，重试安全；timestamp/sign 复用不影响（防重放窗口 5min >> 重试间隔）。
+     */
+    private postWithRetry;
+    /** 三态收敛：任意响应形态 → ExchangeResult */
+    private converge;
+    /** jwt 形态身份提取（三级，见文件头；sub 原样保留，不包前缀） */
+    private resolveJwtIdentity;
+    /** 无外部 id 时的 opaque 回退派生 id：opaque_<sha256>（opaque token 会话内稳定；轮换则身份漂移，外部应提供 identity） */
+    private deriveFallbackId;
+    private mapIdentity;
+}
+
+export { ACTION_GRANT_MAX_TTL_MS, type ActionCheck, type ActionContext, type ActionGateway, ActionGrantError, type ActionGrantOptions, type ActionGrantService, type ActionHandler, type ActionPolicy, type ActionResult, type AlipayAuthorizedUserProfile, type AlipayUserAuthorization, ApiRouteRegistry, type AttachCardActionTokensInput, type AuthConfig, AuthError, type AuthExchangeRegistry, type AuthMiddlewareOptions, type AuthMode, type AuthRuntime, type AuthRuntimeOptions, type AuthenticatedAuth, CONTEXT_ENVELOPE_MAX_BYTES, type CardActionRegistry, type CardEmit, CardEmitter, CardRegistry, type CardSnapshotStore, type CashierResult, type CircuitBreakerConfig, type ComponentStateStore, DomainAssemblyRegistry, EXTERNAL_SLOW_MS, EffectError, type EffectRuntime, type EffectRuntimeOptions, type EmitCardSpec, type EnvExpansionErrorInfo, type EnvironmentSecretProvider, type EventMap, type ExternalExchangeOptions, ExternalIdentityExchange, type ExternalRawIdentity, type FlowStateStore, type GrantRecord, type HandlerDefinition, HandlerRegistry, type HandlerResult, type IdempotencyStore, InMemoryCardSnapshotStore, InMemoryIdempotencyStore, InMemoryLruReplayStore, type InMemoryTransport, type InferToolArgs, type IntegrationsRaw, type IntegrationsRegistry, type IntegrationsRegistryOptions, type IssueOptions, KNOWLEDGE_PLACEHOLDER_DATASET_IDS, type KnowledgeBaseEntry, type KnowledgeClient, type KnowledgeClientOptions, KnowledgeError, type KnowledgeHit, type KnowledgeRegistry, LocalAlipayExchange, type LocalSkill, LocalWeappExchange, type LoginExchangeResolution, type ModuleActionDispatcher, type ModuleActionDispatcherOptions, ModuleActionError, type ModuleResourceResolver, type ModuleServerRegister, NOTICE_TEXT_MAX_LEN, type PaymentClient, type PaymentClientOptions, PaymentError, type PaymentStatus, type PreToolDecideInput, type PreToolDecision, type PreToolDef, type PreToolHistoryTurn, type PreToolLocationContext, PreToolRegistry, type PreToolRouting, type PreToolUserContext, type ProviderAuthStrategy, type ProviderAuthStrategyInput, ProviderError, type RegisteredModuleAction, type RegistryTool, type ReplayStore, type ResolvedAuth, type ResolvedResource, SKILL_LIMITS, STATIC_HEADERS_CREDENTIAL_TYPE, type ScopeSession, ScopeSessionError, type ScopeSessionRegistry, type ScopeSessionRegistryOptions, type SecretSource, type ServerContext, type ServerLogScope, type ServerLogger, type ServerModule, type ServerSpanPayload, type ServerSpanSink, type ServiceAdapterFactory, type ServiceAdapterInput, ServiceRegistry, SkillRegistry, type StoredEntry, TTS_DEFAULTS, TboxAppClient, TboxAsrClient, TboxConversationClient, TboxFeedbackClient, TboxTtsClient, TboxUploadClient, type TokenService, type TokenServiceOptions, ToolRegistry, type TransportFactory, type TransportFactoryOptions, type TtsVoiceConfig, type TypedBus, type WsAuthOptions, type WsAuthenticator, attachCardActionTokens, clearDevProviderFixtures, clearServices, collectIntentRoutes, createActionGateway, createActionGrantService, createAlipayUserAuthorization, createAnonymousIdentity, createAuthExchangeRegistry, createAuthMiddleware, createAuthRuntime, createAuthStrategyRegistry, createAuthenticatedTransportFactory, createEffectRuntime, createEnvironmentSecretProvider, createFixtureTransportFactory, createInMemoryStateStore, createInMemoryTransport, createIntegrationsRegistry, createKnowledgeClient, createModuleActionDispatcher, createModuleResourceResolver, createPaymentClient, createScopeSessionRegistry, createServerContext, createServerLogger, createTokenService, createTokenServiceFromConfig, createTypedBus, createWsAuthenticator, deriveActionGrantKey, expandEnvVars, formatAlipayTimestamp, getRequestContext, hasDevProviderFixture, hashPayload, hashStateRef, loadKnowledgeRegistry, mapExternalIdentity, normalizeContextEnvelope, readAuthConfig, recordCall, registerDevProviderFixture, registerServerModules, registerService, resolveBearerAuth, resolveService, runDevProviderFixture, runLogScope, runWithLogContext, setRequestContext, setServerSpanSink, signAlipayParams, staticHeadersStrategy, toNoticeText, toPem, truncateNoticeText, withCallLog };