prism-mcp-server 19.2.8 → 19.3.0

package/dist/tools/prismInferHandler.js

@@ -22,14 +22,15 @@
 import { pickLocalModel, fmtGb, MODEL_TIERS, resolveOllamaName } from "../utils/modelPicker.js";
 import { getSynaluxJwt, invalidateSynaluxJwt } from "../utils/synaluxJwt.js";
 import { getAvailableMemoryBytes } from "../utils/availableMemory.js";
-import { PRISM_SYNALUX_BASE_URL, PRISM_LOCAL_LLM_URL, } from "../config.js";
+import { PRISM_SYNALUX_BASE_URL, PRISM_LOCAL_LLM_URL, SYNALUX_CONFIGURED, } from "../config.js";
 import { debugLog } from "../utils/logger.js";
 import { getEntitlements, clampCeiling } from "../utils/entitlements.js";
 import { ddLog } from "../utils/ddLogger.js";
 import { stripThink } from "../utils/thinkStrip.js";
 import { passesQualityGate } from "../utils/qualityGate.js";
 import { checkInputSafety, checkOutputSafety } from "../utils/safetyGate.js";
-import { recordInference } from "../utils/inferenceMetrics.js";
+import { callLayer1 as defaultCallLayer1 } from "../utils/layer1.js";
+import { recordInference, formatInferenceMetrics } from "../utils/inferenceMetrics.js";
 // ─── Tool Definition ────────────────────────────────────────────
 export const PRISM_INFER_TOOL = {
     name: "prism_infer",
@@ -148,6 +149,8 @@ export function isPrismInferArgs(args) {
         return false;
     if (a.think !== undefined && typeof a.think !== "boolean")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     if (a.verify !== undefined && typeof a.verify !== "boolean")
         return false;
     if (a.verifier_model !== undefined && typeof a.verifier_model !== "string")
@@ -299,6 +302,48 @@ async function callSynaluxInference(prompt, maxTokens, timeoutMs) {
         return { ok: false, reason: name === "TimeoutError" || name === "AbortError" ? "synalux_timeout" : "synalux_network" };
     }
 }
+// ─── Portal verifier (thin-client HTTP call) ──────────────────
+async function callSynaluxVerifier(opts) {
+    if (!PRISM_SYNALUX_BASE_URL)
+        throw new Error("no_synalux_base_url");
+    const jwt = await getSynaluxJwt();
+    if (!jwt)
+        throw new Error("jwt_exchange_failed");
+    const url = `${PRISM_SYNALUX_BASE_URL}/api/v1/prism/verify-grounding`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Authorization": `Bearer ${jwt}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            draft: opts.draft,
+            evidence: opts.evidence,
+            verifierModel: opts.verifierModel,
+            // Give portal 500ms headroom before our own AbortSignal fires.
+            timeoutMs: Math.max(500, (opts.timeoutMs ?? 5_000) - 500),
+        }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 5_000),
+        redirect: "error",
+    });
+    if (!res.ok)
+        throw new Error(`synalux_verifier_http_${res.status}`);
+    return res.json();
+}
+// In-process mutex that serialises eviction so concurrent requests don't evict
+// a model that another in-flight inference is actively using (F3 fix).
+const _evictionMutex = (() => {
+    let _lock = Promise.resolve();
+    return {
+        acquire() {
+            let release;
+            const next = new Promise(resolve => { release = resolve; });
+            const chain = _lock.then(() => release);
+            _lock = _lock.then(() => next);
+            return chain;
+        },
+    };
+})();
 export async function runInfer(args, deps) {
     const t0 = Date.now();
     const temperature = args.temperature ?? 0;
@@ -366,14 +411,105 @@ export async function runInfer(args, deps) {
     if (installed === null) {
         attempts.push({ tier: "ollama_probe", reason: "unreachable" });
     }
+    // ── §E Layer 1 semantic pre-classifier ──────────────────────────────────
+    // Catches adversarial paraphrases the keyword stub misses.
+    // Runs only when cloud escalation is possible — without cloud, there is
+    // nowhere to route a RESERVED verdict.
+    // Recursion guard: skip when this call IS the Layer 1 classification
+    // (mode="route" + max_tokens<=16 is the Layer 1 call signature).
+    const layer1RecursionGuard = mode === "route" && maxTokens <= 16;
+    if (allowCloud && !layer1RecursionGuard) {
+        const l1fn = deps.callLayer1 ?? defaultCallLayer1;
+        const l1Model = resolveOllamaName("prism-coder:4b", installed ?? new Set());
+        const l1 = await l1fn(args.prompt, deps.ollamaUrl, l1Model);
+        if (l1 !== "OBVIOUS_NOT_RESERVED") {
+            debugLog(`[prism_infer] Layer 1 verdict=${l1} — escalating to cloud`);
+            attempts.push({ tier: "layer1", reason: `layer1_${l1.toLowerCase()}` });
+            const cloudTimeout = args.timeout_ms ?? 90_000;
+            const cloud = await deps.callCloud(args.prompt, maxTokens, cloudTimeout);
+            if (cloud.ok && cloud.output) {
+                return await applyVerification(cloud.output, gatedArgs, deps, {
+                    backend: cloud.backend ?? "synalux",
+                    model_picked: null,
+                    ram_free_mb: ramFreeMb,
+                    latency_ms: Date.now() - t0,
+                    used_cloud: true,
+                    attempts,
+                    plan: ent.plan,
+                    completion_tokens: Math.ceil(cloud.output.length / 4),
+                });
+            }
+            attempts.push({ tier: "synalux", reason: cloud.reason ?? "unknown" });
+            // Layer 1 flagged RESERVED but cloud unavailable — fail closed, never fall through to local.
+            throw new Error(`prism_infer: Layer 1 verdict=${l1} but cloud unavailable. attempts=${JSON.stringify(attempts)}`);
+        }
+        debugLog(`[prism_infer] Layer 1 verdict=OBVIOUS_NOT_RESERVED — proceeding local`);
+    }
+    // ── end Layer 1 ─────────────────────────────────────────────────────────
     // Walk the tier table top → bottom, capped by model_ceiling. Each tier
     // logs its skip reason ("not_pulled" / "ram_insufficient" / fail reason)
     // so the caller can see exactly why each tier was bypassed.
     let localDraft = null;
     if (installed) {
-        const ceilStart = effectiveCeiling
-            ? Math.max(0, MODEL_TIERS.findIndex(t => t.tag.endsWith(`:${effectiveCeiling}`)))
-            : 0;
+        // F4 fix: guard ceiling-not-found — Math.max(0,-1) silently targets tier 0 (27b).
+        // Instead of defaulting to the largest tier, treat not-found as "no ceiling" (start=0).
+        const ceilIdx = effectiveCeiling
+            ? MODEL_TIERS.findIndex(t => t.tag.endsWith(`:${effectiveCeiling}`))
+            : -1;
+        const ceilStart = ceilIdx >= 0 ? ceilIdx : 0;
+        // Auto-evict: if the ceiling tier is installed but not warm and prism's
+        // own smaller tier models are warm, unload them to make room.
+        // Operates only on prism tier models — never evicts arbitrary Ollama models
+        // the caller doesn't own (F1). Uses an in-process mutex to prevent a
+        // concurrent request from evicting a model mid-inference (F3).
+        let freeAfterEvict = freeBytes;
+        if (loaded && loaded.size > 0) {
+            const ceilTier = MODEL_TIERS[ceilIdx >= 0 ? ceilIdx : 0];
+            const ceilName = ceilTier ? resolveOllamaName(ceilTier.tag, installed) : null;
+            const ceilInstalled = ceilName ? installed.has(ceilName) : false;
+            const ceilWarm = ceilName ? loaded.has(ceilName) : false;
+            if (ceilInstalled && !ceilWarm) {
+                // F1 fix: only count and evict prism tier models — not arbitrary warm models.
+                const tierModelsToEvict = MODEL_TIERS
+                    .map(t => resolveOllamaName(t.tag, installed))
+                    .filter(name => loaded.has(name));
+                const tierWarmBytes = tierModelsToEvict.reduce((sum, name) => {
+                    const t = MODEL_TIERS.find(t => resolveOllamaName(t.tag, installed) === name);
+                    return sum + (t ? t.weightsGb * 1024 ** 3 : 0);
+                }, 0);
+                if (freeBytes + tierWarmBytes >= ceilTier.minFreeGb * 1024 ** 3) {
+                    // F3 fix: hold eviction mutex so no concurrent request evicts a model
+                    // that another in-flight inference is actively using.
+                    const released = await _evictionMutex.acquire();
+                    try {
+                        // F2 fix: await each evict call; log failures; don't proceed blind.
+                        const evictResults = await Promise.allSettled(tierModelsToEvict.map(m => fetch(`${deps.ollamaUrl}/api/generate`, {
+                            method: "POST",
+                            body: JSON.stringify({ model: m, keep_alive: 0 }),
+                            signal: AbortSignal.timeout(3_000),
+                        })));
+                        const failed = evictResults.filter(r => r.status === "rejected").length;
+                        if (failed > 0) {
+                            debugLog(`[prism_infer] evict: ${failed}/${tierModelsToEvict.length} unload requests failed`);
+                        }
+                        // Settle: give Ollama time to release buffers before re-reading RAM.
+                        await new Promise(r => setTimeout(r, 800));
+                        freeAfterEvict = deps.freemem();
+                        debugLog(`[prism_infer] auto-evicted ${tierModelsToEvict.join(", ")} ` +
+                            `(${fmtGb(tierWarmBytes)}) → freeAfterEvict=${fmtGb(freeAfterEvict)}`);
+                        // F2 fix: if still insufficient after eviction, log and fall through
+                        // cleanly — the tier loop will emit ram_insufficient rather than
+                        // proceeding on a stale freeBytes value.
+                        if (freeAfterEvict < ceilTier.minFreeGb * 1024 ** 3) {
+                            debugLog(`[prism_infer] evict completed but RAM still insufficient for ${ceilTier.tag}`);
+                        }
+                    }
+                    finally {
+                        released();
+                    }
+                }
+            }
+        }
         let anyViable = false;
         for (let i = ceilStart; i < MODEL_TIERS.length; i++) {
             const tier = MODEL_TIERS[i];
@@ -389,7 +525,7 @@ export async function runInfer(args, deps) {
             // RAM gate — but skip the check if the tier is already warm in
             // Ollama. Reused models don't reallocate weight buffers.
             const isWarm = loaded.has(ollamaName);
-            if (!isWarm && freeBytes < tier.minFreeGb * (1024 ** 3)) {
+            if (!isWarm && freeAfterEvict < tier.minFreeGb * (1024 ** 3)) {
                 attempts.push({ tier: tier.tag, reason: "ram_insufficient" });
                 continue;
             }
@@ -400,20 +536,18 @@ export async function runInfer(args, deps) {
             if (result.ok) {
                 const { stripped, thinkOnly } = stripThink(result.text);
                 const output = stripped;
-                // Quality gate for chat/code modes
-                if (mode !== "route") {
-                    const gate = passesQualityGate(output, thinkOnly, result.doneReason);
-                    if (!gate.pass && allowCloud) {
-                        debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — escalating to cloud`);
-                        attempts.push({ tier: tier.tag, reason: `quality_gate:${gate.reason}` });
-                        if (gate.reason === "hard_truncation" || gate.reason === "loop_detected") {
-                            localDraft = { output, tier: tier.tag, promptTokens: result.promptTokens, completionTokens: result.completionTokens };
-                        }
-                        break;
-                    }
-                    if (!gate.pass) {
-                        debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — no cloud, serving local`);
+                // Quality gate — all modes. Route uses mode-aware empty floor (length===0).
+                const gate = passesQualityGate(output, thinkOnly, result.doneReason, mode);
+                if (!gate.pass && allowCloud) {
+                    debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — escalating to cloud`);
+                    attempts.push({ tier: tier.tag, reason: `quality_gate:${gate.reason}` });
+                    if (gate.reason === "hard_truncation" || gate.reason === "loop_detected") {
+                        localDraft = { output, tier: tier.tag, promptTokens: result.promptTokens, completionTokens: result.completionTokens };
                     }
+                    break;
+                }
+                if (!gate.pass) {
+                    debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — no cloud, serving local`);
                 }
                 return await applyVerification(output, gatedArgs, deps, {
                     backend: `ollama-${tier.tag.replace("prism-coder:", "")}`,
@@ -448,7 +582,9 @@ export async function runInfer(args, deps) {
                 used_cloud: true,
                 attempts,
                 plan: ent.plan,
-                prompt_tokens: Math.ceil(args.prompt.length / 4),
+                // T4: omit prompt_tokens — cloud doesn't return Ollama actual eval count.
+                // recordInference receives prompt_text and computes submittedEst via
+                // estimateTokens(), keeping promptTokensEvaluated=0 (correct for cloud).
                 completion_tokens: Math.ceil(cloud.output.length / 4),
             });
         }
@@ -524,10 +660,24 @@ export async function prismInferHandler(args) {
             callLocal: callOllamaGenerate,
             callCloud: callSynaluxInference,
             ollamaUrl: PRISM_LOCAL_LLM_URL,
+            callVerifier: SYNALUX_CONFIGURED ? callSynaluxVerifier : undefined,
         });
         debugLog(`[prism_infer] backend=${result.backend} model=${result.model_picked} latency=${result.latency_ms}ms free=${result.ram_free_mb}MB`);
         // Local accumulator — sole source of the user-facing metrics block.
-        recordInference(result);
+        // T4: pass prompt_text so recordInference computes submittedEst via
+        // estimateTokens() — critical for cloud path where prompt_tokens is unset.
+        recordInference({ ...result, prompt_text: args.prompt });
+        // Best-effort session telemetry — records that inference ran for this
+        // conversation. Never affects routing or safety decisions.
+        const _convId = args.conversation_id;
+        if (_convId && result.backend !== "safety_gate") {
+            import("../session/sessionContext.js").then(({ noteInferenceForSession }) => {
+                noteInferenceForSession(_convId, {
+                    backend: result.backend,
+                    usedCloud: result.used_cloud,
+                });
+            }).catch(() => { });
+        }
         // Best-effort portal forwarding (independent analytics stream).
         // safety_gate excluded — logging crisis filter triggers is a HIPAA concern.
         if (result.backend !== "safety_gate") {
@@ -543,7 +693,7 @@ export async function prismInferHandler(args) {
         const tokenStr = result.prompt_tokens != null || result.completion_tokens != null
             ? ` tokens=${result.prompt_tokens ?? "?"}in/${result.completion_tokens ?? "?"}out`
             : "";
-        const header = `[prism_infer] backend=${result.backend}` +
+        const headerBase = `[prism_infer] backend=${result.backend}` +
             ` model=${result.model_picked ?? "n/a"}` +
             ` plan=${result.plan ?? "unknown"}` +
             ` free_ram=${result.ram_free_mb}MB` +
@@ -553,6 +703,11 @@ export async function prismInferHandler(args) {
             (result.quality_gate_failed ? ` quality_gate_failed=true` : "") +
             (result.verification ? ` verify=${result.verification.action}` : "") +
             (result.attempts.length ? ` attempts=${JSON.stringify(result.attempts)}` : "");
+        // Append periodic session-level stats to the header line.
+        // compact=true is threshold-gated (PRISM_METRICS_EVERY, default every 5 calls)
+        // so it doesn't appear on every response — only as a rolling summary.
+        const metricsLine = formatInferenceMetrics(true);
+        const header = metricsLine ? `${headerBase}\n${metricsLine}` : headerBase;
         return {
             content: [
                 { type: "text", text: header },

package/dist/tools/sessionDriftHandler.js

@@ -5,7 +5,7 @@
  * (POST /api/v1/prism/memory action=detect_drift) which owns the embedding
  * + detection logic, and returns the structured result.
  *
- * Prism-mcp never does NLP or embedding here — that lives in synalux-private.
+ * Prism-mcp never does NLP or embedding here — that is portal-side.
  */
 import { isSessionDetectDriftArgs } from "./sessionMemoryDefinitions.js";
 import { getStorage } from "../storage/index.js";

package/dist/tools/sessionMemoryDefinitions.js

@@ -99,6 +99,10 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
                 type: "boolean",
                 description: "Set to true to disable automatic CRDT merging and fail strictly on version conflict (original OCC behavior). Default: false.",
             },
+            conversation_id: {
+                type: "string",
+                description: "Optional. Session key for this conversation (same id used in session_load_context). When provided, the server verifies that session_load_context was called for this conversation before accepting the write.",
+            },
         },
         required: ["project"],
     },
@@ -141,6 +145,10 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
                 type: "string",
                 description: "Brief 2-5 word noun phrase describing what this tool call is about.",
             },
+            conversation_id: {
+                type: "string",
+                description: "Optional. Session key for this conversation (same id used in session_save_ledger). When provided, marks the session as context-loaded server-side so project-scoped tools can verify working context without relying on hook-based enforcement. Required on non-Claude hosts.",
+            },
         },
         required: ["project", "toolAction", "toolSummary"],
     },
@@ -509,6 +517,8 @@ export function isSessionSaveHandoffArgs(args) {
         return false;
     if (a.disable_merge !== undefined && typeof a.disable_merge !== "boolean")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     return true;
 }
 // ─── v0.4.0: Type guard for semantic search ──────────────────
@@ -572,6 +582,8 @@ export function isSessionLoadContextArgs(args) {
         return false;
     if (a.toolSummary !== undefined && typeof a.toolSummary !== "string")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     return true;
 }
 // ─── v2.0: Time Travel Tool Definitions ──────────────────────

package/dist/tools/skillRouting.js

@@ -9,9 +9,8 @@
  *      free-tier / disconnected installations still get the BCBA universal
  *      skill loaded.
  *
- * To change the routing for production, edit
- *   synalux-private/portal/src/app/api/v1/skills/routing/route.ts
- * and deploy synalux. prism-mcp picks up the new config within 5 minutes.
+ * To change the routing for production, edit the portal routing endpoint
+ * and deploy. prism-mcp picks up the new config within 5 minutes.
  *
  * Do NOT add hardcoded skill names here outside the OFFLINE_FALLBACK block
  * — that defeats the single-source-of-truth design.
@@ -28,7 +27,10 @@ const OFFLINE_FALLBACK = {
     user_local: { enabled: false, key_prefix: 'user_skill:' },
 };
 const SYNALUX_BASE = process.env.SYNALUX_BASE_URL || 'https://synalux.ai';
-const CACHE_TTL_MS = 5 * 60 * 1000;
+const LIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5min for successful fetches
+const FAILURE_BACKOFF_MS = 30_000; // F5 fix: 30s retry after failure (not 5min)
+// F5 fix: track live vs fallback separately so a transient failure doesn't
+// negative-cache the full routing table for 5 minutes, dropping 19 skills.
 let cached = null;
 let inflight = null;
 async function fetchOnce() {
@@ -51,7 +53,9 @@ async function fetchOnce() {
         return body;
     }
     catch {
-        return OFFLINE_FALLBACK;
+        // On failure: return the last live table (stale-while-revalidate) or OFFLINE_FALLBACK.
+        // The caller marks this as isLive=false so it retries after FAILURE_BACKOFF_MS, not 5min.
+        return cached?.table ?? OFFLINE_FALLBACK;
     }
 }
 /**
@@ -68,15 +72,21 @@ function normalizeEntry(entry, defaultPriority) {
 }
 export async function resolveSkillsForProject(project) {
     const now = Date.now();
-    if (!cached || now - cached.fetchedAt > CACHE_TTL_MS) {
+    // F5 fix: use shorter backoff TTL after failures so a 30s synalux hiccup doesn't
+    // lock the session into OFFLINE_FALLBACK for 5 minutes.
+    const ttl = (cached?.isLive ?? true) ? LIVE_CACHE_TTL_MS : FAILURE_BACKOFF_MS;
+    if (!cached || now - cached.fetchedAt > ttl) {
         if (!inflight) {
             inflight = fetchOnce().then((table) => {
-                cached = { table, fetchedAt: Date.now() };
+                // isLive = true only when we got a live response (not stale cache / OFFLINE_FALLBACK)
+                const isLive = table !== OFFLINE_FALLBACK && table !== cached?.table;
+                cached = { table, fetchedAt: Date.now(), isLive };
                 return table;
             }).finally(() => { inflight = null; });
         }
         await inflight;
     }
+    const isOffline = !(cached?.isLive ?? false);
     const table = cached.table;
     const seen = new Set();
     const skills = [];
@@ -104,6 +114,7 @@ export async function resolveSkillsForProject(project) {
         names: skills.map(s => s.name),
         skills,
         user_local: table.user_local ?? OFFLINE_FALLBACK.user_local,
+        isOffline,
     };
 }
 /**
@@ -113,10 +124,12 @@ export async function resolveSkillsForProject(project) {
  */
 export async function resolveSkillsForPrompt(prompt, baseSkills = []) {
     const now = Date.now();
-    if (!cached || now - cached.fetchedAt > CACHE_TTL_MS) {
+    const ttl = (cached?.isLive ?? true) ? LIVE_CACHE_TTL_MS : FAILURE_BACKOFF_MS;
+    if (!cached || now - cached.fetchedAt > ttl) {
         if (!inflight) {
             inflight = fetchOnce().then((table) => {
-                cached = { table, fetchedAt: Date.now() };
+                const isLive = table !== OFFLINE_FALLBACK && table !== cached?.table;
+                cached = { table, fetchedAt: Date.now(), isLive };
                 return table;
             }).finally(() => { inflight = null; });
         }

package/dist/utils/analytics.js

@@ -48,10 +48,15 @@ async function ensureTable() {
     `);
     _tableReady = true;
 }
-/** Reset DB connection (for tests). */
+/** Reset DB connection and in-memory buffer (for tests). */
 export function _resetDb() {
     _db = null;
     _tableReady = false;
+    BUFFER.length = 0;
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
 }
 // ─── In-Memory Buffer ────────────────────────────────────────
 const BUFFER = [];

package/dist/utils/entitlements.js

@@ -93,6 +93,15 @@ async function fetchEntitlements() {
                 return cache.entitlements;
             return FREE_ENTITLEMENTS;
         }
+        // Normalize legacy ceiling values to the current fleet.
+        if (data.model_ceiling === "14b") {
+            debugLog("[entitlements] grandfathered 14b ceiling → 9b");
+            data.model_ceiling = "9b";
+        }
+        if (data.model_ceiling === "32b") {
+            debugLog("[entitlements] grandfathered 32b ceiling → 27b");
+            data.model_ceiling = "27b";
+        }
         debugLog(`[entitlements] plan=${data.plan} ceiling=${data.model_ceiling} ` +
             `daily=${data.daily_infer_limit} max_tokens=${data.max_tokens}`);
         return data;

package/dist/utils/inferenceMetrics.js

@@ -1,20 +1,40 @@
 /**
  * Inference metrics — local accumulator for user-facing display.
  *
- * The local accumulator is the SOLE source for the session metrics block
- * shown in session_save_ledger/handoff. It tracks what THIS prism process
- * did THIS session — prism is the natural and only complete source for
- * this data (the portal only sees what prism forwards).
+ * Tracks what THIS prism process did THIS session. Portal forwarding
+ * (ddLog) is a separate best-effort stream — display never depends on it.
  *
- * Portal forwarding (ddLog → /api/v1/telemetry) is a separate, best-effort
- * analytics stream that the display path never depends on. If the portal
- * is down, unconfigured, or the token is missing, users still see metrics.
+ * T1 fix: content-aware chars/token estimator (was flat /4, biased for
+ *   emoji-dense/code/CJK payloads by 15–40%).
+ * T2 fix: dual-column prompt tokens — `evaluated` (Ollama actual) vs
+ *   `submittedEst` (estimated submitted, including KV-cached prefixes).
+ *   Ollama returns prompt_eval_count=0 for cached prompts, so "evaluated"
+ *   undercounts on repeated system-prompt calls; submittedEst shows actual load.
  */
 import { debugLog } from "./logger.js";
+// T1 fix: content-aware token estimator. Replaces flat text.length / 4 which
+// underestimates emoji (~2 UTF-16 units but 1.5-2.5 BPE tokens) and CJK
+// (~1 char ≈ 1 token) by 15-40%, and overestimates dense code (~3.3 chars/token).
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const cjkCount = (text.match(/[　-鿿豈-﫿]/g) ?? []).length;
+    const emojiCount = (text.match(/[\u{1F000}-\u{1FFFF}]/gu) ?? []).length;
+    // Code density check: >2% of chars are code punctuation → use code divisor
+    const codePunct = (text.match(/[`{};\[\]=>|#@$%^&*\\]/g) ?? []).length;
+    const isCode = text.length > 0 && codePunct / text.length > 0.02;
+    // UTF-16 length minus CJK and emoji codepoints (emoji are 2 units each)
+    const latinLen = text.length - cjkCount - emojiCount * 2;
+    const latinTokens = latinLen / (isCode ? 3.3 : 4.0);
+    const cjkTokens = cjkCount; // ~1 token per CJK char
+    const emojiTokens = emojiCount * 1.5; // ~1.5 BPE tokens per emoji
+    return Math.ceil(Math.max(0, latinTokens) + cjkTokens + emojiTokens);
+}
 const byModel = {};
 let localCalls = 0;
 let cloudCalls = 0;
-let totalPromptTokens = 0;
+let promptTokensEvaluated = 0;
+let promptTokensSubmittedEst = 0;
 let totalCompletionTokens = 0;
 let totalLatencyMs = 0;
 export function recordInference(result) {
@@ -27,16 +47,35 @@ export function recordInference(result) {
     else {
         localCalls++;
     }
-    const pt = result.prompt_tokens ?? 0;
+    const evaluated = result.prompt_tokens ?? 0;
     const ct = result.completion_tokens ?? 0;
-    totalPromptTokens += pt;
+    // T2: when Ollama returns 0 evaluated (KV-cache hit), estimate submitted tokens
+    // from the prompt text/length so submittedEst reflects actual context load.
+    let submittedEst = evaluated; // default: evaluated is the best estimate
+    if (evaluated === 0 && !result.used_cloud) {
+        if (result.prompt_text) {
+            submittedEst = estimateTokens(result.prompt_text);
+        }
+        else if (result.prompt_length && result.prompt_length > 0) {
+            submittedEst = Math.ceil(result.prompt_length / 4); // flat fallback without text
+        }
+    }
+    promptTokensEvaluated += evaluated;
+    promptTokensSubmittedEst += submittedEst;
     totalCompletionTokens += ct;
     totalLatencyMs += result.latency_ms;
     if (!byModel[key]) {
-        byModel[key] = { calls: 0, promptTokens: 0, completionTokens: 0, totalLatencyMs: 0 };
+        byModel[key] = {
+            calls: 0,
+            promptTokensEvaluated: 0,
+            promptTokensSubmittedEst: 0,
+            completionTokens: 0,
+            totalLatencyMs: 0,
+        };
     }
     byModel[key].calls++;
-    byModel[key].promptTokens += pt;
+    byModel[key].promptTokensEvaluated += evaluated;
+    byModel[key].promptTokensSubmittedEst += submittedEst;
     byModel[key].completionTokens += ct;
     byModel[key].totalLatencyMs += result.latency_ms;
 }
@@ -52,9 +91,10 @@ export function getInferenceSnapshot() {
         totalCalls: total,
         localPct: total > 0 ? Math.round((localCalls / total) * 100) : 0,
         cloudPct: total > 0 ? 100 - Math.round((localCalls / total) * 100) : 0,
-        totalPromptTokens,
+        promptTokensEvaluated,
+        promptTokensSubmittedEst,
         totalCompletionTokens,
-        totalTokens: totalPromptTokens + totalCompletionTokens,
+        totalTokens: promptTokensSubmittedEst + totalCompletionTokens,
         avgLatencyMs: total > 0 ? Math.round(totalLatencyMs / total) : 0,
         byModel: modelCopy,
     };
@@ -62,7 +102,8 @@ export function getInferenceSnapshot() {
 export function resetInferenceMetrics() {
     localCalls = 0;
     cloudCalls = 0;
-    totalPromptTokens = 0;
+    promptTokensEvaluated = 0;
+    promptTokensSubmittedEst = 0;
     totalCompletionTokens = 0;
     totalLatencyMs = 0;
     for (const key of Object.keys(byModel)) {
@@ -75,27 +116,54 @@ export async function inferenceMetricsHandler() {
     return {
         content: [{
                 type: "text",
-                text: block || "No prism_infer calls this session. Metrics track local-model delegation only — not the host model's (Claude's) token spend.",
+                text: block || "No prism_infer calls this session.\n" +
+                    "📊 Delegation Metrics track local-model delegation — not the host model's (Claude's) spend.",
             }],
     };
 }
-export function formatInferenceMetrics() {
+/**
+ * Format inference metrics.
+ *
+ * @param compact - When true, returns a single-line footer for appending to
+ *   prism_infer responses. Output is threshold-gated: only emits every
+ *   PRISM_METRICS_EVERY calls (default 5) so it doesn't drown per-response output.
+ *   When false (default), returns the full multi-line block used by the explicit
+ *   inference_metrics tool.
+ */
+export function formatInferenceMetrics(compact = false) {
     const snap = getInferenceSnapshot();
     if (snap.totalCalls === 0)
         return "";
+    if (compact) {
+        // Threshold gate: only emit every N calls so the footer is periodic, not per-call noise.
+        // The per-call header already shows backend/model/latency; this is the session rollup.
+        const every = parseInt(process.env["PRISM_METRICS_EVERY"] ?? "5", 10);
+        // Always emit on the first call (totalCalls===1) so short sessions (1–4 calls)
+        // see at least one rollup. Otherwise emit every N calls as the rolling summary.
+        if (snap.totalCalls !== 1 && snap.totalCalls % every !== 0)
+            return "";
+        return `📊 local ${snap.localCalls} (${snap.localPct}%) · cloud ${snap.cloudCalls} (${snap.cloudPct}%) · ~${snap.totalTokens.toLocaleString()} tok · avg ${snap.avgLatencyMs}ms`;
+    }
+    // Full multi-line block (explicit inference_metrics tool call).
+    // T2: show both evaluated (Ollama actual) and submitted estimate.
+    // When they differ, the gap is KV-cached prompt tokens (real load, not counted by Ollama).
+    const promptLine = snap.promptTokensEvaluated !== snap.promptTokensSubmittedEst
+        ? `  Prompt tokens: ${snap.promptTokensEvaluated.toLocaleString()} evaluated / ${snap.promptTokensSubmittedEst.toLocaleString()} submitted est.`
+        : `  Prompt tokens: ${snap.promptTokensEvaluated.toLocaleString()}`;
     const lines = [
-        `\n📊 Inference Metrics — local-model delegation (this session):`,
+        `\n📊 Delegation Metrics — local-model calls this session (not host model spend):`,
         `  Total calls: ${snap.totalCalls} — Local: ${snap.localCalls} (${snap.localPct}%) | Cloud: ${snap.cloudCalls} (${snap.cloudPct}%)`,
-        `  Tokens: ${snap.totalPromptTokens.toLocaleString()} in + ${snap.totalCompletionTokens.toLocaleString()} out = ${snap.totalTokens.toLocaleString()} total`,
+        promptLine,
+        `  Completion tokens: ${snap.totalCompletionTokens.toLocaleString()}`,
         `  Avg latency: ${snap.avgLatencyMs}ms`,
     ];
     const models = Object.entries(snap.byModel).sort((a, b) => b[1].calls - a[1].calls);
     if (models.length > 1) {
         lines.push(`  By model:`);
         for (const [name, stats] of models) {
-            const tokens = stats.promptTokens + stats.completionTokens;
+            const tokens = stats.promptTokensSubmittedEst + stats.completionTokens;
             const avgMs = stats.calls > 0 ? Math.round(stats.totalLatencyMs / stats.calls) : 0;
-            lines.push(`    ${name}: ${stats.calls} calls, ${tokens.toLocaleString()} tokens, avg ${avgMs}ms`);
+            lines.push(`    ${name}: ${stats.calls} calls, ${tokens.toLocaleString()} tokens est., avg ${avgMs}ms`);
         }
     }
     return lines.join("\n");