create-windy 0.6.11 → 0.6.14

package/template/docs/platform/agent-runtime.md

@@ -1,325 +1,160 @@
-# Agent Runtime 接入与运行
-
-更新时间：2026-07-26。
-
-Windy 的 Agent Runtime 是可选平台能力。业务模块声明稳定的 AI Operation 和允许调用的
-Tool；Windy Server 负责身份、Feature、Permission、License、Scope、Execution
-Grant 与审计；独立 Agent Server 只负责模型循环、canonical event 和受限 Tool Host
-回调。业务模块不选择 Provider、模型、Endpoint 或凭据。
-
-## 当前可用边界
-
-- 真实业务 Run 使用 Google ADK 2.5 `Runner`、`InMemorySessionService`、`LlmAgent`
-  与 `Event`；ADK 类型只存在于 Python Adapter 内，外部 HTTP/SSE 契约不变。
-- OpenAI-compatible `/chat/completions` Provider，支持流式文本和 function calling。
-- `QWEN_API_KEY` 使用服务端 `SecretRef`，只在 Provider Adapter 发请求前解析。
-- 公网 Endpoint 必须为 HTTPS，并精确命中
-  `AI_PROVIDER_HTTPS_HOST_ALLOWLIST`；`localhost`、容器服务名、RFC 1918 地址和
-  `.internal`/`.local` 主机可使用 HTTP。URL 禁止内嵌凭据、query、fragment 和云
-  metadata 地址。
-- Provider 有连接/请求超时、响应大小上限、安全错误映射和 `/models` readiness 检查。
-- Run 支持幂等创建、canonical SSE、cursor/`Last-Event-ID` 重放、取消和唯一终态。
-- SQLite Store 为单副本有界持久化：默认最多 10,000 个 Run、每个 Run 2,000 个事件、
-  16 MiB 输出、终态保留 7 天。它不保存原始输入，只保存请求指纹；进程重启会把未完成
-  Run 收敛为一个可重试失败终态。
-
-SQLite 模式不能作为多副本共享 Store。需要水平扩容时，必须先提供实现同一 `RunStore`
-契约的外部持久化 Adapter。
-
-## Module 接入
-
-Manifest 的 `aiOperations` 是声明事实。每个 Operation 必须声明自己的 Feature、
-Permission、可选 Entitlement、输入/输出 schema 和 `allowedToolKeys`。模型只会收到该
-集合内的 Tool 定义。
-
-Provider 与 Tool 网络策略必须分开声明。旧 `publicNetworkAccess` 不会开启 Provider：
-
-```ts
-providerEgress: {
-  mode: "configured-endpoint",
-  deploymentKey: "ai.openai-compatible",
-},
-providerDataPolicy: {
-  inputFields: [
-    {
-      jsonPointer: "/content",
-      classification: "internal",
-      dlpAction: "redact",
-    },
-  ],
-  envelopeFields: [
-    {
-      field: "instructions",
-      classification: "internal",
-      dlpAction: "reject",
-    },
-    {
-      field: "user-prompt",
-      classification: "internal",
-      dlpAction: "redact",
-    },
-  ],
-},
-toolNetworkPolicy: {
-  mode: "forbidden",
-},
-```
+# Agent Runtime 接入
+
+## 当前基线
+
+Windy 的服务端 Agent Runtime 由独立 Python Agent Server 承载，生产默认 Engine 是
+`OpenAiCompatibleEngineAdapter`。它直接把 Windy 类型化 Operation、模型轮次和 Tool Host
+组合成受治理 Loop，不依赖第三方 Agent 框架。
+
+外部只依赖 canonical 契约：
 
