create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent-workflow/drizzle-budget-ledger-support.ts

@@ -0,0 +1,226 @@
+import {
+  agentWorkflowBudgetReservations,
+  agentWorkflowRuns,
+} from "@southwind-ai/database";
+import { and, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  assertReservationFits,
+  assertWorkflowAuthorizationFence,
+  calculateRemainingBudget,
+} from "./budget-validation.js";
+import type {
+  WorkflowBudgetLedgerPort,
+  WorkflowBudgetLedgerSnapshot,
+  WorkflowBudgetReservationRecord,
+} from "./budget-ledger.js";
+import { canonicalJson } from "./canonical-json.js";
+import { EMPTY_AGENT_WORKFLOW_USAGE } from "./usage.js";
+
+export async function reserveInTransaction(
+  tx: Transaction,
+  input: Parameters<WorkflowBudgetLedgerPort["reserve"]>[0],
+  alreadyLocked = false,
+) {
+  if (!alreadyLocked) await lockRun(tx, input.parentRunId);
+  const [run] = await tx
+    .select()
+    .from(agentWorkflowRuns)
+    .where(eq(agentWorkflowRuns.runId, input.parentRunId))
+    .limit(1);
+  if (!run) return ledgerConflict();
+  const now = new Date();
+  if (
+    ["completed", "failed", "cancelled", "timed-out"].includes(run.status) ||
+    run.cancellationRequestedAt
+  ) {
+    return { outcome: "run-terminal" as const, safeCode: "RUN_TERMINAL" };
+  }
+  try {
+    assertWorkflowAuthorizationFence(
+      input.authorizationFence,
+      run.actorId,
+      now,
+    );
+  } catch {
+    return {
+      outcome: "authorization-stale" as const,
+      safeCode: "AUTHORIZATION_STALE",
+    };
+  }
+  if (
+    run.version !== input.expectedLedgerVersion ||
+    input.authorizationFence.authorizationSnapshotDigest !==
+      run.authorizationSnapshotDigest ||
+    input.authorizationFence.runPolicyDigest !== run.executionPolicyDigest ||
+    input.deadlineAt !== new Date(run.deadlineAt).toISOString() ||
+    Date.parse(input.deadlineAt) <= now.getTime()
+  ) {
+    return {
+      outcome: "authorization-stale" as const,
+      safeCode: "RUN_POLICY_STALE",
+    };
+  }
+  const [existing] = await tx
+    .select()
+    .from(agentWorkflowBudgetReservations)
+    .where(
+      eq(agentWorkflowBudgetReservations.idempotencyKey, input.idempotencyKey),
+    )
+    .limit(1);
+  const activeRows = await tx
+    .select()
+    .from(agentWorkflowBudgetReservations)
+    .where(
+      and(
+        eq(agentWorkflowBudgetReservations.parentRunId, input.parentRunId),
+        eq(agentWorkflowBudgetReservations.status, "active"),
+      ),
+    )
+    .for("update");
+  if (existing) {
+    return existing.status === "active" &&
+      existing.reservationId === input.reservationId &&
+      existing.parentRunId === input.parentRunId &&
+      existing.delegationId === input.delegationId &&
+      existing.parentNodeRunId === input.parentNodeRunId &&
+      existing.authorizationSnapshotDigest ===
+        input.authorizationFence.authorizationSnapshotDigest &&
+      existing.runPolicyDigest === input.authorizationFence.runPolicyDigest &&
+      canonicalJson(existing.reservedJson) === canonicalJson(input.requested)
+      ? {
+          outcome: "replayed" as const,
+          reservation: toReservation(existing),
+          ledger: snapshot(run, activeRows.map(toReservation)),
+        }
+      : ledgerConflict();
+  }
+  const ledger = snapshot(run, activeRows.map(toReservation));
+  try {
+    assertReservationFits(input.requested, ledger.remaining);
+  } catch {
+    return { outcome: "budget-exceeded" as const, safeCode: "BUDGET_EXCEEDED" };
+  }
+  const [created] = await tx
+    .insert(agentWorkflowBudgetReservations)
+    .values({
+      reservationId: input.reservationId,
+      parentRunId: input.parentRunId,
+      parentNodeRunId: input.parentNodeRunId,
+      delegationId: input.delegationId,
+      idempotencyKey: input.idempotencyKey,
+      authorizationProofId: input.authorizationFence.proofId,
+      authorizationSnapshotDigest:
+        input.authorizationFence.authorizationSnapshotDigest,
+      runPolicyDigest: input.authorizationFence.runPolicyDigest,
+      reservedJson: input.requested,
+      consumedJson: EMPTY_AGENT_WORKFLOW_USAGE,
+      status: "active",
+      version: 1,
+      createdAt: now.getTime(),
+      updatedAt: now.getTime(),
+    })
+    .returning();
+  if (!created) return ledgerConflict();
+  const reservation = toReservation(created);
+  return {
+    outcome: "reserved" as const,
+    reservation,
+    ledger: snapshot(run, [...activeRows.map(toReservation), reservation]),
+  };
+}
+
+export async function readLocked(tx: Transaction, parentRunId: string) {
+  const [run] = await tx
+    .select()
+    .from(agentWorkflowRuns)
+    .where(eq(agentWorkflowRuns.runId, parentRunId))
+    .limit(1);
+  if (!run) throw new Error("Parent Workflow Run 不存在");
+  const rows = await tx
+    .select()
+    .from(agentWorkflowBudgetReservations)
+    .where(
+      and(
+        eq(agentWorkflowBudgetReservations.parentRunId, parentRunId),
+        eq(agentWorkflowBudgetReservations.status, "active"),
+      ),
+    );
+  return snapshot(run, rows.map(toReservation));
+}
+
+export function snapshot(
+  run: typeof agentWorkflowRuns.$inferSelect,
+  activeReservations: readonly WorkflowBudgetReservationRecord[],
+): WorkflowBudgetLedgerSnapshot {
+  return {
+    parentRunId: run.runId,
+    budget: run.budgetJson,
+    consumed: run.usageJson,
+    activeReservations,
+    remaining: calculateRemainingBudget({
+      budget: run.budgetJson,
+      consumed: run.usageJson,
+      activeReservations,
+    }),
+    version: run.version,
+  };
+}
+
+export function toReservation(
+  row: typeof agentWorkflowBudgetReservations.$inferSelect,
+): WorkflowBudgetReservationRecord {
+  return {
+    reservationId: row.reservationId,
+    parentRunId: row.parentRunId,
+    parentNodeRunId: row.parentNodeRunId,
+    delegationId: row.delegationId,
+    idempotencyKey: row.idempotencyKey,
+    authorizationProofId: row.authorizationProofId,
+    authorizationSnapshotDigest: row.authorizationSnapshotDigest,
+    runPolicyDigest: row.runPolicyDigest,
+    requested: row.reservedJson,
+    consumed: row.consumedJson,
+    status: reservationStatus(row.status),
+    version: row.version,
+    createdAt: new Date(row.createdAt).toISOString(),
+    ...(row.settledAt
+      ? { settledAt: new Date(row.settledAt).toISOString() }
+      : {}),
+    ...(row.usageReceiptId ? { usageReceiptId: row.usageReceiptId } : {}),
+    ...(row.reasonCode ? { reasonCode: row.reasonCode } : {}),
+  };
+}
+
+function reservationStatus(
+  value: string,
+): WorkflowBudgetReservationRecord["status"] {
+  if (value === "active" || value === "settled" || value === "released") {
+    return value;
+  }
+  throw new Error("Workflow Budget Reservation 状态无效");
+}
+
+export function sameSettlement(
+  row: WorkflowBudgetReservationRecord,
+  input: Parameters<WorkflowBudgetLedgerPort["settle"]>[0],
+) {
+  return (
+    row.usageReceiptId === input.usageReceiptId &&
+    canonicalJson(row.consumed) === canonicalJson(input.consumed)
+  );
+}
+
+export function ledgerConflict() {
+  return { outcome: "conflict" as const, safeCode: "BUDGET_LEDGER_CONFLICT" };
+}
+
+export async function lockRun(tx: Transaction, runId: string) {
+  await tx.execute(
+    sql`select 1 from ${agentWorkflowRuns} where ${agentWorkflowRuns.runId} = ${runId} for update`,
+  );
+}
+
+export type Transaction = Parameters<
+  Parameters<NodePgDatabase["transaction"]>[0]
+>[0];

