create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,197 @@
+import {
+  budgetFitsWithin,
+  type AgentWorkflowBudget,
+  type AgentWorkflowNode,
+} from "@southwind-ai/shared";
+import {
+  assertAgentWorkflowBudget,
+  assertAgentWorkflowFailurePolicy,
+} from "./definition-budget-validation.js";
+import type { AgentWorkflowDefinitionErrorCode } from "./definition-validation.js";
+
+type Fail = (code: AgentWorkflowDefinitionErrorCode, message: string) => never;
+
+export function assertAgentWorkflowNode(
+  node: AgentWorkflowNode,
+  budget: AgentWorkflowBudget,
+  fail: Fail,
+) {
+  if (!validText(node.id, 96) || !validText(node.label, 160)) {
+    fail("NODE_INVALID", "Workflow Node identity 或 label 无效");
+  }
+  assertAgentWorkflowFailurePolicy(node, (message) =>
+    fail("NODE_INVALID", message),
+  );
+  if (
+    node.timeoutSeconds !== undefined &&
+    (!Number.isSafeInteger(node.timeoutSeconds) ||
+      node.timeoutSeconds < 1 ||
+      node.timeoutSeconds > budget.maxDurationSeconds)
+  ) {
+    fail("NODE_INVALID", `Workflow Node 重试或超时无效：${node.id}`);
+  }
+  if (
+    node.failurePolicy.mode === "retry" &&
+    (!Number.isSafeInteger(node.failurePolicy.maxAttempts) ||
+      node.failurePolicy.maxAttempts < 2 ||
+      !Number.isSafeInteger(node.failurePolicy.backoffSeconds) ||
+      node.failurePolicy.backoffSeconds < 0)
+  ) {
+    fail("NODE_INVALID", `Workflow Node retry policy 无效：${node.id}`);
+  }
+  if (
+    node.type === "condition" &&
+    node.failurePolicy.mode === "retry" &&
+    node.failurePolicy.exhausted === "skip"
+  ) {
+    fail(
+      "NODE_INVALID",
+      `Condition Node retry 耗尽必须 fail-run 或使用显式 fallback：${node.id}`,
+    );
+  }
+  for (const schemaKey of [node.inputSchemaKey, node.outputSchemaKey]) {
+    if (schemaKey !== undefined && !validText(schemaKey, 160)) {
+      fail("NODE_INVALID", `Workflow Node Schema Key 无效：${node.id}`);
+    }
+  }
+  assertNodeType(node, budget, fail);
+}
+
+function assertNodeType(
+  node: AgentWorkflowNode,
+  budget: AgentWorkflowBudget,
+  fail: Fail,
+) {
+  switch (node.type) {
+    case "model":
+      requireTypedIo(node, true, fail);
+      assertTexts(node, [node.operationKey, node.promptKey], fail);
+      if (budget.maxModelAttempts < 1)
+        budgetFailure(node.id, "Model attempt", fail);
+      return;
+    case "tool":
+      requireTypedIo(node, true, fail);
+      assertTexts(node, [node.toolKey], fail);
+      if (budget.maxToolCalls < 1) budgetFailure(node.id, "Tool call", fail);
+      return;
+    case "subagent":
+      requireTypedIo(node, true, fail);
+      assertTexts(
+        node,
+        [
+          node.capabilityKey,
+          node.operationKey,
+          node.workspacePolicyKey,
+          node.scopePolicyKey,
+        ],
+        fail,
+      );
+      assertUniqueTexts(node, "allowedToolKeys", node.allowedToolKeys, fail);
+      assertUniqueTexts(
+        node,
+        "requiredFeatureKeys",
+        node.requiredFeatureKeys,
+        fail,
+      );
+      assertUniqueTexts(
+        node,
+        "requiredPermissionKeys",
+        node.requiredPermissionKeys,
+        fail,
+      );
+      if (node.allowedLicenseVersions) {
+        assertUniqueTexts(
+          node,
+          "allowedLicenseVersions",
+          node.allowedLicenseVersions,
+          fail,
+        );
+      }
+      assertAgentWorkflowBudget(node.budget, `Subagent ${node.id}`, (message) =>
+        fail("BUDGET_INVALID", message),
+      );
+      if (
+        !budgetFitsWithin(node.budget, budget) ||
+        budget.maxSubagents < 1 ||
+        node.budget.maxSubagents < 1
+      ) {
+        budgetFailure(node.id, "Subagent", fail);
+      }
+      return;
+    case "condition":
+      requireTypedIo(node, false, fail);
+      assertTexts(node, [node.conditionKey], fail);
+      assertUniqueTexts(node, "branches", node.branches, fail, 2);
+      return;
+    case "parallel":
+      if (
+        !Number.isSafeInteger(node.maxConcurrency) ||
+        node.maxConcurrency < 2 ||
+        node.maxConcurrency > budget.maxParallelism
+      ) {
+        budgetFailure(node.id, "Parallel concurrency", fail);
+      }
+      return;
+    case "join":
+      return;
+    case "approval":
+      assertTexts(node, [node.title], fail);
+      assertUniqueTexts(node, "candidateRoles", node.candidateRoles, fail, 1);
+      return;
+    case "job":
+      assertTexts(node, [node.taskKey], fail);
+      return;
+    case "wait":
+      assertTexts(node, [node.signalKey], fail);
+      return;
+    case "artifact":
+      assertTexts(node, [node.policyKey, node.artifactKind], fail);
+      return;
+    case "final":
+      assertTexts(node, [node.outputSchemaKey], fail);
+  }
+}
+
+function requireTypedIo(
+  node: AgentWorkflowNode,
+  outputRequired: boolean,
+  fail: Fail,
+) {
+  if (!node.inputSchemaKey || (outputRequired && !node.outputSchemaKey)) {
+    fail("NODE_INVALID", `Workflow Node 缺少 typed I/O Schema：${node.id}`);
+  }
+}
+
+function assertTexts(
+  node: AgentWorkflowNode,
+  values: readonly string[],
+  fail: Fail,
+) {
+  if (values.some((value) => !validText(value, 160))) {
+    fail("NODE_INVALID", `Workflow Node 引用 Key 无效：${node.id}`);
+  }
+}
+
+function assertUniqueTexts(
+  node: AgentWorkflowNode,
+  label: string,
+  values: readonly string[],
+  fail: Fail,
+  minimum = 0,
+) {
+  if (
+    values.length < minimum ||
+    values.some((value) => !validText(value, 160)) ||
+    new Set(values).size !== values.length
+  ) {
+    fail("NODE_INVALID", `Workflow Node ${label} 无效：${node.id}`);
+  }
+}
+
+function validText(value: string, maximum: number) {
+  return value.trim() === value && value.length > 0 && value.length <= maximum;
+}
+
+function budgetFailure(nodeId: string, label: string, fail: Fail): never {
+  fail("BUDGET_INVALID", `${label} 超出 Workflow Budget：${nodeId}`);
+}

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

