create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/side-effect-state.ts

@@ -0,0 +1,226 @@
+import type {
+  AgentWorkflowSideEffectCommand,
+  AgentWorkflowSideEffectReceipt,
+} from "@southwind-ai/shared";
+import { AgentWorkflowStateError } from "./state-machine.js";
+
+export interface PrepareAgentWorkflowSideEffectInput {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: AgentWorkflowSideEffectCommand["effectKind"];
+  readonly effectKey: string;
+  readonly adapter: AgentWorkflowSideEffectCommand["adapter"];
+  readonly idempotencyKey: string;
+  readonly requestDigest: string;
+  readonly budgetReservationId?: string;
+  readonly delegationId?: string;
+  readonly createdAt: string;
+}
+
+export type AgentWorkflowSideEffectTransition =
+  | {
+      readonly type: "dispatch";
+      readonly generation: number;
+      readonly fenceTokenDigest: string;
+      readonly authorizationSnapshotDigest: string;
+      readonly runPolicyDigest: string;
+      readonly budgetReservationId?: string;
+    }
+  | {
+      readonly type: "commit";
+      readonly receipt: AgentWorkflowSideEffectReceipt;
+    }
+  | { readonly type: "reconcile" }
+  | { readonly type: "request-cancel" }
+  | { readonly type: "cancel" }
+  | { readonly type: "fail"; readonly safeCode: string };
+
+export function prepareAgentWorkflowSideEffect(
+  input: PrepareAgentWorkflowSideEffectInput,
+): AgentWorkflowSideEffectCommand {
+  for (const [value, maximum] of [
+    [input.commandId, 96],
+    [input.runId, 96],
+    [input.nodeRunId, 96],
+    [input.effectKey, 160],
+    [input.idempotencyKey, 220],
+  ] as const) {
+    if (!validText(value, maximum))
+      invalid("Side-effect command identity 无效");
+  }
+  assertDigest(input.requestDigest);
+  if (
+    (input.effectKind === "subagent" &&
+      (!input.budgetReservationId || !input.delegationId)) ||
+    (input.effectKind !== "subagent" &&
+      (input.budgetReservationId !== undefined ||
+        input.delegationId !== undefined))
+  ) {
+    invalid("Subagent side-effect 缺少 Delegation/Budget Reservation 坐标");
+  }
+  if (!Number.isFinite(Date.parse(input.createdAt))) {
+    invalid("Side-effect command 时间无效");
+  }
+  return {
+    ...input,
+    generation: 0,
+    status: "prepared",
+    version: 1,
+    updatedAt: input.createdAt,
+  };
+}
+
+export function transitionAgentWorkflowSideEffect(input: {
+  readonly command: AgentWorkflowSideEffectCommand;
+  readonly expectedVersion: number;
+  readonly transition: AgentWorkflowSideEffectTransition;
+  readonly at: string;
+}): AgentWorkflowSideEffectCommand {
+  const { command, transition, at } = input;
+  if (command.version !== input.expectedVersion) {
+    stateError("VERSION_CONFLICT", "Side-effect command version 已变化");
+  }
+  if (
+    !Number.isFinite(Date.parse(at)) ||
+    Date.parse(at) < Date.parse(command.updatedAt)
+  ) {
+    invalid("Side-effect command 时间无效");
+  }
+  const target = targetStatus(command.status, transition.type);
+  if (transition.type === "commit") {
+    assertReceipt(command, transition.receipt);
+    if (transition.receipt.committedAt !== at) {
+      stateError("INVALID_RECEIPT", "Side-effect Receipt committedAt 不一致");
+    }
+  }
+  if (transition.type === "dispatch") {
+    if (transition.generation !== command.generation + 1) {
+      stateError("VERSION_CONFLICT", "Side-effect fence generation 已变化");
+    }
+    assertDigest(transition.fenceTokenDigest);
+    assertDigest(transition.authorizationSnapshotDigest);
+    assertDigest(transition.runPolicyDigest);
+  }
+  return {
+    ...command,
+    status: target,
+    ...(transition.type === "dispatch"
+      ? {
+          generation: transition.generation,
+          fenceTokenDigest: transition.fenceTokenDigest,
+          authorizationSnapshotDigest: transition.authorizationSnapshotDigest,
+          runPolicyDigest: transition.runPolicyDigest,
+          budgetReservationId: transition.budgetReservationId,
+          claimedAt: at,
+          safeErrorCode: undefined,
+        }
+      : {}),
+    ...(transition.type === "commit" ? { committedAt: at } : {}),
+    ...(transition.type === "fail"
+      ? { safeErrorCode: safeCode(transition.safeCode) }
+      : {}),
+    updatedAt: at,
+    version: command.version + 1,
+  };
+}
+
+function assertReceipt(
+  command: AgentWorkflowSideEffectCommand,
+  receipt: AgentWorkflowSideEffectReceipt,
+) {
+  if (
+    receipt.commandId !== command.commandId ||
+    receipt.runId !== command.runId ||
+    receipt.nodeRunId !== command.nodeRunId ||
+    receipt.generation !== command.generation ||
+    receipt.effectKind !== command.effectKind ||
+    receipt.fenceTokenDigest !== command.fenceTokenDigest ||
+    receipt.requestDigest !== command.requestDigest ||
+    receipt.authorizationSnapshotDigest !==
+      command.authorizationSnapshotDigest ||
+    receipt.runPolicyDigest !== command.runPolicyDigest ||
+    !validText(receipt.receiptId, 96) ||
+    !validText(receipt.externalReceiptId, 200)
+  ) {
+    stateError(
+      "INVALID_RECEIPT",
+      "Side-effect Receipt 与 command fence 不一致",
+    );
+  }
+  assertDigest(receipt.resultDigest);
+}
+
+export function samePreparedSideEffect(
+  left: AgentWorkflowSideEffectCommand,
+  right: AgentWorkflowSideEffectCommand,
+) {
+  return (
+    left.commandId === right.commandId &&
+    left.runId === right.runId &&
+    left.nodeRunId === right.nodeRunId &&
+    left.effectKind === right.effectKind &&
+    left.effectKey === right.effectKey &&
+    left.adapter.kind === right.adapter.kind &&
+    left.adapter.coordinate === right.adapter.coordinate &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.requestDigest === right.requestDigest &&
+    left.budgetReservationId === right.budgetReservationId &&
+    left.delegationId === right.delegationId
+  );
+}
+
+function targetStatus(
+  status: AgentWorkflowSideEffectCommand["status"],
+  transition: AgentWorkflowSideEffectTransition["type"],
+): AgentWorkflowSideEffectCommand["status"] {
+  const allowed: Record<
+    AgentWorkflowSideEffectCommand["status"],
+    readonly AgentWorkflowSideEffectTransition["type"][]
+  > = {
+    prepared: ["dispatch", "request-cancel", "fail"],
+    dispatched: ["dispatch", "commit", "request-cancel", "fail"],
+    "cancellation-requested": ["cancel", "commit", "fail"],
+    committed: ["reconcile"],
+    reconciled: [],
+    cancelled: [],
+    failed: [],
+  };
+  if (!allowed[status].includes(transition)) {
+    invalid(`Side-effect command 不允许 ${status} -> ${transition}`);
+  }
+  if (transition === "dispatch") return "dispatched";
+  if (transition === "commit") return "committed";
+  if (transition === "reconcile") return "reconciled";
+  if (transition === "request-cancel") return "cancellation-requested";
+  if (transition === "cancel") return "cancelled";
+  return "failed";
+}
+
+function assertDigest(value: string) {
+  if (!/^sha256:[a-f0-9]{64}$/.test(value)) {
+    stateError("INVALID_RECEIPT", "Side-effect digest 无效");
+  }
+}
+
+function safeCode(value: string) {
+  if (!/^[A-Z][A-Z0-9_]{0,79}$/.test(value)) {
+    invalid("Side-effect safe error code 无效");
+  }
+  return value;
+}
+
+function validText(value: string, maximum: number) {
+  return value.trim() === value && value.length > 0 && value.length <= maximum;
+}
+
+function invalid(message: string): never {
+  stateError("INVALID_TRANSITION", message);
+}
+
+function stateError(
+  code: ConstructorParameters<typeof AgentWorkflowStateError>[0],
+  message: string,
+): never {
+  throw new AgentWorkflowStateError(code, message);
+}

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

