@probelabs/probe 0.6.0-rc239 → 0.6.0-rc241

package/cjs/index.cjs

@@ -38518,7 +38518,7 @@ function resolveTargetPath(target, cwd) {
   }
   return filePart + suffix;
 }
-var import_path6, searchSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, bashSchema, analyzeAllSchema, executePlanSchema, attemptCompletionSchema, searchToolDefinition, queryToolDefinition, extractToolDefinition, delegateToolDefinition, attemptCompletionToolDefinition, analyzeAllToolDefinition, bashToolDefinition, googleSearchToolDefinition, urlContextToolDefinition, searchDescription, queryDescription, extractDescription, delegateDescription, bashDescription, analyzeAllDescription, DEFAULT_VALID_TOOLS;
+var import_path6, searchSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, bashSchema, analyzeAllSchema, executePlanSchema, cleanupExecutePlanSchema, attemptCompletionSchema, searchToolDefinition, queryToolDefinition, extractToolDefinition, delegateToolDefinition, attemptCompletionToolDefinition, analyzeAllToolDefinition, bashToolDefinition, googleSearchToolDefinition, urlContextToolDefinition, searchDescription, queryDescription, extractDescription, delegateDescription, bashDescription, analyzeAllDescription, DEFAULT_VALID_TOOLS;
 var init_common2 = __esm({
   "src/tools/common.js"() {
     "use strict";
@@ -38567,6 +38567,10 @@ var init_common2 = __esm({
       code: external_exports.string().min(1).describe("JavaScript DSL code to execute. All function calls look synchronous \u2014 do NOT use async/await. Use map(items, fn) for batch operations. Use LLM(instruction, data) for AI processing."),
       description: external_exports.string().optional().describe("Human-readable description of what this plan does, for logging.")
     });
+    cleanupExecutePlanSchema = external_exports.object({
+      clearOutputBuffer: external_exports.boolean().optional().default(true).describe("Clear the output buffer from previous execute_plan calls"),
+      clearSessionStore: external_exports.boolean().optional().default(false).describe("Clear the session store (persisted data across execute_plan calls)")
+    });
     attemptCompletionSchema = {
       // Custom validation that requires result parameter but allows direct XML response
       safeParse: (params) => {
@@ -38915,6 +38919,7 @@ Capabilities:
       "delegate",
       "analyze_all",
       "execute_plan",
+      "cleanup_execute_plan",
       "listSkills",
       "useSkill",
       "listFiles",
@@ -39560,6 +39565,9 @@ function createTools(configOptions) {
   }
   if (configOptions.enableExecutePlan && isToolAllowed("execute_plan")) {
     tools2.executePlanTool = createExecutePlanTool(configOptions);
+    if (isToolAllowed("cleanup_execute_plan")) {
+      tools2.cleanupExecutePlanTool = createCleanupExecutePlanTool(configOptions);
+    }
   } else if (isToolAllowed("analyze_all")) {
     tools2.analyzeAllTool = analyzeAllTool(configOptions);
   }
@@ -46478,6 +46486,13 @@ function createWrappedTools(baseTools) {
       baseTools.executePlanTool.execute
     );
   }
+  if (baseTools.cleanupExecutePlanTool) {
+    wrappedTools.cleanupExecutePlanToolInstance = wrapToolWithEmitter(
+      baseTools.cleanupExecutePlanTool,
+      "cleanup_execute_plan",
+      baseTools.cleanupExecutePlanTool.execute
+    );
+  }
   if (baseTools.bashTool) {
     wrappedTools.bashToolInstance = wrapToolWithEmitter(
       baseTools.bashTool,
@@ -83956,15 +83971,31 @@ function isSimpleTextWrapperSchema(schema) {
     return null;
   }
   const trimmed = schema.trim();
-  const simplePatterns = [
-    /^\{\s*["']?(\w+)["']?\s*:\s*["']?string["']?\s*\}$/i,
-    /^\{\s*["']?type["']?\s*:\s*["']?object["']?\s*,\s*["']?properties["']?\s*:\s*\{\s*["']?(\w+)["']?\s*:\s*\{\s*["']?type["']?\s*:\s*["']?string["']?\s*\}\s*\}\s*\}$/i
-  ];
-  for (const pattern of simplePatterns) {
-    const match2 = trimmed.match(pattern);
-    if (match2) {
-      return { fieldName: match2[1] };
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null) {
+    } else {
+      const keys2 = Object.keys(parsed);
+      if (keys2.length === 1 && parsed[keys2[0]] === "string") {
+        return { fieldName: keys2[0] };
+      }
+      if (parsed.type === "object" && parsed.properties) {
+        const propKeys = Object.keys(parsed.properties);
+        if (propKeys.length === 1) {
+          const prop = parsed.properties[propKeys[0]];
+          if (prop && prop.type === "string") {
+            return { fieldName: propKeys[0] };
+          }
+        }
+      }
+      return null;
     }
+  } catch {
+  }
+  const simplePattern = /^\{\s*["']?(\w+)["']?\s*:\s*["']?string["']?\s*\}$/i;
+  const match2 = trimmed.match(simplePattern);
+  if (match2) {
+    return { fieldName: match2[1] };
   }
   return null;
 }
@@ -96826,6 +96857,9 @@ var init_ProbeAgent = __esm({
         }
         if (this.enableExecutePlan && wrappedTools.executePlanToolInstance && isToolAllowed("execute_plan")) {
           this.toolImplementations.execute_plan = wrappedTools.executePlanToolInstance;
+          if (wrappedTools.cleanupExecutePlanToolInstance && isToolAllowed("cleanup_execute_plan")) {
+            this.toolImplementations.cleanup_execute_plan = wrappedTools.cleanupExecutePlanToolInstance;
+          }
         } else if (wrappedTools.analyzeAllToolInstance && isToolAllowed("analyze_all")) {
           this.toolImplementations.analyze_all = wrappedTools.analyzeAllToolInstance;
         }
@@ -98199,6 +98233,10 @@ Workspace: ${this.allowedFolders.join(", ")}`;
           if (this.enableBash && isToolAllowed("bash")) dslFunctions.push("bash");
           toolDefinitions += `${getExecutePlanToolDefinition(dslFunctions)}
 `;
+          if (isToolAllowed("cleanup_execute_plan")) {
+            toolDefinitions += `${getCleanupExecutePlanToolDefinition()}
+`;
+          }
         } else if (isToolAllowed("analyze_all")) {
           toolDefinitions += `${analyzeAllToolDefinition}
 `;
@@ -98274,6 +98312,9 @@ The configuration is loaded from src/config.js lines 15-25 which contains the da
         }
         if (this.enableExecutePlan && isToolAllowed("execute_plan")) {
           availableToolsList += '- execute_plan: Execute a DSL program to orchestrate tool calls. ALWAYS use this for: questions containing "all"/"every"/"comprehensive"/"complete inventory", multi-topic analysis, open-ended discovery questions, or any task requiring full codebase coverage.\n';
+          if (isToolAllowed("cleanup_execute_plan")) {
+            availableToolsList += "- cleanup_execute_plan: Clean up output buffer and session store from previous execute_plan calls.\n";
+          }
         } else if (isToolAllowed("analyze_all")) {
           availableToolsList += "- analyze_all: Process ALL data matching a query using map-reduce (for aggregate questions needing 100% coverage).\n";
         }
@@ -98500,7 +98541,7 @@ You are working with a workspace. Available paths: ${workspaceDesc}
         }
         try {
           const oldHistoryLength = this.history.length;
-          if (this._outputBuffer) {
+          if (this._outputBuffer && !options?._schemaFormatted) {
             this._outputBuffer.items = [];
           }
           if (this.enableTasks) {
@@ -98860,6 +98901,9 @@ You are working with a workspace. Available paths: ${workspaceDesc}
               }
               if (this.enableExecutePlan && this.allowedTools.isEnabled("execute_plan")) {
                 validTools.push("execute_plan");
+                if (this.allowedTools.isEnabled("cleanup_execute_plan")) {
+                  validTools.push("cleanup_execute_plan");
+                }
               } else if (this.allowedTools.isEnabled("analyze_all")) {
                 validTools.push("analyze_all");
               }
@@ -112340,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;
@@ -112347,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);
       }
     }
   });
@@ -113011,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) {
@@ -113266,6 +113390,14 @@ Logs: ${result.logs.join(" | ")}` : "";
             "dsl.error": lastError.substring(0, 1e3)
           });
         }
+        if (outputBuffer && outputBuffer.items && outputBuffer.items.length > 0) {
+          const clearedChars = outputBuffer.items.reduce((sum, item) => sum + item.length, 0);
+          outputBuffer.items = [];
+          planSpan?.addEvent?.("dsl.auto_cleanup", {
+            "cleanup.chars_cleared": clearedChars,
+            "cleanup.reason": "all_retries_exhausted"
+          });
+        }
         finalOutput = `Plan execution failed after ${maxRetries} retries.
 
 Last error: ${lastError}`;
@@ -113278,6 +113410,9 @@ Last error: ${lastError}`;
         planSpan?.end?.();
         return finalOutput;
       } catch (e5) {
+        if (outputBuffer && outputBuffer.items && outputBuffer.items.length > 0) {
+          outputBuffer.items = [];
+        }
         planSpan?.setStatus?.("ERROR");
         planSpan?.addEvent?.("exception", {
           "exception.message": e5.message,
@@ -113721,6 +113856,62 @@ output(table);
 return "Generated table with " + results.length + " items.";
 \`\`\``;
 }
+function createCleanupExecutePlanTool(options) {
+  const { outputBuffer, sessionStore, tracer } = options;
+  return (0, import_ai6.tool)({
+    description: "Clean up output buffer and session store from previous execute_plan calls. Use this when a previous execute_plan failed and left stale data, or before starting a fresh analysis.",
+    parameters: cleanupExecutePlanSchema,
+    execute: async ({ clearOutputBuffer = true, clearSessionStore = false }) => {
+      const span = tracer?.createToolSpan?.("cleanup_execute_plan", {
+        "cleanup.clear_output_buffer": clearOutputBuffer,
+        "cleanup.clear_session_store": clearSessionStore
+      }) || null;
+      const results = [];
+      try {
+        if (clearOutputBuffer && outputBuffer) {
+          const itemCount = outputBuffer.items?.length || 0;
+          const charCount = outputBuffer.items?.reduce((sum, item) => sum + item.length, 0) || 0;
+          outputBuffer.items = [];
+          results.push(`Output buffer cleared (${itemCount} items, ${charCount} chars)`);
+        }
+        if (clearSessionStore && sessionStore) {
+          const keyCount = Object.keys(sessionStore).length;
+          for (const key of Object.keys(sessionStore)) {
+            delete sessionStore[key];
+          }
+          results.push(`Session store cleared (${keyCount} keys)`);
+        }
+        const output = results.length > 0 ? `Cleanup complete:
+- ${results.join("\n- ")}` : "Nothing to clean up";
+        span?.setAttributes?.({
+          "cleanup.result": output,
+          "cleanup.success": true
+        });
+        span?.setStatus?.("OK");
+        span?.end?.();
+        return output;
+      } catch (e5) {
+        span?.setStatus?.("ERROR");
+        span?.addEvent?.("exception", { "exception.message": e5.message });
+        span?.end?.();
+        return `Cleanup failed: ${e5.message}`;
+      }
+    }
+  });
+}
+function getCleanupExecutePlanToolDefinition() {
+  return `## cleanup_execute_plan
+Description: Clean up output buffer and session store from previous execute_plan calls. Use when a previous execute_plan failed and left stale data, or before starting a fresh analysis.
+
+Parameters:
+- clearOutputBuffer: (optional, default: true) Clear the output buffer from previous execute_plan calls
+- clearSessionStore: (optional, default: false) Clear the session store (persisted data across execute_plan calls)
+
+Example:
+<cleanup_execute_plan>
+<clearOutputBuffer>true</clearOutputBuffer>
+</cleanup_execute_plan>`;
+}
 var import_ai6;
 var init_executePlan = __esm({
   "src/tools/executePlan.js"() {
@@ -113879,6 +114070,8 @@ __export(tools_exports, {
   bashTool: () => bashTool,
   bashToolDefinition: () => bashToolDefinition,
   buildToolTagPattern: () => buildToolTagPattern,
+  cleanupExecutePlanSchema: () => cleanupExecutePlanSchema,
+  createCleanupExecutePlanTool: () => createCleanupExecutePlanTool,
   createDescription: () => createDescription,
   createExecutePlanTool: () => createExecutePlanTool,
   createExtractTool: () => createExtractTool,
@@ -113898,6 +114091,7 @@ __export(tools_exports, {
   executePlanSchema: () => executePlanSchema,
   extractSchema: () => extractSchema,
   extractTool: () => extractTool,
+  getCleanupExecutePlanToolDefinition: () => getCleanupExecutePlanToolDefinition,
   getExecutePlanToolDefinition: () => getExecutePlanToolDefinition,
   parseAndResolvePaths: () => parseAndResolvePaths,
   querySchema: () => querySchema,
@@ -114522,6 +114716,8 @@ __export(index_exports, {
   bashSchema: () => bashSchema,
   bashTool: () => bashTool,
   bashToolDefinition: () => bashToolDefinition,
+  cleanupExecutePlanSchema: () => cleanupExecutePlanSchema,
+  createCleanupExecutePlanTool: () => createCleanupExecutePlanTool,
   createExecutePlanTool: () => createExecutePlanTool,
   createSchema: () => createSchema,
   createTaskTool: () => createTaskTool,
@@ -114540,6 +114736,7 @@ __export(index_exports, {
   extractTool: () => extractTool,
   extractToolDefinition: () => extractToolDefinition,
   getBinaryPath: () => getBinaryPath,
+  getCleanupExecutePlanToolDefinition: () => getCleanupExecutePlanToolDefinition,
   getExecutePlanToolDefinition: () => getExecutePlanToolDefinition,
   googleSearchToolDefinition: () => googleSearchToolDefinition,
   grep: () => grep,
@@ -114612,6 +114809,8 @@ init_index();
   bashSchema,
   bashTool,
   bashToolDefinition,
+  cleanupExecutePlanSchema,
+  createCleanupExecutePlanTool,
   createExecutePlanTool,
   createSchema,
   createTaskTool,
@@ -114630,6 +114829,7 @@ init_index();
   extractTool,
   extractToolDefinition,
   getBinaryPath,
+  getCleanupExecutePlanToolDefinition,
   getExecutePlanToolDefinition,
   googleSearchToolDefinition,
   grep,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc239",
+  "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/ProbeAgent.js

@@ -49,6 +49,7 @@ import {
   delegateToolDefinition,
   analyzeAllToolDefinition,
   getExecutePlanToolDefinition,
+  getCleanupExecutePlanToolDefinition,
   bashToolDefinition,
   listFilesToolDefinition,
   searchFilesToolDefinition,
@@ -870,6 +871,10 @@ export class ProbeAgent {
     }
     if (this.enableExecutePlan && wrappedTools.executePlanToolInstance && isToolAllowed('execute_plan')) {
       this.toolImplementations.execute_plan = wrappedTools.executePlanToolInstance;
+      // cleanup_execute_plan is enabled together with execute_plan
+      if (wrappedTools.cleanupExecutePlanToolInstance && isToolAllowed('cleanup_execute_plan')) {
+        this.toolImplementations.cleanup_execute_plan = wrappedTools.cleanupExecutePlanToolInstance;
+      }
     } else if (wrappedTools.analyzeAllToolInstance && isToolAllowed('analyze_all')) {
       // analyze_all is fallback when execute_plan is not enabled
       this.toolImplementations.analyze_all = wrappedTools.analyzeAllToolInstance;
@@ -2582,6 +2587,10 @@ ${extractGuidance}
       if (isToolAllowed('listFiles')) dslFunctions.push('listFiles');
       if (this.enableBash && isToolAllowed('bash')) dslFunctions.push('bash');
       toolDefinitions += `${getExecutePlanToolDefinition(dslFunctions)}\n`;
+      // cleanup_execute_plan is enabled together with execute_plan
+      if (isToolAllowed('cleanup_execute_plan')) {
+        toolDefinitions += `${getCleanupExecutePlanToolDefinition()}\n`;
+      }
     } else if (isToolAllowed('analyze_all')) {
       // Fallback: only register analyze_all if execute_plan is not available
       toolDefinitions += `${analyzeAllToolDefinition}\n`;
@@ -2661,6 +2670,9 @@ The configuration is loaded from src/config.js lines 15-25 which contains the da
     }
     if (this.enableExecutePlan && isToolAllowed('execute_plan')) {
       availableToolsList += '- execute_plan: Execute a DSL program to orchestrate tool calls. ALWAYS use this for: questions containing "all"/"every"/"comprehensive"/"complete inventory", multi-topic analysis, open-ended discovery questions, or any task requiring full codebase coverage.\n';
+      if (isToolAllowed('cleanup_execute_plan')) {
+        availableToolsList += '- cleanup_execute_plan: Clean up output buffer and session store from previous execute_plan calls.\n';
+      }
     } else if (isToolAllowed('analyze_all')) {
       availableToolsList += '- analyze_all: Process ALL data matching a query using map-reduce (for aggregate questions needing 100% coverage).\n';
     }
@@ -2891,8 +2903,10 @@ Follow these instructions carefully:
       // Track initial history length for storage
       const oldHistoryLength = this.history.length;
 
-      // Reset output buffer for this answer() call
-      if (this._outputBuffer) {
+      // Reset output buffer for this answer() call — but NOT during schema correction recursion
+      // When _schemaFormatted is true, this is a recursive call to fix JSON formatting,
+      // and we must preserve the output buffer so the parent call can append it
+      if (this._outputBuffer && !options?._schemaFormatted) {
         this._outputBuffer.items = [];
       }
 
@@ -3411,6 +3425,10 @@ Follow these instructions carefully:
           // Execute Plan tool (requires enableExecutePlan flag, supersedes analyze_all)
           if (this.enableExecutePlan && this.allowedTools.isEnabled('execute_plan')) {
             validTools.push('execute_plan');
+            // cleanup_execute_plan is enabled together with execute_plan
+            if (this.allowedTools.isEnabled('cleanup_execute_plan')) {
+              validTools.push('cleanup_execute_plan');
+            }
           } else if (this.allowedTools.isEnabled('analyze_all')) {
             validTools.push('analyze_all');
           }

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);
       }
     }
   });