create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,31 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../../guards.js";
+import { clientSessionTerminalDigest } from "../client-session/digest.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import { clientWorkflowPublicView } from "./presentation.js";
+import { requireTerminalClientWorkflowArtifact } from "./service-authorization.js";
+import { workflowArtifactConflict } from "./service-support.js";
+import type { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+
+export async function replayCompletedClientWorkflowArtifact(input: {
+  record: ClientAgentWorkflowArtifactRecord;
+  receiptIds: readonly string[];
+  result?: ModuleAiJsonValue;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  loader: ClientAgentWorkflowFactsLoader;
+}) {
+  const facts = await requireTerminalClientWorkflowArtifact({
+    record: input.record,
+    context: input.context,
+    signal: input.signal,
+    loader: input.loader,
+  });
+  if (
+    input.record.terminalRequestDigest !==
+    clientSessionTerminalDigest(input.receiptIds, input.result)
+  ) {
+    throw workflowArtifactConflict("终态请求摘要与首次完成不一致");
+  }
+  return clientWorkflowPublicView(input.record, facts.binding.artifact.kind);
+}

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

@@ -0,0 +1,211 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { BlobStore } from "@southwind-ai/storage";
+import type { ClientSessionRecord } from "../client-session/contracts.js";
+import {
+  clientSessionTerminalDigest,
+  digestJson,
+  digestText,
+} from "../client-session/digest.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import { ClientAgentSessionError } from "../client-session/errors.js";
+import {
+  clientWorkflowTerminalReceipt,
+  storeClientWorkflowArtifact,
+} from "./artifact-builder.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import { clientWorkflowPayloadOf } from "./presentation.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import {
+  workflowArtifactConflict as conflict,
+  workflowArtifactHidden as hidden,
+} from "./service-support.js";
+import { clientWorkflowSessionCall } from "./session-boundary.js";
+import type { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+import type { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+
+interface TerminalProjectionPorts {
+  signal: AbortSignal;
+  sessionRepository: ClientSessionRepository;
+  repository: ClientAgentWorkflowArtifactRepository;
+  loader: ClientAgentWorkflowFactsLoader;
+  blobs: BlobStore;
+  now: () => number;
+}
+
+export async function sealClientWorkflowArtifact(
+  input: TerminalProjectionPorts & {
+    current: ClientAgentWorkflowArtifactRecord;
+    claimToken: string;
+    receiptIds: readonly string[];
+    result?: ModuleAiJsonValue;
+    sessions: GovernedClientAgentSessionService;
+    tasks: ClientAgentWorkflowTaskAuthority;
+  },
+) {
+  const requestDigest = clientSessionTerminalDigest(
+    input.receiptIds,
+    input.result,
+  );
+  const currentFacts = await input.loader.loadTerminal({
+    record: input.current,
+    signal: input.signal,
+  });
+  const openedInputArtifacts = await input.tasks.openInputArtifacts({
+    artifacts: currentFacts.inputArtifacts,
+    actorId: input.current.actorId,
+    scopeDigest: input.current.scopeDigest,
+    signal: input.signal,
+  });
+  const completed = await clientWorkflowSessionCall(
+    input.sessions.finalizeWorkflow(
+      input.current.clientSessionId!,
+      {
+        actorId: input.current.actorId,
+        clientBindingDigest: input.current.clientBindingDigest!,
+        hostSessionDigest: input.current.hostSessionDigest!,
+      },
+      input.receiptIds,
+      input.result,
+      async (proposedResult) => {
+        try {
+          return await currentFacts.binding.terminalResultAuthority.canonicalize(
+            {
+              workflowInput: currentFacts.input,
+              inputArtifacts: openedInputArtifacts,
+              proposedResult,
+              actorId: input.current.actorId,
+              scopeDigest: input.current.scopeDigest,
+              signal: input.signal,
+            },
+          );
+        } catch {
+          throw new ClientAgentSessionError(
+            "INVALID_INPUT",
+            "Project terminal result authority 拒绝结果",
+            400,
+          );
+        }
+      },
+    ),
+    "finalize",
+  );
+  if (completed.status !== "completed" || completed.result === undefined) {
+    throw conflict("Client Agent Session 尚未完成");
+  }
+  const session = await input.sessionRepository.find(
+    input.current.clientSessionId!,
+  );
+  if (!session || session.terminalDigest !== requestDigest) {
+    throw conflict("Client Agent Session 终态请求摘要冲突");
+  }
+  return sealCompletedClientWorkflowSession({
+    ...input,
+    session,
+    terminalRequestDigest: requestDigest,
+    claimTokenHash: digestText(input.claimToken),
+  });
+}
+
+export async function sealCompletedClientWorkflowSession(
+  input: TerminalProjectionPorts & {
+    current: ClientAgentWorkflowArtifactRecord;
+    session: ClientSessionRecord;
+    terminalRequestDigest: `sha256:${string}`;
+    claimTokenHash: `sha256:${string}`;
+  },
+) {
+  const { current, session } = input;
+  if (
+    session.status !== "completed" ||
+    !session.finalResult ||
+    session.terminalDigest !== input.terminalRequestDigest ||
+    session.sessionId !== current.clientSessionId ||
+    session.actorId !== current.actorId ||
+    session.operationKey !== current.operationKey ||
+    session.clientBindingDigest !== current.clientBindingDigest ||
+    session.hostSessionDigest !== current.hostSessionDigest ||
+    input.claimTokenHash !== current.claimTokenHash
+  ) {
+    throw hidden();
+  }
+  const history = [...session.receipts]
+    .sort((left, right) => left.attempt - right.attempt)
+    .map((receipt) => ({
+      receiptId: receipt.receiptId,
+      attempt: receipt.attempt,
+      requestDigest: receipt.requestDigest,
+      responseDigest: receipt.responseDigest,
+      deploymentDigest: receipt.deploymentDigest,
+      issuedAt: new Date(receipt.issuedAt).toISOString(),
+    }));
+  if (!history.length) throw hidden();
+  const historyHeadDigest = digestJson(history);
+  const terminalReceiptId = clientWorkflowTerminalReceipt(
+    current,
+    historyHeadDigest,
+  );
+  const terminalReceiptDigest = digestJson({
+    terminalReceiptId,
+    terminalRequestDigest: input.terminalRequestDigest,
+    workId: current.workId,
+    claimGeneration: current.claimGeneration,
+    clientRunId: session.clientRunId,
+    historyHeadDigest,
+    result: session.finalResult.result,
+  });
+  const terminalResult = {
+    schemaVersion: 1,
+    result: session.finalResult.result,
+    attestation: {
+      clientRunId: session.clientRunId,
+      terminalReceiptId,
+      terminalReceiptDigest,
+      historyLength: history.length,
+      historyHeadDigest,
+      providerAttested: session.finalResult.attestation.providerAttested,
+    },
+    provenance: {
+      workId: current.workId,
+      workflowRunId: current.runId,
+      claimGeneration: current.claimGeneration,
+    },
+  } as const satisfies ModuleAiJsonValue;
+  const facts = await input.loader.load({
+    jobId: current.durableJobId,
+    payload: clientWorkflowPayloadOf(current),
+    signal: input.signal,
+  });
+  const artifact = await storeClientWorkflowArtifact({
+    blobs: input.blobs,
+    result: terminalResult,
+    binding: facts.binding,
+    terminalReceiptDigest,
+  });
+  const terminal = await input.repository.complete({
+    workId: current.workId,
+    claimTokenHash: input.claimTokenHash,
+    terminal: {
+      claimGeneration: current.claimGeneration,
+      clientSessionId: current.clientSessionId!,
+      historySequence: history.length,
+      historyHeadDigest,
+      terminalReceiptId,
+      terminalReceiptDigest,
+      terminalRequestDigest: input.terminalRequestDigest,
+      terminalResult,
+      artifact,
+      now: input.now(),
+    },
+  });
+  if (terminal) return terminal;
+  const converged = await input.repository.find(current.workId);
+  if (
+    converged?.status === "completed" &&
+    converged.terminalReceiptDigest === terminalReceiptDigest &&
+    converged.terminalRequestDigest === input.terminalRequestDigest
+  ) {
+    return converged;
+  }
+  throw conflict("终态回执与当前领取代次冲突");
+}

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

@@ -0,0 +1,173 @@
+import type { ModuleClientAgentHostPrincipal } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../../guards.js";
+import { buildScopeContext } from "../../data-access/context.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import { digestJson } from "../client-session/digest.js";
+import type {
+  ClientAgentWorkflowArtifactBinding,
+  ClientAgentWorkflowArtifactRecord,
+} from "./contracts.js";
+import { clientWorkflowBindingCommitment } from "./binding-registry.js";
+import type { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+
+export const clientBindingDigest = `sha256:${"b".repeat(64)}` as const;
+export const workflowInput = { question: "研判当前页面线索" } as const;
+
+export const workflowBinding: ClientAgentWorkflowArtifactBinding = {
+  workflowKey: "case.full-analysis",
+  nodeId: "page-agent-artifact",
+  operationKey: "analysis.page-agent",
+  releaseDigest: `sha256:${"d".repeat(64)}`,
+  scopeContainmentContractVersion: 1,
+  terminalResultAuthority: {
+    version: "sharp.page-agent-result.v1",
+    digest: `sha256:${"e".repeat(64)}`,
+    async canonicalize({ proposedResult, inputArtifacts }) {
+      if (!Array.isArray(inputArtifacts)) {
+        throw new Error("terminal input artifacts missing");
+      }
+      return proposedResult;
+    },
+  },
+  clientTaskAuthority: {
+    version: "sharp.page-agent-task.v1",
+    digest: `sha256:${"f".repeat(64)}`,
+    async build({ workflowInput }) {
+      return { taskKey: "sharp.page-agent", input: workflowInput };
+    },
+  },
+  launchAuthority: {
+    version: "sharp.workflow-launch.v1",
+    digest: `sha256:${"a".repeat(64)}`,
+    async authorizeRelease() {},
+    async authorizeRun({ currentAuthorizationScope }) {
+      return {
+        authorizationScope: currentAuthorizationScope,
+      };
+    },
+  },
+  artifact: {
+    kind: "structured-data",
+    contentType: "application/json",
+    filename: "page-agent-result.json",
+    retentionPolicyKey: "case-analysis",
+    maxByteSize: 64 * 1024,
+  },
+};
+
+export const principal: ModuleClientAgentHostPrincipal = {
+  actorId: "actor-1",
+  installationId: "installation-1",
+  sessionId: "host-session-1",
+};
+
+const scopeContext = buildScopeContext(principal.actorId, undefined, [
+  {
+    id: "role-analyst",
+    code: "analyst",
+    dataScope: "self",
+    departmentIds: [],
+  },
+]);
+
+export const guardContext: RequestGuardContext = {
+  requestId: "request-1",
+  actor: {
+    id: principal.actorId,
+    type: "user",
+    name: "研判员",
+    roleCodes: ["analyst"],
+    permissionKeys: ["system.agent-workflow.manage"],
+    dataAccess: scopeContext,
+    scopeContext,
+  },
+  startedAt: "2026-08-28T00:00:00.000Z",
+};
+
+export function workflowRecord(
+  patch: Partial<ClientAgentWorkflowArtifactRecord> = {},
+): ClientAgentWorkflowArtifactRecord {
+  const scope = captureAuthorizationScope(guardContext.actor.scopeContext);
+  return {
+    workId: "cawa_work-1",
+    commandId: "command-1",
+    durableJobId: "job-1",
+    runId: "run-1",
+    nodeRunId: "node-run-1",
+    effectKind: "job",
+    taskKey: "system.agent-workflow.client-agent-artifact",
+    operationKey: workflowBinding.operationKey,
+    bindingDigest: digestJson(clientWorkflowBindingCommitment(workflowBinding)),
+    actorId: principal.actorId,
+    scopeDigest: `sha256:${scope.hash}`,
+    authorizationSnapshotDigest: digestJson({ actorId: principal.actorId }),
+    runPolicyDigest: digestJson({ mode: "governed" }),
+    requestDigest: digestJson({ commandId: "command-1" }),
+    inputDigest: digestJson(workflowInput),
+    effectGeneration: 1,
+    effectFenceTokenDigest: digestJson({ fence: "fence-1" }),
+    status: "pending",
+    claimGeneration: 0,
+    historySequence: 0,
+    version: 1,
+    createdAt: 1_000,
+    updatedAt: 1_000,
+    ...patch,
+  };
+}
+
+export function workflowLoader(
+  input: {
+    record?: () => ClientAgentWorkflowArtifactRecord;
+    trace?: string[];
+    active?: () => boolean;
+    terminal?: () => boolean;
+    canonicalize?: typeof workflowBinding.terminalResultAuthority.canonicalize;
+  } = {},
+): ClientAgentWorkflowFactsLoader {
+  return {
+    load: async () => {
+      if (input.active?.() === false) throw new Error("ACTIVE_EFFECT_CLOSED");
+      input.trace?.push("authority-fence-current");
+      return {
+        record: structuredClone(input.record?.() ?? workflowRecord()),
+        input: structuredClone(workflowInput),
+        inputArtifacts: [],
+        frozenScope: captureAuthorizationScope(guardContext.actor.scopeContext)
+          .snapshot,
+        binding: cloneWorkflowBinding(input.canonicalize),
+      };
+    },
+    loadTerminal: async () => {
+      if (input.terminal?.() === false)
+        throw new Error("TERMINAL_AUTHORIZATION_STALE");
+      input.trace?.push("terminal-authority-current");
+      return {
+        binding: cloneWorkflowBinding(input.canonicalize),
+        input: structuredClone(workflowInput),
+        inputArtifacts: [],
+        frozenScope: captureAuthorizationScope(guardContext.actor.scopeContext)
+          .snapshot,
+      };
+    },
+  } as unknown as ClientAgentWorkflowFactsLoader;
+}
+
+function cloneWorkflowBinding(
+  canonicalize = workflowBinding.terminalResultAuthority.canonicalize,
+): ClientAgentWorkflowArtifactBinding {
+  return {
+    ...structuredClone(clientWorkflowBindingCommitment(workflowBinding)),
+    terminalResultAuthority: {
+      ...structuredClone(
+        clientWorkflowBindingCommitment(workflowBinding)
+          .terminalResultAuthority,
+      ),
+      canonicalize,
+    },
+    clientTaskAuthority: workflowBinding.clientTaskAuthority,
+    launchAuthority: workflowBinding.launchAuthority,
+  };
+}
+
+export const workflowSignal = new AbortController().signal;

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

@@ -0,0 +1,254 @@
+import { expect, test } from "bun:test";
+import type { DurableJobService } from "../../jobs/service.js";
+import { buildScopeContext } from "../../data-access/context.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import type { DrizzleAgentWorkflowRepository } from "../../agent-workflow/drizzle-repository.js";
+import { ClientAgentWorkflowArtifactBindingRegistry } from "./binding-registry.js";
+import { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+import {
+  workflowBinding,
+  workflowInput,
+  workflowSignal,
+} from "./workflow-artifact.test-support.js";
+
+test("loader pin Immutable Release 与唯一 job-artifact-final 拓扑", async () => {
+  const fixture = loaderFixture();
+  const facts = await fixture.loader.load({
+    jobId: "job-1",
+    payload: {
+      commandId: "command-1",
+      runId: "run-1",
+      nodeRunId: "node-run-1",
+      effectGeneration: 1,
+      requestDigest: fixture.command.requestDigest,
+    },
+    signal: workflowSignal,
+  });
+  expect(facts.binding.releaseDigest).toBe(workflowBinding.releaseDigest);
+
+  fixture.release.releaseDigest = `sha256:${"e".repeat(64)}`;
+  await expect(
+    fixture.loader.load({
+      jobId: "job-1",
+      payload: {
+        commandId: "command-1",
+        runId: "run-1",
+        nodeRunId: "node-run-1",
+      },
+      signal: workflowSignal,
+    }),
+  ).rejects.toThrow("CLIENT_AGENT_WORKFLOW_RELEASE_BINDING_INVALID");
+
+  fixture.release.releaseDigest = workflowBinding.releaseDigest;
+  fixture.release.definition.edges.push({
+    from: workflowBinding.nodeId,
+    to: "final",
+  });
+  await expect(
+    fixture.loader.load({
+      jobId: "job-1",
+      payload: {
+        commandId: "command-1",
+        runId: "run-1",
+        nodeRunId: "node-run-1",
+      },
+      signal: workflowSignal,
+    }),
+  ).rejects.toThrow("CLIENT_AGENT_WORKFLOW_RELEASE_BINDING_INVALID");
+
+  fixture.release.definition.edges.pop();
+  const fallbackPolicy = {
+    mode: "fallback",
+    nodeId: "final",
+  };
+  fixture.release.definition.nodes[0]!.failurePolicy = fallbackPolicy;
+  await expect(
+    fixture.loader.load({
+      jobId: "job-1",
+      payload: {
+        commandId: "command-1",
+        runId: "run-1",
+        nodeRunId: "node-run-1",
+      },
+      signal: workflowSignal,
+    }),
+  ).rejects.toThrow("CLIENT_AGENT_WORKFLOW_RELEASE_BINDING_INVALID");
+});
+
+test("terminal loader 接受 committed/completed immutable facts 并拒绝摘要漂移", async () => {
+  const fixture = loaderFixture();
+  const begun = await fixture.loader.load({
+    jobId: "job-1",
+    payload: {
+      commandId: "command-1",
+      runId: "run-1",
+      nodeRunId: "node-run-1",
+    },
+    signal: workflowSignal,
+  });
+  fixture.snapshot.run.status = "completed";
+  fixture.snapshot.nodeRuns[0]!.status = "completed";
+  fixture.command.status = "committed";
+  await expect(
+    fixture.loader.loadTerminal({
+      record: begun.record,
+      signal: workflowSignal,
+    }),
+  ).resolves.toMatchObject({ binding: workflowBinding });
+
+  fixture.command.requestDigest = `sha256:${"9".repeat(64)}`;
+  await expect(
+    fixture.loader.loadTerminal({
+      record: begun.record,
+      signal: workflowSignal,
+    }),
+  ).rejects.toThrow("WORKFLOW_TERMINAL_IDENTITY_INVALID");
+});
+
+function loaderFixture() {
+  const scope = captureAuthorizationScope(
+    buildScopeContext("actor-1", undefined, [
+      {
+        id: "role-analyst",
+        code: "analyst",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  );
+  const release = {
+    releaseId: "workflow-release-1",
+    releaseDigest: workflowBinding.releaseDigest,
+    definitionId: "workflow-definition-1",
+    definitionDigest: `sha256:${"f".repeat(64)}`,
+    definition: {
+      schemaVersion: 1,
+      workflowKey: workflowBinding.workflowKey,
+      version: "1.0.0",
+      label: "全案线索研判",
+      entryNodeId: workflowBinding.nodeId,
+      nodes: [
+        {
+          id: workflowBinding.nodeId,
+          type: "job",
+          label: "PageAgent",
+          taskKey: "system.agent-workflow.client-agent-artifact",
+          failurePolicy: { mode: "fail-run" },
+        },
+        {
+          id: "page-agent-output",
+          type: "artifact",
+          label: "受治理产物",
+          policyKey: workflowBinding.artifact.retentionPolicyKey,
+          artifactKind: workflowBinding.artifact.kind,
+          failurePolicy: { mode: "fail-run" },
+        },
+        {
+          id: "final",
+          type: "final",
+          label: "完成",
+          outputSchemaKey: "analysis.result.v1",
+          failurePolicy: { mode: "fail-run" },
+        },
+      ],
+      edges: [
+        { from: workflowBinding.nodeId, to: "page-agent-output" },
+        { from: "page-agent-output", to: "final" },
+      ],
+      budget: budget(),
+    },
+    coordinates: {
+      runtimeVersion: "runtime-1",
+      routeVersion: "route-1",
+      promptVersion: "prompt-1",
+      toolSchemaVersion: "tool-schema-1",
+      manifestDigest: `sha256:${"a".repeat(64)}`,
+    },
+    publishedBy: "actor-1",
+    publishedAt: "2026-08-28T00:00:00.000Z",
+  };
+  const command = {
+    commandId: "command-1",
+    runId: "run-1",
+    nodeRunId: "node-run-1",
+    effectKind: "job",
+    effectKey: workflowBinding.nodeId,
+    adapter: { kind: "durable-job", coordinate: "job-idempotency:node-1" },
+    idempotencyKey: "job-command-1",
+    requestDigest: `sha256:${"1".repeat(64)}`,
+    generation: 1,
+    fenceTokenDigest: `sha256:${"2".repeat(64)}`,
+    authorizationSnapshotDigest: `sha256:${"3".repeat(64)}`,
+    runPolicyDigest: `sha256:${"4".repeat(64)}`,
+    status: "dispatched",
+    version: 2,
+    createdAt: "2026-08-28T00:00:00.000Z",
+    updatedAt: "2026-08-28T00:00:01.000Z",
+  };
+  const snapshot = {
+    run: {
+      runId: "run-1",
+      releaseId: release.releaseId,
+      actorId: "actor-1",
+      scopeDigest: `sha256:${scope.hash}`,
+      authorizationSnapshotDigest: command.authorizationSnapshotDigest,
+      executionPolicyDigest: command.runPolicyDigest,
+      status: "running",
+      inputReceipt: {
+        schemaKey: "analysis.input.v1",
+        value: workflowInput,
+        valueDigest: `sha256:${"5".repeat(64)}`,
+        recordedAt: "2026-08-28T00:00:00.000Z",
+      },
+    },
+    nodeRuns: [
+      {
+        nodeRunId: "node-run-1",
+        runId: "run-1",
+        nodeId: workflowBinding.nodeId,
+        nodeType: "job",
+        status: "running",
+        inputArtifacts: [],
+        outputArtifacts: [],
+      },
+    ],
+    sideEffects: [command],
+  };
+  const workflows = {
+    getSnapshot: async () => snapshot,
+    getRelease: async () => release,
+  } as unknown as DrizzleAgentWorkflowRepository;
+  const jobs = {
+    get: async () => ({
+      job: {
+        id: "job-1",
+        handlerKey: "system.agent-workflow.client-agent-artifact",
+        requestedBy: "actor-1",
+        authorizationScope: scope.snapshot,
+      },
+    }),
+  } as unknown as DurableJobService;
+  return {
+    loader: new ClientAgentWorkflowFactsLoader(
+      workflows,
+      jobs,
+      new ClientAgentWorkflowArtifactBindingRegistry([workflowBinding]),
+    ),
+    release,
+    command,
+    snapshot,
+  };
+}
+
+function budget() {
+  return {
+    maxDurationSeconds: 600,
+    maxModelAttempts: 1,
+    maxToolCalls: 0,
+    maxSubagents: 0,
+    maxParallelism: 1,
+    maxInputTokens: 1,
+    maxOutputTokens: 1,
+    maxCostMicros: 1,
+  };
+}