zames_pro 2.13.0 → 2.14.0

package/README.md

@@ -76,6 +76,23 @@ zames --version
 zames --help
 ```
 
+## Tools
+
+The agent has the same style of tools as Claude Code / Codex CLI:
+
+- **File tools** — `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`. `Read`
+  returns raw content by default; pass `numbered=true` to get `cat -n`-style
+  line numbers (for reference only — do not paste them into `Edit`).
+- **Extra tools** — `LS` (list a directory), `MultiEdit` (several edits to one
+  file applied atomically), `TodoWrite` (session task checklist), `ApplyPatch`
+  (multi-file patch in Codex's V4A format: `*** Begin Patch` … `*** End Patch`).
+- **Git** — `GitStatus`, `GitDiff`, `GitLog`, `GitAdd`, `GitCommit`, `GitPush`.
+- **Web** — `WebFetch`, `WebSearch`.
+- **Service** — `respond` (final answer to the operator, ends the task).
+
+All file tools stay inside the working directory (sandbox). `Write`/`Edit` and
+`MultiEdit`/`ApplyPatch` make a backup (undo) before touching a file.
+
 ## Project context, skills and memory
 
 Like Codex / Claude Code, zames reads project instructions and reusable

package/dist/agent-loop.js

@@ -194,20 +194,20 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 attempt: afterToolRetries,
                 error: e.message,
             });
-            safeWarning('browser.ask() не вернул ответ за ' +
+            safeWarning('browser.ask() did not return an answer within ' +
                 Math.round(askDeadlineMs / 1000) +
-                'с — повторяю запрос.');
+                's — retrying the request.');
             if (afterToolRetries < MAX_AFTER_TOOL_RETRIES) {
                 afterToolRetries++;
                 await new Promise((r) => setTimeout(r, 1500));
                 continue;
             }
             transcript?.log('ask_timeout_exhausted', {
-                message: 'ask() не вернул ответ и лимит повторов исчерпан',
+                message: 'ask() did not return an answer and the retry limit is exhausted',
             });
-            safeWarning('browser.ask() перестал отвечать; лимит повторов исчерпан, ' +
-                'останавливаюсь. Ответа модели нет — проверьте чат DeepSeek вручную.');
-            return 'ask() watchdog: ответ модели не получен';
+            safeWarning('browser.ask() stopped responding; retry limit exhausted, ' +
+                'stopping. No model answer — check the DeepSeek chat manually.');
+            return 'ask() watchdog: no model answer received';
         }
         await reportChat();
         transcript?.log('assistant_raw', { response: rawResponse });
@@ -262,10 +262,10 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 response: String(rawResponse || '').slice(0, 200),
             });
             message =
-                'Ты остановился после результата инструмента. Продолжи работу: ' +
-                    'ответь РОВНО одним JSON-объектом вызова инструмента, без текста до и после, ' +
-                    'например: {"tool": "Bash", "args": {"command": "..."}}. ' +
-                    'Если задача действительно выполнена — вызови respond с итоговым сообщением.';
+                'You stopped after a tool result. Continue the work: ' +
+                    'reply with EXACTLY one JSON tool-call object, no text before or after, ' +
+                    'for example: {"tool": "Bash", "args": {"command": "..."}}. ' +
+                    'If the task is really done — call respond with the final message.';
             await new Promise((r) => setTimeout(r, 1500));
             continue;
         }
@@ -287,7 +287,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
         if (parsedCalls.some((p) => p && p._permissive)) {
             transcript?.log('permissive_parse', { response: rawResponse });
             if (debugLog) {
-                console.error('внимание: tool-call распознан нестрогим парсером');
+                console.error('warning: tool-call recognized by the permissive parser');
             }
         }
         if (!parsed) {
@@ -304,17 +304,17 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     response: rawResponse,
                 });
                 if (debugLog) {
-                    console.error('внимание: ответ похож на tool-call, но не распознан (попытка ' +
+                    console.error('warning: the answer looks like a tool-call but was not recognized (attempt ' +
                         malformedRetries +
                         '/' +
                         MAX_MALFORMED_RETRIES +
                         ')');
                 }
                 message =
-                    'Твой предыдущий ответ не распознан как вызов инструмента. ' +
-                        'Ответь РОВНО одним JSON-объектом вызова инструмента, без текста до и после. ' +
-                        'НЕ используй XML/DSML-теги — только JSON. ' +
-                        'Например: {"tool": "Read", "args": {"path": "src/index.js"}}';
+                    'Your previous answer was not recognized as a tool call. ' +
+                        'Reply with EXACTLY one JSON tool-call object, no text before or after. ' +
+                        'Do NOT use XML/DSML tags — plain JSON only. ' +
+                        'For example: {"tool": "Read", "args": {"path": "src/index.js"}}';
                 continue;
             }
             const trimmed = (rawResponse || '').trim();
@@ -336,16 +336,16 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     response: rawResponse,
                 });
                 if (debugLog) {
-                    console.error('внимание: пустой/служебный ответ, прошу продолжить (попытка ' +
+                    console.error('warning: empty/service answer, asking to continue (attempt ' +
                         stallRetries +
                         '/' +
                         MAX_STALL_RETRIES +
                         ')');
                 }
                 message =
-                    'Продолжи выполнение задачи. Если нужен инструмент — ответь РОВНО ' +
-                        'одним JSON-объектом вызова: {"tool": "...", "args": {...}}. ' +
-                        'Если задача выполнена — вызови инструмент respond с итоговым сообщением.';
+                    'Continue the task. If you need a tool — reply with EXACTLY ' +
+                        'one JSON tool-call object: {"tool": "...", "args": {...}}. ' +
+                        'If the task is done — call the respond tool with the final message.';
                 continue;
             }
             // The answer looks like "I'll call a tool now", but contains no call.
@@ -361,18 +361,18 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     response: rawResponse,
                 });
                 if (debugLog) {
-                    console.error('внимание: ответ похож на незавершённую работу, прошу продолжить (попытка ' +
+                    console.error('warning: the answer looks like unfinished work, asking to continue (attempt ' +
                         looksDoneRetries +
                         '/' +
                         MAX_LOOKSDONE_RETRIES +
                         ')');
                 }
                 message =
-                    'Похоже, ты собирался вызвать инструмент, но не вызвал. ' +
-                        'Если задача ещё не выполнена — ответь РОВНО одним JSON-объектом ' +
-                        'вызова инструмента, без текста до и после. ' +
-                        'Если задача действительно выполнена — вызови respond с итоговым ' +
-                        'сообщением оператору.';
+                    'It looks like you meant to call a tool but did not. ' +
+                        'If the task is not finished — reply with EXACTLY one JSON ' +
+                        'tool-call object, no text before or after. ' +
+                        'If the task is really done — call respond with the final ' +
+                        'message to the operator.';
                 continue;
             }
             // STRICT: only tool calls and respond reach the operator. Plain text is
@@ -387,12 +387,12 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 });
                 message =
                     (justRanTool
-                        ? 'Ты остановился после вызова инструмента и написал обычный текст. '
-                        : 'Ты написал обычный текст без вызова инструмента. ') +
-                        'Задача ещё не завершена. Ответь РОВНО одним JSON-объектом вызова ' +
-                        'инструмента, без текста до и после, например: ' +
+                        ? 'You stopped after a tool call and wrote plain text. '
+                        : 'You wrote plain text without a tool call. ') +
+                        'The task is not finished. Reply with EXACTLY one JSON tool-call ' +
+                        'object, no text before or after, for example: ' +
                         '{\"tool\": \"Bash\", \"args\": {\"command\": \"...\"}}. ' +
-                        'Если задача действительно выполнена — вызови respond с итоговым сообщением.';
+                        'If the task is really done — call respond with the final message.';
                 continue;
             }
             // Budget exhausted. Ask for respond EXACTLY once more; if the model
@@ -404,8 +404,8 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     response: rawResponse.slice(0, 500),
                 });
                 message =
-                    'Последний шаг: вызови инструмент respond с итоговым сообщением ' +
-                        'оператору. Не пиши обычный текст — только вызов respond, например: ' +
+                    'Last step: call the respond tool with the final message ' +
+                        'to the operator. Do not write plain text — only a respond call, for example: ' +
                         '{\"tool\": \"respond\", \"args\": {\"message\": \"...\"}}';
                 continue;
             }
@@ -450,16 +450,16 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 stallRetries++;
                 transcript?.log('empty_respond', { attempt: stallRetries });
                 if (debugLog) {
-                    console.error('внимание: пустой respond, прошу продолжить (попытка ' +
+                    console.error('warning: empty respond, asking to continue (attempt ' +
                         stallRetries +
                         '/' +
                         MAX_STALL_RETRIES +
                         ')');
                 }
                 message =
-                    'Ты вызвал respond с пустым message. Если задача выполнена — ' +
-                        'вызови respond с итоговым сообщением оператору. Если нет — ' +
-                        'продолжи работу вызовом инструмента.';
+                    'You called respond with an empty message. If the task is done — ' +
+                        'call respond with the final message to the operator. If not — ' +
+                        'continue the work with a tool call.';
                 continue;
             }
             // An EMPTY respond must NEVER be a silent final: the operator would see
@@ -469,9 +469,9 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             // the task normally.
             if (!isMeaningfulRespond(msg)) {
                 transcript?.log('empty_respond_exhausted', { response: rawResponse });
-                safeWarning('Модель вызвала respond без текста, и лимит повторов исчерпан. ' +
-                    'Проверьте чат DeepSeek вручную.');
-                return 'Модель не сформировала итоговое сообщение (пустой respond).';
+                safeWarning('The model called respond without text, and the retry limit is exhausted. ' +
+                    'Check the DeepSeek chat manually.');
+                return 'The model produced no final message (empty respond).';
             }
             safeAssistantMessage(msg);
             transcript?.log('assistant_final', { message: msg });
@@ -485,7 +485,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
         for (const call of callsToRun) {
             const tool = tools.find((t) => t.name === call.tool);
             if (!tool) {
-                const err = `Неизвестный инструмент: ${call.tool}`;
+                const err = `Unknown tool: ${call.tool}`;
                 safeToolResult(err);
                 transcript?.log('tool_error', { tool: call.tool, error: err });
                 results.push({ tool: call.tool, result: err });
@@ -498,7 +498,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 result = await tool.fn(call.args);
             }
             catch (e) {
-                result = `Ошибка: ${e.message}`;
+                result = `Error: ${e.message}`;
             }
             safeToolResult(result);
             transcript?.log('tool_result', {
@@ -536,7 +536,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 .join('\n\n');
         }
     }
-    return 'Достигнут лимит итераций.';
+    return 'Iteration limit reached.';
 }
 // The answer looks like a tool call, but parseToolCall() did not recognize it.
 // Used as a safeguard against "the agent called a tool and stopped": in that

package/dist/extraTools.js

@@ -0,0 +1,352 @@
+import fs from 'fs/promises';
+import path from 'path';
+// Extra tools that bring zames closer to Claude Code / Codex CLI:
+//   * LS         - list a directory (Claude Code has LS; Codex has list_dir)
+//   * MultiEdit  - several edits to ONE file applied atomically (Claude Code)
+//   * ApplyPatch - multi-file V4A-style patch (Codex apply_patch)
+//   * TodoWrite  - session task checklist (Claude Code TodoWrite)
+//
+// The core file tools (Read/Write/Edit/Bash/Glob/Grep) live in tools.ts.
+// These are additive: they do not change the existing tool behaviour.
+const NL = String.fromCharCode(10);
+function decodeContent(content, contentBase64) {
+    if (typeof contentBase64 === 'string' && contentBase64.length) {
+        return Buffer.from(contentBase64, 'base64').toString('utf-8');
+    }
+    return String(content ?? '');
+}
+// The todo list is per-process session state. It is deliberately NOT
+// persisted: a fresh run starts with an empty list, like Claude Code's
+// session checklist.
+const todoList = [];
+export function getTodos() {
+    return todoList.map((t) => ({ ...t }));
+}
+export function resetTodos() {
+    todoList.length = 0;
+}
+export function renderTodos(items) {
+    if (!items.length)
+        return 'Todo list is empty.';
+    const mark = (s) => s === 'completed' ? '[x]' : s === 'in_progress' ? '[~]' : '[ ]';
+    const lines = items.map((t, i) => `${i + 1}. ${mark(t.status)} ${t.content}`);
+    const done = items.filter((t) => t.status === 'completed').length;
+    return `Todo list (${done}/${items.length} done):${NL}${lines.join(NL)}`;
+}
+export function normalizeTodos(list) {
+    const items = [];
+    for (const raw of list) {
+        const it = (raw || {});
+        const content = String(it.content ?? it.text ?? '').trim();
+        if (!content)
+            continue;
+        const s = String(it.status ?? 'pending');
+        const status = s === 'completed' || s === 'done'
+            ? 'completed'
+            : s === 'in_progress' || s === 'active'
+                ? 'in_progress'
+                : 'pending';
+        items.push({ content, status });
+    }
+    return items;
+}
+/** Parse a V4A-style patch body into operations. Exported for tests. */
+export function parsePatch(text) {
+    const raw = String(text ?? '').replace(/\r\n/g, NL);
+    if (!/^\s*\*\*\*\s*Begin Patch/m.test(raw)) {
+        return { ops: [], error: 'Patch must start with "*** Begin Patch".' };
+    }
+    if (!/\*\*\*\s*End Patch/.test(raw)) {
+        return { ops: [], error: 'Patch must end with "*** End Patch".' };
+    }
+    const beginIdx = raw.indexOf('*** Begin Patch');
+    const endIdx = raw.lastIndexOf('*** End Patch');
+    const beginLineEnd = raw.indexOf(NL, beginIdx);
+    const body = raw.slice(beginLineEnd === -1 ? beginIdx : beginLineEnd + 1, endIdx);
+    const ops = [];
+    let current = null;
+    for (const line of body.split(NL)) {
+        const header = line.match(/^\*\*\*\s*(Add|Update|Delete) File:\s*(.+?)\s*$/);
+        if (header) {
+            const kind = header[1].toLowerCase();
+            const file = header[2].trim();
+            if (!file)
+                return { ops: [], error: 'Patch header has an empty path.' };
+            if (path.isAbsolute(file) || /(^|[\\/])\.\.([\\/]|$)/.test(file)) {
+                return { ops: [], error: 'Patch path must stay inside the project: ' + file };
+            }
+            current = { op: kind, file, lines: [] };
+            ops.push(current);
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+    }
+    if (!ops.length)
+        return { ops: [], error: 'Patch contains no file operations.' };
+    return { ops };
+}
+/**
+ * Apply an update hunk to existing content using context matching.
+ * The hunk is a list of lines prefixed with ' ' (context), '-' (remove),
+ * '+' (add). We locate the context block by exact match, then by ignoring
+ * trailing whitespace, then by ignoring all whitespace (like Codex).
+ */
+export function applyUpdateHunk(content, hunkLines) {
+    const hasCRLF = content.includes('\r\n');
+    const fileLines = content.split(/\r?\n/);
+    const oldLines = [];
+    const newLines = [];
+    for (const l of hunkLines) {
+        if (l.startsWith('@@'))
+            continue;
+        if (l.startsWith('+')) {
+            newLines.push(l.slice(1));
+        }
+        else if (l.startsWith('-')) {
+            oldLines.push(l.slice(1));
+        }
+        else if (l.startsWith(' ')) {
+            oldLines.push(l.slice(1));
+            newLines.push(l.slice(1));
+        }
+        else if (l === '') {
+            oldLines.push('');
+            newLines.push('');
+        }
+        else {
+            oldLines.push(l);
+            newLines.push(l);
+        }
+    }
+    if (!oldLines.length) {
+        return { ok: false, error: 'Hunk has no context or removed lines to anchor on.' };
+    }
+    const norm = (s, mode) => {
+        if (mode === 'exact')
+            return s;
+        if (mode === 'trim')
+            return s.replace(/[ \t]+$/, '');
+        return s.replace(/\s+/g, '');
+    };
+    for (const mode of ['exact', 'trim', 'ws']) {
+        const anchor = oldLines.map((l) => norm(l, mode));
+        for (let i = 0; i + anchor.length <= fileLines.length; i++) {
+            let match = true;
+            for (let j = 0; j < anchor.length; j++) {
+                if (norm(fileLines[i + j], mode) !== anchor[j]) {
+                    match = false;
+                    break;
+                }
+            }
+            if (!match)
+                continue;
+            const before = fileLines.slice(0, i);
+            const after = fileLines.slice(i + anchor.length);
+            const joined = [...before, ...newLines, ...after].join(hasCRLF ? '\r\n' : NL);
+            return { ok: true, content: joined };
+        }
+    }
+    return {
+        ok: false,
+        error: 'Context not found in the file (hunk did not match): ' +
+            oldLines[0].slice(0, 60),
+    };
+}
+// ---------- factory ----------
+export function createExtraTools(workdir, { undo } = {}) {
+    const root = path.resolve(workdir);
+    const safe = (p) => {
+        const resolved = path.resolve(root, p);
+        const rel = path.relative(root, resolved);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error('Access outside the working directory is forbidden: ' + p);
+        }
+        return resolved;
+    };
+    // Guard against missing/placeholder required args: a missing `path` becomes
+    // String(undefined) === "undefined" and would create a file literally named
+    // "undefined" in the working directory.
+    const req = (v, name) => {
+        if (v === undefined || v === null) {
+            throw new Error(`Missing required argument: ${name}`);
+        }
+        const s = String(v);
+        if (s === '' || s === 'undefined' || s === 'null') {
+            throw new Error(`Invalid required argument ${name}: ${JSON.stringify(v)}`);
+        }
+        return s;
+    };
+    return [
+        {
+            name: 'LS',
+            description: 'List the contents of a directory (files and subfolders). ' +
+                'path defaults to the working directory. Folders are marked with a slash.',
+            parameters: { path: 'string?', ignore: 'string?' },
+            fn: async ({ path: p, ignore }) => {
+                const target = p ? safe(req(p, 'path')) : root;
+                const stat = await fs.stat(target).catch(() => null);
+                if (!stat)
+                    throw new Error('No such directory: ' + p);
+                if (!stat.isDirectory())
+                    throw new Error('Not a directory: ' + p);
+                const ignoreList = (ignore ? String(ignore) : '')
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                const entries = await fs.readdir(target, { withFileTypes: true });
+                const rows = [];
+                for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (ignoreList.includes(e.name))
+                        continue;
+                    if (e.name === 'node_modules' || e.name === '.git') {
+                        rows.push(e.name + '/ (skipped)');
+                        continue;
+                    }
+                    if (e.isDirectory()) {
+                        rows.push(e.name + '/');
+                    }
+                    else {
+                        const full = path.join(target, e.name);
+                        const st = await fs.stat(full).catch(() => null);
+                        rows.push(e.name + (st ? `  (${st.size} bytes)` : ''));
+                    }
+                }
+                return rows.length ? rows.join(NL) : '(empty)';
+            },
+        },
+        {
+            name: 'MultiEdit',
+            description: 'Several targeted edits to ONE file in a single call. edits is an array of ' +
+                '{old_string, new_string, replace_all?}. Edits are applied ' +
+                'in order; if any is not found — none are applied. ' +
+                'For a single edit use Edit.',
+            parameters: {
+                path: 'string',
+                edits: 'array',
+                edits_base64: 'string?',
+            },
+            fn: async ({ path: p, edits, edits_base64 }) => {
+                const file = safe(req(p, 'path'));
+                let list;
+                if (typeof edits_base64 === 'string' && edits_base64.length) {
+                    list = JSON.parse(Buffer.from(edits_base64, 'base64').toString('utf-8'));
+                }
+                else if (Array.isArray(edits)) {
+                    list = edits;
+                }
+                else {
+                    throw new Error('edits must be an array of edits.');
+                }
+                if (!list.length)
+                    throw new Error('edits is empty — nothing to apply.');
+                let content = await fs.readFile(file, 'utf-8');
+                for (let i = 0; i < list.length; i++) {
+                    const e = list[i];
+                    const oldStr = String(e.old_string ?? '');
+                    const newStr = String(e.new_string ?? '');
+                    if (oldStr === '') {
+                        throw new Error(`edits[${i}]: old_string is empty.`);
+                    }
+                    const occurrences = content.split(oldStr).length - 1;
+                    if (occurrences === 0) {
+                        throw new Error(`edits[${i}]: string not found: "${oldStr.slice(0, 60)}..."`);
+                    }
+                    if (occurrences > 1 && !e.replace_all) {
+                        throw new Error(`edits[${i}]: string occurs ${occurrences} times. ` +
+                            'Make old_string more specific or pass replace_all=true.');
+                    }
+                    content = e.replace_all
+                        ? content.split(oldStr).join(newStr)
+                        : content.replace(oldStr, newStr);
+                }
+                if (undo)
+                    await undo.backup(file);
+                await fs.writeFile(file, content, 'utf-8');
+                return `Edited (${list.length} edits): ${p}`;
+            },
+        },
+        {
+            name: 'TodoWrite',
+            description: 'Create/update the session task list. Accepts todos — an array of ' +
+                '{content, status}, where status: pending | in_progress | completed. ' +
+                'Helps track multi-step tasks. Replaces the whole list.',
+            parameters: { todos: 'array', todos_base64: 'string?' },
+            fn: async ({ todos, todos_base64 }) => {
+                let list;
+                if (typeof todos_base64 === 'string' && todos_base64.length) {
+                    list = JSON.parse(Buffer.from(todos_base64, 'base64').toString('utf-8'));
+                }
+                else if (Array.isArray(todos)) {
+                    list = todos;
+                }
+                else {
+                    throw new Error('todos must be an array.');
+                }
+                const items = normalizeTodos(list);
+                todoList.length = 0;
+                todoList.push(...items);
+                return renderTodos(todoList);
+            },
+        },
+        {
+            name: 'ApplyPatch',
+            description: 'Apply a patch to several files in a single call (Codex format). ' +
+                'Body: "*** Begin Patch", operations "*** Add File: <path>" (lines with +), ' +
+                '"*** Update File: <path>" (context with a space, removals with -, additions ' +
+                'with +, @@ anchors optional), "*** Delete File: <path>", then ' +
+                '"*** End Patch". Paths must be relative and inside the project.',
+            parameters: { patch: 'string?', patch_base64: 'string?' },
+            fn: async ({ patch, patch_base64 }) => {
+                const text = decodeContent(patch, patch_base64);
+                const { ops, error } = parsePatch(text);
+                if (error)
+                    throw new Error(error);
+                // Stage every change first, then write.
+                const writes = [];
+                for (const op of ops) {
+                    const file = safe(op.file);
+                    if (op.op === 'delete') {
+                        writes.push({ file, content: null });
+                        continue;
+                    }
+                    if (op.op === 'add') {
+                        const body = op.lines
+                            .filter((l) => l.startsWith('+'))
+                            .map((l) => l.slice(1))
+                            .join(NL);
+                        writes.push({ file, content: body + NL });
+                        continue;
+                    }
+                    let current;
+                    try {
+                        current = await fs.readFile(file, 'utf-8');
+                    }
+                    catch {
+                        throw new Error('Update File: no such file ' + op.file);
+                    }
+                    const res = applyUpdateHunk(current, op.lines);
+                    if (!res.ok) {
+                        throw new Error('Update File ' + op.file + ': ' + res.error);
+                    }
+                    writes.push({ file, content: res.content });
+                }
+                const summary = [];
+                for (const w of writes) {
+                    if (undo)
+                        await undo.backup(w.file);
+                    if (w.content === null) {
+                        await fs.unlink(w.file).catch(() => { });
+                        summary.push('deleted ' + path.relative(root, w.file));
+                    }
+                    else {
+                        await fs.mkdir(path.dirname(w.file), { recursive: true });
+                        await fs.writeFile(w.file, w.content, 'utf-8');
+                        summary.push('written ' + path.relative(root, w.file));
+                    }
+                }
+                return 'Patch applied:' + NL + summary.join(NL);
+            },
+        },
+    ];
+}

package/dist/gitTools.js

@@ -18,16 +18,16 @@ export function runGit(cmd, cwd, timeout = 15_000) {
             const errStr = (stderr || '').toString();
             if (!err) {
                 const combined = (out + errStr).trim();
-                resolve(combined || '(команда выполнена, вывода нет)');
+                resolve(combined || '(command produced no output)');
                 return;
             }
             const parts = [];
             if (err.killed)
-                parts.push(`⏱ Таймаут ${timeout}ms`);
+                parts.push(`⏱ Timeout ${timeout}ms`);
             else if (err.code !== undefined && err.code !== null)
                 parts.push(`Exit code: ${err.code}`);
             else
-                parts.push(`Ошибка: ${err.message}`);
+                parts.push(`Error: ${err.message}`);
             if (out.trim())
                 parts.push(out.trim());
             if (errStr.trim())
@@ -114,7 +114,7 @@ export function createGitTools(workdir) {
     return [
         {
             name: 'GitStatus',
-            description: 'Показать git status рабочей директории. Возвращает ошибку, если это не git-репозиторий.',
+            description: 'Show the git status of the working directory. Returns an error if this is not a git repository.',
             parameters: {},
             fn: async () => {
                 const err = await ensureRepo();
@@ -125,7 +125,7 @@ export function createGitTools(workdir) {
         },
         {
             name: 'GitDiff',
-            description: 'Показать git diff. По умолчанию незастейдженные изменения. Можно ограничить path и указать staged=true.',
+            description: 'Show git diff. By default unstaged changes. Can be limited with path and staged=true.',
             parameters: { path: 'string?', staged: 'boolean?' },
             fn: async ({ path: p, staged }) => {
                 const err = await ensureRepo();
@@ -141,7 +141,7 @@ export function createGitTools(workdir) {
         },
         {
             name: 'GitLog',
-            description: 'Показать последние N коммитов (по умолчанию 10).',
+            description: 'Show the last N commits (default 10).',
             parameters: { count: 'number?' },
             fn: async ({ count }) => {
                 const err = await ensureRepo();
@@ -152,7 +152,7 @@ export function createGitTools(workdir) {
         },
         {
             name: 'GitAdd',
-            description: 'Добавить файлы в индекс. Если paths не задан — git add -A (всё).',
+            description: 'Stage files. If paths is not given — git add -A (everything).',
             parameters: { paths: 'string?' },
             fn: async ({ paths }) => {
                 const err = await ensureRepo();
@@ -165,7 +165,7 @@ export function createGitTools(workdir) {
         },
         {
             name: 'GitCommit',
-            description: 'Закоммитить застейдженное (если ничего не застейджено — сначала git add -A). Не пушит.',
+            description: 'Commit staged changes (if nothing is staged — git add -A first). Does not push.',
             parameters: { message: 'string' },
             fn: async ({ message }) => {
                 const err = await ensureRepo();
@@ -173,14 +173,14 @@ export function createGitTools(workdir) {
                     return err;
                 const msg = String(message || '');
                 if (!msg.trim()) {
-                    return 'Ошибка: message пустой.';
+                    return 'Error: message is empty.';
                 }
                 // We stage everything only if the index is empty (as the description promises).
                 const staged = await runGit('git diff --cached --name-only', workdir, 10_000);
                 const hasStaged = !/^\s*/.test(staged) &&
-                    staged.trim() !== '(команда выполнена, вывода нет)';
+                    staged.trim() !== '(command produced no output)';
                 const addResult = hasStaged
-                    ? '(индекс уже не пуст — add -A пропущен)'
+                    ? '(index is not empty — add -A skipped)'
                     : await runGit('git add -A', workdir, 20_000);
                 const fs = await import('fs/promises');
                 const path = await import('path');
@@ -198,7 +198,7 @@ export function createGitTools(workdir) {
         },
         {
             name: 'GitPush',
-            description: 'Запушить ветку в origin. Требует настроенных креденшелов (SSH или Windows Credential Manager).',
+            description: 'Push a branch to origin. Requires configured credentials (SSH or Windows Credential Manager).',
             parameters: { branch: 'string?', setUpstream: 'boolean?' },
             fn: async ({ branch, setUpstream }) => {
                 const err = await ensureRepo();
@@ -208,7 +208,7 @@ export function createGitTools(workdir) {
                     ? String(branch).trim()
                     : (await runGit('git branch --show-current', workdir, 5000)).trim();
                 if (!b)
-                    return 'Ошибка: не удалось определить ветку для push.';
+                    return 'Error: could not determine the branch to push.';
                 const flag = setUpstream ? '-u ' : '';
                 const target = quoteArgs(b);
                 return runGit(`git push ${flag}origin ${target}`, workdir, 120_000);

package/dist/index.js

@@ -93,6 +93,7 @@ const SRC_EXT = /[.]ts$/.test(new URL(import.meta.url).pathname) ? '.ts' : '.js'
 const RELOADABLE = [
     'mcp',
     'tools',
+    'extraTools',
     'agent-loop',
     'system-prompt',
     'gitTools',
@@ -825,7 +826,7 @@ async function runTask(browser, tools, taskText, workdir, opts, attachments = []
             // case no assistant message was shown, and the operator saw the run
             // just "stop" after a tool call with no explanation. Surface it.
             if (outcome &&
-                (outcome.startsWith('Достигнут лимит итераций') ||
+                (outcome.startsWith('Iteration limit reached') ||
                     outcome.startsWith('ask() watchdog'))) {
                 ui.warning(outcome);
                 transcript?.log('agent_no_answer', { outcome });

package/dist/system-prompt.js

@@ -50,7 +50,7 @@ export function renderContextSection(context) {
 export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, }) {
     const t = translate(locale);
     const toolDescriptions = tools
-        .map((t2) => `### ${t2.name}\n${t2.description}\nПараметры: ${JSON.stringify(t2.parameters)}`)
+        .map((t2) => `### ${t2.name}\n${t2.description}\nParameters: ${JSON.stringify(t2.parameters)}`)
         .join('\n\n');
     const gitSection = gitContext
         ? `\n## Git context\n\n${gitContext}\n`

