create-windy 0.6.11 → 0.6.14

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

@@ -0,0 +1,290 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AgentWorkflowDefinition,
+  JsonValue,
+  AgentWorkflowReleaseCoordinates,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import {
+  AgentWorkflowAuthorizationError,
+  captureAgentWorkflowAuthorization,
+  workflowDigest,
+} from "./authorization.js";
+import type { AgentWorkflowEvaluationRepository } from "./evaluation-repository.js";
+import type { AgentWorkflowEvaluationService } from "./evaluation-service.js";
+import type { AgentWorkflowQueryService } from "./query-service.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+import type { AgentWorkflowService } from "./service.js";
+import { buildAgentWorkflowInputReceipt } from "./input-receipt.js";
+import type { AgentWorkflowWaitSignalService } from "./wait-signal-service.js";
+import type { AgentWorkflowArtifactPort } from "./node-execution-ports.js";
+import type { AgentWorkflowWorkspacePolicyPort } from "./workspace-policy.js";
+import { AgentWorkflowCommandError } from "./command-error.js";
+import {
+  driveWorkflowBatch,
+  type AgentWorkflowSchedulerCommandPort,
+} from "./command-drive.js";
+import {
+  optionalWorkflowBudget,
+  workflowActor,
+  workflowArtifactRefs,
+  workflowEvaluationArm,
+  workflowDeadline,
+  workflowRequestInteger,
+  workflowRequestObject,
+  workflowRequestText,
+} from "./command-input.js";
+import { governedDefinitionToolSchemaVersion } from "./governed-tool-schema.js";
+
+export { AgentWorkflowCommandError } from "./command-error.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class ProductionAgentWorkflowCommandFacade {
+  constructor(
+    private readonly repository: AgentWorkflowRepository,
+    private readonly service: AgentWorkflowService,
+    private readonly query: AgentWorkflowQueryService,
+    private readonly evaluations: AgentWorkflowEvaluationService,
+    private readonly evaluationRepository: AgentWorkflowEvaluationRepository,
+    private readonly modules: readonly ModuleManifest[],
+    private readonly runtime: ServerRuntime,
+    private readonly tools: GovernedToolRegistry,
+    private readonly waitSignals: AgentWorkflowWaitSignalService,
+    private readonly artifacts: AgentWorkflowArtifactPort,
+    private readonly workspacePolicies: AgentWorkflowWorkspacePolicyPort,
+    private readonly schedulerFor: (
+      context: RequestGuardContext,
+    ) => AgentWorkflowSchedulerCommandPort,
+  ) {}
+
+  publish(body: unknown, context: RequestGuardContext) {
+    const value = workflowRequestObject(body);
+    const coordinates = workflowRequestObject(value.coordinates);
+    return this.service.publish({
+      definition: value.definition as AgentWorkflowDefinition,
+      coordinates: {
+        runtimeVersion: workflowRequestText(
+          coordinates.runtimeVersion,
+          "runtimeVersion",
+        ),
+        routeVersion: workflowRequestText(
+          coordinates.routeVersion,
+          "routeVersion",
+        ),
+        promptVersion: workflowRequestText(
+          coordinates.promptVersion,
+          "promptVersion",
+        ),
+        toolSchemaVersion: governedDefinitionToolSchemaVersion(
+          value.definition as AgentWorkflowDefinition,
+          this.tools,
+        ),
+        manifestDigest: workflowDigest(this.modules),
+      } satisfies AgentWorkflowReleaseCoordinates,
+      publishedBy: workflowActor(context),
+      publishedAt: new Date().toISOString(),
+    });
+  }
+
+  async createRun(
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const value = workflowRequestObject(body);
+    const releaseId = workflowRequestText(value.releaseId, "releaseId");
+    const release = await this.repository.getRelease(releaseId);
+    if (!release) throw new AgentWorkflowCommandError("RELEASE_NOT_FOUND", 404);
+    const authorization = await this.authorization(context, release);
+    const now = new Date();
+    const budget = optionalWorkflowBudget(value.budget);
+    const effectiveBudget = budget ?? release.definition.budget;
+    const inputValue = (value.input ?? {}) as JsonValue;
+    const entry = release.definition.nodes.find(
+      ({ id }) => id === release.definition.entryNodeId,
+    )!;
+    const inputReceipt = buildAgentWorkflowInputReceipt({
+      entry,
+      value: inputValue,
+      at: now.toISOString(),
+    });
+    const inputDigest = inputReceipt.valueDigest;
+    const inputArtifacts = workflowArtifactRefs(value.inputArtifacts);
+    if (
+      inputArtifacts.length &&
+      !(await this.artifacts.reauthorize({
+        artifacts: inputArtifacts,
+        actorId: authorization.actorId,
+        scopeDigest: authorization.scopeDigest,
+        signal,
+      }))
+    ) {
+      throw new AgentWorkflowAuthorizationError(
+        "WORKFLOW_ARTIFACT_OBJECT_FORBIDDEN",
+      );
+    }
+    const result = await this.service.createRun({
+      releaseId,
+      tenantId: authorization.tenantId,
+      actorId: authorization.actorId,
+      routeKey: `agent-workflow:${release.coordinates.routeVersion}`,
+      inputDigest,
+      inputReceipt,
+      scopeDigest: authorization.scopeDigest,
+      authorizationSnapshotDigest: authorization.authorizationSnapshotDigest,
+      toolPolicyDigest: authorization.toolPolicyDigest,
+      workspacePolicyDigest: authorization.workspacePolicyDigest,
+      executionPolicyDigest: authorization.executionPolicyDigest,
+      idempotencyKey: workflowRequestText(
+        value.idempotencyKey,
+        "idempotencyKey",
+      ),
+      deadlineAt: workflowDeadline(value.deadlineAt, now, effectiveBudget),
+      ...(budget ? { budget } : {}),
+      inputArtifacts,
+      at: now.toISOString(),
+    });
+    await driveWorkflowBatch({
+      repository: this.repository,
+      scheduler: this.schedulerFor(context),
+      runId: result.record.run.runId,
+      authorizationFence: authorization.fence,
+      signal,
+    });
+    return this.query.detail(result.record.run.runId, context);
+  }
+
+  async cancel(
+    runId: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    await this.query.requireAuthorizedSnapshot(runId, context);
+    const value = workflowRequestObject(body);
+    await this.schedulerFor(context).cancel({
+      runId,
+      reasonCode: workflowRequestText(value.reasonCode, "reasonCode"),
+      at: new Date().toISOString(),
+      signal,
+    });
+    return this.query.detail(runId, context);
+  }
+
+  async recover(
+    runId: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    workflowRequestObject(body);
+    const snapshot = await this.query.requireAuthorizedSnapshot(runId, context);
+    const release = await this.requireRelease(snapshot.run.releaseId);
+    const authorization = await this.authorization(context, release);
+    await this.schedulerFor(context).recover({
+      runId,
+      authorizationFence: authorization.fence,
+      at: new Date().toISOString(),
+      signal,
+    });
+    return this.query.detail(runId, context);
+  }
+
+  async signal(
+    runId: string,
+    nodeRunId: string,
+    signalKey: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    await this.query.requireAuthorizedSnapshot(runId, context);
+    const value = workflowRequestObject(body);
+    await this.waitSignals.signal({
+      runId,
+      nodeRunId,
+      signalKey,
+      idempotencyKey: workflowRequestText(
+        value.idempotencyKey,
+        "idempotencyKey",
+      ),
+      value: (value.value ?? null) as JsonValue,
+      at: new Date().toISOString(),
+    });
+    const snapshot = await this.query.requireAuthorizedSnapshot(runId, context);
+    const release = await this.requireRelease(snapshot.run.releaseId);
+    const authorization = await this.authorization(context, release);
+    await driveWorkflowBatch({
+      repository: this.repository,
+      scheduler: this.schedulerFor(context),
+      runId,
+      authorizationFence: authorization.fence,
+      signal,
+    });
+    return this.query.detail(runId, context);
+  }
+
+  evaluate(body: unknown, context: RequestGuardContext) {
+    const value = workflowRequestObject(body);
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    return this.evaluations.evaluatePair({
+      tenantId: scope.snapshot.tenantId,
+      createdBy: workflowActor(context),
+      scopeDigest: `sha256:${scope.hash}`,
+      evaluationSetKey: workflowRequestText(
+        value.evaluationSetKey,
+        "evaluationSetKey",
+      ),
+      evaluationSetVersion: workflowRequestText(
+        value.evaluationSetVersion,
+        "evaluationSetVersion",
+      ),
+      caseKey: workflowRequestText(value.caseKey, "caseKey"),
+      caseVersion: workflowRequestText(value.caseVersion, "caseVersion"),
+      trialKey: workflowRequestText(value.trialKey, "trialKey"),
+      trialIndex: workflowRequestInteger(value.trialIndex, "trialIndex"),
+      rubricKey: workflowRequestText(value.rubricKey, "rubricKey"),
+      rubricVersion: workflowRequestText(value.rubricVersion, "rubricVersion"),
+      singleAgent: workflowEvaluationArm(value.singleAgent, "singleAgent"),
+      multiAgent: workflowEvaluationArm(value.multiAgent, "multiAgent"),
+    });
+  }
+
+  async getEvaluation(evaluationId: string, context: RequestGuardContext) {
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    const record = await this.evaluationRepository.getById(evaluationId, {
+      tenantId: scope.snapshot.tenantId,
+      createdBy: workflowActor(context),
+    });
+    if (!record || record.identity.scopeDigest !== `sha256:${scope.hash}`) {
+      throw new AgentWorkflowCommandError("EVALUATION_NOT_FOUND", 404);
+    }
+    return record;
+  }
+
+  private authorization(
+    context: RequestGuardContext,
+    release: Awaited<
+      ReturnType<ProductionAgentWorkflowCommandFacade["requireRelease"]>
+    >,
+  ) {
+    return captureAgentWorkflowAuthorization({
+      context,
+      release,
+      modules: this.modules,
+      runtime: this.runtime,
+      tools: this.tools,
+      workspacePolicies: this.workspacePolicies,
+    });
+  }
+
+  private async requireRelease(releaseId: string) {
+    const release = await this.repository.getRelease(releaseId);
+    if (!release) throw new AgentWorkflowCommandError("RELEASE_NOT_FOUND", 404);
+    return release;
+  }
+}

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

