@citeark/agent 0.3.20

package/src/workloads/definition.mjs

@@ -0,0 +1,74 @@
+const AGENT_MODES = new Set(["autonomous", "bounded"]);
+
+const REQUIRED_HOOKS = [
+  "instructions",
+  "prompt",
+  "resumePrompt",
+  "validate",
+  "finalize",
+  "isSucceeded",
+];
+
+/**
+ * Define the contract between an autonomous/bounded Agent workload and the
+ * infrastructure runner. The runner owns isolation, checkpoints and transport;
+ * the workload owns the Agent's task, decisions and result semantics.
+ */
+export function defineAgentWorkload(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("Agent 工作负载定义必须是对象");
+  }
+  if (typeof definition.workload !== "string" || !definition.workload.trim()) {
+    throw new TypeError("Agent 工作负载必须声明 workload");
+  }
+  validateAgentBoundary(definition.agentBoundary);
+  for (const hook of REQUIRED_HOOKS) {
+    if (typeof definition[hook] !== "function") {
+      throw new TypeError(`Agent 工作负载 ${definition.workload} 缺少 ${hook} hook`);
+    }
+  }
+  return Object.freeze({
+    validateScientificComputeDecision: true,
+    controllerValidationRetries: 0,
+    completionRelativePath: "output/result.json",
+    completionHasEvidence: true,
+    recoverFinalMessage: true,
+    ...definition,
+    agentBoundary: Object.freeze({
+      ...definition.agentBoundary,
+      decisionRights: Object.freeze([...definition.agentBoundary.decisionRights]),
+      immutableConstraints: Object.freeze([...definition.agentBoundary.immutableConstraints]),
+    }),
+  });
+}
+
+export function agentWorkloadMetadata(workload) {
+  const definition = defineAgentWorkload(workload);
+  return {
+    schemaVersion: "1.0",
+    workload: definition.workload,
+    agentBoundary: {
+      mode: definition.agentBoundary.mode,
+      decisionRights: [...definition.agentBoundary.decisionRights],
+      immutableConstraints: [...definition.agentBoundary.immutableConstraints],
+    },
+  };
+}
+
+function validateAgentBoundary(boundary) {
+  if (!boundary || typeof boundary !== "object" || Array.isArray(boundary)) {
+    throw new TypeError("Agent 工作负载必须声明 agentBoundary");
+  }
+  if (!AGENT_MODES.has(boundary.mode)) {
+    throw new TypeError("agentBoundary.mode 必须是 autonomous 或 bounded");
+  }
+  for (const field of ["decisionRights", "immutableConstraints"]) {
+    if (
+      !Array.isArray(boundary[field])
+      || boundary[field].length === 0
+      || boundary[field].some((item) => typeof item !== "string" || !item.trim())
+    ) {
+      throw new TypeError(`agentBoundary.${field} 必须是非空字符串数组`);
+    }
+  }
+}

package/src/workloads/phase-aware-reproduction.mjs

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { updateRunState } from "../job.mjs";
+import { resolveResearchPlan } from "../reproduction/plan.mjs";
+import { readAgentUsage } from "../telemetry/usage.mjs";
+import { CiteArkError, readJson } from "../util.mjs";
+import { createAutonomousReproductionWorkload } from "./reproduction.mjs";
+import { defineAgentWorkload } from "./definition.mjs";
+
+const handoffInstruction = `This GPU phase resumes the same CPU-prepared workspace. Read output/cpu-preparation.json and progress.md, inspect live work and reuse prepared inputs. Use the GPU for actual scientific execution and necessary device-specific debugging. If a substantial download, build or other CPU-only preparation remains, stop GPU work and request a CPU continuation by writing output/result.json as {"schemaVersion":"2.0","status":"handoff","nextPhase":"cpu","summary":"Concrete remaining CPU work and why the GPU can be released"}. Preserve all raw results and the current plan first; do not keep an idle GPU rented while doing that preparation. A handoff is not a scientific result. Once the actual computation is done, save its raw outputs and finish with the normal completed/partial/failed summary; CPU coordination performs parsing, independent assessment and publication. All phases share the original cumulative budget.`;
+
+export function createPhaseAwareReproductionWorkload() {
+  const actor = createAutonomousReproductionWorkload();
+  return defineAgentWorkload({
+    ...actor,
+    allowCpuHandoff: true,
+    completionSuccessJq: `(${actor.completionSuccessJq}) or (.schemaVersion == "2.0" and .status == "handoff" and .nextPhase == "cpu")`,
+    prompt: (options) => `${actor.prompt(options)}\n${handoffInstruction}`,
+    resumePrompt: (options) => `${actor.resumePrompt(options)}\n${handoffInstruction}`,
+    async validate(options) {
+      const result = await readJson(options.completionPath).catch(() => null);
+      if (result?.status !== "handoff") return actor.validate(options);
+      const issues = [];
+      if (result.schemaVersion !== "2.0" || result.nextPhase !== "cpu"
+        || typeof result.summary !== "string" || !result.summary.trim()) issues.push("Invalid CPU continuation request");
+      try { await resolveResearchPlan(options.bundle.runtimeTask, options.bundle.directories.output); }
+      catch (error) { issues.push(error.message); }
+      return { result, issues, phaseHandoff: true, protocolVerification: null };
+    },
+    recover: (options) => options.validation.phaseHandoff ? options.validation : actor.recover(options),
+    // Handoffs retain their durable checkpoint; normal terminal outcomes use
+    // the existing completion/retention policy.
+    isSucceeded: (result, issues) => result?.status !== "handoff" && actor.isSucceeded(result, issues),
+    async finalize(options) {
+      if (!options.validation.phaseHandoff) return actor.finalize(options);
+      const { bundle, validation, checkpoint, attempts, timedOut, cloudExecution } = options;
+      if (validation.issues.length || timedOut || checkpoint?.kind !== "full") throw new CiteArkError(
+        "GPU 转 CPU 需要有效交接记录和完整检查点", { failureCode: "research.handoff_incomplete", retryable: false });
+      const usage = await readAgentUsage(path.join(bundle.directories.execution, "trace.jsonl"), {
+        runtimeHome: bundle.directories.runtimeHome, model: bundle.runtimeAgent.model,
+      });
+      await updateRunState(bundle, { status: "completed", finishedAt: new Date().toISOString(),
+        usage, attempts, cloudExecution, phaseHandoff: validation.result });
+      return { bundle, checkpoint, phaseHandoff: validation.result };
+    },
+  });
+}

