prism-mcp-server 20.20.0 → 20.21.0

package/README.md

@@ -32,8 +32,11 @@ A paid subscription adds cloud sync, higher model tiers, and team features throu
   undercounts inline — a number you can check, not marketing.
 - **Route-output enforcement** — route mode returns only well-formed calls to
   tools the host actually advertised. Standard and higher plans can add
-  authenticated deterministic correction; `route_guard: "local"` keeps the
-  prompt and draft entirely on-device.
+  authenticated deterministic correction; `route_guard: "local"` disables that
+  correction only. `cloud_fallback: false` forbids cloud inference fallback and
+  `verify: false` (with no `evidence`) disables the grounding verifier. With all
+  three off, no request carries your prompt, draft or evidence; the per-call
+  entitlement check and telemetry still contact the portal and carry neither.
 - **One setup for every agent** — `prism connect` configures Claude Code,
   Claude Desktop, Cursor, Gemini CLI, and Codex while preserving unrelated
   settings.
@@ -1034,8 +1037,10 @@ The free tier runs entirely on your machine. Paid tiers add cloud sync through t
 redaction (SSNs, dates of birth, medical record numbers, phone numbers, emails,
 and clinical identifiers are stripped before storage). Cloud inference and
 route correction send the request over TLS for processing and do not store it
-as Prism memory; use `route_guard: "local"` or the **local tier** for a full
-air-gap. **Enterprise** includes a HIPAA Business Associate Agreement.
+as Prism memory. The **local tier** (no Synalux key) is the air-gap;
+`route_guard: "local"` only skips the route correction, and `cloud_fallback`
+and `verify` govern the other two channels. **Enterprise** includes a HIPAA
+Business Associate Agreement.
 
 ---
 
@@ -1050,8 +1055,12 @@ before it reaches the host. Malformed or unadvertised calls become `NO_TOOL`.
 With `route_guard: "auto"` (the default), Standard and higher plans also send
 a well-formed draft for one of Prism's seven trained tools—or an unadvertised
 draft that may need correction—to Synalux for authenticated deterministic
-correction. Advertised custom host tools remain local. Set
-`route_guard: "local"` for a fully on-device route path.
+correction. Advertised custom host tools remain local. `route_guard: "local"`
+disables that correction only: cloud inference fallback is governed by
+`cloud_fallback`, and the grounding verifier is a separate channel with its
+own switch (`verify`, on by default when `evidence` is given). With all three
+off, no request carries your prompt, draft or evidence; the entitlement check
+and telemetry still contact the portal and carry neither.
 
 | Model | Ollama tag | Size | Vision | Routing accuracy¹ | Role | Automatic routing tier |
 |---|---|---|---|---|---|---|
@@ -1152,12 +1161,19 @@ check, the local 9B passed 2/3 tasks; the local 27B and Gemini 3.6 Flash each
 passed 3/3. This is a self-published regression signal, not an independent
 leaderboard or a claim of broad model equivalence.
 
-### Cloud Escalation (`cloud_fallback: true`)
+### Cloud Escalation (`cloud_fallback`)
 
 Prism always tries an eligible local model first. If the quality gate detects
-an empty, truncated, think-only, or looping response, paid tiers can retry the
-request through Gemini 3.6 Flash. Free-tier routing stays local and reports the
-quality-gate outcome without making a cloud call.
+an empty, truncated, think-only, or looping response, or the safety screen
+finds the request uncertain or reserved, a paid plan escalates the request
+through Gemini 3.6 Flash. Free-tier routing stays local and reports the
+outcome without making a cloud call.
+
+The flag follows the plan. Leave it unset and your plan decides: paid plans
+escalate, free plans never do. Pass `false` to forbid cloud inference fallback
+for a call, which the clinical delegation rules do for drafting; pass `true`
+to ask for it, which still requires a plan with cloud. A request that carries
+an image is never escalated; screenshots stay on this device.
 
 ---
 
@@ -1361,8 +1377,8 @@ prism_infer({
 })
 // → "n = countActiveUsers(data)"          (local 9b, $0)
 
