# What Is the Main Function of Each Key Executor in OmniRoute? A Technical Deep Dive

> Explore OmniRoute's key executors: BaseExecutor, DefaultExecutor, and CursorExecutor. Understand how they transform LLM requests into provider-specific HTTP calls for efficient data processing.

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

---

**OmniRoute's executors are specialized TypeScript classes that transform normalized LLM requests into provider-specific HTTP calls, with `BaseExecutor` defining the core strategy pattern, `DefaultExecutor` adapting hundreds of standard providers, and `CursorExecutor` implementing a custom HTTP/2 RPC protocol for bidirectional tool streaming.**

The **executor pattern** sits at the heart of the OmniRoute open-source proxy, serving as the final abstraction layer that converts generic chat completion requests into the unique wire formats required by OpenAI, Anthropic, Azure, Cursor, and dozens of other providers. Understanding what each key executor in OmniRoute does is essential for debugging provider-specific failures, extending the platform to support new LLMs, or optimizing routing performance in production environments.

## The Executor Architecture: How OmniRoute Routes LLM Requests

OmniRoute implements a **Strategy pattern** where each executor encapsulates the complete lifecycle of a provider request. The pipeline flows through four distinct stages: First, [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) receives the incoming request and resolves the target provider. Second, the factory function in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) instantiates the appropriate executor class based on the provider ID. Third, the handler constructs an `ExecuteInput` object containing the model, body, credentials, and stream flag. Finally, the executor's `execute()` method performs the actual HTTP transaction, handling retries, token refresh, and response streaming.

## BaseExecutor: The Core Strategy Pattern

**`BaseExecutor`** serves as the abstract foundation for every provider integration in OmniRoute. Located in [`open-sse/executors/base.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/base.ts) (lines 27-43), this class implements the universal mechanics of HTTP communication that remain consistent across all providers.

The class defines the template method `execute()` (lines 560-720), which orchestrates the entire request lifecycle. Key responsibilities include:

- **URL Construction**: The `buildUrl()` method sanitizes endpoint paths and injects provider-specific route segments.
- **Header Management**: `buildHeaders()` prepares authentication pre-ambles, content-type declarations, and fingerprinting metadata.
- **Request Transformation**: `transformRequest()` normalizes the JSON body, strips unsupported parameters, and injects provider defaults.
- **Token Refresh**: `needsRefresh()` evaluates credential expiration and triggers rotation via [`open-sse/services/apiKeyRotator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/apiKeyRotator.ts).
- **Retry Logic**: Exponential backoff and circuit-breaker patterns handle transient network failures.
- **Streaming Orchestration**: The executor manages SSE (Server-Sent Events) chunk generation for streaming responses or buffers JSON payloads for non-streaming calls.

When you create a new provider integration, you typically extend `BaseExecutor` and override only the specific methods that differ from the standard HTTP POST pattern.

## DefaultExecutor: The Universal Adapter for Standard Providers

**`DefaultExecutor`** functions as the workhorse implementation for the majority of LLM providers in the OmniRoute ecosystem. Defined in [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) (lines 96-115), this class extends `BaseExecutor` while adding provider-specific customizations for OpenAI-compatible APIs, Anthropic, Azure, Snowflake, Gemini, and others.

The executor performs several critical adaptations:

- **URL Path Injection**: Automatically appends provider-specific segments like `/v1/chat/completions` or `/v1/messages` based on the configuration in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts).
- **Header Customization**: Merges custom headers for authentication variants, including support for `x-api-key` versus `authorization` bearer tokens.
- **Parameter Filtering**: Strips unsupported JSON fields from the request body that would cause 400 errors with specific providers.
- **Edge-Case Handling**: Implements special logic for non-standard providers like OpenRouter, Qwen, and Gigachat, adjusting request shapes to match their unique schemas.

**`DefaultExecutor`** essentially acts as a universal translator, allowing OmniRoute to support hundreds of providers without requiring dedicated code for each one.

## CursorExecutor: Custom HTTP/2 RPC Implementation

