@animus-labs/cortex 0.2.0

package/dist/tools/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/tools/runtime.ts"],"names":[],"mappings":"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"}

package/dist/tools/shared/cwd-tracker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Working directory tracking across Bash calls.
+ *
+ * Each Bash tool call spawns a new shell process. Shell state
+ * (env vars, aliases) does NOT persist between calls. Only the
+ * working directory persists via this tracker.
+ *
+ * The tracker is reset to the default directory at the start
+ * of each agentic loop.
+ */
+export declare class CwdTracker {
+    private readonly defaultDir;
+    private currentDir;
+    constructor(defaultDir: string);
+    /**
+     * Get the current working directory.
+     */
+    getCwd(): string;
+    /**
+     * Update the working directory. The path is resolved to absolute.
+     */
+    updateCwd(newDir: string): void;
+    /**
+     * Reset to the default directory. Called at the start of each agentic loop.
+     */
+    reset(): void;
+    /**
+     * Get the default (initial) directory.
+     */
+    getDefaultDir(): string;
+}
+//# sourceMappingURL=cwd-tracker.d.ts.map

package/dist/tools/shared/cwd-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd-tracker.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/cwd-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,UAAU,CAAS;gBAEf,UAAU,EAAE,MAAM;IAK9B;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}

package/dist/tools/shared/cwd-tracker.js

@@ -0,0 +1,44 @@
+/**
+ * Working directory tracking across Bash calls.
+ *
+ * Each Bash tool call spawns a new shell process. Shell state
+ * (env vars, aliases) does NOT persist between calls. Only the
+ * working directory persists via this tracker.
+ *
+ * The tracker is reset to the default directory at the start
+ * of each agentic loop.
+ */
+import * as path from 'node:path';
+export class CwdTracker {
+    defaultDir;
+    currentDir;
+    constructor(defaultDir) {
+        this.defaultDir = path.resolve(defaultDir);
+        this.currentDir = this.defaultDir;
+    }
+    /**
+     * Get the current working directory.
+     */
+    getCwd() {
+        return this.currentDir;
+    }
+    /**
+     * Update the working directory. The path is resolved to absolute.
+     */
+    updateCwd(newDir) {
+        this.currentDir = path.resolve(newDir);
+    }
+    /**
+     * Reset to the default directory. Called at the start of each agentic loop.
+     */
+    reset() {
+        this.currentDir = this.defaultDir;
+    }
+    /**
+     * Get the default (initial) directory.
+     */
+    getDefaultDir() {
+        return this.defaultDir;
+    }
+}
+//# sourceMappingURL=cwd-tracker.js.map

package/dist/tools/shared/cwd-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd-tracker.js","sourceRoot":"","sources":["../../../src/tools/shared/cwd-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,OAAO,UAAU;IACJ,UAAU,CAAS;IAC5B,UAAU,CAAS;IAE3B,YAAY,UAAkB;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/tools/shared/edit-history.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-file pre-mutation snapshot stack.
+ *
+ * Both Edit and Write push a snapshot immediately AFTER each successful
+ * mutation. The UndoEdit tool pops the most recent snapshot to revert
+ * a file to its prior state, as long as the on-disk state still matches
+ * what we recorded when the mutation completed (so we never undo on top
+ * of unrelated external changes).
+ *
+ * Scoped per-agent via `CortexToolRuntime`, cleared on each loop reset
+ * — history does not persist across agentic loops or across agents.
+ *
+ * The stack is intentionally bounded (`MAX_STACK_DEPTH`). An unbounded
+ * stack would accumulate full file contents during long refactors and
+ * bloat memory. A deep stack is also rarely useful for the agentic
+ * loop: if the model wants to roll back more than a few edits, it's
+ * more reliable to Read the file and write the intended content
+ * directly.
+ */
+export interface EditHistoryEntry {
+    /**
+     * File contents BEFORE the mutation, or `null` when the file did not
+     * exist before the mutation (created by Write). Undoing a `null`
+     * entry deletes the file.
+     */
+    originalContent: string | null;
+    /** mtime (ms since epoch) of the file immediately AFTER the mutation. */
+    postMutationMtimeMs: number;
+    /** SHA-256 hex digest of the file bytes immediately AFTER the mutation. */
+    postMutationContentHash: string;
+    /** Which tool created the entry (for diagnostics / undo messaging). */
+    source: 'Edit' | 'Write';
+}
+/** Upper bound on snapshots retained per file. */
+export declare const MAX_STACK_DEPTH = 5;
+export declare class EditHistory {
+    private readonly stacks;
+    /**
+     * Push a snapshot for `filePath`. When the per-file stack is at its
+     * depth cap, the oldest entry is dropped so newer edits remain
+     * undoable.
+     */
+    record(filePath: string, entry: EditHistoryEntry): void;
+    /**
+     * Pop and return the most recent entry for `filePath`, or `undefined`
+     * when the file has no recorded history.
+     */
+    pop(filePath: string): EditHistoryEntry | undefined;
+    /** Current stack depth for `filePath` (0 when absent). Diagnostic use. */
+    depth(filePath: string): number;
+    /** Drop all history. Called from `CortexToolRuntime.resetForLoop`. */
+    clear(): void;
+    private normalize;
+}
+//# sourceMappingURL=edit-history.d.ts.map

