promethios-bridge 1.5.1 → 1.7.0

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "promethios-bridge",
-  "version": "1.5.1",
-  "description": "Run Promethios agent frameworks locally on your computer with full file, terminal, browser access, and Native Framework Mode (run OpenClaw and other frameworks in their native interface via the bridge).",
+  "version": "1.7.0",
+  "description": "Run Promethios agent frameworks locally on your computer with full file, terminal, browser access, ambient context capture, and the always-on-top floating chat overlay. Native Framework Mode supports OpenClaw and other frameworks via the bridge.",
   "main": "src/index.js",
   "bin": {
     "promethios-bridge": "src/cli.js"
   },
   "scripts": {
     "start": "node src/cli.js",
-    "dev": "node src/cli.js --dev"
+    "dev": "node src/cli.js --dev",
+    "postinstall": "node node_modules/playwright/cli.js install chromium || npx playwright install chromium || true"
   },
   "keywords": [
     "promethios",
@@ -19,7 +20,9 @@
     "framework",
     "openclaw",
     "native",
-    "clawhub"
+    "clawhub",
+    "overlay",
+    "ambient"
   ],
   "author": "Promethios <hello@promethios.ai>",
   "license": "MIT",
@@ -50,7 +53,8 @@
     "playwright": "^1.42.0"
   },
   "optionalDependencies": {
-    "playwright": "^1.42.0"
+    "playwright": "^1.42.0",
+    "electron": "^29.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/bridge.js

@@ -20,9 +20,15 @@ const chalk = require('chalk');
 const ora = require('ora');
 const fetch = require('node-fetch');
 const { executeLocalTool } = require('./executor');
+const { captureContext } = require('./contextCapture');
+
+// Optional: Electron overlay window (gracefully skipped if not installed)
+let launchOverlay = null;
+try { launchOverlay = require('promethios-overlay/src/launcher').launchOverlay; } catch { /* overlay not installed */ }
 
 const HEARTBEAT_INTERVAL = 30_000; // 30s
 const POLL_INTERVAL = 1_000;       // 1s — poll for pending tool calls
+const CONTEXT_PUSH_INTERVAL = 5_000; // 5s — push ambient context snapshot
 
 async function startBridge({ setupToken, apiBase, port, dev }) {
   const log = dev
@@ -169,6 +175,21 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
   console.log(chalk.gray('  Press Ctrl+C to disconnect.'));
   console.log('');
 
+  // ── Step 4c: Launch Electron overlay window (if available) ──────────────────
+  // The overlay is an always-on-top floating chat pill that works across all
+  // apps on Windows, Mac, and Linux. It auto-launches alongside the bridge.
+  // Users can toggle watching on/off from the pill without restarting the bridge.
+  if (launchOverlay) {
+    try {
+      launchOverlay({ authToken, apiBase, dev });
+      console.log(chalk.cyan('  ⬡ Promethios overlay launched — floating chat is ready'));
+      console.log(chalk.gray('    Hotkey: Ctrl+Shift+P (Win/Linux) or Cmd+Shift+P (Mac)'));
+      console.log('');
+    } catch (err) {
+      log('Overlay launch failed (non-critical):', err.message);
+    }
+  }
+
   // Heartbeat loop
   const heartbeatTimer = setInterval(async () => {
     try {
@@ -182,6 +203,27 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
     }
   }, HEARTBEAT_INTERVAL);
 
+  // ── Step 4b: Ambient context push loop ──────────────────────────────────────
+  // Every 5 seconds, capture what the user is working on (active window, browser
+  // URL, clipboard) and push it to the API. The agent uses this to give
+  // context-aware help without the user having to explain what they're doing.
+  const contextPushLoop = async () => {
+    while (pollActive) {
+      try {
+        const snapshot = await captureContext(process.platform, dev);
+        await fetch(`${apiBase}/api/local-bridge/context`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${authToken}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify(snapshot),
+        });
+        log('Context pushed:', snapshot.active_app, snapshot.active_url || '');
+      } catch (err) {
+        log('Context push failed:', err.message);
+      }
+      await sleep(CONTEXT_PUSH_INTERVAL);
+    }
+  };
+
   // ── Step 5: Poll for pending tool calls (Firestore relay) ─────────────────
   // The cloud backend queues tool calls in Firestore when the agent uses
   // local_shell, local_file_read, or local_file_write. We poll for them here,
@@ -219,6 +261,11 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
     console.error(chalk.red('  ✗ Poll loop crashed:'), err.message);
   });
 
