@tansr/serve 0.8.0 → 0.9.0

package/README.md

@@ -32,6 +32,44 @@ npm install @tansr/serve
 (`@tansr/protocol`、`@tansr/i18n`、`@tansr/kernel`、`@tansr/providers`、
 `@tansr/sdk`)已编译内联,恒不外泄安装面。
 
+## 系统媒体工具 / System media tools
+
+图像生成、视频生成、语音转文字和文字转语音均由内核系统工具执行，工具名为
+`ImageGen`、`VideoGen`、`SpeechToText`、`TextToSpeech`。平台内置会话工厂根据应用能力
+装配它们，并使用 SDK 的平台提供方调用授权模型；`capabilities.platform` 表示平台服务
+授权，不表示独立的“平台工具”类别。平台令牌、模型权限、配额、计费及运行时权限继续生效。
+
+Android/iOS 经 `/v2` 会话连接时，模型与系统媒体工具运行在开发者的 serve 进程中，
+手机负责提交输入和展示真实工具事件/媒体产物，不因此取得服务端文件或终端命令权限。
+用户主动录音转写、朗读使用既有音频直连端点；它们与模型调用媒体工具并存，不自动进入聊天历史。
+SDK 进程内集成仍须通过 `tools.builtin` 显式选择四媒体；这与 serve 平台工厂按应用授权装配的入口不同。
+
+Image generation, video generation, transcription, and speech synthesis are built-in system tools.
+The platform session factory assembles the authorized tools with platform-backed providers.
+`capabilities.platform` retains its service-authorization meaning. On Android and iOS, these tools
+run in the serve process; the mobile client renders their events and artifacts. User-triggered audio
+operations use the separate direct endpoints and do not fabricate model tool events or chat history.
+
+## 会话元数据与开发者登录
+
+新构建的 `GET /v2/sessions/:id` 可返回可选的 `meta.context` 和 `meta.media`。
+前者区分下一轮/执行轮模型、真实观测用量及本地上下文预算；后者列出四类媒体的应用授权、
+模型与限制、采样时间。字段缺席表示未知，客户端不能拿累计 token 用量当作当前上下文占用。
+媒体快照是会话装配时的授权目录，实际工具是否装配及执行权限仍以服务端执行为准。
+这次没有增加 HTTP 切模端点，也没有修改已冻结的内核事件协议。
+
+`countSpeechCharacters`、`planSpeechInput` 和相关类型从本包公开导出，用于按授权模型的
+`maxChars` 校验或显式分段朗读；示例遇到尚无新出口的已发布包时会提示升级。
+开发者登录服务与平台 app_user 分离：客户端向开发者的 login/refresh 入口取短效访问票，
+serve 的 `authenticate` 验证该票并返回 endUserId，平台 appkey 始终只留在服务端。
+完整远程示例见 `examples/serve-demo`；有界续期不会自动重放音频或聊天 POST。
+
+New builds may include optional `meta.context` and `meta.media` in session metadata. Missing fields
+mean unknown. Context estimates and observed billing usage are separate; the media catalog reflects
+the session's assembly-time authorization. Developer login and refresh credentials remain separate
+from platform app_user tokens. The public speech planner uses the authorized model's limit and explicit
+segmentation; authentication recovery never automatically replays paid POST requests.
+
 ## 集成骨架
 
 ```ts
@@ -183,18 +221,24 @@ SSE 连接 reset、在飞轮丢、无收口日志。
 (`sse.drainRetryMs`,缺省 10 s,客户端换台后再连);② **等在飞轮**——`/v2` 运行中的
 轮至多等 `timeoutMs` 到终态,到点剩余 `interrupt()`(轮末 store 提交照走,resume 可
 续);③ **flush 落盘**——等全部 fire-and-forget 的 store 提交/建行 settle
-(`createAgentSessionFactory` 的 `flush`);④ **停机**——终结会话、停监听、掐空闲连接、
+(`createAgentSessionFactory` 的 `flush`);④ **停机**——终结会话(**有界**:在飞 pump 至多等
+`closeAllTimeoutMs`,缺省 5 s、`Infinity` 无界;到点记 `server.close_timeout{face,pending,timeoutMs}`
+后照常继续,永不 settle 的 pump 不再能挂住停机;RF-03)、停监听、掐空闲连接、
 有界等待在飞非 SSE 请求答完(≤ 5 s)再掐残余连接。回执
 `{ completedTurns, abortedTurns, flushedCommits, durationMs }` 可入日志。
 `server.close()` 保持**硬收口**语义(立即中止在飞轮、不等落盘;drain 进行中调用则等
 drain 完成);`/v1` 会话无粗态读面,drain 不等其在飞轮。
 
-最小接线——两枚信号共用一个 handler,幂等位防重复进入:
+最小接线——两枚信号共用一个 handler,幂等位防重复进入;**第二枚信号不要吞掉**,应立即硬退
+(运维按两次 Ctrl+C / 两次 SIGTERM 强停的习惯,吞掉 = 只能等编排器 SIGKILL):
 
 ```ts
 let stopping = false;
 const shutdown = (signal: NodeJS.Signals): void => {
-  if (stopping) return;
+  if (stopping) {
+    console.error(`[my-service] ${signal} received again, exiting now`);
+    process.exit(2);
+  }
   stopping = true;
   console.error(`[my-service] ${signal} received, draining...`);
   server
@@ -222,10 +266,16 @@ process.on('SIGINT', shutdown);
 - **信号要能到达 node**:容器 `CMD`/`ENTRYPOINT` 用 exec 形(JSON 数组)或
   `--init`(tini 作 PID 1 转发),不要 `sh -c "node …"`(sh 当 PID 1 不转发);
 - **退出码由你定**:引擎恒不调 `process.exit`;示例里 `drain()` 成功 `exit(0)`、
-  失败 `exit(1)`,与你的进程监督器约定一致即可;`tansr serve`(CLI 形态)同走
-  drain,超时经 `TANSR_SERVE_DRAIN_TIMEOUT_MS` 可配(缺省 30 s);
-- **Windows 注记**:`process.on('SIGTERM')` 可注册但系统不会发出;本机开发以
-  Ctrl+C(SIGINT)收束,Linux/容器上两枚都会到;
+  失败 `exit(1)`,与你的进程监督器约定一致即可;`tansr serve`(CLI 形态)订阅
+  SIGINT / SIGTERM / SIGHUP / SIGBREAK,首枚同走 drain(超时经 `TANSR_SERVE_DRAIN_TIMEOUT_MS`
+  可配,缺省 30 s),**第二枚立即 `exit(2)`**,整链 drain 超时 + 15 s 未收口亦 `exit(2)`,
+  两者都记 `process.hard_exit{signal,reason,budgetMs,elapsedMs,exitCode}`(RF-03;共享组件
+  `packages/cli/src/assembly/process-lifecycle.ts`);CLI 形态另把每轮墙钟缺省定为
+  `maxTurnWallClockMs = 1800000`(30 min;`TANSR_SERVE_TURN_WALL_CLOCK_MS=0` 停用;审查 #9)——
+  库缺省仍不设,嵌入宿主自行决定;
+- **Windows 注记**:`process.on('SIGTERM')` 可注册但系统不会发出、`taskkill /F` 不发任何信号;
+  控制台关闭以 SIGHUP 到达且系统只留约 10 s(CLI 形态对 SIGHUP 收口预算恒 ≤ 3 s);SIGBREAK
+  (Ctrl+Break)与 SIGINT 同义。本机开发以 Ctrl+C(SIGINT)收束,Linux/容器上 SIGTERM / SIGHUP 都会到;
 - **与 `onTurnEndNotify` 的关系**:优雅关闭期出站通知恒不发(见上文投递纪律),
   客户端靠回连 `Last-Event-ID` / history / resume 追赶。
 - **进程级兜底(十王修案 FX-C-02)**:引擎恒不替你挂 `unhandledRejection` / `uncaughtException`
@@ -283,7 +333,7 @@ doc/130 R-12 生成律:`pnpm env:example` 再生、`pnpm docs:check` 幂等门;
 <!-- env:begin -->
 <!-- 由 packages/server/src/runtime-options.ts 的 SERVE_RUNTIME_ENV 表生成(FX-C-41):`pnpm env:example` 再生,`pnpm docs:check` 幂等门;手改本区段会被门打回 -->
 
-全表 **30 键**(键序 = 表声明序;缺席 / 空串 = 库缺省,非法值忽略并告警):
+全表 **31 键**(键序 = 表声明序;缺席 / 空串 = 库缺省,非法值忽略并告警):
 
 | 变量 | 组 | 目标选项 | 形态 | 约束 | 单位 |
 |---|---|---|---|---|---|
@@ -308,6 +358,7 @@ doc/130 R-12 生成律:`pnpm env:example` 再生、`pnpm docs:check` 幂等门;
 | `TANSR_SERVE_UPSTREAM_IDLE_TIMEOUT_MS` | `session` | `session.timeouts.idleTimeoutMs` | int | integer >= 1 | ms |
 | `TANSR_SERVE_UPSTREAM_TOTAL_TIMEOUT_MS` | `session` | `session.timeouts.totalTimeoutMs` | int | integer >= 1 | ms |
 | `TANSR_SERVE_TURN_WALL_CLOCK_MS` | `session` | `session.maxTurnWallClockMs` | int | integer >= 1 | ms |
+| `TANSR_SERVE_HOST_SHELL` | `session` | `session.hostShell` | enum | posix\|powershell | — |
 | `TANSR_SERVE_SSE_MAX_BUFFER_BYTES` | `sse` | `sse.maxBufferBytes` | int | integer >= 1 | bytes |
 | `TANSR_SERVE_SSE_SLOW_POLICY` | `sse` | `sse.onSlowSubscriber` | enum | disconnect\|drop-oldest | — |
 | `TANSR_SERVE_SSE_RETRY_MS` | `sse` | `sse.retryMs` | int | integer >= 0 | ms |
@@ -318,7 +369,7 @@ doc/130 R-12 生成律:`pnpm env:example` 再生、`pnpm docs:check` 幂等门;
 | `TANSR_SERVE_SESSION_MAX_AGE_DAYS` | `factory` | `factory.sessions.retention.maxAgeDays` | int | integer >= 1 | days |
 | `TANSR_SERVE_SESSION_MAX_PER_END_USER` | `factory` | `factory.sessions.retention.maxPerEndUser` | int | integer >= 1 | — |
 
-分组:`admission`(4) / `http`(1) / `observability`(2) / `ring`(1) / `governance`(5) / `v2`(1) / `notify`(2) / `upstream`(1) / `session`(4) / `sse`(3) / `log`(1) / `process`(2) / `factory`(3)。同表生成的部署样例:`packages/server/.env.example`。
+分组:`admission`(4) / `http`(1) / `observability`(2) / `ring`(1) / `governance`(5) / `v2`(1) / `notify`(2) / `upstream`(1) / `session`(5) / `sse`(3) / `log`(1) / `process`(2) / `factory`(3)。同表生成的部署样例:`packages/server/.env.example`。
 <!-- env:end -->
 
 `factory` 组三键语义(表内只列形态与约束):`TANSR_SERVE_CWD_ON_RESUME=current|stored` → `cwdOnResume`,
@@ -586,7 +637,7 @@ build.upstreamStats?.();           // { tokenMinter: { inflight, queued, mints,
   同批铸出的令牌不再同刻进入刷新窗;某 endUser 铸造失败后窗内不再出网(直接回同一错),
   刷新失败但旧令牌仍在时效内直接沿用旧令牌;`warm(endUserIds)` 可在启动期预热。
 - **令牌失效反馈(十王修案 FX-C-15 / R-02)**:平台对携 `x-tansr-app-token` 的请求(模型 exchange / bundle /
-  平台工具)回 `401 { error: { code: 'unauthorized', detail: { reason } } }` 时,刷新 fetch 在**同一请求内**
+  系统工具的平台提供方)回 `401 { error: { code: 'unauthorized', detail: { reason } } }` 时,刷新 fetch 在**同一请求内**
   `minter.invalidate`(仅当缓存现值仍是本次所携令牌)→ 重铸 → 重发**恰一次**;重试仍 401 则原样交回(每请求至多
   一次重铸,恒不循环)。`reason === 'check_unavailable'`(平台校验依赖瞬态不可用)不失效、不重铸;其余码 /
   403 / 无信封亦不触发。此前吊销令牌后 serve 拿旧令牌 ≈ 55 min 恒 401。计数:`stats().invalidations{reason}`