@citeark/agent 0.3.20

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

@@ -0,0 +1,92 @@
+import { CiteArkError } from "../util.mjs";
+
+const CONFIGURATION_FAILURE = /(?:CODE_GCE_BAD_REQUEST|INVALID_ARGUMENT|invalid value for field|boot disk|disk size|sizeGb|must be at least|cannot be smaller|image.*(?:invalid|not found)|machine type.*invalid)/i;
+const CAPACITY_FAILURE = /(?:RESOURCE_POOL_EXHAUSTED|not enough resources|capacity is unavailable|资源不足|容量不足)/i;
+const AUTHORIZATION_FAILURE = /(?:PERMISSION_DENIED|permission denied|not authorized|forbidden|service account.*(?:missing|invalid|permission))/i;
+
+/**
+ * Convert a provider terminal state into a typed platform failure. Unknown
+ * terminal failures fail closed: only explicitly classified transient
+ * infrastructure failures may ask the outer Worker for another attempt.
+ */
+export function assertSuccessfulGcpBatchTerminal({
+  job,
+  jobId,
+  workload = "workload",
+  infrastructureFailure = null,
+}) {
+  const state = job?.status?.state ?? "STATE_UNSPECIFIED";
+  if (state === "SUCCEEDED") return;
+
+  const descriptions = gcpBatchStatusDescriptions(job);
+  const detail = descriptions.slice(-3).join("；");
+  const evidence = descriptions.join("\n");
+  const base = `GCP Batch ${workload} ${jobId} 以 ${state} 结束${detail ? `：${detail}` : ""}`;
+
+  if (CONFIGURATION_FAILURE.test(evidence)) {
+    throw new CiteArkError(base, {
+      retryable: false,
+      failureCode: "gcp.batch_configuration_invalid",
+      failureCategory: "configuration",
+      retryDisposition: "never",
+      failureOwner: "platform",
+      recoveryAction: "修正镜像、启动盘、机器规格或 Batch Job 配置并通过确定性预检后，再创建新执行",
+    });
+  }
+  if (AUTHORIZATION_FAILURE.test(evidence)) {
+    throw new CiteArkError(base, {
+      retryable: false,
+      failureCode: "gcp.batch_authorization_invalid",
+      failureCategory: "configuration",
+      retryDisposition: "human_input",
+      failureOwner: "platform",
+      recoveryAction: "修正 GCP 服务账号、IAM 或资源访问配置后再创建新执行",
+    });
+  }
+  if (CAPACITY_FAILURE.test(evidence)) {
+    throw new CiteArkError(base, {
+      retryable: true,
+      failureCode: "gcp.capacity_unavailable",
+      failureCategory: "infrastructure",
+      retryDisposition: "different_profile",
+      failureOwner: "provider",
+      recoveryAction: "保持科研计划不变，改用尚未尝试的兼容可用区或资源规格",
+    });
+  }
+  if (infrastructureFailure?.category === "timeout") {
+    throw new CiteArkError(base, {
+      retryable: false,
+      failureCode: "execution.runtime_budget_exhausted",
+      failureCategory: "timeout",
+      retryDisposition: "new_research_plan",
+      failureOwner: "scientific_plan",
+      recoveryAction: "提高合规算力或创建声明更长时限的新 Research Plan；不要原样自动重试",
+    });
+  }
+  if (infrastructureFailure?.retryable === true) {
+    throw new CiteArkError(base, {
+      retryable: true,
+      failureCode: `gcp.infrastructure.${infrastructureFailure.exitCode ?? "transient"}`,
+      failureCategory: "infrastructure",
+      retryDisposition: "same_batch_task",
+      failureOwner: "provider",
+      recoveryAction: "从最近检查点恢复同一不可变目标",
+    });
+  }
+
+  throw new CiteArkError(base, {
+    retryable: false,
+    failureCode: "gcp.batch_terminal_unclassified",
+    failureCategory: infrastructureFailure?.category ?? "infrastructure",
+    retryDisposition: "never",
+    failureOwner: "platform",
+    recoveryAction: "保留完整 Batch 状态事件并完成错误分类；不得用新 Worker 盲目重试",
+  });
+}
+
+export function gcpBatchStatusDescriptions(job) {
+  return (job?.status?.statusEvents ?? [])
+    .map((event) => event?.description)
+    .filter((description) => typeof description === "string" && description.trim())
+    .map((description) => description.trim());
+}

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

