@openagents-org/agent-launcher 0.2.173 → 0.2.176

package/icons/commandcode.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 137 137" role="img" style="flex:none;line-height:1">
+<title>Command Code</title>
+<path d="m0 66.7959c0-31.4879 0-47.2318 9.78204-57.01386 9.78206-9.78204 25.52596-9.78204 57.01396-9.78204h2.5357c31.4883 0 47.2323 0 57.0143 9.78204 9.782 9.78206 9.782 25.52596 9.782 57.01396v2.5357c0 31.4883 0 47.2323-9.782 57.0143s-25.526 9.782-57.0144 9.782h-2.5357c-31.4879 0-47.2318 0-57.01386-9.782-9.78204-9.782-9.78204-25.526-9.78204-57.0144z" fill="#000"/><path d="m69.3317 5.56633h-2.5357c-15.9014 0-27.2674.01182-35.905 1.17312-8.4775 1.13977-13.4886 3.29415-17.173 6.97855s-5.83878 8.6955-6.97855 17.173c-1.1613 8.6376-1.17312 20.0036-1.17312 35.9049v2.5357c0 15.9014.01182 27.2674 1.17312 35.9054 1.13977 8.477 3.29415 13.488 6.97855 17.173 3.6844 3.684 8.6955 5.838 17.173 6.978 8.6376 1.161 20.0036 1.173 35.9049 1.173h2.5357c15.9014 0 27.2674-.012 35.9054-1.173 8.477-1.14 13.488-3.294 17.173-6.978 3.684-3.685 5.838-8.696 6.978-17.173 1.161-8.638 1.173-20.004 1.173-35.9053v-2.5357c0-15.9014-.012-27.2674-1.173-35.905-1.14-8.4775-3.294-13.4886-6.978-17.173-3.685-3.6844-8.696-5.83878-17.173-6.97855-8.638-1.1613-20.004-1.17312-35.9053-1.17312zm-59.54966 4.21571c-9.78204 9.78206-9.78204 25.52596-9.78204 57.01386v2.5357c0 31.4884 0 47.2324 9.78204 57.0144 9.78206 9.782 25.52596 9.782 57.01386 9.782h2.5357c31.4884 0 47.2324 0 57.0144-9.782s9.782-25.526 9.782-57.0143v-2.5357c0-31.488 0-47.2319-9.782-57.01396-9.782-9.78204-25.526-9.78204-57.0143-9.78204h-2.5357c-31.488 0-47.2319 0-57.01396 9.78204z" fill="#000" fill-rule="evenodd"/><path d="m93.6604 26.1784c-8.982 0-16.2887 7.3067-16.2887 16.2888v6.9809h-18.6158v-6.9809c0-8.9821-7.3067-16.2888-16.2887-16.2888-8.9821 0-16.2888 7.3067-16.2888 16.2888s7.3067 16.2887 16.2888 16.2887h6.9809v18.6158h-6.9809c-8.9821 0-16.2888 7.3067-16.2888 16.2888 0 8.9825 7.3067 16.2885 16.2888 16.2885 8.982 0 16.2887-7.306 16.2887-16.2885v-6.981h18.6158v6.981c0 8.9825 7.3067 16.2885 16.2887 16.2885 8.9826 0 16.2886-7.306 16.2886-16.2885 0-8.9821-7.306-16.2888-16.2886-16.2888h-6.9809v-18.6158h6.9809c8.9826 0 16.2886-7.3066 16.2886-16.2887s-7.306-16.2888-16.2886-16.2888zm-6.9809 23.2697v-6.9809c0-3.8628 3.1182-6.9809 6.9809-6.9809 3.8628 0 6.9806 3.1181 6.9806 6.9809 0 3.8627-3.1178 6.9809-6.9806 6.9809zm-44.2123 0c-3.8628 0-6.9809-3.1182-6.9809-6.9809 0-3.8628 3.1181-6.9809 6.9809-6.9809 3.8627 0 6.9809 3.1181 6.9809 6.9809v6.9809zm16.2887 27.9236v-18.6158h18.6158v18.6158zm34.9045 23.2693c-3.8627 0-6.9809-3.1178-6.9809-6.9805v-6.981h6.9809c3.8628 0 6.9806 3.1182 6.9806 6.981 0 3.8627-3.1178 6.9805-6.9806 6.9805zm-51.1932 0c-3.8628 0-6.9809-3.1178-6.9809-6.9805 0-3.8628 3.1181-6.981 6.9809-6.981h6.9809v6.981c0 3.8627-3.1182 6.9805-6.9809 6.9805z" fill="#fff"/></svg>

