@citeark/agent 0.3.20

package/src/compute/gcp-batch-compiler.mjs

@@ -0,0 +1,685 @@
+import { hasSessionEvents } from '../terminal/events.mjs';
+import { needsCompilerRepairGeneration } from "../research/compiler-repair.mjs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+import { restoreRunRecovery, saveRunRecovery, saveRemoteRecovery, restoreRemoteRecovery } from "./coordinator-recovery.mjs";
+import { GcpBatchClient } from "../gcp/batch-client.mjs";
+import { GoogleAccessTokenProvider } from "../gcp/auth.mjs";
+import { GcsStagingClient } from "../gcp/storage.mjs";
+import {
+  ensureFinalWorkspaceCapture,
+  updateRunState,
+} from "../job.mjs";
+import { captureProcess } from "../process.mjs";
+import { createRemoteStageArchive } from "./stage-archive.mjs";
+import {
+  acceptCompilerDraft,
+  compilerPrompt,
+  normalizeCompilationTask,
+  prepareCompilationBundle,
+} from "../research/compiler.mjs";
+import { researchCompilationFailure } from "../research/compiler-failure.mjs";
+import { agentInvocationPromptArgument, buildAgentInvocation } from "../runtime/index.mjs";
+import { publicAgentRuntime, resolveAgentRuntime } from "../runtime/config.mjs";
+import {
+  CODEX_FINAL_MESSAGE_PATH,
+  recoverJsonFromFinalMessage,
+} from "../runtime/final-output.mjs";
+import { readAgentUsage } from "../telemetry/usage.mjs";
+import {
+  CiteArkError,
+  createRunId,
+  pathExists,
+  readJson,
+  writeJson,
+} from "../util.mjs";
+import {
+  buildGcpBatchJob,
+  remoteProviderSession,
+  resolveCheckpointObjects,
+  resolveGcpBatchConfig,
+} from "./gcp-batch-job.mjs";
+import { assertSuccessfulGcpBatchTerminal } from "./gcp-batch-failure.mjs";
+import {
+  createLockedBatchJob,
+  deleteBatchJob,
+  releaseBatchJobAccountLock,
+} from "./gcp-batch-lifecycle.mjs";
+import {
+  classifyProviderActionRequired,
+  describeRemoteAgentFailure,
+} from "./remote-attempt.mjs";
+
+const COMPILER_ACTIVITY_WAITING_SECONDS = 2 * 60;
+
+export async function executeGcpBatchCompilation({
+  taskPath,
+  runsDirectory,
+  runId = createRunId(),
+  agentRuntime,
+  computeProfile,
+  executorOptions = {},
+  dryRun = false,
+  progress = () => {},
+  sourceReviewer,
+  prepareMarkdown,
+  validateResearch = async () => [],
+}) {
+  const absoluteTaskPath = path.resolve(taskPath);
+  const taskDirectory = path.dirname(absoluteTaskPath);
+  const task = normalizeCompilationTask(await readJson(absoluteTaskPath));
+  const runtimeAgent = resolveAgentRuntime({
+    taskAgent: task.agent,
+    ...agentRuntime,
+    requireApi: false,
+  });
+  assertCompilerProfile(computeProfile);
+  task.environment = {
+    ...task.environment,
+    image: computeProfile.image,
+    cpus: computeProfile.cpuCores,
+    memoryGb: computeProfile.memoryGb,
+    gpu: computeProfile.accelerator === "gpu" ? "all" : "none",
+  };
+  const bundle = await restoreRunRecovery({ runsDirectory, runId }) ?? await prepareCompilationBundle({
+    task,
+    taskDirectory,
+    runsDirectory,
+    runId,
+    prepareMarkdown,
+  });
+  bundle.runtimeAgent = { ...runtimeAgent, paperBudgetEnforced: Boolean(executorOptions.gcpBatch?.paperBudget) };
+  bundle.paperBudget = executorOptions.gcpBatch?.paperBudget;
+  bundle.computeDecision = {
+    schemaVersion: "0.1",
+    selectedProfile: structuredClone(computeProfile),
+  };
+  bundle.executionEnvironment = structuredClone(task.environment);
+  bundle.sandboxProvider = "gcp-batch";
+  await updateRunState(bundle, {
+    runtime: runtimeAgent.runtime,
+    agent: publicAgentRuntime(runtimeAgent),
+    sandbox: "gcp-batch",
+    image: task.environment.image,
+    executionEnvironment: bundle.executionEnvironment,
+  });
+
+  const instructions = await readFile(
+    path.join(bundle.directories.input, "agent-instructions.md"),
+    "utf8",
+  );
+  const gcpOptions = executorOptions.gcpBatch ?? {};
+  const config = resolveGcpBatchConfig({ bundle, options: gcpOptions });
+  bundle.sourceReviewProviderSecret = config.providerSecret;
+  const clients = createClients(config, gcpOptions.clients);
+  const temporaryDirectory = await mkdtemp(
+    path.join(os.tmpdir(), "citeark-gcp-compiler-"),
+  );
+  const jobs = bundle.restored ? [...(bundle.state.cloudExecution?.jobs ?? [])] : [];
+  const stagedObjects = new Set();
+  let validationIssues = ["research.json 尚未生成"];
+  let normalizedResearch = null;
+  let normalizationWarnings = [];
+  let blockingFailure = null;
+  let successful = false;
+  let processingLeaseLost = false;
+  await mkdir(path.join(bundle.directories.execution, "prompts"), { recursive: true });
+
+  try {
+    if (bundle.restored && bundle.state.status === "completed" && await pathExists(path.join(bundle.directories.output, "research.normalized.json"))) {
+      const research = await readJson(path.join(bundle.directories.output, bundle.sourceInventory ? "research.json" : "research.normalized.json"));
+      const accepted = await acceptCompilerDraft({ bundle, draft: research, validateResearch, sourceReviewer })
+        .catch((error) => { throw researchCompilationFailure([error.message], error.failureCode === "compiler.source_review_unavailable" ? { code: error.failureCode, retryable: false } : null); });
+      successful = true;
+      progress("复用已完成的 Research Compiler 输出，不创建计算任务");
+      return { dryRun: false, bundle, research: accepted.research, normalizationWarnings: accepted.normalizationWarnings, jobs };
+    }
+    let resumedJob = null;
+    const previous = jobs.at(-1) ?? bundle.state.recoveryPendingJob;
+    if (bundle.restored && previous?.name && typeof clients.batch.findJob === "function") {
+      resumedJob = await clients.batch.findJob(previous.name);
+      if (resumedJob && new Set(["FAILED", "CANCELLED"]).has(resumedJob.status?.state)) {
+        await updateCompilerCloudObservation({ bundle, config, jobs, record: previous, job: resumedJob, state: resumedJob.status.state,
+          checkpointStatus: previous.checkpointStatus, storage: clients.storage, progress });
+        await saveRemoteRecovery({ bundle, storage: clients.storage, bucket: config.stagingBucket, record: previous, persist: gcpOptions.onCheckpoint, recoveryBucket: gcpOptions.recoveryBucket, recoveryNamespace: gcpOptions.recoveryNamespace });
+        await clients.batch.deleteJob(previous.name);
+        await releaseCompilerAccountLock({ bundle, config, clients, record: previous });
+        resumedJob = null;
+      }
+    }
+    // A transport-successful VM can still contain a failed Agent process.
+    // Preserve its accounting, but resume the workspace in a new generation
+    // instead of repeatedly importing the same failed archive. Source-review
+    // recovery without a process failure retains its independent reuse path.
+    const rejectedAgentOutput = bundle.state.status === "invalid_result"
+      ? await describeRemoteAgentFailure(bundle, previous?.attempt ?? 1) : null;
+    if (needsCompilerRepairGeneration(gcpOptions.compilerRepair, bundle.state.status, resumedJob?.status?.state)
+      || (rejectedAgentOutput && resumedJob?.status?.state === "SUCCEEDED")) resumedJob = null;
+    if (bundle.restored && !resumedJob) {
+      const restored = await restoreRemoteRecovery({ bundle, storage: clients.storage, bucket: config.stagingBucket });
+      if (restored) { config.restoreCheckpointPrefix = restored.checkpointPrefix; config.restoreCheckpointBucket = restored.bucket; }
+      bundle.state.recoveryGeneration = (bundle.state.recoveryGeneration ?? 0) + 1;
+      config.stagingPrefix += `-r${bundle.state.recoveryGeneration}`;
+    }
+    const maxAttempts = 1 + runtimeAgent.validationRetries;
+    const checkpointAttempt = 1;
+    for (let attempt = bundle.restored ? previous?.attempt ?? 1 : 1; attempt <= maxAttempts; attempt += 1) {
+      const invocation = await buildAgentInvocation({
+        bundle,
+        attempt,
+        prompt: compilerPrompt(attempt, validationIssues, {
+          continuation: bundle.runtimeTask?.continuation,
+          repairBaseline: bundle.repairBaselineResearch,
+        }),
+        instructions,
+        providerSession: remoteProviderSession(bundle.runtimeAgent),
+      });
+      const resumeInvocation = await buildAgentInvocation({
+        bundle,
+        attempt: 2,
+        prompt: [
+          "Continue from the restored compilation workspace. Inspect preserved artifacts and apply the current task below; a prior research.json may still contain the rejected draft.",
+          compilerPrompt(attempt, validationIssues, {
+            continuation: bundle.runtimeTask?.continuation,
+            repairBaseline: bundle.repairBaselineResearch,
+          }),
+        ].join("\n\n"),
+        instructions,
+        providerSession: remoteProviderSession(bundle.runtimeAgent),
+      });
+      await writeFile(
+        path.join(bundle.directories.execution, "prompts", `attempt-${attempt}.txt`),
+        `${agentInvocationPromptArgument(invocation)}\n`,
+      );
+      await writeFile(
+        path.join(bundle.directories.execution, "prompts", `attempt-${attempt}-resume.txt`),
+        `${agentInvocationPromptArgument(resumeInvocation)}\n`,
+      );
+      const preview = compilerJobPreview({
+        bundle,
+        invocation,
+        resumeInvocation,
+        attempt,
+        config,
+        checkpointAttempt,
+        restoreCheckpointOnStart: attempt > 1 || Boolean(config.restoreCheckpointPrefix),
+        reuseCompletedResultOnRestore: attempt === 1 && !rejectedAgentOutput && !gcpOptions.compilerRepair,
+      });
+      await writeJson(
+        path.join(bundle.directories.execution, `gcp-batch-job-a${attempt}.json`),
+        { schemaVersion: "0.1", executor: "gcp-batch", jobId: preview.jobId, job: sanitizeJob(preview.job) },
+      );
+      if (dryRun) {
+        await updateRunState(bundle, { status: "prepared" });
+        return { dryRun: true, bundle, invocation, jobSpec: preview.job };
+      }
+      if (attempt === 1) {
+        await updateRunState(bundle, {
+          status: "running",
+          startedAt: new Date().toISOString(),
+        });
+      }
+      const stageArchive = path.join(temporaryDirectory, preview.stageFilename);
+      const resultArchive = path.join(temporaryDirectory, preview.resultFilename);
+      if (!resumedJob) await createStageArchive(bundle, stageArchive);
+      stagedObjects.add(preview.stageObject);
+      stagedObjects.add(preview.resultObject);
+      if (hasSessionEvents()) stagedObjects.add(`${preview.resultObject}.trace.jsonl`);
+      stagedObjects.add(preview.checkpointStatus);
+      progress(`GCP Batch ${bundle.runId}: 上传 Research Compiler 输入`);
+      if (!resumedJob) await clients.storage.uploadFile({
+        bucket: config.stagingBucket,
+        object: preview.stageObject,
+        filePath: stageArchive,
+      });
+      try {
+        await gcpOptions.assertActive?.();
+      } catch (error) {
+        if (error?.processingLeaseLost === true) processingLeaseLost = true;
+        throw error;
+      }
+      progress(`GCP Batch ${bundle.runId}: 创建 Research Compiler Job ${preview.jobId}`);
+      bundle.state.recoveryPendingJob = { jobId: preview.jobId, name: clients.batch.jobName(preview.jobId), attempt,
+        resultObject: preview.resultObject, checkpointPrefix: resolveCheckpointObjects(config, checkpointAttempt).prefix,
+        checkpointStatus: preview.checkpointStatus };
+      await saveRunRecovery(bundle, gcpOptions.onCheckpoint);
+      const created = resumedJob ?? await createLockedBatchJob({
+        storage: clients.storage,
+        batch: clients.batch,
+        bucket: config.stagingBucket,
+        accountId: bundle.runtimeAgent.codexAccountId,
+        owner: `${bundle.runId}-${attempt}`,
+        jobId: preview.jobId,
+        job: preview.job,
+      });
+      const jobName = created?.name ?? clients.batch.jobName(preview.jobId);
+      const record = resumedJob ? previous : {
+        attempt,
+        jobId: preview.jobId,
+        name: jobName,
+        state: "QUEUED",
+        startedAt: new Date().toISOString(),
+        checkpointStatus: preview.checkpointStatus,
+        checkpointPrefix: resolveCheckpointObjects(config, checkpointAttempt).prefix,
+        resultObject: preview.resultObject,
+        checkpoint: null,
+        activity: null,
+        codexAccountLockOwner: `${bundle.runId}-${attempt}`,
+      };
+      if (!jobs.includes(record)) jobs.push(record);
+      await saveRunRecovery(bundle, gcpOptions.onCheckpoint);
+      const terminal = await clients.batch.waitForTerminal(jobName, {
+        liveOutput: { storage: clients.storage, bucket: config.stagingBucket, object: `${record.resultObject}.trace.jsonl`, source: `${bundle.runId}:${attempt}`, runtime: bundle.runtimeAgent.runtime },
+          timeoutMs: config.waitTimeoutMinutes * 60_000,
+          pollIntervalMs: config.pollIntervalMs,
+          onState: (state) => {
+            progress(`GCP Batch ${preview.jobId}: ${state}`);
+          },
+          onPoll: async (observedJob, state) => {
+            try {
+              await gcpOptions.assertActive?.();
+            } catch (error) {
+              if (error?.processingLeaseLost === true) processingLeaseLost = true;
+              throw error;
+            }
+            const previousRecovery = `${record.state}:${record.checkpoint?.sequence ?? ""}`;
+            await updateCompilerCloudObservation({
+              bundle,
+              config,
+              jobs,
+              record,
+              job: observedJob,
+              state,
+              checkpointStatus: record.checkpointStatus,
+              storage: clients.storage,
+              progress,
+            });
+            if (previousRecovery !== `${record.state}:${record.checkpoint?.sequence ?? ""}`) await saveRemoteRecovery({ bundle,
+              storage: clients.storage, bucket: config.stagingBucket, record, persist: gcpOptions.onCheckpoint, recoveryBucket: gcpOptions.recoveryBucket, recoveryNamespace: gcpOptions.recoveryNamespace });
+          },
+        });
+        await updateCompilerCloudObservation({
+          bundle,
+          config,
+          jobs,
+          record,
+          job: terminal,
+          state: terminal?.status?.state ?? record.state,
+          checkpointStatus: preview.checkpointStatus,
+          storage: clients.storage,
+          progress,
+        });
+        await saveRemoteRecovery({ bundle, storage: clients.storage, bucket: config.stagingBucket, record, persist: gcpOptions.onCheckpoint, recoveryBucket: gcpOptions.recoveryBucket, recoveryNamespace: gcpOptions.recoveryNamespace });
+        record.state = terminal?.status?.state ?? record.state;
+        record.finishedAt = new Date().toISOString();
+        await releaseCompilerAccountLock({ bundle, config, clients, record });
+        await writeJson(
+          path.join(bundle.directories.execution, `gcp-batch-result-a${attempt}.json`),
+          sanitizeJob(terminal),
+        );
+        assertSuccessfulGcpBatchTerminal({
+          job: terminal,
+          jobId: preview.jobId,
+          workload: "Research Compiler",
+        });
+        await clients.storage.downloadFile({
+          bucket: config.stagingBucket,
+          object: record.resultObject ?? preview.resultObject,
+          filePath: resultArchive,
+        });
+      await extractResultArchive(bundle, resultArchive);
+      resumedJob = null;
+      await saveRunRecovery(bundle, gcpOptions.onCheckpoint);
+
+      const researchPath = path.join(bundle.directories.output, "research.json");
+      await recoverJsonFromFinalMessage({
+        finalMessagePath: hostRuntimePath(bundle, CODEX_FINAL_MESSAGE_PATH),
+        outputPath: researchPath,
+      });
+      const remoteFailure = await describeRemoteAgentFailure(bundle, attempt);
+      if (remoteFailure?.failureCode === "agent.effective_progress_stalled") {
+        blockingFailure = {
+          code: remoteFailure.failureCode,
+          failureCategory: "timeout",
+          retryable: false,
+          message: remoteFailure.message,
+          recoveryAction: "保留编译现场并停止自动重跑；检查模型请求与编译任务书后创建显式续跑任务",
+        };
+        validationIssues = [remoteFailure.message];
+        break;
+      }
+      const providerFailure = remoteFailure?.failureCategory === "provider" && remoteFailure.retryable === false
+        ? { code: remoteFailure.failureCode, failureCategory: "provider", retryable: false, message: remoteFailure.message, recoveryAction: remoteFailure.recoveryAction }
+        : classifyProviderActionRequired(remoteFailure?.message);
+      if (providerFailure) {
+        blockingFailure = providerFailure;
+        validationIssues = [providerFailure.message];
+        break;
+      }
+      // A syntactically valid compiler file can still be an unfinished draft.
+      // Transport publication errors retain their independent recovery path.
+      if (remoteFailure && remoteFailure.failureCategory !== "publication") {
+        blockingFailure = { code: remoteFailure.failureCode ?? "compiler.agent_incomplete",
+          failureCategory: remoteFailure.failureCategory, retryable: remoteFailure.retryable };
+        validationIssues = [remoteFailure.message];
+        break;
+      }
+      try {
+        if (!(await pathExists(researchPath))) {
+          throw new CiteArkError("缺少 /job/output/research.json");
+        }
+        const accepted = await acceptCompilerDraft({ bundle, draft: await readJson(researchPath), validateResearch, sourceReviewer });
+        normalizedResearch = accepted.research;
+        normalizationWarnings = accepted.normalizationWarnings;
+        validationIssues = [];
+        break;
+      } catch (error) {
+        validationIssues = [
+          ...(remoteFailure ? [remoteFailure.message] : []),
+          error instanceof Error ? error.message : String(error),
+        ];
+        if (error.failureCode === "compiler.source_review_unavailable") { blockingFailure = { code: error.failureCode, retryable: false }; break; }
+      }
+    }
+
+    await ensureFinalWorkspaceCapture(bundle);
+    const usage = await readAgentUsage(
+      path.join(bundle.directories.execution, "trace.jsonl"),
+      { runtimeHome: bundle.directories.runtimeHome, model: runtimeAgent.model },
+    );
+    const status = validationIssues.length ? "invalid_result" : "completed";
+    await updateRunState(bundle, {
+      status,
+      finishedAt: new Date().toISOString(),
+      validationIssues,
+      normalizationWarnings,
+      output: normalizedResearch ? "output/research.normalized.json" : null,
+      sandboxImageIdentity: remoteImageIdentity(task.environment.image),
+      cloudExecution: compilerCloudExecution(config, jobs),
+      usage,
+    });
+    await saveRunRecovery(bundle, gcpOptions.onCheckpoint);
+    if (validationIssues.length || !normalizedResearch) {
+      throw researchCompilationFailure(validationIssues, blockingFailure);
+    }
+    const result = {
+      dryRun: false,
+      bundle,
+      research: normalizedResearch,
+      normalizationWarnings,
+      jobs,
+    };
+    successful = true;
+    return result;
+  } finally {
+    if (!config.keepJob && (successful || processingLeaseLost)) {
+      for (const job of jobs) {
+        await deleteBatchJob({ batch: clients.batch, record: job });
+      }
+    }
+    for (const job of jobs) {
+      if (job.jobDeletionRequested || new Set(["SUCCEEDED", "FAILED", "CANCELLED"]).has(job.state)) {
+        await releaseCompilerAccountLock({ bundle, config, clients, record: job });
+      }
+    }
+    if (!config.keepStaging && (successful || processingLeaseLost)) {
+      const checkpointObjects = typeof clients.storage.listObjects === "function"
+        ? await clients.storage.listObjects({
+            bucket: config.stagingBucket,
+            prefix: `${config.stagingPrefix.replaceAll(/[^a-zA-Z0-9_.-]/g, "-")}-checkpoint-`,
+          }).catch(() => [])
+        : [];
+      for (const object of checkpointObjects) stagedObjects.add(object);
+      await Promise.all(
+        [...stagedObjects].map((object) =>
+          clients.storage.deleteObject({ bucket: config.stagingBucket, object }).catch(() => undefined),
+        ),
+      );
+    }
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+async function releaseCompilerAccountLock({ bundle, config, clients, record }) {
+  await releaseBatchJobAccountLock({
+    storage: clients.storage,
+    bucket: config.stagingBucket,
+    accountId: bundle.runtimeAgent?.codexAccountId,
+    owner: record?.codexAccountLockOwner ?? `${bundle.runId}-${record?.attempt ?? 1}`,
+    jobName: record?.name,
+    record,
+  });
+}
+
+function hostRuntimePath(bundle, containerPath) {
+  return path.join(bundle.directories.run, containerPath.replace(/^\/job\//, ""));
+}
+
+export function compilerBatchJobId(runId, attempt, recoveryGeneration = 0) {
+  const stem = runId.toLowerCase().replaceAll(/[^a-z0-9-]/g, "-").replaceAll(/^-+|-+$/g, "");
+  const suffix = `-compile-a${attempt}${recoveryGeneration ? `-r${recoveryGeneration}` : ""}`;
+  if (stem.length + suffix.length <= 63) return `${stem}${suffix}`;
+  const digest = createHash("sha256").update(runId).digest("hex").slice(0, 10);
+  return `${stem.slice(0, 63 - suffix.length - digest.length - 1)}-${digest}${suffix}`;
+}
+
+function compilerJobPreview({
+  bundle,
+  invocation,
+  resumeInvocation,
+  attempt,
+  config,
+  checkpointAttempt = attempt,
+  restoreCheckpointOnStart = false,
+  reuseCompletedResultOnRestore = true,
+}) {
+  const jobId = compilerBatchJobId(bundle.runId, attempt, bundle.state.recoveryGeneration);
+  const stageFilename = `compile-stage-a${attempt}.tar.gz`;
+  const resultFilename = `compile-result-a${attempt}.tar.gz`;
+  const objectPrefix = config.stagingPrefix.replaceAll(/[^a-zA-Z0-9_.-]/g, "-");
+  const stageObject = `${objectPrefix}-${stageFilename}`;
+  const resultObject = `${objectPrefix}-${resultFilename}`;
+  const checkpoint = resolveCheckpointObjects(config, checkpointAttempt);
+  return {
+    jobId,
+    stageFilename,
+    resultFilename,
+    stageObject,
+    resultObject,
+    checkpointStatus: checkpoint.status,
+    job: buildGcpBatchJob({
+      bundle,
+      invocation,
+      resumeInvocation,
+      attempt,
+      config,
+      stageObject,
+      resultObject,
+      checkpointPrefix: checkpoint.prefix,
+      checkpointStatus: checkpoint.status,
+      completionRelativePath: "output/research.json",
+      completionHasEvidence: false,
+      workload: "compilation",
+      restoreCheckpointOnStart,
+      restoreCheckpointPrefix: config.restoreCheckpointPrefix,
+      reuseCompletedResultOnRestore,
+    }),
+  };
+}
+
+function createClients(config, injected = {}) {
+  if (injected.batch && injected.storage) return injected;
+  const auth = injected.auth ?? new GoogleAccessTokenProvider(injected.authOptions);
+  return {
+    batch: injected.batch ?? new GcpBatchClient({
+      projectId: config.projectId,
+      region: config.region,
+      auth,
+      ...injected.batchOptions,
+    }),
+    storage: injected.storage ?? new GcsStagingClient({
+      auth,
+      ...injected.storageOptions,
+    }),
+  };
+}
+
+async function updateCompilerCloudObservation({
+  bundle,
+  config,
+  jobs,
+  record,
+  job,
+  state,
+  checkpointStatus,
+  storage,
+  progress,
+}) {
+  const previousState = record.state;
+  const previousDigest = record.activity?.traceDigest ?? null;
+  const previousEffectiveAt = record.activity?.lastEffectiveAt ?? null;
+  const previousHealth = record.activity?.status ?? null;
+  record.state = state;
+  record.runDuration = job?.status?.runDuration ?? record.runDuration ?? null;
+
+  if (config.checkpointing.enabled && typeof storage.readJsonObject === "function") {
+    const checkpoint = await storage.readJsonObject({
+      bucket: config.stagingBucket,
+      object: checkpointStatus,
+      missing: null,
+    }).catch(() => null);
+    if (
+      checkpoint?.schemaVersion === "0.1"
+      && typeof checkpoint.sequence === "string"
+      && typeof checkpoint.object === "string"
+    ) {
+      const activity = checkpoint.activity && typeof checkpoint.activity === "object"
+        ? checkpoint.activity
+        : {};
+      const { activity: _privateActivity, ...checkpointRecord } = checkpoint;
+      record.checkpoint = checkpointRecord;
+      if (typeof activity.traceDigest === "string") {
+        const traceTail = Array.isArray(activity.traceTail) ? activity.traceTail.slice(-24) : [];
+        const lastEffectiveAt = validIso(activity.lastEffectiveAt);
+        const idleSeconds = lastEffectiveAt
+          ? Math.max(0, Math.floor((Date.now() - Date.parse(lastEffectiveAt)) / 1_000))
+          : null;
+        const attemptStart = traceTail.findLastIndex((event) =>
+          event && typeof event === "object" && event.type === "citeark.attempt_started");
+        const stalled = traceTail.slice(attemptStart + 1).some((event) =>
+          event && typeof event === "object" && event.type === "citeark.agent_stalled");
+        const status = stalled
+          ? "stalled"
+          : idleSeconds !== null && idleSeconds >= COMPILER_ACTIVITY_WAITING_SECONDS
+          ? "waiting_for_model"
+          : "active";
+        record.activity = {
+          traceDigest: activity.traceDigest,
+          traceTail,
+          lastEffectiveAt,
+          observedAt: validIso(activity.observedAt) ?? validIso(checkpoint.createdAt),
+          idleSeconds,
+          status,
+        };
+      }
+    }
+  }
+
+  const activityChanged = (record.activity?.traceDigest ?? null) !== previousDigest
+    || (record.activity?.lastEffectiveAt ?? null) !== previousEffectiveAt;
+  const healthChanged = record.activity?.status !== previousHealth;
+  const stateChanged = record.state !== previousState;
+  if (!activityChanged && !healthChanged && !stateChanged) return;
+
+  if (record.activity?.status === "stalled" && (activityChanged || healthChanged)) {
+    progress(
+      "Research Compiler 已因长时间无有效进展而停止，正在保存诊断现场",
+      { agentActivity: { ...record.activity, traceTail: undefined } },
+    );
+  } else if (activityChanged && record.activity?.lastEffectiveAt) {
+    progress(
+      `Research Compiler 有效进展更新：${record.activity.lastEffectiveAt}`,
+      { agentActivity: { ...record.activity, traceTail: undefined } },
+    );
+  } else if (healthChanged && record.activity?.status === "waiting_for_model") {
+    progress(
+      `Research Compiler 正在等待模型响应；最近有效进展为 ${record.activity.lastEffectiveAt ?? "未知"}`,
+      { agentActivity: { ...record.activity, traceTail: undefined } },
+    );
+  }
+  await updateRunState(bundle, {
+    cloudExecution: compilerCloudExecution(config, jobs),
+  });
+}
+
+function compilerCloudExecution(config, jobs) {
+  return {
+    provider: "gcp",
+    service: "batch",
+    projectId: config.projectId,
+    region: config.region,
+    machineType: config.machineType,
+    provisioningModel: config.provisioningModel,
+    jobs,
+  };
+}
+
+function validIso(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value))
+    ? new Date(value).toISOString()
+    : null;
+}
+
+async function createStageArchive(bundle, destination) {
+  await createRemoteStageArchive({
+    runDirectory: bundle.directories.run,
+    destination,
+    label: "Research Compiler",
+    paperBudget: bundle.paperBudget,
+  });
+}
+
+async function extractResultArchive(bundle, source) {
+  const result = await captureProcess(
+    "tar",
+    ["-xzf", source, "-C", bundle.directories.run],
+  );
+  if (result.code !== 0) {
+    throw new CiteArkError(`解压 Research Compiler 结果失败：\n${result.stderr.trim()}`);
+  }
+}
+
+function sanitizeJob(value) {
+  const clone = structuredClone(value);
+  for (const group of clone?.taskGroups ?? []) {
+    const variables = group?.taskSpec?.environment?.variables;
+    if (variables?.CITEARK_PROVIDER_SECRET_RESOURCE) {
+      variables.CITEARK_PROVIDER_SECRET_RESOURCE = "<secret-manager-version>";
+    }
+    if (variables?.CITEARK_PROVIDER_CREDENTIAL_TOKEN) {
+      variables.CITEARK_PROVIDER_CREDENTIAL_TOKEN = "<short-lived-credential-token>";
+    }
+    const secrets = group?.taskSpec?.environment?.secretVariables;
+    if (secrets) {
+      for (const key of Object.keys(secrets)) secrets[key] = "<secret-manager-version>";
+    }
+  }
+  return clone;
+}
+
+function remoteImageIdentity(image) {
+  const digest = image.match(/@sha256:[0-9a-f]{64}$/)?.[0]?.slice(1) ?? null;
+  return { id: digest, repositoryDigests: digest ? [image] : [] };
+}
+
+function assertCompilerProfile(profile) {
+  if (!profile || profile.executor !== "gcp-batch") {
+    throw new CiteArkError("Research Compiler 必须使用 gcp-batch 资源规格");
+  }
+  if (typeof profile.image !== "string" || !profile.image.includes("@sha256:")) {
+    throw new CiteArkError("Research Compiler 运行镜像必须固定不可变摘要");
+  }
+}