@kontextmind/kxm 0.6.0 → 0.7.0

package/plugins/kxm/src/commands.ts

@@ -1,4 +1,7 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID, 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";
 import { HubClient, HubHttpError } from "./client.ts";
 import type {
   DeliveryMode,
@@ -62,6 +65,7 @@ export interface SessionTokenPayload {
   agentName?: string;
   toolPolicy?: ToolPolicy;
   issuedAt: string;
+  expiresAt?: string;
 }
 
 export interface CommandExecutionContext {
@@ -930,6 +934,13 @@ export function parseAttemptToken(token: string): AttemptTokenPayload | undefine
   return undefined;
 }
 
+export function timingSafeStringCompare(a: string | undefined, b: string | undefined): boolean {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const hashA = createHash("sha256").update(a).digest();
+  const hashB = createHash("sha256").update(b).digest();
+  return timingSafeEqual(hashA, hashB);
+}
+
 export function mintSessionToken(input?: {
   sessionId?: string;
   agentName?: string;
@@ -937,26 +948,53 @@ export function mintSessionToken(input?: {
   preset?: string;
   allowedTools?: string[];
   deniedTools?: string[];
+  expiresAt?: string;
+  ttlMs?: number;
 }): string {
   const toolPolicy: ToolPolicy | undefined = 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 } : {}),
         }
       : undefined
   );
+  const issuedAt = new Date().toISOString();
+  // Decision Q2: Default 24-hour TTL for disk SessionToken
+  const defaultTtlMs = 24 * 60 * 60 * 1000;
+  const ttlMs = typeof input?.ttlMs === "number" && input.ttlMs > 0 ? input.ttlMs : defaultTtlMs;
+  const expiresAt = input?.expiresAt ?? new Date(Date.now() + ttlMs).toISOString();
+
   const payload: SessionTokenPayload = {
     schema: "kxm.session-token.v1",
     sessionId: input?.sessionId ?? `session-${randomUUID()}`,
-    issuedAt: new Date().toISOString(),
+    issuedAt,
+    expiresAt,
     ...(input?.agentName ? { agentName: input.agentName } : {}),
     ...(toolPolicy ? { toolPolicy } : {}),
   };
   return Buffer.from(JSON.stringify(payload)).toString("base64url");
 }
 
+export function isSessionTokenExpired(payloadOrToken: SessionTokenPayload | string): boolean {
+  let payload: SessionTokenPayload | undefined;
+  if (typeof payloadOrToken === "string") {
+    try {
+      const raw = Buffer.from(payloadOrToken.trim(), "base64url").toString("utf8");
+      payload = JSON.parse(raw) as SessionTokenPayload;
+    } 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;
+}
+
 export function parseSessionToken(token: string): SessionTokenPayload | undefined {
   try {
     const raw = Buffer.from(token.trim(), "base64url").toString("utf8");
@@ -967,6 +1005,12 @@ export function parseSessionToken(token: string): SessionTokenPayload | undefine
       && 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 undefined; // Expired token fails closed
+        }
+      }
       return parsed as SessionTokenPayload;
     }
   } catch {
@@ -975,6 +1019,61 @@ export function parseSessionToken(token: string): SessionTokenPayload | undefine
   return undefined;
 }
 
