@probelabs/probe 0.6.0-rc240 → 0.6.0-rc241

package/build/agent/dsl/validator.js

@@ -9,6 +9,81 @@
 import * as acorn from 'acorn';
 import * as walk from 'acorn-walk';
 
+/**
+ * Convert a character offset to line and column numbers.
+ * @param {string} code - The source code
+ * @param {number} offset - Character offset
+ * @returns {{ line: number, column: number }}
+ */
+function offsetToLineColumn(code, offset) {
+  const lines = code.split('\n');
+  let pos = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const lineLength = lines[i].length + 1; // +1 for newline
+    if (pos + lineLength > offset) {
+      return { line: i + 1, column: offset - pos + 1 };
+    }
+    pos += lineLength;
+  }
+  return { line: lines.length, column: 1 };
+}
+
+/**
+ * Generate a code snippet with an arrow pointing to the error location.
+ * @param {string} code - The source code
+ * @param {number} line - Line number (1-based)
+ * @param {number} column - Column number (1-based)
+ * @param {number} contextLines - Number of lines to show before/after (default: 2)
+ * @returns {string}
+ */
+function generateErrorSnippet(code, line, column, contextLines = 2) {
+  const lines = code.split('\n');
+  const startLine = Math.max(0, line - 1 - contextLines);
+  const endLine = Math.min(lines.length, line + contextLines);
+
+  const snippetLines = [];
+  const lineNumWidth = String(endLine).length;
+
+  for (let i = startLine; i < endLine; i++) {
+    const lineNum = String(i + 1).padStart(lineNumWidth, ' ');
+    const marker = (i + 1 === line) ? '>' : ' ';
+    snippetLines.push(`${marker} ${lineNum} | ${lines[i]}`);
+
+    // Add arrow line for the error line
+    if (i + 1 === line) {
+      const padding = ' '.repeat(lineNumWidth + 4); // "  123 | " prefix
+      const arrow = ' '.repeat(Math.max(0, column - 1)) + '^';
+      snippetLines.push(`${padding}${arrow}`);
+    }
+  }
+
+  return snippetLines.join('\n');
+}
+
+/**
+ * Format an error message with code snippet.
+ * @param {string} message - The error message
+ * @param {string} code - The source code
+ * @param {number} offset - Character offset (optional, use -1 if line/column provided)
+ * @param {number} line - Line number (optional)
+ * @param {number} column - Column number (optional)
+ * @returns {string}
+ */
+function formatErrorWithSnippet(message, code, offset = -1, line = 0, column = 0) {
+  if (offset >= 0) {
+    const loc = offsetToLineColumn(code, offset);
+    line = loc.line;
+    column = loc.column;
+  }
+
+  if (line <= 0) {
+    return message;
+  }
+
+  const snippet = generateErrorSnippet(code, line, column);
+  return `${message}\n\n${snippet}`;
+}
+
 // Node types the LLM is allowed to generate
 const ALLOWED_NODE_TYPES = new Set([
   'Program',
@@ -102,16 +177,32 @@ export function validateDSL(code) {
       ecmaVersion: 2022,
       sourceType: 'script',
       allowReturnOutsideFunction: true,
+      locations: true, // Enable location tracking for better error messages
     });
   } catch (e) {
-    return { valid: false, errors: [`Syntax error: ${e.message}`] };
+    // Acorn errors have loc property with line/column
+    const line = e.loc?.line || 0;
+    const column = e.loc?.column ? e.loc.column + 1 : 0; // Acorn column is 0-based
+    const formattedError = formatErrorWithSnippet(
+      `Syntax error: ${e.message}`,
+      code,
+      -1,
+      line,
+      column
+    );
+    return { valid: false, errors: [formattedError] };
   }
 
