create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent-workflow/effect-command-fence.ts

@@ -0,0 +1,250 @@
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowSideEffectCommand,
+  JsonValue,
+} from "@southwind-ai/shared";
+import type { WorkflowAuthorizationFence } from "./budget-validation.js";
+import { assertCanonicalWorkflowSafeValue } from "./workflow-value-validation.js";
+import { canonicalJson } from "./canonical-json.js";
+
+export interface WorkflowEffectCommandFence {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: AgentWorkflowSideEffectCommand["effectKind"];
+  readonly adapter: AgentWorkflowSideEffectCommand["adapter"];
+  readonly generation: number;
+  readonly fenceToken: string;
+  readonly fenceTokenDigest: string;
+  readonly requestDigest: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly budgetReservationId?: string;
+  readonly delegationId?: string;
+  readonly claimedAt: string;
+}
+
+/** A takeover lease that is valid only for adapter reconciliation, never dispatch. */
+export interface WorkflowEffectReconciliationFence extends WorkflowEffectCommandFence {
+  readonly purpose: "reconciliation";
+}
+
+export interface WorkflowEffectCommandReceipt {
+  readonly receiptId: string;
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: AgentWorkflowSideEffectCommand["effectKind"];
+  readonly generation: number;
+  readonly fenceTokenDigest: string;
+  readonly requestDigest: string;
+  readonly externalReceiptId: string;
+  readonly resultDigest: string;
+  readonly smallResult?: JsonValue;
+  readonly artifactRefs?: readonly AgentWorkflowArtifactRef[];
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly committedAt: string;
+}
+
+export type WorkflowEffectCommandClaimResult =
+  | { readonly outcome: "claimed"; readonly fence: WorkflowEffectCommandFence }
+  | {
+      readonly outcome: "replayed";
+      readonly receipt: WorkflowEffectCommandReceipt;
+    }
+  | {
+      readonly outcome: "conflict" | "authorization-stale";
+      readonly safeCode: string;
+    };
+
+export type WorkflowEffectReconciliationClaimResult =
+  | {
+      readonly outcome: "claimed";
+      readonly fence: WorkflowEffectReconciliationFence;
+    }
+  | {
+      readonly outcome: "replayed";
+      readonly receipt: WorkflowEffectCommandReceipt;
+    }
+  | { readonly outcome: "conflict"; readonly safeCode: string };
+
+/**
+ * The adapter must claim before an external write, reject stale generations,
+ * and durably commit the receipt with the command state. Fence tokens are
+ * internal capabilities and must never be copied into canonical Events.
+ */
+export interface WorkflowEffectCommandFencePort {
+  claim(input: {
+    readonly command: AgentWorkflowSideEffectCommand;
+    readonly expectedCommandVersion: number;
+    readonly authorizationFence: WorkflowAuthorizationFence;
+    readonly budgetReservationId?: string;
+    readonly deadlineAt: string;
+  }): Promise<WorkflowEffectCommandClaimResult>;
+  claimReconciliation(input: {
+    readonly command: AgentWorkflowSideEffectCommand;
+    readonly expectedCommandVersion: number;
+  }): Promise<WorkflowEffectReconciliationClaimResult>;
+  commit(input: {
+    readonly fence: WorkflowEffectCommandFence;
+    readonly receipt: WorkflowEffectCommandReceipt;
+  }): Promise<
+    | {
+        readonly outcome: "committed" | "replayed";
+        readonly receipt: WorkflowEffectCommandReceipt;
+      }
+    | { readonly outcome: "conflict"; readonly safeCode: string }
+  >;
+  reconcile(
+    commandId: string,
+  ): Promise<WorkflowEffectCommandReceipt | undefined>;
+}
+
+export function isEffectReconciliationCandidate(
+  command: AgentWorkflowSideEffectCommand,
+) {
+  if (
+    !["prepared", "dispatched", "cancellation-requested"].includes(
+      command.status,
+    )
+  ) {
+    return false;
+  }
+  if (command.generation === 0) {
+    return (
+      command.status !== "dispatched" &&
+      command.fenceTokenDigest === undefined &&
+      command.authorizationSnapshotDigest === undefined &&
+      command.runPolicyDigest === undefined &&
+      command.claimedAt === undefined
+    );
+  }
+  return (
+    command.status !== "prepared" &&
+    command.generation > 0 &&
+    Boolean(
+      command.fenceTokenDigest &&
+      command.authorizationSnapshotDigest &&
+      command.runPolicyDigest &&
+      command.claimedAt,
+    )
+  );
+}
+
+export function assertEffectCommandReceipt(input: {
+  readonly fence: WorkflowEffectCommandFence;
+  readonly receipt: WorkflowEffectCommandReceipt;
+}): void {
+  const { fence, receipt } = input;
+  if (
+    !coordinate(fence.commandId) ||
+    !coordinate(fence.runId) ||
+    !coordinate(fence.nodeRunId) ||
+    !coordinate(fence.adapter.coordinate) ||
+    !coordinate(fence.fenceToken) ||
+    !digest(fence.fenceTokenDigest) ||
+    !Number.isSafeInteger(fence.generation) ||
+    fence.generation < 1 ||
+    !digest(fence.requestDigest) ||
+    !digest(fence.authorizationSnapshotDigest) ||
+    !digest(fence.runPolicyDigest) ||
+    !Number.isFinite(Date.parse(fence.claimedAt)) ||
+    (fence.effectKind === "subagent" &&
+      (!fence.budgetReservationId || !fence.delegationId)) ||
+    (fence.effectKind !== "subagent" &&
+      (fence.budgetReservationId !== undefined ||
+        fence.delegationId !== undefined)) ||
+    !coordinate(receipt.receiptId) ||
+    receipt.commandId !== fence.commandId ||
+    receipt.runId !== fence.runId ||
+    receipt.nodeRunId !== fence.nodeRunId ||
+    receipt.effectKind !== fence.effectKind ||
+    receipt.generation !== fence.generation ||
+    receipt.fenceTokenDigest !== fence.fenceTokenDigest ||
+    receipt.requestDigest !== fence.requestDigest ||
+    receipt.authorizationSnapshotDigest !== fence.authorizationSnapshotDigest ||
+    receipt.runPolicyDigest !== fence.runPolicyDigest ||
+    !coordinate(receipt.externalReceiptId) ||
+    !digest(receipt.resultDigest) ||
+    !Number.isFinite(Date.parse(receipt.committedAt)) ||
+    Date.parse(receipt.committedAt) < Date.parse(fence.claimedAt)
+  ) {
+    throw new WorkflowEffectCommandFenceError(
+      "Effect Command Receipt 与 Fence 不一致",
+    );
+  }
+  if (receipt.smallResult !== undefined) {
+    assertCanonicalWorkflowSafeValue(
+      receipt.smallResult,
+      "effectReceipt.smallResult",
+      8_192,
+    );
+    if (canonicalDigest(receipt.smallResult) !== receipt.resultDigest) {
+      throw new WorkflowEffectCommandFenceError(
+        "Effect Receipt smallResult 与 resultDigest 不一致",
+      );
+    }
+  }
+  if (receipt.artifactRefs !== undefined) {
+    assertCanonicalWorkflowSafeValue(
+      receipt.artifactRefs,
+      "effectReceipt.artifactRefs",
+      64 * 1024,
+    );
+    assertArtifactRefs(receipt.artifactRefs);
+  }
+}
+
+export class WorkflowEffectCommandFenceError extends Error {
+  readonly code = "INVALID_EFFECT_COMMAND_FENCE";
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowEffectCommandFenceError";
+  }
+}
+
+function coordinate(value: string) {
+  return value.trim().length > 0 && value.length <= 256;
+}
+
+function digest(value: string) {
+  return /^sha256:[a-f0-9]{64}$/.test(value);
+}
+
+function canonicalDigest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+function assertArtifactRefs(values: readonly AgentWorkflowArtifactRef[]) {
+  if (values.length > 32)
+    throw new WorkflowEffectCommandFenceError(
+      "Effect Receipt ArtifactRef 超限",
+    );
+  const ids = new Set<string>();
+  for (const value of values) {
+    if (
+      !coordinate(value.artifactId) ||
+      !coordinate(value.kind) ||
+      !coordinate(value.mediaType) ||
+      !coordinate(value.retentionPolicyKey) ||
+      !Number.isSafeInteger(value.byteSize) ||
+      value.byteSize < 0 ||
+      !/^(?:sha256:)?[a-f0-9]{64}$/.test(value.sha256) ||
+      !coordinate(value.source.moduleKey) ||
+      !coordinate(value.source.kind) ||
+      !coordinate(value.source.id) ||
+      !coordinate(value.source.version) ||
+      !Number.isSafeInteger(value.source.sequence) ||
+      value.source.sequence < 1 ||
+      (value.source.digest !== undefined && !digest(value.source.digest)) ||
+      ids.has(value.artifactId)
+    ) {
+      throw new WorkflowEffectCommandFenceError(
+        "Effect Receipt ArtifactRef 无效",
+      );
+    }
+    ids.add(value.artifactId);
+  }
+}
+import { createHash } from "node:crypto";