package/icons/kimi.svg

@@ -1,11 +1,6 @@
-<svg viewBox="0 0 24 24" width="1em" height="1em" xmlns="http://www.w3.org/2000/svg">
-  <defs>
-    <linearGradient id="kimi-g" x1="4" y1="4" x2="20" y2="20" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#141821"/>
-      <stop offset="0.52" stop-color="#2f6df6"/>
-      <stop offset="1" stop-color="#49d2ff"/>
-    </linearGradient>
-  </defs>
-  <rect x="2" y="2" width="20" height="20" rx="6" fill="url(#kimi-g)"/>
-  <path d="M7 6.5h2.6v4.1l4.2-4.1H17l-4.7 4.7 5 6.3h-3.2l-3.6-4.7-.9.9v3.8H7z" fill="#fff"/>
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 112 112" role="img" style="flex:none;line-height:1">
+<title>Kimi Code CLI</title>
+<rect width="112" height="112" rx="28" fill="#000"/>
+<path d="M30 34 38 34 38 56 39 57 63 34 75 34 53 57 65 66 77 73 77 81 73 81 67 78 46 63 38 71 38 81 30 81Z" fill="#fff"/>
+<circle cx="86" cy="28" r="5.5" fill="#1783FF"/>
 </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.173",
+  "version": "0.2.176",
   "description": "OpenAgents Launcher — install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {

package/registry.json

@@ -10,7 +10,11 @@
       "open-source"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "install": {
       "binary": "aider",
       "macos": "curl -LsSf https://aider.chat/install.sh | sh",
@@ -75,7 +79,11 @@
       "vscode"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "install": {
       "binary": "amp",
       "macos": "curl -fsSL https://ampcode.com/install.sh | bash",
@@ -119,7 +127,11 @@
     ],
     "featured": true,
     "order": 1,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "builtin": true,
     "install": {
       "binary": "claude",
@@ -143,7 +155,8 @@
     },
     "check_ready": {
       "env_vars": [
-        "ANTHROPIC_API_KEY"
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_AUTH_TOKEN"
       ],
       "creds_file": "~/.claude/sessions",
       "creds_key": null,
@@ -152,8 +165,37 @@
       "login_command": "claude login",
       "alt_check": "claude --print hi"
     },
-    "probe": { "args": ["--print", "hi"], "timeout_s": 120 },
-    "env_config": []
+    "probe": {
+      "args": [
+        "--print",
+        "hi"
+      ],
+      "timeout_s": 120
+    },
+    "env_config": [],
+    "resolve_env": {
+      "rules": [
+        {
+          "from": "LLM_API_KEY",
+          "to": "ANTHROPIC_AUTH_TOKEN",
+          "if_base_url_contains": "://"
+        },
+        {
+          "from": "LLM_API_KEY",
+          "to": "ANTHROPIC_API_KEY",
+          "unless_base_url_contains": "://"
+        },
+        {
+          "from": "LLM_BASE_URL",
+          "to": "ANTHROPIC_BASE_URL"
+        },
+        {
+          "from": "LLM_MODEL",
+          "to": "ANTHROPIC_MODEL"
+        }
+      ]
+    },
+    "protocol": "anthropic"
   },
   {
     "name": "cline",
@@ -166,7 +208,11 @@
       "autonomous"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": false },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": false
+    },
     "install": {
       "binary": "cline",
       "requires": [
@@ -230,7 +276,11 @@
     ],
     "featured": true,
     "order": 3,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "builtin": true,
     "install": {
       "binary": "codex",
@@ -305,7 +355,11 @@
       "cli"
     ],
     "order": 9,
-    "support": { "install": true, "workspace": true, "collaboration": false },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": false
+    },
     "builtin": true,
     "install": {
       "binary": "copilot",
@@ -400,7 +454,11 @@
     ],
     "check_ready": {
       "binary": "agent",
-      "not_ready_message": "Cursor CLI not found \u2014 install with: curl https://cursor.com/install -fsSL | bash"
+      "not_ready_message": "Cursor is installed but not signed in — run `cursor-agent login` on the device, or set a CURSOR_API_KEY from cursor.com/settings. Third-party or relay API keys do not work with Cursor.",
+      "env_vars": [
+        "CURSOR_API_KEY"
+      ],
+      "login_command": "cursor-agent login"
     },
     "resolve_env": {
       "rules": [
@@ -413,7 +471,8 @@
           "to": "CURSOR_MODEL"
         }
       ]
