@covibes/zeroshot 5.2.1 → 5.3.0

package/cluster-templates/base-templates/single-worker.json

@@ -2,12 +2,15 @@
   "name": "Single Worker",
   "description": "One agent executes and completes. For TRIVIAL tasks and simple INQUIRY.",
   "params": {
-    "worker_model": {
+    "worker_level": {
       "type": "string",
-      "enum": ["haiku", "sonnet", "opus"],
-      "default": "haiku"
+      "enum": ["level1", "level2", "level3"],
+      "default": "level1"
+    },
+    "max_tokens": {
+      "type": "number",
+      "default": 50000
     },
-    "max_tokens": { "type": "number", "default": 50000 },
     "timeout": {
       "type": "number",
       "default": 0,
@@ -23,33 +26,38 @@
     {
       "id": "worker",
       "role": "implementation",
-      "model": "{{worker_model}}",
+      "modelLevel": "{{worker_level}}",
       "timeout": "{{timeout}}",
       "prompt": {
         "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an agent handling a {{task_type}} task.\n\n## TASK TYPE: {{task_type}}\n\n{{#if task_type == 'INQUIRY'}}\nThis is an INQUIRY - exploration and understanding only.\n- Answer questions about the codebase\n- Explore files and explain how things work\n- DO NOT make any changes\n- Provide clear, accurate information\n{{/if}}\n\n{{#if task_type == 'TASK'}}\nThis is a TRIVIAL TASK - quick execution.\n- Straightforward, well-defined action\n- Quick to complete (< 15 minutes)\n- Low risk of breaking existing functionality\n- Execute efficiently, verify it works, done\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nThis is a TRIVIAL DEBUG - simple fix.\n- Obvious issue with clear solution\n- Fix the root cause, not symptoms\n- Verify the fix works\n{{/if}}"
       },
       "contextStrategy": {
-        "sources": [{ "topic": "ISSUE_OPENED", "limit": 1 }],
+        "sources": [
+          {
+            "topic": "ISSUE_OPENED",
+            "limit": 1
+          }
+        ],
         "format": "chronological",
         "maxTokens": "{{max_tokens}}"
       },
-      "triggers": [{ "topic": "ISSUE_OPENED", "action": "execute_task" }],
+      "triggers": [
+        {
+          "topic": "ISSUE_OPENED",
+          "action": "execute_task"
+        }
+      ],
       "hooks": {
         "onComplete": {
           "action": "publish_message",
           "config": {
             "topic": "CLUSTER_COMPLETE",
-            "content": { "text": "Task completed." }
+            "content": {
+              "text": "Task completed."
+            }
           }
         }
       }
-    },
-    {
-      "id": "completion-detector",
-      "role": "orchestrator",
-      "model": "haiku",
-      "timeout": 0,
-      "triggers": [{ "topic": "CLUSTER_COMPLETE", "action": "stop_cluster" }]
     }
   ]
 }

package/cluster-templates/base-templates/worker-validator.json

@@ -2,18 +2,24 @@
   "name": "Worker + Validator",
   "description": "Worker implements, validator checks, rejection loop. For SIMPLE tasks.",
   "params": {
-    "worker_model": {
+    "worker_level": {
       "type": "string",
-      "enum": ["haiku", "sonnet", "opus"],
-      "default": "sonnet"
+      "enum": ["level1", "level2", "level3"],
+      "default": "level2"
     },
-    "validator_model": {
+    "validator_level": {
       "type": "string",
-      "enum": ["haiku", "sonnet", "opus"],
-      "default": "sonnet"
+      "enum": ["level1", "level2", "level3"],
+      "default": "level2"
+    },
+    "max_iterations": {
+      "type": "number",
+      "default": 3
+    },
+    "max_tokens": {
+      "type": "number",
+      "default": 100000
     },
-    "max_iterations": { "type": "number", "default": 3 },
-    "max_tokens": { "type": "number", "default": 100000 },
     "timeout": {
       "type": "number",
       "default": 0,
@@ -29,21 +35,31 @@
     {
       "id": "worker",
       "role": "implementation",
-      "model": "{{worker_model}}",
+      "modelLevel": "{{worker_level}}",
       "timeout": "{{timeout}}",
       "prompt": {
         "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a SIMPLE {{task_type}} task.\n\n## FIRST ITERATION\n\n{{#if task_type == 'TASK'}}\nImplement the requested feature/change:\n- Well-defined scope (one feature, one fix)\n- Standard patterns apply\n- Complete the implementation fully\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nInvestigate and fix the issue:\n- Reproduce the problem\n- Find the root cause (not just symptoms)\n- Apply the fix\n- Verify it works\n{{/if}}\n\n{{#if task_type == 'INQUIRY'}}\nResearch and provide detailed answers:\n- Explore relevant code and documentation\n- Explain how things work\n- Provide accurate, complete information\n{{/if}}\n\n## SUBSEQUENT ITERATIONS (after rejection)\n\nYou are being called back because validators REJECTED your implementation. This is NOT a minor issue.\n\n### FIX LIKE A SENIOR ENGINEER\n\n1. **STOP AND UNDERSTAND FIRST**\n   - Read ALL VALIDATION_RESULT messages completely\n   - Understand WHY each issue exists, not just WHAT it is\n   - Trace the root cause - don't patch symptoms\n\n2. **FIX PROPERLY - NO SHORTCUTS**\n   - Fix the ACTUAL problem, not the error message\n   - If your approach was wrong, redesign it - don't add band-aids\n   - Consider architectural implications of your fix\n   - A senior dev would be embarrassed to submit a half-fix\n\n3. **VERIFY YOUR FIX**\n   - Test your changes actually work\n   - Check you didn't break anything else\n   - If unsure, investigate before committing\n\n### MINDSET\n- Validators are senior engineers reviewing your code\n- They found REAL problems - take them seriously\n- Shortcuts will be caught and rejected again"
       },
       "contextStrategy": {
         "sources": [
-          { "topic": "ISSUE_OPENED", "limit": 1 },
-          { "topic": "VALIDATION_RESULT", "since": "last_task_end", "limit": 3 }
+          {
+            "topic": "ISSUE_OPENED",
+            "limit": 1
+          },
+          {
+            "topic": "VALIDATION_RESULT",
+            "since": "last_task_end",
+            "limit": 3
+          }
         ],
         "format": "chronological",
         "maxTokens": "{{max_tokens}}"
       },
       "triggers": [
-        { "topic": "ISSUE_OPENED", "action": "execute_task" },
+        {
+          "topic": "ISSUE_OPENED",
+          "action": "execute_task"
+        },
         {
           "topic": "VALIDATION_RESULT",
           "logic": {
@@ -69,7 +85,7 @@
     {
       "id": "validator",
       "role": "validator",
-      "model": "{{validator_model}}",
+      "modelLevel": "{{validator_level}}",
       "timeout": "{{timeout}}",
       "outputFormat": "json",
       "jsonSchema": {
@@ -85,24 +101,37 @@
           },
           "errors": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Issues found (empty if approved)"
           }
         },
         "required": ["approved", "summary", "errors"]
       },
       "prompt": {
-        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a validator for a SIMPLE {{task_type}} task.\n\n## 🔴 VERIFICATION PROTOCOL (REQUIRED - PREVENTS FALSE CLAIMS)\n\nBefore making ANY claim about missing functionality or code issues:\n\n1. **SEARCH FIRST** - Use Glob to find ALL relevant files\n2. **READ THE CODE** - Use Read to inspect actual implementation\n3. **GREP FOR PATTERNS** - Use Grep to search for specific code (function names, endpoints, etc.)\n\n**NEVER claim something doesn't exist without FIRST searching for it.**\n\nThe worker may have implemented features in different files than originally planned. If you claim '/api/metrics endpoint is missing' without searching, you may miss that it exists in 'server/routes/health.ts' instead of 'server/routes/api.ts'.\n\n### Example Verification Flow:\n```\n1. Claim: 'Missing error handling for network failures'\n2. BEFORE claiming → Grep for 'catch', 'error', 'try' in relevant files\n3. BEFORE claiming → Read the actual implementation\n4. ONLY IF NOT FOUND → Add to errors array\n```\n\n## VALIDATION CRITERIA\n\n**APPROVE** if:\n- Core functionality works as requested\n- Implementation is correct and complete\n- No obvious bugs or critical issues\n\n**REJECT** if:\n- Major functionality is missing or broken (VERIFIED by searching)\n- Implementation doesn't match requirements (VERIFIED by reading code)\n- Critical bugs present (VERIFIED by inspection)\n\n## TASK TYPE: {{task_type}}\n\n{{#if task_type == 'TASK'}}\nVerify the feature/change works correctly.\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nVerify the bug is actually fixed at root cause.\n{{/if}}\n\n{{#if task_type == 'INQUIRY'}}\nVerify the information is accurate and complete.\n{{/if}}\n\nFor SIMPLE tasks, don't nitpick. Focus on: Does it work and meet requirements?"
+        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a validator for a SIMPLE {{task_type}} task.\n\n## 🔴 VERIFICATION PROTOCOL (REQUIRED - PREVENTS FALSE CLAIMS)\n\nBefore making ANY claim about missing functionality or code issues:\n\n1. **SEARCH FIRST** - Use Glob to find ALL relevant files\n2. **READ THE CODE** - Use Read to inspect actual implementation\n3. **GREP FOR PATTERNS** - Use Grep to search for specific code (function names, endpoints, etc.)\n\n**NEVER claim something doesn't exist without FIRST searching for it.**\n\nThe worker may have implemented features in different files than originally planned. If you claim '/api/metrics endpoint is missing' without searching, you may miss that it exists in 'server/routes/health.ts' instead of 'server/routes/api.ts'.\n\n### Example Verification Flow:\n```\n1. Claim: 'Missing error handling for network failures'\n2. BEFORE claiming → Grep for 'catch', 'error', 'try' in relevant files\n3. BEFORE claiming → Read the actual implementation\n4. ONLY IF NOT FOUND → Add to errors array\n```\n\n## VALIDATION CRITERIA\n\n**APPROVE** if:\n- Core functionality works as requested\n- Implementation is correct and complete\n- No obvious bugs or critical issues\n\n**REJECT** if:\n- Major functionality is missing or broken (VERIFIED by searching)\n- Implementation doesn't match requirements (VERIFIED by reading code)\n- Critical bugs present (VERIFIED by inspection)\n\n## TASK TYPE: {{task_type}}\n\n{{#if task_type == 'TASK'}}\nVerify the feature/change works correctly.\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nVerify the bug is actually fixed at root cause.\n{{/if}}\n\n{{#if task_type == 'INQUIRY'}}\nVerify the information is accurate and complete.\n{{/if}}\n\nFor SIMPLE tasks, don't nitpick. Focus on: Does it work and meet requirements?\n\n## 🔴 DEBUGGING METHODOLOGY CHECK\n\nBefore approving, verify the worker didn't take shortcuts:\n\n### Ad Hoc Fix Detection\n- Did worker fix ONE instance? → Grep for similar patterns. If N > 1 exists, REJECT.\n- Example: Fixed null check in `auth.ts:42`? → `grep -r \"similar pattern\" .` - are there others?\n\n### Root Cause vs Symptom\n- Did worker add a workaround? → Find the ACTUAL bug. If workaround hides real issue, REJECT.\n- Example: Added `|| []` fallback? → WHY is it undefined? Fix THAT.\n\n### Lazy Debugging Red Flags (INSTANT REJECT)\n- Worker suggests \"restart the service\" → REJECT (hides the bug)\n- Worker suggests \"clear the cache\" → REJECT (hides the bug)\n- Worker says \"works on my machine\" → REJECT (not a fix)\n- Worker blames the test → REJECT unless they PROVE test is wrong with evidence"
       },
       "contextStrategy": {
         "sources": [
-          { "topic": "ISSUE_OPENED", "limit": 1 },
-          { "topic": "IMPLEMENTATION_READY", "limit": 1 }
+          {
+            "topic": "ISSUE_OPENED",
+            "limit": 1
+          },
+          {
+            "topic": "IMPLEMENTATION_READY",
+            "limit": 1
+          }
         ],
         "format": "chronological",
         "maxTokens": "{{max_tokens}}"
       },
-      "triggers": [{ "topic": "IMPLEMENTATION_READY", "action": "execute_task" }],
+      "triggers": [
+        {
+          "topic": "IMPLEMENTATION_READY",
+          "action": "execute_task"
+        }
+      ],
       "hooks": {
         "onComplete": {
           "action": "publish_message",
@@ -118,22 +147,6 @@
           }
         }
       }
-    },
-    {
-      "id": "completion-detector",
-      "role": "orchestrator",
-      "model": "haiku",
-      "timeout": 0,
-      "triggers": [
-        {
-          "topic": "VALIDATION_RESULT",
-          "logic": {
-            "engine": "javascript",
-            "script": "const lastPush = ledger.findLast({ topic: 'IMPLEMENTATION_READY' });\nif (!lastPush) return false;\nconst result = ledger.findLast({ topic: 'VALIDATION_RESULT', since: lastPush.timestamp });\nreturn result?.content?.data?.approved === true || result?.content?.data?.approved === 'true';"
-          },
-          "action": "stop_cluster"
-        }
-      ]
     }
   ]
 }

package/cluster-templates/conductor-bootstrap.json

@@ -1,11 +1,12 @@
 {
   "name": "Two-Tier Conductor (Complexity × TaskType)",
-  "description": "Cost-optimized conductor: Haiku junior for 2D classification (complexity + taskType), Sonnet senior for UNCERTAIN tasks. Routes to appropriate cluster config via helpers.getConfig().",
+  "description": "Cost-optimized conductor: level1 junior for 2D classification (complexity + taskType), level2 senior for UNCERTAIN tasks. Routes to appropriate cluster config via helpers.getConfig().",
   "agents": [
     {
       "id": "junior-conductor",
       "role": "conductor",
-      "model": "haiku",
+      "modelLevel": "level1",
+      "useDirectApi": true,
       "outputFormat": "json",
       "jsonSchema": {
         "type": "object",
@@ -28,7 +29,7 @@
         "required": ["complexity", "taskType", "reasoning"]
       },
       "prompt": {
-        "system": "You are the JUNIOR CONDUCTOR (Haiku) - fast, cost-efficient task classification.\n\n## Your Job\nClassify tasks on TWO dimensions: COMPLEXITY and TASK TYPE.\n\n## COMPLEXITY (how hard/risky)\n\n**TRIVIAL** - One command, one file, mechanical\n**SIMPLE** - One concern, straightforward\n**STANDARD** - Multi-file, needs planning\n**CRITICAL** - High risk (auth, payments, security, production)\n**UNCERTAIN** - Escalate to senior conductor\n\n## TASK TYPE (what kind of action)\n\n**INQUIRY** - Questions, exploration, understanding\n- \"How does X work?\", \"What files handle Y?\", \"Explain Z\"\n- NO changes made, just gathering information\n\n**TASK** - Implement something new\n- \"Add feature X\", \"Create Y\", \"Implement Z\"\n- Building new functionality\n\n**DEBUG** - Fix something broken\n- \"Why is X failing?\", \"Fix bug in Y\", \"Debug Z\"\n- Investigating and fixing existing issues\n\n## Output Format\n\n```json\n{\n  \"complexity\": \"TRIVIAL|SIMPLE|STANDARD|CRITICAL|UNCERTAIN\",\n  \"taskType\": \"INQUIRY|TASK|DEBUG\",\n  \"reasoning\": \"Brief explanation\"\n}\n```\n\n## Examples\n\n\"How does auth work?\" → SIMPLE, INQUIRY\n\"Add rate limiting\" → STANDARD, TASK\n\"Fix null pointer bug\" → SIMPLE, DEBUG\n\"Why is the API slow?\" → STANDARD, DEBUG\n\"Deploy to AWS\" → CRITICAL, TASK\n\"terraform plan\" → SIMPLE, TASK\n\"What files handle routing?\" → TRIVIAL, INQUIRY\n\n## Critical Rules\n\n1. ALWAYS output both dimensions\n2. INQUIRY = read-only, TASK = create new, DEBUG = fix broken\n3. complexity=UNCERTAIN only when truly ambiguous\n\nTask: {{ISSUE_OPENED.content.text}}"
+        "system": "You are the JUNIOR CONDUCTOR - fast task classification.\n\n## Your Job\nClassify the task on TWO dimensions.\n\n## COMPLEXITY (pick ONE)\n- TRIVIAL - One command, one file, mechanical\n- SIMPLE - One concern, straightforward\n- STANDARD - Multi-file, needs planning\n- CRITICAL - High risk (auth, payments, security, production)\n- UNCERTAIN - Escalate to senior conductor\n\n## TASK TYPE (pick ONE)\n- INQUIRY - Questions, exploration, read-only\n- TASK - Implement something new\n- DEBUG - Fix something broken\n\n## Examples\n\nTask: \"How does auth work?\"\n```json\n{\"complexity\": \"SIMPLE\", \"taskType\": \"INQUIRY\", \"reasoning\": \"Asking about existing code\"}\n```\n\nTask: \"Add rate limiting\"\n```json\n{\"complexity\": \"STANDARD\", \"taskType\": \"TASK\", \"reasoning\": \"New feature, multiple files\"}\n```\n\nTask: \"Fix null pointer bug\"\n```json\n{\"complexity\": \"SIMPLE\", \"taskType\": \"DEBUG\", \"reasoning\": \"Fixing broken code\"}\n```\n\n## Critical Rules\n1. Output ONLY valid JSON - no other text\n2. complexity must be EXACTLY one of: TRIVIAL, SIMPLE, STANDARD, CRITICAL, UNCERTAIN\n3. taskType must be EXACTLY one of: INQUIRY, TASK, DEBUG\n\nTask: {{ISSUE_OPENED.content.text}}"
       },
       "contextStrategy": {
         "sources": [{ "topic": "ISSUE_OPENED", "limit": 1 }],
@@ -58,7 +59,8 @@
     {
       "id": "senior-conductor",
       "role": "conductor",
-      "model": "sonnet",
+      "modelLevel": "level2",
+      "useDirectApi": true,
       "outputFormat": "json",
       "jsonSchema": {
         "type": "object",
@@ -81,7 +83,7 @@
         "required": ["complexity", "taskType", "reasoning"]
       },
       "prompt": {
-        "system": "You are the SENIOR CONDUCTOR - expert task analyzer for ambiguous tasks.\n\nThe junior conductor was uncertain. Analyze deeply and make a definitive classification.\n\n## COMPLEXITY\n\n**TRIVIAL** - One command/file, mechanical, no risk\n**SIMPLE** - One concern, straightforward\n**STANDARD** - Multi-file, needs planning\n**CRITICAL** - High risk (auth/payments/security/production)\n\n## TASK TYPE\n\n**INQUIRY** - Questions, exploration (read-only)\n**TASK** - Implement something new (create)\n**DEBUG** - Fix something broken (investigate + fix)\n\n## Decision Rules\n\n1. YOU MUST DECIDE - no UNCERTAIN output\n2. When in doubt about complexity, go ONE LEVEL HIGHER\n3. INQUIRY vs TASK vs DEBUG based on intent, not keywords\n4. Consider: Is user asking a question? Building new? Fixing broken?\n\nJunior classified as UNCERTAIN. Original task and reasoning follow."
+        "system": "You are the SENIOR CONDUCTOR - expert task analyzer.\n\nThe junior conductor was uncertain. Make a definitive classification.\n\n## COMPLEXITY (pick ONE - no UNCERTAIN allowed)\n- TRIVIAL - One command/file, mechanical\n- SIMPLE - One concern, straightforward\n- STANDARD - Multi-file, needs planning\n- CRITICAL - High risk (auth/payments/security/production)\n\n## TASK TYPE (pick ONE)\n- INQUIRY - Questions, exploration (read-only)\n- TASK - Implement something new\n- DEBUG - Fix something broken\n\n## Example Output\n```json\n{\"complexity\": \"STANDARD\", \"taskType\": \"TASK\", \"reasoning\": \"Multiple files involved, new feature\"}\n```\n\n## Rules\n1. Output ONLY valid JSON - no other text\n2. YOU MUST DECIDE - pick exactly one value for each field\n3. When in doubt, go ONE LEVEL HIGHER for complexity\n\nJunior was uncertain. Original task follows."
       },
       "contextStrategy": {
         "sources": [

package/lib/docker-config.js

@@ -18,6 +18,9 @@ const MOUNT_PRESETS = {
   kube: { host: '~/.kube', container: '$HOME/.kube', readonly: true },
   terraform: { host: '~/.terraform.d', container: '$HOME/.terraform.d', readonly: false },
   gcloud: { host: '~/.config/gcloud', container: '$HOME/.config/gcloud', readonly: true },
+  claude: { host: '~/.claude', container: '$HOME/.claude', readonly: true },
+  codex: { host: '~/.config/codex', container: '$HOME/.config/codex', readonly: true },
+  gemini: { host: '~/.config/gemini', container: '$HOME/.config/gemini', readonly: true },
 };
 
 /**
@@ -76,7 +79,9 @@ function resolveMounts(config, options = {}) {
       };
     }
 
-    throw new Error(`Invalid mount config: ${JSON.stringify(item)}. Use preset name or {host, container, readonly?}`);
+    throw new Error(
+      `Invalid mount config: ${JSON.stringify(item)}. Use preset name or {host, container, readonly?}`
+    );
   });
 }
 

package/lib/provider-detection.js

@@ -0,0 +1,59 @@
+const { execSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function commandExists(command) {
+  if (!command) return false;
+  if (command.includes(path.sep)) {
+    return fs.existsSync(command);
+  }
+  try {
+    execSync(`command -v ${command}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCommandPath(command) {
+  if (!command) return null;
+  if (command.includes(path.sep)) {
+    return fs.existsSync(command) ? command : null;
+  }
+  try {
+    const output = execSync(`command -v ${command}`, { encoding: 'utf8', stdio: 'pipe' });
+    return output.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function getHelpOutput(command, args = []) {
+  if (!commandExists(command)) return '';
+
+  const attempt = (flag) => {
+    const result = spawnSync(command, [...args, flag], { encoding: 'utf8' });
+    const output = `${result.stdout || ''}${result.stderr || ''}`;
+    return output.trim();
+  };
+
+  const help = attempt('--help');
+  if (help) return help;
+
+  const alt = attempt('-h');
+  return alt || '';
+}
+
+function getVersionOutput(command, args = []) {
+  if (!commandExists(command)) return '';
+  const result = spawnSync(command, [...args, '--version'], { encoding: 'utf8' });
+  const output = `${result.stdout || ''}${result.stderr || ''}`;
+  return output.trim();
+}
+
+module.exports = {
+  commandExists,
+  getCommandPath,
+  getHelpOutput,
+  getVersionOutput,
+};

package/lib/provider-names.js

@@ -0,0 +1,56 @@
+const PROVIDER_ALIASES = {
+  anthropic: 'claude',
+  openai: 'codex',
+  google: 'gemini',
+  claude: 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+};
+
+const VALID_PROVIDERS = ['claude', 'codex', 'gemini'];
+
+function normalizeProviderName(name) {
+  if (!name || typeof name !== 'string') return name;
+  const normalized = PROVIDER_ALIASES[name.toLowerCase()];
+  return normalized || name;
+}
+
+function normalizeProviderSettings(providerSettings) {
+  if (
+    !providerSettings ||
+    typeof providerSettings !== 'object' ||
+    Array.isArray(providerSettings)
+  ) {
+    return providerSettings;
+  }
+
+  const normalized = {};
+  const entries = Object.entries(providerSettings);
+  const aliasFirst = entries.sort(([left], [right]) => {
+    const leftIsCanonical = normalizeProviderName(left) === left;
+    const rightIsCanonical = normalizeProviderName(right) === right;
+    if (leftIsCanonical === rightIsCanonical) return 0;
+    return leftIsCanonical ? 1 : -1;
+  });
+
+  for (const [key, value] of aliasFirst) {
+    const canonical = normalizeProviderName(key);
+    if (!VALID_PROVIDERS.includes(canonical)) {
+      normalized[key] = value;
+      continue;
+    }
+    normalized[canonical] = {
+      ...(normalized[canonical] || {}),
+      ...(value || {}),
+    };
+  }
+
+  return normalized;
+}
+
+module.exports = {
+  PROVIDER_ALIASES,
+  VALID_PROVIDERS,
+  normalizeProviderName,
+  normalizeProviderSettings,
+};