@@ -0,0 +1,198 @@
+import {
+  AGENT_WORKFLOW_SCHEMA_VERSION,
+  type AgentWorkflowDefinition,
+  type AgentWorkflowNode,
+} from "@southwind-ai/shared";
+import { assertAgentWorkflowBudget } from "./definition-budget-validation.js";
+import { assertAgentWorkflowNode } from "./definition-node-validation.js";
+
+export type AgentWorkflowDefinitionErrorCode =
+  | "DEFINITION_INVALID"
+  | "BUDGET_INVALID"
+  | "NODE_INVALID"
+  | "EDGE_INVALID"
+  | "GRAPH_INVALID";
+
+export class AgentWorkflowDefinitionError extends Error {
+  constructor(
+    readonly code: AgentWorkflowDefinitionErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AgentWorkflowDefinitionError";
+  }
+}
+
+export function validateAgentWorkflowDefinition(
+  definition: AgentWorkflowDefinition,
+): AgentWorkflowDefinition {
+  if (
+    definition.schemaVersion !== AGENT_WORKFLOW_SCHEMA_VERSION ||
+    !validText(definition.workflowKey, 160) ||
+    !validText(definition.version, 80) ||
+    !validText(definition.label, 160) ||
+    (definition.description !== undefined &&
+      !validText(definition.description, 2_000))
+  ) {
+    fail("DEFINITION_INVALID", "Workflow Definition 基础字段无效");
+  }
+  assertAgentWorkflowBudget(definition.budget, "Workflow", (message) =>
+    fail("BUDGET_INVALID", message),
+  );
+  if (!definition.nodes.length || definition.nodes.length > 500) {
+    fail("GRAPH_INVALID", "Workflow 节点数量必须为 1 至 500");
+  }
+  if (definition.edges.length > 5_000) {
+    fail("GRAPH_INVALID", "Workflow 边数量超过 5000");
+  }
+
+  const nodes = new Map<string, AgentWorkflowNode>();
+  for (const node of definition.nodes) {
+    if (nodes.has(node.id))
+      fail("NODE_INVALID", `Workflow 节点重复：${node.id}`);
+    assertAgentWorkflowNode(node, definition.budget, fail);
+    nodes.set(node.id, node);
+  }
+  if (!nodes.has(definition.entryNodeId)) {
+    fail("GRAPH_INVALID", "Workflow entryNodeId 未引用已知节点");
+  }
+  const finals = definition.nodes.filter(({ type }) => type === "final");
+  if (finals.length !== 1) {
+    fail("GRAPH_INVALID", "Workflow 必须且只能包含一个 final 节点");
+  }
+
+  const outgoing = new Map<string, typeof definition.edges>();
+  const incoming = new Map<string, typeof definition.edges>();
+  const edgeKeys = new Set<string>();
+  for (const edge of definition.edges) {
+    const from = nodes.get(edge.from);
+    if (!from || !nodes.has(edge.to)) {
+      fail(
+        "EDGE_INVALID",
+        `Workflow Edge 引用了未知节点：${edge.from} -> ${edge.to}`,
+      );
+    }
+    if (edge.from === edge.to) fail("GRAPH_INVALID", "Workflow 节点不能自循环");
+    if (from.type === "condition") {
+      if (!edge.branch || !from.branches.includes(edge.branch)) {
+        fail("EDGE_INVALID", `Condition Edge 缺少已声明 branch：${edge.from}`);
+      }
+    } else if (edge.branch !== undefined) {
+      fail("EDGE_INVALID", `非 Condition Edge 不能声明 branch：${edge.from}`);
+    }
+    const edgeKey = `${edge.from}\u0000${edge.to}\u0000${edge.branch ?? ""}`;
+    if (edgeKeys.has(edgeKey)) fail("EDGE_INVALID", "Workflow Edge 重复");
+    edgeKeys.add(edgeKey);
+    outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge]);
+    incoming.set(edge.to, [...(incoming.get(edge.to) ?? []), edge]);
+  }
+
+  const controlIncoming = new Map(incoming);
+  const controlOutgoing = new Map(outgoing);
+  for (const node of definition.nodes) {
+    if (node.failurePolicy.mode !== "fallback") continue;
+    const target = nodes.get(node.failurePolicy.nodeId);
+    if (!target || target.id === node.id) {
+      fail("GRAPH_INVALID", `Fallback 引用了未知或自身节点：${node.id}`);
+    }
+    const edge = { from: node.id, to: target.id };
+    controlOutgoing.set(node.id, [
+      ...(controlOutgoing.get(node.id) ?? []),
+      edge,
+    ]);
+    controlIncoming.set(target.id, [
+      ...(controlIncoming.get(target.id) ?? []),
+      edge,
+    ]);
+  }
+  assertNodeDegrees(definition, controlIncoming, outgoing, incoming);
+  assertAcyclicAndReachable(definition, controlIncoming, controlOutgoing);
+  return structuredClone(definition);
+}
+
+function assertNodeDegrees(
+  definition: AgentWorkflowDefinition,
+  incoming: ReadonlyMap<string, readonly unknown[]>,
+  outgoing: ReadonlyMap<string, readonly { branch?: string }[]>,
+  normalIncoming: ReadonlyMap<string, readonly unknown[]>,
+) {
+  for (const node of definition.nodes) {
+    const inCount = incoming.get(node.id)?.length ?? 0;
+    const edges = outgoing.get(node.id) ?? [];
+    if (node.id === definition.entryNodeId ? inCount !== 0 : inCount === 0) {
+      fail("GRAPH_INVALID", "entry 必须是唯一无入边节点");
+    }
+    if (node.type === "final") {
+      if (edges.length) fail("GRAPH_INVALID", "final 节点不能有出边");
+      continue;
+    }
+    if (!edges.length)
+      fail("GRAPH_INVALID", `非 final 节点缺少出边：${node.id}`);
+    if (node.type === "condition") {
+      const branches = edges.map(({ branch }) => branch);
+      if (
+        edges.length !== node.branches.length ||
+        node.branches.some((branch) => !branches.includes(branch))
+      ) {
+        fail("GRAPH_INVALID", `Condition branch 未一一绑定 Edge：${node.id}`);
+      }
+    } else if (node.type === "parallel") {
+      if (edges.length < 2 || edges.length > node.maxConcurrency) {
+        fail("GRAPH_INVALID", `Parallel 分支数量超出节点上限：${node.id}`);
+      }
+    } else if (edges.length !== 1) {
+      fail("GRAPH_INVALID", `节点必须只有一个默认出边：${node.id}`);
+    }
+    if (
+      node.type === "join" &&
+      (normalIncoming.get(node.id)?.length ?? 0) < 2
+    ) {
+      fail("GRAPH_INVALID", `Join 节点至少需要两个入边：${node.id}`);
+    }
+  }
+}
+
+function assertAcyclicAndReachable(
+  definition: AgentWorkflowDefinition,
+  incoming: ReadonlyMap<string, readonly unknown[]>,
+  outgoing: ReadonlyMap<string, readonly { to: string }[]>,
+) {
+  const degrees = new Map(
+    definition.nodes.map(({ id }) => [id, incoming.get(id)?.length ?? 0]),
+  );
+  const queue = definition.nodes
+    .filter(({ id }) => degrees.get(id) === 0)
+    .map(({ id }) => id);
+  const visited: string[] = [];
+  while (queue.length) {
+    const id = queue.shift()!;
+    visited.push(id);
+    for (const edge of outgoing.get(id) ?? []) {
+      const degree = (degrees.get(edge.to) ?? 0) - 1;
+      degrees.set(edge.to, degree);
+      if (degree === 0) queue.push(edge.to);
+    }
+  }
+  if (visited.length !== definition.nodes.length) {
+    fail("GRAPH_INVALID", "Workflow Definition 必须是无环图");
+  }
+  const reachable = new Set<string>();
+  const pending = [definition.entryNodeId];
+  while (pending.length) {
+    const id = pending.pop()!;
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    pending.push(...(outgoing.get(id) ?? []).map(({ to }) => to));
+  }
+  if (reachable.size !== definition.nodes.length) {
+    fail("GRAPH_INVALID", "Workflow 所有节点必须从 entry 可达");
+  }
+}
+
+function validText(value: string, maximum: number) {
+  return value.trim() === value && value.length > 0 && value.length <= maximum;
+}
+
+function fail(code: AgentWorkflowDefinitionErrorCode, message: string): never {
+  throw new AgentWorkflowDefinitionError(code, message);
+}

