autoresearcher 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# autoresearcher
+
+`autoresearcher` is a standalone terminal CLI for benchmark-driven autonomous research loops.
+
+It runs this cycle repeatedly:
+
+1. Run one internal headless agent iteration.
+2. Run your benchmark command.
+3. Parse metric with a regex.
+4. Keep iteration only if metric improved.
+
+## Quick Start
+
+```bash
+npm i -g autoresearcher
+
+# In your research repo:
+cd /path/to/your/new-repo
+autoresearcher wizard
+autoresearcher run --iterations 20
+```
+
+## Commands
+
+```bash
+autoresearcher init
+autoresearcher wizard
+autoresearcher run [--iterations N]
+autoresearcher progress [--run-id <id>] [--output <file.svg|file.png>]
+```
+
+## Important Config
+
+The `init` command creates `.autoresearcher/config.json`:
+
+```json
+{
+  "agentMode": "internal",
+  "agentPromptFile": "program.md",
+  "agentPrompt": "Improve the benchmark metric while preserving correctness, test behavior, and safety.",
+  "agentCommand": "./scripts/agent-step.sh",
+  "backendAgent": "",
+  "backendModel": "",
+  "backendMaxIterations": 1,
+  "benchmarkCommand": "./scripts/benchmark.sh",
+  "metricRegex": "score=([0-9.]+)",
+  "direction": "max",
+  "iterations": 20,
+  "autoCommit": false,
+  "onRejectCommand": "",
+  "onKeepCommand": "",
+  "stopOnAgentFailure": true,
+  "streamAgentOutput": true,
+  "commitMessageTemplate": "research: improved metric to {metric} (iter {iteration})"
+}
+```
+
+`agentMode: "internal"` is the default. For a fully custom step command, set `agentMode` to `"command"` and edit `agentCommand`.
+
+## Example Configs
+
+Default internal headless mode:
+
+```json
+{
+  "agentMode": "internal",
+  "agentPromptFile": "program.md",
+  "agentPrompt": "Improve benchmark with safe, minimal changes.",
+  "backendAgent": "amp",
+  "backendModel": "claude-sonnet-4-5-20250929",
+  "backendMaxIterations": 1,
+  "benchmarkCommand": "./scripts/benchmark.sh",
+  "metricRegex": "score=([0-9.]+)",
+  "direction": "max",
+  "iterations": 40,
+  "autoCommit": false
+}
+```
+
+Custom command mode:
+
+```json
+{
+  "agentMode": "command",
+  "agentCommand": "./scripts/agent-step.sh",
+  "benchmarkCommand": "./scripts/benchmark.sh",
+  "metricRegex": "score=([0-9.]+)",
+  "direction": "max",
+  "iterations": 40
+}
+```
+
+## Typical Real Setup
+
+1. Start with internal mode and tailor `agentPrompt` to your objective.
+2. Set one provider key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`).
+3. Optionally pin `backendAgent` and `backendModel`.
+4. Edit `program.md` with your experiment objective and constraints.
+5. Replace `./scripts/benchmark.sh` so it prints one numeric metric, like `score=0.8123`.
+6. Set `direction` to `max` or `min`.
+7. Optionally switch to `agentMode: "command"` and customize `agentCommand`.
+8. Optionally set `onRejectCommand` to revert non-improving changes.
+
+## Progress Graph
+
+Generate a chart from the latest run:
+
+```bash
+autoresearcher progress --output progress.png
+```
+
+For a specific run ID:
+
+```bash
+autoresearcher progress --run-id 2026-03-13T12-51-48-680Z --output run.svg
+```
+
+Example progress graph:
+
+![Post-Quantum Progress Example](https://raw.githubusercontent.com/multivmlabs/autoresearcher/main/apps/docs/docs/public/images/post-quantum-progress.png)
+
+## Logs
+
+Every run writes JSONL logs in `.autoresearcher/runs/<timestamp>.jsonl`.

package/bin/autoresearcher.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "autoresearcher",
+  "version": "0.1.0",
+  "description": "Benchmark-driven autonomous research CLI for post-quantum and blockchain R&D",
+  "type": "module",
+  "bin": {
+    "autoresearcher": "bin/autoresearcher.js"
+  },
+  "scripts": {
+    "start": "node ./bin/autoresearcher.js",
+    "check": "node ./bin/autoresearcher.js --help",
+    "build": "echo \"no build step for plain node cli\""
+  },
+  "keywords": [
+    "cli",
+    "autoresearch",
+    "benchmark",
+    "agent",
+    "post-quantum",
+    "blockchain",
+    "cryptography"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multivmlabs/autoresearcher.git"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "homepage": "https://autoresearcher.multivmlabs.com",
+  "license": "MIT",
+  "dependencies": {
+    "ralph-starter": "^0.4.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,357 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { stdin as input, stdout as output } from 'node:process';
+import readline from 'node:readline/promises';
+import { loadConfig, writeConfig, CONFIG_DIR } from './config.js';
+import { DEFAULT_AGENT_MODE, DEFAULT_AGENT_PROMPT } from './internal-backend.js';
+import { generateProgressChart } from './progress-chart.js';
+import { runResearchLoop } from './run-loop.js';
+
+const AGENT_CHOICES = [
+  { label: 'Auto-detect (recommended)', value: '' },
+  { label: 'amp', value: 'amp' },
+  { label: 'claude-code', value: 'claude-code' },
+  { label: 'codex', value: 'codex' },
+  { label: 'cursor', value: 'cursor' },
+  { label: 'opencode', value: 'opencode' },
+  { label: 'openclaw', value: 'openclaw' },
+];
+
+const MODEL_CHOICES = [
+  { label: 'Use backend default (recommended)', value: '' },
+  { label: 'claude-sonnet-4-5-20250929', value: 'claude-sonnet-4-5-20250929' },
+  { label: 'gpt-5', value: 'gpt-5' },
+  { label: 'Custom model ID', value: '__custom__' },
+];
+
+function parseArgs(args) {
+  const result = { _: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (!token.startsWith('--')) {
+      result._.push(token);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = args[i + 1];
+    if (!next || next.startsWith('--')) {
+      result[key] = true;
+      continue;
+    }
+
+    result[key] = next;
+    i++;
+  }
+
+  return result;
+}
+
+function printHelp() {
+  console.log(`
+autoresearcher - benchmark-driven autonomous research CLI
+
+Usage:
+  autoresearcher init
+  autoresearcher wizard
+  autoresearcher run [--iterations N] [--agent-prompt "..."] [--benchmark-command "..."]
+  autoresearcher progress [--run-id <id>] [--output <file.svg|file.png>]
+  autoresearcher --help
+
+Key config fields:
+  agentMode             "internal" (default) or "command"
+  agentPromptFile       Markdown objective file (default: program.md)
+  agentPrompt           Iteration objective for internal headless agent backend
+  backendAgent          Optional backend agent override (amp/codex/claude-code/...)
+  backendModel          Optional backend model override (provider-specific)
+  agentCommand          Shell command when agentMode is "command"
+  benchmarkCommand      Shell command that prints metric output
+  metricRegex           Regex with capture group, e.g. "score=([0-9.]+)"
+  direction             "max" or "min"
+  iterations            Loop count
+  autoCommit            true/false (git add/commit on improvements)
+  onRejectCommand       Optional command for rejected iterations
+
+Examples:
+  autoresearcher init
+  autoresearcher wizard
+  autoresearcher run --iterations 30
+  autoresearcher progress --output progress.png
+  autoresearcher run --agent-prompt "improve benchmark metric without regressions"
+  autoresearcher run --agent-command "amp -p 'improve benchmark'" --benchmark-command "./scripts/benchmark.sh"
+`);
+}
+
+function createDefaultConfig() {
+  return {
+    agentMode: DEFAULT_AGENT_MODE,
+    agentPromptFile: 'program.md',
+    agentPrompt: DEFAULT_AGENT_PROMPT,
+    agentCommand: './scripts/agent-step.sh',
+    backendAgent: '',
+    backendModel: '',
+    backendMaxIterations: 1,
+    benchmarkCommand: './scripts/benchmark.sh',
+    metricRegex: 'score=([0-9.]+)',
+    direction: 'max',
+    iterations: 20,
+    autoCommit: false,
+    onRejectCommand: '',
+    onKeepCommand: '',
+    stopOnAgentFailure: true,
+    streamAgentOutput: true,
+    commitMessageTemplate: 'research: improved metric to {metric} (iter {iteration})',
+  };
+}
+
+async function writeProgramFile(cwd, programFile = 'program.md', objective = DEFAULT_AGENT_PROMPT) {
+  if (!programFile) return;
+
+  const programPath = path.resolve(cwd, programFile);
+
+  try {
+    await fs.access(programPath);
+    return;
+  } catch {
+    // File does not exist yet, create it from template.
+  }
+
+  const template = `# Research Program
+
+Objective:
+${objective}
+
+Constraints:
+- Preserve correctness and existing behavior.
+- Keep changes minimal and measurable.
+- Avoid adding unnecessary complexity.
+
+Iteration Policy:
+1. Propose one improvement.
+2. Run benchmark.
+3. Keep only metric improvements.
+`;
+
+  await fs.writeFile(programPath, template, 'utf8');
+}
+
+async function selectChoice(rl, title, options, currentValue = '') {
+  const fallbackIndex = 0;
+  const currentIndex = options.findIndex((option) => option.value === currentValue);
+  const defaultIndex = currentIndex >= 0 ? currentIndex : fallbackIndex;
+
+  console.log(`\n${title}`);
+  options.forEach((option, index) => {
+    console.log(`  ${index + 1}. ${option.label}`);
+  });
+
+  while (true) {
+    const answer = (await rl.question(`Select option [${defaultIndex + 1}]: `)).trim();
+    if (!answer) {
+      return options[defaultIndex].value;
+    }
+
+    const index = Number.parseInt(answer, 10);
+    if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+      return options[index - 1].value;
+    }
+
+    console.log(`Please enter a number between 1 and ${options.length}.`);
+  }
+}
+
+async function askText(rl, label, defaultValue = '') {
+  const suffix = defaultValue ? ` [${defaultValue}]` : '';
+  const answer = (await rl.question(`${label}${suffix}: `)).trim();
+  return answer || defaultValue;
+}
+
+async function runWizard() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('Wizard requires an interactive terminal. Use "autoresearcher init" for non-interactive setup.');
+  }
+
+  const cwd = process.cwd();
+  const existingConfig = await loadConfig(cwd).catch(() => null);
+  const base = {
+    ...createDefaultConfig(),
+    ...(existingConfig || {}),
+  };
+
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    console.log('autoresearcher setup wizard');
+    console.log('This configures internal mode with your preferred agent and model.');
+
+    const backendAgent = await selectChoice(rl, 'Choose backend agent', AGENT_CHOICES, base.backendAgent || '');
+    const modelSelection = await selectChoice(rl, 'Choose backend model', MODEL_CHOICES, base.backendModel || '');
+
+    let backendModel = modelSelection;
+    if (modelSelection === '__custom__') {
+      backendModel = await askText(rl, 'Enter custom model ID', base.backendModel || '');
+    }
+
+    const agentPrompt = await askText(rl, 'Iteration objective prompt', base.agentPrompt || DEFAULT_AGENT_PROMPT);
+    const agentPromptFile = await askText(rl, 'Objective file path', base.agentPromptFile || 'program.md');
+    const benchmarkCommand = await askText(rl, 'Benchmark command', base.benchmarkCommand || './scripts/benchmark.sh');
+    const metricRegex = await askText(rl, 'Metric regex', base.metricRegex || 'score=([0-9.]+)');
+    const direction = await selectChoice(
+      rl,
+      'Metric direction',
+      [
+        { label: 'max (higher is better)', value: 'max' },
+        { label: 'min (lower is better)', value: 'min' },
+      ],
+      base.direction === 'min' ? 'min' : 'max'
+    );
+
+    const iterationInput = await askText(rl, 'Iterations per run', String(base.iterations ?? 20));
+    const parsedIterations = Number.parseInt(iterationInput, 10);
+    const iterations = Number.isInteger(parsedIterations) && parsedIterations > 0 ? parsedIterations : 20;
+
+    const config = {
+      ...base,
+      agentMode: DEFAULT_AGENT_MODE,
+      backendAgent,
+      backendModel,
+      agentPromptFile,
+      agentPrompt,
+      benchmarkCommand,
+      metricRegex,
+      direction,
+      iterations,
+    };
+
+    const configPath = await writeConfig(config, cwd);
+    await writeExampleScripts(cwd);
+    await writeProgramFile(cwd, config.agentPromptFile, config.agentPrompt);
+
+    console.log(`\nSaved config to ${configPath}`);
+    console.log('Created or refreshed program/objective and script templates');
+    console.log('Run: autoresearcher run');
+  } finally {
+    rl.close();
+  }
+}
+
+async function writeExampleScripts(cwd) {
+  const scriptsDir = path.join(cwd, 'scripts');
+  await fs.mkdir(scriptsDir, { recursive: true });
+
+  const benchmarkPath = path.join(scriptsDir, 'benchmark.sh');
+  const agentPath = path.join(scriptsDir, 'agent-step.sh');
+
+  const benchmarkScript = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Demo metric: random score for quick smoke testing.
+SCORE=$(awk 'BEGIN{srand(); printf "%.6f", rand()}')
+echo "score=$SCORE"
+`;
+
+  const agentScript = `#!/usr/bin/env bash
+set -euo pipefail
+
+echo "agent iteration: \${AR_ITERATION:-0}"
+# Optional: switch agentMode to "command" and use this script.
+# Example: amp -p "improve benchmark metric"
+`;
+
+  await fs.writeFile(benchmarkPath, benchmarkScript, 'utf8');
+  await fs.writeFile(agentPath, agentScript, 'utf8');
+  await fs.chmod(benchmarkPath, 0o755);
+  await fs.chmod(agentPath, 0o755);
+}
+
+async function runInit() {
+  const config = createDefaultConfig();
+
+  const configPath = await writeConfig(config, process.cwd());
+  await writeExampleScripts(process.cwd());
+  await writeProgramFile(process.cwd(), config.agentPromptFile, config.agentPrompt);
+
+  console.log(`Initialized ${CONFIG_DIR} config at:`);
+  console.log(`  ${configPath}`);
+  console.log('Created program.md and example scripts in ./scripts/.');
+  console.log('Next step: edit program.md and benchmark script, then run: autoresearcher run');
+}
+
+function buildOverrides(parsed) {
+  const map = {
+    'agent-mode': 'agentMode',
+    'agent-prompt-file': 'agentPromptFile',
+    'agent-prompt': 'agentPrompt',
+    iterations: 'iterations',
+    'agent-command': 'agentCommand',
+    'backend-agent': 'backendAgent',
+    'backend-model': 'backendModel',
+    'backend-max-iterations': 'backendMaxIterations',
+    'benchmark-command': 'benchmarkCommand',
+    'metric-regex': 'metricRegex',
+    direction: 'direction',
+    'on-reject-command': 'onRejectCommand',
+    'on-keep-command': 'onKeepCommand',
+    'commit-template': 'commitMessageTemplate',
+  };
+
+  const overrides = {};
+  for (const [cliKey, configKey] of Object.entries(map)) {
+    if (parsed[cliKey] !== undefined) {
+      overrides[configKey] = parsed[cliKey];
+    }
+  }
+
+  if (parsed['agent-command'] !== undefined && parsed['agent-mode'] === undefined) {
+    overrides.agentMode = 'command';
+  }
+  if (parsed['agent-prompt'] !== undefined && parsed['agent-mode'] === undefined) {
+    overrides.agentMode = 'internal';
+  }
+
+  if (parsed['auto-commit'] === true) overrides.autoCommit = true;
+  if (parsed['no-auto-commit'] === true) overrides.autoCommit = false;
+  if (parsed['stream-agent-output'] === true) overrides.streamAgentOutput = true;
+  if (parsed['no-stream-agent-output'] === true) overrides.streamAgentOutput = false;
+
+  return overrides;
+}
+
+export async function runCli(args) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const command = args[0];
+  const parsed = parseArgs(args.slice(1));
+
+  if (command === 'init') {
+    await runInit();
+    return;
+  }
+
+  if (command === 'wizard') {
+    await runWizard();
+    return;
+  }
+
+  if (command === 'run') {
+    const config = await loadConfig(process.cwd());
+    const overrides = buildOverrides(parsed);
+    await runResearchLoop(config, overrides);
+    return;
+  }
+
+  if (command === 'progress') {
+    const chartPath = await generateProgressChart({
+      runId: parsed['run-id'],
+      output: parsed.output,
+    });
+    console.log(`Progress chart written: ${chartPath}`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}

package/src/config.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const CONFIG_DIR = '.autoresearcher';
+export const CONFIG_FILE = 'config.json';
+const LEGACY_CONFIG_DIR = '.ar-agent';
+
+export function getConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, CONFIG_DIR, CONFIG_FILE);
+}
+
+export async function loadConfig(cwd = process.cwd()) {
+  let filePath = getConfigPath(cwd);
+  try {
+    await fs.access(filePath);
+  } catch {
+    filePath = path.join(cwd, LEGACY_CONFIG_DIR, CONFIG_FILE);
+  }
+  const raw = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function writeConfig(config, cwd = process.cwd()) {
+  const dirPath = path.join(cwd, CONFIG_DIR);
+  const filePath = getConfigPath(cwd);
+  await fs.mkdir(dirPath, { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return filePath;
+}

package/src/internal-backend.js

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const DEFAULT_AGENT_MODE = 'internal';
+export const DEFAULT_AGENT_PROMPT =
+  'Improve the benchmark metric while preserving correctness, test behavior, and safety.';
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function resolveBackendRunner() {
+  if (process.env.AR_INTERNAL_BACKEND_COMMAND) {
+    return process.env.AR_INTERNAL_BACKEND_COMMAND;
+  }
+
+  try {
+    const packagePath = require.resolve('ralph-starter/package.json');
+    const packageDir = path.dirname(packagePath);
+    const cliPath = path.join(packageDir, 'dist', 'cli.js');
+    return `${shellQuote(process.execPath)} ${shellQuote(cliPath)}`;
+  } catch {
+    return 'ralph-starter';
+  }
+}
+
+export function resolveAgentMode(config) {
+  if (config.agentMode === 'command' || config.agentMode === 'internal') {
+    return config.agentMode;
+  }
+
+  if (config.agentCommand) {
+    return 'command';
+  }
+
+  return DEFAULT_AGENT_MODE;
+}
+
+export function buildInternalBackendCommand({
+  cwd,
+  iteration,
+  runId,
+  agentPrompt,
+  backendAgent,
+  backendModel,
+  backendMaxIterations,
+}) {
+  const backendRunner = resolveBackendRunner();
+  const maxIterations = Number(backendMaxIterations ?? 1);
+  const safeMaxIterations = Number.isFinite(maxIterations) && maxIterations > 0 ? Math.floor(maxIterations) : 1;
+  const prompt = agentPrompt || DEFAULT_AGENT_PROMPT;
+
+  const contextualPrompt = `${prompt}\n\nIteration context:\n- run_id: ${runId}\n- iteration: ${iteration}`;
+
+  let command = `${backendRunner} run ${shellQuote(contextualPrompt)}`;
+  command += ' --auto';
+  command += ` --max-iterations ${safeMaxIterations}`;
+  command += ` --output-dir ${shellQuote(cwd)}`;
+  command += ' --no-track-progress --no-track-cost';
+
+  if (backendAgent) {
+    command += ` --agent ${shellQuote(backendAgent)}`;
+  }
+
+  if (backendModel) {
+    command += ` --model ${shellQuote(backendModel)}`;
+  }
+
+  return command;
+}

package/src/progress-chart.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+import { runCommand } from './shell.js';
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function linePath(points, xScale, yScale) {
+  if (points.length === 0) return '';
+  return points
+    .map((point, index) => {
+      const x = xScale(point.iteration);
+      const y = yScale(point.metric);
+      return `${index === 0 ? 'M' : 'L'}${x.toFixed(2)} ${y.toFixed(2)}`;
+    })
+    .join(' ');
+}
+
+function buildTicks(minValue, maxValue, count = 5) {
+  if (minValue === maxValue) return [minValue];
+  const step = (maxValue - minValue) / (count - 1);
+  return Array.from({ length: count }, (_, index) => minValue + step * index);
+}
+
+async function resolveRunLogFile(cwd, runId) {
+  const runsDir = path.join(cwd, CONFIG_DIR, 'runs');
+  await fs.mkdir(runsDir, { recursive: true });
+
+  if (runId) {
+    return {
+      runId,
+      filePath: path.join(runsDir, `${runId}.jsonl`),
+      runsDir,
+    };
+  }
+
+  const files = await fs.readdir(runsDir);
+  const runFiles = files.filter((file) => file.endsWith('.jsonl')).sort();
+  if (runFiles.length === 0) {
+    throw new Error(`No run logs found in ${runsDir}`);
+  }
+
+  const fileName = runFiles[runFiles.length - 1];
+  return {
+    runId: fileName.replace(/\.jsonl$/, ''),
+    filePath: path.join(runsDir, fileName),
+    runsDir,
+  };
+}
+
+async function loadChartData(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  const lines = raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const entries = lines.map((line) => JSON.parse(line));
+
+  const metricPoints = entries
+    .filter((entry) => Number.isFinite(entry.metric) && Number.isFinite(entry.iteration))
+    .map((entry) => ({
+      iteration: Number(entry.iteration),
+      metric: Number(entry.metric),
+      status: entry.status,
+    }));
+
+  const bestPoints = entries
+    .filter((entry) => Number.isFinite(entry.bestMetric) && Number.isFinite(entry.iteration))
+    .map((entry) => ({
+      iteration: Number(entry.iteration),
+      metric: Number(entry.bestMetric),
+    }));
+
+  if (metricPoints.length === 0) {
+    throw new Error('Run log does not contain plottable metric points.');
+  }
+
+  return { metricPoints, bestPoints };
+}
+
+function renderSvg({ runId, metricPoints, bestPoints }) {
+  const width = 1200;
+  const height = 680;
+  const margin = { top: 72, right: 48, bottom: 72, left: 88 };
+  const plotWidth = width - margin.left - margin.right;
+  const plotHeight = height - margin.top - margin.bottom;
+
+  const allMetrics = [...metricPoints.map((point) => point.metric), ...bestPoints.map((point) => point.metric)];
+  const minMetric = Math.min(...allMetrics);
+  const maxMetric = Math.max(...allMetrics);
+  const metricRange = Math.max(maxMetric - minMetric, Math.max(Math.abs(maxMetric) * 0.05, 1e-9));
+  const yMin = minMetric - metricRange * 0.15;
+  const yMax = maxMetric + metricRange * 0.15;
+
+  const minIteration = Math.min(...metricPoints.map((point) => point.iteration));
+  const maxIteration = Math.max(...metricPoints.map((point) => point.iteration));
+  const iterationRange = Math.max(maxIteration - minIteration, 1);
+
+  const xScale = (iteration) => margin.left + ((iteration - minIteration) / iterationRange) * plotWidth;
+  const yScale = (metric) => margin.top + ((yMax - metric) / (yMax - yMin)) * plotHeight;
+
+  const xTicks = buildTicks(minIteration, maxIteration, Math.min(6, iterationRange + 1));
+  const yTicks = buildTicks(yMin, yMax, 6);
+
+  const metricPath = linePath(metricPoints, xScale, yScale);
+  const bestPath = linePath(bestPoints, xScale, yScale);
+
+  const pointDots = metricPoints
+    .map((point) => {
+      const color = point.status === 'keep' ? '#7fd3ff' : '#4a5f79';
+      return `<circle cx="${xScale(point.iteration).toFixed(2)}" cy="${yScale(point.metric).toFixed(2)}" r="4" fill="${color}" />`;
+    })
+    .join('\n');
+
+  const xTickLines = xTicks
+    .map((tick) => {
+      const x = xScale(tick).toFixed(2);
+      const label = Number.isInteger(tick) ? String(Math.round(tick)) : tick.toFixed(1);
+      return `<line x1="${x}" y1="${margin.top}" x2="${x}" y2="${height - margin.bottom}" stroke="#14202f" stroke-width="1" />
+<text x="${x}" y="${height - margin.bottom + 26}" text-anchor="middle" fill="#9bb0c8" font-size="13">${label}</text>`;
+    })
+    .join('\n');
+
+  const yTickLines = yTicks
+    .map((tick) => {
+      const y = yScale(tick).toFixed(2);
+      return `<line x1="${margin.left}" y1="${y}" x2="${width - margin.right}" y2="${y}" stroke="#14202f" stroke-width="1" />
+<text x="${margin.left - 12}" y="${(Number(y) + 5).toFixed(2)}" text-anchor="end" fill="#9bb0c8" font-size="13">${tick.toFixed(6)}</text>`;
+    })
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <rect width="100%" height="100%" fill="#000000" />
+  <text x="${margin.left}" y="40" fill="#f2f7ff" font-size="28" font-family="Inter, system-ui, sans-serif" font-weight="700">autoresearcher progress</text>
+  <text x="${margin.left}" y="62" fill="#8ea1b9" font-size="14" font-family="Inter, system-ui, sans-serif">run ${runId}</text>
+
+  ${xTickLines}
+  ${yTickLines}
+
+  <line x1="${margin.left}" y1="${height - margin.bottom}" x2="${width - margin.right}" y2="${height - margin.bottom}" stroke="#304156" stroke-width="1.5" />
+  <line x1="${margin.left}" y1="${margin.top}" x2="${margin.left}" y2="${height - margin.bottom}" stroke="#304156" stroke-width="1.5" />
+
+  <path d="${metricPath}" fill="none" stroke="#4a5f79" stroke-width="2" />
+  <path d="${bestPath}" fill="none" stroke="#7fd3ff" stroke-width="3" />
+  ${pointDots}
+
+  <text x="${margin.left}" y="${height - 18}" fill="#8ea1b9" font-size="13" font-family="Inter, system-ui, sans-serif">iteration</text>
+  <text x="18" y="${margin.top - 18}" fill="#8ea1b9" font-size="13" font-family="Inter, system-ui, sans-serif">metric</text>
+
+  <rect x="${width - 255}" y="30" width="205" height="54" rx="10" fill="#070b11" stroke="#1b2635" />
+  <line x1="${width - 240}" y1="50" x2="${width - 200}" y2="50" stroke="#7fd3ff" stroke-width="3" />
+  <text x="${width - 192}" y="54" fill="#d5e8fb" font-size="13" font-family="Inter, system-ui, sans-serif">best so far</text>
+  <line x1="${width - 240}" y1="70" x2="${width - 200}" y2="70" stroke="#4a5f79" stroke-width="2" />
+  <text x="${width - 192}" y="74" fill="#d5e8fb" font-size="13" font-family="Inter, system-ui, sans-serif">iteration metric</text>
+</svg>`;
+}
+
+export async function generateProgressChart({ runId, output }) {
+  const cwd = process.cwd();
+  const { runId: resolvedRunId, filePath, runsDir } = await resolveRunLogFile(cwd, runId);
+  const chartData = await loadChartData(filePath);
+
+  const chartsDir = path.join(path.dirname(runsDir), 'charts');
+  await fs.mkdir(chartsDir, { recursive: true });
+
+  const outputPath = output
+    ? path.resolve(cwd, output)
+    : path.join(chartsDir, `${resolvedRunId}.svg`);
+
+  const ext = path.extname(outputPath).toLowerCase();
+  const svg = renderSvg({ runId: resolvedRunId, ...chartData });
+
+  if (!ext || ext === '.svg') {
+    const target = ext ? outputPath : `${outputPath}.svg`;
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, svg, 'utf8');
+    return target;
+  }
+
+  if (ext === '.png') {
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    const tempSvgPath = path.join(
+      path.dirname(outputPath),
+      `${path.basename(outputPath, '.png')}.tmp-${Date.now()}.svg`
+    );
+
+    await fs.writeFile(tempSvgPath, svg, 'utf8');
+    const convertResult = await runCommand(
+      `sips -s format png ${shellQuote(tempSvgPath)} --out ${shellQuote(outputPath)}`,
+      { cwd }
+    );
+
+    await fs.unlink(tempSvgPath).catch(() => {});
+
+    if (convertResult.code !== 0) {
+      throw new Error('PNG export requires macOS sips. Use --output <name>.svg or install a converter.');
+    }
+
+    return outputPath;
+  }
+
+  throw new Error('Unsupported output extension. Use .svg or .png');
+}

package/src/run-loop.js

@@ -0,0 +1,238 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+import {
+  buildInternalBackendCommand,
+  DEFAULT_AGENT_PROMPT,
+  resolveAgentMode,
+} from './internal-backend.js';
+import { runCommand } from './shell.js';
+
+function parseMetric(output, metricRegex) {
+  const regex = new RegExp(metricRegex, 'm');
+  const match = output.match(regex);
+  if (!match || !match[1]) return null;
+  const metric = Number(match[1]);
+  return Number.isFinite(metric) ? metric : null;
+}
+
+function isBetter(metric, best, direction) {
+  if (best == null) return true;
+  return direction === 'min' ? metric < best : metric > best;
+}
+
+async function appendRunLog(cwd, runId, entry) {
+  const runsDir = path.join(cwd, CONFIG_DIR, 'runs');
+  const runFile = path.join(runsDir, `${runId}.jsonl`);
+  await fs.mkdir(runsDir, { recursive: true });
+  await fs.appendFile(runFile, `${JSON.stringify(entry)}\n`, 'utf8');
+}
+
+async function getGitCommit(cwd) {
+  const result = await runCommand('git rev-parse --short HEAD', { cwd });
+  return result.code === 0 ? result.stdout.trim() : null;
+}
+
+async function hasGitChanges(cwd) {
+  const result = await runCommand('git status --porcelain', { cwd });
+  return result.code === 0 && result.stdout.trim().length > 0;
+}
+
+function getAgentStepCommand(merged, cwd, iteration, runId, agentPrompt) {
+  const agentMode = resolveAgentMode(merged);
+
+  if (agentMode === 'internal') {
+    return {
+      agentMode,
+      command: buildInternalBackendCommand({
+        cwd,
+        iteration,
+        runId,
+        agentPrompt,
+        backendAgent: merged.backendAgent,
+        backendModel: merged.backendModel,
+        backendMaxIterations: merged.backendMaxIterations,
+      }),
+    };
+  }
+
+  return {
+    agentMode,
+    command: merged.agentCommand,
+  };
+}
+
+async function resolveAgentPrompt(merged, cwd) {
+  if (merged.agentPromptFile) {
+    const promptPath = path.resolve(cwd, merged.agentPromptFile);
+    try {
+      const raw = await fs.readFile(promptPath, 'utf8');
+      const prompt = raw.trim();
+      if (prompt) {
+        return { prompt, source: merged.agentPromptFile };
+      }
+    } catch {
+      // Fall back to inline prompt when file does not exist.
+    }
+  }
+
+  return {
+    prompt: merged.agentPrompt || DEFAULT_AGENT_PROMPT,
+    source: 'config.agentPrompt',
+  };
+}
+
+export async function runResearchLoop(config, cliOverrides = {}) {
+  const cwd = process.cwd();
+  const merged = {
+    ...config,
+    ...cliOverrides,
+  };
+
+  const required = ['benchmarkCommand', 'metricRegex'];
+  for (const key of required) {
+    if (!merged[key]) {
+      throw new Error(`Missing required config: ${key}`);
+    }
+  }
+
+  const agentMode = resolveAgentMode(merged);
+  if (agentMode === 'command' && !merged.agentCommand) {
+    throw new Error('Missing required config: agentCommand (required when agentMode="command")');
+  }
+
+  const direction = merged.direction === 'min' ? 'min' : 'max';
+  const iterations = Number(merged.iterations ?? 20);
+  const runId = new Date().toISOString().replace(/[:.]/g, '-');
+  const resolvedPrompt = await resolveAgentPrompt(merged, cwd);
+
+  let bestMetric = null;
+  let bestIteration = 0;
+
+  console.log(`Starting run ${runId}`);
+  console.log(`Agent mode: ${agentMode}`);
+  if (agentMode === 'internal') {
+    console.log(`Agent objective source: ${resolvedPrompt.source}`);
+    console.log(`Agent objective: ${resolvedPrompt.prompt}`);
+    if (merged.backendAgent) {
+      console.log(`Backend agent: ${merged.backendAgent}`);
+    }
+    if (merged.backendModel) {
+      console.log(`Backend model: ${merged.backendModel}`);
+    }
+  } else {
+    console.log(`Agent command: ${merged.agentCommand}`);
+  }
+  console.log(`Benchmark command: ${merged.benchmarkCommand}`);
+  console.log(`Direction: ${direction} (${direction === 'min' ? 'lower is better' : 'higher is better'})`);
+  console.log(`Iterations: ${iterations}`);
+
+  for (let i = 1; i <= iterations; i++) {
+    console.log(`\n--- Iteration ${i}/${iterations} ---`);
+    const beforeCommit = await getGitCommit(cwd);
+
+    const agentStep = getAgentStepCommand(merged, cwd, i, runId, resolvedPrompt.prompt);
+
+    const agentResult = await runCommand(agentStep.command, {
+      cwd,
+      stream: merged.streamAgentOutput === true,
+      env: { AR_ITERATION: String(i), AR_RUN_ID: runId },
+    });
+
+    if (agentResult.code !== 0) {
+      console.log(`Agent step failed with code ${agentResult.code}`);
+      if (merged.stopOnAgentFailure !== false) {
+        await appendRunLog(cwd, runId, {
+          iteration: i,
+          status: 'agent_failed',
+          agentMode: agentStep.agentMode,
+          agentExitCode: agentResult.code,
+          beforeCommit,
+          timestamp: new Date().toISOString(),
+        });
+        break;
+      }
+    }
+
+    const benchmarkResult = await runCommand(merged.benchmarkCommand, { cwd });
+    const benchmarkOutput = `${benchmarkResult.stdout}\n${benchmarkResult.stderr}`;
+    const metric = parseMetric(benchmarkOutput, merged.metricRegex);
+
+    if (benchmarkResult.code !== 0 || metric == null) {
+      console.log('Benchmark failed or metric could not be parsed.');
+      if (benchmarkResult.stdout) console.log(benchmarkResult.stdout.trim());
+      if (benchmarkResult.stderr) console.log(benchmarkResult.stderr.trim());
+
+      if (merged.onRejectCommand) {
+        await runCommand(merged.onRejectCommand, { cwd, stream: true });
+      }
+
+      await appendRunLog(cwd, runId, {
+        iteration: i,
+        status: 'benchmark_failed',
+        benchmarkExitCode: benchmarkResult.code,
+        parsedMetric: metric,
+        beforeCommit,
+        timestamp: new Date().toISOString(),
+      });
+      continue;
+    }
+
+    const improved = isBetter(metric, bestMetric, direction);
+    console.log(`Metric: ${metric}${bestMetric == null ? ' (baseline)' : ` | best: ${bestMetric}`}`);
+
+    if (improved) {
+      bestMetric = metric;
+      bestIteration = i;
+      console.log('Result: improved -> keep');
+
+      if (merged.autoCommit === true && (await hasGitChanges(cwd))) {
+        const commitMessage = merged.commitMessageTemplate
+          ? merged.commitMessageTemplate
+              .replaceAll('{iteration}', String(i))
+              .replaceAll('{metric}', String(metric))
+          : `research: improve metric to ${metric} (iter ${i})`;
+
+        await runCommand('git add -A', { cwd });
+        const commitResult = await runCommand(`git commit -m "${commitMessage.replaceAll('"', '\\"')}"`, {
+          cwd,
+        });
+        if (commitResult.code === 0) {
+          console.log(`Committed: ${commitMessage}`);
+        } else {
+          console.log('Commit skipped (possibly no staged changes).');
+        }
+      }
+
+      if (merged.onKeepCommand) {
+        await runCommand(merged.onKeepCommand, { cwd, stream: true });
+      }
+    } else {
+      console.log('Result: not improved -> reject');
+      if (merged.onRejectCommand) {
+        await runCommand(merged.onRejectCommand, { cwd, stream: true });
+      }
+    }
+
+    await appendRunLog(cwd, runId, {
+      iteration: i,
+      status: improved ? 'keep' : 'reject',
+      agentMode: agentStep.agentMode,
+      metric,
+      bestMetric,
+      beforeCommit,
+      afterCommit: await getGitCommit(cwd),
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  console.log('\n=== Run Summary ===');
+  if (bestMetric == null) {
+    console.log('No valid metric was recorded.');
+  } else {
+    console.log(`Best metric: ${bestMetric}`);
+    console.log(`Best iteration: ${bestIteration}`);
+  }
+
+  console.log(`Run logs: ${CONFIG_DIR}/runs/${runId}.jsonl`);
+}

package/src/shell.js

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+
+export async function runCommand(command, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const env = { ...process.env, ...(options.env || {}) };
+
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      env,
+      shell: true,
+      stdio: options.stream ? 'inherit' : 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (!options.stream) {
+      child.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+
+    child.on('close', (code) => {
+      resolve({
+        code: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}