@tansr/sdk 0.7.2 → 0.8.0

package/dist/index.d.ts

@@ -15864,6 +15864,84 @@ interface AssembledTooling {
  */
 declare function assembleTooling(options: AssembleToolingOptions): Promise<AssembledTooling>;
 
+/**
+ * S-B1 — 平台令牌档装配:app_user 令牌 → bundle 拉取 → registry 轻装配。
+ *
+ * 三档并立(createSession/query 同判):
+ * - 令牌档:`{ token, baseUrl }`(本模块)——终端分发形态,令牌短时效
+ *   受限(doc/89 契约 1),能力位由 bundle 供给,**恒零本地配置 IO**;
+ * - 托管档:`model: string`(五层配置 BYOK,assembly.ts);
+ * - 注入档:`client + model 对象`(自带 ModelClient)。
+ *
+ * 令牌传输(对接方式定谳):TwpAdapter 是 AK/SK 双头 + 签名三头的自持
+ * 形态,不支持「替换鉴权头」的构造选项(defaultHeaders 只能追加,双头仍
+ * 出线)——故用 fetchImpl 注入缝包装(**不改 providers 包**):每次请求
+ * 剥双头与签名三头、注入契约头 x-tansr-app-token。registry env 只喂占位
+ * 哑值(APP_TOKEN_PLACEHOLDER_VALUE)满足装配期非空校验;令牌本体只活在
+ * fetch 包装闭包,恒不进 registry/adapter 构造参数(INV-10 密钥纪律同源)。
+ */
+
+/**
+ * 平台提示帧(TWP t.warn 同形;S-ARCH doc/109 代拍②):平台对非致命降级
+ * 的结构化告知(思考不可用/余额预警等),恒不代表请求失败。
+ */
+interface PlatformWarning {
+    code: string;
+    message: string;
+}
+/** 令牌档装配选项(createSession/query 的 token 档字段投影) */
+interface AssemblePlatformModelOptions {
+    /** app_user 短期令牌(开发者服务端经 POST /v1/app-tokens 换发) */
+    token: string;
+    /** 平台 API 基址(如 https://api.example.com;/t1 前缀由装配追加) */
+    baseUrl: string;
+    /** 模型别名(bundle aliases/目录 handle);缺省 'main' */
+    model?: string;
+    /** fetch 注入缝(bundle 拉取与 twp 交换共用;测试桩网关) */
+    fetchImpl?: typeof fetch;
+    /** fallback 链最终命中通报(session 装配合成 cost.provider.switched) */
+    onProviderSelected?: (selection: FallbackSelection) => void;
+    /**
+     * S-ARCH(doc/109 代拍②):平台 t.warn 提示帧旁路(thinking_unavailable_on_face
+     * /balance_low 等)。此前 SDK 面恒缺席 = 平台的结构化告知在最后一米静默
+     * 蒸发;经既有 registry twp 选项缝透传,providers 零改动。
+     */
+    onWarn?: (warn: PlatformWarning) => void;
+    /**
+     * doc/91 拍板⑤ — twp meta.sessionId 动态供给(平台会话 id,ULID 形制;
+     * 经 ProviderRegistry twp 选项缝透传,providers 零改动)。createSession
+     * 令牌档 per-AgentSession 铸造一枚注入;缺席 = meta.sessionId 如实不携带
+     * (归账兜底在认证头,批ι 前语义),query 单轮档现维持缺席。
+     */
+    sessionId?: () => string | undefined;
+}
+interface AssembledPlatformModel {
+    client: ModelClient;
+    model: ResolvedModel;
+    contextWindowTokens?: number;
+    maxOutputTokens?: number;
+    /** bundle 装配的 registry(setModel 别名热切换与 Task resolveModel 复用) */
+    registry: ProviderRegistry;
+    /** bundle capabilities 段(S-B3 裁剪的事实源;缺席时为平台缺省档) */
+    capabilities: AppCapabilities;
+    /**
+     * bundle 授权媒体模型集(S-G1;初始化即取,媒体工具装配自取的数据源——
+     * 集成方零手配)。旧 api 无段 = 双空集如实。
+     */
+    platformModels: AppBundlePlatformModels;
+}
+/**
+ * 令牌头注入 fetch 包装:剥 AK/SK 双头与签名三头(值只是占位哑值,但
+ * 恒不出线),注入 x-tansr-app-token。令牌只活在本闭包。
+ */
+declare function createAppTokenFetch(token: string, inner?: typeof fetch): typeof fetch;
+/**
+ * 令牌档一站式:拉 bundle(GET {baseUrl}/t1/config,令牌头鉴权)→ 解析
+ * models/aliases/capabilities → registry 轻装配 → 别名 client。装配失败
+ * 一律 TansrSdkError('assembly_failed') 携修复指引。
+ */
+declare function assemblePlatformModel(options: AssemblePlatformModelOptions): Promise<AssembledPlatformModel>;
+
 /** 托管/令牌档单轮选项(工具/权限缝与 CreateSessionOptions 同名同义) */
 interface ManagedQueryOptions {
     /** 模型别名(main/fast/reasoning/自定义)或 ref(provider/model);缺省 'main' */
@@ -15878,6 +15956,11 @@ interface ManagedQueryOptions {
     token?: string;
     /** 平台 API 基址(令牌档必填,如 https://api.example.com) */
     baseUrl?: string;
+    /**
+     * 平台提示帧承接(S-ARCH;语义同 CreateSessionOptions.onPlatformWarning):
+     * 缺席缺省 console.warn 每码一次,在场即全量接管。
+     */
+    onPlatformWarning?: (warning: PlatformWarning) => void;
     /** 项目层配置发现起点与工具 cwd;缺省 process.cwd() */
     cwd?: string;
     /** 环境变量注入缝;缺省 process.env */
@@ -16050,6 +16133,14 @@ interface CreateSessionOptions {
     token?: string;
     /** 平台 API 基址(令牌档必填,如 https://api.example.com) */
     baseUrl?: string;
+    /**
+     * S-ARCH(doc/109 代拍②)— 平台提示帧承接(仅令牌档产生;其余档恒不
+     * 触发)。平台以 t.warn 结构化告知非致命降级(如 thinking_unavailable_on_face
+     * :思考被请求而当前供应商面无从外露,回答照常仅无思考;balance_low:
+     * 余额预警)。缺席时缺省承接 = console.warn 每码一次(告知恒不静默蒸发);
+     * 提供回调即全量接管(不去重,原始帧逐一交付,呈现策略归开发者)。
+     */
+    onPlatformWarning?: (warning: PlatformWarning) => void;
     /** 项目层配置发现起点与工具 cwd;缺省 process.cwd() */
     cwd?: string;
     /** 环境变量注入缝;缺省 process.env */
@@ -16582,70 +16673,6 @@ interface Narrator {
 }
 declare function createNarrator(source: SessionViewSource, options: NarratorOptions): Narrator;
 
-/**
- * S-B1 — 平台令牌档装配:app_user 令牌 → bundle 拉取 → registry 轻装配。
- *
- * 三档并立(createSession/query 同判):
- * - 令牌档:`{ token, baseUrl }`(本模块)——终端分发形态,令牌短时效
- *   受限(doc/89 契约 1),能力位由 bundle 供给,**恒零本地配置 IO**;
- * - 托管档:`model: string`(五层配置 BYOK,assembly.ts);
- * - 注入档:`client + model 对象`(自带 ModelClient)。
- *
- * 令牌传输(对接方式定谳):TwpAdapter 是 AK/SK 双头 + 签名三头的自持
- * 形态,不支持「替换鉴权头」的构造选项(defaultHeaders 只能追加,双头仍
- * 出线)——故用 fetchImpl 注入缝包装(**不改 providers 包**):每次请求
- * 剥双头与签名三头、注入契约头 x-tansr-app-token。registry env 只喂占位
- * 哑值(APP_TOKEN_PLACEHOLDER_VALUE)满足装配期非空校验;令牌本体只活在
- * fetch 包装闭包,恒不进 registry/adapter 构造参数(INV-10 密钥纪律同源)。
- */
-
-/** 令牌档装配选项(createSession/query 的 token 档字段投影) */
-interface AssemblePlatformModelOptions {
-    /** app_user 短期令牌(开发者服务端经 POST /v1/app-tokens 换发) */
-    token: string;
-    /** 平台 API 基址(如 https://api.example.com;/t1 前缀由装配追加) */
-    baseUrl: string;
-    /** 模型别名(bundle aliases/目录 handle);缺省 'main' */
-    model?: string;
-    /** fetch 注入缝(bundle 拉取与 twp 交换共用;测试桩网关) */
-    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;
-    model: ResolvedModel;
-    contextWindowTokens?: number;
-    maxOutputTokens?: number;
-    /** bundle 装配的 registry(setModel 别名热切换与 Task resolveModel 复用) */
-    registry: ProviderRegistry;
-    /** bundle capabilities 段(S-B3 裁剪的事实源;缺席时为平台缺省档) */
-    capabilities: AppCapabilities;
-    /**
-     * bundle 授权媒体模型集(S-G1;初始化即取,媒体工具装配自取的数据源——
-     * 集成方零手配)。旧 api 无段 = 双空集如实。
-     */
-    platformModels: AppBundlePlatformModels;
-}
-/**
- * 令牌头注入 fetch 包装:剥 AK/SK 双头与签名三头(值只是占位哑值,但
- * 恒不出线),注入 x-tansr-app-token。令牌只活在本闭包。
- */
-declare function createAppTokenFetch(token: string, inner?: typeof fetch): typeof fetch;
-/**
- * 令牌档一站式:拉 bundle(GET {baseUrl}/t1/config,令牌头鉴权)→ 解析
- * models/aliases/capabilities → registry 轻装配 → 别名 client。装配失败
- * 一律 TansrSdkError('assembly_failed') 携修复指引。
- */
-declare function assemblePlatformModel(options: AssemblePlatformModelOptions): Promise<AssembledPlatformModel>;
-
 /**
  * S-E1 — ImageGen 环3 平台工具客户端(doc/84 §4.2 平台托管能力;用户拍板
  * 2026-08-29「开 imageGen」)。
@@ -16930,4 +16957,4 @@ 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, IMAGEGEN_TOOL_TIMEOUT_MS, ImageGenArgsSchema, McpHost, OUTPUT_TAIL_MAX_CHARS, PLATFORM_SEARCH_PROVIDER_NAME, QueueChannel, SequentialToolExecutor, TANSR_PROVIDER_ID, TOOL_GUIDE_LABEL, TansrSdkError, UnavailableChannel, VIDEOGEN_TOOL_MAX_DURATION, VIDEOGEN_TOOL_TIMEOUT_MS, 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, setSessionViewDelivery, stripThinkingParts, subagentModelResolverOf, toToolDef, viewStateFromHistory };
-export type { ActiveToolStatus, Answer, AppBundle, AppBundleImageModel, AppBundleMediaModel, AppBundleModel, AppBundlePlatformModels, AppBundleVideoModel, 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, DeliveryConfig, ErrorView, EventBody, EventEnvelope, GateDecision, HistoryCommitMeta, HookOutcomeStatus, IRBlock, IRErrorKind, IRMessage, IRRequest, IRRole, IRStreamEvent, IRSystemSegment, IRToolContent, IRToolDef, IRToolResultBlock, IRUsage, ImageGenArgs, ImageGenData, ImageModelConstraints, 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, SessionViewDeliveryOptions, SessionViewOptions, SessionViewReducerState, SessionViewSource, SessionViewState, SessionViewStatus, SetModelBinding, SkillsFileSystem, TansrConfig, TerminalReason, TextDeliveryMode, ThinkingDeliveryMode, TodoView, Tool, ToolCallPartStatus, ToolCallView, ToolContext, ToolErrorType, ToolExecutionContext, ToolExecutionOutcome, ToolExecutor, ToolExecutorYield, ToolParameterSpec, ToolResult, ToolResultContent, UIMessage, UIMessagePart, UITextPart, UIThinkingPart, UIToolCallPart, UsageView, VideoGenArgs, VideoGenData, VideoModelConstraints, Visibility };
+export type { ActiveToolStatus, Answer, AppBundle, AppBundleImageModel, AppBundleMediaModel, AppBundleModel, AppBundlePlatformModels, AppBundleVideoModel, 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, DeliveryConfig, ErrorView, EventBody, EventEnvelope, GateDecision, HistoryCommitMeta, HookOutcomeStatus, IRBlock, IRErrorKind, IRMessage, IRRequest, IRRole, IRStreamEvent, IRSystemSegment, IRToolContent, IRToolDef, IRToolResultBlock, IRUsage, ImageGenArgs, ImageGenData, ImageModelConstraints, 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, PlatformWarning, 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, SessionViewDeliveryOptions, SessionViewOptions, SessionViewReducerState, SessionViewSource, SessionViewState, SessionViewStatus, SetModelBinding, SkillsFileSystem, TansrConfig, TerminalReason, TextDeliveryMode, ThinkingDeliveryMode, TodoView, Tool, ToolCallPartStatus, ToolCallView, ToolContext, ToolErrorType, ToolExecutionContext, ToolExecutionOutcome, ToolExecutor, ToolExecutorYield, ToolParameterSpec, ToolResult, ToolResultContent, UIMessage, UIMessagePart, UITextPart, UIThinkingPart, UIToolCallPart, UsageView, VideoGenArgs, VideoGenData, VideoModelConstraints, Visibility };

package/dist/index.js

@@ -32025,6 +32025,15 @@ function appBundleRegistryConfig(bundle, baseUrl) {
 }
 
 // src/platform/client.ts
+function createPlatformWarningHandler(custom) {
+  if (custom !== void 0) return custom;
+  const warned = /* @__PURE__ */ new Set();
+  return (warning) => {
+    if (warned.has(warning.code)) return;
+    warned.add(warning.code);
+    console.warn(`[tansr-sdk] platform warning ${warning.code}: ${warning.message}`);
+  };
+}
 var STRIPPED_HEADERS = [
   TWP_KEY_ID_HEADER,
   TWP_KEY_HEADER,
@@ -32149,7 +32158,8 @@ async function assemblePlatformModel(options) {
     // S-TH3:features 能力串同缝供给(闭包定格;undefined = 门全关同现状)
     twp: {
       ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {},
-      features: () => features
+      features: () => features,
+      ...options.onWarn !== void 0 ? { onWarn: options.onWarn } : {}
     }
   });
   const built = buildClientFromRegistry(registry, options.model ?? "main", options.onProviderSelected);
@@ -32236,7 +32246,8 @@ async function* consumeManaged(options) {
       token: options.token,
       baseUrl: options.baseUrl,
       ...options.model !== void 0 ? { model: options.model } : {},
-      ...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {}
+      ...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {},
+      onWarn: createPlatformWarningHandler(options.onPlatformWarning)
     });
     assembled = { ...platform, loaded: null };
     platformContext = {
@@ -32752,7 +32763,8 @@ async function createSession(options = {}) {
       onProviderSelected: (selection) => {
         const body = providerSwitchedBody(selection);
         if (body !== null) emitBody(body, "provider");
-      }
+      },
+      onWarn: createPlatformWarningHandler(options.onPlatformWarning)
     });
     binding = {
       client: assembled.client,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tansr/sdk",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Tansr public TypeScript SDK: headless agent API (query / createSession / runAgent) + pure protocol type re-exports (public, MIT).",
   "license": "MIT",
   "type": "module",