package/src/workloads/reproduction.mjs

@@ -0,0 +1,85 @@
+import { readAgentInstructions, ensureFinalWorkspaceCapture } from "../job.mjs";
+import { usesWorkspaceSummary } from "../reproduction/workspace-mode.mjs";
+import { validateResultFile } from "../protocol.mjs";
+import {
+  finalizeReproduction,
+  recoverInvalidExecutionResult,
+} from "../reproduction/lifecycle.mjs";
+import {
+  initialReproductionPrompt,
+  retryReproductionPrompt,
+} from "../reproduction/prompts.mjs";
+import {
+  infrastructureResumePrompt,
+  targetRecoveryPrompt,
+} from "../compute/checkpoint-protocol.mjs";
+import { defineAgentWorkload } from "./definition.mjs";
+
+/**
+ * The scientific reproduction Agent is intentionally one complete autonomous
+ * actor. Platform modules may prepare inputs and verify outputs, but they do not
+ * decompose or prescribe the Agent's reasoning and experimental loop.
+ */
+export function createAutonomousReproductionWorkload() {
+  return defineAgentWorkload({
+    workload: "reproduction",
+    agentBoundary: {
+      mode: "autonomous",
+      decisionRights: [
+        "inspect_fixed_research_materials",
+        "install_or_replace_task_local_dependencies",
+        "plan_and_revise_execution_commands",
+        "revise_source_grounded_research_plan_when_enabled",
+        "author_and_debug_helper_implementations",
+        "run_bounded_probes_and_iterate",
+        "acquire_and_verify_public_transports",
+        "delegate_within_the_agent_runtime_budget",
+        "collect_and_diagnose_execution_evidence",
+      ],
+      immutableConstraints: [
+        "original_research_goal_and_input_identity",
+        "allocated_compute_and_time_ceiling",
+        "sandbox_security_boundary",
+        "auditable_evidence_and_result_protocol",
+      ],
+    },
+    validateScientificComputeDecision: true,
+    completionRelativePath: "output/result.json",
+    completionSuccessJq: '.execution.status == "succeeded" or (.schemaVersion == "2.0" and (.status == "completed" or .status == "partial" or .status == "failed"))',
+    completionHasEvidence: true,
+    recoverFinalMessage: true,
+    instructions: (bundle) => readAgentInstructions(bundle.runtimeTask),
+    prompt({ bundle, attempt, validation }) {
+      return attempt === 1
+        ? initialReproductionPrompt(bundle)
+        : retryReproductionPrompt(validation.issues, bundle.runtimeTask);
+    },
+    resumePrompt({ bundle, targetRecovery }) {
+      return targetRecovery
+        ? targetRecoveryPrompt(bundle)
+        : infrastructureResumePrompt(bundle);
+    },
+    async validate({ bundle, completionPath }) {
+      if (usesWorkspaceSummary(bundle.runtimeTask)) await ensureFinalWorkspaceCapture(bundle);
+      return await validateResultFile(
+        completionPath,
+        bundle.runtimeTask,
+        bundle.directories.output,
+      );
+    },
+    async recover({ bundle, validation, attempts, timedOut }) {
+      return await recoverInvalidExecutionResult({
+        bundle,
+        validation,
+        attempts,
+        timedOut,
+      });
+    },
+    async finalize(options) {
+      return await finalizeReproduction(options);
+    },
+    isSucceeded(result, issues) {
+      return issues.length === 0 && result?.execution?.status === "succeeded";
+    },
+  });
+}

