crawlforge-mcp-server 6.5.0 → 6.6.0

package/src/core/browser/snapshot.js

@@ -0,0 +1,346 @@
+/**
+ * Snapshot — the accessibility-style page tree that hands an agent stable
+ * element refs (`@e1`, `@e2`, …) to act on instead of guessed CSS selectors.
+ *
+ * Why ours and not Playwright's: 1.62's `locator.ariaSnapshot()` emits YAML
+ * with no element refs at all, and `page._snapshotForAI()` is private API we
+ * will not depend on. The walk below is injected by us and returns the tree
+ * and the refs from one pass.
+ *
+ * A REF LIVES IN TWO PLACES, and the halves do different jobs:
+ *
+ *   1. In the page — the walk stamps `data-cf-ref="e1"` onto every element it
+ *      refs, so a ref resolves to an ordinary CSS selector,
+ *      `[data-cf-ref="e1"]`. That is what makes refs work with every existing
+ *      action path for free, including the stealth human-behaviour code that
+ *      takes a raw selector string.
+ *   2. In Node — a WeakMap<Page, state> cleared on every main-frame
+ *      navigation. This is the half that DETECTS staleness. Without it a ref
+ *      from a previous page would merely fail to match, and the caller would
+ *      be told "selector not found" instead of "take a new snapshot".
+ *
+ * So a stale ref fails loudly, with the reason and the fix (StaleRefError),
+ * and never silently hits the wrong element.
+ *
+ * Not to be confused with src/core/SnapshotManager.js, which is change-
+ * tracking history.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const REF_ATTRIBUTE = 'data-cf-ref';
+export const DEFAULT_MAX_NODES = 200;
+export const MAX_NODES_LIMIT = 1000;
+
+// Walks of one snapshot call, including the retry when the page navigates
+// mid-walk. Two: one retry is enough for a page that settles, and a page
+// navigating repeatedly is not one a snapshot can describe.
+const MAX_WALK_ATTEMPTS = 2;
+
+// Indentation follows the nesting of EMITTED nodes, and stops deepening past
+// this many levels so a deep DOM cannot produce runaway leading whitespace.
+const MAX_INDENT = 10;
+const MAX_NAME_LENGTH = 120;
+
+const REF_PATTERN = /^@e[1-9]\d*$/;
+
+/** Thrown when a ref cannot be resolved against the page's current snapshot. */
+export class StaleRefError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StaleRefError';
+  }
+}
+
+// Page -> { snapshotId, refs, invalidated, tracking }. WeakMap so a closed
+// page's refs go with it.
+const pageState = new WeakMap();
+
+/** True for an element ref (`@e1`), false for anything else, including non-strings. */
+export function isRef(selector) {
+  return typeof selector === 'string' && REF_PATTERN.test(selector);
+}
+
+/**
+ * The injected walk. Fixed source, written by us — it is not caller-supplied
+ * JavaScript, so it has nothing to do with the ALLOW_JAVASCRIPT_EXECUTION flag
+ * that gates the `executeJavaScript` action. Do not put it behind that flag.
+ */
+function snapshotScript({ refAttribute, interactiveOnly, maxNodes, maxIndent, maxNameLength }) {
+  const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head']);
+  const INTERACTIVE_ROLES = new Set([
+    'button', 'link', 'checkbox', 'radio', 'textbox', 'combobox', 'menuitem',
+    'menuitemcheckbox', 'menuitemradio', 'tab', 'switch', 'option', 'searchbox',
+    'slider', 'spinbutton'
+  ]);
+  const STRUCTURAL_ROLES = new Set([
+    'heading', 'banner', 'navigation', 'contentinfo', 'complementary', 'main',
+    'form', 'region', 'search'
+  ]);
+  const LANDMARK_TAGS = {
+    main: 'main', nav: 'navigation', header: 'banner', footer: 'contentinfo',
+    aside: 'complementary', form: 'form'
+  };
+  const INPUT_ROLES = {
+    text: 'textbox', search: 'textbox', email: 'textbox', tel: 'textbox',
+    url: 'textbox', password: 'textbox', checkbox: 'checkbox', radio: 'radio',
+    submit: 'button', button: 'button', reset: 'button'
+  };
+
+  // Double quotes delimit the name in the tree, so a name may not contain one.
+  const clean = (value) => (value || '').replace(/\s+/g, ' ').trim().replace(/"/g, "'");
+  const truncate = (value) =>
+    (value.length > maxNameLength ? `${value.slice(0, maxNameLength - 1)}…` : value);
+
+  function roleOf(el, tag) {
+    const explicit = (el.getAttribute('role') || '').trim().toLowerCase();
+    if (explicit) return explicit.split(/\s+/)[0];
+    if (tag === 'input') return INPUT_ROLES[(el.getAttribute('type') || 'text').toLowerCase()] || tag;
+    if (tag === 'a') return el.hasAttribute('href') ? 'link' : tag;
+    if (tag === 'button' || tag === 'summary') return 'button';
+    if (tag === 'select') return 'combobox';
+    if (tag === 'textarea') return 'textbox';
+    if (/^h[1-6]$/.test(tag)) return 'heading';
+    return LANDMARK_TAGS[tag] || tag;
+  }
+
+  function nameOf(el, tag, allowTextContent) {
+    const ariaLabel = clean(el.getAttribute('aria-label'));
+    if (ariaLabel) return ariaLabel;
+
+    const labelledBy = (el.getAttribute('aria-labelledby') || '').trim();
+    if (labelledBy) {
+      const referenced = clean(labelledBy.split(/\s+/)
+        .map((id) => (document.getElementById(id) || {}).textContent || '')
+        .join(' '));
+      if (referenced) return referenced;
+    }
+
+    // el.labels covers both `label[for=id]` and an ancestor <label>; closest()
+    // is the fallback for elements that have no .labels (a contenteditable).
+    const labels = el.labels;
+    const labelText = clean(labels && labels.length
+      ? labels[0].textContent
+      : (el.closest('label') || {}).textContent);
+    if (labelText) return labelText;
+
+    for (const attribute of ['placeholder', 'title', 'alt']) {
+      const value = clean(el.getAttribute(attribute));
+      if (value) return value;
+    }
+
+    // A push button's label is its value; a text field's value is user data,
+    // not a name, which is why this is narrowed to the button types.
+    if (tag === 'input' && /^(button|submit|reset)$/.test((el.getAttribute('type') || '').toLowerCase())) {
+      const value = clean(el.value);
+      if (value) return value;
+    }
+
+    // A landmark is named by its label, never by everything inside it —
+    // otherwise <main> would be captioned with the whole page.
+    return allowTextContent ? clean(el.textContent) : '';
+  }
+
+  function isInteractive(el, tag, role) {
+    if (INTERACTIVE_ROLES.has(role)) return true;
+    if (tag === 'a') return el.hasAttribute('href');
+    if (tag === 'input') return (el.getAttribute('type') || '').toLowerCase() !== 'hidden';
+    if (tag === 'select' || tag === 'textarea' || tag === 'button' || tag === 'summary') return true;
+    const editable = el.getAttribute('contenteditable');
+    if (editable !== null && editable !== 'false') return true;
+    const tabindex = el.getAttribute('tabindex');
+    if (tabindex !== null && tabindex.trim() !== '-1') return true;
+    return el.hasAttribute('onclick');
+  }
+
+  function isHidden(el, tag) {
+    if (SKIP_TAGS.has(tag)) return true;
+    if (el.hasAttribute('hidden')) return true;
+    if (el.getAttribute('aria-hidden') === 'true') return true;
+    const style = getComputedStyle(el);
+    return style.display === 'none' || style.visibility === 'hidden';
+  }
+
+  const hasSize = (el) => {
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+
+  const lines = [];
+  const refs = [];
+  let truncated = false;
+
+  function walk(el, depth) {
+    if (truncated) return;
+    const tag = el.tagName.toLowerCase();
+    if (isHidden(el, tag)) return; // the subtree is hidden with it
+
+    const role = roleOf(el, tag);
+    const interactive = isInteractive(el, tag, role);
+    const structural = !interactive && !interactiveOnly &&
+      (/^h[1-6]$/.test(tag) || Boolean(LANDMARK_TAGS[tag]) || STRUCTURAL_ROLES.has(role));
+    let childDepth = depth;
+
+    // A zero-size element is not emitted, but its children still are: a
+    // collapsed wrapper is common, an unreachable subtree is not.
+    if ((interactive || structural) && hasSize(el)) {
+      if (lines.length >= maxNodes) {
+        truncated = true;
+        return;
+      }
+      const name = truncate(nameOf(el, tag, interactive || role === 'heading'));
+      let ref = '';
+      // Only interactive nodes get a ref — a structural line is context, not a target.
+      if (interactive) {
+        const id = `e${refs.length + 1}`;
+        el.setAttribute(refAttribute, id);
+        refs.push({ id, role, name, tag });
+        ref = `@${id} `;
+      }
+      lines.push(`${'  '.repeat(Math.min(depth, maxIndent))}${ref}[${role}]${name ? ` "${name}"` : ''}`);
+      childDepth = depth + 1;
+    }
+
+    for (const child of el.children) walk(child, childDepth);
+  }
+
+  // Drop refs from an earlier walk so a re-snapshot of the same page numbers
+  // cleanly instead of leaving elements answering to a retired id.
+  for (const stale of document.querySelectorAll(`[${refAttribute}]`)) {
+    stale.removeAttribute(refAttribute);
+  }
+  walk(document.body || document.documentElement, 1);
+
+  return { title: clean(document.title), lines, refs, truncated };
+}
+
+function stateFor(page) {
+  let state = pageState.get(page);
+  if (!state) {
+    state = { snapshotId: null, refs: null, invalidated: false, tracking: false, generation: 0 };
+    pageState.set(page, state);
+  }
+  return state;
+}
+
+/**
+ * Walk the page and return its tree plus the refs it assigned.
+ *
+ * @param {import('playwright').Page} page
+ * @param {object} [options]
+ * @param {boolean} [options.interactiveOnly=true] — false also emits headings and landmarks, unreffed
+ * @param {number} [options.maxNodes=200] — cap on emitted nodes, clamped to [1, MAX_NODES_LIMIT]
+ */
+export async function captureSnapshot(page, options = {}) {
+  const interactiveOnly = options.interactiveOnly !== false;
+  const requested = Number(options.maxNodes);
+  const maxNodes = Number.isFinite(requested)
+    ? Math.min(Math.max(Math.floor(requested), 1), MAX_NODES_LIMIT)
+    : DEFAULT_MAX_NODES;
+
+  // Idempotent, and the guarantee that a later navigation invalidates these
+  // refs rather than leaving them to fail as a missing selector.
+  attachRefTracking(page);
+
+  const state = stateFor(page);
+  let title, lines, refs, truncated;
+
+  // A navigation that commits WHILE the walk is running would otherwise leave us
+  // holding refs for a document that has gone — the attributes were stamped on
+  // the old page, so `@e1` would match nothing and surface as a locator timeout
+  // instead of the named error D2 requires. `generation` moves on every
+  // main-frame navigation, so a change across the evaluate means exactly that.
+  // Walk the new document instead; if it navigates again, give up and leave the
+  // refs invalidated rather than publishing a tree for a page nobody is on.
+  for (let attempt = 0; ; attempt++) {
+    const generation = state.generation;
+    ({ title, lines, refs, truncated } = await page.evaluate(snapshotScript, {
+      refAttribute: REF_ATTRIBUTE,
+      interactiveOnly,
+      maxNodes,
+      maxIndent: MAX_INDENT,
+      maxNameLength: MAX_NAME_LENGTH
+    }));
+    if (state.generation === generation) break;
+    if (attempt >= MAX_WALK_ATTEMPTS - 1) {
+      clearRefs(page);
+      throw new StaleRefError(
+        'The page navigated while the snapshot was being taken — take a new snapshot.'
+      );
+    }
+  }
+
+  const snapshotId = randomUUID().slice(0, 8);
+  state.snapshotId = snapshotId;
+  state.refs = new Map(refs.map(({ id, role, name, tag }) => [id, { role, name, tag }]));
+  state.invalidated = false;
+
+  return {
+    snapshotId,
+    url: page.url(),
+    title,
+    tree: [`[document]${title ? ` "${title}"` : ''}`, ...lines].join('\n'),
+    refCount: refs.length,
+    nodeCount: lines.length,
+    truncated,
+    interactiveOnly
+  };
+}
+
+/**
+ * Turn `@e1` into the CSS selector every action path already understands.
+ * Throws StaleRefError when the ref does not belong to the page's current
+ * snapshot — it never guesses.
+ */
+export function resolveRef(page, selector) {
+  if (!isRef(selector)) {
+    // A programming error, not a stale ref: callers gate on isRef().
+    throw new Error(`resolveRef expects an element ref like "@e1", got ${JSON.stringify(selector)}`);
+  }
+
+  const state = pageState.get(page);
+  if (!state || (!state.refs && !state.invalidated)) {
+    throw new StaleRefError(
+      `Unknown element ref ${selector}: no snapshot has been taken on this page — add a { "type": "snapshot" } action before acting on refs.`
+    );
+  }
+  if (!state.refs) {
+    throw new StaleRefError(
+      `Stale element ref ${selector}: the page navigated since the last snapshot — take a new snapshot before acting on refs.`
+    );
+  }
+
+  const id = selector.slice(1);
+  if (!state.refs.has(id)) {
+    const count = state.refs.size;
+    throw new StaleRefError(count === 0
+      ? `Unknown element ref ${selector}: the current snapshot has no refs — take a new snapshot.`
+      : `Unknown element ref ${selector}: the current snapshot has ${count} refs (@e1-@e${count}) — take a new snapshot.`);
+  }
+
+  return `[${REF_ATTRIBUTE}="${id}"]`;
+}
+
+/** Register the navigation listener that invalidates this page's refs. Idempotent. */
+export function attachRefTracking(page) {
+  const state = stateFor(page);
+  if (state.tracking) return;
+  state.tracking = true;
+  page.on('framenavigated', (frame) => {
+    if (frame === page.mainFrame()) clearRefs(page);
+  });
+}
+
+/** Drop the page's refs. A ref resolved afterwards reports the navigation, not a miss. */
+export function clearRefs(page) {
+  const state = pageState.get(page);
+  if (!state) return;
+  // `invalidated` is only meaningful once a snapshot existed — it is what
+  // separates "the page navigated" from "no snapshot has been taken".
+  if (state.refs) state.invalidated = true;
+  state.refs = null;
+  state.snapshotId = null;
+  // Bumped on every clear so a walk in flight can tell the document changed
+  // under it — see captureSnapshot.
+  state.generation++;
+}

package/src/server/fallbackHints.js

@@ -32,6 +32,7 @@ export const FALLBACK_HINTS = Object.freeze({
   extract_with_llm: 'If Ollama is unreachable pass provider:"openai" or "anthropic" with a key, or use extract_structured (CSS fallback needs no LLM).',
   list_ollama_models: 'Ollama is not reachable - use extract_with_llm with provider:"openai"/"anthropic", or extract_structured.',
   scrape_with_actions: 'Check the selector against scrape formats:["html"] output; for a one-shot render of a blocked page use stealth_mode operation:"scrape".',
+  browser_session: 'A session that expired or was closed cannot be reused - start again with operation:"open". If a ref missed, take another snapshot first: navigation invalidates refs. For a chain that needs no session, use scrape_with_actions.',
   deep_research: 'Use agent for a shorter answer, or search_web followed by scrape on the sources that matter.',
   scrape: 'After a 403/429/CAPTCHA/challenge page or an empty shell use stealth_mode operation:"scrape"; if the content needs a click or login use scrape_with_actions.',
   agent: 'Use deep_research for exhaustive sourcing, or search_web followed by scrape on the sources that matter.',

package/src/server/requestContext.js

@@ -6,14 +6,18 @@
  * plumbing. AsyncLocalStorage bridges that gap: the transport runs each
  * request inside a context, and withAuth reads it at invocation time.
  *
- * Today the only flag is `internal`: a request authenticated with the
+ * The first flag is `internal`: a request authenticated with the
  * INTERNAL_PROXY_SECRET (the crawlforge-website REST proxy). Internal requests
  * run tools normally but are billing-exempt — the website has already checked
  * and charged the end user's credits, so metering here would double-bill.
  *
- * The flag lives on the request context, never on the MCP session: a session
- * id created by an internal request grants nothing to a later request that
- * authenticates by other means.
+ * The second is `ownerToken`, which says WHICH of the website's customers an
+ * internal request is being made for (see internalOwnerToken below).
+ *
+ * Both live on the request context, never on the MCP session: a session id
+ * created by an internal request grants nothing to a later request that
+ * authenticates by other means, and an owner established on one request is not
+ * inherited by the next one down the same MCP session.
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -25,6 +29,23 @@ export function isInternalRequest() {
   return requestContext.getStore()?.internal === true;
 }
 
+/**
+ * The end user this internal-proxy request is being made for, or null.
+ *
+ * An opaque per-user token the website derives with an HMAC keyed on the shared
+ * internal secret (mcpOwnerToken in crawlforge-website
+ * src/lib/tools/mcp-proxy.ts), carried on the X-CrawlForge-Owner header. It is
+ * not reversible to a user id here and is not meant to be: all a stateful tool
+ * needs is a value that is stable for one customer and distinct between them.
+ *
+ * Only ever set on a request that already proved the internal secret, and only
+ * after the transport has validated its shape — authenticateRequest in
+ * transports/streamableHttp.js is the single place that decides both.
+ */
+export function internalOwnerToken() {
+  return requestContext.getStore()?.ownerToken ?? null;
+}
+
 /**
  * Record that the compliance gate refused this invocation before anything was
  * fetched — robots.txt disallowed the path, or the host is on the permanent

package/src/server/toolFilter.js

@@ -1,7 +1,7 @@
 /**
  * toolFilter — client-side tool selection (Phase 6).
  *
- * Lets an MCP client load a subset of the 30 registered tools via env vars,
+ * Lets an MCP client load a subset of the 31 registered tools via env vars,
  * cutting context bloat (mirrors Bright Data / Exa's TOOLS / GROUPS pattern).
  *
  * Pure module: no I/O, no logging; process.env is only read via
@@ -17,7 +17,7 @@ export const TOOL_GROUPS = {
   search: ['search_web', 'serp_rank', 'reddit_search'],
   crawl: ['crawl_deep', 'map_site'],
   extract: ['extract_content', 'process_document', 'summarize_content', 'analyze_content', 'extract_structured', 'extract_with_llm', 'list_ollama_models', 'extract_embedded_state'],
-  batch: ['batch_scrape', 'get_batch_results', 'scrape_with_actions'],
+  batch: ['batch_scrape', 'get_batch_results', 'scrape_with_actions', 'browser_session'],
   research: ['deep_research'],
   tracking: ['track_changes'],
   llmstxt: ['generate_llms_txt'],

package/src/server/transports/streamableHttp.js

@@ -314,9 +314,11 @@ export async function connectStreamableHttp(server, authManager, logger, options
       // — never expose an unauthenticated MCP endpoint on a public interface.
       // `internal` marks a request from the website's REST proxy
       // (INTERNAL_PROXY_SECRET): it is billing-exempt in withAuth because the
-      // website already charged the end user. Request-scoped only — never
-      // persisted on the session.
+      // website already charged the end user. `ownerToken` says which of the
+      // website's customers it is being made for. Both are request-scoped only
+      // — never persisted on the session.
       let internal = false;
+      let ownerToken;
       if (!(authManager.isCreatorMode() && hostIsLoopback)) {
         const authResult = await authenticateRequest(req, authManager, oauthProvider);
         if (!authResult.ok) {
@@ -332,6 +334,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
           return;
         }
         internal = authResult.internal === true;
+        ownerToken = authResult.ownerToken;
       }
 
       // Era routing. Only a POST can carry the 2026-07-28 per-request envelope;
@@ -355,7 +358,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
         if (parsedBody !== undefined) {
           const probe = await toWebRequest(req, parsedBody);
           if (!(await isLegacyRequest(probe, parsedBody))) {
-            await requestContext.run({ internal }, () => serveModern(req, res, parsedBody));
+            await requestContext.run({ internal, ownerToken }, () => serveModern(req, res, parsedBody));
             return;
           }
         }
@@ -370,7 +373,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
 
       if (existing) {
         await requestContext.run(
-          { internal, servingServer: existing.server, servingEra: 'legacy' },
+          { internal, ownerToken, servingServer: existing.server, servingEra: 'legacy' },
           () => existing.transport.handleRequest(req, res, parsedBody)
         );
         return;
@@ -406,7 +409,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
       try {
         await sessionServer.connect(transport);
         await requestContext.run(
-          { internal, servingServer: sessionServer, servingEra: 'legacy' },
+          { internal, ownerToken, servingServer: sessionServer, servingEra: 'legacy' },
           () => transport.handleRequest(req, res, parsedBody)
         );
       } catch (err) {
@@ -453,6 +456,28 @@ export async function connectStreamableHttp(server, authManager, logger, options
   };
 }
 
+/**
+ * Hex, and bounded. The website emits 32 characters (mcpOwnerToken in
+ * crawlforge-website src/lib/tools/mcp-proxy.ts); the range is wider so the two
+ * repos can pick a different HMAC slice without a lockstep deploy, and narrow
+ * enough that nothing unbounded, non-printable or structured can ever become
+ * part of an owner id.
+ */
+const OWNER_TOKEN_RE = /^[0-9a-f]{16,64}$/;
+
+/**
+ * The owner token an internal request claims, or undefined.
+ *
+ * Undefined covers absent AND malformed alike, and the difference must not
+ * matter: everything downstream treats "no owner" as "no session", so a value
+ * that fails this check is simply not an owner rather than a strange one. Never
+ * relax this into a coercion — the token becomes part of a tenant key.
+ */
+function readOwnerToken(req) {
+  const value = (req.headers['x-crawlforge-owner'] || '').toString();
+  return OWNER_TOKEN_RE.test(value) ? value : undefined;
+}
+
 /**
  * Validate a request's credentials.
  *
@@ -460,13 +485,14 @@ export async function connectStreamableHttp(server, authManager, logger, options
  *   - `X-Internal-Secret: <INTERNAL_PROXY_SECRET>` — server-to-server requests
  *     from the crawlforge-website REST proxy. Returns { ok, internal: true };
  *     internal requests are billing-exempt in withAuth (the website already
- *     charged the end user). Only active when the env var is set.
+ *     charged the end user). Only active when the env var is set. Such a
+ *     request may also carry `X-CrawlForge-Owner` — see readOwnerToken.
  *   - `Authorization: Bearer <crawlforge-api-key>` (legacy static key)
  *   - `X-API-Key: <crawlforge-api-key>` (legacy static key)
  *   - `Authorization: Bearer <oauth-access-token>` if OAuth is enabled —
  *     the OAuth provider validates the token and maps it to the API key.
  *
- * @returns {Promise<{ok: true, internal?: boolean} | {ok: false, status: number, error: string, message: string, reason: string}>}
+ * @returns {Promise<{ok: true, internal?: boolean, ownerToken?: string} | {ok: false, status: number, error: string, message: string, reason: string}>}
  */
 async function authenticateRequest(req, authManager, oauthProvider) {
   // Internal proxy path first: presenting the header at all means the caller
@@ -480,7 +506,11 @@ async function authenticateRequest(req, authManager, oauthProvider) {
       const provided = createHash('sha256').update(providedSecret).digest();
       const expected = createHash('sha256').update(internalSecret).digest();
       if (timingSafeEqual(provided, expected)) {
-        return { ok: true, internal: true };
+        // Read ONLY here, on the branch that has just proved the secret. A
+        // request that authenticated any other way — or none — never has its
+        // owner header looked at, so claiming an owner requires already being
+        // the proxy.
+        return { ok: true, internal: true, ownerToken: readOwnerToken(req) };
       }
     }
     return {

package/src/skills/agent-skills/crawlforge-batch-automation/SKILL.md

@@ -97,13 +97,20 @@ browser actions before extraction.
 }
 ```
 
-Allowed action types: `wait`, `click`, `type`, `press`, `scroll`, `screenshot`,
-`executeJavaScript`. `executeJavaScript` is disabled unless the deploy sets
+Allowed action types: `snapshot`, `wait`, `click`, `type`, `press`, `scroll`,
+`screenshot`, `executeJavaScript`, `select`, `hover`, `navigate`. Start a chain
+with `{"type": "snapshot"}` to list the page's interactive elements with stable
+refs (`@e1`, `@e2` …) and target those in later actions instead of guessing CSS
+selectors. `executeJavaScript` is disabled unless the deploy sets
 `ALLOW_JAVASCRIPT_EXECUTION=true`. 1–20 actions per call. Screenshots are stored
 as `crawlforge://screenshot/{actionId}` resources. Full action schemas:
 [actions](references/actions.md). CLI:
 `crawlforge actions https://example.com --script login.json --screenshot`.
 
+One-shot: the browser closes when the call returns. When the flow spans more
+than one call, or you need to see the page before choosing what to click, use
+`browser_session` instead (crawlforge-browser-sessions).
+
 ## generate_llms_txt — AI policy file (cost: 5)
 
 ```json

package/src/skills/agent-skills/crawlforge-batch-automation/references/actions.md

@@ -1,10 +1,16 @@
 # scrape_with_actions — Action Types
 
 `scrape_with_actions` runs an ordered `actions[]` array (1–20 items) before
-scraping. Only these 7 action types are allowed (allow-listed in ActionExecutor).
-Each action object has a `type` plus type-specific fields. Common optional
-fields on every action: `timeout`, `description`, `continueOnError`, `retries`
-(0–5), `captureAfter`.
+scraping. Only these action types are allowed (allow-listed in ActionExecutor):
+`snapshot`, `wait`, `click`, `type`, `press`, `scroll`, `screenshot`,
+`executeJavaScript`, `select`, `hover`, `navigate`. Each action object has a
+`type` plus type-specific fields. Common optional fields on every action:
+`timeout`, `description`, `continueOnError`, `retries` (0–5), `captureAfter`.
+
+**Start with a snapshot.** Section 8 returns the page's interactive elements
+with stable refs, and any action's `selector` may name one (`@e1`) instead of a
+CSS selector you have not seen. That is the difference between landing a
+multi-step flow first try and burning the call on a guess.
 
 ## 1. wait
 
@@ -101,6 +107,46 @@ Disabled unless the deployment sets `ALLOW_JAVASCRIPT_EXECUTION=true`.
 { "type": "executeJavaScript", "script": "return document.title", "returnResult": true }
 ```
 
+## 8. snapshot
+
+List the page's interactive elements, each with a stable ref later actions can
+target. Refs are assigned `@e1…@eN` in document order and are **invalidated by
+navigation** — snapshot again after one, or acting on an old ref fails with a
+named error telling you to.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `interactiveOnly` | boolean | Default true. False also lists headings and landmarks, which carry no ref. |
+| `maxNodes` | number | Cap on nodes listed (default 200, max 1000). The result sets `truncated` when the cap stopped the walk. |
+
+```json
+{ "type": "snapshot" }
+```
+
+The tree comes back in `actionResults[i].result.tree`, alongside `snapshotId`,
+`url`, `title`, `refCount`, `nodeCount`, `truncated` and `interactiveOnly`:
+
+```
+[document] "Sign in"
+  @e1 [textbox] "Email"
+  @e2 [textbox] "Password"
+  @e3 [button] "Sign in"
+```
+
+```json
+[
+  { "type": "snapshot" },
+  { "type": "type", "selector": "@e1", "text": "user@example.com" },
+  { "type": "click", "selector": "@e3" }
+]
+```
+
+The tool is stateless, so a chain cannot adapt to its own snapshot mid-flight:
+read the refs in one call, act on them in the next. A fresh load of the same
+page numbers them the same way, and the second chain snapshots again first so
+the refs are stamped on the document it is acting against. The walk covers the
+main frame only — elements inside iframes and shadow DOM get no refs.
+
 ## Top-level options
 
 | Option | Default | Notes |