feat(providers): add Command Code hybrid gateway

.env.example

@@ -223,6 +223,16 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # OPENAI_BASE_URL=https://llmtr.com/v1
 # OPENAI_MODEL=deepseek/deepseek-v4-flash
 
+# For Command Code, use its dedicated key. Claude models on this provider
+# require the Anthropic /messages API and are not routed here. Select the
+# route with /provider or --provider commandcode (or CLAUDE_CODE_USE_OPENAI=1);
+# CMD_API_KEY alone does not autodetect Command Code:
+# CMD_API_KEY=your-commandcode-key-here
+# COMMANDCODE_API_KEY=your-commandcode-key-here  # supported fallback
+# COMMAND_CODE_API_KEY=your-commandcode-key-here  # official Command Code client variable
+# OPENAI_BASE_URL=https://api.commandcode.ai/provider/v1
+# OPENAI_MODEL=deepseek/deepseek-v4-flash
+
 # Use a custom OpenAI-compatible endpoint (optional — defaults to api.openai.com)
 # OPENAI_BASE_URL=https://api.openai.com/v1
 # Choose the OpenAI-compatible API surface (optional).

README.md

@@ -310,6 +310,7 @@ Advanced and source-build guides:
 | AI/ML API | `/provider` or `AIMLAPI_API_KEY` ([setup guide](docs/aimlapi-setup.md)) | Uses `https://api.aimlapi.com/v1`, auto-detects the OpenAI-compatible route from `AIMLAPI_API_KEY`, sends OpenClaude attribution headers, and discovers chat-capable models from the public `/models` catalog |
 | Concentrate | `/provider` or `CONCENTRATE_API_KEY` | Unified OpenAI-compatible gateway at `https://api.concentrate.ai/v1`; defaults to `deepseek-v4-flash` and auto-discovers the chat model catalog |
 | LLMTR | `/provider` or OpenAI-compatible env vars | Multi-model gateway at `https://llmtr.com/v1`; `/provider` and `--provider llmtr` default to `deepseek/deepseek-v4-flash`, while raw env setup must set `OPENAI_BASE_URL=https://llmtr.com/v1` and `OPENAI_MODEL`; accepts `LLMTR_API_KEY` or `OPENAI_API_KEY` after the route is selected and discovers tool-capable Chat Completions models from the public catalog |
+| Command Code | `/provider` or OpenAI-compatible env vars | Hybrid OpenAI-compatible gateway at `https://api.commandcode.ai/provider/v1`; `/provider` and `--provider commandcode` default to `deepseek/deepseek-v4-flash`, while raw env setup must set `OPENAI_BASE_URL=https://api.commandcode.ai/provider/v1` and `OPENAI_MODEL`; requires `CMD_API_KEY`, `COMMANDCODE_API_KEY`, or the official `COMMAND_CODE_API_KEY` after the route is selected and discovers Chat Completions models from the public catalog. Claude models are unsupported by this Chat Completions integration |
 | ApiSmart | `/provider` or `APISMART_API_KEY` | Uses `https://gw.apismart.ai/v1`, defaults to `DEEPSEEK_V4_FLASH`, and supports optional `APISMART_MODEL` plus authenticated model discovery |
 | Hicap | `/provider` or OpenAI-compatible env vars | Uses `api-key` auth, discovers models from unauthenticated `/models`, and supports Responses mode for `gpt-` models |
 | Fireworks AI | `/provider` or env vars | First-class provider with 276 curated models (DeepSeek, Qwen, Llama, Gemma, and more); uses `FIREWORKS_API_KEY` |

