create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/model-pricing-catalog.ts

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import type {
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type { InternalAiRuntimeRunDetail } from "../ai-runtime-report/contracts.js";
+import { canonicalJson } from "./canonical-json.js";
+
+interface ModelPrice {
+  readonly deploymentKey: string;
+  readonly model: string;
+  readonly inputMicrosPerMillion: number;
+  readonly outputMicrosPerMillion: number;
+}
+
+export class AgentWorkflowModelPricingCatalog {
+  readonly #prices: readonly ModelPrice[];
+  readonly digest: string;
+
+  private constructor(
+    readonly version: string,
+    readonly currency: "USD",
+    prices: readonly ModelPrice[],
+  ) {
+    this.#prices = prices;
+    this.digest = digest({ version, currency, prices });
+  }
+
+  static fromJson(value: string | undefined) {
+    if (!value?.trim()) return undefined;
+    const parsed: unknown = JSON.parse(value);
+    if (!record(parsed) || !Array.isArray(parsed.prices)) {
+      throw new Error("WORKFLOW_MODEL_PRICING_INVALID");
+    }
+    const version = text(parsed.version);
+    const currency = text(parsed.currency);
+    const prices = parsed.prices.map((item) => price(item));
+    const coordinates = prices.map(
+      ({ deploymentKey, model }) => `${deploymentKey}\u0000${model}`,
+    );
+    if (
+      !version ||
+      currency !== "USD" ||
+      !prices.length ||
+      new Set(coordinates).size !== coordinates.length
+    ) {
+      throw new Error("WORKFLOW_MODEL_PRICING_INVALID");
+    }
+    return new AgentWorkflowModelPricingCatalog(version, currency, prices);
+  }
+
+  admit(input: {
+    readonly deploymentKey: string | undefined;
+    readonly model: string | undefined;
+    readonly current: AgentWorkflowUsage;
+    readonly budget: AgentWorkflowBudget;
+  }) {
+    const deploymentPrices = this.#prices.filter(
+      ({ deploymentKey, model }) =>
+        deploymentKey === input.deploymentKey &&
+        (model === input.model || model === "*"),
+    );
+    const remainingInputTokens =
+      input.budget.maxInputTokens -
+      (input.current.inputTokens.status === "measured"
+        ? input.current.inputTokens.value
+        : input.budget.maxInputTokens);
+    const remainingOutputTokens =
+      input.budget.maxOutputTokens -
+      (input.current.outputTokens.status === "measured"
+        ? input.current.outputTokens.value
+        : input.budget.maxOutputTokens);
+    const remainingCostMicros =
+      input.budget.maxCostMicros -
+      (input.current.cost.status === "measured"
+        ? input.current.cost.amountMicros
+        : input.budget.maxCostMicros);
+    const remainingDurationSeconds =
+      input.budget.maxDurationSeconds -
+      Math.ceil(input.current.durationMs / 1_000);
+    const maxInputRate = Math.max(
+      ...deploymentPrices.map(
+        ({ inputMicrosPerMillion }) => inputMicrosPerMillion,
+      ),
+    );
+    const maxOutputRate = Math.max(
+      ...deploymentPrices.map(
+        ({ outputMicrosPerMillion }) => outputMicrosPerMillion,
+      ),
+    );
+    const reservedInputCost = Math.ceil(
+      (remainingInputTokens * maxInputRate) / 1_000_000,
+    );
+    const affordableOutputTokens =
+      maxOutputRate === 0
+        ? remainingOutputTokens
+        : Math.floor(
+            ((remainingCostMicros - reservedInputCost) * 1_000_000) /
+              maxOutputRate,
+          );
+    if (
+      !input.deploymentKey ||
+      !input.model ||
+      !deploymentPrices.length ||
+      input.current.inputTokens.status !== "measured" ||
+      input.current.outputTokens.status !== "measured" ||
+      input.current.cost.status !== "measured" ||
+      input.current.cost.currency !== this.currency ||
+      input.current.modelAttempts >= input.budget.maxModelAttempts ||
+      input.current.inputTokens.value >= input.budget.maxInputTokens ||
+      input.current.outputTokens.value >= input.budget.maxOutputTokens ||
+      input.current.cost.amountMicros >= input.budget.maxCostMicros ||
+      remainingDurationSeconds < 1 ||
+      remainingInputTokens < 1 ||
+      remainingOutputTokens < 1 ||
+      affordableOutputTokens < 1
+    ) {
+      throw new Error("MODEL_BUDGET_ADMISSION_DENIED");
+    }
+    return {
+      runtimeBudget: {
+        maxDurationSeconds: remainingDurationSeconds,
+        maxModelAttempts:
+          input.budget.maxModelAttempts - input.current.modelAttempts,
+        maxToolCalls: input.budget.maxToolCalls - input.current.toolCalls,
+        maxSubagents: input.budget.maxSubagents - input.current.subagents,
+        maxParallelism: input.budget.maxParallelism,
+        maxInputTokens: remainingInputTokens,
+        maxOutputTokens: Math.min(
+          remainingOutputTokens,
+          affordableOutputTokens,
+        ),
+        maxCostMicros: remainingCostMicros,
+      },
+      catalogDigest: this.digest,
+    };
+  }
+
+  measure(report: InternalAiRuntimeRunDetail) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let amountMicros = 0;
+    for (const attempt of report.attempts) {
+      if (
+        attempt.usageSource !== "provider-reported" ||
+        attempt.inputTokens === null ||
+        attempt.outputTokens === null
+      ) {
+        throw new Error("MODEL_USAGE_UNMEASURED");
+      }
+      const model = attempt.reportedModel ?? attempt.requestedModel;
+      const price =
+        this.#prices.find(
+          (item) =>
+            item.deploymentKey === attempt.deploymentKey &&
+            item.model === model,
+        ) ??
+        this.#prices.find(
+          (item) =>
+            item.deploymentKey === attempt.deploymentKey && item.model === "*",
+        );
+      if (!price) throw new Error("MODEL_PRICE_UNAVAILABLE");
+      inputTokens = sum(inputTokens, attempt.inputTokens);
+      outputTokens = sum(outputTokens, attempt.outputTokens);
+      amountMicros = sum(
+        amountMicros,
+        Math.ceil(
+          (attempt.inputTokens * price.inputMicrosPerMillion +
+            attempt.outputTokens * price.outputMicrosPerMillion) /
+            1_000_000,
+        ),
+      );
+    }
+    return { inputTokens, outputTokens, amountMicros, currency: this.currency };
+  }
+}
+
+function price(value: unknown): ModelPrice {
+  if (!record(value)) throw new Error("WORKFLOW_MODEL_PRICING_INVALID");
+  const result = {
+    deploymentKey: text(value.deploymentKey),
+    model: text(value.model),
+    inputMicrosPerMillion: integer(value.inputMicrosPerMillion),
+    outputMicrosPerMillion: integer(value.outputMicrosPerMillion),
+  };
+  if (!result.deploymentKey || !result.model) {
+    throw new Error("WORKFLOW_MODEL_PRICING_INVALID");
+  }
+  return result;
+}
+
+function integer(value: unknown) {
+  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+    throw new Error("WORKFLOW_MODEL_PRICING_INVALID");
+  }
+  return Number(value);
+}
+
+function text(value: unknown) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function sum(left: number, right: number) {
+  const value = left + right;
+  if (!Number.isSafeInteger(value)) throw new Error("MODEL_USAGE_OVERFLOW");
+  return value;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}