package/template/apps/server/src/agent-workflow/delegated-tool-authorization.ts

@@ -0,0 +1,15 @@
+import type { AgentRunAuthorizationSnapshot } from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+
+export interface DelegatedAgentToolAuthorizationPort {
+  authorize(input: {
+    readonly runId: string;
+    readonly operationKey: string;
+    readonly toolKey: string;
+    readonly delegation: NonNullable<
+      AgentRunAuthorizationSnapshot["delegation"]
+    >;
+    readonly context: RequestGuardContext;
+    readonly signal: AbortSignal;
+  }): Promise<void>;
+}

package/template/apps/server/src/agent-workflow/delegation-child-delivery.ts

@@ -0,0 +1,129 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { AgentWorkflowArtifactRef, JsonValue } from "@southwind-ai/shared";
+import { assertCanonicalWorkflowSafeValue } from "./event-validation.js";
+import { platformDigest } from "./platform-node-adapter-support.js";
+
+const MAX_CHILD_RESULT_BYTES = 8 * 1024;
+const MAX_ARTIFACT_REFS = 32;
+
+export function canonicalChildDelivery(
+  value: ModuleAiJsonValue,
+  resultDigest: string,
+): {
+  readonly smallResult?: JsonValue;
+  readonly artifacts: readonly AgentWorkflowArtifactRef[];
+} {
+  const artifacts = childArtifactRefs(value);
+  const candidate: JsonValue =
+    record(value) && value.artifactRefs !== undefined
+      ? { ...value, artifactRefs: artifacts.map(artifactRefJson) }
+      : value;
+  try {
+    assertCanonicalWorkflowSafeValue(
+      candidate,
+      "childResult.smallResult",
+      MAX_CHILD_RESULT_BYTES,
+    );
+    if (platformDigest(candidate) !== resultDigest) return { artifacts };
+    return { smallResult: structuredClone(candidate), artifacts };
+  } catch {
+    return { artifacts };
+  }
+}
+
+function childArtifactRefs(value: ModuleAiJsonValue) {
+  if (!record(value) || value.artifactRefs === undefined) return [];
+  if (
+    !Array.isArray(value.artifactRefs) ||
+    value.artifactRefs.length > MAX_ARTIFACT_REFS
+  ) {
+    throw new Error("CHILD_ARTIFACT_REFS_INVALID");
+  }
+  const artifacts = value.artifactRefs.map(stableArtifactRef);
+  const identities = artifacts.map(({ artifactId }) => artifactId);
+  if (new Set(identities).size !== identities.length) {
+    throw new Error("CHILD_ARTIFACT_REFS_DUPLICATE");
+  }
+  return artifacts;
+}
+
+function stableArtifactRef(value: unknown): AgentWorkflowArtifactRef {
+  if (!record(value) || !record(value.source)) {
+    throw new Error("CHILD_ARTIFACT_REF_INVALID");
+  }
+  const artifact: AgentWorkflowArtifactRef = {
+    artifactId: text(value.artifactId),
+    kind: text(value.kind),
+    mediaType: text(value.mediaType),
+    byteSize: integer(value.byteSize, 0),
+    sha256: text(value.sha256),
+    retentionPolicyKey: text(value.retentionPolicyKey),
+    source: {
+      moduleKey: text(value.source.moduleKey),
+      kind: text(value.source.kind),
+      id: text(value.source.id),
+      version: text(value.source.version),
+      sequence: integer(value.source.sequence, 1),
+      ...(value.source.digest === undefined
+        ? {}
+        : { digest: text(value.source.digest) }),
+    },
+  };
+  if (!/^(?:sha256:)?[a-f0-9]{64}$/.test(artifact.sha256)) {
+    throw new Error("CHILD_ARTIFACT_DIGEST_INVALID");
+  }
+  if (
+    artifact.source.digest !== undefined &&
+    !/^sha256:[a-f0-9]{64}$/.test(artifact.source.digest)
+  ) {
+    throw new Error("CHILD_ARTIFACT_SOURCE_DIGEST_INVALID");
+  }
+  assertCanonicalWorkflowSafeValue(
+    artifact,
+    "childResult.artifactRef",
+    4 * 1024,
+  );
+  return artifact;
+}
+
+function artifactRefJson(artifact: AgentWorkflowArtifactRef): JsonValue {
+  return {
+    artifactId: artifact.artifactId,
+    kind: artifact.kind,
+    mediaType: artifact.mediaType,
+    byteSize: artifact.byteSize,
+    sha256: artifact.sha256,
+    retentionPolicyKey: artifact.retentionPolicyKey,
+    source: {
+      moduleKey: artifact.source.moduleKey,
+      kind: artifact.source.kind,
+      id: artifact.source.id,
+      version: artifact.source.version,
+      sequence: artifact.source.sequence,
+      ...(artifact.source.digest ? { digest: artifact.source.digest } : {}),
+    },
+  };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function text(value: unknown) {
+  if (
+    typeof value !== "string" ||
+    value.trim() !== value ||
+    !value ||
+    value.length > 256
+  ) {
+    throw new Error("CHILD_ARTIFACT_COORDINATE_INVALID");
+  }
+  return value;
+}
+
+function integer(value: unknown, minimum: number) {
+  if (!Number.isSafeInteger(value) || Number(value) < minimum) {
+    throw new Error("CHILD_ARTIFACT_COORDINATE_INVALID");
+  }
+  return Number(value);
+}