tg-use 0.1.0__tar.gz

tg_use-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 axisrow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tg_use-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: tg-use
+Version: 0.1.0
+Summary: Руки для агент-харнеса: тестирование Telegram-ботов через web.telegram.org (CLI без LLM)
+Author: axisrow
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/axisrow/tg-use
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: browser-use>=0.13.8
+Dynamic: license-file
+
+# tg-use
+
+tg-use — тестировщик/копировщик Telegram-ботов через web.telegram.org (клиент `/k/`).
+CLI-«руки» + скилл для агент-харнесов: мозг — модель харнеса, CLI обращений к
+внешним моделям не содержит вовсе.
+
+## Два режима работы browser-use
+
+browser-use умеет работать двумя способами, и разница принципиальная:
+
+1. **Browser Harness CLI + скилл — наш путь, рекомендуемый.** Браузер подключается
+   к харнесу (Claude Code, Codex, OpenCode…), и решения принимает модель харнеса.
+   Наш `tg-use.py` — только «руки»: чтение состояния, клики по кнопкам, артефакты,
+   прогон записанных сценариев. Логика «куда кликать дальше» живёт в скилле
+   (`.claude/skills/tg-use/SKILL.md`), а не в коде.
+2. **Встроенный агент `Agent(task=..., llm=...)` со своим LLM-циклом — в этом
+   проекте так не делаем.** Этот режим дублирует мозг харнеса вторым (медленным
+   и ломким) контуром: ключи, endpoint'ы, таймауты, fallback-модели. Был
+   использован в v1 до 2026-09-20 и отвергнут владельцем вместе с z.ai-конфигом.
+
+**Правило: использовать `browser-use skill install`, а не писать своего агента.**
+В CLI нет ни одного обращения к внешней модели — проверяется `test_skeleton.py`.
+
+## Установка
+
+Из клона:
+
+```sh
+pip3 install -r requirements.txt          # в прокси-окружении: env -u ALL_PROXY -u all_proxy pip3 ...
+python3 -m playwright install chromium
+browser-use skill install                 # подключить браузер к харнесу
+```
+
+Из PyPI (Python ≥3.11): `pipx install tg-use` — те же команды без `python3 tg-use.py`:
+`tg-use login`, `tg-use open <@bot>`, `tg-use state`, …; `tg-use skill-install`
+ставит скилл агенту (команды в нём переписываются на `tg-use`).
+
+## Логин
+
+```sh
+python3 tg-use.py login   # откроется окно с QR — отсканируй телефоном один раз
+```
+
+Сессия сохраняется в `~/.tg-use-agent-profile` (= пароль от аккаунта) — повторный
+запуск подхватит её без QR. При первом запуске macOS спросит доступ к «Chromium
+Safe Storage»: вводи пароль входа и жми «Разрешать всегда» — это шифрование
+cookies, без него сессия не переживёт перезапуск.
+
+Browser Harness из коробки цепляется к обычному Chrome с его родным профилем и
+наш изолированный профиль не даёт, поэтому профильный запуск остаётся за CLI:
+`login` держит Chromium на нашем профиле и пишет его адрес в `~/.tg-use-cdp`;
+`state`/`click`/`save`/`test` подключаются к этому живому браузеру. Харнес может
+работать с тем же окном через browser-use (`BU_CDP_URL=$(cat ~/.tg-use-cdp)`).
+
+## Команды (руки; «куда кликать дальше» решает харнес)
+
+| Команда | Что делает |
+|---|---|
+| `tg-use.py login` | headed-браузер с persistent-профилем; адрес → `~/.tg-use-cdp` |
+| `tg-use.py open <@bot>` | открыть чат бота: поиск webk по username + клик по результату, guard по peer-id в hash; без отправок |
+| `tg-use.py state` | JSON: текст последнего сообщения бота + подписи кнопок |
+| `tg-use.py click "<label>"` | нажать inline-кнопку, вернуть новое состояние; отсутствие кнопки/реакции = ошибка (exit 1) |
+| `tg-use.py save [--from id --button label] [--bot @name]` | дописать состояние/ребро в `artifacts/flow.json` + `artifacts/flow.md` (Mermaid) |
+| `tg-use.py test scenario.json` | шаги `{"do": {"send"/"click"}, "expect": {"contains"/"regex"}}` → `artifacts/report.json`; падение = exit 1 |
+
+Дальше — по скиллу `.claude/skills/tg-use/SKILL.md`: малый обход (глубина ≤2,
+до ~5 состояний) и прогон сценариев. Безопасность: темп 2–3 c между действиями,
+только диалоги с ботами, скраб токенов в выводе, PNG не сохраняем.
+
+## Тесты и категории
+
+Граница категорий — цена ошибки. `unit`: offline-скрипты, безопасный дефолт —
+`python3 test_skeleton.py && python3 test_crawl.py && python3 test_hands.py`.
+`state`/`open` — live_read (чтение/открытие чата без отправок); `click`/`save` —
+live_write (обратимые действия в диалоге с ботом); `test`/`login` —
+live_write_danger (необратимая отправка боту / полный доступ к аккаунту).
+Гейты — в `.claude/settings.json`: владелец 2026-09-20 разрешил все подкоманды
+целиком (`Bash(python3 tg-use.py:*)`), категории остались описанием цены ошибки,
+а не спросом харнеса.

tg_use-0.1.0/README.md

