arc-control-mcp 0.3.0

package/src/tools/interact.js

@@ -0,0 +1,321 @@
+import { ArcError } from '../jxa.js';
+import { z, TAB_ID, SELECTOR, VERBOSE, EXACT, NTH, timeoutMs, MAX_CALLER_TIMEOUT_MS } from './schema.js';
+import { write, read, runPage, sleep } from './shared.js';
+
+const POLL_MS = 250;
+const DEFAULT_WAIT_MS = 10000;
+// An MCP client abandons a request after 60s (the SDK's own default), and once
+// it does, the timedOut payload with waitedMs and the last counts is thrown
+// away. So a caller-supplied wait is capped well inside that ceiling, by the
+// MAX_CALLER_TIMEOUT_MS that schema.js holds for every waiting tool. Progress
+// notifications would not buy more time: a client MAY reset its clock on
+// progress and mostly does not.
+const DEFAULT_SCROLL_PX = 800;
+const MAX_OPTIONS_LISTED = 25;
+const TARGET_ATTR_CHARS = 80;
+
+// The shared exact flag, narrowed to the wording these tools have always
+// advertised: the "no effect on CSS selectors" half is what stops a model
+// passing it blind and then wondering why nothing changed.
+const MATCH_EXACT = EXACT.describe(
+  'For "text=" selectors, require the whole trimmed text to equal the label instead of containing it. No effect on CSS selectors.'
+);
+
+// Both are interpolated straight into page scripts, so they have to be literals.
+const matchOpts = (args) => JSON.stringify({ exact: args.exact === true });
+const verboseFlag = (args) => String(args.verbose === true);
+
+/**
+ * The spec asks a receiver of notifications/cancelled to stop work and release
+ * resources. Each poll spawns an osascript process against the user's Arc, so a
+ * loop that ignores the signal keeps prodding their browser for a result nobody
+ * will read. extra is absent when a handler is called internally, for instance
+ * by batch.
+ */
+function throwIfCancelled(extra) {
+  if (extra?.signal?.aborted) throw new ArcError('Cancelled by the caller.');
+}
+
+const TEXT_NOTE =
+  '"text=Label" matches on visible text as a substring, with exact matches ranked first, so a short label also matches longer ones. ' +
+  'Check the returned "matches" count, and pass exact when it is above 1.';
+
+export const tools = [
+  {
+    name: 'click',
+    description:
+      'Click an element. Accepts a CSS selector or "text=Label". Scrolls it into view and dispatches a real pointer sequence, so framework handlers fire. ' +
+      TEXT_NOTE +
+      ' Returns urlBefore, the url as it was immediately before the click: the tab snapshot can be taken before a navigation settles, so follow with wait_for_load when the click navigates.',
+    input: z.object({
+      selector: SELECTOR,
+      tab_id: TAB_ID.optional(),
+      nth: NTH.describe('Which match to click when several exist, 0-based. Order is exact text matches first, then substring matches, each in DOM order.'),
+      exact: MATCH_EXACT,
+      verbose: VERBOSE
+    }),
+    annotations: write('Click')
+  },
+  {
+    name: 'fill',
+    description:
+      'Set the value of an input, textarea or contenteditable. Uses the native setter and fires input and change, so React and similar frameworks register it. ' +
+      'Fails with an error naming the tag when the target cannot be filled: a heading or other non-input, a disabled or readonly field, or a <select> (use select_option for those). ' +
+      TEXT_NOTE,
+    input: z.object({
+      selector: SELECTOR,
+      value: z.string().describe('Value to set'),
+      tab_id: TAB_ID.optional(),
+      nth: NTH.describe('Which match to fill, 0-based'),
+      submit: z
+        .boolean()
+        .default(false)
+        .describe(
+          'Press Enter and request form submit afterwards. The tab usually navigates, so follow with wait_for_load: the returned tab snapshot may predate the navigation, and urlBefore reports the url from just before the key press.'
+        ),
+      exact: MATCH_EXACT,
+      verbose: VERBOSE
+    }),
+    annotations: write('Fill Field')
+  },
+  {
+    name: 'select_option',
+    description:
+      'Choose an option in a select element, by exact option value or exact visible label. ' +
+      'When nothing matches, the failure lists the options that do exist, so the next call can pick a real one.',
+    input: z.object({
+      selector: SELECTOR.describe('CSS selector for the <select>. "text=" cannot reach a select element, so use a CSS selector here.'),
+      option: z.string().describe('Option value or visible text, matched exactly after trimming'),
+      tab_id: TAB_ID.optional()
+    }),
+    annotations: write('Select Option')
+  },
+  {
+    name: 'press_key',
+    description:
+      'Dispatch a key press to an element, or to the focused element when no selector is given. Handles named keys (Enter, Escape, Tab, ArrowDown) and single printable characters. ' +
+      'Returns only a minimal identity for the element that received the key (tag plus whichever of id, name, type and aria-label exist); use query_elements when you need the full picture.',
+    input: z.object({
+      key: z.string().describe('Key name, for example Enter, Escape, Tab, ArrowDown, or a single printable character'),
+      selector: SELECTOR.optional(),
+      tab_id: TAB_ID.optional(),
+      exact: MATCH_EXACT
+    }),
+    annotations: write('Press Key')
+  },
+  {
+    name: 'scroll',
+    description: 'Scroll the page, or scroll an element into view. Page scrolls report scrollY, pageHeight and viewport, so you can tell how much is left.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      selector: SELECTOR.describe(
+        'Scroll this element into view instead of scrolling the page. CSS selector, or "text=Label" (substring, exact matches ranked first).'
+      ).optional(),
+      direction: z.enum(['down', 'up', 'top', 'bottom']).default('down').describe('Page scroll direction'),
+      amount: z.number().default(DEFAULT_SCROLL_PX).describe('Pixels to scroll for up and down'),
+      exact: MATCH_EXACT,
+      verbose: VERBOSE
+    }),
+    annotations: write('Scroll', { idempotent: true })
+  },
+  {
+    name: 'wait_for_selector',
+    description:
+      'Poll until an element appears, becomes visible, or disappears. Use after a click that loads content. ' +
+      'On timeout it says so explicitly with waitedMs and the last counts, and a broken selector or page error fails straight away instead of burning the whole timeout. ' +
+      'The visible state ignores screen-reader clipping (boxes under 2x2 px, inset clip-path), which nothing can actually click.',
+    input: z.object({
+      selector: SELECTOR,
+      tab_id: TAB_ID.optional(),
+      state: z.enum(['present', 'visible', 'absent']).default('visible').describe('Condition to wait for'),
+      timeout_ms: timeoutMs(DEFAULT_WAIT_MS, 'Give up after this long. Every call returns the current counts, so repeated short waits tell you more than one long one.'),
+      exact: MATCH_EXACT,
+      verbose: VERBOSE
+    }),
+    annotations: read('Wait For Selector')
+  }
+];
+
+export const handlers = {
+  click: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var els = A.all(${JSON.stringify(args.selector)}, null, ${matchOpts(args)});
+       var el = els[${args.nth ?? 0}];
+       if (!el) return { error: 'no_match', matches: els.length };
+       var before = location.href;
+       A.click(el);
+       return { clicked: A.describe(el, ${verboseFlag(args)}), matches: els.length, urlBefore: before };`
+    );
+    if (result?.error === 'no_match') {
+      return { ok: false, error: `No element matches ${args.selector}`, matches: result.matches, tab };
+    }
+    return { ok: true, ...result, tab };
+  },
+
+  // A.setValue throws for anything unfillable and runPage turns that into an
+  // ArcError naming the tag, so there is deliberately no catch here: only a
+  // genuinely absent selector gets the soft failure below.
+  fill: async (args) => {
+    const submit = args.submit === true;
+    const { result, tab } = await runPage(
+      args,
+      `var els = A.all(${JSON.stringify(args.selector)}, null, ${matchOpts(args)});
+       var el = els[${args.nth ?? 0}];
+       if (!el) return { error: 'no_match', matches: els.length };
+       A.setValue(el, ${JSON.stringify(args.value)});
+       // Describe before submitting, so filled.value shows what landed even if
+       // the form resets or navigates.
+       var out = { filled: A.describe(el, ${verboseFlag(args)}), matches: els.length };
+       ${submit
+         ? `out.urlBefore = location.href;
+       A.key(el, 'Enter');
+       if (el.form && el.form.requestSubmit) { try { el.form.requestSubmit(); } catch (e) {} }`
+         : ''}
+       return out;`
+    );
+    if (result?.error === 'no_match') {
+      return { ok: false, error: `No element matches ${args.selector}`, matches: result.matches, tab };
+    }
+    if (submit) {
+      return { ok: true, ...result, submitted: true, note: 'The tab may still be navigating. Call wait_for_load before reading the page.', tab };
+    }
+    return { ok: true, ...result, tab };
+  },
+
+  select_option: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var el = A.one(${JSON.stringify(args.selector)});
+       if (!el) return { error: 'no_match' };
+       var tag = el.tagName.toLowerCase();
+       if (tag !== 'select') return { error: 'not_select', tag: tag };
+       var want = ${JSON.stringify(args.option)};
+       var chosen = null;
+       for (var i = 0; i < el.options.length; i++) {
+         var o = el.options[i];
+         if (o.value === want || (o.text || '').trim() === want) {
+           el.selectedIndex = i;
+           chosen = { value: o.value, text: (o.text || '').trim() };
+           break;
+         }
+       }
+       if (!chosen) {
+         // Listing what is there turns a dead end into a recoverable next call.
+         var available = [];
+         for (var j = 0; j < el.options.length && j < ${MAX_OPTIONS_LISTED}; j++) {
+           available.push({ value: el.options[j].value, text: (el.options[j].text || '').trim() });
+         }
+         return { error: 'no_option', available: available, total: el.options.length };
+       }
+       el.dispatchEvent(new Event('input', { bubbles: true }));
+       el.dispatchEvent(new Event('change', { bubbles: true }));
+       return { selected: chosen };`
+    );
+    if (result?.error === 'no_match') return { ok: false, error: `No element matches ${args.selector}`, tab };
+    if (result?.error === 'not_select') {
+      return {
+        ok: false,
+        error: `Selector ${args.selector} resolves to <${result.tag}>, not <select>. Use fill for a text input, or click for a custom dropdown.`,
+        tab
+      };
+    }
+    if (result?.error === 'no_option') {
+      return {
+        ok: false,
+        error: `No option in ${args.selector} has the value or visible text "${args.option}". Pick one from available, which lists ${result.available.length} of the ${result.total} real options with their value and text.`,
+        available: result.available,
+        total: result.total,
+        tab
+      };
+    }
+    return { ok: true, ...result, tab };
+  },
+
+  press_key: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var sel = ${JSON.stringify(args.selector || null)};
+       var el = sel ? A.one(sel, 0, ${matchOpts(args)}) : (document.activeElement || document.body);
+       if (!el) return { error: 'no_match' };
+       A.key(el, ${JSON.stringify(args.key)});
+       // Identity only: a full describe of a fallback document.body would drag
+       // the page's entire innerText into the response.
+       var target = { tag: el.tagName.toLowerCase() };
+       var names = ['id', 'name', 'type', 'aria-label'];
+       for (var i = 0; i < names.length; i++) {
+         var v = el.getAttribute(names[i]);
+         if (v) target[names[i]] = v.slice(0, ${TARGET_ATTR_CHARS});
+       }
+       return { key: ${JSON.stringify(args.key)}, target: target, usedFocusedElement: !sel };`
+    );
+    if (result?.error === 'no_match') {
+      // Without a selector the miss means the document had nothing to aim at.
+      const why = args.selector
+        ? `No element matches ${args.selector}`
+        : 'The page has no focused element and no body to fall back to.';
+      return { ok: false, error: why, tab };
+    }
+    return { ok: true, ...result, tab };
+  },
+
+  scroll: async (args) => {
+    const { result, tab } = await runPage(
+      args,
+      `var sel = ${JSON.stringify(args.selector || null)};
+       if (sel) {
+         var el = A.one(sel, 0, ${matchOpts(args)});
+         if (!el) return { error: 'no_match' };
+         el.scrollIntoView({ block: 'center' });
+         return { scrolledTo: A.describe(el, ${verboseFlag(args)}) };
+       }
+       var dir = ${JSON.stringify(args.direction || 'down')};
+       var amount = ${args.amount ?? DEFAULT_SCROLL_PX};
+       if (dir === 'top') window.scrollTo(0, 0);
+       else if (dir === 'bottom') window.scrollTo(0, document.body.scrollHeight);
+       else window.scrollBy(0, dir === 'up' ? -amount : amount);
+       return { scrollY: window.scrollY, pageHeight: document.body.scrollHeight, viewport: window.innerHeight };`
+    );
+    if (result?.error === 'no_match') return { ok: false, error: `No element matches ${args.selector}`, tab };
+    return { ok: true, ...result, tab };
+  },
+
+  // runPage throws on a page-script failure, and that is left to propagate: a
+  // bad selector is a bad selector on every poll, so retrying it to the
+  // deadline would only turn a clear error into a vague timeout.
+  wait_for_selector: async (args, extra) => {
+    const timeout = Math.min(args.timeout_ms ?? DEFAULT_WAIT_MS, MAX_CALLER_TIMEOUT_MS);
+    const want = args.state || 'visible';
+    const started = Date.now();
+    let last = null;
+
+    while (Date.now() - started < timeout) {
+      throwIfCancelled(extra);
+      const { result, tab } = await runPage(
+        args,
+        `var els = A.all(${JSON.stringify(args.selector)}, null, ${matchOpts(args)});
+         var vis = 0;
+         for (var i = 0; i < els.length; i++) if (A.visible(els[i])) vis++;
+         return { count: els.length, visible: vis, first: els[0] ? A.describe(els[0], ${verboseFlag(args)}) : null };`,
+        // Bound the probe by what is left, so a wedged call cannot push the
+        // tool past the client's timeout.
+        Math.max(timeout - (Date.now() - started), 1500)
+      );
+      last = { ...result, tab };
+      const done =
+        (want === 'present' && result.count > 0) ||
+        (want === 'visible' && result.visible > 0) ||
+        (want === 'absent' && result.count === 0);
+      if (done) return { ok: true, state: want, waitedMs: Date.now() - started, ...last };
+      await sleep(POLL_MS);
+    }
+    return {
+      ok: false,
+      timedOut: true,
+      state: want,
+      waitedMs: Date.now() - started,
+      ...last,
+      note: `Selector "${args.selector}" was not ${want} within ${timeout}ms.`
+    };
+  }
+};

package/src/tools/navigation.js

@@ -0,0 +1,302 @@
+import { ArcError } from '../jxa.js';
+import { z, TAB_ID, timeoutMs, MAX_CALLER_TIMEOUT_MS } from './schema.js';
+import { read, write, runTab, runPage, sleep, state } from './shared.js';
+
+const POLL_MS = 250;
+const LOAD_TIMEOUT_MS = 15000;
+// An MCP client gives up on a request after 60s (the SDK's own default), and a
+// call that outlives that loses its result: the caller sees RequestTimeout
+// instead of the tab that opened fine, or the timedOut payload that explains
+// what the page was doing. So open_url's launch budget plus the longest load
+// wait it can be asked for has to stay clearly inside 60s. Progress
+// notifications do not help: a client MAY reset its clock on progress and
+// mostly does not, so the budget itself is the fix. The ceiling on that wait is
+// MAX_CALLER_TIMEOUT_MS, which schema.js holds for every waiting tool.
+const OPEN_TIMEOUT_MS = 25000;
+// A back, forward or reload commits in well under a second. Giving the move
+// check a short budget of its own means "there is no entry that way" answers
+// quickly instead of burning the whole load timeout on a tab that never moved.
+const MOVE_TIMEOUT_MS = 5000;
+
+// Every caller-supplied wait goes through here, so no argument can push a call
+// past the client's deadline.
+const loadTimeout = (args) => Math.min(args.timeout_ms ?? LOAD_TIMEOUT_MS, MAX_CALLER_TIMEOUT_MS);
+
+// Capped so a missing history entry answers fast, but never longer than the
+// caller asked to wait in total.
+const moveTimeout = (args) => Math.min(loadTimeout(args), MOVE_TIMEOUT_MS);
+
+// Every tool here navigates, so they all take the same waiting controls.
+const WAIT_OPTIONS = {
+  wait_until_loaded: z.boolean().default(true).describe('Wait for the page to finish loading before returning'),
+  timeout_ms: timeoutMs(LOAD_TIMEOUT_MS, 'How long to wait for loading.')
+};
+
+/**
+ * The spec asks a receiver of notifications/cancelled to stop work and release
+ * resources. Every poll here spawns an osascript process against the user's
+ * Arc, so a loop that ignores the signal keeps prodding their browser for a
+ * result nobody will read. extra is absent when a handler is called internally,
+ * for instance by batch.
+ */
+function throwIfCancelled(extra) {
+  if (extra?.signal?.aborted) throw new ArcError('Cancelled by the caller.');
+}
+
+function parseUrl(url) {
+  try {
+    return new URL(url);
+  } catch {
+    throw new ArcError(`Not a valid URL: ${url}. Include a scheme, for example https://`);
+  }
+}
+
+export const tools = [
+  {
+    name: 'open_url',
+    description: 'Open a URL in Arc. Launches Arc if needed. New tabs go into the agent space when one exists, otherwise the main window. Arc auto-selects new tabs, so the previous selection is put back unless you pass activate.',
+    input: z.object({
+      url: z.string().describe('URL to open'),
+      new_tab: z.boolean().default(true).describe('Open a new tab. Set false to navigate an existing tab instead.'),
+      tab_id: TAB_ID.describe('With new_tab false, the tab to navigate. Required in that mode unless this agent already has a tab of its own, since navigating the tab the user is looking at is refused.').optional(),
+      space: z.string().describe('Space id or title to open into, overriding the agent space').optional(),
+      little_arc: z.boolean().default(false).describe('Open a Little Arc window. Fire and forget: Arc does not expose these afterwards.'),
+      activate: z.boolean().default(false).describe('Bring Arc to the front and leave the new tab selected'),
+      ...WAIT_OPTIONS
+    }),
+    annotations: write('Open URL')
+  },
+  {
+    name: 'go_back',
+    description: "Navigate a tab back in history. Goes through the page, so it works on a background tab, which Arc's own back command does not, and the result is checked against the tab url rather than assumed.",
+    input: z.object({ tab_id: TAB_ID.optional(), ...WAIT_OPTIONS }),
+    annotations: write('Go Back')
+  },
+  {
+    name: 'go_forward',
+    description: 'Navigate a tab forward in history. Goes through the page and confirms the tab really moved before reporting success.',
+    input: z.object({ tab_id: TAB_ID.optional(), ...WAIT_OPTIONS }),
+    annotations: write('Go Forward')
+  },
+  {
+    name: 'reload_tab',
+    description:
+      'Reload a tab, then confirm the document really was replaced rather than assume it. Works on a background tab. ' +
+      'Takes wait_until_loaded and timeout_ms like the other navigating tools, and returns from, to and the tab. ' +
+      'Fails with ok false when the tab is still showing the document that was there before, which is what a slow server or a page holding on to unload looks like from outside.',
+    input: z.object({ tab_id: TAB_ID.optional(), ...WAIT_OPTIONS }),
+    annotations: write('Reload Tab', { idempotent: true })
+  },
+  {
+    name: 'wait_for_load',
+    description: 'Poll until a tab has finished loading and the document is ready. Use after an action that triggers navigation.',
+    input: z.object({
+      tab_id: TAB_ID.optional(),
+      timeout_ms: timeoutMs(LOAD_TIMEOUT_MS, 'Give up after this long.'),
+      url_contains: z.string().describe('Also wait until the url contains this substring').optional()
+    }),
+    annotations: read('Wait For Load')
+  }
+];
+
+// A single osascript call must not outlive the wait it belongs to, or one
+// wedged call started near the deadline stretches the whole tool past the
+// client's timeout. Keep a floor so the last poll is still able to answer.
+const MIN_PROBE_MS = 1500;
+const probeBudget = (started, timeout) => Math.max(timeout - (Date.now() - started), MIN_PROBE_MS);
+
+async function readyState(args, remainingMs) {
+  // timeOrigin identifies the document instance, which is how reload_tab tells
+  // a fresh page from the one it asked Arc to replace.
+  const { result, tab } = await runPage(
+    args,
+    `return { ready: document.readyState, url: location.href, origin: performance.timeOrigin };`,
+    remainingMs
+  );
+  return { ...result, tab };
+}
+
+/**
+ * The one polling loop behind every "has the tab actually moved" question.
+ * `settled` vetoes readings until the navigation is real, and `requireReady` is
+ * off for callers that only care that the move happened, not that it finished.
+ */
+async function waitForLoad(args, { settled, requireReady = true, extra } = {}) {
+  const timeout = loadTimeout(args);
+  const started = Date.now();
+  let last = null;
+  while (Date.now() - started < timeout) {
+    throwIfCancelled(extra);
+    last = await readyState(args, probeBudget(started, timeout));
+    const urlOk = !args.url_contains || (last.url || '').includes(args.url_contains);
+    const isReady = !requireReady || last.ready === 'complete';
+    if (isReady && urlOk && (!settled || settled(last))) {
+      return { ok: true, ready: last.ready, url: last.url, tab: last.tab, waitedMs: Date.now() - started };
+    }
+    await sleep(POLL_MS);
+  }
+  return {
+    ok: false,
+    timedOut: true,
+    ready: last?.ready ?? null,
+    url: last?.url ?? null,
+    tab: last?.tab ?? null,
+    waitedMs: Date.now() - started,
+    note: `Still not ready after ${timeout}ms. The page may be slow, or blocked on a login or dialog.`
+  };
+}
+
+/**
+ * Optional wait for the new document, shared by all four navigating tools. A
+ * load timeout does not undo the navigation, so ok stays as the caller set it
+ * and the note is what warns that the content may only be half there.
+ */
+async function withLoad(args, result, extra) {
+  if (!result.tab || args.wait_until_loaded === false) return result;
+
+  const timeout = loadTimeout(args);
+  const loaded = await waitForLoad({ tab_id: result.tab.id, timeout_ms: timeout }, { extra });
+  const out = { ...result, loaded: loaded.ok, ready: loaded.ready, tab: loaded.tab ?? result.tab };
+  // A redirect can move the tab on again after the first url change, so keep
+  // the reported destination in step with the final snapshot.
+  if (result.to !== undefined && out.tab) out.to = out.tab.url;
+  if (!loaded.ok) {
+    out.note = `The tab did not finish loading within ${timeout}ms (readyState ${loaded.ready ?? 'unknown'}), so its content may be incomplete. Call wait_for_load to keep waiting, or read the page again afterwards.`;
+  }
+  return out;
+}
+
+// Arc's own goBack does nothing on a background tab, while goForward and reload
+// do work. Both directions go through the page instead, where history.back()
+// moves a background tab instantly.
+const historyStep = (direction) => {
+  const action = `went ${direction}`;
+  return async (args, extra) => {
+    const { result, tab } = await runPage(
+      args,
+      `var from = location.href;
+       if (history.length < 2) return { error: 'no_history', from: from, historyLength: history.length };
+       // Asynchronous: hand back the pre-move url and let Node confirm the move.
+       history.${direction}();
+       return { from: from, historyLength: history.length };`
+    );
+
+    const { from, historyLength } = result;
+    if (result.error === 'no_history') {
+      return {
+        ok: false,
+        action,
+        from,
+        historyLength,
+        note: `history.length is ${historyLength}, so this tab has nothing to go ${direction} to.`,
+        tab
+      };
+    }
+
+    const moved = await waitForLoad(
+      { tab_id: tab.id, timeout_ms: moveTimeout(args) },
+      { requireReady: false, settled: (reading) => reading.url !== from, extra }
+    );
+    if (!moved.ok) {
+      return {
+        ok: false,
+        action,
+        from,
+        historyLength,
+        note: `The tab is still at ${from} ${moved.waitedMs}ms later, so nothing moved. Most likely there is no ${direction} entry in this tab's history (history.length is ${historyLength}, which counts both directions). A trapped navigation, a page still in flight, or a ${direction} entry with the same url would look the same from here.`,
+        tab: moved.tab ?? tab
+      };
+    }
+
+    return withLoad(args, { ok: true, action, from, to: moved.url, historyLength, tab: moved.tab }, extra);
+  };
+};
+
+export const handlers = {
+  open_url: async (args, extra) => {
+    parseUrl(args.url);
+
+    const result = await runTab(
+      args,
+      `if (!Arc.running()) { Arc.launch(); delay(1.5); }
+       if (P.activate) Arc.activate();
+
+       if (P.little_arc) {
+         Arc.tabs.push(Arc.Tab({ url: P.url }));
+         JSON.stringify({ ok: true, action: "opened in Little Arc", url: P.url, tab: null });
+       } else if (P.new_tab === false) {
+         const tab = target();
+         tab.url = P.url;
+         delay(0.4);
+         JSON.stringify({ ok: true, action: "navigated existing tab", tab: describe(tab) });
+       } else {
+         requireArc();
+         const named = P.space ? findSpace(P.space) : null;
+         if (P.space && !named) throw new Error("SPACE_NOT_FOUND:" + P.space);
+         const space = named || agentSpace();
+         const container = space || mainWindow();
+         const openedIn = space ? space.title() : "main window";
+
+         let restoreId = null;
+         if (!P.activate) { try { restoreId = mainWindow().activeTab.id(); } catch (e) {} }
+
+         const tab = Arc.Tab({ url: P.url });
+         container.tabs.push(tab);
+         delay(0.6);
+         const info = describe(tab);
+
+         // Undo only Arc's own auto-select; if the user moved elsewhere meanwhile, leave them there.
+         let restored = false;
+         let stoleFocus = false;
+         try { stoleFocus = mainWindow().activeTab.id() === info.id; } catch (e) {}
+         if (stoleFocus && restoreId && restoreId !== info.id) {
+           const previous = locate(restoreId);
+           if (previous) { Arc.select(previous); delay(0.3); restored = true; }
+         }
+         JSON.stringify({ ok: true, action: "opened new tab", openedIn: openedIn, tab: info, restoredUserTab: restored });
+       }`,
+      OPEN_TIMEOUT_MS
+    );
+
+    if (result.tab) {
+      state.claim(result.tab.id);
+      result.tab.mine = true;
+    }
+
+    return withLoad(args, result, extra);
+  },
+
+  go_back: historyStep('back'),
+  go_forward: historyStep('forward'),
+
+  reload_tab: async (args, extra) => {
+    // Arc.reload is the one Arc history command verified to work on a
+    // background tab, and an in-page location.reload() would tear the document
+    // down before the envelope could get back out.
+    const { result, tab } = await runPage(args, `return { from: location.href, origin: performance.timeOrigin };`);
+    const { from, origin } = result;
+
+    await runTab({ ...args, tab_id: tab.id }, `Arc.reload(target()); JSON.stringify({ ok: true });`);
+
+    // A reload always builds a new document and every document gets its own
+    // timeOrigin. The navigation entry type stays "reload" for that document's
+    // whole life, so it cannot tell this reload from an earlier one.
+    const moved = await waitForLoad(
+      { tab_id: tab.id, timeout_ms: moveTimeout(args) },
+      { requireReady: false, settled: (reading) => reading.origin !== origin, extra }
+    );
+    if (!moved.ok) {
+      return {
+        ok: false,
+        action: 'reloaded',
+        from,
+        note: `Arc accepted the reload, but ${moved.waitedMs}ms on the tab is still showing the document that was there before it. A slow server may not have responded yet, or the page may be holding on to unload.`,
+        tab: moved.tab ?? tab
+      };
+    }
+
+    return withLoad(args, { ok: true, action: 'reloaded', from, to: moved.url, tab: moved.tab }, extra);
+  },
+
+  wait_for_load: (args, extra) => waitForLoad(args, { extra })
+};

