create-windy 0.6.14 → 0.6.16

package/package.json

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

package/template/.agents/skills/windy-business-module/SKILL.md

@@ -44,8 +44,8 @@ description: "在 Windy 或 create-windy 生成项目中新增或修改业务 Mo
    - 流式写入和大报告分别使用可选 Storage Writer / Report Staging Port、显式 policy
      与 `require*()` helper；Tool 不继承 Writer，缺少 `system.storage` 时直接说明物理
      裁剪边界。
-   **完成标准：业务代码未注入 UploadRepository、BlobStore、Secret locator 或平台
-   manage Repository，缺失 Port 会稳定 fail closed。**
+     **完成标准：业务代码未注入 UploadRepository、BlobStore、Secret locator 或平台
+     manage Repository，缺失 Port 会稳定 fail closed。**
 7. 业务资源含敏感字段时，在 Manifest 声明 Data Policy、standard read、
    sensitive-disclosure reveal、governed-export Permission 和对应 API，再用
    `registerGovernedResources()` 注册对象授权、脱敏投影、受控字段读取与分页 Source。
@@ -67,17 +67,66 @@ description: "在 Windy 或 create-windy 生成项目中新增或修改业务 Mo
     和可选 readiness pin。`system.agent` 的面向用户回答使用平台 Supervisor typed
     final-answer 契约；Durable Handler 只通过 Actor-aware 后台 AI Port 恢复同一幂等
     Run。浏览器或桌面宿主本地编排模型循环时使用 governed Client Agent Session，不向
-    客户端下发 Provider Secret 或 execution grant。**完成标准：Operation 的声明、
-    Handler、发布坐标、输出投影和运行边界一致。**
+    客户端下发 Provider Secret 或 execution grant。Workflow 需要 PageAgent 产物时复用固定
+    `system.agent-workflow.client-agent-artifact` Job taskKey，并在 project-owned Composition
+    登记唯一 Workflow/Node/Operation/Artifact binding；业务 Handler 不直接取得 Client Agent
+    Session、Host Auth、BlobStore 或内部 Durable Context Port。Workflow 专用 Operation 声明
+    `launchAuthority="workflow-artifact"`；binding 登记 scope contract、project launch、
+    client task 与 terminal authority 的静态 version/digest。受保护 Workflow 只能走未暴露为
+    通用路由的 `agentWorkflowProjects` Seam；通用 release/run 即使 digest 相同也 fail closed。
+    claim 的 raw input Artifact 只在 Host 当前重授权后交给 client task authority，Web/Extension
+    只消费 ai-client 严格解析后的有界 canonical task，不自行拼 ArtifactRef、locator 或 prompt。
+    模块把 Storage/JSON 作为下游 Workflow input 时，Route 先经两阶段
+    `workflowInputMaterialization.begin/resolve` 等待真实 Job succeeded，Handler 再用
+    `workflowInputArtifacts` 正式发布，不得把 fileId 当 artifactId；固定 Manifest task 只注册
+    同 key/feature/permission/audit 的 Durable Handler，不额外注册 scheduled no-op。
+    **完成标准：Operation 的声明、
+    Handler、固定 taskKey、项目绑定、发布坐标、输出投影和运行边界一致。**
 11. 补齐 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约覆盖；按
     条件覆盖 Durable 重试/恢复、Tool 未授权发现/调用、资源文件、Secret、治理导出、
-    可选模块裁剪、Sandbox 隔离和 AI 恢复。**完成标准：每个新增能力至少有成功路径、
-    关键拒绝路径和声明/实现漂移检查。**
+    可选模块裁剪、Sandbox 隔离和 AI 恢复。Client Agent Workflow 还要覆盖 pending/fence
+    原子提交、短期 claim、稳定 receipt/Blob putOnce/Durable publishArtifactOnce、两阶段取消与
+    重启恢复。**完成标准：每个新增能力至少有成功路径、关键拒绝路径和声明/实现漂移检查。**
 12. 更新长期文档，并按当前仓库 `AGENTS.md` 与 `package.json` 分层验证。windy-platform
     普通小提交只运行允许的静态检查；合并候选统一运行 `test:merge`，冻结发版候选才运行
     一次 `release:verify`。仅当项目提供 `lint` 脚本时运行 lint；一个 cohesive slice 一个
     Conventional Commit。**完成标准：验证层级、未执行项和提交 SHA 均可审计。**
 
