strom-research 1.0.0

package/dist/runners/claude.js

@@ -0,0 +1,179 @@
+// Claude Code runner. Headless: `claude -p --output-format stream-json
+// --permission-mode dontAsk --settings <tree>/.claude/settings.json` in the
+// tree folder, with the brief on stdin: the tree's permissions decide what is
+// allowed and anything else is denied without asking. The settings are passed
+// explicitly because Claude Code ignores the allow rules of a project's own
+// settings until the user has trusted the folder in an interactive session
+// (found in the first live run: every strom call was refused).
+// Interactive: `claude "<kickoff>"` with the terminal, in the mode of the user's
+// level (agent.permissions): ask — Claude Code's own mode, it asks about what the
+// permissions do not decide; auto — its own review decides and asks only when
+// it is risky; full — --permission-mode bypassPermissions (only the deny rules
+// count), headless or not. Browser tools
+// are on only when a connector fetches through the browser (--chrome), and off
+// otherwise (--no-chrome), whatever Claude Code's own default is.
+import { appendLog, looksLikeLimit, spawnAgent, stopTree } from "./runner.js";
+function describeTool(block) {
+    const input = block.input ?? {};
+    if (block.name === "Bash" && typeof input.command === "string")
+        return `$ ${input.command.split("\n")[0].slice(0, 140)}`;
+    if (typeof input.file_path === "string")
+        return `${block.name} ${input.file_path}`;
+    if (typeof input.url === "string")
+        return `${block.name} ${input.url}`;
+    if (typeof input.query === "string")
+        return `${block.name} "${input.query}"`;
+    return String(block.name ?? "tool");
+}
+/** Command-line arguments for a run (exported for tests). */
+export function claudeArgs(opts) {
+    const level = opts.permissions ?? "auto";
+    const mode = level === "full" ? "bypassPermissions" : !opts.interactive ? "dontAsk" : level === "auto" ? "auto" : undefined;
+    const args = opts.interactive ? [opts.kickoff] : ["-p", "--output-format", "stream-json", "--verbose"];
+    if (mode)
+        args.push("--permission-mode", mode);
+    if (opts.settingsFile)
+        args.push("--settings", opts.settingsFile);
+    if (opts.name)
+        args.push("--name", opts.name);
+    if (opts.model)
+        args.push("--model", opts.model);
+    if (opts.chrome !== undefined)
+        args.push(opts.chrome ? "--chrome" : "--no-chrome");
+    args.push(...(opts.extraArgs ?? []));
+    return args;
+}
+/**
+ * The environment of a headless run. `claude -p` ends when the model ends its
+ * turn, and a command it left in the background dies with it (found in a live
+ * run: `strom read` sent to the background, a wake-up scheduled, the session
+ * over in 32 s and no reader ever read). So nothing goes to the background, no
+ * wake-ups, and one command may take as long as the session.
+ */
+export function headlessEnv(env, timeoutMs) {
+    const long = String(Math.max(timeoutMs ?? 0, 30 * 60_000));
+    return {
+        ...env,
+        CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1",
+        CLAUDE_CODE_DISABLE_CRON: "1",
+        BASH_DEFAULT_TIMEOUT_MS: long,
+        BASH_MAX_TIMEOUT_MS: long,
+    };
+}
+export const claudeRunner = {
+    id: "claude",
+    command: "claude",
+    run(opts) {
+        return new Promise((resolve) => {
+            const child = spawnAgent("claude", claudeArgs(opts), {
+                cwd: opts.cwd,
+                env: opts.interactive ? opts.env : headlessEnv(opts.env, opts.timeoutMs),
+                stdio: opts.interactive ? "inherit" : ["pipe", "pipe", "pipe"],
+                windowsHide: !opts.interactive,
+            });
+            // The brief goes in on stdin: no limit on its length on any platform.
+            if (!opts.interactive)
+                child.stdin?.end(opts.prompt);
+            let timedOut = false;
+            const timer = opts.timeoutMs
+                ? setTimeout(() => {
+                    timedOut = true;
+                    opts.onProgress?.(`time limit reached (${Math.round(opts.timeoutMs / 60000)} min) — stopping the agent`);
+                    stopTree(child);
+                }, opts.timeoutMs)
+                : undefined;
+            opts.signal?.addEventListener("abort", () => stopTree(child), { once: true });
+            const metrics = {};
+            let text = "";
+            let buffer = "";
+            let isError = false;
+            const denied = [];
+            const handle = (line) => {
+                if (!line.trim())
+                    return;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === "assistant") {
+                    const content = (msg.message?.content ?? []);
+                    for (const b of content) {
+                        if (b.type === "tool_use")
+                            opts.onProgress?.(describeTool(b));
+                        else if (b.type === "text" && b.text?.trim())
+                            opts.onProgress?.(b.text.trim().split("\n")[0].slice(0, 160));
+                    }
+                }
+                if (msg.type === "result") {
+                    text = String(msg.result ?? "");
+                    isError = Boolean(msg.is_error);
+                    const u = (msg.usage ?? {});
+                    if (u.input_tokens !== undefined)
+                        metrics.inputTokens = u.input_tokens;
+                    if (u.output_tokens !== undefined)
+                        metrics.outputTokens = u.output_tokens;
+                    if (u.cache_read_input_tokens !== undefined)
+                        metrics.cacheReadTokens = u.cache_read_input_tokens;
+                    if (u.cache_creation_input_tokens !== undefined)
+                        metrics.cacheWriteTokens = u.cache_creation_input_tokens;
+                    if (typeof msg.total_cost_usd === "number")
+                        metrics.costUsd = msg.total_cost_usd;
+                    if (typeof msg.num_turns === "number")
+                        metrics.turns = msg.num_turns;
+                    if (typeof msg.duration_ms === "number")
+                        metrics.durationMs = msg.duration_ms;
+                    for (const d of (msg.permission_denials ?? [])) {
+                        const input = d.tool_input ?? {};
+                        const what = typeof input.command === "string" ? input.command : typeof input.file_path === "string" ? input.file_path : typeof input.url === "string" ? input.url : "";
+                        denied.push(`${d.tool_name ?? "tool"}${what ? `: ${String(what).split("\n")[0].slice(0, 120)}` : ""}`);
+                    }
+                    if (denied.length)
+                        metrics.denied = denied.length;
+                }
+            };
+            child.stdout?.on("data", (d) => {
+                const s = d.toString("utf8");
+                appendLog(opts.logFile, s);
+                buffer += s;
+                let nl;
+                while ((nl = buffer.indexOf("\n")) >= 0) {
+                    handle(buffer.slice(0, nl));
+                    buffer = buffer.slice(nl + 1);
+                }
+            });
+            let stderr = "";
+            child.stderr?.on("data", (d) => {
+                stderr += d.toString("utf8");
+                appendLog(opts.logFile, d.toString("utf8"));
+            });
+            child.on("error", (err) => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve({ exitCode: 127, outcome: "error", text: String(err.message), metrics });
+            });
+            child.on("close", (code) => {
+                if (timer)
+                    clearTimeout(timer);
+                if (buffer)
+                    handle(buffer);
+                const all = `${text}\n${stderr}`;
+                const limit = looksLikeLimit(all);
+                const outcome = opts.signal?.aborted
+                    ? "stopped"
+                    : timedOut
+                        ? "timeout"
+                        : limit.limit
+                            ? "limit"
+                            : /log ?in|authenticat|api key|unauthori[sz]ed/i.test(all) && (code ?? 0) !== 0
+                                ? "auth"
+                                : (code ?? 0) !== 0 || isError
+                                    ? "error"
+                                    : "ok";
+                resolve({ exitCode: code ?? 1, outcome, text: text || stderr.trim(), metrics, ...(limit.resumeAt ? { resumeAt: limit.resumeAt } : {}), ...(denied.length ? { denied } : {}) });
+            });
+        });
+    },
+};