package/dist/tools/shared/edit-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-history.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/edit-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,uBAAuB,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,IAAI,CAAC;AAMjC,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEhE;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAWvD;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IASnD,0EAA0E;IAC1E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI/B,sEAAsE;IACtE,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,SAAS;CAKlB"}

package/dist/tools/shared/edit-history.js

@@ -0,0 +1,72 @@
+/**
+ * Per-file pre-mutation snapshot stack.
+ *
+ * Both Edit and Write push a snapshot immediately AFTER each successful
+ * mutation. The UndoEdit tool pops the most recent snapshot to revert
+ * a file to its prior state, as long as the on-disk state still matches
+ * what we recorded when the mutation completed (so we never undo on top
+ * of unrelated external changes).
+ *
+ * Scoped per-agent via `CortexToolRuntime`, cleared on each loop reset
+ * — history does not persist across agentic loops or across agents.
+ *
+ * The stack is intentionally bounded (`MAX_STACK_DEPTH`). An unbounded
+ * stack would accumulate full file contents during long refactors and
+ * bloat memory. A deep stack is also rarely useful for the agentic
+ * loop: if the model wants to roll back more than a few edits, it's
+ * more reliable to Read the file and write the intended content
+ * directly.
+ */
+import * as path from 'node:path';
+/** Upper bound on snapshots retained per file. */
+export const MAX_STACK_DEPTH = 5;
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+export class EditHistory {
+    stacks = new Map();
+    /**
+     * Push a snapshot for `filePath`. When the per-file stack is at its
+     * depth cap, the oldest entry is dropped so newer edits remain
+     * undoable.
+     */
+    record(filePath, entry) {
+        const key = this.normalize(filePath);
+        const stack = this.stacks.get(key);
+        if (stack === undefined) {
+            this.stacks.set(key, [entry]);
+            return;
+        }
+        stack.push(entry);
+        while (stack.length > MAX_STACK_DEPTH)
+            stack.shift();
+    }
+    /**
+     * Pop and return the most recent entry for `filePath`, or `undefined`
+     * when the file has no recorded history.
+     */
+    pop(filePath) {
+        const key = this.normalize(filePath);
+        const stack = this.stacks.get(key);
+        if (!stack || stack.length === 0)
+            return undefined;
+        const entry = stack.pop();
+        if (stack.length === 0)
+            this.stacks.delete(key);
+        return entry;
+    }
+    /** Current stack depth for `filePath` (0 when absent). Diagnostic use. */
+    depth(filePath) {
+        return this.stacks.get(this.normalize(filePath))?.length ?? 0;
+    }
+    /** Drop all history. Called from `CortexToolRuntime.resetForLoop`. */
+    clear() {
+        this.stacks.clear();
+    }
+    normalize(filePath) {
+        // Matches the normalization used by FileMutationLock and
+        // ReadRegistry so keys stay consistent across the three.
+        return path.resolve(filePath);
+    }
+}
+//# sourceMappingURL=edit-history.js.map

