prism-mcp-server 20.3.1 → 20.4.0

package/README.md

@@ -61,6 +61,69 @@ features.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.4.0
+
+### An Explicitly Named Cloud Backend Fails Loud
+
+Setting `PRISM_STORAGE=synalux` or `=supabase` with incomplete credentials used
+to downgrade silently to local SQLite. The switch was logged to stderr, which
+MCP hosts discard, so nothing surfaced it: sessions kept serving stale local
+context while the cloud held newer history, and `context_source` read `local`
+rather than any kind of warning. A session could run that way for weeks.
+
+Naming a backend outright is a strong statement of intent, so it now throws —
+naming the missing variables and the `PRISM_STORAGE=local` opt-out — instead of
+quietly splitting your session history. `auto` is unchanged: it keeps its
+documented `synalux > supabase > local` degradation, pinned by a test.
+
+**Upgrade note:** if you explicitly set `PRISM_STORAGE=synalux|supabase` and
+your credentials are incomplete, startup now fails with a named error instead
+of silently using local data. That error is the fix — set the missing variable,
+or choose `PRISM_STORAGE=local` deliberately. Default (`auto`) configs are
+unaffected.
+
+The throw is deliberately not treated as a recoverable startup fault: that path
+exists for transient errors (rate limits, 5xx, DNS), which may degrade behind a
+visible notice. A missing credential is a configuration fault and must not be
+papered over.
+
+Also: the skill block is now budgeted by default rather than only on request,
+so a large skill payload cannot crowd out briefing and history.
+
+## What's New in v20.3.2
+
+### Web Scholar: SSRF Hardening
+
+Security release. Web Scholar scrapes article URLs that come from
+search-engine output, so the target is attacker-influenceable through SEO
+poisoning — and because what it scrapes is written into the memory corpus and
+passed to the configured LLM, a redirection to a local address meant reading an
+internal service *and* sending the result onward.
+
+The host guard matched string prefixes instead of parsing the address, and six
+spellings of a local address got through: `[::1]` (`URL.hostname` keeps the
+brackets), `127.0.0.2` (only `.1` was enumerated, not all of `127.0.0.0/8`),
+`0.0.0.0`, `[::ffff:127.0.0.1]`, `localhost.` (a trailing dot defeated every
+suffix check at once), and `[64:ff9b::7f00:1]` (NAT64 embeds IPv4 in its low
+bits). Host classification now parses addresses and also covers CGNAT,
+benchmarking, multicast, reserved, and IPv6 unique-local and link-local ranges.
+
+DNS rebinding is closed too. Every check read the URL string, so a hostname the
+attacker controls passed all of them and could still resolve to `127.0.0.1`.
+Targets are now resolved first, every returned address is validated, and the
+connection is pinned to those addresses so the name is never resolved a second
+time — which also shuts the window between the check and the connect.
+
+Scrape failures no longer vanish into a bare `catch {}`, a run is bounded by
+`PRISM_SCHOLAR_SCRAPE_BUDGET_MS` (default 60s) instead of stalling on a raised
+article count, and responses are capped at 8 MiB.
+
+This is reachable only when scholar actually runs — `scholar_research`, or the
+background loop under `PRISM_SCHOLAR_ENABLED=true` — and when the attacker also
+controls DNS or a search result. Upgrade if you use Web Scholar.
+
+---
+
 ## What's New in v20.3.1
 
 ### Prism Browser Reports Real Failures

package/dist/config.js

