create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/canonical-agent-run-port.ts

@@ -0,0 +1,304 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  AgentDelegationGrant,
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type { AiRuntimeReportRemotePort } from "../ai-runtime-report/contracts.js";
+import type { AgentRunAuthorizationStore } from "../agent/run-authorization.js";
+import type { AgentRuntimePort } from "../agent/run-contracts.js";
+import type { AgentRunFacade } from "../agent/run-facade.js";
+import {
+  AgentWorkflowModelExecutionError,
+  type AgentWorkflowModelExecutionPort,
+} from "./node-execution-ports.js";
+import {
+  cumulativeModelUsage,
+  digest,
+  modelExecutionEvidence,
+  terminalModelUsage,
+  unverifiedModelUsage,
+} from "./canonical-agent-run-evidence.js";
+import type { AgentWorkflowModelPricingCatalog } from "./model-pricing-catalog.js";
+import { findWorkflowAgentRunBinding } from "./canonical-agent-run-binding.js";
+import {
+  awaitWorkflowAgentRun,
+  readWorkflowAgentRunResult,
+} from "./canonical-agent-run-remote.js";
+
+export class CanonicalAgentWorkflowModelExecutionPort implements AgentWorkflowModelExecutionPort {
+  constructor(
+    private readonly facade: AgentRunFacade,
+    private readonly remote: AgentRuntimePort,
+    private readonly reports: AiRuntimeReportRemotePort,
+    private readonly authorizations: AgentRunAuthorizationStore,
+    private readonly pricing?: AgentWorkflowModelPricingCatalog,
+  ) {}
+
+  operationPolicy(operationKey: string) {
+    return this.facade.operationPolicy(operationKey);
+  }
+
+  async startRun(input: {
+    readonly operationKey: string;
+    readonly value: ModuleAiJsonValue;
+    readonly idempotencyKey: string;
+    readonly context: Parameters<AgentRunFacade["start"]>[3];
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    readonly grant?: AgentDelegationGrant;
+  }) {
+    const existing = await findWorkflowAgentRunBinding(this.authorizations, {
+      actorId: input.context.actor.id,
+      operationKey: input.operationKey,
+      idempotencyKey: input.idempotencyKey,
+      sessionId: input.sessionId,
+    });
+    if (existing) return { runId: existing.runId };
+    const operation = this.operationPolicy(input.operationKey);
+    const modelPin = await this.remote.modelCoordinate?.(input.signal);
+    if (
+      !operation ||
+      !modelPin ||
+      modelPin.deploymentKey !== operation.deploymentKey
+    ) {
+      throw new Error("MODEL_COORDINATE_UNAVAILABLE");
+    }
+    return this.facade.start(
+      input.operationKey,
+      input.value,
+      input.idempotencyKey,
+      input.context,
+      [],
+      input.signal,
+      undefined,
+      input.sessionId,
+      input.grant ? { grant: input.grant } : undefined,
+      undefined,
+      modelPin,
+    );
+  }
+
+  async cancelRun(runId: string, signal: AbortSignal) {
+    return (
+      await this.remote.cancel(runId, "workflow-cancellation-requested", signal)
+    ).ok;
+  }
+
+  async execute(
+    input: Parameters<AgentWorkflowModelExecutionPort["execute"]>[0],
+  ) {
+    const existing = await findWorkflowAgentRunBinding(this.authorizations, {
+      actorId: input.context.actor.id,
+      operationKey: input.operationKey,
+      idempotencyKey: input.idempotencyKey,
+      sessionId: input.sessionId,
+    });
+    let runId = existing?.runId;
+    let modelPin = existing?.modelPin;
+    let runtimeBudget: AgentWorkflowBudget | undefined;
+    if (!runId) {
+      const operation = this.operationPolicy(input.operationKey);
+      const release = operation?.release;
+      if (!release || release.promptVersion !== input.promptKey) {
+        throw new Error("MODEL_PROMPT_RELEASE_MISMATCH");
+      }
+      modelPin = await this.remote.modelCoordinate?.(input.signal);
+      if (!modelPin || modelPin.deploymentKey !== operation.deploymentKey) {
+        throw new Error("MODEL_COORDINATE_UNAVAILABLE");
+      }
+      runtimeBudget = this.pricing?.admit({
+        deploymentKey: operation.deploymentKey,
+        model: modelPin.model,
+        current: input.currentUsage,
+        budget: input.budget,
+      }).runtimeBudget;
+    }
+    if (!modelPin || !this.pricing) {
+      throw new Error("MODEL_PRICING_UNAVAILABLE");
+    }
+    const startedAt = Date.now();
+    try {
+      if (!runId) {
+        const started = await this.facade.start(
+          input.operationKey,
+          input.value,
+          input.idempotencyKey,
+          input.context,
+          [],
+          input.signal,
+          undefined,
+          input.sessionId,
+          undefined,
+          runtimeBudget,
+          modelPin,
+        );
+        runId = started.runId;
+      }
+      await awaitWorkflowAgentRun({
+        remote: this.remote,
+        runId,
+        deadlineAt: input.deadlineAt,
+        signal: input.signal,
+      });
+      const [result, report] = await Promise.all([
+        readWorkflowAgentRunResult(this.remote, runId, input.signal),
+        this.reports.run(runId, input.signal),
+      ]);
+      if (
+        !report ||
+        report.status !== "completed" ||
+        !report.modelDeployments.length
+      ) {
+        throw new Error("MODEL_RUNTIME_EVIDENCE_UNAVAILABLE");
+      }
+      return {
+        runId,
+        result,
+        resultDigest: digest(result),
+        cumulativeUsage: cumulativeModelUsage(
+          input.currentUsage,
+          report,
+          Date.now() - startedAt,
+          this.pricing,
+          modelPin,
+        ),
+        executionEvidence: modelExecutionEvidence(
+          runId,
+          report,
+          this.pricing.digest,
+          modelPin,
+        ),
+      };
+    } catch (error) {
+      if (runId && input.signal.aborted) {
+        await this.remote.cancel(
+          runId,
+          "workflow-model-request-aborted",
+          AbortSignal.timeout(5_000),
+        );
+        throw error;
+      }
+      if (runId) {
+        const report = await this.reports.run(
+          runId,
+          AbortSignal.timeout(5_000),
+        );
+        if (report) {
+          throw new AgentWorkflowModelExecutionError(
+            safeCode(error),
+            terminalModelUsage(
+              input.currentUsage,
+              report,
+              Date.now() - startedAt,
+              this.pricing,
+              modelPin,
+            ),
+          );
+        }
+        throw new AgentWorkflowModelExecutionError(
+          "MODEL_RUNTIME_EVIDENCE_UNAVAILABLE",
+          unverifiedModelUsage(input.currentUsage, Date.now() - startedAt),
+        );
+      }
+      throw error;
+    }
+  }
+
+  async cancelByIdempotencyKey(
+    input: Parameters<
+      AgentWorkflowModelExecutionPort["cancelByIdempotencyKey"]
+    >[0],
+  ) {
+    const existing = await findWorkflowAgentRunBinding(this.authorizations, {
+      actorId: input.context.actor.id,
+      operationKey: input.operationKey,
+      idempotencyKey: input.idempotencyKey,
+      sessionId: input.sessionId,
+    });
+    if (!existing) {
+      return { cancelled: true, cumulativeUsage: input.currentUsage };
+    }
+    const { runId, modelPin } = existing;
+    const response = await this.remote.cancel(
+      runId,
+      "workflow-cancellation-requested",
+      input.signal,
+    );
+    if (!response.ok) return { cancelled: false };
+    const report = await this.reports.run(runId, input.signal);
+    if (!report || !["failed", "cancelled"].includes(report.status)) {
+      return { cancelled: false };
+    }
+    return {
+      cancelled: true,
+      cumulativeUsage: terminalModelUsage(
+        input.currentUsage,
+        report,
+        report.durationMs ?? 0,
+        this.pricing,
+        modelPin,
+      ),
+    };
+  }
+
+  async inspect(
+    runId: string,
+    current: AgentWorkflowUsage,
+    signal: AbortSignal,
+  ) {
+    const status = await this.remote.status(runId, signal);
+    if (["accepted", "running", "awaiting-approval"].includes(status.status)) {
+      return { status: "running" as const };
+    }
+    const report = await this.reports.run(runId, signal);
+    if (status.status !== "completed") {
+      const modelPin = await this.authorizations.modelPinForRun(runId);
+      if (!report || !modelPin) {
+        throw new Error("MODEL_RUNTIME_EVIDENCE_UNAVAILABLE");
+      }
+      return {
+        status: status.status as "failed" | "cancelled",
+        cumulativeUsage: terminalModelUsage(
+          current,
+          report,
+          report.durationMs ?? 0,
+          this.pricing,
+          modelPin,
+        ),
+      };
+    }
+    const result = await readWorkflowAgentRunResult(this.remote, runId, signal);
+    if (!report) throw new Error("MODEL_RUNTIME_EVIDENCE_UNAVAILABLE");
+    const modelPin = await this.authorizations.modelPinForRun(runId);
+    if (!modelPin) {
+      throw new Error("MODEL_RUNTIME_EVIDENCE_UNAVAILABLE");
+    }
+    return {
+      status: "completed" as const,
+      result,
+      resultDigest: digest(result),
+      cumulativeUsage: cumulativeModelUsage(
+        current,
+        report,
+        report.durationMs ?? 0,
+        this.pricing,
+        modelPin,
+      ),
+      executionEvidence: modelExecutionEvidence(
+        runId,
+        report,
+        this.pricing?.digest,
+        modelPin,
+      ),
+    };
+  }
+}
+
+function safeCode(error: unknown) {
+  const value =
+    error instanceof Error ? error.message : "MODEL_EXECUTION_FAILED";
+  return /^[A-Z][A-Z0-9_]{0,60}$/.test(value)
+    ? value
+    : "MODEL_EXECUTION_FAILED";
+}

