@xelauvas/xela-cli 0.1.0

package/src/utils/model/modelSupportOverrides.ts

@@ -0,0 +1,50 @@
+import memoize from 'lodash-es/memoize.js'
+import { getAPIProvider } from './providers.js'
+
+export type ModelCapabilityOverride =
+  | 'effort'
+  | 'max_effort'
+  | 'thinking'
+  | 'adaptive_thinking'
+  | 'interleaved_thinking'
+
+const TIERS = [
+  {
+    modelEnvVar: 'ANTHROPIC_DEFAULT_OPUS_MODEL',
+    capabilitiesEnvVar: 'ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES',
+  },
+  {
+    modelEnvVar: 'ANTHROPIC_DEFAULT_SONNET_MODEL',
+    capabilitiesEnvVar: 'ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES',
+  },
+  {
+    modelEnvVar: 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    capabilitiesEnvVar: 'ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES',
+  },
+] as const
+
+/**
+ * Check whether a 3p model capability override is set for a model that matches one of
+ * the pinned ANTHROPIC_DEFAULT_*_MODEL env vars.
+ */
+export const get3PModelCapabilityOverride = memoize(
+  (model: string, capability: ModelCapabilityOverride): boolean | undefined => {
+    if (getAPIProvider() === 'firstParty') {
+      return undefined
+    }
+    const m = model.toLowerCase()
+    for (const tier of TIERS) {
+      const pinned = process.env[tier.modelEnvVar]
+      const capabilities = process.env[tier.capabilitiesEnvVar]
+      if (!pinned || capabilities === undefined) continue
+      if (m !== pinned.toLowerCase()) continue
+      return capabilities
+        .toLowerCase()
+        .split(',')
+        .map(s => s.trim())
+        .includes(capability)
+    }
+    return undefined
+  },
+  (model, capability) => `${model.toLowerCase()}:${capability}`,
+)

package/src/utils/model/providers.ts

@@ -0,0 +1,46 @@
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from '../../services/analytics/index.js'
+import { isEnvTruthy } from '../envUtils.js'
+
+export type APIProvider = 'firstParty' | 'bedrock' | 'vertex' | 'foundry'
+
+export function getAPIProvider(): APIProvider {
+  // When using OpenAI backend, report as non-firstParty to skip
+  // Anthropic-specific codepaths (1P betas, global cache scope,
+  // off-switch checks, etc.)
+  if (process.env.OPENAI_API_KEY) {
+    return 'foundry'
+  }
+  return isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)
+    ? 'bedrock'
+    : isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)
+      ? 'vertex'
+      : isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)
+        ? 'foundry'
+        : 'firstParty'
+}
+
+export function getAPIProviderForStatsig(): AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS {
+  return getAPIProvider() as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+}
+
+/**
+ * Check if ANTHROPIC_BASE_URL is a first-party Anthropic API URL.
+ * Returns true if not set (default API) or points to api.anthropic.com
+ * (or api-staging.anthropic.com for ant users).
+ */
+export function isFirstPartyAnthropicBaseUrl(): boolean {
+  const baseUrl = process.env.ANTHROPIC_BASE_URL
+  if (!baseUrl) {
+    return true
+  }
+  try {
+    const host = new URL(baseUrl).host
+    const allowedHosts = ['api.anthropic.com']
+    if (process.env.USER_TYPE === 'ant') {
+      allowedHosts.push('api-staging.anthropic.com')
+    }
+    return allowedHosts.includes(host)
+  } catch {
+    return false
+  }
+}

package/src/utils/model/validateModel.ts

