strom-research 1.1.1 → 1.3.0

package/dist/core/browser.js

@@ -41,6 +41,56 @@ export const CHROME_ALLOW = [
 export const CHROME_DENY = ["file_upload", "upload_image", "shortcuts_execute", "gif_creator", "browser_batch"].map((t) => `mcp__claude-in-chrome__${t}`);
 /** The permission rule of Claude in Chrome for one site. */
 export const chromeDomain = (host) => `ClaudeInChromeDomain(${host.replace(/^\*\./, "").toLowerCase()})`;
+/** Claude in Chrome in the Chrome Web Store: the extension Claude Code's browser tools work through. */
+export const CLAUDE_IN_CHROME_ID = "fcoeoabgfenejglbffodgkkbkcdhcgfn";
+export const CLAUDE_IN_CHROME_URL = `https://chromewebstore.google.com/detail/${CLAUDE_IN_CHROME_ID}`;
+/** The folders of the browsers' profiles (Chrome, Edge, Brave take extensions from the Chrome Web Store). */
+function browserDataDirs(env, platform) {
+    const home = userHome(env);
+    if (platform === "darwin") {
+        const base = path.join(home, "Library", "Application Support");
+        return [
+            { browser: "Chrome", dir: path.join(base, "Google", "Chrome") },
+            { browser: "Edge", dir: path.join(base, "Microsoft Edge") },
+            { browser: "Brave", dir: path.join(base, "BraveSoftware", "Brave-Browser") },
+        ];
+    }
+    if (platform === "win32") {
+        const base = env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return [
+            { browser: "Chrome", dir: path.join(base, "Google", "Chrome", "User Data") },
+            { browser: "Edge", dir: path.join(base, "Microsoft", "Edge", "User Data") },
+            { browser: "Brave", dir: path.join(base, "BraveSoftware", "Brave-Browser", "User Data") },
+        ];
+    }
+    const base = env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+    return [
+        { browser: "Chrome", dir: path.join(base, "google-chrome") },
+        { browser: "Edge", dir: path.join(base, "microsoft-edge") },
+        { browser: "Brave", dir: path.join(base, "BraveSoftware", "Brave-Browser") },
+    ];
+}
+/**
+ * Is Claude in Chrome installed — in which browsers? Only the extension's folder in the profiles is looked for (its
+ * name), nothing else of the browser is read. Whether it is signed in and connected strom cannot see.
+ */
+export function claudeInChrome(env, platform = process.platform) {
+    const browsers = [];
+    const extension = [];
+    for (const { browser, dir } of browserDataDirs(env, platform)) {
+        let profiles;
+        try {
+            profiles = fs.readdirSync(dir).filter((n) => n === "Default" || /^Profile \d+$/u.test(n));
+        }
+        catch {
+            continue;
+        }
+        browsers.push(browser);
+        if (profiles.some((p) => fs.existsSync(path.join(dir, p, "Extensions", CLAUDE_IN_CHROME_ID))))
+            extension.push(browser);
+    }
+    return { browsers, extension };
+}
 /** The folder a browser saves downloads into by default: ~/Downloads, or what the desktop names it (Linux). */
 export function downloadsDir(env, platform = process.platform) {
     const home = userHome(env);

package/dist/core/clock.js

@@ -0,0 +1,55 @@
+// The session's time. `strom run` stops an agent at its time limit (run.minutes),
+// and what the agent had only in its context is lost then (found in a live run:
+// 25 minutes of reading a census film, nothing written down, all gone). So the
+// agent is told when its session is stopped (STROM_DEADLINE, set by the run; the
+// brief says it), near the end every strom command it runs reminds it, and at
+// the limit an agent that can be resumed gets a few minutes more to write down
+// what it found and close the session (runners: wrapUp).
+/** From how long before the end strom's output reminds the agent (a short session: its last quarter). */
+export const REMIND_MS = 10 * 60_000;
+/** From how long before the end the reminder says to write down and close (a short session: its last eighth). */
+export const CLOSE_MS = 3 * 60_000;
+/** The time an agent stopped at its limit gets to write down what it found. */
+export const WRAP_UP_MS = 5 * 60_000;
+/** When this session is stopped (ms since the epoch), if a run set a limit. */
+export function deadlineOf(env) {
+    const t = Date.parse(env.STROM_DEADLINE ?? "");
+    return Number.isNaN(t) ? undefined : t;
+}
+/** The session's whole time limit (STROM_MINUTES), if the run said it. */
+function limitOf(env) {
+    const m = Number(env.STROM_MINUTES);
+    return m > 0 ? m * 60_000 : undefined;
+}
+/** A time of day as the agent reads it in its brief and in the reminders. */
+export function clockTime(t) {
+    return new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });
+}
+/**
+ * The line strom adds to a command's output near the end of the session (none before): first that the time is
+ * getting short (go on, writing down), in the last minutes to write down and close, then that it is up. A short
+ * session is reminded in proportion — a reminder from its first minute would only make the agent give up.
+ */
+export function clockLine(env, now = Date.now()) {
+    const end = deadlineOf(env);
+    if (end === undefined)
+        return undefined;
+    const limit = limitOf(env);
+    const remind = limit ? Math.min(REMIND_MS, limit / 4) : REMIND_MS;
+    const close = limit ? Math.min(CLOSE_MS, limit / 8) : CLOSE_MS;
+    const left = end - now;
+    if (left > remind)
+        return undefined;
+    const min = Math.max(1, Math.ceil(left / 60_000));
+    if (left <= 0)
+        return '⏳ this session\'s time is up: record what you found and close it now: strom session close --continue --summary "…" --next "exactly where you stopped"';
+    if (left <= close)
+        return `⏳ ${min} min left: this session is stopped at ${clockTime(end)}. Record what you have found now (facts, sources, the images searched), then close: strom session close --summary "…" --next "…"`;
+    return `⏳ ${min} min left: this session is stopped at ${clockTime(end)}. Go on, but write each find down as you have it and start nothing you cannot finish by then.`;
+}
+/** What the brief says of the session's time: when, and not to hurry — strom says when it is getting short. */
+export function briefClock(end, now = Date.now()) {
+    return (`Time: this session is stopped at ${clockTime(end)} (it is ${clockTime(now)} now). Do not hurry and do not stop early: strom's output tells you ` +
+        "when the time is getting short; until then work on the task as usual. Write each find and each stretch of images searched into strom the " +
+        "moment you have it: what is only in your context is lost when the session ends.");
+}

