telegram-agent-kit 0.1.0

package/dist/index.js

@@ -0,0 +1,803 @@
+// src/errors.ts
+var TelegramApiError = class extends Error {
+  constructor(error_code, description) {
+    super(`telegram api ${error_code}${description ? `: ${description}` : ""}`);
+    this.error_code = error_code;
+    this.description = description;
+    this.name = "TelegramApiError";
+  }
+  error_code;
+  description;
+};
+function isBadRequest(err) {
+  return err instanceof TelegramApiError && err.error_code === 400;
+}
+
+// src/format/chunk.ts
+var TELEGRAM_LIMIT = 4096;
+var CHUNK_TARGET = 4e3;
+var RICH_LIMIT = 32768;
+function chunkText(text) {
+  if (text.length <= TELEGRAM_LIMIT) return [text];
+  const chunks = [];
+  let rest = text;
+  while (rest.length > TELEGRAM_LIMIT) {
+    let cut = rest.lastIndexOf("\n\n", CHUNK_TARGET);
+    if (cut < 1) cut = rest.lastIndexOf("\n", CHUNK_TARGET);
+    if (cut < 1) cut = CHUNK_TARGET;
+    const code = rest.charCodeAt(cut - 1);
+    if (code >= 55296 && code <= 56319) cut -= 1;
+    chunks.push(rest.slice(0, cut));
+    rest = rest.slice(cut);
+  }
+  if (rest.length > 0) chunks.push(rest);
+  return chunks;
+}
+function safeSlice(text, max) {
+  if (text.length <= max) return text;
+  let cut = max;
+  const code = text.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut -= 1;
+  return text.slice(0, cut);
+}
+function chunkRich(md) {
+  if (md.length <= RICH_LIMIT) return [md];
+  const out = [];
+  let cur = "";
+  for (const block of md.split("\n\n")) {
+    const candidate = cur === "" ? block : `${cur}
+
+${block}`;
+    if (candidate.length <= RICH_LIMIT) {
+      cur = candidate;
+      continue;
+    }
+    if (cur !== "") {
+      out.push(cur);
+      cur = "";
+    }
+    if (block.length <= RICH_LIMIT) {
+      cur = block;
+      continue;
+    }
+    let rest = block;
+    while (rest.length > RICH_LIMIT) {
+      const cut = safeSlice(rest, RICH_LIMIT);
+      out.push(cut);
+      rest = rest.slice(cut.length);
+    }
+    cur = rest;
+  }
+  if (cur !== "") out.push(cur);
+  return out;
+}
+
+// src/format/md-to-html.ts
+var escapeHtml = (s) => s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var escapeAttr = (s) => escapeHtml(s).replaceAll('"', "&quot;");
+var MARKS = [
+  { marker: "**", tag: "b", underscore: false, single: false },
+  { marker: "__", tag: "b", underscore: true, single: false },
+  { marker: "*", tag: "i", underscore: false, single: true },
+  { marker: "_", tag: "i", underscore: true, single: true },
+  { marker: "~~", tag: "s", underscore: false, single: false }
+];
+var WORD_RE = /[\p{L}\p{N}_]/u;
+var isWord = (ch) => ch !== void 0 && WORD_RE.test(ch);
+var isSpace = (ch) => ch !== void 0 && /\s/.test(ch);
+function findOpener(text, m, from) {
+  for (let p = text.indexOf(m.marker, from); p !== -1; p = text.indexOf(m.marker, p + 1)) {
+    const next = text[p + m.marker.length];
+    if (next === void 0 || isSpace(next)) continue;
+    if (m.single && (next === m.marker || text[p - 1] === m.marker)) continue;
+    if (m.underscore && isWord(text[p - 1])) continue;
+    return p;
+  }
+  return -1;
+}
+function findCloser(text, m, from) {
+  for (let p = text.indexOf(m.marker, from); p !== -1; p = text.indexOf(m.marker, p + 1)) {
+    if (p === from) continue;
+    const prev = text[p - 1];
+    if (prev === void 0 || isSpace(prev)) continue;
+    if (m.single && (prev === m.marker || text[p + m.marker.length] === m.marker))
+      continue;
+    if (m.underscore && isWord(text[p + m.marker.length])) continue;
+    return p;
+  }
+  return -1;
+}
+function renderMarks(text, level, autoClose) {
+  const m = MARKS[level];
+  if (m === void 0) return escapeHtml(text);
+  let out = "";
+  let rest = text;
+  for (; ; ) {
+    const open = findOpener(rest, m, 0);
+    if (open === -1) return out + renderMarks(rest, level + 1, autoClose);
+    const close = findCloser(rest, m, open + m.marker.length);
+    if (close === -1) {
+      const tail = rest.slice(open + m.marker.length);
+      if (autoClose && tail.length > 0) {
+        return out + renderMarks(rest.slice(0, open), level + 1, false) + `<${m.tag}>${renderMarks(tail, level + 1, false)}</${m.tag}>`;
+      }
+      out += renderMarks(
+        rest.slice(0, open + m.marker.length),
+        level + 1,
+        false
+      );
+      rest = tail;
+      continue;
+    }
+    out += renderMarks(rest.slice(0, open), level + 1, false) + `<${m.tag}>${renderMarks(
+      rest.slice(open + m.marker.length, close),
+      level + 1,
+      false
+    )}</${m.tag}>`;
+    rest = rest.slice(close + m.marker.length);
+  }
+}
+var URL_RE = /^https?:\/\/[^\s()]*$/;
+function matchLink(text) {
+  let lb = text.indexOf("[");
+  while (lb !== -1) {
+    const rb = text.indexOf("]", lb + 1);
+    if (rb === -1) return null;
+    if (text[rb + 1] === "(") {
+      const rp = text.indexOf(")", rb + 2);
+      if (rp === -1) return null;
+      const url = text.slice(rb + 2, rp);
+      if (URL_RE.test(url)) {
+        return {
+          index: lb,
+          length: rp + 1 - lb,
+          label: text.slice(lb + 1, rb),
+          url
+        };
+      }
+    }
+    lb = text.indexOf("[", lb + 1);
+  }
+  return null;
+}
+function renderLinks(text, autoClose) {
+  let out = "";
+  let rest = text;
+  for (; ; ) {
+    const m = matchLink(rest);
+    if (m === null) return out + renderMarks(rest, 0, autoClose);
+    out += renderMarks(rest.slice(0, m.index), 0, false) + `<a href="${escapeAttr(m.url)}">${renderMarks(m.label, 0, false)}</a>`;
+    rest = rest.slice(m.index + m.length);
+  }
+}
+function renderCode(text, autoClose) {
+  let out = "";
+  let rest = text;
+  for (; ; ) {
+    const open = rest.indexOf("`");
+    if (open === -1) return out + renderLinks(rest, autoClose);
+    const close = rest.indexOf("`", open + 1);
+    if (close === -1) {
+      const inner = rest.slice(open + 1);
+      if (autoClose && inner.length > 0) {
+        return out + renderLinks(rest.slice(0, open), false) + `<code>${escapeHtml(inner)}</code>`;
+      }
+      return out + renderLinks(rest, autoClose);
+    }
+    if (close === open + 1) {
+      out += renderLinks(rest.slice(0, close + 1), false);
+      rest = rest.slice(close + 1);
+      continue;
+    }
+    out += renderLinks(rest.slice(0, open), false) + `<code>${escapeHtml(rest.slice(open + 1, close))}</code>`;
+    rest = rest.slice(close + 1);
+  }
+}
+function renderInline(line, autoClose) {
+  return renderCode(line, autoClose);
+}
+var FENCE_OPEN_RE = /^(`{3,}|~{3,})\s*(.*)$/;
+var TICK_CLOSE_RE = /^`{3,}\s*$/;
+var TILDE_CLOSE_RE = /^~{3,}\s*$/;
+var LANG_RE = /^[A-Za-z0-9_+-]+$/;
+function fenceLang(info) {
+  const token = info.trim().split(/\s+/)[0] ?? "";
+  return token !== "" && LANG_RE.test(token) ? token : null;
+}
+function renderFence(body, lang) {
+  const code = escapeHtml(body);
+  return lang === null ? `<pre>${code}</pre>` : `<pre><code class="language-${lang}">${code}</code></pre>`;
+}
+var CODE_SPAN_RE = /<code>[\s\S]*?<\/code>/g;
+function boldHeading(html) {
+  let out = "";
+  let last = 0;
+  for (const m of html.matchAll(CODE_SPAN_RE)) {
+    const before = html.slice(last, m.index);
+    if (before !== "") out += `<b>${before}</b>`;
+    out += m[0];
+    last = m.index + m[0].length;
+  }
+  const tail = html.slice(last);
+  if (tail !== "") out += `<b>${tail}</b>`;
+  return out;
+}
+function mdToTelegramHtml(md, opts = {}) {
+  const partial = opts.partial === true;
+  const lines = md.split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    const fence = FENCE_OPEN_RE.exec(line);
+    if (fence !== null) {
+      const closeRe = (fence[1] ?? "").startsWith("`") ? TICK_CLOSE_RE : TILDE_CLOSE_RE;
+      const lang = fenceLang(fence[2] ?? "");
+      let close = -1;
+      for (let j = i + 1; j < lines.length; j += 1) {
+        if (closeRe.test(lines[j] ?? "")) {
+          close = j;
+          break;
+        }
+      }
+      if (close !== -1) {
+        out.push(renderFence(lines.slice(i + 1, close).join("\n"), lang));
+        i = close + 1;
+      } else if (partial) {
+        const body = lines.slice(i + 1).join("\n");
+        out.push(body.length > 0 ? renderFence(body, lang) : escapeHtml(line));
+        i = lines.length;
+      } else {
+        out.push(escapeHtml(lines.slice(i).join("\n")));
+        i = lines.length;
+      }
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      const quoted = [];
+      let j = i;
+      while (j < lines.length && /^>\s?/.test(lines[j] ?? "")) {
+        quoted.push((lines[j] ?? "").replace(/^>\s?/, ""));
+        j += 1;
+      }
+      const lastQuoted = partial && j === lines.length;
+      const inner = quoted.map((q, k) => renderInline(q, lastQuoted && k === quoted.length - 1)).join("\n");
+      out.push(
+        inner.trim() === "" ? escapeHtml(lines.slice(i, j).join("\n")) : `<blockquote>${inner}</blockquote>`
+      );
+      i = j;
+      continue;
+    }
+    const autoClose = partial && i === lines.length - 1;
+    const heading = /^#{1,6}\s+(.*)$/.exec(line);
+    if (heading !== null) {
+      out.push(boldHeading(renderInline(heading[1] ?? "", autoClose)));
+      i += 1;
+      continue;
+    }
+    const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line);
+    if (bullet !== null) {
+      out.push(
+        `${bullet[1] ?? ""}\u2022 ${renderInline(bullet[2] ?? "", autoClose)}`
+      );
+      i += 1;
+      continue;
+    }
+    out.push(renderInline(line, autoClose));
+    i += 1;
+  }
+  return out.join("\n");
+}
+
+// src/format/rich.ts
+var TABLE_DELIM_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;
+var isPipeLine = (line) => line.includes("|");
+var isTableRowLine = (line) => /^\s*\|.*\|\s*$/.test(line);
+function isTableBlock(lines) {
+  return lines.length >= 2 && isPipeLine(lines[0] ?? "") && TABLE_DELIM_RE.test(lines[1] ?? "");
+}
+function isPipeParagraph(lines) {
+  return lines.length >= 1 && lines.every(isTableRowLine) && !isTableBlock(lines);
+}
+function endsAsTable(lines) {
+  return isTableBlock(lines) && lines.slice(2).every(isTableRowLine);
+}
+var FENCE_LINE_RE = /^ {0,3}(`{3,}|~{3,})(.*)/;
+var HTML_CODE_TAG_RE = /<(pre|code)(?:\s[^>]*)?>|<\/(pre|code)>/gi;
+function advanceHtmlLine(open, line) {
+  let cur = open;
+  for (const m of line.matchAll(HTML_CODE_TAG_RE)) {
+    const closing = m[0][1] === "/";
+    const tag = (m[1] ?? m[2])?.toLowerCase() === "pre" ? "pre" : "code";
+    if (cur === null) {
+      if (!closing) cur = { kind: "html", tag };
+    } else if (cur.kind === "html" && closing && tag === cur.tag) {
+      cur = null;
+    }
+  }
+  return cur;
+}
+function advanceCodeRegion(open, lines) {
+  let cur = open;
+  for (const line of lines) {
+    if (cur?.kind === "html") {
+      cur = advanceHtmlLine(cur, line);
+      continue;
+    }
+    const m = FENCE_LINE_RE.exec(line);
+    if (cur?.kind === "fence") {
+      if (m !== null) {
+        const run = m[1] ?? "";
+        if ((run[0] ?? "") === cur.char && run.length >= cur.len && (m[2] ?? "").trim() === "")
+          cur = null;
+      }
+      continue;
+    }
+    if (m !== null) {
+      const run = m[1] ?? "";
+      const info = m[2] ?? "";
+      const char = run[0] ?? "";
+      if (char === "`" && info.includes("`")) {
+        cur = advanceHtmlLine(null, line);
+      } else {
+        cur = { kind: "fence", char, len: run.length };
+      }
+      continue;
+    }
+    cur = advanceHtmlLine(null, line);
+  }
+  return cur;
+}
+function repairRichTables(md) {
+  if (!md.includes("|")) return md;
+  const out = [];
+  let region = null;
+  let prevTable = false;
+  for (const block of md.split("\n\n")) {
+    const lines = block.split("\n");
+    const insideCode = region !== null;
+    const prev = out[out.length - 1];
+    if (!insideCode && prev !== void 0 && prevTable && isPipeParagraph(lines)) {
+      out[out.length - 1] = `${prev}
+${block}`;
+    } else {
+      out.push(block);
+      prevTable = !insideCode && endsAsTable(lines);
+    }
+    region = advanceCodeRegion(region, lines);
+  }
+  return out.join("\n\n");
+}
+var TRAILING_COVER_RE = /^!\[[^\]]*\]\(\s*(https?:\/\/[^\s)]+)[^)]*\)$/;
+function insideCodeRegion(lines, idx) {
+  return advanceCodeRegion(null, lines.slice(0, idx)) !== null;
+}
+function extractTrailingCover(md) {
+  let end = md.length - 1;
+  while (end >= 0 && /\s/.test(md[end] ?? "")) end--;
+  if (end < 0 || md[end] !== ")") return null;
+  const lines = md.split("\n");
+  let i = lines.length - 1;
+  while (i >= 0 && (lines[i] ?? "").trim() === "") i--;
+  if (i < 0) return null;
+  const m = TRAILING_COVER_RE.exec((lines[i] ?? "").trim());
+  if (m === null) return null;
+  if (insideCodeRegion(lines, i)) return null;
+  const url = m[1] ?? "";
+  const body = lines.slice(0, i).join("\n").replace(/\s+$/, "");
+  return { url, body };
+}
+var RICH_MEDIA_RE = new RegExp(
+  [
+    // fenced code block (```+) — line-anchored open; close on a ≥open run that
+    // owns its own line, else code through EOF.
+    "(?:^|\\n)[ ]{0,3}(`{3,})[^\\n`]*(?:[\\s\\S]*?\\n[ ]{0,3}\\1`*[ \\t]*(?=\\n|$)|[\\s\\S]*)",
+    // fenced code block (~~~+) — same, tilde info strings may contain backticks.
+    "(?:^|\\n)[ ]{0,3}(~{3,})[^\\n]*(?:[\\s\\S]*?\\n[ ]{0,3}\\2~*[ \\t]*(?=\\n|$)|[\\s\\S]*)",
+    // inline code span — both delimiters must be COMPLETE backtick runs of EQUAL
+    // length (CommonMark/GFM): opener `(?<!`)(`+)(?!`)` is a whole run, close
+    // `(?<!`)\3(?!`)` is a same-length whole run — never a prefix/suffix of a
+    // longer one. So a `` … `` span keeps an inner single ` and its nested media
+    // literal, while a stray ` adjacent to a longer run is not a span and its real
+    // media still neutralizes.
+    "(?<!`)(`+)(?!`)[\\s\\S]*?(?<!`)\\3(?!`)",
+    // HTML code regions — Rich Markdown honors Telegram's Rich HTML tag subset
+    // (docs: "can contain arbitrary HTML; supported tags are parsed as in Rich
+    // HTML style"), in which <pre> (block) and <code> (inline) are fixed-width
+    // code: their body is literal, so a nested ![](…) is NOT a media send and
+    // must stay verbatim — same rationale as the backtick/tilde branches. Both
+    // are NON-capturing so the media groups stay 4/5/6. Lazy to the first close;
+    // <pre> is listed before <code> so a <pre><code>…</code></pre> is consumed as
+    // ONE region. Optional attributes (e.g. <code class="language-ts">) are
+    // allowed, and the `(?:\s[^>]*)?` guard keeps <codex>/<press> from matching.
+    // Only CLOSED regions skip: an unterminated <pre>/<code> is left to
+    // neutralize (the reply-safe default — and CommonMark would not treat a raw
+    // open tag as code through EOF either, unlike a fence).
+    "<pre(?:\\s[^>]*)?>[\\s\\S]*?</pre>",
+    "<code(?:\\s[^>]*)?>[\\s\\S]*?</code>",
+    // backslash escaping, parity-aware: consume escaped-backslash PAIRS first so
+    // only an ODD run of backslashes escapes the `!`. `\![…]` (1 backslash) is a
+    // literal `!`; `\\![…]` (2 backslashes = one literal `\`) leaves the `!`
+    // unescaped, so the pair is skipped and the real media still neutralizes.
+    "\\\\\\\\",
+    // an escaped-backslash pair — skipped so it can't falsely escape a following `!`
+    "\\\\!",
+    // a single backslash + `!` — a genuinely escaped `!`, not a media start
+    "!\\[([^\\]]*)\\]\\(\\s*(https?:\\/\\/[^\\s)]+)([^)]*)\\)"
+    // media image (groups 4,5,6)
+  ].join("|"),
+  "g"
+);
+function neutralizeRichMedia(md) {
+  return md.replace(
+    RICH_MEDIA_RE,
+    (match, _btFence, _tildeFence, _inlineOpen, label, url, rest) => {
+      if (url === void 0) return match;
+      return label ? `[${label}](${url}${rest})` : url;
+    }
+  );
+}
+
+// src/bridge/send.ts
+var CAPTION_LIMIT = 1024;
+async function sendClassic(client, chatId, text, signal) {
+  for (const chunk of chunkText(text)) {
+    let html;
+    try {
+      html = mdToTelegramHtml(chunk);
+    } catch {
+      html = null;
+    }
+    if (html === null) {
+      await client.sendMessage({ chatId, text: chunk }, signal);
+      continue;
+    }
+    try {
+      await client.sendMessage(
+        { chatId, text: html, parseMode: "HTML" },
+        signal
+      );
+    } catch (err) {
+      if (!isBadRequest(err)) throw err;
+      await client.sendMessage({ chatId, text: chunk }, signal);
+    }
+  }
+}
+async function sendRich(client, chatId, markdown, log, signal) {
+  for (const piece of chunkRich(
+    neutralizeRichMedia(repairRichTables(markdown))
+  )) {
+    try {
+      await client.sendRichMessage({ chatId, markdown: piece }, signal);
+    } catch (err) {
+      if (!isBadRequest(err)) throw err;
+      log.warn("telegram rich fallback", {
+        method: "sendRichMessage",
+        error_code: err.error_code,
+        description: err.description,
+        chatId
+      });
+      await sendClassic(client, chatId, piece, signal);
+    }
+  }
+}
+async function sendText(client, chatId, text, opts, signal) {
+  if (opts.rich) await sendRich(client, chatId, text, opts.log, signal);
+  else await sendClassic(client, chatId, text, signal);
+}
+async function sendCover(client, chatId, url, caption, signal) {
+  if (caption === void 0 || caption === "") {
+    await client.sendPhoto({ chatId, url }, signal);
+    return;
+  }
+  let html;
+  try {
+    html = mdToTelegramHtml(caption);
+  } catch {
+    html = null;
+  }
+  if (html === null) {
+    await client.sendPhoto({ chatId, url, caption }, signal);
+    return;
+  }
+  try {
+    await client.sendPhoto(
+      { chatId, url, caption: html, parseMode: "HTML" },
+      signal
+    );
+  } catch (err) {
+    if (!isBadRequest(err)) throw err;
+    await client.sendPhoto({ chatId, url, caption }, signal);
+  }
+}
+async function sendReply(client, chatId, reply, opts, signal) {
+  const cover = extractTrailingCover(reply);
+  if (cover === null) {
+    await sendText(client, chatId, reply, opts, signal);
+    return;
+  }
+  const longBody = cover.body.length > CAPTION_LIMIT;
+  try {
+    if (longBody) await sendCover(client, chatId, cover.url, void 0, signal);
+    else await sendCover(client, chatId, cover.url, cover.body, signal);
+  } catch (err) {
+    if (!isBadRequest(err)) throw err;
+    await sendText(client, chatId, neutralizeRichMedia(reply), opts, signal);
+    return;
+  }
+  if (longBody) await sendText(client, chatId, cover.body, opts, signal);
+}
+
+// src/draft/constants.ts
+var DEFAULT_DRAFT_CONSTANTS = {
+  throttleMs: 300,
+  // min interval between draft content writes
+  keepaliveMs: 2e4,
+  // re-send last draft text within the ~30s expiry window
+  typingHeartbeatMs: 4500,
+  // re-send `typing` before its ~5s lifetime lapses
+  previewCap: 4e3,
+  // one-message cap for the live preview (= CHUNK_TARGET)
+  maxFailures: 3,
+  // consecutive send failures → disable draft for the turn
+  drainMs: 1e3,
+  // finalize() wait for an in-flight write before abandoning
+  tickMs: 250
+  // ticker granularity
+};
+
+// src/draft/draft-streamer.ts
+var defaultDelay = (ms) => {
+  let handle;
+  const promise = new Promise((resolve) => {
+    handle = setTimeout(resolve, ms);
+  });
+  return { promise, cancel: () => clearTimeout(handle) };
+};
+function createDraftStreamer(deps) {
+  const k = { ...DEFAULT_DRAFT_CONSTANTS, ...deps.constants };
+  const now = deps.now ?? (() => Date.now());
+  const schedule = deps.schedule ?? ((fn, ms) => setInterval(fn, ms));
+  const cancel = deps.cancel ?? ((h) => clearInterval(h));
+  const delay = deps.delay ?? defaultDelay;
+  const { client, chatId, draftId, log } = deps;
+  let latest = "";
+  let lastSent = null;
+  let lastSentAt = 0;
+  let lastAttemptAt = Number.NEGATIVE_INFINITY;
+  let lastTypingAt = 0;
+  let inFlight = null;
+  let inFlightController = null;
+  let consecutiveFailures = 0;
+  let disabled = false;
+  let richMode = deps.rich;
+  let stopped = false;
+  let timer = null;
+  function send(text, t) {
+    const controller = new AbortController();
+    inFlightController = controller;
+    lastAttemptAt = t;
+    const usingRich = richMode;
+    const op = usingRich ? client.sendRichMessageDraft(
+      { chatId, draftId, markdown: text },
+      controller.signal
+    ) : client.sendMessageDraft({ chatId, draftId, text }, controller.signal);
+    inFlight = op.then(() => {
+      lastSent = text;
+      lastSentAt = now();
+      consecutiveFailures = 0;
+    }).catch((err) => {
+      if (controller.signal.aborted) return;
+      if (usingRich && isBadRequest(err)) {
+        richMode = false;
+        log.warn("telegram draft rich disabled", {
+          chat_id: chatId,
+          method: "sendRichMessageDraft",
+          error_code: err.error_code,
+          description: err.description
+        });
+        return;
+      }
+      consecutiveFailures += 1;
+      if (consecutiveFailures >= k.maxFailures) {
+        disabled = true;
+        log.warn("telegram draft disabled after failures", {
+          chat_id: chatId,
+          failures: consecutiveFailures
+        });
+      } else {
+        log.warn("telegram draft send failed", { chat_id: chatId });
+      }
+    }).finally(() => {
+      inFlight = null;
+      inFlightController = null;
+    });
+  }
+  function maybeFlush() {
+    if (stopped || disabled || inFlight) return;
+    const t = now();
+    if (latest !== lastSent && latest.trim().length > 0 && t - lastAttemptAt >= k.throttleMs) {
+      send(latest, t);
+    } else if (lastSent !== null && t - lastSentAt >= k.keepaliveMs) {
+      send(lastSent, t);
+    }
+  }
+  function tick() {
+    maybeFlush();
+    if (!stopped && now() - lastTypingAt >= k.typingHeartbeatMs) {
+      client.sendChatAction({ chatId }).catch(() => {
+      });
+      lastTypingAt = now();
+    }
+  }
+  return {
+    start() {
+      lastTypingAt = now();
+      client.sendChatAction({ chatId }).catch(() => {
+      });
+      timer = schedule(tick, k.tickMs);
+    },
+    push(fullText) {
+      latest = safeSlice(fullText, k.previewCap);
+      maybeFlush();
+    },
+    async finalize() {
+      try {
+        stopped = true;
+        if (timer !== null) {
+          cancel(timer);
+          timer = null;
+        }
+        if (!inFlight) return;
+        const drain = delay(k.drainMs);
+        try {
+          const landed = await Promise.race([
+            inFlight.then(() => true),
+            drain.promise.then(() => false)
+          ]);
+          if (!landed) {
+            inFlightController?.abort();
+            await inFlight?.catch(() => {
+            });
+          }
+        } finally {
+          drain.cancel();
+        }
+      } catch (err) {
+        log.warn("telegram draft finalize error", { err: String(err) });
+      }
+    },
+    async abort() {
+      try {
+        stopped = true;
+        if (timer !== null) {
+          cancel(timer);
+          timer = null;
+        }
+        inFlightController?.abort();
+        await inFlight?.catch(() => {
+        });
+      } catch (err) {
+        log.warn("telegram draft abort error", { err: String(err) });
+      }
+    }
+  };
+}
+
+// src/bridge/turn-loop.ts
+var NOOP_LOG = { warn: () => {
+}, error: () => {
+} };
+async function runTelegramTurn(opts) {
+  const now = opts.now ?? (() => Date.now());
+  const log = opts.log ?? NOOP_LOG;
+  const makeDraftStreamer = opts.makeDraftStreamer ?? createDraftStreamer;
+  const ctx = { chatKey: opts.chatKey, userText: opts.userText };
+  let rollback = null;
+  let turnCompleted = false;
+  let draft = null;
+  let draftTornDown = false;
+  try {
+    if (opts.hooks?.beforeTurn) {
+      try {
+        await opts.hooks.beforeTurn(ctx);
+      } catch (err) {
+        log.error("telegram beforeTurn hook failed", { err: String(err) });
+      }
+    }
+    if (opts.hooks?.preStream) {
+      let res;
+      try {
+        res = await opts.hooks.preStream(ctx) ?? void 0;
+      } catch (err) {
+        log.error("telegram preStream hook failed", { err: String(err) });
+        res = void 0;
+      }
+      if (res?.skip) return;
+    }
+    const threadId = await opts.threadStore.resolve(opts.chatKey, now());
+    const checkpointId = await opts.checkpointer.snapshot(threadId);
+    rollback = { threadId, checkpointId };
+    draft = makeDraftStreamer({
+      client: opts.client,
+      chatId: opts.chatKey.chatId,
+      draftId: opts.draftId,
+      rich: opts.rich,
+      log,
+      constants: opts.draftConstants
+    });
+    draft.start();
+    let reply = "";
+    let errored = false;
+    for await (const ev of opts.agentStream(
+      { messages: [{ role: "user", content: opts.userText }] },
+      { threadId, signal: opts.signal }
+    )) {
+      if (ev.type === "token") {
+        reply += ev.text;
+        draft.push(reply);
+      } else if (ev.type === "error") errored = true;
+    }
+    if (errored) {
+      draftTornDown = true;
+      await draft.abort().catch(() => {
+      });
+      await opts.checkpointer.rollback(rollback.threadId, rollback.checkpointId).catch(
+        (e) => log.error("telegram rollback failed", { err: String(e) })
+      );
+      return;
+    }
+    draftTornDown = true;
+    await draft.finalize().catch(() => {
+    });
+    turnCompleted = true;
+    if (reply.trim().length > 0) {
+      await sendReply(
+        opts.client,
+        opts.chatKey.chatId,
+        reply,
+        { rich: opts.rich, log },
+        opts.signal
+      );
+    } else {
+      log.warn("telegram empty reply", { chatId: opts.chatKey.chatId });
+    }
+    await opts.threadStore.touch(opts.chatKey, now());
+  } catch (err) {
+    log.error("telegram turn failed", { err: String(err) });
+    if (rollback && !turnCompleted) {
+      draftTornDown = true;
+      await draft?.abort().catch(() => {
+      });
+      await opts.checkpointer.rollback(rollback.threadId, rollback.checkpointId).catch(
+        (e) => log.error("telegram rollback failed", { err: String(e) })
+      );
+    }
+  } finally {
+    if (!draftTornDown) await draft?.finalize().catch(() => {
+    });
+    if (opts.hooks?.afterTurn) {
+      try {
+        await opts.hooks.afterTurn(ctx);
+      } catch (err) {
+        log.error("telegram afterTurn hook failed", { err: String(err) });
+      }
+    }
+  }
+}
+export {
+  DEFAULT_DRAFT_CONSTANTS,
+  TelegramApiError,
+  chunkRich,
+  chunkText,
+  createDraftStreamer,
+  extractTrailingCover,
+  isBadRequest,
+  mdToTelegramHtml,
+  neutralizeRichMedia,
+  repairRichTables,
+  runTelegramTurn,
+  safeSlice,
+  sendReply,
+  sendText
+};