@@ -0,0 +1,133 @@
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowBudget,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import { AgentWorkflowCommandError } from "./command-error.js";
+import type { AgentWorkflowEvaluationArmRequest } from "./evaluation-validation.js";
+
+export function workflowRequestObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new AgentWorkflowCommandError("INVALID_WORKFLOW_REQUEST", 400);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function workflowRequestText(value: unknown, field: string) {
+  if (
+    typeof value !== "string" ||
+    value.trim() !== value ||
+    !value ||
+    value.length > 256
+  ) {
+    throw new AgentWorkflowCommandError(`INVALID_${field.toUpperCase()}`, 400);
+  }
+  return value;
+}
+
+export function workflowActor(context: RequestGuardContext) {
+  if (context.actor.type === "anonymous") {
+    throw new AgentWorkflowCommandError("WORKFLOW_ACTOR_REQUIRED", 403);
+  }
+  return context.actor.id;
+}
+
+export function workflowRequestInteger(value: unknown, field: string) {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new AgentWorkflowCommandError(`INVALID_${field.toUpperCase()}`, 400);
+  }
+  return Number(value);
+}
+
+export function workflowDeadline(
+  value: unknown,
+  now: Date,
+  budget: AgentWorkflowBudget,
+) {
+  if (value === undefined) {
+    return new Date(
+      now.getTime() + budget.maxDurationSeconds * 1_000,
+    ).toISOString();
+  }
+  return workflowRequestText(value, "deadlineAt");
+}
+
+export function optionalWorkflowBudget(value: unknown) {
+  return value === undefined
+    ? undefined
+    : (workflowRequestObject(value) as unknown as AgentWorkflowBudget);
+}
+
+export function workflowArtifactRefs(value: unknown) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new AgentWorkflowCommandError("INVALID_INPUT_ARTIFACTS", 400);
+  }
+  return value.map(workflowArtifactRef);
+}
+
+export function workflowEvaluationArm(
+  value: unknown,
+  field: string,
+): AgentWorkflowEvaluationArmRequest {
+  const arm = workflowRequestObject(value);
+  const availability = workflowRequestObject(arm.availability);
+  const status = workflowRequestText(
+    availability.status,
+    `${field}AvailabilityStatus`,
+  );
+  if (status === "run") {
+    return {
+      releaseId: workflowRequestText(arm.releaseId, `${field}ReleaseId`),
+      availability: {
+        status,
+        runId: workflowRequestText(availability.runId, `${field}RunId`),
+      },
+    };
+  }
+  if (status === "unavailable") {
+    return {
+      releaseId: workflowRequestText(arm.releaseId, `${field}ReleaseId`),
+      availability: { status },
+    };
+  }
+  throw new AgentWorkflowCommandError(
+    `INVALID_${field.toUpperCase()}_AVAILABILITY`,
+    400,
+  );
+}
+
+function workflowArtifactRef(value: unknown): AgentWorkflowArtifactRef {
+  const item = workflowRequestObject(value);
+  const source = workflowRequestObject(item.source);
+  const ref = {
+    artifactId: workflowRequestText(item.artifactId, "artifactId"),
+    kind: workflowRequestText(item.kind, "artifactKind"),
+    mediaType: workflowRequestText(item.mediaType, "artifactMediaType"),
+    byteSize: workflowRequestInteger(item.byteSize, "artifactByteSize"),
+    sha256: workflowRequestText(item.sha256, "artifactSha256"),
+    retentionPolicyKey: workflowRequestText(
+      item.retentionPolicyKey,
+      "artifactRetentionPolicyKey",
+    ),
+    source: {
+      moduleKey: workflowRequestText(source.moduleKey, "artifactSourceModule"),
+      kind: workflowRequestText(source.kind, "artifactSourceKind"),
+      id: workflowRequestText(source.id, "artifactSourceId"),
+      version: workflowRequestText(source.version, "artifactSourceVersion"),
+      sequence: workflowRequestInteger(
+        source.sequence,
+        "artifactSourceSequence",
+      ),
+      ...(source.digest === undefined
+        ? {}
+        : {
+            digest: workflowRequestText(source.digest, "artifactSourceDigest"),
+          }),
+    },
+  };
+  if (!/^[a-f0-9]{64}$/.test(ref.sha256) || ref.source.sequence < 1) {
+    throw new AgentWorkflowCommandError("INVALID_ARTIFACT_SHA256", 400);
+  }
+  return ref;
+}

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

