zames_pro 2.73.0 → 2.73.2

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.73.2] - 2026-10-11
+
+### Changed
+
+- docs(readme): document Qwen everywhere and refresh the diagram
+
+## [2.73.1] - 2026-10-11
+
+### Fixed
+
+- **qwen:** live provider switch, verified send, server-busy handling
+
 ## [2.73.0] - 2026-10-11
 
 ### Added

package/README.md

@@ -63,27 +63,31 @@ zames does not call the model API. It launches a headless Chromium with a
 persistent profile, signs in to a chat web app like a human, types the task
 into the chat box, and reads the answer back.
 
-Two chat backends are available, switched with `/provider <deepseek|qwen>`
-(restart required): **DeepSeek** (`chat.deepseek.com`, the default) and
-**Qwen** (`chat.qwen.ai`). Each keeps its own persistent profile, so switching
-never signs the other one out.
+Two chat backends are available, switched with `/provider <deepseek|qwen>`:
+**DeepSeek** (`chat.deepseek.com`, the default) and **Qwen** (`chat.qwen.ai`).
+The switch is **live** — zames closes the current backend and opens the other
+one in place, no restart needed. Each keeps its own persistent profile
+(`~/.zames/profile` and `~/.zames/qwen-profile`), so switching never signs the
+other one out.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="how zames works" width="860">
 </p>
 
 In text: you type a task → zames sends the system prompt plus the task into
-the DeepSeek web chat → the model answers → zames parses the tool call, runs
-the tool locally, feeds the result back, and prints the final answer for you.
+the active chat web app (DeepSeek or Qwen) → the model answers → zames parses
+the tool call, runs the tool locally, feeds the result back, and prints the
+final answer for you.
 
 Key pieces:
 
 - **The answer is read from the raw network stream** (SSE), not the rendered
   DOM, so tool-call JSON with template strings and escapes survives intact.
-- **A persistent profile** (`~/.zames/profile`) keeps you signed in; the
-  headless User-Agent is patched so DeepSeek's CDN does not 403 the login.
-- **A send throttle** (15 s by default) keeps the web chat's rate limit happy
-  during long tool-heavy runs.
+- **A persistent per-provider profile** (`~/.zames/profile` for DeepSeek,
+  `~/.zames/qwen-profile` for Qwen) keeps you signed in; the headless
+  User-Agent is patched so the site's CDN does not 403 the login.
+- **A send throttle** (15 s on DeepSeek, ~1 s on Qwen, which tolerates rapid
+  sends) keeps the web chat's rate limit happy during long tool-heavy runs.
 - **The agent is sandboxed** to the directory it was started in — no tool can
   read or write above it.
 
@@ -174,7 +178,7 @@ zames can drive either **DeepSeek** (`chat.deepseek.com`, the default) or
 **Qwen** (`chat.qwen.ai`):
 
 ```bash
-/provider qwen      # switch to Qwen (persisted); restart zames to take effect
+/provider qwen      # switch to Qwen (persisted) — applied live, no restart
 /provider deepseek  # switch back
 /provider status    # show the active provider / model / login state
 /provider login     # (re)run the sign-in check
@@ -184,15 +188,18 @@ zames can drive either **DeepSeek** (`chat.deepseek.com`, the default) or
 
 Notes:
 
-- The two backends use **separate persistent profiles**
-  (`~/.zames/profile` for DeepSeek, `~/.zames/qwen-profile` for Qwen), so
-  switching never signs the other one out. A provider switch takes effect on
-  the next launch — the browser is created once at startup.
+- The switch is **live**: zames closes the current backend and opens the other
+  one in place, so no restart is needed. The two backends use **separate
+  persistent profiles** (`~/.zames/profile` for DeepSeek, `~/.zames/qwen-profile`
+  for Qwen), so switching never signs the other one out.
+- A chat id belongs to ONE backend, so the new provider opens a **fresh chat**.
+  If the previous chat had messages they are summarized and posted as a
+  handoff with the next task; an empty chat is switched silently.
 - Qwen works in **guest mode** without an account, but a guest is limited to a
   handful of messages per day; for long agent runs sign in (email / Google /
   GitHub — no phone required). zames auto-logins from the saved credentials or
   asks in the terminal, exactly like DeepSeek. `/model` changes the Qwen model
-  at runtime (no restart).
+  at runtime.
 - File attachments on Qwen go through the mode menu's **Upload attachment**
   item; DeepSeek uses its own paperclip.
 - `/doctor` shows the active provider and the UI health of that provider's
@@ -343,9 +350,10 @@ Codex CLI:
   (zames-export-<stamp>.md by default).
 - /doctor — diagnose node, git, config, browser, clipboard, MCP and the
   active chat provider (it also reports that provider's UI health).
-- /provider <deepseek|qwen> — switch the chat backend (restart to apply);
-  /provider status shows the active provider/model/login; /provider login
-  re-runs the sign-in check. /model [id] lists or picks a Qwen model at runtime.
+- /provider <deepseek|qwen> — switch the chat backend (applied live, no
+  restart); /provider status shows the active provider/model/login; /provider
+  login re-runs the sign-in check. /model [id] lists or picks a Qwen model at
+  runtime.
 - /add-dir <path> — validate an extra directory (the sandbox is fixed at
   startup; relaunch with --dir to write there).
 - /resume <n> (after /chats) and /resume-id <id> — open a chat and PRINT its
@@ -582,30 +590,33 @@ zames не вызывает API модели. Он запускает headless C
 профилем, входит в веб-чат как человек, печатает задачу в поле чата и читает
 ответ обратно.
 
-Доступны два бэкенда, переключаются командой `/provider <deepseek|qwen>`
-(нужен перезапуск): **DeepSeek** (`chat.deepseek.com`, по умолчанию) и
-**Qwen** (`chat.qwen.ai`). У каждого свой постоянный профиль, поэтому
-переключение не разлогинивает другой.
+Доступны два бэкенда, переключаются командой `/provider <deepseek|qwen>`:
+**DeepSeek** (`chat.deepseek.com`, по умолчанию) и **Qwen** (`chat.qwen.ai`).
+Переключение **живое** — zames закрывает текущий бэкенд и открывает другой на
+месте, без перезапуска. У каждого свой постоянный профиль
+(`~/.zames/profile` и `~/.zames/qwen-profile`), поэтому переключение не
+разлогинивает другой.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="как работает zames" width="860">
 </p>
 
 Словами: вы вводите задачу → zames отправляет системный промпт и задачу в
-веб-чат DeepSeek → модель отвечает → zames разбирает вызов инструмента,
-выполняет его локально, возвращает результат обратно и печатает финальный
-ответ.
+активный веб-чат (DeepSeek или Qwen) → модель отвечает → zames разбирает
+вызов инструмента, выполняет его локально, возвращает результат обратно и
+печатает финальный ответ.
 
 Ключевые детали:
 
 - **Ответ читается из сырого сетевого потока** (SSE), а не из отрендеренного
   DOM, поэтому JSON вызова инструмента с шаблонными строками и экранированием
   остаётся целым.
-- **Постоянный профиль** (`~/.zames/profile`) держит вас залогиненным;
-  User-Agent headless-браузера подменяется, чтобы CDN DeepSeek не отдавал 403
-  на вход.
-- **Троттлинг отправки** (15 с по умолчанию) щадит рейт-лимит веб-чата во
-  время долгих прогонов с инструментами.
+- **Постоянный профиль на каждого провайдера** (`~/.zames/profile` у DeepSeek,
+  `~/.zames/qwen-profile` у Qwen) держит вас залогиненным; User-Agent
+  headless-браузера подменяется, чтобы CDN сайта не отдавал 403 на вход.
+- **Троттлинг отправки** (15 с у DeepSeek, ~1 с у Qwen, который спокойно
+  переносит частые отправки) щадит рейт-лимит веб-чата во время долгих
+  прогонов с инструментами.
 - **Агент запесочен** в директорию запуска — ни один инструмент не может
   читать или писать выше неё.
 
@@ -698,7 +709,7 @@ zames умеет работать с **DeepSeek** (`chat.deepseek.com`, по у
 **Qwen** (`chat.qwen.ai`):
 
 ```bash
