feat: extend providerOptions with baseUrl/apiKey for OpenAI-compatible endpoints

Adds two optional fields to AgentDefinition.providerOptions (and the
backend OpenRouterProviderRoutingOptions + Zod schema) so an agent can
direct its LLM calls at a custom OpenAI-compatible base URL (Ollama,
LM Studio, self-hosted). The dispatch logic that consumes these fields
lands in a follow-up commit.

Also adds CODEBUFF_BASE_URL / CODEBUFF_PROVIDER_API_KEY env var
constants and SDK getters for them.

Part of issue #678.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: vraj00222

.agents/types/agent-definition.ts

@@ -109,6 +109,25 @@ export interface AgentDefinition {
       audio?: number | string
       request?: number | string
     }
+    /**
+     * Override the upstream LLM endpoint with an OpenAI-compatible base URL.
+     * When set, this agent's LLM calls bypass the Codebuff backend / OpenRouter
+     * and go directly to `${baseUrl}/chat/completions`.
+     *
+     * Use for local models (Ollama, LM Studio) or self-hosted OpenAI-compatible
+     * providers. The other providerOptions keys (order, allow_fallbacks, etc.)
+     * are OpenRouter-specific and ignored when `baseUrl` is set.
+     *
+     * Falls back to env var CODEBUFF_BASE_URL when unset.
+     * Example: "http://localhost:11434/v1"
+     */
+    baseUrl?: string
+    /**
+     * API key for the endpoint set in `baseUrl`. Ignored if `baseUrl` is unset.
+     * Falls back to env var CODEBUFF_PROVIDER_API_KEY. Most local runtimes
+     * (Ollama, LM Studio) ignore the value entirely.
+     */
+    apiKey?: string
   }
 
   // ============================================================================

agents/types/agent-definition.ts

@@ -109,6 +109,25 @@ export interface AgentDefinition {
       audio?: number | string
       request?: number | string
     }
+    /**
+     * Override the upstream LLM endpoint with an OpenAI-compatible base URL.
+     * When set, this agent's LLM calls bypass the Codebuff backend / OpenRouter
+     * and go directly to `${baseUrl}/chat/completions`.
+     *
+     * Use for local models (Ollama, LM Studio) or self-hosted OpenAI-compatible
+     * providers. The other providerOptions keys (order, allow_fallbacks, etc.)
+     * are OpenRouter-specific and ignored when `baseUrl` is set.
+     *
+     * Falls back to env var CODEBUFF_BASE_URL when unset.
+     * Example: "http://localhost:11434/v1"
+     */
+    baseUrl?: string
+    /**
+     * API key for the endpoint set in `baseUrl`. Ignored if `baseUrl` is unset.
+     * Falls back to env var CODEBUFF_PROVIDER_API_KEY. Most local runtimes
+     * (Ollama, LM Studio) ignore the value entirely.
+     */
+    apiKey?: string
   }
 
   // ============================================================================

common/src/constants/custom-provider.ts

@@ -0,0 +1,7 @@
+/** Env var that overrides the upstream LLM endpoint with an OpenAI-compatible base URL.
+ *  Lower precedence than per-agent providerOptions.baseUrl and the CodebuffClient option. */
+export const PROVIDER_BASE_URL_ENV_VAR = 'CODEBUFF_BASE_URL'
+
+/** Env var providing the API key for the endpoint set by PROVIDER_BASE_URL_ENV_VAR.
+ *  Most local runtimes (Ollama, LM Studio) ignore the key entirely. */
+export const PROVIDER_API_KEY_ENV_VAR = 'CODEBUFF_PROVIDER_API_KEY'

common/src/templates/initial-agents-dir/types/agent-definition.ts

@@ -109,6 +109,25 @@ export interface AgentDefinition {
       audio?: number | string
       request?: number | string
     }
