opencode-model-router 1.0.7 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-model-router",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "OpenCode plugin that routes tasks to tiered subagents (fast/medium/heavy) based on complexity",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,5 +35,9 @@
   ],
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3"
   }
 }

package/src/index.ts

@@ -22,6 +22,7 @@ interface TierConfig {
   variant?: string;
   thinking?: ThinkingConfig;
   reasoning?: ReasoningConfig;
+  costRatio?: number;
   color?: string;
   description: string;
   steps?: number;
@@ -36,16 +37,26 @@ interface FallbackConfig {
   presets?: Record<string, Record<string, string[]>>;
 }
 
+interface ModeConfig {
+  defaultTier: string;
+  description: string;
+  overrideRules?: string[];
+}
+
 interface RouterConfig {
   activePreset: string;
+  activeMode?: string;
   presets: Record<string, Preset>;
   rules: string[];
   defaultTier: string;
   fallback?: FallbackConfig;
+  taskPatterns?: Record<string, string[]>;
+  modes?: Record<string, ModeConfig>;
 }
 
 interface RouterState {
   activePreset?: string;
+  activeMode?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -130,6 +141,39 @@ function validateConfig(raw: unknown): RouterConfig {
     throw new Error("tiers.json: 'defaultTier' must be a string");
   }
 
+  // Validate modes if present
+  if (obj.modes !== undefined) {
+    if (typeof obj.modes !== "object" || obj.modes === null || Array.isArray(obj.modes)) {
+      throw new Error("tiers.json: 'modes' must be an object");
+    }
+    const modes = obj.modes as Record<string, unknown>;
+    for (const [modeName, mode] of Object.entries(modes)) {
+      if (typeof mode !== "object" || mode === null) {
+        throw new Error(`tiers.json: mode '${modeName}' must be an object`);
+      }
+      const m = mode as Record<string, unknown>;
+      if (typeof m.defaultTier !== "string") {
+        throw new Error(`tiers.json: mode '${modeName}.defaultTier' must be a string`);
+      }
+      if (typeof m.description !== "string") {
+        throw new Error(`tiers.json: mode '${modeName}.description' must be a string`);
+      }
+    }
+  }
+
+  // Validate taskPatterns if present
+  if (obj.taskPatterns !== undefined) {
+    if (typeof obj.taskPatterns !== "object" || obj.taskPatterns === null || Array.isArray(obj.taskPatterns)) {
+      throw new Error("tiers.json: 'taskPatterns' must be an object");
+    }
+    const tp = obj.taskPatterns as Record<string, unknown>;
+    for (const [tierName, patterns] of Object.entries(tp)) {
+      if (!Array.isArray(patterns)) {
+        throw new Error(`tiers.json: taskPatterns.'${tierName}' must be an array of strings`);
+      }
+    }
+  }
+
   return raw as RouterConfig;
 }
 
@@ -150,9 +194,12 @@ function loadConfig(): RouterConfig {
           cfg.activePreset = resolved;
         }
       }
+      if (state.activeMode && cfg.modes?.[state.activeMode]) {
+        cfg.activeMode = state.activeMode;
+      }
     }
   } catch {
-    // Ignore state read errors and keep tiers.json active preset
+    // Ignore state read errors and keep tiers.json defaults
   }
 
   _cachedConfig = cfg;
@@ -160,6 +207,30 @@ function loadConfig(): RouterConfig {
   return cfg;
 }
 
