@wrongstack/telegram 0.286.0 → 0.289.0

package/README.md

@@ -7,7 +7,7 @@ Send messages, receive instructions, get notified when long tasks finish.
 
 - **`telegram_read`** — Agent reads incoming Telegram messages (newest first, filtered by chat, with ack support)
 - **`telegram_send`** — Agent sends messages via Telegram (HTML formatting, confirm permission)
-- **System prompt injection** — Unread messages appear in the agent's system prompt so it sees them naturally
+- **Metadata-only inbox notice** — The system prompt reports only an unread count; message content stays behind the explicit `telegram_read` tool boundary
 - **Slash commands** — `/telegram`, `/telegram-health`, `/telegram:send`, `/telegram:chatid` in the TUI
 - **Event notifications** — Session end summaries and long tool completions forwarded to Telegram
 - **Allowlist filtering** — Restrict which users/chats can interact with the bot
@@ -24,16 +24,7 @@ Message [@BotFather](https://t.me/BotFather) on Telegram:
 
 Copy the token (looks like `123456789:ABCdef...`).
 
-### 2. Get your chat ID
-
-Message your new bot, then visit:
-```
-https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
-```
-
-Find your `chat.id` in the response.
-
-### 3. Enable the official plugin
+### 2. Enable the official plugin
 
 ```bash
 wstack plugin install telegram
@@ -51,9 +42,17 @@ CLI package, add it like a normal public package:
 npm install @wrongstack/telegram
 ```
 
-### 4. Configure
+### 3. Pair a private chat securely
+
+Run `/telegram-setup` in WrongStack. Enter the bot token in the masked prompt,
+message the bot once from the private Telegram account you want to pair, then
+explicitly select that discovered identity. WrongStack does not print or ask
+you to open a credential-bearing Bot API URL.
+
+### 4. Configure manually (optional)
 
-In `~/.wrongstack/config.json` or `.wrongstack/config.json`:
+The setup command writes this configuration securely. For custom hosts, the
+equivalent shape in `~/.wrongstack/config.json` or `.wrongstack/config.json` is:
 
 ```jsonc
 {
@@ -65,7 +64,10 @@ In `~/.wrongstack/config.json` or `.wrongstack/config.json`:
     "telegram": {
       "botToken": "123456789:ABCdefGHIjkl...",
       "notifyChatId": "987654321",
+      "inboundMode": "paired",
       "allowedUsers": [987654321],
+      "allowedChats": [987654321],
+      "allowedOutboundChats": [987654321],
       "notifyOnSessionEnd": true,
       "longToolThresholdMs": 30000,
       "pollIntervalSec": 2
@@ -87,9 +89,13 @@ the Telegram options.
 | Field | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `botToken` | `string` | **yes** | — | Bot token from @BotFather |
-| `notifyChatId` | `string \| number` | no | — | Default chat for outgoing messages and notifications |
-| `allowedUsers` | `(string \| number)[]` | no | `[]` | User IDs allowed to interact. Empty = all allowed |
-| `allowedChats` | `(string \| number)[]` | no | `[]` | Chat IDs the bot reads from. Empty = all allowed |
+| `notifyChatId` | `string \| number` | no | — | Default chat for outgoing messages and notifications; it is also the paired chat when `inboundMode` is `paired` |
+| `inboundMode` | `disabled \| paired \| allowlist \| public` | no | `disabled` | Inbound authorization policy. `public` must be selected explicitly. |
+| `allowedUsers` | `(string \| number)[]` | no | `[]` | Immutable user IDs accepted by paired/allowlist authorization and remote approvals |
+| `allowedChats` | `(string \| number)[]` | no | `[]` | Chat IDs accepted when `inboundMode` is `allowlist` |
+| `allowedOutboundChats` | `(string \| number)[]` | no | `[]` | Additional explicitly trusted outbound targets beyond `notifyChatId` |
+| `allowGroupChats` | `boolean` | no | `false` | Let `/telegram-settings chat` select a negative group/channel ID as an outbound-only target |
+| `allowGroupApprovals` | `boolean` | no | `false` | Permit approvals in a group target; still requires explicit `allowedUsers` identity binding |
 | `pollIntervalSec` | `number` | no | `2` | How often to poll Telegram for new messages (1–60) |
 | `notifyOnSessionEnd` | `boolean` | no | `false` | Send token usage summary when a session ends |
 | `longToolThresholdMs` | `number` | no | `30000` | Notify when a tool runs longer than this (ms). `0` = off |
@@ -163,8 +169,8 @@ Message text supports Telegram HTML: `<b>bold</b>`, `<i>italic</i>`, `<code>mono
 
 1. Bot polls Telegram every N seconds via `getUpdates`
 2. Incoming messages go into a circular buffer (50 max)
-3. A system prompt contributor injects unread messages so the agent sees them
-4. Agent reads with `telegram_read`, responds with `telegram_send`
+3. A system prompt contributor exposes only the bounded unread count
+4. Agent explicitly reads content with `telegram_read`, then responds with `telegram_send`
 5. Custom event `telegram:message_received` fires for TUI panels / other plugins
 
 ## Events

package/dist/api-client.d.ts

@@ -0,0 +1,119 @@
+export interface TelegramApiUser {
+    id: number;
+    is_bot: boolean;
+    first_name: string;
+    username?: string | undefined;
+}
+export type TelegramApiChatType = 'private' | 'group' | 'supergroup' | 'channel';
+export interface TelegramApiChat {
+    id: number;
+    type: TelegramApiChatType;
+    title?: string | undefined;
+    username?: string | undefined;
+}
+export interface TelegramApiMessage {
+    message_id: number;
+    from?: TelegramApiUser | undefined;
+    chat: TelegramApiChat;
+    date: number;
+    text?: string | undefined;
+}
+export interface TelegramApiCallbackQuery {
+    id: string;
+    from?: TelegramApiUser | undefined;
+    message?: {
+        message_id: number;
+        chat: TelegramApiChat;
+    } | undefined;
+    data?: string | undefined;
+}
+export interface TelegramApiUpdate {
+    update_id: number;
+    message?: TelegramApiMessage | undefined;
+    edited_message?: TelegramApiMessage | undefined;
+    callback_query?: TelegramApiCallbackQuery | undefined;
+}
+export interface TelegramInlineKeyboardButton {
+    text: string;
+    callback_data: string;
+}
+export type TelegramApiClientErrorKind = 'network' | 'http' | 'parse' | 'api';
+export declare abstract class TelegramApiClientError extends Error {
+    readonly kind: TelegramApiClientErrorKind;
+    readonly method: string;
+    protected constructor(kind: TelegramApiClientErrorKind, method: string, message: string);
+}
+export declare class TelegramNetworkError extends TelegramApiClientError {
+    readonly detail: string;
+    readonly aborted: boolean;
+    constructor(method: string, detail: string, aborted?: boolean);
+}
+export declare class TelegramHttpError extends TelegramApiClientError {
+    readonly status: number;
+    constructor(method: string, status: number, statusText?: string | undefined);
+}
+export declare class TelegramResponseParseError extends TelegramApiClientError {
+    constructor(method: string, detail: string);
+}
+export declare class TelegramBotApiError extends TelegramApiClientError {
+    readonly errorCode?: number | undefined;
+    readonly httpStatus?: number | undefined;
+    readonly description: string;
+    readonly retryAfterSeconds?: number | undefined;
+    readonly migrateToChatId?: number | undefined;
+    constructor(method: string, opts: {
+        errorCode?: number | undefined;
+        httpStatus?: number | undefined;
+        description: string;
+        retryAfterSeconds?: number | undefined;
+        migrateToChatId?: number | undefined;
+    });
+}
+export interface RetryDecision {
+    /** Whether to retry the request. */
+    retry: boolean;
+    /** Milliseconds to wait before retrying. 0 when retry is false. */
+    delayMs: number;
+}
+/**
+ * Classify a caught error and decide whether to retry, and how long to wait.
+ * @param err The error thrown by api-client methods.
+ * @param attempt 1-based attempt counter.
+ * @returns A RetryDecision.
+ */
+export declare function classifyRetry(err: unknown, attempt: number): RetryDecision;
+type TelegramFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface TelegramApiClientOptions {
+    token: string;
+    /** Override used by deterministic tests or Bot API proxies. */
+    apiRoot?: string | undefined;
+    /** Optional transport injection. Defaults to globalThis.fetch at call time. */
+    fetch?: TelegramFetch | undefined;
+}
+export interface TelegramRequestOptions {
+    signal?: AbortSignal | undefined;
+}
+export interface TelegramGetUpdatesOptions extends TelegramRequestOptions {
+    deadlineMs?: number | undefined;
+    offset: number;
+    timeoutSeconds: number;
+}
+/** Build the one canonical, token-bearing Bot API base URL. Never log this value. */
+export declare function buildTelegramBotApiBaseUrl(token: string, apiRoot?: string): string;
+export declare function abortableSleep(ms: number, signal?: AbortSignal | undefined): Promise<void>;
+export declare class TelegramApiClient {
+    readonly safeBaseUrl: string;
+    private readonly token;
+    private readonly baseUrl;
+    private readonly fetchOverride?;
+    constructor(opts: TelegramApiClientOptions);
+    getMe(opts?: TelegramRequestOptions): Promise<TelegramApiUser>;
+    getUpdates(opts: TelegramGetUpdatesOptions): Promise<TelegramApiUpdate[]>;
+    sendMessage(chatId: string | number, text: string, opts?: TelegramRequestOptions): Promise<TelegramApiMessage>;
+    sendMessageWithKeyboard(chatId: string | number, text: string, buttons: readonly TelegramInlineKeyboardButton[], opts?: TelegramRequestOptions): Promise<TelegramApiMessage>;
+    answerCallbackQuery(callbackQueryId: string, text: string, showAlert: boolean, opts?: TelegramRequestOptions): Promise<boolean>;
+    private request;
+    private redact;
+}
+export {};
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

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

package/dist/bot-queue.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from '@wrongstack/core';
+import type { TelegramApiMessage } from './api-client.js';
+import type { TelegramBot, TelegramBotResponse } from './bot.js';
+export interface BotOutboundOptions {
+    readonly bot: TelegramBot;
+    /** Pass-through logger (defaults to bot's internal logger via the bot's debug hook). */
+    readonly log: Logger;
+    /** Optional override; defaults to 32 entries per chat. */
+    readonly maxPerChat?: number;
+    /** Optional override; defaults to 4 concurrent sends. */
+    readonly maxConcurrency?: number;
+}
+export declare class TelegramBotOutbound {
+    #private;
+    constructor(opts: BotOutboundOptions);
+    /** Manual send (telegram_send tool, /telegram:send): never silently dropped. */
+    sendManual(chatId: string | number, text: string): Promise<TelegramBotResponse<TelegramApiMessage>>;
+    /**
+     * Notification send (session ended, long tool, delegate): fire-and-forget.
+     * The returned promise resolves as soon as the queue accepts the entry;
+     * downstream send failures are logged and counted but not surfaced.
+     */
+    enqueueNotification(chatId: string | number, text: string): void;
+    stats(): import("./outbound-queue.js").OutboundQueueStats;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=bot-queue.d.ts.map

package/dist/bot-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-queue.d.ts","sourceRoot":"","sources":["../src/bot-queue.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAGjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,qBAAa,mBAAmB;;IAM9B,YAAY,IAAI,EAAE,kBAAkB,EAenC;IAED,gFAAgF;IAC1E,UAAU,CACd,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC,CASlD;IAED;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAW/D;IAED,KAAK,qDAEJ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1B;CACF"}

package/dist/bot.d.ts

@@ -1,29 +1,10 @@
 import type { Logger } from '@wrongstack/core';
+import { type TelegramApiMessage } from './api-client.js';
+import type { OffsetStore } from './offset-store.js';
 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 TelegramBotResponse<T> {
+    ok: true;
+    result: T;
 }
 export interface TelegramIncomingMessage {
     messageId: number;
@@ -34,6 +15,22 @@ export interface TelegramIncomingMessage {
     text: string;
     timestamp: number;
 }
+export interface TelegramApprovalResult {
+    approved: boolean;
+    fromUser: string;
+    fromUserId?: number | undefined;
+}
+export interface TelegramApprovalRequestInput {
+    requestId: string;
+    sessionId: string;
+    expectedChatId: string | number;
+    expectedUserIds: readonly (string | number)[];
+    /** Group/supergroup callbacks are rejected unless this was explicitly enabled. */
+    allowGroup: boolean;
+    expiresAt: number;
+    /** Cancels the request when its owning tool execution is aborted. */
+    signal?: AbortSignal | undefined;
+}
 export interface TelegramBotOptions {
     token: string;
     pollIntervalSec: number;
@@ -45,11 +42,11 @@ export interface TelegramBotOptions {
     /** 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.
+     * Optional typed offset store. When provided, the polling offset is persisted
+     * atomically on every successful poll and restored on startup, preventing
+     * message replay after crashes or restarts.
      */
-    offsetStoragePath?: string | undefined;
+    offsetStore?: OffsetStore | undefined;
     /**
      * Optional cross-process single-poller lock. Telegram allows one
      * `getUpdates` consumer per token; when another wstack instance holds the
@@ -61,9 +58,7 @@ export interface TelegramBotOptions {
     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 api;
     private readonly pollIntervalMs;
     private readonly allowedUsers;
     private readonly allowedChats;
@@ -84,8 +79,8 @@ export declare class TelegramBot {
     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?;
+    /** Typed offset store for atomic polling-cursor persistence. */
+    private readonly offsetStore?;
     /** Single-poller election across wstack instances sharing this token. */
     private readonly lock?;
     private readonly standbyRetryMs;
@@ -118,7 +113,7 @@ export declare class TelegramBot {
     /** 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>>;
+    sendMessage(chatId: string | number, text: string, signal?: AbortSignal | undefined): Promise<TelegramBotResponse<TelegramApiMessage>>;
     /**
      * Send a message that has up to one row of inline buttons (Telegram's
      * `inline_keyboard`). Used by `telegram_approve` to present a
@@ -128,28 +123,26 @@ export declare class TelegramBot {
     sendMessageWithKeyboard(chatId: string | number, text: string, buttons: Array<{
         text: string;
         callback_data: string;
-    }>): Promise<TgResponse<TgMessage>>;
-    health(): Promise<{
+    }>, signal?: AbortSignal | undefined): Promise<TelegramBotResponse<TelegramApiMessage>>;
+    health(signal?: AbortSignal | undefined): 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.
+     * 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.
      */
+    private inboundDenialReason;
+    private processMessage;
     /**
-     * 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.
+     * Resolve a pending approval request exactly once and record its terminal
+     * state before removing it from the live registry.
      */
-    private rejectWaiter;
+    private settleApproval;
     private dispatchCallback;
     /**
      * POST /answerCallbackQuery for a callback. Best-effort: failures are
@@ -159,34 +152,24 @@ export declare class TelegramBot {
      */
     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.
+     * Register one approval request before its prompt is sent. The returned
+     * promise owns the request's only timer and resolves on one terminal event.
      */
-    awaitCallback(key: string, timeoutMs: number): Promise<{
-        approved: boolean;
-        fromUser: string;
-    }>;
+    awaitApproval(input: TelegramApprovalRequestInput): Promise<TelegramApprovalResult>;
+    /**
+     * 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: string, promptMessageId: number): boolean;
+    /** Cancel a request that cannot reach a valid terminal callback. */
+    cancelApproval(requestId: string, fromUser?: string): boolean;
     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

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

package/dist/config-classifier.d.ts

@@ -0,0 +1,64 @@
+import type { TelegramPluginConfig } from './config.js';
+/**
+ * Keys the Telegram plugin can apply live without restarting the bot.
+ *
+ * Rationale per key:
+ * - `inboundMode` / `allowedUsers` / `allowedChats` — `processMessage`
+ *   and `dispatchCallback` re-read the allowlist on every inbound call,
+ *   so toggling the mode or editing the lists takes effect immediately.
+ * - `notifyOnSessionEnd` / `notifyOnDelegate` — re-evaluated on each
+ *   event subscription; no in-flight state to restart.
+ * - `longToolThresholdMs` — pure threshold read inside the tool-notify
+ *   handler; the next long-tool event uses the new value.
+ * - `maxMessageLength` / `allowedOutboundChats` — re-read on every
+ *   `sendMessage` / outbound-target resolution, so the next send reflects
+ *   the change.
+ * - `pollIntervalSec` — the poller reads this on each iteration of its
+ *   wait loop; the next tick uses the new interval.
+ * - `outboundQueuePerChat` / `outboundQueueConcurrency` — the outbound
+ *   queue reads these only at construction. They are documented as
+ *   hot-reload in spirit (the queue can be re-evaluated) but the live
+ *   queue owns a stable copy. Marking them HOT would silently mislead,
+ *   so they are intentionally EXCLUDED until the queue supports
+ *   mid-flight reconfiguration. See `restart-required` below.
+ */
+export declare const HOT_RELOAD_KEYS: Set<keyof TelegramPluginConfig>;
+/**
+ * Keys that require restarting the Telegram plugin (or wstack itself)
+ * for the new value to take effect.
+ *
+ * - `botToken` — every Telegram transport object is constructed once with
+ *   the token baked into the base URL; changing it requires a new
+ *   `TelegramBot` instance.
+ * - `notifyChatId` — bound into the optional-allowedUsers fallback at
+ *   setup (`inboundAllowlist`) and read by every notification callback;
+ *   the inbound allowlist does not rebuild without a setup re-run.
+ * - `offsetStoragePath` — the `OffsetStore` is opened once at setup;
+ *   changing the path would orphan any persisted cursor.
+ * - `singleInstanceLock` — the cross-process `PollLock` is acquired at
+ *   startup; flipping this flag requires a fresh setup to acquire /
+ *   release the right lock file.
+ * - `outboundQueuePerChat` / `outboundQueueConcurrency` — the
+ *   `OutboundQueue` reads these at construction only.
+ */
+export declare const RESTART_REQUIRED_KEYS: Set<keyof TelegramPluginConfig>;
+export type ConfigReloadClass = 'hot' | 'restart-required';
+/**
+ * Classify a single key. Returns `'hot'` for keys in `HOT_RELOAD_KEYS`,
+ * `'restart-required'` for keys in `RESTART_REQUIRED_KEYS`, and
+ * `'restart-required'` as a conservative default for keys that are not
+ * registered in either set — preventing a new field from silently
+ * pretending to be hot-reloadable before the classifier is updated.
+ */
+export declare function classifyReload(key: keyof TelegramPluginConfig): ConfigReloadClass;
+/**
+ * Diff two configs and return the keys whose values differ, each tagged
+ * with its reload classification. Keys present in `previous` but absent in
+ * `next` (or vice versa) are reported as `'restart-required'` so a stale
+ * removal is never silently applied as a live change.
+ */
+export declare function diffConfigKeys(previous: TelegramPluginConfig, next: TelegramPluginConfig): Array<{
+    key: keyof TelegramPluginConfig;
+    classification: ConfigReloadClass;
+}>;
+//# sourceMappingURL=config-classifier.d.ts.map

package/dist/config-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-classifier.d.ts","sourceRoot":"","sources":["../src/config-classifier.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe,iCAU1B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,iCAOhC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,kBAAkB,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,oBAAoB,GAAG,iBAAiB,CAGjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,EAAE,oBAAoB,GACzB,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;IAAC,cAAc,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAc/E"}

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { PluginAPI } from '@wrongstack/core';
 export declare const PLUGIN_NAME = "telegram";
+export type TelegramInboundMode = 'disabled' | 'paired' | 'allowlist' | 'public';
 export interface TelegramPluginConfig {
     /** Telegram Bot API token (from @BotFather). */
     botToken: string;
@@ -9,15 +10,17 @@ export interface TelegramPluginConfig {
      */
     notifyChatId?: string | number | undefined;
     /**
-     * List of user/chat IDs allowed to interact with the bot.
-     * Empty = allow all. Recommended to set in production.
+     * Controls who may send inbound messages to the bot. Defaults to `disabled`
+     * for new/unpaired configurations. Legacy configurations are migrated to
+     * `allowlist` when IDs exist, or `paired` when `notifyChatId` exists.
      */
+    inboundMode?: TelegramInboundMode | undefined;
+    /** List of user IDs accepted when `inboundMode` is `allowlist`. */
     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.
-     */
+    /** List of chat IDs accepted when `inboundMode` is `allowlist`. */
     allowedChats?: Array<string | number> | undefined;
+    /** Additional trusted targets for outbound sends beyond `notifyChatId`. */
+    allowedOutboundChats?: Array<string | number> | undefined;
     /** Polling interval in seconds (default: 2). */
     pollIntervalSec?: number | undefined;
     /** Notify on Telegram when a session ends. */
@@ -43,6 +46,14 @@ export interface TelegramPluginConfig {
      * Set false only if this is guaranteed to be the sole consumer.
      */
     singleInstanceLock?: boolean | undefined;
+    /**
+     * Per-chat pending-message cap for the outbound queue. Older pending
+     * notification entries are dropped when this is exceeded; manual
+     * telegram_send entries surface the overflow as an error. Default: 32.
+     */
+    outboundQueuePerChat?: number | undefined;
+    /** Maximum concurrent outbound sends across all chats. Default: 4. */
+    outboundQueueConcurrency?: number | undefined;
 }
 export declare const DEFAULT_CONFIG: Required<Omit<TelegramPluginConfig, 'botToken' | 'notifyChatId' | 'offsetStoragePath'>>;
 export declare const telegramConfigSchema: {
@@ -58,6 +69,12 @@ export declare const telegramConfigSchema: {
             }[];
             description: string;
         };
+        inboundMode: {
+            type: string;
+            enum: ("allowlist" | "disabled" | "paired" | "public")[];
+            default: string;
+            description: string;
+        };
         allowedUsers: {
             type: string;
             items: {
@@ -76,6 +93,15 @@ export declare const telegramConfigSchema: {
             };
             description: string;
         };
+        allowedOutboundChats: {
+            type: string;
+            items: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            description: string;
+        };
         pollIntervalSec: {
             type: string;
             minimum: number;
@@ -101,8 +127,20 @@ export declare const telegramConfigSchema: {
             type: string;
             description: string;
         };
+        outboundQueuePerChat: {
+            type: string;
+            minimum: number;
+            maximum: number;
+            description: string;
+        };
+        outboundQueueConcurrency: {
+            type: string;
+            minimum: number;
+            maximum: number;
+            description: string;
+        };
     };
     required: string[];
 };
-export declare function readTelegramConfig(api: Pick<PluginAPI, 'config'>): Required<Omit<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>> & Pick<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>;
+export declare function readTelegramConfig(api: Pick<PluginAPI, 'config'> & Partial<Pick<PluginAPI, 'log'>>): Required<Omit<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>> & Pick<TelegramPluginConfig, 'notifyChatId' | 'offsetStoragePath'>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +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"}
+{"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,MAAM,mBAAmB,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAIjF,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC9C,mEAAmE;IACnE,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,mEAAmE;IACnE,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1D,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;IACzC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,sEAAsE;IACtE,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CACnC,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,cAAc,GAAG,mBAAmB,CAAC,CAc9E,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAGjB,IAAI;YAAY,WAAW;;;;;;;;;YAMrC,IAAI;YACJ,IAAI;YACJ,OAAO;YACP,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAmBX,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;;;YAIX,IAAI;YACJ,OAAO;YACP,OAAO;YACP,WAAW;;;YAGX,IAAI;YACJ,OAAO;YACP,OAAO;YACP,WAAW;;;;CAIhB,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,GAC/D,QAAQ,CAAC,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAAC,GAC3E,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAuBjE"}