@kontextmind/kxm 0.6.0 → 0.7.0

package/plugins/kxm/src/external-effects.ts

@@ -5,11 +5,24 @@
 
 import { DatabaseSync } from "node:sqlite";
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import {
+  mkdirSync,
+  openSync,
+  closeSync,
+  writeFileSync,
+  readFileSync,
+  unlinkSync,
+  existsSync,
+  lstatSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
 
 export const EXTERNAL_EFFECT_SCHEMA = "kxm.external-effect-receipt.v1" as const;
 
+export const DEFAULT_LEASE_TIMEOUT_MS = 300_000; // 300s (5 minutes) per Decision Q6
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000; // 30s per Decision Q6
+
 export type ExternalActionKind =
   | "git-branch"
   | "git-commit"
@@ -32,6 +45,7 @@ export interface ExternalEffectReceipt {
   payloadHash: string;
   receiptPayload: Record<string, unknown>;
   executedAt: string;
+  lastHeartbeatAt?: string | undefined;
   completedAt?: string | undefined;
 }
 
@@ -124,15 +138,22 @@ export class ExternalEffectsLedger {
         payload_hash TEXT NOT NULL,
         receipt_payload TEXT NOT NULL,
         executed_at TEXT NOT NULL,
+        last_heartbeat_at TEXT,
         completed_at TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_ext_effects_run ON external_effects(run_id);
     `);
+    try {
+      this.db.exec(`ALTER TABLE external_effects ADD COLUMN last_heartbeat_at TEXT;`);
+    } catch {
+      // Column already present in schema
+    }
   }
 
   /**
    * Preflight Check-And-Set (CAS):
    * Guarantees that an external mutation is only initiated if not already committed or currently in-flight.
+   * Auto-reclaims stale leases after timeoutMs (default 300s per Decision Q6).
    */
   claimEffect(input: {
     runId: string;
@@ -147,6 +168,7 @@ export class ExternalEffectsLedger {
     const now = new Date().toISOString();
     const payloadStr = JSON.stringify(input.payload ?? {});
     const payloadHash = createHash("sha256").update(payloadStr).digest("hex");
+    const timeout = input.timeoutMs ?? DEFAULT_LEASE_TIMEOUT_MS;
 
     const existing = this.getReceipt(effectKey);
     if (existing) {
@@ -158,8 +180,8 @@ export class ExternalEffectsLedger {
         };
       }
       if (existing.status === "in-flight") {
-        const timeout = input.timeoutMs ?? 60000;
-        const elapsed = Date.now() - Date.parse(existing.executedAt);
+        const lastActivity = existing.lastHeartbeatAt ?? existing.executedAt;
+        const elapsed = Date.now() - Date.parse(lastActivity);
         if (elapsed < timeout) {
           return {
             ok: false,
@@ -167,19 +189,20 @@ export class ExternalEffectsLedger {
             existing,
           };
         }
-        // If timed out, allow reclaim by updating status
+        // If timed out, allow reclaim by updating status and timestamps
       }
     }
 
     const stmt = this.db.prepare(`
       INSERT INTO external_effects (
         effect_key, run_id, step_id, attempt_id, action_kind, target_ref,
-        status, payload_hash, receipt_payload, executed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        status, payload_hash, receipt_payload, executed_at, last_heartbeat_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(effect_key) DO UPDATE SET
         attempt_id = excluded.attempt_id,
         status = 'in-flight',
         executed_at = excluded.executed_at,
+        last_heartbeat_at = excluded.last_heartbeat_at,
         payload_hash = excluded.payload_hash,
         receipt_payload = excluded.receipt_payload
     `);
@@ -195,11 +218,37 @@ export class ExternalEffectsLedger {
       payloadHash,
       payloadStr,
       now,
+      now,
     );
 
     return { ok: true, effectKey };
   }
 
+  /**
+   * Refreshes the lease heartbeat for an in-flight effect (Decision Q6).
+   * Workers invoke this periodically (default 30s) while performing side-effects.
+   */
+  heartbeatEffect(effectKey: string): { ok: true; lastHeartbeatAt: string } | { ok: false; error: string } {
+    const existing = this.getReceipt(effectKey);
+    if (!existing) {
+      return { ok: false, error: `effect_not_found: effect ${effectKey} does not exist` };
+    }
+    if (existing.status !== "in-flight") {
+      return {
+        ok: false,
+        error: `effect_not_in_flight: cannot heartbeat effect in status '${existing.status}'`,
+      };
+    }
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      UPDATE external_effects
+      SET last_heartbeat_at = ?
+      WHERE effect_key = ? AND status = 'in-flight'
+    `);
+    stmt.run(now, effectKey);
+    return { ok: true, lastHeartbeatAt: now };
+  }
+
   commitEffect(
     effectKey: string,
     receiptPayload: Record<string, unknown>,
@@ -238,6 +287,7 @@ export class ExternalEffectsLedger {
       payload_hash: string;
       receipt_payload: string;
       executed_at: string;
+      last_heartbeat_at: string | null;
       completed_at: string | null;
     } | undefined;
 
@@ -255,6 +305,7 @@ export class ExternalEffectsLedger {
       payloadHash: row.payload_hash,
       receiptPayload: JSON.parse(row.receipt_payload) as Record<string, unknown>,
       executedAt: row.executed_at,
+      lastHeartbeatAt: row.last_heartbeat_at ?? undefined,
       completedAt: row.completed_at ?? undefined,
     };
   }
@@ -274,6 +325,7 @@ export class ExternalEffectsLedger {
       payload_hash: string;
       receipt_payload: string;
       executed_at: string;
+      last_heartbeat_at: string | null;
       completed_at: string | null;
     }>;
 
@@ -289,6 +341,7 @@ export class ExternalEffectsLedger {
       payloadHash: row.payload_hash,
       receiptPayload: JSON.parse(row.receipt_payload) as Record<string, unknown>,
       executedAt: row.executed_at,
+      lastHeartbeatAt: row.last_heartbeat_at ?? undefined,
       completedAt: row.completed_at ?? undefined,
     }));
   }
