gent-cli 28.0.0 → 29.0.0

package/README.md

@@ -24,7 +24,7 @@ Beyond a faithful git-like workflow, Gent adds:
 - **`gent undo` / `gent redo`** — a one-command safety net over an operation journal (friendlier than `git reflog`).
 - **`gent resolve`** — an interactive conflict resolver (ours / theirs / both / edit / AI).
 - **`gent summary`** — a repository health dashboard, plus **`gent log --graph`**.
-- **Direct local AI** (`gent chat`, `gent review`, `gent merge --ai`, `gent resolve --ai`) — low-latency OpenAI calls from the CLI with task-specific prompts. Configure once with `gent ai configure`.
+- **Direct local AI** (`gent chat`, `gent review`, `gent merge --ai`, `gent resolve --ai`) — low-latency OpenRouter calls from the CLI with task-specific prompts. Configure once with `gent ai configure`.
 - **Genti, your terminal mascot** — a mint one-eyed sky-jelly that *acts out* your workflow: it floats a file crate to the cloud on `gent push`, carries one home on `gent pull`, and reconciles two branches on `gent merge`. It plays once (in place, no scrollback spam) after a successful command. Meet it directly with `gent pet` (add `--loop` to keep it running; try `gent pet push|pull|merge|auth`). Set `GENT_NO_PET=1` (or run in CI / a non-interactive shell) to turn the celebrations off.
 
 See [docs/COMMANDS.md](docs/COMMANDS.md) for the full reference and
@@ -501,12 +501,14 @@ gent explain --staged             # explain currently staged changes
 ### Optional AI features
 
 AI calls run directly from the CLI. Run `gent ai configure` once to enter the