package/template/apps/server/src/agent-workflow/node-adapter-factory.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import type { AgentWorkflowNode } from "@southwind-ai/shared";
+import {
+  AgentWorkflowNodeAdapterRegistry,
+  type AgentWorkflowNodeAdapter,
+} from "./adapter-dispatch.js";
+import { canonicalJson } from "./canonical-json.js";
+import { workflowId } from "./service-support.js";
+
+export interface AgentWorkflowProductionAdapterSet {
+  readonly model: AgentWorkflowNodeAdapter;
+  readonly tool: AgentWorkflowNodeAdapter;
+  readonly subagent: AgentWorkflowNodeAdapter;
+  readonly condition: AgentWorkflowNodeAdapter;
+  readonly approval: AgentWorkflowNodeAdapter;
+  readonly job: AgentWorkflowNodeAdapter;
+  readonly wait: AgentWorkflowNodeAdapter;
+  readonly artifact: AgentWorkflowNodeAdapter;
+  readonly final: AgentWorkflowNodeAdapter;
+}
+
+export function createAgentWorkflowNodeAdapterRegistry(
+  adapters: AgentWorkflowProductionAdapterSet,
+) {
+  assertAdapterTypes(adapters);
+  return new AgentWorkflowNodeAdapterRegistry([
+    adapters.model,
+    adapters.tool,
+    adapters.subagent,
+    adapters.condition,
+    structuralAdapter("parallel"),
+    structuralAdapter("join"),
+    adapters.approval,
+    adapters.job,
+    adapters.wait,
+    adapters.artifact,
+    adapters.final,
+  ]);
+}
+
+function structuralAdapter(
+  nodeType: Extract<AgentWorkflowNode["type"], "parallel" | "join">,
+): AgentWorkflowNodeAdapter {
+  return {
+    nodeType,
+    async prepare({ nodeRun, inputArtifacts }) {
+      const recordedAt = nodeRun.updatedAt;
+      const resultDigest = `sha256:${createHash("sha256")
+        .update(
+          canonicalJson({
+            nodeRunId: nodeRun.nodeRunId,
+            inputArtifactIds: inputArtifacts.map(
+              ({ artifactId }) => artifactId,
+            ),
+          }),
+        )
+        .digest("hex")}`;
+      return {
+        outcome: "direct",
+        result: {
+          receiptId: workflowId(
+            "workflow_receipt",
+            nodeRun.nodeRunId,
+            resultDigest,
+          ),
+          nodeRunId: nodeRun.nodeRunId,
+          resultDigest,
+          artifactIds: inputArtifacts.map(({ artifactId }) => artifactId),
+          recordedAt,
+        },
+        outputArtifacts: inputArtifacts,
+      };
+    },
+  };
+}
+
+function assertAdapterTypes(adapters: AgentWorkflowProductionAdapterSet) {
+  for (const [type, adapter] of Object.entries(adapters)) {
+    if (adapter.nodeType !== type) {
+      throw new Error(`Workflow Adapter factory type 不匹配：${type}`);
+    }
+  }
+}

