patina-cli 3.11.0 → 4.0.0

package/src/auth.js

@@ -1,26 +1,63 @@
 import { readFileSync } from 'node:fs';
 import { inputError } from './errors.js';
 
+/**
+ * Environment variable names checked for HTTP provider authentication.
+ *
+ * @type {string[]}
+ * @example
+ * const supported = HTTP_KEY_ENV_VARS.includes('OPENAI_API_KEY');
+ */
 export const HTTP_KEY_ENV_VARS = [
   'PATINA_API_KEY',
   'OPENAI_API_KEY',
   'GEMINI_API_KEY',
   'GROQ_API_KEY',
   'TOGETHER_API_KEY',
+  'KIMI_API_KEY',
+  'MOONSHOT_API_KEY',
 ];
 
 // Default openai-http runs against the OpenAI-compatible default endpoint, so
 // only generic/OpenAI keys make it authenticated without an explicit provider.
+/**
+ * Default key lookup order for the OpenAI-compatible HTTP provider.
+ *
+ * @type {string[]}
+ * @example
+ * const first = DEFAULT_HTTP_KEY_ENV_VARS[0]; // PATINA_API_KEY
+ */
 export const DEFAULT_HTTP_KEY_ENV_VARS = [
   'PATINA_API_KEY',
   'OPENAI_API_KEY',
 ];
 
+/**
+ * Build the key lookup order for a selected provider.
+ *
+ * @param {string} [providerApiKeyEnv] Provider-specific key env var, such as GEMINI_API_KEY.
+ * @returns {string[]} Unique env var names in lookup order.
+ * @throws {Error} Does not intentionally throw; invalid non-string env names can still propagate JavaScript runtime failures.
+ * @example
+ * const vars = providerHttpKeyEnvVars('GEMINI_API_KEY');
+ */
 export function providerHttpKeyEnvVars(providerApiKeyEnv) {
   if (!providerApiKeyEnv) return DEFAULT_HTTP_KEY_ENV_VARS;
   return uniqueEnvVars([providerApiKeyEnv, 'PATINA_API_KEY']);
 }
 