package/dist/tools/shared/edit-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-history.js","sourceRoot":"","sources":["../../../src/tools/shared/edit-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAqBlC,kDAAkD;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,OAAO,WAAW;IACL,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEhE;;;;OAIG;IACH,MAAM,CAAC,QAAgB,EAAE,KAAuB;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClB,OAAO,KAAK,CAAC,MAAM,GAAG,eAAe;YAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,QAAgB;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACnD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,QAAgB;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;IAChE,CAAC;IAED,sEAAsE;IACtE,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAEO,SAAS,CAAC,QAAgB;QAChC,yDAAyD;QACzD,yDAAyD;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/tools/shared/edit-matcher.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Edit matcher: resolve an Edit tool `old_string` against a file's content
+ * via a tiered cascade.
+ *
+ * Tiers (short-circuit on the first that yields any match):
+ *   1. exact               — raw indexOf, caller handles multi-match based on replace_all
+ *   2. line-trimmed        — per-line trailing-whitespace tolerance; must be unique
+ *   3. indentation-flexible — strips common leading indent on both sides,
+ *                             also tolerates trailing whitespace; must be unique
+ *
+ * Also exports `findNearestMatch` for "did you mean...?" error hints when
+ * no tier matches, and `reindentReplacement` for producing a replacement
+ * string that respects the haystack's indentation when tier 3 matched.
+ *
+ * This module is intentionally pure and I/O-free so the cascade can be
+ * exhaustively unit-tested without the filesystem.
+ */
+export type MatchResult = {
+    kind: 'exact';
+    /** Char offset in haystack where the first match begins. */
+    startIndex: number;
+    /** Length of the matched span (equals needle.length). */
+    matchedLength: number;
+    /** Total number of exact occurrences in haystack. */
+    count: number;
+    /**
+     * 1-based line numbers where each match begins. Capped at the first
+     * 3 entries (diagnostic use only; full count is in `count`).
+     */
+    matchLines: number[];
+} | {
+    kind: 'line-trimmed';
+    startIndex: number;
+    matchedLength: number;
+} | {
+    kind: 'indentation-flexible';
+    startIndex: number;
+    matchedLength: number;
+    /** Common leading indent of the needle's non-empty lines. */
+    needleIndent: string;
+    /** Common leading indent of the matched haystack window. */
+    haystackIndent: string;
+} | {
+    kind: 'ambiguous';
+    tier: 'line-trimmed' | 'indentation-flexible';
+    count: number;
+    /** 1-based line numbers, first 3. */
+    matchLines: number[];
+} | {
+    kind: 'none';
+};
+/**
+ * Run the tiered matcher. Both arguments should already be line-ending
+ * normalized (CRLF -> LF) by the caller.
+ */
+export declare function findMatch(haystack: string, needle: string): MatchResult;
+/**
+ * Re-indent a replacement string so it fits the haystack's indentation
+ * when tier 3 (indentation-flexible) matched.
+ *
+ * Strips up to `needleIndent` leading whitespace from each non-empty line
+ * of `newString`, then prepends `haystackIndent`. Empty / whitespace-only
+ * lines pass through untouched.
+ */
+export declare function reindentReplacement(newString: string, needleIndent: string, haystackIndent: string): string;
+export interface NearestMatch {
+    /** 1-based line number of the best candidate. */
+    bestLine: number;
+    /** Similarity ratio in [0, 1]. */
+    bestRatio: number;
+    /**
+     * Pre-formatted multi-line snippet with line numbers and an arrow on
+     * the best candidate. Suitable for direct inclusion in an error message.
+     */
+    snippet: string;
+}
+/**
+ * Find the closest line in `haystack` to the first non-empty line of
+ * `needle`, returning a diff-style snippet with ±3 lines of context.
+ * Returns undefined when no reasonable candidate (ratio < 0.5) exists.
+ */
+export declare function findNearestMatch(haystack: string, needle: string): NearestMatch | undefined;
+//# sourceMappingURL=edit-matcher.d.ts.map

