@openagents-org/agent-launcher 0.2.143 → 0.2.146

package/src/adapters/base.js

@@ -20,9 +20,21 @@
 const { WorkspaceClient, SessionRevokedError } = require('../workspace-client');
 const { generateSessionTitle, SESSION_DEFAULT_RE } = require('./utils');
 const { defaultAgentWorkdir } = require('../paths');
+const {
+  REASON,
+  classifyJoinError,
+  classifyHeartbeatError,
+} = require('./health-status');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
 
+// Heartbeat runs every 30s. A SINGLE failure is usually a transient blip (brief
+// network hiccup, server redeploy) that the next tick recovers from — surfacing
+// it as a hard 'error' would make the agent flap red for no real reason. Only
+// after this many CONSECUTIVE failures (~60s+ of real downtime) do we report
+// heartbeat_failed up to the daemon. A success resets the streak immediately.
+const HEARTBEAT_ERROR_THRESHOLD = 2;
+
 class BaseAdapter {
   /**
    * @param {object} opts
@@ -32,7 +44,7 @@ class BaseAdapter {
    * @param {string} opts.agentName
    * @param {string} [opts.endpoint]
    */
-  constructor({ workspaceId, channelName, token, agentName, endpoint, agentEnv, agentType, workingDir }) {
+  constructor({ workspaceId, channelName, token, agentName, endpoint, agentEnv, agentType, workingDir, onStatus }) {
     this.workspaceId = workspaceId;
     this.channelName = channelName;
     this.token = token;
@@ -41,9 +53,23 @@ class BaseAdapter {
     this.agentEnv = agentEnv || process.env;
     this.agentType = agentType;
     this.workingDir = workingDir || undefined;
+    // Optional callback the daemon supplies to surface live runtime/connectivity
+    // status (reason + redacted message) into daemon.status.json so the Agents
+    // list / TUI can show the REAL failure instead of a swallowed log line. A
+    // null reason means "healthy again" (clears any prior error).
+    this._onStatus = typeof onStatus === 'function' ? onStatus : null;
+    this._lastReportedStatusKey = null;
+    // Consecutive heartbeat failures — a transient single blip must not flip the
+    // agent to a hard error (see HEARTBEAT_ERROR_THRESHOLD).
+    this._heartbeatFailStreak = 0;
+    // Structured terminal exit reason ({ reason, message }) read by the daemon
+    // after run() returns, to distinguish a clean stop from a real failure.
+    this._exitInfo = null;
+    // Set when the user explicitly stops this adapter (vs an error/revoke), so a
+    // clean stop is never mislabeled as an error.
+    this._stopRequested = false;
     this.client = new WorkspaceClient(this.endpoint);
     this._lastEventId = null;
-    this._lastToolResultId = null;
     this._running = false;
     this._sessionId = null;  // issued by server on /v1/join; used to prove liveness
     this._processedIds = new Set();
@@ -71,13 +97,62 @@ class BaseAdapter {
   }
 
   // ------------------------------------------------------------------
-  // Lifecycle
+  // Runtime status reporting (daemon surfaces this in daemon.status.json)
   // ------------------------------------------------------------------
 
-  async run() {
-    this._running = true;
+  /**
+   * Surface a live status transition to the daemon. `reason` null/'' means the
+   * agent is healthy again (clears any prior error). Deduped so a repeated
+   * failure (e.g. heartbeat every 30s on a down workspace) writes the status
+   * file once, not on every tick. Never throws — status is best-effort.
+   */
+  _reportStatus(reason, message) {
+    const key = `${reason || ''}|${message || ''}`;
+    if (key === this._lastReportedStatusKey) return;
+    this._lastReportedStatusKey = key;
+    if (!this._onStatus) return;
+    try {
+      this._onStatus({ reason: reason || null, message: message || null });
+    } catch { /* status is best-effort */ }
+  }
 
-    // Announce agent to workspace
+  /** Record the FIRST terminal failure reason; later teardown noise can't mask it. */
+  _setExitInfo(reason, message) {
+    if (!this._exitInfo) this._exitInfo = { reason, message };
+  }
+
+  /** Read by the daemon after run() returns. null = clean exit. */
+  getExitInfo() {
+    return this._exitInfo;
+  }
+
+  /** True when stop() was called explicitly (a clean user stop, not a failure). */
+  wasStopRequested() {
+    return this._stopRequested === true;
+  }
+
+  /**
+   * Preflight gate, run by the daemon BEFORE join. Default: always runnable.
+   * Subclasses whose agent needs a resolvable CLI binary override this to return
+   * { ok:false, reason:'runtime_missing', message } so the daemon surfaces a
+   * precise reason and skips the workspace join (no pointless join loop).
+   */
+  preflight() {
+    return { ok: true };
+  }
+
+  // ------------------------------------------------------------------
+  // Lifecycle
+  // ------------------------------------------------------------------
+
+  /**
+   * Announce this agent to the workspace (/v1/join). Returns true on success.
+   * On failure surfaces the REAL reason (e.g. "Workspace join failed: HTTP 401")
+   * to the daemon status instead of only logging it — non-fatal, the poll/
+   * heartbeat loops keep retrying and a later success clears it. Extracted from
+   * run() so the failure-reporting can be unit-tested without the poll loop.
+   */
+  async _joinWorkspace() {
     try {
       const joinResult = await this.client.joinNetwork(this.agentName, this.token, {
         network: this.workspaceId,
@@ -87,9 +162,21 @@ class BaseAdapter {
       });
       this._sessionId = (joinResult && joinResult.session_id) || null;
       this._log(`Joined workspace ${this.workspaceId}${this._sessionId ? ` (session ${this._sessionId.slice(0, 8)})` : ''}`);
+      this._reportStatus(null); // joined OK → clear any prior error
+      return true;
     } catch (e) {
-      this._log(`Warning: join failed: ${e.message} \nStack: ${e.stack}`);
+      const { reason, message } = classifyJoinError(e);
+      this._log(`${message} (status: ${e && e.statusCode != null ? e.statusCode : 'n/a'})`);
+      this._reportStatus(reason, message);
+      return false;
     }
+  }
+
+  async run() {
+    this._running = true;
+
+    // Announce agent to workspace
+    await this._joinWorkspace();
 
     // Sync workspace-managed skills into disabledModules
     try {
@@ -137,6 +224,7 @@ class BaseAdapter {
   }
 
   stop() {
+    this._stopRequested = true;
     this._running = false;
   }
 
@@ -164,13 +252,25 @@ class BaseAdapter {
   async _heartbeat() {
     try {
       await this.client.heartbeat(this.workspaceId, this.agentName, this.token, this._sessionId);
+      this._heartbeatFailStreak = 0;
+      this._reportStatus(null); // alive → clear any prior connectivity error
     } catch (e) {
       if (e instanceof SessionRevokedError) {
         this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`);
+        // Terminal (not a user stop): record so the daemon can show why it ended.
+        this._setExitInfo(REASON.SESSION_REVOKED, 'Workspace session revoked — another client joined with the same agent name');
+        this._reportStatus(REASON.SESSION_REVOKED, 'Workspace session revoked');
         this._running = false;
         return;
       }
-      this._log(`Heartbeat failed: ${e.message}`);
+      // Only surface a hard error after repeated consecutive failures, so a
+      // single transient blip (or an expected brief reconnect) isn't mislabeled.
+      this._heartbeatFailStreak++;
+      const { reason, message } = classifyHeartbeatError(e);
+      this._log(`${message} (consecutive failures: ${this._heartbeatFailStreak})`);
+      if (this._heartbeatFailStreak >= HEARTBEAT_ERROR_THRESHOLD) {
+        this._reportStatus(reason, message);
+      }
     }
   }
 
@@ -552,31 +652,6 @@ class BaseAdapter {
         idleCount++;
       }
 
-      // Sidecar poll: A2UI tool_result events. These are the user's response
-      // to a UI spec this agent (or any agent in the network) emitted. We
-      // surface each one as a synthetic user message so the LLM sees it as
-      // the next turn and can react. Failures here don't break the main
-      // message poll.
-      try {
-        const toolResult = await this.client.pollToolResults(
-          this.workspaceId, this.token,
-          { after: this._lastToolResultId }
-        );
-        if (toolResult.cursor) this._lastToolResultId = toolResult.cursor;
-        for (const event of toolResult.events || []) {
-          const msgId = event.id;
-          if (msgId && this._processedIds.has(msgId)) continue;
-          if (msgId) this._processedIds.add(msgId);
-          const synth = synthesizeToolResultMessage(event);
-          if (synth) await this._dispatchMessage(synth);
-        }
-      } catch (e) {
-        // Non-fatal — log once per poll if it fails
-        if (pollCount <= 3 || pollCount % 20 === 0) {
-          this._log(`tool_result poll #${pollCount} failed: ${e.message}`);
-        }
-      }
-
       // Adaptive polling with warm plateau:
       //   Active (messages incoming):  2s
       //   Warm (≤5 min since last msg): 5s
@@ -710,15 +785,10 @@ class BaseAdapter {
   }
 
   async sendThinking(channel, content) {
-    // Strip ```a2ui blocks if they leak into Claude's intermediate thinking
-    // trace — the real spec gets emitted via sendResponse with proper
-    // payload.spec extraction, so showing the raw block here is just noise
-    // (and a duplicate). If stripping leaves the thinking message empty,
-    // skip it entirely.
-    const { cleanContent } = extractA2UISpec(content);
-    if (!cleanContent || !cleanContent.trim()) return;
+    // Skip empty thinking traces entirely.
+    if (!content || !content.trim()) return;
     try {
-      await this.client.sendMessage(this.workspaceId, channel, this.token, cleanContent, {
+      await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
         senderType: 'agent',
         senderName: this.agentName,
         messageType: 'thinking',
@@ -731,14 +801,11 @@ class BaseAdapter {
   }
 
   async sendResponse(channel, content) {
-    const { cleanContent, spec, specToolCallId } = extractA2UISpec(content);
     try {
-      await this.client.sendMessage(this.workspaceId, channel, this.token, cleanContent, {
+      await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
         senderType: 'agent',
         senderName: this.agentName,
         sessionId: this._sessionId,
-        spec,
-        specToolCallId,
       });
     } catch (e) {
       if (e instanceof SessionRevokedError) {
@@ -865,74 +932,4 @@ class BaseAdapter {
   }
 }
 
-// ------------------------------------------------------------------
-// A2UI helpers
-// ------------------------------------------------------------------
-
-/**
- * Pull the first ```a2ui ... ``` fenced block out of LLM-produced content.
- * Returns the content with the block stripped, the parsed spec, and a
- * tool-call id derived from `spec.tool_call_id` (if present) or a new one.
- * If no block is present or parsing fails, returns the content unchanged
- * with null spec — the message still goes out as plain markdown.
- */
-/**
- * Convert a workspace.tool_result event into a synthetic user-message
- * shape that the agent's _handleMessage can dispatch. The LLM sees this
- * as the next user turn — the content is a short, machine-readable line
- * the LLM can parse without ambiguity. The original spec it emitted is
- * already in the LLM's conversation history; the tool_call_id lets the
- * LLM correlate this back.
- */
-function synthesizeToolResultMessage(event) {
-  if (!event || !event.payload) return null;
-  const p = event.payload;
-  const actionId = p.action_id || '';
-  const toolCallId = p.tool_call_id || '';
-  let valueStr = '';
-  if (p.value !== undefined && p.value !== null) {
-    try { valueStr = JSON.stringify(p.value); } catch (_) { valueStr = String(p.value); }
-  }
-  const lines = [
-    '[ui_action]',
-    `action=${actionId}`,
-    toolCallId ? `tool_call_id=${toolCallId}` : null,
-    valueStr ? `value=${valueStr}` : null,
-  ].filter(Boolean);
-  const content = lines.join(' ');
-  const target = event.target || '';
-  return {
-    messageId: event.id || '',
-    sessionId: target.startsWith('channel/') ? target.replace('channel/', '') : target,
-    senderType: 'human',
-    senderName: 'user',
-    content,
-    mentions: [],
-    messageType: 'chat',
-    metadata: event.metadata || {},
-  };
-}
-
-function extractA2UISpec(content) {
-  if (!content || typeof content !== 'string') {
-    return { cleanContent: content, spec: null, specToolCallId: null };
-  }
-  const match = content.match(/```a2ui\s*\n([\s\S]*?)\n```/);
-  if (!match) return { cleanContent: content, spec: null, specToolCallId: null };
-
-  let spec;
-  try {
-    spec = JSON.parse(match[1]);
-  } catch (_) {
-    return { cleanContent: content, spec: null, specToolCallId: null };
-  }
-
-  const specToolCallId = (spec && spec.tool_call_id) || `tc_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-  if (spec && spec.tool_call_id) delete spec.tool_call_id;
-
-  const cleanContent = content.replace(match[0], '').trim();
-  return { cleanContent, spec, specToolCallId };
-}
-
 module.exports = BaseAdapter;
-module.exports.extractA2UISpec = extractA2UISpec;

package/src/adapters/claude.js

@@ -19,7 +19,7 @@ const { execSync, spawn } = require('child_process');
 const BaseAdapter = require('./base');
 const { formatAttachmentsForPrompt, SESSION_DEFAULT_RE, generateSessionTitle } = require('./utils');
 const { buildClaudeSystemPrompt, buildClaudeSkillMd } = require('./workspace-prompt');
-const { defaultAgentWorkdir, whichBinary, getEnhancedEnv } = require('../paths');
+const { defaultAgentWorkdir, whichBinary, whereBinary } = require('../paths');
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -37,6 +37,12 @@ class ClaudeAdapter extends BaseAdapter {
     this._channelSessions = {}; // channel → Claude CLI session_id
     this._channelProcesses = {}; // channel → child process
     this._stoppingChannels = new Set();
+    // Channels that have already announced "Execution stopped by user." for the
+    // current stop. Two paths race to post it (the control-action handler that
+    // kills the process, and the in-flight message handler that sees
+    // pp.userStopped after exit), so this dedups to a single notice. Reset when
+    // a new message starts processing in the channel.
+    this._stopNoticeSent = new Set();
     this._persistentProcs = {}; // channel → { proc, lineBuffer, pendingLines, idleTimer, messageResolve }
     this._IDLE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour
     this._WATCHDOG_INTERVAL_MS = 15_000; // 15s between checks
@@ -84,9 +90,7 @@ class ClaudeAdapter extends BaseAdapter {
         await this._stopProcess(proc);
         delete this._channelProcesses[channel];
         delete this._channelQueues[channel];
-        try {
-          await this.sendResponse(channel, 'Execution stopped by user.');
-        } catch {}
+        await this._postStopNotice(channel);
       } else {
         for (const pp of Object.values(this._persistentProcs)) pp.userStopped = true;
         await this._stopAllProcesses('Execution stopped by user.');
@@ -258,6 +262,18 @@ class ClaudeAdapter extends BaseAdapter {
     );
   }
 
+  /**
+   * Post "Execution stopped by user." at most once per channel for a given
+   * stop. The control-action handler and the in-flight message handler both
+   * race to announce a stop; without this guard the user sees it twice. The
+   * guard is reset when a new message starts processing in the channel.
+   */
+  async _postStopNotice(channel) {
+    if (!channel || this._stopNoticeSent.has(channel)) return;
+    this._stopNoticeSent.add(channel);
+    try { await this.sendResponse(channel, 'Execution stopped by user.'); } catch {}
+  }
+
   async _stopAllProcesses(completionMessage = 'Execution stopped.') {
     for (const channel of Object.keys(this._persistentProcs)) {
       this._killPersistentProc(channel);
@@ -288,7 +304,9 @@ class ClaudeAdapter extends BaseAdapter {
     for (const c of candidates) {
       if (fs.existsSync(c)) return c;
     }
-    return 'node';
+    // Fall back to the node already running this daemon (absolute, always valid).
+    // Bare 'node' can be off-PATH in a packaged daemon or CI runner.
+    return process.execPath;
   }
 
   /**
@@ -343,24 +361,13 @@ class ClaudeAdapter extends BaseAdapter {
     const portableCandidate = path.join(portableBin, `claude${ext}`);
     if (fs.existsSync(portableCandidate)) return portableCandidate;
 
-    // Tier 1: PATH search. Use the ENRICHED env so the lookup sees the same
-    // node-version-manager / homebrew / npm-global dirs the launcher adds —
-    // a packaged Electron daemon's own PATH is minimal, which is why `which
-    // claude` came up empty and the agent reported "claude CLI not found".
-    // windowsHide stops a console window from flashing.
-    try {
-      const env = getEnhancedEnv();
-      if (IS_WINDOWS) {
-        const r = execSync('where claude.cmd 2>nul || where claude.exe 2>nul || where claude 2>nul', {
-          encoding: 'utf-8', timeout: 5000, windowsHide: true, env,
-        });
-        const hit = r.split(/\r?\n/)[0].trim();
-        if (hit) return hit;
-      } else {
-        const hit = execSync('which claude', { encoding: 'utf-8', timeout: 5000, windowsHide: true, env }).trim();
-        if (hit) return hit;
-      }
-    } catch {}
+    // Tier 1: PATH search via a codepage-safe lookup (whereBinary forces UTF-8
+    // output + verifies existence, so a non-ASCII/Chinese username isn't mangled
+    // into an ENOENT). Uses the ENRICHED env so a packaged daemon's minimal PATH
+    // still sees the node-version-manager / homebrew / npm-global dirs the
+    // launcher adds — that's why a bare `which claude` came up empty before.
+    const viaWhere = whereBinary('claude');
+    if (viaWhere) return viaWhere;
 
     // Tier 2: Next to current Node.js interpreter (npm global)
     const nodeBinDir = path.dirname(process.execPath);
@@ -558,15 +565,9 @@ class ClaudeAdapter extends BaseAdapter {
         const oaPortable = path.join(home3, '.openagents', 'nodejs', 'node_modules', '.bin', `openagents${oaExt}`);
         if (fs.existsSync(oaPortable)) oaBin = oaPortable;
       }
-      if (!oaBin) try {
-        if (IS_WINDOWS) {
-          oaBin = execSync('where openagents.cmd 2>nul || where openagents.exe 2>nul || where openagents 2>nul', {
-            encoding: 'utf-8', timeout: 5000,
-          }).split(/\r?\n/)[0].trim();
-        } else {
-          oaBin = execSync('which openagents', { encoding: 'utf-8', timeout: 5000 }).trim();
-        }
-      } catch {}
+      // Codepage-safe lookup so a non-ASCII/Chinese username in the path isn't
+      // mangled into an ENOENT (see whereBinary).
+      if (!oaBin) oaBin = whereBinary('openagents');
       if (!oaBin) {
         this._log('Could not find openagents binary — MCP tools may not be available');
         mcpCommand = 'openagents';
@@ -937,6 +938,7 @@ class ClaudeAdapter extends BaseAdapter {
 
     const msgChannel = msg.sessionId || this.channelName;
     this._stoppingChannels.delete(msgChannel);
+    this._stopNoticeSent.delete(msgChannel);
     const sender = msg.senderName || msg.senderType || 'user';
     this._log(`Processing message from ${sender} in ${msgChannel}: ${content.slice(0, 80)}...`);
 
@@ -1001,7 +1003,7 @@ class ClaudeAdapter extends BaseAdapter {
       }
       if (existingPP.userStopped) {
         if (!existingPP.everPostedAnything) {
-          try { await this.sendResponse(msgChannel, 'Execution stopped by user.'); } catch {}
+          await this._postStopNotice(msgChannel);
         }
         return;
       }
@@ -1101,7 +1103,7 @@ class ClaudeAdapter extends BaseAdapter {
           this._log(`Process exited during first message (attempt ${attempt + 1}), userStopped=${pp.userStopped}`);
           if (pp.userStopped) {
             if (!pp.everPostedAnything) {
-              try { await this.sendResponse(msgChannel, 'Execution stopped by user.'); } catch {}
+              await this._postStopNotice(msgChannel);
             }
             break;
           }