+    /**
+     * Override the upstream LLM endpoint with an OpenAI-compatible base URL.
+     * When set, this agent's LLM calls bypass the Codebuff backend / OpenRouter
+     * and go directly to `${baseUrl}/chat/completions`.
+     *
+     * Use for local models (Ollama, LM Studio) or self-hosted OpenAI-compatible
+     * providers. The other providerOptions keys (order, allow_fallbacks, etc.)
+     * are OpenRouter-specific and ignored when `baseUrl` is set.
+     *
+     * Falls back to env var CODEBUFF_BASE_URL when unset.
+     * Example: "http://localhost:11434/v1"
+     */
+    baseUrl?: string
+    /**
+     * API key for the endpoint set in `baseUrl`. Ignored if `baseUrl` is unset.
+     * Falls back to env var CODEBUFF_PROVIDER_API_KEY. Most local runtimes
+     * (Ollama, LM Studio) ignore the value entirely.
+     */
+    apiKey?: string
   }
 
   // ============================================================================

common/src/types/agent-template.ts

@@ -37,6 +37,12 @@ export type OpenRouterReasoningOptions = {
     }
 )
 
+/**
+ * OpenRouter provider-routing options, plus optional fields to override the
+ * upstream endpoint with an OpenAI-compatible base URL (e.g. Ollama, LM Studio,
+ * self-hosted). The routing fields below are OpenRouter-specific and are
+ * ignored when `baseUrl` is set.
+ */
 export type OpenRouterProviderRoutingOptions = {
   /**
    * List of provider slugs to try in order (e.g. ["anthropic", "openai"])
@@ -90,6 +96,20 @@ export type OpenRouterProviderRoutingOptions = {
     audio?: number | string
     request?: number | string
   }
+  /**
+   * Override the upstream LLM endpoint with an OpenAI-compatible base URL.
+   * When set, this agent's calls bypass the Codebuff backend / OpenRouter
+   * and go directly to `${baseUrl}/chat/completions`.
+   *
+   * Other keys above (order, allow_fallbacks, ...) are OpenRouter-specific and
+   * are ignored when baseUrl is set. Falls back to env var CODEBUFF_BASE_URL.
+   */
+  baseUrl?: string
+  /**
+   * API key for the endpoint set in `baseUrl`. Ignored if baseUrl is unset.
+   * Falls back to env var CODEBUFF_PROVIDER_API_KEY.
+   */
+  apiKey?: string
 }
 
 export type OpenRouterProviderOptions = {

common/src/types/dynamic-agent-template.ts

@@ -167,6 +167,8 @@ export const DynamicAgentDefinitionSchema = z.object({
           request: z.union([z.number(), z.string()]).optional(),
         })
         .optional(),
+      baseUrl: z.string().url().optional(),
+      apiKey: z.string().optional(),
     })
     .optional(),
 

sdk/src/env.ts

@@ -7,6 +7,10 @@
 
 import { BYOK_OPENROUTER_ENV_VAR } from '@codebuff/common/constants/byok'
 import { CHATGPT_OAUTH_TOKEN_ENV_VAR } from '@codebuff/common/constants/chatgpt-oauth'
+import {
+  PROVIDER_API_KEY_ENV_VAR,
+  PROVIDER_BASE_URL_ENV_VAR,
+} from '@codebuff/common/constants/custom-provider'
 import { API_KEY_ENV_VAR } from '@codebuff/common/constants/paths'
 import { getBaseEnv } from '@codebuff/common/env-process'
 
@@ -48,3 +52,19 @@ export const getByokOpenrouterApiKeyFromEnv = (): string | undefined => {
 export const getChatGptOAuthTokenFromEnv = (): string | undefined => {
   return process.env[CHATGPT_OAUTH_TOKEN_ENV_VAR]
 }
+
+/**
+ * Get the custom upstream provider base URL from environment.
+ * Used when an agent's providerOptions.baseUrl is unset and no CodebuffClient option overrides it.
+ */
+export const getCustomProviderBaseUrlFromEnv = (): string | undefined => {
+  return process.env[PROVIDER_BASE_URL_ENV_VAR]
+}
+
+/**
+ * Get the custom upstream provider API key from environment.
+ * Paired with getCustomProviderBaseUrlFromEnv.
+ */
+export const getCustomProviderApiKeyFromEnv = (): string | undefined => {
+  return process.env[PROVIDER_API_KEY_ENV_VAR]
+}