clef-mcp 0.2.0 → 0.3.0

package/dist/cli.js

@@ -104,9 +104,9 @@ __export(setup_exports, {
 });
 import { execFile as execFile5 } from "child_process";
 import fsSync4 from "fs";
-import fsp8 from "fs/promises";
+import fsp10 from "fs/promises";
 import os4 from "os";
-import path10 from "path";
+import path11 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function bundledSkillPath() {
   return fileURLToPath2(new URL("../skills/clef-decisions/SKILL.md", import.meta.url));
@@ -114,7 +114,7 @@ function bundledSkillPath() {
 async function mergeJsonServerEntry(file, serverKey, container) {
   let doc = {};
   try {
-    doc = JSON.parse(await fsp8.readFile(file, "utf8"));
+    doc = JSON.parse(await fsp10.readFile(file, "utf8"));
   } catch {
     doc = {};
   }
@@ -131,15 +131,15 @@ async function mergeJsonServerEntry(file, serverKey, container) {
     servers[serverKey] = { command: SERVER_ENTRY.command, args: [...SERVER_ENTRY.args] };
     doc.mcpServers = servers;
   }
-  await fsp8.mkdir(path10.dirname(file), { recursive: true });
-  await fsp8.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
+  await fsp10.mkdir(path11.dirname(file), { recursive: true });
+  await fsp10.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
   return "configured";
 }
 async function setupCodex() {
-  const file = path10.join(HOME(), ".codex", "config.toml");
+  const file = path11.join(HOME(), ".codex", "config.toml");
   let content = "";
   try {
-    content = await fsp8.readFile(file, "utf8");
+    content = await fsp10.readFile(file, "utf8");
   } catch {
     content = "";
   }
@@ -147,24 +147,24 @@ async function setupCodex() {
     return { client: "codex", status: "already-configured", detail: file };
   }
   const next = (content && !content.endsWith("\n") ? content + "\n" : content) + "\n" + CODEX_SECTION;
-  await fsp8.mkdir(path10.dirname(file), { recursive: true });
-  await fsp8.writeFile(file, next, "utf8");
+  await fsp10.mkdir(path11.dirname(file), { recursive: true });
+  await fsp10.writeFile(file, next, "utf8");
   return { client: "codex", status: "configured", detail: file };
 }
 async function setupZcode() {
-  const file = path10.join(HOME(), ".zcode", "cli", "config.json");
+  const file = path11.join(HOME(), ".zcode", "cli", "config.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcp.servers");
   return { client: "zcode", status, detail: file };
 }
 async function setupCursor() {
-  const file = path10.join(HOME(), ".cursor", "mcp.json");
+  const file = path11.join(HOME(), ".cursor", "mcp.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcpServers");
   return { client: "cursor", status, detail: file };
 }
 function whichCli(bin) {
-  const dirs = (process.env.PATH ?? "").split(path10.delimiter).filter(Boolean);
+  const dirs = (process.env.PATH ?? "").split(path11.delimiter).filter(Boolean);
   for (const dir of dirs) {
-    const candidate = path10.join(dir, bin);
+    const candidate = path11.join(dir, bin);
     try {
       fsSync4.accessSync(candidate, fsSync4.constants.X_OK);
       return candidate;
@@ -200,19 +200,19 @@ async function setupClaudeCode() {
 }
 async function installSkill() {
   const src = bundledSkillPath();
-  const destDir = path10.join(HOME(), ".agents", "skills", "clef-decisions");
-  const dest = path10.join(destDir, "SKILL.md");
+  const destDir = path11.join(HOME(), ".agents", "skills", "clef-decisions");
+  const dest = path11.join(destDir, "SKILL.md");
   let content = "";
   try {
-    content = await fsp8.readFile(dest, "utf8");
+    content = await fsp10.readFile(dest, "utf8");
   } catch {
   }
-  const incoming = await fsp8.readFile(src, "utf8");
+  const incoming = await fsp10.readFile(src, "utf8");
   if (content === incoming) {
     return { client: "skill", status: "already-configured", detail: dest };
   }
-  await fsp8.mkdir(destDir, { recursive: true });
-  await fsp8.writeFile(dest, incoming, "utf8");
+  await fsp10.mkdir(destDir, { recursive: true });
+  await fsp10.writeFile(dest, incoming, "utf8");
   return { client: "skill", status: "configured", detail: dest };
 }
 function parseClients(raw) {
@@ -437,6 +437,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") {
@@ -457,9 +472,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/config/env.ts
@@ -512,6 +529,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(),
@@ -519,6 +537,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)
   };
 }
@@ -570,48 +589,6 @@ function createLogger(level, sink) {
   return new StderrLogger(level, sink);
 }
 
-// src/models/manifest.ts
-import { createHash } from "crypto";
-import fs from "fs";
-import fsp from "fs/promises";
-import path3 from "path";
-
-// src/config/paths.ts
-import path2 from "path";
-function pathsFor(clefHome) {
-  const root = path2.resolve(clefHome);
-  return {
-    root,
-    modelsDir: path2.join(root, "models"),
-    runtimeDir: path2.join(root, "runtime"),
-    configJson: path2.join(root, "config.json")
-  };
-}
-function quantDirLabel(quant) {
-  switch (quant) {
-    case "Q4_K_M":
-      return "4bit";
-    case "Q8_0":
-      return "8bit";
-    case "BF16":
-      return "bf16";
-    default:
-      return quant.toLowerCase();
-  }
-}
-function modelQuantDir(modelsDir, model, quant) {
-  return path2.join(modelsDir, model, quantDirLabel(quant));
-}
-function manifestPathFor(modelsDir, model, quant) {
-  return path2.join(modelQuantDir(modelsDir, model, quant), "manifest.json");
-}
-function llamaRuntimeDir(runtimeDir, platform, arch) {
-  return path2.join(runtimeDir, "llama.cpp", `${platform}-${arch}`);
-}
-function llamaServerName(platform) {
-  return platform === "win32" ? "llama-server.exe" : "llama-server";
-}
-
 // src/models/registry.ts
 init_errors();
 var GB = 1024 ** 3;
@@ -667,6 +644,51 @@ function pickQuant(spec, totalMemBytes, requested) {
 }
 var QUANT_PREFERENCE = ["Q4_K_M", "Q8_0", "BF16"];
 
+// src/runtime/loader.ts
+init_errors();
+
+// src/models/manifest.ts
+import { createHash } from "crypto";
+import fs from "fs";
+import fsp from "fs/promises";
+import path3 from "path";
+
+// src/config/paths.ts
+import path2 from "path";
+function pathsFor(clefHome) {
+  const root = path2.resolve(clefHome);
+  return {
+    root,
+    modelsDir: path2.join(root, "models"),
+    runtimeDir: path2.join(root, "runtime"),
+    configJson: path2.join(root, "config.json")
+  };
+}
+function quantDirLabel(quant) {
+  switch (quant) {
+    case "Q4_K_M":
+      return "4bit";
+    case "Q8_0":
+      return "8bit";
+    case "BF16":
+      return "bf16";
+    default:
+      return quant.toLowerCase();
+  }
+}
+function modelQuantDir(modelsDir, model, quant) {
+  return path2.join(modelsDir, model, quantDirLabel(quant));
+}
+function manifestPathFor(modelsDir, model, quant) {
+  return path2.join(modelQuantDir(modelsDir, model, quant), "manifest.json");
+}
+function llamaRuntimeDir(runtimeDir, platform, arch) {
+  return path2.join(runtimeDir, "llama.cpp", `${platform}-${arch}`);
+}
+function llamaServerName(platform) {
+  return platform === "win32" ? "llama-server.exe" : "llama-server";
+}
+
 // src/models/manifest.ts
 function isModelManifest(v) {
   if (!v || typeof v !== "object") return false;
@@ -1398,6 +1420,75 @@ ${tail}` : ""), "Run `clef-mcp doctor` for a full diagnosis.")
   }
 };
 
+// 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
 init_errors();
 import { z } from "zod";
@@ -1432,10 +1523,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) {
@@ -1459,23 +1552,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) {
@@ -1484,7 +1581,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) {
@@ -1840,63 +1950,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 {
@@ -1910,7 +1977,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 {
@@ -1928,10 +1995,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();
@@ -1950,16 +2014,326 @@ function createClefServer(deps = {}) {
   return { server, start, shutdown };
 }
 
+// src/daemon/daemon.ts
+init_errors();
+import net3 from "net";
+import fsp5 from "fs/promises";
+import path7 from "path";
+function daemonSocketPath(clefHome) {
+  return path7.join(clefHome, "daemon.sock");
+}
+function createQueue() {
+  let tail = Promise.resolve();
+  return function enqueue(task) {
+    const run = tail.then(task, task);
+    tail = run.catch(() => void 0);
+    return run;
+  };
+}
+function startDaemon(config, log) {
+  const socketPath = daemonSocketPath(config.clefHome);
+  const loader = new RuntimeLoader(config, log);
+  const enqueue = createQueue();
+  let lastUsedAt = Date.now();
+  let closed = false;
+  const ready = (async () => {
+    await fsp5.mkdir(config.clefHome, { recursive: true });
+    const live = await new Promise((resolve) => {
+      const probe = net3.connect(socketPath);
+      probe.once("connect", () => {
+        probe.destroy();
+        resolve(true);
+      });
+      probe.once("error", () => resolve(false));
+    });
+    if (live) {
+      throw new ClefError(
+        ClefErrorCode.RUNTIME_INIT_FAILED,
+        `Another clef-mcp daemon is already listening on ${socketPath}.`,
+        "Stop it (kill $(cat the daemon pid)) or remove CLEF_DAEMON_IDLE-stale sockets and retry."
+      );
+    }
+    await fsp5.rm(socketPath, { force: true });
+    const server = net3.createServer((socket) => {
+      let buffer = "";
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        let nl;
+        while ((nl = buffer.indexOf("\n")) >= 0) {
+          const line = buffer.slice(0, nl);
+          buffer = buffer.slice(nl + 1);
+          if (!line.trim()) continue;
+          handleLine(line, socket).catch((err) => {
+            log.error("daemon request failed", errorJson(err).error);
+            writeLine(socket, errorJson(err));
+          });
+        }
+      });
+    });
+    server.listen(socketPath);
+    log.info("clef-mcp daemon listening", { socket: socketPath });
+    const idleMs = config.daemonIdleSeconds * 1e3;
+    const idleTimer = config.daemonIdleSeconds > 0 ? setInterval(() => {
+      if (closed || Date.now() - lastUsedAt < idleMs) return;
+      void loader.dispose().then(() => log.info("daemon idle, model unloaded"));
+    }, Math.min(idleMs, 6e4)) : void 0;
+    if (idleTimer) idleTimer.unref();
+    const shutdown = () => {
+      closed = true;
+      if (idleTimer) clearInterval(idleTimer);
+      void (async () => {
+        server.close();
+        await fsp5.rm(socketPath, { force: true });
+        await loader.dispose();
+        log.info("clef-mcp daemon stopped");
+      })().finally(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    await new Promise((resolve, reject) => {
+      server.once("listening", resolve);
+      server.once("error", reject);
+    });
+  })();
+  async function handleLine(line, socket) {
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch (err) {
+      writeLine(socket, errorJson(new ClefError(ClefErrorCode.INVALID_INPUT, `request is not valid JSON: ${err instanceof Error ? err.message : String(err)}`)));
+      return;
+    }
+    if (request.ping) {
+      writeLine(socket, { pong: true, model: config.model });
+      return;
+    }
+    lastUsedAt = Date.now();
+    const result = await enqueue(() => decideOnce(request));
+    writeLine(socket, result);
+  }
+  async function decideOnce(request) {
+    let parsed;
+    try {
+      parsed = clefDecideInputSchema(config.limits).parse({ state: request.state, questions: request.questions, ...typeof request.model === "string" ? { model: request.model } : {} });
+    } catch (err) {
+      if (err instanceof ClefError) throw err;
+      const issue = err.issues?.[0];
+      const where = issue?.path?.length ? issue.path.join(".") : "input";
+      throw new ClefError(ClefErrorCode.INVALID_INPUT, `${where}: ${issue?.message ?? "invalid input"}`);
+    }
+    validateStateSize(parsed.state, config.limits);
+    const spec = getModelSpec(parsed.model ?? config.model);
+    const { runtime } = await loader.ensure(spec);
+    const response = await runtime.decide(toSystemOneRequest({ state: parsed.state, questions: parsed.questions, model: spec.id }, spec.id));
+    return fromSystemOneResponse(response, parsed.questions, spec.id);
+  }
+  return {
+    ready,
+    close: async () => {
+      closed = true;
+      await loader.dispose();
+      await fsp5.rm(socketPath, { force: true });
+    }
+  };
+}
+function writeLine(socket, payload) {
+  socket.write(`${JSON.stringify(payload)}
+`);
+}
+
 // src/cli/index.ts
 import { Command } from "commander";
 
+// src/cli/decide.ts
+init_errors();
+import fsp6 from "fs/promises";
+import { ZodError } from "zod";
+
+// src/daemon/client.ts
+import net4 from "net";
+function decideViaDaemon(socketPath, doc, timeoutMs = 12e4) {
+  return new Promise((resolve, reject) => {
+    const socket = net4.connect(socketPath);
+    let buffer = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(new Error(`daemon did not answer within ${timeoutMs} ms`));
+    }, timeoutMs);
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      fn();
+    };
+    socket.once("connect", () => {
+      socket.write(`${JSON.stringify(doc)}
+`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const nl = buffer.indexOf("\n");
+      if (nl < 0) return;
+      const line = buffer.slice(0, nl);
+      finish(() => {
+        try {
+          resolve(JSON.parse(line));
+        } catch {
+          reject(new Error("daemon returned a non-JSON answer"));
+        }
+      });
+    });
+    socket.once("error", (err) => {
+      if (settled) return;
+      finish(() => {
+        if (err.code === "ECONNREFUSED" || err.code === "ENOENT") {
+          resolve(void 0);
+        } else {
+          reject(err);
+        }
+      });
+    });
+  });
+}
+
+// src/cli/decide.ts
+function invalid(message, hint) {
+  return new ClefError(ClefErrorCode.INVALID_INPUT, message, hint);
+}
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parseJson(text, what) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw invalid(
+      `${what} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+      `${what} must be a JSON document (object for state, { "qid": {...} } map for questions).`
+    );
+  }
+}
+async function readSource(source, what, stdin) {
+  if (source === void 0 || source === "") {
+    throw invalid(`${what} is required`, `Pass --${what} <file|"-" for stdin|inline JSON> or pipe a full document to stdin.`);
+  }
+  if (source === "-") {
+    if (!stdin) throw invalid(`no data on stdin for --${what} -`, "Pipe the JSON in or pass a file path.");
+    return parseJson(stdin, what);
+  }
+  try {
+    await fsp6.access(source);
+    const content = await fsp6.readFile(source, "utf8");
+    return parseJson(content, what);
+  } catch (err) {
+    if (err instanceof ClefError) throw err;
+    if (err.code !== "ENOENT") throw err;
+    if (!source.includes("\n")) {
+      process.stderr.write(`clef-mcp decide: ${source} is not an existing file; using the value as inline ${what}
+`);
+    }
+    const trimmed = source.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) return parseJson(trimmed, what);
+    return source;
+  }
+}
+async function runDecide(opts) {
+  const config = loadConfig();
+  const log = createLogger(config.logLevel);
+  const stdin = await readStdin();
+  let state;
+  let questions;
+  let model;
+  if (opts.questions !== void 0) {
+    questions = await readSource(opts.questions, "questions", stdin);
+    state = await readSource(opts.state, "state", opts.state === "-" ? stdin : "");
+  } else {
+    if (!stdin) {
+      throw invalid(
+        "no input on stdin",
+        'Pipe a JSON document {"state": ..., "questions": {...}} to stdin, or pass --questions <file> (and optionally --state <file>).'
+      );
+    }
+    const doc2 = parseJson(stdin, "input");
+    if (!doc2 || typeof doc2 !== "object" || Array.isArray(doc2)) {
+      throw invalid('stdin input must be a JSON object with "state" and "questions"', "See the clef-mcp README for the document shape.");
+    }
+    const record = doc2;
+    state = record.state;
+    questions = record.questions;
+    if (typeof record.model === "string") model = record.model;
+  }
+  const doc = { state, questions, ...model ? { model } : {} };
+  if (opts.daemon) {
+    const answered = await tryDaemon(config, doc);
+    if (answered) {
+      await new Promise(
+        (resolve, reject) => process.stdout.write(`${JSON.stringify(answered)}
+`, (err) => err ? reject(err) : resolve())
+      );
+      return;
+    }
+  }
+  const parsed = validateDoc(config, doc);
+  const spec = getModelSpec(parsed.model ?? config.model);
+  const loader = new RuntimeLoader(config, log);
+  try {
+    const request = toSystemOneRequest({ state: parsed.state, questions: parsed.questions, model: spec.id }, spec.id);
+    const { runtime } = await loader.ensure(spec);
+    const response = await runtime.decide(request);
+    const output = fromSystemOneResponse(response, parsed.questions, spec.id);
+    await new Promise(
+      (resolve, reject) => process.stdout.write(`${JSON.stringify(output)}
+`, (err) => err ? reject(err) : resolve())
+    );
+  } finally {
+    await loader.dispose();
+  }
+}
+async function tryDaemon(config, doc) {
+  const result = await decideViaDaemon(daemonSocketPath(config.clefHome), doc);
+  if (result === void 0) {
+    process.stderr.write("clef-mcp decide: no daemon reachable; running a cold decision\n");
+    return void 0;
+  }
+  if (result.error && typeof result.error === "object") {
+    const e = result.error;
+    throw new ClefError(e.code, e.message, e.hint);
+  }
+  return result;
+}
+function validateDoc(config, doc) {
+  let parsed;
+  try {
+    parsed = clefDecideInputSchema(config.limits).parse(doc);
+  } catch (err) {
+    if (err instanceof ZodError) {
+      const issue = err.issues[0];
+      const where = issue?.path?.length ? issue.path.join(".") : "input";
+      throw invalid(
+        `${where}: ${issue?.message ?? "invalid input"}`,
+        "Fix the field the path names and retry. Shapes: state is a JSON value or string; questions map qid -> {type, instructions, criteria?}."
+      );
+    }
+    throw err;
+  }
+  validateStateSize(parsed.state, config.limits);
+  return parsed;
+}
+
 // src/cli/doctor.ts
 init_errors();
 import { execFile as execFile3 } from "child_process";
 import os3 from "os";
 import { promisify } from "util";
