@klhapp/skillmux 1.0.1 → 1.1.0

package/src/decision.ts

@@ -23,7 +23,10 @@ export function decideResolveOutcome({ reranked, candidates, thresholds }: Decis
     || thresholds.match_margin === undefined
     || thresholds.candidate_floor === undefined
   ) {
-    throw new Error("Reranked decisions require calibrated thresholds.");
+    return {
+      outcome: "ambiguous",
+      candidates: candidates.slice(0, thresholds.candidate_limit),
+    };
   }
   const { match_score, match_margin, candidate_floor } = thresholds;
 

package/src/doctor.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { createClients } from "./clients";
+import { createClients, RemoteInferenceError } from "./clients";
 import { embeddingDimension, expandHome } from "./config";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
@@ -10,6 +10,7 @@ export interface DoctorCheck {
   name: string;
   ok: boolean;
   detail: string;
+  failure_kind?: "configuration" | "availability" | "protocol" | "unexpected";
 }
 
 export interface DoctorReport {
@@ -99,8 +100,13 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     }
   }
 
+  const inferenceFailure = (error: unknown): Pick<DoctorCheck, "detail" | "failure_kind"> =>
+    error instanceof RemoteInferenceError
+      ? { detail: error.message, failure_kind: error.kind }
+      : { detail: "unexpected inference failure", failure_kind: "unexpected" };
+
+  const clients = createClients(config);
   try {
-    const clients = createClients(config);
     const vectors = await clients.embed(["skill router diagnostic"]);
     const actualDimension = vectors[0]?.length ?? 0;
     checks.push({
@@ -108,14 +114,19 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
       ok: actualDimension === embeddingDimension(config),
       detail: `dimension ${actualDimension}`,
     });
-    if (clients.rerank) {
+  } catch (error) {
+    checks.push({ name: "embedding", ok: false, ...inferenceFailure(error) });
+  }
+
+  if (clients.rerank) {
+    try {
       const scores = await clients.rerank("skill router diagnostic", [
         { skill_id: "doctor", text: "Routes a task to an appropriate skill." },
       ]);
       checks.push({ name: "reranker", ok: scores.length === 1 && Number.isFinite(scores[0]), detail: "one finite score" });
+    } catch (error) {
+      checks.push({ name: "reranker", ok: false, ...inferenceFailure(error) });
     }
-  } catch (error) {
-    checks.push({ name: "inference", ok: false, detail: String(error) });
   }
 
   const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);

package/src/eval.ts

@@ -78,7 +78,8 @@ export async function evalVault(cases = loadEvalCases()): Promise<EvalReport> {
   const hybridRankings: string[][] = [];
   for (const evalCase of cases) {
     const lexical = ftsSearch(db, evalCase.query, config.recall.k_lexical);
-    const vector = (await clients.embed([evalCase.query]))[0]!;
+    const vector = (await clients.embed([evalCase.query]))[0];
+    if (!vector) throw new Error("Embedding client returned no query vector.");
     const semantic = vectorTopK(db, vector, config.recall.k_vector);
     lexicalRankings.push(lexical.map((row) => row.skill_id));
     hybridRankings.push(reciprocalRankFusion<SkillRow>(lexical, semantic).map((row) => row.skill_id));

package/src/router-core.ts

@@ -3,6 +3,7 @@ import { watch } from "node:fs";
 import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
+import { RemoteInferenceError } from "./clients";
 import {
   deleteSkill,
   findExactMatch,
@@ -269,12 +270,22 @@ export async function backfillEmbeddings(): Promise<number> {
     const chunk = pending.slice(i, i + BATCH_SIZE);
     try {
       const vectors = await clients.embed(chunk.map(rerankText));
-      chunk.forEach((row, j) => {
-        upsertVector(db, row.skill_id, row.content_sha256, fingerprint, vectors[j]!);
-      });
+      db.transaction(() => {
+        chunk.forEach((row, j) => {
+          const vector = vectors[j];
+          if (!vector) throw new Error("Embedding client returned an incomplete batch.");
+          upsertVector(db, row.skill_id, row.content_sha256, fingerprint, vector);
+        });
+      })();
       count += chunk.length;
     } catch (err) {
-      if (i === 0) throw err;
+      if (
+        i === 0 ||
+        (err instanceof RemoteInferenceError &&
+          (err.kind === "configuration" || err.kind === "protocol"))
+      ) {
+        throw err;
+      }
       break;
     }
   }
@@ -384,44 +395,7 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
     return result;
   }
 
-  const clients = getClients();
-
-  const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
-
-  let retrieval: RetrievalCapability = "lexical";
-  let rows = lexical;
-  if (!input.forceLexical) {
-    try {
-      const queryVec = (await clients.embed([input.query]))[0]!;
-      const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
-      rows = reciprocalRankFusion(lexical, nearest);
-      retrieval = "hybrid";
-    } catch {
-      retrieval = "lexical";
-    }
-  }
-
-  let scores: number[] | null = null;
-  if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
-    try {
-      scores = await clients.rerank(
-        input.query,
-        rows.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
-      );
-      retrieval = "reranked";
-    } catch {
-      scores = null;
-    }
-  }
-
-  const rankedCandidates: RankedCandidate[] = rows
-    .map((r, i) => ({
-      skill_id: r.skill_id,
-      title: r.title,
-      description: r.description,
-      score: scores?.[i] ?? null,
-    }))
-    .sort((a, b) => scores === null ? 0 : (b.score ?? -Infinity) - (a.score ?? -Infinity));
+  const { retrieval, candidates: rankedCandidates } = await retrieveAndRerank(input);
 
   const decisionThresholds = retrieval === "reranked" && config.inference.mode === "remote"
     ? { candidate_limit: config.thresholds.candidate_limit, ...config.inference.thresholds }
@@ -473,6 +447,63 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
   return result;
 }
 
