create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/client-workflow-artifact/release-binding.ts

@@ -0,0 +1,85 @@
+import {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY,
+  type ModuleClientAgentWorkflowArtifactProjectBinding,
+} from "@southwind-ai/server-sdk";
+import type {
+  AgentWorkflowDefinition,
+  AgentWorkflowNode,
+  AgentWorkflowRelease,
+} from "@southwind-ai/shared";
+
+/** PageAgent 权限只属于显式审核的 Immutable Release 与固定三节点拓扑。 */
+export function assertClientAgentWorkflowReleaseBinding(
+  release: AgentWorkflowRelease,
+  binding: ModuleClientAgentWorkflowArtifactProjectBinding,
+) {
+  const definition = release.definition;
+  const pageAgentJobs = definition.nodes.filter(
+    (node) =>
+      node.type === "job" &&
+      node.taskKey === CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY,
+  );
+  const job = pageAgentJobs[0];
+  if (
+    release.releaseDigest !== binding.releaseDigest ||
+    definition.workflowKey !== binding.workflowKey ||
+    pageAgentJobs.length !== 1 ||
+    !job ||
+    job.id !== binding.nodeId ||
+    !failClosed(job)
+  ) {
+    invalid();
+  }
+  const artifact = uniqueSuccessor(definition, job, "artifact");
+  if (
+    artifact.artifactKind !== binding.artifact.kind ||
+    artifact.policyKey !== binding.artifact.retentionPolicyKey ||
+    !failClosed(artifact)
+  ) {
+    invalid();
+  }
+  const final = uniqueSuccessor(definition, artifact, "final");
+  if (!failClosed(final) || outgoing(definition, final.id).length) invalid();
+}
+
+function uniqueSuccessor<T extends "artifact" | "final">(
+  definition: AgentWorkflowDefinition,
+  source: AgentWorkflowNode,
+  type: T,
+): Extract<AgentWorkflowNode, { type: T }> {
+  const edges = outgoing(definition, source.id);
+  const edge = edges[0];
+  const node = definition.nodes.find(({ id }) => id === edge?.to);
+  const incoming = node
+    ? definition.edges.filter(({ to }) => to === node.id)
+    : [];
+  if (
+    edges.length !== 1 ||
+    !edge ||
+    edge.branch !== undefined ||
+    !node ||
+    node.type !== type ||
+    incoming.length !== 1 ||
+    incoming[0]?.from !== source.id ||
+    incoming[0]?.branch !== undefined
+  ) {
+    invalid();
+  }
+  return node as Extract<AgentWorkflowNode, { type: T }>;
+}
+
+function outgoing(definition: AgentWorkflowDefinition, nodeId: string) {
+  return definition.edges.filter(({ from }) => from === nodeId);
+}
+
+function failClosed(node: AgentWorkflowNode) {
+  return (
+    node.failurePolicy.mode === "fail-run" ||
+    (node.failurePolicy.mode === "retry" &&
+      node.failurePolicy.exhausted === "fail-run")
+  );
+}
+
+function invalid(): never {
+  throw new Error("CLIENT_AGENT_WORKFLOW_RELEASE_BINDING_INVALID");
+}

