create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,138 @@
+import { clientAgentWorkflowArtifacts } from "@southwind-ai/database";
+import type { ArtifactRef } from "@southwind-ai/storage";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+
+type Row = typeof clientAgentWorkflowArtifacts.$inferSelect;
+
+export function clientWorkflowArtifactRow(
+  value: ClientAgentWorkflowArtifactRecord,
+): typeof clientAgentWorkflowArtifacts.$inferInsert {
+  return {
+    workId: value.workId,
+    commandId: value.commandId,
+    durableJobId: value.durableJobId,
+    runId: value.runId,
+    nodeRunId: value.nodeRunId,
+    effectKind: value.effectKind,
+    taskKey: value.taskKey,
+    operationKey: value.operationKey,
+    bindingDigest: value.bindingDigest,
+    actorId: value.actorId,
+    scopeDigest: value.scopeDigest,
+    authorizationSnapshotDigest: value.authorizationSnapshotDigest,
+    runPolicyDigest: value.runPolicyDigest,
+    requestDigest: value.requestDigest,
+    inputDigest: value.inputDigest,
+    effectGeneration: value.effectGeneration,
+    effectFenceTokenDigest: value.effectFenceTokenDigest,
+    status: value.status,
+    claimGeneration: value.claimGeneration,
+    clientBindingDigest: value.clientBindingDigest ?? null,
+    installationId: value.installationId ?? null,
+    hostSessionDigest: value.hostSessionDigest ?? null,
+    clientSessionId: value.clientSessionId ?? null,
+    claimTokenHash: value.claimTokenHash ?? null,
+    claimExpiresAt: value.claimExpiresAt ?? null,
+    historySequence: value.historySequence,
+    historyHeadDigest: value.historyHeadDigest ?? null,
+    terminalReceiptId: value.terminalReceiptId ?? null,
+    terminalReceiptDigest: value.terminalReceiptDigest ?? null,
+    terminalRequestDigest: value.terminalRequestDigest ?? null,
+    terminalResultJson: value.terminalResult ?? null,
+    artifactRef: value.artifact?.artifactRef ?? null,
+    artifactFilename: value.artifact?.filename ?? null,
+    artifactContentType: value.artifact?.contentType ?? null,
+    artifactByteSize: value.artifact?.byteSize ?? null,
+    artifactSha256: value.artifact?.sha256 ?? null,
+    cancelRequestedAt: value.cancelRequestedAt ?? null,
+    finishedAt: value.finishedAt ?? null,
+    version: value.version,
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+  };
+}
+
+export function toClientWorkflowArtifact(
+  row: Row,
+): ClientAgentWorkflowArtifactRecord {
+  const artifact =
+    row.artifactRef &&
+    row.artifactFilename &&
+    row.artifactContentType &&
+    row.artifactByteSize !== null &&
+    row.artifactSha256
+      ? {
+          artifactRef: row.artifactRef as ArtifactRef,
+          filename: row.artifactFilename,
+          contentType: row.artifactContentType,
+          byteSize: row.artifactByteSize,
+          sha256: row.artifactSha256,
+        }
+      : undefined;
+  return {
+    workId: row.workId,
+    commandId: row.commandId,
+    durableJobId: row.durableJobId,
+    runId: row.runId,
+    nodeRunId: row.nodeRunId,
+    effectKind: row.effectKind as "job",
+    taskKey: row.taskKey as ClientAgentWorkflowArtifactRecord["taskKey"],
+    operationKey: row.operationKey,
+    bindingDigest: row.bindingDigest as `sha256:${string}`,
+    actorId: row.actorId,
+    scopeDigest: row.scopeDigest as `sha256:${string}`,
+    authorizationSnapshotDigest:
+      row.authorizationSnapshotDigest as `sha256:${string}`,
+    runPolicyDigest: row.runPolicyDigest as `sha256:${string}`,
+    requestDigest: row.requestDigest as `sha256:${string}`,
+    inputDigest: row.inputDigest as `sha256:${string}`,
+    effectGeneration: row.effectGeneration,
+    effectFenceTokenDigest: row.effectFenceTokenDigest as `sha256:${string}`,
+    status: row.status,
+    claimGeneration: row.claimGeneration,
+    ...(row.clientBindingDigest
+      ? {
+          clientBindingDigest: row.clientBindingDigest as `sha256:${string}`,
+        }
+      : {}),
+    ...(row.installationId ? { installationId: row.installationId } : {}),
+    ...(row.hostSessionDigest
+      ? { hostSessionDigest: row.hostSessionDigest as `sha256:${string}` }
+      : {}),
+    ...(row.clientSessionId ? { clientSessionId: row.clientSessionId } : {}),
+    ...(row.claimTokenHash
+      ? { claimTokenHash: row.claimTokenHash as `sha256:${string}` }
+      : {}),
+    ...(row.claimExpiresAt ? { claimExpiresAt: row.claimExpiresAt } : {}),
+    historySequence: row.historySequence,
+    ...(row.historyHeadDigest
+      ? { historyHeadDigest: row.historyHeadDigest as `sha256:${string}` }
+      : {}),
+    ...(row.terminalReceiptId
+      ? { terminalReceiptId: row.terminalReceiptId }
+      : {}),
+    ...(row.terminalReceiptDigest
+      ? {
+          terminalReceiptDigest:
+            row.terminalReceiptDigest as `sha256:${string}`,
+        }
+      : {}),
+    ...(row.terminalRequestDigest
+      ? {
+          terminalRequestDigest:
+            row.terminalRequestDigest as `sha256:${string}`,
+        }
+      : {}),
+    ...(row.terminalResultJson
+      ? { terminalResult: row.terminalResultJson }
+      : {}),
+    ...(artifact ? { artifact } : {}),
+    ...(row.cancelRequestedAt
+      ? { cancelRequestedAt: row.cancelRequestedAt }
+      : {}),
+    ...(row.finishedAt ? { finishedAt: row.finishedAt } : {}),
+    version: row.version,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

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

@@ -0,0 +1,346 @@
+import { clientAgentWorkflowArtifacts } from "@southwind-ai/database";
+import { and, desc, eq, inArray, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ArtifactRef } from "@southwind-ai/storage";
+import type {
+  ClientAgentWorkflowArtifactRecord,
+  ClientAgentWorkflowClaimBinding,
+} from "./contracts.js";
+import {
+  clientWorkflowArtifactRow,
+  toClientWorkflowArtifact,
+} from "./drizzle-mapper.js";
+import {
+  type ClientAgentWorkflowArtifactRepository,
+  sameWorkflowArtifactIdentity,
+} from "./repository.js";
+import { clientWorkflowAuthorityCurrent } from "./authority-current.js";
+import {
+  lockClientWorkflowArtifact as locked,
+  lockClientWorkflowArtifactBySession as lockedByClientSession,
+} from "./drizzle-locks.js";
+
+export class DrizzleClientAgentWorkflowArtifactRepository implements ClientAgentWorkflowArtifactRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  begin(record: ClientAgentWorkflowArtifactRecord) {
+    return this.db.transaction(async (tx) => {
+      const replay = await locked(tx, record.workId);
+      if (!(await clientWorkflowAuthorityCurrent(tx, record, Date.now()))) {
+        throw new Error("CLIENT_AGENT_WORKFLOW_AUTHORITY_STALE");
+      }
+      if (replay) {
+        if (!sameWorkflowArtifactIdentity(replay, record)) {
+          throw new Error("CLIENT_AGENT_WORKFLOW_IDENTITY_CONFLICT");
+        }
+        return replay;
+      }
+      await tx
+        .insert(clientAgentWorkflowArtifacts)
+        .values(clientWorkflowArtifactRow(record))
+        .onConflictDoNothing({
+          target: clientAgentWorkflowArtifacts.commandId,
+        });
+      const existing = await locked(tx, record.workId);
+      if (!existing || !sameWorkflowArtifactIdentity(existing, record)) {
+        throw new Error("CLIENT_AGENT_WORKFLOW_IDENTITY_CONFLICT");
+      }
+      return existing;
+    });
+  }
+
+  find(workId: string) {
+    return this.findWhere(eq(clientAgentWorkflowArtifacts.workId, workId));
+  }
+
+  findByJob(durableJobId: string) {
+    return this.findWhere(
+      eq(clientAgentWorkflowArtifacts.durableJobId, durableJobId),
+    );
+  }
+
+  authorizeClientSessionAttempt(
+    input: Parameters<
+      ClientAgentWorkflowArtifactRepository["authorizeClientSessionAttempt"]
+    >[0],
+  ) {
+    return this.db.transaction((tx) =>
+      this.authorizeClientSessionAttemptInTransaction(
+        tx as unknown as NodePgDatabase,
+        input,
+      ),
+    );
+  }
+
+  async authorizeClientSessionAttemptInTransaction(
+    transaction: NodePgDatabase,
+    input: Parameters<
+      ClientAgentWorkflowArtifactRepository["authorizeClientSessionAttempt"]
+    >[0],
+  ) {
+    const current = await lockedByClientSession(
+      transaction,
+      input.clientSessionId,
+    );
+    if (!current) return "ordinary" as const;
+    if (
+      current.status !== "claimed" ||
+      !current.claimExpiresAt ||
+      current.claimExpiresAt <= input.now ||
+      current.actorId !== input.actorId ||
+      current.operationKey !== input.operationKey ||
+      current.clientBindingDigest !== input.clientBindingDigest ||
+      current.hostSessionDigest !== input.hostSessionDigest ||
+      !(await clientWorkflowAuthorityCurrent(transaction, current, input.now))
+    ) {
+      return "revoked" as const;
+    }
+    return "current" as const;
+  }
+
+  findForActorRun(input: { actorId: string; runId: string }) {
+    return this.findWhere(
+      and(
+        eq(clientAgentWorkflowArtifacts.actorId, input.actorId),
+        eq(clientAgentWorkflowArtifacts.runId, input.runId),
+      )!,
+    );
+  }
+
+  claim(input: {
+    workId: string;
+    expectedVersion: number;
+    allowActiveTakeover?: boolean;
+    binding: ClientAgentWorkflowClaimBinding;
+  }) {
+    return this.db.transaction(async (tx) => {
+      const current = await locked(tx, input.workId);
+      if (!current || current.version !== input.expectedVersion) {
+        return { outcome: "conflict" as const };
+      }
+      if (current.status === "completed" || current.status === "cancelled") {
+        return { outcome: current.status, record: current } as const;
+      }
+      if (
+        !(await clientWorkflowAuthorityCurrent(tx, current, input.binding.now))
+      ) {
+        return { outcome: "conflict" as const };
+      }
+      if (
+        current.status !== "pending" &&
+        (current.status !== "claimed" || !input.allowActiveTakeover)
+      ) {
+        return { outcome: "busy" as const, record: current };
+      }
+      const previousClientSessionId = current.clientSessionId;
+      const [row] = await tx
+        .update(clientAgentWorkflowArtifacts)
+        .set({
+          status: "claimed",
+          claimGeneration: current.claimGeneration + 1,
+          clientBindingDigest: input.binding.clientBindingDigest,
+          installationId: input.binding.installationId,
+          hostSessionDigest: input.binding.hostSessionDigest,
+          clientSessionId: null,
+          claimTokenHash: input.binding.claimTokenHash,
+          claimExpiresAt: input.binding.claimExpiresAt,
+          updatedAt: input.binding.now,
+          version: current.version + 1,
+        })
+        .where(
+          and(
+            eq(clientAgentWorkflowArtifacts.workId, current.workId),
+            eq(clientAgentWorkflowArtifacts.version, current.version),
+          ),
+        )
+        .returning();
+      if (!row) return { outcome: "conflict" as const };
+      return {
+        outcome: "claimed" as const,
+        record: toClientWorkflowArtifact(row),
+        ...(previousClientSessionId ? { previousClientSessionId } : {}),
+      };
+    });
+  }
+
+  async bindClientSession(input: {
+    workId: string;
+    claimGeneration: number;
+    clientSessionId: string;
+    now: number;
+  }) {
+    const [row] = await this.db
+      .update(clientAgentWorkflowArtifacts)
+      .set({
+        clientSessionId: input.clientSessionId,
+        updatedAt: input.now,
+        version: sql`${clientAgentWorkflowArtifacts.version} + 1`,
+      })
+      .where(
+        and(
+          eq(clientAgentWorkflowArtifacts.workId, input.workId),
+          eq(clientAgentWorkflowArtifacts.status, "claimed"),
+          eq(
+            clientAgentWorkflowArtifacts.claimGeneration,
+            input.claimGeneration,
+          ),
+          sql`${clientAgentWorkflowArtifacts.clientSessionId} is null`,
+        ),
+      )
+      .returning();
+    return row ? toClientWorkflowArtifact(row) : undefined;
+  }
+
+  complete(
+    input: Parameters<ClientAgentWorkflowArtifactRepository["complete"]>[0],
+  ) {
+    return this.db.transaction(async (tx) => {
+      const current = await locked(tx, input.workId);
+      if (
+        !current ||
+        current.status !== "claimed" ||
+        current.claimGeneration !== input.terminal.claimGeneration ||
+        current.clientSessionId !== input.terminal.clientSessionId ||
+        current.claimTokenHash !== input.claimTokenHash
+      ) {
+        return undefined;
+      }
+      if (
+        !(await clientWorkflowAuthorityCurrent(tx, current, input.terminal.now))
+      ) {
+        return undefined;
+      }
+      const [row] = await tx
+        .update(clientAgentWorkflowArtifacts)
+        .set({
+          status: "completed",
+          historySequence: input.terminal.historySequence,
+          historyHeadDigest: input.terminal.historyHeadDigest,
+          terminalReceiptId: input.terminal.terminalReceiptId,
+          terminalReceiptDigest: input.terminal.terminalReceiptDigest,
+          terminalRequestDigest: input.terminal.terminalRequestDigest,
+          terminalResultJson: input.terminal.terminalResult,
+          artifactRef: input.terminal.artifact.artifactRef,
+          artifactFilename: input.terminal.artifact.filename,
+          artifactContentType: input.terminal.artifact.contentType,
+          artifactByteSize: input.terminal.artifact.byteSize,
+          artifactSha256: input.terminal.artifact.sha256,
+          finishedAt: input.terminal.now,
+          updatedAt: input.terminal.now,
+          version: current.version + 1,
+        })
+        .where(
+          and(
+            eq(clientAgentWorkflowArtifacts.workId, current.workId),
+            eq(clientAgentWorkflowArtifacts.version, current.version),
+          ),
+        )
+        .returning();
+      return row ? toClientWorkflowArtifact(row) : undefined;
+    });
+  }
+
+  async requestCancel(input: { workId: string; now: number }) {
+    return this.db.transaction(async (tx) => {
+      const current = await locked(tx, input.workId);
+      if (!current) return undefined;
+      if (current.status === "cancelled") return current;
+      if (current.status === "completed") return undefined;
+      if (current.status === "cancellation-requested") return current;
+      const [row] = await tx
+        .update(clientAgentWorkflowArtifacts)
+        .set({
+          status: "cancellation-requested",
+          cancelRequestedAt: input.now,
+          updatedAt: input.now,
+          version: current.version + 1,
+        })
+        .where(
+          and(
+            eq(clientAgentWorkflowArtifacts.workId, current.workId),
+            eq(clientAgentWorkflowArtifacts.version, current.version),
+          ),
+        )
+        .returning();
+      return row ? toClientWorkflowArtifact(row) : undefined;
+    });
+  }
+
+  async finalizeCancel(input: { workId: string; now: number }) {
+    return this.db.transaction(async (tx) => {
+      const current = await locked(tx, input.workId);
+      if (!current) return undefined;
+      if (current.status === "cancelled") return current;
+      if (current.status !== "cancellation-requested") return undefined;
+      const [row] = await tx
+        .update(clientAgentWorkflowArtifacts)
+        .set({
+          status: "cancelled",
+          finishedAt: input.now,
+          updatedAt: input.now,
+          version: current.version + 1,
+        })
+        .where(
+          and(
+            eq(clientAgentWorkflowArtifacts.workId, current.workId),
+            eq(clientAgentWorkflowArtifacts.version, current.version),
+          ),
+        )
+        .returning();
+      return row ? toClientWorkflowArtifact(row) : undefined;
+    });
+  }
+
+  async listClaimedByHost(input: {
+    actorId: string;
+    hostSessionDigest: `sha256:${string}`;
+  }) {
+    const rows = await this.db
+      .select()
+      .from(clientAgentWorkflowArtifacts)
+      .where(
+        and(
+          eq(clientAgentWorkflowArtifacts.actorId, input.actorId),
+          eq(
+            clientAgentWorkflowArtifacts.hostSessionDigest,
+            input.hostSessionDigest,
+          ),
+          inArray(clientAgentWorkflowArtifacts.status, [
+            "claimed",
+            "cancellation-requested",
+          ]),
+        ),
+      )
+      .orderBy(desc(clientAgentWorkflowArtifacts.updatedAt));
+    return rows.map(toClientWorkflowArtifact);
+  }
+
+  async listActiveArtifactRefs(_now: Date): Promise<ArtifactRef[]> {
+    const rows = await this.db
+      .select({ artifactRef: clientAgentWorkflowArtifacts.artifactRef })
+      .from(clientAgentWorkflowArtifacts)
+      .where(eq(clientAgentWorkflowArtifacts.status, "completed"));
+    return rows.flatMap(({ artifactRef: ref }) =>
+      ref ? [ref as ArtifactRef] : [],
+    );
+  }
+
+  async listCancellationRequested() {
+    const rows = await this.db
+      .select()
+      .from(clientAgentWorkflowArtifacts)
+      .where(eq(clientAgentWorkflowArtifacts.status, "cancellation-requested"))
+      .orderBy(desc(clientAgentWorkflowArtifacts.updatedAt));
+    return rows.map(toClientWorkflowArtifact);
+  }
+
+  private async findWhere(predicate: ReturnType<typeof eq>) {
+    const [row] = await this.db
+      .select()
+      .from(clientAgentWorkflowArtifacts)
+      .where(predicate)
+      .orderBy(desc(clientAgentWorkflowArtifacts.createdAt))
+      .limit(1);
+    return row ? toClientWorkflowArtifact(row) : undefined;
+  }
+}

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

@@ -0,0 +1,21 @@
+export type ClientAgentWorkflowArtifactErrorCode =
+  | "NOT_FOUND"
+  | "INVALID_INPUT"
+  | "CONFLICT"
+  | "FORBIDDEN"
+  | "CANCELLED"
+  | "RECEIPT_REJECTED"
+  | "ARTIFACT_TOO_LARGE"
+  | "ARTIFACT_STORE_UNAVAILABLE"
+  | "PROVIDER_FAILED";
+
+export class ClientAgentWorkflowArtifactError extends Error {
+  constructor(
+    readonly code: ClientAgentWorkflowArtifactErrorCode,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "ClientAgentWorkflowArtifactError";
+  }
+}

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

@@ -0,0 +1,167 @@
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+  type DurableHandlerRegistry,
+} from "@southwind-ai/jobs";
+import { CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY } from "@southwind-ai/server-sdk";
+import {
+  clientAgentWorkflowArtifactSourceKind,
+  clientAgentWorkflowArtifactSourceModule,
+  type ClientAgentWorkflowArtifactBinding,
+  type ClientAgentWorkflowArtifactRecord,
+} from "./contracts.js";
+import type { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import type { ClientAgentWorkflowJobPayload } from "./workflow-loader.js";
+import { GovernedClientAgentWorkflowArtifactJobPort } from "./job-port.js";
+
+export function registerClientAgentWorkflowArtifactHandler(input: {
+  registry: DurableHandlerRegistry;
+  service: GovernedClientAgentWorkflowArtifactService;
+}) {
+  input.registry.register({
+    key: CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY,
+    payload: { parse: parsePayload },
+    execute: (payload, context) => execute(input.service, payload, context),
+  });
+}
+
+async function execute(
+  service: GovernedClientAgentWorkflowArtifactService,
+  payload: ClientAgentWorkflowJobPayload,
+  context: DurableHandlerContext,
+) {
+  const begun = await service.begin({
+    jobId: context.jobId,
+    payload,
+    signal: context.signal,
+  });
+  const port = new GovernedClientAgentWorkflowArtifactJobPort(
+    service,
+    context.jobId,
+    begun.binding,
+    begun.record,
+    context.signal,
+  );
+  let view = await port.begin({ input: begun.input });
+  try {
+    while (!["completed", "cancelled"].includes(view.status)) {
+      await waitForChange(context.signal);
+      view = await port.claimOrAdvance(view.command);
+    }
+  } catch (error) {
+    await port.reconcileOrCancel(view.command);
+    throw error;
+  }
+  if (view.status === "cancelled") {
+    throw new DurableHandlerError(
+      "CLIENT_AGENT_WORKFLOW_CANCELLED",
+      "Client Agent Workflow 已取消",
+      false,
+    );
+  }
+  await publishStableArtifact(port.record, port.binding, context);
+}
+
+async function publishStableArtifact(
+  record: ClientAgentWorkflowArtifactRecord,
+  binding: ClientAgentWorkflowArtifactBinding,
+  context: DurableHandlerContext,
+) {
+  if (
+    !record.artifact ||
+    !record.terminalReceiptId ||
+    !record.terminalReceiptDigest ||
+    !record.historyHeadDigest ||
+    record.historySequence < 1
+  ) {
+    throw new DurableHandlerError(
+      "CLIENT_AGENT_WORKFLOW_RECEIPT_INVALID",
+      "Client Agent Workflow 终态回执不完整",
+      false,
+    );
+  }
+  if (!context.publishArtifactOnce) {
+    throw new DurableHandlerError(
+      "STABLE_ARTIFACT_PUBLICATION_UNAVAILABLE",
+      "稳定产物发布能力未装配",
+      false,
+    );
+  }
+  await context.publishArtifactOnce(record.terminalReceiptId, {
+    kind: binding.artifact.kind,
+    artifactRef: record.artifact.artifactRef,
+    filename: record.artifact.filename,
+    contentType: record.artifact.contentType,
+    byteSize: record.artifact.byteSize,
+    sha256: record.artifact.sha256,
+    ownerId: record.actorId,
+    metadata: {
+      retentionPolicyKey: binding.artifact.retentionPolicyKey,
+      sourceModuleKey: clientAgentWorkflowArtifactSourceModule,
+      sourceKind: clientAgentWorkflowArtifactSourceKind,
+      sourceId: record.workId,
+      sourceVersion: record.terminalReceiptId,
+      sourceSequence: record.historySequence,
+      sourceDigest: record.terminalReceiptDigest,
+      workflowClaimGeneration: record.claimGeneration,
+      historyHeadDigest: record.historyHeadDigest,
+    },
+  });
+}
+
+function parsePayload(value: unknown): ClientAgentWorkflowJobPayload {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidPayload();
+  }
+  const input = value as Record<string, unknown>;
+  const allowed = new Set([
+    "commandId",
+    "runId",
+    "nodeRunId",
+    "effectGeneration",
+    "requestDigest",
+  ]);
+  if (Object.keys(input).some((key) => !allowed.has(key))) {
+    throw invalidPayload();
+  }
+  const text = (key: string) => {
+    const current = input[key];
+    if (typeof current !== "string" || !current.trim()) throw invalidPayload();
+    return current;
+  };
+  const effectGeneration = input.effectGeneration;
+  if (!Number.isSafeInteger(effectGeneration) || Number(effectGeneration) < 1) {
+    throw invalidPayload();
+  }
+  return {
+    commandId: text("commandId"),
+    runId: text("runId"),
+    nodeRunId: text("nodeRunId"),
+    effectGeneration: Number(effectGeneration),
+    requestDigest: text("requestDigest"),
+  };
+}
+
+function waitForChange(signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) return reject(signal.reason);
+    const timeout = setTimeout(done, 500);
+    signal.addEventListener("abort", aborted, { once: true });
+    function done() {
+      signal.removeEventListener("abort", aborted);
+      resolve();
+    }
+    function aborted() {
+      clearTimeout(timeout);
+      reject(signal.reason);
+    }
+  });
+}
+
+function invalidPayload() {
+  return new DurableHandlerError(
+    "CLIENT_AGENT_WORKFLOW_PAYLOAD_INVALID",
+    "Client Agent Workflow 任务载荷无效",
+    false,
+  );
+}

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

@@ -0,0 +1,29 @@
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import { cancelClientWorkflowArtifact } from "./cancellation.js";
+
+export async function revokeClientWorkflowArtifactHost(input: {
+  records: readonly ClientAgentWorkflowArtifactRecord[];
+  repository: ClientAgentWorkflowArtifactRepository;
+  sessions: GovernedClientAgentSessionService;
+  now: () => number;
+}) {
+  const errors: unknown[] = [];
+  for (const record of input.records) {
+    try {
+      await cancelClientWorkflowArtifact({
+        record,
+        repository: input.repository,
+        sessions: input.sessions,
+        cause: "workflow-host-revoked",
+        now: input.now(),
+      });
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length)
+    throw new AggregateError(errors, "Workflow Host 撤销未完全收敛");
+  return input.records.length;
+}