+  // Helper to add error with code snippet
+  const addError = (message, position) => {
+    errors.push(formatErrorWithSnippet(message, code, position));
+  };
+
   // Step 2: Walk every node and validate
   walk.full(ast, (node) => {
     // Check node type against whitelist
     if (!ALLOWED_NODE_TYPES.has(node.type)) {
-      errors.push(`Blocked node type: ${node.type} at position ${node.start}`);
+      addError(`Blocked node type: ${node.type}`, node.start);
       return;
     }
 
@@ -121,7 +212,7 @@ export function validateDSL(code) {
         node.type === 'FunctionExpression') &&
       node.async
     ) {
-      errors.push(`Async functions are not allowed at position ${node.start}. Write synchronous code — the runtime handles async.`);
+      addError(`Async functions are not allowed. Write synchronous code — the runtime handles async.`, node.start);
     }
 
     // Block generator functions
@@ -129,19 +220,19 @@ export function validateDSL(code) {
       (node.type === 'FunctionExpression') &&
       node.generator
     ) {
-      errors.push(`Generator functions are not allowed at position ${node.start}`);
+      addError(`Generator functions are not allowed`, node.start);
     }
 
 
     // Check identifiers against blocklist
     if (node.type === 'Identifier' && BLOCKED_IDENTIFIERS.has(node.name)) {
-      errors.push(`Blocked identifier: '${node.name}' at position ${node.start}`);
+      addError(`Blocked identifier: '${node.name}'`, node.start);
     }
 
     // Check member expressions for blocked properties
     if (node.type === 'MemberExpression' && !node.computed) {
       if (node.property.type === 'Identifier' && BLOCKED_PROPERTIES.has(node.property.name)) {
-        errors.push(`Blocked property access: '.${node.property.name}' at position ${node.property.start}`);
+        addError(`Blocked property access: '.${node.property.name}'`, node.property.start);
       }
     }
 
@@ -149,7 +240,7 @@ export function validateDSL(code) {
     if (node.type === 'MemberExpression' && node.computed) {
       if (node.property.type === 'Literal' && typeof node.property.value === 'string') {
         if (BLOCKED_PROPERTIES.has(node.property.value) || BLOCKED_IDENTIFIERS.has(node.property.value)) {
-          errors.push(`Blocked computed property access: '["${node.property.value}"]' at position ${node.property.start}`);
+          addError(`Blocked computed property access: '["${node.property.value}"]'`, node.property.start);
         }
       }
     }
@@ -157,7 +248,7 @@ export function validateDSL(code) {
     // Block variable declarations named with blocked identifiers
     if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier') {
       if (BLOCKED_IDENTIFIERS.has(node.id.name)) {
-        errors.push(`Cannot declare variable with blocked name: '${node.id.name}' at position ${node.id.start}`);
+        addError(`Cannot declare variable with blocked name: '${node.id.name}'`, node.id.start);
       }
     }
   });

package/build/agent/index.js

@@ -21481,6 +21481,50 @@ var init_walk = __esm({
 });
 
 // src/agent/dsl/validator.js