package/template/apps/server/src/agent-workflow/canonical-agent-run-remote.ts

@@ -0,0 +1,64 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { AgentRuntimePort } from "../agent/run-contracts.js";
+
+export async function awaitWorkflowAgentRun(input: {
+  readonly remote: AgentRuntimePort;
+  readonly runId: string;
+  readonly deadlineAt: string;
+  readonly signal: AbortSignal;
+}) {
+  while (Date.now() < Date.parse(input.deadlineAt)) {
+    const status = await input.remote.status(input.runId, input.signal);
+    if (status.status === "completed") return;
+    if (status.status === "failed" || status.status === "cancelled") {
+      throw new Error(`MODEL_RUN_${status.status.toUpperCase()}`);
+    }
+    await wait(500, input.signal);
+  }
+  await input.remote.cancel(input.runId, "workflow-node-timeout", input.signal);
+  throw new Error("MODEL_RUN_TIMEOUT");
+}
+
+export async function readWorkflowAgentRunResult(
+  remote: AgentRuntimePort,
+  runId: string,
+  signal: AbortSignal,
+) {
+  const response = await remote.result(runId, signal);
+  const value: unknown = response.ok ? await response.json() : undefined;
+  if (
+    !isRecord(value) ||
+    value.runId !== runId ||
+    value.status !== "completed" ||
+    !isJson(value.output)
+  ) {
+    throw new Error("MODEL_RESULT_INVALID");
+  }
+  return value.output;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function isJson(value: unknown): value is ModuleAiJsonValue {
+  if (value === null || ["string", "number", "boolean"].includes(typeof value))
+    return true;
+  if (Array.isArray(value)) return value.every(isJson);
+  return isRecord(value) && Object.values(value).every(isJson);
+}
+
+function wait(milliseconds: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, milliseconds);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}

