@kontextmind/kxm 0.7.112 → 0.7.118

package/packages/core/tui/src/tui/optimizer.ts

@@ -0,0 +1,154 @@
+/**
+ * Plan Optimizer Engine.
+ *
+ * Analyzes upcoming tasks against dependency graphs, token footprints,
+ * and harness/model capabilities to generate concrete proposals for:
+ * 1. Concurrency (parallel fanout for independent tasks)
+ * 2. Cost (downscaling lightweight tasks to faster/cheaper models)
+ * 3. Reordering (failing fast on syntax/lint before heavier passes)
+ */
+
+export interface OptimizerTaskInput {
+  readonly id: string;
+  readonly title: string;
+  readonly stageId: string;
+  readonly role: string;
+  readonly harness: string;
+  readonly model: string;
+  readonly dependencies: readonly string[];
+  readonly estimatedTokens?: number | undefined;
+  readonly category?: "implementation" | "test" | "docs" | "lint" | "security" | undefined;
+}
+
+export interface OptimizationProposal {
+  readonly id: string;
+  readonly category: "concurrency" | "cost" | "reorder" | "slice";
+  readonly title: string;
+  readonly description: string;
+  readonly targetTaskIds: readonly string[];
+  readonly projectedTimeSavingsSeconds: number;
+  readonly projectedCostSavingsPercent: number;
+  readonly suggestedModel?: string | undefined;
+  readonly suggestedHarness?: string | undefined;
+  readonly selected: boolean;
+}
+
+export interface OptimizerResult {
+  readonly proposals: readonly OptimizationProposal[];
+  readonly totalProjectedTimeSavingsSeconds: number;
+  readonly totalProjectedCostSavingsPercent: number;
+}
+
+/**
+ * Analyze a task queue and generate optimization proposals.
+ */
+export function evaluatePlanOptimizations(tasks: readonly OptimizerTaskInput[]): OptimizerResult {
+  const proposals: OptimizationProposal[] = [];
+
+  // 1. Detect Parallel Fanout Opportunities (tasks with no mutual dependencies in the same stage)
+  const byStage = new Map<string, OptimizerTaskInput[]>();
+  for (const task of tasks) {
+    const list = byStage.get(task.stageId) ?? [];
+    list.push(task);
+    byStage.set(task.stageId, list);
+  }
+
+  for (const [stageId, stageTasks] of byStage) {
+    if (stageTasks.length >= 2) {
+      const independent = stageTasks.filter((t) => t.dependencies.length === 0 || t.dependencies.every((dep) => !stageTasks.some((st) => st.id === dep)));
+      if (independent.length >= 2) {
+        proposals.push({
+          id: `opt_fanout_${stageId}`,
+          category: "concurrency",
+          title: `Parallelize ${independent.length} tasks in stage "${stageId}"`,
+          description: `Tasks [${independent.map((t) => t.id).join(", ")}] have zero mutual dependencies and can execute concurrently via kxm_fanout.`,
+          targetTaskIds: independent.map((t) => t.id),
+          projectedTimeSavingsSeconds: Math.round(independent.length * 15),
+          projectedCostSavingsPercent: 0,
+          selected: true,
+        });
+      }
+    }
+  }
+
+  // 2. Detect Cost/Model Downscaling Opportunities (Docs or Lint on top-tier frontier models)
+  for (const task of tasks) {
+    const isFrontier = /claude-3-5-sonnet|claude-3-opus|gpt-4o|gpt-5/i.test(task.model);
+    if (isFrontier && (task.category === "docs" || /doc|readme|markdown/i.test(task.title))) {
+      proposals.push({
+        id: `opt_cost_${task.id}`,
+        category: "cost",
+        title: `Downscale model for documentation task "${task.title}"`,
+        description: `Task "${task.id}" is documentation-focused. Routing to a high-throughput lightweight model saves significant token budget.`,
+        targetTaskIds: [task.id],
+        projectedTimeSavingsSeconds: 5,
+        projectedCostSavingsPercent: 65,
+        suggestedHarness: "pi",
+        suggestedModel: "qwen/qwen3-coder-plus",
+        selected: true,
+      });
+    } else if (isFrontier && (task.category === "lint" || /lint|format|style/i.test(task.title))) {
+      proposals.push({
+        id: `opt_lint_${task.id}`,
+        category: "cost",
+        title: `Downscale model for formatting/lint task "${task.title}"`,
+        description: `Task "${task.id}" performs deterministic formatting/linting. Use a fast local/tier-1 helper.`,
+        targetTaskIds: [task.id],
+        projectedTimeSavingsSeconds: 8,
+        projectedCostSavingsPercent: 80,
+        suggestedHarness: "pi",
+        suggestedModel: "google/gemini-2.5-flash",
+        selected: true,
+      });
+    }
+  }
+
+  const totalTimeSavings = proposals.reduce((acc, p) => acc + p.projectedTimeSavingsSeconds, 0);
+  const totalCostSavings = proposals.length > 0
+    ? Math.round(proposals.reduce((acc, p) => acc + p.projectedCostSavingsPercent, 0) / proposals.length)
+    : 0;
+
+  return {
+    proposals,
+    totalProjectedTimeSavingsSeconds: totalTimeSavings,
+    totalProjectedCostSavingsPercent: totalCostSavings,
+  };
+}
+
+/**
+ * Apply selected proposals to the task queue.
+ */
+export function applyPlanOptimizations<T extends OptimizerTaskInput>(
+  tasks: readonly T[],
+  proposals: readonly OptimizationProposal[],
+): { tasks: T[]; appliedCount: number } {
+  const selected = proposals.filter((p) => p.selected);
+  if (selected.length === 0) return { tasks: [...tasks], appliedCount: 0 };
+
+  const modelOverrides = new Map<string, { harness?: string; model?: string }>();
+  for (const proposal of selected) {
+    if (proposal.category === "cost" && proposal.suggestedModel) {
+      for (const targetId of proposal.targetTaskIds) {
+        modelOverrides.set(targetId, {
+          ...(proposal.suggestedHarness ? { harness: proposal.suggestedHarness } : {}),
+          model: proposal.suggestedModel,
+        });
+      }
+    }
+  }
+
+  const updated = tasks.map((task) => {
+    const override = modelOverrides.get(task.id);
+    if (!override) return task;
+    return {
+      ...task,
+      ...(override.harness ? { harness: override.harness } : {}),
+      ...(override.model ? { model: override.model } : {}),
+    };
+  });
+
+  return {
+    tasks: updated,
+    appliedCount: selected.length,
+  };
+}