package/src/workspace/command.mjs

@@ -0,0 +1,242 @@
+import { readSettings, resolveModelProfile, savedModel } from '../settings/store.mjs';
+import { resolveAgentRuntime } from '../runtime/config.mjs';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { TerminalScreen } from '../terminal/screen.mjs';
+import { PlainSession } from '../terminal/plain.mjs';
+import { withSessionEvents, sessionEvent } from '../terminal/events.mjs';
+import { promptResearchEntry } from './entry.mjs';
+import { readFile, mkdir } from 'node:fs/promises';
+import { prepareResearchInput } from './input.mjs';
+import { planWorkspace, executeWorkspace, ensureSigningKey } from './session.mjs';
+import { createTerminalPrompter, cancelled } from '../deployment/terminal.mjs';
+import { configureLocalModel, readLocalPreferences, writeLocalPreferences } from '../deployment/guided.mjs';
+import { inspectLocalDocker, setupLocalRuntime } from '../deployment/environment.mjs';
+import { captureProcess } from '../process.mjs';
+import { readJson, writeJson, pathExists } from '../util.mjs';
+import { publishLocalCap } from '../deployment/local.mjs';
+
+export async function startResearch(argv, helpers) {
+  if (!process.env.CITEARK_JOB_WORKER) {
+    const settings = await readSettings();
+    const i = argv.indexOf('--compute'); const name = i >= 0 ? argv[i + 1] : argv.includes('--resume') ? undefined : settings.defaultCompute;
+    const hasInput = ['--paper', '--cap', '--repository-id', '--resume'].some(flag => argv.includes(flag)) || (argv[0] && !argv[0].startsWith('-'));
+    if (hasInput && name && settings.compute[name]?.type === 'ssh') return (await import('../remote/command.mjs')).startRemoteResearch(argv, settings.compute[name], name);
+    if (argv.includes('--background')) {
+      const job = await (await import('./jobs.mjs')).launchJob(argv);
+      console.log(JSON.stringify(job)); return job;
+    }
+  }
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== 'dumb'
+    && !argv.some(value => ['--plain', '--non-interactive', '--dry-run'].includes(value));
+  const args = argv.filter(value => value !== '--plain');
+  if (argv.includes('--dry-run')) return runResearch(args, helpers);
+  if (!interactive) {
+    const output = new PlainSession();
+    try { return await withSessionEvents(event => output.event(event), () => runResearch(args, helpers, null, output)); }
+    finally { await output.close(); }
+  }
+  const version = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+  const screen = new TerminalScreen({ version, onExit: async () => {
+    screen.event({ kind: 'status', text: 'CLI disconnected. Compute may continue; use the workspace to resume.' });
+    await screen.close();
+    console.log('CLI disconnected. Compute may continue; use the workspace to resume.');
+    process.exit(130);
+  } });
+  screen.start();
+  try {
+    const result = await withSessionEvents(event => screen.event(event), () => runResearch(args, helpers, screen, screen));
+    if (!screen.closed) await screen.finish(result?.phase === 'completed' ? 'Completed' : 'Plan saved');
+    return result;
+  } catch (error) {
+    screen.event({ kind: 'error', text: error.message });
+    if (error.exitCode !== 130) await screen.finish('Stopped');
+    throw error;
+  } finally { await screen.close(); }
+}
+
+async function runResearch(argv, { parseOptions, agentEntryOptions, gcpEntryOptions, autoDlEntryOptions,
+  agentRuntimeOptions, executorOptions }, screen = null, output = null) {
+  let reference = argv[0] && !argv[0].startsWith('-') ? argv.shift() : null;
+  const optionalAgent = Object.fromEntries(Object.entries(agentEntryOptions()).map(([k,v]) => [k, { ...v, required: false }]));
+  const options = parseOptions(argv, { ...optionalAgent, ...gcpEntryOptions(), ...autoDlEntryOptions(),
+    '--paper': { type: 'string' }, '--repository': { type: 'string' }, '--cap': { type: 'string' },
+    '--repository-id': { type: 'string' }, '--run': { type: 'string' }, '--goal': { type: 'string' },
+    '--guide': { type: 'string' }, '--experiments': { type: 'string' }, '--work-dir': { type: 'string' },
+    '--compute-catalog': { type: 'string' }, '--compute-policy': { type: 'string' }, '--compute-profile': { type: 'string' },
+    '--platform': { type: 'string', default: 'https://citeark.com' },
+    '--device': { type: 'string', default: 'cpu' }, '--image': { type: 'string' },
+    '--resume': { type: 'boolean', default: false }, '--plan-only': { type: 'boolean', default: false },
+    '--non-interactive': { type: 'boolean', default: false }, '--dry-run': { type: 'boolean', default: false },
+    '--signing-key': { type: 'string' },
+    '--model-profile': { type: 'string' }, '--assessment-profile': { type: 'string' }, '--compute': { type: 'string' },
+    '--change-model': { type: 'boolean', default: false }, '--background': { type: 'boolean', default: false },
+  });
+  if (reference && options['--repository-id']) throw Error('Provide a paper ID or --repository-id, not both.');
+  if (!['cpu', 'cuda'].includes(options['--device'])) throw Error('--device must be cpu or cuda');
+  const dryRun = options['--dry-run'];
+  const prompt = !dryRun && !options['--non-interactive'] && process.stdin.isTTY && process.stdout.isTTY
+    ? screen ?? createTerminalPrompter() : null;
+  reference = await promptResearchEntry({ options, reference, prompt });
+  if (!reference && !options['--repository-id'] && !options['--paper'] && !options['--cap'] && !options['--resume']) {
+    throw Error('Provide --paper, --cap, or a paper ID. Run citeark in a terminal for guided setup.');
+  }
+  if (options['--resume'] && !options['--work-dir']) throw Error('Provide --work-dir to resume a workspace.');
+  const settings = await readSettings();
+  const chosenCompute = options['--compute'] ?? (!options['--resume'] ? settings.defaultCompute : undefined);
+  if (!process.env.CITEARK_JOB_WORKER && settings.compute[chosenCompute]?.type === 'ssh') {
+    if (options['--goal'] === undefined && prompt) options['--goal'] = await prompt.ask('What would you like to investigate? (optional)');
+    const remoteArgs = [...(reference ? [reference] : []), ...Object.entries(options).flatMap(([key, value]) => value === undefined || value === false ? [] : value === true ? [key] : [key, String(value)])];
+    await screen?.close();
+    return (await import('../remote/command.mjs')).startRemoteResearch(remoteArgs, settings.compute[chosenCompute], chosenCompute);
+  }
+  const root = path.resolve(options['--work-dir'] ?? `citeark-research-${Date.now()}`);
+  const sessionPath = path.join(root, 'workspace.json');
+  if (!options['--resume'] && await pathExists(root) && !process.env.CITEARK_JOB_WORKER) throw Error('Choose a new workspace directory or use --resume to continue.');
+  let saved = options['--resume'] ? await readJson(sessionPath) : null;
+  if (saved?.executorSettings) for (const [key, value] of Object.entries(saved.executorSettings)) if (!argv.includes(key)) options[key] = value;
+  if (output && saved) await output.attach(path.join(root, 'session.events.jsonl'));
+  if (saved?.phase === 'completed') {
+    console.log(`Research completed: ${saved.artifacts.join('\n')}`);
+    return saved;
+  }
+  if (options['--resume'] && [reference, options['--paper'], options['--cap'], options['--goal'], options['--repository']].some(Boolean)) {
+    throw Error('Resuming uses the saved sources and goal. Create a new workspace to change them.');
+  }
+  await mkdir(root, { recursive: true });
+  if (output && !saved) await output.attach(path.join(root, 'session.events.jsonl'));
+  if (screen) screen.context = root;
+  sessionEvent({ kind: 'stage', stage: 'intake', status: 'Running' });
+  let goal = options['--goal'];
+  if (!saved && goal === undefined && prompt) goal = await prompt.ask('What would you like to investigate? (optional)');
+  const input = saved?.input ?? await prepareResearchInput({ directory: path.join(root, 'input'),
+    paper: options['--paper'], repository: options['--repository'], capPath: options['--cap'],
+    reference: options['--repository-id'] ?? reference, baseUrl: options['--platform'], runId: options['--run'],
+    goal, guide: options['--guide'] ? await readFile(options['--guide'], 'utf8') : '' });
+  if (screen) screen.context = `${input.title ?? 'Research'} · ${root}`;
+  if (saved && ['--compute', '--compute-catalog', '--compute-policy', '--compute-profile', '--image'].some(key => options[key])) throw Error('Resuming uses the saved compute configuration. Start a new workspace to select different resources.');
+  const computeName = options['--compute'] ?? (!saved ? settings.defaultCompute : undefined);
+  const compute = computeName ? settings.compute[computeName] : null;
+  if (computeName && !compute) throw Error(`Unknown compute profile: ${computeName}`);
+  if (compute?.type === 'ssh') throw Error('Use the SSH session entry to start research on this server.');
+  if (compute?.type === 'catalog' && !saved) {
+    options['--compute-catalog'] ??= compute.catalog; options['--compute-policy'] ??= compute.policy; options['--compute-profile'] ??= compute.profile;
+  }
+  if (compute?.type === 'local') { options['--device'] = compute.device; options['--image'] ??= compute.image; }
+  let catalogPath = saved?.computeCatalogPath ?? options['--compute-catalog'];
+  if (!catalogPath && prompt) catalogPath = await prompt.ask('Compute configuration file (leave empty for local Docker)');
+  const profile = saved?.computeProfile ?? options['--compute-profile'];
+  const policyPath = saved?.computePolicyPath ?? options['--compute-policy'];
+  if (!catalogPath && !dryRun) {
+    const host = await inspectLocalDocker();
+    const gpu = options['--device'] === 'cuda';
+    if (gpu && (host.hostPlatform === 'darwin' || host.architecture !== 'amd64')) throw Error('CUDA is unavailable on this machine. Select remote compute or a CPU experiment.');
+    const image = options['--image'] ?? `citeark-agent/runtime:${gpu ? 'cuda' : 'cpu'}`;
+    const available = await captureProcess('docker', ['image', 'inspect', image]);
+    if (available.code) {
+      if (!prompt || !await prompt.confirm('Prepare the local research environment?')) throw Error(`Run citeark setup first${gpu ? ' --gpu' : ''}`);
+      await setupLocalRuntime({ gpu });
+    }
+    const catalog = { schemaVersion: '0.1', profiles: [{ id: 'user-local', label: 'Local Docker', executor: 'local-docker',
+      accelerator: gpu ? 'gpu' : 'cpu', image, cpuCores: host.cpus, memoryGb: Math.floor(host.memoryGb), hourlyUsd: 0, available: true }] };
+    if (gpu) {
+      const { checkLocalExecution } = await import('../deployment/environment.mjs');
+      const check = await checkLocalExecution({ environment: { image, gpu: 'all', cpus: 1, memoryGb: 1 }, compute: {} });
+      const gpus = check.observed.gpus;
+      catalog.profiles[0].gpu = { type: gpus[0].name, count: gpus.length, vramGb: Math.floor(Math.min(...gpus.map(g => g.memoryGb))) };
+    }
+    catalogPath = path.join(root, 'compute.json');
+    await writeJson(catalogPath, catalog);
+  }
+  catalogPath = catalogPath ? path.resolve(catalogPath) : undefined;
+  let policy = policyPath ? path.resolve(policyPath) : undefined;
+  if (!saved) {
+    if (catalogPath) { const catalog = await readJson(catalogPath); catalogPath = path.join(root, 'compute.json'); await writeJson(catalogPath, catalog); }
+    if (policy) { const limits = await readJson(policy); policy = path.join(root, 'compute-policy.json'); await writeJson(policy, limits); }
+  }
+  if (!saved) {
+    const task = await readJson(input.compileTaskPath);
+    if (catalogPath) {
+      const catalog = await readJson(catalogPath);
+      const limits = policy ? await readJson(policy) : {};
+      task.computeContext = { profiles: catalog.profiles, limits: { maximumCost: limits.maxEstimatedComputeUsd ?? null }, computePolicy: limits };
+    }
+    if (catalogPath) {
+      const catalog = await readJson(catalogPath);
+      const compiler = catalog.profiles.find(item => item.id === profile)
+        ?? catalog.profiles.find(item => item.available !== false && item.accelerator === 'cpu')
+        ?? catalog.profiles.find(item => item.available !== false);
+      if (compiler?.executor === 'local-docker' && compiler.image) task.environment.image = compiler.image;
+    }
+    if (options['--image']) task.environment.image = options['--image'];
+    await writeJson(input.compileTaskPath, task);
+  }
+  const overridingModel = ['--model-profile', '--assessment-profile', '--agent', '--model', '--api-base-url', '--effort', '--subagent-model', '--model-budget'].some(k => options[k]);
+  if (saved?.modelConfiguration && overridingModel && !options['--change-model']) throw Error('Resuming uses the saved model. Add --change-model to record an explicit model change.');
+  const selected = saved?.modelConfiguration && !options['--change-model'] ? saved.modelConfiguration
+    : resolveModelProfile(settings, options['--model-profile']) ?? await readLocalPreferences();
+  const keyEnvironment = options['--api-key-env'] ?? selected?.apiKeyEnv;
+  const explicit = { ...selected, runtime: options['--agent'] ?? selected?.runtime,
+    apiBaseUrl: options['--api-base-url'] ?? selected?.apiBaseUrl ?? process.env.CITEARK_MODEL_API_URL,
+    model: options['--model'] ?? selected?.model ?? process.env.CITEARK_MODEL,
+    apiKeyEnv: keyEnvironment, apiKey: options['--api-key'] ?? (keyEnvironment ? process.env[keyEnvironment] : selected?.apiKey ?? process.env.CITEARK_MODEL_API_KEY),
+    apiKeySource: keyEnvironment ? `env:${keyEnvironment}` : options['--api-key'] ? 'parameter' : process.env.CITEARK_MODEL_API_KEY ? 'env:CITEARK_MODEL_API_KEY' : 'local-session',
+    subagentModel: options['--subagent-model'] ?? selected?.subagentModel,
+    effort: options['--effort'] ?? selected?.effort,
+    maxBudgetUsd: options['--model-budget'] ? Number(options['--model-budget']) : selected?.maxBudgetUsd };
+  const runtime = prompt ? await configureLocalModel({ options: explicit, saved: selected ?? {}, prompt })
+    : { ...explicit, runtime: explicit.runtime ?? 'opencode', apiBaseUrl: explicit.apiBaseUrl ?? (dryRun ? 'https://api.invalid' : undefined), model: explicit.model ?? (dryRun ? 'dry-run' : undefined) };
+  resolveAgentRuntime({ ...runtime, requireApi: !dryRun && !options['--gcp-provider-secret'] && !process.env.CITEARK_GCP_PROVIDER_SECRET });
+  if (prompt) await writeLocalPreferences(runtime);
+  const assessmentConfig = options['--assessment-profile'] ? resolveModelProfile(settings, options['--assessment-profile']) : saved?.assessmentConfiguration;
+  const assessmentRuntime = assessmentConfig ? { ...assessmentConfig, apiKey: assessmentConfig.apiKeyEnv ? process.env[assessmentConfig.apiKeyEnv] : assessmentConfig.apiKey } : runtime;
+  if (assessmentConfig) resolveAgentRuntime({ ...assessmentRuntime, requireApi: !dryRun });
+  const previous = saved ?? { schemaVersion: '1.0', input, computeCatalogPath: catalogPath, computePolicyPath: policy, computeProfile: profile, phase: 'planning', artifacts: [] };
+  if (options['--change-model'] && saved?.modelConfiguration) previous.modelChanges = [...(previous.modelChanges ?? []), { at: new Date().toISOString(), previous: saved.modelConfiguration, next: savedModel(runtime) }];
+  previous.executorSettings = Object.fromEntries(Object.entries(options).filter(([key, value]) => value !== undefined && (key.startsWith('--gcp-') || key.startsWith('--autodl-') || key === '--allow-remote-model-key')));
+  previous.modelConfiguration = savedModel(runtime);
+  if (assessmentConfig) previous.assessmentConfiguration = savedModel(assessmentRuntime);
+  await writeJson(sessionPath, previous);
+  const signingKeyPath = dryRun ? options['--signing-key'] : await ensureSigningKey(options['--signing-key']);
+  if (screen) screen.context += ` · ${runtime.model}`;
+  if (screen && !process.env.CITEARK_JOB_WORKER) {
+    const { interactiveResearch } = await import('./interactive.mjs');
+    const completed = await interactiveResearch({ root, options, screen, runtime, assessmentRuntime, signingKeyPath });
+    if (completed?.phase === 'completed') await offerPublish(completed, { prompt, input, options });
+    return completed;
+  }
+  sessionEvent({ kind: 'stage', stage: 'research_compilation', status: 'Running' });
+  const planned = await planWorkspace({ directory: root, input, agentRuntime: runtime,
+    computeCatalogPath: catalogPath, computePolicyPath: policy, computeProfile: profile,
+    executorOptions: executorOptions(options), signingKeyPath, dryRun, ...(output ? { progress: () => {} } : {}) });
+  if (dryRun) { console.log(`Research inputs prepared (dry run): ${root}`); return planned; }
+  sessionEvent({ kind: 'stage', stage: 'awaiting_selection', status: 'Waiting for experiment selection' });
+  const experiments = planned.research.experiments;
+  console.log(`\nWorkspace: ${root}\nAvailable experiments:`);
+  experiments.forEach((item, index) => console.log(`${index + 1}. ${item.id} — ${item.title}`));
+  let experimentIds = options['--experiments']?.split(',').map(id => id.trim()).filter(Boolean);
+  if (!planned.session.targets && !experimentIds?.length && !options['--plan-only'] && prompt) {
+    const selected = await prompt.ask('Select experiment numbers (comma-separated; leave empty to save the plan)');
+    experimentIds = selected ? selected.split(',').map(value => experiments[Number(value.trim()) - 1]?.id ?? value.trim()) : [];
+  }
+  if (options['--plan-only'] || (!planned.session.targets && !experimentIds?.length)) {
+    console.log(`Plan saved. Continue with citeark start --resume --work-dir ${JSON.stringify(root)} --experiments <experiment-id>`);
+    return planned.session;
+  }
+  if (prompt && !await prompt.confirm('Run the selected experiments?')) throw cancelled();
+  const completed = await executeWorkspace({ directory: root, experimentIds, agentRuntime: runtime, assessmentRuntime,
+    executorOptions: executorOptions(options), signingKeyPath, ...(output ? { progress: () => {} } : {}) });
+  console.log(`Signed research artifacts saved locally:\n${completed.artifacts.join('\n')}`);
+  await offerPublish(completed, { prompt, input, options });
+  sessionEvent({ kind: 'stage', stage: 'completed', status: 'Completed' });
+  return completed;
+}
+
+async function offerPublish(completed, { prompt, input, options }) {
+  if (prompt && await prompt.confirm('Upload this plan and its results to CiteArk?')) {
+    const token = process.env.CITEARK_API_KEY ?? await prompt.ask('CiteArk API key (hidden)', { secret: true });
+    const visibility = input.platformRepositoryId && await prompt.confirm('Publish as a public community result for this paper?') ? 'public' : 'private';
+    for (const capPath of completed.artifacts) console.log(JSON.stringify(await publishLocalCap({ capPath,
+      repositoryId: input.platformRepositoryId, baseUrl: options['--platform'], token, visibility })));
+  }
+}

