create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/client-workflow-artifact/authority-current.ts

@@ -0,0 +1,59 @@
+import {
+  agentWorkflowNodeRuns,
+  agentWorkflowRuns,
+  agentWorkflowSideEffectCommands,
+} from "@southwind-ai/database";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+
+export async function clientWorkflowAuthorityCurrent(
+  db: NodePgDatabase,
+  record: ClientAgentWorkflowArtifactRecord,
+  now: number,
+) {
+  const [command] = await db
+    .select()
+    .from(agentWorkflowSideEffectCommands)
+    .where(eq(agentWorkflowSideEffectCommands.commandId, record.commandId))
+    .for("update")
+    .limit(1);
+  if (!command) return false;
+  const [run] = await db
+    .select()
+    .from(agentWorkflowRuns)
+    .where(eq(agentWorkflowRuns.runId, record.runId))
+    .for("update")
+    .limit(1);
+  if (!run) return false;
+  const [nodeRun] = await db
+    .select()
+    .from(agentWorkflowNodeRuns)
+    .where(eq(agentWorkflowNodeRuns.nodeRunId, record.nodeRunId))
+    .for("update")
+    .limit(1);
+  return Boolean(
+    nodeRun &&
+    command.status === "dispatched" &&
+    command.runId === record.runId &&
+    command.nodeRunId === record.nodeRunId &&
+    command.effectKind === record.effectKind &&
+    command.adapterKind === "durable-job" &&
+    command.generation === record.effectGeneration &&
+    command.requestDigest === record.requestDigest &&
+    command.fenceTokenDigest === record.effectFenceTokenDigest &&
+    command.authorizationSnapshotDigest ===
+      record.authorizationSnapshotDigest &&
+    command.runPolicyDigest === record.runPolicyDigest &&
+    ["accepted", "running", "waiting"].includes(run.status) &&
+    !run.cancellationRequestedAt &&
+    run.deadlineAt > now &&
+    run.actorId === record.actorId &&
+    run.scopeDigest === record.scopeDigest &&
+    run.authorizationSnapshotDigest === record.authorizationSnapshotDigest &&
+    run.executionPolicyDigest === record.runPolicyDigest &&
+    nodeRun.runId === record.runId &&
+    nodeRun.nodeType === "job" &&
+    ["running", "waiting"].includes(nodeRun.status),
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/binding-registry.test.ts

@@ -0,0 +1,189 @@
+import { expect, test } from "bun:test";
+import {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS as limits,
+  type ModuleClientAgentWorkflowArtifactProjectBinding,
+} from "@southwind-ai/server-sdk";
+import {
+  clientWorkflowBindingCommitment,
+  ClientAgentWorkflowArtifactBindingRegistry,
+} from "./binding-registry.js";
+
+test("Composition 启动时拒绝超出 DB/DTO 边界与路径型文件名", () => {
+  for (const binding of [
+    value({ workflowKey: "w".repeat(limits.workflowKey + 1) }),
+    value({ nodeId: "n".repeat(limits.nodeId + 1) }),
+    value({ operationKey: "o".repeat(limits.operationKey + 1) }),
+    value({ releaseDigest: `sha256:${"d".repeat(65)}` }),
+    value({
+      terminalResultAuthority: {
+        ...value().terminalResultAuthority,
+        version: "v".repeat(limits.terminalAuthorityVersion + 1),
+      },
+    }),
+    value({
+      terminalResultAuthority: {
+        ...value().terminalResultAuthority,
+        digest: `sha256:${"e".repeat(65)}`,
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        kind: "k".repeat(limits.artifactKind + 1),
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        filename: `${"f".repeat(limits.artifactFilename)}x`,
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        retentionPolicyKey: "r".repeat(limits.retentionPolicyKey + 1),
+      },
+    }),
+    value({
+      artifact: { ...value().artifact, maxByteSize: limits.maxByteSize + 1 },
+    }),
+    value({ artifact: { ...value().artifact, filename: "nested/out.json" } }),
+    value({ artifact: { ...value().artifact, filename: "nested\\out.json" } }),
+    value({ workflowKey: "workflow\0key" }),
+    value({ nodeId: "page-agent\0artifact" }),
+    value({ operationKey: "analysis\0page-agent" }),
+    value({ releaseDigest: `sha256:${"d".repeat(63)}\0` }),
+    value({
+      artifact: { ...value().artifact, kind: "analysis\0report" },
+    }),
+    invalidContentTypeBinding(),
+    value({
+      artifact: { ...value().artifact, filename: "analysis\0.json" },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        retentionPolicyKey: "analysis\0case-artifact",
+      },
+    }),
+  ]) {
+    expect(
+      () => new ClientAgentWorkflowArtifactBindingRegistry([binding]),
+    ).toThrow("CLIENT_AGENT_WORKFLOW_BINDING_INVALID");
+  }
+});
+
+function invalidContentTypeBinding(): ModuleClientAgentWorkflowArtifactProjectBinding {
+  const binding = value();
+  Object.defineProperty(binding.artifact, "contentType", {
+    value: "application/json\0",
+    enumerable: true,
+  });
+  return binding;
+}
+
+test("每个 Workflow 只允许一个固定 PageAgent Job binding", () => {
+  expect(
+    () =>
+      new ClientAgentWorkflowArtifactBindingRegistry([
+        value(),
+        value({ nodeId: "other-node" }),
+      ]),
+  ).toThrow("CLIENT_AGENT_WORKFLOW_BINDING_DUPLICATE");
+});
+
+test("binding commitment 只承诺 authority version 与 digest", () => {
+  const first = value();
+  const second = value({
+    terminalResultAuthority: {
+      ...first.terminalResultAuthority,
+      async canonicalize() {
+        return { changed: true };
+      },
+    },
+    clientTaskAuthority: {
+      version: "sharp.client-task.v1",
+      digest: `sha256:${"f".repeat(64)}`,
+      async build({ workflowInput }) {
+        return { taskKey: "sharp.full-review", input: workflowInput };
+      },
+    },
+    launchAuthority: {
+      version: "sharp.workflow-launch.v1",
+      digest: `sha256:${"a".repeat(64)}`,
+      async authorizeRelease() {},
+      async authorizeRun({ actorId }) {
+        return {
+          authorizationScope: {
+            tenantId: "single-tenant",
+            actorId,
+            grants: [{ scope: "self" }],
+            roleIds: ["role-analyst"],
+          },
+        };
+      },
+    },
+  });
+  expect(clientWorkflowBindingCommitment(first)).toEqual(
+    clientWorkflowBindingCommitment(second),
+  );
+  expect(clientWorkflowBindingCommitment(first)).not.toEqual(
+    clientWorkflowBindingCommitment(
+      value({
+        terminalResultAuthority: {
+          ...first.terminalResultAuthority,
+          version: "sharp.analysis-result.v2",
+        },
+      }),
+    ),
+  );
+});
+
+function value(
+  patch: Partial<ModuleClientAgentWorkflowArtifactProjectBinding> = {},
+): ModuleClientAgentWorkflowArtifactProjectBinding {
+  return {
+    workflowKey: "analysis.cross-case.full-review",
+    nodeId: "page-agent-artifact",
+    operationKey: "analysis.cross-case.page-agent",
+    releaseDigest: `sha256:${"d".repeat(64)}`,
+    scopeContainmentContractVersion: 1,
+    terminalResultAuthority: {
+      version: "sharp.analysis-result.v1",
+      digest: `sha256:${"e".repeat(64)}`,
+      async canonicalize({ proposedResult }) {
+        return proposedResult;
+      },
+    },
+    clientTaskAuthority: {
+      version: "sharp.client-task.v1",
+      digest: `sha256:${"f".repeat(64)}`,
+      async build({ workflowInput }) {
+        return { taskKey: "sharp.full-review", input: workflowInput };
+      },
+    },
+    launchAuthority: {
+      version: "sharp.workflow-launch.v1",
+      digest: `sha256:${"a".repeat(64)}`,
+      async authorizeRelease() {},
+      async authorizeRun({ actorId }) {
+        return {
+          authorizationScope: {
+            tenantId: "single-tenant",
+            actorId,
+            grants: [{ scope: "self" }],
+            roleIds: ["role-analyst"],
+          },
+        };
+      },
+    },
+    artifact: {
+      kind: "analysis-report",
+      contentType: "application/json",
+      filename: "analysis.json",
+      retentionPolicyKey: "analysis.case-artifact",
+      maxByteSize: 4 * 1024 * 1024,
+    },
+    ...patch,
+  };
+}

package/template/apps/server/src/agent/client-workflow-artifact/binding-registry.ts

@@ -0,0 +1,153 @@
+import {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS as limits,
+  CLIENT_AGENT_WORKFLOW_SCOPE_CONTAINMENT_CONTRACT_VERSION,
+} from "@southwind-ai/server-sdk";
+import { validDigest } from "../client-session/digest.js";
+import type { ClientAgentWorkflowArtifactBinding } from "./contracts.js";
+
+export class ClientAgentWorkflowArtifactBindingRegistry {
+  readonly #bindings: ReadonlyMap<string, ClientAgentWorkflowArtifactBinding>;
+
+  constructor(bindings: readonly ClientAgentWorkflowArtifactBinding[]) {
+    const values = new Map<string, ClientAgentWorkflowArtifactBinding>();
+    const workflowKeys = new Set<string>();
+    for (const binding of bindings) {
+      assertBinding(binding);
+      const key = coordinate(binding.workflowKey, binding.nodeId);
+      if (values.has(key) || workflowKeys.has(binding.workflowKey)) {
+        throw new Error("CLIENT_AGENT_WORKFLOW_BINDING_DUPLICATE");
+      }
+      workflowKeys.add(binding.workflowKey);
+      values.set(key, freezeBinding(binding));
+    }
+    this.#bindings = values;
+  }
+
+  require(workflowKey: string, nodeId: string) {
+    const binding = this.#bindings.get(coordinate(workflowKey, nodeId));
+    if (!binding) throw new Error("CLIENT_AGENT_WORKFLOW_BINDING_MISSING");
+    return binding;
+  }
+
+  findWorkflow(workflowKey: string) {
+    return [...this.#bindings.values()].find(
+      (binding) => binding.workflowKey === workflowKey,
+    );
+  }
+
+  get size() {
+    return this.#bindings.size;
+  }
+}
+
+function coordinate(workflowKey: string, nodeId: string) {
+  return `${workflowKey}\0${nodeId}`;
+}
+
+function assertBinding(binding: ClientAgentWorkflowArtifactBinding) {
+  if (
+    !bounded(binding.workflowKey, limits.workflowKey) ||
+    !bounded(binding.nodeId, limits.nodeId) ||
+    !bounded(binding.operationKey, limits.operationKey) ||
+    !bounded(binding.releaseDigest, limits.releaseDigest) ||
+    !validDigest(binding.releaseDigest) ||
+    binding.scopeContainmentContractVersion !==
+      CLIENT_AGENT_WORKFLOW_SCOPE_CONTAINMENT_CONTRACT_VERSION ||
+    !bounded(
+      binding.terminalResultAuthority.version,
+      limits.terminalAuthorityVersion,
+    ) ||
+    !bounded(
+      binding.terminalResultAuthority.digest,
+      limits.terminalAuthorityDigest,
+    ) ||
+    !validDigest(binding.terminalResultAuthority.digest) ||
+    typeof binding.terminalResultAuthority.canonicalize !== "function" ||
+    !bounded(
+      binding.clientTaskAuthority.version,
+      limits.terminalAuthorityVersion,
+    ) ||
+    !bounded(
+      binding.clientTaskAuthority.digest,
+      limits.terminalAuthorityDigest,
+    ) ||
+    !validDigest(binding.clientTaskAuthority.digest) ||
+    typeof binding.clientTaskAuthority.build !== "function" ||
+    !bounded(
+      binding.launchAuthority.version,
+      limits.terminalAuthorityVersion,
+    ) ||
+    !bounded(binding.launchAuthority.digest, limits.terminalAuthorityDigest) ||
+    !validDigest(binding.launchAuthority.digest) ||
+    typeof binding.launchAuthority.authorizeRelease !== "function" ||
+    typeof binding.launchAuthority.authorizeRun !== "function" ||
+    !bounded(binding.artifact.kind, limits.artifactKind) ||
+    !bounded(binding.artifact.contentType, limits.artifactContentType) ||
+    !bounded(binding.artifact.filename, limits.artifactFilename) ||
+    binding.artifact.filename.includes("/") ||
+    binding.artifact.filename.includes("\\") ||
+    !bounded(binding.artifact.retentionPolicyKey, limits.retentionPolicyKey) ||
+    binding.artifact.contentType !== "application/json" ||
+    !Number.isSafeInteger(binding.artifact.maxByteSize) ||
+    binding.artifact.maxByteSize < 1 ||
+    binding.artifact.maxByteSize > limits.maxByteSize
+  ) {
+    throw new Error("CLIENT_AGENT_WORKFLOW_BINDING_INVALID");
+  }
+}
+
+export function clientWorkflowBindingCommitment(
+  binding: ClientAgentWorkflowArtifactBinding,
+) {
+  return {
+    workflowKey: binding.workflowKey,
+    nodeId: binding.nodeId,
+    operationKey: binding.operationKey,
+    releaseDigest: binding.releaseDigest,
+    scopeContainmentContractVersion: binding.scopeContainmentContractVersion,
+    terminalResultAuthority: {
+      version: binding.terminalResultAuthority.version,
+      digest: binding.terminalResultAuthority.digest,
+    },
+    clientTaskAuthority: {
+      version: binding.clientTaskAuthority.version,
+      digest: binding.clientTaskAuthority.digest,
+    },
+    launchAuthority: {
+      version: binding.launchAuthority.version,
+      digest: binding.launchAuthority.digest,
+    },
+    artifact: { ...binding.artifact },
+  } as const;
+}
+
+function freezeBinding(
+  binding: ClientAgentWorkflowArtifactBinding,
+): ClientAgentWorkflowArtifactBinding {
+  return Object.freeze({
+    ...clientWorkflowBindingCommitment(binding),
+    terminalResultAuthority: Object.freeze({
+      ...clientWorkflowBindingCommitment(binding).terminalResultAuthority,
+      canonicalize: binding.terminalResultAuthority.canonicalize,
+    }),
+    clientTaskAuthority: Object.freeze({
+      ...clientWorkflowBindingCommitment(binding).clientTaskAuthority,
+      build: binding.clientTaskAuthority.build,
+    }),
+    launchAuthority: Object.freeze({
+      ...clientWorkflowBindingCommitment(binding).launchAuthority,
+      authorizeRelease: binding.launchAuthority.authorizeRelease,
+      authorizeRun: binding.launchAuthority.authorizeRun,
+    }),
+    artifact: Object.freeze({ ...binding.artifact }),
+  });
+}
+
+function bounded(value: string, maxLength: number) {
+  return (
+    value.length > 0 &&
+    value.length <= maxLength &&
+    value === value.trim() &&
+    !value.includes(String.fromCharCode(0))
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/bootstrap.ts

@@ -0,0 +1,77 @@
+import type { ModuleClientAgentWorkflowArtifactProjectBinding } from "@southwind-ai/server-sdk";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RouteApp } from "../../system/routes.js";
+import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { BlobStore } from "@southwind-ai/storage";
+import type { StaticRouteAuthorizer } from "../../module-host/static-route-authorization.js";
+import { createManifestAuthorizedRouteApp } from "../../module-host/static-route-authorization.js";
+import type { DurableJobService } from "../../jobs/service.js";
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import { DrizzleAgentWorkflowRepository } from "../../agent-workflow/drizzle-repository.js";
+import { ClientAgentWorkflowArtifactBindingRegistry } from "./binding-registry.js";
+import { DrizzleClientAgentWorkflowArtifactRepository } from "./drizzle-repository.js";
+import { registerClientAgentWorkflowArtifactHandler } from "./handler.js";
+import { registerClientAgentWorkflowArtifactRoutes } from "./routes.js";
+import { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import { ClientAgentWorkflowArtifactSourceAccess } from "./source-access.js";
+import { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+
+export function createClientAgentWorkflowArtifactRuntime(input: {
+  readonly db?: NodePgDatabase;
+  readonly hostApp?: RouteApp;
+  readonly routeAuthorizer: StaticRouteAuthorizer;
+  readonly bindings?: readonly ModuleClientAgentWorkflowArtifactProjectBinding[];
+  readonly sessions?: GovernedClientAgentSessionService;
+  readonly sessionRepository?: ClientSessionRepository;
+  readonly jobs: DurableJobService;
+  readonly jobRegistry: DurableHandlerRegistry;
+  readonly blobs: BlobStore;
+}) {
+  if (
+    !input.db ||
+    !input.hostApp ||
+    !input.sessions ||
+    !input.sessionRepository ||
+    !input.bindings?.length
+  ) {
+    return undefined;
+  }
+  const bindings = new ClientAgentWorkflowArtifactBindingRegistry(
+    input.bindings,
+  );
+  const repository = new DrizzleClientAgentWorkflowArtifactRepository(input.db);
+  const loader = new ClientAgentWorkflowFactsLoader(
+    new DrizzleAgentWorkflowRepository(input.db),
+    input.jobs,
+    bindings,
+  );
+  const tasks = new ClientAgentWorkflowTaskAuthority();
+  const service = new GovernedClientAgentWorkflowArtifactService(
+    repository,
+    loader,
+    input.sessions,
+    input.sessionRepository,
+    input.blobs,
+    tasks,
+  );
+  registerClientAgentWorkflowArtifactHandler({
+    registry: input.jobRegistry,
+    service,
+  });
+  registerClientAgentWorkflowArtifactRoutes(
+    createManifestAuthorizedRouteApp(input.hostApp, input.routeAuthorizer),
+    service,
+  );
+  return {
+    service,
+    sourceAccess: new ClientAgentWorkflowArtifactSourceAccess(
+      repository,
+      input.jobs,
+    ),
+    bindTaskArtifacts: (
+      artifacts: import("../../agent-workflow/node-execution-ports.js").AgentWorkflowArtifactPort,
+    ) => tasks.bind(artifacts),
+  };
+}

package/template/apps/server/src/agent/client-workflow-artifact/cancellation.ts

@@ -0,0 +1,47 @@
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import { clientWorkflowSessionCall } from "./session-boundary.js";
+
+export async function cancelClientWorkflowArtifact(input: {
+  record: ClientAgentWorkflowArtifactRecord;
+  repository: ClientAgentWorkflowArtifactRepository;
+  sessions: GovernedClientAgentSessionService;
+  cause: string;
+  now: number;
+}) {
+  const requested = await input.repository.requestCancel({
+    workId: input.record.workId,
+    now: input.now,
+  });
+  if (!requested || requested.status === "completed") return undefined;
+  if (requested.status === "cancelled") return requested;
+  if (requested.clientSessionId) {
+    await clientWorkflowSessionCall(
+      input.sessions.revokeSession(requested.clientSessionId, input.cause),
+      "revoke",
+    );
+  }
+  return input.repository.finalizeCancel({
+    workId: requested.workId,
+    now: input.now,
+  });
+}
+
+export async function recoverClientWorkflowCancellations(input: {
+  repository: ClientAgentWorkflowArtifactRepository;
+  sessions: GovernedClientAgentSessionService;
+  now: () => number;
+}) {
+  const records = await input.repository.listCancellationRequested();
+  for (const record of records) {
+    await cancelClientWorkflowArtifact({
+      record,
+      repository: input.repository,
+      sessions: input.sessions,
+      cause: "workflow-cancel-recovery",
+      now: input.now(),
+    });
+  }
+  return records.length;
+}

package/template/apps/server/src/agent/client-workflow-artifact/completed-recovery.ts

@@ -0,0 +1,31 @@
+import type { BlobStore } from "@southwind-ai/storage";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import { workflowArtifactConflict as conflict } from "./service-support.js";
+import { sealCompletedClientWorkflowSession } from "./terminal-seal.js";
+import type { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+
+export async function recoverCompletedClientWorkflowArtifact(input: {
+  current: ClientAgentWorkflowArtifactRecord;
+  signal: AbortSignal;
+  sessionRepository: ClientSessionRepository;
+  repository: ClientAgentWorkflowArtifactRepository;
+  loader: ClientAgentWorkflowFactsLoader;
+  blobs: BlobStore;
+  now: () => number;
+}) {
+  const { current } = input;
+  if (current.status !== "claimed" || !current.clientSessionId) return current;
+  const session = await input.sessionRepository.find(current.clientSessionId);
+  if (!session || session.status !== "completed") return current;
+  if (!session.terminalDigest || !current.claimTokenHash) {
+    throw conflict("已完成 Client Agent Session 缺少稳定终态摘要");
+  }
+  return sealCompletedClientWorkflowSession({
+    ...input,
+    session,
+    terminalRequestDigest: session.terminalDigest,
+    claimTokenHash: current.claimTokenHash,
+  });
+}

package/template/apps/server/src/agent/client-workflow-artifact/contracts.ts

@@ -0,0 +1,104 @@
+import type {
+  ModuleAiJsonValue,
+  ModuleClientAgentWorkflowArtifactProjectBinding,
+  ModuleClientAgentWorkflowExecutionTask,
+} from "@southwind-ai/server-sdk";
+import type { ArtifactRef } from "@southwind-ai/storage";
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+
+export const clientAgentWorkflowArtifactTaskKey =
+  "system.agent-workflow.client-agent-artifact";
+export const clientAgentWorkflowArtifactSourceModule = "system.agent-workflow";
+export const clientAgentWorkflowArtifactSourceKind = "client-agent-artifact";
+
+export type ClientAgentWorkflowArtifactBinding =
+  ModuleClientAgentWorkflowArtifactProjectBinding;
+
+export type ClientAgentWorkflowArtifactStatus =
+  | "pending"
+  | "claimed"
+  | "cancellation-requested"
+  | "completed"
+  | "cancelled";
+
+export interface ClientAgentWorkflowArtifactRecord {
+  readonly workId: string;
+  readonly commandId: string;
+  readonly durableJobId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: "job";
+  readonly taskKey: typeof clientAgentWorkflowArtifactTaskKey;
+  readonly operationKey: string;
+  readonly bindingDigest: `sha256:${string}`;
+  readonly actorId: string;
+  readonly scopeDigest: `sha256:${string}`;
+  readonly authorizationSnapshotDigest: `sha256:${string}`;
+  readonly runPolicyDigest: `sha256:${string}`;
+  readonly requestDigest: `sha256:${string}`;
+  readonly inputDigest: `sha256:${string}`;
+  readonly effectGeneration: number;
+  readonly effectFenceTokenDigest: `sha256:${string}`;
+  readonly status: ClientAgentWorkflowArtifactStatus;
+  readonly claimGeneration: number;
+  readonly clientBindingDigest?: `sha256:${string}`;
+  readonly installationId?: string;
+  readonly hostSessionDigest?: `sha256:${string}`;
+  readonly clientSessionId?: string;
+  readonly claimTokenHash?: `sha256:${string}`;
+  readonly claimExpiresAt?: number;
+  readonly historySequence: number;
+  readonly historyHeadDigest?: `sha256:${string}`;
+  readonly terminalReceiptId?: string;
+  readonly terminalReceiptDigest?: `sha256:${string}`;
+  readonly terminalRequestDigest?: `sha256:${string}`;
+  readonly terminalResult?: Readonly<Record<string, unknown>>;
+  readonly artifact?: ClientAgentWorkflowStoredArtifact;
+  readonly cancelRequestedAt?: number;
+  readonly finishedAt?: number;
+  readonly version: number;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export interface ClientAgentWorkflowStoredArtifact {
+  readonly artifactRef: ArtifactRef;
+  readonly filename: string;
+  readonly contentType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface ClientAgentWorkflowBeginFacts {
+  readonly record: ClientAgentWorkflowArtifactRecord;
+  readonly input: ModuleAiJsonValue;
+  readonly binding: ClientAgentWorkflowArtifactBinding;
+  /** Immutable authorization captured by the real Durable Job at Run launch. */
+  readonly frozenScope: AuthorizationScopeSnapshot;
+  readonly inputArtifacts: readonly import("@southwind-ai/shared").AgentWorkflowArtifactRef[];
+}
+
+export type ClientAgentWorkflowExecutionTask =
+  ModuleClientAgentWorkflowExecutionTask;
+
+export interface ClientAgentWorkflowClaimBinding {
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly installationId: string;
+  readonly hostSessionDigest: `sha256:${string}`;
+  readonly claimTokenHash: `sha256:${string}`;
+  readonly claimExpiresAt: number;
+  readonly now: number;
+}
+
+export interface ClientAgentWorkflowTerminalInput {
+  readonly claimGeneration: number;
+  readonly clientSessionId: string;
+  readonly historySequence: number;
+  readonly historyHeadDigest: `sha256:${string}`;
+  readonly terminalReceiptId: string;
+  readonly terminalReceiptDigest: `sha256:${string}`;
+  readonly terminalRequestDigest: `sha256:${string}`;
+  readonly terminalResult: Readonly<Record<string, unknown>>;
+  readonly artifact: ClientAgentWorkflowStoredArtifact;
+  readonly now: number;
+}

package/template/apps/server/src/agent/client-workflow-artifact/drizzle-locks.ts

@@ -0,0 +1,30 @@
+import { clientAgentWorkflowArtifacts } from "@southwind-ai/database";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { toClientWorkflowArtifact } from "./drizzle-mapper.js";
+
+export async function lockClientWorkflowArtifact(
+  db: NodePgDatabase,
+  workId: string,
+) {
+  const [row] = await db
+    .select()
+    .from(clientAgentWorkflowArtifacts)
+    .where(eq(clientAgentWorkflowArtifacts.workId, workId))
+    .for("update")
+    .limit(1);
+  return row ? toClientWorkflowArtifact(row) : undefined;
+}
+
+export async function lockClientWorkflowArtifactBySession(
+  db: NodePgDatabase,
+  clientSessionId: string,
+) {
+  const [row] = await db
+    .select()
+    .from(clientAgentWorkflowArtifacts)
+    .where(eq(clientAgentWorkflowArtifacts.clientSessionId, clientSessionId))
+    .for("update")
+    .limit(1);
+  return row ? toClientWorkflowArtifact(row) : undefined;
+}