create-windy 0.6.12 → 0.6.15

package/template/docs/platform/client-agent-session.md

@@ -0,0 +1,319 @@
+# Governed Client Agent Session
+
+更新时间：2026-08-28。
+
+## 目的与边界
+
+Client Agent Session 是 Windy 为浏览器、桌面壳和扩展等“宿主本地编排模型循环”提供的
+通用治理协议。它不是 PageAgent 专属实现，也不允许下游产品复制 Provider 凭据或
+Agent Server 的 Tool execution grant。下游只负责业务 Composition 和浏览器 binding；
+Windy 拥有会话、模型代理、receipt、终态和审计语义。
+
+生产闭环已经提供：
+
+- `ModuleAiOperationDefinition.clientExecution` 显式 opt-in 与组合门禁；
+- `@southwind-ai/server-sdk` 的宿主 Port 和 `@southwind-ai/ai-client/client-agent` DTO；
+- 单 Run opaque bearer、Actor/Operation/Release/Input/Binding 承诺；
+- `/chat/completions` 请求的 role、字段、model、字节、step 和并发约束；
+- Manifest `providerDataPolicy` envelope allowlist 与 DLP；
+- opaque Provider response receipt、exactly-once finalize/cancel/status/result；
+- Provider 优先结果投影，以及不可冒充 Provider 证明的 `clientProjected` 标记；
+- Actor、binding、权限漂移、TTL 和显式撤销后的 fail-closed 状态机。
+- Windy Server 到 Agent Server 的 internal-token SSE Adapter；Agent Server 固定管理面
+  deployment、物理 model、Provider URL 和 Key；
+- PostgreSQL/Drizzle `client_agent_sessions` 与 `client_agent_receipts` 事务仓储、前向
+  migration 和进程重启恢复；
+- 登录会话撤销、权限漂移、TTL、binding revoke 与 Abort 的联动；
+- `pageAgentClientRun` readiness 协商。只有 Agent Server Provider 与已配对的 Browser
+  Assistant Host Auth Adapter 同时就绪时才返回该 capability。
+
+## Manifest opt-in
+
+只有 `kind=agent`、`providerEgress.mode=configured-endpoint` 且已有
+`providerDataPolicy` 的 Operation 能声明：
+
+```ts
+clientExecution: {
+  mode: "governed-session",
+  launchAuthority: "direct", // Workflow Artifact 专用 Operation 使用 workflow-artifact
+  maxSteps: 12,
+  maxRequestBytes: 262_144,
+  maxResponseBytes: 262_144,
+  maxConcurrentRequests: 1,
+}
+```
+
+这些上限不能突破 Operation 的输入/输出边界；`maxSteps` 最大 128，并发最大 4。
+Manifest 不声明 Provider URL、物理模型或 Secret。客户端收到的 `modelAlias` 只是本次
+Session 的固定逻辑别名。
+
+`launchAuthority="workflow-artifact"` 是 Host enforcement，不是 prompt 约定：普通
+`/agent/runs` 与普通 Client Session create 均隐藏并拒绝该 Operation，只有固定 Workflow
+Artifact service 的内部 create seam 可签发 Session。
+
+## HTTP 契约
+
+创建与 capability 请求使用配对后短期 `bax_` installation session：
+
+```text
+POST /api/agent/client-sessions
+```
+
+请求只包含 `operationKey`、符合 Operation input schema 的 `input`，以及宿主计算的
+`clientBindingDigest`。binding 应覆盖 installation、conversation、tab 和 document
+epoch 或宿主等价的服务切换 epoch；Windy 只保存 digest，不依赖当前浏览网页 origin 的
+人工授权。创建时自动执行 License、Feature、Permission、Scope、
+Provider egress 与 data policy 检查，并返回：
+
+- `clientRunId`、`sessionId`；
+- 受信 `trustedBaseUrl` 和固定 `modelAlias`；
+- steps/request bytes/response bytes/duration/concurrency 上限；
+- `expiresAt` 和 `car_` 前缀的单 Run bearer。
+- `capabilities: ["pageAgentClientRun"]`。
+
+浏览器扩展不需要也不持有宿主 Web cookie。`Authorization: Bearer bax_...` 只由
+Client Agent Host Auth Adapter 在这些 route 上解析，再按 `actorId` 加载 canonical
+Actor、最新 RBAC 与 Scope；普通业务 API 的 Actor resolver 明确拒绝 `bax_` 和 `car_`。
+调用创建前可探测生产 readiness：
+
+```text
+GET /api/agent/client-sessions/capabilities
+```
+
+成功响应为 `{ capabilities: ["pageAgentClientRun"], modelAlias }`。Provider 未配置、
+Agent Server 不可达或未登录时不协商该能力。此流程没有逐动作 approval，也不要求用户
+复制 token；宿主把 grant 只保存在受信内存中。
+
+带 `:sessionId` 的后续 Route 使用 `Authorization: Bearer car_...`，同时通过
+`X-Windy-Host-Authorization: Bearer bax_...` 提供配对 Host Actor，并在
+`x-windy-client-binding-digest` 中重申 binding：
+
+```text
+POST /api/agent/client-sessions/:sessionId/v1/chat/completions
+POST /api/agent/client-sessions/:sessionId/finalize
+POST /api/agent/client-sessions/:sessionId/cancel
+GET  /api/agent/client-sessions/:sessionId
+GET  /api/agent/client-sessions/:sessionId/result
+POST /api/agent/client-sessions/revoke
+```
+
+`trustedBaseUrl` 是带当前 `sessionId` 的 OpenAI-compatible baseURL，例如
+`https://windy.example/api/agent/client-sessions/cas_x/v1/`。PageAgent 只向其
+`chat/completions` 子路径发送请求。`revoke` 使用 `bax_` Host Auth 和
+`{ clientBindingDigest }`，只撤销当前 Actor 的匹配 binding；服务切换、installation
+撤销或宿主 session 关闭时应调用它。登出和登录会话撤销会由平台自动执行 Actor revoke。
+
+bax/car bearer 只匹配 Client Agent Route，不能调用普通业务 API 或 Tool Host。服务端只保存其
+SHA-256 hash。客户端请求只能使用固定 model alias 和允许的 OpenAI-compatible 字段；
+URL、endpoint、未知 body 字段、未知 role、越界 Tool schema 都会被拒绝。
+
+PageAgent Core 1.12.2 的通用 envelope 已锁定：`parallel_tool_calls` 必须为 `false`；
+`tool_choice` 可为 `auto`、`none`，或引用当次 `tools` 中 function 的命名选择（包括
+MacroTool `AgentOutput`）；assistant 历史可携带经校验的 `tool_calls`，后续 tool message
+必须以 `tool_call_id/name` 匹配该调用。并行调用、未知命名 function 或断裂的 tool history
+都会 fail closed。
+
+流式响应转发标准 OpenAI SSE chunk；成功末尾追加
+`event: windy.receipt`，其 data 为 receipt，再发送 `[DONE]`。非流式响应在
+`windy_receipt` 字段和 `x-windy-provider-receipt-id` 响应头返回相同 receipt。Abort 会
+向 Agent Server 和 Provider 传播；取消或撤权后迟到 chunk 不能生成 receipt。
+
+## Receipt 与终态
+
+每次成功 Provider attempt 生成一个 `receipt_` opaque ID，并持有以下不可变绑定：
+
+- Client Run、Actor、Operation、Release、binding digest；
+- attempt 序号、request/response/deployment digest；
+- issuedAt 和可选的服务端 canonical result 投影。
+
+Repository 不保存 raw prompt、Provider response、Secret 或 bearer。HTTP 只公开 receipt
+所需的 opaque ID 与 digest，不公开 Actor、Scope、Release 内部快照。
+
+`finalize` 必须按 attempt 顺序提交本 Run 的完整 receipt 链，且没有在途请求。Gateway
+能够从最终 Provider response 得到 schema-valid 投影时，结果标为
+`provider-observed`；否则可以接受有界、schema-valid 的客户端投影，但必须标为
+`client-projected`，`providerAttested=false`。客户端 DTO 没有 `runtimeVerified` 字段。
+
+完成、取消、撤销和过期都是不可改写终态。重复的相同 finalize 返回同一结果；不同
+finalize、终态后的模型调用和跨 Run/Actor/binding receipt 重放均被拒绝。取消会 abort
+在途 Provider 请求；即使响应随后到达，也不能再追加 receipt 或改变终态。
+
+## Workflow Artifact Port
+
+预设 Workflow 调用 PageAgent 时复用既有 `job -> artifact -> final` 图节点，不新增
+Client Agent 节点或在线画布。Release 的 Job Node 固定使用
+`system.agent-workflow.client-agent-artifact` taskKey；project-owned Composition 为每个
+Workflow 最多绑定一个 PageAgent Node、一个已声明 Operation 和 Artifact Policy。业务
+Handler 只看到 `begin / claimOrAdvance / reconcileOrCancel` 三动作深 Port，不获得 Host
+Auth、Provider 坐标、Client Session bearer 或 BlobStore。
+
+绑定必须 pin 审核时的完整 Immutable Release，而不是只写可被后续版本复用的 Workflow Key：
+
+```ts
+{
+  workflowKey: "analysis.cross-case.full-review",
+  releaseDigest: "sha256:<审核后 Immutable Release digest>",
+  scopeContainmentContractVersion: 1,
+  nodeId: "page-agent-artifact",
+  operationKey: "analysis.cross-case.page-agent",
+  terminalResultAuthority: {
+    version: "sharp.cross-case-result.v1",
+    digest: "sha256:<project validator rules digest>",
+    canonicalize: async ({ workflowInput, inputArtifacts, proposedResult, actorId, scopeDigest, signal }) => {
+      // inputArtifacts 是 terminal 时重新授权并打开的 JSON，可校验 sourceArtifactId/locator
+    },
+  },
+  clientTaskAuthority: {
+    version: "sharp.cross-case-client-task.v1",
+    digest: "sha256:<project task projection digest>",
+    build: async ({ workflowInput, inputArtifacts, actorId, scopeDigest, signal }) => {
+      // inputArtifacts 是 Host 当前重授权并打开后的 JSON；只返回有界执行输入
+      return { taskKey: "sharp.cross-case.page-agent", input: { /* canonical locator/task */ } };
+    },
+  },
+  launchAuthority: {
+    version: "sharp.cross-case-launch.v1",
+    digest: "sha256:<membership/source/version/scope admission digest>",
+    authorizeRelease: async ({ definition, coordinates, actorId, signal }) => {},
+    authorizeRun: async ({ releaseId, releaseDigest, workflowInput, inputArtifacts, actorId, currentAuthorizationScope, signal }) => ({
+      authorizationScope: narrowToExactCase(currentAuthorizationScope, workflowInput),
+    }),
+  },
+  artifact: {
+    kind: "analysis-report",
+    contentType: "application/json",
+    filename: "analysis.json",
+    retentionPolicyKey: "analysis.case-artifact",
+    maxByteSize: 4 * 1024 * 1024,
+  },
+}
+```
+
+该 Release 中固定 taskKey 的 Job Node 必须唯一，并且只能形成无 branch 的
+`job -> artifact -> final` 直接链；Artifact Node 的 kind/policy 必须与绑定一致，三节点的
+failure policy 不得通过 fallback/skip 绕开链路。发布新 Release 后必须重新审核并更新
+`releaseDigest`，旧绑定不会静默授予新 Release PageAgent 权限。
+
+terminal authority 在 Client Session 原子完成前收到 loader 当前 Workflow input，以及重新
+reauthorize/resolve/open 后逐项核对实际 metadata 与字节上限的 canonical JSON input artifacts，
+再结合候选 canonical result、Actor、冻结 scope digest 与 AbortSignal 做 input-relative provenance
+校验。任一来源撤权、Owner/source 漂移、打开失败或 project 拒绝时 Session 与 Artifact 都保持
+未完成；返回值还要再次通过 Operation output schema。binding commitment 只承诺 authority
+`version/digest`，绝不序列化函数本体。
+
+受绑定保护的 Workflow 不能从通用 `POST /agent/workflows/releases` 或 `/runs` 发布、复造或
+启动；即使 Actor、权限、Definition、coordinates 与 release digest 完全相同也按未发现拒绝。
+project-owned preset 只能使用 Host 返回但不挂通用路由的 `agentWorkflowProjects` Seam：发布先
+调用 `launchAuthority.authorizeRelease`，启动先调用 `authorizeRun`，再把返回的 exact-case scope
+与 Host 传入的 `currentAuthorizationScope` 做 containment，并以该窄 scope 持久化 Run/Job
+authorization。项目不得猜 tenant、roles 或 grants；Digest 只是 commitment，不是 launch capability。
+
+claim 进入 running 前，Host 用当前 Run 的冻结 scope 对 Node `inputArtifacts` 重新执行 Durable
+Artifact 字节、Owner 与 source authorization，并只把打开的 JSON payload 交给 project-owned
+`clientTaskAuthority`。浏览器只收到 `{schemaVersion, taskKey, input, inputDigest}` 的 256 KiB
+canonical task；`@southwind-ai/ai-client` 对未知字段、非 JSON、错误格式 digest/状态组合 fail closed，
+不会下发 raw Artifact。task authority 与 terminal authority 独立，前者控制执行输入，后者控制
+input-relative 终态结果。
+
+浏览器可见 `workId` 的 canonical opaque 前缀固定为 `cawa_`；Server 生成器、
+`@southwind-ai/server-sdk` 和 `@southwind-ai/ai-client` validator 必须同步，调用方只能原样回传，
+不得解析前缀后的内部身份。
+
+Server 在浏览器可领取前先持久化 pending，并在同一事务锁定 canonical command 与 Run，
+复核 Actor、Scope、authorization、run policy、request digest、generation 和 effect fence。
+生产 Web 使用当前登录 Cookie，扩展使用已配对 `bax_` Host Auth；两者都只得到绑定
+installation/session/run/node/command/scope/digest 的短期 grant。Client Agent Session 的
+receipt 链完成后，Server 以一次性 terminal receipt 将 canonical JSON 写入稳定 Blob 坐标，
+再用 `publishArtifactOnce` 发布 Durable Artifact；重启只协调同一 receipt，不重放模型副作用。
+每次 Provider attempt 在预留前和真正出网紧前检查 canonical bridge，并在执行期间持续检查
+Run/Node/command、generation/fence、Actor、Operation、client binding、Host session 与当前授权；
+取消、Host revoke 或 fence 轮换会先撤销 Session 并阻止新出网，普通非 Workflow Session 仍沿用
+原有授权语义。
+
+Session finalize 与 Blob/bridge complete 之间允许进程退出。恢复只读已持久化的 completed Session、
+完整 receipt 链、final result 与 terminal request digest，确定性重建 terminal receipt、JSON 与稳定
+Blob ref，再执行 `putOnce` 和 bridge complete。恢复不等待浏览器重发 advance，也不再次调用
+Provider。completed advance 只有 `receiptIds + result` 的 canonical terminal request digest 与首次
+完成完全一致时才幂等返回；任何顺序、receipt 或 result 漂移都 fail closed。
+此 terminal replay 使用独立的 terminal-safe authorization：继续复核当前 Actor、RBAC、Scope、
+Host/Session/claim 及原 Release/Definition/command 不可变坐标，但不要求 command 仍处于
+`dispatched` 或 Run 仍处于 active。因而 command 已 committed/reconciled、Run 已 completed 后，
+相同摘要仍返回同一 Artifact。Scope 不做当前 digest 与冻结 digest 的机械相等比较：Host 从
+Durable Job 读取不可伪造的冻结 authorizationScope，并证明当前 Actor scope 仍包含该冻结范围；
+相等是特例，当前范围缩小到不再包含冻结范围时仍按未发现处理，也不会恢复成更宽 Run。
+
+模块 Durable Handler 需要把 Storage resource 或 JSON snapshot 作为后续 Workflow input 时，使用
+`context.workflowInputArtifacts`（或 `requireModuleWorkflowInputArtifactPublicationPortV1`）。Host
+先执行既有 resource-file policy/对象授权，再 `BlobStore.putOnce` 并在当前真实 Job lease 内调用
+`publishArtifactOnce`；返回的 `AgentWorkflowArtifactRef.artifactId` 来自 Durable Artifact receipt，
+绝不能用 Storage `fileId` 替代。source coordinate 仍须由模块注册的 authoritative source
+Adapter 支持当前对象复验。
+
+Workflow 启动前的时序使用两阶段 `ModuleRequestContext.workflowInputMaterialization`：模块同时在
+Manifest 声明 `<module>.workflow-input-materialize` Task，并用
+`defineModuleWorkflowInputMaterializationHandlerV1` 注册固定 Handler。Route 先 `begin`，Host 只把
+module-owned source specs 与当前 Actor/scope 提交为真实 Durable Job；后续 `resolve` 只返回
+`pending`，或从同一 succeeded Job 的正式 publication 投影 `ready + AgentWorkflowArtifactRef[]`。
+`begin`、Durable payload parser 与 worker publication 复用同一 public strict parser：resource/json
+字段按 mode 必填且互斥，未知字段、getter/稀疏数组、危险键、非有限数字、超深/超节点/超字节 JSON
+一律在 Storage/Blob 写入前拒绝；resource request 也必须精确匹配 `fileId/purpose/resourceType/resourceId`。
+调用方只能在 ready 后把 refs 连同 source IDs 交给 preset start；project prepare 仍重读业务对象并
+逐项匹配坐标，Workflow start 随后再次校验 Durable Artifact 字节、Owner、source authorization 与
+冻结 scope。客户端回传的是待复验 capability-like ref，不是来源授权事实。取消、撤权、Job/metadata
+漂移或非 succeeded 状态不会返回 refs；Coordinator 不创建 synthetic job。
+该固定 Manifest task 的实现事实就是同 key、同 feature/permission/audit 的 Durable Handler；
+Module completeness 不要求再注册 scheduled `registerTaskHandlers` no-op，任一 capability 坐标漂移
+仍按缺少实现 fail closed。
+
+`completed` 与 `cancelled` 是吸收态。取消先持久化 `cancellation-requested`，再撤销关联
+Client Session，最后提交 cancelled；启动恢复会继续未完成的取消。只有尚未产生 attempt、
+receipt 或在途请求的同一 installation/session/binding 才能立即接管丢失响应的 claim；其它
+迟到写入、过期 claim、fence 漂移、不同内容占用同一 Blob/Artifact 坐标均 fail closed。
+
+## 部署与稳定错误
+
+生产 Server 必须配置 `WINDY_PUBLIC_BASE_URL=https://windy.example`。它只用于生成受信
+Windy baseURL，不能指向 Provider。Provider URL、Key、物理 model 和 deployment 只通过
+Agent Server 管理面环境配置；公共 DTO 没有 BYOK 字段，也不支持客户端 model override。
+
+稳定错误 code 为 `INVALID_INPUT`、`FORBIDDEN`、`NOT_FOUND`、`CONFLICT`、
+`LIMIT_EXCEEDED`、`PROVIDER_FAILED`、`INTERNAL_ERROR`。message 使用简体中文安全文案，不透传 Provider
+正文、URL、Key、物理 model 或内部错误。License/Feature/Permission/Scope 不满足统一
+fail closed，不进入人工审批状态机。
+
+PostgreSQL 集成回归使用 `CLIENT_AGENT_TEST_DATABASE_URL`，覆盖并发预留、receipt 原子写入、
+重启恢复与终态不可改写；Agent Server contract 回归覆盖 tool calls、DLP、SSE、Abort 和
+Provider 错误脱敏。
+
+## 升级说明
+
+从不含生产 Client Agent Session 的版本升级时：
+
+1. 先执行标准 `windy update` / migration 流程，确认 migration 0055 已创建 session 与
+   receipt 两张表，0056 已加入 Host Session digest；不要手工回填 token 或 Provider 响应；
+2. Server 配置 `WINDY_PUBLIC_BASE_URL`，生产必须是最终用户可访问的 HTTPS 利剑服务 origin；
+3. Agent Server 继续使用现有 `QWEN_API_URL`、`QWEN_API_KEY`、`QWEN_MODEL` 与 deployment
+   配置，绝不把这些值复制到 Web、扩展或业务模块；
+4. 业务模块仅在目标 Agent Operation 上声明 `clientExecution`；Workflow 专用 Operation 还必须
+   声明 `launchAuthority: "workflow-artifact"`，同时保留原
+   Feature/Permission/License/Scope 与 `providerDataPolicy`；
+5. 在 project-owned `client-agent-host-auth-binding.ts` 装配实现
+   `ModuleClientAgentHostAuthAdapter` 的 P-256 pairing/bax Adapter；其 `authenticate` 只返回
+   actor/installation/session 标识，权限仍由 Windy canonical Actor 加载，并通过
+   `bindRevocations` 把 installation/session 撤销推给 Session Service。未装配或未 ready 时
+   不注册/不协商 capability；
+6. 客户端先请求 capabilities；只有出现 `pageAgentClientRun` 才切换 PageAgent 路径，否则
+   保持旧路径或明确不可用；
+7. 服务地址或 installation pairing 切换前调用 binding revoke，清除内存中的 grant；无法
+   联系旧服务时不得复用旧 token，等待其短 TTL 到期。
+
+Workflow Artifact Port 还要求 fresh deploy 顺序应用
+`0062_client_agent_workflow_artifact.sql`，并在 project-owned
+`client-agent-workflow-artifact-binding.ts` 登记审核后的 Workflow/Node/Operation/Artifact
+绑定。已经发布的 `0.6.14` recipe 保持不可变；既有 Starter 的 project-owned Composition
+由 `0.6.15` narrow recipe 以唯一 import/Omit/runtime property 三锚点接入。binding 缺失时
+创建新默认空 seam；只有完整匹配旧默认空 seam 才升级 release/scope/terminal authority 注释契约，客户已登记或
+任意字节漂移均在写入前停止并保留 WIP。
+
+协议没有 BYOK、用户模型选择、逐动作审批或逐目标网页 origin 授权字段。宿主配对只负责
+识别目标 Windy 服务、当前登录 actor、installation 和撤销边界。

