interface ProviderConfig {
  /** Provider identifier from the taxonomy */
  provider: ProviderId;
  
  /** Model identifier (provider-specific format) */
  model: string;
  
  /** Wire protocol the provider's API speaks */
  transport: TransportId;
  
  /** Authentication configuration */
  auth: ProviderAuth;
  
  /** Provider-specific parameters */
  params: Record<string, string>;
}

type ProviderId =
  | 'anthropic'     // Anthropic direct API
  | 'openai'        // OpenAI direct API
  | 'google'        // Google AI Studio
  | 'bedrock'       // AWS Bedrock
  | 'vertex'        // Google Vertex AI
  | 'azure'         // Azure OpenAI
  | 'foundry'       // Azure AI Foundry
  | 'ollama'        // Local Ollama instance
  | 'local'         // Generic local model server
  | 'openrouter'    // OpenRouter
  | 'groq'          // Groq
  | 'fireworks'     // Fireworks AI
  | 'together'      // Together AI
  | 'deepseek'      // DeepSeek
  | 'mistral'       // Mistral AI
  | 'cerebras'      // Cerebras
  | 'sambanova'     // SambaNova
  | 'custom';       // User-defined endpoint

type TransportId =
  | 'anthropic'          // Anthropic Messages API
  | 'openai-chat'        // OpenAI Chat Completions
  | 'openai-responses'   // OpenAI Responses API
  | 'google';            // Google GenerateContent

interface ProviderAuth {
  /** Auth mechanism */
  type: 'api_key' | 'oauth' | 'iam' | 'adc' | 'service_account' | 'spn' | 'bearer' | 'none' | 'command';
  
  /** API key value (or env var name prefixed with $) */
  apiKey?: string;
  
  /** OAuth/bearer token */
  token?: string;
  
  /** External command that outputs a token */
  command?: string;
  
  /** AWS-specific */
  awsProfile?: string;
  awsRoleArn?: string;
  awsSessionToken?: string;
  
  /** GCP-specific */
  gcpCredentialsFile?: string;
  
  /** Azure-specific */
  azureTenantId?: string;
  azureClientId?: string;
  azureClientSecret?: string;
}

1. Provider defaults (§2.2)              ← lowest priority
2. Global config:  ~/.amux/providers.json
3. Project config: .amux/providers.json
4. Named profile:  --profile <name>
5. Environment variables
6. CLI flags                              ← highest priority

{
  "$schema": "https://a5c.ai/schemas/amux-providers.json",
  "version": 1,
  
  "defaults": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },

  "profiles": {
    "work-bedrock": {
      "provider": "bedrock",
      "model": "anthropic.claude-sonnet-4-20250514-v1:0",
      "auth": {
        "type": "iam",
        "awsProfile": "work-sso"
      },
      "params": {
        "region": "us-east-1"
      }
    },
    "home-vertex": {
      "provider": "vertex",
      "model": "claude-sonnet-4@20250514",
      "auth": {
        "type": "adc"
      },
      "params": {
        "project": "my-home-project",
        "region": "us-central1"
      }
    },
    "local-ollama": {
      "provider": "ollama",
      "model": "qwen3:32b",
      "auth": { "type": "none" },
      "params": {
        "apiBase": "http://localhost:11434"
      }
    },
    "corp-proxy": {
      "provider": "custom",
      "transport": "openai-chat",
      "model": "internal-claude-proxy",
      "auth": {
        "type": "command",
        "command": "corp-auth-helper get-token --scope llm"
      },
      "params": {
        "apiBase": "https://llm-proxy.corp.internal/v1"
      }
    }
  }
}

interface HarnessProviderTranslation {
  /** Environment variables to set */
  env: Record<string, string>;
  
  /** CLI arguments to prepend */
  args: string[];
  
  /** Config file content to write (for harnesses that need it) */
  configContent?: string;
  
  /** Config file path (if configContent is set) */
  configPath?: string;
  
  /** Whether a proxy is required */
  proxyRequired: boolean;
  
  /** If proxy is required, what transport should it expose */
  proxyExposedTransport?: TransportId;
}

configContent = `
[model_providers.amux]
name = "amux-proxy"
base_url = "${proxyBaseUrl}/v1/"
wire_api = "responses"
env_key = "AMUX_PROXY_KEY"
`;
configPath = path.join(os.homedir(), '.codex', 'config.toml');
args = ['--profile', 'amux'];

function buildOpenCodeConfig(resolved: ProviderConfig, proxyUrl?: string): string {
  const baseUrl = proxyUrl || resolved.params.apiBase;
  const npm = proxyUrl
    ? '@ai-sdk/openai-compatible'
    : resolveOpenCodeNpm(resolved.provider);
  
  return JSON.stringify({
    $schema: 'https://opencode.ai/config.json',
    provider: {
      amux: { npm, options: { baseURL: baseUrl } },
    },
    model: {
      default: `amux/${resolved.model}`,
    },
  });
}

import { resolveProvider, translateForHarness } from '@a5c-ai/agent-mux-core';

// Resolve from mixed sources
const config: ProviderConfig = resolveProvider({
  provider: 'bedrock',
  model: 'anthropic.claude-sonnet-4-20250514-v1:0',
  region: 'us-east-1',
  // ... other overrides
});

// Translate to harness-specific config
const translation: HarnessProviderTranslation = translateForHarness('claude', config);
console.log(translation.env);    // { CLAUDE_CODE_USE_BEDROCK: "1", AWS_REGION: "us-east-1", ... }
console.log(translation.args);   // []
console.log(translation.proxyRequired); // false

// Use with RunOptions
const runOptions: RunOptions = {
  agent: 'claude',
  prompt: 'hello',
  providerConfig: config,  // new field on RunOptions
};

interface RunOptions {
  // ... existing fields ...
  
  /** Provider configuration. When set, overrides adapter-default provider settings. */
  providerConfig?: ProviderConfig;
  
  /** Named provider profile to load. Merged with providerConfig if both set. */
  providerProfile?: string;
}

interface SubprocessAdapter {
  // ... existing methods ...
  
  /**
   * Translate a ProviderConfig into harness-specific env vars and args.
   * Returns proxyRequired=true if the harness cannot speak this provider natively.
   */
  translateProvider?(config: ProviderConfig): HarnessProviderTranslation;
}

# List models for a provider
amux models --provider bedrock
amux models --provider vertex --region us-central1

# List models available for a harness+provider combo
amux models --harness claude --provider bedrock

function translateModelId(canonical: string, provider: ProviderId): string {
  const entry = MODEL_TRANSLATION_TABLE[canonical];
  if (!entry) return canonical; // pass through unknown models
  return entry[provider] ?? canonical;
}

# Launch with Ollama, auto-pull model if not present
amux launch claude ollama --model qwen3:32b --with-proxy-if-needed

# List locally available models
amux models --provider ollama