@kontextmind/kxm 0.6.0 → 0.7.0

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", "memory-leak-debugging"],
+    skills: ["troubleshooting", "kxm", "kxm-query", "kxm-work"],
     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"],
+    skills: ["modern-web-guidance", "kxm", "kxm-mind", "kxm-query"],
     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"],
+    skills: ["kxm", "kxm-mind", "kxm-query"],
     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"],
+    skills: ["kxm", "kxm-protocol", "kxm-triage"],
     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"],
+    skills: ["kxm", "kxm-protocol"],
     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"],
+    skills: ["kxm", "kxm-query"],
     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"],
+    skills: ["kxm-session", "kxm-mind", "kxm-query", "kxm-insights"],
     defaultCommand: (p) => `kxm run research-strategy/architecture-spike "${p}"`,
   },
 ];
@@ -110,36 +110,30 @@ export function suggestWorkflowAndRoles(
   }
 
   if (bestScore <= 0) {
-    // Default fallback to feature-implementation
     bestPattern = WORKFLOW_PATTERNS[1]!;
     matchedReasons.push("Default fallback: general feature implementation workflow");
   }
 
-  // Determine active harnesses
   const activeHarnesses = new Set(
     (options.availableHarnesses ?? [])
       .filter((h) => h.auth === "active" || h.auth === "ready" || h.auth === "configured")
       .map((h) => h.harness.toLowerCase()),
   );
 
-  // If none specified or active, assume standard default rotation
   const hasClaude = activeHarnesses.size === 0 || activeHarnesses.has("claude");
   const hasGrok = activeHarnesses.size === 0 || activeHarnesses.has("grok");
   const hasCodex = activeHarnesses.size === 0 || activeHarnesses.has("codex");
 
-  // Planner
   const planner: RoleSpec = hasClaude
     ? { harness: "claude", model: "fable", role: "planner" }
     : { harness: "codex", model: "gpt-5.6-sol", role: "planner" };
 
-  // Writer (Starting rotation: Grok 4.6 headless)
   const writer: RoleSpec = hasGrok
     ? { harness: "grok", model: "grok-4.6", role: "writer" }
     : (activeHarnesses.has("agy")
       ? { harness: "agy", model: "gemini-2.5-pro", role: "writer" }
       : { harness: "pi", model: "qwen/qwen3-coder-plus", role: "writer" });
 
-  // Critics (Vendor independent: Fable Arch + Codex CLI)
   const critics: RoleSpec[] = [
     { harness: "claude", model: "fable", role: "reviewer-arch" },
     { harness: "codex", model: "gpt-5.6-sol", role: "reviewer-cli" },

package/plugins/kxm/src/telemetry.ts

@@ -114,3 +114,85 @@ export function readRoutingRecords(path: string): Array<{ recordedAt: string; ro
   }
   return records;
 }
