@namzu/sdk 3.0.0 → 3.2.0

package/dist/tools/builtins/__tests__/stale-file-refusal.test.js

@@ -0,0 +1,187 @@
+import { lstatSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { atomicWriteFile } from '../atomic-write-file.js';
+import { fingerprintContent } from '../content-fingerprint.js';
+import { EditTool } from '../edit.js';
+/**
+ * The mutation lock serializes THIS runtime's writers. It cannot see a
+ * person editing in an editor, another process, or a second agent run —
+ * and an edit computed against a body that has since moved is a lost
+ * update whichever of those did the moving.
+ *
+ * Worse than undetected, it was misreported: an `old_string` that no
+ * longer matches came back as "not found in file — make sure the string
+ * matches exactly", which tells the agent its input was wrong when the
+ * file changed underneath it. The agent then retries the same edit
+ * against the same moved file.
+ */
+function trackerOver(store) {
+    return {
+        recordRead: (key, content) => {
+            if (content !== undefined)
+                store.set(key, fingerprintContent(content));
+        },
+        hasRead: (key) => store.has(key),
+        fingerprint: (key) => store.get(key),
+    };
+}
+function contextWith(workingDirectory, tracker) {
+    return {
+        runId: 'run_stale',
+        workingDirectory,
+        abortSignal: new AbortController().signal,
+        env: {},
+        log: () => { },
+        ...(tracker ? { fileReadTracker: tracker } : {}),
+    };
+}
+describe('an edit against a file that moved is refused, not applied', () => {
+    it('refuses when the body changed since the agent read it', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const store = new Map();
+        const tracker = trackerOver(store);
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        // Somebody else rewrites the very line this edit anchors on.
+        writeFileSync(file, 'alpha\nBETA WAS REWRITTEN\n');
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir, tracker));
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('changed on disk after you read it');
+        // The refusal has to be actionable, and "nothing was written" is the
+        // part that stops the agent re-running the same edit blind.
+        expect(result.error).toContain('Read the file again');
+        expect(result.error).toContain('Nothing was written');
+        expect(readFileSync(file, 'utf-8')).toBe('alpha\nBETA WAS REWRITTEN\n');
+    });
+    it('applies normally when the file is untouched', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const tracker = trackerOver(new Map());
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir, tracker));
+        expect(result.success).toBe(true);
+        expect(readFileSync(file, 'utf-8')).toBe('alpha\ngamma\n');
+    });
+    it('lets a second edit in the same turn proceed against what the first wrote', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const tracker = trackerOver(new Map());
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        const context = contextWith(dir, tracker);
+        const first = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, context);
+        // Without re-fingerprinting after a successful write, this second edit
+        // would see its own predecessor's output as someone else's drift.
+        const second = await EditTool.execute({ path: 'doc.md', old_string: 'alpha', new_string: 'omega', replace_all: false }, context);
+        expect(first.success).toBe(true);
+        expect(second.success).toBe(true);
+        expect(readFileSync(file, 'utf-8')).toBe('omega\ngamma\n');
+    });
+    it('proceeds when the host tracks nothing, which is the older contract', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n');
+        // `fingerprint` is optional. A host that never captured one must not
+        // have every edit refused.
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir));
+        expect(result.success).toBe(true);
+    });
+    it('proceeds when the path was never read, so there is nothing to be stale against', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n');
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir, trackerOver(new Map())));
+        expect(result.success).toBe(true);
+    });
+});
+describe('the fingerprint distinguishes bodies', () => {
+    it('is stable for identical content', () => {
+        expect(fingerprintContent('alpha\n')).toBe(fingerprintContent('alpha\n'));
+    });
+    it('differs on a one-character change', () => {
+        expect(fingerprintContent('alpha\n')).not.toBe(fingerprintContent('alphb\n'));
+    });
+    it('differs on trailing whitespace, which a diff would also treat as a change', () => {
+        expect(fingerprintContent('alpha')).not.toBe(fingerprintContent('alpha '));
+    });
+});
+describe('an atomic commit writes through a symlink rather than over it', () => {
+    /** Creating one needs a privilege this platform does not always grant. */
+    function symlinkOrSkip(target, link) {
+        try {
+            symlinkSync(target, link);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    it('keeps the link and updates its target', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-symlink-'));
+        const real = join(dir, 'real.md');
+        const link = join(dir, 'link.md');
+        writeFileSync(real, 'original\n');
+        if (!symlinkOrSkip(real, link))
+            return;
+        await atomicWriteFile(link, 'replaced\n');
+        // `rename` onto the link path would have swapped the link for a plain
+        // file, silently detaching every other path that pointed through it.
+        expect(lstatSync(link).isSymbolicLink()).toBe(true);
+        expect(readFileSync(real, 'utf-8')).toBe('replaced\n');
+        expect(readFileSync(link, 'utf-8')).toBe('replaced\n');
+    });
+    it('still creates a file that does not exist yet', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-symlink-'));
+        const fresh = join(dir, 'new.md');
+        await atomicWriteFile(fresh, 'created\n');
+        expect(readFileSync(fresh, 'utf-8')).toBe('created\n');
+    });
+});
+describe('drift that does not touch the anchor is not a conflict', () => {
+    it('applies when someone changed an unrelated part of the file', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const tracker = trackerOver(new Map());
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        // Someone appends a line. The edit's anchor is untouched, so the edit
+        // is still exactly as well defined as when it was computed —
+        // refusing here would reject a safe edit every time anybody wrote
+        // anywhere in the file.
+        writeFileSync(file, 'alpha\nbeta\nan unrelated new line\n');
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir, tracker));
+        expect(result.success).toBe(true);
+        expect(readFileSync(file, 'utf-8')).toBe('alpha\ngamma\nan unrelated new line\n');
+    });
+    it('reports a genuinely wrong anchor as wrong, not as drift', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const tracker = trackerOver(new Map());
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        // Nothing moved. The anchor is simply not in the file, and telling
+        // the agent to re-read would send it to look for a change that never
+        // happened.
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'nowhere', new_string: 'x', replace_all: false }, contextWith(dir, tracker));
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('not found in file');
+        expect(result.error).not.toContain('changed on disk');
+    });
+    it('reports drift when the anchor became ambiguous because of it', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'));
+        const file = join(dir, 'doc.md');
+        writeFileSync(file, 'alpha\nbeta\n');
+        const tracker = trackerOver(new Map());
+        tracker.recordRead(file, 'alpha\nbeta\n');
+        // A second copy of the anchor appears. "not unique — add more
+        // context" would send the agent to widen an anchor that was unique
+        // when it read the file.
+        writeFileSync(file, 'alpha\nbeta\nbeta\n');
+        const result = await EditTool.execute({ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false }, contextWith(dir, tracker));
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('changed on disk');
+    });
+});
+//# sourceMappingURL=stale-file-refusal.test.js.map

