consult-llm-mcp 2.1.0 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP server that lets Claude Code consult stronger AI models (GPT-5.2, Gemini
 3.0 Pro, DeepSeek Reasoner) when Sonnet has you running in circles and you need
-to bring in the heavy artillery.
+to bring in the heavy artillery. Supports multi-turn conversations.
 
 ```
 > Still getting this error after your fix. Ask gemini
@@ -22,6 +22,9 @@ to bring in the heavy artillery.
   iter_captures() approach now.
 ```
 
+[Quick start](#quick-start) · [Configuration](#configuration) ·
+[Changelog](CHANGELOG.md)
+
 ## Features
 
 - Query powerful AI models (GPT-5.2, Gemini 3.0 Pro, DeepSeek Reasoner) with
@@ -29,9 +32,13 @@ to bring in the heavy artillery.
 - Direct queries with optional file context
 - Include git changes for code review and analysis
 - Comprehensive logging with cost estimation
-- [Gemini CLI mode](#gemini-cli): Use the `gemini` CLI to take advantage of
+- [Gemini CLI backend](#gemini-cli): Use the `gemini` CLI to take advantage of
   [free quota](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli)
-- [Codex CLI mode](#codex-cli): Use the `codex` CLI for OpenAI models
+- [Codex CLI backend](#codex-cli): Use the `codex` CLI for OpenAI models
+- [Cursor CLI backend](#cursor-cli): Use the `cursor-agent` CLI to route GPT and
+  Gemini models through a single tool
+- [Multi-turn conversations](#multi-turn-conversations): Resume CLI sessions
+  across requests with `thread_id`
 - [Web mode](#web-mode): Copy formatted prompts to clipboard for browser-based
   LLM services
 - Simple: provides just one MCP tool to not clutter the context
@@ -41,20 +48,23 @@ to bring in the heavy artillery.
 1. **Add to Claude Code**:
 
    ```bash
-   claude mcp add consult-llm -e GEMINI_API_KEY=your_key -- npx -y consult-llm-mcp
+   claude mcp add consult-llm \
+     -e OPENAI_API_KEY=your_key \
+     -e GEMINI_API_KEY=your_key \
+     -- npx -y consult-llm-mcp
    ```
 
    For global availability across projects, add `--scope user`.
 
    <details>
-   <summary>Using multiple API keys or CLI mode</summary>
+   <summary>Using multiple API keys or CLI backends</summary>
 
    ```bash
    claude mcp add consult-llm \
      -e OPENAI_API_KEY=your_openai_key \
      -e GEMINI_API_KEY=your_gemini_key \
      -e DEEPSEEK_API_KEY=your_deepseek_key \
-     -e GEMINI_MODE=cli \
+     -e GEMINI_BACKEND=gemini-cli \
      -- npx -y consult-llm-mcp
    ```
 
@@ -297,24 +307,26 @@ confidence in the approach.
 
 </details>
 
-## Modes
+## Backends
 
-consult-llm-mcp supports three modes of operation:
+Each model is routed to a **backend** — either an API endpoint or a CLI tool.
 
-| Mode    | Description                   | When to use                                                      |
-| ------- | ----------------------------- | ---------------------------------------------------------------- |
-| **API** | Queries LLM APIs directly     | You have API keys and want the simplest setup                    |
-| **CLI** | Shells out to local CLI tools | Free quota (Gemini), existing subscriptions, or prefer CLI tools |
-| **Web** | Copies prompt to clipboard    | You prefer browser UIs or want to review prompts                 |
+| Backend        | Description                      | When to use                                                      |
+| -------------- | -------------------------------- | ---------------------------------------------------------------- |
+| **API**        | Queries LLM APIs directly        | You have API keys and want the simplest setup                    |
+| **Gemini CLI** | Shells out to `gemini` CLI       | Free quota (Gemini), existing subscriptions, or prefer CLI tools |
+| **Codex CLI**  | Shells out to `codex` CLI        | OpenAI models via Codex subscription                             |
+| **Cursor CLI** | Shells out to `cursor-agent` CLI | Route GPT and Gemini through one tool                            |
+| **Web**        | Copies prompt to clipboard       | You prefer browser UIs or want to review prompts                 |
 
-### API mode (default)
+### API (default)
 
-The default mode. Requires API keys configured via environment variables. See
+The default backend. Requires API keys configured via environment variables. See
 [Configuration](#configuration) for details.
 
-### CLI mode
+### CLI backends
 
-Instead of making API calls, shell out to local CLI tools. The CLI agents can
+Instead of making API calls, shell out to local CLI tools. The CLI tools can
 explore the codebase themselves, so you don't need to pass all relevant files as
 context, but it helps.
 
@@ -331,7 +343,7 @@ Use Gemini's local CLI to take advantage of Google's
 **Setup:**
 
 ```bash
-claude mcp add consult-llm -e GEMINI_MODE=cli -- npx -y consult-llm-mcp
+claude mcp add consult-llm -e GEMINI_BACKEND=gemini-cli -- npx -y consult-llm-mcp
 ```
 
 #### Codex CLI
@@ -346,41 +358,76 @@ Use OpenAI's Codex CLI for OpenAI models.
 **Setup:**
 
 ```bash
-claude mcp add consult-llm -e OPENAI_MODE=cli -- npx -y consult-llm-mcp
+claude mcp add consult-llm -e OPENAI_BACKEND=codex-cli -- npx -y consult-llm-mcp
 ```
 
 <!-- prettier-ignore -->
 > [!TIP]
 > Set reasoning effort with `-e CODEX_REASONING_EFFORT=high`. Options:
-> `none`, `minimal`, `low`, `medium`, `high`, `xhigh` (gpt-5.1-codex-max only).
+> `none`, `minimal`, `low`, `medium`, `high`, `xhigh`.
+
+#### Cursor CLI
+
+Use Cursor's agent CLI to route GPT and Gemini models through one tool.
+
+**Requirements:**
+
+1. Install the [Cursor agent CLI](https://cursor.com/cli) (`cursor-agent` in
+   PATH)
+
+**Setup:**
+
+```bash
+# Route GPT models through Cursor CLI
+claude mcp add consult-llm -e OPENAI_BACKEND=cursor-cli -- npx -y consult-llm-mcp
+
+# Route Gemini models through Cursor CLI
+claude mcp add consult-llm -e GEMINI_BACKEND=cursor-cli -- npx -y consult-llm-mcp
+
+# Route everything through Cursor CLI
+claude mcp add consult-llm \
+  -e OPENAI_BACKEND=cursor-cli \
+  -e GEMINI_BACKEND=cursor-cli \
+  -- npx -y consult-llm-mcp
+```
 
 #### Multi-turn conversations
 
-CLI mode supports multi-turn conversations via the `thread_id` parameter. The
+CLI backends support multi-turn conversations via the `thread_id` parameter. The
 first response includes a `[thread_id:xxx]` prefix. Pass that ID in follow-up
 requests to continue the conversation with full context from prior turns.
 
-This works with both Gemini CLI and Codex CLI. Gemini uses session IDs, Codex
-uses thread IDs, but both are passed through the same `thread_id` parameter.
+This works with all CLI backends (Gemini CLI, Codex CLI, Cursor CLI). Each uses
+its own session/thread mechanism, but all are passed through the same
+`thread_id` parameter.
 
 ```
-⏺ consult-llm - consult_llm (MCP)(prompt: "What's your take on winter?",
+> Ask codex what's the best caching strategy for our read-heavy API
+
+⏺ consult-llm - consult_llm (MCP)(prompt: "What's the best caching strategy for a read-heavy API?",
                                    model: "gpt-5.3-codex")
   ⎿  [thread_id:thread_b1ff711...]
 
-     Winter is high-variance, not universally the worst. ...
+     Redis with TTL-based invalidation. Set short TTLs for volatile data ...
 
-⏺ consult-llm - consult_llm (MCP)(prompt: "What about rain?",
+⏺ Codex recommends Redis with TTL-based invalidation — but our payment
+  endpoints need strong consistency. Let me push back on that.
+
+⏺ consult-llm - consult_llm (MCP)(prompt: "What if we need strong consistency guarantees?
+                                            Does that change your recommendation?",
                                    model: "gpt-5.3-codex",
                                    thread_id: "thread_b1ff711...")
   ⎿  [thread_id:thread_b1ff711...]
 
-     Rain has high upside, high annoyance depending on context. ...
+     Yes — with strong consistency, the TTL approach breaks down. Consider
+     write-through caching or cache invalidation on writes instead ...
+
+⏺ Good — Codex revised its recommendation based on the consistency
+  constraint. I'll use write-through caching for the payment endpoints.
 ```
 
-See [skills/debate/SKILL.md](skills/debate/SKILL.md) for a skill where the agent
-debates an opponent LLM through multiple turns, then synthesizes and implements
-the result.
+See the [debate skills](#debate-skills) for multi-LLM workflows that use
+`thread_id` to maintain context across debate rounds.
 
 ### Web mode
 
@@ -409,19 +456,22 @@ See the "Using web mode..." example above for a concrete transcript.
 - `DEEPSEEK_API_KEY` - Your DeepSeek API key (required for DeepSeek models)
 - `CONSULT_LLM_DEFAULT_MODEL` - Override the default model (optional)
   - Options: `gpt-5.2` (default), `gemini-2.5-pro`, `gemini-3-pro-preview`,
-    `deepseek-reasoner`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-max`,
-    `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5.1`
-- `GEMINI_MODE` - Choose between API or CLI mode for Gemini models (optional)
-  - Options: `api` (default), `cli`
-  - CLI mode uses the system-installed `gemini` CLI tool
-- `OPENAI_MODE` - Choose between API or CLI mode for OpenAI models (optional)
-  - Options: `api` (default), `cli`
-  - CLI mode uses the system-installed `codex` CLI tool
+    `deepseek-reasoner`, `gpt-5.3-codex`, `gpt-5.2-codex`
+- `GEMINI_BACKEND` - Backend for Gemini models (optional)
+  - Options: `api` (default), `gemini-cli`, `cursor-cli`
+- `OPENAI_BACKEND` - Backend for OpenAI models (optional)
+  - Options: `api` (default), `codex-cli`, `cursor-cli`
 - `CODEX_REASONING_EFFORT` - Configure reasoning effort for Codex CLI (optional)
   - See [Codex CLI](#codex-cli) for details and available options
+- `CONSULT_LLM_EXTRA_MODELS` - Add models not in the built-in list (optional)
+  - Comma-separated list, e.g., `grok-3,kimi-k2.5`
+  - Merged with built-in models and included in the tool schema
+  - Useful for newly released models with a known provider prefix (`gpt-`,
+    `gemini-`, `deepseek-`)
 - `CONSULT_LLM_ALLOWED_MODELS` - List of models to advertise (optional)
   - Comma-separated list, e.g., `gpt-5.2,gemini-3-pro-preview`
   - When set, only these models appear in the tool schema
+  - Filters the combined catalog (built-in + extra models)
   - If `CONSULT_LLM_DEFAULT_MODEL` is set, it must be in this list
   - See [Tips](#controlling-which-models-claude-uses) for usage examples
 - `CONSULT_LLM_SYSTEM_PROMPT_PATH` - Custom path to system prompt file
@@ -442,7 +492,9 @@ This creates a placeholder file with the default system prompt that you can edit
 to customize how the consultant LLM behaves. The custom prompt is read on every
 request, so changes take effect immediately without restarting the server.
 
-To revert to the default prompt, simply delete the `SYSTEM_PROMPT.md` file.
+When a custom prompt file exists, it acts as a full override — `task_mode`
+overlays are not applied on top. To revert to the default prompt with
+`task_mode` support, simply delete the `SYSTEM_PROMPT.md` file.
 
 #### Custom prompt path
 
@@ -502,8 +554,18 @@ models complex questions.
 
 - **model** (optional): LLM model to use
   - Options: `gpt-5.2` (default), `gemini-2.5-pro`, `gemini-3-pro-preview`,
-    `deepseek-reasoner`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-max`,
-    `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5.1`
+    `deepseek-reasoner`, `gpt-5.3-codex`, `gpt-5.2-codex`
+
+- **task_mode** (optional): Controls the system prompt persona. The calling LLM
+  should choose based on the task:
+  - `general` (default): Neutral base prompt that defers to the user prompt
+  - `review`: Critical code reviewer — bugs, security, performance,
+    anti-patterns
+  - `debug`: Focused troubleshooter — root cause analysis, execution tracing,
+    ignores style issues
+  - `plan`: Constructive architect — trade-offs, alternatives, always includes a
+    final recommendation
+  - `create`: Generative writer — docs, content, polished output
 
 - **web_mode** (optional): Copy prompt to clipboard instead of querying LLM
   - Default: `false`
@@ -512,7 +574,7 @@ models complex questions.
     services
 
 - **thread_id** (optional): Resume a multi-turn conversation
-  - Works with Codex CLI (`gpt-*`) and Gemini CLI (`gemini-*`) in CLI mode
+  - Works with CLI backends (Codex CLI, Gemini CLI, Cursor CLI)
   - The first response includes a `[thread_id:xxx]` prefix — pass that ID back
     as `thread_id` in follow-up requests to maintain conversation context
 
@@ -532,10 +594,6 @@ models complex questions.
 - **gpt-5.2**: OpenAI's latest GPT model
 - **gpt-5.3-codex**: OpenAI's Codex model based on GPT-5.3
 - **gpt-5.2-codex**: OpenAI's Codex model based on GPT-5.2
-- **gpt-5.1-codex-max**: Strongest OpenAI Codex model
-- **gpt-5.1-codex**: OpenAI's Codex model optimized for coding
-- **gpt-5.1-codex-mini**: Lighter, faster version of gpt-5.1-codex
-- **gpt-5.1**: Broad world knowledge with strong general reasoning
 
 ## Logging
 
@@ -640,6 +698,34 @@ for the full content.
 Save it as `~/.claude/commands/consult.md` and you can then use it by typing
 `/consult ask gemini about X` or `/consult ask codex about X` in Claude Code.
 
+## Debate skills
+
+Two skills that orchestrate structured debates between LLMs to find the best
+implementation approach before writing code. Both use `thread_id` to maintain
+conversation context across rounds, so each LLM remembers the full debate
+history without resending everything.
+
+### debate
+
+**Claude moderates, two LLMs debate.** Gemini and Codex independently propose
+approaches, then critique each other's proposals. Claude synthesizes the best
+ideas and implements. See [skills/debate/SKILL.md](skills/debate/SKILL.md).
+
+```
+> /debate design the multi-tenant isolation strategy
+```
+
+### debate-vs
+
+**Claude participates as a debater** against one opponent LLM (Gemini or Codex)
+through multiple rounds. Claude forms its own position, then debates back and
+forth before synthesizing and implementing. See
+[skills/debate-vs/SKILL.md](skills/debate-vs/SKILL.md).
+
+```
+> /debate-vs --gemini design the multi-tenant isolation strategy
+```
+
 ## Development
 
 To work on the MCP server locally and use your development version:
@@ -647,7 +733,7 @@ To work on the MCP server locally and use your development version:
 1. Clone the repository and install dependencies:
 
    ```bash
-   git clone https://github.com/yourusername/consult-llm-mcp.git
+   git clone https://github.com/raine/consult-llm-mcp.git
    cd consult-llm-mcp
    npm install
    ```

package/dist/config.d.ts

@@ -1,9 +1,11 @@
 import { z } from 'zod/v4';
+/** Build the final model catalog from built-in + extra + allowlist filtering. */
+export declare function buildModelCatalog(builtinModels: readonly string[], extraModelsRaw?: string, allowedModelsRaw?: string): string[];
 export declare const SupportedChatModel: z.ZodEnum<{
     [x: string]: string;
 }>;
 export type SupportedChatModel = z.infer<typeof SupportedChatModel>;
-export declare const fallbackModel: "gemini-2.5-pro" | "gemini-3-pro-preview" | "deepseek-reasoner" | "gpt-5.2" | "gpt-5.3-codex" | "gpt-5.2-codex" | "gpt-5.1-codex-max" | "gpt-5.1-codex" | "gpt-5.1-codex-mini" | "gpt-5.1";
+export declare const fallbackModel: string;
 declare const Config: z.ZodObject<{
     openaiApiKey: z.ZodOptional<z.ZodString>;
     geminiApiKey: z.ZodOptional<z.ZodString>;
@@ -11,13 +13,15 @@ declare const Config: z.ZodObject<{
     defaultModel: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
-    geminiMode: z.ZodDefault<z.ZodEnum<{
+    geminiBackend: z.ZodDefault<z.ZodEnum<{
         api: "api";
-        cli: "cli";
+        "gemini-cli": "gemini-cli";
+        "cursor-cli": "cursor-cli";
     }>>;
-    openaiMode: z.ZodDefault<z.ZodEnum<{
+    openaiBackend: z.ZodDefault<z.ZodEnum<{
         api: "api";
-        cli: "cli";
+        "cursor-cli": "cursor-cli";
+        "codex-cli": "codex-cli";
     }>>;
     codexReasoningEffort: z.ZodOptional<z.ZodEnum<{
         none: "none";
@@ -33,5 +37,6 @@ type ParsedConfig = z.infer<typeof Config>;
 export type Config = ParsedConfig & {
     allowedModels: string[];
 };
+export declare function migrateBackendEnv(newVar: string | undefined, oldVar: string | undefined, providerCliValue: string, legacyName: string, newName: string): string | undefined;
 export declare const config: Config;
 export {};

package/dist/config.js

@@ -1,17 +1,33 @@
 import { z } from 'zod/v4';
 import { ALL_MODELS } from './models.js';
-// Parse allowed models from environment
-const rawAllowedModels = process.env.CONSULT_LLM_ALLOWED_MODELS
-    ? process.env.CONSULT_LLM_ALLOWED_MODELS.split(',')
-        .map((m) => m.trim())
-        .filter((m) => m.length > 0)
-    : [];
-const enabledModels = rawAllowedModels.length > 0
-    ? ALL_MODELS.filter((m) => rawAllowedModels.includes(m))
-    : [...ALL_MODELS];
+import { logToFile } from './logger.js';
+/** Build the final model catalog from built-in + extra + allowlist filtering. */
+export function buildModelCatalog(builtinModels, extraModelsRaw, allowedModelsRaw) {
+    const extraModels = extraModelsRaw
+        ? extraModelsRaw
+            .split(',')
+            .map((m) => m.trim())
+            .filter((m) => m.length > 0)
+        : [];
+    const allAvailable = [
+        ...builtinModels,
+        ...extraModels.filter((m) => !builtinModels.includes(m)),
+    ];
+    const allowedModels = allowedModelsRaw
+        ? allowedModelsRaw
+            .split(',')
+            .map((m) => m.trim())
+            .filter((m) => m.length > 0)
+        : [];
+    return allowedModels.length > 0
+        ? allAvailable.filter((m) => allowedModels.includes(m))
+        : allAvailable;
+}
+const enabledModels = buildModelCatalog(ALL_MODELS, process.env.CONSULT_LLM_EXTRA_MODELS, process.env.CONSULT_LLM_ALLOWED_MODELS);
 if (enabledModels.length === 0) {
-    console.error('❌ Invalid environment variables:');
-    console.error('  CONSULT_LLM_ALLOWED_MODELS: No valid models enabled.');
+    const msg = 'Invalid environment variables:\n  CONSULT_LLM_ALLOWED_MODELS: No valid models enabled.';
+    logToFile(`FATAL ERROR:\n${msg}`);
+    console.error(`❌ ${msg}`);
     process.exit(1);
 }
 // Dynamic Zod enum based on enabled models
@@ -24,28 +40,40 @@ const Config = z.object({
     geminiApiKey: z.string().optional(),
     deepseekApiKey: z.string().optional(),
     defaultModel: SupportedChatModel.optional(),
-    geminiMode: z.enum(['api', 'cli']).default('api'),
-    openaiMode: z.enum(['api', 'cli']).default('api'),
+    geminiBackend: z.enum(['api', 'gemini-cli', 'cursor-cli']).default('api'),
+    openaiBackend: z.enum(['api', 'codex-cli', 'cursor-cli']).default('api'),
     codexReasoningEffort: z
         .enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh'])
         .optional(),
     systemPromptPath: z.string().optional(),
 });
+// Migrate legacy GEMINI_MODE / OPENAI_MODE env vars
+export function migrateBackendEnv(newVar, oldVar, providerCliValue, legacyName, newName) {
+    if (newVar)
+        return newVar;
+    if (!oldVar)
+        return undefined;
+    const mapped = oldVar === 'cli' ? providerCliValue : oldVar;
+    logToFile(`DEPRECATED: ${legacyName}=${oldVar} → use ${newName}=${mapped} instead`);
+    return mapped;
+}
 const parsedConfig = Config.safeParse({
     openaiApiKey: process.env.OPENAI_API_KEY,
     geminiApiKey: process.env.GEMINI_API_KEY,
     deepseekApiKey: process.env.DEEPSEEK_API_KEY,
     defaultModel: process.env.CONSULT_LLM_DEFAULT_MODEL,
-    geminiMode: process.env.GEMINI_MODE,
-    openaiMode: process.env.OPENAI_MODE,
+    geminiBackend: migrateBackendEnv(process.env.GEMINI_BACKEND, process.env.GEMINI_MODE, 'gemini-cli', 'GEMINI_MODE', 'GEMINI_BACKEND'),
+    openaiBackend: migrateBackendEnv(process.env.OPENAI_BACKEND, process.env.OPENAI_MODE, 'codex-cli', 'OPENAI_MODE', 'OPENAI_BACKEND'),
     codexReasoningEffort: process.env.CODEX_REASONING_EFFORT,
     systemPromptPath: process.env.CONSULT_LLM_SYSTEM_PROMPT_PATH,
 });
 if (!parsedConfig.success) {
-    console.error('❌ Invalid environment variables:');
-    for (const issue of parsedConfig.error.issues) {
-        console.error(`  ${issue.path.join('.')}: ${issue.message}`);
-    }
+    const details = parsedConfig.error.issues
+        .map((issue) => `  ${issue.path.join('.')}: ${issue.message}`)
+        .join('\n');
+    const msg = `Invalid environment variables:\n${details}`;
+    logToFile(`FATAL ERROR:\n${msg}`);
+    console.error(`❌ ${msg}`);
     process.exit(1);
 }
 export const config = {

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi } from 'vitest';
+import { migrateBackendEnv, buildModelCatalog } from './config.js';
+import { ALL_MODELS } from './models.js';
+vi.mock('./logger.js', () => ({ logToFile: vi.fn() }));
+describe('migrateBackendEnv', () => {
+    it('returns newVar when set, ignoring oldVar', () => {
+        expect(migrateBackendEnv('cursor-cli', 'cli', 'gemini-cli', 'GEMINI_MODE', 'GEMINI_BACKEND')).toBe('cursor-cli');
+    });
+    it('maps "cli" to provider-specific cli value', () => {
+        expect(migrateBackendEnv(undefined, 'cli', 'gemini-cli', 'GEMINI_MODE', 'GEMINI_BACKEND')).toBe('gemini-cli');
+    });
+    it('passes through non-cli values directly', () => {
+        expect(migrateBackendEnv(undefined, 'api', 'gemini-cli', 'GEMINI_MODE', 'GEMINI_BACKEND')).toBe('api');
+    });
+    it('returns undefined when both vars are missing', () => {
+        expect(migrateBackendEnv(undefined, undefined, 'gemini-cli', 'GEMINI_MODE', 'GEMINI_BACKEND')).toBeUndefined();
+    });
+    it('maps openai cli to codex-cli', () => {
+        expect(migrateBackendEnv(undefined, 'cli', 'codex-cli', 'OPENAI_MODE', 'OPENAI_BACKEND')).toBe('codex-cli');
+    });
+});
+describe('buildModelCatalog', () => {
+    it('returns all built-in models when no env vars are set', () => {
+        const result = buildModelCatalog(ALL_MODELS);
+        expect(result).toEqual([...ALL_MODELS]);
+    });
+    it('appends extra models to the catalog', () => {
+        const result = buildModelCatalog(ALL_MODELS, 'grok-3,kimi-k2.5');
+        expect(result).toContain('grok-3');
+        expect(result).toContain('kimi-k2.5');
+        expect(result.length).toBe(ALL_MODELS.length + 2);
+    });
+    it('deduplicates extra models that overlap with built-ins', () => {
+        const result = buildModelCatalog(ALL_MODELS, 'gpt-5.2,grok-3');
+        expect(result.filter((m) => m === 'gpt-5.2').length).toBe(1);
+        expect(result.length).toBe(ALL_MODELS.length + 1);
+    });
+    it('filters by allowlist from combined catalog', () => {
+        const result = buildModelCatalog(ALL_MODELS, 'grok-3', 'gpt-5.2,grok-3');
+        expect(result).toEqual(['gpt-5.2', 'grok-3']);
+    });
+    it('allowlist can include only extra models', () => {
+        const result = buildModelCatalog(ALL_MODELS, 'grok-3', 'grok-3');
+        expect(result).toEqual(['grok-3']);
+    });
+    it('allowlist filters out models not in catalog', () => {
+        const result = buildModelCatalog(ALL_MODELS, undefined, 'nonexistent');
+        expect(result).toEqual([]);
+    });
+    it('handles whitespace and empty entries in extra models', () => {
+        const result = buildModelCatalog(ALL_MODELS, ' grok-3 , , kimi-k2.5 ');
+        expect(result).toContain('grok-3');
+        expect(result).toContain('kimi-k2.5');
+        expect(result.length).toBe(ALL_MODELS.length + 2);
+    });
+    it('handles whitespace in allowlist', () => {
+        const result = buildModelCatalog(ALL_MODELS, undefined, ' gpt-5.2 , gemini-2.5-pro ');
+        expect(result).toContain('gpt-5.2');
+        expect(result).toContain('gemini-2.5-pro');
+        expect(result.length).toBe(2);
+    });
+    it('preserves built-in model order with extras appended', () => {
+        const result = buildModelCatalog(ALL_MODELS, 'aaa-model,zzz-model');
+        const builtinPart = result.slice(0, ALL_MODELS.length);
+        expect(builtinPart).toEqual([...ALL_MODELS]);
+        expect(result.slice(ALL_MODELS.length)).toEqual(['aaa-model', 'zzz-model']);
+    });
+});

package/dist/executors/api.d.ts

@@ -0,0 +1,3 @@
+import type OpenAI from 'openai';
+import type { LlmExecutor } from './types.js';
+export declare function createApiExecutor(client: OpenAI): LlmExecutor;

package/dist/executors/api.js

@@ -0,0 +1,29 @@
+import { logToFile } from '../logger.js';
+export function createApiExecutor(client) {
+    return {
+        capabilities: {
+            isCli: false,
+            supportsThreads: false,
+            supportsFileRefs: false,
+        },
+        async execute(prompt, model, systemPrompt, filePaths) {
+            if (filePaths && filePaths.length > 0) {
+                const msg = `File paths were provided but are not supported by the API executor for model ${model}. They will be ignored.`;
+                logToFile(`WARNING: ${msg}`);
+                console.warn(`Warning: ${msg}`);
+            }
+            const completion = await client.chat.completions.create({
+                model,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: prompt },
+                ],
+            });
+            const response = completion.choices[0]?.message?.content;
+            if (!response) {
+                throw new Error('No response from the model via API');
+            }
+            return { response, usage: completion.usage ?? null };
+        },
+    };
+}

package/dist/executors/codex-cli.d.ts

@@ -0,0 +1,6 @@
+import type { LlmExecutor } from './types.js';
+export declare function parseCodexJsonl(output: string): {
+    threadId: string | undefined;
+    response: string;
+};
+export declare function createCodexExecutor(): LlmExecutor;