strom-research 1.1.1 → 1.3.0

package/assets/plugins/gates/claude-usage/gate.ts

@@ -0,0 +1,125 @@
+// A strom gate (interface 1): let the research work alone while the Claude
+// subscription has room. It asks Claude Code itself (`claude -p /usage`, the
+// plan's limits as the server reports them) and answers strom:
+//   exit 0  go on           exit 1  wait (JSON "until": when to ask again)
+//   exit 2  stop the run    — one line of JSON on stdout says why.
+//
+// The rule, the pace of the week: the share of the week gone since its reset
+// (a day is about 14.3 %) against the week's usage. With the number you give
+// it (strom config set run.gate "claude-usage 10") a session starts only while
+// usage is at least that many points behind the week gone: gone − used ≥ 10.
+// Without a number: 0 — no faster than the week goes. Else it waits until the
+// week has caught up (or past the reset); a full session: until it resets.
+//
+// strom writes this file; a copy of your own goes into a folder of its own name.
+
+import { spawnSync } from "node:child_process";
+
+const DAY = 86_400_000;
+const WEEK = 7 * DAY;
+const lang = (process.env.STROM_LANG ?? "en").slice(0, 2);
+
+const T: Record<string, Record<string, string>> = {
+  en: {
+    other: "the agent is not Claude Code — nothing to check",
+    api: "Claude Code runs on an API key, not a subscription — no plan limits",
+    go: "week {used} % used, {gone} % gone, {behind} in hand (at least {min} needed)",
+    session: "the session is used up — until it resets",
+    week: "week {used} % used, {gone} % gone, {behind} in hand (at least {min} needed) — until the week catches up",
+    bad: "the number must be 0 to 99, not \"{arg}\"",
+    unread: "cannot read `claude -p /usage`: {detail}",
+  },
+  cs: {
+    other: "agent není Claude Code — není co hlídat",
+    api: "Claude Code běží na API klíči, ne na předplatném — žádné limity plánu",
+    go: "týden: využito {used} %, uplynulo {gone} %, náskok {behind} (potřeba aspoň {min})",
+    session: "sezení je vyčerpané — do jeho obnovení",
+    week: "týden: využito {used} %, uplynulo {gone} %, náskok {behind} (potřeba aspoň {min}) — dokud čas nedožene",
+    bad: "číslo musí být 0 až 99, ne \"{arg}\"",
+    unread: "nelze přečíst `claude -p /usage`: {detail}",
+  },
+  de: {
+    other: "der Agent ist nicht Claude Code — nichts zu prüfen",
+    api: "Claude Code läuft mit einem API-Schlüssel, nicht im Abo — keine Planlimits",
+    go: "Woche: {used} % genutzt, {gone} % vergangen, Vorsprung {behind} (mindestens {min} nötig)",
+    session: "die Sitzung ist aufgebraucht — bis sie zurückgesetzt wird",
+    week: "Woche: {used} % genutzt, {gone} % vergangen, Vorsprung {behind} (mindestens {min} nötig) — bis die Zeit aufholt",
+    bad: "die Zahl muss 0 bis 99 sein, nicht \"{arg}\"",
+    unread: "`claude -p /usage` nicht lesbar: {detail}",
+  },
+};
+function say(key: string, v: Record<string, string | number> = {}): string {
+  const s = (T[lang] ?? T.en!)[key] ?? T.en![key]!;
+  return s.replace(/\{(\w+)\}/g, (_, k: string) => String(v[k] ?? ""));
+}
+function answer(code: 0 | 1 | 2, reason: string, until?: Date): never {
+  console.log(JSON.stringify({ reason, ...(until ? { until: until.toISOString() } : {}) }));
+  process.exit(code);
+}
+
+// ── your number: how many points usage must be behind the week gone ─────────
+const arg = process.argv[2] ?? "0";
+const min = Number(arg);
+if (!/^\d{1,2}$/.test(arg)) answer(2, say("bad", { arg }));
+
+if ((process.env.STROM_AGENT ?? "claude") !== "claude") answer(0, say("other"));
+
+// ── what Claude Code says ───────────────────────────────────────────────────
+const r = spawnSync("claude", ["-p", "/usage"], { encoding: "utf8", timeout: 90_000, shell: process.platform === "win32", windowsHide: true });
+if (r.error || r.status !== 0) answer(2, say("unread", { detail: r.error?.message ?? (r.stderr || r.stdout || `exit ${r.status}`).trim().split("\n")[0] ?? "" }));
+const text = r.stdout;
+if (/API key/i.test(text) && !/Current week/i.test(text)) answer(0, say("api"));
+
+const LINE = /^Current (session|week)(?: \(([^)]+)\))?:\s*(\d+)%\s*used(?:\s*·\s*resets\s*(.+))?$/i;
+let session: { used: number; resets?: Date } | undefined;
+let week: { used: number; resets?: Date } | undefined;
+for (const raw of text.split(/\r?\n/)) {
+  const m = LINE.exec(raw.trim());
+  if (!m) continue;
+  const item = { used: Number(m[3]), ...(m[4] ? { resets: resetAt(m[4]) } : {}) };
+  if (m[1]!.toLowerCase() === "session") session = item;
+  // the limit of all models is the one that stops the work; a model's own week only if there is no other
+  else if (!week || /all models/i.test(m[2] ?? "")) week = item;
+}
+if (!week?.resets) answer(2, say("unread", { detail: "no line \"Current week … resets …\"" }));
+
+const now = Date.now();
+const start = week.resets.getTime() - WEEK;
+const gone = Math.max(0, Math.min(100, ((now - start) / WEEK) * 100));
+const behind = gone - week.used;
+const v = { used: week.used, gone: Math.round(gone), behind: Math.round(behind), min };
+if (session && session.used >= 100) answer(1, say("session"), session.resets ? new Date(session.resets.getTime() + 60_000) : undefined);
+if (behind < min) {
+  // when the week gone reaches usage + the number; past the reset, the new week's number
+  let at = start + ((week.used + min) / 100) * WEEK;
+  if (at >= week.resets.getTime()) at = week.resets.getTime() + (min / 100) * WEEK;
+  answer(1, say("week", v), new Date(Math.max(at, now + 5 * 60_000)));
+}
+answer(0, say("go", v));
+
+/** "Sep 30 at 2pm (Europe/Prague)", "Oct 2 at 11:30am (UTC)" → the moment. */
+function resetAt(s: string): Date | undefined {
+  const m = /^(\w{3})\w*\s+(\d{1,2})\s+at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(([^)]+)\)/i.exec(s.trim());
+  if (!m) return undefined;
+  const month = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"].indexOf(m[1]!.toLowerCase());
+  if (month < 0) return undefined;
+  const hour = (Number(m[3]) % 12) + (m[5]!.toLowerCase() === "pm" ? 12 : 0);
+  const zone = m[6]!;
+  for (const year of [new Date().getUTCFullYear(), new Date().getUTCFullYear() + 1]) {
+    const guess = Date.UTC(year, month, Number(m[2]), hour, Number(m[4] ?? 0));
+    const at = guess - offsetMs(guess, zone);
+    if (at > Date.now() - DAY) return new Date(at);
+  }
+  return undefined;
+}
+
+/** The zone's offset from UTC at that moment ("Europe/Prague" in summer: +2 h). */
+function offsetMs(at: number, zone: string): number {
+  try {
+    const name = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" }).formatToParts(new Date(at)).find((p) => p.type === "timeZoneName")?.value ?? "";
+    const m = /GMT([+-])(\d{2}):?(\d{2})?/.exec(name);
+    return m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3] ?? 0)) * 60_000 : 0;
+  } catch {
+    return 0;
+  }
+}

