strom-research 1.7.0 → 1.8.0

package/dist/core/changelog.js

@@ -0,0 +1,223 @@
+// What one commit of a research saved, as a person reads it — in the research
+// language, records by their names: "New person: Jan Novák (*1905) [P0001]",
+// "Downloaded 7 images: Kniha N 1850 (images 16–22)". Made from the operations
+// the commit logged (data/ops/*.jsonl, each line one operation); a commit
+// without them (the readers' notes) by its subject. For the Strom app (the
+// bridge's /log and change events): strom's own commit subjects are English
+// and name records by their IDs.
+import { displayName, lifespan } from "./people.js";
+import { ownerName, cardFact } from "./overview.js";
+import { phrase } from "./phrases.js";
+import { eventName, humanDate, humanPlace, humanTask } from "../cli/human.js";
+/** Operations nobody needs to read: what another line says already, or bookkeeping. */
+const QUIET = new Set(["session.metrics", "task.start", "task.continue", "session.note"]);
+/** The one-line form of an operation, by its kind: {who} a person or family, {name} the record. */
+const SAID = {
+    "person.add": "log.person.add",
+    "person.name": "log.person.name",
+    "person.edit": "log.person.edit",
+    "person.cite": "log.person.cite",
+    "person.retract": "log.person.retract",
+    "family.add": "log.family.add",
+    "family.edit": "log.family.edit",
+    "family.cite": "log.family.cite",
+    "source.add": "log.source.add",
+    "source.edit": "log.source.edit",
+    "recordset.add": "log.recordset.add",
+    "recordset.edit": "log.recordset.edit",
+    "recordset.calibrate": "log.recordset.calibrate",
+    "task.add": "log.task.add",
+    "task.done": "log.task.done",
+    "task.park": "log.task.park",
+    "task.drop": "log.task.drop",
+    "task.wait": "log.task.wait",
+    "task.wake": "log.task.wake",
+    "task.edit": "log.task.edit",
+    "session.start": "log.session.start",
+    "session.close": "log.session.close",
+    "lesson.add": "log.lesson.add",
+    "hypothesis.add": "log.hypothesis.add",
+    "hypothesis.argue": "log.hypothesis.argue",
+    "hypothesis.decide": "log.hypothesis.decide",
+    "conflict.add": "log.conflict.add",
+    "conflict.resolve": "log.conflict.resolve",
+    "place.add": "log.place.add",
+    "place.edit": "log.place.edit",
+    "place.jurisdiction": "log.place.edit",
+    "repository.add": "log.repository.add",
+    "repository.edit": "log.repository.edit",
+    "story.set": "log.story.set",
+    "story.approve": "log.story.approve",
+    "note.add": "log.note.add",
+    "input.add": "log.input.add",
+    "input.sync": "log.input.sync",
+    "input.done": "log.input.done",
+    "research.add": "log.research.add",
+    "research.edit": "log.research.edit",
+    "research.pause": "log.research.pause",
+    "research.resume": "log.research.resume",
+    "research.done": "log.research.done",
+};
+const EVENT_SAID = {
+    "event.add": "log.event.add",
+    "event.edit": "log.event.edit",
+    "event.cite": "log.event.cite",
+    "event.retract": "log.event.retract",
+};
+const SEARCH_SAID = {
+    found: "log.search.found",
+    negative: "log.search.negative",
+    partial: "log.search.partial",
+    inconclusive: "log.search.inconclusive",
+};
+function short(text, max = 90) {
+    const one = text.replace(/\s+/g, " ").trim();
+    return one.length > max ? `${one.slice(0, max - 1).trimEnd()}…` : one;
+}
+/** Image numbers as ranges: 16–22, 30. */
+function ranges(ns) {
+    const sorted = [...new Set(ns)].sort((a, b) => a - b);
+    const out = [];
+    for (let i = 0; i < sorted.length; i++) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        out.push(j > i ? `${sorted[i]}–${sorted[j]}` : String(sorted[i]));
+        i = j;
+    }
+    return out.join(", ");
+}
+function kindOf(op) {
+    const [record] = op.split(".");
+    if (record === "person" || record === "family" || record === "event")
+        return "person";
+    if (record === "source" || record === "media" || record === "recordset" || record === "repository")
+        return "source";
+    if (record === "story")
+        return "story";
+    return "other";
+}
+/** Lines of what a commit saved, in the research language, each with what it is about; its subject when it logged no operation. */
+export function changeLines(tree, ops, subject, lang) {
+    const get = (id) => (id ? tree.get(id) : undefined);
+    const who = (id) => {
+        const r = get(id);
+        if (!r)
+            return id ?? "";
+        if (r.type === "person") {
+            const span = lifespan(r);
+            return `${displayName(r)}${span ? ` (${span})` : ""} [${r.id}]`;
+        }
+        return r.type === "family" ? ownerName(tree, r.id) : r.id;
+    };
+    const task = (id) => {
+        const t = get(id);
+        return t ? short(humanTask(tree, t.what, lang)) : (id ?? "");
+    };
+    const name = (id) => {
+        const r = get(id);
+        if (!r)
+            return id ?? "";
+        switch (r.type) {
+            case "person":
+            case "family":
+                return who(r.id);
+            case "task":
+                return task(r.id);
+            case "session":
+                return r.task ? task(r.task) : r.id;
+            case "source":
+            case "recordset":
+            case "conflict":
+                return short(r.title);
+            case "research":
+            case "repository":
+            case "input":
+                return short(r.name);
+            case "search":
+                return short(r.question);
+            case "lesson":
+                return short(r.rule);
+            case "hypothesis":
+                return short(r.question);
+            case "place":
+                return r.names[0]?.name ?? r.id;
+            default:
+                return r.id;
+        }
+    };
+    const fact = (owner, eventId) => {
+        const e = get(owner)?.events.find((x) => x.id === eventId);
+        if (!e)
+            return undefined;
+        const f = cardFact(tree, e);
+        const what = [f.value, humanDate(f.date, lang), humanPlace(f.place, f.house, lang)].filter(Boolean).join(", ");
+        return `${eventName(f.kind, lang, f.label)}${what ? `: ${what}` : ""}`;
+    };
+    const out = [];
+    let kind = "other";
+    const say = (line) => {
+        if (line && !out.some((l) => l.text === line))
+            out.push({ text: line, kind });
+    };
+    // Images downloaded: one line for each book, whatever their order.
+    const images = new Map();
+    for (const o of ops) {
+        if (QUIET.has(o.op))
+            continue;
+        kind = kindOf(o.op);
+        const [first, second] = o.targets;
+        if (o.op === "media.add") {
+            const m = get(first);
+            const key = m?.recordset ?? "";
+            if (!images.has(key)) {
+                images.set(key, []);
+                out.push({ text: `\u0000media:${key}`, kind: "source" }); // its place in the order, filled in below
+            }
+            if (m?.image !== undefined)
+                images.get(key).push(m.image);
+            continue;
+        }
+        if (EVENT_SAID[o.op]) {
+            const f = fact(first, second);
+            say(f ? phrase(lang, EVENT_SAID[o.op], { who: who(first), fact: f }) : o.summary);
+            continue;
+        }
+        if (o.op === "search.add" || o.op === "search.edit") {
+            const s = get(first);
+            say(s ? phrase(lang, SEARCH_SAID[s.result] ?? "log.search.found", { name: short(s.question) }) : o.summary);
+            continue;
+        }
+        if (o.op === "family.child") {
+            say(phrase(lang, "log.family.child", { who: who(first), child: who(second) }));
+            continue;
+        }
+        if (o.op === "person.merge" || o.op === "family.merge") {
+            say(phrase(lang, "log.merge", { who: who(second) }));
+            continue;
+        }
+        const key = SAID[o.op];
+        say(key ? phrase(lang, key, { who: who(first), name: name(first) }) : o.summary);
+    }
+    const lines = out.map(({ text: line, kind }) => {
+        if (!line.startsWith("\u0000media:"))
+            return { text: line, kind };
+        const book = line.slice("\u0000media:".length);
+        const ns = images.get(book) ?? [];
+        const title = get(book)?.title;
+        const n = Math.max(ns.length, 1);
+        const text = !title
+            ? phrase(lang, "log.media.loose", { n })
+            : ns.length === 1
+                ? phrase(lang, "log.media.one", { name: title, image: ns[0] })
+                : phrase(lang, "log.media", { name: title, n, images: ns.length ? ranges(ns) : "" });
+        return { text, kind };
+    });
+    if (lines.length)
+        return lines;
+    // no operations: the readers' notes of a book, else the subject as strom wrote it
+    const reading = /^Reading (B\d+)-(\d+)-(\d+): (\d+) images?/.exec(subject);
+    if (reading)
+        return [{ text: phrase(lang, "log.reading", { name: get(reading[1])?.title ?? reading[1], n: reading[4], images: reading[2] === reading[3] ? reading[2] : `${reading[2]}–${reading[3]}` }), kind: "source" }];
+    return ops.length ? [] : [{ text: subject, kind: "other" }];
+}

