@openagents-org/agent-launcher 0.2.143 → 0.2.145

package/src/agent-rows.js

@@ -40,7 +40,16 @@ function loadAgentRows(connector) {
     let health = null;
     try {
       health = connector.healthCheck(agent.type || 'openclaw');
-      if (health && !health.ready) notReadyMsg = health.message || 'Not configured';
+      if (health && !health.ready) {
+        // "Not installed" only when the executable is genuinely missing; an
+        // installed-but-signed-out agent shows its login/config message, never
+        // "Not installed". Mirrors the launcher's formatHealthLabel rule.
+        const notInstalled =
+          health.reason === 'not_installed' || health.installed === false;
+        notReadyMsg = notInstalled
+          ? 'Not installed'
+          : health.message || 'Not configured';
+      }
     } catch {}
 
     return {
@@ -55,6 +64,9 @@ function loadAgentRows(connector) {
       path: agent.path || '',
       network: agent.network || '',
       lastError: info.last_error || '',
+      // Structured daemon failure reason (spawn_failed / workspace_join_failed /
+      // heartbeat_failed / runtime_missing / …) paired with lastError.
+      errorReason: info.error_reason || '',
       notReadyMsg,
       health,
       configured: true,

package/src/auth-guidance.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Pure, content-free helpers that turn an agent's registry `check_ready` plus a
+ * health-check result into human-readable authentication guidance.
+ *
+ * Used by the connector TUI (`showConfigureScreen`) and CLI (`agn env`) so an
+ * agent whose sign-in is an OAuth/credential FILE (e.g. Gemini's
+ * ~/.gemini/oauth_creds.json) is guided to authenticate instead of being
+ * mislabeled "No configuration required for this agent type".
+ *
+ * These helpers NEVER read, parse, copy, or print credential CONTENTS. They use
+ * only the agent's DECLARED metadata — the login command and env-var NAMES from
+ * `check_ready`, and the already-computed (non-sensitive) `message` / status
+ * fields the installer's health check returns. No token, key, email, or file
+ * path is ever emitted.
+ */
+
+/**
+ * True when an agent declares any credential / sign-in capability in
+ * `check_ready` — an OAuth/credential file, API-key env vars, a service-account
+ * path env, or a login command. This is the OPT-IN gate: agents WITHOUT any of
+ * these are left exactly as before (the caller keeps showing "No configuration
+ * required"), so other agents are never polluted by Gemini's guidance.
+ *
+ * @param {object|null|undefined} checkReady
+ * @returns {boolean}
+ */
+function hasCredentialMetadata(checkReady) {
+  if (!checkReady || typeof checkReady !== 'object') return false;
+  return !!(
+    checkReady.creds_file ||
+    (Array.isArray(checkReady.env_vars) && checkReady.env_vars.length) ||
+    (Array.isArray(checkReady.creds_path_env) && checkReady.creds_path_env.length) ||
+    checkReady.login_command
+  );
+}
+
+/**
+ * A short, NON-sensitive label for a ready auth_mode. Registry-overridable via
+ * `check_ready.auth_detected_labels` (e.g. Gemini maps cli_login → "Google
+ * account sign-in detected"). Falls back to a generic, agent-agnostic phrase so
+ * any future credential-file agent reads sensibly without extra config.
+ *
+ * @param {object} checkReady
+ * @param {string|null|undefined} authMode  'cli_login' | 'api_key' | other
+ * @returns {string}
+ */
+function readyLabel(checkReady, authMode) {
+  const labels = (checkReady && checkReady.auth_detected_labels) || {};
+  if (authMode === 'cli_login') return labels.cli_login || 'CLI sign-in detected';
+  if (authMode === 'api_key') return labels.api_key || 'API key detected';
+  return labels[authMode] || 'authenticated';
+}
+
+/**
+ * Build display lines (plain text, no markup, no secrets) describing an agent's
+ * authentication state and the concrete next step. The caller is responsible
+ * for any terminal styling.
+ *
+ * @param {object} entry   Registry catalog entry (has .label/.name/.check_ready)
+ * @param {object|null} health  Result of installer.healthCheck(type)
+ * @returns {{ ready: boolean, status: string, lines: string[] }}
+ */
+function formatAuthGuidance(entry, health) {
+  const checkReady = (entry && entry.check_ready) || {};
+  const label = (entry && (entry.label || entry.name)) || 'This agent';
+  const h = health || {};
+  const lines = [];
+
+  if (h.installed === false) {
+    lines.push(`${label} is not installed yet.`);
+    return { ready: false, status: 'not_installed', lines };
+  }
+
+  if (h.ready) {
+    lines.push(`Ready — ${readyLabel(checkReady, h.auth_mode)}.`);
+    return { ready: true, status: h.auth_status || 'ready', lines };
+  }
+
+  // Not ready: lead with the registry's own (non-sensitive) reason, then the
+  // concrete next steps derived from the DECLARED login command + env-var names.
+  if (h.message) lines.push(h.message);
+  const loginCmd = checkReady.login_command;
+  if (loginCmd) {
+    lines.push(
+      `Run \`${loginCmd}\` in your terminal and complete sign-in, then return here and refresh the agent status.`,
+    );
+  }
+  const envVars = Array.isArray(checkReady.env_vars) ? checkReady.env_vars : [];
+  if (envVars.length) {
+    lines.push(`Alternatively, configure ${envVars.join(' or ')}.`);
+  }
+  if (!lines.length) lines.push(`${label} requires authentication before use.`);
+  return { ready: false, status: h.auth_status || 'no_credentials', lines };
+}
+
+module.exports = { hasCredentialMetadata, readyLabel, formatAuthGuidance };

package/src/cli.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { AgentConnector, Daemon } = require('./index');
+const { hasCredentialMetadata, formatAuthGuidance } = require('./auth-guidance');
 
 // ---------------------------------------------------------------------------
 // Arg parsing
@@ -483,14 +484,30 @@ async function cmdEnv(connector, flags, positional) {
       const display = field.password && val ? '***' : (val || '(not set)');
       print(`  ${field.name}: ${display}  ${field.required ? '(required)' : ''}`);
     }
+    return;
+  }
+
+  // No env_config, but the agent may still require a sign-in/credential (e.g.
+  // Gemini's OAuth login). Surface readiness + login guidance from the registry
+  // check_ready rather than a misleading "No env vars configured". Gated on
+  // credential metadata so plain no-config agents keep their existing output.
+  const entry = connector.registry.getEntry(type);
+  if (hasCredentialMetadata(entry && entry.check_ready)) {
+    let health = null;
+    try { health = connector.healthCheck(type); } catch {}
+    const g = formatAuthGuidance(entry, health);
+    print(`${entry.label || type} authentication status: ${g.ready ? 'Ready' : 'Not ready'}`);
+    print('');
+    for (const line of g.lines) print(line);
+    return;
+  }
+
+  const entries = Object.entries(env);
+  if (entries.length === 0) {
+    print(`No env vars configured for ${type}`);
   } else {
-    const entries = Object.entries(env);
-    if (entries.length === 0) {
-      print(`No env vars configured for ${type}`);
-    } else {
-      for (const [k, v] of entries) {
-        print(`  ${k}: ${v}`);
-      }
+    for (const [k, v] of entries) {
+      print(`  ${k}: ${v}`);
     }
   }
 }

package/src/config.js

@@ -426,8 +426,14 @@ function parseYamlValue(val) {
   if (val === 'true') return true;
   if (val === 'false') return false;
   if (/^\d+$/.test(val)) return parseInt(val, 10);
-  if ((val.startsWith("'") && val.endsWith("'")) ||
-      (val.startsWith('"') && val.endsWith('"'))) {
+  if (val.startsWith('"') && val.endsWith('"')) {
+    // Reverse serializeYamlValue's escaping (\\ → \, \" → "). Without this a
+    // double-quoted Windows path like "D:\重要资料" (quoted because of the drive
+    // colon) round-trips to D:\\重要资料 and accumulates an extra backslash on
+    // every save/load cycle, corrupting the agent's working dir.
+    return val.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  if (val.startsWith("'") && val.endsWith("'")) {
     return val.slice(1, -1);
   }
   if (val.startsWith('{') || val.startsWith('[')) {

package/src/daemon.js

@@ -210,6 +210,7 @@ class Daemon {
         restarts: info.restarts,
         started_at: info.startedAt || null,
         last_error: info.lastError || null,
+        error_reason: info.errorReason || null,
       };
     }
     return result;
@@ -363,6 +364,9 @@ class Daemon {
       restarts: 0,
       startedAt: null,
       lastError: null,
+      // Structured failure reason (health-status REASON) paired with lastError,
+      // so the UI/TUI can classify "why" without parsing the message.
+      errorReason: null,
       proc: null,
       _backoff: 2,
     };
@@ -472,9 +476,33 @@ class Daemon {
   // Internal — adapter loop (workspace-connected agents)
   // ---------------------------------------------------------------------------
 
+  /**
+   * Apply a live status update reported by a running adapter (join/heartbeat
+   * health). A genuine failure reason → state 'error' + redacted last_error so
+   * the Agents list / TUI show the real cause; a null reason → recovered, clear
+   * the error. Ignored once the agent is stopping (a user stop must win).
+   */
+  _applyAdapterStatus(name, info, update) {
+    if (!update || this._shuttingDown || this._stoppedAgents.has(name)) return;
+    const { isErrorReason, redactDiagnostic } = require('./adapters/health-status');
+    const reason = update.reason || null;
+    if (reason && isErrorReason(reason)) {
+      info.state = 'error';
+      info.errorReason = reason;
+      info.lastError = redactDiagnostic(update.message || reason);
+    } else {
+      // Recovered / healthy again — clear any prior connectivity error.
+      if (info.state === 'error') info.state = 'running';
+      info.errorReason = null;
+      info.lastError = null;
+    }
+    this._writeStatus();
+  }
+
   async _adapterLoop(name, agentCfg, info, network) {
     const { createAdapter } = require('./adapters');
     const { skillsToDisabledModules } = require('./skill-catalog');
+    const { redactDiagnostic } = require('./adapters/health-status');
     const agentType = agentCfg.type || 'openclaw';
     const endpoint = network.endpoint || 'https://workspace-endpoint.openagents.org';
 
@@ -501,20 +529,46 @@ class Daemon {
         // .claude/skills there failed with EPERM. Root it under ~/.openagents.
         workingDir: agentCfg.path || defaultAgentWorkdir(name),
         toolMode: agentCfg.tool_mode || 'skills',
+        // Live runtime/connectivity status → daemon.status.json (Agents list/TUI).
+        onStatus: (update) => this._applyAdapterStatus(name, info, update),
       });
     } catch (e) {
-      this._log(`${name} failed to create ${agentType} adapter: ${e.message}`);
+      // A construction failure (e.g. unknown agent type in this core) is a hard
+      // error with a real cause — surface it (redacted), do not pretend stopped.
       info.state = 'error';
-      info.lastError = e.message;
+      info.errorReason = 'adapter_crashed';
+      info.lastError = redactDiagnostic(e.message || String(e));
+      this._log(`${name} failed to create ${agentType} adapter: ${info.lastError}`);
       this._writeStatus();
       return;
     }
 
+    // Preflight: when the agent's runtime binary is genuinely missing, surface a
+    // precise reason ('runtime_missing') and DO NOT join the workspace — there is
+    // no point spinning a join/poll loop that can never run the CLI. Adapters
+    // that don't override preflight() always pass.
+    try {
+      const pf =
+        typeof adapter.preflight === 'function' ? adapter.preflight() : null;
+      if (pf && pf.ok === false) {
+        info.state = 'error';
+        info.errorReason = pf.reason || 'runtime_missing';
+        info.lastError = redactDiagnostic(pf.message || 'runtime not available');
+        this._writeStatus();
+        this._log(`${name} preflight failed (${info.errorReason}): ${info.lastError}`);
+        return;
+      }
+    } catch (e) {
+      this._log(`${name} preflight error (ignored, continuing): ${e.message}`);
+    }
+
     // Store adapter reference for stop and duplicate detection
     this._adapters[name] = adapter;
 
     info.state = 'running';
     info.startedAt = new Date().toISOString();
+    info.lastError = null;
+    info.errorReason = null;
     this._writeStatus();
     this._log(`${name} adapter online → ${network.slug} (type: ${agentType})`);
 
@@ -531,14 +585,41 @@ class Daemon {
       await adapter.run();
       clearInterval(checkStop);
     } catch (e) {
-      info.lastError = (e.message || String(e)).slice(0, 200);
+      info.errorReason = info.errorReason || 'adapter_crashed';
+      info.lastError = redactDiagnostic((e.message || String(e)).slice(0, 200));
       this._log(`${name} adapter error: ${info.lastError}`);
     }
 
     delete this._adapters[name];
-    info.state = 'stopped';
+
+    // Final state: a clean stop (user stop / daemon shutdown) is NEVER an error.
+    // A terminal failure recorded by the adapter (join/heartbeat/session-revoked)
+    // or a crash surfaces as 'error' with its classified, redacted reason.
+    const userStopped =
+      this._shuttingDown ||
+      this._stoppedAgents.has(name) ||
+      (typeof adapter.wasStopRequested === 'function' && adapter.wasStopRequested());
+    if (userStopped) {
+      info.state = 'stopped';
+      info.lastError = null;
+      info.errorReason = null;
+    } else {
+      const exit =
+        (typeof adapter.getExitInfo === 'function' && adapter.getExitInfo()) ||
+        null;
+      if (exit && exit.reason) {
+        info.state = 'error';
+        info.errorReason = exit.reason;
+        info.lastError = redactDiagnostic(exit.message || exit.reason);
+      } else if (info.errorReason) {
+        // A crash, or a live error report that never recovered — keep it visible.
+        info.state = 'error';
+      } else {
+        info.state = 'stopped';
+      }
+    }
     this._writeStatus();
-    this._log(`${name} adapter stopped`);
+    this._log(`${name} adapter stopped (state: ${info.state})`);
   }
 
   // NOTE: Adapter-specific message handling (openclaw, claude, codex)