-Provider URL 与 Secret 不在 Manifest 或浏览器 DTO 中；Server 只把 `inputFields`
-选出的治理后输入交给 Handler，Agent Server 只允许当前启动
-配置的 Deployment。Tool policy 缺省为 forbidden，且不继承 Provider egress。完整
-威胁模型、兼容行为与尚未覆盖项见
-[Agent Provider 与 Tool 网络边界](../architecture/ai-egress.md)。
-
-模块在 `setup(host)` 中注册模型无关的输入准备器：
-
-```ts
-host.registerAiOperationHandlers([
-  {
-    operationKey: "example.summary.generate",
-    prepare(input, context) {
-      return {
-        instructions: "只根据用户提供的数据生成简洁摘要。",
-        userPrompt: JSON.stringify({
-          input,
-          actorId: context.actor.id,
-        }),
-      };
-    },
-  },
-]);
+```text
+POST /api/agent/runs
+GET  /api/agent/runs/:runId/events
+GET  /api/agent/runs/:runId/result
+POST /api/agent/runs/:runId/cancel
 ```
 
-不要把 Permission、Feature、License、Scope、Execution Grant、Provider 或 API Key
-放进返回值。`prepare` 只负责把已经过宿主 Guard 的类型化输入转成指令和用户消息。
+创建 Run 必须携带幂等键；SSE 支持 cursor 重放和 heartbeat。Engine 切换不改变 Run DTO、
+canonical Event、唯一终态、取消或 Tool 授权语义。
+
+## 能力与治理边界
 
-Tool handler 仍通过 `registerToolHandlers` 注册。模型提出 Tool Call 后，Agent Server
-携带短时 opaque grant 回调 Windy Server；受限 Tool Host 会验证：
+Direct Engine 已覆盖：
 
-1. grant 是否绑定当前 Run、Operation、Actor 且未过期；
-2. Tool 是否属于 Operation 的 `allowedToolKeys`；
-3. Operation 与 Tool 当前的 Feature、Permission 和 License；
-4. 宿主创建的 Actor 与请求 Scope。
+- 文本 delta 与最终文本；
+- JSON Schema 结构化输出；
+- Citation/Source 归一化；
+- Image Artifact 输入与 Vision readiness；
+- 单 Tool、多 Tool和有界多轮 Tool；
+- Tool allowlist、参数校验、Execution Grant 与二次授权；
+- 审批 pending、approved、rejected 与恢复；
+- 用户取消、deadline、Provider/Tool 失败和任务取消；
+- Provider Attempt、Usage、容量与 deployment attestation。
 
-Tool 请求不能携带权限列表、License、Scope 或“已授权”标志。客户端或模型提供的这些
-字段会被拒绝，未知 Tool 也不会形成注册表探测通道。
+业务模块只能声明稳定 Operation Key、输入/输出 Schema、Feature、Permission、可用 Tool 和
+Provider Data Policy。业务代码不持有 Provider Key，不导入 Runtime 私有类型，也不能直接
+访问 Agent Server。
 
-## 跨进程 Limits 契约
+Provider 调用前会执行：
 
-Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Windy Server
-在调用远端 Agent Server 前先执行文本输入与 Artifact 声明的 `maxInputBytes` 校验；
-跨进程请求逐字段发送 Agent Server 需要再次执行的时长、输入、输出、图片数量与像素
-上限。禁止通过展开 Manifest 对象透传 limits：TypeScript 的结构类型不会在运行时
-移除额外字段，而 Agent Server 契约会以 `extra=forbid` 拒绝未知字段。
+1. 当前 Actor、Feature、License、RBAC 与数据范围 Guard；
+2. Operation Release、Schema、输入 commitment 与 Artifact 授权；
+3. Provider readiness、capacity 和部署事实校验；
+4. outbound envelope DLP 与 Host allowlist；
+5. append-only 出网审计，审计失败则禁止出网。
 
-这个边界保证输入上限仍由持有原始业务输入的 Server 强制执行，同时避免 Python Runtime
-被平台内部但不属于远端契约的字段阻断。新增 limits 字段时，必须分别决定执行归属，并在
-真实 HTTP 序列化测试中确认请求体。
+Tool 调用继续由 Windy Server 执行。Agent Server 只收到 opaque Execution Grant；每次 Tool
+都重新校验当前权限、Scope、审批和 receipt，不把 Run 创建时的权限快照当长期授权。
 
-## 本地 Compose profile
+## 配置
 
-选择 `system.agent` 的 create-windy 项目会生成 `agent` profile 和随机内部 Token。
-在 `.env` 中填写：
+选择 `system.agent` 的项目在本机 `.env` 配置：
 
 ```dotenv
 PLATFORM_ENABLE_AI=true
