assistme 0.6.9 → 0.8.1

package/dist/chunk-4RHN77BN.js

@@ -0,0 +1,3383 @@
+import {
+  AppError,
+  BrowseSkillRowSchema,
+  CDP_COMMAND_TIMEOUT_MS,
+  FRAME_CONTEXTS_MAX_SIZE,
+  MEMORY_COMPRESSION_TARGET,
+  MEMORY_COMPRESSION_THRESHOLD,
+  MEMORY_DEDUP_SIMILARITY_THRESHOLD,
+  SCHEDULER_INTERVAL_MS,
+  SHELL_MAX_OUTPUT,
+  SHELL_TIMEOUT_MS,
+  SKILL_DESCRIPTION_BUDGET_CHARS,
+  SkillCreateResultSchema,
+  SkillRowSchema,
+  WS_CONNECT_TIMEOUT_MS,
+  callMcpHandler,
+  errorMessage,
+  log,
+  readAuthStore,
+  safeParse,
+  writeAuthStore
+} from "./chunk-QHMIXIWO.js";
+import {
+  getConfig
+} from "./chunk-YYSJHZSO.js";
+
+// src/db/auth.ts
+async function loginWithToken(mcpToken) {
+  if (!mcpToken.startsWith("am_")) {
+    throw new Error("Invalid token format. Use an am_ token from the web page.");
+  }
+  const result = await callMcpHandler(
+    "auth.validate_token",
+    {},
+    mcpToken
+  );
+  const store = readAuthStore();
+  store["mcp_token"] = mcpToken;
+  writeAuthStore(store);
+  return result.user_id;
+}
+async function getCurrentUserId() {
+  const result = await callMcpHandler("auth.validate_token");
+  return result.user_id;
+}
+async function logout() {
+  try {
+    writeAuthStore({});
+  } catch {
+  }
+}
+
+// src/db/session.ts
+async function createSession(sessionName, workspacePath, version) {
+  const { getConfig: getConfig2 } = await import("./config-3RWSAUAZ.js");
+  const data = await callMcpHandler("session.create", {
+    session_name: sessionName,
+    workspace_path: workspacePath,
+    version,
+    model: getConfig2().model || null
+  });
+  return data;
+}
+async function updateHeartbeat(sessionId) {
+  try {
+    await callMcpHandler("session.heartbeat", { session_id: sessionId });
+  } catch (err) {
+    log.warn(`Heartbeat update failed: ${err instanceof Error ? err.message : err}`);
+  }
+}
+async function endSession(sessionId) {
+  try {
+    await callMcpHandler("session.end", { session_id: sessionId });
+  } catch (err) {
+    log.error(`Failed to end session: ${err instanceof Error ? err.message : err}`);
+  }
+}
+async function setSessionBusy(sessionId, busy) {
+  await callMcpHandler("session.set_busy", {
+    session_id: sessionId,
+    busy
+  });
+}
+async function cleanupStaleSessions(currentSessionId, thresholdMs = 12e4) {
+  try {
+    const result = await callMcpHandler("session.cleanup_stale", {
+      current_session_id: currentSessionId,
+      threshold_ms: thresholdMs
+    });
+    return result.cleaned;
+  } catch {
+    return 0;
+  }
+}
+async function getActiveSessions(limit = 5) {
+  return callMcpHandler("session.get_active", { limit });
+}
+
+// src/db/task.ts
+async function createTask(conversationId, sessionId, prompt) {
+  const data = await callMcpHandler("task.create", {
+    conversation_id: conversationId,
+    session_id: sessionId,
+    prompt
+  });
+  return { ...data, prompt };
+}
+async function pollAndClaimTask(sessionId) {
+  try {
+    const data = await callMcpHandler("task.poll_and_claim", {
+      session_id: sessionId
+    });
+    if (!data) return null;
+    return {
+      ...data,
+      prompt: data.metadata?.prompt || data.content || ""
+    };
+  } catch (err) {
+    log.warn(`Poll-and-claim failed: ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}
+async function claimTask(messageId) {
+  const data = await callMcpHandler("task.claim", {
+    message_id: messageId
+  });
+  return data;
+}
+async function completeTask(messageId, resultSummary, tokenUsage) {
+  await callMcpHandler("task.complete", {
+    message_id: messageId,
+    result: resultSummary,
+    token_usage: tokenUsage || null
+  });
+}
+async function failTask(messageId, errorMessage2) {
+  try {
+    await callMcpHandler("task.fail", {
+      message_id: messageId,
+      error: errorMessage2
+    });
+  } catch (err) {
+    log.error(`Failed to update task status: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+// src/db/conversation.ts
+async function getOrCreateCliConversation() {
+  const data = await callMcpHandler("conversation.get_or_create");
+  return data;
+}
+async function getConversationHistory(conversationId, excludeMessageId, limit = 20) {
+  try {
+    const rows = await callMcpHandler("conversation.get_history", {
+      conversation_id: conversationId,
+      exclude_message_id: excludeMessageId,
+      limit
+    });
+    return (rows || []).reverse().map((row) => {
+      const prompt = row.metadata?.prompt || "";
+      const content = row.content || "";
+      const response = row.status === "failed" ? `[Task failed] ${content}` : content;
+      return { prompt, response };
+    }).filter((entry) => entry.prompt && entry.response);
+  } catch (err) {
+    log.debug(`Failed to fetch conversation history: ${err instanceof Error ? err.message : err}`);
+    return [];
+  }
+}
+
+// src/db/event.ts
+var MAX_EMIT_RETRIES = 2;
+var EMIT_RETRY_DELAY_MS = 500;
+async function emitWithRetry(messageId, eventType, eventData, seq) {
+  for (let attempt = 0; attempt <= MAX_EMIT_RETRIES; attempt++) {
+    try {
+      await callMcpHandler("event.emit", {
+        message_id: messageId,
+        event_type: eventType,
+        event_data: eventData,
+        seq
+      });
+      return;
+    } catch (err) {
+      if (attempt < MAX_EMIT_RETRIES) {
+        await new Promise((r) => setTimeout(r, EMIT_RETRY_DELAY_MS * (attempt + 1)));
+      } else {
+        log.warn(
+          `Failed to emit event after ${MAX_EMIT_RETRIES + 1} attempts: ${err instanceof Error ? err.message : err}`
+        );
+      }
+    }
+  }
+}
+var eventSequence = 0;
+function resetEventSequence() {
+  eventSequence = 0;
+}
+async function emitEvent(messageId, eventType, eventData) {
+  eventSequence++;
+  await emitWithRetry(messageId, eventType, eventData, eventSequence);
+}
+
+// src/db/action.ts
+async function setActionRequest(messageId, actionData) {
+  await callMcpHandler("action.set_request", {
+    message_id: messageId,
+    action_data: actionData
+  });
+}
+async function pollActionResponse(messageId) {
+  return callMcpHandler("action.poll_response", {
+    message_id: messageId
+  });
+}
+
+// src/db/job-poll.ts
+async function pollAndClaimJobRun() {
+  try {
+    const data = await callMcpHandler("job.claim_pending_run");
+    return data;
+  } catch (err) {
+    log.debug(`Job run poll failed: ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}
+
+// src/browser/chrome-launcher.ts
+import { execSync, spawn } from "child_process";
+import { platform as platform2, homedir } from "os";
+import { existsSync, unlinkSync, mkdirSync, cpSync } from "fs";
+import { join } from "path";
+
+// src/browser/controller.ts
+import { WebSocket } from "ws";
+import { platform } from "os";
+var BrowserController = class {
+  ws = null;
+  debugPort;
+  messageId = 0;
+  callbacks = /* @__PURE__ */ new Map();
+  connected = false;
+  currentTabId = null;
+  refCache = /* @__PURE__ */ new Map();
+  frameContexts = /* @__PURE__ */ new Map();
+  // refId → contextId
+  constructor(port = 9222) {
+    this.debugPort = port;
+  }
+  // ── Connection ──────────────────────────────────────────────────
+  async isAvailable() {
+    try {
+      const res = await fetch(`http://127.0.0.1:${this.debugPort}/json/version`, {
+        signal: AbortSignal.timeout(2e3)
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+  async connect(tabIndex) {
+    if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+      if (tabIndex === void 0) {
+        return "Already connected to browser.";
+      }
+      const tabs2 = await this.getTabs();
+      const pageTabs2 = tabs2.filter((t) => t.type === "page");
+      const targetTab2 = pageTabs2[tabIndex];
+      if (targetTab2 && targetTab2.id === this.currentTabId) {
+        return `Already connected to tab: "${targetTab2.title}"`;
+      }
+      await this.disconnect();
+    }
+    const available = await this.isAvailable();
+    if (!available) {
+      throw new Error(
+        `Cannot connect to browser on port ${this.debugPort}. Chrome remote debugging is not reachable. Please ensure Chrome is running with remote debugging enabled.`
+      );
+    }
+    const tabs = await this.getTabs();
+    const pageTabs = tabs.filter((t) => t.type === "page");
+    if (pageTabs.length === 0) {
+      throw new Error("No browser tabs found. Please open at least one tab.");
+    }
+    const targetTab = pageTabs[tabIndex ?? 0];
+    if (!targetTab.webSocketDebuggerUrl) {
+      throw new Error("Tab does not expose a WebSocket debugger URL.");
+    }
+    this.currentTabId = targetTab.id;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      this.ws = new WebSocket(targetTab.webSocketDebuggerUrl);
+      const connectTimeout = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          this.ws?.close();
+          reject(new Error(`Connection timeout (${WS_CONNECT_TIMEOUT_MS}ms)`));
+        }
+      }, WS_CONNECT_TIMEOUT_MS);
+      this.ws.on("open", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(connectTimeout);
+        this.connected = true;
+        this.send("Page.enable").catch(() => {
+        });
+        this.send("Runtime.enable").catch(() => {
+        });
+        this.send("DOM.enable").catch(() => {
+        });
+        resolve(`Connected to tab: "${targetTab.title}" (${targetTab.url})`);
+      });
+      this.ws.on("message", (data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          if (msg.id !== void 0 && this.callbacks.has(msg.id)) {
+            this.callbacks.get(msg.id)(msg);
+            this.callbacks.delete(msg.id);
+          }
+        } catch {
+        }
+      });
+      this.ws.on("error", (err) => {
+        this.connected = false;
+        if (!settled) {
+          settled = true;
+          clearTimeout(connectTimeout);
+          reject(new Error(`WebSocket error: ${err.message}`));
+        }
+      });
+      this.ws.on("close", () => {
+        this.connected = false;
+        this.ws = null;
+        for (const [id, cb] of this.callbacks) {
+          cb({ id, error: { code: -1, message: "WebSocket closed" } });
+        }
+        this.callbacks.clear();
+      });
+    });
+  }
+  async disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+      this.connected = false;
+    }
+    this.refCache.clear();
+    this.frameContexts.clear();
+    return "Disconnected from browser.";
+  }
+  // ── CDP Protocol ────────────────────────────────────────────────
+  async getTabs() {
+    const res = await fetch(`http://127.0.0.1:${this.debugPort}/json`, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    return await res.json();
+  }
+  send(method, params) {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        reject(new Error("Not connected to browser. Call browser_connect first."));
+        return;
+      }
+      const id = ++this.messageId;
+      const timeout = setTimeout(() => {
+        this.callbacks.delete(id);
+        reject(new Error(`CDP command timed out: ${method}`));
+      }, CDP_COMMAND_TIMEOUT_MS);
+      this.callbacks.set(id, (response) => {
+        clearTimeout(timeout);
+        if (response.error) {
+          reject(new Error(`CDP error: ${response.error.message}`));
+        } else {
+          resolve(response.result || {});
+        }
+      });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+  ensureConnected() {
+    if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("Not connected to browser. Use browser_connect tool first.");
+    }
+  }
+  // ── Navigation ──────────────────────────────────────────────────
+  async navigate(url) {
+    this.ensureConnected();
+    await this.send("Page.navigate", { url });
+    await this.waitForLoad();
+    const info = await this.getPageInfo();
+    return `Navigated to: ${info.title}
+URL: ${info.url}`;
+  }
+  async goBack() {
+    this.ensureConnected();
+    try {
+      const history = await this.send("Page.getNavigationHistory");
+      const idx = history.currentIndex ?? 0;
+      const entries = history.entries ?? [];
+      if (idx > 0 && entries[idx - 1]) {
+        await this.send("Page.navigateToHistoryEntry", {
+          entryId: entries[idx - 1].id
+        });
+      } else {
+        await this.evaluate("window.history.back()");
+      }
+    } catch {
+      await this.evaluate("window.history.back()");
+    }
+    await this.waitForLoad();
+    const info = await this.getPageInfo();
+    return `Went back to: ${info.title}`;
+  }
+  async reload() {
+    this.ensureConnected();
+    await this.send("Page.reload");
+    await this.waitForLoad();
+    return "Page reloaded.";
+  }
+  // ── Page Reading ────────────────────────────────────────────────
+  async readPage() {
+    this.ensureConnected();
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          // Get page title and URL
+          let output = "Title: " + document.title + "\\n";
+          output += "URL: " + window.location.href + "\\n\\n";
+
+          // Get main text content, cleaned up
+          const body = document.body.cloneNode(true);
+          // Remove scripts, styles, navs that add noise
+          body.querySelectorAll('script, style, noscript, svg, iframe').forEach(el => el.remove());
+
+          const text = body.innerText
+            .split('\\n')
+            .map(line => line.trim())
+            .filter(line => line.length > 0)
+            .join('\\n');
+
+          output += text;
+          return output.slice(0, 30000);
+        })()
+      `,
+      returnByValue: true
+    });
+    return result.result?.value || "Could not read page content.";
+  }
+  async readElement(selector) {
+    this.ensureConnected();
+    const selectorJS = JSON.stringify(selector);
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
+          return el.innerText || el.textContent || el.value || '(empty)';
+        })()
+      `,
+      returnByValue: true
+    });
+    return result.result?.value || "Element not found.";
+  }
+  async getPageInfo() {
+    const result = await this.send("Runtime.evaluate", {
+      expression: `JSON.stringify({ title: document.title, url: window.location.href })`,
+      returnByValue: true
+    });
+    try {
+      return JSON.parse(result.result?.value || "{}");
+    } catch {
+      return { title: "Unknown", url: "unknown" };
+    }
+  }
+  // ── Screenshots (for Claude vision) ─────────────────────────────
+  async screenshot() {
+    this.ensureConnected();
+    const result = await this.send("Page.captureScreenshot", {
+      format: "png",
+      quality: 80,
+      captureBeyondViewport: false
+    });
+    return result.data || "";
+  }
+  // ── Interactions ────────────────────────────────────────────────
+  async click(selector) {
+    this.ensureConnected();
+    const selectorJS = JSON.stringify(selector);
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          var sel = ${selectorJS};
+
+          // Support :contains('text') pseudo-selector (not native CSS)
+          var containsMatch = sel.match(/^(.+?)?:contains\\(['"](.+?)['"]\\)$/);
+          if (containsMatch) {
+            var baseTag = (containsMatch[1] || '*').toLowerCase();
+            var searchText = containsMatch[2];
+            var candidates = document.querySelectorAll(baseTag === '*' ? '*' : baseTag);
+            var found = null;
+            for (var i = 0; i < candidates.length; i++) {
+              var c = candidates[i];
+              // Prefer exact text match on direct text content (not children)
+              var directText = Array.from(c.childNodes)
+                .filter(function(n) { return n.nodeType === 3; })
+                .map(function(n) { return n.textContent.trim(); })
+                .join(' ');
+              if (directText === searchText || c.textContent.trim() === searchText) {
+                // Prefer the deepest (most specific) matching element
+                if (!found || found.contains(c)) found = c;
+              }
+            }
+            if (!found) return 'Element not found: ' + sel;
+            found.scrollIntoView({ block: 'center', behavior: 'instant' });
+            found.click();
+            return 'Clicked: ' + (found.tagName || '') + ' ' + (found.textContent || '').slice(0, 50).trim();
+          }
+
+          var el = document.querySelector(sel);
+          if (!el) return 'Element not found: ' + sel;
+
+          // Scroll into view
+          el.scrollIntoView({ block: 'center', behavior: 'instant' });
+
+          // Click
+          el.click();
+          return 'Clicked: ' + (el.tagName || '') + ' ' + (el.textContent || '').slice(0, 50).trim();
+        })()
+      `,
+      returnByValue: true
+    });
+    await new Promise((r) => setTimeout(r, 500));
+    return result.result?.value || "Click executed.";
+  }
+  async typeText(selector, text) {
+    this.ensureConnected();
+    const selectorJS = JSON.stringify(selector);
+    const textJS = JSON.stringify(text);
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          var el = document.querySelector(${selectorJS});
+
+          // If not found in main document, search same-origin iframes
+          if (!el) {
+            var iframes = document.querySelectorAll('iframe');
+            for (var i = 0; i < iframes.length; i++) {
+              try {
+                var iframeDoc = iframes[i].contentDocument;
+                if (iframeDoc) {
+                  el = iframeDoc.querySelector(${selectorJS});
+                  if (el) break;
+                }
+              } catch(e) { /* cross-origin, skip */ }
+            }
+          }
+
+          if (!el) return 'Element not found: ' + ${selectorJS};
+
+          el.focus();
+
+          // Check if this is a contenteditable element (rich text editor)
+          var isContentEditable = el.isContentEditable ||
+            el.getAttribute('contenteditable') === 'true' ||
+            el.getAttribute('contenteditable') === '';
+
+          if (isContentEditable) {
+            // For contenteditable: select all content, then replace
+            var ownerDoc = el.ownerDocument;
+            var sel = ownerDoc.defaultView.getSelection();
+            var range = ownerDoc.createRange();
+            range.selectNodeContents(el);
+            sel.removeAllRanges();
+            sel.addRange(range);
+            // Use insertText command which respects undo stack and triggers input events
+            ownerDoc.execCommand('insertText', false, ${textJS});
+            return 'Typed into: ' + (el.tagName || '') + ' [contenteditable]';
+          }
+
+          // For input/textarea: clear and set value
+          var nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+            window.HTMLInputElement.prototype, 'value'
+          )?.set || Object.getOwnPropertyDescriptor(
+            window.HTMLTextAreaElement.prototype, 'value'
+          )?.set;
+          if (nativeInputValueSetter) {
+            nativeInputValueSetter.call(el, ${textJS});
+          } else {
+            el.value = ${textJS};
+          }
+
+          // Dispatch events that frameworks (React, Angular, Material) listen to
+          el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
+          el.dispatchEvent(new Event('change', { bubbles: true, cancelable: true }));
+          el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: ${textJS} }));
+          return 'Typed into: ' + (el.tagName || '') + ' [' + (el.name || el.id || '') + ']';
+        })()
+      `,
+      returnByValue: true
+    });
+    const textResult = result.result?.value || "";
+    if (textResult.startsWith("Element not found")) {
+      return this.typeAtFocus(text);
+    }
+    return textResult || "Text entered.";
+  }
+  /**
+   * Type text into the currently focused element using CDP Input.insertText.
+   * This bypasses DOM queries entirely and works with any focused element,
+   * including those inside cross-origin iframes or shadow DOM.
+   */
+  async typeAtFocus(text) {
+    this.ensureConnected();
+    const modKey = platform() === "darwin" ? "Meta" : "Control";
+    await this.pressKey(`${modKey}+a`);
+    await new Promise((r) => setTimeout(r, 50));
+    await this.pressKey("Backspace");
+    await new Promise((r) => setTimeout(r, 50));
+    await this.send("Input.insertText", { text });
+    await new Promise((r) => setTimeout(r, 100));
+    return "Text entered (into focused element).";
+  }
+  async pressKey(key) {
+    this.ensureConnected();
+    const keyMap = {
+      Enter: { keyCode: 13, code: "Enter" },
+      Tab: { keyCode: 9, code: "Tab" },
+      Escape: { keyCode: 27, code: "Escape" },
+      Backspace: { keyCode: 8, code: "Backspace" },
+      Delete: { keyCode: 46, code: "Delete" },
+      ArrowDown: { keyCode: 40, code: "ArrowDown" },
+      ArrowUp: { keyCode: 38, code: "ArrowUp" },
+      ArrowLeft: { keyCode: 37, code: "ArrowLeft" },
+      ArrowRight: { keyCode: 39, code: "ArrowRight" },
+      Home: { keyCode: 36, code: "Home" },
+      End: { keyCode: 35, code: "End" },
+      Space: { keyCode: 32, code: "Space" }
+    };
+    const modifierMap = {
+      Alt: 1,
+      Control: 2,
+      Meta: 4,
+      Shift: 8
+    };
+    const parts = key.split("+");
+    let modifiers = 0;
+    let actualKey = parts[parts.length - 1];
+    for (let i = 0; i < parts.length - 1; i++) {
+      const mod = modifierMap[parts[i]];
+      if (mod) modifiers |= mod;
+    }
+    const mapped = keyMap[actualKey];
+    if (mapped) {
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: actualKey,
+        code: mapped.code,
+        windowsVirtualKeyCode: mapped.keyCode,
+        nativeVirtualKeyCode: mapped.keyCode,
+        modifiers
+      });
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: actualKey,
+        code: mapped.code,
+        windowsVirtualKeyCode: mapped.keyCode,
+        nativeVirtualKeyCode: mapped.keyCode,
+        modifiers
+      });
+    } else if (actualKey.length === 1) {
+      const code = `Key${actualKey.toUpperCase()}`;
+      const keyCode = actualKey.toUpperCase().charCodeAt(0);
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: actualKey,
+        code,
+        windowsVirtualKeyCode: keyCode,
+        nativeVirtualKeyCode: keyCode,
+        modifiers
+      });
+      if (!modifiers) {
+        await this.send("Input.dispatchKeyEvent", {
+          type: "char",
+          text: actualKey,
+          modifiers
+        });
+      }
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: actualKey,
+        code,
+        modifiers
+      });
+    } else {
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: actualKey,
+        modifiers
+      });
+      await this.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: actualKey,
+        modifiers
+      });
+    }
+    return `Pressed key: ${key}`;
+  }
+  async scrollDown() {
+    this.ensureConnected();
+    await this.send("Runtime.evaluate", {
+      expression: "window.scrollBy(0, window.innerHeight * 0.8)"
+    });
+    await new Promise((r) => setTimeout(r, 300));
+    return "Scrolled down.";
+  }
+  async scrollUp() {
+    this.ensureConnected();
+    await this.send("Runtime.evaluate", {
+      expression: "window.scrollBy(0, -window.innerHeight * 0.8)"
+    });
+    await new Promise((r) => setTimeout(r, 300));
+    return "Scrolled up.";
+  }
+  // ── Annotated Snapshot (ref system) ─────────────────────────────
+  /**
+   * Take a snapshot of all interactive elements on the page.
+   *
+   * Strategy (informed by research — arxiv:2511.19477):
+   *  - **Text ref table is ALWAYS returned** — compact, low-token, works for
+   *    all page complexities including dense layouts (date pickers, tables).
+   *  - **Annotated screenshot is OPTIONAL** (annotate parameter):
+   *    - true:  overlay ref badges on screenshot (best for simple pages with
+   *             few interactive elements — gives visual context)
+   *    - false: plain screenshot without overlays (default — avoids label
+   *             clutter on dense pages; model still sees the page visually)
+   *    - Research shows text-based grounding outperforms visual annotations
+   *      on complex pages, and the hybrid approach (a11y text primary +
+   *      selective vision) achieves ~85% vs ~50% for pure vision.
+   */
+  async snapshot(annotate = false) {
+    this.ensureConnected();
+    await this.waitForLoad(5e3);
+    const findResult = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          // Clean up previous refs
+          document.querySelectorAll('[data-assistme-ref]').forEach(function(el) {
+            el.removeAttribute('data-assistme-ref');
+          });
+
+          var selectors = [
+            'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
+            '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]',
+            '[role="combobox"]', '[role="listbox"]', '[role="menuitem"]', '[role="tab"]',
+            '[role="switch"]', '[role="slider"]', '[role="option"]', '[role="searchbox"]',
+            '[onclick]', '[tabindex]:not([tabindex="-1"])',
+            '[contenteditable="true"]'
+          ].join(', ');
+
+          // Collect elements from main document AND same-origin iframes
+          var all = Array.from(document.querySelectorAll(selectors));
+          try {
+            var iframes = document.querySelectorAll('iframe');
+            for (var fi = 0; fi < iframes.length; fi++) {
+              try {
+                var iframeDoc = iframes[fi].contentDocument;
+                if (iframeDoc) {
+                  var iframeRect = iframes[fi].getBoundingClientRect();
+                  var iframeEls = iframeDoc.querySelectorAll(selectors);
+                  for (var fe = 0; fe < iframeEls.length; fe++) {
+                    // Tag iframe elements with offset for coordinate correction
+                    iframeEls[fe].__iframeOffset = { x: iframeRect.x, y: iframeRect.y };
+                    all.push(iframeEls[fe]);
+                  }
+                }
+              } catch(e) { /* cross-origin iframe, skip */ }
+            }
+          } catch(e) { /* iframe enumeration failed, continue */ }
+
+          var refs = [];
+          var vh = window.innerHeight;
+          var vw = window.innerWidth;
+
+          for (var i = 0; i < all.length && refs.length < 80; i++) {
+            var el = all[i];
+            var rect = el.getBoundingClientRect();
+
+            // Skip invisible / tiny elements
+            if (rect.width < 5 || rect.height < 5) continue;
+            var style = window.getComputedStyle(el);
+            if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') continue;
+
+            // Skip elements far outside viewport
+            if (rect.bottom < -50 || rect.top > vh + 50) continue;
+            if (rect.right < -50 || rect.left > vw + 50) continue;
+
+            // Determine role
+            var role = el.getAttribute('role') || '';
+            if (!role) {
+              var tag = el.tagName.toLowerCase();
+              if (tag === 'a') role = 'link';
+              else if (tag === 'button') role = 'button';
+              else if (tag === 'input') {
+                var t = (el.type || 'text').toLowerCase();
+                if (t === 'checkbox') role = 'checkbox';
+                else if (t === 'radio') role = 'radio';
+                else if (t === 'submit' || t === 'button') role = 'button';
+                else role = 'textbox';
+              }
+              else if (tag === 'select') role = 'combobox';
+              else if (tag === 'textarea') role = 'textbox';
+              else role = tag;
+            }
+
+            // Determine accessible name
+            var name = '';
+            var ariaLabel = el.getAttribute('aria-label');
+            var ariaLabelledBy = el.getAttribute('aria-labelledby');
+            if (ariaLabel) {
+              name = ariaLabel;
+            } else if (ariaLabelledBy) {
+              var labelEl = document.getElementById(ariaLabelledBy);
+              if (labelEl) name = labelEl.textContent.trim();
+            } else if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+              if (el.id) {
+                var lbl = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+                if (lbl) name = lbl.textContent.trim();
+              }
+              if (!name) name = el.getAttribute('placeholder') || el.getAttribute('name') || '';
+            } else {
+              name = (el.textContent || '').trim().slice(0, 60);
+            }
+
+            var refId = refs.length + 1;
+            el.setAttribute('data-assistme-ref', String(refId));
+
+            // Correct coordinates for elements inside iframes
+            var offsetX = el.__iframeOffset ? el.__iframeOffset.x : 0;
+            var offsetY = el.__iframeOffset ? el.__iframeOffset.y : 0;
+
+            refs.push({
+              id: refId,
+              role: role,
+              name: name,
+              tag: el.tagName.toLowerCase(),
+              type: el.getAttribute('type') || '',
+              box: {
+                x: Math.round(rect.x + offsetX),
+                y: Math.round(rect.y + offsetY),
+                width: Math.round(rect.width),
+                height: Math.round(rect.height)
+              }
+            });
+          }
+
+          return JSON.stringify(refs);
+        })()
+      `,
+      returnByValue: true
+    });
+    const refs = JSON.parse(
+      findResult.result?.value || "[]"
+    ).map((r) => ({
+      id: r.id,
+      role: r.role,
+      name: r.name,
+      tag: r.tag,
+      inputType: r.type || "",
+      box: r.box
+    }));
+    await this.discoverCrossOriginFrameRefs(refs);
+    if (annotate && refs.length <= 40) {
+      const refsJson = JSON.stringify(refs);
+      await this.send("Runtime.evaluate", {
+        expression: `
+          (function() {
+            var old = document.getElementById('__assistme_refs__');
+            if (old) old.remove();
+
+            var overlay = document.createElement('div');
+            overlay.id = '__assistme_refs__';
+            overlay.style.cssText = 'position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2147483647;';
+
+            var refs = ${refsJson};
+            var vh = window.innerHeight;
+            var vw = window.innerWidth;
+
+            for (var i = 0; i < refs.length; i++) {
+              var b = refs[i].box;
+              if (b.y + b.height < 0 || b.y > vh || b.x + b.width < 0 || b.x > vw) continue;
+
+              // Red badge with ref number
+              var badge = document.createElement('div');
+              var badgeTop = Math.max(0, b.y - 14);
+              var badgeLeft = Math.max(0, b.x);
+              badge.style.cssText = 'position:fixed;background:#e8384f;color:#fff;font:bold 10px/1.2 monospace;padding:1px 3px;border-radius:2px;white-space:nowrap;'
+                + 'left:' + badgeLeft + 'px;top:' + badgeTop + 'px;';
+              badge.textContent = String(refs[i].id);
+              overlay.appendChild(badge);
+
+              // Border around element
+              var border = document.createElement('div');
+              border.style.cssText = 'position:fixed;border:1.5px solid #e8384f;border-radius:2px;'
+                + 'left:' + b.x + 'px;top:' + b.y + 'px;width:' + b.width + 'px;height:' + b.height + 'px;';
+              overlay.appendChild(border);
+            }
+
+            document.documentElement.appendChild(overlay);
+          })()
+        `
+      });
+    }
+    const image = await this.screenshot();
+    if (annotate) {
+      await this.send("Runtime.evaluate", {
+        expression: `(function() { var el = document.getElementById('__assistme_refs__'); if (el) el.remove(); })()`
+      });
+    }
+    this.refCache.clear();
+    for (const ref of refs) {
+      this.refCache.set(ref.id, ref);
+    }
+    const pageInfo = await this.getPageInfo();
+    return { image, refs, url: pageInfo.url, title: pageInfo.title };
+  }
+  /**
+   * Build a compact text table of refs for the model.
+   */
+  static formatRefTable(result) {
+    let table = `Page: ${result.title}
+URL: ${result.url}
+
+Refs:
+`;
+    for (const ref of result.refs) {
+      const extra = ref.inputType ? ` (${ref.inputType})` : "";
+      const nameStr = ref.name ? ` "${ref.name}"` : "";
+      table += `[${ref.id}] ${ref.role}${nameStr}${extra}
+`;
+    }
+    if (result.refs.length === 0) {
+      table += "(no interactive elements found)\n";
+    }
+    return table;
+  }
+  // ── Cross-Origin Iframe Discovery ────────────────────────────────
+  /**
+   * Use CDP's Page.getFrameTree + Runtime.evaluate with contextId to discover
+   * interactive elements inside cross-origin iframes (e.g., ProtonMail editor,
+   * Google Docs, embedded rich text editors).
+   *
+   * Same-origin iframes are already handled inline by the main snapshot JS.
+   * This method handles the ones that threw cross-origin errors.
+   */
+  async discoverCrossOriginFrameRefs(refs) {
+    this.frameContexts.clear();
+    try {
+      const frameTree = await this.send("Page.getFrameTree");
+      const mainFrameId = frameTree.frameTree?.frame?.id;
+      const childFrames = frameTree.frameTree?.childFrames || [];
+      if (childFrames.length === 0) return;
+      const contexts = await this.getFrameContexts(mainFrameId || "");
+      for (const child of childFrames) {
+        const frameId = child.frame.id;
+        const contextId = contexts.get(frameId);
+        if (!contextId) continue;
+        const iframeOffsetResult = await this.send("Runtime.evaluate", {
+          expression: `
+            (function() {
+              var iframes = document.querySelectorAll('iframe');
+              for (var i = 0; i < iframes.length; i++) {
+                try {
+                  // Match by frame src or name
+                  var f = iframes[i];
+                  if (f.contentWindow) {
+                    var r = f.getBoundingClientRect();
+                    if (r.width > 10 && r.height > 10) {
+                      return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, index: i });
+                    }
+                  }
+                } catch(e) {}
+              }
+              return 'null';
+            })()
+          `,
+          returnByValue: true
+        });
+        let iframeOffset = { x: 0, y: 0 };
+        try {
+          const parsed = JSON.parse(
+            iframeOffsetResult.result?.value || "null"
+          );
+          if (parsed) iframeOffset = { x: parsed.x, y: parsed.y };
+        } catch {
+        }
+        const startRefId = refs.length + 1;
+        try {
+          const frameResult = await this.send("Runtime.evaluate", {
+            expression: `
+              (function() {
+                var selectors = [
+                  'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
+                  '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]',
+                  '[role="combobox"]', '[role="listbox"]', '[role="menuitem"]', '[role="tab"]',
+                  '[role="switch"]', '[role="slider"]', '[role="option"]', '[role="searchbox"]',
+                  '[onclick]', '[tabindex]:not([tabindex="-1"])',
+                  '[contenteditable="true"]', '[contenteditable=""]'
+                ].join(', ');
+
+                var all = document.querySelectorAll(selectors);
+                // Also check if the body itself is contenteditable
+                if (document.body && (document.body.isContentEditable || document.body.getAttribute('contenteditable') === 'true')) {
+                  all = [document.body].concat(Array.from(all));
+                }
+
+                var refs = [];
+                var startId = ${startRefId};
+                var vh = window.innerHeight;
+                var vw = window.innerWidth;
+
+                for (var i = 0; i < all.length && refs.length < 20; i++) {
+                  var el = all[i];
+                  var rect = el.getBoundingClientRect();
+                  if (rect.width < 5 || rect.height < 5) continue;
+                  var style = window.getComputedStyle(el);
+                  if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') continue;
+
+                  var role = el.getAttribute('role') || '';
+                  if (!role) {
+                    var tag = el.tagName.toLowerCase();
+                    if (tag === 'a') role = 'link';
+                    else if (tag === 'button') role = 'button';
+                    else if (tag === 'input') {
+                      var t = (el.type || 'text').toLowerCase();
+                      if (t === 'checkbox') role = 'checkbox';
+                      else if (t === 'radio') role = 'radio';
+                      else if (t === 'submit' || t === 'button') role = 'button';
+                      else role = 'textbox';
+                    }
+                    else if (tag === 'select') role = 'combobox';
+                    else if (tag === 'textarea') role = 'textbox';
+                    else if (el.isContentEditable) role = 'textbox';
+                    else role = tag;
+                  }
+
+                  var name = '';
+                  var ariaLabel = el.getAttribute('aria-label');
+                  if (ariaLabel) {
+                    name = ariaLabel;
+                  } else if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+                    name = el.getAttribute('placeholder') || el.getAttribute('name') || '';
+                  } else if (el.isContentEditable) {
+                    name = 'compose body';
+                  } else {
+                    name = (el.textContent || '').trim().slice(0, 60);
+                  }
+
+                  var refId = startId + refs.length;
+                  el.setAttribute('data-assistme-ref', String(refId));
+
+                  refs.push({
+                    id: refId,
+                    role: role,
+                    name: name,
+                    tag: el.tagName.toLowerCase(),
+                    type: el.getAttribute('type') || '',
+                    box: {
+                      x: Math.round(rect.x),
+                      y: Math.round(rect.y),
+                      width: Math.round(rect.width),
+                      height: Math.round(rect.height)
+                    },
+                    inFrame: true
+                  });
+                }
+
+                return JSON.stringify(refs);
+              })()
+            `,
+            contextId,
+            returnByValue: true
+          });
+          const frameRefs = JSON.parse(
+            frameResult.result?.value || "[]"
+          );
+          for (const r of frameRefs) {
+            refs.push({
+              id: r.id,
+              role: r.role,
+              name: r.name,
+              tag: r.tag,
+              inputType: r.type || "",
+              box: {
+                x: Math.round(r.box.x + iframeOffset.x),
+                y: Math.round(r.box.y + iframeOffset.y),
+                width: r.box.width,
+                height: r.box.height
+              }
+            });
+            if (this.frameContexts.size < FRAME_CONTEXTS_MAX_SIZE) {
+              this.frameContexts.set(r.id, contextId);
+            }
+          }
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * Get execution context IDs for each frame in the page.
+   * Uses Runtime.executionContextCreated events collected during the session,
+   * or falls back to evaluating in known frames.
+   */
+  async getFrameContexts(_mainFrameId) {
+    const contexts = /* @__PURE__ */ new Map();
+    try {
+      await this.send("Runtime.enable").catch(() => {
+      });
+      const frameTree = await this.send("Page.getFrameTree");
+      const childFrames = frameTree.frameTree?.childFrames || [];
+      for (const child of childFrames) {
+        try {
+          const world = await this.send("Page.createIsolatedWorld", {
+            frameId: child.frame.id,
+            worldName: "assistme-snapshot",
+            grantUniveralAccess: true
+          });
+          if (world.executionContextId) {
+            contexts.set(child.frame.id, world.executionContextId);
+          }
+        } catch {
+        }
+      }
+    } catch {
+    }
+    return contexts;
+  }
+  // ── Ref Resolution ────────────────────────────────────────────────
+  /**
+   * Resolve a ref ID to its current center coordinates in the viewport.
+   * Uses two strategies:
+   *  1. Fast: find by data-assistme-ref attribute (set during snapshot)
+   *  2. Stable: search by role + accessible name (survives DOM changes)
+   *
+   * Includes actionability checks (like Playwright):
+   *  - Element must be visible (not display:none, not zero-size)
+   *  - Element must be in viewport (scrolls into view if needed)
+   *  - Element must not be covered by another element (checks elementFromPoint)
+   *
+   * Returns null if the element cannot be found or is not actionable.
+   * Returns { error: string } if found but not actionable (for diagnostics).
+   */
+  async resolveRef(refId) {
+    const cached = this.refCache.get(refId);
+    const role = cached?.role || "";
+    const name = cached?.name || "";
+    const roleJS = JSON.stringify(role);
+    const nameJS = JSON.stringify(name);
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          var refId = ${refId};
+          var role = ${roleJS};
+          var name = ${nameJS};
+
+          // Strategy 1: data attribute (fast, from last snapshot)
+          var el = document.querySelector('[data-assistme-ref="' + refId + '"]');
+
+          // Strategy 2: role + name search (stable, survives DOM changes)
+          if (!el && role && name) {
+            var selectorMap = {
+              textbox: 'input, textarea, [role="textbox"], [role="searchbox"]',
+              button: 'button, [role="button"], input[type="submit"], input[type="button"]',
+              link: 'a[href], [role="link"]',
+              combobox: 'select, [role="combobox"]',
+              checkbox: 'input[type="checkbox"], [role="checkbox"]',
+              radio: 'input[type="radio"], [role="radio"]',
+              tab: '[role="tab"]',
+              menuitem: '[role="menuitem"]',
+              option: '[role="option"], option',
+            };
+            var sel = selectorMap[role] || '*[role="' + role + '"]';
+            var candidates = document.querySelectorAll(sel);
+            for (var i = 0; i < candidates.length; i++) {
+              var c = candidates[i];
+              var cName = c.getAttribute('aria-label')
+                || c.getAttribute('placeholder')
+                || (c.textContent || '').trim().slice(0, 60);
+              if (cName === name) { el = c; break; }
+            }
+          }
+
+          if (!el) return 'null';
+
+          // \u2500\u2500 Actionability checks (Playwright-style) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+          // Check visibility
+          var style = window.getComputedStyle(el);
+          if (style.display === 'none')
+            return JSON.stringify({ error: 'Element is hidden (display:none)' });
+          if (style.visibility === 'hidden')
+            return JSON.stringify({ error: 'Element is hidden (visibility:hidden)' });
+          if (parseFloat(style.opacity) < 0.05)
+            return JSON.stringify({ error: 'Element is hidden (opacity:0)' });
+
+          // Check disabled
+          if (el.disabled || el.getAttribute('aria-disabled') === 'true')
+            return JSON.stringify({ error: 'Element is disabled' });
+
+          // Scroll into view
+          el.scrollIntoView({ block: 'center', behavior: 'instant' });
+          var r = el.getBoundingClientRect();
+
+          // Check non-zero size
+          if (r.width < 1 || r.height < 1)
+            return JSON.stringify({ error: 'Element has zero size (' + r.width + 'x' + r.height + ')' });
+
+          // Check element is in viewport
+          if (r.bottom < 0 || r.top > window.innerHeight || r.right < 0 || r.left > window.innerWidth)
+            return JSON.stringify({ error: 'Element is outside viewport after scroll' });
+
+          var cx = r.x + r.width / 2;
+          var cy = r.y + r.height / 2;
+
+          // Check not covered by another element (hit test)
+          var topEl = document.elementFromPoint(cx, cy);
+          if (topEl && topEl !== el && !el.contains(topEl) && !topEl.closest('[data-assistme-ref="' + refId + '"]')) {
+            // Check if the covering element is the overlay (ignore it)
+            if (!topEl.closest('#__assistme_refs__')) {
+              var coverTag = topEl.tagName.toLowerCase();
+              var coverText = (topEl.textContent || '').trim().slice(0, 30);
+              return JSON.stringify({
+                error: 'Element is covered by <' + coverTag + '>' + (coverText ? ' "' + coverText + '"' : ''),
+                x: cx, y: cy, width: r.width, height: r.height
+              });
+            }
+          }
+
+          return JSON.stringify({
+            x: cx,
+            y: cy,
+            width: r.width,
+            height: r.height
+          });
+        })()
+      `,
+      returnByValue: true
+    });
+    const value = result.result?.value;
+    if (value && value !== "null") {
+      try {
+        return JSON.parse(value);
+      } catch {
+      }
+    }
+    const frameContextId = this.frameContexts.get(refId);
+    if (frameContextId) {
+      return this.resolveRefInFrame(refId, frameContextId, role, name);
+    }
+    return null;
+  }
+  /**
+   * Resolve a ref inside a cross-origin iframe using its execution context.
+   * Returns coordinates adjusted by the iframe's viewport offset.
+   */
+  async resolveRefInFrame(refId, contextId, role, name) {
+    const roleJS = JSON.stringify(role);
+    const nameJS = JSON.stringify(name);
+    try {
+      const offsetResult = await this.send("Runtime.evaluate", {
+        expression: `
+          (function() {
+            var iframes = document.querySelectorAll('iframe');
+            for (var i = 0; i < iframes.length; i++) {
+              var r = iframes[i].getBoundingClientRect();
+              if (r.width > 10 && r.height > 10) {
+                return JSON.stringify({ x: r.x, y: r.y });
+              }
+            }
+            return JSON.stringify({ x: 0, y: 0 });
+          })()
+        `,
+        returnByValue: true
+      });
+      const offset = JSON.parse(
+        offsetResult.result?.value || '{"x":0,"y":0}'
+      );
+      const frameResult = await this.send("Runtime.evaluate", {
+        expression: `
+          (function() {
+            var el = document.querySelector('[data-assistme-ref="${refId}"]');
+            if (!el && ${roleJS} && ${nameJS}) {
+              // Fallback: search by role
+              var candidates = document.querySelectorAll('*');
+              for (var i = 0; i < candidates.length; i++) {
+                var c = candidates[i];
+                if (c.isContentEditable || c.getAttribute('contenteditable') === 'true') {
+                  el = c; break;
+                }
+              }
+            }
+            if (!el) return 'null';
+
+            el.scrollIntoView({ block: 'center', behavior: 'instant' });
+            var r = el.getBoundingClientRect();
+            if (r.width < 1 || r.height < 1) return JSON.stringify({ error: 'Zero size' });
+
+            return JSON.stringify({
+              x: r.x + r.width / 2,
+              y: r.y + r.height / 2,
+              width: r.width,
+              height: r.height
+            });
+          })()
+        `,
+        contextId,
+        returnByValue: true
+      });
+      const value = frameResult.result?.value;
+      if (!value || value === "null") return null;
+      const parsed = JSON.parse(value);
+      if (parsed.error) return parsed;
+      return {
+        x: parsed.x + offset.x,
+        y: parsed.y + offset.y,
+        width: parsed.width,
+        height: parsed.height
+      };
+    } catch {
+      return null;
+    }
+  }
+  // ── Ref-based Interactions (CDP Input Events) ─────────────────────
+  /**
+   * Click an element by ref using CDP Input.dispatchMouseEvent.
+   * This simulates a real mouse click through the browser's input pipeline,
+   * triggering hover states, focus management, and all native browser events
+   * — more reliable than el.click() for framework components.
+   *
+   * Includes auto-wait: retries up to 3 times (with 500ms intervals) if the
+   * element is not yet actionable (e.g., covered by a loading overlay, still
+   * animating into view). This matches Playwright's auto-waiting behavior.
+   */
+  async clickRef(refId) {
+    this.ensureConnected();
+    const ref = this.refCache.get(refId);
+    const refLabel = `[${refId}] ${ref?.role || ""} "${ref?.name || ""}"`;
+    const maxRetries = 3;
+    let lastError = "";
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const resolved = await this.resolveRef(refId);
+      if (!resolved) {
+        return {
+          success: false,
+          message: `Ref ${refLabel} not found. Take a new snapshot with browser_snapshot.`
+        };
+      }
+      if (resolved.error) {
+        lastError = resolved.error;
+        if (attempt < maxRetries - 1) {
+          await new Promise((r) => setTimeout(r, 500));
+          continue;
+        }
+        return { success: false, message: `Cannot click ${refLabel}: ${lastError}` };
+      }
+      if (attempt === 0) {
+        await new Promise((r) => setTimeout(r, 50));
+        const settled = await this.resolveRef(refId);
+        if (settled && !settled.error) {
+          resolved.x = settled.x;
+          resolved.y = settled.y;
+        }
+      }
+      await this.send("Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: resolved.x,
+        y: resolved.y
+      });
+      await this.send("Input.dispatchMouseEvent", {
+        type: "mousePressed",
+        x: resolved.x,
+        y: resolved.y,
+        button: "left",
+        clickCount: 1
+      });
+      await this.send("Input.dispatchMouseEvent", {
+        type: "mouseReleased",
+        x: resolved.x,
+        y: resolved.y,
+        button: "left",
+        clickCount: 1
+      });
+      await new Promise((r) => setTimeout(r, 300));
+      return { success: true, message: `Clicked ${refLabel}` };
+    }
+    return { success: false, message: `Cannot click ${refLabel}: ${lastError}` };
+  }
+  /**
+   * Type text into an element by ref using CDP Input events.
+   * Clicks to focus, selects all existing text (Ctrl/Cmd+A), then uses
+   * Input.insertText for reliable text insertion across all frameworks.
+   */
+  async typeRef(refId, text) {
+    this.ensureConnected();
+    const ref = this.refCache.get(refId);
+    const refLabel = `[${refId}] ${ref?.role || ""} "${ref?.name || ""}"`;
+    const clickResult = await this.clickRef(refId);
+    if (!clickResult.success) return clickResult;
+    await new Promise((r) => setTimeout(r, 100));
+    const selectAllKey = platform() === "darwin" ? "Meta+a" : "Control+a";
+    await this.pressKey(selectAllKey);
+    await new Promise((r) => setTimeout(r, 50));
+    await this.pressKey("Backspace");
+    await new Promise((r) => setTimeout(r, 50));
+    const frameContextId = this.frameContexts.get(refId);
+    const clearEvalOpts = {
+      expression: `
+        (function() {
+          var el = document.querySelector('[data-assistme-ref="${refId}"]');
+          if (!el) return 'no_element';
+
+          // For contenteditable elements, check textContent instead of value
+          if (el.isContentEditable || el.getAttribute('contenteditable') === 'true') {
+            if (el.textContent && el.textContent.trim() !== '') {
+              el.textContent = '';
+              el.dispatchEvent(new Event('input', { bubbles: true }));
+              return 'js_cleared';
+            }
+            return 'ok';
+          }
+
+          if (el.value !== undefined && el.value !== '') {
+            // Ctrl+A didn't work (some frameworks intercept it) \u2014 clear via JS
+            var setter = Object.getOwnPropertyDescriptor(
+              window.HTMLInputElement.prototype, 'value'
+            )?.set || Object.getOwnPropertyDescriptor(
+              window.HTMLTextAreaElement.prototype, 'value'
+            )?.set;
+            if (setter) setter.call(el, '');
+            else el.value = '';
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+            return 'js_cleared';
+          }
+          return 'ok';
+        })()
+      `,
+      returnByValue: true
+    };
+    if (frameContextId) {
+      clearEvalOpts.contextId = frameContextId;
+    }
+    const cleared = await this.send("Runtime.evaluate", clearEvalOpts);
+    const clearStatus = cleared.result?.value || "ok";
+    if (clearStatus === "no_element" && !frameContextId) {
+      return {
+        success: false,
+        message: `Ref ${refLabel} not found after click. Take a new snapshot.`
+      };
+    }
+    await this.send("Input.insertText", { text });
+    await new Promise((r) => setTimeout(r, 100));
+    return { success: true, message: `Typed "${text}" into ${refLabel}` };
+  }
+  /**
+   * Select a dropdown option by ref. Delegates to selectOption with the
+   * ref's data attribute as selector, handling both native <select> and
+   * custom dropdown components.
+   */
+  async selectRef(refId, option) {
+    this.ensureConnected();
+    const cached = this.refCache.get(refId);
+    if (!cached) {
+      return {
+        success: false,
+        message: `Ref [${refId}] not found. Take a new snapshot with browser_snapshot.`
+      };
+    }
+    const refLabel = `[${refId}] ${cached.role} "${cached.name}"`;
+    const result = await this.selectOption(`[data-assistme-ref="${refId}"]`, option);
+    const message = result.replace(/\[data-assistme-ref="\d+"\]/, refLabel);
+    const success = !result.includes("not found");
+    return { success, message };
+  }
+  // ── Action Pipeline ───────────────────────────────────────────────
+  /**
+   * Execute a batch of actions sequentially using refs.
+   * Reduces round-trips: instead of one tool call per action, the model
+   * can specify a sequence of actions that execute atomically.
+   *
+   * Optionally takes a screenshot after all actions complete.
+   */
+  async act(actions, takeScreenshot = false) {
+    this.ensureConnected();
+    const results = [];
+    for (const spec of actions) {
+      let result;
+      let success = true;
+      try {
+        switch (spec.action) {
+          case "click": {
+            const r = await this.clickRef(spec.ref);
+            result = r.message;
+            success = r.success;
+            break;
+          }
+          case "type": {
+            const r = await this.typeRef(spec.ref, spec.text);
+            result = r.message;
+            success = r.success;
+            break;
+          }
+          case "select": {
+            const r = await this.selectRef(spec.ref, spec.option);
+            result = r.message;
+            success = r.success;
+            break;
+          }
+          case "press":
+            result = await this.pressKey(spec.key);
+            break;
+          case "scroll":
+            result = spec.direction === "up" ? await this.scrollUp() : await this.scrollDown();
+            break;
+          case "wait":
+            await new Promise((r) => setTimeout(r, Math.min(spec.ms, 5e3)));
+            result = `Waited ${spec.ms}ms`;
+            break;
+          default:
+            result = `Unknown action: ${spec.action}`;
+            success = false;
+        }
+      } catch (err) {
+        result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+        success = false;
+      }
+      results.push({
+        action: spec.action,
+        ref: "ref" in spec ? spec.ref : void 0,
+        result,
+        success
+      });
+      if (!success) break;
+      if (spec.action !== "wait") {
+        await new Promise((r) => setTimeout(r, 200));
+      }
+    }
+    let screenshot;
+    if (takeScreenshot) {
+      await new Promise((r) => setTimeout(r, 300));
+      screenshot = await this.screenshot();
+    }
+    return { results, screenshot };
+  }
+  // ── Dropdown/Select ─────────────────────────────────────────────
+  /**
+   * Select an option from a dropdown — handles both native <select> elements
+   * and custom Material Design / React / Angular dropdown components.
+   *
+   * Strategy:
+   * 1. Try native <select> first (by selector or label text)
+   * 2. Fall back to custom dropdown: click to open, then click the option by text
+   */
+  async selectOption(selector, optionText) {
+    this.ensureConnected();
+    const selectorJS = JSON.stringify(selector);
+    const optionJS = JSON.stringify(optionText);
+    const result = await this.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          var sel = ${selectorJS};
+          var optText = ${optionJS};
+
+          // Strategy 1: Native <select> element
+          var selectEl = document.querySelector(sel);
+          if (selectEl && selectEl.tagName === 'SELECT') {
+            var options = selectEl.querySelectorAll('option');
+            for (var i = 0; i < options.length; i++) {
+              if (options[i].textContent.trim() === optText) {
+                selectEl.value = options[i].value;
+                selectEl.dispatchEvent(new Event('change', { bubbles: true }));
+                selectEl.dispatchEvent(new Event('input', { bubbles: true }));
+                return 'Selected "' + optText + '" in native select';
+              }
+            }
+            return 'Option "' + optText + '" not found in select. Available: ' +
+              Array.from(options).map(function(o) { return o.textContent.trim(); }).join(', ');
+          }
+
+          // Strategy 2: Custom dropdown \u2014 find the trigger element
+          var trigger = selectEl;
+          if (!trigger) {
+            // Try finding by aria-label first (fast, indexed)
+            trigger = document.querySelector('[aria-label="' + sel.replace(/"/g, '\\"') + '"]');
+          }
+          if (!trigger) {
+            // Try finding by label/placeholder text in likely dropdown elements
+            var dropdownCandidates = document.querySelectorAll(
+              'button, [role="combobox"], [role="listbox"], [role="button"], ' +
+              'select, input, .MuiSelect-root, .MuiInput-root, ' +
+              '[class*="select"], [class*="dropdown"], [class*="picker"]'
+            );
+            for (var j = 0; j < dropdownCandidates.length; j++) {
+              var el = dropdownCandidates[j];
+              var ownText = Array.from(el.childNodes)
+                .filter(function(n) { return n.nodeType === 3; })
+                .map(function(n) { return n.textContent.trim(); })
+                .join('');
+              if (ownText === sel || el.getAttribute('aria-label') === sel ||
+                  el.getAttribute('placeholder') === sel) {
+                trigger = el;
+                break;
+              }
+            }
+          }
+
+          if (!trigger) return 'Dropdown not found: ' + sel;
+
+          // Click to open the dropdown
+          trigger.scrollIntoView({ block: 'center', behavior: 'instant' });
+          trigger.click();
+
+          // Wait a frame for the dropdown menu to render, then select the option
+          return new Promise(function(resolve) {
+            setTimeout(function() {
+              // Look for the option in listbox/menu/dropdown overlays
+              var optionContainers = document.querySelectorAll(
+                '[role="listbox"], [role="menu"], [role="presentation"], .MuiMenu-list, .MuiList-root, ul.mdc-list, .VfPpkd-xl07Ob'
+              );
+
+              // Also check all visible elements as fallback
+              var searchIn = optionContainers.length > 0
+                ? Array.from(optionContainers).flatMap(function(c) { return Array.from(c.querySelectorAll('*')); })
+                : Array.from(document.querySelectorAll('li, [role="option"], [role="menuitem"], div[data-value]'));
+
+              for (var k = 0; k < searchIn.length; k++) {
+                var opt = searchIn[k];
+                var txt = opt.textContent ? opt.textContent.trim() : '';
+                if (txt === optText) {
+                  opt.scrollIntoView({ block: 'center', behavior: 'instant' });
+                  opt.click();
+                  resolve('Selected "' + optText + '" from custom dropdown');
+                  return;
+                }
+              }
+
+              // Broader search: visible leaf elements in interactive containers
+              var broadCandidates = document.querySelectorAll(
+                'li, span, div, a, button, label, [role="option"], [role="menuitem"], ' +
+                '[role="menuitemradio"], [role="menuitemcheckbox"], [data-value]'
+              );
+              for (var m = 0; m < broadCandidates.length; m++) {
+                var candidate = broadCandidates[m];
+                if (candidate.textContent && candidate.textContent.trim() === optText &&
+                    candidate.offsetParent !== null && candidate.children.length === 0) {
+                  candidate.click();
+                  resolve('Selected "' + optText + '" (broad match)');
+                  return;
+                }
+              }
+
+              resolve('Option "' + optText + '" not found in dropdown');
+            }, 300);
+          });
+        })()
+      `,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    await new Promise((r) => setTimeout(r, 500));
+    return result.result?.value || "Selection attempted.";
+  }
+  // ── JavaScript Evaluation ───────────────────────────────────────
+  async evaluate(expression) {
+    this.ensureConnected();
+    const result = await this.send("Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    const evalResult = result.result;
+    const value = evalResult?.value;
+    if (value === void 0) {
+      const desc = evalResult?.description;
+      return desc || "(undefined)";
+    }
+    return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  }
+  // ── Tab Management ──────────────────────────────────────────────
+  async listTabs() {
+    const tabs = await this.getTabs();
+    const pageTabs = tabs.filter((t) => t.type === "page");
+    if (pageTabs.length === 0) return "No tabs open.";
+    return pageTabs.map(
+      (t, i) => `[${i}] ${t.title.slice(0, 60)}${this.currentTabId === t.id ? " (active)" : ""}
+    ${t.url}`
+    ).join("\n\n");
+  }
+  async switchTab(index) {
+    const tabs = await this.getTabs();
+    const pageTabs = tabs.filter((t) => t.type === "page");
+    if (index < 0 || index >= pageTabs.length) {
+      return `Invalid tab index. Available: 0-${pageTabs.length - 1}`;
+    }
+    await this.disconnect();
+    return this.connect(index);
+  }
+  async openNewTab(url) {
+    const targetUrl = url || "about:blank";
+    const res = await fetch(
+      `http://127.0.0.1:${this.debugPort}/json/new?${encodeURIComponent(targetUrl)}`,
+      { signal: AbortSignal.timeout(5e3) }
+    );
+    const tab = await res.json();
+    await this.disconnect();
+    const tabs = await this.getTabs();
+    const idx = tabs.filter((t) => t.type === "page").findIndex((t) => t.id === tab.id);
+    if (idx >= 0) {
+      await this.connect(idx);
+    }
+    return `Opened new tab: ${targetUrl}`;
+  }
+  // ── Helpers ─────────────────────────────────────────────────────
+  async waitForLoad(timeoutMs = 8e3) {
+    const start = Date.now();
+    let sawInteractive = false;
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const result = await this.send("Runtime.evaluate", {
+          expression: "document.readyState",
+          returnByValue: true
+        });
+        const state = result.result?.value;
+        if (state === "complete") {
+          await new Promise((r) => setTimeout(r, 300));
+          return;
+        }
+        if (state === "interactive") {
+          if (!sawInteractive) {
+            sawInteractive = true;
+          }
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    if (sawInteractive) {
+      await new Promise((r) => setTimeout(r, 300));
+    }
+  }
+  isConnected() {
+    return this.connected && this.ws?.readyState === WebSocket.OPEN;
+  }
+  // ── Login Detection ────────────────────────────────────────────
+  /**
+   * Detect if the current page appears to be a login/authentication page.
+   * Checks URL patterns, password input fields, and login form actions.
+   */
+  async detectLoginPage() {
+    try {
+      const result = await this.send("Runtime.evaluate", {
+        expression: `
+          (function() {
+            var url = window.location.href.toLowerCase();
+
+            // Exclude signup/registration pages \u2014 these are NOT login pages
+            var signupPatterns = [
+              '/signup', '/sign-up', '/sign_up', '/register',
+              '/registration', '/create-account', '/create_account',
+              '/join', '/enroll',
+              'accounts.google.com/lifecycle/steps/signup',
+              'signup.live.com',
+            ];
+            for (var s = 0; s < signupPatterns.length; s++) {
+              if (url.indexOf(signupPatterns[s]) !== -1) {
+                return JSON.stringify({ isLoginPage: false, reason: '' });
+              }
+            }
+
+            // URL-based detection
+            var loginPatterns = [
+              '/login', '/signin', '/sign-in', '/sign_in',
+              '/auth/', '/sso/', '/oauth/', '/session/new',
+              '/accounts/login', '/users/sign_in',
+              'accounts.google.com/v3/signin',
+              'accounts.google.com/servicelogin',
+              'login.microsoftonline.com',
+              'github.com/login', 'github.com/session',
+              'login.live.com', 'appleid.apple.com'
+            ];
+            for (var i = 0; i < loginPatterns.length; i++) {
+              if (url.indexOf(loginPatterns[i]) !== -1) {
+                return JSON.stringify({
+                  isLoginPage: true,
+                  reason: 'URL contains login pattern: ' + loginPatterns[i]
+                });
+              }
+            }
+
+            // Password input detection (visible only)
+            var passwordInputs = document.querySelectorAll('input[type="password"]');
+            for (var j = 0; j < passwordInputs.length; j++) {
+              var input = passwordInputs[j];
+              var rect = input.getBoundingClientRect();
+              var style = window.getComputedStyle(input);
+              if (rect.width > 0 && rect.height > 0 &&
+                  style.display !== 'none' && style.visibility !== 'hidden') {
+                return JSON.stringify({
+                  isLoginPage: true,
+                  reason: 'Page contains visible password input field'
+                });
+              }
+            }
+
+            // Login form action detection
+            var formSelectors = [
+              'form[action*="login"]', 'form[action*="signin"]',
+              'form[action*="session"]', 'form[action*="auth"]',
+              'form[action*="authenticate"]'
+            ];
+            var loginForms = document.querySelectorAll(formSelectors.join(','));
+            if (loginForms.length > 0) {
+              return JSON.stringify({
+                isLoginPage: true,
+                reason: 'Page contains login form'
+              });
+            }
+
+            return JSON.stringify({ isLoginPage: false, reason: '' });
+          })()
+        `,
+        returnByValue: true
+      });
+      const value = result.result?.value;
+      return JSON.parse(value || '{"isLoginPage":false,"reason":""}');
+    } catch {
+      return { isLoginPage: false, reason: "" };
+    }
+  }
+};
+
+// src/browser/chrome-launcher.ts
+function findChromePath() {
+  const os = platform2();
+  if (os === "darwin") {
+    const paths = [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+    ];
+    return paths.find((p) => existsSync(p)) ?? null;
+  }
+  if (os === "linux") {
+    const names = [
+      "google-chrome",
+      "google-chrome-stable",
+      "chromium-browser",
+      "chromium",
+      "microsoft-edge",
+      "microsoft-edge-stable",
+      "brave-browser"
+    ];
+    for (const name of names) {
+      try {
+        return execSync(`which ${name}`, {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        }).trim();
+      } catch {
+      }
+    }
+    return null;
+  }
+  if (os === "win32") {
+    const prefixes = [
+      process.env.PROGRAMFILES,
+      process.env["PROGRAMFILES(X86)"],
+      process.env.LOCALAPPDATA
+    ].filter(Boolean);
+    const subPaths = [
+      "Google\\Chrome\\Application\\chrome.exe",
+      "Microsoft\\Edge\\Application\\msedge.exe",
+      "BraveSoftware\\Brave-Browser\\Application\\brave.exe"
+    ];
+    for (const prefix of prefixes) {
+      for (const sub of subPaths) {
+        const p = `${prefix}\\${sub}`;
+        if (existsSync(p)) return p;
+      }
+    }
+    return null;
+  }
+  return null;
+}
+function getDefaultProfileDir(chromePath) {
+  const home = homedir();
+  const os = platform2();
+  if (os === "darwin") {
+    if (chromePath.includes("Brave Browser"))
+      return join(home, "Library", "Application Support", "BraveSoftware", "Brave-Browser");
+    if (chromePath.includes("Microsoft Edge"))
+      return join(home, "Library", "Application Support", "Microsoft Edge");
+    if (chromePath.includes("Chromium"))
+      return join(home, "Library", "Application Support", "Chromium");
+    if (chromePath.includes("Canary"))
+      return join(home, "Library", "Application Support", "Google", "Chrome Canary");
+    return join(home, "Library", "Application Support", "Google", "Chrome");
+  }
+  if (os === "win32") {
+    const appData = process.env.LOCALAPPDATA || join(home, "AppData", "Local");
+    if (chromePath.includes("brave"))
+      return join(appData, "BraveSoftware", "Brave-Browser", "User Data");
+    if (chromePath.includes("msedge")) return join(appData, "Microsoft", "Edge", "User Data");
+    return join(appData, "Google", "Chrome", "User Data");
+  }
+  if (chromePath.includes("brave")) return join(home, ".config", "BraveSoftware", "Brave-Browser");
+  if (chromePath.includes("microsoft-edge")) return join(home, ".config", "microsoft-edge");
+  if (chromePath.includes("chromium")) return join(home, ".config", "chromium");
+  return join(home, ".config", "google-chrome");
+}
+function getDebugProfileDir(chromePath) {
+  const home = homedir();
+  const debugDir = join(home, ".assistme", "browser-profile");
+  if (!existsSync(debugDir)) {
+    mkdirSync(debugDir, { recursive: true });
+    log.debug(`Created debug profile directory: ${debugDir}`);
+    const realDir = getDefaultProfileDir(chromePath);
+    if (existsSync(realDir)) {
+      seedDebugProfile(realDir, debugDir);
+    }
+  }
+  return debugDir;
+}
+function seedDebugProfile(realDir, debugDir) {
+  const rootFiles = ["Local State"];
+  const profileFiles = ["Bookmarks", "Preferences", "Favicons", "Top Sites", "Shortcuts"];
+  for (const file of rootFiles) {
+    const src = join(realDir, file);
+    const dest = join(debugDir, file);
+    try {
+      if (existsSync(src)) {
+        cpSync(src, dest, { force: true });
+        log.debug(`Seeded: ${file}`);
+      }
+    } catch {
+    }
+  }
+  const srcProfile = join(realDir, "Default");
+  const destProfile = join(debugDir, "Default");
+  if (existsSync(srcProfile)) {
+    mkdirSync(destProfile, { recursive: true });
+    for (const file of profileFiles) {
+      const src = join(srcProfile, file);
+      const dest = join(destProfile, file);
+      try {
+        if (existsSync(src)) {
+          cpSync(src, dest, { force: true });
+          log.debug(`Seeded: Default/${file}`);
+        }
+      } catch {
+      }
+    }
+    const srcExt = join(srcProfile, "Extensions");
+    const destExt = join(destProfile, "Extensions");
+    try {
+      if (existsSync(srcExt)) {
+        cpSync(srcExt, destExt, { recursive: true, force: true });
+        log.debug("Seeded: Default/Extensions");
+      }
+    } catch {
+    }
+  }
+}
+function spawnChrome(chromePath, port) {
+  const profileDir = getDebugProfileDir(chromePath);
+  const flags = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${profileDir}`,
+    "--restore-last-session"
+  ];
+  log.debug(`Spawning browser: ${chromePath} ${flags.join(" ")}`);
+  const child = spawn(chromePath, flags, {
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stderr = "";
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+  child.on("error", (err) => {
+    log.error(`Chrome spawn error: ${err.message}`);
+  });
+  child.on("exit", (code, signal) => {
+    if (code !== null && code !== 0) {
+      log.debug(`Chrome exited with code ${code}${signal ? ` (signal: ${signal})` : ""}`);
+      if (stderr) {
+        const lines = stderr.split("\n").filter(Boolean).slice(0, 5);
+        for (const line of lines) {
+          log.debug(`  chrome stderr: ${line}`);
+        }
+      }
+    }
+  });
+  child.unref();
+  return child;
+}
+async function waitForCDP(browser, timeoutMs = 3e4) {
+  const start = Date.now();
+  let attempts = 0;
+  while (Date.now() - start < timeoutMs) {
+    attempts++;
+    if (await browser.isAvailable()) {
+      log.debug(`CDP became reachable after ${attempts} attempts (${Date.now() - start}ms)`);
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  log.debug(`CDP not reachable after ${attempts} attempts (${timeoutMs}ms timeout)`);
+  return false;
+}
+async function isPortInUse(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: AbortSignal.timeout(1e3)
+    });
+    const body = await res.text();
+    return !body.includes("webSocketDebuggerUrl");
+  } catch {
+    return false;
+  }
+}
+async function ensureBrowserAvailable(port = 9222) {
+  const browser = getBrowser(port);
+  if (await browser.isAvailable()) {
+    log.debug("CDP already reachable \u2014 no launch needed");
+    return { success: true, action: "already_available" };
+  }
+  if (await isPortInUse(port)) {
+    log.debug(`Port ${port} is in use by a non-Chrome process`);
+    return {
+      success: false,
+      action: "port_conflict",
+      detail: `Port ${port} is already in use by another process. Try a different port or stop the conflicting process.`
+    };
+  }
+  const chromePath = findChromePath();
+  if (!chromePath) {
+    log.debug("Chrome binary not found on this system");
+    return { success: false, action: "chrome_not_found" };
+  }
+  log.debug(`Found Chrome at: ${chromePath}`);
+  spawnChrome(chromePath, port);
+  if (await waitForCDP(browser)) {
+    return { success: true, action: "launched", chromePath };
+  }
+  const debugDir = getDebugProfileDir(chromePath);
+  const lockPath = join(debugDir, "SingletonLock");
+  if (existsSync(lockPath)) {
+    log.debug("Found stale SingletonLock in debug profile \u2014 removing and retrying");
+    try {
+      unlinkSync(lockPath);
+      for (const f of ["SingletonSocket", "SingletonCookie"]) {
+        try {
+          unlinkSync(join(debugDir, f));
+        } catch {
+        }
+      }
+    } catch {
+    }
+    spawnChrome(chromePath, port);
+    if (await waitForCDP(browser, 15e3)) {
+      return { success: true, action: "launched", chromePath };
+    }
+  }
+  return {
+    success: false,
+    action: "launch_failed",
+    chromePath,
+    detail: "Could not start browser with remote debugging. Possible causes:\n  1) Another assistme debug browser is already using port " + port + "\n  2) The browser crashed on startup\nTry: rm -rf ~/.assistme/browser-profile && assistme"
+  };
+}
+var browserInstances = /* @__PURE__ */ new Map();
+function getBrowser(port = 9222) {
+  let instance = browserInstances.get(port);
+  if (!instance) {
+    instance = new BrowserController(port);
+    browserInstances.set(port, instance);
+  }
+  return instance;
+}
+
+// src/agent/scheduler.ts
+import { Cron } from "croner";
+function getNextRunTime(cronExpr, timezone, fromDate) {
+  const now = fromDate || /* @__PURE__ */ new Date();
+  try {
+    const job = new Cron(cronExpr, { timezone: timezone || "UTC" });
+    const next = job.nextRun(now);
+    if (!next) {
+      throw new Error(`No future run time found for cron expression: ${cronExpr}`);
+    }
+    return next;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("No future run time")) {
+      throw err;
+    }
+    throw new Error(`Invalid cron expression "${cronExpr}": ${errorMessage(err)}`);
+  }
+}
+var Scheduler = class {
+  timer = null;
+  running = false;
+  onScheduledTask = null;
+  async start(onScheduledTask) {
+    this.onScheduledTask = onScheduledTask;
+    this.running = true;
+    await this.initializeNextRuns();
+    this.timer = setInterval(() => this.checkDueTasks(), SCHEDULER_INTERVAL_MS);
+    log.info("Scheduler started (checking every 30s)");
+  }
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  async initializeNextRuns() {
+    try {
+      const data = await callMcpHandler("schedule.get_uninitialized");
+      if (data) {
+        for (const task of data) {
+          const nextRun = getNextRunTime(task.cron_expression, task.timezone);
+          await callMcpHandler("schedule.update", {
+            task_id: task.id,
+            next_run_at: nextRun.toISOString()
+          });
+        }
+      }
+    } catch (err) {
+      log.debug(`Scheduler init: ${errorMessage(err)}`);
+    }
+  }
+  async checkDueTasks() {
+    if (!this.running || !this.onScheduledTask) return;
+    try {
+      const dueTasks = await callMcpHandler("schedule.check_due");
+      if (!dueTasks || dueTasks.length === 0) return;
+      const task = dueTasks[0];
+      log.info(`Scheduled task due: "${task.name}"`);
+      const nextRun = getNextRunTime(task.cron_expression, task.timezone);
+      await callMcpHandler("schedule.update", {
+        task_id: task.id,
+        last_run_at: (/* @__PURE__ */ new Date()).toISOString(),
+        next_run_at: nextRun.toISOString(),
+        run_count: task.run_count + 1
+      });
+      try {
+        await this.onScheduledTask(task);
+        await callMcpHandler("schedule.update", {
+          task_id: task.id,
+          last_error: null
+        });
+      } catch (err) {
+        const errMsg = errorMessage(err);
+        await callMcpHandler("schedule.update", {
+          task_id: task.id,
+          last_error: errMsg
+        });
+        log.error(`Scheduled task "${task.name}" failed: ${errMsg}`);
+      }
+    } catch (err) {
+      log.debug(`Scheduler check error: ${errorMessage(err)}`);
+    }
+  }
+};
+async function createScheduledTask(name, prompt, cronExpression, timezone = "UTC") {
+  const nextRun = getNextRunTime(cronExpression, timezone);
+  return callMcpHandler("schedule.create", {
+    name,
+    prompt,
+    cron_expression: cronExpression,
+    timezone,
+    next_run_at: nextRun.toISOString()
+  });
+}
+async function listScheduledTasks() {
+  return callMcpHandler("schedule.list");
+}
+async function toggleScheduledTask(taskId, enabled) {
+  const params = { task_id: taskId, enabled };
+  if (enabled) {
+    const taskData = await callMcpHandler(
+      "schedule.get_task",
+      { task_id: taskId }
+    );
+    if (taskData) {
+      const nextRun = getNextRunTime(taskData.cron_expression, taskData.timezone);
+      params.next_run_at = nextRun.toISOString();
+    }
+  }
+  await callMcpHandler("schedule.toggle", params);
+}
+async function deleteScheduledTask(taskId) {
+  await callMcpHandler("schedule.delete", { task_id: taskId });
+}
+
+// src/agent/memory.ts
+var MemoryManager = class {
+  /**
+   * Store a new memory. Called by the agent after completing tasks
+   * to remember important facts about the user.
+   */
+  async remember(content, category = "general", options) {
+    const expiresAt = options?.expiresInDays ? new Date(Date.now() + options.expiresInDays * 864e5).toISOString() : null;
+    const data = await callMcpHandler("memory.store", {
+      category,
+      content,
+      importance: options?.importance ?? 5,
+      tags: options?.tags ?? [],
+      source_message_id: options?.sourceMessageId ?? null,
+      expires_at: expiresAt
+    });
+    log.debug(`Memory stored: [${category}] ${content.slice(0, 80)}...`);
+    return data;
+  }
+  /**
+   * Search memories by query text. Uses ILIKE + tag containment.
+   */
+  async search(query, limit = 10) {
+    try {
+      return await callMcpHandler("memory.search", {
+        query,
+        limit
+      });
+    } catch (err) {
+      log.warn(`Memory search failed: ${err instanceof Error ? err.message : err}`);
+      return [];
+    }
+  }
+  /**
+   * Get the most important/recent memories to include in context.
+   * Called before each task to build the agent's "working memory".
+   * Automatically filters out expired memories.
+   */
+  async getContext(maxItems = 20) {
+    const all = await callMcpHandler("memory.get_context", {
+      max_items: maxItems
+    });
+    const seen = /* @__PURE__ */ new Set();
+    return (all || []).filter((m) => {
+      if (seen.has(m.id)) return false;
+      seen.add(m.id);
+      return true;
+    });
+  }
+  /**
+   * Format memories into a string for the system prompt.
+   */
+  async buildMemoryPrompt() {
+    const memories = await this.getContext();
+    if (memories.length === 0) return "";
+    const sections = {};
+    for (const m of memories) {
+      const key = m.category;
+      if (!sections[key]) sections[key] = [];
+      sections[key].push(`- ${m.content}`);
+    }
+    const categoryLabels = {
+      instruction: "Standing Instructions",
+      preference: "User Preferences",
+      general: "Known Facts",
+      context: "Context",
+      skill_learned: "Learned Skills",
+      fact: "Facts"
+    };
+    let prompt = "\n\n## What You Know About The User\n";
+    for (const [cat, items] of Object.entries(sections)) {
+      prompt += `
+### ${categoryLabels[cat] || cat}
+`;
+      prompt += items.join("\n") + "\n";
+    }
+    return prompt;
+  }
+  // ── CRUD for CLI ────────────────────────────────────────────
+  async list(category, limit = 20) {
+    const data = await callMcpHandler("memory.list", {
+      category: category || null,
+      limit
+    });
+    return data || [];
+  }
+  async add(content, category = "general", importance = 5, tags = []) {
+    return this.remember(content, category, { importance, tags });
+  }
+  async remove(memoryId) {
+    await callMcpHandler("memory.remove", { memory_id: memoryId });
+  }
+  async clear(category) {
+    const result = await callMcpHandler("memory.clear", {
+      category: category || null
+    });
+    return result.count;
+  }
+  // ── Compression & Deduplication ──────────────────────────────────
+  /**
+   * Check if memory count exceeds threshold and compress if needed.
+   * Called automatically after task completion.
+   */
+  async compressIfNeeded() {
+    try {
+      const all = await this.list(void 0, 200);
+      if (all.length < MEMORY_COMPRESSION_THRESHOLD) {
+        return 0;
+      }
+      log.info(`Memory compression triggered: ${all.length} memories (threshold: ${MEMORY_COMPRESSION_THRESHOLD})`);
+      let removed = 0;
+      const now = Date.now();
+      for (const m of all) {
+        if (m.expires_at && new Date(m.expires_at).getTime() < now) {
+          await this.remove(m.id);
+          removed++;
+        }
+      }
+      const remaining = all.filter(
+        (m) => !m.expires_at || new Date(m.expires_at).getTime() >= now
+      );
+      const duplicateIds = this.findDuplicates(remaining);
+      for (const id of duplicateIds) {
+        await this.remove(id);
+        removed++;
+      }
+      const afterDedup = remaining.filter((m) => !duplicateIds.has(m.id));
+      if (afterDedup.length > MEMORY_COMPRESSION_TARGET) {
+        const toRemove = afterDedup.sort((a, b) => {
+          if (a.importance !== b.importance) return a.importance - b.importance;
+          if (a.access_count !== b.access_count) return a.access_count - b.access_count;
+          return new Date(a.created_at).getTime() - new Date(b.created_at).getTime();
+        }).slice(0, afterDedup.length - MEMORY_COMPRESSION_TARGET);
+        for (const m of toRemove) {
+          if (m.category === "instruction" && m.importance >= 8) continue;
+          await this.remove(m.id);
+          removed++;
+        }
+      }
+      if (removed > 0) {
+        log.info(`Memory compression complete: removed ${removed} memories`);
+      }
+      return removed;
+    } catch (err) {
+      log.warn(`Memory compression error: ${err instanceof Error ? err.message : err}`);
+      return 0;
+    }
+  }
+  /**
+   * Find duplicate memories based on content similarity.
+   * Returns the IDs of memories that should be removed (keeps the higher-importance duplicate).
+   */
+  findDuplicates(memories) {
+    const toRemove = /* @__PURE__ */ new Set();
+    for (let i = 0; i < memories.length; i++) {
+      if (toRemove.has(memories[i].id)) continue;
+      for (let j = i + 1; j < memories.length; j++) {
+        if (toRemove.has(memories[j].id)) continue;
+        if (memories[i].category !== memories[j].category) continue;
+        const similarity = computeWordOverlap(memories[i].content, memories[j].content);
+        if (similarity >= MEMORY_DEDUP_SIMILARITY_THRESHOLD) {
+          if (memories[i].importance > memories[j].importance || memories[i].importance === memories[j].importance && new Date(memories[i].created_at) > new Date(memories[j].created_at)) {
+            toRemove.add(memories[j].id);
+          } else {
+            toRemove.add(memories[i].id);
+          }
+        }
+      }
+    }
+    return toRemove;
+  }
+};
+function computeWordOverlap(a, b) {
+  const wordsA = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+  const wordsB = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+  if (wordsA.size === 0 && wordsB.size === 0) return 1;
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+  let intersection = 0;
+  for (const w of wordsA) {
+    if (wordsB.has(w)) intersection++;
+  }
+  const union = wordsA.size + wordsB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// src/agent/skills.ts
+import { execSync as execSync2 } from "child_process";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "need",
+  "dare",
+  "ought",
+  "used",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "between",
+  "out",
+  "off",
+  "over",
+  "under",
+  "again",
+  "further",
+  "then",
+  "once",
+  "here",
+  "there",
+  "when",
+  "where",
+  "why",
+  "how",
+  "all",
+  "each",
+  "every",
+  "both",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "no",
+  "nor",
+  "not",
+  "only",
+  "own",
+  "same",
+  "so",
+  "than",
+  "too",
+  "very",
+  "and",
+  "but",
+  "or",
+  "if",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "i",
+  "me",
+  "my",
+  "we",
+  "our",
+  "you",
+  "your",
+  "he",
+  "him",
+  "she",
+  "her",
+  "they",
+  "them",
+  "what",
+  "which",
+  "who",
+  "whom"
+]);
+function tokenize(text) {
+  const englishTokens = text.split(/[\s\-_/.,;:!?()[\]{}'"]+/).filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+  const chineseChars = text.replace(/[^\u4e00-\u9fff]/g, "");
+  const chineseBigrams = [];
+  for (let i = 0; i < chineseChars.length - 1; i++) {
+    chineseBigrams.push(chineseChars.slice(i, i + 2));
+  }
+  return [...englishTokens, ...chineseBigrams];
+}
+function bigrams(tokens) {
+  const result = /* @__PURE__ */ new Set();
+  for (let i = 0; i < tokens.length - 1; i++) {
+    result.add(`${tokens[i]} ${tokens[i + 1]}`);
+  }
+  return result;
+}
+function parseDbMetadata(raw) {
+  if (!raw || typeof raw !== "object") return {};
+  const obj = raw;
+  const openclaw = obj.openclaw || obj;
+  return {
+    emoji: openclaw.emoji,
+    requires: openclaw.requires,
+    primaryEnv: openclaw.primaryEnv,
+    os: openclaw.os,
+    always: openclaw.always,
+    skillKey: openclaw.skillKey,
+    credentials: openclaw.credentials
+  };
+}
+var SkillManager = class {
+  skills = /* @__PURE__ */ new Map();
+  idfCache = /* @__PURE__ */ new Map();
+  userId = null;
+  /** Cache for findRelevant() — keyed by prompt, invalidated on skill changes */
+  relevanceCache = /* @__PURE__ */ new Map();
+  DESCRIPTION_BUDGET_CHARS = SKILL_DESCRIPTION_BUDGET_CHARS;
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  async loadFromDb() {
+    if (!this.userId) return;
+    try {
+      const data = await callMcpHandler("skill.load");
+      this.skills.clear();
+      for (const raw of data || []) {
+        const row = safeParse(SkillRowSchema, raw);
+        if (!row) continue;
+        const skill = this.rowToSkill(row);
+        this.skills.set(skill.name, skill);
+      }
+      this.buildIdfCache();
+      if (this.skills.size > 0) {
+        log.info(`Loaded ${this.skills.size} skill(s) from DB`);
+      }
+    } catch (err) {
+      log.debug(`DB skill load error: ${err}`);
+    }
+  }
+  rowToSkill(row) {
+    return {
+      name: String(row.name),
+      description: String(row.description ?? ""),
+      version: String(row.version ?? "1.0.0"),
+      userInvocable: row.user_invocable !== false,
+      disableModelInvocation: row.disable_model_invocation === true,
+      keywords: Array.isArray(row.keywords) ? row.keywords : [],
+      allowedTools: Array.isArray(row.allowed_tools) ? row.allowed_tools : [],
+      argumentHint: String(row.argument_hint ?? ""),
+      metadata: parseDbMetadata(row.metadata),
+      homepage: String(row.homepage ?? ""),
+      content: String(row.content ?? ""),
+      filePath: "",
+      source: row.source || "manual",
+      dbId: row.id != null ? String(row.id) : void 0,
+      sourceSkillId: row.source_skill_id != null ? String(row.source_skill_id) : void 0,
+      invocationCount: typeof row.invocation_count === "number" ? row.invocation_count : 0
+    };
+  }
+  /** Invalidate caches when skills change (create, add, update, remove). */
+  invalidateCaches() {
+    this.relevanceCache.clear();
+    this.buildIdfCache();
+  }
+  buildIdfCache() {
+    this.idfCache.clear();
+    const docFreq = /* @__PURE__ */ new Map();
+    const totalSkills = this.skills.size || 1;
+    for (const skill of this.skills.values()) {
+      const allText = `${skill.name} ${skill.description} ${skill.content} ${skill.keywords.join(" ")}`.toLowerCase();
+      const words = new Set(tokenize(allText));
+      for (const w of words) {
+        docFreq.set(w, (docFreq.get(w) || 0) + 1);
+      }
+    }
+    for (const [word, df] of docFreq) {
+      this.idfCache.set(word, Math.log(totalSkills / df) + 1);
+    }
+  }
+  getAll() {
+    return Array.from(this.skills.values());
+  }
+  get(name) {
+    return this.skills.get(name);
+  }
+  findRelevant(prompt, maxResults = 3) {
+    const cacheKey = prompt.toLowerCase();
+    const cached = this.relevanceCache.get(cacheKey);
+    if (cached && cached.maxResults >= maxResults) {
+      return cached.results.slice(0, maxResults);
+    }
+    const lower = cacheKey;
+    const promptTokens = tokenize(lower);
+    const promptTokenSet = new Set(promptTokens);
+    const idf = (word) => this.idfCache.get(word) || 1;
+    const scored = [];
+    for (const skill of this.skills.values()) {
+      if (skill.disableModelInvocation) continue;
+      let score = 0;
+      if (lower.includes(skill.name.toLowerCase())) score += 10;
+      for (const kw of skill.keywords) {
+        if (lower.includes(kw.toLowerCase())) score += 8;
+      }
+      const descTokens = tokenize(skill.description.toLowerCase());
+      for (const word of descTokens) {
+        if (promptTokenSet.has(word)) score += 3 * idf(word);
+      }
+      const contentTokens = tokenize(skill.content.toLowerCase());
+      for (const word of contentTokens) {
+        if (promptTokenSet.has(word)) score += 0.5 * idf(word);
+      }
+      const promptBigrams = bigrams(promptTokens);
+      const descBigrams = bigrams(descTokens);
+      for (const bg of descBigrams) {
+        if (promptBigrams.has(bg)) score += 5;
+      }
+      if (score > 0) scored.push({ skill, score });
+    }
+    const results = scored.sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => s.skill);
+    this.relevanceCache.set(cacheKey, { results, maxResults });
+    return results;
+  }
+  /**
+   * Build lightweight skill descriptions for the system prompt.
+   * When a taskPrompt is provided, relevant skills are prioritized to the top;
+   * remaining skills are sorted by usage frequency (invocationCount).
+   */
+  buildSkillDescriptions(taskPrompt) {
+    const all = this.getAll().filter((s) => !s.disableModelInvocation);
+    if (all.length === 0) return "";
+    const alwaysSkills = all.filter((s) => s.metadata.always);
+    const rest = all.filter((s) => !s.metadata.always);
+    let relevantNames = null;
+    if (taskPrompt) {
+      const relevant = this.findRelevant(taskPrompt, 10);
+      relevantNames = new Set(relevant.map((s) => s.name));
+    }
+    const sorted = rest.sort((a, b) => {
+      if (relevantNames) {
+        const aRelevant = relevantNames.has(a.name);
+        const bRelevant = relevantNames.has(b.name);
+        if (aRelevant && !bRelevant) return -1;
+        if (!aRelevant && bRelevant) return 1;
+      }
+      return (b.invocationCount || 0) - (a.invocationCount || 0);
+    });
+    const skills = [...alwaysSkills, ...sorted];
+    let budget = this.DESCRIPTION_BUDGET_CHARS;
+    let prompt = "\n\n## Your Skills\n";
+    prompt += "These are your approved skills. Use skill_invoke to load full instructions when a task matches.\n";
+    prompt += "If no skill matches but the task is a reusable pattern, consider creating one with skill_create.\n\n";
+    let included = 0;
+    for (const skill of skills) {
+      const emoji = skill.metadata.emoji || "";
+      const hint = skill.argumentHint ? ` (${skill.argumentHint})` : "";
+      const line = `- **${emoji ? emoji + " " : ""}${skill.name}**${hint}: ${skill.description}
+`;
+      if (budget - line.length < 0) break;
+      budget -= line.length;
+      prompt += line;
+      included++;
+    }
+    if (included < skills.length) {
+      prompt += `
+_(${skills.length - included} additional skills available \u2014 use skill_search to find more)_
+`;
+    }
+    return prompt;
+  }
+  async create(name, description, content, options) {
+    if (!this.userId) return null;
+    try {
+      const metadata = options?.emoji ? { openclaw: { emoji: options.emoji } } : {};
+      const data = await callMcpHandler(
+        "skill.create",
+        {
+          name,
+          description,
+          content,
+          version: "1.0.0",
+          source: options?.source || "manual",
+          emoji: options?.emoji || null,
+          keywords: options?.keywords || [],
+          metadata
+        }
+      );
+      const raw = Array.isArray(data) ? data[0] : data;
+      const row = safeParse(SkillCreateResultSchema, raw);
+      if (!row) {
+        log.debug(`Skill create returned invalid data for "${name}"`);
+        return null;
+      }
+      const id = row.out_id || row.id;
+      const skillName = row.out_name || row.name || name;
+      this.skills.set(skillName, {
+        name: skillName,
+        description,
+        version: "1.0.0",
+        userInvocable: true,
+        disableModelInvocation: false,
+        keywords: options?.keywords || [],
+        allowedTools: [],
+        argumentHint: "",
+        metadata: options?.emoji ? { emoji: options.emoji } : {},
+        homepage: "",
+        content,
+        filePath: "",
+        source: options?.source || "manual",
+        dbId: id,
+        invocationCount: 0
+      });
+      this.invalidateCaches();
+      log.info(`Skill "${skillName}" created in skills table (pending approval)`);
+      return { id, name: skillName };
+    } catch (err) {
+      log.debug(`Skill create error: ${err}`);
+      return null;
+    }
+  }
+  async addSkill(skillId) {
+    if (!this.userId) return null;
+    try {
+      const result = await callMcpHandler(
+        "skill.fetch_and_add",
+        { skill_id: skillId }
+      );
+      const row = result.skill;
+      const agentSkillRow = result.agent_skill && typeof result.agent_skill === "object" ? result.agent_skill : row;
+      const skill = this.rowToSkill({
+        ...agentSkillRow,
+        name: row.name,
+        description: row.description,
+        content: row.content,
+        source_skill_id: skillId
+      });
+      this.skills.set(skill.name, skill);
+      this.invalidateCaches();
+      log.info(`Skill "${row.name}" added to user's collection`);
+      return skill;
+    } catch (err) {
+      log.debug(`addSkill error: ${err}`);
+      return null;
+    }
+  }
+  remove(name) {
+    const skill = this.skills.get(name);
+    if (!skill) return false;
+    this.skills.delete(name);
+    this.invalidateCaches();
+    this.removeFromDb(name).catch(() => {
+    });
+    return true;
+  }
+  listFormatted() {
+    const skills = this.getAll();
+    if (skills.length === 0) return "No skills in your collection.";
+    return skills.map((s) => {
+      const emoji = s.metadata.emoji || "";
+      return `  ${emoji ? emoji + " " : ""}${s.name} (${s.version}) [${s.source}]
+    ${s.description}`;
+    }).join("\n\n");
+  }
+  findSimilar(name) {
+    if (this.skills.has(name)) return this.skills.get(name);
+    const normalizedName = name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    for (const [existingName, skill] of this.skills) {
+      const normalizedExisting = existingName.toLowerCase().replace(/[^a-z0-9]/g, "");
+      if (normalizedName.includes(normalizedExisting) || normalizedExisting.includes(normalizedName)) {
+        return skill;
+      }
+      const nameWords = new Set(name.split("-"));
+      const existingWords = new Set(existingName.split("-"));
+      let overlap = 0;
+      for (const w of nameWords) {
+        if (existingWords.has(w)) overlap++;
+      }
+      if (overlap >= 2 || overlap >= 1 && nameWords.size <= 2) {
+        return skill;
+      }
+    }
+    return null;
+  }
+  update(name, newContent, description) {
+    const skill = this.skills.get(name);
+    if (!skill) return false;
+    const versionParts = skill.version.split(".").map(Number);
+    versionParts[2] = (versionParts[2] || 0) + 1;
+    const newVersion = versionParts.join(".");
+    const newDescription = description || skill.description;
+    skill.content = newContent;
+    skill.description = newDescription;
+    skill.version = newVersion;
+    this.invalidateCaches();
+    this.syncToAgentSkills(name, newDescription, newContent, newVersion, {
+      source: "auto_improved"
+    }).catch(() => {
+    });
+    if (skill.sourceSkillId && this.userId) {
+      callMcpHandler("skill.update_source", {
+        source_skill_id: skill.sourceSkillId,
+        content: newContent,
+        description: newDescription,
+        version: newVersion
+      }).catch(() => {
+      });
+    }
+    log.info(`Skill "${name}" updated to v${newVersion}`);
+    return true;
+  }
+  // ── DB Integration ─────────────────────────────────────────────────
+  async syncToAgentSkills(name, description, content, version, options) {
+    if (!this.userId) return;
+    try {
+      const data = await callMcpHandler("skill.upsert", {
+        name,
+        description,
+        content,
+        version,
+        source: options?.source || "manual",
+        emoji: options?.emoji || null,
+        keywords: options?.keywords || [],
+        change_summary: options?.changeSummary || null,
+        source_skill_id: options?.sourceSkillId || null
+      });
+      const skill = this.skills.get(name);
+      if (skill && data && typeof data === "object" && "id" in data) {
+        skill.dbId = data.id;
+      }
+      log.debug(`Skill "${name}" synced to agent_skills`);
+    } catch (err) {
+      log.debug(`DB skill sync error for "${name}": ${err}`);
+    }
+  }
+  async logInvocation(skillName, options) {
+    if (!this.userId) return;
+    const skill = this.skills.get(skillName);
+    const skillDbId = skill?.dbId;
+    if (!skillDbId) {
+      log.debug(`Cannot log invocation: skill "${skillName}" has no DB ID`);
+      return;
+    }
+    try {
+      await callMcpHandler("skill.log_invocation", {
+        skill_id: skillDbId,
+        message_id: options?.messageId || null,
+        session_id: options?.sessionId || null,
+        task_prompt: options?.taskPrompt?.slice(0, 500) || null,
+        arguments: options?.arguments || null,
+        success: options?.success ?? null
+      });
+    } catch (err) {
+      log.debug(`Invocation log error: ${err}`);
+    }
+  }
+  async searchDb(query, limit = 10) {
+    if (this.userId) {
+      try {
+        const data = await callMcpHandler("skill.search", {
+          query,
+          limit
+        });
+        if (data) {
+          return data.map((row) => ({
+            name: String(row.name),
+            description: String(row.description ?? ""),
+            emoji: String(row.emoji ?? ""),
+            source: String(row.source ?? "manual"),
+            invocationCount: typeof row.invocation_count === "number" ? row.invocation_count : 0
+          }));
+        }
+      } catch {
+      }
+    }
+    const results = this.findRelevant(query, limit);
+    return results.map((s) => ({
+      name: s.name,
+      description: s.description,
+      emoji: s.metadata.emoji || "",
+      source: s.source,
+      invocationCount: 0
+    }));
+  }
+  async removeFromDb(name) {
+    if (!this.userId) return;
+    try {
+      await callMcpHandler("skill.remove", { name });
+    } catch {
+    }
+  }
+  // ── Marketplace ────────────────────────────────────────────────────
+  async publish(name, options) {
+    if (!this.userId) return null;
+    const skill = this.skills.get(name);
+    if (!skill) return null;
+    if (skill.source === "external") {
+      log.debug(`Cannot publish external skill "${name}"`);
+      return null;
+    }
+    try {
+      const data = await callMcpHandler("skill.publish", {
+        name: skill.name,
+        description: skill.description,
+        version: skill.version,
+        emoji: skill.metadata.emoji || null,
+        content: skill.content,
+        argument_hint: skill.argumentHint || null,
+        keywords: skill.keywords,
+        allowed_tools: skill.allowedTools,
+        author_name: options?.authorName || null,
+        metadata: skill.metadata,
+        homepage: skill.homepage || null,
+        category: options?.category || null,
+        source: skill.source
+      });
+      log.info(`Skill "${name}" published to marketplace`);
+      return data;
+    } catch (err) {
+      log.debug(`Publish error: ${err}`);
+      return null;
+    }
+  }
+  async browse(options) {
+    try {
+      const data = await callMcpHandler("skill.browse", {
+        query: options?.query || null,
+        category: options?.category || null,
+        sort: options?.sort || "popular",
+        limit: options?.limit || 20,
+        offset: options?.offset || 0
+      });
+      return (data || []).map((r) => safeParse(BrowseSkillRowSchema, r)).filter(Boolean).map((r) => ({
+        id: r.id,
+        name: r.name,
+        description: r.description,
+        emoji: r.emoji,
+        version: r.version,
+        authorName: r.author_name,
+        category: r.category,
+        installCount: r.install_count,
+        avgRating: r.avg_rating ?? null,
+        ratingCount: r.rating_count
+      }));
+    } catch {
+      return [];
+    }
+  }
+};
+function validateSkillName(name) {
+  if (!name || name.length === 0) return "name is empty";
+  if (name.length > 64) return `name too long (${name.length}/64 chars)`;
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+    return `name must be lowercase kebab-case (a-z, 0-9, hyphens), no leading/trailing/consecutive hyphens. Got: "${name}"`;
+  }
+  return null;
+}
+function normalizeSkillName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 64);
+}
+function substituteArguments(content, args) {
+  const parts = args.split(/\s+/);
+  content = content.replace(/\$ARGUMENTS/g, args);
+  content = content.replace(/\$ARGUMENTS\[(\d+)\]/g, (_, i) => parts[parseInt(i)] || "");
+  content = content.replace(/\$(\d+)(?!\w)/g, (_, i) => parts[parseInt(i)] || "");
+  return content;
+}
+var SAFE_DYNAMIC_COMMANDS = /^(date|whoami|hostname|uname|pwd|echo|node\s+--version|npm\s+--version|git\s+(branch|rev-parse|log\s+--oneline)|cat\s+)/;
+function preprocessDynamicContext(content, cwd) {
+  return content.replace(/!`([^`]+)`/g, (_, cmd) => {
+    if (!SAFE_DYNAMIC_COMMANDS.test(cmd.trim())) {
+      return `[command blocked: ${cmd}]`;
+    }
+    try {
+      return execSync2(cmd, { timeout: 1e4, encoding: "utf-8", cwd }).trim();
+    } catch {
+      return `[command failed: ${cmd}]`;
+    }
+  });
+}
+
+// src/credentials/credential-store.ts
+import { randomUUID } from "crypto";
+import { dirname } from "path";
+
+// src/credentials/encryption.ts
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, createHash } from "crypto";
+import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2, hostname, userInfo } from "os";
+var ALGORITHM = "aes-256-gcm";
+var KEY_LENGTH = 32;
+var IV_LENGTH = 12;
+var AUTH_TAG_LENGTH = 16;
+var SALT_FILE = "encryption.salt";
+function deriveKey(basePath) {
+  const saltPath = join2(basePath, SALT_FILE);
+  let salt;
+  if (existsSync2(saltPath)) {
+    salt = readFileSync(saltPath);
+  } else {
+    salt = randomBytes(32);
+    if (!existsSync2(basePath)) {
+      mkdirSync2(basePath, { recursive: true, mode: 448 });
+    }
+    writeFileSync(saltPath, salt, { mode: 384 });
+  }
+  const machineId = createHash("sha256").update(hostname()).update(userInfo().username).update(homedir2()).digest();
+  return scryptSync(machineId, salt, KEY_LENGTH);
+}
+function encrypt(plaintext, key) {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf-8"),
+    cipher.final()
+  ]);
+  return {
+    iv: iv.toString("base64"),
+    data: encrypted.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64")
+  };
+}
+function decrypt(payload, key) {
+  const iv = Buffer.from(payload.iv, "base64");
+  const data = Buffer.from(payload.data, "base64");
+  const tag = Buffer.from(payload.tag, "base64");
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(tag);
+  return Buffer.concat([
+    decipher.update(data),
+    decipher.final()
+  ]).toString("utf-8");
+}
+
+// src/credentials/local-store.ts
+import Database from "better-sqlite3";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir3 } from "os";
+var DEFAULT_DB_DIR = join3(homedir3(), ".config", "assistme");
+var DEFAULT_DB_NAME = "local.db";
+var LocalStore = class {
+  db;
+  dbPath;
+  constructor(dbPath) {
+    const dir = dbPath ? dbPath : DEFAULT_DB_DIR;
+    if (!existsSync3(dir)) {
+      mkdirSync3(dir, { recursive: true, mode: 448 });
+    }
+    this.dbPath = dbPath ? join3(dbPath, DEFAULT_DB_NAME) : join3(DEFAULT_DB_DIR, DEFAULT_DB_NAME);
+    this.db = new Database(this.dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("foreign_keys = ON");
+    this.migrate();
+  }
+  /** Run schema migrations. Idempotent — safe to call on every startup. */
+  migrate() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS credentials (
+        id            TEXT PRIMARY KEY,
+        name          TEXT NOT NULL UNIQUE,
+        type          TEXT NOT NULL DEFAULT 'secret',
+        skill_name    TEXT,
+        tags          TEXT NOT NULL DEFAULT '[]',
+        encrypted_data TEXT NOT NULL,
+        created_at    TEXT NOT NULL,
+        updated_at    TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_credentials_name ON credentials(name);
+      CREATE INDEX IF NOT EXISTS idx_credentials_skill ON credentials(skill_name);
+      CREATE INDEX IF NOT EXISTS idx_credentials_type ON credentials(type);
+
+      CREATE TABLE IF NOT EXISTS programs (
+        id            TEXT PRIMARY KEY,
+        name          TEXT NOT NULL UNIQUE,
+        description   TEXT NOT NULL DEFAULT '',
+        language      TEXT NOT NULL DEFAULT 'unknown',
+        directory     TEXT NOT NULL,
+        skill_name    TEXT,
+        tags          TEXT NOT NULL DEFAULT '[]',
+        status        TEXT NOT NULL DEFAULT 'active',
+        metadata      TEXT NOT NULL DEFAULT '{}',
+        created_at    TEXT NOT NULL,
+        updated_at    TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_programs_name ON programs(name);
+      CREATE INDEX IF NOT EXISTS idx_programs_skill ON programs(skill_name);
+      CREATE INDEX IF NOT EXISTS idx_programs_status ON programs(status);
+    `);
+  }
+  /** Get the raw database handle for direct queries. */
+  getDb() {
+    return this.db;
+  }
+  /** Close the database connection. */
+  close() {
+    this.db.close();
+  }
+};
+var _instance = null;
+function getLocalStore(dbPath) {
+  if (!_instance) {
+    _instance = new LocalStore(dbPath);
+  }
+  return _instance;
+}
+
+// src/credentials/credential-store.ts
+var CredentialStore = class {
+  store;
+  encryptionKey;
+  constructor(dbPath) {
+    this.store = getLocalStore(dbPath);
+    this.encryptionKey = deriveKey(dirname(this.store.dbPath));
+  }
+  // ── CRUD ────────────────────────────────────────────────────────
+  save(name, type, data, opts) {
+    const db = this.store.getDb();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const encryptedData = this.encryptData(data);
+    const tags = JSON.stringify(opts?.tags || []);
+    const existing = db.prepare("SELECT id FROM credentials WHERE name = ?").get(name);
+    if (existing) {
+      db.prepare(`
+        UPDATE credentials
+        SET type = ?, skill_name = ?, tags = ?, encrypted_data = ?, updated_at = ?
+        WHERE id = ?
+      `).run(type, opts?.skillName ?? null, tags, encryptedData, now, existing.id);
+      log.debug(`Credential "${name}" updated (${existing.id})`);
+      return this.toMeta({ id: existing.id, name, type, skill_name: opts?.skillName ?? null, tags, encrypted_data: encryptedData, created_at: now, updated_at: now });
+    }
+    const id = randomUUID();
+    db.prepare(`
+      INSERT INTO credentials (id, name, type, skill_name, tags, encrypted_data, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, name, type, opts?.skillName ?? null, tags, encryptedData, now, now);
+    log.debug(`Credential "${name}" saved (${id})`);
+    return { id, name, type, skillName: opts?.skillName, tags: opts?.tags || [], createdAt: now, updatedAt: now };
+  }
+  get(id) {
+    const row = this.store.getDb().prepare("SELECT * FROM credentials WHERE id = ?").get(id);
+    return row ? this.toCredential(row) : null;
+  }
+  getByName(name) {
+    const row = this.store.getDb().prepare("SELECT * FROM credentials WHERE name = ?").get(name);
+    return row ? this.toCredential(row) : null;
+  }
+  update(id, data) {
+    const row = this.store.getDb().prepare("SELECT * FROM credentials WHERE id = ?").get(id);
+    if (!row) return null;
+    const existing = this.decryptData(row.encrypted_data);
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(data)) {
+      if (value !== void 0) {
+        merged[key] = value;
+      }
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const encryptedData = this.encryptData(merged);
+    this.store.getDb().prepare("UPDATE credentials SET encrypted_data = ?, updated_at = ? WHERE id = ?").run(encryptedData, now, id);
+    log.debug(`Credential "${row.name}" updated`);
+    return this.toMeta({ ...row, encrypted_data: encryptedData, updated_at: now });
+  }
+  remove(id) {
+    const result = this.store.getDb().prepare("DELETE FROM credentials WHERE id = ?").run(id);
+    if (result.changes > 0) {
+      log.debug(`Credential ${id} removed`);
+      return true;
+    }
+    return false;
+  }
+  removeByName(name) {
+    const result = this.store.getDb().prepare("DELETE FROM credentials WHERE name = ?").run(name);
+    if (result.changes > 0) {
+      log.debug(`Credential "${name}" removed`);
+      return true;
+    }
+    return false;
+  }
+  // ── Query ───────────────────────────────────────────────────────
+  list() {
+    const rows = this.store.getDb().prepare("SELECT * FROM credentials ORDER BY updated_at DESC").all();
+    return rows.map((r) => this.toMeta(r));
+  }
+  findBySkill(skillName) {
+    const rows = this.store.getDb().prepare("SELECT * FROM credentials WHERE skill_name = ? ORDER BY name").all(skillName);
+    return rows.map((r) => this.toMeta(r));
+  }
+  findByTag(tag) {
+    const rows = this.store.getDb().prepare("SELECT * FROM credentials WHERE tags LIKE ? ORDER BY name").all(`%${tag.toLowerCase()}%`);
+    return rows.filter((r) => {
+      const tags = JSON.parse(r.tags);
+      return tags.some((t) => t.toLowerCase() === tag.toLowerCase());
+    }).map((r) => this.toMeta(r));
+  }
+  findByType(type) {
+    const rows = this.store.getDb().prepare("SELECT * FROM credentials WHERE type = ? ORDER BY name").all(type);
+    return rows.map((r) => this.toMeta(r));
+  }
+  // ── Bulk ────────────────────────────────────────────────────────
+  removeBySkill(skillName) {
+    const result = this.store.getDb().prepare("DELETE FROM credentials WHERE skill_name = ?").run(skillName);
+    return result.changes;
+  }
+  clear() {
+    this.store.getDb().prepare("DELETE FROM credentials").run();
+  }
+  // ── Internal ────────────────────────────────────────────────────
+  encryptData(data) {
+    const payload = encrypt(JSON.stringify(data), this.encryptionKey);
+    return JSON.stringify(payload);
+  }
+  decryptData(encrypted) {
+    const payload = JSON.parse(encrypted);
+    const decrypted = decrypt(payload, this.encryptionKey);
+    return JSON.parse(decrypted);
+  }
+  toMeta(row) {
+    return {
+      id: row.id,
+      name: row.name,
+      type: row.type,
+      skillName: row.skill_name || void 0,
+      tags: JSON.parse(row.tags),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at
+    };
+  }
+  toCredential(row) {
+    try {
+      return {
+        meta: this.toMeta(row),
+        data: this.decryptData(row.encrypted_data)
+      };
+    } catch (err) {
+      log.debug(`Failed to decrypt credential ${row.id}: ${err}`);
+      return null;
+    }
+  }
+};
+var _instance2 = null;
+function getCredentialStore() {
+  if (!_instance2) {
+    _instance2 = new CredentialStore();
+  }
+  return _instance2;
+}
+
+// src/tools/shell.ts
+import { exec } from "child_process";
+var BLOCKED_PATTERNS = [
+  /rm\s+(-\w*\s+)*-\w*r\w*\s+\/($|\s)/i,
+  // rm -rf /, rm -fr /, etc.
+  /rm\s+(-\w*\s+)*-\w*r\w*\s+~($|\s|\/)/i,
+  // rm -rf ~, rm -fr ~/, etc.
+  /\bmkfs\b/i,
+  // mkfs (any form)
+  /\bdd\s+.*\bif=/i,
+  // dd if=
+  /:\s*\(\s*\)\s*\{/,
+  // fork bomb :(){}
+  /\bchmod\s+(-\w+\s+)*-R\s+777\s+\//i,
+  // chmod -R 777 /
+  />\s*\/dev\/sd[a-z]/i,
+  // write to raw disk
+  /\bshutdown\b/i,
+  // shutdown
+  /\breboot\b/i,
+  // reboot
+  /\bsystemctl\s+(start|stop|disable|mask)\b/i
+  // dangerous systemctl ops
+];
+function isBlocked(command) {
+  return BLOCKED_PATTERNS.some((pattern) => pattern.test(command));
+}
+async function executeShell(command, cwd) {
+  if (isBlocked(command)) {
+    throw new AppError(`Command blocked for safety: "${command}"`, "COMMAND_BLOCKED");
+  }
+  const config = getConfig();
+  const workDir = cwd || config.workspacePath;
+  return new Promise((resolve) => {
+    exec(
+      command,
+      {
+        cwd: workDir,
+        timeout: SHELL_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        // 1MB buffer
+        env: { ...process.env, TERM: "dumb" }
+      },
+      (error, stdout, stderr) => {
+        let output = "";
+        if (stdout) {
+          output += stdout;
+        }
+        if (stderr) {
+          output += stderr ? `
+[stderr]
+${stderr}` : "";
+        }
+        if (error && !stdout && !stderr) {
+          output = `Error: ${error.message}`;
+        }
+        if (output.length > SHELL_MAX_OUTPUT) {
+          output = output.slice(0, SHELL_MAX_OUTPUT) + `
+
+[Output truncated at ${SHELL_MAX_OUTPUT} bytes]`;
+        }
+        resolve(output || "(no output)");
+      }
+    );
+  });
+}
+
+export {
+  loginWithToken,
+  getCurrentUserId,
+  logout,
+  createSession,
+  updateHeartbeat,
+  endSession,
+  setSessionBusy,
+  cleanupStaleSessions,
+  getActiveSessions,
+  createTask,
+  pollAndClaimTask,
+  claimTask,
+  completeTask,
+  failTask,
+  getOrCreateCliConversation,
+  getConversationHistory,
+  resetEventSequence,
+  emitEvent,
+  setActionRequest,
+  pollActionResponse,
+  pollAndClaimJobRun,
+  BrowserController,
+  ensureBrowserAvailable,
+  getBrowser,
+  getNextRunTime,
+  Scheduler,
+  createScheduledTask,
+  listScheduledTasks,
+  toggleScheduledTask,
+  deleteScheduledTask,
+  executeShell,
+  MemoryManager,
+  SkillManager,
+  validateSkillName,
+  normalizeSkillName,
+  substituteArguments,
+  preprocessDynamicContext,
+  getLocalStore,
+  getCredentialStore
+};