**`CursorExecutor`** represents a radical departure from the standard HTTP request-response pattern, providing specialized handling for the Cursor LLM service. Located in [`open-sse/executors/cursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/cursor.ts) (lines 1-90), this executor implements a bidirectional **Connect-RPC** protocol over HTTP/2.

Unlike other executors that rely on simple POST requests, **`CursorExecutor`** manages:

- **Binary Protocol Handling**: Uses [`open-sse/utils/cursorAgentProtobuf.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/cursorAgentProtobuf.ts) to encode and decode Protobuf frames for the Cursor wire format.
- **Session Management**: Maintains stateful connections for tool-call continuations through methods `openH2()` and `driveH2()`.
- **Bidirectional Streaming**: Simultaneously sends request chunks while receiving text generation and tool-call events.
- **Frame Processing**: The `processFrame()` method (lines 380-525) decodes Cursor-specific binary frames, extracts MCP (Model Context Protocol) tool definitions, and synthesizes OpenAI-compatible SSE chunks for downstream consumers.

This executor essentially bridges Cursor's proprietary real-time protocol with OmniRoute's standardized SSE output format, enabling tool-use capabilities that would otherwise break in a standard HTTP adapter.

## Provider-Specific Thin Wrappers and Specialized Executors

Beyond the three primary executors, OmniRoute maintains a collection of **thin wrapper classes** that exist primarily for registry discoverability. Files like [`github.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/github.ts), [`gitlab.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/gitlab.ts), and [`aws-polly.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/aws-polly.ts) export classes extending `BaseExecutor` with nothing more than a provider name constructor:

```typescript
// From open-sse/executors/github.ts
export class GithubExecutor extends BaseExecutor {
  constructor() {
    super('github', PROVIDERS.github);
  }
}

```

These wrappers allow the factory in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) to map provider IDs to concrete classes without conditional logic.

**`OpenCodeExecutor`** (in [`open-sse/executors/opencode.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/opencode.ts), lines 1-30) represents a specialized variant that extends `BaseExecutor` to forward client-side headers prefixed with `x-opencode-*` to upstream providers, enabling OpenCode-specific features while reusing the base HTTP implementation.

## How Executors Fit Into the Request Pipeline

Understanding the execution flow helps debug where provider-specific logic applies:

1. **Request Routing**: [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) receives the HTTP request and extracts the provider ID from the path or headers.
2. **Executor Resolution**: The handler calls `getExecutor(providerId)` from [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts), which returns an instance of `DefaultExecutor`, `CursorExecutor`, or a specialized wrapper.
3. **Input Preparation**: The handler constructs an `ExecuteInput` object containing the model identifier, normalized request body, streaming flag, and credentials retrieved from `getValidApiKey()`.
4. **Execution**: The executor's `execute()` method builds the final URL, headers, and body, then initiates the upstream HTTP connection.
5. **Response Streaming**: For streaming requests, the executor reads the upstream response and yields SSE chunks; for non-streaming, it buffers and returns the complete JSON payload.

## Practical Implementation Examples

### Using an Executor Directly

While normally the handler manages execution, you can instantiate executors directly for testing or custom workflows:

```typescript
import { getExecutor } from '@/open-sse/executors/index.ts';
import { getValidApiKey } from '@/open-sse/services/apiKeyRotator.ts';

// Configure request for OpenAI's GPT-4o
const provider = 'openai';
const model = 'gpt-4o';
const body = {
  model,
  messages: [{ role: 'user', content: 'Hello, world!' }],
  stream: true,
};

// Resolve credentials and executor
const credentials = await getValidApiKey(provider);
const exec = getExecutor(provider);  // Returns DefaultExecutor instance

// Execute and receive stream
const result = await exec.execute({
  model,
  body,
  stream: true,
  credentials,
  signal: null,
  log: console,
});

```

### Creating a Custom Provider Executor

To integrate a proprietary API with unique URL requirements:

```typescript
// src/open-sse/executors/my-custom.ts
import { BaseExecutor } from './base.ts';
import { PROVIDERS } from '../config/constants.ts';

export class MyCustomExecutor extends BaseExecutor {
  constructor() {
    super('my-custom', PROVIDERS['my-custom']);
  }

  // Override URL construction
  buildUrl() {
    return 'https://api.my-custom.com/v1/chat';
  }

  // Transform request body before sending
  transformRequest(model, body, stream, credentials) {
    const newBody = { ...body, customFlag: true };
    return super.transformRequest(model, newBody, stream, credentials);
  }
}

```

Register the new executor in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts):