+## Client Agent Workflow 重复故障解法
+
+- 跨层 opaque ID 必须选一个 canonical prefix，并同步 Server 生成器、public SDK、客户端
+  validator、样例与文档；不要用“兼容多个前缀”隐藏漂移。
+- 新增 Drizzle Migration 必须同步 SQL、schema、journal 和 snapshot；snapshot `prevId` 精确指向
+  前一 snapshot `id`，并用仓库锁定版本独立再生成比对。
+- Workflow fence 必须约束每一次 Provider attempt：预留前、出网紧前和在途期间从 canonical
+  Run/Node/command/generation/fence 与当前授权复核；撤销或 checker 不确定时先 revoke Session。
+- Session finalize 到 Blob/bridge complete 是明确崩溃窗；恢复只读 completed Session 的 receipt、
+  final result 和 terminal digest，确定性 `putOnce`/complete，禁止等待浏览器或重放 Provider。
+- completed replay 必须持久化并比较 `receiptIds + result` 的 canonical terminal request digest；
+  完全一致才幂等，任何漂移 fail closed。
+- completed replay 使用 terminal-safe authorization：继续复核当前 Actor/RBAC/Scope、claim/Host/
+  Session 与原 Release/Definition/command 不可变坐标，但不能重新要求 command 为 dispatched 或
+  Run active；撤权隐藏、摘要漂移冲突。
+- Workflow PageAgent project binding 必须 pin 审核 Release 的 `releaseDigest`；loader 验证固定
+  taskKey Job 唯一，且只有无 branch/fallback/skip 的 `job -> artifact -> final` 直接链，Artifact
+  kind/policy 与绑定一致。新 Release 必须重新审核，不能静默继承旧权限。
+- 不要用当前 scope digest 等于冻结 Run digest 作为多案授权证明。Host 读取持久 Job scope，验证
+  当前 canonical Actor scope 包含冻结范围；只允许当前更宽或相等，不恢复冻结范围以外权限。
+- terminal authority 的 binding digest 只包含稳定 version/digest，不包含函数；拒绝发生在 Session
+  completed transition 前；它必须收到 terminal-time 重新授权并打开的 canonical JSON input artifacts，
+  不能只看 output schema。普通 Run/Session create 必须同时拒绝 workflow-only Operation。
+- project launch authority 必须接收 Host capture 的 `currentAuthorizationScope`，只返回它的收窄范围；
+  Host 再做 containment。业务代码不得硬编码或猜 tenant、roleIds、grants。
+- pre-start Workflow input 物化必须是两阶段：Request Context coordinator `begin` 提交固定模块
+  materializer 的真实 Durable Job，`resolve` 仅在 succeeded 且 publication/source metadata 完全匹配
+  时返回 refs；begin、Durable payload 与 worker publication 共用 strict parser，mode 字段互斥且拒绝
+  unknown/unsafe/超预算 JSON。ready 后业务 prepare 仍重读 sourceIds 并逐项匹配，Workflow start
+  再复验 Artifact。
+- Targeted patch 新增 project-owned seam 时，连续 recipe 必须覆盖 public source 缺失、精确旧默认空、
+  精确新默认空和客户修改四态。binding 用完整字节白名单；Composition 的 import/type/runtime property
+  作为原子唯一锚点组。任何部分装配、重复、换行/注释漂移或非空客户 binding 都在写入前 fail closed；
+  未选择所属可选模块时不得注入 seam。candidate regression 固定以上一公开版本为直接来源。
+
 ## 项目所有权与自动装配
 
 - `apps/web/src`、`apps/server/src/app`、业务模块源码和 `windy.modules.json` 都是
@@ -98,7 +147,8 @@ description: "在 Windy 或 create-windy 生成项目中新增或修改业务 Mo
   `packages/server-sdk/src/request-context.ts`、`packages/server-sdk/src/durable-handler.ts`
 - Tool 与 AI：`packages/server-sdk/src/tool-registration.ts`、
   `packages/server-sdk/src/sandbox-tool.ts`、
