What Is Combo Routing Resolution in OmniRoute? A Deep Dive into the Routing Engine

Combo routing resolution is the core mechanism that transforms a user-defined combo—containing a list of models, a routing strategy, and optional nested combos—into an ordered set of concrete execution targets, complete with resilience checks and execution tracing.

In the OmniRoute repository (diegosouzapw/OmniRoute), combo routing resolution serves as the bridge between high-level routing configuration and actual LLM invocation. This process, implemented in the routing engine, ensures that abstract combo definitions are translated into provider-specific execution plans with proper failover handling and observability.

Core Components of the Routing Engine

The combo routing resolution pipeline spans two primary modules in the open-sse/services/ directory. Understanding these files is essential for tracing how a request moves from definition to dispatch.

Entry Point: handleComboChat

The resolution process begins in open-sse/services/combo.ts within the handleComboChat() function. This handler receives the request payload and combo definition, immediately expanding the combo into concrete targets by invoking resolveComboTargets()【https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/services/combo.ts#L698】.

The output of this expansion is an array of ResolvedComboTarget objects. Each target encapsulates:

• Provider identifier and model ID
• Connection credentials
• Runtime metadata (quota status, circuit-breaker state)

Target Resolution Logic in comboStructure.ts

The actual resolution logic resides in open-sse/services/combo/comboStructure.ts, specifically within the resolveComboTargets() function【https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/services/combo/comboStructure.ts#L13-L18】. This module handles the structural expansion of combo definitions, supporting both flat and hierarchically nested configurations.

How Target Resolution Works

The resolution process follows a distinct two-phase approach: structural expansion followed by visibility filtering.

Recursive Expansion of Nested Combos

When resolveComboTargets() processes a combo, it first checks for the presence of nested definitions via the allCombos parameter. If nested combos exist, the function recursively expands them through resolveNestedComboTargets(). Otherwise, it falls back to getOrderedTopLevelRuntimeSteps() to process the top-level runtime configuration.

This recursive design allows OmniRoute to support complex routing hierarchies where high-level routing strategies delegate to specialized sub-combos.

Visibility Filtering

After expansion, the raw target list passes through filterVisibleComboTargets(). This function removes any models hidden via the dashboard configuration by consulting getHiddenModelsByProvider(). Only visible, active targets proceed to the strategy-specific ordering phase.

Strategy-Specific Ordering

Once the engine produces the filtered target list, it applies the selected routing strategy to determine execution order. OmniRoute supports multiple strategies including priority, weighted, round-robin, auto, and fusion.

Each strategy implements a dedicated helper function:

• scoreAutoTargets – Builds candidate pools and applies cost/latency scoring for the auto strategy
• resolveWeightedTargets – Selects and orders targets based on configured weights

The final ordered array is stored in orderedTargets and subsequently fed into the per-target dispatch loop that calls handleSingleModel().

Resilience and Gating Mechanisms

Before any target executes, the routing engine performs a cascade of resilience checks within executeTarget() inside handleComboChat(). These safeguards prevent resource waste and ensure graceful degradation:

• Provider-level circuit breaker – Checked via getCircuitBreaker()
• Provider-wide cooldown – Validated through isProviderInCooldown()
• Model-level lockout – Enforced by isModelLocked()
• Quota exhaustion cutoff – Determined by resolveQuotaExhaustionCutoffForTarget()
• Context overflow and parameter validation – Handled by predicates like isContextOverflow400()

If any check fails, the engine skips the target and falls back to the next ordered candidate, maintaining system stability without client-side intervention.

Execution Tracing for Observability

For debugging and analytics, the routing engine maintains a per-invocation execution trace. Key trace operations include:

• startComboTrace() – Initializes the trace context
• recordComboDecision() – Logs each routing decision (dispatch, skip, or failure)
• finishComboTrace() – Completes the trace record

The trace ID returns to the client via the X-OmniRoute-Combo-Trace response header, enabling post-mortem analysis of specific routing decisions.

Implementation Examples

Resolving a Combo to Runnable Targets

// Example: Resolve a combo to a list of runnable targets
import { resolveComboTargets } from "@omniroute/open-sse/services/combo.ts";

const combo = await getComboFromData("my-combo");
const allCombos = await getAllCombos(); // nested combos collection
const targets = resolveComboTargets(combo, allCombos);

// `targets` is an array of ResolvedComboTarget ready for dispatch

Dispatching a Combo with the Default Handler

// Example: Dispatch a combo using the default handler
import { handleComboChat } from "@omniroute/open-sse/services/combo.ts";

const response = await handleComboChat({
  body: requestBody,
  combo,
  handleSingleModel: (body, model) => fetchProvider(body, model),
  log: logger,
  settings: {},               // optional resilience settings
  allCombos,                  // nested combos if any
});

Summary

• Combo routing resolution transforms abstract combo definitions into executable target lists through the resolveComboTargets() function in open-sse/services/combo/comboStructure.ts.
• The process supports recursive nested combo expansion and visibility filtering to ensure only active, permitted models enter the execution pipeline.
• Strategy-specific ordering reorders targets based on priority, weight, or auto-scoring algorithms before dispatch.
• Resilience checks including circuit breakers, cooldowns, and quota validation occur immediately before execution in executeTarget().
• Full execution tracing via X-OmniRoute-Combo-Trace headers provides observability into routing decisions.

Frequently Asked Questions

How does OmniRoute handle nested combos during resolution?

OmniRoute resolves nested combos recursively through resolveNestedComboTargets() in comboStructure.ts. When the allCombos parameter contains child definitions, the engine expands them inline before applying visibility filters and strategy ordering, allowing complex hierarchical routing configurations.

What happens when a model fails the resilience checks?

When a target fails resilience checks—such as circuit breaker trips, provider cooldowns, or model lockouts—the executeTarget() function records the skip decision via recordComboDecision() and immediately attempts the next target in the orderedTargets array. This happens transparently without returning an error to the client until all targets are exhausted.

Where can I find the implementation of the auto-routing strategy?

The auto-routing strategy is implemented in open-sse/services/combo/autoStrategy.ts. This module contains the scoreAutoTargets() function, which builds candidate pools and applies cost and latency scoring to dynamically select the optimal model for each request.

How can I trace a specific combo routing decision?

Each combo invocation generates a unique trace ID through startComboTrace() in open-sse/services/combo.ts. The system returns this ID in the X-OmniRoute-Combo-Trace HTTP header, allowing you to correlate client requests with internal routing decisions logged via recordComboDecision().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}