create-windy 0.6.12 → 0.6.14

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

@@ -0,0 +1,305 @@
+import type {
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type {
+  WorkflowBudgetLedgerSnapshot,
+  WorkflowBudgetReservationRecord,
+} from "./budget-ledger.js";
+
+export const WORKFLOW_BUDGET_KEYS = [
+  "maxDurationSeconds",
+  "maxModelAttempts",
+  "maxToolCalls",
+  "maxSubagents",
+  "maxParallelism",
+  "maxInputTokens",
+  "maxOutputTokens",
+  "maxCostMicros",
+] as const satisfies readonly (keyof AgentWorkflowBudget)[];
+
+export interface WorkflowAuthorizationFence {
+  readonly proofId: string;
+  readonly actorId: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly checkedAt: string;
+  readonly expiresAt: string;
+}
+
+export function assertWorkflowAuthorizationFence(
+  fence: WorkflowAuthorizationFence,
+  actorId: string,
+  now = new Date(),
+): void {
+  const checkedAt = Date.parse(fence.checkedAt);
+  const expiresAt = Date.parse(fence.expiresAt);
+  if (
+    !fence.proofId.trim() ||
+    fence.actorId !== actorId ||
+    !isDigest(fence.authorizationSnapshotDigest) ||
+    !isDigest(fence.runPolicyDigest) ||
+    !Number.isFinite(checkedAt) ||
+    checkedAt > now.getTime() ||
+    !Number.isFinite(expiresAt) ||
+    expiresAt <= now.getTime()
+  ) {
+    throw invalid("当前 Host Authorization Fence 无效或已过期");
+  }
+}
+
+export function calculateRemainingBudget(input: {
+  readonly budget: AgentWorkflowBudget;
+  readonly consumed: AgentWorkflowUsage;
+  readonly activeReservations: readonly Pick<
+    WorkflowBudgetReservationRecord,
+    "requested" | "status"
+  >[];
+}): AgentWorkflowBudget {
+  assertBudget(input.budget, "父级 Budget");
+  const used = usageAsBudget(input.consumed);
+  const reserved = zeroBudget();
+  for (const reservation of input.activeReservations) {
+    if (reservation.status !== "active") continue;
+    assertBudget(reservation.requested, "活动 Reservation");
+    addBudget(reserved, reservation.requested);
+  }
+  const remaining = zeroBudget();
+  for (const key of WORKFLOW_BUDGET_KEYS) {
+    const amount = input.budget[key] - used[key] - reserved[key];
+    if (amount < 0) throw invalid(`Budget Ledger 已超额：${key}`);
+    remaining[key] = amount;
+  }
+  return Object.freeze(remaining);
+}
+
+export function assertReservationFits(
+  requested: AgentWorkflowBudget,
+  remaining: AgentWorkflowBudget,
+): void {
+  assertBudget(requested, "请求 Reservation");
+  assertBudget(remaining, "剩余 Budget");
+  const exceeded = WORKFLOW_BUDGET_KEYS.find(
+    (key) => requested[key] > remaining[key],
+  );
+  if (exceeded) {
+    throw new WorkflowBudgetError(
+      "BUDGET_EXCEEDED",
+      `子 Agent Budget 超出父级剩余额度：${exceeded}`,
+    );
+  }
+}
+
+export function assertSettlementWithinReservation(
+  consumed: AgentWorkflowUsage,
+  reservation: AgentWorkflowBudget,
+): void {
+  assertBudget(reservation, "Reservation Budget");
+  const used = usageAsBudget(consumed);
+  const exceeded = WORKFLOW_BUDGET_KEYS.find(
+    (key) => key !== "maxParallelism" && used[key] > reservation[key],
+  );
+  if (exceeded) {
+    throw new WorkflowBudgetError(
+      "BUDGET_EXCEEDED",
+      `子 Agent 消耗超出已预留 Budget：${exceeded}`,
+    );
+  }
+}
+
+export function assertBudgetLedgerSnapshot(
+  snapshot: WorkflowBudgetLedgerSnapshot,
+): void {
+  if (
+    !snapshot.parentRunId.trim() ||
+    !Number.isSafeInteger(snapshot.version) ||
+    snapshot.version < 1
+  ) {
+    throw invalid("Budget Ledger 坐标无效");
+  }
+  const expected = calculateRemainingBudget(snapshot);
+  if (
+    WORKFLOW_BUDGET_KEYS.some(
+      (key) => expected[key] !== snapshot.remaining[key],
+    )
+  ) {
+    throw invalid("Budget Ledger 剩余额度与持久事实不一致");
+  }
+  const ids = new Set<string>();
+  const delegations = new Set<string>();
+  for (const reservation of snapshot.activeReservations) {
+    assertReservation(reservation, snapshot.parentRunId);
+    if (
+      reservation.status !== "active" ||
+      ids.has(reservation.reservationId) ||
+      delegations.has(reservation.delegationId)
+    ) {
+      throw invalid("活动 Budget Reservation 坐标重复");
+    }
+    ids.add(reservation.reservationId);
+    delegations.add(reservation.delegationId);
+  }
+}
+
+export function assertReservation(
+  reservation: WorkflowBudgetReservationRecord,
+  parentRunId = reservation.parentRunId,
+): void {
+  if (
+    !reservation.reservationId.trim() ||
+    reservation.parentRunId !== parentRunId ||
+    !reservation.delegationId.trim() ||
+    !reservation.idempotencyKey.trim() ||
+    !reservation.authorizationProofId.trim() ||
+    !isDigest(reservation.authorizationSnapshotDigest) ||
+    !isDigest(reservation.runPolicyDigest) ||
+    !Number.isSafeInteger(reservation.version) ||
+    reservation.version < 1 ||
+    !Number.isFinite(Date.parse(reservation.createdAt))
+  ) {
+    throw invalid("Budget Reservation 坐标无效");
+  }
+  assertBudget(reservation.requested, "Reservation Budget");
+  assertUsage(reservation.consumed, "Reservation Usage");
+  if (reservation.status === "settled") {
+    if (
+      !reservation.usageReceiptId?.trim() ||
+      !reservation.settledAt ||
+      !Number.isFinite(Date.parse(reservation.settledAt))
+    ) {
+      throw invalid("已结算 Reservation 缺少 Usage Receipt");
+    }
+    try {
+      assertSettlementWithinReservation(
+        reservation.consumed,
+        reservation.requested,
+      );
+    } catch (error) {
+      const expectedReason =
+        error instanceof WorkflowBudgetError &&
+        error.code === "BUDGET_USAGE_UNKNOWN"
+          ? "USAGE_UNKNOWN_OR_EXCEEDED"
+          : "BUDGET_EXCEEDED";
+      if (
+        !(error instanceof WorkflowBudgetError) ||
+        !["BUDGET_EXCEEDED", "BUDGET_USAGE_UNKNOWN"].includes(error.code) ||
+        reservation.reasonCode !== expectedReason
+      ) {
+        throw error;
+      }
+    }
+  }
+}
+
+function usageAsBudget(usage: AgentWorkflowUsage): AgentWorkflowBudget {
+  assertUsage(usage, "Workflow Usage");
+  if (
+    usage.inputTokens.status !== "measured" ||
+    usage.outputTokens.status !== "measured" ||
+    usage.cost.status !== "measured"
+  ) {
+    throw new WorkflowBudgetError(
+      "BUDGET_USAGE_UNKNOWN",
+      "Workflow Usage 未完整计量，拒绝继续分配 Budget",
+    );
+  }
+  return {
+    maxDurationSeconds: Math.ceil(usage.durationMs / 1_000),
+    maxModelAttempts: usage.modelAttempts,
+    maxToolCalls: usage.toolCalls,
+    maxSubagents: usage.subagents,
+    maxParallelism: 0,
+    maxInputTokens: usage.inputTokens.value,
+    maxOutputTokens: usage.outputTokens.value,
+    maxCostMicros: usage.cost.amountMicros,
+  };
+}
+
+function zeroBudget(): Record<keyof AgentWorkflowBudget, number> {
+  return Object.fromEntries(
+    WORKFLOW_BUDGET_KEYS.map((key) => [key, 0]),
+  ) as Record<keyof AgentWorkflowBudget, number>;
+}
+
+function addBudget(
+  target: Record<keyof AgentWorkflowBudget, number>,
+  value: AgentWorkflowBudget,
+) {
+  for (const key of WORKFLOW_BUDGET_KEYS) {
+    const next = target[key] + value[key];
+    if (!Number.isSafeInteger(next)) throw invalid("Budget 汇总溢出");
+    target[key] = next;
+  }
+}
+
+function assertBudget(value: AgentWorkflowBudget, label: string) {
+  for (const key of WORKFLOW_BUDGET_KEYS) {
+    if (!Number.isSafeInteger(value[key]) || value[key] < 0) {
+      throw invalid(`${label} 无效：${key}`);
+    }
+  }
+}
+
+function assertUsage(value: AgentWorkflowUsage, label: string) {
+  for (const [key, amount] of [
+    ["durationMs", value.durationMs],
+    ["modelAttempts", value.modelAttempts],
+    ["toolCalls", value.toolCalls],
+    ["subagents", value.subagents],
+  ] as const) {
+    if (!Number.isSafeInteger(amount) || amount < 0) {
+      throw invalid(`${label} 无效：${key}`);
+    }
+  }
+  assertMeasuredCount(value.inputTokens, `${label} inputTokens`);
+  assertMeasuredCount(value.outputTokens, `${label} outputTokens`);
+  if (value.cost.status === "measured") {
+    if (
+      !Number.isSafeInteger(value.cost.amountMicros) ||
+      value.cost.amountMicros < 0 ||
+      !/^[A-Z]{3}$/.test(value.cost.currency)
+    ) {
+      throw invalid(`${label} cost 无效`);
+    }
+  } else if (!safeReason(value.cost.reasonCode)) {
+    throw invalid(`${label} cost 未知原因无效`);
+  }
+}
+
+function assertMeasuredCount(
+  value: AgentWorkflowUsage["inputTokens"],
+  label: string,
+) {
+  if (value.status === "measured") {
+    if (!Number.isSafeInteger(value.value) || value.value < 0) {
+      throw invalid(`${label} 无效`);
+    }
+  } else if (!safeReason(value.reasonCode)) {
+    throw invalid(`${label} 未知原因无效`);
+  }
+}
+
+function safeReason(value: string) {
+  return /^[A-Z][A-Z0-9_]{0,79}$/.test(value);
+}
+
+function isDigest(value: string) {
+  return /^sha256:[a-f0-9]{64}$/.test(value);
+}
+
+export class WorkflowBudgetError extends Error {
+  constructor(
+    readonly code:
+      | "INVALID_BUDGET"
+      | "BUDGET_EXCEEDED"
+      | "BUDGET_USAGE_UNKNOWN",
+    message: string,
+  ) {
+    super(message);
+    this.name = "WorkflowBudgetError";
+  }
+}
+
+function invalid(message: string) {
+  return new WorkflowBudgetError("INVALID_BUDGET", message);
+}

package/template/apps/server/src/agent-workflow/canonical-agent-run-binding.ts

@@ -0,0 +1,17 @@
+import type { AgentRunAuthorizationStore } from "../agent/run-authorization.js";
+
+export async function findWorkflowAgentRunBinding(
+  authorizations: AgentRunAuthorizationStore,
+  input: {
+    readonly actorId: string;
+    readonly operationKey: string;
+    readonly idempotencyKey: string;
+    readonly sessionId?: string;
+  },
+) {
+  const runId = await authorizations.findRunByIdempotency(input);
+  if (!runId) return undefined;
+  const modelPin = await authorizations.modelPinForRun(runId);
+  if (!modelPin) throw new Error("MODEL_COORDINATE_UNAVAILABLE");
+  return { runId, modelPin };
+}

package/template/apps/server/src/agent-workflow/canonical-agent-run-evidence.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import type { AgentWorkflowUsage } from "@southwind-ai/shared";
+import type { InternalAiRuntimeRunDetail } from "../ai-runtime-report/contracts.js";
+import { canonicalJson } from "./canonical-json.js";
+import type { AgentWorkflowModelPricingCatalog } from "./model-pricing-catalog.js";
+
+export interface FrozenModelCoordinate {
+  readonly deploymentKey: string;
+  readonly model: string;
+}
+
+export function cumulativeModelUsage(
+  current: AgentWorkflowUsage,
+  report: InternalAiRuntimeRunDetail,
+  elapsedMs: number,
+  pricing: AgentWorkflowModelPricingCatalog | undefined,
+  pin: FrozenModelCoordinate,
+): AgentWorkflowUsage {
+  assertPinnedModelReport(report, pin);
+  if (!pricing) throw new Error("MODEL_PRICING_UNAVAILABLE");
+  const measured = pricing.measure(report);
+  return {
+    durationMs: current.durationMs + Math.max(0, Math.round(elapsedMs)),
+    modelAttempts: current.modelAttempts + report.attemptCount,
+    toolCalls: current.toolCalls,
+    subagents: current.subagents,
+    inputTokens: count(current.inputTokens, measured.inputTokens),
+    outputTokens: count(current.outputTokens, measured.outputTokens),
+    cost:
+      current.cost.status === "measured" &&
+      current.cost.currency === measured.currency
+        ? {
+            status: "measured",
+            amountMicros: current.cost.amountMicros + measured.amountMicros,
+            currency: measured.currency,
+            source: "catalog-estimated",
+          }
+        : { status: "unknown", reasonCode: "MODEL_COST_BASELINE_UNKNOWN" },
+  };
+}
+
+export function terminalModelUsage(
+  current: AgentWorkflowUsage,
+  report: InternalAiRuntimeRunDetail,
+  elapsedMs: number,
+  pricing: AgentWorkflowModelPricingCatalog | undefined,
+  pin: FrozenModelCoordinate,
+) {
+  try {
+    return cumulativeModelUsage(current, report, elapsedMs, pricing, pin);
+  } catch {
+    return report.attemptCount === 0
+      ? {
+          ...current,
+          durationMs: current.durationMs + Math.max(0, Math.round(elapsedMs)),
+        }
+      : unverifiedModelUsage(current, elapsedMs, report.attemptCount);
+  }
+}
+
+export function unverifiedModelUsage(
+  current: AgentWorkflowUsage,
+  elapsedMs: number,
+  attemptCount = 1,
+): AgentWorkflowUsage {
+  return {
+    durationMs: current.durationMs + Math.max(0, Math.round(elapsedMs)),
+    modelAttempts: current.modelAttempts + Math.max(1, attemptCount),
+    toolCalls: current.toolCalls,
+    subagents: current.subagents,
+    inputTokens: {
+      status: "unknown",
+      reasonCode: "MODEL_TERMINAL_USAGE_UNVERIFIED",
+    },
+    outputTokens: {
+      status: "unknown",
+      reasonCode: "MODEL_TERMINAL_USAGE_UNVERIFIED",
+    },
+    cost: {
+      status: "unknown",
+      reasonCode: "MODEL_TERMINAL_USAGE_UNVERIFIED",
+    },
+  };
+}
+
+export function modelExecutionEvidence(
+  runId: string,
+  report: InternalAiRuntimeRunDetail,
+  pricingCatalogDigest: string | undefined,
+  pin: FrozenModelCoordinate,
+) {
+  assertPinnedModelReport(report, pin);
+  return {
+    source: "agent-runtime-report" as const,
+    agentRunId: runId,
+    modelRouteKey: pin.deploymentKey,
+    model: pin.model,
+    modelDeploymentDigest: digest(report.modelDeployments),
+    modelConfigurationDigest: digest({
+      engineId: report.engineId,
+      releaseId: report.releaseId,
+      operationKey: report.operationKey,
+      pricingCatalogDigest,
+      pin,
+    }),
+  };
+}
+
+export function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+function assertPinnedModelReport(
+  report: InternalAiRuntimeRunDetail,
+  pin: FrozenModelCoordinate,
+) {
+  if (
+    report.modelDeployments.length !== 1 ||
+    report.modelDeployments[0]?.deploymentKey !== pin.deploymentKey ||
+    report.modelDeployments[0]?.model !== pin.model ||
+    report.attempts.some(
+      (attempt) =>
+        attempt.deploymentKey !== pin.deploymentKey ||
+        attempt.reportedModel !== pin.model,
+    )
+  ) {
+    throw new Error("MODEL_RUNTIME_PIN_MISMATCH");
+  }
+}
+
+function count(
+  current: AgentWorkflowUsage["inputTokens"],
+  value: number | null,
+): AgentWorkflowUsage["inputTokens"] {
+  return current.status === "measured" && value !== null
+    ? {
+        status: "measured",
+        value: current.value + value,
+        source: "provider-reported",
+      }
+    : { status: "unknown", reasonCode: "PROVIDER_TOKENS_NOT_REPORTED" };
+}