@tansr/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -15503,9 +15503,8 @@ interface SdkToolsOptions {
     builtin?: readonly string[];
     /**
      * 环3 平台能力选择(词表:imageGen/videoGen/webSearch)。位关恒 fail-fast;
-     * S-E1/S-F 起 imageGen/videoGen 位开即装配平台工具客户端(ImageGen/VideoGen,
-     * 材料 = 令牌档 platformContext,托管/注入档选择即可读错);webSearch 仍只
-     * 校验位(客户端候后续卡,位开静默不装)。
+     * 位开即装配平台工具客户端(ImageGen/VideoGen/PlatformWebSearch,材料 =
+     * 令牌档 platformContext,托管/注入档选择即可读错)。
      */
     platform?: readonly string[];
     /** 环1 自定义工具(defineTool 产物;kernel Tool 形态直给亦可) */
@@ -15550,8 +15549,7 @@ declare function resolveBuiltinSelection(selection: readonly string[] | undefine
 /**
  * platform 选择集解出(校验 + 装配序):未知名/位关恒 fail-fast 可读错;
  * 返回按 PLATFORM_NAMES 固定序去重的选择集(prompt 前缀稳定,builtin 同律)。
- * S-E1/S-F 起 imageGen/videoGen 进装配径(工具客户端);webSearch 位开静默
- * 不装(客户端候后续卡,语义与旧 validate-only 一致)。
+ * 三位(imageGen/videoGen/webSearch)全进装配径(工具客户端)。
  */
 declare function resolvePlatformSelection(selection: readonly string[] | undefined, capabilities: AppCapabilities): PlatformCapabilityName[];
 /** guide 段的语义标签(IRSystemSegment.label;skills 索引段同款纪律) */
@@ -16397,6 +16395,74 @@ 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 补打通」)。
+ *
+ * 环3 语义:执行不在终端本地——工具 execute 经令牌档 fetch 打平台网关
+ * POST {baseUrl}/t1/websearch(鉴权头 x-tansr-app-token),平台代调搜索
+ * 供应商池(加权选池 + 一次故障转移),**按次计量计费归 App**(pricePerCall;
+ * 开发者对终端如何转售自主,计量计费分离)。
+ *
+ * wire 契约(api 仓 TwpWebsearchRequest/Response,doc/36 §3.2):请求
+ * {query, max_results?} 为 snake_case——与 CLI 内核 HTTP 搜索后端字节同构的
+ * 既有特例(imagegen/videogen 的 camelCase 系 twp 核心纪律,本面迁就既有
+ * 字节);响应 {results:[{title,url,snippet}]}(供应商方言已在网关归一)。
+ *
+ * 命名注记: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 侧同样恒不打印。
+ */
+
+/** 结果数 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 前缀由本工具追加)。 */
+    baseUrl: string;
+    /** app_user 短期令牌(只活在本闭包,恒不进工具定义/日志)。 */
+    token: string;
+    /** fetch 注入缝(测试桩网关;缺省全局 fetch)。 */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * 环3 平台联网搜索工具(kernel Tool 形态;name 'PlatformWebSearch',命名注记
+ * 见文件头)。计费副作用真实存在(按次扣 App 余额)——恒不声明只读/并发安全
+ * (ImageGen/VideoGen 同律保守档;权限规则可按名 gate)。
+ */
+declare function createWebSearchTool(options: CreateWebSearchToolOptions): Tool<WebSearchArgs>;
+
 /** bundle 内单模型条目(SDK 消费子集) */
 interface AppBundleModel {
     handle: string;
@@ -16461,5 +16527,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, accumulateUsage, appBundleRegistryConfig, appendUserMessage, assembleManagedModel, assemblePlatformModel, assembleSdkSkills, assembleTooling, attachSdkMcp, attachSdkTaskTool, buildClientFromRegistry, buildSdkToolSet, buildToolGuideSegment, createAppTokenFetch, createImageGenTool, createMcpHost, createNarrator, createSdkPermissionGate, createSession, createSessionView, createVideoGenTool, 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, 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 };
+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 };

package/dist/index.js

@@ -30550,6 +30550,123 @@ function createVideoGenTool(options) {
   };
 }
 