package/dist/core/clock.js

@@ -5,12 +5,32 @@
 // 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).
+import fs from "node:fs";
+import path from "node:path";
 /** 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;
+/**
+ * The user asked a session to finish now (strom session finish): a file of the tree's own, read by every strom
+ * command the session's agent runs — a run's session cannot be told otherwise (it reads no input).
+ */
+export function finishFile(root, session) {
+    return path.join(root, ".strom", "finish", `${session}.json`);
+}
+export function askFinish(root, session, by) {
+    fs.mkdirSync(path.dirname(finishFile(root, session)), { recursive: true });
+    fs.writeFileSync(finishFile(root, session), JSON.stringify({ at: new Date().toISOString(), by }) + "\n");
+}
+export function finishAsked(root, session) {
+    return fs.existsSync(finishFile(root, session));
+}
+/** What every strom command says to the agent of a session the user asked to finish. */
+export const FINISH_LINE = "⏳ the user asks you to finish this session now: start nothing new; record in strom what you found and have not recorded yet " +
+    '(facts, sources, the images searched, in vain too), then strom session close --continue --summary "…" --next "exactly where you stopped" ' +
+    "(or finish the task, if it is done).";
 /** 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 ?? "");

package/dist/core/config.js

@@ -55,6 +55,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.browser", env: "", tree: true, kind: "choice", choices: ["archives", "always"], description: "browser tools (Claude in Chrome) for the Claude Code sessions strom starts: archives (default) — only in a research whose connectors fetch through the browser, for their sites; always — in every session, for the sites of the research's archives (a conversation asks about others) — only you turn it on" },
     { 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" },
@@ -72,6 +73,7 @@ const FIELDS = {
     "agent.permissions": "agentPermissions",
     "agent.where": "agentWhere",
     "agent.remote": "agentRemote",
+    "agent.browser": "agentBrowser",
     "strom.app": "stromApp",
     "strom.app.url": "stromAppUrl",
     "main.person": "mainPerson",

package/dist/core/connector.js

@@ -236,6 +236,11 @@ export function treeBrowserConnectors(tree, shared) {
     if (!all.length)
         return [];
     const fetchedBy = new Set(tree.list("media").flatMap((m) => (m.fetched ? [m.fetched.connector] : [])));
+    const hosts = new Set(treeSites(tree));
+    return all.filter((c) => fetchedBy.has(c.name) || c.manifest.hosts.some((h) => hosts.has(siteOf(h))));
+}
+/** The sites of the archives a tree's records name (repositories, record sets, sources with an address). */
+function treeSites(tree) {
     const hosts = new Set();
     for (const r of [...tree.list("repository"), ...tree.list("recordset"), ...tree.list("source")])
         if (r.url && !r.retracted)
@@ -245,7 +250,26 @@ export function treeBrowserConnectors(tree, shared) {
             catch {
                 // not an address
             }
-    return all.filter((c) => fetchedBy.has(c.name) || c.manifest.hosts.some((h) => hosts.has(siteOf(h))));
+    return [...hosts];
+}
+/**
+ * Browser tools for the tree's agent (Claude in Chrome): whether its sessions get them, and for which sites.
+ * `agent.browser` archives (default): only where a connector of the tree fetches through the browser, for its sites;
+ * always (the user's choice): every session, for the sites of the tree's archives and of the connectors — a
+ * conversation asks about any other, a run nobody watches uses none other.
+ */
+export function agentBrowser(tree, shared) {
+    const via = treeBrowserConnectors(tree, shared);
+    const always = new Settings(tree.env, {}).resolve("agent.browser", tree.config)?.value === "always";
+    const hosts = new Set(via.flatMap((c) => c.manifest.hosts));
+    if (always) {
+        for (const c of shared ? scanConnectors(shared).connectors : [])
+            for (const h of c.manifest.hosts)
+                hosts.add(h);
+        for (const h of treeSites(tree))
+            hosts.add(h);
+    }
+    return { on: always || via.length > 0, hosts: [...hosts], always };
 }
 export function findConnector(shared, name) {
     if (!shared)

package/dist/core/directions.js

@@ -0,0 +1,41 @@
+// Which direction of a research (G…) a task belongs to. A task names its
+// research when it was added in a session of one (or named it); a task added
+// elsewhere belongs to the direction its people are in — the narrowest one when
+// several reach them (the ancestors of a grandmother before those of her
+// grandson). The queue, the menu and the Strom app go by the same answer.
+import { researchPeople } from "./frontier.js";
+import { subjectPeople } from "./records.js";
+import { typeOfId } from "./tree.js";
+export function scopes(tree) {
+    return tree.list("research").map((research) => ({ research, people: researchPeople(tree, research) }));
+}
+/** The people a task is about: its persons, the partners of its families, the people of its conflicts and hypotheses. */
+export function aboutPeople(tree, subject) {
+    const partners = subject.filter((id) => typeOfId(id) === "family").flatMap((id) => tree.get(id)?.partners ?? []);
+    return [...new Set([...subjectPeople(tree, subject), ...partners])];
+}
+/** The direction a task belongs to: its own, else the narrowest one its people are in; none for a task about nobody. */
+export function directionOf(tree, t, all) {
+    if (t.research)
+        return t.research;
+    const about = aboutPeople(tree, t.subject);
+    if (!about.length)
+        return undefined;
+    return all
+        .filter((s) => about.some((p) => s.people.has(p)))
+        .sort((a, b) => a.people.size - b.people.size || a.research.id.localeCompare(b.research.id))[0]?.research.id;
+}
+/**
+ * Whether a task is work of a research (strom session start --research, strom
+ * run --research): its own, or about the people it is about (a task added
+ * elsewhere or before it began); a task about nobody and of no research, any
+ * research's.
+ */
+export function ofResearch(tree, t, scope) {
+    if (t.research === scope.research.id)
+        return true;
+    const about = aboutPeople(tree, t.subject);
+    if (!about.length)
+        return !t.research;
+    return about.some((p) => scope.people.has(p)) || (!t.research && !scope.people.size);
+}

package/dist/core/links.js

@@ -29,15 +29,19 @@ export const LINK_SCHEME = "strom-research";
  * as it is now into the app's window, open the research's menu, a conversation with the agent (of one person),
  * a task (answered, put aside, given up, back in the queue), a person's review, a new direction from a person —
  * and (the app's second wave) a new research with a tree of the app, strom's update, the agent's sessions and
- * what they cost, a conflict decided (by the user or the agent), a story approved, a sync taken back, the setup.
+ * what they cost, a conflict decided (by the user or the agent), a story approved, a sync taken back, the setup —
+ * and (the app's 3.5.0) the research followed live in the app's window; a direction of the research paused, ended or
+ * taken up again, a conversation about one direction, a session at work asked to finish.
  */
-export const LINK_ACTIONS = ["send", "excerpt", "app", "open", "chat", "task", "review", "research", "new", "update", "sessions", "conflict", "story", "sync-undo", "setup"];
+export const LINK_ACTIONS = ["send", "excerpt", "app", "open", "chat", "task", "review", "research", "new", "update", "sessions", "conflict", "story", "sync-undo", "setup", "live", "direction", "finish"];
 /** A person's review: the person, with the family, with the ancestors (strom review --scope). */
 export const LINK_SCOPES = ["person", "family", "line"];
 /** A new direction from a person (strom research new --direction). */
 export const LINK_DIRECTIONS = ["ancestors", "descendants"];
 /** What a link does with a task: put it aside, give it up, back into the queue (none: answer it). */
 export const LINK_TASK_DOS = ["park", "drop", "wake"];
+/** What a link does with a direction of the research (strom research pause|done|resume). */
+export const LINK_DIRECTION_DOS = ["pause", "done", "resume"];
 /** What a link does with a conflict: the user decides it, or leaves it to the agent. */
 export const LINK_CONFLICT_DOS = ["decide", "agent"];
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -46,6 +50,8 @@ const PERSON = /^P\d{1,9}$/;
 const TASK = /^T\d{1,9}$/;
 const CONFLICT = /^X\d{1,9}$/;
 const INPUT = /^I\d{1,9}$/;
+const RESEARCH = /^G\d{1,9}$/;
+const SESSION = /^N\d{1,9}$/;
 /** The app's own mark of a tree it hands over (32 random bytes, base64url). */
 export const APP_TOKEN = /^[A-Za-z0-9_-]{22,43}$/;
 /** An excerpt's mark (_STROM_CLIP): letters, digits and "-", at most 32. */
@@ -103,6 +109,7 @@ export function parseLink(text) {
     switch (action) {
         case "send":
         case "app":
+        case "live":
         case "open":
         case "update":
         case "sessions":
@@ -115,8 +122,10 @@ export function parseLink(text) {
                 throw new LinkError("no excerpt named");
             return { action, tree: id, source, clip };
         }
-        case "chat":
-            return { action, tree: id, ...(person ? { person } : {}) };
+        case "chat": {
+            const research = idOf(q, "research", RESEARCH, false);
+            return { action, tree: id, ...(person ? { person } : {}), ...(research ? { research } : {}) };
+        }
         case "task": {
             const task = idOf(q, "task", TASK, true);
             return { action, tree: id, task, ...(q.has("do") ? { do: oneOf(q, "do", LINK_TASK_DOS) } : {}) };
@@ -136,6 +145,10 @@ export function parseLink(text) {
             return { action, tree: id, id: idOf(q, "id", CONFLICT, true), do: oneOf(q, "do", LINK_CONFLICT_DOS, "decide") };
         case "sync-undo":
             return { action, tree: id, intake: idOf(q, "intake", INPUT, true) };
+        case "direction":
+            return { action, tree: id, id: idOf(q, "id", RESEARCH, true), do: oneOf(q, "do", LINK_DIRECTION_DOS) };
+        case "finish":
+            return { action, tree: id, session: idOf(q, "session", SESSION, true) };
     }
     throw new LinkError(`unknown action "${action.slice(0, 32)}"`);
 }