prism-mcp-server 20.18.1 → 20.19.0

package/dist/config.js

@@ -8,7 +8,10 @@ import { fileURLToPath } from "node:url";
  * validates required ones, and exports them for use throughout the server.
  *
  * Environment variable guide:
- *   BRAVE_API_KEY          — (required) API key for Brave Search Pro. Get one at https://brave.com/search/api/
+ *   BRAVE_API_KEY          — (required for search) API key for Brave Search Pro, and the only
+ *                            thing search needs in fully-local operation. A configured Synalux
+ *                            account supplies it portal-side instead, so exactly one of the two
+ *                            is needed. Get one at https://brave.com/search/api/
  *   GOOGLE_API_KEY         — (optional) API key for Google AI Studio / Gemini. Enables paper analysis.
  *   BRAVE_ANSWERS_API_KEY  — (optional) API key for Brave Answers (AI grounding). Enables brave_answers tool.
  *   SUPABASE_URL           — (optional) Your Supabase project URL. Enables session memory tools.
@@ -18,9 +21,15 @@ import { fileURLToPath } from "node:url";
  *   VOYAGE_API_KEY         — (optional) Voyage AI API key for embeddings.
  *                            Set embedding_provider=voyage to use. https://dash.voyageai.com
  *
- * If a required key is missing, the process exits immediately.
- * If an optional key is missing, a warning is logged but the server continues
- * with reduced functionality (the corresponding tools will be unavailable).
+ * No key is enforced at startup. Nothing here calls process.exit, so a missing
+ * key never stops the server — it starts with reduced functionality and the
+ * affected tools error when they are actually called. Missing keys log a
+ * warning, except BRAVE_API_KEY, which warns only under PRISM_DEBUG_LOGGING.
+ *
+ * Said plainly because the old wording ("the process exits immediately") was
+ * describing behaviour no key has ever had, and read as a hard startup
+ * dependency on a Brave + Firecrawl pair — see issue #188, filed on exactly
+ * that premise.
  */
 // ─── Server Identity ──────────────────────────────────────────
 function resolveServerVersion() {
@@ -66,12 +75,6 @@ if (!BRAVE_ANSWERS_API_KEY && process.env.PRISM_DEBUG_LOGGING === "true") {
 // ─── Optional: Voyage AI Embeddings ──────────────────────────
 // Set embedding_provider=voyage to enable. Requires VOYAGE_API_KEY.
 export const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY; // embedding_provider=voyage
-// ─── Optional: Google Search (Scholar Pipeline Fallback) ──────
-// Used when Brave or Tavily keys are missing.
-// Requires: Google Custom Search API Key + Search Engine ID (CX).
-// Get yours at: https://developers.google.com/custom-search/v1/overview
-export const GOOGLE_SEARCH_API_KEY = process.env.GOOGLE_SEARCH_API_KEY;
-export const GOOGLE_SEARCH_CX = process.env.GOOGLE_SEARCH_CX;
 // ─── v2.0 / v12.1 / v13: Storage Backend Selection ──────────
 // Three backends are implemented:
 //   "local"    — SQLite, fully offline. Free-tier default.
@@ -193,11 +196,17 @@ export const PRISM_SCHEDULER_ENABLED = process.env.PRISM_SCHEDULER_ENABLED !== "
 export const PRISM_SCHEDULER_INTERVAL_MS = parseInt(process.env.PRISM_SCHEDULER_INTERVAL_MS || "43200000", 10 // 12 hours
 );
 // ─── v5.4: Autonomous Web Scholar ─────────────────────────────
-// Background LLM research pipeline powered by Brave Search + Firecrawl.
+// Background LLM research pipeline: web search or free academic discovery,
+// local scrape, LLM synthesis.
 export const FIRECRAWL_API_KEY = process.env.FIRECRAWL_API_KEY;
 export const PRISM_SCHOLAR_ENABLED = process.env.PRISM_SCHOLAR_ENABLED === "true";
-if (PRISM_SCHOLAR_ENABLED && !FIRECRAWL_API_KEY) {
-    console.error("Warning: FIRECRAWL_API_KEY not set. Web Scholar will fall back to free search.");
+// FIRECRAWL_API_KEY is currently unspent: Web Scholar scrapes with its own
+// local scraper, and discovery is now selected by whether a web
+// search is possible at all (portal credentials or BRAVE_API_KEY), not by the
+// presence of this key. Kept exported so an existing .env does not break.
+// The warning below is about the key Scholar actually needs.
+if (PRISM_SCHOLAR_ENABLED && !BRAVE_API_KEY && !SYNALUX_CONFIGURED) {
+    console.error("Warning: no web search configured (BRAVE_API_KEY or a Synalux portal login). Web Scholar will use the free academic sources.");
 }
 export const PRISM_SCHOLAR_INTERVAL_MS = parseInt(process.env.PRISM_SCHOLAR_INTERVAL_MS || "0", 10 // Default manual-only
 );

package/dist/dashboard/server.js

@@ -350,7 +350,7 @@ return false;}
                             firecrawlApiKey: {
                                 type: "string",
                                 title: "Firecrawl API Key",
-                                description: "Optional: API key for Firecrawl (enables Web Scholar pipeline). Get one at https://www.firecrawl.dev/"
+                                description: "Optional and currently unused: Web Scholar scrapes locally, and its discovery is selected by BRAVE_API_KEY or a Synalux portal login. Get one at https://www.firecrawl.dev/"
                             },
                             braveAnswersApiKey: {
                                 type: "string",

package/dist/scholar/webScholar.js

@@ -1,4 +1,4 @@
-import { BRAVE_API_KEY, FIRECRAWL_API_KEY, GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_CX, SEMANTIC_SCHOLAR_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND, PRISM_SCHOLAR_SCRAPE_BUDGET_MS, } from "../config.js";
+import { BRAVE_API_KEY, SEMANTIC_SCHOLAR_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND, PRISM_SCHOLAR_SCRAPE_BUDGET_MS, } from "../config.js";
 import { getStorage } from "../storage/index.js";
 import { debugLog } from "../utils/logger.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
@@ -7,9 +7,12 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync,
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { performWebSearchRaw } from "../utils/braveApi.js";
-import { performGoogleSearch } from "../utils/googleSearchApi.js";
 import { getTracer } from "../utils/telemetry.js";
 import { searchYahooFree, scrapeArticleLocal } from "./freeSearch.js";
+// The same capability flag performWebSearchRaw itself branches on, imported
+// from the same module so the gate and the transport cannot disagree about
+// whether a web search is possible.
+import { SYNALUX_SEARCH_AVAILABLE } from "../utils/synaluxSearch.js";
 // ─── Hivemind Integration Helpers ────────────────────────────
 const SCHOLAR_PROJECT = "prism-scholar";
 const SCHOLAR_ROLE = "scholar";
@@ -192,9 +195,20 @@ export async function runWebScholar(overrideTopic, overrideProject) {
     const tracer = getTracer();
     const span = tracer.startSpan("background.web_scholar");
     try {
-        const useGoogle = !!(GOOGLE_SEARCH_API_KEY && GOOGLE_SEARCH_CX);
-        const useBraveFirecrawl = !useGoogle && !!(BRAVE_API_KEY && FIRECRAWL_API_KEY);
-        const useFreeFallback = !useGoogle && !useBraveFirecrawl;
+        // Discovery provider: ask whether a web search is POSSIBLE, not whether
+        // this machine happens to hold a key. performWebSearchRaw serves portal
+        // users from Synalux-side credentials and everyone else from their own
+        // BRAVE_API_KEY, so either one makes web discovery available.
+        //
+        // This used to read `BRAVE_API_KEY && FIRECRAWL_API_KEY`, which was wrong
+        // twice over: a portal-configured user holding no local key was demoted to
+        // the free academic path even though the portal would have served them,
+        // and a user who set only BRAVE_API_KEY was demoted for want of a Firecrawl
+        // key that nothing spends (scraping is always scrapeArticleLocal).
+        //
+        // Google Custom Search used to take priority over both; now removed
+        // because Google discontinues that API on 2027-01-01.
+        const useWebSearch = SYNALUX_SEARCH_AVAILABLE || !!BRAVE_API_KEY;
         const topic = overrideTopic || await selectTopic();
         const project = overrideProject || SCHOLAR_PROJECT;
         if (!topic) {
@@ -210,16 +224,29 @@ export async function runWebScholar(overrideTopic, overrideProject) {
         await hivemindRegister(topic);
         await hivemindHeartbeat(`Searching for: ${topic}`);
         let urls = [];
-        if (useGoogle) {
-            const googleResults = await performGoogleSearch(GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_CX, topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
-            urls = googleResults.map(r => r.url).filter(Boolean);
-        }
-        else if (useBraveFirecrawl) {
-            const braveResponse = await performWebSearchRaw(topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
-            const braveData = JSON.parse(braveResponse);
-            urls = (braveData.web?.results || []).map((r) => r.url).filter(Boolean);
+        // Set when web search was selected but the request itself failed. The run
+        // then continues on the free path and says so at the top of its report.
+        let webSearchFailure = null;
+        if (useWebSearch) {
+            try {
+                const braveResponse = await performWebSearchRaw(topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
+                const braveData = JSON.parse(braveResponse);
+                urls = (braveData.web?.results || []).map((r) => r.url).filter(Boolean);
+            }
+            catch (err) {
+                // The portal refuses web search for free plans (403) and for stale
+                // credentials (401), and a direct Brave key can be bad or rate-limited.
+                // Before the capability gate above, a signed-in free account never
+                // reached the portal from here — the gate looked only for a local key —
+                // so it took the free academic path below. Fall back to exactly that
+                // path. The transport (braveApi.ts portalFirst) has already applied the
+                // one permitted escape — the user's own key on a plan refusal — so
+                // Scholar adds no second attempt of its own.
+                webSearchFailure = err instanceof Error ? err.message : String(err);
+                console.error(`[WebScholar] Web search unavailable, continuing on free sources: ${webSearchFailure}`);
+            }
         }
-        else {
+        if (!useWebSearch || webSearchFailure !== null) {
             // Parallel Academic Discovery (PubMed + ERIC + Semantic Scholar)
             const academicCount = Math.ceil(PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN / 2);
             const academicResults = await Promise.all([
@@ -291,6 +318,12 @@ export async function runWebScholar(overrideTopic, overrideProject) {
             created_at: new Date().toISOString()
         });
         await hivemindBroadcast(topic, scrapedTexts.length);
+        // The ledger keeps the clean report; the caller (tool result, dashboard)
+        // is told when the sources were not the ones its credentials implied, so
+        // a paid account's portal outage is never a silent downgrade.
+        if (webSearchFailure !== null) {
+            return `Note: web search was unavailable (${webSearchFailure}); this report used the free academic sources.\n\n${summary}`;
+        }
         return summary;
     }
     catch (err) {

package/dist/skillManifestSync.js

@@ -256,6 +256,109 @@ async function listFiles(root, current = root) {
     }
     return files.sort();
 }
+/**
+ * Artifacts nobody authors. ADMISSION RULE for these lists — an entry must be
+ * (1) machine-generated as a side effect of USING or BROWSING the directory,
+ * (2) regenerated on demand at no cost, and (3) never shippable content. Any
+ * other untracked file is a local edit and must keep conflicting. Do not widen
+ * this into "ignore files we do not recognise".
+ */
+const DERIVED_ARTIFACT_DIRS = new Set(["__pycache__"]);
+/** Compared lowercased: Explorer writes both `Thumbs.db` and `thumbs.db`. */
+const DERIVED_ARTIFACT_FILES = new Set([".ds_store", "thumbs.db", "desktop.ini"]);
+const DERIVED_ARTIFACT_EXT = /\.py[co]$/;
+function isDerivedArtifactFile(name) {
+    const lower = name.toLocaleLowerCase("en-US");
+    return DERIVED_ARTIFACT_FILES.has(lower) || DERIVED_ARTIFACT_EXT.test(lower);
+}
+/**
+ * Remove regenerable junk from a marker-owned skill directory.
+ *
+ * `isPristineMarkedSkill` compares the FULL recursive file list against the
+ * marker's key list, so ONE untracked file classifies the skill as a conflict —
+ * frozen, silently skipped by every later sync. Two ways that happens without
+ * anyone editing anything:
+ *
+ *   - CPython writes `__pycache__/<mod>.cpython-XX.pyc` beside any module it
+ *     IMPORTS (exec'ing a script does not). Observed 2026-09-14:
+ *     dead-link-prevention froze after something imported check_links.py.
+ *   - Finder drops `.DS_Store` into any directory a user OPENS, and Explorer
+ *     drops `Thumbs.db`/`desktop.ini`. Reproduced 2026-09-14: browsing a
+ *     managed skill folder is enough to stop it updating. Windows is a
+ *     supported host, so both families belong here.
+ *
+ * PURGE, never ignore. Exempting these from the integrity walk would turn a
+ * noisy false conflict into a code-execution hole: CPython loads a cached .pyc
+ * in preference to its source whenever the pyc header's recorded source mtime
+ * and size match the .py, and both of those fields live in the attacker-written
+ * pyc. An ignored .pyc is arbitrary bytecode that executes while sync still
+ * reports the skill pristine and keeps updating it. Deleting restores integrity
+ * instead — the next import regenerates the cache from the .py the marker
+ * actually verifies, and any OTHER untracked file still conflicts as before.
+ *
+ * Touches nothing Prism does not own, nothing the manifest shipped, and never
+ * follows a symlink out of the skill root.
+ */
+async function purgeDerivedArtifacts(path) {
+    // Self-guarding, not caller-guarded. Three sites call this now and the
+    // symlink check is the only thing standing between a delete primitive and an
+    // arbitrary target, so it lives HERE — a fourth caller that forgets to lstat
+    // must not be able to reintroduce the escape.
+    let rootStat;
+    try {
+        rootStat = await lstat(path);
+    }
+    catch {
+        return;
+    }
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        return;
+    const marker = await readJson(join(path, MARKER));
+    if (!marker || marker.owner !== OWNER || !marker.files || typeof marker.files !== "object")
+        return;
+    const shipped = new Set(Object.keys(marker.files));
+    const shippedPaths = [...shipped];
+    // BEST EFFORT, always. This runs inside materializeNative's try block before
+    // anything is staged, so letting an EACCES escape would convert one skill's
+    // junk file into a `partial` sync that freezes EVERY other skill — trading a
+    // one-skill problem for the whole-root outage shape this file's header
+    // describes. A delete we cannot do just means the pristine check conflicts
+    // that one skill, exactly as it did before this function existed.
+    const discard = async (child, recursive) => {
+        try {
+            await rm(child, { recursive, force: true });
+        }
+        catch { /* leave it; it conflicts */ }
+    };
+    const walk = async (current) => {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const child = join(current, entry.name);
+            const rel = relative(path, child).split(sep).join("/");
+            // Never follow a symlink out of the skill root; listFiles still rejects it.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                const shippedUnder = shippedPaths.some((file) => file === rel || file.startsWith(`${rel}/`));
+                if (DERIVED_ARTIFACT_DIRS.has(entry.name) && !shippedUnder) {
+                    await discard(child, true);
+                    continue;
+                }
+                await walk(child);
+            }
+            else if (entry.isFile() && isDerivedArtifactFile(entry.name) && !shipped.has(rel)) {
+                await discard(child, false);
+            }
+        }
+    };
+    await walk(path);
+}
 async function isPristineMarkedSkill(path, generation) {
     const marker = await readJson(join(path, MARKER));
     if (!marker || marker.owner !== OWNER || (generation && marker.generation !== generation) ||
@@ -404,6 +507,12 @@ async function enforceNativeEntitlements(incomingNames, agentsSkillsDir) {
         const target = join(agentsSkillsDir, name);
         if (!(await exists(target)))
             continue;
+        // Same reason as the materialize paths: junk nobody wrote must not make a
+        // clean skill look hand-edited. Here the misread is quieter but permanent —
+        // the skill leaves discovery either way, but a false "locally modified"
+        // parks it in quarantine forever instead of deleting it, and nothing ever
+        // collects that directory.
+        await purgeDerivedArtifacts(target);
         if (await isPristineMarkedSkill(target)) {
             await rm(target, { recursive: true, force: true });
             continue;
@@ -604,6 +713,8 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
             if (!(await exists(target)))
                 continue;
             const stat = await lstat(target);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                await purgeDerivedArtifacts(target);
             const pristine = stat.isDirectory() && !stat.isSymbolicLink() && await isPristineManagedSkill(target, true);
             if (!pristine) {
                 // Preserve locally modified managed content, but quarantine it outside
@@ -659,6 +770,8 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
             }
             const stat = await lstat(target);
             const managedSkill = managedCandidates.has(skill.name);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                await purgeDerivedArtifacts(target);
             if (!stat.isDirectory() || stat.isSymbolicLink() || !(await isPristineManagedSkill(target, managedSkill))) {
                 conflicts.push(skill.name);
                 if (managedSkill)

package/dist/tools/definitions.js

@@ -261,7 +261,7 @@ export const RESEARCH_PAPER_ANALYSIS_TOOL = {
 export const SCHOLAR_RESEARCH_TOOL = {
     name: "scholar_research",
     description: "Triggers an autonomous research pipeline on a specific topic. " +
-        "Uses Brave/Firecrawl to discover scientific papers and journals, " +
+        "Discovers scientific papers and journals with web search (Synalux portal or your BRAVE_API_KEY) or free academic sources, " +
         "extracts their content, synthesizes a comprehensive markdown report, " +
         "and saves the result to the Mind Palace ledger. " +
         "Best for deep clinical research, literature reviews, and evidence-based practice updates.",

package/dist/tools/ledgerHandlers.js

@@ -496,13 +496,31 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
     const conflictSuffix = snapshot.conflicts.length > 0
         ? ` · ${snapshot.conflicts.length} conflict${snapshot.conflicts.length === 1 ? "" : "s"} — see warning`
         : "";
+    // Name the CONDITION, then hand over the procedure that reveals the cause.
+    // This used to read "local copy has no Prism ownership marker", which is one
+    // of several causes and not the common one. On 2026-09-14 dead-link-prevention
+    // tripped it with a marker that was present and digest-exact; the real cause
+    // was one extra untracked file. The sentence sent the operator to quarantine
+    // the directory and rerun `prism connect` (which rewrites host MCP config and
+    // wants every host closed) when the fix was deleting a regenerable cache dir.
+    // A wrong cause is worse than no cause: it buys a confident wrong repair.
+    //
+    // Deliberately a PROCEDURE, not an enumeration of causes. Listing all of them
+    // is both longer and weaker — a list still leaves the operator guessing, while
+    // the file-list-vs-marker diff names the offender outright. Length is not
+    // cosmetic here: this block renders in the HEAD, which capNativeStartupText
+    // keeps while cutting the tail, so every extra character evicts session
+    // context. An enumerated draft measured 858 chars — 21% of the whole 4,000
+    // quick budget, against 9% for the wrong-but-short original.
     const conflictWarning = snapshot.conflicts.length > 0
-        ? `\n> - ⚠️ **SKILLS NOT UPDATING (local copy has no Prism ownership marker):** ` +
+        ? `\n> - ⚠️ **SKILLS NOT UPDATING (on-disk copy differs from the managed one):** ` +
             `${formatBoundedSkillNames([...snapshot.conflicts].sort(), "blocked")}. ` +
-            `Each named skill is frozen at whatever version is on disk — updates are ` +
-            `withheld to protect local edits. To resume updates: move the skill's ` +
-            `directory out of the native skills folder and rerun \`prism connect\` ` +
-            `(or a session bootstrap) to reinstall the managed copy.`
+            `Each is frozen at whatever version is on disk — updates are withheld to ` +
+            `protect local edits. To see why, compare the directory's file list with ` +
+            `the \`files\` keys in its \`.prism-managed.json\`. An extra file you do ` +
+            `not need? Delete it; the next sync adopts the skill again. A local edit ` +
+            `you want to discard? Move the directory out of the native skills folder ` +
+            `and rerun \`prism connect\` (or a session bootstrap).`
         : "";
     // Durable, not per-run: a later sync reports "unchanged" while the roots stay
     // frozen from an earlier failed materialization. This line is the difference

package/dist/tools/skillRouting.js

@@ -313,8 +313,8 @@ async function fetchKeywordTable(expectVersion) {
  * string that happens to appear in material they pasted as evidence. Observed
  * 2026-08-31: a user asked "what's going on with skill loading?" and pasted a
  * startup log; the log listed installed skill names, and the literal token
- * `fusa-bss-billing` inside it satisfied that skill's own trigger
- * `\bfusa\b.{0,20}\b(billing|invoice)\b`. Two unrelated private skills loaded
+ * `acme-xyz-billing` inside it satisfied that skill's own trigger
+ * `\bacme\b.{0,20}\b(billing|invoice)\b`. Two unrelated private skills loaded
  * and were injected as binding rules for a debugging question — pasting a log
  * that NAMES a skill should never activate it.
  *
@@ -322,7 +322,7 @@ async function fetchKeywordTable(expectVersion) {
  *   1. Fenced code blocks — pasted output, by convention.
  *   2. Hyphenated skill-name tokens (`foo-bar-baz`). A bare skill name is
  *      metadata about the system, not a description of work. Removing only the
- *      NAME SPAN keeps its constituent words available: "fusa billing invoice"
+ *      NAME SPAN keeps its constituent words available: "acme billing invoice"
  *      typed by the user still matches, because that text is not a name token.
  *
  * Deliberately NOT length-capped: a long prompt is not evidence of pasting,
@@ -357,7 +357,7 @@ export function stripQuotedEvidenceForRouting(prompt, promptKeywords = {}) {
     // false positive being fixed. Using the actual routable names is exact.
     //
     // Deliberate consequence, not an oversight: a user who TYPES a skill's name
-    // ("update fusa-bss-billing's invoice rate") no longer trigger-routes that
+    // ("update acme-xyz-billing's invoice rate") no longer trigger-routes that
     // skill. That is acceptable because the agent reads the raw prompt and can
     // invoke a literally-named skill directly — trigger routing exists for
     // SYMPTOM text, where the name is absent. A pasted log naming skills must
@@ -382,7 +382,7 @@ export function stripQuotedEvidenceForRouting(prompt, promptKeywords = {}) {
         // the whole prompt — the sibling _applyPromptRouting swallows bad
         // patterns for the same reason (adversarial review, confirmed).
         // Only IDENTIFIER-SHAPED names are stripped: at least two segments joined
-        // by - or _ (fusa-bss-billing, training-results-gate). Round-3 review
+        // by - or _ (acme-xyz-billing, training-results-gate). Round-3 review
         // proved the unconditional version was self-defeating for skills whose
         // name is an ordinary word: stripping `sentry` from "check sentry for
         // recent errors" killed that skill's OWN trigger (\bsentry\b) — 100% of
@@ -395,7 +395,7 @@ export function stripQuotedEvidenceForRouting(prompt, promptKeywords = {}) {
         // name must not butt directly against a letter/digit, but MAY butt
         // against segment glue (-/_). Round 3's stricter (?<![\w-]) anchors
         // refused to strip the name out of longer compounds — a pasted
-        // `fusa-bss-billing-worker` container name survived intact, and because
+        // `acme-xyz-billing-worker` container name survived intact, and because
         // \b fires at every internal hyphen, the skill's own trigger still
         // matched inside it: the exact incident class this function exists to
         // kill. Alignment on segment edges strips those compounds while still

package/dist/utils/braveApi.js

@@ -29,6 +29,8 @@
  * The Brave Answers endpoint uses a separate BRAVE_ANSWERS_API_KEY via Bearer token.
  */
 import { BRAVE_API_KEY, BRAVE_ANSWERS_API_KEY } from "../config.js";
+import { debugLog } from "./logger.js";
+import { isPortalPlanRefusal } from "./portalError.js";
 import { SYNALUX_SEARCH_AVAILABLE, synaluxWebSearch, synaluxWebSearchRaw, synaluxLocalSearch, synaluxLocalSearchRaw, synaluxBraveAnswers, } from "./synaluxSearch.js";
 const BRAVE_API_KEY_MISSING_ERROR = "BRAVE_API_KEY is not configured";
 const BRAVE_ANSWERS_API_KEY_MISSING_ERROR = "BRAVE_ANSWERS_API_KEY is not configured";
@@ -38,14 +40,37 @@ function requireBraveApiKey() {
         throw new Error(BRAVE_API_KEY_MISSING_ERROR);
     return BRAVE_API_KEY;
 }
+/**
+ * Portal first. A configured Synalux account is a privacy boundary:
+ * provider credentials and query redaction stay portal-side, so an outage,
+ * a quota, or an expired login never turns into a direct provider call
+ * with the original query.
+ *
+ * The one exception is the portal's PLAN refusal (403 on a free plan). That
+ * account is not entitled to portal search at all, so a user who configured
+ * their own key gets it used — the same footing as a user who never signed
+ * in. Without an own key the refusal propagates unchanged.
+ */
+async function portalFirst(viaPortal, ownKey, viaOwnKey) {
+    try {
+        return await viaPortal();
+    }
+    catch (err) {
+        if (ownKey && isPortalPlanRefusal(err)) {
+            debugLog("[braveApi] portal refused this plan; using the locally configured key instead");
+            return viaOwnKey();
+        }
+        throw err;
+    }
+}
 // Brave Answers API call (AI Grounding/OpenAI-compatible)
 export async function performBraveAnswers(query, model = "brave") {
-    // A configured Synalux account is a privacy boundary: provider
-    // credentials and redaction stay portal-side. Never escape to a direct
-    // provider with the original query when that portal request fails.
     if (SYNALUX_SEARCH_AVAILABLE) {
-        return synaluxBraveAnswers(query, model);
+        return portalFirst(() => synaluxBraveAnswers(query, model), BRAVE_ANSWERS_API_KEY, () => braveAnswersDirect(query, model));
     }
+    return braveAnswersDirect(query, model);
+}
+async function braveAnswersDirect(query, model) {
     if (!BRAVE_ANSWERS_API_KEY) {
         throw new Error(BRAVE_ANSWERS_API_KEY_MISSING_ERROR);
     }
@@ -80,8 +105,12 @@ export async function performWebSearchRaw(query, count = 10, offset = 0) {
     if (SYNALUX_SEARCH_AVAILABLE) {
         if (offset !== 0)
             throw new Error(SYNALUX_OFFSET_UNSUPPORTED_ERROR);
-        return synaluxWebSearchRaw(query, count);
+        return portalFirst(() => synaluxWebSearchRaw(query, count), BRAVE_API_KEY, () => braveWebSearchRaw(query, count, offset));
     }
+    return braveWebSearchRaw(query, count, offset);
+}
+// Direct Brave web search on the locally configured key
+async function braveWebSearchRaw(query, count, offset) {
     const braveApiKey = requireBraveApiKey();
     const url = new URL("https://api.search.brave.com/res/v1/web/search");
     url.searchParams.set("q", query);
@@ -105,9 +134,13 @@ export async function performWebSearch(query, count = 10, offset = 0) {
     if (SYNALUX_SEARCH_AVAILABLE) {
         if (offset !== 0)
             throw new Error(SYNALUX_OFFSET_UNSUPPORTED_ERROR);
-        return synaluxWebSearch(query, count);
+        return portalFirst(() => synaluxWebSearch(query, count), BRAVE_API_KEY, () => braveWebSearch(query, count, offset));
     }
-    const textData = await performWebSearchRaw(query, count, offset);
+    return braveWebSearch(query, count, offset);
+}
+// Direct Brave web search, formatted
+async function braveWebSearch(query, count, offset) {
+    const textData = await braveWebSearchRaw(query, count, offset);
     const data = JSON.parse(textData);
     // Extract just web results
     const results = (data.web?.results || []).map((result) => ({
@@ -165,8 +198,12 @@ function chunkArray(arr, size) {
 // Raw local search API call with poi/details payload
 export async function performLocalSearchRaw(query, count = 5) {
     if (SYNALUX_SEARCH_AVAILABLE) {
-        return synaluxLocalSearchRaw(query, count);
+        return portalFirst(() => synaluxLocalSearchRaw(query, count), BRAVE_API_KEY, () => braveLocalSearchRaw(query, count));
     }
+    return braveLocalSearchRaw(query, count);
+}
+// Direct Brave local search on the locally configured key
+async function braveLocalSearchRaw(query, count) {
     const braveApiKey = requireBraveApiKey();
     // Initial search to get location IDs
     const webUrl = new URL("https://api.search.brave.com/res/v1/web/search");
@@ -190,7 +227,8 @@ export async function performLocalSearchRaw(query, count = 5) {
         ?.filter((r) => r.id != null)
         .map((r) => r.id) || [];
     if (locationIds.length === 0) {
-        const fallback = await performWebSearch(query, count);
+        // Already on the direct path: stay on it rather than re-asking the portal.
+        const fallback = await braveWebSearch(query, count, 0);
         return JSON.stringify({
             source: "web_fallback",
             query,
@@ -223,9 +261,13 @@ export async function performLocalSearchRaw(query, count = 5) {
 // Local search API call with poi details
 export async function performLocalSearch(query, count = 5) {
     if (SYNALUX_SEARCH_AVAILABLE) {
-        return synaluxLocalSearch(query, count);
+        return portalFirst(() => synaluxLocalSearch(query, count), BRAVE_API_KEY, () => braveLocalSearch(query, count));
     }
-    const rawData = await performLocalSearchRaw(query, count);
+    return braveLocalSearch(query, count);
+}
+// Direct Brave local search, formatted
+async function braveLocalSearch(query, count) {
+    const rawData = await braveLocalSearchRaw(query, count);
     const parsed = JSON.parse(rawData);
     if (parsed.source === "web_fallback") {
         return parsed.formattedText || "No local results found";

package/dist/utils/portalError.js

@@ -0,0 +1,41 @@
+/**
+ * Portal HTTP errors carry their status and body so a caller can tell a
+ * PLAN refusal — the account is signed in, but its plan does not include
+ * the feature — from an outage, a quota, or an expired login. Only the plan
+ * refusal may be answered with the user's own provider key (braveApi.ts);
+ * everything else stays inside the portal's privacy boundary.
+ */
+export class PortalHttpError extends Error {
+    portalPath;
+    portalStatus;
+    portalBody;
+    constructor(path, status, body) {
+        super(`[synaluxSearch] ${path} HTTP ${status}: ${body}`);
+        this.name = "PortalHttpError";
+        this.portalPath = path;
+        this.portalStatus = status;
+        this.portalBody = body;
+    }
+}
+/**
+ * True when the portal refused because of the account's plan: the
+ * `auth.plan === 'free'` gate on the prism search routes answers 403 with
+ * `{ error: "... requires Standard plan or higher.", upgrade_url: "/pricing" }`.
+ * Either signal — the word "plan" in the body, or a structured
+ * `upgrade_url` — is accepted, so a reworded message does not silently take
+ * a free user's own key away again. A 403 with neither is not a plan
+ * refusal, whatever else it may be.
+ */
+export function isPortalPlanRefusal(err) {
+    if (!(err instanceof PortalHttpError) || err.portalStatus !== 403)
+        return false;
+    if (/\bplan\b/i.test(err.portalBody))
+        return true;
+    try {
+        const body = JSON.parse(err.portalBody);
+        return typeof body?.upgrade_url === "string";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/synaluxSearch.js

@@ -17,6 +17,7 @@
  * SYNALUX_SEARCH_AVAILABLE before calling.
  */
 import { debugLog } from "./logger.js";
+import { PortalHttpError } from "./portalError.js";
 import { getSynaluxJwt, invalidateSynaluxJwt } from "./synaluxJwt.js";
 import { PRISM_SYNALUX_BASE_URL, SYNALUX_CONFIGURED, } from "../config.js";
 // ─── Public availability flag ────────────────────────────────
@@ -59,7 +60,9 @@ async function portalPost(path, body, timeoutMs = 15_000) {
     }
     if (!res.ok) {
         const text = await res.text().catch(() => "(no body)");
-        throw new Error(`[synaluxSearch] ${path} HTTP ${res.status}: ${text}`);
+        // Same message as before; the typed error lets braveApi.ts recognise a
+        // plan refusal without parsing the message.
+        throw new PortalHttpError(path, res.status, text);
     }
     return (await res.json());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.18.1",
+  "version": "20.19.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",

package/dist/utils/googleSearchApi.js

@@ -1,42 +0,0 @@
-import { debugLog } from "./logger.js";
-/**
- * Google Custom Search API Utility
- * ===============================
- *
- * Performs a web search using the Google Custom Search JSON API.
- * Requires: API Key and Search Engine ID (CX).
- *
- * @param apiKey - Google Search API Key
- * @param cx - Search Engine ID (CX)
- * @param query - The search query
- * @param count - Number of results to return (max 10)
- * @returns Array of result objects { title, url, snippet }
- */
-export async function performGoogleSearch(apiKey, cx, query, count = 5) {
-    try {
-        const safeCount = Math.min(Math.max(1, count), 10);
-        const url = new URL("https://customsearch.googleapis.com/customsearch/v1");
-        url.searchParams.append("key", apiKey);
-        url.searchParams.append("cx", cx);
-        url.searchParams.append("q", query);
-        url.searchParams.append("num", safeCount.toString());
-        const response = await fetch(url.toString(), {
-            signal: AbortSignal.timeout(15_000),
-        });
-        if (!response.ok) {
-            const error = await response.json();
-            throw new Error(`Google Search API failed: ${JSON.stringify(error)}`);
-        }
-        const data = await response.json();
-        const items = data.items || [];
-        return items.map((item) => ({
-            title: item.title,
-            url: item.link,
-            snippet: item.snippet,
-        }));
-    }
-    catch (err) {
-        debugLog(`[GoogleSearch] Error: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-}