@@ -0,0 +1,527 @@
+import { modelRoute } from '../provider/model-route.mjs';
+import { hasSessionEvents } from '../terminal/events.mjs';
+import {
+  checkpointObjectPrefix,
+  checkpointStatusObject,
+  GCP_BATCH_RETRYABLE_INFRASTRUCTURE_EXIT_CODES,
+  resolveCheckpointPolicy,
+} from "./checkpoint-protocol.mjs";
+import { buildCheckpointedWorkerScript } from "./gcp-checkpoint-worker.mjs";
+import {
+  nativeDeepSeekProvider,
+  openCodeModelDefinition,
+  openCodeModelReference,
+} from "../runtime/opencode.mjs";
+import { gcpBatchControllerWaitTimeoutMinutes } from "../contracts/execution-timeouts.mjs";
+
+export const GCP_STAGING_MOUNT = "/mnt/disks/citeark-staging";
+export const GCP_RESTORE_MOUNT = "/mnt/disks/citeark-restore";
+export const GCP_BATCH_SUPERVISOR_GRACE_SECONDS = 10 * 60;
+export const GCP_COMPILER_PROVIDER_REQUEST_TIMEOUT_SECONDS = 10 * 60;
+export const GCP_COMPILER_AGENT_STALL_TIMEOUT_SECONDS = 20 * 60;
+
+export function buildGcpBatchJob({
+  bundle,
+  invocation,
+  resumeInvocation,
+  attempt,
+  config,
+  stageObject,
+  resultObject,
+  externalObjectPrefix = `${resultObject}.object`,
+  checkpointPrefix,
+  checkpointStatus,
+  restoreCheckpointPrefix,
+  completionRelativePath = "output/result.json",
+  completionHasEvidence = true,
+  completionValidatorRelativePath = null,
+  completionSuccessJq = '.execution.status == "succeeded"',
+  preserveRebuildableCache = false,
+  finalCheckpointKind = "critical",
+  finalCheckpointReason = "publication-ready",
+  allowCpuHandoff = false,
+  runtimeBudgetMinutes,
+  workload = "reproduction",
+  restoreCheckpointOnStart = false,
+  reuseCompletedResultOnRestore = true,
+}) {
+  const agent = bundle.runtimeAgent;
+  const providerRelay = !agent.codexAccountId && agent.billingMode !== "user_byok"
+    && (usesProviderRelay(agent) || Boolean(bundle.paperBudget));
+  const providerRequestTimeoutSeconds = workload === "compilation"
+    ? GCP_COMPILER_PROVIDER_REQUEST_TIMEOUT_SECONDS
+    : 30 * 60;
+  const provider = remoteProviderEnvironment(agent, config.providerSecret, {
+    providerRelay,
+    providerRequestTimeoutSeconds,
+    providerCredentialBroker: config.providerCredentialBroker,
+  });
+  if (bundle.paperBudget && !agent.codexAccountId && agent.billingMode !== "user_byok") {
+    provider.variables.CITEARK_PAPER_BUDGET_REQUIRED = "1";
+  }
+  if (agent.codexAccountId) Object.assign(provider.variables, {
+    CITEARK_CODEX_AUTH_SECRET: `projects/${config.projectId}/secrets/citeark-codex-${agent.codexAccountId}/versions/latest`,
+    CITEARK_CODEX_ACCOUNT_BUCKET: config.stagingBucket,
+    CITEARK_CODEX_ACCOUNT_OWNER: `${bundle.runId}-${attempt}`,
+    CITEARK_CODEX_ACCOUNT_LOCK_MODE: "coordinator",
+  });
+  const instance = {
+    ...(config.instanceTemplate
+      ? { instanceTemplate: config.instanceTemplate }
+      : { policy: directInstancePolicy({ bundle, config }) }),
+    blockProjectSshKeys: true,
+    ...(bundle.executionEnvironment.gpu === "all"
+      ? { installGpuDrivers: !(config.instanceTemplate || config.gpuDriversPreinstalled) }
+      : {}),
+  };
+  const restoreMount = restoreCheckpointPrefix
+    && config.restoreCheckpointBucket !== config.stagingBucket
+    ? GCP_RESTORE_MOUNT
+    : GCP_STAGING_MOUNT;
+  const taskSpec = {
+    runnables: [{
+      displayName: `citeark-${workload}-attempt-${attempt}`,
+      container: {
+        imageUri: bundle.executionEnvironment.image,
+        entrypoint: "/bin/bash",
+        commands: ["-lc", buildCheckpointedWorkerScript({
+          runId: bundle.runId,
+          initialInvocation: invocation,
+          resumeInvocation,
+          attempt,
+          stagePath: `${GCP_STAGING_MOUNT}/${stageObject}`,
+          resultPath: `${GCP_STAGING_MOUNT}/${resultObject}`,
+          liveTracePath: hasSessionEvents() ? `${GCP_STAGING_MOUNT}/${resultObject}.trace.jsonl` : undefined,
+          externalObjectPrefixPath: `${GCP_STAGING_MOUNT}/${externalObjectPrefix}`,
+          checkpointPrefixPath: `${GCP_STAGING_MOUNT}/${checkpointPrefix}`,
+          checkpointStatusPath: `${GCP_STAGING_MOUNT}/${checkpointStatus}`,
+          restoreCheckpointPrefixPath: `${restoreMount}/${restoreCheckpointPrefix ?? checkpointPrefix}`,
+          checkpointPolicy: config.checkpointing,
+          runtimeBudgetSeconds: Math.ceil((Number.isFinite(runtimeBudgetMinutes) && runtimeBudgetMinutes > 0
+            ? Math.min(runtimeBudgetMinutes, bundle.runtimeTask.environment.timeoutMinutes)
+            : bundle.executionEnvironment.timeoutMinutes) * 60),
+          completionRelativePath,
+          completionHasEvidence,
+          completionValidatorRelativePath,
+          completionSuccessJq,
+          preserveRebuildableCache,
+          finalCheckpointKind,
+          finalCheckpointReason,
+          allowCpuHandoff,
+          providerRelay,
+          providerRelayPath: "/job/input/runner-provider-relay.mjs",
+          agentStallTimeoutSeconds: workload === "compilation"
+            ? GCP_COMPILER_AGENT_STALL_TIMEOUT_SECONDS
+            : 0,
+          restoreCheckpointOnStart,
+          reuseCompletedResultOnRestore,
+        })],
+        volumes: [
+          `${GCP_STAGING_MOUNT}:${GCP_STAGING_MOUNT}:rw`,
+          ...(restoreMount === GCP_RESTORE_MOUNT
+            ? [`${GCP_RESTORE_MOUNT}:${GCP_RESTORE_MOUNT}:ro`]
+            : []),
+        ],
+        options: `--shm-size=${bundle.executionEnvironment.shmGb}g`,
+        blockExternalNetwork: false,
+      },
+    }],
+    computeResource: {
+      cpuMilli: String(Math.ceil(bundle.executionEnvironment.cpus * 1000)),
+      memoryMib: String(Math.ceil(bundle.executionEnvironment.memoryGb * 1024)),
+    },
+    // The Agent enforces the immutable scientific budget itself. Batch gets a
+    // small supervisor grace window so a timed-out Agent can still checkpoint,
+    // write an auditable failure envelope, and upload the result archive.
+    maxRunDuration: `${Math.ceil(bundle.executionEnvironment.timeoutMinutes * 60) + GCP_BATCH_SUPERVISOR_GRACE_SECONDS}s`,
+    maxRetryCount: config.infrastructureRetryCount,
+    ...(config.infrastructureRetryCount > 0 ? {
+      lifecyclePolicies: [{
+        action: "RETRY_TASK",
+        actionCondition: {
+          exitCodes: [...GCP_BATCH_RETRYABLE_INFRASTRUCTURE_EXIT_CODES],
+        },
+      }],
+    } : {}),
+    volumes: [{
+      // Mount the bucket root without mountOptions. The current Batch COS
+      // image expands `implicit-dirs` into an invalid GCSFuse v3 command.
+      // Root-level, run-unique object names do not need directory emulation.
+      gcs: { remotePath: config.stagingBucket },
+      mountPath: GCP_STAGING_MOUNT,
+    }, ...(restoreMount === GCP_RESTORE_MOUNT ? [{
+      gcs: { remotePath: config.restoreCheckpointBucket },
+      mountPath: GCP_RESTORE_MOUNT,
+    }] : [])],
+    environment: provider,
+  };
+  return {
+    taskGroups: [{
+      taskSpec,
+      taskCount: "1",
+      parallelism: "1",
+      taskCountPerNode: "1",
+    }],
+    allocationPolicy: {
+      instances: [instance],
+      ...(config.allowedLocations?.length ? {
+        location: { allowedLocations: config.allowedLocations },
+      } : {}),
+      ...(config.serviceAccount ? {
+        serviceAccount: {
+          email: config.serviceAccount,
+          scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+        },
+      } : {}),
+      labels: labels(bundle.runId, attempt, workload),
+    },
+    labels: labels(bundle.runId, attempt, workload),
+    logsPolicy: { destination: "CLOUD_LOGGING" },
+  };
+}
+
+export function resolveGcpBatchConfig({ bundle, options = {} }) {
+  const profile = bundle.computeDecision?.selectedProfile?.executorConfig ?? {};
+  const projectId = first(options.projectId, profile.projectId, process.env.CITEARK_GCP_PROJECT, process.env.GOOGLE_CLOUD_PROJECT);
+  const region = first(options.region, profile.region, process.env.CITEARK_GCP_BATCH_REGION);
+  const stagingBucket = first(options.stagingBucket, profile.stagingBucket, process.env.CITEARK_GCP_STAGING_BUCKET);
+  const restoreCheckpointBucket = first(options.restoreCheckpointBucket, stagingBucket);
+  const serviceAccount = first(options.serviceAccount, profile.serviceAccount, process.env.CITEARK_GCP_BATCH_SERVICE_ACCOUNT);
+  const subscription = modelRoute(bundle.runtimeAgent).transport === "codex_subscription";
+  const providerSecret = subscription ? undefined : first(options.providerSecret, process.env.CITEARK_GCP_PROVIDER_SECRET);
+  const machineType = first(options.machineType, profile.machineType);
+  const instanceTemplate = first(options.instanceTemplate, profile.instanceTemplate);
+  const bootDiskImage = first(options.bootDiskImage, profile.bootDiskImage);
+  const provisioningModel = first(options.provisioningModel, profile.provisioningModel, "SPOT").toUpperCase();
+  const issues = [];
+  const providerCredentialBroker = normalizeProviderCredentialBroker(options.providerCredentialBroker, issues);
+  if (!projectId) issues.push("缺少 GCP projectId（--gcp-project 或 CITEARK_GCP_PROJECT）");
+  if (!region) issues.push("缺少 GCP region（--gcp-region 或 CITEARK_GCP_BATCH_REGION）");
+  if (!stagingBucket) issues.push("缺少临时 GCS bucket（--gcp-staging-bucket 或 CITEARK_GCP_STAGING_BUCKET）");
+  if (options.restoreCheckpointBucket && !safeBucketName(restoreCheckpointBucket)) {
+    issues.push("restoreCheckpointBucket 不是安全的 GCS bucket 名称");
+  }
+  if (!machineType && !instanceTemplate) {
+    issues.push("gcp-batch profile 至少需要 executorConfig.machineType 或 executorConfig.instanceTemplate");
+  }
+  if (!subscription && !providerSecret) issues.push("缺少模型 API Key 对应的 Secret Manager 版本（--gcp-provider-secret）");
+  if (providerSecret && !/^projects\/[^/]+\/secrets\/[^/]+\/versions\/[^/]+$/.test(providerSecret)) {
+    issues.push("gcpProviderSecret 必须是 projects/.../secrets/.../versions/... 格式");
+  }
+  if (!new Set(["STANDARD", "SPOT", "FLEX_START"]).has(provisioningModel)) {
+    issues.push("provisioningModel 必须是 STANDARD、SPOT 或 FLEX_START");
+  }
+  if (!remoteImage(bundle.executionEnvironment.image)) {
+    issues.push("gcp-batch 必须使用可由云端拉取的完整镜像 URI（例如 us-docker.pkg.dev/project/repo/image@sha256:...）");
+  }
+  if (
+    options.reuseCompletedResultOnRestore !== undefined
+    && typeof options.reuseCompletedResultOnRestore !== "boolean"
+  ) {
+    issues.push("reuseCompletedResultOnRestore 必须是布尔值");
+  }
+  if (issues.length) throw new TypeError(`GCP Batch 执行参数无效：\n- ${issues.join("\n- ")}`);
+  const infrastructureRetryCount = nonNegativeInteger(
+    options.infrastructureRetryCount ?? profile.infrastructureRetryCount,
+    provisioningModel === "SPOT" ? 2 : 0,
+  );
+  const checkpointing = resolveCheckpointPolicy({ options, profile });
+  const restoreCheckpointPrefix = optionalObjectPrefix(options.restoreCheckpointPrefix);
+  const allowedLocations = normalizeAllowedLocations(
+    options.allowedLocations ?? profile.allowedLocations,
+    region,
+  );
+  return {
+    projectId,
+    region,
+    stagingBucket,
+    restoreCheckpointBucket,
+    serviceAccount,
+    providerSecret,
+    providerCredentialBroker,
+    machineType,
+    instanceTemplate,
+    bootDiskImage,
+    gpuDriversPreinstalled: options.gpuDriversPreinstalled === true
+      || profile.gpuDriversPreinstalled === true,
+    allowedLocations,
+    hourlyUsd: bundle.computeDecision?.selectedProfile?.hourlyUsd ?? null,
+    provisioningModel,
+    acceleratorType: first(options.acceleratorType, profile.acceleratorType),
+    bootDiskType: first(options.bootDiskType, profile.bootDiskType, "pd-balanced"),
+    bootDiskGb: positiveInteger(options.bootDiskGb ?? profile.bootDiskGb, 100),
+    infrastructureRetryCount,
+    checkpointing,
+    restoreCheckpointPrefix,
+    reuseCompletedResultOnRestore: options.reuseCompletedResultOnRestore === true,
+    pollIntervalMs: positiveInteger(options.pollIntervalMs, 10_000),
+    waitTimeoutMinutes: positiveInteger(
+      options.waitTimeoutMinutes ?? profile.waitTimeoutMinutes,
+      gcpBatchControllerWaitTimeoutMinutes({
+        executionTimeoutMinutes: bundle.executionEnvironment.timeoutMinutes,
+        infrastructureRetryCount,
+      }),
+    ),
+    keepJob: options.keepJob === true,
+    keepStaging: options.keepStaging === true,
+    stagingPrefix: `citeark/jobs/${bundle.runId}`,
+  };
+}
+
+function normalizeAllowedLocations(value, region) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+    throw new TypeError("allowedLocations 必须是非空位置字符串数组");
+  }
+  const unique = [...new Set(value)];
+  const invalid = unique.filter((item) =>
+    !new RegExp(`^(?:zones/${escapeRegExp(region)}-[a-z]|regions/${escapeRegExp(region)})$`).test(item));
+  if (invalid.length) {
+    throw new TypeError(`allowedLocations 必须位于任务区域 ${region}：${invalid.join("、")}`);
+  }
+  return unique;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function directInstancePolicy({ bundle, config }) {
+  const policy = {
+    machineType: config.machineType,
+    provisioningModel: config.provisioningModel,
+    bootDisk: {
+      type: config.bootDiskType,
+      sizeGb: String(config.bootDiskGb),
+      ...(config.bootDiskImage ? { image: config.bootDiskImage } : {}),
+    },
+  };
+  if (bundle.executionEnvironment.gpu === "all") {
+    policy.accelerators = [{
+      type: config.acceleratorType ?? normalizeAcceleratorType(bundle.computeDecision?.selectedProfile?.gpu?.type),
+      count: String(bundle.computeDecision?.selectedProfile?.gpu?.count ?? 1),
+    }];
+  }
+  return policy;
+}
+
+function optionalObjectPrefix(value) {
+  if (value === undefined || value === null || value === "") return null;
+  if (typeof value !== "string" || !/^[a-zA-Z0-9_.-]{1,900}$/.test(value)) {
+    throw new TypeError("restoreCheckpointPrefix 必须是 GCS bucket 根目录下的安全对象前缀");
+  }
+  return value;
+}
+
+function safeBucketName(value) {
+  return typeof value === "string"
+    && /^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$/.test(value)
+    && !value.includes("..")
+    && !value.startsWith("goog");
+}
+
+export function remoteProviderSession(agent) {
+  return {
+    containerBaseUrl:
+      agent.runtime === "codex" && (agent.reasoningMode === "pro" || agent.paperBudgetEnforced)
+        ? "http://127.0.0.1:4317"
+        : agent.runtime === "claude-code"
+          ? agent.api.baseUrl.replace(/\/$/, "")
+          : stripOpenAiVersion(agent.api.baseUrl),
+  };
+}
+
+export function remoteProviderEnvironment(
+  agent,
+  secretResource,
+  {
+    providerRelay = usesProviderRelay(agent),
+    providerRequestTimeoutSeconds = 30 * 60,
+    providerCredentialBroker,
+  } = {},
+) {
+  if (agent.codexAccountId) {
+    if (agent.runtime !== "codex") throw new TypeError("订阅登录仅支持 Codex");
+    return { variables: { HOME: "/job/runtime-home", CODEX_HOME: "/job/runtime-home/codex", CITEARK_CODEX_ACCOUNT_ID: agent.codexAccountId } };
+  }
+  if (agent.runtime === "claude-code") {
+    return runtimeSecretEnvironment({
+      credentialName: "ANTHROPIC_API_KEY",
+      secretResource,
+      providerCredentialBroker,
+      variables: {
+        HOME: "/job/runtime-home",
+        ANTHROPIC_BASE_URL: agent.api.baseUrl,
+        ANTHROPIC_MODEL: agent.model,
+        ANTHROPIC_DEFAULT_OPUS_MODEL: agent.model,
+        ANTHROPIC_DEFAULT_SONNET_MODEL: agent.model,
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: agent.subagentModel,
+        CLAUDE_CODE_SUBAGENT_MODEL: agent.subagentModel,
+        CLAUDE_CODE_EFFORT_LEVEL: agent.effort,
+        CLAUDE_CODE_AUTO_COMPACT_WINDOW: String(agent.autoCompactWindow),
+        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+      },
+    });
+  }
+  if (agent.runtime === "codex") {
+    return runtimeSecretEnvironment({
+      credentialName: "OPENAI_API_KEY",
+      secretResource,
+      providerCredentialBroker,
+      variables: {
+        HOME: "/job/runtime-home",
+        CODEX_HOME: "/job/runtime-home/codex",
+        ...(providerRelay ? {
+          CITEARK_PROVIDER_UPSTREAM_BASE_URL: stripOpenAiVersion(agent.api.baseUrl),
+          CITEARK_CODEX_UPSTREAM_BASE_URL: stripOpenAiVersion(agent.api.baseUrl),
+          CITEARK_CODEX_REASONING_MODE: agent.reasoningMode,
+          CITEARK_CODEX_RELAY_PORT: "4317",
+          CITEARK_PROVIDER_REQUEST_TIMEOUT_SECONDS: String(providerRequestTimeoutSeconds),
+        } : {}),
+      },
+    });
+  }
+  if (nativeDeepSeekProvider(agent)) {
+    return runtimeSecretEnvironment({
+      credentialName: "DEEPSEEK_API_KEY",
+      secretResource,
+      providerCredentialBroker,
+      variables: {
+        HOME: "/job/runtime-home",
+        OPENCODE_DISABLE_AUTOUPDATE: "1",
+      },
+    });
+  }
+  const config = {
+    $schema: "https://opencode.ai/config.json",
+    model: openCodeModelReference(agent),
+    // Task-local scientific inputs and outputs sit outside repository cwd.
+    // Explicit rules also reach child sessions, whose asks --auto may not handle.
+    permission: {
+      external_directory: {
+        "/job/input/paper/**": "allow",
+        "/job/input/reference-materials.json": "allow",
+        "/job/output/**": "allow",
+        // Tool-created temporary files belong to this disposable worker too.
+        "/tmp/**": "allow",
+      },
+    },
+    provider: {
+      citeark: {
+        npm: "@ai-sdk/openai-compatible",
+        name: "CiteArk Direct Provider",
+        options: {
+          baseURL: providerRelay
+            ? "http://127.0.0.1:4317/v1"
+            : agent.api.baseUrl,
+          apiKey: "{env:CITEARK_API_KEY}",
+        },
+        models: { [agent.model]: openCodeModelDefinition(agent) },
+      },
+    },
+  };
+  return runtimeSecretEnvironment({
+    credentialName: "CITEARK_API_KEY",
+    secretResource,
+    providerCredentialBroker,
+    variables: {
+      HOME: "/job/runtime-home",
+      OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
+      OPENCODE_DISABLE_AUTOUPDATE: "1",
+      ...(providerRelay ? {
+        CITEARK_PROVIDER_UPSTREAM_BASE_URL: stripOpenAiVersion(agent.api.baseUrl),
+        CITEARK_CODEX_REASONING_MODE: agent.reasoningMode,
+        CITEARK_CODEX_RELAY_PORT: "4317",
+        CITEARK_PROVIDER_REQUEST_TIMEOUT_SECONDS: String(providerRequestTimeoutSeconds),
+      } : {}),
+    },
+  });
+}
+
+function usesProviderRelay(agent) {
+  if (agent.billingMode === "user_byok") return false;
+  return agent.reasoningMode === "pro"
+    || (agent.runtime === "opencode" && !nativeDeepSeekProvider(agent));
+}
+
+function runtimeSecretEnvironment({ credentialName, secretResource, providerCredentialBroker, variables }) {
+  return {
+    variables: {
+      ...variables,
+      CITEARK_PROVIDER_SECRET_ENV_NAME: credentialName,
+      ...(providerCredentialBroker
+        ? {
+            CITEARK_PROVIDER_CREDENTIAL_URL: providerCredentialBroker.url,
+            CITEARK_PROVIDER_CREDENTIAL_TOKEN: providerCredentialBroker.token,
+          }
+        : { CITEARK_PROVIDER_SECRET_RESOURCE: secretResource }),
+    },
+  };
+}
+
+function normalizeProviderCredentialBroker(value, issues) {
+  if (value === undefined || value === null) return null;
+  try {
+    const url = new URL(value.url);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+      issues.push("BYOK 凭据代理必须是无凭据、无查询参数的 HTTPS 地址");
+    }
+  } catch {
+    issues.push("BYOK 凭据代理地址无效");
+  }
+  if (typeof value.token !== "string" || value.token.length < 32 || value.token.length > 4096) {
+    issues.push("BYOK 凭据代理令牌无效");
+  }
+  return { url: value.url, token: value.token };
+}
+
+export function resolveCheckpointObjects(config, attempt) {
+  const prefix = checkpointObjectPrefix(config.stagingPrefix, attempt);
+  return { prefix, status: checkpointStatusObject(prefix) };
+}
+
+function labels(runId, attempt, workload = "reproduction") {
+  return {
+    citeark: workload,
+    "citeark-run": runId.toLowerCase().replaceAll(/[^a-z0-9_-]/g, "-").slice(0, 63),
+    "citeark-attempt": String(attempt),
+  };
+}
+
+function normalizeAcceleratorType(value) {
+  const normalized = String(value ?? "").toLowerCase();
+  const known = {
+    l4: "nvidia-l4",
+    t4: "nvidia-tesla-t4",
+    a100: "nvidia-tesla-a100",
+    "a100-40gb": "nvidia-tesla-a100",
+    "a100-80gb": "nvidia-a100-80gb",
+    h100: "nvidia-h100-80gb",
+  };
+  return known[normalized] ?? value;
+}
+
+function stripOpenAiVersion(value) {
+  return value.replace(/\/$/, "").replace(/\/v1$/, "");
+}
+
+function first(...values) {
+  return values.find((value) => typeof value === "string" && value.trim())?.trim() ?? null;
+}
+
+function remoteImage(value) {
+  const registry = String(value ?? "").split("/")[0];
+  return registry.includes(".") || registry === "localhost";
+}
+
+function positiveInteger(value, fallback) {
+  const numeric = value === undefined || value === null ? fallback : Number(value);
+  if (!Number.isInteger(numeric) || numeric <= 0) throw new TypeError("GCP Batch 数值参数必须是正整数");
+  return numeric;
+}
+
+function nonNegativeInteger(value, fallback) {
+  const numeric = value === undefined || value === null ? fallback : Number(value);
+  if (!Number.isInteger(numeric) || numeric < 0) throw new TypeError("GCP Batch 重试次数必须是非负整数");
+  return numeric;
+}

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