+function offsetToLineColumn(code, offset2) {
+  const lines = code.split("\n");
+  let pos = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const lineLength = lines[i].length + 1;
+    if (pos + lineLength > offset2) {
+      return { line: i + 1, column: offset2 - pos + 1 };
+    }
+    pos += lineLength;
+  }
+  return { line: lines.length, column: 1 };
+}
+function generateErrorSnippet(code, line, column, contextLines = 2) {
+  const lines = code.split("\n");
+  const startLine = Math.max(0, line - 1 - contextLines);
+  const endLine = Math.min(lines.length, line + contextLines);
+  const snippetLines = [];
+  const lineNumWidth = String(endLine).length;
+  for (let i = startLine; i < endLine; i++) {
+    const lineNum = String(i + 1).padStart(lineNumWidth, " ");
+    const marker = i + 1 === line ? ">" : " ";
+    snippetLines.push(`${marker} ${lineNum} | ${lines[i]}`);
+    if (i + 1 === line) {
+      const padding = " ".repeat(lineNumWidth + 4);
+      const arrow = " ".repeat(Math.max(0, column - 1)) + "^";
+      snippetLines.push(`${padding}${arrow}`);
+    }
+  }
+  return snippetLines.join("\n");
+}
+function formatErrorWithSnippet(message, code, offset2 = -1, line = 0, column = 0) {
+  if (offset2 >= 0) {
+    const loc = offsetToLineColumn(code, offset2);
+    line = loc.line;
+    column = loc.column;
+  }
+  if (line <= 0) {
+    return message;
+  }
+  const snippet = generateErrorSnippet(code, line, column);
+  return `${message}
+
+${snippet}`;
+}
 function validateDSL(code) {
   const errors = [];
   let ast;
@@ -21488,40 +21532,54 @@ function validateDSL(code) {
     ast = parse3(code, {
       ecmaVersion: 2022,
       sourceType: "script",
-      allowReturnOutsideFunction: true
+      allowReturnOutsideFunction: true,
+      locations: true
+      // Enable location tracking for better error messages
     });
   } catch (e) {
-    return { valid: false, errors: [`Syntax error: ${e.message}`] };
+    const line = e.loc?.line || 0;
+    const column = e.loc?.column ? e.loc.column + 1 : 0;
+    const formattedError = formatErrorWithSnippet(
+      `Syntax error: ${e.message}`,
+      code,
+      -1,
+      line,
+      column
+    );
+    return { valid: false, errors: [formattedError] };
   }
+  const addError = (message, position) => {
+    errors.push(formatErrorWithSnippet(message, code, position));
+  };
   full(ast, (node) => {
     if (!ALLOWED_NODE_TYPES.has(node.type)) {
-      errors.push(`Blocked node type: ${node.type} at position ${node.start}`);
+      addError(`Blocked node type: ${node.type}`, node.start);
       return;
     }
     if ((node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") && node.async) {
-      errors.push(`Async functions are not allowed at position ${node.start}. Write synchronous code \u2014 the runtime handles async.`);
+      addError(`Async functions are not allowed. Write synchronous code \u2014 the runtime handles async.`, node.start);
     }
     if (node.type === "FunctionExpression" && node.generator) {
-      errors.push(`Generator functions are not allowed at position ${node.start}`);
+      addError(`Generator functions are not allowed`, node.start);
     }
     if (node.type === "Identifier" && BLOCKED_IDENTIFIERS.has(node.name)) {
-      errors.push(`Blocked identifier: '${node.name}' at position ${node.start}`);
+      addError(`Blocked identifier: '${node.name}'`, node.start);
     }
     if (node.type === "MemberExpression" && !node.computed) {
       if (node.property.type === "Identifier" && BLOCKED_PROPERTIES.has(node.property.name)) {
-        errors.push(`Blocked property access: '.${node.property.name}' at position ${node.property.start}`);
+        addError(`Blocked property access: '.${node.property.name}'`, node.property.start);
       }
     }
     if (node.type === "MemberExpression" && node.computed) {
       if (node.property.type === "Literal" && typeof node.property.value === "string") {
         if (BLOCKED_PROPERTIES.has(node.property.value) || BLOCKED_IDENTIFIERS.has(node.property.value)) {
-          errors.push(`Blocked computed property access: '["${node.property.value}"]' at position ${node.property.start}`);
+          addError(`Blocked computed property access: '["${node.property.value}"]'`, node.property.start);
         }
       }
     }
     if (node.type === "VariableDeclarator" && node.id.type === "Identifier") {
       if (BLOCKED_IDENTIFIERS.has(node.id.name)) {
-        errors.push(`Cannot declare variable with blocked name: '${node.id.name}' at position ${node.id.start}`);
+        addError(`Cannot declare variable with blocked name: '${node.id.name}'`, node.id.start);
       }
     }
   });
@@ -28836,10 +28894,32 @@ var init_esm5 = __esm({
 
 // src/tools/executePlan.js
 import { tool as tool4 } from "ai";
+function decodeHtmlEntities(str) {
+  const entities = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  let result = str.replace(/&(?:amp|lt|gt|quot|apos|#39|#x27);/gi, (match2) => {
+    return entities[match2.toLowerCase()] || match2;
+  });
+  result = result.replace(/&#(\d+);/g, (match2, dec) => {
+    return String.fromCharCode(parseInt(dec, 10));
+  });
+  result = result.replace(/&#x([0-9a-f]+);/gi, (match2, hex) => {
+    return String.fromCharCode(parseInt(hex, 16));
+  });
+  return result;
+}
 function stripCodeWrapping(code) {
   let s = String(code || "");
   s = s.replace(/^```(?:javascript|js)?\n?/gm, "").replace(/```$/gm, "");
   s = s.replace(/<\/?(?:execute_plan|code)>/g, "");
+  s = decodeHtmlEntities(s);
   return s.trim();
 }
 function buildToolImplementations(configOptions) {
@@ -68204,7 +68284,7 @@ __export(schemaUtils_exports, {
   createJsonCorrectionPrompt: () => createJsonCorrectionPrompt,
   createMermaidCorrectionPrompt: () => createMermaidCorrectionPrompt,
   createSchemaDefinitionCorrectionPrompt: () => createSchemaDefinitionCorrectionPrompt,
-  decodeHtmlEntities: () => decodeHtmlEntities,
+  decodeHtmlEntities: () => decodeHtmlEntities2,
   extractMermaidFromJson: () => extractMermaidFromJson,
   extractMermaidFromMarkdown: () => extractMermaidFromMarkdown,
   generateExampleFromSchema: () => generateExampleFromSchema,
@@ -68309,7 +68389,7 @@ function enforceNoAdditionalProperties(schema) {
   applyRecursively(cloned);
   return cloned;
 }
-function decodeHtmlEntities(text) {
+function decodeHtmlEntities2(text) {
   if (!text || typeof text !== "string") {
     return text;
   }
@@ -69752,7 +69832,7 @@ When presented with a broken Mermaid diagram, analyze it thoroughly and provide
        * @returns {Promise<string>} - The corrected Mermaid diagram
        */
       async fixMermaidDiagram(diagramContent, originalErrors = [], diagramInfo = {}) {
-        const decodedContent = decodeHtmlEntities(diagramContent);
+        const decodedContent = decodeHtmlEntities2(diagramContent);
         if (decodedContent !== diagramContent) {
           try {
             const quickValidation = await validateMermaidDiagram(decodedContent);

package/build/tools/executePlan.js

@@ -16,8 +16,42 @@ import { glob } from 'glob';
 
 export { executePlanSchema };
 
+/**
+ * Decode common HTML entities that LLMs sometimes produce when generating code.
+ * This handles entities like &amp;&amp; → &&, &lt;= → <=, etc.
+ */
+function decodeHtmlEntities(str) {
+  const entities = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&#39;': "'",
+    '&#x27;': "'",
+  };
+
+  // Replace named/common entities
+  let result = str.replace(/&(?:amp|lt|gt|quot|apos|#39|#x27);/gi, (match) => {
+    return entities[match.toLowerCase()] || match;
+  });
+
+  // Handle numeric entities (decimal): &#60; → <
+  result = result.replace(/&#(\d+);/g, (match, dec) => {
+    return String.fromCharCode(parseInt(dec, 10));
+  });
+
+  // Handle numeric entities (hex): &#x3C; → <
+  result = result.replace(/&#x([0-9a-f]+);/gi, (match, hex) => {
+    return String.fromCharCode(parseInt(hex, 16));
+  });
+
+  return result;
+}
+
 /**
  * Strip markdown fences and XML tags that LLMs sometimes wrap code in.
+ * Also decodes HTML entities that may appear in XML-extracted code.
  */
 function stripCodeWrapping(code) {
   let s = String(code || '');
@@ -25,6 +59,8 @@ function stripCodeWrapping(code) {
   s = s.replace(/^```(?:javascript|js)?\n?/gm, '').replace(/```$/gm, '');
   // Strip XML-style tags: <execute_plan>, </execute_plan>, <code>, </code>
   s = s.replace(/<\/?(?:execute_plan|code)>/g, '');
+  // Decode HTML entities (e.g., &amp;&amp; → &&, &lt;= → <=)
+  s = decodeHtmlEntities(s);
   return s.trim();
 }
 

package/cjs/agent/ProbeAgent.cjs

@@ -50930,6 +50930,50 @@ var init_walk = __esm({
 });
 
 // src/agent/dsl/validator.js
+function offsetToLineColumn(code, offset2) {
+  const lines = code.split("\n");
+  let pos = 0;
+  for (let i5 = 0; i5 < lines.length; i5++) {
+    const lineLength = lines[i5].length + 1;
+    if (pos + lineLength > offset2) {
+      return { line: i5 + 1, column: offset2 - pos + 1 };
+    }
+    pos += lineLength;
+  }
+  return { line: lines.length, column: 1 };
+}
+function generateErrorSnippet(code, line, column, contextLines = 2) {
+  const lines = code.split("\n");
+  const startLine = Math.max(0, line - 1 - contextLines);
+  const endLine = Math.min(lines.length, line + contextLines);
+  const snippetLines = [];
+  const lineNumWidth = String(endLine).length;
+  for (let i5 = startLine; i5 < endLine; i5++) {
+    const lineNum = String(i5 + 1).padStart(lineNumWidth, " ");
+    const marker15 = i5 + 1 === line ? ">" : " ";
+    snippetLines.push(`${marker15} ${lineNum} | ${lines[i5]}`);
+    if (i5 + 1 === line) {
+      const padding = " ".repeat(lineNumWidth + 4);
+      const arrow = " ".repeat(Math.max(0, column - 1)) + "^";
+      snippetLines.push(`${padding}${arrow}`);
+    }
+  }
+  return snippetLines.join("\n");
+}
+function formatErrorWithSnippet(message, code, offset2 = -1, line = 0, column = 0) {
+  if (offset2 >= 0) {
+    const loc = offsetToLineColumn(code, offset2);
+    line = loc.line;
+    column = loc.column;
+  }
+  if (line <= 0) {
+    return message;
+  }
+  const snippet = generateErrorSnippet(code, line, column);
+  return `${message}
+
+${snippet}`;
+}
 function validateDSL(code) {
   const errors = [];
   let ast;
@@ -50937,40 +50981,54 @@ function validateDSL(code) {
     ast = parse3(code, {
       ecmaVersion: 2022,
       sourceType: "script",
-      allowReturnOutsideFunction: true
+      allowReturnOutsideFunction: true,
+      locations: true
+      // Enable location tracking for better error messages
     });
   } catch (e5) {
-    return { valid: false, errors: [`Syntax error: ${e5.message}`] };
+    const line = e5.loc?.line || 0;
+    const column = e5.loc?.column ? e5.loc.column + 1 : 0;
+    const formattedError = formatErrorWithSnippet(
+      `Syntax error: ${e5.message}`,
+      code,
+      -1,
+      line,
+      column
+    );
+    return { valid: false, errors: [formattedError] };
   }
+  const addError = (message, position) => {
+    errors.push(formatErrorWithSnippet(message, code, position));
+  };
   full(ast, (node) => {
     if (!ALLOWED_NODE_TYPES.has(node.type)) {
-      errors.push(`Blocked node type: ${node.type} at position ${node.start}`);
+      addError(`Blocked node type: ${node.type}`, node.start);
       return;
     }
     if ((node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") && node.async) {
-      errors.push(`Async functions are not allowed at position ${node.start}. Write synchronous code \u2014 the runtime handles async.`);
+      addError(`Async functions are not allowed. Write synchronous code \u2014 the runtime handles async.`, node.start);
     }
     if (node.type === "FunctionExpression" && node.generator) {
-      errors.push(`Generator functions are not allowed at position ${node.start}`);
+      addError(`Generator functions are not allowed`, node.start);
     }
     if (node.type === "Identifier" && BLOCKED_IDENTIFIERS.has(node.name)) {
-      errors.push(`Blocked identifier: '${node.name}' at position ${node.start}`);
+      addError(`Blocked identifier: '${node.name}'`, node.start);
     }
     if (node.type === "MemberExpression" && !node.computed) {
       if (node.property.type === "Identifier" && BLOCKED_PROPERTIES.has(node.property.name)) {
-        errors.push(`Blocked property access: '.${node.property.name}' at position ${node.property.start}`);
+        addError(`Blocked property access: '.${node.property.name}'`, node.property.start);
       }
     }
     if (node.type === "MemberExpression" && node.computed) {
       if (node.property.type === "Literal" && typeof node.property.value === "string") {
         if (BLOCKED_PROPERTIES.has(node.property.value) || BLOCKED_IDENTIFIERS.has(node.property.value)) {
-          errors.push(`Blocked computed property access: '["${node.property.value}"]' at position ${node.property.start}`);
+          addError(`Blocked computed property access: '["${node.property.value}"]'`, node.property.start);
         }
       }
     }
     if (node.type === "VariableDeclarator" && node.id.type === "Identifier") {
       if (BLOCKED_IDENTIFIERS.has(node.id.name)) {
-        errors.push(`Cannot declare variable with blocked name: '${node.id.name}' at position ${node.id.start}`);
+        addError(`Cannot declare variable with blocked name: '${node.id.name}'`, node.id.start);
       }
     }
   });
@@ -58284,10 +58342,32 @@ var init_esm5 = __esm({
 });
 
 // src/tools/executePlan.js
+function decodeHtmlEntities(str) {
+  const entities = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  let result = str.replace(/&(?:amp|lt|gt|quot|apos|#39|#x27);/gi, (match2) => {
+    return entities[match2.toLowerCase()] || match2;
+  });
+  result = result.replace(/&#(\d+);/g, (match2, dec) => {
+    return String.fromCharCode(parseInt(dec, 10));
+  });
+  result = result.replace(/&#x([0-9a-f]+);/gi, (match2, hex) => {
+    return String.fromCharCode(parseInt(hex, 16));
+  });
+  return result;
+}
 function stripCodeWrapping(code) {
   let s5 = String(code || "");
   s5 = s5.replace(/^```(?:javascript|js)?\n?/gm, "").replace(/```$/gm, "");
   s5 = s5.replace(/<\/?(?:execute_plan|code)>/g, "");
+  s5 = decodeHtmlEntities(s5);
   return s5.trim();
 }
 function buildToolImplementations(configOptions) {
@@ -97220,7 +97300,7 @@ __export(schemaUtils_exports, {
   createJsonCorrectionPrompt: () => createJsonCorrectionPrompt,
   createMermaidCorrectionPrompt: () => createMermaidCorrectionPrompt,
   createSchemaDefinitionCorrectionPrompt: () => createSchemaDefinitionCorrectionPrompt,
-  decodeHtmlEntities: () => decodeHtmlEntities,
+  decodeHtmlEntities: () => decodeHtmlEntities2,
   extractMermaidFromJson: () => extractMermaidFromJson,
   extractMermaidFromMarkdown: () => extractMermaidFromMarkdown,
   generateExampleFromSchema: () => generateExampleFromSchema,
@@ -97325,7 +97405,7 @@ function enforceNoAdditionalProperties(schema) {
   applyRecursively(cloned);
   return cloned;
 }
-function decodeHtmlEntities(text) {
+function decodeHtmlEntities2(text) {
   if (!text || typeof text !== "string") {
     return text;
   }
@@ -98768,7 +98848,7 @@ When presented with a broken Mermaid diagram, analyze it thoroughly and provide
        * @returns {Promise<string>} - The corrected Mermaid diagram
        */
       async fixMermaidDiagram(diagramContent, originalErrors = [], diagramInfo = {}) {
-        const decodedContent = decodeHtmlEntities(diagramContent);
+        const decodedContent = decodeHtmlEntities2(diagramContent);
         if (decodedContent !== diagramContent) {
           try {
             const quickValidation = await validateMermaidDiagram(decodedContent);

package/cjs/index.cjs

@@ -112384,6 +112384,50 @@ var init_walk = __esm({
 });
 
 // src/agent/dsl/validator.js
+function offsetToLineColumn(code, offset2) {
+  const lines = code.split("\n");
+  let pos = 0;
+  for (let i5 = 0; i5 < lines.length; i5++) {
+    const lineLength = lines[i5].length + 1;
+    if (pos + lineLength > offset2) {
+      return { line: i5 + 1, column: offset2 - pos + 1 };
+    }
+    pos += lineLength;
+  }
+  return { line: lines.length, column: 1 };
+}
+function generateErrorSnippet(code, line, column, contextLines = 2) {
+  const lines = code.split("\n");
+  const startLine = Math.max(0, line - 1 - contextLines);
+  const endLine = Math.min(lines.length, line + contextLines);
+  const snippetLines = [];
+  const lineNumWidth = String(endLine).length;
+  for (let i5 = startLine; i5 < endLine; i5++) {
+    const lineNum = String(i5 + 1).padStart(lineNumWidth, " ");
+    const marker15 = i5 + 1 === line ? ">" : " ";
+    snippetLines.push(`${marker15} ${lineNum} | ${lines[i5]}`);
+    if (i5 + 1 === line) {
+      const padding = " ".repeat(lineNumWidth + 4);
+      const arrow = " ".repeat(Math.max(0, column - 1)) + "^";
+      snippetLines.push(`${padding}${arrow}`);
+    }
+  }
+  return snippetLines.join("\n");
+}
+function formatErrorWithSnippet(message, code, offset2 = -1, line = 0, column = 0) {
+  if (offset2 >= 0) {
+    const loc = offsetToLineColumn(code, offset2);
+    line = loc.line;
+    column = loc.column;
+  }
+  if (line <= 0) {
+    return message;
+  }
+  const snippet = generateErrorSnippet(code, line, column);
+  return `${message}
+
+${snippet}`;
+}
 function validateDSL(code) {
   const errors = [];
   let ast;
@@ -112391,40 +112435,54 @@ function validateDSL(code) {
     ast = parse8(code, {
       ecmaVersion: 2022,
       sourceType: "script",
-      allowReturnOutsideFunction: true
+      allowReturnOutsideFunction: true,
+      locations: true
+      // Enable location tracking for better error messages
     });
   } catch (e5) {
-    return { valid: false, errors: [`Syntax error: ${e5.message}`] };
+    const line = e5.loc?.line || 0;
+    const column = e5.loc?.column ? e5.loc.column + 1 : 0;
+    const formattedError = formatErrorWithSnippet(
+      `Syntax error: ${e5.message}`,
+      code,
+      -1,
+      line,
+      column
+    );
+    return { valid: false, errors: [formattedError] };
   }
+  const addError = (message, position) => {
+    errors.push(formatErrorWithSnippet(message, code, position));
+  };
   full(ast, (node) => {
     if (!ALLOWED_NODE_TYPES.has(node.type)) {
-      errors.push(`Blocked node type: ${node.type} at position ${node.start}`);
+      addError(`Blocked node type: ${node.type}`, node.start);
       return;
     }
     if ((node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") && node.async) {
-      errors.push(`Async functions are not allowed at position ${node.start}. Write synchronous code \u2014 the runtime handles async.`);
+      addError(`Async functions are not allowed. Write synchronous code \u2014 the runtime handles async.`, node.start);
     }
     if (node.type === "FunctionExpression" && node.generator) {
-      errors.push(`Generator functions are not allowed at position ${node.start}`);
+      addError(`Generator functions are not allowed`, node.start);
     }
     if (node.type === "Identifier" && BLOCKED_IDENTIFIERS.has(node.name)) {
-      errors.push(`Blocked identifier: '${node.name}' at position ${node.start}`);
+      addError(`Blocked identifier: '${node.name}'`, node.start);
     }
     if (node.type === "MemberExpression" && !node.computed) {
       if (node.property.type === "Identifier" && BLOCKED_PROPERTIES.has(node.property.name)) {
-        errors.push(`Blocked property access: '.${node.property.name}' at position ${node.property.start}`);
+        addError(`Blocked property access: '.${node.property.name}'`, node.property.start);
       }
     }
     if (node.type === "MemberExpression" && node.computed) {
       if (node.property.type === "Literal" && typeof node.property.value === "string") {
         if (BLOCKED_PROPERTIES.has(node.property.value) || BLOCKED_IDENTIFIERS.has(node.property.value)) {
-          errors.push(`Blocked computed property access: '["${node.property.value}"]' at position ${node.property.start}`);
+          addError(`Blocked computed property access: '["${node.property.value}"]'`, node.property.start);
         }
       }
     }
     if (node.type === "VariableDeclarator" && node.id.type === "Identifier") {
       if (BLOCKED_IDENTIFIERS.has(node.id.name)) {
-        errors.push(`Cannot declare variable with blocked name: '${node.id.name}' at position ${node.id.start}`);
+        addError(`Cannot declare variable with blocked name: '${node.id.name}'`, node.id.start);
       }
     }
   });
@@ -113055,10 +113113,32 @@ var init_runtime = __esm({
 });
 
 // src/tools/executePlan.js
+function decodeHtmlEntities2(str) {
+  const entities = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  let result = str.replace(/&(?:amp|lt|gt|quot|apos|#39|#x27);/gi, (match2) => {
+    return entities[match2.toLowerCase()] || match2;
+  });
+  result = result.replace(/&#(\d+);/g, (match2, dec) => {
+    return String.fromCharCode(parseInt(dec, 10));
+  });
+  result = result.replace(/&#x([0-9a-f]+);/gi, (match2, hex) => {
+    return String.fromCharCode(parseInt(hex, 16));
+  });
+  return result;
+}
 function stripCodeWrapping(code) {
   let s5 = String(code || "");
   s5 = s5.replace(/^```(?:javascript|js)?\n?/gm, "").replace(/```$/gm, "");
   s5 = s5.replace(/<\/?(?:execute_plan|code)>/g, "");
+  s5 = decodeHtmlEntities2(s5);
   return s5.trim();
 }
 function buildToolImplementations(configOptions) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc240",
+  "version": "0.6.0-rc241",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/agent/dsl/validator.js

@@ -9,6 +9,81 @@
 import * as acorn from 'acorn';
 import * as walk from 'acorn-walk';
 
+/**
+ * Convert a character offset to line and column numbers.
+ * @param {string} code - The source code
+ * @param {number} offset - Character offset
+ * @returns {{ line: number, column: number }}
+ */
+function offsetToLineColumn(code, offset) {
+  const lines = code.split('\n');
+  let pos = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const lineLength = lines[i].length + 1; // +1 for newline
+    if (pos + lineLength > offset) {
+      return { line: i + 1, column: offset - pos + 1 };
+    }
+    pos += lineLength;
+  }
+  return { line: lines.length, column: 1 };
+}
+
+/**
+ * Generate a code snippet with an arrow pointing to the error location.
+ * @param {string} code - The source code
+ * @param {number} line - Line number (1-based)
+ * @param {number} column - Column number (1-based)
+ * @param {number} contextLines - Number of lines to show before/after (default: 2)
+ * @returns {string}
+ */
+function generateErrorSnippet(code, line, column, contextLines = 2) {
+  const lines = code.split('\n');
+  const startLine = Math.max(0, line - 1 - contextLines);
+  const endLine = Math.min(lines.length, line + contextLines);
+
+  const snippetLines = [];
+  const lineNumWidth = String(endLine).length;
+
+  for (let i = startLine; i < endLine; i++) {
+    const lineNum = String(i + 1).padStart(lineNumWidth, ' ');
+    const marker = (i + 1 === line) ? '>' : ' ';
+    snippetLines.push(`${marker} ${lineNum} | ${lines[i]}`);
+
+    // Add arrow line for the error line
+    if (i + 1 === line) {
+      const padding = ' '.repeat(lineNumWidth + 4); // "  123 | " prefix
+      const arrow = ' '.repeat(Math.max(0, column - 1)) + '^';
+      snippetLines.push(`${padding}${arrow}`);
+    }
+  }
+
+  return snippetLines.join('\n');
+}
+
+/**
+ * Format an error message with code snippet.
+ * @param {string} message - The error message
+ * @param {string} code - The source code
+ * @param {number} offset - Character offset (optional, use -1 if line/column provided)
+ * @param {number} line - Line number (optional)
+ * @param {number} column - Column number (optional)
+ * @returns {string}
+ */
+function formatErrorWithSnippet(message, code, offset = -1, line = 0, column = 0) {
+  if (offset >= 0) {
+    const loc = offsetToLineColumn(code, offset);
+    line = loc.line;
+    column = loc.column;
+  }
+
+  if (line <= 0) {
+    return message;
+  }
+
+  const snippet = generateErrorSnippet(code, line, column);
+  return `${message}\n\n${snippet}`;
+}
+
 // Node types the LLM is allowed to generate
 const ALLOWED_NODE_TYPES = new Set([
   'Program',
@@ -102,16 +177,32 @@ export function validateDSL(code) {
       ecmaVersion: 2022,
       sourceType: 'script',
       allowReturnOutsideFunction: true,
+      locations: true, // Enable location tracking for better error messages
     });
   } catch (e) {
-    return { valid: false, errors: [`Syntax error: ${e.message}`] };
+    // Acorn errors have loc property with line/column
+    const line = e.loc?.line || 0;
+    const column = e.loc?.column ? e.loc.column + 1 : 0; // Acorn column is 0-based
+    const formattedError = formatErrorWithSnippet(
+      `Syntax error: ${e.message}`,
+      code,
+      -1,
+      line,
+      column
+    );
+    return { valid: false, errors: [formattedError] };
   }
 
+  // Helper to add error with code snippet
+  const addError = (message, position) => {
+    errors.push(formatErrorWithSnippet(message, code, position));
+  };
+
   // Step 2: Walk every node and validate
   walk.full(ast, (node) => {
     // Check node type against whitelist
     if (!ALLOWED_NODE_TYPES.has(node.type)) {
-      errors.push(`Blocked node type: ${node.type} at position ${node.start}`);
+      addError(`Blocked node type: ${node.type}`, node.start);
       return;
     }
 
@@ -121,7 +212,7 @@ export function validateDSL(code) {
         node.type === 'FunctionExpression') &&
       node.async
     ) {
-      errors.push(`Async functions are not allowed at position ${node.start}. Write synchronous code — the runtime handles async.`);
+      addError(`Async functions are not allowed. Write synchronous code — the runtime handles async.`, node.start);
     }
 
     // Block generator functions
@@ -129,19 +220,19 @@ export function validateDSL(code) {
       (node.type === 'FunctionExpression') &&
       node.generator
     ) {
-      errors.push(`Generator functions are not allowed at position ${node.start}`);
+      addError(`Generator functions are not allowed`, node.start);
     }
 
 
     // Check identifiers against blocklist
     if (node.type === 'Identifier' && BLOCKED_IDENTIFIERS.has(node.name)) {
-      errors.push(`Blocked identifier: '${node.name}' at position ${node.start}`);
+      addError(`Blocked identifier: '${node.name}'`, node.start);
     }
 
     // Check member expressions for blocked properties
     if (node.type === 'MemberExpression' && !node.computed) {
       if (node.property.type === 'Identifier' && BLOCKED_PROPERTIES.has(node.property.name)) {
-        errors.push(`Blocked property access: '.${node.property.name}' at position ${node.property.start}`);
+        addError(`Blocked property access: '.${node.property.name}'`, node.property.start);
       }
     }
 
@@ -149,7 +240,7 @@ export function validateDSL(code) {
     if (node.type === 'MemberExpression' && node.computed) {
       if (node.property.type === 'Literal' && typeof node.property.value === 'string') {
         if (BLOCKED_PROPERTIES.has(node.property.value) || BLOCKED_IDENTIFIERS.has(node.property.value)) {
-          errors.push(`Blocked computed property access: '["${node.property.value}"]' at position ${node.property.start}`);
+          addError(`Blocked computed property access: '["${node.property.value}"]'`, node.property.start);
         }
       }
     }
@@ -157,7 +248,7 @@ export function validateDSL(code) {
     // Block variable declarations named with blocked identifiers
     if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier') {
       if (BLOCKED_IDENTIFIERS.has(node.id.name)) {
-        errors.push(`Cannot declare variable with blocked name: '${node.id.name}' at position ${node.id.start}`);
+        addError(`Cannot declare variable with blocked name: '${node.id.name}'`, node.id.start);
       }
     }
   });

package/src/tools/executePlan.js

@@ -16,8 +16,42 @@ import { glob } from 'glob';
 
 export { executePlanSchema };
 
+/**
+ * Decode common HTML entities that LLMs sometimes produce when generating code.
+ * This handles entities like &amp;&amp; → &&, &lt;= → <=, etc.
+ */
+function decodeHtmlEntities(str) {
+  const entities = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&#39;': "'",
+    '&#x27;': "'",
+  };
+
+  // Replace named/common entities
+  let result = str.replace(/&(?:amp|lt|gt|quot|apos|#39|#x27);/gi, (match) => {
+    return entities[match.toLowerCase()] || match;
+  });
+
+  // Handle numeric entities (decimal): &#60; → <
+  result = result.replace(/&#(\d+);/g, (match, dec) => {
+    return String.fromCharCode(parseInt(dec, 10));
+  });
+
+  // Handle numeric entities (hex): &#x3C; → <
+  result = result.replace(/&#x([0-9a-f]+);/gi, (match, hex) => {
+    return String.fromCharCode(parseInt(hex, 16));
+  });
+
+  return result;
+}
+
 /**
  * Strip markdown fences and XML tags that LLMs sometimes wrap code in.
+ * Also decodes HTML entities that may appear in XML-extracted code.
  */
 function stripCodeWrapping(code) {
   let s = String(code || '');
@@ -25,6 +59,8 @@ function stripCodeWrapping(code) {
   s = s.replace(/^```(?:javascript|js)?\n?/gm, '').replace(/```$/gm, '');
   // Strip XML-style tags: <execute_plan>, </execute_plan>, <code>, </code>
   s = s.replace(/<\/?(?:execute_plan|code)>/g, '');
+  // Decode HTML entities (e.g., &amp;&amp; → &&, &lt;= → <=)
+  s = decodeHtmlEntities(s);
   return s.trim();
 }