package/template/apps/server/src/agent-workflow/drizzle-budget-ledger.ts

@@ -0,0 +1,189 @@
+import {
+  agentWorkflowBudgetReservations,
+  agentWorkflowDelegations,
+  agentWorkflowRuns,
+} from "@southwind-ai/database";
+import type { AgentDelegationGrant } from "@southwind-ai/shared";
+import { and, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { canonicalJson } from "./canonical-json.js";
+import type { WorkflowBudgetLedgerPort } from "./budget-ledger.js";
+import { settleInTransaction } from "./drizzle-budget-ledger-settlement.js";
+import {
+  ledgerConflict,
+  lockRun,
+  readLocked,
+  reserveInTransaction,
+  snapshot,
+  toReservation,
+} from "./drizzle-budget-ledger-support.js";
+
+type ReserveResult = Awaited<ReturnType<WorkflowBudgetLedgerPort["reserve"]>>;
+
+class DelegationReservationRollback extends Error {
+  constructor(readonly result: ReserveResult) {
+    super("Delegation 与 Budget Reservation 未能原子建立");
+  }
+}
+
+export class DrizzleWorkflowBudgetLedger implements WorkflowBudgetLedgerPort {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async read(parentRunId: string) {
+    return this.db.transaction(
+      async (tx) => {
+        const [run] = await tx
+          .select()
+          .from(agentWorkflowRuns)
+          .where(eq(agentWorkflowRuns.runId, parentRunId))
+          .limit(1);
+        if (!run) return undefined;
+        const reservations = await tx
+          .select()
+          .from(agentWorkflowBudgetReservations)
+          .where(
+            and(
+              eq(agentWorkflowBudgetReservations.parentRunId, parentRunId),
+              eq(agentWorkflowBudgetReservations.status, "active"),
+            ),
+          );
+        return snapshot(run, reservations.map(toReservation));
+      },
+      { isolationLevel: "repeatable read", accessMode: "read only" },
+    );
+  }
+
+  reserve(input: Parameters<WorkflowBudgetLedgerPort["reserve"]>[0]) {
+    return this.db.transaction((tx) => reserveInTransaction(tx, input));
+  }
+
+  settle(input: Parameters<WorkflowBudgetLedgerPort["settle"]>[0]) {
+    return this.db.transaction((tx) => settleInTransaction(tx, input));
+  }
+
+  release(input: Parameters<WorkflowBudgetLedgerPort["release"]>[0]) {
+    return this.db.transaction(async (tx) => {
+      await lockRun(tx, input.parentRunId);
+      const [row] = await tx
+        .select()
+        .from(agentWorkflowBudgetReservations)
+        .where(
+          eq(
+            agentWorkflowBudgetReservations.reservationId,
+            input.reservationId,
+          ),
+        )
+        .for("update")
+        .limit(1);
+      if (!row || row.parentRunId !== input.parentRunId)
+        return ledgerConflict();
+      if (row.status === "released") {
+        return row.reasonCode === input.reasonCode
+          ? {
+              outcome: "replayed" as const,
+              reservation: toReservation(row),
+              ledger: await readLocked(tx, input.parentRunId),
+            }
+          : ledgerConflict();
+      }
+      if (
+        row.status !== "active" ||
+        row.version !== input.expectedReservationVersion ||
+        row.authorizationSnapshotDigest !== input.authorizationSnapshotDigest ||
+        row.runPolicyDigest !== input.runPolicyDigest
+      )
+        return ledgerConflict();
+      const [updated] = await tx
+        .update(agentWorkflowBudgetReservations)
+        .set({
+          status: "released",
+          reasonCode: input.reasonCode,
+          usageReceiptId: null,
+          settledAt: Date.parse(input.releasedAt),
+          updatedAt: Date.parse(input.releasedAt),
+          version: row.version + 1,
+        })
+        .where(
+          and(
+            eq(
+              agentWorkflowBudgetReservations.reservationId,
+              row.reservationId,
+            ),
+            eq(agentWorkflowBudgetReservations.version, row.version),
+          ),
+        )
+        .returning();
+      if (!updated) return ledgerConflict();
+      return {
+        outcome: "released" as const,
+        reservation: toReservation(updated),
+        ledger: await readLocked(tx, input.parentRunId),
+      };
+    });
+  }
+
+  async createDelegationWithReservation(input: {
+    readonly grant: AgentDelegationGrant;
+    readonly parentNodeRunId: string;
+    readonly delegationIdempotencyKey: string;
+    readonly reservation: Parameters<WorkflowBudgetLedgerPort["reserve"]>[0];
+    readonly createdAt: string;
+  }) {
+    try {
+      return await this.db.transaction(async (tx) => {
+        if (
+          input.reservation.parentRunId !== input.grant.parentRunId ||
+          input.reservation.parentNodeRunId !== input.parentNodeRunId ||
+          input.reservation.delegationId !== input.grant.delegationId ||
+          input.grant.parentNodeRunId !== input.parentNodeRunId
+        ) {
+          return ledgerConflict();
+        }
+        await lockRun(tx, input.grant.parentRunId);
+        const [existing] = await tx
+          .select()
+          .from(agentWorkflowDelegations)
+          .where(
+            eq(
+              agentWorkflowDelegations.idempotencyKey,
+              input.delegationIdempotencyKey,
+            ),
+          )
+          .limit(1);
+        if (!existing) {
+          await tx.insert(agentWorkflowDelegations).values({
+            delegationId: input.grant.delegationId,
+            parentRunId: input.grant.parentRunId,
+            parentNodeId: input.grant.parentNodeId,
+            parentNodeRunId: input.parentNodeRunId,
+            idempotencyKey: input.delegationIdempotencyKey,
+            childSessionId: input.grant.childSessionId,
+            childAgentRunId: input.grant.childAgentRunId ?? null,
+            grantJson: input.grant,
+            status: input.grant.status,
+            createdAt: Date.parse(input.createdAt),
+            updatedAt: Date.parse(input.createdAt),
+          });
+        } else if (
+          existing.delegationId !== input.grant.delegationId ||
+          existing.parentNodeRunId !== input.parentNodeRunId ||
+          canonicalJson(existing.grantJson) !== canonicalJson(input.grant)
+        ) {
+          return ledgerConflict();
+        }
+        const reserved = await reserveInTransaction(
+          tx,
+          input.reservation,
+          true,
+        );
+        if (!existing && !["reserved", "replayed"].includes(reserved.outcome)) {
+          throw new DelegationReservationRollback(reserved);
+        }
+        return reserved;
+      });
+    } catch (error) {
+      if (error instanceof DelegationReservationRollback) return error.result;
+      throw error;
+    }
+  }
+}

package/template/apps/server/src/agent-workflow/drizzle-cancellation-reconcile.ts

@@ -0,0 +1,177 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  agentWorkflowNodeRuns,
+  agentWorkflowRuns,
+  agentWorkflowSideEffectCommands,
+  agentWorkflowSideEffectReceipts,
+} from "@southwind-ai/database";
+import { and, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  WorkflowEffectCommandFencePort,
+  WorkflowEffectCommandReceipt,
+  WorkflowEffectReconciliationClaimResult,
+} from "./effect-command-fence.js";
+import { isEffectReconciliationCandidate } from "./effect-command-fence.js";
+import type { AgentWorkflowSideEffectReceipt } from "@southwind-ai/shared";
+import {
+  toSideEffect,
+  toSideEffectReceipt,
+} from "./drizzle-repository-mappers.js";
+import { samePreparedSideEffect } from "./side-effect-state.js";
+import { canonicalJson } from "./canonical-json.js";
+
+export function claimEffectForCancellation(
+  db: NodePgDatabase,
+  input: Parameters<WorkflowEffectCommandFencePort["claimReconciliation"]>[0],
+) {
+  return db.transaction(async (tx) => {
+    await lockEffectCommand(tx, input.command.commandId);
+    const [command] = await tx
+      .select()
+      .from(agentWorkflowSideEffectCommands)
+      .where(
+        eq(agentWorkflowSideEffectCommands.commandId, input.command.commandId),
+      )
+      .limit(1);
+    if (!command) return effectFenceConflict("EFFECT_COMMAND_NOT_FOUND");
+    if (!samePreparedSideEffect(toSideEffect(command), input.command)) {
+      return effectFenceConflict("EFFECT_COMMAND_CONFLICT");
+    }
+    const [receipt] = await tx
+      .select()
+      .from(agentWorkflowSideEffectReceipts)
+      .where(eq(agentWorkflowSideEffectReceipts.commandId, command.commandId))
+      .limit(1);
+    if (receipt) {
+      return {
+        outcome: "replayed" as const,
+        receipt: toSideEffectReceipt(receipt),
+      };
+    }
+    const [[run], [nodeRun]] = await Promise.all([
+      tx
+        .select()
+        .from(agentWorkflowRuns)
+        .where(eq(agentWorkflowRuns.runId, command.runId))
+        .for("update")
+        .limit(1),
+      tx
+        .select()
+        .from(agentWorkflowNodeRuns)
+        .where(eq(agentWorkflowNodeRuns.nodeRunId, command.nodeRunId))
+        .for("update")
+        .limit(1),
+    ]);
+    if (
+      !run ||
+      ["completed", "failed", "cancelled", "timed-out"].includes(run.status) ||
+      !nodeRun ||
+      nodeRun.runId !== run.runId ||
+      !["running", "waiting"].includes(nodeRun.status)
+    ) {
+      return effectFenceConflict("WORKFLOW_RECONCILIATION_NOT_ACTIVE");
+    }
+    const current = toSideEffect(command);
+    if (
+      command.version !== input.expectedCommandVersion ||
+      !isEffectReconciliationCandidate(current) ||
+      (!run.cancellationRequestedAt &&
+        command.status !== "cancellation-requested")
+    ) {
+      return effectFenceConflict("EFFECT_RECONCILIATION_STALE");
+    }
+    const now = new Date();
+    const generation = Math.max(1, command.generation);
+    const fenceToken = `reconciliation.${randomBytes(32).toString("base64url")}`;
+    const fenceTokenDigest = effectFenceDigest(fenceToken);
+    const authorizationSnapshotDigest =
+      command.authorizationSnapshotDigest ?? run.authorizationSnapshotDigest;
+    const runPolicyDigest =
+      command.runPolicyDigest ?? run.executionPolicyDigest;
+    const [updated] = await tx
+      .update(agentWorkflowSideEffectCommands)
+      .set({
+        generation,
+        fenceTokenDigest,
+        authorizationSnapshotDigest,
+        runPolicyDigest,
+        status: "cancellation-requested",
+        safeErrorCode: null,
+        claimedAt: now.getTime(),
+        updatedAt: now.getTime(),
+        version: command.version + 1,
+      })
+      .where(
+        and(
+          eq(agentWorkflowSideEffectCommands.commandId, command.commandId),
+          eq(agentWorkflowSideEffectCommands.version, command.version),
+          eq(agentWorkflowSideEffectCommands.generation, command.generation),
+        ),
+      )
+      .returning();
+    if (!updated) return effectFenceConflict("EFFECT_RECONCILIATION_STALE");
+    return {
+      outcome: "claimed" as const,
+      fence: {
+        purpose: "reconciliation" as const,
+        commandId: updated.commandId,
+        runId: updated.runId,
+        nodeRunId: updated.nodeRunId,
+        effectKind: updated.effectKind,
+        adapter: input.command.adapter,
+        generation,
+        fenceToken,
+        fenceTokenDigest,
+        requestDigest: updated.requestDigest,
+        authorizationSnapshotDigest,
+        runPolicyDigest,
+        ...(updated.budgetReservationId
+          ? { budgetReservationId: updated.budgetReservationId }
+          : {}),
+        ...(updated.delegationId ? { delegationId: updated.delegationId } : {}),
+        claimedAt: now.toISOString(),
+      },
+    } satisfies WorkflowEffectReconciliationClaimResult;
+  });
+}
+
+export async function lockEffectCommand(tx: Transaction, commandId: string) {
+  await tx.execute(
+    sql`select 1 from ${agentWorkflowSideEffectCommands} where ${agentWorkflowSideEffectCommands.commandId} = ${commandId} for update`,
+  );
+}
+
+export function effectFenceDigest(value: string) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+export function effectFenceConflict(safeCode: string) {
+  return { outcome: "conflict" as const, safeCode };
+}
+
+export function sameEffectReceipt(
+  left: AgentWorkflowSideEffectReceipt,
+  right: WorkflowEffectCommandReceipt,
+) {
+  return (
+    left.receiptId === right.receiptId &&
+    left.commandId === right.commandId &&
+    left.runId === right.runId &&
+    left.nodeRunId === right.nodeRunId &&
+    left.effectKind === right.effectKind &&
+    left.generation === right.generation &&
+    left.fenceTokenDigest === right.fenceTokenDigest &&
+    left.requestDigest === right.requestDigest &&
+    left.externalReceiptId === right.externalReceiptId &&
+    left.resultDigest === right.resultDigest &&
+    canonicalJson(left.smallResult ?? null) ===
+      canonicalJson(right.smallResult ?? null) &&
+    canonicalJson(left.artifactRefs ?? []) ===
+      canonicalJson(right.artifactRefs ?? []) &&
+    left.authorizationSnapshotDigest === right.authorizationSnapshotDigest &&
+    left.runPolicyDigest === right.runPolicyDigest
+  );
+}
+
+type Transaction = Parameters<Parameters<NodePgDatabase["transaction"]>[0]>[0];