package/dist/runners/codex.js

@@ -0,0 +1,45 @@
+// OpenAI Codex CLI runner. Headless: `codex exec --json` in the tree folder
+// with the brief on stdin. The user's level decides the sandbox: ask and auto
+// work in Codex's sandbox on the tree folder (the shared folder added, the
+// network on — strom fetches), where what the sandbox refuses simply fails —
+// nothing asks, as with Claude Code's dontAsk; full runs without the sandbox.
+// Interactive conversations are started by strom chat (agents/launch.ts).
+import { runJsonLines } from "./jsonl.js";
+/** Command-line arguments of a headless run (exported for tests). */
+export function codexArgs(opts) {
+    const sandbox = opts.permissions === "full"
+        ? ["--dangerously-bypass-approvals-and-sandbox"]
+        : ["--sandbox", "workspace-write", "-c", "sandbox_workspace_write.network_access=true", ...(opts.shared ? ["--add-dir", opts.shared] : [])];
+    return ["exec", "--json", "--skip-git-repo-check", ...sandbox, ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), "-"];
+}
+export const codexRunner = {
+    id: "codex",
+    command: "codex",
+    run(opts) {
+        return runJsonLines("codex", codexArgs(opts), opts.env, opts, (msg, heard) => {
+            const item = msg.item;
+            if (msg.type === "item.started" && item?.type === "command_execution" && item.command)
+                opts.onProgress?.(`$ ${item.command.replace(/^\S*sh -lc '(.*)'$/s, "$1").split("\n")[0].slice(0, 140)}`);
+            if (msg.type === "item.completed" && item?.type === "agent_message" && item.text) {
+                heard.text = item.text;
+                opts.onProgress?.(item.text.trim().split("\n")[0].slice(0, 160));
+            }
+            // The sandbox refused a command (a write outside the tree, the network off): counted like a denial.
+            if (msg.type === "item.completed" && item?.type === "command_execution" && item.exit_code !== 0 && /operation not permitted|sandbox|read-only file system/i.test(item.aggregated_output ?? ""))
+                heard.denied.push(`Bash: ${String(item.command ?? "").slice(0, 120)}`);
+            if (msg.type === "turn.completed") {
+                const u = (msg.usage ?? {});
+                const m = heard.metrics;
+                m.inputTokens = (m.inputTokens ?? 0) + (u.input_tokens ?? 0);
+                m.outputTokens = (m.outputTokens ?? 0) + (u.output_tokens ?? 0);
+                m.cacheReadTokens = (m.cacheReadTokens ?? 0) + (u.cached_input_tokens ?? 0);
+                m.turns = (m.turns ?? 0) + 1;
+            }
+            if (msg.type === "turn.failed" || msg.type === "error") {
+                heard.isError = true;
+                const e = msg.error;
+                heard.text = String(e?.message ?? msg.message ?? heard.text);
+            }
+        });
+    },
+};

