create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent-workflow/drizzle-artifact-port.ts

@@ -0,0 +1,211 @@
+import { durableJobArtifacts, durableJobs } from "@southwind-ai/database";
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { hashAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { DurableArtifactService } from "../jobs/artifact-service.js";
+import type { AgentWorkflowArtifactPolicyRegistry } from "./artifact-policy.js";
+import { AgentWorkflowArtifactAccessError } from "./artifact-access-error.js";
+import type { AgentWorkflowArtifactSourceAuthorizationPort } from "./artifact-source-authorization.js";
+import type { AgentWorkflowArtifactPort } from "./node-execution-ports.js";
+import {
+  derivedWorkflowArtifact,
+  derivedWorkflowDurableArtifact,
+  durableWorkflowArtifactRef,
+  samePersistedWorkflowSeal,
+  sameWorkflowArtifact,
+} from "./drizzle-artifact-support.js";
+import {
+  AgentWorkflowArtifactTokenCodec,
+  AgentWorkflowArtifactTokenError,
+} from "./workflow-artifact-token.js";
+
+export class DrizzleAgentWorkflowArtifactPort implements AgentWorkflowArtifactPort {
+  private readonly tokens: AgentWorkflowArtifactTokenCodec;
+
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly durableArtifacts: DurableArtifactService,
+    private readonly policies: AgentWorkflowArtifactPolicyRegistry,
+    private readonly sourceAuthorization: AgentWorkflowArtifactSourceAuthorizationPort,
+    tokenSecret: string,
+  ) {
+    this.tokens = new AgentWorkflowArtifactTokenCodec(tokenSecret);
+  }
+
+  async seal(input: Parameters<AgentWorkflowArtifactPort["seal"]>[0]) {
+    const policy = this.policies.require(input.policyKey, input.artifactKind);
+    const sealed: AgentWorkflowArtifactRef[] = [];
+    for (const source of input.sourceArtifacts) {
+      this.policies.assertArtifact(policy, source);
+      const origin = await this.authorizedDurable(
+        source,
+        input.actorId,
+        input.scopeDigest,
+      );
+      if (!origin) throw forbidden();
+      const artifact = derivedWorkflowArtifact(
+        source,
+        input.policyKey,
+        input.artifactKind,
+      );
+      const durable = derivedWorkflowDurableArtifact(
+        origin,
+        artifact,
+        input.actorId,
+        input.scopeDigest,
+      );
+      await this.db
+        .insert(durableJobArtifacts)
+        .values(durable)
+        .onConflictDoNothing({ target: durableJobArtifacts.id });
+      const persisted = await this.durableById(artifact.artifactId);
+      if (!persisted || !samePersistedWorkflowSeal(persisted, durable)) {
+        throw new Error("ARTIFACT_SEAL_CONFLICT");
+      }
+      sealed.push(artifact);
+    }
+    return sealed;
+  }
+
+  async reauthorize(
+    input: Parameters<AgentWorkflowArtifactPort["reauthorize"]>[0],
+  ) {
+    for (const artifact of input.artifacts) {
+      if (
+        !(await this.authorizedDurable(
+          artifact,
+          input.actorId,
+          input.scopeDigest,
+        ))
+      ) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  async resolve(input: Parameters<AgentWorkflowArtifactPort["resolve"]>[0]) {
+    const artifact = await this.refById(input.artifactId);
+    if (
+      !artifact ||
+      !(await this.authorizedDurable(
+        artifact,
+        input.actorId,
+        input.scopeDigest,
+      ))
+    ) {
+      throw forbidden();
+    }
+    const expiresAt = new Date(Date.now() + 60_000).toISOString();
+    return {
+      artifact,
+      expiresAt,
+      token: this.tokens.issue({
+        artifactId: artifact.artifactId,
+        actorId: input.actorId,
+        scopeDigest: input.scopeDigest,
+        expiresAt,
+      }),
+    };
+  }
+
+  async open(input: Parameters<AgentWorkflowArtifactPort["open"]>[0]) {
+    let claims;
+    try {
+      claims = this.tokens.verify(input.token);
+    } catch (error) {
+      if (error instanceof AgentWorkflowArtifactTokenError) {
+        throw new AgentWorkflowArtifactAccessError(
+          "ARTIFACT_TOKEN_INVALID",
+          400,
+        );
+      }
+      throw error;
+    }
+    if (
+      claims.actorId !== input.actorId ||
+      claims.scopeDigest !== input.scopeDigest ||
+      Date.parse(claims.expiresAt) <= Date.now()
+    ) {
+      throw new AgentWorkflowArtifactAccessError("ARTIFACT_TOKEN_INVALID", 400);
+    }
+    const artifact = await this.refById(claims.artifactId);
+    const durable = artifact
+      ? await this.authorizedDurable(artifact, input.actorId, input.scopeDigest)
+      : undefined;
+    if (!artifact || !durable) throw forbidden();
+    const opened = await this.durableArtifacts.open(
+      durable.jobId,
+      durable.kind,
+      input.actorId,
+    );
+    return {
+      artifact,
+      body: opened.body,
+      filename: durable.filename,
+      contentType: durable.contentType,
+    };
+  }
+
+  private async authorizedDurable(
+    artifact: AgentWorkflowArtifactRef,
+    actorId: string,
+    scopeDigest: string,
+  ) {
+    const durable = await this.durableById(artifact.artifactId);
+    if (!durable || !sameWorkflowArtifact(durable, artifact)) return undefined;
+    try {
+      await this.sourceAuthorization.requireCurrent({
+        artifact,
+        actorId,
+        scopeDigest,
+      });
+    } catch {
+      return undefined;
+    }
+    const [job] = await this.db
+      .select({ authorizationScope: durableJobs.authorizationScope })
+      .from(durableJobs)
+      .where(eq(durableJobs.id, durable.jobId))
+      .limit(1);
+    if (
+      !job?.authorizationScope ||
+      `sha256:${hashAuthorizationScope(job.authorizationScope)}` !== scopeDigest
+    ) {
+      return undefined;
+    }
+    const inspected = await this.durableArtifacts
+      .inspect(durable.jobId, durable.kind, actorId)
+      .catch(() => undefined);
+    return inspected && sameWorkflowArtifact(inspected, artifact)
+      ? inspected
+      : undefined;
+  }
+
+  private async durableById(id: string) {
+    const [row] = await this.db
+      .select()
+      .from(durableJobArtifacts)
+      .where(eq(durableJobArtifacts.id, id))
+      .limit(1);
+    if (!row) return undefined;
+    return {
+      ...row,
+      artifactRef: row.artifactRef,
+      stageId: row.stageId ?? undefined,
+      expiresAt: row.expiresAt?.toISOString(),
+      metadata: row.metadata ?? undefined,
+      createdAt: row.createdAt.toISOString(),
+    };
+  }
+
+  private async refById(id: string) {
+    const durable = await this.durableById(id);
+    return durable ? durableWorkflowArtifactRef(durable) : undefined;
+  }
+}
+
+function forbidden() {
+  return new AgentWorkflowArtifactAccessError("ARTIFACT_FORBIDDEN", 403);
+}

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

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import type { DurableJobArtifact } from "@southwind-ai/jobs";
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+import { canonicalJson } from "./canonical-json.js";
+
+type CausalArtifactSource = AgentWorkflowArtifactRef["source"] & {
+  readonly sequence: number;
+  readonly digest?: string;
+};
+
+export interface WorkflowDurableArtifactShape {
+  readonly id: string;
+  readonly jobId: string;
+  readonly kind: string;
+  readonly artifactRef: { toString(): string };
+  readonly filename: string;
+  readonly contentType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly ownerId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export function derivedWorkflowArtifact(
+  source: AgentWorkflowArtifactRef,
+  policyKey: string,
+  artifactKind: string,
+): AgentWorkflowArtifactRef {
+  return {
+    artifactId: `workflow_artifact_${hash({
+      source: source.artifactId,
+      sourceCoordinate: source.source,
+      sha256: source.sha256,
+      policyKey,
+      artifactKind,
+    }).slice(0, 40)}`,
+    kind: artifactKind,
+    mediaType: source.mediaType,
+    byteSize: source.byteSize,
+    sha256: source.sha256,
+    retentionPolicyKey: policyKey,
+    source: structuredClone(source.source),
+  };
+}
+
+export function derivedWorkflowDurableArtifact(
+  origin: DurableJobArtifact,
+  artifact: AgentWorkflowArtifactRef,
+  actorId: string,
+  scopeDigest: string,
+) {
+  const source = causalSource(artifact);
+  return {
+    id: artifact.artifactId,
+    jobId: origin.jobId,
+    stageId: origin.stageId ?? null,
+    kind: `workflow:${hash(artifact).slice(0, 56)}`,
+    artifactRef: origin.artifactRef.toString(),
+    filename: origin.filename,
+    contentType: artifact.mediaType,
+    byteSize: artifact.byteSize,
+    sha256: artifact.sha256.replace(/^sha256:/, ""),
+    ownerId: actorId,
+    metadata: {
+      retentionPolicyKey: artifact.retentionPolicyKey,
+      sourceModuleKey: source.moduleKey,
+      sourceKind: source.kind,
+      sourceId: source.id,
+      sourceVersion: source.version,
+      sourceSequence: source.sequence,
+      ...(source.digest ? { sourceDigest: source.digest } : {}),
+      workflowArtifactKind: artifact.kind,
+      workflowOriginArtifactId: origin.id,
+      workflowScopeDigest: scopeDigest,
+    },
+    expiresAt: origin.expiresAt ? new Date(origin.expiresAt) : null,
+    createdAt: new Date(),
+  };
+}
+
+function causalSource(artifact: AgentWorkflowArtifactRef) {
+  return artifact.source as CausalArtifactSource;
+}
+
+export function durableWorkflowArtifactRef(
+  source: WorkflowDurableArtifactShape,
+): AgentWorkflowArtifactRef | undefined {
+  const metadata = source.metadata ?? {};
+  const text = [
+    metadata.retentionPolicyKey,
+    metadata.sourceModuleKey,
+    metadata.sourceKind,
+    metadata.sourceId,
+    metadata.sourceVersion,
+    metadata.workflowArtifactKind ?? source.kind,
+  ];
+  if (
+    text.some((value) => typeof value !== "string" || !value.trim()) ||
+    !Number.isSafeInteger(metadata.sourceSequence) ||
+    Number(metadata.sourceSequence) < 1
+  ) {
+    return undefined;
+  }
+  const sourceCoordinate: CausalArtifactSource = {
+    moduleKey: text[1] as string,
+    kind: text[2] as string,
+    id: text[3] as string,
+    version: text[4] as string,
+    sequence: metadata.sourceSequence as number,
+    ...(typeof metadata.sourceDigest === "string" && metadata.sourceDigest
+      ? { digest: metadata.sourceDigest }
+      : {}),
+  };
+  return {
+    artifactId: source.id,
+    kind: text[5] as string,
+    mediaType: source.contentType,
+    byteSize: source.byteSize,
+    sha256: source.sha256,
+    retentionPolicyKey: text[0] as string,
+    source: sourceCoordinate,
+  };
+}
+
+export function sameWorkflowArtifact(
+  source: WorkflowDurableArtifactShape,
+  candidate: AgentWorkflowArtifactRef,
+) {
+  const ref = durableWorkflowArtifactRef(source);
+  return Boolean(ref && canonicalJson(ref) === canonicalJson(candidate));
+}
+
+export function samePersistedWorkflowSeal(
+  left: WorkflowDurableArtifactShape,
+  right: ReturnType<typeof derivedWorkflowDurableArtifact>,
+) {
+  return (
+    left.id === right.id &&
+    left.jobId === right.jobId &&
+    left.kind === right.kind &&
+    left.artifactRef.toString() === right.artifactRef &&
+    left.ownerId === right.ownerId &&
+    left.contentType === right.contentType &&
+    left.byteSize === right.byteSize &&
+    left.sha256 === right.sha256 &&
+    canonicalJson(left.metadata) === canonicalJson(right.metadata)
+  );
+}
+
+function hash(value: unknown) {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}

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

@@ -0,0 +1,271 @@
+import {
+  agentWorkflowBudgetReservations,
+  agentWorkflowRuns,
+} from "@southwind-ai/database";
+import type { AgentWorkflowUsage } from "@southwind-ai/shared";
+import { and, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  assertSettlementWithinReservation,
+  WorkflowBudgetError,
+} from "./budget-validation.js";
+import type { WorkflowBudgetLedgerPort } from "./budget-ledger.js";
+import {
+  ledgerConflict,
+  lockRun,
+  readLocked,
+  sameSettlement,
+  toReservation,
+} from "./drizzle-budget-ledger-support.js";
+import { toRun } from "./drizzle-repository-mappers.js";
+import { recordAgentWorkflowUsage } from "./usage.js";
+
+export async function settleInTransaction(
+  tx: Transaction,
+  input: Parameters<WorkflowBudgetLedgerPort["settle"]>[0],
+) {
+  await lockRun(tx, input.parentRunId);
+  const [[runRow], [reservationRow]] = await Promise.all([
+    tx
+      .select()
+      .from(agentWorkflowRuns)
+      .where(eq(agentWorkflowRuns.runId, input.parentRunId))
+      .limit(1),
+    tx
+      .select()
+      .from(agentWorkflowBudgetReservations)
+      .where(
+        eq(agentWorkflowBudgetReservations.reservationId, input.reservationId),
+      )
+      .for("update")
+      .limit(1),
+  ]);
+  if (
+    !runRow ||
+    !reservationRow ||
+    reservationRow.parentRunId !== input.parentRunId
+  ) {
+    return ledgerConflict();
+  }
+  const current = toReservation(reservationRow);
+  if (reservationRow.status === "settled") {
+    if (!sameSettlement(current, input)) return ledgerConflict();
+    if (current.reasonCode === "BUDGET_EXCEEDED") {
+      return {
+        outcome: "budget-exceeded" as const,
+        safeCode: "BUDGET_EXCEEDED",
+      };
+    }
+    return usageKnown(current.consumed)
+      ? {
+          outcome: "replayed" as const,
+          reservation: current,
+          ledger: await readLocked(tx, input.parentRunId),
+        }
+      : {
+          outcome: "usage-unknown" as const,
+          safeCode: "USAGE_UNKNOWN_OR_EXCEEDED",
+        };
+  }
+  if (
+    reservationRow.status !== "active" ||
+    reservationRow.version !== input.expectedReservationVersion ||
+    reservationRow.authorizationSnapshotDigest !==
+      input.authorizationSnapshotDigest ||
+    reservationRow.runPolicyDigest !== input.runPolicyDigest ||
+    ["completed", "failed", "cancelled", "timed-out"].includes(runRow.status)
+  ) {
+    return ledgerConflict();
+  }
+  let cumulativeUsage: AgentWorkflowUsage;
+  let usageUnknown = false;
+  let budgetExceeded = false;
+  try {
+    assertSettlementWithinReservation(
+      input.consumed,
+      reservationRow.reservedJson,
+    );
+    cumulativeUsage = addUsage(runRow.usageJson, input.consumed);
+    recordAgentWorkflowUsage(
+      toRun(runRow),
+      cumulativeUsage,
+      runRow.version,
+      monotonicAt(input.settledAt, runRow.updatedAt),
+    );
+  } catch (error) {
+    if (!(error instanceof WorkflowBudgetError)) throw error;
+    usageUnknown = error.code === "BUDGET_USAGE_UNKNOWN";
+    budgetExceeded = error.code === "BUDGET_EXCEEDED";
+    if (!usageUnknown && !budgetExceeded) throw error;
+    cumulativeUsage = usageUnknown
+      ? addUsageAllowUnknown(runRow.usageJson, input.consumed)
+      : addUsage(runRow.usageJson, input.consumed);
+    recordAgentWorkflowUsage(
+      toRun(runRow),
+      cumulativeUsage,
+      runRow.version,
+      monotonicAt(input.settledAt, runRow.updatedAt),
+      usageUnknown,
+      usageUnknown || budgetExceeded,
+    );
+  }
+  const settledAt = Date.parse(input.settledAt);
+  const [updatedReservation] = await tx
+    .update(agentWorkflowBudgetReservations)
+    .set({
+      consumedJson: input.consumed,
+      status: "settled",
+      usageReceiptId: input.usageReceiptId,
+      reasonCode: budgetExceeded
+        ? "BUDGET_EXCEEDED"
+        : usageUnknown
+          ? "USAGE_UNKNOWN_OR_EXCEEDED"
+          : null,
+      settledAt,
+      updatedAt: settledAt,
+      version: reservationRow.version + 1,
+    })
+    .where(
+      and(
+        eq(
+          agentWorkflowBudgetReservations.reservationId,
+          reservationRow.reservationId,
+        ),
+        eq(agentWorkflowBudgetReservations.version, reservationRow.version),
+      ),
+    )
+    .returning();
+  if (!updatedReservation) return ledgerConflict();
+  const runUpdatedAt = Math.max(settledAt, runRow.updatedAt);
+  const [updatedRun] = await tx
+    .update(agentWorkflowRuns)
+    .set({
+      usageJson: cumulativeUsage,
+      updatedAt: runUpdatedAt,
+      version: runRow.version + 1,
+    })
+    .where(
+      and(
+        eq(agentWorkflowRuns.runId, runRow.runId),
+        eq(agentWorkflowRuns.version, runRow.version),
+      ),
+    )
+    .returning();
+  if (!updatedRun) throw new Error("BUDGET_LEDGER_RUN_CAS_FAILED");
+  if (usageUnknown) {
+    return {
+      outcome: "usage-unknown" as const,
+      safeCode: "USAGE_UNKNOWN_OR_EXCEEDED",
+    };
+  }
+  if (budgetExceeded) {
+    return {
+      outcome: "budget-exceeded" as const,
+      safeCode: "BUDGET_EXCEEDED",
+    };
+  }
+  return {
+    outcome: "settled" as const,
+    reservation: toReservation(updatedReservation),
+    ledger: await readLocked(tx, input.parentRunId),
+  };
+}
+
+function addUsage(
+  parent: AgentWorkflowUsage,
+  child: AgentWorkflowUsage,
+): AgentWorkflowUsage {
+  if (
+    parent.inputTokens.status !== "measured" ||
+    child.inputTokens.status !== "measured" ||
+    parent.outputTokens.status !== "measured" ||
+    child.outputTokens.status !== "measured" ||
+    parent.cost.status !== "measured" ||
+    child.cost.status !== "measured" ||
+    parent.cost.currency !== child.cost.currency
+  ) {
+    throw new Error("Budget settle Usage 未完整计量");
+  }
+  return {
+    durationMs: sum(parent.durationMs, child.durationMs),
+    modelAttempts: sum(parent.modelAttempts, child.modelAttempts),
+    toolCalls: sum(parent.toolCalls, child.toolCalls),
+    subagents: sum(parent.subagents, child.subagents),
+    inputTokens: measuredCount(
+      sum(parent.inputTokens.value, child.inputTokens.value),
+    ),
+    outputTokens: measuredCount(
+      sum(parent.outputTokens.value, child.outputTokens.value),
+    ),
+    cost: {
+      status: "measured",
+      amountMicros: sum(parent.cost.amountMicros, child.cost.amountMicros),
+      currency: parent.cost.currency,
+      source: "host-measured",
+    },
+  };
+}
+
+function addUsageAllowUnknown(
+  parent: AgentWorkflowUsage,
+  child: AgentWorkflowUsage,
+): AgentWorkflowUsage {
+  return {
+    durationMs: sum(parent.durationMs, child.durationMs),
+    modelAttempts: sum(parent.modelAttempts, child.modelAttempts),
+    toolCalls: sum(parent.toolCalls, child.toolCalls),
+    subagents: sum(parent.subagents, child.subagents),
+    inputTokens: addCount(parent.inputTokens, child.inputTokens),
+    outputTokens: addCount(parent.outputTokens, child.outputTokens),
+    cost:
+      parent.cost.status === "measured" && child.cost.status === "measured"
+        ? {
+            status: "measured",
+            amountMicros: sum(
+              parent.cost.amountMicros,
+              child.cost.amountMicros,
+            ),
+            currency: sameCurrency(parent.cost.currency, child.cost.currency),
+            source: "host-measured",
+          }
+        : { status: "unknown", reasonCode: "CHILD_USAGE_UNKNOWN" },
+  };
+}
+
+function addCount(
+  parent: AgentWorkflowUsage["inputTokens"],
+  child: AgentWorkflowUsage["inputTokens"],
+): AgentWorkflowUsage["inputTokens"] {
+  return parent.status === "measured" && child.status === "measured"
+    ? measuredCount(sum(parent.value, child.value))
+    : { status: "unknown", reasonCode: "CHILD_USAGE_UNKNOWN" };
+}
+
+function sameCurrency(parent: string, child: string) {
+  if (parent !== child) throw new Error("Budget Usage 币种不一致");
+  return parent;
+}
+
+function usageKnown(value: AgentWorkflowUsage) {
+  return (
+    value.inputTokens.status === "measured" &&
+    value.outputTokens.status === "measured" &&
+    value.cost.status === "measured"
+  );
+}
+
+function measuredCount(value: number): AgentWorkflowUsage["inputTokens"] {
+  return { status: "measured", value, source: "host-measured" };
+}
+
+function sum(left: number, right: number) {
+  const value = left + right;
+  if (!Number.isSafeInteger(value)) throw new Error("Budget Usage 汇总溢出");
+  return value;
+}
+
+function monotonicAt(left: string, right: number) {
+  return new Date(Math.max(Date.parse(left), right)).toISOString();
+}
+
+type Transaction = Parameters<Parameters<NodePgDatabase["transaction"]>[0]>[0];