@@ -0,0 +1,69 @@
+import type { AgentWorkflowNodeResultReceipt } from "@southwind-ai/shared";
+import type { AgentWorkflowNodeAdapter } from "./adapter-dispatch.js";
+import {
+  directPlatformResult,
+  failedPlatformResult,
+  platformDigest,
+} from "./platform-node-adapter-support.js";
+
+export interface AgentWorkflowConditionEvaluator {
+  readonly conditionKey: string;
+  evaluate(input: {
+    readonly receipts: readonly AgentWorkflowNodeResultReceipt[];
+    readonly allowedBranches: readonly string[];
+  }): Promise<string> | string;
+}
+
+export class AgentWorkflowConditionRegistry {
+  readonly #evaluators: ReadonlyMap<string, AgentWorkflowConditionEvaluator>;
+
+  constructor(evaluators: readonly AgentWorkflowConditionEvaluator[]) {
+    this.#evaluators = new Map(
+      evaluators.map((evaluator) => [evaluator.conditionKey, evaluator]),
+    );
+    if (this.#evaluators.size !== evaluators.length) {
+      throw new Error("Workflow Condition evaluator Key 重复");
+    }
+  }
+
+  require(conditionKey: string) {
+    const evaluator = this.#evaluators.get(conditionKey);
+    if (!evaluator) throw new Error("WORKFLOW_CONDITION_UNKNOWN");
+    return evaluator;
+  }
+}
+
+export function conditionNodeAdapter(
+  conditions: AgentWorkflowConditionRegistry,
+): AgentWorkflowNodeAdapter {
+  return {
+    nodeType: "condition",
+    async prepare(context) {
+      const node = context.node;
+      if (node.type !== "condition") {
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      }
+      const receipts = context.inputReceipts;
+      const branch = await conditions.require(node.conditionKey).evaluate({
+        receipts,
+        allowedBranches: node.branches,
+      });
+      if (!node.branches.includes(branch)) {
+        return failedPlatformResult("CONDITION_BRANCH_INVALID");
+      }
+      return directPlatformResult({
+        context,
+        result: { conditionKey: node.conditionKey, selectedBranch: branch },
+        resultDigest: platformDigest({
+          conditionKey: node.conditionKey,
+          branch,
+          inputs: receipts.map(({ receiptId, resultDigest }) => ({
+            receiptId,
+            resultDigest,
+          })),
+        }),
+        selectedBranch: branch,
+      });
+    },
+  };
+}

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

