@tansr/sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -5644,8 +5644,9 @@ declare const TansrConfigSchema: z.ZodObject<{
          * TANSR_CLASSIFIER_TIGHTEN_OUTSIDE_AUTO / TANSR_CLASSIFIER_BUDGET 保留为
          * 最高优先覆盖(逐键接管)。仅 user/managed 层被尊重(T-K0:分类器属
          * 用户/企业的信任与成本决策,项目层声明整段忽略+示警)。
-         * 刻意不进配置:TANSR_CLASSIFIER_ALLOW_UNQUALIFIED(资格越过)——
-         * break-glass 性质,进配置文件即可分发可持久,恒 env-only。
+         * 史注:TANSR_CLASSIFIER_ALLOW_UNQUALIFIED(资格越过)曾刻意不进配置
+         * (break-glass 性质恒 env-only),已随 UAA P4-C2 整体退役(2026-08-30,
+         * 任命即授照后无「未达资格」可越)。
          */
         classifier: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
@@ -7021,15 +7022,6 @@ interface PermissionClassifierConfig {
     classifier: PermissionClassifier;
     /** 咨询超时(毫秒),缺省 DEFAULT_CLASSIFIER_TIMEOUT_MS;超时维持 ask */
     timeoutMs?: number;
-    /**
-     * safe→allow 裁决人资格位(T-K12 止血,05 §10.2/INV-5)。
-     *
-     * @deprecated T-K23c 起由 resolveQualificationTier 三级档位解析闭包取代
-     * (16 §4.5);仅供过渡期测试。解析闭包缺席时按 `true→'high'` /
-     * `false|缺省→'none'` 派生;闭包在场时本位被忽略。W1 收口卡
-     * (T-K23g)将其移出生产装配路径。
-     */
-    qualifiedForAllow?: boolean;
     /**
      * 三级资格档动态解析闭包(T-K23c,16 §4.5):返回当前生效档
      * (= min(授格档, 天花板, 会话覆盖),合成在装配层)。引擎**每次咨询
@@ -10591,9 +10583,9 @@ declare class PermissionEngine {
     /**
      * 生效资格档解析(T-K23c,16 §4.5):解析闭包在场即**现算**(装配层合成
      * min(entry, ceiling, override);闭包抛错 → 'none',词表外脏值由
-     * softenRadiusAllows 安全查表兜底——T-INV-B 一切异常朝严);闭包缺席时
-     * 按 @deprecated 布尔位派生 `true→'high'/false|缺省→'none'`(W1 过渡
-     * 兼容,16 §4.5;收口见 T-K23g)。
+     * softenRadiusAllows 安全查表兜底——T-INV-B 一切异常朝严);闭包缺席
+     * 恒 'none'(无任命即无软化面;@deprecated 布尔位 qualifiedForAllow
+     * 已随 P4-C3 拆除,2026-08-30)。
      */
     private resolveClassifierTier;
     /**
@@ -15542,22 +15534,79 @@ interface AppBundleModel {
     capabilities: Record<string, unknown>;
     contextWindow: number | null;
 }
+/**
+ * 图像模型受理约束(bundle platformModels.imageGen 行 constraints 加法键,
+ * 2026-09-01;网关侧单源 = /t1 运行时校验档同一 classify 词表)。工具描述
+ * 逐模型拼注——智能体首发即中,不再靠拒收错误试错(用户实测连环拒收后追加)。
+ */
+interface ImageModelConstraints {
+    /** false = 模型定档分辨率,size 在场即拒。 */
+    size: boolean;
+    seed: boolean;
+    negativePrompt: boolean;
+    /** 单请求张数帽(n 超帽由网关钳)。 */
+    maxImages: number;
+    /** 富输入 imageUrls 受理域(null = 纯文生行,在场即拒)。 */
+    imageInput: {
+        min: number;
+        max: number;
+        urlOk: boolean;
+        b64Ok: boolean;
+    } | null;
+    /** false = 动词行(引用既有任务),prompt 在场即拒。 */
+    promptRequired: boolean;
+    /** 动词行必携 action{taskId,actionId}。 */
+    actionRequired?: boolean;
+}
+/** 视频模型受理约束(同上镜像;时长域/首帧受理/比例域是实测三大拒收源)。 */
+interface VideoModelConstraints {
+    durations: {
+        kind: 'set';
+        values: number[];
+        defaultSec: number;
+    } | {
+        kind: 'range';
+        min: number;
+        max: number;
+        defaultSec: number;
+    };
+    /** 比例词形域(null = ratio 在场即拒;键缺席 = 透传上游,域未实录)。 */
+    ratio?: string[] | null;
+    negativePrompt: boolean;
+    seed: boolean;
+    /** 首帧图受理域(required = i2v 专用行必携 imageUrls;null = 纯文生行在场即拒)。 */
+    imageInput: {
+        required: boolean;
+        max: number;
+        urlOk: boolean;
+        b64Ok: boolean;
+    } | null;
+    audioInput: boolean;
+}
 /**
  * 授权媒体模型条目(S-G1 媒体池化顺位取用,用户拍板 2026-08-30):`model` =
  * canonical handle(/t1/imagegen、/t1/videogen 的 model 位可直用)。网关契约
- * 恒不下发价格/成本/供应商内部信息,本形态即全量。
+ * 恒不下发价格/成本/供应商内部信息。constraints 加法键(2026-09-01)按 kind
+ * 特化(下方两型);条目级容错:缺席/坏形状 = undefined(旧 api 回落通用
+ * 描述,恒不臆造受理面)。
  */
 interface AppBundleMediaModel {
     model: string;
     displayName: string;
 }
+interface AppBundleImageModel extends AppBundleMediaModel {
+    constraints?: ImageModelConstraints;
+}
+interface AppBundleVideoModel extends AppBundleMediaModel {
+    constraints?: VideoModelConstraints;
+}
 /**
  * 授权媒体模型集(bundle platformModels 段):序 = 平台收敛稳定序,**顺位第一
  * 即工具/网关 model 缺省时的生效模型**;空数组 = 平台未配置(如实,恒不猜名)。
  */
 interface AppBundlePlatformModels {
-    imageGen: AppBundleMediaModel[];
-    videoGen: AppBundleMediaModel[];
+    imageGen: AppBundleImageModel[];
+    videoGen: AppBundleVideoModel[];
 }
 /** bundle-for-app 的 SDK 消费子集 */
 interface AppBundle {
@@ -16546,20 +16595,23 @@ declare const ImageGenArgsSchema: z.ZodObject<{
     size: z.ZodOptional<z.ZodString>;
     n: z.ZodOptional<z.ZodNumber>;
     seed: z.ZodOptional<z.ZodNumber>;
+    imageUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
     size?: string | undefined;
     n?: number | undefined;
-    negativePrompt?: string | undefined;
     seed?: number | undefined;
+    negativePrompt?: string | undefined;
+    imageUrls?: string[] | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
     size?: string | undefined;
     n?: number | undefined;
-    negativePrompt?: string | undefined;
     seed?: number | undefined;
+    negativePrompt?: string | undefined;
+    imageUrls?: string[] | undefined;
 }>;
 type ImageGenArgs = z.infer<typeof ImageGenArgsSchema>;
 /** 表面层渲染用结构化数据(ToolResult.data;错误时携错误码)。 */
@@ -16581,11 +16633,12 @@ interface CreateImageGenToolOptions {
     fetchImpl?: typeof fetch;
     /**
      * 授权图像模型集(S-G1;bundle platformModels.imageGen,装配循环自取):
-     * 工具描述自列(顺位第一 = model 缺省生效模型);空数组 = 平台未配置
-     * (描述如实注明,恒不猜名);缺席 = 集未知(注入档直构/旧径),描述回落
-     * 通用指引。
+     * 工具描述自列(顺位第一 = model 缺省生效模型),constraints 在场时逐模型
+     * 拼受理约束注记(2026-09-01——size/富输入/动词行,智能体首发即中);
+     * 空数组 = 平台未配置(描述如实注明,恒不猜名);缺席 = 集未知(注入档
+     * 直构/旧径),描述回落通用指引。
      */
-    models?: readonly AppBundleMediaModel[];
+    models?: readonly AppBundleImageModel[];
 }
 /**
  * 环3 平台图像生成工具(kernel Tool 形态;name 'ImageGen' 沿 kernel PascalCase
@@ -16621,20 +16674,23 @@ declare const VideoGenArgsSchema: z.ZodObject<{
     duration: z.ZodOptional<z.ZodNumber>;
     ratio: z.ZodOptional<z.ZodString>;
     seed: z.ZodOptional<z.ZodNumber>;
+    imageUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
     duration?: number | undefined;
-    negativePrompt?: string | undefined;
     seed?: number | undefined;
+    negativePrompt?: string | undefined;
     ratio?: string | undefined;
+    imageUrls?: string[] | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
     duration?: number | undefined;
-    negativePrompt?: string | undefined;
     seed?: number | undefined;
+    negativePrompt?: string | undefined;
     ratio?: string | undefined;
+    imageUrls?: string[] | undefined;
 }>;
 type VideoGenArgs = z.infer<typeof VideoGenArgsSchema>;
 /** 表面层渲染用结构化数据(ToolResult.data;错误时携错误码)。 */
@@ -16658,11 +16714,12 @@ interface CreateVideoGenToolOptions {
     fetchImpl?: typeof fetch;
     /**
      * 授权视频模型集(S-G1;bundle platformModels.videoGen,装配循环自取):
-     * 工具描述自列(顺位第一 = model 缺省生效模型);空数组 = 平台未配置
-     * (描述如实注明,恒不猜名);缺席 = 集未知(注入档直构/旧径),描述回落
-     * 通用指引。
+     * 工具描述自列(顺位第一 = model 缺省生效模型),constraints 在场时逐模型
+     * 拼受理约束注记(2026-09-01——时长域/i2v 首帧/比例域,实测三大拒收源
+     * 前置进描述);空数组 = 平台未配置(如实注明恒不猜名);缺席 = 集未知
+     * (注入档直构/旧径),描述回落通用指引。
      */
-    models?: readonly AppBundleMediaModel[];
+    models?: readonly AppBundleVideoModel[];
 }
 /**
  * 环3 平台视频生成工具(kernel Tool 形态;name 'VideoGen' 沿 kernel PascalCase
@@ -16739,4 +16796,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, 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 };
+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, 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, 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, VideoModelConstraints, Visibility };

package/dist/index.js

@@ -1455,8 +1455,9 @@ var PermissionsSectionSchema = z5.object({
    * TANSR_CLASSIFIER_TIGHTEN_OUTSIDE_AUTO / TANSR_CLASSIFIER_BUDGET 保留为
    * 最高优先覆盖(逐键接管)。仅 user/managed 层被尊重(T-K0:分类器属
    * 用户/企业的信任与成本决策,项目层声明整段忽略+示警)。
-   * 刻意不进配置:TANSR_CLASSIFIER_ALLOW_UNQUALIFIED(资格越过)——
-   * break-glass 性质,进配置文件即可分发可持久,恒 env-only。
+   * 史注:TANSR_CLASSIFIER_ALLOW_UNQUALIFIED(资格越过)曾刻意不进配置
+   * (break-glass 性质恒 env-only),已随 UAA P4-C2 整体退役(2026-08-30,
+   * 任命即授照后无「未达资格」可越)。
    */
   classifier: z5.object({
     enabled: z5.boolean().optional(),
@@ -11984,14 +11985,14 @@ var PermissionEngine = class {
   /**
    * 生效资格档解析(T-K23c,16 §4.5):解析闭包在场即**现算**(装配层合成
    * min(entry, ceiling, override);闭包抛错 → 'none',词表外脏值由
-   * softenRadiusAllows 安全查表兜底——T-INV-B 一切异常朝严);闭包缺席时
-   * 按 @deprecated 布尔位派生 `true→'high'/false|缺省→'none'`(W1 过渡
-   * 兼容,16 §4.5;收口见 T-K23g)。
+   * softenRadiusAllows 安全查表兜底——T-INV-B 一切异常朝严);闭包缺席
+   * 恒 'none'(无任命即无软化面;@deprecated 布尔位 qualifiedForAllow
+   * 已随 P4-C3 拆除,2026-08-30)。
    */
   resolveClassifierTier(config) {
     const resolve2 = config.resolveQualificationTier;
     if (resolve2 === void 0) {
-      return config.qualifiedForAllow === true ? "high" : "none";
+      return "none";
     }
     try {
       return resolve2();
@@ -12964,6 +12965,47 @@ function buildDecisionRecord(params) {
 }
 
 // ../kernel/src/tools/dispatch/dispatching-tool-executor.ts
+function suggestToolName(attempted, registered) {
+  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const a = norm(attempted);
+  if (a === "") return null;
+  let prefixHit = null;
+  let levHit = null;
+  let levBest = 3;
+  for (const name of registered) {
+    const n = norm(name);
+    if (n === a) return name;
+    if (prefixHit === null && Math.min(n.length, a.length) >= 4 && (n.startsWith(a) || a.startsWith(n))) {
+      prefixHit = name;
+    }
+    const d = boundedLevenshtein(a, n, 2);
+    if (d !== null && d < levBest) {
+      levBest = d;
+      levHit = name;
+    }
+  }
+  return prefixHit ?? levHit;
+}
+function boundedLevenshtein(a, b, cap) {
+  if (Math.abs(a.length - b.length) > cap) return null;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i, ...Array.from({ length: b.length }, () => 0)];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      rowMin = Math.min(rowMin, cur[j]);
+    }
+    if (rowMin > cap) return null;
+    prev = cur;
+  }
+  const d = prev[b.length];
+  return d <= cap ? d : null;
+}
 var DEFAULT_MAX_CONCURRENCY = 8;
 var DEFAULT_TIMEOUT_MS = 12e4;
 var unsafeNoGateConstruction = false;
@@ -13163,7 +13205,8 @@ var DispatchingToolExecutor = class {
       const tool = this.#registry.get(call.name);
       if (tool === void 0) {
         const registered = this.#registry.names();
-        const message = `Unknown tool "${call.name}". ` + (registered.length > 0 ? `Available tools: ${registered.join(", ")}.` : "No tools are registered.");
+        const suggested = suggestToolName(call.name, registered);
+        const message = `Unknown tool "${call.name}". ` + (suggested !== null ? `Did you mean "${suggested}"? ` : "") + (registered.length > 0 ? `Available tools: ${registered.join(", ")}.` : "No tools are registered.");
         yield {
           t: "event",
           body: { type: "tool.failed", toolCallId: call.id, errorType: "unknown_tool", message }
@@ -30812,13 +30855,18 @@ var ImageGenArgsSchema = z42.object({
   // S-G1(媒体池化顺位取用):Optional——缺席即不发 model 位,网关按授权集顺位
   // 第一生效(与 bundle platformModels.imageGen 首行恒同);点名限集内(工具描述自列)。
   model: z42.string().min(1).optional().describe(
-    "Image model name from the authorized set listed in this tool description. Omit to use the default (the first authorized model)."
+    "Image model name from the authorized set listed in this tool description. Omit to use the default (the first authorized model) when the user did not ask for a specific model. Never omit or swap this field as a workaround when the user named a model that is not in the set — tell the user and let them choose first."
   ),
   prompt: z42.string().refine((s) => s.trim().length > 0, { message: "prompt must be a non-empty string" }).describe("Positive prompt describing the desired image content, style and composition."),
   negativePrompt: z42.string().min(1).max(500).optional().describe("Negative prompt: content to keep out of the image."),
   size: z42.string().regex(/^\d{2,5}\*\d{2,5}$/, { message: "size must look like '1024*1024' (width*height)" }).optional().describe("Output resolution as 'width*height' (for example '1024*1024'; defaults to the model's default)."),
   n: z42.number().int().min(1).max(IMAGEGEN_TOOL_MAX_N).optional().describe(`Number of images to generate (default 1, max ${IMAGEGEN_TOOL_MAX_N}; each image is billed).`),
-  seed: z42.number().int().min(0).max(2147483647).optional().describe("Random seed for relatively stable output (defaults to a random seed upstream).")
+  seed: z42.number().int().min(0).max(2147483647).optional().describe("Random seed for relatively stable output (defaults to a random seed upstream)."),
+  // 媒体二批富输入位(2026-09-01;网关 TwpImagegenRequestSchema 同帽 1..14):
+  // 受理域随模型(工具描述逐模型注明;不受理的模型在场即 bad_request)。
+  imageUrls: z42.array(z42.string().min(1)).min(1).max(14).optional().describe(
+    "Input images for image editing or reference-conditioned generation (public http(s) URLs or data:image/*;base64 URIs). Only pass this for models whose bracketed note in this description lists imageUrls support; other models reject it."
+  )
 });
 function errorResult13(text, model, errorCode2) {
   const data = { model, images: [], imageCount: 0, ...errorCode2 !== void 0 ? { errorCode: errorCode2 } : {} };
@@ -30832,7 +30880,7 @@ function hintOf(code) {
     return " Image generation is not configured on this platform yet; tell the user instead of retrying.";
   }
   if (code === "model_not_authorized") {
-    return " Use an image model name that this app is authorized for.";
+    return ` The requested model is not in the authorized image model set of this app. Do not silently retry with another model or without "model" — tell the user, show the authorized image models from this tool's description, and let the user choose.`;
   }
   if (code === "imagegen_quota_exceeded") {
     return " The daily image quota for this account is exhausted; retry after the daily reset (UTC+8).";
@@ -30842,6 +30890,25 @@ function hintOf(code) {
   }
   return "";
 }
+function imageModelNote(m) {
+  const label = m.displayName !== m.model ? `${m.model} (${m.displayName})` : m.model;
+  const c = m.constraints;
+  if (c === void 0) return label;
+  const notes = [];
+  if (!c.promptRequired) {
+    notes.push("task-action model, NOT usable via this tool — pick another model");
+  }
+  if (!c.size) notes.push("fixed output size — do not pass size");
+  if (c.imageInput !== null) {
+    const forms = c.imageInput.urlOk && c.imageInput.b64Ok ? "URL or base64 data URI" : c.imageInput.urlOk ? "URL only" : "base64 data URI only";
+    const count = c.imageInput.min > 0 ? `requires ${c.imageInput.min === c.imageInput.max ? String(c.imageInput.min) : `${c.imageInput.min}-${c.imageInput.max}`} input image(s)` : `accepts up to ${c.imageInput.max} reference image(s)`;
+    notes.push(`${count} via imageUrls (${forms})`);
+  }
+  if (!c.seed) notes.push("no seed");
+  if (!c.negativePrompt) notes.push("no negativePrompt");
+  if (c.maxImages === 1) notes.push("single image per call (n=1)");
+  return notes.length > 0 ? `${label} [${notes.join("; ")}]` : label;
+}
 function authorizedModelsNote(models) {
   if (models === void 0) {
     return ' Omit "model" to use the app default, or ask the app developer for authorized model names.';
@@ -30849,8 +30916,8 @@ function authorizedModelsNote(models) {
   if (models.length === 0) {
     return " The platform has no image model configured for this app yet — tell the user instead of retrying or guessing model names.";
   }
-  const listed = models.map((m) => m.displayName !== m.model ? `${m.model} (${m.displayName})` : m.model).join(", ");
-  return ` Authorized image models (omit "model" to use the first as default): ${listed}.`;
+  const listed = models.map((m) => `- ${imageModelNote(m)}`).join("\n");
+  return ' Authorized image models — the first is the default when "model" is omitted; bracketed notes are hard per-model constraints enforced by the platform (violating them fails the call):\n' + listed + '\nIf the user names a model outside this list (including a video model asked to make images), do not silently omit "model" or substitute another model — tell the user, show this list, and let them choose.';
 }
 function createImageGenTool(options) {
   const base = options.baseUrl.replace(/\/+$/, "");
@@ -30859,7 +30926,7 @@ function createImageGenTool(options) {
   return {
     name: "ImageGen",
     description: "Generates images from a text prompt via the tansr platform (ring-3 hosted capability; the platform calls the image provider and bills the app per generated image). Returns image URLs that stay valid for roughly 24 hours — surface them to the user promptly. Requires the app to have the imageGen platform capability enabled." + authorizedModelsNote(options.models),
-    shortDescription: "Generate images from a prompt via the tansr platform (billed per image). Args: model?, prompt, negativePrompt?, size?, n?, seed?.",
+    shortDescription: "Generate images from a prompt via the tansr platform (billed per image). Args: model?, prompt, negativePrompt?, size?, n?, seed?, imageUrls?.",
     inputSchema: ImageGenArgsSchema,
     isReadOnly: false,
     isConcurrencySafe: false,
@@ -30874,7 +30941,8 @@ function createImageGenTool(options) {
         ...args.negativePrompt !== void 0 ? { negativePrompt: args.negativePrompt } : {},
         ...args.size !== void 0 ? { size: args.size } : {},
         ...args.n !== void 0 ? { n: args.n } : {},
-        ...args.seed !== void 0 ? { seed: args.seed } : {}
+        ...args.seed !== void 0 ? { seed: args.seed } : {},
+        ...args.imageUrls !== void 0 ? { imageUrls: args.imageUrls } : {}
       };
       let response;
       try {
@@ -30930,15 +30998,21 @@ var VideoGenArgsSchema = z43.object({
   // S-G1(媒体池化顺位取用):Optional——缺席即不发 model 位,网关按授权集顺位
   // 第一生效(与 bundle platformModels.videoGen 首行恒同);点名限集内(工具描述自列)。
   model: z43.string().min(1).optional().describe(
-    "Video model name from the authorized set listed in this tool description. Omit to use the default (the first authorized model)."
+    "Video model name from the authorized set listed in this tool description. Omit to use the default (the first authorized model) when the user did not ask for a specific model. Never omit or swap this field as a workaround when the user named a model that is not in the set — tell the user and let them choose first."
   ),
   prompt: z43.string().refine((s) => s.trim().length > 0, { message: "prompt must be a non-empty string" }).describe("Positive prompt describing the desired video content, motion, style and camera work."),
   negativePrompt: z43.string().min(1).max(500).optional().describe("Negative prompt: content to keep out of the video."),
   duration: z43.number().int().min(2).max(VIDEOGEN_TOOL_MAX_DURATION).optional().describe(
-    `Video duration in seconds (default 5, max ${VIDEOGEN_TOOL_MAX_DURATION}; billing is per second — longer costs more).`
+    "Video duration in seconds (billing is per second — longer costs more). Models accept only the durations listed in their bracketed note; omit to use the model default."
   ),
   ratio: z43.string().regex(/^(adaptive|\d{1,2}:\d{1,2})$/, { message: "ratio must look like '16:9' (or 'adaptive' where supported)" }).optional().describe("Aspect ratio such as '16:9', '9:16' or '1:1' (defaults to the model's default)."),
-  seed: z43.number().int().min(0).max(2147483647).optional().describe("Random seed for relatively stable output (defaults to a random seed upstream).")
+  seed: z43.number().int().min(0).max(2147483647).optional().describe("Random seed for relatively stable output (defaults to a random seed upstream)."),
+  // 媒体二批富输入位(2026-09-01;网关 TwpVideogenRequestSchema 同帽 1..2):
+  // i2v 首帧(seedance 支持首帧+尾帧两张);受理域随模型(描述逐模型注明,
+  // i2v 专用行缺席即拒、纯文生行在场即拒)。
+  imageUrls: z43.array(z43.string().min(1)).min(1).max(2).optional().describe(
+    'First-frame image(s) for image-to-video generation (public http(s) URL or data:image/*;base64 URI). REQUIRED for models marked "image-to-video ONLY" in this description (generate or obtain an image first, e.g. via the ImageGen tool); rejected by text-to-video-only models.'
+  )
 });
 function errorResult14(text, model, errorCode2) {
   const data = {
@@ -30958,7 +31032,7 @@ function hintOf2(code) {
     return " Video generation is not configured on this platform yet; tell the user instead of retrying.";
   }
   if (code === "model_not_authorized") {
-    return " Use a video model name that this app is authorized for.";
+    return ` The requested model is not in the authorized video model set of this app. Do not silently retry with another model or without "model" — tell the user, show the authorized video models from this tool's description, and let the user choose.`;
   }
   if (code === "videogen_quota_exceeded") {
     return " The daily video-seconds quota for this account is exhausted; retry after the daily reset (UTC+8).";
@@ -30966,8 +31040,34 @@ function hintOf2(code) {
   if (code === "insufficient_balance") {
     return " The app account balance is insufficient; the app developer needs to top up.";
   }
+  if (code === "upstream_error") {
+    return " The video provider failed to execute the task. If imageUrls was passed, the provider may be unable to fetch that image host — retry with an image from a different image model or another public URL.";
+  }
   return "";
 }
+function videoModelNote(m) {
+  const label = m.displayName !== m.model ? `${m.model} (${m.displayName})` : m.model;
+  const c = m.constraints;
+  if (c === void 0) return label;
+  const notes = [];
+  const d = c.durations;
+  notes.push(
+    d.kind === "set" ? `duration ${d.values.join("|")}s ONLY (default ${d.defaultSec}s)` : `duration ${d.min}-${d.max}s (default ${d.defaultSec}s)`
+  );
+  if (c.imageInput === null) {
+    notes.push("text-to-video only — rejects imageUrls");
+  } else {
+    const forms = c.imageInput.urlOk && c.imageInput.b64Ok ? "URL or base64 data URI" : c.imageInput.urlOk ? "URL only" : "base64 data URI only";
+    notes.push(
+      c.imageInput.required ? `image-to-video ONLY — first-frame image via imageUrls is REQUIRED (${forms})` : `optional first-frame image via imageUrls (${forms})`
+    );
+  }
+  if (c.ratio === null) notes.push("no ratio");
+  else if (c.ratio !== void 0) notes.push(`ratio ${c.ratio.join("|")}`);
+  if (!c.seed) notes.push("no seed");
+  if (!c.negativePrompt) notes.push("no negativePrompt");
+  return `${label} [${notes.join("; ")}]`;
+}
 function authorizedModelsNote2(models) {
   if (models === void 0) {
     return ' Omit "model" to use the app default, or ask the app developer for authorized model names.';
@@ -30975,8 +31075,8 @@ function authorizedModelsNote2(models) {
   if (models.length === 0) {
     return " The platform has no video model configured for this app yet — tell the user instead of retrying or guessing model names.";
   }
-  const listed = models.map((m) => m.displayName !== m.model ? `${m.model} (${m.displayName})` : m.model).join(", ");
-  return ` Authorized video models (omit "model" to use the first as default): ${listed}.`;
+  const listed = models.map((m) => `- ${videoModelNote(m)}`).join("\n");
+  return ' Authorized video models — the first is the default when "model" is omitted; bracketed notes are hard per-model constraints enforced by the platform (violating them fails the call):\n' + listed + '\nIf the user names a model outside this list (including an image model asked to make videos), do not silently omit "model" or substitute another model — tell the user, show this list, and let them choose.';
 }
 function createVideoGenTool(options) {
   const base = options.baseUrl.replace(/\/+$/, "");
@@ -30985,7 +31085,7 @@ function createVideoGenTool(options) {
   return {
     name: "VideoGen",
     description: "Generates a short video from a text prompt via the tansr platform (ring-3 hosted capability; the platform calls the video provider and bills the app per second of generated video). Generation is a long-running task (often minutes). Returns a video URL that stays valid for roughly 24 hours — surface it to the user promptly. Requires the app to have the videoGen platform capability enabled." + authorizedModelsNote2(options.models),
-    shortDescription: "Generate a video from a prompt via the tansr platform (billed per second). Args: model?, prompt, negativePrompt?, duration?, ratio?, seed?.",
+    shortDescription: "Generate a video from a prompt via the tansr platform (billed per second). Args: model?, prompt, negativePrompt?, duration?, ratio?, seed?, imageUrls?.",
     inputSchema: VideoGenArgsSchema,
     isReadOnly: false,
     isConcurrencySafe: false,
@@ -31000,7 +31100,8 @@ function createVideoGenTool(options) {
         ...args.negativePrompt !== void 0 ? { negativePrompt: args.negativePrompt } : {},
         ...args.duration !== void 0 ? { duration: args.duration } : {},
         ...args.ratio !== void 0 ? { ratio: args.ratio } : {},
-        ...args.seed !== void 0 ? { seed: args.seed } : {}
+        ...args.seed !== void 0 ? { seed: args.seed } : {},
+        ...args.imageUrls !== void 0 ? { imageUrls: args.imageUrls } : {}
       };
       let response;
       try {
@@ -31516,14 +31617,72 @@ function parseModel(raw) {
     contextWindow: typeof raw.contextWindow === "number" ? raw.contextWindow : null
   };
 }
-function parseMediaModels(raw) {
+function parseMediaImageInput(raw, flagKey) {
+  if (raw === null) return null;
+  if (!isRecord8(raw)) return false;
+  const flag = raw[flagKey];
+  if (flagKey === "min" ? typeof flag !== "number" : typeof flag !== "boolean") return false;
+  if (typeof raw.max !== "number" || typeof raw.urlOk !== "boolean" || typeof raw.b64Ok !== "boolean") return false;
+  return { flag, max: raw.max, urlOk: raw.urlOk, b64Ok: raw.b64Ok };
+}
+function parseImageConstraints(raw) {
+  if (!isRecord8(raw)) return void 0;
+  if (typeof raw.size !== "boolean" || typeof raw.seed !== "boolean" || typeof raw.negativePrompt !== "boolean" || typeof raw.maxImages !== "number" || typeof raw.promptRequired !== "boolean") {
+    return void 0;
+  }
+  const input = parseMediaImageInput(raw.imageInput, "min");
+  if (input === false) return void 0;
+  return {
+    size: raw.size,
+    seed: raw.seed,
+    negativePrompt: raw.negativePrompt,
+    maxImages: raw.maxImages,
+    imageInput: input === null ? null : { min: input.flag, max: input.max, urlOk: input.urlOk, b64Ok: input.b64Ok },
+    promptRequired: raw.promptRequired,
+    ...raw.actionRequired === true ? { actionRequired: true } : {}
+  };
+}
+function parseVideoConstraints(raw) {
+  if (!isRecord8(raw)) return void 0;
+  const d = raw.durations;
+  let durations = null;
+  if (isRecord8(d) && typeof d.defaultSec === "number") {
+    if (d.kind === "set" && Array.isArray(d.values) && d.values.every((v) => typeof v === "number")) {
+      durations = { kind: "set", values: [...d.values], defaultSec: d.defaultSec };
+    } else if (d.kind === "range" && typeof d.min === "number" && typeof d.max === "number") {
+      durations = { kind: "range", min: d.min, max: d.max, defaultSec: d.defaultSec };
+    }
+  }
+  if (durations === null) return void 0;
+  if (typeof raw.negativePrompt !== "boolean" || typeof raw.seed !== "boolean" || typeof raw.audioInput !== "boolean") {
+    return void 0;
+  }
+  const input = parseMediaImageInput(raw.imageInput, "required");
+  if (input === false) return void 0;
+  let ratio;
+  if (raw.ratio === void 0) ratio = void 0;
+  else if (raw.ratio === null) ratio = null;
+  else if (Array.isArray(raw.ratio) && raw.ratio.every((r) => typeof r === "string")) ratio = [...raw.ratio];
+  else return void 0;
+  return {
+    durations,
+    ...ratio !== void 0 ? { ratio } : {},
+    negativePrompt: raw.negativePrompt,
+    seed: raw.seed,
+    imageInput: input === null ? null : { required: input.flag, max: input.max, urlOk: input.urlOk, b64Ok: input.b64Ok },
+    audioInput: raw.audioInput
+  };
+}
+function parseMediaModels(raw, parseConstraints) {
   if (!Array.isArray(raw)) return [];
   const out = [];
   for (const item of raw) {
     if (!isRecord8(item) || typeof item.model !== "string" || item.model === "") continue;
+    const constraints = item.constraints === void 0 ? void 0 : parseConstraints(item.constraints);
     out.push({
       model: item.model,
-      displayName: typeof item.displayName === "string" && item.displayName !== "" ? item.displayName : item.model
+      displayName: typeof item.displayName === "string" && item.displayName !== "" ? item.displayName : item.model,
+      ...constraints !== void 0 ? { constraints } : {}
     });
   }
   return out;
@@ -31544,8 +31703,8 @@ function parseAppBundle(raw) {
     aliases,
     capabilities: parsedCaps.success ? parsedCaps.data : DEFAULT_APP_CAPABILITIES,
     platformModels: {
-      imageGen: parseMediaModels(mediaRaw.imageGen),
-      videoGen: parseMediaModels(mediaRaw.videoGen)
+      imageGen: parseMediaModels(mediaRaw.imageGen, parseImageConstraints),
+      videoGen: parseMediaModels(mediaRaw.videoGen, parseVideoConstraints)
     }
   };
 }

package/package.json

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