package/dist/tools.js

@@ -3,6 +3,11 @@ import path from 'path';
 import { exec } from 'child_process';
 import { createGitTools } from './gitTools.js';
 import { createWebTools } from './web.js';
+import { createExtraTools } from './extraTools.js';
+// NOTE: tool descriptions and tool-result strings are AGENT-FACING, not
+// user-facing. They must be in ENGLISH (like Claude Code / Codex). Only the
+// strings the OPERATOR sees (help, spinner, service messages) are localized —
+// those live in src/i18n.ts (CATALOG) and are picked by the locale setting.
 export function createTools(workdir, { undo } = {}) {
     const root = path.resolve(workdir);
     const safe = (p) => {
@@ -11,7 +16,7 @@ export function createTools(workdir, { undo } = {}) {
         // (C:\work\proj vs C:\work\proj-old). We compute via relative().
         const rel = path.relative(root, resolved);
         if (rel.startsWith('..') || path.isAbsolute(rel)) {
-            throw new Error(`Доступ за пределы рабочей директории: ${p}`);
+            throw new Error(`Access outside the working directory is forbidden: ${p}`);
         }
         return resolved;
     };
@@ -28,7 +33,7 @@ export function createTools(workdir, { undo } = {}) {
             const target = path.resolve(root, raw);
             const rel = path.relative(root, target);
             if (rel.startsWith('..') || path.isAbsolute(rel)) {
-                throw new Error('Sandbox: выход за пределы ' + root + ' запрещён (cd ' + raw + ')');
+                throw new Error('Sandbox: leaving ' + root + ' is forbidden (cd ' + raw + ')');
             }
         }
     };
@@ -51,21 +56,21 @@ export function createTools(workdir, { undo } = {}) {
             const errStr = (stderr || '').toString();
             if (!err) {
                 const combined = (out + errStr).trim();
-                resolve(combined || '(команда выполнена без вывода)');
+                resolve(combined || '(command produced no output)');
                 return;
             }
             const parts = [];
             if (err.killed) {
-                parts.push(`⏱ Таймаут после ${timeout}ms — процесс убит.`);
+                parts.push(`⏱ Timeout after ${timeout}ms — process killed.`);
             }
             else if (err.code !== undefined && err.code !== null) {
                 parts.push(`Exit code: ${err.code}`);
             }
             else if (err.signal) {
-                parts.push(`Убит сигналом: ${err.signal}`);
+                parts.push(`Killed by signal: ${err.signal}`);
             }
             else {
-                parts.push(`Ошибка: ${err.message}`);
+                parts.push(`Error: ${err.message}`);
             }
             if (out.trim())
                 parts.push(`stdout:\n${out.trim()}`);
@@ -84,45 +89,76 @@ export function createTools(workdir, { undo } = {}) {
         }
         return String(content ?? '');
     };
+    // Guard against missing/placeholder required args. Without this, a tool call
+    // that omits `path` (or sends it as null) becomes String(undefined) ===
+    // "undefined" and the tool silently creates a file literally named
+    // "undefined" in the working directory. `req()` rejects that up front.
+    const req = (v, name) => {
+        if (v === undefined || v === null) {
+            throw new Error(`Missing required argument: ${name}`);
+        }
+        const s = String(v);
+        if (s === '' || s === 'undefined' || s === 'null') {
+            throw new Error(`Invalid required argument ${name}: ${JSON.stringify(v)}`);
+        }
+        return s;
+    };
     const baseTools = [
         {
             name: 'Read',
-            description: 'Прочитать содержимое файла. Опционально: offset и limit (строки).',
-            parameters: { path: 'string', offset: 'number?', limit: 'number?' },
-            fn: async ({ path: p, offset, limit }) => {
-                const file = safe(String(p));
+            description: 'Read a file. Optional: offset and limit (lines). ' +
+                'numbered=true adds cat -n style line numbers (1-based) for reference ' +
+                'only — do NOT copy the numbers into Edit old_string. ' +
+                'Lines longer than 2000 chars are truncated.',
+            parameters: {
+                path: 'string',
+                offset: 'number?',
+                limit: 'number?',
+                numbered: 'boolean?',
+            },
+            fn: async ({ path: p, offset, limit, numbered }) => {
+                const file = safe(req(p, 'path'));
                 const content = await fs.readFile(file, 'utf-8');
+                if (content === '')
+                    return '(file is empty)';
                 const lines = content.split('\n');
                 const start = offset ?? 0;
                 const end = limit ? start + limit : lines.length;
-                return lines.slice(start, end).join('\n');
+                const slice = lines.slice(start, end);
+                const clip = (l) => l.length > 2000 ? l.slice(0, 2000) + ' …[line truncated]' : l;
+                if (!numbered)
+                    return slice.map(clip).join('\n');
+                const width = String(start + slice.length).length;
+                return slice
+                    .map((l, i) => String(start + i + 1).padStart(width) + '\t' + clip(l))
+                    .join('\n');
             },
         },
         {
             name: 'Write',
-            description: 'Создать или перезаписать файл. content — текст; content_base64 — тот же ' +
-                'контент в base64 (используй, если текст содержит , обратные слэши, ' +
-                'переводы строк или другие символы, которые могут исказиться).',
+            description: 'Create or overwrite a file. content — text; content_base64 — the same ' +
+                'content base64-encoded (use it if the text contains $, backslashes, ' +
+                'newlines or other characters that may get corrupted in transit).',
             parameters: {
                 path: 'string',
                 content: 'string?',
                 content_base64: 'string?',
             },
             fn: async ({ path: p, content, content_base64 }) => {
-                const file = safe(String(p));
+                const file = safe(req(p, 'path'));
                 const text = decodeContent(content, content_base64);
                 if (undo)
                     await undo.backup(file);
                 await fs.mkdir(path.dirname(file), { recursive: true });
                 await fs.writeFile(file, text, 'utf-8');
-                return `Файл записан: ${p}`;
+                return `File written: ${p}`;
             },
         },
         {
             name: 'Edit',
-            description: 'Точечная замена строки в файле. old_string должен встречаться один раз. ' +
-                'old_base64/new_base64 — те же строки в base64 (если текст содержит ' +
-                'спецсимволы, которые могут исказиться).',
+            description: 'Replace a string in a file. old_string must occur exactly once. ' +
+                'old_base64/new_base64 — the same strings base64-encoded (if the text ' +
+                'contains special characters that may get corrupted).',
             parameters: {
                 path: 'string',
                 old_string: 'string?',
@@ -131,81 +167,99 @@ export function createTools(workdir, { undo } = {}) {
                 new_base64: 'string?',
             },
             fn: async ({ path: p, old_string, new_string, old_base64, new_base64 }) => {
-                const file = safe(String(p));
+                const file = safe(req(p, 'path'));
                 const oldStr = decodeContent(old_string, old_base64);
                 const newStr = decodeContent(new_string, new_base64);
                 if (oldStr === '') {
-                    throw new Error('old_string пустой — нечего заменять.');
+                    throw new Error('old_string is empty — nothing to replace.');
                 }
                 let content = await fs.readFile(file, 'utf-8');
                 const occurrences = content.split(oldStr).length - 1;
                 if (occurrences === 0) {
-                    throw new Error(`Строка не найдена в ${p}: "${oldStr.slice(0, 60)}..."`);
+                    throw new Error(`String not found in ${p}: "${oldStr.slice(0, 60)}..."`);
                 }
                 if (occurrences > 1) {
-                    throw new Error(`Строка встречается ${occurrences} раз в ${p}. Уточните old_string.`);
+                    throw new Error(`String occurs ${occurrences} times in ${p}. Make old_string more specific.`);
                 }
                 if (undo)
                     await undo.backup(file);
                 content = content.replace(oldStr, newStr);
                 await fs.writeFile(file, content, 'utf-8');
-                return `Отредактирован: ${p}`;
+                return `Edited: ${p}`;
             },
         },
         {
             name: 'Bash',
-            description: 'Выполнить shell-команду в рабочей директории (cmd.exe на Windows, sh на Linux/macOS). ' +
-                'Не использовать для long-running процессов (серверы) — уйдут в таймаут. ' +
-                'Не использовать для команд, требующих интерактивного ввода. ' +
-                'Для git — инструменты Git*. Для интернета — WebFetch / WebSearch.',
+            description: 'Run a shell command in the working directory (cmd.exe on Windows, sh on Linux/macOS). ' +
+                'Do not use for long-running processes (servers) — they will hit the timeout. ' +
+                'Do not use for commands that require interactive input. ' +
+                'For git use the Git* tools. For the web use WebFetch / WebSearch.',
             parameters: { command: 'string', timeout: 'number?' },
             fn: async ({ command, timeout }) => {
-                assertCommandInsideRoot(String(command));
-                return runShell(String(command), timeout);
+                assertCommandInsideRoot(req(command, 'command'));
+                return runShell(req(command, 'command'), timeout);
             },
         },
         {
             name: 'Glob',
-            description: 'Найти файлы по glob-паттерну (например, "**/*.js").',
-            parameters: { pattern: 'string' },
-            fn: async ({ pattern }) => {
+            description: 'Find files by glob pattern (e.g. "**/*.js"). ' +
+                'path (optional) — search directory inside the project.',
+            parameters: { pattern: 'string', path: 'string?' },
+            fn: async ({ pattern, path: searchPath }) => {
                 const { glob } = await import('fs/promises');
+                const cwd = searchPath ? safe(String(searchPath)) : workdir;
                 const results = [];
-                for await (const f of glob(String(pattern), { cwd: workdir })) {
+                for await (const f of glob(req(pattern, 'pattern'), { cwd })) {
                     // Sandbox: ignore anything that goes outside root.
-                    const abs = path.resolve(workdir, f);
+                    const abs = path.resolve(cwd, f);
                     const rel = path.relative(root, abs);
                     if (rel.startsWith('..') || path.isAbsolute(rel))
                         continue;
                     results.push(f);
                 }
-                return results.length ? results.join('\n') : 'Ничего не найдено.';
+                return results.length ? results.join('\n') : 'No matches found.';
             },
         },
         {
             name: 'Grep',
-            description: 'Поиск по содержимому файлов (регулярное выражение).',
-            parameters: { pattern: 'string', path: 'string?' },
-            fn: async ({ pattern, path: searchPath }) => {
+            description: 'Search file contents (regular expression). include — file name ' +
+                'filter (e.g. "*.ts"). output: content (default, matching lines with ' +
+                'numbers), files_only (paths only), count (match count per file).',
+            parameters: {
+                pattern: 'string',
+                path: 'string?',
+                include: 'string?',
+                output: 'string?',
+            },
+            fn: async ({ pattern, path: searchPath, include, output }) => {
+                const pat = req(pattern, 'pattern');
                 const target = searchPath ? safe(String(searchPath)) : workdir;
+                const inc = include ? String(include).trim() : '';
+                const mode = String(output || 'content').toLowerCase();
                 if (process.platform === 'win32') {
-                    const escaped = String(pattern).replace(/"/g, '\\"');
-                    const scope = searchPath
-                        ? '"' + target + '\\*'
-                        : '*';
+                    const escaped = pat.replace(/"/g, '\\"');
+                    const scope = searchPath ? '"' + target + '\\*' : '*';
                     return runShell(`findstr /s /n /r /c:"${escaped}" ` + scope);
                 }
-                return runShell(`grep -rn -E ${JSON.stringify(pattern)} ${JSON.stringify(target)} || true`);
+                const flags = mode === 'files_only'
+                    ? '-rlE'
+                    : mode === 'count'
+                        ? '-rcE'
+                        : '-rnE';
+                const includeArg = inc ? ' --include=' + JSON.stringify(inc) : '';
+                return runShell(`grep ${flags}${includeArg} ${JSON.stringify(pat)} ` +
+                    `${JSON.stringify(target)} || true`);
             },
         },
     ];
     const gitTools = createGitTools(workdir);
     const webTools = createWebTools();
+    const extraTools = createExtraTools(workdir, { undo });
     const respondTool = {
         name: 'respond',
-        description: 'Дать финальный ответ пользователю и завершить задачу.',
+        description: 'Give the final answer to the user and finish the task.',
         parameters: { message: 'string' },
         fn: async ({ message }) => message,
     };
-    return [...baseTools, ...gitTools, ...webTools, respondTool];
+    return [...baseTools, ...extraTools, ...gitTools, ...webTools, respondTool];
 }

package/dist/web.js

@@ -112,9 +112,9 @@ export function createWebTools() {
     return [
         {
             name: 'WebFetch',
-            description: 'Загрузить URL и вернуть очищенный текст страницы (без HTML-тегов). ' +
-                'Используй для чтения документации, статей, README на GitHub. ' +
-                'Если страница рендерится JavaScript-ом и текст пустой — попробуй ещё раз с render=true.',
+            description: 'Fetch a URL and return the cleaned text of the page (without HTML tags). ' +
+                'Use it to read docs, articles, READMEs on GitHub. ' +
+                'If the page is rendered by JavaScript and the text is empty — retry with render=true.',
             parameters: {
                 url: 'string',
                 render: 'boolean?',
@@ -122,7 +122,7 @@ export function createWebTools() {
             },
             fn: async ({ url, render, maxChars }) => {
                 if (!/^https?:\/\//i.test(String(url))) {
-                    return `Ошибка: URL должен начинаться с http:// или https://`;
+                    return `Error: URL must start with http:// or https://`;
                 }
                 const limit = Math.min(Number(maxChars) || MAX_TEXT, 60_000);
                 try {
@@ -143,21 +143,21 @@ export function createWebTools() {
                     if (text.length < 200) {
                         return (`HTTP ${r.status}  ${r.url}\n` +
                             `Content-Type: ${r.contentType}\n\n` +
-                            `Страница почти пустая в сыром HTML (${text.length} символов). ` +
-                            `Похоже, контент рендерится JavaScript-ом. ` +
-                            `Повтори вызов с render=true.\n\n---\n${text}`);
+                            `The page is almost empty in raw HTML (${text.length} chars). ` +
+                            `It looks like the content is rendered by JavaScript. ` +
+                            `Retry with render=true.\n\n---\n${text}`);
                     }
                     return formatResult(r.status, r.url, text, limit);
                 }
                 catch (e) {
-                    return `Ошибка загрузки ${url}: ${e.message}`;
+                    return `Error fetching ${url}: ${e.message}`;
                 }
             },
         },
         {
             name: 'WebSearch',
-            description: 'Поиск в интернете через DuckDuckGo HTML (без API-ключа). ' +
-                'Возвращает список результатов: заголовок, URL, краткое описание.',
+            description: 'Search the web via DuckDuckGo HTML (no API key). ' +
+                'Returns a list of results: title, URL, short description.',
             parameters: {
                 query: 'string',
                 maxResults: 'number?',
@@ -165,7 +165,7 @@ export function createWebTools() {
             fn: async ({ query, maxResults }) => {
                 const q = encodeURIComponent(String(query || ''));
                 if (!q)
-                    return 'Ошибка: query пустой.';
+                    return 'Error: query is empty.';
                 const limit = Math.min(Math.max(Number(maxResults) || 8, 1), 20);
                 try {
                     const r = await httpFetch(`https://html.duckduckgo.com/html/?q=${q}`, {
@@ -175,7 +175,7 @@ export function createWebTools() {
                         },
                     });
                     if (r.status !== 200) {
-                        return `DuckDuckGo вернул HTTP ${r.status}`;
+                        return `DuckDuckGo returned HTTP ${r.status}`;
                     }
                     // We parse with simple regexes. The html.duckduckgo.com format is stable.
                     const results = [];
@@ -194,14 +194,14 @@ export function createWebTools() {
                         results.push({ title, url: href, snippet });
                     }
                     if (!results.length) {
-                        return `Результатов не найдено. Возможно, изменился формат выдачи DuckDuckGo.`;
+                        return `No results found. The DuckDuckGo output format may have changed.`;
                     }
                     const lines = results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}` +
                         (r.snippet ? `\n   ${r.snippet}` : ''));
                     return lines.join('\n\n');
                 }
                 catch (e) {
-                    return `Ошибка поиска: ${e.message}`;
+                    return `Search error: ${e.message}`;
                 }
             },
         },
@@ -215,5 +215,5 @@ function formatResult(status, url, text, limit) {
         truncated = true;
     }
     return (`HTTP ${status}  ${url}\n\n${out}` +
-        (truncated ? `\n\n[...обрезано на ${limit} символах]` : ''));
+        (truncated ? `\n\n[...truncated at ${limit} chars]` : ''));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Terminal coding agent over chat.deepseek.com via Playwright",
   "type": "module",
   "bin": {