@tiagojct/subsub 0.20.0 → 0.22.0

package/dist/subsub.js

@@ -13,9 +13,9 @@
  * The Python servers start in session_start (not in the factory) and stop in
  * session_shutdown. Tools are registered once and use the current bridge.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
 import { expand, findUv, FREE_MODELS, loadConfig, parseEnvFile, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
@@ -28,7 +28,13 @@ import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missing
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.js";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.js";
-import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
+import { headerLines, LIBRARIAN_THEME, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
+import { footerLines, toolRenderers, usageTotals } from "./chrome.js";
+import { ApprovalView } from "./dialogs.js";
+import { allowedFile, listNotes, OPENABLE, openFile } from "./files.js";
+import { LibraryView, NotesView } from "./screens.js";
+import { glyphs, paintFromTheme, workingFrames } from "./skin.js";
+import { loadWords, toolWord } from "./words.js";
 import { systemAddition } from "./prompt.js";
 import { logUsage } from "./usage.js";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason, outboundProblem } from "./roles.js";
@@ -124,11 +130,21 @@ export async function createSubsub(pi, deps = {}) {
     let scheme;
     let modelId = "no model";
     let headerTui;
+    let footerTui;
+    /** True once the session started with the look on; the tool renderers are asked before a context exists. */
+    let lookActive = false;
+    let words;
+    const redraw = () => {
+        headerTui?.requestRender();
+        footerTui?.requestRender();
+    };
     const library = { zotero: "checking" };
     const quote = cfg.quotes === false ? undefined : QUOTES[Math.floor(Math.random() * QUOTES.length)];
     const lookOn = (ctx) => standalone && cfg.look !== false && ctx.mode === "tui";
     /** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
     const webView = process.env.SUBSUB_WEB === "1";
+    /** The state of the library goes to the client as a status text: for the web view and for the full-screen terminal client (subsub tui). */
+    const sideChannel = webView || process.env.SUBSUB_TUI === "1";
     let lastError;
     /** The last provider or tool error of the session, for /feedback. */
     let recentError;
@@ -139,7 +155,7 @@ export async function createSubsub(pi, deps = {}) {
     let webCtx;
     function emitWeb() {
         const ctx = webCtx;
-        if (!webView || !ctx || ctx.mode !== "rpc")
+        if (!sideChannel || !ctx || ctx.mode !== "rpc")
             return;
         const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
         const state = {
@@ -163,15 +179,110 @@ export async function createSubsub(pi, deps = {}) {
         if (!lookOn(ctx) || cfg.themes === false)
             return;
         scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
-        const name = themeName(scheme, cfg.themes || undefined);
+        // The Librarian has its own plate (madder); a theme named in the settings applies to both modes unless themes.librarian says otherwise.
+        const base = mode === "librarian" ? (cfg.themesLibrarian ?? cfg.themes ?? LIBRARIAN_THEME) : cfg.themes || undefined;
+        const name = themeName(scheme, base, ctx.ui.theme.getColorMode?.());
         const theme = name ? ctx.ui.getTheme(name) : undefined;
         // A Theme object (not a name) changes the theme for this run only; the saved setting stays.
         if (theme)
             ctx.ui.setTheme(theme);
+        // The working indicator takes the accent of the mode.
+        const mark = paintFromTheme(ctx.ui.theme).mark;
+        ctx.ui.setWorkingIndicator?.({ frames: workingFrames(glyphs(), Boolean(process.env.SUBSUB_REDUCE_MOTION && process.env.SUBSUB_REDUCE_MOTION !== "0")).map(mark), intervalMs: 160 });
+    }
+    /**
+     * Ask the user to approve a change. With the look on, the preview opens as an overlay with its own keys (see dialogs.ts); otherwise, and over RPC,
+     * it is pi's confirm dialog. Only a yes counts: anything else, including an overlay that cannot open, is a no.
+     */
+    async function approve(ctx, title, body) {
+        if (lookOn(ctx) && typeof ctx.ui.custom === "function") {
+            const answer = await ctx.ui.custom((tui, theme, _keys, done) => new ApprovalView({ title, body, lang, paint: paintFromTheme(theme), glyphs: glyphs(), done, rows: () => tui.terminal?.rows ?? 24, redraw: () => tui.requestRender() }), { overlay: true, overlayOptions: { width: "92%", minWidth: 40, maxHeight: "92%", anchor: "center", margin: 1 } });
+            return answer === true;
+        }
+        return (await ctx.ui.confirm(title, body)) === true;
+    }
+    /** The notes and library screens cover the terminal: the conversation is behind them and comes back when they close. */
+    const OVERLAY = { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 } };
+    /** True when the terminal look can show a screen of its own; otherwise says where the same thing is. */
+    function screenOk(ctx) {
+        if (lookOn(ctx) && typeof ctx.ui.custom === "function")
+            return true;
+        ctx.ui.notify(L("Sub-Sub: this screen is part of the terminal look. In subsub web, use the Notes button and the library search.", "Sub-Sub: este ecrã faz parte do aspeto do terminal. Em subsub web, use o botão Notas e a pesquisa na biblioteca."), "info");
+        return false;
+    }
+    /** /notes: the notes in the Sub-Sub folder, newest first; the note under the cursor shows beside the list. */
+    async function openNotes(ctx) {
+        if (!screenOk(ctx))
+            return;
+        const root = cfg.vault ?? ctx.cwd;
+        const notes = listNotes(root);
+        const { Markdown } = await import("@earendil-works/pi-tui");
+        const { getMarkdownTheme } = await import("@earendil-works/pi-coding-agent");
+        await ctx.ui.custom((tui, theme, _keys, done) => new NotesView({
+            notes,
+            read: (path) => {
+                const file = allowedFile(path, root, cfg.vault);
+                return file && statSync(file).size < 2_000_000 ? readFileSync(file, "utf8") : "";
+            },
+            markdown: (text, width) => new Markdown(text, 1, 0, getMarkdownTheme()).render(width),
+            open: (path) => {
+                const file = allowedFile(path, root, cfg.vault);
+                if (file && OPENABLE.has(extname(file).toLowerCase()))
+                    openFile(file, cfg.vault);
+            },
+            done: () => done(),
+            lang,
+            paint: paintFromTheme(theme),
+            glyphs: glyphs(),
+            rows: () => tui.terminal?.rows ?? 24,
+            redraw: () => tui.requestRender(),
+        }), OVERLAY);
+    }
+    /** /library: search as you type; Enter puts /read <item> in the box (the Librarian gets the key), ctrl+n puts /lit-note <item>. */
+    async function openLibrary(ctx) {
+        if (!screenOk(ctx))
+            return;
+        const ref = (it) => it.citekey || it.key;
+        await ctx.ui.custom((tui, theme, _keys, done) => new LibraryView({
+            search: async (query) => {
+                const r = await current().call("zotero_find_items", { query, limit: 25 });
+                if (r.isError)
+                    throw new Error(r.text);
+                return (r.data?.items ?? []).filter((it) => it && it.key);
+            },
+            choose: (it) => {
+                ctx.ui.setEditorText(mode === "researcher" ? `/read ${ref(it)}` : ref(it));
+                done();
+            },
+            note: (it) => {
+                ctx.ui.setEditorText(`/lit-note ${ref(it)}`);
+                done();
+            },
+            done: () => done(),
+            lang,
+            paint: paintFromTheme(theme),
+            glyphs: glyphs(),
+            researcher: mode === "researcher",
+            rows: () => tui.terminal?.rows ?? 24,
+            redraw: () => tui.requestRender(),
+        }), OVERLAY);
+    }
+    /** /actions: the buttons of the web view as a list; the choice goes into the box, so the user adds what is missing and presses Enter. */
+    async function openActions(ctx) {
+        const w = words ?? (await loadWords());
+        const list = [...(mode === "researcher" ? w.ACTIONS.research : []), ...w.ACTIONS.library].filter((a) => a.needs !== "starbuck" || starbuckEnabled(cfg));
+        const labels = list.map((a) => `${a[lang]}   /${a.cmd}`);
+        const pick = await ctx.ui.select(L("Actions", "Ações"), labels);
+        const a = list[labels.indexOf(pick ?? "")];
+        if (a)
+            ctx.ui.setEditorText(a.cmd.endsWith(" ") ? `/${a.cmd}` : `/${a.cmd} `);
     }
     function paintFor(ctx) {
         return (text) => ctx.mode === "tui"
-            ? paintPreview(text, (x) => ctx.ui.theme.fg("success", x), (x) => ctx.ui.theme.fg("error", x), (x) => ctx.ui.theme.fg("text", x))
+            ? (() => {
+                const p = paintFromTheme(ctx.ui.theme);
+                return paintPreview(text, p.ok, p.strike, p.text);
+            })()
             : text;
     }
     async function refreshLibrary() {
@@ -190,7 +301,7 @@ export async function createSubsub(pi, deps = {}) {
         catch {
             library.zotero = "down";
         }
-        headerTui?.requestRender();
+        redraw();
         emitWeb();
     }
     function setHeader(ctx) {
@@ -209,26 +320,45 @@ export async function createSubsub(pi, deps = {}) {
                         library,
                         quote,
                         width,
-                        paint: {
-                            mark: (x) => th.fg("accent", x),
-                            text: (x) => th.fg("text", x),
-                            muted: (x) => th.fg("muted", x),
-                            dim: (x) => th.fg("dim", x),
-                            warn: (x) => th.fg("warning", x),
-                        },
+                        paint: paintFromTheme(th),
+                        lang,
+                        glyphs: glyphs(),
                     });
                 },
                 invalidate() { },
             };
         });
     }
