@citeark/agent 0.3.20

package/scripts/review-compiler-sources.mjs

@@ -0,0 +1,44 @@
+// Default is local input preparation only. --apply sends fixed sources and
+// candidates to the configured OpenRouter model using the supplied budget.
+import { readFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareSourceReviewInput, reviewCompilerSources } from '../src/research/source-review.mjs';
+import { writeJson } from '../src/util.mjs';
+const args = process.argv.slice(2);
+const value = (flag) => { const i = args.indexOf(flag); return i < 0 ? null : args[i + 1]; };
+const candidates = args.flatMap((arg, i) => arg === '--candidate' ? [args[i + 1]] : []);
+const paperPath = value('--paper');
+const repositoryRoot = value('--repository');
+const output = value('--output');
+if (!paperPath || !repositoryRoot || !output || !candidates.length) throw new Error('Required: --paper FILE --repository SNAPSHOT --output DIR --candidate FILE (repeatable). Default: no model calls.');
+await mkdir(output, { recursive: true });
+const sources = await prepareSourceReviewInput({ paperPath, repositoryRoot, directory: path.join(output, 'source-review') });
+const manifest = { ...sources.identity, pageCount: sources.pages.length, initialImages: 0,
+  repositoryFiles: sources.repositoryIndex, initialRepositoryContentBytes: 0,
+  orientationBytes: Buffer.byteLength(JSON.stringify(sources.orientation)),
+  sourceIndexBytes: Buffer.byteLength(JSON.stringify({pages:sources.pageIndex,repository:sources.repositoryIndex})),
+  candidateFiles: candidates.map((filename) => path.resolve(filename)), applied: args.includes('--apply') };
+await writeJson(path.join(output, 'input-manifest.json'), manifest);
+if (!args.includes('--apply')) { console.log(JSON.stringify({ status: 'prepared_only', pageCount: manifest.pageCount, files: manifest.repositoryFiles.length, orientationBytes: manifest.orientationBytes, sourceIndexBytes: manifest.sourceIndexBytes })); }
+else {
+  if (!value('--runtime-json') || !value('--budget-json')) throw new Error('--apply requires --runtime-json and --budget-json; no unmetered fallback');
+  const runtimeAgent = JSON.parse(await readFile(value('--runtime-json'), 'utf8'));
+  runtimeAgent.paperBudgetEnforced = true;
+  const paperBudget = JSON.parse(await readFile(value('--budget-json'), 'utf8'));
+  if (!paperBudget.url || !paperBudget.token || !paperBudget.workerId) throw new Error('Budget descriptor must include url, token and workerId');
+  const bundle = { directories: { execution: output, repositorySnapshot: repositoryRoot }, runtimeAgent, paperBudget,
+    sourceReviewProviderSecret: value('--provider-secret'), runtimeTask: { paper: { digest: `sha256:${sources.identity.paperDigest}` }, reproductionScope: value('--scope') ?? 'low' } };
+  const results = [];
+  for (const filename of candidates) {
+    const candidate = JSON.parse(await readFile(filename, 'utf8'));
+    if (candidate.provenance) delete candidate.provenance.compilerSourceReview;
+    try { const review = await reviewCompilerSources({ bundle, candidate, paperPath, prepare: async () => sources }); results.push({ candidate: path.resolve(filename), accepted: true, reportDigest: review.reportDigest }); }
+    catch (error) {
+      results.push({ candidate: path.resolve(filename), accepted: false, code: error.failureCode, message: error.message });
+      if (error.failureCode !== 'compiler.source_review_rejected') break;
+    }
+    await writeJson(path.join(output, 'results.json'), results);
+  }
+  await writeJson(path.join(output, 'results.json'), results);
+  console.log(JSON.stringify(results));
+}

package/scripts/run-asset-preparation.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -uo pipefail
+
+deterministic_script="$1"
+shift
+set +e
+python3 "$deterministic_script"
+status=$?
+set -e
+if [ "$status" -eq 0 ]; then
+  exit 0
+fi
+if [ "$status" -ne 86 ]; then
+  exit "$status"
+fi
+printf '%s\n' '{"type":"citeark.asset_preparation_agent_fallback","reason":"deterministic-fast-path-declined"}'
+exec "$@"

package/scripts/run-research-plan.mjs

