@molecule/api-ai-tools 1.2.0 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-22T21:57:22.227Z
+Generated: 2026-09-24T01:21:52.537Z
 -->
 
 # @molecule/api-ai-tools
@@ -957,6 +957,15 @@ Peer dependencies:
   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
   stopped). Each entry carries its own content or its own error, so one bad
   path never fails the batch.
+- **`edit_file` shows the result, so the model need not re-read.** A
+  successful edit returns `excerpt`: each edited region as it now reads, with
+  1-based line numbers (`N: text`) and a few lines of context, capped at
+  60 lines in total (what did not fit is named by line range),
+  plus `totalLines`. `write_file` returns `totalLines`, and `excerpt` only
+  for a small file (up to 40 lines) — a big file is never echoed back.
+  Line numbers count the way `read_file` does, so they are valid offsets. The
+  excerpt is redacted like a read. The existing fields (`ok`,
+  `replacementsApplied`, `alreadyApplied`, `syntaxError`) are unchanged.
 - **A parameter under another name is not a broken tool.** Every tool's input
   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
   snake_case), and a handler that throws returns an error naming the missing

package/dist/backends/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,mEAAmE;IAEnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CA2ClB"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,mEAAmE;IAEnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CAmDlB"}

package/dist/backends/sandbox.js

