create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent-workflow/service-run-command.ts

@@ -0,0 +1,131 @@
+import { isAgentWorkflowNodeTerminal } from "@southwind-ai/shared";
+import type { WorkflowBudgetLedgerPort } from "./budget-ledger.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+import {
+  transitionAgentWorkflowNodeRun,
+  transitionAgentWorkflowRun,
+  type AgentWorkflowRunCommand,
+} from "./state-machine.js";
+import {
+  nodeEventData,
+  runEventData,
+  workflowEvent,
+} from "./service-support.js";
+
+export interface TransitionAgentWorkflowRunInput {
+  readonly runId: string;
+  readonly expectedVersion: number;
+  readonly expectedSequence: number;
+  readonly command: Exclude<
+    AgentWorkflowRunCommand,
+    { type: "wait" | "resume" }
+  >;
+  readonly idempotencyKey: string;
+  readonly at: string;
+}
+
+export async function executeAgentWorkflowRunCommand(input: {
+  readonly repository: AgentWorkflowRepository;
+  readonly budgetLedger: WorkflowBudgetLedgerPort;
+  readonly request: TransitionAgentWorkflowRunInput;
+}) {
+  const request = input.request;
+  const snapshot = await input.repository.getSnapshot(request.runId);
+  if (!snapshot) throw new Error("Workflow Run 不存在");
+  const release = await input.repository.getRelease(snapshot.run.releaseId);
+  if (!release) throw new Error("Workflow Release 不存在");
+  if (request.command.type === "complete") {
+    const finalNode = release.definition.nodes.find(
+      ({ type }) => type === "final",
+    )!;
+    const finalRun = snapshot.nodeRuns.find(
+      ({ nodeId, status, resultReceipt }) =>
+        nodeId === finalNode.id && status === "completed" && resultReceipt,
+    );
+    const ledger = await input.budgetLedger.read(request.runId);
+    const activeEffect = snapshot.sideEffects.some(({ status }) =>
+      ["prepared", "dispatched", "cancellation-requested"].includes(status),
+    );
+    if (
+      !finalRun ||
+      !ledger ||
+      ledger.activeReservations.length > 0 ||
+      activeEffect ||
+      snapshot.nodeRuns.some(
+        ({ status }) => !isAgentWorkflowNodeTerminal(status),
+      )
+    ) {
+      throw new Error("Workflow Run 尚未由 final/Effect/Budget 收敛");
+    }
+  }
+  const next = transitionAgentWorkflowRun({
+    run: snapshot.run,
+    expectedVersion: request.expectedVersion,
+    command: request.command,
+    at: request.at,
+  });
+  const nodeUpdates = [];
+  const events = [];
+  if (request.command.type === "start") {
+    const entry = snapshot.nodeRuns.find(
+      ({ nodeId, status }) =>
+        nodeId === release.definition.entryNodeId && status === "pending",
+    );
+    if (!entry) throw new Error("Workflow entry Node 尚未就绪或已启动");
+    const ready = transitionAgentWorkflowNodeRun({
+      nodeRun: entry,
+      expectedVersion: entry.version,
+      command: { type: "ready" },
+      at: request.at,
+    });
+    nodeUpdates.push({ expectedVersion: entry.version, value: ready });
+    events.push(
+      workflowEvent({
+        runId: request.runId,
+        idempotencyKey: `${request.idempotencyKey}:${entry.nodeRunId}`,
+        at: request.at,
+        data: nodeEventData(entry, { type: "ready" }),
+      }),
+    );
+  }
+  if (["cancel", "timeout", "fail"].includes(request.command.type)) {
+    const nodeCommand =
+      request.command.type === "timeout"
+        ? ({ type: "timeout" } as const)
+        : ({ type: "cancel" } as const);
+    for (const node of snapshot.nodeRuns.filter(
+      ({ status }) => !isAgentWorkflowNodeTerminal(status),
+    )) {
+      const value = transitionAgentWorkflowNodeRun({
+        nodeRun: node,
+        expectedVersion: node.version,
+        command: nodeCommand,
+        at: request.at,
+      });
+      nodeUpdates.push({ expectedVersion: node.version, value });
+      events.push(
+        workflowEvent({
+          runId: request.runId,
+          idempotencyKey: `${request.idempotencyKey}:${node.nodeRunId}`,
+          at: request.at,
+          data: nodeEventData(node, nodeCommand),
+        }),
+      );
+    }
+  }
+  const runEvent = workflowEvent({
+    runId: request.runId,
+    idempotencyKey: request.idempotencyKey,
+    at: request.at,
+    data: runEventData(request.command),
+  });
+  if (request.command.type === "start") events.unshift(runEvent);
+  else events.push(runEvent);
+  return input.repository.commit({
+    runId: request.runId,
+    expectedSequence: request.expectedSequence,
+    runUpdate: { expectedVersion: request.expectedVersion, value: next },
+    nodeUpdates,
+    events,
+  });
+}

