@citeark/agent 0.3.20

package/src/remote/command.mjs

@@ -0,0 +1,178 @@
+import path from "node:path";
+import os from "node:os";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  writeFile,
+  stat,
+  rm,
+} from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { readSettings } from "../settings/store.mjs";
+import { shellQuote } from "../util.mjs";
+import { captureProcess } from "../process.mjs";
+import { sshCommand, sshShell } from "./ssh.mjs";
+import { attachJob } from "../workspace/jobs.mjs";
+
+export function takeOption(args, flag) {
+  const index = args.indexOf(flag);
+  if (index < 0) return undefined;
+  if (!args[index + 1] || args[index + 1].startsWith("--"))
+    throw Error(`${flag} requires a value.`);
+  return args.splice(index, 2)[1];
+}
+export async function remoteProfile(name) {
+  const settings = await readSettings();
+  const profile = settings.compute[name];
+  if (!profile || profile.type !== "ssh")
+    throw Error(`Unknown SSH compute profile: ${name}`);
+  return profile;
+}
+export async function startRemoteResearch(argv, profile, name) {
+  if (argv.includes("--api-key"))
+    throw Error(
+      "Remote research uses credentials configured on the server. Select a remote model profile or API key environment variable.",
+    );
+  const detach = argv.includes("--background");
+  const args = [...argv];
+  takeOption(args, "--compute");
+  const specified = takeOption(args, "--work-dir");
+  const root =
+    specified ?? path.posix.join(profile.directory, `research-${randomUUID()}`);
+  if (!path.posix.isAbsolute(root))
+    throw Error("Use an absolute remote workspace path.");
+  if (args.includes("--dry-run")) {
+    console.log(
+      JSON.stringify(
+        {
+          host: profile.host,
+          directory: root,
+          modelCredentials: "configured-on-remote-host",
+          action: "prepare-only",
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  if (!args.includes("--resume")) {
+    await sshShell(
+      profile,
+      `mkdir -p ${shellQuote(profile.directory)} && mkdir ${shellQuote(root)} && mkdir ${shellQuote(path.posix.join(root, "input-files"))}`,
+    );
+    for (const flag of ["--paper", "--cap", "--repository", "--guide"]) {
+      const i = args.indexOf(flag);
+      const local = args[i + 1];
+      if (i < 0 || /^https?:\/\//.test(local)) continue;
+      const location = path.resolve(local);
+      const info = await stat(location);
+      const destination = path.posix.join(
+        root,
+        "input-files",
+        `${flag.slice(2)}${info.isDirectory() ? "" : path.extname(location)}`,
+      );
+      if (info.isDirectory()) {
+        const temp = await mkdtemp(path.join(os.tmpdir(), "citeark-transfer-"));
+        try {
+          const archive = path.join(temp, "code.tgz");
+          const result = await captureProcess(
+            "tar",
+            [
+              "--exclude=.git",
+              "--exclude=.env*",
+              "--exclude=node_modules",
+              "--exclude=.citeark",
+              "-czf",
+              archive,
+              "-C",
+              location,
+              ".",
+            ],
+            { env: { ...process.env, COPYFILE_DISABLE: "1" } },
+          );
+          if (result.code) throw Error(result.stderr);
+          await sshShell(
+            profile,
+            `mkdir ${shellQuote(destination)} && tar -xzf - -C ${shellQuote(destination)}`,
+            { input: await readFile(archive) },
+          );
+        } finally {
+          await rm(temp, { recursive: true, force: true });
+        }
+      } else
+        await sshShell(profile, `cat > ${shellQuote(destination)}`, {
+          input: await readFile(location),
+        });
+      args[i + 1] = destination;
+    }
+  }
+  // Catalog paths and model profile names refer to the server's configuration.
+  args.push("--work-dir", root);
+  if (!args.includes("--background")) args.push("--background");
+  const started = JSON.parse(await sshCommand(profile, ["start", ...args]));
+  console.log(`Research started on ${profile.host}: ${started.directory}`);
+  console.log(
+    `Reconnect: citeark session attach ${JSON.stringify(root)} --compute ${name}`,
+  );
+  if (detach) return started;
+  const state = await attachJob(root, {
+    inspect: (directory, cursor) => inspectRemote(profile, directory, cursor),
+    control: (directory, text) =>
+      sshCommand(profile, ["session", "note", directory, "--message", text]),
+  });
+  if (state?.status === "awaiting_selection")
+    console.log(
+      `Run selected experiments: citeark start --resume --work-dir ${JSON.stringify(root)} --compute ${name} --experiments <ids>`,
+    );
+  return state;
+}
+export const inspectRemote = async (profile, root, cursor = 0) =>
+  JSON.parse(
+    await sshCommand(profile, [
+      "session",
+      "inspect",
+      root,
+      "--cursor",
+      String(cursor),
+    ]),
+  );
+export async function remoteSession(argv, name) {
+  const profile = await remoteProfile(name);
+  const [action, root, ...args] = argv;
+  if (action === "attach")
+    return attachJob(root, {
+      inspect: (directory, cursor) => inspectRemote(profile, directory, cursor),
+      control: (directory, text) =>
+        sshCommand(profile, ["session", "note", directory, "--message", text]),
+    });
+  if (action === "fetch") {
+    const output = path.resolve(
+      takeOption(args, "--output") ?? path.basename(root),
+    );
+    const state = await inspectRemote(profile, root);
+    if (!state.artifacts.length)
+      throw Error("This session has no CAP artifacts yet.");
+    await mkdir(output, { recursive: true });
+    const { readCapArchive } = await import("../cap/v2/read.mjs");
+    const temp = await mkdtemp(path.join(os.tmpdir(), "citeark-cap-check-"));
+    try {
+      for (const [index, file] of [...new Set(state.artifacts)].entries()) {
+        const bytes = await sshShell(profile, `cat -- ${shellQuote(file)}`, {
+          binary: true,
+        });
+        const local = path.join(temp, `${index}.cap`);
+        await writeFile(local, bytes);
+        await readCapArchive(local, path.join(temp, `verify-${index}`));
+        const target = path.join(output, `${index + 1}-${path.basename(file)}`);
+        await writeFile(target, bytes, { flag: "wx" });
+        console.log(target);
+      }
+    } finally {
+      await rm(temp, { recursive: true, force: true });
+    }
+    return;
+  }
+  console.log((await sshCommand(profile, ["session", ...argv])).trim());
+}

package/src/remote/ssh.mjs

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process";
+import { shellQuote } from "../util.mjs";
+
+export function sshArguments(profile, command) {
+  return [
+    ...(profile.configFile ? ["-F", profile.configFile] : []),
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=yes",
+    "-o",
+    "ConnectTimeout=15",
+    ...(profile.port ? ["-p", String(profile.port)] : []),
+    ...(profile.identityFile ? ["-i", profile.identityFile] : []),
+    profile.host,
+    command,
+  ];
+}
+export async function sshShell(
+  profile,
+  command,
+  { input, binary = false } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("ssh", sshArguments(profile, command), {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const output = [];
+    let error = "";
+    child.stdout.on("data", (chunk) => output.push(chunk));
+    child.stderr.on("data", (chunk) => {
+      error += chunk;
+    });
+    child.on("error", reject);
+    child.stdin.on("error", (err) => {
+      if (err.code !== "EPIPE") reject(err);
+    });
+    child.on("close", (code) =>
+      code === 0
+        ? resolve(
+            binary
+              ? Buffer.concat(output)
+              : Buffer.concat(output).toString("utf8"),
+          )
+        : reject(
+            Error(
+              `SSH command failed (${code}): ${error.trim() || "Check the remote command and SSH connection."}`,
+            ),
+          ),
+    );
+    child.stdin.end(input);
+  });
+}
+export const sshCommand = (profile, args, options) =>
+  sshShell(
+    profile,
+    `cd ${shellQuote(profile.directory)} && exec ${shellQuote(profile.command ?? "citeark")} ${args.map(shellQuote).join(" ")}`,
+    options,
+  );

package/src/repository-origin.mjs

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { devNull } from "node:os";
+
+import { captureProcess } from "./process.mjs";
+import { CiteArkError } from "./util.mjs";
+
+export const IMPLEMENTATION_ORIGINS = new Set([
+  "official",
+  "citeark_reconstruction",
+]);
+
+export const RECONSTRUCTION_SCAFFOLD_COMMIT = "8af5c5a966cf8d5e55560659ef5a33e6ceadaa33";
+
+export const RECONSTRUCTION_REPOSITORY = Object.freeze({
+  implementationOrigin: "citeark_reconstruction",
+  url: "citeark://reconstruction/v1",
+  commit: RECONSTRUCTION_SCAFFOLD_COMMIT,
+});
+
+export function isCiteArkReconstructionRepository(repository) {
+  return repository?.implementationOrigin === "citeark_reconstruction"
+    || repository?.url === RECONSTRUCTION_REPOSITORY.url;
+}
+
+/** Create the deterministic empty base used by paper-driven reconstructions. */
+export async function prepareReconstructionRepository(destination) {
+  const fixedEnvironment = {
+    ...process.env,
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: devNull,
+    GIT_AUTHOR_NAME: "CiteArk",
+    GIT_AUTHOR_EMAIL: "research@citeark.com",
+    GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z",
+    GIT_COMMITTER_NAME: "CiteArk",
+    GIT_COMMITTER_EMAIL: "research@citeark.com",
+    GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+  };
+  await mkdir(destination, { recursive: true });
+  await writeFile(
+    `${destination}/CITEARK_RECONSTRUCTION.md`,
+    `# CiteArk independent reconstruction\n\nThis workspace intentionally starts without author-provided source code. The execution Agent must implement only the fixed, paper-grounded protocol in the blind execution contract.\n`,
+    "utf8",
+  );
+  const init = await captureProcess(
+    "git",
+    ["init", "--object-format=sha1", "--initial-branch=main"],
+    { cwd: destination, env: fixedEnvironment },
+  );
+  if (init.code !== 0) throw new CiteArkError(`无法初始化独立重建工作区：${init.stderr.trim()}`);
+  const add = await captureProcess(
+    "git",
+    ["-c", "core.autocrlf=false", "add", "CITEARK_RECONSTRUCTION.md"],
+    { cwd: destination, env: fixedEnvironment },
+  );
+  if (add.code !== 0) throw new CiteArkError(`无法固定独立重建工作区：${add.stderr.trim()}`);
+  const commit = await captureProcess(
+    "git",
+    [
+      "commit",
+      "--no-gpg-sign",
+      "--cleanup=verbatim",
+      "-m",
+      "Initialize CiteArk independent reconstruction workspace",
+    ],
+    { cwd: destination, env: fixedEnvironment },
+  );
+  if (commit.code !== 0) throw new CiteArkError(`无法提交独立重建工作区：${commit.stderr.trim()}`);
+  const revision = await captureProcess(
+    "git",
+    ["rev-parse", "HEAD"],
+    { cwd: destination, env: fixedEnvironment },
+  );
+  if (revision.code !== 0) throw new CiteArkError("无法读取独立重建工作区版本");
+  const observedCommit = revision.stdout.trim();
+  if (observedCommit !== RECONSTRUCTION_SCAFFOLD_COMMIT) {
+    throw new CiteArkError(
+      `独立重建基座 commit 不稳定：expected=${RECONSTRUCTION_SCAFFOLD_COMMIT}, observed=${observedCommit}`,
+    );
+  }
+  return observedCommit;
+}

package/src/reproduction/evidence-feedback.mjs

@@ -0,0 +1,96 @@
+import path from "node:path";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { getEvidenceParser } from "../evidence/parser-registry.mjs";
+import { safeRelativePath } from "../util.mjs";
+
+/** Extraction feedback for the live Agent. No target values, scientific verdicts
+ * or automatic metric selection: a valid scalar can still answer the wrong question.
+ */
+export async function inspectResearchPlanEvidence(contract, outputDirectory) {
+  const measurements = [];
+  const files = new Map();
+  const root = await realpath(outputDirectory);
+  for (const measurement of contract.measurements ?? []) {
+    const descriptor = measurement.parser;
+    const item = {
+      measurementId: measurement.measurementId,
+      metric: measurement.metric,
+      unit: measurement.unit,
+      evidencePath: descriptor?.evidencePath ?? null,
+      parser: descriptor?.id ?? null,
+      interpretation: measurementInterpretation(measurement),
+      ...(descriptor?.id === "json.scalar" ? { field: descriptor.config?.pointer ?? "",
+        scale: descriptor.config?.scale ?? 1, offset: descriptor.config?.offset ?? 0 } : {}),
+    };
+    try {
+      if (!safeRelativePath(descriptor?.evidencePath)) throw new Error("Evidence path must stay inside output");
+      if (!files.has(descriptor.evidencePath)) {
+        const filename = path.join(root, descriptor.evidencePath);
+        const stat = await lstat(filename);
+        if (!stat.isFile() || !(await realpath(filename)).startsWith(`${root}${path.sep}`)) {
+          throw new Error("Evidence must be a regular file inside output");
+        }
+        // The preview is advisory and bounded; large evidence remains available
+        // to the final parser, not a reason to rerun or mark the experiment failed.
+        if (stat.size > 32 * 1024 * 1024) throw new Error("Evidence exceeds the 32 MiB interactive preview limit; inspect it directly before final parsing");
+        files.set(descriptor.evidencePath, await readFile(filename, "utf8"));
+      }
+      const parser = getEvidenceParser(descriptor);
+      if (!parser) throw new Error(`Unknown parser ${descriptor?.id}@${descriptor?.version}`);
+      const text = files.get(descriptor.evidencePath);
+      const parsed = parser.parse(text, descriptor.config ?? {});
+      item.status = "available";
+      item.value = parsed.primary.value;
+      if (descriptor.id === "json.scalar") {
+        // Expose neighboring field NAMES only. Their presence is not an error
+        // and never selects a field based on its numeric proximity to a target.
+        item.neighboringFields = neighboringFields(text, descriptor.config?.pointer ?? "");
+      }
+    } catch (error) {
+      item.status = "unresolved";
+      item.reason = error.code === "ENOENT" ? "Evidence has not been written at this path" : error.message;
+    }
+    measurements.push(item);
+  }
+  const assigned = contract.executionPlan?.originalMeasurements ?? contract.measurements ?? [];
+  const assignedIds = assigned.map((item) => item.measurementId);
+  const currentIds = new Set(measurements.map((item) => item.measurementId));
+  const interpretationReview = measurements
+    .filter((item) => item.status === "available" && item.interpretation.status !== "resolved")
+    .map((item) => ({
+      measurementId: item.measurementId,
+      field: item.field ?? null,
+      neighboringFields: item.neighboringFields ?? [],
+      action: "Resolve the quantity and aggregation from the source/evaluator using the retained output before considering another experiment.",
+    }));
+  return {
+    role: "extraction_preview_not_scientific_verification",
+    interpretationReview,
+    assignedMeasurementIds: assignedIds,
+    additionalPlannedMeasurementIds: measurements.filter((item) => !assignedIds.includes(item.measurementId)).map((item) => item.measurementId),
+    remainingClaimMeasurementIds: (contract.workspacePlan?.measurements ?? []).filter((item) => !currentIds.has(item.measurementId)).map((item) => item.measurementId),
+    measurements,
+    nextAction: "Check field meaning and aggregation against the sources. Correct source-resolvable defects using existing raw output; never select a value because it looks closer to the paper. Missing or genuinely unavailable evidence may remain partial within the same budget.",
+  };
+}
+
+function neighboringFields(text, pointer) {
+  try {
+    if (!pointer.startsWith("/")) return [];
+    const keys = pointer.slice(1).split("/").map((key) => key.replaceAll("~1", "/").replaceAll("~0", "~"));
+    let parent = JSON.parse(text);
+    for (const key of keys.slice(0, -1)) parent = parent[key];
+    return parent && typeof parent === "object" && !Array.isArray(parent) ? Object.keys(parent).slice(0, 30) : [];
+  } catch { return []; }
+}
+
+/** A source-grounded declaration to be audited, never a scientific verdict. */
+export function measurementInterpretation(measurement) {
+  const review = measurement?.interpretation;
+  const sources = Array.isArray(review?.sources)
+    ? review.sources.filter((item) => typeof item === "string" && item.trim()) : [];
+  const reason = typeof review?.reason === "string" ? review.reason.trim() : "";
+  const resolved = review?.status === "resolved" && sources.length > 0 && reason.length > 0;
+  return { status: resolved ? "resolved" : "unresolved", sources, reason: reason
+    || "The selected quantity, evaluator field and aggregation have no recorded source-grounded interpretation." };
+}

package/src/reproduction/incomplete-initialization.mjs

@@ -0,0 +1,25 @@
+import { readdir, rename } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { pathExists, readJson } from '../util.mjs';
+
+export async function preserveIncompleteInitialization({runsDirectory, runId, task}) {
+  const root=path.resolve(runsDirectory,runId);
+  if (!await pathExists(root)) return null;
+  // Never replace a prepared run, remote execution, or recoverable session.
+  if (await pathExists(path.join(root,'run.json')) || await pathExists(path.join(root,'recovery-bundle.json'))) return null;
+  const submitted=await readJson(path.join(root,'input','submitted-task.json')).catch(()=>null);
+  if (!task.contractDigest || submitted?.contractDigest!==task.contractDigest) return null;
+  for (const folder of ['execution','output','workspace','runtime-home']) {
+    async function hasFiles(directory) {
+      for(const entry of await readdir(directory,{withFileTypes:true}).catch(()=>[])) {
+        if (!entry.isDirectory() || await hasFiles(path.join(directory,entry.name))) return true;
+      }
+      return false;
+    }
+    if(await hasFiles(path.join(root,folder))) return null;
+  }
+  const preserved=`${root}.incomplete-${randomUUID()}`;
+  await rename(root,preserved);
+  return preserved;
+}