From 3d207faac5ca3389572b88eb0881b2dca040c6fb Mon Sep 17 00:00:00 2001
From: Tam Nhu Tran <kaitran.ntt@gmail.com>
Date: Thu, 12 Feb 2026 03:26:20 +0700
Subject: [PATCH] feat(cliproxy): add composite variant type definitions

- Add CompositeVariantConfig, CompositeTierConfig interfaces
- Add CLIPROXY_SUPPORTED_PROVIDERS const array
- Extend ExecutorConfig with composite fields (isComposite, compositeTiers, compositeDefaultTier)
- Update variants record type to accept composite configs
- Export CLIProxyVariantConfig from types barrel

Refs #506
---
 src/cliproxy/types.ts              | 12 +++++++
 src/config/unified-config-types.ts | 58 ++++++++++++++++++++++++++++--
 src/types/index.ts                 |  1 +
 3 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/src/cliproxy/types.ts b/src/cliproxy/types.ts
index 3ecc56bb..06c83dc1 100644
--- a/src/cliproxy/types.ts
+++ b/src/cliproxy/types.ts
@@ -3,6 +3,8 @@
  * Types for CLIProxyAPI binary management and execution
  */
 
+import { CompositeTierConfig } from '../config/unified-config-types';
+
 /**
  * Supported operating systems
  */
@@ -181,6 +183,16 @@ export interface ExecutorConfig {
   pollInterval: number;
   /** Custom settings path for user-defined CLIProxy variants */
   customSettingsPath?: string;
+  /** Composite variant: true when mixing providers per tier */
+  isComposite?: boolean;
+  /** Composite variant: per-tier provider+model mappings */
+  compositeTiers?: {
+    opus: CompositeTierConfig;
+    sonnet: CompositeTierConfig;
+    haiku: CompositeTierConfig;
+  };
+  /** Composite variant: which tier is the default */
+  compositeDefaultTier?: 'opus' | 'sonnet' | 'haiku';
 }
 
 /**
diff --git a/src/config/unified-config-types.ts b/src/config/unified-config-types.ts
index 1cdc945f..621dc7d4 100644
--- a/src/config/unified-config-types.ts
+++ b/src/config/unified-config-types.ts
@@ -21,6 +21,21 @@
  */
 export const UNIFIED_CONFIG_VERSION = 8;
 
+/**
+ * Supported CLIProxy providers.
+ * Includes all OAuth-based providers supported by CLIProxyAPI.
+ */
+export const CLIPROXY_SUPPORTED_PROVIDERS = [
+  'gemini',
+  'codex',
+  'agy',
+  'qwen',
+  'iflow',
+  'kiro',
+  'ghcp',
+  'claude',
+] as const;
+
 /**
  * Account configuration (formerly in profiles.json).
  * Represents an isolated Claude instance via CLAUDE_CONFIG_DIR.
@@ -72,6 +87,43 @@ export interface CLIProxyVariantConfig {
   auth?: CLIProxyAuthConfig;
 }
 
+/**
+ * Per-tier provider+model mapping for composite variants.
+ */
+export interface CompositeTierConfig {
+  /** Provider for this tier */
+  provider: 'gemini' | 'codex' | 'agy' | 'qwen' | 'iflow' | 'kiro' | 'ghcp' | 'claude';
+  /** Model ID to use for this tier */
+  model: string;
+  /** Account nickname (optional, references oauth_accounts) */
+  account?: string;
+}
+
+/**
+ * Composite variant configuration.
+ * Mixes different providers per Claude tier (opus, sonnet, haiku) in a single profile.
+ * Uses CLIProxyAPI root endpoints (/v1/messages) for model-based routing
+ * instead of provider-specific endpoints (/api/provider/{provider}).
+ */
+export interface CompositeVariantConfig {
+  /** Discriminator for composite type */
+  type: 'composite';
+  /** Which tier ANTHROPIC_MODEL equals (default must be one of the three) */
+  default_tier: 'opus' | 'sonnet' | 'haiku';
+  /** Per-tier provider+model mapping */
+  tiers: {
+    opus: CompositeTierConfig;
+    sonnet: CompositeTierConfig;
+    haiku: CompositeTierConfig;
+  };
+  /** Path to settings file */
+  settings?: string;
+  /** Shared port for the composite profile */
+  port?: number;
+  /** Per-variant auth override (optional) */
+  auth?: CLIProxyAuthConfig;
+}
+
 /**
  * CLIProxy authentication configuration.
  * Allows customization of API key and management secret for CLIProxyAPI.
@@ -122,8 +174,8 @@ export interface CLIProxyConfig {
   oauth_accounts: OAuthAccounts;
   /** Built-in providers (read-only, for reference) */
   providers: readonly string[];
-  /** User-defined provider variants */
-  variants: Record<string, CLIProxyVariantConfig>;
+  /** User-defined provider variants (single-provider or composite) */
+  variants: Record<string, CLIProxyVariantConfig | CompositeVariantConfig>;
   /** Logging configuration (disabled by default) */
   logging?: CLIProxyLoggingConfig;
   /** Kiro: disable incognito browser mode (use normal browser to save credentials) */
@@ -672,7 +724,7 @@ export function createEmptyUnifiedConfig(): UnifiedConfig {
     cliproxy: {
       backend: 'plus',
       oauth_accounts: {},
-      providers: ['gemini', 'codex', 'agy', 'qwen', 'iflow', 'kiro', 'ghcp'],
+      providers: [...CLIPROXY_SUPPORTED_PROVIDERS],
       variants: {},
       logging: {
         enabled: false,
diff --git a/src/types/index.ts b/src/types/index.ts
index 5ed78646..4adba8b4 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -12,6 +12,7 @@ export type {
   EnvValue,
   ProfileMetadata,
   ProfilesRegistry,
+  CLIProxyVariantConfig,
   CLIProxyVariantsConfig,
 } from './config';
 export { isConfig, isSettings } from './config';