-AGENT_SERVER_INTERNAL_TOKEN=<至少 32 字符的随机值>
-ADK_DEBUG_PLATFORM_TOKEN=<create-windy 自动生成的独立随机值>
-AGENT_RUN_ENCRYPTION_SECRET=<至少 32 字符的独立随机值>
-AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符的随机值>
+AGENT_SERVER_INTERNAL_TOKEN=<至少 32 字符随机值>
+AGENT_RUN_ENCRYPTION_SECRET=<至少 32 字符随机值>
 QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
-QWEN_API_KEY=<服务端密钥>
+QWEN_API_KEY=<server-only secret>
 QWEN_MODEL=qwen-plus
 AI_PROVIDER_HTTPS_HOST_ALLOWLIST=dashscope-intl.aliyuncs.com
 AI_PROVIDER_CAPABILITIES=text-generation
 AI_PROVIDER_INPUT_MODALITIES=text
-AI_PROVIDER_AUDIT_RETENTION_DAYS=90
-
-# 可选安全上限
-# AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
-# AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
-# AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
 ```
 
-然后启动：
+运行：
 
 ```bash
 bun run dev:agent
 ```
 
-`create-windy` 会为新的本地项目分别生成内部 Token、ADK 调试 Token、Run Store 加密
-Secret 与 Artifact 加密 Secret，四者不得互相复用。已有项目升级时 updater 只会为
-普通 `.env` 原子补齐缺失或空的受管 Secret，不覆盖任何非空值；符号链接、重复定义或
-缺失的 `.env` 会停止自动修复并由 `windy doctor` 报告，避免覆盖外部 Secret Store 或
-已有部署配置。
-`AI_ARTIFACT_ENCRYPTION_SECRET` 只用于平台签发短时 opaque ArtifactRef，不得复用
-Provider Key。Vision Deployment 需把能力与输入模态显式扩展为
-`text-generation,vision` 和 `text,image`，详见
-[Vision AI Runtime](./vision-ai-runtime.md)。Document profile 的配置与调用链见
-[Document AI Runtime](./document-ai-runtime.md)。
+`QWEN_*`、allowlist 和 Provider deployment facts 只进入 Agent Server，不进入 Web、浏览器
+Bundle、业务 Tool 或更新报告。缺少 URL、Key 或 Model 时，Runtime 使用
+`UnavailableEngineAdapter` 返回稳定 unavailable，不尝试猜测 Provider 或降级到其它 Engine。
 
-`QWEN_*` 只注入 `agent-server` 容器；Web service 没有这些环境变量。不要增加 `VITE_`
-前缀，也不要把 `.env`、日志、错误响应或截图中的真实 Key 提交到仓库。
+公网 Provider 必须是 HTTPS 且 Host 精确命中 allowlist。本机、Compose 服务名和私有网络
+Endpoint 可以使用 HTTP；重定向、DNS 解析和最终连接仍受网络策略约束。
 
-健康检查：
+## Vision
 
-```text
-GET http://agent-server:8080/health/live
-GET http://agent-server:8080/health/ready
-GET http://agent-server:8080/health/provider-governance
-```
+Vision 不能只根据模型名称或 Endpoint 可达性开启。部署必须声明：
 
-`ready` 会访问 Provider 的 `/models`。失败只返回稳定错误，不回显 Provider body、
-Authorization、Secret、Endpoint query 或底层异常文本。
-`provider-governance` 需要内部 Bearer Token，只返回留存、允许/拒绝/脱敏和 TTL 清理
-聚合，不返回 Run ID、prompt 或正文。
-
-## 字段治理迁移
-
-启用 `providerEgress.mode=configured-endpoint` 的既有业务 Operation 必须同时新增
-`providerDataPolicy`。升级后缺少策略会在 Manifest Composition 阶段以
-`Provider 字段发送 allowlist 缺失` fail fast，不会静默发送或降级放行。
-
-迁移时先枚举业务 input schema 中确实需要出境的最小 JSON Pointer；为每个字段声明
-分类与 `reject/redact`。再枚举 outbound envelope：无 Tool 的单轮问答通常只需要
-`instructions` 和 `user-prompt`；Tool schema、模型上一轮 Tool Call 和 Tool result
-分别需要 `tool-definitions`、`provider-output`、`tool-results`。不要为消除启动错误
-一次性允许全部字段。原始 input 会在进入 `prepare` 前裁剪，因此 Handler 必须只依赖
-allowlist 中的字段。
-
-Agent profile 还必须挂载 `AI_PROVIDER_AUDIT_STORE_PATH`。create-windy Starter 使用
-`/app/data/agent/provider-audit.sqlite3` 并复用单副本持久卷；自行维护 Compose 的项目
-需要显式补齐该变量。未配置时 Provider 启动 fail closed，并给出缺失变量名。
-
-## Developer-only ADK Web
-
-ADK Web 使用独立 profile 调试真实 canonical Run。项目先在 project-owned 的
-`apps/agent-server/project/adk-web-debug.json` 选择一个文本 Operation：
-
-```json
-{
-  "schemaVersion": 1,
-  "textOperation": {
-    "key": "your-module.copilot.global",
-    "dataActorId": "user_dev_admin"
-  }
-}
+```dotenv
+AI_PROVIDER_CAPABILITIES=text-generation,vision
+AI_PROVIDER_INPUT_MODALITIES=text,image
+AI_PROVIDER_DEPLOYMENT_IDENTITY=windy-deployment-v1_<uuid-v4>
+AI_PROVIDER_RELEASE_DIGEST=sha256:<64-lowercase-hex>
+AI_PROVIDER_READINESS_TTL_SECONDS=60
+AI_PROVIDER_MAX_CONCURRENT_RUNS=1
+AI_PROVIDER_MAX_QUEUE_DEPTH=0
 ```
 