scripts/provider-launch.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from 'bun:test'
-import { hasUsableOpenAILaunchCredential } from './provider-launch.ts'
+import {
+  getOpenAILaunchCredentialError,
+  hasUsableOpenAILaunchCredential,
+} from './provider-launch.ts'
 
 describe('provider-launch OpenAI credential validation', () => {
   test('accepts valid OPENAI_API_KEYS before placeholder OPENAI_API_KEY fallback', () => {
@@ -19,4 +22,73 @@ describe('provider-launch OpenAI credential validation', () => {
       } as NodeJS.ProcessEnv),
     ).toBe(false)
   })
+
+  test('accepts a dedicated Command Code credential on its selected route', () => {
+    expect(
+      hasUsableOpenAILaunchCredential({
+        CLAUDE_CODE_USE_OPENAI: '1',
+        OPENAI_BASE_URL: 'https://api.commandcode.ai/provider/v1',
+        CMD_API_KEY: 'cmd-key',
+      } as NodeJS.ProcessEnv),
+    ).toBe(true)
+  })
+
+  test('accepts the Command Code fallback credential on its selected route', () => {
+    expect(
+      hasUsableOpenAILaunchCredential({
+        CLAUDE_CODE_USE_OPENAI: '1',
+        OPENAI_BASE_URL: 'https://api.commandcode.ai/provider/v1',
+        COMMANDCODE_API_KEY: 'fallback-key',
+      } as NodeJS.ProcessEnv),
+    ).toBe(true)
+  })
+
+  test('rejects a generic credential for the dedicated-only Command Code route', () => {
+    expect(
+      hasUsableOpenAILaunchCredential({
+        CLAUDE_CODE_USE_OPENAI: '1',
+        OPENAI_BASE_URL: 'https://api.commandcode.ai/provider/v1',
+        OPENAI_API_KEY: 'generic-key',
+      } as NodeJS.ProcessEnv),
+    ).toBe(false)
+  })
+
+  test.each([
+    'CMD_API_KEY',
+    'COMMANDCODE_API_KEY',
+    'COMMAND_CODE_API_KEY',
+  ] as const)(
+    'rejects a placeholder %s on the selected Command Code route',
+    credentialEnvVar => {
+      expect(
+        hasUsableOpenAILaunchCredential({
+          CLAUDE_CODE_USE_OPENAI: '1',
+          OPENAI_BASE_URL: 'https://api.commandcode.ai/provider/v1',
+          [credentialEnvVar]: 'SUA_CHAVE',
+        } as NodeJS.ProcessEnv),
+      ).toBe(false)
+    },
+  )
+
+  test('reports Command Code credential guidance for its selected route', () => {
+    expect(
+      getOpenAILaunchCredentialError({
+        CLAUDE_CODE_USE_OPENAI: '1',
+        OPENAI_BASE_URL: 'https://api.commandcode.ai/provider/v1',
+      } as NodeJS.ProcessEnv),
+    ).toBe(
+      'CMD_API_KEY is required for the Command Code route (fallbacks: COMMANDCODE_API_KEY or COMMAND_CODE_API_KEY) and cannot include placeholder values such as SUA_CHAVE. Set one of those environment variables, rerun the launcher, then use /provider to save the Command Code profile.',
+    )
+  })
+
+  test('preserves generic OpenAI credential guidance outside Command Code', () => {
+    expect(
+      getOpenAILaunchCredentialError({
+        CLAUDE_CODE_USE_OPENAI: '1',
+        OPENAI_BASE_URL: 'https://api.openai.com/v1',
+      } as NodeJS.ProcessEnv),
+    ).toBe(
+      'OPENAI_API_KEYS or OPENAI_API_KEY is required for openai profile and cannot include SUA_CHAVE. Run: bun run profile:init -- --provider openai --api-key <key>',
+    )
+  })
 })

scripts/provider-launch.ts

@@ -15,6 +15,10 @@ import {
   type ProfileFile,
   type ProviderProfile,
 } from '../src/utils/providerProfile.ts'
+import {
+  getRouteCredentialValue,
+  resolveActiveRouteIdFromEnv,
+} from '../src/integrations/routeMetadata.ts'
 import {
   getAtomicChatChatBaseUrl,
   getOllamaChatBaseUrl,
@@ -156,7 +160,22 @@ function hasUsableGeminiLaunchAuth(env: NodeJS.ProcessEnv): boolean {
 export function hasUsableOpenAILaunchCredential(
   env: NodeJS.ProcessEnv,
 ): boolean {
-  return resolveOpenAICredentialEnvState(env).configured
+  return getOpenAILaunchCredentialError(env) === null
+}
+
+export function getOpenAILaunchCredentialError(
+  env: NodeJS.ProcessEnv,
+): string | null {
+  if (resolveActiveRouteIdFromEnv(env) === 'commandcode') {
+    if (getRouteCredentialValue('commandcode', env)) {
+      return null
+    }
+    return 'CMD_API_KEY is required for the Command Code route (fallbacks: COMMANDCODE_API_KEY or COMMAND_CODE_API_KEY) and cannot include placeholder values such as SUA_CHAVE. Set one of those environment variables, rerun the launcher, then use /provider to save the Command Code profile.'
+  }
+  if (resolveOpenAICredentialEnvState(env).configured) {
+    return null
+  }
+  return 'OPENAI_API_KEYS or OPENAI_API_KEY is required for openai profile and cannot include SUA_CHAVE. Run: bun run profile:init -- --provider openai --api-key <key>'
 }
 
 async function main(): Promise<void> {
@@ -234,10 +253,10 @@ async function main(): Promise<void> {
     process.exit(1)
   }
 
-  if (profile === 'openai' && !hasUsableOpenAILaunchCredential(env)) {
-    console.error(
-      'OPENAI_API_KEYS or OPENAI_API_KEY is required for openai profile and cannot include SUA_CHAVE. Run: bun run profile:init -- --provider openai --api-key <key>',
-    )
+  const openAICredentialError =
+    profile === 'openai' ? getOpenAILaunchCredentialError(env) : null
+  if (openAICredentialError) {
+    console.error(openAICredentialError)
     process.exit(1)
   }
 

src/cli/bg.test.ts

@@ -16,6 +16,8 @@ import {
   LOG_STREAM_CHUNK_SIZE,
   parseBackgroundInvocation,
   parseLogsInvocation,
+  resolveBackgroundSessionModel,
+  resolveBackgroundSessionProvider,
 } from './bg.js'
 import {
   BACKGROUND_SESSION_ID_ENV,
@@ -107,6 +109,83 @@ async function withTempFile<T>(
 }
 
 describe('background session CLI parsing', () => {
+  it('records the final root provider selected by CLI startup', async () => {
+    const parsed = parseBackgroundInvocation([
+      '--provider',
+      'anthropic',
+      '--provider=commandcode',
+      '--bg',
+      'do the work',
+    ])
+    const launch = await buildBackgroundSessionLaunch(
+      parsed.childArgs,
+      '00000000-0000-4000-8000-000000000001',
+    )
+
+    expect(resolveBackgroundSessionProvider(launch.childArgs)).toBe(
+      'commandcode',
+    )
+  })
+
+  it('does not record provider-looking text consumed by a root option', async () => {
+    const parsed = parseBackgroundInvocation([
+      '--system-prompt',
+      '--provider=commandcode',
+      '--bg',
+      'do the work',
+    ])
+    const launch = await buildBackgroundSessionLaunch(
+      parsed.childArgs,
+      '00000000-0000-4000-8000-000000000001',
+    )
+
+    expect(resolveBackgroundSessionProvider(launch.childArgs)).toBeUndefined()
+  })
+
+  it('records the root session model when a nested command also has --model', async () => {
+    const generatedSessionId = '00000000-0000-4000-8000-000000000001'
+
+    for (const nested of [
+      ['aimlapi', 'topup'],
+      ['auto-mode', 'critique'],
+    ] as const) {
+      const parsed = parseBackgroundInvocation([
+        '--model',
+        'deepseek/deepseek-v4-flash',
+        ...nested,
+        '--model',
+        'anthropic/claude-sonnet-4-6',
+        '--bg',
+        'do the work',
+      ])
+      const launch = await buildBackgroundSessionLaunch(
+        parsed.childArgs,
+        generatedSessionId,
+      )
+
+      expect(resolveBackgroundSessionModel(launch.childArgs)).toBe(
+        'deepseek/deepseek-v4-flash',
+      )
+    }
+  })
+
+  it('does not record a nested --model as the background session model', async () => {
+    const parsed = parseBackgroundInvocation([
+      'aimlapi',
+      'topup',
+      '--model',
+      'anthropic/claude-sonnet-4-6',
+      '--bg',
+      'do the work',
+    ])
+    const launch = await buildBackgroundSessionLaunch(
+      parsed.childArgs,
+      '00000000-0000-4000-8000-000000000001',
+    )
+
+    expect(resolveBackgroundSessionModel(launch.childArgs)).toBeUndefined()
+  })
+
   it('generates a fresh bounded lower-case hex marker from 32 random bytes', () => {
     const first = generateBackgroundProcessMarker(size => {
       expect(size).toBe(32)

src/cli/bg.ts

@@ -4,8 +4,15 @@ import { closeSync, openSync } from 'node:fs'
 import { open, unlink } from 'node:fs/promises'
 import { basename } from 'node:path'
 import treeKill from 'tree-kill'
-import { argsBeforeDelimiter } from '../utils/cliArgs.js'
-import { hasPrintFlag } from '../utils/printFlag.js'
+import {
+  argsBeforeDelimiter,
+  parseModelFlagValue,
+} from '../utils/cliArgs.js'
+import {
+  argsBeforeModelOwningSubcommand,
+  hasPrintFlag,
+  parseRootOptionValue,
+} from '../utils/printFlag.js'
 import { isProcessRunning } from '../utils/genericProcessUtils.js'
 import {
   assertBackgroundSessionNameAvailable,
@@ -341,6 +348,24 @@ function findSessionName(args: string[]): string | undefined {
   return findFlagValue(args, '--name') ?? findFlagValue(args, '-n')
 }
 
+/**
+ * Background session metadata must record the same root `--model` that CLI
+ * startup applies. Nested `aimlapi topup` / `auto-mode critique` flags are not
+ * the session model.
+ */
+export function resolveBackgroundSessionModel(
+  childArgs: readonly string[],
+): string | undefined {
+  return parseModelFlagValue(argsBeforeModelOwningSubcommand(childArgs))
+}
+
+/** Keep registry metadata aligned with the provider selected by CLI startup. */
+export function resolveBackgroundSessionProvider(
+  childArgs: readonly string[],
+): string | undefined {
+  return parseRootOptionValue(childArgs, '--provider')
+}
+
 function hasPrintMode(args: string[]): boolean {
   return hasPrintFlag(args)
 }
@@ -1145,8 +1170,8 @@ export async function handleBgFlag(args: string[]): Promise<void> {
     pid: child.pid,
     cwd: process.cwd(),
     command,
-    provider: findFlagValue(childArgs, '--provider'),
-    model: findFlagValue(childArgs, '--model'),
+    provider: resolveBackgroundSessionProvider(childArgs),
+    model: resolveBackgroundSessionModel(childArgs),
     sessionId,
     processMarker,
     stdoutLogPath: logPaths.stdoutLogPath,