package/assets/plugins/hooks/README.md

@@ -0,0 +1,91 @@
+# strom hooks — interface 1
+
+A hook is a program of yours that strom tells what was saved into a research:
+a person added to the family tree, a fact found, a task done, a session
+closed. What it does with it is up to you — a message to your phone, a line
+in a log, a backup. strom starts it in the background after each save and
+never waits for it: a hook that is slow or fails never holds up or breaks the
+research.
+
+    plugins/hooks/
+      README.md                this interface
+      my-hook/                 one hook: hook.json and its program
+        hook.log               what it printed (strom keeps it)
+
+**Turn one on**: `strom hook on <name>` — only you (an agent asks you in a
+window of the system). A folder alone does nothing: an agent may build a hook
+for you, but it runs only once you turn it on. `strom hook off <name>`,
+`strom hook list`. **Try it**: `strom hook test <name>` runs it now on the last
+operations saved in the research you are in, waits and shows what it printed
+(`--op person.add --target P0001`: one operation you name).
+
+## hook.json
+
+    {
+      "interface": 1,
+      "title": "My phone",
+      "command": ["node", "hook.ts"],
+      "events": ["person.add", "family.child", "session.close"]
+    }
+
+- `command`: the program and its arguments, run in the hook's folder. `node`
+  is strom's own Node (TypeScript runs as it is) — best on every system.
+- `events`: the operations it wants — one (`person.add`), a kind
+  (`person.*`) or all (`*`, the default). Saves with none of them do not start
+  it.
+- `timeout`: seconds `strom hook test` waits for it (default 60).
+
+## What it gets
+
+One JSON document on stdin (also in the file `STROM_EVENT_FILE`): one save
+into one research, with the operations it saved that the hook wants.
+
+    {
+      "interface": 1,
+      "hook": "my-hook",
+      "tree": { "name": "Novákovi", "id": "…", "root": "/…/Novákovi", "lang": "en" },
+      "commit": "3f2a9c1…",
+      "at": "2026-10-02T14:03:11.000Z",
+      "events": [
+        { "op": "person.add", "targets": ["P0012"], "summary": "+P0012 Josef /Novák/ · E0031 BIRT 1851 …",
+          "at": "2026-10-02T14:03:10.412Z", "by": "N0007" }
+      ]
+    }
+
+- `op`: what was done — `person.add` (a person in the family tree),
+  `family.add`, `family.child` (a child linked to parents), `event.add` (a
+  fact: birth, marriage, death…), `event.edit`, `person.merge`, `source.add`
+  (a record read), `media.add` (a scan), `task.add`, `task.done`, `task.wait`
+  (waiting for you), `story.set`, `session.start`, `session.close`… — the same
+  names as the research's history.
+- `targets`: the records it concerns — read more of them through strom, as
+  the user would: `strom person card P0012`, `strom person show P0012 --json`,
+  `strom session show N0007`.
+- `by`: the session that saved it (N0007), or `user`.
+- `tree`: which research. A hook you turn on hears from all your researches;
+  to hear from some only, let it skip the others by `tree.name` or `tree.id`
+  (e.g. a list in a config file of its own).
+
+Environment variables, besides the user's own: `STROM_HOOK` (its name),
+`STROM_TREE` (the research's folder — run strom there), `STROM_LANG` (the
+research language), `STROM_EVENT_FILE`. What the hook itself writes through
+strom tells no hook again.
+
+## An example: a message to your phone (Telegram)
+
+    // hook.ts — the bot's token and your chat's id in config.json beside it
+    import fs from "node:fs";
+    import { execFileSync } from "node:child_process";
+    const cfg = JSON.parse(fs.readFileSync("config.json", "utf8"));
+    const save = JSON.parse(fs.readFileSync(0, "utf8"));
+    for (const e of save.events.filter((e) => e.op === "person.add")) {
+      const card = execFileSync("strom", ["person", "card", e.targets[0]], { cwd: save.tree.root, encoding: "utf8" });
+      await fetch(`https://api.telegram.org/bot${cfg.token}/sendMessage`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ chat_id: cfg.chat, text: `${save.tree.name}: a new person\n\n${card}` }),
+      });
+    }
+
+Keep secrets such as a token in the hook's own folder: the `.gitignore` of the
+plugins folder keeps every plugin out of any repository.