+// src/platform/websearch-tool.ts
+import { z as z44 } from "zod";
+var WEBSEARCH_TOOL_MAX_RESULTS = 20;
+var WebSearchArgsSchema2 = z44.object({
+  query: z44.string().max(1024).refine((s) => s.trim().length > 0, { message: "query must be a non-empty string" }).describe("Search query text (the platform never logs or stores it)."),
+  max_results: z44.number().int().min(1).max(WEBSEARCH_TOOL_MAX_RESULTS).optional().describe(
+    `Desired number of results (default 8, max ${WEBSEARCH_TOOL_MAX_RESULTS}; the provider may cap it lower). Billing is per call, not per result.`
+  )
+});
+function errorResult15(text, query2, errorCode2) {
+  const data = {
+    query: query2,
+    results: [],
+    resultCount: 0,
+    ...errorCode2 !== void 0 ? { errorCode: errorCode2 } : {}
+  };
+  return { content: [{ t: "text", text }], isError: true, data };
+}
+function hintOf3(code) {
+  if (code === "forbidden") {
+    return " The app platform capability webSearch is disabled; the app developer can enable it in console → app → capabilities.";
+  }
+  if (code === "websearch_not_configured") {
+    return " Web search is not configured on this platform yet (no active search provider); tell the user instead of retrying.";
+  }
+  if (code === "websearch_quota_exceeded") {
+    return " The daily web-search quota for this account is exhausted; retry after the daily reset (UTC+8).";
+  }
+  if (code === "rate_limited") {
+    return " Too many requests right now; wait briefly before retrying.";
+  }
+  if (code === "insufficient_balance") {
+    return " The app account balance is insufficient; the app developer needs to top up.";
+  }
+  if (code === "upstream_error") {
+    return " All search providers failed for this request (nothing was billed); a later retry may succeed.";
+  }
+  return "";
+}
+function createWebSearchTool2(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const token = options.token;
+  return {
+    name: "PlatformWebSearch",
+    description: "Searches the web via the tansr platform (ring-3 hosted capability; the platform calls a managed search provider pool and bills the app per call). Returns a numbered list of results with title, URL and snippet. Requires the app to have the webSearch platform capability enabled.",
+    shortDescription: "Search the web via the tansr platform (billed per call). Args: query, max_results?.",
+    inputSchema: WebSearchArgsSchema2,
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    async execute(args, ctx) {
+      if (ctx.signal.aborted) {
+        return errorResult15("Tool execution was aborted.", args.query);
+      }
+      const payload = {
+        query: args.query,
+        ...args.max_results !== void 0 ? { max_results: args.max_results } : {}
+      };
+      let response;
+      try {
+        response = await fetchImpl(`${base}/t1/websearch`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+            [HEADER_APP_TOKEN]: token
+          },
+          body: JSON.stringify(payload),
+          signal: ctx.signal
+        });
+      } catch (err) {
+        if (ctx.signal.aborted) return errorResult15("Tool execution was aborted.", args.query);
+        const message = err instanceof Error ? err.message : String(err);
+        return errorResult15(`Web search request failed to reach the platform: ${message}`, args.query);
+      }
+      let raw = null;
+      try {
+        raw = await response.json();
+      } catch {
+        raw = null;
+      }
+      if (!response.ok) {
+        const envelope = raw ?? {};
+        const code = typeof envelope.error?.code === "string" ? envelope.error.code : `http_${response.status}`;
+        const message = typeof envelope.error?.message === "string" ? envelope.error.message : "request rejected";
+        return errorResult15(`Web search failed (${code}): ${message}.${hintOf3(code)}`, args.query, code);
+      }
+      const body = raw ?? {};
+      if (!Array.isArray(body.results)) {
+        return errorResult15("Web search returned an unexpected platform response (no results array).", args.query);
+      }
+      const results = body.results.map((item) => {
+        const row = item ?? {};
+        if (typeof row.title !== "string" || typeof row.url !== "string") return null;
+        return {
+          title: row.title,
+          url: row.url,
+          snippet: typeof row.snippet === "string" ? row.snippet : ""
+        };
+      }).filter((item) => item !== null);
+      const data = { query: args.query, results, resultCount: results.length };
+      if (results.length === 0) {
+        return { content: [{ t: "text", text: "Web search returned no results for this query (the call was still billed)." }], data };
+      }
+      const lines = [
+        `Web search returned ${results.length} result(s) (billed per call):`,
+        ...results.map((item, i) => {
+          const block = [`${i + 1}. ${item.title}`, `   ${item.url}`];
+          if (item.snippet !== "") block.push(`   ${item.snippet}`);
+          return block.join("\n");
+        })
+      ];
+      return { content: [{ t: "text", text: lines.join("\n") }], data };
+    }
+  };
+}
+
 // src/toolset.ts
 var BUILTIN_ORDER = [
   "read",
@@ -30681,7 +30798,6 @@ function buildSdkToolSet(options = {}) {
   validateCustomSelection(selection.custom, capabilities);
   const platformTools = [];
   for (const name of platformNames) {
-    if (name !== "imageGen" && name !== "videoGen") continue;
     const pc = options.platformContext;
     if (pc === void 0) {
       throw new TansrSdkError(
@@ -30694,7 +30810,9 @@ function buildSdkToolSet(options = {}) {
       token: pc.token,
       ...pc.fetchImpl !== void 0 ? { fetchImpl: pc.fetchImpl } : {}
     };
-    platformTools.push(name === "imageGen" ? createImageGenTool(materials) : createVideoGenTool(materials));
+    platformTools.push(
+      name === "imageGen" ? createImageGenTool(materials) : name === "videoGen" ? createVideoGenTool(materials) : createWebSearchTool2(materials)
+    );
   }
   const store = options.store ?? new TodoStore();
   const channel = options.promptChannel ?? new UnavailableChannel();
@@ -32490,6 +32608,8 @@ export {
   UnavailableChannel,
   VIDEOGEN_TOOL_MAX_DURATION,
   VideoGenArgsSchema,
+  WEBSEARCH_TOOL_MAX_RESULTS,
+  WebSearchArgsSchema2 as WebSearchArgsSchema,
   accumulateUsage,
   appBundleRegistryConfig,
   appendUserMessage,
@@ -32510,6 +32630,7 @@ export {
   createSession,
   createSessionView,
   createVideoGenTool,
+  createWebSearchTool2 as createWebSearchTool,
   defineSkill,
   defineTool,
   initialSessionViewState,

package/package.json

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