+function resolveUserConfigDirectory(overrideDir?: string | undefined): string {
+  if (overrideDir) return resolve(overrideDir);
+  return resolve(process.env.KXM_USER_CONFIG_DIR?.trim() || join(homedir(), ".config", "kxm"));
+}
+
+export function sessionTokenPath(userConfigDir?: string | undefined): string {
+  return join(resolveUserConfigDirectory(userConfigDir), "session.token");
+}
+
+export function persistSessionTokenToDisk(
+  token: string,
+  options?: { userConfigDir?: string | undefined; mode?: number | undefined } | undefined,
+): string {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const mode = options?.mode ?? 0o600;
+  writeFileSync(filePath, `${token.trim()}\n`, { encoding: "utf8", mode });
+  try {
+    chmodSync(filePath, mode);
+  } catch {
+    // Ignore permissions error on filesystems that do not support POSIX modes
+  }
+  return filePath;
+}
+
+export function readSessionTokenFromDisk(options?: {
+  userConfigDir?: string | undefined;
+} | undefined): { token: string; payload: SessionTokenPayload } | undefined {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const token = readFileSync(filePath, "utf8").trim();
+    if (!token) return undefined;
+    const payload = parseSessionToken(token);
+    if (!payload) return undefined;
+    return { token, payload };
+  } catch {
+    return undefined;
+  }
+}
+
+export function clearSessionTokenFromDisk(options?: {
+  userConfigDir?: string | undefined;
+} | undefined): boolean {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return false;
+  try {
+    unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function matchToolPattern(pattern: string, toolName: string): boolean {
   if (pattern === "*" || pattern === toolName) return true;
   if (pattern.endsWith("*")) {
@@ -1026,6 +1125,7 @@ export function isToolAllowed(commandName: string, policy?: ToolPolicy): boolean
 export function enforceToolPolicy(
   commandName: string,
   env: NodeJS.ProcessEnv = process.env,
+  options?: { runId?: string; stageId?: string },
 ): { allowed: boolean; error?: string; detail?: string } {
   const attemptTokenRaw = env.KXM_ATTEMPT_TOKEN?.trim();
   if (attemptTokenRaw) {
@@ -1040,14 +1140,56 @@ export function enforceToolPolicy(
         detail: `command ${commandName} is denied by attempt tool policy`,
       };
     }
+    // AttemptToken boundary: AttemptTokens are strictly worker tokens.
+    // They cannot execute administrative state promotion unless explicitly allowed in toolPolicy
+    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",
+        };
+      }
+    }
+    // AttemptToken boundary: Scoped strictly to runId if provided in execution options
+    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 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 sessionTokenRaw = env.KXM_SESSION_TOKEN?.trim();
-  if (sessionTokenRaw) {
-    const session = parseSessionToken(sessionTokenRaw);
+  const tokenFile = sessionTokenPath(env.KXM_USER_CONFIG_DIR);
+  if (existsSync(tokenFile)) {
+    let tokenRaw: string | undefined;
+    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) : undefined;
     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 {

package/plugins/kxm/src/config.ts

@@ -193,8 +193,8 @@ export function loadKxmConfig(
       const text = readFileSync(userConfigFile, "utf8");
       userRaw = (parse(text) as Record<string, unknown>) ?? {};
       userLoadedPath = userConfigFile;
-    } catch {
-      // ignore parse error, fallback
+    } catch (error) {
+      throw new Error(`invalid user config YAML at ${userConfigFile}`, { cause: error });
     }
   }
 
@@ -205,8 +205,8 @@ export function loadKxmConfig(
       const text = readFileSync(repoConfigFile, "utf8");
       repoRaw = (parse(text) as Record<string, unknown>) ?? {};
       repoLoadedPath = repoConfigFile;
-    } catch {
-      // ignore parse error, fallback
+    } catch (error) {
+      throw new Error(`invalid project config YAML at ${repoConfigFile}`, { cause: error });
     }
   }
 
@@ -264,6 +264,9 @@ export function setKxmConfigValue(
   }
 
   const parts = keyPath.split(".");
+  if (parts.some((part) => !part || part === "__proto__" || part === "prototype" || part === "constructor")) {
+    throw new Error("invalid config key path");
+  }
   let cursor = existing;
   for (let i = 0; i < parts.length - 1; i++) {
     const p = parts[i]!;

package/plugins/kxm/src/context-packet.ts

@@ -291,6 +291,178 @@ export function formatContextPacketForPrompt(packet: FormalContextPacketV2): str
   return sections.join("\n").trim();
 }
 
+export interface PruningAudit {
+  initialTokens: number;
+  finalTokens: number;
+  budgetTokens: number;
+  prunedStages: Array<"L1_defaults" | "L2_episodes" | "L2_docs" | "L5_artifacts">;
+  prunedItemCounts: {
+    sharedDefaults: number;
+    episodes: number;
+    docs: number;
+    artifactSnippets: number;
+  };
+  unresolvedGaps: string[];
+}
+
+export function estimateContextPacketTokens(packet: FormalContextPacketV2): number {
+  const prompt = formatContextPacketForPrompt(packet);
+  return Math.ceil(prompt.length / 4);
+}
+
+/**
+ * Deterministic Pruning Hierarchy (Decision Q4):
+ * L1 Defaults -> L2 Historical Episodes -> L2 Project Docs -> L5 Artifacts; L3 Task Objective is inviolable.
+ */
+export function pruneContextPacket(
+  packet: FormalContextPacketV2,
+  tokenBudget?: number,
+): { packet: FormalContextPacketV2; audit: PruningAudit } {
+  const budget = tokenBudget ?? packet.budget.allocatedTokens;
+  let currentTokens = estimateContextPacketTokens(packet);
+  const initialTokens = currentTokens;
+
+  const prunedStages: Array<"L1_defaults" | "L2_episodes" | "L2_docs" | "L5_artifacts"> = [];
+  const prunedItemCounts = {
+    sharedDefaults: 0,
+    episodes: 0,
+    docs: 0,
+    artifactSnippets: 0,
+  };
+  const unresolvedGaps: string[] = [...packet.budget.unresolvedGaps];
+
+  if (currentTokens <= budget) {
+    return {
+      packet: {
+        ...packet,
+        budget: {
+          ...packet.budget,
+          allocatedTokens: budget,
+          estimatedTokens: currentTokens,
+        },
+      },
+      audit: {
+        initialTokens,
+        finalTokens: currentTokens,
+        budgetTokens: budget,
+        prunedStages,
+        prunedItemCounts,
+        unresolvedGaps,
+      },
+    };
+  }
+
+  // Clone packet environment and predecessors to prune deterministically
+  const environment: ContextPacketEnvironment = {
+    sharedDefaults: [...packet.environment.sharedDefaults],
+    projectKnowledge: [...packet.environment.projectKnowledge],
+    currentState: [...packet.environment.currentState],
+    contradictions: [...packet.environment.contradictions],
+    activeSkills: [...packet.environment.activeSkills],
+  };
+  const predecessors: ContextPacketPredecessor[] = packet.predecessors.map((p) => ({
+    ...p,
+    artifacts: p.artifacts.map((a) => ({ ...a })),
+  }));
+
+  const workingPacket: FormalContextPacketV2 = {
+    ...packet,
+    environment,
+    predecessors,
+    budget: { ...packet.budget, allocatedTokens: budget },
+  };
+
+  // Stage 1 (L1 Defaults): Drop shared defaults first
+  if (environment.sharedDefaults.length > 0 && currentTokens > budget) {
+    prunedStages.push("L1_defaults");
+    while (environment.sharedDefaults.length > 0 && currentTokens > budget) {
+      environment.sharedDefaults.pop();
+      prunedItemCounts.sharedDefaults += 1;
+      currentTokens = estimateContextPacketTokens(workingPacket);
+    }
+  }
+
+  // Stage 2 (L2 Historical Episodes): Drop episode state items
+  if (currentTokens > budget) {
+    const episodeIndices: number[] = [];
+    for (let i = environment.currentState.length - 1; i >= 0; i--) {
+      if (environment.currentState[i]?.kind === "episode") {
+        episodeIndices.push(i);
+      }
+    }
+    if (episodeIndices.length > 0) {
+      prunedStages.push("L2_episodes");
+      for (const idx of episodeIndices) {
+        if (currentTokens <= budget) break;
+        environment.currentState.splice(idx, 1);
+        prunedItemCounts.episodes += 1;
+        currentTokens = estimateContextPacketTokens(workingPacket);
+      }
+    }
+  }
+
+  // Stage 3 (L2 Project Docs / Knowledge): Drop project knowledge/doc items
+  if (currentTokens > budget && environment.projectKnowledge.length > 0) {
+    prunedStages.push("L2_docs");
+    while (environment.projectKnowledge.length > 0 && currentTokens > budget) {
+      environment.projectKnowledge.pop();
+      prunedItemCounts.docs += 1;
+      currentTokens = estimateContextPacketTokens(workingPacket);
+    }
+  }
+
+  // Stage 4 (L5 Artifacts): Prune artifact content snippets, then artifact entries if still overflowing
+  if (currentTokens > budget) {
+    const hasArtifacts = predecessors.some((p) => p.artifacts.length > 0);
+    if (hasArtifacts) {
+      prunedStages.push("L5_artifacts");
+      // First strip snippets
+      for (const p of predecessors) {
+        for (const a of p.artifacts) {
+          if (a.contentSnippet) {
+            a.contentSnippet = undefined;
+            prunedItemCounts.artifactSnippets += 1;
+          }
+        }
+      }
+      currentTokens = estimateContextPacketTokens(workingPacket);
+
+      // If still overflowing, prune artifacts list
+      if (currentTokens > budget) {
+        for (const p of predecessors) {
+          p.artifacts = [];
+        }
+        currentTokens = estimateContextPacketTokens(workingPacket);
+      }
+    }
+  }
+
+  // L3 Task Objective Inviolable:
+  // task, plan, and acceptance criteria are inviolable and never stripped.
+  if (currentTokens > budget) {
+    unresolvedGaps.push("context_budget_exceeded_task_inviolable");
+  }
+
+  workingPacket.budget = {
+    ...packet.budget,
+    allocatedTokens: budget,
+    estimatedTokens: currentTokens,
+    unresolvedGaps,
+  };
+
+  return {
+    packet: workingPacket,
+    audit: {
+      initialTokens,
+      finalTokens: currentTokens,
+      budgetTokens: budget,
+      prunedStages,
+      prunedItemCounts,
+      unresolvedGaps,
+    },
+  };
+}
+
 /**
  * Builds a structured handoff manifest between workflow roles.
  */

package/plugins/kxm/src/extension.ts

@@ -24,6 +24,11 @@ import {
   type SessionHubStatus,
   type SessionWorkItem,
 } from "./session-work.ts";
+import {
+  loadActiveWorkflowProgress,
+  renderWorkflowTuiText,
+  renderWorkflowWidgetLines,
+} from "./workflow-tui.ts";
 
 const SETTLEMENT_RETRY_BASE_MS = 250;
 const SETTLEMENT_RETRY_MAX_MS = 30_000;
@@ -303,6 +308,10 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     const brief = await loadSessionBriefAsync(cwd, process.env, currentWork, hub);
     ctx.ui.setStatus?.("kxm", brief.statusLine);
     ctx.ui.setWidget?.("kxm-work", brief.widgetLines);
+    const progress = loadActiveWorkflowProgress(cwd);
+    if (progress) {
+      ctx.ui.setWidget?.("kxm-progress", renderWorkflowWidgetLines(progress));
+    }
     if (!offerPicker || !sessionBriefPickerEnabled({
       env: process.env,
       ...(ctx.mode ? { mode: ctx.mode } : {}),
@@ -866,8 +875,20 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
         ctx.ui.notify(brief.statusLine, "info");
         return;
       }
+      if (command === "progress" || command === "workflow") {
+        const cwd = typeof ctx.cwd === "string" ? ctx.cwd : process.cwd();
+        const progress = loadActiveWorkflowProgress(cwd);
+        if (progress) {
+          const lines = renderWorkflowWidgetLines(progress);
+          ctx.ui.setWidget?.("kxm-progress", lines);
+          ctx.ui.notify(renderWorkflowTuiText(progress), "info");
+        } else {
+          ctx.ui.notify("kxm: no active workflow run found in state.", "info");
+        }
+        return;
+      }
       if (command === "help") {
-        ctx.ui.notify("kxm: /kxm | /kxm status | /kxm hub | /kxm memory | /kxm help. CLI: kxm session brief, kxm hub view, kxm memory brief", "info");
+        ctx.ui.notify("kxm: /kxm | /kxm status | /kxm progress | /kxm workflow | /kxm hub | /kxm memory | /kxm help. CLI: kxm session brief, kxm hub view, kxm memory brief", "info");
         return;
       }
       if (command === "memory") {
@@ -889,6 +910,20 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     },
   });
 
+  pi.registerCommand("workflow", {
+    description: "Display active KXM workflow stage progress, assigned roles, and model metrics",
+    handler: async (_args, ctx) => {
+      const cwd = typeof ctx.cwd === "string" ? ctx.cwd : process.cwd();
+      const progress = loadActiveWorkflowProgress(cwd);
+      if (progress) {
+        ctx.ui.setWidget?.("kxm-progress", renderWorkflowWidgetLines(progress));
+        ctx.ui.notify(renderWorkflowTuiText(progress), "info");
+      } else {
+        ctx.ui.notify("kxm: no active workflow run found in state.", "info");
+      }
+    },
+  });
+
   return nousFactoryWork(pi, (report) => {
     nousReport = report;
   });