package/template/apps/server/src/agent-workflow/service-state-error.ts

@@ -0,0 +1,21 @@
+export type AgentWorkflowStateErrorCode =
+  | "VERSION_CONFLICT"
+  | "INVALID_TRANSITION"
+  | "TERMINAL_RUN"
+  | "TERMINAL_NODE_RUN"
+  | "CANCELLATION_REQUESTED"
+  | "DEADLINE_EXCEEDED"
+  | "BUDGET_EXCEEDED"
+  | "USAGE_UNMEASURED"
+  | "RETRY_EXHAUSTED"
+  | "INVALID_RECEIPT";
+
+export class AgentWorkflowStateError extends Error {
+  constructor(
+    readonly code: AgentWorkflowStateErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AgentWorkflowStateError";
+  }
+}

package/template/apps/server/src/agent-workflow/service-state-invariants.ts

@@ -0,0 +1,44 @@
+import {
+  isAgentWorkflowNodeTerminal,
+  isAgentWorkflowTerminal,
+  type AgentWorkflowNodeRun,
+  type AgentWorkflowRun,
+} from "@southwind-ai/shared";
+import { AgentWorkflowStateError } from "./service-state-error.js";
+
+export function assertRunStateInvariant(run: AgentWorkflowRun) {
+  if (
+    isAgentWorkflowTerminal(run.status) !== Boolean(run.finishedAt) ||
+    Date.parse(run.createdAt) > Date.parse(run.updatedAt) ||
+    (run.finishedAt &&
+      Date.parse(run.finishedAt) < Date.parse(run.updatedAt)) ||
+    Date.parse(run.deadlineAt) <= Date.parse(run.createdAt) ||
+    (run.cancellationRequestedAt &&
+      (Date.parse(run.cancellationRequestedAt) < Date.parse(run.createdAt) ||
+        Date.parse(run.cancellationRequestedAt) > Date.parse(run.updatedAt)))
+  ) {
+    invalid("Workflow Run 状态与终态时间不一致");
+  }
+}
+
+export function assertNodeRunStateInvariant(nodeRun: AgentWorkflowNodeRun) {
+  const finished =
+    isAgentWorkflowNodeTerminal(nodeRun.status) ||
+    nodeRun.status === "retry-scheduled";
+  if (
+    finished !== Boolean(nodeRun.finishedAt) ||
+    Date.parse(nodeRun.createdAt) > Date.parse(nodeRun.updatedAt) ||
+    (nodeRun.startedAt &&
+      Date.parse(nodeRun.startedAt) < Date.parse(nodeRun.createdAt)) ||
+    (nodeRun.finishedAt &&
+      Date.parse(nodeRun.finishedAt) < Date.parse(nodeRun.updatedAt)) ||
+    (nodeRun.status === "completed" && !nodeRun.resultReceipt) ||
+    (nodeRun.status !== "completed" && nodeRun.resultReceipt !== undefined)
+  ) {
+    invalid("Node Run 状态、终态时间或 Receipt 不一致");
+  }
+}
+
+function invalid(message: string): never {
+  throw new AgentWorkflowStateError("INVALID_TRANSITION", message);
+}

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

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import type {
+  AgentWorkflowEventData,
+  AgentWorkflowNode,
+  AgentWorkflowNodeRun,
+  AgentWorkflowRelease,
+  AgentWorkflowRun,
+} from "@southwind-ai/shared";
+import type { PendingAgentWorkflowEvent } from "./repository.js";
+import type {
+  AgentWorkflowNodeRunCommand,
+  AgentWorkflowRunCommand,
+} from "./state-machine.js";
+
+export function workflowId(prefix: string, ...parts: readonly string[]) {
+  const hash = createHash("sha256").update(parts.join("\u0000")).digest("hex");
+  return `${prefix}_${hash.slice(0, 48)}`;
+}
+
+export function workflowEvent(input: {
+  readonly runId: string;
+  readonly idempotencyKey: string;
+  readonly at: string;
+  readonly data: AgentWorkflowEventData;
+  readonly causationEventId?: string;
+  readonly parentEventId?: string;
+}): PendingAgentWorkflowEvent {
+  return {
+    eventId: workflowId("workflow_event", input.runId, input.idempotencyKey),
+    occurredAt: input.at,
+    data: structuredClone(input.data),
+    ...(input.causationEventId
+      ? { causationEventId: input.causationEventId }
+      : {}),
+    ...(input.parentEventId ? { parentEventId: input.parentEventId } : {}),
+  };
+}
+
+export function runEventData(
+  command: AgentWorkflowRunCommand,
+): AgentWorkflowEventData {
+  switch (command.type) {
+    case "start":
+      return { type: "workflow.run-started" };
+    case "request-cancel":
+      return {
+        type: "workflow.cancellation-requested",
+        reasonCode: command.reasonCode,
+      };
+    case "complete":
+      return { type: "workflow.run-completed" };
+    case "fail":
+      return { type: "workflow.run-failed", safeCode: command.safeCode };
+    case "cancel":
+      return { type: "workflow.run-cancelled" };
+    case "timeout":
+      return { type: "workflow.run-timed-out" };
+    default:
+      throw new Error("waiting/resume 不产生 Run canonical Event");
+  }
+}
+
+export function nodeEventData(
+  nodeRun: AgentWorkflowNodeRun,
+  command: AgentWorkflowNodeRunCommand,
+): AgentWorkflowEventData {
+  const base = { nodeRunId: nodeRun.nodeRunId, nodeId: nodeRun.nodeId };
+  switch (command.type) {
+    case "ready":
+      return { type: "workflow.node-ready", ...base };
+    case "start":
+    case "resume":
+      return { type: "workflow.node-started", ...base };
+    case "wait":
+      return { type: "workflow.node-waiting", ...base };
+    case "complete":
+      return {
+        type: "workflow.node-completed",
+        ...base,
+        resultDigest: command.receipt.resultDigest,
+        receiptId: command.receipt.receiptId,
+      };
+    case "schedule-retry":
+      return {
+        type: "workflow.node-retry-scheduled",
+        ...base,
+        safeCode: command.safeCode,
+      };
+    case "fail":
+      return {
+        type: "workflow.node-failed",
+        ...base,
+        safeCode: command.safeCode,
+      };
+    case "cancel":
+      return { type: "workflow.node-cancelled", ...base };
+    case "skip":
+      return { type: "workflow.node-skipped", ...base };
+    case "timeout":
+      return { type: "workflow.node-timed-out", ...base };
+  }
+}
+
+export function findDefinitionNode(
+  release: AgentWorkflowRelease,
+  nodeRun: AgentWorkflowNodeRun,
+): AgentWorkflowNode {
+  const node = release.definition.nodes.find(({ id }) => id === nodeRun.nodeId);
+  if (!node || node.type !== nodeRun.nodeType) {
+    throw new Error("Node Run 未绑定 Release 中的 typed node");
+  }
+  return node;
+}
+
+export function assertDigest(value: string) {
+  if (!/^sha256:[a-f0-9]{64}$/.test(value)) {
+    throw new Error("Workflow policy digest 无效");
+  }
+}
+
+export function assertRunPolicies(run: AgentWorkflowRun) {
+  for (const digest of [
+    run.inputDigest,
+    run.scopeDigest,
+    run.authorizationSnapshotDigest,
+    run.toolPolicyDigest,
+    run.workspacePolicyDigest,
+    run.executionPolicyDigest,
+  ]) {
+    assertDigest(digest);
+  }
+}
+
+export function maxAttempts(node: AgentWorkflowNode) {
+  return node.failurePolicy.mode === "retry"
+    ? node.failurePolicy.maxAttempts
+    : 1;
+}
+
+export function workflowTimestamp(value: string) {
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error("Workflow timestamp 无效");
+  }
+  return value;
+}
+
+export function workflowCoordinate(value: string) {
+  if (value.trim() !== value || !value || value.length > 96) {
+    throw new Error("Workflow coordinate 无效");
+  }
+  return value;
+}

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

