create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,249 @@
+import type {
+  AgentWorkflowNodeRun,
+  AgentWorkflowSideEffectCommand,
+} from "@southwind-ai/shared";
+import type {
+  AgentWorkflowAdapterDispatchResult,
+  AgentWorkflowAdapterPreparation,
+  AgentWorkflowNodeAdapter,
+  AgentWorkflowNodeAdapterContext,
+} from "./adapter-dispatch.js";
+import {
+  awaitScheduledNode,
+  deadlineCompletionAt,
+  scheduledNodeSignal,
+} from "./scheduler-deadline.js";
+import {
+  dispatchResultAt,
+  failScheduledEffect,
+} from "./scheduler-effect-result.js";
+import {
+  convergeDispatch,
+  convergeFailure,
+  convergeWait,
+} from "./scheduler-execution-convergence.js";
+import type {
+  executeScheduledNode,
+  SchedulerExecutionDependencies,
+} from "./scheduler-execution.js";
+import { prepareAgentWorkflowSideEffect } from "./side-effect-state.js";
+import { workflowId } from "./service-support.js";
+
+type UnclaimedEffect = Exclude<
+  Awaited<ReturnType<SchedulerExecutionDependencies["effectFence"]["claim"]>>,
+  { readonly outcome: "claimed" }
+>;
+
+export async function executePreparedSideEffect(
+  dependencies: SchedulerExecutionDependencies,
+  state: {
+    readonly input: Parameters<typeof executeScheduledNode>[1];
+    readonly snapshot: Awaited<
+      ReturnType<SchedulerExecutionDependencies["requireSnapshot"]>
+    >;
+    readonly running: AgentWorkflowNodeRun;
+    readonly context: AgentWorkflowNodeAdapterContext;
+    readonly adapter: AgentWorkflowNodeAdapter;
+    readonly preparation: Extract<
+      AgentWorkflowAdapterPreparation,
+      { readonly outcome: "effect" }
+    >;
+    readonly preparedAt: string;
+    readonly deadlineAt: string;
+    readonly deadline: ReturnType<typeof scheduledNodeSignal>;
+  },
+) {
+  const { input, running, preparation } = state;
+  const command = prepareAgentWorkflowSideEffect({
+    commandId: workflowId(
+      "workflow_effect",
+      running.nodeRunId,
+      preparation.effectKey,
+    ),
+    runId: input.runId,
+    nodeRunId: running.nodeRunId,
+    effectKind: preparation.effectKind,
+    effectKey: preparation.effectKey,
+    adapter: preparation.adapter,
+    idempotencyKey: workflowId(
+      "workflow_effect_idem",
+      running.idempotencyKey,
+      preparation.effectKey,
+    ),
+    requestDigest: preparation.requestDigest,
+    budgetReservationId: preparation.budgetReservationId,
+    delegationId: preparation.delegationId,
+    createdAt: state.preparedAt,
+  });
+  const prepared = await dependencies.repository.prepareSideEffect(command);
+  const claim = await dependencies.effectFence.claim({
+    command: prepared.command,
+    expectedCommandVersion: prepared.command.version,
+    authorizationFence: input.authorizationFence,
+    budgetReservationId: preparation.budgetReservationId,
+    deadlineAt: state.deadlineAt,
+  });
+  if (claim.outcome !== "claimed") {
+    return convergeUnclaimed(dependencies, state, prepared.command, claim);
+  }
+  if (!state.adapter.dispatch) {
+    await failScheduledEffect(
+      dependencies,
+      prepared.command.commandId,
+      "ADAPTER_DISPATCH_MISSING",
+      monotonicAt(state.preparedAt),
+    );
+    return dependencies.serializeMutation(() =>
+      convergeFailure(
+        dependencies,
+        input,
+        running,
+        "ADAPTER_DISPATCH_MISSING",
+        state.preparedAt,
+      ),
+    );
+  }
+  let dispatched: AgentWorkflowAdapterDispatchResult;
+  try {
+    dispatched = await awaitScheduledNode(
+      state.adapter.dispatch({
+        context: state.context,
+        command: prepared.command,
+        fence: claim.fence,
+      }),
+      state.deadline,
+    );
+  } catch {
+    const waitingAt = state.deadline.expired()
+      ? deadlineCompletionAt(state.deadlineAt, running.updatedAt)
+      : monotonicAt(state.preparedAt, running.updatedAt);
+    return dependencies.serializeMutation(() =>
+      convergeWait(
+        dependencies,
+        input.runId,
+        running,
+        prepared.command.adapter,
+        waitingAt,
+      ),
+    );
+  }
+  const dispatchedAt = monotonicAt(
+    state.preparedAt,
+    dispatchResultAt(state.preparedAt, dispatched),
+  );
+  if (dispatched.outcome === "committed") {
+    const committed = await dependencies.effectFence.commit({
+      fence: claim.fence,
+      receipt: dispatched.receipt,
+    });
+    if (committed.outcome === "conflict") {
+      return dependencies.serializeMutation(() =>
+        convergeWait(
+          dependencies,
+          input.runId,
+          running,
+          prepared.command.adapter,
+          dispatchedAt,
+        ),
+      );
+    }
+  }
+  return dependencies.serializeMutation(() =>
+    convergeDispatch(
+      dependencies,
+      input.runId,
+      running,
+      command.commandId,
+      dispatched,
+      dispatchedAt,
+    ),
+  );
+}
+
+async function convergeUnclaimed(
+  dependencies: SchedulerExecutionDependencies,
+  state: Parameters<typeof executePreparedSideEffect>[1],
+  command: AgentWorkflowSideEffectCommand,
+  claim: UnclaimedEffect,
+) {
+  const { input, running, preparation } = state;
+  if (claim.outcome === "replayed") {
+    if (!state.adapter.reconcile) {
+      return dependencies.serializeMutation(() =>
+        convergeWait(
+          dependencies,
+          input.runId,
+          running,
+          preparation.adapter,
+          state.preparedAt,
+        ),
+      );
+    }
+    const reconciled = await awaitScheduledNode(
+      state.adapter.reconcile({
+        context: state.context,
+        command,
+        authorizationFence: input.authorizationFence,
+        committedReceipt: claim.receipt,
+      }),
+      state.deadline,
+    ).catch(() => ({ outcome: "pending" as const }));
+    const at = monotonicAt(
+      state.preparedAt,
+      dispatchResultAt(state.preparedAt, reconciled),
+    );
+    return dependencies.serializeMutation(() =>
+      reconciled.outcome === "pending" || reconciled.outcome === "failed"
+        ? convergeWait(
+            dependencies,
+            input.runId,
+            running,
+            preparation.adapter,
+            at,
+          )
+        : convergeDispatch(
+            dependencies,
+            input.runId,
+            running,
+            command.commandId,
+            reconciled,
+            at,
+          ),
+    );
+  }
+  if (claim.outcome === "conflict") {
+    return dependencies.serializeMutation(() =>
+      convergeWait(
+        dependencies,
+        input.runId,
+        running,
+        preparation.adapter,
+        state.preparedAt,
+      ),
+    );
+  }
+  await failScheduledEffect(
+    dependencies,
+    command.commandId,
+    claim.safeCode,
+    state.preparedAt,
+  );
+  return dependencies.serializeMutation(() =>
+    convergeFailure(
+      dependencies,
+      input,
+      running,
+      claim.safeCode,
+      state.preparedAt,
+    ),
+  );
+}
+
+function monotonicAt(...values: Array<string | undefined>) {
+  return new Date(
+    Math.max(
+      Date.now(),
+      ...values.map((value) => Date.parse(value ?? "") || 0),
+    ),
+  ).toISOString();
+}

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