@@ -0,0 +1,79 @@
+# tg-use
+
+tg-use — тестировщик/копировщик Telegram-ботов через web.telegram.org (клиент `/k/`).
+CLI-«руки» + скилл для агент-харнесов: мозг — модель харнеса, CLI обращений к
+внешним моделям не содержит вовсе.
+
+## Два режима работы browser-use
+
+browser-use умеет работать двумя способами, и разница принципиальная:
+
+1. **Browser Harness CLI + скилл — наш путь, рекомендуемый.** Браузер подключается
+   к харнесу (Claude Code, Codex, OpenCode…), и решения принимает модель харнеса.
+   Наш `tg-use.py` — только «руки»: чтение состояния, клики по кнопкам, артефакты,
+   прогон записанных сценариев. Логика «куда кликать дальше» живёт в скилле
+   (`.claude/skills/tg-use/SKILL.md`), а не в коде.
+2. **Встроенный агент `Agent(task=..., llm=...)` со своим LLM-циклом — в этом
+   проекте так не делаем.** Этот режим дублирует мозг харнеса вторым (медленным
+   и ломким) контуром: ключи, endpoint'ы, таймауты, fallback-модели. Был
+   использован в v1 до 2026-09-20 и отвергнут владельцем вместе с z.ai-конфигом.
+
+**Правило: использовать `browser-use skill install`, а не писать своего агента.**
+В CLI нет ни одного обращения к внешней модели — проверяется `test_skeleton.py`.
+
+## Установка
+
+Из клона:
+
+```sh
+pip3 install -r requirements.txt          # в прокси-окружении: env -u ALL_PROXY -u all_proxy pip3 ...
+python3 -m playwright install chromium
+browser-use skill install                 # подключить браузер к харнесу
+```
+
+Из PyPI (Python ≥3.11): `pipx install tg-use` — те же команды без `python3 tg-use.py`:
+`tg-use login`, `tg-use open <@bot>`, `tg-use state`, …; `tg-use skill-install`
+ставит скилл агенту (команды в нём переписываются на `tg-use`).
+
+## Логин
+
+```sh
+python3 tg-use.py login   # откроется окно с QR — отсканируй телефоном один раз
+```
+
+Сессия сохраняется в `~/.tg-use-agent-profile` (= пароль от аккаунта) — повторный
+запуск подхватит её без QR. При первом запуске macOS спросит доступ к «Chromium
+Safe Storage»: вводи пароль входа и жми «Разрешать всегда» — это шифрование
+cookies, без него сессия не переживёт перезапуск.
+
+Browser Harness из коробки цепляется к обычному Chrome с его родным профилем и
+наш изолированный профиль не даёт, поэтому профильный запуск остаётся за CLI:
+`login` держит Chromium на нашем профиле и пишет его адрес в `~/.tg-use-cdp`;
+`state`/`click`/`save`/`test` подключаются к этому живому браузеру. Харнес может
+работать с тем же окном через browser-use (`BU_CDP_URL=$(cat ~/.tg-use-cdp)`).
+
+## Команды (руки; «куда кликать дальше» решает харнес)
+
+| Команда | Что делает |
+|---|---|
+| `tg-use.py login` | headed-браузер с persistent-профилем; адрес → `~/.tg-use-cdp` |
+| `tg-use.py open <@bot>` | открыть чат бота: поиск webk по username + клик по результату, guard по peer-id в hash; без отправок |
+| `tg-use.py state` | JSON: текст последнего сообщения бота + подписи кнопок |
+| `tg-use.py click "<label>"` | нажать inline-кнопку, вернуть новое состояние; отсутствие кнопки/реакции = ошибка (exit 1) |
+| `tg-use.py save [--from id --button label] [--bot @name]` | дописать состояние/ребро в `artifacts/flow.json` + `artifacts/flow.md` (Mermaid) |
+| `tg-use.py test scenario.json` | шаги `{"do": {"send"/"click"}, "expect": {"contains"/"regex"}}` → `artifacts/report.json`; падение = exit 1 |
+
+Дальше — по скиллу `.claude/skills/tg-use/SKILL.md`: малый обход (глубина ≤2,
+до ~5 состояний) и прогон сценариев. Безопасность: темп 2–3 c между действиями,
+только диалоги с ботами, скраб токенов в выводе, PNG не сохраняем.
+
+## Тесты и категории
+
+Граница категорий — цена ошибки. `unit`: offline-скрипты, безопасный дефолт —
+`python3 test_skeleton.py && python3 test_crawl.py && python3 test_hands.py`.
+`state`/`open` — live_read (чтение/открытие чата без отправок); `click`/`save` —
+live_write (обратимые действия в диалоге с ботом); `test`/`login` —
+live_write_danger (необратимая отправка боту / полный доступ к аккаунту).
+Гейты — в `.claude/settings.json`: владелец 2026-09-20 разрешил все подкоманды
+целиком (`Bash(python3 tg-use.py:*)`), категории остались описанием цены ошибки,
+а не спросом харнеса.

tg_use-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tg-use"
+dynamic = ["version"]
+description = "Руки для агент-харнеса: тестирование Telegram-ботов через web.telegram.org (CLI без LLM)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<4.0"
+dependencies = ["browser-use>=0.13.8"]
+authors = [{ name = "axisrow" }]
+
+[project.urls]
+Homepage = "https://github.com/axisrow/tg-use"
+
+[project.scripts]
+tg-use = "tg_use:main"
+
+[tool.setuptools]
+packages = ["tg_use"]
+
+[tool.setuptools.package-data]
+tg_use = ["SKILL.md"]
+
+[tool.setuptools.dynamic]
+version = { attr = "tg_use.__version__" }