package/dist/tools/builtins/__tests__/stale-file-refusal.test.js.map

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

package/dist/tools/builtins/atomic-write-file.d.ts

@@ -8,6 +8,6 @@ interface AtomicWriteHooks {
  * The temp file lives beside the destination so rename stays on one
  * filesystem. A failed pre-commit write leaves the original untouched.
  */
-export declare function atomicWriteFile(filePath: string, content: string, hooks?: AtomicWriteHooks): Promise<void>;
+export declare function atomicWriteFile(requestedPath: string, content: string, hooks?: AtomicWriteHooks): Promise<void>;
 export {};
 //# sourceMappingURL=atomic-write-file.d.ts.map

package/dist/tools/builtins/atomic-write-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/atomic-write-file.ts"],"names":[],"mappings":"AAIA,UAAU,gBAAgB;IACzB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,gBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Bf"}
+{"version":3,"file":"atomic-write-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/atomic-write-file.ts"],"names":[],"mappings":"AAIA,UAAU,gBAAgB;IACzB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACpC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,gBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/tools/builtins/atomic-write-file.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
+import { mkdir, open, realpath, rename, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 /**
  * Commit a complete file body without exposing a truncated destination.
@@ -7,7 +7,14 @@ import { basename, dirname, join } from 'node:path';
  * The temp file lives beside the destination so rename stays on one
  * filesystem. A failed pre-commit write leaves the original untouched.
  */
-export async function atomicWriteFile(filePath, content, hooks = {}) {
+export async function atomicWriteFile(requestedPath, content, hooks = {}) {
+    // Write THROUGH a symlink, not over it. `rename` replaces whatever sits
+    // at the destination, so committing onto a link path swaps the link for
+    // a regular file: the link is gone, and every other path that pointed
+    // through it now reads stale content. Resolving first keeps the link and
+    // updates what it points at, which is what a caller editing a linked
+    // file means. A path that does not exist yet resolves to itself.
+    const filePath = await realpath(requestedPath).catch(() => requestedPath);
     const directory = dirname(filePath);
     await mkdir(directory, { recursive: true });
     const existingMode = await stat(filePath)
@@ -33,12 +40,34 @@ export async function atomicWriteFile(filePath, content, hooks = {}) {
             await unlink(tempPath).catch(() => undefined);
     }
 }
+/**
+ * Best-effort, and only after the rename has already committed.
+ *
+ * Syncing the directory is what makes the RENAME survive a power loss on a
+ * POSIX filesystem. Not every platform permits it — opening a directory and
+ * calling fsync raises `EPERM` on Windows — and there the whole builtin was
+ * unusable: every `edit` and every `write` failed with `EPERM: operation not
+ * permitted, fsync` after correctly writing the file.
+ *
+ * Swallowing is right here and nowhere else in this file. By this point the
+ * destination already holds the complete new body; the only thing still at
+ * stake is durability across an OS-level crash, and on a platform that
+ * refuses the call there is no second way to ask. Failing the write would
+ * trade a durability refinement for a guaranteed error on every write.
+ *
+ * The sibling in `utils/atomic-write.ts` — the one the disk stores use, and
+ * the one that has run on this platform all along — does not sync the
+ * directory at all.
+ */
 async function syncDirectory(directory) {
     let handle;
     try {
         handle = await open(directory, 'r');
         await handle.sync();
     }
+    catch {
+        // Unsupported on this platform; the rename already landed.
+    }
     finally {
         await handle?.close().catch(() => undefined);
     }

package/dist/tools/builtins/atomic-write-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write-file.js","sourceRoot":"","sources":["../../../src/tools/builtins/atomic-write-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAmB,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACrF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAOnD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,QAAgB,EAChB,OAAe,EACf,QAA0B,EAAE;IAE5B,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnC,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE3C,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;SACvC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC3B,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACxB,MAAM,QAAQ,GAAG,IAAI,CACpB,SAAS,EACT,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CACjE,CAAA;IACD,IAAI,MAA8B,CAAA;IAClC,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,IAAI,KAAK,CAAC,CAAA;QAC1D,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACxC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QACnB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,GAAG,SAAS,CAAA;QAClB,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,CAAA;QAC5B,MAAM,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QAChC,SAAS,GAAG,IAAI,CAAA;QAChB,MAAM,aAAa,CAAC,SAAS,CAAC,CAAA;IAC/B,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC5C,IAAI,CAAC,SAAS;YAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC9D,CAAC;AACF,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC7C,IAAI,MAA8B,CAAA;IAClC,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;QACnC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACpB,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC7C,CAAC;AACF,CAAC"}
+{"version":3,"file":"atomic-write-file.js","sourceRoot":"","sources":["../../../src/tools/builtins/atomic-write-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAmB,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC/F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAOnD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,aAAqB,EACrB,OAAe,EACf,QAA0B,EAAE;IAE5B,wEAAwE;IACxE,wEAAwE;IACxE,sEAAsE;IACtE,yEAAyE;IACzE,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,CAAA;IACzE,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnC,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE3C,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;SACvC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC3B,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACxB,MAAM,QAAQ,GAAG,IAAI,CACpB,SAAS,EACT,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CACjE,CAAA;IACD,IAAI,MAA8B,CAAA;IAClC,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,IAAI,KAAK,CAAC,CAAA;QAC1D,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACxC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QACnB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,GAAG,SAAS,CAAA;QAClB,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,CAAA;QAC5B,MAAM,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QAChC,SAAS,GAAG,IAAI,CAAA;QAChB,MAAM,aAAa,CAAC,SAAS,CAAC,CAAA;IAC/B,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC5C,IAAI,CAAC,SAAS;YAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC9D,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC7C,IAAI,MAA8B,CAAA;IAClC,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;QACnC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACpB,CAAC;IAAC,MAAM,CAAC;QACR,2DAA2D;IAC5D,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC7C,CAAC;AACF,CAAC"}

package/dist/tools/builtins/content-fingerprint.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A short, stable fingerprint of a file body.
+ *
+ * Used to answer one question at mutation time: is the file still what the
+ * agent read? An `edit` is computed against a remembered body, and between
+ * the read and the write that body can move — a person editing in an
+ * editor, another process, a second agent run. The in-process mutation lock
+ * serializes this runtime's own writers and is blind to every one of those.
+ *
+ * Without this the drift is not merely undetected, it is actively
+ * misreported: an `old_string` that no longer matches comes back as "not
+ * found in file — make sure the string matches exactly", which tells the
+ * agent its input was wrong when the file changed underneath it. The agent
+ * then retries the same edit against the same moved file.
+ *
+ * Truncated deliberately. This distinguishes two bodies; it is not a
+ * security boundary, and a full digest per read costs bytes in a structure
+ * that lives for the whole run.
+ */
+export declare function fingerprintContent(content: string): string;
+/** What a mutation tool tells the agent when the file moved under it. */
+export declare function staleFileError(path: string): string;
+//# sourceMappingURL=content-fingerprint.d.ts.map

package/dist/tools/builtins/content-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-fingerprint.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/content-fingerprint.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/tools/builtins/content-fingerprint.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+/**
+ * A short, stable fingerprint of a file body.
+ *
+ * Used to answer one question at mutation time: is the file still what the
+ * agent read? An `edit` is computed against a remembered body, and between
+ * the read and the write that body can move — a person editing in an
+ * editor, another process, a second agent run. The in-process mutation lock
+ * serializes this runtime's own writers and is blind to every one of those.
+ *
+ * Without this the drift is not merely undetected, it is actively
+ * misreported: an `old_string` that no longer matches comes back as "not
+ * found in file — make sure the string matches exactly", which tells the
+ * agent its input was wrong when the file changed underneath it. The agent
+ * then retries the same edit against the same moved file.
+ *
+ * Truncated deliberately. This distinguishes two bodies; it is not a
+ * security boundary, and a full digest per read costs bytes in a structure
+ * that lives for the whole run.
+ */
+export function fingerprintContent(content) {
+    return createHash('sha256').update(content, 'utf-8').digest('hex').slice(0, 16);
+}
+/** What a mutation tool tells the agent when the file moved under it. */
+export function staleFileError(path) {
+    return (`${path} changed on disk after you read it, so this edit was computed against a stale copy ` +
+        'and was not applied. Read the file again and redo the edit against its current contents. ' +
+        'Nothing was written.');
+}
+//# sourceMappingURL=content-fingerprint.js.map

package/dist/tools/builtins/content-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-fingerprint.js","sourceRoot":"","sources":["../../../src/tools/builtins/content-fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IACjD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AAChF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,CACN,GAAG,IAAI,qFAAqF;QAC5F,2FAA2F;QAC3F,sBAAsB,CACtB,CAAA;AACF,CAAC"}

package/dist/tools/builtins/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/edit.ts"],"names":[],"mappings":"AAoEA,eAAO,MAAM,QAAQ;;;;;;;;EA4DnB,CAAA"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/edit.ts"],"names":[],"mappings":"AA4HA,eAAO,MAAM,QAAQ;;;;;;;;EAiHnB,CAAA"}

package/dist/tools/builtins/edit.js

@@ -1,16 +1,37 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from '../defineTool.js';
+import { atomicWriteFile } from './atomic-write-file.js';
+import { fingerprintContent, staleFileError } from './content-fingerprint.js';
+import { withFileMutationLock } from './file-mutation-lock.js';
+/**
+ * Two schemas, on purpose.
+ *
+ * `inputSchema` is what a HOST may send, and it accepts the `oldStr`/`newStr`
+ * aliases and `insertLine` because hosts that expose replacement under those
+ * names are real. `modelInputSchema` below is what a MODEL is constrained to
+ * — one closed canonical shape — because giving a model four spellings of the
+ * same field is how it learns to guess between them.
+ *
+ * `.strict()` is what makes the accepted set closed. Without it zod's default
+ * is to STRIP an unknown key, so a hallucinated or misspelled field is
+ * silently dropped and the edit proceeds against an input nobody wrote.
+ */
 const inputSchema = z
     .object({
-    path: z.string().describe('Path to the file to edit'),
+    path: z
+        .string()
+        .refine((value) => value.trim().length > 0, 'Path must not be empty.')
+        .describe('Path to the file to edit. Must not be empty.'),
     old_string: z
         .string()
+        .min(1)
         .optional()
         .describe('The exact string to find and replace. Must be unique in the file.'),
     oldStr: z
         .string()
+        .min(1)
         .optional()
         .describe('Alias for old_string. Used by hosts that expose text replacement as oldStr/newStr.'),
     new_string: z
@@ -30,23 +51,69 @@ const inputSchema = z
         .default(false)
         .describe('Replace all occurrences instead of just the first unique match'),
 })
+    .strict()
     .refine((value) => typeof value.new_string === 'string' || typeof value.newStr === 'string', {
     message: 'Either new_string or newStr is required.',
 })
     .refine((value) => value.insertLine !== undefined ||
     typeof value.old_string === 'string' ||
     typeof value.oldStr === 'string', { message: 'Either old_string/oldStr or insertLine is required.' });
+/**
+ * What a capable provider constrains the model to emit: one shape, closed.
+ *
+ * The aliases above exist for hosts, not for models. A model offered
+ * `old_string` and `oldStr` as separate optional fields has to guess which
+ * one this deployment wants, and `additionalProperties: false` is what turns
+ * an invented field into a generation-time refusal rather than a silent drop.
+ */
+const modelInputSchema = {
+    type: 'object',
+    properties: {
+        path: {
+            type: 'string',
+            description: 'Path to the file to edit. Must not be empty.',
+        },
+        old_string: {
+            type: 'string',
+            description: 'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+        },
+        new_string: {
+            type: 'string',
+            description: 'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
+        },
+        replace_all: {
+            type: 'boolean',
+            description: 'Replace every occurrence instead of requiring one unique match.',
+        },
+    },
+    required: ['path', 'old_string', 'new_string'],
+    additionalProperties: false,
+};
 export const EditTool = defineTool({
     name: 'edit',
     description: 'Makes targeted edits to a file using exact string find-and-replace or line insertion. THIS IS THE PREFERRED WAY TO MODIFY AN EXISTING FILE — never reach for `write` to change a file that already exists, because `write` overwrites the whole body and discards earlier work on partial failure. `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Self-budget new_string/newStr under 12000 characters before emitting the tool call; use repeated bounded edits for long sections. Preserves file formatting and indentation.',
     inputSchema,
+    modelInputSchema,
+    enforceModelInput: true,
+    validationErrorHint: 'Required shape: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}. Optional: "replace_all": true.',
     category: 'filesystem',
     permissions: ['file_write'],
     readOnly: false,
     destructive: false,
     concurrencySafe: false,
     async execute(input, context) {
-        const normalized = normalizeEditInput(input);
+        // Re-validated here rather than trusted from the registry: `execute` is
+        // reachable directly, and the closed contract is only closed if the
+        // check runs on the path a caller can actually take.
+        const parsed = inputSchema.safeParse(input);
+        if (!parsed.success) {
+            return {
+                success: false,
+                output: '',
+                error: `Invalid edit input: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
+            };
+        }
+        const normalized = normalizeEditInput(parsed.data);
         if (!normalized.success) {
             return { success: false, output: '', error: normalized.error };
         }
@@ -58,33 +125,70 @@ export const EditTool = defineTool({
                 error: 'old_string/oldStr and new_string/newStr are identical — no change needed',
             };
         }
-        // Sandbox-aware: route through sandbox when available
-        if (context.sandbox) {
-            const buffer = await context.sandbox.readFile(input.path);
-            const content = buffer.toString('utf-8');
+        const filePath = resolve(context.workingDirectory, parsed.data.path);
+        // Read-modify-write is not atomic on its own: two edits to the same
+        // path interleave their reads, and the second write lands on content
+        // the first had already replaced — so one edit vanishes and the loser
+        // reports "old_string not found", blaming the model for a race. The
+        // key spans both branches because sandbox and local are distinct
+        // files even when the path string matches.
+        const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`;
+        return withFileMutationLock(lockKey, async () => {
+            if (context.sandbox) {
+                const buffer = await context.sandbox.readFile(parsed.data.path);
+                const result = applyEdit(buffer.toString('utf-8'), normalized.operation);
+                if (!result.success) {
+                    return { success: false, output: '', error: result.error };
+                }
+                await context.sandbox.writeFile(parsed.data.path, result.content);
+                return {
+                    success: true,
+                    output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
+                    data: { path: parsed.data.path, replacements: result.replacements, sandboxed: true },
+                };
+            }
+            const content = await readFile(filePath, 'utf-8');
             const result = applyEdit(content, normalized.operation);
             if (!result.success) {
+                // The anchor did not match what is on disk. Two very different
+                // situations produce that, and the difference is the whole
+                // value of the fingerprint:
+                //
+                // The file is as the agent left it, and the anchor is simply
+                // wrong — "not found, match the whitespace exactly" is the
+                // right thing to say.
+                //
+                // Or the file moved after the read — a person in an editor,
+                // another process, a second agent — and the same message is a
+                // lie that sends the agent to re-check text that was never the
+                // problem, so it retries the identical edit against the same
+                // moved file.
+                //
+                // Deliberately NOT a gate on the successful path. An anchor
+                // that still matches uniquely is well defined however much
+                // changed elsewhere in the file, and refusing there would
+                // reject safe edits every time anyone touched an unrelated
+                // line.
+                const seen = context.fileReadTracker?.fingerprint?.(filePath);
+                if (seen !== undefined && seen !== fingerprintContent(content)) {
+                    return { success: false, output: '', error: staleFileError(filePath) };
+                }
                 return { success: false, output: '', error: result.error };
             }
-            await context.sandbox.writeFile(input.path, result.content);
+            // Temp file, fsync, rename — a reader sees the old body or the new
+            // one, never a half-written one. A plain `writeFile` that fails
+            // partway leaves the user's source truncated.
+            await atomicWriteFile(filePath, result.content);
+            // This runtime is now the last writer, so the next edit in the same
+            // turn compares against what we just wrote rather than the read
+            // before it.
+            context.fileReadTracker?.recordRead(filePath, result.content);
             return {
                 success: true,
-                output: `Edited ${input.path}: ${result.replacements} replacement(s) [sandboxed]`,
-                data: { path: input.path, replacements: result.replacements, sandboxed: true },
+                output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
+                data: { path: filePath, replacements: result.replacements },
             };
-        }
-        const filePath = resolve(context.workingDirectory, input.path);
-        const content = await readFile(filePath, 'utf-8');
-        const result = applyEdit(content, normalized.operation);
-        if (!result.success) {
-            return { success: false, output: '', error: result.error };
-        }
-        await writeFile(filePath, result.content, 'utf-8');
-        return {
-            success: true,
-            output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
-            data: { path: filePath, replacements: result.replacements },
-        };
+        });
     },
 });
 function normalizeEditInput(input) {
@@ -138,24 +242,25 @@ function applyEdit(content, input) {
     if (input.operation === 'insert') {
         return applyLineInsert(content, input);
     }
-    if (!content.includes(input.oldString)) {
+    const replacement = normalizeLineEndings(content, input);
+    if (!content.includes(replacement.oldString)) {
         return {
             success: false,
             error: 'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
         };
     }
-    if (input.replace_all) {
-        const parts = content.split(input.oldString);
+    if (replacement.replace_all) {
+        const parts = content.split(replacement.oldString);
         const replacements = parts.length - 1;
         return {
             success: true,
-            content: parts.join(input.newString),
+            content: parts.join(replacement.newString),
             replacements,
         };
     }
     // Uniqueness check: old_string/oldStr must appear exactly once
-    const firstIndex = content.indexOf(input.oldString);
-    const secondIndex = content.indexOf(input.oldString, firstIndex + 1);
+    const firstIndex = content.indexOf(replacement.oldString);
+    const secondIndex = content.indexOf(replacement.oldString, firstIndex + 1);
     if (secondIndex !== -1) {
         const lineNumber = content.slice(0, firstIndex).split('\n').length;
         const secondLine = content.slice(0, secondIndex).split('\n').length;
@@ -167,8 +272,8 @@ function applyEdit(content, input) {
     return {
         success: true,
         content: content.slice(0, firstIndex) +
-            input.newString +
-            content.slice(firstIndex + input.oldString.length),
+            replacement.newString +
+            content.slice(firstIndex + replacement.oldString.length),
         replacements: 1,
     };
 }
@@ -190,4 +295,40 @@ function applyLineInsert(content, input) {
         replacements: 1,
     };
 }
+/**
+ * Reconcile the caller's line endings with the file's.
+ *
+ * A model reading a CRLF file and writing back LF (or the reverse) produces
+ * an `old_string` that is correct in every visible way and matches nothing.
+ * The failure reads as "your text is wrong" when the text is right and only
+ * the invisible half of each line break differs.
+ *
+ * Only applied when the file is CONSISTENT. A mixed-ending file has no
+ * single right answer, and rewriting boundaries there would corrupt the
+ * half that was already correct.
+ */
+function normalizeLineEndings(content, input) {
+    const withoutCrlf = content.replaceAll('\r\n', '');
+    const usesOnlyCrlf = content.includes('\r\n') && !withoutCrlf.includes('\n');
+    if (usesOnlyCrlf) {
+        return {
+            ...input,
+            oldString: content.includes(input.oldString)
+                ? input.oldString
+                : input.oldString.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n'),
+            newString: input.newString.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n'),
+        };
+    }
+    const usesOnlyLf = content.includes('\n') && !content.includes('\r\n');
+    if (usesOnlyLf) {
+        return {
+            ...input,
+            oldString: content.includes(input.oldString)
+                ? input.oldString
+                : input.oldString.replaceAll('\r\n', '\n'),
+            newString: input.newString.replaceAll('\r\n', '\n'),
+        };
+    }
+    return input;
+}
 //# sourceMappingURL=edit.js.map