package/dist/core/config.js

@@ -39,6 +39,8 @@ export const SETTINGS = [
     })),
     { key: "brief.budget", env: "STROM_BRIEF_BUDGET", tree: true, kind: "number", description: `size of the brief in tokens (default ${DEFAULT_BUDGET})` },
     { key: "run.minutes", env: "STROM_RUN_MINUTES", tree: true, kind: "number", description: `time limit of one \`strom run\` session (default ${DEFAULT_RUN_MINUTES})` },
+    // Read from the config file only, changed by the user alone: the gate decides what working alone spends.
+    { key: "run.gate", env: "", tree: false, kind: "plugin", description: "a condition on the agent working alone: the gate (plugins/gates/<name>) strom asks before each session of strom run — go on, wait or stop; its name, then what it is given (strom gate list; e.g. claude-usage 10: the Claude subscription's daily ration, 10 points in hand) — only you set it" },
     { key: "queue.strategy", env: "STROM_QUEUE_STRATEGY", tree: true, kind: "choice", choices: STRATEGIES, description: "order of the task queue: balanced (default — nearest ancestors first, spread over the lines, nothing taken forever), depth (stay on one line), priority (strict priority)" },
     { key: "gedcom.for", env: "STROM_GEDCOM_FOR", tree: true, kind: "choice", choices: ["both", "standard", "strom"], description: "GEDCOM files written: both (default), standard (any program), strom (the Strom app)" },
     { key: "stories", env: "STROM_STORIES", tree: true, kind: "choice", choices: ["yes", "no"], description: "stories of the ancestors for the family, written from the facts: yes (default — strom proposes one once a person's life is told by records), no — the user is told when the research starts and may say no" },