+
+export const FEDERATED_METRIC_SCHEMA = "kxm.federated-metric.v1" as const;
+
+export interface FederatedModelMetric {
+  schema: typeof FEDERATED_METRIC_SCHEMA;
+  harness: string;
+  model: string;
+  timestamp: string;
+  latencyMs: number;
+  tokensIn?: number | null | undefined;
+  tokensOut?: number | null | undefined;
+  costUsd?: number | null | undefined;
+  verifierOutcome?: "passed" | "warning" | "failed" | undefined;
+}
+
+/**
+ * Exports anonymized model telemetry metrics to federated user directory (Decision Q15).
+ * Strictly strips repository paths, prompts, code diffs, run IDs, and memory items.
+ */
+export function exportFederatedTelemetry(
+  records: Array<RoutingRecord | RoutingRecordV2>,
+  globalDir?: string,
+): number {
+  const targetDir = globalDir
+    ? join(globalDir, "telemetry")
+    : join(process.env.XDG_CONFIG_HOME || join(process.env.HOME || "~", ".config"), "kxm", "telemetry");
+
+  mkdirSync(targetDir, { recursive: true });
+  const metricsPath = join(targetDir, "model-metrics.jsonl");
+
+  let exported = 0;
+  for (const r of records) {
+    const isV2 = r.schema === "kxm.routing-record.v2";
+    const v2 = isV2 ? (r as RoutingRecordV2) : undefined;
+    const harness = (v2 ? v2.harness : (r.providerMetadata?.harness as string | undefined)) || "unknown";
+    const model = (v2 ? (v2.effectiveModel || v2.requestedModel) : (r.effectiveModel || r.requestedModel)) || "unknown";
+    const timestamp = (r as any).recordedAt || new Date().toISOString();
+    const latencyMs = v2 ? v2.latencyMs : (typeof r.providerMetadata?.latencyMs === "number" ? (r.providerMetadata.latencyMs as number) : 0);
+
+    const metric: FederatedModelMetric = {
+      schema: FEDERATED_METRIC_SCHEMA,
+      harness,
+      model,
+      timestamp,
+      latencyMs,
+      tokensIn: r.tokensIn ?? null,
+      tokensOut: r.tokensOut ?? null,
+      costUsd: r.costUsd ?? null,
+      verifierOutcome: r.verifierOutcome,
+    };
+
+    appendFileSync(metricsPath, `${JSON.stringify(metric)}\n`, { encoding: "utf8", mode: 0o600 });
+    exported++;
+  }
+
+  return exported;
+}
+
+export function readFederatedTelemetry(globalDir?: string): FederatedModelMetric[] {
+  const targetDir = globalDir
+    ? join(globalDir, "telemetry")
+    : join(process.env.XDG_CONFIG_HOME || join(process.env.HOME || "~", ".config"), "kxm", "telemetry");
+  const metricsPath = join(targetDir, "model-metrics.jsonl");
+  try {
+    const raw = readFileSync(metricsPath, "utf8");
+    const metrics: FederatedModelMetric[] = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const parsed = JSON.parse(line) as FederatedModelMetric;
+        if (parsed.schema === FEDERATED_METRIC_SCHEMA) {
+          metrics.push(parsed);
+        }
+      } catch {
+        // Skip malformed
+      }
+    }
+    return metrics;
+  } catch {
+    return [];
+  }
+}

package/plugins/kxm/src/tui.ts

@@ -15,7 +15,11 @@ import {
   type Terminal,
   type TUI,
 } from "@earendil-works/pi-tui";