package/template/docs/platform/embedding-ai-runtime.md

@@ -0,0 +1,94 @@
+# Embedding AI Runtime
+
+Windy 提供受治理的文本与图片 Embedding 调用边界，不提供业务向量库。业务模块仍负责向量表、索引版本、增量更新、案件权限过滤、重建和排序。
+
+## 调用链
+
+业务模块在 Manifest 注册 `kind=embedding` Operation，同时声明稳定的 Feature、Permission、License、审计动作、数据分类、输入模态、能力和预算。模块 `setup(host)` 通过 `prepareEmbedding` 生成领域选项；浏览器只调用同源 `/api/embeddings`。
+
+文本经过 Provider 数据字段治理后进入 Runtime。图片必须是当前 Actor 有权读取的 `ArtifactRef`；平台重新签发短时引用，Runtime 校验大小、哈希、MIME 和像素预算，移除元数据后才交给内网 Adapter。业务代码不能提交文件路径、任意 URL 或 Base64。
+
+`POST /api/embeddings/runs` 创建持久 Run；轮询 events/result 或取消时都会重新验证当前 Actor、Module、Feature、Permission、License 和 scope。图片 Run 在 worker 实际读图前仅以 `runId/itemId` 回调 Server；Server 从持久绑定恢复密封引用、重建当前 Guard 并刷新读取授权。客户端与 Embedding Runtime 都不能提交 Actor、scope 或新的 Artifact token。授权、资源完整性或部署限制发生漂移时，该操作 fail-closed。
+
+```ts
+const operation = {
+  key: "analysis.embedding.multimodal",
+  kind: "embedding",
+  featureKey: "analysis.embedding",
+  permissionKey: "analysis.embedding.execute",
+  licenseFeatureKey: "analysis.embedding",
+  auditAction: "analysis.embedding.execute",
+  dataClassification: "sensitive",
+  inputModalities: ["text", "image"],
+  outputModalities: ["embedding"],
+  requiredCapabilities: ["embedding.text", "embedding.image"],
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 20_000_000,
+    maxOutputBytes: 20_000_000,
+    maxUnits: 64,
+    maxArtifacts: 16,
+    maxPixelsPerArtifact: 20_000_000,
+  },
+};
+```
+
+## 固定输出契约
+
+每个批次返回稳定 `batchId`、逐项输入 SHA-256 和向量，以及由 Runtime 配置固定的：
+
+- `deploymentAlias`
+- `model`
+- `version`
+- `dimensions`
+- `normalized`
+
+Runtime 拒绝 ID/顺序漂移、维度漂移、非有限数值和与归一化声明不一致的向量。Adapter 响应不能覆盖上述部署元数据。这些字段使业务索引可重现、可判断何时需要重建。
+
+## 部署
+
+Adapter URL 只允许本机、Compose 服务名、`.internal` 或私网 IP。平台不允许把敏感输入发往任意公网端点。
+
+```dotenv
+EMBEDDING_SERVER_URL=http://embedding-server:8092
+EMBEDDING_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+EMBEDDING_RUN_ARTIFACT_URL=http://server:9747/api/internal/embeddings/runs
+EMBEDDING_ADAPTER_URL=http://embedding-adapter:9000
+EMBEDDING_ADAPTER_TOKEN=
+EMBEDDING_DEPLOYMENT_KEY=local-embedding
+EMBEDDING_DEPLOYMENT_IDENTITY=windy-deployment-v1_<uuidv4>
+EMBEDDING_RELEASE_DIGEST=sha256:<64位小写十六进制>
+EMBEDDING_OFFERS_DIGEST=sha256:<64位小写十六进制>
+EMBEDDING_DEPLOYMENT_ALIAS=intranet-multimodal-v1
+EMBEDDING_MODEL=local-model
+EMBEDDING_MODEL_VERSION=2026-07
+EMBEDDING_DIMENSIONS=1024
+EMBEDDING_NORMALIZED=true
+EMBEDDING_CAPABILITIES=embedding.text,embedding.image
+EMBEDDING_MAX_UNITS=256
+EMBEDDING_RUN_ENCRYPTION_SECRET=至少32字符的独立密钥
+EMBEDDING_MAX_CONCURRENT_RUNS=1
+EMBEDDING_MAX_QUEUE_DEPTH=0
+EMBEDDING_READINESS_TIMEOUT_SECONDS=5
+EMBEDDING_READINESS_TTL_SECONDS=60
+EMBEDDING_RUN_TERMINAL_TTL_SECONDS=604800
+```
+
+启动可选服务：
+
+```bash
+bun run dev:embedding
+```
+
+健康端点需要内部 Bearer Token，只在 `/v1/embedding/readiness` 真实探测 Adapter、
+重算完整原子 offers 与 release digest，并与配置 pin 完全一致时发布 readiness V1。
+可用 `python -m southwind_embedding_server.pin_cli` 从同一真实探测事实计算部署 pins；
+命令只输出 pins，不写 `.env`。Host 在业务 prepare、Artifact/Run 创建前固定
+deployment pin，Remote 与 Embedding Runtime 在实际调用前再次核对。未配置 Adapter、
+缺失 pin、探测失败或部署漂移时返回 503，不回退到假向量或其它模型。
+
+## 错误与审计
+
+稳定错误码包括 `INVALID_INPUT`、`FORBIDDEN`、`CAPABILITY_UNAVAILABLE`、`BUDGET_EXCEEDED`、`OUTPUT_VALIDATION_FAILED` 和 `RUNTIME_UNAVAILABLE`。错误响应不透传 Adapter 正文。
+
+成功审计记录 Operation、Actor、批次、输入数量、部署别名、模型版本、维度和归一化状态，不记录原文、图片或向量。