@@ -0,0 +1,307 @@
+import {
+  budgetFitsWithin,
+  type AgentWorkflowArtifactRef,
+  type AgentWorkflowBudget,
+  type AgentWorkflowInputReceipt,
+  type AgentWorkflowRun,
+  type AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type { WorkflowEffectCommandFencePort } from "./effect-command-fence.js";
+import type { WorkflowBudgetLedgerPort } from "./budget-ledger.js";
+import {
+  buildAgentWorkflowRelease,
+  type PublishAgentWorkflowReleaseInput,
+} from "./release.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+import {
+  transitionAgentWorkflowNodeRun,
+  type AgentWorkflowNodeRunCommand,
+} from "./state-machine.js";
+import { EMPTY_AGENT_WORKFLOW_USAGE } from "./usage.js";
+import { assertAgentWorkflowInputReceipt } from "./input-receipt.js";
+import {
+  assertRunPolicies,
+  findDefinitionNode,
+  maxAttempts,
+  nodeEventData,
+  workflowCoordinate,
+  workflowEvent,
+  workflowId,
+  workflowTimestamp,
+} from "./service-support.js";
+import {
+  executeAgentWorkflowRunCommand,
+  type TransitionAgentWorkflowRunInput,
+} from "./service-run-command.js";
+import {
+  assertWorkflowNodeCompletion,
+  workflowRunCompletionReadiness,
+} from "./service-completion.js";
+import { buildNodeCommandRunUpdate } from "./service-node-run-update.js";
+import { assertNodeCommandAdmitted } from "./service-node-admission.js";
+import {
+  scheduleAgentWorkflowRetry,
+  type ScheduleAgentWorkflowRetryInput,
+} from "./service-retry.js";
+
+export interface CreateAgentWorkflowRunRequest {
+  readonly releaseId: string;
+  readonly tenantId: string;
+  readonly actorId: string;
+  readonly routeKey: string;
+  readonly inputDigest: string;
+  readonly inputReceipt: AgentWorkflowInputReceipt;
+  readonly scopeDigest: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly toolPolicyDigest: string;
+  readonly workspacePolicyDigest: string;
+  readonly executionPolicyDigest: string;
+  readonly idempotencyKey: string;
+  readonly deadlineAt: string;
+  readonly budget?: AgentWorkflowBudget;
+  readonly sessionId?: string;
+  readonly parentRunId?: string;
+  readonly parentNodeId?: string;
+  readonly parentNodeRunId?: string;
+  readonly parentEventId?: string;
+  readonly delegationId?: string;
+  readonly inputArtifacts?: readonly AgentWorkflowArtifactRef[];
+  readonly at: string;
+}
+
+export class AgentWorkflowService {
+  constructor(
+    private readonly repository: AgentWorkflowRepository,
+    private readonly effectFence: WorkflowEffectCommandFencePort,
+    private readonly budgetLedger: WorkflowBudgetLedgerPort,
+  ) {}
+
+  publish(input: PublishAgentWorkflowReleaseInput) {
+    return this.repository.publishRelease(buildAgentWorkflowRelease(input));
+  }
+
+  async createRun(input: CreateAgentWorkflowRunRequest) {
+    const release = await this.requireRelease(input.releaseId);
+    const budget = input.budget ?? release.definition.budget;
+    if (!budgetFitsWithin(budget, release.definition.budget)) {
+      throw new Error("Workflow Run Budget 超出 immutable Release");
+    }
+    const createdAt = workflowTimestamp(input.at);
+    assertAgentWorkflowInputReceipt(input.inputReceipt, input.inputDigest);
+    const entry = release.definition.nodes.find(
+      ({ id }) => id === release.definition.entryNodeId,
+    )!;
+    if (
+      input.inputReceipt.schemaKey !== entry.inputSchemaKey ||
+      Date.parse(input.inputReceipt.recordedAt) > Date.parse(createdAt)
+    ) {
+      throw new Error("Workflow Input Receipt 不符合 entry Definition");
+    }
+    const parentCoordinates = [
+      input.parentRunId,
+      input.parentNodeId,
+      input.parentNodeRunId,
+      input.parentEventId,
+      input.delegationId,
+    ];
+    if (
+      Date.parse(input.deadlineAt) <= Date.parse(createdAt) ||
+      Date.parse(input.deadlineAt) - Date.parse(createdAt) >
+        budget.maxDurationSeconds * 1_000 ||
+      (!parentCoordinates.every(Boolean) && parentCoordinates.some(Boolean))
+    ) {
+      throw new Error("Workflow Run Deadline 或 Parent 坐标无效");
+    }
+    const runId = workflowId(
+      "workflow_run",
+      input.tenantId,
+      input.actorId,
+      release.releaseId,
+      input.routeKey,
+      input.inputDigest,
+      input.idempotencyKey,
+    );
+    const run: AgentWorkflowRun = {
+      runId,
+      releaseId: release.releaseId,
+      tenantId: workflowCoordinate(input.tenantId),
+      actorId: workflowCoordinate(input.actorId),
+      routeKey: workflowCoordinate(input.routeKey),
+      inputDigest: input.inputDigest,
+      inputReceipt: structuredClone(input.inputReceipt),
+      scopeDigest: input.scopeDigest,
+      authorizationSnapshotDigest: input.authorizationSnapshotDigest,
+      toolPolicyDigest: input.toolPolicyDigest,
+      workspacePolicyDigest: input.workspacePolicyDigest,
+      executionPolicyDigest: input.executionPolicyDigest,
+      status: "accepted",
+      budget: structuredClone(budget),
+      usage: structuredClone(EMPTY_AGENT_WORKFLOW_USAGE),
+      deadlineAt: input.deadlineAt,
+      ...(input.sessionId
+        ? { sessionId: workflowCoordinate(input.sessionId) }
+        : {}),
+      ...(input.parentRunId ? { parentRunId: input.parentRunId } : {}),
+      ...(input.parentNodeId ? { parentNodeId: input.parentNodeId } : {}),
+      ...(input.parentNodeRunId
+        ? { parentNodeRunId: input.parentNodeRunId }
+        : {}),
+      createdAt,
+      updatedAt: createdAt,
+      version: 1,
+    };
+    assertRunPolicies(run);
+    const nodeRunId = workflowId("workflow_node_run", runId, entry.id, "1");
+    const initialNodeRun = {
+      nodeRunId,
+      runId,
+      nodeId: entry.id,
+      nodeType: entry.type,
+      status: "pending" as const,
+      attempt: 1,
+      maxAttempts: maxAttempts(entry),
+      idempotencyKey: workflowId("workflow_node_attempt", runId, entry.id, "1"),
+      inputArtifacts: structuredClone(input.inputArtifacts ?? []),
+      outputArtifacts: [],
+      createdAt,
+      updatedAt: createdAt,
+      version: 1,
+    };
+    return this.repository.createRun({
+      idempotencyKey: input.idempotencyKey,
+      run,
+      initialNodeRun,
+      event: workflowEvent({
+        runId,
+        idempotencyKey: "run-created",
+        at: createdAt,
+        parentEventId: input.parentEventId,
+        data: {
+          type: "workflow.run-created",
+          releaseId: release.releaseId,
+          inputReceipt: structuredClone(input.inputReceipt),
+          ...(input.parentRunId ? { parentRunId: input.parentRunId } : {}),
+          ...(input.parentNodeId ? { parentNodeId: input.parentNodeId } : {}),
+          ...(input.parentNodeRunId
+            ? { parentNodeRunId: input.parentNodeRunId }
+            : {}),
+          ...(input.delegationId ? { delegationId: input.delegationId } : {}),
+        },
+      }),
+    });
+  }
+
+  transitionRun(input: TransitionAgentWorkflowRunInput) {
+    return executeAgentWorkflowRunCommand({
+      repository: this.repository,
+      budgetLedger: this.budgetLedger,
+      request: input,
+    });
+  }
+
+  completionReadiness(runId: string) {
+    return workflowRunCompletionReadiness({
+      repository: this.repository,
+      budgetLedger: this.budgetLedger,
+      runId,
+    });
+  }
+
+  readBudget(runId: string) {
+    return this.budgetLedger.read(runId);
+  }
+
+  settleBudget(input: Parameters<WorkflowBudgetLedgerPort["settle"]>[0]) {
+    return this.budgetLedger.settle(input);
+  }
+
+  releaseBudget(input: Parameters<WorkflowBudgetLedgerPort["release"]>[0]) {
+    return this.budgetLedger.release(input);
+  }
+
+  async transitionNode(input: {
+    readonly runId: string;
+    readonly nodeRunId: string;
+    readonly expectedNodeVersion: number;
+    readonly expectedRunVersion?: number;
+    readonly expectedSequence: number;
+    readonly command: Exclude<
+      AgentWorkflowNodeRunCommand,
+      { type: "schedule-retry" }
+    >;
+    readonly cumulativeUsage?: AgentWorkflowUsage;
+    readonly effectCommandId?: string;
+    readonly idempotencyKey: string;
+    readonly at: string;
+  }) {
+    const snapshot = await this.requireSnapshot(input.runId);
+    const nodeRun = snapshot.nodeRuns.find(
+      ({ nodeRunId }) => nodeRunId === input.nodeRunId,
+    );
+    if (!nodeRun) throw new Error("Node Run 不存在");
+    const release = await this.requireRelease(snapshot.run.releaseId);
+    const definitionNode = findDefinitionNode(release, nodeRun);
+    assertNodeCommandAdmitted({
+      run: snapshot.run,
+      command: input.command,
+      effectCommandId: input.effectCommandId,
+      at: input.at,
+    });
+    if (input.command.type === "complete") {
+      await assertWorkflowNodeCompletion({
+        repository: this.repository,
+        effectFence: this.effectFence,
+        run: snapshot.run,
+        node: definitionNode,
+        receipt: input.command.receipt,
+        commandId: input.effectCommandId,
+      });
+    }
+    const value = transitionAgentWorkflowNodeRun({
+      nodeRun,
+      expectedVersion: input.expectedNodeVersion,
+      command: input.command,
+      at: workflowTimestamp(input.at),
+    });
+    const runUpdate = buildNodeCommandRunUpdate({
+      run: snapshot.run,
+      command: input.command,
+      cumulativeUsage: input.cumulativeUsage,
+      expectedRunVersion: input.expectedRunVersion,
+      at: input.at,
+    });
+    return this.repository.commit({
+      runId: input.runId,
+      expectedSequence: input.expectedSequence,
+      ...(runUpdate ? { runUpdate } : {}),
+      nodeUpdates: [{ expectedVersion: input.expectedNodeVersion, value }],
+      events: [
+        workflowEvent({
+          runId: input.runId,
+          idempotencyKey: input.idempotencyKey,
+          at: input.at,
+          data: nodeEventData(nodeRun, input.command),
+        }),
+      ],
+    });
+  }
+
+  scheduleRetry(input: ScheduleAgentWorkflowRetryInput) {
+    return scheduleAgentWorkflowRetry({
+      repository: this.repository,
+      request: input,
+    });
+  }
+
+  private async requireRelease(releaseId: string) {
+    const release = await this.repository.getRelease(releaseId);
+    if (!release) throw new Error("Workflow Release 不存在");
+    return release;
+  }
+
+  private async requireSnapshot(runId: string) {
+    const snapshot = await this.repository.getSnapshot(runId);
+    if (!snapshot) throw new Error("Workflow Run 不存在");
+    return snapshot;
+  }
+}