@tansr/serve 0.8.1 → 0.9.0

package/README.md

@@ -50,6 +50,26 @@ The platform session factory assembles the authorized tools with platform-backed
 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
@@ -201,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
@@ -240,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`
@@ -301,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 键**(键序 = 表声明序;缺席 / 空串 = 库缺省,非法值忽略并告警):
 
 | 变量 | 组 | 目标选项 | 形态 | 约束 | 单位 |
 |---|---|---|---|---|---|
@@ -326,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 |
@@ -336,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`,