@openagents-org/agent-launcher 0.2.171 → 0.2.173

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;

package/src/workspace-client.js

@@ -517,6 +517,7 @@ class WorkspaceClient {
       role: a.role || 'member',
       status: a.status || 'offline',
       enabledSkills: a.enabled_skills || null,
+      model: a.model || null,
     }));
   }