package/template/apps/server/src/agent/client-workflow-artifact/repository.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from "bun:test";
+import type { ArtifactRef } from "@southwind-ai/storage";
+import { InMemoryClientAgentWorkflowArtifactRepository } from "./in-memory-repository.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+
+describe("Client Agent Workflow Artifact lifecycle", () => {
+  test("pending 先持久化，claim generation 使旧领取失效", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const pending = await repository.begin(record());
+    expect(pending.status).toBe("pending");
+    const first = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: pending.version,
+      binding: claim("sha256:first", 200),
+    });
+    expect(first.outcome).toBe("claimed");
+    if (first.outcome !== "claimed") throw new Error("claim failed");
+    const busy = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: first.record.version,
+      binding: claim("sha256:busy", 199),
+    });
+    expect(busy.outcome).toBe("busy");
+    const expiredWithoutFence = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: first.record.version,
+      binding: claim("sha256:second", 201),
+    });
+    expect(expiredWithoutFence.outcome).toBe("busy");
+    const takeover = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: first.record.version,
+      allowActiveTakeover: true,
+      binding: claim("sha256:second", 201),
+    });
+    expect(takeover.outcome).toBe("claimed");
+    if (takeover.outcome !== "claimed") throw new Error("takeover failed");
+    expect(takeover.record.claimGeneration).toBe(2);
+  });
+
+  test("completed 与 cancelled 为吸收态，迟到写 fail closed", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const pending = await repository.begin(record());
+    const claimed = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: pending.version,
+      binding: claim("sha256:claim", 200),
+    });
+    if (claimed.outcome !== "claimed") throw new Error("claim failed");
+    const bound = await repository.bindClientSession({
+      workId: pending.workId,
+      claimGeneration: 1,
+      clientSessionId: "cas_1",
+      now: 101,
+    });
+    expect(bound?.clientSessionId).toBe("cas_1");
+    const completed = await repository.complete({
+      workId: pending.workId,
+      claimTokenHash: "sha256:claim",
+      terminal: {
+        claimGeneration: 1,
+        clientSessionId: "cas_1",
+        historySequence: 1,
+        historyHeadDigest: "sha256:history",
+        terminalReceiptId: "cawr_terminal",
+        terminalReceiptDigest: "sha256:terminal",
+        terminalRequestDigest: "sha256:request-terminal",
+        terminalResult: { result: "ok" },
+        artifact: {
+          artifactRef: "blob_11111111111111111111111111111111" as ArtifactRef,
+          filename: "result.json",
+          contentType: "application/json",
+          byteSize: 2,
+          sha256: "1".repeat(64),
+        },
+        now: 102,
+      },
+    });
+    expect(completed?.status).toBe("completed");
+    expect(
+      await repository.requestCancel({ workId: pending.workId, now: 103 }),
+    ).toBe(undefined);
+    expect(
+      await repository.complete({
+        workId: pending.workId,
+        claimTokenHash: "sha256:stale",
+        terminal: {
+          claimGeneration: 1,
+          clientSessionId: "cas_1",
+          historySequence: 1,
+          historyHeadDigest: "sha256:stale",
+          terminalReceiptId: "cawr_stale",
+          terminalReceiptDigest: "sha256:stale",
+          terminalRequestDigest: "sha256:stale-request",
+          terminalResult: { result: "late" },
+          artifact: completed!.artifact!,
+          now: 104,
+        },
+      }),
+    ).toBe(undefined);
+  });
+
+  test("取消先持久 intent，再进入吸收终态", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const pending = await repository.begin(record());
+    const requested = await repository.requestCancel({
+      workId: pending.workId,
+      now: 101,
+    });
+    expect(requested?.status).toBe("cancellation-requested");
+    const cancelled = await repository.finalizeCancel({
+      workId: pending.workId,
+      now: 102,
+    });
+    expect(cancelled?.status).toBe("cancelled");
+    expect(
+      await repository.finalizeCancel({ workId: pending.workId, now: 103 }),
+    ).toEqual(cancelled);
+  });
+
+  test("attempt authority 绑定 Session、Actor、Operation、client 与 Host digest", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const pending = await repository.begin(record());
+    const claimed = await repository.claim({
+      workId: pending.workId,
+      expectedVersion: pending.version,
+      binding: claim("sha256:claim", 101),
+    });
+    if (claimed.outcome !== "claimed") throw new Error("claim failed");
+    await repository.bindClientSession({
+      workId: pending.workId,
+      claimGeneration: claimed.record.claimGeneration,
+      clientSessionId: "cas_authority",
+      now: 102,
+    });
+    const facts = {
+      clientSessionId: "cas_authority",
+      actorId: "actor-1",
+      operationKey: "analysis.page-agent",
+      clientBindingDigest: "sha256:binding" as const,
+      hostSessionDigest: "sha256:host" as const,
+      now: 103,
+    };
+
+    await expect(repository.authorizeClientSessionAttempt(facts)).resolves.toBe(
+      "current",
+    );
+    await expect(
+      repository.authorizeClientSessionAttempt({
+        ...facts,
+        actorId: "actor-drift",
+      }),
+    ).resolves.toBe("revoked");
+    await expect(
+      repository.authorizeClientSessionAttempt({
+        ...facts,
+        clientSessionId: "cas_ordinary",
+      }),
+    ).resolves.toBe("ordinary");
+    await repository.requestCancel({ workId: pending.workId, now: 104 });
+    await expect(repository.authorizeClientSessionAttempt(facts)).resolves.toBe(
+      "revoked",
+    );
+  });
+});
+
+function record(): ClientAgentWorkflowArtifactRecord {
+  return {
+    workId: "cawa_work",
+    commandId: "command-1",
+    durableJobId: "job-1",
+    runId: "run-1",
+    nodeRunId: "node-run-1",
+    effectKind: "job",
+    taskKey: "system.agent-workflow.client-agent-artifact",
+    operationKey: "analysis.page-agent",
+    bindingDigest: "sha256:binding-policy",
+    actorId: "actor-1",
+    scopeDigest: "sha256:scope",
+    authorizationSnapshotDigest: "sha256:authorization",
+    runPolicyDigest: "sha256:policy",
+    requestDigest: "sha256:request",
+    inputDigest: "sha256:input",
+    effectGeneration: 1,
+    effectFenceTokenDigest: "sha256:fence",
+    status: "pending",
+    claimGeneration: 0,
+    historySequence: 0,
+    version: 1,
+    createdAt: 100,
+    updatedAt: 100,
+  };
+}
+
+function claim(token: `sha256:${string}`, now: number) {
+  return {
+    clientBindingDigest: "sha256:binding" as const,
+    installationId: "installation-1",
+    hostSessionDigest: "sha256:host" as const,
+    claimTokenHash: token,
+    claimExpiresAt: 200,
+    now,
+  };
+}

