chorus-cli 0.5.0 → 0.5.2

package/README.md

@@ -72,7 +72,7 @@ chorus run 4464 --super --qa 'John Doe'
 
 ## Docs
 
-Full documentation at [getchorusai.com/docs](https://getchorusai.com/docs)
+Full documentation at [choruscli.com/docs](https://choruscli.com/docs)
 
 ## License
 

package/index.js

@@ -62,7 +62,7 @@ async function getMachineId() {
 }
 
 // Run coder.py with real-time stderr streaming so progress is visible
-function runCoder(prompt) {
+function runCoder(prompt, { model } = {}) {
   return new Promise((resolve, reject) => {
     const env = { ...process.env };
     if (CONFIG.ai.chorusApiKey) {
@@ -72,7 +72,12 @@ function runCoder(prompt) {
     if (CONFIG.ai.machineId) {
       env.CHORUS_MACHINE_ID = CONFIG.ai.machineId;
     }
-    const proc = spawn(CONFIG.ai.venvPython, [CONFIG.ai.coderPath, '--prompt', prompt], {
+    if (isFreeModel(model)) {
+      env.CHORUS_FREE = '1';
+    }
+    const coderArgs = [CONFIG.ai.coderPath, '--prompt', prompt];
+    if (model) { coderArgs.push('--model', model); }
+    const proc = spawn(CONFIG.ai.venvPython, coderArgs, {
       cwd: process.cwd(),
       env,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -103,7 +108,7 @@ function runCoder(prompt) {
 }
 
 // Run qa.py with issue context on stdin, capture JSON from stdout
-function runQAChat(issue, enrichedDetails, qaName, useSuper = false) {
+function runQAChat(issue, enrichedDetails, qaName, useSuper = false, { model } = {}) {
   return new Promise((resolve, reject) => {
     const input = JSON.stringify({
       issue_number: issue.number,
@@ -117,6 +122,7 @@ function runQAChat(issue, enrichedDetails, qaName, useSuper = false) {
       args.push('--auth', CONFIG.teams.authPath);
     }
     if (useSuper) {args.push('--super');}
+    if (model) {args.push('--model', model);}
 
     const env = { ...process.env };
     if (CONFIG.ai.chorusApiKey) {
@@ -126,6 +132,9 @@ function runQAChat(issue, enrichedDetails, qaName, useSuper = false) {
     if (CONFIG.ai.machineId) {
       env.CHORUS_MACHINE_ID = CONFIG.ai.machineId;
     }
+    if (isFreeModel(model)) {
+      env.CHORUS_FREE = '1';
+    }
     if (CONFIG.messenger === 'slack' && CONFIG.slack.botToken) {
       env.SLACK_BOT_TOKEN = CONFIG.slack.botToken;
     }
@@ -202,7 +211,7 @@ const CONFIG = {
 // Use createProvider(CONFIG, issueArg) to get the right provider.
 
 // ===== AI ENRICHMENT =====
-async function enrichWithAI(issue) {
+async function enrichWithAI(issue, { model } = {}) {
   const prompt = `Analyze this GitHub issue and write questions for QA clarification.
 
 ISSUE DETAILS:
@@ -253,7 +262,7 @@ IMPORTANT: Output ONLY the message above. Do not include any preamble, thinking
     const openai = new OpenAI(openaiOpts);
 
     const response = await openai.chat.completions.create({
-      model: 'chorus-default',
+      model: model || 'chorus-default',
       max_tokens: 2000,
       messages: [
         {
@@ -262,7 +271,10 @@ IMPORTANT: Output ONLY the message above. Do not include any preamble, thinking
         }
       ]
     }, {
-      headers: { 'X-Chorus-Mode': 'enrich' },
+      headers: {
+        'X-Chorus-Mode': 'enrich',
+        ...(isFreeModel(model) && { 'X-Chorus-Free': '1' }),
+      },
     });
 
     if (response.usage) {
@@ -279,7 +291,7 @@ IMPORTANT: Output ONLY the message above. Do not include any preamble, thinking
 }
 
 // ===== CODE GENERATION =====
-async function generateCode(issue, enrichedDetails, qaResponse) {
+async function generateCode(issue, enrichedDetails, qaResponse, { model } = {}) {
   const tool = CONFIG.ai.codingTool;
 
   if (tool === 'coder') {
@@ -304,7 +316,7 @@ Instructions:
 
     console.log('🔨 Generating code with Coder agent...');
 
-    return await runCoder(prompt);
+    return await runCoder(prompt, { model });
   }
 
   // Fallback: kimi
@@ -423,7 +435,7 @@ async function getCodeRabbitReview(solution, issue, provider) {
   }
 }
 
-async function refineCode(solution, review) {
+async function refineCode(solution, review, { model } = {}) {
   const tool = CONFIG.ai.codingTool;
 
   if (tool === 'coder') {
@@ -448,7 +460,7 @@ Instructions:
 
     console.log('🔄 Refining code with Coder agent...');
 
-    return await runCoder(prompt);
+    return await runCoder(prompt, { model });
   }
 
   // Fallback: kimi
@@ -535,6 +547,10 @@ ${lintOutput.slice(0, 5000)}`;
 
 // ===== TOKEN LIMIT =====
 
+function isFreeModel(model) {
+  return model && FREE_MODELS.has(model);
+}
+
 function isTokenLimitError(err) {
   const msg = typeof err === 'string' ? err : (err?.message || err?.error || '');
   return msg.includes('token limit exceeded') || msg.includes('rate_limit_error');
@@ -545,19 +561,38 @@ async function fetchAccountEmail() {
   return null;
 }
 
+async function fetchCreditBalance(email) {
+  if (!email || !CONFIG.ai.chorusApiKey) return null;
+  try {
+    const baseUrl = CONFIG.ai.chorusApiUrl.replace(/\/v1\/?$/, '');
+    const res = await fetch(`${baseUrl}/tokens/balance?email=${encodeURIComponent(email)}&client=true`);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.tokenBalance ?? null;
+  } catch {
+    return null;
+  }
+}
+
 async function printTokenLimitMessage() {
   const email = await fetchAccountEmail();
-  const base = 'https://getchorusai.com/pricing';
+  const base = 'https://choruscli.com/pricing';
   const url = email ? `${base}?email=${encodeURIComponent(email)}` : base;
 
   console.error('\n⚠️  You\'ve run out of Chorus tokens for this month.\n');
+
+  const balance = await fetchCreditBalance(email);
+  if (balance !== null) {
+    console.error(`   Remaining credit balance: ${balance}\n`);
+  }
+
   console.error('   To keep going, purchase more tokens at:');
   console.error(`   ${url}\n`);
   console.error('   Or wait for your monthly allowance to reset.\n');
 }
 
 // ===== MAIN WORKFLOW =====
-async function processTicket(issueArg, { useSuper = false, skipQA = false, qaName: qaNameOverride } = {}) {
+async function processTicket(issueArg, { useSuper = false, skipQA = false, qaName: qaNameOverride, model } = {}) {
   try {
     console.log('🚀 Starting ticket processing...\n');
 
@@ -581,7 +616,25 @@ async function processTicket(issueArg, { useSuper = false, skipQA = false, qaNam
       efs(CONFIG.ai.venvPython, ['-m', 'pip', 'install', '-r', reqFile], { stdio: 'inherit' });
     }
 
-    // 0a. Verify no modified tracked files (untracked files like .chorus/ are fine)
+    // 0a. Check token balance — free models can proceed with zero balance
+    const usingFree = isFreeModel(model);
+    const email = await fetchAccountEmail();
+    const balance = await fetchCreditBalance(email);
+
+    if (balance !== null && balance <= 0 && !usingFree) {
+      await printTokenLimitMessage();
+      console.log('   Tip: Use --free to run with a free model\n');
+      process.exit(1);
+    }
+    if (usingFree) {
+      if (balance !== null && balance <= 0) {
+        console.log(`🆓 Using free model "${model}"\n`);
+      } else {
+        console.log(`🆓 Using free model "${model}"\n`);
+      }
+    }
+
+    // 0b. Verify no modified tracked files (untracked files like .chorus/ are fine)
     const { stdout: gitStatus } = await execPromise('git status --porcelain --untracked-files=no');
     if (gitStatus.trim()) {
       console.error('⚠️ Working directory has uncommitted changes. Commit or stash first:');
@@ -621,7 +674,7 @@ async function processTicket(issueArg, { useSuper = false, skipQA = false, qaNam
     console.log(`Found issue #${issue.number}: ${issue.title}\n`);
 
     // 2. Enrich with AI
-    const enrichedDetails = await enrichWithAI(issue);
+    const enrichedDetails = await enrichWithAI(issue, { model });
     console.log('Enrichment complete\n', enrichedDetails);
 
     // 3. Multi-turn QA conversation via qa.py
@@ -631,12 +684,13 @@ async function processTicket(issueArg, { useSuper = false, skipQA = false, qaNam
     } else {
       const qaName = qaNameOverride || await provider.getUserDisplayName(issue.user.login);
       console.log(`💬 Starting QA conversation with ${qaName?.login}...`);
-      const qaResult = await runQAChat(issue, enrichedDetails, qaName, useSuper);
+      const qaResult = await runQAChat(issue, enrichedDetails, qaName, useSuper, { model });
       qaResponse = qaResult.requirements;
 
       if (!qaResult.completed) {
-        if (isTokenLimitError(qaResult.error)) {
+        if (isTokenLimitError(qaResult.error) && !usingFree) {
           await printTokenLimitMessage();
+          console.log('   Tip: Use --free to run with a free model\n');
           process.exit(1);
         }
         console.warn('⚠️  QA chat did not complete successfully:', qaResult.error || 'unknown');
@@ -659,7 +713,7 @@ async function processTicket(issueArg, { useSuper = false, skipQA = false, qaNam
 
     for (let attempt = 1; attempt <= maxCodeAttempts; attempt++) {
       if (attempt === 1) {
-        solution = await generateCode(issue, enrichedDetails, qaResponse);
+        solution = await generateCode(issue, enrichedDetails, qaResponse, { model });
       } else {
         // Reprompt with explicit instruction that files must be written
         const retryPrompt = `You previously attempted to implement this issue but DID NOT write any files. Your task is NOT complete until you have actually created or modified files using write_file or edit_file.
@@ -680,13 +734,14 @@ ${qaResponse}
 CRITICAL: You MUST write code to actual files. Do not just describe changes — use write_file or edit_file to make them. If you are unsure where to make changes, explore the codebase first, then write the code.`;
 
         console.log(`🔁 Reprompting coder (attempt ${attempt}/${maxCodeAttempts})...`);
-        solution = await runCoder(retryPrompt);
+        solution = await runCoder(retryPrompt, { model });
       }
 
       if (solution.completed === false) {
         const errs = solution.errors || [solution.summary || ''];
-        if (errs.some(e => isTokenLimitError(e))) {
+        if (errs.some(e => isTokenLimitError(e)) && !usingFree) {
           printTokenLimitMessage();
+          console.log('   Tip: Use --free to run with a free model\n');
           process.exit(1);
         }
         console.error('❌ Code generation failed:', errs);
@@ -746,7 +801,7 @@ CRITICAL: You MUST write code to actual files. Do not just describe changes —
       while (review.needsChanges && iterations < maxIterations) {
         console.log(`Iteration ${iterations + 1}/${maxIterations}...`);
 
-        const refined = await refineCode(solution, review);
+        const refined = await refineCode(solution, review, { model });
 
         if (refined.completed === false) {
           console.warn('⚠️  Refinement had errors:', refined.errors);
@@ -824,8 +879,9 @@ Instructions:
 
       if (revised.completed === false) {
         const errs = revised.errors || [revised.summary || ''];
-        if (errs.some(e => isTokenLimitError(e))) {
+        if (errs.some(e => isTokenLimitError(e)) && !usingFree) {
           printTokenLimitMessage();
+          console.log('   Tip: Use --free to run with a free model\n');
           rl.close();
           process.exit(1);
         }
@@ -855,8 +911,9 @@ Instructions:
     console.log('\n✨ Ticket processing complete!');
 
   } catch (error) {
-    if (isTokenLimitError(error)) {
+    if (isTokenLimitError(error) && !isFreeModel(model)) {
       await printTokenLimitMessage();
+      console.log('   Tip: Use --free to run with a free model\n');
       process.exit(1);
     }
     console.error('❌ Error processing ticket:', error);
@@ -1252,21 +1309,91 @@ function printZEP() {
 const command = process.argv[2];
 const _envExists = require('fs').existsSync(path.join(os.homedir(), '.config', 'chorus', '.env'));
 
+const FREE_MODELS = new Set([
+  'deepseek', 'gemini', 'gemini-flash-lite', 'gpt-oss', 'gpt-nano',
+  'gpt-mini', 'gpt-5.2', 'gpt-4.1-mini', 'gpt-4o-mini', 'grok',
+  'kimi', 'glm', 'minimax', 'step'
+]);
+
+const PAID_MODELS = new Set([
+  'claude', 'chatgpt', 'qwen', 'llama', 'mistral', 'command-r'
+]);
+
+const ALLOWED_MODELS = new Set([...FREE_MODELS, ...PAID_MODELS]);
+
+const DEFAULT_FREE_MODEL = 'deepseek';
+
+function printModelTable(out = console.error) {
+  out('\n  Free models:');
+  out('  ┌─────────────────────┬──────────────────────────────────┐');
+  out('  │ Flag value          │ Model                            │');
+  out('  ├─────────────────────┼──────────────────────────────────┤');
+  out('  │ deepseek            │ DeepSeek V3.2          (default) │');
+  out('  │ gemini              │ Gemini 2.5 Flash                 │');
+  out('  │ gemini-flash-lite   │ Gemini 2.5 Flash Lite            │');
+  out('  │ gpt-oss             │ GPT-OSS 120B                     │');
+  out('  │ gpt-nano            │ GPT-5 Nano                       │');
+  out('  │ gpt-mini            │ GPT-5 Mini                       │');
+  out('  │ gpt-5.2             │ GPT-5.2                          │');
+  out('  │ gpt-4.1-mini        │ GPT-4.1 Mini                     │');
+  out('  │ gpt-4o-mini         │ GPT-4o Mini                      │');
+  out('  │ grok                │ Grok 4.1 Fast                    │');
+  out('  │ kimi                │ Kimi K2.5                        │');
+  out('  │ glm                 │ GLM-5                            │');
+  out('  │ minimax             │ Minimax M2.5                     │');
+  out('  │ step                │ Step 3.5 Flash                   │');
+  out('  └─────────────────────┴──────────────────────────────────┘');
+  out('\n  Paid models:');
+  out('  ┌─────────────────────┬──────────────────────────────────┐');
+  out('  │ Flag value          │ Model                            │');
+  out('  ├─────────────────────┼──────────────────────────────────┤');
+  out('  │ claude              │ Claude                           │');
+  out('  │ chatgpt             │ ChatGPT                          │');
+  out('  │ qwen                │ Qwen                             │');
+  out('  │ llama               │ Llama                            │');
+  out('  │ mistral             │ Mistral                          │');
+  out('  │ command-r           │ Command R                        │');
+  out('  └─────────────────────┴──────────────────────────────────┘');
+}
+
 function parseRunArgs() {
   const args = process.argv.slice(3);
-  const opts = { useSuper: false, skipQA: false, qaName: null, issueArg: null };
+  const opts = { useSuper: false, skipQA: false, qaName: null, issueArg: null, model: null, free: false };
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--super') {
       opts.useSuper = true;
     } else if (args[i] === '--skip-qa') {
       opts.skipQA = true;
+    } else if (args[i] === '--free') {
+      opts.free = true;
     } else if (args[i] === '--qa' && i + 1 < args.length) {
       opts.qaName = args[++i];
+    } else if (args[i] === '--model' && i + 1 < args.length) {
+      const val = args[++i];
+      if (!ALLOWED_MODELS.has(val)) {
+        console.error(`Error: invalid model "${val}". Allowed models: ${[...ALLOWED_MODELS].join(', ')}`);
+        printModelTable();
+        process.exit(1);
+      }
+      opts.model = val;
     } else if (!args[i].startsWith('--')) {
       opts.issueArg = args[i];
     }
   }
+
+  // --free: default to best free model, or validate that --model is free
+  if (opts.free) {
+    if (opts.model && !FREE_MODELS.has(opts.model)) {
+      console.error(`Error: "${opts.model}" is a paid model and cannot be used with --free.`);
+      printModelTable();
+      process.exit(1);
+    }
+    if (!opts.model) {
+      opts.model = DEFAULT_FREE_MODEL;
+    }
+  }
+
   return opts;
 }
 
@@ -1284,6 +1411,13 @@ if (command === 'setup') {
     const { issueArg, ...opts } = parseRunArgs();
     processTicket(issueArg, opts).catch(console.error);
   }
+} else if (command === 'models') {
+  console.log('\nChorus — Available Models');
+  printModelTable(console.log);
+  console.log('\nUsage:');
+  console.log('  chorus run 4464 --model deepseek    Use a specific model');
+  console.log('  chorus run 4464 --free              Use the best free model (DeepSeek V3.2)');
+  console.log('  chorus run 4464 --free --model kimi  Use a specific free model\n');
 } else if (command === 'zep') {
   printZEP()
 } else {
@@ -1302,10 +1436,14 @@ Chorus — AI-powered ticket automation (GitHub & Azure DevOps)
 
 Usage:
   chorus setup                       - Set up provider, Chorus auth + messenger
+  chorus models                      - List all available models (free & paid)
   chorus run                         - Process latest assigned issue
   chorus run 4464                    - Process specific issue by number
   chorus run <url>                   - Process issue from full URL (auto-detects provider)
   chorus run 4464 --super            - Use Opus 4.6 for QA evaluation
+  chorus run 4464 --model deepseek   - Use a specific model (see --free for free options)
+  chorus run 4464 --free             - Use the best free model (DeepSeek V3.2)
+  chorus run 4464 --free --model kimi - Use a specific free model
   chorus run 4464 --qa 'John Doe'    - Specify QA contact name for chat
   chorus run 4464 --skip-qa          - Skip QA conversation, go straight to coding
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chorus-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Automated ticket resolution with AI, Teams, and Slack integration",
   "main": "index.js",
   "bin": {

package/tools/coder.py

@@ -878,8 +878,13 @@ def run_prompt(client, prompt, chorus_context):
 def main():
     parser = argparse.ArgumentParser(description="Coder — AI coding agent powered by Claude via Chorus")
     parser.add_argument("-p", "--prompt", help="Run a single prompt headlessly and output JSON")
+    parser.add_argument("--model", help="Override the model sent to the proxy")
     args = parser.parse_args()
 
+    global MODEL
+    if args.model:
+        MODEL = args.model
+
     api_key = os.environ.get("CHORUS_API_KEY")
     if not api_key:
         print(f"{C.RED}Error: CHORUS_API_KEY not set. Run 'chorus setup' to configure.{C.RESET}", file=sys.stderr)
@@ -887,9 +892,15 @@ def main():
 
     base_url = os.environ.get("CHORUS_API_URL", "https://chorus-bad0f.web.app/v1")
     machine_id = os.environ.get("CHORUS_MACHINE_ID")
-    client_kwargs = {"api_key": api_key, "base_url": base_url}
+    chorus_free = os.environ.get("CHORUS_FREE", "")
+    default_headers = {}
     if machine_id:
-        client_kwargs["default_headers"] = {"X-Machine-Id": machine_id}
+        default_headers["X-Machine-Id"] = machine_id
+    if chorus_free:
+        default_headers["X-Chorus-Free"] = "1"
+    client_kwargs = {"api_key": api_key, "base_url": base_url}
+    if default_headers:
+        client_kwargs["default_headers"] = default_headers
     client = OpenAI(**client_kwargs)
     cwd = os.getcwd()
 

package/tools/qa.py

@@ -408,9 +408,15 @@ def run_qa_chat(issue_context, messenger, qa_name):
     api_key = os.environ.get("CHORUS_API_KEY")
     base_url = os.environ.get("CHORUS_API_URL", "https://chorus-bad0f.web.app/v1")
     machine_id = os.environ.get("CHORUS_MACHINE_ID")
-    client_kwargs = {"api_key": api_key, "base_url": base_url}
+    chorus_free = os.environ.get("CHORUS_FREE", "")
+    default_headers = {}
     if machine_id:
-        client_kwargs["default_headers"] = {"X-Machine-Id": machine_id}
+        default_headers["X-Machine-Id"] = machine_id
+    if chorus_free:
+        default_headers["X-Chorus-Free"] = "1"
+    client_kwargs = {"api_key": api_key, "base_url": base_url}
+    if default_headers:
+        client_kwargs["default_headers"] = default_headers
     client = OpenAI(**client_kwargs)
     conversation = []
     raw_responses = []
@@ -483,8 +489,14 @@ def main():
     parser.add_argument("--auth", help="Path to Teams auth state JSON (required for --messenger teams)")
     parser.add_argument("--qa", required=True, help="QA person's name")
     parser.add_argument("--super", action="store_true", help="Use Opus 4.6 instead of Sonnet")
+    parser.add_argument("--model", help="Override the model sent to the proxy")
     args = parser.parse_args()
 
+    # Override model if specified
+    global MODEL
+    if args.model:
+        MODEL = args.model
+
     # chorus_mode tells the proxy which model to use
     global QA_CHORUS_MODE
     if args.super: