@kontextmind/kxm 0.7.0 → 0.7.10

package/plugins/kxm/src/role.ts

@@ -373,3 +373,338 @@ export function modifyRole(
   writeFileSync(filePath, stringify(updated), "utf8");
   return { id: roleId, role: updated, filePath, scope };
 }
+
+// ---------------------------------------------------------------------------
+// Role Seat & Host Mapping Governance (kxm.role-hosts.v1)
+// ---------------------------------------------------------------------------
+
+export const KXM_ROLE_HOSTS_SCHEMA = "kxm.role-hosts.v1" as const;
+
+export interface RoleSeatDefinition {
+  seatId: string;
+  description?: string | undefined;
+  defaultModel?: string | undefined;
+  defaultHost?: string | undefined;
+  allowedTools?: readonly string[] | undefined;
+  requiredEvidenceKind?: string | undefined;
+}
+
+export interface RoleSeatBinding {
+  model?: string | undefined;
+  host?: string | undefined;
+  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
+}
+
+export interface RoleHostsConfig {
+  schema: typeof KXM_ROLE_HOSTS_SCHEMA;
+  seats?: Record<string, RoleSeatBinding> | undefined;
+  hostProviders?: Record<string, string> | undefined;
+}
+
+export const DEFAULT_ROLE_SEATS: Record<string, RoleSeatDefinition> = {
+  planner: {
+    seatId: "planner",
+    description: "Architecture breakdown, requirement decomposition, and safety boundary definition.",
+    defaultModel: "anthropic/claude-fable-5.1",
+    defaultHost: "pi",
+    allowedTools: ["view_file", "grep_search", "find_by_name", "list_dir"],
+    requiredEvidenceKind: "architecture_review",
+  },
+  writer: {
+    seatId: "writer",
+    description: "Primary implementation agent. Writes code, refactors components, and authors unit tests.",
+    defaultModel: "x-ai/grok-4.6",
+    defaultHost: "grok",
+    allowedTools: ["view_file", "replace_file_content", "write_to_file", "run_command"],
+    requiredEvidenceKind: "git_diff",
+  },
+  "critic-arch": {
+    seatId: "critic-arch",
+    description: "Independent critic reviewing implementation diffs for architectural integrity.",
+    defaultModel: "anthropic/claude-fable-5.1",
+    defaultHost: "pi",
+    allowedTools: ["view_file", "grep_search"],
+    requiredEvidenceKind: "architecture_review",
+  },
+  "critic-cli": {
+    seatId: "critic-cli",
+    description: "CLI, documentation, and developer ergonomics critic.",
+    defaultModel: "openai/gpt-5.6-sol",
+    defaultHost: "pi",
+    allowedTools: ["view_file", "grep_search"],
+    requiredEvidenceKind: "cli_review",
+  },
+  verifier: {
+    seatId: "verifier",
+    description: "Deterministic gate evaluation runner.",
+    defaultModel: "evaluator",
+    defaultHost: "pi",
+    allowedTools: ["run_command"],
+    requiredEvidenceKind: "test_run",
+  },
+};
+
+export function roleHostsFilePath(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+  preferJson = false,
+): string {
+  const dir = scope === "global" ? userConfigDirectory(userConfigDir) : repoConfigDirectory(repoRoot);
+  return join(dir, preferJson ? "role-hosts.json" : "role-hosts.yaml");
+}
+
+export function findExistingRoleHostsFile(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+): { filePath: string; exists: boolean; format: "yaml" | "json" } {
+  const dir = scope === "global" ? userConfigDirectory(userConfigDir) : repoConfigDirectory(repoRoot);
+  const yamlPath = join(dir, "role-hosts.yaml");
+  const ymlPath = join(dir, "role-hosts.yml");
+  const jsonPath = join(dir, "role-hosts.json");
+
+  if (existsSync(yamlPath)) return { filePath: yamlPath, exists: true, format: "yaml" };
+  if (existsSync(ymlPath)) return { filePath: ymlPath, exists: true, format: "yaml" };
+  if (existsSync(jsonPath)) return { filePath: jsonPath, exists: true, format: "json" };
+  return { filePath: yamlPath, exists: false, format: "yaml" };
+}
+
+export function parseRoleHostsFile(filePath: string): RoleHostsConfig | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = parse(raw) as Partial<RoleHostsConfig>;
+    if (!parsed || typeof parsed !== "object") return undefined;
+    if (parsed.schema && parsed.schema !== KXM_ROLE_HOSTS_SCHEMA) return undefined;
+    return {
+      schema: KXM_ROLE_HOSTS_SCHEMA,
+      seats: parsed.seats && typeof parsed.seats === "object" ? parsed.seats : {},
+      hostProviders: parsed.hostProviders && typeof parsed.hostProviders === "object" ? parsed.hostProviders : {},
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function loadRoleHostsConfig(options: {
+  scope?: "all" | "global" | "local" | undefined;
+  repoRoot?: string | undefined;
+  userConfigDir?: string | undefined;
+} = {}): { config: RoleHostsConfig; filePath?: string | undefined; scope: "local" | "global" | "default" } {
+  const scopeFilter = options.scope ?? "all";
+  const repoRoot = options.repoRoot ?? process.cwd();
+
+  let localConfig: RoleHostsConfig | undefined;
+  let localPath: string | undefined;
+  if (scopeFilter !== "global") {
+    const localFound = findExistingRoleHostsFile("local", repoRoot, options.userConfigDir);
+    if (localFound.exists) {
+      localConfig = parseRoleHostsFile(localFound.filePath);
+      localPath = localFound.filePath;
+    }
+  }
+
+  let globalConfig: RoleHostsConfig | undefined;
+  let globalPath: string | undefined;
+  if (scopeFilter !== "local") {
+    const globalFound = findExistingRoleHostsFile("global", repoRoot, options.userConfigDir);
+    if (globalFound.exists) {
+      globalConfig = parseRoleHostsFile(globalFound.filePath);
+      globalPath = globalFound.filePath;
+    }
+  }
+
+  if (scopeFilter === "local") {
+    return {
+      config: localConfig ?? { schema: KXM_ROLE_HOSTS_SCHEMA, seats: {}, hostProviders: {} },
+      filePath: localPath,
+      scope: localPath ? "local" : "default",
+    };
+  }
+
+  if (scopeFilter === "global") {
+    return {
+      config: globalConfig ?? { schema: KXM_ROLE_HOSTS_SCHEMA, seats: {}, hostProviders: {} },
+      filePath: globalPath,
+      scope: globalPath ? "global" : "default",
+    };
+  }
+
+  // Merge: local seats override global seats; local hostProviders merge over global hostProviders
+  const mergedSeats: Record<string, RoleSeatBinding> = {
+    ...(globalConfig?.seats ?? {}),
+    ...(localConfig?.seats ?? {}),
+  };
+  const mergedHostProviders: Record<string, string> = {
+    ...(globalConfig?.hostProviders ?? {}),
+    ...(localConfig?.hostProviders ?? {}),
+  };
+
+  const primaryPath = localPath ?? globalPath;
+  const primaryScope = localPath ? "local" : (globalPath ? "global" : "default");
+
+  return {
+    config: {
+      schema: KXM_ROLE_HOSTS_SCHEMA,
+      seats: mergedSeats,
+      hostProviders: mergedHostProviders,
+    },
+    filePath: primaryPath,
+    scope: primaryScope,
+  };
+}
+
+export function saveRoleHostsConfig(
+  config: RoleHostsConfig,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+    format?: "yaml" | "json" | undefined;
+  } = {},
+): { filePath: string; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = scope === "global" ? userConfigDirectory(options.userConfigDir) : repoConfigDirectory(repoRoot);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const format = options.format ?? "yaml";
+  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
+  const payload: RoleHostsConfig = {
+    schema: KXM_ROLE_HOSTS_SCHEMA,
+    seats: config.seats ?? {},
+    ...(config.hostProviders && Object.keys(config.hostProviders).length > 0 ? { hostProviders: config.hostProviders } : {}),
+  };
+
+  const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : stringify(payload);
+  writeFileSync(filePath, content, "utf8");
+  return { filePath, scope };
+}
+
+export function setRoleSeatHost(
+  seatId: string,
+  host: string,
+  options: {
+    model?: string | undefined;
+    effort?: "low" | "medium" | "high" | "xhigh" | undefined;
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+    format?: "yaml" | "json" | undefined;
+  } = {},
+): { filePath: string; seatId: string; binding: RoleSeatBinding; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const current = loadRoleHostsConfig({
+    scope,
+    repoRoot: options.repoRoot,
+    userConfigDir: options.userConfigDir,
+  });
+
+  const seats = { ...(current.config.seats ?? {}) };
+  const existing = seats[seatId] ?? {};
+  const binding: RoleSeatBinding = {
+    ...existing,
+    host,
+    ...(options.model !== undefined ? { model: options.model } : {}),
+    ...(options.effort !== undefined ? { effort: options.effort } : {}),
+  };
+  seats[seatId] = binding;
+
+  const updatedConfig: RoleHostsConfig = {
+    ...current.config,
+    schema: KXM_ROLE_HOSTS_SCHEMA,
+    seats,
+  };
+
+  const saved = saveRoleHostsConfig(updatedConfig, {
+    scope,
+    repoRoot: options.repoRoot,
+    userConfigDir: options.userConfigDir,
+    format: options.format,
+  });
+
+  return { filePath: saved.filePath, seatId, binding, scope };
+}
+
+export function resolveRoleSeat(
+  seatId: string,
+  options: {
+    hostOverride?: string | undefined;
+    modelOverride?: string | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): {
+  seatId: string;
+  host: string;
+  model?: string | undefined;
+  provider?: string | undefined;
+  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
+  source: "override" | "role-hosts" | "seat-default" | "role-roster" | "fallback";
+} {
+  const hostsConfig = loadRoleHostsConfig({
+    scope: "all",
+    repoRoot: options.repoRoot,
+    userConfigDir: options.userConfigDir,
+  }).config;
+
+  const configuredSeat = hostsConfig.seats?.[seatId];
+  const defaultSeat = DEFAULT_ROLE_SEATS[seatId];
+  const roleDef = getRole(seatId, {
+    scope: "all",
+    repoRoot: options.repoRoot,
+    userConfigDir: options.userConfigDir,
+  })?.role ?? DEFAULT_ROLES[seatId];
+  const primaryRoster = roleDef?.roster?.[0];
+
+  // Resolve host
+  let host = "pi";
+  let source: "override" | "role-hosts" | "seat-default" | "role-roster" | "fallback" = "fallback";
+
+  if (options.hostOverride) {
+    host = options.hostOverride;
+    source = "override";
+  } else if (configuredSeat?.host) {
+    host = configuredSeat.host;
+    source = "role-hosts";
+  } else if (defaultSeat?.defaultHost) {
+    host = defaultSeat.defaultHost;
+    source = "seat-default";
+  } else if (primaryRoster?.harness) {
+    host = primaryRoster.harness;
+    source = "role-roster";
+  }
+
+  // Resolve model
+  let model: string | undefined;
+  if (options.modelOverride) {
+    model = options.modelOverride;
+  } else if (configuredSeat?.model) {
+    model = configuredSeat.model;
+  } else if (defaultSeat?.defaultModel) {
+    model = defaultSeat.defaultModel;
+  } else if (primaryRoster?.model) {
+    model = primaryRoster.model;
+  }
+
+  // Resolve provider
+  const provider = hostsConfig.hostProviders?.[host]
+    ?? roleDef?.roster?.find((r) => r.harness === host)?.provider;
+
+  // Resolve effort
+  const effort = configuredSeat?.effort
+    ?? roleDef?.roster?.find((r) => r.harness === host)?.effort;
+
+  return {
+    seatId,
+    host,
+    model,
+    provider,
+    effort,
+    source,
+  };
+}
+

package/plugins/kxm/src/runtime.ts

@@ -7,3 +7,7 @@ export * from "./vnext-harness.ts";
 export * from "./database.ts";
 export * from "./logger.ts";
 export * from "./improve.ts";
+export * from "./browser.ts";
+export * from "./modes.ts";
+export * from "./ssh-remote.ts";
+export * from "./subagent-control.ts";

package/plugins/kxm/src/safety-integrity.ts

@@ -0,0 +1,76 @@
+/**
+ * Safety, security, process integrity, and command seatbelts.
+ *
+ * Implements deterministic safety invariants:
+ * - Literal blocklist intercepting destructive shell mutations (rm -rf, git reset --hard, etc.)
+ * - Unbypassable raw byte fidelity brake for verification gates and critic reviews (bypassing lossy compression)
+ * - Pinned SSH host key verification policy for headless remote execution
+ */
+
+export const DESTRUCTIVE_COMMAND_PATTERNS: readonly RegExp[] = Object.freeze([
+  /^\s*rm\s+.*-[a-zA-Z]*r[a-zA-Z]*f/i,
+  /^\s*rm\s+.*-[a-zA-Z]*f[a-zA-Z]*r/i,
+  /^\s*rm\s+.*(-[a-zA-Z]*r[a-zA-Z]*\s+.*-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+.*-[a-zA-Z]*r[a-zA-Z]*)/i,
+  /^\s*git\s+reset\s+--hard/i,
+  /^\s*git\s+clean\s+-[a-zA-Z]*f/i,
+  /^\s*git\s+checkout\s+--\s+/i,
+  /^\s*git\s+restore\s+(\.|\*|--staged\s+(\.|\*))/i,
+]);
+
+/**
+ * Literal command seatbelt: blocks destructive mutations from autonomous agents.
+ * Throws a descriptive error if command matches any destructive pattern.
+ */
+export function assertCommandSeatbelt(command: string): void {
+  for (const pattern of DESTRUCTIVE_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      throw new Error(
+        `Command blocked by KXM safety seatbelt: "${command}". Destructive workspace mutations require explicit operator override.`,
+      );
+    }
+  }
+}
+
+export interface RtkBypassContext {
+  stepKind?: string | undefined;
+  agentRole?: string | undefined;
+  preset?: string | undefined;
+}
+
+const CRITIC_PRESETS = new Set(["critic-arch", "critic-cli", "auditor"]);
+const CRITIC_ROLES = new Set(["critic-arch", "critic-cli", "auditor", "reviewer-arch", "reviewer-cli"]);
+
+/**
+ * Gate and Critic RTK Brake:
+ * Hardcode an unbypassable check ensuring lossy command output compression (RTK)
+ * is strictly prohibited for:
+ * 1. Verification gates (stepKind === "gate")
+ * 2. Critic and auditor agents (critic-arch, critic-cli, auditor)
+ */
+export function isRtkBypassRequired(context: RtkBypassContext): boolean {
+  if (context.stepKind === "gate") return true;
+  if (context.agentRole && CRITIC_ROLES.has(context.agentRole)) return true;
+  if (context.preset && CRITIC_PRESETS.has(context.preset)) return true;
+  return false;
+}
+
+const INSECURE_SSH_HOST_KEY_PATTERNS: readonly RegExp[] = Object.freeze([
+  /StrictHostKeyChecking=(accept-new|no|off)/i,
+  /UserKnownHostsFile=\/dev\/null/i,
+]);
+
+/**
+ * Pinned host key verification policy for headless SSH remote execution.
+ * Rejects TOFU (accept-new) and disabled host key checking.
+ */
+export function assertPinnedSshHostKeyPolicy(sshArgs: readonly string[]): void {
+  for (const arg of sshArgs) {
+    for (const pattern of INSECURE_SSH_HOST_KEY_PATTERNS) {
+      if (pattern.test(arg)) {
+        throw new Error(
+          `Insecure SSH host key policy rejected: "${arg}". KXM headless SSH requires pinned host keys with StrictHostKeyChecking=yes and BatchMode=yes.`,
+        );
+      }
+    }
+  }
+}

