@tiagojct/subsub 0.11.4 → 0.12.0

package/src/preview.ts

@@ -5,6 +5,62 @@
 
 const MAX_LINES = 14;
 
+export type Lang = "en" | "pt";
+
+/** The words of the preview in English and European Portuguese; tags, titles and values stay as they are. */
+const WORDS = {
+	en: {
+		more: (n: number) => `... and ${n} more`,
+		moreChars: (n: number) => `[${n} more characters not shown]`,
+		empty: "(empty)",
+		change: "(change)",
+		undo: "Undo",
+		already: "ALREADY APPLIED",
+		drift: (n: number) => `${n} item(s) changed after the note was written; the note overwrites them:`,
+		now: "now",
+		none: "(none)",
+		wouldChange: (n: number) => `${n} item(s) would change.`,
+		inShort: (listed: number, total: number) => (listed < total ? `In short (in the ${listed} items listed):` : "In short:"),
+		items: "Items:",
+		itemsN: (n: number) => `${n} item(s)`,
+		changed: "changed",
+		wouldImport: (n: number) => `${n} item(s) would be imported:`,
+		noAbstract: "(no abstract)",
+		wouldAttach: (n: number) => `${n} PDF(s) would be attached:`,
+		newCollection: "New collection",
+		inside: "inside",
+		noteOn: "Note on",
+		link: "Link",
+		skipped: "Skipped",
+		errors: "Errors",
+	},
+	pt: {
+		more: (n: number) => `... e mais ${n}`,
+		moreChars: (n: number) => `[mais ${n} caracteres não mostrados]`,
+		empty: "(vazio)",
+		change: "(alteração)",
+		undo: "Anular",
+		already: "JÁ APLICADO",
+		drift: (n: number) => `${n} item(ns) mudaram depois de a nota ser escrita; a nota substitui-os:`,
+		now: "agora",
+		none: "(nenhuma)",
+		wouldChange: (n: number) => `${n} item(ns) vão mudar.`,
+		inShort: (listed: number, total: number) => (listed < total ? `Em resumo (nos ${listed} itens listados):` : "Em resumo:"),
+		items: "Itens:",
+		itemsN: (n: number) => `${n} item(ns)`,
+		changed: "alterado",
+		wouldImport: (n: number) => `${n} item(ns) vão ser importados:`,
+		noAbstract: "(sem resumo)",
+		wouldAttach: (n: number) => `${n} PDF(s) vão ser anexados:`,
+		newCollection: "Nova coleção",
+		inside: "dentro de",
+		noteOn: "Nota sobre",
+		link: "Ligação",
+		skipped: "Ignorados",
+		errors: "Erros",
+	},
+};
+
 type Obj = Record<string, unknown>;
 
 function s(v: unknown, n = 90): string {
@@ -13,19 +69,19 @@ function s(v: unknown, n = 90): string {
 }
 
 /** What will be written: shown whole up to a large limit, and the rest is counted, never silently cut. */
-function whole(v: unknown, n = 3000): string {
+function whole(v: unknown, w: (typeof WORDS)[Lang], n = 3000): string {
 	const t = typeof v === "string" ? v : JSON.stringify(v);
-	return t.length > n ? `${t.slice(0, n)} [${t.length - n} more characters not shown]` : t;
+	return t.length > n ? `${t.slice(0, n)} ${w.moreChars(t.length - n)}` : t;
 }
 
-function list(rows: string[], total?: number): string[] {
+function list(rows: string[], w: (typeof WORDS)[Lang], total?: number): string[] {
 	const out = rows.slice(0, MAX_LINES);
 	const rest = (total ?? rows.length) - out.length;
-	if (rest > 0) out.push(`... and ${rest} more`);
+	if (rest > 0) out.push(w.more(rest));
 	return out;
 }
 
-function describeChange(c: Obj): string {
+function describeChange(c: Obj, w: (typeof WORDS)[Lang]): string {
 	const parts: string[] = [];
 	if (Array.isArray(c.added) && c.added.length) parts.push(`+ ${c.added.join(", ")}`);
 	if (Array.isArray(c.removed) && c.removed.length) parts.push(`- ${c.removed.join(", ")}`);
@@ -33,73 +89,92 @@ function describeChange(c: Obj): string {
 		if (["key", "item", "added", "removed", "tags_after"].includes(k)) continue;
 		if (v && typeof v === "object" && "after" in (v as Obj)) {
 			const b = (v as Obj).before;
-			parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${whole((v as Obj).after)}`);
+			parts.push(`${k}: ${s(b || w.empty, 40)} -> ${whole((v as Obj).after, w)}`);
 		}
 	}
-	return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || "(change)"}`;
+	return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || w.change}`;
+}
+
+/** For a large batch: each tag and field with the number of items it changes, so the whole is readable at once. */
+function tally(changes: Obj[], total: number, w: (typeof WORDS)[Lang]): string[] {
+	const count = new Map<string, number>();
+	const add = (k: string) => count.set(k, (count.get(k) ?? 0) + 1);
+	for (const c of changes) {
+		for (const tag of (c.added as string[] | undefined) ?? []) add(`+ ${tag}`);
+		for (const tag of (c.removed as string[] | undefined) ?? []) add(`- ${tag}`);
+		for (const [k, v] of Object.entries(c)) if (v && typeof v === "object" && "after" in (v as Obj)) add(`${k} ${w.changed}`);
+	}
+	if (!count.size) return [];
+	const rank = (k: string) => (k.startsWith("+") ? 0 : k.startsWith("-") ? 1 : 2);
+	const rows = [...count].sort((a, b) => rank(a[0]) - rank(b[0]) || b[1] - a[1] || a[0].localeCompare(b[0])).map(([k, n]) => `  ${k}: ${w.itemsN(n)}`);
+	return [w.inShort(changes.length, total), ...list(rows, w), w.items];
 }
 
-export function formatPreview(tool: string, preview: unknown): string {
+export function formatPreview(tool: string, preview: unknown, lang: Lang = "en"): string {
+	const w = WORDS[lang];
 	if (!preview || typeof preview !== "object") return s(preview, 1500);
 	const p = preview as Obj;
 	const lines: string[] = [];
 	if (p.undoing && typeof p.undoing === "object") {
 		const u = p.undoing as Obj;
-		lines.push(`Undo ${u.op}: ${s(u.summary, 80)}`);
+		lines.push(`${w.undo} ${u.op}: ${s(u.summary, 80)}`);
 	}
 	if (Array.isArray(p.already_applied) && p.already_applied.length) {
-		lines.push(`ALREADY APPLIED: ${p.already_applied.join(", ")}`);
+		lines.push(`${w.already}: ${p.already_applied.join(", ")}`);
 	}
 	const drift = p.changed_since_note as Obj | undefined;
 	if (drift && typeof drift === "object" && typeof drift.count === "number") {
-		lines.push(`${drift.count} item(s) changed after the note was written; the note overwrites them:`);
+		lines.push(w.drift(drift.count));
 		const items = Object.entries((drift.items as Obj) ?? {}).map(
-			([k, v]) => `  ${k} now: ${((v as Obj).now as string[] | undefined)?.join(", ") || "(none)"}`,
+			([k, v]) => `  ${k} ${w.now}: ${((v as Obj).now as string[] | undefined)?.join(", ") || w.none}`,
 		);
 		lines.push(...items.slice(0, 4));
 	}
 	if (typeof p.would_change === "number") {
-		lines.push(`${p.would_change} item(s) would change.`);
+		lines.push(w.wouldChange(p.would_change));
 		const changes = (p.changes as Obj[]) ?? [];
-		lines.push(...list(changes.map(describeChange), p.would_change as number));
+		if (p.would_change > 10) lines.push(...tally(changes, p.would_change as number, w));
+		lines.push(...list(changes.map((c) => describeChange(c, w)), w, p.would_change as number));
 	}
 	if (Array.isArray(p.would_import)) {
-		lines.push(`${p.would_import.length} item(s) would be imported:`);
+		lines.push(w.wouldImport(p.would_import.length));
 		lines.push(
 			...list(
 				(p.would_import as Obj[]).map(
-					(r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : "  (no abstract)"}`,
+					(r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : `  ${w.noAbstract}`}`,
 				),
+				w,
 			),
 		);
 	}
 	if (Array.isArray(p.would_attach)) {
-		lines.push(`${p.would_attach.length} PDF(s) would be attached:`);
+		lines.push(w.wouldAttach(p.would_attach.length));
 		lines.push(
 			...list(
 				(p.would_attach as Obj[]).map(
 					(r) => `${s(r.item, 60)}  [${r.host_type ?? "?"}, ${r.version ?? "?"}${r.license ? `, ${r.license}` : ""}]`,
 				),
+				w,
 			),
 		);
 	}
 	if (p.would_create && typeof p.would_create === "object") {
-		const w = p.would_create as Obj;
-		lines.push(`New collection: ${w.name}${w.parent ? ` (inside ${w.parent})` : ""}`);
+		const nc = p.would_create as Obj;
+		lines.push(`${w.newCollection}: ${nc.name}${nc.parent ? ` (${w.inside} ${nc.parent})` : ""}`);
 	}
 	if (tool.endsWith("attach_note") || tool.endsWith("create_note")) {
-		if (p.item || p.parent) lines.push(`Note on: ${s(p.item ?? p.parent, 90)}`);
-		if (p.summary || p.note_preview) lines.push(whole(p.summary ?? p.note_preview));
-		if (p.link) lines.push(`Link: ${p.link}`);
+		if (p.item || p.parent) lines.push(`${w.noteOn}: ${s(p.item ?? p.parent, 90)}`);
+		if (p.summary || p.note_preview) lines.push(whole(p.summary ?? p.note_preview, w));
+		if (p.link) lines.push(`${w.link}: ${p.link}`);
 	}
 	const skipped = p.skipped as Obj | undefined;
 	if (skipped && typeof skipped === "object" && Object.keys(skipped).length) {
-		lines.push(`Skipped: ${Object.keys(skipped).length}`);
-		lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`)).slice(0, 5));
+		lines.push(`${w.skipped}: ${Object.keys(skipped).length}`);
+		lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`), w).slice(0, 5));
 	}
 	const errors = p.errors as Obj | undefined;
 	if (errors && typeof errors === "object" && Object.keys(errors).length) {
-		lines.push(`Errors: ${Object.keys(errors).length}`);
+		lines.push(`${w.errors}: ${Object.keys(errors).length}`);
 		lines.push(...Object.entries(errors).slice(0, 5).map(([k, v]) => `  ${k}: ${s(v, 70)}`));
 	}
 	if (!lines.length) lines.push(s(p, 1500));

package/src/subsub.ts

@@ -34,6 +34,7 @@ import {
 	starbuckCommand,
 	starbuckEnabled,
 	type SubsubConfig,
+	uiLanguage,
 	who,
 } from "./config.ts";
 import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
@@ -41,9 +42,10 @@ import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { applyEdits, checkLiteratureNote } from "./notes.ts";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
-import { providerTrouble, TROUBLE_TEXT } from "./keys.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 { systemAddition } from "./prompt.ts";
+import { logUsage } from "./usage.ts";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.ts";
 
 const MODE_ENTRY = "subsub-mode";
@@ -96,6 +98,10 @@ export function starbuckEnv(cfg: Pick<SubsubConfig, "envFile">, processEnv: Node
 
 export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Promise<void> {
 	const cfg = deps.config ?? loadConfig();
+	// Notices, dialogs and previews in the language of the interface (English or European Portuguese).
+	const lang = uiLanguage(cfg.language);
+	const L = (en: string, pt: string) => (lang === "pt" ? pt : en);
+	const trouble = lang === "pt" ? TROUBLE_TEXT_PT : TROUBLE_TEXT;
 	let bridge: Bridge | undefined = deps.bridge;
 	const toolNames = new Set<string>();
 	/** Original input schemas, to turn "[...]" strings back into lists. */
@@ -151,6 +157,11 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	const lookOn = (ctx: ExtensionContext) => standalone && cfg.look !== false && ctx.mode === "tui";
 	/** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
 	const webView = process.env.SUBSUB_WEB === "1";
+	let lastError: string | undefined;
+	let resumes = 0;
+	let resumeTimer: ReturnType<typeof setTimeout> | undefined;
+	let turnStart = 0;
+	let turnTools = 0;
 	let webCtx: ExtensionContext | undefined;
 	function emitWeb(): void {
 		const ctx = webCtx;
@@ -292,19 +303,21 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
 		applyTheme(ctx);
 		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
+		logUsage(cfg.usageLog, { ev: "session", mode, profile, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
 		if (lookOn(ctx)) {
 			setHeader(ctx);
 			void refreshLibrary();
 		} else if (webView) {
 			void refreshLibrary();
 		}
-		if (!ctx.model && !webView) ctx.ui.notify("Sub-Sub: no model is connected yet. Type /login and select a provider (or use the model button in subsub web).", "warning");
+		if (!ctx.model && !webView) ctx.ui.notify(L("Sub-Sub: no model is connected yet. Type /login and select a provider (or use the model button in subsub web).", "Sub-Sub: ainda não há um modelo ligado. Escreva /login e selecione um fornecedor (ou use o botão do modelo em subsub web)."), "warning");
 		for (const [name, err] of Object.entries(bridge.errors)) {
 			ctx.ui.notify(`Sub-Sub: the ${name} server did not start: ${err.split("\n")[0]}`, "error");
 		}
 	});
 
 	pi.on("session_shutdown", async () => {
+		if (resumeTimer) clearTimeout(resumeTimer);
 		if (deps.bridge) return;
 		const b = bridge;
 		bridge = undefined;
@@ -328,18 +341,48 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	// 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 };
-		if (webView || m.role !== "assistant" || m.stopReason !== "error") return;
+		if (m.role !== "assistant" || m.stopReason !== "error") return;
+		lastError = m.errorMessage;
+		if (webView || perMinuteWait(m.errorMessage) !== undefined) return;
 		const kind = providerTrouble(m.errorMessage);
-		if (kind) ctx.ui.notify(`Sub-Sub: ${TROUBLE_TEXT[kind]}`, "warning");
+		if (kind) ctx.ui.notify(`Sub-Sub: ${trouble[kind]}`, "warning");
+	});
+
+	// A per-minute limit (free tiers): wait as long as the provider says, then continue the task,
+	// up to three times per request of the user. Anything the user types cancels the wait.
+	pi.on("agent_end", async (_event, ctx) => {
+		if (turnStart) logUsage(cfg.usageLog, { ev: "turn", seconds: Math.round((Date.now() - turnStart) / 1000), tools: turnTools, error: providerTrouble(lastError) ?? (lastError ? "other" : undefined) });
+		turnStart = 0;
+		const wait = perMinuteWait(lastError);
+		lastError = undefined;
+		if (wait === undefined) return;
+		if (resumes >= 3) {
+			ctx.ui.notify(`Sub-Sub: ${trouble.quota}`, "warning");
+			return;
+		}
+		resumes++;
+		ctx.ui.notify(L(`Sub-Sub: the provider's per-minute limit was reached. Continuing in ${wait} seconds (type anything to stop waiting).`, `Sub-Sub: atingiu o limite por minuto do fornecedor. Continua dentro de ${wait} segundos (escreva qualquer coisa para deixar de esperar).`), "info");
+		resumeTimer = setTimeout(() => {
+			resumeTimer = undefined;
+			pi.sendMessage(
+				{ customType: "subsub-resume", content: "The model provider's per-minute limit was reached and has now passed. Continue the task where you stopped; do not repeat finished steps.", display: false },
+				{ triggerTurn: true },
+			);
+		}, wait * 1000);
 	});
 
 
 	// Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
 	// The input event comes before pi expands a prompt template.
 	pi.on("input", async (event, ctx) => {
+		if (resumeTimer) clearTimeout(resumeTimer);
+		resumeTimer = undefined;
+		resumes = 0;
 		const cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+		// The usage log keeps the kind of request and its length, never its text.
+		if (cmd !== "subsub-refresh") logUsage(cfg.usageLog, { ev: "ask", kind: cmd ? `/${cmd}` : "message", words: event.text.trim().split(/\s+/).filter(Boolean).length });
 		if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
-			ctx.ui.notify(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, "warning");
+			ctx.ui.notify(L(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, `Sub-Sub: /${cmd} faz parte do Investigador. Mude com /researcher.`), "warning");
 			return { action: "handled" };
 		}
 		const why = promptBlocked(event.text, profile);
@@ -348,6 +391,11 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		return { action: "handled" };
 	});
 
