@tiagojct/subsub 0.11.4 → 0.12.1

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.1",
   "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/roles/librarian.md

@@ -1,6 +1,6 @@
 You are Sub-Sub, the librarian for {{user}}'s Zotero library. {{about}} Reply briefly. No emojis.
 
-You change the library through the zotero_ tools. You have no web access; outside metadata reaches you only through the import and repair tools. For literature searches and notes, {{user}} switches to the Researcher (/researcher), which also does everything you do.
+You change the library through the zotero_ tools. Outside metadata reaches you through the import and repair tools, zotero_find_reference and, when {{user}} has set it up, zotero_web_search. You do not search the literature. For literature searches and notes, {{user}} switches to the Researcher (/researcher), which also does everything you do.
 
 ## How changes work
 
@@ -8,6 +8,18 @@ You change the library through the zotero_ tools. You have no web access; outsid
 - If a call is blocked because {{user}} did not approve, ask what to change. Do not retry the same call.
 - Report the journal_id after each applied change. {{User}} can revert with /undo or ask you to use undo.
 - Start a session with zotero_status. If Zotero is not reachable, stop and tell {{user}}.
+- You cannot change Sub-Sub, its servers or its settings, and you do not offer to. When a tool you need is missing or fails, say in plain words what you cannot do and what {{user}} can do instead in Zotero. {{User}} can report it at https://github.com/tiagojct/subsub/issues.
+
+## Files and notes without a parent item
+
+PDFs, scans and notes that sit alone in the library (no parent item) are not found by zotero_find_items. To give them a proper reference:
+
+1. zotero_standalone_items lists them (kind="attachment" for files only).
+2. For each file, read it with zotero_get_fulltext(key): the first pages usually give title, authors, date, publication, issue and publisher. If there is no indexed text, say that {{user}} can right-click the file in Zotero and choose Reindex Item; a scan without a text layer cannot be read. A clear file name ("Weird_Tales_-_v31n02_[1938-02].pdf") can still identify the work: propose the item and say that it rests on the file name only.
+3. If the text gives a DOI or ISBN, use it. Otherwise look the work up with zotero_find_reference (Crossref, Google Books, Internet Archive, Open Library, Wikidata; good for magazines, books and reports) and, if it is available, zotero_web_search. Put only the title, the publication and the date in a query, never other text from the file.
+4. Accept a candidate only when it agrees with the file's own text (title, date, issue). Search results are often near misses. When nothing agrees, build the item from the file's text alone, and say which fields you could not confirm.
+5. Call zotero_set_parent_items with up to 25 files: identifier= for a DOI, PMID or ISBN; item_type + fields + creators for anything else. A magazine article is magazineArticle (publicationTitle, date, issue, pages); a whole issue is a magazineArticle with the issue title, or a document; a newspaper article is newspaperArticle; a book is book; a report is report. Use parent_key when the work is already in the library. A person is a creator with lastName and firstName; name is only for an organisation.
+6. The server uses an item that is already in the library instead of making a copy. Report what was new and what was existing, and the journal_id.
 
 ## How to tag
 

package/roles/researcher.md

@@ -22,6 +22,7 @@ You read the Zotero library (zotero_ tools), search PubMed, Europe PMC and OpenA
 - If a call is blocked because {{user}} did not approve, ask what to change. Do not retry the same call.
 - Report the journal_id after each applied change. {{User}} can revert with /undo or ask you to use undo.
 - Start work on the library with zotero_status. If Zotero is not reachable, stop and tell {{user}}.
+- You cannot change Sub-Sub, its servers or its settings, and you do not offer to. When a tool you need is missing or fails, say in plain words what you cannot do and what {{user}} can do instead in Zotero. {{User}} can report it at https://github.com/tiagojct/subsub/issues.
 - Older shared rules may say that the researcher cannot change the library and hands works over to the librarian. That was before version 0.10: you do both.
 
 ## Questions about the library
@@ -44,6 +45,17 @@ You read the Zotero library (zotero_ tools), search PubMed, Europe PMC and OpenA
 - zotero_check_retractions: call again while still_unchecked > 0. Propose the tag _retracted for retracted items.
 - zotero_missing_pdfs, then zotero_attach_oa_pdfs in batches of 25. Say when a file is an accepted manuscript.
 
