@tiagojct/subsub 0.20.0 → 0.21.0

package/src/subsub.ts

@@ -15,9 +15,9 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge, type ServerSpec } from "./bridge.ts";
 import {
@@ -43,7 +43,13 @@ import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missing
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.ts";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.ts";
-import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
+import { headerLines, LIBRARIAN_THEME, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
+import { footerLines, toolRenderers, usageTotals } from "./chrome.ts";
+import { ApprovalView } from "./dialogs.ts";
+import { allowedFile, listNotes, OPENABLE, openFile } from "./files.ts";
+import { LibraryView, NotesView, type LibraryItem } from "./screens.ts";
+import { glyphs, paintFromTheme, workingFrames } from "./skin.ts";
+import { loadWords, toolWord, type Words } from "./words.ts";
 import { systemAddition } from "./prompt.ts";
 import { logUsage } from "./usage.ts";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason, outboundProblem } from "./roles.ts";
@@ -153,6 +159,14 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	let scheme: Scheme | undefined;
 	let modelId = "no model";
 	let headerTui: { requestRender(force?: boolean): void } | undefined;
+	let footerTui: { requestRender(force?: boolean): void } | undefined;
+	/** True once the session started with the look on; the tool renderers are asked before a context exists. */
+	let lookActive = false;
+	let words: Words | undefined;
+	const redraw = () => {
+		headerTui?.requestRender();
+		footerTui?.requestRender();
+	};
 	const library: LibraryState = { zotero: "checking" };
 	const quote = cfg.quotes === false ? undefined : QUOTES[Math.floor(Math.random() * QUOTES.length)];
 	const lookOn = (ctx: ExtensionContext) => standalone && cfg.look !== false && ctx.mode === "tui";
@@ -190,21 +204,123 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	function applyTheme(ctx: ExtensionContext): void {
 		if (!lookOn(ctx) || cfg.themes === false) return;
 		scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
-		const name = themeName(scheme, cfg.themes || undefined);
+		// The Librarian has its own plate (madder); a theme named in the settings applies to both modes unless themes.librarian says otherwise.
+		const base = mode === "librarian" ? (cfg.themesLibrarian ?? cfg.themes ?? LIBRARIAN_THEME) : cfg.themes || undefined;
+		const name = themeName(scheme, base, ctx.ui.theme.getColorMode?.());
 		const theme = name ? ctx.ui.getTheme(name) : undefined;
 		// A Theme object (not a name) changes the theme for this run only; the saved setting stays.
 		if (theme) ctx.ui.setTheme(theme);
+		// The working indicator takes the accent of the mode.
+		const mark = paintFromTheme(ctx.ui.theme).mark;
+		ctx.ui.setWorkingIndicator?.({ frames: workingFrames(glyphs(), Boolean(process.env.SUBSUB_REDUCE_MOTION && process.env.SUBSUB_REDUCE_MOTION !== "0")).map(mark), intervalMs: 160 });
+	}
+
+	/**
+	 * Ask the user to approve a change. With the look on, the preview opens as an overlay with its own keys (see dialogs.ts); otherwise, and over RPC,
+	 * it is pi's confirm dialog. Only a yes counts: anything else, including an overlay that cannot open, is a no.
+	 */
+	async function approve(ctx: ExtensionContext, title: string, body: string): Promise<boolean> {
+		if (lookOn(ctx) && typeof ctx.ui.custom === "function") {
+			const answer = await ctx.ui.custom<boolean>(
+				(tui, theme, _keys, done) =>
+					new ApprovalView({ title, body, lang, paint: paintFromTheme(theme), glyphs: glyphs(), done, rows: () => tui.terminal?.rows ?? 24, redraw: () => tui.requestRender() }),
+				{ overlay: true, overlayOptions: { width: "92%", minWidth: 40, maxHeight: "92%", anchor: "center", margin: 1 } },
+			);
+			return answer === true;
+		}
+		return (await ctx.ui.confirm(title, body)) === true;
+	}
+
+	/** The notes and library screens cover the terminal: the conversation is behind them and comes back when they close. */
+	const OVERLAY = { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 } } as const;
+
+	/** True when the terminal look can show a screen of its own; otherwise says where the same thing is. */
+	function screenOk(ctx: ExtensionContext): boolean {
+		if (lookOn(ctx) && typeof ctx.ui.custom === "function") return true;
+		ctx.ui.notify(L("Sub-Sub: this screen is part of the terminal look. In subsub web, use the Notes button and the library search.", "Sub-Sub: este ecrã faz parte do aspeto do terminal. Em subsub web, use o botão Notas e a pesquisa na biblioteca."), "info");
+		return false;
+	}
+
+	/** /notes: the notes in the Sub-Sub folder, newest first; the note under the cursor shows beside the list. */
+	async function openNotes(ctx: ExtensionContext): Promise<void> {
+		if (!screenOk(ctx)) return;
+		const root = cfg.vault ?? ctx.cwd;
+		const notes = listNotes(root);
+		const { Markdown } = await import("@earendil-works/pi-tui");
+		const { getMarkdownTheme } = await import("@earendil-works/pi-coding-agent");
+		await ctx.ui.custom<void>(
+			(tui, theme, _keys, done) =>
+				new NotesView({
+					notes,
+					read: (path) => {
+						const file = allowedFile(path, root, cfg.vault);
+						return file && statSync(file).size < 2_000_000 ? readFileSync(file, "utf8") : "";
+					},
+					markdown: (text, width) => new Markdown(text, 1, 0, getMarkdownTheme()).render(width),
+					open: (path) => {
+						const file = allowedFile(path, root, cfg.vault);
+						if (file && OPENABLE.has(extname(file).toLowerCase())) openFile(file, cfg.vault);
+					},
+					done: () => done(),
+					lang,
+					paint: paintFromTheme(theme),
+					glyphs: glyphs(),
+					rows: () => tui.terminal?.rows ?? 24,
+					redraw: () => tui.requestRender(),
+				}),
+			OVERLAY,
+		);
+	}
+
+	/** /library: search as you type; Enter puts /read <item> in the box (the Librarian gets the key), ctrl+n puts /lit-note <item>. */
+	async function openLibrary(ctx: ExtensionContext): Promise<void> {
+		if (!screenOk(ctx)) return;
+		const ref = (it: LibraryItem) => it.citekey || it.key;
+		await ctx.ui.custom<void>(
+			(tui, theme, _keys, done) =>
+				new LibraryView({
+					search: async (query) => {
+						const r = await current().call("zotero_find_items", { query, limit: 25 });
+						if (r.isError) throw new Error(r.text);
+						return ((r.data as { items?: LibraryItem[] })?.items ?? []).filter((it) => it && it.key);
+					},
+					choose: (it) => {
+						ctx.ui.setEditorText(mode === "researcher" ? `/read ${ref(it)}` : ref(it));
+						done();
+					},
+					note: (it) => {
+						ctx.ui.setEditorText(`/lit-note ${ref(it)}`);
+						done();
+					},
+					done: () => done(),
+					lang,
+					paint: paintFromTheme(theme),
+					glyphs: glyphs(),
+					researcher: mode === "researcher",
+					rows: () => tui.terminal?.rows ?? 24,
+					redraw: () => tui.requestRender(),
+				}),
+			OVERLAY,
+		);
+	}
+
+	/** /actions: the buttons of the web view as a list; the choice goes into the box, so the user adds what is missing and presses Enter. */
+	async function openActions(ctx: ExtensionContext): Promise<void> {
+		const w = words ?? (await loadWords());
+		const list = [...(mode === "researcher" ? w.ACTIONS.research : []), ...w.ACTIONS.library].filter((a) => a.needs !== "starbuck" || starbuckEnabled(cfg));
+		const labels = list.map((a) => `${a[lang]}   /${a.cmd}`);
+		const pick = await ctx.ui.select(L("Actions", "Ações"), labels);
+		const a = list[labels.indexOf(pick ?? "")];
+		if (a) ctx.ui.setEditorText(a.cmd.endsWith(" ") ? `/${a.cmd}` : `/${a.cmd} `);
 	}
 
 	function paintFor(ctx: ExtensionContext) {
 		return (text: string) =>
 			ctx.mode === "tui"
-				? paintPreview(
-						text,
-						(x) => ctx.ui.theme.fg("success", x),
-						(x) => ctx.ui.theme.fg("error", x),
-						(x) => ctx.ui.theme.fg("text", x),
-					)
+				? (() => {
+						const p = paintFromTheme(ctx.ui.theme);
+						return paintPreview(text, p.ok, p.strike, p.text);
+					})()
 				: text;
 	}
 