+	pi.on("agent_start", async () => {
+		turnStart = Date.now();
+		turnTools = 0;
+	});
+
 	pi.on("before_agent_start", async (event, ctx) => ({
 		systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
 	}));
@@ -357,6 +405,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	const record = (data: Record<string, unknown>) => pi.appendEntry(BENCH_ENTRY, data);
 
 	pi.on("tool_call", async (event, ctx) => {
+		turnTools++;
 		const name = event.toolName;
 		const input = (event.input ?? {}) as Record<string, unknown>;
 		// Previews and the real call must see the same, repaired arguments.
@@ -385,7 +434,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}?`, `Asking because ${verdict.why}.`);
+			const ok = await ctx.ui.confirm(`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) {
@@ -397,7 +446,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(`Sub-Sub: run ${name}?`, describeArgs(input));
+			const ok = await ctx.ui.confirm(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.
@@ -410,12 +459,13 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			return { block: true, reason: `Preview failed: ${(err as Error).message}` };
 		}
 		if (preview.isError) return { block: true, reason: preview.text };
-		const title = `Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`;
-		let shown = formatPreview(name, preview.data ?? preview.text);
+		const title = L(`Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`, `Sub-Sub: aplicar ${name.replace(/^(zotero|scholar)_/, "")}?`);
+		let shown = formatPreview(name, preview.data ?? preview.text, lang);
 		// 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} (the library changed; this is the new preview)` : title, paintFor(ctx)(shown));
+			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));
+			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;
 			try {
@@ -424,7 +474,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				return { block: true, reason: `Preview failed: ${(err as Error).message}` };
 			}
 			if (again.isError) return { block: true, reason: again.text };
