vexi-cli 0.5.5 → 0.9.0

package/dist/snapshots/index.js

@@ -0,0 +1,278 @@
+/**
+ * Snapshot engine for undo/redo of AI file edits.
+ *
+ * Before executing any shell command that looks like a file write, Vexi
+ * saves a copy of only the affected files into:
+ *
+ *   .vexi/snapshots/<session-id>/<entry-id>/files/<encoded-path>
+ *
+ * State (undo/redo stacks) is persisted in:
+ *   .vexi/snapshots/<session-id>/state.json
+ *
+ * The active session is tracked in:
+ *   .vexi/snapshots/current-session
+ *
+ * Design choices:
+ * - Only snapshots files it is about to change (NOT the whole project tree).
+ * - Max 50 snapshots per session; oldest pruned automatically.
+ * - Undo restores the pre-command file state; redo re-applies the reverted state.
+ * - New files created by a command are not deleted on undo (limitation v1).
+ */
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join, isAbsolute, relative, dirname, resolve, sep } from 'node:path';
+import { writeJsonAtomic, readJson } from '../utils/fs-atomic.js';
+/**
+ * Resolve `rel` against `root` and verify the result stays inside `root`.
+ * Blocks path traversal (e.g. a relative path containing `..` segments)
+ * from letting snapshot save/restore read or overwrite files outside the
+ * project — snapshots are only ever meant to cover project files.
+ */
+function resolveWithinRoot(root, rel) {
+    const absRoot = resolve(root);
+    const abs = isAbsolute(rel) ? resolve(rel) : resolve(absRoot, rel);
+    if (abs !== absRoot && !abs.startsWith(absRoot + sep))
+        return null;
+    return abs;
+}
+const MAX_SNAPSHOTS = 50;
+function makeId() {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+}
+function encodeRelPath(relPath) {
+    return relPath.replace(/[\\/]/g, '__').replace(/:/g, '_C_');
+}
+export class SnapshotManager {
+    root;
+    sessionId;
+    sessionDir;
+    statePath;
+    _state = null;
+    constructor(root, sessionId) {
+        this.root = root;
+        this.sessionId = sessionId;
+        this.sessionDir = join(root, '.vexi', 'snapshots', sessionId);
+        this.statePath = join(this.sessionDir, 'state.json');
+    }
+    /** Create a manager pointing at the most-recently registered session. */
+    static async forCurrentSession(root) {
+        const markerPath = join(root, '.vexi', 'snapshots', 'current-session');
+        try {
+            const id = (await fs.readFile(markerPath, 'utf-8')).trim();
+            if (id)
+                return new SnapshotManager(root, id);
+        }
+        catch { }
+        return null;
+    }
+    /** Write the "current-session" marker so CLI commands can find this session. */
+    async registerAsCurrentSession() {
+        const markerPath = join(this.root, '.vexi', 'snapshots', 'current-session');
+        await fs.mkdir(dirname(markerPath), { recursive: true });
+        await fs.writeFile(markerPath, this.sessionId, 'utf-8');
+    }
+    async getState() {
+        if (this._state)
+            return this._state;
+        const loaded = await readJson(this.statePath);
+        this._state = loaded ?? {
+            sessionId: this.sessionId,
+            undoStack: [],
+            redoStack: [],
+            entries: {},
+        };
+        return this._state;
+    }
+    async persistState() {
+        if (this._state)
+            await writeJsonAtomic(this.statePath, this._state);
+    }
+    async saveFiles(id, relPaths) {
+        const dir = join(this.sessionDir, id, 'files');
+        await fs.mkdir(dir, { recursive: true });
+        const saved = [];
+        for (const rel of relPaths) {
+            const abs = resolveWithinRoot(this.root, rel);
+            if (!abs || !existsSync(abs))
+                continue;
+            await fs.copyFile(abs, join(dir, encodeRelPath(rel)));
+            saved.push(rel);
+        }
+        return saved;
+    }
+    async restoreFiles(id, relPaths) {
+        const dir = join(this.sessionDir, id, 'files');
+        for (const rel of relPaths) {
+            const dest = resolveWithinRoot(this.root, rel);
+            if (!dest)
+                continue;
+            try {
+                await fs.copyFile(join(dir, encodeRelPath(rel)), dest);
+            }
+            catch { }
+        }
+    }
+    async deleteEntry(state, id) {
+        delete state.entries[id];
+        await fs.rm(join(this.sessionDir, id), { recursive: true, force: true }).catch(() => { });
+    }
+    /**
+     * Save the current state of `files` before applying an edit.
+     * Call this right before running the shell command.
+     * Returns true if at least one file was snapshotted.
+     */
+    async takeSnapshot(files, label) {
+        if (files.length === 0)
+            return false;
+        const state = await this.getState();
+        const id = makeId();
+        const saved = await this.saveFiles(id, files);
+        if (saved.length === 0)
+            return false;
+        state.entries[id] = { id, at: Date.now(), label, files: saved };
+        state.undoStack.push(id);
+        state.redoStack = []; // new edit invalidates redo history
+        while (state.undoStack.length > MAX_SNAPSHOTS) {
+            await this.deleteEntry(state, state.undoStack.shift());
+        }
+        await this.persistState();
+        return true;
+    }
+    /** Restore the last snapshotted file state. Returns the reverted entry, or null if nothing to undo. */
+    async undo() {
+        const state = await this.getState();
+        if (state.undoStack.length === 0)
+            return null;
+        const id = state.undoStack[state.undoStack.length - 1];
+        const entry = state.entries[id];
+        if (!entry)
+            return null;
+        // Save current (post-edit) state as a redo point covering the same files
+        const redoId = makeId();
+        const redoSaved = await this.saveFiles(redoId, entry.files);
+        if (redoSaved.length > 0) {
+            state.entries[redoId] = { id: redoId, at: Date.now(), label: entry.label, files: redoSaved };
+            state.redoStack.push(redoId);
+        }
+        await this.restoreFiles(id, entry.files);
+        state.undoStack.pop();
+        await this.deleteEntry(state, id);
+        await this.persistState();
+        return entry;
+    }
+    /** Re-apply the last undone change. Returns the re-applied entry, or null if nothing to redo. */
+    async redo() {
+        const state = await this.getState();
+        if (state.redoStack.length === 0)
+            return null;
+        const id = state.redoStack[state.redoStack.length - 1];
+        const entry = state.entries[id];
+        if (!entry)
+            return null;
+        // Save current (post-undo) state back onto the undo stack
+        const undoId = makeId();
+        const undoSaved = await this.saveFiles(undoId, entry.files);
+        if (undoSaved.length > 0) {
+            state.entries[undoId] = { id: undoId, at: Date.now(), label: entry.label, files: undoSaved };
+            state.undoStack.push(undoId);
+        }
+        await this.restoreFiles(id, entry.files);
+        state.redoStack.pop();
+        await this.deleteEntry(state, id);
+        await this.persistState();
+        return entry;
+    }
+    /** List all available undo entries, newest first. */
+    async list() {
+        const state = await this.getState();
+        return [...state.undoStack]
+            .reverse()
+            .map((id) => state.entries[id])
+            .filter(Boolean);
+    }
+    /** Remove all snapshot sessions except this one (and the current-session marker). */
+    async clean() {
+        return SnapshotManager.cleanAll(this.root, this.sessionId);
+    }
+    /** Remove all snapshot session directories, optionally keeping one by ID. */
+    static async cleanAll(root, keepSessionId) {
+        const snapshotsDir = join(root, '.vexi', 'snapshots');
+        let count = 0;
+        try {
+            const entries = await fs.readdir(snapshotsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (keepSessionId && entry.name === keepSessionId)
+                    continue;
+                try {
+                    await fs.rm(join(snapshotsDir, entry.name), { recursive: true, force: true });
+                    count++;
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return count;
+    }
+    /**
+     * Extract file paths that a shell command is likely to write.
+     * Returns relative paths (relative to cwd) for files that currently exist on disk.
+     * This is best-effort: covers common patterns (cat >, sed -i, mv, cp, tee, etc.)
+     * and files with known extensions that appear as bare tokens in the command.
+     */
+    static extractFilePaths(command, cwd) {
+        const found = new Set();
+        const tryAdd = (raw) => {
+            if (!raw)
+                return;
+            const p = raw.trim().replace(/^["']|["']$/g, '');
+            if (!p || p.startsWith('-') || p.startsWith('http') || p === '/dev/null')
+                return;
+            const abs = isAbsolute(p) ? p : join(cwd, p);
+            if (!resolveWithinRoot(cwd, abs))
+                return; // never track files outside the project root
+            if (existsSync(abs)) {
+                found.add(relative(cwd, abs).replace(/\\/g, '/'));
+            }
+        };
+        // cat > file  /  cat >> file
+        for (const m of command.matchAll(/\bcat\s+>>?\s+(\S+)/gi))
+            tryAdd(m[1]);
+        // echo ... > file  /  >> file
+        for (const m of command.matchAll(/\becho\b.*?>>?\s+(\S+)/gi))
+            tryAdd(m[1]);
+        // sed -i[suffix] 'expr' file
+        for (const m of command.matchAll(/\bsed\b.*?-i\S*\s+(?:'[^']*'|"[^"]*"|\S+)\s+(\S+)/gi))
+            tryAdd(m[1]);
+        // patch [options] file
+        for (const m of command.matchAll(/\bpatch\b(?:\s+-[a-zA-Z0-9]+)*\s+(\S+)/gi))
+            tryAdd(m[1]);
+        // tee file
+        for (const m of command.matchAll(/\btee\s+(\S+)/gi))
+            tryAdd(m[1]);
+        // cp src dst
+        for (const m of command.matchAll(/\bcp\b(?:\s+-[a-zA-Z]+)*\s+(\S+)\s+(\S+)/gi)) {
+            tryAdd(m[1]);
+            tryAdd(m[2]);
+        }
+        // mv src dst
+        for (const m of command.matchAll(/\bmv\b(?:\s+-[a-zA-Z]+)*\s+(\S+)\s+(\S+)/gi)) {
+            tryAdd(m[1]);
+            tryAdd(m[2]);
+        }
+        // node/deno: fs.writeFileSync('file', ...)
+        for (const m of command.matchAll(/writeFileSync\s*\(\s*["']([^"']+)["']/gi))
+            tryAdd(m[1]);
+        // python: open('file', 'w') or open('file', 'a')
+        for (const m of command.matchAll(/\bopen\s*\(\s*["']([^"']+)["']\s*,\s*["'][wa]/gi))
+            tryAdd(m[1]);
+        // PowerShell: Set-Content / Out-File / Add-Content
+        for (const m of command.matchAll(/\b(?:Set-Content|Out-File|Add-Content)\b.*?-(?:Path|Value|FilePath)\s+["']?(\S+?)["']?(?:\s|$)/gi))
+            tryAdd(m[1]);
+        // Generic: bare token with a known source-file extension
+        for (const m of command.matchAll(/(?:^|[\s;|&>])["']?([\w./\\-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|py|rs|go|java|c|cpp|h|hpp|css|scss|html|yaml|yml|toml|sh|env|txt|xml|sql|graphql|vue|svelte|rb|php|swift|kt|cs))["']?(?=\s|$|[;|&])/gim))
+            tryAdd(m[1]);
+        return [...found];
+    }
+}

package/dist/snapshots/index.test.js

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { SnapshotManager } from './index.js';
+async function mkTmp() {
+    return fs.mkdtemp(join(tmpdir(), 'vexi-snap-test-'));
+}
+async function writeFile(dir, name, content) {
+    const p = join(dir, name);
+    await fs.writeFile(p, content, 'utf8');
+    return p;
+}
+describe('SnapshotManager', () => {
+    let root;
+    let manager;
+    beforeEach(async () => {
+        root = await mkTmp();
+        manager = new SnapshotManager(root, 'test-session');
+    });
+    afterEach(async () => {
+        await fs.rm(root, { recursive: true, force: true });
+    });
+    it('round-trip: takeSnapshot → undo restores file content', async () => {
+        const filePath = await writeFile(root, 'hello.txt', 'original');
+        const snapped = await manager.takeSnapshot([filePath], 'initial write');
+        expect(snapped).toBe(true);
+        await fs.writeFile(filePath, 'modified', 'utf8');
+        const entry = await manager.undo();
+        expect(entry).not.toBeNull();
+        expect(entry.files.some((f) => f.endsWith('hello.txt') || f === filePath)).toBe(true);
+        const restored = await fs.readFile(filePath, 'utf8');
+        expect(restored).toBe('original');
+    });
+    it('round-trip: undo → redo restores modified content', async () => {
+        const filePath = await writeFile(root, 'hello.txt', 'original');
+        await manager.takeSnapshot([filePath], 'initial write');
+        await fs.writeFile(filePath, 'modified', 'utf8');
+        await manager.undo();
+        const afterUndo = await fs.readFile(filePath, 'utf8');
+        expect(afterUndo).toBe('original');
+        const redoEntry = await manager.redo();
+        expect(redoEntry).not.toBeNull();
+        const afterRedo = await fs.readFile(filePath, 'utf8');
+        expect(afterRedo).toBe('modified');
+    });
+    it('list() returns newest snapshot first', async () => {
+        const filePath = await writeFile(root, 'a.txt', 'v1');
+        await manager.takeSnapshot([filePath], 'first');
+        await fs.writeFile(filePath, 'v2', 'utf8');
+        await manager.takeSnapshot([filePath], 'second');
+        const list = await manager.list();
+        expect(list.length).toBe(2);
+        expect(list[0].label).toBe('second');
+        expect(list[1].label).toBe('first');
+    });
+    it('undo() returns null when stack is empty', async () => {
+        const result = await manager.undo();
+        expect(result).toBeNull();
+    });
+    it('redo() returns null when stack is empty', async () => {
+        const result = await manager.redo();
+        expect(result).toBeNull();
+    });
+    it('takeSnapshot clears redo stack', async () => {
+        const filePath = await writeFile(root, 'b.txt', 'v1');
+        await manager.takeSnapshot([filePath], 'snap1');
+        await fs.writeFile(filePath, 'v2', 'utf8');
+        await manager.undo();
+        // new snapshot after undo — redo stack should be cleared
+        await manager.takeSnapshot([filePath], 'snap2');
+        const redo = await manager.redo();
+        expect(redo).toBeNull();
+    });
+    it('takeSnapshot returns false when no files exist', async () => {
+        const result = await manager.takeSnapshot([join(root, 'ghost.txt')], 'missing');
+        expect(result).toBe(false);
+    });
+});
+describe('SnapshotManager.extractFilePaths', () => {
+    let cwd;
+    beforeEach(async () => {
+        cwd = await fs.mkdtemp(join(tmpdir(), 'vexi-ext-test-'));
+        // create the files so existsSync passes
+        await fs.mkdir(join(cwd, 'src'), { recursive: true });
+        await fs.writeFile(join(cwd, 'src', 'app.ts'), '', 'utf8');
+        await fs.writeFile(join(cwd, 'src', 'utils.js'), '', 'utf8');
+    });
+    afterEach(async () => {
+        await fs.rm(cwd, { recursive: true, force: true });
+    });
+    it('extracts path from cat > redirect', () => {
+        const paths = SnapshotManager.extractFilePaths('cat > src/app.ts', cwd);
+        expect(paths.length).toBeGreaterThan(0);
+        expect(paths.some((p) => p.endsWith('app.ts'))).toBe(true);
+    });
+    it('extracts path from sed -i command', () => {
+        const paths = SnapshotManager.extractFilePaths("sed -i 's/foo/bar/' src/utils.js", cwd);
+        expect(paths.some((p) => p.endsWith('utils.js'))).toBe(true);
+    });
+    it('returns empty array for non-file commands', () => {
+        const paths = SnapshotManager.extractFilePaths('npm install', cwd);
+        expect(paths).toEqual([]);
+    });
+});

package/dist/tools/index.js

@@ -0,0 +1,280 @@
+/**
+ * Built-in file tools — Feature #1 (structured, deterministic file editing).
+ *
+ * The original design edited files by asking the model to emit shell commands
+ * (`cat >`, `sed -i`, `tee`…) which Vexi then ran, and the snapshot engine
+ * *regex-guessed* which files were touched. That is fragile: a mis-escaped
+ * `sed` corrupts files, and a missed write leaves nothing to undo.
+ *
+ * These built-in tools replace that path for editing. They use the same
+ * provider-agnostic text protocol as MCP (a fenced ```vexi-tool``` JSON block,
+ * WITHOUT a `server` field), so they work with every provider — no native
+ * function-calling API required. Because each write goes through here, the
+ * snapshot is taken on the *exact* file about to change, making undo precise.
+ */
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve, relative, sep, dirname } from 'node:path';
+/** Names of the built-in tools the model may call. */
+export const BUILTIN_TOOL_NAMES = ['read_file', 'write_file', 'edit_file'];
+/** Cap on how much file content is returned to the model in one read. */
+const MAX_READ_BYTES = 64 * 1024;
+/**
+ * Parse a built-in file-tool call from a model reply, or null.
+ * Matches a ```vexi-tool``` block whose `tool` is a known built-in name and
+ * which has NO `server` field (that is how MCP tool calls are told apart).
+ */
+export function parseBuiltinToolCall(reply) {
+    const match = reply.match(/```vexi-tool\s*\n([\s\S]*?)```/);
+    if (!match)
+        return null;
+    try {
+        const json = JSON.parse(match[1]);
+        if (typeof json.server === 'string')
+            return null; // that's an MCP call
+        if (typeof json.tool !== 'string')
+            return null;
+        if (!BUILTIN_TOOL_NAMES.includes(json.tool))
+            return null;
+        const { tool, ...args } = json;
+        return { tool, args };
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve `rel` against `root`, rejecting paths that escape the project root. */
+function resolveWithinRoot(root, rel) {
+    const absRoot = resolve(root);
+    const abs = isAbsolute(rel) ? resolve(rel) : resolve(absRoot, rel);
+    if (abs !== absRoot && !abs.startsWith(absRoot + sep))
+        return null;
+    return abs;
+}
+function asString(v) {
+    return typeof v === 'string' ? v : null;
+}
+/** Count non-overlapping occurrences of `needle` in `haystack`. */
+function countOccurrences(haystack, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let i = haystack.indexOf(needle);
+    while (i !== -1) {
+        count++;
+        i = haystack.indexOf(needle, i + needle.length);
+    }
+    return count;
+}
+/**
+ * Execute a built-in file tool. Snapshots any file about to be written
+ * (via the provided SnapshotManager) so the edit is undoable exactly.
+ */
+export async function executeBuiltinTool(call, root, snapshots) {
+    const rawPath = asString(call.args.path);
+    if (!rawPath)
+        return { result: 'TOOL ERROR: missing "path".', files: [] };
+    const abs = resolveWithinRoot(root, rawPath);
+    if (!abs)
+        return { result: `TOOL ERROR: path "${rawPath}" is outside the project root.`, files: [] };
+    const rel = relative(root, abs).replace(/\\/g, '/');
+    switch (call.tool) {
+        // ── read_file {path, [start], [end]} ────────────────────────────────
+        case 'read_file': {
+            if (!existsSync(abs))
+                return { result: `TOOL ERROR: file not found: ${rel}`, files: [] };
+            let content;
+            try {
+                content = await fs.readFile(abs, 'utf-8');
+            }
+            catch (e) {
+                return { result: `TOOL ERROR: cannot read ${rel}: ${e instanceof Error ? e.message : String(e)}`, files: [] };
+            }
+            const lines = content.split('\n');
+            const start = Number.isInteger(call.args.start) ? Math.max(1, call.args.start) : 1;
+            const end = Number.isInteger(call.args.end) ? Math.min(lines.length, call.args.end) : lines.length;
+            const slice = lines.slice(start - 1, end);
+            let numbered = slice.map((l, i) => `${start + i}\t${l}`).join('\n');
+            if (numbered.length > MAX_READ_BYTES) {
+                numbered = numbered.slice(0, MAX_READ_BYTES) + '\n… [truncated — read a smaller line range]';
+            }
+            return { result: `FILE ${rel} (lines ${start}-${end} of ${lines.length}):\n${numbered}`, files: [] };
+        }
+        // ── write_file {path, content} — create or overwrite ────────────────
+        case 'write_file': {
+            const content = asString(call.args.content);
+            if (content === null)
+                return { result: 'TOOL ERROR: missing "content".', files: [] };
+            const existed = existsSync(abs);
+            if (existed) {
+                // Snapshot the current version BEFORE overwriting so undo restores it.
+                await snapshots.takeSnapshot([rel], `write_file ${rel}`).catch(() => { });
+            }
+            try {
+                await fs.mkdir(dirname(abs), { recursive: true });
+                await fs.writeFile(abs, content, 'utf-8');
+            }
+            catch (e) {
+                return { result: `TOOL ERROR: cannot write ${rel}: ${e instanceof Error ? e.message : String(e)}`, files: [] };
+            }
+            const lineCount = content.split('\n').length;
+            return {
+                result: `OK: ${existed ? 'overwrote' : 'created'} ${rel} (${lineCount} lines).`,
+                files: [rel],
+            };
+        }
+        // ── edit_file {path, old, new, [all]} — exact substring replace ──────
+        case 'edit_file': {
+            const oldStr = asString(call.args.old);
+            const newStr = asString(call.args.new);
+            if (oldStr === null || newStr === null) {
+                return { result: 'TOOL ERROR: edit_file requires string "old" and "new".', files: [] };
+            }
+            if (oldStr === newStr) {
+                return { result: 'TOOL ERROR: "old" and "new" are identical — nothing to change.', files: [] };
+            }
+            if (!existsSync(abs))
+                return { result: `TOOL ERROR: file not found: ${rel}`, files: [] };
+            let content;
+            try {
+                content = await fs.readFile(abs, 'utf-8');
+            }
+            catch (e) {
+                return { result: `TOOL ERROR: cannot read ${rel}: ${e instanceof Error ? e.message : String(e)}`, files: [] };
+            }
+            const occurrences = countOccurrences(content, oldStr);
+            if (occurrences === 0) {
+                return { result: `TOOL ERROR: "old" string not found in ${rel}. Read the file and copy the exact text (including whitespace).`, files: [] };
+            }
+            const all = call.args.all === true;
+            if (occurrences > 1 && !all) {
+                return {
+                    result: `TOOL ERROR: "old" matches ${occurrences} places in ${rel}. Add surrounding context to make it unique, or set "all": true to replace every occurrence.`,
+                    files: [],
+                };
+            }
+            // Snapshot BEFORE editing so undo restores the pre-edit version exactly.
+            await snapshots.takeSnapshot([rel], `edit_file ${rel}`).catch(() => { });
+            const updated = all
+                ? content.split(oldStr).join(newStr)
+                : content.replace(oldStr, newStr);
+            try {
+                await fs.writeFile(abs, updated, 'utf-8');
+            }
+            catch (e) {
+                return { result: `TOOL ERROR: cannot write ${rel}: ${e instanceof Error ? e.message : String(e)}`, files: [] };
+            }
+            return {
+                result: `OK: edited ${rel} (${all ? occurrences : 1} replacement${all && occurrences > 1 ? 's' : ''}).`,
+                files: [rel],
+            };
+        }
+        default:
+            return { result: `TOOL ERROR: unknown built-in tool "${call.tool}".`, files: [] };
+    }
+}
+// ── Native function-calling support ───────────────────────────────────────────
+/** JSON-Schema definitions of the built-in file tools, for native tool calling. */
+export const BUILTIN_TOOL_DEFS = [
+    {
+        name: 'read_file',
+        description: 'Read a file from the project, optionally a 1-based line range. Read before editing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Project-relative file path.' },
+                start: { type: 'integer', description: 'First line to read (1-based).' },
+                end: { type: 'integer', description: 'Last line to read (inclusive).' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'write_file',
+        description: 'Create a new file or fully overwrite an existing one with exact content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Project-relative file path.' },
+                content: { type: 'string', description: 'Full file content to write.' },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    {
+        name: 'edit_file',
+        description: 'Replace the exact substring "old" with "new" in a file. "old" must appear verbatim and be unique unless "all" is true.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Project-relative file path.' },
+                old: { type: 'string', description: 'Exact existing text to replace (include surrounding context to be unique).' },
+                new: { type: 'string', description: 'Replacement text.' },
+                all: { type: 'boolean', description: 'Replace every occurrence instead of requiring uniqueness.' },
+            },
+            required: ['path', 'old', 'new'],
+        },
+    },
+];
+/** Separator between an MCP server name and tool name in a native tool call. */
+const MCP_SEP = '__';
+/**
+ * Build the full native tool list (built-in file tools + connected MCP tools)
+ * and a router that maps each tool name back to how it should be executed.
+ */
+export function buildNativeTools(mcp) {
+    const route = new Map();
+    const defs = [];
+    for (const def of BUILTIN_TOOL_DEFS) {
+        defs.push(def);
+        route.set(def.name, { kind: 'builtin' });
+    }
+    for (const t of mcp.tools) {
+        // Function names must match ^[a-zA-Z0-9_-]+$ — encode "server/tool" safely.
+        const name = `${t.server}${MCP_SEP}${t.name}`.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const schema = (t.inputSchema && typeof t.inputSchema === 'object')
+            ? t.inputSchema
+            : { type: 'object', properties: {} };
+        defs.push({ name, description: t.description.split('\n')[0], inputSchema: schema });
+        route.set(name, { kind: 'mcp', server: t.server, tool: t.name });
+    }
+    return { defs, route };
+}
+/**
+ * Execute a native tool call by name, routing to a built-in file tool or an
+ * MCP server. Returns the text result plus any project files that changed.
+ */
+export async function dispatchNativeTool(name, args, route, root, snapshots, mcp) {
+    const target = route.get(name);
+    if (!target)
+        return { result: `TOOL ERROR: unknown tool "${name}".`, files: [] };
+    if (target.kind === 'builtin') {
+        return executeBuiltinTool({ tool: name, args }, root, snapshots);
+    }
+    try {
+        const result = await mcp.callTool(target.server, target.tool, args);
+        return { result, files: [] };
+    }
+    catch (e) {
+        return { result: `TOOL ERROR: ${e instanceof Error ? e.message : String(e)}`, files: [] };
+    }
+}
+/** System-prompt block describing the built-in file tools. */
+export function builtinToolsBlock() {
+    return [
+        '## File tools (built-in — prefer these over shell for reading/editing files)',
+        'Read and edit files directly and reliably with these tools instead of shell commands',
+        '(cat/sed/tee). To call one, reply with ONLY a fenced block and nothing else:',
+        '```vexi-tool',
+        '{"tool": "edit_file", "path": "src/foo.ts", "old": "<exact text>", "new": "<replacement>"}',
+        '```',
+        'Available tools:',
+        '- read_file {path, [start], [end]} — return file contents, optionally a 1-based line range. Read before editing.',
+        '- write_file {path, content} — create a new file or fully overwrite an existing one with exact content.',
+        '- edit_file {path, old, new, [all]} — replace the exact substring "old" with "new". "old" must appear verbatim '
+            + 'and be unique unless you set "all": true. Include enough surrounding context to make "old" unique.',
+        'The JSON must be valid: escape newlines as \\n and quotes as \\" inside string values. Do NOT include a "server" field '
+            + '(that is reserved for MCP tools). You will receive the tool result in the next message; then continue.',
+        'Still use `bash` shell blocks for non-editing work: installing deps, building, running tests, starting servers.',
+    ].join('\n');
+}