package/src/tools/schema.js

@@ -0,0 +1,48 @@
+/**
+ * Zod input schemas. Zod is the single source of truth: the JSON Schema each
+ * tool advertises is generated from it in registry.js, and the same schema
+ * validates incoming arguments, so the two can never drift apart.
+ *
+ * Keep `z.number()` rather than `z.number().int()`. The int variant emits
+ * Number.MAX_SAFE_INTEGER bounds into the generated schema, which is noise in
+ * every tools/list response.
+ */
+import { z } from 'zod';
+
+export { z };
+
+/** A caller-supplied wait must stay well under a client's 60s request timeout. */
+export const MAX_CALLER_TIMEOUT_MS = 30000;
+
+export const TAB_ID = z
+  .string()
+  .describe("Arc tab id from list_tabs. Omit to use this agent's current tab. A tool that changes a tab will not fall back to the tab the user is looking at, so pass this or call open_url first.");
+
+export const SELECTOR = z
+  .string()
+  .describe('CSS selector, or "text=Some label" to match on visible text (case-insensitive substring, exact matches ranked first)');
+
+export const VERBOSE = z
+  .boolean()
+  .default(false)
+  .describe('Include the bulky element rect and longer attribute values');
+
+export const EXACT = z
+  .boolean()
+  .default(false)
+  .describe('For a "text=" selector, require the whole visible text to match rather than a substring');
+
+export const NTH = z
+  .number()
+  .default(0)
+  .describe('Which match to act on when several exist, 0-based');
+
+/** Every wait shares one ceiling, advertised so a client can see it up front. */
+export const timeoutMs = (defaultMs, note) =>
+  z
+    .number()
+    .max(MAX_CALLER_TIMEOUT_MS)
+    .default(defaultMs)
+    .describe(
+      `${note} Capped at ${MAX_CALLER_TIMEOUT_MS}ms so the call cannot outlive a client's request timeout. To wait longer, call this again.`
+    );