package/template/docs/platform/platform-authentication.md

@@ -99,14 +99,11 @@ Server 会幂等创建默认开发管理员和 `developer` 角色；仅当默认
 
 Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV_AUTH_BYPASS=1` 和非空 `VITE_DEV_ADMIN_TOKEN` 时，前端才会携带显式 Bearer Token，并在登录页和应用壳持续显示警告；生产构建无条件忽略这两个变量。完成一次真实密码登录后，当前页面生命周期内会停用开发 Token，后续请求只使用 Cookie。
 
-选择 Agent 模块的新项目会在本机 `.env` 自动生成独立随机
-`ADK_DEBUG_PLATFORM_TOKEN`。只有 `bun run dev:adk-web` 加载的开发 Compose Wrapper
-会把它作为 `WINDY_ADK_DEBUG_TOKEN` 注入 Server，并注入 localhost-only ADK Web；它
-不会复用 `WINDY_DEV_ADMIN_TOKEN`，也不会启用固定 `dev-admin-token` 或 `user:` 直通。
-Server 仅在 canonical Agent Run 路径和只读
-`GET /api/agent/debug/sessions/v1/**` 路径把它解析成 `service_adk_debug`，权限收敛为
-项目选择的 Operation 与 allowed Tools 权限闭包。该 Token 不进入 Web、Agent
-Server、Provider 或生产 Compose；非 development Server 即使误配也会拒绝。
+Agent Runtime 调试与历史会话读取复用 Windy 主站的真实登录身份，不创建第二种调试
+Token、专用服务身份或开发认证旁路。`GET /api/agent/sessions/v1/**` 按 Provider 所绑定
+Operation 的 Feature、Permission 与当前 Actor 数据范围逐次授权；主站 Runtime Report
+继续要求 `system.ai-runtime.read`。这些接口不接受 `WINDY_DEV_ADMIN_TOKEN` 以外的新型
+Bearer 方案，也不会把内部服务 Token 下发给浏览器。
 
 未配置 `DATABASE_URL` 时不会注册真实登录 API；只允许显式的非生产开发直通，不存在内存生产账号或默认生产密码。
 

package/template/package.json

@@ -20,7 +20,6 @@
     "dev:speech": "PLATFORM_ENABLE_AI=true SPEECH_SERVER_URL=http://speech-server:8091 docker compose --profile agent --profile speech up --build",
     "speech:pins": "bun run scripts/provision-speech-readiness.ts",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
-    "dev:adk-web": "bun run scripts/dev-adk-web.ts",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",

package/template/packages/ai-client/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/agent/index.js";
+export * from "./src/client-agent/index.js";
 export type { ArtifactRef } from "./src/artifact-ref.js";
 export * from "./src/document/index.js";
 export * from "./src/embedding/index.js";

package/template/packages/ai-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/ai-client",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -18,6 +18,8 @@
   "exports": {
     ".": "./index.ts",
     "./agent": "./src/agent/index.ts",
+    "./client-agent": "./src/client-agent/index.ts",
+    "./client-agent/workflow-artifact": "./src/client-agent/workflow-artifact/index.ts",
     "./contracts": "./src/agent/contracts/index.ts",
     "./document": "./src/document/index.ts",
     "./embedding": "./src/embedding/index.ts",

package/template/packages/ai-client/src/agent/client/client.ts

@@ -74,6 +74,7 @@ export class HttpAgentCaller implements AgentCaller {
       ...(options.screenshotIntakeToken
         ? { screenshotIntakeToken: options.screenshotIntakeToken }
         : {}),
+      ...(options.sessionId ? { sessionId: options.sessionId } : {}),
     };
     let response: Response;
     try {
@@ -103,6 +104,7 @@ export class HttpAgentCaller implements AgentCaller {
     const created = parseCreatedRun(await safeJson(response, "创建 Agent Run"));
     return this.createRun(operation, created.runId, created.eventsUrl, {
       signal: options.signal,
+      sessionId: options.sessionId,
     });
   }
 
@@ -120,7 +122,11 @@ export class HttpAgentCaller implements AgentCaller {
         {
           method: "POST",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ operationKey: operation.key, cursor }),
+          body: JSON.stringify({
+            operationKey: operation.key,
+            cursor,
+            ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+          }),
           signal: options.signal,
         },
       );
@@ -154,6 +160,7 @@ export class HttpAgentCaller implements AgentCaller {
       signal: options.signal,
       initialSequence: cursor,
       initialTerminal: attached.terminalEvent,
+      sessionId: options.sessionId,
     });
   }
 
@@ -173,9 +180,15 @@ export class HttpAgentCaller implements AgentCaller {
       signal?: AbortSignal;
       initialSequence?: number;
       initialTerminal?: TerminalAgentEvent;
+      sessionId?: string;
     },
   ): AgentRun<Output> {
-    const operationQuery = `operationKey=${encodeURIComponent(operation.key)}`;
+    const operationQuery = [
+      `operationKey=${encodeURIComponent(operation.key)}`,
+      ...(state.sessionId
+        ? [`sessionId=${encodeURIComponent(state.sessionId)}`]
+        : []),
+    ].join("&");
     return new HttpAgentRun<Output>({
       id: runId,
       eventsUrl: this.endpoint(eventsPath),

package/template/packages/ai-client/src/agent/client/run-protocol.test.ts

@@ -29,17 +29,31 @@ describe("Agent Run protocol safety", () => {
     expect(fake.calls).toBe(1);
   });
 
-  test("跨 chunk 解析 heartbeat 和事件 frame", async () => {
-    const started = frame({
-      type: "run.started",
-      runId: "run-chunks",
-      sequence: 1,
-    });
-    const completed = frame({
-      type: "run.completed",
-      runId: "run-chunks",
-      sequence: 2,
-    });
+  test("从 sequence 0 跨 chunk 解码完整 canonical 事件流", async () => {
+    const canonicalEvents: AgentEvent[] = [
+      { type: "run.started", runId: "run-chunks", sequence: 1 },
+      {
+        type: "input.prepared",
+        runId: "run-chunks",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: ["text"],
+      },
+      {
+        type: "output.delta",
+        runId: "run-chunks",
+        sequence: 3,
+        text: "完成",
+      },
+      {
+        type: "usage.reported",
+        runId: "run-chunks",
+        sequence: 4,
+        usage: { source: "unknown" },
+      },
+      { type: "run.completed", runId: "run-chunks", sequence: 5 },
+    ];
+    const stream = `: heartbeat\n\n${canonicalEvents.map(frame).join("")}`;
     const fake = plannedFetch([
       () =>
         json({
@@ -47,23 +61,21 @@ describe("Agent Run protocol safety", () => {
           status: "accepted",
           eventsUrl: "/events",
         }),
-      () =>
-        sse([
-          ": heart",
-          "beat\n\n" + started.slice(0, 9),
-          started.slice(9) + completed.slice(0, 17),
-          completed.slice(17),
-        ]),
+      (input, init) => {
+        const url = new URL(
+          input instanceof Request ? input.url : input.toString(),
+        );
+        expect(url.searchParams.has("after")).toBe(false);
+        expect(new Headers(init?.headers).has("last-event-id")).toBe(false);
+        return sse([stream.slice(0, 8), stream.slice(8, 41), stream.slice(41)]);
+      },
       () => json({ runId: "run-chunks", status: "completed", output: "ok" }),
     ]);
     const run = await start(fake.fetch, "chunks");
     const events = collect(run.events);
 
     await expect(run.result()).resolves.toBe("ok");
-    expect((await events).map(({ type }) => type)).toEqual([
-      "run.started",
-      "run.completed",
-    ]);
+    expect(await events).toEqual(canonicalEvents);
   });
 
   test("run.failed 返回 canonical 安全错误且不请求 result", async () => {
@@ -186,16 +198,18 @@ function start(fetch: AgentFetch, idempotencyKey: string) {
   }).start(operation, null, { idempotencyKey });
 }
 
-function plannedFetch(plans: Array<() => Response>): {
+function plannedFetch(
+  plans: Array<(...args: Parameters<AgentFetch>) => Response>,
+): {
   fetch: AgentFetch;
   readonly calls: number;
 } {
   let calls = 0;
   return {
-    fetch: async () => {
+    fetch: async (...args) => {
       const plan = plans[calls++];
       if (!plan) throw new Error("unexpected fetch");
-      return plan();
+      return plan(...args);
     },
     get calls() {
       return calls;

package/template/packages/ai-client/src/agent/client/types.ts

@@ -7,11 +7,15 @@ export interface StartAgentRunOptions {
   artifacts?: readonly ArtifactRef[];
   /** Host-issued one-shot screenshot intake; never an Artifact URL or Run owner. */
   screenshotIntakeToken?: string;
+  /** 可选的长期 Session；服务端会重新校验当前 Actor 与授权范围。 */
+  sessionId?: string;
   signal?: AbortSignal;
 }
 
 export interface AttachAgentRunOptions {
   cursor?: number;
+  /** 恢复长期 Session 关联；服务端仍会校验 Run、Actor 与 Scope。 */
+  sessionId?: string;
   signal?: AbortSignal;
 }