create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import type { AgentWorkflowNodeResultReceipt } from "@southwind-ai/shared";
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+import type { AgentWorkflowUsage } from "@southwind-ai/shared";
+import type { JsonValue } from "@southwind-ai/shared";
+import type {
+  AgentWorkflowAdapterPreparation,
+  AgentWorkflowAdapterDispatchResult,
+  AgentWorkflowNodeAdapterContext,
+} from "./adapter-dispatch.js";
+import { canonicalJson } from "./canonical-json.js";
+import { assertCanonicalWorkflowSafeValue } from "./event-validation.js";
+import type {
+  WorkflowEffectCommandFence,
+  WorkflowEffectCommandReceipt,
+} from "./effect-command-fence.js";
+import { workflowId } from "./service-support.js";
+
+export function committedPlatformResult(
+  context: AgentWorkflowNodeAdapterContext,
+  fence: WorkflowEffectCommandFence,
+  resultDigest: string,
+  externalReceiptId = fence.adapter.coordinate,
+  outputArtifacts: readonly AgentWorkflowArtifactRef[] = context.inputArtifacts,
+  cumulativeUsage?: AgentWorkflowUsage,
+  executionEvidence?: NonNullable<
+    AgentWorkflowNodeResultReceipt["executionEvidence"]
+  >,
+  smallResult?: JsonValue,
+): AgentWorkflowAdapterDispatchResult {
+  const receiptId = workflowId("workflow_effect_receipt", fence.commandId);
+  const receipt: WorkflowEffectCommandReceipt = {
+    receiptId,
+    commandId: fence.commandId,
+    runId: fence.runId,
+    nodeRunId: fence.nodeRunId,
+    effectKind: fence.effectKind,
+    generation: fence.generation,
+    fenceTokenDigest: fence.fenceTokenDigest,
+    requestDigest: fence.requestDigest,
+    externalReceiptId,
+    resultDigest,
+    ...(smallResult === undefined ? {} : { smallResult }),
+    ...(outputArtifacts.length ? { artifactRefs: outputArtifacts } : {}),
+    authorizationSnapshotDigest: fence.authorizationSnapshotDigest,
+    runPolicyDigest: fence.runPolicyDigest,
+    committedAt: new Date().toISOString(),
+  };
+  return reconciledPlatformResult(
+    context,
+    receipt,
+    outputArtifacts,
+    cumulativeUsage,
+    executionEvidence,
+  );
+}
+
+export function reconciledPlatformResult(
+  context: AgentWorkflowNodeAdapterContext,
+  receipt: WorkflowEffectCommandReceipt,
+  outputArtifacts: readonly AgentWorkflowArtifactRef[] = receipt.artifactRefs ??
+    context.inputArtifacts,
+  cumulativeUsage?: AgentWorkflowUsage,
+  executionEvidence?: NonNullable<
+    AgentWorkflowNodeResultReceipt["executionEvidence"]
+  >,
+): AgentWorkflowAdapterDispatchResult {
+  return {
+    outcome: "committed",
+    receipt,
+    nodeResult: resultReceipt(
+      context,
+      receipt,
+      outputArtifacts,
+      executionEvidence,
+    ),
+    outputArtifacts,
+    ...(cumulativeUsage ? { cumulativeUsage } : {}),
+  };
+}
+
+function resultReceipt(
+  context: AgentWorkflowNodeAdapterContext,
+  receipt: WorkflowEffectCommandReceipt,
+  outputArtifacts: readonly AgentWorkflowArtifactRef[],
+  executionEvidence?: NonNullable<
+    AgentWorkflowNodeResultReceipt["executionEvidence"]
+  >,
+): AgentWorkflowNodeResultReceipt {
+  return {
+    receiptId: receipt.receiptId,
+    nodeRunId: context.nodeRun.nodeRunId,
+    resultDigest: receipt.resultDigest,
+    ...(context.node.outputSchemaKey
+      ? { outputSchemaKey: context.node.outputSchemaKey }
+      : {}),
+    artifactIds: outputArtifacts.map(({ artifactId }) => artifactId),
+    ...(executionEvidence ? { executionEvidence } : {}),
+    ...(receipt.smallResult === undefined
+      ? {}
+      : { smallResult: receipt.smallResult }),
+    recordedAt: context.nodeRun.updatedAt,
+  };
+}
+
+export function workflowNodeDeadline(context: AgentWorkflowNodeAdapterContext) {
+  const timeout = context.node.timeoutSeconds ?? 86_400;
+  return new Date(
+    Math.min(Date.parse(context.run.deadlineAt), Date.now() + timeout * 1_000),
+  ).toISOString();
+}
+
+export function effectCommandId(nodeRunId: string, effectKey: string) {
+  return workflowId("workflow_effect", nodeRunId, effectKey);
+}
+
+export function approvalCoordinate(commandId: string) {
+  const value = createHash("sha256").update(commandId).digest("hex");
+  return `workflow_approval_${value.slice(0, 40)}`;
+}
+
+export function platformDigest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+export function failedPlatformResult(
+  safeCode: string,
+  cumulativeUsage?: AgentWorkflowUsage,
+) {
+  return {
+    outcome: "failed" as const,
+    safeCode,
+    ...(cumulativeUsage ? { cumulativeUsage } : {}),
+  };
+}
+
+export function directPlatformResult(input: {
+  readonly context: AgentWorkflowNodeAdapterContext;
+  readonly result: JsonValue;
+  readonly resultDigest?: string;
+  readonly selectedBranch?: string;
+  readonly outputArtifacts?: readonly AgentWorkflowArtifactRef[];
+  readonly cumulativeUsage?: AgentWorkflowUsage;
+  readonly executionEvidence?: NonNullable<
+    AgentWorkflowNodeResultReceipt["executionEvidence"]
+  >;
+}): AgentWorkflowAdapterPreparation {
+  const outputArtifacts = input.outputArtifacts ?? input.context.inputArtifacts;
+  const resultDigest = input.resultDigest ?? platformDigest(input.result);
+  return {
+    outcome: "direct",
+    result: {
+      receiptId: workflowId(
+        "workflow_node_receipt",
+        input.context.nodeRun.nodeRunId,
+        resultDigest,
+      ),
+      nodeRunId: input.context.nodeRun.nodeRunId,
+      resultDigest,
+      ...(input.context.node.outputSchemaKey
+        ? { outputSchemaKey: input.context.node.outputSchemaKey }
+        : {}),
+      ...(input.selectedBranch ? { selectedBranch: input.selectedBranch } : {}),
+      ...(input.executionEvidence
+        ? { executionEvidence: input.executionEvidence }
+        : {}),
+      ...(smallResult(input.result) ? { smallResult: input.result } : {}),
+      artifactIds: outputArtifacts.map(({ artifactId }) => artifactId),
+      recordedAt: new Date().toISOString(),
+    },
+    outputArtifacts,
+    ...(input.cumulativeUsage
+      ? { cumulativeUsage: input.cumulativeUsage }
+      : {}),
+  };
+}
+
+function smallResult(value: JsonValue) {
+  try {
+    assertCanonicalWorkflowSafeValue(value, "smallResult", 8_192);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,264 @@
+import type {
+  DurableJobArtifact,
+  DurableJobSnapshot,
+} from "@southwind-ai/jobs";
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { DurableJobService } from "../jobs/service.js";
+import type { DurableJobWorker } from "../jobs/worker.js";
+import type { WorkflowService } from "../workflow/service.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import {
+  captureAuthorizationScope,
+  hashAuthorizationScope,
+} from "../data-access/scope-snapshot.js";
+import type {
+  AgentWorkflowAdapterDispatchResult,
+  AgentWorkflowNodeAdapter,
+  AgentWorkflowNodeAdapterContext,
+} from "./adapter-dispatch.js";
+import type { WorkflowEffectCommandFence } from "./effect-command-fence.js";
+import { CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY } from "@southwind-ai/server-sdk";
+import { createAgentWorkflowNodeAdapterRegistry } from "./node-adapter-factory.js";
+import {
+  directPlatformNodeAdapter,
+  waitPlatformNodeAdapter,
+} from "./platform-node-direct-adapters.js";
+import {
+  committedPlatformResult,
+  failedPlatformResult,
+  platformDigest,
+  reconciledPlatformResult,
+} from "./platform-node-adapter-support.js";
+import { approvalPlatformNodeAdapter } from "./platform-node-approval.js";
+import {
+  conditionNodeAdapter,
+  type AgentWorkflowConditionRegistry,
+} from "./condition-node-adapter.js";
+import { modelNodeAdapter } from "./model-node-adapter.js";
+import { toolNodeAdapter } from "./tool-node-adapter.js";
+import { subagentNodeAdapter } from "./subagent-node-adapter.js";
+import { artifactNodeAdapter } from "./artifact-node-adapter.js";
+import type {
+  AgentWorkflowArtifactPort,
+  AgentWorkflowDelegationExecutionPort,
+  AgentWorkflowModelExecutionPort,
+  AgentWorkflowNodeInputPort,
+} from "./node-execution-ports.js";
+import { ReceiptAgentWorkflowNodeInputPort } from "./node-input-receipt-port.js";
+
+export function createPlatformAgentWorkflowNodeAdapters(input: {
+  readonly context: RequestGuardContext;
+  readonly workflow: WorkflowService;
+  readonly jobs: DurableJobService;
+  readonly jobWorker: DurableJobWorker;
+  readonly tools: GovernedToolRegistry;
+  readonly inputs?: AgentWorkflowNodeInputPort;
+  readonly agentRuns: AgentWorkflowModelExecutionPort;
+  readonly delegations: AgentWorkflowDelegationExecutionPort;
+  readonly conditions: AgentWorkflowConditionRegistry;
+  readonly artifacts: AgentWorkflowArtifactPort;
+}) {
+  const inputs = input.inputs ?? new ReceiptAgentWorkflowNodeInputPort();
+  return createAgentWorkflowNodeAdapterRegistry({
+    model: modelNodeAdapter({
+      context: input.context,
+      inputs,
+      agentRuns: input.agentRuns,
+    }),
+    tool: toolNodeAdapter({
+      context: input.context,
+      inputs,
+      tools: input.tools,
+      workflow: input.workflow,
+    }),
+    subagent: subagentNodeAdapter({
+      context: input.context,
+      inputs,
+      delegations: input.delegations,
+    }),
+    condition: conditionNodeAdapter(input.conditions),
+    approval: approvalPlatformNodeAdapter(input.context, input.workflow),
+    job: jobAdapter(input.context, input.jobs, input.jobWorker),
+    wait: waitPlatformNodeAdapter(),
+    artifact: artifactNodeAdapter(input.artifacts),
+    final: directPlatformNodeAdapter("final"),
+  });
+}
+
+function jobAdapter(
+  context: RequestGuardContext,
+  jobs: DurableJobService,
+  worker: DurableJobWorker,
+): AgentWorkflowNodeAdapter {
+  const scope = captureAuthorizationScope(context.actor.scopeContext);
+  const submit = async (
+    nodeContext: AgentWorkflowNodeAdapterContext,
+    command: {
+      readonly commandId: string;
+      readonly generation: number;
+      readonly requestDigest: string;
+    },
+    idempotencyKey: string,
+  ) => {
+    const node = nodeContext.node;
+    if (node.type !== "job") throw new Error("NODE_TYPE_MISMATCH");
+    const submitted = await jobs.submit({
+      handlerKey: node.taskKey,
+      queue: "agent-workflow",
+      idempotencyKey,
+      payload: {
+        commandId: command.commandId,
+        runId: nodeContext.run.runId,
+        nodeRunId: nodeContext.nodeRun.nodeRunId,
+        effectGeneration: command.generation,
+        requestDigest: command.requestDigest,
+      },
+      requestedBy: context.actor.id,
+      authorizationScope: scope.snapshot,
+      maxAttempts:
+        node.taskKey === CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY ? 3 : 1,
+      timeoutSeconds: node.timeoutSeconds ?? 900,
+    });
+    if (
+      submitted.job.requestedBy !== context.actor.id ||
+      !submitted.job.authorizationScope ||
+      hashAuthorizationScope(submitted.job.authorizationScope) !== scope.hash
+    ) {
+      throw new Error("JOB_OBJECT_FORBIDDEN");
+    }
+    return submitted;
+  };
+  return {
+    nodeType: "job",
+    async prepare({ node, nodeRun }) {
+      if (node.type !== "job")
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      return {
+        outcome: "effect",
+        effectKind: "job",
+        effectKey: node.id,
+        adapter: {
+          kind: "durable-job",
+          coordinate: `job-idempotency:${nodeRun.idempotencyKey}`,
+        },
+        requestDigest: platformDigest({ taskKey: node.taskKey }),
+      };
+    },
+    async dispatch({ context: nodeContext, command, fence }) {
+      const submitted = await submit(
+        nodeContext,
+        { ...command, generation: fence.generation },
+        command.idempotencyKey,
+      );
+      return jobResult(nodeContext, fence, await jobs.get(submitted.job.id));
+    },
+    async reconcile({
+      context: nodeContext,
+      command,
+      fence,
+      committedReceipt,
+    }) {
+      const submitted = await submit(
+        nodeContext,
+        command,
+        command.idempotencyKey,
+      );
+      const snapshot = await jobs.get(submitted.job.id);
+      if (snapshot?.job.status === "succeeded" && committedReceipt) {
+        return reconciledPlatformResult(nodeContext, committedReceipt, [
+          ...nodeContext.inputArtifacts,
+          ...snapshot.artifacts.map(projectJobArtifact),
+        ]);
+      }
+      return fence
+        ? jobResult(nodeContext, fence, snapshot)
+        : { outcome: "pending" };
+    },
+    async cancel({ context: nodeContext, command }) {
+      if (!command) return { cancelled: true };
+      const submitted = await submit(
+        nodeContext,
+        command,
+        command.idempotencyKey,
+      );
+      const snapshot = await jobs.get(submitted.job.id);
+      if (snapshot && !["queued", "running"].includes(snapshot.job.status)) {
+        return { cancelled: snapshot.job.status === "cancelled" };
+      }
+      return { cancelled: await worker.cancel(submitted.job.id) };
+    },
+  };
+}
+
+function jobResult(
+  context: AgentWorkflowNodeAdapterContext,
+  fence: WorkflowEffectCommandFence,
+  snapshot: DurableJobSnapshot | undefined,
+): AgentWorkflowAdapterDispatchResult {
+  if (!snapshot || ["queued", "running"].includes(snapshot.job.status)) {
+    return {
+      outcome: "waiting",
+      adapter: {
+        kind: "durable-job",
+        coordinate: snapshot?.job.id ?? fence.adapter.coordinate,
+      },
+    };
+  }
+  if (snapshot.job.status !== "succeeded") {
+    return failedPlatformResult(
+      `DURABLE_JOB_${snapshot.job.status.toUpperCase()}`,
+    );
+  }
+  return committedPlatformResult(
+    context,
+    fence,
+    platformDigest({
+      jobId: snapshot.job.id,
+      artifacts: snapshot.artifacts.map(({ id, sha256 }) => ({ id, sha256 })),
+    }),
+    snapshot.job.id,
+    [...context.inputArtifacts, ...snapshot.artifacts.map(projectJobArtifact)],
+  );
+}
+
+function projectJobArtifact(
+  artifact: DurableJobArtifact,
+): AgentWorkflowArtifactRef {
+  const metadata = artifact.metadata ?? {};
+  const required = [
+    metadata.retentionPolicyKey,
+    metadata.sourceModuleKey,
+    metadata.sourceKind,
+    metadata.sourceId,
+    metadata.sourceVersion,
+    metadata.sourceSequence,
+  ];
+  if (
+    required
+      .slice(0, 5)
+      .some((value) => typeof value !== "string" || !value.trim()) ||
+    !Number.isSafeInteger(metadata.sourceSequence) ||
+    Number(metadata.sourceSequence) < 1
+  ) {
+    throw new Error("DURABLE_JOB_ARTIFACT_COORDINATE_MISSING");
+  }
+  return {
+    artifactId: artifact.id,
+    kind: artifact.kind,
+    mediaType: artifact.contentType,
+    byteSize: artifact.byteSize,
+    sha256: artifact.sha256,
+    retentionPolicyKey: metadata.retentionPolicyKey as string,
+    source: {
+      moduleKey: metadata.sourceModuleKey as string,
+      kind: metadata.sourceKind as string,
+      id: metadata.sourceId as string,
+      version: metadata.sourceVersion as string,
+      sequence: metadata.sourceSequence as number,
+      ...(typeof metadata.sourceDigest === "string" && metadata.sourceDigest
+        ? { digest: metadata.sourceDigest }
+        : {}),
+    },
+  };
+}

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

@@ -0,0 +1,146 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { WorkflowService } from "../workflow/service.js";
+import type {
+  AgentWorkflowAdapterDispatchResult,
+  AgentWorkflowNodeAdapter,
+  AgentWorkflowNodeAdapterContext,
+} from "./adapter-dispatch.js";
+import type { WorkflowEffectCommandFence } from "./effect-command-fence.js";
+import {
+  approvalCoordinate,
+  committedPlatformResult,
+  effectCommandId,
+  failedPlatformResult,
+  platformDigest,
+  reconciledPlatformResult,
+  workflowNodeDeadline,
+} from "./platform-node-adapter-support.js";
+
+export function approvalPlatformNodeAdapter(
+  context: RequestGuardContext,
+  workflow: WorkflowService,
+): AgentWorkflowNodeAdapter {
+  return {
+    nodeType: "approval",
+    async prepare({ node, nodeRun }) {
+      if (node.type !== "approval") {
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      }
+      const commandId = effectCommandId(nodeRun.nodeRunId, node.id);
+      return {
+        outcome: "effect",
+        effectKind: "approval",
+        effectKey: node.id,
+        adapter: {
+          kind: "approval-work-item",
+          coordinate: approvalCoordinate(commandId),
+        },
+        requestDigest: platformDigest({
+          title: node.title,
+          candidateRoles: node.candidateRoles,
+        }),
+      };
+    },
+    async dispatch({ context: nodeContext, command, fence }) {
+      const item = await ensureApproval(
+        context,
+        workflow,
+        nodeContext,
+        command,
+      );
+      return approvalResult(nodeContext, fence, item.status, item.version);
+    },
+    async reconcile({
+      context: nodeContext,
+      command,
+      fence,
+      committedReceipt,
+    }) {
+      let item = await workflow.get(command.adapter.coordinate, context.actor);
+      if (!item && fence) {
+        item = await ensureApproval(context, workflow, nodeContext, command);
+      }
+      if (!item) return { outcome: "pending" };
+      if (item.status === "approved" && committedReceipt) {
+        return reconciledPlatformResult(nodeContext, committedReceipt);
+      }
+      return fence
+        ? approvalResult(nodeContext, fence, item.status, item.version)
+        : { outcome: "pending" };
+    },
+    async cancel({ command }) {
+      if (!command) return { cancelled: true };
+      const item = await workflow.get(
+        command.adapter.coordinate,
+        context.actor,
+      );
+      if (!item || !["pending", "claimed"].includes(item.status)) {
+        return { cancelled: !item || item.status === "cancelled" };
+      }
+      await workflow.cancel(
+        item.id,
+        {
+          expectedVersion: item.version,
+          idempotencyKey: `${command.idempotencyKey}:cancel`,
+          reason: "Agent Workflow cancelled",
+        },
+        context.actor,
+      );
+      return { cancelled: true };
+    },
+  };
+}
+
+async function ensureApproval(
+  context: RequestGuardContext,
+  workflow: WorkflowService,
+  nodeContext: AgentWorkflowNodeAdapterContext,
+  command: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["command"],
+) {
+  const node = nodeContext.node;
+  if (node.type !== "approval") throw new Error("NODE_TYPE_MISMATCH");
+  return workflow.create(
+    {
+      id: command.adapter.coordinate,
+      title: node.title,
+      candidateRoles: node.candidateRoles.map((code) => ({ code })),
+      dueAt: workflowNodeDeadline(nodeContext),
+      target: {
+        type: "agent-workflow-run",
+        id: command.runId,
+        route: `/admin/system/agent-workflows?runId=${encodeURIComponent(command.runId)}`,
+      },
+      idempotencyKey: command.idempotencyKey,
+    },
+    context.actor,
+  );
+}
+
+function approvalResult(
+  context: AgentWorkflowNodeAdapterContext,
+  fence: WorkflowEffectCommandFence,
+  status: string,
+  version: number,
+): AgentWorkflowAdapterDispatchResult {
+  if (["pending", "claimed"].includes(status)) {
+    return {
+      outcome: "waiting",
+      adapter: {
+        kind: "approval-work-item",
+        coordinate: fence.adapter.coordinate,
+      },
+    };
+  }
+  if (status !== "approved") {
+    return failedPlatformResult(
+      `APPROVAL_${status.toUpperCase().replaceAll("-", "_")}`,
+    );
+  }
+  return committedPlatformResult(
+    context,
+    fence,
+    platformDigest({ status, version }),
+  );
+}

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

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import type { AgentWorkflowNodeAdapter } from "./adapter-dispatch.js";
+import { canonicalJson } from "./canonical-json.js";
+import { workflowId } from "./service-support.js";
+
+export function waitPlatformNodeAdapter(): AgentWorkflowNodeAdapter {
+  return {
+    nodeType: "wait",
+    async prepare({ node, nodeRun }) {
+      if (node.type !== "wait") return failed("NODE_TYPE_MISMATCH");
+      return {
+        outcome: "waiting",
+        adapter: {
+          kind: "wait-signal",
+          coordinate: `workflow-signal:${digest({
+            signalKey: node.signalKey,
+            nodeRunId: nodeRun.nodeRunId,
+            idempotencyKey: nodeRun.idempotencyKey,
+          }).slice("sha256:".length)}`,
+        },
+      };
+    },
+  };
+}
+
+export function directPlatformNodeAdapter(
+  nodeType: "final",
+): AgentWorkflowNodeAdapter {
+  return {
+    nodeType,
+    async prepare(context) {
+      const resultDigest = digest({
+        nodeType,
+        inputArtifacts: context.inputArtifacts,
+      });
+      return {
+        outcome: "direct",
+        result: {
+          receiptId: workflowId(
+            "workflow_node_receipt",
+            context.nodeRun.nodeRunId,
+          ),
+          nodeRunId: context.nodeRun.nodeRunId,
+          resultDigest,
+          ...(context.node.outputSchemaKey
+            ? { outputSchemaKey: context.node.outputSchemaKey }
+            : {}),
+          artifactIds: context.inputArtifacts.map(
+            ({ artifactId }) => artifactId,
+          ),
+          recordedAt: context.nodeRun.updatedAt,
+        },
+        outputArtifacts: context.inputArtifacts,
+      };
+    },
+  };
+}
+
+function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+function failed(safeCode: string) {
+  return { outcome: "failed" as const, safeCode };
+}