@@ -202,6 +202,10 @@ if (PRISM_SCHOLAR_ENABLED && !FIRECRAWL_API_KEY) {
 export const PRISM_SCHOLAR_INTERVAL_MS = parseInt(process.env.PRISM_SCHOLAR_INTERVAL_MS || "0", 10 // Default manual-only
 );
 export const PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN = parseInt(process.env.PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN || "3", 10);
+// Wall-clock ceiling for a run's scrape loop. Scrapes are sequential with a
+// 15s per-fetch timeout, so without this a raised article count turns into a
+// multi-minute stall.
+export const PRISM_SCHOLAR_SCRAPE_BUDGET_MS = parseInt(process.env.PRISM_SCHOLAR_SCRAPE_BUDGET_MS || "60000", 10);
 export const PRISM_SCHOLAR_TOPICS = (process.env.PRISM_SCHOLAR_TOPICS || "ai,agents")
     .split(",")
     .map(t => t.trim());

package/dist/scholar/freeSearch.js

@@ -2,6 +2,12 @@ import * as cheerio from 'cheerio';
 import { JSDOM } from 'jsdom';
 import { Readability } from '@mozilla/readability';
 import TurndownService from 'turndown';
+import { lookup as dnsLookupCb } from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import { promisify } from 'node:util';
+const dnsLookup = promisify(dnsLookupCb);
 /**
  * Searches Yahoo Web Search and parses the HTML results using Cheerio.
  * Yahoo provides a reliable HTML fallback that does not block basic automated browser requests.
@@ -42,47 +48,244 @@ export async function searchYahooFree(query, limit = 5) {
     });
     return results;
 }
+function classifyIPv4(octets) {
+    const [a, b] = octets;
+    if (a === 127)
+        return 'loopback'; // 127.0.0.0/8 — not just 127.0.0.1
+    if (a === 0)
+        return 'loopback'; // 0.0.0.0/8 routes to the local host
+    if (a === 10)
+        return 'private'; // RFC1918
+    if (a === 172 && b >= 16 && b <= 31)
+        return 'private';
+    if (a === 192 && b === 168)
+        return 'private';
+    if (a === 169 && b === 254)
+        return 'private'; // link-local + cloud metadata
+    if (a === 100 && b >= 64 && b <= 127)
+        return 'private'; // CGNAT
+    if (a === 192 && b === 0)
+        return 'private'; // IETF protocol assignments
+    if (a === 198 && (b === 18 || b === 19))
+        return 'private'; // benchmarking
+    if (a >= 224)
+        return 'private'; // multicast + reserved
+    return 'public';
+}
+function parseIPv4(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const value = Number(part);
+        if (value > 255)
+            return null;
+        octets.push(value);
+    }
+    return octets;
+}
 /**
- * Fetches an article's HTML, extracts clean content via Readability,
- * and converts it to Markdown using Turndown.
+ * Classify a URL's host.
+ *
+ * Exported so the bypass table can be asserted directly. String-prefix checks
+ * are not sufficient here: `URL.hostname` keeps the brackets on IPv6 literals,
+ * 127.0.0.0/8 is far wider than 127.0.0.1, and 0.0.0.0 and IPv4-mapped IPv6
+ * both reach the local host.
  */
-export async function scrapeArticleLocal(url) {
-    // SSRF protection: reject private/internal URLs.
-    // Set PRISM_DEV_MODE=1 to allow loopback/private hosts during local dev
-    // (testing against a local docs server, internal wiki, etc.). The flag
-    // is intentionally OFF in production deploys.
-    const devMode = process.env.PRISM_DEV_MODE === '1' || process.env.NODE_ENV === 'development';
+export function classifyScrapeHost(rawHost) {
+    // URL.hostname returns IPv6 literals bracketed — strip the brackets. Node
+    // keeps a trailing '.' on named hosts (localhost. still resolves to
+    // 127.0.0.1), and that dot otherwise defeats every suffix check below.
+    const host = rawHost.toLowerCase()
+        .replace(/^\[|\]$/g, '')
+        .replace(/\.+$/, '');
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return 'loopback';
+    if (host.endsWith('.internal') || host.endsWith('.local'))
+        return 'private';
+    const ipv4 = parseIPv4(host);
+    if (ipv4)
+        return classifyIPv4(ipv4);
+    if (host.includes(':')) {
+        if (host === '::1')
+            return 'loopback';
+        if (host === '::')
+            return 'loopback';
+        // Prefixes that carry an IPv4 address in their low 32 bits. Node
+        // rewrites ::ffff:127.0.0.1 to ::ffff:7f00:1, so both the dotted and
+        // hex-pair spellings have to decode.
+        const embedding = /^(?:::ffff|64:ff9b(?::1)?::?)[:]?(.+)$/.exec(host);
+        if (embedding) {
+            const suffix = embedding[1];
+            const dotted = parseIPv4(suffix);
+            if (dotted)
+                return classifyIPv4(dotted);
+            const hexPair = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(suffix);
+            if (hexPair) {
+                const high = parseInt(hexPair[1], 16);
+                const low = parseInt(hexPair[2], 16);
+                return classifyIPv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+            }
+            // Reserved translation prefix with an undecodable tail — not public.
+            return 'private';
+        }
+        if (/^64:ff9b:/.test(host))
+            return 'private'; // NAT64 (RFC 6052/8215)
+        if (/^f[cd][0-9a-f]{2}:/.test(host))
+            return 'private'; // fc00::/7 unique-local
+        if (/^fe[89ab][0-9a-f]:/.test(host))
+            return 'private'; // fe80::/10 link-local
+        return 'public';
+    }
+    return 'public';
+}
+/**
+ * Reject scrape targets that point at the local host or an internal network.
+ *
+ * The URL reaching here comes from search-engine output, so it is
+ * attacker-influenceable via SEO poisoning. A successful fetch would be
+ * persisted into the memory corpus, so this fails closed.
+ */
+export function assertSafeScrapeTarget(url, devMode) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('Invalid URL: could not be parsed');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error(`Invalid URL: protocol ${parsed.protocol} is not allowed`);
+    }
+    const hostClass = classifyScrapeHost(parsed.hostname);
+    if (hostClass === 'private') {
+        // Never allowed, even in dev mode: on a shared LAN these can reach
+        // other machines, and 169.254.169.254 is cloud metadata.
+        throw new Error('Invalid URL: private network URLs not allowed');
+    }
+    if (hostClass === 'loopback' && !devMode) {
+        throw new Error('Invalid URL: loopback URLs not allowed in production (set PRISM_DEV_MODE=1 to allow)');
+    }
+}
+/** Max article HTML accepted, so a hostile endpoint cannot stream us to death. */
+const MAX_ARTICLE_BYTES = 8 * 1024 * 1024;
+/**
+ * Resolve a hostname and validate every address it answers with.
+ *
+ * The string checks above only see the hostname, so a name the attacker
+ * controls can pass them and still resolve to 127.0.0.1 (DNS rebinding).
+ * Returns the address to connect to, which the caller pins so the name is
+ * never resolved a second time.
+ */
+export async function resolveAndValidateHost(hostname, devMode) {
+    const bracketless = hostname.replace(/^\[|\]$/g, '');
+    // A literal address needs no lookup; assertSafeScrapeTarget already ruled on it.
+    if (net.isIP(bracketless) !== 0) {
+        return [{ address: bracketless, family: net.isIP(bracketless) }];
+    }
+    let resolved;
     try {
-        const parsed = new URL(url);
-        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
-            throw new Error('Invalid protocol');
-        const host = parsed.hostname.toLowerCase();
-        const isLoopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
-        const isPrivate = host.startsWith('10.') || host.startsWith('192.168.') || host.startsWith('169.254.') ||
-            /^172\.(1[6-9]|2\d|3[01])\./.test(host) || host.endsWith('.internal') || host.endsWith('.local');
-        if (isLoopback && !devMode) {
-            throw new Error('Loopback URLs not allowed in production (set PRISM_DEV_MODE=1 to allow)');
+        resolved = await dnsLookup(hostname, { all: true, verbatim: true });
+    }
+    catch (err) {
+        throw new Error(`Invalid URL: could not resolve ${hostname}`);
+    }
+    if (resolved.length === 0) {
+        throw new Error(`Invalid URL: ${hostname} resolved to no addresses`);
+    }
+    // Reject if ANY answer is non-public. A name that resolves to both a
+    // public and a private address is the rebinding shape itself, so picking
+    // the "good" one would just make the attack racy instead of blocked.
+    for (const entry of resolved) {
+        const hostClass = classifyScrapeHost(entry.address);
+        if (hostClass === 'private') {
+            throw new Error(`Invalid URL: ${hostname} resolves to a private address (${entry.address})`);
         }
-        if (isPrivate) {
-            // Private RFC1918 ranges are never allowed — even in dev mode they
-            // can cross into other tenants' machines on a shared LAN.
-            throw new Error('Private network URLs not allowed');
+        if (hostClass === 'loopback' && !devMode) {
+            throw new Error(`Invalid URL: ${hostname} resolves to a loopback address (${entry.address})`);
         }
     }
-    catch (e) {
-        throw new Error(`Invalid URL: ${e instanceof Error ? e.message : 'unknown'}`);
-    }
-    const response = await fetch(url, {
-        headers: {
-            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
-        },
-        redirect: 'error',
-        signal: AbortSignal.timeout(15_000),
+    // Every answer is validated, so returning all of them keeps Node's
+    // dual-stack fallback working. Pinning only the first would fail whenever
+    // a host's leading AAAA is unreachable, which plain fetch handles.
+    return resolved;
+}
+/**
+ * GET an article over a connection pinned to a pre-validated address.
+ *
+ * Node's fetch would resolve the name again inside the request, which
+ * reopens the rebinding window between our check and the connection
+ * (TOCTOU). Supplying `lookup` guarantees the socket goes to the address we
+ * validated, while the URL still supplies the Host header and TLS SNI.
+ */
+function fetchPinned(url, addresses) {
+    return new Promise((resolve, reject) => {
+        const transport = url.protocol === 'https:' ? https : http;
+        const req = transport.request(url, {
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            },
+            // Node calls this in two shapes: with { all: true } it wants an
+            // array of { address, family } (autoSelectFamily, the default
+            // since Node 20), otherwise the (err, address, family) form.
+            // Answering the wrong one yields "Invalid IP address: undefined".
+            lookup: (_hostname, options, callback) => {
+                if (options && options.all) {
+                    callback(null, addresses);
+                }
+                else {
+                    callback(null, addresses[0].address, addresses[0].family);
+                }
+            },
+        }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                // Matches the previous redirect: 'error' behaviour — a
+                // redirect is a second target that was never validated.
+                res.destroy();
+                reject(new Error(`Failed to fetch article HTML: refusing redirect (${status})`));
+                return;
+            }
+            if (status < 200 || status >= 300) {
+                res.destroy();
+                reject(new Error(`Failed to fetch article HTML: ${status} ${res.statusMessage ?? ''}`.trim()));
+                return;
+            }
+            let size = 0;
+            const chunks = [];
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_ARTICLE_BYTES) {
+                    res.destroy();
+                    reject(new Error(`Failed to fetch article HTML: exceeded ${MAX_ARTICLE_BYTES} bytes`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            res.on('error', reject);
+        });
+        req.setTimeout(15_000, () => {
+            req.destroy(new Error('Failed to fetch article HTML: timed out after 15000ms'));
+        });
+        req.on('error', reject);
+        req.end();
     });
-    if (!response.ok) {
-        throw new Error(`Failed to fetch article HTML: ${response.statusText}`);
-    }
-    const html = await response.text();
+}
+export async function scrapeArticleLocal(url) {
+    // SSRF protection: reject private/internal URLs.
+    // Set PRISM_DEV_MODE=1 to allow loopback hosts during local dev (testing
+    // against a local docs server, internal wiki, etc.). The flag is
+    // intentionally OFF in production deploys.
+    const devMode = process.env.PRISM_DEV_MODE === '1' || process.env.NODE_ENV === 'development';
+    assertSafeScrapeTarget(url, devMode);
+    // Then resolve, validate every answer, and pin the connection to it.
+    const parsed = new URL(url);
+    const addresses = await resolveAndValidateHost(parsed.hostname, devMode);
+    const html = await fetchPinned(parsed, addresses);
     // Create a virtual DOM for Readability to traverse
     const doc = new JSDOM(html, { url });
     // Extract the article content like Firefox Reader View

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, } from "../config.js";
+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 { getStorage } from "../storage/index.js";
 import { debugLog } from "../utils/logger.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
@@ -238,15 +238,41 @@ export async function runWebScholar(overrideTopic, overrideProject) {
             return `No articles found for "${topic}"`;
         await hivemindHeartbeat(`Scraping ${urls.length} articles on: ${topic}`);
         const scrapedTexts = [];
+        const scrapeFailures = [];
+        // Scrapes run sequentially with a 15s per-fetch timeout, so N URLs cost
+        // up to N * 15s. PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN is env-overridable,
+        // so bound the whole loop rather than trusting the item count.
+        // A non-finite budget (bad env value, or a test that stubs the config
+        // module wholesale) must not silently disable scraping or the budget.
+        const budgetMs = Number.isFinite(PRISM_SCHOLAR_SCRAPE_BUDGET_MS) && PRISM_SCHOLAR_SCRAPE_BUDGET_MS > 0
+            ? PRISM_SCHOLAR_SCRAPE_BUDGET_MS
+            : 60_000;
+        const scrapeDeadline = Date.now() + budgetMs;
         for (const url of urls) {
+            if (Date.now() >= scrapeDeadline) {
+                scrapeFailures.push(`${url} — skipped: ${budgetMs}ms scrape budget exhausted`);
+                continue;
+            }
             try {
                 const article = await scrapeArticleLocal(url);
                 scrapedTexts.push(`Source: ${url}\nTitle: ${article.title}\n\n${article.content.slice(0, 15_000)}`);
             }
-            catch { }
+            catch (err) {
+                // A swallowed failure makes an empty run look identical to a good one.
+                const reason = err instanceof Error ? err.message : String(err);
+                scrapeFailures.push(`${url} — ${reason}`);
+                console.error(`[Scholar] scrape failed: ${url} — ${reason}`);
+            }
+        }
+        if (scrapedTexts.length === 0) {
+            const detail = scrapeFailures.length
+                ? `\n${scrapeFailures.join('\n')}`
+                : ' (no URLs attempted)';
+            return `All ${urls.length} scrape(s) failed for "${topic}":${detail}`;
+        }
+        if (scrapeFailures.length > 0) {
+            console.error(`[Scholar] ${scrapeFailures.length}/${urls.length} scrapes failed for "${topic}"`);
         }
-        if (scrapedTexts.length === 0)
-            return "All scrapes failed";
         await hivemindHeartbeat(`Synthesizing ${scrapedTexts.length} articles on: ${topic}`);
         const prompt = `You are an AI research assistant. Topic: "${topic}". Read these articles and write a comprehensive report.\n\n${scrapedTexts.join("\n---\n")}`;
         const llm = getLLMProvider();

package/dist/storage/index.js

@@ -92,13 +92,34 @@ export async function getStorage() {
         debugLog(`[Prism Storage] Auto-resolved: ${requested}`);
     }
     // ─── Validate explicit backend has credentials ────────────────
+    // An explicitly requested cloud backend with missing credentials must fail
+    // loud. Silently serving local SQLite splits session history: the caller
+    // keeps working against a stale local copy while believing it is on the
+    // cloud, and console.error goes to stderr, which MCP hosts discard. "auto"
+    // already refuses to fall back for this exact reason (see above); naming a
+    // backend outright is a stronger statement of intent, so it must not be
+    // weaker about protecting history.
+    //
+    // Observed in the field: a base URL present without its API key (a
+    // `prism connect` run from a shell that never exported the key strips it)
+    // downgraded every subsequent session to local storage for weeks. The local
+    // copy kept serving months-old context while the cloud held current history,
+    // and nothing in-band surfaced the downgrade.
+    //
+    // This throw is deliberately NOT matched by isRecoverableStartupStorageError
+    // (startupRecovery.ts): a missing credential is a configuration fault, not a
+    // transient one, so startup must not paper over it with last-good context.
     if (requested === "synalux" && !(await ensureSynaluxCredentials())) {
-        console.error("[Prism Storage] Synalux backend requested but PRISM_SYNALUX_BASE_URL/PRISM_SYNALUX_API_KEY are missing or invalid. Falling back to local storage.");
-        requested = "local";
+        throw new Error("[Prism Storage] PRISM_STORAGE=synalux but Synalux credentials are missing or invalid " +
+            "(need PRISM_SYNALUX_BASE_URL and PRISM_SYNALUX_API_KEY). " +
+            "Refusing to fall back to local storage because that silently splits session history. " +
+            "Set PRISM_STORAGE=local explicitly if local-only storage is intended.");
     }
     if (requested === "supabase" && !(await ensureSupabaseCredentials())) {
-        console.error("[Prism Storage] Supabase backend requested but SUPABASE_URL/SUPABASE_KEY are missing or invalid. Falling back to local storage.");
-        requested = "local";
+        throw new Error("[Prism Storage] PRISM_STORAGE=supabase but Supabase credentials are missing or invalid " +
+            "(need SUPABASE_URL and SUPABASE_KEY). " +
+            "Refusing to fall back to local storage because that silently splits session history. " +
+            "Set PRISM_STORAGE=local explicitly if local-only storage is intended.");
     }
     // ─── Initialize ───────────────────────────────────────────────
     activeStorageBackend = requested;

package/dist/tools/ledgerHandlers.js

@@ -1344,8 +1344,12 @@ export async function sessionLoadContextHandler(args, options = {}) {
     // exists to deliver. The protected floor may still exceed this tranche
     // (always inlined); the reserved 40% keeps history alive whenever the
     // caller's budget covers the floor at all.
-    const skillBudgetChars = maxTokens && maxTokens > 0 ? Math.floor(maxTokens * 3.5 * 0.6) : Number.POSITIVE_INFINITY;
-    const { assembleSkillBlock } = await import("../utils/skillBudget.js");
+    // Armed by DEFAULT, not only when the caller passes max_tokens — see
+    // resolveSkillBudgetChars for why an unbudgeted default cost the agent its
+    // entire response on 2026-08-01. `level` scales the tranche so `quick`
+    // actually means quick.
+    const { assembleSkillBlock, resolveSkillBudgetChars } = await import("../utils/skillBudget.js");
+    const skillBudgetChars = resolveSkillBudgetChars(maxTokens, level);
     const budgeted = assembleSkillBlock(skillEntries, skillBudgetChars);
     skillBlock = budgeted.block;
     loadedSkills.push(...budgeted.inlined);

package/dist/utils/skillBudget.js

@@ -27,6 +27,51 @@ function render(e) {
     const label = e.category === "role" ? "ROLE SKILL" : "SKILL";
     return `\n\n[📜 ${label}: ${e.name}]\n${e.content.trim()}`;
 }
+/**
+ * Skill tranche used when the caller sets no `max_tokens`.
+ *
+ * Sized against the ~25k-token host tool-result cap: at the 3.5 chars/token
+ * heuristic that is ~87k chars for the WHOLE response, so the skill block has
+ * to leave room for briefing, handoff, and history.
+ *
+ * These are ADDITIVE on top of the protected floor, not a total. Protected
+ * skills inline even when the budget is already blown (assembleSkillBlock), and
+ * the repo-measured v26 floor is ~39k chars on its own — so the ceiling here is
+ * roughly 87k - 39k - memory. `standard` matches the 8,400-char tranche the
+ * existing v26 shape test already treats as the standard budget (60% of 14k
+ * tokens); `deep` doubles it and still leaves headroom for deep history.
+ *
+ * `quick` is deliberately near-nothing — it is the setting a caller picks to
+ * minimize context, and before this it still inlined the full skill payload,
+ * because `level` gated only the memory portion, which is the small part.
+ *
+ * Every value is finite and > 0 on purpose: assembleSkillBlock treats ≤ 0 and
+ * non-finite as "unbudgeted", so a zero here would silently restore the very
+ * bug this table exists to fix.
+ */
+export const DEFAULT_SKILL_BUDGET_CHARS = {
+    quick: 2_000,
+    standard: 8_400,
+    deep: 16_000,
+};
+/**
+ * Resolve the skill-block budget for one call.
+ *
+ * 2026-08-01: this previously evaluated to POSITIVE_INFINITY whenever
+ * `max_tokens` was absent — which is the documented default and therefore the
+ * common call shape. Routing v25 (76 -> 95 skills, 19 moved to auto-load) then
+ * pushed the unbudgeted block to 91,578 chars, past the host cap, and the host
+ * diverted the ENTIRE response to a file: the agent received no context at all.
+ * The budget must be armed by default, not only when a caller opts in.
+ */
+export function resolveSkillBudgetChars(maxTokens, level) {
+    // 60% of the response allowance: skills must not saturate it, or the
+    // briefing and history this tool exists to deliver get truncated away.
+    if (typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0) {
+        return Math.max(1, Math.floor(maxTokens * 3.5 * 0.6));
+    }
+    return DEFAULT_SKILL_BUDGET_CHARS[level] ?? DEFAULT_SKILL_BUDGET_CHARS.standard;
+}
 /**
  * Assemble the skill block within `budgetChars`. `budgetChars` ≤ 0 or
  * non-finite means unbudgeted (legacy behavior: inline everything).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.3.1",
+  "version": "20.4.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local or subscription-gated Synalux storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",