@arvorco/relentless 0.3.1 → 0.4.2

package/src/routing/router.ts

@@ -0,0 +1,287 @@
+/**
+ * Mode-Model Matrix Router (US-010)
+ *
+ * Routes tasks to optimal harness/model combinations based on
+ * user-selected cost optimization mode and task complexity.
+ *
+ * Key concepts:
+ * - MODE_MODEL_MATRIX: 4 modes x 4 complexity levels = 16 routing rules
+ * - routeTask(): Main function that classifies task and determines routing
+ * - Token estimation: Formula-based cost prediction
+ *
+ * @module src/routing/router
+ */
+
+import { z } from "zod";
+import type { UserStory } from "../prd/types";
+import type { AutoModeConfig, Mode, Complexity, HarnessName } from "../config/schema";
+import { HarnessNameSchema, ModeSchema, ComplexitySchema, DEFAULT_CONFIG } from "../config/schema";
+import { classifyTask } from "./classifier";
+import { getHarnessForModel, getModelById } from "./registry";
+
+/**
+ * A routing rule specifying harness and model for a mode/complexity combination.
+ */
+export const RoutingRuleSchema = z.object({
+  /** Harness to use */
+  harness: HarnessNameSchema,
+  /** Model ID to use */
+  model: z.string(),
+});
+export type RoutingRule = z.infer<typeof RoutingRuleSchema>;
+
+/**
+ * Complete routing decision including complexity, mode, cost, and reasoning.
+ */
+export const RoutingDecisionSchema = z.object({
+  /** Selected harness */
+  harness: HarnessNameSchema,
+  /** Selected model ID */
+  model: z.string(),
+  /** Classified task complexity */
+  complexity: ComplexitySchema,
+  /** Active cost optimization mode */
+  mode: ModeSchema,
+  /** Estimated cost in USD based on token estimation */
+  estimatedCost: z.number(),
+  /** Human-readable explanation of routing decision */
+  reasoning: z.string(),
+});
+export type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
+
+/**
+ * Mode-Model Matrix defining routing rules for each mode/complexity combination.
+ *
+ * 4 modes x 4 complexity levels = 16 routing rules:
+ *
+ * | Mode   | Simple           | Medium           | Complex          | Expert           |
+ * |--------|------------------|------------------|------------------|------------------|
+ * | free   | opencode/glm-4.7 | opencode/glm-4.7 | opencode/grok-code-fast-1 | opencode/grok-code-fast-1 |
+ * | cheap  | claude/haiku     | gemini/flash     | codex/gpt-5.2-low| codex/gpt-5.2-low|
+ * | good   | claude/sonnet    | claude/sonnet    | claude/opus      | claude/opus      |
+ * | genius | claude/opus      | claude/opus      | claude/opus      | claude/opus      |
+ */
+export const MODE_MODEL_MATRIX: Record<Mode, Record<Complexity, RoutingRule>> = {
+  /**
+   * Free mode: Use only zero-cost models.
+   * Best for learning, experimentation, or tight budgets.
+   */
+  free: {
+    simple: { harness: "opencode", model: "glm-4.7" },
+    medium: { harness: "opencode", model: "glm-4.7" },
+    complex: { harness: "opencode", model: "grok-code-fast-1" },
+    expert: { harness: "opencode", model: "grok-code-fast-1" },
+  },
+
+  /**
+   * Cheap mode: Use low-cost models for most tasks, escalate only for expert tasks.
+   * Saves 50-70% vs SOTA pricing.
+   */
+  cheap: {
+    simple: { harness: "claude", model: "haiku-4.5" },
+    medium: { harness: "gemini", model: "gemini-3-flash" },
+    complex: { harness: "codex", model: "gpt-5.2-low" },
+    expert: { harness: "codex", model: "gpt-5.2-low" },
+  },
+
+  /**
+   * Good mode: Balanced quality/cost with smart routing.
+   * Default mode - good for most production work.
+   */
+  good: {
+    simple: { harness: "claude", model: "sonnet-4.5" },
+    medium: { harness: "claude", model: "sonnet-4.5" },
+    complex: { harness: "claude", model: "opus-4.5" },
+    expert: { harness: "claude", model: "opus-4.5" },
+  },
+
+  /**
+   * Genius mode: Use SOTA models for all tasks.
+   * Maximum quality, no cost optimization.
+   */
+  genius: {
+    simple: { harness: "claude", model: "opus-4.5" },
+    medium: { harness: "claude", model: "opus-4.5" },
+    complex: { harness: "claude", model: "opus-4.5" },
+    expert: { harness: "claude", model: "opus-4.5" },
+  },
+};
+
+/**
+ * Estimate the number of tokens needed for a task.
+ *
+ * Formula: (contentLength / 4) * 1.5
+ * - Divide by 4: Average chars per token in English
+ * - Multiply by 1.5: Account for agent response (input + output)
+ *
+ * @param story - The user story to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokens(story: UserStory): number {
+  const title = story.title || "";
+  const description = story.description || "";
+  const criteria = (story.acceptanceCriteria || []).join(" ");
+
+  const contentLength = title.length + description.length + criteria.length;
+
+  // Formula: (content.length / 4) * 1.5
+  // 4 chars per token average, 1.5x multiplier for agent response
+  return Math.ceil((contentLength / 4) * 1.5);
+}
+
+/**
+ * Calculate the estimated cost for a task based on model pricing.
+ *
+ * Cost formula: (inputTokens * inputCost + outputTokens * outputCost) / 1_000_000
+ * - Assumes output is ~1.5x input for agent tasks
+ * - Costs are per million tokens
+ *
+ * @param modelId - The model identifier
+ * @param estimatedTokens - Estimated input token count
+ * @returns Estimated cost in USD
+ */
+export function calculateCost(modelId: string, estimatedTokens: number): number {
+  const model = getModelById(modelId);
+
+  if (!model) {
+    return 0;
+  }
+
+  // Free tier models have zero cost
+  if (model.tier === "free") {
+    return 0;
+  }
+
+  // Assume output is roughly 1.5x input for agent tasks
+  const inputTokens = estimatedTokens;
+  const outputTokens = Math.ceil(estimatedTokens * 1.5);
+
+  // Costs are per million tokens
+  const inputCost = (inputTokens * model.inputCost) / 1_000_000;
+  const outputCost = (outputTokens * model.outputCost) / 1_000_000;
+
+  return inputCost + outputCost;
+}
+
+/**
+ * Route a task to the optimal harness/model combination.
+ *
+ * This function:
+ * 1. Classifies the task complexity using the hybrid classifier
+ * 2. Looks up the routing rule from MODE_MODEL_MATRIX
+ * 3. Calculates estimated cost
+ * 4. Returns a complete RoutingDecision
+ *
+ * @param story - The user story to route
+ * @param config - Auto mode configuration
+ * @param modeOverride - Optional mode to override config.defaultMode
+ * @returns RoutingDecision with harness, model, complexity, mode, cost, and reasoning
+ */
+export async function routeTask(
+  story: UserStory,
+  config: AutoModeConfig,
+  modeOverride?: Mode
+): Promise<RoutingDecision> {
+  // Determine the active mode
+  const mode = modeOverride ?? config.defaultMode;
+
+  // Classify task complexity
+  const classification = await classifyTask(story);
+  const complexity = classification.complexity;
+
+  // Look up routing rule from matrix and apply config overrides
+  const rule = resolveRoutingRule(config, mode, complexity);
+  const harness = rule.harness;
+  const model = rule.model;
+
+  // Calculate estimated cost
+  const tokens = estimateTokens(story);
+  const estimatedCost = calculateCost(model, tokens);
+
+  // Generate reasoning
+  const reasoning = buildReasoning({
+    complexity,
+    mode,
+    harness,
+    model,
+    classification,
+    tokens,
+    estimatedCost,
+  });
+
+  return {
+    harness,
+    model,
+    complexity,
+    mode,
+    estimatedCost,
+    reasoning,
+  };
+}
+
+function hasCustomModeModels(config: AutoModeConfig): boolean {
+  const defaults = DEFAULT_CONFIG.autoMode.modeModels;
+  return (
+    config.modeModels.simple !== defaults.simple ||
+    config.modeModels.medium !== defaults.medium ||
+    config.modeModels.complex !== defaults.complex ||
+    config.modeModels.expert !== defaults.expert
+  );
+}
+
+function resolveRoutingRule(
+  config: AutoModeConfig,
+  mode: Mode,
+  complexity: Complexity
+): RoutingRule {
+  const rule = MODE_MODEL_MATRIX[mode][complexity];
+
+  // Only apply modeModels override for "good" mode
+  // Other modes (free, cheap, genius) should always use the matrix
+  if (mode !== "good" || !hasCustomModeModels(config)) {
+    return rule;
+  }
+
+  const overrideModel = config.modeModels[complexity];
+  const overrideProfile = getModelById(overrideModel);
+  if (!overrideProfile) {
+    return rule;
+  }
+
+  const overrideHarness = getHarnessForModel(overrideModel);
+  return {
+    harness: overrideHarness ?? rule.harness,
+    model: overrideModel,
+  };
+}
+
+/**
+ * Build a human-readable reasoning string for a routing decision.
+ */
+function buildReasoning(params: {
+  complexity: Complexity;
+  mode: Mode;
+  harness: HarnessName;
+  model: string;
+  classification: { confidence: number; reasoning: string };
+  tokens: number;
+  estimatedCost: number;
+}): string {
+  const {
+    complexity,
+    mode,
+    harness,
+    model,
+    classification,
+    tokens,
+    estimatedCost,
+  } = params;
+
+  const costStr = estimatedCost === 0 ? "free" : `$${estimatedCost.toFixed(4)}`;
+
+  return (
+    `Task classified as ${complexity} (confidence: ${(classification.confidence * 100).toFixed(0)}%). ` +
+    `Using ${mode} mode, routing to ${harness}/${model}. ` +
+    `Estimated tokens: ${tokens}, cost: ${costStr}.`
+  );
+}