-OpenAI key through a masked prompt; Gent stores it locally with owner-only
+OpenRouter key through a masked prompt; Gent stores it locally with owner-only
 permissions. Fast task-specific prompts keep review, merge resolution, chat,
 and summaries concise.
 
 ```bash
-gent ai configure                 # configure OpenAI once on this computer
+gent ai configure                 # configure OpenRouter once on this computer
+gent ai configure <your-key>      # same, non-interactive (scripts, SSH)
+gent ai configure <your-key> --model vendor/model   # pin a different model
 gent commit --ai                  # suggest a commit message from the staged diff
 gent explain                      # narrate a diff instead of just printing it
 gent resolve                      # ours/theirs/both/AI/edit/skip per conflict hunk

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gent-cli",
-  "version": "28.0.0",
+  "version": "29.0.0",
   "description": "A modern, Git-like version control CLI with cloud sync, AI-powered superpowers (ask/review/docs/changelog), and zero-friction setup (gent setup/doctor/config).",
   "main": "src/index.js",
   "bin": {

package/src/commands/ai.js

@@ -1,7 +1,8 @@
 /**
  * AI Command - Manage and verify AI integration.
  *
- *   gent ai configure         → securely save a key for this computer
+ *   gent ai configure         → securely save your own key for this computer
+ *   gent ai configure <key>   → same, without the interactive prompt
  *   gent ai status            → show local AI status
  *   gent ai test              → make a tiny live request to confirm it works
  *   gent ai models            → show provider management information
@@ -13,10 +14,10 @@ const ora = require('ora');
 const ai = require('../utils/ai-service');
 const localAiConfig = require('../utils/local-ai-config');
 
-async function aiCommand(subcommand) {
+async function aiCommand(subcommand, key, options = {}) {
     const sub = (subcommand || 'status').toLowerCase();
     switch (sub) {
-        case 'configure': return configure();
+        case 'configure': return configure(key, options);
         case 'status': return status();
         case 'test': return test();
         case 'models': return models();
@@ -27,22 +28,39 @@ async function aiCommand(subcommand) {
     }
 }
 
-async function configure() {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        console.error(chalk.red('Run `gent ai configure` in an interactive terminal.'));
+async function configure(key, options = {}) {
+    // A key passed as an argument keeps `gent ai configure` usable in scripts,
+    // over SSH, and anywhere stdin is not a terminal.
+    let apiKey = typeof key === 'string' ? key.trim() : '';
+
+    if (!apiKey) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error(chalk.red('No terminal available for the masked prompt.'));
+            console.log(chalk.gray('  Pass the key directly: gent ai configure <your-openrouter-key>'));
+            process.exitCode = 1;
+            return;
+        }
+        ({ apiKey } = await inquirer.prompt([{
+            type: 'password',
+            name: 'apiKey',
+            message: 'OpenRouter API key:',
+            mask: '*',
+            validate: value => localAiConfig.validateApiKey(value) || 'Enter a valid OpenRouter key beginning with sk-or-v1-.',
+        }]));
+    }
+
+    if (!localAiConfig.validateApiKey(apiKey)) {
+        console.error(chalk.red('That is not a valid OpenRouter key. Keys begin with sk-or-v1-.'));
+        console.log(chalk.gray('  Create one at https://openrouter.ai/keys'));
         process.exitCode = 1;
         return;
     }
-    const { apiKey } = await inquirer.prompt([{
-        type: 'password',
-        name: 'apiKey',
-        message: 'OpenAI API key:',
-        mask: '*',
-        validate: value => localAiConfig.validateApiKey(value) || 'Enter a valid key beginning with sk-.',
-    }]);
-    const savedPath = await localAiConfig.saveApiKey(apiKey);
-    console.log(chalk.green('✓ Gent AI configured for this computer.'));
+
+    const savedPath = await localAiConfig.saveApiKey(apiKey, { model: options.model });
+    console.log(chalk.green('✓ Gent AI configured for this computer with your own key.'));
     console.log(chalk.gray(`  Stored locally in ${savedPath} with owner-only permissions.`));
+    console.log(chalk.gray(`  Model: ${await ai.resolveModel()}`));
+    console.log(chalk.gray('  Run `gent ai test` to verify it.'));
 }
 
 async function status() {
@@ -71,7 +89,7 @@ async function test() {
     try {
         const reply = await ai.complete({
             prompt: 'Reply with the single word: pong',
-            maxTokens: 8,
+            maxTokens: 32,
         });
         spinner.succeed(chalk.green(`✓ Reachable. Reply: "${reply}"`));
     } catch (err) {

package/src/commands/doctor.js

@@ -154,14 +154,14 @@ async function checkAiKey(probe) {
         return {
             name: 'AI service',
             status: 'pass',
-            detail: 'verified — OpenAI responded',
+            detail: 'verified — OpenRouter responded',
         };
     } catch (err) {
         return {
             name: 'AI service',
             status: 'fail',
             detail: err.message,
-            hint: 'Run `gent ai configure` to replace the key, or check the OpenAI project quota.',
+            hint: 'Run `gent ai configure` to replace the key, or check credits at https://openrouter.ai/credits.',
         };
     }
 }

package/src/index.js

@@ -369,8 +369,9 @@ program
     .action(doctorCommand);
 
 program
-    .command('ai [subcommand]')
+    .command('ai [subcommand] [key]')
     .description('Configure or inspect local AI (configure|status|test|models)')
+    .option('--model <id>', 'Pin an OpenRouter model id for this computer')
     .action(aiCommand);
 
 // ─── Platform-special (AI-powered) ──────────────────────

package/src/utils/ai-service.js

@@ -1,9 +1,14 @@
-/** Direct, low-latency OpenAI client for Gent's local AI commands. */
+/** Direct, low-latency OpenRouter client for Gent's local AI commands. */
 
 const axios = require('axios');
 
-const API_URL = 'https://api.openai.com/v1/responses';
-const DEFAULT_MODEL = 'gpt-4.1-mini';
+const API_URL = 'https://openrouter.ai/api/v1/chat/completions';
+const DEFAULT_MODEL = 'xiaomi/mimo-v2.5:nitro';
+// The default model reasons before answering, and those tokens come out of the
+// same budget as the reply. Too small a budget returns content: null with
+// finish_reason "length", so keep a floor and add headroom on every request.
+const MIN_OUTPUT_TOKENS = 256;
+const REASONING_HEADROOM = 512;
 
 const PROMPTS = Object.freeze({
     chat: 'Answer as a concise senior engineer. Use the repository context. Give the direct answer first.',
@@ -17,7 +22,9 @@ const PROMPTS = Object.freeze({
 });
 
 function getApiKey() {
-    return process.env.OPENAI_API_KEY || null;
+    // OPENAI_API_KEY stays readable so installs configured before the
+    // OpenRouter switch keep working until they reconfigure.
+    return process.env.OPENROUTER_API_KEY || process.env.OPENAI_API_KEY || null;
 }
 
 function getModel() {
@@ -30,7 +37,7 @@ function getApiUrl() {
 
 async function resolveKey() {
     const value = getApiKey();
-    return { value, source: value ? 'local CLI configuration' : 'unset' };
+    return { value, source: value ? 'local CLI configuration (OpenRouter)' : 'unset' };
 }
 
 async function resolveModel() {
@@ -51,6 +58,18 @@ function disabledHint() {
 
 function extractText(payload) {
     const chunks = [];
+    // OpenRouter / chat-completions shape.
+    for (const choice of payload?.choices || []) {
+        const content = choice?.message?.content;
+        if (typeof content === 'string') {
+            chunks.push(content);
+        } else if (Array.isArray(content)) {
+            for (const part of content) {
+                if (typeof part?.text === 'string') chunks.push(part.text);
+            }
+        }
+    }
+    // Responses-API shape, still accepted so a custom GENT_AI_API_URL works.
     for (const item of payload?.output || []) {
         if (item.type !== 'message') continue;
         for (const content of item.content || []) {
@@ -60,26 +79,40 @@ function extractText(payload) {
     return chunks.join('').trim();
 }
 
+function truncatedByBudget(payload) {
+    return (payload?.choices || []).some(choice => choice?.finish_reason === 'length');
+}
+
 async function complete({ prompt, system, profile = 'chat', maxTokens = 1024 }) {
     const apiKey = getApiKey();
     if (!apiKey) throw new Error(disabledHint());
     const instructions = [PROMPTS[profile], system].filter(Boolean).join('\n\n');
+    const budget = Math.max(MIN_OUTPUT_TOKENS, maxTokens) + REASONING_HEADROOM;
     try {
         const response = await axios.post(getApiUrl(), {
             model: getModel(),
-            input: prompt,
-            instructions,
-            max_output_tokens: maxTokens,
-            store: false,
+            messages: [
+                ...(instructions ? [{ role: 'system', content: instructions }] : []),
+                { role: 'user', content: prompt },
+            ],
+            max_tokens: budget,
+            // Keep reasoning models brief; ignored by models without reasoning.
+            reasoning: { effort: 'low' },
         }, {
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
+                'HTTP-Referer': 'https://github.com/gent-cli',
+                'X-Title': 'Gent CLI',
             },
-            timeout: 30000,
+            timeout: 60000,
         });
         const text = extractText(response.data);
-        if (!text) throw new Error('OpenAI returned an empty response');
+        if (!text) {
+            throw new Error(truncatedByBudget(response.data)
+                ? `Model "${getModel()}" used the whole ${budget}-token budget before replying. Raise it or set GENT_AI_MODEL to a lighter model.`
+                : `Model "${getModel()}" returned an empty response.`);
+        }
         return text;
     } catch (error) {
         throw enrichAiError(error);
@@ -90,10 +123,14 @@ function enrichAiError(error) {
     const status = error?.response?.status;
     const apiError = error?.response?.data?.error;
     const apiCode = typeof apiError === 'object' ? apiError?.code : null;
-    if (status === 401 || status === 403) return new Error('OpenAI rejected the configured CLI credential.');
-    if (status === 404) return new Error(`OpenAI rejected model "${getModel()}".`);
-    if (apiCode === 'insufficient_quota') return new Error('Gent AI quota is exhausted.');
-    if (status === 429) return new Error('Gent AI is busy. Retry in a moment.');
+    const apiType = typeof apiError === 'object' ? apiError?.type : null;
+    const quotaCodes = ['insufficient_quota', 'credit_balance_exhausted', 'billing_hard_limit_reached'];
+    if (status === 401 || status === 403) return new Error('OpenRouter rejected the configured CLI credential. Run `gent ai configure` with a valid key.');
+    if (status === 404) return new Error(`OpenRouter has no model "${getModel()}". Set GENT_AI_MODEL to a model id from https://openrouter.ai/models.`);
+    if (status === 402 || quotaCodes.includes(apiCode) || quotaCodes.includes(apiType)) {
+        return new Error('OpenRouter billing: this key has no credits left. Add credits at https://openrouter.ai/credits — the key itself is valid.');
+    }
+    if (status === 429) return new Error('Gent AI is rate limited. Retry in a moment.');
     if (apiError?.message) return new Error(`Gent AI failed: ${apiError.message}`);
     if (typeof apiError === 'string') return new Error(apiError);
     return error;