-该 v1 接缝只承诺 `{ "question": string } -> { "text": string }`。Operation、Permission、
-Feature、Tool、Scope、Provider Policy 和输入输出 Schema 仍由业务 Module Manifest
-声明；`dataActorId` 必须是项目当前存在且启用的开发用户，用于复用真实案件成员关系与
-当前 Scope。Windy 不接受第二份权限、Scope 或 Tool 列表。用户不存在、权限闭包不足、
-Operation 未知或不符合文本契约时明确拒绝，不回退成伪造回答。
+Agent Server 以固定合成图片执行 bounded readiness，不读取客户 Artifact。实际 Run 只接受平台
+签发、当前 Actor 仍可访问的 ArtifactRef；浏览器不能提交任意 URL、宿主路径或 Base64 来绕过
+存储授权。Vision 输入模态和 Artifact 数量会进入脱敏 Trajectory，图片内容不会进入报表。
 
-一条命令会同时启动 Server、Tool Sandbox、Agent Server 与 ADK Web：
+## 持久化与 Engine 兼容
 
-```bash
-bun run dev:adk-web
-```
+生产 Run 必须使用持久 Store。SQLite 仅支持单副本；多副本必须配置共享 PostgreSQL Store。
+每个 Run 和 Runtime Report 保存稳定 Engine ID：
 