-/provider qwen      # переключиться на Qwen (сохраняется); нужен перезапуск
+/provider qwen      # переключиться на Qwen (сохраняется) — применяется сразу
 /provider deepseek  # вернуться обратно
 /provider status    # активный провайдер / модель / статус входа
 /provider login     # повторно пройти проверку входа
@@ -708,15 +719,17 @@ zames умеет работать с **DeepSeek** (`chat.deepseek.com`, по у
 
 Замечания:
 
-- У бэкендов **разные постоянные профили** (`~/.zames/profile` у DeepSeek,
-  `~/.zames/qwen-profile` у Qwen), поэтому переключение не разлогинивает
-  другой. Смена провайдера применяется при следующем запуске — браузер
-  создаётся один раз на старте.
+- Переключение **живое**: zames закрывает текущий бэкенд и открывает другой на
+  месте, перезапуск не нужен. У бэкендов **разные постоянные профили**
+  (`~/.zames/profile` у DeepSeek, `~/.zames/qwen-profile` у Qwen), поэтому
+  переключение не разлогинивает другой.
+- id чата принадлежит ОДНОМУ бэкенду, поэтому новый провайдер открывает
+  **свежий чат**. Если в прошлом чате были сообщения, они сжимаются и
+  подставляются как handoff в следующую задачу; пустой чат переключается молча.
 - Qwen работает в **гостевом режиме** без аккаунта, но гостю доступно всего
   несколько сообщений в день; для долгих прогонов войдите (email / Google /
   GitHub — телефон не нужен). zames сам логинится по сохранённым кредам или
-  спросит в терминале, как и с DeepSeek. `/model` меняет модель Qwen на лету
-  (без перезапуска).
+  спросит в терминале, как и с DeepSeek. `/model` меняет модель Qwen на лету.
 - Вложения в Qwen идут через пункт **Upload attachment** в меню режима; в
   DeepSeek — своя скрепка.
 - `/doctor` показывает активный провайдер и состояние UI его страницы.
@@ -872,9 +885,10 @@ zames --task "..." --output-format jsonl \
   (по умолчанию zames-export-<stamp>.md).
 - /doctor — диагностика node, git, конфига, браузера, буфера обмена, MCP и
   активного провайдера чата (плюс состояние UI его страницы).
-- /provider <deepseek|qwen> — сменить бэкенд чата (нужен перезапуск);
-  /provider status показывает активный провайдер/модель/вход; /provider login
-  повторно проверяет вход. /model [id] покажет или выберет модель Qwen на лету.
+- /provider <deepseek|qwen> — сменить бэкенд чата (применяется сразу, без
+  перезапуска); /provider status показывает активный провайдер/модель/вход;
+  /provider login повторно проверяет вход. /model [id] покажет или выберет
+  модель Qwen на лету.
 - /add-dir <path> — проверить дополнительную директорию (песочница
   фиксируется при старте; для записи туда перезапустите с --dir).
 - /resume <n> (после /chats) и /resume-id <id> — открыть чат и НАПЕЧАТАТЬ его

package/dist/agent-loop.js

@@ -547,9 +547,11 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     (justRanTool
                         ? 'You stopped after a tool call and wrote plain text. '
                         : 'You wrote plain text without a tool call. ') +
+                        'Plain text is a PROTOCOL VIOLATION — the operator never sees it. ' +
                         'The task is not finished. Reply with EXACTLY one JSON tool-call ' +
                         'object, no text before or after, for example: ' +
                         '{\"tool\": \"Bash\", \"args\": {\"command\": \"...\"}}. ' +
+                        'Do NOT explain, plan or narrate — call a tool. ' +
                         'If the task is really done — call respond with the final message.';
                 continue;
             }

package/dist/i18n/common.js

