create-windy 0.6.19 → 0.6.20

package/dist/cli.js

@@ -372,6 +372,7 @@ var agentOptionalModule = {
   documentation: [
     "docs/adr/0003-agent-session-event-source.md",
     "docs/architecture/agent-harness.md",
+    "docs/architecture/agent-runtime-compatibility.md",
     "docs/architecture/agent-workflow.md",
     "docs/architecture/durable-jobs.md",
     "docs/architecture/ai-egress.md",
@@ -4092,6 +4093,7 @@ var templateDocumentationFiles = [
   "docs/adr/0003-agent-session-event-source.md",
   "docs/architecture/admin-surface-boundary.md",
   "docs/architecture/agent-harness.md",
+  "docs/architecture/agent-runtime-compatibility.md",
   "docs/architecture/agent-workflow.md",
   "docs/architecture/ai-egress.md",
   "docs/architecture/ai-runtime.md",
@@ -8500,6 +8502,11 @@ var recipes = [
     id: "starter-0.6.18-to-0.6.19",
     from: "0.6.18",
     to: "0.6.19"
+  },
+  {
+    id: "starter-0.6.19-to-0.6.20",
+    from: "0.6.19",
+    to: "0.6.20"
   }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "f2e5ced778480dc66e9dd03dd79023b9eda766a1",
-  "generatorVersion": "0.6.19",
+  "templateCommit": "2b9bad011549abb0be1af6a4d0eefe60426f7247",
+  "generatorVersion": "0.6.20",
   "modules": [
     {
       "name": "system",

package/template/docs/architecture/agent-runtime-compatibility.md

@@ -0,0 +1,107 @@
+# Remote Agent Runtime 兼容契约
+
+更新时间：2026-09-02。
+
+状态：WAI-1 V1 兼容协商基础已实现。它不开放新的业务 Run 入口，也不代表外部业务系统已经可以
+直接接入生产 Agent Server。
+
+## 目标
+
+Windy 继续只有一套 Agent Runtime。业务系统保留领域治理，中央 Windy Runtime 负责模型执行和
+运行事实，两者通过显式版本化的 Remote Agent Runtime Interface 演进，不能依赖“HTTP 能通”或
+共享源码版本猜测兼容性。
+
+WAI-1 只冻结兼容 Offer 和 Run 创建时的版本 pin：
+
+- Agent Server 通过受认证的 `GET /api/agent/runtime/compatibility` 返回 V1 Offer；
+- Windy Server 选择共同协议版本，并校验 Engine release、协议能力和完整 Offer 摘要；
+- 创建 Run 时用请求头固定所选协议版本和 Offer digest；
+- Agent Server 在写 Store 或执行 Engine 前重新校验两个 pin；
+- 旧 Server 不发送 pin 时，新 Agent Server 保持兼容；新 Server 在 `prefer-v1` 模式下只对旧
+  Agent Server 的明确 `404` 回退，畸形或不兼容 Offer 不降级。
+
+公开 TypeScript 契约位于 `@southwind-ai/server-sdk`。它是 Server Adapter 的 Interface，不进入
+浏览器 Bundle，也不让业务 Module 直接访问 Agent Server。
+
+## 所有权
+
+| 所有者       | 保留职责                                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 外部业务系统 | Manifest、Operation prepare、Feature/RBAC/License/Data Scope、DLP、Artifact 授权、Execution Grant、Tool allowlist、审批、幂等、审计与 Tool Handler |
+| 中央 Windy   | Run 生命周期、Remote execution、Provider/模型路由、canonical SSE/result/cancel、Usage 与可观测事实                                                 |
+| Agent Server | 受控 Model/Tool loop、Run Store、Engine identity、协议 Offer 与 pin 校验；禁止访问业务数据库或 Repository                                          |
+
+中央 Runtime 只接收业务 Host 已治理的输入、ArtifactRef、版本化 Operation Release、Tool schema
+和 opaque Execution Grant。数据库 URL、Repository Adapter、业务 Secret、Actor 自报权限或“已审批”
+标志都不属于此 Interface。
+
+## V1 Offer
+
+Offer 使用以下稳定结构：
+
+```json
+{
+  "schemaVersion": 1,
+  "runtimeKind": "agent",
+  "engineId": "windy.direct.openai-compatible.v1",
+  "protocolVersions": [1],
+  "protocolFeatures": ["canonical-sse-replay.v1", "run-lifecycle.v1"],
+  "toolCallback": {
+    "contractVersion": 1,
+    "authentication": "windy-internal-bearer-v1"
+  },
+  "releaseDigest": "sha256:<engine-and-protocol-digest>",
+  "capabilitiesDigest": "sha256:<features-and-callback-digest>",
+  "offerDigest": "sha256:<complete-offer-digest>"
+}
+```
+
+`protocolFeatures` 描述 Runtime 传输与治理语义，不复用 Operation 的
+`requiredCapabilities`。后者仍表示模型或执行能力，例如 `text-generation`、`vision`。
+
+三个摘要使用稳定字段顺序、排序后的集合和紧凑 JSON 计算：
+
+- `releaseDigest` 绑定 `runtimeKind + engineId + protocolVersions`；
+- `capabilitiesDigest` 绑定 `protocolFeatures + toolCallback`；
+- `offerDigest` 绑定前述全部字段与两个子摘要。
+
+调用方必须重新计算摘要。只修改数组顺序不会改变语义；重复、超界、非法稳定 Key、未知
+`schemaVersion`、无共同协议、能力缺失、callback auth 不匹配或摘要漂移都失败关闭。
+
+## 协商与滚动升级
+
+Windy 项目组合使用 `prefer-v1`：
+
+1. 每次创建 Run 前读取当前 Offer，不缓存跨进程替换后的事实；
+2. Offer 为合法 V1 时发送：
+   - `X-Windy-Agent-Runtime-Protocol: 1`
+   - `X-Windy-Agent-Runtime-Offer-Digest: sha256:...`
+3. 只有兼容端点明确返回 `404` 才按旧协议创建 Run；网络失败、403、5xx、畸形响应和不兼容
+   V1 均拒绝启动；
+4. Agent Server 接受“两个 pin 都缺失”的旧客户端；只有一个 pin、未知版本或 digest 不一致均在
+   Run admission 前拒绝。
+
+供后续外部业务 Host 使用的 Adapter 必须选择 `require-v1`，不能允许 404 legacy fallback。
+Run body 保持原样，避免给 Pydantic `extra=forbid` 的旧 Agent Server 增加字段而破坏滚动升级。
+
+## 当前认证限制
+
+V1 Offer 如实声明 `windy-internal-bearer-v1`。它只适用于同一受控部署内的 Windy Server 与
+Agent Server，仍使用 `AGENT_SERVER_INTERNAL_TOKEN` 保护兼容查询、Run 接口和 Tool callback。
+
+不得把该 token 复制给 Sharp S-Word 或其它业务系统，也不得把当前 callback URL 暴露为跨系统
+公共入口。外部生产接入前必须新增独立受众、短时或可轮换凭据、重放保护和按业务 Host 撤销的
+callback auth profile；届时外部 Adapter 以 `require-v1` 要求新 profile，旧内部 Adapter 继续并行。
+
+## 非目标
+
+WAI-1 不实现：
+
+- LiteLLM 或多 Provider Gateway；
+- 完整 RAG、向量索引或跨系统检索；
+- Sharp S-Word 的 Manifest、Tool、数据或 UI 接线；
+- 远程业务 Host 注册表、租户路由或共享 Copilot UI；
+- callback 认证升级。
+
+这些能力必须在新切片中复用本 Interface，不得新增第二套 Agent Server、Run/Event DTO 或业务数据库
+访问路径。