crawlforge-mcp-server 6.22.2 → 6.23.0

package/src/tools/extract/extractStructured.js

@@ -154,6 +154,88 @@ export function verifyFieldShapes(data, schema) {
   return { data: out, unverified };
 }
 
+/**
+ * The value of the label/value row whose label names the field: a two-cell
+ * <tr> (`<th>UPC</th><td>…</td>`) or a <dt>/<dd> pair. Every word of the
+ * field name must be in the label; among several matches the label with the
+ * fewest extra words wins. The CSS fallback only looked at class, id, itemprop
+ * and meta, so a product-information table never answered anything:
+ * books.toscrape's UPC came back missing (live sweep 2026-10-20, 2.3).
+ *
+ * @param {import('cheerio').CheerioAPI} $
+ * @param {string} key - schema field name
+ * @returns {string|null}
+ */
+function labelledValue($, key) {
+  const want = keyWords(key);
+  if (want.length === 0) return null;
+  let best = null;
+  const consider = (label, value) => {
+    const words = keyWords(label);
+    if (!value || !want.every((w) => words.includes(w))) return;
+    const extra = words.length - want.length;
+    if (!best || extra < best.extra) best = { value, extra };
+  };
+  $('tr').each((_, tr) => {
+    const cells = $(tr).children('th, td');
+    if (cells.length === 2) consider(cells.first().text(), cells.last().text().trim());
+  });
+  $('dt').each((_, dt) => consider($(dt).text(), $(dt).next('dd').text().trim()));
+  return best ? best.value : null;
+}
+
+/** Field-name words a page's own wording leaves out: "in_stock_count". */
+const COUNT_WORDS = new Set(['count', 'number', 'num', 'total', 'qty', 'quantity']);
+
+/**
+ * For a numeric field: the text after the field's phrase on the first page
+ * line that has it with a number after it. `in_stock_count` reads
+ * "In stock (22 available)" as " (22 available)", which the caller coerces to
+ * 22. Only the text after the phrase counts, so a number earlier on the line
+ * is never taken.
+ *
+ * @param {string} text - flattened page text, one line per block
+ * @param {string} key
+ * @returns {string|null}
+ */
+function textAfterPhrase(text, key) {
+  const words = keyWords(key).filter((w) => !COUNT_WORDS.has(w));
+  if (words.length === 0) return null;
+  const phrase = new RegExp(`\\b${words.join('[\\s_-]*')}\\b`, 'i');
+  for (const line of text.split('\n')) {
+    const match = phrase.exec(line);
+    if (!match) continue;
+    const rest = line.slice(match.index + match[0].length);
+    if (/\d/.test(rest)) return rest;
+  }
+  return null;
+}
+
+const RATING_WORDS = { one: 1, two: 2, three: 3, four: 4, five: 5 };
+
+/**
+ * A star rating carried only in a class token: books.toscrape renders three
+ * stars as `<p class="star-rating Three">` with five identical icons inside,
+ * so no text on the page says 3. For a field named for a rating or stars, the
+ * first class token on a star/rating element that spells a number one to five
+ * is that number. Decision (2.3): it is returned as a number for a
+ * number/integer field and as its digit string ("3") otherwise.
+ *
+ * @param {import('cheerio').CheerioAPI} $
+ * @param {string} key
+ * @returns {number|null}
+ */
+function classRating($, key) {
+  if (!keyWords(key).some((w) => w === 'rating' || w === 'stars' || w === 'star')) return null;
+  for (const el of $('[class*="star"], [class*="rating"]').toArray()) {
+    for (const token of ($(el).attr('class') || '').split(/\s+/)) {
+      const n = RATING_WORDS[token.toLowerCase()];
+      if (n) return n;
+    }
+  }
+  return null;
+}
+
 /** Lowercased, whitespace-collapsed text for a containment check. */
 function squash(text) {
   return text.toLowerCase().replace(/\s+/g, ' ').trim();
@@ -502,10 +584,30 @@ export class ExtractStructuredTool {
       const failedRequired = extractionResult.valid !== true
         && (missingRequired.length > 0 || invalidRequired.length > 0);
 
+      // Every requested field is in `data`. A field no method filled used to
+      // be left out with no null and no note, so a caller could not tell
+      // "not on the page" from "not looked for" (live sweep 2026-10-20, 2.3).
+      // An empty array is an answer (no items), not a missing value.
+      const data = { ...(extractionResult.data || {}) };
+      const missingFields = [];
+      if (!Array.isArray(extractionResult.data)) {
+        for (const key of Object.keys(schema.properties || {})) {
+          const value = data[key];
+          if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+            data[key] = null;
+            missingFields.push(key);
+          }
+        }
+      }
+      if (missingFields.length > 0) {
+        extractionNotes.push(`Not found on the page, returned as null: ${missingFields.join(', ')}`);
+      }
+
       return {
         success: !failedRequired,
         url,
-        data: extractionResult.data || {},
+        data,
+        missing_fields: missingFields,
         extraction_method: extractionMethod,
         // The provider and model that produced an LLM extraction (R24).
         ...(extractionMethod === 'llm' && extractionResult.model
@@ -556,6 +658,7 @@ export class ExtractStructuredTool {
     const properties = schema.properties || {};
     const extracted = {};
     let fieldsFound = 0;
+    let pageText = null; // flattened lazily, only for a numeric field that needs it
 
     for (const [key, fieldSchema] of Object.entries(properties)) {
       // Schema keys become CSS selector fragments below (class/id/data-attr).
@@ -647,6 +750,15 @@ export class ExtractStructuredTool {
           }
         }
 
+        // A labelled table or definition-list row: <th>UPC</th><td>…</td>.
+        if (!(key in extracted)) {
+          const labelled = labelledValue($, key);
+          if (labelled) {
+            extracted[key] = this._coerceValue(labelled, fieldSchema);
+            fieldsFound++;
+          }
+        }
+
         // Last resort: semantic element selectors for well-known field names
         // (e.g. title -> <h1>/<title>) so common fields resolve without hints.
         if (!(key in extracted)) {
@@ -673,6 +785,27 @@ export class ExtractStructuredTool {
             }
           }
         }
+
+        // A rating encoded only as a class token (`star-rating Three`).
+        if (!(key in extracted)) {
+          const stars = classRating($, key);
+          if (stars !== null) {
+            const numeric = fieldSchema.type === 'number' || fieldSchema.type === 'integer';
+            extracted[key] = numeric ? stars : String(stars);
+            fieldsFound++;
+          }
+        }
+
+        // A numeric field stated in running text: "In stock (22 available)".
+        if (!(key in extracted) && (fieldSchema.type === 'number' || fieldSchema.type === 'integer')) {
+          if (pageText === null) pageText = flattenBodyText($);
+          const after = textAfterPhrase(pageText, key);
+          const value = after === null ? null : this._coerceValue(after, fieldSchema);
+          if (typeof value === 'number') {
+            extracted[key] = value;
+            fieldsFound++;
+          }
+        }
       } catch (_fieldError) {
         // Invalid selector for this key — skip the field, keep going.
         continue;

package/src/tools/extract/processDocument.js

@@ -15,6 +15,7 @@ import { safeFetch } from '../../utils/ssrfGuard.js';
 import { preflightFetch } from '../../utils/robotsGate.js';
 import { noteRetryAfter } from '../../utils/hostRateLimiter.js';
 import { isRemoteTransport } from '../../utils/remoteMode.js';
+import { assertLocalFileAllowed } from '../../utils/localFilePolicy.js';
 import { flattenText } from 'crawlforge-extractors';
 import { load } from 'cheerio';
 
@@ -178,6 +179,38 @@ export function decodeTextBody(buffer, contentType = '') {
   }
 }
 
+// Lines that open a PDF's text layer without being its title: arXiv's margin
+// stamp ("arXiv:1706.03762v7 [cs.CL] 2 Aug 2023") and bare page numbers.
+const NON_TITLE_LINE_RE = /^(arXiv:\S+.*|\d+)$/i;
+const MAX_TITLE_CHARS = 200;
+
+/**
+ * A title for a document with none in its metadata: the first non-empty line
+ * of its text when that line is short enough to be one, else null. arXiv
+ * stamps and page numbers before it are skipped.
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function titleFromText(text) {
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const candidate = line.replace(/\s+/g, ' ').trim();
+    if (candidate === '' || NON_TITLE_LINE_RE.test(candidate)) continue;
+    return candidate.length <= MAX_TITLE_CHARS ? candidate : null;
+  }
+  return null;
+}
+
+/**
+ * The text of the first h1-h6 in HTML, or null when it has none.
+ * @param {string} html
+ * @returns {string|null}
+ */
+export function firstHeadingFromHtml(html) {
+  const $ = load(html || '');
+  const text = $('h1, h2, h3, h4, h5, h6').first().text().replace(/\s+/g, ' ').trim();
+  return text || null;
+}
+
 export class ProcessDocumentTool {
   constructor() {
     this.pdfProcessor = new PDFProcessor();
@@ -221,6 +254,12 @@ export class ProcessDocumentTool {
         );
       }
 
+      // Locally, a read is still held to the document extensions and kept out
+      // of dot-directories (or held to CRAWLFORGE_ALLOWED_DIRS): see localFilePolicy.js.
+      const readFrom = sourceType === 'file' || sourceType === 'pdf_file'
+        ? await assertLocalFileAllowed(source)
+        : source;
+
       const result = {
         source,
         sourceType,
@@ -232,10 +271,10 @@ export class ProcessDocumentTool {
       // Determine document type and processing method
       if (sourceType.includes('pdf')) {
         result.documentType = 'pdf';
-        await this.processPDFDocument(result, source, sourceType, options, { respect_robots, user_agent });
+        await this.processPDFDocument(result, readFrom, sourceType, options, { respect_robots, user_agent });
       } else if (sourceType === 'file') {
         result.documentType = 'file';
-        await this.processLocalFileDocument(result, source, options);
+        await this.processLocalFileDocument(result, readFrom, options);
       } else {
         result.documentType = 'web';
         await this.processWebDocument(result, source, options, { respect_robots, user_agent });
@@ -362,8 +401,9 @@ export class ProcessDocumentTool {
       result.pagesRead = { ...pdfResult.extractedPages, totalPages: pdfResult.pageCount };
     }
 
-    // Set title
-    result.title = pdfResult.metadata?.title || null;
+    // Set title: the metadata title, else the first short line of the text
+    // (an arXiv PDF carries no /Title, live sweep 6.11).
+    result.title = pdfResult.metadata?.title || titleFromText(result.content.text);
 
     // Set metadata
     if (pdfResult.metadata) {
@@ -481,7 +521,10 @@ export class ProcessDocumentTool {
       const md = await mammoth.convertToMarkdown({ buffer });
       result.content.markdown = md.value || '';
     }
-    result.title = null;
+    // A .docx has no title field mammoth reads: use the first heading, else
+    // the first short line of the text (live sweep 6.11).
+    const html = await mammoth.convertToHtml({ buffer });
+    result.title = firstHeadingFromHtml(html.value) || titleFromText(result.content.text);
     const notes = (raw.messages || []).map((m) => m.message).filter(Boolean);
     if (notes.length > 0) result.warnings = [...(result.warnings || []), ...notes.slice(0, 5)];
   }

package/src/tools/extract/summarizeContent.js

@@ -21,7 +21,9 @@ const SummarizeContentSchema = z.object({
   text: z.string().min(10),
   options: z.object({
     summaryLength: z.enum(['short', 'medium', 'long']).default('medium'),
-    summaryType: z.enum(['extractive', 'abstractive']).default('extractive'),
+    // No default: omitted with summaryLength 'medium', abstractive is tried
+    // and falls back to extractive without flagging it (see execute).
+    summaryType: z.enum(['extractive', 'abstractive']).optional(),
     includeKeypoints: z.boolean().default(true),
     includeKeywords: z.boolean().default(true),
     includeStatistics: z.boolean().default(true),
@@ -93,6 +95,26 @@ const NAVIGATION_PHRASES = new Set([
   'de wikipedia, la enciclopedia libre'
 ]);
 
+// Whole lines that are page chrome wherever they appear: consent buttons and
+// account links. The live sweep (2026-10-20) found "all cookies manage
+// preferences" and "register subscribe" in summarize_content key points and
+// keywords. Matched exactly, like NAVIGATION_PHRASES, so a sentence that
+// merely contains one of these words is never touched.
+const CHROME_LINES = new Set([
+  'accept', 'accept all', 'accept all cookies', 'accept cookies', 'reject all',
+  'reject all cookies', 'manage preferences', 'manage cookies', 'manage settings',
+  'cookie settings', 'cookie preferences', 'cookies', 'cookie policy', 'i agree',
+  'register', 'subscribe', 'sign in', 'sign up', 'sign up now', 'log in', 'login',
+  'menu', 'search', 'close', 'skip to content', 'accessibility help', 'privacy policy',
+  'terms of use', 'terms of service'
+]);
+
+// A line about cookies that also speaks the language of consent is a banner,
+// not content; "Bake the cookies for 12 minutes" has no consent vocabulary.
+const COOKIE_WORD = /\bcookies?\b/i;
+const CONSENT_WORD = /\b(accept|agree|consent|manage|preferences|settings|policy|privacy|reject|we use|partners)\b/i;
+const SENTENCE_PUNCTUATION = /[.!?…。！？]/;
+
 export class SummarizeContentTool {
   constructor() {
     this.contentAnalyzer = new ContentAnalyzer();
@@ -131,7 +153,10 @@ export class SummarizeContentTool {
       // Page text often opens with navigation chrome ("Jump to content",
       // "From Wikipedia, the free encyclopedia") that otherwise leads the
       // summary and key points — strip it before summarizing.
-      const text = this.stripLeadingBoilerplate(rawText);
+      // The rest of the page's chrome (menus, consent banners, repeated
+      // labels) is spread through the text, and its unpunctuated lines glue
+      // whole runs of headlines into one "sentence" — strip and split those too.
+      const text = this.terminateLines(this.stripPageBoilerplate(this.stripLeadingBoilerplate(rawText)));
 
       const result = {
         originalText: rawText.substring(0, 500) + (rawText.length > 500 ? '...' : ''),
@@ -148,7 +173,7 @@ export class SummarizeContentTool {
           extractKeywords: options.includeKeywords,
           detectLanguage: true,
           summaryLength: options.summaryLength,
-          summaryType: options.summaryType,
+          summaryType: options.summaryType ?? 'extractive',
           maxKeywords: options.maxKeywords,
           extractTopics: false,
           extractEntities: false,
@@ -167,7 +192,18 @@ export class SummarizeContentTool {
       // D1.3: If abstractive mode requested, attempt sampling-based enhancement.
       // If it can't run (no LLM/sampling available), fall back to the extractive
       // result but flag it explicitly rather than silently masking.
-      if (options.summaryType === 'abstractive') {
+      // An omitted summaryType at the default 'medium' length prefers an
+      // abstractive summary when an LLM is reachable, and otherwise keeps the
+      // extractive one silently: the caller asked for no particular type, so
+      // nothing was degraded. Text too short to compress (ratio 1) is left as is.
+      const preferAbstractive = options.summaryType === undefined &&
+        options.summaryLength === 'medium' && analysisResult.summary.compressionRatio < 1;
+      if (preferAbstractive) {
+        const abstractive = await this._abstractiveSummaryViaSampling(
+          text, analysisResult.summary, options.summaryLength, analysisResult.language?.name
+        );
+        if (abstractive) result.summary = abstractive;
+      } else if (options.summaryType === 'abstractive') {
         const abstractive = await this._abstractiveSummaryViaSampling(
           text, analysisResult.summary, options.summaryLength, analysisResult.language?.name
         );
@@ -201,7 +237,7 @@ export class SummarizeContentTool {
       // Step 6: Set metadata
       result.metadata = {
         language: analysisResult.language?.code || options.language || 'unknown',
-        processingMethod: options.summaryType,
+        processingMethod: options.summaryType ?? result.summary.type,
         confidenceScore: this.calculateConfidenceScore(text, result.summary.text)
       };
 
@@ -361,6 +397,88 @@ export class SummarizeContentTool {
     return strippedLines > 0 ? lines.slice(index).join('\n') : text;
   }
 
+  /**
+   * Strip navigation and consent chrome from anywhere in extracted page text.
+   * A line is dropped when it is:
+   *   - a CHROME_LINES / NAVIGATION_PHRASES entry, or a cookie line that uses
+   *     consent vocabulary;
+   *   - a pipe/bullet menu ("Home | News | Sport"): 3+ segments of ≤ 4 words;
+   *   - repeated on the page: a short label (≤ 4 words, unpunctuated) loses
+   *     every copy — "In stock", "Add to basket", section names — while a
+   *     longer repeated line keeps its first copy;
+   *   - part of a nav run: 4+ consecutive lines that are each ≤ 30 chars,
+   *     ≤ 4 words, unpunctuated and digit-free. The digit rule keeps listings
+   *     whose short titles alternate with prices or counts.
+   * If almost nothing survives (< 10 chars) the text is returned untouched.
+   * @param {string} text - Text to clean
+   * @returns {string} - Text without page chrome
+   */
+  stripPageBoilerplate(text) {
+    const lines = text.split('\n');
+    const key = (line) => line.trim().replace(/[.!?…。！？]+$/, '').trim().toLowerCase();
+    const isShort = (line) => line.split(/\s+/).length <= 4 && !SENTENCE_PUNCTUATION.test(line);
+
+    const counts = new Map();
+    for (const line of lines) {
+      const k = key(line);
+      if (k) counts.set(k, (counts.get(k) || 0) + 1);
+    }
+
+    const seen = new Set();
+    const drop = lines.map((raw) => {
+      const line = raw.trim();
+      if (!line) return false;
+      const k = key(line);
+      if (CHROME_LINES.has(k) || NAVIGATION_PHRASES.has(k)) return true;
+      if (COOKIE_WORD.test(line) && CONSENT_WORD.test(line)) return true;
+      const segments = line.split(/\s*[|•·]\s*/).filter(Boolean);
+      if (segments.length >= 3 && segments.every((s) => s.split(/\s+/).length <= 4)) return true;
+      if (counts.get(k) > 1 && (isShort(line) || seen.has(k))) return true;
+      seen.add(k);
+      return false;
+    });
+
+    // Runs are measured on the original lines, so a menu whose items were
+    // already dropped as repeats still counts towards the run around them.
+    const isNavLine = (line) => line.length <= 30 && isShort(line) && !/\d/.test(line);
+    let run = [];
+    const flush = () => {
+      if (run.length >= 4) for (const i of run) drop[i] = true;
+      run = [];
+    };
+    lines.forEach((raw, i) => {
+      const line = raw.trim();
+      if (!line) return;
+      if (isNavLine(line) || drop[i]) run.push(i);
+      else flush();
+    });
+    flush();
+
+    const cleaned = lines.filter((_, i) => !drop[i]).join('\n').replace(/\n{3,}/g, '\n\n').trim();
+    return cleaned.length >= 10 ? cleaned : text;
+  }
+
+  /**
+   * End each unpunctuated line with a full stop when the next line starts a
+   * new unit (a capital, digit, quote or currency sign). Headlines, titles and
+   * prices carry no terminator, so without this the sentence splitter glued a
+   * whole column of them into one "sentence" — the books listing's summary
+   * was a run of prices. A next line starting in lower case is a wrapped
+   * sentence and is left alone; CJK has no capitals and is never touched.
+   * @param {string} text
+   * @returns {string}
+   */
+  terminateLines(text) {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trimEnd();
+      if (!line.trim() || /[.!?…。！？:;,]$/.test(line)) continue;
+      const next = lines.slice(i + 1).find((l) => l.trim());
+      if (next && /^[\p{Lu}\p{N}£$€'"‘“(]/u.test(next.trim())) lines[i] = `${line}.`;
+    }
+    return lines.join('\n');
+  }
+
   /**
    * Extract key points from original text and summary
    * @param {string} originalText - Original text

package/src/tools/llmstxt/generateLLMsTxt.js

@@ -740,9 +740,9 @@ export class GenerateLLMsTxtTool {
     lines.push('If you encounter issues or need clarification on these guidelines:');
     lines.push('1. Check this document for guidance');
     lines.push('2. Review the basic llms.txt file');
-    // Only when section 1 printed something to contact: without either field
-    // this pointed at contact information the file did not contain.
-    if (outputOptions.contactEmail || outputOptions.organizationName) {
+    // Only when the section above lists a contact: an organization name
+    // alone is not one, and without an email it is empty (live sweep 4.4).
+    if (outputOptions.contactEmail) {
       lines.push('3. Contact us using the information above');
     }
     lines.push('');
@@ -833,8 +833,9 @@ export class GenerateLLMsTxtTool {
       });
     }
 
-    // API recommendations
-    if (analysis.apis && analysis.apis.length > 0) {
+    // API recommendations: only endpoints that answered JSON/XML, not links
+    // to API documentation pages.
+    if (analysis.apis && analysis.apis.some((api) => api.type !== 'documentation')) {
       recommendations.push({
         type: 'integration',
         priority: 'high',

package/src/tools/result/readResult.js

@@ -10,7 +10,6 @@
  */
 
 import { z } from 'zod';
-import { selectJsonPath } from 'crawlforge-extractors';
 import { getResultStore, RESULT_HANDLE_PATTERN } from '../../core/ResultStore.js';
 import { MAX_INLINE_CHARS_PARAM, resolveMaxInlineChars, resultTextView } from '../../server/inlineThreshold.js';
 import { dualOutput } from '../../server/registerTool.js';
@@ -27,7 +26,7 @@ export const READ_RESULT_INPUT_SHAPE = {
   length: z.number().int().min(1).max(200000).optional().describe("slice: characters to return (default 10,000); lines: lines to return (default 200, max 5,000)"),
   query: z.string().min(1).max(500).optional().describe("search: the text to find, matched literally, case-insensitive"),
   max_matches: z.number().int().min(1).max(100).optional().default(20).describe("search: matches to return (default 20)"),
-  path: z.string().optional().describe("json_path: dotted keys and array indexes, e.g. \"results[3].content\" — not JSONPath"),
+  path: z.string().optional().describe("json_path: dotted keys and array indexes from the root of the stored result, e.g. \"results[3].content\"; a key holding a \".\" in brackets, e.g. files[\"llms.txt\"]; a JSON string field is read into, e.g. \"body.items[0]\" for a fetch_url JSON body — not JSONPath"),
   ...MAX_INLINE_CHARS_PARAM
 };
 
@@ -57,6 +56,81 @@ export function goneMessage(store, handle) {
       return `Result handle deleted by the server at ${at}.`;
   }
 }
+/**
+ * Split a json_path into keys: dotted keys, [0] indexes, [key] and the
+ * bracket-quoted ["a.b"] / ['a.b'], whose key may hold a ".".
+ */
+export function parseResultPath(path) {
+  const segments = [];
+  let i = 0;
+  while (i < path.length) {
+    if (path[i] === '.') { i++; continue; }
+    if (path[i] === '[') {
+      const quote = path[i + 1];
+      if (quote === '"' || quote === "'") {
+        const close = path.indexOf(`${quote}]`, i + 2);
+        if (close === -1) throw new Error(`Path "${path}" has an unclosed ${quote} key: write it as [${quote}key${quote}]`);
+        segments.push(path.slice(i + 2, close));
+        i = close + 2;
+      } else {
+        const close = path.indexOf(']', i);
+        const end = close === -1 ? path.length : close;
+        segments.push(path.slice(i + 1, end));
+        i = end + 1;
+      }
+      continue;
+    }
+    let end = i;
+    while (end < path.length && path[end] !== '.' && path[end] !== '[') end++;
+    segments.push(path.slice(i, end));
+    i = end;
+  }
+  return segments.filter((segment) => segment !== '');
+}
+
+function describeKeys(value) {
+  if (Array.isArray(value)) return `array of length ${value.length}`;
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value);
+    return `available keys: ${keys.slice(0, 25).join(', ')}${keys.length > 25 ? `, … (${keys.length} total)` : ''}`;
+  }
+  return `a ${value === null ? 'null' : typeof value} value, which has no keys`;
+}
+
+/**
+ * Resolve a json_path from the root of the stored result. A string holding
+ * JSON (a fetch_url body) is parsed when the path goes on into it.
+ * @throws {Error} "path not found", naming the keys where it stopped and the
+ *   result's top-level keys
+ */
+export function selectResultPath(root, path) {
+  const segments = parseResultPath(path);
+  if (segments.length === 0) throw new Error(`Path "${path}" is empty`);
+  let current = root;
+  const walked = [];
+  for (const segment of segments) {
+    if (typeof current === 'string' && /^\s*[[{]/.test(current)) {
+      try { current = JSON.parse(current); } catch { /* not JSON: a string has no keys */ }
+    }
+    const container = current !== null && typeof current === 'object';
+    const key = Array.isArray(current) ? Number(segment) : segment;
+    if (!container || !Object.hasOwn(current, key)) {
+      const at = walked.length === 0 ? 'the result' : `"${walked.join('.')}"`;
+      const top = walked.length === 0 ? '' : `; the stored result's top-level keys: ${Object.keys(root).join(', ')}`;
+      throw new Error(`Path "${path}" not found: ${at} has no "${segment}" (${describeKeys(current)})${top}`);
+    }
+    current = current[key];
+    walked.push(segment);
+  }
+  return current;
+}
+
+// A bad path on a live handle names its own next step, so withAuth does not
+// append read_result's hint for a handle that is gone.
+const PATH_NEXT_STEP = 'Next step: the handle is still valid - call read_result operation "json_path" again with a path '
+  + 'from the keys above. Paths start at the stored result (a fetch_url body is under "body."), and a key holding '
+  + 'a "." goes in brackets, e.g. files["llms.txt"].';
+
 // read_result declares an outputSchema, so a success carries structuredContent too.
 const ok = (object) => dualOutput(object);
 
@@ -140,17 +214,12 @@ export async function readResultHandler(params) {
     case 'json_path': {
       const { path } = params;
       if (!path) return fail('path is required for operation "json_path"');
-      // A text view whose text is itself JSON (a fetch_url body) is read as
-      // that JSON; otherwise the stored result object is the subject.
-      let subject = entry.payload;
-      if (view === 'text') {
-        try { subject = JSON.parse(text); } catch { /* not JSON: address the result object */ }
-      }
+      // One root for every tool: the whole stored result (live sweep 4.3).
       let value;
       try {
-        value = selectJsonPath(subject, path);
+        value = selectResultPath(entry.payload, path);
       } catch (error) {
-        return fail(error.message);
+        return fail(`${error.message}\n${PATH_NEXT_STEP}`);
       }
       const valueJson = JSON.stringify(value) ?? 'null';
       if (valueJson.length > maxChars) {