+import { mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
 import type { AgentRecord } from "./protocol.ts";
+import { slugifyBranchPart } from "./external-effects.ts";
 import {
   loadLocalMeshSnapshot,
   summarizeMeshRun,
@@ -138,6 +142,114 @@ export function applyMeshTuiKey(view: MeshTuiView, key: string, itemCount = 0):
   return view;
 }
 
+export interface DegradeWorktreeResult {
+  ok: boolean;
+  branchName: string;
+  worktreePath: string;
+  jumpCommand: string;
+  copiedToClipboard: boolean;
+  error?: string | undefined;
+}
+
+export function copyToClipboard(text: string): boolean {
+  try {
+    if (process.platform === "darwin") {
+      const proc = spawnSync("pbcopy", { input: text, encoding: "utf8", windowsHide: true });
+      return proc.status === 0;
+    }
+    if (process.platform === "win32") {
+      const proc = spawnSync("clip", { input: text, encoding: "utf8", windowsHide: true });
+      return proc.status === 0;
+    }
+    const wl = spawnSync("wl-copy", [text], { encoding: "utf8", windowsHide: true });
+    if (wl.status === 0) return true;
+    const xclip = spawnSync("xclip", ["-selection", "clipboard"], { input: text, encoding: "utf8", windowsHide: true });
+    return xclip.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Automated Degrade Worktree Spawn (Decision Q1).
+ * Spawns an isolated git worktree for human operator intervention on key 'd'.
+ * Detaches the AI worker, copies directory path to clipboard, and prints jump command.
+ */
+export function spawnDegradeWorktree(
+  repoRoot: string,
+  runId: string,
+  options?: {
+    description?: string | undefined;
+    execFn?: ((cmd: string, args: string[]) => { status: number; stdout: string; stderr: string }) | undefined;
+    clipboardFn?: ((text: string) => boolean) | undefined;
+  },
+): DegradeWorktreeResult {
+  const runner = options?.execFn ?? ((cmd: string, args: string[]) => {
+    const res = spawnSync(cmd, args, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      env: Object.fromEntries(
+        Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("GIT_")),
+      ),
+    });
+    return {
+      status: res.status ?? 1,
+      stdout: res.stdout || "",
+      stderr: res.stderr || "",
+    };
+  });
+
+  const cleanRunId = runId.replace(/^run_/, "");
+  const desc = options?.description ? slugifyBranchPart(options.description, 30) : "degrade";
+  const branchName = `kxm/run-${cleanRunId}-${desc}`;
+  const relativeWtPath = join(".kxm", "worktrees", `run-${cleanRunId}-${desc}`);
+  const absoluteWtPath = resolve(repoRoot, relativeWtPath);
+  const jumpCommand = `cd "${absoluteWtPath}"`;
+
+  try {
+    mkdirSync(dirname(absoluteWtPath), { recursive: true });
+
+    const branchCheck = runner("git", ["rev-parse", "--verify", `refs/heads/${branchName}`]);
+    let wtRes: { status: number; stdout: string; stderr: string };
+    if (branchCheck.status === 0) {
+      wtRes = runner("git", ["worktree", "add", absoluteWtPath, branchName]);
+    } else {
+      wtRes = runner("git", ["worktree", "add", "-b", branchName, absoluteWtPath]);
+    }
+
+    if (wtRes.status !== 0) {
+      return {
+        ok: false,
+        branchName,
+        worktreePath: absoluteWtPath,
+        jumpCommand,
+        copiedToClipboard: false,
+        error: `failed_to_add_worktree: ${wtRes.stderr.trim() || wtRes.stdout.trim()}`,
+      };
+    }
+
+    const clipFn = options?.clipboardFn ?? copyToClipboard;
+    const copied = clipFn(absoluteWtPath);
+    return {
+      ok: true,
+      branchName,
+      worktreePath: absoluteWtPath,
+      jumpCommand,
+      copiedToClipboard: copied,
+    };
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      branchName,
+      worktreePath: absoluteWtPath,
+      jumpCommand,
+      copiedToClipboard: false,
+      error: `degrade_worktree_spawn_error: ${(err as Error).message}`,
+    };
+  }
+}
+
 export interface MeshTuiSnapshot extends LocalMeshSnapshot {
   serverUrl: string;
   healthOk: boolean;
@@ -534,6 +646,12 @@ export class KxmDashboard implements Component {
     this.requestRender();
   }
 
+  setStatusMessage(message: string): void {
+    this.view = { ...this.view, statusMessage: message };
+    this.rebuild();
+    this.requestRender();
+  }
+
   private activeScroll(): ScrollView {
     return this.view.pane === "detail" ? this.detailScroll : this.listScroll;
   }
@@ -886,6 +1004,28 @@ export async function runMeshTui(input: {
             body: JSON.stringify({ signalKey: "operator-approval", status: "failed", summary: "Rejected by operator in kxm dash" }),
             signal: abort.signal,
           });
+        } else if (action.action === "degrade") {
+          await input.fetchImpl(`${base}/v1/runs/${encodeURIComponent(targetId)}/signal?project=${encodeURIComponent(input.project)}`, {
+            method: "POST",
+            headers: headers(),
+            body: JSON.stringify({ signalKey: "operator-degrade", status: "degraded", summary: "Degraded to operator worktree from kxm dash" }),
+            signal: abort.signal,
+          });
+          const repoRoot = process.cwd();
+          const degradeRes = spawnDegradeWorktree(repoRoot, targetId, {
+            description: "operator-degrade",
+          });
+          if (dashboard) {
+            if (degradeRes.ok) {
+              dashboard.setStatusMessage(
+                `[DEGRADE] Worktree: ${degradeRes.worktreePath} (cd command copied to clipboard)`,
+              );
+            } else {
+              dashboard.setStatusMessage(
+                `[DEGRADE] Signal sent, worktree failed: ${degradeRes.error}`,
+              );
+            }
+          }
         }
       } catch {
         // fail-soft on dashboard network errors during key press

package/plugins/kxm/src/vnext-config.ts

@@ -4,30 +4,19 @@ import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Ajv2020, type ErrorObject, type ValidateFunction } from "ajv/dist/2020.js";
-import { isAlias, isCollection, isMap, isScalar, parseDocument, visit } from "yaml";
+import {
+  RestrictedYamlError,
+  VNEXT_YAML_LIMITS,
+  parseRestrictedYaml as parseRestrictedYamlShared,
+  type VnextYamlLimits,
+} from "./restricted-yaml.mjs";
 import { resolveVnextTemplateBaseline } from "./vnext-template.ts";
 import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS, validateHarnessModelPair } from "./vnext-harness.ts";
 
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonObject = { [key: string]: JsonValue };
-
-export interface VnextYamlLimits {
-  maxDocumentBytes: number;
-  maxDepth: number;
-  maxScalarBytes: number;
-  maxCollectionItems: number;
-  maxTotalNodes: number;
-  maxKeys: number;
-}
-
-export const VNEXT_YAML_LIMITS: Readonly<VnextYamlLimits> = Object.freeze({
-  maxDocumentBytes: 256 * 1024,
-  maxDepth: 32,
-  maxScalarBytes: 64 * 1024,
-  maxCollectionItems: 4096,
-  maxTotalNodes: 16_384,
-  maxKeys: 8192,
-});
+export type { VnextYamlLimits };
+export { VNEXT_YAML_LIMITS };
 
 export type VnextValidationPhase = "discovery" | "parse" | "schema" | "path" | "reference" | "semantic";
 
