create-windy 0.6.14 → 0.6.15

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

@@ -0,0 +1,345 @@
+import { describe, expect, test } from "bun:test";
+import { MemoryBlobStore } from "@southwind-ai/storage";
+import {
+  createFixture,
+  validCompletion,
+} from "../client-session/service.test-support.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import { buildScopeContext } from "../../data-access/context.js";
+import { InMemoryClientAgentWorkflowArtifactRepository } from "./in-memory-repository.js";
+import { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+import {
+  clientBindingDigest,
+  guardContext,
+  principal,
+  workflowBinding,
+  workflowLoader,
+  workflowRecord,
+  workflowSignal,
+} from "./workflow-artifact.test-support.js";
+
+describe("Governed Client Agent Workflow Artifact service contract", () => {
+  test("authority 与 effect fence 复验后才持久化 pending，再签发短期 claim", async () => {
+    const fixture = await createWorkflowFixture();
+
+    const begun = await fixture.service.begin({
+      jobId: "job-1",
+      payload: {
+        commandId: "command-1",
+        runId: "run-1",
+        nodeRunId: "node-run-1",
+        effectGeneration: 1,
+        requestDigest: workflowRecord().requestDigest,
+      },
+      signal: workflowSignal,
+    });
+
+    expect(fixture.trace).toEqual([
+      "authority-fence-current",
+      "persist-pending",
+    ]);
+    expect(begun.record).toMatchObject({
+      status: "pending",
+      effectGeneration: 1,
+      effectFenceTokenDigest: workflowRecord().effectFenceTokenDigest,
+    });
+
+    const claimed = await fixture.service.claim(claimInput());
+    expect(claimed).toMatchObject({ status: "running", claimVersion: 1 });
+    if (!("sessionGrant" in claimed) || !("claimToken" in claimed)) {
+      throw new Error("claim grant missing");
+    }
+    expect(claimed.claimToken).toStartWith("cawc_");
+    expect(claimed.sessionGrant).toMatchObject({
+      modelAlias: "windy-default",
+      capabilities: ["pageAgentClientRun"],
+    });
+    expect(JSON.stringify(claimed)).not.toContain("providerUrl");
+    expect(JSON.stringify(claimed)).not.toContain("apiKey");
+  });
+
+  test("receipt chain 只写一次 stable Blob，completed retry 不重放页面副作用", async () => {
+    const fixture = await createWorkflowFixture();
+    await begin(fixture.service);
+    const claimed = await fixture.service.claim(claimInput());
+    if (!("sessionGrant" in claimed) || !("claimToken" in claimed)) {
+      throw new Error("claim grant missing");
+    }
+    const completion = await fixture.sessions.service.complete(
+      claimed.sessionGrant.sessionId,
+      validCompletion(),
+      {
+        token: claimed.sessionGrant.accessToken,
+        actorId: principal.actorId,
+        clientBindingDigest,
+        hostSessionDigest: hostSessionDigest(principal),
+      },
+    );
+    const input = {
+      workId: claimed.workId,
+      claimVersion: claimed.claimVersion,
+      claimToken: claimed.claimToken,
+      receiptIds: [completion.receipt.receiptId],
+      result: { answer: "客户端投影" },
+      principal,
+      guardContext,
+      signal: workflowSignal,
+    } as const;
+
+    const completed = await fixture.service.advance(input);
+    expect(completed).toMatchObject({ status: "completed" });
+    expect(fixture.blobs.size).toBe(1);
+    const persisted = await fixture.repository.find(claimed.workId);
+    expect(persisted).toMatchObject({
+      status: "completed",
+      historySequence: 1,
+      terminalReceiptId: expect.stringMatching(/^cawr_/),
+      terminalReceiptDigest: expect.stringMatching(/^sha256:/),
+      artifact: { sha256: expect.stringMatching(/^[a-f0-9]{64}$/) },
+    });
+
+    fixture.loaderState.active = false;
+    await expect(fixture.service.advance(input)).resolves.toEqual(completed);
+    expect(fixture.trace.at(-1)).toBe("terminal-authority-current");
+    await expect(
+      fixture.service.advance({ ...input, result: { answer: "漂移" } }),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    await expect(
+      fixture.service.advance({ ...input, receiptIds: ["receipt_drift"] }),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    await expect(
+      fixture.service.advance({
+        ...input,
+        guardContext: {
+          ...guardContext,
+          actor: { ...guardContext.actor, permissionKeys: [] },
+        },
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    const driftedScope = buildScopeContext(principal.actorId, undefined, [
+      {
+        id: "role-drifted",
+        code: "drifted",
+        dataScope: "tenant",
+        departmentIds: [],
+      },
+    ]);
+    await expect(
+      fixture.service.advance({
+        ...input,
+        guardContext: {
+          ...guardContext,
+          actor: {
+            ...guardContext.actor,
+            dataAccess: driftedScope,
+            scopeContext: driftedScope,
+          },
+        },
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    expect(fixture.blobs.size).toBe(1);
+    expect(fixture.sessions.provider.requests).toHaveLength(1);
+  });
+
+  test("Session finalize 后桥接前崩溃，重启只读终态恢复 Blob 与桥接", async () => {
+    const fixture = await createWorkflowFixture();
+    await begin(fixture.service);
+    const claimed = await fixture.service.claim(claimInput());
+    if (!("sessionGrant" in claimed) || !("claimToken" in claimed)) {
+      throw new Error("claim grant missing");
+    }
+    const completion = await fixture.sessions.service.complete(
+      claimed.sessionGrant.sessionId,
+      validCompletion(),
+      {
+        token: claimed.sessionGrant.accessToken,
+        actorId: principal.actorId,
+        clientBindingDigest,
+        hostSessionDigest: hostSessionDigest(principal),
+      },
+    );
+    const receiptIds = [completion.receipt.receiptId];
+    await fixture.sessions.service.finalizeWorkflow(
+      claimed.sessionGrant.sessionId,
+      {
+        actorId: principal.actorId,
+        clientBindingDigest,
+        hostSessionDigest: hostSessionDigest(principal),
+      },
+      receiptIds,
+      { answer: "客户端投影" },
+      async (proposedResult) =>
+        workflowBinding.terminalResultAuthority.canonicalize({
+          workflowInput: { question: "研判当前页面线索" },
+          inputArtifacts: [],
+          proposedResult,
+          actorId: principal.actorId,
+          scopeDigest: workflowRecord().scopeDigest,
+          signal: workflowSignal,
+        }),
+    );
+    const interrupted = await fixture.repository.find(claimed.workId);
+    expect(interrupted?.status).toBe("claimed");
+    expect(interrupted?.artifact).toBeUndefined();
+    expect(fixture.blobs.size).toBe(0);
+
+    const restarted = new GovernedClientAgentWorkflowArtifactService(
+      fixture.repository,
+      fixture.loader,
+      fixture.sessions.service,
+      fixture.sessions.repository,
+      fixture.blobs,
+      new ClientAgentWorkflowTaskAuthority(),
+      () => fixture.sessions.clock.value,
+    );
+    const recovered = await restarted.reconcileOrCancel({
+      jobId: "job-1",
+      cancel: false,
+      signal: workflowSignal,
+    });
+    expect(recovered).toMatchObject({
+      status: "completed",
+      terminalRequestDigest: expect.stringMatching(/^sha256:/),
+      artifact: { artifactRef: expect.stringMatching(/^blob_/) },
+    });
+    await expect(
+      restarted.reconcileOrCancel({
+        jobId: "job-1",
+        cancel: false,
+        signal: workflowSignal,
+      }),
+    ).resolves.toEqual(recovered);
+    expect(fixture.blobs.size).toBe(1);
+    expect(fixture.sessions.provider.requests).toHaveLength(1);
+  });
+
+  test("旧 claim generation 与 token 在 takeover 后失去 attempt authority", async () => {
+    const fixture = await createWorkflowFixture();
+    await begin(fixture.service);
+    const first = await fixture.service.claim(claimInput());
+    const second = await fixture.service.claim(claimInput());
+    if (
+      !("claimToken" in first) ||
+      !("sessionGrant" in first) ||
+      !("claimToken" in second)
+    ) {
+      throw new Error("claim grant missing");
+    }
+    expect(second.claimVersion).toBe(2);
+    await expect(
+      fixture.service.advance({
+        workId: first.workId,
+        claimVersion: first.claimVersion,
+        claimToken: first.claimToken,
+        receiptIds: ["receipt-from-stale-attempt"],
+        principal,
+        guardContext,
+        signal: workflowSignal,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    expect(
+      (await fixture.sessions.repository.find(first.sessionGrant.sessionId))
+        ?.status,
+    ).toBe("revoked");
+    expect(fixture.sessions.provider.requests).toHaveLength(0);
+  });
+
+  test("canonical Workflow authority 漂移时，Provider attempt 出网前 fail closed", async () => {
+    const fixture = await createWorkflowFixture();
+    await begin(fixture.service);
+    const claimed = await fixture.service.claim(claimInput());
+    if (!("sessionGrant" in claimed)) throw new Error("claim grant missing");
+    await fixture.repository.requestCancel({
+      workId: claimed.workId,
+      now: fixture.sessions.clock.value,
+    });
+
+    await expect(
+      fixture.sessions.service.complete(
+        claimed.sessionGrant.sessionId,
+        validCompletion(),
+        {
+          token: claimed.sessionGrant.accessToken,
+          actorId: principal.actorId,
+          clientBindingDigest,
+          hostSessionDigest: hostSessionDigest(principal),
+        },
+      ),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    expect(fixture.sessions.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.sessions.repository.find(claimed.sessionGrant.sessionId))
+        ?.status,
+    ).toBe("revoked");
+  });
+});
+
+async function createWorkflowFixture() {
+  const trace: string[] = [];
+  const loaderState = { active: true, terminal: true };
+  class TraceRepository extends InMemoryClientAgentWorkflowArtifactRepository {
+    override async begin(record: ReturnType<typeof workflowRecord>) {
+      trace.push("persist-pending");
+      return super.begin(record);
+    }
+  }
+  const repository = new TraceRepository();
+  const sessions = await createFixture({
+    attemptAuthority: {
+      async check(facts) {
+        const current = await repository.findForActorRun({
+          actorId: facts.actorId,
+          runId: "run-1",
+        });
+        if (!current) return "ordinary";
+        return current.status === "claimed" &&
+          current.clientSessionId === facts.sessionId &&
+          current.clientBindingDigest === facts.clientBindingDigest &&
+          current.hostSessionDigest === facts.hostSessionDigest
+          ? "current"
+          : "revoked";
+      },
+    },
+  });
+  const blobs = new MemoryBlobStore();
+  const loader = workflowLoader({
+    trace,
+    active: () => loaderState.active,
+    terminal: () => loaderState.terminal,
+  });
+  const service = new GovernedClientAgentWorkflowArtifactService(
+    repository,
+    loader,
+    sessions.service,
+    sessions.repository,
+    blobs,
+    new ClientAgentWorkflowTaskAuthority(),
+    () => sessions.clock.value,
+  );
+  return { service, repository, sessions, blobs, trace, loader, loaderState };
+}
+
+function claimInput() {
+  return {
+    workflowRunId: "run-1",
+    clientBindingDigest,
+    principal,
+    guardContext,
+    signal: workflowSignal,
+  };
+}
+
+function begin(service: GovernedClientAgentWorkflowArtifactService) {
+  return service.begin({
+    jobId: "job-1",
+    payload: {
+      commandId: "command-1",
+      runId: "run-1",
+      nodeRunId: "node-run-1",
+      effectGeneration: 1,
+      requestDigest: workflowRecord().requestDigest,
+    },
+    signal: workflowSignal,
+  });
+}

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

@@ -0,0 +1,350 @@
+import { randomBytes } from "node:crypto";
+import type {
+  ModuleAiJsonValue,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+import type { BlobStore } from "@southwind-ai/storage";
+import type { RequestGuardContext } from "../../guards.js";
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import { digestText, validDigest } from "../client-session/digest.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import type * as WorkflowLoader from "./workflow-loader.js";
+import {
+  clientWorkflowPayloadOf,
+  clientWorkflowPublicView,
+} from "./presentation.js";
+import {
+  requiredWorkflowArtifactText as required,
+  workflowArtifactActor as actor,
+  workflowArtifactConflict as conflict,
+  workflowArtifactHidden as hidden,
+  workflowArtifactInvalid as invalid,
+} from "./service-support.js";
+import {
+  fenceResumableClientWorkflowClaim,
+  reconcileClientWorkflowTakeover,
+} from "./takeover.js";
+import { clientWorkflowSessionCall } from "./session-boundary.js";
+import {
+  cancelClientWorkflowArtifact,
+  recoverClientWorkflowCancellations,
+} from "./cancellation.js";
+import { sealClientWorkflowArtifact } from "./terminal-seal.js";
+import { recoverCompletedClientWorkflowArtifact } from "./completed-recovery.js";
+import { revokeClientWorkflowArtifactHost } from "./host-revocation.js";
+import { replayCompletedClientWorkflowArtifact } from "./terminal-replay.js";
+import {
+  requireClientWorkflowClaim,
+  requireCurrentClientWorkflowArtifact,
+} from "./service-authorization.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+
+export class GovernedClientAgentWorkflowArtifactService {
+  readonly #recovery: Promise<number>;
+
+  constructor(
+    private readonly repository: ClientAgentWorkflowArtifactRepository,
+    private readonly loader: WorkflowLoader.ClientAgentWorkflowFactsLoader,
+    private readonly sessions: GovernedClientAgentSessionService,
+    private readonly sessionRepository: ClientSessionRepository,
+    private readonly blobs: BlobStore,
+    private readonly tasks: ClientAgentWorkflowTaskAuthority = new ClientAgentWorkflowTaskAuthority(),
+    private readonly now: () => number = Date.now,
+  ) {
+    this.#recovery = recoverClientWorkflowCancellations({
+      repository: this.repository,
+      sessions: this.sessions,
+      now: this.now,
+    });
+  }
+
+  async begin(input: {
+    jobId: string;
+    payload: WorkflowLoader.ClientAgentWorkflowJobPayload;
+    signal: AbortSignal;
+  }) {
+    await this.#recovery;
+    const facts = await this.loader.load(input);
+    const begun = await this.repository.begin(facts.record);
+    return {
+      record: await this.recoverCompleted(begun, input.signal),
+      input: facts.input,
+      binding: facts.binding,
+    };
+  }
+
+  async claim(input: {
+    workflowRunId: string;
+    clientBindingDigest: string;
+    principal: ModuleClientAgentHostPrincipal;
+    guardContext: RequestGuardContext;
+    signal: AbortSignal;
+  }) {
+    await this.#recovery;
+    if (!validDigest(input.clientBindingDigest)) throw invalid("绑定摘要无效");
+    const actorId = actor(input.guardContext);
+    if (input.principal.actorId !== actorId) throw hidden();
+    const current = await this.repository.findForActorRun({
+      actorId,
+      runId: required(input.workflowRunId),
+    });
+    if (!current) throw hidden();
+    const initialFacts = await this.requireCurrent(
+      current,
+      input.guardContext,
+      input.signal,
+    );
+    if (current.status === "completed" || current.status === "cancelled") {
+      return clientWorkflowPublicView(
+        current,
+        initialFacts.binding.artifact.kind,
+      );
+    }
+    const claimToken = `cawc_${randomBytes(32).toString("base64url")}`;
+    const hostDigest = hostSessionDigest(input.principal);
+    const allowActiveTakeover = await fenceResumableClientWorkflowClaim({
+      record: current,
+      binding: {
+        clientBindingDigest: input.clientBindingDigest,
+        installationId: input.principal.installationId,
+        hostSessionDigest: hostDigest,
+      },
+      sessionRepository: this.sessionRepository,
+      sessions: this.sessions,
+      repository: this.repository,
+      now: this.now(),
+    });
+    const claimed = await this.repository.claim({
+      workId: current.workId,
+      expectedVersion: current.version,
+      allowActiveTakeover,
+      binding: {
+        clientBindingDigest: input.clientBindingDigest as `sha256:${string}`,
+        installationId: required(input.principal.installationId),
+        hostSessionDigest: hostDigest,
+        claimTokenHash: digestText(claimToken),
+        claimExpiresAt: this.now() + 5 * 60_000,
+        now: this.now(),
+      },
+    });
+    if (claimed.outcome !== "claimed") {
+      if (
+        claimed.record &&
+        ["completed", "cancelled"].includes(claimed.record.status)
+      ) {
+        return clientWorkflowPublicView(
+          claimed.record,
+          initialFacts.binding.artifact.kind,
+        );
+      }
+      throw conflict("领取状态已变化，请重试");
+    }
+    await reconcileClientWorkflowTakeover({
+      previousClientSessionId: claimed.previousClientSessionId,
+      workId: current.workId,
+      sessions: this.sessions,
+      sessionRepository: this.sessionRepository,
+      repository: this.repository,
+      now: this.now(),
+    });
+    const facts = await this.loader.load({
+      jobId: current.durableJobId,
+      payload: clientWorkflowPayloadOf(current),
+      signal: input.signal,
+    });
+    const task = await this.tasks.build({
+      facts,
+      actorId,
+      scopeDigest: claimed.record.scopeDigest,
+      signal: input.signal,
+    });
+    const grant = await clientWorkflowSessionCall(
+      this.sessions.createWorkflow({
+        operationKey: claimed.record.operationKey,
+        input: facts.input,
+        clientBindingDigest: input.clientBindingDigest,
+        hostSessionDigest: claimed.record.hostSessionDigest!,
+        actorId,
+      }),
+      "create",
+    );
+    const bound = await this.repository.bindClientSession({
+      workId: current.workId,
+      claimGeneration: claimed.record.claimGeneration,
+      clientSessionId: grant.sessionId,
+      now: this.now(),
+    });
+    if (!bound) {
+      await this.sessions.revokeSession(grant.sessionId, "workflow-claim-race");
+      throw conflict("领取状态已失效");
+    }
+    return {
+      ...clientWorkflowPublicView(bound, facts.binding.artifact.kind),
+      claimToken,
+      sessionGrant: grant,
+      task,
+    };
+  }
+
+  async advance(input: {
+    workId: string;
+    claimVersion: number;
+    claimToken: string;
+    receiptIds: readonly string[];
+    result?: ModuleAiJsonValue;
+    principal: ModuleClientAgentHostPrincipal;
+    guardContext: RequestGuardContext;
+    signal: AbortSignal;
+  }) {
+    await this.#recovery;
+    const current = await this.requireClaim(input);
+    if (current.status === "completed") {
+      return replayCompletedClientWorkflowArtifact({
+        record: current,
+        receiptIds: input.receiptIds,
+        ...(input.result === undefined ? {} : { result: input.result }),
+        context: input.guardContext,
+        signal: input.signal,
+        loader: this.loader,
+      });
+    }
+    if (current.status === "cancelled") throw hidden();
+    const facts = await this.requireCurrent(
+      current,
+      input.guardContext,
+      input.signal,
+    );
+    return clientWorkflowPublicView(
+      await sealClientWorkflowArtifact({
+        current,
+        claimToken: input.claimToken,
+        receiptIds: input.receiptIds,
+        ...(input.result === undefined ? {} : { result: input.result }),
+        signal: input.signal,
+        sessions: this.sessions,
+        sessionRepository: this.sessionRepository,
+        repository: this.repository,
+        loader: this.loader,
+        blobs: this.blobs,
+        tasks: this.tasks,
+        now: this.now,
+      }),
+      facts.binding.artifact.kind,
+    );
+  }
+
+  async cancelClaim(input: {
+    workId: string;
+    claimVersion: number;
+    claimToken: string;
+    principal: ModuleClientAgentHostPrincipal;
+    guardContext: RequestGuardContext;
+    signal: AbortSignal;
+  }) {
+    await this.#recovery;
+    const current = await this.requireClaim(input);
+    const facts = await this.requireCurrent(
+      current,
+      input.guardContext,
+      input.signal,
+    );
+    if (current.status === "completed" || current.status === "cancelled") {
+      return clientWorkflowPublicView(current, facts.binding.artifact.kind);
+    }
+    const cancelled = await cancelClientWorkflowArtifact({
+      record: current,
+      repository: this.repository,
+      sessions: this.sessions,
+      cause: "workflow-client-cancel",
+      now: this.now(),
+    });
+    if (!cancelled) throw conflict("已完成产物不可取消");
+    return clientWorkflowPublicView(cancelled, facts.binding.artifact.kind);
+  }
+
+  async reconcileOrCancel(input: {
+    jobId: string;
+    cancel: boolean;
+    signal: AbortSignal;
+  }) {
+    await this.#recovery;
+    const current = await this.repository.findByJob(input.jobId);
+    if (!current) return undefined;
+    if (
+      (!input.cancel && current.status !== "cancellation-requested") ||
+      current.status === "completed"
+    ) {
+      return input.cancel
+        ? current
+        : this.recoverCompleted(current, input.signal);
+    }
+    return cancelClientWorkflowArtifact({
+      record: current,
+      repository: this.repository,
+      sessions: this.sessions,
+      cause: "workflow-effect-cancelled",
+      now: this.now(),
+    });
+  }
+
+  async revokeHost(principal: ModuleClientAgentHostPrincipal) {
+    await this.#recovery;
+    const digest = hostSessionDigest(principal);
+    const records = await this.repository.listClaimedByHost({
+      actorId: principal.actorId,
+      hostSessionDigest: digest,
+    });
+    return revokeClientWorkflowArtifactHost({
+      records,
+      repository: this.repository,
+      sessions: this.sessions,
+      now: this.now,
+    });
+  }
+
+  private async requireClaim(input: {
+    workId: string;
+    claimVersion: number;
+    claimToken: string;
+    principal: ModuleClientAgentHostPrincipal;
+    guardContext: RequestGuardContext;
+  }) {
+    return requireClientWorkflowClaim({
+      ...input,
+      repository: this.repository,
+      sessionRepository: this.sessionRepository,
+      now: this.now(),
+    });
+  }
+
+  private async requireCurrent(
+    record: ClientAgentWorkflowArtifactRecord,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return requireCurrentClientWorkflowArtifact({
+      record,
+      context,
+      signal,
+      loader: this.loader,
+    });
+  }
+
+  private recoverCompleted(
+    current: ClientAgentWorkflowArtifactRecord,
+    signal: AbortSignal,
+  ) {
+    return recoverCompletedClientWorkflowArtifact({
+      current,
+      signal,
+      sessionRepository: this.sessionRepository,
+      repository: this.repository,
+      loader: this.loader,
+      blobs: this.blobs,
+      now: this.now,
+    });
+  }
+}