@@ -52,6 +54,7 @@ export const SETTINGS = [
     // Read from the config file only — no variable, no flag, no tree: nothing an agent can set.
     { key: "agent.permissions", env: "", tree: false, kind: "choice", choices: PERMISSION_LEVELS, description: "what the agent may do without asking you: ask (what the tree allows; anything else it asks), auto (default: what the tree allows; anything else the agent's own review decides, asking only when risky), full (everything but what the tree denies) — only you raise it" },
     { key: "agent.where", env: "STROM_AGENT_WHERE", tree: false, kind: "choice", choices: ["app", "terminal"], description: "where you talk with the agent: app (its desktop app — the easiest), terminal (its CLI) — unset: the app when it is installed" },
+    { key: "agent.remote", env: "", tree: false, kind: "choice", choices: ["on", "off"], description: "the Claude Code sessions strom starts (strom run, strom chat in the terminal) with Remote Control: on — follow and steer them from claude.ai or the Claude app on your phone; off (default) — only you turn it on" },
     { key: "updates", env: "STROM_UPDATES", tree: false, kind: "choice", choices: ["check", "off"], description: "look for new versions of strom: check (default — at most once a day, one small file from the project's releases; strom says so, strom update installs it) or off" },
     { key: "strom.app", env: "", tree: false, kind: "choice", choices: ["yes", "no"], description: "you use the Strom app: yes (strom says which file to import into it), no (strom never mentions it) — unset: strom notices it itself" },
     { key: "strom.app.url", env: "STROM_APP_URL", tree: false, kind: "url", description: "another copy of the Strom app to open instead of https://stromapp.info/run/ — its beta (https://beta.stromapp.info/run/), its development (http://127.0.0.1:8080/); installed from a browser, that copy opens as its own app" },
@@ -67,12 +70,14 @@ const FIELDS = {
     "browser.downloads": "browserDownloads",
     "agent.permissions": "agentPermissions",
     "agent.where": "agentWhere",
+    "agent.remote": "agentRemote",
     "strom.app": "stromApp",
     "strom.app.url": "stromAppUrl",
     "main.person": "mainPerson",
     "excerpts.quality": "excerptsQuality",
     "excerpts.for": "excerptsFor",
     "excerpts.mb": "excerptsMb",
+    "run.gate": "runGate",
 };
 /** Environment variables that are not settings but steer strom. */
 export const OTHER_ENV = [
@@ -128,6 +133,11 @@ export function checkValue(def, raw, resolvePath) {
                 throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: def.choices?.join(", ") });
             return c;
         }
+        case "plugin":
+            // its name, then what it is given: "claude-usage 10"
+            if (!/^[a-z0-9][a-z0-9-]*(\s+\S+)*$/.test(v))
+                throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: 'a plugin\'s name (lowercase letters, digits and dashes), then what it is given, e.g. "claude-usage 10"' });
+            return v.split(/\s+/).join(" ");
         case "person":
             if (!/^[Pp]\d{4,}$/.test(v))
                 throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: "a person's ID, e.g. P0009 (strom find <name>)" });
