@tiagojct/subsub 0.11.3 → 0.12.0

package/dist/subsub.js

@@ -19,14 +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 { 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)), "..");
@@ -69,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. */
@@ -122,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;
@@ -264,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();
@@ -272,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;
@@ -298,12 +312,52 @@ export async function createSubsub(pi, deps = {}) {
             await applyMode(ctx, m, false, false);
     });
     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;
+        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);
@@ -312,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)}`,
     }));
@@ -319,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.
@@ -355,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) {
@@ -368,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.
@@ -383,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;
@@ -400,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;
@@ -446,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) {
@@ -485,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", {
@@ -594,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,8 +21,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.js";
-import { configPath, expand, loadConfig, 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";
 import { realish, within } from "./paths.js";
 export function parseWebArgs(args) {
@@ -46,42 +47,9 @@ 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 const KEY_PROVIDERS = [
-    { 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, provider, key) {
-    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 = {};
-    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.js";
 /** pi as a child process in RPC mode. Strict JSONL: records end at LF only. */
 export class Agent {
     proc;
@@ -582,7 +550,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                 }
                 case "GET /api/models": {
                     const data = (await agent.request({ type: "get_available_models" }));
-                    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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.11.3",
+  "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";
@@ -134,7 +134,10 @@ export function runOne(opts: {
 	provider?: string;
 }): Promise<RunSummary> {
 	mkdirSync(opts.out, { recursive: true });
-	const args = ["--mode", "rpc", "--no-session", "--provider", opts.provider ?? "opencode-go", "--model", opts.model];
+	// "google/gemini-x" or "openrouter/vendor/model:free" name their provider; a bare name is OpenCode Go.
+	const slash = opts.model.indexOf("/");
+	const [provider, model] = slash > 0 && !opts.provider ? [opts.model.slice(0, slash), opts.model.slice(slash + 1)] : [opts.provider ?? "opencode-go", opts.model];
+	const args = ["--mode", "rpc", "--no-session", "--provider", provider, "--model", model];
 	if (opts.role === "librarian") args.push("--librarian");
 	const env = { ...process.env, ...opts.extraEnv, SUBSUB_BENCH_OUT: opts.out, SUBSUB_CONFIG: opts.configFile };
 	const proc = spawn(process.execPath, [opts.cli ?? join(PACKAGE_DIR, "bin", "subsub.js"), ...args], { cwd: opts.cwd, env });
@@ -460,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,
@@ -608,7 +612,9 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
 			const prompt = promptFor(j.task, t, j.code, out);
 			if (!prompt) return;
 			const cf = join(cfgDir, `${j.code}.json`);
-			writeFileSync(cf, JSON.stringify({ ...userCfg, profile: "editor", models: { librarian: `opencode-go/${j.model}`, researcher: `opencode-go/${j.model}` }, model: undefined, libraryChanges: undefined }));
+			// A bare name is an OpenCode Go model; provider/id (google/gemini-..., openrouter/x/y:free) is any provider.
+			const spec = j.model.includes("/") ? j.model : `opencode-go/${j.model}`;
+			writeFileSync(cf, JSON.stringify({ ...userCfg, profile: "editor", models: { librarian: spec, researcher: spec }, model: undefined, libraryChanges: undefined }));
 			const s = await runOne({ ...j, prompt, out, cwd: cfg.vault!, configFile: cf, timeoutSec });
 			n++;
 			console.log(`${n}/${jobs.length}  ${j.code}  ${j.task}  ${s.seconds}s  ${s.error ?? (s.settled ? "done" : "?")}`);

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

@@ -35,11 +35,37 @@ export const DEFAULT_MODELS: Record<Mode, string> = {
 	librarian: "opencode-go/mimo-v2.6-flash",
 	researcher: "opencode-go/mimo-v2.6-pro",
 };
+/** The tested free models (Google AI Studio free tier; see the Models page): enough to try Sub-Sub. */
+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), eu (tested, servers in the EU).
+ */
+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";
@@ -82,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 {
@@ -193,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.
+ * --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,8 @@ import { fileURLToPath } from "node:url";
 import {
 	configPath,
 	DEFAULT_MODELS,
+	EU_MODELS,
+	FREE_MODELS,
 	expand,
 	isProfile,
 	loadConfig,
@@ -43,6 +45,7 @@ import {
 } from "./config.ts";
 import { defaultRunner, starbuckCheck } from "./doctor.ts";
 import { applyMoves, FOLDER_NAME, leftBehind, NOTE_DIRS, planMoves, SETTINGS_DIR, SETTINGS_FILES, subsubFolder } from "./layout.ts";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 import { PROFILE_SPECS } from "./profiles.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
@@ -185,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}` })),
@@ -228,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).",
@@ -238,10 +268,21 @@ 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");
 	const modelDefault = hadModel ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
 	const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
+	let googleKey = "";
+	if (models === "google-free" && !hasProvider(agentDir, "google")) {
+		const url = KEY_PROVIDERS.find((p) => p.id === "google")?.url;
+		explain(
+			"Free Google key",
+			`Open ${url}, sign in with a Google account, and select "Create API key". Copy the key and paste it here. Sub-Sub saves it in ${join(agentDir, "auth.json")}, readable only by you. In the EU, the UK and Switzerland, Google does not use your prompts to improve its products; elsewhere, on the free tier, it may. When a limit is reached, Sub-Sub says so.`,
+		);
+		googleKey = (await io.ask("Google API key (Enter to add it later with the model button or /login)", "")).trim();
+	}
 
 	// ---- write
 	if (move === "yes") applyMoves(moves);
@@ -279,13 +320,29 @@ 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;
 	if (models === "keep") patch.models = current.models;
 	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) {
+		try {
+			saveApiKey(agentDir, "google", googleKey);
+			keyNote = `Saved: the Google key, in ${join(agentDir, "auth.json")}`;
+		} 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.";
+	}
 
 	const zotero = await zoteroReachable(deps.fetch);
 	const starbuckNote = starbuck === "on" && deps.prepareStarbuck ? deps.prepareStarbuck(loadConfig(initEnv)) : "";
@@ -293,6 +350,7 @@ export async function runInit(
 	io.say(`Saved: ${configFile}`);
 	io.say(`Saved: ${envFile}`);
 	for (const c of created) io.say(`Created: ${c}`);
+	if (keyNote) io.say(keyNote);
 	if (move === "yes") io.say(`Moved: ${moves.length} file(s) into ${notes}`);
 	for (const d of leftBehind(from, notes)) io.say(`Not moved: ${d}. If Sub-Sub wrote these notes, move them into ${notes} yourself.`);
 	io.say(