@@ -1,8 +1,8 @@
 // Common UI strings: app/common, status, tasks, messages, diff, context, undo, cd.
 export const commonMessages = {
     'app.tagline': {
-        ru: 'агент поверх chat.deepseek.com через Playwright',
-        en: 'coding agent over chat.deepseek.com via Playwright',
+        ru: 'агент поверх chat.deepseek.com / chat.qwen.ai через Playwright',
+        en: 'coding agent over chat.deepseek.com / chat.qwen.ai via Playwright',
     },
     'common.yes': { ru: 'да', en: 'yes' },
     'common.no': { ru: 'нет', en: 'no' },

package/dist/i18n/qwen.js

@@ -26,10 +26,6 @@ export const qwenMessages = {
         ru: 'Qwen: войти не удалось. Войдите вручную в окне браузера (запустите с --headed) и повторите.',
         en: 'Qwen: sign-in failed. Sign in manually in the browser window (launch with --headed) and retry.',
     },
-    'qwen.attach_unsupported': {
-        ru: 'Qwen: вложения пока не поддерживаются — файлы не отправлены.',
-        en: 'Qwen: attachments are not supported yet — files were not sent.',
-    },
     'qwen.guest_limit': {
         ru: 'Qwen: исчерпан суточный лимит гостя. Войдите в аккаунт (email / Google / GitHub) командой /provider login или запустите с --headed.',
         en: 'Qwen: the guest daily limit is exhausted. Sign in (email / Google / GitHub) with /provider login, or launch with --headed.',
@@ -55,16 +51,24 @@ export const qwenMessages = {
         en: 'Failed to fetch the Qwen model list: {v}',
     },
     'provider.switched': {
-        ru: 'Провайдер чата: {v}. Перезапустите zames, чтобы сменить браузер.',
-        en: 'Chat provider: {v}. Restart zames to switch the browser.',
+        ru: 'Провайдер чата: {v}.',
+        en: 'Chat provider: {v}.',
+    },
+    'provider.switching': {
+        ru: 'Переключаю провайдера на {v}: закрываю старый браузер и открываю {v}...',
+        en: 'Switching provider to {v}: closing the old browser and opening {v}...',
+    },
+    'provider.switch_failed': {
+        ru: '✖ Не удалось открыть браузер {v}: {error}. Остаюсь на прежнем провайдере; проверь вход и попробуй снова.',
+        en: '✖ Could not open the {v} browser: {error}. Staying on the previous provider; check the login and retry.',
     },
     'provider.usage': {
         ru: 'Использование: /provider <deepseek|qwen> | /provider login | /provider status',
         en: 'Usage: /provider <deepseek|qwen> | /provider login | /provider status',
     },
     'provider.handoff_saved': {
-        ru: 'Контекст текущего чата сжат и сохранён для {v}. Он подхватится при следующем запуске.',
-        en: 'The current chat was summarized and saved for {v}. It will be carried over on the next launch.',
+        ru: 'Контекст текущего чата сжат и сохранён для {v}. Он подхватится в следующей задаче.',
+        en: 'The current chat was summarized and saved for {v}. It will be carried over with the next task.',
     },
     'provider.handoff_used': {
         ru: '📎 Подхватил контекст предыдущего провайдера (carried-over summary).',
@@ -82,4 +86,47 @@ export const qwenMessages = {
         ru: 'Провайдер: {v}, модель: {m}, вход: {auth}',
         en: 'Provider: {v}, model: {m}, login: {auth}',
     },
+    // Qwen-specific statuses. The DeepSeek path had these under `ds.*`; using
+    // the SAME keys from QwenBrowser broke provider encapsulation (a Qwen notice
+    // was labelled with DeepSeek wording), so they live here instead.
+    'qwen.rate_limit_wait': {
+        ru: '⏳ {provider}: «слишком часто». Жду {min} мин ({attempt}/{max}) и повторю отправку...',
+        en: '⏳ {provider}: "too frequent". Waiting {min} min ({attempt}/{max}), then resending...',
+    },
+    'qwen.server_busy_wait': {
+        ru: '⏳ {provider}: сервер занят. Жду {sec}с ({attempt}/{max}) и повторю...',
+        en: '⏳ {provider}: server busy. Waiting {sec}s ({attempt}/{max}), then retrying...',
+    },
+    'qwen.incomplete_retry': {
+        ru: '⏳ {provider} оборвал ответ — переотправляю задачу ({attempt}/{max})...',
+        en: '⏳ {provider} truncated the answer — resending the task ({attempt}/{max})...',
+    },
+    'qwen.ask_retry': {
+        ru: '⚠ Отправка не удалась (попытка {attempt}/{max} на этот запрос): {error} — повторяю...',
+        en: '⚠ Send failed (attempt {attempt}/{max} for this request): {error} — retrying...',
+    },
+    'qwen.ask_failed': {
+        ru: '✖ Не удалось получить ответ от {provider} после {max} попыток: {error}',
+        en: '✖ Could not get an answer from {provider} after {max} attempts: {error}',
+    },
+    'qwen.attach_read_failed': {
+        ru: '⚠ не удалось прочитать вложение {name}: {error}',
+        en: '⚠ could not read the attachment {name}: {error}',
+    },
+    'qwen.attach_no_input': {
+        ru: '⚠ не найдено поле загрузки файлов — вложения не прикреплены',
+        en: '⚠ file upload field not found — the attachments were not attached',
+    },
+    'qwen.input_missing': {
+        ru: '✖ Не найдено поле ввода на странице {provider}. Запусти /debug-dom и поправь INPUT_SELECTORS.',
+        en: '✖ The {provider} input field was not found. Run /debug-dom and fix INPUT_SELECTORS.',
+    },
+    'qwen.send_no_new_answer': {
+        ru: '✖ Новый ответ не получен — на странице остался прежний текст. Возможно, сообщение не отправилось (кнопка отправки не нажалась). Проверь чат {provider} вручную.',
+        en: '✖ No new answer received — the page still shows the previous text. The message may not have been sent (the send button was not pressed). Check the {provider} chat manually.',
+    },
+    'qwen.send_button_missing': {
+        ru: '✖ Кнопка отправки Qwen не найдена или недоступна — сообщение не отправлено. Проверь чат вручную.',
+        en: '✖ The Qwen send button was not found or is disabled — the message was not sent. Check the chat manually.',
+    },
 };

package/dist/index.js

@@ -613,6 +613,46 @@ function providerAnswerTimeoutMs() {
 function browserProviderUrl() {
     return providerChatUrlPrefix(config.provider);
 }
+/**
+ * Build the browser for a provider. Called at startup AND on a live
+ * `/provider` switch, so both paths construct the class the same way. The
+ * two backends differ in every layer (selectors, SSE format, chat-id scheme),
+ * so the choice is a class, not a flag; the shared timings live in
+ * config.browser and only Qwen-only knobs are overridden.
+ */
+function createProviderBrowser(provider) {
+    const persistAuth = (username, password) => {
+        config.browser.auth.username = username;
+        config.browser.auth.password = password;
+        try {
+            writeConfigValue('home', 'browser.auth.username', username);
+            writeConfigValue('home', 'browser.auth.password', password);
+        }
+        catch { }
+    };
+    return provider === 'qwen'
+        ? new QwenBrowser({
+            headless,
+            debug,
+            channel: config.browserChannel,
+            ...config.browser,
+            // Qwen-specific overrides (see config.qwen): no 15s DeepSeek
+            // throttle, a longer cold-start answer timeout.
+            minSendIntervalMs: config.qwen.minSendIntervalMs,
+            answerTimeoutMs: config.qwen.answerTimeoutMs,
+            model: config.qwen.model,
+            locale: currentLocale,
+            onAuthSave: persistAuth,
+        })
+        : new DeepSeekBrowser({
+            headless,
+            debug,
+            channel: config.browserChannel,
+            ...config.browser,
+            locale: currentLocale,
+            onAuthSave: persistAuth,
+        });
+}
 /**
  * Print the dialogue of the just-opened chat into the terminal. Called by
  * /resume, /resume-id and on startup when a previous session is restored, so
@@ -784,47 +824,10 @@ async function main() {
     // class choice, not a flag. The shared timings live in config.browser; only
     // the model is provider-specific. A provider switch takes effect on the
     // next launch (the operator is told to restart).
-    const provider = asProviderId(config.provider);
-    const browser = provider === 'qwen'
-        ? new QwenBrowser({
-            headless,
-            debug,
-            channel: config.browserChannel,
-            ...config.browser,
-            // Qwen-specific overrides (see config.qwen): no 15s DeepSeek
-            // throttle, a longer cold-start answer timeout.
-            minSendIntervalMs: config.qwen.minSendIntervalMs,
-            answerTimeoutMs: config.qwen.answerTimeoutMs,
-            model: config.qwen.model,
-            locale: currentLocale,
-            onAuthSave: (username, password) => {
-                config.browser.auth.username = username;
-                config.browser.auth.password = password;
-                try {
-                    writeConfigValue('home', 'browser.auth.username', username);
-                    writeConfigValue('home', 'browser.auth.password', password);
-                }
-                catch { }
-            },
-        })
-        : new DeepSeekBrowser({
-            headless,
-            debug,
-            channel: config.browserChannel,
-            ...config.browser,
-            locale: currentLocale,
-            // Persist credentials the operator typed in the terminal so the next
-            // launch can re-login silently after a logout.
-            onAuthSave: (username, password) => {
-                config.browser.auth.username = username;
-                config.browser.auth.password = password;
-                try {
-                    writeConfigValue('home', 'browser.auth.username', username);
-                    writeConfigValue('home', 'browser.auth.password', password);
-                }
-                catch { }
-            },
-        });
+    // `let`, not `const`: a live /provider switch disposes this instance and
+    // builds the other one IN PLACE (see the /provider block in the main loop),
+    // so the URL changes without restarting zames.
+    let browser = createProviderBrowser(asProviderId(config.provider));
     const bootSpinner = mod.createSpinner(currentLocale);
     bootSpinner.thinking();
     try {
@@ -2062,69 +2065,135 @@ async function main() {
                     console.log(theme.system(t('provider.switched', { v: arg })));
                     continue;
                 }
-                // CARRY-OVER: a chat id only exists on its own backend, so switching
-                // providers loses the conversation. Summarize the CURRENT chat (still
-                // on the OLD browser object) and persist a handoff for the target; on
-                // the next launch the new provider posts it as the first message.
-                if (editor)
-                    editor.lock(t('msg.input_locked'));
-                try {
-                    const spin = editor || mod.createSpinner(currentLocale);
-                    spin.thinking();
-                    let summary = '';
-                    try {
-                        const answer = await browser.ask(mod.commands.buildCompactPrompt(currentLocale), {
-                            agent: true,
-                            timeout: providerAnswerTimeoutMs(),
-                        });
-                        const trimmed = String(answer || '').trim();
-                        if (mod.commands.isUsableCompactSummary(trimmed))
-                            summary = trimmed;
+                // Is there anything worth carrying over? A FRESH/EMPTY chat has no
+                // context to summarize, so switching it is a pure URL/backend change:
+                // summarizing an empty chat used to post a useless "please compact"
+                // request into a brand-new chat (a real complaint). We only build a
+                // handoff when the chat actually has messages.
+                let chatHasMessages = false;
+                if (browser.fetchChatMessages) {
+                    const cid = await browser.getCurrentChatId().catch(() => null);
+                    if (cid) {
+                        const all = await browser.fetchChatMessages(cid).catch(() => []);
+                        chatHasMessages =
+                            mod.commands.trimRestoredMessages(all, 0).length > 0;
                     }
-                    catch (e) {
-                        if (debug)
-                            console.error('handoff summary failed:', e.message);
-                    }
-                    // Fall back to the LOCAL history when the model summary is unusable.
-                    if (!summary && browser.fetchChatMessages) {
-                        const cid = await browser.getCurrentChatId().catch(() => null);
-                        const all = cid
-                            ? await browser.fetchChatMessages(cid).catch(() => [])
-                            : [];
-                        const msgs = mod.commands.trimRestoredMessages(all, 0);
-                        if (msgs.length) {
-                            summary = mod.commands.formatRestoredHistory(msgs, { limit: 40 });
+                }
+                if (chatHasMessages) {
+                    // CARRY-OVER: a chat id only exists on its own backend, so switching
+                    // providers loses the conversation. Summarize the CURRENT chat (still
+                    // on the OLD browser object) and persist a handoff for the target; it
+                    // is posted as the first message once the new provider is live.
+                    if (editor)
+                        editor.lock(t('msg.input_locked'));
+                    try {
+                        const spin = editor || mod.createSpinner(currentLocale);
+                        spin.thinking();
+                        let summary = '';
+                        try {
+                            const answer = await browser.ask(mod.commands.buildCompactPrompt(currentLocale), {
+                                agent: true,
+                                timeout: providerAnswerTimeoutMs(),
+                            });
+                            const trimmed = String(answer || '').trim();
+                            if (mod.commands.isUsableCompactSummary(trimmed))
+                                summary = trimmed;
+                        }
+                        catch (e) {
+                            if (debug)
+                                console.error('handoff summary failed:', e.message);
+                        }
+                        // Fall back to the LOCAL history when the model summary is unusable.
+                        if (!summary && browser.fetchChatMessages) {
+                            const cid = await browser.getCurrentChatId().catch(() => null);
+                            const all = cid
+                                ? await browser.fetchChatMessages(cid).catch(() => [])
+                                : [];
+                            const msgs = mod.commands.trimRestoredMessages(all, 0);
+                            if (msgs.length) {
+                                summary = mod.commands.formatRestoredHistory(msgs, {
+                                    limit: 40,
+                                });
+                            }
+                        }
+                        spin.stop();
+                        if (summary) {
+                            saveProviderHandoff({
+                                provider: arg,
+                                workdir: currentWorkdir,
+                                summary,
+                                task: lastTaskText || undefined,
+                                createdAt: new Date().toISOString(),
+                            });
+                            console.log(theme.system(t('provider.handoff_saved', { v: arg })));
+                        }
+                        else {
+                            console.log(theme.warn(t('provider.handoff_empty')));
                         }
                     }
-                    spin.stop();
-                    if (summary) {
-                        saveProviderHandoff({
-                            provider: arg,
-                            workdir: currentWorkdir,
-                            summary,
-                            task: lastTaskText || undefined,
-                            createdAt: new Date().toISOString(),
-                        });
-                        console.log(theme.system(t('provider.handoff_saved', { v: arg })));
-                    }
-                    else {
-                        console.log(theme.warn(t('provider.handoff_empty')));
+                    finally {
+                        if (editor)
+                            editor.unlock();
                     }
                 }
-                finally {
-                    if (editor)
-                        editor.unlock();
-                }
                 // Tag the current session with the OLD provider before switching.
                 if (currentChatId)
                     saveLastChat(currentChatId, currentWorkdir);
+                // Persist the choice FIRST so a crash mid-switch still remembers it.
                 config.provider = arg;
                 config.qwen.enabled = arg === 'qwen';
                 try {
                     writeConfigValue('home', 'provider', arg);
                 }
                 catch { }
-                console.log(theme.system(t('provider.switched', { v: arg })));
+                // LIVE SWITCH: dispose the old backend and open the new one in place,
+                // so the operator does not have to restart zames. The chat is NOT
+                // resumable across providers (different chat ids), so the new backend
+                // starts a FRESH chat and the handoff (if any) is posted with the next
+                // task.
+                if (editor)
+                    editor.lock(t('msg.input_locked'));
+                try {
+                    console.log(theme.system(t('provider.switching', { v: arg })));
+                    // Launch the NEW backend FIRST; only close the old one once it is up.
+                    // If we closed the old browser before the new one launched and the
+                    // launch failed, `browser` would point at a dead instance and every
+                    // later command would break.
+                    const nextBrowser = createProviderBrowser(arg);
+                    await nextBrowser.launch();
+                    await nextBrowser.waitForLogin();
+                    const oldBrowser = browser;
+                    browser = nextBrowser;
+                    await oldBrowser.close().catch(() => { });
+                    // The new backend has no chat yet.
+                    currentChatId = await browser.getCurrentChatId().catch(() => null);
+                    if (editor) {
+                        editor.setProvider(providerLabel(arg));
+                    }
+                    try {
+                        warnUiHealth(await browser.probeUiHealth());
+                    }
+                    catch { }
+                    console.log(theme.system(t('provider.switched', { v: arg })));
+                }
+                catch (e) {
+                    // The new backend did not come up: keep the OLD one active so the
+                    // session keeps working, and roll the persisted choice back.
+                    config.provider = from;
+                    config.qwen.enabled = from === 'qwen';
+                    try {
+                        writeConfigValue('home', 'provider', from);
+                    }
+                    catch { }
+                    console.error(theme.warn(t('provider.switch_failed', {
+                        v: arg,
+                        error: e.message,
+                    })));
+                }
+                finally {
+                    if (editor)
+                        editor.unlock();
+                }
                 continue;
             }
             console.error(theme.warn(t('provider.usage')));

package/dist/providers.js

@@ -3,7 +3,7 @@
 //   1. add an entry here (id, label, chat URL prefix, extra config section);
 //   2. add the provider's `<name>-ui.ts` + `<name>-net-capture.ts` +
 //      `<name>-browser.ts` (implementing ChatProvider, see types.ts);
-//   3. register the class in `createBrowser()` in index.ts.
+//   3. register the class in `createProviderBrowser()` in index.ts.
 // Everything else (config enum, /provider validation, sessions tagging, the
 // /doctor row, the {provider} label in operator messages, /chat URL) reads
 // from HERE, so nothing else has to be touched.

package/dist/qwen-browser.js

@@ -27,7 +27,7 @@ import { cleanAnswer, headlessEngineKey, readCachedHeadlessUA, writeCachedHeadle
 import { chatSignalInDom, dumpDomCountsInDom, isElementEnabledInDom, readInputTrimmedTextInDom, readLastAnswerInDom, readPageToastsInDom, readUserAgentInDom, setBusyTitleInDom, clickStopInDom, stopButtonVisibleInDom, } from './browser-dom.js';
 import { probeUiHealth, } from './ui-health.js';
 import { CHAT_URL, CHAT_ID_RE, chatUrl, INPUT_SELECTORS, SEND_SELECTORS, STOP_SELECTORS, STOP_NAME_RE, NEW_CHAT_SELECTOR, MODEL_TRIGGER_SELECTOR, MODELS_URL, CHAT_LIST_URL, chatHistoryUrl, AGE_GATE_MODAL, AGE_GATE_CONTINUE, COOKIE_ACCEPT_RE, ATTACH_SELECTORS, ATTACH_MENU_TRIGGER, ATTACH_MENU_ITEM_RE, THINKING_SELECTOR, THINKING_MODE_RE, FAST_MODE_RE, WEB_SEARCH_MENU_RE, ANSWER_SELECTORS, THINK_CLASS_RE, MESSAGE_CONTAINER_SELECTORS, ASSISTANT_CLASS_RE, CHAT_SIGNAL_NODES_SELECTOR, MARKDOWN_SELECTOR, TOGGLE_SELECTORS, } from './qwen-ui.js';
-import { extractAnswer, extractTokenUsage, isFinishedWithoutAnswer, isRateLimitText, isGuestLimitText, } from './qwen-net-capture.js';
+import { extractAnswer, extractTokenUsage, isFinishedWithoutAnswer, isRateLimitText, isGuestLimitText, isServerBusyText, } from './qwen-net-capture.js';
 // A SEPARATE profile from DeepSeek's ~/.zames/profile. Two persistent Chromium
 // contexts on ONE --user-data-dir cannot coexist (SingletonLock), and keeping
 // Qwen's cookies apart also means switching providers never logs the other
@@ -56,6 +56,8 @@ export class QwenBrowser {
     serverBusyWaitMs;
     maxIncompleteRetries;
     incompleteWaitMs;
+    startWaitMs;
+    sendButtonWaitMs;
     // The Qwen model id sent with each completion request. Empty means "let the
     // site pick" (its own default). Read from config, overridable with /model.
     model;
@@ -82,6 +84,11 @@ export class QwenBrowser {
     // limit for today's usage"). Distinct from _netRateLimited: it cannot be
     // waited out, so ask() fails fast with a "log in" message.
     _netGuestLimit;
+    // True when the completion body carries the server-busy / service-unavailable
+    // notice. Mirrors _netRateLimited: the DOM toast is short-lived, so the RAW
+    // body is the reliable signal. ask() then backs off instead of waiting out
+    // the whole answer deadline.
+    _netServerBusy;
     _netChatId;
     _lastTokenUsage;
     _toggles;
@@ -101,7 +108,7 @@ export class QwenBrowser {
     onSendState;
     onNotice;
     userAgent;
-    constructor({ headless = false, debug = false, channel = null, answerTimeoutMs = 180000, askRetries = 3, stabilityChecks = 2, stabilityDelayMs = 400, minSendIntervalMs = 15000, rateLimitWaitMs = 300000, maxRateLimitRetries = 6, maxServerBusyRetries = 5, serverBusyWaitMs = 3000, maxIncompleteRetries = 4, incompleteWaitMs = 2000, model = '', deepThinking = false, webSearch = true, auth, locale, onAuthSave, userAgent, } = {}) {
+    constructor({ headless = false, debug = false, channel = null, answerTimeoutMs = 180000, askRetries = 3, stabilityChecks = 2, stabilityDelayMs = 400, minSendIntervalMs = 15000, rateLimitWaitMs = 300000, maxRateLimitRetries = 6, maxServerBusyRetries = 5, serverBusyWaitMs = 3000, maxIncompleteRetries = 4, incompleteWaitMs = 2000, startWaitMs = 30000, sendButtonWaitMs = 8000, model = '', deepThinking = false, webSearch = true, auth, locale, onAuthSave, userAgent, } = {}) {
         this.headless = headless;
         this.debug = debug;
         this.channel = channel;
@@ -116,6 +123,8 @@ export class QwenBrowser {
         this.serverBusyWaitMs = serverBusyWaitMs;
         this.maxIncompleteRetries = maxIncompleteRetries;
         this.incompleteWaitMs = incompleteWaitMs;
+        this.startWaitMs = startWaitMs;
+        this.sendButtonWaitMs = sendButtonWaitMs;
         this.model = model;
         this.deepThinking = deepThinking;
         this.webSearch = webSearch;
@@ -138,6 +147,7 @@ export class QwenBrowser {
         this._netNoAnswer = false;
         this._netRateLimited = false;
         this._netGuestLimit = false;
+        this._netServerBusy = false;
         this._netChatId = null;
         this._lastTokenUsage = null;
         this._toggles = { deepThinking, webSearch };
@@ -380,6 +390,12 @@ export class QwenBrowser {
                     this._netRateLimited = true;
                     this._netCapture = '';
                 }
+                // The server-busy notice can arrive with a non-empty (partial) answer
+                // too, so it is checked OUTSIDE the `!extracted` branch as well — the
+                // point is to back off, not to discard a usable answer.
+                if (isServerBusyText(body)) {
+                    this._netServerBusy = true;
+                }
                 this._netCaptureAt = Date.now();
             }
         }
@@ -830,6 +846,10 @@ export class QwenBrowser {
             }, { url: MODELS_URL, auth: this._apiAuth });
             if (res?.error) {
                 this._lastHistoryError = res.error;
+                // Surface the failure: an empty list otherwise looks identical to
+                // "the catalogue is empty", so /model would print "(none)" with no
+                // hint that the API call failed.
+                this._notice(this._t('qwen.model_error', { v: res.error }));
                 return [];
             }
             const data = res?.data || {};
@@ -861,6 +881,7 @@ export class QwenBrowser {
         }
         catch (e) {
             this._lastHistoryError = e.message;
+            this._notice(this._t('qwen.model_error', { v: e.message }));
             return [];
         }
     }
@@ -1038,6 +1059,13 @@ export class QwenBrowser {
     // Pick Auto/Thinking/Fast in the `.qwen-thinking-selector` dropdown. The
     // option labels are localized, so they are matched by a loose regex.
     async _applyThinkingMode() {
+        // Only touch the mode dropdown when the desired state changed since the
+        // last apply (same rationale as _applyWebSearch): opening it on every send
+        // is slow and can steal focus from the send button. A manual flip by the
+        // operator is still honored because we re-read the current label below.
+        const wantMode = this.deepThinking ? 1 : 0;
+        if (this._appliedThinking === wantMode)
+            return;
         try {
             const trigger = this.page.locator(THINKING_SELECTOR).first();
             if ((await trigger.count().catch(() => 0)) === 0)
@@ -1299,7 +1327,7 @@ export class QwenBrowser {
                         if (rateLimitRetries >= this.maxRateLimitRetries)
                             break;
                         rateLimitRetries++;
-                        this._notice(this._t('ds.rate_limit_wait', {
+                        this._notice(this._t('qwen.rate_limit_wait', {
                             min: Math.ceil(this.rateLimitWaitMs / 60000),
                             attempt: rateLimitRetries,
                             max: this.maxRateLimitRetries,
@@ -1307,10 +1335,15 @@ export class QwenBrowser {
                         await this._sleepInterruptible(this.rateLimitWaitMs);
                         continue;
                     }
-                    if (/server busy/i.test(msg)) {
+                    if (e instanceof QwenServerBusyError || /server busy/i.test(msg)) {
                         if (serverBusyRetries >= this.maxServerBusyRetries)
                             break;
                         serverBusyRetries++;
+                        this._notice(this._t('qwen.server_busy_wait', {
+                            sec: Math.ceil(this.serverBusyWaitMs / 1000),
+                            attempt: serverBusyRetries,
+                            max: this.maxServerBusyRetries,
+                        }));
                         await this._sleepInterruptible(this.serverBusyWaitMs);
                         continue;
                     }
@@ -1318,7 +1351,7 @@ export class QwenBrowser {
                         if (incompleteRetries >= this.maxIncompleteRetries)
                             break;
                         incompleteRetries++;
-                        this._notice(theme.warn(this._t('ds.incomplete_retry', {
+                        this._notice(theme.warn(this._t('qwen.incomplete_retry', {
                             attempt: incompleteRetries,
                             max: this.maxIncompleteRetries,
                         })));
@@ -1342,7 +1375,7 @@ export class QwenBrowser {
                             })));
                         }
                     }
-                    this._notice(theme.warn(this._t('ds.ask_retry', {
+                    this._notice(theme.warn(this._t('qwen.ask_retry', {
                         attempt: attempt + 1,
                         max: this.askRetries,
                         error: msg,
@@ -1353,7 +1386,7 @@ export class QwenBrowser {
                     attempt++;
                 }
             }
-            throw new Error(this._t('ds.ask_failed', {
+            throw new Error(this._t('qwen.ask_failed', {
                 max: this.askRetries,
                 error: lastErr?.message || '',
             }));
@@ -1376,7 +1409,7 @@ export class QwenBrowser {
             }
             catch (e) {
                 failed.push({ path: f.path, name: f.name });
-                this._notice(theme.warn(this._t('ds.attach_read_failed', {
+                this._notice(theme.warn(this._t('qwen.attach_read_failed', {
                     name: f.name,
                     error: e.message,
                 })));
@@ -1421,7 +1454,7 @@ export class QwenBrowser {
             }
             catch { }
         }
-        this._notice(this._t('ds.attach_no_input'));
+        this._notice(this._t('qwen.attach_no_input'));
         for (const f of files)
             failed.push({ path: f.path, name: f.name });
         return failed;
@@ -1498,7 +1531,7 @@ export class QwenBrowser {
             catch { }
         }
         if (!input)
-            throw new Error(this._t('ds.input_missing'));
+            throw new Error(this._t('qwen.input_missing'));
         const beforeText = await this._readLastAnswerTextCleanDom().catch(() => '');
         await this._waitForSendSlot(agent);
         if (this._abort)
@@ -1516,6 +1549,7 @@ export class QwenBrowser {
         this._netNoAnswer = false;
         this._netRateLimited = false;
         this._netGuestLimit = false;
+        this._netServerBusy = false;
         this._netBody = '';
         await this._applyToggles();
         if (attachments.length) {
@@ -1523,13 +1557,26 @@ export class QwenBrowser {
             prompt = rewriteFailedAttachments(prompt, failed);
         }
         await this._setInputText(input, prompt);
-        // Send: wait for an ENABLED send button (it is disabled while the input is
-        // empty or an upload is in flight), then click; fall back to Enter. With
-        // attachments the upload can keep the button disabled for a while, so the
-        // window is longer in that case.
-        const sendDeadline = Date.now() + (attachments.length ? 30_000 : 8000);
+        // Send. The input may hold the text WITHOUT the message having been sent
+        // (a real complaint: "text is in the Qwen chat but the send button was not
+        // pressed"). So we do not merely click once — we click AND verify, retrying
+        // through a deadline until the input actually clears (Qwen clears the
+        // textarea the moment it accepts the message). Verification is the ONLY
+        // reliable signal: a disabled button, a menu that stole focus, or a click
+        // that landed on an overlay all leave the text in place.
+        //
+        // We try, in order each round: (1) a click on a VISIBLE, ENABLED send
+        // button, (2) Enter as a fallback. With attachments the upload can keep the
+        // button disabled for a while, so the window is longer in that case.
+        const sendDeadline = Date.now() + (attachments.length ? 30_000 : this.sendButtonWaitMs);
+        const preSendSignal = await this._chatSignal();
         let sent = false;
         while (!sent && Date.now() < sendDeadline) {
+            // (1) the send button, if present/enabled/visible. We remember whether a
+            // click was actually issued: pressing Enter in the SAME round could send
+            // the message a SECOND time if the click already worked but the input
+            // had not cleared yet.
+            let clicked = false;
             for (const sel of SEND_SELECTORS) {
                 const btn = this.page.locator(sel).last();
                 try {
@@ -1543,32 +1590,48 @@ export class QwenBrowser {
                     if (!enabled)
                         continue;
                     await btn.click({ timeout: 1500 });
-                    sent = true;
+                    clicked = true;
                     break;
                 }
                 catch { }
             }
-            if (!sent)
-                await this.page.waitForTimeout(150);
-        }
-        if (!sent)
-            await this.page.keyboard.press('Enter');
-        this._lastSentAt = Date.now();
-        // Verify the send really went out: Qwen clears the textarea when the
-        // message is accepted. If the text is still there, press Enter once more.
-        try {
+            // (2) Enter fallback — ONLY when no send button was clicked this round
+            // (a build that sends solely on Enter, or a missing button). This is
+            // what avoids a double send.
+            if (!clicked) {
+                await this.page.keyboard.press('Enter').catch(() => { });
+            }
+            // VERIFY: the input must clear. Give the app a moment to react. A send
+            // ALSO counts as successful when the page started generating (the chat
+            // signal grew / a Stop button appeared) even if the textarea did not
+            // clear immediately — some builds keep the last message in the box.
             await this.page.waitForTimeout(300);
             const stillThere = await input
                 .evaluate(readInputTrimmedTextInDom)
                 .catch(() => '');
-            if (stillThere) {
-                await this.page.keyboard.press('Enter');
-                this._lastSentAt = Date.now();
+            if (!stillThere) {
+                sent = true;
+                break;
             }
+            const sig = await this._chatSignal().catch(() => preSendSignal);
+            const stopVisible = await this._stopButtonVisible().catch(() => false);
+            if (stopVisible ||
+                sig.nodes > preSendSignal.nodes ||
+                sig.lastLen > preSendSignal.lastLen) {
+                sent = true;
+                break;
+            }
+            await this.page.waitForTimeout(150);
+        }
+        this._lastSentAt = Date.now();
+        if (!sent) {
+            // The text is still in the input after the whole deadline: the message
+            // was NOT sent. Throw so ask() retries the send instead of waiting out
+            // the full answer timeout for a turn that never started.
+            throw new Error(this._t('qwen.send_button_missing'));
         }
-        catch { }
         // Wait for the answer to start, then for it to settle.
-        const startDeadline = Date.now() + 30_000;
+        const startDeadline = Date.now() + this.startWaitMs;
         const startSignal = await this._chatSignal();
         let started = false;
         while (Date.now() < startDeadline) {
@@ -1584,6 +1647,9 @@ export class QwenBrowser {
             if (this._netRateLimited && this._netCaptureAt >= this._lastSentAt) {
                 throw new QwenRateLimitError(this._netBody.slice(0, 300));
             }
+            if (this._netServerBusy && this._netCaptureAt >= this._lastSentAt) {
+                throw new QwenServerBusyError(this._netBody.slice(0, 300));
+            }
             const sig = await this._chatSignal();
             if (sig.nodes > startSignal.nodes || sig.lastLen > startSignal.lastLen) {
                 started = true;
@@ -1615,6 +1681,9 @@ export class QwenBrowser {
             if (this._netRateLimited && this._netCaptureAt >= this._lastSentAt) {
                 throw new QwenRateLimitError(this._netBody.slice(0, 300));
             }
+            if (this._netServerBusy && this._netCaptureAt >= this._lastSentAt) {
+                throw new QwenServerBusyError(this._netBody.slice(0, 300));
+            }
             if (this._netNoAnswer && this._netCaptureAt >= this._lastSentAt) {
                 throw new QwenIncompleteError('finished without answer');
             }
@@ -1642,7 +1711,7 @@ export class QwenBrowser {
         const answer = this._netCapture || last;
         if (answer && answer !== beforeText)
             return answer;
-        throw new Error(this._t('ds.send_no_new_answer'));
+        throw new Error(this._t('qwen.send_no_new_answer'));
     }
 }
 // Qwen-specific error classes so ask() can branch on the retryable families.
@@ -1666,3 +1735,9 @@ class QwenIncompleteError extends Error {
         this.name = 'QwenIncompleteError';
     }
 }
+class QwenServerBusyError extends Error {
+    constructor(detail) {
+        super('server busy: ' + detail);
+        this.name = 'QwenServerBusyError';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.73.0",
+  "version": "2.73.2",
   "description": "Terminal coding agent that drives a real browser to chat with DeepSeek, Qwen and other web LLMs — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
@@ -33,7 +33,10 @@
     "test": "tsx --test test/*.test.ts",
     "test:watch": "tsx --test --watch test/*.test.ts",
     "self-smoke": "tsx scripts/self-smoke.mts",
+    "qwen-smoke": "tsx scripts/qwen-smoke.mts",
     "render-demo": "tsx scripts/render-demo.mts",
+    "render-how": "tsx scripts/render-how-it-works.mts",
+    "render-how": "tsx scripts/render-how-it-works.mts",
     "build:readme": "tsx scripts/build-readme.mts",
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "husky"

package/scripts/qwen-smoke.mts

@@ -0,0 +1,189 @@
+// Qwen (chat.qwen.ai) self-smoke: a REAL isolated QwenBrowser instance against
+// the live site, to catch integration regressions (login, send, answer) that
+// unit tests cannot.
+//
+// Isolation: HOME is pointed at a throwaway dir BEFORE importing any project
+// module (they compute ~/.zames paths at load). The real Qwen profile
+// (~/.zames/qwen-profile) is COPIED read-only into the temp HOME so the
+// browser starts already signed in; the live profile is NEVER opened. The
+// Playwright browser cache is symlinked read-only. Nothing in the operator's
+// ~/.zames is written.
+//
+// Usage:  npx tsx scripts/qwen-smoke.mts [--headed] [--no-reuse-profile]
+// Exit code 0 = all scenarios passed; 2 = login failed (could not start).
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const HEADED = process.argv.includes('--headed')
+const REUSE_PROFILE = !process.argv.includes('--no-reuse-profile')
+const REAL_HOME = os.homedir()
+const PROFILE_SRC = path.join(REAL_HOME, '.zames', 'qwen-profile')
+
+if (!process.env.ZAMES_QWEN_SMOKE_HOME) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'zames-qwen-smoke-'))
+  process.env.HOME = tmp
+  process.env.ZAMES_QWEN_SMOKE_HOME = tmp
+  fs.mkdirSync(path.join(tmp, '.zames'), { recursive: true })
+  fs.mkdirSync(path.join(tmp, '.cache'), { recursive: true })
+  const realCfg = path.join(REAL_HOME, '.zames', 'config.json')
+  if (fs.existsSync(realCfg)) {
+    fs.copyFileSync(realCfg, path.join(tmp, '.zames', 'config.json'))
+  }
+  const realPw = path.join(REAL_HOME, '.cache', 'ms-playwright')
+  if (fs.existsSync(realPw)) {
+    fs.symlinkSync(realPw, path.join(tmp, '.cache', 'ms-playwright'))
+  }
+  if (REUSE_PROFILE && fs.existsSync(PROFILE_SRC)) {
+    fs.cpSync(PROFILE_SRC, path.join(tmp, '.zames', 'qwen-profile'), {
+      recursive: true,
+      filter: (src) => !/^Singleton/.test(path.basename(src)),
+    })
+  }
+}
+const SMOKE_HOME = process.env.ZAMES_QWEN_SMOKE_HOME as string
+
+// --- project modules (dynamic: they read HOME at import) --------------------
+const { QwenBrowser } = await import('../src/qwen-browser.ts')
+const { loadConfig } = await import('../src/config.ts')
+
+const cfg = loadConfig()
+
+interface SmokeResult {
+  name: string
+  ok: boolean
+  note?: string
+}
+const results: SmokeResult[] = []
+let loginFailed = false
+const record = (name: string, ok: boolean, note?: string): void => {
+  results.push({ name, ok, note })
+  console.log((ok ? 'PASS ' : 'FAIL ') + name + (note ? '  — ' + note : ''))
+}
+
+const browser = new QwenBrowser({
+  headless: !HEADED,
+  debug: process.env.ZAMES_QWEN_SMOKE_DEBUG === '1',
+  channel: cfg.browserChannel,
+  auth: cfg.browser.auth,
+  locale: 'ru',
+  minSendIntervalMs: 0,
+  answerTimeoutMs: 180000,
+  webSearch: false,
+  deepThinking: false,
+})
+browser.onNotice = (t: string) => console.log('  [notice] ' + t)
+
+async function main() {
+  console.log(
+    'qwen-smoke: HOME=' +
+      SMOKE_HOME +
+      ' headed=' +
+      HEADED +
+      ' reuse-profile=' +
+      REUSE_PROFILE,
+  )
+  await browser.launch()
+
+  // Bound the login wait so a cold/expired session fails fast with a clear
+  // hint instead of hanging until the caller's tool timeout.
+  const loginPromise = browser.waitForLogin()
+  const timedOut = await Promise.race([
+    loginPromise.then(() => false),
+    new Promise<boolean>((r) => setTimeout(() => r(true), 60000)),
+  ])
+  if (timedOut) {
+    loginFailed = true
+    record('login', false, 'timed out after 60s')
+  } else {
+    const logged = await browser.isLoggedIn().catch(() => false)
+    record('login', logged, logged ? '' : 'not signed in (guest)')
+    if (!logged) loginFailed = true
+  }
+
+  if (!loginFailed) {
+    // 1) new chat + a SIMPLE ask that needs no tools: the model must answer.
+    try {
+      await browser.newChat()
+      const id = await browser.getCurrentChatId()
+      record('newChat', true, 'id=' + (id || '(none)'))
+    } catch (e) {
+      record('newChat', false, (e as Error).message)
+    }
+
+    try {
+      const ans = await browser.ask('Reply with exactly: PONG', {
+        agent: true,
+      })
+      const ok = /PONG/i.test(ans)
+      record('ask:simple', ok, ok ? '' : 'got: ' + ans.slice(0, 80))
+    } catch (e) {
+      record('ask:simple', false, (e as Error).message)
+    }
+
+    // 2) a second send right after the first: guards the send-verify path (the
+    //    "text entered but send button not pressed" regression).
+    try {
+      const ans = await browser.ask('Reply with exactly: PONG2', {
+        agent: true,
+      })
+      const ok = /PONG2/i.test(ans)
+      record('ask:second-send', ok, ok ? '' : 'got: ' + ans.slice(0, 80))
+    } catch (e) {
+      record('ask:second-send', false, (e as Error).message)
+    }
+
+    // 3) model catalogue + token usage (best-effort, non-fatal).
+    try {
+      const models = await browser.listModels()
+      record('listModels', models.length > 0, 'n=' + models.length)
+    } catch (e) {
+      record('listModels', false, (e as Error).message)
+    }
+
+    const usage = browser.getLastTokenUsage()
+    record('tokenUsage', usage !== null, 'usage=' + String(usage))
+
+    // 4) tool-call emission: the agent-loop depends on the model returning a
+    //    parseable JSON tool call. Ask for one explicitly and check the PARSER
+    //    (not the model's prose).
+    try {
+      const { parseToolCall } = await import('../src/answer-parse.ts')
+      const ans = await browser.ask(
+        'Call the Read tool for the file package.json. Reply with EXACTLY one ' +
+          'JSON tool-call object and nothing else: ' +
+          '{"tool":"Read","args":{"path":"..."}}',
+        { agent: true },
+      )
+      const parsed = parseToolCall(ans)
+      const call = Array.isArray(parsed) ? parsed[0] : parsed
+      const ok = !!call && call.tool === 'Read'
+      record('toolCall', ok, ok ? '' : 'got: ' + ans.slice(0, 100))
+    } catch (e) {
+      record('toolCall', false, (e as Error).message)
+    }
+  }
+
+  await browser.close().catch(() => {})
+
+  const failed = results.filter((r) => !r.ok)
+  console.log(
+    '\nqwen-smoke: ' +
+      (results.length - failed.length) +
+      '/' +
+      results.length +
+      ' passed',
+  )
+  if (!process.env.ZAMES_QWEN_SMOKE_KEEP) {
+    fs.rmSync(SMOKE_HOME, { recursive: true, force: true })
+  } else {
+    console.log('kept HOME: ' + SMOKE_HOME)
+  }
+  process.exit(loginFailed ? 2 : failed.length ? 1 : 0)
+}
+
+main().catch((e) => {
+  console.error('qwen-smoke crashed:', (e as Error).message)
+  process.exit(1)
+})

package/scripts/render-how-it-works.mts

@@ -0,0 +1,129 @@
+// Render docs/how-it-works.png — the architecture diagram used in README.md.
+//
+// Why a generator: the README must show BOTH chat backends (DeepSeek and
+// Qwen), not just DeepSeek. A hand-drawn PNG drifts; this renders a fixed
+// HTML page with headless Chromium so the diagram is reproducible and easy to
+// update when a provider is added.
+//
+// Run:  npm run render-how  (tsx scripts/render-how-it-works.mts)
+//
+// Isolation: chromium.launch() uses a THROWAWAY in-memory context, never
+// ~/.zames/profile (see AGENTS.md — never touch the live agent's browser).
+
+import { chromium } from 'playwright'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const out = path.join(root, 'docs', 'how-it-works.png')
+
+const C = {
+  bg: '#23272e',
+  panel: '#2b303a',
+  border: '#3b4250',
+  text: '#cfc9b0',
+  dim: '#8a9bb5',
+  user: '#b4b8d0',
+  accent: '#7fc4f0',
+  ds: '#6f8ed0',
+  qwen: '#6fd0b0',
+  tool: '#c6a97e',
+}
+
+const W = 1300
+const H = 360
+
+const box = (
+  title: string,
+  sub: string,
+  color: string,
+): string =>
+  '<div class="box" style="border-color:' +
+  color +
+  '">' +
+  '<div class="box-t" style="color:' +
+  color +
+  '">' +
+  title +
+  '</div>' +
+  '<div class="box-s">' +
+  sub +
+  '</div></div>'
+
+const html =
+  '<!doctype html><html><head><meta charset="utf-8"><style>' +
+  '@font-face{font-family:ZM;src:local("DejaVu Sans Mono")}' +
+  'html,body{margin:0;padding:0;background:' +
+  C.bg +
+  '}' +
+  'body{font-family:"DejaVu Sans Mono",monospace;color:' +
+  C.text +
+  ';-webkit-font-smoothing:antialiased}' +
+  '.wrap{box-sizing:border-box;width:' +
+  W +
+  'px;height:' +
+  H +
+  'px;padding:26px 30px}' +
+  '.row{display:flex;align-items:center;justify-content:space-between;gap:8px}' +
+  '.box{box-sizing:border-box;border:2px solid;border-radius:10px;padding:14px 16px;' +
+  'background:' +
+  C.panel +
+  ';min-width:150px;text-align:center}' +
+  '.box-t{font-size:18px;font-weight:700;margin-bottom:6px}' +
+  '.box-s{font-size:12px;color:' +
+  C.dim +
+  ';line-height:1.5}' +
+  '.arrow{font-size:26px;color:' +
+  C.dim +
+  '}' +
+  '.flow-label{font-size:12px;color:' +
+  C.dim +
+  ';text-align:center;margin-top:4px}' +
+  '.providers{display:flex;flex-direction:column;gap:10px}' +
+  '.col{display:flex;flex-direction:column;align-items:center;gap:4px}' +
+  '.legend{margin-top:20px;font-size:12px;color:' +
+  C.dim +
+  ';text-align:center}' +
+  '.legend b{color:' +
+  C.text +
+  '}' +
+  '</style></head><body><div class="wrap">' +
+  '<div class="row">' +
+  // left: the operator
+  '<div class="col">' +
+  box('Operator', 'terminal task<br/>+ tool approval', C.user) +
+  '<div class="flow-label">types a task</div>' +
+  '</div>' +
+  '<div class="arrow">&#8594;</div>' +
+  // middle: zames
+  '<div class="col">' +
+  box(
+    'zames',
+    'sandboxed tools<br/>parses tool-calls<br/>runs them locally',
+    C.accent,
+  ) +
+  '<div class="flow-label">system prompt + task</div>' +
+  '</div>' +
+  '<div class="arrow">&#8644;</div>' +
+  // right: the two backends
+  '<div class="providers">' +
+  box('DeepSeek', 'chat.deepseek.com<br/>~/.zames/profile', C.ds) +
+  box('Qwen', 'chat.qwen.ai<br/>~/.zames/qwen-profile', C.qwen) +
+  '</div>' +
+  '</div>' +
+  '<div class="legend">zames drives a <b>real browser</b> over a persistent per-provider profile &mdash; no API key. ' +
+  'Switch live with <b>/provider &lt;deepseek|qwen&gt;</b> (each chat id belongs to one backend).</div>' +
+  '</div></body></html>'
+
+const browser = await chromium.launch({ headless: true })
+try {
+  const page = await browser.newPage({
+    viewport: { width: W, height: H },
+    deviceScaleFactor: 2,
+  })
+  await page.setContent(html, { waitUntil: 'load' })
+  await page.screenshot({ path: out })
+  console.log('wrote', path.relative(root, out))
+} finally {
+  await browser.close()
+}