package/src/workspace/control.mjs

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const context = new AsyncLocalStorage();
+export const withResearchControl = (control, action) =>
+  context.run(control, action);
+export const researchInstructions = async () =>
+  (await context.getStore()?.instructions?.()) ?? "";
+export const recordResearchCleanup = async (record) => {
+  await context.getStore()?.cleanup?.(record);
+};
+export const researchSignal = () => context.getStore()?.signal;
+export async function researchBoundary(stage) {
+  await context.getStore()?.boundary?.(stage);
+  assertResearchActive();
+}
+export function assertResearchActive() {
+  if (researchSignal()?.aborted) throw researchSignal().reason;
+}
+export function cancellationError() {
+  const error = Error("Research cancelled by the user.");
+  error.exitCode = 130;
+  error.processingLeaseLost = true;
+  error.researchCancelled = true;
+  return error;
+}
+export function controlledExecutors(options = {}) {
+  if (!context.getStore()) return options;
+  return {
+    ...options,
+    ...Object.fromEntries(
+      ["gcpBatch", "autoDl"].map((key) => [
+        key,
+        {
+          ...options[key],
+          assertActive: async () => {
+            assertResearchActive();
+            await options[key]?.assertActive?.();
+          },
+          ...(key === "gcpBatch"
+            ? { keepJob: false }
+            : {
+                keepInstance: false,
+                keepFailedInstance: false,
+                releaseOnFailure: true,
+              }),
+        },
+      ]),
+    ),
+  };
+}

