# Where to Find OmniRoute's Combo Handler: Complete Source Code Guide

> Find OmniRoute's combo handler code in open-sse/services/combo.ts. Explore the full source code guide for the handleComboChat function and related logic in the open-sse/services/combo/ directory.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: source-code-guide
- Published: 2026-07-09

---

**OmniRoute's combo handler lives in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) as the `handleComboChat` function, with supporting logic distributed across the `open-sse/services/combo/` directory.**

OmniRoute implements sophisticated model routing through its "combo" system, which orchestrates multiple AI providers and fallback strategies. If you are debugging routing behavior or extending the framework, you need to locate the core **OmniRoute combo handler** code. The implementation resides in the Open-SSE services layer of the `diegosouzapw/OmniRoute` repository.

## Main Entry Point: open-sse/services/combo.ts

The primary entry point for all combo processing is [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts). This file exports `handleComboChat`, the main async function that implements the full routing lifecycle including fallback chains, session stickiness, auto-combo selection, and quota management.

```typescript
// open-sse/services/combo.ts
export async function handleComboChat(params: {
  body: any;
  combo: ComboDefinition;
  handleSingleModel: ModelExecutor;
  isModelAvailable?: ModelAvailabilityChecker;
  log: Logger;
  settings: Settings;
  allCombos: ComboMap | null;
  relayOptions: RelayOptions;
  signal?: AbortSignal;
}): Promise<Response> {
  // Full orchestration logic: pinning, strategy selection, retries, etc.
}

```

This function returns a standard Fetch API `Response` and is designed to be pure-async, making it easy to integrate into Next.js API routes or other server frameworks.

## Supporting Modules in the Combo Directory

The handler delegates specific responsibilities to specialized modules within `open-sse/services/combo/`:

