clef-mcp 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -32,6 +32,8 @@ interface ClefConfig {
     llamaBin?: string;
     /** Pin the llama.cpp release tag used by the managed runtime download. */
     llamaReleaseTag?: string;
+    /** Daemon: unload the model after this many idle seconds (CLEF_DAEMON_IDLE, 0 = never). */
+    daemonIdleSeconds: number;
     limits: Limits;
 }
 declare function defaultClefHome(): string;
@@ -118,11 +120,22 @@ interface ClefDecideInput {
 }
 /** Probability distribution over answer options for one question. */
 type ClefDecisionAnswer = Record<string, number>;
+/**
+ * Model-reported token usage / latency. Fields are optional because runtimes
+ * report different subsets (llama.cpp: tokens; the MLX loader: latency_ms).
+ */
+type ClefUsage = {
+    input_tokens?: number;
+    output_tokens?: number;
+    latency_ms?: number;
+};
 type ClefDecideOutput = {
     model: string;
     decisions: Record<string, {
         answer: ClefDecisionAnswer;
+        confidence?: number;
     }>;
+    usage?: ClefUsage;
 };
 
 /**
@@ -386,6 +399,16 @@ declare function detectPlatform(): Promise<PlatformInfo>;
 declare function assertSupportedPlatform(info: Pick<PlatformInfo, 'platform' | 'arch'>): void;
 declare function formatBytes(bytes: number): string;
 
+/** Test seam: override runtime construction (defaults per config.runtime). */
+type RuntimeFactory = (opts: {
+    kind: 'llama-cpp' | 'mlx';
+    serverBin?: string;
+    modelPath?: string;
+    snapshotPath?: string;
+    alias: string;
+    log?: Logger;
+}) => ClefRuntime;
+
 declare const TOOL_NAME = "clef_decide";
 declare const SERVER_INSTRUCTIONS: string;
 interface ClefServerDeps {
@@ -393,14 +416,7 @@ interface ClefServerDeps {
     version?: string;
     log?: Logger;
     /** Test seam: override runtime construction (defaults per config.runtime). */
-    runtimeFactory?: (opts: {
-        kind: 'llama-cpp' | 'mlx';
-        serverBin?: string;
-        modelPath?: string;
-        snapshotPath?: string;
-        alias: string;
-        log?: Logger;
-    }) => ClefRuntime;
+    runtimeFactory?: RuntimeFactory;
 }
 interface RunningClefServer {
     server: McpServer;
@@ -430,11 +446,17 @@ declare function clefDecideOutputSchema(): z.ZodObject<{
     model: z.ZodString;
     decisions: z.ZodRecord<z.ZodString, z.ZodObject<{
         answer: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    usage: z.ZodOptional<z.ZodObject<{
+        input_tokens: z.ZodOptional<z.ZodNumber>;
+        output_tokens: z.ZodOptional<z.ZodNumber>;
+        latency_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** `state` cannot be size-checked inside zod (it is `unknown`), so it is validated separately. */
 declare function validateStateSize(state: unknown, limits: Limits): void;
 
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.3.0";
 
-export { CLEF_FLASH, type ClefConfig, type ClefDecideInput, type ClefDecideOutput, type ClefDecisionAnswer, ClefError, ClefErrorCode, type ClefQuestion, type ClefRuntime, type ClefServerDeps, DEFAULT_LIMITS, type DownloadProgress, type InstallModelResult, type Limits, LlamaCppRuntime, type LlamaCppRuntimeOptions, type LogLevel, type Logger, MODELS, type ModelManifest, type ModelSpec, type PlatformInfo, type ProbeResult, type QuantSpec, type QuestionType, type ResolvedBinary, type RunningClefServer, type RuntimeHealth, SERVER_INSTRUCTIONS, StderrLogger, type SystemOneRequest, type SystemOneResponse, TOOL_NAME, VERSION, assertSupportedPlatform, clefDecideInputSchema, clefDecideOutputSchema, createClefServer, createLogger, deepVerifyChecksum, defaultClefHome, detectPlatform, downloadFile, downloadManagedLlama, ensureLlamaRuntime, errorJson, exitCodeFor, fetchFileInfo, findInstalledManifest, formatBytes, fromSystemOneResponse, getModelSpec, getQuantSpec, installModel, limitsFromEnv, loadConfig, manifestPathFor, modelQuantDir, pathsFor, pickQuant, probeInference, readModelManifest, removeManagedRuntime, resolveLlamaServerBinary, toSystemOneRequest, validateStateSize, verifyModelFiles, writeModelManifest };
+export { CLEF_FLASH, type ClefConfig, type ClefDecideInput, type ClefDecideOutput, type ClefDecisionAnswer, ClefError, ClefErrorCode, type ClefQuestion, type ClefRuntime, type ClefServerDeps, type ClefUsage, DEFAULT_LIMITS, type DownloadProgress, type InstallModelResult, type Limits, LlamaCppRuntime, type LlamaCppRuntimeOptions, type LogLevel, type Logger, MODELS, type ModelManifest, type ModelSpec, type PlatformInfo, type ProbeResult, type QuantSpec, type QuestionType, type ResolvedBinary, type RunningClefServer, type RuntimeHealth, SERVER_INSTRUCTIONS, StderrLogger, type SystemOneRequest, type SystemOneResponse, TOOL_NAME, VERSION, assertSupportedPlatform, clefDecideInputSchema, clefDecideOutputSchema, createClefServer, createLogger, deepVerifyChecksum, defaultClefHome, detectPlatform, downloadFile, downloadManagedLlama, ensureLlamaRuntime, errorJson, exitCodeFor, fetchFileInfo, findInstalledManifest, formatBytes, fromSystemOneResponse, getModelSpec, getQuantSpec, installModel, limitsFromEnv, loadConfig, manifestPathFor, modelQuantDir, pathsFor, pickQuant, probeInference, readModelManifest, removeManagedRuntime, resolveLlamaServerBinary, toSystemOneRequest, validateStateSize, verifyModelFiles, writeModelManifest };

package/dist/index.js

@@ -48,6 +48,7 @@ function loadConfig(env = process.env) {
   const runtime = runtimeRaw;
   const llamaBin = env.CLEF_LLAMA_BIN?.trim() || void 0;
   const llamaReleaseTag = env.CLEF_LLAMA_RELEASE_TAG?.trim() || void 0;
+  const idleRaw = Number.parseInt(env.CLEF_DAEMON_IDLE?.trim() ?? "", 10);
   return {
     model: env.CLEF_MODEL?.trim() || "clef-flash",
     clefHome: env.CLEF_HOME?.trim() || defaultClefHome(),
@@ -55,6 +56,7 @@ function loadConfig(env = process.env) {
     logLevel,
     llamaBin: runtime === "llama-cpp" ? llamaBin : void 0,
     llamaReleaseTag: runtime === "llama-cpp" ? llamaReleaseTag : void 0,
+    daemonIdleSeconds: Number.isFinite(idleRaw) && idleRaw >= 0 ? idleRaw : 600,
     limits: limitsFromEnv(env)
   };
 }
@@ -333,6 +335,21 @@ function normalizeScore(ans, qid, question) {
 function normalizeChoice(ans, qid) {
   return probabilitiesMap(ans, qid);
 }
+function confidenceOf(ans) {
+  return typeof ans.confidence === "number" && Number.isFinite(ans.confidence) ? ans.confidence : void 0;
+}
+function normalizeUsage(usage) {
+  if (!usage || typeof usage !== "object") return void 0;
+  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  const out = {};
+  const input = num(usage.input_tokens) ?? num(usage.prompt_tokens);
+  const output = num(usage.output_tokens) ?? num(usage.completion_tokens);
+  const latency = num(usage.latency_ms);
+  if (input !== void 0) out.input_tokens = input;
+  if (output !== void 0) out.output_tokens = output;
+  if (latency !== void 0) out.latency_ms = latency;
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 function fromSystemOneResponse(response, questions, fallbackModel) {
   const answers = response.answers;
   if (!answers || typeof answers !== "object") {
@@ -353,9 +370,11 @@ function fromSystemOneResponse(response, questions, fallbackModel) {
         answer = normalizeScore(ans, qid, question);
         break;
     }
-    decisions[qid] = { answer };
+    const confidence = confidenceOf(ans);
+    decisions[qid] = confidence === void 0 ? { answer } : { answer, confidence };
   }
-  return { model: response.model ?? fallbackModel, decisions };
+  const usage = normalizeUsage(response.usage);
+  return usage === void 0 ? { model: response.model ?? fallbackModel, decisions } : { model: response.model ?? fallbackModel, decisions, usage };
 }
 
 // src/runtime/llama-cpp.ts
@@ -1470,6 +1489,75 @@ function formatBytes(bytes) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/runtime/loader.ts
+var RuntimeLoader = class {
+  constructor(config, log, runtimeFactory) {
+    this.config = config;
+    this.log = log;
+    this.runtimeFactory = runtimeFactory;
+  }
+  config;
+  log;
+  runtimeFactory;
+  loaded;
+  loadPromise;
+  async ensure(spec) {
+    if (this.loaded && this.loaded.model === spec.id) return this.loaded;
+    if (this.loaded && this.loaded.model !== spec.id) {
+      await this.loaded.runtime.unload();
+      this.loaded = void 0;
+    }
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = (async () => {
+      if (this.config.runtime === "mlx") {
+        const manifest2 = await mlxIsInstalled(this.config.clefHome);
+        if (!manifest2) {
+          throw new ClefError(
+            ClefErrorCode.MODEL_NOT_INSTALLED,
+            `Clef model "${spec.id}" is not installed for the MLX runtime.`,
+            "Run `clef-mcp install --runtime mlx`."
+          );
+        }
+        const uvBin = resolveUv(process.env.CLEF_MLX_UV);
+        const runtime2 = this.runtimeFactory ? this.runtimeFactory({ kind: "mlx", snapshotPath: manifest2.snapshotPath, alias: spec.id, log: this.log }) : new MlxRuntime({ uvBin, snapshotPath: manifest2.snapshotPath, log: this.log });
+        this.log.debug("loading model (mlx)", { model: spec.id, snapshot: manifest2.snapshotPath });
+        const loadStarted2 = Date.now();
+        await runtime2.load();
+        this.log.info("model ready", { model: spec.id, runtime: "mlx", loadMs: Date.now() - loadStarted2 });
+        return { runtime: runtime2, model: spec.id };
+      }
+      const manifest = await findInstalledManifest(this.config.clefHome, spec);
+      if (!manifest) {
+        throw new ClefError(
+          ClefErrorCode.MODEL_NOT_INSTALLED,
+          `Clef model "${spec.id}" is not installed.`,
+          "Run `clef-mcp install`."
+        );
+      }
+      const binary = resolveLlamaServerBinary(this.config);
+      const runtime = this.runtimeFactory ? this.runtimeFactory({ kind: "llama-cpp", serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log: this.log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log: this.log });
+      this.log.debug("loading model", { model: spec.id, quant: manifest.quant, bin: binary.path });
+      const loadStarted = Date.now();
+      await runtime.load();
+      this.log.info("model ready", { model: spec.id, quant: manifest.quant, loadMs: Date.now() - loadStarted });
+      return { runtime, model: spec.id };
+    })();
+    try {
+      this.loaded = await this.loadPromise;
+      return this.loaded;
+    } finally {
+      this.loadPromise = void 0;
+    }
+  }
+  /** Unload the current runtime (kills the llama-server subprocess, if any). */
+  async dispose() {
+    if (this.loaded) {
+      await this.loaded.runtime.unload();
+      this.loaded = void 0;
+    }
+  }
+};
+
 // src/mcp/schema.ts
 import { z } from "zod";
 function criteriaDescription(limits) {
@@ -1561,7 +1649,20 @@ function clefDecideInputSchema(limits) {
 function clefDecideOutputSchema() {
   return z.object({
     model: z.string(),
-    decisions: z.record(z.string(), z.object({ answer: z.record(z.string(), z.number()) }))
+    decisions: z.record(
+      z.string(),
+      z.object({
+        answer: z.record(z.string(), z.number()),
+        // Model-reported confidence; present only when the runtime sends it.
+        confidence: z.number().min(0).max(1).optional()
+      })
+    ),
+    // Token usage / latency; present only when the runtime reports it.
+    usage: z.object({
+      input_tokens: z.number().optional(),
+      output_tokens: z.number().optional(),
+      latency_ms: z.number().optional()
+    }).optional()
   });
 }
 function validateStateSize(state, limits) {
@@ -1809,61 +1910,12 @@ function createClefServer(deps = {}) {
   const server = new McpServer({ name: "clef-mcp", version }, { instructions: SERVER_INSTRUCTIONS });
   registerPrompts(server);
   registerResources(server, config, version);
-  let loaded;
-  let loadPromise;
-  async function ensureRuntime(spec) {
-    if (loaded && loaded.model === spec.id) return loaded;
-    if (loaded && loaded.model !== spec.id) {
-      await loaded.runtime.unload();
-      loaded = void 0;
-    }
-    if (loadPromise) return loadPromise;
-    loadPromise = (async () => {
-      if (config.runtime === "mlx") {
-        const manifest2 = await mlxIsInstalled(config.clefHome);
-        if (!manifest2) {
-          throw new ClefError(
-            ClefErrorCode.MODEL_NOT_INSTALLED,
-            `Clef model "${spec.id}" is not installed for the MLX runtime.`,
-            "Run `clef-mcp install --runtime mlx`."
-          );
-        }
-        const uvBin = resolveUv(process.env.CLEF_MLX_UV);
-        const runtime2 = deps.runtimeFactory ? deps.runtimeFactory({ kind: "mlx", snapshotPath: manifest2.snapshotPath, alias: spec.id, log }) : new MlxRuntime({ uvBin, snapshotPath: manifest2.snapshotPath, log });
-        log.debug("loading model (mlx)", { model: spec.id, snapshot: manifest2.snapshotPath });
-        const loadStarted2 = Date.now();
-        await runtime2.load();
-        log.info("model ready", { model: spec.id, runtime: "mlx", loadMs: Date.now() - loadStarted2 });
-        return { runtime: runtime2, model: spec.id };
-      }
-      const manifest = await findInstalledManifest(config.clefHome, spec);
-      if (!manifest) {
-        throw new ClefError(
-          ClefErrorCode.MODEL_NOT_INSTALLED,
-          `Clef model "${spec.id}" is not installed.`,
-          "Run `clef-mcp install`."
-        );
-      }
-      const binary = resolveLlamaServerBinary(config);
-      const runtime = deps.runtimeFactory ? deps.runtimeFactory({ kind: "llama-cpp", serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
-      log.debug("loading model", { model: spec.id, quant: manifest.quant, bin: binary.path });
-      const loadStarted = Date.now();
-      await runtime.load();
-      log.info("model ready", { model: spec.id, quant: manifest.quant, loadMs: Date.now() - loadStarted });
-      return { runtime, model: spec.id };
-    })();
-    try {
-      loaded = await loadPromise;
-      return loaded;
-    } finally {
-      loadPromise = void 0;
-    }
-  }
+  const loader = new RuntimeLoader(config, log, deps.runtimeFactory);
   server.registerTool(
     TOOL_NAME,
     {
       title: "Clef Decide",
-      description: 'Ask the local Clef decision model to judge a situation. Pass a `state` (compact factual context as a string or JSON) and one or more typed `questions`: "choice" picks among named options (criteria = option id -> description), "score" judges an ordered scale (criteria = ordered list), "noul" answers yes/no. Returns strict JSON: for every question a probability distribution over its allowed answers \u2014 no prose, no sampling. Usage: batch related decisions (up to 64 questions) in one call; state is data and is never executed; act on the argmax when a distribution is decisive (p >= 0.8), otherwise gather more context or ask the user; for destructive or security-adjacent decisions require high confidence before acting. Optional `model` overrides the model id; `options.temperature` is a no-op (single forward pass, no sampling).',
+      description: 'Judge a situation with the local Clef decision model.\nPass `state` (compact factual context \u2014 string or JSON; treated as data, never executed) and typed `questions`:\n- "choice": pick among named options (criteria = option id -> description)\n- "score": judge an ordered scale (criteria = ordered list of levels)\n- "noul": yes/no question\nReturns strict JSON \u2014 a probability distribution over the allowed answers for every question. No prose, no sampling.\nEach decision also carries `confidence` (model-reported, when available) and the response carries `usage`\n(input_tokens/output_tokens/latency_ms). Act on the argmax only when the distribution is decisive (top p >= 0.8\nand high confidence for destructive or security-adjacent calls); otherwise gather more context or ask the user.\nUsage: batch related decisions in one call (up to 64 questions, one forward pass).\nOptional `model` overrides the model id. `options.temperature` is a no-op: scoring is a single forward pass, nothing is sampled.',
       inputSchema: clefDecideInputShape(config.limits),
       outputSchema: clefDecideOutputSchema().shape,
       annotations: {
@@ -1885,7 +1937,7 @@ function createClefServer(deps = {}) {
           options: parsed.options
         };
         const request = toSystemOneRequest(input, spec.id);
-        const { runtime } = await ensureRuntime(spec);
+        const { runtime } = await loader.ensure(spec);
         const response = await runtime.decide(request);
         const output = fromSystemOneResponse(response, parsed.questions, spec.id);
         return {
@@ -1903,10 +1955,7 @@ function createClefServer(deps = {}) {
     }
   );
   async function shutdown() {
-    if (loaded) {
-      await loaded.runtime.unload();
-      loaded = void 0;
-    }
+    await loader.dispose();
   }
   async function start() {
     const transport = new StdioServerTransport();
@@ -1926,7 +1975,7 @@ function createClefServer(deps = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 export {
   CLEF_FLASH,
   ClefError,