@@ -120,16 +109,6 @@ const SECRET_VALUE_PATTERNS: readonly RegExp[] = [
   /\bAKIA[A-Z0-9]{16}\b/,
   /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
 ];
-const ALLOWED_YAML_TAGS = new Set([
-  "tag:yaml.org,2002:map",
-  "tag:yaml.org,2002:seq",
-  "tag:yaml.org,2002:str",
-  "tag:yaml.org,2002:null",
-  "tag:yaml.org,2002:bool",
-  "tag:yaml.org,2002:int",
-  "tag:yaml.org,2002:float",
-]);
-
 function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -149,97 +128,22 @@ function fail(phase: VnextValidationPhase, code: string, file: string, message:
   throw new VnextConfigError([issue(phase, code, file, message)]);
 }
 
-function decodeUtf8(input: string | Uint8Array, label: string): string {
-  if (typeof input === "string") return input;
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(input);
-  } catch {
-    fail("parse", "invalid_utf8", label, "document is not valid UTF-8");
-  }
-}
-
 function isJsonObject(value: JsonValue): value is JsonObject {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function assertJsonValue(value: unknown, label: string, path = "$", seen = new Set<unknown>()): asserts value is JsonValue {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) fail("parse", "non_json_number", label, `${path} is not a finite JSON number`);
-    return;
-  }
-  if (!value || typeof value !== "object") fail("parse", "non_json_value", label, `${path} is not JSON-compatible`);
-  if (seen.has(value)) fail("parse", "cyclic_value", label, `${path} is cyclic`);
-  seen.add(value);
-  if (Array.isArray(value)) {
-    for (const [index, candidate] of value.entries()) assertJsonValue(candidate, label, `${path}[${index}]`, seen);
-  } else {
-    const prototype = Object.getPrototypeOf(value) as unknown;
-    if (prototype !== Object.prototype && prototype !== null) {
-      fail("parse", "constructed_object", label, `${path} has a forbidden constructed type`);
-    }
-    for (const [key, candidate] of Object.entries(value)) assertJsonValue(candidate, label, `${path}.${key}`, seen);
-  }
-  seen.delete(value);
-}
-
 /** Parse the restricted, JSON-compatible YAML profile used by all vNext configuration. */
 export function parseRestrictedYaml(
   input: string | Uint8Array,
   label = "<yaml>",
   limits: Readonly<VnextYamlLimits> = VNEXT_YAML_LIMITS,
 ): JsonObject {
-  const byteLength = typeof input === "string" ? Buffer.byteLength(input, "utf8") : input.byteLength;
-  if (byteLength > limits.maxDocumentBytes) {
-    fail("parse", "document_too_large", label, `document exceeds ${limits.maxDocumentBytes} bytes`);
-  }
-  const text = decodeUtf8(input, label);
-  const document = parseDocument(text, {
-    customTags: [],
-    strict: true,
-    uniqueKeys: true,
-  });
-  if (document.errors.length > 0) {
-    fail("parse", "invalid_yaml", label, document.errors.map((error) => error.message).join("; "));
-  }
-  if (document.warnings.length > 0) {
-    fail("parse", "yaml_warning", label, document.warnings.map((warning) => warning.message).join("; "));
-  }
-
-  let nodes = 0;
-  let keys = 0;
-  visit(document, (_key, node, path) => {
-    nodes += 1;
-    if (nodes > limits.maxTotalNodes) fail("parse", "node_limit", label, `document exceeds ${limits.maxTotalNodes} nodes`);
-    if (path.length > limits.maxDepth) fail("parse", "depth_limit", label, `document exceeds nesting depth ${limits.maxDepth}`);
-    if (isAlias(node)) fail("parse", "alias_forbidden", label, "aliases are forbidden");
-    if (node && typeof node === "object" && "anchor" in node && typeof node.anchor === "string") {
-      fail("parse", "anchor_forbidden", label, "anchors are forbidden");
-    }
-    if (isCollection(node) && node.items.length > limits.maxCollectionItems) {
-      fail("parse", "collection_limit", label, `collection exceeds ${limits.maxCollectionItems} items`);
-    }
-    if (isMap(node)) {
-      keys += node.items.length;
-      if (keys > limits.maxKeys) fail("parse", "key_limit", label, `document exceeds ${limits.maxKeys} mapping keys`);
-      for (const pair of node.items) {
-        if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
-          fail("parse", "non_string_key", label, "mapping keys must be strings");
-        }
-      }
-    }
-    if (isScalar(node) && typeof node.value === "string" && Buffer.byteLength(node.value, "utf8") > limits.maxScalarBytes) {
-      fail("parse", "scalar_limit", label, `scalar exceeds ${limits.maxScalarBytes} bytes`);
-    }
-    if (node && typeof node === "object" && "tag" in node && typeof node.tag === "string" && !ALLOWED_YAML_TAGS.has(node.tag)) {
-      fail("parse", "tag_forbidden", label, `tag ${node.tag} is forbidden`);
-    }
-  });
-
-  const value = document.toJS({ maxAliasCount: 0 }) as unknown;
-  assertJsonValue(value, label);
-  if (!isJsonObject(value)) fail("parse", "root_not_object", label, "resource root must be a mapping");
-  return value;
+  try {
+    return parseRestrictedYamlShared(input, label, limits);
+  } catch (error) {
+    if (error instanceof RestrictedYamlError) throw new VnextConfigError(error.issues);
+    throw error;
+  }
 }
 
 function readJsonObject(file: string): Record<string, unknown> {
@@ -570,6 +474,7 @@ function listNamedResources(
       continue;
     }
     const id = basename(entry.name, ".yaml");
+    if (kind === "model" && id === "inventory") continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue("path", "resource_id_invalid", displayPath(root, join(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;