@humanjs/mcp 0.4.2 → 0.5.0

package/dist/index.js

@@ -71,6 +71,197 @@ function parseViewport(raw) {
   }
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+
+// src/observability.ts
+var RingBuffer = class {
+  constructor(limit) {
+    this.limit = limit;
+    if (limit < 1) throw new Error(`RingBuffer limit must be >= 1, got ${limit}`);
+  }
+  limit;
+  items = [];
+  droppedCount = 0;
+  push(item) {
+    this.items.push(item);
+    if (this.items.length > this.limit) {
+      this.items.shift();
+      this.droppedCount += 1;
+    }
+  }
+  toArray() {
+    return this.items;
+  }
+  /** Entries evicted because the buffer was full. */
+  get dropped() {
+    return this.droppedCount;
+  }
+  get size() {
+    return this.items.length;
+  }
+  clear() {
+    this.items = [];
+    this.droppedCount = 0;
+  }
+};
+var CONSOLE_BUFFER_LIMIT = 500;
+var NETWORK_BUFFER_LIMIT = 500;
+var ERROR_LEVELS = /* @__PURE__ */ new Set(["error", "pageerror"]);
+var MAX_PATTERN_LENGTH = 200;
+function compilePattern(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(
+      `\`pattern\` is ${pattern.length} characters; the limit is ${MAX_PATTERN_LENGTH}. Filter on something short and distinctive ("cors", "\\.png$") and narrow further with \`onlyErrors\`/\`status\` rather than one long alternation.`
+    );
+  }
+  try {
+    return new RegExp(pattern, "i");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Invalid \`pattern\` regular expression: ${detail}. Pass a valid JS regex (it is matched case-insensitively), or omit \`pattern\` to see everything.`
+    );
+  }
+}
+function queryConsole(buffer, query) {
+  const all = buffer.toArray();
+  const regex = query.pattern ? compilePattern(query.pattern) : null;
+  const matches = all.filter((entry) => {
+    if (query.onlyErrors && !ERROR_LEVELS.has(entry.level)) return false;
+    if (regex && !regex.test(entry.text)) return false;
+    return true;
+  });
+  return {
+    entries: takeLast(matches, query.limit),
+    matched: matches.length,
+    total: all.length,
+    dropped: buffer.dropped
+  };
+}
+function queryNetwork(buffer, query) {
+  const all = buffer.toArray();
+  const regex = query.pattern ? compilePattern(query.pattern) : null;
+  const matches = all.filter((entry) => {
+    if (query.onlyFailures && !isFailure(entry)) return false;
+    if (query.status !== void 0 && entry.status !== query.status) return false;
+    if (regex && !regex.test(entry.url)) return false;
+    return true;
+  });
+  return {
+    entries: takeLast(matches, query.limit),
+    matched: matches.length,
+    total: all.length,
+    dropped: buffer.dropped
+  };
+}
+function isFailure(entry) {
+  if (entry.failure !== null) return true;
+  return entry.status !== null && entry.status >= 400;
+}
+function takeLast(items, limit) {
+  if (limit === void 0 || items.length <= limit) return items;
+  return items.slice(items.length - limit);
+}
+function formatConsole(result) {
+  if (result.entries.length === 0) return emptyMessage("console messages", result);
+  const lines = result.entries.map((entry) => {
+    const where = entry.source ? `  (${entry.source})` : "";
+    return `[${entry.level}] ${entry.text}${where}`;
+  });
+  return [...lines, "", summary("message", result)].join("\n");
+}
+function formatNetwork(result) {
+  if (result.entries.length === 0) return emptyMessage("network requests", result);
+  const lines = result.entries.map((entry) => {
+    const status = entry.failure !== null ? `FAILED (${entry.failure})` : String(entry.status);
+    const timing = entry.ms === null ? "" : ` ${entry.ms}ms`;
+    return `${status} ${entry.method} ${entry.url} [${entry.resourceType}]${timing}`;
+  });
+  return [...lines, "", summary("request", result)].join("\n");
+}
+function emptyMessage(noun, result) {
+  if (result.total === 0 && result.dropped === 0) {
+    return `No ${noun} captured yet for this session.`;
+  }
+  const dropped = result.dropped > 0 ? ` ${result.dropped} older ${noun} were dropped from the buffer, so this is not proof they never happened.` : "";
+  return `No ${noun} matched the filter (${result.total} in the buffer).${dropped}`;
+}
+function summary(noun, result) {
+  const shown = result.entries.length < result.matched ? `showing the ${result.entries.length} most recent of ${result.matched} matching ${noun}s` : `${result.matched} matching ${noun}${result.matched === 1 ? "" : "s"}`;
+  const dropped = result.dropped > 0 ? `; ${result.dropped} older dropped (buffer full)` : "";
+  return `\u2014 ${shown} of ${result.total} captured${dropped}`;
+}
+function attachObservers(page) {
+  const consoleBuffer = new RingBuffer(CONSOLE_BUFFER_LIMIT);
+  const networkBuffer = new RingBuffer(NETWORK_BUFFER_LIMIT);
+  const startedAt = /* @__PURE__ */ new WeakMap();
+  const onConsole = (message) => {
+    const location = message.location();
+    const source = location.url ? `${location.url}:${location.lineNumber}:${location.columnNumber}` : null;
+    consoleBuffer.push({
+      level: message.type(),
+      text: message.text(),
+      source,
+      at: Date.now()
+    });
+  };
+  const onPageError = (error) => {
+    consoleBuffer.push({
+      level: "pageerror",
+      text: error.stack ?? `${error.name}: ${error.message}`,
+      source: null,
+      at: Date.now()
+    });
+  };
+  const onRequest = (request) => {
+    startedAt.set(request, Date.now());
+  };
+  const onResponse = (response) => {
+    const request = response.request();
+    const start = startedAt.get(request);
+    networkBuffer.push({
+      method: request.method(),
+      url: response.url(),
+      status: response.status(),
+      failure: null,
+      resourceType: request.resourceType(),
+      at: Date.now(),
+      ms: start === void 0 ? null : Date.now() - start
+    });
+  };
+  const onRequestFailed = (request) => {
+    const start = startedAt.get(request);
+    networkBuffer.push({
+      method: request.method(),
+      url: request.url(),
+      status: null,
+      failure: request.failure()?.errorText ?? "request failed",
+      resourceType: request.resourceType(),
+      at: Date.now(),
+      ms: start === void 0 ? null : Date.now() - start
+    });
+  };
+  page.on("console", onConsole);
+  page.on("pageerror", onPageError);
+  page.on("request", onRequest);
+  page.on("response", onResponse);
+  page.on("requestfailed", onRequestFailed);
+  let detached = false;
+  return {
+    console: consoleBuffer,
+    network: networkBuffer,
+    detach: () => {
+      if (detached) return;
+      detached = true;
+      page.off("console", onConsole);
+      page.off("pageerror", onPageError);
+      page.off("request", onRequest);
+      page.off("response", onResponse);
+      page.off("requestfailed", onRequestFailed);
+    }
+  };
+}
+
+// src/session.ts
 var DEFAULT_SESSION_ID = "default";
 var SessionManager = class {
   /** Backing browser for `ephemeral` and `cdp` modes. */
@@ -130,6 +321,7 @@ var SessionManager = class {
     const personality = options.personality ?? this.env.personality;
     const speed = options.speed ?? this.env.speed;
     const human = await createHuman(page, { personality, speed });
+    const observers = attachObservers(page);
     const session = {
       id,
       context,
@@ -139,6 +331,7 @@ var SessionManager = class {
       speed,
       mode: config.mode,
       recording: null,
+      observers,
       createdAt: Date.now()
     };
     this.sessions.set(id, session);
@@ -260,6 +453,7 @@ var SessionManager = class {
   async close(id) {
     const session = this.sessions.get(id);
     if (!session) return;
+    session.observers.detach();
     if (session.recording) {
       const rec = session.recording;
       session.recording = null;
@@ -517,6 +711,10 @@ function registerBrowserTools(server, { sessions }) {
   );
 }
 var preset = z.enum(["careful", "fast", "distracted", "precise"]);
+function toMediaValue(value) {
+  if (value === void 0) return void 0;
+  return value === "system" ? null : value;
+}
 function registerConfigTools(server, { sessions }) {
   server.registerTool(
     "human_set_personality",
@@ -580,6 +778,49 @@ function registerConfigTools(server, { sessions }) {
       return { content: [{ type: "text", text: `viewport set to ${width}\xD7${height}` }] };
     }
   );
+  server.registerTool(
+    "human_emulate_media",
+    {
+      title: "Emulate media features",
+      description: "Emulates CSS media features for a session so you can verify the accessibility and theming paths a real user would get. `reducedMotion: 'reduce'` is the important one: it is the only way to check that a site's prefers-reduced-motion path actually works, and it is normally impossible to test without changing OS settings. Settings persist across navigations until changed; pass 'system' to stop emulating a feature.",
+      inputSchema: {
+        reducedMotion: z.enum(["reduce", "no-preference", "system"]).optional().describe(
+          "Emulate prefers-reduced-motion. Use 'reduce' to verify the reduced-motion path renders and stays usable."
+        ),
+        colorScheme: z.enum(["light", "dark", "no-preference", "system"]).optional().describe("Emulate prefers-color-scheme, to check the light and dark themes."),
+        forcedColors: z.enum(["active", "none", "system"]).optional().describe(
+          "Emulate forced-colors (Windows High Contrast). 'active' reveals content that disappears when the author's colors are overridden."
+        ),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ reducedMotion, colorScheme, forcedColors, session }) => {
+      if (reducedMotion === void 0 && colorScheme === void 0 && forcedColors === void 0) {
+        throw new Error(
+          'Pass at least one of `reducedMotion`, `colorScheme` or `forcedColors`. Use "system" to stop emulating one.'
+        );
+      }
+      const { human } = await sessions.get(session);
+      await human.emulateMedia({
+        reducedMotion: toMediaValue(reducedMotion),
+        colorScheme: toMediaValue(colorScheme),
+        forcedColors: toMediaValue(forcedColors)
+      });
+      const applied = [
+        reducedMotion && `prefers-reduced-motion: ${reducedMotion}`,
+        colorScheme && `prefers-color-scheme: ${colorScheme}`,
+        forcedColors && `forced-colors: ${forcedColors}`
+      ].filter(Boolean);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `emulating ${applied.join(", ")} \u2014 re-render or navigate if the page only reads these at load`
+          }
+        ]
+      };
+    }
+  );
 }
 function resolveOutputPath(outputDir, filename) {
   const base = basename(filename);
@@ -609,8 +850,39 @@ function resolveRecordingFormat(filename) {
   return null;
 }
 
+// src/sweep.ts
+var TEXT_SWEEP_LIMIT = 100;
+var HTML_SWEEP_LIMIT = 10;
+var SWEEP_READ_TIMEOUT_MS = 2e3;
+async function sweepRead(elements, read) {
+  const settled = await Promise.allSettled(elements.map((element) => read(element)));
+  return settled.map(
+    (result) => result.status === "fulfilled" ? { ok: true, value: result.value } : { ok: false }
+  );
+}
+function sweepBody(readings, render, separator = "\n") {
+  return readings.map(
+    (reading, index) => reading.ok ? `[${index}] ${render(reading.value)}` : `[${index}] (unreadable \u2014 the page replaced this element mid-sweep)`
+  ).join(separator);
+}
+function sweepSummary(readings, total, selector) {
+  const shown = readings.length;
+  const unreadable = readings.filter((reading) => !reading.ok).length;
+  const head = shown >= total ? `\u2014 ${total} element${total === 1 ? "" : "s"} matched ${selector}` : `\u2014 showing the first ${shown} of ${total} elements matching ${selector}; raise \`limit\` to see more`;
+  if (unreadable === 0) return head;
+  return `${head}; ${unreadable} could not be read \u2014 re-run if you need ${unreadable === 1 ? "it" : "them"}`;
+}
+
 // src/tools/inspection.ts
 var sessionArg = z.string().optional().describe("Session ID to act on. Omit to use the default session.");
+var allArg = z.boolean().optional().describe(
+  "Read every element the selector matches instead of just the first. Use it to sweep a page \u2014 all image sources, all row labels, all link hrefs \u2014 in one call."
+);
+function matchLimitArg(fallback) {
+  return z.number().int().positive().optional().describe(
+    `With \`all\`, the maximum number of matches to return (default ${fallback}). The total number found is always reported.`
+  );
+}
 function registerInspectionTools(server, ctx) {
   server.registerTool(
     "human_screenshot",
@@ -631,7 +903,11 @@ function registerInspectionTools(server, ctx) {
     async ({ selector, fullPage, filename, session }) => {
       const { human, page } = await ctx.sessions.get(session);
       const buffer = selector ? await page.locator(selector).screenshot() : await human.screenshot({ fullPage: fullPage ?? false });
-      const content = [{ type: "image", data: buffer.toString("base64"), mimeType: "image/png" }];
+      const scope = selector ? `element ${selector}` : fullPage ? "full page" : "viewport";
+      const content = [
+        { type: "image", data: buffer.toString("base64"), mimeType: "image/png" },
+        { type: "text", text: `captured ${scope} of ${page.url()}` }
+      ];
       if (filename) {
         const path = resolveOutputPath(ctx.env.outputDir, filename);
         await writeFile(path, buffer);
@@ -673,15 +949,29 @@ function registerInspectionTools(server, ctx) {
     "human_get_text",
     {
       title: "Get an element's text",
-      description: "Returns the visible innerText of the first element matching `selector`. Use to read a specific label, price, status, or message.",
+      description: "Returns the innerText of the first element matching `selector` \u2014 a specific label, price, status, or message. Set `all` to read every match instead, e.g. every row's title in a table; a sweep reports each match in document order, including ones that are not currently visible.",
       inputSchema: {
         selector: z.string().describe("Selector of the element to read."),
+        all: allArg,
+        limit: matchLimitArg(TEXT_SWEEP_LIMIT),
         session: sessionArg
       }
     },
-    async ({ selector, session }) => {
+    async ({ selector, all, limit, session }) => {
       const { page } = await ctx.sessions.get(session);
-      const text = await page.locator(selector).innerText();
+      if (!all) {
+        const text2 = await page.locator(selector).first().innerText();
+        return { content: [{ type: "text", text: text2 }] };
+      }
+      const elements = await page.locator(selector).all();
+      const shown = elements.slice(0, limit ?? TEXT_SWEEP_LIMIT);
+      const readings = await sweepRead(
+        shown,
+        (element) => element.innerText({ timeout: SWEEP_READ_TIMEOUT_MS })
+      );
+      const text = elements.length === 0 ? `No elements matched ${selector}` : `${sweepBody(readings, (value) => value)}
+
+${sweepSummary(readings, elements.length, selector)}`;
       return { content: [{ type: "text", text }] };
     }
   );
@@ -689,17 +979,31 @@ function registerInspectionTools(server, ctx) {
     "human_get_attribute",
     {
       title: "Get an element's attribute",
-      description: "Returns the value of an attribute on the first element matching `selector` (or reports it is absent). Handy for reading aria-label, data-*, href, value, disabled state, etc. \u2014 often how you confirm an icon-only button's purpose.",
+      description: "Returns the value of an attribute on the first element matching `selector` (or reports it is absent). Handy for reading aria-label, data-*, href, value, disabled state, etc. \u2014 often how you confirm an icon-only button's purpose. Set `all` to collect the attribute across every match, which is the compact way to extract every image source or link target on a page.",
       inputSchema: {
         selector: z.string().describe("Selector of the element."),
         attribute: z.string().describe('Attribute name, e.g. "aria-label", "href", "data-state".'),
+        all: allArg,
+        limit: matchLimitArg(TEXT_SWEEP_LIMIT),
         session: sessionArg
       }
     },
-    async ({ selector, attribute, session }) => {
+    async ({ selector, attribute, all, limit, session }) => {
       const { page } = await ctx.sessions.get(session);
-      const value = await page.locator(selector).getAttribute(attribute);
-      const text = value === null ? `${selector} has no attribute "${attribute}"` : `${attribute}="${value}"`;
+      if (!all) {
+        const value = await page.locator(selector).first().getAttribute(attribute);
+        const text2 = value === null ? `${selector} has no attribute "${attribute}"` : `${attribute}="${value}"`;
+        return { content: [{ type: "text", text: text2 }] };
+      }
+      const elements = await page.locator(selector).all();
+      const shown = elements.slice(0, limit ?? TEXT_SWEEP_LIMIT);
+      const readings = await sweepRead(
+        shown,
+        (element) => element.getAttribute(attribute, { timeout: SWEEP_READ_TIMEOUT_MS })
+      );
+      const text = elements.length === 0 ? `No elements matched ${selector}` : `${sweepBody(readings, (value) => value ?? "(absent)")}
+
+${sweepSummary(readings, elements.length, selector)}`;
       return { content: [{ type: "text", text }] };
     }
   );
@@ -707,16 +1011,109 @@ function registerInspectionTools(server, ctx) {
     "human_get_html",
     {
       title: "Get an element's HTML",
-      description: "Returns the outerHTML of the first element matching `selector` \u2014 the element plus its children, including its own attributes (class, aria-label, etc.). The go-to tool for discovering the real selector of a control with no obvious text. Target a specific region; full-page HTML is large.",
+      description: "Returns the outerHTML of the first element matching `selector` \u2014 the element plus its children, including its own attributes (class, aria-label, etc.). The go-to tool for discovering the real selector of a control with no obvious text. Target a specific region; full-page HTML is large. Set `all` to dump every match, but prefer human_get_attribute with `all` when you only need one attribute from each \u2014 it returns the same information for a fraction of the tokens.",
       inputSchema: {
         selector: z.string().describe("Selector of the region to dump. Target narrowly."),
+        all: allArg,
+        limit: matchLimitArg(HTML_SWEEP_LIMIT),
         session: sessionArg
       }
     },
-    async ({ selector, session }) => {
+    async ({ selector, all, limit, session }) => {
       const { page } = await ctx.sessions.get(session);
-      const html = await page.locator(selector).evaluate((el) => el.outerHTML);
-      return { content: [{ type: "text", text: html }] };
+      if (!all) {
+        const html = await page.locator(selector).first().evaluate((el) => el.outerHTML);
+        return { content: [{ type: "text", text: html }] };
+      }
+      const elements = await page.locator(selector).all();
+      const shown = elements.slice(0, limit ?? HTML_SWEEP_LIMIT);
+      const readings = await sweepRead(
+        shown,
+        (element) => element.evaluate((el) => el.outerHTML, void 0, { timeout: SWEEP_READ_TIMEOUT_MS })
+      );
+      const text = elements.length === 0 ? `No elements matched ${selector}` : `${sweepBody(readings, (value) => value, "\n\n")}
+
+${sweepSummary(readings, elements.length, selector)}`;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+var sessionArg2 = z.string().optional().describe("Session ID to read from. Omit to use the default session.");
+var patternArg = z.string().optional().describe(
+  'Case-insensitive regular expression to filter by. Omit to see everything. Use it to cut noise on chatty pages, e.g. "cors|refused" or "\\\\.png$".'
+);
+var DEFAULT_LIMIT = 50;
+var limitArg = z.number().int().positive().optional().describe(
+  `Maximum entries to return, most recent first-in-list-last (default ${DEFAULT_LIMIT}). The count of everything that matched is always reported, so you can tell when you are seeing a slice.`
+);
+var clearArg = z.boolean().optional().describe(
+  "Empty the WHOLE buffer after this read \u2014 not only the entries returned, and not only the ones that matched your filter. Use it for a clean slate before an action, so the next call shows just what that action caused. How many entries it discarded is reported back."
+);
+function withClearNote(text, discarded) {
+  if (discarded === 0) return `${text}
+\u2014 buffer was already empty`;
+  return `${text}
+\u2014 buffer cleared, ${discarded} entr${discarded === 1 ? "y" : "ies"} discarded`;
+}
+function registerObservabilityTools(server, { sessions }) {
+  server.registerTool(
+    "human_console_messages",
+    {
+      title: "Read the browser console",
+      description: "Returns console output and uncaught page errors captured for this session, newest last. Capture starts when the session is created, so this covers everything since \u2014 including errors thrown during the first page load. The go-to tool when something looks wrong on the page but the screenshot doesn't explain why: CORS rejections, failed asset loads, and thrown exceptions all surface here and nowhere else.",
+      inputSchema: {
+        pattern: patternArg,
+        onlyErrors: z.boolean().optional().describe(
+          "Keep only console.error output and uncaught page errors, dropping log/info/warn/debug."
+        ),
+        limit: limitArg,
+        clear: clearArg,
+        session: sessionArg2
+      }
+    },
+    async ({ pattern, onlyErrors, limit, clear, session }) => {
+      const { observers } = await sessions.get(session);
+      const result = queryConsole(observers.console, {
+        pattern,
+        onlyErrors,
+        limit: limit ?? DEFAULT_LIMIT
+      });
+      const formatted = formatConsole(result);
+      const discarded = observers.console.size;
+      if (clear) observers.console.clear();
+      const text = clear ? withClearNote(formatted, discarded) : formatted;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "human_network_requests",
+    {
+      title: "Inspect network activity",
+      description: 'Returns network responses captured for this session, newest last, with method, URL, HTTP status and round-trip time. Requests that never got a response (DNS failure, blocked by CORS, aborted) are included with the browser\'s failure reason instead of a status. Use `onlyFailures` to answer "what broke?" in one call \u2014 it covers both 4xx/5xx responses and requests that never completed.',
+      inputSchema: {
+        pattern: patternArg,
+        onlyFailures: z.boolean().optional().describe(
+          "Keep only 4xx/5xx responses and requests that failed before responding. The fastest way to find a broken asset or API call."
+        ),
+        status: z.number().int().optional().describe("Keep only responses with this exact HTTP status, e.g. 404 or 500."),
+        limit: limitArg,
+        clear: clearArg,
+        session: sessionArg2
+      }
+    },
+    async ({ pattern, onlyFailures, status, limit, clear, session }) => {
+      const { observers } = await sessions.get(session);
+      const result = queryNetwork(observers.network, {
+        pattern,
+        onlyFailures,
+        status,
+        limit: limit ?? DEFAULT_LIMIT
+      });
+      const formatted = formatNetwork(result);
+      const discarded = observers.network.size;
+      if (clear) observers.network.clear();
+      const text = clear ? withClearNote(formatted, discarded) : formatted;
+      return { content: [{ type: "text", text }] };
     }
   );
 }
@@ -744,7 +1141,7 @@ function resolveTarget(input) {
 }
 
 // src/tools/primitives.ts
-var sessionArg2 = z.string().optional().describe(
+var sessionArg3 = z.string().optional().describe(
   "Session ID to act on. Omit to use the default session (created lazily on first call). Use human_create_session for parallel browsers."
 );
 function registerPrimitiveTools(server, { sessions, env }) {
@@ -755,7 +1152,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: `Navigates the session's page to a URL. Plugins observe a "goto" action. Equivalent to a user typing a URL in the address bar.`,
       inputSchema: {
         url: z.string().url().describe("Absolute URL to navigate to."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ url, session }) => {
@@ -769,7 +1166,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
     {
       title: "Click (humanized)",
       description: "Moves the cursor to the target along a humanized Bezier path and clicks. Target is a selector OR x/y coordinates \u2014 use coordinates for icon-only buttons or anything with no clean selector that you can see in a screenshot.",
-      inputSchema: { ...targetFields, session: sessionArg2 }
+      inputSchema: { ...targetFields, session: sessionArg3 }
     },
     async ({ selector, x, y, session }) => {
       const { human } = await sessions.get(session);
@@ -783,7 +1180,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
     {
       title: "Right-click (humanized)",
       description: "Right-clicks the target to open a context menu. Same motion as human_click; only the dispatched button differs. Target is a selector OR x/y coordinates.",
-      inputSchema: { ...targetFields, session: sessionArg2 }
+      inputSchema: { ...targetFields, session: sessionArg3 }
     },
     async ({ selector, x, y, session }) => {
       const { human } = await sessions.get(session);
@@ -799,7 +1196,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
     {
       title: "Double-click (humanized)",
       description: "Double-clicks the target \u2014 same humanized motion as human_click, but two presses within the OS double-click window. Use for things that open/activate on double-click (list rows, file items, editable cells). Target is a selector OR x/y coordinates.",
-      inputSchema: { ...targetFields, session: sessionArg2 }
+      inputSchema: { ...targetFields, session: sessionArg3 }
     },
     async ({ selector, x, y, session }) => {
       const { human } = await sessions.get(session);
@@ -817,7 +1214,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: "Moves the cursor to an element and settles on it (no click), letting hover-triggered UI fire \u2014 tooltips, dropdowns. Element-bound only; for positioning the cursor at coordinates without an element, use human_move.",
       inputSchema: {
         selector: z.string().describe("Selector of the element to hover."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, session }) => {
@@ -831,7 +1228,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
     {
       title: "Move the cursor (humanized)",
       description: "Moves the cursor to a target along a Bezier path with no click and no settle dwell \u2014 pure positioning. Useful before a keyboard action, for canvas work, or cinematic beats. Target is a selector OR x/y coordinates.",
-      inputSchema: { ...targetFields, session: sessionArg2 }
+      inputSchema: { ...targetFields, session: sessionArg3 }
     },
     async ({ selector, x, y, session }) => {
       const { human } = await sessions.get(session);
@@ -852,7 +1249,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
         toSelector: z.string().optional().describe("Destination selector. Provide this OR toX/toY."),
         toX: z.number().optional().describe("Destination X coordinate. Requires toY."),
         toY: z.number().optional().describe("Destination Y coordinate. Requires toX."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ fromSelector, fromX, fromY, toSelector, toX, toY, session }) => {
@@ -878,7 +1275,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       inputSchema: {
         selector: z.string().describe("Selector of the input/textarea/contenteditable."),
         value: z.string().describe("Text to type. May contain newlines."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, value, session }) => {
@@ -895,7 +1292,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       inputSchema: {
         selector: z.string().describe("Selector of the field to paste into."),
         value: z.string().describe("Text to insert."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, value, session }) => {
@@ -911,7 +1308,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: "Clears a text field (input/textarea/contenteditable) with a real keyboard gesture \u2014 click to focus, select-all, then delete \u2014 firing the input events the page expects. Use before human_type when you need to replace an existing value rather than append to it.",
       inputSchema: {
         selector: z.string().describe("Selector of the field to clear."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, session }) => {
@@ -928,7 +1325,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       inputSchema: {
         selector: z.string().describe("Selector of the element whose text to select."),
         text: z.string().optional().describe("Optional substring to select instead of the element\u2019s whole text."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, text, session }) => {
@@ -945,7 +1342,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: "Ticks a checkbox or radio \u2014 moves the cursor to it and clicks, but only if it is not already checked (a real user does not re-click a ticked box). Verifies the resulting state. Pass the checkbox/radio input itself (or a [role=checkbox]) \u2014 not a wrapping <label> \u2014 so the current state can be read and the click stays idempotent.",
       inputSchema: {
         selector: z.string().describe("Selector of the checkbox/radio input."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, session }) => {
@@ -961,7 +1358,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: "Unticks a checkbox \u2014 humanized click only if currently checked. Radios cannot be unchecked by clicking (select a different option instead). Pass the checkbox input itself (or a [role=checkbox]) \u2014 not a wrapping <label> \u2014 so its state can be read and the click stays idempotent.",
       inputSchema: {
         selector: z.string().describe("Selector of the checkbox input."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, session }) => {
@@ -978,7 +1375,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       inputSchema: {
         selector: z.string().describe("Selector of the <select> element."),
         values: z.union([z.string(), z.array(z.string())]).describe("Option value, or array of values for a multi-select."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, values, session }) => {
@@ -997,7 +1394,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       inputSchema: {
         selector: z.string().describe("Selector of the file input."),
         files: z.union([z.string(), z.array(z.string())]).describe("Filename(s) inside HUMANJS_UPLOAD_DIR \u2014 a basename only, no path components."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, files, session }) => {
@@ -1017,7 +1414,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
       description: 'Presses a single key (Enter, Tab, Escape, ArrowDown, \u2026) or a chord (Mod+S, Cmd+Shift+P, Ctrl+C). "Mod" maps to Meta on Mac and Control elsewhere. Dispatches against focus \u2014 does not move the cursor; compose with human_click/human_move when you need both.',
       inputSchema: {
         key: z.string().describe('Key or chord, e.g. "Enter", "Tab", "Mod+S", "Ctrl+Shift+K".'),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ key, session }) => {
@@ -1039,7 +1436,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
         to: z.number().optional().describe("Absolute scroll position on the chosen axis."),
         axis: z.enum(["x", "y"]).optional().describe('Axis to scroll. Defaults to "y".'),
         within: z.string().optional().describe("Selector of a scrollable container to scope the scroll to."),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ target, by, to, axis, within, session }) => {
@@ -1062,7 +1459,7 @@ function registerPrimitiveTools(server, { sessions, env }) {
         selector: z.string().optional().describe("Selector of the text to read. Provide this OR text."),
         text: z.string().optional().describe('Literal text to "read" (no DOM lookup). Provide this OR selector.'),
         kind: z.enum(["prose", "code", "scan"]).optional().describe('Reading style. Auto-detected as "code" for <pre>/<code> when omitted.'),
-        session: sessionArg2
+        session: sessionArg3
       }
     },
     async ({ selector, text, kind, session }) => {
@@ -1226,6 +1623,12 @@ Export as a test: human_stop_recording picks format by extension. A .spec.ts (or
 
 Captured input + passwords: typed/pasted text IS recorded into the timeline and code exports, so generated scripts/tests are runnable \u2014 EXCEPT password fields, which are always masked (emitted as an empty string with a "fill in" comment). This is intentional, not a bug; don't work around it by hand-editing the secret back in. If the user explicitly wants the flow to log in, edit the exported file to read the credential from an env var (e.g. process.env.APP_PASSWORD) and tell them to set it \u2014 never hardcode a real password into a file that may be committed.
 
+When something looks wrong and the screenshot doesn't explain it, read human_console_messages (onlyErrors: true) and human_network_requests (onlyFailures: true) before guessing. A CORS rejection, a 404 on an image, or an uncaught TypeError appears in neither the screenshot nor the page text \u2014 those two tools are the only place it shows up. Capture is always on, so you can act first and check afterwards. Do NOT reach for curl to debug a page: a request made outside the browser carries none of its origin, cookies, or headers, so the failure you are chasing won't reproduce.
+
+Accessibility and theming: human_emulate_media sets prefers-reduced-motion, prefers-color-scheme and forced-colors. Use reducedMotion: 'reduce' to verify a reduced-motion path \u2014 it is otherwise untestable without changing OS settings.
+
+Reading many elements at once: human_get_text, human_get_attribute and human_get_html take all: true to return every match instead of the first. For "every image source" or "every link target", human_get_attribute with all is far cheaper than dumping HTML.
+
 Dynamic UI: prefer specific selectors (role, aria-label) over text \u2014 the same visible text often matches several cards before a filter, or the wrong one after. If a click reports multiple matches, narrow the selector.
 
 Browser state: by default each run is a fresh, signed-out browser. If a flow needs a login, tell the user to enable persistence (human_enable_persistence or HUMANJS_PERSIST) or CDP attach \u2014 see human_browser_info.`;
@@ -1239,6 +1642,7 @@ async function main() {
   );
   registerPrimitiveTools(server, ctx);
   registerInspectionTools(server, ctx);
+  registerObservabilityTools(server, ctx);
   registerRecordingTools(server, ctx);
   registerSessionTools(server, ctx);
   registerConfigTools(server, ctx);