@tiagojct/subsub 0.6.1 → 0.8.0

package/dist/config.js

@@ -12,13 +12,21 @@
  *
  * `subsub init` writes this file. Without "serverDir" (or when that folder does
  * not exist), the Zotero servers run from PyPI with uv.
+ *
+ * Add-ons: "addons": ["starbuck"] starts Starbuck (reference checks) as a third
+ * server, "verify". It runs from "starbuckDir" when that folder has a
+ * pyproject.toml, otherwise from the pinned PyPI release (STARBUCK_SOURCE).
+ * `subsub init` and the web view turn it on and off.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 export const PROFILES = ["reader", "scholar", "author", "editor"];
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.5.0";
+/** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
+export const STARBUCK_VERSION = "0.2.0";
+export const STARBUCK_SOURCE = `starbuck==${STARBUCK_VERSION}`;
 export function expand(p, home) {
     const base = home ?? process.env.HOME ?? homedir();
     return resolve(p.replace(/^~(?=$|\/)/, base));
@@ -119,6 +127,8 @@ export function loadConfig(env = process.env) {
         look: user.look,
         quotes: user.quotes,
         themes: user.themes,
+        addons: Array.isArray(user.addons) ? user.addons.filter((a) => typeof a === "string") : [],
+        starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
     };
 }
 /** uv is often missing from PATH when pi is started outside a login shell. */
@@ -143,6 +153,23 @@ export function serverCommand(cfg, program, args = [], env = process.env) {
     }
     return { command: uv, args: ["tool", "run", "--quiet", "--from", `zotero-local-mcp==${SERVER_VERSION}`, program, ...args] };
 }