+  // Start context push loop in background
+  contextPushLoop().catch(err => {
+    log('Context push loop crashed:', err.message);
+  });
+
   // Graceful shutdown
   const shutdown = async (signal) => {
     console.log('');
@@ -321,6 +368,27 @@ async function registerBridge({ authToken, apiBase, callbackUrl, port, dev }) {
   const homeDir = osModule.homedir();
   const username = osModule.userInfo().username;
 
+  // ── Desktop path probe ────────────────────────────────────────────────────
+  // On Windows, the visual Desktop can be redirected anywhere by OneDrive,
+  // Group Policy, or manual folder redirection. We probe the real path at
+  // connect time so the agent always uses the correct location.
+  // Resolution order (first that exists wins):
+  //   1. Windows registry: HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders\Desktop
+  //      This is the authoritative source — it reflects OneDrive redirection,
+  //      GPO folder redirection, and any custom Desktop path.
+  //   2. %USERPROFILE%\OneDrive\Desktop  (common OneDrive default)
+  //   3. %USERPROFILE%\Desktop           (standard local Desktop)
+  let desktopPath = null;
+  if (platform === 'win32') {
+    desktopPath = await probeWindowsDesktopPath(homeDir, dev);
+  } else if (platform === 'darwin') {
+    desktopPath = `${homeDir}/Desktop`;
+  } else {
+    desktopPath = `${homeDir}/Desktop`;
+  }
+
+  if (dev) console.log('[debug] Resolved desktopPath:', desktopPath);
+
   const res = await fetch(`${apiBase}/api/local-bridge/register`, {
     method: 'POST',
     headers: {
@@ -332,10 +400,11 @@ async function registerBridge({ authToken, apiBase, callbackUrl, port, dev }) {
       callbackUrl,
       capabilities,
       bridgeVersion: require('../package.json').version,
-      os: platform,   // 'win32' | 'darwin' | 'linux'
-      shell,          // 'cmd' | 'zsh' | 'bash' etc.
-      homeDir,        // e.g. 'C:\\Users\\ted' or '/Users/ted'
-      username,       // e.g. 'ted'
+      os: platform,      // 'win32' | 'darwin' | 'linux'
+      shell,             // 'cmd' | 'zsh' | 'bash' etc.
+      homeDir,           // e.g. 'C:\\Users\\ted' or '/Users/ted'
+      username,          // e.g. 'ted'
+      desktopPath,       // resolved real Desktop path — may differ from homeDir\Desktop
     }),
   });
 
@@ -345,6 +414,69 @@ async function registerBridge({ authToken, apiBase, callbackUrl, port, dev }) {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Probe the real Windows Desktop path for any user configuration
+// ─────────────────────────────────────────────────────────────────────────────
+async function probeWindowsDesktopPath(homeDir, dev) {
+  const { execSync } = require('child_process');
+  const fs = require('fs');
+  const path = require('path');
+  const log = dev ? (...a) => console.log('[debug]', ...a) : () => {};
+
+  // Strategy 1: Read the Windows registry — the authoritative source.
+  // The 'User Shell Folders' key stores the ACTUAL Desktop path after any
+  // OneDrive or GPO folder redirection. It may contain %USERPROFILE% which
+  // we expand manually.
+  try {
+    const regOutput = execSync(
+      'reg query "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders" /v Desktop',
+      { encoding: 'utf8', timeout: 5000 }
+    );
+    // Output format: "    Desktop    REG_EXPAND_SZ    C:\Users\ted\OneDrive\Desktop"
+    const match = regOutput.match(/Desktop\s+REG_EXPAND_SZ\s+(.+)/);
+    if (match) {
+      let regPath = match[1].trim();
+      // Expand %USERPROFILE% manually (Windows env vars in registry values)
+      regPath = regPath.replace(/%USERPROFILE%/gi, homeDir);
+      regPath = regPath.replace(/%USERNAME%/gi, path.basename(homeDir));
+      log('Registry Desktop path:', regPath);
+      if (fs.existsSync(regPath)) {
+        return regPath;
+      }
+      log('Registry path does not exist on disk, falling back:', regPath);
+    }
+  } catch (e) {
+    log('Registry query failed:', e.message);
+  }
+
+  // Strategy 2: PowerShell [Environment]::GetFolderPath('Desktop')
+  // This resolves the shell namespace Desktop correctly including OneDrive.
+  try {
+    const psOutput = execSync(
+      'powershell -NoProfile -Command "[Environment]::GetFolderPath(\'Desktop\')"',
+      { encoding: 'utf8', timeout: 8000 }
+    ).trim();
+    if (psOutput && fs.existsSync(psOutput)) {
+      log('PowerShell Desktop path:', psOutput);
+      return psOutput;
+    }
+  } catch (e) {
+    log('PowerShell Desktop probe failed:', e.message);
+  }
+
+  // Strategy 3: Check common OneDrive Desktop path
+  const oneDriveDesktop = path.join(homeDir, 'OneDrive', 'Desktop');
+  if (fs.existsSync(oneDriveDesktop)) {
+    log('OneDrive Desktop found:', oneDriveDesktop);
+    return oneDriveDesktop;
+  }
+
+  // Strategy 4: Standard local Desktop fallback
+  const localDesktop = path.join(homeDir, 'Desktop');
+  log('Falling back to local Desktop:', localDesktop);
+  return localDesktop;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // What this bridge can do (declared to the cloud for permission manifest display)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/contextCapture.js

@@ -0,0 +1,324 @@
+/**
+ * Promethios Local Bridge — Ambient Context Capture
+ *
+ * Captures what the user is currently working on:
+ *   - Active window title + process name
+ *   - Active browser URL (Chrome, Edge, Firefox via accessibility / window title)
+ *   - Selected / clipboard text (last copied text)
+ *   - Active form field content (via clipboard snapshot)
+ *
+ * Designed to run every 5 seconds and push a lightweight context snapshot
+ * to the Promethios API so the AI always knows what the user is doing.
+ *
+ * Platform support:
+ *   - Windows: PowerShell Get-Process / UIAutomation / Get-Clipboard
+ *   - macOS:   AppleScript / pbpaste
+ *   - Linux:   xdotool / xclip (if available)
+ */
+
+const { execSync, exec } = require('child_process');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main capture function — returns a context snapshot object
+// ─────────────────────────────────────────────────────────────────────────────
+async function captureContext(platform, dev) {
+  const log = dev ? (...a) => console.log('[context]', ...a) : () => {};
+
+  const snapshot = {
+    captured_at: new Date().toISOString(),
+    active_window: null,   // { title, process }
+    active_url: null,      // string — browser URL if active
+    active_app: null,      // friendly app name
+    clipboard_text: null,  // last copied text (truncated to 500 chars)
+    browser_tab_title: null, // browser tab title if browser is active
+  };
+
+  try {
+    if (platform === 'win32') {
+      await captureWindows(snapshot, log);
+    } else if (platform === 'darwin') {
+      await captureMac(snapshot, log);
+    } else {
+      await captureLinux(snapshot, log);
+    }
+  } catch (err) {
+    log('Context capture error:', err.message);
+  }
+
+  return snapshot;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Windows capture via PowerShell
+// ─────────────────────────────────────────────────────────────────────────────
+async function captureWindows(snapshot, log) {
+  // Active window title + process name
+  try {
+    const psScript = `
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+public class Win32 {
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, StringBuilder text, int count);
+  [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr hWnd, out int lpdwProcessId);
+}
+"@
+$hwnd = [Win32]::GetForegroundWindow()
+$sb = New-Object System.Text.StringBuilder 512
+[Win32]::GetWindowText($hwnd, $sb, 512) | Out-Null
+$pid = 0
+[Win32]::GetWindowThreadProcessId($hwnd, [ref]$pid) | Out-Null
+$proc = Get-Process -Id $pid -ErrorAction SilentlyContinue
+$result = @{
+  title = $sb.ToString()
+  process = if ($proc) { $proc.Name } else { "unknown" }
+} | ConvertTo-Json -Compress
+Write-Output $result
+`.trim();
+
+    const output = execSync(
+      `powershell -NoProfile -NonInteractive -Command "${psScript.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`,
+      { encoding: 'utf8', timeout: 4000, windowsHide: true }
+    ).trim();
+
+    const parsed = JSON.parse(output);
+    snapshot.active_window = { title: parsed.title, process: parsed.process };
+    snapshot.active_app = friendlyAppName(parsed.process, parsed.title);
+    log('Active window:', snapshot.active_window);
+  } catch (err) {
+    log('Windows active window capture failed:', err.message);
+  }
+
+  // Extract browser URL from window title (works for Chrome, Edge, Firefox)
+  // Chrome/Edge format: "<page title> - <browser name>"
+  // Firefox format: "<page title> — Mozilla Firefox"
+  if (snapshot.active_window) {
+    const url = extractUrlFromBrowserTitle(snapshot.active_window.title, snapshot.active_window.process);
+    if (url) {
+      snapshot.active_url = url;
+      snapshot.browser_tab_title = extractTabTitle(snapshot.active_window.title, snapshot.active_window.process);
+    }
+  }
+
+  // Clipboard text (last copied)
+  try {
+    const clip = execSync(
+      'powershell -NoProfile -NonInteractive -Command "Get-Clipboard -ErrorAction SilentlyContinue"',
+      { encoding: 'utf8', timeout: 2000, windowsHide: true }
+    ).trim();
+    if (clip && clip.length > 0 && clip.length < 5000) {
+      snapshot.clipboard_text = clip.slice(0, 500);
+      log('Clipboard:', snapshot.clipboard_text.slice(0, 80));
+    }
+  } catch (err) {
+    log('Clipboard capture failed:', err.message);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// macOS capture via AppleScript
+// ─────────────────────────────────────────────────────────────────────────────
+async function captureMac(snapshot, log) {
+  // Active app + window title
+  try {
+    const script = `
+tell application "System Events"
+  set frontApp to first application process whose frontmost is true
+  set appName to name of frontApp
+  set windowTitle to ""
+  try
+    set windowTitle to name of front window of frontApp
+  end try
+  return appName & "|" & windowTitle
+end tell`;
+    const output = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`,
+      { encoding: 'utf8', timeout: 4000 }).trim();
+    const [appName, windowTitle] = output.split('|');
+    snapshot.active_window = { title: windowTitle || '', process: appName || '' };
+    snapshot.active_app = appName;
+    log('Active app:', appName, 'Window:', windowTitle);
+  } catch (err) {
+    log('macOS active window capture failed:', err.message);
+  }
+
+  // Browser URL via AppleScript (Chrome, Safari, Firefox)
+  if (snapshot.active_window) {
+    const proc = (snapshot.active_window.process || '').toLowerCase();
+    try {
+      let urlScript = '';
+      if (proc.includes('chrome') || proc.includes('chromium')) {
+        urlScript = 'tell application "Google Chrome" to return URL of active tab of front window';
+      } else if (proc.includes('safari')) {
+        urlScript = 'tell application "Safari" to return URL of current tab of front window';
+      } else if (proc.includes('firefox')) {
+        urlScript = 'tell application "Firefox" to return URL of active tab of front window';
+      } else if (proc.includes('edge')) {
+        urlScript = 'tell application "Microsoft Edge" to return URL of active tab of front window';
+      }
+      if (urlScript) {
+        const url = execSync(`osascript -e '${urlScript}'`,
+          { encoding: 'utf8', timeout: 3000 }).trim();
+        snapshot.active_url = url;
+        snapshot.browser_tab_title = snapshot.active_window.title;
+        log('Browser URL:', url);
+      }
+    } catch (err) {
+      log('macOS browser URL capture failed:', err.message);
+    }
+  }
+
+  // Clipboard
+  try {
+    const clip = execSync('pbpaste', { encoding: 'utf8', timeout: 2000 }).trim();
+    if (clip && clip.length > 0 && clip.length < 5000) {
+      snapshot.clipboard_text = clip.slice(0, 500);
+    }
+  } catch (err) {
+    log('macOS clipboard capture failed:', err.message);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Linux capture via xdotool / xclip (best-effort)
+// ─────────────────────────────────────────────────────────────────────────────
+async function captureLinux(snapshot, log) {
+  try {
+    const title = execSync('xdotool getactivewindow getwindowname 2>/dev/null',
+      { encoding: 'utf8', timeout: 2000 }).trim();
+    snapshot.active_window = { title, process: 'unknown' };
+    snapshot.active_app = title;
+  } catch (err) {
+    log('Linux active window capture failed:', err.message);
+  }
+
+  try {
+    const clip = execSync('xclip -selection clipboard -o 2>/dev/null || xsel --clipboard --output 2>/dev/null',
+      { encoding: 'utf8', timeout: 2000 }).trim();
+    if (clip && clip.length > 0 && clip.length < 5000) {
+      snapshot.clipboard_text = clip.slice(0, 500);
+    }
+  } catch (err) {
+    log('Linux clipboard capture failed:', err.message);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Try to extract a URL from a browser window title.
+ * Chrome/Edge show: "<page title> - Google Chrome"
+ * Firefox shows:   "<page title> — Mozilla Firefox"
+ * We can't get the actual URL from the title alone, but we can detect
+ * that a browser is active and parse the tab title.
+ *
+ * For richer URL capture on Windows, we use the UIAutomation address bar
+ * approach via PowerShell — but that's expensive, so we only do it when
+ * the active process is a known browser.
+ */
+function extractUrlFromBrowserTitle(title, process) {
+  const proc = (process || '').toLowerCase();
+  const isBrowser = proc.includes('chrome') || proc.includes('msedge') ||
+    proc.includes('firefox') || proc.includes('opera') || proc.includes('brave');
+  if (!isBrowser) return null;
+
+  // Try to get URL from Chrome/Edge via PowerShell UIAutomation (Windows only)
+  // This reads the address bar text directly — works even for SPAs
+  if (proc.includes('chrome') || proc.includes('msedge')) {
+    try {
+      const psScript = `
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+$proc = Get-Process -Name "${proc.includes('msedge') ? 'msedge' : 'chrome'}" -ErrorAction SilentlyContinue | Select-Object -First 1
+if ($proc) {
+  $root = [System.Windows.Automation.AutomationElement]::FromHandle($proc.MainWindowHandle)
+  $cond = New-Object System.Windows.Automation.PropertyCondition([System.Windows.Automation.AutomationElement]::NameProperty, "Address and search bar")
+  $bar = $root.FindFirst([System.Windows.Automation.TreeScope]::Descendants, $cond)
+  if ($bar) {
+    $vp = $bar.GetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern)
+    Write-Output $vp.Current.Value
+  }
+}`.trim();
+      const url = execSync(
+        `powershell -NoProfile -NonInteractive -Command "${psScript.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`,
+        { encoding: 'utf8', timeout: 5000, windowsHide: true }
+      ).trim();
+      if (url && (url.startsWith('http') || url.startsWith('chrome'))) {
+        return url;
+      }
+    } catch (err) {
+      // UIAutomation not available — fall back to title parsing
+    }
+  }
+
+  return null; // URL not extractable from title alone
+}
+
+function extractTabTitle(windowTitle, process) {
+  const proc = (process || '').toLowerCase();
+  // Strip browser suffix from title
+  return windowTitle
+    .replace(/ - Google Chrome$/, '')
+    .replace(/ - Microsoft Edge$/, '')
+    .replace(/ — Mozilla Firefox$/, '')
+    .replace(/ - Brave$/, '')
+    .replace(/ - Opera$/, '')
+    .trim();
+}
+
+function friendlyAppName(processName, windowTitle) {
+  const proc = (processName || '').toLowerCase();
+  if (proc.includes('chrome')) return 'Google Chrome';
+  if (proc.includes('msedge')) return 'Microsoft Edge';
+  if (proc.includes('firefox')) return 'Firefox';
+  if (proc.includes('brave')) return 'Brave Browser';
+  if (proc.includes('code')) return 'VS Code';
+  if (proc.includes('excel')) return 'Microsoft Excel';
+  if (proc.includes('word')) return 'Microsoft Word';
+  if (proc.includes('outlook')) return 'Microsoft Outlook';
+  if (proc.includes('slack')) return 'Slack';
+  if (proc.includes('teams')) return 'Microsoft Teams';
+  if (proc.includes('zoom')) return 'Zoom';
+  if (proc.includes('notepad')) return 'Notepad';
+  if (proc.includes('explorer')) return 'File Explorer';
+  if (proc.includes('cmd') || proc.includes('powershell') || proc.includes('windowsterminal')) return 'Terminal';
+  return processName || 'Unknown';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Format context snapshot as a human-readable string for the agent system prompt
+// ─────────────────────────────────────────────────────────────────────────────
+function formatContextForPrompt(snapshot) {
+  if (!snapshot) return '';
+
+  const lines = [];
+  lines.push('── USER CONTEXT (live, captured just now) ──────────────────');
+
+  if (snapshot.active_app) {
+    lines.push(`Active app: ${snapshot.active_app}`);
+  }
+  if (snapshot.active_window && snapshot.active_window.title) {
+    lines.push(`Window title: ${snapshot.active_window.title}`);
+  }
+  if (snapshot.active_url) {
+    lines.push(`Browser URL: ${snapshot.active_url}`);
+  }
+  if (snapshot.browser_tab_title && snapshot.browser_tab_title !== snapshot.active_window?.title) {
+    lines.push(`Tab: ${snapshot.browser_tab_title}`);
+  }
+  if (snapshot.clipboard_text) {
+    lines.push(`Clipboard: "${snapshot.clipboard_text.slice(0, 200)}${snapshot.clipboard_text.length > 200 ? '...' : ''}"`);
+  }
+  if (snapshot.captured_at) {
+    lines.push(`Captured: ${snapshot.captured_at}`);
+  }
+
+  lines.push('────────────────────────────────────────────────────────────');
+
+  return lines.join('\n');
+}
+
+module.exports = { captureContext, formatContextForPrompt };

package/src/executor.js

@@ -15,11 +15,46 @@
  */
 
 const fs = require('fs').promises;
+const fsSync = require('fs');
 const path = require('path');
+const os = require('os');
 const { execSync, exec } = require('child_process');
 const { promisify } = require('util');
 const execAsync = promisify(exec);
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Custom Tool Registry
+// Tools the agent invents at runtime are stored here and persisted to disk.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CUSTOM_TOOLS_DIR = path.join(os.homedir(), '.promethios');
+const CUSTOM_TOOLS_FILE = path.join(CUSTOM_TOOLS_DIR, 'custom_tools.json');
+
+// In-memory registry: { [toolName]: { name, description, parameters, type, implementation, createdAt } }
+if (!global.__customToolRegistry) {
+  global.__customToolRegistry = {};
+  // Load persisted tools on first require
+  try {
+    if (fsSync.existsSync(CUSTOM_TOOLS_FILE)) {
+      const saved = JSON.parse(fsSync.readFileSync(CUSTOM_TOOLS_FILE, 'utf8'));
+      Object.assign(global.__customToolRegistry, saved);
+      const count = Object.keys(saved).length;
+      if (count > 0) console.log(`[Bridge] Loaded ${count} custom tool(s) from ${CUSTOM_TOOLS_FILE}`);
+    }
+  } catch (e) {
+    console.warn('[Bridge] Could not load custom tools:', e.message);
+  }
+}
+
+function saveCustomToolRegistry() {
+  try {
+    fsSync.mkdirSync(CUSTOM_TOOLS_DIR, { recursive: true });
+    fsSync.writeFileSync(CUSTOM_TOOLS_FILE, JSON.stringify(global.__customToolRegistry, null, 2), 'utf8');
+  } catch (e) {
+    console.warn('[Bridge] Could not save custom tools:', e.message);
+  }
+}
+
 async function executeLocalTool({ toolName, args, frameworkId, dev }) {
   const log = dev ? (...a) => console.log('[executor]', ...a) : () => {};
 
@@ -45,6 +80,79 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
   if (toolName === 'local_browser_control') {
     return executeLocalTool({ toolName: 'browser_control', args, frameworkId, dev });
   }
+  if (toolName === 'local_create_folder') {
+    return executeLocalTool({ toolName: 'create_folder', args, frameworkId, dev });
+  }
+  if (toolName === 'local_move') {
+    return executeLocalTool({ toolName: 'move_path', args, frameworkId, dev });
+  }
+  if (toolName === 'local_copy') {
+    return executeLocalTool({ toolName: 'copy_path', args, frameworkId, dev });
+  }
+  if (toolName === 'local_delete') {
+    return executeLocalTool({ toolName: 'delete_path', args, frameworkId, dev });
+  }
+  if (toolName === 'local_define_tool') {
+    return executeLocalTool({ toolName: 'define_tool', args, frameworkId, dev });
+  }
+  if (toolName === 'local_list_tools') {
+    return executeLocalTool({ toolName: 'list_tools', args, frameworkId, dev });
+  }
+  if (toolName === 'local_remove_tool') {
+    return executeLocalTool({ toolName: 'remove_tool', args, frameworkId, dev });
+  }
+
+  // ── Dynamic dispatch: check custom tool registry before the built-in switch ──
+  if (global.__customToolRegistry[toolName]) {
+    const toolDef = global.__customToolRegistry[toolName];
+    log(`Dispatching custom tool: ${toolName} (type=${toolDef.type})`);
+
+    if (toolDef.type === 'shell') {
+      // Level 1: shell template — substitute {param} placeholders with args values
+      let cmd = toolDef.implementation;
+      for (const [key, val] of Object.entries(args || {})) {
+        // Escape the value for shell safety (basic quoting)
+        const safe = String(val).replace(/"/g, '\\"');
+        cmd = cmd.replace(new RegExp(`\\{${key}\\}`, 'g'), safe);
+      }
+      log(`Custom shell tool cmd: ${cmd}`);
+      const timeoutMs = 30_000;
+      const { stdout, stderr } = await execAsync(cmd, {
+        timeout: timeoutMs,
+        cwd: args.cwd ? resolveSafePath(args.cwd) : os.homedir(),
+        maxBuffer: 1024 * 1024,
+      });
+      return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0, toolName };
+    }
+
+    if (toolDef.type === 'js') {
+      // Level 2: JS function body — run in vm sandbox
+      const vm = require('vm');
+      const context = vm.createContext({
+        args: { ...args },
+        fetch,
+        require,
+        process: { env: process.env, platform: process.platform },
+        console,
+        Buffer,
+        URL,
+        URLSearchParams,
+        crypto: require('crypto'),
+        fs: require('fs').promises,
+        path: require('path'),
+        os: require('os'),
+        execAsync,
+        resolveSafePath,
+        result: undefined,
+      });
+      const script = new vm.Script(`(async () => { ${toolDef.implementation} })().then(r => { result = r; });`);
+      await script.runInContext(context);
+      await new Promise(r => setTimeout(r, 200));
+      return context.result !== undefined ? context.result : { success: true, toolName };
+    }
+
+    throw new Error(`Custom tool "${toolName}" has unknown type: ${toolDef.type}. Expected 'shell' or 'js'.`);
+  }
 
   // ── local_execute is the built-in tool injected by the backend when the bridge
   //    is connected. It uses an `action` field to dispatch to the right handler.
@@ -126,12 +234,17 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
       try {
         playwright = require('playwright');
       } catch (e) {
-        // Playwright not installed — install it automatically
+        // Playwright not installed — install it locally into the bridge's own node_modules
+        // so require() can find it without relying on global npm or npx resolution.
         const chalk = require('chalk');
+        const bridgeDir = path.join(__dirname, '..');
         console.log(chalk.yellow('\n  Playwright not found — installing automatically (one-time setup, ~2 min)...\n'));
         try {
-          execSync('npm install -g playwright', { stdio: 'inherit' });
-          execSync('npx playwright install chromium', { stdio: 'inherit' });
+          execSync('npm install playwright --save-optional', { stdio: 'inherit', cwd: bridgeDir });
+          // Use the locally installed playwright binary directly to avoid npx resolution issues
+          const isWin = process.platform === 'win32';
+          const playwrightBin = path.join(bridgeDir, 'node_modules', '.bin', isWin ? 'playwright.cmd' : 'playwright');
+          execSync(`"${playwrightBin}" install chromium`, { stdio: 'inherit', cwd: bridgeDir });
           playwright = require('playwright');
           console.log(chalk.green('\n  Playwright installed. Browser automation is ready.\n'));
         } catch (installErr) {
@@ -410,6 +523,68 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
       };
     }
 
+    // ── File management ────────────────────────────────────────────────────────────
+    case 'create_folder': {
+      const folderPath = resolveSafePath(args.path);
+      log('create_folder', folderPath);
+      await fs.mkdir(folderPath, { recursive: true });
+      return { success: true, path: folderPath, created: true };
+    }
+
+    case 'move_path': {
+      const srcPath = resolveSafePath(args.src);
+      const dstPath = resolveSafePath(args.dst);
+      log('move_path', srcPath, '->', dstPath);
+      // Ensure destination parent directory exists
+      await fs.mkdir(path.dirname(dstPath), { recursive: true });
+      await fs.rename(srcPath, dstPath);
+      return { success: true, src: srcPath, dst: dstPath };
+    }
+
+    case 'copy_path': {
+      const srcPath = resolveSafePath(args.src);
+      const dstPath = resolveSafePath(args.dst);
+      log('copy_path', srcPath, '->', dstPath);
+      // Ensure destination parent directory exists
+      await fs.mkdir(path.dirname(dstPath), { recursive: true });
+      // Check if source is a directory
+      const srcStat = await fs.stat(srcPath);
+      if (srcStat.isDirectory()) {
+        // Recursive directory copy
+        async function copyDir(src, dst) {
+          await fs.mkdir(dst, { recursive: true });
+          const entries = await fs.readdir(src, { withFileTypes: true });
+          for (const entry of entries) {
+            const srcEntry = path.join(src, entry.name);
+            const dstEntry = path.join(dst, entry.name);
+            if (entry.isDirectory()) {
+              await copyDir(srcEntry, dstEntry);
+            } else {
+              await fs.copyFile(srcEntry, dstEntry);
+            }
+          }
+        }
+        await copyDir(srcPath, dstPath);
+        return { success: true, src: srcPath, dst: dstPath, type: 'directory' };
+      } else {
+        await fs.copyFile(srcPath, dstPath);
+        return { success: true, src: srcPath, dst: dstPath, type: 'file' };
+      }
+    }
+
+    case 'delete_path': {
+      const targetPath = resolveSafePath(args.path);
+      log('delete_path', targetPath);
+      const targetStat = await fs.stat(targetPath);
+      if (targetStat.isDirectory()) {
+        await fs.rm(targetPath, { recursive: true, force: true });
+        return { success: true, path: targetPath, type: 'directory' };
+      } else {
+        await fs.unlink(targetPath);
+        return { success: true, path: targetPath, type: 'file' };
+      }
+    }
+
     // ── Browser ────────────────────────────────────────────────────────────────────
     case 'open_browser': {
       const url = args.url;
@@ -553,6 +728,75 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
       }
     }
 
+    // ── Dynamic tool synthesis ───────────────────────────────────────────────────────────────
+    case 'define_tool': {
+      const { name: tName, description: tDesc, parameters: tParams, type: tType, implementation: tImpl } = args;
+      if (!tName) throw new Error('name is required');
+      if (!tType || !['shell', 'js'].includes(tType)) throw new Error('type must be "shell" or "js"');
+      if (!tImpl) throw new Error('implementation is required');
+      // Validate tool name: lowercase alphanumeric + underscores only
+      if (!/^[a-z][a-z0-9_]*$/.test(tName)) {
+        throw new Error(`Tool name "${tName}" is invalid. Use lowercase letters, numbers, and underscores only (must start with a letter).`);
+      }
+      // Prevent overwriting built-in tools
+      const RESERVED = ['local_shell','local_file_read','local_file_write','local_file_read_binary',
+        'local_file_upload_to_thread','local_browser_control','local_create_folder','local_move',
+        'local_copy','local_delete','local_define_tool','local_list_tools','local_remove_tool'];
+      if (RESERVED.includes(tName)) throw new Error(`Cannot redefine built-in tool: ${tName}`);
+
+      const toolEntry = {
+        name: tName,
+        description: tDesc || '',
+        parameters: tParams || { type: 'object', properties: {}, required: [] },
+        type: tType,
+        implementation: tImpl,
+        createdAt: new Date().toISOString(),
+      };
+      global.__customToolRegistry[tName] = toolEntry;
+      saveCustomToolRegistry();
+      log(`Defined custom tool: ${tName} (type=${tType})`);
+      return {
+        success: true,
+        toolName: tName,
+        type: tType,
+        message: `Tool "${tName}" registered successfully. You can now call it directly by name.`,
+        totalCustomTools: Object.keys(global.__customToolRegistry).length,
+      };
+    }
+
+    case 'list_tools': {
+      const tools = Object.values(global.__customToolRegistry);
+      if (tools.length === 0) {
+        return { tools: [], message: 'No custom tools defined yet. Use local_define_tool to create one.' };
+      }
+      return {
+        tools: tools.map(t => ({
+          name: t.name,
+          description: t.description,
+          type: t.type,
+          parameters: t.parameters,
+          createdAt: t.createdAt,
+        })),
+        count: tools.length,
+        message: `${tools.length} custom tool(s) available: ${tools.map(t => t.name).join(', ')}`,
+      };
+    }
+
+    case 'remove_tool': {
+      const { name: rName } = args;
+      if (!rName) throw new Error('name is required');
+      if (!global.__customToolRegistry[rName]) {
+        return { success: false, message: `Tool "${rName}" not found in custom registry.` };
+      }
+      delete global.__customToolRegistry[rName];
+      saveCustomToolRegistry();
+      return {
+        success: true,
+        message: `Tool "${rName}" removed from registry.`,
+        totalCustomTools: Object.keys(global.__customToolRegistry).length,
+      };
+    }
+
     // ── Custom tool (developer-written code from framework definition) ────
     case 'custom':
     default: {
@@ -608,33 +852,56 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
  *
  * On macOS/Linux the standard ~/Desktop is used.
  */
+// Cache the resolved Desktop path so registry queries don't repeat every call
+let _resolvedDesktopPath = null;
+
 function resolveDesktopPath() {
+  if (_resolvedDesktopPath) return _resolvedDesktopPath;
+
   if (process.platform !== 'win32') {
-    return path.join(require('os').homedir(), 'Desktop');
+    _resolvedDesktopPath = path.join(require('os').homedir(), 'Desktop');
+    console.log(`[Executor] Desktop path resolved (non-Windows): ${_resolvedDesktopPath}`);
+    return _resolvedDesktopPath;
   }
-  // Try registry first (most reliable — works even with custom Desktop locations)
+
+  // Try registry first (most reliable — works even with custom Desktop locations,
+  // including OneDrive Desktop Backup which silently redirects the Desktop folder)
   try {
     const { execSync } = require('child_process');
     const regOut = execSync(
       'reg query "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders" /v Desktop',
-      { encoding: 'utf8', timeout: 3000 }
+      { encoding: 'utf8', timeout: 5000 }
     );
     const match = regOut.match(/Desktop\s+REG_(?:SZ|EXPAND_SZ)\s+(.+)/i);
     if (match) {
       // Expand environment variables like %USERPROFILE%
       let desktopPath = match[1].trim();
       desktopPath = desktopPath.replace(/%([^%]+)%/g, (_, varName) => process.env[varName] || `%${varName}%`);
-      if (require('fs').existsSync(desktopPath)) return desktopPath;
+      if (require('fs').existsSync(desktopPath)) {
+        _resolvedDesktopPath = desktopPath;
+        console.log(`[Executor] Desktop path resolved via registry: ${_resolvedDesktopPath}`);
+        return _resolvedDesktopPath;
+      } else {
+        console.warn(`[Executor] Registry Desktop path does not exist on disk: ${desktopPath} — falling through`);
+      }
     }
-  } catch { /* registry query failed, fall through */ }
+  } catch (regErr) {
+    console.warn(`[Executor] Registry Desktop query failed (${regErr.message}) — falling through to OneDrive check`);
+  }
 
   // Fallback: check OneDrive Desktop first (most common on Windows 11)
   const userProfile = process.env.USERPROFILE || require('os').homedir();
   const oneDriveDesktop = path.join(userProfile, 'OneDrive', 'Desktop');
-  if (require('fs').existsSync(oneDriveDesktop)) return oneDriveDesktop;
+  if (require('fs').existsSync(oneDriveDesktop)) {
+    _resolvedDesktopPath = oneDriveDesktop;
+    console.log(`[Executor] Desktop path resolved via OneDrive fallback: ${_resolvedDesktopPath}`);
+    return _resolvedDesktopPath;
+  }
 
   // Final fallback: local Desktop
-  return path.join(userProfile, 'Desktop');
+  _resolvedDesktopPath = path.join(userProfile, 'Desktop');
+  console.log(`[Executor] Desktop path resolved via local fallback: ${_resolvedDesktopPath}`);
+  return _resolvedDesktopPath;
 }
 
 function resolveSafePath(inputPath) {