-  `packages/server-sdk/src/ai-operation-registration.ts`
+  `packages/server-sdk/src/ai-operation-registration.ts`、
+  `packages/server-sdk/src/client-agent-workflow-artifact.ts`
 - Secret、Storage 与治理：`packages/server-sdk/src/secret-port.ts`、
   `packages/server-sdk/src/secret-binding.ts`、`packages/server-sdk/src/storage-port.ts`、
   `packages/server-sdk/src/report-staging-port.ts`、
@@ -111,7 +161,7 @@ description: "在 Windy 或 create-windy 生成项目中新增或修改业务 Mo
 - 条件能力：`docs/architecture/module-secret-resolution.md`、
   `docs/architecture/report-staging.md`、`docs/platform/governed-export-renderers.md`、
   `docs/platform/agent-tool-approval.md`、`docs/platform/background-ai-operations.md`、
-  `docs/platform/client-agent-session.md`
+  `docs/platform/client-agent-session.md`、`docs/architecture/agent-workflow.md`
 
 某个事实源或 `system.agent` / `system.storage` 不存在时，先说明当前生成组合的物理边界，
 不在业务层补一套替代实现。

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "74fc88e548934dbda773291c4ad078d16a5396d1",
-  "generatorVersion": "0.6.14",
+  "templateCommit": "8e1d09815139887e150b7ed51d5b974879b1ec54",
+  "generatorVersion": "0.6.16",
   "modules": [
     {
       "name": "system",

package/template/apps/server/src/agent/client-session/attempt-authority.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test";
+import { createFixture, validCompletion } from "./service.test-support.js";
+import { consumeClientAgentCompletion } from "./completion.js";
+
+describe("Client Session Provider attempt authority", () => {
+  test("普通 Session 经 Host checker 明确分类后保持原 completion 行为", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return "ordinary";
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).resolves.toBeDefined();
+    expect(fixture.provider.requests).toHaveLength(1);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("active");
+  });
+
+  test("每个 Workflow Session attempt 出网前复核，漂移先撤销且不调用 Provider", async () => {
+    let decision = "current" as "current" | "revoked";
+    let checks = 0;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check(facts) {
+          checks += 1;
+          expect(facts).toMatchObject({
+            actorId: "actor-1",
+            operationKey: "support.answer",
+          });
+          return decision;
+        },
+      },
+    });
+
+    await fixture.complete(validCompletion());
+    decision = "revoked";
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    expect(checks).toBe(4);
+    expect(fixture.provider.requests).toHaveLength(1);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后 authority 漂移仍在真正 Provider 出网紧前阻断", async () => {
+    let checks = 0;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          checks += 1;
+          return checks === 1 ? "current" : "revoked";
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(checks).toBe(2);
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后当前授权漂移也在真正 Provider 出网紧前阻断", async () => {
+    let revokeCurrentAuthorization: () => void = () => undefined;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          revokeCurrentAuthorization();
+          return "current";
+        },
+      },
+    });
+    revokeCurrentAuthorization = () => {
+      fixture.admission.allowed = false;
+    };
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后 Session 被 takeover 撤销时，generator 不得开始 Provider", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return "current";
+        },
+      },
+    });
+    const completion = await fixture.service.startCompletion(
+      fixture.grant.sessionId,
+      validCompletion(),
+      fixture.caller,
+    );
+    await fixture.repository.transition(
+      fixture.grant.sessionId,
+      "active",
+      "revoked",
+    );
+
+    await expect(
+      consumeClientAgentCompletion(completion.events),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    expect(fixture.provider.requests).toHaveLength(0);
+  });
+
+  test("Provider 返回后 fence 漂移时不提交迟到 receipt", async () => {
+    let decision = "current" as "current" | "revoked";
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return decision;
+        },
+      },
+      execute: async () => {
+        decision = "revoked";
+        return {
+          choices: [{ message: { role: "assistant", content: "late" } }],
+        };
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.receipts,
+    ).toHaveLength(0);
+    expect(fixture.provider.requests).toHaveLength(1);
+  });
+
+  test("authority checker 异常同样 fail closed 且不产生 Provider attempt", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          throw new Error("database unavailable");
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+});

package/template/apps/server/src/agent/client-session/attempt-authority.ts