@@ -0,0 +1,98 @@
+// The staged helper imports the same plan validator as the coordinator.
+import { createHash, randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { appendFile, mkdir, open, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { finished } from "node:stream/promises";
+import { resolveResearchPlan } from "../src/reproduction/plan.mjs";
+import { inspectResearchPlanEvidence } from "../src/reproduction/evidence-feedback.mjs";
+
+const [planPath = "/job/output/research-plan.json", ...args] = process.argv.slice(2);
+const scientificStepId = args[0] === '--step' ? args[1] : null;
+const command = args[0] === '--step' ? args.slice(2) : args;
+const contractPath = path.resolve(path.dirname(planPath), "../input/task.json");
+const contract = JSON.parse(await readFile(contractPath, "utf8"));
+let resolved;
+try {
+  if (args[0] === '--step' && (!scientificStepId || !contract.researchGraph?.steps?.some(step => step.id === scientificStepId))) {
+    throw new Error(`Unknown scientific step: ${String(scientificStepId)}`);
+  }
+  resolved = await resolveResearchPlan(contract, path.dirname(planPath));
+  if (!resolved.executionPlan || path.basename(planPath) !== "research-plan.json") {
+    throw new Error("Expected research-plan.json for a workspacePlan-enabled task");
+  }
+} catch (error) {
+  console.error(`${error.message}\nCorrect the plan and run this helper again. Reuse existing raw evidence; plan validation does not require repeating the experiment.`);
+  process.exit(1);
+}
+const plan = resolved.executionPlan.plan;
+const canonical = (value) => Array.isArray(value) ? value.map(canonical)
+  : value && typeof value === "object"
+    ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+const bytes = JSON.stringify(canonical(plan));
+const digest = createHash("sha256").update(bytes).digest("hex");
+const directory = path.join(path.dirname(planPath), "plan-history");
+await mkdir(directory, { recursive: true });
+let newRevision = true;
+try { await writeFile(path.join(directory, `${digest}.json`), bytes, { flag: "wx" }); }
+catch (error) { if (error.code !== "EEXIST") throw error; newRevision = false; }
+// The runner captures this statement and its exact plan bytes outside the
+// workspace. Snapshot files alone are Agent declarations, not execution proof.
+// Always recapture complete final bytes. Repeated commands with an unchanged
+// plan can refer to the revision, avoiding the same large snapshot on every probe.
+console.log(JSON.stringify({ event: "research_plan_execution", planDigest: `sha256:${digest}`,
+  ...(newRevision || !command.length ? { plan } : {}), command,
+  ...(!command.length && contract.workspacePlan?.version === 2
+    ? { evidenceFeedback: await inspectResearchPlanEvidence(resolved, path.dirname(planPath)) } : {}),
+}));
+if (command.length) {
+  const startedAt = new Date().toISOString();
+  const capture = contract.workspacePlan?.version === 2;
+  const executionId = randomUUID();
+  const stdoutPath = `experiment-logs/${executionId}.stdout.log`;
+  const stderrPath = `experiment-logs/${executionId}.stderr.log`;
+  const record = { planDigest: `sha256:${digest}`, command, startedAt,
+    ...(scientificStepId ? { scientificStepId } : {}),
+    ...(capture ? { executionId, stdoutPath, stderrPath } : {}) };
+  const recordPath = path.join(path.dirname(planPath), "experiment-records.jsonl");
+  const recordEvent = async (event) => {
+    if (contract.workspacePlan?.version !== 2) return;
+    const line = JSON.stringify({ ...record, ...event });
+    await appendFile(recordPath, `${line}\n`);
+    console.log(line);
+  };
+  const logs = [];
+  if (capture) {
+    await mkdir(path.join(path.dirname(planPath), "experiment-logs"), { recursive: true });
+    for (const filename of [stdoutPath, stderrPath]) {
+      const target = path.join(path.dirname(planPath), filename);
+      // Open before starting the command: a logging failure must not silently
+      // discard a scientific run. Each invocation gets fresh files.
+      const handle = await open(target, "wx");
+      const stream = createWriteStream(target, { fd: handle.fd, autoClose: false });
+      logs.push({ handle, stream });
+    }
+  }
+  await recordEvent({ event: "experiment_started" });
+  const child = spawn(command[0], command.slice(1), { stdio: capture ? ["inherit", "pipe", "pipe"] : "inherit" });
+  const written = logs.map(({ stream }) => finished(stream));
+  if (capture) {
+    child.stdout.pipe(logs[0].stream);
+    child.stderr.pipe(logs[1].stream);
+    child.stdout.pipe(process.stdout, { end: false });
+    child.stderr.pipe(process.stderr, { end: false });
+  }
+  let spawnError = null;
+  child.on("error", (error) => { spawnError = error.message; console.error(error.message); });
+  const [[code, signal]] = await Promise.all([
+    new Promise((resolve) => child.once("close", (...args) => resolve(args))),
+    ...written,
+  ]);
+  for (const { handle } of logs) { await handle.sync(); await handle.close(); }
+  process.exitCode = spawnError ? 1 : code ?? (signal ? 1 : 0);
+  await recordEvent({ event: "experiment_finished", finishedAt: new Date().toISOString(),
+    exitCode: process.exitCode, signal, ...(spawnError ? { error: spawnError } : {}),
+    ...(capture ? { evidenceFeedback: await inspectResearchPlanEvidence(resolved, path.dirname(planPath)) } : {}),
+  });
+}

package/scripts/validate-asset-preparation.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Deterministically validate and finalize an asset-preparation manifest."""
+
+from __future__ import annotations
+
+import hashlib
+import fnmatch
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+JOB_ROOT = Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+
+
+def canonical(value: object) -> bytes:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+
+
+def digest_bytes(value: bytes) -> str:
+    return "sha256:" + hashlib.sha256(value).hexdigest()
+
+
+def digest_file(target: Path) -> str:
+    digest = hashlib.sha256()
+    with target.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return "sha256:" + digest.hexdigest()
+
+
+def inside_job(value: str, *, allow_final_symlink: bool = False) -> Path:
+    target = Path(value)
+    if target.is_absolute() and target.parts[:2] == ("/", "job") and JOB_ROOT != Path("/job"):
+        target = JOB_ROOT.joinpath(*target.parts[2:])
+    elif not target.is_absolute():
+        target = JOB_ROOT / target
+    # Task-local virtual environments intentionally use a python symlink into
+    # the immutable base image. Permit that final executable symlink only for
+    # the explicit runtime probe; all evidence and asset paths still resolve
+    # their complete chain before the containment check.
+    resolved = Path(os.path.abspath(target)) if allow_final_symlink else target.resolve()
+    if resolved != JOB_ROOT and JOB_ROOT not in resolved.parents:
+        raise ValueError(f"path escapes /job: {value}")
+    return resolved
+
+
+def relative_output(value: str) -> Path:
+    if not value or value.startswith("/") or ".." in Path(value).parts:
+        raise ValueError(f"unsafe evidence path: {value}")
+    return inside_job(f"output/{value}")
+
+
+def inventory_asset(asset: dict, record: dict) -> None:
+    root = inside_job(asset["localPath"])
+    # localPath is a host-owned binding. A model may restate it incorrectly in
+    # the draft manifest, but it is never allowed to redirect prepared bytes
+    # away from the immutable plan. Canonicalize, then inspect the planned path.
+    record["localPath"] = asset["localPath"]
+    if record.get("status") not in {"prepared", "stream_ready"}:
+        return
+    if not root.is_dir():
+        raise ValueError(f"prepared asset directory missing: {root}")
+    files = []
+    for target in sorted(root.rglob("*")):
+        if target.is_symlink():
+            raise ValueError(f"asset symlink is not allowed: {target}")
+        if not target.is_file():
+            continue
+        relative = target.relative_to(root).as_posix()
+        files.append({
+            "path": relative,
+            "bytes": target.stat().st_size,
+            "digest": digest_file(target),
+        })
+    if not files:
+        raise ValueError(f"prepared asset has no files: {asset['id']}")
+    total = sum(item["bytes"] for item in files)
+    if total > asset["maximumExpandedBytes"]:
+        raise ValueError(f"asset exceeds approved disk budget: {asset['id']}")
+    paths = [item["path"] for item in files]
+    requested = asset.get("requiredPaths", [])
+    record["selectionObservation"] = {
+        "requested": requested,
+        "matched": [
+            pattern for pattern in requested
+            if any(fnmatch.fnmatchcase(candidate, pattern) for candidate in paths)
+        ],
+        "unmatched": [
+            pattern for pattern in requested
+            if not any(fnmatch.fnmatchcase(candidate, pattern) for candidate in paths)
+        ],
+    }
+    for pattern in asset.get("excludedPaths", []):
+        if any(fnmatch.fnmatchcase(candidate, pattern) for candidate in paths):
+            raise ValueError(f"asset contains excluded path {pattern}: {asset['id']}")
+    record["files"] = files
+    record["totalBytes"] = total
+
+
+def validate_evidence(check: dict, record: dict, *, require_passed: bool = True) -> None:
+    if require_passed and record.get("status") in {"verified", "passed"}:
+        record["status"] = "passed"
+    if require_passed and record.get("status") != "passed":
+        raise ValueError(f"real preflight did not pass: {check['id']}")
+    commands = record.get("commands")
+    if not isinstance(commands, list) or not any(isinstance(item, str) and item.strip() for item in commands):
+        raise ValueError(f"preflight command missing: {check['id']}")
+    descriptors = record.get("evidence")
+    if not isinstance(descriptors, list) or not descriptors:
+        raise ValueError(f"preflight evidence missing: {check['id']}")
+    normalized_descriptors = []
+    for descriptor in descriptors:
+        if isinstance(descriptor, str):
+            descriptor = {"path": descriptor}
+        if not isinstance(descriptor, dict):
+            raise ValueError(f"preflight evidence descriptor invalid: {check['id']}")
+        target = relative_output(descriptor.get("path", ""))
+        if not target.is_file():
+            raise ValueError(f"preflight evidence file missing: {target}")
+        descriptor["bytes"] = target.stat().st_size
+        descriptor["digest"] = digest_file(target)
+        normalized_descriptors.append(descriptor)
+    record["evidence"] = normalized_descriptors
+
+
+def validate_asset_identity(asset: dict, record: dict) -> None:
+    if record.get("identity") != asset.get("identity"):
+        raise ValueError(f"asset identity mismatch: {asset['id']}")
+    if asset.get("revision") and record.get("revision") != asset.get("revision"):
+        raise ValueError(f"asset revision mismatch: {asset['id']}")
+    allowed_sources = {
+        item.get("url") for item in asset.get("sourceLocators", []) if isinstance(item, dict)
+    }
+    if allowed_sources and record.get("sourceLocator") not in allowed_sources:
+        raise ValueError(f"asset source is outside the approved plan: {asset['id']}")
+    verification = record.get("verification")
+    if not isinstance(verification, dict):
+        raise ValueError(f"asset identity verification missing: {asset['id']}")
+    validate_evidence({"id": f"asset:{asset['id']}"}, verification)
+
+
+def validate_acquisition(asset: dict, record: dict) -> int:
+    acquisition = record.get("acquisition")
+    if not isinstance(acquisition, dict):
+        raise ValueError(f"asset transfer audit missing: {asset['id']}")
+    download_bytes = acquisition.get("downloadBytes")
+    if not isinstance(download_bytes, int) or isinstance(download_bytes, bool) or download_bytes < 0:
+        raise ValueError(f"asset download bytes invalid: {asset['id']}")
+    if download_bytes > asset["maximumDownloadBytes"]:
+        raise ValueError(f"asset exceeds approved download budget: {asset['id']}")
+    locators = asset.get("sourceLocators", [])
+    selected = next(
+        (item for item in locators if item.get("url") == record.get("sourceLocator")),
+        None,
+    )
+    if selected:
+        expected_digest = selected.get("expectedDigest")
+        if expected_digest and acquisition.get("sourceDigest") != expected_digest:
+            raise ValueError(f"asset source digest mismatch: {asset['id']}")
+        if selected.get("fallbackRequiresDigestMatch") and not expected_digest:
+            raise ValueError(f"unverified mirror is not an acceptable fallback: {asset['id']}")
+        earlier = [
+            item for item in locators
+            if item.get("rank", 999999) < selected.get("rank", 999999)
+        ]
+        attempts = {
+            item.get("url"): item
+            for item in acquisition.get("attemptedSources", [])
+            if isinstance(item, dict)
+        }
+        for candidate in earlier:
+            if attempts.get(candidate.get("url"), {}).get("status") != "failed":
+                raise ValueError(
+                    f"higher-priority source failure was not recorded: {asset['id']}"
+                )
+    validate_evidence(
+        {"id": f"acquisition:{asset['id']}"},
+        acquisition,
+        require_passed=False,
+    )
+    return download_bytes
+
+
+def runtime_environment() -> dict:
+    python = inside_job("runtime-venv/bin/python", allow_final_symlink=True)
+    if not python.is_file():
+        raise ValueError("task-local /job/runtime-venv Python is missing")
+    version = subprocess.run(
+        [str(python), "--version"], check=True, capture_output=True, text=True
+    ).stdout.strip()
+    if not version:
+        version = subprocess.run(
+            [str(python), "--version"], check=True, capture_output=True, text=True
+        ).stderr.strip()
+    packages = subprocess.run(
+        [str(python), "-m", "pip", "freeze", "--all"],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout
+    normalized = "\n".join(sorted(line.strip() for line in packages.splitlines() if line.strip())) + "\n"
+    target = inside_job("output/logs/asset-preparation/package-inventory.txt")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(normalized, encoding="utf-8")
+    inventory_digest = digest_bytes(normalized.encode())
+    return {
+        "path": "/job/runtime-venv",
+        "pythonVersion": version,
+        "lockPath": "logs/asset-preparation/package-inventory.txt",
+        "lockDigest": inventory_digest,
+        "packageInventoryDigest": inventory_digest,
+    }
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        raise ValueError("usage: validate-asset-preparation.py PLAN MANIFEST")
+    plan = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    manifest_path = Path(sys.argv[2])
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("schemaVersion") != "0.1" or manifest.get("kind") != "citeark.asset-preparation-manifest":
+        raise ValueError("invalid manifest envelope")
+    if manifest.get("planDigest") != plan.get("planDigest"):
+        raise ValueError("manifest plan digest mismatch")
+    records = {item.get("assetId"): item for item in manifest.get("assets", []) if isinstance(item, dict)}
+    if len(records) != len(manifest.get("assets", [])):
+        raise ValueError("asset manifest contains duplicate or invalid records")
+    planned_asset_ids = {asset["id"] for asset in plan.get("assets", [])}
+    if set(records) != planned_asset_ids:
+        raise ValueError("asset manifest records do not exactly match the plan")
+    total_downloaded = 0
+    for asset in plan.get("assets", []):
+        record = records.get(asset["id"])
+        if record is None:
+            raise ValueError(f"asset record missing: {asset['id']}")
+        action = asset["decision"]["action"]
+        accepted = {
+            "metadata": {"metadata_verified", "prepared"},
+            "stream": {"stream_ready", "prepared"},
+            "blocked": {"blocked"},
+            "inspect": {"prepared", "stream_ready"} if asset.get("supportsStreaming") else {"prepared"},
+            "prepare": {"prepared"},
+        }[action]
+        if record.get("status") not in accepted:
+            raise ValueError(f"asset status mismatch: {asset['id']}")
+        validate_asset_identity(asset, record)
+        if record.get("status") in {"prepared", "stream_ready"}:
+            total_downloaded += validate_acquisition(asset, record)
+        inventory_asset(asset, record)
+    if total_downloaded > plan["limits"]["totalDownloadBytes"]:
+        raise ValueError("prepared assets exceed the total download budget")
+    total_prepared = sum(
+        record.get("totalBytes", 0)
+        for record in records.values()
+        if isinstance(record.get("totalBytes", 0), int)
+    )
+    if total_prepared > plan["limits"]["totalExpandedBytes"]:
+        raise ValueError("prepared assets exceed the total disk budget")
+    disk = os.statvfs(JOB_ROOT)
+    free_bytes = disk.f_bavail * disk.f_frsize
+    if free_bytes < plan["limits"]["minimumFreeBytesAfterPreparation"]:
+        raise ValueError("free disk space after preparation is below the approved reserve")
+    checks = {item.get("checkId"): item for item in manifest.get("checks", []) if isinstance(item, dict)}
+    if len(checks) != len(manifest.get("checks", [])):
+        raise ValueError("asset manifest contains duplicate or invalid checks")
+    if set(checks) != {check["id"] for check in plan.get("checks", [])}:
+        raise ValueError("asset manifest checks do not exactly match the plan")
+    for check in plan.get("checks", []):
+        record = checks.get(check["id"])
+        if record is None or record.get("kind") != check["kind"]:
+            raise ValueError(f"preflight record missing: {check['id']}")
+        validate_evidence(check, record)
+    manifest["runtimeEnvironment"] = runtime_environment()
+    manifest["validatedAt"] = __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat().replace("+00:00", "Z")
+    manifest.pop("manifestDigest", None)
+    manifest["manifestDigest"] = digest_bytes(canonical(manifest))
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed", "manifestDigest": manifest["manifestDigest"]}))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as error:
+        print(f"asset manifest validation failed: {error}", file=sys.stderr)
+        raise SystemExit(2)

package/scripts/verify-local-runtime.mjs

@@ -0,0 +1,57 @@
+// No model service or paper execution: exercise Docker mounts, Python isolation
+// and the authenticated host relay with a local HTTP fixture.
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtemp, mkdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { startProviderSession } from '../src/provider/relay.mjs';
+import { buildDockerRun } from '../src/sandbox/docker.mjs';
+import { runProcess } from '../src/process.mjs';
+import { HANDOFF_SCHEMA, stageExecutionHandoff } from '../src/deployment/handoff.mjs';
+
+const root=await mkdtemp(path.join(tmpdir(),'CiteArk 本地 runtime '));
+const requests=[];
+const api=http.createServer((request,response)=>{
+  requests.push({url:request.url,authorization:request.headers.authorization});
+  request.resume();
+  response.writeHead(200,{'content-type':'application/json'});
+  response.end(JSON.stringify({choices:[{message:{role:'assistant',content:'local-fixture-ok'}}]}));
+});
+let relay;
+try {
+  await new Promise(resolve=>api.listen(0,'127.0.0.1',resolve));
+  const runtimeAgent={runtime:'opencode',model:'fixture',api:{protocol:'openai-chat-completions',
+    baseUrl:`http://127.0.0.1:${api.address().port}`,apiKey:'local-fixture-credential',credentialSource:'test'}};
+  relay=await startProviderSession(runtimeAgent);
+  const directories=Object.fromEntries(['input','workspace','output','runtimeHome','execution'].map(k=>[k,path.join(root,k)]));
+  await Promise.all(Object.values(directories).map(p=>mkdir(p,{recursive:true})));
+  await mkdir(path.join(directories.workspace,'repository'));
+  const bundle={runId:`local-probe-${Date.now()}`,directories,runtimeAgent,
+    executionEnvironment:{image:'citeark-agent/runtime:cpu',cpus:1,memoryGb:2,shmGb:1,gpu:'none'}};
+  await stageExecutionHandoff(bundle,{schema:HANDOFF_SCHEMA,instructions:'Local runtime fixture only.',files:[]});
+  const python=`import json,os,pathlib,urllib.request,torch
+cfg=json.loads(os.environ['OPENCODE_CONFIG_CONTENT'])
+url=cfg['provider']['citeark']['options']['baseURL']+'/chat/completions'
+req=urllib.request.Request(url,data=json.dumps({'model':'fixture','messages':[{'role':'user','content':'fixture'}]}).encode(),headers={'Content-Type':'application/json','Authorization':'Bearer '+os.environ['CITEARK_API_KEY']})
+with urllib.request.urlopen(req,timeout=30) as r: answer=json.load(r)
+assert answer['choices'][0]['message']['content']=='local-fixture-ok'
+assert (torch.ones((8,8)) @ torch.ones((8,8))).sum().item()==512
+pathlib.Path('/job/workspace/repository/源文件.txt').write_text('workspace-ok')
+pathlib.Path('/job/assets/input.txt').write_text('external-input-fixture')
+pathlib.Path('/job/output/probe.json').write_text(json.dumps({'relay':'ok','python':os.environ['VIRTUAL_ENV'],'torch':torch.__version__}))`;
+  const invocation=buildDockerRun({bundle,runtimeCommand:'python',runtimeArgs:['-c',python],attempt:1,providerSession:relay});
+  const result=await runProcess(invocation.command,invocation.args,{timeoutMs:120000});
+  assert.equal(result.code,0);
+  const output=JSON.parse(await readFile(path.join(directories.output,'probe.json'),'utf8'));
+  assert.equal(output.python,'/job/runtime-venv');
+  assert.equal(await readFile(path.join(directories.workspace,'repository','源文件.txt'),'utf8'),'workspace-ok');
+  assert.equal(requests.length,1);
+  assert.equal(requests[0].authorization,'Bearer local-fixture-credential');
+  console.log(JSON.stringify({status:'passed',mounts:'unicode-and-space-paths',relay:'container-to-host',...output}));
+} finally {
+  await relay?.close();
+  api.closeAllConnections();
+  await new Promise(resolve=>api.close(resolve));
+  await rm(root,{recursive:true,force:true});
+}

package/scripts/verify-npm-package.mjs

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { access, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const root = fileURLToPath(new URL('..', import.meta.url));
+const manifest = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+const temporary = await mkdtemp(path.join(tmpdir(), 'citeark-npm-'));
+if (!process.env.npm_execpath) throw Error('请运行 npm run test:package。');
+const npm = (args, options = {}) => run(process.execPath, [process.env.npm_execpath, ...args], { cwd: root, ...options });
+try {
+  const { stdout } = await npm(['pack', '--json', '--ignore-scripts', '--pack-destination', temporary]);
+  const [packed] = JSON.parse(stdout);
+  const files = new Set(packed.files.map(file => file.path));
+  for (const required of ['src/cli.mjs', 'src/public/host.mjs', 'src/public/cap.mjs',
+    'dist/arkgraph/viewer.js', 'dist/arkgraph/viewer.css', 'dist/arkgraph/viewer.en.js', 'dist/arkgraph/viewer.en.css', 'dist/arkgraph/index.html', 'dist/arkgraph/boot.js', 'scripts/preview-arkgraph.mjs',
+    'docker/claude-code/Dockerfile', 'runtime/requirements-baseline.txt', 'runtime/install-local-cpu-runtime.sh',
+    'scripts/run-research-plan.mjs', 'examples/toy-evaluation/paper.md', 'protocol/CAP.md',
+    'runtime/mineru/parse.py', 'runtime/mineru/requirements.txt', 'src/research/paper-command.mjs']) {
+    assert.ok(files.has(required), `Missing runtime input: ${required}`);
+  }
+  for (const file of files) {
+    if (file.startsWith('dist/arkgraph/')) continue;
+    assert.doesNotMatch(file, /(^|\/)(?:\.env(?:\.|$)|\.npmrc$|\.git\/|node_modules\/|tests\/|dist\/)/);
+  }
+  const prefix = path.join(temporary, 'install');
+  await npm(['install', '--global', '--prefix', prefix, '--no-audit', '--no-fund', path.join(temporary, packed.filename)]);
+  const windows = process.platform === 'win32';
+  const bin = name => path.join(prefix, windows ? `${name}.cmd` : `bin/${name}`);
+  const cli = (name, args) => run(windows ? `"${bin(name)}"` : bin(name), args, { cwd: temporary, shell: windows });
+  for (const name of ['citeark', 'citeark-agent']) {
+    assert.equal((await cli(name, ['--version'])).stdout.trim(), manifest.version);
+  }
+  assert.match((await cli('citeark', ['--help'])).stdout, /citeark start/);
+  assert.match((await cli('citeark', ['--help'])).stdout, /citeark paper setup/);
+  // No terminal means help, not a blocking prompt or an accidental research run.
+  assert.match((await cli('citeark', [])).stdout, /CiteArk Agent/);
+  await cli('citeark', ['init', '--dir', 'example']);
+  await access(path.join(temporary, 'example', 'repository', 'evaluate.py'));
+  await cli('citeark', ['start', '--paper', 'example/paper.md', '--dry-run', '--work-dir', 'research']);
+  const session = JSON.parse(await readFile(path.join(temporary, 'research', 'workspace.json'), 'utf8'));
+  assert.equal(session.input.platformRepositoryId, null);
+  // Resolve the exported APIs from a consumer next to the installed node_modules.
+  const consumerRoot = windows ? prefix : path.join(prefix, 'lib');
+  await run(process.execPath, ['--input-type=module', '-e',
+    `import { createRequire } from 'node:module'; import { pathToFileURL } from 'node:url';
+     const require = createRequire(${JSON.stringify(path.join(consumerRoot, 'consumer.cjs'))});
+     await import(pathToFileURL(require.resolve('@citeark/agent/host')));
+     await import(pathToFileURL(require.resolve('@citeark/agent/cap')));`], { cwd: temporary });
+  console.log(`${manifest.name}@${manifest.version}: global commands, help, example, independent dry-run and public APIs passed (${packed.entryCount} package files).`);
+} finally {
+  await rm(temporary, { recursive: true, force: true });
+}