-			const now = formatPreview(name, again.data ?? again.text);
+			const now = formatPreview(name, again.data ?? again.text, lang);
 			if (now === shown) return undefined;
 			shown = now;
 		}
@@ -465,7 +515,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(`Sub-Sub: write the Starbuck report to ${dir}?`, `Asking because ${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}.`));
 		return ok ? undefined : { block: true, reason: `${user} did not allow writing the report there. Ask where to put it (report_dir).` };
 	}
 
@@ -505,7 +555,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		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("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "info");
+			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");
 		},
 	});
 
@@ -513,7 +563,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		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("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "info");
+			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");
 		},
 	});
 
@@ -617,11 +667,11 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				ctx.ui.notify(preview.text, "warning");
 				return;
 			}
-			const ok = await ctx.ui.confirm("Sub-Sub: undo?", paintFor(ctx)(formatPreview("zotero_undo", preview.data)));
+			const ok = await ctx.ui.confirm(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>;
-			ctx.ui.notify(res.isError ? res.text : `Undone: ${d.applied} item(s).`, res.isError ? "error" : "info");
+			ctx.ui.notify(res.isError ? res.text : L(`Undone: ${d.applied} item(s).`, `Anulado: ${d.applied} item(ns).`), res.isError ? "error" : "info");
 		},
 	});
 }

