@tiagojct/subsub 0.23.0 → 0.24.1

package/dist/tui.js

@@ -11,12 +11,15 @@ import { CombinedAutocompleteProvider, Editor, HStack, Markdown, matchesKey, Pro
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
 import { fill, footerLines } from "./chrome.js";
 import { loadConfig, uiLanguage } from "./config.js";
+import { modelsAfterLogin } from "./init.js";
 import { LIBRARIAN_THEME, DEFAULT_THEME, paintPreview, QUOTES } from "./look.js";
 import { PURPOSES } from "./read.js";
 import { allowedFile, listNotes, OPENABLE, openFile } from "./files.js";
 import { Agent, findLibrary, isDialog, Side, withHints } from "./rpc.js";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
+import { CUSTOM_DEFAULT_NAME, saveCustomProvider } from "./providers.js";
 import { ApprovalView } from "./dialogs.js";
-import { ChoiceView, InputView, LibraryView, NotesView } from "./screens.js";
+import { itemRef, ChoiceView, InputView, LibraryView, NotesView } from "./screens.js";
 import { glyphs as chooseGlyphs, workingFrames } from "./skin.js";
 import { bannerLines, entriesFromMessages, loadPalette, messageText, schemeFromEnv, SIDE_WIDTH, sideLines, transcriptLines } from "./tui-view.js";
 import { loadWords } from "./words.js";
@@ -161,6 +164,8 @@ export class TuiApp {
             { name: "library", description: pt ? "Pesquisar na biblioteca à medida que escreve" : "Search your library as you type" },
             { name: "actions", description: pt ? "As ações da vista no navegador" : "The actions of the browser view" },
             { name: "sessions", description: pt ? "Conversas anteriores" : "Earlier conversations" },
+            { name: "resume", description: pt ? "Retomar uma conversa anterior" : "Resume an earlier conversation" },
+            { name: "login", description: pt ? "Ligar um fornecedor do modelo" : "Connect a model provider" },
             { name: "new", description: pt ? "Uma conversa nova" : "A new conversation" },
             { name: "model", description: pt ? "Escolher o modelo" : "Choose the model" },
             { name: "restart", description: pt ? "Recomeçar o pi na mesma conversa" : "Start pi again in the same conversation" },
@@ -445,7 +450,7 @@ export class TuiApp {
     async openLibrary() {
         if (this.overlay)
             return;
-        const ref = (it) => it.citekey || it.key;
+        const ref = itemRef;
         this.open(new LibraryView({
             ...this.common(),
             researcher: this.mode === "researcher",
@@ -503,6 +508,71 @@ export class TuiApp {
             cancel: () => this.close(),
         }), true);
     }
+    /** Ask one line on its own screen; undefined when the user presses Esc. */
+    ask(title, opts = {}) {
+        return new Promise((resolve) => {
+            this.open(new InputView({
+                ...this.common(),
+                title,
+                ...opts,
+                submit: (text) => (this.close(), resolve(text.trim())),
+                cancel: () => (this.close(), resolve(undefined)),
+            }), true);
+        });
+    }
+    /** /login: a provider that pi has (its API key) or another provider that speaks the OpenAI API; then pi starts again. */
+    async openLogin() {
+        if (this.overlay)
+            return;
+        const pt = this.lang === "pt";
+        const agentDir = this.d.agentDir;
+        if (!agentDir)
+            return void this.notice("error", pt ? "Sem pasta do agente: use subsub web." : "No agent folder: use subsub web.");
+        const choices = [
+            ...KEY_PROVIDERS.map((p) => ({ label: p.label, hint: p.url, value: p.id })),
+            { label: pt ? "Outro fornecedor (API da OpenAI)" : "Another provider (OpenAI API)", hint: pt ? "servidor da instituição, Ollama, LM Studio" : "your institution's server, Ollama, LM Studio", value: CUSTOM_DEFAULT_NAME },
+        ];
+        const provider = await new Promise((resolve) => {
+            this.open(new ChoiceView({
+                ...this.common(),
+                title: pt ? "Ligar um fornecedor" : "Connect a provider",
+                choices,
+                choose: (v) => (this.close(), resolve(v)),
+                cancel: () => (this.close(), resolve(undefined)),
+            }), true);
+        });
+        if (!provider)
+            return;
+        let spec;
+        try {
+            if (provider === CUSTOM_DEFAULT_NAME) {
+                const baseUrl = await this.ask(pt ? "Endereço do servidor" : "Server address", { placeholder: "https://llm.example.org/v1" });
+                if (baseUrl === undefined)
+                    return;
+                const model = await this.ask(pt ? "Identificador do modelo" : "Model id");
+                if (model === undefined)
+                    return;
+                const key = await this.ask(pt ? "Chave de API (Enter sem chave, num servidor local)" : "API key (Enter for none, for a local server)", { secret: true });
+                if (key === undefined)
+                    return;
+                [spec] = saveCustomProvider(agentDir, { name: CUSTOM_DEFAULT_NAME, baseUrl, apiKey: key, models: [model] });
+            }
+            else {
+                const label = KEY_PROVIDERS.find((p) => p.id === provider)?.label ?? provider;
+                const key = await this.ask(pt ? `Chave de API de ${label}` : `API key for ${label}`, { secret: true });
+                if (!key)
+                    return;
+                saveApiKey(agentDir, provider, key);
+            }
+            this.d.afterLogin?.(provider, spec);
+        }
+        catch (err) {
+            this.notice("error", err.message);
+            return void this.tui.requestRender();
+        }
+        this.notice("info", pt ? "Guardado. O pi recomeça com o fornecedor." : "Saved. pi starts again with the provider.");
+        await this.restart();
+    }
     /** /new: an empty conversation. */
     async newConversation() {
         try {
@@ -579,12 +649,12 @@ export class TuiApp {
         this.editor.setText("");
         if (/^\/(quit|exit)\s*$/.test(line))
             return void (await this.quit());
-        const unavailable = /^\/(login|logout|settings|tree|resume|fork|share|export|import|hotkeys|reload)\b/.exec(line);
+        const unavailable = /^\/(logout|settings|tree|fork|share|export|import|hotkeys|reload)\b/.exec(line);
         if (unavailable) {
             this.notice("info", this.lang === "pt" ? `/${unavailable[1]} não existe em subsub tui. Use subsub no terminal ou subsub web.` : `/${unavailable[1]} is not in subsub tui. Use subsub in the terminal, or subsub web.`);
             return void this.tui.requestRender();
         }
-        const own = { "/restart": () => this.restart(), "/model": () => this.openModels(), "/notes": () => this.openNotes(), "/library": () => this.openLibrary(), "/actions": () => this.openActions(), "/sessions": () => this.openSessions(), "/new": () => this.newConversation() };
+        const own = { "/restart": () => this.restart(), "/model": () => this.openModels(), "/notes": () => this.openNotes(), "/library": () => this.openLibrary(), "/actions": () => this.openActions(), "/sessions": () => this.openSessions(), "/resume": () => this.openSessions(), "/login": () => this.openLogin(), "/new": () => this.newConversation() };
         if (own[line])
             return void (await own[line]());
         try {
@@ -645,6 +715,8 @@ export async function runTui(args, env = process.env) {
             themes: { researcher: typeof cfg.themes === "string" ? cfg.themes : undefined, librarian: cfg.themesLibrarian ?? (typeof cfg.themes === "string" ? cfg.themes : undefined) },
             sessions: async () => (await SessionManager.list(cwd)).filter((s) => s.messageCount > 0).sort((a, b) => +new Date(b.modified) - +new Date(a.modified)).map((s) => ({ title: s.name ?? s.firstMessage.slice(0, 60), path: s.path })),
             onQuit: resolve,
+            agentDir: env.PI_CODING_AGENT_DIR,
+            afterLogin: (provider, spec) => modelsAfterLogin(env, provider, spec),
         });
         void app.start();
     });

package/dist/web.js

@@ -20,8 +20,9 @@ import { homedir } from "node:os";
 import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
 import { configPath, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, uiLanguage, withStarbuck } from "./config.js";
-import { TESTED_MODELS } from "./init.js";
+import { modelsAfterLogin } from "./init.js";
 import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
+import { CUSTOM_DEFAULT_NAME, saveCustomProvider } from "./providers.js";
 export function parseWebArgs(args) {
     const o = { port: 0, open: true, librarian: false, here: false, idleMinutes: 10, piArgs: [] };
     for (let i = 0; i < args.length; i++) {
@@ -463,10 +464,13 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                         return send(res, 409, { error: "busy" });
                     const body = await readJson(req);
                     return withRestart(res, () => {
+                        if (body.provider === CUSTOM_DEFAULT_NAME) {
+                            // Another provider (OpenAI API): models.json; its model becomes the default when none is set.
+                            const [spec] = saveCustomProvider(agentDir, { name: CUSTOM_DEFAULT_NAME, baseUrl: String(body.baseUrl ?? ""), apiKey: String(body.key ?? ""), models: [String(body.model ?? "")] });
+                            return modelsAfterLogin(env, CUSTOM_DEFAULT_NAME, spec);
+                        }
                         saveApiKey(agentDir, String(body.provider ?? ""), String(body.key ?? ""));
-                        const current = loadConfig(env);
-                        if (body.provider === "opencode-go" && Object.keys(current.models).length === 0)
-                            saveConfig({ models: TESTED_MODELS, model: undefined }, env);
+                        modelsAfterLogin(env, String(body.provider ?? ""));
                     });
                 }
                 case "GET /api/notes":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.23.0",
+  "version": "0.24.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",

package/prompts/check-library.md

@@ -0,0 +1,12 @@
+---
+description: "Check the library: duplicates, retracted or corrected works, and files without a parent item"
+---
+Check my whole library in three parts, then give me one report.
+
+1. Duplicates: run zotero_find_duplicates. For each group, give the items with their evidence (identifiers, fields, files, citekeys) and say which record is the fullest. Do not call items duplicates on a similar title alone. When the item types differ, say that Zotero's Duplicate Items view will not show the group. I merge them in Zotero; do not change these items.
+2. Retractions and corrections: run zotero_check_retractions, and call it again while still_unchecked > 0. List the retracted works and the expressions of concern first, then the corrections. Give the notice for each (type, date, DOI).
+3. Files and notes without a parent item: run zotero_standalone_items and give the count by kind, with the first ten names.
+
+The report: one short section for each part, with counts first. Say how many items were checked and how many had no DOI (those cannot be checked for retractions). If a part found nothing, say so in one line.
+
+Then, if there are retracted works or expressions of concern, propose the tag _retracted for them with one zotero_tag_items call (dry_run=false), so that I see one preview for all of them. Do not tag corrections. For the files without a parent item, offer the steps of "Files and notes without a parent item"; do not start them without my answer.

package/prompts/compare.md

@@ -8,7 +8,7 @@ Make a short slug: lower case, hyphens, at most five words. Use today's date (YY
 
 1. Find the sources.
    - If the user gave citekeys, DOIs or PMIDs, use exactly those.
-   - Otherwise: library first (zotero_find_items, with the user's own words and then close synonyms), then scholar_search_multi with three phrasings. Choose 3 to 10 sources and say why.
+   - Otherwise: library first (one zotero_find_items call with queries: the user's own words, then close synonyms), then scholar_search_multi with three phrasings. Choose 3 to 10 sources and say why.
 2. Read each source before you describe it: zotero_get_fulltext for library items, scholar_read_oa_fulltext (methods and results) for open-access works, scholar_get_work for the abstract of the others. Note whether you read the full text or only the abstract.
 3. Build the matrix, one row per source:
    | # | Source | Claim on the question | Evidence type | Population and setting | Caveats | Confidence |

package/prompts/lit.md

@@ -18,9 +18,9 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
 
 ## 2. Gather
 
-1. Library first: zotero_find_items for the topic, with the user's own words first and then with close synonyms and word forms, one call for each (and the topic tags). Note what the library already has.
+1. Library first: one zotero_find_items call for the topic with queries: the user's own words first, then close synonyms and word forms (and the topic tags). Note what the library already has. Check that the items that only a synonym found (found_by without q1) are on the topic before you use them.
 2. Outside: scholar_search_multi with three or four phrasings of the question (synonyms, the test or drug name, the condition name, MeSH terms). Give include_terms (the key concepts) and exclude_terms (populations or designs outside the question) so that the server pre-screens the results. Use year limits when the question needs recent work.
-3. Screen. For every work in the merged list, decide: read, maybe, or exclude, with a reason of a few words. Prefer systematic reviews, guidelines and primary studies with the right design. Write the screening log to `Research/.plans/<slug>-screening.md`: a table (#, work, identifier, pre-screen, decision, reason) and the counts for a flow diagram: found by the searches, unique works, pre-screen excluded, screened, read, used.
+3. Screen. For every work in the merged list, decide: read, maybe, or exclude, with a reason of a few words. Prefer systematic reviews, guidelines and primary studies with the right design. Write the screening log to `Research/.plans/<slug>-screening.md`: a table (#, work, identifier, pre-screen, decision, reason) and the counts for a flow diagram: found by the searches (the library search included), duplicates removed, unique works, of these already in the library, pre-screen excluded, screened, read, used.
 4. Read before you summarise:
    - Library items: zotero_get_fulltext, or the abstract when there is no full text.
    - Open-access works: scholar_read_oa_fulltext, first the section list, then only the sections you need (usually methods and results).
@@ -62,6 +62,8 @@ review_type: AI-assisted rapid review (not a systematic review)
 question: "<question in one sentence>"
 searches: ["<phrasing 1>", "<phrasing 2>", "<phrasing 3>"]
 sources_found: <number of unique works>
+duplicates_removed: <number>
+sources_in_library: <number of unique works already in the library>
 sources_screened: <number>
 sources_read: <number>
 sources_used: <number>
@@ -94,7 +96,8 @@ Under Methods, after the text, draw the flow of works with the counts of the scr
 
 ```mermaid
 flowchart TD
-  A["Found by the searches: <n>"] --> B["Unique works: <n>"]
+  A["Found by the searches: <n>"] --> B["Unique works: <n> (in the library: <n>)"]
+  A -.-> X0["Duplicates removed: <n>"]
   B -.-> X1["Excluded by the pre-screen: <n>"]
   B --> C["Screened: <n>"]
   C -.-> X2["Excluded at screening: <n>"]
@@ -103,7 +106,7 @@ flowchart TD
   D --> E["Used in this note: <n>"]
 ```
 
-The counts must add up: unique works = pre-screen excluded + screened; screened = excluded at screening + read; read = not used + used.
+The counts must add up: found = duplicates removed + unique works; unique works = pre-screen excluded + screened; screened = excluded at screening + read; read = not used + used.
 
 If a step fails (a service does not answer, a full text cannot be read), do not stop. Finish the note, mark the step "BLOCKED: <what failed>", and set verification: BLOCKED.
 
@@ -129,3 +132,5 @@ When the user asks for a reading list (for example `/lit reading list: <topic>`,
 The Methods section has the same flow diagram, with "On the reading list: <n>" as the last box. "What it studies" says what the work asks and how, never what it found. Do not state results, effect sizes or conclusions anywhere in the note. Then give the user the path, the first work to read and why, and the works worth adding to the library.
 
 Before you answer, read the note back to confirm that it exists. For a review, give the user the path, the answer in three lines, and the works worth adding to the library (offer to import them). For a reading list, give the user what the section above says, with no results.
+
+Then offer a RIS file of the screened works, for a second screening in Rayyan or Covidence: `Research/.plans/<slug>-screened.ris`. Write it only when the user agrees, with one scholar_export_bibliography call: citekeys for the library items, and identifiers (the DOI, or pmid:<number>) for the others. Report the works it did not find.

package/roles/librarian.md

@@ -12,7 +12,8 @@ You change the library through the zotero_ tools. Outside metadata reaches you t
 - Call a write tool with dry_run=false when you intend the change. Sub-Sub shows {{user}} the server's preview and applies it only on approval.
 - 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}}.
+- Start a session with zotero_status. If Zotero is not reachable, stop and tell {{user}}: the Librarian needs Zotero. Searches in PubMed, Europe PMC and OpenAlex work without Zotero in the Researcher.
+- Group libraries are read-only. zotero_list_libraries lists them. To search or read a group, pass library="group:<id>" to the read tools (find_items, get_item, get_fulltext, get_figure, find_duplicates, check_retractions and others). A reference written as "<citekey or key> in group:<id>" is in that group. You cannot change items in a group: say so, and tell {{user}} to change them in the Zotero window.
 - 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

package/roles/researcher.md

@@ -24,13 +24,14 @@ You read the Zotero library (zotero_ tools), search PubMed, Europe PMC and OpenA
 - Call a write tool with dry_run=false when you intend the change. Sub-Sub shows {{user}} the server's preview and applies it only on approval. The same holds for scholar_attach_note and scholar_export_bibliography.
 - 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}}.
+- Start work on the library with zotero_status. If Zotero is not reachable, tell {{user}} that the library tools do not work until Zotero is open. When the request does not need the library, continue with the scholar tools, and do not say whether a work is in the library.
+- Group libraries are read-only. zotero_list_libraries lists them. To search or read a group, pass library="group:<id>" to the read tools (find_items, get_item, get_fulltext, get_figure, find_duplicates, check_retractions and others). A reference written as "<citekey or key> in group:<id>" is in that group. You cannot change items in a group: say so, and tell {{user}} to change them in the Zotero window.
 - 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
 
-- "What do I have on X": search with zotero_find_items (query, tags, fulltext=true when needed). First search with {{user}}'s own words, as written. Then search again with close synonyms and other word forms (singular and plural, noun and adjective, spelling variants, an older or foreign name), one call for each. Join the results and list each item once. Answer in the chat: citekey, year, one line per item, and the words you searched.
+- "What do I have on X": search with one zotero_find_items call with queries: first {{user}}'s own words, as written, then close synonyms and other word forms (singular and plural, noun and adjective, spelling variants, an older or foreign name). Add tags, or fulltext=true, when needed. Answer in the chat: citekey, year, one line per item, and the words you searched. Put the items that only a synonym found (found_by without q1) under their own head, "Found only by a synonym", with the synonym after each: they can be only near the topic. When zotero_list_libraries shows group libraries, search them too with the same queries, and name the group of each item from a group.
 
 ## Outside search and gaps
 

package/src/chrome.ts

@@ -116,7 +116,7 @@ export function toolLine(opts: { state: ToolState; word: string; detail?: string
 export function toolDetail(args: unknown, max = 40): string {
 	if (!args || typeof args !== "object") return "";
 	const a = args as Record<string, unknown>;
-	for (const k of ["query", "q", "title", "citekey", "key", "keys", "doi", "identifier", "path", "name", "text"]) {
+	for (const k of ["query", "queries", "q", "title", "citekey", "key", "keys", "doi", "identifier", "path", "name", "text"]) {
 		const v = a[k];
 		if (v === undefined || v === null || v === "") continue;
 		const s = Array.isArray(v) ? v.filter((x) => typeof x !== "object").join(", ") : String(v);

package/src/config.ts

@@ -62,7 +62,7 @@ export function uiLanguage(language: string | undefined): "pt" | "en" {
 }
 
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.6.0";
+export const SERVER_VERSION = "0.7.0";
 
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";
@@ -107,6 +107,8 @@ export interface SubsubConfig {
 	starbuckDir?: string;
 	/** The pilot's usage log, kept on this computer only (see usage.ts). Off by default. */
 	usageLog?: boolean;
+	/** US dollars per session: a note at 80%, a question before each new request from 100% (see cost.ts). */
+	costLimit?: number;
 }
 
 export function expand(p: string, home?: string): string {
@@ -208,6 +210,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 				? settingsFile(vault, "rules")
 				: undefined,
 		startTimeout: user.startTimeout ?? 45,
+		costLimit: typeof user.costLimit === "number" && user.costLimit > 0 ? user.costLimit : undefined,
 		uvPath: user.uvPath ? expand(user.uvPath, home) : undefined,
 		look: user.look,
 		quotes: user.quotes,

package/src/cost.ts

@@ -0,0 +1,22 @@
+/**
+ * The cost limit of a session (`costLimit` in the settings, in US dollars). At 80% Sub-Sub says so once; from 100%
+ * it asks before each new request. A running answer is never cut.
+ */
+
+export type CostLevel = "ok" | "near" | "over";
+
+/** Where the session's cost is against the limit. An unknown cost (null) or no limit is "ok". */
+export function costStatus(spent: number | null, limit: number | undefined): { level: CostLevel; spent: number; limit?: number } {
+	if (spent === null || !limit || limit <= 0) return { level: "ok", spent: spent ?? 0, limit };
+	return { level: spent >= limit ? "over" : spent >= 0.8 * limit ? "near" : "ok", spent, limit };
+}
+
+export const money = (n: number) => `$${n.toFixed(2)}`;
+
+/** Commands that do not send anything to the model: no question for these. */
+export const LOCAL_COMMANDS = new Set(["subsub", "researcher", "librarian", "history", "undo", "notes", "library", "actions", "feedback"]);
+
+export function usesModel(text: string): boolean {
+	const cmd = /^\/([\w-]+)(?:\s|$)/.exec(text.trim())?.[1];
+	return !cmd || !(cmd.startsWith("subsub-") || LOCAL_COMMANDS.has(cmd));
+}

package/src/doctor.ts

@@ -4,7 +4,8 @@
  * Checks Node, the settings file, uv, the Zotero server (it runs
  * `zotero-local-mcp --check`), Zotero itself, the tag list, the notes folder,
  * the contact email, Starbuck (when the add-on is on) and the model login. Exit
- * code 1 when something needs a fix.
+ * code 1 when something needs a fix. Zotero is optional: when it is not
+ * running, the line is a NOTE, because the search tools work without it.
  */
 
 import { spawnSync } from "node:child_process";
@@ -23,6 +24,7 @@ import {
 	refreshedArgs,
 } from "./config.ts";
 import { isObsidianVault, LEGACY_SETTINGS_DIR, SETTINGS_FILES, settingsFile } from "./layout.ts";
+import { customProviders } from "./providers.ts";
 
 export interface Check {
 	name: string;
@@ -55,6 +57,7 @@ function nodeOk(version: string): boolean {
 }
 
 function hasLogin(agentDir: string): boolean {
+	if (customProviders(agentDir).length) return true; // another provider, in models.json
 	try {
 		const data = JSON.parse(readFileSync(join(agentDir, "auth.json"), "utf8"));
 		return Boolean(data) && typeof data === "object" && Object.keys(data).length > 0;
@@ -122,7 +125,14 @@ export function runChecks(
 	out.push(
 		st.zotero === "reachable"
 			? { name: "Zotero", ok: true, detail: `reachable, write permission ${st.write_key_remembered ? "remembered" : "asked at the first change"}` }
-			: { name: "Zotero", ok: false, detail: String(st.error ?? "not reachable"), fix: `Start Zotero 10 or later. ${ZOTERO_SETTING}` },
+			: // Optional: without Zotero, Sub-Sub still searches PubMed, Europe PMC and OpenAlex and writes notes.
+				{
+					name: "Zotero",
+					ok: true,
+					warn: true,
+					detail: `${String(st.error ?? "not reachable")}: the search tools work, the library tools do not`,
+					fix: `Start Zotero 10 or later. ${ZOTERO_SETTING}`,
+				},
 	);
 	const v = st.vocabulary ?? {};
 	if (v.loaded === false || !v.tags) {

package/src/init.ts

@@ -19,7 +19,8 @@
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --folder (or --notes), --move
  * yes|no, --tags health-sciences|health-informatics|any-field,
- * --email, --starbuck on|off, --models keep|later|opencode-go|mistral-eu|google-free.
+ * --email, --starbuck on|off, --models keep|later|opencode-go|mistral-eu|google-free|custom,
+ * and for custom: --provider-url, --provider-key, --provider-model.
  */
 
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -44,6 +45,7 @@ import {
 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 { CUSTOM_DEFAULT_NAME, type CustomProvider, saveCustomProvider } from "./providers.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 
@@ -55,6 +57,16 @@ export const STARTER_TAGS: Record<string, string> = {
 
 export const TESTED_MODELS = DEFAULT_MODELS;
 
+/**
+ * After a login in subsub web or subsub tui: when no models are set yet, OpenCode Go gets the tested models and
+ * another provider (spec "<name>/<id>") its own model in both modes. Models already chosen stay.
+ */
+export function modelsAfterLogin(env: NodeJS.ProcessEnv, provider: string, spec?: string): void {
+	if (Object.keys(loadConfig(env).models).length) return;
+	if (spec) saveConfig({ models: { librarian: spec, researcher: spec }, model: undefined }, env);
+	else if (provider === "opencode-go") saveConfig({ models: TESTED_MODELS, model: undefined }, env);
+}
+
 export interface InitIO {
 	ask(question: string, def: string): Promise<string>;
 	choose(question: string, options: Array<{ value: string; label: string }>, def: string): Promise<string>;
@@ -252,6 +264,7 @@ export async function runInit(
 		{ 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)` },
+		{ value: "custom", label: "Another provider that speaks the OpenAI API: your institution's server, or a local one (Ollama, LM Studio)" },
 	];
 	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";
@@ -266,6 +279,20 @@ export async function runInit(
 		googleKey = (await io.ask("Google API key (Enter to add it later with the model button or /login)", "")).trim();
 	}
 
+	let custom: CustomProvider | undefined;
+	if (models === "custom") {
+		explain(
+			"Another provider",
+			`Give the address of the server (it usually ends in /v1), the API key and the model id. Sub-Sub saves them in ${join(agentDir, "models.json")}, readable only by you, and uses the model in both modes. Your messages go to that server.`,
+		);
+		custom = {
+			name: CUSTOM_DEFAULT_NAME,
+			baseUrl: (await io.ask("Server address, e.g. https://llm.example.org/v1", flags["provider-url"] ?? "")).trim(),
+			apiKey: (await io.ask("API key (Enter for none, for a local server)", flags["provider-key"] ?? "")).trim(),
+			models: [(await io.ask("Model id", flags["provider-model"] ?? "")).trim()],
+		};
+	}
+
 	// ---- write
 	if (move === "yes") applyMoves(moves);
 	for (const dir of [notes, ...NOTE_DIRS.map((d) => join(notes, d)), join(notes, SETTINGS_DIR)]) {
@@ -315,8 +342,18 @@ export async function runInit(
 	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 (custom) {
+		try {
+			const [spec] = saveCustomProvider(agentDir, custom);
+			patch.models = { librarian: spec, researcher: spec };
+			keyNote = `Saved: the provider ${custom.name}, in ${join(agentDir, "models.json")}`;
+		} catch (err) {
+			patch.models = current.models;
+			keyNote = `The provider was not saved: ${(err as Error).message} Type subsub init again, or choose a model in Sub-Sub.`;
+		}
+	}
+	saveConfig(patch, initEnv);
 	if (googleKey) {
 		try {
 			saveApiKey(agentDir, "google", googleKey);

package/src/look.ts

@@ -84,8 +84,8 @@ type Lang = "en" | "pt";
 
 /** The words of the library line, as in the web view (web/i18n.js: zoteroChecking, zoteroDown, items, toReview). */
 export const LIBRARY_WORDS = {
-	en: { checking: "Zotero: checking...", down: "Zotero is not running. Start it, then type /subsub.", items: "items", toCheck: "to check", prefix: "Zotero" },
-	pt: { checking: "Zotero: a verificar...", down: "O Zotero não está aberto. Abra-o e escreva /subsub.", items: "itens", toCheck: "por verificar", prefix: "Zotero" },
+	en: { checking: "Zotero: checking...", down: "Zotero is closed: search only. Start it, then type /subsub.", items: "items", toCheck: "to check", prefix: "Zotero" },
+	pt: { checking: "Zotero: a verificar...", down: "O Zotero está fechado: só pesquisa. Abra-o e escreva /subsub.", items: "itens", toCheck: "por verificar", prefix: "Zotero" },
 };
 
 function cut(s: string, width: number): string {

package/src/prompt.ts

@@ -56,7 +56,12 @@ export function roleText(mode: Mode, cfg?: Pick<SubsubConfig, "userName" | "abou
 	return cfg ? fill(raw, cfg) : raw;
 }
 
-export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): string {
+/** What Sub-Sub knows now: `zoteroDown` when the last check found Zotero closed. */
+export interface PromptState {
+	zoteroDown?: boolean;
+}
+
+export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string, state: PromptState = {}): string {
 	const user = who(cfg);
 	const parts = [`# Sub-Sub: ${mode === "librarian" ? "Librarian" : "Researcher"} mode`, roleText(mode, cfg)];
 	if (cfg.vault) {
@@ -85,6 +90,14 @@ export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): stri
 			`${capital(user)} works at the University of Porto. Papers that are not open access often open through the university's subscriptions when ${user} uses Sub-Sub on the U.Porto network: say so when a work is not open access.`,
 		);
 	}
+	if (state.zoteroDown) {
+		parts.push(
+			"# Zotero is closed",
+			mode === "librarian"
+				? `Zotero is not running now, so the zotero_ tools fail. The Librarian needs Zotero: tell ${user} to start Zotero and type /subsub. In the Researcher, searches in PubMed, Europe PMC and OpenAlex work without Zotero.`
+				: `Zotero is not running now, so the zotero_ tools fail. The scholar_ tools work: search PubMed, Europe PMC and OpenAlex, read open-access full texts, and write notes in the Sub-Sub folder. When a request needs ${user}'s library, say that Zotero is closed and ask ${user} to start it and type /subsub. Do not say whether a work is in the library.`,
+		);
+	}
 	// The language rule comes last, so it wins over the shared rules and the vault conventions.
 	parts.push("# Language", languageRule(cfg.language, user));
 	return parts.join("\n\n");

package/src/providers.ts

@@ -0,0 +1,82 @@
+/**
+ * A model provider that pi does not include: a server that speaks the OpenAI API (an institution's
+ * server, Ollama, LM Studio, vLLM). Sub-Sub writes it to pi's models.json in the agent folder.
+ * The FMUP model service will be one of these.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { KEY_PROVIDERS } from "./keys.ts";
+
+export interface CustomProvider {
+	/** The provider name in pi (models are "<name>/<model id>"). */
+	name: string;
+	baseUrl: string;
+	/** Empty for a local server without a key. */
+	apiKey?: string;
+	models: string[];
+}
+
+export const CUSTOM_DEFAULT_NAME = "custom";
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/** The problem with a custom provider, or undefined when it can be saved. */
+export function customProviderProblem(p: CustomProvider): string | undefined {
+	if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(p.name)) return "The provider name can have only lowercase letters, digits and hyphens.";
+	if (KEY_PROVIDERS.some((k) => k.id === p.name)) return `${p.name} is a provider that pi already has: select it in the list.`;
+	let url: URL;
+	try {
+		url = new URL(p.baseUrl.trim());
+	} catch {
+		return "The address must be a full URL, for example https://llm.example.org/v1.";
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") return "The address must start with https://.";
+	if (url.protocol === "http:" && !LOCAL_HOSTS.has(url.hostname)) return "Use https:// for a server on another computer, so that your key and your messages are encrypted.";
+	const key = (p.apiKey ?? "").trim();
+	if (/\s/.test(key) || key.length > 400) return "That does not look like an API key.";
+	const ids = p.models.map((m) => m.trim()).filter(Boolean);
+	if (!ids.length) return "Give at least one model id.";
+	if (ids.some((m) => /\s/.test(m) || m.length > 200)) return "A model id has no spaces.";
+	return undefined;
+}
+
+/**
+ * Add or replace the provider in <agentDir>/models.json; other providers stay. The file is readable only by
+ * the user, because it can hold the key. Returns the model specs ("<name>/<id>").
+ */
+export function saveCustomProvider(agentDir: string, p: CustomProvider): string[] {
+	const problem = customProviderProblem(p);
+	if (problem) throw new Error(problem);
+	mkdirSync(agentDir, { recursive: true });
+	const file = join(agentDir, "models.json");
+	let data: { providers?: Record<string, unknown> } & Record<string, unknown> = {};
+	if (existsSync(file)) {
+		try {
+			data = JSON.parse(readFileSync(file, "utf8")) ?? {};
+		} catch {
+			throw new Error(`${file} is not valid JSON; fix it first.`);
+		}
+	}
+	const ids = [...new Set(p.models.map((m) => m.trim()).filter(Boolean))];
+	data.providers = {
+		...(data.providers ?? {}),
+		// pi shows a provider's models only when it has a key; a local server ignores the placeholder.
+		[p.name]: { baseUrl: p.baseUrl.trim(), api: "openai-completions", apiKey: (p.apiKey ?? "").trim() || "none", models: ids.map((id) => ({ id })) },
+	};
+	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+	chmodSync(file, 0o600); // also when the file was there before
+	return ids.map((id) => `${p.name}/${id}`);
+}
+
+/** The providers in <agentDir>/models.json that have at least one model. */
+export function customProviders(agentDir: string): string[] {
+	try {
+		const data = JSON.parse(readFileSync(join(agentDir, "models.json"), "utf8"));
+		return Object.entries((data?.providers ?? {}) as Record<string, { models?: unknown[] }>)
+			.filter(([, v]) => Array.isArray(v?.models) && v.models.length > 0)
+			.map(([k]) => k);
+	} catch {
+		return [];
+	}
+}

package/src/roles.ts

@@ -87,6 +87,17 @@ export function toolsFor(mode: Mode, registered: string[], opts: ToolOptions = {
 	return [...new Set(wanted)].filter((n) => has.has(n));
 }
 
+/**
+ * The active tools for `next`, Sub-Sub's set for the mode. Inside plain pi, Sub-Sub replaces only its own
+ * server tools and keeps the rest (pi's tools, other extensions' tools); with the `subsub` command, the set is
+ * Sub-Sub's alone.
+ */
+export function activeTools(current: string[], next: string[], standalone: boolean): string[] {
+	if (standalone) return next;
+	const kept = current.filter((n) => !SERVER_PREFIXES.some((p) => n.startsWith(p)));
+	return [...new Set([...kept, ...next])];
+}
+
 /** Why a Sub-Sub tool is not available now, or undefined when it is. */
 export function unavailableReason(name: string, mode: Mode, registered: string[], opts: ToolOptions = {}): string | undefined {
 	if (toolsFor(mode, registered, opts).includes(name)) return undefined;