+export function starbuckEnabled(cfg) {
+    return (cfg.addons ?? []).includes("starbuck");
+}
+/** How to start Starbuck's MCP server: from the local folder when it exists, otherwise the pinned release. */
+export function starbuckCommand(cfg, env = process.env) {
+    const uv = findUv(cfg, env);
+    if (cfg.starbuckDir && existsSync(join(cfg.starbuckDir, "pyproject.toml"))) {
+        return { command: uv, args: ["run", "--quiet", "--directory", cfg.starbuckDir, "starbuck-mcp"] };
+    }
+    return { command: uv, args: ["tool", "run", "--quiet", "--from", STARBUCK_SOURCE, "starbuck-mcp"] };
+}
+/** The addons setting with Starbuck turned on or off; other add-ons stay. Undefined (no setting) when empty. */
+export function withStarbuck(addons, on) {
+    const rest = (addons ?? []).filter((a) => a !== "starbuck");
+    const out = on ? [...rest, "starbuck"] : rest;
+    return out.length ? out : undefined;
+}
 /** How prompts name the user. */
 export function who(cfg) {
     return cfg.userName ?? "the user";

package/dist/doctor.js

@@ -3,13 +3,14 @@
  *
  * Checks Node, the settings file, uv, the Zotero server (it runs
  * `zotero-local-mcp --check`), Zotero itself, the tag list, the notes folder,
- * the contact email and the model login. Exit code 1 when something needs a fix.
+ * the contact email, Starbuck (when the add-on is on) and the model login. Exit
+ * code 1 when something needs a fix.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { findUv, loadConfig, SERVER_VERSION, serverCommand } from "./config.js";
+import { findUv, loadConfig, SERVER_VERSION, serverCommand, STARBUCK_SOURCE, starbuckCommand, starbuckEnabled, } from "./config.js";
 import { profileSpec } from "./profiles.js";
 export const defaultRunner = (command, args, env) => {
     const r = spawnSync(command, args, { env, encoding: "utf8", timeout: 120_000 });
@@ -100,12 +101,32 @@ export function runChecks(cfg, env, deps = {}) {
     out.push(st.contact_email_set
         ? { name: "Contact email", ok: true, detail: "set" }
         : { name: "Contact email", ok: true, warn: true, detail: "not set: open-access PDFs cannot be found", fix: "Type subsub init and give an email address." });
+    if (starbuckEnabled(cfg))
+        out.push(starbuckCheck(cfg, env, run));
     const agentDir = deps.agentDir ?? (env.SUBSUB_AGENT_DIR ? env.SUBSUB_AGENT_DIR : join(homedir(), ".subsub", "agent"));
     out.push(hasLogin(agentDir)
         ? { name: "Model login", ok: true, detail: Object.keys(cfg.models).length ? Object.values(cfg.models).join(", ") : "pi's default model" }
         : { name: "Model login", ok: false, detail: "no model provider yet", fix: "Type subsub, then /login." });
     return out;
 }
+/** The Starbuck add-on: can uv start it? (`starbuck --version`, from the local folder or the pinned release) */
+export function starbuckCheck(cfg, env, run) {
+    const cmd = starbuckCommand(cfg, env);
+    const local = cmd.args.includes("--directory");
+    const args = cmd.args.slice(0, -1).concat(["starbuck", "--version"]);
+    const res = run(cmd.command, args, env);
+    if (res.status === 0) {
+        return { name: "Starbuck", ok: true, detail: `${res.stdout.trim()} ${local ? `from ${cfg.starbuckDir}` : `from ${STARBUCK_SOURCE}`}` };
+    }
+    return {
+        name: "Starbuck",
+        ok: false,
+        detail: local ? `cannot start from ${cfg.starbuckDir}` : `cannot install ${STARBUCK_SOURCE} with uv`,
+        fix: local
+            ? `Type: cd "${cfg.starbuckDir}" && uv sync`
+            : "Check the internet connection and run subsub doctor again. To turn reference checks off, type subsub init.",
+    };
+}
 export function formatChecks(checks) {
     return checks
         .map((c) => {

package/dist/init.js

@@ -12,14 +12,16 @@
  *
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --notes, --profile, --tags
- * health-sciences|health-informatics|any-field, --email, --models keep|later|opencode-go.
+ * health-sciences|health-informatics|any-field, --email, --starbuck on|off,
+ * --models keep|later|opencode-go.
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { configPath, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig } from "./config.js";
+import { configPath, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig, starbuckEnabled, withStarbuck, } from "./config.js";
+import { defaultRunner, starbuckCheck } from "./doctor.js";
 import { PROFILE_SPECS } from "./profiles.js";
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 export const STARTER_TAGS = {
@@ -92,6 +94,10 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         tags = await io.choose("Starter tag list (edit it later in the notes folder)", Object.entries(STARTER_TAGS).map(([value, label]) => ({ value, label })), flags.tags ?? (fmup ? "health-sciences" : "any-field"));
     }
     const email = (await io.ask("Email for Unpaywall and Crossref, to find open-access PDFs (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
+    const starbuck = await io.choose("Reference checks (Starbuck): check that cited works exist, match their citation and were not retracted", [
+        { value: "off", label: "Off" },
+        { value: "on", label: "On (the researcher gets /verify; uses the email above)" },
+    ], flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"));
     const modelOptions = [
         ...(existing.models ? [{ value: "keep", label: `Keep: ${JSON.stringify(existing.models)}` }] : []),
         { value: "later", label: "Choose later in Sub-Sub (/login, then /model)" },
@@ -128,6 +134,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         setup: fmup ? "fmup" : undefined,
         vault: notes,
         envFile,
+        addons: withStarbuck(current.addons, starbuck === "on"),
     };
     if (models === "later")
         patch.models = {};
@@ -135,6 +142,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         patch.models = TESTED_MODELS;
     saveConfig(patch, initEnv);
     const zotero = await zoteroReachable(deps.fetch);
+    const starbuckNote = starbuck === "on" && deps.prepareStarbuck ? deps.prepareStarbuck(loadConfig(initEnv)) : "";
     io.say("");
     io.say(`Saved: ${configFile}`);
     io.say(`Saved: ${envFile}`);
@@ -143,6 +151,8 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     io.say(zotero
         ? "Zotero: reachable."
         : "Zotero: not reachable. Start Zotero 10, then in Zotero open Settings > Advanced and turn on \"Allow other applications on this computer to communicate with Zotero\".");
+    if (starbuck === "on")
+        io.say(starbuckNote || "Reference checks: on. The first start downloads Starbuck.");
     if (fmup)
         io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, connect a model provider yourself.");
     io.say("Next: type subsub web to open Sub-Sub in your browser (or subsub for the terminal). Connect a model provider with the model button (or /login in the terminal). To check the setup, type subsub doctor.");
@@ -203,7 +213,11 @@ export async function initMain(args, env = process.env) {
     const flags = parseFlags(args);
     const io = flags.yes || !process.stdin.isTTY ? defaultsIO((l) => console.log(l)) : terminalIO();
     try {
-        await runInit(io, flags, env);
+        await runInit(io, flags, env, { prepareStarbuck: (cfg) => {
+                // Download Starbuck now, so that the first start of Sub-Sub does not wait for it.
+                const c = starbuckCheck(cfg, env, defaultRunner);
+                return c.ok ? `Reference checks: on (${c.detail}).` : `Reference checks: on, but ${c.detail}. ${c.fix ?? ""}`.trim();
+            } });
         return 0;
     }
     catch (err) {

package/dist/notes.js

@@ -0,0 +1,42 @@
+/**
+ * Checks on the literature notes the researcher writes (a note whose front matter has a
+ * citekey). Each note must say what it was written from (evidence: full text, abstract
+ * or metadata), and only a note written from the full text may give page numbers.
+ * The write gate calls these before a write or edit runs; a failed check blocks the call
+ * with a reason, so the model corrects the note.
+ */
+export const EVIDENCE = ["full text", "abstract", "metadata"];
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const PAGES = /\b(?:pp?\.|pages?)\s?\d+/i;
+export function frontMatter(text) {
+    return FRONT.exec(text)?.[1];
+}
+export function field(front, name) {
+    const m = new RegExp(`^${name}:[ \\t]*(.*)$`, "m").exec(front);
+    return m ? m[1].trim().replace(/^["']|["']$/g, "").trim() : undefined;
+}
+/** Why a new literature note cannot be written as it is, or undefined when it can. */
+export function checkLiteratureNote(text) {
+    const m = FRONT.exec(text);
+    if (!m || !field(m[1], "citekey"))
+        return undefined;
+    const evidence = field(m[1], "evidence")?.toLowerCase();
+    if (!evidence || !EVIDENCE.includes(evidence)) {
+        return 'A literature note needs "evidence:" in its front matter, with one of: full text, abstract, metadata (what you read to write it). Add it and write the note again.';
+    }
+    const body = text.slice(m[0].length);
+    if (evidence !== "full text" && PAGES.test(body)) {
+        return `This note says evidence: ${evidence}, but it gives page numbers. Page numbers come only from the full text: remove them, or read the full text and set evidence: full text.`;
+    }
+    return undefined;
+}
+/** The text of a file after pi's edit tool applies edits[] (each oldText matched against the original). */
+export function applyEdits(current, edits) {
+    let out = current;
+    for (const e of edits) {
+        const oldText = String(e.oldText ?? "");
+        if (oldText && out.includes(oldText))
+            out = out.replace(oldText, () => String(e.newText ?? ""));
+    }
+    return out;
+}

package/dist/profiles.js

@@ -18,6 +18,7 @@ export const PROFILE_SPECS = {
         label: "Reader",
         summary: "explains each step; reading notes are quotes and questions; no summaries; no bulk library changes",
         without: [...BULK_LIBRARY, ...MANUSCRIPT],
+        withoutPrompts: ["lit", "compare", "review", "digest"],
         batch: 10,
         rules: [
             "Profile: Reader. {{User}} is learning to work with the literature and wants to do the reading and the writing.",
@@ -33,6 +34,7 @@ export const PROFILE_SPECS = {
         label: "Scholar",
         summary: "literature notes, syntheses, searches and alerts; the full librarian",
         without: MANUSCRIPT,
+        withoutPrompts: ["review"],
         batch: 25,
         rules: [
             "Profile: Scholar.",
@@ -46,6 +48,7 @@ export const PROFILE_SPECS = {
         label: "Author",
         summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
         without: [],
+        withoutPrompts: [],
         batch: 25,
         rules: [
             "Profile: Author.",
@@ -60,6 +63,7 @@ export const PROFILE_SPECS = {
         label: "Editor",
         summary: "everything, including drafting manuscript text on request",
         without: [],
+        withoutPrompts: [],
         batch: 25,
         rules: [
             "Profile: Editor. All tools.",
@@ -72,6 +76,17 @@ export const PROFILE_SPECS = {
 export function profileSpec(p) {
     return PROFILE_SPECS[p];
 }
+/** Why a prompt command does not run in this profile, or undefined when it does. */
+export function promptBlocked(text, profile) {
+    const m = /^\/([\w-]+)(?:\s|$)/.exec(text.trim());
+    if (!m || !PROFILE_SPECS[profile].withoutPrompts.includes(m[1]))
+        return undefined;
+    const allowed = Object.values(PROFILE_SPECS)
+        .filter((s) => !s.withoutPrompts.includes(m[1]))
+        .map((s) => s.label)
+        .join(", ");
+    return `/${m[1]} is not part of the ${PROFILE_SPECS[profile].label} profile (it is in: ${allowed}). Change the profile with /profile.`;
+}
 export function profileList(current) {
     return Object.values(PROFILE_SPECS)
         .map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)

package/dist/prompt.js

@@ -65,6 +65,9 @@ export function systemAddition(mode, cfg, cwd) {
                 parts.push(`# Vault conventions (${f})`, t);
         }
     }
+    if (cfg.setup === "fmup") {
+        parts.push("# U.Porto", `${capital(user)} works at the University of Porto. Papers that are not open access often open through the university's subscriptions when ${user} uses Sub-Sub on the U.Porto network: say so when a work is not open access.`);
+    }
     // The profile and the language rule come last, so they win over the shared rules and the vault conventions.
     parts.push("# Profile", fill(profileSpec(cfg.profile).rules, cfg));
     parts.push("# Language", languageRule(cfg.language, user));

package/dist/roles.js

@@ -3,6 +3,8 @@
  */
 import { profileSpec } from "./profiles.js";
 export const FILE_TOOLS = ["read", "edit", "write", "grep", "find", "ls"];
+/** Prefixes of the tools that Sub-Sub's servers provide (the gate checks the mode for these). */
+export const SERVER_PREFIXES = ["zotero_", "scholar_", "verify_"];
 export const ZOTERO_READ = [
     "status",
     "library_overview",
@@ -43,7 +45,11 @@ export function toolsFor(mode, registered, profile = "editor") {
     const without = new Set(profileSpec(profile).without);
     const wanted = mode === "librarian"
         ? [...registered.filter((n) => n.startsWith("zotero_")), ...FILE_TOOLS]
-        : [...ZOTERO_READ, ...registered.filter((n) => n.startsWith("scholar_")), ...FILE_TOOLS];
+        : [
+            ...ZOTERO_READ,
+            ...registered.filter((n) => n.startsWith("scholar_") || n.startsWith("verify_")),
+            ...FILE_TOOLS,
+        ];
     return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
 }
 /** Why a Sub-Sub tool is not available now, or undefined when it is. */

package/dist/subsub.js

@@ -8,22 +8,25 @@
  * - 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.
+ * - Add-on: with "addons": ["starbuck"], Starbuck runs as a third server
+ *   ("verify") for reference checks; its tools belong to researcher mode.
  *
  * 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 { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
-import { expand, findUv, isProfile, loadConfig, saveConfig, serverCommand, who } from "./config.js";
-import { profileList, profileSpec } from "./profiles.js";
+import { expand, findUv, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, who, } from "./config.js";
+import { profileList, profileSpec, promptBlocked } from "./profiles.js";
 import { coerceArgs, loosenArrays } from "./args.js";
+import { applyEdits, checkLiteratureNote } from "./notes.js";
 import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview } from "./preview.js";
 import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
 import { systemAddition } from "./prompt.js";
-import { gateKind, toolsFor, unavailableReason } from "./roles.js";
+import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.js";
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 const MODE_ENTRY = "subsub-mode";
 const BENCH_ENTRY = "subsub-bench";
@@ -36,12 +39,32 @@ function ownVersion() {
     }
 }
 export { findUv };
-export function serverSpecs(cfg) {
+export function serverSpecs(cfg, processEnv = process.env) {
     const env = cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {};
-    return [
-        { name: "zotero", ...serverCommand(cfg, "zotero-local-mcp"), env },
-        { name: "scholar", ...serverCommand(cfg, "zotero-scholar-mcp"), env },
+    const specs = [
+        { name: "zotero", ...serverCommand(cfg, "zotero-local-mcp", [], processEnv), env },
+        { name: "scholar", ...serverCommand(cfg, "zotero-scholar-mcp", [], processEnv), env },
     ];
+    if (starbuckEnabled(cfg))
+        specs.push({ name: "verify", ...starbuckCommand(cfg, processEnv), env: starbuckEnv(cfg, processEnv) });
+    return specs;
+}
+/**
+ * Starbuck reads its contact address and API keys from the environment. Sub-Sub keeps
+ * them in the zotero-local-mcp env file, so they are passed on (the environment wins).
+ */
+export function starbuckEnv(cfg, processEnv = process.env) {
+    const file = cfg.envFile ? parseEnvFile(cfg.envFile) : {};
+    const out = {};
+    const email = processEnv.STARBUCK_EMAIL || file.STARBUCK_EMAIL || processEnv.ZOTERO_CONTACT_EMAIL || file.ZOTERO_CONTACT_EMAIL;
+    if (email)
+        out.STARBUCK_EMAIL = email;
+    for (const key of ["NCBI_API_KEY", "OPENALEX_API_KEY"]) {
+        const v = processEnv[key] || file[key];
+        if (v)
+            out[key] = v;
+    }
+    return out;
 }
 export async function createSubsub(pi, deps = {}) {
     const cfg = deps.config ?? loadConfig();
@@ -111,6 +134,7 @@ export async function createSubsub(pi, deps = {}) {
             language: cfg.language,
             userName: cfg.userName ?? null,
             vault: cfg.vault ?? null,
+            starbuck: starbuckEnabled(cfg),
         };
         try {
             ctx.ui.setStatus("subsub.web", JSON.stringify(state));
@@ -245,6 +269,15 @@ export async function createSubsub(pi, deps = {}) {
         await b?.close();
     });
     pi.on("model_select", async (_event, ctx) => status(ctx));
+    // 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.
+    pi.on("input", async (event, ctx) => {
+        const why = promptBlocked(event.text, profile);
+        if (!why)
+            return { action: "continue" };
+        ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
+        return { action: "handled" };
+    });
     pi.on("before_agent_start", async (event, ctx) => ({
         systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
     }));
@@ -258,7 +291,7 @@ export async function createSubsub(pi, deps = {}) {
         const schema = schemas.get(name);
         if (schema)
             coerceArgs(schema, input);
-        if (name.startsWith("zotero_") || name.startsWith("scholar_")) {
+        if (SERVER_PREFIXES.some((p) => name.startsWith(p))) {
             const why = unavailableReason(name, mode, registered(), profile);
             if (why) {
                 if (benchOut)
@@ -266,6 +299,8 @@ export async function createSubsub(pi, deps = {}) {
                 return { block: true, reason: why };
             }
         }
+        if (name.startsWith("verify_"))
+            return verifyGate(name, input, ctx);
         const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
         if (!kind)
             return undefined;
@@ -273,6 +308,9 @@ export async function createSubsub(pi, deps = {}) {
             return benchGate(name, input, kind, ctx.cwd, ctx.signal);
         if (kind === "path") {
             const target = normalizeToolPath(String(input.path ?? ""), ctx.cwd);
+            const noteProblem = literatureNoteProblem(name, target, input);
+            if (noteProblem)
+                return { block: true, reason: noteProblem };
             const verdict = judgePath(target, buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
             if (verdict.ok)
                 return undefined;
@@ -303,9 +341,56 @@ export async function createSubsub(pi, deps = {}) {
         const ok = await ctx.ui.confirm(`Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`, paintFor(ctx)(formatPreview(name, preview.data ?? preview.text)));
         return ok ? undefined : { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
     });
+    /** A literature note (front matter with a citekey) must state its evidence; see notes.ts. */
+    function literatureNoteProblem(name, target, input) {
+        if (!target.toLowerCase().endsWith(".md"))
+            return undefined;
+        if (name === "write")
+            return checkLiteratureNote(String(input.content ?? ""));
+        if (name === "edit" && Array.isArray(input.edits) && existsSync(target)) {
+            const current = readFileSync(target, "utf8");
+            return checkLiteratureNote(applyEdits(current, input.edits));
+        }
+        return undefined;
+    }
+    /**
+     * Starbuck writes its reports into a folder: report_dir, or _starbuck next to the
+     * manuscript. Inside the vault or the working folder that needs no approval; elsewhere
+     * Sub-Sub asks, as for any file write. record_claims gets the current model's name.
+     */
+    async function verifyGate(name, input, ctx) {
+        if (name === "verify_record_claims") {
+            input.judged_by = ctx.model ? [ctx.model.provider, ctx.model.id].filter(Boolean).join("/") : "the agent's model";
+        }
+        if (name === "verify_check_references")
+            return undefined;
+        const dir = input.report_dir
+            ? normalizeToolPath(String(input.report_dir), ctx.cwd)
+            : input.path
+                ? join(dirname(normalizeToolPath(String(input.path), ctx.cwd)), "_starbuck")
+                : undefined;
+        if (!dir)
+            return undefined;
+        const verdict = judgePath(dir, buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
+        if (verdict.ok)
+            return undefined;
+        if (benchOut) {
+            record({ kind: "path_blocked", tool: name, path: dir });
+            return { block: true, reason: `Model test: Starbuck reports only inside the vault or ${benchOut}.` };
+        }
+        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(`Sub-Sub: write the Starbuck report to ${dir}?`, `Asking because ${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) {
         if (kind === "path") {
             const target = normalizeToolPath(String(input.path ?? ""), cwd);
+            const noteProblem = literatureNoteProblem(name, target, input);
+            if (noteProblem) {
+                record({ kind: "note_blocked", tool: name, path: target, reason: noteProblem });
+                return { block: true, reason: noteProblem };
+            }
             if (within(target, realish(benchOut)))
                 return undefined;
             record({ kind: "path_blocked", tool: name, path: target });

package/dist/web.js

@@ -21,9 +21,9 @@ import { homedir } from "node:os";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
-import { expand, loadConfig, saveConfig } from "./config.js";
+import { expand, loadConfig, saveConfig, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
-import { within } from "./paths.js";
+import { realish, within } from "./paths.js";
 export function parseWebArgs(args) {
     const o = { port: 0, open: true, librarian: false, here: false, idleMinutes: 10, piArgs: [] };
     for (let i = 0; i < args.length; i++) {
@@ -559,6 +559,17 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     await restartAgent();
                     return send(res, 200, { ok: true });
                 }
+                case "POST /api/addons": {
+                    // Turn an add-on on or off, then restart pi so the extension starts or stops its server.
+                    if (busy)
+                        return send(res, 409, { error: "busy" });
+                    const body = await readJson(req);
+                    if (typeof body.starbuck !== "boolean")
+                        return send(res, 400, { error: "starbuck must be true or false" });
+                    saveConfig({ addons: withStarbuck(loadConfig(env).addons, body.starbuck) }, env);
+                    await restartAgent();
+                    return send(res, 200, { ok: true });
+                }
                 case "POST /api/restart":
                     if (agent.proc)
                         return send(res, 200, { ok: true });
@@ -580,7 +591,10 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     const body = await readJson(req);
                     const target = resolve(cwd, expand(String(body.path ?? "")));
                     const vault = cfg.vault;
-                    if (!(within(target, cwd) || (vault && within(target, vault))) || !existsSync(target))
+                    // Judge the real file, so a link inside the notes 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))
                         return send(res, 404, { error: "not found in the notes 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.6.1",
+  "version": "0.8.0",
   "description": "Sub-Sub: a Zotero librarian and research assistant in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
@@ -26,9 +26,11 @@
     ]
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
     "@modelcontextprotocol/sdk": "^1.30.1"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.4"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -55,9 +57,11 @@
     "src",
     "templates",
     "themes",
-    "web"
+    "web",
+    "THIRD_PARTY_NOTICES"
   ],
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.4",
     "@types/node": "^24.19.0",
     "typescript": "^5.9.3"
   },

package/prompts/compare.md

@@ -0,0 +1,23 @@
+---
+description: "Researcher: compare sources on a question (a source matrix: claim, evidence type, caveats, confidence)"
+argument-hint: "<question, or citekeys, DOIs or PMIDs>"
+---
+Compare the sources on: $ARGUMENTS
+
+Make a short slug: lower case, hyphens, at most five words. Use today's date (YYYY-MM-DD).
+
+1. Find the sources.
+   - If the user gave citekeys, DOIs or PMIDs, use exactly those.
+   - Otherwise: library first (zotero_find_items), then scholar_search_multi with three phrasings. Choose 3 to 10 sources and say why.
+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.
+   - 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.
+5. Check the sources: verify_check_references when the verify_ tools are available, otherwise scholar_get_work for each identifier. Never write "verified" for a check you did not run.
+6. Write one note: `Research/<date> <slug> comparison.md` in the notes folder (do not overwrite; add -2). Front matter: title, date, type: comparison, sources (the identifiers), verification (PASS, PASS WITH NOTES or BLOCKED), reference_check (path of the Starbuck report, or none). End with a Sources section: [@citekey] for library items, full reference with DOI and "(not in library)" for the others.
+7. If a step fails, finish the note anyway and mark the step "BLOCKED: <what failed>".
+
+Give the user the path and three lines on what the comparison shows.

package/prompts/digest.md

@@ -0,0 +1,23 @@
+---
+description: "Researcher: digest of the last days: new works from the alerts and what the recent notes changed"
+argument-hint: "[days, default 7] [topic]"
+---
+Write a digest of the last ${1:-7} days. Topic, if given: ${@:2}
+
+1. Collect, in the notes folder:
+   - the alert notes `Inbox/Literature alerts YYYY-MM-DD.md` dated in the period (the date is in the file name);
+   - the notes in `Research/` whose front matter `date:` is in the period;
+   - the literature notes whose front matter `created:` is in the period.
+   Use ls and find to list them, and read their front matter for the dates. If a topic is given, keep only what is about it.
+2. Read each note you use. Do not describe a work that you did not read in a note, an abstract (scholar_get_work) or a full text.
+3. Write `Research/Digest <today, YYYY-MM-DD>.md` (do not overwrite; add -2) with these sections, in this order:
+   - What changed in our understanding: what the period's notes and works add to or change in what the user knew, each point with its sources.
+   - New works worth reading: at most ten from the alerts, one line each on why, with DOI or PMID and whether it is in the library. Mark the ones the alert pre-screen excluded only if you keep them, and say why.
+   - Disagreements and open questions: between the new works, or between them and the earlier notes.
+   - Questions for the user: decisions that need the user (what to read, what to import, what to drop).
+   - Sources: [@citekey] for library items; full reference with DOI and "(not in library)" for the others.
+   Front matter: title, date, type: digest, period (from and to), sources (the notes and alert files used).
+4. If there is nothing in the period, say so in one line and do not write a note.
+5. Offer scholar_queue_imports for the works the user wants to add.
+
+Give the user the path and the three most important points.