package/packages/core/tui/src/tui/queue.ts

@@ -0,0 +1,90 @@
+/**
+ * Task Queue & Topological Reordering Engine.
+ *
+ * Manages upcoming tasks in the execution queue with safety guards:
+ * - Detects prerequisite violations when moving a task before its dependencies
+ * - Prevents circular dependency cycles
+ * - Shifts tasks safely up or down
+ */
+
+export interface QueuedTaskItem {
+  readonly id: string;
+  readonly title: string;
+  readonly stageId: string;
+  readonly role: string;
+  readonly harness: string;
+  readonly model: string;
+  readonly status: "completed" | "in_flight" | "pending" | "blocked" | "failed";
+  readonly dependencies: readonly string[];
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly estimatedDurationSec?: number | undefined;
+  readonly estimatedCostUsd?: number | undefined;
+}
+
+export interface ReorderResult {
+  readonly success: boolean;
+  readonly tasks: readonly QueuedTaskItem[];
+  readonly warning?: string | undefined;
+}
+
+/**
+ * Reorder a task in the upcoming queue with dependency validation.
+ */
+export function reorderQueuedTasks(
+  tasks: readonly QueuedTaskItem[],
+  fromIndex: number,
+  toIndex: number,
+): ReorderResult {
+  if (
+    fromIndex < 0 ||
+    fromIndex >= tasks.length ||
+    toIndex < 0 ||
+    toIndex >= tasks.length ||
+    fromIndex === toIndex
+  ) {
+    return { success: false, tasks, warning: "invalid_indices" };
+  }
+
+  const target = tasks[fromIndex]!;
+
+  // Cannot reorder in-flight or completed tasks
+  if (target.status === "in_flight" || target.status === "completed") {
+    return {
+      success: false,
+      tasks,
+      warning: `cannot move ${target.status} task "${target.id}"`,
+    };
+  }
+
+  // Create mutable copy and move
+  const draft = [...tasks];
+  const [removed] = draft.splice(fromIndex, 1);
+  draft.splice(toIndex, 0, removed!);
+
+  // Validate dependencies:
+  // For every task at index i, none of its dependencies can appear at index j > i.
+  const idToIndex = new Map<string, number>();
+  for (let i = 0; i < draft.length; i++) {
+    idToIndex.set(draft[i]!.id, i);
+  }
+
+  for (let i = 0; i < draft.length; i++) {
+    const task = draft[i]!;
+    for (const depId of task.dependencies) {
+      const depIndex = idToIndex.get(depId);
+      if (depIndex !== undefined && depIndex > i) {
+        return {
+          success: false,
+          tasks,
+          warning: `Prerequisite violation: "${task.id}" depends on "${depId}", which is scheduled later at position ${depIndex + 1}`,
+        };
+      }
+    }
+  }
+
+  return {
+    success: true,
+    tasks: draft,
+  };
+}