@@ -222,7 +338,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		} catch {
 			library.zotero = "down";
 		}
-		headerTui?.requestRender();
+		redraw();
 		emitWeb();
 	}
 
@@ -241,13 +357,9 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 						library,
 						quote,
 						width,
-						paint: {
-							mark: (x) => th.fg("accent", x),
-							text: (x) => th.fg("text", x),
-							muted: (x) => th.fg("muted", x),
-							dim: (x) => th.fg("dim", x),
-							warn: (x) => th.fg("warning", x),
-						},
+						paint: paintFromTheme(th),
+						lang,
+						glyphs: glyphs(),
 					});
 				},
 				invalidate() {},
@@ -255,12 +367,39 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		});
 	}
 
+	function setFooter(ctx: ExtensionContext): void {
+		if (!lookOn(ctx)) return;
+		ctx.ui.setFooter((tui) => {
+			footerTui = tui;
+			return {
+				render: (width: number) => {
+					try {
+						const usage = ctx.getContextUsage();
+						const totals = usageTotals(ctx.sessionManager.getEntries());
+						return footerLines(
+							{ mode, lang, library, model: modelId, percent: usage?.percent ?? null, window: usage?.contextWindow, tokens: totals.tokens, cost: totals.cost, down: bridge ? Object.keys(bridge.errors) : [] },
+							width,
+							paintFromTheme(ctx.ui.theme),
+							glyphs(),
+						);
+					} catch {
+						return []; // the context is gone after shutdown
+					}
+				},
+				invalidate() {},
+				dispose() {
+					footerTui = undefined;
+				},
+			};
+		});
+	}
+
 	function status(ctx: ExtensionContext): void {
 		modelId = ctx.model ? `${ctx.model.id}` : "no model";
 		const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
 		ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
 		if (standalone) ctx.ui.setTitle(`Sub-Sub: ${mode}`);
-		headerTui?.requestRender();
+		redraw();
 		webCtx = ctx;
 		emitWeb();
 	}