package/dist/runners/index.js

@@ -0,0 +1,13 @@
+import { claudeRunner } from "./claude.js";
+import { codexRunner } from "./codex.js";
+import { antigravityRunner } from "./antigravity.js";
+import { opencodeRunner } from "./opencode.js";
+import { scriptRunner } from "./script.js";
+export const RUNNERS = {
+    claude: claudeRunner,
+    codex: codexRunner,
+    antigravity: antigravityRunner,
+    opencode: opencodeRunner,
+    script: scriptRunner,
+};
+export const DEFAULT_RUNNER = "claude";

package/dist/runners/jsonl.js

@@ -0,0 +1,86 @@
+// A headless agent that reports as JSON lines (Codex `exec --json`, Antigravity
+// `--output-format stream-json`): the brief on stdin, one event per line on
+// stdout, a time limit, Ctrl-C, the subscription limit and a missing login
+// recognised — the same for every such agent; each runner only reads its own
+// events.
+import { appendLog, looksLikeLimit, spawnAgent, stopTree } from "./runner.js";
+export function runJsonLines(command, args, env, opts, onEvent) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const child = spawnAgent(command, args, { cwd: opts.cwd, env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        child.stdin?.end(opts.prompt);
+        let timedOut = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                opts.onProgress?.(`time limit reached (${Math.round(opts.timeoutMs / 60000)} min) — stopping the agent`);
+                stopTree(child);
+            }, opts.timeoutMs)
+            : undefined;
+        opts.signal?.addEventListener("abort", () => stopTree(child), { once: true });
+        const heard = { metrics: {}, text: "", isError: false, denied: [] };
+        let buffer = "";
+        const handle = (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return; // a line of plain text among the events
+            }
+            onEvent(msg, heard);
+        };
+        child.stdout?.on("data", (d) => {
+            const s = d.toString("utf8");
+            appendLog(opts.logFile, s);
+            buffer += s;
+            let nl;
+            while ((nl = buffer.indexOf("\n")) >= 0) {
+                handle(buffer.slice(0, nl));
+                buffer = buffer.slice(nl + 1);
+            }
+        });
+        let stderr = "";
+        child.stderr?.on("data", (d) => {
+            stderr += d.toString("utf8");
+            appendLog(opts.logFile, d.toString("utf8"));
+        });
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ exitCode: 127, outcome: "error", text: String(err.message), metrics: heard.metrics });
+        });
+        child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            if (buffer)
+                handle(buffer);
+            heard.metrics.durationMs ??= Date.now() - started;
+            if (heard.denied.length)
+                heard.metrics.denied = heard.denied.length;
+            const all = `${heard.text}\n${stderr}`;
+            const limit = looksLikeLimit(all);
+            const outcome = opts.signal?.aborted
+                ? "stopped"
+                : timedOut
+                    ? "timeout"
+                    : limit.limit
+                        ? "limit"
+                        : /log ?in|authenticat|api[ _]?key|unauthori[sz]ed|GEMINI_API_KEY/i.test(all) && ((code ?? 0) !== 0 || heard.isError)
+                            ? "auth"
+                            : (code ?? 0) !== 0 || heard.isError
+                                ? "error"
+                                : "ok";
+            resolve({
+                exitCode: code ?? 1,
+                outcome,
+                text: heard.text || stderr.trim(),
+                metrics: heard.metrics,
+                ...(limit.resumeAt ? { resumeAt: limit.resumeAt } : {}),
+                ...(heard.denied.length ? { denied: heard.denied } : {}),
+            });
+        });
+    });
+}

