@tansr/serve 0.3.2 → 0.5.0

package/dist/index.d.ts

@@ -4207,6 +4207,7 @@ declare const CONTROL_FRAME: {
     readonly permissionClosed: "server.permission.closed";
     readonly questionRequest: "server.question.request";
     readonly questionClosed: "server.question.closed";
+    readonly platformWarning: "server.platform.warning";
 };
 type ControlFrameName = (typeof CONTROL_FRAME)[keyof typeof CONTROL_FRAME];
 /** 判别一个流内条目是否控制帧(编码器/过滤器共用;gap 帧另路不经此判) */
@@ -4244,6 +4245,14 @@ interface PermissionRequestPayload {
 interface RequestClosedPayload {
     requestId: string;
 }
+/**
+ * server.platform.warning 载荷(平台 t.warn 同形投影;恒不代表请求失败,
+ * 回答照常——仅结构化告知非致命降级,呈现策略归端上)。
+ */
+interface PlatformWarningPayload {
+    code: string;
+    message: string;
+}
 /** server.question.request 载荷(kernel Question 白名单拷贝) */
 interface QuestionRequestPayload {
     requestId: string;
@@ -4259,7 +4268,7 @@ interface QuestionRequestPayload {
     /** 仅无订阅者宽限期激活时在场(epoch_ms) */
     expiresAt?: number;
 }
-type ControlFramePayload = ToolRequestPayload | ToolCancelPayload | PermissionRequestPayload | RequestClosedPayload | QuestionRequestPayload;
+type ControlFramePayload = ToolRequestPayload | ToolCancelPayload | PermissionRequestPayload | RequestClosedPayload | QuestionRequestPayload | PlatformWarningPayload;
 /** 出站通知 HMAC 签名头(值形 `sha256=<hex>`,对原始请求体全文签) */
 declare const TURN_END_NOTIFY_SIGNATURE_HEADER = "x-tansr-signature";
 /** 轮终局词表(KernelEvent turn.completed/turn.aborted 的投影) */
@@ -9825,6 +9834,71 @@ interface ServeSessionFactory extends SessionFactory {
     create(init: SessionInit, extras?: ServeSessionExtras): ServeSessionDriver;
 }
 
+interface CreateAppTokenMinterOptions {
+    /** 平台 API 基址(尾斜杠归一) */
+    apiBaseUrl: string;
+    /** 平台「应用」公开标识(= api_keys.public_id;AK 头) */
+    appId: string;
+    /** 平台「应用」主密钥(SK 头 + 签名钥派生;恒不出本闭包) */
+    appKey: string;
+    /** 换发令牌 TTL(秒;缺省 3600,契约边界 60–86400 钳制) */
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+interface AppTokenMinter {
+    /** 取 endUserId 的现值令牌(缓存命中直返;临期/缺席铸新,在飞去重) */
+    tokenFor(endUserId: string): Promise<string>;
+}
+/**
+ * per-endUser app_user 令牌铸造器:appkey 双头 + TWP 签名三头(providers
+ * 签名件原样复用)POST /v1/app-tokens;失败结构化上抛(状态码 + 平台错误
+ * 码,恒不携凭据与令牌本体)。
+ */
+declare function createAppTokenMinter(options: CreateAppTokenMinterOptions): AppTokenMinter;
+interface CreatePlatformSessionAssemblerOptions {
+    minter: AppTokenMinter;
+    /** 平台 API 基址(bundle 拉取与 twp 消费同基址) */
+    apiBaseUrl: string;
+    fetchImpl?: typeof fetch;
+    /**
+     * S-ARCH P2 — 平台提示帧承接(t.warn:thinking_unavailable_on_face/
+     * balance_low 等;SDK onPlatformWarning 同源语义)。缺席缺省 console.warn
+     * 每 (endUser, code) 一次(告知恒不静默蒸发);在场即全量接管。
+     * 注:向端上(/v2 SSE)转发需新控制帧,系 doc/98 冻结面增笔——候拍,
+     * 本缝先保证服务端可观测与宿主可编程。
+     */
+    onPlatformWarning?: (warning: {
+        endUserId: string;
+        sessionId: string;
+        code: string;
+        message: string;
+    }) => void;
+}
+interface PlatformSessionAssemblerInput {
+    endUserId: string;
+    sessionId: string;
+    /** 会话请求的模型别名(bundle aliases/目录 handle;缺省 'main') */
+    model?: string;
+    /**
+     * S-ARCH P2(拍板 2026-09-02)— per-会话传输沉降缝:平台提示帧除宿主
+     * 承接(options.onPlatformWarning)外,同帧投递本缝(工厂接 v2 控制帧
+     * server.platform.warning 下发端上)。两路并行不互斥。
+     */
+    onWarning?: (warning: {
+        code: string;
+        message: string;
+    }) => void;
+}
+/**
+ * per-endUser 平台令牌档装配缝实现(agent-session-factory
+ * assembleEndUserModel 消费):铸/取该 endUser 现值令牌 → SDK
+ * assemblePlatformModel(bundle → registry;per-会话平台 ULID 经既有
+ * twp sessionId 缝出线)→ 返回逐会话装配器(别名解析走 bundle registry;
+ * Task 三档降档同表)。刷新 fetch 覆写令牌头,跨时效长会话自续。
+ */
+declare function createPlatformSessionAssembler(options: CreatePlatformSessionAssemblerOptions): (input: PlatformSessionAssemblerInput) => Promise<SessionModelAssembler>;
+
 /**
  * A 案 — 平台内置形 serve 内层工厂(用户拍板 2026-09-01:真平台装配内置
  * 进 serve,做实五形态边界)。
@@ -9906,6 +9980,12 @@ interface PlatformAgentSessionOptions {
     maxTurnsPerQuery?: number;
     /** runQuery 注入缝(测试脚本化;透传平台内层工厂) */
     runQueryImpl?: Parameters<typeof createPlatformServeSessionFactory>[0]['runQueryImpl'];
+    /**
+     * S-ARCH P2 — 平台提示帧承接(t.warn;透传装配缝,语义同 SDK
+     * onPlatformWarning):缺席缺省 console.warn 每 (endUser, code) 一次。
+     * 向 /v2 端上转发需新控制帧(doc/98 冻结面增笔),候拍不代拍。
+     */
+    onPlatformWarning?: Parameters<typeof createPlatformSessionAssembler>[0]['onPlatformWarning'];
 }
 interface CreateAgentSessionFactoryOptions {
     /**
@@ -9941,6 +10021,11 @@ interface CreateAgentSessionFactoryOptions {
         endUserId: string;
         sessionId: string;
         model?: string;
+        /** S-ARCH P2:平台提示帧 per-会话沉降缝(工厂绑 v2 控制帧下发;自实现装配器可如实忽略) */
+        onWarning?: (warning: {
+            code: string;
+            message: string;
+        }) => void;
     }) => Promise<SessionModelAssembler>;
 }
 interface AgentSessionFactoryBuild {
@@ -9969,6 +10054,15 @@ declare class AgentSessionBridge {
     bindEmitter(emit: (type: string, payload: unknown) => void): void;
     /** 活跃 SSE 订阅者数通报(注册仓 → 句柄 → 本桥;提问宽限判据) */
     noteSubscribers(count: number): void;
+    /**
+     * S-ARCH P2(拍板 2026-09-02)— 平台提示帧下发:t.warn 投影为
+     * server.platform.warning 控制帧(带 id 进环形缓冲,断线重放可见;旧端
+     * 未知帧兜底恒安全)。emit 缝未绑定的窄窗(装配期恒无 warn)静默无害。
+     */
+    emitPlatformWarning(payload: {
+        code: string;
+        message: string;
+    }): void;
     /** 工具调用登记(RemoteToolProxy.execute 内部调用) */
     registerToolCall(callId: string, name: string, args: unknown, deadlineAt: number, signal: AbortSignal): Promise<ToolResult>;
     /** ⑨ 回执受理(第一份有效终局;重复 409 无害) */
@@ -10000,49 +10094,6 @@ interface RemoteToolBuild {
  */
 declare function buildRemoteTool(decl: ClientToolDecl, bridge: AgentSessionBridge, now?: () => number): RemoteToolBuild;
 
-interface CreateAppTokenMinterOptions {
-    /** 平台 API 基址(尾斜杠归一) */
-    apiBaseUrl: string;
-    /** 平台「应用」公开标识(= api_keys.public_id;AK 头) */
-    appId: string;
-    /** 平台「应用」主密钥(SK 头 + 签名钥派生;恒不出本闭包) */
-    appKey: string;
-    /** 换发令牌 TTL(秒;缺省 3600,契约边界 60–86400 钳制) */
-    ttlSeconds?: number;
-    fetchImpl?: typeof fetch;
-    now?: () => number;
-}
-interface AppTokenMinter {
-    /** 取 endUserId 的现值令牌(缓存命中直返;临期/缺席铸新,在飞去重) */
-    tokenFor(endUserId: string): Promise<string>;
-}
-/**
- * per-endUser app_user 令牌铸造器:appkey 双头 + TWP 签名三头(providers
- * 签名件原样复用)POST /v1/app-tokens;失败结构化上抛(状态码 + 平台错误
- * 码,恒不携凭据与令牌本体)。
- */
-declare function createAppTokenMinter(options: CreateAppTokenMinterOptions): AppTokenMinter;
-interface CreatePlatformSessionAssemblerOptions {
-    minter: AppTokenMinter;
-    /** 平台 API 基址(bundle 拉取与 twp 消费同基址) */
-    apiBaseUrl: string;
-    fetchImpl?: typeof fetch;
-}
-interface PlatformSessionAssemblerInput {
-    endUserId: string;
-    sessionId: string;
-    /** 会话请求的模型别名(bundle aliases/目录 handle;缺省 'main') */
-    model?: string;
-}
-/**
- * per-endUser 平台令牌档装配缝实现(agent-session-factory
- * assembleEndUserModel 消费):铸/取该 endUser 现值令牌 → SDK
- * assemblePlatformModel(bundle → registry;per-会话平台 ULID 经既有
- * twp sessionId 缝出线)→ 返回逐会话装配器(别名解析走 bundle registry;
- * Task 三档降档同表)。刷新 fetch 覆写令牌头,跨时效长会话自续。
- */
-declare function createPlatformSessionAssembler(options: CreatePlatformSessionAssemblerOptions): (input: PlatformSessionAssemblerInput) => Promise<SessionModelAssembler>;
-
 /**
  * /v2 装配半场 i18n 消息键(A 案下沉 2026-09-01)。
  *

package/dist/index.js

@@ -37889,7 +37889,12 @@ var CONTROL_FRAME = {
   permissionRequest: "server.permission.request",
   permissionClosed: "server.permission.closed",
   questionRequest: "server.question.request",
-  questionClosed: "server.question.closed"
+  questionClosed: "server.question.closed",
+  // S-ARCH P2(用户拍板 2026-09-02「同意」,doc/98 §三增笔四族七名):平台
+  // 提示帧下发端上——thinking_unavailable_on_face/balance_low 等非致命降级
+  // 结构化告知,端侧可渲染「为什么这次没有思考」;旧端未知帧兜底恒安全
+  // (Android UnknownControlFrame / iOS 同律实证)。
+  platformWarning: "server.platform.warning"
 };
 var CONTROL_FRAME_NAMES = new Set(Object.values(CONTROL_FRAME));
 function isControlFrameType(type) {
@@ -53944,6 +53949,14 @@ var AgentSessionBridge = class {
   #send(type, payload) {
     this.#emit?.(type, payload);
   }
+  /**
+   * S-ARCH P2(拍板 2026-09-02)— 平台提示帧下发:t.warn 投影为
+   * server.platform.warning 控制帧(带 id 进环形缓冲,断线重放可见;旧端
+   * 未知帧兜底恒安全)。emit 缝未绑定的窄窗(装配期恒无 warn)静默无害。
+   */
+  emitPlatformWarning(payload) {
+    this.#send(CONTROL_FRAME.platformWarning, payload);
+  }
   // ———— 工具桥半场(RemoteToolProxy 的登记/回执面)————
   /** 工具调用登记(RemoteToolProxy.execute 内部调用) */
   registerToolCall(callId, name, args, deadlineAt, signal) {
@@ -60630,7 +60643,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);
@@ -60713,6 +60727,13 @@ function createAppTokenMinter(options) {
   };
 }
 function createPlatformSessionAssembler(options) {
+  const warnedDefault = /* @__PURE__ */ new Set();
+  const deliverWarning = options.onPlatformWarning ?? ((w) => {
+    const key2 = `${w.endUserId}\0${w.code}`;
+    if (warnedDefault.has(key2)) return;
+    warnedDefault.add(key2);
+    console.warn(`[tansr-serve] platform warning ${w.code} (endUser=${w.endUserId}): ${w.message}`);
+  });
   return async (input) => {
     const initialToken = await options.minter.tokenFor(input.endUserId);
     const platformSessionId = ulid();
@@ -60729,7 +60750,19 @@ function createPlatformSessionAssembler(options) {
       baseUrl: options.apiBaseUrl,
       ...input.model !== void 0 ? { model: input.model } : {},
       fetchImpl: refreshingFetch,
-      sessionId: () => platformSessionId
+      sessionId: () => platformSessionId,
+      // S-ARCH P2:平台提示帧经 SDK onWarn 缝出线,携会话归属(serve 面
+      // per-会话装配,归属天然可判——CLI 进程级电台的「无从归属」不适用此径);
+      // 双路投递:宿主承接(遥测/日志)+ per-会话传输沉降(v2 控制帧)。
+      onWarn: (warn) => {
+        deliverWarning({
+          endUserId: input.endUserId,
+          sessionId: input.sessionId,
+          code: warn.code,
+          message: warn.message
+        });
+        input.onWarning?.({ code: warn.code, message: warn.message });
+      }
     });
     return (alias, onProviderSelected) => {
       const built = buildClientFromRegistry(platform.registry, alias, onProviderSelected);
@@ -61268,7 +61301,8 @@ function createAgentSessionFactory(options) {
     assembleEndUserModel = createPlatformSessionAssembler({
       minter,
       apiBaseUrl: platform.apiBaseUrl,
-      ...platform.fetchImpl !== void 0 ? { fetchImpl: platform.fetchImpl } : {}
+      ...platform.fetchImpl !== void 0 ? { fetchImpl: platform.fetchImpl } : {},
+      ...platform.onPlatformWarning !== void 0 ? { onPlatformWarning: platform.onPlatformWarning } : {}
     });
     innerFactory = createPlatformServeSessionFactory({
       cwd: options.cwd,
@@ -61356,7 +61390,10 @@ function createAgentSessionFactory(options) {
         assembleOverride = await assembleEndUserModel({
           endUserId: init.endUserId,
           sessionId,
-          ...init.model !== void 0 ? { model: init.model } : {}
+          ...init.model !== void 0 ? { model: init.model } : {},
+          // S-ARCH P2(拍板 2026-09-02):平台提示帧沉降 v2 控制帧
+          // server.platform.warning(桥 emit 缝绑定恒早于首轮,无丢失窗)
+          onWarning: (warning) => bridge.emitPlatformWarning(warning)
         });
       }
       let driver;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tansr/serve",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Tansr agent session server: the bare /v2 agent-session protocol engine (REST + SSE) you embed in your own Node service. Session auth is fully yours via the authenticate seam. Published as @tansr/serve (decided 2026-09-01); the pack script stamps the publish name into the tarball.",
   "license": "MIT",
   "type": "module",