-    }
+    },
+    "provider_locked": true
   },
   {
     "name": "gemini",
@@ -427,7 +486,11 @@
       "cli"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "install": {
       "binary": "gemini",
       "requires": [
@@ -470,7 +533,13 @@
         "api_key": "API key detected"
       }
     },
-    "probe": { "args": ["-p", "hi"], "timeout_s": 120 },
+    "probe": {
+      "args": [
+        "-p",
+        "hi"
+      ],
+      "timeout_s": 120
+    },
     "env_config": []
   },
   {
@@ -484,7 +553,11 @@
       "cli"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "install": {
       "binary": "agy",
       "macos": "curl -fsSL https://antigravity.google/cli/install.sh | bash",
@@ -586,7 +659,7 @@
   {
     "name": "nanoclaw",
     "label": "NanoClaw",
-    "description": "Containerized agent runtime \u2014 each Agent Group runs in its own Docker container (Claude Agent SDK). Bridged to the Workspace via a native OpenAgents channel.",
+    "description": "Containerized agent runtime — each Agent Group runs in its own Docker container (Claude Agent SDK). Bridged to the Workspace via a native OpenAgents channel.",
     "homepage": "https://github.com/nanocoai/nanoclaw",
     "tags": [
       "coding",
@@ -596,7 +669,11 @@
       "open-source"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": false },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": false
+    },
     "install": {
       "binary": "ncl",
       "requires": [
@@ -632,7 +709,7 @@
         "NANOCLAW_AGENT_GROUP"
       ],
       "saved_env_key": "NANOCLAW_AGENT_GROUP",
-      "not_ready_message": "Set NANOCLAW_AGENT_GROUP (and NANOCLAW_HOME) \u2014 press e to configure"
+      "not_ready_message": "Set NANOCLAW_AGENT_GROUP (and NANOCLAW_HOME) — press e to configure"
     }
   },
   {
@@ -646,7 +723,11 @@
     ],
     "featured": true,
     "order": 2,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "builtin": true,
     "install": {
       "binary": "openclaw",
@@ -716,7 +797,7 @@
         "OPENAI_API_KEY"
       ],
       "saved_env_key": "LLM_API_KEY",
-      "not_ready_message": "Not configured \u2014 press e to configure"
+      "not_ready_message": "Not configured — press e to configure"
     }
   },
   {
@@ -790,29 +871,38 @@
       ],
       "saved_env_key": "LLM_API_KEY",
       "min_version": "1.17.0",
-      "not_ready_message": "Not configured \u2014 press e to configure"
+      "not_ready_message": "Not configured — press e to configure"
     }
   },
   {
     "name": "kimi",
-    "label": "Kimi",
-    "description": "Kimi agent powered by Moonshot AI, OpenAI-compatible API.",
-    "homepage": "https://platform.moonshot.ai",
+    "label": "Kimi Code CLI",
+    "description": "Kimi Code CLI — Moonshot AI's terminal coding agent.",
+    "homepage": "https://moonshotai.github.io/kimi-code",
     "tags": [
       "coding",
+      "cli",
       "moonshot",
       "open-source"
     ],
     "featured": true,
     "order": 7,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "builtin": true,
     "install": {
       "binary": "kimi",
-      "api_only": true,
-      "macos": "echo 'Kimi uses direct API mode — no binary install needed'",
-      "linux": "echo 'Kimi uses direct API mode — no binary install needed'",
-      "windows": "echo 'Kimi uses direct API mode — no binary install needed'"
+      "requires": [
+        "nodejs"
+      ],
+      "verify": "kimi --version",
+      "verify_win": "kimi --version",
+      "macos": "npm install -g @moonshot-ai/kimi-code",
+      "linux": "npm install -g @moonshot-ai/kimi-code",
+      "windows": "npm install -g @moonshot-ai/kimi-code"
     },
     "adapter": {
       "module": "openagents.adapters.kimi",
@@ -824,8 +914,8 @@
     "env_config": [
       {
         "name": "KIMI_API_KEY",
-        "description": "Moonshot/Kimi API key (also accepts MOONSHOT_API_KEY env var)",
-        "required": true,
+        "description": "Moonshot/Kimi API key (also accepts MOONSHOT_API_KEY). Leave blank to use `kimi login`.",
+        "required": false,
         "password": true
       },
       {
@@ -849,8 +939,10 @@
         "MOONSHOT_API_KEY"
       ],
       "saved_env_key": "KIMI_API_KEY",
-      "not_ready_message": "No API key — press e to configure"
-    }
+      "login_command": "kimi login",
+      "not_ready_message": "Not configured — set an API key (press e) or run: kimi login"
+    },
+    "tagline": "Moonshot AI's Kimi Code CLI coding agent."
   },
   {
     "name": "hermes",
@@ -865,11 +957,18 @@
     ],
     "featured": true,
     "order": 6,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "builtin": true,
     "install": {
       "binary": "hermes",
-      "requires": ["python3", "git"],
+      "requires": [
+        "python3",
+        "git"
+      ],
       "macos": "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup",
       "linux": "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup",
       "windows": "\"%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\" -NoProfile -ExecutionPolicy Bypass -Command \"Invoke-RestMethod -UseBasicParsing 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1' | Invoke-Expression\""
@@ -882,7 +981,38 @@
       "creds_no_parse": true,
       "status_command": "hermes status",
       "login_command": "hermes setup",
-      "not_ready_message": "Hermes not configured — run: hermes setup"
+      "not_ready_message": "Hermes not configured — run: hermes setup",
+      "env_vars": [
+        "OPENAI_API_KEY"
+      ],
+      "saved_env_key": "LLM_API_KEY"
+    },
+    "env_config": [
+      {
+        "name": "LLM_API_KEY",
+        "description": "API key for a custom OpenAI-compatible endpoint (optional if you sign in with `hermes setup`)",
+        "required": false,
+        "password": true
+      },
+      {
+        "name": "LLM_BASE_URL",
+        "description": "Custom OpenAI-compatible base URL (leave empty to use Hermes's own provider login)",
+        "required": false,
+        "placeholder": "https://api.openai.com/v1"
+      },
+      {
+        "name": "LLM_MODEL",
+        "description": "Model name served by the endpoint above",
+        "required": false
+      }
+    ],
+    "resolve_env": {
+      "rules": [
+        {
+          "from": "LLM_API_KEY",
+          "to": "OPENAI_API_KEY"
+        }
+      ]
     }
   },
   {
@@ -1136,7 +1266,11 @@
       "headless"
     ],
     "builtin": true,
