feat: add inference_metrics read-only MCP tool (19.2.3)

New tool returns the session's local-delegation metrics on demand.
No args, read-only, reads the existing local accumulator. Description
explicitly notes this tracks prism_infer delegation only, not Claude's
own token spend.

2 new tests for the handler (empty + populated).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Synalux AI

package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "19.2.2",
+  "version": "19.2.3",
   "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-first storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",

src/server.ts

@@ -100,6 +100,7 @@ import { sanitizeMcpOutput } from "./utils/sanitizer.js";
 import { getTracer, initTelemetry } from "./utils/telemetry.js";
 import { context as otelContext, trace, SpanStatusCode } from "@opentelemetry/api";
 import { ddInfo, ddError as ddLogError } from "./utils/ddLogger.js";
+import { inferenceMetricsHandler } from "./utils/inferenceMetrics.js";
 
 // ─── Import Tool Definitions (schemas) and Handlers (implementations) ─────
 
@@ -171,6 +172,8 @@ import {
   QUERY_MEMORY_NATURAL_TOOL,
   // v15.5: Knowledge Ingestion
   KNOWLEDGE_INGEST_TOOL,
+  // v19.2: Inference Metrics
+  INFERENCE_METRICS_TOOL,
 
   sessionSaveLedgerHandler,
   sessionSaveHandoffHandler,
@@ -345,6 +348,8 @@ function buildSessionMemoryTools(autoloadList: string[]): Tool[] {
     QUERY_MEMORY_NATURAL_TOOL,     // query_memory_natural — NL → structured memory search
     // ─── v15.5: Knowledge Ingestion ───
     KNOWLEDGE_INGEST_TOOL,         // knowledge_ingest — chunk code, gen Q&A, store in graph
+    // ─── v19.2: Inference Metrics ───
+    INFERENCE_METRICS_TOOL,          // inference_metrics — read-only session delegation stats
   ];
 }
 
@@ -1078,6 +1083,9 @@ export function createServer() {
             if (!SESSION_MEMORY_ENABLED) throw new Error("Session memory not configured.");
             result = await knowledgeIngestHandler(args); break;
 
+          case "inference_metrics":
+            result = await inferenceMetricsHandler(); break;
+
           default:
             result = {
               content: [{ type: "text", text: `Unknown tool: ${name}` }],

src/tools/index.ts

@@ -120,6 +120,7 @@ export { verifyBehaviorHandler } from "./behavioralVerifierHandler.js";
 // Chunks source code, generates Q&A via Claude Haiku, stores in knowledge graph.
 // Three entry points: MCP tool, REST API, GitHub webhook.
 export { KNOWLEDGE_INGEST_TOOL } from "./ingestDefinitions.js";
+export { INFERENCE_METRICS_TOOL } from "./sessionMemoryDefinitions.js";
 export { knowledgeIngestHandler, handleGitHubWebhook, ingestKnowledge, isIngestArgs } from "./ingestHandler.js";
 
 // ── v15.4: prism_infer — local-first inference (RAM-gated cascade) ──

src/tools/sessionMemoryDefinitions.ts

@@ -2035,3 +2035,18 @@ export function isVerifyBehaviorArgs(a: unknown): a is {
   if (typeof o.change_summary !== "string") return false;
   return true;
 }
+
+// ─── v19.2: Inference Metrics Tool ──────────────────────────
+
+export const INFERENCE_METRICS_TOOL: Tool = {
+  name: "inference_metrics",
+  description:
+    "Returns the current session's local-model inference metrics — call count, " +
+    "local vs cloud split, token totals, per-model breakdown, and average latency. " +
+    "Read-only, no arguments. Reflects prism_infer delegation usage only, not the " +
+    "host model's (Claude's) own token spend (use /cost for that).",
+  inputSchema: {
+    type: "object",
+    properties: {},
+  },
+};

src/utils/inferenceMetrics.ts

@@ -105,6 +105,19 @@ export function resetInferenceMetrics(): void {
     debugLog("[inference-metrics] Session metrics reset");
 }
 
+export async function inferenceMetricsHandler(): Promise<{
+    content: Array<{ type: "text"; text: string }>;
+    isError?: boolean;
+}> {
+    const block = formatInferenceMetrics();
+    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.",
+        }],
+    };
+}
+
 export function formatInferenceMetrics(): string {
     const snap = getInferenceSnapshot();
     if (snap.totalCalls === 0) return "";

tests/inferenceMetrics.test.ts

@@ -4,6 +4,7 @@ import {
     getInferenceSnapshot,
     resetInferenceMetrics,
     formatInferenceMetrics,
+    inferenceMetricsHandler,
 } from "../src/utils/inferenceMetrics.js";
 
 beforeEach(() => {
@@ -147,6 +148,19 @@ describe("formatInferenceMetrics", () => {
         expect(out.indexOf("prism-coder:9b")).toBeLessThan(out.indexOf("prism-coder:27b"));
     });
 
+    it("handler returns message when no calls", async () => {
+        const result = await inferenceMetricsHandler();
+        expect(result.content[0].text).toContain("No prism_infer calls");
+        expect(result.content[0].text).toContain("local-model delegation");
+    });
+
+    it("handler returns metrics block when calls exist", async () => {
+        recordInference({ backend: "ollama-9b", model_picked: "prism-coder:9b", used_cloud: false, latency_ms: 100, prompt_tokens: 200, completion_tokens: 80 });
+        const result = await inferenceMetricsHandler();
+        expect(result.content[0].text).toContain("Total calls: 1");
+        expect(result.content[0].text).toContain("Local: 1 (100%)");
+    });
+
     it("mixed local and cloud", () => {
         recordInference({ backend: "ollama-9b", model_picked: "prism-coder:9b", used_cloud: false, latency_ms: 50, prompt_tokens: 100, completion_tokens: 50 });
         recordInference({ backend: "synalux", model_picked: null, used_cloud: true, latency_ms: 200, prompt_tokens: 80, completion_tokens: 40 });