@@ -42,9 +42,17 @@ export function createSandboxBackend(sandbox, projectRoot = '/workspace') {
             // printed still comes back, with exit code 124. Wrapping only the inner
             // command would run it in a child shell that never sees unexported variables
             // the consumer's sourcing set.
+            // Its output goes to files that are printed once the shell exits, never to
+            // the exec's own pipe: `cd app && server > log &` backgrounds a SUBSHELL whose
+            // stdout is still that pipe (the redirect covers the server only), and the
+            // exec waits for every holder of the pipe — past the budget, which kills the
+            // shell but not the detached subshell, until the caller's outer timeout
+            // throws the output away. Measured: three 300 s calls in two runs (X0 x31,
+            // x33). A background child now holds a file, and the call returns when the
+            // command does.
             const budgetSeconds = opts?.budgetMs ? Math.max(1, Math.round(opts.budgetMs / 1000)) : 0;
             const fullCommand = budgetSeconds
-                ? `timeout -k 5 ${budgetSeconds} bash -c ${shellQuote(anchored)}`
+                ? `o=$(mktemp); e=$(mktemp); timeout -k 5 ${budgetSeconds} bash -c ${shellQuote(anchored)} > "$o" 2> "$e" < /dev/null; c=$?; cat "$o"; cat "$e" >&2; rm -f "$o" "$e"; exit $c`
                 : anchored;
             // sandbox.exec is the Sandbox interface method — runs inside Docker, inherently sandboxed
             const result = await sandbox.exec(fullCommand, { timeout: opts?.timeout });

package/dist/edit-excerpt.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What `edit_file` / `write_file` hand back so the model can see the result of
+ * a change without reading the file again.
+ *
+ * Measured on X0 benchmark runs: 7–31 `read_file` calls per build re-read a
+ * file the executor had just written or edited — to check the result, or to
+ * find line numbers for the next edit. Each is a full model round-trip. The
+ * edited region, numbered, answers both questions in the edit's own result.
+ *
+ * @module
+ */
+/** Lines of unchanged context shown above and below each edited region. */
+export declare const EDIT_EXCERPT_CONTEXT_LINES = 3;
+/** Most lines an edit excerpt shows in total, across all regions. */
+export declare const EDIT_EXCERPT_MAX_LINES = 60;
+/** Longest single line an excerpt shows before cutting it (minified files). */
+export declare const EDIT_EXCERPT_MAX_LINE_CHARS = 240;
+/** A `write_file` result echoes the file back only when it has at most this many lines… */
+export declare const WRITE_ECHO_MAX_LINES = 40;
+/** …and at most this many characters. */
+export declare const WRITE_ECHO_MAX_CHARS = 3000;
+/** A half-open character range `[start, end)` in a string. */
+export interface CharSpan {
+    /** First changed character. */
+    start: number;
+    /** One past the last changed character (equal to `start` for a pure deletion). */
+    end: number;
+}
+/**
+ * Number of lines in a file, counted the way `read_file` counts them
+ * (`split('\n').length`), so a line number from an excerpt is a valid
+ * `read_file` offset. An empty file has 0 lines.
+ *
+ * @param content - The file text.
+ * @returns The line count.
+ */
+export declare function countLines(content: string): number;
+/**
+ * The region of `after` that differs from `before`, found by trimming the
+ * common prefix and suffix. Exact for a single replacement, whatever matched it
+ * (verbatim or whitespace-tolerant), which is how `edit_file` uses it.
+ *
+ * @param before - Text before the change.
+ * @param after - Text after the change.
+ * @returns The changed span in `after`, or null when the texts are equal.
+ */
+export declare function changedSpan(before: string, after: string): CharSpan | null;
+/**
+ * Fold one more change into the spans already recorded, keeping every span
+ * expressed in the coordinates of the NEWEST text. Spans after the change shift
+ * by its length delta; spans it overlaps merge into it.
+ *
+ * @param spans - Spans recorded so far, in `before` coordinates.
+ * @param before - Text before this change.
+ * @param after - Text after this change.
+ * @returns The spans in `after` coordinates, sorted by start.
+ */
+export declare function addChangeSpan(spans: CharSpan[], before: string, after: string): CharSpan[];
+/**
+ * The edited regions of a file as they now read — numbered, with a few lines of
+ * context, capped at {@link EDIT_EXCERPT_MAX_LINES} in total. What does not fit
+ * is named by line range so the model can `read_file` exactly that window.
+ *
+ * @param content - The file's text after the edit.
+ * @param spans - Changed character spans in `content` (from {@link addChangeSpan}).
+ * @returns The excerpt text, or an empty string when there is nothing to show.
+ */
+export declare function renderEditExcerpt(content: string, spans: CharSpan[]): string;
+/**
+ * A small file, numbered, for a `write_file` result — or null when the file is
+ * too big to echo (the model has what it just wrote; only line numbers are new).
+ *
+ * @param content - The file's text as written.
+ * @returns The numbered text, or null when the file is over the echo limits.
+ */
+export declare function renderSmallFile(content: string): string | null;
+//# sourceMappingURL=edit-excerpt.d.ts.map

package/dist/edit-excerpt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-excerpt.d.ts","sourceRoot":"","sources":["../src/edit-excerpt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,KAAK,CAAA;AAExC,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAE9C,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,yCAAyC;AACzC,eAAO,MAAM,oBAAoB,OAAO,CAAA;AAExC,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAY1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAmB1F;AA2CD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CA+C5E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D"}

package/dist/edit-excerpt.js

@@ -0,0 +1,199 @@
+/**
+ * What `edit_file` / `write_file` hand back so the model can see the result of
+ * a change without reading the file again.
+ *
+ * Measured on X0 benchmark runs: 7–31 `read_file` calls per build re-read a
+ * file the executor had just written or edited — to check the result, or to
+ * find line numbers for the next edit. Each is a full model round-trip. The
+ * edited region, numbered, answers both questions in the edit's own result.
+ *
+ * @module
+ */
+/** Lines of unchanged context shown above and below each edited region. */
+export const EDIT_EXCERPT_CONTEXT_LINES = 3;
+/** Most lines an edit excerpt shows in total, across all regions. */
+export const EDIT_EXCERPT_MAX_LINES = 60;
+/** Longest single line an excerpt shows before cutting it (minified files). */
+export const EDIT_EXCERPT_MAX_LINE_CHARS = 240;
+/** A `write_file` result echoes the file back only when it has at most this many lines… */
+export const WRITE_ECHO_MAX_LINES = 40;
+/** …and at most this many characters. */
+export const WRITE_ECHO_MAX_CHARS = 3000;
+/**
+ * Number of lines in a file, counted the way `read_file` counts them
+ * (`split('\n').length`), so a line number from an excerpt is a valid
+ * `read_file` offset. An empty file has 0 lines.
+ *
+ * @param content - The file text.
+ * @returns The line count.
+ */
+export function countLines(content) {
+    return content === '' ? 0 : content.split('\n').length;
+}
+/**
+ * The region of `after` that differs from `before`, found by trimming the
+ * common prefix and suffix. Exact for a single replacement, whatever matched it
+ * (verbatim or whitespace-tolerant), which is how `edit_file` uses it.
+ *
+ * @param before - Text before the change.
+ * @param after - Text after the change.
+ * @returns The changed span in `after`, or null when the texts are equal.
+ */
+export function changedSpan(before, after) {
+    if (before === after)
+        return null;
+    const max = Math.min(before.length, after.length);
+    let prefix = 0;
+    while (prefix < max && before.charCodeAt(prefix) === after.charCodeAt(prefix))
+        prefix++;
+    let suffix = 0;
+    while (suffix < max - prefix &&
+        before.charCodeAt(before.length - 1 - suffix) === after.charCodeAt(after.length - 1 - suffix))
+        suffix++;
+    return { start: prefix, end: after.length - suffix };
+}
+/**
+ * Fold one more change into the spans already recorded, keeping every span
+ * expressed in the coordinates of the NEWEST text. Spans after the change shift
+ * by its length delta; spans it overlaps merge into it.
+ *
+ * @param spans - Spans recorded so far, in `before` coordinates.
+ * @param before - Text before this change.
+ * @param after - Text after this change.
+ * @returns The spans in `after` coordinates, sorted by start.
+ */
+export function addChangeSpan(spans, before, after) {
+    const change = changedSpan(before, after);
+    if (!change)
+        return spans;
+    // The change's extent in BEFORE coordinates: same start, and the same suffix.
+    const beforeEnd = before.length - (after.length - change.end);
+    const delta = after.length - before.length;
+    let merged = { ...change };
+    const out = [];
+    for (const span of spans) {
+        if (span.end < change.start)
+            out.push(span);
+        else if (span.start > beforeEnd)
+            out.push({ start: span.start + delta, end: span.end + delta });
+        else
+            merged = {
+                start: Math.min(merged.start, span.start),
+                end: Math.max(merged.end, span.end > beforeEnd ? span.end + delta : change.end),
+            };
+    }
+    out.push(merged);
+    return out.sort((a, b) => a.start - b.start);
+}
+/**
+ * The 1-based line a character offset falls on.
+ *
+ * @param lineStarts - Offset of the first character of each line.
+ * @param offset - A character offset into the text.
+ * @returns The line number, 1-based.
+ */
+function lineAt(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+/**
+ * Render numbered lines `from..to` (1-based, inclusive), cutting very long lines.
+ *
+ * @param lines - The file's lines.
+ * @param from - First line to render.
+ * @param to - Last line to render.
+ * @returns One `N: text` row per line.
+ */
+function numbered(lines, from, to) {
+    const rows = [];
+    for (let n = from; n <= to; n++) {
+        const text = lines[n - 1] ?? '';
+        rows.push(`${n}: ${text.length > EDIT_EXCERPT_MAX_LINE_CHARS
+            ? `${text.slice(0, EDIT_EXCERPT_MAX_LINE_CHARS)}… (+${text.length - EDIT_EXCERPT_MAX_LINE_CHARS} chars)`
+            : text}`);
+    }
+    return rows;
+}
+/**
+ * The edited regions of a file as they now read — numbered, with a few lines of
+ * context, capped at {@link EDIT_EXCERPT_MAX_LINES} in total. What does not fit
+ * is named by line range so the model can `read_file` exactly that window.
+ *
+ * @param content - The file's text after the edit.
+ * @param spans - Changed character spans in `content` (from {@link addChangeSpan}).
+ * @returns The excerpt text, or an empty string when there is nothing to show.
+ */
+export function renderEditExcerpt(content, spans) {
+    if (spans.length === 0 || content === '')
+        return '';
+    const lines = content.split('\n');
+    const lineStarts = [0];
+    for (let i = 0; i < content.length; i++)
+        if (content[i] === '\n')
+            lineStarts.push(i + 1);
+    // Line ranges with context, merged where they touch.
+    const ranges = [];
+    for (const span of spans) {
+        const first = lineAt(lineStarts, span.start);
+        const last = lineAt(lineStarts, Math.max(span.start, span.end - 1));
+        const from = Math.max(1, first - EDIT_EXCERPT_CONTEXT_LINES);
+        const to = Math.min(lines.length, last + EDIT_EXCERPT_CONTEXT_LINES);
+        const prev = ranges[ranges.length - 1];
+        if (prev && from <= prev.to + 1)
+            prev.to = Math.max(prev.to, to);
+        else
+            ranges.push({ from, to });
+    }
+    let budget = EDIT_EXCERPT_MAX_LINES;
+    const rows = [];
+    const elided = [];
+    for (const { from, to } of ranges) {
+        if (budget <= 0) {
+            elided.push(from === to ? `${from}` : `${from}-${to}`);
+            continue;
+        }
+        if (rows.length > 0)
+            rows.push('…');
+        const size = to - from + 1;
+        if (size <= budget) {
+            rows.push(...numbered(lines, from, to));
+            budget -= size;
+            continue;
+        }
+        // Too big for what is left: show its head and tail, name the middle.
+        const head = Math.max(1, Math.ceil(budget / 2));
+        const tail = Math.max(0, budget - head);
+        rows.push(...numbered(lines, from, from + head - 1));
+        const gapFrom = from + head;
+        const gapTo = to - tail;
+        rows.push(`… (lines ${gapFrom}-${gapTo} not shown)`);
+        if (tail > 0)
+            rows.push(...numbered(lines, gapTo + 1, to));
+        budget = 0;
+    }
+    if (elided.length > 0) {
+        rows.push(`… (also edited, not shown: lines ${elided.join(', ')})`);
+    }
+    return rows.join('\n');
+}
+/**
+ * A small file, numbered, for a `write_file` result — or null when the file is
+ * too big to echo (the model has what it just wrote; only line numbers are new).
+ *
+ * @param content - The file's text as written.
+ * @returns The numbered text, or null when the file is over the echo limits.
+ */
+export function renderSmallFile(content) {
+    const total = countLines(content);
+    if (total === 0 || total > WRITE_ECHO_MAX_LINES || content.length > WRITE_ECHO_MAX_CHARS)
+        return null;
+    return numbered(content.split('\n'), 1, total).join('\n');
+}

package/dist/index.d.ts

@@ -29,6 +29,15 @@
  *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
  *   stopped). Each entry carries its own content or its own error, so one bad
  *   path never fails the batch.
+ * - **`edit_file` shows the result, so the model need not re-read.** A
+ *   successful edit returns `excerpt`: each edited region as it now reads, with
+ *   1-based line numbers (`N: text`) and a few lines of context, capped at
+ *   60 lines in total (what did not fit is named by line range),
+ *   plus `totalLines`. `write_file` returns `totalLines`, and `excerpt` only
+ *   for a small file (up to 40 lines) — a big file is never echoed back.
+ *   Line numbers count the way `read_file` does, so they are valid offsets. The
+ *   excerpt is redacted like a read. The existing fields (`ok`,
+ *   `replacementsApplied`, `alreadyApplied`, `syntaxError`) are unchanged.
  * - **A parameter under another name is not a broken tool.** Every tool's input
  *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
  *   snake_case), and a handler that throws returns an error naming the missing

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -29,6 +29,15 @@
  *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
  *   stopped). Each entry carries its own content or its own error, so one bad
  *   path never fails the batch.
