@tiagojct/subsub 0.11.3 → 0.12.0

package/src/keys.ts

@@ -0,0 +1,79 @@
+/** Model providers that take an API key, and plain words for their common errors. */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * `where`: where the provider processes the data, as a key into the web view's strings
+ * (eu, us, cn, varies). Shown next to the key form, so the choice of provider is an informed one.
+ */
+export const KEY_PROVIDERS: Array<{ id: string; label: string; url: string; where: "eu" | "us" | "cn" | "varies" }> = [
+	{ id: "opencode-go", label: "OpenCode Go", url: "https://opencode.ai/auth", where: "varies" },
+	{ id: "openrouter", label: "OpenRouter", url: "https://openrouter.ai/keys", where: "varies" },
+	{ id: "anthropic", label: "Anthropic", url: "https://console.anthropic.com/settings/keys", where: "us" },
+	{ id: "openai", label: "OpenAI", url: "https://platform.openai.com/api-keys", where: "us" },
+	{ id: "google", label: "Google Gemini", url: "https://aistudio.google.com/apikey", where: "us" },
+	{ id: "mistral", label: "Mistral (EU)", url: "https://console.mistral.ai/api-keys", where: "eu" },
+	{ id: "deepseek", label: "DeepSeek", url: "https://platform.deepseek.com/api_keys", where: "cn" },
+];
+
+/** Save an API key the way pi's /login does: auth.json in the agent folder, readable only by the user. */
+export function saveApiKey(agentDir: string, provider: string, key: string): void {
+	if (!KEY_PROVIDERS.some((p) => p.id === provider)) throw new Error(`Unknown provider: ${provider}`);
+	const clean = key.trim();
+	if (!clean || /\s/.test(clean) || clean.length > 400) throw new Error("That does not look like an API key.");
+	mkdirSync(agentDir, { recursive: true });
+	const file = join(agentDir, "auth.json");
+	let data: Record<string, unknown> = {};
+	if (existsSync(file)) {
+		try {
+			data = JSON.parse(readFileSync(file, "utf8")) ?? {};
+		} catch {
+			throw new Error(`${file} is not valid JSON; fix it or type /login in the terminal.`);
+		}
+	}
+	data[provider] = { type: "api_key", key: clean };
+	// Write through a symlink (a shared pi auth.json) rather than replacing it.
+	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+
+export type Trouble = "quota" | "busy" | "blocked" | "key";
+
+/** What a provider's error means for the user, or undefined when it is something else. */
+export function providerTrouble(text: string | undefined): Trouble | undefined {
+	if (!text) return undefined;
+	if (/RESOURCE_EXHAUSTED|\b429\b|quota|rate.?limit|too many requests|usage limit/i.test(text)) return "quota";
+	if (/\b(503|529)\b|UNAVAILABLE|high demand|overloaded/i.test(text)) return "busy";
+	if (/RECITATION|SAFETY|PROHIBITED_CONTENT/.test(text)) return "blocked";
+	if (/\b(401|403)\b|API key not valid|invalid api key|PERMISSION_DENIED|UNAUTHENTICATED/i.test(text)) return "key";
+	return undefined;
+}
+
+/** The words for each kind in notices (the web view has its own, in web/i18n.js). */
+export const TROUBLE_TEXT_PT: Record<Trouble, string> = {
+	quota: "O fornecedor do modelo recusou o pedido: atingiu um limite da sua conta. Os níveis gratuitos limitam o texto enviado por minuto e os pedidos por dia. Espere um minuto e peça ao Sub-Sub para continuar; se voltar a acontecer, esgotou o limite diário (renova-se no dia seguinte). Ou use outro modelo (/model).",
+	busy: "O fornecedor do modelo está sobrecarregado neste momento. Tente outra vez dentro de alguns minutos ou use outro modelo (/model).",
+	blocked: "O fornecedor do modelo interrompeu a resposta (por exemplo, por repetir uma fonte palavra por palavra). Peça outra vez por outras palavras ou use outro modelo (/model).",
+	key: "O fornecedor do modelo não aceitou a chave da API. Verifique-a ou introduza uma nova com /login.",
+};
+export const TROUBLE_TEXT: Record<Trouble, string> = {
+	quota: "The model provider refused the request: a limit of your account was reached. Free tiers limit the text sent each minute and the requests each day. Wait a minute and ask Sub-Sub to continue; if it happens again, the daily limit is used up (it resets the next day). Or use another model (/model).",
+	busy: "The model provider is busy at the moment. Try again in a few minutes, or use another model (/model).",
+	blocked: "The model provider stopped the reply (for example, because it repeated a source word for word). Ask again in other words, or use another model (/model).",
+	key: "The model provider did not accept the API key. Check it, or enter a new one with /login.",
+};
+
+/**
+ * Seconds to wait before a per-minute limit lets the request through again, or undefined when the
+ * error is not a per-minute limit (a daily limit, a spent balance, anything else). pi does not
+ * retry Google's per-minute 429, because its text mentions billing.
+ */
+export function perMinuteWait(text: string | undefined): number | undefined {
+	if (!text || providerTrouble(text) !== "quota") return undefined;
+	if (/PerDay|per day|daily/i.test(text)) return undefined;
+	const delay = /retryDelay\\*"\s*:\s*\\*"(\d+(?:\.\d+)?)s/.exec(text);
+	const seconds = delay?.[1] ?? /retry in (\d+(?:\.\d+)?)s/i.exec(text)?.[1];
+	if (seconds) return Math.min(120, Math.ceil(Number(seconds)) + 2);
+	return /PerMinute|per minute/i.test(text) ? 60 : undefined;
+}

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,8 +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 { 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";
@@ -95,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. */
@@ -150,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;
@@ -291,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;
@@ -324,13 +338,51 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 	pi.on("model_select", async (_event, ctx) => status(ctx));
+	// 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 (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[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);
@@ -339,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)}`,
 	}));
@@ -348,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.
@@ -376,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) {
@@ -388,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.
@@ -401,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 {
@@ -415,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;
 		}
@@ -456,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).` };
 	}
 
