@tritard/waterbrother 0.16.6 → 0.16.8

package/README.md

@@ -29,6 +29,7 @@ It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
 - First-run onboarding wizard in terminal
   - asks for provider first
   - asks for API key when the selected provider requires one
+  - tries a live provider model list after credentials, then falls back to the built-in catalog
   - prompts for default model and agent profile
 - Multi-provider chat integration through provider adapters and model registry
 - Vision command for local images: `waterbrother vision <image-path> <prompt>`
@@ -258,9 +259,11 @@ Rollout order:
 3. approvals over messaging
 4. only then group DM collaboration
 
-Current Telegram limitation:
+Current Telegram behavior:
 - remote prompts run with `approval=never`
-- status, runtime inspection, and read-oriented prompts work best
+- replies are rendered as Telegram-safe HTML, with code blocks and stripped raw Markdown symbols
+- the gateway sends typing activity and edits one in-progress message into the final reply before falling back to chunked follow-up messages
+- pending pairings are explicit and expire automatically after 12 hours unless approved
 - mutating and approval-heavy work stay local until remote approvals land
 - pairing is now explicit: first DM creates a pending request, then approve locally with `waterbrother gateway pair telegram <user-id>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "description": "Waterbrother: bring-your-own-model coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/channels.js

@@ -55,7 +55,8 @@ function normalizeTelegramConfig(value = {}) {
   const common = normalizeCommonChannelConfig(source);
   return {
     ...common,
-    botToken: String(source.botToken || "").trim()
+    botToken: String(source.botToken || "").trim(),
+    pairingExpiryMinutes: Number.isFinite(Number(source.pairingExpiryMinutes)) ? Math.max(1, Math.floor(Number(source.pairingExpiryMinutes))) : 720
   };
 }
 
@@ -130,6 +131,7 @@ function summarizeChannel(serviceId, config = {}) {
     pairingMode: config.pairingMode || "manual",
     defaultRuntimeProfile: config.defaultRuntimeProfile || "",
     linkedSessionId: config.linkedSessionId || "",
+    pairingExpiryMinutes: Number.isFinite(Number(config.pairingExpiryMinutes)) ? Math.max(1, Math.floor(Number(config.pairingExpiryMinutes))) : 720,
     missing,
     requiredFields: [...spec.requiredFields],
     envKeys: [...spec.envKeys]
@@ -178,7 +180,8 @@ export function buildChannelOnboardingPayload(serviceId) {
       prerequisites: [
         "Create a Telegram bot with BotFather",
         "Capture the bot token",
-        "Start with manual pairing so first-contact DMs create a pending approval request"
+        "Start with manual pairing so first-contact DMs create a pending approval request",
+        "Telegram replies are rendered as clean HTML with live typing and edit-in-place delivery"
       ],
       commands: [
         "waterbrother config set-json channels '{\"telegram\":{\"enabled\":true,\"botToken\":\"YOUR_BOT_TOKEN\",\"pairingMode\":\"manual\",\"allowedUserIds\":[]}}'",
@@ -190,7 +193,9 @@ export function buildChannelOnboardingPayload(serviceId) {
       notes: [
         "Start with direct messages only.",
         "Unknown DMs create a pending pairing request you approve locally.",
-        "Remote commands include /help, /status, /runtime, /sessions, /resume <id>, /new, and /clear."
+        "Pending pairings expire automatically after 12 hours unless approved.",
+        "Remote commands include /help, /status, /runtime, /sessions, /resume <id>, /new, and /clear.",
+        "Telegram uses typing indicators and edit-in-place responses before falling back to chunked follow-up messages."
       ]
     };
   }

package/src/cli.js

@@ -10,7 +10,7 @@ import { getConfigPath, loadConfigLayers, resolveRuntimeConfig, saveConfig } fro
 import { createChatCompletion, createJsonCompletion, listModels } from "./model-client.js";
 import { buildChannelOnboardingPayload, getChannelStatuses, getGatewayStatus } from "./channels.js";
 import { runGatewayService } from "./gateway.js";
-import { loadGatewayState, saveGatewayState } from "./gateway-state.js";
+import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayState, prunePendingPairings, saveGatewayState } from "./gateway-state.js";
 import {
   getDefaultDesignModelForProvider,
   getDefaultModelForProvider,
@@ -2830,16 +2830,65 @@ async function chooseProviderInteractive(defaultProvider = 'xai') {
   return selected?.value || defaultProvider;
 }
 
-async function chooseModelInteractive(defaultModel, provider = '') {
-  const catalog = MODEL_CATALOG.filter((model) => !provider || model.provider === provider);
-  const defaultIndex = Math.max(0, catalog.findIndex((model) => model.id === defaultModel));
-  const options = catalog.map((model, index) => ({
-    value: model.id,
-    label: `${model.id}${index === defaultIndex ? ' (default)' : ''}`
+async function chooseModelInteractive(defaultModel, provider = '', { apiKey = '', baseUrl = '', allowRemote = true } = {}) {
+  const normalizedProvider = normalizeProvider(provider);
+  let remoteModels = [];
+  if (allowRemote && normalizedProvider) {
+    try {
+      remoteModels = await listModels({
+        provider: normalizedProvider,
+        apiKey,
+        baseUrl
+      });
+    } catch {
+      remoteModels = [];
+    }
+  }
+
+  const seen = new Set();
+  const options = [];
+
+  for (const model of remoteModels) {
+    const value = String(model?.id || "").trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    options.push({
+      value,
+      label: model?.notes ? `${value} - ${model.notes}` : value
+    });
+  }
+
+  for (const model of MODEL_CATALOG) {
+    if (normalizedProvider && model.provider !== normalizedProvider) continue;
+    const value = String(model?.id || "").trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    options.push({
+      value,
+      label: model?.notes ? `${value} - ${model.notes}` : value
+    });
+  }
+
+  if (!options.length) {
+    options.push({
+      value: defaultModel,
+      label: `${defaultModel} (default)`
+    });
+  }
+
+  const defaultIndex = Math.max(0, options.findIndex((model) => model.value === defaultModel));
+  const titledOptions = options.map((model, index) => ({
+    value: model.value,
+    label: `${model.label}${index === defaultIndex ? " (default)" : ""}`
   }));
+
   const selected = await chooseFromInteractiveMenu({
-    title: 'Select default model:',
-    options,
+    title: remoteModels.length
+      ? `Select default model for ${normalizedProvider} (live list):`
+      : normalizedProvider
+        ? `Select default model for ${normalizedProvider}:`
+        : "Select default model:",
+    options: titledOptions,
     defaultIndex
   });
   return selected?.value || defaultModel;
@@ -2927,7 +2976,11 @@ async function runOnboardingWizard(config, { cwd }) {
   }
 
   next.baseUrl = providerSpec?.defaultBaseUrl || next.baseUrl || '';
-  next.model = await chooseModelInteractive(next.model || getDefaultModelForProvider(next.provider), next.provider);
+  next.model = await chooseModelInteractive(next.model || getDefaultModelForProvider(next.provider), next.provider, {
+    apiKey: next.apiKey,
+    baseUrl: next.baseUrl,
+    allowRemote: providerSpec?.supportsRemoteModelList !== false
+  });
   next.agentProfile = await chooseAgentProfileInteractive(next.agentProfile || 'coder');
   if (!next.approvalMode) next.approvalMode = 'on-request';
   if (!next.designModel) next.designModel = getDefaultDesignModelForProvider(next.provider);
@@ -3229,13 +3282,18 @@ async function runGatewayCommand(positional, runtime, { cwd = process.cwd(), asJ
     if (service !== "telegram") {
       throw new Error("Usage: waterbrother gateway pairings [telegram]");
     }
-    const state = await loadGatewayState(service);
+    const ttlMinutes = Number.isFinite(Number(runtime.channels?.telegram?.pairingExpiryMinutes))
+      ? Math.max(1, Math.floor(Number(runtime.channels.telegram.pairingExpiryMinutes)))
+      : DEFAULT_PENDING_PAIRING_TTL_MINUTES;
+    const loadedState = await loadGatewayState(service);
+    const { state, pruned } = prunePendingPairings(loadedState, ttlMinutes);
+    if (pruned > 0) await saveGatewayState(service, state);
     const pending = Object.values(state.pendingPairings || {});
     const paired = Array.isArray(runtime.channels?.telegram?.allowedUserIds)
       ? runtime.channels.telegram.allowedUserIds.map((value) => String(value || "").trim()).filter(Boolean)
       : [];
     if (asJson) {
-      printData({ service, pending, paired }, true);
+      printData({ service, pending, paired, pairingExpiryMinutes: ttlMinutes }, true);
       return;
     }
     console.log(`telegram paired users: ${paired.length ? paired.join(", ") : "none"}`);
@@ -3243,11 +3301,12 @@ async function runGatewayCommand(positional, runtime, { cwd = process.cwd(), asJ
       console.log("telegram pending pairings: none");
       return;
     }
-    console.log("telegram pending pairings:");
+    console.log(`telegram pending pairings (expire after ${ttlMinutes} minutes):`);
     for (const item of pending) {
       const username = String(item?.username || "").trim();
       const detail = username ? ` (${username})` : "";
-      console.log(`  ${item.userId}${detail}`);
+      const lastSeen = String(item?.lastSeenAt || item?.firstSeenAt || "").trim();
+      console.log(`  ${item.userId}${detail}${lastSeen ? ` [last seen ${lastSeen}]` : ""}`);
     }
     return;
   }
@@ -6876,7 +6935,12 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
     }
 
     if (line === "/gateway pairings") {
-      const state = await loadGatewayState("telegram");
+      const ttlMinutes = Number.isFinite(Number(context.runtime.channels?.telegram?.pairingExpiryMinutes))
+        ? Math.max(1, Math.floor(Number(context.runtime.channels.telegram.pairingExpiryMinutes)))
+        : DEFAULT_PENDING_PAIRING_TTL_MINUTES;
+      const loadedState = await loadGatewayState("telegram");
+      const { state, pruned } = prunePendingPairings(loadedState, ttlMinutes);
+      if (pruned > 0) await saveGatewayState("telegram", state);
       const pending = Object.values(state.pendingPairings || {});
       const paired = Array.isArray(context.runtime.channels?.telegram?.allowedUserIds)
         ? context.runtime.channels.telegram.allowedUserIds.map((value) => String(value || "").trim()).filter(Boolean)
@@ -6885,10 +6949,11 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       if (!pending.length) {
         console.log("telegram pending pairings: none");
       } else {
-        console.log("telegram pending pairings:");
+        console.log(`telegram pending pairings (expire after ${ttlMinutes} minutes):`);
         for (const item of pending) {
           const username = String(item?.username || "").trim();
-          console.log(`  ${item.userId}${username ? ` (${username})` : ""}`);
+          const lastSeen = String(item?.lastSeenAt || item?.firstSeenAt || "").trim();
+          console.log(`  ${item.userId}${username ? ` (${username})` : ""}${lastSeen ? ` [last seen ${lastSeen}]` : ""}`);
         }
       }
       continue;

package/src/gateway-state.js

@@ -3,26 +3,54 @@ import os from "node:os";
 import path from "node:path";
 
 const GATEWAY_DIR = path.join(os.homedir(), ".waterbrother", "gateway");
+export const DEFAULT_PENDING_PAIRING_TTL_MINUTES = 720;
 
 function gatewayStatePath(serviceId) {
   return path.join(GATEWAY_DIR, `${String(serviceId || "").trim().toLowerCase()}.json`);
 }
 
+function normalizeGatewayState(parsed = {}) {
+  return {
+    offset: Number.isFinite(Number(parsed?.offset)) ? Math.max(0, Math.floor(Number(parsed.offset))) : 0,
+    peers: parsed?.peers && typeof parsed.peers === "object" ? parsed.peers : {},
+    pendingPairings: parsed?.pendingPairings && typeof parsed.pendingPairings === "object" ? parsed.pendingPairings : {}
+  };
+}
+
 export async function ensureGatewayStateDir() {
   await fs.mkdir(GATEWAY_DIR, { recursive: true });
 }
 
+export function prunePendingPairings(state, ttlMinutes = DEFAULT_PENDING_PAIRING_TTL_MINUTES, now = Date.now()) {
+  const current = normalizeGatewayState(state);
+  const ttlMs = Math.max(1, Number.isFinite(Number(ttlMinutes)) ? Math.floor(Number(ttlMinutes)) : DEFAULT_PENDING_PAIRING_TTL_MINUTES) * 60 * 1000;
+  const pendingPairings = {};
+  let pruned = 0;
+
+  for (const [userId, item] of Object.entries(current.pendingPairings || {})) {
+    const lastSeenMs = Date.parse(item?.lastSeenAt || item?.firstSeenAt || "");
+    if (!Number.isFinite(lastSeenMs) || now - lastSeenMs <= ttlMs) {
+      pendingPairings[userId] = item;
+    } else {
+      pruned += 1;
+    }
+  }
+
+  return {
+    state: {
+      ...current,
+      pendingPairings
+    },
+    pruned
+  };
+}
+
 export async function loadGatewayState(serviceId) {
   await ensureGatewayStateDir();
   const filePath = gatewayStatePath(serviceId);
   try {
     const raw = await fs.readFile(filePath, "utf8");
-    const parsed = JSON.parse(raw);
-    return {
-      offset: Number.isFinite(Number(parsed?.offset)) ? Math.max(0, Math.floor(Number(parsed.offset))) : 0,
-      peers: parsed?.peers && typeof parsed.peers === "object" ? parsed.peers : {},
-      pendingPairings: parsed?.pendingPairings && typeof parsed.pendingPairings === "object" ? parsed.pendingPairings : {}
-    };
+    return normalizeGatewayState(JSON.parse(raw));
   } catch (error) {
     if (error?.code === "ENOENT") {
       return { offset: 0, peers: {}, pendingPairings: {} };
@@ -34,11 +62,7 @@ export async function loadGatewayState(serviceId) {
 export async function saveGatewayState(serviceId, state) {
   await ensureGatewayStateDir();
   const filePath = gatewayStatePath(serviceId);
-  const next = {
-    offset: Number.isFinite(Number(state?.offset)) ? Math.max(0, Math.floor(Number(state.offset))) : 0,
-    peers: state?.peers && typeof state.peers === "object" ? state.peers : {},
-    pendingPairings: state?.pendingPairings && typeof state.pendingPairings === "object" ? state.pendingPairings : {}
-  };
+  const next = normalizeGatewayState(state);
   const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
   await fs.writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
   await fs.rename(tmpPath, filePath);

package/src/gateway.js

@@ -4,7 +4,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { createSession, listSessions, loadSession, saveSession } from "./session-store.js";
-import { loadGatewayState, saveGatewayState } from "./gateway-state.js";
+import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayState, prunePendingPairings, saveGatewayState } from "./gateway-state.js";
 import { getGatewayStatus, getChannelSpec } from "./channels.js";
 
 const execFileAsync = promisify(execFile);
@@ -12,18 +12,64 @@ const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 const BIN_PATH = path.join(PACKAGE_ROOT, "bin", "waterbrother.js");
 const TELEGRAM_API_BASE = "https://api.telegram.org";
 const TELEGRAM_MESSAGE_LIMIT = 3900;
+const TELEGRAM_MAX_RETRIES = 4;
+const TELEGRAM_TYPING_INTERVAL_MS = 4000;
+const TELEGRAM_PREVIEW_TEXT = "<i>Working…</i>";
+const TELEGRAM_COMMANDS = [
+  { command: "help", description: "Show Telegram control help" },
+  { command: "status", description: "Show the linked remote session" },
+  { command: "runtime", description: "Show active runtime status" },
+  { command: "sessions", description: "List recent remote sessions" },
+  { command: "new", description: "Start a fresh remote session" },
+  { command: "clear", description: "Clear current remote conversation" }
+];
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function stringifyError(error) {
+  if (!error) return "unknown error";
+  if (typeof error === "string") return error;
+  return error.stderr || error.stdout || error.message || String(error);
+}
 
-function chunkText(text, maxLength = TELEGRAM_MESSAGE_LIMIT) {
+function escapeTelegramHtml(text) {
+  return String(text || "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function stripTelegramMarkup(text) {
+  return String(text || "")
+    .replace(/<pre><code>/g, "")
+    .replace(/<\/code><\/pre>/g, "")
+    .replace(/<code>/g, "`")
+    .replace(/<\/code>/g, "`")
+    .replace(/<b>/g, "")
+    .replace(/<\/b>/g, "")
+    .replace(/<i>/g, "")
+    .replace(/<\/i>/g, "")
+    .replace(/<s>/g, "")
+    .replace(/<\/s>/g, "")
+    .replace(/<a [^>]*href="([^"]+)"[^>]*>(.*?)<\/a>/g, "$2 ($1)")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+function splitLongPlainText(text, maxLength = TELEGRAM_MESSAGE_LIMIT) {
   const value = String(text || "").trim();
   if (!value) return [""];
   const chunks = [];
   let rest = value;
   while (rest.length > maxLength) {
-    let splitIndex = rest.lastIndexOf("\n", maxLength);
-    if (splitIndex < Math.floor(maxLength * 0.6)) {
-      splitIndex = rest.lastIndexOf(" ", maxLength);
-    }
-    if (splitIndex < Math.floor(maxLength * 0.5)) splitIndex = maxLength;
+    let splitIndex = rest.lastIndexOf("\n\n", maxLength);
+    if (splitIndex < Math.floor(maxLength * 0.55)) splitIndex = rest.lastIndexOf("\n", maxLength);
+    if (splitIndex < Math.floor(maxLength * 0.55)) splitIndex = rest.lastIndexOf(" ", maxLength);
+    if (splitIndex < Math.floor(maxLength * 0.45)) splitIndex = maxLength;
     chunks.push(rest.slice(0, splitIndex).trim());
     rest = rest.slice(splitIndex).trim();
   }
