@wrongstack/telegram 0.284.0 → 0.285.0

package/dist/bot.d.ts

@@ -0,0 +1,192 @@
+import type { Logger } from '@wrongstack/core';
+import type { PollLock } from './poll-lock.js';
+interface TgUser {
+    id: number;
+    is_bot: boolean;
+    first_name: string;
+    username?: string | undefined;
+}
+interface TgChat {
+    id: number;
+    type: 'private' | 'group' | 'supergroup' | 'channel';
+    title?: string | undefined;
+    username?: string | undefined;
+}
+interface TgMessage {
+    message_id: number;
+    from?: TgUser | undefined;
+    chat: TgChat;
+    date: number;
+    text?: string | undefined;
+}
+interface TgResponse<T> {
+    ok: boolean;
+    result?: T | undefined;
+    description?: string | undefined;
+    error_code?: number | undefined;
+}
+export interface TelegramIncomingMessage {
+    messageId: number;
+    chatId: number;
+    chatType: string;
+    userId?: number | undefined;
+    userName?: string | undefined;
+    text: string;
+    timestamp: number;
+}
+export interface TelegramBotOptions {
+    token: string;
+    pollIntervalSec: number;
+    allowedUsers: Set<string>;
+    allowedChats: Set<string>;
+    /** Max messages to buffer for the agent to read. Default: 50. */
+    bufferSize: number;
+    log: Logger;
+    /** Called for each incoming message that passes allowlist checks. */
+    onMessage(msg: TelegramIncomingMessage): void;
+    /**
+     * Optional path to a file that stores the polling offset. When provided,
+     * the offset is persisted on every successful poll and restored on startup,
+     * preventing message replay after crashes or restarts.
+     */
+    offsetStoragePath?: string | undefined;
+    /**
+     * Optional cross-process single-poller lock. Telegram allows one
+     * `getUpdates` consumer per token; when another wstack instance holds the
+     * lock, this bot stands by (no polling) and takes over once the holder
+     * stops or its heartbeat goes stale.
+     */
+    lock?: PollLock | undefined;
+    /** How often a standby instance retries acquiring the lock. Default: 15s. */
+    standbyRetryMs?: number | undefined;
+}
+export declare class TelegramBot {
+    private readonly baseUrl;
+    /** Base URL with token redacted, safe to use in log calls. */
+    private readonly safeBaseUrl;
+    private readonly pollIntervalMs;
+    private readonly allowedUsers;
+    private readonly allowedChats;
+    private readonly log;
+    private readonly onMessage;
+    private readonly controller;
+    private pollTimer;
+    private pollActive;
+    private offset;
+    /**
+     * 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.
+     */
+    private conflictStreak;
+    private static readonly CONFLICT_BACKOFF_AFTER;
+    private static readonly CONFLICT_POLL_MS;
+    private _startedAt;
+    /** If set, the offset is persisted here after each successful poll. */
+    private readonly offsetStoragePath?;
+    /** Single-poller election across wstack instances sharing this token. */
+    private readonly lock?;
+    private readonly standbyRetryMs;
+    private standbyTimer;
+    private standbyAnnounced;
+    private readonly bufferMax;
+    private readonly buffer;
+    private readonly callbackWaiters;
+    constructor(opts: TelegramBotOptions);
+    /** Start polling for updates. Idempotent. */
+    start(): void;
+    /** Stop polling and cancel all in-flight requests. */
+    stop(): void;
+    /** True when the bot is started but waiting for the poll lock. */
+    get standby(): boolean;
+    /**
+     * Acquire the poll lock (when configured) and start the poll loop, or
+     * stand by and retry until the current holder releases it.
+     */
+    private acquireAndPoll;
+    /** The lock was stolen while we held it — pause polling and stand by. */
+    private handleLockLost;
+    get startedAt(): number | null;
+    get running(): boolean;
+    /** Return buffered messages, newest first. Optionally filter by chat. */
+    getMessages(opts?: {
+        chatId?: string | number | undefined;
+        limit?: number | undefined;
+    }): TelegramIncomingMessage[];
+    /** Drop messages older than the given message ID from the buffer. */
+    acknowledge(lastMessageId: number): number;
+    get bufferCount(): number;
+    sendMessage(chatId: string | number, text: string): Promise<TgResponse<TgMessage>>;
+    /**
+     * 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
+     * pass already-encoded `callback_data` strings (≤ 64 bytes each).
+     */
+    sendMessageWithKeyboard(chatId: string | number, text: string, buttons: Array<{
+        text: string;
+        callback_data: string;
+    }>): Promise<TgResponse<TgMessage>>;
+    health(): Promise<{
+        ok: boolean;
+        username?: string | undefined;
+        error?: string | undefined;
+    }>;
+    private schedulePoll;
+    private poll;
+    private processMessage;
+    /**
+     * Handle an inbound `callback_query` update: route it to a registered
+     * waiter (if any), and acknowledge it via `answerCallbackQuery` so the
+     * client stops spinning. Telegram requires the answer within 10 s.
+     */
+    /**
+     * Resolve any pending waiter for `key` with a `{ approved: false, fromUser }`
+     * value, regardless of why the callback was rejected (allowlist, shutdown,
+     * etc.). Returns true if a waiter was found and resolved, false otherwise.
+     * This helper centralizes the race-safe `delete → resolve` pattern in one
+     * place so the deny and shutdown paths don't drift out of sync.
+     */
+    private rejectWaiter;
+    private dispatchCallback;
+    /**
+     * 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).
+     */
+    private answerCallback;
+    /**
+     * Register a waiter for a callback_query whose `data` field equals `key`.
+     * Resolves with `{ approved, fromUser }` when a matching press arrives, or
+     * with `{ approved: false, fromUser: 'timeout' }` after `timeoutMs`.
+     *
+     * Callers are responsible for not registering the same key twice — a
+     * second `awaitCallback` for an in-flight key is undefined.
+     */
+    awaitCallback(key: string, timeoutMs: number): Promise<{
+        approved: boolean;
+        fromUser: string;
+    }>;
+    private loadOffset;
+    private saveOffset;
+}
+/**
+ * Truncate text to fit Telegram's 4096-char message limit.
+ * Preserves semantic boundaries in this priority order:
+ *   1. Paragraph break (double newline)
+ *   2. Sentence break (. ! ? followed by space/newline)
+ *   3. Word break (space)
+ *   4. Hard cut with ellipsis
+ *
+ * When a clean boundary is found, appends "…" to signal intentional truncation.
+ */
+export declare function truncateForTelegram(text: string, maxLen?: number): string;
+/**
+ * Escape HTML special chars for Telegram's HTML parse mode.
+ */
+export declare function escapeHtml(text: string): string;
+export {};
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,108 @@
+import type { PluginAPI } from '@wrongstack/core';
+export declare const PLUGIN_NAME = "telegram";
+export interface TelegramPluginConfig {
+    /** Telegram Bot API token (from @BotFather). */
+    botToken: string;
+    /**
+     * Default chat ID for outgoing notifications.
+     * The agent's `telegram_send` tool can override per-call.
+     */
+    notifyChatId?: string | number | undefined;
+    /**
+     * List of user/chat IDs allowed to interact with the bot.
+     * Empty = allow all. Recommended to set in production.
+     */
+    allowedUsers?: Array<string | number> | undefined;
+    /**
+     * List of group/chat IDs the bot is allowed to read from.
+     * Empty = allow all. Narrow this to prevent noise.
+     */
+    allowedChats?: Array<string | number> | undefined;
+    /** Polling interval in seconds (default: 2). */
+    pollIntervalSec?: number | undefined;
+    /** Notify on Telegram when a session ends. */
+    notifyOnSessionEnd?: boolean | undefined;
+    /** Notify when a tool runs longer than this threshold (ms). Set 0 to disable. */
+    longToolThresholdMs?: number | undefined;
+    /** Notify (humanized) when a `delegate` subagent finishes. Default: true. */
+    notifyOnDelegate?: boolean | undefined;
+    /** Maximum message length for Telegram (Telegram caps at 4096). */
+    maxMessageLength?: number | undefined;
+    /**
+     * Path to a file that stores the Telegram polling offset. When set,
+     * the offset is persisted on every successful poll and restored on startup,
+     * preventing message replay after crashes or restarts.
+     * The directory must already exist and be writable.
+     */
+    offsetStoragePath?: string | undefined;
+    /**
+     * Elect a single poller per bot token across wstack instances (default:
+     * true). Telegram allows one `getUpdates` consumer per token; without this,
+     * two instances sharing a token fight and get HTTP 409 on every poll.
+     * Extra instances stand by and take over when the active poller stops.
+     * Set false only if this is guaranteed to be the sole consumer.
+     */
+    singleInstanceLock?: boolean | undefined;
+}
+export declare const DEFAULT_CONFIG: Required<Omit<TelegramPluginConfig, 'botToken' | 'notifyChatId' | 'offsetStoragePath'>>;
+export declare const telegramConfigSchema: {
+    type: string;
+    properties: {
+        botToken: {
+            type: string;
+            description: string;
+        };
+        notifyChatId: {
+            oneOf: {
+                type: string;
+            }[];
+            description: string;
+        };
+        allowedUsers: {
+            type: string;
+            items: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            description: string;
+        };
+        allowedChats: {
+            type: string;
+            items: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            description: string;
+        };
+        pollIntervalSec: {
+            type: string;
+            minimum: number;
+            maximum: number;
+            description: string;
+        };
+        notifyOnSessionEnd: {
+            type: string;
+        };
+        longToolThresholdMs: {
+            type: string;
+            minimum: number;
+        };
+        notifyOnDelegate: {
+            type: string;
+        };
+        maxMessageLength: {
+            type: string;
+            minimum: number;
+            maximum: number;
+        };
+        singleInstanceLock: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare function readTelegramConfig(api: Pick<PluginAPI, 'config'>): Required<Omit<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>> & Pick<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,cAAc,GAAG,mBAAmB,CAAC,CASlH,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAGjB,IAAI;YAAY,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;YAgBrC,IAAI;YACJ,OAAO;YACP,OAAO;YACP,WAAW;;;YAES,IAAI;;;YACH,IAAI;YAAa,OAAO;;;YAC3B,IAAI;;;YACJ,IAAI;YAAa,OAAO;YAAO,OAAO;;;YAExD,IAAI;YACJ,WAAW;;;;CAIhB,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,GAC7B,QAAQ,CAAC,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAAC,GAC3E,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAgBjE"}

package/dist/format.d.ts

@@ -0,0 +1,70 @@
+/** Subset of the core `delegate.completed` event payload we render. */
+export interface DelegateCompletedLike {
+    target: string;
+    task: string;
+    ok: boolean;
+    status?: string | undefined;
+    summary: string;
+    durationMs: number;
+    iterations: number;
+    toolCalls: number;
+    costUsd?: number | undefined;
+    subagentId?: string | undefined;
+}
+/** Subset of core `tool.executed` event payload. */
+export interface ToolExecutedLike {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+    /** Raw tool output — only the first 300 chars are rendered. */
+    output?: string | undefined;
+}
+/** Subset of core `session.ended` event payload (from Usage). */
+export interface SessionEndedLike {
+    id: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead?: number | undefined;
+    cacheWrite?: number | undefined;
+}
+/** Compact human duration: `42s`, `3m`, `1.5h`. */
+export declare function fmtDuration(ms: number): string;
+/**
+ * Format a numeric count of tokens for human readability.
+ * Uses comma-separated thousands: 1,234, 56,789.
+ */
+export declare function fmtTokens(n: number): string;
+/**
+ * Try to render a tool's output as a short human-readable snippet.
+ * Strips JSON braces/quoting, redacts secrets, limits to ~300 chars,
+ * preserves first/last lines.
+ */
+export declare function fmtToolOutput(raw: string | undefined): string;
+/**
+ * Render a finished delegation as a readable Telegram message.
+ *
+ * Example:
+ *   ✅ Delegate → bug-hunter · success
+ *   Found 3 null-deref risks in auth.ts and patched the worst one…
+ *   ⏱ 3m · 4 iter · 37 tools · 💲0.0820
+ */
+export declare function formatDelegateCompleted(e: DelegateCompletedLike): string;
+/**
+ * Render a long-running tool execution notification.
+ *
+ * Example:
+ *   ✅ bash completed in 45.2s
+ *   pnpm test — 12 suites, 47 tests passed
+ *   …
+ */
+export declare function formatToolExecuted(e: ToolExecutedLike): string;
+/**
+ * Render a session-end notification.
+ *
+ * Example:
+ *   🏁 Session sess_abcd ended
+ *   ⬇ 8,234 in · ⬆ 3,456 out · 11,690 total
+ *   Cache: 1,200 read · 800 written
+ */
+export declare function formatSessionEnded(e: SessionEndedLike): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAuBA,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAMD,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoB7D;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAqBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAS9D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAkB9D"}

package/dist/index.d.ts

@@ -1,60 +1,6 @@
-import { Plugin } from '@wrongstack/core';
-
-interface TelegramIncomingMessage {
-    messageId: number;
-    chatId: number;
-    chatType: string;
-    userId?: number | undefined;
-    userName?: string | undefined;
-    text: string;
-    timestamp: number;
-}
-
-interface TelegramPluginConfig {
-    /** Telegram Bot API token (from @BotFather). */
-    botToken: string;
-    /**
-     * Default chat ID for outgoing notifications.
-     * The agent's `telegram_send` tool can override per-call.
-     */
-    notifyChatId?: string | number | undefined;
-    /**
-     * List of user/chat IDs allowed to interact with the bot.
-     * Empty = allow all. Recommended to set in production.
-     */
-    allowedUsers?: Array<string | number> | undefined;
-    /**
-     * List of group/chat IDs the bot is allowed to read from.
-     * Empty = allow all. Narrow this to prevent noise.
-     */
-    allowedChats?: Array<string | number> | undefined;
-    /** Polling interval in seconds (default: 2). */
-    pollIntervalSec?: number | undefined;
-    /** Notify on Telegram when a session ends. */
-    notifyOnSessionEnd?: boolean | undefined;
-    /** Notify when a tool runs longer than this threshold (ms). Set 0 to disable. */
-    longToolThresholdMs?: number | undefined;
-    /** Notify (humanized) when a `delegate` subagent finishes. Default: true. */
-    notifyOnDelegate?: boolean | undefined;
-    /** Maximum message length for Telegram (Telegram caps at 4096). */
-    maxMessageLength?: number | undefined;
-    /**
-     * Path to a file that stores the Telegram polling offset. When set,
-     * the offset is persisted on every successful poll and restored on startup,
-     * preventing message replay after crashes or restarts.
-     * The directory must already exist and be writable.
-     */
-    offsetStoragePath?: string | undefined;
-    /**
-     * Elect a single poller per bot token across wstack instances (default:
-     * true). Telegram allows one `getUpdates` consumer per token; without this,
-     * two instances sharing a token fight and get HTTP 409 on every poll.
-     * Extra instances stand by and take over when the active poller stops.
-     * Set false only if this is guaranteed to be the sole consumer.
-     */
-    singleInstanceLock?: boolean | undefined;
-}
-
+import type { Plugin } from '@wrongstack/core';
 declare const plugin: Plugin;
-
-export { type TelegramIncomingMessage, type TelegramPluginConfig, plugin as default };
+export default plugin;
+export type { TelegramIncomingMessage } from './bot.js';
+export type { TelegramPluginConfig } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAU,MAAM,EAAE,MAAM,kBAAkB,CAAC;AA2DvD,QAAA,MAAM,MAAM,EAAE,MAkPb,CAAC;eAEa,MAAM;AAGrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,10 +1,8 @@
-import { expectDefined } from '@wrongstack/core';
-import { wstackGlobalRoot, sleep } from '@wrongstack/core/utils';
-import { randomUUID, createHash } from 'crypto';
-import { mkdirSync, unlinkSync, writeFileSync, renameSync, readFileSync } from 'fs';
-import { dirname, join } from 'path';
-
 // src/index.ts
+import { expectDefined as expectDefined2 } from "@wrongstack/core";
+
+// src/bot.ts
+import { sleep } from "@wrongstack/core/utils";
 function redactToken(url, token) {
   return url.replace(token, "[REDACTED]");
 }
@@ -436,7 +434,7 @@ var TelegramBot = class _TelegramBot {
   async loadOffset() {
     if (!this.offsetStoragePath) return;
     try {
-      const { readFileSync: readFileSync2 } = await import('fs');
+      const { readFileSync: readFileSync2 } = await import("node:fs");
       const raw = readFileSync2(this.offsetStoragePath, "utf8").trim();
       const n = Number.parseInt(raw, 10);
       if (Number.isFinite(n) && n >= 0) {
@@ -449,7 +447,7 @@ var TelegramBot = class _TelegramBot {
   async saveOffset() {
     if (!this.offsetStoragePath) return;
     try {
-      const { writeFileSync: writeFileSync2 } = await import('fs');
+      const { writeFileSync: writeFileSync2 } = await import("node:fs");
       writeFileSync2(this.offsetStoragePath, String(this.offset), "utf8");
     } catch (err) {
       this.log.debug(`Failed to persist Telegram offset: ${err}`);
@@ -665,6 +663,12 @@ function formatSessionEnded(e) {
   }
   return lines.join("\n");
 }
+
+// src/poll-lock.ts
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { wstackGlobalRoot } from "@wrongstack/core/utils";
 function lockPathForToken(token, globalRoot = wstackGlobalRoot()) {
   const hash = createHash("sha256").update(token).digest("hex").slice(0, 12);
   return join(globalRoot, "telegram", `poll-${hash}.lock`);
@@ -783,6 +787,9 @@ var PollLock = class {
     }
   }
 };
+
+// src/slash-commands/index.ts
+import { expectDefined } from "@wrongstack/core";
 function tgHealthCommand(bot, cfg) {
   return {
     name: "telegram-health",
@@ -980,6 +987,9 @@ function makeTelegramSendTool(opts) {
     }
   };
 }
+
+// src/tools/telegram-approve.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
 function makeTelegramApproveTool(opts) {
   return {
     name: "telegram_approve",
@@ -1023,7 +1033,7 @@ function makeTelegramApproveTool(opts) {
         );
       }
       const timeoutMs = Math.min(Math.max(input.timeout_ms ?? 6e4, 1e3), 6e5);
-      const token = randomUUID().slice(0, 16);
+      const token = randomUUID2().slice(0, 16);
       const yesKey = `approve:${token}:yes`;
       const noKey = `approve:${token}:no`;
       const heading = `\u26A0\uFE0F ${input.prompt}`;
@@ -1170,7 +1180,7 @@ var plugin = {
           formatSessionEnded(payload),
           runtimeCfg.maxMessageLength
         );
-        void bot.sendMessage(expectDefined(runtimeCfg.notifyChatId), msg).catch((err) => {
+        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
           log.debug(`Failed to send session end notification: ${err.message}`);
         });
       })
@@ -1188,7 +1198,7 @@ var plugin = {
           formatToolExecuted(payload),
           runtimeCfg.maxMessageLength
         );
-        void bot.sendMessage(expectDefined(runtimeCfg.notifyChatId), msg).catch((err) => {
+        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
           log.debug(`Failed to send tool notification: ${err.message}`);
         });
       })
@@ -1200,7 +1210,7 @@ var plugin = {
           formatDelegateCompleted(event),
           runtimeCfg.maxMessageLength
         );
-        void bot.sendMessage(expectDefined(runtimeCfg.notifyChatId), msg).catch((err) => {
+        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
           log.debug(`Failed to send delegate notification: ${err.message}`);
         });
       })
@@ -1256,8 +1266,8 @@ var plugin = {
     return h;
   }
 };
-var index_default = plugin;
-
-export { index_default as default };
+var src_default = plugin;
+export {
+  src_default as default
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map