@klhapp/skillmux 1.6.0 → 1.7.0

package/src/init.ts

@@ -357,15 +357,14 @@ export function applyInit(
   return manifest;
 }
 
-/** Verbatim from docs/sdd/skr-cli/think.md §3.3 — the shared instruction-stack paragraph. */
 export const DISCOVERY_PARAGRAPH =
   "Skills: only a curated core is loaded statically. Before improvising a " +
   "multi-step workflow, or when a task smells like a domain you have no loaded " +
   "skill for (career/resume, trading, SEO, i18n, design, one-off tooling), " +
-  "call `resolve_skill` with a one-line task description. `matched` → follow " +
-  "the returned SKILL.md. `ambiguous` → pick from the candidates and " +
-  "`fetch_skill`. `no_match` → proceed normally; don't force an unrelated " +
-  "skill.";
+  "call `resolve_skill` with a one-line task description. `resolve_skill` " +
+  "returns a ranked shortlist; inspect candidates, fetch one or more " +
+  "relevant skills with `fetch_skill`, or ignore all and proceed normally " +
+  "when none are useful.";
 
 export const MCP_REGISTRATION_SNIPPET = JSON.stringify(
   { mcpServers: { "skillmux": { command: "skillmux", args: ["serve"] } } },

package/src/metrics.ts

@@ -8,8 +8,7 @@ type MetricsDeploymentIdentity = Pick<
 
 export class MetricsRegistry {
   private requests = new Map<string, number>();
-  private outcomes = new Map<string, number>();
-  
+
   private buckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0];
   private latencyBuckets = new Array(this.buckets.length).fill(0);
   private latencyInf = 0;
@@ -34,10 +33,6 @@ export class MetricsRegistry {
     this.requests.set(method, (this.requests.get(method) || 0) + 1);
   }
 
-  recordResolveOutcome(outcome: string) {
-    this.outcomes.set(outcome, (this.outcomes.get(outcome) || 0) + 1);
-  }
-
   recordDegradation(stage: "embedding" | "reranker", reason: string) {
     const key = `${stage}:${reason}`;
     this.degradations.set(key, (this.degradations.get(key) || 0) + 1);
@@ -72,13 +67,6 @@ export class MetricsRegistry {
       lines.push(`skill_router_requests_total{method="${method}"} ${count}`);
     }
 
-    // Resolve outcomes total
-    lines.push("# HELP skill_router_resolve_outcomes_total Total count of resolve_skill query outcomes.");
-    lines.push("# TYPE skill_router_resolve_outcomes_total counter");
-    for (const [outcome, count] of this.outcomes) {
-      lines.push(`skill_router_resolve_outcomes_total{outcome="${outcome}"} ${count}`);
-    }
-
     // Latency histogram
     lines.push("# HELP skill_router_resolve_latency_seconds Latency histogram of resolve_skill executions.");
     lines.push("# TYPE skill_router_resolve_latency_seconds histogram");

package/src/router-core.ts

@@ -23,7 +23,6 @@ import {
   vectorTopK,
 } from "./db";
 import type { SkillRow } from "./db";
-import { decideResolveOutcome, type Decision } from "./decision";
 import type {
   RankedCandidate,
   RetrievalCapability,
@@ -54,7 +53,6 @@ function maxVaultMtime(vaultPath: string, localVaultPaths: string[]): number {
 
 export { buildAuditRow } from "./audit";
 export { loadConfig } from "./config";
-export { decideResolveOutcome } from "./decision";
 export type * from "./types";
 
 const NO_MATCH_MESSAGE =
@@ -370,87 +368,40 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
   const { config, db } = await getEnv();
   await syncVaultIfNeeded();
 
-  // Short-circuit: exact match on skill_id, title, or alias (First Principles #1)
-  const exactMatch = findExactMatch(db, input.query);
-  if (exactMatch) {
-    const delivery = await deliverSkill(db, config, exactMatch.skill_id);
-    const result: ResolveResult = {
-      outcome: "matched",
-      retrieval: "exact",
-      skill_id: exactMatch.skill_id,
-      title: delivery.title,
-      content_sha256: delivery.content_sha256,
-      score: 1.0,
-      margin: 1.0,
-      body: delivery.body,
-      files: delivery.files,
-    };
-    insertAudit(
-      db,
-      buildAuditRow({
-        id: 0,
-        ts: new Date().toISOString(),
-        query: input.query,
-        outcome: "matched",
-        retrieval: "exact",
-        candidates: [{ skill_id: exactMatch.skill_id, score: 1.0 }],
-        selected_skill_id: exactMatch.skill_id,
-        latency_ms: Math.round(performance.now() - t0),
-      }),
-    );
-    return result;
+  if (input.top_k !== undefined) {
+    if (!Number.isInteger(input.top_k) || input.top_k < 1) {
+      throw new Error(`Invalid top_k: ${input.top_k} must be a positive integer`);
+    }
+    if (input.top_k > config.output.max_top_k) {
+      throw new Error(
+        `Invalid top_k: ${input.top_k} exceeds max_top_k of ${config.output.max_top_k}`,
+      );
+    }
   }
 
+  const effectiveTopK = input.top_k ?? config.output.top_k;
   const retrievalResult = await retrieveAndRerank(input);
   const { retrieval, candidates: rankedCandidates } = retrievalResult;
 
-  const decision = decideRetrievalResult(config, retrievalResult);
-
-  let result: ResolveResult;
-  if (decision.outcome === "matched") {
-    const delivery = await deliverSkill(db, config, decision.skill_id);
-    result = {
-      outcome: "matched",
-      retrieval: "reranked",
-      ...(retrievalResult.degraded_from
-        ? {
-            degraded_from: retrievalResult.degraded_from,
-            degradation_reason: retrievalResult.degradation_reason,
-          }
-        : {}),
-      skill_id: decision.skill_id,
-      title: delivery.title,
-      content_sha256: delivery.content_sha256,
-      score: decision.score,
-      margin: decision.margin,
-      body: delivery.body,
-      files: delivery.files,
-    };
-  } else if (decision.outcome === "ambiguous") {
-    result = {
-      outcome: "ambiguous",
-      retrieval,
-      ...(retrievalResult.degraded_from
-        ? {
-            degraded_from: retrievalResult.degraded_from,
-            degradation_reason: retrievalResult.degradation_reason,
-          }
-        : {}),
-      candidates: decision.candidates.map(({ score: _score, ...candidate }) => candidate),
-    };
-  } else {
-    result = {
-      outcome: "no_match",
-      retrieval,
-      ...(retrievalResult.degraded_from
-        ? {
-            degraded_from: retrievalResult.degraded_from,
-            degradation_reason: retrievalResult.degradation_reason,
-          }
-        : {}),
-      message: NO_MATCH_MESSAGE,
-    };
-  }
+  const candidates: RankedCandidate[] = rankedCandidates
+    .slice(0, effectiveTopK)
+    .map((c, index) => ({
+      rank: index + 1,
+      skill_id: c.skill_id,
+      description: c.description,
+      score: c.score,
+    }));
+
+  const result: ResolveResult = {
+    retrieval,
+    ...(retrievalResult.degraded_from
+      ? {
+          degraded_from: retrievalResult.degraded_from,
+          degradation_reason: retrievalResult.degradation_reason,
+        }
+      : {}),
+    candidates,
+  };
 
   insertAudit(
     db,
@@ -458,12 +409,10 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
       id: 0, // assigned by SQLite
       ts: new Date().toISOString(),
       query: input.query,
-      outcome: result.outcome,
       retrieval,
       degraded_from: retrievalResult.degraded_from ?? null,
       degradation_reason: retrievalResult.degradation_reason ?? null,
-      candidates: rankedCandidates.map((c) => ({ skill_id: c.skill_id, score: c.score })),
-      selected_skill_id: result.outcome === "matched" ? result.skill_id : null,
+      candidates: candidates.map((c) => ({ skill_id: c.skill_id, score: c.score })),
       latency_ms: Math.round(performance.now() - t0),
     }),
   );
@@ -471,11 +420,18 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
   return result;
 }
 
+export interface RawCandidate {
+  skill_id: string;
+  title: string;
+  description: string;
+  score: number | null;
+}
+
 export interface RetrievalResult {
   retrieval: Exclude<RetrievalCapability, "exact">;
   degraded_from?: "reranked" | "hybrid";
   degradation_reason?: DegradationReason;
-  candidates: RankedCandidate[];
+  candidates: RawCandidate[];
   trace: Array<{
     skill_id: string;
     lexical_rank: number | null;
@@ -484,18 +440,6 @@ export interface RetrievalResult {
   }>;
 }
 
-export function decideRetrievalResult(config: Config, result: RetrievalResult): Decision {
-  const candidateLimit = config.output?.ambiguous_candidate_limit ?? config.thresholds?.candidate_limit ?? 5;
-  const thresholds = result.retrieval === "reranked" && config.inference.mode === "remote"
-    ? { candidate_limit: candidateLimit, ...config.inference.thresholds }
-    : { ...config.thresholds, candidate_limit: candidateLimit };
-  return decideResolveOutcome({
-    reranked: result.retrieval === "reranked",
-    candidates: result.candidates,
-    thresholds,
-  });
-}
-
 export function classifyInferenceError(
   stage: "embedding" | "reranker",
   error: unknown,
@@ -530,64 +474,26 @@ export function classifyInferenceError(
   return stage === "embedding" ? "embedding_unavailable" : "reranker_unavailable";
 }
 
-export interface StageTiming {
-  embedding_ms: number;
-  lexical_ms: number;
-  vector_ms: number;
-  reranker_ms: number;
-}
-
-export interface RetrieveSnapshotOptions {
-  onTiming?: (timing: StageTiming) => void;
-}
-
 /**
- * Retrieve the full fused candidate set and rerank it once without applying
- * decision thresholds, synchronizing the vault before reading the index.
+ * Retrieve the full fused candidate set, optionally rerank it, and synchronize
+ * the vault before reading the index.
  */
 export async function retrieveAndRerank(
   input: ResolveSkillInput,
 ): Promise<RetrievalResult> {
   await syncVaultIfNeeded();
-  return retrieveAndRerankSnapshot(input);
-}
-
-/**
- * Retrieve candidates against an already-synchronized index snapshot without
- * triggering syncVaultIfNeeded(). Calibration uses this to avoid observing the
- * policy it is trying to replace while keeping one corpus for the whole run.
- */
-export async function retrieveAndRerankSnapshot(
-  input: ResolveSkillInput,
-  options?: RetrieveSnapshotOptions,
-): Promise<RetrievalResult> {
   const { config, db } = await getEnv();
   const clients = getClients();
-  const measureTiming = options?.onTiming !== undefined;
 
-  let embedding_ms = 0;
-  let lexical_ms = 0;
-  let vector_ms = 0;
-  let reranker_ms = 0;
-
-  const tEmbed0 = measureTiming ? performance.now() : 0;
   const embedPromise =
     !input.forceLexical && clients.embed
       ? clients.embed([input.query]).then(
-        (res) => {
-          if (measureTiming) embedding_ms = Math.max(0, performance.now() - tEmbed0);
-          return res;
-        },
-        (err) => {
-          if (measureTiming) embedding_ms = Math.max(0, performance.now() - tEmbed0);
-          return { error: err };
-        },
+        (res) => res,
+        (err) => ({ error: err }),
       )
       : null;
 
-  const tLex0 = measureTiming ? performance.now() : 0;
   const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
-  if (measureTiming) lexical_ms = Math.max(0, performance.now() - tLex0);
   const lexicalRanks = new Map(lexical.map((row, index) => [row.skill_id, index + 1]));
 
   let retrieval: RetrievalResult["retrieval"] = "lexical";
@@ -611,17 +517,14 @@ export async function retrieveAndRerankSnapshot(
         }),
       );
     } else {
-      const tVec0 = measureTiming ? performance.now() : 0;
       try {
         const queryVec = (embedRes as Float32Array[])[0];
         if (!queryVec) throw new Error("Embedding client returned no query vector.");
         const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
-        if (measureTiming) vector_ms = Math.max(0, performance.now() - tVec0);
         rows = reciprocalRankFusion(lexical, nearest);
         fusedRows = rows;
         retrieval = "hybrid";
       } catch (embedError) {
-        if (measureTiming) vector_ms = Math.max(0, performance.now() - tVec0);
         retrieval = "lexical";
         degraded_from = clients.rerank ? "reranked" : "hybrid";
         degradation_reason = classifyInferenceError("embedding", embedError);
@@ -641,17 +544,14 @@ export async function retrieveAndRerankSnapshot(
   if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
     const kRerank = config.recall.k_rerank ?? 10;
     const rerankCandidates = rows.slice(0, kRerank);
-    const tRerank0 = measureTiming ? performance.now() : 0;
     try {
       scores = await clients.rerank(
         input.query,
         rerankCandidates.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
       );
-      if (measureTiming) reranker_ms = Math.max(0, performance.now() - tRerank0);
       retrieval = "reranked";
       rows = rerankCandidates;
     } catch (rerankError) {
-      if (measureTiming) reranker_ms = Math.max(0, performance.now() - tRerank0);
       scores = null;
       degraded_from = "reranked";
       degradation_reason = classifyInferenceError("reranker", rerankError);
@@ -679,13 +579,6 @@ export async function retrieveAndRerankSnapshot(
     : new Map<string, number>();
   const traceRows = fusedRows ?? rows;
 
-  options?.onTiming?.({
-    embedding_ms,
-    lexical_ms,
-    vector_ms,
-    reranker_ms,
-  });
-
   return {
     retrieval,
     ...(degraded_from ? { degraded_from, degradation_reason } : {}),

package/src/server.ts

@@ -74,30 +74,29 @@ export function createMcpServer(): McpServer {
     "resolve_skill",
     {
       description:
-        "Route a natural-language task description to the most relevant skill in the vault. " +
-        "Returns outcome matched (skill delivered inline), ambiguous (shortlist — pick one, then call fetch_skill), " +
-        "or no_match (proceed under your normal workflow).",
-      inputSchema: { query: z.string().min(1) },
+        "Route a natural-language task description to candidate skills in the vault. " +
+        "Returns a ranked shortlist of candidates. Use fetch_skill to retrieve a candidate's complete instructions.",
+      inputSchema: {
+        query: z.string().min(1).describe("Natural-language task or prompt description to route."),
+        top_k: z
+          .number()
+          .int()
+          .min(1)
+          .optional()
+          .describe("Optional maximum number of ranked candidates to return (subject to server max_top_k limit)."),
+      },
     },
-    async ({ query }) => {
+    async ({ query, top_k }) => {
       const startTime = performance.now();
       try {
-        const result = await resolveSkill({ query });
+        const result = await resolveSkill({ query, top_k });
         const duration = (performance.now() - startTime) / 1000;
         metricsRegistry.recordResolveLatencySeconds(duration);
-        metricsRegistry.recordResolveOutcome(result.outcome);
         if (result.degradation_reason) {
           const stage = result.degradation_reason.startsWith("embedding_") ? "embedding" : "reranker";
           metricsRegistry.recordDegradation(stage, result.degradation_reason);
         }
 
-        if (result.outcome === "matched") {
-          const { body, ...meta } = result;
-          return {
-            content: [{ type: "text" as const, text: body }],
-            structuredContent: { ...meta },
-          };
-        }
         return {
           content: [{ type: "text" as const, text: JSON.stringify(result) }],
           structuredContent: { ...result },
@@ -394,7 +393,6 @@ export async function startServer(opts?: {
               JSON.stringify({
                 config_read: true,
                 config_write: !isExternallyManaged,
-                calibration: false,
                 persistence: isExternallyManaged
                   ? "externally_managed"
                   : "writable",
@@ -481,18 +479,6 @@ export async function startServer(opts?: {
             });
           }
 
-          if (url.pathname.startsWith("/admin/v1/calibrations")) {
-            return new Response(
-              JSON.stringify({
-                error: "not_implemented",
-                message:
-                  "Remote calibration is not implemented in this release. " +
-                  "Run `skillmux calibrate` against a local target.",
-              }),
-              { status: 501, headers },
-            );
-          }
-
           return new Response("Not Found", { status: 404, headers });
         }