@tansr/sdk 0.11.0 → 0.13.0

package/NOTICE

@@ -0,0 +1,18 @@
+NOTICE — @tansr/sdk
+===================
+
+Generated by `pnpm release:verify-notice --write --package sdk` (tansr FX-C-29, inline-declaration rule).
+Do not edit by hand: `pnpm release:verify-notice --check` regenerates this file from the esbuild metafile and fails
+on any difference. Every third-party package compiled into the shipped bundle is listed below, no more and no less;
+each must carry an allow-listed license. Humans review the license column; the machine keeps the table honest.
+
+Artifacts covered: dist/index.js
+Runtime dependencies resolved from the consumer's node_modules (declared, not bundled): @vscode/ripgrep, undici, zod, zod-to-json-schema
+Bundled third-party packages: 0
+
+BUNDLED THIRD-PARTY PACKAGES
+----------------------------
+(none — this bundle inlines no third-party code)
+
+LICENSE TEXTS
+-------------

package/README.md

@@ -29,6 +29,25 @@ for await (const event of session.events) {
 
 模型目录与能力位由平台 App 配置(控制台治理)自动下发,本地零配置。
 
+## 应用系统提示词（AP-SP）
+
+平台管理 API 的 `systemPrompt` 是应用业务角色，`systemPromptPolicy` 控制与 SDK `system` 的关系：
+
+| 平台策略 | 未传 system | system 有内容 | system: [] |
+| --- | --- | --- | --- |
+| fallback（默认） | 平台 P | SDK S | 无业务段 |
+| prepend（保留） | 平台 P | P → S | 平台 P |
+
+平台正文未配置时，仅使用 SDK 段。`systemAppend` 在业务段选定后追加宿主使用指南，不触发覆盖；工具、Skills、MCP 指南仍按已装配能力追加。不要把平台正文再复制进 SDK 参数。`session.applicationPrompt` 提供实际装配的只读 `source`／`policy`，不包含正文。
+
+`PUT /v1/apps/{appId}/config` 写入 `{ systemPrompt, systemPromptPolicy }`，`GET /v1/apps/{appId}` 的 `config` 回读；组织管理另传 `x-tansr-org`。正文最多 16000 Unicode 码点，null／空白清空；策略不接受 null，字段缺席均保留。
+
+P 和 S 同为模型 system 输入，拼接次序不保证冲突指令谁胜出。平台适合公共角色集中维护，SDK 适合动态或版本化场景；有矛盾应修改正文或选择 fallback。权限／裁决／额度不靠提示词强制，正文不能存密钥。
+
+已有令牌档会话在下一新轮前自动核验平台 P／策略，不需重建。每轮 ETag 条件请求绕过装配缓存，工具多步保持同轮快照；先应用新段再计算上下文预算。失败发 application_prompt_refresh_failed 并中止本轮，保留历史、可原会话重试；预检30秒上限且可取消。宿主 S/A、模型和工具权限仍沿原装配生命周期。BYOK／注入 client 不读平台默认，runAgent 需宿主显式调用 resolveApplicationSystem。
+
+完整三档 SDK、Windows Electron、serve、Android／iOS 示例见[提示词指南](https://docs.tansr.com/sdk/system-prompts/)与仓内 doc/90 §4.12。此能力仍须发布包含 AP-SP 的 API 与 SDK／serve，旧版本不识别保留策略。
+
 ## 三档 API × 三档模型来源
 
 | API | 形态 | 适用 |
@@ -67,15 +86,41 @@ for await (const event of session.events) {
   `createSession({ thinking: { budget } })` + `session.setThinking(…)`(下一轮生效),
   与呈现档正交(详见手册 §9.1);
 - **权限**:`permission: { mode?, rules?, askUser? }`——ask 裁决桥到你的 UI,缺席
-  fail-closed 降级 deny;
+  fail-closed 降级 deny;令牌档缺省装配控制台任命的**裁决人**(`adjudication?: { posture?, callBudget?,
+  enabled?, endUser? }`,模式由 kernel 按姿态 × 资格档推导):显式 `permission.mode` 即视为自管模式——
+  裁决人不装并通报 `adjudicator_skipped_by_mode`(0.12 兼容径);**例外**:显式 `adjudication: { … }`
+  与 `permission.mode` 同现即 throw `invalid_options`(真矛盾,fail-fast),静默自管请传
+  `adjudication: { enabled: false }`;变更登记见 `CHANGELOG.md`;
 - **计量**:`cost.usage.updated` 逐请求;终端自查 `/v1/my-usage` 恒无金额字段,
   开发者对账 `/v1/app-usage/by-end-user` 含金额(恒不代理给终端)。
 
-能力位(17 工具位 + 3 平台位)在平台控制台按 App 配置;位关而显式选择恒得到装配期
-可读错(`capability_disabled`,含修复指引),恒不静默缺工具。
+能力位(17 工具位 + 5 平台位:webSearch / imageGen / videoGen / speechToText / textToSpeech,
+`CAPABILITY_TOOL_KEYS` / `CAPABILITY_PLATFORM_KEYS` 为事实源)在平台控制台按 App 配置;位关而显式
+选择恒得到装配期可读错(`capability_disabled`,含修复指引),恒不静默缺工具。
 
 ## 文档与示例
 
+### 可等待生命周期（ARC-07，当前源码能力，待配套发布）
+
+`idle()`、`close()`、`session.ended` 维持原有业务语义；它们不证明异步存储、生成器的 `finally` 或 MCP 传输已经完成。离开页面或退出应用时，检查新的回执：
+
+```ts
+const result = await session.closeAsync({ timeoutMs: 30_000, flushStore: true });
+if (result.status !== 'completed') {
+  // 保留 session；显示状态/数量即可，不把原始 cause 直接写日志或发给 renderer。
+  console.warn({ status: result.status, pending: result.pending, failureCount: result.failureCount });
+  // 稍后继续观察：await session.drain({ timeoutMs: 30_000 });
+}
+```
+
+`drain()` 不关闭会话；`closeAsync()` 先逻辑关闭再等待。超时或 `signal` 取消的是本次观察，底层清理继续，其他等待者不受影响。默认观察上限 30 秒，`0` 读取当前状态，`Infinity` 只用于宿主明确管理的真实依赖链。`flushStore` 缺省关闭；借用的 store 永不由 SDK 自动 `close()`。`retryPersistence: true` 显式重试待修复历史提交，不重放业务回调；不要在自己的 `onHistoryCommit` 内等待本会话的 `drain()`。
+
+会话内 `mcp: { servers }` 由 SDK 所有；传入应用级 `McpHost` 是借用。共享 host 必须等全部使用它的会话完成后，再由应用 `await host.dispose()`。`cleanupEvidence` 中 `transport-completion` 指本地传输完成层，第三方连接没有 `settleClose` 时只提供 `connector-close-promise`，不是任意操作系统子进程或 HTTP 远端退出证明。
+
+`query()` 提前 `break` 仍发送中止，并等待真实收尾到 `cleanupTimeoutMs`（默认 30 秒）。用 `onLifecycleError(error)` 保留 `SdkLifecycleError.cleanup`，随后可继续 `error.cleanup?.drain()`；消费者自己抛错时，JavaScript 可能优先保留消费者异常，因此第二条回调通道不可省略。托管／令牌档 `query` 现可显式传 `skills`、`mcp`，能力位及所有权规则与 `createSession` 相同；注入档仍不隐式装配工具或读取技能目录。
+
+完整规则见 `doc/90-SDK技术手册.md` §4.13。Electron 真正使用 `closeAsync`，外层 30 秒观察超时可再次等待；Android／iOS 继续现有 serve 会话协议，手机断线不等于删除会话，真实资源收尾由 Node 宿主负责。
+
 - **技术手册(完整)**:仓内 `doc/90-SDK技术手册.md`——安装、三方闭环令牌接入、三档
   API、能力位、defineTool/skills/MCP、渲染管道、权限、计量、imageGen、错误码排障、
   安全须知;

package/contract/MANIFEST.json

@@ -0,0 +1,66 @@
+{
+  "revision": 4,
+  "sha256": "c57ffb63c51fa37f84814857240785a1c1d433839a7d0e6ebcdedc419838597c",
+  "errorCodes": 38,
+  "eventTypes": 54,
+  "eventTypeNames": [
+    "agent.completed",
+    "agent.followup",
+    "agent.interrupted",
+    "agent.progress",
+    "agent.report",
+    "agent.settled",
+    "agent.spawned",
+    "cost.cache_miss",
+    "cost.model.mismatch",
+    "cost.provider.switched",
+    "cost.usage.updated",
+    "hook.blocked",
+    "hook.completed",
+    "hook.triggered",
+    "mcp.catalog_updated",
+    "mcp.closed",
+    "mcp.connect_failed",
+    "mcp.connected",
+    "mcp.discovered",
+    "mcp.elicitation_declined",
+    "mcp.reconnect_exhausted",
+    "mcp.reconnected",
+    "mcp.reconnecting",
+    "mcp.tool_skipped",
+    "msg.block.end",
+    "msg.block.start",
+    "msg.retracted",
+    "msg.text.delta",
+    "msg.thinking.delta",
+    "plan.todo.updated",
+    "session.checkpointed",
+    "session.compacted",
+    "session.created",
+    "session.cwd_changed",
+    "session.ended",
+    "session.forked",
+    "session.locale.changed",
+    "session.microcompacted",
+    "session.output_style.changed",
+    "session.restored",
+    "session.resumed",
+    "session.workspace_trust.changed",
+    "tool.completed",
+    "tool.failed",
+    "tool.output.delta",
+    "tool.permission.decided",
+    "tool.permission.requested",
+    "tool.progress",
+    "tool.proposed",
+    "tool.started",
+    "turn.aborted",
+    "turn.completed",
+    "turn.error",
+    "turn.started"
+  ],
+  "eventSchemaSha256": "ddc7afac50d2ff8980ebeab2d8b3089dd197623dc2a23049e76a0944fa15ef59",
+  "contractVersion": "v1",
+  "sourceCommit": "34a6f37e23036ce8aa7cccd67dbbbd40863d8544",
+  "generatedAt": "2026-09-10T02:55:26.356Z"
+}