@@ -0,0 +1,191 @@
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
+  ClientSessionAttemptAuthorityDecision,
+  ClientSessionRecord,
+} from "./contracts.js";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { clientSessionConflict } from "./errors.js";
+import type { ClientSessionRepository } from "./repository.js";
+
+export type ClientSessionAttemptRevocationCause =
+  | "authorization-drift"
+  | "authorization-check-failed"
+  | "ttl"
+  | "workflow-authority"
+  | "workflow-authority-check-failed";
+
+export interface ClientSessionAttemptAuthorityHostChecker extends ClientSessionAttemptAuthorityChecker {
+  checkTransaction?(
+    transaction: NodePgDatabase,
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    now: number,
+  ): Promise<ClientSessionAttemptAuthorityDecision>;
+}
+
+/** 启动时先创建 binding，Workflow runtime 完成装配后再绑定唯一 Host checker。 */
+export class ClientSessionAttemptAuthorityBinding implements ClientSessionAttemptAuthorityChecker {
+  #checker?: ClientSessionAttemptAuthorityHostChecker;
+
+  bind(checker: ClientSessionAttemptAuthorityHostChecker): () => void {
+    if (this.#checker) {
+      throw new Error("Client Session attempt authority checker 重复绑定");
+    }
+    this.#checker = checker;
+    return () => {
+      if (this.#checker === checker) this.#checker = undefined;
+    };
+  }
+
+  check(
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    signal?: AbortSignal,
+  ): Promise<ClientSessionAttemptAuthorityDecision> {
+    return this.#checker?.check(facts, signal) ?? Promise.resolve("ordinary");
+  }
+
+  checkTransaction(
+    transaction: NodePgDatabase,
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    now: number,
+  ) {
+    return this.#checker?.checkTransaction
+      ? this.#checker.checkTransaction(transaction, facts, now)
+      : (this.#checker?.check(facts) ?? Promise.resolve("ordinary" as const));
+  }
+}
+
+export async function enforceClientSessionAttemptAuthority(input: {
+  checker: ClientSessionAttemptAuthorityChecker;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  signal?: AbortSignal;
+  workflowOwned: boolean;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}): Promise<boolean> {
+  let decision: ClientSessionAttemptAuthorityDecision;
+  try {
+    decision = await input.checker.check(
+      clientSessionAttemptAuthorityFacts(input.record),
+      input.signal,
+    );
+  } catch {
+    await revoke(input, "workflow-authority-check-failed");
+    throw clientSessionConflict("Client Agent 会话 authority 校验失败");
+  }
+  if (decision === "current") return true;
+  if (decision === "ordinary" && !input.workflowOwned) return false;
+  await revoke(input, "workflow-authority");
+  throw clientSessionConflict("Client Agent 会话 authority 已失效");
+}
+
+export async function enforceClientSessionCurrentAuthorization(input: {
+  admission: ClientSessionAdmissionPort;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  attempt?: number;
+  now: number;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}) {
+  const canonical = await input.repository.find(input.record.sessionId);
+  if (!canonical || canonical.status !== "active") {
+    throw clientSessionConflict("Client Agent 会话已关闭");
+  }
+  if (
+    input.attempt !== undefined &&
+    !canonical.pendingAttempts.includes(input.attempt)
+  ) {
+    await revokeCurrentAuthorization(input, canonical);
+    throw clientSessionConflict("Client Agent attempt 已失效");
+  }
+  let cause: ClientSessionAttemptRevocationCause | undefined;
+  if (canonical.expiresAt <= input.now) {
+    cause = "ttl";
+  } else {
+    try {
+      cause = (await input.admission.reauthorize(canonical, canonical.actorId))
+        ? undefined
+        : "authorization-drift";
+    } catch {
+      cause = "authorization-check-failed";
+    }
+  }
+  if (!cause) return;
+  const status = cause === "ttl" ? "expired" : "revoked";
+  const closed = await input.repository.transition(
+    canonical.sessionId,
+    "active",
+    status,
+  );
+  if (closed) await input.audit(closed, cause);
+  throw clientSessionConflict("Client Agent 会话当前授权已失效");
+}
+
+export async function enforceClientSessionProviderBoundary(input: {
+  admission: ClientSessionAdmissionPort;
+  checker: ClientSessionAttemptAuthorityChecker;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  attempt?: number;
+  now: number;
+  signal?: AbortSignal;
+  workflowOwned: boolean;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}) {
+  await enforceClientSessionCurrentAuthorization(input);
+  if (!input.workflowOwned) return;
+  await enforceClientSessionAttemptAuthority({
+    checker: input.checker,
+    record: input.record,
+    repository: input.repository,
+    ...(input.signal ? { signal: input.signal } : {}),
+    workflowOwned: true,
+    audit: input.audit,
+  });
+}
+
+async function revokeCurrentAuthorization(
+  input: Parameters<typeof enforceClientSessionCurrentAuthorization>[0],
+  canonical: ClientSessionRecord,
+) {
+  const revoked = await input.repository.transition(
+    canonical.sessionId,
+    "active",
+    "revoked",
+  );
+  if (revoked) await input.audit(revoked, "authorization-check-failed");
+}
+
+export function clientSessionAttemptAuthorityFacts(
+  record: ClientSessionRecord,
+) {
+  return {
+    sessionId: record.sessionId,
+    clientRunId: record.clientRunId,
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    clientBindingDigest: record.clientBindingDigest,
+    hostSessionDigest: record.hostSessionDigest,
+  };
+}
+
+async function revoke(
+  input: Parameters<typeof enforceClientSessionAttemptAuthority>[0],
+  cause: ClientSessionAttemptRevocationCause,
+) {
+  const revoked = await input.repository.transition(
+    input.record.sessionId,
+    "active",
+    "revoked",
+  );
+  if (revoked) await input.audit(revoked, cause);
+}

package/template/apps/server/src/agent/client-session/bootstrap.ts

@@ -21,6 +21,7 @@ import {
   createClientAgentHostAuthRouteApp,
   hostSessionDigest,
 } from "./host-auth.js";
+import { ClientSessionAttemptAuthorityBinding } from "./attempt-authority.js";
 
 export function createClientAgentSessionRuntime(input: {
   app: RouteApp;
@@ -38,12 +39,21 @@ export function createClientAgentSessionRuntime(input: {
     registerUnavailableClientAgentSessionRoutes(
       createManifestAuthorizedRouteApp(input.app, input.routeAuthorizer),
     );
-    return { service: undefined, dispose: undefined };
+    return {
+      service: undefined,
+      repository: undefined,
+      hostApp: undefined,
+      attemptAuthority: undefined,
+      revokeHost: undefined,
+      dispose: undefined,
+    };
   }
+  const attemptAuthority = new ClientSessionAttemptAuthorityBinding();
+  const repository = input.db
+    ? new DrizzleClientSessionRepository(input.db, attemptAuthority)
+    : new InMemoryClientSessionRepository();
   const service = new GovernedClientAgentSessionService(
-    input.db
-      ? new DrizzleClientSessionRepository(input.db)
-      : new InMemoryClientSessionRepository(),
+    repository,
     new ManifestClientSessionAdmission(
       input.modules,
       input.hosts,
@@ -64,6 +74,7 @@ export function createClientAgentSessionRuntime(input: {
     }),
     new RuntimeClientSessionAudit(input.runtime),
     trustedBaseUrl(),
+    attemptAuthority,
   );
   const hostApp = createClientAgentHostAuthRouteApp({
     app: input.app,
@@ -75,13 +86,18 @@ export function createClientAgentSessionRuntime(input: {
     createManifestAuthorizedRouteApp(hostApp, input.routeAuthorizer),
     service,
   );
-  const unbind = input.hostAuth.bindRevocations(async (principal) => {
-    await service.revokeHostSession(
-      hostSessionDigest(principal),
-      principal.actorId,
-    );
-  });
-  return { service, dispose: unbind };
+  return {
+    service,
+    repository,
+    hostApp,
+    attemptAuthority,
+    revokeHost: (principal: Parameters<typeof hostSessionDigest>[0]) =>
+      service.revokeHostSession(
+        hostSessionDigest(principal),
+        principal.actorId,
+      ),
+    dispose: undefined,
+  };
 }
 
 function trustedBaseUrl(): string {