package/template/apps/server/src/agent-workflow/node-adapters.ts

@@ -0,0 +1,50 @@
+import type { RequestActor } from "../guards.js";
+
+export interface AgentWorkflowAdapterCoordinate {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly idempotencyKey: string;
+}
+
+export interface AgentWorkflowAdapterDispatch {
+  readonly adapterId: string;
+  readonly created: boolean;
+  readonly status: "waiting" | "completed" | "failed" | "cancelled";
+  readonly resultDigest?: string;
+  readonly safeErrorCode?: string;
+}
+
+export interface AgentWorkflowApprovalDispatchInput extends AgentWorkflowAdapterCoordinate {
+  readonly actor: RequestActor;
+  readonly title: string;
+  readonly candidateRoleCodes: readonly string[];
+  readonly dueAt: string;
+}
+
+export interface AgentWorkflowApprovalNodeAdapter {
+  dispatch(
+    input: AgentWorkflowApprovalDispatchInput,
+  ): Promise<AgentWorkflowAdapterDispatch>;
+  reconcile(input: {
+    readonly adapterId: string;
+    readonly actor: RequestActor;
+  }): Promise<AgentWorkflowAdapterDispatch | undefined>;
+}
+
+export interface AgentWorkflowJobDispatchInput extends AgentWorkflowAdapterCoordinate {
+  readonly actor: RequestActor;
+  readonly taskKey: string;
+  readonly timeoutSeconds: number;
+  readonly generation: number;
+}
+
+export interface AgentWorkflowDurableJobNodeAdapter {
+  dispatch(
+    input: AgentWorkflowJobDispatchInput,
+  ): Promise<AgentWorkflowAdapterDispatch>;
+  reconcile(input: {
+    readonly adapterId: string;
+    readonly actor: RequestActor;
+  }): Promise<AgentWorkflowAdapterDispatch | undefined>;
+}