- **[`comboStructure.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboStructure.ts)** – Contains `resolveComboTargets`, `resolveComboRuntimeUnits`, and `filterTargetsByRequestCompatibility` for turning combo definitions into executable target lists.
- **[`applyStrategyOrdering.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/applyStrategyOrdering.ts)** – Implements the 17 built-in routing strategies including **priority**, **weighted**, **round-robin**, and **quota-share**.
- **[`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts)** – Houses `buildAutoCandidates` and `resolveAutoStrategyOrder` for automatic model selection based on scoring heuristics.
- **[`fusion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/fusion.ts)** – Implements `handleFusionChat` for parallel model panels with a judging model.
- **[`pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/pipeline.ts)** – Implements `handlePipelineChat` for sequential model chaining.
- **[`quotaShareStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/quotaShareStrategy.ts)** – Handles quota-share target selection and concurrency limits.
- **[`comboCooldownRetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboCooldownRetry.ts)** – Manages the "cool-down-wait" mechanic for quota-share strategies.
- **[`comboPredicates.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboPredicates.ts)** – Provides predicate functions for target eligibility checks (model lockout, provider cooldown).
- **[`rrState.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rrState.ts)** – Maintains round-robin sticky state (counters and sticky targets).

## How the Combo Handler Works (Execution Flow)

Understanding the `handleComboChat` implementation requires following its strict 11-phase execution pipeline:

### 1. Context Setup

The handler begins by calling `phaseComboSetup` to create a `comboCtx` object containing the request body, combo definition, runtime settings, and logger.

### 2. Pinned Model Shortcut

If a session-cache pin exists, the handler attempts the pinned model first, guarded by health checks before proceeding to the full strategy.

### 3. Strategy Shortcuts

For specialized modes, the handler routes directly to subsystem handlers:
- **`fusion`** → `handleFusionChat` (parallel execution with judge)
- **`pipeline`** → `handlePipelineChat` (sequential steps)

### 4. Target Expansion and Resolution

Wildcards like `openai/*` are expanded via `expandProviderWildcardsInCombo`. Then `resolveComboTargets` flattens the combo definition into a list of `ResolvedComboTarget` objects.

### 5. Strategy-Specific Ordering

Depending on the strategy defined in the combo:
- Simple strategies (`priority`, `round-robin`, `weighted`) build an ordered list directly.
- **`auto`** triggers `resolveAutoStrategyOrder`, which calls `buildAutoCandidates` to generate and score candidates.

### 6. Session Stickiness and Task Routing

The handler optionally re-orders targets based on recent successful targets. If enabled, `classifyTask` and `reorderByTaskWeight` further refine the order based on task-aware weights.

### 7. Pre-Screen and Quota Checks

Early validation prunes unavailable targets using provider cooldown checks and quota-share availability.

### 8. Execution Loop

The handler iterates through ordered targets, invoking `handleSingleModelWithTimeout` for each attempt. This loop includes:
- Quality validation via `validateResponseQuality`
- Retry logic with per-target back-off
- Global `MAX_GLOBAL_ATTEMPTS` enforcement
- Quota-share cooldown waits

### 9. Shadow Routing

Parallel "shadow" targets execute for telemetry purposes without affecting the primary response path.

If all targets fail, the function returns a `comboModelNotFoundResponse` (404-style error).

## Practical Usage Example

The following pattern shows how higher-level routes (such as [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)) invoke the combo handler:

```typescript
import { handleComboChat } from '@/open-sse/services/combo';

async function routeCombo(requestBody: any) {
  // Retrieve combo definition from your data store
  const combo = await getComboFromDb('my-awesome-combo');

  const response = await handleComboChat({
    body: requestBody,
    combo,
    handleSingleModel: (body, modelStr, target) => 
      defaultExecutor.execute(body, modelStr, target),
    isModelAvailable: undefined,
    log: console,
    settings: {},
    allCombos: null,
    relayOptions: {},
    signal: undefined,
  });

  return response; // Returns standard Fetch API Response
}

```

This structure delegates the complex routing orchestration to the combo service while keeping the API route thin and maintainable.

## Summary

- **Primary Location:** [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) contains the `handleComboChat` function that serves as the single source of truth for combo routing.
- **Strategy Implementations:** [`open-sse/services/combo/applyStrategyOrdering.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/applyStrategyOrdering.ts) defines the 17 built-in routing algorithms.
- **Advanced Modes:** Fusion and pipeline strategies live in [`fusion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/fusion.ts) and [`pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/pipeline.ts) respectively.
- **State Management:** Round-robin state and auto-combo scoring reside in [`rrState.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rrState.ts) and [`autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/autoStrategy.ts).
- **Integration:** The handler is framework-agnostic, returning a standard `Response` object suitable for Next.js, Express, or other Node.js servers.

## Frequently Asked Questions

### What is the main function that handles combo routing in OmniRoute?

The main function is **`handleComboChat`** exported from [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts). This async function orchestrates the entire combo lifecycle including strategy selection, target resolution, fallback retries, and session stickiness.

### Where are the routing strategies like round-robin and weighted implemented?

These strategies are implemented in **[`open-sse/services/combo/applyStrategyOrdering.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/applyStrategyOrdering.ts)**. This module contains the logic for all 17 built-in strategies including priority, weighted distribution, round-robin, auto-selection, and quota-share.

### How does OmniRoute handle automatic model selection in combos?

Auto-combo logic resides in **[`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts)**. The `buildAutoCandidates` function generates eligible model candidates, while `resolveAutoStrategyOrder` applies scoring heuristics to select the optimal target without manual configuration.

### What file contains the fusion and pipeline strategy logic?

Fusion (parallel panel with judge) and pipeline (sequential chaining) have dedicated files: **[`open-sse/services/combo/fusion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/fusion.ts)** and **[`open-sse/services/combo/pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/pipeline.ts)**. These export `handleFusionChat` and `handlePipelineChat`, which are called as shortcuts within the main combo handler when those specific strategies are requested.