@@ -326,12 +336,20 @@ export class Settings {
     downloads() {
         return String(this.resolve("browser.downloads")?.value ?? downloadsDir(this.env));
     }
+    /** Claude Code sessions strom starts with Remote Control (agent.remote: on). */
+    agentRemote() {
+        return this.resolve("agent.remote")?.value === "on";
+    }
     /** Where the user wants to talk with the agent, if they said (env, else the config); see whereToTalk. */
     agentWhere() {
         const r = this.resolve("agent.where");
         return r ? String(r.value) : undefined;
     }
     /** What the agent may do without asking — from the config file alone, which only the user raises. */
+    /** The gate of working alone, if the user set one (the config file only). */
+    runGate() {
+        return this.config.runGate || undefined;
+    }
     agentPermissions() {
         const v = this.config.agentPermissions ?? "auto";
         return PERMISSION_ALIASES[v] ?? (PERMISSION_LEVELS.includes(v) ? v : "auto");

package/dist/core/gate.js

@@ -0,0 +1,175 @@
+// Gates: a condition the user sets on working alone. Before each session of
+// `strom run` (--loop runs on for as long as there is work) strom asks the
+// gate the user chose (setting run.gate) whether to go on, wait or stop — the
+// subscription's capacity, a budget, the night's tariff: whatever the gate's
+// program decides, strom holds only the interface.
+//
+// A gate is a folder in the plugins folder, <shared>/plugins/gates/<name>/,
+// with gate.json ({"interface": 1, "command": [...]}) and its program; the
+// user may give it arguments after its name (run.gate "claude-usage 10"). The
+// interface (assets/plugins/gates/README.md, copied next to the gates): the
+// program's exit status says it — 0 go on, 1 wait, 2 stop — and one line of
+// JSON on stdout may add why ("reason") and how long to wait ("wait" seconds
+// or "until" a time). Anything else (a crash, no answer in time) stops the
+// run: working alone never spends blind.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { StromError, UsageError } from "./errors.js";
+import { NAME_RE, pluginsDir } from "./connector.js";
+import { readAsset } from "./assets.js";
+export const GATE_INTERFACE = 1;
+const MANIFEST = "gate.json";
+/** How long a gate may think (it may ask a service). */
+const DEFAULT_TIMEOUT_S = 120;
+/** A gate that says wait without saying how long is asked again after this. */
+export const DEFAULT_WAIT_MS = 15 * 60_000;
+/** Never ask again sooner than this (a gate answering "wait 0" must not spin). */
+const MIN_WAIT_MS = 60_000;
+export function gatesDir(shared) {
+    return path.join(pluginsDir(shared), "gates");
+}
+/** The gates folder with strom's own files: the interface and the gates strom ships (refreshed). */
+export function ensureGatesDir(shared) {
+    const dir = gatesDir(shared);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const own = [[path.join(dir, "README.md"), readAsset("plugins", "gates", "README.md")]];
+        for (const name of SHIPPED)
+            for (const f of ["gate.json", "gate.ts"])
+                own.push([path.join(dir, name, f), readAsset("plugins", "gates", name, f)]);
+        for (const [file, text] of own) {
+            if (text === undefined)
+                continue;
+            let old;
+            try {
+                old = fs.readFileSync(file, "utf8");
+            }
+            catch {
+                old = undefined;
+            }
+            if (old === text)
+                continue;
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, text);
+        }
+    }
+    catch (err) {
+        // a folder strom may not write here (an agent's sandbox): the gates there still run
+        if (!["EACCES", "EPERM", "EROFS"].includes(err?.code ?? ""))
+            throw err;
+    }
+    return dir;
+}
+/** Gates strom ships: ready in the gates folder, used only when the user sets run.gate. */
+export const SHIPPED = ["claude-usage"];
+export function listGates(shared) {
+    const dir = gatesDir(shared);
+    let names = [];
+    try {
+        names = fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && NAME_RE.test(d.name)).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.sort()) {
+        try {
+            out.push(loadGate(shared, name));
+        }
+        catch {
+            // not a gate (yet): no gate.json, or one strom cannot read — `strom gate test <name>` says why
+        }
+    }
+    return out;
+}
+/** A gate as the user names it: its name, then what it is given ("claude-usage 10"). */
+export function loadGate(shared, spec) {
+    const [name = "", ...args] = spec.trim().split(/\s+/);
+    if (!NAME_RE.test(name))
+        throw new UsageError(`invalid gate name "${name}"`, { hint: "lowercase letters, digits and dashes, e.g. claude-usage" });
+    const dir = path.join(gatesDir(shared), name);
+    const file = path.join(dir, MANIFEST);
+    if (!fs.existsSync(file))
+        throw new StromError(`no gate "${name}" (no ${file})`, { hint: `the gates here: strom gate list — a gate is a folder in ${gatesDir(shared)} with ${MANIFEST}` });
+    let m;
+    try {
+        m = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new StromError(`gate "${name}": ${MANIFEST} is not valid JSON (${err.message})`);
+    }
+    if (m.interface !== GATE_INTERFACE)
+        throw new StromError(`gate "${name}" is for interface ${m.interface}, this strom knows ${GATE_INTERFACE}`, { hint: m.interface > GATE_INTERFACE ? "update strom: strom update" : `see ${path.join(gatesDir(shared), "README.md")}` });
+    if (!Array.isArray(m.command) || !m.command.length || !m.command.every((c) => typeof c === "string" && c))
+        throw new StromError(`gate "${name}": "command" must be a list of strings, e.g. ["node", "gate.ts"]`);
+    return { name, dir, manifest: m, args };
+}
+/** Ask the gate once. Never throws: a gate that fails answers "error". */
+export function askGate(gate, env, facts) {
+    const [cmd, ...args] = gate.manifest.command;
+    const program = cmd === "node" ? process.execPath : cmd;
+    const timeout = (gate.manifest.timeout ?? DEFAULT_TIMEOUT_S) * 1000;
+    const r = spawnSync(program, [...args, ...gate.args], {
+        cwd: gate.dir,
+        encoding: "utf8",
+        timeout,
+        windowsHide: true,
+        env: {
+            ...env,
+            STROM_GATE: gate.name,
+            STROM_TREE: facts.tree,
+            STROM_LANG: facts.lang,
+            STROM_AGENT: facts.agent,
+            STROM_MODEL: facts.model ?? "",
+            STROM_SESSIONS: String(facts.sessions),
+            STROM_COST_USD: facts.costUsd.toFixed(2),
+            STROM_NEXT_TASK: facts.nextTask ?? "",
+        },
+    });
+    if (r.error) {
+        const timedOut = r.error.code === "ETIMEDOUT";
+        return { verdict: "error", reason: timedOut ? `no answer within ${timeout / 1000} s` : r.error.message };
+    }
+    const said = parseSaid(r.stdout ?? "");
+    const reason = said.reason ?? (r.status !== 0 && r.status !== 1 && r.status !== 2 ? lastLine(r.stderr ?? "") : undefined);
+    switch (r.status) {
+        case 0:
+            return { verdict: "go", ...(reason ? { reason } : {}) };
+        case 1:
+            return { verdict: "wait", ...(reason ? { reason } : {}), waitMs: Math.max(MIN_WAIT_MS, said.waitMs ?? DEFAULT_WAIT_MS) };
+        case 2:
+            return { verdict: "stop", ...(reason ? { reason } : {}) };
+        default:
+            return { verdict: "error", reason: reason ?? (r.signal ? `ended by ${r.signal}` : `exit status ${r.status}`) };
+    }
+}
+/** The last line of JSON the gate printed: {"reason", "wait" (seconds) | "until" (a time)}; plain text is the reason. */
+function parseSaid(stdout) {
+    const line = lastLine(stdout);
+    if (!line)
+        return {};
+    if (!line.startsWith("{"))
+        return { reason: line.slice(0, 300) };
+    try {
+        const j = JSON.parse(line);
+        const out = {};
+        if (typeof j.reason === "string" && j.reason.trim())
+            out.reason = j.reason.trim().slice(0, 300);
+        if (typeof j.wait === "number" && Number.isFinite(j.wait) && j.wait >= 0)
+            out.waitMs = j.wait * 1000;
+        else if (typeof j.until === "string" && !Number.isNaN(Date.parse(j.until)))
+            out.waitMs = Date.parse(j.until) - Date.now();
+        return out;
+    }
+    catch {
+        return { reason: line.slice(0, 300) };
+    }
+}
+function lastLine(s) {
+    return s
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .pop();
+}