package/src/workspace/entry.mjs

@@ -0,0 +1,28 @@
+// Collect missing entry information before entering the existing research flow.
+export async function promptResearchEntry({ options, reference, prompt }) {
+  if (!prompt || reference || ['--paper', '--cap', '--repository-id', '--resume'].some(key => options[key])) return reference;
+  if (prompt.openResearch) return prompt.openResearch(options);
+  const choice = prompt.choose ? await prompt.choose('Start a research session', [
+    { value: '1', label: 'Open a paper' }, { value: '2', label: 'Open a CiteArk paper' },
+    { value: '3', label: 'Use a CAP artifact' }, { value: '4', label: 'Resume a workspace' },
+  ]) : await prompt.ask('Start research: 1 Paper; 2 CiteArk ID; 3 CAP artifact; 4 Resume', { defaultValue: '1' });
+  if (choice === '4') {
+    options['--resume'] = true;
+    options['--work-dir'] = await prompt.ask('Workspace directory');
+    return reference;
+  }
+  if (choice === '2') return await prompt.ask('CiteArk paper ID');
+  if (choice === '1') {
+    options['--paper'] = await prompt.ask('Paper file path or URL');
+    if (!options['--paper']) throw Error('Enter a paper file path or URL.');
+  } else if (choice === '3') {
+    options['--cap'] = await prompt.ask('CAP file path');
+    if (!options['--cap']) throw Error('Enter a CAP file path.');
+    options['--paper'] = await prompt.ask('Paper file or URL (leave empty to use the CAP source)') || undefined;
+  } else {
+    throw Error('Choose 1, 2, 3, or 4.');
+  }
+  options['--repository'] ??= await prompt.ask('Code directory or repository URL (optional)') || undefined;
+  options['--guide'] ??= await prompt.ask('Research guide file (optional)') || undefined;
+  return reference;
+}

