dsh-tg-bridge 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleks Vega
+
+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.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# dsh-tg-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Telegram-мост для [DeepSeek Harness](https://deepseek.com): управляй агентом из
+бота — текстом, голосом и фото, без открытия десктопного приложения.
+
+Каждая тема форума = отдельный проект со своей сессией и своим рабочим
+каталогом. Ответы приходят с прогрессом, кнопкой «Стоп» и копируемыми блоками
+кода.
+
+## Что умеет
+
+- **Текст** — обычная задача уходит агенту, ответ приходит в ту же тему.
+- **Голос** — локальный faster-whisper, расшифровка показывается до ответа.
+- **Фото** — уходит в модель со зрением; текст и интерфейс распознаются.
+- **Проект на тему** — `/cd pixel-creator`, и все ходы идут из этого каталога.
+- **Живой прогресс** — «⏳ Работаю…» с шагами, счётчиком времени и кэшем в финале.
+- **Не теряет сообщения** — журнал с подтверждением и переигрыванием.
+- **Fail-fast** — при исчерпанной квоте сразу переключается на free-модель.
+- **`dsh-tg check`** — диагностика одной командой без изменений в системе.
+- **Языки** — меню и служебные сообщения на `en`, `ru`, `zh`; `/lang` переключает язык темы, новый пользователь получает свой по `language_code` из Telegram (всё вне ru/zh → `en`).
+- **Кнопки «Стоп»/«Повторить», approvals** — в планах v1.1 (см. `docs/ROADMAP.md`).
+
+## Требования
+
+- Node.js ≥ 20
+- Установленный DeepSeek Harness (`~/.dsh/profiles/headless`)
+- Токен Telegram-бота от [@BotFather](https://t.me/BotFather)
+
+## Языки
+
+- Меню (`/` в чате) — три набора: `ru` по умолчанию, `en`, `zh`.
+- Язык темы: `/lang en|ru|zh`; хранится в `state.json` и переживает рестарт.
+- Новый пользователь получает язык из `language_code` Telegram; всё, что не `ru`/`zh`, → `en`.
+- Переведены: меню, стартовое сообщение, статус хода, ошибки, `/cd`, `/new`, `/stop`, `/lang`,
+  ответ на неизвестную команду. Длинные отчёты (`/status`, `/sessions`, `/models` и т. п.)
+  пока на русском — это следующий проход.
+
+## Установка
+
+Три способа, выбери один.
+
+**A. npm (рекомендуется)**
+
+```bash
+npx dsh-tg-bridge@latest init     # создать config.json из шаблона
+npx dsh-tg-bridge@latest check    # диагностика, ничего не меняет
+npx dsh-tg-bridge@latest setup    # установить и запустить мост
+```
+
+**B. Одной строкой (curl / PowerShell)**
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/aleksvega/dsh-tg-bridge/main/install.sh | bash
+```
+
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/aleksvega/dsh-tg-bridge/main/install.ps1 | iex
+```
+
+**C. Вручную**
+
+```bash
+git clone https://github.com/aleksvega/dsh-tg-bridge.git ~/.dsh/tg-bridge
+cd ~/.dsh/tg-bridge
+cp config.example.json config.json
+node cli.mjs check
+node cli.mjs setup
+```
+
+**2. Положить токен бота в хранилище DSH**
+
+Файл `~/.dsh/.credentials.yaml`, секция `refs`:
+
+```yaml
+refs:
+  DSH_TELEGRAM_BOT_TOKEN: "123456789:AA..."
+```
+
+Имя переменной может быть любым с префиксом `DSH_TELEGRAM_BOT_TOKEN_` —
+мост найдёт его сам.
+
+**3. Создать конфиг**
+
+```bash
+cp config.example.json config.json
+```
+
+Заполнить `allowedUserIds` — свой числовой id (узнать у
+[@userinfobot](https://t.me/userinfobot)). Без него мост не отвечает никому:
+это защита от чужих сообщений.
+
+**4. Применить и проверить**
+
+```bash
+node setup.mjs          # остановит старый мост, поднимет новый, поставит меню
+node setup.mjs --check  # только отчёт, ничего не меняет
+```
+
+**5. Автозапуск (Windows)**
+
+```powershell
+Register-ScheduledTask -TaskName "DSH-TG-Bridge" `
+  -Action (New-ScheduledTaskAction -Execute "node" -Argument "bridge.mjs" -WorkingDirectory "$HOME\.dsh\tg-bridge") `
+  -Trigger (New-ScheduledTaskTrigger -AtLogOn) -Force
+```
+
+## Проверка
+
+Напиши боту:
+
+| Команда | Ожидание |
+|---|---|
+| `/doctor` | отчёт: pid, Telegram, диск, каталог, сессия |
+| `/help` | список команд по группам |
+| `/cd pixel-creator` | тема привязана к проекту |
+| `/prices` | цены моделей и стоимость текущей |
+
+## Команды
+
+```
+Работа:       /cd · /new · /stop · /send · /seed
+Сессии:       /status · /sessions · /resume
+Модели:       /models · /model · /prices
+Расширения:   /skills · /plugins · /plugin · /soul
+Диагностика:  /doctor · /logs [errors|N|текст]
+Служебное:    /app · /restart · /help
+```
+
+## Как это работает
+
+```
+Telegram → bridge.mjs → dsh --profile headless --json → ответ
+             │
+             ├─ журнал pending/ + ack  (сообщения не теряются)
+             ├─ очередь на тему        (ходы в темах параллельны)
+             ├─ прогресс + кнопки      (видно, что работа идёт)
+             └─ fail-fast по квоте     (free-модели как резерв)
+```
+
+Мост — один процесс с long-polling. На каждый ход поднимается отдельный
+процесс CLI, который умирает после ответа; поэтому «нет процесса DSH» между
+ходами — это норма, а не сбой.
+
+## Безопасность
+
+- `config.json`, `state.json`, `pending/`, логи — в `.gitignore`, в репозиторий
+  не попадают.
+- Токен хранится в хранилище DSH, не в коде и не в конфиге.
+- Мост отвечает только id из `allowedUserIds`.
+
+## Документация
+
+- [docs/STATE.md](docs/STATE.md) — что работает, известные проблемы
+- [docs/ROADMAP.md](docs/ROADMAP.md) — что дальше
+- [docs/UX-ANALYSIS.md](docs/UX-ANALYSIS.md) — разбор интерактива
+- [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md) — критерии приёмки
+- [docs/CHANGELOG.md](docs/CHANGELOG.md) — история изменений
+- [docs/RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md) — критерии готовности релиза
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/bot-menu.mjs

@@ -0,0 +1,141 @@
+// dsh-bot-menu — install the Telegram command menu that matches THIS bridge.
+//
+// Why it exists: the menu the person sees is whatever `setMyCommands` last
+// wrote, and another plugin (@xmanrui/dsh-im) had set a Chinese list of 31
+// commands that this bridge does not implement. A menu that lies is worse than
+// no menu, so the bridge owns its own list and re-asserts it on start.
+//
+// Usage: node bot-menu.mjs [--delete]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const args = new Set(process.argv.slice(2));
+
+const token = (() => {
+  const yaml = readFileSync(join(homedir(), '.dsh', '.credentials.yaml'), 'utf8');
+  const m = /^\s*(DSH_TELEGRAM_BOT_TOKEN_[A-Z0-9_]+):\s*["']?([^"'\s]+)/m.exec(yaml);
+  return m ? m[2] : '';
+})();
+
+/** The real, implemented surface of dsh-tg-bridge — nothing aspirational. */
+const COMMANDS = [
+  { command: 'new', description: 'Новая сессия в этой теме' },
+  { command: 'cd', description: 'Привязать тему к проекту: /cd pixel-creator' },
+  { command: 'status', description: 'Сессии, модель, активные ходы' },
+  { command: 'stop', description: 'Остановить текущий ход' },
+  { command: 'prices', description: 'Цены моделей и что стоит текущая' },
+  { command: 'send', description: 'Прислать файл из проекта в чат' },
+  { command: 'seed', description: 'Засеять пустую тему текстом и закрепить' },
+  { command: 'sessions', description: 'Последние сессии' },
+  { command: 'resume', description: 'Продолжить сессию по id' },
+  { command: 'models', description: 'Список моделей' },
+  { command: 'model', description: 'Сменить модель: /model <id>' },
+  { command: 'skills', description: 'Скиллы: список или текст одного' },
+  { command: 'soul', description: 'Персона: показать или задать' },
+  { command: 'plugins', description: 'Плагины профиля' },
+  { command: 'plugin', description: 'add/remove/disable/enable плагина' },
+  { command: 'app', description: 'Перезапуск приложения: /app restart confirm' },
+  { command: 'restart', description: 'Перезапуск моста: /restart confirm' },
+  { command: 'doctor', description: 'Диагностика: мост, сеть, диск, каталог, сессия' },
+  { command: 'logs', description: 'Хвост лога моста: /logs 50 или /logs TG_NET' },
+  { command: 'help', description: 'Все команды и подсказки' },
+  { command: 'lang', description: 'Язык интерфейса: en, ru, zh' },
+];
+
+/** English menu (language_code: en). Same commands, translated descriptions. */
+const COMMANDS_EN = [
+  { command: 'new', description: 'New session in this topic' },
+  { command: 'cd', description: 'Bind this topic to a project: /cd pixel-creator' },
+  { command: 'status', description: 'Sessions, model, active turns' },
+  { command: 'stop', description: 'Stop the current turn' },
+  { command: 'prices', description: 'Model prices and the cost of the current one' },
+  { command: 'send', description: 'Send a file from the project into the chat' },
+  { command: 'seed', description: 'Seed an empty topic with text and pin it' },
+  { command: 'sessions', description: 'Recent sessions' },
+  { command: 'resume', description: 'Continue a session by id' },
+  { command: 'models', description: 'Available models' },
+  { command: 'model', description: 'Show or switch the model' },
+  { command: 'skills', description: 'Installed skills' },
+  { command: 'soul', description: 'Agent persona' },
+  { command: 'plugins', description: 'Installed plugins' },
+  { command: 'plugin', description: 'Enable or disable a plugin' },
+  { command: 'app', description: 'Desktop app control' },
+  { command: 'restart', description: 'Restart the bridge: /restart confirm' },
+  { command: 'doctor', description: 'Diagnostics: bridge, network, disk, directory, session' },
+  { command: 'logs', description: 'Bridge log tail: /logs 50 or /logs TG_NET' },
+  { command: 'help', description: 'All commands and hints' },
+  { command: 'lang', description: 'Interface language: en, ru, zh' },
+];
+
+/** Chinese menu (language_code: zh-hans). */
+const COMMANDS_ZH = [
+  { command: 'new', description: '在本话题开始新会话' },
+  { command: 'cd', description: '将本话题绑定到项目：/cd pixel-creator' },
+  { command: 'status', description: '会话、模型、进行中的任务' },
+  { command: 'stop', description: '停止当前任务' },
+  { command: 'prices', description: '模型价格与当前模型花费' },
+  { command: 'send', description: '把项目中的文件发送到聊天' },
+  { command: 'seed', description: '用文本初始化空话题并置顶' },
+  { command: 'sessions', description: '最近的会话' },
+  { command: 'resume', description: '按 id 继续会话' },
+  { command: 'models', description: '可用模型' },
+  { command: 'model', description: '查看或切换模型' },
+  { command: 'skills', description: '已安装的技能' },
+  { command: 'soul', description: '代理人格设定' },
+  { command: 'plugins', description: '已安装的插件' },
+  { command: 'plugin', description: '启用或停用插件' },
+  { command: 'app', description: '桌面应用控制' },
+  { command: 'restart', description: '重启桥接：/restart confirm' },
+  { command: 'doctor', description: '诊断：桥接、网络、磁盘、目录、会话' },
+  { command: 'logs', description: '桥接日志：/logs 50 或 /logs TG_NET' },
+  { command: 'help', description: '全部命令与提示' },
+  { command: 'lang', description: '界面语言：en、ru、zh' },
+];
+
+async function api(method, body) {
+  const res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+    signal: AbortSignal.timeout(20000),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!json.ok) throw new Error(`${method}: ${json.description || res.status}`);
+  return json.result;
+}
+
+async function main() {
+  if (!token) {
+    console.error('bot token not found in ~/.dsh/.credentials.yaml');
+    process.exit(1);
+  }
+  if (args.has('--delete')) {
+    await api('deleteMyCommands', {});
+    console.log('menu deleted');
+    return;
+  }
+  // Telegram keeps one menu per language_code, so a Chinese or English user
+  // sees the list in their own language instead of Russian.
+  await api('setMyCommands', { commands: COMMANDS });
+  // Telegram validates language_code against its own ISO list: 'zh-hans' is
+  // rejected with "invalid language code", 'zh' is accepted. Each language is
+  // installed independently — one refusal must not leave the others unset.
+  for (const [code, list] of [['en', COMMANDS_EN], ['zh', COMMANDS_ZH]]) {
+    try {
+      await api('setMyCommands', { commands: list, language_code: code });
+      console.log(`menu installed for ${code}: ${list.length} commands`);
+    } catch (error) {
+      console.error(`menu for ${code} failed: ${error.message}`);
+    }
+  }
+  const check = await api('getMyCommands', {});
+  console.log(`menu installed: ${check.length} commands`);
+  for (const c of check) console.log(`  /${c.command} — ${c.description}`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/bridge-kick.mjs

@@ -0,0 +1,118 @@
+// bridge-kick — one-minute supervisor tick.
+//
+// The DSH-TG-Bridge task only fires every five minutes, so a bridge that exited
+// for a code update could wait that long before coming back. This tick is cheap
+// and only starts a bridge when the pid file is missing or the process is gone;
+// otherwise it exits immediately. A live pid that refuses to die (EPERM) counts
+// as alive: refusing to start a second poller is what prevents 409 conflicts.
+//
+// Exit codes: 0 = nothing to do or started, 2 = start failed.
+
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync, openSync, closeSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh');
+const DIR = join(DSH_HOME, 'tg-bridge');
+const BRIDGE = join(DIR, 'bridge.mjs');
+const PID_FILE = join(DIR, 'bridge.pid');
+const KICK_LOG = join(DIR, 'kick.log');
+
+// Shared with setup.mjs: a restart holds this lock, so a tick that lands in the
+// middle of one must not start a second poller.
+const LOCK = join(DIR, 'restart.lock');
+function acquireLock(owner) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = openSync(LOCK, 'wx');
+      writeFileSync(fd, JSON.stringify({ pid: process.pid, owner, ts: Date.now() }));
+      closeSync(fd);
+      const release = () => { try { unlinkSync(LOCK); } catch {} };
+      process.on('exit', release);
+      return release;
+    } catch (error) {
+      if (error.code !== 'EEXIST') return null;
+      let held = 0;
+      try { held = Number(JSON.parse(readFileSync(LOCK, 'utf8')).pid) || 0; } catch {}
+      let alive = false;
+      if (held) {
+        try { process.kill(held, 0); alive = true; } catch (e) { alive = e.code === 'EPERM'; }
+      }
+      if (alive) return null;
+      try { unlinkSync(LOCK); } catch {}
+    }
+  }
+  return null;
+}
+
+function log(line) {
+  try {
+    appendFileSync(KICK_LOG, `${new Date().toISOString()} ${line}\n`, 'utf8');
+  } catch {}
+}
+
+function pidFromFile() {
+  try {
+    const pid = Number(readFileSync(PID_FILE, 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** True when the pid exists; a permission error still means "alive". */
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function bridgePids() {
+  const r = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+    "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Where-Object { $_.CommandLine -match 'bridge\\.mjs' } | Select-Object -ExpandProperty ProcessId"],
+    { encoding: 'utf8', windowsHide: true, timeout: 20000 });
+  return (r.stdout || '').split(/\r?\n/).map((v) => Number(v.trim())).filter((v) => Number.isInteger(v) && v > 0);
+}
+
+function main() {
+  if (!acquireLock('kick')) {
+    log('restart in progress (setup holds the lock), skipping this tick');
+    return 0;
+  }
+  if (!existsSync(BRIDGE)) {
+    log('bridge.mjs missing');
+    return 2;
+  }
+  // A restart marker with an empty queue means the previous process exited on
+  // purpose: start it again and clear the marker.
+  const marker = join(DIR, 'restart.pending');
+  const restartPending = existsSync(marker);
+
+  const filePid = pidFromFile();
+  const live = bridgePids();
+  if (live.length > 0 || (filePid && alive(filePid))) {
+    if (restartPending && live.length === 0) log(`marker present but pid ${filePid} alive`);
+    return 0;
+  }
+
+  log(restartPending ? 'marker present and no bridge: starting' : 'no bridge: starting');
+  const child = spawnSync(process.execPath, ['--dns-result-order=ipv4first', BRIDGE], {
+    cwd: DIR,
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  if (child.error) {
+    log(`start failed: ${child.error.message}`);
+    return 2;
+  }
+  try { readFileSync; } catch {}
+  log('start issued');
+  return 0;
+}
+
+process.exit(main());

package/bridge-restart-idle.mjs

@@ -0,0 +1,100 @@
+// bridge-restart-idle — restart the bridge only when no turn is running.
+//
+// v1 watched for a "sent chat=" log line and died before acting (pipes inside a
+// detached process). v2 polls the process tree instead: a turn is running while
+// a DeepSeek Harness.exe child belongs to the bridge. Restart happens only after
+// several consecutive checks find no such child, so the pending reply is already
+// delivered and nothing is killed mid-answer.
+//
+// Usage: node bridge-restart-idle.mjs [--idle-sec 12] [--max-min 20]
+
+import { execFileSync, spawn } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh');
+const DIR = join(DSH_HOME, 'tg-bridge');
+const BRIDGE = join(DIR, 'bridge.mjs');
+const PID_FILE = join(DIR, 'bridge.pid');
+const RL = join(DIR, 'restart.log');
+
+const argv = process.argv.slice(2);
+const idleSec = Number(argv[argv.indexOf('--idle-sec') + 1]) || 12;
+const maxMin = Number(argv[argv.indexOf('--max-min') + 1]) || 20;
+const deadline = Date.now() + maxMin * 60000;
+
+function log(line) {
+  try {
+    appendFileSync(RL, `${new Date().toISOString()} ${line}\n`, 'utf8');
+  } catch {}
+}
+
+function runJson(script) {
+  try {
+    const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 20000,
+    });
+    return (out || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+function bridgePid() {
+  const raw = runJson("try { (Get-Content '" + PID_FILE.replace(/'/g, "''") + "' -Raw).Trim() } catch { '' }");
+  const pid = Number(raw);
+  return Number.isInteger(pid) && pid > 0 ? pid : 0;
+}
+
+/** Children of the bridge = the CLI process of one running turn. */
+function runningTurns(pid) {
+  const raw = runJson(
+    `Get-CimInstance Win32_Process -Filter "ParentProcessId=${pid}" | Where-Object { $_.Name -like 'DeepSeek Harness*' -and $_.CommandLine -match '--profile' } | Measure-Object | Select-Object -ExpandProperty Count`
+  );
+  return Number(raw) || 0;
+}
+
+async function main() {
+  log(`v2 started: waiting for ${idleSec}s of idle`);
+  let idleSince = 0;
+
+  while (Date.now() < deadline) {
+    const pid = bridgePid();
+    if (!pid) {
+      log('no bridge pid; nothing to restart');
+      return;
+    }
+    const turns = runningTurns(pid);
+    if (turns > 0) {
+      idleSince = 0;
+      await new Promise((r) => setTimeout(r, 3000));
+      continue;
+    }
+    if (!idleSince) idleSince = Date.now();
+    if (Date.now() - idleSince >= idleSec * 1000) {
+      log(`idle ${idleSec}s with no running turn; restarting bridge ${pid}`);
+      try {
+        process.kill(pid, 'SIGTERM');
+      } catch (error) {
+        log(`kill failed: ${error.message}`);
+      }
+      await new Promise((r) => setTimeout(r, 3000));
+      const child = spawn(process.execPath, ['--dns-result-order=ipv4first', BRIDGE], {
+        cwd: DIR,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      child.unref();
+      log(`started bridge pid ${child.pid}`);
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  log('deadline reached; bridge left as is');
+}
+
+main().catch((error) => log(`fatal: ${error.message}`));