+export interface RetrievalResult {
+  retrieval: Exclude<RetrievalCapability, "exact">;
+  candidates: RankedCandidate[];
+}
+
+/**
+ * Retrieve the full fused candidate set and rerank it once without applying
+ * decision thresholds. Calibration uses this to avoid observing the policy it
+ * is trying to replace.
+ */
+export async function retrieveAndRerank(
+  input: ResolveSkillInput,
+): Promise<RetrievalResult> {
+  const { config, db } = await getEnv();
+  await syncVaultIfNeeded();
+  const clients = getClients();
+  const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
+
+  let retrieval: RetrievalResult["retrieval"] = "lexical";
+  let rows = lexical;
+  if (!input.forceLexical) {
+    try {
+      const queryVec = (await clients.embed([input.query]))[0];
+      if (!queryVec) throw new Error("Embedding client returned no query vector.");
+      const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
+      rows = reciprocalRankFusion(lexical, nearest);
+      retrieval = "hybrid";
+    } catch {
+      retrieval = "lexical";
+    }
+  }
+
+  let scores: number[] | null = null;
+  if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
+    try {
+      scores = await clients.rerank(
+        input.query,
+        rows.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
+      );
+      retrieval = "reranked";
+    } catch {
+      scores = null;
+    }
+  }
+
+  const candidates = rows
+    .map((r, i) => ({
+      skill_id: r.skill_id,
+      title: r.title,
+      description: r.description,
+      score: scores?.[i] ?? null,
+    }))
+    .sort((a, b) => scores === null ? 0 : (b.score ?? -Infinity) - (a.score ?? -Infinity));
+
+  return { retrieval, candidates };
+}
+
 export async function fetchSkill(input: FetchSkillInput): Promise<FetchSkillResult> {
   const { config, db } = await getEnv();
   await syncVaultIfNeeded();

package/src/server.ts

@@ -4,7 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { createClients } from "./clients";
-import { loadConfig, resolveConfigPath } from "./config";
+import { expandHome, loadConfig, rerankerFingerprint, resolveConfigPath } from "./config";
 import { ConfigWatcher, type ReloadStatus } from "./config-watcher";
 import { RuntimeSnapshotManager } from "./snapshot";
 import {
@@ -513,13 +513,16 @@ export async function startServer(opts?: {
                   JSON.stringify({ error: "Calibration run not found" }),
                   { status: 404, headers },
                 );
-              const { DEFAULT_CONFIG_PATH, expandHome } =
-                await import("./config");
+              const active = snapshots.acquire();
+              const currentRerankerFingerprint = rerankerFingerprint(
+                active.snapshot.config,
+              );
+              active.release();
               await applyCalibrationRun(
                 db,
                 runId,
-                expandHome(DEFAULT_CONFIG_PATH),
-                {},
+                expandHome(configPath),
+                { currentRerankerFingerprint },
               );
               return new Response(JSON.stringify({ ok: true, run_id: runId }), {
                 status: 200,

package/src/types.ts

@@ -54,15 +54,15 @@ export interface LocalInferenceConfig {
 
 export interface RemoteEmbeddingConfig {
   provider: "openai";
-  base_url: string;
+  endpoint: string;
   model: string;
   dimension: number;
   api_key_env?: string;
 }
 
 export interface RemoteRerankerConfig {
-  provider: "infinity";
-  base_url: string;
+  adapter: "jina-v1" | "bifrost-v1";
+  endpoint: string;
   model: string;
   api_key_env?: string;
 }