-    "support": { "install": true, "workspace": true, "collaboration": true },
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
     "install": {
       "binary": "dsh",
       "npm_package": "@deepseek-ai/dsh",
@@ -1212,5 +1346,96 @@
         }
       ]
     }
+  },
+  {
+    "name": "commandcode",
+    "label": "Command Code",
+    "description": "Terminal coding agent that learns your coding taste, driven headlessly for workspace tasks",
+    "homepage": "https://commandcode.ai",
+    "tags": [
+      "coding",
+      "cli",
+      "terminal",
+      "headless"
+    ],
+    "builtin": true,
+    "support": {
+      "install": true,
+      "workspace": true,
+      "collaboration": true
+    },
+    "install": {
+      "binary": "command-code",
+      "binary_aliases": [
+        "commandcode",
+        "cmdc"
+      ],
+      "npm_package": "command-code",
+      "requires": [
+        "nodejs"
+      ],
+      "verify": "command-code --version",
+      "verify_win": "command-code --version",
+      "macos": "npm install -g command-code",
+      "linux": "npm install -g command-code",
+      "windows": "npm install -g command-code"
+    },
+    "adapter": {
+      "module": "openagents.adapters.commandcode",
+      "class": "CommandCodeAdapter"
+    },
+    "launch": null,
+    "env_config": [
+      {
+        "name": "COMMAND_CODE_API_KEY",
+        "description": "Command Code API key for headless/CI auth. Optional — leave blank if you signed in with `command-code login` instead.",
+        "required": false,
+        "password": true
+      },
+      {
+        "name": "COMMANDCODE_MODEL",
+        "description": "Model id to run on. Leave empty for the account default; BYOK models are prefixed with their provider (for example openrouter/deepseek-v4-flash).",
+        "required": false,
+        "placeholder": "claude-sonnet-4-6"
+      },
+      {
+        "name": "COMMANDCODE_EFFORT",
+        "description": "Reasoning effort for each run. Leave empty for the model default.",
+        "required": false,
+        "options": [
+          "low",
+          "medium",
+          "high"
+        ]
+      },
+      {
+        "name": "COMMANDCODE_MAX_TURNS",
+        "description": "Maximum tool-use turns per message. Leave empty for the CLI default of 100; a run that hits the limit still returns its partial answer.",
+        "required": false,
+        "placeholder": "100"
+      }
+    ],
+    "check_ready": {
+      "min_version": "1.0.0",
+      "env_vars": [
+        "COMMAND_CODE_API_KEY"
+      ],
+      "saved_env_key": "COMMAND_CODE_API_KEY",
+      "login_command": "command-code login",
+      "not_ready_message": "Not configured — sign in with `command-code login`, or set COMMAND_CODE_API_KEY (press e)",
+      "unreadable_message": "Command Code credentials could not be read. Sign in again with `command-code login`, or re-enter COMMAND_CODE_API_KEY in the Configure screen."
+    },
+    "resolve_env": {
+      "rules": [
+        {
+          "from": "LLM_API_KEY",
+          "to": "COMMAND_CODE_API_KEY"
+        },
+        {
+          "from": "LLM_MODEL",
+          "to": "COMMANDCODE_MODEL"
+        }
+      ]
+    }
   }
 ]

