arc-control-mcp 0.3.0

package/src/state.js

@@ -0,0 +1,216 @@
+import { readFileSync, writeFileSync, renameSync, mkdirSync, openSync, closeSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// Ownership is per process, never seeded from disk: two agents can share a
+// label, and adopting the other one's tabs would let close_own_tabs close
+// them. The file is keyed by session so a restarted agent can still find the
+// tabs its dead predecessor leaked, and reap them on purpose (staleIds).
+const STATE_DIR = process.env.ARC_MCP_STATE_DIR || join(homedir(), 'Library', 'Application Support', 'arc-control-mcp');
+const LABEL = process.env.ARC_MCP_LABEL || 'default';
+const STATE_FILE = join(STATE_DIR, `${LABEL}.json`);
+const LOCK_FILE = `${STATE_FILE}.lock`;
+const LOCK_WAIT_MS = 2000;
+const LOCK_RETRY_MS = 5;
+
+// pids get reused, so the start time keeps a restarted agent from being
+// mistaken for its own previous session.
+const SESSION_ID = `${process.pid}-${Math.round(Date.now() - process.uptime() * 1000)}`;
+
+// How long a dead session's tab ids stay interesting. Long enough to survive a
+// weekend of restarts, short enough that the file cannot grow forever.
+const STALE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+export const AGENT_SPACE = process.env.ARC_MCP_SPACE || 'Agent';
+
+const session = { owned: new Set(), currentTabId: null };
+
+const pidOf = (sessionId) => Number.parseInt(String(sessionId).split('-')[0], 10);
+
+// EPERM means the pid exists but belongs to someone else, which still counts
+// as alive. Anything else (ESRCH, a malformed id) means gone.
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+const isDeadSession = (sessionId) => sessionId !== SESSION_ID && !isAlive(pidOf(sessionId));
+
+function readSessions() {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+  if (raw && raw.sessions && typeof raw.sessions === 'object') return raw.sessions;
+  // A file written by the flat pre-session format carries no session identity,
+  // so there is no way to tell whether its tabs were left by a run that ended
+  // or are being used right now by a server still on the old code. Treating
+  // them as reapable once marked two of the user's live tabs for closing, so
+  // they are dropped instead. The cost is that genuinely leaked pre-upgrade
+  // tabs need closing by hand, which is far cheaper than closing live ones.
+  if (raw && Array.isArray(raw.owned) && raw.owned.length > 0) {
+    console.error(
+      `arc-control: ignoring ${raw.owned.length} tab id(s) from the pre-session state format, ` +
+        'since they cannot be attributed to a finished run. Close them by hand if they were left behind.'
+    );
+  }
+  return {};
+}
+
+/** Dead sessions are kept only while they still name tabs worth reaping. */
+function compact(sessions) {
+  const cutoff = Date.now() - STALE_RETENTION_MS;
+  const out = {};
+  for (const [id, entry] of Object.entries(sessions)) {
+    if (!isDeadSession(id)) {
+      out[id] = entry;
+      continue;
+    }
+    if (!entry.owned || entry.owned.length === 0) continue;
+    const updatedAt = Date.parse(entry.updatedAt || '');
+    if (Number.isFinite(updatedAt) && updatedAt < cutoff) continue;
+    out[id] = entry;
+  }
+  return out;
+}
+
+function writeAtomic(sessions) {
+  // Temp name carries the session id so two writers never share one, and the
+  // rename means a crash mid-write cannot leave a half-written state file.
+  const tmp = `${STATE_FILE}.${SESSION_ID}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ label: LABEL, sessions }, null, 2));
+  renameSync(tmp, STATE_FILE);
+}
+
+// The state file is tiny, so a blocking wait costs microseconds and is much
+// simpler than an async lock in code paths that are otherwise synchronous.
+const sleepSync = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+/**
+ * Cross-process mutex. Without it, two agents reading and writing the same
+ * file lose each other's updates: measured, one agent's tab vanished from disk
+ * and stopped being reapable. `wx` fails when the lock exists, which is the
+ * whole mechanism. A lock older than LOCK_WAIT_MS belonged to a crashed
+ * process, so it is broken rather than left to wedge every later call.
+ */
+function withLock(fn) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  let fd;
+  for (;;) {
+    try {
+      fd = openSync(LOCK_FILE, 'wx');
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() > deadline) {
+        rmSync(LOCK_FILE, { force: true });
+        fd = openSync(LOCK_FILE, 'w');
+        break;
+      }
+      sleepSync(LOCK_RETRY_MS);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    closeSync(fd);
+    rmSync(LOCK_FILE, { force: true });
+  }
+}
+
+/**
+ * Read-modify-write, so a sibling process sharing this label keeps its own
+ * entry. `reaped` ids are also dropped from the dead sessions that listed
+ * them, which is how a closed leaked tab stops being reported as stale.
+ * A persistence failure is logged and swallowed: it must never fail a tool call.
+ */
+function persist(reaped) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    withLock(() => {
+      const sessions = readSessions();
+      sessions[SESSION_ID] = {
+        owned: [...session.owned],
+        currentTabId: session.currentTabId,
+        updatedAt: new Date().toISOString()
+      };
+      if (reaped && reaped.size > 0) {
+        for (const [id, entry] of Object.entries(sessions)) {
+          if (id === SESSION_ID) continue;
+          sessions[id] = { ...entry, owned: (entry.owned || []).filter((tabId) => !reaped.has(tabId)) };
+        }
+      }
+      writeAtomic(compact(sessions));
+    });
+  } catch (error) {
+    console.error('arc-control: could not persist state:', error.message);
+  }
+}
+
+export function claim(tabId) {
+  if (!tabId) return;
+  session.owned.add(tabId);
+  session.currentTabId = tabId;
+  persist();
+}
+
+export function release(tabId) {
+  session.owned.delete(tabId);
+  if (session.currentTabId === tabId) {
+    session.currentTabId = [...session.owned].pop() || null;
+  }
+  persist(new Set([tabId]));
+}
+
+export function focusOwn(tabId) {
+  if (!session.owned.has(tabId)) return;
+  session.currentTabId = tabId;
+  persist();
+}
+
+export const ownedIds = () => [...session.owned];
+export const currentTabId = () => session.currentTabId;
+export const isOwned = (tabId) => session.owned.has(tabId);
+export const label = () => LABEL;
+export const sessionId = () => SESSION_ID;
+export const stateFile = () => STATE_FILE;
+
+/**
+ * Tabs left behind by dead sessions of this label. Cleanup can reap these
+ * deliberately; a live sibling's tabs are never in here.
+ */
+export function staleIds() {
+  const out = new Set();
+  for (const [id, entry] of Object.entries(readSessions())) {
+    if (!isDeadSession(id)) continue;
+    for (const tabId of entry.owned || []) {
+      if (!session.owned.has(tabId)) out.add(tabId);
+    }
+  }
+  return [...out];
+}
+
+/** Drop ids for tabs that no longer exist, so state does not grow forever. */
+export function reconcile(liveIds) {
+  const live = new Set(liveIds);
+  let changed = false;
+  for (const id of session.owned) {
+    if (!live.has(id)) {
+      session.owned.delete(id);
+      changed = true;
+    }
+  }
+  if (session.currentTabId && !live.has(session.currentTabId)) {
+    session.currentTabId = [...session.owned].pop() || null;
+    changed = true;
+  }
+  const vanished = new Set(staleIds().filter((id) => !live.has(id)));
+  if (changed || vanished.size > 0) persist(vanished);
+}

package/src/tools/content.js

@@ -0,0 +1,217 @@
+import { z, TAB_ID, SELECTOR, VERBOSE } from './schema.js';
+import { read, runPage } from './shared.js';
+
+const DEFAULT_MAX_CHARS = 20000;
+const DEFAULT_ELEMENT_LIMIT = 40;
+const DEFAULT_LINK_LIMIT = 100;
+
+// A blank line between joined element texts, so paragraph boundaries survive.
+const PARAGRAPH_GAP = '\n\n';
+// Cannot occur in an href or in visible text, so it is a safe key joiner.
+const DEDUPE_SEP = '\u0000';
+
+export const tools = [
+  {
+    name: 'get_page_content',
+    description:
+      'Get the visible text of a page, or of every element matching a selector joined with blank lines. Always reports "matched", so a partial answer is never silent. Nested matches repeat their text, so prefer a leaf-ish selector.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      selector: SELECTOR.optional(),
+      first_only: z.boolean().default(false).describe('Return only the first match instead of joining all of them'),
+      max_chars: z.number().default(DEFAULT_MAX_CHARS).describe('Truncate the joined text at this length')
+    }),
+    annotations: read('Get Page Content')
+  },
+  {
+    name: 'get_html',
+    description:
+      'Get the HTML of a page or element. Use when you need markup, attributes or structure rather than text. Returns one element only: it reports how many matched and takes nth to pick a different one.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      selector: SELECTOR.optional(),
+      nth: z.number().default(0).describe('Which match to return when several exist, 0-based'),
+      outer: z.boolean().default(true).describe('Include the element tag itself'),
+      max_chars: z.number().default(DEFAULT_MAX_CHARS).describe('Truncate at this length')
+    }),
+    annotations: read('Get HTML')
+  },
+  {
+    name: 'query_elements',
+    description:
+      'Find elements and return structured details: text, value, href, visibility, disabled state and attributes. The main way to see what is on a page before acting on it. "text=" matching is substring, with exact matches ranked first; pass exact to require an exact match.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      selector: SELECTOR,
+      limit: z.number().default(DEFAULT_ELEMENT_LIMIT).describe('Maximum elements to return'),
+      visible_only: z.boolean().default(false).describe('Skip hidden elements'),
+      exact: z.boolean().default(false).describe('For a "text=" selector, match the whole text rather than a substring'),
+      verbose: VERBOSE
+    }),
+    annotations: read('Query Elements')
+  },
+  {
+    name: 'get_links',
+    description:
+      'List links on the page with their text and resolved href. Pass unique to collapse repeated href and text pairs, which navigation and footers produce in bulk.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      query: z.string().optional().describe('Case-insensitive substring matched against link text and href'),
+      unique: z.boolean().default(false).describe('Collapse links with an identical href and text, reporting how many were dropped'),
+      limit: z.number().default(DEFAULT_LINK_LIMIT).describe('Maximum links to return')
+    }),
+    annotations: read('Get Links')
+  },
+  {
+    name: 'get_page_info',
+    description: 'Page overview: title, url, ready state, meta description, headings, form and frame counts. Cheap orientation before deciding what to do.',
+    input: z.object({ tab_id: TAB_ID.optional() }),
+    annotations: read('Get Page Info')
+  }
+];
+
+export const handlers = {
+  get_page_content: async (args) => {
+    const limit = args.max_chars ?? DEFAULT_MAX_CHARS;
+    const firstOnly = args.first_only === true;
+    const { result, tab } = await runPage(
+      args,
+      `var sel = ${JSON.stringify(args.selector || null)};
+       var limit = ${limit};
+       // documentElement covers a document whose body has not parsed yet.
+       var els = sel ? A.all(sel) : [document.body || document.documentElement];
+       if (!els.length) return A.miss(sel);
+       var take = ${firstOnly} ? 1 : els.length;
+       var parts = [];
+       for (var i = 0; i < els.length && parts.length < take; i++) parts.push(els[i].innerText || '');
+       var text = parts.join(${JSON.stringify(PARAGRAPH_GAP)});
+       return {
+         text: text.slice(0, limit),
+         length: text.length,
+         truncated: text.length > limit,
+         matched: els.length,
+         returned: parts.length
+       };`
+    );
+    if (result?.error === 'no_match') return { error: `No element matches ${args.selector}`, tab };
+    if (firstOnly && result.matched > 1) {
+      const note = `first_only: this is 1 of ${result.matched} matches for "${args.selector}". Omit first_only to join them all.`;
+      return { ...result, note, tab };
+    }
+    return { ...result, tab };
+  },
+
+  get_html: async (args) => {
+    const limit = args.max_chars ?? DEFAULT_MAX_CHARS;
+    const nth = args.nth ?? 0;
+    const { result, tab } = await runPage(
+      args,
+      `var sel = ${JSON.stringify(args.selector || null)};
+       var limit = ${limit};
+       var els = sel ? A.all(sel) : [document.documentElement];
+       var el = els[${nth}];
+       if (!el) return { error: 'no_match', matched: els.length };
+       var html = ${args.outer === false ? 'el.innerHTML' : 'el.outerHTML'} || '';
+       return {
+         html: html.slice(0, limit),
+         length: html.length,
+         truncated: html.length > limit,
+         matched: els.length,
+         nth: ${nth}
+       };`
+    );
+    if (result?.error === 'no_match') {
+      // "nothing matched" and "nth is past the end" look alike to the page but
+      // need different fixes, so name which one happened.
+      const error = result.matched
+        ? `nth ${nth} is out of range: ${result.matched} element(s) match ${args.selector}`
+        : `No element matches ${args.selector}`;
+      return { error, matched: result.matched, tab };
+    }
+    if (result.matched > 1) {
+      const note = `${result.matched} elements match "${args.selector}" and this is nth ${nth}. Narrow the selector, or pass nth for another. Use get_page_content for the text of all of them.`;
+      return { ...result, note, tab };
+    }
+    return { ...result, tab };
+  },
+
+  query_elements: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var els = A.all(${JSON.stringify(args.selector)}, null, { exact: ${args.exact === true} });
+       var out = [];
+       for (var i = 0; i < els.length && out.length < ${args.limit ?? DEFAULT_ELEMENT_LIMIT}; i++) {
+         var d = A.describe(els[i], ${args.verbose === true});
+         if (${args.visible_only === true} && !d.visible) continue;
+         d.index = i;
+         out.push(d);
+       }
+       return { total: els.length, returned: out.length, elements: out };`
+    );
+    return { ...result, selector: args.selector, tab };
+  },
+
+  get_links: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var q = ${JSON.stringify((args.query || '').toLowerCase())};
+       var unique = ${args.unique === true};
+       var limit = ${args.limit ?? DEFAULT_LINK_LIMIT};
+       var links = document.querySelectorAll('a[href]');
+       var out = [];
+       var seen = {};
+       var matched = 0;
+       var collapsed = 0;
+       // Scans every anchor even once the limit is hit, so the counts describe
+       // the page rather than the first slice of it.
+       for (var i = 0; i < links.length; i++) {
+         var a = links[i];
+         var text = (a.innerText || a.getAttribute('aria-label') || '').trim();
+         var href = a.href;
+         if (q && (text + ' ' + href).toLowerCase().indexOf(q) === -1) continue;
+         matched++;
+         if (unique) {
+           var key = href + ${JSON.stringify(DEDUPE_SEP)} + text;
+           if (seen[key]) { collapsed++; continue; }
+           seen[key] = 1;
+         }
+         if (out.length >= limit) continue;
+         out.push({ text: text.slice(0, 200), href: href, visible: A.visible(a) });
+       }
+       return { total: links.length, matched: matched, collapsed: collapsed, returned: out.length, links: out };`
+    );
+    return { ...result, tab };
+  },
+
+  get_page_info: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `function meta(name) {
+         var m = document.querySelector('meta[name="' + name + '"], meta[property="og:' + name + '"]');
+         return m ? m.content : null;
+       }
+       var hs = [];
+       var nodes = document.querySelectorAll('h1,h2,h3');
+       for (var i = 0; i < nodes.length && hs.length < 30; i++) {
+         var t = (nodes[i].innerText || '').trim();
+         if (t) hs.push({ level: nodes[i].tagName.toLowerCase(), text: t.slice(0, 150) });
+       }
+       return {
+         title: document.title,
+         url: location.href,
+         ready: document.readyState,
+         description: meta('description'),
+         headings: hs,
+         counts: {
+           links: document.querySelectorAll('a[href]').length,
+           forms: document.forms.length,
+           inputs: document.querySelectorAll('input,textarea,select').length,
+           buttons: document.querySelectorAll('button,[role=button]').length,
+           iframes: document.querySelectorAll('iframe').length
+         },
+         textLength: (document.body ? document.body.innerText : '').length
+       };`
+    );
+    return { ...result, tab };
+  }
+};