@@ -0,0 +1,159 @@
+// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
+import { MODEL_ALIASES } from './aliases.js'
+import { isModelAllowed } from './modelAllowlist.js'
+import { getAPIProvider } from './providers.js'
+import { sideQuery } from '../sideQuery.js'
+import {
+  NotFoundError,
+  APIError,
+  APIConnectionError,
+  AuthenticationError,
+} from '@anthropic-ai/sdk'
+import { getModelStrings } from './modelStrings.js'
+
+// Cache valid models to avoid repeated API calls
+const validModelCache = new Map<string, boolean>()
+
+/**
+ * Validates a model by attempting an actual API call.
+ */
+export async function validateModel(
+  model: string,
+): Promise<{ valid: boolean; error?: string }> {
+  const normalizedModel = model.trim()
+
+  // Empty model is invalid
+  if (!normalizedModel) {
+    return { valid: false, error: 'Model name cannot be empty' }
+  }
+
+  // Check against availableModels allowlist before any API call
+  if (!isModelAllowed(normalizedModel)) {
+    return {
+      valid: false,
+      error: `Model '${normalizedModel}' is not in the list of available models`,
+    }
+  }
+
+  // Check if it's a known alias (these are always valid)
+  const lowerModel = normalizedModel.toLowerCase()
+  if ((MODEL_ALIASES as readonly string[]).includes(lowerModel)) {
+    return { valid: true }
+  }
+
+  // Check if it matches ANTHROPIC_CUSTOM_MODEL_OPTION (pre-validated by the user)
+  if (normalizedModel === process.env.ANTHROPIC_CUSTOM_MODEL_OPTION) {
+    return { valid: true }
+  }
+
+  // Check cache first
+  if (validModelCache.has(normalizedModel)) {
+    return { valid: true }
+  }
+
+
+  // Try to make an actual API call with minimal parameters
+  try {
+    await sideQuery({
+      model: normalizedModel,
+      max_tokens: 1,
+      maxRetries: 0,
+      querySource: 'model_validation',
+      messages: [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'text',
+              text: 'Hi',
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+      ],
+    })
+
+    // If we got here, the model is valid
+    validModelCache.set(normalizedModel, true)
+    return { valid: true }
+  } catch (error) {
+    return handleValidationError(error, normalizedModel)
+  }
+}
+
+function handleValidationError(
+  error: unknown,
+  modelName: string,
+): { valid: boolean; error: string } {
+  // NotFoundError (404) means the model doesn't exist
+  if (error instanceof NotFoundError) {
+    const fallback = get3PFallbackSuggestion(modelName)
+    const suggestion = fallback ? `. Try '${fallback}' instead` : ''
+    return {
+      valid: false,
+      error: `Model '${modelName}' not found${suggestion}`,
+    }
+  }
+
+  // For other API errors, provide context-specific messages
+  if (error instanceof APIError) {
+    if (error instanceof AuthenticationError) {
+      return {
+        valid: false,
+        error: 'Authentication failed. Please check your API credentials.',
+      }
+    }
+
+    if (error instanceof APIConnectionError) {
+      return {
+        valid: false,
+        error: 'Network error. Please check your internet connection.',
+      }
+    }
+
+    // Check error body for model-specific errors
+    const errorBody = error.error as unknown
+    if (
+      errorBody &&
+      typeof errorBody === 'object' &&
+      'type' in errorBody &&
+      errorBody.type === 'not_found_error' &&
+      'message' in errorBody &&
+      typeof errorBody.message === 'string' &&
+      errorBody.message.includes('model:')
+    ) {
+      return { valid: false, error: `Model '${modelName}' not found` }
+    }
+
+    // Generic API error
+    return { valid: false, error: `API error: ${error.message}` }
+  }
+
+  // For unknown errors, be safe and reject
+  const errorMessage = error instanceof Error ? error.message : String(error)
+  return {
+    valid: false,
+    error: `Unable to validate model: ${errorMessage}`,
+  }
+}
+
+// @[MODEL LAUNCH]: Add a fallback suggestion chain for the new model → previous version
+/**
+ * Suggest a fallback model for 3P users when the selected model is unavailable.
+ */
+function get3PFallbackSuggestion(model: string): string | undefined {
+  if (getAPIProvider() === 'firstParty') {
+    return undefined
+  }
+  const lowerModel = model.toLowerCase()
+  if (lowerModel.includes('opus-4-6') || lowerModel.includes('opus_4_6')) {
+    return getModelStrings().opus41
+  }
+  if (lowerModel.includes('sonnet-4-6') || lowerModel.includes('sonnet_4_6')) {
+    return getModelStrings().sonnet45
+  }
+  if (lowerModel.includes('sonnet-4-5') || lowerModel.includes('sonnet_4_5')) {
+    return getModelStrings().sonnet40
+  }
+  return undefined
+}

