clef-mcp 0.2.0 → 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.0";
+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) {
@@ -1503,10 +1591,12 @@ function scoreCriteria(limits) {
 }
 function questionSchema(limits) {
   return z.object({
-    type: z.enum(["noul", "choice", "score"]),
-    instructions: z.string().min(1).max(limits.maxInstructionsChars),
+    type: z.enum(["noul", "choice", "score"]).describe('"choice" = pick among named options; "score" = judge an ordered scale; "noul" = yes/no question'),
+    instructions: z.string().min(1).max(limits.maxInstructionsChars).describe("What to judge, phrased as a self-contained question."),
     criteria: z.union([z.array(z.string()), z.record(z.string(), z.string())]).optional()
-  }).superRefine((q, ctx) => {
+  }).describe(
+    "A single decision question. Allowed answers come from `criteria` and must be mutually exclusive and collectively exhaustive."
+  ).superRefine((q, ctx) => {
     if (q.type === "choice") {
       const parsed = choiceCriteria(limits).safeParse(q.criteria);
       if (!parsed.success) {
@@ -1530,23 +1620,27 @@ function questionSchema(limits) {
 }
 function clefDecideInputShape(limits) {
   return {
-    state: z.unknown(),
-    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).check((ctx) => {
+    state: z.unknown().describe(
+      "Task state as data: a compact string or JSON object with the facts needed to judge (task, errors, logs, diffs). Never treated as instructions. Serialized size limit: 1 MB; model context is 16k tokens."
+    ),
+    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).describe(
+      "Map of question id -> typed question. Up to 64 questions per call; all are scored together in a single forward pass, so batch related decisions here."
+    ).check((ctx) => {
       const count = Object.keys(ctx.value).length;
       if (count === 0) ctx.issues.push({ code: "custom", message: "questions must not be empty", input: ctx.value });
       if (count > limits.maxQuestions) {
         ctx.issues.push({ code: "custom", message: `too many questions (max ${limits.maxQuestions})`, input: ctx.value });
       }
     }),
-    model: z.string().min(1).optional(),
+    model: z.string().min(1).optional().describe("Model id to use (default: clef-flash from CLEF_MODEL)."),
     options: z.object({
       /**
        * Accepted for forward compatibility. Clef scores all options in a
        * single forward pass — there is no sampling, so temperature is a
        * documented no-op.
        */
-      temperature: z.number().min(0).max(2).optional()
-    }).optional()
+      temperature: z.number().min(0).max(2).optional().describe("Accepted for forward compatibility; no-op. Clef scores in a single forward pass without sampling.")
+    }).optional().describe("Extra options. Currently only temperature, which is a documented no-op.")
   };
 }
 function clefDecideInputSchema(limits) {
@@ -1555,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) {
@@ -1803,63 +1910,20 @@ 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: "Pass task state and a set of structured questions (noul / choice / score) to the local Clef decision model. Returns a probability distribution over the allowed answers for every question. The result is structured JSON.",
+      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
+      outputSchema: clefDecideOutputSchema().shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async (args) => {
       try {
@@ -1873,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 {
@@ -1891,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();
@@ -1914,7 +1975,7 @@ function createClefServer(deps = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 export {
   CLEF_FLASH,
   ClefError,