package/template/apps/server/src/agent-workflow/evaluation-evidence-coordinates.ts

@@ -0,0 +1,225 @@
+import {
+  agentWorkflowDelegations,
+  agentWorkflowNodeRuns,
+  agentWorkflowReleases,
+  agentWorkflowRuns,
+} from "@southwind-ai/database";
+import type {
+  AgentWorkflowEvaluationArmKind,
+  AgentWorkflowEvaluationArmCoordinates,
+  AgentWorkflowEvaluationConditions,
+  AgentWorkflowEvaluationReleaseIdentity,
+} from "@southwind-ai/shared";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import { canonicalEvaluationDigest } from "./evaluation-repository.js";
+import { normalizeArmCoordinates } from "./evaluation-validation.js";
+import {
+  definitionToolKeys,
+  governedDefinitionToolSchemaVersion,
+} from "./governed-tool-schema.js";
+import {
+  evaluationToolRegistryFacts,
+  type AgentWorkflowEvaluationToolRegistration,
+} from "./evaluation-tool-registration.js";
+
+type ReleaseRow = typeof agentWorkflowReleases.$inferSelect;
+type RunRow = typeof agentWorkflowRuns.$inferSelect;
+type NodeRunRow = typeof agentWorkflowNodeRuns.$inferSelect;
+type DelegationRow = typeof agentWorkflowDelegations.$inferSelect;
+
+export function observedEvaluationCoordinates(
+  release: ReleaseRow,
+  run: RunRow,
+  nodes: readonly NodeRunRow[],
+  tools: GovernedToolRegistry,
+  evaluatorTools: AgentWorkflowEvaluationToolRegistration | undefined,
+): AgentWorkflowEvaluationArmCoordinates {
+  return normalizeArmCoordinates({
+    releaseId: release.releaseId,
+    release: releaseIdentity(release),
+    conditions: observedConditions(release, run, nodes, tools, evaluatorTools),
+    availability: { status: "run", runId: run.runId },
+  });
+}
+
+export function unavailableEvaluationCoordinates(
+  release: ReleaseRow,
+  scopeDigest: string,
+  reasonCode: string,
+  tools: GovernedToolRegistry,
+  evaluatorTools: AgentWorkflowEvaluationToolRegistration | undefined,
+): AgentWorkflowEvaluationArmCoordinates {
+  return normalizeArmCoordinates({
+    releaseId: release.releaseId,
+    release: releaseIdentity(release),
+    conditions: {
+      inputDigest: null,
+      modelRouteKey: null,
+      model: null,
+      modelDeploymentDigest: null,
+      modelConfigurationDigest: null,
+      toolSchemaDigest: governedToolSchemaDigest(
+        release,
+        tools,
+        evaluatorTools,
+      ),
+      toolRuntimePolicyDigest: null,
+      allowedToolKeys: releaseToolKeys(release),
+      budget: release.releaseJson.definition.budget,
+      scopeDigest,
+      authorizationSnapshotDigest: null,
+      workspacePolicyDigest: null,
+      executionPolicyDigest: null,
+      runtimeVersion: release.releaseJson.coordinates.runtimeVersion,
+    },
+    availability: { status: "unavailable", reasonCode },
+  });
+}
+
+export function lacksProviderEvidence(
+  release: ReleaseRow,
+  nodes: readonly NodeRunRow[],
+) {
+  const required = new Set(
+    release.releaseJson.definition.nodes
+      .filter(({ type }) => type === "model" || type === "subagent")
+      .map(({ id }) => id),
+  );
+  return [...required].some((nodeId) => {
+    const observed = nodes
+      .filter((node) => node.nodeId === nodeId)
+      .sort((left, right) => right.attempt - left.attempt)[0];
+    return (
+      !observed ||
+      observed.status !== "completed" ||
+      !observed.resultReceiptJson?.executionEvidence
+    );
+  });
+}
+
+export function lacksArmSemantics(
+  release: ReleaseRow,
+  nodes: readonly NodeRunRow[],
+  delegations: readonly DelegationRow[],
+  runId: string,
+  arm: AgentWorkflowEvaluationArmKind,
+) {
+  const modelNodeIds = release.releaseJson.definition.nodes
+    .filter(({ type }) => type === "model")
+    .map(({ id }) => id);
+  const subagentNodeIds = release.releaseJson.definition.nodes
+    .filter(({ type }) => type === "subagent")
+    .map(({ id }) => id);
+  if (arm === "single-agent") {
+    return (
+      modelNodeIds.length === 0 ||
+      subagentNodeIds.length > 0 ||
+      delegations.some(({ parentRunId }) => parentRunId === runId)
+    );
+  }
+  const completedSubagents = nodes.filter(
+    (node) =>
+      subagentNodeIds.includes(node.nodeId) &&
+      node.status === "completed" &&
+      node.resultReceiptJson !== null,
+  );
+  return (
+    completedSubagents.length === 0 ||
+    completedSubagents.some(
+      ({ nodeRunId }) =>
+        !delegations.some(
+          (delegation) =>
+            delegation.parentRunId === runId &&
+            delegation.parentNodeRunId === nodeRunId &&
+            delegation.status === "completed" &&
+            delegation.childAgentRunId !== null,
+        ),
+    )
+  );
+}
+
+export function lacksGovernedToolFacts(
+  release: ReleaseRow,
+  tools: GovernedToolRegistry,
+) {
+  return (
+    release.releaseJson.coordinates.toolSchemaVersion !==
+      governedDefinitionToolSchemaVersion(
+        release.releaseJson.definition,
+        tools,
+      ) || releaseToolKeys(release).some((key) => !tools.definition(key))
+  );
+}
+
+function observedConditions(
+  release: ReleaseRow,
+  run: RunRow,
+  nodes: readonly NodeRunRow[],
+  tools: GovernedToolRegistry,
+  evaluatorTools: AgentWorkflowEvaluationToolRegistration | undefined,
+): AgentWorkflowEvaluationConditions {
+  const evidence = nodes.flatMap(({ resultReceiptJson }) =>
+    resultReceiptJson?.executionEvidence
+      ? [resultReceiptJson.executionEvidence]
+      : [],
+  );
+  return {
+    inputDigest: run.inputDigest,
+    modelRouteKey: unique(evidence.map(({ modelRouteKey }) => modelRouteKey)),
+    model: unique(evidence.map(({ model }) => model)),
+    modelDeploymentDigest: coordinateDigest(
+      evidence.map(({ modelDeploymentDigest }) => modelDeploymentDigest),
+    ),
+    modelConfigurationDigest: coordinateDigest(
+      evidence.map(({ modelConfigurationDigest }) => modelConfigurationDigest),
+    ),
+    toolSchemaDigest: governedToolSchemaDigest(release, tools, evaluatorTools),
+    toolRuntimePolicyDigest: run.toolPolicyDigest,
+    allowedToolKeys: releaseToolKeys(release),
+    budget: run.budgetJson,
+    scopeDigest: run.scopeDigest,
+    authorizationSnapshotDigest: run.authorizationSnapshotDigest,
+    workspacePolicyDigest: run.workspacePolicyDigest,
+    executionPolicyDigest: run.executionPolicyDigest,
+    runtimeVersion: release.releaseJson.coordinates.runtimeVersion,
+  };
+}
+
+function governedToolSchemaDigest(
+  release: ReleaseRow,
+  tools: GovernedToolRegistry,
+  evaluatorTools: AgentWorkflowEvaluationToolRegistration | undefined,
+) {
+  return coordinateDigest({
+    frozenVersion: release.releaseJson.coordinates.toolSchemaVersion,
+    currentRegistryVersion: governedDefinitionToolSchemaVersion(
+      release.releaseJson.definition,
+      tools,
+    ),
+    evaluationTools: evaluationToolRegistryFacts(evaluatorTools, tools),
+  });
+}
+
+function releaseIdentity(
+  release: ReleaseRow,
+): AgentWorkflowEvaluationReleaseIdentity {
+  const coordinates = release.releaseJson.coordinates;
+  return {
+    releaseDigest: release.releaseDigest,
+    routeVersion: coordinates.routeVersion,
+    promptVersion: coordinates.promptVersion,
+    manifestDigest: coordinates.manifestDigest,
+  };
+}
+
+function releaseToolKeys(release: ReleaseRow) {
+  return definitionToolKeys(release.releaseJson.definition);
+}
+
+function unique(values: readonly string[]) {
+  return [...new Set(values)].sort().join(",") || null;
+}
+
+function coordinateDigest(value: unknown) {
+  return `sha256:${canonicalEvaluationDigest(value)}`;
+}