@@ -496,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");
 		},
 	});
 
@@ -504,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");
 		},
 	});
 
@@ -608,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,8 +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 { configPath, expand, loadConfig, 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";
 import { realish, within } from "./paths.ts";
 
@@ -55,42 +56,11 @@ 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)
 
-export const KEY_PROVIDERS: Array<{ id: string; label: string; url: string }> = [
-	{ id: "opencode-go", label: "OpenCode Go", url: "https://opencode.ai/auth" },
-	{ id: "openrouter", label: "OpenRouter", url: "https://openrouter.ai/keys" },
-	{ id: "anthropic", label: "Anthropic", url: "https://console.anthropic.com/settings/keys" },
-	{ id: "openai", label: "OpenAI", url: "https://platform.openai.com/api-keys" },
-	{ id: "google", label: "Google Gemini", url: "https://aistudio.google.com/apikey" },
-	{ id: "mistral", label: "Mistral", url: "https://console.mistral.ai/api-keys" },
-	{ id: "deepseek", label: "DeepSeek", url: "https://platform.deepseek.com/api_keys" },
-];
-
-/** Save an API key the way pi's /login does: auth.json in the agent folder, readable only by the user. */
-export function saveApiKey(agentDir: string, provider: string, key: string): void {
-	if (!KEY_PROVIDERS.some((p) => p.id === provider)) throw new Error(`Unknown provider: ${provider}`);
-	const clean = key.trim();
-	if (!clean || /\s/.test(clean) || clean.length > 400) throw new Error("That does not look like an API key.");
-	mkdirSync(agentDir, { recursive: true });
-	const file = join(agentDir, "auth.json");
-	let data: Record<string, unknown> = {};
-	if (existsSync(file)) {
-		try {
-			data = JSON.parse(readFileSync(file, "utf8")) ?? {};
-		} catch {
-			throw new Error(`${file} is not valid JSON; fix it or type /login in the terminal.`);
-		}
-	}
-	data[provider] = { type: "api_key", key: clean };
-	// Write through a symlink (a shared pi auth.json) rather than replacing it.
-	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
-}
+export { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 
 // ---------------------------------------------------------------- pi in RPC mode
 
@@ -597,7 +567,7 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 				}
 				case "GET /api/models": {
 					const data = (await agent.request({ type: "get_available_models" })) as { models?: unknown[] } | unknown[];
-					return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []) });
+					return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []), recommended: RECOMMENDED_MODELS });
 				}
 				case "POST /api/model": {
 					if (busy || switching) return send(res, 409, { error: "busy" });