@citeark/agent 0.3.20

package/src/workspace/interactive.mjs

@@ -0,0 +1,94 @@
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import { readJson, writeJson } from "../util.mjs";
+import { launchJob, attachJob } from "./jobs.mjs";
+
+// The terminal observes the same durable worker used by headless servers.
+export async function interactiveResearch({
+  root,
+  options,
+  screen,
+  runtime,
+  assessmentRuntime,
+  signingKeyPath,
+}) {
+  const env = { ...process.env };
+  const sessionPath = path.join(root, "workspace.json");
+  const session = await readJson(sessionPath);
+  for (const [agent, field, fallback] of [
+    [runtime, "modelConfiguration", "CITEARK_SESSION_MODEL_KEY"],
+    [
+      assessmentRuntime,
+      "assessmentConfiguration",
+      "CITEARK_SESSION_ASSESSMENT_KEY",
+    ],
+  ]) {
+    if (!agent.apiKey || !session[field]) continue;
+    const key = session[field].apiKeyEnv ?? fallback;
+    env[key] = agent.apiKey;
+    session[field].apiKeyEnv = key;
+  }
+  await writeJson(sessionPath, session);
+  await screen.stopRecording();
+  let cursor = (await stat(path.join(root, "session.events.jsonl"))).size;
+  const retained = Object.entries(options).filter(
+    ([key]) =>
+      key.startsWith("--gcp-") ||
+      key.startsWith("--autodl-") ||
+      key === "--allow-remote-model-key",
+  );
+  const args = [
+    "--resume",
+    "--work-dir",
+    root,
+    "--signing-key",
+    signingKeyPath,
+    ...retained.flatMap(([key, value]) =>
+      value === undefined || value === false
+        ? []
+        : value === true
+          ? [key]
+          : [key, String(value)],
+    ),
+  ];
+  let experiments = options["--experiments"];
+  while (true) {
+    await launchJob(
+      [...args, ...(experiments ? ["--experiments", experiments] : [])],
+      { env },
+    );
+    const state = await attachJob(root, { output: screen, cursor });
+    cursor = state.cursor;
+    if (state.detached) {
+      await screen.close();
+      console.log(`Reconnect: citeark session attach ${JSON.stringify(root)}`);
+      return { phase: "detached" };
+    }
+    if (
+      state.status === "failed" ||
+      state.status === "cancelled" ||
+      state.status === "interrupted"
+    )
+      throw Error(state.error ?? `Session ${state.status}`);
+    if (state.status !== "awaiting_selection" || options["--plan-only"])
+      return readJson(sessionPath);
+    for (const [i, experiment] of state.experiments.entries())
+      screen.event({
+        kind: "status",
+        text: `${i + 1}. ${experiment.id} — ${experiment.title}`,
+      });
+    const answer = await screen.ask(
+      "Select experiment numbers (comma-separated; leave empty to save the plan)",
+    );
+    if (!answer) return readJson(sessionPath);
+    experiments = answer
+      .split(",")
+      .map(
+        (value) =>
+          state.experiments[Number(value.trim()) - 1]?.id ?? value.trim(),
+      )
+      .join(",");
+    if (!(await screen.confirm("Run the selected experiments?")))
+      return readJson(sessionPath);
+  }
+}

package/src/workspace/jobs.mjs