@@ -0,0 +1,321 @@
+import {
+  isAgentWorkflowNodeTerminal,
+  isAgentWorkflowNodeTransitionAllowed,
+  isAgentWorkflowRunTransitionAllowed,
+  isAgentWorkflowTerminal,
+  usageFitsWithinBudget,
+  type AgentWorkflowArtifactRef,
+  type AgentWorkflowNodeResultReceipt,
+  type AgentWorkflowNodeRun,
+  type AgentWorkflowRun,
+} from "@southwind-ai/shared";
+import { assertAgentWorkflowNodeResultReceipt } from "./node-result-receipt.js";
+import {
+  assertNodeRunStateInvariant,
+  assertRunStateInvariant,
+} from "./service-state-invariants.js";
+import {
+  AgentWorkflowStateError,
+  type AgentWorkflowStateErrorCode,
+} from "./service-state-error.js";
+
+export {
+  AgentWorkflowStateError,
+  type AgentWorkflowStateErrorCode,
+} from "./service-state-error.js";
+
+export type AgentWorkflowRunCommand =
+  | { readonly type: "start" }
+  | {
+      readonly type: "wait";
+      readonly adapter?: NonNullable<AgentWorkflowNodeRun["adapter"]>;
+    }
+  | { readonly type: "resume" }
+  | { readonly type: "complete" }
+  | { readonly type: "fail"; readonly safeCode: string }
+  | { readonly type: "request-cancel"; readonly reasonCode: string }
+  | { readonly type: "cancel" }
+  | { readonly type: "timeout" };
+
+export type AgentWorkflowNodeRunCommand =
+  | { readonly type: "ready" }
+  | { readonly type: "start" }
+  | {
+      readonly type: "wait";
+      readonly adapter?: NonNullable<AgentWorkflowNodeRun["adapter"]>;
+    }
+  | { readonly type: "resume" }
+  | {
+      readonly type: "complete";
+      readonly receipt: AgentWorkflowNodeResultReceipt;
+      readonly outputArtifacts: readonly AgentWorkflowArtifactRef[];
+    }
+  | {
+      readonly type: "schedule-retry";
+      readonly safeCode: string;
+    }
+  | { readonly type: "fail"; readonly safeCode: string }
+  | { readonly type: "cancel" }
+  | { readonly type: "skip" }
+  | { readonly type: "timeout" };
+
+export interface CreateAgentWorkflowRetryInput {
+  readonly source: AgentWorkflowNodeRun;
+  readonly nodeRunId: string;
+  readonly idempotencyKey: string;
+  readonly inputArtifacts?: AgentWorkflowNodeRun["inputArtifacts"];
+  readonly createdAt: string;
+}
+
+export function transitionAgentWorkflowRun(input: {
+  readonly run: AgentWorkflowRun;
+  readonly expectedVersion: number;
+  readonly command: AgentWorkflowRunCommand;
+  readonly at: string;
+}): AgentWorkflowRun {
+  const { run, command, at } = input;
+  assertVersion(run.version, input.expectedVersion);
+  assertRunStateInvariant(run);
+  assertTimestamp(at, run.updatedAt);
+  if (isAgentWorkflowTerminal(run.status)) {
+    fail("TERMINAL_RUN", "Workflow Run 终态不可继续变更");
+  }
+  if (
+    run.cancellationRequestedAt &&
+    !["cancel", "timeout"].includes(command.type)
+  ) {
+    fail("CANCELLATION_REQUESTED", "Workflow Run 已请求取消");
+  }
+  if (command.type === "cancel" && !run.cancellationRequestedAt) {
+    fail(
+      "INVALID_TRANSITION",
+      "Workflow Run 必须先持久 cancellation-requested",
+    );
+  }
+  if (
+    Date.parse(at) >= Date.parse(run.deadlineAt) &&
+    !["request-cancel", "timeout"].includes(command.type)
+  ) {
+    fail("DEADLINE_EXCEEDED", "Workflow Run 已超过 Deadline");
+  }
+
+  if (
+    command.type === "complete" &&
+    !usageFitsWithinBudget(run.usage, run.budget)
+  ) {
+    fail("USAGE_UNMEASURED", "Workflow Run Usage 未完整计量或已超过 Budget");
+  }
+  if (command.type === "request-cancel") safeCode(command.reasonCode);
+
+  const next = runStatus(run.status, command.type);
+  const value = {
+    ...run,
+    status: next,
+    ...(command.type === "request-cancel" && !run.cancellationRequestedAt
+      ? { cancellationRequestedAt: at }
+      : {}),
+    ...(command.type === "fail"
+      ? { safeErrorCode: safeCode(command.safeCode) }
+      : {}),
+    ...(["cancel", "timeout", "complete"].includes(command.type)
+      ? { safeErrorCode: undefined }
+      : {}),
+    updatedAt: at,
+    ...(isAgentWorkflowTerminal(next) ? { finishedAt: at } : {}),
+    version: run.version + 1,
+  };
+  assertRunStateInvariant(value);
+  return value;
+}
+
+export function transitionAgentWorkflowNodeRun(input: {
+  readonly nodeRun: AgentWorkflowNodeRun;
+  readonly expectedVersion: number;
+  readonly command: AgentWorkflowNodeRunCommand;
+  readonly at: string;
+}): AgentWorkflowNodeRun {
+  const { nodeRun, command, at } = input;
+  assertVersion(nodeRun.version, input.expectedVersion);
+  assertNodeRunStateInvariant(nodeRun);
+  assertTimestamp(at, nodeRun.updatedAt);
+  if (
+    isAgentWorkflowNodeTerminal(nodeRun.status) &&
+    !(nodeRun.status === "failed" && command.type === "schedule-retry")
+  ) {
+    fail("TERMINAL_NODE_RUN", "Node Run 终态不可继续变更");
+  }
+  const status = nodeStatus(nodeRun.status, command.type);
+  if (
+    command.type === "schedule-retry" &&
+    nodeRun.attempt >= nodeRun.maxAttempts
+  ) {
+    fail("RETRY_EXHAUSTED", "Node Run 已耗尽重试次数");
+  }
+  if (command.type === "complete") {
+    try {
+      assertAgentWorkflowNodeResultReceipt(
+        nodeRun,
+        command.receipt,
+        command.outputArtifacts,
+        at,
+      );
+    } catch (error) {
+      fail(
+        "INVALID_RECEIPT",
+        error instanceof Error ? error.message : "Node Result Receipt 无效",
+      );
+    }
+  }
+  const startedAt =
+    command.type === "start" ? (nodeRun.startedAt ?? at) : nodeRun.startedAt;
+  const finishedAt =
+    isAgentWorkflowNodeTerminal(status) || status === "retry-scheduled"
+      ? at
+      : undefined;
+  const value = {
+    ...nodeRun,
+    status,
+    ...(command.type === "complete"
+      ? {
+          resultReceipt: structuredClone(command.receipt),
+          outputArtifacts: structuredClone(command.outputArtifacts),
+          safeErrorCode: undefined,
+        }
+      : {}),
+    ...(command.type === "wait" && command.adapter
+      ? { adapter: structuredClone(command.adapter) }
+      : {}),
+    ...(command.type === "fail" || command.type === "schedule-retry"
+      ? { safeErrorCode: safeCode(command.safeCode) }
+      : {}),
+    startedAt,
+    finishedAt,
+    updatedAt: at,
+    version: nodeRun.version + 1,
+  };
+  assertNodeRunStateInvariant(value);
+  return value;
+}
+
+export function createAgentWorkflowRetry(
+  input: CreateAgentWorkflowRetryInput,
+): AgentWorkflowNodeRun {
+  const { source } = input;
+  if (source.status !== "retry-scheduled") {
+    fail("INVALID_TRANSITION", "仅 retry-scheduled Node Run 可创建新尝试");
+  }
+  if (source.attempt >= source.maxAttempts) {
+    fail("RETRY_EXHAUSTED", "Node Run 已耗尽重试次数");
+  }
+  if (!input.nodeRunId.trim() || !input.idempotencyKey.trim()) {
+    fail("INVALID_TRANSITION", "重试 Node Run identity 无效");
+  }
+  assertTimestamp(input.createdAt, source.updatedAt);
+  return {
+    nodeRunId: input.nodeRunId,
+    runId: source.runId,
+    nodeId: source.nodeId,
+    previousNodeRunId: source.nodeRunId,
+    nodeType: source.nodeType,
+    status: "pending",
+    attempt: source.attempt + 1,
+    maxAttempts: source.maxAttempts,
+    idempotencyKey: input.idempotencyKey,
+    inputArtifacts: structuredClone(
+      input.inputArtifacts ?? source.inputArtifacts,
+    ),
+    outputArtifacts: [],
+    createdAt: input.createdAt,
+    updatedAt: input.createdAt,
+    version: 1,
+  };
+}
+
+function runStatus(
+  status: AgentWorkflowRun["status"],
+  command: AgentWorkflowRunCommand["type"],
+): AgentWorkflowRun["status"] {
+  const target: Record<
+    AgentWorkflowRunCommand["type"],
+    AgentWorkflowRun["status"]
+  > = {
+    start: "running",
+    wait: "waiting",
+    resume: "running",
+    complete: "completed",
+    fail: "failed",
+    "request-cancel": status,
+    cancel: "cancelled",
+    timeout: "timed-out",
+  };
+  const next = target[command];
+  if (
+    command !== "request-cancel" &&
+    !isAgentWorkflowRunTransitionAllowed(status, next)
+  ) {
+    invalidTransition("Workflow Run", status, command);
+  }
+  if (
+    command === "request-cancel" &&
+    !["accepted", "running", "waiting"].includes(status)
+  ) {
+    invalidTransition("Workflow Run", status, command);
+  }
+  return next;
+}
+
+function nodeStatus(
+  status: AgentWorkflowNodeRun["status"],
+  command: AgentWorkflowNodeRunCommand["type"],
+): AgentWorkflowNodeRun["status"] {
+  const statuses: Record<
+    AgentWorkflowNodeRunCommand["type"],
+    AgentWorkflowNodeRun["status"]
+  > = {
+    ready: "ready",
+    start: "running",
+    wait: "waiting",
+    resume: "running",
+    complete: "completed",
+    "schedule-retry": "retry-scheduled",
+    fail: "failed",
+    cancel: "cancelled",
+    skip: "skipped",
+    timeout: "timed-out",
+  };
+  const next = statuses[command];
+  if (!isAgentWorkflowNodeTransitionAllowed(status, next)) {
+    invalidTransition("Node Run", status, command);
+  }
+  return next;
+}
+
+function assertVersion(actual: number, expected: number) {
+  if (actual !== expected) fail("VERSION_CONFLICT", "Workflow version 已变化");
+}
+
+function assertTimestamp(value: string, previous?: string) {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || (previous && time < Date.parse(previous))) {
+    fail("INVALID_TRANSITION", "Workflow 状态时间无效");
+  }
+}
+
+function safeCode(value: string) {
+  if (!/^[A-Z][A-Z0-9_]{0,79}$/.test(value)) {
+    fail("INVALID_TRANSITION", "Workflow safe error code 无效");
+  }
+  return value;
+}
+
+function invalidTransition(
+  scope: string,
+  status: string,
+  command: string,
+): never {
+  fail("INVALID_TRANSITION", `${scope} 不允许 ${status} -> ${command}`);
+}
+
+function fail(code: AgentWorkflowStateErrorCode, message: string): never {
+  throw new AgentWorkflowStateError(code, message);
+}