```typescript
import { MyCustomExecutor } from './my-custom.ts';

export function getExecutor(provider: string) {
  switch (provider) {
    case 'my-custom': return new MyCustomExecutor();
    // ...existing cases
    default: return new DefaultExecutor(provider);
  }
}

```

### Handling Cursor Tool Calls

For Cursor-specific tool-use scenarios:

```typescript
import { getExecutor } from '@/open-sse/executors/index.ts';

const exec = getExecutor('cursor');  // Returns CursorExecutor
const input = {
  model: 'cursor-auto',
  body: {
    messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
    tools: [{
      type: 'function',
      function: { name: 'weather', description: 'Get weather data' }
    }],
  },
  stream: true,
  credentials: { accessToken: 'sk-cursor-...' },
};

const { response } = await exec.execute(input);
// Response streams SSE chunks including tool_calls deltas

```

## Key Source Files for Developer Reference

- **[`open-sse/executors/base.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/base.ts)**: Core strategy implementation, retry logic, and streaming abstractions (lines 27-43, 560-720).
- **[`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts)**: Universal adapter for standard providers with URL/header customization (lines 96-115).
- **[`open-sse/executors/cursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/cursor.ts)**: HTTP/2 Connect-RPC implementation with Protobuf frame processing (lines 1-90, 380-525 for `processFrame()`).
- **[`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts)**: Factory function mapping provider IDs to executor classes.
- **[`open-sse/services/apiKeyRotator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/apiKeyRotator.ts)**: Credential refresh logic consumed by `BaseExecutor`.
- **[`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts)**: Provider metadata and URL path configurations.
- **[`open-sse/utils/cursorAgentProtobuf.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/cursorAgentProtobuf.ts)**: Protobuf serialization helpers for Cursor protocol frames.

## Summary

- **BaseExecutor** implements the foundational Strategy pattern, handling HTTP mechanics, token refresh, retry loops, and SSE streaming for all providers.
- **DefaultExecutor** extends the base class to support hundreds of standard LLM APIs through URL customization, header injection, and request-body normalization.
- **CursorExecutor** replaces the standard HTTP flow entirely, implementing a bidirectional Connect-RPC protocol over HTTP/2 with specialized tool-call frame processing.
- **Thin wrapper executors** provide registry mappings for minor providers without requiring unique logic, while specialized variants like `OpenCodeExecutor` handle protocol-specific header forwarding.
- The executor factory in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) enables dynamic provider resolution, allowing OmniRoute to proxy any LLM API through a unified interface.

## Frequently Asked Questions

### What is the difference between BaseExecutor and DefaultExecutor in OmniRoute?

**`BaseExecutor`** is the abstract foundation that defines the executor contract and implements universal HTTP handling, while **`DefaultExecutor`** is a concrete implementation that extends `BaseExecutor` to add provider-specific URL paths, header customizations, and parameter filtering for standard REST APIs. `BaseExecutor` handles the *how* of HTTP communication; `DefaultExecutor` handles the *what* of provider-specific request shapes.

### How does CursorExecutor handle tool calls differently from other executors?

**`CursorExecutor`** uses a bidirectional HTTP/2 Connect-RPC protocol rather than simple POST requests, maintaining persistent connections for multi-turn tool interactions. The `processFrame()` method (lines 380-525) decodes Cursor's binary Protobuf frames containing MCP tool definitions and translates them into OpenAI-compatible `tool_calls` SSE events, whereas standard executors pass tool definitions through JSON request bodies and receive discrete HTTP responses.

### Can I create a custom executor for a proprietary LLM provider?

Yes, you can extend **`BaseExecutor`** in a new file like [`open-sse/executors/my-custom.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/my-custom.ts), override methods such as `buildUrl()` or `transformRequest()` to handle proprietary authentication or request formats, and register the class in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts). This approach allows integration of RPC-based or non-standard APIs without modifying the core OmniRoute handler logic.

### Where does OmniRoute handle API key rotation and token refresh?

Token refresh logic resides in [`open-sse/services/apiKeyRotator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/apiKeyRotator.ts), which supplies refreshed credentials to **`BaseExecutor`** instances. The `needsRefresh()` method in `BaseExecutor` evaluates credential expiration, while the `execute()` method (lines 560-720) triggers rotation automatically when authentication fails, ensuring zero-downtime key cycling for all executor types.