+    function setFooter(ctx) {
+        if (!lookOn(ctx))
+            return;
+        ctx.ui.setFooter((tui) => {
+            footerTui = tui;
+            return {
+                render: (width) => {
+                    try {
+                        const usage = ctx.getContextUsage();
+                        const totals = usageTotals(ctx.sessionManager.getEntries());
+                        return footerLines({ mode, lang, library, model: modelId, percent: usage?.percent ?? null, window: usage?.contextWindow, tokens: totals.tokens, cost: totals.cost, down: bridge ? Object.keys(bridge.errors) : [] }, width, paintFromTheme(ctx.ui.theme), glyphs());
+                    }
+                    catch {
+                        return []; // the context is gone after shutdown
+                    }
+                },
+                invalidate() { },
+                dispose() {
+                    footerTui = undefined;
+                },
+            };
+        });
+    }
     function status(ctx) {
         modelId = ctx.model ? `${ctx.model.id}` : "no model";
         const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
         ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
         if (standalone)
             ctx.ui.setTitle(`Sub-Sub: ${mode}`);
-        headerTui?.requestRender();
+        redraw();
         webCtx = ctx;
         emitWeb();
     }
@@ -252,6 +382,7 @@ export async function createSubsub(pi, deps = {}) {
         }
         if (remember)
             pi.appendEntry(MODE_ENTRY, { mode });
