@openagents-org/agent-launcher 0.2.103 → 0.2.110

package/package.json

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

package/registry.json

@@ -136,16 +136,27 @@
       {
         "name": "OPENAI_API_KEY",
         "description": "OpenAI API key",
-        "required": true,
+        "required": false,
         "password": true
+      },
+      {
+        "name": "OPENAI_BASE_URL",
+        "description": "OpenAI-compatible base URL",
+        "required": false
       }
     ],
     "check_ready": {
-      "env_vars": [
-        "OPENAI_API_KEY"
+      "env_all": [
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL"
       ],
-      "saved_env_key": "OPENAI_API_KEY",
-      "not_ready_message": "No API key \u2014 press e to configure"
+      "saved_env_all": [
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL"
+      ],
+      "status_command": "codex login status",
+      "login_command": "codex login",
+      "not_ready_message": "Not configured. Set OPENAI_API_KEY + OPENAI_BASE_URL, or run: codex login"
     },
     "resolve_env": {
       "rules": [
@@ -525,4 +536,4 @@
       "windows": "pip install sweagent"
     }
   }
-]
+]

package/src/adapters/base.js

@@ -12,12 +12,12 @@
  *
  * Subclasses must implement _handleMessage(msg).
  *
- * Direct port of Python: src/openagents/adapters/base.py
+ * Direct port of Python: sdk/src/openagents/adapters/base.py
  */
 
 'use strict';
 
-const { WorkspaceClient } = require('../workspace-client');
+const { WorkspaceClient, SessionRevokedError } = require('../workspace-client');
 const { generateSessionTitle, SESSION_DEFAULT_RE } = require('./utils');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