package/src/usage.ts

@@ -0,0 +1,75 @@
+/**
+ * The pilot's usage log: off unless the user turns it on (subsub init, or "usageLog": true).
+ * One JSON line per event in ~/.subsub/usage-log.jsonl: times, counts, commands and tool names.
+ * Never what the user wrote, the replies, titles or file names. Nothing is sent anywhere; the
+ * user reads it with `subsub usage` and sends the file to the pilot team if they want to.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type UsageEvent =
+	| { ev: "session"; mode: string; profile: string; model?: string }
+	| { ev: "ask"; kind: string; words: number }
+	| { ev: "turn"; seconds: number; tools: number; error?: string }
+	| { ev: "change"; tool: string; approved: boolean };
+
+export function usageFile(env: NodeJS.ProcessEnv = process.env): string {
+	return join(env.HOME ?? homedir(), ".subsub", "usage-log.jsonl");
+}
+
+export function logUsage(on: boolean | undefined, event: UsageEvent, env: NodeJS.ProcessEnv = process.env): void {
+	if (!on) return;
+	try {
+		const file = usageFile(env);
+		mkdirSync(dirname(file), { recursive: true });
+		appendFileSync(file, `${JSON.stringify({ t: new Date().toISOString(), ...event })}\n`, { mode: 0o600 });
+	} catch {
+		/* a log must never stop the work */
+	}
+}
+
+/** A plain summary of the log: days, sessions, requests, commands, time, library changes. */
+export function summarizeUsage(text: string): string {
+	const rows = text
+		.split("\n")
+		.filter(Boolean)
+		.flatMap((l) => {
+			try {
+				return [JSON.parse(l) as UsageEvent & { t: string }];
+			} catch {
+				return [];
+			}
+		});
+	if (!rows.length) return "The usage log is empty.";
+	const days = new Set(rows.map((r) => r.t.slice(0, 10)));
+	const count = <T extends UsageEvent["ev"]>(ev: T) => rows.filter((r) => r.ev === ev) as Array<Extract<UsageEvent, { ev: T }> & { t: string }>;
+	const asks = count("ask");
+	const turns = count("turn");
+	const changes = count("change");
+	const kinds = new Map<string, number>();
+	for (const a of asks) kinds.set(a.kind, (kinds.get(a.kind) ?? 0) + 1);
+	const minutes = Math.round(turns.reduce((s, r) => s + r.seconds, 0) / 60);
+	const errors = turns.filter((r) => r.error).length;
+	const lines = [
+		`From ${rows[0].t.slice(0, 10)} to ${rows.at(-1)!.t.slice(0, 10)}: Sub-Sub used on ${days.size} day(s), in ${count("session").length} session(s).`,
+		`Requests: ${asks.length} (${[...kinds].sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(", ")}).`,
+		`Time Sub-Sub spent working: ${minutes} minute(s), with ${turns.reduce((s, r) => s + r.tools, 0)} tool call(s) and ${errors} error(s).`,
+		`Library changes: ${changes.filter((c) => c.approved).length} approved, ${changes.filter((c) => !c.approved).length} declined.`,
+	];
+	return lines.join("\n");
+}
+
+export function usageMain(env: NodeJS.ProcessEnv = process.env): number {
+	const file = usageFile(env);
+	if (!existsSync(file)) {
+		console.log(`No usage log yet (${file}). To keep one for the pilot, type subsub init and turn it on, or set "usageLog": true in the settings.`);
+		return 0;
+	}
+	console.log(summarizeUsage(readFileSync(file, "utf8")));
+	console.log("");
+	console.log(`The log: ${file}`);
+	console.log("It holds times, counts, commands and tool names, never what you wrote or what Sub-Sub replied. To share it with the pilot team, send this file.");
+	return 0;
+}