package/src/utils/modelCost.ts

@@ -0,0 +1,235 @@
+import type { BetaUsage as Usage } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs'
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from 'src/services/analytics/index.js'
+import { logEvent } from 'src/services/analytics/index.js'
+import { setHasUnknownModelCost } from '../bootstrap/state.js'
+import { isFastModeEnabled } from './fastMode.js'
+import {
+  CLAUDE_3_5_HAIKU_CONFIG,
+  CLAUDE_3_5_V2_SONNET_CONFIG,
+  CLAUDE_3_7_SONNET_CONFIG,
+  CLAUDE_HAIKU_4_5_CONFIG,
+  CLAUDE_OPUS_4_1_CONFIG,
+  CLAUDE_OPUS_4_5_CONFIG,
+  CLAUDE_OPUS_4_6_CONFIG,
+  CLAUDE_OPUS_4_CONFIG,
+  CLAUDE_SONNET_4_5_CONFIG,
+  CLAUDE_SONNET_4_6_CONFIG,
+  CLAUDE_SONNET_4_CONFIG,
+} from './model/configs.js'
+import {
+  firstPartyNameToCanonical,
+  getCanonicalName,
+  getDefaultMainLoopModelSetting,
+  type ModelShortName,
+} from './model/model.js'
+
+// @see https://platform.claude.com/docs/en/about-claude/pricing
+export type ModelCosts = {
+  inputTokens: number
+  outputTokens: number
+  promptCacheWriteTokens: number
+  promptCacheReadTokens: number
+  webSearchRequests: number
+}
+
+// Standard pricing tier for Sonnet models: $3 input / $15 output per Mtok
+export const COST_TIER_3_15 = {
+  inputTokens: 3,
+  outputTokens: 15,
+  promptCacheWriteTokens: 3.75,
+  promptCacheReadTokens: 0.3,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+// Pricing tier for Opus 4/4.1: $15 input / $75 output per Mtok
+export const COST_TIER_15_75 = {
+  inputTokens: 15,
+  outputTokens: 75,
+  promptCacheWriteTokens: 18.75,
+  promptCacheReadTokens: 1.5,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+// Pricing tier for Opus 4.5: $5 input / $25 output per Mtok
+export const COST_TIER_5_25 = {
+  inputTokens: 5,
+  outputTokens: 25,
+  promptCacheWriteTokens: 6.25,
+  promptCacheReadTokens: 0.5,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+// Fast mode pricing for Opus 4.6: $30 input / $150 output per Mtok
+export const COST_TIER_30_150 = {
+  inputTokens: 30,
+  outputTokens: 150,
+  promptCacheWriteTokens: 37.5,
+  promptCacheReadTokens: 3,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+// Pricing for Haiku 3.5: $0.80 input / $4 output per Mtok
+export const COST_HAIKU_35 = {
+  inputTokens: 0.8,
+  outputTokens: 4,
+  promptCacheWriteTokens: 1,
+  promptCacheReadTokens: 0.08,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+// Pricing for Haiku 4.5: $1 input / $5 output per Mtok
+export const COST_HAIKU_45 = {
+  inputTokens: 1,
+  outputTokens: 5,
+  promptCacheWriteTokens: 1.25,
+  promptCacheReadTokens: 0.1,
+  webSearchRequests: 0.01,
+} as const satisfies ModelCosts
+
+const DEFAULT_UNKNOWN_MODEL_COST = COST_TIER_5_25
+
+/**
+ * Get the cost tier for Opus 4.6 based on fast mode.
+ */
+export function getOpus46CostTier(fastMode: boolean): ModelCosts {
+  if (isFastModeEnabled() && fastMode) {
+    return COST_TIER_30_150
+  }
+  return COST_TIER_5_25
+}
+
+// @[MODEL LAUNCH]: Add a pricing entry for the new model below.
+// Costs from https://platform.claude.com/docs/en/about-claude/pricing
+// Web search cost: $10 per 1000 requests = $0.01 per request
+export const MODEL_COSTS: Record<ModelShortName, ModelCosts> = {
+  [firstPartyNameToCanonical(CLAUDE_3_5_HAIKU_CONFIG.firstParty)]:
+    COST_HAIKU_35,
+  [firstPartyNameToCanonical(CLAUDE_HAIKU_4_5_CONFIG.firstParty)]:
+    COST_HAIKU_45,
+  [firstPartyNameToCanonical(CLAUDE_3_5_V2_SONNET_CONFIG.firstParty)]:
+    COST_TIER_3_15,
+  [firstPartyNameToCanonical(CLAUDE_3_7_SONNET_CONFIG.firstParty)]:
+    COST_TIER_3_15,
+  [firstPartyNameToCanonical(CLAUDE_SONNET_4_CONFIG.firstParty)]:
+    COST_TIER_3_15,
+  [firstPartyNameToCanonical(CLAUDE_SONNET_4_5_CONFIG.firstParty)]:
+    COST_TIER_3_15,
+  [firstPartyNameToCanonical(CLAUDE_SONNET_4_6_CONFIG.firstParty)]:
+    COST_TIER_3_15,
+  [firstPartyNameToCanonical(CLAUDE_OPUS_4_CONFIG.firstParty)]: COST_TIER_15_75,
+  [firstPartyNameToCanonical(CLAUDE_OPUS_4_1_CONFIG.firstParty)]:
+    COST_TIER_15_75,
+  [firstPartyNameToCanonical(CLAUDE_OPUS_4_5_CONFIG.firstParty)]:
+    COST_TIER_5_25,
+  [firstPartyNameToCanonical(CLAUDE_OPUS_4_6_CONFIG.firstParty)]:
+    COST_TIER_5_25,
+}
+
+/**
+ * Calculates the USD cost based on token usage and model cost configuration
+ */
+function tokensToUSDCost(modelCosts: ModelCosts, usage: Usage): number {
+  return (
+    (usage.input_tokens / 1_000_000) * modelCosts.inputTokens +
+    (usage.output_tokens / 1_000_000) * modelCosts.outputTokens +
+    ((usage.cache_read_input_tokens ?? 0) / 1_000_000) *
+      modelCosts.promptCacheReadTokens +
+    ((usage.cache_creation_input_tokens ?? 0) / 1_000_000) *
+      modelCosts.promptCacheWriteTokens +
+    (usage.server_tool_use?.web_search_requests ?? 0) *
+      modelCosts.webSearchRequests
+  )
+}
+
+export function getModelCosts(model: string, usage: Usage): ModelCosts {
+  const shortName = getCanonicalName(model)
+
+  // Check if this is an Opus 4.6 model with fast mode active.
+  if (
+    shortName === firstPartyNameToCanonical(CLAUDE_OPUS_4_6_CONFIG.firstParty)
+  ) {
+    const isFastMode = usage.speed === 'fast'
+    return getOpus46CostTier(isFastMode)
+  }
+
+  const costs = MODEL_COSTS[shortName]
+  if (!costs) {
+    trackUnknownModelCost(model, shortName)
+    return (
+      MODEL_COSTS[getCanonicalName(getDefaultMainLoopModelSetting())] ??
+      DEFAULT_UNKNOWN_MODEL_COST
+    )
+  }
+  return costs
+}
+
+function trackUnknownModelCost(model: string, shortName: ModelShortName): void {
+  logEvent('tengu_unknown_model_cost', {
+    model: model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    shortName:
+      shortName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  })
+  setHasUnknownModelCost()
+}
+
+// Calculate the cost of a query in US dollars.
+// If the model's costs are not found, use the default model's costs.
+export function calculateUSDCost(resolvedModel: string, usage: Usage): number {
+  // OpenAI pricing is not tracked here; return 0 to avoid false cost reports.
+  if (process.env.OPENAI_API_KEY) {
+    return 0
+  }
+  const modelCosts = getModelCosts(resolvedModel, usage)
+  return tokensToUSDCost(modelCosts, usage)
+}
+
+/**
+ * Calculate cost from raw token counts without requiring a full BetaUsage object.
+ * Useful for side queries (e.g. classifier) that track token counts independently.
+ */
+export function calculateCostFromTokens(
+  model: string,
+  tokens: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadInputTokens: number
+    cacheCreationInputTokens: number
+  },
+): number {
+  const usage: Usage = {
+    input_tokens: tokens.inputTokens,
+    output_tokens: tokens.outputTokens,
+    cache_read_input_tokens: tokens.cacheReadInputTokens,
+    cache_creation_input_tokens: tokens.cacheCreationInputTokens,
+  } as Usage
+  return calculateUSDCost(model, usage)
+}
+
+function formatPrice(price: number): string {
+  // Format price: integers without decimals, others with 2 decimal places
+  // e.g., 3 -> "$3", 0.8 -> "$0.80", 22.5 -> "$22.50"
+  if (Number.isInteger(price)) {
+    return `$${price}`
+  }
+  return `$${price.toFixed(2)}`
+}
+
+/**
+ * Format model costs as a pricing string for display
+ * e.g., "$3/$15 per Mtok"
+ */
+export function formatModelPricing(costs: ModelCosts): string {
+  return `${formatPrice(costs.inputTokens)}/${formatPrice(costs.outputTokens)} per Mtok`
+}
+
+/**
+ * Get formatted pricing string for a model
+ * Accepts either a short name or full model name
+ * Returns undefined if model is not found
+ */
+export function getModelPricingString(model: string): string | undefined {
+  const shortName = getCanonicalName(model)
+  const costs = MODEL_COSTS[shortName]
+  if (!costs) return undefined
+  return formatModelPricing(costs)
+}

package/src/utils/modifiers.ts

@@ -0,0 +1,36 @@
+export type ModifierKey = 'shift' | 'command' | 'control' | 'option'
+
+let prewarmed = false
+
+/**
+ * Pre-warm the native module by loading it in advance.
+ * Call this early to avoid delay on first use.
+ */
+export function prewarmModifiers(): void {
+  if (prewarmed || process.platform !== 'darwin') {
+    return
+  }
+  prewarmed = true
+  // Load module in background
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { prewarm } = require('modifiers-napi') as { prewarm: () => void }
+    prewarm()
+  } catch {
+    // Ignore errors during prewarm
+  }
+}
+
+/**
+ * Check if a specific modifier key is currently pressed (synchronous).
+ */
+export function isModifierPressed(modifier: ModifierKey): boolean {
+  if (process.platform !== 'darwin') {
+    return false
+  }
+  // Dynamic import to avoid loading native module at top level
+  const { isModifierPressed: nativeIsModifierPressed } =
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('modifiers-napi') as { isModifierPressed: (m: string) => boolean }
+  return nativeIsModifierPressed(modifier)
+}

package/src/utils/mtls.ts

@@ -0,0 +1,179 @@
+import type * as https from 'https'
+import { Agent as HttpsAgent } from 'https'
+import memoize from 'lodash-es/memoize.js'
+import type * as tls from 'tls'
+import type * as undici from 'undici'
+import { getCACertificates } from './caCerts.js'
+import { logForDebugging } from './debug.js'
+import { getFsImplementation } from './fsOperations.js'
+
+export type MTLSConfig = {
+  cert?: string
+  key?: string
+  passphrase?: string
+}
+
+export type TLSConfig = MTLSConfig & {
+  ca?: string | string[] | Buffer
+}
+
+/**
+ * Get mTLS configuration from environment variables
+ */
+export const getMTLSConfig = memoize((): MTLSConfig | undefined => {
+  const config: MTLSConfig = {}
+
+  // Note: NODE_EXTRA_CA_CERTS is automatically handled by Node.js at runtime
+  // We don't need to manually load it - Node.js appends it to the built-in CAs automatically
+
+  // Client certificate
+  if (process.env.CLAUDE_CODE_CLIENT_CERT) {
+    try {
+      config.cert = getFsImplementation().readFileSync(
+        process.env.CLAUDE_CODE_CLIENT_CERT,
+        { encoding: 'utf8' },
+      )
+      logForDebugging(
+        'mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT',
+      )
+    } catch (error) {
+      logForDebugging(`mTLS: Failed to load client certificate: ${error}`, {
+        level: 'error',
+      })
+    }
+  }
+
+  // Client key
+  if (process.env.CLAUDE_CODE_CLIENT_KEY) {
+    try {
+      config.key = getFsImplementation().readFileSync(
+        process.env.CLAUDE_CODE_CLIENT_KEY,
+        { encoding: 'utf8' },
+      )
+      logForDebugging('mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY')
+    } catch (error) {
+      logForDebugging(`mTLS: Failed to load client key: ${error}`, {
+        level: 'error',
+      })
+    }
+  }
+
+  // Key passphrase
+  if (process.env.CLAUDE_CODE_CLIENT_KEY_PASSPHRASE) {
+    config.passphrase = process.env.CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
+    logForDebugging('mTLS: Using client key passphrase')
+  }
+
+  // Only return config if at least one option is set
+  if (Object.keys(config).length === 0) {
+    return undefined
+  }
+
+  return config
+})
+
+/**
+ * Create an HTTPS agent with mTLS configuration
+ */
+export const getMTLSAgent = memoize((): HttpsAgent | undefined => {
+  const mtlsConfig = getMTLSConfig()
+  const caCerts = getCACertificates()
+
+  if (!mtlsConfig && !caCerts) {
+    return undefined
+  }
+
+  const agentOptions: https.AgentOptions = {
+    ...mtlsConfig,
+    ...(caCerts && { ca: caCerts }),
+    // Enable keep-alive for better performance
+    keepAlive: true,
+  }
+
+  logForDebugging('mTLS: Creating HTTPS agent with custom certificates')
+  return new HttpsAgent(agentOptions)
+})
+
+/**
+ * Get TLS options for WebSocket connections
+ */
+export function getWebSocketTLSOptions(): tls.ConnectionOptions | undefined {
+  const mtlsConfig = getMTLSConfig()
+  const caCerts = getCACertificates()
+
+  if (!mtlsConfig && !caCerts) {
+    return undefined
+  }
+
+  return {
+    ...mtlsConfig,
+    ...(caCerts && { ca: caCerts }),
+  }
+}
+
+/**
+ * Get fetch options with TLS configuration (mTLS + CA certs) for undici
+ */
+export function getTLSFetchOptions(): {
+  tls?: TLSConfig
+  dispatcher?: undici.Dispatcher
+} {
+  const mtlsConfig = getMTLSConfig()
+  const caCerts = getCACertificates()
+
+  if (!mtlsConfig && !caCerts) {
+    return {}
+  }
+
+  const tlsConfig: TLSConfig = {
+    ...mtlsConfig,
+    ...(caCerts && { ca: caCerts }),
+  }
+
+  if (typeof Bun !== 'undefined') {
+    return { tls: tlsConfig }
+  }
+  logForDebugging('TLS: Created undici agent with custom certificates')
+  // Create a custom undici Agent with TLS options. Lazy-required so that
+  // the ~1.5MB undici package is only loaded when mTLS/CA certs are configured.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const undiciMod = require('undici') as typeof undici
+  const agent = new undiciMod.Agent({
+    connect: {
+      cert: tlsConfig.cert,
+      key: tlsConfig.key,
+      passphrase: tlsConfig.passphrase,
+      ...(tlsConfig.ca && { ca: tlsConfig.ca }),
+    },
+    pipelining: 1,
+  })
+
+  return { dispatcher: agent }
+}
+
+/**
+ * Clear the mTLS configuration cache.
+ */
+export function clearMTLSCache(): void {
+  getMTLSConfig.cache.clear?.()
+  getMTLSAgent.cache.clear?.()
+  logForDebugging('Cleared mTLS configuration cache')
+}
+
+/**
+ * Configure global Node.js TLS settings
+ */
+export function configureGlobalMTLS(): void {
+  const mtlsConfig = getMTLSConfig()
+
+  if (!mtlsConfig) {
+    return
+  }
+
+  // NODE_EXTRA_CA_CERTS is automatically handled by Node.js at runtime
+  if (process.env.NODE_EXTRA_CA_CERTS) {
+    logForDebugging(
+      'NODE_EXTRA_CA_CERTS detected - Node.js will automatically append to built-in CAs',
+    )
+  }
+}