package/dist/core/hooks.js

@@ -0,0 +1,210 @@
+// Hooks: the user's programs told of what was saved into a research. After
+// every commit of a research, strom starts each hook the user turned on
+// (`strom hook on <name>`) in the background — never waiting for it, never
+// failing because of it — with the operations that commit saved: a person
+// added, a fact, a task done, a session closed… A hook filters them
+// (`events` in hook.json, or itself), may read more through strom (`strom
+// person card P0002`) and does with it what the user wants: a message to
+// their phone, a log, a backup.
+//
+// A hook is a folder in the plugins folder, <shared>/plugins/hooks/<name>/,
+// with hook.json ({"interface": 1, "command": [...], "events": [...]}) and its
+// program (interface: assets/plugins/hooks/README.md, copied next to the
+// hooks). The event comes as one JSON document on the program's stdin; what it
+// prints goes to hook.log in its folder. A hook runs only when the user turned
+// it on — a folder an agent put there does nothing by itself.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { StromError, UsageError } from "./errors.js";
+import { NAME_RE, pluginsDir } from "./connector.js";
+import { readAsset } from "./assets.js";
+export const HOOK_INTERFACE = 1;
+const MANIFEST = "hook.json";
+/** How long `strom hook test` waits for a hook. */
+const DEFAULT_TIMEOUT_S = 60;
+/** Event files older than this are cleared away (a hook reads its own at once). */
+const KEEP_MS = 24 * 3600_000;
+/** The hook's output, appended; cut to its last part when it grows past this. */
+const LOG_MAX = 1024 * 1024;
+export function hooksDir(shared) {
+    return path.join(pluginsDir(shared), "hooks");
+}
+/** The hooks folder with its interface (refreshed). */
+export function ensureHooksDir(shared) {
+    const dir = hooksDir(shared);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const text = readAsset("plugins", "hooks", "README.md");
+        const file = path.join(dir, "README.md");
+        let old;
+        try {
+            old = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            old = undefined;
+        }
+        if (text !== undefined && old !== text)
+            fs.writeFileSync(file, text);
+    }
+    catch (err) {
+        if (!["EACCES", "EPERM", "EROFS"].includes(err?.code ?? ""))
+            throw err;
+    }
+    return dir;
+}
+export function listHooks(shared) {
+    let names = [];
+    try {
+        names = fs
+            .readdirSync(hooksDir(shared), { withFileTypes: true })
+            .filter((d) => d.isDirectory() && NAME_RE.test(d.name))
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.sort()) {
+        try {
+            out.push(loadHook(shared, name));
+        }
+        catch {
+            // not a hook (yet): `strom hook test <name>` says why
+        }
+    }
+    return out;
+}
+export function loadHook(shared, name) {
+    if (!NAME_RE.test(name))
+        throw new UsageError(`invalid hook name "${name}"`, { hint: "lowercase letters, digits and dashes, e.g. telegram" });
+    const dir = path.join(hooksDir(shared), name);
+    const file = path.join(dir, MANIFEST);
+    if (!fs.existsSync(file))
+        throw new StromError(`no hook "${name}" (no ${file})`, { hint: `the hooks here: strom hook list — a hook is a folder in ${hooksDir(shared)} with ${MANIFEST}` });
+    let m;
+    try {
+        m = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new StromError(`hook "${name}": ${MANIFEST} is not valid JSON (${err.message})`);
+    }
+    if (m.interface !== HOOK_INTERFACE)
+        throw new StromError(`hook "${name}" is for interface ${m.interface}, this strom knows ${HOOK_INTERFACE}`, {
+            hint: m.interface > HOOK_INTERFACE ? "update strom: strom update" : `see ${path.join(hooksDir(shared), "README.md")}`,
+        });
+    if (!Array.isArray(m.command) || !m.command.length || !m.command.every((c) => typeof c === "string" && c))
+        throw new StromError(`hook "${name}": "command" must be a list of strings, e.g. ["node", "hook.ts"]`);
+    if (m.events !== undefined && (!Array.isArray(m.events) || !m.events.every((e) => typeof e === "string" && e)))
+        throw new StromError(`hook "${name}": "events" must be a list like ["person.add", "session.*"]`);
+    return { name, dir, manifest: m };
+}
+/** Does the hook want this operation? "*" all, "person.*" a kind, "person.add" one. */
+export function wants(m, op) {
+    return (m.events ?? ["*"]).some((p) => p === "*" || p === op || (p.endsWith(".*") && op.startsWith(p.slice(0, -1))));
+}
+/** The operations of a commit the hook wants, or none. */
+export function forHook(hook, events) {
+    return events.filter((e) => wants(hook.manifest, e.op));
+}
+function program(hook) {
+    const [cmd, ...args] = hook.manifest.command;
+    return { cmd: cmd === "node" ? process.execPath : cmd, args };
+}
+function hookEnv(env, hook, payload, file) {
+    return {
+        ...env,
+        STROM_HOOK: hook.name,
+        STROM_TREE: payload.tree.root,
+        STROM_LANG: payload.tree.lang,
+        STROM_EVENT_FILE: file,
+        // what it runs of strom reads the research the event came from, as the user would
+        STROM_NONINTERACTIVE: "1",
+    };
+}
+/** The event as a file (the hook's stdin, and STROM_EVENT_FILE); old ones are cleared away. */
+function eventFile(hook, payload) {
+    const dir = path.join(hook.dir, ".events");
+    fs.mkdirSync(dir, { recursive: true });
+    try {
+        for (const f of fs.readdirSync(dir)) {
+            const p = path.join(dir, f);
+            if (Date.now() - fs.statSync(p).mtimeMs > KEEP_MS)
+                fs.rmSync(p, { force: true });
+        }
+    }
+    catch {
+        // another process cleared it
+    }
+    const file = path.join(dir, `${payload.at.replace(/[:.]/g, "-")}-${process.pid}-${Math.random().toString(36).slice(2, 8)}.json`);
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n");
+    return file;
+}
+/** Its log, cut to its last part when it has grown too big. */
+function logFd(hook) {
+    const file = path.join(hook.dir, "hook.log");
+    try {
+        if (fs.statSync(file).size > LOG_MAX) {
+            const tail = fs.readFileSync(file).subarray(-LOG_MAX / 2);
+            fs.writeFileSync(file, tail);
+        }
+    }
+    catch {
+        // no log yet
+    }
+    return fs.openSync(file, "a");
+}
+/**
+ * Tell the hooks the user turned on what a commit saved — in the background: strom neither waits for them nor
+ * fails because of them. A hook's own writes (it may run strom) tell no hook again.
+ */
+export function fireHooks(shared, names, env, payload) {
+    if (!shared || !names?.length || !payload.events.length || env.STROM_HOOK)
+        return;
+    for (const name of names) {
+        try {
+            const hook = loadHook(shared, name);
+            const events = forHook(hook, payload.events);
+            if (!events.length)
+                continue;
+            const full = { ...payload, hook: name, events };
+            const file = eventFile(hook, full);
+            let input;
+            let log;
+            try {
+                input = fs.openSync(file, "r");
+                log = logFd(hook);
+                const { cmd, args } = program(hook);
+                const child = spawn(cmd, args, { cwd: hook.dir, env: hookEnv(env, hook, full, file), stdio: [input, log, log], detached: true, windowsHide: true });
+                child.on("error", () => undefined);
+                child.unref();
+            }
+            finally {
+                // the child has its own copies; ours are closed whatever happened
+                for (const fd of [input, log])
+                    if (fd !== undefined)
+                        fs.closeSync(fd);
+            }
+        }
+        catch {
+            // a hook that is gone or broken never stops the research: strom hook test <name> says why
+        }
+    }
+}
+/** Run a hook now and wait for it (strom hook test): what it printed and how it ended. */
+export function runHookNow(hook, env, payload) {
+    const file = eventFile(hook, payload);
+    const { cmd, args } = program(hook);
+    const r = spawnSync(cmd, args, {
+        cwd: hook.dir,
+        env: hookEnv(env, hook, payload, file),
+        input: fs.readFileSync(file),
+        encoding: "utf8",
+        timeout: (hook.manifest.timeout ?? DEFAULT_TIMEOUT_S) * 1000,
+        windowsHide: true,
+    });
+    const output = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+    if (r.error)
+        return { status: null, output, error: r.error.code === "ETIMEDOUT" ? `no end within ${hook.manifest.timeout ?? DEFAULT_TIMEOUT_S} s` : r.error.message };
+    return { status: r.status, output };
+}

