@tansr/serve 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tansr (tansr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# tansr agent session server
+
+> **对外发布名 = `@tansr/serve`(用户拍板 2026-09-01)**。workspace 内恒以
+> `@tansr/server` 引用;发布 tarball 由 `pnpm release:pack-serve` 盖发布名。
+> **license = MIT**(同批拍板;正式协议考察待全部开发完成后进行)。
+
+tansr **Agent 会话服务**的 `/v2` 协议引擎 + **内置真平台装配**(A 案,用户
+拍板 2026-09-01),以 npm 包形态嵌进**你自己的 Node 服务**。wire 契约权威 =
+doc/98(Agent 会话服务 v2 契约冻结件)。
+
+引擎负责传输与协议机器:11 个 `/v2` 端点路由、SSE 编帧与逐会话事件环形缓冲、
+`Last-Event-ID` 重放、三类桥回执受理(工具/权限/提问)、多会话治理(保留窗/
+闲置回收/并发帽)、轮末出站 webhook 通知。**会话鉴权完全归你**:引擎只暴露
+`authenticate` 注入缝,token 形制/签发/校验由你的登录态体系全权自定
+(最大放权)——引擎恒不规定、恒不内置任何 token 服务。
+
+**真装配内置**:`createAgentSessionFactory({ platform })` 四行接通 tansr
+平台——appid/appkey → per-endUser `app_user` 令牌(`POST /v1/app-tokens`,
+TWP 签名)→ bundle registry 模型装配 → 内核查询环真调模型,计费按 endUser
+归因;不用自写 Agent、不依赖任何 tansr 私有仓。
+
+## 安装
+
+```bash
+npm install @tansr/serve
+```
+
+运行时要求:Node ≥ 22.19。唯一第三方依赖 `zod` 随包解析;tansr 内部包
+(`@tansr/protocol`、`@tansr/i18n`、`@tansr/kernel`、`@tansr/providers`、
+`@tansr/sdk`)已编译内联,恒不外泄安装面。
+
+## 集成骨架
+
+```ts
+import { createAgentSessionFactory, registerBuiltinLocales, startServer } from '@tansr/serve';
+import type { AgentSessionsOptions } from '@tansr/serve';
+
+registerBuiltinLocales(); // 可选:错误体文案本地化(不注册则回落键名)
+
+// ② 真装配(内置,A 案):appid/appkey → per-endUser 令牌 → 内核查询环。
+//    也可换成你自实现的 AgentSessionFactory(注入形,契约同形)。
+const build = createAgentSessionFactory({
+  platform: {
+    apiBaseUrl: 'https://api.tansr.com',
+    appId: process.env.TANSR_APP_KEY_ID!,  // 平台控制台签发
+    appKey: process.env.TANSR_APP_KEY!,    // 恒不下发端、恒不入日志
+  },
+  cwd: process.cwd(),
+});
+
+const v2: AgentSessionsOptions = {
+  // ① 鉴权缝(唯一鉴权面):你的登录态 → endUserId;null = 401。
+  //    token 形制自定——自家 JWT/session cookie/OAuth/API key 皆可。
+  authenticate: async (req) => {
+    const user = await myAuth.verify(req.headers['authorization']);
+    return user ? { endUserId: user.id } : null;
+  },
+  createSession: build.factory,
+  // ③ 可选:SessionStore 读面(resume/列表)、治理参数、轮末 webhook 缝
+  // store, governance, onTurnEndNotify, ...
+};
+
+const server = await startServer({
+  port: 8787,
+  host: '127.0.0.1',
+  token: myV1Token, // /v1 面 Bearer(与 /v2 鉴权互不相通)
+  createSession: myV1Factory,
+  version: '1.0.0',
+  v2,
+});
+```
+
+平台内置形当前工具面为最小集(TodoWrite/AskUser + 逐会话远程工具三桥);
+`profile`/`budget` 请求位暂不支持(带上会 400 明告,候后续版本)。一体式
+可跑示例见仓内 `examples/serve-demo/agent-real.ts`。
+
+## 三层鉴权定盘(架构拍板 2026-08-31)
+
+| 层 | 凭据 | 归属 |
+|---|---|---|
+| sdk ↔ serve(会话面) | 你自定的登录态/token | **完全开发者侧**;引擎只经 `authenticate` 缝取 `endUserId` |
+| serve ↔ api(引擎上游) | `appid` + `appkey`(平台「应用」颁发) | serve 持有;以 appkey 换 per-endUser `app_user` 令牌供内部 harness 调模型,endUser 计费归因 |
+| sdk 持 `appid` | 公开应用标识(client_id 语义) | 可下发端亮明身份;恒非凭据 |
+
+红线:`appkey` 恒不下发端;`app_user` 令牌恒不出 serve;`/v2` 恒不受理 `/v1`
+Bearer。会话 id 恒非鉴权因子(逐端点归属校验独立成立,跨租 403/404)。
+
+## 推送唤醒 webhook 缝(轮末出站通知;doc/98 §五-5.4,A4-2/D5)
+
+移动端 App 退后台、SSE 断开后,轮跑完了怎么唤醒用户?**引擎恒不内置推送
+通道(FCM/厂商通道由你自接,D5 终拍:SDK 与 serve 恒不内置)**,只留一条
+webhook 缝:`AgentSessionsOptions.onTurnEndNotify` 在场时,会话**轮终局
+(turn.completed / turn.aborted)且该刻无活跃 SSE 订阅者**才向你的 URL
+POST 一份最小载荷(有订阅者 = 客户端在线,恒不发;同轮恒一发,防抖)。
+
+```ts
+const v2: AgentSessionsOptions = {
+  // ...authenticate / createSession...
+  onTurnEndNotify: {
+    url: 'https://your-service.example/tansr/turn-end',
+    secret: process.env.NOTIFY_SECRET, // 可选:HMAC-SHA256 对原始体全文签名
+  },
+};
+```
+
+- **载荷**(`TurnEndNotifyPayload` 冻结形,恒不携消息内容恒不携凭据):
+  `{ sessionId, endUserId, turnId?, status: 'completed'|'aborted', lastSeq, ts }`
+  ——`lastSeq` 供客户端持水位比对判断是否需要重放追赶,`ts` 供弃过期/防重放;
+- **签名**:`secret` 在场时携 `x-tansr-signature: sha256=<hex>`
+  (`TURN_END_NOTIFY_SIGNATURE_HEADER`),对原始请求体全文 HMAC-SHA256——
+  接收端先验签再消费;
+- **投递纪律**:fire-and-forget 恒不阻断会话主链;2xx 即成功,否则指数退避
+  重试(缺省 1+2 次,`V2_LIMITS.notifyMaxRetries/notifyTimeoutMs/notifyBackoffMs`
+  可覆写);终败走 `onDeliveryFailure` 结构化通报;服务器优雅关闭期恒不出站;
+- **收到通知后**:你的服务自行走 FCM/厂商推送叫醒 App;App 回连
+  `GET /v2/sessions/:id/events` 带 `Last-Event-ID` 断点续传,窗口外走
+  history/resume 恢复链。
+
+## 主要出口
+
+- `startServer(options)` / `StartServerOptions`(`v2?: AgentSessionsOptions`;
+  v2 缺席 = `/v2` 面零暴露);
+- `AgentSessionsOptions`:`authenticate`(唯一鉴权缝)、`createSession`
+  (`AgentSessionFactory`)、`store`(`AgentStoreReader`)、`governance`、
+  `mediaMaxBodyBytes`、`onTurnEndNotify`;
+- **真装配面(A 案,2026-09-01)**:`createAgentSessionFactory`
+  (`platform` 内置形 / `factory` 注入形)、`createPlatformServeSessionFactory`、
+  `createAppTokenMinter` / `createPlatformSessionAssembler`(铸令牌与
+  per-endUser 装配缝)、`createServeAgentSessionStore`(轮粒度持久 store)、
+  `ServeSessionDriver` / `AgentSessionBridge` / `buildRemoteTool` 及契约类型族
+  (`ServeSessionFactory` / `ServeSessionExtras` / `AssembledSessionModel` 等);
+- 契约持份:`V2_LIMITS` / `V2_ERROR_CODE` / `CONTROL_FRAME` /
+  `AGENT_SESSION_CONTRACT_VERSION` / 请求体 zod schema 族 / 控制帧载荷类型;
+- SSE 机器:`encodeSseFrame` / `encodeAgentStreamFrame` / `EventRingBuffer`;
+- 轮末通知:`TurnEndNotifier` / `TURN_END_NOTIFY_SIGNATURE_HEADER`;
+- i18n 便携面:`registerBuiltinLocales` / `setLocale` / `negotiateLocale`。
+
+## 发布形态
+
+- 双态 exports:开发态 `src/index.ts`(workspace tsx 直消费);发布态
+  `publishConfig` 三键覆盖指 `dist`(`pnpm pack` 应用);
+- `build.mjs`(S-D1 内联范式):esbuild 内联 `@tansr/protocol`/`@tansr/i18n`/
+  `@tansr/kernel`/`@tansr/providers`/`@tansr/sdk` → `dist/index.js`
+  (含 createRequire 垫片治内联 CJS 依赖);tsc + rollup-plugin-dts 卷积 →
+  `dist/index.d.ts`;产物守卫拒任何 `@tansr/*` 残留;
+- `pnpm release:pack-serve`:pack 窗口盖发布名 `@tansr/serve` + 剔内部
+  devDeps,打包后守卫复检 manifest/依赖面/文件表/license(MIT + LICENSE 件
+  版权行 Tansr)+ **⑥真装配出口断言**(动态 import 验三出口可调 + wire/d.ts
+  锚);发布动作恒候用户口令。