package/src/workspace/input.mjs

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { readCapArchive, readCapBlob } from '../cap/v2/read.mjs';
+import { validateCodeFiles } from '../deployment/handoff.mjs';
+import { normalizeResearchStructure } from '../research/structure.mjs';
+import { sha256Value, sha256File, writeJson } from '../util.mjs';
+
+const source = value => /^https?:\/\//.test(value) ? { url: value } : { path: path.resolve(value) };
+
+export async function prepareResearchInput({ directory, paper, repository, capPath, reference,
+  baseUrl = 'https://citeark.com', runId, goal = '', guide = '', token = process.env.CITEARK_API_KEY, fetchImpl = fetch }) {
+  await mkdir(directory, { recursive: true });
+  const platformRequest = url => fetchImpl(url, token && new URL(url).origin === new URL(baseUrl).origin ? { headers: { authorization: `Bearer ${token}` } } : undefined);
+  let platformRepositoryId = null;
+  let title = 'Independent research';
+  let platformPaper = null;
+  if (reference) {
+    const response = await platformRequest(new URL(`/api/v1/repositories/${encodeURIComponent(reference)}/deployment`, baseUrl));
+    if (!response.ok) throw Error(`Unable to read paper details: HTTP ${response.status}`);
+    const { data } = await response.json();
+    platformRepositoryId = data.repositoryId;
+    title = data.title;
+    platformPaper = data.researchInput?.paper ?? null;
+    paper ??= platformPaper?.url ? new URL(platformPaper.url, baseUrl).href : undefined;
+    repository ??= data.researchInput?.repository?.url;
+    const previous = runId ? data.choices?.find(item => item.runId === runId) : data.choices?.[0];
+    if (runId && !previous) throw Error('The selected run has no readable reference CAP.');
+    if (previous && !capPath) {
+      const download = await platformRequest(new URL(previous.archiveUrl, baseUrl));
+      if (!download.ok) throw Error(`Unable to download reference CAP: HTTP ${download.status}`);
+      capPath = path.join(directory, 'reference.cap');
+      await writeFile(capPath, Buffer.from(await download.arrayBuffer()));
+    }
+  }
+  let inventory = null;
+  let materials = null;
+  let artifact = null;
+  if (capPath) {
+    artifact = await readCapArchive(capPath, path.join(directory, 'reference-artifact'));
+    const handoff = await readCapBlob(artifact, 'deployment-handoff');
+    const plan = await readCapBlob(artifact, 'research-plan-input');
+    inventory = await readCapBlob(artifact, 'research-inventory')
+      ?? plan?.sourceInventory?.research ?? handoff?.research?.sourceInventory?.research
+      ?? artifact.records.sourceWork[0]?.citeark?.sourceInventory?.research ?? null;
+    const work = artifact.records.sourceWork[0];
+    title = work?.title ?? title;
+    // A received archive may suggest public sources, never paths on this host.
+    paper ??= work?.sources?.find(item => item.kind === 'paper' && /^https?:\/\//.test(item.uri))?.uri;
+    repository ??= work?.sources?.find(item => item.kind === 'repository' && /^https?:\/\//.test(item.uri))?.uri;
+    materials = { schemaVersion: '1.0', sourceArtifactDigest: artifact.artifactDigest,
+      instructions: handoff?.instructions ?? '', files: handoff ? validateCodeFiles(handoff.files) : [],
+      usage: 'Historical reference only. Choose and plan this research independently; collect fresh observations.' };
+    if (handoff?.instructions) guide = [guide, handoff.instructions].filter(Boolean).join('\n\n');
+  }
+  if (!paper) throw Error('Provide a paper file or URL. This CAP has no accessible paper source.');
+  let paperSource = { ...source(paper), title };
+  if (reference && paperSource.url && new URL(paperSource.url).origin === new URL(baseUrl).origin) {
+    const response = await platformRequest(paperSource.url);
+    if (!response.ok) throw Error(`Unable to read the paper: HTTP ${response.status}`);
+    const filename = path.join(directory, 'paper.pdf');
+    await writeFile(filename, Buffer.from(await response.arrayBuffer()));
+    if (platformPaper?.digest && `sha256:${await sha256File(filename)}` !== platformPaper.digest) throw Error('The downloaded paper does not match its source digest.');
+    paperSource = { path: filename, sourceUrl: paperSource.url, title };
+  }
+  const repositorySource = repository ? source(repository) : undefined;
+  const retainedRepository = inventory?.provenance?.sourceIdentity?.repository;
+  if (repositorySource?.url && retainedRepository?.url === repositorySource.url && retainedRepository.commit) {
+    repositorySource.commit = retainedRepository.commit;
+  }
+  const task = { schemaVersion: '0.1', name: 'independent-research', paper: paperSource,
+    ...(repositorySource ? { repository: repositorySource } : {}),
+    researchGoal: goal, reproductionGuide: guide,
+    compilationStage: inventory ? 'execution_plan' : 'inventory',
+    environment: { image: 'citeark-agent/runtime:cpu', cpus: 2, memoryGb: 4, timeoutMinutes: 45, gpu: 'none' } };
+  if (inventory) {
+    inventory = normalizeResearchStructure(inventory);
+    if (inventory.compilationStage !== 'inventory') throw Error('The CAP does not contain a source inventory.');
+    const inventoryPath = path.join(directory, 'inventory.json');
+    await writeJson(inventoryPath, inventory);
+    task.sourceInventory = { path: inventoryPath, digest: `sha256:${sha256Value(inventory)}` };
+  }
+  const referenceMaterialsPath = materials ? path.join(directory, 'reference-materials.json') : null;
+  if (materials) {
+    await writeJson(referenceMaterialsPath, materials);
+    task.referenceMaterialsPath = referenceMaterialsPath;
+  }
+  const compileTaskPath = path.join(directory, 'task.json');
+  await writeJson(compileTaskPath, task);
+  return { compileTaskPath, referenceMaterialsPath, platformRepositoryId, title,
+    sourceArtifactDigests: artifact ? [artifact.artifactDigest] : [], paper: paperSource,
+    sourceCompilationDigests: artifact?.kind === 'research-compilation' ? [artifact.artifactDigest] : [] };
+}
+