create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/repository.ts

@@ -0,0 +1,157 @@
+import type {
+  AgentWorkflowEventData,
+  AgentWorkflowEventEnvelope,
+  AgentWorkflowNodeRun,
+  AgentWorkflowRelease,
+  AgentWorkflowRun,
+  AgentWorkflowSideEffectCommand,
+  AgentWorkflowBudget,
+} from "@southwind-ai/shared";
+
+export interface PendingAgentWorkflowEvent {
+  readonly eventId: string;
+  readonly occurredAt: string;
+  readonly causationEventId?: string;
+  readonly parentEventId?: string;
+  readonly childWorkflowRunId?: string;
+  readonly data: AgentWorkflowEventData;
+}
+
+export interface AgentWorkflowRunRecord {
+  readonly run: AgentWorkflowRun;
+  readonly idempotencyKey: string;
+  readonly headSequence: number;
+  readonly recoveryCount: number;
+}
+
+export interface AgentWorkflowRunSnapshot extends AgentWorkflowRunRecord {
+  readonly nodeRuns: readonly AgentWorkflowNodeRun[];
+  readonly sideEffects: readonly AgentWorkflowSideEffectCommand[];
+}
+
+export interface PublishAgentWorkflowReleaseResult {
+  readonly release: AgentWorkflowRelease;
+  readonly created: boolean;
+}
+
+export interface CreateAgentWorkflowRunInput {
+  readonly idempotencyKey: string;
+  readonly run: AgentWorkflowRun;
+  readonly initialNodeRun: AgentWorkflowNodeRun;
+  readonly event: PendingAgentWorkflowEvent;
+}
+
+export interface AgentWorkflowRunMutation {
+  readonly runId: string;
+  readonly expectedSequence: number;
+  readonly runUpdate?: {
+    readonly expectedVersion: number;
+    readonly value: AgentWorkflowRun;
+  };
+  readonly nodeUpdates?: readonly {
+    readonly expectedVersion: number;
+    readonly value: AgentWorkflowNodeRun;
+  }[];
+  readonly nodeInserts?: readonly AgentWorkflowNodeRun[];
+  readonly recovery?: {
+    readonly expectedCount: number;
+    readonly nextCount: number;
+  };
+  readonly events: readonly PendingAgentWorkflowEvent[];
+}
+
+export interface AgentWorkflowMutationResult {
+  readonly record: AgentWorkflowRunRecord;
+  readonly events: readonly AgentWorkflowEventEnvelope[];
+  readonly replayed: boolean;
+}
+
+export interface AgentWorkflowEventReadInput {
+  readonly runId: string;
+  readonly afterSequence: number;
+  readonly limit: number;
+}
+
+export interface AgentWorkflowRecoveryAdmissionInput {
+  readonly runId: string;
+  readonly expectedSequence: number;
+  readonly expectedRecoveryCount: number;
+  readonly actorId: string;
+  readonly scopeDigest: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly toolPolicyDigest: string;
+  readonly workspacePolicyDigest: string;
+  readonly executionPolicyDigest: string;
+  readonly event: PendingAgentWorkflowEvent;
+}
+
+export interface AgentWorkflowRecoveryAdmissionResult extends AgentWorkflowMutationResult {
+  readonly remainingBudget: AgentWorkflowBudget;
+}
+
+/**
+ * Mutations are atomic. Run/Node versions and event sequence are CAS values;
+ * eventId makes retry of an already committed mutation safe.
+ */
+export interface AgentWorkflowRepository {
+  publishRelease(
+    release: AgentWorkflowRelease,
+  ): Promise<PublishAgentWorkflowReleaseResult>;
+  getRelease(releaseId: string): Promise<AgentWorkflowRelease | undefined>;
+  findRelease(
+    workflowKey: string,
+    version: string,
+  ): Promise<AgentWorkflowRelease | undefined>;
+  createRun(
+    input: CreateAgentWorkflowRunInput,
+  ): Promise<AgentWorkflowMutationResult>;
+  getRun(runId: string): Promise<AgentWorkflowRunRecord | undefined>;
+  listRunsForActor(
+    tenantId: string,
+    actorId: string,
+    scopeDigest: string,
+    limit: number,
+  ): Promise<readonly AgentWorkflowRunRecord[]>;
+  getSnapshot(runId: string): Promise<AgentWorkflowRunSnapshot | undefined>;
+  getNodeRun(nodeRunId: string): Promise<AgentWorkflowNodeRun | undefined>;
+  listNodeRuns(runId: string): Promise<readonly AgentWorkflowNodeRun[]>;
+  readEvents(
+    input: AgentWorkflowEventReadInput,
+  ): Promise<readonly AgentWorkflowEventEnvelope[]>;
+  findEvent(eventId: string): Promise<AgentWorkflowEventEnvelope | undefined>;
+  commit(input: AgentWorkflowRunMutation): Promise<AgentWorkflowMutationResult>;
+  admitRecovery(
+    input: AgentWorkflowRecoveryAdmissionInput,
+  ): Promise<AgentWorkflowRecoveryAdmissionResult>;
+  prepareSideEffect(
+    command: AgentWorkflowSideEffectCommand,
+  ): Promise<{ command: AgentWorkflowSideEffectCommand; created: boolean }>;
+  getSideEffect(
+    commandId: string,
+  ): Promise<AgentWorkflowSideEffectCommand | undefined>;
+  listSideEffects(
+    runId: string,
+  ): Promise<readonly AgentWorkflowSideEffectCommand[]>;
+  updateSideEffect(
+    command: AgentWorkflowSideEffectCommand,
+    expectedVersion: number,
+  ): Promise<AgentWorkflowSideEffectCommand>;
+}
+
+export type AgentWorkflowRepositoryConflictCode =
+  | "RELEASE_IMMUTABLE_CONFLICT"
+  | "RUN_IDEMPOTENCY_CONFLICT"
+  | "RUN_NOT_FOUND"
+  | "VERSION_CONFLICT"
+  | "SEQUENCE_CONFLICT"
+  | "EVENT_ID_CONFLICT"
+  | "NODE_RUN_CONFLICT"
+  | "SIDE_EFFECT_CONFLICT"
+  | "RECOVERY_ADMISSION_REJECTED";
+
+export class AgentWorkflowRepositoryConflict extends Error {
+  constructor(readonly code: AgentWorkflowRepositoryConflictCode) {
+    super(code);
+    this.name = "AgentWorkflowRepositoryConflict";
+  }
+}