@@ -163,6 +200,8 @@ function briefSummary(value) {
 module.exports = {
     PROMPTS,
     DEFAULT_MODEL,
+    MIN_OUTPUT_TOKENS,
+    REASONING_HEADROOM,
     isEnabled,
     getModel,
     getApiKey,

package/src/utils/local-ai-config.js

@@ -3,17 +3,22 @@ const os = require('os');
 const path = require('path');
 const { GENT_DIR } = require('./constants');
 
+const KEY_NAME = 'OPENROUTER_API_KEY';
+// Written alongside the key so an install configured before the OpenRouter
+// switch does not keep pinning a stale OpenAI model id.
+const LEGACY_KEY_NAMES = ['OPENAI_API_KEY'];
+
 function getEnvPath() {
     return path.join(os.homedir(), GENT_DIR, '.env');
 }
 
 function validateApiKey(value) {
-    return typeof value === 'string' && /^sk-[A-Za-z0-9_-]{20,}$/.test(value.trim());
+    return typeof value === 'string' && /^sk-or-v1-[A-Za-z0-9]{32,}$/.test(value.trim());
 }
 
-async function saveApiKey(value) {
-    const apiKey = value.trim();
-    if (!validateApiKey(apiKey)) throw new Error('Enter a valid OpenAI API key beginning with sk-.');
+async function saveApiKey(value, { model } = {}) {
+    const apiKey = typeof value === 'string' ? value.trim() : '';
+    if (!validateApiKey(apiKey)) throw new Error('Enter a valid OpenRouter API key beginning with sk-or-v1-.');
 
     const envPath = getEnvPath();
     const directory = path.dirname(envPath);
@@ -21,19 +26,26 @@ async function saveApiKey(value) {
         if (error.code === 'ENOENT') return '';
         throw error;
     });
+    const managed = [KEY_NAME, ...LEGACY_KEY_NAMES];
     const lines = existing
         .split(/\r?\n/)
-        .filter(line => !/^\s*OPENAI_API_KEY\s*=/.test(line));
+        .filter(line => !managed.some(name => new RegExp(`^\\s*${name}\\s*=`).test(line)))
+        // Drop any model pinned for a previous provider; the service default wins.
+        .filter(line => !/^\s*GENT_AI_MODEL\s*=/.test(line));
     while (lines.length && lines[lines.length - 1] === '') lines.pop();
-    lines.push(`OPENAI_API_KEY=${apiKey}`);
+    lines.push(`${KEY_NAME}=${apiKey}`);
+    if (model) lines.push(`GENT_AI_MODEL=${model}`);
 
     await fs.mkdir(directory, { recursive: true, mode: 0o700 });
     const temporary = `${envPath}.tmp-${process.pid}`;
     await fs.writeFile(temporary, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
     await fs.rename(temporary, envPath);
     await fs.chmod(envPath, 0o600);
-    process.env.OPENAI_API_KEY = apiKey;
+    process.env[KEY_NAME] = apiKey;
+    for (const name of LEGACY_KEY_NAMES) delete process.env[name];
+    if (model) process.env.GENT_AI_MODEL = model;
+    else delete process.env.GENT_AI_MODEL;
     return envPath;
 }
 
-module.exports = { getEnvPath, validateApiKey, saveApiKey };
+module.exports = { getEnvPath, validateApiKey, saveApiKey, KEY_NAME };