+/**
+ * Inspect where an HTTP API key would be read from without exposing the secret.
+ *
+ * @param {object} [options] Inspection options.
+ * @param {object} [options.env=process.env] Environment map to inspect.
+ * @param {Function} [options.readFile] File reader for PATINA_API_KEY_FILE.
+ * @param {string[]} [options.envVars=DEFAULT_HTTP_KEY_ENV_VARS] Env vars to check.
+ * @returns {{ok: boolean, source: string|null, envVars: string[], filePath: string|null, detail: string}} Source diagnostics.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const source = inspectHttpApiKeySource({ env: { PATINA_API_KEY: 'sk-...' } });
+ */
 export function inspectHttpApiKeySource({
   env = process.env,
   readFile = readFileSync,
@@ -48,8 +85,20 @@ export function inspectHttpApiKeySource({
   };
 }
 
+/**
+ * Resolve the HTTP API key from a key file or environment.
+ *
+ * @param {object} [options] Resolution options.
+ * @param {string} [options.apiKeyFile] Explicit key file path.
+ * @param {object} [options.env=process.env] Environment map.
+ * @param {Function} [options.readFile] File reader for key files.
+ * @param {string[]} [options.envVars=DEFAULT_HTTP_KEY_ENV_VARS] Env var lookup order.
+ * @returns {string|undefined} Resolved key value, or undefined when unauthenticated.
+ * @throws {PatinaCliError} When the configured key file cannot be read or is empty.
+ * @example
+ * const key = resolveHttpApiKey({ env: process.env });
+ */
 export function resolveHttpApiKey({
-  explicitApiKey,
   apiKeyFile,
   env = process.env,
   readFile = readFileSync,
@@ -68,7 +117,6 @@ export function resolveHttpApiKey({
     return file.key;
   }
 
-  if (explicitApiKey) return explicitApiKey;
 
   const source = inspectHttpApiKeySource({ env, readFile, envVars });
   return source.ok && source.source !== 'PATINA_API_KEY_FILE'

package/src/backends/claude-cli.js

@@ -2,9 +2,12 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+import { DEFAULT_BACKEND_TIMEOUT_MS, runInteractiveCommand } from './contract.js';
+import { resolveLocalCliModel } from '../model-defaults.js';
 
 export const name = 'claude-cli';
+export const loginCommand = 'claude auth login';
+export const installHint = 'Install Claude Code first, then run `patina auth login claude-cli` again.';
 
 export function isAvailable() {
   try {
@@ -23,22 +26,34 @@ export function isAuthenticated() {
 }
 
 export function authHint() {
-  return 'Run `claude` once interactively and follow the OAuth prompt to authenticate (uses your Claude subscription, no API key needed).';
+  return `Run \`${loginCommand}\` and follow the OAuth prompt to authenticate (uses your Claude subscription, no API key needed).`;
 }
 
-export async function invoke({ prompt, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+export function login(options = {}) {
+  return runInteractiveCommand({
+    backendName: name,
+    command: 'claude',
+    args: ['auth', 'login'],
+    notFoundHint: installHint,
+    ...options,
+  });
+}
+
+export async function invoke({ prompt, model, modelSource, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('claude-cli backend: prompt must be a non-empty string');
   }
   throwIfAborted(signal);
 
+  const cliModel = resolveLocalCliModel({ backendName: name, model, modelSource });
+
   // Spawn from a fresh temp directory so a prompt-injection in user text
   // cannot read or write inside the caller's repo. claude -p prints to
   // stdout, so no output file plumbing is needed (unlike codex-cli).
   const dir = mkdtempSync(join(tmpdir(), 'patina-claude-'));
 
   return new Promise((resolve, reject) => {
-    const proc = spawn('claude', ['-p'], { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
+    const proc = spawn('claude', ['-p', '--model', cliModel], { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
 
     let stdout = '';
     let stderr = '';

package/src/backends/codex-cli.js

@@ -2,9 +2,12 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+import { DEFAULT_BACKEND_TIMEOUT_MS, runInteractiveCommand } from './contract.js';
+import { resolveLocalCliModel } from '../model-defaults.js';
 
 export const name = 'codex-cli';
+export const loginCommand = 'codex login';
+export const installHint = 'Install it from https://github.com/openai/codex, then run `patina auth login codex-cli` again.';
 
 export function isAvailable() {
   try {
@@ -20,15 +23,27 @@ export function isAuthenticated() {
 }
 
 export function authHint() {
-  return 'Run `codex login` to authenticate (uses your ChatGPT Plus account, no API key needed).';
+  return `Run \`${loginCommand}\` to authenticate (uses your ChatGPT Plus account, no API key needed).`;
 }
 
-export async function invoke({ prompt, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+export function login(options = {}) {
+  return runInteractiveCommand({
+    backendName: name,
+    command: 'codex',
+    args: ['login'],
+    notFoundHint: installHint,
+    ...options,
+  });
+}
+
+export async function invoke({ prompt, model, modelSource, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('codex-cli backend: prompt must be a non-empty string');
   }
   throwIfAborted(signal);
 
+  const cliModel = resolveLocalCliModel({ backendName: name, model, modelSource });
+
   // Run codex from a fresh temp directory with the read-only sandbox so that
   // a prompt-injection in user text cannot read the caller's repo or write
   // arbitrary files. The output file lives inside the same temp dir so codex
@@ -42,6 +57,7 @@ export async function invoke({ prompt, signal, timeout = DEFAULT_BACKEND_TIMEOUT
       '--skip-git-repo-check',
       '--sandbox', 'read-only',
       '-C', dir,
+      '--model', cliModel,
       '--output-last-message', outFile,
     ], { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
 

package/src/backends/contract.js

@@ -1,4 +1,69 @@
-export const DEFAULT_BACKEND_TIMEOUT_MS = 180_000;
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEFAULT_BACKEND_TIMEOUT_MS = 600_000;
+export const DEFAULT_HTTP_MAX_RETRIES = 2;
+export const PROMPT_SIZE_WARNING_CHARS = 20_000;
+
+export const BACKEND_SAFETY_DEFAULTS = Object.freeze({
+  'openai-http': {
+    maxConcurrency: 4,
+    maxRetries: DEFAULT_HTTP_MAX_RETRIES,
+    promptMode: 'strict',
+    agentRuntime: false,
+  },
+  'codex-cli': {
+    maxConcurrency: 2,
+    maxRetries: 0,
+    promptMode: 'minimal',
+    agentRuntime: true,
+  },
+  'claude-cli': {
+    maxConcurrency: 1,
+    maxRetries: 0,
+    promptMode: 'minimal',
+    agentRuntime: true,
+  },
+  'gemini-cli': {
+    maxConcurrency: 2,
+    maxRetries: 0,
+    promptMode: 'minimal',
+    agentRuntime: true,
+  },
+  'kimi-cli': {
+    maxConcurrency: 1,
+    maxRetries: 0,
+    promptMode: 'minimal',
+    agentRuntime: true,
+  },
+});
+
+const UNKNOWN_BACKEND_SAFETY = Object.freeze({
+  maxConcurrency: Infinity,
+  maxRetries: 0,
+  promptMode: 'strict',
+  agentRuntime: false,
+});
+
+export function getBackendSafety(backendName) {
+  return BACKEND_SAFETY_DEFAULTS[backendName] || UNKNOWN_BACKEND_SAFETY;
+}
+
+export function resolveBackendMaxConcurrency(backendName, override) {
+  const n = override === undefined || override === null
+    ? getBackendSafety(backendName).maxConcurrency
+    : Number(override);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : Infinity;
+}
+
+export function resolveBackendMaxRetries(backendName, override) {
+  const n = override === undefined || override === null
+    ? getBackendSafety(backendName).maxRetries
+    : Number(override);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+}
 
 export function isRetryableBackendError(err, { attemptIndex = 0, signal } = {}) {
   if (signal?.aborted) return false;
@@ -10,6 +75,8 @@ export function isRetryableBackendError(err, { attemptIndex = 0, signal } = {})
 export function describeBackendError(err) {
   const status = extractStatus(err);
   if (status) return `HTTP ${status}`;
+  const exitCode = extractExitCode(err);
+  if (exitCode) return `exit code ${exitCode}`;
   return err?.name || 'error';
 }
 
@@ -19,3 +86,165 @@ function extractStatus(err) {
   const match = String(err?.message || '').match(/\bHTTP\s+(429|503)\b/);
   return match ? Number(match[1]) : null;
 }
+
+function extractExitCode(err) {
+  const direct = Number(err?.code);
+  if (Number.isFinite(direct)) return direct;
+  const match = String(err?.message || '').match(/\bexited with code\s+(\d+)\b/i);
+  return match ? Number(match[1]) : null;
+}
+
+export async function withBackendConcurrencySlot({
+  backendName,
+  maxConcurrency,
+  signal,
+  timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+  pollMs = 250,
+  staleMs = Math.max(timeout * 2, 30 * 60_000),
+  fn,
+} = {}) {
+  if (typeof fn !== 'function') {
+    throw new Error('backend concurrency slot requires fn');
+  }
+  if (!Number.isFinite(maxConcurrency)) {
+    return fn();
+  }
+
+  const slot = await acquireBackendSlot({
+    backendName,
+    maxConcurrency,
+    signal,
+    timeout,
+    pollMs,
+    staleMs,
+  });
+
+  try {
+    return await fn();
+  } finally {
+    releaseBackendSlot(slot);
+  }
+}
+
+async function acquireBackendSlot({
+  backendName,
+  maxConcurrency,
+  signal,
+  timeout,
+  pollMs,
+  staleMs,
+}) {
+  throwIfAborted(signal, `${backendName || 'backend'}: aborted while waiting for concurrency slot`);
+  const startedAt = Date.now();
+  const root = join(tmpdir(), 'patina-backend-slots', safePathSegment(backendName || 'backend'));
+  mkdirSync(root, { recursive: true });
+
+  for (;;) {
+    for (let index = 0; index < maxConcurrency; index++) {
+      const slot = join(root, `slot-${index}`);
+      cleanupStaleSlot(slot, staleMs);
+      try {
+        mkdirSync(slot);
+        writeFileSync(join(slot, 'owner.json'), JSON.stringify({
+          pid: process.pid,
+          backendName,
+          createdAt: new Date().toISOString(),
+        }), 'utf8');
+        return slot;
+      } catch (err) {
+        if (err?.code !== 'EEXIST') throw err;
+      }
+    }
+
+    throwIfAborted(signal, `${backendName || 'backend'}: aborted while waiting for concurrency slot`);
+    if (Date.now() - startedAt >= timeout) {
+      throw new Error(`${backendName || 'backend'}: timed out waiting for concurrency slot (cap ${maxConcurrency})`);
+    }
+    await sleepWithAbort(Math.min(pollMs, timeout), signal, backendName);
+  }
+}
+
+function cleanupStaleSlot(slot, staleMs) {
+  try {
+    const ageMs = Date.now() - statSync(slot).mtimeMs;
+    if (ageMs > staleMs) rmSync(slot, { recursive: true, force: true });
+  } catch {}
+}
+
+function releaseBackendSlot(slot) {
+  try {
+    rmSync(slot, { recursive: true, force: true });
+  } catch {}
+}
+
+function sleepWithAbort(ms, signal, backendName) {
+  if (ms <= 0) return Promise.resolve();
+  if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      cleanup();
+      reject(abortError(`${backendName || 'backend'}: aborted while waiting for concurrency slot`));
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', onAbort);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function throwIfAborted(signal, message) {
+  if (signal?.aborted) throw abortError(message);
+}
+
+function abortError(message) {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function safePathSegment(value) {
+  return String(value).replace(/[^a-z0-9._-]+/gi, '_');
+}
+
+export function runInteractiveCommand({
+  backendName,
+  command,
+  args = [],
+  cwd = process.cwd(),
+  env = process.env,
+  stdio = 'inherit',
+  notFoundHint,
+} = {}) {
+  if (!backendName || !command) {
+    throw new Error('interactive backend command requires backendName and command');
+  }
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(command, args, { cwd, env, stdio });
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error(`${backendName}: \`${command}\` CLI not found. ${notFoundHint || 'Install the CLI and try again.'}`));
+        return;
+      }
+      reject(new Error(`${backendName}: failed to spawn ${command} (${err.message})`));
+    });
+
+    proc.on('close', (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      if (signal) {
+        reject(new Error(`${backendName}: ${command} was terminated by ${signal}`));
+        return;
+      }
+      reject(new Error(`${backendName}: ${command} exited with code ${code}`));
+    });
+  });
+}

package/src/backends/gemini-cli.js

@@ -2,9 +2,12 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+import { DEFAULT_BACKEND_TIMEOUT_MS, runInteractiveCommand } from './contract.js';
+import { resolveLocalCliModel } from '../model-defaults.js';
 
 export const name = 'gemini-cli';
+export const loginCommand = 'gemini';
+export const installHint = 'Install Gemini CLI first, then run `patina auth login gemini-cli` again.';
 
 export function isAvailable() {
   try {
@@ -28,10 +31,20 @@ export function authHint() {
   if (process.env.GEMINI_API_KEY) {
     return 'Authenticated via GEMINI_API_KEY env var.';
   }
-  return 'Run `gemini` once interactively to log in via Google OAuth, or set GEMINI_API_KEY.';
+  return `Run \`${loginCommand}\` once interactively to log in via Google OAuth, or set GEMINI_API_KEY.`;
 }
 
-export async function invoke({ prompt, model, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+export function login(options = {}) {
+  return runInteractiveCommand({
+    backendName: name,
+    command: 'gemini',
+    args: [],
+    notFoundHint: installHint,
+    ...options,
+  });
+}
+
+export async function invoke({ prompt, model, modelSource, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('gemini-cli backend: prompt must be a non-empty string');
   }
@@ -43,8 +56,8 @@ export async function invoke({ prompt, model, signal, timeout = DEFAULT_BACKEND_
   // --skip-trust is required because the temp dir isn't in gemini's trusted
   // workspace list (otherwise gemini exits 55).
   const dir = mkdtempSync(join(tmpdir(), 'patina-gemini-'));
-  const args = ['-p', '', '--output-format', 'text', '--skip-trust'];
-  if (model) args.push('-m', model);
+  const cliModel = resolveLocalCliModel({ backendName: name, model, modelSource });
+  const args = ['-p', '', '--output-format', 'text', '--skip-trust', '-m', cliModel];
 
   return new Promise((resolve, reject) => {
     const proc = spawn('gemini', args, { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });

package/src/backends/index.js

@@ -2,12 +2,18 @@ import { callLLM } from '../api.js';
 import * as codexCli from './codex-cli.js';
 import * as claudeCli from './claude-cli.js';
 import * as geminiCli from './gemini-cli.js';
+import * as kimiCli from './kimi-cli.js';
 import { inspectHttpApiKeySource } from '../auth.js';
 import { inputError } from '../errors.js';
+import { DEFAULT_BEST_MODELS } from '../model-defaults.js';
 import {
   DEFAULT_BACKEND_TIMEOUT_MS,
   describeBackendError,
+  getBackendSafety,
   isRetryableBackendError,
+  resolveBackendMaxConcurrency,
+  resolveBackendMaxRetries,
+  withBackendConcurrencySlot,
 } from './contract.js';
 
 const openaiHttp = {
@@ -22,12 +28,12 @@ const openaiHttp = {
     model,
     signal,
     timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+    maxRetries,
     temperature,
     seed,
     onResponse,
-    cache,
   }) =>
-    callLLM({ prompt, apiKey, baseURL, model, signal, timeout, temperature, seed, onResponse, cache }),
+    callLLM({ prompt, apiKey, baseURL, model, signal, timeout, maxRetries, temperature, seed, onResponse }),
 };
 
 const REGISTRY = {
@@ -35,16 +41,57 @@ const REGISTRY = {
   'codex-cli': codexCli,
   'claude-cli': claudeCli,
   'gemini-cli': geminiCli,
+  'kimi-cli': kimiCli,
+};
+
+const BACKEND_META = {
+  'openai-http': {
+    kind: 'http',
+    selectWith: 'default, --backend openai-http, --provider <name>',
+    defaultModel: DEFAULT_BEST_MODELS.openai,
+  },
+  'codex-cli': {
+    kind: 'local-cli',
+    selectWith: '--backend codex-cli, --model codex-*',
+    defaultModel: DEFAULT_BEST_MODELS.codexCli,
+  },
+  'claude-cli': {
+    kind: 'local-cli',
+    selectWith: '--backend claude-cli, --model claude-*',
+    defaultModel: DEFAULT_BEST_MODELS.claudeCli,
+  },
+  'gemini-cli': {
+    kind: 'local-cli',
+    selectWith: '--backend gemini-cli, --model gemini-*',
+    defaultModel: DEFAULT_BEST_MODELS.geminiCli,
+  },
+  'kimi-cli': {
+    kind: 'local-cli',
+    selectWith: '--backend kimi-cli, --model kimi-*',
+    defaultModel: DEFAULT_BEST_MODELS.kimiCli,
+  },
 };
 
 export function listBackends() {
   return Object.keys(REGISTRY).map((key) => {
     const b = REGISTRY[key];
+    const meta = BACKEND_META[key] || { kind: 'unknown', selectWith: `--backend ${key}` };
+    const safety = getBackendSafety(key);
     return {
       name: key,
+      kind: meta.kind,
+      selectWith: meta.selectWith,
+      defaultModel: meta.defaultModel || null,
+      safety,
+      maxConcurrency: safety.maxConcurrency,
+      maxRetries: safety.maxRetries,
+      promptMode: safety.promptMode,
+      agentRuntime: safety.agentRuntime,
       available: b.isAvailable(),
       authenticated: b.isAuthenticated(),
       authHint: b.authHint(),
+      loginCommand: b.loginCommand || null,
+      installHint: b.installHint || null,
     };
   });
 }
@@ -53,21 +100,26 @@ export function listBackendNames() {
   return Object.keys(REGISTRY);
 }
 
-export function selectBackend({ name, model } = {}) {
+export function selectBackend({ name, model, modelSource } = {}) {
   if (name) {
     const backend = resolveBackend(name);
     return { backend, autoSelected: false, reason: 'explicit' };
   }
 
-  if (model && /^codex(-|$)/i.test(model)) {
+  const useModelHeuristic = model && (modelSource === undefined || modelSource === 'flag');
+
+  if (useModelHeuristic && /^codex(-|$)/i.test(model)) {
     return { backend: REGISTRY['codex-cli'], autoSelected: false, reason: 'model heuristic' };
   }
-  if (model && /^claude(-|$)/i.test(model)) {
+  if (useModelHeuristic && /^claude(-|$)/i.test(model)) {
     return { backend: REGISTRY['claude-cli'], autoSelected: false, reason: 'model heuristic' };
   }
-  if (model && /^gemini(-|$)/i.test(model)) {
+  if (useModelHeuristic && /^gemini(-|$)/i.test(model)) {
     return { backend: REGISTRY['gemini-cli'], autoSelected: false, reason: 'model heuristic' };
   }
+  if (useModelHeuristic && /^kimi(-|$)/i.test(model)) {
+    return { backend: REGISTRY['kimi-cli'], autoSelected: false, reason: 'model heuristic' };
+  }
 
   // No silent auto-fallback to any CLI backend. Sending arbitrary text to a
   // coding agent is a higher-trust action than calling a plain completion
@@ -76,7 +128,7 @@ export function selectBackend({ name, model } = {}) {
   return { backend: REGISTRY['openai-http'], autoSelected: false, reason: 'default' };
 }
 
-export function selectBackendChain({ name, model } = {}) {
+export function selectBackendChain({ name, model, modelSource } = {}) {
   if (name) {
     const names = String(name)
       .split(',')
@@ -96,7 +148,7 @@ export function selectBackendChain({ name, model } = {}) {
     };
   }
 
-  const selected = selectBackend({ model });
+  const selected = selectBackend({ model, modelSource });
   return {
     backends: [selected.backend],
     autoSelected: selected.autoSelected,
@@ -110,27 +162,50 @@ export async function invokeBackendChain({
   apiKey,
   baseURL,
   model,
+  modelSource,
   signal,
   timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+  maxConcurrency,
+  maxRetries,
   temperature,
   seed,
   onResponse,
-  cache,
   logger,
 }) {
   if (!Array.isArray(backends) || backends.length === 0) {
     throw inputError(
       'no backend selected',
       'patina could not resolve a backend to run.',
-      'Pass --backend openai-http, codex-cli, claude-cli, or gemini-cli.'
+      'Pass --backend openai-http, codex-cli, claude-cli, gemini-cli, or kimi-cli.'
     );
   }
 
   let lastError = null;
   for (let attemptIndex = 0; attemptIndex < backends.length; attemptIndex++) {
     const backend = backends[attemptIndex];
+    const effectiveMaxConcurrency = resolveBackendMaxConcurrency(backend.name, maxConcurrency);
+    const effectiveMaxRetries = resolveBackendMaxRetries(backend.name, maxRetries);
     try {
-      return await backend.invoke({ prompt, apiKey, baseURL, model, signal, timeout, temperature, seed, onResponse, cache });
+      return await withBackendConcurrencySlot({
+        backendName: backend.name,
+        maxConcurrency: effectiveMaxConcurrency,
+        signal,
+        timeout,
+        fn: () => backend.invoke({
+          prompt,
+          apiKey,
+          baseURL,
+          model,
+          modelSource,
+          signal,
+          timeout,
+          maxRetries: effectiveMaxRetries,
+          temperature,
+          seed,
+          onResponse,
+          logger,
+        }),
+      });
     } catch (err) {
       lastError = err;
       const next = backends[attemptIndex + 1];
@@ -146,7 +221,7 @@ export async function invokeBackendChain({
   throw lastError || new Error('backend fallback chain failed without an error');
 }
 
-function resolveBackend(name) {
+export function resolveBackend(name) {
   const backend = REGISTRY[name];
   if (!backend) {
     throw inputError(