package/template/apps/server/src/agent/client-workflow-artifact/repository.ts

@@ -0,0 +1,97 @@
+import type {
+  ClientAgentWorkflowArtifactRecord,
+  ClientAgentWorkflowClaimBinding,
+  ClientAgentWorkflowTerminalInput,
+} from "./contracts.js";
+import type { ArtifactRef } from "@southwind-ai/storage";
+
+export type ClientAgentWorkflowClaimResult =
+  | {
+      readonly outcome: "claimed";
+      readonly record: ClientAgentWorkflowArtifactRecord;
+      readonly previousClientSessionId?: string;
+    }
+  | {
+      readonly outcome: "busy" | "completed" | "cancelled" | "conflict";
+      readonly record?: ClientAgentWorkflowArtifactRecord;
+    };
+
+export interface ClientAgentWorkflowArtifactRepository {
+  begin(
+    record: ClientAgentWorkflowArtifactRecord,
+  ): Promise<ClientAgentWorkflowArtifactRecord>;
+  find(workId: string): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  findByJob(
+    durableJobId: string,
+  ): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  authorizeClientSessionAttempt(input: {
+    clientSessionId: string;
+    actorId: string;
+    operationKey: string;
+    clientBindingDigest: `sha256:${string}`;
+    hostSessionDigest: `sha256:${string}`;
+    now: number;
+  }): Promise<"ordinary" | "current" | "revoked">;
+  findForActorRun(input: {
+    actorId: string;
+    runId: string;
+  }): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  claim(input: {
+    workId: string;
+    expectedVersion: number;
+    allowActiveTakeover?: boolean;
+    binding: ClientAgentWorkflowClaimBinding;
+  }): Promise<ClientAgentWorkflowClaimResult>;
+  bindClientSession(input: {
+    workId: string;
+    claimGeneration: number;
+    clientSessionId: string;
+    now: number;
+  }): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  complete(input: {
+    workId: string;
+    claimTokenHash: `sha256:${string}`;
+    terminal: ClientAgentWorkflowTerminalInput;
+  }): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  requestCancel(input: {
+    workId: string;
+    now: number;
+  }): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  finalizeCancel(input: {
+    workId: string;
+    now: number;
+  }): Promise<ClientAgentWorkflowArtifactRecord | undefined>;
+  listClaimedByHost(input: {
+    actorId: string;
+    hostSessionDigest: `sha256:${string}`;
+  }): Promise<readonly ClientAgentWorkflowArtifactRecord[]>;
+  listCancellationRequested(): Promise<
+    readonly ClientAgentWorkflowArtifactRecord[]
+  >;
+  listActiveArtifactRefs(now: Date): Promise<ArtifactRef[]>;
+}
+
+export function sameWorkflowArtifactIdentity(
+  left: ClientAgentWorkflowArtifactRecord,
+  right: ClientAgentWorkflowArtifactRecord,
+) {
+  return (
+    left.workId === right.workId &&
+    left.commandId === right.commandId &&
+    left.durableJobId === right.durableJobId &&
+    left.runId === right.runId &&
+    left.nodeRunId === right.nodeRunId &&
+    left.effectKind === right.effectKind &&
+    left.taskKey === right.taskKey &&
+    left.operationKey === right.operationKey &&
+    left.bindingDigest === right.bindingDigest &&
+    left.actorId === right.actorId &&
+    left.scopeDigest === right.scopeDigest &&
+    left.authorizationSnapshotDigest === right.authorizationSnapshotDigest &&
+    left.runPolicyDigest === right.runPolicyDigest &&
+    left.requestDigest === right.requestDigest &&
+    left.inputDigest === right.inputDigest &&
+    left.effectGeneration === right.effectGeneration &&
+    left.effectFenceTokenDigest === right.effectFenceTokenDigest
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/routes-handler.contract.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DurableHandlerRegistry,
+  type DurableHandlerContext,
+} from "@southwind-ai/jobs";
+import { artifactRef } from "@southwind-ai/storage";
+import type { RouteApp } from "../../system/routes.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import { registerClientAgentWorkflowArtifactHandler } from "./handler.js";
+import { registerClientAgentWorkflowArtifactRoutes } from "./routes.js";
+import type { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import {
+  clientBindingDigest,
+  guardContext,
+  principal,
+  workflowBinding,
+  workflowInput,
+  workflowRecord,
+} from "./workflow-artifact.test-support.js";
+
+describe("Governed Client Agent Workflow Artifact routes", () => {
+  test("Route 拒绝 Provider 坐标注入，且只把 canonical Host principal 交给 Service", async () => {
+    const calls: unknown[] = [];
+    const service = {
+      claim: async (input: unknown) => {
+        calls.push(input);
+        return { workId: "cawa_work-1", status: "running", claimVersion: 1 };
+      },
+    } as unknown as GovernedClientAgentWorkflowArtifactService;
+    const app = captureRoutes();
+    registerClientAgentWorkflowArtifactRoutes(app, service);
+    const handler = app.handlers.get("/agent/client-workflow-artifacts/claim")!;
+    const context = {
+      request: new Request("https://windy.example/claim", { method: "POST" }),
+      guardContext,
+      clientAgentHost: {
+        principal,
+        hostSessionDigest: hostSessionDigest(principal),
+      },
+    };
+
+    const rejected = await handler({
+      ...context,
+      body: {
+        workflowRunId: "run-1",
+        clientBindingDigest,
+        providerUrl: "https://attacker.example/v1",
+      },
+    });
+    expect(rejected).toBeInstanceOf(Response);
+    expect((rejected as Response).status).toBe(400);
+    expect(calls).toHaveLength(0);
+
+    await expect(
+      handler({
+        ...context,
+        body: { workflowRunId: "run-1", clientBindingDigest },
+      }),
+    ).resolves.toMatchObject({ status: "running", claimVersion: 1 });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      workflowRunId: "run-1",
+      clientBindingDigest,
+      principal,
+      guardContext,
+    });
+  });
+});
+
+describe("Governed Client Agent Workflow Artifact durable publication", () => {
+  test("completed retry 与 Worker 重启只按 terminal receipt publishArtifactOnce", async () => {
+    const { handler, beginCalls } = completedHandler();
+    const publications = new Map<
+      string,
+      { readonly artifactRef: string; readonly sha256: string }
+    >();
+    let publishOnceCalls = 0;
+    const context = durableContext({
+      publishArtifactOnce: async (publicationKey, artifact) => {
+        publishOnceCalls++;
+        const existing = publications.get(publicationKey);
+        const value = {
+          artifactRef: artifact.artifactRef,
+          sha256: artifact.sha256,
+        };
+        if (existing && JSON.stringify(existing) !== JSON.stringify(value)) {
+          throw new Error("publication identity conflict");
+        }
+        publications.set(publicationKey, existing ?? value);
+        return {
+          schemaVersion: 1,
+          publicationKey,
+          artifactId: "artifact-stable-1",
+          jobId: context.jobId,
+          stageKey: context.stageKey,
+          kind: artifact.kind,
+          artifactRef: artifact.artifactRef,
+          sha256: artifact.sha256,
+        };
+      },
+    });
+
+    await handler.execute(jobPayload(), context);
+    await handler.execute(jobPayload(), context);
+
+    expect(beginCalls.value).toBe(2);
+    expect(publishOnceCalls).toBe(2);
+    expect(publications.size).toBe(1);
+    expect([...publications.keys()]).toEqual(["cawr_terminal-1"]);
+  });
+
+  test("stable publication 未装配时 fail closed，不回退到可重放 publishArtifact", async () => {
+    const { handler } = completedHandler();
+    let fallbackCalls = 0;
+    const context = durableContext({
+      publishArtifact: async () => {
+        fallbackCalls++;
+      },
+    });
+
+    await expect(handler.execute(jobPayload(), context)).rejects.toMatchObject({
+      code: "STABLE_ARTIFACT_PUBLICATION_UNAVAILABLE",
+      retryable: false,
+    });
+    expect(fallbackCalls).toBe(0);
+  });
+});
+
+function completedHandler() {
+  const beginCalls = { value: 0 };
+  const record = workflowRecord({
+    status: "completed",
+    claimGeneration: 1,
+    historySequence: 1,
+    historyHeadDigest: "sha256:history-1",
+    terminalReceiptId: "cawr_terminal-1",
+    terminalReceiptDigest: "sha256:terminal-1",
+    terminalResult: { result: { answer: "完成" } },
+    artifact: {
+      artifactRef: artifactRef(`blob_${"a".repeat(32)}`),
+      filename: workflowBinding.artifact.filename,
+      contentType: workflowBinding.artifact.contentType,
+      byteSize: 18,
+      sha256: "a".repeat(64),
+    },
+    finishedAt: 1_100,
+  });
+  const service = {
+    begin: async () => {
+      beginCalls.value++;
+      return { record, input: workflowInput, binding: workflowBinding };
+    },
+  } as unknown as GovernedClientAgentWorkflowArtifactService;
+  const registry = new DurableHandlerRegistry();
+  registerClientAgentWorkflowArtifactHandler({ registry, service });
+  const handler = registry.get(record.taskKey);
+  if (!handler) throw new Error("handler registration failed");
+  return { handler, beginCalls };
+}
+
+function jobPayload() {
+  const record = workflowRecord();
+  return {
+    commandId: record.commandId,
+    runId: record.runId,
+    nodeRunId: record.nodeRunId,
+    effectGeneration: record.effectGeneration,
+    requestDigest: record.requestDigest,
+  };
+}
+
+function durableContext(
+  patch: Partial<DurableHandlerContext>,
+): DurableHandlerContext {
+  return {
+    jobId: "job-1",
+    stageKey: "main",
+    attemptNumber: 1,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => {
+      throw new Error("unstable publication must not be used");
+    },
+    ...patch,
+  };
+}
+
+function captureRoutes() {
+  const handlers = new Map<string, (context: unknown) => Promise<unknown>>();
+  const app = {
+    handlers,
+    get: () => undefined,
+    post: (path: string, handler: (context: unknown) => unknown) => {
+      handlers.set(path, async (context) => handler(context));
+    },
+    put: () => undefined,
+    delete: () => undefined,
+  } as unknown as RouteApp & { readonly handlers: typeof handlers };
+  return app;
+}