@openagents-org/agent-launcher 0.2.171 → 0.2.172

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.171",
-  "description": "OpenAgents Launcher \u2014 install, configure, and run AI coding agents from your terminal",
+  "version": "0.2.172",
+  "description": "OpenAgents Launcher — install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {
     "agn": "bin/agent-connector.js",

package/registry.json

@@ -152,6 +152,7 @@
       "login_command": "claude login",
       "alt_check": "claude --print hi"
     },
+    "probe": { "args": ["--print", "hi"], "timeout_s": 120 },
     "env_config": []
   },
   {
@@ -417,7 +418,7 @@
   {
     "name": "gemini",
     "label": "Gemini CLI",
-    "description": "Google's open-source AI agent for the command line",
+    "description": "Google's Gemini CLI (legacy — superseded by Antigravity CLI; needs a Gemini API key or Code Assist license since June 2026)",
     "homepage": "https://github.com/google-gemini/gemini-cli",
     "tags": [
       "coding",
@@ -462,13 +463,59 @@
       ],
       "saved_env_key": "GEMINI_API_KEY",
       "login_command": "gemini",
-      "not_ready_message": "Needs sign-in — run `gemini` to sign in, or set GEMINI_API_KEY.",
+      "not_ready_message": "Set GEMINI_API_KEY (Google ended individual sign-in for Gemini CLI in June 2026), or run `gemini` if your org has a Code Assist license.",
       "unreadable_message": "Gemini credentials were found but could not be read. Check permissions on ~/.gemini, or run `gemini` to sign in again.",
       "auth_detected_labels": {
         "cli_login": "Google account sign-in detected",
         "api_key": "API key detected"
       }
     },
+    "probe": { "args": ["-p", "hi"], "timeout_s": 120 },
+    "env_config": []
+  },
+  {
+    "name": "antigravity",
+    "label": "Antigravity CLI",
+    "description": "Google's agent-first CLI (agy) — the successor to Gemini CLI",
+    "homepage": "https://antigravity.google",
+    "tags": [
+      "coding",
+      "google",
+      "cli"
+    ],
+    "builtin": true,
+    "support": { "install": true, "workspace": true, "collaboration": true },
+    "install": {
+      "binary": "agy",
+      "macos": "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+      "linux": "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+      "windows": "irm https://antigravity.google/cli/install.ps1 | iex"
+    },
+    "adapter": {
+      "module": "openagents.adapters.antigravity",
+      "class": "AntigravityAdapter"
+    },
+    "launch": {
+      "args": [
+        "-p",
+        "Your agent name is '{agent_name}'.",
+        "--dangerously-skip-permissions",
+        "--output-format",
+        "stream-json"
+      ]
+    },
+    "check_ready": {
+      "env_vars": [
+        "GEMINI_API_KEY"
+      ],
+      "saved_env_key": "GEMINI_API_KEY",
+      "login_command": "agy",
+      "not_ready_message": "Needs sign-in — run `agy` to sign in with Google, or set GEMINI_API_KEY.",
+      "auth_detected_labels": {
+        "cli_login": "Google account sign-in detected",
+        "api_key": "API key detected"
+      }
+    },
     "env_config": []
   },
   {

package/src/adapters/antigravity-stream.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * Pure helpers for the Antigravity CLI (agy) adapter — argv construction,
+ * stream-json event interpretation, and failure classification. No I/O and no
+ * process state, so every branch is unit-testable (see
+ * test/antigravity-stream.test.js).
+ *
+ * agy's headless protocol (`--output-format stream-json`) is NDJSON with an
+ * `event` field per line: exactly one `init`, any number of `step_update`,
+ * exactly one `result`. That differs from the old Gemini CLI stream (`type`
+ * field, `message`/`tool_use` events), which is why this is a new module
+ * rather than a tweak to the gemini adapter.
+ */
+
+/** Build the argv tail (everything after the binary) for one headless run. */
+function buildAgyArgv({ prompt, model, conversationId, skipResume = false } = {}) {
+  const args = [
+    '-p', prompt || '',
+    // Counterpart of gemini's `-y`: headless runs have no interactive
+    // approval prompt, and a soft-denied tool call silently degrades the
+    // answer. The daemon is the approval boundary here, same as every other
+    // CLI adapter.
+    '--dangerously-skip-permissions',
+    '--output-format', 'stream-json',
+  ];
+  if (model) args.push('--model', model);
+  if (conversationId && !skipResume) args.push('--conversation', conversationId);
+  return args;
+}
+
+/** Parse one NDJSON line. Returns the event object, or null for non-events. */
+function parseAgyEvent(line) {
+  const trimmed = (line || '').trim();
+  if (!trimmed) return null;
+  let obj;
+  try { obj = JSON.parse(trimmed); } catch { return null; }
+  if (!obj || typeof obj !== 'object' || typeof obj.event !== 'string') return null;
+  return obj;
+}
+
+/** One-line preview of a tool call's parameters for the status ticker. */
+function toolPreview(parameters) {
+  if (!parameters || typeof parameters !== 'object') return '';
+  // agy uses PascalCase parameter names (e.g. CommandLine); check both.
+  const pick = (...names) => {
+    for (const n of names) {
+      const v = parameters[n];
+      if (typeof v === 'string' && v) return v;
+    }
+    return null;
+  };
+  return (
+    pick('CommandLine', 'command') ||
+    pick('AbsolutePath', 'file_path', 'path') ||
+    pick('Query', 'query', 'pattern') ||
+    JSON.stringify(parameters).slice(0, 150)
+  );
+}
+
+/**
+ * Reducer over one run's event stream. `consume(event)` returns display
+ * actions for the adapter to translate into workspace calls:
+ *
+ *   {type:'conversation', id}          — persist for --conversation resume
+ *   {type:'thinking', text}            — a finished agent_response block
+ *   {type:'tool', name, preview}       — a tool step began
+ *   {type:'result', status, response, error}
+ *
+ * `finalResponse()` afterwards yields the text to post: the result envelope's
+ * `response` when present (authoritative), else the last completed
+ * agent_response block — mirroring the gemini adapter's "text after the last
+ * tool use" semantics for streams that die before their result event.
+ */
+class AgyRunState {
+  constructor() {
+    this.conversationId = null;
+    this.status = null;
+    this.error = null;
+    this._resultResponse = '';
+    this._blocks = [];       // completed agent_response texts since last tool
+    this._pending = '';      // text_delta accumulator for the ACTIVE block
+    this._toolSteps = new Set(); // step_index values already announced
+  }
+
+  consume(event) {
+    if (!event || typeof event !== 'object') return [];
+    const actions = [];
+
+    if (event.event === 'init') {
+      if (event.conversation_id) {
+        this.conversationId = event.conversation_id;
+        actions.push({ type: 'conversation', id: event.conversation_id });
+      }
+      return actions;
+    }
+
+    if (event.event === 'step_update') {
+      const step = event.step_update || {};
+      if (step.step_type === 'agent_response') {
+        if (typeof step.text_delta === 'string') this._pending += step.text_delta;
+        if (step.state === 'DONE') {
+          const text = this._pending.trim();
+          this._pending = '';
+          if (text) {
+            this._blocks.push(text);
+            actions.push({ type: 'thinking', text });
+          }
+        }
+      } else if (step.step_type === 'tool') {
+        // Announce each tool step once, on first sight — agy repeats the step
+        // across ACTIVE/DONE updates.
+        const key = step.step_index != null ? step.step_index : `t${this._toolSteps.size}`;
+        if (!this._toolSteps.has(key)) {
+          this._toolSteps.add(key);
+          const info = step.tool_info || {};
+          const name = info.name || step.tool_name || 'tool';
+          actions.push({ type: 'tool', name, preview: toolPreview(info.parameters) });
+          // A tool ran: any text before it was narration, not the answer.
+          this._blocks = [];
+        }
+      }
+      return actions;
+    }
+
+    if (event.event === 'result') {
+      const result = event.result || {};
+      if (result.conversation_id && !this.conversationId) {
+        this.conversationId = result.conversation_id;
+        actions.push({ type: 'conversation', id: result.conversation_id });
+      }
+      this.status = result.status || null;
+      this.error = result.error || null;
+      if (typeof result.response === 'string') this._resultResponse = result.response;
+      actions.push({
+        type: 'result',
+        status: this.status,
+        response: this._resultResponse,
+        error: this.error,
+      });
+      return actions;
+    }
+
+    return actions;
+  }
+
+  /** True once the stream produced any user-visible text. */
+  sawText() {
+    return this._blocks.length > 0 || !!this._resultResponse.trim();
+  }
+
+  finalResponse() {
+    const fromResult = this._resultResponse.trim();
+    if (fromResult) return fromResult;
+    // Stream died before its result event — fall back to the accumulated
+    // agent_response text (plus any half-flushed delta).
+    return [...this._blocks, this._pending.trim()].filter(Boolean).join('\n\n').trim();
+  }
+}
+
+const AUTH_RE = /authentication (required|failed)|not authenticated|sign[ -]?in|log[ -]?in required|no valid credentials|GEMINI_API_KEY/i;
+const PROVIDER_RE = /modelProvider|model provider/i;
+const MODEL_RE = /unknown model|invalid model/i;
+const TIMEOUT_RE = /print-timeout|timed? ?out/i;
+
+/**
+ * Turn a failed run (non-zero exit, or a result event with status ERROR) into
+ * a { kind, message } the adapter can post verbatim. This is the fix for the
+ * "No response generated. Please try again." dead end: the real reason was in
+ * stderr all along, so surface it.
+ */
+function classifyAgyFailure({ code, stderr, error } = {}) {
+  // The docs describe `result.error` as {type, message}; agy 1.1.17 actually
+  // emits a plain string ("authentication failed or timed out"). Take both.
+  const err = error && typeof error === 'object' ? error : {};
+  const errText =
+    typeof error === 'string' ? error : [err.type, err.message].filter(Boolean).join(' ');
+  const text = [errText, stderr].filter(Boolean).join('\n');
+
+  if (AUTH_RE.test(text)) {
+    return {
+      kind: 'auth',
+      message:
+        'Antigravity CLI needs authentication. Run `agy` once in a terminal to ' +
+        'sign in with Google, or set GEMINI_API_KEY for this agent (the ' +
+        'connector configures the provider automatically).',
+    };
+  }
+  if (PROVIDER_RE.test(text)) {
+    return {
+      kind: 'config',
+      message:
+        'Antigravity CLI is configured for API-key auth but no key is set. ' +
+        'Set GEMINI_API_KEY for this agent, or remove "modelProvider" from ' +
+        '~/.gemini/antigravity-cli/settings.json to use Google sign-in.',
+    };
+  }
+  if (MODEL_RE.test(text)) {
+    return {
+      kind: 'model',
+      message:
+        'Antigravity CLI rejected the configured model. Check ANTIGRAVITY_MODEL ' +
+        '(list valid slugs with `agy models`).',
+    };
+  }
+  if (TIMEOUT_RE.test(text)) {
+    return { kind: 'timeout', message: 'Antigravity CLI timed out before producing a response.' };
+  }
+  const detail = (errText || (stderr || '').trim().split('\n').pop() || '').slice(0, 200);
+  return {
+    kind: 'unknown',
+    message: detail
+      ? `Antigravity CLI failed (exit ${code ?? '?'}): ${detail}`
+      : `Antigravity CLI exited with code ${code ?? '?'} without a response.`,
+  };
+}
+
+/**
+ * Filesystem candidates for the agy binary, beyond a PATH lookup. The install
+ * script targets ~/.local/bin on macOS/Linux and %LOCALAPPDATA%\agy\bin on
+ * Windows. Pure: the adapter applies fs.existsSync.
+ */
+function agyBinaryCandidates({ home, isWindows, localAppData } = {}) {
+  if (isWindows) {
+    const base = localAppData || '';
+    return base ? [`${base}\\agy\\bin\\agy.exe`] : [];
+  }
+  return [
+    `${home}/.local/bin/agy`,
+    '/opt/homebrew/bin/agy',
+    '/usr/local/bin/agy',
+  ];
+}
+
+module.exports = {
+  buildAgyArgv,
+  parseAgyEvent,
+  toolPreview,
+  AgyRunState,
+  classifyAgyFailure,
+  agyBinaryCandidates,
+};

package/src/adapters/antigravity.js

@@ -0,0 +1,390 @@
+/**
+ * Antigravity CLI (agy) adapter for OpenAgents workspace.
+ *
+ * Successor to the Gemini CLI adapter: Google transitioned Gemini CLI into
+ * Antigravity CLI in May 2026 and cut individual-account access to the old
+ * CLI that June. agy is a closed-source Go binary — no npm runtime prefix and
+ * no .cmd/.js shim resolution needed — driven headless via
+ * `agy -p <prompt> --output-format stream-json`.
+ *
+ * Stream interpretation, argv building, and failure classification live in
+ * ./antigravity-stream.js (pure, unit-tested); this file owns process
+ * lifecycle and workspace I/O, structurally mirroring gemini.js.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+
+const BaseAdapter = require('./base');
+const { whereBinary } = require('../paths');
+const { formatAttachmentsForPrompt, SESSION_DEFAULT_RE, generateSessionTitle } = require('./utils');
+const { buildClaudeSystemPrompt } = require('./workspace-prompt');
+const {
+  buildAgyArgv,
+  parseAgyEvent,
+  AgyRunState,
+  classifyAgyFailure,
+  agyBinaryCandidates,
+} = require('./antigravity-stream');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+class AntigravityAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts - BaseAdapter opts plus:
+   * @param {Set} [opts.disabledModules]
+   * @param {string} [opts.workingDir]
+   */
+  constructor(opts) {
+    super(opts);
+    this.disabledModules = opts.disabledModules || new Set();
+    // Read-only pinned context, same as gemini: agy has no MCP bridge to the
+    // workspace knowledge tools, so it can see the decision log but not write it.
+    this._usesPinnedContext = true;
+    this._channelConversations = {}; // channel → agy conversation_id
+    this._channelProcesses = {}; // channel → child process
+    this._sessionsFile = path.join(
+      os.homedir(), '.openagents', 'sessions',
+      `${this.workspaceId}_${this.agentName}_antigravity.json`
+    );
+    this._loadSessions();
+  }
+
+  _loadSessions() {
+    try {
+      if (fs.existsSync(this._sessionsFile)) {
+        const data = JSON.parse(fs.readFileSync(this._sessionsFile, 'utf-8'));
+        if (data && typeof data === 'object') {
+          Object.assign(this._channelConversations, data);
+          this._log(`Loaded ${Object.keys(data).length} conversation(s)`);
+        }
+      }
+    } catch {
+      this._log('Could not load sessions file, starting fresh');
+    }
+  }
+
+  _saveSessions() {
+    try {
+      const dir = path.dirname(this._sessionsFile);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(this._sessionsFile, JSON.stringify(this._channelConversations));
+    } catch {}
+  }
+
+  async _onControlAction(action, _payload) {
+    if (action === 'stop') {
+      await this._stopAllProcesses();
+    }
+  }
+
+  async _stopProcess(proc) {
+    if (!proc || proc.exitCode !== null) return;
+    try {
+      if (IS_WINDOWS) {
+        try { execSync(`taskkill /F /T /PID ${proc.pid}`, { timeout: 5000 }); } catch {}
+      } else {
+        try { process.kill(-proc.pid, 'SIGTERM'); } catch {
+          proc.kill('SIGTERM');
+        }
+        await new Promise((resolve) => {
+          const timeout = setTimeout(() => {
+            try { process.kill(-proc.pid, 'SIGKILL'); } catch {
+              proc.kill('SIGKILL');
+            }
+            resolve();
+          }, 5000);
+          proc.on('exit', () => { clearTimeout(timeout); resolve(); });
+        });
+      }
+    } catch {}
+  }
+
+  async _stopAllProcesses() {
+    const entries = Object.entries(this._channelProcesses);
+    if (!entries.length) return;
+    this._log(`Stopping ${entries.length} running process(es)...`);
+    for (const [channel, proc] of entries) {
+      await this._stopProcess(proc);
+      delete this._channelProcesses[channel];
+      delete this._channelQueues[channel];
+      try {
+        await this.sendStatus(channel, 'Execution stopped by user');
+      } catch {}
+    }
+  }
+
+  _findAgyBinary() {
+    // PATH first (codepage-safe lookup, see whereBinary), then the install
+    // script's fixed destinations.
+    const viaWhere = whereBinary('agy');
+    if (viaWhere) return viaWhere;
+    const candidates = agyBinaryCandidates({
+      home: os.homedir(),
+      isWindows: IS_WINDOWS,
+      localAppData: process.env.LOCALAPPDATA,
+    });
+    for (const c of candidates) {
+      if (fs.existsSync(c)) return c;
+    }
+    return null;
+  }
+
+  /**
+   * agy ignores a bare GEMINI_API_KEY unless the settings file also selects
+   * the gemini provider — and, inversely, refuses to start when the provider
+   * is selected but the key is missing. When the user configured a key for
+   * this agent, select the provider for them; never touch the file otherwise
+   * (a keyring/OAuth sign-in needs no provider entry and must not gain one,
+   * or the CLI stops starting the day the key is removed).
+   */
+  _ensureAgyAuth() {
+    if (this._agyAuthReady) return;
+    this._agyAuthReady = true;
+    try {
+      const env = this.agentEnv || process.env;
+      const apiKey = (env.GEMINI_API_KEY || '').trim();
+      if (!apiKey) return; // OAuth / keyring — leave the user's setup alone.
+      const dir = path.join(os.homedir(), '.gemini', 'antigravity-cli');
+      fs.mkdirSync(dir, { recursive: true });
+      const file = path.join(dir, 'settings.json');
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(file, 'utf-8')) || {}; } catch {}
+      if (settings.modelProvider === 'gemini') return; // already selected.
+      settings.modelProvider = 'gemini';
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2));
+      this._log('Configured Antigravity CLI for API-key auth (~/.gemini/antigravity-cli/settings.json)');
+    } catch (e) {
+      this._log(`agy auth setup skipped: ${e.message}`);
+    }
+  }
+
+  _buildAgyCmd(prompt, channelName, { skipResume = false } = {}) {
+    this._ensureAgyAuth();
+    const agyBin = this._findAgyBinary();
+    if (!agyBin) {
+      throw new Error(
+        'agy CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
+      );
+    }
+
+    const pinned = this.pinnedPromptOpts(channelName);
+    const systemPrompt = '\n' + buildClaudeSystemPrompt({
+      agentName: this.agentName,
+      workspaceId: this.workspaceId,
+      channelName,
+      mode: this._mode,
+      decisionLog: pinned.decisionLog ? { ...pinned.decisionLog, writeAccess: false } : null,
+      glossary: pinned.glossary ? { ...pinned.glossary, writeAccess: false } : null,
+    });
+
+    // No system-prompt flag in agy's print mode either — prepend it.
+    const fullPrompt = `${systemPrompt}\n\n---\n\nUser message:\n${prompt}`;
+
+    const env = this.agentEnv || process.env;
+    const model = (env.ANTIGRAVITY_MODEL || env.AGY_MODEL || '').trim();
+
+    const args = buildAgyArgv({
+      prompt: fullPrompt,
+      model,
+      conversationId: this._channelConversations[channelName],
+      skipResume,
+    });
+    return { cmd: [agyBin, ...args] };
+  }
+
+  async _handleMessage(msg) {
+    let content = (msg.content || '').trim();
+    const attachments = msg.attachments || [];
+
+    const attText = formatAttachmentsForPrompt(attachments);
+    if (attText) {
+      content = content ? content + attText : attText.trim();
+    }
+
+    if (!content) return;
+
+    const msgChannel = msg.sessionId || this.channelName;
+    const sender = msg.senderName || msg.senderType || 'user';
+    this._log(`Processing message from ${sender} in ${msgChannel}: ${content.slice(0, 80)}...`);
+
+    if (!this._titledSessions.has(msgChannel)) {
+      this._titledSessions.add(msgChannel);
+      try {
+        const info = await this.client.getSession(this.workspaceId, msgChannel, this.token);
+        const resumeFrom = info.resumeFrom;
+        if (resumeFrom && !this._channelConversations[msgChannel]) {
+          const sourceConversation = this._channelConversations[resumeFrom];
+          if (sourceConversation) {
+            this._channelConversations[msgChannel] = sourceConversation;
+            this._saveSessions();
+            this._log(`Resuming channel ${msgChannel} from ${resumeFrom}`);
+          }
+        }
+        const title = generateSessionTitle(content);
+        if (title && !info.titleManuallySet && SESSION_DEFAULT_RE.test(info.title || '')) {
+          await this.client.updateSession(
+            this.workspaceId, msgChannel, this.token,
+            { title, autoTitle: true }
+          );
+        }
+      } catch {}
+    }
+
+    await this.sendStatus(msgChannel, 'thinking...');
+
+    let cmd;
+    const cleanEnv = { ...(this.agentEnv || process.env) };
+
+    let _shouldRetry = false;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const built = this._buildAgyCmd(content, msgChannel, { skipResume: attempt > 0 });
+        cmd = built.cmd;
+      } catch (e) {
+        await this.sendError(msgChannel, e.message);
+        return;
+      }
+
+      try {
+        const proc = spawn(cmd[0], cmd.slice(1), {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: cleanEnv,
+          cwd: this.workingDir,
+          detached: !IS_WINDOWS,
+          windowsHide: true,
+        });
+        this._channelProcesses[msgChannel] = proc;
+
+        const run = new AgyRunState();
+        let stderrBuf = '';
+        let lineBuffer = '';
+        let _pendingLines = Promise.resolve();
+
+        if (proc.stderr) {
+          proc.stderr.on('data', (chunk) => { stderrBuf += chunk.toString('utf-8'); });
+        }
+
+        _shouldRetry = await new Promise((resolve, reject) => {
+          let consecutiveTimeouts = 0;
+          let lastDataTime = Date.now();
+          let timeoutTimer = null;
+
+          const resetTimeout = () => {
+            consecutiveTimeouts = 0;
+            lastDataTime = Date.now();
+          };
+
+          const startTimeoutMonitor = () => {
+            timeoutTimer = setInterval(async () => {
+              const elapsed = Date.now() - lastDataTime;
+              if (elapsed >= 15000) {
+                consecutiveTimeouts++;
+                lastDataTime = Date.now();
+                if (consecutiveTimeouts === 2) {
+                  try { await this.sendStatus(msgChannel, 'Processing...'); } catch {}
+                }
+                if (consecutiveTimeouts >= 20) {
+                  this._log(`Process idle for ${consecutiveTimeouts * 15}s, killing...`);
+                  await this._stopProcess(proc);
+                }
+              }
+            }, 15000);
+          };
+          startTimeoutMonitor();
+
+          const processLine = async (line) => {
+            const event = parseAgyEvent(line);
+            if (!event) return;
+            resetTimeout();
+            for (const action of run.consume(event)) {
+              if (action.type === 'conversation') {
+                this._channelConversations[msgChannel] = action.id;
+                this._saveSessions();
+              } else if (action.type === 'thinking') {
+                try { await this.sendThinking(msgChannel, action.text); } catch {}
+              } else if (action.type === 'tool') {
+                try { await this.sendStatus(msgChannel, `${action.name} › ${action.preview}`); } catch {}
+              }
+              // 'result' is read from `run` after exit.
+            }
+          };
+
+          proc.on('exit', async (code) => {
+            if (timeoutTimer) clearInterval(timeoutTimer);
+
+            try { await _pendingLines; } catch {}
+
+            const lines = lineBuffer.split('\n');
+            for (const line of lines) {
+              try { await processLine(line); } catch {}
+            }
+
+            delete this._channelProcesses[msgChannel];
+
+            if (code !== 0) {
+              this._log(`CLI exited with code ${code}`);
+              if (stderrBuf.trim()) {
+                this._log(`stderr: ${stderrBuf.trim().slice(0, 500)}`);
+              }
+            }
+
+            const response = run.finalResponse();
+            const failed = code !== 0 || run.status === 'ERROR';
+
+            if (response && !failed) {
+              try { await this.sendResponse(msgChannel, response); } catch {}
+              resolve(false);
+            } else if (failed && this._channelConversations[msgChannel] && attempt === 0) {
+              // A stored conversation id the CLI no longer knows fails the
+              // whole run — clear it and retry once from scratch.
+              this._log(`Stale conversation for ${msgChannel}, clearing and retrying without resume`);
+              delete this._channelConversations[msgChannel];
+              this._saveSessions();
+              resolve(true);
+            } else if (failed) {
+              // Surface the real reason (auth, provider config, bad model)
+              // instead of a generic retry prompt — the gemini adapter's
+              // silent-stderr dead end is what this branch fixes.
+              const { kind, message } = classifyAgyFailure({ code, stderr: stderrBuf, error: run.error });
+              this._log(`run failed (${kind})`);
+              try { await this.sendError(msgChannel, message); } catch {}
+              resolve(false);
+            } else {
+              if (!run.sawText()) {
+                try { await this.sendResponse(msgChannel, 'No response generated. Please try again.'); } catch {}
+              }
+              resolve(false);
+            }
+          });
+
+          proc.on('error', (err) => {
+            if (timeoutTimer) clearInterval(timeoutTimer);
+            reject(err);
+          });
+
+          proc.stdout.on('data', (chunk) => {
+            lineBuffer += chunk.toString('utf-8');
+            resetTimeout();
+            const lines = lineBuffer.split('\n');
+            lineBuffer = lines.pop();
+            for (const line of lines) {
+              _pendingLines = _pendingLines.then(() => processLine(line)).catch(() => {});
+            }
+          });
+        });
+      } catch (e) {
+        this._log(`Error handling message: ${e.message}`);
+        await this.sendError(msgChannel, `Error processing message: ${e.message}`);
+        break;
+      }
+      if (!_shouldRetry) break;
+    }
+  }
+}
+
+module.exports = AntigravityAdapter;

