@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/src/relevance.ts

@@ -0,0 +1,138 @@
+import type { ContextItem } from "./context.ts";
+
+/**
+ * Deterministic lexical relevance (BM25) for context ranking and recall.
+ *
+ * No model, no clock, no randomness: the same query and documents always
+ * produce bit-identical scores, so arbiter packets and recall results stay
+ * reproducible and testable.
+ */
+
+/** Words that carry no task signal. Dropped before scoring. */
+export const RELEVANCE_STOPWORDS: ReadonlySet<string> = Object.freeze(new Set([
+  "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "can", "could",
+  "did", "do", "does", "for", "from", "had", "has", "have", "how", "if", "in",
+  "into", "is", "it", "its", "of", "on", "or", "our", "should", "so", "than",
+  "that", "the", "their", "them", "then", "there", "these", "they", "this",
+  "those", "to", "was", "we", "were", "what", "when", "where", "which", "while",
+  "who", "why", "will", "with", "would", "you", "your",
+]));
+
+/** BM25 term-frequency saturation. */
+export const RELEVANCE_K1 = 1.2;
+/** BM25 document-length normalization. */
+export const RELEVANCE_B = 0.75;
+
+const MIN_TOKEN_CHARS = 2;
+const MAX_TOKEN_CHARS = 64;
+
+function foldPlural(token: string): string {
+  if (/^\p{N}+$/u.test(token)) return token;
+  if (token.length > 4 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("sses")) return token.slice(0, -2);
+  if (
+    token.length > 3
+    && token.endsWith("s")
+    && !token.endsWith("ss")
+    && !token.endsWith("us")
+    && !token.endsWith("is")
+  ) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
+
+/** NFKC-normalized, lowercased, stopword-free, plural-folded tokens in text
+ * order, duplicates kept. */
+export function relevanceTokens(text: string): string[] {
+  const tokens: string[] = [];
+  for (const raw of text.normalize("NFKC").toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (raw.length < MIN_TOKEN_CHARS || raw.length > MAX_TOKEN_CHARS) continue;
+    if (RELEVANCE_STOPWORDS.has(raw)) continue;
+    tokens.push(foldPlural(raw));
+  }
+  return tokens;
+}
+
+/** Index-aligned BM25 scores of each document against the query. Terms are
+ * summed in first-occurrence query order so the float result is bit-stable. */
+export function scoreRelevance(query: string, documents: readonly string[]): number[] {
+  const scores = documents.map(() => 0);
+  const terms = [...new Set(relevanceTokens(query))];
+  if (terms.length === 0 || documents.length === 0) return scores;
+
+  const indexed = documents.map((document) => {
+    const tokens = relevanceTokens(document);
+    const frequencies = new Map<string, number>();
+    for (const token of tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    return { length: tokens.length, frequencies };
+  });
+  const count = indexed.length;
+  let totalLength = 0;
+  for (const document of indexed) totalLength += document.length;
+  const averageLength = totalLength > 0 ? totalLength / count : 1;
+
+  const inverseFrequency = new Map<string, number>();
+  for (const term of terms) {
+    let documentFrequency = 0;
+    for (const document of indexed) {
+      if (document.frequencies.has(term)) documentFrequency += 1;
+    }
+    inverseFrequency.set(term, Math.log(1 + (count - documentFrequency + 0.5) / (documentFrequency + 0.5)));
+  }
+
+  indexed.forEach((document, index) => {
+    let score = 0;
+    for (const term of terms) {
+      const frequency = document.frequencies.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const lengthNorm = 1 - RELEVANCE_B + RELEVANCE_B * (document.length / averageLength);
+      score += inverseFrequency.get(term)! * ((frequency * (RELEVANCE_K1 + 1)) / (frequency + RELEVANCE_K1 * lengthNorm));
+    }
+    scores[index] = score;
+  });
+  return scores;
+}
+
+/** Relevance rounded to three decimals for audits and responses. */
+export function roundRelevance(score: number): number {
+  return Math.round(score * 1000) / 1000;
+}
+
+/** The text a context item is ranked on: its summary plus its state key.
+ * Kind, id and sourceRef are excluded. */
+export function contextItemRelevanceText(item: ContextItem): string {
+  return item.stateKey !== undefined ? `${item.summary} ${item.stateKey}` : item.summary;
+}
+
+/** Locale-independent code-unit order for identifiers. */
+export function compareCodeUnitIds(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export interface RankedRecallItem {
+  item: ContextItem;
+  relevance: number;
+}
+
+/** Rank recall candidates: exact-phrase hits first, then BM25 any-token hits,
+ * then id. An empty query is a phrase hit for every item (id order). Items
+ * that neither contain the phrase nor share a token are dropped. */
+export function rankRecall(query: string, items: readonly ContextItem[], limit: number): RankedRecallItem[] {
+  const needle = query.toLowerCase();
+  const scores = scoreRelevance(query, items.map(contextItemRelevanceText));
+  const ranked: { item: ContextItem; score: number; phraseHit: boolean }[] = [];
+  items.forEach((item, index) => {
+    const score = scores[index] ?? 0;
+    const phraseHit = needle === ""
+      || item.summary.toLowerCase().includes(needle)
+      || (item.stateKey ?? "").toLowerCase().includes(needle);
+    if (phraseHit || score > 0) ranked.push({ item, score, phraseHit });
+  });
+  ranked.sort((left, right) =>
+    (right.phraseHit ? 1 : 0) - (left.phraseHit ? 1 : 0)
+    || right.score - left.score
+    || compareCodeUnitIds(left.item.id, right.item.id),
+  );
+  return ranked.slice(0, limit).map(({ item, score }) => ({ item, relevance: roundRelevance(score) }));
+}

package/plugins/kxm/src/retrospective.ts

@@ -5,6 +5,7 @@ import {
   canonicalWorkflowEvidenceKey,
   journalPromotionState,
   normalizeVerifiedWorkflowEvidence,
+  rankImprovementSignals,
   type WorkflowJournalEntry,
   type WorkflowRun,
 } from "./workflow.ts";
@@ -248,12 +249,14 @@ export function buildRetrospective(
   const byCategory: Record<string, number> = {};
   const byArea: Record<string, number> = {};
   const byClass: Record<string, number> = {};
+  const byErrorClass: Record<string, number> = {};
   for (const entry of entries) {
     increment(byCategory, entry.category);
     increment(byArea, entry.area);
     increment(byClass, classFromEvidence(entry.evidence));
+    if (entry.category === "error") increment(byErrorClass, classFromEvidence(entry.evidence));
   }
-  const recurringErrorClasses = Object.entries(byClass)
+  const recurringErrorClasses = Object.entries(byErrorClass)
     .map(([errorClass, count]) => ({ class: errorClass, count }))
     .sort((left, right) => right.count - left.count || left.class.localeCompare(right.class));
   const resolvedContradictions = new Set(entries.filter((entry) => entry.category === "decision" || entry.category === "lesson").flatMap((entry) => entry.relatedEntryIds));
@@ -263,15 +266,18 @@ export function buildRetrospective(
   const decisions = entries
     .filter((entry) => entry.category === "decision")
     .map((entry) => ({ id: entry.id, summary: entry.summary, area: entry.area }));
-  const proposedImprovements = entries
-    .filter((entry) => entry.category === "lesson" || entry.category === "error")
-    .slice(0, 12)
-    .map((entry) => ({
-      area: entry.area,
-      summary: entry.summary,
-      successMeasure: "reduce recurrence of this class in the next comparable run",
-      status: "proposed" as const,
-    }));
+  // Ranked, merged error and lesson signals over this run's raw entries. The
+  // category filter runs before the limit so up to 12 of them survive.
+  const proposedImprovements = rankImprovementSignals(
+    journal.filter((entry) => entry.runId === run.id && (entry.category === "error" || entry.category === "lesson")),
+    new Map([[run.id, run]]),
+    12,
+  ).map((signal) => ({
+    area: signal.area,
+    summary: signal.summary,
+    successMeasure: redactSecrets(`no recurrence of ${signal.key} in the next ${run.definitionId} run`),
+    status: "proposed" as const,
+  }));
   const evidenceAudit = buildEvidenceAudit(run);
   const degradedStageIds = run.stages
     .filter((stage) => stage.degraded)

package/plugins/kxm/src/runtime-service.ts

@@ -117,7 +117,7 @@ function collectMemoryFiles(dir: string, baseDir: string, ignoreSubdirs: Set<str
  * the promoted-state snapshot.
  */
 export function computeKxmMemoryRevision(
-  bundle: KxmProjectBundle,
+  bundle: Pick<KxmProjectBundle, "projectRoot">,
   options: KxmMemoryRevisionOptions = {},
 ): string {
   const hash = createHash("sha256");
@@ -248,6 +248,11 @@ export interface KxmRuntimeContext {
    * freeze a budget by supplying a stale clock.
    */
   readonly budgetClock?: () => string;
+  /**
+   * Optional structured logger (the Runtime supervisor's). The engine writes
+   * metadata-only lines here, ids and counts, never task or memory text.
+   */
+  readonly logger?: (entry: Record<string, unknown>) => void;
 }
 
 const closedRuntimeContexts = new WeakSet<KxmRuntimeContext>();
@@ -286,6 +291,7 @@ export function openKxmRuntimeContext(
     now?: string;
     homeRuntimeId: string;
     budgetClock?: () => string;
+    logger?: (entry: Record<string, unknown>) => void;
   },
 ): KxmRuntimeContext {
   const paths = kxmRuntimePaths(options.stateRoot !== undefined ? { stateRoot: options.stateRoot } : {});
@@ -310,6 +316,7 @@ export function openKxmRuntimeContext(
       eventStore,
       configRevision: bundle.configRevision,
       ...(options.budgetClock ? { budgetClock: options.budgetClock } : {}),
+      ...(options.logger ? { logger: options.logger } : {}),
     };
   } catch (error) {
     registry.close();

package/plugins/kxm/src/runtime-supervisor.ts

@@ -683,7 +683,7 @@ async function startKxmRuntimeSupervisorInner(
     const key = projectRuntimeKey(projectRoot);
     const existing = contexts.get(key);
     if (existing) return existing;
-    const context = openKxmRuntimeContext(projectRoot, { homeRuntimeId: activeRuntimeId, stateRoot: paths.stateRoot });
+    const context = openKxmRuntimeContext(projectRoot, { homeRuntimeId: activeRuntimeId, stateRoot: paths.stateRoot, logger });
     registerSyncCredentials(context);
     contexts.set(key, context);
     return context;
@@ -1315,7 +1315,21 @@ export async function kxmRuntimeRequest(
   if (!response.ok) {
     const code = typeof payload.error === "string" ? payload.error : "runtime_request_failed";
     const message = typeof payload.message === "string" ? payload.message : `runtime request failed with HTTP ${response.status}`;
-    throw runtimeError(code, path, message);
+    throw runtimeError(code, path, `${message}${handoffSuffix(payload.handoff)}`);
   }
   return payload;
 }
+
+const HANDOFF_TEXT_MAX = 200;
+
+/** Why the Runtime handed a run off, from a `run_handoff_required` body: the
+ * reason, field and detail, each capped so a refusal stays one readable line. */
+function handoffSuffix(handoff: unknown): string {
+  if (!handoff || typeof handoff !== "object" || Array.isArray(handoff)) return "";
+  const parts: string[] = [];
+  for (const key of ["reason", "field", "detail"] as const) {
+    const value = (handoff as Record<string, unknown>)[key];
+    if (typeof value === "string" && value.length > 0) parts.push(`${key} ${value.slice(0, HANDOFF_TEXT_MAX)}`);
+  }
+  return parts.length > 0 ? ` (handoff ${parts.join("; ")})` : "";
+}

package/plugins/kxm/src/session-token-hint.ts

@@ -0,0 +1,17 @@
+/** User-directed fix for a `session_token_invalid` tool-policy denial.
+ *
+ * `enforceToolPolicy` (commands.ts) returns that error from three places: an
+ * invalid `KXM_SESSION_TOKEN` in the environment (detail starts with
+ * `KXM_SESSION_TOKEN`), and an unreadable or malformed/expired session token
+ * file on disk. The Claude SessionStart hook and the MCP server both use this
+ * text, so a session sees one explanation. Neither text prints or reissues a
+ * token: `kxm session token --issue` and bare `kxm session token` print one. */
+
+const ENV_TEXT = "KXM_SESSION_TOKEN in the environment Claude Code was launched from is malformed or expired, so every kxm_* tool fails with tool_policy_denied. Ask the user to unset or replace KXM_SESSION_TOKEN in the environment Claude Code was launched from, then restart Claude Code.";
+
+const DISK_TEXT = "The KXM session token file on this machine is expired, malformed or unreadable, so every kxm_* tool fails with tool_policy_denied. Ask the user to run `kxm session token --clear` in their own terminal. `kxm session token --status` reports No active session token found for an expired file even though the file still blocks tools. The kxm plugin no longer refreshes that 24-hour token.";
+
+export function sessionTokenFixHint(policy: { error?: string | undefined; detail?: string | undefined }): string | undefined {
+  if (policy.error !== "session_token_invalid") return undefined;
+  return policy.detail?.startsWith("KXM_SESSION_TOKEN") ? ENV_TEXT : DISK_TEXT;
+}

package/plugins/kxm/src/suggest.ts

@@ -32,49 +32,49 @@ const WORKFLOW_PATTERNS: WorkflowPattern[] = [
     id: "software-engineering/bug-fix",
     area: "software-engineering",
     keywords: ["fix", "bug", "flaky", "failure", "timeout", "error", "repro", "crash", "broken", "hang"],
-    skills: ["troubleshooting", "kxm", "kxm-query", "kxm-work"],
+    skills: ["kxm-workflow", "kxm-runs", "kxm-context-memory"],
     defaultCommand: (p) => `kxm run software-engineering/bug-fix "${p}"`,
   },
   {
     id: "software-engineering/feature-implementation",
     area: "software-engineering",
     keywords: ["feature", "implement", "add", "build", "create", "develop", "support", "endpoint", "ui", "tui"],
-    skills: ["modern-web-guidance", "kxm", "kxm-mind", "kxm-query"],
+    skills: ["kxm-workflow", "kxm-peer", "kxm-context-memory"],
     defaultCommand: (p) => `kxm run software-engineering/feature-implementation "${p}"`,
   },
   {
     id: "software-engineering/refactoring",
     area: "software-engineering",
     keywords: ["refactor", "cleanup", "reorganize", "modularize", "deduplicate", "split", "simplify", "deprecate"],
-    skills: ["kxm", "kxm-mind", "kxm-query"],
+    skills: ["kxm-workflow", "kxm-runs"],
     defaultCommand: (p) => `kxm run software-engineering/refactoring "${p}"`,
   },
   {
     id: "security-reliability/vulnerability-remediation",
     area: "security-reliability",
     keywords: ["cve", "vulnerability", "security", "exploit", "sanitize", "leak", "secret", "injection", "redact", "auth"],
-    skills: ["kxm", "kxm-protocol", "kxm-triage"],
+    skills: ["kxm-workflow", "kxm-definitions"],
     defaultCommand: (p) => `kxm run security-reliability/vulnerability-remediation "${p}"`,
   },
   {
     id: "security-reliability/reliability-hardening",
     area: "security-reliability",
     keywords: ["idempotency", "retry", "circuit-breaker", "cas", "lock", "concurrency", "deadlock", "race", "crash-recovery"],
-    skills: ["kxm", "kxm-protocol"],
+    skills: ["kxm-workflow", "kxm-peer"],
     defaultCommand: (p) => `kxm run security-reliability/reliability-hardening "${p}"`,
   },
   {
     id: "data-analytics/pipeline-migration",
     area: "data-analytics",
     keywords: ["database", "sqlite", "migration", "pipeline", "schema", "transform", "table", "wal", "foreign", "cascading"],
-    skills: ["kxm", "kxm-query"],
+    skills: ["kxm-runs", "kxm-context-memory"],
     defaultCommand: (p) => `kxm run data-analytics/pipeline-migration "${p}"`,
   },
   {
     id: "research-strategy/architecture-spike",
     area: "research-strategy",
     keywords: ["spike", "investigate", "prototype", "research", "feasibility", "benchmark", "explore", "evaluate"],
-    skills: ["kxm-session", "kxm-mind", "kxm-query", "kxm-insights"],
+    skills: ["kxm-session", "kxm-context-memory", "kxm-routing-improve"],
     defaultCommand: (p) => `kxm run research-strategy/architecture-spike "${p}"`,
   },
 ];

package/plugins/kxm/src/workflow-manager.ts

@@ -18,10 +18,40 @@ export interface WorkflowDefSummary {
   roles: string[];
 }
 
+// Fresh objects per use: YAML stringify turns a repeated object into an
+// anchor and alias, which the restricted project loader refuses.
+const completed = () => ({ target: "$terminal", terminalStatus: "completed" });
+const failed = () => ({ target: "$terminal", terminalStatus: "failed" });
+
+/** The project's `test` gate from `kxm init`. A gate step settles on `passed` or
+ * `implementation-failure`, never `failed`. `maxAttempts` counts entries into a
+ * step, so every step a back-edge re-enters allows one entry per transition. */
+function verifyStep(retryStep: string): Record<string, unknown> {
+  return {
+    id: "verify",
+    kind: "gate",
+    gate: "test",
+    expect: "pass",
+    maxAttempts: 3,
+    repositories: { control: "write" },
+    on: {
+      passed: completed(),
+      "implementation-failure": { target: retryStep, maxTransitions: 2 },
+    },
+  };
+}
+
+/**
+ * Built-in `kxm workflow add --template` definitions. Each is a complete
+ * kxm.workflow.v1 document (the file name is the workflow id) that uses only
+ * what `kxm init` creates: the coordinator and implementer agents, the control
+ * repository, and the `test` gate. Agent steps declare `failed` because the
+ * producer falls back to it.
+ */
 export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
   "implement-and-verify": {
     schema: "kxm.workflow.v1",
-    description: "Standard implement and verify workflow",
+    description: "Implement a change, then run the project's test gate; a failing gate sends the work back to implement.",
     coordinator: "coordinator",
     limits: {
       maxTransitions: 8,
@@ -30,38 +60,20 @@ export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
       {
         id: "implement",
         kind: "agent",
-        role: "writer",
-        maxAttempts: 2,
+        agent: "implementer",
+        maxAttempts: 3,
+        repositories: { control: "write" },
         on: {
           passed: "verify",
-          failed: {
-            target: "$terminal",
-            terminalStatus: "failed",
-          },
-        },
-      },
-      {
-        id: "verify",
-        kind: "gate",
-        gate: "verify-gate",
-        expect: "pass",
-        maxAttempts: 1,
-        on: {
-          passed: {
-            target: "$terminal",
-            terminalStatus: "completed",
-          },
-          failed: {
-            target: "implement",
-            maxTransitions: 2,
-          },
+          failed: failed(),
         },
       },
+      verifyStep("implement"),
     ],
   },
   "dual-critic-review": {
     schema: "kxm.workflow.v1",
-    description: "Dual-critic review workflow with independent Fable architecture and Sol CLI critics",
+    description: "Implement, review twice, then run the project's test gate. Both reviews run as the coordinator agent; for independent critics, add agents under .kxm/agents and point review-arch and review-cli at them.",
     coordinator: "coordinator",
     limits: {
       maxTransitions: 12,
@@ -70,102 +82,92 @@ export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
       {
         id: "implement",
         kind: "agent",
-        role: "writer",
-        maxAttempts: 2,
+        agent: "implementer",
+        maxAttempts: 3,
+        repositories: { control: "write" },
         on: {
           passed: "review-arch",
-          failed: {
-            target: "$terminal",
-            terminalStatus: "failed",
-          },
+          failed: failed(),
         },
       },
       {
         id: "review-arch",
         kind: "agent",
-        role: "critic-arch",
-        maxAttempts: 2,
+        agent: "coordinator",
+        maxAttempts: 3,
+        repositories: { control: "read" },
         on: {
           passed: "review-cli",
-          failed: {
-            target: "implement",
-            maxTransitions: 2,
-          },
+          failed: { target: "implement", maxTransitions: 2 },
         },
       },
       {
         id: "review-cli",
         kind: "agent",
-        role: "critic-cli",
-        maxAttempts: 2,
+        agent: "coordinator",
+        maxAttempts: 3,
+        repositories: { control: "read" },
         on: {
           passed: "verify",
-          failed: {
-            target: "implement",
-            maxTransitions: 2,
-          },
-        },
-      },
-      {
-        id: "verify",
-        kind: "gate",
-        gate: "verify-gate",
-        expect: "pass",
-        maxAttempts: 1,
-        on: {
-          passed: {
-            target: "$terminal",
-            terminalStatus: "completed",
-          },
-          failed: {
-            target: "implement",
-            maxTransitions: 2,
-          },
+          failed: { target: "implement", maxTransitions: 2 },
         },
       },
+      verifyStep("implement"),
     ],
   },
   "spec-and-plan": {
     schema: "kxm.workflow.v1",
-    description: "Specification and architecture breakdown planning workflow",
+    description: "Plan a change, then review the plan. Both steps run as the coordinator agent and only read the repository.",
     coordinator: "coordinator",
     limits: {
-      maxTransitions: 6,
+      maxTransitions: 8,
     },
     steps: [
       {
         id: "plan",
         kind: "agent",
-        role: "planner",
-        maxAttempts: 2,
+        agent: "coordinator",
+        maxAttempts: 3,
+        repositories: { control: "read" },
         on: {
           passed: "review-arch",
-          failed: {
-            target: "$terminal",
-            terminalStatus: "failed",
-          },
+          failed: failed(),
         },
       },
       {
         id: "review-arch",
         kind: "agent",
-        role: "critic-arch",
-        maxAttempts: 2,
+        agent: "coordinator",
+        maxAttempts: 3,
+        repositories: { control: "read" },
         on: {
-          passed: {
-            target: "$terminal",
-            terminalStatus: "completed",
-          },
-          failed: {
-            target: "plan",
-            maxTransitions: 2,
-          },
+          passed: completed(),
+          failed: { target: "plan", maxTransitions: 2 },
         },
       },
     ],
   },
 };
 
+/** The one-step definition `kxm workflow add <id>` writes without a template or file. */
+export function scaffoldWorkflowDefinition(description: string): Record<string, unknown> {
+  return {
+    schema: "kxm.workflow.v1",
+    description,
+    coordinator: "coordinator",
+    limits: { maxTransitions: 8 },
+    steps: [
+      {
+        id: "step-1",
+        kind: "agent",
+        agent: "implementer",
+        repositories: { control: "write" },
+        on: { passed: completed(), failed: failed() },
+      },
+    ],
+  };
+}
+
 export const DEFAULT_WORKFLOW_TEMPLATE = WORKFLOW_TEMPLATES["implement-and-verify"]!;
 
 export function workflowsDirectory(