package/template/apps/server/src/agent-workflow/routes.ts

@@ -0,0 +1,307 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import { AgentWorkflowDefinitionError } from "./definition-validation.js";
+import { AgentWorkflowEvaluationServiceError } from "./evaluation-service.js";
+import {
+  AgentWorkflowQueryError,
+  type AgentWorkflowQueryService,
+} from "./query-service.js";
+import { AgentWorkflowRepositoryConflict } from "./repository.js";
+import { AgentWorkflowStateError } from "./state-machine.js";
+import { AgentWorkflowAuthorizationError } from "./authorization.js";
+import { AgentWorkflowCommandError } from "./command-facade.js";
+import { AgentWorkflowEvaluationRepositoryConflict } from "./evaluation-repository.js";
+import { AgentWorkflowWaitSignalError } from "./wait-signal-service.js";
+import type { AgentWorkflowArtifactPort } from "./node-execution-ports.js";
+import { AgentWorkflowArtifactAccessError } from "./artifact-access-error.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+
+interface WorkflowRouteContext {
+  readonly body?: unknown;
+  readonly params: Record<string, string | undefined>;
+  readonly request: Request;
+  readonly guardContext: RequestGuardContext;
+}
+
+export interface AgentWorkflowCommandFacade {
+  publish(body: unknown, context: RequestGuardContext): Promise<unknown>;
+  createRun(
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<unknown>;
+  cancel(
+    runId: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<unknown>;
+  recover(
+    runId: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<unknown>;
+  signal(
+    runId: string,
+    nodeRunId: string,
+    signalKey: string,
+    body: unknown,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<unknown>;
+  evaluate(body: unknown, context: RequestGuardContext): Promise<unknown>;
+  getEvaluation(
+    evaluationId: string,
+    context: RequestGuardContext,
+  ): Promise<unknown>;
+}
+
+export function registerAgentWorkflowRoutes(
+  app: RouteApp,
+  runtime?: {
+    readonly query: AgentWorkflowQueryService;
+    readonly commands: AgentWorkflowCommandFacade;
+    readonly artifacts: AgentWorkflowArtifactPort;
+    readonly readiness: {
+      readonly modelNodes:
+        | {
+            readonly status: "available";
+            readonly pricingCatalogDigest: string;
+          }
+        | { readonly status: "unavailable"; readonly safeCode: string };
+    };
+  },
+) {
+  app.get("/agent/workflows/readiness", (raw) =>
+    handle(raw, async () => required(runtime).readiness),
+  );
+  app.get("/agent/workflows/releases/:releaseId", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).query.release(param(route, "releaseId")),
+    ),
+  );
+  app.get("/agent/workflows/runs", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).query.list(
+        route.guardContext,
+        integerQuery(route.request, "limit", 100, 1, 200),
+      ),
+    ),
+  );
+  app.get("/agent/workflows/runs/:runId", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).query.detail(param(route, "runId"), route.guardContext),
+    ),
+  );
+  app.get("/agent/workflows/runs/:runId/events", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).query.events(
+        param(route, "runId"),
+        route.guardContext,
+        integerQuery(route.request, "afterSequence", 0, 0, 2_147_483_647),
+        integerQuery(route.request, "limit", 200, 1, 1_000),
+      ),
+    ),
+  );
+  app.get("/agent/workflows/evaluations/:evaluationId", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.getEvaluation(
+        param(route, "evaluationId"),
+        route.guardContext,
+      ),
+    ),
+  );
+  app.get("/agent/workflows/artifacts/:artifactId/resolve", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).artifacts.resolve({
+        artifactId: param(route, "artifactId"),
+        actorId: route.guardContext.actor.id,
+        scopeDigest: routeScopeDigest(route.guardContext),
+        signal: route.request.signal,
+      }),
+    ),
+  );
+  app.get("/agent/workflows/artifacts/open", async (raw) => {
+    const route = raw as WorkflowRouteContext;
+    try {
+      const token = new URL(route.request.url).searchParams.get("token");
+      if (!token) throw new AgentWorkflowRouteInputError("token");
+      const opened = await required(runtime).artifacts.open({
+        token,
+        actorId: route.guardContext.actor.id,
+        scopeDigest: routeScopeDigest(route.guardContext),
+        signal: route.request.signal,
+      });
+      return new Response(opened.body, {
+        headers: {
+          "cache-control": "private, no-store",
+          "content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(opened.filename)}`,
+          "content-length": String(opened.artifact.byteSize),
+          "content-type": opened.contentType,
+        },
+      });
+    } catch (error) {
+      return routeError(error, route.guardContext.requestId);
+    }
+  });
+  app.post("/agent/workflows/releases", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.publish(route.body, route.guardContext),
+    ),
+  );
+  app.post("/agent/workflows/runs", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.createRun(
+        route.body,
+        route.guardContext,
+        route.request.signal,
+      ),
+    ),
+  );
+  app.post("/agent/workflows/runs/:runId/cancel", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.cancel(
+        param(route, "runId"),
+        route.body,
+        route.guardContext,
+        route.request.signal,
+      ),
+    ),
+  );
+  app.post("/agent/workflows/runs/:runId/recover", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.recover(
+        param(route, "runId"),
+        route.body,
+        route.guardContext,
+        route.request.signal,
+      ),
+    ),
+  );
+  app.post(
+    "/agent/workflows/runs/:runId/nodes/:nodeRunId/signals/:signalKey",
+    (raw) =>
+      handle(raw, (route) =>
+        required(runtime).commands.signal(
+          param(route, "runId"),
+          param(route, "nodeRunId"),
+          param(route, "signalKey"),
+          route.body,
+          route.guardContext,
+          route.request.signal,
+        ),
+      ),
+  );
+  app.post("/agent/workflows/evaluations", (raw) =>
+    handle(raw, (route) =>
+      required(runtime).commands.evaluate(route.body, route.guardContext),
+    ),
+  );
+  return app;
+}
+
+async function handle(
+  raw: unknown,
+  operation: (route: WorkflowRouteContext) => Promise<unknown>,
+) {
+  const route = raw as WorkflowRouteContext;
+  try {
+    return json(await operation(route));
+  } catch (error) {
+    return routeError(error, route.guardContext.requestId);
+  }
+}
+
+function required<T>(value: T | undefined): T {
+  if (!value) throw new AgentWorkflowRuntimeUnavailable();
+  return value;
+}
+
+function param(route: WorkflowRouteContext, key: string) {
+  const value = route.params[key];
+  if (!value?.trim() || value.length > 256) {
+    throw new AgentWorkflowRouteInputError(key);
+  }
+  return value;
+}
+
+function integerQuery(
+  request: Request,
+  key: string,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+) {
+  const raw = new URL(request.url).searchParams.get(key);
+  if (raw === null) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new AgentWorkflowRouteInputError(key);
+  }
+  return value;
+}
+
+function routeError(error: unknown, requestId: string) {
+  if (error instanceof AgentWorkflowQueryError) {
+    return json(
+      { code: error.code, requestId, retryable: false },
+      error.status,
+    );
+  }
+  if (error instanceof AgentWorkflowWaitSignalError) {
+    return json(
+      { code: error.code, requestId, retryable: false },
+      error.status,
+    );
+  }
+  if (error instanceof AgentWorkflowArtifactAccessError) {
+    return json(
+      { code: error.code, requestId, retryable: false },
+      error.status,
+    );
+  }
+  if (
+    error instanceof AgentWorkflowCommandError ||
+    error instanceof AgentWorkflowAuthorizationError
+  ) {
+    const status =
+      error instanceof AgentWorkflowCommandError ? error.status : 403;
+    return json({ code: error.code, requestId, retryable: false }, status);
+  }
+  if (
+    error instanceof AgentWorkflowRouteInputError ||
+    error instanceof AgentWorkflowDefinitionError ||
+    error instanceof AgentWorkflowEvaluationServiceError
+  ) {
+    return json(
+      { code: "INVALID_WORKFLOW_REQUEST", requestId, retryable: false },
+      400,
+    );
+  }
+  if (
+    error instanceof AgentWorkflowRepositoryConflict ||
+    error instanceof AgentWorkflowEvaluationRepositoryConflict ||
+    error instanceof AgentWorkflowStateError
+  ) {
+    return json({ code: error.code, requestId, retryable: false }, 409);
+  }
+  return json(
+    { code: "AGENT_WORKFLOW_UNAVAILABLE", requestId, retryable: true },
+    503,
+  );
+}
+
+function json(body: unknown, status = 200) {
+  return Response.json(body, {
+    status,
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+class AgentWorkflowRouteInputError extends Error {}
+class AgentWorkflowRuntimeUnavailable extends Error {}
+
+function routeScopeDigest(context: RequestGuardContext) {
+  return `sha256:${captureAuthorizationScope(context.actor.scopeContext).hash}`;
+}