tg_use-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tg_use-0.1.0/tg_use/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: tg-use
+description: Снятие структуры меню Telegram-ботов и прогон сценариев через web.telegram.org CLI tg-use.py (руки) — мозг (ты) решает, куда кликать.
+---
+
+# tg-use: малый обход бота и сценарий
+
+Браузерная механика — в скилле `browser-use` (`browser-use skill install`); этот
+скилл — только профильный нюанс и процедура. В CLI нет модели: решения принимаешь
+ты, `tg-use.py` — только руки (login/open/state/click/save/test).
+
+## Подготовка
+
+1. `python3 tg-use.py login` — headed-браузер с профилем `~/.tg-use-agent-profile`
+   (= пароль от аккаунта; не коммитить, не чистить). Адрес живого браузера он
+   пишет в `~/.tg-use-cdp`; окно не закрывать до конца работы. Повторный запуск
+   QR не требует. Хочешь работать с этим браузером сам через browser-use —
+   подключайся по `BU_CDP_URL=$(cat ~/.tg-use-cdp)`, это тот же Chromium.
+2. `python3 tg-use.py open @bot` — CLI сам находит чат по username через поиск
+   webk и открывает его, проверяя peer-id (guard от чужого чата); ничего не
+   отправляет. Руками в браузере ничего не открываем. Сразу после `login`
+   поиск webk бывает глух — CLI сам будит поле настоящей клавишей (#27);
+   поиск не ответил — это неисправность: сообщи владельцу, не жди и не повторяй.
+3. `python3 tg-use.py state` — убедись, что чат отвечает. Если бот ещё не
+   стартовал (пусто), `/start` уходит одностадийным сценарием — `test` с шагом
+   `{"do": {"send": "/start"}}`.
+
+## Малый обход (глубина ≤2, до ~5 состояний)
+
+Цикл, каждый шаг — вызов CLI; темп задаёшь ты: пауза 2–3 c между вызовами.
+Ошибка «страница webk не смонтирована» — повтори `open @bot`.
+
+1. `python3 tg-use.py state` → JSON `{id, text, buttons, reply_buttons}` (reply_buttons —
+   нижняя reply-клавиатура бота; click жмёт и её кнопки).
+2. `python3 tg-use.py save --bot @bot` — первое состояние (корень); дальше
+   `save --from <id> --button "<label>"`.
+3. Выбери кнопку сам; лучше
+   не «API Token» (токен будет замазан скрабом). `python3 tg-use.py click "<label>"` —
+   вернёт новое состояние; ошибка = битое ребро, пометь и не повторяй.
+4. Новое состояние → `save --from <id_родителя> --button "<label>"`.
+5. Вложенные уровни: из нового состояния один шаг вглубь (итого ≤2 от корня),
+   не более ~5 состояний. Достаточно для карты меню.
+
+Артефакты: `artifacts/flow.json` + `artifacts/flow.md` (Mermaid) — CLI
+перезаписывает их после каждого save, прерванный обход оставляет валидный след.
+
+## Сценарий
+
+Сохрани `artifacts/<bot>.scenario.json`:
+`[{"do": {"send": "/mybots"} | {"click": "<label>"}, "expect": {"contains"|"regex": "..."}}]`
+и прогони: `python3 tg-use.py test artifacts/<bot>.scenario.json` → `artifacts/report.json`
+(pass/fail по шагам + латентность), падение = exit 1. `send` шлёт любой текст
+в диалог бота, не только `/`-команды — свободный ввод опросников проходит им.
+
+## Правила безопасности (не упрощать)
+
+- Только диалоги с ботами; ни одного сообщения живым людям.
+- PNG не снимаем; текст артефактов и так проходит скраб токенов.
+- Деструктивное не выбирай: любое решение — твоё, в моменте; CLI ничего не запрещает.

tg_use-0.1.0/tg_use/__init__.py

@@ -0,0 +1,632 @@
+"""tg-use — руки для агент-харнеса: тестировщик Telegram-ботов через web.telegram.org (клиент /k/).
+
+В CLI нет ни одного обращения к внешней модели: мозг — модель харнеса, который
+запускает этот CLI (README: два режима browser-use; наш — Browser Harness CLI +
+скилл). browser-use используется как библиотека браузера (BrowserSession):
+навигация, ожидания и клики — его зона. Встроенный агент со своим циклом не
+используется — обход и выбор следующего шага делает харнес (см. SKILL.md).
+
+Безопасность: темп 2–3 c между действиями задаёт харнес между вызовами CLI;
+только диалоги с ботами; скраб токенов в каждом выводе;
+~/.tg-use-agent-profile = пароль (полный доступ к аккаунту).
+"""
+
+__version__ = '0.1.0'
+
+import os
+
+import argparse
+import asyncio
+import hashlib
+import json
+import logging
+import re
+import time
+import urllib.request
+
+from browser_use.browser import BrowserSession
+
+logging.getLogger('browser_use').setLevel(logging.WARNING)  # event-логи библиотеки — не наш вывод
+
+TG_URL = 'https://web.telegram.org/k/'
+PROFILE = os.path.expanduser('~/.tg-use-agent-profile')  # = пароль: полный доступ к аккаунту
+CDP_FILE = os.path.expanduser('~/.tg-use-cdp')  # login пишет сюда адрес живого браузера
+ART = 'artifacts'  # артефакты: flow.json, flow.md, report.json
+POLL = 2.5    # темп 2–3 c между действиями в чате
+WAIT = 12.0   # потолок ожидания реакции бота после клика/отправки
+OPEN_POLL = 2.0  # пауза между пробами монтирования webk в wait_open
+
+JS_STATE = '''() => {
+  // reply-клавиатура — нижняя панель .reply-keyboard: кнопки там те же
+  // button.reply-markup-button (tweb replyKeyboard.tsx). Панель висит в DOM
+  // постоянно (display:none без клавиатуры, кнопки остаются после закрытия) —
+  // offsetParent берёт только живую видимую панель
+  const reply = [...document.querySelectorAll('.reply-keyboard button.reply-markup-button')]
+    .filter(b => b.offsetParent !== null)
+    .map(b => (b.querySelector('.reply-markup-button-text') || b).innerText.trim());
+  const bubbles = [...document.querySelectorAll('.bubble.is-in')];
+  const last = bubbles[bubbles.length - 1];
+  if (!last) return {text: '', buttons: [], reply_buttons: reply,
+                     bodyLen: document.body ? document.body.innerText.length : 0};
+  const t = last.querySelector('.translatable-message') || last.querySelector('.message');
+  const buttons = [...last.querySelectorAll('button.reply-markup-button')]
+    .map(b => (b.querySelector('.reply-markup-button-text') || b).innerText.trim());
+  return {text: (t ? t.innerText : '').trim(), buttons, reply_buttons: reply, n: bubbles.length};
+}'''
+
+# клик той же пробой, что нашла кнопку: между поиском и кликом DOM не пере-запрашивается,
+# так что бот не успеет переписать сообщение и увести клик в чужую кнопку
+JS_CLICK_BUTTON = '''(label) => {
+  const bubbles = [...document.querySelectorAll('.bubble.is-in')];
+  const last = bubbles[bubbles.length - 1];
+  const byLabel = b => (b.querySelector('.reply-markup-button-text') || b).innerText.trim() === label;
+  const btn = (last && [...last.querySelectorAll('button.reply-markup-button')].find(byLabel))
+    // reply-клавиатура: та же проба без пере-запроса DOM; offsetParent отсекает
+    // панель-двойник display:none (кнопки в ней остаются после закрытия)
+    || [...document.querySelectorAll('.reply-keyboard button.reply-markup-button')]
+         .filter(b => b.offsetParent !== null).find(byLabel);
+  if (!btn) return false;
+  btn.scrollIntoView({block: 'center'});
+  for (const type of ['mousedown', 'mouseup', 'click']) {
+    btn.dispatchEvent(new MouseEvent(type, {bubbles: true, cancelable: true, view: window}));
+  }
+  return true;
+}'''
+
+JS_TYPE = '''(text) => {
+  const field = document.querySelector('.input-message-input');
+  if (!field) return 'no-field';
+  field.focus();
+  return 'typed:' + String(document.execCommand('insertText', false, text));
+}'''
+
+# reply-клавиатура webk свёрнута по умолчанию: кнопки попадают в DOM только после
+# клика по тумблеру у поля ввода (наблюдено живьём: drwebbot, manybot)
+JS_TOGGLE_REPLY = '''() => {
+  if (document.querySelector('.reply-keyboard')) return 'open';
+  const t = document.querySelector('.btn-icon.toggle-reply-markup');
+  if (!t) return 'no-toggle';
+  for (const type of ['mousedown', 'mouseup', 'click']) {
+    t.dispatchEvent(new MouseEvent(type, {bubbles: true, cancelable: true, view: window}));
+  }
+  return 'toggled';
+}'''
+
+# панель reply-клавиатуры переживает смену чата: после open клик схлопывает
+# пережитую, read_state развернёт уже для нового чата (иначе чужие reply_buttons —
+# дефект найден живой приёмкой #31: в чате drwebbot светились кнопки manybot)
+JS_COLLAPSE_REPLY = '''() => {
+  const t = document.querySelector('.btn-icon.toggle-reply-markup');
+  if (!t) return 'no-toggle';
+  for (const type of ['mousedown', 'mouseup', 'click']) {
+    t.dispatchEvent(new MouseEvent(type, {bubbles: true, cancelable: true, view: window}));
+  }
+  return 'toggled';
+}'''
+
+
+def scrub(text: str) -> str:
+    """Затереть секреты (токены ботов вида 1234567890:AA...) перед выводом/записью в артефакты."""
+    # без хвостового \b: если токен кончается на -/_, границы слова нет и 1–2 символа остались бы видимыми
+    return re.sub(r'\b\d{8,12}:[A-Za-z0-9_-]{30,}', '[REDACTED]', text)
+
+
+def esc(s: str, limit: int = 40) -> str:
+    """Первая строка строки, обрезанная и безопасная для кавычек Mermaid."""
+    return s.splitlines()[0][:limit].replace('"', "'") if s else '(нет текста)'
+
+
+def state_key(st: dict) -> str:
+    """Ключ дедупа состояния: sha1(текст + отсортированные подписи кнопок)."""
+    return hashlib.sha1((st['text'] + str(sorted(st['buttons']))).encode()).hexdigest()
+
+
+def reaction_key(st: dict) -> str:
+    """Ключ пробы состояния (текст + кнопки + n): для сравнения двух подряд опросов.
+    Сам по себе реакцией НЕ считается: список бабблов виртуализирован и n гуляет без бота."""
+    return hashlib.sha1((str(st.get('n', 0)) + st['text'] + str(sorted(st['buttons']))).encode()).hexdigest()
+
+
+def reaction_seen(st: dict, before: dict, prev_rk: str) -> bool:
+    """Реакция бота на действие: сменились текст/кнопки, ИЛИ вырос n — но рост верим
+    только после двух подряд одинаковых проб (догрузка истории меняет n без действия бота).
+    Граница эвристики: если виртуализация сдула список ниже before.n, дубль бота может
+    не дотянуть до before.n — таймаут (FAIL); ложных реакций это не даёт никогда."""
+    if state_key(st) != state_key(before):
+        return True
+    return bool(prev_rk) and st.get('n', 0) > before.get('n', 0) and reaction_key(st) == prev_rk
+
+
+def check_expect(text: str, expect: dict | None) -> tuple[bool, str]:
+    """Ожидания шага против текста последнего сообщения бота: contains и/или regex."""
+    for kind, pat in (expect or {}).items():
+        if kind not in ('contains', 'regex'):  # опечатка в сценарии = падение, не ложный PASS
+            return False, f'неизвестный expect: {kind!r} (умею contains/regex)'
+        if kind == 'contains' and pat not in text:
+            return False, f'в тексте нет «{pat}»'
+        if kind == 'regex' and not re.search(pat, text):
+            return False, f'в тексте нет /{pat}/'
+    return True, ''
+
+
+def write_artifacts(flow: dict) -> None:
+    """flow.json + flow.md (Mermaid); перезаписывается целиком после каждого save."""
+    os.makedirs(ART, exist_ok=True)
+    with open(os.path.join(ART, 'flow.json'), 'w') as f:
+        json.dump(flow, f, ensure_ascii=False, indent=2)
+    lines = ['flowchart TD']
+    for st in flow['states']:
+        lines.append(f'    {st["id"]}["{esc(st["text"])}"]')
+    for e in flow['edges']:
+        lines.append(f'    {e["from"]} -->|"{esc(e["button"], 25)}"| {e["to"]}')
+    with open(os.path.join(ART, 'flow.md'), 'w') as f:
+        f.write('# flow\n\n```mermaid\n' + '\n'.join(lines) + '\n```\n')
+
+
+def install_skill(repo_dir: str, home: str) -> str:
+    """Поставить скилл tg-use агенту: копия SKILL.md в ~/.claude/skills/tg-use/ с
+    командами под этот способ установки — репо: абсолютный путь к CLI рядом,
+    pip-пакет: консольный скрипт tg-use. → путь установки (переустанавливай
+    после обновлений)."""
+    src = os.path.join(repo_dir, '.claude', 'skills', 'tg-use', 'SKILL.md')
+    if os.path.exists(src):  # репо: CLI лежит рядом — команды на абсолютный путь
+        with open(src) as f:
+            text = f.read()
+        text = text.replace('python3 tg-use.py', f'python3 {os.path.join(repo_dir, "tg-use.py")}')
+    else:  # пакет (pip install): SKILL.md внутри пакета, CLI — скрипт tg-use на PATH
+        with open(os.path.join(repo_dir, 'SKILL.md')) as f:
+            text = f.read()
+        text = text.replace('python3 tg-use.py', 'tg-use')
+    dst_dir = os.path.join(home, '.claude', 'skills', 'tg-use')
+    os.makedirs(dst_dir, exist_ok=True)
+    dst = os.path.join(dst_dir, 'SKILL.md')
+    with open(dst, 'w') as f:
+        f.write(text)
+    return dst
+
+
+def cdp_alive() -> str:
+    """Адрес живого браузера из CDP_FILE, если тот отвечает по HTTP, иначе ''."""
+    try:
+        with open(CDP_FILE) as f:
+            cdp = f.read().strip()
+    except OSError:
+        return ''
+    base = cdp.split('/devtools')[0].replace('ws', 'http', 1)
+    try:
+        with urllib.request.urlopen(base + '/json/version', timeout=3) as r:
+            r.read()
+    except Exception:  # файл протух или браузер умер
+        return ''
+    return cdp
+
+
+async def connect() -> BrowserSession:
+    """Подключиться к браузеру, оставленному login (адрес в ~/.tg-use-cdp)."""
+    try:
+        with open(CDP_FILE) as f:
+            cdp = f.read().strip()
+    except FileNotFoundError:
+        raise SystemExit('нет живого браузера: сначала python3 tg-use.py login')
+    browser = BrowserSession(cdp_url=cdp)
+    try:
+        await browser.start()
+    except Exception as e:
+        raise SystemExit(f'браузер {cdp} не отвечает ({type(e).__name__}: {e}); перезапусти login')
+    return browser
+
+
+async def ensure_reply_keyboard(page) -> None:
+    """Развернуть свёрнутую webk reply-клавиатуру, чтобы state/click видели кнопки;
+    панель уже открыта или тумблера нет — no-op."""
+    if (await page.evaluate(JS_TOGGLE_REPLY)) == 'toggled':
+        await asyncio.sleep(OPEN_POLL)  # панель монтируется асинхронно
+
+
+async def read_state(page) -> dict:
+    """Текст последнего сообщения бота + подписи кнопок (из живого чата).
+    Несмонтированная страница ≠ пустой чат: честная ошибка вместо «бот молчит»."""
+    await ensure_reply_keyboard(page)
+    st = json.loads(await page.evaluate(JS_STATE))
+    if not (st.get('bodyLen') or st.get('n')):  # нет сообщений И нет body → UI не смонтирован
+        raise RuntimeError('страница webk не смонтирована (воркеры залипли?) — оживи: open @bot')
+    return st
+
+
+async def wait_reaction(page, before: dict) -> dict:
+    """Опрашивать состояние, пока бот не среагирует (reaction_seen); тишина — ошибка ребра."""
+    deadline = time.monotonic() + WAIT
+    prev_rk = ''
+    while True:
+        await asyncio.sleep(POLL)
+        st = await read_state(page)
+        if reaction_seen(st, before, prev_rk):
+            return st
+        prev_rk = reaction_key(st)
+        if time.monotonic() > deadline:
+            raise RuntimeError('реакции бота не последовало (состояние не изменилось)')
+
+
+async def do_click(page, label: str) -> dict:
+    """Нажать кнопку по подписи и вернуть новое состояние; промах — ошибка ребра."""
+    before = await read_state(page)
+    # evaluate питонизирует голые булевы (JS true → 'True'), это не JSON — json.loads падает
+    if (await page.evaluate(JS_CLICK_BUTTON, label)) != 'True':
+        raise RuntimeError(f'кнопки «{label}» нет под последним сообщением и на reply-клавиатуре')
+    return await wait_reaction(page, before)
+
+
+async def do_send(page, text: str) -> dict:
+    """Отправить текст или команду в поле ввода и вернуть новое состояние."""
+    before = await read_state(page)
+    typed = await page.evaluate(JS_TYPE, text)
+    if typed != 'typed:true':
+        raise RuntimeError(f'не удалось ввести «{text}» (поле ввода: {typed or "нет ответа"})')
+    await page.press('Enter')
+    return await wait_reaction(page, before)
+
+
+def shown(st: dict) -> dict:
+    """Состояние для вывода/артефактов: скраб токенов + короткий id."""
+    st = dict(st, text=scrub(st['text']))
+    return dict(st, id=state_key(st)[:8])
+
+
+async def cmd_login() -> None:
+    """Headed-браузер с persistent-профилем; адрес живого браузера — в ~/.tg-use-cdp.
+    Повторный login к живому Chromium подключается, а не запускает второй: второй на том
+    же профиле молча пересоздаёт браузер в пустом temp-профиле (SingletonLock) — сессия
+    терялась при напечатанном «Сессия сохранена»."""
+    alive = cdp_alive()
+    if alive:
+        print(f'живой Chromium уже работает ({alive}); второй не запускаю — переиспользую его.')
+        browser = await connect()
+    else:
+        # ponytail: зомби-браузер без CDP-файла не ловим — после kill() в finally такие
+        # не остаются; поймать руками удалённый файл при живом окне можно только так
+        if os.path.exists(CDP_FILE):
+            os.remove(CDP_FILE)  # протухший адрес мёртвого браузера только путает
+        browser = BrowserSession(user_data_dir=PROFILE, headless=False)
+        await browser.start()
+    try:
+        page = await browser.must_get_current_page()
+        await page.goto(TG_URL)
+        if not browser.cdp_url:  # явная проверка вместо assert: не отключается python -O
+            raise RuntimeError('браузер не отдал CDP-адрес после старта')
+        with open(CDP_FILE, 'w') as f:
+            f.write(browser.cdp_url)
+        print(f'браузер {browser.cdp_url} — адрес записан в {CDP_FILE}; окно не закрывать до конца работы.')
+        try:
+            input(
+                'Если QR — отсканируй телефоном (Telegram → Настройки → Устройства → '
+                'Привязать устройство); если список чатов — сессия уже живая. Enter, когда закончишь. '
+            )
+        except EOFError:  # запущено без tty: окно держится открытым до остановки процесса
+            print('stdin закрыт: окно держится открытым; останови процесс (Ctrl+C/kill), когда закончишь.')
+            await asyncio.Event().wait()
+    finally:
+        if alive:
+            await browser.stop()  # ранее запущенный Chromium остаётся живым, адрес в файле
+        else:
+            await browser.kill()  # stop() оставил бы зомби-браузер без CDP-файла: повторный
+            if os.path.exists(CDP_FILE):
+                os.remove(CDP_FILE)  # login считал бы, что браузера нет, хотя он жив
+    if alive:
+        print(f'браузер остаётся живым; подкоманды подключатся через {CDP_FILE}.')
+    else:
+        print(f'Сессия сохранена в {PROFILE}; следующий запуск подхватит её без QR.')
+
+
+# guard по location.hash: webk пишет туда peerId открытого чата (#8602734479),
+# а .chat-info показывает display name — с username не совпадает (BotFather — редкое совпадение)
+JS_OPEN_INFO = '''() => {
+  const el = document.querySelector('.chat-info');  // верхняя плашка открытого чата
+  return {hash: location.hash,
+          title: el ? el.innerText.trim().split('\\n')[0] : '',
+          bodyLen: document.body ? document.body.innerText.length : 0};  // 0 = не смонтирован
+}'''
+
+# поиск: панель может быть свёрнута (querySelector хватает скрытого поля-двойника) —
+# берём только видимое поле; если панель закрыта, открывает триггер. После вставки
+# webk реагирует только на input-событие, само значение поля не триггерит выдачу
+# (проверено живьём: текст в поле есть, список не фильтруется); явный диспетч
+# дублирует native input от execCommand — для поискового поля безвредно (дебаунс).
+JS_OPEN_SEARCH = '''(query) => {
+  const fields = [...document.querySelectorAll('.input-search-input')]
+    .filter(e => e.offsetParent !== null);
+  if (!fields.length) return 0;
+  fields[0].focus();
+  fields[0].value = '';  // без очистки старый запрос глушит новый ввод
+  // хвостовой пробел — жертва будки: Backspace в cmd_open стирает только его,
+  // в поле остаётся полный query; без него будка съедает последний символ запроса
+  document.execCommand('insertText', false, query + ' ');
+  fields[0].dispatchEvent(new InputEvent('input', {bubbles: true}));
+  return 1;
+}'''
+
+JS_SEARCH_TRIGGER = '''() => {
+  const t = document.querySelector('.sidebar-header-search-trigger');
+  if (t) t.click();
+}'''
+
+# строка результата поиска: локальные совпадения — .chatlist-chat, глобальный поиск
+# (бот вне диалогов) — a.rp.row; у обоих есть data-peer-id, а текст содержит display
+# name (Dr.Web | @DrWebBot), не @username. Сначала строка с точным @username в тексте
+# (lookahead отсекает @GameBotNews при поиске gamebot), фолбэк — нормализованная
+# подстрока (не-буквоцифры в мусор) для строк без username в тексте; needle проходит
+# [A-Za-z0-9_] в cmd_open — метасимволов regex в нём нет. Полный набор
+# mousedown/mouseup/click — голый el.click() строку не открывает
+JS_CLICK_FOUND = '''(needle) => {
+  const norm = (s) => (s || '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const rows = [...document.querySelectorAll('a.rp.row, .chatlist-chat')]
+    .filter(e => e.offsetParent !== null);
+  const exact = new RegExp('@' + needle.toLowerCase() + '(?![a-z0-9_])');
+  const el = rows.find(e => exact.test(e.innerText.toLowerCase()))
+          || rows.find(e => norm(e.innerText).includes(norm(needle)));
+  if (!el) return '';
+  const peer = el.getAttribute('data-peer-id') || (el.getAttribute('href') || '').slice(1);
+  for (const type of ['mousedown', 'mouseup', 'click']) {
+    el.dispatchEvent(new MouseEvent(type, {bubbles: true, cancelable: true, view: window}));
+  }
+  return peer;
+}'''
+
+
+def kill_webk_workers(base: str) -> tuple[int, int]:
+    """Убить shared-воркеры webk по CDP HTTP-базе (например http://127.0.0.1:9222).
+    Их залипание = вечная загрузка вкладки; /json — единственная дверь к worker-таргетам.
+    Ответ /json/close контролируем живьём (200 + 'Target is closing'): если для
+    worker-таргета close не сработал — честная деградация вместо молчаливого «успеха»,
+    revive держится и на reload, но счёт закрытых в отчёте правдивый.
+    ponytail: причина залипания не выяснена; если webk починят — просто удалить вызов.
+    Глубокая дверь (WS к worker-таргету) не нужна, пока revive спасается reload'ом."""
+    try:
+        with urllib.request.urlopen(base + '/json/list', timeout=5) as r:
+            targets = json.load(r)
+        ids = [t['id'] for t in targets
+               if t.get('type') == 'shared_worker' and 'web.telegram.org' in t.get('url', '')]
+    except Exception as e:  # браузер висит — CDP HTTP может не ответить: чистый выход без traceback
+        raise SystemExit(f'не удалось убить воркеры webk через {base} ({type(e).__name__}: {e}); '
+                         f'ничего не отправлено')
+    closed = 0
+    for i in ids:
+        try:
+            with urllib.request.urlopen(f'{base}/json/close/{i}', timeout=5) as r:
+                if r.status == 200 and 'closing' in r.read().decode('utf-8', 'replace').lower():
+                    closed += 1
+        except Exception:  # отказ отдельного close не валит revive — остаётся reload; счёт честный
+            pass
+    return closed, len(ids)
+
+
+async def wait_open(page, tries: int, want: tuple = ()) -> dict:
+    """Смонтированность UI; при want — ждать hash из want (чат открыт)."""
+    wants = tuple(w.lower() for w in want)
+    st = {}
+    for _ in range(tries):
+        st = json.loads(await page.evaluate(JS_OPEN_INFO))
+        if st['bodyLen'] and (not wants or st['hash'].lower() in wants):
+            return st
+        await asyncio.sleep(OPEN_POLL)
+    return st
+
+
+async def cmd_open(bot: str) -> None:
+    """Открыть чат бота в живом браузере: hash-роутинг webk (#@username) + guard «webk съел хэш»; без отправок."""
+    name = bot.lstrip('@')
+    if not re.fullmatch(r'[A-Za-z0-9_]{4,64}', name):  # формат для UX; в JS имя идёт параметром
+        raise SystemExit(f'{bot!r}: жду username вида @name (латиница, цифры, _)')
+    browser = await connect()
+    try:
+        page = await browser.must_get_current_page()
+        url = await page.evaluate('() => location.href')
+        if not url.startswith(TG_URL):
+            # пустая/чужая вкладка: полный переход, руками ничего не набираем
+            await page.goto(TG_URL)
+        if not (await wait_open(page, 15))['bodyLen']:  # медленный старт — норма: до ~30 c
+            browser, page = await revive_page(browser)  # воркеры webk залипли — оживляем
+        # локальный поиск — путь username → чат; результат даёт data-peer-id для верификации
+        if not json.loads(await page.evaluate(JS_OPEN_SEARCH, name)):
+            await page.evaluate(JS_SEARCH_TRIGGER)  # панель поиска свёрнута — открыть кликом
+            await asyncio.sleep(OPEN_POLL)
+            if not json.loads(await page.evaluate(JS_OPEN_SEARCH, name)):
+                raise SystemExit('нет поля поиска webk; ничего не отправлено')
+        await page.press('Backspace')  # будка: webk после старта глух к синтетике
+        # (наблюдено 2026-09-24): настоящая клавиша CDP будит поле input-событием
+        # от удаления последнего символа; жертва будки — хвостовой пробел из
+        # JS_OPEN_SEARCH, в поле остаётся полный query, не найдётся — exit 1
+        peer = ''
+        for _ in range(10):  # ~20 c: индекс/рендер результатов
+            peer = (await page.evaluate(JS_CLICK_FOUND, name.lower())) or ''
+            if peer:
+                break
+            await asyncio.sleep(OPEN_POLL)
+        if not peer:
+            raise SystemExit(f'чат {bot} не найден через поиск webk по username; '
+                             f'ничего не отправлено')
+        # tweb переписывает hash на #peerId (у ботов #<минус>peerId) или #@username
+        wants = ('#' + peer, '#-' + peer, '#@' + name.lower())
+        await wait_open(page, 10, want=wants)
+        await asyncio.sleep(OPEN_POLL)  # дать плашке чата устаканиться после закрытия поиска
+        st = json.loads(await page.evaluate(JS_OPEN_INFO))
+        await page.evaluate(JS_COLLAPSE_REPLY)  # пережитая панель: чужие reply_buttons
+    finally:
+        await browser.stop()
+    if not (st['bodyLen'] and st['hash'].lower() in wants):
+        raise SystemExit(f'чат {bot} не открылся (hash: {st["hash"] or "пусто"}, '
+                         f'заголовок: {st["title"] or "пусто"}); ничего не отправлено')
+    print(json.dumps({'opened': bot, 'title': st['title'], 'hash': st['hash']}, ensure_ascii=False))
+
+
+async def revive_page(browser) -> tuple:
+    """Оживить залипшую страницу: kill воркеров при отключённом клиенте + reload фреш-сессией.
+    Сессия, пережившая залипание, отваливается от таргета и молча не делает reload."""
+    await browser.stop()
+    base = (browser.cdp_url or '').split('/devtools')[0].replace('ws', 'http', 1)
+    closed, total = kill_webk_workers(base)
+    browser = await connect()
+    try:  # SystemExit не Exception: глотаем всё, но фреш-сессию останавливаем и перебрасываем
+        page = await browser.must_get_current_page()
+        await page.reload()
+        if not (await wait_open(page, 15))['bodyLen']:  # перемонтаж занимает ~5 c — ждём честно
+            raise SystemExit(f'webk не ожил даже после kill {closed}/{total} воркеров + '
+                             f'перезапуска сессии')
+        return browser, page
+    except BaseException:
+        await browser.stop()
+        raise
+
+
+async def live_page() -> tuple:
+    """Подключиться к живому браузеру; залипшую страницу оживить на месте. → (browser, page)."""
+    browser = await connect()
+    page = await browser.must_get_current_page()
+    # ponytail: порог 8 проб ≈ 16 c — компромисс: живой медленный старт (норма до ~30 c)
+    # чаще переживает, а мёртвую вкладку не тянем полминуты; убитые живые начнутся — поднять до 15
+    if (await wait_open(page, 8))['bodyLen']:
+        return browser, page
+    return await revive_page(browser)
+
+
+async def cmd_state() -> None:
+    browser, page = await live_page()
+    try:
+        print(json.dumps(shown(await read_state(page)), ensure_ascii=False, indent=2))
+    finally:
+        await browser.stop()
+
+
+async def cmd_click(label: str) -> None:
+    browser, page = await live_page()
+    try:
+        st = shown(await do_click(page, label))
+        print(f'клик «{label}» →', flush=True)
+        print(json.dumps(st, ensure_ascii=False, indent=2))
+    finally:
+        await browser.stop()
+
+
+async def cmd_save(from_id: str, button: str, bot: str) -> None:
+    """Дописать текущее состояние (и ребро from --button, если задано) в flow.json/flow.md."""
+    if button and not from_id:  # иначе кнопка потерялась бы молча
+        raise SystemExit('--button без --from: ребро некуда прикрепить')
+    try:
+        with open(os.path.join(ART, 'flow.json')) as f:
+            flow = json.load(f)
+    except FileNotFoundError:
+        flow = {'bot': bot, 'states': [], 'edges': []}
+    except json.JSONDecodeError as e:  # битый flow = чистый отказ, не traceback
+        raise SystemExit(f'битый {ART}/flow.json: {e}')
+    if from_id and from_id[:8] not in {s['id'] for s in flow['states']}:
+        # опечатка в id = висячее ребро и битая ссылка в Mermaid; проверяем до подключения к браузеру
+        raise SystemExit(f'--from {from_id[:8]}: нет такого состояния в {ART}/flow.json')
+    browser, page = await live_page()
+    try:
+        st = shown(await read_state(page))
+    finally:
+        await browser.stop()
+    new = st['id'] not in {s['id'] for s in flow['states']}
+    if new:
+        flow['states'].append({k: st[k] for k in ('id', 'text', 'buttons')})
+    if from_id:
+        edge = {'from': from_id[:8], 'to': st['id'], 'button': button}
+        if edge not in flow['edges']:
+            flow['edges'].append(edge)
+    write_artifacts(flow)
+    print(json.dumps({'id': st['id'], 'new': new, 'states': len(flow['states']),
+                      'edges': len(flow['edges'])}, ensure_ascii=False))
+
+
+async def cmd_test(scenario_path: str) -> None:
+    """Прогнать сценарий [{do, expect}] → artifacts/report.json; падение = exit 1."""
+    try:
+        with open(scenario_path) as f:
+            steps = json.load(f)
+    except OSError as e:
+        raise SystemExit(f'не удалось открыть {scenario_path}: {e}')
+    except json.JSONDecodeError as e:
+        raise SystemExit(f'битый {scenario_path}: {e}')
+    if not isinstance(steps, list) or not steps:  # пустой сценарий — не PASS за 0 шагов
+        raise SystemExit('сценарий: жду непустой список шагов [{"do": ..., "expect": ...}]')
+    for i, step in enumerate(steps):  # кривой сценарий = ошибка до подключения к браузеру
+        do = step.get('do', {}) if isinstance(step, dict) else None
+        if not isinstance(do, dict) or not ({'click', 'send'} >= set(do)):
+            raise SystemExit(f'шаг {i + 1}: жду {{"do": {{"click"/"send": ...}}}} или {{"do": {{}}}}')
+        if len(do) > 1:  # click+send вместе молча брал click
+            raise SystemExit(f'шаг {i + 1}: click и send вместе — жду что-то одно')
+    browser, page = await live_page()
+    results = []
+    try:
+        for i, step in enumerate(steps):
+            do = step.get('do', {})  # шаг без do — read_state-шаг, как и в предвалидации
+            t0 = time.monotonic()
+            try:
+                if 'click' in do:
+                    st = shown(await do_click(page, do['click']))
+                elif 'send' in do:
+                    st = shown(await do_send(page, do['send']))
+                else:
+                    st = shown(await read_state(page))
+                ok, why = check_expect(st['text'], step.get('expect'))
+            except Exception as e:
+                ok, st, why = False, {'text': '', 'buttons': []}, f'{type(e).__name__}: {e}'
+            results.append({'step': i + 1, 'do': do, 'expect': step.get('expect'),
+                            'pass': ok, 'ms': round((time.monotonic() - t0) * 1000),
+                            'text': st['text'], **({'error': why} if why else {})})
+            print(f'шаг {i + 1}: {"ok" if ok else "FAIL"} {why}', flush=True)
+            if not ok:
+                break  # дальше сценарий бессмыслен: хрупкие шаги после сломанного врут
+    finally:
+        await browser.stop()
+        passed = all(r['pass'] for r in results)
+        if results:  # в finally, чтобы report остался и по Ctrl+C; Ctrl+C до первого шага
+            os.makedirs(ART, exist_ok=True)  # не пишет пустой report с pass=true — самообман
+            with open(os.path.join(ART, 'report.json'), 'w') as f:
+                json.dump({'scenario': os.path.basename(scenario_path), 'pass': passed,
+                           'steps': results}, f, ensure_ascii=False, indent=2)
+    print(f'итог: {"PASS" if passed else "FAIL"} ({len(results)} шагов) → {ART}/report.json')
+    if not passed:
+        raise SystemExit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog='tg-use', description='Руки для харнеса: Telegram-боты через web.telegram.org')
+    sub = parser.add_subparsers(dest='cmd', required=True)
+    sub.add_parser('login', help='headed-браузер с persistent-профилем (QR сканирует человек)')
+    p_open = sub.add_parser('open', help='открыть чат бота: поиск webk по username + клик, guard по peer-id hash, без отправок')
+    p_open.add_argument('bot', help='бот в форме @name')
+    sub.add_parser('state', help='JSON: последнее сообщение бота + подписи кнопок')
+    p_click = sub.add_parser('click', help='нажать кнопку по подписи (inline или reply-клавиатура; пустая реакция = ошибка ребра)')
+    p_click.add_argument('label')
+    p_save = sub.add_parser('save', help='дописать состояние/ребро в artifacts/flow.json + flow.md')
+    p_save.add_argument('--from', dest='from_id', default='', help='id состояния, из которого вышло ребро')
+    p_save.add_argument('--button', default='', help='подпись кнопки ребра')
+    p_save.add_argument('--bot', default='', help='имя бота (только для первого save)')
+    p_test = sub.add_parser('test', help='прогнать сценарий → artifacts/report.json (fail = exit 1)')
+    p_test.add_argument('scenario', help='JSON: [{"do": {"click"/"send": ...}, "expect": {"contains"/"regex": ...}}]')
+    sub.add_parser('skill-install', help='поставить скилл tg-use агенту (~/.claude/skills/tg-use); переустанавливай после обновлений репо')
+    args = parser.parse_args()
+
+    try:
+        if args.cmd == 'login':
+            asyncio.run(cmd_login())
+        elif args.cmd == 'open':
+            asyncio.run(cmd_open(args.bot))
+        elif args.cmd == 'state':
+            asyncio.run(cmd_state())
+        elif args.cmd == 'click':
+            asyncio.run(cmd_click(args.label))
+        elif args.cmd == 'save':
+            asyncio.run(cmd_save(args.from_id, args.button, args.bot))
+        elif args.cmd == 'test':
+            asyncio.run(cmd_test(args.scenario))
+        elif args.cmd == 'skill-install':
+            repo = os.path.dirname(os.path.abspath(__file__))
+            dst = install_skill(repo, os.path.expanduser('~'))
+            print(f'скилл установлен: {dst}; переустанови после обновлений репо')
+    except RuntimeError as e:  # ошибка руки (промах кнопки, нет реакции) — не traceback
+        raise SystemExit(f'ошибка: {e}')
+
+
+if __name__ == '__main__':
+    main()

