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

> Discover combo routing resolution in OmniRoute. This core engine transforms user-defined combos into ordered execution targets, ensuring resilience and tracing for your routing needs.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-23

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboStructure.ts)

The actual resolution logic resides in [`open-sse/services/combo/comboStructure.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```typescript
// 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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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()`.