poltertab 1.5.0 → 1.6.0-beta.1

package/mcp-server/index.js

@@ -13,7 +13,14 @@ const { SMART_SCROLL_SETTLE_MS, POLTERTAB_HOME } = require("./config.js");
 const updates = require("./update-check.js");
 const { BROWSER_TOOLS } = require("./tools.js");
 const { writeOutput, summarizeOutput, rowsOf } = require("./output.js");
-const { readMemory, saveMemory } = require("./memory.js");
+const {
+  readMemory,
+  saveMemory,
+  getSelector,
+  recordSelector,
+  noteSelectorFail,
+  selectorKey,
+} = require("./memory.js");
 const { extractAll } = require("./extract-all.js");
 const bridge = require("./bridge.js");
 const OWN_VERSION = require("./../package.json").version;
@@ -53,6 +60,44 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   };
 });
 
+// Which page a tab (or a named session) is on, learned from the URL any
+// navigate/get_url/action result reveals — no extra round-trip to ask. The
+// selector store is keyed by this, so it has to be the page the click actually
+// lands on.
+const pageByTab = new Map();
+const pageBySession = new Map();
+let lastPage = null;
+
+function pageOf(url) {
+  try {
+    const u = new URL(url);
+    return u.hostname ? { host: u.hostname, path: u.pathname } : null;
+  } catch {
+    return null;
+  }
+}
+
+function rememberPage(args, result) {
+  const page = pageOf(result && result.url);
+  if (!page) return;
+  const tabId = (result && result.tabId) ?? (args && args.tabId);
+  if (tabId != null) pageByTab.set(tabId, page);
+  if (args && args.session) pageBySession.set(args.session, page);
+  lastPage = page;
+}
+
+// An explicitly targeted tab or session resolves to ITS OWN page or to nothing.
+// Falling back to a process-global here is how a click in session s1 ended up
+// keyed to whatever host s2 had navigated to most recently — and `session` is
+// the documented multi-tab mechanism, so that path is normal usage, not a
+// corner case. No page means no healing, which is the safe direction.
+function pageFor(args) {
+  const a = args || {};
+  if (a.session) return pageBySession.get(a.session) || null;
+  if (a.tabId != null) return pageByTab.get(a.tabId) || null;
+  return lastPage;
+}
+
 const handleToolCall = async (request) => {
   const { name, arguments: args } = request.params;
 
@@ -142,9 +187,11 @@ const handleToolCall = async (request) => {
     if (action === "get_site_memory") {
       const host = args.hostname || args.domain || args.url;
       if (!host) throw new Error("Missing 'hostname' parameter");
+      // The agent only wants its own notes; the selectors map is internal
+      // plumbing for self-healing and would just be noise here.
       return {
         content: [
-          { type: "text", text: JSON.stringify(readMemory(host), null, 2) },
+          { type: "text", text: JSON.stringify(readMemory(host).notes, null, 2) },
         ],
       };
     }
@@ -184,9 +231,54 @@ const handleToolCall = async (request) => {
       };
     }
 
-    const result = await bridge.sendCommand(action, args || {});
+    // Self-healing: for click/fill, supply a remembered fingerprint when the
+    // selector has no explicit one, and remember the fingerprint that worked so
+    // a later drift can be relocated. Keyed by the page the action lands on and
+    // by the action itself — see memory.selectorKey.
+    const healable = action === "click" || action === "fill";
+    const selector = args && args.selector;
+    const page = healable && selector ? pageFor(args) : null;
+    const key = page ? selectorKey(action, page.path, selector) : null;
+    if (key && !args.fingerprint) {
+      // Reading the store must never stop a click that would otherwise work.
+      try {
+        const stored = getSelector(page.host, key);
+        if (stored) args.fingerprint = stored.fingerprint;
+      } catch (_) {
+        // Unreadable store: proceed on the caller's own selector.
+      }
+    }
+
+    let result;
+    try {
+      result = await bridge.sendCommand(action, args || {});
+    } catch (err) {
+      // A selector that missed even with its stored fingerprint is drifting;
+      // enough misses and memory.js stops trusting it. Bookkeeping only — it
+      // must not replace the error the caller needs to see.
+      if (key && /not found/i.test(err.message)) {
+        try {
+          noteSelectorFail(page.host, key);
+        } catch (_) {
+          // Best effort.
+        }
+      }
+      throw err;
+    }
     bridge.noteActiveTab((result && result.tabId) || (args && args.tabId));
 
+    // Learn the page for later, and store the fingerprint of what resolved.
+    // Wrapped because the browser has ALREADY acted: a failure here would be
+    // reported as a failed click, and the agent would retry and double-submit.
+    try {
+      rememberPage(args, result);
+      if (key && result && result.fingerprint) {
+        recordSelector(page.host, key, result.fingerprint);
+      }
+    } catch (_) {
+      // The action succeeded; losing the bookkeeping is the lesser evil.
+    }
+
     // Any read tool can send its payload to disk. Placed after tab tracking so
     // taking the file path does not cost the session its tab bookkeeping.
     if (args && args.output_file && result && typeof result === "object") {

package/mcp-server/memory.js

@@ -65,17 +65,143 @@ function memoryFile(rawHost) {
   return path.join(MEMORY_DIR, `${bare}.json`);
 }
 
+// Free-text notes are capped so a chatty agent can't grow one file without
+// bound; selectors likewise, evicting the least-recently-used first.
+const NOTES_CAP = 100;
+const SELECTORS_CAP = 200;
+// A selector that keeps missing even with its fingerprint has drifted past
+// recognition — stop trusting it rather than relocating against a dead signature.
+const MAX_FAILS = 3;
+
+// Normalize any on-disk shape — including the original bare array — to the
+// current { notes, selectors } form. Old files upgrade in place on the next
+// write, so there is no migration step.
+function normalize(raw) {
+  if (Array.isArray(raw)) return { notes: raw, selectors: {} };
+  return {
+    notes: raw && Array.isArray(raw.notes) ? raw.notes : [],
+    selectors:
+      raw && raw.selectors && typeof raw.selectors === "object"
+        ? raw.selectors
+        : {},
+  };
+}
+
 function readMemory(rawHost) {
   const file = memoryFile(rawHost);
-  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : [];
+  if (!fs.existsSync(file)) return normalize(null);
+  // getSelector sits on the click/fill path, so an unreadable file here used to
+  // brick every click on the host. A truncated or hand-edited file is not worth
+  // that: read it as empty and let the action proceed on its own selector.
+  try {
+    return normalize(JSON.parse(fs.readFileSync(file, "utf8")));
+  } catch (_) {
+    return normalize(null);
+  }
 }
 
-function saveMemory(rawHost, obstacle, solution) {
+// writeFileSync truncates in place, so a crash — or a second MCP process, which
+// bridge.js explicitly supports — mid-write leaves a half-written file that the
+// next read cannot parse. Write a sibling temp file and rename: rename is atomic
+// within a directory, so a reader sees the old file or the new one, never a
+// partial one.
+function writeMemory(rawHost, data) {
   const file = memoryFile(rawHost);
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (_) {
+      // Nothing to clean up.
+    }
+    throw err;
+  }
+}
+
+// The selector store is bookkeeping for an action that already happened, so a
+// failed write must never surface as a failed click — the agent would retry and
+// double-submit. saveMemory stays strict: it IS the user's action.
+function bestEffort(fn) {
+  try {
+    fn();
+  } catch (_) {
+    // Read-only or full home: keep the healing we cannot persist to ourselves.
+  }
+}
+
+function saveMemory(rawHost, obstacle, solution) {
   const data = readMemory(rawHost);
-  data.push({ obstacle, solution, timestamp: Date.now() });
-  fs.writeFileSync(file, JSON.stringify(data, null, 2));
-  return data.length;
+  // Re-saving an identical note is a no-op, not another copy of the same line.
+  const dup = data.notes.some(
+    (n) => n.obstacle === obstacle && n.solution === solution,
+  );
+  if (!dup) {
+    data.notes.push({ obstacle, solution, timestamp: Date.now() });
+    if (data.notes.length > NOTES_CAP)
+      data.notes = data.notes.slice(-NOTES_CAP);
+  }
+  writeMemory(rawHost, data);
+  return data.notes.length;
+}
+
+// Selector entries are keyed by action + page path + selector, not by selector
+// alone. Host-only keying meant a fingerprint learned for "#submit" on
+// /checkout was injected into a click on "#submit" on /settings, and one
+// recorded by fill was injected into a click — different elements, and on
+// destructive controls that is a wrong click, then persisted as the new truth.
+function selectorKey(action, path, selector) {
+  return `${action}|${path || "/"}|${selector}`;
+}
+
+function getSelector(rawHost, selector) {
+  return readMemory(rawHost).selectors[selector] || null;
+}
+
+function recordSelector(rawHost, selector, fingerprint) {
+  if (!fingerprint) return; // nothing worth remembering
+  bestEffort(() => {
+    const data = readMemory(rawHost);
+    data.selectors[selector] = {
+      fingerprint,
+      lastOk: Date.now(),
+      failCount: 0,
+    };
+    evictSelectors(data.selectors);
+    writeMemory(rawHost, data);
+  });
+}
+
+function noteSelectorFail(rawHost, selector) {
+  bestEffort(() => {
+    const data = readMemory(rawHost);
+    const entry = data.selectors[selector];
+    if (!entry) return;
+    entry.failCount = (entry.failCount || 0) + 1;
+    if (entry.failCount >= MAX_FAILS) delete data.selectors[selector];
+    writeMemory(rawHost, data);
+  });
+}
+
+// Bound the store: when a host accrues too many selectors, drop the ones whose
+// last success is oldest.
+function evictSelectors(selectors) {
+  const keys = Object.keys(selectors);
+  if (keys.length <= SELECTORS_CAP) return;
+  keys
+    .sort((a, b) => (selectors[a].lastOk || 0) - (selectors[b].lastOk || 0))
+    .slice(0, keys.length - SELECTORS_CAP)
+    .forEach((k) => delete selectors[k]);
 }
 
-module.exports = { memoryFile, readMemory, saveMemory };
+module.exports = {
+  memoryFile,
+  selectorKey,
+  readMemory,
+  saveMemory,
+  getSelector,
+  recordSelector,
+  noteSelectorFail,
+};

package/mcp-server/tools.js

@@ -29,6 +29,17 @@ const SINK = {
   },
 };
 
+// Self-healing: browser_click/browser_fill return the resolved element's
+// fingerprint. Pass it back on a later call and, if the selector has drifted
+// (a renamed id/class), the element is relocated by structural similarity.
+const FINGERPRINT = {
+  fingerprint: {
+    type: "object",
+    description:
+      "Optional. The `fingerprint` object a previous browser_click/browser_fill returned for this element. When the selector no longer matches, the element is relocated by structural similarity and the result carries healed:true.",
+  },
+};
+
 // Define tools
 const BROWSER_TOOLS = [
   {
@@ -45,11 +56,13 @@ const BROWSER_TOOLS = [
   },
   {
     name: "browser_click",
-    description: "Click an element on the page",
+    description:
+      "Click an element on the page. Returns the element's `fingerprint` (pass it back later to survive a selector change) and `healed:true` if the selector had drifted and the element was relocated.",
     inputSchema: {
       type: "object",
       properties: {
         selector: { type: "string" },
+        ...FINGERPRINT,
         ...TARGET,
       },
       required: ["selector"],
@@ -57,13 +70,15 @@ const BROWSER_TOOLS = [
   },
   {
     name: "browser_fill",
-    description: "Fill an input field with text",
+    description:
+      "Fill an input field with text. Returns the field's `fingerprint` (pass it back later to survive a selector change) and `healed:true` if the selector had drifted and the field was relocated.",
     inputSchema: {
       type: "object",
       properties: {
         selector: { type: "string" },
         value: { type: "string" },
         submit: { type: "boolean" },
+        ...FINGERPRINT,
         ...TARGET,
       },
       required: ["selector", "value"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.5.0",
+  "version": "1.6.0-beta.1",
   "description": "Let any AI assistant drive and scrape your existing Chrome profile — no headless browser, no complex setup.",
   "bin": {
     "poltertab": "./bin/poltertab.js"