@blockrun/clawrouter 0.12.38 → 0.12.40

package/dist/index.d.ts

@@ -128,6 +128,42 @@ type OpenClawPluginDefinition = {
     activate?: (api: OpenClawPluginApi) => void | Promise<void>;
 };
 
+/**
+ * Tier → Model Selection
+ *
+ * Maps a classification tier to the cheapest capable model.
+ * Builds RoutingDecision metadata with cost estimates and savings.
+ */
+
+type ModelPricing = {
+    inputPrice: number;
+    outputPrice: number;
+};
+/**
+ * Get the ordered fallback chain for a tier: [primary, ...fallbacks].
+ */
+declare function getFallbackChain(tier: Tier, tierConfigs: Record<Tier, TierConfig>): string[];
+/**
+ * Calculate cost for a specific model (used when fallback model is used).
+ * Returns updated cost fields for RoutingDecision.
+ */
+declare function calculateModelCost(model: string, modelPricing: Map<string, ModelPricing>, estimatedInputTokens: number, maxOutputTokens: number, routingProfile?: "free" | "eco" | "auto" | "premium"): {
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+};
+/**
+ * Get the fallback chain filtered by context length.
+ * Only returns models that can handle the estimated total context.
+ *
+ * @param tier - The tier to get fallback chain for
+ * @param tierConfigs - Tier configurations
+ * @param estimatedTotalTokens - Estimated total context (input + output)
+ * @param getContextWindow - Function to get context window for a model ID
+ * @returns Filtered list of models that can handle the context
+ */
+declare function getFallbackChainFiltered(tier: Tier, tierConfigs: Record<Tier, TierConfig>, estimatedTotalTokens: number, getContextWindow: (modelId: string) => number | undefined): string[];
+
 /**
  * Smart Router Types
  *
@@ -148,6 +184,16 @@ type RoutingDecision = {
     baselineCost: number;
     savings: number;
     agenticScore?: number;
+    /** Which tier configs were used (auto/eco/premium/agentic) — avoids re-derivation in proxy */
+    tierConfigs?: Record<Tier, TierConfig>;
+    /** Which routing profile was applied */
+    profile?: "auto" | "eco" | "premium" | "agentic";
+};
+type RouterOptions = {
+    config: RoutingConfig;
+    modelPricing: Map<string, ModelPricing>;
+    routingProfile?: "free" | "eco" | "auto" | "premium";
+    hasTools?: boolean;
 };
 type TierConfig = {
     primary: string;
@@ -211,42 +257,6 @@ type RoutingConfig = {
     overrides: OverridesConfig;
 };
 
-/**
- * Tier → Model Selection
- *
- * Maps a classification tier to the cheapest capable model.
- * Builds RoutingDecision metadata with cost estimates and savings.
- */
-
-type ModelPricing = {
-    inputPrice: number;
-    outputPrice: number;
-};
-/**
- * Get the ordered fallback chain for a tier: [primary, ...fallbacks].
- */
-declare function getFallbackChain(tier: Tier, tierConfigs: Record<Tier, TierConfig>): string[];
-/**
- * Calculate cost for a specific model (used when fallback model is used).
- * Returns updated cost fields for RoutingDecision.
- */
-declare function calculateModelCost(model: string, modelPricing: Map<string, ModelPricing>, estimatedInputTokens: number, maxOutputTokens: number, routingProfile?: "free" | "eco" | "auto" | "premium"): {
-    costEstimate: number;
-    baselineCost: number;
-    savings: number;
-};
-/**
- * Get the fallback chain filtered by context length.
- * Only returns models that can handle the estimated total context.
- *
- * @param tier - The tier to get fallback chain for
- * @param tierConfigs - Tier configurations
- * @param estimatedTotalTokens - Estimated total context (input + output)
- * @param getContextWindow - Function to get context window for a model ID
- * @returns Filtered list of models that can handle the context
- */
-declare function getFallbackChainFiltered(tier: Tier, tierConfigs: Record<Tier, TierConfig>, estimatedTotalTokens: number, getContextWindow: (modelId: string) => number | undefined): string[];
-
 /**
  * Default Routing Config
  *
@@ -262,24 +272,12 @@ declare const DEFAULT_ROUTING_CONFIG: RoutingConfig;
  * Smart Router Entry Point
  *
  * Classifies requests and routes to the cheapest capable model.
- * 100% local — rules-based scoring handles all requests in <1ms.
- * Ambiguous cases default to configurable tier (MEDIUM by default).
+ * Delegates to pluggable RouterStrategy (default: RulesStrategy, <1ms).
  */
 
-type RouterOptions = {
-    config: RoutingConfig;
-    modelPricing: Map<string, ModelPricing>;
-    routingProfile?: "free" | "eco" | "auto" | "premium";
-    hasTools?: boolean;
-};
 /**
  * Route a request to the cheapest capable model.
- *
- * 1. Check overrides (large context, structured output)
- * 2. Run rule-based classifier (14 weighted dimensions, <1ms)
- * 3. If ambiguous, default to configurable tier (no external API calls)
- * 4. Select model for tier
- * 5. Return RoutingDecision with metadata
+ * Delegates to the registered "rules" strategy by default.
  */
 declare function route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): RoutingDecision;
 