package/dist/runners/opencode.js

@@ -0,0 +1,50 @@
+// OpenCode runner. Headless: `opencode run --format json "<kickoff>"` in the tree
+// folder with the brief on stdin (it joins what is piped in with the message).
+// The tree's rules are its project config (opencode.json: strom allowed, the
+// evidence and git denied); what they would ask about is refused in a run
+// nobody watches — under ask and auto that is all; full adds --auto
+// (everything the rules do not deny). Events are JSON lines: text, tool_use,
+// step_start, step_finish (tokens and cost of a step), error.
+import { runJsonLines } from "./jsonl.js";
+/** Command-line arguments of a headless run (exported for tests). */
+export function opencodeArgs(opts) {
+    return ["run", "--format", "json", ...(opts.permissions === "full" ? ["--auto"] : []), ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), opts.kickoff];
+}
+export const opencodeRunner = {
+    id: "opencode",
+    command: "opencode",
+    run(opts) {
+        const args = opencodeArgs({ ...opts, kickoff: "Your brief is above. Work only through `strom` in this folder, as it says." });
+        const tokens = { input: 0, output: 0, cacheRead: 0 };
+        return runJsonLines("opencode", args, opts.env, opts, (msg, heard) => {
+            const part = (msg.part ?? {});
+            if (msg.type === "tool_use") {
+                const state = (part.state ?? {});
+                const input = state.input ?? {};
+                const what = typeof input.command === "string" ? `$ ${input.command}` : typeof input.filePath === "string" ? `${String(part.tool)} ${input.filePath}` : String(part.tool ?? "tool");
+                opts.onProgress?.(what.split("\n")[0].slice(0, 140));
+                if (state.status === "error" && /reject|denied|not allowed|permission/i.test(state.error ?? ""))
+                    heard.denied.push(`${String(part.tool)}: ${what.slice(0, 120)}`);
+            }
+            if (msg.type === "text" && typeof part.text === "string" && part.text.trim())
+                heard.text = part.text;
+            if (msg.type === "step_finish") {
+                // One step of the conversation; the run's use is their sum.
+                const t = (part.tokens ?? {});
+                tokens.input += t.input ?? 0;
+                tokens.output += (t.output ?? 0) + (t.reasoning ?? 0);
+                tokens.cacheRead += t.cache?.read ?? 0;
+                const m = heard.metrics;
+                m.inputTokens = tokens.input;
+                m.outputTokens = tokens.output;
+                m.cacheReadTokens = tokens.cacheRead;
+                m.turns = (m.turns ?? 0) + 1;
+            }
+            if (msg.type === "error") {
+                heard.isError = true;
+                const e = (msg.error ?? {});
+                heard.text = e.data?.message ?? e.name ?? "error";
+            }
+        });
+    },
+};

package/dist/runners/runner.js

