zames_pro 2.6.0 → 2.7.0

package/dist/agent-loop.js

@@ -1,12 +1,13 @@
 import { buildSystemPrompt } from './system-prompt.js';
 import { getGitContext, formatGitContext } from './gitTools.js';
 import { parseXmlToolCalls } from './xml-toolcall.js';
-export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 40, freshChat = false, sendSystemPrompt = false, transcript = null, onThinking = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, debugLog = false, locale = 'ru', }) {
+import { translate } from './i18n.js';
+export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 40, freshChat = false, sendSystemPrompt = false, transcript = null, onThinking = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, onWarning = () => { }, debugLog = false, locale = 'ru', }) {
     if (freshChat) {
         await browser.newChat();
         transcript?.log('new_chat');
     }
-    // Сообщаем вызывающему актуальный chat id.
+    // Report the current chat id to the caller.
     let lastReportedChatId = null;
     const reportChat = async () => {
         let id = null;
@@ -42,7 +43,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             gitContext: gitText,
         });
         onThinking();
-        // system-prompt — отправка агента: с паузой (agent: true).
+        // system-prompt is an agent send: throttled (agent: true).
         await browser.ask(systemPrompt, { timeout: 60_000, agent: true });
         await reportChat();
     }
@@ -52,23 +53,24 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
     const MAX_MALFORMED_RETRIES = 3;
     let stallRetries = 0;
     const MAX_STALL_RETRIES = 5;
-    // Защита от «агент встал»: DeepSeek иногда присылает финальный текст,
-    // который лишь ОПИСЫВАЕТ следующий вызов инструмента (или рвёт ответ на
-    // полуслове), и агент молча завершает задачу, хотя работа не сделана.
-    // Если финальный ответ похож на «сейчас вызову …» — переспрашиваем, а не
-    // останавливаемся. Счётчик общий, чтобы не зациклиться на болтливой модели.
+    // Guard against "the agent stalled": DeepSeek sometimes sends a final text
+    // that merely DESCRIBES the next tool call (or cuts the answer off
+    // mid-word), and the agent silently finishes the task even though the work
+    // is not done. If the final answer looks like "I'll call ... now" — we
+    // re-ask instead of stopping. The counter is shared so we don't loop on a
+    // chatty model.
     let looksDoneRetries = 0;
     const MAX_LOOKSDONE_RETRIES = 3;
     for (let i = 0; i < maxIterations; i++) {
         onThinking();
-        // Первое сообщение (task) — пользовательский ввод: без паузы.
-        // Последующие (tool-result и просьбы переотправить) — агентские:
-        // с паузой, чтобы не упираться в лимит частоты.
+        // The first message (task) is user input: no throttle.
+        // Subsequent ones (tool-result and resend requests) are agent sends:
+        // throttled so we don't hit the rate limit.
         const isFirst = i === 0;
         const rawResponse = await browser.ask(message, { agent: !isFirst });
         await reportChat();
         transcript?.log('assistant_raw', { response: rawResponse });
-        // Пользователь прервал генерацию (Esc/Ctrl+C).
+        // The user aborted generation (Esc/Ctrl+C).
         if (/^\s*\(прервано пользователем\)\s*$/.test(rawResponse)) {
             transcript?.log('user_aborted');
             return rawResponse;
@@ -87,10 +89,10 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             }
         }
         if (!parsed) {
-            // Ответ похож на (возможно, обрезанный) вызов инструмента. Ловим не
-            // только явный JSON, но и XML/DSML-формы, «грязные» варианты и
-            // незакрытые фрагменты: если такой ответ молча принять за финальный,
-            // агент встанет, хотя модель пыталась позвать инструмент.
+            // The answer looks like a (possibly truncated) tool call. We catch not
+            // only explicit JSON but also XML/DSML forms, "dirty" variants and
+            // unclosed fragments: if such an answer is silently taken as final, the
+            // agent stalls even though the model tried to call a tool.
             const looksLikeToolCall = responseLooksLikeToolCall(rawResponse);
             if (looksLikeToolCall && malformedRetries < MAX_MALFORMED_RETRIES) {
                 malformedRetries++;
@@ -113,11 +115,11 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 continue;
             }
             const trimmed = (rawResponse || '').trim();
-            // Служебный ответ — это КОРОТКАЯ заглушка DeepSeek («Reading…») или
-            // короткое уведомление о лимите. Слова про rate limit в ДЛИННОМ
-            // ответе — это, как правило, сам агент цитирует код/логи (в транскрипте
-            // был ровно такой случай: ответ на 1365 символов про ask() и лимиты),
-            // и принимать его за «служебный» нельзя, иначе агент зря переспрашивает.
+            // A service answer is a SHORT DeepSeek placeholder ("Reading…") or a
+            // short rate-limit notice. Words about the rate limit in a LONG answer
+            // are usually the agent itself quoting code/logs (the transcript had
+            // exactly such a case: a 1365-char answer about ask() and limits), and
+            // it must not be taken as "service", otherwise the agent re-asks in vain.
             const looksService = !trimmed ||
                 trimmed.length < 2 ||
                 /^(reading|thinking|searching|analyzing|generating|stop|остановить|читаю|думаю|поиск|анализ)[\s.…]*$/i.test(trimmed) ||
@@ -142,11 +144,11 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                         'Если задача выполнена — вызови инструмент respond с итоговым сообщением.';
                 continue;
             }
