@tansr/sdk 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -10087,6 +10087,50 @@ interface Tool<Args = unknown> {
     execute(args: Args, ctx: ToolContext): Promise<ToolResult>;
 }
 
+/**
+ * T-D6 — 会话待办台账(内存态,不做持久化)。
+ *
+ * 设计要点:
+ * - `TodoItem` 形状与 protocol `plan.todo.updated` 事件的 items 对齐
+ *   (id/content/status 三字段;status 在事件侧是宽松 string,本侧收窄为枚举);
+ * - 依赖注入:`onChange` 由工厂(内核会话装配处)注入,store 本身不发事件、
+ *   不落盘——外部在回调里接线 `plan.todo.updated` 事件与(未来的)持久化;
+ * - 所有对外暴露的数组/对象均为副本,防止调用方或回调持引用后污染内部状态。
+ */
+/** 待办状态全集(as const 元组,供 zod enum 与类型共用一份事实源) */
+declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
+type TodoStatus = (typeof TODO_STATUSES)[number];
+interface TodoItem {
+    id: string;
+    content: string;
+    status: TodoStatus;
+}
+/**
+ * merge 输入:按 id 定位,已知 id 只覆盖给定字段(未给字段保留原值);
+ * 未知 id 追加为新项,此时 content 与 status 必须齐全(TodoWrite 工具
+ * 的 schema 恒为全量,不会触发缺字段路径;此约束仅防御其他内部调用方)。
+ */
+type TodoPatch = {
+    id: string;
+} & Partial<Omit<TodoItem, 'id'>>;
+interface TodoStoreOptions {
+    /** 变更回调:replace/merge 每次调用后触发一次,载荷为变更后完整列表的独立副本 */
+    onChange?: (items: TodoItem[]) => void;
+}
+declare class TodoStore {
+    #private;
+    constructor(options?: TodoStoreOptions);
+    /** 当前列表(副本;修改返回值不影响内部状态) */
+    list(): TodoItem[];
+    /** 全量替换(含替换为空 = 清空台账),返回变更后快照 */
+    replace(items: readonly TodoItem[]): TodoItem[];
+    /**
+     * 按 id 合并:已知 id 原位覆盖给定字段;未知 id 按提交顺序追加到尾部。
+     * 返回变更后快照。未知 id 缺 content/status 视为调用方契约错误,抛 TypeError。
+     */
+    merge(patches: readonly TodoPatch[]): TodoItem[];
+}
+
 /**
  * T-C1 — 测试用顺序工具执行器(ToolExecutor 的最小实现)。
  *
@@ -10820,50 +10864,6 @@ type OnToolDecision = (record: ToolDecisionRecord) => void;
  */
 type CaptureFileCheckpoints = (paths: readonly string[]) => Promise<void> | void;
 
-/**
- * T-D6 — 会话待办台账(内存态,不做持久化)。
- *
- * 设计要点:
- * - `TodoItem` 形状与 protocol `plan.todo.updated` 事件的 items 对齐
- *   (id/content/status 三字段;status 在事件侧是宽松 string,本侧收窄为枚举);
- * - 依赖注入:`onChange` 由工厂(内核会话装配处)注入,store 本身不发事件、
- *   不落盘——外部在回调里接线 `plan.todo.updated` 事件与(未来的)持久化;
- * - 所有对外暴露的数组/对象均为副本,防止调用方或回调持引用后污染内部状态。
- */
-/** 待办状态全集(as const 元组,供 zod enum 与类型共用一份事实源) */
-declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
-type TodoStatus = (typeof TODO_STATUSES)[number];
-interface TodoItem {
-    id: string;
-    content: string;
-    status: TodoStatus;
-}
-/**
- * merge 输入:按 id 定位,已知 id 只覆盖给定字段(未给字段保留原值);
- * 未知 id 追加为新项,此时 content 与 status 必须齐全(TodoWrite 工具
- * 的 schema 恒为全量,不会触发缺字段路径;此约束仅防御其他内部调用方)。
- */
-type TodoPatch = {
-    id: string;
-} & Partial<Omit<TodoItem, 'id'>>;
-interface TodoStoreOptions {
-    /** 变更回调:replace/merge 每次调用后触发一次,载荷为变更后完整列表的独立副本 */
-    onChange?: (items: TodoItem[]) => void;
-}
-declare class TodoStore {
-    #private;
-    constructor(options?: TodoStoreOptions);
-    /** 当前列表(副本;修改返回值不影响内部状态) */
-    list(): TodoItem[];
-    /** 全量替换(含替换为空 = 清空台账),返回变更后快照 */
-    replace(items: readonly TodoItem[]): TodoItem[];
-    /**
-     * 按 id 合并:已知 id 原位覆盖给定字段;未知 id 按提交顺序追加到尾部。
-     * 返回变更后快照。未知 id 缺 content/status 视为调用方契约错误,抛 TypeError。
-     */
-    merge(patches: readonly TodoPatch[]): TodoItem[];
-}
-
 /**
  * T-D6 — 交互通道抽象:AskUser 工具与表面层之间的依赖注入缝。
  *
@@ -16588,6 +16588,15 @@ declare function assemblePlatformModel(options: AssemblePlatformModelOptions): P
 
 /** 生成张数 wire 帽(与网关 TwpImagegenRequestSchema 同值;超模型帽由网关再钳)。 */
 declare const IMAGEGEN_TOOL_MAX_N = 4;