-// A turn the on-device screen finds uncertain when read alone is not served
-// locally: it goes to Synalux cloud on a paid plan, or is refused with
+// A turn the on-device screen finds uncertain, alone or in context, is not
+// served locally: it goes to Synalux cloud on a paid plan, or is refused with
 // cloud_fallback: false. The result names the reason (layer1_uncertain) so
 // the host can decide what to do with the thread.
 prism_infer({

package/dist/localFirstPolicy.js

@@ -9,7 +9,8 @@ export const LOCAL_FIRST_POLICY_LINES = [
     "## Prism local-first orchestration",
     "For bounded, verifiable delegated work, use Prism's local worker before any host-native or background subagent.",
     "When session_task_route is available, call it first. If it returns target `claw`, call `prism_infer` with the",
-    "recommended arguments, `cloud_fallback: false`, and the `project` and `conversation_id` from this session when known.",
+    "recommended arguments and the `project` and `conversation_id` from this session when known. Leave `cloud_fallback`",
+    "unset so the plan decides it; pass `false` to forbid cloud inference fallback.",
     "If the route says `needs_history`, or the task follows up an earlier `prism_infer` answer, pass the accepted prior",
     "turns as `messages` (paid plans); never send a follow-up without them, and never re-send a turn you rejected.",
     "Prism loads that project's dashboard-configured quick, standard, or deep memory and selects a RAM-safe local model.",

package/dist/storage/inferMetricsLedger.js

@@ -42,8 +42,8 @@ const LEDGER_UNAVAILABLE_ERROR = "Inference metrics ledger is unavailable";
 const INSERT_METRIC_SQL = `INSERT OR IGNORE INTO infer_metrics
     (ts, caller, mode, backend, model, used_cloud, gate_outcome,
      refusal_reason, prompt_tokens, completion_tokens, latency_ms, ram_free_mb,
-     source_event_id)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+     source_event_id, history_turns, refusal_layer)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
 function closeClient(context) {
     const activeClient = client;
     client = null;
@@ -83,17 +83,25 @@ function ensureTable() {
                     completion_tokens INTEGER,
                     latency_ms INTEGER,
                     ram_free_mb INTEGER,
-                    source_event_id TEXT
+                    source_event_id TEXT,
+                    history_turns INTEGER,
+                    refusal_layer TEXT
                 )`);
             // Existing ledgers predate external panel-spool ingestion. SQLite has
             // no ADD COLUMN IF NOT EXISTS, so use the repository's established
             // idempotent migration pattern and reject only unexpected failures.
-            try {
-                await client.execute(`ALTER TABLE infer_metrics ADD COLUMN source_event_id TEXT`);
-            }
-            catch (e) {
-                if (!(e instanceof Error) || !e.message.includes("duplicate column name"))
-                    throw e;
+            for (const column of [
+                "source_event_id TEXT",
+                "history_turns INTEGER",
+                "refusal_layer TEXT",
+            ]) {
+                try {
+                    await client.execute(`ALTER TABLE infer_metrics ADD COLUMN ${column}`);
+                }
+                catch (e) {
+                    if (!(e instanceof Error) || !e.message.includes("duplicate column name"))
+                        throw e;
+                }
             }
             await client.execute(`CREATE INDEX IF NOT EXISTS idx_infer_metrics_ts ON infer_metrics (ts)`);
             await client.execute(`CREATE UNIQUE INDEX IF NOT EXISTS idx_infer_metrics_source_event
@@ -149,6 +157,7 @@ function metricArgs(row) {
         row.refusal_reason ?? null, row.prompt_tokens ?? null,
         row.completion_tokens ?? null, row.latency_ms ?? null,
         row.ram_free_mb ?? null, row.source_event_id ?? null,
+        row.history_turns ?? null, row.refusal_layer ?? null,
     ];
 }
 /** Aggregate all persisted rows (optionally since a timestamp). */

package/dist/tools/prismInferHandler.js

@@ -9,7 +9,7 @@
  *   1. Probe Ollama, list tags
  *   2. Pick largest viable local tier (pickLocalModel)
  *   3. Call /api/generate locally — return on success
- *   4. On local fail, if cloud_fallback=true:
+ *   4. On local fail, if the plan allows cloud (explicit cloud_fallback:false forbids it):
  *        - exchange synalux_sk_ → JWT (cached)
  *        - POST synalux portal /api/v1/prism/inference
  *        - portal serves Gemini 3.6 Flash according to the user's tier
@@ -259,6 +259,11 @@ async function classifyHistoryWindow(l1fn, window, ollamaUrl, model, budget) {
         budget.tripped = true;
         return "UNCERTAIN";
     }
+    // deterministic:false is deliberate for a JOINT window and must stay so:
+    // the co-occurrence rules see words from different turns as one clause
+    // (the 2026-09-16 field refusal's joined window fires them; every turn
+    // alone is clean). The rules run per turn in proximity slices upstream;
+    // here only the model reads, and only to RAISE.
     const verdict = await l1fn(window, ollamaUrl, model, undefined, undefined, { deterministic: false });
     if (budget) {
         budget.consecutiveErrors = verdict === "ERROR" ? budget.consecutiveErrors + 1 : 0;
@@ -389,7 +394,7 @@ export const PRISM_INFER_TOOL = {
         "the caller's `task_complexity`, then validates loaded memory size, model context, " +
         "entitlements, installed models, and free RAM at call time. " +
         "Falls through to the Synalux portal Gemini 3.6 Flash cloud fallback " +
-        "only when local is unviable AND `cloud_fallback=true`. " +
+        "only when local is unviable or refused and the plan allows cloud; `cloud_fallback: false` forbids it. " +
         "When `project` is provided, loads the dashboard-configured quick/standard/deep handoff and bounded history " +
         "as untrusted historical context for a memory-aware local worker. " +
         "Use this for code generation, summarisation, classification, or any synth task you would " +
@@ -474,8 +479,7 @@ export const PRISM_INFER_TOOL = {
             },
             cloud_fallback: {
                 type: "boolean",
-                description: "Fall through to the Synalux portal cascade on local failure. Default false: saving tokens is the point.",
-                default: false,
+                description: "Synalux portal cascade when local is unviable or refused. Omitted: the plan decides; false forbids it.",
             },
             timeout_ms: {
                 type: "number",
@@ -529,7 +533,7 @@ export const PRISM_INFER_TOOL = {
                 type: "string",
                 enum: ["auto", "local"],
                 description: "'auto' (default): local advertised-tool contract plus, on paid plans, the private " +
-                    "Synalux deterministic route correction. 'local': prompt and draft stay on-device.",
+                    "Synalux deterministic route correction. 'local': skips that correction only.",
                 default: "auto",
             },
             think: {
@@ -1051,8 +1055,9 @@ export class ReservedRefusalError extends Error {
         const what = category ? `category="${category}"` : "matched the semantic classifier";
         const remedy = cloudWasAllowed
             ? "Cloud escalation was permitted and did not produce an answer; see attempts."
-            : "Reserved content is never answered by a local model. Pass cloud_fallback: true "
-                + "to escalate to a stronger model, or answer it in the host thread instead.";
+            : "Reserved content is never answered by a local model. This call had no cloud: either it "
+                + "passed cloud_fallback: false, or the plan has none. Pass cloud_fallback: true (or omit "
+                + "it, on a paid plan) to escalate to a stronger model, or answer it in the host thread instead.";
         super(`prism_infer: Layer 1 verdict=${verdict}, ${what} — reserved content refused. `
             + `${remedy} attempts=${JSON.stringify(attempts)}`);
         this.attempts = attempts;
@@ -1060,7 +1065,7 @@ export class ReservedRefusalError extends Error {
         this.name = "ReservedRefusalError";
     }
 }
-function makeReservedRefusal(verdict, attempts, category = null, cloudWasAllowed = false) {
+function makeReservedRefusal(verdict, attempts, category = null, cloudWasAllowed = false, ledger = {}) {
     // Ledger the refusal (fire-and-forget). No prompt content is persisted —
     // same HIPAA posture as the safety_gate exclusion. gate_outcome mirrors
     // the §5.2 report-mode row so refusal queries see both modes.
@@ -1068,6 +1073,8 @@ function makeReservedRefusal(verdict, attempts, category = null, cloudWasAllowed
         backend: "refused", model: null, used_cloud: false,
         gate_outcome: "refused",
         refusal_reason: "layer1_reserved",
+        history_turns: ledger.history_turns,
+        refusal_layer: ledger.refusal_layer,
     });
     return new ReservedRefusalError(verdict, attempts, category, cloudWasAllowed);
 }
@@ -1400,10 +1407,25 @@ export async function runInfer(args, deps) {
     // Retained for the log line, which describes the request rather than a
     // specific backend.
     const maxTokens = cloudMaxTokens;
-    // Cloud fallback only for paid plans
+    // Cloud fallback is the PLAN's to give. An omitted flag means "whatever my
+    // plan entitles me to": paid plans escalate, free plans do not. Explicit
+    // false still forbids cloud INFERENCE fallback — the clinical delegation
+    // rules and token-saving callers depend on that; the route guard and the
+    // grounding verifier keep their own switches (route_guard, verify) — and
+    // explicit true still needs a
+    // plan with cloud. Until 2026-09-16 an omitted flag meant "no cloud", so a
+    // paid, portal-ruled entitlement sat unused and an UNCERTAIN verdict
+    // dead-ended instead of escalating; measured in production the day
+    // multi-turn shipped, on a host that simply did not pass the argument.
     // let, not const: the reserved-image branch pins this off mid-call so no
     // later escalation path can carry even the prompt text off-device.
-    let allowCloud = args.cloud_fallback === true && ent.features.cloud_fallback;
+    // The default is image-aware: cloud can never serve an image request
+    // (screenshots stay on this device), so defaulting it ON for one would only
+    // convert a gate-failed-but-usable local answer into a hard failure — an
+    // explicit request still behaves as before and is refused at the point of
+    // use with its attempt named.
+    const planDefault = ent.features.cloud_fallback && !(args.images?.length);
+    let allowCloud = (args.cloud_fallback ?? planDefault) && ent.features.cloud_fallback;
     // Verification only for paid plans (free users skip L3 grounding)
     const canVerify = ent.features.grounding_verifier;
     // The portal entitlement is authoritative. A paid plan alone must not
@@ -1438,6 +1460,20 @@ export async function runInfer(args, deps) {
         multi_turn: multiTurnPolicy(ent),
         history_turns: args.messages?.length ?? 0,
     };
+    // Which screen layer decided the call; ledgered on a refusal. Bookkeeping
+    // only: raise() is worseLayer1Verdict with a label and the assignment stays
+    // at the call site, so it changes no outcome. Declared here because
+    // refusedResult() can run before the Layer 1 block. Without it, "which
+    // layer refused this" needs a transcript replay — exactly what a benign
+    // production refusal cost on 2026-09-16.
+    let l1Layer = null;
+    const ledgerMeta = () => ({ history_turns: args.messages?.length ?? 0, refusal_layer: l1Layer ?? undefined });
+    const raise = (cur, next, source) => {
+        const merged = worseLayer1Verdict(cur, next);
+        if (merged !== cur)
+            l1Layer = source;
+        return merged;
+    };
     const refusedResult = (reason) => ({
         output: "",
         backend: "refused",
@@ -1448,6 +1484,7 @@ export async function runInfer(args, deps) {
         attempts,
         ...entMeta,
         gate_outcome: { status: "refused", reason, served_anyway: false },
+        refusal_layer: l1Layer ?? undefined,
     });
     debugLog(`[prism_infer] plan=${ent.plan} ceiling=${effectiveCeiling} max_tokens=${maxTokens} ` +
         `cloud=${allowCloud} verify=${canVerify} route_guard=${canUsePrivateRouteGuard}`);
@@ -1593,6 +1630,8 @@ export async function runInfer(args, deps) {
         if (!args.messages?.length) {
             // Single turn: the exact call it always was.
             l1 = await l1fn(args.prompt, deps.ollamaUrl, l1Model, undefined, resolvedImages);
+            if (l1 !== "OBVIOUS_NOT_RESERVED")
+                l1Layer = "prompt";
         }
         else {
             l1 = "OBVIOUS_NOT_RESERVED";
@@ -1621,7 +1660,7 @@ export async function runInfer(args, deps) {
                 for (const slice of windowsOf(turn.content, DETERMINISTIC_FLOOR_WINDOW_CHARS, DETERMINISTIC_FLOOR_WINDOW_OVERLAP)) {
                     const det = classifyDeterministicLayer1(slice, { operational: isUser });
                     if (det)
-                        l1 = worseLayer1Verdict(l1, det);
+                        l1 = raise(l1, det, "rules");
                 }
             }
             // 2. Semantic floor, per TURN in isolation; every verdict read
@@ -1651,10 +1690,10 @@ export async function runInfer(args, deps) {
                         continue;
                     const alone = await classifyHistoryWindow(l1fn, window, deps.ollamaUrl, l1Model, budget);
                     if (alone === "OBVIOUS_RESERVED") {
-                        l1 = "OBVIOUS_RESERVED";
+                        l1 = raise(l1, "OBVIOUS_RESERVED", "isolated");
                         break history;
                     }
-                    l1 = worseLayer1Verdict(l1, alone);
+                    l1 = raise(l1, alone, "isolated");
                 }
             }
             // The current prompt is a request: its deterministic floor runs
@@ -1667,7 +1706,7 @@ export async function runInfer(args, deps) {
             for (const slice of windowsOf(args.prompt, DETERMINISTIC_FLOOR_WINDOW_CHARS, DETERMINISTIC_FLOOR_WINDOW_OVERLAP)) {
                 const promptDet = classifyDeterministicLayer1(slice);
                 if (promptDet)
-                    l1 = worseLayer1Verdict(l1, promptDet);
+                    l1 = raise(l1, promptDet, "rules");
                 if (promptDet !== "OBVIOUS_NOT_RESERVED")
                     promptRoutine = false;
             }
@@ -1681,7 +1720,7 @@ export async function runInfer(args, deps) {
             // (review round 19: skipping it there bypassed that floor).
             const promptFastPath = promptRoutine && args.prompt.length <= MAX_CLASSIFIER_PROMPT_LENGTH && (resolvedImages?.length ?? 0) === 0;
             if (l1 !== "OBVIOUS_RESERVED" && !promptFastPath) {
-                l1 = worseLayer1Verdict(l1, await l1fn(args.prompt, deps.ollamaUrl, l1Model, undefined, resolvedImages, { deterministic: false }));
+                l1 = raise(l1, await l1fn(args.prompt, deps.ollamaUrl, l1Model, undefined, resolvedImages, { deterministic: false }), "prompt");
             }
             // 3. Context, raise only: one window per turn and one for the
             // prompt (see contextWindows), cached like any window. Skipped
@@ -1697,7 +1736,7 @@ export async function runInfer(args, deps) {
                 for (const window of contextWindows(args)) {
                     if (!window.trim())
                         continue;
-                    l1 = worseLayer1Verdict(l1, await classifyHistoryWindow(l1fn, window, deps.ollamaUrl, l1Model, budget));
+                    l1 = raise(l1, await classifyHistoryWindow(l1fn, window, deps.ollamaUrl, l1Model, budget), "context");
                     if (l1 === "UNCERTAIN" || l1 === "OBVIOUS_RESERVED")
                         break;
                 }
@@ -1705,7 +1744,7 @@ export async function runInfer(args, deps) {
             // A budget or breaker trip raises to UNCERTAIN whatever the cache
             // held (text: cloud or refused; with an image: local only).
             if (budget.tripped)
-                l1 = worseLayer1Verdict(l1, "UNCERTAIN");
+                l1 = raise(l1, "UNCERTAIN", "budget");
             if (budget.calls > LAYER1_SCREEN_CALL_BUDGET) {
                 attempts.push({ tier: "layer1", reason: `layer1_screen_over_budget:${LAYER1_SCREEN_CALL_BUDGET}` });
             }
@@ -1753,7 +1792,7 @@ export async function runInfer(args, deps) {
                 attempts.push({ tier: "synalux", reason: "reserved_escalation_refused_images_stay_local" });
                 if (wantReport)
                     return refusedResult("layer1_reserved");
-                throw makeReservedRefusal(l1, attempts, reservedCat, true);
+                throw makeReservedRefusal(l1, attempts, reservedCat, true, ledgerMeta());
             }
             if (allowCloud) {
                 const cloudTimeout = args.timeout_ms ?? 90_000;
@@ -1769,7 +1808,7 @@ export async function runInfer(args, deps) {
                         attempts.push({ tier: "synalux", reason: `reserved_weak_backend:${cloud.backend}` });
                         if (wantReport)
                             return refusedResult("layer1_reserved");
-                        throw makeReservedRefusal(l1, attempts, reservedCat, true);
+                        throw makeReservedRefusal(l1, attempts, reservedCat, true, ledgerMeta());
                     }
                     return await applyVerification(cloud.output, gatedArgs, deps, {
                         backend: cloud.backend ?? "synalux",
@@ -1787,7 +1826,7 @@ export async function runInfer(args, deps) {
             }
             if (wantReport)
                 return refusedResult("layer1_reserved");
-            throw makeReservedRefusal(l1, attempts, reservedCat, allowCloud);
+            throw makeReservedRefusal(l1, attempts, reservedCat, allowCloud, ledgerMeta());
         }
         if (l1 === "UNCERTAIN_LENGTH") {
             // §5.3: prompt too long to classify in full, but the full-text
@@ -1818,7 +1857,7 @@ export async function runInfer(args, deps) {
                 attempts.push({ tier: "synalux", reason: "error_escalation_refused_images_stay_local" });
                 if (wantReport)
                     return refusedResult("layer1_error");
-                throw makeReservedRefusal(l1, attempts);
+                throw makeReservedRefusal(l1, attempts, null, false, ledgerMeta());
             }
             if (allowCloud) {
                 const cloudTimeout = args.timeout_ms ?? 90_000;
@@ -1842,6 +1881,7 @@ export async function runInfer(args, deps) {
             debugLog(`[prism_infer] keyword backstop verdict=${backstop}`);
             attempts.push({ tier: "keyword_backstop", reason: `backstop_${backstop.toLowerCase()}` });
             if (backstop === "OBVIOUS_RESERVED") {
+                l1Layer = "backstop"; // the regex net refused, whatever raised the verdict before it
                 if (wantReport)
                     return refusedResult("keyword_backstop_reserved");
                 // Serve-mode backstop refusal previously wrote NO ledger row —
@@ -1850,6 +1890,8 @@ export async function runInfer(args, deps) {
                     backend: "refused", model: null, used_cloud: false,
                     gate_outcome: "refused",
                     refusal_reason: "keyword_backstop_reserved",
+                    history_turns: args.messages?.length ?? 0,
+                    refusal_layer: "backstop",
                 });
                 throw new Error(`prism_infer: classifier failed + keyword backstop caught reserved content. attempts=${JSON.stringify(attempts)}`);
             }

package/dist/tools/taskRouterHandler.js

@@ -347,7 +347,10 @@ function buildRecommendedArgs(args, complexityScore) {
         ...(args.project ? { project: args.project } : {}),
         mode: "code",
         task_complexity: complexityScore,
-        cloud_fallback: false,
+        // cloud_fallback is deliberately absent: prism_infer resolves it from the
+        // plan's entitlements, which the router does not read. Pinning it false
+        // here made a paid plan's escalation unreachable for any host that copied
+        // these arguments verbatim (2026-09-16).
         escalation: "report",
     };
 }

package/dist/utils/inferenceMetrics.js

@@ -139,6 +139,8 @@ export function recordInference(result) {
         completion_tokens: result.completion_tokens,
         latency_ms: result.latency_ms,
         ram_free_mb: result.ram_free_mb,
+        history_turns: result.history_turns,
+        refusal_layer: result.refusal_layer,
     });
     // §5.2: refused results (escalation:"report") get a ledger row above but
     // must NOT touch the session accumulators — no model ran and nothing was

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.20.0",
+  "version": "20.21.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",