package/plugins/kxm/src/sqlite.ts

@@ -0,0 +1,76 @@
+/** Runtime-portable SQLite constructor.
+ *
+ * Prefers Node's built-in `node:sqlite` (the supported runtime for the kxm
+ * CLI). Pi loads extensions inside its embedded Bun runtime, which does not
+ * provide `node:sqlite`, so fall back to Bun's `bun:sqlite` there.
+ *
+ * The two runtimes differ in one option this codebase uses: Node spells the
+ * flag `readOnly`, Bun spells it `readonly`. Options are normalized here so
+ * callers keep using the Node spelling everywhere.
+ */
+import { createRequire } from "node:module";
+
+export interface DatabaseSyncOptions {
+  readOnly?: boolean;
+  [key: string]: unknown;
+}
+
+export interface StatementSync {
+  run(...params: unknown[]): { changes: number | bigint; lastInsertRowid: number | bigint };
+  get(...params: unknown[]): Record<string, unknown> | undefined;
+  all(...params: unknown[]): Array<Record<string, unknown>>;
+}
+
+type NativeDatabase = {
+  prepare(sql: string): StatementSync;
+  exec(sql: string): unknown;
+  close(): void;
+};
+
+const requireFromHere = createRequire(import.meta.url);
+
+function loadNative(): { Ctor: new (path: string, options?: object) => NativeDatabase; bun: boolean } {
+  try {
+    const mod = requireFromHere("node:sqlite") as { DatabaseSync?: new (path: string, options?: object) => NativeDatabase };
+    if (mod.DatabaseSync) return { Ctor: mod.DatabaseSync, bun: false };
+  } catch {
+    // Not a Node runtime exposing node:sqlite (e.g. pi's embedded Bun).
+  }
+  try {
+    const mod = requireFromHere("bun:sqlite") as
+      | { DatabaseSync?: new (path: string, options?: object) => NativeDatabase; Database?: new (path: string, options?: object) => NativeDatabase }
+      | undefined;
+    const Ctor = mod?.DatabaseSync ?? mod?.Database;
+    if (Ctor) return { Ctor, bun: true };
+  } catch {
+    // No bun:sqlite either.
+  }
+  throw new Error("kxm: no supported sqlite module found (need node:sqlite or bun:sqlite)");
+}
+
+const native = loadNative();
+
+export class DatabaseSync {
+  private readonly inner: NativeDatabase;
+
+  constructor(path: string, options?: DatabaseSyncOptions) {
+    let normalized: object | undefined = options;
+    if (native.bun && options) {
+      const { readOnly, ...rest } = options;
+      normalized = readOnly === undefined ? rest : { ...rest, readonly: readOnly };
+    }
+    this.inner = normalized === undefined ? new native.Ctor(path) : new native.Ctor(path, normalized);
+  }
+
+  prepare(sql: string): StatementSync {
+    return this.inner.prepare(sql);
+  }
+
+  exec(sql: string): unknown {
+    return this.inner.exec(sql);
+  }
+
+  close(): void {
+    this.inner.close();
+  }
+}