@tiagojct/subsub 0.6.0 → 0.7.0

package/src/doctor.ts

@@ -3,14 +3,24 @@
  *
  * 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, type SubsubConfig } from "./config.ts";
+import {
+	findUv,
+	loadConfig,
+	SERVER_VERSION,
+	serverCommand,
+	STARBUCK_SOURCE,
+	starbuckCommand,
+	starbuckEnabled,
+	type SubsubConfig,
+} from "./config.ts";
 import { profileSpec } from "./profiles.ts";
 
 export interface Check {
@@ -137,6 +147,7 @@ export function runChecks(
 			? { 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)
@@ -146,6 +157,25 @@ export function runChecks(
 	return out;
 }
 
+/** The Starbuck add-on: can uv start it? (`starbuck --version`, from the local folder or the pinned release) */
+export function starbuckCheck(cfg: SubsubConfig, env: NodeJS.ProcessEnv, run: Runner): Check {
+	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: Check[]): string {
 	return checks
 		.map((c) => {

package/src/init.ts

@@ -12,7 +12,8 @@
  *
  * 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";
@@ -20,7 +21,20 @@ 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.ts";
+import {
+	configPath,
+	expand,
+	isProfile,
+	loadConfig,
+	parseEnvFile,
+	PROFILES,
+	readConfigFile,
+	saveConfig,
+	starbuckEnabled,
+	type SubsubConfig,
+	withStarbuck,
+} from "./config.ts";
+import { defaultRunner, starbuckCheck } from "./doctor.ts";
 import { PROFILE_SPECS } from "./profiles.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
@@ -83,13 +97,14 @@ export async function runInit(
 	io: InitIO,
 	flags: Record<string, string>,
 	env: NodeJS.ProcessEnv = process.env,
-	deps: { fetch?: typeof fetch; home?: string } = {},
+	deps: { fetch?: typeof fetch; home?: string; prepareStarbuck?: (cfg: SubsubConfig) => string } = {},
 ): Promise<InitResult> {
-	const home = deps.home ?? homedir();
-	const configFile = configPath(env);
+	const home = deps.home ?? env.HOME ?? homedir();
+	const initEnv: NodeJS.ProcessEnv = { ...env, HOME: home };
+	const configFile = configPath(initEnv);
 	const existing = readConfigFile(configFile) as Record<string, any>;
-	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: string[] = [];
 
@@ -109,6 +124,7 @@ export async function runInit(
 	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(),
+		home,
 	);
 	const profileDefault = flags.profile ?? existing.profile ?? (fmup ? "reader" : "scholar");
 	const profile = await io.choose(
@@ -117,7 +133,7 @@ export async function runInit(
 		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}.`);
@@ -131,12 +147,20 @@ export async function runInit(
 	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);
 
@@ -169,12 +193,14 @@ export async function runInit(
 		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}`);
@@ -184,6 +210,7 @@ export async function runInit(
 			? "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.");
 	return { configFile, envFile, notes, created, zotero };
@@ -241,7 +268,11 @@ export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.
 	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) {
 		console.error(`Sub-Sub init: ${(err as Error).message}`);

package/src/notes.ts

@@ -0,0 +1,46 @@
+/**
+ * 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"] as const;
+
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const PAGES = /\b(?:pp?\.|pages?)\s?\d+/i;
+
+export function frontMatter(text: string): string | undefined {
+	return FRONT.exec(text)?.[1];
+}
+
+export function field(front: string, name: string): string | undefined {
+	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: string): string | undefined {
+	const m = FRONT.exec(text);
+	if (!m || !field(m[1], "citekey")) return undefined;
+	const evidence = field(m[1], "evidence")?.toLowerCase();
+	if (!evidence || !(EVIDENCE as readonly string[]).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: string, edits: Array<{ oldText?: unknown; newText?: unknown }>): string {
+	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/src/profiles.ts

@@ -19,6 +19,8 @@ export interface ProfileSpec {
 	summary: string;
 	/** Tools this profile does not offer (full names). */
 	without: string[];
+	/** Prompt commands this profile does not run (names without the slash). */
+	withoutPrompts: string[];
 	/** Items per review note and per batch. */
 	batch: number;
 	/** Added to the system prompt. {{user}} is the user's name or "the user". */
@@ -36,6 +38,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		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.",
@@ -51,6 +54,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Scholar",
 		summary: "literature notes, syntheses, searches and alerts; the full librarian",
 		without: MANUSCRIPT,
+		withoutPrompts: ["review"],
 		batch: 25,
 		rules: [
 			"Profile: Scholar.",
@@ -64,6 +68,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Author",
 		summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
 		without: [],
+		withoutPrompts: [],
 		batch: 25,
 		rules: [
 			"Profile: Author.",
@@ -78,6 +83,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Editor",
 		summary: "everything, including drafting manuscript text on request",
 		without: [],
+		withoutPrompts: [],
 		batch: 25,
 		rules: [
 			"Profile: Editor. All tools.",
@@ -92,6 +98,17 @@ export function profileSpec(p: Profile): ProfileSpec {
 	return PROFILE_SPECS[p];
 }
 
+/** Why a prompt command does not run in this profile, or undefined when it does. */
+export function promptBlocked(text: string, profile: Profile): string | undefined {
+	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?: Profile): string {
 	return Object.values(PROFILE_SPECS)
 		.map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)

package/src/prompt.ts

@@ -74,6 +74,12 @@ export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): stri
 			if (t) 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/src/roles.ts

@@ -7,6 +7,9 @@ import { profileSpec } from "./profiles.ts";
 
 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",
@@ -51,7 +54,11 @@ export function toolsFor(mode: Mode, registered: string[], profile: Profile = "e
 	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));
 }
 

package/src/subsub.ts

@@ -8,24 +8,41 @@
  * - 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 type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge, type ServerSpec } from "./bridge.ts";
-import { expand, findUv, isProfile, loadConfig, type Mode, type Profile, saveConfig, serverCommand, type SubsubConfig, who } from "./config.ts";
-import { profileList, profileSpec } from "./profiles.ts";
+import {
+	expand,
+	findUv,
+	isProfile,
+	loadConfig,
+	type Mode,
+	parseEnvFile,
+	type Profile,
+	saveConfig,
+	serverCommand,
+	starbuckCommand,
+	starbuckEnabled,
+	type SubsubConfig,
+	who,
+} from "./config.ts";
+import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays } from "./args.ts";
+import { applyEdits, checkLiteratureNote } from "./notes.ts";
 import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
 import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
 import { systemAddition } from "./prompt.ts";
-import { gateKind, toolsFor, unavailableReason } from "./roles.ts";
+import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.ts";
 
 export interface SubsubDeps {
 	config?: SubsubConfig;
@@ -48,12 +65,30 @@ function ownVersion(): string {
 
 export { findUv };
 
-export function serverSpecs(cfg: SubsubConfig): ServerSpec[] {
+export function serverSpecs(cfg: SubsubConfig, processEnv: NodeJS.ProcessEnv = process.env): ServerSpec[] {
 	const env: Record<string, string> = 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: ServerSpec[] = [
+		{ 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: Pick<SubsubConfig, "envFile">, processEnv: NodeJS.ProcessEnv = process.env): Record<string, string> {
+	const file = cfg.envFile ? parseEnvFile(cfg.envFile) : {};
+	const out: Record<string, string> = {};
+	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: ExtensionAPI, deps: SubsubDeps = {}): Promise<void> {
@@ -125,6 +160,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			language: cfg.language,
 			userName: cfg.userName ?? null,
 			vault: cfg.vault ?? null,
+			starbuck: starbuckEnabled(cfg),
 		};
 		try {
 			ctx.ui.setStatus("subsub.web", JSON.stringify(state));
@@ -262,6 +298,15 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 
 	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)}`,
 	}));
@@ -276,18 +321,21 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		// Previews and the real call must see the same, repaired arguments.
 		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) record({ kind: "wrong_mode", tool: name, input });
 				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;
 		if (benchOut) 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;
 			if (!ctx.hasUI) return { block: true, reason: `Writing ${target} needs ${user}'s approval: ${verdict.why}.` };
@@ -318,9 +366,52 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		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: string, target: string, input: Record<string, unknown>): string | undefined {
+		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 as Array<{ oldText?: unknown; newText?: unknown }>));
+		}
+		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: string, input: Record<string, unknown>, ctx: ExtensionContext) {
+		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: string, input: Record<string, unknown>, kind: string, cwd: string, signal?: AbortSignal) {
 		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 });
 			return { block: true, reason: `Model test: write only inside ${benchOut}.` };

package/src/web.ts

@@ -22,9 +22,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.ts";
-import { expand, loadConfig, saveConfig, type SubsubConfig } from "./config.ts";
+import { expand, loadConfig, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
 import { TESTED_MODELS } from "./init.ts";
-import { within } from "./paths.ts";
+import { realish, within } from "./paths.ts";
 
 // ---------------------------------------------------------------- options
 
@@ -577,6 +577,15 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					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 });
 					agent.start();
@@ -595,7 +604,10 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					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)) return send(res, 404, { error: "not found in the notes folder" });
+					// 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())) return send(res, 403, { error: "Sub-Sub opens only notes and documents (.md, .txt, .pdf, .bib, .csv, .qmd)." });
 					if (vault && within(target, vault) && existsSync(join(vault, ".obsidian"))) openExternal(`obsidian://open?path=${encodeURIComponent(target)}`);