package/dist/index.js

@@ -2022,6 +2022,99 @@ function getFallbackChainFiltered(tier, tierConfigs, estimatedTotalTokens, getCo
   return filtered;
 }
 
+// src/router/strategy.ts
+var RulesStrategy = class {
+  name = "rules";
+  route(prompt, systemPrompt, maxOutputTokens, options) {
+    const { config, modelPricing } = options;
+    const fullText = `${systemPrompt ?? ""} ${prompt}`;
+    const estimatedTokens = Math.ceil(fullText.length / 4);
+    const ruleResult = classifyByRules(prompt, systemPrompt, estimatedTokens, config.scoring);
+    const { routingProfile } = options;
+    let tierConfigs;
+    let profileSuffix;
+    let profile;
+    if (routingProfile === "eco" && config.ecoTiers) {
+      tierConfigs = config.ecoTiers;
+      profileSuffix = " | eco";
+      profile = "eco";
+    } else if (routingProfile === "premium" && config.premiumTiers) {
+      tierConfigs = config.premiumTiers;
+      profileSuffix = " | premium";
+      profile = "premium";
+    } else {
+      const agenticScore = ruleResult.agenticScore ?? 0;
+      const isAutoAgentic = agenticScore >= 0.5;
+      const isExplicitAgentic = config.overrides.agenticMode ?? false;
+      const hasToolsInRequest = options.hasTools ?? false;
+      const useAgenticTiers = (hasToolsInRequest || isAutoAgentic || isExplicitAgentic) && config.agenticTiers != null;
+      tierConfigs = useAgenticTiers ? config.agenticTiers : config.tiers;
+      profileSuffix = useAgenticTiers ? ` | agentic${hasToolsInRequest ? " (tools)" : ""}` : "";
+      profile = useAgenticTiers ? "agentic" : "auto";
+    }
+    const agenticScoreValue = ruleResult.agenticScore;
+    if (estimatedTokens > config.overrides.maxTokensForceComplex) {
+      const decision2 = selectModel(
+        "COMPLEX",
+        0.95,
+        "rules",
+        `Input exceeds ${config.overrides.maxTokensForceComplex} tokens${profileSuffix}`,
+        tierConfigs,
+        modelPricing,
+        estimatedTokens,
+        maxOutputTokens,
+        routingProfile,
+        agenticScoreValue
+      );
+      return { ...decision2, tierConfigs, profile };
+    }
+    const hasStructuredOutput = systemPrompt ? /json|structured|schema/i.test(systemPrompt) : false;
+    let tier;
+    let confidence;
+    const method = "rules";
+    let reasoning = `score=${ruleResult.score.toFixed(2)} | ${ruleResult.signals.join(", ")}`;
+    if (ruleResult.tier !== null) {
+      tier = ruleResult.tier;
+      confidence = ruleResult.confidence;
+    } else {
+      tier = config.overrides.ambiguousDefaultTier;
+      confidence = 0.5;
+      reasoning += ` | ambiguous -> default: ${tier}`;
+    }
+    if (hasStructuredOutput) {
+      const tierRank = { SIMPLE: 0, MEDIUM: 1, COMPLEX: 2, REASONING: 3 };
+      const minTier = config.overrides.structuredOutputMinTier;
+      if (tierRank[tier] < tierRank[minTier]) {
+        reasoning += ` | upgraded to ${minTier} (structured output)`;
+        tier = minTier;
+      }
+    }
+    reasoning += profileSuffix;
+    const decision = selectModel(
+      tier,
+      confidence,
+      method,
+      reasoning,
+      tierConfigs,
+      modelPricing,
+      estimatedTokens,
+      maxOutputTokens,
+      routingProfile,
+      agenticScoreValue
+    );
+    return { ...decision, tierConfigs, profile };
+  }
+};
+var registry = /* @__PURE__ */ new Map();
+registry.set("rules", new RulesStrategy());
+function getStrategy(name) {
+  const strategy = registry.get(name);
+  if (!strategy) {
+    throw new Error(`Unknown routing strategy: ${name}`);
+  }
+  return strategy;
+}
+
 // src/router/config.ts
 var DEFAULT_ROUTING_CONFIG = {
   version: "2.0",
@@ -3114,7 +3207,11 @@ var DEFAULT_ROUTING_CONFIG = {
     SIMPLE: {
       primary: "nvidia/gpt-oss-120b",
       // FREE! $0.00/$0.00
-      fallback: ["google/gemini-2.5-flash-lite", "google/gemini-2.5-flash", "deepseek/deepseek-chat"]
+      fallback: [
+        "google/gemini-2.5-flash-lite",
+        "google/gemini-2.5-flash",
+        "deepseek/deepseek-chat"
+      ]
     },
     MEDIUM: {
       primary: "google/gemini-2.5-flash-lite",
@@ -3239,77 +3336,8 @@ var DEFAULT_ROUTING_CONFIG = {
 
 // src/router/index.ts
 function route(prompt, systemPrompt, maxOutputTokens, options) {
-  const { config, modelPricing } = options;
-  const fullText = `${systemPrompt ?? ""} ${prompt}`;
-  const estimatedTokens = Math.ceil(fullText.length / 4);
-  const ruleResult = classifyByRules(prompt, systemPrompt, estimatedTokens, config.scoring);
-  const { routingProfile } = options;
-  let tierConfigs;
-  let profileSuffix;
-  if (routingProfile === "eco" && config.ecoTiers) {
-    tierConfigs = config.ecoTiers;
-    profileSuffix = " | eco";
-  } else if (routingProfile === "premium" && config.premiumTiers) {
-    tierConfigs = config.premiumTiers;
-    profileSuffix = " | premium";
-  } else {
-    const agenticScore = ruleResult.agenticScore ?? 0;
-    const isAutoAgentic = agenticScore >= 0.5;
-    const isExplicitAgentic = config.overrides.agenticMode ?? false;
-    const hasToolsInRequest = options.hasTools ?? false;
-    const useAgenticTiers = (hasToolsInRequest || isAutoAgentic || isExplicitAgentic) && config.agenticTiers != null;
-    tierConfigs = useAgenticTiers ? config.agenticTiers : config.tiers;
-    profileSuffix = useAgenticTiers ? ` | agentic${hasToolsInRequest ? " (tools)" : ""}` : "";
-  }
-  const agenticScoreValue = ruleResult.agenticScore;
-  if (estimatedTokens > config.overrides.maxTokensForceComplex) {
-    return selectModel(
-      "COMPLEX",
-      0.95,
-      "rules",
-      `Input exceeds ${config.overrides.maxTokensForceComplex} tokens${profileSuffix}`,
-      tierConfigs,
-      modelPricing,
-      estimatedTokens,
-      maxOutputTokens,
-      routingProfile,
-      agenticScoreValue
-    );
-  }
-  const hasStructuredOutput = systemPrompt ? /json|structured|schema/i.test(systemPrompt) : false;
-  let tier;
-  let confidence;
-  const method = "rules";
-  let reasoning = `score=${ruleResult.score.toFixed(2)} | ${ruleResult.signals.join(", ")}`;
-  if (ruleResult.tier !== null) {
-    tier = ruleResult.tier;
-    confidence = ruleResult.confidence;
-  } else {
-    tier = config.overrides.ambiguousDefaultTier;
-    confidence = 0.5;
-    reasoning += ` | ambiguous -> default: ${tier}`;
-  }
-  if (hasStructuredOutput) {
-    const tierRank = { SIMPLE: 0, MEDIUM: 1, COMPLEX: 2, REASONING: 3 };
-    const minTier = config.overrides.structuredOutputMinTier;
-    if (tierRank[tier] < tierRank[minTier]) {
-      reasoning += ` | upgraded to ${minTier} (structured output)`;
-      tier = minTier;
-    }
-  }
-  reasoning += profileSuffix;
-  return selectModel(
-    tier,
-    confidence,
-    method,
-    reasoning,
-    tierConfigs,
-    modelPricing,
-    estimatedTokens,
-    maxOutputTokens,
-    routingProfile,
-    agenticScoreValue
-  );
+  const strategy = getStrategy("rules");
+  return strategy.route(prompt, systemPrompt, maxOutputTokens, options);
 }
 
 // src/logger.ts
@@ -5454,6 +5482,12 @@ var ROUTING_PROFILES = /* @__PURE__ */ new Set([
   "premium"
 ]);
 var FREE_MODEL = "nvidia/gpt-oss-120b";
+var FREE_TIER_CONFIGS = {
+  SIMPLE: { primary: FREE_MODEL, fallback: [] },
+  MEDIUM: { primary: FREE_MODEL, fallback: [] },
+  COMPLEX: { primary: FREE_MODEL, fallback: [] },
+  REASONING: { primary: FREE_MODEL, fallback: [] }
+};
 var freeRequestCount = 0;
 var MAX_MESSAGES = 200;
 var CONTEXT_LIMIT_KB = 5120;
@@ -7328,16 +7362,17 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
 
 `;
           }
-          await logUsage({
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          routingDecision = {
             model: freeModel,
             tier: "SIMPLE",
-            cost: 0,
+            confidence: 1,
+            method: "rules",
+            reasoning: "free profile",
+            costEstimate: 0,
             baselineCost: 0,
             savings: 1,
-            // 100% savings
-            latencyMs: 0
-          });
+            tierConfigs: FREE_TIER_CONFIGS
+          };
         } else {
           effectiveSessionId = getSessionId(req.headers) ?? deriveSessionId(parsedMessages);
           const existingSession = effectiveSessionId ? sessionStore.getSession(effectiveSessionId) : void 0;
@@ -7428,18 +7463,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
             const contentHash = hashRequestContent(prompt, toolCallNames);
             const shouldEscalate = sessionStore.recordRequestHash(effectiveSessionId, contentHash);
             if (shouldEscalate) {
-              const activeTierConfigs = (() => {
-                if (routingDecision.reasoning?.includes("agentic") && routerOpts.config.agenticTiers) {
-                  return routerOpts.config.agenticTiers;
-                }
-                if (routingProfile === "eco" && routerOpts.config.ecoTiers) {
-                  return routerOpts.config.ecoTiers;
-                }
-                if (routingProfile === "premium" && routerOpts.config.premiumTiers) {
-                  return routerOpts.config.premiumTiers;
-                }
-                return routerOpts.config.tiers;
-              })();
+              const activeTierConfigs = routingDecision.tierConfigs ?? routerOpts.config.tiers;
               const escalation = sessionStore.escalateSession(
                 effectiveSessionId,
                 activeTierConfigs
@@ -7655,18 +7679,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
     if (routingDecision) {
       const estimatedInputTokens = Math.ceil(body.length / 4);
       const estimatedTotalTokens = estimatedInputTokens + maxTokens;
-      const tierConfigs = (() => {
-        if (routingDecision.reasoning?.includes("agentic") && routerOpts.config.agenticTiers) {
-          return routerOpts.config.agenticTiers;
-        }
-        if (routingProfile === "eco" && routerOpts.config.ecoTiers) {
-          return routerOpts.config.ecoTiers;
-        }
-        if (routingProfile === "premium" && routerOpts.config.premiumTiers) {
-          return routerOpts.config.premiumTiers;
-        }
-        return routerOpts.config.tiers;
-      })();
+      const tierConfigs = routingDecision.tierConfigs ?? routerOpts.config.tiers;
       const fullChain = getFallbackChain(routingDecision.tier, tierConfigs);
       const contextFiltered = getFallbackChainFiltered(
         routingDecision.tier,
@@ -7746,6 +7759,14 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
         status: result.errorStatus || 500
       };
       if (result.isProviderError && !isLastAttempt) {
+        const isExplicitModelError = !routingDecision;
+        const isUnknownExplicitModel = isExplicitModelError && /unknown.*model|invalid.*model/i.test(result.errorBody || "");
+        if (isUnknownExplicitModel) {
+          console.log(
+            `[ClawRouter] Explicit model error from ${tryModel}, not falling back: ${result.errorBody?.slice(0, 100)}`
+          );
+          break;
+        }
         if (result.errorStatus === 429) {
           markRateLimited(tryModel);
           try {