@vybestack/llxprt-code-tools 0.10.0 → 0.11.0-nightly.260728.ffaa8d5d7

package/src/index.ts

@@ -236,6 +236,7 @@ export type {
   ToolInfoConfirmationDetails,
   ToolCallConfirmationDetails,
   ToolLocation,
+  LiveOutputUpdate,
 } from './tools/tools.js';
 
 export {
@@ -294,6 +295,7 @@ export {
   OUTPUT_UPDATE_INTERVAL_MS,
   type ShellToolParams,
 } from './tools/shell.js';
+export { buildCommandToExecute } from './tools/shell-helpers.js';
 export {
   DISCOVERED_TOOL_PREFIX,
   ToolRegistry,
@@ -428,6 +430,15 @@ export { ASTConfig } from './tools/ast-edit/ast-config.js';
 export { ASTQueryExtractor } from './tools/ast-edit/ast-query-extractor.js';
 export { RepositoryContextProvider } from './tools/ast-edit/repository-context-provider.js';
 export { validateASTSyntax } from './tools/ast-edit/edit-calculator.js';
+export {
+  summarizeAstValidation,
+  computeLineDelta,
+  findEditStartLine,
+  extractErrorLineNumber,
+  formatValidationLineLabel,
+  type AstValidationResult,
+  type AstValidationSummary,
+} from './tools/ast-edit/validation-categorizer.js';
 export {
   detectLanguage,
   extractImports,

package/src/interfaces/IShellToolHost.ts

@@ -9,6 +9,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { AnsiOutput } from '../utils/terminalSerializer.js';
+
 /**
  * Tools-owned interface for shell tool host dependencies.
  *
@@ -210,6 +212,6 @@ export interface IShellToolHost {
  */
 export interface ShellOutputEvent {
   type: 'data' | 'binary_detected' | 'binary_progress';
-  chunk?: string;
+  chunk?: string | AnsiOutput;
   bytesReceived?: number;
 }

package/src/tools/ast-edit/ast-edit-invocation.ts

@@ -32,7 +32,7 @@ import { toIdeConnectionStatus } from '../edit-utils.js';
 import { hasLspCap } from '../../interfaces/host-capabilities.js';
 import { DEFAULT_CREATE_PATCH_OPTIONS } from '../../utils/diffOptions.js';
 import { collectLspDiagnosticsBlock } from '../../utils/lsp-diagnostics-helper.js';
-import type { AnsiOutput } from '../../utils/terminalSerializer.js';
+import type { LiveOutputUpdate } from '../../utils/terminalSerializer.js';
 import { ensureParentDirectoriesExist } from '../../utils/ensure-dirs.js';
 
 import type { ASTEditToolParams } from './types.js';
@@ -44,6 +44,13 @@ import {
   getFileLastModified,
   type CalculatedEdit,
 } from './edit-calculator.js';
+import {
+  summarizeAstValidation,
+  computeLineDelta,
+  findEditStartLine,
+  formatValidationLineLabel,
+  type AstValidationResult,
+} from './validation-categorizer.js';
 
 function normalizeSeverity(severity: unknown): string {
   if (typeof severity !== 'number') {
@@ -144,6 +151,7 @@ export class ASTEditToolInvocation
       ideConfirmation,
       metadata: {
         astValidation: editData.astValidation,
+        preEditValidation: editData.preEditValidation,
         fileFreshness: editData.fileFreshness,
       },
     };
@@ -178,7 +186,7 @@ export class ASTEditToolInvocation
 
   async execute(
     signal: AbortSignal,
-    _updateOutput?: (output: string | AnsiOutput) => void,
+    _updateOutput?: (update: LiveOutputUpdate) => void,
     _terminalColumns?: number,
     _terminalRows?: number,
     _setPidCallback?: (pid: number) => void,
@@ -217,9 +225,8 @@ export class ASTEditToolInvocation
           workspaceRoot,
         );
 
-      const astValidation =
-        editData.astValidation ??
-        this.validateASTSyntax(this.params.file_path, editData.newContent);
+      const { astValidation, preEditValidation, lineDelta, editStartLine } =
+        this.computeValidationContext(editData);
 
       const fileName = path.basename(this.params.file_path);
       const fileDiff = Diff.createPatch(
@@ -234,6 +241,9 @@ export class ASTEditToolInvocation
       const editPreviewLlmContent = this.buildPreviewLlmContent(
         enhancedContext,
         astValidation,
+        preEditValidation,
+        lineDelta,
+        editStartLine,
         currentMtime,
         workspaceRoot,
       );
@@ -243,7 +253,7 @@ export class ASTEditToolInvocation
         fileName,
         originalContent: currentContent,
         newContent: editData.newContent,
-        metadata: { astValidation, currentMtime },
+        metadata: { astValidation, preEditValidation, currentMtime },
       };
 
       return {
@@ -263,20 +273,60 @@ export class ASTEditToolInvocation
     }
   }
 
+  private computeValidationContext(editData: CalculatedEdit): {
+    astValidation: { valid: boolean; errors: string[] };
+    preEditValidation: AstValidationResult | undefined;
+    lineDelta: number;
+    editStartLine: number | null;
+  } {
+    const astValidation =
+      editData.astValidation ??
+      this.validateASTSyntax(this.params.file_path, editData.newContent);
+    const preEditValidation: AstValidationResult | undefined =
+      editData.preEditValidation ??
+      (editData.currentContent !== null
+        ? this.validateASTSyntax(this.params.file_path, editData.currentContent)
+        : undefined);
+    const lineDelta = computeLineDelta(
+      this.params.old_string,
+      this.params.new_string,
+    );
+    const editStartLine = findEditStartLine(
+      editData.currentContent,
+      this.params.old_string,
+    );
+    return { astValidation, preEditValidation, lineDelta, editStartLine };
+  }
+
   private buildPreviewLlmContent(
     enhancedContext: Awaited<
       ReturnType<ASTContextCollector['collectEnhancedContext']>
     >,
     astValidation: { valid: boolean; errors: string[] },
+    preEditValidation: { valid: boolean; errors: string[] } | undefined,
+    lineDelta: number,
+    editStartLine: number | null,
     currentMtime: number | null,
     workspaceRoot: string,
   ): string {
+    const summary = summarizeAstValidation(
+      preEditValidation,
+      astValidation,
+      lineDelta,
+      editStartLine,
+    );
     return [
       `LLXPRT EDIT PREVIEW: ${this.params.file_path}`,
       `- Context: ${enhancedContext.language} file with ${enhancedContext.declarations.length} declarations`,
       `- Functions: ${enhancedContext.languageContext.functions.length}`,
       `- Classes: ${enhancedContext.languageContext.classes.length}`,
-      `- AST validation: ${astValidation.valid ? 'PASSED' : 'FAILED'}`,
+      `- AST validation: ${summary.label}`,
+      preEditValidation && !preEditValidation.valid
+        ? `- Pre-existing syntax errors: Yes${formatValidationLineLabel(preEditValidation.errors)}`
+        : '',
+      !astValidation.valid
+        ? `- AST errors: ${astValidation.errors.join(', ')}`
+        : '',
       `- Relevant snippets: ${enhancedContext.relevantSnippets.length} found`,
       enhancedContext.repositoryContext
         ? `- Repository: ${enhancedContext.repositoryContext.gitUrl}`
@@ -285,9 +335,6 @@ export class ASTEditToolInvocation
         ? `- Related files: ${enhancedContext.relatedFiles.length}`
         : '',
       this.formatConnectedFilesContext(enhancedContext, workspaceRoot),
-      !astValidation.valid
-        ? `- AST errors: ${astValidation.errors.join(', ')}`
-        : '',
       currentMtime !== null ? `- Timestamp: ${currentMtime}` : '',
       '',
       'ENHANCED CONTEXT ANALYSIS:',
@@ -408,21 +455,44 @@ export class ASTEditToolInvocation
         DEFAULT_CREATE_PATCH_OPTIONS,
       );
 
+      const { astValidation, preEditValidation, lineDelta, editStartLine } =
+        this.computeValidationContext(editData);
       const displayResult = {
         fileDiff,
         fileName,
         originalContent: editData.currentContent,
         newContent: contentToWrite,
         applied: true,
-        metadata: { astValidation: editData.astValidation },
+        metadata: {
+          astValidation,
+          preEditValidation,
+        },
       };
+      const summary = summarizeAstValidation(
+        preEditValidation,
+        astValidation,
+        lineDelta,
+        editStartLine,
+      );
 
       const llmSuccessMessageParts: string[] = [
         `Successfully applied edit to: ${this.params.file_path}`,
         `- Changes: ${editData.occurrences} replacement(s) applied`,
-        `- AST validation: ${editData.astValidation?.valid === true ? 'PASSED' : 'FAILED'}`,
+        `- AST validation: ${summary.label}`,
       ];
 
+      if (preEditValidation && !preEditValidation.valid) {
+        llmSuccessMessageParts.push(
+          `- Pre-existing syntax errors: Yes${formatValidationLineLabel(preEditValidation.errors)}${summary.newlyIntroduced ? '' : ' (not introduced by this edit)'}`,
+        );
+      }
+
+      if (summary.newlyIntroduced) {
+        llmSuccessMessageParts.push(
+          `- AST errors: ${astValidation.errors.join(', ')}`,
+        );
+      }
+
       await this.appendLspDiagnostics(llmSuccessMessageParts);
 
       return {

package/src/tools/ast-edit/ast-read-file-invocation.ts

@@ -18,7 +18,7 @@ import { makeRelative, shortenPath } from '../../utils/paths.js';
 import { isNodeError } from '../../utils/errors.js';
 import { countLines } from '../../utils/fileUtils.js';
 import type { IToolHost } from '../../interfaces/index.js';
-import type { AnsiOutput } from '../../utils/terminalSerializer.js';
+import type { LiveOutputUpdate } from '../../utils/terminalSerializer.js';
 
 import type { ASTReadFileToolParams } from './types.js';
 import { ASTConfig } from './ast-config.js';
@@ -51,7 +51,7 @@ export class ASTReadFileToolInvocation
 
   async execute(
     _signal?: AbortSignal,
-    _updateOutput?: (output: string | AnsiOutput) => void,
+    _updateOutput?: (update: LiveOutputUpdate) => void,
     _terminalColumns?: number,
     _terminalRows?: number,
     _setPidCallback?: (pid: number) => void,

package/src/tools/ast-edit/edit-calculator.ts

@@ -26,6 +26,7 @@ export interface CalculatedEdit {
   error?: { display: string; raw: string; type: ToolErrorType };
   isNewFile: boolean;
   astValidation?: { valid: boolean; errors: string[] };
+  preEditValidation?: { valid: boolean; errors: string[] };
   fileFreshness?: number | null;
 }
 
@@ -86,6 +87,14 @@ export async function calculateEdit(
     params.file_path,
   );
 
+  // Validate the original (pre-edit) content so post-edit errors can be
+  // categorized as pre-existing vs newly-introduced (issue #2124).
+  // Skipped for new files where there is no prior content to baseline.
+  const preEditValidation =
+    !noChangeError && currentContent !== null
+      ? validateASTSyntax(params.file_path, currentContent)
+      : undefined;
+
   let astValidation: { valid: boolean; errors: string[] } | undefined;
   if (!noChangeError) {
     astValidation = validateASTSyntax(params.file_path, newContent);
@@ -98,6 +107,7 @@ export async function calculateEdit(
     error: noChangeError,
     isNewFile,
     astValidation,
+    preEditValidation,
     fileFreshness: currentMtime,
   };
 }
@@ -164,6 +174,7 @@ function checkFreshness(
       },
       isNewFile: false,
       astValidation: undefined,
+      preEditValidation: undefined,
       fileFreshness: currentMtime,
     };
   }
@@ -203,6 +214,12 @@ function validateEditParams(
         raw: `Failed to edit, 0 occurrences found for old_string in ${params.file_path}. No edits made.`,
         type: ToolErrorType.EDIT_NO_OCCURRENCE_FOUND,
       };
+    } else if (occurrences > 1) {
+      error = {
+        display: `old_string appears ${occurrences} times. Include more surrounding context to target a specific occurrence.`,
+        raw: `old_string appears ${occurrences} times in ${params.file_path}. Provide more surrounding context to disambiguate.`,
+        type: ToolErrorType.EDIT_EXPECTED_OCCURRENCE_MISMATCH,
+      };
     } else if (normalizedOldString === normalizedNewString) {
       error = {
         display: `No changes to apply. The old_string and new_string are identical.`,
@@ -234,12 +251,11 @@ function checkNoChange(
 }
 
 /**
- * Counts occurrences that will be replaced (0 or 1).
- * Returns 0/1 not true count, aligned with String.replace() single-replacement semantics.
+ * Returns the true number of occurrences of searchString in content.
  *
  * @param content - File content
  * @param searchString - String to search for
- * @returns 0 if not found, 1 if found
+ * @returns Number of occurrences (0 if not found)
  */
 export function countOccurrences(
   content: string,
@@ -247,9 +263,13 @@ export function countOccurrences(
 ): number {
   if (!searchString) return 0;
 
-  // Since applyReplacement uses String.replace (single replacement),
-  // count occurrences that will actually be replaced (0 or 1)
-  return content.includes(searchString) ? 1 : 0;
+  let count = 0;
+  let idx = content.indexOf(searchString);
+  while (idx !== -1) {
+    count++;
+    idx = content.indexOf(searchString, idx + searchString.length);
+  }
+  return count;
 }
 
 /**

package/src/tools/ast-edit/validation-categorizer.ts

@@ -0,0 +1,263 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Categorizes AST validation results into pre-existing vs newly-introduced
+ * errors by comparing the pre-edit and post-edit parse trees.
+ *
+ * Background (issue #2124): tree-sitter is error-recovering and will report
+ * ERROR/MISSING nodes for any pre-existing syntax weirdness in a file. Without
+ * a baseline, every post-edit validation failure looks like the edit's fault,
+ * causing the LLM to either blindly force the edit or abandon it for a less
+ * capable tool. Comparing against the pre-edit baseline lets us tell the LLM
+ * whether the failure was already there.
+ */
+
+export type AstValidationResult = { valid: boolean; errors: string[] };
+
+export interface AstValidationSummary {
+  /** Post-edit validation status. */
+  status: 'PASSED' | 'FAILED' | 'SKIPPED';
+  /** True when the post-edit error(s) also existed in the pre-edit content. */
+  preExisting: boolean;
+  /** True when the edit likely introduced an error that did not exist before. */
+  newlyIntroduced: boolean;
+  /** One-line label suitable for LLM-facing output. */
+  label: string;
+}
+
+/**
+ * Extracts the leading line number from a validation error message such as
+ * "Syntax error at line 173, column 5". Returns null when no line is found.
+ */
+export function extractErrorLineNumber(error: string): number | null {
+  const match = /line (\d+)/i.exec(error);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+interface ErrorLocation {
+  line: number;
+  column: number;
+}
+
+function extractErrorLocation(error: string): ErrorLocation | null {
+  const match = /line (\d+), column (\d+)/i.exec(error);
+  if (!match) return null;
+  return {
+    line: parseInt(match[1], 10),
+    column: parseInt(match[2], 10),
+  };
+}
+
+/**
+ * Finds the 1-based line number where an edit begins in the original content.
+ * Returns null when the position cannot be determined (e.g. new file) or when
+ * oldString appears more than once (ambiguous — indexOf would return the first
+ * match, but the actual edit could target a different occurrence, making the
+ * computed line unreliable for shift matching).
+ */
+export function findEditStartLine(
+  content: string | null,
+  oldString: string,
+): number | null {
+  if (!content || !oldString) return null;
+  const firstIdx = content.indexOf(oldString);
+  if (firstIdx === -1) return null;
+  // Ambiguous: oldString appears more than once, so we cannot reliably
+  // determine which occurrence the edit targets. Return null to fall back
+  // to the less precise (but safe) lineDelta-based matching.
+  if (content.indexOf(oldString, firstIdx + 1) !== -1) return null;
+  return content.substring(0, firstIdx).split('\n').length;
+}
+
+/** Counts newline delimiters, which determine shifts below an edit. */
+function countLineBreaks(s: string | undefined): number {
+  if (!s) return 0;
+  return s.split('\n').length - 1;
+}
+
+/**
+ * Computes the net line delta an edit introduces. A positive value means the
+ * edit added lines (shifting errors below it downward); negative means removed.
+ */
+export function computeLineDelta(
+  oldString: string | undefined,
+  newString: string | undefined,
+): number {
+  return countLineBreaks(newString) - countLineBreaks(oldString);
+}
+
+/**
+ * Determines whether a pre-edit error line and a post-edit error line refer to
+ * the same location, accounting for line shifts caused by the edit.
+ *
+ * When the edit's start line is known, errors at or below the edit must have
+ * shifted by `lineDelta`, while errors above it did not shift — this avoids the
+ * false positive of matching a newly-introduced error to a nearby pre-existing
+ * one. The validator emits deterministic line and column coordinates, so both
+ * must match exactly after applying the known line shift.
+ *
+ * When the edit position is unknown, the two cases are made mutually exclusive
+ * based on whether `lineDelta` is zero, which is the safest fallback.
+ */
+function locationsMatch(
+  pre: ErrorLocation,
+  post: ErrorLocation,
+  lineDelta: number,
+  editStartLine: number | null,
+): boolean {
+  if (pre.column !== post.column) return false;
+
+  if (editStartLine !== null) {
+    if (pre.line > editStartLine) {
+      return pre.line + lineDelta === post.line;
+    }
+    if (pre.line === editStartLine) {
+      return false;
+    }
+    return pre.line === post.line;
+  }
+
+  return lineDelta === 0 && pre.line === post.line;
+}
+
+/**
+ * Categorizes post-edit AST validation results relative to the pre-edit
+ * baseline so the LLM understands whether failures are its fault.
+ *
+ * @param preEdit - Validation result of the original file content.
+ * @param postEdit - Validation result of the edited file content.
+ * @param lineDelta - Net lines added/removed by the edit (for shift matching).
+ * @param editStartLine - 1-based line where the edit begins (for precise matching).
+ */
+export function summarizeAstValidation(
+  preEdit: AstValidationResult | undefined,
+  postEdit: AstValidationResult | undefined,
+  lineDelta = 0,
+  editStartLine: number | null = null,
+): AstValidationSummary {
+  if (!postEdit) {
+    return {
+      status: 'SKIPPED',
+      preExisting: false,
+      newlyIntroduced: false,
+      label: 'SKIPPED (validation not performed)',
+    };
+  }
+
+  // Post-edit is valid.
+  if (postEdit.valid) {
+    if (preEdit && !preEdit.valid) {
+      return {
+        status: 'PASSED',
+        preExisting: false,
+        newlyIntroduced: false,
+        label: `PASSED (edit may have resolved pre-existing error${formatLineLabel(preEdit.errors)})`,
+      };
+    }
+    return {
+      status: 'PASSED',
+      preExisting: false,
+      newlyIntroduced: false,
+      label: 'PASSED',
+    };
+  }
+
+  // Post-edit is invalid.
+  const postErrors = postEdit.errors;
+  const preHadErrors = preEdit !== undefined && !preEdit.valid;
+
+  // Pre-edit was clean (or no baseline / new file) → the edit introduced the error.
+  if (!preHadErrors) {
+    return {
+      status: 'FAILED',
+      preExisting: false,
+      newlyIntroduced: true,
+      label: `FAILED (new error introduced by this edit${formatLineLabel(postErrors)})`,
+    };
+  }
+
+  // Both pre- and post-edit are invalid. Determine whether every post-edit
+  // error corresponds to the same location as a pre-edit one. Iterate over the
+  // raw error strings (not just those with parseable line numbers) so that
+  // unparseable post-edit errors are conservatively treated as unmatched
+  // rather than silently dropped.
+  const unmatchedPreLocations = preEdit.errors
+    .map(extractErrorLocation)
+    .filter((location): location is ErrorLocation => location !== null);
+  let matchedCount = 0;
+  let allMatched = postErrors.length > 0;
+  for (const postErr of postErrors) {
+    const postLocation = extractErrorLocation(postErr);
+    const matchingIndex =
+      postLocation === null
+        ? -1
+        : unmatchedPreLocations.findIndex((preLocation) =>
+            locationsMatch(preLocation, postLocation, lineDelta, editStartLine),
+          );
+    if (matchingIndex === -1) {
+      allMatched = false;
+      break;
+    }
+    matchedCount++;
+    unmatchedPreLocations.splice(matchingIndex, 1);
+  }
+
+  if (allMatched) {
+    return {
+      status: 'FAILED',
+      preExisting: true,
+      newlyIntroduced: false,
+      label: `FAILED (pre-existing error${formatLineLabel(postErrors)} — present before this edit)`,
+    };
+  }
+
+  // File was already broken, but the post-edit errors don't line up with the
+  // pre-existing ones. They may be cascading from the same root cause or newly
+  // introduced; surface both for the LLM to judge.
+  return formatMixedValidationSummary(
+    preEdit.errors,
+    postErrors,
+    matchedCount > 0,
+  );
+}
+
+function formatMixedValidationSummary(
+  preErrors: string[],
+  postErrors: string[],
+  hasMatchedError: boolean,
+): AstValidationSummary {
+  const preErrorNoun = preErrors.length === 1 ? 'error' : 'errors';
+  let postErrorDescription =
+    'post-edit validation failed without error details';
+  if (postErrors.length > 0) {
+    const postErrorNoun = postErrors.length === 1 ? 'error' : 'errors';
+    postErrorDescription = `post-edit ${postErrorNoun}${formatLineLabel(postErrors)} may be newly introduced`;
+  }
+  return {
+    status: 'FAILED',
+    preExisting: hasMatchedError,
+    newlyIntroduced: true,
+    label: `FAILED (file had pre-existing ${preErrorNoun}${formatLineLabel(preErrors)}; ${postErrorDescription})`,
+  };
+}
+
+function extractErrorLineNumbers(errors: string[]): number[] {
+  const lines: number[] = [];
+  for (const err of errors) {
+    const line = extractErrorLineNumber(err);
+    if (line !== null) lines.push(line);
+  }
+  return lines;
+}
+
+export function formatValidationLineLabel(errors: string[]): string {
+  const lines = extractErrorLineNumbers(errors);
+  if (lines.length === 0) return '';
+  return ` at line${lines.length > 1 ? 's' : ''} ${lines.join(', ')}`;
+}
+
+function formatLineLabel(errors: string[]): string {
+  return formatValidationLineLabel(errors);
+}

package/src/tools/codesearch.ts

@@ -23,6 +23,7 @@ import {
   Kind,
   type ToolInvocation,
   type ToolResult,
+  type LiveOutputUpdate,
 } from './tools.js';
 
 const API_CONFIG = {
@@ -140,7 +141,7 @@ class CodeSearchToolInvocation extends BaseToolInvocation<
 
   async execute(
     signal: AbortSignal,
-    _updateOutput?: (output: string) => void,
+    _updateOutput?: (update: LiveOutputUpdate) => void,
   ): Promise<ToolResult> {
     const codeRequest: McpCodeRequest = {
       jsonrpc: '2.0',

package/src/tools/direct-web-fetch.ts

@@ -14,6 +14,7 @@ import {
   Kind,
   type ToolInvocation,
   type ToolResult,
+  type LiveOutputUpdate,
 } from './tools.js';
 import { DIRECT_WEB_FETCH_TOOL } from '../types/tool-names.js';
 import { ToolErrorType } from '../types/tool-error.js';
@@ -103,7 +104,7 @@ class DirectWebFetchToolInvocation extends BaseToolInvocation<
 
   async execute(
     signal: AbortSignal,
-    _updateOutput?: (output: string) => void,
+    _updateOutput?: (update: LiveOutputUpdate) => void,
   ): Promise<ToolResult> {
     const protocolError = this.validateUrlProtocol();
     if (protocolError) return protocolError;

package/src/tools/exa-web-search.ts

@@ -19,6 +19,7 @@ import {
   Kind,
   type ToolInvocation,
   type ToolResult,
+  type LiveOutputUpdate,
 } from './tools.js';
 
 const API_CONFIG = {
@@ -154,7 +155,7 @@ class ExaWebSearchToolInvocation extends BaseToolInvocation<
 
   async execute(
     signal: AbortSignal,
-    _updateOutput?: (output: string) => void,
+    _updateOutput?: (update: LiveOutputUpdate) => void,
   ): Promise<ToolResult> {
     const searchRequest: McpSearchRequest = {
       jsonrpc: '2.0',