+        applyTheme(ctx);
         status(ctx);
     }
     pi.on("session_start", async (_event, ctx) => {
@@ -279,14 +410,17 @@ export async function createSubsub(pi, deps = {}) {
         // Judge light or dark before Sub-Sub changes the theme.
         if (lookOn(ctx))
             scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
-        applyTheme(ctx);
+        lookActive = lookOn(ctx);
+        if (lookActive)
+            words = await loadWords().catch(() => undefined);
         await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
         logUsage(cfg.usageLog, { ev: "session", mode, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
         if (lookOn(ctx)) {
             setHeader(ctx);
+            setFooter(ctx);
             void refreshLibrary();
         }
-        else if (webView) {
+        else if (sideChannel) {
             void refreshLibrary();
         }
         if (!ctx.model && !webView)
@@ -319,6 +453,18 @@ export async function createSubsub(pi, deps = {}) {
             await applyMode(ctx, m, false, false);
     });
     pi.on("model_select", async (_event, ctx) => status(ctx));
+    // Plain-word tool lines for Sub-Sub's own tools (the look only); pi's tools keep pi's rows.
+    const rows = toolRenderers({ word: (name) => (words ? toolWord(words, lang, name) : name), lang, glyphs, paint: paintFromTheme });
+    pi.registerToolRenderer?.((toolName, next) => (lookActive && SERVER_PREFIXES.some((p) => toolName.startsWith(p)) ? rows(toolName) : next()));
+    pi.on("tool_execution_start", async (event, ctx) => {
+        if (lookActive && words && !event.parentToolCallId)
+            ctx.ui.setWorkingMessage?.(`${toolWord(words, lang, event.toolName)}...`);
+    });
+    pi.on("tool_execution_end", async (_event, ctx) => {
+        if (lookActive)
+            ctx.ui.setWorkingMessage?.();
+    });
+    pi.on("turn_end", async () => redraw());
     // A provider error in plain words (quota, busy, blocked, key); the web view words its own.
     pi.on("message_end", async (event, ctx) => {
         const m = event.message;
@@ -433,7 +579,7 @@ export async function createSubsub(pi, deps = {}) {
                 return undefined;
             if (!ctx.hasUI)
                 return { block: true, reason: `Writing ${target} needs ${user}'s approval: ${verdict.why}.` };
-            const ok = await ctx.ui.confirm(`Sub-Sub: ${name} ${target}?`, L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
+            const ok = await approve(ctx, `Sub-Sub: ${name} ${target}?`, L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
             return ok ? undefined : { block: true, reason: `${user} did not allow writing to that file.` };
         }
         if (!ctx.hasUI) {
@@ -446,7 +592,7 @@ export async function createSubsub(pi, deps = {}) {
                 if (!verdict.ok && /protected|hidden/.test(verdict.why))
                     return { block: true, reason: `Sub-Sub does not write there: ${verdict.why}.` };
             }
-            const ok = await ctx.ui.confirm(L(`Sub-Sub: run ${name}?`, `Sub-Sub: executar ${name}?`), describeArgs(input));
+            const ok = await approve(ctx, L(`Sub-Sub: run ${name}?`, `Sub-Sub: executar ${name}?`), describeArgs(input));
             return ok ? undefined : { block: true, reason: `${user} did not approve. Ask what to change.` };
         }
         // kind === "preview": the server computes the change first, then the user decides.
@@ -472,7 +618,7 @@ export async function createSubsub(pi, deps = {}) {
         // The dialog may stay open for minutes. Before applying, compute the preview again: if the
         // library changed meanwhile (an edit in Zotero, new items), show the new preview instead.
         for (let round = 0; round < 3; round++) {
-            const ok = await ctx.ui.confirm(round ? `${title} ${L("(the library changed; this is the new preview)", "(a biblioteca mudou; esta é a nova pré-visualização)")}` : title, paintFor(ctx)(shown));
+            const ok = await approve(ctx, round ? `${title} ${L("(the library changed; this is the new preview)", "(a biblioteca mudou; esta é a nova pré-visualização)")}` : title, paintFor(ctx)(shown));
             logUsage(cfg.usageLog, { ev: "change", tool: name, approved: ok });
             if (!ok)
                 return { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
@@ -586,7 +732,7 @@ export async function createSubsub(pi, deps = {}) {
         }
         if (!ctx.hasUI)
             return { block: true, reason: `Writing a Starbuck report to ${dir} needs ${user}'s approval: ${verdict.why}.` };
-        const ok = await ctx.ui.confirm(L(`Sub-Sub: write the Starbuck report to ${dir}?`, `Sub-Sub: escrever o relatório do Starbuck em ${dir}?`), L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
+        const ok = await approve(ctx, L(`Sub-Sub: write the Starbuck report to ${dir}?`, `Sub-Sub: escrever o relatório do Starbuck em ${dir}?`), L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
         return ok ? undefined : { block: true, reason: `${user} did not allow writing the report there. Ask where to put it (report_dir).` };
     }
     async function benchGate(name, input, kind, cwd, signal) {
@@ -621,20 +767,35 @@ export async function createSubsub(pi, deps = {}) {
                 `for ${user}.${shown}`,
         };
     }
+    const switchTo = async (ctx, next) => {
+        await applyMode(ctx, next, true);
+        ctx.ui.notify(next === "librarian"
+            ? L("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "Sub-Sub: modo Bibliotecário. Para pesquisas e notas, mude para /researcher.")
+            : L("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "Sub-Sub: modo Investigador. Pesquisa, escreve notas e também altera a biblioteca, com pré-visualização."), "info");
+    };
     pi.registerCommand("librarian", {
         description: "Sub-Sub: switch to the Librarian (manages the library: tags, imports, metadata, PDFs)",
-        handler: async (_args, ctx) => {
-            await applyMode(ctx, "librarian", true);
-            ctx.ui.notify(L("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "Sub-Sub: modo Bibliotecário. Para pesquisas e notas, mude para /researcher."), "info");
-        },
+        handler: async (_args, ctx) => switchTo(ctx, "librarian"),
     });
     pi.registerCommand("researcher", {
         description: "Sub-Sub: switch to the Researcher (searches, notes, reviews, and everything the Librarian does)",
-        handler: async (_args, ctx) => {
-            await applyMode(ctx, "researcher", true);
-            ctx.ui.notify(L("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "Sub-Sub: modo Investigador. Pesquisa, escreve notas e também altera a biblioteca, com pré-visualização."), "info");
-        },
+        handler: async (_args, ctx) => switchTo(ctx, "researcher"),
     });
+    // Screens of the terminal look (the web view has its own panels, so these are only for the `subsub` command).
+    if (standalone) {
+        pi.registerCommand("notes", { description: "Sub-Sub: the notes in your Sub-Sub folder", handler: async (_args, ctx) => openNotes(ctx) });
+        pi.registerCommand("library", { description: "Sub-Sub: search your Zotero library as you type", handler: async (_args, ctx) => openLibrary(ctx) });
+        pi.registerCommand("actions", { description: "Sub-Sub: the actions of the web view, as a list", handler: async (_args, ctx) => openActions(ctx) });
+        // Alt works when the terminal sends it as Escape plus the letter; macOS Terminal and iTerm2 do not by default (Option types a symbol), so each also has a function key.
+        const keys = (names, description, handler) => {
+            for (const k of names)
+                pi.registerShortcut?.(k, { description, handler });
+        };
+        keys(["alt+n", "f2"], "Sub-Sub: notes", (ctx) => openNotes(ctx));
+        keys(["alt+l", "f3"], "Sub-Sub: library search", (ctx) => openLibrary(ctx));
+        keys(["alt+a", "f4"], "Sub-Sub: actions", (ctx) => openActions(ctx));
+        keys(["alt+m", "f5"], "Sub-Sub: switch between the Researcher and the Librarian", (ctx) => switchTo(ctx, mode === "researcher" ? "librarian" : "researcher"));
+    }
     pi.registerCommand("subsub", {
         description: "Sub-Sub: Zotero connection and library overview",
         handler: async (_args, ctx) => {
@@ -660,7 +821,7 @@ export async function createSubsub(pi, deps = {}) {
                         : `Items: ${o.items}. Without tags: ${o.without_manual_tags}. Missing facets: ${JSON.stringify(o.missing_facet)}. Awaiting review (_agent): ${o.awaiting_review}.`);
                 }
             }
-            headerTui?.requestRender();
+            redraw();
             emitWeb();
             ctx.ui.notify(lines.join("\n"), "info");
         },
@@ -713,6 +874,12 @@ export async function createSubsub(pi, deps = {}) {
     // A registered command runs before the input hook, so /read checks the mode itself.
     pi.registerCommand("read", {
         description: "Sub-Sub: read a paper with guidance; Sub-Sub finds the passages and asks, you write the answers. /read [background|fact|extract|critique] <citekey, DOI, PMID or title words>",
+        getArgumentCompletions: (prefix) => {
+            if (/\s/.test(prefix.trim()))
+                return null;
+            const found = Object.keys(PURPOSES).filter((k) => k.startsWith(prefix.trim().toLowerCase()));
+            return found.length ? found.map((k) => ({ value: k, label: L(PURPOSES[k][0], PURPOSES[k][1]) })) : null;
+        },
         handler: async (args, ctx) => {
             if (mode === "librarian")
                 return ctx.ui.notify(researcherOnly("read"), "warning");
@@ -840,7 +1007,7 @@ export async function createSubsub(pi, deps = {}) {
                 ctx.ui.notify(preview.text, "warning");
                 return;
             }
-            const ok = await ctx.ui.confirm(L("Sub-Sub: undo?", "Sub-Sub: anular?"), paintFor(ctx)(formatPreview("zotero_undo", preview.data, lang)));
+            const ok = await approve(ctx, L("Sub-Sub: undo?", "Sub-Sub: anular?"), paintFor(ctx)(formatPreview("zotero_undo", preview.data, lang)));
             if (!ok)
                 return;
             const res = await current().call("zotero_undo", { ...input, dry_run: false });

package/dist/tui-view.js

@@ -0,0 +1,228 @@
+/**
+ * The screen of `subsub tui`, in parts that know nothing about processes: the colours (read from the themes in themes/, since a client of pi's RPC
+ * mode has no pi theme), the transcript, the side panel and the footer. The controller in src/tui.ts feeds them.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getTerminalColorMode, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { cut, evidenceLine, rule, toolDetail, toolLine } from "./chrome.js";
+import { headerLines } from "./look.js";
+import { UNICODE } from "./skin.js";
+// ---------------------------------------------------------------- colours
+/** A Sub-Sub theme file, read as a table of foreground colours. */
+export class Palette {
+    vars;
+    colors;
+    mode;
+    name;
+    constructor(file, mode) {
+        this.name = file.name ?? "";
+        this.vars = file.vars ?? {};
+        this.colors = file.colors;
+        this.mode = mode;
+    }
+    /** The colour of a theme role (accent, text, muted, dim, success, warning, mdLink, ...) as an SGR foreground sequence, or "" for the terminal's own. */
+    ansi(role) {
+        let v = this.colors[role];
+        if (typeof v === "string" && v in this.vars)
+            v = this.vars[v];
+        if (v === undefined || v === "")
+            return "";
+        if (typeof v === "number")
+            return `\x1b[38;5;${v}m`;
+        const [r, g, b] = [1, 3, 5].map((i) => parseInt(v.slice(i, i + 2), 16));
+        return this.mode === "truecolor" ? `\x1b[38;2;${r};${g};${b}m` : `\x1b[38;5;${rgbTo256(r, g, b)}m`;
+    }
+    fg(role, text) {
+        const on = this.ansi(role);
+        return on ? `${on}${text}\x1b[39m` : text;
+    }
+    bold = (t) => `\x1b[1m${t}\x1b[22m`;
+    italic = (t) => `\x1b[3m${t}\x1b[23m`;
+    underline = (t) => `\x1b[4m${t}\x1b[24m`;
+    strikethrough = (t) => `\x1b[9m${t}\x1b[29m`;
+    /** The paint roles of the screens (see Paint in look.ts). */
+    paint() {
+        return {
+            mark: (x) => this.fg("accent", x),
+            text: (x) => this.fg("text", x),
+            muted: (x) => this.fg("muted", x),
+            dim: (x) => this.fg("dim", x),
+            ok: (x) => this.fg("success", x),
+            pend: (x) => this.fg("warning", x),
+            strike: (x) => this.strikethrough(this.fg("muted", x)),
+        };
+    }
+    /** For pi-tui's Markdown component. */
+    markdownTheme() {
+        return {
+            heading: (t) => this.bold(this.fg("mdHeading", t)),
+            link: (t) => this.underline(this.fg("mdLink", t)),
+            linkUrl: (t) => this.fg("mdLinkUrl", t),
+            code: (t) => this.fg("mdCode", t),
+            codeBlock: (t) => this.fg("mdCodeBlock", t),
+            codeBlockBorder: (t) => this.fg("mdCodeBlockBorder", t),
+            quote: (t) => this.italic(this.fg("mdQuote", t)),
+            quoteBorder: (t) => this.fg("mdQuoteBorder", t),
+            hr: (t) => this.fg("mdHr", t),
+            listBullet: (t) => this.fg("mdListBullet", t),
+            bold: this.bold,
+            italic: this.italic,
+            strikethrough: this.strikethrough,
+            underline: this.underline,
+        };
+    }
+    /** For pi-tui's Editor. */
+    editorTheme() {
+        return {
+            borderColor: (t) => this.fg("borderMuted", t),
+            selectList: {
+                selectedPrefix: (t) => this.fg("accent", t),
+                selectedText: (t) => this.fg("text", t),
+                description: (t) => this.fg("muted", t),
+                scrollInfo: (t) => this.fg("dim", t),
+                noMatch: (t) => this.fg("muted", t),
+            },
+        };
+    }
+}
+/** The nearest xterm-256 index of an RGB colour (cube or grey ramp). */
+function rgbTo256(r, g, b) {
+    const cube = [0, 95, 135, 175, 215, 255];
+    const near = (v) => cube.reduce((best, c, i) => (Math.abs(c - v) < Math.abs(cube[best] - v) ? i : best), 0);
+    const [ri, gi, bi] = [near(r), near(g), near(b)];
+    const grey = Math.round((r + g + b) / 3);
+    const greyIndex = Math.min(255, Math.max(232, 232 + Math.round((grey - 8) / 10)));
+    const cubeDist = (cube[ri] - r) ** 2 + (cube[gi] - g) ** 2 + (cube[bi] - b) ** 2;
+    const greyValue = 8 + (greyIndex - 232) * 10;
+    const greyDist = (greyValue - r) ** 2 + (greyValue - g) ** 2 + (greyValue - b) ** 2;
+    return greyDist < cubeDist ? greyIndex : 16 + 36 * ri + 6 * gi + bi;
+}
+/** Dark or light terminal: from COLORFGBG ("15;0" is light text on black), else dark. */
+export function schemeFromEnv(env = process.env) {
+    const bg = Number((env.COLORFGBG ?? "").split(";").at(-1));
+    if (!Number.isFinite(bg) || (env.COLORFGBG ?? "") === "")
+        return "dark";
+    return bg === 7 || bg >= 9 ? "light" : "dark";
+}
+/** The palette of a theme (glauca for the Researcher, try-works for the Librarian) in the colour mode of the terminal. */
+export function loadPalette(themesDir, base, scheme, mode = getTerminalColorMode() === "256color" ? "256color" : "truecolor") {
+    const name = `${base}-${scheme}${mode === "256color" ? "-256" : ""}`;
+    return new Palette(JSON.parse(readFileSync(join(themesDir, `${name}.json`), "utf8")), mode);
+}
+/** The text of a message's content: a string, or the text blocks of a list. */
+export function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.filter((b) => b?.type === "text").map((b) => b.text ?? "").join("\n\n");
+}
+const toolWordOf = (w, lang, name) => {
+    const short = name.replace(/^(zotero|scholar)_/, "");
+    return w ? (w.TOOLS[lang][short] ?? w.TOOLS.en[short] ?? name) : name;
+};
+/** One entry as lines, without the empty line that separates entries. */
+export function entryLines(e, width, c) {
+    const g = c.glyphs ?? UNICODE;
+    const p = c.paint;
+    const w = Math.max(10, width);
+    switch (e.kind) {
+        case "user": {
+            const lines = wrapTextWithAnsi(e.text, w - 2);
+            return lines.map((l, i) => `${i === 0 ? p.mark(g.pointer) : " "} ${p.text(l)}`);
+        }
+        case "assistant":
+            return c.markdown(e.text, w);
+        case "tool": {
+            const head = toolLine({ state: e.state, word: toolWordOf(c.words, c.lang, e.name), detail: toolDetail(e.args), error: e.error, lang: c.lang, width: w }, p, g);
+            if (!c.expanded || !e.output?.trim())
+                return [head];
+            return [head, ...e.output.split("\n").slice(0, 40).map((l) => p.muted(cut(`  ${l}`, w)))];
+        }
+        case "notice": {
+            const text = e.level === "info" ? p.muted(cut(e.text, w)) : p.text(cut(`${g.hollow} ${e.text}`, w));
+            return [text];
+        }
+        case "evidence":
+            return [evidenceLine(e.text, c.lang, w, p, g)];
+    }
+}
+/** The whole transcript: the entries one after another, an empty line between them. */
+export function transcriptLines(entries, width, c) {
+    const out = [];
+    let previous;
+    for (const e of entries) {
+        const lines = entryLines(e, width, c);
+        if (!lines.length)
+            continue;
+        // Tool rows and notices belong together; every other change of speaker gets an empty line.
+        if (out.length && !(previous?.kind === "tool" && e.kind === "tool"))
+            out.push("");
+        out.push(...lines);
+        previous = e;
+    }
+    return out;
+}
+/** The messages of an earlier conversation (get_messages) as entries. */
+export function entriesFromMessages(messages) {
+    const out = [];
+    const tools = new Map();
+    for (const m of messages) {
+        if (m.role === "user") {
+            const text = messageText(m.content).trim();
+            if (text && !text.startsWith("/subsub-"))
+                out.push({ kind: "user", text });
+        }
+        else if (m.role === "assistant") {
+            for (const b of Array.isArray(m.content) ? m.content : []) {
+                if (b.type === "text" && b.text?.trim())
+                    out.push({ kind: "assistant", text: b.text });
+                else if (b.type === "toolCall") {
+                    const t = { kind: "tool", id: b.id, name: b.name, args: b.arguments, state: "done" };
+                    tools.set(b.id, t);
+                    out.push(t);
+                }
+            }
+        }
+        else if (m.role === "toolResult") {
+            const t = tools.get(m.toolCallId);
+            if (t) {
+                t.output = messageText(m.content);
+                if (m.isError) {
+                    t.state = "failed";
+                    t.error = t.output.trim().split("\n")[0];
+                }
+            }
+        }
+    }
+    return out;
+}
+export const SIDE_WIDTH = 30;
+const SIDE_WORDS = {
+    en: { notes: "notes", library: "library", actions: "actions", mode: "mode", conversations: "Conversations", none: "none yet" },
+    pt: { notes: "notas", library: "biblioteca", actions: "ações", mode: "modo", conversations: "Conversas", none: "ainda não há" },
+};
+/** The side panel as lines of exactly `width` visible columns are not needed: the layout pads them. */
+export function sideLines(s, width, rows, p, g = UNICODE) {
+    const w = Math.max(16, width);
+    const words = SIDE_WORDS[s.lang];
+    const mode = s.mode === "librarian" ? "Librarian" : "Researcher";
+    const lib = s.library.zotero === "reachable" ? `${s.library.items ?? "?"} ${s.lang === "pt" ? "itens" : "items"}` : s.library.zotero === "down" ? `${g.hollow} Zotero` : "Zotero...";
+    const lines = [p.mark(cut(` Sub-Sub ${s.version}`, w)), p.text(cut(` ${mode}`, w)), p.muted(cut(` ${lib}`, w)), p.dim(cut(` ${s.model}`, w)), rule(w, "solid", p.muted, g)];
+    for (const [key, word] of [["F2", words.notes], ["F3", words.library], ["F4", words.actions], ["F5", words.mode]])
+        lines.push(p.muted(cut(` ${key.padEnd(4)}${word}`, w)));
+    lines.push(rule(w, "solid", p.muted, g), p.text(cut(` ${words.conversations}`, w)));
+    if (!s.conversations.length)
+        lines.push(p.dim(cut(`  ${words.none}`, w)));
+    for (const c of s.conversations) {
+        if (lines.length >= rows)
+            break;
+        lines.push(c.open ? `${p.mark(g.pointer)}${p.text(cut(` ${c.title}`, w - 1))}` : ` ${p.muted(cut(` ${c.title}`, w - 1))}`);
+    }
+    return lines.slice(0, Math.max(rows, 1));
+}
+/** The top of the transcript at the start: the banner and the quote (the same as the header of `subsub`). */
+export function bannerLines(o) {
+    return headerLines({ ...o, quote: o.quote });
+}