package/template/apps/server/src/agent-workflow/node-execution-ports.ts

@@ -0,0 +1,185 @@
+import type {
+  ModuleAiJsonValue,
+  ModuleToolInput,
+} from "@southwind-ai/server-sdk";
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+  JsonValue,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { AgentWorkflowNodeAdapterContext } from "./adapter-dispatch.js";
+import type { WorkflowEffectCommandFence } from "./effect-command-fence.js";
+
+export interface AgentWorkflowNodeInputPort {
+  readJson(input: {
+    readonly context: AgentWorkflowNodeAdapterContext;
+    readonly schemaKey?: string;
+  }): Promise<ModuleAiJsonValue>;
+  readToolInput(input: {
+    readonly context: AgentWorkflowNodeAdapterContext;
+    readonly schemaKey?: string;
+  }): Promise<ModuleToolInput>;
+}
+
+export interface AgentWorkflowModelExecutionPort {
+  execute(input: {
+    readonly operationKey: string;
+    readonly promptKey: string;
+    readonly value: ModuleAiJsonValue;
+    readonly idempotencyKey: string;
+    readonly context: RequestGuardContext;
+    readonly sessionId?: string;
+    readonly deadlineAt: string;
+    readonly currentUsage: AgentWorkflowUsage;
+    readonly budget: AgentWorkflowBudget;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly runId: string;
+    readonly result: ModuleAiJsonValue;
+    readonly resultDigest: string;
+    readonly cumulativeUsage: AgentWorkflowUsage;
+    readonly executionEvidence: NonNullable<
+      import("@southwind-ai/shared").AgentWorkflowNodeResultReceipt["executionEvidence"]
+    >;
+  }>;
+  /** Reattaches through the canonical Run idempotency binding; no client Run ID is trusted. */
+  cancelByIdempotencyKey(input: {
+    readonly operationKey: string;
+    readonly idempotencyKey: string;
+    readonly context: RequestGuardContext;
+    readonly sessionId?: string;
+    readonly signal: AbortSignal;
+    readonly currentUsage: AgentWorkflowUsage;
+  }): Promise<{
+    readonly cancelled: boolean;
+    readonly cumulativeUsage?: AgentWorkflowUsage;
+  }>;
+}
+
+export class AgentWorkflowModelExecutionError extends Error {
+  constructor(
+    readonly safeCode: string,
+    readonly cumulativeUsage: AgentWorkflowUsage,
+  ) {
+    super(safeCode);
+    this.name = "AgentWorkflowModelExecutionError";
+  }
+}
+
+export interface AgentWorkflowDelegationExecutionPort {
+  reserve(input: {
+    readonly parentRunId: string;
+    readonly parentNodeId: string;
+    readonly parentNodeRunId: string;
+    readonly capabilityKey: string;
+    readonly operationKey: string;
+    readonly allowedToolKeys: readonly string[];
+    readonly requiredFeatureKeys: readonly string[];
+    readonly requiredPermissionKeys: readonly string[];
+    readonly allowedLicenseVersions?: readonly string[];
+    readonly budget: AgentWorkflowBudget;
+    readonly workspacePolicyKey: string;
+    readonly scopePolicyKey: string;
+    readonly parentActorId: string;
+    readonly parentScopeDigest: string;
+    readonly parentAuthorizationSnapshotDigest: string;
+    readonly parentToolPolicyDigest: string;
+    readonly parentWorkspacePolicyDigest: string;
+    readonly parentExecutionPolicyDigest: string;
+    readonly context: RequestGuardContext;
+    readonly idempotencyKey: string;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly delegationId: string;
+    readonly budgetReservationId: string;
+    readonly childSessionId: string;
+  }>;
+  start(input: {
+    readonly delegationId: string;
+    readonly childSessionId: string;
+    readonly operationKey: string;
+    readonly value: ModuleAiJsonValue;
+    readonly effectFence: WorkflowEffectCommandFence;
+    readonly idempotencyKey: string;
+    readonly deadlineAt: string;
+    readonly signal: AbortSignal;
+  }): Promise<{ readonly childAgentRunId: string }>;
+  reconcile(input: {
+    readonly delegationId: string;
+    readonly signal: AbortSignal;
+  }): Promise<
+    | { readonly status: "running" }
+    | {
+        readonly status: "completed";
+        readonly childAgentRunId: string;
+        readonly resultDigest: string;
+        readonly smallResult?: JsonValue;
+        readonly artifacts: readonly AgentWorkflowArtifactRef[];
+        readonly cumulativeUsage: AgentWorkflowUsage;
+        readonly executionEvidence: NonNullable<
+          import("@southwind-ai/shared").AgentWorkflowNodeResultReceipt["executionEvidence"]
+        >;
+      }
+    | {
+        readonly status: "failed" | "cancelled";
+        readonly safeCode: string;
+        readonly cumulativeUsage?: AgentWorkflowUsage;
+      }
+  >;
+  cancel(delegationId: string, signal: AbortSignal): Promise<boolean>;
+}
+
+export interface AgentWorkflowArtifactPort {
+  seal(input: {
+    readonly policyKey: string;
+    readonly artifactKind: string;
+    readonly sourceArtifacts: readonly AgentWorkflowArtifactRef[];
+    readonly actorId: string;
+    readonly scopeDigest: string;
+    readonly idempotencyKey: string;
+    readonly signal: AbortSignal;
+  }): Promise<readonly AgentWorkflowArtifactRef[]>;
+  reauthorize(input: {
+    readonly artifacts: readonly AgentWorkflowArtifactRef[];
+    readonly actorId: string;
+    readonly scopeDigest: string;
+    readonly signal: AbortSignal;
+  }): Promise<boolean>;
+  resolve(input: {
+    readonly artifactId: string;
+    readonly actorId: string;
+    readonly scopeDigest: string;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly artifact: AgentWorkflowArtifactRef;
+    readonly token: string;
+    readonly expiresAt: string;
+  }>;
+  open(input: {
+    readonly token: string;
+    readonly actorId: string;
+    readonly scopeDigest: string;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly artifact: AgentWorkflowArtifactRef;
+    readonly body: import("@southwind-ai/storage").ReadableBlob["body"];
+    readonly filename: string;
+    readonly contentType: string;
+  }>;
+}
+
+export interface AgentWorkflowSignalPort {
+  read(input: {
+    readonly signalKey: string;
+    readonly coordinate: string;
+    readonly actorId: string;
+    readonly scopeDigest: string;
+    readonly signal: AbortSignal;
+  }): Promise<
+    | { readonly status: "waiting" }
+    | { readonly status: "received"; readonly resultDigest: string }
+    | { readonly status: "revoked" | "expired"; readonly safeCode: string }
+  >;
+}

package/template/apps/server/src/agent-workflow/node-input-receipt-port.ts

@@ -0,0 +1,42 @@
+import type {
+  ModuleAiJsonValue,
+  ModuleToolInput,
+} from "@southwind-ai/server-sdk";
+import type { AgentWorkflowNodeInputPort } from "./node-execution-ports.js";
+
+/** Reads only immutable Run/Node receipts; never accepts request-body values. */
+export class ReceiptAgentWorkflowNodeInputPort implements AgentWorkflowNodeInputPort {
+  async readJson(
+    input: Parameters<AgentWorkflowNodeInputPort["readJson"]>[0],
+  ): Promise<ModuleAiJsonValue> {
+    const matching = input.context.inputReceipts.filter(
+      ({ outputSchemaKey }) =>
+        !input.schemaKey || outputSchemaKey === input.schemaKey,
+    );
+    if (matching.length > 1) {
+      throw new Error("WORKFLOW_NODE_INPUT_AMBIGUOUS");
+    }
+    if (matching.length === 1) {
+      const value = matching[0]!.smallResult;
+      if (value === undefined) {
+        throw new Error("WORKFLOW_NODE_INPUT_ARTIFACT_ONLY");
+      }
+      return structuredClone(value);
+    }
+    const receipt = input.context.run.inputReceipt;
+    if (input.schemaKey && receipt.schemaKey !== input.schemaKey) {
+      throw new Error("WORKFLOW_NODE_INPUT_SCHEMA_MISMATCH");
+    }
+    return structuredClone(receipt.value);
+  }
+
+  async readToolInput(
+    input: Parameters<AgentWorkflowNodeInputPort["readToolInput"]>[0],
+  ): Promise<ModuleToolInput> {
+    const value = await this.readJson(input);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("WORKFLOW_TOOL_INPUT_NOT_OBJECT");
+    }
+    return value as ModuleToolInput;
+  }
+}

package/template/apps/server/src/agent-workflow/node-result-receipt.ts

@@ -0,0 +1,50 @@
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowNodeResultReceipt,
+  AgentWorkflowNodeRun,
+} from "@southwind-ai/shared";
+import { assertCanonicalWorkflowSafeValue } from "./event-validation.js";
+
+export function assertAgentWorkflowNodeResultReceipt(
+  nodeRun: AgentWorkflowNodeRun,
+  receipt: AgentWorkflowNodeResultReceipt,
+  artifacts: readonly AgentWorkflowArtifactRef[],
+  at: string,
+) {
+  if (
+    !validIdentity(receipt.receiptId, 160) ||
+    receipt.nodeRunId !== nodeRun.nodeRunId ||
+    !Number.isFinite(Date.parse(receipt.recordedAt)) ||
+    Date.parse(receipt.recordedAt) < Date.parse(nodeRun.updatedAt) ||
+    Date.parse(receipt.recordedAt) > Date.parse(at) ||
+    !/^sha256:[a-f0-9]{64}$/.test(receipt.resultDigest)
+  ) {
+    throw new Error("Node Result Receipt 坐标无效");
+  }
+  if (
+    (nodeRun.nodeType === "condition" &&
+      !validIdentity(receipt.selectedBranch ?? "", 96)) ||
+    (nodeRun.nodeType !== "condition" && receipt.selectedBranch !== undefined)
+  ) {
+    throw new Error("Condition Node Result Receipt 缺少合法分支");
+  }
+  assertSmallResult(receipt.smallResult);
+  const artifactIds = artifacts.map(({ artifactId }) => artifactId);
+  if (
+    new Set(artifactIds).size !== artifactIds.length ||
+    JSON.stringify(artifactIds) !== JSON.stringify(receipt.artifactIds)
+  ) {
+    throw new Error("Node Result Receipt 的 ArtifactRef 不一致");
+  }
+}
+
+function assertSmallResult(
+  value: AgentWorkflowNodeResultReceipt["smallResult"],
+) {
+  if (value === undefined) return;
+  assertCanonicalWorkflowSafeValue(value, "smallResult", 16 * 1024);
+}
+
+function validIdentity(value: string, maximum: number) {
+  return value.trim() === value && value.length > 0 && value.length <= maximum;
+}