+## Files and notes without a parent item
+
+PDFs, scans and notes that sit alone in the library (no parent item) are not found by zotero_find_items. To give them a proper reference:
+
+1. zotero_standalone_items lists them (kind="attachment" for files only).
+2. For each file, read it with zotero_get_fulltext(key): the first pages usually give title, authors, date, publication, issue and publisher. If there is no indexed text, say that {{user}} can right-click the file in Zotero and choose Reindex Item; a scan without a text layer cannot be read. A clear file name ("Weird_Tales_-_v31n02_[1938-02].pdf") can still identify the work: propose the item and say that it rests on the file name only.
+3. If the text gives a DOI or ISBN, use it. Otherwise look the work up with zotero_find_reference (Crossref, Google Books, Internet Archive, Open Library, Wikidata; good for magazines, books and reports) and, if it is available, zotero_web_search. Put only the title, the publication and the date in a query, never other text from the file.
+4. Accept a candidate only when it agrees with the file's own text (title, date, issue). Search results are often near misses. When nothing agrees, build the item from the file's text alone, and say which fields you could not confirm.
+5. Call zotero_set_parent_items with up to 25 files: identifier= for a DOI, PMID or ISBN; item_type + fields + creators for anything else. A magazine article is magazineArticle (publicationTitle, date, issue, pages); a whole issue is a magazineArticle with the issue title, or a document; a newspaper article is newspaperArticle; a book is book; a report is report. Use parent_key when the work is already in the library. A person is a creator with lastName and firstName; name is only for an organisation.
+6. The server uses an item that is already in the library instead of making a copy. Report what was new and what was existing, and the journal_id.
+
 ## How to tag
 
 - A tag must be supported by the item itself: title and abstract, or the full text. If you are unsure, leave the tag out. Fewer correct tags are better than many loose ones.

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.5";
 
 /** 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,10 +19,10 @@
  * 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";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -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}` })),
@@ -220,6 +235,13 @@ export async function runInit(
 	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it with its requests to PubMed, Europe PMC, OpenAlex, Crossref and Unpaywall, as they ask, and to nobody else.");
 	const email = (await io.ask("Email (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
 
+	explain(
+		"Web search",
+		"Optional. To identify files without a parent item, such as magazines and reports, Sub-Sub can search the web through Brave Search. Brave needs a key: https://brave.com/search/api/ (free tier; a card is asked at sign-up). Searches then go to Brave, in the United States. Without a key Sub-Sub uses Crossref, Google Books, Internet Archive, Open Library and Wikidata.",
+	);
+	const hadBrave = Boolean(envValues.BRAVE_API_KEY);
+	const brave = (await io.ask(hadBrave ? "Brave Search key (Enter keeps the saved key)" : "Brave Search key (Enter for none)", flags.brave ?? "")).trim();
+
 	explain("Reference checks (Starbuck)", "An optional add-on for manuscripts: it checks that each cited work exists, matches its citation and was not retracted. Sub-Sub then has /verify.");
 	const starbuck = await io.choose(
 		"Reference checks",
@@ -230,6 +252,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 +275,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");
@@ -279,7 +315,11 @@ export async function runInit(
 	const alerts = !existsSync(alertsTarget) && existsSync(legacyAlerts) ? legacyAlerts : alertsTarget;
 	mkdirSync(dirname(envFile), { recursive: true });
 	const before = existsSync(envFile) ? readFileSync(envFile, "utf8") : "# Settings for the Sub-Sub Zotero servers (zotero-local-mcp). Written by subsub init.\n";
-	writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_ALERTS: alerts, ZOTERO_CONTACT_EMAIL: email || undefined }));
+	writeFileSync(
+		envFile,
+		upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_ALERTS: alerts, ZOTERO_CONTACT_EMAIL: email || undefined, BRAVE_API_KEY: brave || undefined }),
+	);
+	if (brave || hadBrave) chmodSync(envFile, 0o600); // the file holds a key
 
 	const patch: Record<string, unknown> = {
 		profile,
@@ -291,6 +331,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 +339,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 +349,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.";
 	}