@kontextmind/kxm 0.7.92 → 0.7.93

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(