-import fsp5 from "fs/promises";
-import path7 from "path";
+import fsp7 from "fs/promises";
+import path8 from "path";
 
 // src/models/platform.ts
 init_errors();
@@ -2113,14 +2487,14 @@ async function checkBinaryVersion(binaryPath) {
 async function detectMcpConfigs() {
   const home = os3.homedir();
   const hints = [
-    { client: "Codex", path: path7.join(home, ".codex", "config.toml"), configured: false },
-    { client: "Claude Code (user)", path: path7.join(home, ".claude.json"), configured: false },
-    { client: "Claude Code (project)", path: path7.resolve(".mcp.json"), configured: false },
-    { client: "Cursor", path: path7.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
+    { client: "Codex", path: path8.join(home, ".codex", "config.toml"), configured: false },
+    { client: "Claude Code (user)", path: path8.join(home, ".claude.json"), configured: false },
+    { client: "Claude Code (project)", path: path8.resolve(".mcp.json"), configured: false },
+    { client: "Cursor", path: path8.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
   ];
   for (const hint of hints) {
     try {
-      const content = await fsp5.readFile(hint.path, "utf8");
+      const content = await fsp7.readFile(hint.path, "utf8");
       hint.configured = content.includes("clef-mcp");
     } catch {
       hint.configured = false;
@@ -2333,14 +2707,14 @@ init_errors();
 // src/models/llama-install.ts
 init_errors();
 import { execFile as execFile4 } from "child_process";
-import fsp7 from "fs/promises";
-import path9 from "path";
+import fsp9 from "fs/promises";
+import path10 from "path";
 
 // src/models/hf.ts
 init_errors();
 import { createHash as createHash2 } from "crypto";
-import fsp6 from "fs/promises";
-import path8 from "path";
+import fsp8 from "fs/promises";
+import path9 from "path";
 var HF_BASE_URL = "https://huggingface.co";
 function resolveUrl(repo, revision, file) {
   return `${HF_BASE_URL}/${repo}/resolve/${revision}/${file}`;
@@ -2398,7 +2772,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const total = opts.expectedSize ?? (res.headers.get("content-length") ? Number(res.headers.get("content-length")) : void 0);
   const hash = createHash2("sha256");
-  const handle = await fsp6.open(dest, "w");
+  const handle = await fsp8.open(dest, "w");
   let bytes = 0;
   try {
     for await (const chunk of res.body) {
@@ -2413,7 +2787,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const sha256 = hash.digest("hex");
   if (opts.expectedSha256 && sha256 !== opts.expectedSha256) {
-    await fsp6.rm(dest, { force: true });
+    await fsp8.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.CHECKSUM_MISMATCH,
       `Checksum mismatch after download: expected ${opts.expectedSha256}, got ${sha256}`,
@@ -2421,7 +2795,7 @@ async function downloadOnce(url, dest, opts) {
     );
   }
   if (opts.expectedSize !== void 0 && bytes !== opts.expectedSize) {
-    await fsp6.rm(dest, { force: true });
+    await fsp8.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
       `Downloaded size mismatch: expected ${opts.expectedSize} bytes, got ${bytes}`
@@ -2439,17 +2813,17 @@ async function installModel(opts) {
     return { manifest: existing, alreadyInstalled: true };
   }
   const info = await fetchFileInfo(modelSpec.repo, modelSpec.revision, quantSpec.file);
-  const finalPath = path8.join(path8.dirname(manifestPath2), quantSpec.file);
-  await fsp6.mkdir(path8.dirname(finalPath), { recursive: true });
-  const tmpPath = path8.join(path8.dirname(finalPath), `.download-${quantSpec.file}`);
-  await fsp6.rm(tmpPath, { force: true });
+  const finalPath = path9.join(path9.dirname(manifestPath2), quantSpec.file);
+  await fsp8.mkdir(path9.dirname(finalPath), { recursive: true });
+  const tmpPath = path9.join(path9.dirname(finalPath), `.download-${quantSpec.file}`);
+  await fsp8.rm(tmpPath, { force: true });
   opts.log?.info("downloading model", { repo: modelSpec.repo, file: quantSpec.file });
   const result = await downloadFile(info.downloadUrl, tmpPath, {
     expectedSha256: info.sha256,
     expectedSize: info.size ?? quantSpec.bytes,
     onProgress: opts.onProgress
   });
-  await fsp6.rename(tmpPath, finalPath);
+  await fsp8.rename(tmpPath, finalPath);
   const manifest = {
     schemaVersion: 1,
     model: modelSpec.id,
@@ -2537,12 +2911,12 @@ async function findServerBinary(dir, platform) {
     const current = queue.shift();
     let entries;
     try {
-      entries = await fsp7.readdir(current, { withFileTypes: true });
+      entries = await fsp9.readdir(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
-      const full = path9.join(current, entry.name);
+      const full = path10.join(current, entry.name);
       if (entry.isDirectory()) queue.push(full);
       else if (entry.name === target) return full;
     }
@@ -2553,14 +2927,14 @@ async function findServerBinary(dir, platform) {
   );
 }
 async function extractRelease(archivePath, destDir, platform) {
-  await fsp7.mkdir(destDir, { recursive: true });
+  await fsp9.mkdir(destDir, { recursive: true });
   const args = archivePath.endsWith(".zip") ? ["-xf", archivePath] : ["-xzf", archivePath];
   try {
     await execTar(args, destDir);
   } catch (err) {
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
-      `Could not extract ${path9.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
+      `Could not extract ${path10.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
       "Extract the archive manually and point CLEF_LLAMA_BIN at llama-server."
     );
   }
@@ -2570,7 +2944,7 @@ async function ensureLlamaRuntime(cfg, log) {
     const resolved = resolveLlamaServerBinary(cfg);
     if (resolved.source === "managed") {
       const platformDir = llamaRuntimeDir(pathsFor(cfg.clefHome).runtimeDir, process.platform, process.arch);
-      const manifest = readRuntimeManifest(path9.join(platformDir, "runtime-manifest.json"));
+      const manifest = readRuntimeManifest(path10.join(platformDir, "runtime-manifest.json"));
       return { ...resolved, releaseTag: manifest?.releaseTag ?? "unknown", freshInstall: false };
     }
     return { ...resolved, releaseTag: resolved.source, freshInstall: false };
@@ -2602,16 +2976,16 @@ async function downloadManagedLlama(cfg, log) {
   }
   const asset = pickAsset(release, platform, arch);
   log?.info("downloading llama.cpp runtime", { tag: release.tag_name, asset: asset.name });
-  const tagDir = path9.join(platformDir, release.tag_name);
-  await fsp7.mkdir(tagDir, { recursive: true });
-  const tmpArchive = path9.join(platformDir, `.download-${asset.name}`);
-  await fsp7.rm(tmpArchive, { force: true });
+  const tagDir = path10.join(platformDir, release.tag_name);
+  await fsp9.mkdir(tagDir, { recursive: true });
+  const tmpArchive = path10.join(platformDir, `.download-${asset.name}`);
+  await fsp9.rm(tmpArchive, { force: true });
   const result = await downloadFile(asset.browser_download_url, tmpArchive, { expectedSize: asset.size, attempts: 3 });
   await extractRelease(tmpArchive, tagDir, platform);
-  await fsp7.rm(tmpArchive, { force: true });
+  await fsp9.rm(tmpArchive, { force: true });
   const binaryPath = await findServerBinary(tagDir, platform);
-  if (platform !== "win32") await fsp7.chmod(binaryPath, 493);
-  await writeRuntimeManifest(path9.join(platformDir, "runtime-manifest.json"), {
+  if (platform !== "win32") await fsp9.chmod(binaryPath, 493);
+  await writeRuntimeManifest(path10.join(platformDir, "runtime-manifest.json"), {
     schemaVersion: 1,
     kind: "llama-cpp",
     releaseTag: release.tag_name,
@@ -2627,11 +3001,11 @@ async function removeManagedRuntime(cfg) {
   const { runtimeDir } = pathsFor(cfg.clefHome);
   const dir = llamaRuntimeDir(runtimeDir, process.platform, process.arch);
   try {
-    await fsp7.stat(dir);
+    await fsp9.stat(dir);
   } catch {
     return false;
   }
-  await fsp7.rm(dir, { recursive: true, force: true });
+  await fsp9.rm(dir, { recursive: true, force: true });
   return true;
 }
 
@@ -2639,7 +3013,7 @@ async function removeManagedRuntime(cfg) {
 init_prompt();
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 // src/cli/install.ts
 var OS_NAMES = {
@@ -2828,7 +3202,7 @@ async function runStatus() {
 
 // src/cli/uninstall.ts
 init_errors();
-import fsp9 from "fs/promises";
+import fsp11 from "fs/promises";
 init_prompt();
 async function runUninstall(opts) {
   const config = loadConfig();
@@ -2867,7 +3241,7 @@ async function runUninstall(opts) {
     return;
   }
   if (target) {
-    await fsp9.rm(target, { recursive: true, force: true });
+    await fsp11.rm(target, { recursive: true, force: true });
     console.log(`Removed: ${target}`);
   }
   if (opts.runtime) {
@@ -2894,6 +3268,24 @@ program.action(async () => {
     handleCliError(err);
   }
 });
+program.command("decide").description("One-shot decision (no MCP session): JSON in, strict JSON result out. For hooks, CI and scripts.").option("--state <source>", 'state: file path, "-" for stdin, or inline JSON/text').option("--questions <source>", 'questions map: file path, "-" for stdin, or inline JSON').option("--model <id>", "model to use (default: CLEF_MODEL or clef-flash)").option("--daemon", "route through a running `clef-mcp daemon` (falls back to a cold run when none is reachable)").action(async (opts) => {
+  try {
+    await runDecide(opts);
+    process.exit(0);
+  } catch (err) {
+    handleCliError(err);
+  }
+});
+program.command("daemon").description("Keep the model warm and answer decide requests on a local unix socket in CLEF_HOME (used by decide --daemon).").action(async () => {
+  try {
+    const config = loadConfig();
+    const log = createLogger(config.logLevel);
+    const daemon = startDaemon(config, log);
+    await daemon.ready;
+  } catch (err) {
+    handleCliError(err);
+  }
+});
 program.command("install").description("Detect the machine, download a Clef model + runtime, verify checksum and inference.").option("--model <id>", "model to install (default: clef-flash)").option("--quant <id>", "quantization override: Q4_K_M | Q8_0 | BF16").option("-y, --yes", "assume yes for all prompts (non-interactive)").option("--skip-runtime", "do not download/verify the llama.cpp runtime").option("--skip-probe", "skip the post-install inference verification").option("--runtime <id>", "inference runtime: llama-cpp (default) | mlx (Apple Silicon)").option("--setup", "also register the MCP server + agent skill in detected clients (same as running `clef-mcp setup`)").action(async (opts) => {
   try {
     await runInstall(opts);