@tiagojct/subsub 0.11.4 → 0.12.0

package/dist/subsub.js

@@ -19,15 +19,16 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
-import { expand, findUv, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, who, } from "./config.js";
+import { expand, findUv, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
 import { profileList, profileSpec, promptBlocked } from "./profiles.js";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
 import { applyEdits, checkLiteratureNote } from "./notes.js";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview } from "./preview.js";
-import { providerTrouble, TROUBLE_TEXT } from "./keys.js";
+import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.js";
 import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
 import { systemAddition } from "./prompt.js";
+import { logUsage } from "./usage.js";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.js";
 const MODE_ENTRY = "subsub-mode";
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -70,6 +71,10 @@ export function starbuckEnv(cfg, processEnv = process.env) {
 }
 export async function createSubsub(pi, deps = {}) {
     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, pt) => (lang === "pt" ? pt : en);
+    const trouble = lang === "pt" ? TROUBLE_TEXT_PT : TROUBLE_TEXT;
     let bridge = deps.bridge;
     const toolNames = new Set();
     /** Original input schemas, to turn "[...]" strings back into lists. */
@@ -123,6 +128,11 @@ export async function createSubsub(pi, deps = {}) {
     const lookOn = (ctx) => 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;
+    let resumes = 0;
+    let resumeTimer;
+    let turnStart = 0;
+    let turnTools = 0;
     let webCtx;
     function emitWeb() {
         const ctx = webCtx;
@@ -265,6 +275,7 @@ export async function createSubsub(pi, deps = {}) {
             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();
@@ -273,12 +284,14 @@ export async function createSubsub(pi, deps = {}) {
             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");
+            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;
@@ -302,18 +315,49 @@ export async function createSubsub(pi, deps = {}) {
     // 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;
-        if (webView || m.role !== "assistant" || m.stopReason !== "error")
+        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");
+            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);
@@ -322,6 +366,10 @@ export async function createSubsub(pi, deps = {}) {
         ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
         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)}`,
     }));
@@ -329,6 +377,7 @@ export async function createSubsub(pi, deps = {}) {
     const benchOut = process.env.SUBSUB_BENCH_OUT ? expand(process.env.SUBSUB_BENCH_OUT) : undefined;
     const record = (data) => pi.appendEntry(BENCH_ENTRY, data);
     pi.on("tool_call", async (event, ctx) => {
+        turnTools++;
         const name = event.toolName;
         const input = (event.input ?? {});
         // Previews and the real call must see the same, repaired arguments.
@@ -365,7 +414,7 @@ export async function createSubsub(pi, deps = {}) {
                 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) {
@@ -378,7 +427,7 @@ export async function createSubsub(pi, deps = {}) {
                 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.
@@ -393,12 +442,13 @@ export async function createSubsub(pi, deps = {}) {
         }
         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;
@@ -410,7 +460,7 @@ export async function createSubsub(pi, deps = {}) {
             }
             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 +506,7 @@ export async function createSubsub(pi, deps = {}) {
         }
         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).` };
     }
     async function benchGate(name, input, kind, cwd, signal) {
@@ -495,14 +545,14 @@ export async function createSubsub(pi, deps = {}) {
         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");
         },
     });
     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("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");
         },
     });
     pi.registerCommand("profile", {
@@ -604,12 +654,12 @@ export async function createSubsub(pi, deps = {}) {
                 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 ?? {});
-            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/dist/usage.js

@@ -0,0 +1,69 @@
+/**
+ * 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 function usageFile(env = process.env) {
+    return join(env.HOME ?? homedir(), ".subsub", "usage-log.jsonl");
+}
+export function logUsage(on, event, env = process.env) {
+    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) {
+    const rows = text
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((l) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        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 = (ev) => rows.filter((r) => r.ev === ev);
+    const asks = count("ask");
+    const turns = count("turn");
+    const changes = count("change");
+    const kinds = new Map();
+    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 = process.env) {
+    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/dist/web.js

@@ -21,7 +21,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.js";
-import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, withStarbuck } from "./config.js";
+import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, uiLanguage, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
 import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
 import { obsidianRoot } from "./layout.js";
@@ -47,10 +47,7 @@ export function parseWebArgs(args) {
     }
     return o;
 }
-/** "pt" when the language setting is Portuguese, else "en". */
-export function uiLanguage(language) {
-    return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
-}
+export { uiLanguage } from "./config.js";
 // ---------------------------------------------------------------- providers (API keys)
 export { KEY_PROVIDERS, saveApiKey } from "./keys.js";
 /** pi as a child process in RPC mode. Strict JSONL: records end at LF only. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "Sub-Sub: a research assistant that works from your own Zotero library, in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
@@ -29,13 +29,13 @@
     "@modelcontextprotocol/sdk": "^1.30.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.0.4"
+    "@earendil-works/pi-coding-agent": "~1.0.4"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "test": "node --test test/unit.test.ts",
+    "test": "node --test test/unit.test.ts test/paths.property.test.ts",
     "test:e2e": "node --test test/e2e.test.ts",
     "build": "node scripts/build.mjs",
     "prepack": "npm run build"
@@ -46,6 +46,7 @@
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
     "assets",
     "bin",
     "dist",

package/src/bench.ts

@@ -14,7 +14,7 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expand, loadConfig, type Mode, starbuckCommand, starbuckEnabled } from "./config.ts";
@@ -463,7 +463,8 @@ export function scoreRun(task: string, dir: string, t: Tasks, index: IndexRow[],
 			dois: dois.length,
 			pmids: pmids.length,
 			ungrounded: [...dois.filter((d) => !seen.includes(d)), ...pmids.filter((p) => !seen.includes(p))],
-			screening_log: existsSync(plans) && readdirSync(plans).some((f) => /screening/i.test(f)),
+			// A model may write .plans as a file instead of a folder: then there is no screening log.
+			screening_log: existsSync(plans) && statSync(plans).isDirectory() && readdirSync(plans).some((f) => /screening/i.test(f)),
 			multi_searches: calls.filter((c) => c.name === "scholar_search_multi").length,
 			fulltext_reads: calls.filter((c) => c.name === "scholar_read_oa_fulltext" || c.name === "zotero_get_fulltext").length,
 			starbuck: text && starbuck ? starbuck(join(dir, "Lit.md")) : undefined,

package/src/cli.ts

@@ -142,6 +142,7 @@ Usage:
   subsub web             Open Sub-Sub in the browser
   subsub init            Set up or change the settings (folder, tag list, profile, models)
   subsub doctor          Check the set-up; each line marked FIX says what to do
+  subsub usage           The pilot's usage log (if turned on): a summary and where the file is
   subsub shortcut        Add a Sub-Sub shortcut (--remove takes it away)
   subsub review preview|apply <note>
                          Check or apply a tag review note from Inbox/
@@ -191,6 +192,11 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 		process.exitCode = await doctorMain(env);
 		return;
 	}
+	if (args[0] === "usage") {
+		const { usageMain } = await import("./usage.ts");
+		process.exitCode = usageMain(env);
+		return;
+	}
 	if (args[0] === "review") {
 		const r = reviewCommand(args.slice(1), loadConfig(env), env);
 		const res = spawnSync(r.command, r.args, { env: r.env, stdio: "inherit" });

package/src/config.ts

@@ -40,22 +40,32 @@ export const FREE_MODELS: Record<Mode, string> = {
 	librarian: "google/gemini-3.1-flash-lite",
 	researcher: "google/gemini-3.1-flash-lite",
 };
+/** The tested EU-hosted models (Mistral, servers in the EU; see the Models page). */
+export const EU_MODELS: Record<Mode, string> = {
+	librarian: "mistral/mistral-medium-3.5",
+	researcher: "mistral/mistral-medium-3.5",
+};
 /**
  * Models marked in the model dialog, from the model tests (see the Models page). `why` is a
  * key into the web view's strings: tested (a default), cheaper (tested, same quality, lower cost),
- * free (tested, works on a free tier).
+ * free (tested, works on a free tier), eu (tested, servers in the EU).
  */
-export const RECOMMENDED_MODELS: Array<{ spec: string; modes: Mode[]; why: "tested" | "cheaper" | "free" }> = [
+export const RECOMMENDED_MODELS: Array<{ spec: string; modes: Mode[]; why: "tested" | "cheaper" | "free" | "eu" }> = [
 	{ spec: DEFAULT_MODELS.librarian, modes: ["librarian"], why: "tested" },
 	{ spec: DEFAULT_MODELS.researcher, modes: ["researcher"], why: "tested" },
 	{ spec: "opencode-go/qwen3.8-flash", modes: ["researcher"], why: "cheaper" },
+	{ spec: EU_MODELS.researcher, modes: ["librarian", "researcher"], why: "eu" },
 	{ spec: FREE_MODELS.librarian, modes: ["librarian", "researcher"], why: "free" },
 ];
+/** "pt" when the language setting is Portuguese, else "en": the language of the interface. */
+export function uiLanguage(language: string | undefined): "pt" | "en" {
+	return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
+}
 export type Profile = "reader" | "scholar" | "author" | "editor";
 export const PROFILES: Profile[] = ["reader", "scholar", "author", "editor"];
 
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.5.3";
+export const SERVER_VERSION = "0.5.4";
 
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";
@@ -98,6 +108,8 @@ export interface SubsubConfig {
 	addons?: string[];
 	/** Local Starbuck folder (used when it has a pyproject.toml). */
 	starbuckDir?: string;
+	/** The pilot's usage log, kept on this computer only (see usage.ts). Off by default. */
+	usageLog?: boolean;
 }
 
 export function expand(p: string, home?: string): string {
@@ -209,6 +221,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 		themes,
 		addons: Array.isArray(user.addons) ? user.addons.filter((a): a is string => typeof a === "string") : [],
 		starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
+		usageLog: user.usageLog === true,
 	};
 }
 

package/src/init.ts

@@ -19,7 +19,7 @@
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --folder (or --notes), --move
  * yes|no, --profile, --tags health-sciences|health-informatics|any-field,
- * --email, --starbuck on|off, --models keep|later|opencode-go|google-free.
+ * --email, --starbuck on|off, --models keep|later|opencode-go|mistral-eu|google-free.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
 import {
 	configPath,
 	DEFAULT_MODELS,
+	EU_MODELS,
 	FREE_MODELS,
 	expand,
 	isProfile,
@@ -187,8 +188,22 @@ export async function runInit(
 	);
 	const fmup = setup === "fmup";
 
+	// Students start in Reader: Sub-Sub helps them read and does not write syntheses for them unless asked.
+	let student = fmup;
+	if (!flags.profile && !existing.profile && !fmup) {
+		explain("Who you are", "Students start with the Reader profile: Sub-Sub helps you read (notes with quotations, page numbers and questions) and does not write summaries or syntheses unless you ask. You can change the profile at any time.");
+		student = (await io.choose(
+			"You are",
+			[
+				{ value: "student", label: "A student" },
+				{ value: "researcher", label: "A researcher, teacher or clinician" },
+			],
+			flags.student === "no" ? "researcher" : "student",
+		)) === "student";
+	}
+
 	explain("Profile", "The profile sets how much Sub-Sub writes for you and which tools it offers. Change it at any time with /profile.");
-	const profileDefault = flags.profile ?? existing.profile ?? (fmup ? "reader" : "scholar");
+	const profileDefault = flags.profile ?? existing.profile ?? (student ? "reader" : "scholar");
 	const profile = await io.choose(
 		"Profile",
 		PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })),
@@ -230,6 +245,19 @@ export async function runInit(
 		flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"),
 	);
 
+	explain(
+		"Usage log for the pilot",
+		"If you take part in the Sub-Sub pilot, Sub-Sub can keep a log on this computer: when you used it, which commands, how long it worked and how many library changes you approved. Never what you wrote or what it replied. Nothing is sent; subsub usage shows the log, and you decide whether to send it.",
+	);
+	const usage = await io.choose(
+		"Usage log",
+		[
+			{ value: "off", label: "Off" },
+			{ value: "on", label: "On (for the pilot)" },
+		],
+		flags.usage ?? (existing.usageLog === true ? "on" : "off"),
+	);
+
 	explain(
 		"Models",
 		"Sub-Sub needs an account with a model provider. Each mode can use its own model: the Librarian a fast, cheap one for tags and imports, the Researcher a stronger one for reading. You can connect a provider later in Sub-Sub with the model button (or /login in the terminal).",
@@ -240,6 +268,7 @@ export async function runInit(
 		...(hadModel ? [{ value: "keep", label: `Keep: ${show(current.models)}` }] : []),
 		{ value: "later", label: "Choose later in Sub-Sub" },
 		{ value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODELS.librarian} for the Librarian, ${TESTED_MODELS.researcher} for the Researcher` },
+		{ value: "mistral-eu", label: `Mistral, servers in the EU (GDPR): ${EU_MODELS.researcher} in both modes; about six times the cost of OpenCode Go` },
 		{ value: "google-free", label: `Free, to try Sub-Sub: Google AI Studio, ${FREE_MODELS.researcher} in both modes (a free key, no card; limits per minute and per day; 18 or older)` },
 	];
 	const agentDir = initEnv.SUBSUB_AGENT_DIR ? expand(initEnv.SUBSUB_AGENT_DIR, home) : join(home, ".subsub", "agent");
@@ -291,6 +320,7 @@ export async function runInit(
 		envFile,
 		libraryChanges: undefined,
 		addons: withStarbuck(current.addons, starbuck === "on"),
+		usageLog: usage === "on" ? true : undefined,
 	};
 	// A model per mode; "model" (0.10, one for both) is replaced.
 	patch.model = undefined;
@@ -298,6 +328,7 @@ export async function runInit(
 	if (models === "later") patch.models = {};
 	if (models === "opencode-go") patch.models = TESTED_MODELS;
 	if (models === "google-free") patch.models = FREE_MODELS;
+	if (models === "mistral-eu") patch.models = EU_MODELS;
 	saveConfig(patch, initEnv);
 	let keyNote = "";
 	if (googleKey) {
@@ -307,6 +338,8 @@ export async function runInit(
 		} catch (err) {
 			keyNote = `The Google key was not saved (${(err as Error).message}). Add it in Sub-Sub with the model button or /login.`;
 		}
+	} else if (models === "mistral-eu" && !hasProvider(agentDir, "mistral")) {
+		keyNote = `No Mistral key yet. Get one at ${KEY_PROVIDERS.find((p) => p.id === "mistral")?.url}, then add it in Sub-Sub with the model button (subsub web) or /login (in the terminal).`;
 	} else if (models === "google-free" && !hasProvider(agentDir, "google")) {
 		keyNote = "No Google key yet. Add it in Sub-Sub with the model button (subsub web) or /login (in the terminal), with the provider Google Gemini.";
 	}

package/src/keys.ts

@@ -3,14 +3,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-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" },
+/**
+ * `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. */
@@ -46,10 +50,30 @@ export function providerTrouble(text: string | undefined): Trouble | undefined {
 	return undefined;
 }
 
-/** The terminal's words for each kind (the web view has its own, in English and Portuguese). */
+/** 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;
+}