package/src/adapters/index.js

@@ -22,6 +22,7 @@ const AmpAdapter = require('./amp');
 const MiniSweAgentAdapter = require('./mini');
 const PiAdapter = require('./pi');
 const DeepSeekAdapter = require('./deepseek');
+const AntigravityAdapter = require('./antigravity');
 
 const ADAPTER_MAP = {
   openclaw: OpenClawAdapter,
@@ -41,11 +42,12 @@ const ADAPTER_MAP = {
   'mini-swe-agent': MiniSweAgentAdapter,
   pi: PiAdapter,
   deepseek: DeepSeekAdapter,
+  antigravity: AntigravityAdapter,
 };
 
 /**
  * Create an adapter instance for the given agent type.
- * @param {string} type - Agent type (openclaw, claude, codex, opencode, nanoclaw, cursor, hermes, gemini, kimi, aider, goose, copilot, cline, amp, mini-swe-agent, pi, deepseek)
+ * @param {string} type - Agent type (openclaw, claude, codex, opencode, nanoclaw, cursor, hermes, gemini, kimi, aider, goose, copilot, cline, amp, mini-swe-agent, pi, deepseek, antigravity)
  * @param {object} opts - Adapter constructor options
  * @returns {BaseAdapter}
  */
@@ -76,6 +78,7 @@ module.exports = {
   MiniSweAgentAdapter,
   PiAdapter,
   DeepSeekAdapter,
+  AntigravityAdapter,
   createAdapter,
   ADAPTER_MAP,
 };

package/src/cli.js

@@ -806,6 +806,37 @@ async function cmdTestLLM(connector, _flags, positional) {
   }
 }
 