@@ -31,27 +77,101 @@ function chunkText(text, maxLength = TELEGRAM_MESSAGE_LIMIT) {
   return chunks.filter(Boolean);
 }
 
-function stringifyError(error) {
-  if (!error) return "unknown error";
-  if (typeof error === "string") return error;
-  return error.stderr || error.stdout || error.message || String(error);
+function splitCodeBlock(text, maxLength = TELEGRAM_MESSAGE_LIMIT) {
+  const lines = String(text || "").split("\n");
+  const chunks = [];
+  let current = [];
+  for (const line of lines) {
+    const next = [...current, line].join("\n");
+    if (next.length > maxLength && current.length) {
+      chunks.push(current.join("\n"));
+      current = [line];
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.length) chunks.push(current.join("\n"));
+  return chunks.filter(Boolean);
 }
 
-function escapeTelegramHtml(text) {
-  return String(text || "")
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+function tokenizeMarkdown(text) {
+  const source = String(text || "").replace(/\r\n/g, "\n");
+  if (!source.trim()) return [];
+  const tokens = [];
+  let index = 0;
+  while (index < source.length) {
+    const fenceStart = source.indexOf("```", index);
+    if (fenceStart === -1) {
+      const tail = source.slice(index);
+      if (tail.trim()) tokens.push({ type: "text", value: tail });
+      break;
+    }
+    const before = source.slice(index, fenceStart);
+    if (before.trim()) tokens.push({ type: "text", value: before });
+    const languageEnd = source.indexOf("\n", fenceStart + 3);
+    const language = languageEnd === -1 ? "" : source.slice(fenceStart + 3, languageEnd).trim();
+    const codeStart = languageEnd === -1 ? fenceStart + 3 : languageEnd + 1;
+    const fenceEnd = source.indexOf("```", codeStart);
+    if (fenceEnd === -1) {
+      const tail = source.slice(fenceStart);
+      if (tail.trim()) tokens.push({ type: "text", value: tail });
+      break;
+    }
+    const code = source.slice(codeStart, fenceEnd).replace(/^\n+|\n+$/g, "");
+    tokens.push({ type: "code", language, value: code });
+    index = fenceEnd + 3;
+  }
+  return tokens;
 }
 
-function renderTelegramMarkup(text) {
-  let value = escapeTelegramHtml(String(text || "").trim());
+function renderInlineTelegramHtml(text) {
+  let value = escapeTelegramHtml(String(text || ""));
+  value = value.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '<a href="$2">$1</a>');
   value = value.replace(/\*\*([^*\n][^*]*?)\*\*/g, "<b>$1</b>");
+  value = value.replace(/__([^_\n][^_]*?)__/g, "<b>$1</b>");
+  value = value.replace(/(^|[^*])\*([^*\n][^*]*?)\*(?!\*)/g, "$1<i>$2</i>");
+  value = value.replace(/(^|[^_])_([^_\n][^_]*?)_(?!_)/g, "$1<i>$2</i>");
+  value = value.replace(/~~([^~\n][^~]*?)~~/g, "<s>$1</s>");
   value = value.replace(/`([^`\n]+)`/g, "<code>$1</code>");
-  value = value.replace(/^\s*-\s+/gm, "• ");
   return value;
 }
 
+function normalizeTextBlock(text) {
+  return String(text || "")
+    .replace(/^\s{0,3}#{1,6}\s+/gm, "")
+    .replace(/^\s*[-*]\s+/gm, "• ")
+    .replace(/^\s*\d+\.\s+/gm, (match) => `${match.trim()} `)
+    .replace(/^>\s?/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function renderTelegramChunks(text, maxLength = TELEGRAM_MESSAGE_LIMIT) {
+  const tokens = tokenizeMarkdown(text);
+  if (!tokens.length) return [escapeTelegramHtml(String(text || "").trim()) || "(no content)"];
+
+  const rendered = [];
+  for (const token of tokens) {
+    if (token.type === "code") {
+      const source = token.value || "";
+      const codeChunks = splitCodeBlock(source, Math.max(1200, maxLength - 32));
+      for (const part of codeChunks) {
+        rendered.push(`<pre><code>${escapeTelegramHtml(part)}</code></pre>`);
+      }
+      continue;
+    }
+
+    const normalized = normalizeTextBlock(token.value);
+    if (!normalized) continue;
+    const textChunks = splitLongPlainText(normalized, maxLength - 64);
+    for (const part of textChunks) {
+      rendered.push(renderInlineTelegramHtml(part));
+    }
+  }
+
+  return rendered.length ? rendered : ["(no content)"];
+}
+
 function buildRemoteHelp() {
   return [
     "<b>Waterbrother Telegram control</b>",
@@ -125,6 +245,25 @@ function formatSessionListMarkup(currentSessionId, sessions = []) {
   return lines.join("\n");
 }
 
+function extractRetryDelayMs(error, attempt) {
+  const retryAfter = Number(error?.retryAfterSeconds);
+  if (Number.isFinite(retryAfter) && retryAfter > 0) {
+    return retryAfter * 1000;
+  }
+  const base = 400 * (2 ** attempt);
+  const jitter = Math.floor(Math.random() * 250);
+  return Math.min(5000, base + jitter);
+}
+
+function shouldRetryTelegramError(error) {
+  if (!error) return false;
+  if (error.permanent) return false;
+  if (error.isParseModeError) return false;
+  if (error.isNetworkError) return true;
+  const status = Number(error.status || 0);
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
 class TelegramGateway {
   constructor({ runtime, cwd, io = console }) {
     this.runtime = runtime;
@@ -143,30 +282,75 @@ class TelegramGateway {
     return `${TELEGRAM_API_BASE}/bot${this.botToken}`;
   }
 
-  async callApi(method, payload = {}) {
-    const response = await fetch(`${this.apiBase}/${method}`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(payload)
-    });
-    const json = await response.json().catch(() => ({}));
-    if (!response.ok || json?.ok === false) {
-      throw new Error(`Telegram API ${method} failed: ${json?.description || response.statusText || response.status}`);
+  get pairingExpiryMinutes() {
+    const raw = Number(this.channel.pairingExpiryMinutes);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_PENDING_PAIRING_TTL_MINUTES;
+  }
+
+  async callApi(method, payload = {}, { allowPlainFallback = false } = {}) {
+    let lastError = null;
+    for (let attempt = 0; attempt < TELEGRAM_MAX_RETRIES; attempt += 1) {
+      try {
+        const response = await fetch(`${this.apiBase}/${method}`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(payload)
+        });
+        const json = await response.json().catch(() => ({}));
+        if (!response.ok || json?.ok === false) {
+          const error = new Error(`Telegram API ${method} failed: ${json?.description || response.statusText || response.status}`);
+          error.status = response.status;
+          error.description = json?.description || "";
+          error.retryAfterSeconds = Number(json?.parameters?.retry_after || 0) || 0;
+          error.isParseModeError = /parse entities|can't parse/i.test(error.description);
+          if (allowPlainFallback && error.isParseModeError && payload.parse_mode) {
+            const fallbackPayload = { ...payload };
+            delete fallbackPayload.parse_mode;
+            fallbackPayload.text = stripTelegramMarkup(String(payload.text || ""));
+            return this.callApi(method, fallbackPayload, { allowPlainFallback: false });
+          }
+          throw error;
+        }
+        return json.result;
+      } catch (error) {
+        const wrapped = error instanceof Error ? error : new Error(String(error));
+        if (wrapped.name === "TypeError" && !wrapped.status) {
+          wrapped.isNetworkError = true;
+        }
+        lastError = wrapped;
+        if (!shouldRetryTelegramError(wrapped) || attempt === TELEGRAM_MAX_RETRIES - 1) {
+          throw wrapped;
+        }
+        await sleep(extractRetryDelayMs(wrapped, attempt));
+      }
     }
-    return json.result;
+    throw lastError || new Error(`Telegram API ${method} failed`);
   }
 
-  async sendMessage(chatId, text, replyToMessageId = null, { parseMode = "HTML" } = {}) {
-    const chunks = chunkText(text);
+  async sendMessage(chatId, text, replyToMessageId = null, { parseMode = "HTML", disableWebPagePreview = true } = {}) {
+    const chunks = parseMode === "HTML" ? renderTelegramChunks(text) : splitLongPlainText(text);
+    const sent = [];
     for (const chunk of chunks) {
-      await this.callApi("sendMessage", {
+      const result = await this.callApi("sendMessage", {
         chat_id: chatId,
         text: chunk,
         reply_to_message_id: replyToMessageId || undefined,
         parse_mode: parseMode || undefined,
-        disable_web_page_preview: true
-      });
+        disable_web_page_preview: disableWebPagePreview
+      }, { allowPlainFallback: parseMode === "HTML" });
+      sent.push(result);
     }
+    return sent;
+  }
+
+  async editMessage(chatId, messageId, text, { parseMode = "HTML", disableWebPagePreview = true } = {}) {
+    return this.callApi("editMessageText", {
+      chat_id: chatId,
+      message_id: messageId,
+      text,
+      parse_mode: parseMode || undefined,
+      disable_web_page_preview: disableWebPagePreview
+    }, { allowPlainFallback: parseMode === "HTML" });
   }
 
   async getMe() {
@@ -181,12 +365,29 @@ class TelegramGateway {
     });
   }
 
+  async registerCommands() {
+    await this.callApi("setMyCommands", {
+      commands: TELEGRAM_COMMANDS
+    });
+  }
+
   isAuthorizedUser(from) {
     const userId = String(from?.id || "").trim();
     const allowed = Array.isArray(this.channel.allowedUserIds) ? this.channel.allowedUserIds.map((value) => String(value)) : [];
     return allowed.includes(userId);
   }
 
+  prunePairings() {
+    const { state, pruned } = prunePendingPairings(this.state, this.pairingExpiryMinutes);
+    this.state = state;
+    return pruned;
+  }
+
+  async persistState() {
+    this.prunePairings();
+    await saveGatewayState("telegram", this.state);
+  }
+
   async addPendingPairing(message) {
     const userId = String(message?.from?.id || "").trim();
     const username = [message?.from?.username, message?.from?.first_name, message?.from?.last_name].filter(Boolean).join(" ").trim();
@@ -198,7 +399,7 @@ class TelegramGateway {
       lastSeenAt: new Date().toISOString(),
       lastMessageId: message.message_id
     };
-    await saveGatewayState("telegram", this.state);
+    await this.persistState();
   }
 
   async rejectUnpairedMessage(message) {
@@ -208,12 +409,13 @@ class TelegramGateway {
       message.chat.id,
       [
         "<b>Pairing required</b>",
-        `This Telegram account is not paired with Waterbrother yet.`,
+        "This Telegram account is not paired with Waterbrother yet.",
         `Your Telegram user id is: <code>${escapeTelegramHtml(userId)}</code>`,
         "",
         "Approve it locally with:",
         `<code>waterbrother gateway pair telegram ${escapeTelegramHtml(userId)}</code>`,
         "",
+        `Pending pairing requests expire after <code>${escapeTelegramHtml(this.pairingExpiryMinutes)}</code> minutes.`,
         "Then keep the gateway running and send your message again."
       ].join("\n"),
       message.message_id,
@@ -238,7 +440,7 @@ class TelegramGateway {
         lastSeenAt: new Date().toISOString(),
         lastMessageId: message.message_id
       };
-      await saveGatewayState("telegram", this.state);
+      await this.persistState();
       return existing.sessionId;
     }
 
@@ -263,7 +465,7 @@ class TelegramGateway {
       lastMessageId: message.message_id
     };
     delete this.state.pendingPairings[userId];
-    await saveGatewayState("telegram", this.state);
+    await this.persistState();
     return session.id;
   }
 
@@ -292,7 +494,7 @@ class TelegramGateway {
       lastMessageId: message.message_id
     };
     delete this.state.pendingPairings[userId];
-    await saveGatewayState("telegram", this.state);
+    await this.persistState();
     return session.id;
   }
 
@@ -322,7 +524,7 @@ class TelegramGateway {
       lastSeenAt: new Date().toISOString(),
       lastMessageId: message.message_id
     };
-    await saveGatewayState("telegram", this.state);
+    await this.persistState();
     return session.id;
   }
 
@@ -381,9 +583,70 @@ class TelegramGateway {
     return JSON.parse(stdout);
   }
 
+  async startTypingLoop(chatId) {
+    let stopped = false;
+    const tick = async () => {
+      while (!stopped) {
+        try {
+          await this.callApi("sendChatAction", {
+            chat_id: chatId,
+            action: "typing"
+          });
+        } catch {
+          // Best-effort only.
+        }
+        await sleep(TELEGRAM_TYPING_INTERVAL_MS);
+      }
+    };
+    const promise = tick();
+    return async () => {
+      stopped = true;
+      await promise.catch(() => {});
+    };
+  }
+
+  async sendProgressMessage(chatId, replyToMessageId) {
+    const [message] = await this.sendMessage(chatId, TELEGRAM_PREVIEW_TEXT, replyToMessageId, { parseMode: "HTML" });
+    return message || null;
+  }
+
+  async deliverPromptResult(chatId, replyToMessageId, previewMessage, content) {
+    const chunks = renderTelegramChunks(content);
+    if (!chunks.length) {
+      if (previewMessage?.message_id) {
+        await this.editMessage(chatId, previewMessage.message_id, "(no content)");
+      } else {
+        await this.sendMessage(chatId, "(no content)", replyToMessageId);
+      }
+      return;
+    }
+
+    if (previewMessage?.message_id) {
+      await this.editMessage(chatId, previewMessage.message_id, chunks[0]);
+      for (const chunk of chunks.slice(1)) {
+        await this.sendMessage(chatId, chunk, null, { parseMode: "HTML" });
+      }
+      return;
+    }
+
+    for (const [index, chunk] of chunks.entries()) {
+      await this.sendMessage(chatId, chunk, index === 0 ? replyToMessageId : null, { parseMode: "HTML" });
+    }
+  }
+
+  async deliverPromptFailure(chatId, replyToMessageId, previewMessage, error) {
+    const text = `<b>Remote run failed</b>\n${escapeTelegramHtml(stringifyError(error).slice(0, 3000))}`;
+    if (previewMessage?.message_id) {
+      await this.editMessage(chatId, previewMessage.message_id, text, { parseMode: "HTML" });
+      return;
+    }
+    await this.sendMessage(chatId, text, replyToMessageId, { parseMode: "HTML" });
+  }
+
   async handleTextMessage(message) {
     if (!message?.chat || message.chat.type !== "private") return;
     if (!message?.text) return;
+    this.prunePairings();
     if (!this.isAuthorizedUser(message.from)) {
       await this.rejectUnpairedMessage(message);
       return;
@@ -399,7 +662,7 @@ class TelegramGateway {
 
     if (text === "/new") {
       const sessionId = await this.startFreshSession(message);
-      await this.sendMessage(message.chat.id, `Started new remote session: ${sessionId}`, message.message_id);
+      await this.sendMessage(message.chat.id, `Started new remote session: <code>${escapeTelegramHtml(sessionId)}</code>`, message.message_id);
       return;
     }
 
@@ -464,25 +727,16 @@ class TelegramGateway {
       return;
     }
 
+    const stopTyping = await this.startTypingLoop(message.chat.id);
+    let previewMessage = null;
     try {
-      await this.callApi("sendChatAction", {
-        chat_id: message.chat.id,
-        action: "typing"
-      });
-    } catch {
-      // Best-effort only.
-    }
-
-    try {
+      previewMessage = await this.sendProgressMessage(message.chat.id, message.message_id);
       const content = await this.runPrompt(sessionId, text);
-      await this.sendMessage(message.chat.id, renderTelegramMarkup(content), message.message_id);
+      await this.deliverPromptResult(message.chat.id, message.message_id, previewMessage, content);
     } catch (error) {
-      await this.sendMessage(
-        message.chat.id,
-        `<b>Remote run failed</b>\n${escapeTelegramHtml(stringifyError(error).slice(0, 3000))}`,
-        message.message_id,
-        { parseMode: "HTML" }
-      );
+      await this.deliverPromptFailure(message.chat.id, message.message_id, previewMessage, error);
+    } finally {
+      await stopTyping();
     }
   }
 
@@ -501,7 +755,10 @@ class TelegramGateway {
     }
 
     this.state = await loadGatewayState("telegram");
+    this.prunePairings();
     const me = await this.getMe();
+    await this.registerCommands();
+    await this.persistState();
     this.io.log?.(`Telegram gateway connected as @${me.username || me.id}`);
 
     for (;;) {
@@ -513,7 +770,7 @@ class TelegramGateway {
         }
         await this.handleUpdate(update);
       }
-      await saveGatewayState("telegram", this.state);
+      await this.persistState();
     }
   }
 }