@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/dist/core.js

@@ -59,6 +59,61 @@ function parseBoundedInteger(value, field, fallback, min, max) {
   }
   return value;
 }
+var TERMINAL_RECEIPT_SCHEMA = "kxm.terminal-receipt.v1";
+var VALID_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["accepted", "audit_escalation", "rejected", "error"]);
+function validateTerminalReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ProtocolError(400, "terminal receipt must be an object", "invalid_terminal_receipt");
+  }
+  const record = value;
+  if (record.schema !== void 0 && record.schema !== TERMINAL_RECEIPT_SCHEMA) {
+    throw new ProtocolError(400, `terminal receipt schema must be ${TERMINAL_RECEIPT_SCHEMA}`, "invalid_terminal_receipt");
+  }
+  const status = record.status;
+  if (!status || !VALID_TERMINAL_STATUSES.has(status)) {
+    throw new ProtocolError(
+      400,
+      `terminal receipt status must be one of: ${Array.from(VALID_TERMINAL_STATUSES).join(", ")}`,
+      "invalid_terminal_receipt"
+    );
+  }
+  const seat = requireString(record.seat, "seat", { max: 64 });
+  const runId = requireString(record.runId, "runId", { max: 128 });
+  const stageId = requireString(record.stageId, "stageId", { max: 128 });
+  const timestamp = requireString(record.timestamp, "timestamp", { max: 64 });
+  const host = requireString(record.host, "host", { max: 64 });
+  const model = requireString(record.model, "model", { max: 128 });
+  let evidence;
+  if (record.evidence !== void 0) {
+    if (!record.evidence || typeof record.evidence !== "object" || Array.isArray(record.evidence)) {
+      throw new ProtocolError(400, "terminal receipt evidence must be an object", "invalid_terminal_receipt");
+    }
+    evidence = record.evidence;
+  }
+  let metrics;
+  if (record.metrics !== void 0) {
+    if (!record.metrics || typeof record.metrics !== "object" || Array.isArray(record.metrics)) {
+      throw new ProtocolError(400, "terminal receipt metrics must be an object", "invalid_terminal_receipt");
+    }
+    metrics = record.metrics;
+  }
+  const escalationReason = optionalString(record.escalationReason, "escalationReason", 1024);
+  const ruling = optionalString(record.ruling, "ruling", 2048);
+  return {
+    schema: TERMINAL_RECEIPT_SCHEMA,
+    status,
+    seat,
+    runId,
+    stageId,
+    timestamp,
+    host,
+    model,
+    ...evidence ? { evidence } : {},
+    ...metrics ? { metrics } : {},
+    ...escalationReason ? { escalationReason } : {},
+    ...ruling ? { ruling } : {}
+  };
+}
 
 // plugins/kxm/src/routing.ts
 import { createHash } from "node:crypto";