package/src/web.ts

@@ -22,7 +22,7 @@ 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 { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
+import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, type SubsubConfig, uiLanguage, withStarbuck } from "./config.ts";
 import { TESTED_MODELS } from "./init.ts";
 import { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 import { obsidianRoot } from "./layout.ts";
@@ -56,10 +56,7 @@ export function parseWebArgs(args: string[]): WebOptions {
 	return o;
 }
 
-/** "pt" when the language setting is Portuguese, else "en". */
-export function uiLanguage(language: string | undefined): "pt" | "en" {
-	return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
-}
+export { uiLanguage } from "./config.ts";
 
 // ---------------------------------------------------------------- providers (API keys)
 

package/web/app.css

@@ -883,3 +883,14 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 @media (prefers-reduced-motion: reduce) {
 	*, *::before, *::after { animation: none !important; transition: none !important; }
 }
+
+/* First run: what is still missing */
+.setup { margin-block: 1.4rem 1rem; padding: 0.9rem 1rem; border: 1px solid var(--rule); border-left: 3px solid var(--accent); border-radius: 6px; background: var(--raised); text-align: left; max-width: 40rem; }
+.setup h2 { margin: 0 0 0.5rem; font-size: 0.95rem; }
+.setup ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 0.55rem; }
+.setup li { display: grid; grid-template-columns: 4.5rem 1fr auto; gap: 0.6rem; align-items: start; font-size: 0.88rem; line-height: 1.45; }
+.setup li > * { min-width: 0; }
+.setup .mark { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.05em; padding-top: 0.15rem; color: var(--muted); }
+.setup li.todo .mark { color: var(--rem); }
+.setup li.ok .step-text { color: var(--muted); }
+@media (max-width: 560px) { .setup li { grid-template-columns: 1fr; gap: 0.2rem; } }

