@tiagojct/subsub 0.6.0 → 0.7.0

package/dist/config.js

@@ -12,15 +12,24 @@
  *
  * `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 function expand(p) {
-    return resolve(p.replace(/^~(?=$|\/)/, homedir()));
+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));
 }
 export function parseEnvFile(path) {
     const out = {};
@@ -41,7 +50,7 @@ export function parseEnvFile(path) {
     return out;
 }
 export function configPath(env = process.env) {
-    return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json");
+    return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json", env.HOME);
 }
 export function readConfigFile(file) {
     if (!existsSync(file))
@@ -68,6 +77,7 @@ export function isProfile(x) {
     return typeof x === "string" && PROFILES.includes(x);
 }
 export function loadConfig(env = process.env) {
+    const home = env.HOME;
     const file = configPath(env);
     let user = {};
     if (existsSync(file)) {
@@ -78,16 +88,18 @@ export function loadConfig(env = process.env) {
             throw new Error(`Sub-Sub: cannot read ${file}: ${err.message}`);
         }
     }
-    const envCandidates = [
-        user.envFile,
-        env.ZOTERO_MCP_ENV,
-        "~/.config/zotero-local-mcp/env",
-        "~/.config/opencode/zotero.env",
-    ].filter((x) => Boolean(x));
-    const envFile = envCandidates.map(expand).find((p) => existsSync(p));
-    const envValues = envFile ? parseEnvFile(envFile) : {};
+    const explicitEnv = user.envFile ?? env.ZOTERO_MCP_ENV;
+    const envFile = explicitEnv
+        ? expand(explicitEnv, home)
+        : [
+            "~/.config/zotero-local-mcp/env",
+            "~/.config/opencode/zotero.env",
+        ]
+            .map((p) => expand(p, home))
+            .find((p) => existsSync(p));
+    const envValues = envFile && existsSync(envFile) ? parseEnvFile(envFile) : {};
     const vaultRaw = user.vault ?? env.ZOTERO_VAULT ?? envValues.ZOTERO_VAULT;
-    const vault = vaultRaw ? expand(vaultRaw) : undefined;
+    const vault = vaultRaw ? expand(vaultRaw, home) : undefined;
     const mode = user.defaultMode === "librarian" ? "librarian" : "researcher";
     return {
         configFile: file,
@@ -96,7 +108,7 @@ export function loadConfig(env = process.env) {
         about: typeof user.about === "string" && user.about.trim() ? user.about.trim() : undefined,
         language: typeof user.language === "string" && user.language.trim() ? user.language.trim() : "English",
         setup: user.setup,
-        serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp"),
+        serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp", home),
         envFile,
         vault,
         models: user.models ?? {
@@ -104,26 +116,29 @@ export function loadConfig(env = process.env) {
             researcher: "opencode-go/mimo-v2.6-pro",
         },
         defaultMode: mode,
-        vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map(expand),
+        vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map((p) => expand(p, home)),
         sharedRules: user.sharedRules
-            ? expand(user.sharedRules)
+            ? expand(user.sharedRules, home)
             : vault
                 ? join(vault, "Systems", "Zotero agent.md")
                 : undefined,
         startTimeout: user.startTimeout ?? 45,
-        uvPath: user.uvPath ? expand(user.uvPath) : undefined,
+        uvPath: user.uvPath ? expand(user.uvPath, home) : undefined,
         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. */
 export function findUv(cfg, env = process.env, platform = process.platform) {
+    const home = env.HOME;
     const unix = ["~/.local/bin/uv", "/opt/homebrew/bin/uv", "/usr/local/bin/uv", "~/.cargo/bin/uv"];
     const windows = ["~/.local/bin/uv.exe", "~/.cargo/bin/uv.exe", env.LOCALAPPDATA ? join(env.LOCALAPPDATA, "uv", "uv.exe") : ""];
     const candidates = [cfg.uvPath, env.SUBSUB_UV, ...(platform === "win32" ? windows : unix)]
         .filter((x) => Boolean(x))
-        .map(expand);
+        .map((p) => expand(p, home));
     return candidates.find((p) => existsSync(p)) ?? "uv";
 }
 /**
@@ -138,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 = {
@@ -63,11 +65,12 @@ export async function zoteroReachable(fetchFn = fetch) {
     }
 }
 export async function runInit(io, flags, env = process.env, deps = {}) {
-    const home = deps.home ?? homedir();
-    const configFile = configPath(env);
+    const home = deps.home ?? env.HOME ?? homedir();
+    const initEnv = { ...env, HOME: home };
+    const configFile = configPath(initEnv);
     const existing = readConfigFile(configFile);
-    const current = loadConfig(env);
-    const envFile = current.envFile ?? expand(env.ZOTERO_MCP_ENV ?? join(home, ".config", "zotero-local-mcp", "env"));
+    const current = loadConfig(initEnv);
+    const envFile = current.envFile ?? expand(initEnv.ZOTERO_MCP_ENV ?? join(home, ".config", "zotero-local-mcp", "env"), home);
     const envValues = existsSync(envFile) ? parseEnvFile(envFile) : {};
     const created = [];
     io.say(existsSync(configFile) ? `Sub-Sub settings (${configFile}). Press Enter to keep the value in brackets.` : "Sub-Sub setup. Press Enter to take the value in brackets.");
@@ -79,10 +82,10 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     const userName = (await io.ask("Your name, for Sub-Sub's replies (Enter for none)", flags.name ?? existing.userName ?? "")).trim();
     const about = (await io.ask('One line about you, e.g. "a master\'s student in health informatics" (optional)', flags.about ?? existing.about ?? "")).trim();
     const language = (await io.ask("Language for replies and notes (a language, or auto for the language you write in)", flags.language ?? existing.language ?? "English")).trim() || "English";
-    const notes = expand((await io.ask("Notes folder (Markdown files; an Obsidian vault works)", flags.notes ?? current.vault ?? envValues.ZOTERO_VAULT ?? join(home, "Documents", "Sub-Sub"))).trim());
+    const notes = expand((await io.ask("Notes folder (Markdown files; an Obsidian vault works)", flags.notes ?? current.vault ?? envValues.ZOTERO_VAULT ?? join(home, "Documents", "Sub-Sub"))).trim(), home);
     const profileDefault = flags.profile ?? existing.profile ?? (fmup ? "reader" : "scholar");
     const profile = await io.choose("Profile (change it later with /profile)", PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })), isProfile(profileDefault) ? profileDefault : "scholar");
-    const vocab = envValues.ZOTERO_VOCAB ? expand(envValues.ZOTERO_VOCAB) : join(notes, "Systems", "Zotero tags.md");
+    const vocab = envValues.ZOTERO_VOCAB ? expand(envValues.ZOTERO_VOCAB, home) : join(notes, "Systems", "Zotero tags.md");
     let tags = "keep";
     if (existsSync(vocab)) {
         io.say(`Tag list: keeping ${vocab}.`);
@@ -91,12 +94,16 @@ 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)" },
         { value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODELS.librarian} for the librarian, ${TESTED_MODELS.researcher} for the researcher` },
     ];
-    const agentDir = env.SUBSUB_AGENT_DIR ? expand(env.SUBSUB_AGENT_DIR) : join(home, ".subsub", "agent");
+    const agentDir = initEnv.SUBSUB_AGENT_DIR ? expand(initEnv.SUBSUB_AGENT_DIR, home) : join(home, ".subsub", "agent");
     const modelDefault = existing.models ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
     const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
     // ---- write
@@ -127,13 +134,15 @@ 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 = {};
     if (models === "opencode-go")
         patch.models = TESTED_MODELS;
-    saveConfig(patch, env);
+    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}`);
@@ -142,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.");
@@ -202,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()))