@tiagojct/subsub 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Sub-Sub follows the version numbers of npm: a change in the second number (0.13) adds features or changes how you use it; a change in the third (0.13.1) only fixes.
 
+## 0.24.1 (2026-11-01)
+
+- In the terminal, the tool line of a library search with several queries (your words and their synonyms, 0.24.0) shows the words it searched. It showed nothing after the tool name.
+
+## 0.24.0 (2026-11-01)
+
+With the Zotero server 0.7.0.
+
+- Inside plain pi, Sub-Sub no longer turns off the tools of pi and of your other extensions: it adds its own and swaps only those when the mode changes (issue #1). The `subsub` command, `subsub web` and `subsub tui` keep only Sub-Sub's tools, as before.
+- Without Zotero. Sub-Sub starts when Zotero is closed, and `subsub doctor` shows a NOTE, not a FIX. The library line says "Zotero is closed: search only". The Researcher can then search PubMed, Europe PMC and OpenAlex, read open-access full texts and write notes; the Librarian needs Zotero. Sub-Sub is still made to start from your Zotero library. A new FAQ in the README and on the Help page says this.
+- Searching the library: one search with your words and their synonyms. The items that only a synonym found are listed under their own head, "Found only by a synonym", because they can be only near the topic.
+- Another provider that speaks the OpenAI API: your institution's server, or a local one (Ollama, LM Studio). Connect it in `subsub init`, in the browser view (the model button, "Another provider") or with `/login` in `subsub tui`. Sub-Sub saves it in `models.json`, readable only by you; a server on another computer must use https. This is also how the FMUP model service will connect.
+- Group libraries, read-only. The library search covers your library and the group libraries in Zotero, and marks each item from a group with the group's name. Sub-Sub can read, quote and write notes on items in a group; it cannot change them.
+- `subsub tui`: `/login` connects a provider (an API key, shown as stars, or another provider), and `/resume` opens the earlier conversations.
+- A cost limit. With `"costLimit": 2` (US dollars) in the settings, Sub-Sub says when a conversation has used 80% of it, and from the limit on it asks before each new request to the model. It never stops an answer that is running. The browser view then shows the cost next to the model.
+- `/check-library` (Check the library in the actions): duplicates, retracted or corrected works and files without a parent item, in one report, then one preview to tag the retracted works `_retracted`. Sub-Sub does not merge or delete.
+- `/lit` counts the duplicates removed and the works already in your library, in the screening log and the flow diagram. At the end it offers a RIS file of the screened works, for a second screening in Rayyan or Covidence. Bibliographies can now be RIS as well as CSL JSON, and can include works that are not in your library (by DOI, PMID or ISBN).
+- Tests: plain pi with other tools, the prompt without Zotero, the library search with groups, the provider checks, `/login` in `subsub tui` with the key hidden, the cost limit, and the new command.
+
 ## 0.23.0 (2026-10-24)
 
 - The browser view is set like the website. Replies and notes have the website's headings (a fine rule above each section), its numbered steps and a slightly larger text. A note opens on the lighter field of a page, and the list of notes is grouped by folder under small-capital heads, with the date on the right. The empty conversation has the website's running head and a larger heading. Notes and the model in the top bar are plain text buttons, as in the website's menu. A command you send (`/read ...`) is shown in the mono. The working line is drawn dotted, dashed and solid, as in the terminal, instead of a moving gradient. Scrollbars are thin. On a phone, Notes is no longer cut to "No..." (the theme button is in the side panel there).

package/README.md

@@ -39,7 +39,7 @@ The [Commands page](https://subsub.tiagojacinto.eu/profiles/) lists the tools an
 
 ## Requirements
 
-- Zotero 10 or later, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" on.
+- Zotero 10 or later, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" on. Sub-Sub starts without Zotero, but then only the search tools work (see [FAQ](#faq)).
 - Node.js 22.19 or later, and [uv](https://docs.astral.sh/uv/). The installers add both if they are missing.
 - An account with a model provider that pi supports (for example OpenCode Go, OpenRouter, Anthropic, OpenAI, Mistral, Google), or a local model. To try Sub-Sub without paying, a free Google AI Studio key is enough (see [Use Sub-Sub for free](https://subsub.tiagojacinto.eu/models/#use-sub-sub-for-free)).
 - macOS, Linux or Windows.
@@ -70,7 +70,7 @@ subsub doctor
 
 `subsub init` asks a few questions. Press Enter to accept the default. It creates the Sub-Sub folder (`~/Documents/Sub-Sub`, or a `Sub-Sub` folder inside your Obsidian vault) with `Inbox/`, `Literature/`, `Syntheses/`, `Research/` and `Zotero/`, a starter tag list (`Zotero/Zotero tags.md`) and the note formats (`Zotero/Zotero agent.md`). `subsub doctor` checks the set-up; each line marked FIX says what to do.
 
-If you already use pi, you can add Sub-Sub to it: `pi install npm:@tiagojct/subsub`.
+If you already use pi, you can add Sub-Sub to it: `pi install npm:@tiagojct/subsub`. Sub-Sub then adds its tools and keeps pi's tools and the tools of your other extensions.
 
 Sub-Sub runs its Zotero server, [zotero-local-mcp](https://github.com/tiagojct/zotero-local-mcp), from PyPI with uv.
 
@@ -89,7 +89,7 @@ In the browser view, connect a model provider with the model button. In the term
 
 The terminal has its own look, drawn like the website: a footer with the mode, the library, the model, the context in use and the cost; Sub-Sub's tools in plain words (`search the library: asthma`); and an approval screen for library changes (`y` applies, `n` or Esc leaves the library as it is, Enter does nothing). `/notes`, `/library` and `/actions` open screens for your notes, a library search and the actions of the browser view; F2, F3, F4 and F5 (mode) are shortcuts; so are Alt+N, Alt+L, Alt+A and Alt+M where your terminal sends Alt (in macOS Terminal and iTerm2, Option types a symbol unless you turn on "Use Option as Meta key", and a Mac needs Fn with the F key unless the F keys are set as standard). Nothing is red: a failure is ink with a hollow mark and a word, and a removal is struck through. For terminals that cannot draw box glyphs, set `SUBSUB_ASCII=1`; `SUBSUB_REDUCE_MOTION=1` stops the working indicator from moving; `"look": false` in the settings brings back the plain screen.
 
-`subsub tui` puts Sub-Sub on the whole terminal, as the browser view puts it in the browser: a conversation that scrolls, a side panel from 110 columns, the editor and the footer, with the same colours and screens. Besides the commands above, `/sessions` and `/new` change the conversation, `/model` chooses the model, `/restart` starts pi again in the same conversation, and `/quit` leaves (Ctrl+C twice also quits). `--light` or `--dark` set the colours when your terminal does not say. It does not have pi's own screens (`/login`, `/settings`, `/tree`, `/resume`): use `subsub` or `subsub web` for them.
+`subsub tui` puts Sub-Sub on the whole terminal, as the browser view puts it in the browser: a conversation that scrolls, a side panel from 110 columns, the editor and the footer, with the same colours and screens. Besides the commands above, `/sessions` (or `/resume`) and `/new` change the conversation, `/model` chooses the model, `/login` connects a provider (an API key, or another provider that speaks the OpenAI API), `/restart` starts pi again in the same conversation, and `/quit` leaves (Ctrl+C twice also quits). `--light` or `--dark` set the colours when your terminal does not say. It does not have pi's other screens (`/settings`, `/tree`, `/fork`) or sign-in through a provider's website: use `subsub` or `subsub web` for them.
 
 The browser view also has a library search (each result can start `/read` or `/lit-note`), a notes pane that shows the notes of your Sub-Sub folder next to the conversation (note paths and `[[links]]` in replies open there), argument hints for the commands, and rename, delete (to `~/.subsub/trash`) and export for conversations.
 
@@ -106,9 +106,10 @@ Commands in Sub-Sub:
 | `/ai-statement [uses]` | A draft statement on the use of AI for a manuscript, with the Sub-Sub version, its DOI and your models |
 | `/tag-batch [size]` | Tag items that have no topic, with your tag list |
 | `/clean-tags` | Find tags that are not in your tag list and propose fixes |
+| `/check-library` | Check the whole library: duplicates, retracted or corrected works, files without a parent item. One report, then one preview to tag retracted works `_retracted` |
 | `/import-queue [path]` | Import the references in the import queue note |
 | `/read [reason] <citekey>` | Guided reading of one paper. Sub-Sub asks why you read it (background, one fact, extraction for a review, critique), finds the passages and asks questions; you write the answers. For extraction it adds a row to your extraction sheet in `Research/` |
-| `/lit <question>` | Literature review: the library first, then one merged search; an evidence table, agreement, disagreement and open questions; one note in `Research/` |
+| `/lit <question>` | Literature review: the library first, then one merged search; an evidence table, agreement, disagreement and open questions; one note in `Research/`, with a flow of the counts (duplicates removed, already in the library, screened, read, used). On request, a RIS file of the screened works for Rayyan or Covidence |
 | `/compare <question or citekeys>` | A matrix of sources: claim, evidence, caveats, confidence |
 | `/lit-note <citekey>` | A literature note on one item, from its full text |
 | `/synthesis <topic>` | A synthesis of what the library says on a topic |
@@ -142,6 +143,7 @@ subsub review apply 13-31
 | `defaultMode` | `researcher` or `librarian` | `researcher` |
 | `addons` | `["starbuck"]` adds reference checks | `[]` |
 | `usageLog` | `true` keeps the pilot's usage log on this computer (`subsub usage`) | off |
+| `costLimit` | US dollars for one conversation, for example `2`. At 80% Sub-Sub says so; from the limit on, it asks before each new request to the model. A running answer is not stopped. The browser view then shows the cost next to the model | none |
 | `serverDir` | A local copy of zotero-local-mcp, for development | the PyPI release |
 | `starbuckDir` | A local copy of Starbuck, for development | the pinned release |
 | `look`, `quotes`, `themes` | The terminal look (header, footer, approval screen, tool lines), the Moby-Dick quotations, and the terminal colours (`subsub-glauca`, `subsub-try-works`, or `false` for your pi theme). `themes` can be `{"researcher": "...", "librarian": "..."}`: the Librarian uses `subsub-try-works` unless you say otherwise | on, on, `subsub-glauca` |
@@ -162,6 +164,18 @@ Sub-Sub finds open-access copies through Unpaywall and Europe PMC. For other pap
 
 Turn it on in `subsub init`, with the switch in the browser view, or with `"addons": ["starbuck"]` in the settings. Then `subsub doctor` must show Starbuck ok. Starbuck writes its report in a `_starbuck` folder next to the manuscript.
 
+## FAQ
+
+### Do I need a Zotero library?
+
+Sub-Sub is made to start from your Zotero library: it reads what you already have, and it finds, imports and tags only what is missing. Use it with Zotero when you can, even if the library is empty at first.
+
+Sub-Sub also starts when Zotero is not running. The library line then says "Zotero is closed: search only". In the Researcher, Sub-Sub can search PubMed, Europe PMC and OpenAlex, read open-access full texts and write notes in the Sub-Sub folder. It cannot search, read, import, tag or undo in the library, and it cannot attach notes to items. The Librarian needs Zotero. `subsub doctor` shows a NOTE for Zotero, not a FIX. Start Zotero and type `/subsub` to connect.
+
+### Can Sub-Sub use group libraries?
+
+Yes, for reading. The library search covers your own library and the group libraries in your Zotero, and marks each item from a group with the group's name. Sub-Sub can read, quote and write notes on items in a group, but it cannot change them (tags, fields, imports): change them in the Zotero window.
+
 ## Model test
 
 `subsub-bench` runs several models on the same tasks against your own library and scores them. Nothing in the library changes. See [docs/model-test.md](https://github.com/tiagojct/subsub/blob/main/docs/model-test.md) and the [Models page](https://subsub.tiagojacinto.eu/models/) for the latest results.

package/dist/chrome.js

@@ -92,7 +92,7 @@ export function toolDetail(args, max = 40) {
     if (!args || typeof args !== "object")
         return "";
     const a = args;
-    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;

package/dist/config.js

@@ -57,7 +57,7 @@ export function uiLanguage(language) {
     return /portug|^pt\b|^pt-/i.test(language ?? "") ? "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";
 export const STARBUCK_SOURCE = `starbuck==${STARBUCK_VERSION}`;
@@ -162,6 +162,7 @@ export function loadConfig(env = process.env) {
                 ? 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/dist/cost.js

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+/** Where the session's cost is against the limit. An unknown cost (null) or no limit is "ok". */
+export function costStatus(spent, limit) {
+    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) => `$${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) {
+    const cmd = /^\/([\w-]+)(?:\s|$)/.exec(text.trim())?.[1];
+    return !cmd || !(cmd.startsWith("subsub-") || LOCAL_COMMANDS.has(cmd));
+}

package/dist/doctor.js

@@ -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";
 import { existsSync, readFileSync } from "node:fs";
@@ -12,6 +13,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { findUv, loadConfig, SERVER_VERSION, serverCommand, STARBUCK_SOURCE, starbuckCommand, starbuckEnabled, refreshedArgs, } from "./config.js";
 import { isObsidianVault, LEGACY_SETTINGS_DIR, SETTINGS_FILES, settingsFile } from "./layout.js";
+import { customProviders } from "./providers.js";
 export const defaultRunner = (command, args, env) => {
     const r = spawnSync(command, args, { env, encoding: "utf8", timeout: 120_000 });
     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error?.message };
@@ -22,6 +24,8 @@ function nodeOk(version) {
     return major > 22 || (major === 22 && minor >= 19);
 }
 function hasLogin(agentDir) {
+    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;
@@ -80,7 +84,14 @@ export function runChecks(cfg, env, deps = {}) {
     out.push({ name: "Zotero server", ok: true, detail: local ? `from ${cfg.serverDir}` : `zotero-local-mcp ${SERVER_VERSION}` });
     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) {
         const path = v.path && v.path !== "None" ? v.path : undefined; // the server writes Python's None when unset

package/dist/init.js

@@ -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";
 import { homedir } from "node:os";
@@ -30,6 +31,7 @@ import { configPath, DEFAULT_MODELS, EU_MODELS, FREE_MODELS, expand, loadConfig,
 import { defaultRunner, starbuckCheck } from "./doctor.js";
 import { applyMoves, FOLDER_NAME, leftBehind, NOTE_DIRS, planMoves, SETTINGS_DIR, SETTINGS_FILES, subsubFolder } from "./layout.js";
 import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
+import { CUSTOM_DEFAULT_NAME, saveCustomProvider } from "./providers.js";
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 export const STARTER_TAGS = {
     "health-sciences": "Health sciences: clinical areas, public health, methods and study designs",
@@ -37,6 +39,18 @@ export const STARTER_TAGS = {
     "any-field": "Any field: methods and document types only; Sub-Sub proposes topics from your library",
 };
 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, provider, spec) {
+    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);
+}
 /** Set KEY=VALUE lines in an env file text; other lines and comments stay. */
 export function upsertEnv(text, values) {
     const lines = text ? text.replace(/\n$/, "").split("\n") : [];
@@ -173,6 +187,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         { 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";
@@ -183,6 +198,16 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         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();
     }
+    let custom;
+    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);
@@ -235,8 +260,19 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         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.message} Type subsub init again, or choose a model in Sub-Sub.`;
+        }
+    }
+    saveConfig(patch, initEnv);
     if (googleKey) {
         try {
             saveApiKey(agentDir, "google", googleKey);

package/dist/look.js

@@ -55,8 +55,8 @@ export function themeName(scheme, base = DEFAULT_THEME, colorMode) {
 export const plain = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, ok: (s) => s, pend: (s) => s, strike: (s) => s };
 /** 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, width) {
     return [...s].length > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;

package/dist/prompt.js

@@ -50,7 +50,7 @@ export function roleText(mode, cfg) {
     const raw = readIf(join(ROLE_DIR, `${mode}.md`)) ?? `You are Sub-Sub, the ${mode}.`;
     return cfg ? fill(raw, cfg) : raw;
 }
-export function systemAddition(mode, cfg, cwd) {
+export function systemAddition(mode, cfg, cwd, state = {}) {
     const user = who(cfg);
     const parts = [`# Sub-Sub: ${mode === "librarian" ? "Librarian" : "Researcher"} mode`, roleText(mode, cfg)];
     if (cfg.vault) {
@@ -70,6 +70,11 @@ export function systemAddition(mode, cfg, cwd) {
     if (cfg.setup === "fmup") {
         parts.push("# U.Porto", `${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/dist/providers.js

@@ -0,0 +1,78 @@
+/**
+ * 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.js";
+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) {
+    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;
+    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, p) {
+    const problem = customProviderProblem(p);
+    if (problem)
+        throw new Error(problem);
+    mkdirSync(agentDir, { recursive: true });
+    const file = join(agentDir, "models.json");
+    let data = {};
+    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) {
+    try {
+        const data = JSON.parse(readFileSync(join(agentDir, "models.json"), "utf8"));
+        return Object.entries((data?.providers ?? {}))
+            .filter(([, v]) => Array.isArray(v?.models) && v.models.length > 0)
+            .map(([k]) => k);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/roles.js

@@ -69,6 +69,17 @@ export function toolsFor(mode, registered, opts = {}) {
     ];
     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, next, standalone) {
+    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, mode, registered, opts = {}) {
     if (toolsFor(mode, registered, opts).includes(name))

package/dist/screens.js

@@ -204,6 +204,11 @@ export class NotesView {
         this.o.redraw?.();
     }
 }
+/** How a command names an item: the citekey (or key), and the group library when it is in one. */
+export function itemRef(it) {
+    const ref = it.citekey || it.key;
+    return it.library ? `${ref} in ${it.library}` : ref;
+}
 export function libraryLines(o) {
     const g = o.glyphs ?? UNICODE;
     const p = o.paint;
@@ -225,7 +230,7 @@ export function libraryLines(o) {
         const start = Math.max(0, Math.min(o.selected - Math.floor(fit / 2), o.items.length - fit));
         for (const [k, it] of o.items.slice(start, start + fit).entries()) {
             const chosen = start + k === o.selected;
-            const meta = [it.authors, it.year, it.citekey].filter(Boolean).join(" · ");
+            const meta = [it.authors, it.year, it.citekey, it.group].filter(Boolean).join(" · ");
             out.push(chosen ? `${p.mark(g.pointer)} ${p.text(cut(it.title || it.key, w - 2))}` : `  ${p.muted(cut(it.title || it.key, w - 2))}`, `  ${p.dim(cut(meta, w - 2))}`);
         }
     }
@@ -398,7 +403,8 @@ export class InputView {
         this.text = o.prefill ?? "";
     }
     render(width) {
-        return fill(inputLines({ title: this.o.title, placeholder: this.o.placeholder, text: this.text, width, lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs }), width);
+        const text = this.o.secret ? "*".repeat([...this.text].length) : this.text;
+        return fill(inputLines({ title: this.o.title, placeholder: this.o.placeholder, text, width, lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs }), width);
     }
     invalidate() { }
     handleInput(data) {

package/dist/subsub.js

@@ -30,14 +30,15 @@ import { describeArgs, formatPreview, isEmptyPreview } from "./preview.js";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.js";
 import { headerLines, LIBRARIAN_THEME, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
 import { footerLines, toolRenderers, usageTotals } from "./chrome.js";
+import { costStatus, money, usesModel } from "./cost.js";
 import { ApprovalView } from "./dialogs.js";
 import { allowedFile, listNotes, OPENABLE, openFile } from "./files.js";
-import { LibraryView, NotesView } from "./screens.js";
+import { itemRef, LibraryView, NotesView } from "./screens.js";
 import { glyphs, paintFromTheme, workingFrames } from "./skin.js";
 import { loadWords, toolWord } from "./words.js";
 import { systemAddition } from "./prompt.js";
 import { logUsage } from "./usage.js";
-import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason, outboundProblem } from "./roles.js";
+import { activeTools, gateKind, SERVER_PREFIXES, toolsFor, unavailableReason, outboundProblem } from "./roles.js";
 const MODE_ENTRY = "subsub-mode";
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 const BENCH_ENTRY = "subsub-bench";
@@ -152,6 +153,8 @@ export async function createSubsub(pi, deps = {}) {
     let resumeTimer;
     let turnStart = 0;
     let turnTools = 0;
+    /** The cost level already noted in this session, so each note comes once. */
+    let costNoted;
     let webCtx;
     function emitWeb() {
         const ctx = webCtx;
@@ -167,6 +170,8 @@ export async function createSubsub(pi, deps = {}) {
             userName: cfg.userName ?? null,
             vault: cfg.vault ?? null,
             starbuck: starbuckEnabled(cfg),
+            // Shown next to the model only when there is a limit.
+            cost: cfg.costLimit ? { spent: usageTotals(ctx.sessionManager.getEntries()).cost, limit: cfg.costLimit } : null,
         };
         try {
             ctx.ui.setStatus("subsub.web", JSON.stringify(state));
@@ -242,14 +247,9 @@ export async function createSubsub(pi, deps = {}) {
     async function openLibrary(ctx) {
         if (!screenOk(ctx))
             return;
-        const ref = (it) => it.citekey || it.key;
+        const ref = itemRef;
         await ctx.ui.custom((tui, theme, _keys, done) => new LibraryView({
-            search: async (query) => {
-                const r = await current().call("zotero_find_items", { query, limit: 25 });
-                if (r.isError)
-                    throw new Error(r.text);
-                return (r.data?.items ?? []).filter((it) => it && it.key);
-            },
+            search: searchLibraries,
             choose: (it) => {
                 ctx.ui.setEditorText(mode === "researcher" ? `/read ${ref(it)}` : ref(it));
                 done();
@@ -285,6 +285,36 @@ export async function createSubsub(pi, deps = {}) {
             })()
             : text;
     }
+    /** The group libraries in Zotero, from the last library check (read-only; searched with the user's library). */
+    let groups = [];
+    /** Search the user's library, then each group library; a group's items carry the group. */
+    async function searchLibraries(query) {
+        const first = await current().call("zotero_find_items", { query, limit: 25 });
+        if (first.isError)
+            throw new Error(first.text);
+        const items = (first.data?.items ?? []).filter((it) => it && it.key);
+        for (const g of groups) {
+            const r = await current().call("zotero_find_items", { query, limit: 25, library: g.library });
+            if (r.isError)
+                continue;
+            for (const it of r.data?.items ?? [])
+                if (it?.key)
+                    items.push({ ...it, library: g.library, group: g.name });
+        }
+        return items;
+    }
+    async function refreshGroups() {
+        if (!current().has("zotero_list_libraries"))
+            return;
+        try {
+            const r = await current().call("zotero_list_libraries", {});
+            const all = (r.data?.libraries ?? []);
+            groups = r.isError ? [] : all.filter((l) => l.library?.startsWith("group:")).map((l) => ({ library: l.library, name: l.name || l.library }));
+        }
+        catch {
+            groups = [];
+        }
+    }
     async function refreshLibrary() {
         try {
             const st = await current().call("zotero_status", {});
@@ -296,6 +326,7 @@ export async function createSubsub(pi, deps = {}) {
                 const ov = await current().call("zotero_library_overview", {});
                 const o = (ov.data ?? {});
                 Object.assign(library, { zotero: "reachable", items: o.items, toReview: o.awaiting_review });
+                await refreshGroups();
             }
         }
         catch {
@@ -366,7 +397,7 @@ export async function createSubsub(pi, deps = {}) {
     /** Set the mode's tools and, unless `switchModel` is false, the mode's model. */
     async function applyMode(ctx, next, remember, switchModel = true) {
         mode = next;
-        pi.setActiveTools(toolsFor(mode, registered(), toolOpts()));
+        pi.setActiveTools(activeTools(pi.getActiveTools(), toolsFor(mode, registered(), toolOpts()), standalone));
         const spec = cfg.models[mode];
         if (spec && switchModel) {
             const i = spec.indexOf("/");
@@ -386,6 +417,7 @@ export async function createSubsub(pi, deps = {}) {
         status(ctx);
     }
     pi.on("session_start", async (_event, ctx) => {
+        costNoted = undefined; // a new or another conversation: its own cost
         if (!bridge) {
             const b = new Bridge();
             await b.start(deps.specs ?? serverSpecs(cfg), cfg.startTimeout * 1000);
@@ -486,6 +518,15 @@ export async function createSubsub(pi, deps = {}) {
     // 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) => {
+        const spent = costStatus(usageTotals(ctx.sessionManager.getEntries()).cost, cfg.costLimit);
+        if (spent.level !== "ok" && costNoted !== spent.level) {
+            costNoted = spent.level;
+            ctx.ui.notify(spent.level === "near"
+                ? L(`Sub-Sub: this conversation has used 80% of your cost limit (${money(spent.spent)} of ${money(spent.limit)}).`, `Sub-Sub: esta conversa já usou 80% do seu limite de custo (${money(spent.spent)} de ${money(spent.limit)}).`)
+                : L(`Sub-Sub: this conversation has reached your cost limit (${money(spent.spent)} of ${money(spent.limit)}). Sub-Sub will ask before each new request.`, `Sub-Sub: esta conversa atingiu o seu limite de custo (${money(spent.spent)} de ${money(spent.limit)}). O Sub-Sub vai perguntar antes de cada pedido novo.`), "warning");
+        }
+        if (cfg.costLimit)
+            emitWeb(); // the cost next to the model in the browser view
         if (turnStart)
             logUsage(cfg.usageLog, { ev: "turn", seconds: Math.round((Date.now() - turnStart) / 1000), tools: turnTools, error: providerTrouble(lastError) ?? (lastError ? "other" : undefined) });
         turnStart = 0;
@@ -511,6 +552,17 @@ export async function createSubsub(pi, deps = {}) {
         resumeTimer = undefined;
         resumes = 0;
         const cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+        // Over the cost limit: ask before each new request to the model (a running answer is not cut).
+        const spent = costStatus(usageTotals(ctx.sessionManager.getEntries()).cost, cfg.costLimit);
+        if (spent.level === "over" && usesModel(event.text)) {
+            const text = L(`This conversation has cost ${money(spent.spent)}, over your limit of ${money(spent.limit)} (costLimit in the settings). Send this request to the model?`, `Esta conversa já custou ${money(spent.spent)}, acima do seu limite de ${money(spent.limit)} (costLimit nas definições). Enviar este pedido ao modelo?`);
+            const go = ctx.hasUI ? await ctx.ui.confirm(L("Sub-Sub: cost limit", "Sub-Sub: limite de custo"), text) : false;
+            if (!go) {
+                if (!ctx.hasUI)
+                    ctx.ui.notify(text, "warning");
+                return { action: "handled" };
+            }
+        }
         // 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 });
@@ -530,7 +582,7 @@ export async function createSubsub(pi, deps = {}) {
         turnTools = 0;
     });
     pi.on("before_agent_start", async (event, ctx) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, cfg, ctx.cwd)}`,
+        systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, cfg, ctx.cwd, { zoteroDown: library.zotero === "down" })}`,
     }));
     /** Model test (subsub-bench): record every change instead of asking, and apply none. */
     const benchOut = process.env.SUBSUB_BENCH_OUT ? expand(process.env.SUBSUB_BENCH_OUT) : undefined;
@@ -819,6 +871,9 @@ export async function createSubsub(pi, deps = {}) {
                     lines.push(ov.isError
                         ? ov.text
                         : `Items: ${o.items}. Without tags: ${o.without_manual_tags}. Missing facets: ${JSON.stringify(o.missing_facet)}. Awaiting review (_agent): ${o.awaiting_review}.`);
+                    await refreshGroups();
+                    if (groups.length)
+                        lines.push(`Group libraries (read-only, searched with yours): ${groups.map((g) => g.name).join(", ")}.`);
                 }
             }
             redraw();
@@ -842,8 +897,7 @@ export async function createSubsub(pi, deps = {}) {
             const q = String(args ?? "").trim();
             let out;
             try {
-                const r = await current().call("zotero_find_items", { query: q, limit: 25 });
-                out = r.isError ? { error: r.text } : { items: r.data?.items ?? [] };
+                out = { items: await searchLibraries(q) };
             }
             catch (err) {
                 out = { error: err.message };

package/dist/tui-view.js

@@ -208,7 +208,7 @@ export function sideLines(s, width, rows, p, g = UNICODE) {
     const w = Math.max(16, width);
     const words = SIDE_WORDS[s.lang];
     const mode = s.mode === "librarian" ? "Librarian" : "Researcher";
-    const lib = s.library.zotero === "reachable" ? `${s.library.items ?? "?"} ${s.lang === "pt" ? "itens" : "items"}` : s.library.zotero === "down" ? `${g.hollow} Zotero` : "Zotero...";
+    const lib = s.library.zotero === "reachable" ? `${s.library.items ?? "?"} ${s.lang === "pt" ? "itens" : "items"}` : s.library.zotero === "down" ? `${g.hollow} Zotero: ${s.lang === "pt" ? "só pesquisa" : "search only"}` : "Zotero...";
     const lines = [p.mark(cut(` Sub-Sub ${s.version}`, w)), p.text(cut(` ${mode}`, w)), p.muted(cut(` ${lib}`, w)), p.dim(cut(` ${s.model}`, w)), rule(w, "solid", p.muted, g)];
     for (const [key, word] of [["F2", words.notes], ["F3", words.library], ["F4", words.actions], ["F5", words.mode]])
         lines.push(p.muted(cut(` ${key.padEnd(4)}${word}`, w)));