package/packages/core/tui/src/tui/roleBudget.ts

@@ -0,0 +1,104 @@
+/**
+ * Role Subscription Budget Limits & Rollover Engine.
+ *
+ * Tracks per-role subscription quotas, metered run spend caps,
+ * and executes rollover cascades when limits are exhausted.
+ */
+
+export interface RoleBudgetConfig {
+  readonly roleId: string;
+  readonly type: "subscription" | "metered" | "hybrid";
+  readonly runSpendCapUsd?: number | undefined;
+  readonly monthlySpendCapUsd?: number | undefined;
+  readonly monthlyTokenQuota?: number | undefined;
+  readonly rolloverPercent?: number | undefined; // 0 - 100
+  readonly onExhausted: "cascade_to_roster" | "borrow_from_pool" | "pause_for_approval" | "fail_closed";
+  readonly fallbackModel?: string | undefined;
+  readonly fallbackHarness?: string | undefined;
+  readonly emergencyPoolLimitUsd?: number | undefined;
+}
+
+export interface RoleBudgetState {
+  readonly roleId: string;
+  readonly currentRunSpendUsd: number;
+  readonly currentMonthlySpendUsd: number;
+  readonly usedTokens: number;
+  readonly rolledOverTokens: number;
+  readonly borrowedFromPoolUsd: number;
+}
+
+export interface BudgetEvaluationResult {
+  readonly status: "ok" | "near_limit" | "exhausted";
+  readonly nextAction: "proceed" | "cascade" | "borrow" | "pause" | "fail_closed";
+  readonly fallbackModel?: string | undefined;
+  readonly fallbackHarness?: string | undefined;
+  readonly warning?: string | undefined;
+}
+
+/**
+ * Evaluate if a role execution can proceed under its budget caps or needs rollover.
+ */
+export function evaluateRoleBudget(
+  config: RoleBudgetConfig,
+  state: RoleBudgetState,
+  projectedCostUsd = 0,
+): BudgetEvaluationResult {
+  const projectedRunSpend = state.currentRunSpendUsd + projectedCostUsd;
+
+  // 1. Check run spend cap
+  if (config.runSpendCapUsd !== undefined && projectedRunSpend > config.runSpendCapUsd) {
+    if (config.onExhausted === "cascade_to_roster" && config.fallbackModel) {
+      return {
+        status: "exhausted",
+        nextAction: "cascade",
+        fallbackModel: config.fallbackModel,
+        fallbackHarness: config.fallbackHarness ?? "pi",
+        warning: `Role "${config.roleId}" reached run spend cap ($${config.runSpendCapUsd.toFixed(2)}); rolling over to ${config.fallbackModel}`,
+      };
+    }
+    if (config.onExhausted === "borrow_from_pool" && (config.emergencyPoolLimitUsd ?? 0) > state.borrowedFromPoolUsd) {
+      return {
+        status: "exhausted",
+        nextAction: "borrow",
+        warning: `Role "${config.roleId}" borrowing from project emergency buffer`,
+      };
+    }
+    return {
+      status: "exhausted",
+      nextAction: config.onExhausted === "pause_for_approval" ? "pause" : "fail_closed",
+      warning: `Role "${config.roleId}" exhausted run spend cap ($${config.runSpendCapUsd.toFixed(2)})`,
+    };
+  }
+
+  // 2. Check monthly spend cap
+  if (config.monthlySpendCapUsd !== undefined && (state.currentMonthlySpendUsd + projectedCostUsd) > config.monthlySpendCapUsd) {
+    if (config.onExhausted === "cascade_to_roster" && config.fallbackModel) {
+      return {
+        status: "exhausted",
+        nextAction: "cascade",
+        fallbackModel: config.fallbackModel,
+        fallbackHarness: config.fallbackHarness ?? "pi",
+        warning: `Role "${config.roleId}" reached monthly budget limit ($${config.monthlySpendCapUsd.toFixed(2)})`,
+      };
+    }
+    return {
+      status: "exhausted",
+      nextAction: "pause",
+      warning: `Role "${config.roleId}" reached monthly budget cap ($${config.monthlySpendCapUsd.toFixed(2)})`,
+    };
+  }
+
+  // 3. Near limit alert (>= 85% of budget)
+  if (config.runSpendCapUsd && (projectedRunSpend / config.runSpendCapUsd) >= 0.85) {
+    return {
+      status: "near_limit",
+      nextAction: "proceed",
+      warning: `Role "${config.roleId}" is at ${Math.round((projectedRunSpend / config.runSpendCapUsd) * 100)}% of run budget`,
+    };
+  }
+
+  return {
+    status: "ok",
+    nextAction: "proceed",
+  };
+}

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.112",
+  "version": "0.7.118",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",