strom-research 1.5.0 → 1.6.0

package/dist/core/excerpt.js

@@ -7,7 +7,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { inputPath, sharperPart } from "./media.js";
+import { clipText, inputPath, sharperPart } from "./media.js";
 import { kinship } from "./kin.js";
 import { Settings } from "./config.js";
 import { crop, resize, toGrey } from "../image/image.js";
@@ -21,6 +21,11 @@ export const LEVELS = [
 ];
 /** A margin round the clip, of its longer side: the edge of the entry stays in. */
 const MARGIN = 0.03;
+/** A clip's mark: from where it is (its image and region) — a clip made again is another excerpt; "input": a document the user gave. */
+export function clipMark(c) {
+    return `c${crypto.createHash("sha256").update(clipText(c)).digest("hex").slice(0, 10)}`;
+}
+export const INPUT_MARK = "input";
 /** A clip with the margin an excerpt keeps round it. */
 export function withMargin(r) {
     const pad = MARGIN * Math.max(r.w, r.h);
@@ -60,7 +65,7 @@ export function renderClip(tree, shared, clip, all = tree.list("media"), level =
         const jpeg = fs.readFileSync(cache);
         const size = imageSize(jpeg);
         if (size)
-            return { media: m.id, from: src.id, jpeg, ...size, url };
+            return { media: m.id, from: src.id, jpeg, ...size, url, clip: clipMark(clip) };
     }
     if (cachedOnly)
         return LATER;
@@ -69,7 +74,7 @@ export function renderClip(tree, shared, clip, all = tree.list("media"), level =
     const out = finish(crop(img, px.x, px.y, Math.max(1, Math.min(px.w, img.width - px.x)), Math.max(1, Math.min(px.h, img.height - px.y))), level);
     fs.mkdirSync(path.dirname(cache), { recursive: true });
     fs.writeFileSync(cache, out.jpeg);
-    return { media: m.id, from: src.id, ...out, url };
+    return { media: m.id, from: src.id, ...out, url, clip: clipMark(clip) };
 }
 /** The image of a document the user gave (an input), when it is one: JPEG or PNG on this computer. */
 function inputImage(tree, id) {
@@ -90,14 +95,14 @@ export function renderInput(tree, id, level = LEVELS[1], cachedOnly = false) {
         const jpeg = fs.readFileSync(cache);
         const size = imageSize(jpeg);
         if (size)
-            return { media: found.input.id, from: found.input.id, jpeg, ...size };
+            return { media: found.input.id, from: found.input.id, jpeg, ...size, clip: INPUT_MARK };
     }
     if (cachedOnly)
         return LATER;
     const out = finish(decodeImage(fs.readFileSync(found.file)), level);
     fs.mkdirSync(path.dirname(cache), { recursive: true });
     fs.writeFileSync(cache, out.jpeg);
-    return { media: found.input.id, from: found.input.id, ...out };
+    return { media: found.input.id, from: found.input.id, ...out, clip: INPUT_MARK };
 }
 /** The same excerpt at a lower level, made from the excerpt itself (quick: no scan is opened again). */
 function lower(e, level) {
@@ -217,3 +222,46 @@ export function planExcerpts(tree, shared, opts) {
 export function dataUrl(e) {
     return `data:image/jpeg;base64,${Buffer.from(e.jpeg).toString("base64")}`;
 }
+/** The margin round an excerpt opened in full: the lines round the entry stay in view. */
+const FULL_MARGIN = 0.1;
+/**
+ * One excerpt of a source (by its mark) as sharp as the research has it — the region with more round it, from the
+ * sharpest image of that place, not made smaller (a strom-research://excerpt link from the Strom app, which keeps
+ * them small). A document the user gave: the file itself. Made once, in .strom/excerpts.
+ */
+export function fullExcerpt(tree, shared, s, mark) {
+    if (mark === INPUT_MARK) {
+        const found = !s.clips?.length ? inputImage(tree, s.input) : undefined;
+        return found ? { file: found.file } : { missing: "clip" };
+    }
+    const clip = s.clips?.find((c) => clipMark(c) === mark);
+    if (!clip)
+        return { missing: "clip" };
+    const all = tree.list("media");
+    const m = all.find((x) => x.id === clip.media);
+    if (!m)
+        return { missing: "clip" };
+    const pad = FULL_MARGIN * Math.max(clip.region.w, clip.region.h);
+    const f = (n) => Math.min(1, Math.max(0, n));
+    const x = f(clip.region.x - pad);
+    const y = f(clip.region.y - pad);
+    const wanted = { x, y, w: f(clip.region.x + clip.region.w + pad) - x, h: f(clip.region.y + clip.region.h + pad) - y };
+    const sharper = sharperPart(all, m, wanted);
+    const src = sharper?.part ?? m;
+    const region = sharper?.crop ?? wanted;
+    const file = path.join(shared, src.file);
+    if (!fs.existsSync(file)) {
+        const url = m.url ?? src.url;
+        return url ? { url } : { missing: "scan" };
+    }
+    const key = crypto.createHash("sha256").update(JSON.stringify({ sha: src.sha, region, full: 1 })).digest("hex").slice(0, 16);
+    const cache = path.join(tree.root, ".strom", "excerpts", `full-${s.id}-${src.id}-${key}.jpg`);
+    if (fs.existsSync(cache))
+        return { file: cache };
+    const img = decodeImage(fs.readFileSync(file));
+    const px = { x: Math.round(region.x * img.width), y: Math.round(region.y * img.height), w: Math.round(region.w * img.width), h: Math.round(region.h * img.height) };
+    const cut = crop(img, px.x, px.y, Math.max(1, Math.min(px.w, img.width - px.x)), Math.max(1, Math.min(px.h, img.height - px.y)));
+    fs.mkdirSync(path.dirname(cache), { recursive: true });
+    fs.writeFileSync(cache, encodeImage(cut, "jpeg", 92));
+    return { file: cache };
+}

package/dist/core/links.js

@@ -0,0 +1,357 @@
+// Links from the Strom app: strom-research://send?tree=… and
+// strom-research://excerpt?tree=…&source=…&clip=… (the app's spec
+// docs/ZADANI_VYZKUM_ODKAZY_Z_APLIKACE.md in the Strom repository). A web page
+// may not start a program on the computer — only through a scheme of links the
+// program registered with the system, and the browser asks first. strom
+// registers it for this user alone, no admin rights, on the user's yes (the
+// wizard, strom doctor --fix, strom link on):
+//
+//   macOS    a small AppleScript applet ~/Applications/Strom Research.app —
+//            the system hands a link over as an Apple Event, never as an argument
+//   Windows  HKCU\Software\Classes\strom-research, straight to strom's Node
+//            (never through cmd, which would read the link again: %, &, ")
+//   Linux    a .desktop entry, the default for x-scheme-handler/strom-research
+//
+// Any page can open such a link, so what it carries is never trusted: strom
+// checks each part's shape, writes nothing without the user's word in the
+// terminal, and an unknown action, research or excerpt is only said.
+// The app learns that links work from strom itself (the bridge's /status,
+// the GEDCOM it serves): only while the scheme here leads to this strom.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { userHome } from "./paths.js";
+import { stromLauncher } from "./self.js";
+import { ICON } from "./shortcut.js";
+export const LINK_SCHEME = "strom-research";
+/**
+ * What the links strom understands do: send the edited tree back, open an excerpt in full, send the 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.
+ */
+export const LINK_ACTIONS = ["send", "excerpt", "app", "open", "chat", "task", "review", "research", "new", "update", "sessions", "conflict", "story", "sync-undo", "setup"];
+/** 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 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;
+const SOURCE = /^S\d{1,9}$/;
+const PERSON = /^P\d{1,9}$/;
+const TASK = /^T\d{1,9}$/;
+const CONFLICT = /^X\d{1,9}$/;
+const INPUT = /^I\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. */
+export const CLIP_MARK = /^[A-Za-z0-9-]{1,32}$/;
+/** Why a link was not taken: said to the user, never acted on. */
+export class LinkError extends Error {
+}
+/** One of fixed values, the default when none is given; anything else is a LinkError. */
+function oneOf(q, name, values, fallback) {
+    const v = q.get(name) ?? fallback;
+    if (v === undefined || !values.includes(v))
+        throw new LinkError(`unknown ${name} "${(v ?? "").slice(0, 32)}"`);
+    return v;
+}
+/** An ID of a kind (P…, T…): upper-cased, checked; none when not given and not needed. */
+function idOf(q, name, shape, needed) {
+    if (!q.has(name) && !needed)
+        return undefined;
+    const v = (q.get(name) ?? "").toUpperCase();
+    if (!shape.test(v))
+        throw new LinkError(`no ${name} named`);
+    return v;
+}
+/** A link, checked part by part; anything else is a LinkError. No link at all (the applet opened by itself): the menu. */
+export function parseLink(text) {
+    if (!text?.trim())
+        return { action: "menu" };
+    const raw = text.trim();
+    if (raw.length > 2048)
+        throw new LinkError("too long");
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new LinkError("not a link");
+    }
+    if (url.protocol !== `${LINK_SCHEME}:`)
+        throw new LinkError(`not a ${LINK_SCHEME} link`);
+    // strom-research://send?… — and the forms systems make of it: …//send/?…, strom-research:send?…
+    const action = (url.host || url.pathname).replace(/^\/+|\/+$/g, "").toLowerCase();
+    const q = url.searchParams;
+    // the one link without a research: a tree of the app becomes one
+    if (action === "new") {
+        const app = q.get("app") ?? "";
+        if (!APP_TOKEN.test(app))
+            throw new LinkError("no tree of the app named");
+        return { action, app };
+    }
+    const tree = q.get("tree") ?? "";
+    if (!UUID.test(tree))
+        throw new LinkError("no research named");
+    const id = tree.toLowerCase();
+    const person = idOf(q, "person", PERSON, false);
+    switch (action) {
+        case "send":
+        case "app":
+        case "open":
+        case "update":
+        case "sessions":
+        case "setup":
+            return { action, tree: id };
+        case "excerpt": {
+            const source = (q.get("source") ?? "").toUpperCase();
+            const clip = q.get("clip") ?? "";
+            if (!SOURCE.test(source) || !CLIP_MARK.test(clip))
+                throw new LinkError("no excerpt named");
+            return { action, tree: id, source, clip };
+        }
+        case "chat":
+            return { action, tree: id, ...(person ? { person } : {}) };
+        case "task": {
+            const task = idOf(q, "task", TASK, true);
+            return { action, tree: id, task, ...(q.has("do") ? { do: oneOf(q, "do", LINK_TASK_DOS) } : {}) };
+        }
+        case "review":
+        case "research":
+        case "story": {
+            if (!person)
+                throw new LinkError("no person named");
+            if (action === "review")
+                return { action, tree: id, person, scope: oneOf(q, "scope", LINK_SCOPES, "person") };
+            if (action === "research")
+                return { action, tree: id, person, direction: oneOf(q, "direction", LINK_DIRECTIONS, "ancestors") };
+            return { action, tree: id, person, do: oneOf(q, "do", ["final"]) };
+        }
+        case "conflict":
+            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) };
+    }
+    throw new LinkError(`unknown action "${action.slice(0, 32)}"`);
+}
+/** A link written again from what was checked in it: only its known parts, in one form (handed to a new terminal). */
+export function linkText(link) {
+    const { action, ...parts } = link;
+    const q = new URLSearchParams(Object.entries(parts).filter((e) => typeof e[1] === "string"));
+    return `${LINK_SCHEME}://${action}?${q}`;
+}
+/**
+ * What the handler runs: this strom's Node and script, "link open", the link. A strom of its own settings folder
+ * (STROM_CONFIG_DIR) gives its links that folder too (macOS, Linux: through env) — the same researches answer them.
+ */
+function handlerArgv(env = {}, platform = process.platform) {
+    const { command, args } = stromLauncher();
+    const own = env.STROM_CONFIG_DIR && platform !== "win32" ? ["/usr/bin/env", `STROM_CONFIG_DIR=${env.STROM_CONFIG_DIR}`] : [];
+    return [...own, command, ...args, "link", "open"];
+}
+/** macOS: the applet strom makes. */
+export function macApp(env) {
+    return path.join(userHome(env), "Applications", "Strom Research.app");
+}
+/** Linux: the entry that takes the links (the shortcut's own is strom-research.desktop). */
+export const LINUX_ENTRY = "strom-research-link.desktop";
+function linuxEntry(env) {
+    return path.join(env.XDG_DATA_HOME ?? path.join(userHome(env), ".local", "share"), "applications", LINUX_ENTRY);
+}
+const WIN_KEY = `HKCU\\Software\\Classes\\${LINK_SCHEME}`;
+/** AppleScript string literal. */
+function appleString(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** A POSIX shell word. */
+function shellWord(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The applet's script: a link comes as an Apple Event (open location); opened by itself, the menu. strom runs in
+ * the background, so the applet ends at once; what strom has to say it says in a window or a terminal of its own.
+ */
+export function macScript(argv) {
+    const run = argv.map(shellWord).join(" ");
+    return [
+        "on open location theURL",
+        `\tdo shell script ${appleString(`${run} `)} & quoted form of theURL & ${appleString(" >/dev/null 2>&1 &")}`,
+        "end open location",
+        "on run",
+        `\tdo shell script ${appleString(`${run} >/dev/null 2>&1 &`)}`,
+        "end run",
+        "",
+    ].join("\n");
+}
+/** Windows: the command in the registry — strom's Node itself, the link one argument. */
+export function windowsCommand(argv = handlerArgv({}, "win32")) {
+    return [...argv, "%1"].map((a) => `"${a}"`).join(" ");
+}
+/** A word of a .desktop Exec line, quoted as the spec says; "%" doubled. */
+function desktopWord(s) {
+    const quoted = /[\s"'\\$`<>~|&;*?#()]/.test(s) ? `"${s.replace(/([\\"`$])/g, "\\$1")}"` : s;
+    // …and a .desktop value escapes its backslashes once more
+    return quoted.replace(/\\/g, "\\\\").replace(/%/g, "%%");
+}
+export function linuxDesktopEntry(argv) {
+    return [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Name=Strom Research",
+        "NoDisplay=true",
+        `Exec=${argv.map(desktopWord).join(" ")} %u`,
+        `Icon=${ICON.png}`,
+        "Terminal=false",
+        `MimeType=x-scheme-handler/${LINK_SCHEME};`,
+        "",
+    ].join("\n");
+}
+const sys = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 30_000, windowsHide: true });
+    return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+};
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+/** The app the system opens a strom-research link with (macOS), or "". */
+function macHandlerPath(run) {
+    const js = `ObjC.import("AppKit");var u=$.NSWorkspace.sharedWorkspace.URLForApplicationToOpenURL($.NSURL.URLWithString("${LINK_SCHEME}://status"));u.isNil()?"":u.path.js`;
+    const r = run("osascript", ["-l", "JavaScript", "-e", js]);
+    return r.status === 0 ? r.stdout.trim() : "";
+}
+/** The mark inside strom's applet: what it runs (another strom's applet, or one of an older place, is not ours). */
+function macMark(app) {
+    return path.join(app, "Contents", "Resources", "strom-link.json");
+}
+/** Does the scheme lead to this strom? No system is asked from a test (STROM_NO_INSTALL). */
+export function linkHandlerState(env, platform = process.platform, run = sys) {
+    if (env.STROM_NO_INSTALL === "1" && run === sys)
+        return "none";
+    const argv = handlerArgv(env, platform);
+    if (platform === "darwin") {
+        const at = macHandlerPath(run);
+        if (!at)
+            return "none";
+        const app = macApp(env);
+        if (path.resolve(at) !== path.resolve(app))
+            return "other";
+        try {
+            return JSON.stringify(JSON.parse(fs.readFileSync(macMark(app), "utf8")).argv) === JSON.stringify(argv) ? "ours" : "other";
+        }
+        catch {
+            return "other";
+        }
+    }
+    if (platform === "win32") {
+        const r = run("reg.exe", ["query", `${WIN_KEY}\\shell\\open\\command`, "/ve"]);
+        if (r.status !== 0)
+            return "none";
+        const value = /REG_(?:EXPAND_)?SZ\s+(.*)$/m.exec(r.stdout)?.[1]?.trim();
+        return value === windowsCommand(argv) ? "ours" : value ? "other" : "none";
+    }
+    const r = run("xdg-mime", ["query", "default", `x-scheme-handler/${LINK_SCHEME}`]);
+    const entry = r.status === 0 ? r.stdout.trim() : "";
+    if (!entry)
+        return "none";
+    if (entry !== LINUX_ENTRY)
+        return "other";
+    try {
+        return fs.readFileSync(linuxEntry(env), "utf8") === linuxDesktopEntry(argv) ? "ours" : "other";
+    }
+    catch {
+        return "other";
+    }
+}
+/** The actions a link can do here: all of them while the scheme leads to this strom, else none. */
+export function linkActions(state) {
+    return state === "ours" ? [...LINK_ACTIONS] : [];
+}
+/** Register the scheme for this user (or register it again: this strom moved, was updated); true when it leads to this strom now. */
+export function registerLinks(env, platform = process.platform, run = sys) {
+    if (env.STROM_NO_INSTALL === "1" && run === sys)
+        return false;
+    const argv = handlerArgv(env, platform);
+    if (platform === "darwin") {
+        const app = macApp(env);
+        fs.mkdirSync(path.dirname(app), { recursive: true });
+        fs.rmSync(app, { recursive: true, force: true });
+        const script = path.join(path.dirname(app), ".strom-link.applescript");
+        fs.writeFileSync(script, macScript(argv));
+        const made = run("osacompile", ["-o", app, script]);
+        fs.rmSync(script, { force: true });
+        if (made.status !== 0)
+            return false;
+        const plist = path.join(app, "Contents", "Info.plist");
+        run("plutil", ["-replace", "CFBundleIdentifier", "-string", "info.stromapp.research.link", plist]);
+        run("plutil", ["-replace", "CFBundleName", "-string", "Strom Research", plist]);
+        run("plutil", ["-replace", "LSUIElement", "-bool", "true", plist]);
+        run("plutil", ["-replace", "CFBundleURLTypes", "-json", JSON.stringify([{ CFBundleURLName: "Strom Research", CFBundleURLSchemes: [LINK_SCHEME] }]), plist]);
+        // its icon: Strom Research's own
+        if (fs.existsSync(ICON.png))
+            run("sips", ["-s", "format", "icns", ICON.png, "--out", path.join(app, "Contents", "Resources", "applet.icns")]);
+        fs.writeFileSync(macMark(app), JSON.stringify({ argv }, null, 2));
+        // the applet's seal covers its Info.plist: sealed again, by itself (no one's certificate)
+        run("codesign", ["--force", "--sign", "-", app]);
+        run(LSREGISTER, ["-f", app]);
+        return linkHandlerState(env, platform, run) === "ours";
+    }
+    if (platform === "win32") {
+        const add = (key, args) => run("reg.exe", ["add", key, ...args, "/f"]).status === 0;
+        const ok = add(WIN_KEY, ["/ve", "/d", "URL:Strom Research"]) &&
+            add(WIN_KEY, ["/v", "URL Protocol", "/d", ""]) &&
+            add(`${WIN_KEY}\\DefaultIcon`, ["/ve", "/d", ICON.ico]) &&
+            add(`${WIN_KEY}\\shell\\open\\command`, ["/ve", "/d", windowsCommand(argv)]);
+        return ok && linkHandlerState(env, platform, run) === "ours";
+    }
+    const file = linuxEntry(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, linuxDesktopEntry(argv));
+    run("xdg-mime", ["default", LINUX_ENTRY, `x-scheme-handler/${LINK_SCHEME}`]);
+    run("update-desktop-database", [path.dirname(file)]);
+    return linkHandlerState(env, platform, run) === "ours";
+}
+/** What strom put there for the links (for strom uninstall): the applet, the registry key or the entry. */
+export function linkFiles(env, platform = process.platform, run = sys) {
+    if (platform === "darwin")
+        return fs.existsSync(macApp(env)) && fs.existsSync(macMark(macApp(env))) ? [macApp(env)] : [];
+    if (platform === "win32") {
+        if (env.STROM_NO_INSTALL === "1" && run === sys)
+            return [];
+        const r = run("reg.exe", ["query", `${WIN_KEY}\\shell\\open\\command`, "/ve"]);
+        return r.status === 0 && /link"? "?open/.test(r.stdout) ? [WIN_KEY] : [];
+    }
+    return fs.existsSync(linuxEntry(env)) ? [linuxEntry(env)] : [];
+}
+/** Take the scheme off again (strom link off, strom uninstall); true when nothing of strom's is left for it. */
+export function unregisterLinks(env, platform = process.platform, run = sys) {
+    if (platform === "darwin") {
+        const app = macApp(env);
+        if (fs.existsSync(macMark(app))) {
+            run(LSREGISTER, ["-u", app]);
+            fs.rmSync(app, { recursive: true, force: true });
+        }
+        return !fs.existsSync(app) || !fs.existsSync(macMark(app));
+    }
+    if (platform === "win32") {
+        if (!linkFiles(env, platform, run).length)
+            return true;
+        return run("reg.exe", ["delete", WIN_KEY, "/f"]).status === 0;
+    }
+    const file = linuxEntry(env);
+    fs.rmSync(file, { force: true });
+    // the default the entry was given goes with it
+    const list = path.join(env.XDG_CONFIG_HOME ?? path.join(userHome(env), ".config"), "mimeapps.list");
+    try {
+        const text = fs.readFileSync(list, "utf8");
+        const kept = text.split("\n").filter((l) => !(l.startsWith(`x-scheme-handler/${LINK_SCHEME}=`) && l.includes(LINUX_ENTRY)));
+        if (kept.length !== text.split("\n").length)
+            fs.writeFileSync(list, kept.join("\n"));
+    }
+    catch {
+        // no list
+    }
+    return true;
+}

package/dist/core/live.js

@@ -25,14 +25,19 @@ import { spawn, spawnSync } from "node:child_process";
 import { Tree, VERSION } from "./tree.js";
 import { exportGedcom } from "../gedcom/export.js";
 import { excerptSettings, planExcerpts } from "./excerpt.js";
-import { noteNothingSent, receiveTree, SYNC_MAX_BYTES } from "./sync.js";
+import { noteAdoptFailed, noteNothingSent, pendingAdoption, receiveAdopted, receiveTree, SYNC_MAX_BYTES } from "./sync.js";
 import { ui } from "../cli/ui.js";
 /** New images for the app, made for at most so long when the tree changed (the rest the next time). */
 const LIVE_IMAGES_MS = 20_000;
 import { liveWorkers } from "./workers.js";
-import { openSessions } from "./session.js";
+import { monthSpend, openSessions } from "./session.js";
+import { rankTasks } from "./queue.js";
+import { humanTask } from "../cli/human.js";
+import { knownNewerVersion } from "./update.js";
 import { gitProgram } from "./git.js";
-import { isStromAppOrigin } from "./stromapp.js";
+import { appOpensLinks, isStromAppOrigin } from "./stromapp.js";
+import { Settings } from "./config.js";
+import { linkActions, linkHandlerState } from "./links.js";
 import { stromLauncher } from "./self.js";
 /** Where a running bridge of a tree is noted. */
 export function liveFile(root) {
@@ -125,10 +130,43 @@ function working(root, tree) {
         return { who: w.label, since: w.since, ...(s ? { session: s.id, ...(s.task ? { task: task ? `${task.id} ${task.what}` : s.task } : {}) } : {}) };
     });
 }
+/** How long what the system says of the links is taken as true (asking it costs a program started). */
+const LINKS_FRESH_MS = 60_000;
+let linksSeen;
+/** The strom-research:// links this computer takes: said to the app only while the scheme leads to this strom. */
+function links(env) {
+    if (!linksSeen || Date.now() - linksSeen.at > LINKS_FRESH_MS)
+        linksSeen = { at: Date.now(), actions: linkActions(linkHandlerState(env)) };
+    return linksSeen.actions;
+}
+/** At most so many tasks of the queue the app is told (the rest counted): what comes next, then what was put aside. */
+const QUEUE_NEXT = 14;
+const QUEUE_PARKED = 6;
+/** The agent's queue in its order, for the user (records by their names), and how many more there are. */
+function queue(tree, settings) {
+    const lang = tree.lang;
+    const next = rankTasks(tree, tree.list("task"), settings.strategy(tree.config)).map((r) => r.task);
+    const parked = tree.list("task").filter((t) => t.state === "parked");
+    const item = (state) => (t) => ({ id: t.id, text: humanTask(tree, t.what, lang), state });
+    const shown = [...next.slice(0, QUEUE_NEXT).map(item("next")), ...parked.slice(0, QUEUE_PARKED).map(item("parked"))];
+    return { queue: shown, queueMore: next.length + parked.length - shown.length };
+}
+/** The last tree the Strom app sent (through the bridge) that the research took and has not taken back. */
+function lastIntake(tree) {
+    const last = tree
+        .list("input")
+        .filter((i) => i.sync && !i.sync.undone && i.sync.applied.length && i.name.startsWith("strom-app-"))
+        .sort((a, b) => a.created.localeCompare(b.created))
+        .pop();
+    return last ? { id: last.id, at: last.created } : undefined;
+}
 /** What the app shows beside the tree. */
 function status(root, env) {
     const tree = Tree.open(root, env);
+    const settings = new Settings(env, {});
     const waiting = tree.list("task").filter((t) => t.state === "waiting");
+    const newer = knownNewerVersion(settings, env);
+    const intake = lastIntake(tree);
     return {
         strom: VERSION,
         tree: { id: tree.config.id, name: tree.config.name, lang: tree.lang },
@@ -138,7 +176,13 @@ function status(root, env) {
         researches: tree.list("research").map((r) => ({ id: r.id, name: r.name, state: r.state })),
         working: working(root, tree),
         open: openSessions(tree).map((s) => ({ id: s.id, task: s.task, started: s.started })),
-        waiting: waiting.map((t) => ({ id: t.id, what: t.what, on: t.waitingOn ?? "" })),
+        // since when it waits: its last change is the one that made it wait
+        waiting: waiting.map((t) => ({ id: t.id, what: t.what, on: t.waitingOn ?? "", at: t.updated })),
+        links: links(env),
+        ...queue(tree, settings),
+        ...(newer ? { update: { version: newer } } : {}),
+        spend: { ...monthSpend(tree, new Date().toISOString().slice(0, 7)), currency: "USD" },
+        ...(intake ? { lastIntake: intake } : {}),
     };
 }
 /** Run the bridge of the tree here, until idle or stopped. */
@@ -175,22 +219,40 @@ export function serveLive(root, env) {
             nothing(req, res, origin);
             return;
         }
+        if (req.method === "POST" && t === token && what === "adopt") {
+            receive(req, res, origin, "adopt");
+            return;
+        }
         if (req.method !== "GET" || t !== token) {
             res.writeHead(404).end();
             return;
         }
         try {
-            if (what === "status") {
+            if (what === "adopt") {
+                // the new research started from the app's link: which tree of the app it waits for (its mark), its name
+                const mark = pendingAdoption(root);
+                const tree = Tree.open(root, env);
+                const body = mark ? { token: mark, name: tree.config.name, tree: tree.config.id } : { error: "this research waits for no tree" };
+                res.writeHead(mark ? 200 : 404, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(body));
+            }
+            else if (what === "status") {
                 res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(status(root, env)));
             }
             else if (what === "tree.ged" || what === "images.ged") {
                 const h = head(root);
-                if (!ged || ged.head !== h) {
+                if (!ged || ged.head !== h || ged.links !== (appOpensLinks(new Settings(env, {})) ? links(env).join(" ") : "")) {
                     const tree = Tree.open(root, env);
                     // the images from the cache; new ones made for a while at most (the rest the next time the tree changes)
                     const set = excerptSettings(tree);
                     const images = set ? planExcerpts(tree, set.shared, { quality: set.quality, for: set.for, maxBytes: set.mb * 1024 * 1024, budgetMs: LIVE_IMAGES_MS }) : undefined;
-                    ged = { head: h, text: exportGedcom(tree, { for: "strom", ...(h ? { head: h } : {}), ...(images ? { excerpts: images.of } : {}) }).text };
+                    // an app that opens strom-research:// links: each excerpt's mark, and the links this computer takes
+                    const opens = appOpensLinks(new Settings(env, {}));
+                    const offered = opens ? links(env) : [];
+                    ged = {
+                        head: h,
+                        links: offered.join(" "),
+                        text: exportGedcom(tree, { for: "strom", ...(h ? { head: h } : {}), ...(images ? { excerpts: images.of } : {}), ...(opens ? { clips: true, research: true } : {}), ...(offered.length ? { links: offered } : {}) }).text,
+                    };
                 }
                 res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "X-Strom-Head": h }).end(ged.text);
             }
@@ -208,7 +270,7 @@ export function serveLive(root, env) {
         }
     });
     /** The user's tree from the app: only from its pages, only so large; the answer in the research's language. */
-    const receive = (req, res, origin) => {
+    const receive = (req, res, origin, as = "sync") => {
         const reply = (code, body) => res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(body));
         const lang = () => {
             try {
@@ -238,11 +300,21 @@ export function serveLive(root, env) {
                 return;
             }
             try {
-                const got = receiveTree(root, env, Buffer.concat(chunks).toString("utf8"));
+                const text = Buffer.concat(chunks).toString("utf8");
+                if (as === "adopt") {
+                    // kept for the research in the terminal to take in; the app links its tree to this research
+                    receiveAdopted(root, text);
+                    reply(200, { tree: Tree.open(root, env).config.id, head: head(root) ?? "" });
+                    return;
+                }
+                const got = receiveTree(root, env, text);
                 reply(200, { ok: true, changes: got.changes, file: path.basename(got.file) });
             }
             catch (e) {
                 const m = e.message;
+                // the new research in the terminal waits for it: told, it stops waiting
+                if (as === "adopt" && pendingAdoption(root))
+                    noteAdoptFailed(root, /empty|no people/.test(m) ? "empty" : "other");
                 const key = /another research/.test(m) ? "ui.sync.bridge.other" : /does not look like/.test(m) ? "ui.sync.bridge.foreign" : /empty|no people|not a GEDCOM/.test(m) ? "ui.sync.bridge.empty" : undefined;
                 reply(400, { error: key ? ui(lang(), key) : m });
             }

package/dist/core/schema.js

@@ -98,6 +98,7 @@ export const SCHEMAS = {
     },
     conflict: {
         title: S({ req: true, max: 200 }),
+        fact: S({ max: 8 }),
         subject: RS(ANY_SUBJECT, 1),
         claims: { t: "array", req: true, min: 2, of: { source: R("source"), value: S({ req: true, max: 500 }), note: S({ max: 500 }) } },
         state: S({ req: true, enum: ["open", "resolved"] }),

package/dist/core/session.js

@@ -157,3 +157,9 @@ export function recentSessions(tree, research, n = 2) {
         .sort((a, b) => (b.ended ?? b.updated).localeCompare(a.ended ?? a.updated))
         .slice(0, n);
 }
+/** What the agent's sessions of a month ("2026-09", by when they started) cost: how many, the dollars known (a session stopped before it said: its known part). */
+export function monthSpend(tree, month) {
+    const of = tree.list("session").filter((s) => s.started.slice(0, 7) === month);
+    const amount = of.reduce((sum, s) => sum + (s.metrics?.costUsd ?? 0), 0);
+    return { month, sessions: of.length, amount: Math.round(amount * 100) / 100 };
+}