-访问地址为 `http://127.0.0.1:8000`。Compose 服务在容器内监听 `0.0.0.0:8000`，
-但端口只发布到宿主机 `127.0.0.1`。启动脚本读取 project-owned JSON，将唯一
-Operation Key 与真实开发数据用户注入 Windy-owned `docker-compose.agent-debug.yml`；
-普通 `dev`、`agent` profile 和生产 Compose 均不包含该服务或调试身份。
-
-选择 `canonical_debug` 应用后，每条问题由确定性 dispatcher 交给正式
-`POST /api/agent/runs`，再读取 SSE 与最终结果：
-
-- `create-windy` 自动生成独立随机 `ADK_DEBUG_PLATFORM_TOKEN`，无需复制登录 Token；
-- Server 只在 `NODE_ENV=development` 且加载调试 Compose Wrapper 时创建专用
-  `service_adk_debug` 身份；该 Token 只在 canonical Run 路径和只读 debug-session
-  GET 路径生效，不能访问 Foundation、Admin 或其它 Server API；即使与普通会话 Token
-  误碰撞也被视为保留调试凭据，不会回退普通认证；
-- Server 每次从用户目录解析 `dataActorId`，复用该用户当前 Scope 和业务成员 ID；只在
-  用户本身拥有完整权限闭包时，向 Module 投影该真实用户。核心 Run、Token 和审计主体仍
-  是 `service_adk_debug`，不会冒充普通用户会话；
-- 专用身份的权限精确收窄到所选 Operation Permission 与其 `allowedToolKeys` 的
-  Permission 闭包，并在 Tool Host 重新解析用户和复核 Scope；不能切换到其它 Operation；
-- ADK Web 容器不读取 `QWEN_*`、Provider Secret、`AGENT_SERVER_INTERNAL_TOKEN`，
-  不连接业务 Repository 或 Tool Host；
-- 正式 Server 仍签发 Actor、Scope 和短时 Execution Grant，Agent Server 仍按
-  `allowedToolKeys` 执行并审计；
-- SSE 先于结果持久化结束时，Adapter 最多再等待 60 秒并每 500ms 读取同一个 Run
-  的结果；只重试明确标记为可重试的 `RUN_CONFLICT`，不会重新创建 Run；
-- 事件摘要最多 64 条，单个 SSE frame 最大 64 KiB；流式 `output.delta` 只显示计数，
-  客户端边读边压缩，不先把完整事件流保存在内存。
-
-`safe_debug` 仍保留为不接业务的纯 ADK UI smoke。`canonical_debug` 能验证真实数据、
-模型与 Tool 链，但 ADK Web 显示的是“dispatcher → canonical Run”，不是另一进程内部
-完整的 Prompt/Agent/Workflow 节点图。完整 workflow replay 需要另行定义版本化调试
-协议，不能从当前事件摘要推断。
-
-### 业务调试会话 V1
-
-业务模块可通过 `ModuleHost.registerDebugSessionProviders()` 把已有会话投影到
-`canonical_debug` 的原生 ADK Web 会话列表。该能力是 developer-only 的通用只读
-接缝，不是业务会话 Repository，也不定义 Copilot、案件或其它领域 DTO：
-
-- Provider 必须以本模块命名空间注册，并绑定至少一个本模块 Agent Operation；
-  `featureKey` 与 `permissionKey` 必须与绑定 Operation 完全一致，`auditAction` 必须
-  已在同一 Manifest 声明。
-- `list()` 和 `get()` 只接收 Host 投影的当前业务用户、当前配置的唯一 Operation、
-  分页上限、不透明 cursor 与 `AbortSignal`。Provider 应使用稳定 keyset 分页，并在
-  自身 Service/Repository 边界内再次执行对象级授权，只返回完成态的 `user` /
-  `assistant` 文本。
-- Server 只向 ADK Web 暴露
-  `GET /api/agent/debug/sessions/v1` 与
-  `GET /api/agent/debug/sessions/v1/:sessionId`。两条路径复用专用 Debug Bearer，
-  每次请求都重做 License、Feature 与 RBAC Guard；其它 Method 不在 Token 白名单。
-- 业务 `sourceId` 只用于 Provider 回查。Host 签发绑定“投影业务用户 + Operation +
-  Provider + sourceId”的 HMAC 不透明 ID；详情读取先重新 list 并重新授权，再调用
-  `get()`，不会把可逆 ID、Actor ID、Operation Key、Provider Key 或业务范围 ID
-  返回 ADK。
-- Provider 每页最多返回 100 个会话，Host 会沿不透明 cursor 读取完成后再交给原生
-  ADK 列表，不静默丢弃第 101 条及更旧会话；任一分页或 Provider 失败都会拒绝整份
-  业务列表，避免把 partial 结果伪装成完整结果。详情最多 64 条消息，单条最多
-  16,000 字符，总计最多 128,000 字符。重复条目、循环游标、超界、乱序、未知角色、
-  非法时间或 Provider 异常均安全拒绝。
-
-ADK 2.5 通过官方 `services.py` Service Registry 加载 `windy-debug://v1` composite
-Session Service。普通 ADK session 继续保存在进程内 `InMemorySessionService`；业务
-会话在每次详情读取时重新授权并转换为 ADK `Session/Event` 的实时只读投影，不在
-ADK 本地固化，也不复制 Tool、Citation、Run ID、内部
-Operation 或业务对象标识。平台列表暂时不可用时仍返回普通本地 session；已选择的导入
-session 详情不可用时明确失败。
-
-导入 session 在 V1 中严格只读：PATCH/rename 与新消息都会在 `append_event()` 拒绝，
-在 canonical Tool 再做一次防御性拒绝；DELETE 只在当前 ADK Web 进程创建本地 tombstone，
-不会删除业务历史。刷新进程后 tombstone 消失。要继续提问必须新建普通本地 ADK
-session；由于当前 canonical bridge 输入仍只有 `{ question }`，平台不会把历史文本冒充
-成业务 continuation。真正的历史续问需要后续版本定义通用、受权限治理的高层
-Operation 契约。
-
-## 客户端协议
-
-浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Windy Server：
+- 新 Run：`windy.direct.openai-compatible.v1`；
+- 历史 Run：保留原始 `google.adk.v2` 值，只读兼容。
+
+历史 Run/Event/Result/Report、业务会话和 Client Agent Session 不会因 Engine 迁移而重写。
+已终止历史 Run 可继续读取。旧 Engine 的中断 Run 不允许由 Direct Engine 从内部状态续跑，
+会稳定失败并要求创建新 Run，避免跨实现重复执行 Tool 副作用。
+
+## 主站 Run 与 Trajectory
+
+统一入口为 `/admin/system/ai-runtime`。列表、详情和脱敏 Trajectory 同时要求 Feature
+`system.ai-runtime` 与 Permission `system.ai-runtime.read`，并按当前 Actor 数据范围过滤。
+
+Trajectory 从 canonical Event 投影，只展示：
+
+- Run 开始、Engine ID 和输入模态；
+- Model Attempt/Usage 的安全汇总；
+- Tool Key、审批状态和受控 Artifact 数量；
+- 失败码、取消和唯一终态。
+
+它不展示输入输出正文、Prompt、chain-of-thought、完整 Tool 参数、Secret、内部 Actor ID 或
+Provider 原始 body。越权与不存在统一返回 404，读取会写入关键审计。
+
+## 历史业务会话
+
+业务模块通过 `ModuleHost.registerAgentSessionProviders()` 注册 V1 只读投影。Provider 必须
+绑定本模块 Manifest 已声明的 Agent Operation；Host 复用该 Operation 的 Feature、Permission
+和数据范围。主站接口：
 
 ```text
-POST /api/agent/runs
-GET  /api/agent/runs/:runId/events
-GET  /api/agent/runs/:runId/result
-POST /api/agent/runs/:runId/cancel
+GET /api/agent/sessions/v1
+GET /api/agent/sessions/v1/:sessionId
 ```
 
-SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，以及唯一一个
-`run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
-cursor 恢复；不要重新创建 Run 或重复执行 Tool。
+接口使用当前登录身份，不接受专用服务 Token。Session ID 是 Host 生成的 opaque HMAC ID，
+不会暴露 Provider Key 或业务 `sourceId`。列表有界分页，详情每次重新授权；Provider 失败时
+整份结果 fail closed，不返回可能不完整或跨范围的混合列表。
 
-运行用量、缓存覆盖、滚动时间范围、数据范围与低基数 Prometheus 指标见
-[AI Runtime 用量与运行报表](./agent-runtime-observability.md)。
+旧 `registerDebugSessionProviders()` 仅作为一个兼容发布周期的 deprecated alias，内部调用
+同一注册表，不再有独立调试语义。
 
-## 升级既有 Starter
+## Client Agent Session 与 PageAgent
 
-目标 CLI 会一次解析 source 到 target 的连续 recipe，不需要逐个安装中间 CLI。确认
-npm registry 已能解析目标 artifact 后，先检查计划，再应用：
+服务端 Engine 迁移不改变 Client Agent Session。PageAgent 仍通过
+`/api/agent/client-sessions/**` 的短时能力与 Host Auth Adapter 工作，Provider 凭据留在服务端，
+客户端只获得受当前 Actor、Operation、Tool 和 origin 约束的会话。Client receipt、取消、
+Usage、审计和历史读取继续使用既有 canonical DTO。
 
-```bash
-bunx --bun create-windy@latest update --check
-bunx --bun create-windy@latest update
-bun install
-```
+PageAgent 是浏览器宿主本地 Loop，不会被服务端 Direct Engine 接管，也不能借此扩展
+Server Operation 的 Tool、Scope 或 Secret。完整契约见
+[Client Agent Session](./client-agent-session.md)。
+
+## 迁移与故障恢复
+
+从 `create-windy@0.6.13` 更新到 `0.6.14` 时，updater 删除未漂移的 Windy-managed ADK
+Compose/脚本；客户修改过的 managed 文件形成冲突。project-owned debug JSON 和普通 `.env`
+只进入不含值的人工清理报告，不自动删除或改写。
 
-升级器会更新受管模板文件；本地修改产生冲突时会 fail closed 并保留事务备份，不会静默
-覆盖。升级后按上面的环境变量启用 `agent` profile；`agent-debug` 仍只用于无业务 Tool
-的本机调试。自动化部署应把已审阅的 `latest` 替换为精确版本。
+详细操作、重复故障和快速恢复见
+[ADK 退役与 Direct Engine 恢复](../operations/adk-retirement.md)。

package/template/docs/platform/agent-tool-approval.md

@@ -0,0 +1,61 @@
+# Agent 写 Tool 审批与恢复
+
+`approval: "required"` 是执行协议，不是 Prompt 提示。模型请求写 Tool 后，平台先重新校验当前 Actor、Operation、Feature、Permission、License、Scope 和输入 Schema，再创建 Workflow Work Item；Handler 在审批通过前不会收到调用。
+
+## Manifest
+
+```ts
+{
+  key: "case.finding.merge",
+  operation: "command",
+  approval: "required",
+  approvalRoles: [{ code: "case-reviewer", name: "案件审核员" }],
+  approvalTimeoutSeconds: 86_400,
+  idempotency: "required",
+  // permissionKey / featureKey / auditAction / schema / limits ...
+}
+```
+
+审批 Tool 必须显式声明非空候选角色、正整数等待上限和
+`idempotency: "required"`；查询 Tool 不能要求审批。
+
+## 运行语义
+
+1. Provider 发起 Tool Call。Agent Runtime 以 Run、Tool Key 和规范化参数生成稳定
+   `toolCallId`，Provider 重试或 Runtime 恢复不会改变该标识。
+2. Tool Host 只接受内部认证与平台签发的 Execution Grant，并使用当前服务端 Actor
+   重新执行 Operation 与 Tool Guard。
+3. `approval=required` 创建持久化 Work Item。Run 发出
+   `approval.required(workItemId, toolCallId)` 并进入 `awaiting-approval`。
+4. Runtime 轮询同一 Tool Call。批准后再次执行全部 Guard 与 Schema 校验；拒绝、取消
+   和超时发出 `approval.resolved`，随后 Run 安全失败，不执行副作用。
+5. 批准后 Handler 收到 `context.idempotencyKey === toolCallId`。业务写入必须同时使用该
+   键与领域 `expectedVersion`，不能信任模型或浏览器传入的 `approved=true`。
+
+Tool Host 对同一进程内的相同 Run/Tool Call 做 single-flight 和结果复用。Agent Run Store
+加密保存未完成调用上下文；服务重启时以 `run.resumed` 恢复，稳定 Tool Call 标识保证
+同一审批与业务幂等键被复用。终态后立即清除加密调用上下文。
+
+## 事件与错误
+
+- `approval.required`
+- `approval.resolved`，`outcome` 为 `approved`、`rejected`、`cancelled` 或
+  `timed-out`
+- `tool.completed`
+- 唯一 `run.completed`、`run.failed` 或 `run.cancelled`
+
+内部审批响应使用稳定代码 `APPROVAL_REQUIRED`、`APPROVAL_REJECTED`、
+`APPROVAL_CANCELLED`、`APPROVAL_TIMED_OUT` 和 `APPROVAL_UNAVAILABLE`，不透传
+Workflow 或业务异常正文。
+
+## 部署
+
+生产 Agent Store 必须配置独立的至少 32 字节密钥：
+
+```dotenv
+AGENT_RUN_STORE_PATH=/app/data/agent/runs.sqlite3
+AGENT_RUN_ENCRYPTION_SECRET=
+```
+
+密钥丢失时未完成 Run fail closed，不能以明文回退。当前 SQLite Store 是单副本恢复面；
+多副本共享 Store、不可变 Release、评估和完整观测关联见 Agent 生产运行文档。

package/template/docs/platform/background-ai-operations.md

@@ -0,0 +1,50 @@
+# Actor-aware 后台 AI Operation
+
+## 适用范围
+
+业务模块可以在 Durable Handler 中调用本模块 Manifest 已声明的、无 Tool 的 Agent
+Operation。首个用例是浏览器关闭后继续生成 Copilot 滚动摘要。该 Port 不替代业务会话、
+消息、摘要版本或结果写入 Repository。
+
+`system.agent` 因此依赖 `system.scheduler`。没有启用 AI Runtime 时，普通业务和任务
+Worker 仍可启动；调用后台 AI Port 会得到稳定的
+`AI_OPERATION_UNAVAILABLE`。
+
+## SDK
+
+`ModuleDurableHandlerContext.ai.enqueueOperation()` 只接受：
+
+- `operationKey`：必须属于当前模块；
+- `input`：最小 JSON 输入，仍执行 Manifest allowlist 与 DLP；
+- `idempotencyKey`：由业务来源和版本组成的稳定幂等键；
+- 可选 `timeoutSeconds`：1 至 900 秒。
+
+返回 `{ runId, output }`。业务应在同一事务中用会话或摘要的 expected-version 写入结果，
+防止较旧任务覆盖用户已经更新的摘要。
+
+## 授权和恢复
+
+Job 提交时，宿主保存当前 Actor 与授权范围快照。每次执行、重试和租约恢复都会重新解析
+当前 Actor，并检查范围未变化。实际创建或重新连接 Run 时还会重新执行 Operation 的
+Feature、Permission、License、Provider 数据策略、出网策略、输入/输出上限和审计。
+
+业务模块不能传入 Actor，不能跨模块调用 Operation，也不能接触 Provider Secret、
+Execution Grant、Remote Runtime 或平台 Repository。
+
+后台 Operation 必须声明 `allowedToolKeys: []`。这样租约丢失或任务重试只会通过相同
+幂等键恢复同一个 Run，不会扩大写 Tool 的重复副作用窗口。
+
+## 状态与错误
+
+Durable Handler 等待同一 Run 的终态：
+
+- `completed`：读取受控 JSON 结果；
+- `failed`：返回 `AI_OPERATION_FAILED`，保留安全的 retryable 语义；
+- `cancelled`：返回不可重试的 `AI_OPERATION_CANCELLED`；
+- 超时：请求取消远端 Run，返回可重试的 `AI_OPERATION_TIMEOUT`；
+- 权限、模块或 Tool 约束不满足：返回不可重试的
+  `AI_OPERATION_DENIED`。
+
+平台服务重启后，Run 授权绑定和 Agent Store 都从 PostgreSQL 恢复。Worker 重试使用相同
+幂等键，因此不会新建 Run。租约丢失时不主动取消远端 Run，后继 Worker 可以继续恢复；
+用户取消或显式超时才请求远端取消。