@@ -0,0 +1,418 @@
+import { spawn } from "node:child_process";
+import {
+  open,
+  mkdir,
+  readFile,
+  writeFile,
+  rename,
+  readdir,
+  rm,
+  appendFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { settingsPath } from "../settings/store.mjs";
+
+export const jobDirectory = (root) =>
+  path.join(path.resolve(root), ".citeark-job");
+export async function jobJson(root, name, fallback = null) {
+  try {
+    return JSON.parse(
+      await readFile(path.join(jobDirectory(root), name), "utf8"),
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+export async function saveJobJson(root, name, value) {
+  const file = path.join(jobDirectory(root), name);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.tmp`;
+  await writeFile(temp, JSON.stringify(value) + "\n", { mode: 0o600 });
+  await rename(temp, file);
+}
+export function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+const terminal = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "awaiting_selection",
+  "prepared",
+]);
+export async function inspectJob(root, cursor = 0) {
+  let state = await jobJson(root, "state.json");
+  if (!state) throw Error(`No managed research session at ${root}`);
+  if (!terminal.has(state.status) && !alive(state.pid))
+    state = { ...state, status: "interrupted" };
+  const file = path.join(root, "session.events.jsonl");
+  let events = [],
+    nextCursor = cursor;
+  try {
+    const handle = await open(file, "r");
+    try {
+      const chunks = [];
+      let bytes = 0,
+        complete = -1;
+      while (complete < 0) {
+        const chunk = Buffer.alloc(512 * 1024);
+        const { bytesRead } = await handle.read(
+          chunk,
+          0,
+          chunk.length,
+          cursor + bytes,
+        );
+        if (!bytesRead) break;
+        chunks.push(chunk.subarray(0, bytesRead));
+        const newline = chunk.subarray(0, bytesRead).lastIndexOf(10);
+        if (newline >= 0) complete = bytes + newline;
+        bytes += bytesRead;
+        if (bytesRead < chunk.length) break;
+      }
+      const buffer = Buffer.concat(chunks);
+      if (complete >= 0) {
+        events = buffer
+          .subarray(0, complete)
+          .toString("utf8")
+          .split("\n")
+          .filter(Boolean)
+          .map(JSON.parse);
+        nextCursor += complete + 1;
+      }
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  let workspace;
+  try {
+    workspace = JSON.parse(
+      await readFile(path.join(root, "workspace.json"), "utf8"),
+    );
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  let experiments;
+  if (state.status === "awaiting_selection" && workspace?.researchPath)
+    experiments = JSON.parse(
+      await readFile(workspace.researchPath, "utf8"),
+    ).experiments.map(({ id, title }) => ({ id, title }));
+  return {
+    ...state,
+    directory: root,
+    cursor: nextCursor,
+    events,
+    experiments,
+    artifacts: workspace?.artifacts ?? [],
+  };
+}
+
+export async function launchJob(
+  argv,
+  { cwd = process.cwd(), env = process.env } = {},
+) {
+  if (argv.includes("--api-key"))
+    throw Error(
+      "Background research uses a model profile or --api-key-env. Credentials must not appear in command arguments.",
+    );
+  const args = argv.filter((a) => a !== "--background");
+  const pathOptions = [
+    "--paper",
+    "--cap",
+    "--repository",
+    "--guide",
+    "--compute-catalog",
+    "--compute-policy",
+    "--signing-key",
+    "--work-dir",
+  ];
+  for (const option of pathOptions) {
+    const i = args.indexOf(option);
+    if (i >= 0 && args[i + 1] && !/^https?:\/\//.test(args[i + 1]))
+      args[i + 1] = path.resolve(cwd, args[i + 1]);
+  }
+  const i = args.indexOf("--work-dir");
+  const root =
+    i >= 0 ? args[i + 1] : path.resolve(cwd, `citeark-research-${Date.now()}`);
+  if (i < 0) args.push("--work-dir", root);
+  const previous = await jobJson(root, "state.json");
+  if (previous && !terminal.has(previous.status) && alive(previous.pid))
+    throw Error(
+      `Session is ${previous.status}. Use citeark session attach ${JSON.stringify(root)}.`,
+    );
+  if (!args.includes("--resume")) {
+    try {
+      await readFile(path.join(root, "workspace.json"));
+      throw Error("Workspace exists. Use --resume to continue it.");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  await mkdir(jobDirectory(root), { recursive: true, mode: 0o700 });
+  const lock = path.join(jobDirectory(root), "starting");
+  const owner = await jobJson(root, "owner.json");
+  if (owner && !alive(owner.pid))
+    await rm(lock, { recursive: true, force: true });
+  let spawned = false;
+  try {
+    await mkdir(lock);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw Error("Another process is starting this session.");
+    throw error;
+  }
+  try {
+    if (!args.includes("--non-interactive")) args.push("--non-interactive");
+    if (!args.includes("--plain")) args.push("--plain");
+    await saveJobJson(root, "request.json", { argv: args, cwd });
+    await saveJobJson(root, "control.json", { action: "run" });
+    const log = await open(
+      path.join(jobDirectory(root), "worker.log"),
+      "a",
+      0o600,
+    );
+    let child;
+    try {
+      child = spawn(
+        process.execPath,
+        [fileURLToPath(new URL("./worker.mjs", import.meta.url)), root],
+        {
+          cwd,
+          env: { ...env, CITEARK_JOB_WORKER: "1" },
+          detached: true,
+          stdio: ["ignore", log.fd, log.fd],
+        },
+      );
+      await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+      });
+    } finally {
+      await log.close();
+    }
+    await saveJobJson(root, "owner.json", { pid: child.pid });
+    spawned = true;
+    child.unref();
+    for (let attempt = 0; attempt < 50; attempt++) {
+      if ((await jobJson(root, "state.json"))?.pid === child.pid) break;
+      if (!alive(child.pid))
+        throw Error(
+          "Research worker failed to start. See .citeark-job/worker.log.",
+        );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    const index = path.join(path.dirname(settingsPath(env)), "sessions");
+    await mkdir(index, { recursive: true, mode: 0o700 });
+    const { createHash } = await import("node:crypto");
+    await writeFile(
+      path.join(
+        index,
+        `${createHash("sha256").update(root).digest("hex")}.json`,
+      ),
+      JSON.stringify({ directory: root }),
+      { mode: 0o600 },
+    );
+    return { pid: child.pid, directory: root };
+  } finally {
+    if (!spawned) await rm(lock, { recursive: true, force: true });
+  }
+}
+
+export async function sessionCommand(argv, parseOptions) {
+  const { takeOption, remoteSession } = await import("../remote/command.mjs");
+  const compute = takeOption(argv, "--compute");
+  if (compute) return remoteSession(argv, compute);
+  const [action = "list", directory, ...rest] = argv;
+  if (action === "list") {
+    let files;
+    const index = path.join(path.dirname(settingsPath()), "sessions");
+    try {
+      files = await readdir(index);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      files = [];
+    }
+    for (const file of files.filter((f) => f.endsWith(".json"))) {
+      const entry = JSON.parse(await readFile(path.join(index, file), "utf8"));
+      try {
+        const s = await inspectJob(entry.directory);
+        console.log(`${s.status}  ${entry.directory}`);
+      } catch (error) {
+        if (error.code !== "ENOENT")
+          console.log(`unavailable  ${entry.directory}`);
+      }
+    }
+    return;
+  }
+  if (!directory)
+    throw Error(
+      "Usage: citeark session status|attach|pause|resume|cancel <workspace>",
+    );
+  const root = path.resolve(directory);
+  if (action === "status" || action === "inspect") {
+    const options = parseOptions(rest, {
+      "--cursor": { type: "string", default: "0" },
+    });
+    const cursor = Number(options["--cursor"]);
+    if (!Number.isSafeInteger(cursor) || cursor < 0)
+      throw Error("Invalid transcript cursor.");
+    const value = await inspectJob(root, cursor);
+    if (action === "status") {
+      delete value.events;
+      delete value.cursor;
+    }
+    console.log(JSON.stringify(value));
+    return value;
+  }
+  if (action === "attach") return attachJob(root);
+  if (action === "note") {
+    const options = parseOptions(rest, {
+      "--message": { type: "string", required: true },
+    });
+    await controlJob(root, options["--message"]);
+    console.log("Instruction queued for the next Agent invocation.");
+    return;
+  }
+  const state = await inspectJob(root);
+  if (!["cancel", "pause", "resume"].includes(action))
+    throw Error(`Unknown session operation: ${action}`);
+  if (terminal.has(state.status) || state.status === "interrupted")
+    throw Error(
+      `Session is ${state.status}. Use citeark start --resume --work-dir ${JSON.stringify(root)} to continue.`,
+    );
+  await saveJobJson(root, "control.json", {
+    action: action === "resume" ? "run" : action,
+    requestedAt: new Date().toISOString(),
+  });
+  console.log(
+    action === "pause"
+      ? "Pause requested; it takes effect at the next stage boundary."
+      : `${action === "cancel" ? "Cancellation" : "Resume"} requested. Use session status to confirm.`,
+  );
+}
+
+export async function controlJob(root, text) {
+  const state = await inspectJob(root);
+  if (terminal.has(state.status) || state.status === "interrupted")
+    throw Error(
+      `Session is ${state.status}; resume it before sending instructions.`,
+    );
+  if (["/pause", "/resume", "/cancel"].includes(text)) {
+    await saveJobJson(root, "control.json", {
+      action: text === "/resume" ? "run" : text.slice(1),
+      requestedAt: new Date().toISOString(),
+    });
+  } else {
+    if (!text.trim()) return;
+    await appendFile(
+      path.join(jobDirectory(root), "notes.jsonl"),
+      JSON.stringify({ at: new Date().toISOString(), text }) + "\n",
+      { mode: 0o600 },
+    );
+  }
+}
+
+export async function attachJob(
+  root,
+  {
+    inspect = inspectJob,
+    control = controlJob,
+    output,
+    cursor: initialCursor = 0,
+  } = {},
+) {
+  const { PlainSession } = await import("../terminal/plain.mjs");
+  const { TerminalScreen } = await import("../terminal/screen.mjs");
+  const interactive =
+    !output &&
+    process.stdin.isTTY &&
+    process.stdout.isTTY &&
+    process.env.TERM !== "dumb";
+  let detached = false;
+  const sink =
+    output ??
+    (interactive
+      ? new TerminalScreen({
+          onExit: () => {
+            detached = true;
+          },
+          onInput: async (text) => {
+            await control(root, text);
+            sink.event({
+              kind: "status",
+              text: text.startsWith("/")
+                ? "Control request sent."
+                : "Instruction queued for the next Agent invocation.",
+            });
+          },
+        })
+      : new PlainSession());
+  const previousExit = sink.onExit,
+    previousInput = sink.onInput;
+  if (output) {
+    sink.onExit = () => {
+      detached = true;
+    };
+    sink.onInput = async (text) => {
+      await control(root, text);
+      sink.event({
+        kind: "status",
+        text: text.startsWith("/")
+          ? "Control request sent."
+          : "Instruction queued for the next Agent invocation.",
+      });
+    };
+  }
+  if (interactive) {
+    sink.context = root;
+    sink.start();
+  }
+  const disconnect = () => {
+    detached = true;
+  };
+  if (!interactive) process.once("SIGINT", disconnect);
+  let cursor = initialCursor,
+    state;
+  try {
+    while (!detached) {
+      state = await inspect(root, cursor);
+      for (const event of state.events) sink.event(event);
+      const progressed = state.cursor !== cursor;
+      cursor = state.cursor;
+      if (
+        (terminal.has(state.status) || state.status === "interrupted") &&
+        !progressed
+      )
+        break;
+      if (!progressed)
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+    if (!detached && interactive) await sink.finish(`Session ${state.status}`);
+  } finally {
+    if (!interactive) process.removeListener("SIGINT", disconnect);
+    if (!output) await sink.close();
+    else {
+      sink.onExit = previousExit;
+      sink.onInput = previousInput;
+    }
+  }
+  if (state?.resourceCleanup?.some((item) => item.status === "failed"))
+    console.log(
+      "Resource cleanup needs attention. Use session status to inspect the resource IDs before resuming.",
+    );
+  console.log(
+    `Session ${detached ? "detached; research continues" : state.status}: ${root}`,
+  );
+  if (state?.experiments)
+    for (const { id, title } of state.experiments)
+      console.log(`${id}  ${title}`);
+  return { ...state, detached, cursor };
+}

package/src/workspace/session.mjs

@@ -0,0 +1,97 @@
+import { reproductionCampaign } from '../compute/campaign.mjs';
+import { generateKeyPairSync } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { executeFullPipeline } from '../pipeline/orchestrator.mjs';
+import { projectSharedExecutionClaim } from '../pipeline/shared-execution.mjs';
+import { resolveReproductionTargets } from '../pipeline/targets.mjs';
+import { createScientificAssessor } from '../verification/ai-assessor.mjs';
+import { readJson, writeJson, pathExists } from '../util.mjs';
+
+export async function ensureSigningKey(filename = path.join(process.env.CITEARK_CONFIG_DIR ?? path.join(homedir(), '.citeark'), 'signing-key.pem')) {
+  if (!await pathExists(filename)) {
+    await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
+    const privateKey = generateKeyPairSync('ed25519').privateKey.export({ type: 'pkcs8', format: 'pem' });
+    await writeFile(filename, privateKey, { flag: 'wx', mode: 0o600 });
+  }
+  return filename;
+}
+
+export function selectResearchTargets(research, experimentIds) {
+  if (!experimentIds?.length) throw Error('Select experiments to run, or use --plan-only to save the plan.');
+  const selected = [...new Set(experimentIds)];
+  const targets = selected.flatMap(experimentId => {
+    const experiment = research.experiments.find(item => item.id === experimentId);
+    if (!experiment) throw Error(`Unknown experiment: ${experimentId}`);
+    const matches = resolveReproductionTargets(research, { experimentId });
+    if (!matches.length) throw Error(`Experiment ${experimentId} has no verifiable measurement targets.`);
+    return matches;
+  });
+  return targets;
+}
+
+export async function planWorkspace({ directory, input, agentRuntime, computeCatalogPath, computePolicyPath,
+  computeProfile, executorOptions, signingKeyPath, dryRun = false, progress = message => console.log(message) },
+  { pipeline = executeFullPipeline } = {}) {
+  executorOptions = { ...executorOptions, gcpBatch: { onCheckpoint: async () => {}, ...executorOptions?.gcpBatch }, autoDl: { onCheckpoint: async () => {}, ...executorOptions?.autoDl } };
+  const root = path.resolve(directory);
+  const sessionPath = path.join(root, 'workspace.json');
+  const session = await pathExists(sessionPath) ? await readJson(sessionPath) : {
+    schemaVersion: '1.0', input, computeCatalogPath, computePolicyPath, computeProfile,
+    phase: 'planning', artifacts: [] };
+  await writeJson(sessionPath, session);
+  if (session.researchPath && !dryRun) return { session, research: await readJson(session.researchPath) };
+  const planningDirectory = path.join(root, 'planning');
+  const plan = await pipeline({ compileTaskPath: session.input.compileTaskPath, workDirectory: planningDirectory,
+    stopAfter: 'research_plan', agentRuntime, computeCatalogPath, computePolicyPath, computeProfile, executorOptions,
+    signingKeyPath, sourceArtifactDigests: session.input.sourceArtifactDigests,
+    sourceCompilationDigests: session.input.sourceCompilationDigests,
+    dryRun, progress, resume: await pathExists(path.join(planningDirectory, 'pipeline.json')) });
+  if (dryRun) return { dryRun: true, session, plan };
+  session.researchPath = path.join(planningDirectory, 'research.normalized.json');
+  session.planningArtifact = { path: plan.researchPlanArchive.path, digest: plan.researchPlan.artifactDigest };
+  session.phase = 'awaiting_selection';
+  session.artifacts = plan.researchPlanArchive ? [plan.researchPlanArchive.path] : [];
+  await writeJson(sessionPath, session);
+  return { session, research: plan.research };
+}
+
+export async function executeWorkspace({ directory, experimentIds, agentRuntime, assessmentRuntime = agentRuntime, executorOptions, signingKeyPath,
+  progress = message => console.log(message) }, { pipeline = executeFullPipeline, project = projectSharedExecutionClaim } = {}) {
+  executorOptions = { ...executorOptions, gcpBatch: { onCheckpoint: async () => {}, ...executorOptions?.gcpBatch }, autoDl: { onCheckpoint: async () => {}, ...executorOptions?.autoDl } };
+  const root = path.resolve(directory);
+  const sessionPath = path.join(root, 'workspace.json');
+  const session = await readJson(sessionPath);
+  const research = await readJson(session.researchPath);
+  if (session.phase === 'completed') return session;
+  const targets = reproductionCampaign(research, session.targets ?? selectResearchTargets(research, experimentIds)).targets;
+  if (session.targets && experimentIds?.length &&
+    JSON.stringify([...new Set(session.targets.map(t => t.experimentId))].sort()) !== JSON.stringify([...new Set(experimentIds)].sort())) {
+    throw Error('Resuming preserves the selected experiments. Create a new workspace for a different selection.');
+  }
+  session.targets = targets;
+  session.phase = 'executing';
+  await writeJson(sessionPath, session);
+  const executionDirectory = path.join(root, 'execution');
+  const assessor = createScientificAssessor({ runtimeAgent: assessmentRuntime, providerSecret: executorOptions?.gcpBatch?.providerSecret });
+  const first = await pipeline({ researchPath: session.researchPath, workDirectory: executionDirectory,
+    executionTargets: targets, claimId: targets[0].claimId, experimentId: targets[0].experimentId,
+    agentRuntime, executorOptions, signingKeyPath, scientificAssessor: assessor,
+    computeCatalogPath: session.computeCatalogPath, computePolicyPath: session.computePolicyPath,
+    computeProfile: session.computeProfile, referenceMaterialsPath: session.input.referenceMaterialsPath,
+    sourceArtifactDigests: [...new Set([...(session.input.sourceArtifactDigests ?? []), session.planningArtifact.digest])],
+    sourceCompilationDigests: session.input.sourceCompilationDigests,
+    resume: await pathExists(path.join(executionDirectory, 'pipeline.json')), progress });
+  const artifacts = [session.planningArtifact.path, first.researchPlanArchive.path, first.archive.path];
+  for (const [index, target] of targets.slice(1).entries()) {
+    const result = await project({ sourcePipeline: first, researchPath: session.researchPath,
+      ...target, workDirectory: path.join(root, `result-${index + 2}`), signingKeyPath,
+      researchArtifactDigest: first.researchPlan.artifactDigest, scientificAssessor: assessor });
+    artifacts.push(result.archive.path);
+  }
+  session.phase = 'completed';
+  session.artifacts = artifacts;
+  await writeJson(sessionPath, session);
+  return session;
+}