package/web/app.js

@@ -395,6 +395,36 @@ function clearEmpty() {
 	log.querySelector(".empty")?.remove();
 }
 
+/** First run: what is still missing (Zotero, a model, the servers), each with its fix. Hidden when all is ready. */
+function setupList() {
+	const L = state?.library;
+	const m = state?.model ?? session?.model;
+	const steps = [
+		{ ok: L?.zotero === "reachable", wait: !L || L.zotero === "checking", text: t("stepZotero") },
+		{ ok: Boolean(m && m.id && m.id !== "unknown"), text: t("stepModel"), action: { label: t("connect"), run: openModels } },
+		{ ok: !state?.down?.length, text: t("stepServers", { x: (state?.down ?? []).join(", ") }) },
+	];
+	if (steps.every((x) => x.ok || x.wait)) return null;
+	return el(
+		"div",
+		{ class: "setup" },
+		el("h2", { text: t("setupTitle") }),
+		el(
+			"ol",
+			{},
+			steps.map((x) =>
+				el(
+					"li",
+					{ class: x.ok ? "ok" : x.wait ? "wait" : "todo" },
+					el("span", { class: "mark", text: x.ok ? t("stepDone") : x.wait ? "…" : t("stepTodo") }),
+					el("span", { class: "step-text", text: x.ok ? x.text.split(". ")[0] : x.text }),
+					!x.ok && x.action ? el("button", { type: "button", class: "primary small-btn", text: x.action.label, onclick: x.action.run }) : null,
+				),
+			),
+		),
+	);
+}
+
 function renderEmpty() {
 	if (log.children.length) return;
 	const s = SUGGESTIONS[mode()].map((x) => x[lang] ?? x.en);
@@ -405,6 +435,7 @@ function renderEmpty() {
 			el("p", { class: "kicker", text: t(mode()) }),
 			el("h1", { text: t("emptyTitle") }),
 			el("p", { class: "lede", text: t(mode() === "librarian" ? "emptyLibrarian" : "emptyResearcher") }),
+			setupList(),
 			el(
 				"div",
 				{ class: "chips" },
@@ -505,6 +536,23 @@ function finishTool(id, result, isError) {
 	row.querySelector("pre")?.remove();
 	if (text) row.append(el("pre", { text: text.length > 6000 ? `${text.slice(0, 6000)}\n...` : text }));
 	if (isError) row.querySelector(".label").textContent = `${toolLabel(row.dataset.name)} (${t("failed")})`;
+	// An applied library change gets an Undo button; it runs /undo with its id, which previews first.
+	const jid = !isError && !/undo/.test(row.dataset.name) && /"journal_id":\s*"(\d{8}-\d{6}-\d{2}-[a-z_]+)"/.exec(text ?? "")?.[1];
+	if (jid && !row.querySelector(".undo")) {
+		row.querySelector("summary").append(
+			el("button", {
+				type: "button",
+				class: "open undo",
+				text: t("undo"),
+				title: t("undoTitle"),
+				onclick: (e) => {
+					e.preventDefault();
+					if (busy) return note(t("busy"), "warning");
+					sendMessage(`/undo ${jid}`);
+				},
+			}),
+		);
+	}
 }
 
 function attachCopyButtons(root) {
@@ -925,6 +973,7 @@ async function openModels() {
 		const free = { google: "freeGoogle", openrouter: "freeOpenRouter" }[sel.value];
 		$("login-free").hidden = !free;
 		$("login-free").textContent = free ? t(free) : "";
+		$("login-where").textContent = p?.where ? t(`where_${p.where}`) : "";
 	};
 	sel.onchange = setLink;
 	setLink();