@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/textTools.js

@@ -1,156 +1,293 @@
-import { constants, realpathSync, statSync } from 'node:fs';
-import { lstat, open, rename, unlink } from 'node:fs/promises';
+import { open, rename, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-class FileFault extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-    }
-}
+import { FileFault, bounded, workspaceRoot, validPath, checkPath, readSnapshot, digest, fits, cursor, readCursor, replace, diff, assertText } from './fileToolsSupport.js';
 const fail = (code, message) => ({ code, message, effect: 'none' });
-/** Controlled local directories only. Path checks are NOT an adversarial sandbox. */
-export function createTextTools({ root, maxBytes = 64 * 1024 }) {
-    if (!path.isAbsolute(root))
-        throw new Error('An explicit absolute workspace root is required');
-    const workspace = realpathSync(root);
-    if (!statSync(workspace).isDirectory())
-        throw new Error('Workspace must be a directory');
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 64 * 1024) {
-        throw new Error('maxBytes must be an integer in [1, 65536]');
-    }
-    const validate = (args, write) => {
-        if (!args || typeof args !== 'object' || Array.isArray(args)
-            || typeof args.path !== 'string' || !args.path.trim()
-            || Object.keys(args).some(k => k !== 'path' && !(write && k === 'content'))
-            || (write && typeof args.content !== 'string'))
-            return fail('invalid_arguments', 'Expected path and, for write, content');
-        if (args.path.includes('\0') || path.isAbsolute(args.path) || args.path.split(/[\\/]/).includes('..')) {
-            return fail('path_out_of_scope', 'Expected a relative path without parent traversal');
-        }
-        if (write && Buffer.byteLength(args.content) > maxBytes)
-            return fail('too_large', 'Text exceeds byte limit');
-        return null;
-    };
-    const check = async (relative, allowMissing) => {
-        const target = path.resolve(workspace, relative);
-        const rel = path.relative(workspace, target);
-        if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
-            throw new FileFault('path_out_of_scope', 'Path is outside the file workspace');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Controlled directories only. Queues are same-pack, not cross-process CAS or a multi-file transaction. */
+export function createTextTools(options) {
+    const root = workspaceRoot(options.root);
+    const maxBytes = bounded(options.maxBytes, 8 * 1024 * 1024, 'maxBytes');
+    const maxOutputBytes = bounded(options.maxOutputBytes, 64 * 1024, 'maxOutputBytes');
+    const writers = new Map();
+    const targetsFor = (args, name) => name === 'patch'
+        ? args.files : name === 'edit' ? [{
+            path: args.path, expectedSha256: args.expectedSha256,
+            edits: [{ oldText: args.oldText, newText: args.newText }],
+        }] : [args];
+    const validate = (args, name) => {
+        if (!object(args))
+            return fail('invalid_arguments', 'Expected an argument object');
+        const keys = name === 'patch' ? ['files'] : name === 'read' ? ['path', 'startLine', 'limit', 'cursor']
+            : name === 'edit' ? ['path', 'expectedSha256', 'oldText', 'newText'] : ['path', 'content', 'expectedSha256'];
+        if (Object.keys(args).some(key => !keys.includes(key)))
+            return fail('invalid_arguments', 'Unexpected tool fields');
+        if (Buffer.byteLength(JSON.stringify(args)) > 64 * 1024)
+            return fail('too_large', 'Arguments exceed 64 KiB');
+        if (name === 'read') {
+            if (!validPath(args.path))
+                return fail(typeof args.path === 'string' && (path.isAbsolute(args.path)
+                    || args.path.split(/[\\/]/).includes('..')) ? 'path_out_of_scope' : 'invalid_arguments', 'Expected a bounded relative file path');
+            if (['startLine', 'limit'].some(key => args[key] !== undefined && (typeof args[key] !== 'number'
+                || !Number.isSafeInteger(args[key]) || args[key] < 1 || args[key] > 1_000_000))
+                || (args.cursor !== undefined && (typeof args.cursor !== 'string' || !args.cursor || args.cursor.length > 2048))) {
+                return fail('invalid_arguments', 'Expected positive startLine/limit and an optional cursor');
+            }
+            return null;
         }
-        const parts = rel.split(path.sep);
-        let current = workspace;
-        for (let i = 0; i < parts.length; i++) {
-            current = path.join(current, parts[i]);
-            const final = i === parts.length - 1;
-            let stat;
-            try {
-                stat = await lstat(current);
+        if (name === 'patch' && (!Array.isArray(args.files) || !args.files.length || args.files.length > 16
+            || !args.files.every(object)))
+            return fail('invalid_arguments', 'patch expects 1..16 existing files');
+        const targets = targetsFor(args, name);
+        for (const target of targets) {
+            if (!validPath(target.path))
+                return fail(typeof target.path === 'string' && (path.isAbsolute(target.path)
+                    || target.path.split(/[\\/]/).includes('..')) ? 'path_out_of_scope' : 'invalid_arguments', 'Expected bounded relative file paths');
+            if (name === 'patch' && Object.keys(target).some(key => !['path', 'expectedSha256', 'edits'].includes(key))) {
+                return fail('invalid_arguments', 'Unexpected patch file fields');
             }
-            catch (error) {
-                if (error.code === 'ENOENT' && final && allowMissing)
-                    return target;
-                throw error;
+            if (target.expectedSha256 !== undefined && (typeof target.expectedSha256 !== 'string'
+                || !/^[a-f0-9]{64}$/.test(target.expectedSha256)))
+                return fail('invalid_arguments', 'Expected lowercase SHA-256');
+            if (name === 'write') {
+                if (typeof target.content !== 'string')
+                    return fail('invalid_arguments', 'Expected content');
+                if (Buffer.byteLength(target.content) > maxBytes)
+                    return fail('too_large', 'Text exceeds byte limit');
             }
-            if (stat.isSymbolicLink())
-                throw new FileFault('symlink_denied', 'Symlinks are not allowed');
-            if (final ? !stat.isFile() || stat.nlink > 1 : !stat.isDirectory()) {
-                throw new FileFault('not_regular_file', 'Expected ordinary directories and a single-link regular file');
+            else {
+                if (typeof target.expectedSha256 !== 'string' || !Array.isArray(target.edits) || !target.edits.length
+                    || target.edits.length > 32 || target.edits.some(edit => !object(edit)
+                    || Object.keys(edit).some(key => !['oldText', 'newText'].includes(key))
+                    || typeof edit.oldText !== 'string' || !edit.oldText || typeof edit.newText !== 'string')) {
+                    return fail('invalid_arguments', 'Expected 1..32 exact edits and a SHA-256 precondition');
+                }
+                if (target.edits.some(edit => [edit.oldText, edit.newText].some(text => Buffer.byteLength(text) > maxBytes))) {
+                    return fail('too_large', 'Text exceeds byte limit');
+                }
             }
         }
-        return target;
+        return null;
     };
-    return ['read', 'write'].map(name => {
-        const writing = name === 'write';
-        return {
-            definition: {
-                name,
-                description: writing ? 'Replace a workspace UTF-8 text file' : 'Read a bounded workspace UTF-8 text file',
-                inputSchema: { type: 'object', properties: { path: { type: 'string' },
-                        ...(writing ? { content: { type: 'string' } } : {}) },
-                    required: writing ? ['path', 'content'] : ['path'], additionalProperties: false },
-            },
-            validate: (args) => validate(args, writing),
-            async execute(args, _scope, signal) {
-                const invalid = validate(args, writing);
-                if (invalid)
-                    return { ok: false, error: invalid };
-                const { path: relative, content } = args;
-                let temporary;
-                let committed = false;
-                let result;
-                try {
-                    signal.throwIfAborted();
-                    const target = await check(relative, writing);
-                    if (!writing) {
-                        const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-                        try {
-                            const stat = await file.stat();
-                            if (!stat.isFile() || stat.nlink > 1)
-                                throw new FileFault('not_regular_file', 'Expected single-link regular file');
-                            if (stat.size > maxBytes)
-                                throw new FileFault('too_large', 'File exceeds byte limit');
-                            const buffer = Buffer.alloc(maxBytes + 1);
-                            let bytes = 0;
-                            while (bytes < buffer.length) {
-                                signal.throwIfAborted();
-                                const read = await file.read(buffer, bytes, buffer.length - bytes, bytes);
-                                if (!read.bytesRead)
-                                    break;
-                                bytes += read.bytesRead;
-                            }
-                            if (bytes > maxBytes)
-                                throw new FileFault('too_large', 'File exceeds byte limit');
-                            let text;
-                            try {
-                                text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, bytes));
-                            }
-                            catch {
-                                throw new FileFault('invalid_utf8', 'File is not valid UTF-8');
-                            }
-                            result = { ok: true, content: JSON.stringify({ path: relative, text, bytes }) };
-                        }
-                        finally {
-                            await file.close();
+    const editSchema = { type: 'object', properties: { oldText: { type: 'string' }, newText: { type: 'string' } },
+        required: ['oldText', 'newText'], additionalProperties: false };
+    return ['read', 'write', 'edit', 'patch'].map(name => ({
+        definition: {
+            name,
+            description: name === 'read' ? 'Read UTF-8 pages with full-file SHA-256, exact byte offsets and request-bound cursor'
+                : name === 'patch' ? 'Unique nonoverlapping original-text edits to existing files; preflight all, sequential commits, bounded actual diffs; partial failures stop'
+                    : name === 'edit' ? 'Replace one unique literal match with expected SHA-256 and actual diff'
+                        : 'Create or replace UTF-8 text with SHA-256 precondition and actual diff',
+            inputSchema: { type: 'object', properties: name === 'patch' ? { files: { type: 'array', minItems: 1, maxItems: 16,
+                        items: { type: 'object', properties: { path: { type: 'string' }, expectedSha256: { type: 'string' },
+                                edits: { type: 'array', minItems: 1, maxItems: 32, items: editSchema } },
+                            required: ['path', 'expectedSha256', 'edits'], additionalProperties: false } } }
+                    : { path: { type: 'string' }, ...(name === 'read' ? { startLine: { type: 'integer' },
+                            limit: { type: 'integer' }, cursor: { type: 'string' } } : { expectedSha256: { type: 'string' },
+                            ...(name === 'edit' ? editSchema.properties : { content: { type: 'string' } }) }) },
+                required: name === 'patch' ? ['files'] : name === 'read' ? ['path'] : name === 'edit'
+                    ? ['path', 'expectedSha256', 'oldText', 'newText'] : ['path', 'content'], additionalProperties: false },
+        },
+        validate: args => validate(args, name),
+        async execute(args, scope, signal) {
+            const invalid = validate(args, name);
+            if (invalid)
+                return { ok: false, error: invalid };
+            const outcome = (value) => ({ ok: true, content: JSON.stringify(value) });
+            const fit = (result) => fits(result, maxOutputBytes, name, scope.toolCallId);
+            const readText = async (target) => {
+                const snapshot = await readSnapshot(target, maxBytes, signal);
+                assertText(snapshot.text);
+                return snapshot;
+            };
+            const held = [];
+            const receipts = [];
+            let temporary;
+            let committing = false;
+            let index = 0;
+            try {
+                signal.throwIfAborted();
+                if (name === 'read') {
+                    const request = args;
+                    const snapshot = await readText(await checkPath(root, request.path));
+                    const binding = digest(JSON.stringify([request.path, request.startLine ?? 1, request.limit ?? 200, maxBytes, maxOutputBytes]));
+                    const fingerprint = snapshot.sha256 + ':' + snapshot.identity;
+                    let start = readCursor(request.cursor, binding, fingerprint, snapshot.text.length);
+                    if (!request.cursor) {
+                        for (let line = 1; line < (request.startLine ?? 1); line++) {
+                            const offset = snapshot.text.indexOf('\n', start);
+                            if (offset < 0)
+                                throw new FileFault('line_out_of_range', 'startLine is beyond EOF');
+                            start = offset + 1;
                         }
                     }
-                    else {
-                        const candidate = path.join(path.dirname(target), `.agent-${randomUUID()}.tmp`);
-                        const file = await open(candidate, 'wx', 0o600);
-                        temporary = candidate;
-                        try {
-                            await file.writeFile(content, { encoding: 'utf8', signal });
-                        }
-                        finally {
-                            await file.close();
+                    if (start > 0 && /[\uDC00-\uDFFF]/.test(snapshot.text[start] ?? ''))
+                        throw new FileFault('invalid_cursor', 'Cursor splits a code point');
+                    let end = start;
+                    for (let count = 0; count < (request.limit ?? 200) && end < snapshot.text.length; count++) {
+                        const offset = snapshot.text.indexOf('\n', end);
+                        end = offset < 0 ? snapshot.text.length : offset + 1;
+                    }
+                    const requestedEnd = end;
+                    const lineAt = (offset) => {
+                        let line = 1;
+                        for (let i = 0; i < offset; i++)
+                            if (snapshot.text[i] === '\n')
+                                line++;
+                        return line;
+                    };
+                    const make = (stop) => outcome({ path: request.path, text: snapshot.text.slice(start, stop),
+                        bytes: Buffer.byteLength(snapshot.text.slice(start, stop)), fileBytes: snapshot.bytes, sha256: snapshot.sha256,
+                        byteStart: Buffer.byteLength(snapshot.text.slice(0, start)), byteEnd: Buffer.byteLength(snapshot.text.slice(0, stop)),
+                        startLine: lineAt(start), endLine: lineAt(Math.max(start, stop - 1)),
+                        complete: stop === snapshot.text.length, nextCursor: stop === snapshot.text.length ? null : cursor(binding, fingerprint, stop),
+                        truncationReason: stop < requestedEnd ? 'output_bytes' : stop < snapshot.text.length ? 'line_limit' : null });
+                    if (!fit(make(end))) {
+                        let low = start;
+                        let high = end;
+                        while (low < high) {
+                            let middle = Math.ceil((low + high) / 2);
+                            if (/[\uDC00-\uDFFF]/.test(snapshot.text[middle] ?? ''))
+                                middle--;
+                            if (middle <= low)
+                                break;
+                            if (fit(make(middle)))
+                                low = middle;
+                            else
+                                high = middle - 1;
                         }
-                        await check(relative, true);
-                        signal.throwIfAborted();
-                        await rename(temporary, target);
-                        committed = true;
-                        temporary = undefined;
-                        result = { ok: true, content: JSON.stringify({ path: relative, bytes: Buffer.byteLength(content) }) };
+                        end = low;
+                    }
+                    if ((end === start && start < snapshot.text.length) || !fit(make(end))) {
+                        throw new FileFault('output_limit', 'Budget cannot hold one code point and metadata');
                     }
+                    return make(end);
                 }
-                catch (error) {
-                    const code = error instanceof FileFault ? error.code
-                        : signal.aborted ? 'cancelled_before_commit'
-                            : error.code === 'ENOENT' ? 'not_found' : 'io_error';
-                    result = { ok: false, error: fail(code, error instanceof FileFault ? error.message : `File operation failed (${code})`) };
+                const targets = targetsFor(args, name);
+                const keys = targets.map(target => path.resolve(root, target.path));
+                if (new Set(keys).size !== keys.length)
+                    throw new FileFault('edit_conflict', 'Duplicate target paths');
+                for (const key of [...keys].sort()) {
+                    const previous = writers.get(key);
+                    let release;
+                    const promise = new Promise(resolve => { release = resolve; });
+                    writers.set(key, promise);
+                    held.push({ key, promise, release });
+                    await previous;
+                    signal.throwIfAborted();
                 }
+                const snapshots = [];
+                const candidates = [];
+                const snapshot = async (target) => {
+                    const absolute = await checkPath(root, target.path, name === 'write');
+                    if (absolute === root)
+                        throw new FileFault('not_regular_file', 'Expected a file');
+                    try {
+                        return await readText(absolute);
+                    }
+                    catch (error) {
+                        if (name === 'write' && error.code === 'ENOENT')
+                            return undefined;
+                        throw error;
+                    }
+                };
+                let totalBytes = 0;
+                for (const target of targets) {
+                    signal.throwIfAborted();
+                    const before = await snapshot(target);
+                    if (target.expectedSha256 === undefined ? before !== undefined : before?.sha256 !== target.expectedSha256) {
+                        throw new FileFault('edit_conflict', 'File changed or exists without an expected SHA-256');
+                    }
+                    const edits = target.edits ? target.edits.map(edit => {
+                        const start = before.text.indexOf(edit.oldText);
+                        if (start < 0 || before.text.indexOf(edit.oldText, start + 1) >= 0) {
+                            throw new FileFault('edit_conflict', 'oldText must match exactly once, including overlapping matches');
+                        }
+                        return { start, end: start + edit.oldText.length, text: edit.newText };
+                    }).sort((a, b) => a.start - b.start) : [{ start: 0, end: before?.text.length ?? 0, text: target.content }];
+                    if (edits.some((edit, i) => i > 0 && edit.start < edits[i - 1].end))
+                        throw new FileFault('edit_conflict', 'Edits overlap in original text');
+                    const next = replace(before?.text ?? '', edits);
+                    assertText(next);
+                    const bytes = Buffer.byteLength(next);
+                    totalBytes += bytes + (before?.bytes ?? 0);
+                    if (bytes > maxBytes || totalBytes > 32 * 1024 * 1024)
+                        throw new FileFault('too_large', 'Mutation snapshot byte budget exceeded');
+                    snapshots.push(before);
+                    candidates.push(next);
+                    receipts.push({ path: target.path, status: 'not_attempted', beforeSha256: before?.sha256 ?? null,
+                        sha256: null, candidateSha256: digest(next), bytes,
+                        diff: diff(target.path, before?.text ?? '', edits, next, before === undefined) });
+                }
+                const success = () => outcome(name === 'patch' ? { files: receipts, complete: true } : receipts[0]);
+                const cleanupPath = targets.reduce((longest, target) => {
+                    const candidate = path.join(path.dirname(target.path), `.agent-${'0'.repeat(36)}.tmp`);
+                    return Buffer.byteLength(JSON.stringify(JSON.stringify(candidate))) > Buffer.byteLength(JSON.stringify(JSON.stringify(longest)))
+                        ? candidate : longest;
+                }, '');
+                const reserved = receipts.map(receipt => ({ ...receipt, status: 'not_attempted', sha256: receipt.candidateSha256 }));
+                const partial = { ok: false, error: { code: 'cancelled_before_commit', effect: 'unknown',
+                        message: JSON.stringify({ complete: false, files: reserved, failedIndex: targets.length, cause: 'cancelled_before_commit',
+                            temporary: cleanupPath }) + ' '.repeat(256) } };
+                // Include the most expensive doubly encoded cleanup path BEFORE touching any file.
+                if (!fit(outcome(name === 'patch' ? { files: reserved, complete: true } : reserved[0])) || !fit(partial)) {
+                    throw new FileFault('output_limit', 'Encoded diff/receipt exceeds budget; no writes attempted');
+                }
+                committing = true;
+                for (index = 0; index < targets.length; index++) {
+                    const target = targets[index];
+                    signal.throwIfAborted();
+                    const absolute = await checkPath(root, target.path, name === 'write');
+                    const candidate = path.join(path.dirname(absolute), `.agent-${randomUUID()}.tmp`);
+                    const file = await open(candidate, 'wx', 0o600);
+                    temporary = candidate;
+                    try {
+                        await file.writeFile(candidates[index], { encoding: 'utf8', signal });
+                    }
+                    finally {
+                        await file.close();
+                    }
+                    const after = await snapshot(target);
+                    if (snapshots[index]?.identity !== after?.identity || snapshots[index]?.sha256 !== after?.sha256) {
+                        throw new FileFault('edit_conflict', 'File changed before commit; no replacement was made');
+                    }
+                    signal.throwIfAborted();
+                    await rename(temporary, absolute);
+                    temporary = undefined;
+                    receipts[index].status = 'committed';
+                    receipts[index].sha256 = receipts[index].candidateSha256;
+                }
+                return success();
+            }
+            catch (error) {
+                const code = error instanceof FileFault ? error.code : signal.aborted ? 'cancelled_before_commit'
+                    : error.code === 'ENOENT' ? 'not_found' : 'io_error';
+                let cleanupFailed = false;
                 if (temporary) {
                     try {
                         await unlink(temporary);
+                        temporary = undefined;
                     }
                     catch {
-                        return { ok: false, error: { code: 'cleanup_failed',
-                                message: `Owned temporary file remains: ${path.relative(workspace, temporary)}; targetCommitted=${committed}`,
-                                effect: 'unknown' } };
+                        cleanupFailed = true;
                     }
                 }
-                return result;
-            },
-        };
-    });
+                const committed = receipts.some(receipt => receipt.status === 'committed');
+                if (committing && index < receipts.length)
+                    receipts[index].status = 'rejected';
+                if (committed || cleanupFailed)
+                    return { ok: false, error: { code: cleanupFailed ? 'cleanup_failed' : code, effect: 'unknown',
+                            message: JSON.stringify({ complete: false, files: receipts, failedIndex: index, cause: code,
+                                temporary: temporary ? path.relative(root, temporary) : null }) } };
+                return { ok: false, error: fail(code, error instanceof FileFault ? error.message : `File operation failed (${code})`) };
+            }
+            finally {
+                for (const lock of held.reverse()) {
+                    lock.release();
+                    if (writers.get(lock.key) === lock.promise)
+                        writers.delete(lock.key);
+                }
+            }
+        },
+    }));
 }