+/**
+ * 客户端硬超时缺省(毫秒;kernel Tool.timeoutMs 位)= 服务端生成预算 120s
+ * (tansr-api IMAGEGEN_DEFAULT_TIMEOUT_MS,解出层全模型恒用此值——含 classic
+ * 万相异步任务与 mj_task midjourney 任务轮询长径)+ 60s 余量(videogen 同口径:
+ * 请求上行/网关前置/响应回传)。kernel 统一档同为 120s、对服务端预算零余量——
+ * 任务径跑满预算时客户端恒先掐(同 videogen 的有扣无产形态,窗口更短),故
+ * 显式声明盖过。
+ */
+declare const IMAGEGEN_TOOL_TIMEOUT_MS = 180000;
 declare const ImageGenArgsSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
@@ -16639,6 +16648,12 @@ interface CreateImageGenToolOptions {
      * 直构/旧径),描述回落通用指引。
      */
     models?: readonly AppBundleImageModel[];
+    /**
+     * 客户端硬超时覆盖(毫秒;透传 kernel Tool.timeoutMs)。缺省
+     * IMAGEGEN_TOOL_TIMEOUT_MS(服务端 120s 预算 + 60s 余量)——恒不回落
+     * kernel 120s 统一档(与服务端预算零余量,任务轮询径必先掐)。
+     */
+    timeoutMs?: number;
 }
 /**
  * 环3 平台图像生成工具(kernel Tool 形态;name 'ImageGen' 沿 kernel PascalCase
@@ -16667,6 +16682,16 @@ declare function createImageGenTool(options: CreateImageGenToolOptions): Tool<Im
 
 /** 时长 wire 帽(秒;与网关 TwpVideogenRequestSchema 同值;超模型帽由网关再钳)。 */
 declare const VIDEOGEN_TOOL_MAX_DURATION = 30;
+/**
+ * 客户端硬超时缺省(毫秒;kernel Tool.timeoutMs 位)= 服务端轮询预算 600s
+ * (tansr-api VIDEOGEN_DEFAULT_TIMEOUT_MS,解出层全模型恒用此值)+ 60s 余量
+ * (请求上行/网关前置[认证/限流/配额/预扣]/响应回传)。/t1/videogen 系服务端
+ * 同步长等——客户端必须等到服务端先出结论(成功或 upstream_timeout 退款),
+ * 恒不先掐:客户端先超时会复现「服务端成功结算而智能体无产出」的有扣无产
+ * (2026-09-01 定谳:kling-v3 实测 122-185s,kernel 120s 缺省档下结构性必超时,
+ * 三笔 ¥2.40 计 ¥7.20 有扣无产)。
+ */
+declare const VIDEOGEN_TOOL_TIMEOUT_MS = 660000;
 declare const VideoGenArgsSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
