@kontextmind/kxm 0.6.0 → 0.7.0

package/plugins/kxm/src/role.ts

@@ -0,0 +1,375 @@
+/**
+ * KXM Role Management Subsystem (kxm.role.v1).
+ * Supports modular per-role YAML files with descriptions, skills, tool permissions, and model rosters.
+ * Implements global (~/.config/kxm/roles/) and local (.kxm/roles/) inheritance.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+import { repoConfigDirectory, userConfigDirectory } from "./config.ts";
+
+export const KXM_ROLE_SCHEMA = "kxm.role.v1" as const;
+
+export interface KxmRosterEntry {
+  harness: string;
+  model: string;
+  provider?: string | undefined;
+  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
+  mode?: "headless" | "interactive" | "either" | undefined;
+}
+
+export interface KxmRoleToolPolicy {
+  preset?: string | undefined;
+  allow?: string[] | undefined;
+  deny?: string[] | undefined;
+}
+
+export interface KxmTemplateContract {
+  template: string;
+  schema?: string | undefined;
+}
+
+export interface KxmRolePolicy {
+  vendorIndependenceRequired?: boolean | undefined;
+  maxTransitions?: number | undefined;
+  requiresGateVerification?: boolean | undefined;
+}
+
+export interface KxmRoleDefinition {
+  schema: typeof KXM_ROLE_SCHEMA;
+  id: string;
+  description: string;
+  skills?: string[] | undefined;
+  tools?: KxmRoleToolPolicy | undefined;
+  produces?: KxmTemplateContract[] | undefined;
+  consumes?: KxmTemplateContract[] | undefined;
+  roster: KxmRosterEntry[];
+  policy?: KxmRolePolicy | undefined;
+}
+
+export interface KxmRoleSummary {
+  id: string;
+  description: string;
+  scope: "global" | "local" | "overridden";
+  filePath: string;
+  skills: string[];
+  toolsCount: number;
+  roster: KxmRosterEntry[];
+  primaryModel?: string | undefined;
+  primaryHarness?: string | undefined;
+}
+
+export const DEFAULT_ROLES: Record<string, KxmRoleDefinition> = {
+  writer: {
+    schema: KXM_ROLE_SCHEMA,
+    id: "writer",
+    description: "Primary implementation agent. Writes code, refactors components, and authors unit tests.",
+    skills: ["kxm", "unit-testing"],
+    tools: {
+      preset: "author",
+      allow: ["view_file", "replace_file_content", "write_to_file", "run_command"],
+      deny: ["git push"],
+    },
+    produces: [{ template: "code-patch" }],
+    roster: [
+      { harness: "grok", model: "grok-4.6", effort: "low", mode: "headless" },
+      { harness: "pi", provider: "openrouter", model: "openrouter/qwen/qwen3-coder-plus", effort: "medium" },
+      { harness: "agy", model: "gemini-2.5-pro", effort: "low" },
+    ],
+  },
+  planner: {
+    schema: KXM_ROLE_SCHEMA,
+    id: "planner",
+    description: "Architecture breakdown, requirement decomposition, and safety boundary definition.",
+    skills: ["kxm-session", "architecture-planning"],
+    tools: {
+      preset: "read_only",
+      allow: ["view_file", "grep_search", "find_by_name", "list_dir"],
+      deny: ["write_to_file", "replace_file_content", "run_command"],
+    },
+    produces: [{ template: "implementation-plan" }],
+    roster: [
+      { harness: "claude", model: "fable", effort: "medium" },
+    ],
+  },
+  "critic-arch": {
+    schema: KXM_ROLE_SCHEMA,
+    id: "critic-arch",
+    description: "Independent critic reviewing implementation diffs for architectural integrity and permission boundaries.",
+    policy: { vendorIndependenceRequired: true },
+    tools: {
+      preset: "critic",
+      allow: ["view_file", "grep_search"],
+    },
+    produces: [{ template: "critic-signoff" }],
+    roster: [
+      { harness: "claude", model: "fable", effort: "medium" },
+    ],
+  },
+  "critic-cli": {
+    schema: KXM_ROLE_SCHEMA,
+    id: "critic-cli",
+    description: "CLI, documentation, and developer ergonomics critic.",
+    policy: { vendorIndependenceRequired: true },
+    tools: {
+      preset: "critic",
+      allow: ["view_file", "grep_search"],
+    },
+    produces: [{ template: "critic-signoff" }],
+    roster: [
+      { harness: "codex", model: "gpt-5.6-sol", effort: "low" },
+    ],
+  },
+  verifier: {
+    schema: KXM_ROLE_SCHEMA,
+    id: "verifier",
+    description: "Deterministic gate evaluation runner.",
+    tools: {
+      preset: "verifier",
+      allow: ["run_command"],
+    },
+    produces: [{ template: "verification-receipt" }],
+    roster: [
+      { harness: "pi", model: "evaluator", effort: "low" },
+    ],
+  },
+};
+
+export function rolesDirectory(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+): string {
+  if (scope === "global") {
+    return join(userConfigDirectory(userConfigDir), "roles");
+  }
+  return join(repoConfigDirectory(repoRoot), "roles");
+}
+
+export function ensureRolesDirectory(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+): string {
+  const dir = rolesDirectory(scope, repoRoot, userConfigDir);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+export function ensureDefaultRoles(userConfigDir?: string): void {
+  const dir = ensureRolesDirectory("global", undefined, userConfigDir);
+  for (const [id, def] of Object.entries(DEFAULT_ROLES)) {
+    const filePath = join(dir, `${id}.yaml`);
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, stringify(def), "utf8");
+    }
+  }
+}
+
+export function parseRoleFile(filePath: string): KxmRoleDefinition | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = parse(raw) as Partial<KxmRoleDefinition>;
+    if (!parsed || typeof parsed !== "object" || parsed.schema !== KXM_ROLE_SCHEMA) {
+      return undefined;
+    }
+    const id = parsed.id || filePath.replace(/^.*[\\/]/, "").replace(/\.yaml$/i, "");
+    return {
+      schema: KXM_ROLE_SCHEMA,
+      id,
+      description: parsed.description || "",
+      skills: Array.isArray(parsed.skills) ? parsed.skills : [],
+      tools: parsed.tools,
+      produces: parsed.produces,
+      consumes: parsed.consumes,
+      roster: Array.isArray(parsed.roster) ? parsed.roster : [],
+      policy: parsed.policy,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function listRoles(options: {
+  scope?: "all" | "global" | "local" | undefined;
+  repoRoot?: string | undefined;
+  userConfigDir?: string | undefined;
+} = {}): KxmRoleSummary[] {
+  const scopeFilter = options.scope ?? "all";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const globalDir = rolesDirectory("global", repoRoot, options.userConfigDir);
+  const localDir = rolesDirectory("local", repoRoot, options.userConfigDir);
+
+  const localRoles = new Map<string, { role: KxmRoleDefinition; filePath: string }>();
+  if (scopeFilter !== "global" && existsSync(localDir)) {
+    for (const entry of readdirSync(localDir)) {
+      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+        const filePath = join(localDir, entry);
+        const parsed = parseRoleFile(filePath);
+        if (parsed) {
+          localRoles.set(parsed.id, { role: parsed, filePath });
+        }
+      }
+    }
+  }
+
+  const globalRoles = new Map<string, { role: KxmRoleDefinition; filePath: string }>();
+  if (scopeFilter !== "local" && existsSync(globalDir)) {
+    for (const entry of readdirSync(globalDir)) {
+      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+        const filePath = join(globalDir, entry);
+        const parsed = parseRoleFile(filePath);
+        if (parsed) {
+          globalRoles.set(parsed.id, { role: parsed, filePath });
+        }
+      }
+    }
+  }
+
+  const result: KxmRoleSummary[] = [];
+
+  // 1. Process local roles
+  for (const [id, { role, filePath }] of localRoles) {
+    const isOverridden = globalRoles.has(id);
+    const primary = role.roster[0];
+    result.push({
+      id,
+      description: role.description,
+      scope: isOverridden ? "overridden" : "local",
+      filePath,
+      skills: role.skills ?? [],
+      toolsCount: (role.tools?.allow?.length ?? 0),
+      roster: role.roster,
+      primaryModel: primary?.model,
+      primaryHarness: primary?.harness,
+    });
+  }
+
+  // 2. Process global roles not in local (or if scope is global only)
+  for (const [id, { role, filePath }] of globalRoles) {
+    if (scopeFilter === "global" || !localRoles.has(id)) {
+      const primary = role.roster[0];
+      result.push({
+        id,
+        description: role.description,
+        scope: "global",
+        filePath,
+        skills: role.skills ?? [],
+        toolsCount: (role.tools?.allow?.length ?? 0),
+        roster: role.roster,
+        primaryModel: primary?.model,
+        primaryHarness: primary?.harness,
+      });
+    }
+  }
+
+  result.sort((a, b) => a.id.localeCompare(b.id));
+  return result;
+}
+
+export function getRole(
+  roleId: string,
+  options: {
+    scope?: "all" | "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { role: KxmRoleDefinition; scope: "global" | "local"; filePath: string } | undefined {
+  const scope = options.scope ?? "all";
+  const repoRoot = options.repoRoot ?? process.cwd();
+
+  // Check local first if allowed
+  if (scope !== "global") {
+    const localDir = rolesDirectory("local", repoRoot, options.userConfigDir);
+    const localFile = join(localDir, `${roleId}.yaml`);
+    const parsed = parseRoleFile(localFile);
+    if (parsed) return { role: parsed, scope: "local", filePath: localFile };
+  }
+
+  // Check global
+  if (scope !== "local") {
+    const globalDir = rolesDirectory("global", repoRoot, options.userConfigDir);
+    const globalFile = join(globalDir, `${roleId}.yaml`);
+    const parsed = parseRoleFile(globalFile);
+    if (parsed) return { role: parsed, scope: "global", filePath: globalFile };
+  }
+
+  return undefined;
+}
+
+export function addRole(
+  role: KxmRoleDefinition,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+    overwrite?: boolean | undefined;
+  } = {},
+): { id: string; filePath: string; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${role.id}.yaml`);
+
+  if (existsSync(filePath) && !options.overwrite) {
+    throw new Error(`role_already_exists: role '${role.id}' already exists at ${filePath}`);
+  }
+
+  writeFileSync(filePath, stringify(role), "utf8");
+  return { id: role.id, filePath, scope };
+}
+
+export function removeRole(
+  roleId: string,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = rolesDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${roleId}.yaml`);
+
+  if (!existsSync(filePath)) {
+    throw new Error(`role_not_found: role '${roleId}' not found in ${scope} directory (${filePath})`);
+  }
+
+  rmSync(filePath);
+  return { id: roleId, removed: true, filePath, scope };
+}
+
+export function modifyRole(
+  roleId: string,
+  updates: Partial<KxmRoleDefinition>,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { id: string; role: KxmRoleDefinition; filePath: string; scope: "global" | "local" } {
+  const target = getRole(roleId, { scope: options.scope, repoRoot: options.repoRoot, userConfigDir: options.userConfigDir });
+  if (!target) {
+    throw new Error(`role_not_found: role '${roleId}' does not exist`);
+  }
+
+  const updated: KxmRoleDefinition = {
+    ...target.role,
+    ...updates,
+    schema: KXM_ROLE_SCHEMA,
+    id: roleId, // preserve identity
+  };
+
+  const scope = options.scope ?? target.scope;
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${roleId}.yaml`);
+
+  writeFileSync(filePath, stringify(updated), "utf8");
+  return { id: roleId, role: updated, filePath, scope };
+}

package/plugins/kxm/src/routing.ts

@@ -532,9 +532,106 @@ export interface RoutingReport {
 export interface GenerateRoutingReportOptions {
   catalog?: PriceCatalog | undefined;
   includeEquivalentListCost?: boolean | undefined;
+  halfLifeDays?: number | undefined;
   now?: () => string;
 }
 
+/**
+ * Calculates exponential decay weight for historical telemetry (Decision Q14).
+ * Weight w = 2^(-delta_t / halfLifeDays).
+ */
+export function computeDecayedWeight(
+  recordedAt: string | number,
+  halfLifeDays: number = 14,
+  now: number = Date.now(),
+): number {
+  const ts = typeof recordedAt === "number" ? recordedAt : Date.parse(recordedAt);
+  if (!Number.isFinite(ts)) return 1.0;
+  const deltaMs = Math.max(0, now - ts);
+  const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1000;
+  return Math.pow(2, -deltaMs / halfLifeMs);
+}
+
+export interface RouteCircuitStatus {
+  status: "healthy" | "demoted" | "quarantined";
+  consecutiveFailures: number;
+  penaltyMultiplier: number;
+  reason?: string | undefined;
+}
+
+/**
+ * Evaluates route health against the circuit breaker policy (Decision Q13).
+ * Detects failure streaks in the observation window and applies soft demotion or quarantine.
+ */
+export function evaluateCircuitBreaker(
+  records: Array<RoutingRecord | RoutingRecordV2>,
+  route: { harness: string; model: string },
+  config?: {
+    mode?: "soft_demotion" | "quarantine" | undefined;
+    failureThreshold?: number | undefined;
+    windowSeconds?: number | undefined;
+    penaltyMultiplier?: number | undefined;
+  },
+  now: number = Date.now(),
+): RouteCircuitStatus {
+  const mode = config?.mode ?? "soft_demotion";
+  const failureThreshold = config?.failureThreshold ?? 3;
+  const windowSeconds = config?.windowSeconds ?? 3600;
+  const penaltyMultiplier = config?.penaltyMultiplier ?? 5.0;
+  const windowMs = windowSeconds * 1000;
+
+  const matching = records.filter((r) => {
+    const isV2 = r.schema === ROUTING_RECORD_V2_SCHEMA;
+    const harness = isV2 ? (r as RoutingRecordV2).harness : (r.providerMetadata?.harness as string | undefined);
+    const model = isV2
+      ? ((r as RoutingRecordV2).effectiveModel || (r as RoutingRecordV2).requestedModel)
+      : (r.effectiveModel || r.requestedModel);
+    if (harness !== route.harness || model !== route.model) return false;
+
+    const recAt = (r as any).recordedAt;
+    const ts = typeof recAt === "string" ? Date.parse(recAt) : 0;
+    return ts >= (now - windowMs);
+  });
+
+  matching.sort((a, b) => {
+    const ta = typeof (a as any).recordedAt === "string" ? Date.parse((a as any).recordedAt) : 0;
+    const tb = typeof (b as any).recordedAt === "string" ? Date.parse((b as any).recordedAt) : 0;
+    return tb - ta;
+  });
+
+  let consecutiveFailures = 0;
+  for (const r of matching) {
+    const passed = r.verifierOutcome === "passed" || r.finalOutcome === "accepted" || r.finalOutcome === "completed";
+    if (passed && (r.retries ?? 0) === 0) {
+      break;
+    }
+    consecutiveFailures++;
+  }
+
+  if (consecutiveFailures >= failureThreshold) {
+    if (mode === "quarantine") {
+      return {
+        status: "quarantined",
+        consecutiveFailures,
+        penaltyMultiplier,
+        reason: `Route quarantined after ${consecutiveFailures} consecutive failures within ${windowSeconds}s`,
+      };
+    }
+    return {
+      status: "demoted",
+      consecutiveFailures,
+      penaltyMultiplier,
+      reason: `Route demoted with ${penaltyMultiplier}x penalty after ${consecutiveFailures} consecutive failures`,
+    };
+  }
+
+  return {
+    status: "healthy",
+    consecutiveFailures,
+    penaltyMultiplier: 1.0,
+  };
+}
+
 export function generateRoutingReport(
   records: Array<RoutingRecord | RoutingRecordV2>,
   options: GenerateRoutingReportOptions = {},
@@ -675,7 +772,8 @@ export function generateRoutingReport(
             tokensIn: r.tokensIn ?? null,
             tokensOut: r.tokensOut ?? null,
             cacheReadTokens: r.cacheReadTokens ?? null,
-            contextTokens: (v2?.contextTokens ?? r.tokensIn) ?? null,
+            cacheWriteTokens: v2?.cacheWriteTokens ?? null,
+            contextTokens: v2?.contextTokens ?? null,
           });
           if (calc) {
             equivTotal += calc.costUsd;

package/plugins/kxm/src/session-work.ts

@@ -553,13 +553,20 @@ export function sessionBriefPickerEnabled(input: { env?: NodeJS.ProcessEnv; mode
   return reason === "startup" || reason === "new" || reason === "fork";
 }
 
-export const KXM_SLASH_SUBCOMMANDS = ["status", "hub", "memory", "help"] as const;
+export const KXM_SLASH_SUBCOMMANDS = ["status", "hub", "memory", "progress", "workflow", "help"] as const;
 export type KxmSlashCommand = "brief" | typeof KXM_SLASH_SUBCOMMANDS[number];
 
 export function parseKxmSlashArgs(args: string | undefined): KxmSlashCommand {
   const raw = String(args ?? "").trim().toLowerCase();
   if (raw === "" || raw === "brief") return "brief";
-  if (raw === "status" || raw === "hub" || raw === "memory" || raw === "help") return raw;
+  if (
+    raw === "status"
+    || raw === "hub"
+    || raw === "memory"
+    || raw === "progress"
+    || raw === "workflow"
+    || raw === "help"
+  ) return raw;
   return "help";
 }