@@ -297,3 +350,299 @@ export class ExternalEffectsLedger {
     this.db.close();
   }
 }
+
+export interface WorktreeLock {
+  lockPath: string;
+  release: () => void;
+}
+
+/**
+ * Resolves the lockfile location for concurrent git worktree modifications.
+ * By default targets .git/kxm-worktree.lock, or if in a linked worktree, targets the main git directory.
+ */
+export function resolveWorktreeLockPath(repoRoot: string): string {
+  const gitPath = join(repoRoot, ".git");
+  if (existsSync(gitPath)) {
+    try {
+      const stat = lstatSync(gitPath);
+      if (stat.isDirectory()) {
+        return join(gitPath, "kxm-worktree.lock");
+      }
+      if (stat.isFile()) {
+        const content = readFileSync(gitPath, "utf8").trim();
+        const match = content.match(/^gitdir:\s*(.+)$/i);
+        if (match && match[1]) {
+          const resolvedGitDir = resolve(repoRoot, match[1]);
+          return join(resolvedGitDir, "kxm-worktree.lock");
+        }
+      }
+    } catch {
+      // Fall back
+    }
+  }
+  return join(repoRoot, ".kxm-worktree.lock");
+}
+
+/**
+ * Acquires an exclusive file-based lock for worktree mutations.
+ * Supports auto-breaking stale locks if the holding process has died or timed out.
+ */
+export function acquireWorktreeLock(
+  repoRoot: string,
+  options?: {
+    timeoutMs?: number | undefined;
+    staleTimeoutMs?: number | undefined;
+    pollIntervalMs?: number | undefined;
+  },
+): { ok: true; lock: WorktreeLock } | { ok: false; error: string } {
+  const lockPath = resolveWorktreeLockPath(repoRoot);
+  const timeoutMs = options?.timeoutMs ?? 5_000;
+  const staleTimeoutMs = options?.staleTimeoutMs ?? 30_000;
+  const pollIntervalMs = options?.pollIntervalMs ?? 50;
+  const startTime = Date.now();
+
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  while (true) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      const metadata = JSON.stringify({
+        pid: process.pid,
+        acquiredAt: new Date().toISOString(),
+        repoRoot,
+      });
+      writeFileSync(fd, metadata, "utf8");
+      closeSync(fd);
+
+      return {
+        ok: true,
+        lock: {
+          lockPath,
+          release: () => {
+            try {
+              unlinkSync(lockPath);
+            } catch {
+              // Ignore if already unlinked
+            }
+          },
+        },
+      };
+    } catch (err: unknown) {
+      const code = (err as { code?: string }).code;
+      if (code !== "EEXIST") {
+        return { ok: false, error: `lock_io_error: ${(err as Error).message}` };
+      }
+
+      // Existing lock found - check for staleness
+      try {
+        const content = readFileSync(lockPath, "utf8");
+        const parsed = JSON.parse(content) as { pid?: number; acquiredAt?: string };
+        let isStale = false;
+
+        if (parsed.acquiredAt) {
+          const age = Date.now() - Date.parse(parsed.acquiredAt);
+          if (age > staleTimeoutMs) {
+            isStale = true;
+          }
+        }
+
+        if (parsed.pid && typeof parsed.pid === "number") {
+          try {
+            process.kill(parsed.pid, 0);
+          } catch (e: unknown) {
+            if ((e as { code?: string }).code === "ESRCH") {
+              isStale = true; // Process dead
+            }
+          }
+        }
+
+        if (isStale) {
+          try {
+            unlinkSync(lockPath);
+            continue; // Immediately retry lock
+          } catch {
+            // Already unlinked or contention
+          }
+        }
+      } catch {
+        // Corrupt lock file
+        try {
+          unlinkSync(lockPath);
+          continue;
+        } catch {
+          // Ignore
+        }
+      }
+
+      if (Date.now() - startTime >= timeoutMs) {
+        return {
+          ok: false,
+          error: `lock_timeout: timed out after ${timeoutMs}ms waiting for worktree lock at ${lockPath}`,
+        };
+      }
+
+      if (pollIntervalMs > 0) {
+        const waitBuf = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(waitBuf, 0, 0, pollIntervalMs);
+      }
+    }
+  }
+}
+
+/**
+ * Runs a function inside an exclusive worktree lock.
+ */
+export async function withWorktreeLock<T>(
+  repoRoot: string,
+  fn: () => T | Promise<T>,
+  options?: {
+    timeoutMs?: number | undefined;
+    staleTimeoutMs?: number | undefined;
+    pollIntervalMs?: number | undefined;
+  },
+): Promise<T> {
+  const res = acquireWorktreeLock(repoRoot, options);
+  if (!res.ok) {
+    throw new Error(`worktree_lock_failed: ${res.error}`);
+  }
+  try {
+    return await fn();
+  } finally {
+    res.lock.release();
+  }
+}
+
+export interface BranchCleanupOptions {
+  removeWorktree?: boolean | undefined;
+  deleteRemote?: boolean | undefined;
+  remoteName?: string | undefined;
+  execFn?: ((cmd: string, args: string[]) => { status: number; stdout: string; stderr: string }) | undefined;
+}
+
+export interface BranchCleanupResult {
+  ok: boolean;
+  branchName: string;
+  deletedLocalBranch: boolean;
+  deletedRemoteBranch: boolean;
+  removedWorktreePath?: string | undefined;
+  error?: string | undefined;
+}
+
+/**
+ * Deterministic Branch Cleanup (Decision Q7).
+ * Removes associated git worktrees and deletes the local (and optionally remote) run branch.
+ */
+export function cleanupMergedRunBranch(
+  repoRoot: string,
+  branchName: string,
+  options?: BranchCleanupOptions,
+): BranchCleanupResult {
+  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 shouldRemoveWorktree = options?.removeWorktree ?? true;
+  let removedWorktreePath: string | undefined;
+  let deletedLocalBranch = false;
+  let deletedRemoteBranch = false;
+
+  // 1. Remove worktree if one is attached to this branch
+  if (shouldRemoveWorktree) {
+    try {
+      const wtList = runner("git", ["worktree", "list", "--porcelain"]);
+      if (wtList.status === 0) {
+        const blocks = wtList.stdout.split(/\n\n+/);
+        for (const block of blocks) {
+          const lines = block.trim().split("\n");
+          let wtPath: string | undefined;
+          let wtBranch: string | undefined;
+          for (const line of lines) {
+            if (line.startsWith("worktree ")) {
+              wtPath = line.substring("worktree ".length).trim();
+            } else if (line.startsWith("branch ")) {
+              wtBranch = line.substring("branch ".length).trim();
+            }
+          }
+          if (wtPath && wtBranch && (wtBranch === `refs/heads/${branchName}` || wtBranch === branchName)) {
+            const rmRes = runner("git", ["worktree", "remove", "--force", wtPath]);
+            if (rmRes.status === 0) {
+              removedWorktreePath = wtPath;
+            } else {
+              return {
+                ok: false,
+                branchName,
+                deletedLocalBranch: false,
+                deletedRemoteBranch: false,
+                error: `failed_to_remove_worktree: ${rmRes.stderr.trim() || rmRes.stdout.trim()}`,
+              };
+            }
+          }
+        }
+      }
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        branchName,
+        deletedLocalBranch: false,
+        deletedRemoteBranch: false,
+        error: `worktree_inspection_failed: ${(err as Error).message}`,
+      };
+    }
+  }
+
+  // 2. Delete local branch if it exists
+  const checkBranch = runner("git", ["rev-parse", "--verify", `refs/heads/${branchName}`]);
+  if (checkBranch.status === 0) {
+    const delRes = runner("git", ["branch", "-D", branchName]);
+    if (delRes.status === 0) {
+      deletedLocalBranch = true;
+    } else {
+      return {
+        ok: false,
+        branchName,
+        deletedLocalBranch: false,
+        deletedRemoteBranch: false,
+        ...(removedWorktreePath ? { removedWorktreePath } : {}),
+        error: `failed_to_delete_local_branch: ${delRes.stderr.trim() || delRes.stdout.trim()}`,
+      };
+    }
+  }
+
+  // 3. Delete remote branch if requested
+  if (options?.deleteRemote) {
+    const remote = options.remoteName || "origin";
+    const remoteDelRes = runner("git", ["push", remote, "--delete", branchName]);
+    if (remoteDelRes.status === 0) {
+      deletedRemoteBranch = true;
+    } else {
+      return {
+        ok: false,
+        branchName,
+        deletedLocalBranch,
+        deletedRemoteBranch: false,
+        ...(removedWorktreePath ? { removedWorktreePath } : {}),
+        error: `failed_to_delete_remote_branch: ${remoteDelRes.stderr.trim() || remoteDelRes.stdout.trim()}`,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    branchName,
+    deletedLocalBranch,
+    deletedRemoteBranch,
+    ...(removedWorktreePath ? { removedWorktreePath } : {}),
+  };
+}

package/plugins/kxm/src/hub.ts

@@ -29,6 +29,7 @@ import {
   type WorkflowMessageContext,
 } from "./protocol.ts";
 import { workflowScopeExtras } from "./diagnostics.ts";
+import { timingSafeStringCompare } from "./commands.ts";
 import { arbitrate, explainContextItem, journalEntryToContextItem, memoryRecordToContextItem, rolePolicy } from "./arbiter.ts";
 import { loadAuthoredMemory } from "./memory.ts";
 import { contextItemAuditMetadata, CONTEXT_AUTHORITIES, CONTEXT_CONFIDENCES, type ContextAuthority, type ContextConfidence, type ContextItem } from "./context.ts";
@@ -123,10 +124,7 @@ function publicAgent(agent: StoredAgent): AgentRecord {
 }
 
 function safeTokenEqual(actual: string | undefined, expected: string): boolean {
-  if (!actual) return false;
-  const actualHash = createHash("sha256").update(actual).digest();
-  const expectedHash = createHash("sha256").update(expected).digest();
-  return timingSafeEqual(actualHash, expectedHash);
+  return timingSafeStringCompare(actual, expected);
 }
 
 function bearerToken(request: IncomingMessage): string | undefined {

package/plugins/kxm/src/improve.ts

@@ -381,3 +381,75 @@ export function formatImprovementReport(report: ImprovementReport): string {
 
   return lines.join("\n");
 }
+
+export interface PromotionDecision {
+  eligible: boolean;
+  policy: "manual_pr" | "critic_quorum" | "auto_threshold";
+  authorized: boolean;
+  reason: string;
+}
+
+/**
+ * Evaluates candidate promotion policy (Decision Q11).
+ * Supports:
+ * - manual_pr: strict operator signoff via Git PR / CLI (fail-closed anti-privilege-escalation)
+ * - critic_quorum: requires dual critic approval before auto-promotion
+ * - auto_threshold: requires candidate to exceed recurrence and verifyPassRate thresholds
+ */
+export function evaluatePromotionPolicy(
+  candidate: ImprovementCandidate,
+  policy: "manual_pr" | "critic_quorum" | "auto_threshold" = "manual_pr",
+  options?: {
+    criticApprovals?: string[] | undefined;
+    autoThreshold?: {
+      minRuns: number;
+      minPassRate: number;
+      minCostSavings?: number | undefined;
+    } | undefined;
+  },
+): PromotionDecision {
+  if (policy === "manual_pr") {
+    return {
+      eligible: true,
+      policy,
+      authorized: false,
+      reason: "Manual PR review and signoff required by policy (fail-closed anti-privilege-escalation)",
+    };
+  }
+
+  if (policy === "critic_quorum") {
+    const approvals = options?.criticApprovals ?? [];
+    const hasQuorum = approvals.length >= 2;
+    return {
+      eligible: true,
+      policy,
+      authorized: hasQuorum,
+      reason: hasQuorum
+        ? `Authorized by critic quorum (${approvals.join(", ")})`
+        : `Requires dual critic quorum; current approvals: ${approvals.length}/2`,
+    };
+  }
+
+  if (policy === "auto_threshold") {
+    const threshold = options?.autoThreshold ?? { minRuns: 10, minPassRate: 0.95 };
+    const recurrence = candidate.baselineMetrics.recurrence;
+    const passRate = candidate.baselineMetrics.verifyPassRate;
+    const meetsThreshold = recurrence >= threshold.minRuns && passRate >= threshold.minPassRate;
+
+    return {
+      eligible: true,
+      policy,
+      authorized: meetsThreshold,
+      reason: meetsThreshold
+        ? `Authorized by auto-threshold (runs=${recurrence}>=${threshold.minRuns}, passRate=${passRate}>=${threshold.minPassRate})`
+        : `Auto-threshold not met: runs=${recurrence}/${threshold.minRuns}, passRate=${passRate}/${threshold.minPassRate}`,
+    };
+  }
+
+  return {
+    eligible: false,
+    policy,
+    authorized: false,
+    reason: `Unknown promotion policy: ${String(policy)}`,
+  };
+}

package/plugins/kxm/src/mcp-server.ts

@@ -7,7 +7,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.6.0";
+const VERSION = "0.7.0";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

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

@@ -0,0 +1,127 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { stringify } from "yaml";
+
+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 = (command: string, args: string[], source: string) => {
+    const result = spawnSync(command, args, { encoding: "utf8", timeout: 20_000, shell: false });
+    const ok = result.status === 0;
+    sources[source] = { url: `${command} ${args.join(" ")}`, ok, ...(ok ? {} : { error: (result.stderr || "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");
+      }
+    }
+  };
+  native("pi", ["--list-models"], "pi");
+  native("grok", ["models"], "grok");
+  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;
+}