@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/src/subagent-control.ts

@@ -0,0 +1,312 @@
+/**
+ * Supervisory agent control, in-process real-time steering, and work-splitting.
+ *
+ * Implements:
+ * - Dual-tool control plane: `agent` (spawn) and `agent_control` (manage, poll, steer, stop).
+ * - Strict capability narrowing via `allowed_tools[]` allowlists.
+ * - Mid-flight steering instruction injection.
+ * - Subagent state lifecycle management (working, blocked, idle, done, error).
+ */
+
+import { randomUUID } from "node:crypto";
+import { assertCommandSeatbelt } from "./safety-integrity.ts";
+
+export type SubagentType = "general" | "Explore" | "Plan" | "Reviewer" | "Auditor";
+export type SubagentStatus = "pending" | "running" | "blocked" | "completed" | "stopped" | "failed";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high";
+
+export interface AgentSpawnParams {
+  prompt: string;
+  description: string;
+  type?: SubagentType | undefined;
+  model?: string | undefined;
+  thinking?: ThinkingLevel | undefined;
+  allowed_tools?: string[] | undefined;
+  turns?: number | undefined;
+  background?: boolean | undefined;
+  parent_tools?: readonly string[] | undefined;
+}
+
+export interface AgentControlParams {
+  action: "info" | "result" | "steer" | "stop";
+  kind?: "types" | "models" | "active" | undefined;
+  agent_id?: string | undefined;
+  message?: string | undefined;
+  turns?: number | undefined;
+  verbose?: boolean | undefined;
+}
+
+export interface SubagentRecord {
+  id: string;
+  description: string;
+  type: SubagentType;
+  model: string;
+  thinking: ThinkingLevel;
+  allowedTools: string[];
+  status: SubagentStatus;
+  turnsMax: number;
+  turnsCompleted: number;
+  prompt: string;
+  createdAt: string;
+  updatedAt: string;
+  steeringMessages: Array<{ text: string; injectedAt: string; processed: boolean }>;
+  output?: string | undefined;
+  error?: string | undefined;
+}
+
+export interface SubagentExecutionReceipt {
+  ok: boolean;
+  action: string;
+  agent_id?: string | undefined;
+  status?: SubagentStatus | undefined;
+  activeAgents?: Array<{ id: string; description: string; type: SubagentType; status: SubagentStatus }> | undefined;
+  types?: readonly SubagentType[] | undefined;
+  result?: string | undefined;
+  steered?: boolean | undefined;
+  stopped?: boolean | undefined;
+  error?: string | undefined;
+}
+
+export const SUBAGENT_TYPES: readonly SubagentType[] = Object.freeze([
+  "general",
+  "Explore",
+  "Plan",
+  "Reviewer",
+  "Auditor",
+]);
+
+export const DEFAULT_SUBAGENT_MODELS: Readonly<Record<SubagentType, string>> = Object.freeze({
+  general: "grok/grok-4.6",
+  Explore: "openrouter/qwen/qwen3-coder-plus",
+  Plan: "claude/fable",
+  Reviewer: "openai/gpt-5.6-sol",
+  Auditor: "claude/fable",
+});
+
+/**
+ * Validates and intersects child allowed tools against the parent tool surface.
+ * Enforces the safety invariant that a child can only narrow, never expand authority.
+ */
+export function narrowSubagentTools(
+  requestedTools: readonly string[] | undefined,
+  parentTools?: readonly string[] | undefined,
+): string[] {
+  if (!requestedTools || requestedTools.length === 0) {
+    return parentTools ? [...parentTools] : ["read", "grep", "find"];
+  }
+
+  if (!parentTools || parentTools.length === 0) {
+    return [...requestedTools];
+  }
+
+  const parentSet = new Set(parentTools);
+  const narrowed: string[] = [];
+
+  for (const tool of requestedTools) {
+    if (parentSet.has(tool)) {
+      narrowed.push(tool);
+    }
+  }
+
+  if (narrowed.length === 0 && requestedTools.length > 0) {
+    throw new Error(
+      `Cannot spawn subagent: requested tools [${requestedTools.join(", ")}] expand beyond parent capabilities.`,
+    );
+  }
+
+  return narrowed;
+}
+
+/**
+ * In-Process Subagent Manager.
+ */
+export class SubagentManager {
+  private readonly subagents = new Map<string, SubagentRecord>();
+
+  /**
+   * Spawns a new managed subagent with strict capability boundaries.
+   */
+  spawn(params: AgentSpawnParams): SubagentRecord {
+    if (!params.prompt || !params.prompt.trim()) {
+      throw new Error('Subagent "prompt" is required.');
+    }
+    if (!params.description || !params.description.trim()) {
+      throw new Error('Subagent "description" is required.');
+    }
+
+    const type = params.type ?? "general";
+    const model = params.model ?? DEFAULT_SUBAGENT_MODELS[type] ?? "grok/grok-4.6";
+    const thinking = params.thinking ?? "low";
+    const allowedTools = narrowSubagentTools(params.allowed_tools, params.parent_tools);
+    const id = `ag_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+    const now = new Date().toISOString();
+
+    const record: SubagentRecord = {
+      id,
+      description: params.description.trim(),
+      type,
+      model,
+      thinking,
+      allowedTools,
+      status: params.background === false ? "completed" : "running",
+      turnsMax: params.turns ?? 10,
+      turnsCompleted: 0,
+      prompt: params.prompt.trim(),
+      createdAt: now,
+      updatedAt: now,
+      steeringMessages: [],
+    };
+
+    this.subagents.set(id, record);
+    return record;
+  }
+
+  /**
+   * Dispatches an action from the `agent_control` tool.
+   */
+  control(params: AgentControlParams): SubagentExecutionReceipt {
+    const action = params.action;
+
+    // 1. Action: "info"
+    if (action === "info") {
+      const kind = params.kind ?? "active";
+      if (kind === "types") {
+        return {
+          ok: true,
+          action: "info",
+          types: SUBAGENT_TYPES,
+        };
+      }
+      if (kind === "models") {
+        return {
+          ok: true,
+          action: "info",
+          result: JSON.stringify(DEFAULT_SUBAGENT_MODELS),
+        };
+      }
+      const active = Array.from(this.subagents.values()).map((ag) => ({
+        id: ag.id,
+        description: ag.description,
+        type: ag.type,
+        status: ag.status,
+      }));
+      return {
+        ok: true,
+        action: "info",
+        activeAgents: active,
+      };
+    }
+
+    if (!params.agent_id) {
+      return {
+        ok: false,
+        action,
+        error: 'Parameter "agent_id" is required for result, steer, and stop actions.',
+      };
+    }
+
+    const agent = this.subagents.get(params.agent_id);
+    if (!agent) {
+      return {
+        ok: false,
+        action,
+        agent_id: params.agent_id,
+        error: `Subagent "${params.agent_id}" not found.`,
+      };
+    }
+
+    // 2. Action: "result"
+    if (action === "result") {
+      return {
+        ok: true,
+        action: "result",
+        agent_id: agent.id,
+        status: agent.status,
+        result: agent.output ?? `[Subagent is currently ${agent.status}]`,
+      };
+    }
+
+    // 3. Action: "steer"
+    if (action === "steer") {
+      if (!params.message || !params.message.trim()) {
+        return {
+          ok: false,
+          action: "steer",
+          agent_id: agent.id,
+          error: 'Parameter "message" is required for steer action.',
+        };
+      }
+
+      if (agent.status === "completed" || agent.status === "stopped" || agent.status === "failed") {
+        return {
+          ok: false,
+          action: "steer",
+          agent_id: agent.id,
+          error: `Cannot steer subagent "${agent.id}" because it is already ${agent.status}.`,
+        };
+      }
+
+      agent.steeringMessages.push({
+        text: params.message.trim(),
+        injectedAt: new Date().toISOString(),
+        processed: false,
+      });
+      agent.updatedAt = new Date().toISOString();
+
+      return {
+        ok: true,
+        action: "steer",
+        agent_id: agent.id,
+        status: agent.status,
+        steered: true,
+      };
+    }
+
+    // 4. Action: "stop"
+    if (action === "stop") {
+      agent.status = "stopped";
+      agent.updatedAt = new Date().toISOString();
+      return {
+        ok: true,
+        action: "stop",
+        agent_id: agent.id,
+        status: "stopped",
+        stopped: true,
+      };
+    }
+
+    return {
+      ok: false,
+      action,
+      error: `Unknown control action "${action}".`,
+    };
+  }
+
+  /**
+   * Retrieves an agent record by ID.
+   */
+  get(agentId: string): SubagentRecord | undefined {
+    return this.subagents.get(agentId);
+  }
+
+  /**
+   * Marks a subagent as completed with output.
+   */
+  complete(agentId: string, output: string): void {
+    const agent = this.subagents.get(agentId);
+    if (agent) {
+      agent.status = "completed";
+      agent.output = output;
+      agent.updatedAt = new Date().toISOString();
+    }
+  }
+
+  /**
+   * Returns all active running subagents.
+   */
+  listActive(): SubagentRecord[] {
+    return Array.from(this.subagents.values()).filter(
+      (ag) => ag.status === "running" || ag.status === "pending" || ag.status === "blocked",
+    );
+  }
+}

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-bindings.ts

@@ -15,7 +15,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import {
   VnextConfigError,