zames_pro 2.12.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
@@ -106,6 +123,42 @@ Skills and custom commands show up in the «/» completion list and in `/help`.
 /init [--force]               analyze the project and create AGENTS.md
 ```
 
+## MCP (external tools)
+
+zames can use tools from [MCP](https://modelcontextprotocol.io) servers.
+The flagship example is @playwright/mcp: it gives the agent a real browser
+(navigate, click, snapshot, type, ...) on top of the one zames already uses
+for the DeepSeek chat.
+
+Drop a config file (same shape as Claude Code / Cursor):
+
+- `~/.zames/mcp.json` - global
+- `<project>/.zames/mcp.json` - project-scoped (later files win)
+- `<project>/.mcp.json` - the common MCP name
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
+    }
+  }
+}
+```
+
+IMPORTANT: keep the MCP browser isolated. @playwright/mcp defaults to the
+SAME profile directory as zames (~/.zames/profile). If it is launched
+without --isolated (or without its own --user-data-dir), the MCP browser
+and the agent browser fight over one profile and the DeepSeek chat shows
+"Something went wrong when opening your profile". Always pass --isolated
+as in the example above.
+Servers can also be remote ("url": "https://...", "transport": "sse").
+Their tools show up in the agent as `server__tool` (e.g.
+`playwright__browser_navigate`) and are listed with `/mcp` and in `/status`.
+A server that fails to connect is skipped with a warning and never breaks the
+agent.
+
 ## Configuration
 
 Global config: `~/.zames/config.json`

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);
+            },
+        },
+    ];
+}