+ * - **`edit_file` shows the result, so the model need not re-read.** A
+ *   successful edit returns `excerpt`: each edited region as it now reads, with
+ *   1-based line numbers (`N: text`) and a few lines of context, capped at
+ *   60 lines in total (what did not fit is named by line range),
+ *   plus `totalLines`. `write_file` returns `totalLines`, and `excerpt` only
+ *   for a small file (up to 40 lines) — a big file is never echoed back.
+ *   Line numbers count the way `read_file` does, so they are valid offsets. The
+ *   excerpt is redacted like a read. The existing fields (`ok`,
+ *   `replacementsApplied`, `alreadyApplied`, `syntaxError`) are unchanged.
  * - **A parameter under another name is not a broken tool.** Every tool's input
  *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
  *   snake_case), and a handler that throws returns an error naming the missing

package/dist/schemas.js

@@ -61,7 +61,7 @@ export const TOOL_SCHEMAS = {
     },
     write_file: {
         name: 'write_file',
-        description: 'Create or overwrite a file with full content. Use edit_file for small targeted changes instead.',
+        description: "Create or overwrite a file with full content. Use edit_file for small targeted changes instead. The result gives the file's line count (and a small file's numbered lines).",
         parameters: {
             type: 'object',
             properties: {
@@ -79,7 +79,7 @@ export const TOOL_SCHEMAS = {
     },
     edit_file: {
         name: 'edit_file',
-        description: 'Make targeted search-and-replace edits to a file. Preferred over write_file for small changes. Each old_string must match exactly once in the file.',
+        description: 'Make targeted search-and-replace edits to a file. Preferred over write_file for small changes. Each old_string must match exactly once in the file. The result shows each edited region as it now reads, with line numbers, so there is no need to re-read the file to check an edit.',
         parameters: {
             type: 'object',
             properties: {

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAY9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA+BnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0tCxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAoB9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA+BnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAqxCxF"}

package/dist/tools.js

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { addChangeSpan, changedSpan, countLines, renderEditExcerpt, renderSmallFile, } from './edit-excerpt.js';
 import { guardToolExecute, missingParamError } from './input-normalizer.js';
 import { TOOL_SCHEMAS } from './schemas.js';
 /**
@@ -487,7 +488,17 @@ export function buildTools(backend, config) {
                 const diff = computeDiff(oldContent, finalContent);
                 if (onFileChange)
                     onFileChange({ type: oldContent === null ? 'created' : 'modified', path });
-                return { path, ok: true, diff, ...(await syntaxErrorAfterWrite(path)) };
+                // The line count (and, for a small file, the numbered text) so the next
+                // edit or read does not need a read_file just to learn line numbers.
+                const echo = renderSmallFile(finalContent);
+                return {
+                    path,
+                    ok: true,
+                    diff,
+                    totalLines: countLines(finalContent),
+                    ...(echo !== null ? { excerpt: sanitizeFileContent(echo, path) } : {}),
+                    ...(await syntaxErrorAfterWrite(path)),
+                };
             }
             catch (e) {
                 return { error: `Failed to write ${path}: ${e.message}` };
@@ -527,6 +538,10 @@ export function buildTools(backend, config) {
                     content = verdict.content;
                 }
                 const oldContent = content;
+                let alreadyApplied = 0;
+                // Where each applied replacement landed, in the coordinates of the
+                // latest content — rendered into the result so the model sees the edit.
+                let spans = [];
                 for (const { old_string: oldString, new_string: newString } of replacements) {
                     // Validate each replacement is well-formed BEFORE touching content. A
                     // weak model sometimes emits a batch element missing a field or with a
@@ -539,6 +554,19 @@ export function buildTools(backend, config) {
                         };
                     }
                     const count = content.split(oldString).length - 1;
+                    // The edit is ALREADY in the file: old_string is gone and a distinctive
+                    // new_string is there exactly once. The executor re-sends an edit it
+                    // made a few calls ago (it works from its memory of the file), and the
+                    // "not found" error cost it a read_file plus a retry each time — 6 to 11
+                    // times a build in X0 x30/x34. Report it as applied instead. Short or
+                    // repeated new_strings still error: they could be there by coincidence.
+                    if (count === 0 &&
+                        newString !== oldString &&
+                        newString.trim().length >= 20 &&
+                        content.split(newString).length - 1 === 1) {
+                        alreadyApplied++;
+                        continue;
+                    }
                     if (count === 0) {
                         // A bare "old_string not found" gives the model nothing to correct, so
                         // it retries blindly (the #1 edit_file failure mode). Diagnose WHY the
@@ -556,6 +584,7 @@ export function buildTools(backend, config) {
                         // churn source. Uniqueness keeps this safe; ambiguous matches error.
                         const fuzzy = whitespaceTolerantReplace(content, oldString, newString);
                         if (fuzzy !== null) {
+                            spans = addChangeSpan(spans, content, fuzzy);
                             content = fuzzy;
                             continue;
                         }
@@ -646,7 +675,15 @@ export function buildTools(backend, config) {
                     // a self-inflicted syntax error written with ok:true that the executor
                     // then can't locate. count === 1 here, so indexOf is the unique site.
                     const at = content.indexOf(oldString);
-                    content = content.slice(0, at) + newString + content.slice(at + oldString.length);
+                    const spliced = content.slice(0, at) + newString + content.slice(at + oldString.length);
+                    spans = addChangeSpan(spans, content, spliced);
+                    content = spliced;
+                }
+                const alreadyNote = alreadyApplied > 0
+                    ? `${alreadyApplied} of these edits ${alreadyApplied === 1 ? 'was' : 'were'} already in the file (its new_string is there and its old_string is not) — nothing to do for ${alreadyApplied === 1 ? 'it' : 'them'}.`
+                    : null;
+                if (content === oldContent) {
+                    return { path, ok: true, replacementsApplied: 0, alreadyApplied, note: alreadyNote };
                 }
                 if (onFileDiff)
                     onFileDiff({ path, oldContent, newContent: content });
@@ -655,10 +692,28 @@ export function buildTools(backend, config) {
                     await onAfterWrite(path).catch(() => { });
                 if (onFileChange)
                     onFileChange({ type: 'modified', path });
+                // Show the edited regions as they now read, numbered. Measured: most
+                // re-reads of a just-edited file were to see the result or to find line
+                // numbers for the next edit — a full round-trip each. If an after-write
+                // hook rewrote the file (a formatter), show what is really on disk.
+                let finalContent = content;
+                if (onAfterWrite) {
+                    // A failed re-read just means the excerpt shows what was written.
+                    const reread = await backend.readFile(path).catch(() => null);
+                    if (typeof reread === 'string' && reread !== '' && reread !== content) {
+                        finalContent = reread;
+                        const whole = changedSpan(oldContent, reread);
+                        spans = whole ? [whole] : [];
+                    }
+                }
+                const excerpt = renderEditExcerpt(finalContent, spans);
                 return {
                     path,
                     ok: true,
-                    replacementsApplied: replacements.length,
+                    replacementsApplied: replacements.length - alreadyApplied,
+                    ...(alreadyApplied > 0 ? { alreadyApplied, note: alreadyNote } : {}),
+                    totalLines: countLines(finalContent),
+                    ...(excerpt ? { excerpt: sanitizeFileContent(excerpt, path) } : {}),
                     ...(await syntaxErrorAfterWrite(path)),
                 };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",