@@ -0,0 +1,81 @@
+import { recordResearchCleanup } from '../workspace/control.mjs';
+import {
+  acquireCodexAccountLock,
+  codexAccountLockReference,
+  releaseCodexAccountLock,
+} from "./codex-account-lock.mjs";
+
+/**
+ * Batch 资源和 Codex 账号锁必须由同一个生命周期拥有。
+ * 创建失败在这里回滚锁；调用方只记录成功创建的 Job。
+ */
+export async function createLockedBatchJob({
+  storage,
+  batch,
+  bucket,
+  accountId,
+  owner,
+  jobId,
+  job,
+}) {
+  const jobName = batch.jobName(jobId);
+  const lock = await acquireCodexAccountLock({
+    storage,
+    batch,
+    bucket,
+    accountId,
+    owner,
+    jobName,
+  });
+  try {
+    return await batch.createJob(jobId, job);
+  } catch (error) {
+    await releaseCodexAccountLock({ storage, lock }).catch(() => undefined);
+    throw error;
+  }
+}
+
+export async function releaseBatchJobAccountLock({
+  storage,
+  bucket,
+  accountId,
+  owner,
+  jobName,
+  record,
+}) {
+  const lock = codexAccountLockReference({
+    bucket,
+    accountId,
+    owner,
+    jobName,
+  });
+  if (!lock || record?.codexAccountLockReleased) return;
+  try {
+    const result = await releaseCodexAccountLock({ storage, lock });
+    if (result.reason !== "owner-mismatch" && record) {
+      record.codexAccountLockReleased = true;
+    }
+  } catch (error) {
+    if (record) {
+      record.cleanupErrors = [
+        ...(record.cleanupErrors ?? []),
+        error instanceof Error ? error.message : String(error),
+      ];
+    }
+  }
+}
+
+export async function deleteBatchJob({ batch, record }) {
+  if (!record?.name || record.jobDeletionRequested === true) return;
+  try {
+    await batch.deleteJob(record.name);
+    record.jobDeletionRequested = true;
+  } catch (error) {
+    record.jobDeletionRequested = false;
+    record.cleanupErrors = [
+      ...(record.cleanupErrors ?? []),
+      error instanceof Error ? error.message : String(error),
+    ];
+  }
+  await recordResearchCleanup({ provider: 'gcp-batch', resource: record.name, status: record.jobDeletionRequested ? 'requested' : 'failed', ...(record.cleanupErrors?.length ? { error: record.cleanupErrors.at(-1) } : {}) });
+}