package/src/adapters/base.js

@@ -30,6 +30,7 @@ const {
   REASON,
   classifyJoinError,
   classifyHeartbeatError,
+  httpStatusOf,
 } = require('./health-status');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
@@ -661,11 +662,29 @@ class BaseAdapter {
         messages = result.messages;
         rawCursor = result.cursor;
         composingActive = !!result.composing;
+        this._pollAuthFailStreak = 0;
         if (pollCount <= 3 || pollCount % 20 === 0) {
           this._log(`Poll #${pollCount}: ${messages.length} messages, cursor=${rawCursor || 'none'}${composingActive ? ' composing' : ''}`);
         }
       } catch (e) {
         this._log(`Poll #${pollCount} failed: ${e.message} \nStack: ${e.stack}`);
+        // A rejected credential never heals by retrying with the same token —
+        // it means the device was re-paired/unpaired and this adapter is
+        // running on a revoked one. After a few consecutive rejections (not
+        // one: a server redeploy can 401 transiently), surface a hard error
+        // so status/heartbeat stop claiming "running" while nothing works.
+        // The daemon's credential watch restarts the adapter when a fresh
+        // token lands on disk, which also clears this state.
+        const sc = httpStatusOf(e);
+        if (sc === 401 || sc === 403 || /invalid workspace credentials/i.test(e.message || '')) {
+          this._pollAuthFailStreak = (this._pollAuthFailStreak || 0) + 1;
+          if (this._pollAuthFailStreak >= 3) {
+            this._reportStatus(
+              REASON.WORKSPACE_JOIN_FAILED,
+              'Workspace rejected this agent\'s credentials — re-pair the device or reconnect the agent to the workspace',
+            );
+          }
+        }
         await this._sleep(5000);
         continue;
       }

package/src/adapters/codex.js

@@ -490,7 +490,47 @@ class CodexAdapter extends BaseAdapter {
     const raw = String(errorMessage || '').trim()
       || stderrTail
       || (exitCode ? `codex exited with code ${exitCode}` : '');
-    return CodexAdapter._redact(raw).slice(0, 500).trim();
+    const detail = CodexAdapter._explain(CodexAdapter._unwrap(raw));
+    return CodexAdapter._redact(detail).slice(0, 500).trim();
+  }
+
+  /**
+   * Unwrap the API's JSON error envelope so the user reads the sentence, not
+   * the transport. The backend rejects a run with a body like
+   * `{"detail":"The 'gpt-5.6-sol' model requires a newer version of Codex."}`
+   * and it was surfaced verbatim, braces and all (#649).
+   */
+  static _unwrap(raw) {
+    const text = String(raw || '').trim();
+    if (!text.startsWith('{') && !text.startsWith('[')) return text;
+    try {
+      const parsed = JSON.parse(text);
+      for (const key of ['detail', 'message', 'error']) {
+        const v = parsed && parsed[key];
+        if (typeof v === 'string' && v.trim()) return v.trim();
+        // OpenAI also nests as { error: { message } }.
+        if (v && typeof v.message === 'string' && v.message.trim()) return v.message.trim();
+      }
+    } catch {}
+    return text;
+  }
+
+  /**
+   * Add the missing half of a backend rejection: what to actually do about it.
+   *
+   * "Please upgrade to the latest app or CLI" is true but unactionable inside a
+   * workspace chat — the user is not at a terminal and does not necessarily
+   * know the CLI is theirs to update. Name where the update button lives. The
+   * match is on the backend's own wording, so an unrelated failure is passed
+   * through untouched.
+   */
+  static _explain(detail) {
+    if (!/requires a newer version|upgrade to the latest (app|version)/i.test(detail)) {
+      return detail;
+    }
+    return `${detail}\n\nUpdate the Codex CLI from OpenAgents Launcher ` +
+      '(Agents → Codex → Update), or run `npm install -g @openai/codex@latest`, ' +
+      'then try again. Picking an older model also works around it for now.';
   }
 
   /** Redact secrets (keys, tokens, bearer/authorization, query secrets) from diagnostics. */