create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent-workflow/drizzle-write-support.ts

@@ -0,0 +1,101 @@
+import {
+  agentWorkflowEvents,
+  agentWorkflowNodeRuns,
+  agentWorkflowRuns,
+} from "@southwind-ai/database";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { and, desc, eq, sql } from "drizzle-orm";
+import { nodeRunRow, runRow, toRun } from "./drizzle-repository-mappers.js";
+import { conflict } from "./in-memory-repository-support.js";
+import type {
+  AgentWorkflowRunMutation,
+  AgentWorkflowRunRecord,
+} from "./repository.js";
+
+export async function applyRunMutation(
+  tx: Transaction,
+  input: AgentWorkflowRunMutation,
+) {
+  if (input.runUpdate) {
+    const [updated] = await tx
+      .update(agentWorkflowRuns)
+      .set({
+        ...runRow(input.runUpdate.value),
+        ...(input.recovery ? { recoveryCount: input.recovery.nextCount } : {}),
+      })
+      .where(
+        and(
+          eq(agentWorkflowRuns.runId, input.runId),
+          eq(agentWorkflowRuns.version, input.runUpdate.expectedVersion),
+          ...(input.recovery
+            ? [
+                eq(
+                  agentWorkflowRuns.recoveryCount,
+                  input.recovery.expectedCount,
+                ),
+              ]
+            : []),
+        ),
+      )
+      .returning({ id: agentWorkflowRuns.runId });
+    if (!updated) conflict("VERSION_CONFLICT");
+  } else if (input.recovery) {
+    const [updated] = await tx
+      .update(agentWorkflowRuns)
+      .set({ recoveryCount: input.recovery.nextCount })
+      .where(
+        and(
+          eq(agentWorkflowRuns.runId, input.runId),
+          eq(agentWorkflowRuns.recoveryCount, input.recovery.expectedCount),
+        ),
+      )
+      .returning({ id: agentWorkflowRuns.runId });
+    if (!updated) conflict("VERSION_CONFLICT");
+  }
+  for (const update of input.nodeUpdates ?? []) {
+    const [row] = await tx
+      .update(agentWorkflowNodeRuns)
+      .set(nodeRunRow(update.value))
+      .where(
+        and(
+          eq(agentWorkflowNodeRuns.nodeRunId, update.value.nodeRunId),
+          eq(agentWorkflowNodeRuns.version, update.expectedVersion),
+        ),
+      )
+      .returning({ id: agentWorkflowNodeRuns.nodeRunId });
+    if (!row) conflict("VERSION_CONFLICT");
+  }
+  if (input.nodeInserts?.length) {
+    await tx
+      .insert(agentWorkflowNodeRuns)
+      .values(input.nodeInserts.map(nodeRunRow));
+  }
+}
+
+export async function runRecord(
+  tx: Transaction,
+  row: typeof agentWorkflowRuns.$inferSelect,
+): Promise<AgentWorkflowRunRecord> {
+  const [head] = await tx
+    .select({ sequence: agentWorkflowEvents.sequence })
+    .from(agentWorkflowEvents)
+    .where(eq(agentWorkflowEvents.runId, row.runId))
+    .orderBy(desc(agentWorkflowEvents.sequence))
+    .limit(1);
+  return {
+    run: toRun(row),
+    idempotencyKey: row.idempotencyKey,
+    headSequence: head?.sequence ?? 0,
+    recoveryCount: row.recoveryCount,
+  };
+}
+
+export async function lock(tx: Transaction, key: string) {
+  await tx.execute(
+    sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`,
+  );
+}
+
+export type Transaction = Parameters<
+  Parameters<NodePgDatabase["transaction"]>[0]
+>[0];

package/template/apps/server/src/agent-workflow/durable-continuation-authorization.ts

@@ -0,0 +1,109 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import {
+  AgentWorkflowAuthorizationError,
+  captureAgentWorkflowAuthorization,
+  type AgentWorkflowAuthorizationSnapshot,
+} from "./authorization.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+import type { AgentWorkflowWorkspacePolicyPort } from "./workspace-policy.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class AgentWorkflowContinuationAuthorizationError extends Error {
+  constructor(readonly safeCode: string) {
+    super(safeCode);
+    this.name = "AgentWorkflowContinuationAuthorizationError";
+  }
+}
+
+export interface AuthorizedAgentWorkflowContinuation {
+  readonly context: RequestGuardContext;
+  readonly authorization: AgentWorkflowAuthorizationSnapshot;
+}
+
+export async function authorizeAgentWorkflowContinuation(input: {
+  readonly runId: string;
+  readonly repository: AgentWorkflowRepository;
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ServerRuntime;
+  readonly tools: GovernedToolRegistry;
+  readonly workspacePolicies: AgentWorkflowWorkspacePolicyPort;
+  readonly resolveActor: (actorId: string) => Promise<RequestActor | undefined>;
+}): Promise<AuthorizedAgentWorkflowContinuation> {
+  const snapshot = await input.repository.getSnapshot(input.runId);
+  if (!snapshot) throw denied("WORKFLOW_CONTINUATION_RUN_NOT_FOUND");
+  const release = await input.repository.getRelease(snapshot.run.releaseId);
+  if (!release) throw denied("WORKFLOW_CONTINUATION_RELEASE_NOT_FOUND");
+  const actor = await input.resolveActor(snapshot.run.actorId);
+  if (!actor || actor.type === "anonymous") {
+    throw denied("WORKFLOW_CONTINUATION_ACTOR_REVOKED");
+  }
+  const context = await input.runtime.createGuardContextForActor(
+    new Request("http://jobs.local/agent-workflow/continue"),
+    actor,
+  );
+  const feature = input.modules
+    .flatMap(({ features }) => features)
+    .find(({ key }) => key === "system.agent-workflow");
+  if (!feature) throw denied("WORKFLOW_CONTINUATION_FEATURE_MISSING");
+  const access = await evaluateAccessGuards(
+    input.runtime,
+    context,
+    {
+      permission: { permissionKey: "system.agent-workflow.manage" },
+      feature,
+    },
+    { record: false },
+  );
+  if (!access.decision.allowed) {
+    throw denied("WORKFLOW_CONTINUATION_ACCESS_REVOKED");
+  }
+  let authorization: AgentWorkflowAuthorizationSnapshot;
+  try {
+    authorization = await captureAgentWorkflowAuthorization({
+      context,
+      release,
+      modules: input.modules,
+      runtime: input.runtime,
+      tools: input.tools,
+      workspacePolicies: input.workspacePolicies,
+    });
+  } catch (error) {
+    if (error instanceof AgentWorkflowAuthorizationError) {
+      throw denied("WORKFLOW_CONTINUATION_POLICY_REVOKED");
+    }
+    throw error;
+  }
+  if (
+    authorization.actorId !== snapshot.run.actorId ||
+    authorization.tenantId !== snapshot.run.tenantId ||
+    authorization.scopeDigest !== snapshot.run.scopeDigest ||
+    authorization.authorizationSnapshotDigest !==
+      snapshot.run.authorizationSnapshotDigest ||
+    authorization.toolPolicyDigest !== snapshot.run.toolPolicyDigest ||
+    authorization.workspacePolicyDigest !==
+      snapshot.run.workspacePolicyDigest ||
+    authorization.executionPolicyDigest !== snapshot.run.executionPolicyDigest
+  ) {
+    throw denied("WORKFLOW_CONTINUATION_FENCE_DRIFTED");
+  }
+  return { context, authorization };
+}
+
+export function deniedContinuationActor(actorId: string): RequestActor {
+  return {
+    id: actorId,
+    type: "user",
+    name: actorId,
+    roleCodes: [],
+    permissionKeys: [],
+  };
+}
+
+function denied(safeCode: string) {
+  return new AgentWorkflowContinuationAuthorizationError(safeCode);
+}

package/template/apps/server/src/agent-workflow/durable-continuation-driver.ts

@@ -0,0 +1,97 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { DurableHandlerError } from "@southwind-ai/jobs";
+import { isAgentWorkflowTerminal } from "@southwind-ai/shared";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  AgentWorkflowContinuationAuthorizationError,
+  authorizeAgentWorkflowContinuation,
+  deniedContinuationActor,
+} from "./durable-continuation-authorization.js";
+import type { AgentWorkflowSchedulerCommandPort } from "./command-drive.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+import type { AgentWorkflowWorkspacePolicyPort } from "./workspace-policy.js";
+
+export async function authorizeOrCancelContinuation(input: {
+  readonly runId: string;
+  readonly repository: AgentWorkflowRepository;
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly tools: GovernedToolRegistry;
+  readonly workspacePolicies: AgentWorkflowWorkspacePolicyPort;
+  readonly resolveActor: (actorId: string) => Promise<RequestActor | undefined>;
+  readonly createScheduler: (
+    context: RequestGuardContext,
+  ) => Pick<AgentWorkflowSchedulerCommandPort, "cancel">;
+  readonly signal: AbortSignal;
+}) {
+  try {
+    return await authorizeAgentWorkflowContinuation(input);
+  } catch (error) {
+    if (!(error instanceof AgentWorkflowContinuationAuthorizationError)) {
+      throw durableFailure(
+        "AGENT_WORKFLOW_CONTINUATION_AUTHORIZATION_CHECK_FAILED",
+        "Agent Workflow continuation 当前授权校验失败",
+        error,
+      );
+    }
+    const snapshot = await input.repository.getSnapshot(input.runId);
+    if (!snapshot || isAgentWorkflowTerminal(snapshot.run.status)) return;
+    const actor =
+      (await input.resolveActor(snapshot.run.actorId)) ??
+      deniedContinuationActor(snapshot.run.actorId);
+    const context = await input.runtime.createGuardContextForActor(
+      new Request("http://jobs.local/agent-workflow/cancel"),
+      actor,
+    );
+    try {
+      await input.createScheduler(context).cancel({
+        runId: input.runId,
+        reasonCode: error.safeCode,
+        at: monotonicNow(snapshot.run.updatedAt),
+        signal: input.signal,
+      });
+    } catch (cancelError) {
+      throw durableFailure(
+        "AGENT_WORKFLOW_CONTINUATION_CANCEL_FAILED",
+        "Agent Workflow continuation 授权失效后未能收敛取消",
+        cancelError,
+      );
+    }
+    return undefined;
+  }
+}
+
+export async function deferAgentWorkflowRecovery(input: {
+  readonly repository: AgentWorkflowRepository;
+  readonly port: Pick<AgentWorkflowSchedulerCommandPort, "deferContinuation">;
+  readonly runId: string;
+  readonly reason: "recovery-pending" | "request-aborted";
+}) {
+  const snapshot = await input.repository.getSnapshot(input.runId);
+  if (!snapshot || isAgentWorkflowTerminal(snapshot.run.status)) return;
+  await input.port.deferContinuation({
+    runId: input.runId,
+    mode: "recover",
+    reason: input.reason,
+    sourceSequence: snapshot.headSequence,
+    availableAt: new Date(Date.now() + 5_000).toISOString(),
+  });
+}
+
+export function agentWorkflowContinuationOutcome(value: unknown) {
+  return value && typeof value === "object" && "outcome" in value
+    ? String((value as { outcome?: unknown }).outcome)
+    : undefined;
+}
+
+function durableFailure(code: string, message: string, cause: unknown) {
+  return new DurableHandlerError(code, message, true, {
+    cause: cause instanceof Error ? cause.name : "unknown",
+  });
+}
+
+function monotonicNow(previous: string) {
+  return new Date(Math.max(Date.now(), Date.parse(previous))).toISOString();
+}

package/template/apps/server/src/agent-workflow/durable-continuation-runtime.ts

@@ -0,0 +1,173 @@
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+  type DurableHandlerRegistry,
+} from "@southwind-ai/jobs";
+import { isAgentWorkflowTerminal } from "@southwind-ai/shared";
+import type { DurableJobService } from "../jobs/service.js";
+import type { DurableJobWorker } from "../jobs/worker.js";
+import type {
+  AgentWorkflowContinuationRequest,
+  AgentWorkflowSchedulerCommandPort,
+} from "./command-drive.js";
+import type { AgentWorkflowRepository } from "./repository.js";
+
+export const AGENT_WORKFLOW_CONTINUATION_HANDLER =
+  "system.agent-workflow.continue";
+const CONTINUATION_QUEUE = AGENT_WORKFLOW_CONTINUATION_HANDLER;
+
+interface ContinuationPayload {
+  readonly runId: string;
+  readonly mode: AgentWorkflowContinuationRequest["mode"];
+  readonly reason: AgentWorkflowContinuationRequest["reason"];
+  readonly sourceSequence: number;
+}
+
+export interface AgentWorkflowContinuationExecutor {
+  execute(input: {
+    readonly payload: ContinuationPayload;
+    readonly context: DurableHandlerContext;
+  }): Promise<void>;
+}
+
+export class DurableAgentWorkflowContinuationRuntime {
+  private timer?: ReturnType<typeof setInterval>;
+  private polling = false;
+
+  constructor(
+    private readonly jobs: DurableJobService,
+    private readonly worker: DurableJobWorker,
+    registry: DurableHandlerRegistry,
+    private readonly repository: AgentWorkflowRepository,
+    private readonly executor: AgentWorkflowContinuationExecutor,
+    private readonly onError: (error: unknown) => void,
+    private readonly pollIntervalMs = 1_000,
+  ) {
+    registry.register({
+      key: AGENT_WORKFLOW_CONTINUATION_HANDLER,
+      payload: { parse: parsePayload },
+      execute: (payload, context) =>
+        this.executor.execute({ payload, context }),
+    });
+  }
+
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.wake(), this.pollIntervalMs);
+    this.timer.unref();
+    this.wake();
+  }
+
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  port(
+    causeId = "command",
+  ): Pick<AgentWorkflowSchedulerCommandPort, "deferContinuation"> {
+    return {
+      deferContinuation: (input) => this.defer(input, causeId),
+    };
+  }
+
+  private async defer(
+    input: AgentWorkflowContinuationRequest,
+    causeId: string,
+  ) {
+    const snapshot = await this.repository.getSnapshot(input.runId);
+    if (!snapshot || isAgentWorkflowTerminal(snapshot.run.status)) return;
+    const availableAt = date(input.availableAt, "availableAt");
+    await this.jobs.submit({
+      handlerKey: AGENT_WORKFLOW_CONTINUATION_HANDLER,
+      queue: CONTINUATION_QUEUE,
+      requestedBy: snapshot.run.actorId,
+      idempotencyKey: continuationKey(input, causeId),
+      payload: {
+        runId: input.runId,
+        mode: input.mode,
+        reason: input.reason,
+        sourceSequence: input.sourceSequence,
+      },
+      availableAt,
+      maxAttempts: 5,
+      timeoutSeconds: 300,
+    });
+    this.wake();
+  }
+
+  private wake() {
+    void this.poll().catch(this.onError);
+  }
+
+  private async poll() {
+    if (this.polling) return;
+    this.polling = true;
+    try {
+      for (let index = 0; index < 16; index += 1) {
+        const result = await this.worker.runNext(
+          CONTINUATION_QUEUE,
+          `server-${process.pid}-agent-workflow`,
+        );
+        if (result.status === "idle") return;
+      }
+    } finally {
+      this.polling = false;
+    }
+  }
+}
+
+function parsePayload(value: unknown): ContinuationPayload {
+  const input = record(value);
+  if (
+    !text(input.runId) ||
+    !["advance", "recover"].includes(String(input.mode)) ||
+    ![
+      "batch-limit",
+      "retry-backoff",
+      "waiting",
+      "recovery-pending",
+      "request-aborted",
+    ].includes(String(input.reason)) ||
+    !Number.isSafeInteger(input.sourceSequence) ||
+    Number(input.sourceSequence) < 0
+  ) {
+    throw new DurableHandlerError(
+      "AGENT_WORKFLOW_CONTINUATION_INVALID",
+      "Agent Workflow continuation payload 无效",
+      false,
+    );
+  }
+  return input as unknown as ContinuationPayload;
+}
+
+function continuationKey(
+  input: AgentWorkflowContinuationRequest,
+  causeId: string,
+) {
+  return [
+    input.runId,
+    input.mode,
+    input.reason,
+    String(input.sourceSequence),
+    causeId,
+  ].join(":");
+}
+
+function date(value: string, field: string) {
+  const milliseconds = Date.parse(value);
+  if (!Number.isFinite(milliseconds)) {
+    throw new Error(`Agent Workflow continuation ${field} 无效`);
+  }
+  return new Date(milliseconds);
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function text(value: unknown): value is string {
+  return typeof value === "string" && Boolean(value.trim());
+}

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

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import type { DurableJobSnapshot } from "@southwind-ai/jobs";
+import type { DurableJobService } from "../jobs/service.js";
+import {
+  captureAuthorizationScope,
+  hashAuthorizationScope,
+} from "../data-access/scope-snapshot.js";
+import type { RequestActor } from "../guards.js";
+import type {
+  AgentWorkflowAdapterDispatch,
+  AgentWorkflowDurableJobNodeAdapter,
+} from "./node-adapters.js";
+
+/** Adapts Durable Job submit/snapshot; the Workflow never takes over its lease state. */
+export class DurableJobNodeAdapter implements AgentWorkflowDurableJobNodeAdapter {
+  constructor(private readonly jobs: DurableJobService) {}
+
+  async dispatch(
+    input: Parameters<AgentWorkflowDurableJobNodeAdapter["dispatch"]>[0],
+  ) {
+    const scope = captureAuthorizationScope(input.actor.scopeContext);
+    const submitted = await this.jobs.submit({
+      handlerKey: input.taskKey,
+      queue: "agent-workflow",
+      idempotencyKey: input.idempotencyKey,
+      payload: {
+        commandId: input.commandId,
+        runId: input.runId,
+        nodeRunId: input.nodeRunId,
+        generation: input.generation,
+      },
+      requestedBy: input.actor.id,
+      authorizationScope: scope.snapshot,
+      maxAttempts: 1,
+      timeoutSeconds: input.timeoutSeconds,
+    });
+    return project(submitted.job.id, submitted.created, submitted.job.status);
+  }
+
+  async reconcile(
+    input: Parameters<AgentWorkflowDurableJobNodeAdapter["reconcile"]>[0],
+  ) {
+    const snapshot = await this.jobs.get(input.adapterId);
+    if (!snapshot) return undefined;
+    requireCurrentObjectAuthorization(snapshot, input.actor);
+    return projectSnapshot(snapshot);
+  }
+}
+
+function requireCurrentObjectAuthorization(
+  snapshot: DurableJobSnapshot,
+  actor: RequestActor,
+) {
+  const current = captureAuthorizationScope(actor.scopeContext);
+  if (
+    snapshot.job.requestedBy !== actor.id ||
+    !snapshot.job.authorizationScope ||
+    hashAuthorizationScope(snapshot.job.authorizationScope) !== current.hash
+  ) {
+    throw new AgentWorkflowJobAdapterError("JOB_OBJECT_FORBIDDEN");
+  }
+}
+
+function projectSnapshot(snapshot: DurableJobSnapshot) {
+  const result = project(snapshot.job.id, false, snapshot.job.status);
+  if (result.status !== "completed") return result;
+  return {
+    ...result,
+    resultDigest: digest({
+      jobId: snapshot.job.id,
+      status: snapshot.job.status,
+      artifacts: snapshot.artifacts.map(({ id, sha256 }) => ({ id, sha256 })),
+    }),
+  } satisfies AgentWorkflowAdapterDispatch;
+}
+
+function project(
+  adapterId: string,
+  created: boolean,
+  status: DurableJobSnapshot["job"]["status"],
+): AgentWorkflowAdapterDispatch {
+  if (status === "queued" || status === "running") {
+    return { adapterId, created, status: "waiting" };
+  }
+  if (status === "succeeded") {
+    return { adapterId, created, status: "completed" };
+  }
+  return {
+    adapterId,
+    created,
+    status: status === "cancelled" ? "cancelled" : "failed",
+    safeErrorCode:
+      status === "cancelled" ? "DURABLE_JOB_CANCELLED" : "DURABLE_JOB_FAILED",
+  };
+}
+
+function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+export class AgentWorkflowJobAdapterError extends Error {
+  constructor(readonly code: "JOB_OBJECT_FORBIDDEN") {
+    super(code);
+    this.name = "AgentWorkflowJobAdapterError";
+  }
+}