create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,232 @@
+import type {
+  ClientAgentWorkflowArtifactRecord,
+  ClientAgentWorkflowClaimBinding,
+} from "./contracts.js";
+import type { ArtifactRef } from "@southwind-ai/storage";
+import {
+  type ClientAgentWorkflowArtifactRepository,
+  sameWorkflowArtifactIdentity,
+} from "./repository.js";
+
+export class InMemoryClientAgentWorkflowArtifactRepository implements ClientAgentWorkflowArtifactRepository {
+  readonly #records = new Map<string, ClientAgentWorkflowArtifactRecord>();
+
+  async begin(record: ClientAgentWorkflowArtifactRecord) {
+    const existing = this.#records.get(record.workId);
+    if (existing) {
+      if (!sameWorkflowArtifactIdentity(existing, record)) throw conflict();
+      return clone(existing);
+    }
+    if (
+      [...this.#records.values()].some(
+        (value) =>
+          value.commandId === record.commandId ||
+          value.durableJobId === record.durableJobId,
+      )
+    ) {
+      throw conflict();
+    }
+    this.#records.set(record.workId, clone(record));
+    return clone(record);
+  }
+
+  async find(workId: string) {
+    return optional(this.#records.get(workId));
+  }
+
+  async findByJob(durableJobId: string) {
+    return optional(
+      [...this.#records.values()].find(
+        (record) => record.durableJobId === durableJobId,
+      ),
+    );
+  }
+
+  async authorizeClientSessionAttempt(
+    input: Parameters<
+      ClientAgentWorkflowArtifactRepository["authorizeClientSessionAttempt"]
+    >[0],
+  ) {
+    const current = [...this.#records.values()].find(
+      (record) => record.clientSessionId === input.clientSessionId,
+    );
+    if (!current) return "ordinary" as const;
+    return current.status === "claimed" &&
+      Boolean(current.claimExpiresAt && current.claimExpiresAt > input.now) &&
+      current.actorId === input.actorId &&
+      current.operationKey === input.operationKey &&
+      current.clientBindingDigest === input.clientBindingDigest &&
+      current.hostSessionDigest === input.hostSessionDigest
+      ? ("current" as const)
+      : ("revoked" as const);
+  }
+
+  async findForActorRun(input: { actorId: string; runId: string }) {
+    return optional(
+      [...this.#records.values()].find(
+        (record) =>
+          record.actorId === input.actorId && record.runId === input.runId,
+      ),
+    );
+  }
+
+  async claim(input: {
+    workId: string;
+    expectedVersion: number;
+    allowActiveTakeover?: boolean;
+    binding: ClientAgentWorkflowClaimBinding;
+  }) {
+    const current = this.#records.get(input.workId);
+    if (!current || current.version !== input.expectedVersion) {
+      return { outcome: "conflict" as const };
+    }
+    if (current.status === "completed" || current.status === "cancelled") {
+      return { outcome: current.status, record: clone(current) } as const;
+    }
+    if (
+      current.status !== "pending" &&
+      (current.status !== "claimed" || !input.allowActiveTakeover)
+    ) {
+      return { outcome: "busy" as const, record: clone(current) };
+    }
+    const previousClientSessionId = current.clientSessionId;
+    const updated: ClientAgentWorkflowArtifactRecord = {
+      ...current,
+      ...input.binding,
+      status: "claimed",
+      claimGeneration: current.claimGeneration + 1,
+      clientSessionId: undefined,
+      version: current.version + 1,
+      updatedAt: input.binding.now,
+    };
+    this.#records.set(current.workId, clone(updated));
+    return {
+      outcome: "claimed" as const,
+      record: clone(updated),
+      ...(previousClientSessionId ? { previousClientSessionId } : {}),
+    };
+  }
+
+  async bindClientSession(input: {
+    workId: string;
+    claimGeneration: number;
+    clientSessionId: string;
+    now: number;
+  }) {
+    const current = this.#records.get(input.workId);
+    if (
+      !current ||
+      current.status !== "claimed" ||
+      current.claimGeneration !== input.claimGeneration ||
+      current.clientSessionId
+    ) {
+      return undefined;
+    }
+    const updated = {
+      ...current,
+      clientSessionId: input.clientSessionId,
+      version: current.version + 1,
+      updatedAt: input.now,
+    };
+    this.#records.set(current.workId, clone(updated));
+    return clone(updated);
+  }
+
+  async complete(
+    input: Parameters<ClientAgentWorkflowArtifactRepository["complete"]>[0],
+  ) {
+    const current = this.#records.get(input.workId);
+    if (
+      !current ||
+      current.status !== "claimed" ||
+      current.claimGeneration !== input.terminal.claimGeneration ||
+      current.clientSessionId !== input.terminal.clientSessionId ||
+      current.claimTokenHash !== input.claimTokenHash
+    ) {
+      return undefined;
+    }
+    const updated: ClientAgentWorkflowArtifactRecord = {
+      ...current,
+      ...input.terminal,
+      status: "completed",
+      version: current.version + 1,
+      updatedAt: input.terminal.now,
+      finishedAt: input.terminal.now,
+    };
+    this.#records.set(current.workId, clone(updated));
+    return clone(updated);
+  }
+
+  async requestCancel(input: { workId: string; now: number }) {
+    const current = this.#records.get(input.workId);
+    if (!current) return undefined;
+    if (current.status === "cancelled") return clone(current);
+    if (current.status === "completed") return undefined;
+    if (current.status === "cancellation-requested") return clone(current);
+    const updated: ClientAgentWorkflowArtifactRecord = {
+      ...current,
+      status: "cancellation-requested",
+      cancelRequestedAt: input.now,
+      version: current.version + 1,
+      updatedAt: input.now,
+    };
+    this.#records.set(current.workId, clone(updated));
+    return clone(updated);
+  }
+
+  async finalizeCancel(input: { workId: string; now: number }) {
+    const current = this.#records.get(input.workId);
+    if (!current) return undefined;
+    if (current.status === "cancelled") return clone(current);
+    if (current.status !== "cancellation-requested") return undefined;
+    const updated: ClientAgentWorkflowArtifactRecord = {
+      ...current,
+      status: "cancelled",
+      finishedAt: input.now,
+      version: current.version + 1,
+      updatedAt: input.now,
+    };
+    this.#records.set(current.workId, clone(updated));
+    return clone(updated);
+  }
+
+  async listClaimedByHost(input: {
+    actorId: string;
+    hostSessionDigest: `sha256:${string}`;
+  }) {
+    return [...this.#records.values()]
+      .filter(
+        (record) =>
+          record.actorId === input.actorId &&
+          record.hostSessionDigest === input.hostSessionDigest &&
+          ["claimed", "cancellation-requested"].includes(record.status),
+      )
+      .map(clone);
+  }
+
+  async listActiveArtifactRefs(_now: Date): Promise<ArtifactRef[]> {
+    return [...this.#records.values()].flatMap((record) =>
+      record.status === "completed" && record.artifact
+        ? [record.artifact.artifactRef]
+        : [],
+    );
+  }
+
+  async listCancellationRequested() {
+    return [...this.#records.values()]
+      .filter((record) => record.status === "cancellation-requested")
+      .map(clone);
+  }
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function optional<T>(value: T | undefined) {
+  return value === undefined ? undefined : clone(value);
+}
+
+function conflict() {
+  return new Error("CLIENT_AGENT_WORKFLOW_IDENTITY_CONFLICT");
+}

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

@@ -0,0 +1,101 @@
+import type {
+  ModuleClientAgentWorkflowArtifactBeginSpec,
+  ModuleClientAgentWorkflowArtifactCommand,
+  ModuleClientAgentWorkflowArtifactPort,
+  ModuleClientAgentWorkflowArtifactView,
+} from "@southwind-ai/server-sdk";
+import { digestJson } from "../client-session/digest.js";
+import type {
+  ClientAgentWorkflowArtifactBinding,
+  ClientAgentWorkflowArtifactRecord,
+} from "./contracts.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+import type { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+
+export class GovernedClientAgentWorkflowArtifactJobPort implements ModuleClientAgentWorkflowArtifactPort {
+  #record: ClientAgentWorkflowArtifactRecord;
+
+  constructor(
+    private readonly service: GovernedClientAgentWorkflowArtifactService,
+    private readonly jobId: string,
+    readonly binding: ClientAgentWorkflowArtifactBinding,
+    record: ClientAgentWorkflowArtifactRecord,
+    private readonly signal: AbortSignal,
+  ) {
+    this.#record = record;
+  }
+
+  async begin(spec: ModuleClientAgentWorkflowArtifactBeginSpec) {
+    if (digestJson(spec.input) !== this.#record.inputDigest) throw invalid();
+    return view(this.#record, this.binding.artifact.kind);
+  }
+
+  async claimOrAdvance(command: ModuleClientAgentWorkflowArtifactCommand) {
+    this.requireCommand(command);
+    const current = await this.service.reconcileOrCancel({
+      jobId: this.jobId,
+      cancel: false,
+      signal: this.signal,
+    });
+    if (!current) throw invalid();
+    this.#record = current;
+    return view(current, this.binding.artifact.kind);
+  }
+
+  async reconcileOrCancel(command: ModuleClientAgentWorkflowArtifactCommand) {
+    this.requireCommand(command);
+    const current = await this.service.reconcileOrCancel({
+      jobId: this.jobId,
+      cancel: this.signal.aborted && this.signal.reason === "cancelled",
+      signal: this.signal,
+    });
+    if (!current) throw invalid();
+    this.#record = current;
+    return view(current, this.binding.artifact.kind);
+  }
+
+  get record() {
+    return this.#record;
+  }
+
+  private requireCommand(command: ModuleClientAgentWorkflowArtifactCommand) {
+    if (command.value !== this.#record.workId) throw invalid();
+  }
+}
+
+function view(
+  record: ClientAgentWorkflowArtifactRecord,
+  artifactKind: string,
+): ModuleClientAgentWorkflowArtifactView {
+  const status =
+    record.status === "claimed"
+      ? "running"
+      : record.status === "cancellation-requested"
+        ? "cancelled"
+        : record.status;
+  return {
+    command: { value: record.workId },
+    status,
+    ...(record.artifact
+      ? {
+          artifact: {
+            artifactId: record.workId,
+            kind: artifactKind,
+            contentType: record.artifact.contentType,
+            filename: record.artifact.filename,
+            byteSize: record.artifact.byteSize,
+            sha256: record.artifact.sha256,
+          },
+        }
+      : {}),
+    ...(status === "cancelled" ? { safeCode: "WORK_CANCELLED" as const } : {}),
+  };
+}
+
+function invalid() {
+  return new ClientAgentWorkflowArtifactError(
+    "NOT_FOUND",
+    "Workflow Client Agent command 已失效",
+    404,
+  );
+}

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

@@ -0,0 +1,41 @@
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import type { ClientAgentWorkflowJobPayload } from "./workflow-loader.js";
+
+export function clientWorkflowPayloadOf(
+  record: ClientAgentWorkflowArtifactRecord,
+): ClientAgentWorkflowJobPayload {
+  return {
+    commandId: record.commandId,
+    runId: record.runId,
+    nodeRunId: record.nodeRunId,
+    effectGeneration: record.effectGeneration,
+    requestDigest: record.requestDigest,
+  };
+}
+
+export function clientWorkflowPublicView(
+  record: ClientAgentWorkflowArtifactRecord,
+  artifactKind = "structured-data",
+) {
+  const status =
+    record.status === "claimed" || record.status === "cancellation-requested"
+      ? "running"
+      : record.status;
+  return {
+    workId: record.workId,
+    status,
+    claimVersion: record.claimGeneration,
+    ...(record.status === "completed" && record.artifact
+      ? {
+          artifact: {
+            artifactId: record.workId,
+            kind: artifactKind,
+            contentType: record.artifact.contentType,
+            filename: record.artifact.filename,
+            byteSize: record.artifact.byteSize,
+            sha256: record.artifact.sha256,
+          },
+        }
+      : {}),
+  };
+}

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

@@ -0,0 +1,253 @@
+import { describe, expect, test } from "bun:test";
+import { MemoryBlobStore } from "@southwind-ai/storage";
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import { digestText } from "../client-session/digest.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import { InMemoryClientAgentWorkflowArtifactRepository } from "./in-memory-repository.js";
+import { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+import { fenceResumableClientWorkflowClaim } from "./takeover.js";
+import {
+  clientBindingDigest,
+  guardContext,
+  principal,
+  workflowLoader,
+  workflowRecord,
+  workflowSignal,
+} from "./workflow-artifact.test-support.js";
+
+const claimToken = `cawc_${"t".repeat(43)}`;
+
+describe("Governed Client Agent Workflow Artifact cancellation recovery", () => {
+  test("takeover 在清除旧 Session bridge 前先持久撤销", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const claimed = await seedClaimed(repository, workflowRecord());
+    const revoked: string[] = [];
+    const allowed = await fenceResumableClientWorkflowClaim({
+      record: claimed,
+      binding: {
+        clientBindingDigest,
+        installationId: principal.installationId,
+        hostSessionDigest: hostSessionDigest(principal),
+      },
+      sessionRepository: {
+        find: async () => ({
+          attemptCount: 0,
+          activeRequests: 0,
+          receipts: [],
+        }),
+      } as unknown as ClientSessionRepository,
+      sessions: {
+        revokeSession: async (sessionId: string) => {
+          expect((await repository.find(claimed.workId))?.clientSessionId).toBe(
+            sessionId,
+          );
+          revoked.push(sessionId);
+        },
+      } as unknown as GovernedClientAgentSessionService,
+      repository,
+      now: 1_050,
+    });
+
+    expect(allowed).toBe(true);
+    expect(revoked).toEqual([claimed.clientSessionId]);
+  });
+
+  test("过期 takeover 在换代前撤销旧 Session，发现 attempt 时吸收取消", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const claimed = await seedClaimed(repository, workflowRecord());
+    await expect(
+      fenceResumableClientWorkflowClaim({
+        record: claimed,
+        binding: {
+          clientBindingDigest: `sha256:${"x".repeat(64)}`,
+          installationId: "replacement-installation",
+          hostSessionDigest: `sha256:${"y".repeat(64)}`,
+        },
+        sessionRepository: {
+          find: async () => ({
+            attemptCount: 1,
+            activeRequests: 0,
+            receipts: [],
+          }),
+        } as unknown as ClientSessionRepository,
+        sessions: {
+          revokeSession: async (sessionId: string) => {
+            expect(
+              (await repository.find(claimed.workId))?.clientSessionId,
+            ).toBe(sessionId);
+          },
+        } as unknown as GovernedClientAgentSessionService,
+        repository,
+        now: 61_000,
+      }),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    expect((await repository.find(claimed.workId))?.status).toBe("cancelled");
+  });
+
+  test("取消先持久 cancellation-requested，再 revoke Session 并进入吸收态", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const claimed = await seedClaimed(repository, workflowRecord());
+    const revokeStates: string[] = [];
+    const service = createService(repository, async (sessionId) => {
+      expect(sessionId).toBe(claimed.clientSessionId);
+      revokeStates.push((await repository.find(claimed.workId))!.status);
+    });
+
+    const cancelled = await service.cancelClaim({
+      workId: claimed.workId,
+      claimVersion: claimed.claimGeneration,
+      claimToken,
+      principal,
+      guardContext,
+      signal: workflowSignal,
+    });
+
+    expect(revokeStates).toEqual(["cancellation-requested"]);
+    expect(cancelled.status).toBe("cancelled");
+    expect((await repository.find(claimed.workId))?.status).toBe("cancelled");
+    await expect(
+      service.advance({
+        workId: claimed.workId,
+        claimVersion: claimed.claimGeneration,
+        claimToken,
+        receiptIds: ["late-receipt"],
+        principal,
+        guardContext,
+        signal: workflowSignal,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+  });
+
+  test("host revoke 只取消同 Actor 与 host binding 的全部领取", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const first = await seedClaimed(repository, workflowRecord());
+    const second = await seedClaimed(
+      repository,
+      workflowRecord({
+        workId: "cawa_work-2",
+        commandId: "command-2",
+        durableJobId: "job-2",
+        runId: "run-2",
+        nodeRunId: "node-run-2",
+        requestDigest: "sha256:request-2",
+        effectFenceTokenDigest: "sha256:fence-2",
+      }),
+    );
+    const revoked: string[] = [];
+    const service = createService(repository, async (sessionId) => {
+      revoked.push(sessionId);
+    });
+
+    await expect(service.revokeHost(principal)).resolves.toBe(2);
+    expect(revoked.sort()).toEqual(
+      [first.clientSessionId!, second.clientSessionId!].sort(),
+    );
+    expect((await repository.find(first.workId))?.status).toBe("cancelled");
+    expect((await repository.find(second.workId))?.status).toBe("cancelled");
+  });
+
+  test("host revoke 单条失败仍继续撤销同 Host 的后续领取", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const first = await seedClaimed(repository, workflowRecord());
+    const second = await seedClaimed(
+      repository,
+      workflowRecord({
+        workId: "cawa_work-host-retry",
+        commandId: "command-host-retry",
+        durableJobId: "job-host-retry",
+        runId: "run-host-retry",
+        nodeRunId: "node-run-host-retry",
+        requestDigest: "sha256:request-host-retry",
+        effectFenceTokenDigest: "sha256:fence-host-retry",
+      }),
+    );
+    const calls: string[] = [];
+    const service = createService(repository, async (sessionId) => {
+      calls.push(sessionId);
+      if (sessionId === first.clientSessionId) throw new Error("host offline");
+    });
+
+    await expect(service.revokeHost(principal)).rejects.toBeInstanceOf(
+      AggregateError,
+    );
+    expect(calls.sort()).toEqual(
+      [first.clientSessionId!, second.clientSessionId!].sort(),
+    );
+    expect((await repository.find(second.workId))?.status).toBe("cancelled");
+  });
+
+  test("重启从稳定 cancellation intent 恢复，不重新 create/finalize Session", async () => {
+    const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+    const claimed = await seedClaimed(repository, workflowRecord());
+    await repository.requestCancel({ workId: claimed.workId, now: 1_100 });
+    const calls: string[] = [];
+
+    const restarted = createService(repository, async (sessionId, cause) => {
+      calls.push(`revoke:${sessionId}:${cause}`);
+      expect((await repository.find(claimed.workId))?.status).toBe(
+        "cancellation-requested",
+      );
+    });
+    const recovered = await restarted.reconcileOrCancel({
+      jobId: claimed.durableJobId,
+      cancel: false,
+      signal: workflowSignal,
+    });
+
+    expect(calls).toEqual([
+      `revoke:${claimed.clientSessionId}:workflow-cancel-recovery`,
+    ]);
+    expect(recovered?.status).toBe("cancelled");
+  });
+});
+
+async function seedClaimed(
+  repository: InMemoryClientAgentWorkflowArtifactRepository,
+  record: ReturnType<typeof workflowRecord>,
+) {
+  const pending = await repository.begin(record);
+  const claimed = await repository.claim({
+    workId: pending.workId,
+    expectedVersion: pending.version,
+    binding: {
+      clientBindingDigest,
+      installationId: principal.installationId,
+      hostSessionDigest: hostSessionDigest(principal),
+      claimTokenHash: digestText(claimToken),
+      claimExpiresAt: 60_000,
+      now: 1_001,
+    },
+  });
+  if (claimed.outcome !== "claimed") throw new Error("claim failed");
+  const bound = await repository.bindClientSession({
+    workId: pending.workId,
+    claimGeneration: claimed.record.claimGeneration,
+    clientSessionId: `cas_${pending.workId}`,
+    now: 1_002,
+  });
+  if (!bound) throw new Error("session bind failed");
+  return bound;
+}
+
+function createService(
+  repository: InMemoryClientAgentWorkflowArtifactRepository,
+  revoke: (sessionId: string, cause: string) => Promise<void>,
+) {
+  const sessions = {
+    revokeSession: revoke,
+  } as unknown as GovernedClientAgentSessionService;
+  const sessionRepository = {
+    find: async () => undefined,
+  } as unknown as ClientSessionRepository;
+  return new GovernedClientAgentWorkflowArtifactService(
+    repository,
+    workflowLoader(),
+    sessions,
+    sessionRepository,
+    new MemoryBlobStore(),
+    new ClientAgentWorkflowTaskAuthority(),
+    () => 2_000,
+  );
+}