-            // Ответ похож на «сейчас вызову инструмент», но вызова в нём нет.
-            // DeepSeek иногда так обрывает ход: пишет «Now update README…» или
-            // «Let me run the tests…» и замолкает. Если принять это за финал,
-            // агент встаёт, не сделав работу. Просим продолжить и на этот раз
-            // обязательно вызвать инструмент (или respond, если правда готово).
+            // The answer looks like "I'll call a tool now", but contains no call.
+            // DeepSeek sometimes cuts the turn like this: writes "Now update
+            // README…" or "Let me run the tests…" and goes silent. If this is taken
+            // as final, the agent stalls without doing the work. We ask it to
+            // continue and to actually call a tool this time (or respond if truly done).
             if (looksLikeUnfinishedWork(trimmed) && looksDoneRetries < MAX_LOOKSDONE_RETRIES) {
                 looksDoneRetries++;
                 transcript?.log('unfinished_retry', {
@@ -168,6 +170,14 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                         'сообщением оператору.';
                 continue;
             }
+            // All re-ask attempts are exhausted, yet the answer still looks like a
+            // tool call. Most likely this is a silent stall: we show the operator a
+            // warning in the terminal (not only in the transcript) so they see the
+            // problem immediately instead of wondering why the agent stalled.
+            if (responseLooksLikeToolCall(rawResponse)) {
+                transcript?.log('suspicious_final', { response: rawResponse });
+                onWarning(translate(locale)('msg.suspicious_stop'));
+            }
             onAssistantMessage(rawResponse);
             transcript?.log('assistant_final', { message: rawResponse });
             return rawResponse;
@@ -178,9 +188,9 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             const msg = typeof respondCall.args.message === 'string'
                 ? respondCall.args.message
                 : String(respondCall.args.message ?? '');
-            // Пустой respond — не финал: модель позвала respond, но не написала
-            // итог. Если так завершить, оператор не увидит ничего, а задача
-            // «зависнет». Просим продолжить (в пределах stallRetries).
+            // An empty respond is not final: the model called respond but wrote no
+            // summary. Finishing like this would show the operator nothing and the
+            // task would "hang". We ask it to continue (within stallRetries).
             if (!msg.trim() && stallRetries < MAX_STALL_RETRIES) {
                 stallRetries++;
                 transcript?.log('empty_respond', { attempt: stallRetries });
@@ -243,45 +253,45 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
     }
     return 'Достигнут лимит итераций.';
 }
-// Ответ похож на вызов инструмента, но parseToolCall() его не распознал.
-// Используется как страховка от «агент вызвал инструмент и остановился»:
-// в этом случае runAgentLoop просит модель переотправить вызов, а не
-// завершает задачу. Ловим и явные форматы, и «поломанные» головы вызова
-// (`<｜tool": ...`, `**tool**:`, `tool": ...`), и обрезанные вызовы.
+// 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
+// case runAgentLoop asks the model to resend the call instead of finishing the
+// task. We catch both explicit formats and "broken" call heads
+// (`<｜tool": ...`, `**tool**:`, `tool": ...`), and truncated calls.
 export function responseLooksLikeToolCall(rawResponse) {
     const raw = rawResponse || '';
     return (
-    // Явные маркеры форматов tool-call: JSON-ключ "tool", XML/DSML-теги,
-    // function_call и т.п.
+    // Explicit tool-call format markers: the JSON key "tool", XML/DSML tags,
+    // function_call, etc.
     /("tool"\s*:|\btool_calls?\b|\binvoke\b|\bparameter\b|DSML|function_call)/i.test(raw) ||
-        // «tool» без открывающей кавычки/скобки, с мусорным префиксом
-        // (`<｜tool":`, `**tool**:`, `- tool:`): ключ вызова, а не проза.
+        // "tool" without an opening quote/bracket, with a junk prefix
+        // (`<｜tool":`, `**tool**:`, `- tool:`): a call key, not prose.
         /(^|[^A-Za-z0-9_])(?:\*\*)?tool(?:\*\*)?["'`\u2018\u2019\u201c\u201d]*\s*:/.test(raw) ||
-        // Ключи в одинарных кавычках или без кавычек: {'tool': 'Read', ...}.
+        // Keys in single quotes or unquoted: {'tool': 'Read', ...}.
         /[\{\[]\s*['"]?(tool|name|args)['"]?\s*:/.test(raw) ||
-        // Обрезанный вызов: начинается как JSON-объект, но не закрыт, и в нём
-        // есть ключ аргумента (args/command/path/...). Требуем именно открывающую
-        // скобку в начале (после пробелов/префикса), чтобы не ловить обычную
-        // прозу с двоеточиями вроде «path: ...».
+        // Truncated call: starts like a JSON object but is not closed, and has an
+        // argument key (args/command/path/...). We require the opening bracket at
+        // the start (after spaces/prefix) so we don't catch ordinary prose with
+        // colons like "path: ...".
         /^\s*[\[\{]/.test(raw) &&
             /["']?(?:tool|args|command|path|old_string|content|content_base64)["']?\s*:/.test(raw) ||
         /<\s*\|?\s*(DSML|invoke|parameter)/i.test(raw) ||
         /^\s*\[?\s*\{[^}]*$/.test(raw.trim()));
 }
-// Текст, который обещает вызов инструмента в будущем времени, но самого
-// вызова не содержит. DeepSeek регулярно так «зависает»: пишет
-// «Now update README to mention …», «Let me run the tests», «Сейчас проверю»
-// и останавливается. Такие ответы нельзя принимать за финальные — иначе
-// агент встаёт, не выполнив работу. Держим эвристику узкой (будущее время /
-// намерение), чтобы не ловить обычные отчёты о выполненной работе.
+// Text that promises a tool call in the future tense but contains no call
+// itself. DeepSeek regularly "hangs" like this: it writes
+// "Now update README to mention …", "Let me run the tests", "I'll check now"
+// and stops. Such answers must not be taken as final — otherwise the agent
+// stalls without doing the work. We keep the heuristic narrow (future tense /
+// intent) so we don't catch ordinary reports of completed work.
 function looksLikeUnfinishedWork(text) {
     const t = (text || '').trim();
     if (!t)
         return false;
-    // Длинные ответы (отчёты) не трогаем — там может быть что угодно.
+    // Long answers (reports) are left alone — anything can be in there.
     if (t.length > 600)
         return false;
-    // Уже есть финальный маркер — считаем ответ завершённым.
+    // A final marker is already present — treat the answer as complete.
     if (/\b(done|finished|completed|готово|выполнено|завершено)\b/i.test(t)) {
         return false;
     }
@@ -722,17 +732,18 @@ function findMatching(text, openIdx, openCh, closeCh) {
     }
     return -1;
 }
-// Модель иногда отдаёт вызов инструмента с ключами/строками в одинарных
-// кавычках («{'tool': 'Read', 'args': {...}}») или с ключами без кавычек
-// («{tool: "Read", args: {...}}»). Это не валидный JSON, и без нормализации
-// такой ответ молча принимается за финальный — агент встаёт, не вызвав
-// инструмент. Приводим его к двойным кавычкам.
+// The model sometimes returns a tool call with single-quoted keys/strings
+// ("{'tool': 'Read', 'args': {...}}") or unquoted keys
+// ("{tool: \"Read\", args: {...}}"). This is not valid JSON, and without
+// normalization such an answer is silently taken as final — the agent stalls
+// without calling a tool. We normalize it to double quotes.
 function normalizePseudoJson(str) {
-    // Ключи без кавычек: {tool: ...} или , args: ... → "tool": / "args":
+    // Unquoted keys: {tool: ...} or , args: ... → "tool": / "args":
     let out = str.replace(/([\{\[]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
     out = out.replace(/,\s*([A-Za-z_][A-Za-z0-9_]*)\s*:/g, ', "$1":');
-    // Одинарные кавычки → двойные. Не трогаем содержимое уже двойных строк,
-    // идущее подряд, и экранируем случайные двойные внутри одинарных.
+    // Single quotes → double quotes. We don't touch the content of already
+    // double-quoted strings in a row, and escape stray double quotes inside
+    // single quotes.
     let res = '';
     let inDouble = false;
     let inSingle = false;
@@ -770,27 +781,27 @@ function normalizePseudoJson(str) {
     }
     return res;
 }
-// Модель иногда портит начало вызова: `<｜tool": "Bash", "args": {...}`,
-// `tool": "Read", ...`, `**tool**: ...`, `- tool: ...`. В таких ответах
-// нет открывающей `{`, а ключ `tool` лишился первой кавычки. Если такой
-// ответ принять за финальный, агент молча встанет (частая «остановка»).
-// Восстанавливаем: срезаем мусорный префикс до слова tool, добавляем `{` и
-// доводим кавычки ключа до парных.
+// The model sometimes corrupts the head of a call: `<｜tool": "Bash", "args": {...}`,
+// `tool": "Read", ...`, `**tool**: ...`, `- tool: ...`. Such answers have no
+// opening `{`, and the `tool` key lost its first quote. If such an answer is
+// taken as final, the agent silently stalls (a frequent "stop").
+// We repair it: trim the junk prefix up to the word tool, add `{` and
+// balance the key quotes.
 function repairToolCallPreamble(text) {
     const t = (text || '').trim();
     const m = t.match(/(?:^|[^A-Za-z0-9_])(?:\*\*)?(tool)(?:\*\*)?["'`\u2018\u2019\u201c\u201d]*\s*:/);
     if (!m || m.index === undefined)
         return null;
-    // Начало ищем с первой кавычки/скобки вокруг ключа, иначе — с слова tool.
+    // We look for the start from the first quote/bracket around the key, otherwise from the word tool.
     let start = m.index;
     const brace = t.indexOf('{', Math.max(0, start - 1));
     if (brace !== -1 && brace < start)
         start = brace;
     let frag = t.slice(start);
-    // Если фрагмент не начинается с `{` — добавляем его.
+    // If the fragment does not start with `{` — we add it.
     if (!frag.startsWith('{')) {
-        // Ключ мог потерять открывающую кавычку: tool": → "tool":.
-        // Срезаем ведущий мусор до слова tool и нормализуем кавычки ключа.
+        // The key may have lost its opening quote: tool": → "tool".
+        // We trim the leading junk up to the word tool and normalize the key quotes.
         frag = frag.replace(/^[^A-Za-z0-9_]*/, '');
         frag = frag.replace(/^(?:\*\*)?(["'`\u2018\u2019\u201c\u201d]*)(tool)(?:\*\*)?["'`\u2018\u2019\u201c\u201d]*\s*:/, '"$2":');
         frag = '{' + frag;
@@ -806,8 +817,23 @@ export function parseToolCall(text) {
         .replace(/```$/i, '')
         .trim();
     const candidates = extractJsonObjects(cleaned);
-    for (let i = candidates.length - 1; i >= 0; i--) {
+    // We collect EVERY recognized call, not just the first one found. The model
+    // often emits several separate {"tool": ...} objects in one answer instead of
+    // a single JSON array. Returning only one of them used to drop the rest and
+    // could leave the agent "stalled after a tool call" with pending work.
+    const collected = [];
+    const tryCollect = (parsed) => {
+        if (!parsed)
+            return false;
+        if (Array.isArray(parsed))
+            collected.push(...parsed);
+        else
+            collected.push(parsed);
+        return true;
+    };
+    for (let i = 0; i < candidates.length; i++) {
         const raw = candidates[i];
+        // A JSON array of calls is authoritative: if present, use all of it.
         const arrFirst = tryParseArray(raw);
         if (arrFirst)
             return arrFirst;
@@ -815,22 +841,32 @@ export function parseToolCall(text) {
         if (arrRepaired)
             return arrRepaired;
         const first = tryParse(raw);
-        if (first)
-            return first;
+        if (first) {
+            tryCollect(first);
+            continue;
+        }
         const repaired = raw.replace(/\\(?!["\\/bfnrtu])/g, '\\\\');
         const second = tryParse(repaired);
-        if (second)
-            return second;
+        if (second) {
+            tryCollect(second);
+            continue;
+        }
         const ctrl = repairRawControlChars(raw);
         const third = tryParse(ctrl);
-        if (third)
-            return third;
+        if (third) {
+            tryCollect(third);
+            continue;
+        }
         const ctrlArr = tryParseArray(ctrl);
         if (ctrlArr)
             return ctrlArr;
     }
-    // Псевдо-JSON (одинарные кавычки / ключи без кавычек) — нормализуем и
-    // пробуем распарсить как обычный вызов, прежде чем идти в permissive.
+    if (collected.length === 1)
+        return collected[0];
+    if (collected.length > 1)
+        return collected;
+    // Pseudo-JSON (single quotes / unquoted keys) — normalize and try to parse
+    // as a regular call before going permissive.
     if (/['"]?tool['"]?\s*:/.test(cleaned)) {
         const norm = normalizePseudoJson(cleaned);
         if (norm !== cleaned) {
@@ -861,10 +897,10 @@ export function parseToolCall(text) {
     const xmlCalls = parseXmlToolCalls(cleaned);
     if (xmlCalls)
         return Array.isArray(xmlCalls) ? xmlCalls : [xmlCalls];
-    // Последняя попытка: «починить» испорченную голову вызова (`<｜tool": ...`,
-    // `tool": ...`, `**tool**: ...`, `- tool: ...`). Делаем это ТОЛЬКО как
-    // fallback, после обычного разбора — иначе легко испортить валидный JSON
-    // (например, массив вызовов начинается с `[`, внутри которого `{"tool":`).
+    // Last attempt: "fix" a corrupted call head (`<｜tool": ...`,
+    // `tool": ...`, `**tool**: ...`, `- tool: ...`). We do this ONLY as a
+    // fallback, after regular parsing — otherwise it's easy to corrupt valid
+    // JSON (e.g. an array of calls starts with `[`, containing `{"tool":`).
     const preamble = repairToolCallPreamble(cleaned);
     if (preamble && preamble !== cleaned) {
         const reps = [

package/dist/browser.js

@@ -25,10 +25,9 @@ const SEND_SELECTORS = [
     'button[aria-label*="send" i]',
     'button[aria-label*="отправ" i]',
 ];
-// ВАЖНО: сюда НЕЛЬЗЯ добавлять общий 'div[role="button"][class*="ds-button--primary"]'
-// — под него попадает кнопка отправки, которая видна всегда, и тогда
-// _isGenerating() вечно возвращает true, из-за чего ответ никогда не
-// считается готовым.
+// IMPORTANT: you MUST NOT add the generic 'div[role="button"][class*="ds-button--primary"]'
+// here — it matches the send button, which is always visible, and then
+// _isGenerating() always returns true, so the answer is never considered ready.
 const STOP_SELECTORS = [
     'div[role="button"][aria-label*="stop" i]',
     'div[role="button"][aria-label*="останов" i]',
@@ -36,16 +35,16 @@ const STOP_SELECTORS = [
     'button:has-text("Остановить")',
     'button[aria-label*="Stop" i]',
 ];
-// Служебные статусы интерфейса DeepSeek, которые НЕ являются ответом модели.
-// Иначе агент принимает статус (Reading...) за ответ и ломает разбор.
+// DeepSeek UI service statuses that are NOT the model's answer.
+// Otherwise the agent takes a status (Reading...) for an answer and breaks parsing.
 const STATUS_RE = /^(reading|thinking|searching|analyzing|generating|stop|остановить|читаю|думаю|поиск|анализ)[\s.…]*$/i;
-// Ответ DeepSeek при превышении лимита частоты.
+// DeepSeek's answer when the rate limit is exceeded.
 const RATE_LIMIT_RE = /(messages? too frequent|too many requests|rate limit|слишком часто|повторите позже|try again later)/i;
 export function isRateLimitText(text) {
     return RATE_LIMIT_RE.test(String(text || ''));
 }
-// Ошибка «слишком часто»: отличается от прочих, чтобы ask() ждал долго
-// (лимиты DeepSeek сбрасываются за минуты) и повторял отправку сам.
+// The "too frequent" error: distinct from others so ask() waits a long time
+// (DeepSeek limits reset over minutes) and retries the send itself.
 export class RateLimitError extends Error {
     constructor(detail) {
         super('Messages too frequent. Try again later. ' + detail);
@@ -100,9 +99,9 @@ export class DeepSeekBrowser {
     maxRateLimitRetries;
     _lastSentAt;
     _abort;
-    // Пользователь нажал Esc/Ctrl+C — «стоп» для ВСЕЙ текущей пачки задач
-    // (включая очередь). В отличие от _abort (сбрасывается на каждую
-    // отправку), этот флаг живёт до явного запуска новой задачи с промпта.
+    // The user pressed Esc/Ctrl+C — a "stop" for the WHOLE current batch of
+    // tasks (including the queue). Unlike _abort (reset on every send), this
+    // flag lives until a new task is explicitly started from the prompt.
     _stopped;
     context;
     page;
@@ -284,9 +283,9 @@ export class DeepSeekBrowser {
         return null;
     }
     async _readLastAnswerText() {
-        // Если удалось перехватить сырой текст ответа по сети (без рендер-
-        // искажений DeepSeek) и он относится к текущему ответу — отдаём его.
-        // Это защищает $, экранированные переводы строк и т.п. в аргументах.
+        // If we managed to intercept the raw answer text over the network
+        // (without DeepSeek's render distortions) and it belongs to the current
+        // answer — we return it. This protects $, escaped newlines, etc. in arguments.
         if (this._netCapture && this._netCaptureAt >= this._lastSentAt) {
             return this._netCapture;
         }
@@ -304,9 +303,9 @@ export class DeepSeekBrowser {
             return out.replace(new RegExp(NL + '{3,}', 'g'), NL + NL).trim();
         }, ANSWER_SELECTORS);
     }
-    // Читаем ТОЛЬКО видимые тосты/уведомления/ошибки, а не весь текст
-    // страницы. Иначе ловим «try again later» из служебных/скрытых блоков
-    // и уходим в ложное ожидание лимита на 5 минут.
+    // We read ONLY visible toasts/notifications/errors, not the whole page
+    // text. Otherwise we catch "try again later" from service/hidden blocks
+    // and go into a false 5-minute rate-limit wait.
     async _readPageText() {
         return await this.page
             .evaluate(() => {
@@ -340,9 +339,9 @@ export class DeepSeekBrowser {
             return '';
         return raw;
     }
-    // Найти кнопку Stop в интерфейсе DeepSeek. Полагаться только на класс
-    // нельзя: во время генерации кнопка отправки (та же circle-кнопка)
-    // меняет иконку на «квадрат» (stop), сохраняя классы.
+    // Find the Stop button in the DeepSeek UI. We can't rely on the class
+    // alone: during generation the send button (the same circle button)
+    // changes its icon to a "square" (stop) while keeping the classes.
     async _stopButtonVisible() {
         const explicit = await this._findVisible(STOP_SELECTORS, 250);
         if (explicit)
@@ -361,7 +360,7 @@ export class DeepSeekBrowser {
                     (b.textContent || '')).toLowerCase();
                 if (/stop|останов/.test(label))
                     return true;
-                // Иконка-квадрат = кнопка Stop; стрелка (path без rect) = отправка.
+                // A square icon = Stop button; an arrow (path without rect) = send.
                 const svg = b.querySelector('svg');
                 if (svg && svg.querySelector('rect'))
                     return true;
@@ -420,9 +419,9 @@ export class DeepSeekBrowser {
             }
             catch (e) {
                 lastErr = e;
-                // Лимит частоты: DeepSeek не принял сообщение. Ждём долго и
-                // повторяем отправку в ТОТ ЖЕ чат (без newChat — иначе теряется
-                // контекст). Паузы не расходуют обычные попытки ask().
+                // Rate limit: DeepSeek did not accept the message. We wait a long time
+                // and resend into the SAME chat (without newChat — otherwise the
+                // context is lost). The waits don't consume the regular ask() attempts.
                 if (e instanceof RateLimitError) {
                     rateLimitRetries++;
                     if (rateLimitRetries > this.maxRateLimitRetries) {
@@ -495,9 +494,9 @@ export class DeepSeekBrowser {
             await this.page.keyboard.insertText(text);
         }
     }
-    // Пауза между отправками. Применяется ТОЛЬКО к сообщениям агента
-    // (tool-result, system-prompt), чтобы не упираться в лимит частоты.
-    // Пользовательский ввод отправляется без задержки.
+    // Pause between sends. Applied ONLY to agent messages
+    // (tool-result, system-prompt) so we don't hit the rate limit.
+    // User input is sent without delay.
     async _waitForSendSlot(agent) {
         if (!agent)
             return;
@@ -510,7 +509,7 @@ export class DeepSeekBrowser {
         await this.page.waitForTimeout(gap);
     }
     async _askOnce(prompt, { timeout, agent }) {
-        // Сбрасываем флаг прерывания ТОЛЬКО в самом начале отправки.
+        // We reset the abort flag ONLY at the very start of the send.
         this._abort = false;
         const input = await this._findVisible(INPUT_SELECTORS, 10_000);
         if (!input) {
@@ -540,9 +539,9 @@ export class DeepSeekBrowser {
             await this.page.keyboard.press('Enter');
         }
         this._lastSentAt = Date.now();
-        // Ждём старта: либо появился Stop, либо изменился текст ответа,
-        // либо вырос общий объём текста на странице. Параллельно ловим
-        // тост о превышении лимита частоты (только тосты, не весь body).
+        // Wait for the start: either Stop appeared, or the answer text changed,
+        // or the total amount of text on the page grew. In parallel we catch
+        // the rate-limit toast (only toasts, not the whole body).
         const startDeadline = Date.now() + 15_000;
         const startBodyLen = await this.page
             .evaluate(() => document.body.innerText.length)
@@ -567,15 +566,15 @@ export class DeepSeekBrowser {
             await this.page.waitForTimeout(300);
         }
         if (!started) {
-            // Больше НЕ проверяем лимит по всему тексту страницы — это давало
-            // ложные срабатывания и 5-минутные паузы. Просто сообщаем, что
-            // генерация не началась.
+            // We NO LONGER check the limit over the whole page text — that caused
+            // false positives and 5-minute waits. We just report that
+            // generation did not start.
             throw new Error('Ответ не начал генерироваться за 15с. Возможно, сообщение не отправилось.');
         }
-        // Ждём, пока ответ перестанет меняться. Условие "не генерируется"
-        // проверяем через рост текста, а НЕ через _isGenerating().
-        // Параллельно ловим тост лимита частоты, если он всплывёт во время
-        // генерации (читаем только тосты, ложных срабатываний нет).
+        // Wait until the answer stops changing. We check the "not generating"
+        // condition via text growth, NOT via _isGenerating().
+        // In parallel we catch the rate-limit toast if it pops up during
+        // generation (we read only toasts, so there are no false positives).
         const deadline = Date.now() + timeout;
         let last = '';
         let stable = 0;
@@ -584,8 +583,8 @@ export class DeepSeekBrowser {
             if (this._abort) {
                 return last || '(прервано пользователем)';
             }
-            // Тост лимита проверяем не каждый тик, а раз в ~5 тиков, чтобы не
-            // дёргать DOM лишний раз.
+            // We check the limit toast not every tick but about once per 5 ticks,
+            // so we don't poke the DOM unnecessarily.
             if (tick++ % 5 === 0) {
                 const pageText = await this._readPageText();
                 if (isRateLimitText(pageText)) {