package/dist/agents/global.js

@@ -80,6 +80,16 @@ const OPENCODE_STROM = "strom *";
 function opencodeDir(env) {
     return path.join(env.XDG_CONFIG_HOME ?? path.join(userHome(env), ".config"), "opencode");
 }
+/** Claude Code starts its own conversations with Remote Control (its setting remoteControlAtStartup, the user's own). */
+export function claudeRemoteAtStartup(env) {
+    try {
+        const file = path.join(env.CLAUDE_CONFIG_DIR ?? path.join(userHome(env), ".claude"), "settings.json");
+        return JSON.parse(fs.readFileSync(file, "utf8")).remoteControlAtStartup === true;
+    }
+    catch {
+        return false; // no settings, or not readable: not on
+    }
+}
 export function globalTargets(env) {
     const home = userHome(env);
     return [

package/dist/agents/launch.js

@@ -19,7 +19,7 @@ import { claudeArgs } from "../runners/claude.js";
 /** The command line of a conversation with this agent. */
 export function conversationArgs(agent, o) {
     if (agent === "claude")
-        return claudeArgs({ interactive: true, kickoff: o.kickoff, permissions: o.level, settingsFile: o.settingsFile, ...(o.name ? { name: o.name } : {}), ...(o.model ? { model: o.model } : {}), ...(o.chrome !== undefined ? { chrome: o.chrome } : {}) });
+        return claudeArgs({ interactive: true, kickoff: o.kickoff, permissions: o.level, settingsFile: o.settingsFile, ...(o.name ? { name: o.name } : {}), ...(o.model ? { model: o.model } : {}), ...(o.chrome !== undefined ? { chrome: o.chrome } : {}), ...(o.remote ? { remote: true } : {}) });
     if (agent === "codex") {
         const args = o.level === "full"
             ? ["--dangerously-bypass-approvals-and-sandbox"]

package/dist/brief/brief.js

@@ -10,6 +10,7 @@ import { displayName, familiesAsChild, familiesAsPartner, formatName, label, lif
 import { langName } from "../core/lang.js";
 import { methodFor } from "../core/assets.js";
 import { recentSessions } from "../core/session.js";
+import { briefClock } from "../core/clock.js";
 import { calibrationLine } from "../core/calibration.js";
 import { taskRecordsets } from "../core/frontier.js";
 import { reviewItems } from "../core/review.js";
@@ -122,6 +123,7 @@ export function buildBrief(tree, opts) {
             ...(research?.notes ?? []).slice(-3).map((n) => `From the user: ${n.text}`),
             `Research language: ${langName(lang)} — talk to the user and write notes, tasks and summaries in ${langName(lang)}; transcripts stay in the original language.`,
             "Work ONLY through `strom` commands; never edit files in data/ (it is detected and blocks all writing). Record findings as you go.",
+            opts.deadline !== undefined ? briefClock(opts.deadline) : "",
         ].filter(Boolean).join("\n"),
     });
     // 2. the task

package/dist/cli/main.js

@@ -6,11 +6,16 @@ import { groupHelp, helpFor } from "./help.js";
 import { autoCommit } from "./commit.js";
 import { assertIntact } from "../core/integrity.js";
 import { resetCache } from "../core/git.js";
-import { VERSION } from "../core/tree.js";
+import { Tree, VERSION } from "../core/tree.js";
+import { fireHooks, HOOK_INTERFACE } from "../core/hooks.js";
+import { prependPath } from "../runners/runner.js";
+import { shimDir } from "../commands/session.js";
 import { isAgent } from "../core/which.js";
 import { noticeStromApp } from "../core/stromapp.js";
 import { isNewer } from "../core/update.js";
 import { refreshGlobal } from "../agents/global.js";
+import { clockLine } from "../core/clock.js";
+import { currentSession } from "../core/session.js";
 import { checkArgs, GroupOnly, parseOptions, resolveCommand, splitPassthrough } from "./execute.js";
 import "../commands/index.js";
 export { splitCommand } from "./execute.js";
@@ -74,6 +79,9 @@ export async function main(argv, io, env, cwd) {
     const json = argv.includes("--json");
     const debug = argv.includes("--debug");
     resetCache();
+    // what ran, for the reminder of the session's time
+    let ran;
+    let command;
     try {
         // "strom 'person list'" (one quoted word) means the same as strom person list.
         if (argv[0] && !argv[0].startsWith("-") && /\s/.test(argv[0].trim()))
@@ -109,6 +117,21 @@ export async function main(argv, io, env, cwd) {
             return EXIT.ok;
         }
         const ctx = Context.fromOptions({ env, cwd, io, json, values: v });
+        ran = ctx;
+        command = def.path.join(" ");
+        // What is saved into a research, the user's hooks are told of (in the background).
+        Tree.onCommit = (tree, ops, commit) => {
+            if (!ctx.settings.config.hooks?.length || env.STROM_HOOK)
+                return;
+            // this strom on the hook's PATH: it reads more of what was saved (strom person card P0012)
+            fireHooks(ctx.settings.shared()?.value, ctx.settings.config.hooks, prependPath(env, shimDir(tree)), {
+                interface: HOOK_INTERFACE,
+                tree: { name: tree.config.name, id: tree.config.id, root: tree.root, lang: tree.lang },
+                commit,
+                at: new Date().toISOString(),
+                events: ops.map((o) => ({ op: o.op, targets: o.targets, summary: o.summary, at: o.at, by: o.by, ...(o.reason ? { reason: o.reason } : {}) })),
+            });
+        };
         // Started by the Strom app: remembered quietly (it is where the results go).
         if (env.STROM_APP)
             noticeStromApp(ctx.settings, env);
@@ -153,9 +176,27 @@ export async function main(argv, io, env, cwd) {
         // command has the tree to itself from its first read to its commit.
         const result = def.writes && def.tree && def.lock !== "sections" ? await ctx.tree().holdTreeLock(work) : await work();
         print(io, ctx, result);
+        remind(io, ctx, command);
         return result.exitCode ?? EXIT.ok;
     }
     catch (err) {
-        return printError(io, json, err, debug);
+        const code = printError(io, json, err, debug);
+        remind(io, ran, command);
+        return code;
+    }
+}
+/** Near the end of a session with a time limit (strom run), every command reminds the agent how long it has left. */
+function remind(io, ctx, command) {
+    const line = ctx && command !== "session close" ? clockLine(ctx.env) : undefined;
+    if (!line)
+        return;
+    try {
+        // closed already: nothing to remind of
+        if (ctx.hasTree() && !currentSession(ctx.tree(), ctx.env))
+            return;
+    }
+    catch {
+        return;
     }
+    io.stderr(line + "\n");
 }

package/dist/cli/menu-parts.js

@@ -0,0 +1,140 @@
+// What the guided menu and its submenus share: an item, the loop of a submenu,
+// asking for a person, and the paths a person drops into the terminal.
+import { fileURLToPath } from "node:url";
+import { ui } from "./ui.js";
+import { Tree } from "../core/tree.js";
+import { findPersons, label } from "../core/people.js";
+import { agentsHere } from "../core/apps.js";
+import { AGENTS } from "../core/which.js";
+/** The test (or a script) gave all its answers: nothing more is asked. */
+export function outOfAnswers(ctx) {
+    return ctx.io.answers !== undefined && ctx.io.answers.length === 0;
+}
+/** "Press Enter to go back to the menu." — unless there is nobody to press it. */
+export async function pause(ctx, lang) {
+    if (!outOfAnswers(ctx))
+        await ctx.ask(ui(lang, "ui.enter"));
+}
+/**
+ * A submenu: its items (built afresh each time, so what they say is current), numbered in the order shown, 0 back.
+ * An item's act returning true leaves the submenu. An act waits for Enter itself, only after a long answer —
+ * never after 0 or a question left: the person went back, nothing to read.
+ */
+export async function subMenu(ctx, lang, build) {
+    for (;;) {
+        if (outOfAnswers(ctx))
+            return;
+        const { title, items } = build();
+        const all = [...items, { key: "0", label: ui(lang, "ui.browse.back"), act: async () => true }];
+        ctx.io.stdout("\n");
+        let n = 0;
+        // Enter goes back: an item here changes or starts something, a person picks it by its number
+        const i = await ctx.choose(title ?? "", all.map((it) => ({ key: it.key === "0" ? "0" : String(++n), label: it.label })), all.length - 1);
+        if (i === undefined)
+            return;
+        if ((await guarded(ctx, lang, all[i].act)) === true)
+            return;
+    }
+}
+/** Ask for a person by name or ID; several match: pick one. Nobody (Enter, or no answers left): undefined. */
+export async function pickPerson(ctx, lang, root, question, suggested) {
+    const tree = Tree.open(root, ctx.env);
+    for (;;) {
+        if (outOfAnswers(ctx))
+            return undefined;
+        const who = (await ctx.ask(question, suggested)).trim();
+        if (!who || who === "0")
+            return undefined;
+        const byId = /^P\d+$/i.test(who) ? tree.get(who.toUpperCase()) : undefined;
+        const hits = byId && !byId.retracted ? [byId] : findPersons(tree, who);
+        if (!hits.length)
+            ctx.io.stdout(ui(lang, "ui.review.none", { who }) + "\n");
+        else if (hits.length === 1)
+            return hits[0];
+        else {
+            const i = await ctx.choose(ui(lang, "ui.review.pick"), hits.slice(0, 9).map((p) => ({ label: label(p) })), 0, { back: ui(lang, "ui.browse.back") });
+            return i === undefined ? undefined : hits[i];
+        }
+    }
+}
+/**
+ * The paths in what a person typed or dropped into the terminal: a file dragged in comes quoted ('…', "…") or
+ * with its spaces escaped (macOS, Linux: My\ Folder), several of them separated by spaces. On Windows a backslash
+ * is the path's own, never an escape.
+ */
+export function droppedPaths(answer, platform = process.platform) {
+    const out = [];
+    let cur = "";
+    let quote;
+    let any = false;
+    const s = answer.trim();
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (quote) {
+            if (c === quote)
+                quote = undefined;
+            else
+                cur += c;
+        }
+        else if (c === "'" || c === '"') {
+            quote = c;
+            any = true;
+        }
+        else if (c === "\\" && platform !== "win32" && i + 1 < s.length) {
+            cur += s[++i];
+            any = true;
+        }
+        else if (/\s/u.test(c)) {
+            if (cur || any)
+                out.push(cur);
+            cur = "";
+            any = false;
+        }
+        else
+            cur += c;
+    }
+    if (cur || any)
+        out.push(cur);
+    // some terminals drop a file as its address: file:///Users/…/My%20Folder
+    return out.filter(Boolean).map((p) => {
+        // Git Bash on Windows: /c/Users/… is C:\Users\…
+        const drive = platform === "win32" ? /^\/([a-zA-Z])(\/.*)?$/u.exec(p) : null;
+        if (drive)
+            return `${drive[1].toUpperCase()}:${(drive[2] ?? "/").replace(/\//gu, "\\")}`;
+        if (!/^file:\/\//iu.test(p))
+            return p;
+        try {
+            return fileURLToPath(p);
+        }
+        catch {
+            return p;
+        }
+    });
+}
+/** The translator of one language, as the menu's items use it. */
+export function translator(lang) {
+    return (key, values = {}) => ui(lang, key, values);
+}
+/** Is the agent of the research on this computer — its CLI or its desktop app? Without it, nothing is offered to start with it. */
+export function agentReady(ctx, tree) {
+    const agent = ctx.settings.agent(tree).value;
+    // an agent strom does not look for (a script of the user's) is theirs to have
+    return !AGENTS.some((a) => a.id === agent) || agentsHere(ctx.env).some((a) => a.id === agent);
+}
+/** Claude Code is the agent of the research and on this computer: only then does the menu speak of what is Claude's (Remote Control, its usage). */
+export function claudeHere(ctx, tree) {
+    return ctx.settings.agent(tree).value === "claude" && agentsHere(ctx.env).some((a) => a.id === "claude" && a.cli);
+}
+/**
+ * An item's act, and what goes wrong in it said in a sentence — the menu goes on (a folder that could not be read, a
+ * command that refused): never a crash of the menu with an agent's error.
+ */
+export async function guarded(ctx, lang, act) {
+    try {
+        return await act();
+    }
+    catch (err) {
+        ctx.io.stdout(ui(lang, "ui.menu.failed", { reason: err.message }) + "\n");
+        await pause(ctx, lang);
+    }
+}