+async function cmdProbe(connector, flags, positional) {
+  const target = positional[0];
+  if (!target) { print('Usage: agn probe <type|agent> [--json]'); return; }
+
+  // Accept an agent name as a convenience — probe its type.
+  let type = target;
+  try {
+    const agent = connector.config.getAgent(target);
+    if (agent) type = agent.type || 'openclaw';
+  } catch {}
+
+  const result = await connector.probeAgentType(type);
+
+  if (flags && flags.json) {
+    // Machine consumers (the daemon's probe_agent node command) read ONLY
+    // stdout JSON — same contract as `agn runtimes --json`.
+    process.stdout.write(JSON.stringify(result));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (result.ok) {
+    print(`OK (${result.method}, ${result.durationMs}ms)${result.reply ? ` — ${result.reply}` : ''}`);
+    if (result.code === 'static_only') print(result.message);
+  } else {
+    print(`FAILED [${result.code}] ${result.message || ''}`.trim());
+    for (const line of result.guidance || []) print(`  → ${line}`);
+    process.exitCode = 1;
+  }
+}
+
 async function cmdVersion() {
   const pkg = require('../package.json');
   print(`${pkg.name} v${pkg.version}`);
@@ -874,6 +905,7 @@ Commands:
   tool-mode [agent] [mode]    View/set tool mode (mcp or skills)
   autostart [--disable]       Enable/disable auto-start on login
   test-llm <type>             Test LLM connection
+  probe <type|agent> [--json] Smoke-test an agent (tiny end-to-end prompt)
   logs [agent] [--lines N]    View daemon logs
   workspace create [name]     Create a new workspace
   workspace join <token>      Join workspace with token
@@ -962,6 +994,7 @@ async function main() {
     skills: () => cmdSkills(connector, flags, positional),
     'tool-mode': () => cmdToolMode(connector, flags, positional),
     'test-llm': () => cmdTestLLM(connector, flags, positional),
+    probe: () => cmdProbe(connector, flags, positional),
     update: () => cmdUpdate(connector),
     'mcp-server': () => {
       const { runMcpServer } = require('./mcp-server');

package/src/daemon.js

@@ -47,9 +47,86 @@ class Daemon {
     this._runningCommands = new Set();   // node-command ids currently executing
     this._runtimes = [];                 // detected agent runtimes for the node view
     this._runtimesInterval = null;
+    this._probes = this._loadProbes();   // type → last smoke-test result (persisted)
+    this._probeInterval = null;
+    this._probeStartupTimer = null;
+    this._probeInFlight = new Set();     // types being probed right now
     this._reloadInFlight = null;  // serialize concurrent _reload() calls
   }
 
+  // ── Agent smoke tests (probes) ─────────────────────────────────────────
+  // A probe runs one tiny end-to-end prompt through an agent type (see
+  // probe.js) — the check that catches "connected but never answers".
+  // Results are persisted so a daemon restart doesn't re-spend LLM calls,
+  // and are reported to every paired workspace on the node heartbeat.
+
+  _probesFile() {
+    return path.join(os.homedir(), '.openagents', 'probes.json');
+  }
+
+  _loadProbes() {
+    try {
+      const data = JSON.parse(fs.readFileSync(this._probesFile(), 'utf-8'));
+      return data && typeof data === 'object' ? data : {};
+    } catch { return {}; }
+  }
+
+  _saveProbes() {
+    try {
+      fs.mkdirSync(path.dirname(this._probesFile()), { recursive: true });
+      fs.writeFileSync(this._probesFile(), JSON.stringify(this._probes, null, 2), 'utf-8');
+    } catch {}
+  }
+
+  /**
+   * Probe one type via a child `agn probe --json` (same off-event-loop
+   * pattern as _refreshRuntimes; a probe can block for its full timeout).
+   */
+  async _probeType(type) {
+    if (this._probeInFlight.has(type)) return this._probes[type] || null;
+    this._probeInFlight.add(type);
+    try {
+      const r = await this._runAgn(['probe', type, '--json']);
+      let parsed = null;
+      try { parsed = JSON.parse(r.stdout.trim()); } catch {}
+      if (!parsed || typeof parsed !== 'object') {
+        parsed = {
+          type, ok: false, method: 'none', code: 'probe_error',
+          message: (r.stderr || 'probe failed').slice(0, 400),
+          guidance: [], at: new Date().toISOString(),
+        };
+      }
+      this._probes[type] = parsed;
+      this._saveProbes();
+      return parsed;
+    } finally {
+      this._probeInFlight.delete(type);
+    }
+  }
+
+  /**
+   * Periodic sweep: probe each type that has a configured agent and whose
+   * last result is missing or stale. Sequential on purpose — probes cost a
+   * (tiny) model call each; there is no hurry.
+   */
+  async _probeConfiguredTypes(maxAgeMs) {
+    const types = [...new Set(this.config.getAgents().map((a) => a.type || 'openclaw'))];
+    for (const type of types) {
+      const last = this._probes[type];
+      const age = last && last.at ? Date.now() - Date.parse(last.at) : Infinity;
+      if (age < maxAgeMs) continue;
+      try { await this._probeType(type); } catch {}
+    }
+    this._nodeHeartbeat();
+  }
+
+  /** Runtimes annotated with each type's last probe, for the heartbeat. */
+  _runtimesWithProbes() {
+    return (this._runtimes || []).map((r) =>
+      this._probes[r.type] ? { ...r, probe: this._probes[r.type] } : r
+    );
+  }
+
   /**
    * Heartbeat this device (node) to EVERY workspace it is paired to,
    * independent of any agent, so each workspace's "connected devices" view
@@ -67,7 +144,7 @@ class Daemon {
     const nodeCfg = require('./node-config');
     const pairings = nodeCfg.listPairings().filter((p) => p && p.node_id && p.token);
     if (!pairings.length) return;  // no node connected
-    const info = { ...nodeCfg.gatherDeviceInfo(), runtimes: this._runtimes, fs: this._buildFs() };
+    const info = { ...nodeCfg.gatherDeviceInfo(), runtimes: this._runtimesWithProbes(), fs: this._buildFs() };
     await Promise.all(pairings.map((p) => this._nodeHeartbeatOne(nodeCfg, p, info)));
   }
 
@@ -270,6 +347,10 @@ class Daemon {
         if (r2.code !== 0) throw new Error(r2.stderr || r2.stdout || 'connect failed');
         ok = true;
         message = `Agent '${name}' created`;
+        // First-connect smoke test, in the background (a probe can take its
+        // full timeout — never hold the create result hostage). The outcome
+        // reaches the workspace via the heartbeat's runtimes[].probe.
+        this._probeType(type).then(() => this._nodeHeartbeat()).catch(() => {});
       } else if (action === 'start_agent') {
         const r = await this._runAgn(['start', name]);
         ok = r.code === 0;
@@ -304,6 +385,24 @@ class Daemon {
         }
         ok = true;
         message = `Agent '${name}' reconfigured`;
+      } else if (action === 'probe_agent') {
+        // Smoke-test on demand ("Test agent" in the workspace). Accepts a
+        // type directly, or an agent name (must belong to this workspace).
+        let type = (args.type || '').trim();
+        if (!type && name) {
+          const agent = this.config.getAgent(name);
+          if (!agent || !this._agentOnNodeWorkspace(agent, n)) {
+            throw new Error(`Agent '${name}' is not managed by this workspace`);
+          }
+          type = agent.type || 'openclaw';
+        }
+        if (!type) throw new Error('Missing agent type');
+        const probe = await this._probeType(type);
+        ok = !!(probe && probe.ok);
+        message = (probe && probe.message) || (ok ? 'Smoke test passed' : 'Smoke test failed');
+        data = { probe };
+        // Push the fresh result right away (same pattern as detect_runtimes).
+        this._nodeHeartbeat();
       } else if (action === 'detect_runtimes') {
         await this._refreshRuntimes();
         // Push the fresh detection right away rather than waiting for the next
@@ -428,6 +527,20 @@ class Daemon {
     this._refreshRuntimes();
     this._runtimesInterval = setInterval(() => this._refreshRuntimes(), 120000);
 
+    // Smoke-test configured agent types periodically (each probe spends one
+    // tiny model call, so: only types with agents, only when the last result
+    // is a day old, and a few minutes after startup so install/login churn
+    // settles first). Persisted results keep restarts from re-spending calls.
+    const PROBE_MAX_AGE_MS = 24 * 3600 * 1000;
+    this._probeStartupTimer = setTimeout(
+      () => this._probeConfiguredTypes(PROBE_MAX_AGE_MS).catch(() => {}),
+      3 * 60 * 1000,
+    );
+    this._probeInterval = setInterval(
+      () => this._probeConfiguredTypes(PROBE_MAX_AGE_MS).catch(() => {}),
+      6 * 3600 * 1000,
+    );
+
     // Watch config file for hot-reload
     this._watchConfig();
 
@@ -455,6 +568,8 @@ class Daemon {
     if (this._cmdInterval) clearInterval(this._cmdInterval);
     if (this._nodeHeartbeatInterval) clearInterval(this._nodeHeartbeatInterval);
     if (this._runtimesInterval) clearInterval(this._runtimesInterval);
+    if (this._probeStartupTimer) clearTimeout(this._probeStartupTimer);
+    if (this._probeInterval) clearInterval(this._probeInterval);
     if (this._configWatcher) { try { this._configWatcher.close(); } catch {} }
 
     // Kill all child processes

package/src/index.js

@@ -289,6 +289,15 @@ class AgentConnector {
     const { testLLMConnection } = require('./utils');
     return testLLMConnection(env);
   }
+
+  /**
+   * Smoke-test an agent type end to end (tiny "hi" prompt through its CLI or
+   * LLM API) and classify any failure into actionable guidance. See probe.js.
+   */
+  async probeAgentType(agentType, opts) {
+    const { probeAgentType } = require('./probe');
+    return probeAgentType(this, agentType, opts);
+  }
 }
 
 const adapters = require('./adapters');

package/src/probe.js

@@ -0,0 +1,318 @@
+'use strict';
+
+/**
+ * Agent smoke test ("probe") — answers the question static health checks
+ * can't: does this agent actually produce a response on this device?
+ *
+ * healthCheck() proves a binary exists and credentials LOOK present; users
+ * still hit "No response generated", invalid-key errors, and silent hangs at
+ * message time. The probe closes that gap by running one tiny end-to-end
+ * prompt ("hi") the same way the adapter would, then classifying whatever
+ * came back into a machine code plus human guidance ("run `claude login` on
+ * the device", "the API key is invalid", ...).
+ *
+ * Tiering (cheapest thing that proves liveness):
+ *   1. healthCheck gate — not installed / not configured fails fast with the
+ *      existing auth guidance, no process spawned, no tokens spent.
+ *   2. Live check, picked from the registry entry:
+ *      - `probe.args`            → run the agent CLI itself (e.g. --print hi)
+ *      - `check_ready.alt_check` → run the entry's declared liveness command
+ *      - saved API key           → one direct LLM API call (testLLMConnection)
+ *      - none of the above       → report static checks only (never guess a
+ *        CLI invocation; a wrong flag would misreport a healthy agent).
+ *
+ * Results carry NO environment values. CLI output is truncated and scrubbed
+ * of anything key-shaped before it leaves this module.
+ */
+
+const os = require('os');
+const { spawn } = require('child_process');
+const { getEnhancedEnv } = require('./paths');
+const { formatAuthGuidance } = require('./auth-guidance');
+const { testLLMConnection } = require('./utils');
+
+const PROBE_PROMPT = 'hi';
+const DEFAULT_TIMEOUT_MS = 90_000;
+const OUTPUT_CAP = 400;      // max chars of CLI output kept for diagnostics
+const REPLY_CAP = 160;       // max chars of a successful reply echoed back
+
+/** Failure codes, ordered roughly by how actionable they are for the user. */
+const CODE = {
+  OK: 'ok',
+  STATIC_ONLY: 'static_only',
+  UNKNOWN_TYPE: 'unknown_type',
+  NOT_INSTALLED: 'not_installed',
+  NOT_READY: 'not_ready',
+  INVALID_API_KEY: 'invalid_api_key',
+  MISSING_API_KEY: 'missing_api_key',
+  NOT_LOGGED_IN: 'not_logged_in',
+  OUT_OF_CREDIT: 'out_of_credit',
+  RATE_LIMITED: 'rate_limited',
+  NETWORK: 'network',
+  TIMEOUT: 'timeout',
+  EMPTY_RESPONSE: 'empty_response',
+  CLI_ERROR: 'cli_error',
+};
+
+/** Redact anything that looks like a secret before output leaves the device. */
+function scrub(text) {
+  if (!text) return '';
+  return String(text)
+    .replace(/sk-[A-Za-z0-9_-]{8,}/g, 'sk-****')
+    .replace(/(api[-_ ]?key["':\s=]+)[A-Za-z0-9_-]{8,}/gi, '$1****')
+    .replace(/Bearer\s+[A-Za-z0-9._-]{8,}/gi, 'Bearer ****');
+}
+
+function tail(text, cap) {
+  const s = scrub(String(text || '').trim());
+  return s.length > cap ? '…' + s.slice(-cap) : s;
+}
+
+/**
+ * Whether this agent authenticates via API key (configured/expected) rather
+ * than a CLI login. Steers the wording for auth-flavored failures.
+ */
+function authFlavor(entry, agentEnv) {
+  const cr = (entry && entry.check_ready) || {};
+  const envCfg = (entry && entry.env_config) || [];
+  const hasKeyField = envCfg.some((f) => f && /key/i.test(f.name || ''));
+  const hasSavedKey = !!(agentEnv && (agentEnv.LLM_API_KEY || agentEnv.OPENAI_API_KEY || agentEnv.ANTHROPIC_API_KEY));
+  if (hasSavedKey || (hasKeyField && !cr.login_command)) return 'api_key';
+  if (cr.login_command) return 'cli_login';
+  return hasKeyField ? 'api_key' : 'cli_login';
+}
+
+/**
+ * Classify a failed live check into a code. Pattern-matches the combined
+ * output; callers turn the code into guidance via buildGuidance().
+ */
+function classifyFailure(output, { timedOut = false, spawnError = null } = {}) {
+  if (spawnError && /ENOENT/.test(String(spawnError))) return CODE.NOT_INSTALLED;
+  if (timedOut) return CODE.TIMEOUT;
+  const text = String(output || '').toLowerCase();
+  if (!text && spawnError) return CODE.CLI_ERROR;
+
+  if (/credit balance|insufficient[_ ]?(quota|credits|funds)|payment required|\b402\b|billing/.test(text)) return CODE.OUT_OF_CREDIT;
+  if (/rate[- ]?limit|too many requests|\b429\b|overloaded|\b529\b/.test(text)) return CODE.RATE_LIMITED;
+  if (/enotfound|econnrefused|econnreset|etimedout|eai_again|fetch failed|socket hang up|network error|self[- ]signed certificate|unable to get local issuer/.test(text)) return CODE.NETWORK;
+  if (/api key.{0,24}(not set|not found|missing)|no api key|missing api key|environment variable.{0,40}(is )?(not set|required)/.test(text)) return CODE.MISSING_API_KEY;
+  if (/invalid.{0,12}(api.?key|x-api-key|token)|incorrect api key|authentication[_ ]?error|invalid credentials|\b401\b|unauthorized|forbidden|\b403\b/.test(text)) return CODE.INVALID_API_KEY;
+  if (/not logged in|not authenticated|login required|please (log ?in|sign ?in|authenticate)|run .{0,40}login|no credentials/.test(text)) return CODE.NOT_LOGGED_IN;
+  return CODE.CLI_ERROR;
+}
+
+/** Human next-steps for a code. Plain strings, no markup, no secrets. */
+function buildGuidance(code, entry, agentEnv, extra = {}) {
+  const label = (entry && (entry.label || entry.name)) || 'This agent';
+  const type = (entry && entry.name) || 'agent';
+  const login = entry && entry.check_ready && entry.check_ready.login_command;
+  const flavor = authFlavor(entry, agentEnv);
+  const lines = [];
+  switch (code) {
+    case CODE.NOT_INSTALLED:
+      lines.push(`${label} is not installed on this device. Install it from the launcher's Install page.`);
+      if (entry && entry.install_command) lines.push(`Or install manually: ${entry.install_command}`);
+      break;
+    case CODE.INVALID_API_KEY:
+    case CODE.MISSING_API_KEY:
+      if (flavor === 'cli_login' && login) {
+        lines.push(`${label}'s sign-in looks invalid or expired. On the device, run: ${login}`);
+      } else {
+        lines.push(code === CODE.MISSING_API_KEY
+          ? `${label} has no API key configured. Add one in the launcher (Agents → ${label} → Configure) or edit the agent in the workspace and enter a key.`
+          : `${label}'s API key was rejected by the provider. Replace it in the launcher (Agents → ${label} → Configure) or edit the agent in the workspace.`);
+        lines.push(`To verify a key on the device: agn test-llm ${type}`);
+      }
+      break;
+    case CODE.NOT_LOGGED_IN:
+      lines.push(login
+        ? `${label} is not signed in on this device. In a terminal there, run: ${login}`
+        : `${label} is not signed in on this device. Sign in with its CLI, then re-run the test.`);
+      break;
+    case CODE.OUT_OF_CREDIT:
+      lines.push(`The provider account for ${label} is out of credit or quota. Add credit, or switch the agent to a different API key or model.`);
+      break;
+    case CODE.RATE_LIMITED:
+      lines.push(`The provider is rate-limiting ${label}. Wait a few minutes and test again.`);
+      break;
+    case CODE.NETWORK:
+      lines.push(`The device could not reach the model provider. Check the device's network, proxy, and firewall, then test again.`);
+      break;
+    case CODE.TIMEOUT:
+      lines.push(`${label} did not answer within ${Math.round((extra.timeoutMs || DEFAULT_TIMEOUT_MS) / 1000)}s. It may be waiting for interactive input (a first-run consent or login prompt).`);
+      lines.push(`On the device, run the agent's CLI once in a terminal to clear any prompt, then test again.`);
+      break;
+    case CODE.EMPTY_RESPONSE:
+      lines.push(`${label} exited without producing a response. Run its CLI manually on the device to see what it prints.`);
+      break;
+    case CODE.NOT_READY:
+      // Caller supplies the static-auth guidance lines instead.
+      break;
+    default:
+      lines.push(`${label} failed to respond. Run its CLI manually on the device to inspect the error.`);
+      break;
+  }
+  return lines;
+}
+
+/** Run a CLI to completion with a hard timeout. Never rejects. */
+function runCommand(cmd, args, { env, timeoutMs, shell = false }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        env,
+        cwd: os.homedir(),
+        shell,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      resolve({ code: 1, stdout: '', stderr: '', spawnError: e.message, timedOut: false });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch {}
+    }, timeoutMs);
+    const finish = (code, spawnError) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code, stdout, stderr, spawnError: spawnError || null, timedOut });
+    };
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (e) => finish(1, e.message));
+    child.on('close', (code) => finish(code == null ? 1 : code));
+  });
+}
+
+/**
+ * Smoke-test one agent type end to end. Returns a result object; never throws.
+ *
+ * @param {object} connector AgentConnector (registry/installer/env access)
+ * @param {string} type      agent type name (registry entry name)
+ * @param {object} [opts]    { timeoutMs }
+ */
+async function probeAgentType(connector, type, opts = {}) {
+  const startedAt = Date.now();
+  const done = (fields) => ({
+    type,
+    at: new Date().toISOString(),
+    durationMs: Date.now() - startedAt,
+    guidance: [],
+    ...fields,
+  });
+
+  const entry = connector.registry.getEntry(type);
+  if (!entry) {
+    return done({ ok: false, method: 'none', code: CODE.UNKNOWN_TYPE, message: `Unknown agent type '${type}'` });
+  }
+
+  let health = {};
+  try { health = connector.healthCheck(type) || {}; } catch (e) {
+    health = { installed: false, ready: false, message: e.message };
+  }
+
+  let agentEnv = {};
+  try {
+    const saved = connector.getAgentEnv(type) || {};
+    const resolved = connector.resolveAgentEnv(type, saved) || {};
+    agentEnv = { ...saved, ...resolved };
+  } catch {}
+
+  if (!health.installed) {
+    return done({
+      ok: false, method: 'none', code: CODE.NOT_INSTALLED,
+      message: 'Not installed',
+      guidance: buildGuidance(CODE.NOT_INSTALLED, entry, agentEnv),
+    });
+  }
+
+  // Definitively unconfigured (auth_status 'unknown' still gets a live try:
+  // the real run is the final authority for unverifiable logins).
+  if (!health.ready && health.auth_status !== 'unknown') {
+    let lines = [];
+    try { lines = formatAuthGuidance(entry, health).lines; } catch {}
+    return done({
+      ok: false, method: 'none', code: CODE.NOT_READY,
+      message: health.message || 'Not configured',
+      guidance: lines.length ? lines : buildGuidance(CODE.NOT_LOGGED_IN, entry, agentEnv),
+    });
+  }
+
+  const timeoutMs = opts.timeoutMs
+    || (entry.probe && entry.probe.timeout_s ? entry.probe.timeout_s * 1000 : DEFAULT_TIMEOUT_MS);
+  const env = { ...getEnhancedEnv(), ...agentEnv };
+
+  // ── Live tier 1: the agent's own CLI, when the registry declares how ──
+  const probeArgs = entry.probe && Array.isArray(entry.probe.args) ? entry.probe.args : null;
+  const altCheck = entry.check_ready && entry.check_ready.alt_check;
+  if ((probeArgs && health.binary) || altCheck) {
+    const res = probeArgs && health.binary
+      ? await runCommand(health.binary, probeArgs, { env, timeoutMs })
+      : await runCommand(altCheck, [], { env, timeoutMs, shell: true });
+    const output = `${res.stdout}\n${res.stderr}`;
+    if (!res.timedOut && !res.spawnError && res.code === 0 && res.stdout.trim()) {
+      return done({
+        ok: true, method: 'cli', code: CODE.OK,
+        message: 'Responded',
+        reply: tail(res.stdout, REPLY_CAP),
+      });
+    }
+    let code = res.code === 0 && !res.timedOut && !res.spawnError
+      ? CODE.EMPTY_RESPONSE
+      : classifyFailure(output, res);
+    // A CLI probe spawn-ENOENT despite installed=true means the binary went
+    // away between checks — report it as not installed, not a mystery error.
+    if (code === CODE.NOT_INSTALLED) {
+      return done({
+        ok: false, method: 'cli', code,
+        message: 'The agent binary could not be executed',
+        guidance: buildGuidance(code, entry, agentEnv),
+      });
+    }
+    return done({
+      ok: false, method: 'cli', code,
+      message: tail(res.stderr || res.stdout, OUTPUT_CAP) || (res.timedOut ? 'Timed out' : `Exited with code ${res.code}`),
+      guidance: buildGuidance(code, entry, agentEnv, { timeoutMs }),
+    });
+  }
+
+  // ── Live tier 2: direct LLM API call for API-key agents (e.g. OpenClaw) ──
+  const hasApiKey = !!(agentEnv.LLM_API_KEY || agentEnv.OPENAI_API_KEY || agentEnv.ANTHROPIC_API_KEY
+    || agentEnv.KIMI_API_KEY || agentEnv.MOONSHOT_API_KEY);
+  if (hasApiKey || (entry.install && entry.install.api_only)) {
+    let res;
+    try { res = await testLLMConnection(agentEnv); } catch (e) { res = { success: false, error: e.message }; }
+    if (res && res.success) {
+      return done({
+        ok: true, method: 'llm_api', code: CODE.OK,
+        message: 'Responded',
+        reply: tail(res.response || '', REPLY_CAP),
+      });
+    }
+    const code = classifyFailure(res && res.error, {});
+    return done({
+      ok: false, method: 'llm_api', code,
+      message: tail(res && res.error, OUTPUT_CAP) || 'LLM API test failed',
+      guidance: buildGuidance(code, entry, agentEnv),
+    });
+  }
+
+  // ── No safe live probe — report the static result honestly rather than
+  // inventing a CLI invocation that could misfire. ──
+  return done({
+    ok: health.ready === true, method: 'none', code: CODE.STATIC_ONLY,
+    message: health.ready
+      ? 'Static checks passed (no live probe is defined for this agent type)'
+      : (health.message || 'Not configured'),
+  });
+}
+
+module.exports = { probeAgentType, classifyFailure, buildGuidance, authFlavor, scrub, CODE, DEFAULT_TIMEOUT_MS };

package/src/registry.js

@@ -100,6 +100,7 @@ class Registry {
         if (b.install) entry.install = { ...b.install };
         if (!entry.check_ready && b.check_ready) entry.check_ready = b.check_ready;
         if (!entry.launch && b.launch) entry.launch = b.launch;
+        if (!entry.probe && b.probe) entry.probe = b.probe;
         // Always take featured/order/support from bundled (source of truth for ordering)
         if (b.featured !== undefined) entry.featured = b.featured;
         if (b.order !== undefined) entry.order = b.order;
@@ -146,6 +147,7 @@ class Registry {
       if (b.install) entry.install = { ...b.install };
       if (!entry.check_ready && b.check_ready) entry.check_ready = b.check_ready;
       if (!entry.launch && b.launch) entry.launch = b.launch;
+      if (!entry.probe && b.probe) entry.probe = b.probe;
       if ((!entry.env_config || !entry.env_config.length) && b.env_config?.length) entry.env_config = b.env_config;
     }
     return entry;