package/src/tui/App.tsx

@@ -64,6 +64,8 @@ export function App({ state }: AppProps): React.ReactElement {
           story={state.currentStory}
           elapsedSeconds={state.elapsedSeconds}
           isRunning={state.isRunning}
+          idleSeconds={state.idleSeconds}
+          routing={state.currentRouting}
         />
       </Box>
 

package/src/tui/TUIRunner.tsx

@@ -10,10 +10,11 @@ import { App } from "./App.js";
 import type { TUIState, Story, AgentState } from "./types.js";
 import type { AgentName } from "../agents/types.js";
 import type { PRD } from "../prd/types.js";
-import type { RelentlessConfig } from "../config/schema.js";
+import type { RelentlessConfig, Mode } from "../config/schema.js";
 import { getAgent, getInstalledAgents } from "../agents/registry.js";
 import { loadPRD, getNextStory, isComplete, countStories } from "../prd/index.js";
-import { routeStory } from "../execution/router.js";
+import { routeTask } from "../routing/router.js";
+import { getModelForHarnessAndMode, getFreeModeHarnesses } from "../routing/fallback.js";
 import { loadQueueForTUI, watchQueueFile, stopWatchingQueue, QUEUE_PANEL_REFRESH_INTERVAL } from "./components/QueuePanel.js";
 import { handleQueueKeypress, submitToQueue } from "./components/QueueInput.js";
 import { handleQueueDeletionKeypress, removeQueueItem, clearQueueItems } from "./components/QueueRemoval.js";
@@ -29,6 +30,14 @@ export interface TUIRunnerOptions {
   feature: string;
   config: RelentlessConfig;
   dryRun?: boolean;
+  /** Cost optimization mode */
+  mode?: "free" | "cheap" | "good" | "genius";
+  /** Harness fallback order */
+  fallbackOrder?: ("claude" | "codex" | "droid" | "opencode" | "amp" | "gemini")[];
+  /** Skip final review phase */
+  skipReview?: boolean;
+  /** Review quality mode (can differ from execution mode) */
+  reviewMode?: "free" | "cheap" | "good" | "genius";
 }
 
 interface TUIRunnerProps extends TUIRunnerOptions {
@@ -44,9 +53,17 @@ function TUIRunnerComponent({
   feature,
   config,
   dryRun = false,
+  mode,
+  fallbackOrder,
   onComplete,
 }: TUIRunnerProps): React.ReactElement {
   const { exit } = useApp();
+  const autoModeEnabled = preferredAgent === "auto";
+  const autoModeConfig = config.autoMode;
+  let autoMode = (mode ?? autoModeConfig.defaultMode) as Mode;
+  let effectiveFallbackOrder: AgentName[] = autoModeEnabled
+    ? getFreeModeHarnesses((fallbackOrder ?? autoModeConfig.fallbackOrder) as AgentName[])
+    : config.fallback.priority;
   const [state, setState] = useState<TUIState>({
     feature,
     project: "",
@@ -56,9 +73,11 @@ function TUIRunnerComponent({
     maxIterations,
     currentStory: null,
     currentAgent: null,
+    currentRouting: undefined,
     agents: [],
     outputLines: [],
     elapsedSeconds: 0,
+    idleSeconds: 0,
     isRunning: false,
     isComplete: false,
     queueItems: [],
@@ -72,6 +91,7 @@ function TUIRunnerComponent({
   // Queue file watcher ref
   const queueWatcherRef = React.useRef<FSWatcher | null>(null);
   const featurePathRef = React.useRef<string>("");
+  const lastOutputAtRef = React.useRef<number>(Date.now());
 
   // Load queue items function
   const loadQueueItems = useCallback(async () => {
@@ -240,14 +260,16 @@ function TUIRunnerComponent({
     }
   });
 
-  // Timer for elapsed time
+  // Timer for elapsed and idle time
   useEffect(() => {
     if (!state.isRunning) return;
 
     const interval = setInterval(() => {
+      const now = Date.now();
       setState((prev) => ({
         ...prev,
         elapsedSeconds: prev.elapsedSeconds + 1,
+        idleSeconds: Math.floor((now - lastOutputAtRef.current) / 1000),
       }));
     }, 1000);
 
@@ -261,6 +283,7 @@ function TUIRunnerComponent({
     
     if (cleanLines.length === 0) return; // Skip empty lines
     
+    lastOutputAtRef.current = Date.now();
     setState((prev) => ({
       ...prev,
       outputLines: [...prev.outputLines.slice(-100), ...cleanLines], // Keep last 100 lines
@@ -275,6 +298,24 @@ function TUIRunnerComponent({
       try {
         // Load PRD
         const prd = await loadPRD(prdPath);
+        const prdRoutingPreference = prd.routingPreference;
+        const preferredMode =
+          prdRoutingPreference?.type === "auto" ? prdRoutingPreference.mode : undefined;
+        autoMode = (mode ?? preferredMode ?? autoModeConfig.defaultMode) as Mode;
+        const allowFree =
+          prdRoutingPreference?.type === "auto"
+            ? prdRoutingPreference.allowFree !== false
+            : true;
+        const autoFallbackOrder = (fallbackOrder ?? autoModeConfig.fallbackOrder) as AgentName[];
+        const filteredFallbackOrder =
+          allowFree || autoMode === "free"
+            ? autoFallbackOrder
+            : autoFallbackOrder.filter((h) => h !== "opencode");
+        effectiveFallbackOrder = autoModeEnabled
+          ? autoMode === "free"
+            ? getFreeModeHarnesses(filteredFallbackOrder)
+            : filteredFallbackOrder
+          : config.fallback.priority;
 
         // Get installed agents
         const installed = await getInstalledAgents();
@@ -310,6 +351,10 @@ function TUIRunnerComponent({
           addOutput("DRY RUN - not executing agents");
         }
 
+        if (autoModeEnabled && !autoModeConfig.enabled) {
+          addOutput("Auto mode routing enabled via CLI even though config.autoMode.enabled is false.");
+        }
+
         // Track rate-limited agents
         const limitedAgents = new Map<AgentName, { resetTime?: Date; detectedAt: Date }>();
 
@@ -348,15 +393,41 @@ function TUIRunnerComponent({
               phase: story.phase,
             },
             elapsedSeconds: 0,
+            idleSeconds: 0,
+            currentRouting: autoModeEnabled ? prev.currentRouting : undefined,
           }));
+          lastOutputAtRef.current = Date.now();
 
           addOutput(`--- Iteration ${i}/${maxIterations} ---`);
           addOutput(`Story: ${story.id} - ${story.title}`);
 
           // Select agent
           let agentName: AgentName;
+          let autoRoutingDecision: Awaited<ReturnType<typeof routeTask>> | null = null;
+          let autoRoutingModel: string | undefined;
+
           if (preferredAgent === "auto") {
-            agentName = routeStory(story, config.routing);
+            autoRoutingDecision = await routeTask(story, autoModeConfig, autoMode);
+            if (!autoRoutingDecision) {
+              throw new Error("Failed to get routing decision");
+            }
+            const decision = autoRoutingDecision;
+            agentName = decision.harness as AgentName;
+            autoRoutingModel = decision.model;
+
+            setState((prev) => ({
+              ...prev,
+              currentRouting: {
+                mode: autoMode,
+                complexity: decision.complexity,
+                harness: agentName,
+                model: decision.model,
+              },
+            }));
+
+            addOutput(
+              `Routing: ${autoMode}/${decision.complexity} -> ${agentName}/${decision.model}`
+            );
           } else {
             agentName = preferredAgent;
           }
@@ -372,12 +443,34 @@ function TUIRunnerComponent({
               limitedAgents.delete(agentName);
             } else {
               // Try fallback
-              for (const fallbackName of config.fallback.priority) {
+              for (const fallbackName of effectiveFallbackOrder) {
                 if (!limitedAgents.has(fallbackName)) {
                   const installed = agentStates.find((a) => a.name === fallbackName);
                   if (installed) {
                     agentName = fallbackName;
-                    addOutput(`Switched to fallback agent: ${fallbackName}`);
+                    if (autoRoutingDecision && autoModeEnabled) {
+                      const fallbackModel = getModelForHarnessAndMode(
+                        fallbackName,
+                        autoMode,
+                        autoRoutingDecision.complexity,
+                        autoModeConfig
+                      );
+                      autoRoutingModel = fallbackModel;
+                      setState((prev) => ({
+                        ...prev,
+                        currentRouting: {
+                          mode: autoMode,
+                          complexity: autoRoutingDecision.complexity,
+                          harness: fallbackName,
+                          model: fallbackModel,
+                        },
+                      }));
+                      addOutput(
+                        `Switched to fallback agent: ${fallbackName} (model ${fallbackModel})`
+                      );
+                    } else {
+                      addOutput(`Switched to fallback agent: ${fallbackName}`);
+                    }
                     break;
                   }
                 }
@@ -419,7 +512,8 @@ function TUIRunnerComponent({
             const stream = agent.invokeStream(prompt, {
               workingDirectory,
               dangerouslyAllowAll: config.agents[agent.name]?.dangerouslyAllowAll ?? true,
-              model: config.agents[agent.name]?.model,
+              model: autoModeEnabled ? autoRoutingModel : config.agents[agent.name]?.model,
+              timeout: config.execution.timeout,
             });
 
             let result;
@@ -475,7 +569,8 @@ function TUIRunnerComponent({
             const result = await agent.invoke(prompt, {
               workingDirectory,
               dangerouslyAllowAll: config.agents[agent.name]?.dangerouslyAllowAll ?? true,
-              model: config.agents[agent.name]?.model,
+              model: autoModeEnabled ? autoRoutingModel : config.agents[agent.name]?.model,
+              timeout: config.execution.timeout,
             });
 
             // Add output preview

package/src/tui/components/CurrentStory.tsx

@@ -14,6 +14,13 @@ interface CurrentStoryProps {
   story: Story | null;
   elapsedSeconds: number;
   isRunning: boolean;
+  idleSeconds: number;
+  routing?: {
+    mode: "free" | "cheap" | "good" | "genius";
+    complexity: "simple" | "medium" | "complex" | "expert";
+    harness: string;
+    model: string;
+  };
 }
 
 function formatTime(seconds: number): string {
@@ -29,6 +36,8 @@ export function CurrentStory({
   story,
   elapsedSeconds,
   isRunning,
+  idleSeconds,
+  routing,
 }: CurrentStoryProps): React.ReactElement {
   if (!story) {
     return (
@@ -59,8 +68,21 @@ export function CurrentStory({
         ) : (
           <Text color={colors.dim}>{symbols.pending} Waiting</Text>
         )}
-        <Text color={colors.dim}> [elapsed: {formatTime(elapsedSeconds)}]</Text>
+        <Text color={colors.dim}>
+          {" "}
+          [elapsed: {formatTime(elapsedSeconds)}, idle: {formatTime(idleSeconds)}]
+        </Text>
       </Box>
+      {routing && (
+        <Box>
+          <Text color={colors.dim}>Routing: </Text>
+          <Text color={colors.warning}>
+            {routing.mode}/{routing.complexity}
+          </Text>
+          <Text color={colors.dim}> → </Text>
+          <Text>{routing.harness}/{routing.model}</Text>
+        </Box>
+      )}
     </Box>
   );
 }

package/src/tui/hooks/useTUI.ts

@@ -35,6 +35,7 @@ export function useTUI(options: UseTUIOptions): UseTUIReturn {
     agents: options.agents,
     outputLines: [],
     elapsedSeconds: 0,
+    idleSeconds: 0,
     isRunning: false,
     isComplete: false,
     error: undefined,

package/src/tui/types.ts

@@ -42,12 +42,21 @@ export interface TUIState {
   currentStory: Story | null;
   /** Current agent */
   currentAgent: AgentState | null;
+  /** Current routing decision (auto mode) */
+  currentRouting?: {
+    mode: "free" | "cheap" | "good" | "genius";
+    complexity: "simple" | "medium" | "complex" | "expert";
+    harness: AgentName;
+    model: string;
+  };
   /** All agents with their states */
   agents: AgentState[];
   /** Agent output lines */
   outputLines: string[];
   /** Elapsed time in seconds */
   elapsedSeconds: number;
+  /** Idle time in seconds since last output */
+  idleSeconds: number;
   /** Is running */
   isRunning: boolean;
   /** Is complete */