@tiagojct/subsub 0.16.0 → 0.18.0

package/dist/subsub.js

@@ -6,24 +6,25 @@
  *   and writes notes. Each mode can have its own model.
  * - An approval gate: every library change is previewed by the server (dry run)
  *   and shown to the user; nothing is applied without a yes.
- * - Profiles (reader, scholar, author, editor) set what Sub-Sub writes and which
- *   tools it offers; /profile changes it.
- * - Commands: /librarian, /researcher, /profile, /subsub, /history, /undo.
+ * - Commands: /librarian, /researcher, /read, /subsub, /history, /undo.
  * - Add-on: with "addons": ["starbuck"], Starbuck runs as a third server
  *   ("verify") for reference checks.
  *
  * 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, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
-import { expand, findUv, FREE_MODELS, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
-import { profileList, profileSpec, promptBlocked } from "./profiles.js";
+import { expand, findUv, FREE_MODELS, loadConfig, parseEnvFile, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
 import { aiStatement } from "./statement.js";
-import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.js";
+import { feedbackNote, ISSUES_URL } from "./feedback.js";
+import { formatChecks, runChecks } from "./doctor.js";
+import { PURPOSES, readArgs, readInstruction } from "./read.js";
+import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn, sourceOf, withPageLinks } from "./notes.js";
 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";
@@ -114,8 +115,7 @@ export async function createSubsub(pi, deps = {}) {
     pi.registerFlag("researcher", { description: "Start Sub-Sub in the Researcher mode", type: "boolean", default: false });
     let mode = cfg.defaultMode;
     const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
-    const toolOpts = () => ({ profile, bench: benchRun });
-    let profile = cfg.profile;
+    const toolOpts = () => ({ bench: benchRun });
     const user = who(cfg);
     /** True when started with the `subsub` command (not as a package inside plain pi). */
     const standalone = process.env.SUBSUB_CLI === "1";
@@ -130,6 +130,8 @@ export async function createSubsub(pi, deps = {}) {
     /** 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";
     let lastError;
+    /** The last provider or tool error of the session, for /feedback. */
+    let recentError;
     let resumes = 0;
     let resumeTimer;
     let turnStart = 0;
@@ -142,8 +144,6 @@ export async function createSubsub(pi, deps = {}) {
         const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
         const state = {
             mode,
-            profile,
-            profileLabel: profileSpec(profile).label,
             model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null,
             down,
             library,
@@ -205,7 +205,6 @@ export async function createSubsub(pi, deps = {}) {
                     return headerLines({
                         version,
                         mode,
-                        profile: profileSpec(profile).label,
                         model: modelId,
                         library,
                         quote,
@@ -226,7 +225,7 @@ export async function createSubsub(pi, deps = {}) {
     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} | ${profileSpec(profile).label} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
+        ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
         if (standalone)
             ctx.ui.setTitle(`Sub-Sub: ${mode}`);
         headerTui?.requestRender();
@@ -282,7 +281,7 @@ export async function createSubsub(pi, deps = {}) {
             scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
         applyTheme(ctx);
         await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
-        logUsage(cfg.usageLog, { ev: "session", mode, profile, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
+        logUsage(cfg.usageLog, { ev: "session", mode, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
         if (lookOn(ctx)) {
             setHeader(ctx);
             void refreshLibrary();
@@ -307,6 +306,7 @@ export async function createSubsub(pi, deps = {}) {
     });
     /** Prompt commands for the Researcher; the Librarian has the library ones (tag-batch, clean-tags, import-queue). */
     const RESEARCH_PROMPTS = ["lit", "compare", "lit-note", "synthesis", "gaps", "manuscript", "verify", "review", "alert", "request-copy", "digest"];
+    const researcherOnly = (cmd) => L(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, `Sub-Sub: /${cmd} faz parte do Investigador. Mude com /researcher.`);
     // /tree moves to another branch: take that branch's mode (pi restores its model itself).
     pi.on("session_tree", async (_event, ctx) => {
         let m;
@@ -324,13 +324,19 @@ export async function createSubsub(pi, deps = {}) {
         const m = event.message;
         if (m.role !== "assistant" || m.stopReason !== "error")
             return;
-        lastError = m.errorMessage;
+        lastError = recentError = m.errorMessage;
         if (webView || perMinuteWait(m.errorMessage) !== undefined)
             return;
         const kind = providerTrouble(m.errorMessage);
         if (kind)
             ctx.ui.notify(`Sub-Sub: ${trouble[kind]}`, "warning");
     });
+    pi.on("tool_result", async (event) => {
+        if (!event.isError)
+            return;
+        const text = event.content.map((c) => (c.type === "text" ? c.text : "")).join(" ");
+        recentError = `${event.toolName ?? "tool"}: ${text}`.slice(0, 2000);
+    });
     // A per-minute limit (free tiers): wait as long as the provider says, then continue the task,
     // up to three times per request of the user. Anything the user types cancels the wait.
     pi.on("agent_end", async (_event, ctx) => {
@@ -352,8 +358,7 @@ export async function createSubsub(pi, deps = {}) {
             pi.sendMessage({ customType: "subsub-resume", content: "The model provider's per-minute limit was reached and has now passed. Continue the task where you stopped; do not repeat finished steps.", display: false }, { triggerTurn: true });
         }, wait * 1000);
     });
-    // Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
-    // The input event comes before pi expands a prompt template.
+    // Research prompts in the Librarian. The input event comes before pi expands a prompt template.
     pi.on("input", async (event, ctx) => {
         if (resumeTimer)
             clearTimeout(resumeTimer);
@@ -364,21 +369,22 @@ export async function createSubsub(pi, deps = {}) {
         if (cmd !== "subsub-refresh")
             logUsage(cfg.usageLog, { ev: "ask", kind: cmd ? `/${cmd}` : "message", words: event.text.trim().split(/\s+/).filter(Boolean).length });
         if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
-            ctx.ui.notify(L(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, `Sub-Sub: /${cmd} faz parte do Investigador. Mude com /researcher.`), "warning");
+            ctx.ui.notify(researcherOnly(cmd), "warning");
+            return { action: "handled" };
+        }
+        // shortcut: a notice for the habit of 0.16 and earlier; drop it a few versions on.
+        if (cmd === "profile") {
+            ctx.ui.notify(L("Sub-Sub no longer has profiles: every command is in the Researcher. To read a paper with guidance, type /read.", "O Sub-Sub já não tem perfis: todos os comandos estão no Investigador. Para ler um artigo com orientação, escreva /read."), "info");
             return { action: "handled" };
         }
-        const why = promptBlocked(event.text, profile);
-        if (!why)
-            return { action: "continue" };
-        ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
-        return { action: "handled" };
+        return { action: "continue" };
     });
     pi.on("agent_start", async () => {
         turnStart = Date.now();
         turnTools = 0;
     });
     pi.on("before_agent_start", async (event, ctx) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
+        systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, cfg, ctx.cwd)}`,
     }));
     /** Model test (subsub-bench): record every change instead of asking, and apply none. */
     const benchOut = process.env.SUBSUB_BENCH_OUT ? expand(process.env.SUBSUB_BENCH_OUT) : undefined;
@@ -512,14 +518,28 @@ export async function createSubsub(pi, deps = {}) {
             return undefined;
         const full = await fullTextOf(key, signal);
         // Without the full text (no PDF indexed, Zotero closed) there is nothing to check against.
-        return full ? quoteProblem(missingQuotes(text, full, quotesIn(before))) : undefined;
+        if (!full)
+            return undefined;
+        const missing = quoteProblem(missingQuotes(text, full.text, quotesIn(before)));
+        // A note that passes is written with its page references linked to the PDF.
+        if (!missing && full.attachment) {
+            const link = (s) => withPageLinks(s, sourceOf(full.text), full.attachment);
+            if (name === "write")
+                input.content = link(String(input.content ?? ""));
+            else
+                for (const e of input.edits)
+                    if (typeof e.newText === "string")
+                        e.newText = link(e.newText);
+        }
+        return missing;
     }
-    /** The whole indexed full text of an item, read in parts, kept for the session. */
+    /** The whole indexed full text of an item and its attachment, read in parts, kept for the session. */
     const fullTexts = new Map();
     async function fullTextOf(key, signal) {
         if (fullTexts.has(key))
             return fullTexts.get(key) ?? undefined;
         let text = "";
+        let attachment;
         let offset = 0;
         try {
             for (let part = 0; offset !== null && part < 20; part++) {
@@ -528,14 +548,16 @@ export async function createSubsub(pi, deps = {}) {
                     break;
                 const data = (res.data ?? {});
                 text += data.text ?? "";
+                attachment ??= data.attachment;
                 offset = data.next_offset ?? null;
             }
         }
         catch {
             /* no full text: the check is skipped */
         }
-        fullTexts.set(key, text || null);
-        return text || undefined;
+        const full = text ? { text, attachment } : null;
+        fullTexts.set(key, full);
+        return full ?? undefined;
     }
     /**
      * Starbuck writes its reports into a folder: report_dir, or _starbuck next to the
@@ -613,34 +635,10 @@ export async function createSubsub(pi, deps = {}) {
             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");
         },
     });
-    pi.registerCommand("profile", {
-        description: "Sub-Sub: show or change the profile (reader, scholar, author, editor)",
-        handler: async (args, ctx) => {
-            const want = args.trim().toLowerCase();
-            if (!want) {
-                ctx.ui.notify(`Profile: ${profileSpec(profile).label}. To change it, type /profile <name>.\n${profileList(profile)}`, "info");
-                return;
-            }
-            if (!isProfile(want)) {
-                ctx.ui.notify(`Unknown profile "${want}". Choose one of:\n${profileList(profile)}`, "warning");
-                return;
-            }
-            profile = want;
-            let saved = "";
-            try {
-                saved = ` Saved in ${saveConfig({ profile })}.`;
-            }
-            catch (err) {
-                saved = ` Not saved: ${err.message}`;
-            }
-            await applyMode(ctx, mode, false, false);
-            ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
-        },
-    });
     pi.registerCommand("subsub", {
         description: "Sub-Sub: Zotero connection and library overview",
         handler: async (_args, ctx) => {
-            const lines = [`Mode: ${mode}. Profile: ${profileSpec(profile).label}. Model: ${ctx.model?.id ?? "none"}.`];
+            const lines = [`Mode: ${mode}. Model: ${ctx.model?.id ?? "none"}.`];
             if (!bridge) {
                 ctx.ui.notify(`${lines[0]}\nThe Zotero servers are not running. Try /reload.`, "warning");
                 return;
@@ -674,6 +672,24 @@ export async function createSubsub(pi, deps = {}) {
             await refreshLibrary();
         },
     });
+    // The web view's library search: the result goes to the page through a status, like the library counts.
+    pi.registerCommand("subsub-find", {
+        description: "Sub-Sub: search the library for the web view",
+        handler: async (args, ctx) => {
+            if (ctx.mode !== "rpc")
+                return;
+            const q = String(args ?? "").trim();
+            let out;
+            try {
+                const r = await current().call("zotero_find_items", { query: q, limit: 25 });
+                out = r.isError ? { error: r.text } : { items: r.data?.items ?? [] };
+            }
+            catch (err) {
+                out = { error: err.message };
+            }
+            ctx.ui.setStatus("subsub.find", JSON.stringify({ q, ...out }));
+        },
+    });
     pi.registerCommand("ai-statement", {
         description: "Sub-Sub: a draft statement on the use of AI for a manuscript (what journals ask for)",
         handler: async (args, ctx) => {
@@ -694,6 +710,98 @@ export async function createSubsub(pi, deps = {}) {
             ctx.ui.notify(L(`Sub-Sub: a draft statement on the use of AI is in ${file}. Complete the parts in brackets. To name the tasks, type /ai-statement followed by them, for example: /ai-statement literature searches and reading notes.`, `Sub-Sub: há um rascunho da declaração sobre o uso de IA em ${file}. Complete as partes entre parênteses retos. Para indicar as tarefas, escreva /ai-statement seguido delas, por exemplo: /ai-statement literature searches and reading notes.`), "info");
         },
     });
+    // 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>",
+        handler: async (args, ctx) => {
+            if (mode === "librarian")
+                return ctx.ui.notify(researcherOnly("read"), "warning");
+            let { purpose, ref } = readArgs(String(args ?? ""));
+            ref ||= (await ctx.ui.input(L("Which paper?", "Que artigo?"), L("citekey, DOI, PMID or title words", "citekey, DOI, PMID ou palavras do título")))?.trim() ?? "";
+            if (!ref)
+                return;
+            if (!purpose) {
+                const labels = Object.values(PURPOSES).map(([en, pt]) => L(en, pt));
+                purpose = Object.keys(PURPOSES)[labels.indexOf((await ctx.ui.select(L("Why are you reading it?", "Porque vai ler este artigo?"), labels)) ?? "")];
+                if (!purpose)
+                    return;
+            }
+            const req = { ref, purpose, date: new Date().toISOString().slice(0, 10) };
+            if (purpose === "fact") {
+                req.fact = (await ctx.ui.input(L("Which fact are you looking for?", "Que dado procura?")))?.trim();
+                if (!req.fact)
+                    return;
+            }
+            if (purpose === "extract") {
+                let sheets = [];
+                try {
+                    sheets = readdirSync(join(cfg.vault ?? ctx.cwd, "Research")).filter((f) => f.endsWith(" extraction.md")).sort();
+                }
+                catch {
+                    // No Research folder yet: the first sheet is a new one.
+                }
+                const fresh = L("New sheet", "Nova folha");
+                const pick = sheets.length ? await ctx.ui.select(L("Which extraction sheet?", "Que folha de extração?"), [...sheets, fresh]) : fresh;
+                if (!pick)
+                    return;
+                if (pick === fresh) {
+                    req.question = (await ctx.ui.input(L("The question of your review", "A pergunta da sua revisão")))?.trim();
+                    if (!req.question)
+                        return;
+                }
+                else
+                    req.sheet = `Research/${pick}`;
+            }
+            pi.sendUserMessage(readInstruction(req), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+        },
+    });
+    pi.registerCommand("feedback", {
+        description: "Sub-Sub: a draft bug report or idea in Inbox/, to read and post on GitHub yourself; Sub-Sub sends nothing  [what happened]",
+        handler: async (args, ctx) => {
+            const date = new Date().toISOString().slice(0, 10);
+            let piVersion = "";
+            try {
+                piVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..", "package.json"), "utf8")).version;
+            }
+            catch {
+                /* not needed for the report */
+            }
+            let checks;
+            try {
+                checks = deps.doctor ? deps.doctor() : formatChecks(runChecks(cfg, process.env));
+            }
+            catch (err) {
+                checks = `subsub doctor failed: ${err.message}`;
+            }
+            const text = feedbackNote({
+                what: String(args ?? ""),
+                date,
+                versions: `Sub-Sub ${ownVersion()}${piVersion ? `, pi ${piVersion}` : ""}, Node ${process.version}, ${process.platform} ${process.arch}`,
+                setup: [
+                    `Mode: ${mode}. Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}.`,
+                    `Language: ${cfg.language}. Reference checks (Starbuck): ${starbuckEnabled(cfg) ? "on" : "off"}.`,
+                    `Zotero: ${library.zotero}.${bridge && Object.keys(bridge.errors).length ? ` Servers not running: ${Object.keys(bridge.errors).join(", ")}.` : ""}`,
+                ],
+                checks,
+                lastError: recentError,
+                home: homedir(),
+                vault: cfg.vault,
+            });
+            const dir = join(cfg.vault ?? ctx.cwd, "Inbox");
+            let file = join(dir, `${date} Sub-Sub feedback.md`);
+            for (let n = 2; existsSync(file); n++)
+                file = join(dir, `${date} Sub-Sub feedback-${n}.md`);
+            try {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, text);
+            }
+            catch (err) {
+                ctx.ui.notify(`${L("Could not save it", "Não foi possível guardar")}: ${err.message}`, "warning");
+                return;
+            }
+            ctx.ui.notify(L(`Sub-Sub: a draft report is in ${file}. Read it, add what you expected, take out anything you do not want to share, and post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`, `Sub-Sub: há um rascunho do relatório em ${file}. Leia-o, acrescente o que esperava, retire o que não quer partilhar e publique-o em ${ISSUES_URL}. O Sub-Sub não enviou nada.`), "info");
+        },
+    });
     pi.registerCommand("history", {
         description: "Sub-Sub: recent library changes",
         handler: async (_args, ctx) => {

package/dist/web.js

@@ -15,16 +15,17 @@
  */
 import { spawn } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, appendFileSync } from "node:fs";
+import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, appendFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { extname, join, normalize, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, normalize, relative, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
 import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, uiLanguage, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
 import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
-import { obsidianRoot } from "./layout.js";
+import { NOTE_DIRS, obsidianRoot, SETTINGS_DIR } from "./layout.js";
+import { field, frontMatter } from "./notes.js";
 import { realish, within } from "./paths.js";
 export function parseWebArgs(args) {
     const o = { port: 0, open: true, librarian: false, here: false, idleMinutes: 10, piArgs: [] };
@@ -181,8 +182,45 @@ const TYPES = {
     ".png": "image/png",
     ".ico": "image/x-icon",
 };
+/** Files that the notes pane shows. */
+const NOTE_TYPES = new Set([".md", ".markdown"]);
+/** Images that a note shows (a figure cut out of a PDF, for example). */
+const IMAGE_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
 /** Files that the Open button may hand to the system (never programs or scripts). */
 export const OPENABLE = new Set([".md", ".markdown", ".txt", ".pdf", ".bib", ".csv", ".qmd"]);
+/** A file inside the working folder or the Sub-Sub folder, judged by its real path, so a link cannot point outside. */
+export function allowedFile(raw, cwd, vault) {
+    // expand() resolves against the process folder: use it for "~" only.
+    const target = resolve(cwd, raw.startsWith("~") ? expand(raw) : raw);
+    const real = realish(target);
+    const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
+    return inside && existsSync(target) && statSync(target).isFile() ? target : undefined;
+}
+/** The note a [[wikilink]] names: the first <folder>/<name>.md in the Sub-Sub folder, as Obsidian would find it. */
+export function wikilinkTarget(name, root) {
+    const file = name.endsWith(".md") ? name : `${name}.md`;
+    return ["", ...NOTE_DIRS, SETTINGS_DIR].map((d) => join(root, d, file)).find((f) => existsSync(f));
+}
+/** The notes in the Sub-Sub folders, newest first (dot folders such as Research/.plans left out). */
+export function listNotes(root, max = 300) {
+    const out = [];
+    for (const d of [...NOTE_DIRS, SETTINGS_DIR]) {
+        let names = [];
+        try {
+            names = readdirSync(join(root, d), { recursive: true });
+        }
+        catch {
+            continue;
+        }
+        for (const n of names) {
+            if (!n.endsWith(".md") || n.split(/[\\/]/).some((x) => x.startsWith(".")))
+                continue;
+            const path = join(root, d, n);
+            out.push({ path, rel: join(d, n), modified: statSync(path).mtimeMs });
+        }
+    }
+    return out.sort((a, b) => b.modified - a.modified).slice(0, max);
+}
 const CSP = [
     "default-src 'none'",
     "script-src 'self'",
@@ -194,6 +232,14 @@ const CSP = [
     "form-action 'none'",
     "frame-ancestors 'none'",
 ].join("; ");
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
 function same(a, b) {
     const x = Buffer.from(a);
     const y = Buffer.from(b);
@@ -263,6 +309,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
     const agentDir = agentDirFor(env, home);
     const cwd = chooseCwd(process.cwd(), home, cfg.vault, opts.here);
     const lang = uiLanguage(cfg.language);
+    const notesRoot = cfg.vault ?? cwd;
     const token = randomBytes(24).toString("base64url");
     const webDir = join(PACKAGE_DIR, "web");
     const bin = join(PACKAGE_DIR, "bin", "subsub.js");
@@ -274,6 +321,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
     const clients = new Set();
     const dialogs = new Map();
     let subsubState = null;
+    let lastFind = null;
     let busy = false;
     let lastSeen = Date.now();
     let restarting = false;
@@ -310,6 +358,14 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                 }
                 broadcast({ type: "subsub_state", state: subsubState });
             }
+            else if (ev.method === "setStatus" && ev.statusKey === "subsub.find") {
+                try {
+                    lastFind = ev.statusText ? JSON.parse(ev.statusText) : null;
+                }
+                catch {
+                    lastFind = null;
+                }
+            }
             else if (ev.method === "notify") {
                 broadcast(ev);
             }
@@ -353,13 +409,22 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
             out.session = await agent.request({ type: "get_state" });
             lastSession = out.session.sessionFile ?? lastSession;
             out.messages = (await agent.request({ type: "get_messages" })).messages;
-            out.commands = (await agent.request({ type: "get_commands" })).commands;
+            const commands = (await agent.request({ type: "get_commands" })).commands;
+            // RPC has no argument hints: read them from the prompt files.
+            out.commands = commands.map((c) => {
+                const front = c.source === "prompt" && c.sourceInfo?.path ? frontMatter(readText(c.sourceInfo.path)) : undefined;
+                const hint = front && field(front, "argument-hint");
+                return hint ? { ...c, hint } : c;
+            });
         }
         catch (err) {
             out.error = err.message;
         }
         return out;
     }
+    async function currentSession() {
+        return (await agent.request({ type: "get_state" })).sessionFile;
+    }
     async function sessions() {
         const { SessionManager } = await import("@earendil-works/pi-coding-agent");
         const list = await SessionManager.list(cwd);
@@ -493,7 +558,8 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     if (!message)
                         return send(res, 400, { error: "empty message" });
                     try {
-                        await agent.request({ type: "prompt", message, ...(busy ? { streamingBehavior: "followUp" } : {}) });
+                        // A command answers only after its dialogs close (/read, /undo), so wait longer than the default.
+                        await agent.request({ type: "prompt", message, ...(busy ? { streamingBehavior: "followUp" } : {}) }, 60 * 60_000);
                     }
                     catch (err) {
                         // No provider yet: the page opens the model dialog instead of showing pi's text.
@@ -599,14 +665,78 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                             saveConfig({ models: TESTED_MODELS, model: undefined }, env);
                     });
                 }
+                case "GET /api/notes":
+                    return send(res, 200, { root: notesRoot, notes: listNotes(notesRoot) });
+                case "GET /api/note": {
+                    const raw = url.searchParams.get("path") ?? "";
+                    const wiki = !/[\\/]/.test(raw) && !/\.\w+$/.test(raw) ? wikilinkTarget(raw, notesRoot) : undefined;
+                    // A relative path is tried in the working folder, then in the Sub-Sub folder (Literature/x.md).
+                    const file = allowedFile(wiki ?? raw, cwd, cfg.vault) ?? allowedFile(raw, notesRoot, cfg.vault);
+                    if (!file)
+                        return send(res, 404, { error: "not found in the Sub-Sub folder" });
+                    if (!NOTE_TYPES.has(extname(file).toLowerCase()))
+                        return send(res, 415, { error: "not a note" });
+                    if (statSync(file).size > 2_000_000)
+                        return send(res, 413, { error: "too large to show" });
+                    return send(res, 200, { path: file, name: basename(file), text: readFileSync(file, "utf8") });
+                }
+                case "GET /api/note-file": {
+                    const raw = url.searchParams.get("path") ?? "";
+                    const file = allowedFile(raw, cwd, cfg.vault) ?? allowedFile(raw, notesRoot, cfg.vault);
+                    if (!file)
+                        return send(res, 404, { error: "not found in the Sub-Sub folder" });
+                    const type = IMAGE_TYPES[extname(file).toLowerCase()];
+                    if (!type)
+                        return send(res, 415, { error: "not an image" });
+                    if (statSync(file).size > 20_000_000)
+                        return send(res, 413, { error: "too large to show" });
+                    res.writeHead(200, { ...common, "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+                    return void createReadStream(file).pipe(res);
+                }
+                case "GET /api/library": {
+                    const q = (url.searchParams.get("q") ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
+                    if (!q)
+                        return send(res, 200, { q, items: [] });
+                    await agent.request({ type: "prompt", message: `/subsub-find ${q}` });
+                    return send(res, 200, lastFind?.q === q ? lastFind : { q, items: [] });
+                }
+                case "POST /api/session/name": {
+                    const body = await readJson(req);
+                    const name = String(body.name ?? "").replace(/\s+/g, " ").trim();
+                    if (!name || name.length > 120)
+                        return send(res, 400, { error: "a name of 1 to 120 characters" });
+                    const known = (await sessions());
+                    if (!known.some((x) => x.path === body.path))
+                        return send(res, 404, { error: "no such session" });
+                    if (body.path === (await currentSession()))
+                        await agent.request({ type: "set_session_name", name });
+                    else {
+                        const { SessionManager } = await import("@earendil-works/pi-coding-agent");
+                        SessionManager.open(String(body.path)).appendSessionInfo(name);
+                    }
+                    return send(res, 200, { ok: true });
+                }
+                case "POST /api/session/trash": {
+                    const body = await readJson(req);
+                    const known = (await sessions());
+                    if (!known.some((x) => x.path === body.path))
+                        return send(res, 404, { error: "no such session" });
+                    if (body.path === (await currentSession()))
+                        return send(res, 409, { error: "the open conversation" });
+                    // Nothing is deleted: the file moves to a trash folder next to the agent folder, in the same
+                    // subfolder as under sessions/, so that moving it back is one step.
+                    const rel = relative(join(agentDir, "sessions"), String(body.path));
+                    const to = join(dirname(agentDir), "trash", rel.startsWith("..") ? basename(rel) : rel);
+                    mkdirSync(dirname(to), { recursive: true });
+                    renameSync(String(body.path), to);
+                    return send(res, 200, { ok: true });
+                }
                 case "POST /api/open": {
                     const body = await readJson(req);
-                    const target = resolve(cwd, expand(String(body.path ?? "")));
                     const vault = cfg.vault;
                     // Judge the real file, so a link inside the Sub-Sub folder cannot open a document outside it.
-                    const real = realish(target);
-                    const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
-                    if (!inside || !existsSync(target))
+                    const target = allowedFile(String(body.path ?? ""), cwd, vault);
+                    if (!target)
                         return send(res, 404, { error: "not found in the Sub-Sub folder" });
                     // Documents only: a file that the model wrote must never be run.
                     if (!OPENABLE.has(extname(target).toLowerCase()))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Sub-Sub: a research assistant that works from your own Zotero library, in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",

package/prompts/compare.md

@@ -12,7 +12,7 @@ Make a short slug: lower case, hyphens, at most five words. Use today's date (YY
 2. Read each source before you describe it: zotero_get_fulltext for library items, scholar_read_oa_fulltext (methods and results) for open-access works, scholar_get_work for the abstract of the others. Note whether you read the full text or only the abstract.
 3. Build the matrix, one row per source:
    | # | Source | Claim on the question | Evidence type | Population and setting | Caveats | Confidence |
-   - Evidence type: for example randomised trial, cohort, case-control, cross-sectional, diagnostic accuracy, systematic review, guideline, expert opinion, modelling.
+   - Evidence type: for example randomised trial, cohort, case-control, cross-sectional, diagnostic accuracy, systematic review, guideline, expert opinion, modelling. Add "(preprint)" to a work that is not peer reviewed yet.
    - Caveats: risk of bias, small sample, surrogate outcome, short follow-up, industry funding, abstract only.
    - Confidence: high, moderate or low, with one reason.
 4. Below the matrix, write: where the sources agree; where they disagree and the most likely reason (population, design, outcome definition, analysis); what no source answers. Cite source numbers in every sentence. Write "inference:" before a statement that no single source makes.

package/prompts/gaps.md

@@ -2,4 +2,4 @@
 description: "What am I missing on a topic"
 argument-hint: "<topic or question>"
 ---
-Search PubMed and OpenAlex for: $ARGUMENTS. Tell me how many results are already in my library and list the most relevant ones that are missing, one line each. Ask before you import or queue anything.
+Search PubMed and OpenAlex for: $ARGUMENTS. Tell me how many results are already in my library and list the 5 to 15 most relevant ones that are missing, the best fit first, one line each. This is a list to choose from: do not read the works, and do not search again unless the first search found almost nothing. Ask before you import or queue anything.