@hamp10/agentforge 0.2.21 → 0.2.23

package/src/browser.js

@@ -0,0 +1,392 @@
+/**
+ * AgentForge Browser Tool — Puppeteer connected to AgentForge Browser (port 9223)
+ * Uses puppeteer-core to attach to the already-running AgentForge Browser.
+ *
+ * Tab isolation: each agent gets its own dedicated tab so concurrent agents
+ * never interfere with each other. Pass agentId to browserAction().
+ */
+
+import puppeteer from 'puppeteer-core';
+
+const BROWSER_URL = 'http://127.0.0.1:9223';
+
+let _browser = null;
+// Per-agent active page map — agents never share a page reference
+const _agentPages = new Map();
+
+async function getBrowser() {
+  if (_browser && _browser.isConnected()) return _browser;
+  _browser = await puppeteer.connect({
+    browserURL: BROWSER_URL,
+    defaultViewport: null,
+    protocolTimeout: 60000,
+  });
+  _browser.on('disconnected', () => { _browser = null; _agentPages.clear(); });
+  return _browser;
+}
+
+// Return the active page for this agent. Creates a fresh tab on first use.
+// preferUrl: hint — if the agent's tab already has a better match among all open
+// tabs (e.g. a link opened a new tab), update the agent's pointer to it.
+async function getPage(agentId, preferUrl) {
+  const browser = await getBrowser();
+
+  // Check if the agent already has a live page
+  const existing = _agentPages.get(agentId);
+  if (existing && !existing.isClosed()) {
+    // If preferUrl given, check if any tab matches better (handles new-tab links)
+    if (preferUrl) {
+      const pages = await browser.pages();
+      const match = pages.find(p => !p.isClosed() && p.url().includes(preferUrl));
+      if (match && match !== existing) {
+        _agentPages.set(agentId, match);
+        return match;
+      }
+    }
+    return existing;
+  }
+
+  // Agent has no page — open a fresh tab so it doesn't land on another agent's tab
+  const fresh = await browser.newPage();
+  _agentPages.set(agentId, fresh);
+  return fresh;
+}
+
+const _wait = (ms) => new Promise(r => setTimeout(r, ms));
+
+// Take a structured snapshot of a page — content + interactive elements + all inputs
+async function _snapshot(page, agentId) {
+  const url = page.url();
+  let title = '';
+  try { title = await page.title(); } catch {}
+
+  const browser = await getBrowser();
+  const allPages = await browser.pages();
+  const open = allPages.filter(p => !p.isClosed());
+  const tabLines = await Promise.all(open.map(async (p, i) => {
+    const u = p.url();
+    let t = '';
+    try { t = await p.title(); } catch {}
+    const active = (p === page) ? ' ← ACTIVE' : '';
+    return `  [tab ${i}] ${t || '(no title)'} — ${u}${active}`;
+  }));
+
+  const data = await Promise.race([
+    page.evaluate(() => {
+      // All interactive clickable elements (buttons, links, tabs)
+      const clickEls = [...document.querySelectorAll('a,button,[role="button"],[role="link"],[role="tab"],[role="menuitem"]')];
+      const interactive = clickEls.slice(0, 80).map((el, i) => {
+        const label = (el.textContent || el.getAttribute('aria-label') || el.getAttribute('title') || '').trim().replace(/\s+/g, ' ').slice(0, 80);
+        return label ? `[${i}] ${el.tagName.toLowerCase()}: ${label}` : null;
+      }).filter(Boolean);
+
+      // All form inputs — these are critical for filling in filters
+      const formEls = [...document.querySelectorAll('input,select,textarea')];
+      const inputs = formEls.slice(0, 40).map((el, i) => {
+        const name = el.name || el.id || el.getAttribute('placeholder') || '';
+        const type = el.type || el.tagName.toLowerCase();
+        const val = el.value || '';
+        const opts = el.tagName === 'SELECT'
+          ? Array.from(el.options).map(o => o.text.trim()).filter(Boolean).slice(0, 20).join(' | ')
+          : '';
+        return `[input-${i}] ${type} name="${name}" value="${val}"${opts ? ` options: ${opts}` : ''}`;
+      });
+
+      // Page text — scroll position 0 so we always capture the top of the page
+      window.scrollTo(0, 0);
+      const bodyText = (document.body?.innerText || '').replace(/\n{3,}/g, '\n\n').slice(0, 8000);
+
+      return { interactive, inputs, bodyText };
+    }),
+    new Promise((_, rej) => setTimeout(() => rej(new Error('page.evaluate() timed out (10s)')), 10000)),
+  ]).catch(err => { console.log(`[browser.js] snapshot evaluate error: ${err.message}`); return { interactive: [], inputs: [], bodyText: '' }; });
+
+  const lines = [
+    `Open tabs:`,
+    ...tabLines,
+    ``,
+    `Active tab — URL: ${url}`,
+    `Title: ${title}`,
+  ];
+
+  if (data.interactive.length) {
+    lines.push(``, `Clickable elements (use ref index with click action):`);
+    lines.push(...data.interactive);
+  }
+
+  if (data.inputs.length) {
+    lines.push(``, `Form inputs (use selector="#id" or selector="[name=x]" with type action):`);
+    lines.push(...data.inputs);
+  }
+
+  lines.push(``, `Page content:`, data.bodyText);
+
+  // Thin-content warning — JS-heavy pages need a screenshot to read properly
+  const bodyLen = (data.bodyText || '').trim().length;
+  if (bodyLen < 500) {
+    lines.push(``, `⚠️ Page content is limited (${bodyLen} chars) — this page likely loads content via JavaScript. Use {"action":"screenshot"} to see exactly what is on screen right now.`);
+  }
+
+  return lines.join('\n');
+}
+
+// Release an agent's tab reference when their task is done.
+// Tab is intentionally kept open so the user can see the final state of the app.
+export function releaseAgentTab(agentId) {
+  _agentPages.delete(agentId);
+}
+
+// Hard outer timeout for any browser action — prevents any CDP call from hanging forever.
+// Most actions (navigate, snapshot) should complete in <15s. We give 25s for safety.
+const BROWSER_ACTION_TIMEOUT_MS = 25000;
+
+async function _browserActionInner(input, agentId, browser) {
+  try {
+    switch (input.action) {
+
+      case 'tabs': {
+        const pages = await browser.pages();
+        const open = pages.filter(p => !p.isClosed());
+        const lines = await Promise.all(open.map(async (p, i) => {
+          const url = p.url();
+          let title = '';
+          try { title = await p.title(); } catch {}
+          return `[${i}] ${title || '(no title)'} — ${url}`;
+        }));
+        return `Open tabs (${open.length}):\n${lines.join('\n')}\n\nTo switch to a tab: {"action":"focus","url":"fragment"} or {"action":"focus","index":N}`;
+      }
+
+      case 'navigate':
+      case 'open': {
+        const url = input.url || input.targetUrl;
+        const page = await getPage(agentId);
+        // Use Promise.race to enforce a hard 20s cap — page.goto timeout option can hang
+        const navResult = await Promise.race([
+          page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 }),
+          new Promise((_, rej) => setTimeout(() => rej(new Error(`Navigation hard-timeout (20s): ${url}`)), 20000)),
+        ]).catch(err => ({ __navError: err.message }));
+        if (navResult && navResult.__navError) {
+          // Navigation timed out but page may have partially loaded — still snapshot it
+          console.log(`[browser.js] navigate timeout for ${url}: ${navResult.__navError}`);
+        }
+        _agentPages.set(agentId, page);
+        // Brief pause for initial render, then snapshot
+        await _wait(400);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'focus': {
+        const pages = await browser.pages();
+        const open = pages.filter(p => !p.isClosed());
+        let target;
+        if (input.index !== undefined) {
+          target = open[parseInt(input.index)];
+        } else if (input.url) {
+          target = open.find(p => p.url().includes(input.url));
+        }
+        if (!target) return `Tab not found. Available tabs:\n${open.map((p,i) => `[${i}] ${p.url()}`).join('\n')}`;
+        await target.bringToFront();
+        _agentPages.set(agentId, target);
+        return await _snapshot(target, agentId);
+      }
+
+      case 'snapshot': {
+        const page = await getPage(agentId, input.url);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'screenshot': {
+        const page = await getPage(agentId, input.url);
+        const buf = await page.screenshot({ type: 'png', fullPage: false });
+        return { __screenshot: true, base64: buf.toString('base64') };
+      }
+
+      case 'click': {
+        const page = await getPage(agentId);
+
+        // Snapshot pages BEFORE click so we can detect truly new tabs (not background tabs)
+        const pagesBefore = new Set((await browser.pages()).map(p => p.target()._targetId || p.url()));
+
+        let clickResult = null;
+
+        if (input.ref !== undefined) {
+          clickResult = await page.evaluate((idx) => {
+            const els = document.querySelectorAll('a,button,[role="button"],[role="link"],[role="tab"],[role="menuitem"]');
+            const el = els[idx];
+            if (el) { el.focus(); el.click(); return `[${idx}] ${el.tagName}: ${(el.textContent||'').trim().slice(0,80)}`; }
+            return null;
+          }, parseInt(input.ref));
+        } else if (input.text) {
+          clickResult = await page.evaluate((text) => {
+            const all = Array.from(document.querySelectorAll('a,button,input,select,span,div,th,td,li,label,[role="button"]'));
+            const el = all.find(e => e.textContent.trim().includes(text) && e.offsetParent !== null);
+            if (el) { el.click(); return `${el.tagName}: ${el.textContent.trim().slice(0, 80)}`; }
+            return null;
+          }, input.text);
+        } else if (input.selector) {
+          await page.click(input.selector);
+          clickResult = `clicked ${input.selector}`;
+        } else if (input.x !== undefined) {
+          await page.mouse.click(input.x, input.y || 0);
+          clickResult = `clicked (${input.x}, ${input.y})`;
+        }
+
+        if (!clickResult) {
+          return input.ref !== undefined
+            ? `Element [${input.ref}] not found — take a snapshot to get current refs`
+            : `No visible element found matching "${input.text || input.selector}"`;
+        }
+
+        // Brief pause for dynamic content to render
+        await _wait(300);
+
+        // Check if this click opened a genuinely new tab (compare against pre-click snapshot)
+        const pagesAfter = await browser.pages();
+        const agentPage = _agentPages.get(agentId);
+        const newTab = pagesAfter.find(p => {
+          if (p.isClosed() || p === agentPage) return false;
+          const id = p.target()._targetId || p.url();
+          return !pagesBefore.has(id) && !p.url().startsWith('about') && !p.url().startsWith('chrome');
+        });
+        if (newTab) {
+          _agentPages.set(agentId, newTab);
+          await _wait(600); // let new tab load
+          const snap = await _snapshot(newTab, agentId);
+          return `Clicked: ${clickResult}\n\n⚠️ New tab opened — now viewing new tab.\n--- Page state after click ---\n${snap}`;
+        }
+
+        // Always return a fresh snapshot after clicking so agent immediately sees what changed
+        const snap = await _snapshot(page, agentId);
+        return `Clicked: ${clickResult}\n\n--- Page state after click ---\n${snap}`;
+      }
+
+      case 'type': {
+        const page = await getPage(agentId);
+        const text = input.text || '';
+        if (input.selector) {
+          await page.focus(input.selector);
+          await page.evaluate((sel) => {
+            const el = document.querySelector(sel);
+            if (el) { el.value = ''; el.dispatchEvent(new Event('input', {bubbles:true})); }
+          }, input.selector);
+          await page.type(input.selector, text, { delay: 30 });
+          await page.evaluate((sel) => {
+            const el = document.querySelector(sel);
+            if (el) el.dispatchEvent(new Event('change', {bubbles:true}));
+          }, input.selector);
+        } else {
+          await page.keyboard.type(text, { delay: 30 });
+        }
+        await _wait(500);
+        return `Typed "${text.slice(0, 60)}" — take a snapshot to see the result`;
+      }
+
+      case 'act': {
+        const req = input.request || {};
+        if (req.kind === 'click') return browserAction({ action: 'click', ref: req.ref, selector: req.selector }, agentId);
+        if (req.kind === 'type') return browserAction({ action: 'type', selector: req.selector, text: req.text }, agentId);
+        return `Unknown act kind: ${req.kind}`;
+      }
+
+      case 'press': {
+        // Press a keyboard key on the active page — use "Enter" to submit forms.
+        // Pass selector to re-focus an element first (prevents focus drift during model thinking gaps).
+        const page = await getPage(agentId);
+        const key = input.key || 'Enter';
+        if (input.selector) {
+          try { await page.focus(input.selector); } catch {}
+          await _wait(100); // brief settle after focus
+        }
+        await page.keyboard.press(key);
+        await _wait(800); // let the page react (navigation, form submission, etc.)
+        return await _snapshot(page, agentId);
+      }
+
+      case 'scroll': {
+        const page = await getPage(agentId);
+        const dx = input.x || 0, dy = input.y || 400;
+        await page.evaluate((x, y) => window.scrollBy(x, y), dx, dy);
+        await _wait(300);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'evaluate': {
+        const page = await getPage(agentId);
+        const result = await page.evaluate(input.script || input.expression || '');
+        return result === undefined ? 'undefined' : JSON.stringify(result);
+      }
+
+      case 'back': {
+        const page = await getPage(agentId);
+        await page.goBack({ waitUntil: 'domcontentloaded', timeout: 10000 });
+        await _wait(500);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'forward': {
+        const page = await getPage(agentId);
+        await page.goForward({ waitUntil: 'domcontentloaded', timeout: 10000 });
+        await _wait(500);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'wait': {
+        await _wait(input.ms || 1000);
+        const page = await getPage(agentId);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'url': {
+        const page = await getPage(agentId);
+        return page.url();
+      }
+
+      case 'reload': {
+        const page = await getPage(agentId);
+        await page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 });
+        await _wait(500);
+        return await _snapshot(page, agentId);
+      }
+
+      case 'select': {
+        const page = await getPage(agentId);
+        await page.select(input.selector, input.value);
+        await _wait(500);
+        return await _snapshot(page, agentId);
+      }
+
+      default:
+        return `Unknown browser action: ${input.action}. Valid: tabs, navigate, open, focus, snapshot, click, type, screenshot, scroll, evaluate, select, press, wait, reload, back, forward, url`;
+    }
+  } catch (err) {
+    return `Browser error (${input.action}): ${err.message}`;
+  }
+}
+
+export async function browserAction(input, agentId = 'agent') {
+  let browser;
+  try {
+    browser = await Promise.race([
+      getBrowser(),
+      new Promise((_, rej) => setTimeout(() => rej(new Error('getBrowser() timed out after 10s')), 10000)),
+    ]);
+  } catch (err) {
+    return `Browser error: ${err.message}\nIs AgentForge Browser running? (port 9223)`;
+  }
+
+  // Wrap the entire action in a hard timeout — prevents getPage(), page.goto(), page.evaluate()
+  // and any other CDP call from hanging indefinitely.
+  try {
+    const result = await Promise.race([
+      _browserActionInner(input, agentId, browser),
+      new Promise((_, rej) => setTimeout(() => rej(new Error(`Browser action timed out after ${BROWSER_ACTION_TIMEOUT_MS/1000}s (action=${input.action})`)), BROWSER_ACTION_TIMEOUT_MS)),
+    ]);
+    return result;
+  } catch (err) {
+    console.log(`[browser.js] ⏱️ Hard timeout: ${err.message}`);
+    // Reset stale connection — next action will reconnect fresh to Chrome CDP
+    _browser = null;
+    _agentPages.clear();
+    return `Browser error (${input.action}): ${err.message}`;
+  }
+}

package/src/default-task-guides.js

@@ -0,0 +1,95 @@
+export const TASK_GUIDE_TYPE_LABELS = Object.freeze({
+  general: 'General',
+  ui: 'UI',
+  code: 'Code',
+  research: 'Research',
+  data: 'Data',
+  planning: 'Planning',
+  creative: 'Creative',
+});
+
+const UI_PRODUCT_QUALITY_CONTENT = `UI work must result in a real product surface, not superficial styling.
+
+Required process:
+1. On the initial attempt, inspect the actual app visually first with browser/screenshot. Use DOM snapshots only to locate controls.
+2. For existing products, inspect at least two nearby or comparable live surfaces when they exist, plus the source files/templates/styles that create those surfaces. Use them to learn the product's strongest layout patterns, content depth, interaction patterns, and quality bar before changing the target surface. After you start editing a narrowly scoped target, do not drift into reference surfaces as work targets; final browser verification must be on the changed target surface(s).
+3. When the task names a narrow page, listing, route, screen, or component, find analogous pages/components in the same project and read their code before rebuilding. Treat those analogous files as read-only reference context unless the user named them too. Match the established system while making the target surface as strong as the best local examples.
+4. Identify the product domain, primary user job, key workflow, empty/error/loading states, and what makes the current UI feel unfinished.
+5. Make product-level changes: information architecture, workflow, hierarchy, components, states, copy, data density, responsiveness, and visual system. Color-only, label-only, spacing-only, or hero-only passes are incomplete.
+6. Preserve real capability. If keys/auth/data/devices/models are missing, design useful setup, empty, disabled, demo, or recovery states instead of deleting complexity.
+7. Translate the task language into first-class product objects, workflow states, outcomes, and primary actions. Keep vendor, model, framework, or implementation details secondary unless the user is explicitly configuring them.
+8. For apps, tools, dashboards, games, and operational products, the first screen must be the actual working surface. Do not replace the app with a marketing hero, explainer page, or decorative showcase.
+9. Respect the requested scope. When the user names specific pages, screens, listings, flows, or components, improve those target surfaces and their directly owned assets. Put page-specific styles/content in target-owned files where possible. Do not redesign shared/global navigation, templates, styles, reference pages, or unrelated pages unless the target cannot work without it; if shared files are touched, verify adjacent surfaces did not regress and explain why the shared change was necessary.
+10. On retries, nudges, or runtime recovery after inspection/read/browser activity already happened, do not restart discovery. Continue from current files and tool results; the next material step should be an edit/write or a focused verification of changed UI. If a UI-quality attempt was restored or rejected as too thin/shallow, change strategy instead of redoing small CSS, copy, badge, icon, CTA, or hero edits.
+11. If repeated targeted edits are failing or accumulating as micro-edits, replace the complete scoped file from the latest inspected source instead of chaining many small stale-string replacements. If source-artifact feedback appears, clean it up as part of the next pass, but do not treat cleanup as the design fix.
+
+Quality bar:
+- The first screen shows what matters now and what to do next within a few seconds.
+- The first screen is not just a sparse headline/subtitle/button on a blank background. It should show meaningful product content, workflow, comparison, data, media, examples, or other concrete structure before the user has to hunt for the substance.
+- Controls have visible default, hover/focus, selected, disabled, loading, success, error, and empty states where relevant.
+- Layout survives desktop and narrow widths; text does not overflow, overlap, clip, or become unreadable.
+- Accessibility is built in: contrast, focus, keyboard flow, target size, and clear status/error messages.
+- Screenshots must be checked for unintended visual artifacts: clipped or partially cut-off letters/text, broken layering, abrupt discontinuities, accidental overlays, tiling/repeating backgrounds, broken transparency, visible crop edges, and anything that reads as rendering damage rather than deliberate design.
+- Keep technical/provider/model configuration out of the primary workflow unless that configuration is the product's main job. Use advanced settings, secondary panels, or defaults for implementation details.
+- Remove generic AI-dashboard filler, placeholder panels, duplicated sections, mismatched spacing/radii/shadows, dead buttons, decorative gradients, and external visual assets that do not support the task.
+- Avoid one-note visual systems dominated by a single hue, glow, or gradient. Use restrained hierarchy, purposeful contrast, and domain-specific objects instead of decoration.
+- The changed screen should hold up next to the product's own strongest screens and normal professional design standards. If it looks thinner, rougher, less considered, or less coherent than nearby surfaces, keep iterating.
+
+Completion rule:
+Run/inspect the changed UI visually, compare it against the product context you inspected, critique it once, fix material issues, and repeat until there are no obvious quality gaps. Then finish with concrete changed screens/files and blockers. Do not mark complete after planning, reading files, or making generic polish.`;
+
+export const DEFAULT_TASK_GUIDES = Object.freeze({
+  ui: Object.freeze({
+    idSuffix: 'ui-product-quality-v10',
+    name: 'UI/UX Product Design Quality Gate',
+    description: 'Requires agents to deliver researched, complete, domain-aware product UX instead of superficial visual tweaks.',
+    task_type: 'ui',
+    trigger_keywords: Object.freeze([
+      'ui', 'ux', 'visual', 'design', 'frontend', 'css', 'html', 'page',
+      'dashboard', 'website', 'app', 'layout', 'component', 'responsive',
+      'professional', 'polish', 'vibecoded', 'vibe-coded', 'landing',
+      'empty state', 'workflow', 'product design', 'interface', 'screen',
+      'visual hierarchy', 'user experience', 'design system', 'readability',
+      'readable', 'legibility', 'contrast', 'accessibility',
+    ]),
+    priority: 300,
+    content: UI_PRODUCT_QUALITY_CONTENT,
+  }),
+  code: Object.freeze({
+    idSuffix: 'code-delivery-v1',
+    name: 'Code Delivery',
+    description: 'Keeps implementation and shipping tasks grounded in existing project structure and real delivery evidence.',
+    task_type: 'code',
+    trigger_keywords: Object.freeze([
+      'code', 'repo', 'project', 'bug', 'fix', 'implement', 'refactor', 'test',
+      'commit', 'push', 'publish', 'deploy', 'release', 'production', 'live',
+      'ship', 'shipping',
+    ]),
+    priority: 100,
+    content: `For code tasks:
+- Read the existing project structure before editing.
+- Follow local patterns and preserve unrelated user changes.
+- Make the smallest complete change that solves the task.
+- Run the relevant checks or explain exactly why they could not run.
+- Do not create throwaway proof files such as verification notes, screenshots, or status artifacts inside the user's repo unless the user asked for them.
+- Do not create or switch git branches unless the user asked for a branch or pull request. If the user asks to commit and push, deliver on the current branch/upstream.
+- If the user asks to commit, push, publish, deploy, release, or update a live site, that delivery step is part of the task. Do not report completion until you have run the matching git/deploy/publish command, verified the target state, and reported exact evidence.
+- Report changed files and remaining blockers only after implementation is complete.`,
+  }),
+});
+
+export const SERVER_DEFAULT_TASK_GUIDES = Object.freeze([
+  DEFAULT_TASK_GUIDES.ui,
+  DEFAULT_TASK_GUIDES.code,
+]);
+
+export function getStarterTaskGuide(type) {
+  const guide = DEFAULT_TASK_GUIDES[type];
+  if (!guide) return null;
+  return {
+    name: guide.name,
+    description: guide.description,
+    keywords: guide.trigger_keywords.join(', '),
+    content: guide.content,
+  };
+}

package/src/resolveOpenclaw.js

@@ -11,7 +11,7 @@
  */
 
 import { execSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import path from 'path';
 
@@ -23,6 +23,25 @@ function tryExec(cmd) {
   }
 }
 
+function tryReadDir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function uniqueExisting(paths) {
+  return [...new Set(paths.filter(Boolean).map(p => path.normalize(p)))].filter(p => existsSync(p));
+}
+
+function nvmNodeDirs(home) {
+  const base = path.join(home, '.nvm', 'versions', 'node');
+  return tryReadDir(base)
+    .filter(entry => entry.isDirectory())
+    .map(entry => path.join(base, entry.name));
+}
+
 // Walk up from a binary path to find dist/index.js in the containing package.
 function findModuleIndex(binPath) {
   if (!binPath) return null;
@@ -54,7 +73,7 @@ export function resolveOpenclawModule() {
   // 2. which openclaw → resolve symlink → find dist/index.js
   const which = tryExec('which openclaw');
   if (which && existsSync(which)) {
-    const real = tryExec(`readlink -f "${which}"`) || which;
+    const real = tryExec(`readlink -f "${which}"`) || tryExec(`realpath "${which}"`) || which;
     const idx = findModuleIndex(real);
     if (idx) return idx;
     // which found the binary but we couldn't find index.js — try npm root
@@ -69,17 +88,22 @@ export function resolveOpenclawModule() {
 
   // 4. Static fallbacks for known install locations
   const home = process.env.HOME || homedir();
+  const npmPrefix = tryExec('npm config get prefix');
+  const nodeDirs = nvmNodeDirs(home);
   const statics = [
     '/usr/local/lib/node_modules/openclaw/dist/index.js',
     path.join(home, '.npm-global/lib/node_modules/openclaw/dist/index.js'),
+    path.join(home, '.local/lib/node_modules/openclaw/dist/index.js'),
+    path.join(home, '.volta/tools/image/packages/openclaw/lib/node_modules/openclaw/dist/index.js'),
     '/opt/homebrew/lib/node_modules/openclaw/dist/index.js',
     // nvm — try the active version via node path
     path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules', 'openclaw', 'dist', 'index.js'),
-  ].map(p => path.normalize(p));
+    npmPrefix ? path.join(npmPrefix, 'lib', 'node_modules', 'openclaw', 'dist', 'index.js') : null,
+    ...nodeDirs.map(dir => path.join(dir, 'lib', 'node_modules', 'openclaw', 'dist', 'index.js')),
+  ];
 
-  for (const p of statics) {
-    if (existsSync(p)) return p;
-  }
+  const existing = uniqueExisting(statics);
+  if (existing.length > 0) return existing[0];
 
   return null;
 }
@@ -95,11 +119,18 @@ export function resolveOpenclawBin() {
   if (which && existsSync(which)) return which;
 
   const home = process.env.HOME || homedir();
+  const npmPrefix = tryExec('npm config get prefix');
+  const nodeDirs = nvmNodeDirs(home);
   const statics = [
     '/usr/local/bin/openclaw',
     path.join(home, '.npm-global/bin/openclaw'),
+    path.join(home, '.local/bin/openclaw'),
+    path.join(home, '.volta/bin/openclaw'),
+    path.join(home, '.asdf/shims/openclaw'),
     '/opt/homebrew/bin/openclaw',
     path.join(path.dirname(process.execPath), 'openclaw'),
+    npmPrefix ? path.join(npmPrefix, 'bin', 'openclaw') : null,
+    ...nodeDirs.map(dir => path.join(dir, 'bin', 'openclaw')),
   ];
-  return statics.find(p => existsSync(p)) || null;
+  return uniqueExisting(statics)[0] || null;
 }

package/src/selfUpdate.js

@@ -7,6 +7,9 @@
  */
 
 import { execSync, spawn } from 'child_process';
+import { mkdirSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
 
 function parseVersion(v) {
   return (v || '0.0.0').split('.').map(Number);
@@ -44,11 +47,11 @@ export async function checkAndUpdate(packageName, currentVersion) {
   console.log(`   Updating ${packageName}...`);
 
   try {
-    execSync(`npm install -g ${packageName}@${latestVersion}`, { stdio: 'inherit' });
+    installGlobalPackage(`${packageName}@${latestVersion}`);
   } catch {
-    // First attempt failed (often EEXIST on the bin symlink) — retry with --force
+    // First attempt failed (often EEXIST on the bin symlink) — retry with --force.
     try {
-      execSync(`npm install -g --force ${packageName}@${latestVersion}`, { stdio: 'inherit' });
+      installGlobalPackage(`${packageName}@${latestVersion}`, { force: true });
     } catch {
       console.warn('⚠️  Auto-update failed — continuing with current version');
       return;
@@ -69,3 +72,28 @@ export async function checkAndUpdate(packageName, currentVersion) {
   // Park the parent — child owns the terminal from here
   await new Promise(() => {});
 }
+
+function installGlobalPackage(pkg, { force = false } = {}) {
+  const forceFlag = force ? ' --force' : '';
+  try {
+    execSync(`npm install -g${forceFlag} ${pkg}`, { stdio: 'inherit' });
+    return;
+  } catch (error) {
+    if (!looksLikePermissionFailure(error)) throw error;
+  }
+
+  const prefix = path.join(homedir(), '.npm-global');
+  mkdirSync(path.join(prefix, 'bin'), { recursive: true });
+  mkdirSync(path.join(prefix, 'lib', 'node_modules'), { recursive: true });
+  execSync(`npm config set prefix "${prefix}"`, { stdio: 'inherit' });
+  const env = {
+    ...process.env,
+    PATH: `${path.join(prefix, 'bin')}${path.delimiter}${process.env.PATH || ''}`,
+  };
+  execSync(`npm install -g${forceFlag} ${pkg}`, { stdio: 'inherit', env });
+}
+
+function looksLikePermissionFailure(error) {
+  const text = `${error?.message || ''}\n${error?.stderr?.toString?.() || ''}\n${error?.stdout?.toString?.() || ''}`;
+  return /EACCES|permission denied|access/i.test(text);
+}