@@ -296,6 +435,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			}
 		}
 		if (remember) pi.appendEntry(MODE_ENTRY, { mode });
+		applyTheme(ctx);
 		status(ctx);
 	}
 
@@ -320,11 +460,13 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		const modelChosen = hasModel && hasMessages;
 		// Judge light or dark before Sub-Sub changes the theme.
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
-		applyTheme(ctx);
+		lookActive = lookOn(ctx);
+		if (lookActive) words = await loadWords().catch(() => undefined);
 		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
 		logUsage(cfg.usageLog, { ev: "session", mode, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
 		if (lookOn(ctx)) {
 			setHeader(ctx);
+			setFooter(ctx);
 			void refreshLibrary();
 		} else if (webView) {
 			void refreshLibrary();
@@ -358,6 +500,16 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 	pi.on("model_select", async (_event, ctx) => status(ctx));
+	// Plain-word tool lines for Sub-Sub's own tools (the look only); pi's tools keep pi's rows.
+	const rows = toolRenderers({ word: (name) => (words ? toolWord(words, lang, name) : name), lang, glyphs, paint: paintFromTheme });
+	pi.registerToolRenderer?.((toolName, next) => (lookActive && SERVER_PREFIXES.some((p) => toolName.startsWith(p)) ? (rows(toolName) as never) : next()));
+	pi.on("tool_execution_start", async (event, ctx) => {
+		if (lookActive && words && !event.parentToolCallId) ctx.ui.setWorkingMessage?.(`${toolWord(words, lang, event.toolName)}...`);
+	});
+	pi.on("tool_execution_end", async (_event, ctx) => {
+		if (lookActive) ctx.ui.setWorkingMessage?.();
+	});
+	pi.on("turn_end", async () => redraw());
 	// A provider error in plain words (quota, busy, blocked, key); the web view words its own.
 	pi.on("message_end", async (event, ctx) => {
 		const m = event.message as { role?: string; stopReason?: string; errorMessage?: string };
@@ -466,7 +618,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			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}.` };
-			const ok = await ctx.ui.confirm(`Sub-Sub: ${name} ${target}?`, L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
+			const ok = await approve(ctx, `Sub-Sub: ${name} ${target}?`, L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
 			return ok ? undefined : { block: true, reason: `${user} did not allow writing to that file.` };
 		}
 		if (!ctx.hasUI) {
@@ -478,7 +630,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				const verdict = judgePath(normalizeToolPath(input.output_path, ctx.cwd), buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
 				if (!verdict.ok && /protected|hidden/.test(verdict.why)) return { block: true, reason: `Sub-Sub does not write there: ${verdict.why}.` };
 			}
-			const ok = await ctx.ui.confirm(L(`Sub-Sub: run ${name}?`, `Sub-Sub: executar ${name}?`), describeArgs(input));
+			const ok = await approve(ctx, L(`Sub-Sub: run ${name}?`, `Sub-Sub: executar ${name}?`), describeArgs(input));
 			return ok ? undefined : { block: true, reason: `${user} did not approve. Ask what to change.` };
 		}
 		// kind === "preview": the server computes the change first, then the user decides.
@@ -502,7 +654,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		// The dialog may stay open for minutes. Before applying, compute the preview again: if the
 		// library changed meanwhile (an edit in Zotero, new items), show the new preview instead.
 		for (let round = 0; round < 3; round++) {
-			const ok = await ctx.ui.confirm(round ? `${title} ${L("(the library changed; this is the new preview)", "(a biblioteca mudou; esta é a nova pré-visualização)")}` : title, paintFor(ctx)(shown));
+			const ok = await approve(ctx, round ? `${title} ${L("(the library changed; this is the new preview)", "(a biblioteca mudou; esta é a nova pré-visualização)")}` : title, paintFor(ctx)(shown));
 			logUsage(cfg.usageLog, { ev: "change", tool: name, approved: ok });
 			if (!ok) return { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
 			let again;
@@ -598,7 +750,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			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(L(`Sub-Sub: write the Starbuck report to ${dir}?`, `Sub-Sub: escrever o relatório do Starbuck em ${dir}?`), L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
+		const ok = await approve(ctx, L(`Sub-Sub: write the Starbuck report to ${dir}?`, `Sub-Sub: escrever o relatório do Starbuck em ${dir}?`), L(`Asking because ${verdict.why}.`, `Pergunto porque: ${verdict.why}.`));
 		return ok ? undefined : { block: true, reason: `${user} did not allow writing the report there. Ask where to put it (report_dir).` };
 	}
 
@@ -634,22 +786,37 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		};
 	}
 
+	const switchTo = async (ctx: ExtensionContext, next: Mode): Promise<void> => {
+		await applyMode(ctx, next, true);
+		ctx.ui.notify(
+			next === "librarian"
+				? L("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "Sub-Sub: modo Bibliotecário. Para pesquisas e notas, mude para /researcher.")
+				: L("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "Sub-Sub: modo Investigador. Pesquisa, escreve notas e também altera a biblioteca, com pré-visualização."),
+			"info",
+		);
+	};
+
 	pi.registerCommand("librarian", {
 		description: "Sub-Sub: switch to the Librarian (manages the library: tags, imports, metadata, PDFs)",
-		handler: async (_args, ctx) => {
-			await applyMode(ctx, "librarian", true);
-			ctx.ui.notify(L("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "Sub-Sub: modo Bibliotecário. Para pesquisas e notas, mude para /researcher."), "info");
-		},
+		handler: async (_args, ctx) => switchTo(ctx, "librarian"),
 	});
 
 	pi.registerCommand("researcher", {
 		description: "Sub-Sub: switch to the Researcher (searches, notes, reviews, and everything the Librarian does)",
-		handler: async (_args, ctx) => {
-			await applyMode(ctx, "researcher", true);
-			ctx.ui.notify(L("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "Sub-Sub: modo Investigador. Pesquisa, escreve notas e também altera a biblioteca, com pré-visualização."), "info");
-		},
+		handler: async (_args, ctx) => switchTo(ctx, "researcher"),
 	});
 
+	// Screens of the terminal look (the web view has its own panels, so these are only for the `subsub` command).
+	if (standalone) {
+		pi.registerCommand("notes", { description: "Sub-Sub: the notes in your Sub-Sub folder", handler: async (_args, ctx) => openNotes(ctx) });
+		pi.registerCommand("library", { description: "Sub-Sub: search your Zotero library as you type", handler: async (_args, ctx) => openLibrary(ctx) });
+		pi.registerCommand("actions", { description: "Sub-Sub: the actions of the web view, as a list", handler: async (_args, ctx) => openActions(ctx) });
+		pi.registerShortcut?.("alt+n", { description: "Sub-Sub: notes", handler: (ctx) => openNotes(ctx) });
+		pi.registerShortcut?.("alt+l", { description: "Sub-Sub: library search", handler: (ctx) => openLibrary(ctx) });
+		pi.registerShortcut?.("alt+a", { description: "Sub-Sub: actions", handler: (ctx) => openActions(ctx) });
+		pi.registerShortcut?.("alt+m", { description: "Sub-Sub: switch between the Researcher and the Librarian", handler: (ctx) => switchTo(ctx, mode === "researcher" ? "librarian" : "researcher") });
+	}
+
 	pi.registerCommand("subsub", {
 		description: "Sub-Sub: Zotero connection and library overview",
 		handler: async (_args, ctx) => {
@@ -675,7 +842,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 					);
 				}
 			}
-			headerTui?.requestRender();
+			redraw();
 			emitWeb();
 			ctx.ui.notify(lines.join("\n"), "info");
 		},
@@ -734,6 +901,11 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	// A registered command runs before the input hook, so /read checks the mode itself.
 	pi.registerCommand("read", {
 		description: "Sub-Sub: read a paper with guidance; Sub-Sub finds the passages and asks, you write the answers. /read [background|fact|extract|critique] <citekey, DOI, PMID or title words>",
+		getArgumentCompletions: (prefix: string) => {
+			if (/\s/.test(prefix.trim())) return null;
+			const found = Object.keys(PURPOSES).filter((k) => k.startsWith(prefix.trim().toLowerCase()));
+			return found.length ? found.map((k) => ({ value: k, label: L(PURPOSES[k as Purpose][0], PURPOSES[k as Purpose][1]) })) : null;
+		},
 		handler: async (args, ctx) => {
 			if (mode === "librarian") return ctx.ui.notify(researcherOnly("read"), "warning");
 			let { purpose, ref } = readArgs(String(args ?? ""));
@@ -855,7 +1027,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				ctx.ui.notify(preview.text, "warning");
 				return;
 			}
-			const ok = await ctx.ui.confirm(L("Sub-Sub: undo?", "Sub-Sub: anular?"), paintFor(ctx)(formatPreview("zotero_undo", preview.data, lang)));
+			const ok = await approve(ctx, L("Sub-Sub: undo?", "Sub-Sub: anular?"), paintFor(ctx)(formatPreview("zotero_undo", preview.data, lang)));
 			if (!ok) return;
 			const res = await current().call("zotero_undo", { ...input, dry_run: false });
 			const d = (res.data ?? {}) as Record<string, unknown>;

package/src/web.ts

@@ -63,6 +63,11 @@ export { uiLanguage } from "./config.ts";
 
 export { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 
+// ---------------------------------------------------------------- files (shared with the terminal screens)
+
+import { allowedFile, listNotes, openExternal, openFile, OPENABLE, wikilinkTarget } from "./files.ts";
+export { allowedFile, listNotes, openExternal, OPENABLE, wikilinkTarget };
+
 // ---------------------------------------------------------------- pi in RPC mode
 
 type Listener = (ev: any) => void;
@@ -206,43 +211,6 @@ const NOTE_TYPES = new Set([".md", ".markdown"]);
 /** Images that a note shows (a figure cut out of a PDF, for example). */
 const IMAGE_TYPES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
 
-/** Files that the Open button may hand to the system (never programs or scripts). */
-export const OPENABLE = new Set([".md", ".markdown", ".txt", ".pdf", ".bib", ".csv", ".qmd"]);
-
-/** A file inside the working folder or the Sub-Sub folder, judged by its real path, so a link cannot point outside. */
-export function allowedFile(raw: string, cwd: string, vault?: string): string | undefined {
-	// expand() resolves against the process folder: use it for "~" only.
-	const target = resolve(cwd, raw.startsWith("~") ? expand(raw) : raw);
-	const real = realish(target);
-	const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
-	return inside && existsSync(target) && statSync(target).isFile() ? target : undefined;
-}
-
-/** The note a [[wikilink]] names: the first <folder>/<name>.md in the Sub-Sub folder, as Obsidian would find it. */
-export function wikilinkTarget(name: string, root: string): string | undefined {
-	const file = name.endsWith(".md") ? name : `${name}.md`;
-	return ["", ...NOTE_DIRS, SETTINGS_DIR].map((d) => join(root, d, file)).find((f) => existsSync(f));
-}
-
-/** The notes in the Sub-Sub folders, newest first (dot folders such as Research/.plans left out). */
-export function listNotes(root: string, max = 300): Array<{ path: string; rel: string; modified: number }> {
-	const out: Array<{ path: string; rel: string; modified: number }> = [];
-	for (const d of [...NOTE_DIRS, SETTINGS_DIR]) {
-		let names: string[] = [];
-		try {
-			names = readdirSync(join(root, d), { recursive: true }) as string[];
-		} catch {
-			continue;
-		}
-		for (const n of names) {
-			if (!n.endsWith(".md") || n.split(/[\\/]/).some((x) => x.startsWith("."))) continue;
-			const path = join(root, d, n);
-			out.push({ path, rel: join(d, n), modified: statSync(path).mtimeMs });
-		}
-	}
-	return out.sort((a, b) => b.modified - a.modified).slice(0, max);
-}
-
 const CSP = [
 	"default-src 'none'",
 	"script-src 'self'",
@@ -310,18 +278,6 @@ function alive(pid: number): boolean {
 	}
 }
 
-/** Open a URL or a file with the system's default program. */
-export function openExternal(target: string): void {
-	const opts = { detached: true, stdio: "ignore" as const, windowsHide: true };
-	let child: ChildProcess;
-	if (process.platform === "darwin") child = spawn("open", [target], opts);
-	// rundll32 hands the target to the default program without cmd.exe parsing it.
-	else if (process.platform === "win32") child = spawn("rundll32", ["url.dll,FileProtocolHandler", target], opts);
-	else child = spawn("xdg-open", [target], opts);
-	child.on("error", () => {});
-	child.unref();
-}
-
 // ---------------------------------------------------------------- server
 
 interface RunningFile {
@@ -739,8 +695,7 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					if (!target) return send(res, 404, { error: "not found in the Sub-Sub folder" });
 					// Documents only: a file that the model wrote must never be run.
 					if (!OPENABLE.has(extname(target).toLowerCase())) return send(res, 403, { error: "Sub-Sub opens only notes and documents (.md, .txt, .pdf, .bib, .csv, .qmd)." });
-					if (vault && within(target, vault) && obsidianRoot(vault)) openExternal(`obsidian://open?path=${encodeURIComponent(target)}`);
-					else openExternal(target);
+					openFile(target, vault);
 					return send(res, 200, { ok: true });
 				}
 				case "POST /api/quit":

package/src/words.ts

@@ -0,0 +1,40 @@
+/**
+ * The plain words of the web view (actions, suggestions, names of tools, in English and Portuguese), for the terminal screens.
+ * web/i18n.js is a browser module with no imports; it is loaded here as it is, so the two views never differ.
+ */
+
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PACKAGE_DIR } from "./cli.ts";
+
+export interface Action {
+	cmd: string;
+	en: string;
+	pt: string;
+	/** Send the command at once instead of filling the box. */
+	send?: boolean;
+	/** The command takes a library item. */
+	item?: boolean;
+	/** Needs an add-on, for example "starbuck". */
+	needs?: string;
+}
+
+export interface Words {
+	ACTIONS: { research: Action[]; library: Action[] };
+	SUGGESTIONS: Record<"researcher" | "librarian", Array<{ en: string; pt: string }>>;
+	TOOLS: { en: Record<string, string>; pt: Record<string, string> };
+}
+
+let words: Promise<Words> | undefined;
+
+/** A dynamic import: a static one would pull a file outside src/ into the TypeScript build. */
+export function loadWords(): Promise<Words> {
+	words ??= import(pathToFileURL(join(PACKAGE_DIR, "web", "i18n.js")).href) as Promise<Words>;
+	return words;
+}
+
+/** What a tool is called while it runs ("zotero_find_items" is "search the library"); unknown tools keep their name. */
+export function toolWord(w: Words, lang: "en" | "pt", name: string): string {
+	const short = name.replace(/^(zotero|scholar)_/, "");
+	return w.TOOLS[lang][short] ?? w.TOOLS.en[short] ?? name;
+}

package/themes/subsub-glauca-dark-256.json

@@ -0,0 +1,80 @@
+{
+	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "subsub-glauca-dark-256",
+	"vars": {
+		"ink": 254,
+		"muted": 145,
+		"faint": 246,
+		"prussian": 110,
+		"madder": 173,
+		"sap": 144,
+		"gamboge": 179,
+		"mark": 242,
+		"rule": 236,
+		"accent": 110,
+		"wash": 236
+	},
+	"colors": {
+		"text": "ink",
+		"userMessageText": "ink",
+		"customMessageText": "ink",
+		"toolTitle": "ink",
+		"mdHeading": "ink",
+		"mdCode": "ink",
+		"mdCodeBlock": "ink",
+		"error": "ink",
+		"muted": "muted",
+		"toolOutput": "muted",
+		"mdQuote": "muted",
+		"toolDiffContext": "muted",
+		"thinkingText": "muted",
+		"toolDiffRemoved": "muted",
+		"dim": "faint",
+		"mdLinkUrl": "faint",
+		"syntaxComment": "faint",
+		"border": "mark",
+		"mdQuoteBorder": "mark",
+		"mdListBullet": "mark",
+		"borderMuted": "rule",
+		"mdHr": "rule",
+		"mdCodeBlockBorder": "rule",
+		"scrollbarTrack": "rule",
+		"thinkingOff": "rule",
+		"scrollbarThumb": "faint",
+		"accent": "accent",
+		"borderAccent": "accent",
+		"bashMode": "accent",
+		"customMessageLabel": "accent",
+		"thinkingXhigh": "accent",
+		"thinkingMax": "accent",
+		"mdLink": "prussian",
+		"thinkingHigh": "prussian",
+		"success": "sap",
+		"toolDiffAdded": "sap",
+		"warning": "gamboge",
+		"selectedBg": "wash",
+		"searchMatchBg": "",
+		"searchMatchText": "ink",
+		"userMessageBg": "",
+		"toolSuccessBg": "",
+		"customMessageBg": "",
+		"toolErrorBg": "",
+		"toolPendingBg": "",
+		"syntaxKeyword": "prussian",
+		"syntaxNumber": "prussian",
+		"syntaxFunction": "ink",
+		"syntaxVariable": "ink",
+		"syntaxType": "ink",
+		"syntaxString": "muted",
+		"syntaxOperator": "muted",
+		"syntaxPunctuation": "faint",
+		"thinkingMinimal": "faint",
+		"thinkingLow": "mark",
+		"thinkingMedium": "muted"
+	},
+	"export": {
+		"pageBg": "#12171c",
+		"cardBg": "#192128",
+		"infoBg": "#0d1115"
+	}
+}