@@ -0,0 +1,63 @@
+// Runners start an AI agent CLI on a prompt in a tree folder and report back.
+// Adding an agent = one file implementing Runner.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { findAgent } from "../core/which.js";
+/** Recognise a subscription/usage limit in an agent's message. */
+export function looksLikeLimit(text) {
+    if (!/(usage|rate|session|weekly|5-hour|daily)\s+limit|limit (reached|exceeded)|quota|too many requests|out of (credits|usage)/i.test(text))
+        return { limit: false };
+    const at = /resets?\s+(?:at\s+)?([^.\n]+)/i.exec(text)?.[1]?.trim();
+    return at ? { limit: true, resumeAt: at } : { limit: true };
+}
+export function appendLog(file, chunk) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, chunk);
+}
+/**
+ * The environment with `dir` first on PATH. On Windows the variable is
+ * usually spelled "Path"; adding a second "PATH" beside it leaves the child
+ * with two, and which one wins is undefined — so the existing key is reused.
+ */
+export function prependPath(env, dir) {
+    const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (k.toUpperCase() !== "PATH" || k === key)
+            out[k] = v;
+    out[key] = `${dir}${path.delimiter}${env[key] ?? ""}`;
+    return out;
+}
+/** Quote one argument for cmd.exe (only used for .cmd/.bat launchers on Windows). */
+function cmdQuote(arg) {
+    if (/^[\w.\-/:=@]+$/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+/**
+ * Start an agent CLI found on PATH. npm installs agents on Windows as .cmd
+ * launchers, which Node can only start through cmd.exe.
+ */
+export function spawnAgent(command, args, opts) {
+    const found = findAgent(command, opts.env) ?? command;
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(found)) {
+        const line = [cmdQuote(found), ...args.map(cmdQuote)].join(" ");
+        return spawn(opts.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `"${line}"`], { ...opts, windowsVerbatimArguments: true, env: opts.env });
+    }
+    return spawn(found, args, { ...opts, env: opts.env });
+}
+/** Stop a child and everything it started (Windows: the whole process tree). */
+export function stopTree(child) {
+    if (child.exitCode !== null || child.pid === undefined)
+        return;
+    if (process.platform === "win32")
+        spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    else {
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+        }, 5000).unref();
+    }
+}

package/dist/runners/script.js

@@ -0,0 +1,58 @@
+// A runner that executes a local script instead of an AI agent — for tests
+// and for scripted, repeatable runs. STROM_RUNNER_SCRIPT names the script
+// (run with node); it gets the same environment an agent would, and the
+// prompt both on stdin (like a headless agent) and in STROM_PROMPT.
+import { spawn } from "node:child_process";
+import { appendLog, looksLikeLimit, stopTree } from "./runner.js";
+export const scriptRunner = {
+    id: "script",
+    command: process.execPath,
+    run(opts) {
+        const script = opts.env.STROM_RUNNER_SCRIPT;
+        return new Promise((resolve) => {
+            if (!script)
+                return resolve({ exitCode: 2, outcome: "error", text: "STROM_RUNNER_SCRIPT is not set", metrics: {} });
+            const child = spawn(process.execPath, [script, ...(opts.extraArgs ?? [])], {
+                cwd: opts.cwd,
+                env: { ...opts.env, STROM_PROMPT: opts.prompt },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            child.stdin.end(opts.prompt);
+            let timedOut = false;
+            const timer = opts.timeoutMs
+                ? setTimeout(() => {
+                    timedOut = true;
+                    stopTree(child);
+                }, opts.timeoutMs)
+                : undefined;
+            opts.signal?.addEventListener("abort", () => stopTree(child), { once: true });
+            let out = "";
+            const denied = [];
+            const on = (d) => {
+                for (const l of d.toString("utf8").split("\n"))
+                    if (l.startsWith("denied: "))
+                        denied.push(l.slice(8).trim());
+                out += d.toString("utf8");
+                appendLog(opts.logFile, d.toString("utf8"));
+                for (const l of d.toString("utf8").split("\n"))
+                    if (l.trim())
+                        opts.onProgress?.(l.trim().slice(0, 160));
+            };
+            child.stdout.on("data", on);
+            child.stderr.on("data", on);
+            child.on("close", (code) => {
+                if (timer)
+                    clearTimeout(timer);
+                const limit = looksLikeLimit(out);
+                resolve({
+                    exitCode: code ?? 1,
+                    outcome: opts.signal?.aborted ? "stopped" : timedOut ? "timeout" : limit.limit ? "limit" : code === 0 ? "ok" : "error",
+                    text: out.trim().split("\n").slice(-5).join("\n"),
+                    metrics: { turns: 1, ...(denied.length ? { denied: denied.length } : {}) },
+                    ...(limit.resumeAt ? { resumeAt: limit.resumeAt } : {}),
+                    ...(denied.length ? { denied } : {}),
+                });
+            });
+        });
+    },
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "strom-research",
+  "version": "1.0.0",
+  "description": "Genealogical research toolkit for AI coding agents",
+  "type": "module",
+  "bin": {
+    "strom": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "strom": "node src/cli.ts",
+    "test": "node --test --test-reporter=dot \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "release": "node scripts/build-release.ts"
+  },
+  "keywords": [
+    "genealogy",
+    "family-tree",
+    "gedcom",
+    "research",
+    "cli"
+  ],
+  "author": "Milan Víšek",
+  "homepage": "https://github.com/ACiDekCZ/strom-research#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ACiDekCZ/strom-research.git"
+  },
+  "bugs": "https://github.com/ACiDekCZ/strom-research/issues",
+  "license": "MPL-2.0",
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^7.0.2"
+  }
+}