@wrongstack/telegram 0.309.1 → 0.310.0

package/dist/index.js

@@ -262,74 +262,253 @@ var TelegramApiClient = class {
   }
 };
 
-// src/bot.ts
-var TelegramBot = class _TelegramBot {
-  api;
-  pollIntervalMs;
-  allowedUsers;
-  allowedChats;
+// src/approval-flow.ts
+var ApprovalFlow = class {
+  callbackWaiters = /* @__PURE__ */ new Map();
   log;
-  onMessage;
-  controller = new AbortController();
-  pollTimer = null;
-  pollActive = false;
-  offset = 0;
+  api;
+  inboundDenialReason;
+  constructor(deps) {
+    this.log = deps.log;
+    this.api = deps.api;
+    this.inboundDenialReason = deps.inboundDenialReason;
+  }
+  settleApproval(requestId, state, result) {
+    const request = this.callbackWaiters.get(requestId);
+    if (request?.state !== "pending") return false;
+    request.state = state;
+    clearTimeout(request.timer);
+    if (request.signal && request.abortHandler) request.signal.removeEventListener("abort", request.abortHandler);
+    const leftover = request.pendingCallbacks.splice(0);
+    for (const cq of leftover) {
+      const notice = state === "expired" ? "Approval request expired" : state === "cancelled" ? "Approval request cancelled" : "Approval request settled";
+      void this.answerCallback(cq.id, notice, true);
+    }
+    this.callbackWaiters.delete(requestId);
+    request.resolve(result);
+    return true;
+  }
+  async dispatchCallback(cq) {
+    const key = cq.data ?? "";
+    const action = /^approve:([^:]+):(yes|no)$/.exec(key);
+    const requestId = action?.[1];
+    const request = requestId ? this.callbackWaiters.get(requestId) : void 0;
+    const userId = cq.from?.id !== void 0 ? String(cq.from.id) : void 0;
+    const chatId = cq.message?.chat.id !== void 0 ? String(cq.message.chat.id) : void 0;
+    const denialReason = this.inboundDenialReason(userId, chatId);
+    if (denialReason) {
+      const identity = denialReason === "user" ? userId ?? "unknown" : chatId ?? "unknown";
+      this.log.warn(`Ignoring callback_query from non-allowlisted ${denialReason} ${identity} (data="${key}") \u2014 possible hijack attempt.`);
+      await this.answerCallback(cq.id, "\u26D4 Not authorized", true);
+      return;
+    }
+    if (!request || !requestId || !action) {
+      await this.answerCallback(cq.id, "Approval request unavailable", true);
+      this.log.debug(`Unmatched callback_query data="${key}" (no pending approval request)`);
+      return;
+    }
+    if (Date.now() >= request.expiresAt) {
+      await this.answerCallback(cq.id, "Approval request expired", true);
+      this.settleApproval(requestId, "expired", { approved: false, fromUser: "timeout" });
+      return;
+    }
+    if (request.promptMessageId === void 0) {
+      request.pendingCallbacks.push(cq);
+      return;
+    }
+    const messageId = cq.message?.message_id;
+    const chatType = cq.message?.chat.type;
+    const wrongIdentity = userId === void 0 || chatId !== request.expectedChatId || !request.expectedUserIds.has(userId) || messageId !== request.promptMessageId || chatType !== "private" && !request.allowGroup;
+    if (wrongIdentity) {
+      this.log.warn(`Ignoring callback_query that does not match approval request ${request.requestId} in session ${request.sessionId}.`);
+      await this.answerCallback(cq.id, "\u26D4 Not authorized for this approval", true);
+      return;
+    }
+    const approved = action[2] === "yes";
+    const fromUser = cq.from?.username ?? cq.from?.first_name ?? `user:${userId}`;
+    const resolved = this.settleApproval(requestId, "resolved", { approved, fromUser, fromUserId: cq.from?.id });
+    await this.answerCallback(cq.id, resolved ? approved ? "Approved \u2713" : "Denied \u2717" : "Approval request unavailable", !resolved);
+  }
+  async answerCallback(callbackQueryId, text, showAlert) {
+    try {
+      await this.api().answerCallbackQuery(callbackQueryId, text, showAlert, { signal: AbortSignal.timeout(5e3) });
+    } catch (err) {
+      this.log.debug(`answerCallbackQuery failed: ${err.message}`);
+    }
+  }
+  awaitApproval(input) {
+    if (input.expectedUserIds.length === 0) throw new Error("Telegram approval requires at least one expected user ID.");
+    if (this.callbackWaiters.has(input.requestId)) throw new Error(`Telegram approval request ${input.requestId} is already pending.`);
+    return new Promise((resolve) => {
+      const delayMs = Math.max(0, input.expiresAt - Date.now());
+      const timer = setTimeout(() => {
+        this.settleApproval(input.requestId, "expired", { approved: false, fromUser: "timeout" });
+      }, delayMs);
+      const request = { requestId: input.requestId, sessionId: input.sessionId, expectedChatId: String(input.expectedChatId), expectedUserIds: new Set(input.expectedUserIds.map(String)), allowGroup: input.allowGroup, pendingCallbacks: [], expiresAt: input.expiresAt, state: "pending", resolve, timer, signal: input.signal };
+      if (input.signal) request.abortHandler = () => {
+        this.settleApproval(input.requestId, "cancelled", { approved: false, fromUser: "aborted" });
+      };
+      this.callbackWaiters.set(input.requestId, request);
+      if (input.signal?.aborted) request.abortHandler?.();
+      else if (input.signal && request.abortHandler) input.signal.addEventListener("abort", request.abortHandler, { once: true });
+    });
+  }
+  bindApprovalPrompt(requestId, promptMessageId) {
+    const request = this.callbackWaiters.get(requestId);
+    if (request?.state !== "pending" || request.promptMessageId !== void 0) return false;
+    request.promptMessageId = promptMessageId;
+    const pending = request.pendingCallbacks.splice(0);
+    for (const callback of pending) void this.dispatchCallback(callback).catch((err) => this.log.debug(`Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`));
+    return true;
+  }
+  cancelApproval(requestId, fromUser = "cancelled") {
+    return this.settleApproval(requestId, "cancelled", { approved: false, fromUser });
+  }
+  cancelAll(fromUser) {
+    for (const requestId of Array.from(this.callbackWaiters.keys())) this.settleApproval(requestId, "cancelled", { approved: false, fromUser });
+  }
+};
+
+// src/inbox.ts
+var TelegramInbox = class {
+  deps;
+  // Circular buffer for incoming messages. Public readonly so the white-box
+  // suites can seed it directly through `bot.inbox.buffer` without
+  // type-asserting past module boundaries.
+  buffer = [];
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /** Return buffered messages, newest first. Optionally filter by chat. */
+  getMessages(opts) {
+    let msgs = [...this.buffer].reverse();
+    if (opts?.chatId) {
+      const cid = String(opts.chatId);
+      msgs = msgs.filter((m) => String(m.chatId) === cid);
+    }
+    const limit = opts?.limit ?? 20;
+    return msgs.slice(0, limit);
+  }
+  /** Drop messages older than or equal to the given message ID from the buffer (optionally scoped to a specific chat). */
+  acknowledge(lastMessageId, chatId) {
+    const before = this.buffer.length;
+    const cid = chatId !== void 0 && chatId !== null && String(chatId).trim() !== "" ? String(chatId).trim() : void 0;
+    const remaining = [];
+    for (const buffered of this.buffer) {
+      if (cid !== void 0) {
+        if (String(buffered.chatId) === cid && buffered.messageId <= lastMessageId) {
+          continue;
+        }
+      } else if (buffered.messageId <= lastMessageId) {
+        continue;
+      }
+      remaining.push(buffered);
+    }
+    this.buffer.length = 0;
+    this.buffer.push(...remaining);
+    return before - this.buffer.length;
+  }
+  get bufferCount() {
+    return this.buffer.length;
+  }
   /**
-   * Consecutive HTTP 409 ("another getUpdates in flight") responses. Two
-   * wstack instances polling the same bot token used to fight at full poll
-   * speed forever, erroring on every cycle. After CONFLICT_BACKOFF_AFTER
-   * consecutive conflicts this instance backs off to a slow poll and warns
-   * once; any successful poll resets to the normal cadence.
+   * Apply the inbound identity policy to every update type. A non-empty set is
+   * a mandatory constraint: missing identity fails closed instead of bypassing
+   * the allowlist. An empty set leaves that identity dimension unrestricted.
+   * Public because ApprovalFlow consumes the same gate via the bot's wiring.
    */
-  conflictStreak = 0;
-  static CONFLICT_BACKOFF_AFTER = 3;
-  static CONFLICT_POLL_MS = 6e4;
-  _startedAt = null;
-  /** Typed offset store for atomic polling-cursor persistence. */
+  denialReason(userId, chatId) {
+    if (this.deps.allowedChats.size > 0 && (chatId === void 0 || !this.deps.allowedChats.has(chatId))) {
+      return "chat";
+    }
+    if (this.deps.allowedUsers.size > 0 && (userId === void 0 || !this.deps.allowedUsers.has(userId))) {
+      return "user";
+    }
+    return void 0;
+  }
+  processMessage(msg) {
+    const chatId = String(msg.chat.id);
+    const userId = msg.from ? String(msg.from.id) : void 0;
+    const denialReason = this.denialReason(userId, chatId);
+    if (denialReason === "user") {
+      this.deps.log.debug(`Ignoring message from user ${userId ?? "unknown"} (not in allowedUsers)`);
+      void this.deps.sendNotice(chatId, "\u26D4 You are not authorized to interact with this bot.").catch(
+        (err) => this.deps.log.debug(
+          `Failed to send denial notice: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      return;
+    }
+    if (denialReason === "chat") {
+      this.deps.log.debug(`Ignoring message from chat ${chatId} (not in allowedChats)`);
+      return;
+    }
+    const incoming = {
+      messageId: msg.message_id,
+      chatId: msg.chat.id,
+      chatType: msg.chat.type,
+      userId: msg.from?.id,
+      userName: msg.from?.username ?? msg.from?.first_name,
+      text: msg.text,
+      timestamp: msg.date * 1e3
+    };
+    this.buffer.push(incoming);
+    while (this.buffer.length > this.deps.bufferMax) this.buffer.shift();
+    this.deps.onMessage(incoming);
+  }
+};
+
+// src/poller.ts
+var Poller = class _Poller {
+  api;
+  pollIntervalMs;
+  log;
+  controller;
   offsetStore;
-  /** Single-poller election across wstack instances sharing this token. */
   lock;
   standbyRetryMs;
-  getParseMode;
+  pollTimer = null;
   standbyTimer = null;
   standbyAnnounced = false;
-  // Circular buffer for incoming messages
-  bufferMax;
-  buffer = [];
-  // Pending approval requests keyed by request identity, not raw callback
-  // data. Each request binds both yes/no actions to its originating session,
-  // target chat, intended users, prompt message, and expiry.
-  callbackWaiters = /* @__PURE__ */ new Map();
-  constructor(opts) {
-    this.api = new TelegramApiClient({ token: opts.token });
-    this.pollIntervalMs = opts.pollIntervalSec * 1e3;
-    this.allowedUsers = opts.allowedUsers;
-    this.allowedChats = opts.allowedChats;
-    this.bufferMax = opts.bufferSize;
-    this.log = opts.log;
-    this.onMessage = opts.onMessage;
-    this.offsetStore = opts.offsetStore;
-    this.lock = opts.lock;
-    this.standbyRetryMs = opts.standbyRetryMs ?? 15e3;
-    this.getParseMode = opts.getParseMode;
-    if (this.lock) {
-      this.lock.onLost = () => this.handleLockLost();
-    }
-    if (this.offsetStore) {
-      void this.loadOffset();
-    }
+  pollActive = false;
+  _startedAt = null;
+  offset = 0;
+  _conflictStreak = 0;
+  static CONFLICT_BACKOFF_AFTER = 3;
+  static CONFLICT_POLL_MS = 6e4;
+  onCallbackQuery;
+  onMessageUpdate;
+  constructor(deps) {
+    this.api = deps.api;
+    this.pollIntervalMs = deps.pollIntervalMs;
+    this.log = deps.log;
+    this.controller = deps.controller;
+    this.offsetStore = deps.offsetStore;
+    this.lock = deps.lock;
+    this.standbyRetryMs = deps.standbyRetryMs;
+    this.onCallbackQuery = deps.onCallbackQuery;
+    this.onMessageUpdate = deps.onMessageUpdate;
+    if (this.lock) this.lock.onLost = () => this.handleLockLost();
+    if (this.offsetStore) void this.loadOffset();
+  }
+  get active() {
+    return this.pollActive;
+  }
+  get startedAt() {
+    return this._startedAt;
+  }
+  get standby() {
+    return this.pollActive && this.lock !== void 0 && !this.lock.held;
+  }
+  get conflictStreak() {
+    return this._conflictStreak;
   }
-  // ------------------------------------------------------------------
-  // Lifecycle
-  // ------------------------------------------------------------------
-  /** Start polling for updates. Idempotent. */
   start() {
     if (this.pollActive) return;
     this.pollActive = true;
     this._startedAt = Date.now();
     this.acquireAndPoll();
   }
-  /** Stop polling and cancel all in-flight requests. */
   stop() {
     this.pollActive = false;
     this.controller.abort();
@@ -341,31 +520,13 @@ var TelegramBot = class _TelegramBot {
       clearTimeout(this.standbyTimer);
       this.standbyTimer = null;
     }
-    for (const requestId of Array.from(this.callbackWaiters.keys())) {
-      this.settleApproval(requestId, "cancelled", {
-        approved: false,
-        fromUser: "shutdown"
-      });
-    }
-    this.lock?.release();
-    this.log.info("Telegram bot stopped");
-  }
-  /** True when the bot is started but waiting for the poll lock. */
-  get standby() {
-    return this.pollActive && this.lock !== void 0 && !this.lock.held;
   }
-  /**
-   * Acquire the poll lock (when configured) and start the poll loop, or
-   * stand by and retry until the current holder releases it.
-   */
   acquireAndPoll() {
     if (!this.pollActive) return;
     if (this.lock && !this.lock.tryAcquire()) {
       if (!this.standbyAnnounced) {
         this.standbyAnnounced = true;
-        this.log.info(
-          "Telegram: another wstack instance is already polling this bot token \u2014 standing by; will take over when it stops."
-        );
+        this.log.info("Telegram: another wstack instance is already polling this bot token \u2014 standing by; will take over when it stops.");
       }
       this.standbyTimer = setTimeout(() => this.acquireAndPoll(), this.standbyRetryMs);
       this.standbyTimer.unref?.();
@@ -374,78 +535,100 @@ var TelegramBot = class _TelegramBot {
     if (this.standbyAnnounced) {
       this.standbyAnnounced = false;
       this.log.info("Telegram: poll lock acquired \u2014 taking over polling.");
-    } else {
-      this.log.info(`Telegram bot polling started (${this.api.safeBaseUrl})`);
-    }
+    } else this.log.info(`Telegram bot polling started (${this.api().safeBaseUrl})`);
     this.schedulePoll();
   }
-  /** The lock was stolen while we held it — pause polling and stand by. */
   handleLockLost() {
     if (!this.pollActive) return;
     if (this.pollTimer) {
       clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
-    this.log.warn(
-      "Telegram: poll lock lost to another instance \u2014 pausing polling and standing by."
-    );
+    this.log.warn("Telegram: poll lock lost to another instance \u2014 pausing polling and standing by.");
     this.standbyAnnounced = true;
     this.standbyTimer = setTimeout(() => this.acquireAndPoll(), this.standbyRetryMs);
     this.standbyTimer.unref?.();
   }
-  get startedAt() {
-    return this._startedAt;
-  }
-  get running() {
-    return this.pollActive;
-  }
-  // ------------------------------------------------------------------
-  // Buffer — incoming messages the agent can read
-  // ------------------------------------------------------------------
-  /** Return buffered messages, newest first. Optionally filter by chat. */
-  getMessages(opts) {
-    let msgs = [...this.buffer].reverse();
-    if (opts?.chatId) {
-      const cid = String(opts.chatId);
-      msgs = msgs.filter((m) => String(m.chatId) === cid);
-    }
-    const limit = opts?.limit ?? 20;
-    return msgs.slice(0, limit);
+  schedulePoll() {
+    if (!this.pollActive) return;
+    if (this.lock && !this.lock.held) return;
+    const delay = this._conflictStreak >= _Poller.CONFLICT_BACKOFF_AFTER ? _Poller.CONFLICT_POLL_MS : this.pollIntervalMs;
+    this.pollTimer = setTimeout(() => {
+      void this.poll().finally(() => this.schedulePoll());
+    }, delay);
   }
-  /** Drop messages older than or equal to the given message ID from the buffer (optionally scoped to a specific chat). */
-  acknowledge(lastMessageId, chatId) {
-    const before = this.buffer.length;
-    const cid = chatId !== void 0 && chatId !== null && String(chatId).trim() !== "" ? String(chatId).trim() : void 0;
-    const remaining = [];
-    for (const buffered of this.buffer) {
-      if (cid !== void 0) {
-        if (String(buffered.chatId) === cid && buffered.messageId <= lastMessageId) {
+  async poll() {
+    try {
+      const updates = await this.api().getUpdates({ offset: this.offset, timeoutSeconds: 10, deadlineMs: 15e3, signal: this.controller.signal });
+      this._conflictStreak = 0;
+      for (const upd of updates) {
+        if (upd.update_id < this.offset) continue;
+        if (upd.callback_query) {
+          this.onCallbackQuery(upd.callback_query);
+          this.offset = upd.update_id + 1;
           continue;
         }
-      } else if (buffered.messageId <= lastMessageId) {
-        continue;
+        const raw = upd.message ?? upd.edited_message;
+        if (!raw?.text) {
+          this.offset = upd.update_id + 1;
+          continue;
+        }
+        try {
+          this.onMessageUpdate(raw);
+          this.offset = upd.update_id + 1;
+        } catch (err) {
+          this.log.debug(`Telegram processMessage failed: ${err instanceof Error ? err.message : String(err)}`);
+          break;
+        }
+      }
+      if (this.offsetStore && updates.length > 0) void this.saveOffset();
+    } catch (err) {
+      if (err instanceof TelegramNetworkError && err.aborted) return;
+      if (err instanceof TelegramBotApiError && err.errorCode === 409) {
+        this._conflictStreak++;
+        if (this._conflictStreak === _Poller.CONFLICT_BACKOFF_AFTER) this.log.warn(this.lock ? "Telegram: another consumer outside this machine is polling this bot token (HTTP 409) \u2014 backing off to 60s polls. Check other machines/bots using this token, or a registered webhook (deleteWebhook)." : "Telegram: another instance is polling this bot token (HTTP 409) \u2014 backing off to 60s polls until it stops.");
+        this.log.debug(`Telegram getUpdates failed: ${err.description}`);
+        return;
+      }
+      this.log.debug(`Telegram poll error: ${err.message}`);
+    }
+  }
+  async loadOffset() {
+    if (!this.offsetStore) return;
+    try {
+      const saved = this.offsetStore.read();
+      if (saved !== null) {
+        this.offset = saved;
+        this.log.debug(`Telegram polling offset restored: ${this.offset}`);
       }
-      remaining.push(buffered);
+    } catch {
     }
-    this.buffer.length = 0;
-    this.buffer.push(...remaining);
-    return before - this.buffer.length;
   }
-  get bufferCount() {
-    return this.buffer.length;
+  async saveOffset() {
+    if (!this.offsetStore) return;
+    try {
+      this.offsetStore.write(this.offset);
+    } catch (err) {
+      this.log.debug(`Failed to persist Telegram offset: ${err}`);
+    }
+  }
+};
+
+// src/outbox.ts
+var TelegramOutbox = class {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
   }
-  // ------------------------------------------------------------------
-  // Outgoing — send a message
-  // ------------------------------------------------------------------
   async sendMessage(chatId, text, signal) {
-    this.log.debug(`Sending Telegram message to ${chatId} (${text.length} chars)`);
+    this.deps.log.debug(`Sending Telegram message to ${chatId} (${text.length} chars)`);
     let lastErr;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
         const timeout = AbortSignal.timeout(1e4);
-        const result = await this.api.sendMessage(chatId, text, {
+        const result = await this.deps.api().sendMessage(chatId, text, {
           signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-          parseMode: this.getParseMode?.()
+          parseMode: this.deps.getParseMode?.()
         });
         return { ok: true, result };
       } catch (err) {
@@ -453,12 +636,12 @@ var TelegramBot = class _TelegramBot {
         const decision = classifyRetry(err, attempt);
         if (!decision.retry) {
           if (attempt > 1)
-            this.log.debug(
+            this.deps.log.debug(
               `Telegram sendMessage terminal error on attempt ${attempt}, not retrying`
             );
           break;
         }
-        this.log.debug(
+        this.deps.log.debug(
           `Telegram sendMessage attempt ${attempt} failed, retrying in ${decision.delayMs}ms...`
         );
         await abortableSleep(decision.delayMs, signal);
@@ -466,13 +649,10 @@ var TelegramBot = class _TelegramBot {
     }
     throw lastErr;
   }
-  // ------------------------------------------------------------------
-  // Outgoing — send a message with an inline keyboard
-  // ------------------------------------------------------------------
   /**
    * Send a message that has up to one row of inline buttons (Telegram's
    * `inline_keyboard`). Used by `telegram_approve` to present a
-   * yes/no prompt. The keyboard payload is opaque to the bot — callers
+   * yes/no prompt. The keyboard payload is opaque to the outbox — callers
    * pass already-encoded `callback_data` strings (≤ 64 bytes each).
    */
   async sendMessageWithKeyboard(chatId, text, buttons, signal) {
@@ -480,9 +660,9 @@ var TelegramBot = class _TelegramBot {
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
         const timeout = AbortSignal.timeout(1e4);
-        const result = await this.api.sendMessageWithKeyboard(chatId, text, buttons, {
+        const result = await this.deps.api().sendMessageWithKeyboard(chatId, text, buttons, {
           signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-          parseMode: this.getParseMode?.()
+          parseMode: this.deps.getParseMode?.()
         });
         return { ok: true, result };
       } catch (err) {
@@ -490,7 +670,7 @@ var TelegramBot = class _TelegramBot {
         const decision = classifyRetry(err, attempt);
         if (!decision.retry) {
           if (attempt > 1)
-            this.log.debug(
+            this.deps.log.debug(
               `Telegram sendMessageWithKeyboard terminal error on attempt ${attempt}, not retrying`
             );
           break;
@@ -500,9 +680,6 @@ var TelegramBot = class _TelegramBot {
     }
     throw lastErr;
   }
-  // ------------------------------------------------------------------
-  // Health
-  // ------------------------------------------------------------------
   async health(signal) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), 5e3);
@@ -510,7 +687,7 @@ var TelegramBot = class _TelegramBot {
       const timeout = AbortSignal.timeout(5e3);
       const deadline = AbortSignal.any([ctrl.signal, timeout]);
       const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
-      const user = await this.api.getMe({ signal: combined });
+      const user = await this.deps.api().getMe({ signal: combined });
       return { ok: true, username: user.username };
     } catch (err) {
       if (err instanceof TelegramBotApiError) return { ok: false, error: err.description };
@@ -520,318 +697,146 @@ var TelegramBot = class _TelegramBot {
       clearTimeout(timer);
     }
   }
-  // ------------------------------------------------------------------
-  // Polling
-  // ------------------------------------------------------------------
-  schedulePoll() {
-    if (!this.pollActive) return;
-    if (this.lock && !this.lock.held) return;
-    const delay = this.conflictStreak >= _TelegramBot.CONFLICT_BACKOFF_AFTER ? _TelegramBot.CONFLICT_POLL_MS : this.pollIntervalMs;
-    this.pollTimer = setTimeout(() => {
-      void this.poll().finally(() => this.schedulePoll());
-    }, delay);
-  }
-  async poll() {
-    try {
-      const updates = await this.api.getUpdates({
-        offset: this.offset,
-        timeoutSeconds: 10,
-        deadlineMs: 15e3,
-        signal: this.controller.signal
-      });
-      this.conflictStreak = 0;
-      for (const upd of updates) {
-        if (upd.update_id < this.offset) continue;
-        this.offset = upd.update_id + 1;
-        if (upd.callback_query) {
-          void this.dispatchCallback(upd.callback_query).catch(
-            (err) => this.log.debug(
-              `Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`
-            )
-          );
-          continue;
-        }
-        const raw = upd.message ?? upd.edited_message;
-        if (!raw?.text) continue;
-        this.processMessage({ ...raw, text: raw.text });
-      }
-      if (this.offsetStore && updates.length > 0) void this.saveOffset();
-    } catch (err) {
-      if (err instanceof TelegramNetworkError && err.aborted) return;
-      if (err instanceof TelegramBotApiError && err.errorCode === 409) {
-        this.conflictStreak++;
-        if (this.conflictStreak === _TelegramBot.CONFLICT_BACKOFF_AFTER) {
-          this.log.warn(
-            this.lock ? "Telegram: another consumer outside this machine is polling this bot token (HTTP 409) \u2014 backing off to 60s polls. Check other machines/bots using this token, or a registered webhook (deleteWebhook)." : "Telegram: another instance is polling this bot token (HTTP 409) \u2014 backing off to 60s polls until it stops."
-          );
-        }
-        this.log.debug(`Telegram getUpdates failed: ${err.description}`);
-        return;
-      }
-      this.log.debug(`Telegram poll error: ${err.message}`);
-    }
-  }
-  /**
-   * Apply the inbound identity policy to every update type. A non-empty set is
-   * a mandatory constraint: missing identity fails closed instead of bypassing
-   * the allowlist. An empty set leaves that identity dimension unrestricted.
-   */
-  inboundDenialReason(userId, chatId) {
-    if (this.allowedChats.size > 0 && (chatId === void 0 || !this.allowedChats.has(chatId))) {
-      return "chat";
-    }
-    if (this.allowedUsers.size > 0 && (userId === void 0 || !this.allowedUsers.has(userId))) {
-      return "user";
-    }
-    return void 0;
-  }
-  processMessage(msg) {
-    const chatId = String(msg.chat.id);
-    const userId = msg.from ? String(msg.from.id) : void 0;
-    const denialReason = this.inboundDenialReason(userId, chatId);
-    if (denialReason === "user") {
-      this.log.debug(`Ignoring message from user ${userId ?? "unknown"} (not in allowedUsers)`);
-      void this.sendMessage(chatId, "\u26D4 You are not authorized to interact with this bot.").catch(
-        (err) => this.log.debug(
-          `Failed to send denial notice: ${err instanceof Error ? err.message : String(err)}`
-        )
-      );
-      return;
-    }
-    if (denialReason === "chat") {
-      this.log.debug(`Ignoring message from chat ${chatId} (not in allowedChats)`);
-      return;
-    }
-    const incoming = {
-      messageId: msg.message_id,
-      chatId: msg.chat.id,
-      chatType: msg.chat.type,
-      userId: msg.from?.id,
-      userName: msg.from?.username ?? msg.from?.first_name,
-      text: msg.text,
-      timestamp: msg.date * 1e3
-    };
-    this.buffer.push(incoming);
-    while (this.buffer.length > this.bufferMax) this.buffer.shift();
-    this.onMessage(incoming);
-  }
-  /**
-   * Resolve a pending approval request exactly once and record its terminal
-   * state before removing it from the live registry.
-   */
-  settleApproval(requestId, state, result) {
-    const request = this.callbackWaiters.get(requestId);
-    if (request?.state !== "pending") return false;
-    request.state = state;
-    clearTimeout(request.timer);
-    if (request.signal && request.abortHandler) {
-      request.signal.removeEventListener("abort", request.abortHandler);
-    }
-    const leftoverCallbacks = request.pendingCallbacks.splice(0);
-    for (const cq of leftoverCallbacks) {
-      const notice = state === "expired" ? "Approval request expired" : state === "cancelled" ? "Approval request cancelled" : "Approval request settled";
-      void this.answerCallback(cq.id, notice, true);
-    }
-    this.callbackWaiters.delete(requestId);
-    request.resolve(result);
-    return true;
-  }
-  async dispatchCallback(cq) {
-    const key = cq.data ?? "";
-    const action = /^approve:([^:]+):(yes|no)$/.exec(key);
-    const requestId = action?.[1];
-    const request = requestId ? this.callbackWaiters.get(requestId) : void 0;
-    const userId = cq.from?.id !== void 0 ? String(cq.from.id) : void 0;
-    const chatId = cq.message?.chat.id !== void 0 ? String(cq.message.chat.id) : void 0;
-    const denialReason = this.inboundDenialReason(userId, chatId);
-    if (denialReason) {
-      const identity = denialReason === "user" ? userId ?? "unknown" : chatId ?? "unknown";
-      this.log.warn(
-        `Ignoring callback_query from non-allowlisted ${denialReason} ${identity} (data="${key}") \u2014 possible hijack attempt.`
-      );
-      await this.answerCallback(cq.id, "\u26D4 Not authorized", true);
-      return;
-    }
-    if (!request || !requestId || !action) {
-      await this.answerCallback(cq.id, "Approval request unavailable", true);
-      this.log.debug(`Unmatched callback_query data="${key}" (no pending approval request)`);
-      return;
-    }
-    if (Date.now() >= request.expiresAt) {
-      await this.answerCallback(cq.id, "Approval request expired", true);
-      this.settleApproval(requestId, "expired", { approved: false, fromUser: "timeout" });
-      return;
-    }
-    if (request.promptMessageId === void 0) {
-      request.pendingCallbacks.push(cq);
-      return;
-    }
-    const messageId = cq.message?.message_id;
-    const chatType = cq.message?.chat.type;
-    const wrongIdentity = userId === void 0 || chatId !== request.expectedChatId || !request.expectedUserIds.has(userId) || messageId !== request.promptMessageId || chatType !== "private" && !request.allowGroup;
-    if (wrongIdentity) {
-      this.log.warn(
-        `Ignoring callback_query that does not match approval request ${request.requestId} in session ${request.sessionId}.`
-      );
-      await this.answerCallback(cq.id, "\u26D4 Not authorized for this approval", true);
-      return;
-    }
-    const approved = action[2] === "yes";
-    const fromUser = cq.from?.username ?? cq.from?.first_name ?? `user:${userId}`;
-    const resolved = this.settleApproval(requestId, "resolved", {
-      approved,
-      fromUser,
-      fromUserId: cq.from?.id
-    });
-    await this.answerCallback(
-      cq.id,
-      resolved ? approved ? "Approved \u2713" : "Denied \u2717" : "Approval request unavailable",
-      !resolved
-    );
-  }
-  /**
-   * POST /answerCallbackQuery for a callback. Best-effort: failures are
-   * logged at debug and swallowed — the caller's resolve() must not depend
-   * on the ack reaching Telegram (the user may get a "loading" spinner if
-   * it fails, but the agent's approval flow continues normally).
-   */
-  async answerCallback(callbackQueryId, text, showAlert) {
-    try {
-      await this.api.answerCallbackQuery(callbackQueryId, text, showAlert, {
-        signal: AbortSignal.timeout(5e3)
-      });
-    } catch (err) {
-      this.log.debug(`answerCallbackQuery failed: ${err.message}`);
-    }
-  }
-  /**
-   * Register one approval request before its prompt is sent. The returned
-   * promise owns the request's only timer and resolves on one terminal event.
-   */
-  awaitApproval(input) {
-    if (input.expectedUserIds.length === 0) {
-      throw new Error("Telegram approval requires at least one expected user ID.");
-    }
-    if (this.callbackWaiters.has(input.requestId)) {
-      throw new Error(`Telegram approval request ${input.requestId} is already pending.`);
-    }
-    return new Promise((resolve) => {
-      const delayMs = Math.max(0, input.expiresAt - Date.now());
-      const timer = setTimeout(() => {
-        this.settleApproval(input.requestId, "expired", {
-          approved: false,
-          fromUser: "timeout"
-        });
-      }, delayMs);
-      const request = {
-        requestId: input.requestId,
-        sessionId: input.sessionId,
-        expectedChatId: String(input.expectedChatId),
-        expectedUserIds: new Set(input.expectedUserIds.map(String)),
-        allowGroup: input.allowGroup,
-        pendingCallbacks: [],
-        expiresAt: input.expiresAt,
-        state: "pending",
-        resolve,
-        timer,
-        signal: input.signal
-      };
-      if (input.signal) {
-        request.abortHandler = () => {
-          this.settleApproval(input.requestId, "cancelled", {
-            approved: false,
-            fromUser: "aborted"
-          });
-        };
-      }
-      this.callbackWaiters.set(input.requestId, request);
-      if (input.signal?.aborted) {
-        request.abortHandler?.();
-      } else if (input.signal && request.abortHandler) {
-        input.signal.addEventListener("abort", request.abortHandler, { once: true });
-      }
-    });
-  }
-  /**
-   * Attach the Bot API response's prompt message ID to an existing request.
-   * Any callback that arrived during the send is replayed against the fully
-   * bound identity without allocating a second waiter or timer.
-   */
-  bindApprovalPrompt(requestId, promptMessageId) {
-    const request = this.callbackWaiters.get(requestId);
-    if (request?.state !== "pending" || request.promptMessageId !== void 0) return false;
-    request.promptMessageId = promptMessageId;
-    const pending = request.pendingCallbacks.splice(0);
-    for (const callback of pending) {
-      void this.dispatchCallback(callback).catch(
-        (err) => this.log.debug(
-          `Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`
-        )
-      );
-    }
-    return true;
-  }
-  /** Cancel a request that cannot reach a valid terminal callback. */
-  cancelApproval(requestId, fromUser = "cancelled") {
-    return this.settleApproval(requestId, "cancelled", { approved: false, fromUser });
-  }
-  async loadOffset() {
-    if (!this.offsetStore) return;
-    try {
-      const saved = this.offsetStore.read();
-      if (saved !== null) {
-        this.offset = saved;
-        this.log.debug(`Telegram polling offset restored: ${this.offset}`);
-      }
-    } catch {
-    }
-  }
-  async saveOffset() {
-    if (!this.offsetStore) return;
-    try {
-      this.offsetStore.write(this.offset);
-    } catch (err) {
-      this.log.debug(`Failed to persist Telegram offset: ${err}`);
-    }
-  }
 };
+
+// src/text-format.ts
 var MAX_TELEGRAM_MESSAGE_LENGTH = 4096;
 function truncateForTelegram(text, maxLen = 4e3) {
   const effectiveMaxLen = Math.min(maxLen, MAX_TELEGRAM_MESSAGE_LENGTH);
   if (text.length <= effectiveMaxLen) return text;
   const cutoff = effectiveMaxLen - 30;
   if (cutoff <= 0) return `${text.slice(0, effectiveMaxLen - 1)}\u2026`;
-  const searchEnd = Math.min(text.length, effectiveMaxLen);
-  const paraIdx = text.lastIndexOf("\n\n", searchEnd);
+  const paraSearchEnd = effectiveMaxLen - 3;
+  const paraIdx = text.lastIndexOf("\n\n", paraSearchEnd);
   if (paraIdx > cutoff) {
     return `${text.slice(0, paraIdx)}
 
 \u2026`;
   }
-  const nlIdx = text.lastIndexOf("\n", searchEnd);
+  const nlSearchEnd = effectiveMaxLen - 2;
+  const nlIdx = text.lastIndexOf("\n", nlSearchEnd);
   if (nlIdx > cutoff) {
     return `${text.slice(0, nlIdx)}
 \u2026`;
   }
+  const sentenceSearchEnd = effectiveMaxLen - 1;
   const sentenceRe = /[.!?](?=\s)/g;
   let match;
   let sentenceIdx = -1;
   match = sentenceRe.exec(text);
   while (match !== null) {
-    if (match.index >= searchEnd) break;
-    if (match.index > cutoff) sentenceIdx = match.index + 1;
+    if (match.index + 1 > sentenceSearchEnd) break;
+    if (match.index + 1 > cutoff) sentenceIdx = match.index + 1;
     match = sentenceRe.exec(text);
   }
   if (sentenceIdx > cutoff) {
     return `${text.slice(0, sentenceIdx)}\u2026`;
   }
-  const spaceIdx = text.lastIndexOf(" ", searchEnd);
+  const spaceSearchEnd = effectiveMaxLen - 2;
+  const spaceIdx = text.lastIndexOf(" ", spaceSearchEnd);
   if (spaceIdx > cutoff) {
     return `${text.slice(0, spaceIdx)} \u2026`;
   }
-  return `${text.slice(0, effectiveMaxLen - 20)}\u2026[+${text.length - effectiveMaxLen + 20} chars]`;
+  const hardSlice = text.slice(0, effectiveMaxLen - 20);
+  const hardResult = `${hardSlice}\u2026[+${text.length - hardSlice.length} chars]`;
+  if (hardResult.length <= effectiveMaxLen) return hardResult;
+  return `${text.slice(0, effectiveMaxLen - 1)}\u2026`;
 }
 
+// src/bot.ts
+var TelegramBot = class {
+  api;
+  log;
+  lock;
+  approvals;
+  poller;
+  inbox;
+  outbox;
+  constructor(opts) {
+    this.api = new TelegramApiClient({ token: opts.token });
+    this.log = opts.log;
+    this.lock = opts.lock;
+    this.inbox = new TelegramInbox({
+      log: this.log,
+      allowedUsers: opts.allowedUsers,
+      allowedChats: opts.allowedChats,
+      bufferMax: opts.bufferSize,
+      onMessage: opts.onMessage,
+      sendNotice: (chatId, text) => this.sendMessage(chatId, text)
+    });
+    this.outbox = new TelegramOutbox({ log: this.log, api: () => this.api, getParseMode: opts.getParseMode });
+    this.approvals = new ApprovalFlow({
+      log: this.log,
+      api: () => this.api,
+      inboundDenialReason: (userId, chatId) => this.inbox.denialReason(userId, chatId)
+    });
+    this.poller = new Poller({
+      api: () => this.api,
+      pollIntervalMs: opts.pollIntervalSec * 1e3,
+      log: this.log,
+      controller: new AbortController(),
+      offsetStore: opts.offsetStore,
+      lock: opts.lock,
+      standbyRetryMs: opts.standbyRetryMs ?? 15e3,
+      onCallbackQuery: (cq) => {
+        void this.approvals.dispatchCallback(cq).catch((err) => this.log.debug(`Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`));
+      },
+      onMessageUpdate: (msg) => this.processMessage({ ...msg, text: msg.text })
+    });
+  }
+  start() {
+    this.poller.start();
+  }
+  stop() {
+    this.poller.stop();
+    this.approvals.cancelAll("shutdown");
+    this.lock?.release();
+    this.log.info("Telegram bot stopped");
+  }
+  get standby() {
+    return this.poller.standby;
+  }
+  get startedAt() {
+    return this.poller.startedAt;
+  }
+  get running() {
+    return this.poller.active;
+  }
+  getMessages(opts) {
+    return this.inbox.getMessages(opts);
+  }
+  acknowledge(lastMessageId, chatId) {
+    return this.inbox.acknowledge(lastMessageId, chatId);
+  }
+  get bufferCount() {
+    return this.inbox.bufferCount;
+  }
+  processMessage(msg) {
+    this.inbox.processMessage(msg);
+  }
+  sendMessage(chatId, text, signal) {
+    return this.outbox.sendMessage(chatId, text, signal);
+  }
+  sendMessageWithKeyboard(chatId, text, buttons, signal) {
+    return this.outbox.sendMessageWithKeyboard(chatId, text, buttons, signal);
+  }
+  async health(signal) {
+    return this.outbox.health(signal);
+  }
+  get callbackWaiters() {
+    return this.approvals.callbackWaiters;
+  }
+  awaitApproval(input) {
+    return this.approvals.awaitApproval(input);
+  }
+  bindApprovalPrompt(requestId, promptMessageId) {
+    return this.approvals.bindApprovalPrompt(requestId, promptMessageId);
+  }
+  cancelApproval(requestId, fromUser = "cancelled") {
+    return this.approvals.cancelApproval(requestId, fromUser);
+  }
+};
+
 // src/config.ts
 import { resolvePluginConfig } from "@wrongstack/core/plugin";
 var PLUGIN_NAME = "telegram";
@@ -1157,7 +1162,8 @@ var PollLock = class {
       this.startHeartbeat();
       return true;
     } catch (err) {
-      if (err.code !== "EEXIST") {
+      const code = err.code;
+      if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES" && code !== "EBUSY") {
         return false;
       }
     }
@@ -1214,7 +1220,7 @@ var PollLock = class {
       this.onLost?.();
       return;
     }
-    const tmp = `${this.lockPath}.${process.pid}.tmp`;
+    const tmp = `${this.lockPath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
     try {
       const payload = { ...current, heartbeatAt: Date.now() };
       writeFileSync(tmp, JSON.stringify(payload));
@@ -1245,7 +1251,7 @@ var PollLock = class {
 };
 
 // src/offset-store.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import {
   closeSync,
   fsyncSync,
@@ -1307,7 +1313,7 @@ var OffsetStore = class {
   write(offset) {
     if (!this.path || offset < 0) return;
     mkdirSync2(dirname2(this.path), { recursive: true });
-    const tmp = `${this.path}.${process.pid}.tmp`;
+    const tmp = `${this.path}.${process.pid}.${randomUUID2().slice(0, 8)}.tmp`;
     const fd = openSync(tmp, "w");
     try {
       writeSync(fd, JSON.stringify(offset));
@@ -1482,7 +1488,7 @@ and the \`telegram_send\` tool when no chat_id is specified.`,
 }
 
 // src/tools/telegram-approve.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 function makeTelegramApproveTool(opts) {
   return {
     name: "telegram_approve",
@@ -1529,7 +1535,7 @@ function makeTelegramApproveTool(opts) {
         throw new Error("Telegram group approvals require explicit per-user configuration.");
       }
       const expectedUserIds = configuredUserIds.length > 0 ? configuredUserIds : [String(chatId)];
-      const requestId = randomUUID2().slice(0, 16);
+      const requestId = randomUUID3().slice(0, 16);
       const yesKey = `approve:${requestId}:yes`;
       const noKey = `approve:${requestId}:no`;
       const prompt = scrubTelegramOutboundText(input.prompt);