@@ -0,0 +1,235 @@
+import type {
+  AgentWorkflowDefinition,
+  AgentWorkflowNode,
+  AgentWorkflowNodeRun,
+} from "@southwind-ai/shared";
+
+export function schedulableSuccessors(input: {
+  readonly definition: AgentWorkflowDefinition;
+  readonly completed: AgentWorkflowNodeRun;
+  readonly nodeRuns: readonly AgentWorkflowNodeRun[];
+}): readonly AgentWorkflowNode[] {
+  const { definition, completed, nodeRuns } = input;
+  if (!["completed", "skipped"].includes(completed.status)) return [];
+  const source = definition.nodes.find(({ id }) => id === completed.nodeId);
+  if (!source) throw new Error("Completed Node 不属于 immutable Definition");
+  const edges = definition.edges.filter(({ from }) => from === source.id);
+  const selected =
+    source.type === "condition"
+      ? edges.filter(
+          ({ branch }) => branch === completed.resultReceipt?.selectedBranch,
+        )
+      : edges;
+  const candidates = selected
+    .map(({ to }) => definition.nodes.find(({ id }) => id === to)!)
+    .filter(
+      (node) =>
+        isJoinReady(node, definition, nodeRuns) &&
+        !nodeRuns.some(({ nodeId }) => nodeId === node.id),
+    );
+  if (source.type !== "parallel") return candidates;
+  const branchIds = new Set(edges.map(({ to }) => to));
+  const active = nodeRuns.filter(
+    (item) =>
+      branchIds.has(item.nodeId) &&
+      !["completed", "failed", "cancelled", "skipped", "timed-out"].includes(
+        item.status,
+      ),
+  ).length;
+  return candidates.slice(0, Math.max(0, source.maxConcurrency - active));
+}
+
+export function initiallySchedulable(
+  definition: AgentWorkflowDefinition,
+  nodeRuns: readonly AgentWorkflowNodeRun[],
+) {
+  const entry = definition.nodes.find(
+    ({ id }) => id === definition.entryNodeId,
+  )!;
+  return nodeRuns.some(({ nodeId }) => nodeId === entry.id) ? [] : [entry];
+}
+
+export type AgentWorkflowFailureDecision =
+  | { readonly type: "retry"; readonly backoffSeconds: number }
+  | { readonly type: "skip" }
+  | { readonly type: "fallback"; readonly nodeId: string }
+  | { readonly type: "fail-run" };
+
+export function failureDecision(
+  node: AgentWorkflowNode,
+  nodeRun: AgentWorkflowNodeRun,
+): AgentWorkflowFailureDecision {
+  const policy = node.failurePolicy;
+  if (policy.mode === "skip") return { type: "skip" };
+  if (policy.mode === "fail-run") return { type: "fail-run" };
+  if (policy.mode === "fallback") {
+    return { type: "fallback", nodeId: policy.nodeId };
+  }
+  if (nodeRun.attempt < policy.maxAttempts) {
+    return { type: "retry", backoffSeconds: policy.backoffSeconds };
+  }
+  return { type: policy.exhausted };
+}
+
+export function adapterKind(node: AgentWorkflowNode) {
+  switch (node.type) {
+    case "model":
+      return "model-operation" as const;
+    case "tool":
+      return "agent-tool" as const;
+    case "subagent":
+      return "child-agent" as const;
+    case "approval":
+      return "approval-work-item" as const;
+    case "job":
+      return "durable-job" as const;
+    case "wait":
+      return "wait-signal" as const;
+    case "artifact":
+      return "artifact-store" as const;
+    case "final":
+    case "condition":
+    case "parallel":
+    case "join":
+      return "finalizer" as const;
+  }
+}
+
+function isJoinReady(
+  node: AgentWorkflowNode,
+  definition: AgentWorkflowDefinition,
+  nodeRuns: readonly AgentWorkflowNodeRun[],
+) {
+  if (node.type !== "join") return true;
+  const reachable = effectiveReachableNodes(definition, nodeRuns);
+  const predecessors = definition.edges
+    .filter(({ to }) => to === node.id)
+    .map(({ from }) => from)
+    .filter((nodeId) => reachable.has(nodeId));
+  const latest = predecessors.map(
+    (nodeId) =>
+      nodeRuns
+        .filter((run) => run.nodeId === nodeId)
+        .sort((left, right) => right.attempt - left.attempt)[0],
+  );
+  if (node.strategy === "any") {
+    return latest.some((run) => run?.status === "completed");
+  }
+  const settled = latest.every((run) =>
+    ["completed", "failed", "cancelled", "skipped", "timed-out"].includes(
+      run?.status ?? "pending",
+    ),
+  );
+  return node.strategy === "all-settled"
+    ? settled
+    : latest.every((run) =>
+        ["completed", "skipped"].includes(run?.status ?? "pending"),
+      );
+}
+
+export function joinAnyLoserNodeIds(input: {
+  readonly definition: AgentWorkflowDefinition;
+  readonly joinId: string;
+  readonly nodeRuns: readonly AgentWorkflowNodeRun[];
+}) {
+  const predecessors = input.definition.edges
+    .filter(({ to }) => to === input.joinId)
+    .map(({ from }) => from);
+  const winners = predecessors.filter(
+    (nodeId) => latestRun(input.nodeRuns, nodeId)?.status === "completed",
+  );
+  const losers = predecessors.filter((nodeId) => !winners.includes(nodeId));
+  const edges = effectiveEdges(input.definition, input.nodeRuns);
+  const loserAncestors = ancestorsOf(edges, losers);
+  const winnerAncestors = ancestorsOf(edges, winners);
+  const loserRoots = [...loserAncestors].filter(
+    (nodeId) => !winnerAncestors.has(nodeId),
+  );
+  const winnerRoots = [...winnerAncestors].filter(
+    (nodeId) => !loserAncestors.has(nodeId),
+  );
+  const loserDescendants = descendantsOf(edges, loserRoots);
+  const winnerDescendants = descendantsOf(edges, winnerRoots);
+  return new Set(
+    [...loserDescendants].filter((nodeId) => !winnerDescendants.has(nodeId)),
+  );
+}
+
+function effectiveReachableNodes(
+  definition: AgentWorkflowDefinition,
+  nodeRuns: readonly AgentWorkflowNodeRun[],
+) {
+  const reachable = new Set<string>();
+  const fallbackTargets = definition.nodes.flatMap((source) => {
+    const policy = source.failurePolicy;
+    return policy.mode === "fallback" &&
+      latestRun(nodeRuns, source.id)?.status === "failed" &&
+      nodeRuns.some(({ nodeId }) => nodeId === policy.nodeId)
+      ? [policy.nodeId]
+      : [];
+  });
+  const pending = [definition.entryNodeId, ...fallbackTargets];
+  const edges = effectiveEdges(definition, nodeRuns);
+  while (pending.length) {
+    const nodeId = pending.shift()!;
+    if (reachable.has(nodeId)) continue;
+    reachable.add(nodeId);
+    for (const edge of edges.filter(({ from }) => from === nodeId)) {
+      pending.push(edge.to);
+    }
+  }
+  return reachable;
+}
+
+function latestRun(nodeRuns: readonly AgentWorkflowNodeRun[], nodeId: string) {
+  return nodeRuns
+    .filter((run) => run.nodeId === nodeId)
+    .sort((left, right) => right.attempt - left.attempt)[0];
+}
+
+function effectiveEdges(
+  definition: AgentWorkflowDefinition,
+  nodeRuns: readonly AgentWorkflowNodeRun[],
+) {
+  return definition.edges.filter((edge) => {
+    const node = definition.nodes.find(({ id }) => id === edge.from);
+    if (node?.type !== "condition") return true;
+    const selected = latestRun(nodeRuns, node.id)?.resultReceipt
+      ?.selectedBranch;
+    return !selected || edge.branch === selected;
+  });
+}
+
+function ancestorsOf(
+  edges: readonly { readonly from: string; readonly to: string }[],
+  targets: readonly string[],
+) {
+  const seen = new Set<string>();
+  const pending = [...targets];
+  while (pending.length) {
+    const current = pending.shift()!;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    pending.push(
+      ...edges.filter(({ to }) => to === current).map(({ from }) => from),
+    );
+  }
+  return seen;
+}
+
+function descendantsOf(
+  edges: readonly { readonly from: string; readonly to: string }[],
+  roots: readonly string[],
+) {
+  const seen = new Set<string>();
+  const pending = [...roots];
+  while (pending.length) {
+    const current = pending.shift()!;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    pending.push(
+      ...edges.filter(({ from }) => from === current).map(({ to }) => to),
+    );
+  }
+  return seen;
+}