package/dist/tools/shared/edit-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-matcher.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/edit-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB,GACD;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;CACxB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,cAAc,GAAG,sBAAsB,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAMrB;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAavE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR;AAMD,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,YAAY,GAAG,SAAS,CAyC1B"}

package/dist/tools/shared/edit-matcher.js

@@ -0,0 +1,359 @@
+/**
+ * Edit matcher: resolve an Edit tool `old_string` against a file's content
+ * via a tiered cascade.
+ *
+ * Tiers (short-circuit on the first that yields any match):
+ *   1. exact               — raw indexOf, caller handles multi-match based on replace_all
+ *   2. line-trimmed        — per-line trailing-whitespace tolerance; must be unique
+ *   3. indentation-flexible — strips common leading indent on both sides,
+ *                             also tolerates trailing whitespace; must be unique
+ *
+ * Also exports `findNearestMatch` for "did you mean...?" error hints when
+ * no tier matches, and `reindentReplacement` for producing a replacement
+ * string that respects the haystack's indentation when tier 3 matched.
+ *
+ * This module is intentionally pure and I/O-free so the cascade can be
+ * exhaustively unit-tested without the filesystem.
+ */
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run the tiered matcher. Both arguments should already be line-ending
+ * normalized (CRLF -> LF) by the caller.
+ */
+export function findMatch(haystack, needle) {
+    // Note: we intentionally do NOT bail on needle.length > haystack.length.
+    // Tier 3 tolerates over-indented needles, so a longer-than-haystack needle
+    // can still produce a valid match after common-indent stripping.
+    if (needle.length === 0)
+        return { kind: 'none' };
+    const exact = findExact(haystack, needle);
+    if (exact.kind === 'exact')
+        return exact;
+    const trimmed = findLineTrimmed(haystack, needle);
+    if (trimmed.kind !== 'none')
+        return trimmed;
+    return findIndentationFlexible(haystack, needle);
+}
+/**
+ * Re-indent a replacement string so it fits the haystack's indentation
+ * when tier 3 (indentation-flexible) matched.
+ *
+ * Strips up to `needleIndent` leading whitespace from each non-empty line
+ * of `newString`, then prepends `haystackIndent`. Empty / whitespace-only
+ * lines pass through untouched.
+ */
+export function reindentReplacement(newString, needleIndent, haystackIndent) {
+    if (needleIndent === haystackIndent)
+        return newString;
+    return newString
+        .split('\n')
+        .map((line) => {
+        if (line.trim() === '')
+            return line;
+        const stripped = line.startsWith(needleIndent)
+            ? line.slice(needleIndent.length)
+            : line;
+        return haystackIndent + stripped;
+    })
+        .join('\n');
+}
+/** Hard scan limit on large files; Levenshtein is O(m*n) per line. */
+const NEAREST_MATCH_SCAN_CAP = 2000;
+const NEAREST_MATCH_MIN_RATIO = 0.5;
+const NEAREST_MATCH_CONTEXT = 3;
+/**
+ * Find the closest line in `haystack` to the first non-empty line of
+ * `needle`, returning a diff-style snippet with ±3 lines of context.
+ * Returns undefined when no reasonable candidate (ratio < 0.5) exists.
+ */
+export function findNearestMatch(haystack, needle) {
+    const needleLines = needle.split('\n');
+    const firstNonEmpty = needleLines.find((line) => line.trim() !== '');
+    if (firstNonEmpty === undefined)
+        return undefined;
+    const haystackLines = haystack.split('\n');
+    const scanLimit = Math.min(haystackLines.length, NEAREST_MATCH_SCAN_CAP);
+    const needleTrim = firstNonEmpty.trim();
+    let bestIdx = -1;
+    let bestRatio = 0;
+    for (let i = 0; i < scanLimit; i++) {
+        const line = haystackLines[i];
+        const lineTrim = line.trim();
+        if (lineTrim === '')
+            continue;
+        const ratio = levenshteinRatio(needleTrim, lineTrim);
+        if (ratio > bestRatio) {
+            bestRatio = ratio;
+            bestIdx = i;
+        }
+    }
+    if (bestIdx === -1 || bestRatio < NEAREST_MATCH_MIN_RATIO)
+        return undefined;
+    const start = Math.max(0, bestIdx - NEAREST_MATCH_CONTEXT);
+    const end = Math.min(haystackLines.length - 1, bestIdx + NEAREST_MATCH_CONTEXT);
+    const gutterWidth = String(end + 1).length;
+    const rendered = [];
+    for (let i = start; i <= end; i++) {
+        const num = String(i + 1).padStart(gutterWidth);
+        const marker = i === bestIdx ? '  <- nearest' : '';
+        rendered.push(`  ${num} | ${haystackLines[i]}${marker}`);
+    }
+    return {
+        bestLine: bestIdx + 1,
+        bestRatio,
+        snippet: rendered.join('\n'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Tier 1: exact
+// ---------------------------------------------------------------------------
+function findExact(haystack, needle) {
+    const uniqueLines = [];
+    let count = 0;
+    let firstStart = -1;
+    let pos = 0;
+    while (true) {
+        const idx = haystack.indexOf(needle, pos);
+        if (idx === -1)
+            break;
+        count++;
+        if (count === 1)
+            firstStart = idx;
+        // Keep up to 3 DISTINCT line numbers. Multiple hits on the same line
+        // (e.g. replace_all of a short variable) should show one line, not
+        // the same number repeated.
+        if (uniqueLines.length < 3) {
+            const line = charIndexToLine(haystack, idx);
+            if (!uniqueLines.includes(line))
+                uniqueLines.push(line);
+        }
+        pos = idx + needle.length;
+    }
+    if (count === 0)
+        return { kind: 'none' };
+    return {
+        kind: 'exact',
+        startIndex: firstStart,
+        matchedLength: needle.length,
+        count,
+        matchLines: uniqueLines,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tier 2: line-trimmed (tolerates per-line trailing whitespace)
+// ---------------------------------------------------------------------------
+function findLineTrimmed(haystack, needle) {
+    const needleLines = needle.split('\n');
+    const haystackLines = haystack.split('\n');
+    if (needleLines.length > haystackLines.length)
+        return { kind: 'none' };
+    const needleTrimmed = needleLines.map(trimEnd);
+    // Short-circuit when tier 2 would degenerate to tier 1: if trimming
+    // changes nothing on either side, tier 1 has already run and either
+    // found a match or not — re-running here would just rediscover the
+    // same result.
+    const needleEqual = arraysEqual(needleLines, needleTrimmed);
+    if (needleEqual && !haystackHasTrailingWhitespace(haystackLines)) {
+        return { kind: 'none' };
+    }
+    const windowLen = needleLines.length;
+    const matches = [];
+    for (let i = 0; i + windowLen <= haystackLines.length; i++) {
+        let ok = true;
+        for (let j = 0; j < windowLen; j++) {
+            if (trimEnd(haystackLines[i + j]) !== needleTrimmed[j]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            matches.push(i);
+    }
+    if (matches.length === 0)
+        return { kind: 'none' };
+    if (matches.length > 1) {
+        return {
+            kind: 'ambiguous',
+            tier: 'line-trimmed',
+            count: matches.length,
+            matchLines: matches.slice(0, 3).map((i) => i + 1),
+        };
+    }
+    const span = linesToSpan(haystackLines, matches[0], windowLen);
+    return {
+        kind: 'line-trimmed',
+        startIndex: span.startIndex,
+        matchedLength: span.matchedLength,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tier 3: indentation-flexible (common-indent strip + trailing trim)
+// ---------------------------------------------------------------------------
+function findIndentationFlexible(haystack, needle) {
+    const needleLines = needle.split('\n');
+    const haystackLines = haystack.split('\n');
+    if (needleLines.length > haystackLines.length)
+        return { kind: 'none' };
+    const needleIndent = commonLeadingIndent(needleLines);
+    const needleCanonical = needleLines.map((line) => trimEnd(stripLeading(line, needleIndent)));
+    // If the needle has no stripped content (e.g. entirely blank lines),
+    // fall out — we'd match noise.
+    if (needleCanonical.every((line) => line === ''))
+        return { kind: 'none' };
+    const windowLen = needleLines.length;
+    const matches = [];
+    for (let i = 0; i + windowLen <= haystackLines.length; i++) {
+        const window = haystackLines.slice(i, i + windowLen);
+        const windowIndent = commonLeadingIndent(window);
+        let ok = true;
+        for (let j = 0; j < windowLen; j++) {
+            const canonical = trimEnd(stripLeading(window[j], windowIndent));
+            if (canonical !== needleCanonical[j]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            matches.push({ startLine: i, haystackIndent: windowIndent });
+    }
+    if (matches.length === 0)
+        return { kind: 'none' };
+    if (matches.length > 1) {
+        return {
+            kind: 'ambiguous',
+            tier: 'indentation-flexible',
+            count: matches.length,
+            matchLines: matches.slice(0, 3).map((m) => m.startLine + 1),
+        };
+    }
+    const m = matches[0];
+    const span = linesToSpan(haystackLines, m.startLine, windowLen);
+    // Guard: if the indents are identical, tier 2 would have caught this
+    // (or tier 1 already did). Promote to 'none' so we don't mask a true
+    // no-match with a spurious tier 3 hit.
+    if (needleIndent === m.haystackIndent) {
+        return { kind: 'none' };
+    }
+    return {
+        kind: 'indentation-flexible',
+        startIndex: span.startIndex,
+        matchedLength: span.matchedLength,
+        needleIndent,
+        haystackIndent: m.haystackIndent,
+    };
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function trimEnd(s) {
+    return s.replace(/[ \t]+$/u, '');
+}
+function stripLeading(line, indent) {
+    return line.startsWith(indent) ? line.slice(indent.length) : line;
+}
+function haystackHasTrailingWhitespace(lines) {
+    for (const line of lines) {
+        if (line.length > 0 && /[ \t]$/u.test(line))
+            return true;
+    }
+    return false;
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Longest common leading whitespace prefix across non-empty lines.
+ * Lines that are empty or whitespace-only are skipped so a blank line
+ * inside a block doesn't collapse the shared indent to "".
+ */
+function commonLeadingIndent(lines) {
+    let common;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        const m = /^[ \t]*/u.exec(line);
+        const leading = m ? m[0] : '';
+        if (common === undefined) {
+            common = leading;
+            continue;
+        }
+        let i = 0;
+        const max = Math.min(common.length, leading.length);
+        while (i < max && common[i] === leading[i])
+            i++;
+        common = common.slice(0, i);
+        if (common.length === 0)
+            return '';
+    }
+    return common ?? '';
+}
+/**
+ * Convert a (startLine, windowLen) line-index span into a (startIndex,
+ * matchedLength) character span in the original haystack. Assumes the
+ * haystack was split by '\n' — inner newlines are counted, but no
+ * trailing newline is included in `matchedLength`.
+ */
+function linesToSpan(lines, startLine, windowLen) {
+    let startIndex = 0;
+    for (let i = 0; i < startLine; i++) {
+        startIndex += lines[i].length + 1;
+    }
+    let matchedLength = 0;
+    for (let i = 0; i < windowLen; i++) {
+        matchedLength += lines[startLine + i].length;
+        if (i < windowLen - 1)
+            matchedLength += 1;
+    }
+    return { startIndex, matchedLength };
+}
+/** Count 1-based line number of a character offset in haystack. */
+function charIndexToLine(haystack, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < haystack.length; i++) {
+        if (haystack.charCodeAt(i) === 10 /* \n */)
+            line++;
+    }
+    return line;
+}
+// ---------------------------------------------------------------------------
+// Levenshtein (for findNearestMatch only)
+// ---------------------------------------------------------------------------
+function levenshteinRatio(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const max = Math.max(a.length, b.length);
+    if (max === 0)
+        return 1;
+    const dist = levenshteinDistance(a, b);
+    return 1 - dist / max;
+}
+function levenshteinDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+//# sourceMappingURL=edit-matcher.js.map