@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/src/model-inventory.ts

@@ -0,0 +1,127 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { defaultSpawn } from "./vnext-oneshot-process.ts";
+
+export interface InventoryPrice {
+  inputPerMillion: number | null;
+  outputPerMillion: number | null;
+  cacheReadPerMillion: number | null;
+  cacheWritePerMillion: number | null;
+}
+
+export interface InventoryCapabilities {
+  thinking: { supported: boolean | null; levels?: string[]; default?: string; source: string };
+  speed: { fast: boolean | null; tiers?: string[]; source: string };
+}
+
+export interface InventoryModel {
+  id: string;
+  name?: string;
+  contextLength?: number;
+  capabilities: InventoryCapabilities;
+  standard?: InventoryPrice;
+  discount?: InventoryPrice;
+  sources: string[];
+}
+
+export interface ModelInventory {
+  schema: "kxm.model-inventory.v1";
+  fetchedAt: string;
+  currency: "USD";
+  sources: Record<string, { url: string; ok: boolean; error?: string }>;
+  models: InventoryModel[];
+}
+
+const OR_URL = "https://openrouter.ai/api/v1/models";
+const NOUS_URL = "https://inference-api.nousresearch.com/v1/models";
+
+function price(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value * 1_000_000;
+  if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) && Number(value) >= 0) return Number(value) * 1_000_000;
+  return null;
+}
+function rates(raw: any): InventoryPrice | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const input = price(raw.prompt ?? raw.input);
+  const output = price(raw.completion ?? raw.output);
+  if (input === null && output === null) return undefined;
+  return {
+    inputPerMillion: input,
+    outputPerMillion: output,
+    cacheReadPerMillion: price(raw.input_cache_read ?? raw.cache_read),
+    cacheWritePerMillion: price(raw.input_cache_write ?? raw.cache_write),
+  };
+}
+function modelId(id: string): string {
+  return id.trim().toLowerCase();
+}
+async function fetchModels(url: string, authorization?: string): Promise<{ data: any[]; error?: string }> {
+  try {
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (authorization) headers.Authorization = `Bearer ${authorization}`;
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(15_000) });
+    if (!response.ok) return { data: [], error: `HTTP ${response.status}` };
+    const payload = await response.json() as any;
+    if (Array.isArray(payload?.data)) return { data: payload.data };
+    return { data: [], error: "response has no data array" };
+  } catch (error) {
+    return { data: [], error: error instanceof Error ? error.message : "request failed" };
+  }
+}
+
+/** Refreshes a provenance-bearing model inventory. Aggregator prices are never treated as native auth evidence. */
+export async function refreshModelInventory(options: { outputRoot: string; env?: NodeJS.ProcessEnv; now?: Date }): Promise<ModelInventory> {
+  const env = options.env ?? process.env;
+  const fetchedAt = (options.now ?? new Date()).toISOString();
+  const sources: ModelInventory["sources"] = {};
+  const byId = new Map<string, InventoryModel>();
+  const add = (item: any, source: string, kind: "standard" | "discount") => {
+    if (!item || typeof item.id !== "string" || !item.id.trim()) return;
+    const key = modelId(item.id);
+    const current: InventoryModel = byId.get(key) ?? { id: item.id, ...(typeof item.name === "string" ? { name: item.name } : {}), ...(typeof item.context_length === "number" ? { contextLength: item.context_length } : {}), capabilities: { thinking: { supported: null, source: "unknown" }, speed: { fast: null, source: "unknown" } }, sources: [] };
+    if (!current.sources.includes(source)) current.sources.push(source);
+    const parsed = rates(item.pricing);
+    if (parsed) {
+      if (kind === "standard") current.standard = parsed;
+      else current.discount = parsed;
+    }
+    if (!current.name && typeof item.name === "string") current.name = item.name;
+    if (!current.contextLength && typeof item.context_length === "number") current.contextLength = item.context_length;
+    const parameters = Array.isArray(item.supported_parameters) ? item.supported_parameters.filter((value: unknown): value is string => typeof value === "string") : [];
+    if (parameters.some((value: string) => /reasoning|thinking/i.test(value))) current.capabilities.thinking = { supported: true, source };
+    if (parameters.some((value: string) => /speed|service.?tier|fast/i.test(value))) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+    if (Array.isArray(item.thinkingLevels) && item.thinkingLevels.length > 0) current.capabilities.thinking = { supported: true, levels: item.thinkingLevels, ...(item.defaultThinking ? { default: item.defaultThinking } : {}), source };
+    if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+    byId.set(key, current);
+  };
+  const native = async (command: string, args: string[], source: string) => {
+    const result = await defaultSpawn(command, args, { env, timeoutMs: 20_000 });
+    const ok = result.code === 0 && !result.error;
+    sources[source] = { url: `${command} ${args.join(" ")}`, ok, ...(ok ? {} : { error: (result.stderr || result.error?.message || "command failed").trim().slice(0, 240) }) };
+    if (!ok) return;
+    for (const line of (result.stdout || "").split(/\r?\n/)) {
+      const parts = line.trim().split(/\s+/);
+      const id = source === "pi" && parts.length >= 2 && parts[0] !== "provider" ? `${parts[0]}/${parts[1]}` : parts[0];
+      if (id && /^[a-z0-9][a-z0-9._/-]+$/i.test(id) && id !== "Available") {
+        const effortMatch = source === "agy" ? id.match(/-(low|medium|high)$/i) : null;
+        add({ id, ...(effortMatch?.[1] ? { thinkingLevels: [effortMatch[1].toLowerCase()] } : {}) }, source, "standard");
+      }
+    }
+  };
+  await native("pi", ["--list-models"], "pi");
+  await native("grok", ["models"], "grok");
+  await native("agy", ["models"], "agy");
+  const openrouter = await fetchModels(env.KXM_OPENROUTER_MODELS_URL?.trim() || OR_URL, env.OPENROUTER_API_KEY);
+  const openrouterUrl = env.KXM_OPENROUTER_MODELS_URL?.trim() || OR_URL;
+  sources.openrouter = { url: openrouterUrl, ok: !openrouter.error, ...(openrouter.error ? { error: openrouter.error } : {}) };
+  for (const item of openrouter.data) add(item, "openrouter", "standard");
+  const nousUrl = env.KXM_NOUS_MODELS_URL?.trim() || NOUS_URL;
+  const nous = await fetchModels(nousUrl, env.NOUS_API_KEY);
+  sources.nous = { url: nousUrl, ok: !nous.error, ...(nous.error ? { error: nous.error } : {}) };
+  for (const item of nous.data) add(item, "nous", "discount");
+  const inventory: ModelInventory = { schema: "kxm.model-inventory.v1", fetchedAt, currency: "USD", sources, models: [...byId.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+  mkdirSync(join(options.outputRoot, ".kxm", "models"), { recursive: true });
+  writeFileSync(join(options.outputRoot, ".kxm", "models", "inventory.yaml"), stringify(inventory), "utf8");
+  return inventory;
+}

package/plugins/kxm/src/modes.ts

@@ -0,0 +1,348 @@
+/**
+ * KXM Declarative Workflow Modes, Domain Isolation, and Pre-Flight Explain
+ *
+ * Implements major modes (base role + tools + prompt) and stackable domain
+ * toolkits to eliminate prompt bloat and calculate pre-flight token costs.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { calculateModelCost, type PriceCatalog, loadPriceCatalog } from "./prices.ts";
+
+export interface MajorMode {
+  description?: string | undefined;
+  baseTools: string[];
+  contextFiles?: string[] | undefined;
+  thinkingLevel?: "low" | "medium" | "high" | "xhigh" | undefined;
+  model?: string | undefined;
+}
+
+export interface Domain {
+  description?: string | undefined;
+  tools: string[];
+  contextFiles?: string[] | undefined;
+  promptSnippet?: string | undefined;
+}
+
+export interface ModesConfig {
+  schema: "kxm.modes.v1";
+  majorModes: Record<string, MajorMode>;
+  domains?: Record<string, Domain> | undefined;
+}
+
+export interface ResolvedMode {
+  majorMode: string;
+  enabledDomains: string[];
+  tools: string[];
+  contextFiles: string[];
+  promptSnippets: string[];
+  thinkingLevel?: string | undefined;
+  model?: string | undefined;
+}
+
+export interface ContextBreakdownItem {
+  name: string;
+  chars: number;
+  estimatedTokens: number;
+}
+
+export interface PromptFootprint {
+  majorMode: string;
+  enabledDomains: string[];
+  model: string;
+  breakdown: ContextBreakdownItem[];
+  totalChars: number;
+  totalTokens: number;
+  contextWindowRatio: number;
+  projectedCost: {
+    inputCostUsd: number | null;
+    cacheReadCostUsd: number | null;
+    outputCostEstimateUsd: number | null;
+  };
+}
+
+export const DEFAULT_MODES_CONFIG: ModesConfig = Object.freeze({
+  schema: "kxm.modes.v1",
+  majorModes: {
+    coder: {
+      description: "First-pass implementation, bug fixing, and test authoring",
+      baseTools: ["read", "edit", "write", "bash"],
+      contextFiles: ["AGENTS.md"],
+      thinkingLevel: "medium" as const,
+      model: "grok/grok-4.6",
+    },
+    planner: {
+      description: "High-level architectural planning, scoping, and decomposition",
+      baseTools: ["read", "grep", "find"],
+      contextFiles: ["plans/implementation-plan.md"],
+      thinkingLevel: "high" as const,
+      model: "claude/fable",
+    },
+    auditor: {
+      description: "Security, compliance, and code quality verification",
+      baseTools: ["read", "grep"],
+      contextFiles: ["SECURITY.md"],
+      thinkingLevel: "high" as const,
+      model: "codex/gpt-5.6-sol",
+    },
+    browser: {
+      description: "Web application exploration, screenshotting, and UI testing",
+      baseTools: ["read", "bash"],
+      contextFiles: ["docs/browser-automation.md"],
+      thinkingLevel: "medium" as const,
+      model: "grok/grok-4.6",
+    },
+  },
+  domains: {
+    git: {
+      description: "Git version control operations",
+      tools: ["git_status", "git_diff", "git_commit"],
+      promptSnippet: "Follow git branch conventions; never commit directly to main.",
+    },
+    k8s: {
+      description: "Kubernetes cluster inspection and deployment",
+      tools: ["kubectl_get", "kubectl_describe"],
+      promptSnippet: "Target local dev cluster; verify namespaces before mutating.",
+    },
+    database: {
+      description: "Database queries and schema verification",
+      tools: ["sqlite_query", "sqlite_schema"],
+      promptSnippet: "Database is SQLite at .kxm/state/kxm.db; use read-only queries.",
+    },
+    browser: {
+      description: "Remote Steel browser sessions and visual testing",
+      tools: ["steel_session", "steel_scrape", "steel_screenshot"],
+      promptSnippet: "Use Steel on DOKS for browser automation; invoke takeover on MFA.",
+    },
+  },
+});
+
+/**
+ * Estimate tokens from character count using standard ~4 chars/token heuristic.
+ */
+export function estimateTokens(charCount: number): number {
+  return Math.ceil(charCount / 3.8);
+}
+
+/**
+ * Load and validate `.kxm/modes.yaml` from project root or return defaults.
+ */
+export function loadModesConfig(projectRoot?: string): ModesConfig {
+  if (!projectRoot) {
+    return DEFAULT_MODES_CONFIG;
+  }
+
+  const modesPath = join(projectRoot, ".kxm", "modes.yaml");
+  if (!existsSync(modesPath)) {
+    return DEFAULT_MODES_CONFIG;
+  }
+
+  try {
+    const raw = readFileSync(modesPath, "utf8");
+    const parsed = parse(raw) as Partial<ModesConfig>;
+    if (parsed && parsed.schema === "kxm.modes.v1" && parsed.majorModes) {
+      return {
+        schema: "kxm.modes.v1",
+        majorModes: { ...DEFAULT_MODES_CONFIG.majorModes, ...parsed.majorModes },
+        domains: { ...DEFAULT_MODES_CONFIG.domains, ...parsed.domains },
+      };
+    }
+  } catch {
+    // Malformed config falls back to default safely
+  }
+
+  return DEFAULT_MODES_CONFIG;
+}
+
+/**
+ * Resolve active tools, context files, and prompt snippets for a major mode and domain set.
+ */
+export function resolveActiveMode(
+  config: ModesConfig,
+  majorModeName = "coder",
+  domainNames: string[] = []
+): ResolvedMode {
+  const major = config.majorModes[majorModeName] || config.majorModes["coder"] || DEFAULT_MODES_CONFIG.majorModes["coder"]!;
+  const tools = new Set<string>(major.baseTools);
+  const contextFiles = new Set<string>(major.contextFiles || []);
+  const promptSnippets: string[] = [];
+
+  const enabledDomains: string[] = [];
+
+  if (config.domains) {
+    for (const dName of domainNames) {
+      const d = config.domains[dName.toLowerCase().trim()];
+      if (d) {
+        enabledDomains.push(dName.toLowerCase().trim());
+        d.tools.forEach((t) => tools.add(t));
+        (d.contextFiles || []).forEach((f) => contextFiles.add(f));
+        if (d.promptSnippet) {
+          promptSnippets.push(d.promptSnippet);
+        }
+      }
+    }
+  }
+
+  return {
+    majorMode: majorModeName,
+    enabledDomains,
+    tools: Array.from(tools),
+    contextFiles: Array.from(contextFiles),
+    promptSnippets,
+    thinkingLevel: major.thinkingLevel,
+    model: major.model || "grok/grok-4.6",
+  };
+}
+
+/**
+ * Calculate the exact prompt token footprint and projected costs for a mode configuration.
+ */
+export function calculatePromptFootprint(
+  resolved: ResolvedMode,
+  projectRoot: string = process.cwd(),
+  catalog?: PriceCatalog
+): PromptFootprint {
+  const breakdown: ContextBreakdownItem[] = [];
+
+  // 1. Base System Prompt
+  const baseSystemPromptChars = 3200; // ~850 tokens base system prompt
+  breakdown.push({
+    name: `Base System Prompt (${resolved.majorMode})`,
+    chars: baseSystemPromptChars,
+    estimatedTokens: estimateTokens(baseSystemPromptChars),
+  });
+
+  // 2. Context Files
+  for (const relPath of resolved.contextFiles) {
+    const fullPath = join(projectRoot, relPath);
+    let chars = 0;
+    if (existsSync(fullPath)) {
+      try {
+        chars = readFileSync(fullPath, "utf8").length;
+      } catch {
+        chars = 0;
+      }
+    }
+    if (chars === 0) {
+      chars = 1500; // Estimated fallback if missing
+    }
+    breakdown.push({
+      name: `Context File: ${relPath}`,
+      chars,
+      estimatedTokens: estimateTokens(chars),
+    });
+  }
+
+  // 3. Domain Prompts
+  if (resolved.promptSnippets.length > 0) {
+    const snippetChars = resolved.promptSnippets.join("\n").length;
+    breakdown.push({
+      name: `Domain Prompts (${resolved.enabledDomains.join(", ")})`,
+      chars: snippetChars,
+      estimatedTokens: estimateTokens(snippetChars),
+    });
+  }
+
+  // 4. Tool Schemas
+  // Each MCP / standard tool schema consumes ~150-200 tokens
+  const toolSchemaChars = resolved.tools.length * 650;
+  breakdown.push({
+    name: `Tool Schemas (${resolved.tools.length} active tools)`,
+    chars: toolSchemaChars,
+    estimatedTokens: estimateTokens(toolSchemaChars),
+  });
+
+  const totalChars = breakdown.reduce((sum, item) => sum + item.chars, 0);
+  const totalTokens = breakdown.reduce((sum, item) => sum + item.estimatedTokens, 0);
+  const maxContextWindow = 200000;
+  const contextWindowRatio = Math.round((totalTokens / maxContextWindow) * 1000) / 10;
+
+  // 5. Projected Costs
+  const cat = catalog || loadPriceCatalog(projectRoot);
+  const rawModel = resolved.model || "grok/grok-4.6";
+  const [prov, mod] = rawModel.includes("/") ? rawModel.split("/", 2) : [undefined, rawModel];
+
+  const inputCost = cat
+    ? calculateModelCost(cat, {
+        model: mod || rawModel,
+        ...(prov !== undefined ? { provider: prov } : {}),
+        tokensIn: totalTokens,
+        tokensOut: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      })
+    : undefined;
+
+  const cacheReadCost = cat
+    ? calculateModelCost(cat, {
+        model: mod || rawModel,
+        ...(prov !== undefined ? { provider: prov } : {}),
+        tokensIn: 0,
+        tokensOut: 0,
+        cacheReadTokens: totalTokens,
+        cacheWriteTokens: 0,
+      })
+    : undefined;
+
+  const outputEstimateCost = cat
+    ? calculateModelCost(cat, {
+        model: mod || rawModel,
+        ...(prov !== undefined ? { provider: prov } : {}),
+        tokensIn: 0,
+        tokensOut: 1000,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      })
+    : undefined;
+
+  return {
+    majorMode: resolved.majorMode,
+    enabledDomains: resolved.enabledDomains,
+    model: resolved.model || "grok/grok-4.6",
+    breakdown,
+    totalChars,
+    totalTokens,
+    contextWindowRatio,
+    projectedCost: {
+      inputCostUsd: inputCost?.costUsd ?? null,
+      cacheReadCostUsd: cacheReadCost?.costUsd ?? null,
+      outputCostEstimateUsd: outputEstimateCost?.costUsd ?? null,
+    },
+  };
+}
+
+/**
+ * Format a human-readable ASCII report for `kxm explain`.
+ */
+export function formatModesExplainReport(footprint: PromptFootprint): string {
+  const divider = "═".repeat(60);
+  const subDivider = "─".repeat(60);
+
+  let out = `\n${divider}\n`;
+  out += `KXM PRE-FLIGHT CONTEXT EXPLAIN\n`;
+  out += `${divider}\n`;
+  out += `Major Mode:       ${footprint.majorMode}\n`;
+  out += `Enabled Domains:  ${footprint.enabledDomains.length > 0 ? footprint.enabledDomains.join(", ") : "(none)"}\n`;
+  out += `Target Model:     ${footprint.model}\n\n`;
+
+  out += `CONTEXT BREAKDOWN:\n`;
+  for (const item of footprint.breakdown) {
+    const padName = item.name.padEnd(38, " ");
+    const tokenStr = `${item.estimatedTokens.toLocaleString()} tokens`.padStart(16, " ");
+    out += `  • ${padName} ${tokenStr}\n`;
+  }
+
+  out += `${subDivider}\n`;
+  const totalPad = `TOTAL PROMPT FOOTPRINT:`.padEnd(38, " ");
+  const totalStr = `${footprint.totalTokens.toLocaleString()} tokens`.padStart(16, " ");
+  out += `  ${totalPad} ${totalStr} (${footprint.contextWindowRatio}% of 200k window)\n\n`;
+
+  out += `PROJECTED COSTS (per turn):\n`;
+  out += `  • Initial Turn Input Cost:   ${footprint.projectedCost.inputCostUsd !== null ? `$${footprint.projectedCost.inputCostUsd.toFixed(4)}` : "unmetered/unknown"}\n`;
+  out += `  • Subsequent Cache-Read Cost: ${footprint.projectedCost.cacheReadCostUsd !== null ? `$${footprint.projectedCost.cacheReadCostUsd.toFixed(4)} (approx 90% savings)` : "unmetered/unknown"}\n`;
+  out += `  • Output Estimate (1k tokens): ${footprint.projectedCost.outputCostEstimateUsd !== null ? `$${footprint.projectedCost.outputCostEstimateUsd.toFixed(4)}` : "unmetered/unknown"}\n`;
+  out += `${divider}\n`;
+
+  return out;
+}

package/plugins/kxm/src/policy-draft.d.mts

@@ -0,0 +1,55 @@
+import type { JsonObject } from "./restricted-yaml.mjs";
+
+export const POLICY_DRAFT_MODEL_SCHEMA: "kxm.model.v2";
+export const POLICY_DRAFT_ROLE_SCHEMA: "kxm.role.v2";
+export const POLICY_DRAFT_PURPOSES: readonly [
+  "writer",
+  "planner",
+  "reviewer-arch",
+  "reviewer-cli",
+  "experiment",
+];
+export const POLICY_DRAFT_PERMISSIONS: readonly ["edit", "read-only"];
+export const POLICY_DRAFT_STATUSES: readonly ["admitted", "candidate", "retired"];
+
+export interface PolicyDraftIssue {
+  phase: "parse" | "schema" | "reference" | "semantic";
+  code: string;
+  file: string;
+  message: string;
+}
+
+export interface PolicyDraftCeiling {
+  readonly provider: string;
+  readonly roles?: readonly string[];
+  readonly permissions: readonly string[];
+  readonly models?: readonly string[];
+  readonly efforts?: readonly string[];
+}
+
+export interface PolicyDraftOptions {
+  readonly ceilings: Readonly<Record<string, PolicyDraftCeiling>>;
+  readonly nativePiBrakeProviders: readonly string[];
+  readonly piAllowedProviders: readonly string[];
+  readonly vendorAliases?: Readonly<Record<string, string>>;
+}
+
+export type PolicyDraftDocument = JsonObject | string | Uint8Array;
+
+export interface PolicyDraftInput {
+  readonly models?: Readonly<Record<string, PolicyDraftDocument>> | readonly PolicyDraftDocument[];
+  readonly roles?: Readonly<Record<string, PolicyDraftDocument>> | readonly PolicyDraftDocument[];
+  readonly evidence?: Readonly<Record<string, string | Uint8Array>>;
+}
+
+export interface PolicyDraftData {
+  readonly models: Readonly<Record<string, JsonObject>>;
+  readonly roles: Readonly<Record<string, JsonObject>>;
+}
+
+export type PolicyDraftResult =
+  | { readonly ok: true; readonly data: PolicyDraftData }
+  | { readonly ok: false; readonly issues: readonly PolicyDraftIssue[] };
+
+/** Pure draft validation. Not admission, not a trusted loader, and not file I/O. */
+export function validatePolicyDraft(input: PolicyDraftInput, options: PolicyDraftOptions): PolicyDraftResult;