package/dist/core/media.js

@@ -64,22 +64,36 @@ const MIME = {
 export function mimeOf(file) {
     return MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream";
 }
-/** Every file under the given paths (folders recursively), hidden files skipped. */
+/**
+ * Every file under the given paths (folders recursively), hidden files skipped. What is inside a folder but cannot be
+ * read (a broken link or alias, a folder the system keeps to itself) is left out; the paths given must be there.
+ */
 export function collectFiles(paths) {
     const out = [];
-    const walk = (p) => {
+    const walk = (p, given) => {
         const base = path.basename(p);
-        if (base.startsWith(".") || base === "Thumbs.db" || base === "desktop.ini")
+        if (!given && (base.startsWith(".") || base === "Thumbs.db" || base === "desktop.ini"))
+            return;
+        let st;
+        let names = [];
+        try {
+            st = fs.statSync(p);
+            if (st.isDirectory())
+                names = fs.readdirSync(p).sort();
+        }
+        catch (err) {
+            if (given)
+                throw err;
             return;
-        const st = fs.statSync(p);
+        }
         if (st.isDirectory())
-            for (const e of fs.readdirSync(p).sort())
-                walk(path.join(p, e));
+            for (const e of names)
+                walk(path.join(p, e), false);
         else if (st.isFile())
             out.push(p);
     };
     for (const p of paths)
-        walk(p);
+        walk(p, true);
     return out;
 }
 const digitGroups = (file) => path.basename(file, path.extname(file)).match(/\d+/g) ?? [];

package/dist/core/overview.js

@@ -72,6 +72,8 @@ export function treeStats(tree, from) {
         if (!stats.sessions.last || at > stats.sessions.last)
             stats.sessions.last = at;
         cost += s.metrics?.costUsd ?? 0;
+        if (s.metrics?.costPartial)
+            stats.sessions.costPartial = (stats.sessions.costPartial ?? 0) + 1;
     }
     if (cost > 0)
         stats.sessions.costUsd = Math.round(cost * 100) / 100;

package/dist/core/phrases.js

@@ -76,6 +76,7 @@ export const PHRASES = {
     "intake.done.imported": "the leads are checked for obvious mistakes (duplicates, impossible dates) and the first locate/link tasks exist",
     "intake.done.read": "what it adds to the tree is entered as leads citing it (strom source add … --kind family-tree --form authored --input {id}) — or the input is skipped with a reason (strom input skip {id} --reason …)",
     "intake.done": "every person and fact in it is recorded (a source if it is an original document, leads otherwise) and cited — or the input is skipped with a reason (strom input skip I… --reason …)",
+    "task.answer": "The user answered (to: {asked}): {answer}",
 };
 const catalogs = new Map();
 /**