@tansr/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -10928,6 +10928,41 @@ declare class UnavailableChannel implements PromptChannel {
     ask(_questions: readonly Question[], _signal: AbortSignal): Promise<Answer[]>;
 }
 
+/**
+ * T-D4 — Web 搜索后端接口(可插拔)。
+ *
+ * 命名为 WebSearchProvider(而非任务卡字面的 SearchProvider)以避开
+ * 《09》§8 前置项 4 预留给代码检索(T-D2 语义索引)的 SearchProvider
+ * 名字空间——kernel 顶层出口是 `export *`,同名必撞。偏差已记入任务报告。
+ */
+/** 单条搜索结果(结构化;渲染归表面层) */
+interface WebSearchResultItem {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** provider 收到的查询(maxResults 已被工具层夹紧到上限) */
+interface WebSearchQuery {
+    query: string;
+    maxResults: number;
+}
+interface WebSearchProviderContext {
+    /** 工具层合成的取消信号(ctx.signal + 工具内部超时) */
+    signal: AbortSignal;
+}
+/**
+ * 搜索后端契约:
+ * - 返回结构化结果数组(可多于 maxResults,工具层会截断);
+ * - 失败以 throw 表达(工具层捕获并转结构化错误);错误消息中**不得**
+ *   出现密钥原文(实现方自行脱敏,内置 HTTP provider 见 http-search-provider.ts);
+ * - 必须尊重 signal(至少把它传给底层 I/O)。
+ */
+interface WebSearchProvider {
+    /** 后端名(进 ToolResult.data 供渲染与审计;如 "http") */
+    readonly name: string;
+    search(query: WebSearchQuery, context: WebSearchProviderContext): Promise<WebSearchResultItem[]>;
+}
+
 /** 单条解析结果(node:dns lookup all:true 的消费子集) */
 interface ResolvedHostAddress {
     address: string;
@@ -15489,22 +15524,98 @@ type AppCapabilities = z.infer<typeof AppCapabilitiesSchema>;
 /** 平台缺省档(保守值;终值⏸候拍板⑥,doc/83 §八) */
 declare const DEFAULT_APP_CAPABILITIES: AppCapabilities;
 
+/** bundle 内单模型条目(SDK 消费子集) */
+interface AppBundleModel {
+    handle: string;
+    modelId: string;
+    displayName: string;
+    /**
+     * 原始厂商(模型呈现面二波,用户拍板 2026-08-30 ④;api bundle 加法键,
+     * 法人/品牌如 'Anthropic')。集成方模型切换器「厂商 → 系列」分组呈现的
+     * 一级维;旧 bundle 缺键/api 未校准 = null(呈现面回落平铺,恒不猜)。
+     */
+    manufacturer: string | null;
+    /** 模型族 = 系列维(api T-A13 列;两级分组二级维;缺键 = null) */
+    family: string | null;
+    /** 上游协议标识(信息位;消费恒走 twp,方言转换收敛在网关) */
+    protocol: string;
+    capabilities: Record<string, unknown>;
+    contextWindow: number | null;
+}
+/**
+ * 授权媒体模型条目(S-G1 媒体池化顺位取用,用户拍板 2026-08-30):`model` =
+ * canonical handle(/t1/imagegen、/t1/videogen 的 model 位可直用)。网关契约
+ * 恒不下发价格/成本/供应商内部信息,本形态即全量。
+ */
+interface AppBundleMediaModel {
+    model: string;
+    displayName: string;
+}
+/**
+ * 授权媒体模型集(bundle platformModels 段):序 = 平台收敛稳定序,**顺位第一
+ * 即工具/网关 model 缺省时的生效模型**;空数组 = 平台未配置(如实,恒不猜名)。
+ */
+interface AppBundlePlatformModels {
+    imageGen: AppBundleMediaModel[];
+    videoGen: AppBundleMediaModel[];
+}
+/** bundle-for-app 的 SDK 消费子集 */
+interface AppBundle {
+    models: AppBundleModel[];
+    aliases: Record<string, string>;
+    /** App 能力位(doc/89 契约 2;段缺席/坏形状 = 平台缺省档) */
+    capabilities: AppCapabilities;
+    /**
+     * 授权媒体模型集(S-G1):工具描述/装配 system 段的自取数据源——集成方
+     * 恒不手配模型名。旧 bundle 无段 = 双空集如实(段级容错同 capabilities
+     * 方向:缺席恒不臆造)。
+     */
+    platformModels: AppBundlePlatformModels;
+}
+/** 平台 provider 档名(与 cli TANSR_PROVIDER_ID 同值;registry 键与别名前缀) */
+declare const TANSR_PROVIDER_ID = "tansr";
+/**
+ * 令牌档 registry 的 ApiKey 占位环境变量(readApiKey 非空校验的哑值通道;
+ * 真实鉴权头由 createAppTokenFetch 包装覆写,令牌恒不进 registry env)。
+ */
+declare const APP_TOKEN_PLACEHOLDER_ENV = "TANSR_SDK_APP_TOKEN_TIER";
+/**
+ * bundle 载荷 → SDK 消费子集。顶层形状非法返回 null(调用方结构化报错);
+ * 条目级损坏逐条跳过。capabilities 段严格校验,失败回落平台缺省档
+ * (fail-closed 方向:缺省档保守)。platformModels 段(S-G1)加法解析:
+ * 段缺席(旧 api)/坏形状 = 双空集如实——媒体工具据此如实注明未配置,
+ * 恒不猜模型名;**序恒保持下发序**(顺位第一即缺省)。
+ */
+declare function parseAppBundle(raw: unknown): AppBundle | null;
+/**
+ * bundle → 令牌档 RegistryConfig:单一 tansr 档(twp/1,占位鉴权变量)+
+ * 别名表(目录裸名自动别名最低层,显式 aliases 压过)。恒零本地配置 IO。
+ */
+declare function appBundleRegistryConfig(bundle: AppBundle, baseUrl: string): RegistryConfig;
+
 /** 环2 内置工具词表(与 AppCapabilities.tools 的工具位同名,doc/84 §4.1) */
 type BuiltinToolName = 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'list' | 'shell' | 'webFetch' | 'webSearch' | 'http' | 'todoWrite' | 'askUser';
-/** 环3 平台能力词表(与 AppCapabilities.platform 同名) */
-type PlatformCapabilityName = 'imageGen' | 'videoGen' | 'webSearch';
+/**
+ * 环3 平台能力词表(与 AppCapabilities.platform 同名;webSearch 自 S-WS2 收编
+ * 进环2 builtin——位 platform.webSearch 仍在能力契约,但装配入口移位)。
+ */
+type PlatformCapabilityName = 'imageGen' | 'videoGen';
 /** 三环工具入口(CreateSessionOptions.tools / ManagedQueryOptions.tools) */
 interface SdkToolsOptions {
     /**
      * 环2 内置工具选择(词表:read/write/edit/glob/grep/list/shell/webFetch/
      * webSearch/http/todoWrite/askUser)。缺席 = 装配能力位放行的全部内置
      * 工具;空数组 = 零内置(纯自定义工具场景)。显式列出位关工具报可读错。
+     * webSearch 双门(S-WS2):除工具位外还需令牌档材料 + platform.webSearch 位
+     * (后端恒平台通道,SDK 恒不 BYO)——缺席选择时通道不备静默不装,显式选择
+     * 即 fail-fast 分因可读错。
      */
     builtin?: readonly string[];
     /**
-     * 环3 平台能力选择(词表:imageGen/videoGen/webSearch)。位关恒 fail-fast;
-     * 位开即装配平台工具客户端(ImageGen/VideoGen/PlatformWebSearch,材料 =
-     * 令牌档 platformContext,托管/注入档选择即可读错)。
+     * 环3 平台能力选择(词表:imageGen/videoGen)。位关恒 fail-fast;位开即
+     * 装配平台工具客户端(ImageGen/VideoGen,材料 = 令牌档 platformContext,
+     * 托管/注入档选择即可读错)。webSearch 已收编进 tools.builtin(S-WS2),
+     * 此处显式列出报迁移指引。
      */
     platform?: readonly string[];
     /** 环1 自定义工具(defineTool 产物;kernel Tool 形态直给亦可) */
@@ -15520,6 +15631,13 @@ interface PlatformToolContext {
     token: string;
     /** fetch 注入缝(测试桩网关;缺省全局 fetch) */
     fetchImpl?: typeof fetch;
+    /**
+     * bundle 授权媒体模型集(S-G1 媒体池化顺位取用):令牌档装配自
+     * assemblePlatformModel 随取随注——ImageGen/VideoGen 工具描述自列授权集
+     * (顺位第一 = model 缺省生效模型),集成方零手配。缺席(注入档测试直构
+     * 等)= 工具描述按未知集处理(仍可显式点名)。
+     */
+    platformModels?: AppBundlePlatformModels;
 }
 interface BuildSdkToolSetOptions {
     /** 三环工具入口;缺席 = 只装能力位放行的内置工具 */
@@ -15782,6 +15900,85 @@ declare function accumulateUsage(total: IRUsage | undefined, next: IRUsage): IRU
  */
 declare function query(options: QueryOptions): AsyncGenerator<KernelEvent, QueryResult, undefined>;
 
+/**
+ * doc/91 会话管理实施批 — SessionStore 可注入存储接口(拍板③/⑦)。
+ *
+ * 定位:SDK 会话存储的**唯一承诺面**(拍板⑦:kernel journal 原语恒不经
+ * SDK 出口导出,FileSessionStore 只作内部消费)。「存哪」被本接口抽象掉——
+ * 本地文件(createFileSessionStore)、开发者自建 DB、平台托管(二期
+ * createPlatformSessionStore,候独立拍板)三态同形,createSession 的
+ * resume/store 双字段(拍板③)恒不随存储后端变化。
+ *
+ * 概念收敛(doc/91 §3.1):对外「会话」= AgentSession 逻辑会话,一个
+ * sessionId 一段历史;存储内部的卷/纪元轮换是实现细节,list 面恒按逻辑
+ * 会话呈现。
+ */
+
+/** 会话存储登记行(元数据半边;内容经 get 另取,list 恒不携内容) */
+interface SessionRecordMeta {
+    /** 逻辑会话 id(= AgentSession.sessionId;缺省 UUID 形制,可显式供给) */
+    sessionId: string;
+    /** ISO-8601 创建时间 */
+    createdAt: string;
+    /** ISO-8601 最近提交时间(list 排序锚) */
+    updatedAt: string;
+    /** 会话标题(缺省 = 首条用户输入截断;可显式供给) */
+    title?: string;
+    /**
+     * 平台会话 id(ULID 26 位 Crockford;doc/91 拍板⑤):令牌档 createSession
+     * per-AgentSession 铸造并经 twp meta.sessionId 出线,ULID↔内核 UUID 映射
+     * 落在此键——平台侧会话行(归因/续租/亲和)与本地记录互认的桥。
+     */
+    platformSessionId?: string;
+    /** 开发者自留元数据域(SDK 恒不消费其内容) */
+    meta?: Record<string, unknown>;
+}
+/** create 登记参数(sessionId 缺省由 store 铸造 UUID) */
+interface SessionStoreCreateInit {
+    sessionId?: string;
+    title?: string;
+    /** 平台会话 ULID(令牌档装配注入;重复登记时以新值对账更新) */
+    platformSessionId?: string;
+    meta?: Record<string, unknown>;
+}
+/** commit 附带信息(与 CreateSessionOptions.onHistoryCommit 的 meta 同形) */
+interface SessionStoreCommitMeta {
+    /**
+     * true = 历史前缀被就地改写(session.compacted 压缩折叠 /
+     * session.microcompacted 存根化),已存内容不再与之对齐——实现方不得按
+     * 长度增量追加,须整卷轮换(demo persistence 先例,doc/91 §3.3)。
+     */
+    readonly rewritten: boolean;
+}
+/** get 终值(meta + 完整历史;resume 径另过配对治理,见 session.ts) */
+interface SessionRecord {
+    meta: SessionRecordMeta;
+    messages: IRMessage[];
+}
+/**
+ * 会话存储接口(拍板③冻结形态)。实现纪律:
+ * - commit 的 rewritten=true 须整卷轮换(语义见 SessionStoreCommitMeta);
+ * - 存储损坏恒结构化报错(throw),恒不静默返回残缺历史(doc/88 对抗式
+ *   验收:改坏存储文件须报错不静默);
+ * - list 恒不携消息内容(枚举是元数据面);
+ * - create 幂等(同 sessionId 重复登记返回既有记录,platformSessionId
+ *   以新值对账更新——resume 后的新 AgentSession 铸新平台 ULID 经此落位)。
+ */
+interface SessionStore {
+    /** 建会话(登记 meta;id 由 store 铸造或调用方供给;幂等) */
+    create(init: SessionStoreCreateInit): Promise<SessionRecordMeta>;
+    /** 取单会话(meta + 完整历史;不存在返回 null;损坏结构化 throw) */
+    get(sessionId: string): Promise<SessionRecord | null>;
+    /** 列会话(按 updatedAt 倒序;恒无内容) */
+    list(filter?: {
+        limit?: number;
+    }): Promise<SessionRecordMeta[]>;
+    /** 轮末提交(对接 onHistoryCommit;rewritten=true 须整卷轮换) */
+    commit(sessionId: string, history: readonly IRMessage[], meta: SessionStoreCommitMeta): Promise<void>;
+    /** 删除/归档(FileSessionStore = 目录删除;平台实现 = 归档语义) */
+    delete(sessionId: string): Promise<void>;
+}
+
 interface CreateSessionOptions {
     /**
      * 模型档(三档判定):
@@ -15867,6 +16064,26 @@ interface CreateSessionOptions {
      * console.warn(错误不静默消失)。
      */
     onHistoryCommit?: (history: readonly IRMessage[], meta: HistoryCommitMeta) => void | Promise<void>;
+    /**
+     * 一等恢复:自 store 取回历史与 meta 预载(与 initialMessages 互斥;
+     * sessionId 同给时必须与 resume.sessionId 一致)。resume 径内置配对治理
+     * (sessions/pairing.ts,拍板④):断尾 tool_call 补 isError 占位、孤儿
+     * tool_result 截断到干净边界——kernel 对 initialMessages 原样收不校验,
+     * 治理保证 wire 恒不 400。目标不存在抛 TansrSdkError('session_not_found');
+     * 存储损坏由 store.get 结构化上抛(恒不静默)。
+     */
+    resume?: {
+        sessionId: string;
+        store: SessionStore;
+    };
+    /**
+     * 在场时自动接管会话登记(store.create,幂等;令牌档的平台会话 ULID
+     * 映射随登记落 SessionRecordMeta,拍板⑤)与每轮落卷(store.commit;
+     * store 先行、onHistoryCommit 回调后行,失败面同 sdk.persistence 吞错
+     * 纪律)。与 resume 正交:续存一个恢复的会话把同一 store 同时传两处。
+     * 缺席 = 纯内存零变化(SDK 恒不引入任何隐式落盘)。
+     */
+    store?: SessionStore;
 }
 /** onHistoryCommit 附带信息(落盘方决定增量追加还是整卷轮换) */
 interface HistoryCommitMeta {
@@ -15958,6 +16175,16 @@ declare class AgentSession {
  */
 declare function createSession(options?: CreateSessionOptions): Promise<AgentSession>;
 
+interface CreateFileSessionStoreOptions {
+    /** 存储根目录(显式传入,恒不隐式扫用户目录;Electron 场景传 userData) */
+    dir: string;
+}
+/**
+ * 缺省文件实现工厂。目录布局(kernel journal 原语同款):
+ *   <dir>/sessions/<sessionId>/{journal.jsonl, meta.json, lock, attachments/}
+ */
+declare function createFileSessionStore(options: CreateFileSessionStoreOptions): SessionStore;
+
 /**
  * T-E8 — SDK 结构化错误。
  *
@@ -15975,7 +16202,11 @@ type SdkErrorCode =
 /** App 能力位关闭而被显式选择(S-B3;消息含控制台修复指引) */
  | 'capability_disabled'
 /** 会话已关闭后仍调用会改变状态的方法 */
- | 'session_closed';
+ | 'session_closed'
+/** resume 目标会话在 store 中不存在(doc/91 拍板③) */
+ | 'session_not_found'
+/** 会话存储损坏(中段损坏/哈希链断裂/坏 payload;doc/88 对抗锚:恒不静默) */
+ | 'session_store_corrupted';
 declare class TansrSdkError extends Error {
     readonly code: SdkErrorCode;
     constructor(code: SdkErrorCode, message: string, options?: {
@@ -16155,6 +16386,25 @@ declare function appendUserMessage(state: SessionViewReducerState, text: string)
  */
 declare function markSourceFailure(state: SessionViewReducerState, error: unknown): SessionViewReducerState;
 
+/**
+ * viewStateFromHistory — L2/L3 重建入口(doc/98 §五恢复链步骤④;doc/97
+ * 卡 A3-1 的 TS 半边,与 tansr-android :core 同名 Kotlin 实现逐语义对齐,
+ * 双端金样卷(test/view-golden)锁一致性,重录恒双仓同笔)。
+ *
+ * 语义:治理后历史快照(IRMessage[],pairing 已保证配对完整)→ 定稿消息
+ * 投影(无流式簿记):
+ * - text/thinking 空文本不建 part(与 reducer「空块定稿即删」同律);
+ * - tool_call 与 tool_result 按 callId 全卷配对(后写者胜):有回执按
+ *   isError 落 completed/failed,resultText = 回执 text 项拼接(空则缺席);
+ *   无回执(断尾)落 aborted;
+ * - 纯 tool_result 消息不落 user 气泡(回执是协议载体不是用户话语);
+ *   tool_result/opaque/image 与未知块型恒不建 part,空消息整条跳过;
+ * - 消息 id 单调续接(msg-1…),internal.nextMessageSeq 随之推进——重建后
+ *   新增消息恒不撞 id;其余内部簿记与视图字段取初始态(status='idle')。
+ */
+
+declare function viewStateFromHistory(messages: readonly IRMessage[]): SessionViewReducerState;
+
 /**
  * S-B7 — 事件泵(view 内部共享;session-view 与 narrator 同用)。
  *
@@ -16233,6 +16483,13 @@ interface AssemblePlatformModelOptions {
     fetchImpl?: typeof fetch;
     /** fallback 链最终命中通报(session 装配合成 cost.provider.switched) */
     onProviderSelected?: (selection: FallbackSelection) => void;
+    /**
+     * doc/91 拍板⑤ — twp meta.sessionId 动态供给(平台会话 id,ULID 形制;
+     * 经 ProviderRegistry twp 选项缝透传,providers 零改动)。createSession
+     * 令牌档 per-AgentSession 铸造一枚注入;缺席 = meta.sessionId 如实不携带
+     * (归账兜底在认证头,批ι 前语义),query 单轮档现维持缺席。
+     */
+    sessionId?: () => string | undefined;
 }
 interface AssembledPlatformModel {
     client: ModelClient;
@@ -16243,6 +16500,11 @@ interface AssembledPlatformModel {
     registry: ProviderRegistry;
     /** bundle capabilities 段(S-B3 裁剪的事实源;缺席时为平台缺省档) */
     capabilities: AppCapabilities;
+    /**
+     * bundle 授权媒体模型集(S-G1;初始化即取,媒体工具装配自取的数据源——
+     * 集成方零手配)。旧 api 无段 = 双空集如实。
+     */
+    platformModels: AppBundlePlatformModels;
 }
 /**
  * 令牌头注入 fetch 包装:剥 AK/SK 双头与签名三头(值只是占位哑值,但
@@ -16278,22 +16540,22 @@ declare function assemblePlatformModel(options: AssemblePlatformModelOptions): P
 /** 生成张数 wire 帽(与网关 TwpImagegenRequestSchema 同值;超模型帽由网关再钳)。 */
 declare const IMAGEGEN_TOOL_MAX_N = 4;
 declare const ImageGenArgsSchema: z.ZodObject<{
-    model: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
     negativePrompt: z.ZodOptional<z.ZodString>;
     size: z.ZodOptional<z.ZodString>;
     n: z.ZodOptional<z.ZodNumber>;
     seed: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    model: string;
     prompt: string;
+    model?: string | undefined;
     size?: string | undefined;
     n?: number | undefined;
     negativePrompt?: string | undefined;
     seed?: number | undefined;
 }, {
-    model: string;
     prompt: string;
+    model?: string | undefined;
     size?: string | undefined;
     n?: number | undefined;
     negativePrompt?: string | undefined;
@@ -16317,6 +16579,13 @@ interface CreateImageGenToolOptions {
     token: string;
     /** fetch 注入缝(测试桩网关;缺省全局 fetch)。 */
     fetchImpl?: typeof fetch;
+    /**
+     * 授权图像模型集(S-G1;bundle platformModels.imageGen,装配循环自取):
+     * 工具描述自列(顺位第一 = model 缺省生效模型);空数组 = 平台未配置
+     * (描述如实注明,恒不猜名);缺席 = 集未知(注入档直构/旧径),描述回落
+     * 通用指引。
+     */
+    models?: readonly AppBundleMediaModel[];
 }
 /**
  * 环3 平台图像生成工具(kernel Tool 形态;name 'ImageGen' 沿 kernel PascalCase
@@ -16346,22 +16615,22 @@ declare function createImageGenTool(options: CreateImageGenToolOptions): Tool<Im
 /** 时长 wire 帽(秒;与网关 TwpVideogenRequestSchema 同值;超模型帽由网关再钳)。 */
 declare const VIDEOGEN_TOOL_MAX_DURATION = 30;
 declare const VideoGenArgsSchema: z.ZodObject<{
-    model: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
     negativePrompt: z.ZodOptional<z.ZodString>;
     duration: z.ZodOptional<z.ZodNumber>;
     ratio: z.ZodOptional<z.ZodString>;
     seed: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    model: string;
     prompt: string;
+    model?: string | undefined;
     duration?: number | undefined;
     negativePrompt?: string | undefined;
     seed?: number | undefined;
     ratio?: string | undefined;
 }, {
-    model: string;
     prompt: string;
+    model?: string | undefined;
     duration?: number | undefined;
     negativePrompt?: string | undefined;
     seed?: number | undefined;
@@ -16387,6 +16656,13 @@ interface CreateVideoGenToolOptions {
     token: string;
     /** fetch 注入缝(测试桩网关;缺省全局 fetch)。 */
     fetchImpl?: typeof fetch;
+    /**
+     * 授权视频模型集(S-G1;bundle platformModels.videoGen,装配循环自取):
+     * 工具描述自列(顺位第一 = model 缺省生效模型);空数组 = 平台未配置
+     * (描述如实注明,恒不猜名);缺席 = 集未知(注入档直构/旧径),描述回落
+     * 通用指引。
+     */
+    models?: readonly AppBundleMediaModel[];
 }
 /**
  * 环3 平台视频生成工具(kernel Tool 形态;name 'VideoGen' 沿 kernel PascalCase
@@ -16396,60 +16672,30 @@ interface CreateVideoGenToolOptions {
 declare function createVideoGenTool(options: CreateVideoGenToolOptions): Tool<VideoGenArgs>;
 
 /**
- * S-WS — WebSearch 环3 平台工具客户端(imagegen/videogen-tool.ts 同构镜像;
- * doc/84 §4.2 平台托管能力;用户拍板 2026-08-30「webSearch 补打通」)。
+ * S-WS2 — 平台联网搜索后端(kernel WebSearchProvider 实现;用户拍板 2026-08-31
+ * 「SDK 恒不暴露 BYO 档,移除相关逻辑,内核态 WebSearch 直接走平台」)。
  *
- * 环3 语义:执行不在终端本地——工具 execute 经令牌档 fetch 打平台网关
- * POST {baseUrl}/t1/websearch(鉴权头 x-tansr-app-token),平台代调搜索
- * 供应商池(加权选池 + 一次故障转移),**按次计量计费归 App**(pricePerCall;
- * 开发者对终端如何转售自主,计量计费分离)。
+ * 形态注记(取代 S-WS 的环3 独立工具 'PlatformWebSearch'):SDK 里联网搜索恒
+ * 一件工具 = kernel 环2 'WebSearch',后端恒为本 provider(平台通道)。BYO
+ * (TANSR_WEBSEARCH_ENDPOINT/KEY 环境变量后端)在 SDK 装配面恒不存在——终端
+ * 持搜索商密钥即 appkey 防盗模型要消灭的反模式;可解释可审计面恒在平台
+ * (逐笔 usage_events、预扣结算闭环、endUserId 归因、失败零计费)。
  *
- * wire 契约(api 仓 TwpWebsearchRequest/Response,doc/36 §3.2):请求
- * {query, max_results?} 为 snake_case——与 CLI 内核 HTTP 搜索后端字节同构的
- * 既有特例(imagegen/videogen 的 camelCase 系 twp 核心纪律,本面迁就既有
- * 字节);响应 {results:[{title,url,snippet}]}(供应商方言已在网关归一)。
+ * wire 契约(api TwpWebsearchRequest/Response,doc/36 §3.2):POST /t1/websearch
+ * {query, max_results} snake_case;响应 {results:[{title,url,snippet}]}
+ * (供应商方言已在网关归一;供应商身份恒匿名,doc/50 采购红线)。按次计量
+ * 计费归 App(pricePerCall;开发者对终端如何转售自主,计量计费分离)。
  *
- * 命名注记:kernel 环2 内置搜索工具已占名 'WebSearch'(终端本地 HTTP 后端,
- * tools.webSearch 位),本工具名取 'PlatformWebSearch' 与位名 platform.webSearch
- * 对齐——双位同开双选时两环并存,恒不注册表撞名。
- *
- * 装配面:tools.platform: ['webSearch'] 且 bundle 能力位 platform.webSearch=true
- * 时由 buildSdkToolSet 装配(位关 fail-fast 可读错);材料(baseUrl/token)
- * 来自会话令牌档——托管/注入档选择本工具恒 fail-fast 指引改用令牌档。
- *
- * 错误纪律(imagegen 同款):恒不 throw——网关错误信封归一为 isError 结构化
- * 结果(携错误码与修复指引),智能体可自纠不炸查询环;令牌本体只活在闭包
- * (INV-10 密钥纪律)。数据主权注记:查询文本平台侧恒不落日志不落库(网关
- * 红线),SDK 侧同样恒不打印。
+ * 错误纪律:WebSearchProvider 契约以 throw 表达失败——kernel search-tool 捕获
+ * 转 provider_error 结构化错误(不炸查询环),错误消息携网关错误码与修复指引;
+ * 令牌只活在闭包(INV-10),查询文本平台侧恒不落日志不落库(网关红线),SDK
+ * 侧同样恒不打印。
  */
 
-/** 结果数 wire 帽(与网关 TwpWebsearchRequestSchema 同值;供应商侧上限再截)。 */
-declare const WEBSEARCH_TOOL_MAX_RESULTS = 20;
-declare const WebSearchArgsSchema: z.ZodObject<{
-    query: z.ZodEffects<z.ZodString, string, string>;
-    max_results: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    max_results?: number | undefined;
-}, {
-    query: string;
-    max_results?: number | undefined;
-}>;
-type WebSearchArgs = z.infer<typeof WebSearchArgsSchema>;
-/** 表面层渲染用结构化数据(ToolResult.data;错误时携错误码)。 */
-interface WebSearchData {
-    query: string;
-    results: Array<{
-        title: string;
-        url: string;
-        snippet: string;
-    }>;
-    resultCount: number;
-    /** 网关错误码(如 forbidden/websearch_not_configured/websearch_quota_exceeded;成功缺席)。 */
-    errorCode?: string;
-}
-interface CreateWebSearchToolOptions {
-    /** 平台 API 基址(令牌档会话档;/t1 前缀由本工具追加)。 */
+/** 后端名(进 kernel WebSearch 的 ToolResult.data.provider,供渲染与审计)。 */
+declare const PLATFORM_SEARCH_PROVIDER_NAME = "tansr-platform";
+interface CreatePlatformSearchProviderOptions {
+    /** 平台 API 基址(令牌档会话档;/t1 前缀由本 provider 追加)。 */
     baseUrl: string;
     /** app_user 短期令牌(只活在本闭包,恒不进工具定义/日志)。 */
     token: string;
@@ -16457,47 +16703,12 @@ interface CreateWebSearchToolOptions {
     fetchImpl?: typeof fetch;
 }
 /**
- * 环3 平台联网搜索工具(kernel Tool 形态;name 'PlatformWebSearch',命名注记
- * 见文件头)。计费副作用真实存在(按次扣 App 余额)——恒不声明只读/并发安全
- * (ImageGen/VideoGen 同律保守档;权限规则可按名 gate)。
+ * 平台联网搜索 provider(kernel WebSearchProvider 契约):经令牌档 fetch 打
+ * 平台网关,平台代调搜索供应商池(加权选池 + 故障转移),按次计费归 App。
+ * 结果条目做最小映射(title/url 非字符串剔除,snippet 缺席补空串);上限
+ * 截断、URL 卫生、去重恒由 kernel search-tool 层收口(不信任 provider 同律)。
  */
-declare function createWebSearchTool(options: CreateWebSearchToolOptions): Tool<WebSearchArgs>;
-
-/** bundle 内单模型条目(SDK 消费子集) */
-interface AppBundleModel {
-    handle: string;
-    modelId: string;
-    displayName: string;
-    /** 上游协议标识(信息位;消费恒走 twp,方言转换收敛在网关) */
-    protocol: string;
-    capabilities: Record<string, unknown>;
-    contextWindow: number | null;
-}
-/** bundle-for-app 的 SDK 消费子集 */
-interface AppBundle {
-    models: AppBundleModel[];
-    aliases: Record<string, string>;
-    /** App 能力位(doc/89 契约 2;段缺席/坏形状 = 平台缺省档) */
-    capabilities: AppCapabilities;
-}
-/** 平台 provider 档名(与 cli TANSR_PROVIDER_ID 同值;registry 键与别名前缀) */
-declare const TANSR_PROVIDER_ID = "tansr";
-/**
- * 令牌档 registry 的 ApiKey 占位环境变量(readApiKey 非空校验的哑值通道;
- * 真实鉴权头由 createAppTokenFetch 包装覆写,令牌恒不进 registry env)。
- */
-declare const APP_TOKEN_PLACEHOLDER_ENV = "TANSR_SDK_APP_TOKEN_TIER";
-/**
- * bundle 载荷 → SDK 消费子集。顶层形状非法返回 null(调用方结构化报错);
- * 条目级损坏逐条跳过。capabilities 段严格校验,失败回落平台缺省档
- * (fail-closed 方向:缺省档保守)。
- */
-declare function parseAppBundle(raw: unknown): AppBundle | null;
-/**
- * bundle → 令牌档 RegistryConfig:单一 tansr 档(twp/1,占位鉴权变量)+
- * 别名表(目录裸名自动别名最低层,显式 aliases 压过)。恒零本地配置 IO。
- */
-declare function appBundleRegistryConfig(bundle: AppBundle, baseUrl: string): RegistryConfig;
+declare function createPlatformSearchProvider(options: CreatePlatformSearchProviderOptions): WebSearchProvider;
 
 interface CreateSdkPermissionGateOptions {
     /** 权限规则的路径锚定目录;必须与 executor 的 cwd 一致 */
@@ -16527,5 +16738,5 @@ declare function attachSdkTaskTool(toolset: SdkToolsetRef, config: AttachSdkTask
  */
 declare function subagentModelResolverOf(registry: ProviderRegistry | null): SubagentModelResolver | undefined;
 
-export { APP_SDK_CONTRACT_VERSION, APP_TOKEN_PLACEHOLDER_ENV, AgentSession, AppCapabilitiesSchema, AppTokenRequestSchema, AppTokenResponseSchema, DEFAULT_APP_CAPABILITIES, DEFAULT_MAX_TOKENS, DEFAULT_MAX_TURNS, EndUserIdSchema, HEADER_APP_TOKEN, IMAGEGEN_TOOL_MAX_N, ImageGenArgsSchema, McpHost, OUTPUT_TAIL_MAX_CHARS, QueueChannel, SequentialToolExecutor, TANSR_PROVIDER_ID, TOOL_GUIDE_LABEL, TansrSdkError, UnavailableChannel, VIDEOGEN_TOOL_MAX_DURATION, VideoGenArgsSchema, WEBSEARCH_TOOL_MAX_RESULTS, WebSearchArgsSchema, accumulateUsage, appBundleRegistryConfig, appendUserMessage, assembleManagedModel, assemblePlatformModel, assembleSdkSkills, assembleTooling, attachSdkMcp, attachSdkTaskTool, buildClientFromRegistry, buildSdkToolSet, buildToolGuideSegment, createAppTokenFetch, createImageGenTool, createMcpHost, createNarrator, createSdkPermissionGate, createSession, createSessionView, createVideoGenTool, createWebSearchTool, defineSkill, defineTool, initialSessionViewState, markSourceFailure, parseAppBundle, providerSwitchedBody, query, reduceSessionView, resolveBuiltinSelection, resolveInitialMessages, resolvePlatformSelection, runAgent, subagentModelResolverOf, toToolDef };
-export type { ActiveToolStatus, Answer, AppBundle, AppBundleModel, AppCapabilities, AppTokenRequest, AppTokenResponse, AskUserCallback, AssembleManagedModelOptions, AssemblePlatformModelOptions, AssembleToolingOptions, AssembledManagedModel, AssembledPlatformModel, AssembledSkills, AssembledTooling, AttachSdkTaskToolConfig, BuildSdkToolSetOptions, BuiltinToolName, Capability, CompactNowOptions, CompactNowResult, ConfigDiagnostic, CreateImageGenToolOptions, CreateSdkPermissionGateOptions, CreateSessionOptions, CreateVideoGenToolOptions, CreateWebSearchToolOptions, DecisionSource, DefineSkillOptions, DefineToolOptions, DefinedSkill, DefinedTool, ErrorView, EventBody, EventEnvelope, GateDecision, HookOutcomeStatus, IRBlock, IRErrorKind, IRMessage, IRRequest, IRRole, IRStreamEvent, IRSystemSegment, IRToolContent, IRToolDef, IRToolResultBlock, IRUsage, ImageGenArgs, ImageGenData, Integrity, JournalKind, JournalRecord, KernelEvent, KernelState, LoadConfigOptions, LoadedConfig, ManagedQueryOptions, McpClientEvent, McpConnectFactory, McpConnection, McpEventObserver, McpHostOptions, McpServerConfig, McpSessionOption, ModelCallOptions, ModelClient, Narrator, NarratorOptions, NarratorVerbosity, PermissionDecision, PermissionGate, PermissionMode, PermissionOptions, PermissionRules, PlatformCapabilityName, PlatformToolContext, Pricing, PromptCachingMode, PromptChannel, ProposedToolCall, ProtocolKind, ProviderProfile, QueryCompactionOptions, QueryCounters, QueryHandle, QueryOptions, QueryResult, Question, QuestionOption, ResolvedModel, RunAgentOptions, SdkErrorCode, SdkSkillsOptions, SdkToolSet, SdkToolsOptions, SdkToolsetRef, SequentialToolHandler, SequentialToolResult, SessionEventSource, SessionView, SessionViewReducerState, SessionViewSource, SessionViewState, SessionViewStatus, SetModelBinding, SkillsFileSystem, TansrConfig, TerminalReason, TodoView, Tool, ToolCallPartStatus, ToolCallView, ToolContext, ToolErrorType, ToolExecutionContext, ToolExecutionOutcome, ToolExecutor, ToolExecutorYield, ToolParameterSpec, ToolResult, ToolResultContent, UIMessage, UIMessagePart, UITextPart, UIThinkingPart, UIToolCallPart, UsageView, VideoGenArgs, VideoGenData, Visibility, WebSearchArgs, WebSearchData };
+export { APP_SDK_CONTRACT_VERSION, APP_TOKEN_PLACEHOLDER_ENV, AgentSession, AppCapabilitiesSchema, AppTokenRequestSchema, AppTokenResponseSchema, DEFAULT_APP_CAPABILITIES, DEFAULT_MAX_TOKENS, DEFAULT_MAX_TURNS, EndUserIdSchema, HEADER_APP_TOKEN, IMAGEGEN_TOOL_MAX_N, ImageGenArgsSchema, McpHost, OUTPUT_TAIL_MAX_CHARS, PLATFORM_SEARCH_PROVIDER_NAME, QueueChannel, SequentialToolExecutor, TANSR_PROVIDER_ID, TOOL_GUIDE_LABEL, TansrSdkError, UnavailableChannel, VIDEOGEN_TOOL_MAX_DURATION, VideoGenArgsSchema, accumulateUsage, appBundleRegistryConfig, appendUserMessage, assembleManagedModel, assemblePlatformModel, assembleSdkSkills, assembleTooling, attachSdkMcp, attachSdkTaskTool, buildClientFromRegistry, buildSdkToolSet, buildToolGuideSegment, createAppTokenFetch, createFileSessionStore, createImageGenTool, createMcpHost, createNarrator, createPlatformSearchProvider, createSdkPermissionGate, createSession, createSessionView, createVideoGenTool, defineSkill, defineTool, initialSessionViewState, markSourceFailure, parseAppBundle, providerSwitchedBody, query, reduceSessionView, resolveBuiltinSelection, resolveInitialMessages, resolvePlatformSelection, runAgent, subagentModelResolverOf, toToolDef, viewStateFromHistory };
+export type { ActiveToolStatus, Answer, AppBundle, AppBundleMediaModel, AppBundleModel, AppBundlePlatformModels, AppCapabilities, AppTokenRequest, AppTokenResponse, AskUserCallback, AssembleManagedModelOptions, AssemblePlatformModelOptions, AssembleToolingOptions, AssembledManagedModel, AssembledPlatformModel, AssembledSkills, AssembledTooling, AttachSdkTaskToolConfig, BuildSdkToolSetOptions, BuiltinToolName, Capability, CompactNowOptions, CompactNowResult, ConfigDiagnostic, CreateFileSessionStoreOptions, CreateImageGenToolOptions, CreatePlatformSearchProviderOptions, CreateSdkPermissionGateOptions, CreateSessionOptions, CreateVideoGenToolOptions, DecisionSource, DefineSkillOptions, DefineToolOptions, DefinedSkill, DefinedTool, ErrorView, EventBody, EventEnvelope, GateDecision, HistoryCommitMeta, HookOutcomeStatus, IRBlock, IRErrorKind, IRMessage, IRRequest, IRRole, IRStreamEvent, IRSystemSegment, IRToolContent, IRToolDef, IRToolResultBlock, IRUsage, ImageGenArgs, ImageGenData, Integrity, JournalKind, JournalRecord, KernelEvent, KernelState, LoadConfigOptions, LoadedConfig, ManagedQueryOptions, McpClientEvent, McpConnectFactory, McpConnection, McpEventObserver, McpHostOptions, McpServerConfig, McpSessionOption, ModelCallOptions, ModelClient, Narrator, NarratorOptions, NarratorVerbosity, PermissionDecision, PermissionGate, PermissionMode, PermissionOptions, PermissionRules, PlatformCapabilityName, PlatformToolContext, Pricing, PromptCachingMode, PromptChannel, ProposedToolCall, ProtocolKind, ProviderProfile, QueryCompactionOptions, QueryCounters, QueryHandle, QueryOptions, QueryResult, Question, QuestionOption, ResolvedModel, RunAgentOptions, SdkErrorCode, SdkSkillsOptions, SdkToolSet, SdkToolsOptions, SdkToolsetRef, SequentialToolHandler, SequentialToolResult, SessionEventSource, SessionRecord, SessionRecordMeta, SessionStore, SessionStoreCommitMeta, SessionStoreCreateInit, SessionView, SessionViewReducerState, SessionViewSource, SessionViewState, SessionViewStatus, SetModelBinding, SkillsFileSystem, TansrConfig, TerminalReason, TodoView, Tool, ToolCallPartStatus, ToolCallView, ToolContext, ToolErrorType, ToolExecutionContext, ToolExecutionOutcome, ToolExecutor, ToolExecutorYield, ToolParameterSpec, ToolResult, ToolResultContent, UIMessage, UIMessagePart, UITextPart, UIThinkingPart, UIToolCallPart, UsageView, VideoGenArgs, VideoGenData, Visibility };