@@ -43,6 +43,7 @@ class BaseAdapter {
     this.client = new WorkspaceClient(this.endpoint);
     this._lastEventId = null;
     this._running = false;
+    this._sessionId = null;  // issued by server on /v1/join; used to prove liveness
     this._processedIds = new Set();
     this._titledSessions = new Set();
     this._mode = 'execute';
@@ -65,13 +66,14 @@ class BaseAdapter {
 
     // Announce agent to workspace
     try {
-      await this.client.joinNetwork(this.agentName, this.token, {
+      const joinResult = await this.client.joinNetwork(this.agentName, this.token, {
         network: this.workspaceId,
         agentType: this.agentType || 'agent',
         serverHost: require('os').hostname(),
         workingDir: this.workingDir || process.cwd(),
       });
-      this._log(`Joined workspace ${this.workspaceId}`);
+      this._sessionId = (joinResult && joinResult.session_id) || null;
+      this._log(`Joined workspace ${this.workspaceId}${this._sessionId ? ` (session ${this._sessionId.slice(0, 8)})` : ''}`);
     } catch (e) {
       this._log(`Warning: join failed: ${e.message}`);
     }
@@ -130,8 +132,13 @@ class BaseAdapter {
 
   async _heartbeat() {
     try {
-      await this.client.heartbeat(this.workspaceId, this.agentName, this.token);
+      await this.client.heartbeat(this.workspaceId, this.agentName, this.token, this._sessionId);
     } catch (e) {
+      if (e instanceof SessionRevokedError) {
+        this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`);
+        this._running = false;
+        return;
+      }
       this._log(`Heartbeat failed: ${e.message}`);
     }
   }
@@ -312,8 +319,11 @@ class BaseAdapter {
         senderName: this.agentName,
         messageType: 'status',
         metadata: { agent_mode: this._mode },
+        sessionId: this._sessionId,
       });
-    } catch {}
+    } catch (e) {
+      if (e instanceof SessionRevokedError) this._onSessionRevoked();
+    }
   }
 
   async sendThinking(channel, content) {
@@ -323,15 +333,27 @@ class BaseAdapter {
         senderName: this.agentName,
         messageType: 'thinking',
         metadata: { agent_mode: this._mode },
+        sessionId: this._sessionId,
       });
-    } catch {}
+    } catch (e) {
+      if (e instanceof SessionRevokedError) this._onSessionRevoked();
+    }
   }
 
   async sendResponse(channel, content) {
-    await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
-      senderType: 'agent',
-      senderName: this.agentName,
-    });
+    try {
+      await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
+        senderType: 'agent',
+        senderName: this.agentName,
+        sessionId: this._sessionId,
+      });
+    } catch (e) {
+      if (e instanceof SessionRevokedError) {
+        this._onSessionRevoked();
+        return;
+      }
+      throw e;
+    }
   }
 
   async sendError(channel, error) {
@@ -339,8 +361,16 @@ class BaseAdapter {
       await this.client.sendMessage(this.workspaceId, channel, this.token, error, {
         senderType: 'agent',
         senderName: this.agentName,
+        sessionId: this._sessionId,
       });
-    } catch {}
+    } catch (e) {
+      if (e instanceof SessionRevokedError) this._onSessionRevoked();
+    }
+  }
+
+  _onSessionRevoked() {
+    this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`);
+    this._running = false;
   }
 
   // ------------------------------------------------------------------

package/src/adapters/claude.js

@@ -6,7 +6,7 @@
  * - Claude CLI subprocess (stream-json) for task execution
  * - MCP server for workspace tool access
  *
- * Direct port of Python: src/openagents/adapters/claude.py
+ * Direct port of Python: sdk/src/openagents/adapters/claude.py
  */
 
 'use strict';
@@ -272,72 +272,56 @@ class ClaudeAdapter extends BaseAdapter {
     if (this.disabledModules.has('files')) mcpArgs.push('--disable-files');
     if (this.disabledModules.has('browser')) mcpArgs.push('--disable-browser');
 
-    // Find openagents binary (multi-tier)
-    let oaBin = null;
-    const home3 = os.homedir();
-    // Tier 0: Check all isolated runtime prefixes for openagents binary
-    const oaExt = IS_WINDOWS ? '.cmd' : '';
-    const runtimesRoot = path.join(home3, '.openagents', 'runtimes');
-    try {
-      for (const d of fs.readdirSync(runtimesRoot, { withFileTypes: true })) {
-        if (d.isDirectory()) {
-          const candidate = path.join(runtimesRoot, d.name, 'node_modules', '.bin', `openagents${oaExt}`);
-          if (fs.existsSync(candidate)) { oaBin = candidate; break; }
+    // Resolve the MCP server entry point. Prefer the sibling bin inside this
+    // very package — it's guaranteed to exist whenever claude.js is executing,
+    // so it never falls through to a broken PATH lookup. If Claude Code can't
+    // spawn the MCP server, it silently hides every workspace tool and the
+    // agent reports "workspace_read_file isn't in my tool set".
+    let mcpCommand = this._findNodeBin();
+    let mcpFinalArgs = mcpArgs;
+    const siblingBin = path.resolve(__dirname, '..', '..', 'bin', 'agent-connector.js');
+    if (fs.existsSync(siblingBin)) {
+      mcpFinalArgs = [siblingBin, ...mcpArgs];
+    } else {
+      // Fallback: search installed locations (older layouts, global installs)
+      let oaBin = null;
+      const home3 = os.homedir();
+      const oaExt = IS_WINDOWS ? '.cmd' : '';
+      const runtimesRoot = path.join(home3, '.openagents', 'runtimes');
+      try {
+        for (const d of fs.readdirSync(runtimesRoot, { withFileTypes: true })) {
+          if (d.isDirectory()) {
+            const candidate = path.join(runtimesRoot, d.name, 'node_modules', '.bin', `openagents${oaExt}`);
+            if (fs.existsSync(candidate)) { oaBin = candidate; break; }
+          }
         }
+      } catch {}
+      if (!oaBin) {
+        const oaPortable = path.join(home3, '.openagents', 'nodejs', 'node_modules', '.bin', `openagents${oaExt}`);
+        if (fs.existsSync(oaPortable)) oaBin = oaPortable;
       }
-    } catch {}
-    // Tier 0b: Legacy portable install
-    if (!oaBin) {
-      const oaPortable = path.join(home3, '.openagents', 'nodejs', 'node_modules', '.bin', `openagents${oaExt}`);
-      if (fs.existsSync(oaPortable)) oaBin = oaPortable;
-    }
-    // Tier 1: PATH
-    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();
+      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 {}
+      if (!oaBin) {
+        this._log('Could not find openagents binary — MCP tools may not be available');
+        mcpCommand = 'openagents';
       } else {
-        oaBin = execSync('which openagents', { encoding: 'utf-8', timeout: 5000 }).trim();
-      }
-    } catch {}
-    // Tier 2: Next to Node.js
-    if (!oaBin) {
-      const nodeBinDir2 = path.dirname(process.execPath);
-      const oaExt = IS_WINDOWS ? '.cmd' : '';
-      const nearNode2 = path.join(nodeBinDir2, `openagents${oaExt}`);
-      if (fs.existsSync(nearNode2)) oaBin = nearNode2;
-    }
-    // Tier 3: Common locations
-    if (!oaBin) {
-      const home2 = os.homedir();
-      const oaCandidates = IS_WINDOWS ? [
-        path.join(process.env.APPDATA || '', 'npm', 'openagents.cmd'),
-      ] : [
-        path.join(home2, '.openagents', 'npm-global', 'bin', 'openagents'),
-        path.join(home2, '.local', 'bin', 'openagents'),
-        path.join(home2, '.npm-global', 'bin', 'openagents'),
-        '/opt/homebrew/bin/openagents',
-        '/usr/local/bin/openagents',
-      ];
-      for (const c of oaCandidates) {
-        if (fs.existsSync(c)) { oaBin = c; break; }
+        const resolved = this._resolveToNodeCmd(oaBin);
+        if (resolved) {
+          mcpCommand = resolved[0];
+          mcpFinalArgs = [resolved[1], ...mcpArgs];
+        } else {
+          mcpCommand = oaBin;
+        }
       }
     }
-    if (!oaBin) {
-      oaBin = 'openagents';
-      this._log('Could not find openagents binary — MCP tools may not be available');
-    }
-
-    // Resolve shim/symlink to node + JS entry point for MCP server
-    // (.cmd shims and #!/usr/bin/env node shebangs both fail as MCP commands)
-    let mcpCommand = oaBin;
-    let mcpFinalArgs = mcpArgs;
-    const mcpResolved = this._resolveToNodeCmd(oaBin);
-    if (mcpResolved) {
-      mcpCommand = mcpResolved[0];
-      mcpFinalArgs = [mcpResolved[1], ...mcpArgs];
-    }
 
     const mcpConfig = {
       mcpServers: {

package/src/adapters/codex.js

@@ -140,7 +140,18 @@ class CodexAdapter extends BaseAdapter {
     const nearNode = path.join(nodeBinDir, `codex${ext}`);
     if (fs.existsSync(nearNode)) return nearNode;
 
-    // Tier 3: Common install locations
+    // Tier 3: npm global prefix (handles custom npm prefix like D:\node\node_global)
+    try {
+      const npmPrefix = execSync('npm config get prefix', {
+        encoding: 'utf-8', timeout: 5000, windowsHide: true,
+      }).trim();
+      if (npmPrefix) {
+        const prefixCandidate = path.join(npmPrefix, `codex${ext}`);
+        if (fs.existsSync(prefixCandidate)) return prefixCandidate;
+      }
+    } catch {}
+
+    // Tier 4: Common install locations
     const candidates = IS_WINDOWS ? [
       path.join(process.env.APPDATA || '', 'npm', 'codex.cmd'),
     ] : [
@@ -265,12 +276,10 @@ class CodexAdapter extends BaseAdapter {
         cmd.push('-C', this.workingDir);
       }
 
-      cmd.push(fullPrompt);
-
       this._log(`Spawning: codex exec ${threadId && attempt === 0 ? `resume ${threadId} ` : ''}--json --full-auto -m ${this._directModel || 'default'}`);
 
       try {
-        const result = await this._spawnCodex(cmd, env, msgChannel);
+        const result = await this._spawnCodex(cmd, env, msgChannel, fullPrompt);
 
         if (result.responseText) {
           await this.sendResponse(msgChannel, result.responseText);
@@ -293,14 +302,15 @@ class CodexAdapter extends BaseAdapter {
     }
   }
 
-  async _spawnCodex(cmd, env, msgChannel) {
+  async _spawnCodex(cmd, env, msgChannel, prompt) {
     return new Promise((resolve, reject) => {
       const proc = spawn(cmd[0], cmd.slice(1), {
-        stdio: ['ignore', 'pipe', 'pipe'],
+        stdio: ['pipe', 'pipe', 'pipe'],
         env,
         cwd: this.workingDir,
         detached: !IS_WINDOWS,
         windowsHide: true,
+        shell: IS_WINDOWS,
       });
       this._channelProcesses[msgChannel] = proc;
 
@@ -314,6 +324,11 @@ class CodexAdapter extends BaseAdapter {
         proc.stderr.on('data', (chunk) => { stderrBuf += chunk.toString('utf-8'); });
       }
 
+      if (proc.stdin) {
+        proc.stdin.write(prompt || '', 'utf-8');
+        proc.stdin.end();
+      }
+
       const processLine = async (line) => {
         line = line.trim();
         if (!line) return;

package/src/adapters/cursor.js

@@ -2,7 +2,7 @@
  * Cursor adapter — AI-powered code editor agent mode.
  *
  * Uses direct LLM API mode (OpenAI-compatible chat completions).
- * Port of Python: src/openagents/adapters/cursor.py
+ * Port of Python: sdk/src/openagents/adapters/cursor.py
  */
 
 'use strict';

package/src/adapters/llm-direct.js

@@ -4,7 +4,7 @@
  * Calls OpenAI-compatible chat completions API directly with SSE streaming.
  * No CLI binary needed — just OPENAI_API_KEY + OPENAI_BASE_URL.
  *
- * Port of Python: src/openagents/adapters/nanoclaw.py & cursor.py
+ * Port of Python: sdk/src/openagents/adapters/nanoclaw.py & cursor.py
  */
 
 'use strict';

package/src/adapters/nanoclaw.js

@@ -2,7 +2,7 @@
  * NanoClaw adapter — lightweight containerized coding agent.
  *
  * Uses direct LLM API mode (OpenAI-compatible chat completions).
- * Port of Python: src/openagents/adapters/nanoclaw.py
+ * Port of Python: sdk/src/openagents/adapters/nanoclaw.py
  */
 
 'use strict';

package/src/adapters/openclaw.js

@@ -5,7 +5,7 @@
  * - CLI mode: `openclaw agent --local --json` (preferred)
  * - Workspace context injected via SKILL.md auto-discovery
  *
- * Direct port of Python: src/openagents/adapters/openclaw.py
+ * Direct port of Python: sdk/src/openagents/adapters/openclaw.py
  * (CLI mode only — gateway WS and direct HTTP modes are not yet ported)
  */
 

package/src/adapters/opencode.js

@@ -5,7 +5,7 @@
  * `opencode run --format json` as a subprocess. OpenCode handles its own
  * model configuration, provider selection, and tool chain.
  *
- * Port of Python PR #316: src/openagents/adapters/opencode.py
+ * Port of Python PR #316: sdk/src/openagents/adapters/opencode.py
  */
 
 'use strict';

package/src/adapters/utils.js

@@ -1,7 +1,7 @@
 /**
  * Shared utilities for adapter implementations.
  *
- * Direct port of Python: src/openagents/adapters/utils.py
+ * Direct port of Python: sdk/src/openagents/adapters/utils.py
  */
 
 'use strict';

package/src/adapters/workspace-prompt.js

@@ -6,7 +6,7 @@
  * - Multi-agent collaboration (@mention delegation)
  * - Workspace REST API skills (files, browser, tunnels)
  *
- * Direct port of Python: src/openagents/adapters/workspace_prompt.py
+ * Direct port of Python: sdk/src/openagents/adapters/workspace_prompt.py
  */
 
 'use strict';
@@ -21,8 +21,12 @@ function buildWorkspaceIdentity(agentName, workspaceId, channelName, mode = 'exe
     '— just write your answer naturally.\n\n' +
     '## Workspace Context\n' +
     `- Workspace ID: ${workspaceId}\n` +
-    `- Channel: ${channelName}\n` +
-    `- Mode: ${mode}\n`
+    `- Channel: ${channelName}  (this is the channel you are currently speaking in)\n` +
+    `- Mode: ${mode}\n\n` +
+    'When you need prior context, call `workspace_get_history` with ' +
+    `\`channel="${channelName}"\` (the current channel). Without the ` +
+    'channel argument the tool falls back to a default channel that may ' +
+    'be different from where you are.\n'
   );
 }
 

package/src/daemon.js

@@ -30,6 +30,7 @@ class Daemon {
     this._shuttingDown = false;
     this._statusInterval = null;
     this._cmdInterval = null;
+    this._reloadInFlight = null;  // serialize concurrent _reload() calls
   }
 
   // ---------------------------------------------------------------------------
@@ -182,6 +183,22 @@ class Daemon {
     const bin = execPath || process.execPath;
 
     fs.mkdirSync(configDir, { recursive: true });
+
+    // Refuse to start if an existing daemon is already running.
+    // Without this check, repeated `agn up` invocations would spawn
+    // multiple daemons that each process the same message → duplicate
+    // bot replies.
+    const existingPid = Daemon._readPid(pidFile);
+    if (existingPid && Daemon._isAlive(existingPid)) {
+      console.error(`Daemon already running (PID ${existingPid}).`);
+      console.error(`Run 'agn down' first, or 'agn status' to check.`);
+      process.exit(1);
+    }
+    // Stale pid file — clean up before spawning fresh
+    if (existingPid) {
+      try { fs.unlinkSync(pidFile); } catch {}
+    }
+
     const logFd = fs.openSync(logFile, 'a');
 
     // Build env with enhanced PATH (ensures node/npm are findable)
@@ -636,6 +653,27 @@ class Daemon {
   }
 
   async _reload() {
+    // Serialize reloads. fs.watch, the 'reload' command, and SIGHUP can
+    // all fire concurrently. Without a mutex, two _reload() calls in flight
+    // may both observe the same stale `this._adapters[name]` entry between
+    // stopAgent() and _launchAgent(), leaving a ghost adapter running
+    // alongside the new one → duplicate bot replies per message.
+    if (this._reloadInFlight) {
+      // Wait for the in-flight reload to finish, then run once more
+      // (the config may have changed again since it started).
+      this._reloadInFlight = this._reloadInFlight.then(
+        () => this._reloadUnsafe(),
+        () => this._reloadUnsafe(),
+      );
+      return this._reloadInFlight;
+    }
+    this._reloadInFlight = this._reloadUnsafe().finally(() => {
+      this._reloadInFlight = null;
+    });
+    return this._reloadInFlight;
+  }
+
+  async _reloadUnsafe() {
     this._log('Reloading config...');
     const oldNames = this._cachedAgentNames || new Set();
     const oldConfigs = this._cachedAgentConfigs || {};
@@ -657,12 +695,14 @@ class Daemon {
     // Start new agents or restart agents whose network changed
     for (const agent of newAgents) {
       if (!oldNames.has(agent.name)) {
+        await this._ensureAdapterCleared(agent.name);
         this._launchAgent(agent);
         this._log(`Reload: started new agent '${agent.name}'`);
       } else if ((oldConfigs[agent.name] || '') !== (agent.network || '')) {
         // Network config changed — restart agent
         await this.stopAgent(agent.name);
         this._stoppedAgents.delete(agent.name);
+        await this._ensureAdapterCleared(agent.name);
         this._launchAgent(agent);
         this._log(`Reload: restarted '${agent.name}' (network changed)`);
       }
@@ -673,6 +713,28 @@ class Daemon {
     this._writeStatus();
   }
 
+  /**
+   * Wait until the old adapter (if any) has fully released its slot in
+   * this._adapters before relaunching. stopAgent already waits up to 5s,
+   * but on slow shutdowns that can be too short — and _launchAgent's
+   * duplicate-check would then silently skip the relaunch, leaving the
+   * OLD adapter running instead of starting the new one.
+   */
+  async _ensureAdapterCleared(name) {
+    for (let i = 0; i < 20; i++) {
+      if (!this._adapters || !this._adapters[name]) return;
+      await this._sleep(500);
+    }
+    // Last resort: force-clear the slot so the new adapter can start.
+    // The old adapter will exit on its next poll iteration since its
+    // entry in _stoppedAgents triggers adapter.stop() via checkStop.
+    if (this._adapters && this._adapters[name]) {
+      this._log(`WARNING: adapter '${name}' did not clear after 10s — force-releasing slot to avoid duplicate`);
+      try { this._adapters[name].stop(); } catch {}
+      delete this._adapters[name];
+    }
+  }
+
   _writePid() {
     try {
       fs.writeFileSync(this.config.pidFile, String(process.pid), 'utf-8');

package/src/identity.js

@@ -3,7 +3,7 @@
 /**
  * Local identity management (~/.openagents/identity.json).
  *
- * Port of Python: src/openagents/client/workspace_client.py (identity section)
+ * Port of Python: sdk/src/openagents/client/workspace_client.py (identity section)
  */
 
 const fs = require('fs');

package/src/installer.js

@@ -5,6 +5,10 @@ const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
 const { whichBinary, getEnhancedEnv, getRuntimePrefix } = require('./paths');
+const { EnvManager } = require('./env');
+
+const STATUS_CACHE_TTL_MS = 10000;
+const statusCache = new Map();
 
 /**
  * Manages installation and uninstallation of agent runtimes.
@@ -19,6 +23,7 @@ class Installer {
     this.configDir = configDir;
     this.markersFile = path.join(configDir, 'installed_agents.json');
     this.markersDir = path.join(configDir, 'installed');
+    this.env = new EnvManager(configDir);
   }
 
   /**
@@ -131,7 +136,17 @@ class Installer {
    */
   healthCheck(agentType) {
     const binary = this._whichBinary(agentType);
-    if (!binary) return { installed: false, binary: null, version: null };
+    if (!binary) {
+      return {
+        installed: false,
+        binary: null,
+        version: null,
+        ready: false,
+        auth_mode: null,
+        execution_mode: 'unavailable',
+        message: 'Not installed',
+      };
+    }
 
     const entry = this.registry.getEntry(agentType);
     const checkCmd = entry && entry.install ? entry.install.check_command : null;
@@ -150,51 +165,152 @@ class Installer {
       version = match ? match[1] : raw.split('\n')[0];
     } catch {}
 
-    // Check login/ready status if check_ready is defined
-    let ready = true;
+    const readiness = this._evaluateReadiness(agentType, entry, binary);
+    return { installed: true, binary, version, ...readiness };
+  }
+
+  _evaluateReadiness(agentType, entry, binary) {
     const checkReady = entry?.check_ready;
-    if (checkReady) {
-      ready = false;
-      // Check env vars
-      if (checkReady.env_vars) {
-        for (const v of checkReady.env_vars) {
-          if (process.env[v]) { ready = true; break; }
+    if (!checkReady) {
+      return {
+        ready: true,
+        auth_mode: null,
+        execution_mode: 'unavailable',
+        message: 'Ready',
+      };
+    }
+
+    const savedEnv = this.env.getEffective(agentType, this.registry);
+    const directEnv = this._hasAllValues(process.env, checkReady.env_all);
+    const directSaved = this._hasAllValues(savedEnv, checkReady.saved_env_all || checkReady.env_all);
+    const directReady = directEnv || directSaved;
+    const envAnyReady = this._hasAnyValue(process.env, checkReady.env_vars);
+    const savedAnyReady = !!(checkReady.saved_env_key && savedEnv[checkReady.saved_env_key]);
+    const credsReady = this._checkCredsReady(checkReady);
+
+    let cliReady = false;
+    if (checkReady.status_command && binary) {
+      cliReady = this._checkStatusCommand(checkReady.status_command);
+    }
+
+    if (directReady) {
+      return {
+        ready: true,
+        auth_mode: 'api_key',
+        execution_mode: 'direct',
+        message: 'Ready',
+      };
+    }
+
+    if (cliReady) {
+      return {
+        ready: true,
+        auth_mode: 'cli_login',
+        execution_mode: 'subprocess',
+        message: 'Ready',
+      };
+    }
+
+    if (envAnyReady || savedAnyReady) {
+      // Legacy single-key path (e.g. agents that only advertise env_vars / saved_env_key).
+      // An API key being present means the agent can be launched with it in the environment,
+      // so treat this as a direct-launch configuration.
+      return {
+        ready: true,
+        auth_mode: 'api_key',
+        execution_mode: 'direct',
+        message: 'Ready',
+      };
+    }
+
+    if (credsReady) {
+      return {
+        ready: true,
+        auth_mode: 'cli_login',
+        execution_mode: 'subprocess',
+        message: 'Ready',
+      };
+    }
+
+    return {
+      ready: false,
+      auth_mode: null,
+      execution_mode: 'unavailable',
+      message: checkReady.not_ready_message || 'Not configured',
+    };
+  }
+
+  _hasAllValues(source, keys) {
+    if (!keys || keys.length === 0) return false;
+    return keys.every((key) => !!(source && source[key]));
+  }
+
+  _hasAnyValue(source, keys) {
+    if (!keys || keys.length === 0) return false;
+    return keys.some((key) => !!(source && source[key]));
+  }
+
+  _checkCredsReady(checkReady) {
+    if (checkReady.creds_file) {
+      try {
+        const credsPath = checkReady.creds_file.replace('~', os.homedir());
+        if (fs.existsSync(credsPath)) {
+          const stat = fs.statSync(credsPath);
+          if (stat.isDirectory()) return fs.readdirSync(credsPath).length > 0;
+          const creds = JSON.parse(fs.readFileSync(credsPath, 'utf-8'));
+          if (checkReady.creds_key) return !!creds[checkReady.creds_key];
+          return true;
         }
+      } catch {}
+    }
+
+    if (checkReady.keychain_service && process.platform === 'darwin') {
+      if (this._checkMacKeychain(checkReady.keychain_service, checkReady.creds_key)) {
+        return true;
       }
-      // Check credentials file or directory
-      if (!ready && checkReady.creds_file) {
-        try {
-          const credsPath = checkReady.creds_file.replace('~', os.homedir());
-          if (fs.existsSync(credsPath)) {
-            const stat = fs.statSync(credsPath);
-            if (stat.isDirectory()) {
-              // Directory exists — check if it has files (e.g. session files)
-              ready = fs.readdirSync(credsPath).length > 0;
-            } else {
-              // File — parse JSON and check key
-              const creds = JSON.parse(fs.readFileSync(credsPath, 'utf-8'));
-              if (checkReady.creds_key) {
-                ready = !!creds[checkReady.creds_key];
-              } else {
-                ready = true;
-              }
-            }
-          }
-        } catch {}
-      }
-      // Also check OAuth credentials (Claude Code stores tokens in .credentials.json)
-      if (!ready) {
-        try {
-          const oauthFile = path.join(os.homedir(), '.claude', '.credentials.json');
-          if (fs.existsSync(oauthFile)) {
-            const creds = JSON.parse(fs.readFileSync(oauthFile, 'utf-8'));
-            if (creds.claudeAiOauth?.accessToken) ready = true;
-          }
-        } catch {}
-      }
     }
 
-    return { installed: true, binary, version, ready };
+    return false;
+  }
+
+  /**
+   * Check a macOS Keychain generic-password entry. If creds_key is provided the
+   * stored value is parsed as JSON and required to contain that key; otherwise any
+   * non-empty value counts as ready. Returns false on non-macOS or on any error.
+   */
+  _checkMacKeychain(service, credsKey) {
+    try {
+      const stdout = execSync(
+        `security find-generic-password -s ${JSON.stringify(service)} -w`,
+        { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf-8' },
+      ).trim();
+      if (!stdout) return false;
+      if (!credsKey) return true;
+      const creds = JSON.parse(stdout);
+      return !!creds[credsKey];
+    } catch {
+      return false;
+    }
+  }
+
+  _checkStatusCommand(command) {
+    const cached = statusCache.get(command);
+    if (cached && (Date.now() - cached.ts) < STATUS_CACHE_TTL_MS) {
+      return cached.ok;
+    }
+
+    let ok = false;
+    try {
+      execSync(command, {
+        stdio: 'ignore',
+        timeout: 5000,
+        env: getEnhancedEnv(),
+      });
+      ok = true;
+    } catch {}
+
+    statusCache.set(command, { ok, ts: Date.now() });
+    return ok;
   }
 
   /**

package/src/mcp-server.js

@@ -27,11 +27,12 @@ function buildToolDefs(disabledModules) {
     // -- Workspace core (always enabled) --
     {
       name: 'workspace_get_history',
-      description: 'Read recent messages in the current workspace channel.',
+      description: 'Read recent messages in a workspace channel. Defaults to the current channel; pass channel to query another.',
       inputSchema: {
         type: 'object',
         properties: {
           limit: { type: 'integer', description: 'Number of messages to return (default 20)', default: 20 },
+          channel: { type: 'string', description: 'Channel name (e.g. "channel-9bcd8e66"); omit to use the current channel.' },
         },
       },
     },
@@ -341,7 +342,8 @@ class McpServer {
 
       case 'workspace_get_history': {
         const limit = args.limit || 20;
-        const data = await this.ws.pollMessages(this.workspaceId, this.channelName, this.token, { limit });
+        const channel = args.channel || this.channelName;
+        const data = await this.ws.pollMessages(this.workspaceId, channel, this.token, { limit });
         const events = data.events || data || [];
         if (!events.length) return text('No messages yet.');
         const lines = events.map((e) => {

package/src/paths.js

@@ -139,9 +139,18 @@ function _addWindowsPaths(dirs) {
   // System32 (cmd.exe, powershell, etc) — Electron may not have it
   _push(dirs, path.join(sysRoot, 'System32'));
 
-  // npm global bin
+  // npm global bin (default location)
   if (appData) _push(dirs, path.join(appData, 'npm'));
 
+  // npm global bin (custom prefix — e.g. user configured npm prefix to D:\node\node_global)
+  try {
+    const npmPrefix = execSync('npm config get prefix', {
+      encoding: 'utf-8', timeout: 5000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (npmPrefix) _push(dirs, npmPrefix);
+  } catch {}
+
   // Portable Node.js installed by OpenAgents Launcher
   _push(dirs, path.join(HOME, '.openagents', 'nodejs'));
 

package/src/tui.js

@@ -85,54 +85,11 @@ function loadAgentRows(connector) {
         workspace = agent.network;
       }
     }
-    // Check if agent type needs configuration (API key etc.)
     let notReadyMsg = '';
+    let health = null;
     try {
-      const agentType = agent.type || 'openclaw';
-      const entry = connector.registry.getEntry(agentType);
-      if (entry && entry.check_ready) {
-        const cr = entry.check_ready;
-        let isReady = false;
-        // Check saved env
-        if (cr.saved_env_key) {
-          const saved = connector.env.load(agentType);
-          if (saved[cr.saved_env_key]) isReady = true;
-        }
-        // Check process env vars
-        if (!isReady && cr.env_vars) {
-          for (const v of cr.env_vars) {
-            if (process.env[v]) { isReady = true; break; }
-          }
-        }
-        // Check creds file/directory (for claude)
-        if (!isReady && cr.creds_file) {
-          const credsPath = cr.creds_file.replace('~', process.env.HOME || process.env.USERPROFILE || '');
-          try {
-            if (fs.existsSync(credsPath)) {
-              const stat = fs.statSync(credsPath);
-              if (stat.isDirectory()) {
-                // Directory (e.g. ~/.claude/sessions) — check if it has files
-                isReady = fs.readdirSync(credsPath).length > 0;
-              } else {
-                const creds = JSON.parse(fs.readFileSync(credsPath, 'utf-8'));
-                if (cr.creds_key) isReady = !!creds[cr.creds_key];
-                else isReady = true;
-              }
-            }
-          } catch {}
-        }
-        // Also check OAuth credentials (Claude Code stores tokens in .credentials.json)
-        if (!isReady) {
-          try {
-            const oauthFile = path.join(process.env.HOME || '', '.claude', '.credentials.json');
-            if (fs.existsSync(oauthFile)) {
-              const creds = JSON.parse(fs.readFileSync(oauthFile, 'utf-8'));
-              if (creds.claudeAiOauth && creds.claudeAiOauth.accessToken) isReady = true;
-            }
-          } catch {}
-        }
-        if (!isReady) notReadyMsg = cr.not_ready_message || 'Not configured';
-      }
+      health = connector.healthCheck(agent.type || 'openclaw');
+      if (health && !health.ready) notReadyMsg = health.message || 'Not configured';
     } catch {}
 
     return {
@@ -144,11 +101,24 @@ function loadAgentRows(connector) {
       network: agent.network || '',
       lastError: info.last_error || '',
       notReadyMsg,
+      health,
       configured: true,
     };
   });
 }
 
+function describeHealth(health) {
+  if (!health) return '';
+  if (!health.ready) return health.message || 'Not configured';
+  const parts = ['Ready'];
+  if (health.auth_mode === 'api_key') parts.push('API key');
+  else if (health.auth_mode === 'cli_login') parts.push('CLI login');
+  if (health.execution_mode && health.execution_mode !== 'unavailable') {
+    parts.push(health.execution_mode);
+  }
+  return parts.join(' | ');
+}
+
 function loadCatalog(connector) {
   const { execSync } = require('child_process');
   const entries = connector.registry.getCatalogSync();
@@ -372,6 +342,7 @@ function createTUI() {
         // Detail row: working dir + config warning
         const details = [];
         details.push(r.path || process.env.HOME || '~');
+        if (r.health) details.push(`{cyan-fg}${describeHealth(r.health)}{/cyan-fg}`);
         if (r.notReadyMsg) details.push(`{yellow-fg}⚠ ${r.notReadyMsg}{/yellow-fg}`);
         items.push(`  {gray-fg}  ${details.join('  |  ')}{/gray-fg}`);
       }

package/src/workspace-client.js

@@ -5,6 +5,19 @@ const http = require('http');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
 
+/**
+ * Thrown when the workspace rejects a request because our session_id has
+ * been revoked by a newer /v1/join as the same agent. Callers should
+ * stop the adapter rather than retry.
+ */
+class SessionRevokedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SessionRevokedError';
+    this.code = 'session_revoked';
+  }
+}
+
 /**
  * HTTP client for workspace API operations.
  *
@@ -84,12 +97,18 @@ class WorkspaceClient {
 
   /**
    * Send heartbeat via POST /v1/heartbeat.
+   *
+   * @param {string} [sessionId] - optional session id returned by /v1/join.
+   *   If the server's current session for this agent differs, _post()
+   *   throws SessionRevokedError and the caller should stop its adapter.
    */
-  async heartbeat(workspaceId, agentName, token) {
-    const data = await this._post('/v1/heartbeat', {
+  async heartbeat(workspaceId, agentName, token, sessionId) {
+    const body = {
       agent_name: agentName,
       network: workspaceId,
-    }, this._wsHeaders(token));
+    };
+    if (sessionId) body.session_id = sessionId;
+    const data = await this._post('/v1/heartbeat', body, this._wsHeaders(token));
     return data.data || data;
   }
 
@@ -107,9 +126,15 @@ class WorkspaceClient {
 
   /**
    * Post a raw event via POST /v1/events.
+   *
+   * @param {string} [sessionId] - if given, embedded in event.metadata so
+   *   the server can reject stale sessions with SessionRevokedError.
    */
-  async sendEvent(workspaceId, event, token) {
+  async sendEvent(workspaceId, event, token, sessionId) {
     event.network = workspaceId;
+    if (sessionId) {
+      event.metadata = { ...(event.metadata || {}), session_id: sessionId };
+    }
     const data = await this._post('/v1/events', event, this._wsHeaders(token));
     return data.data || data;
   }
@@ -118,7 +143,7 @@ class WorkspaceClient {
    * Send a chat message to a workspace channel.
    */
   async sendMessage(workspaceId, channelName, token, content, {
-    senderType = 'agent', senderName, messageType = 'chat', metadata, attachments,
+    senderType = 'agent', senderName, messageType = 'chat', metadata, attachments, sessionId,
   } = {}) {
     const sourcePrefix = senderType === 'agent' ? 'openagents' : 'human';
     const source = senderName ? `${sourcePrefix}:${senderName}` : `${sourcePrefix}:unknown`;
@@ -132,7 +157,7 @@ class WorkspaceClient {
       target: `channel/${channelName}`,
       payload,
       metadata: metadata || {},
-    }, token);
+    }, token, sessionId);
   }
 
   /**
@@ -175,24 +200,41 @@ class WorkspaceClient {
       cursor = events[events.length - 1].id || null;
     }
 
-    // Filter for messages targeted at this agent
+    // Filter for messages targeted at this agent.
+    //
+    // target_agents semantics:
+    //   • absent            → legacy server with no routing decision
+    //                         (broadcast for human messages, ignore for agents)
+    //   • [...agentNames]   → only listed agents should respond
+    //   • ["__no_response__"]
+    //                       → routing happened and decided nobody
+    //                         should respond. Sentinel is used instead
+    //                         of [] because pre-0.2.106 clients treat
+    //                         empty array as "broadcast" and every
+    //                         agent would reply. The sentinel is
+    //                         non-empty and matches no real agent.
     const messages = [];
     for (const e of events) {
       const source = e.source || '';
       const meta = e.metadata || {};
-      const targetAgents = meta.target_agents || [];
+      const targetAgents = meta.target_agents;
+      const hasTargetList = Array.isArray(targetAgents);
 
       // Skip own messages
       if (source === `openagents:${agentName}`) continue;
 
       if (source.startsWith('human:')) {
-        // Human messages: pick up if targeted at this agent or broadcast
-        if (!targetAgents.length || targetAgents.includes(agentName)) {
+        if (hasTargetList) {
+          if (targetAgents.includes(agentName)) {
+            messages.push(this._eventToMessage(e));
+          }
+        } else {
+          // Legacy server (no target_agents): broadcast for compat
           messages.push(this._eventToMessage(e));
         }
       } else if (source.startsWith('openagents:')) {
-        // Agent messages: only pick up if explicitly mentioned
-        if (targetAgents.includes(agentName)) {
+        // Agent messages: only pick up if explicitly listed
+        if (hasTargetList && targetAgents.includes(agentName)) {
           messages.push(this._eventToMessage(e));
         }
       }
@@ -545,7 +587,11 @@ class WorkspaceClient {
             const parsed = JSON.parse(data);
             if (res.statusCode >= 400) {
               const msg = parsed.message || `HTTP ${res.statusCode}`;
-              reject(new Error(msg));
+              if (typeof msg === 'string' && msg.toLowerCase().includes('session_revoked')) {
+                reject(new SessionRevokedError(msg));
+              } else {
+                reject(new Error(msg));
+              }
             } else {
               resolve(parsed);
             }
@@ -634,4 +680,4 @@ class WorkspaceClient {
   }
 }
 
-module.exports = { WorkspaceClient };
+module.exports = { WorkspaceClient, SessionRevokedError };