@@ -0,0 +1,41 @@
+import type {
+  AgentWorkflowBudget,
+  AgentWorkflowNode,
+} from "@southwind-ai/shared";
+
+export function assertAgentWorkflowBudget(
+  budget: AgentWorkflowBudget,
+  label: string,
+  invalid: (message: string) => never,
+) {
+  const entries = Object.entries(budget) as Array<
+    [keyof AgentWorkflowBudget, number]
+  >;
+  if (
+    entries.some(([, value]) => !Number.isSafeInteger(value) || value < 0) ||
+    budget.maxDurationSeconds < 1 ||
+    budget.maxParallelism < 1
+  ) {
+    invalid(`${label} Budget 无效`);
+  }
+}
+
+export function assertAgentWorkflowFailurePolicy(
+  node: AgentWorkflowNode,
+  invalid: (message: string) => never,
+) {
+  if (
+    node.type === "condition" &&
+    (node.failurePolicy.mode === "skip" ||
+      (node.failurePolicy.mode === "retry" &&
+        node.failurePolicy.exhausted === "skip"))
+  ) {
+    invalid(`Condition Node 不能使用无确定分支的 skip：${node.id}`);
+  }
+  if (
+    node.type === "final" &&
+    ["skip", "fallback"].includes(node.failurePolicy.mode)
+  ) {
+    invalid(`Final Node 必须生成 receipt 或使 Run 失败：${node.id}`);
+  }
+}