+// ---------------------------------------------------------------------------
+// State persistence helpers
+// ---------------------------------------------------------------------------
+
+/** Read current persisted state (or empty object on failure). */
+function readState(): RouterState {
+  try {
+    if (existsSync(statePath())) {
+      return JSON.parse(readFileSync(statePath(), "utf-8")) as RouterState;
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+/** Write state to disk (merges with existing keys). */
+function writeState(patch: Partial<RouterState>): void {
+  const state = { ...readState(), ...patch };
+  const p = statePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
 function saveActivePreset(presetName: string): void {
   const cfg = loadConfig();
   const resolved = resolvePresetName(cfg, presetName);
@@ -170,15 +241,23 @@ function saveActivePreset(presetName: string): void {
   cfg.activePreset = resolved;
 
   // Persist user-selected preset to state file only — never mutate tiers.json
-  const presetState: RouterState = { activePreset: resolved };
-  const p = statePath();
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, JSON.stringify(presetState, null, 2) + "\n", "utf-8");
+  writeState({ activePreset: resolved });
 
   // Invalidate cache so next read picks up the new active preset
   invalidateConfigCache();
 }
 
+function saveActiveMode(modeName: string): void {
+  const cfg = loadConfig();
+  if (!cfg.modes?.[modeName]) {
+    return;
+  }
+
+  cfg.activeMode = modeName;
+  writeState({ activeMode: modeName });
+  invalidateConfigCache();
+}
+
 function getActiveTiers(cfg: RouterConfig): Preset {
   return cfg.presets[cfg.activePreset] ?? Object.values(cfg.presets)[0]!;
 }
@@ -210,6 +289,15 @@ function buildAgentOptions(tier: TierConfig): Record<string, unknown> {
   return Object.keys(opts).length > 0 ? opts : {};
 }
 
+// ---------------------------------------------------------------------------
+// Mode helpers
+// ---------------------------------------------------------------------------
+
+function getActiveMode(cfg: RouterConfig): ModeConfig | undefined {
+  if (!cfg.modes || !cfg.activeMode) return undefined;
+  return cfg.modes[cfg.activeMode];
+}
+
 // ---------------------------------------------------------------------------
 // Fallback instructions builder
 // ---------------------------------------------------------------------------
@@ -241,6 +329,33 @@ function buildFallbackInstructions(cfg: RouterConfig): string {
   ].join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// Cost & taxonomy builders
+// ---------------------------------------------------------------------------
+
+function buildTaskTaxonomy(cfg: RouterConfig): string {
+  if (!cfg.taskPatterns || Object.keys(cfg.taskPatterns).length === 0) return "";
+
+  const lines = ["Coding task routing guide:"];
+  for (const [tier, patterns] of Object.entries(cfg.taskPatterns)) {
+    if (Array.isArray(patterns) && patterns.length > 0) {
+      lines.push(`- @${tier}: ${patterns.join(", ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function buildCostAwareness(cfg: RouterConfig): string {
+  const tiers = getActiveTiers(cfg);
+  const costs = Object.entries(tiers)
+    .filter(([_, t]) => t.costRatio != null)
+    .map(([name, t]) => `@${name}=${t.costRatio}x`)
+    .join(", ");
+
+  if (!costs) return "";
+  return `Cost ratios: ${costs}. Always use the cheapest tier that can reliably handle the task.`;
+}
+
 // ---------------------------------------------------------------------------
 // System prompt builder
 // ---------------------------------------------------------------------------
@@ -264,8 +379,16 @@ function buildDelegationProtocol(cfg: RouterConfig): string {
     })
     .join("\n");
 
-  // Use configurable rules from tiers.json instead of hardcoded ones
-  const numberedRules = cfg.rules
+  // Task taxonomy from config
+  const taxonomy = buildTaskTaxonomy(cfg);
+
+  // Cost awareness
+  const costLine = buildCostAwareness(cfg);
+
+  // Mode-aware rules: if active mode has overrideRules, use those; otherwise use global rules
+  const mode = getActiveMode(cfg);
+  const effectiveRules = mode?.overrideRules?.length ? mode.overrideRules : cfg.rules;
+  const numberedRules = effectiveRules
     .map((rule, i) => `${i + 1}. ${rule}`)
     .join("\n");
 
@@ -277,6 +400,9 @@ function buildDelegationProtocol(cfg: RouterConfig): string {
     "",
     "Tier capabilities:",
     tierDescriptions,
+    ...(taxonomy ? ["", taxonomy] : []),
+    ...(costLine ? ["", costLine] : []),
+    ...(mode ? [`\nActive mode: ${cfg.activeMode} (${mode.description})`] : []),
     "",
     "Apply to every user message (plan and ad-hoc):",
     numberedRules,
@@ -320,6 +446,50 @@ function buildTiersOutput(cfg: RouterConfig): string {
   return lines.join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// /budget command output
+// ---------------------------------------------------------------------------
+
+function buildBudgetOutput(cfg: RouterConfig, args: string): string {
+  const modes = cfg.modes;
+  if (!modes || Object.keys(modes).length === 0) {
+    return 'No modes configured in tiers.json. Add a "modes" section to enable budget mode.';
+  }
+
+  const requested = args.trim().toLowerCase();
+  const currentMode = cfg.activeMode || "normal";
+
+  // No args: show current mode and available modes
+  if (!requested) {
+    const lines = ["# Routing Modes\n"];
+    for (const [name, mode] of Object.entries(modes)) {
+      const active = name === currentMode ? " <- active" : "";
+      lines.push(`- **${name}**${active}: ${mode.description} (default tier: @${mode.defaultTier})`);
+    }
+    lines.push(`\nSwitch with: \`/budget <mode>\``);
+    return lines.join("\n");
+  }
+
+  // Switch mode
+  if (modes[requested]) {
+    saveActiveMode(requested);
+    const mode = modes[requested];
+    return [
+      `Routing mode switched to **${requested}**.`,
+      "",
+      mode.description,
+      `Default tier: @${mode.defaultTier}`,
+      ...(mode.overrideRules?.length
+        ? ["", "Active rules:", ...mode.overrideRules.map((r) => `- ${r}`)]
+        : []),
+      "",
+      "Mode change takes effect immediately on the next message.",
+    ].join("\n");
+  }
+
+  return `Unknown mode: "${requested}". Available: ${Object.keys(modes).join(", ")}`;
+}
+
 // ---------------------------------------------------------------------------
 // /preset command output
 // ---------------------------------------------------------------------------
@@ -413,6 +583,10 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
         template: "$ARGUMENTS",
         description: "Show or switch model presets (e.g., /preset openai)",
       };
+      opencodeConfig.command["budget"] = {
+        template: "$ARGUMENTS",
+        description: "Show or switch routing mode (e.g., /budget, /budget budget, /budget quality)",
+      };
       opencodeConfig.command["annotate-plan"] = {
         template: [
           "Annotate the plan with tier directives for model delegation.",
@@ -443,7 +617,7 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
     },
 
     // -----------------------------------------------------------------------
-    // Inject delegation protocol — uses cached config (invalidated on /preset)
+    // Inject delegation protocol — uses cached config (invalidated on /preset or /budget)
     // -----------------------------------------------------------------------
     "experimental.chat.system.transform": async (_input: any, output: any) => {
       try {
@@ -455,7 +629,7 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
     },
 
     // -----------------------------------------------------------------------
-    // Handle /tiers and /preset commands
+    // Handle /tiers, /preset, and /budget commands
     // -----------------------------------------------------------------------
     "command.execute.before": async (input: any, output: any) => {
       if (input.command === "tiers") {
@@ -474,6 +648,16 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
           text: buildPresetOutput(cfg, input.arguments ?? ""),
         });
       }
+
+      if (input.command === "budget") {
+        try {
+          cfg = loadConfig();
+        } catch {}
+        output.parts.push({
+          type: "text" as const,
+          text: buildBudgetOutput(cfg, input.arguments ?? ""),
+        });
+      }
     },
   };
 };

package/tiers.json

@@ -1,9 +1,11 @@
 {
   "activePreset": "anthropic",
+  "activeMode": "normal",
   "presets": {
     "anthropic": {
       "fast": {
         "model": "anthropic/claude-haiku-4-5",
+        "costRatio": 1,
         "description": "Haiku 4.5 for exploration, search, and simple reads",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -17,6 +19,7 @@
       "medium": {
         "model": "anthropic/claude-sonnet-4-5",
         "variant": "max",
+        "costRatio": 5,
         "description": "Sonnet 4.5 max for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -31,6 +34,7 @@
       "heavy": {
         "model": "anthropic/claude-opus-4-6",
         "variant": "max",
+        "costRatio": 20,
         "description": "Opus 4.6 max for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -45,6 +49,7 @@
     "openai": {
       "fast": {
         "model": "openai/gpt-5.3-codex-spark",
+        "costRatio": 1,
         "description": "GPT-5.3 Codex Spark for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -56,6 +61,7 @@
       },
       "medium": {
         "model": "openai/gpt-5.3-codex",
+        "costRatio": 5,
         "description": "GPT-5.3 Codex default settings for implementation and standard coding",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -69,6 +75,7 @@
       "heavy": {
         "model": "openai/gpt-5.3-codex",
         "variant": "xhigh",
+        "costRatio": 20,
         "description": "GPT-5.3 Codex xhigh for architecture and complex tasks",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning.",
@@ -83,6 +90,7 @@
     "github-copilot": {
       "fast": {
         "model": "github-copilot/claude-haiku-4-5",
+        "costRatio": 1,
         "description": "Claude Haiku 4.5 via GitHub Copilot for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -95,6 +103,7 @@
       },
       "medium": {
         "model": "github-copilot/claude-sonnet-4-5",
+        "costRatio": 5,
         "description": "Claude Sonnet 4.5 via GitHub Copilot for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -109,6 +118,7 @@
       "heavy": {
         "model": "github-copilot/claude-opus-4-6",
         "variant": "thinking",
+        "costRatio": 20,
         "description": "Claude Opus 4.6 via GitHub Copilot for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -123,6 +133,7 @@
     "google": {
       "fast": {
         "model": "google/gemini-2.5-flash",
+        "costRatio": 1,
         "description": "Gemini 2.5 Flash for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -135,6 +146,7 @@
       },
       "medium": {
         "model": "google/gemini-2.5-pro",
+        "costRatio": 5,
         "description": "Gemini 2.5 Pro for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -148,6 +160,7 @@
       },
       "heavy": {
         "model": "google/gemini-3-pro-preview",
+        "costRatio": 20,
         "description": "Gemini 3 Pro Preview for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -160,6 +173,69 @@
       }
     }
   },
+  "taskPatterns": {
+    "fast": [
+      "Find, search, locate, or grep files and code patterns",
+      "List or show directory structure and file contents",
+      "Read or display specific files or sections",
+      "Check git status, log, diff, or blame",
+      "Lookup documentation, API signatures, or type definitions",
+      "Count occurrences, lines, or matches",
+      "Check if a file, function, or class exists",
+      "Simple rename or string replacement across files"
+    ],
+    "medium": [
+      "Implement a new feature, function, or component",
+      "Refactor or restructure existing code",
+      "Write or update tests",
+      "Fix a bug (first or second attempt)",
+      "Modify or update existing code logic",
+      "Code review with suggested changes",
+      "Run build/lint/test and fix resulting errors",
+      "Create a new file from a template or pattern",
+      "Database migration or schema changes",
+      "API endpoint implementation",
+      "Configuration or dependency updates"
+    ],
+    "heavy": [
+      "Design system or module architecture from scratch",
+      "Debug a problem after 2+ failed attempts",
+      "Security audit or vulnerability review",
+      "Performance profiling and optimization",
+      "Migration strategy (framework, language, infrastructure)",
+      "Complex multi-system integration design",
+      "Evaluate tradeoffs between competing approaches",
+      "Root cause analysis of complex or elusive failures"
+    ]
+  },
+  "modes": {
+    "normal": {
+      "defaultTier": "medium",
+      "description": "Balanced quality and cost — delegates based on task complexity"
+    },
+    "budget": {
+      "defaultTier": "fast",
+      "description": "Aggressive cost savings — defaults to cheapest tier, escalates only when needed",
+      "overrideRules": [
+        "Default ALL tasks to @fast unless they clearly require code edits or complex reasoning",
+        "Use @medium ONLY for: multi-file edits, complex refactors, test suites, or build-fix cycles",
+        "Use @heavy ONLY when explicitly requested by user or after 2+ failed @medium attempts",
+        "Prefer executing simple tasks directly (grep, read, glob) over delegating — zero delegation overhead",
+        "Batch multiple related searches into a single @fast delegation instead of multiple calls",
+        "When uncertain between @fast and @medium, choose @fast — escalate only on failure"
+      ]
+    },
+    "quality": {
+      "defaultTier": "medium",
+      "description": "Quality-first — uses stronger models more liberally for better results",
+      "overrideRules": [
+        "Default to @medium for all tasks including exploration when deep context understanding matters",
+        "Use @heavy for any task involving architecture, debugging, security, or multi-file coordination",
+        "Use @fast only for trivial single-tool operations (one grep, one file read)",
+        "Prefer thoroughness over speed — better to over-qualify a task than under-qualify it"
+      ]
+    }
+  },
   "fallback": {
     "global": {
       "anthropic": ["openai", "google", "github-copilot"],
@@ -177,7 +253,10 @@
     "Use @fast for any read-only exploration or research task",
     "Keep orchestration (planning, decisions, verification) for yourself - delegate execution",
     "For trivial tasks (single grep, single file read), execute directly without delegation",
-    "Never delegate to @heavy if you are already running on an opus-class model - do it yourself"
+    "Never delegate to @heavy if you are already running on an opus-class model - do it yourself",
+    "If a task takes 1-2 tool calls, execute directly — delegation overhead is not worth the cost",
+    "Consult the task routing guide below to match task type to the correct tier",
+    "Consider cost ratios when choosing tiers — always use the cheapest tier that can reliably handle the task"
   ],
   "defaultTier": "medium"
 }