@kontextmind/kxm 0.6.0 → 0.7.10

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/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/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";
 }
 

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();
+  }
+}