@@ -68,10 +123,7 @@ function findModelPrice(catalog, model, provider) {
   const normalizedModel = model.trim().toLowerCase();
   const normalizedProvider = provider?.trim().toLowerCase();
   for (const entry of catalog.models) {
-    if (normalizedProvider && entry.provider.toLowerCase() !== normalizedProvider) {
-      const matchesAlias = entry.aliases?.some((a) => a.toLowerCase() === normalizedModel);
-      if (!matchesAlias) continue;
-    }
+    if (normalizedProvider && entry.provider.toLowerCase() !== normalizedProvider) continue;
     if (entry.id.toLowerCase() === normalizedModel || entry.model.toLowerCase() === normalizedModel) {
       return entry;
     }
@@ -84,20 +136,19 @@ function findModelPrice(catalog, model, provider) {
 function calculateModelCost(catalog, params) {
   const row = findModelPrice(catalog, params.model, params.provider);
   if (!row || row.tiers.length === 0) return void 0;
-  const context = params.contextTokens ?? params.tokensIn ?? 0;
-  let selectedTier = row.tiers[0];
-  for (const tier of row.tiers) {
-    if (tier.upToContextTokens !== void 0 && tier.upToContextTokens !== null && context > tier.upToContextTokens) {
-      continue;
-    }
-    selectedTier = tier;
-    break;
-  }
-  const tokensIn = params.tokensIn ?? 0;
-  const tokensOut = params.tokensOut ?? 0;
-  const cacheRead = params.cacheReadTokens ?? 0;
-  const cacheWrite = params.cacheWriteTokens ?? 0;
+  if (catalog.currency !== void 0 && catalog.currency !== "USD") return void 0;
+  const validCount = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+  const tokensIn = params.tokensIn;
+  const tokensOut = params.tokensOut;
+  const cacheRead = params.cacheReadTokens;
+  const cacheWrite = params.cacheWriteTokens;
+  if (!validCount(tokensIn) || !validCount(tokensOut) || !validCount(cacheRead) || !validCount(cacheWrite)) return void 0;
+  const context = params.contextTokens;
+  if (context != null && !validCount(context)) return void 0;
+  const selectedTier = context == null ? row.tiers.length === 1 && row.tiers[0].upToContextTokens == null ? row.tiers[0] : void 0 : row.tiers.find((tier) => tier.upToContextTokens == null || context <= tier.upToContextTokens);
+  if (!selectedTier || cacheRead > 0 && selectedTier.cacheReadPerMillion == null || cacheWrite > 0 && selectedTier.cacheWritePerMillion == null) return void 0;
   const cost = tokensIn / 1e6 * selectedTier.inputPerMillion + tokensOut / 1e6 * selectedTier.outputPerMillion + cacheRead / 1e6 * (selectedTier.cacheReadPerMillion ?? 0) + cacheWrite / 1e6 * (selectedTier.cacheWritePerMillion ?? 0);
+  if (!Number.isFinite(cost) || cost < 0) return void 0;
   const priceRef = `${catalog.date}#${row.id}`;
   return {
     costUsd: Math.round(cost * 1e6) / 1e6,
@@ -435,6 +486,63 @@ function computePercentile(sorted, p) {
   }
   return sorted[base];
 }
+function computeDecayedWeight(recordedAt, halfLifeDays = 14, now = Date.now()) {
+  const ts = typeof recordedAt === "number" ? recordedAt : Date.parse(recordedAt);
+  if (!Number.isFinite(ts)) return 1;
+  const deltaMs = Math.max(0, now - ts);
+  const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1e3;
+  return Math.pow(2, -deltaMs / halfLifeMs);
+}
+function evaluateCircuitBreaker(records, route, config, now = Date.now()) {
+  const mode = config?.mode ?? "soft_demotion";
+  const failureThreshold = config?.failureThreshold ?? 3;
+  const windowSeconds = config?.windowSeconds ?? 3600;
+  const penaltyMultiplier = config?.penaltyMultiplier ?? 5;
+  const windowMs = windowSeconds * 1e3;
+  const matching = records.filter((r) => {
+    const isV2 = r.schema === ROUTING_RECORD_V2_SCHEMA;
+    const harness = isV2 ? r.harness : r.providerMetadata?.harness;
+    const model = isV2 ? r.effectiveModel || r.requestedModel : r.effectiveModel || r.requestedModel;
+    if (harness !== route.harness || model !== route.model) return false;
+    const recAt = r.recordedAt;
+    const ts = typeof recAt === "string" ? Date.parse(recAt) : 0;
+    return ts >= now - windowMs;
+  });
+  matching.sort((a, b) => {
+    const ta = typeof a.recordedAt === "string" ? Date.parse(a.recordedAt) : 0;
+    const tb = typeof b.recordedAt === "string" ? Date.parse(b.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
+  };
+}
 function generateRoutingReport(records, options = {}) {
   const generatedAt = options.now ? options.now() : (/* @__PURE__ */ new Date()).toISOString();
   if (records.length === 0) {
@@ -538,7 +646,8 @@ function generateRoutingReport(records, options = {}) {
             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;
@@ -742,7 +851,10 @@ function redactStringList(values, maxItems = 32) {
 }
 
 // plugins/kxm/src/commands.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { createHash as createHash2, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 
 // plugins/kxm/src/client.ts
 var HubHttpError = class extends Error {
@@ -1508,26 +1620,60 @@ function parseAttemptToken(token) {
   }
   return void 0;
 }
+function timingSafeStringCompare(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const hashA = createHash2("sha256").update(a).digest();
+  const hashB = createHash2("sha256").update(b).digest();
+  return timingSafeEqual(hashA, hashB);
+}
 function mintSessionToken(input) {
   const toolPolicy = input?.toolPolicy ?? (input?.allowedTools || input?.deniedTools || input?.preset ? {
     ...input?.preset ? { preset: input.preset } : {},
-    ...input?.allowedTools ? { allow: input.allowedTools } : {},
-    ...input?.deniedTools ? { deny: input.deniedTools } : {}
+    ...input?.allowedTools ? { allow: input.allowedTools, allowedTools: input.allowedTools } : {},
+    ...input?.deniedTools ? { deny: input.deniedTools, deniedTools: input.deniedTools } : {}
   } : void 0);
+  const issuedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const defaultTtlMs = 24 * 60 * 60 * 1e3;
+  const ttlMs = typeof input?.ttlMs === "number" && input.ttlMs > 0 ? input.ttlMs : defaultTtlMs;
+  const expiresAt = input?.expiresAt ?? new Date(Date.now() + ttlMs).toISOString();
   const payload = {
     schema: "kxm.session-token.v1",
     sessionId: input?.sessionId ?? `session-${randomUUID2()}`,
-    issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    issuedAt,
+    expiresAt,
     ...input?.agentName ? { agentName: input.agentName } : {},
     ...toolPolicy ? { toolPolicy } : {}
   };
   return Buffer.from(JSON.stringify(payload)).toString("base64url");
 }
+function isSessionTokenExpired(payloadOrToken) {
+  let payload;
+  if (typeof payloadOrToken === "string") {
+    try {
+      const raw = Buffer.from(payloadOrToken.trim(), "base64url").toString("utf8");
+      payload = JSON.parse(raw);
+    } catch {
+      return true;
+    }
+  } else {
+    payload = payloadOrToken;
+  }
+  if (!payload || !payload.expiresAt) return false;
+  const expiryTime = new Date(payload.expiresAt).getTime();
+  if (Number.isNaN(expiryTime)) return true;
+  return Date.now() >= expiryTime;
+}
 function parseSessionToken(token) {
   try {
     const raw = Buffer.from(token.trim(), "base64url").toString("utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && parsed.schema === "kxm.session-token.v1" && typeof parsed.sessionId === "string") {
+      if (parsed.expiresAt) {
+        const expiryTime = new Date(parsed.expiresAt).getTime();
+        if (!Number.isNaN(expiryTime) && Date.now() >= expiryTime) {
+          return void 0;
+        }
+      }
       return parsed;
     }
   } catch {
@@ -1535,6 +1681,49 @@ function parseSessionToken(token) {
   }
   return void 0;
 }
+function resolveUserConfigDirectory(overrideDir) {
+  if (overrideDir) return resolve(overrideDir);
+  return resolve(process.env.KXM_USER_CONFIG_DIR?.trim() || join(homedir(), ".config", "kxm"));
+}
+function sessionTokenPath(userConfigDir) {
+  return join(resolveUserConfigDirectory(userConfigDir), "session.token");
+}
+function persistSessionTokenToDisk(token, options) {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const mode = options?.mode ?? 384;
+  writeFileSync(filePath, `${token.trim()}
+`, { encoding: "utf8", mode });
+  try {
+    chmodSync(filePath, mode);
+  } catch {
+  }
+  return filePath;
+}
+function readSessionTokenFromDisk(options) {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return void 0;
+  try {
+    const token = readFileSync(filePath, "utf8").trim();
+    if (!token) return void 0;
+    const payload = parseSessionToken(token);
+    if (!payload) return void 0;
+    return { token, payload };
+  } catch {
+    return void 0;
+  }
+}
+function clearSessionTokenFromDisk(options) {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return false;
+  try {
+    unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function matchToolPattern(pattern, toolName) {
   if (pattern === "*" || pattern === toolName) return true;
   if (pattern.endsWith("*")) {
@@ -1577,7 +1766,7 @@ function isToolAllowed(commandName, policy) {
   }
   return true;
 }
-function enforceToolPolicy(commandName, env = process.env) {
+function enforceToolPolicy(commandName, env = process.env, options) {
   const attemptTokenRaw = env.KXM_ATTEMPT_TOKEN?.trim();
   if (attemptTokenRaw) {
     const attempt = parseAttemptToken(attemptTokenRaw);
@@ -1591,13 +1780,51 @@ function enforceToolPolicy(commandName, env = process.env) {
         detail: `command ${commandName} is denied by attempt tool policy`
       };
     }
+    if (commandName === "kxm_promote" || commandName === "promote") {
+      const explicitAllow = attempt.toolPolicy?.allow ?? attempt.toolPolicy?.allowedTools;
+      if (!Array.isArray(explicitAllow) || !explicitAllow.includes("kxm_promote") && !explicitAllow.includes("promote") && !explicitAllow.includes("*")) {
+        return {
+          allowed: false,
+          error: "attempt_token_admin_denied",
+          detail: "AttemptToken worker cannot perform operator state promotion without explicit policy grant"
+        };
+      }
+    }
+    if (options?.runId && attempt.runId && options.runId !== attempt.runId) {
+      return {
+        allowed: false,
+        error: "attempt_token_scope_violation",
+        detail: `attempt token runId ${attempt.runId} does not match request runId ${options.runId}`
+      };
+    }
     return { allowed: true };
   }
-  const sessionTokenRaw = env.KXM_SESSION_TOKEN?.trim();
-  if (sessionTokenRaw) {
-    const session = parseSessionToken(sessionTokenRaw);
+  const envSessionRaw = env.KXM_SESSION_TOKEN?.trim();
+  if (envSessionRaw) {
+    const session = parseSessionToken(envSessionRaw);
+    if (!session) {
+      return { allowed: false, error: "session_token_invalid", detail: "KXM_SESSION_TOKEN is malformed or expired" };
+    }
+    if (!isToolAllowed(commandName, session.toolPolicy)) {
+      return {
+        allowed: false,
+        error: "tool_policy_denied",
+        detail: `command ${commandName} is denied by session tool policy`
+      };
+    }
+    return { allowed: true };
+  }
+  const tokenFile = sessionTokenPath(env.KXM_USER_CONFIG_DIR);
+  if (existsSync(tokenFile)) {
+    let tokenRaw;
+    try {
+      tokenRaw = readFileSync(tokenFile, "utf8").trim();
+    } catch {
+      return { allowed: false, error: "session_token_invalid", detail: "Session token file on disk could not be read" };
+    }
+    const session = tokenRaw ? parseSessionToken(tokenRaw) : void 0;
     if (!session) {
-      return { allowed: false, error: "session_token_invalid", detail: "KXM_SESSION_TOKEN is malformed" };
+      return { allowed: false, error: "session_token_invalid", detail: "Session token on disk is malformed or expired" };
     }
     if (!isToolAllowed(commandName, session.toolPolicy)) {
       return {
@@ -1612,8 +1839,8 @@ function enforceToolPolicy(commandName, env = process.env) {
 }
 
 // plugins/kxm/src/logger.ts
-import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from "node:fs";
-import { dirname } from "node:path";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync, statSync, unlinkSync as unlinkSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
 var LOG_LEVEL_PRIORITY = {
   debug: 10,
   info: 20,
@@ -1650,10 +1877,10 @@ function redactLogValue(val, key) {
 function rotateLogFiles(filePath, maxFiles) {
   for (let i = maxFiles; i >= 1; i--) {
     const current = `${filePath}.${i}`;
-    if (existsSync(current)) {
+    if (existsSync2(current)) {
       if (i >= maxFiles) {
         try {
-          unlinkSync(current);
+          unlinkSync2(current);
         } catch {
         }
       } else {
@@ -1664,7 +1891,7 @@ function rotateLogFiles(filePath, maxFiles) {
       }
     }
   }
-  if (existsSync(filePath)) {
+  if (existsSync2(filePath)) {
     try {
       renameSync(filePath, `${filePath}.1`);
     } catch {
@@ -1681,7 +1908,7 @@ function createLogger(options) {
   const shouldStdout = options.stdout ?? !isDaemon;
   const correlationDefaults = options.correlation ?? {};
   let currentSize = 0;
-  if (filePath && existsSync(filePath)) {
+  if (filePath && existsSync2(filePath)) {
     try {
       currentSize = statSync(filePath).size;
     } catch {
@@ -1719,7 +1946,7 @@ function createLogger(options) {
         currentSize = 0;
       }
       try {
-        mkdirSync(dirname(filePath), { recursive: true });
+        mkdirSync2(dirname2(filePath), { recursive: true });
         appendFileSync(filePath, line, { encoding: "utf8", mode: 384 });
         currentSize += lineBytes;
       } catch {
@@ -1785,13 +2012,17 @@ export {
   ROUTING_RECORD_SCHEMA,
   ROUTING_RECORD_V2_SCHEMA,
   ROUTING_REPORT_SCHEMA,
+  TERMINAL_RECEIPT_SCHEMA,
   WORKER_RESULT_SCHEMA,
   WORKER_SCHEMA,
   agentWorker,
   behavioralConfigHash,
+  clearSessionTokenFromDisk,
   compareRoutingRecords,
+  computeDecayedWeight,
   createLogger,
   enforceToolPolicy,
+  evaluateCircuitBreaker,
   formatRoutingReport,
   gateWorker,
   generateRoutingReport,
@@ -1800,6 +2031,7 @@ export {
   getPiToolDefinitions,
   groupByBehavior,
   isQuotaExhausted,
+  isSessionTokenExpired,
   isToolAllowed,
   looksLikeSecret,
   mintAttemptToken,
@@ -1813,11 +2045,16 @@ export {
   parseRoutingRecord,
   parseRoutingRecordV2,
   parseSessionToken,
+  persistSessionTokenToDisk,
+  readSessionTokenFromDisk,
   reconcileInbox,
   redactLogValue,
   redactSecrets,
   redactStringList,
   requireString,
   rotateLogFiles,
+  sessionTokenPath,
+  timingSafeStringCompare,
+  validateTerminalReceipt,
   workerResult
 };