tg_use-0.1.0/tg_use.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: tg-use
+Version: 0.1.0
+Summary: Руки для агент-харнеса: тестирование Telegram-ботов через web.telegram.org (CLI без LLM)
+Author: axisrow
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/axisrow/tg-use
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: browser-use>=0.13.8
+Dynamic: license-file
+
+# tg-use
+
+tg-use — тестировщик/копировщик Telegram-ботов через web.telegram.org (клиент `/k/`).
+CLI-«руки» + скилл для агент-харнесов: мозг — модель харнеса, CLI обращений к
+внешним моделям не содержит вовсе.
+
+## Два режима работы browser-use
+
+browser-use умеет работать двумя способами, и разница принципиальная:
+
+1. **Browser Harness CLI + скилл — наш путь, рекомендуемый.** Браузер подключается
+   к харнесу (Claude Code, Codex, OpenCode…), и решения принимает модель харнеса.
+   Наш `tg-use.py` — только «руки»: чтение состояния, клики по кнопкам, артефакты,
+   прогон записанных сценариев. Логика «куда кликать дальше» живёт в скилле
+   (`.claude/skills/tg-use/SKILL.md`), а не в коде.
+2. **Встроенный агент `Agent(task=..., llm=...)` со своим LLM-циклом — в этом
+   проекте так не делаем.** Этот режим дублирует мозг харнеса вторым (медленным
+   и ломким) контуром: ключи, endpoint'ы, таймауты, fallback-модели. Был
+   использован в v1 до 2026-09-20 и отвергнут владельцем вместе с z.ai-конфигом.
+
+**Правило: использовать `browser-use skill install`, а не писать своего агента.**
+В CLI нет ни одного обращения к внешней модели — проверяется `test_skeleton.py`.
+
+## Установка
+
+Из клона:
+
+```sh
+pip3 install -r requirements.txt          # в прокси-окружении: env -u ALL_PROXY -u all_proxy pip3 ...
+python3 -m playwright install chromium
+browser-use skill install                 # подключить браузер к харнесу
+```
+
+Из PyPI (Python ≥3.11): `pipx install tg-use` — те же команды без `python3 tg-use.py`:
+`tg-use login`, `tg-use open <@bot>`, `tg-use state`, …; `tg-use skill-install`
+ставит скилл агенту (команды в нём переписываются на `tg-use`).
+
+## Логин
+
+```sh
+python3 tg-use.py login   # откроется окно с QR — отсканируй телефоном один раз
+```
+
+Сессия сохраняется в `~/.tg-use-agent-profile` (= пароль от аккаунта) — повторный
+запуск подхватит её без QR. При первом запуске macOS спросит доступ к «Chromium
+Safe Storage»: вводи пароль входа и жми «Разрешать всегда» — это шифрование
+cookies, без него сессия не переживёт перезапуск.
+
+Browser Harness из коробки цепляется к обычному Chrome с его родным профилем и
+наш изолированный профиль не даёт, поэтому профильный запуск остаётся за CLI:
+`login` держит Chromium на нашем профиле и пишет его адрес в `~/.tg-use-cdp`;
+`state`/`click`/`save`/`test` подключаются к этому живому браузеру. Харнес может
+работать с тем же окном через browser-use (`BU_CDP_URL=$(cat ~/.tg-use-cdp)`).
+
+## Команды (руки; «куда кликать дальше» решает харнес)
+
+| Команда | Что делает |
+|---|---|
+| `tg-use.py login` | headed-браузер с persistent-профилем; адрес → `~/.tg-use-cdp` |
+| `tg-use.py open <@bot>` | открыть чат бота: поиск webk по username + клик по результату, guard по peer-id в hash; без отправок |
+| `tg-use.py state` | JSON: текст последнего сообщения бота + подписи кнопок |
+| `tg-use.py click "<label>"` | нажать inline-кнопку, вернуть новое состояние; отсутствие кнопки/реакции = ошибка (exit 1) |
+| `tg-use.py save [--from id --button label] [--bot @name]` | дописать состояние/ребро в `artifacts/flow.json` + `artifacts/flow.md` (Mermaid) |
+| `tg-use.py test scenario.json` | шаги `{"do": {"send"/"click"}, "expect": {"contains"/"regex"}}` → `artifacts/report.json`; падение = exit 1 |
+
+Дальше — по скиллу `.claude/skills/tg-use/SKILL.md`: малый обход (глубина ≤2,
+до ~5 состояний) и прогон сценариев. Безопасность: темп 2–3 c между действиями,
+только диалоги с ботами, скраб токенов в выводе, PNG не сохраняем.
+
+## Тесты и категории
+
+Граница категорий — цена ошибки. `unit`: offline-скрипты, безопасный дефолт —
+`python3 test_skeleton.py && python3 test_crawl.py && python3 test_hands.py`.
+`state`/`open` — live_read (чтение/открытие чата без отправок); `click`/`save` —
+live_write (обратимые действия в диалоге с ботом); `test`/`login` —
+live_write_danger (необратимая отправка боту / полный доступ к аккаунту).
+Гейты — в `.claude/settings.json`: владелец 2026-09-20 разрешил все подкоманды
+целиком (`Bash(python3 tg-use.py:*)`), категории остались описанием цены ошибки,
+а не спросом харнеса.

tg_use-0.1.0/tg_use.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+tg_use/SKILL.md
+tg_use/__init__.py
+tg_use.egg-info/PKG-INFO
+tg_use.egg-info/SOURCES.txt
+tg_use.egg-info/dependency_links.txt
+tg_use.egg-info/entry_points.txt
+tg_use.egg-info/requires.txt
+tg_use.egg-info/top_level.txt

tg_use-0.1.0/tg_use.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tg_use-0.1.0/tg_use.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tg-use = tg_use:main

tg_use-0.1.0/tg_use.egg-info/requires.txt

@@ -0,0 +1 @@
+browser-use>=0.13.8

tg_use-0.1.0/tg_use.egg-info/top_level.txt

@@ -0,0 +1 @@
+tg_use