@@ -16720,6 +16745,12 @@ interface CreateVideoGenToolOptions {
      * (注入档直构/旧径),描述回落通用指引。
      */
     models?: readonly AppBundleVideoModel[];
+    /**
+     * 客户端硬超时覆盖(毫秒;透传 kernel Tool.timeoutMs)。缺省
+     * VIDEOGEN_TOOL_TIMEOUT_MS(服务端 600s 预算 + 60s 余量)——恒不回落
+     * kernel 120s 统一档(视频生成分钟级,120s 帽结构性必超时)。
+     */
+    timeoutMs?: number;
 }
 /**
  * 环3 平台视频生成工具(kernel Tool 形态;name 'VideoGen' 沿 kernel PascalCase
@@ -16795,5 +16826,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, 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 { 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, 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, 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

@@ -30851,6 +30851,7 @@ var AppQuotaSchema = z41.object({
 // src/platform/imagegen-tool.ts
 import { z as z42 } from "zod";
 var IMAGEGEN_TOOL_MAX_N = 4;
+var IMAGEGEN_TOOL_TIMEOUT_MS = 18e4;
 var ImageGenArgsSchema = z42.object({
   // S-G1(媒体池化顺位取用):Optional——缺席即不发 model 位,网关按授权集顺位
   // 第一生效(与 bundle platformModels.imageGen 首行恒同);点名限集内(工具描述自列)。
@@ -30925,11 +30926,14 @@ function createImageGenTool(options) {
   const token = options.token;
   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),
+    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). Some models run as polled tasks and can take a minute or two — client-side wait cap is ~3 minutes. 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?, imageUrls?.",
     inputSchema: ImageGenArgsSchema,
     isReadOnly: false,
     isConcurrencySafe: false,
+    // 2026-09-01 定谳修(videogen 同批):服务端预算 120s 与 kernel 120s 缺省档
+    // 零余量,classic/mj_task 任务轮询径跑满预算时客户端恒先掐——声明 180s 盖过。
+    timeoutMs: options.timeoutMs ?? IMAGEGEN_TOOL_TIMEOUT_MS,
     async execute(args, ctx) {
       const modelRef = args.model ?? "(default)";
       if (ctx.signal.aborted) {
@@ -30994,6 +30998,7 @@ function createImageGenTool(options) {
 // src/platform/videogen-tool.ts
 import { z as z43 } from "zod";
 var VIDEOGEN_TOOL_MAX_DURATION = 30;
+var VIDEOGEN_TOOL_TIMEOUT_MS = 66e4;
 var VideoGenArgsSchema = z43.object({
   // S-G1(媒体池化顺位取用):Optional——缺席即不发 model 位,网关按授权集顺位
   // 第一生效(与 bundle platformModels.videoGen 首行恒同);点名限集内(工具描述自列)。
@@ -31084,11 +31089,15 @@ function createVideoGenTool(options) {
   const token = options.token;
   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),
+    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). This call waits for the result — client-side wait cap is ~11 minutes; do not abort or retry early. 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?, imageUrls?.",
     inputSchema: VideoGenArgsSchema,
     isReadOnly: false,
     isConcurrencySafe: false,
+    // 2026-09-01 定谳修:/t1/videogen 系服务端同步长等(600s 轮询预算),kernel
+    // 120s 缺省档下分钟级任务结构性必超时且有扣无产——工具级声明盖过缺省档
+    // (kernel 全局档恒不动;dispatching-tool-executor timeoutMs>0 即生效)。
+    timeoutMs: options.timeoutMs ?? VIDEOGEN_TOOL_TIMEOUT_MS,
     async execute(args, ctx) {
       const modelRef = args.model ?? "(default)";
       if (ctx.signal.aborted) {
@@ -32050,7 +32059,7 @@ function toolCallIds(message) {
 function toolResultIds(message) {
   return message.blocks.flatMap((b) => b.t === "tool_result" ? [b.callId] : []);
 }
-function repairHistoryPairing(messages) {
+function repairHistoryPairing2(messages) {
   const open4 = /* @__PURE__ */ new Set();
   let cleanEnd = 0;
   for (let i = 0; i < messages.length; i++) {
@@ -32409,7 +32418,7 @@ async function createSession(options = {}) {
         `createSession: session "${options.resume.sessionId}" was not found in the given store; list() the store or create a fresh session instead.`
       );
     }
-    initialMessages = repairHistoryPairing(record.messages).messages;
+    initialMessages = repairHistoryPairing2(record.messages).messages;
   }
   const platformSessionId = tokenTier ? ulid() : void 0;
   let sessionRef = null;
@@ -33699,6 +33708,7 @@ export {
   EndUserIdSchema,
   HEADER_APP_TOKEN,
   IMAGEGEN_TOOL_MAX_N,
+  IMAGEGEN_TOOL_TIMEOUT_MS,
   ImageGenArgsSchema,
   McpHost,
   OUTPUT_TAIL_MAX_CHARS,
@@ -33710,6 +33720,7 @@ export {
   TansrSdkError,
   UnavailableChannel,
   VIDEOGEN_TOOL_MAX_DURATION,
+  VIDEOGEN_TOOL_TIMEOUT_MS,
   VideoGenArgsSchema,
   accumulateUsage,
   appBundleRegistryConfig,

package/package.json

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