package/template/apps/server/src/agent-workflow/canonical-json.ts

@@ -0,0 +1,16 @@
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalValue(item)]),
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,195 @@
+import type { WorkflowAuthorizationFence } from "./budget-validation.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+
+export interface AgentWorkflowSchedulerCommandPort {
+  advance(input: SchedulerAuthorizationInput): Promise<unknown>;
+  cancel(input: {
+    readonly runId: string;
+    readonly reasonCode: string;
+    readonly at: string;
+    readonly signal: AbortSignal;
+  }): Promise<unknown>;
+  recover(input: SchedulerAuthorizationInput): Promise<unknown>;
+  deferContinuation(input: AgentWorkflowContinuationRequest): Promise<void>;
+}
+
+export interface AgentWorkflowContinuationRequest {
+  readonly runId: string;
+  readonly mode: "advance" | "recover";
+  readonly reason:
+    | "batch-limit"
+    | "retry-backoff"
+    | "waiting"
+    | "recovery-pending"
+    | "request-aborted";
+  readonly sourceSequence: number;
+  readonly availableAt: string;
+}
+
+export interface SchedulerAuthorizationInput {
+  readonly runId: string;
+  readonly authorizationFence: WorkflowAuthorizationFence;
+  readonly at: string;
+  readonly signal: AbortSignal;
+}
+
+export async function driveWorkflowBatch(input: {
+  readonly repository: AgentWorkflowRepository;
+  readonly scheduler: AgentWorkflowSchedulerCommandPort;
+  readonly runId: string;
+  readonly authorizationFence: WorkflowAuthorizationFence;
+  readonly signal: AbortSignal;
+}) {
+  for (let index = 0; index < 32; index += 1) {
+    const before = await input.repository.getSnapshot(input.runId);
+    if (!before || terminal(before.run.status)) return { outcome: "terminal" };
+    if (input.signal.aborted) {
+      await defer(input, before, "advance", "request-aborted", delay(1_000));
+      return { outcome: "deferred", reason: "request-aborted" } as const;
+    }
+    let advanced: unknown;
+    try {
+      advanced = await input.scheduler.advance({
+        runId: input.runId,
+        authorizationFence: input.authorizationFence,
+        at: new Date().toISOString(),
+        signal: input.signal,
+      });
+    } catch (error) {
+      if (!input.signal.aborted) throw error;
+      const current = await input.repository.getSnapshot(input.runId);
+      if (current && !terminal(current.run.status)) {
+        await defer(
+          input,
+          current,
+          needsRecovery(current) ? "recover" : "advance",
+          "request-aborted",
+          delay(1_000),
+        );
+      }
+      return { outcome: "deferred", reason: "request-aborted" } as const;
+    }
+    const after = await input.repository.getSnapshot(input.runId);
+    if (!after || terminal(after.run.status)) return { outcome: "terminal" };
+    const directive = continuationDirective(advanced, after);
+    if (directive) {
+      await defer(
+        input,
+        after,
+        directive.mode,
+        directive.reason,
+        directive.availableAt,
+      );
+      return { outcome: "deferred", reason: directive.reason } as const;
+    }
+    if (after.headSequence === before.headSequence) {
+      const mode = needsRecovery(after) ? "recover" : "advance";
+      const reason = mode === "recover" ? "recovery-pending" : "waiting";
+      await defer(input, after, mode, reason, delay(5_000));
+      return { outcome: "deferred", reason } as const;
+    }
+  }
+  const current = await input.repository.getSnapshot(input.runId);
+  if (!current || terminal(current.run.status)) return { outcome: "terminal" };
+  await defer(
+    input,
+    current,
+    "advance",
+    "batch-limit",
+    new Date().toISOString(),
+  );
+  return { outcome: "deferred", reason: "batch-limit" } as const;
+}
+
+function continuationDirective(
+  value: unknown,
+  snapshot: NonNullable<
+    Awaited<ReturnType<AgentWorkflowRepository["getSnapshot"]>>
+  >,
+) {
+  const outcome = record(value).outcome;
+  if (outcome === "retry-after" || outcome === "backoff") {
+    return {
+      mode: "advance" as const,
+      reason: "retry-backoff" as const,
+      availableAt: retryAt(value) ?? delay(1_000),
+    };
+  }
+  if (["pending", "waiting", "completion-blocked"].includes(String(outcome))) {
+    const mode: AgentWorkflowContinuationRequest["mode"] = needsRecovery(
+      snapshot,
+    )
+      ? "recover"
+      : "advance";
+    return {
+      mode,
+      reason:
+        mode === "recover"
+          ? ("recovery-pending" as const)
+          : ("waiting" as const),
+      availableAt: delay(5_000),
+    };
+  }
+  return undefined;
+}
+
+async function defer(
+  input: Parameters<typeof driveWorkflowBatch>[0],
+  snapshot: NonNullable<
+    Awaited<ReturnType<AgentWorkflowRepository["getSnapshot"]>>
+  >,
+  mode: AgentWorkflowContinuationRequest["mode"],
+  reason: AgentWorkflowContinuationRequest["reason"],
+  availableAt: string,
+) {
+  await input.scheduler.deferContinuation({
+    runId: input.runId,
+    mode,
+    reason,
+    sourceSequence: snapshot.headSequence,
+    availableAt,
+  });
+}
+
+function needsRecovery(
+  snapshot: NonNullable<
+    Awaited<ReturnType<AgentWorkflowRepository["getSnapshot"]>>
+  >,
+) {
+  return (
+    snapshot.nodeRuns.some(
+      ({ status, resultReceipt }) =>
+        ["running", "waiting"].includes(status) && !resultReceipt,
+    ) ||
+    snapshot.sideEffects.some(({ status }) =>
+      [
+        "prepared",
+        "dispatched",
+        "committed",
+        "failed",
+        "cancellation-requested",
+      ].includes(status),
+    )
+  );
+}
+
+function retryAt(value: unknown) {
+  const candidate = record(value).retryAt;
+  return typeof candidate === "string" && Number.isFinite(Date.parse(candidate))
+    ? candidate
+    : undefined;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function delay(milliseconds: number) {
+  return new Date(Date.now() + milliseconds).toISOString();
+}
+
+function terminal(status: string) {
+  return ["completed", "failed", "cancelled", "timed-out"].includes(status);
+}

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

@@ -0,0 +1,9 @@
+export class AgentWorkflowCommandError extends Error {
+  constructor(
+    readonly code: string,
+    readonly status: 400 | 403 | 404,
+  ) {
+    super(code);
+    this.name = "AgentWorkflowCommandError";
+  }
+}