package/templates/Zotero agent.md

@@ -40,6 +40,7 @@ Shared rules for the Sub-Sub librarian and researcher. Sub-Sub reads this file a
 - Folder: Literature/. File name: the citekey (smith2026.md).
 - Create a note only when the user asks. Ask before creating more than 10 notes.
 - Write from the full text (get_fulltext) when it exists. Otherwise use the abstract and the Zotero notes, and write "(from abstract)" after the summary.
+- Front matter field evidence: full text, abstract or metadata (what you read). Page numbers only with evidence: full text. Sub-Sub refuses a literature note without this field.
 - Do not copy the abstract in full. Give page numbers for quotes when the text shows them.
 - If a note for the citekey exists, do not overwrite it. Add a dated section or ask.
 - After the note is written, offer to link it in Zotero with attach_note.
@@ -58,6 +59,7 @@ item-type: journalArticle
 venue: Journal name
 doi: 10.xxxx/xxxxx
 zotero: zotero://select/library/items/ITEMKEY
+evidence: full text
 status: to-read
 tags:
   - topic/example

package/themes/subsub-glauca-dark.json

@@ -2,28 +2,28 @@
 	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
 	"name": "subsub-glauca-dark",
 	"vars": {
-		"bg": "#10161c",
-		"surface": "#171f26",
-		"raised": "#1f2932",
-		"text": "#e8eef2",
-		"muted": "#8c8c8c",
-		"line": "#2a3540",
-		"mark": "#3d97ff",
-		"markBright": "#6cb2ff",
-		"markDeep": "#007aff",
-		"toneDeep": "#142430",
-		"tone": "#2b4356",
-		"toneBright": "#4d7391",
-		"tonePale": "#93b7c9",
-		"green": "#62ba46",
-		"red": "#b85f5f",
-		"yellow": "#c79a3d",
-		"violet": "#b184db",
-		"link": "#4a9edb",
-		"dim": "#616365",
-		"select": "#2b4356",
-		"okBg": "#22352a",
-		"errBg": "#31292f"
+		"bg": "#121517",
+		"surface": "#181d20",
+		"raised": "#20272b",
+		"text": "#e5ebec",
+		"muted": "#8a9699",
+		"line": "#283236",
+		"mark": "#5d99be",
+		"markBright": "#78b4da",
+		"markDeep": "#41789c",
+		"toneDeep": "#0e181c",
+		"tone": "#263e48",
+		"toneBright": "#486e7e",
+		"tonePale": "#8cb6cb",
+		"green": "#68aa80",
+		"red": "#cf5c5c",
+		"yellow": "#c49a46",
+		"violet": "#9d82b3",
+		"link": "#78b4da",
+		"dim": "#5d6a6d",
+		"select": "#263e48",
+		"okBg": "#1b2920",
+		"errBg": "#331c19"
 	},
 	"colors": {
 		"accent": "mark",
@@ -65,15 +65,15 @@
 		"toolDiffAdded": "green",
 		"toolDiffRemoved": "red",
 		"toolDiffContext": "muted",
-		"syntaxComment": "#8c8c8c",
-		"syntaxKeyword": "#007aff",
-		"syntaxFunction": "#4a9edb",
-		"syntaxVariable": "#e8eef2",
-		"syntaxString": "#62ba46",
-		"syntaxNumber": "#b184db",
-		"syntaxType": "#45a3ad",
-		"syntaxOperator": "#a7b1b8",
-		"syntaxPunctuation": "#86929a",
+		"syntaxComment": "#5d6a6d",
+		"syntaxKeyword": "#78b4da",
+		"syntaxFunction": "#5d99be",
+		"syntaxVariable": "#e5ebec",
+		"syntaxString": "#68aa80",
+		"syntaxNumber": "#9d82b3",
+		"syntaxType": "#8cb6cb",
+		"syntaxOperator": "#8a9699",
+		"syntaxPunctuation": "#8a9699",
 		"thinkingOff": "line",
 		"thinkingMinimal": "dim",
 		"thinkingLow": "toneBright",
@@ -84,8 +84,8 @@
 		"bashMode": "mark"
 	},
 	"export": {
-		"pageBg": "#10161c",
-		"cardBg": "#171f26",
-		"infoBg": "#1f2932"
+		"pageBg": "#121517",
+		"cardBg": "#181d20",
+		"infoBg": "#20272b"
 	}
 }