charness 0.0.0-stage → 3.0.0

package/dist/connectors/telegram/timezonePicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezonePicker.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/timezonePicker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAKlC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAQnC,oDAAoD;AACpD,eAAO,MAAM,0BAA0B,WAAW,CAAC;AACnD,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,QAAsB,CAAC;AACxD,eAAO,MAAM,kBAAkB,QAAqB,CAAC;AAErD,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAIlF;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI9E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInF;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEtE;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,iEA4BnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC;IACnD,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,kBAAkB,GAAG,IAAI,CA8B3B"}

package/dist/connectors/telegram/timezonePicker.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zonePickCallbackRe = exports.regionPageCallbackRe = exports.timezoneAutoCallback = exports.timezonePickerBackCallback = exports.timezonePageSize = void 0;
+exports.buildRegionPageCallback = buildRegionPageCallback;
+exports.buildZonePickCallback = buildZonePickCallback;
+exports.parseRegionPageCallback = parseRegionPageCallback;
+exports.parseZonePickCallback = parseZonePickCallback;
+exports.getTimezoneAt = getTimezoneAt;
+exports.getTimezoneRegionAt = getTimezoneRegionAt;
+exports.buildTimezoneRegionPicker = buildTimezoneRegionPicker;
+exports.buildTimezoneZonePicker = buildTimezoneZonePicker;
+/**
+ * @description Pure builders + callback codec for the two-level `/timezone`
+ * picker: level 1 is the 10 IANA regions, level 2 is that region's zones,
+ * paginated.
+ *
+ * Two levels rather than one flat list because there are 418 zones — the same
+ * constraint that forced `/model` into a provider → models picker once a
+ * provider with hundreds of models appeared. And every callback carries INDEXES
+ * rather than the zone name: `America/Argentina/Buenos_Aires` plus a region
+ * index and a page number does not reliably fit Telegram's 64-BYTE
+ * `callback_data` cap, and a truncated id resolves to the wrong zone silently.
+ *
+ * Kept pure (no `t()`, no bot state) so the `✓` placement, the pagination
+ * clamping and the codec round-trip are unit-testable without a Telegram
+ * surface. Header TEXT is the caller's job — it is localized, the keyboard is
+ * not.
+ */
+const telegraf_1 = require("telegraf");
+const paginateList_1 = require("../../utils/paginateList");
+const timezone_1 = require("../../utils/timezone");
+/** Zones listed per level-2 page — one per row, matching `/model`'s page size. */
+exports.timezonePageSize = 10;
+/** Regions per keyboard row on level 1 (10 regions ⇒ 5 rows). */
+const regionsPerRow = 2;
+const regionPageCallbackPrefix = 'tzr_';
+const zonePickCallbackPrefix = 'tz_';
+/** Back to the region level (level 2 → level 1). */
+exports.timezonePickerBackCallback = 'tzback';
+/** Reset the setting to the host zone. */
+exports.timezoneAutoCallback = 'tzauto';
+/** Anchored matchers for `bot.action(...)` — the wire format's single definition. */
+exports.regionPageCallbackRe = /^tzr_(\d+)_(\d+)$/;
+exports.zonePickCallbackRe = /^tz_(\d+)_(\d+)$/;
+function buildRegionPageCallback(regionIndex, page) {
+    return `${regionPageCallbackPrefix}${regionIndex}_${page}`;
+}
+function buildZonePickCallback(regionIndex, zoneIndex) {
+    return `${zonePickCallbackPrefix}${regionIndex}_${zoneIndex}`;
+}
+function parseRegionPageCallback(callbackData) {
+    const match = exports.regionPageCallbackRe.exec(callbackData);
+    if (!match)
+        return null;
+    return { regionIndex: Number(match[1]), page: Number(match[2]) };
+}
+function parseZonePickCallback(callbackData) {
+    const match = exports.zonePickCallbackRe.exec(callbackData);
+    if (!match)
+        return null;
+    return { regionIndex: Number(match[1]), zoneIndex: Number(match[2]) };
+}
+/**
+ * @description Resolve a level-2 pick back to its zone name, or `null` when the
+ * indexes no longer resolve. Stale keyboards stay tappable forever in Telegram,
+ * so an out-of-range index must answer "nothing" rather than pick a neighbour.
+ */
+function getTimezoneAt(regionIndex, zoneIndex) {
+    const region = (0, timezone_1.listTimezoneRegions)()[regionIndex];
+    if (region === undefined)
+        return null;
+    return (0, timezone_1.getTimezonesForRegion)(region)[zoneIndex] ?? null;
+}
+/** The region name at `regionIndex`, or `null` for a stale index. */
+function getTimezoneRegionAt(regionIndex) {
+    return (0, timezone_1.listTimezoneRegions)()[regionIndex] ?? null;
+}
+/** `✓ `-prefix a label when it is the current selection. */
+function getSelectionLabel(label, isCurrent) {
+    return isCurrent ? `✓ ${label}` : label;
+}
+/**
+ * @description Build the level-1 region keyboard, two regions per row, plus a
+ * full-width `🌐 Auto (host zone)` reset row.
+ *
+ * The `✓` marks the region CONTAINING the current zone (so the operator can see
+ * where they are without opening a page), or the Auto row when nothing is
+ * stored. A fixed-offset zone (`+04:00`) belongs to no region, so no region is
+ * marked — that is honest rather than arbitrarily highlighting one.
+ *
+ * `🌐 Auto (host zone)` is a fixed glyph+word rather than a translated string,
+ * mirroring the `/language` picker's Auto row: recognisable across locales and
+ * one less per-locale key to keep in parity.
+ */
+function buildTimezoneRegionPicker(currentZone) {
+    const regions = (0, timezone_1.listTimezoneRegions)();
+    const currentRegion = currentZone === null ? null : (0, timezone_1.getTimezoneRegion)(currentZone);
+    const rows = [];
+    for (let index = 0; index < regions.length; index += regionsPerRow) {
+        const row = [];
+        for (let offset = 0; offset < regionsPerRow; offset += 1) {
+            const region = regions[index + offset];
+            if (region === undefined)
+                break;
+            row.push(telegraf_1.Markup.button.callback(getSelectionLabel(region, region === currentRegion), buildRegionPageCallback(index + offset, 0)));
+        }
+        rows.push(row);
+    }
+    rows.push([
+        telegraf_1.Markup.button.callback(getSelectionLabel('🌐 Auto (host zone)', currentZone === null), exports.timezoneAutoCallback),
+    ]);
+    return telegraf_1.Markup.inlineKeyboard(rows);
+}
+/**
+ * @description Build a region's zone page: one zone per row (names are long),
+ * with a `‹ Prev` / page pill / `⬅ Regions` / `Next ›` navigation row.
+ *
+ * Returns `null` for a region index that no longer resolves — a stale callback
+ * must be answered as expired, not rendered against a different region.
+ */
+function buildTimezoneZonePicker(regionIndex, page, currentZone) {
+    const region = getTimezoneRegionAt(regionIndex);
+    if (region === null)
+        return null;
+    const zones = (0, timezone_1.getTimezonesForRegion)(region);
+    const { slice, currentPage, totalPages } = (0, paginateList_1.paginateList)(zones, page, exports.timezonePageSize);
+    const pageOffset = currentPage * exports.timezonePageSize;
+    const rows = slice.map((zone, sliceIndex) => [
+        telegraf_1.Markup.button.callback(getSelectionLabel(zone, zone === currentZone), buildZonePickCallback(regionIndex, pageOffset + sliceIndex)),
+    ]);
+    const navigationRow = [];
+    if (currentPage > 0) {
+        navigationRow.push(telegraf_1.Markup.button.callback('‹ Prev', buildRegionPageCallback(regionIndex, currentPage - 1)));
+    }
+    navigationRow.push(telegraf_1.Markup.button.callback('⬅ Regions', exports.timezonePickerBackCallback));
+    if (currentPage < totalPages - 1) {
+        navigationRow.push(telegraf_1.Markup.button.callback('Next ›', buildRegionPageCallback(regionIndex, currentPage + 1)));
+    }
+    rows.push(navigationRow);
+    return { region, keyboard: telegraf_1.Markup.inlineKeyboard(rows), currentPage, totalPages };
+}
+//# sourceMappingURL=timezonePicker.js.map

package/dist/connectors/telegram/timezonePicker.js.map

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

package/dist/connectors/telegram/updateDispatcher.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @description Decouples Telegraf's long-polling intake from per-handler
+ * latency so load in one topic can no longer delay intake (or the read-✓✓
+ * receipt) of another.
+ *
+ * **The problem.** Telegraf 4.16.3 long-polling runs
+ * `for await (updates) await Promise.all(updates.map(handleUpdate))`. The next
+ * `getUpdates` — which BOTH acknowledges the previous batch (flips the user's
+ * second checkmark) AND fetches new messages for every thread — cannot fire
+ * until every handler in the current batch resolves. One handler stuck on a
+ * Telegram send (worse: under a 429 cooldown), an agent start, or a folder
+ * mkdir holds the whole loop, so unrelated topics stall.
+ *
+ * **The fix.** Wrap `bot.handleUpdate` so it ENQUEUES the real work into a
+ * per-thread serial queue and resolves immediately. `Promise.all` then resolves
+ * at once, the next `getUpdates` (ACK + new batch) fires now, and the real
+ * middleware chain runs off the polling loop — per-thread-serial, cross-thread
+ * parallel.
+ *
+ * **ACK-before-process is accepted** (matches the existing `voiceQueue`): the
+ * offset is sent as soon as the update is enqueued, so an update queued but not
+ * yet processed at a HARD crash is lost (Telegram won't redeliver). Graceful
+ * shutdown drains the queues (bounded), so only an actual crash can drop work.
+ */
+import type { ServerResponse } from 'http';
+import type { Update } from 'telegraf/typings/core/types/typegram';
+/**
+ * @description Coarse serialization key for a RAW Telegram update:
+ * `"<chatId>:<threadId>"`, or `"global"` for updates with no chat. It governs
+ * ONLY queue serialization + cross-thread parallelism — routing correctness
+ * stays inside the unchanged handler chain, which re-resolves the real
+ * `SessionKey` itself. Narrowed on the `Update` union (no `any`).
+ */
+export declare function getUpdateQueueKey(update: Update): string;
+export interface UpdateDispatcherDeps {
+    /** Map a raw update to its serialization key (FIFO per key, parallel across keys). */
+    getKey: (update: Update) => string;
+    /**
+     * Backstop for an unexpected rejection of the wrapped chain. The original
+     * `bot.handleUpdate` already routes handler errors to `bot.catch`, so this
+     * only fires if the chain rejects outside that — never swallow it silently.
+     */
+    onError?: (error: unknown, update: Update) => void;
+}
+export interface UpdateDispatcher {
+    /**
+     * Append `run` to the update's per-key serial queue and return SYNCHRONOUSLY
+     * (does not await `run`). Preserves arrival order within a key; never throws.
+     */
+    dispatch(update: Update, run: () => Promise<void>): void;
+    /**
+     * Await all outstanding work to settle, raced against `timeoutMs` so it can
+     * never outlast the shutdown watchdog. Used by the graceful-shutdown drain.
+     */
+    drainIdle(timeoutMs: number): Promise<void>;
+    /** Outstanding (queued + in-flight) task count — for tests / metrics. */
+    size(): number;
+}
+/**
+ * @description Build the per-thread serial dispatcher. One {@link SerialQueue}
+ * per key (created lazily; the map is bounded by the number of active topics);
+ * different keys run concurrently.
+ */
+export declare function createUpdateDispatcher(deps: UpdateDispatcherDeps): UpdateDispatcher;
+/**
+ * Minimal seam over Telegraf's reassignable `handleUpdate`. The polling loop
+ * calls `this.handleUpdate(update)` per update, so reassigning the instance
+ * property before `bot.launch` re-routes every update through the dispatcher.
+ */
+interface DispatchableBot {
+    handleUpdate(update: Update, webhookResponse?: ServerResponse): Promise<void>;
+}
+/**
+ * @description Reassign `bot.handleUpdate` to enqueue via `dispatcher` and
+ * resolve immediately, so the polling loop's `Promise.all` settles at once and
+ * the next `getUpdates` (ACK + fetch) fires without waiting on the handlers.
+ *
+ * **Polling-only.** The captured `webhookResponse` is forwarded to the original
+ * for completeness, but a webhook deployment would need its response written
+ * synchronously per update — this offload model only fits long polling, which
+ * is the bot's sole transport (`bot.launch`).
+ */
+export declare function installUpdateDispatcher(bot: DispatchableBot, dispatcher: UpdateDispatcher): void;
+export {};
+//# sourceMappingURL=updateDispatcher.d.ts.map

package/dist/connectors/telegram/updateDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateDispatcher.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/updateDispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AAYnE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgDxD;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,yEAAyE;IACzE,IAAI,IAAI,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAmDnF;AAED;;;;GAIG;AACH,UAAU,eAAe;IACvB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAMhG"}

package/dist/connectors/telegram/updateDispatcher.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * @description Decouples Telegraf's long-polling intake from per-handler
+ * latency so load in one topic can no longer delay intake (or the read-✓✓
+ * receipt) of another.
+ *
+ * **The problem.** Telegraf 4.16.3 long-polling runs
+ * `for await (updates) await Promise.all(updates.map(handleUpdate))`. The next
+ * `getUpdates` — which BOTH acknowledges the previous batch (flips the user's
+ * second checkmark) AND fetches new messages for every thread — cannot fire
+ * until every handler in the current batch resolves. One handler stuck on a
+ * Telegram send (worse: under a 429 cooldown), an agent start, or a folder
+ * mkdir holds the whole loop, so unrelated topics stall.
+ *
+ * **The fix.** Wrap `bot.handleUpdate` so it ENQUEUES the real work into a
+ * per-thread serial queue and resolves immediately. `Promise.all` then resolves
+ * at once, the next `getUpdates` (ACK + new batch) fires now, and the real
+ * middleware chain runs off the polling loop — per-thread-serial, cross-thread
+ * parallel.
+ *
+ * **ACK-before-process is accepted** (matches the existing `voiceQueue`): the
+ * offset is sent as soon as the update is enqueued, so an update queued but not
+ * yet processed at a HARD crash is lost (Telegram won't redeliver). Graceful
+ * shutdown drains the queues (bounded), so only an actual crash can drop work.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUpdateQueueKey = getUpdateQueueKey;
+exports.createUpdateDispatcher = createUpdateDispatcher;
+exports.installUpdateDispatcher = installUpdateDispatcher;
+const serialQueue_1 = require("../../utils/serialQueue");
+/** Key for updates that carry no chat (inline query, poll, etc.) — one queue. */
+const globalQueueKey = 'global';
+/** Stand-in thread id for chats without a forum topic (DMs, basic groups). */
+const noThreadId = 0;
+function buildQueueKey(chatId, threadId) {
+    return `${chatId}:${threadId ?? noThreadId}`;
+}
+/**
+ * @description Coarse serialization key for a RAW Telegram update:
+ * `"<chatId>:<threadId>"`, or `"global"` for updates with no chat. It governs
+ * ONLY queue serialization + cross-thread parallelism — routing correctness
+ * stays inside the unchanged handler chain, which re-resolves the real
+ * `SessionKey` itself. Narrowed on the `Update` union (no `any`).
+ */
+function getUpdateQueueKey(update) {
+    if ('message' in update) {
+        return buildQueueKey(update.message.chat.id, update.message.message_thread_id);
+    }
+    if ('edited_message' in update) {
+        return buildQueueKey(update.edited_message.chat.id, update.edited_message.message_thread_id);
+    }
+    if ('channel_post' in update) {
+        return buildQueueKey(update.channel_post.chat.id, update.channel_post.message_thread_id);
+    }
+    if ('edited_channel_post' in update) {
+        return buildQueueKey(update.edited_channel_post.chat.id, update.edited_channel_post.message_thread_id);
+    }
+    if ('callback_query' in update) {
+        const message = update.callback_query.message;
+        // An inline-mode callback carries no message (only inline_message_id) → no chat.
+        if (!message)
+            return globalQueueKey;
+        // `message_thread_id` exists only on the accessible Message variant.
+        const threadId = 'message_thread_id' in message ? message.message_thread_id : undefined;
+        return buildQueueKey(message.chat.id, threadId);
+    }
+    if ('message_reaction' in update) {
+        return buildQueueKey(update.message_reaction.chat.id, undefined);
+    }
+    if ('message_reaction_count' in update) {
+        return buildQueueKey(update.message_reaction_count.chat.id, undefined);
+    }
+    if ('my_chat_member' in update) {
+        return buildQueueKey(update.my_chat_member.chat.id, undefined);
+    }
+    if ('chat_member' in update) {
+        return buildQueueKey(update.chat_member.chat.id, undefined);
+    }
+    if ('chat_join_request' in update) {
+        return buildQueueKey(update.chat_join_request.chat.id, undefined);
+    }
+    if ('chat_boost' in update) {
+        return buildQueueKey(update.chat_boost.chat.id, undefined);
+    }
+    if ('removed_chat_boost' in update) {
+        return buildQueueKey(update.removed_chat_boost.chat.id, undefined);
+    }
+    // inline_query / chosen_inline_result / shipping_query / pre_checkout_query /
+    // poll / poll_answer carry no chat.
+    return globalQueueKey;
+}
+/**
+ * @description Build the per-thread serial dispatcher. One {@link SerialQueue}
+ * per key (created lazily; the map is bounded by the number of active topics);
+ * different keys run concurrently.
+ */
+function createUpdateDispatcher(deps) {
+    const queues = new Map();
+    const outstanding = new Set();
+    function getQueue(key) {
+        let queue = queues.get(key);
+        if (!queue) {
+            queue = (0, serialQueue_1.createSerialQueue)();
+            queues.set(key, queue);
+        }
+        return queue;
+    }
+    function dispatch(update, run) {
+        const key = deps.getKey(update);
+        const queue = getQueue(key);
+        // `createSerialQueue` recovers its internal tail past a rejection, so a
+        // throwing `run` neither breaks this key's queue nor any sibling key.
+        const task = queue.run(run).then(() => undefined, (error) => {
+            deps.onError?.(error, update);
+        });
+        outstanding.add(task);
+        void task.finally(() => {
+            outstanding.delete(task);
+        });
+    }
+    function drainIdle(timeoutMs) {
+        // Snapshot now: shutdown has already stopped polling, so no new task is
+        // enqueued past this point; tasks still WAITING in their queue are already
+        // in `outstanding` (each `dispatch` adds its task before it starts).
+        const settled = Promise.allSettled(Array.from(outstanding)).then(() => undefined);
+        let handle;
+        const timeout = new Promise((resolve) => {
+            handle = setTimeout(resolve, timeoutMs);
+        });
+        // Clear the loser so a fast drain never leaves a ref'd timer pinning the
+        // event loop open (which would delay process exit on shutdown).
+        return Promise.race([settled, timeout]).finally(() => {
+            if (handle)
+                clearTimeout(handle);
+        });
+    }
+    function size() {
+        return outstanding.size;
+    }
+    return { dispatch, drainIdle, size };
+}
+/**
+ * @description Reassign `bot.handleUpdate` to enqueue via `dispatcher` and
+ * resolve immediately, so the polling loop's `Promise.all` settles at once and
+ * the next `getUpdates` (ACK + fetch) fires without waiting on the handlers.
+ *
+ * **Polling-only.** The captured `webhookResponse` is forwarded to the original
+ * for completeness, but a webhook deployment would need its response written
+ * synchronously per update — this offload model only fits long polling, which
+ * is the bot's sole transport (`bot.launch`).
+ */
+function installUpdateDispatcher(bot, dispatcher) {
+    const original = bot.handleUpdate.bind(bot);
+    bot.handleUpdate = (update, webhookResponse) => {
+        dispatcher.dispatch(update, () => original(update, webhookResponse));
+        return Promise.resolve();
+    };
+}
+//# sourceMappingURL=updateDispatcher.js.map

package/dist/connectors/telegram/updateDispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateDispatcher.js","sourceRoot":"","sources":["../../../src/connectors/telegram/updateDispatcher.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;AAsBH,8CAgDC;AAiCD,wDAmDC;AAqBD,0DAMC;AAjLD,yDAA8E;AAE9E,iFAAiF;AACjF,MAAM,cAAc,GAAG,QAAQ,CAAC;AAChC,8EAA8E;AAC9E,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,SAAS,aAAa,CAAC,MAAc,EAAE,QAA4B;IACjE,OAAO,GAAG,MAAM,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,MAAc;IAC9C,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QACxB,OAAO,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;QAC/B,OAAO,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,cAAc,IAAI,MAAM,EAAE,CAAC;QAC7B,OAAO,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,qBAAqB,IAAI,MAAM,EAAE,CAAC;QACpC,OAAO,aAAa,CAClB,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,EAClC,MAAM,CAAC,mBAAmB,CAAC,iBAAiB,CAC7C,CAAC;IACJ,CAAC;IACD,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC;QAC9C,iFAAiF;QACjF,IAAI,CAAC,OAAO;YAAE,OAAO,cAAc,CAAC;QACpC,qEAAqE;QACrE,MAAM,QAAQ,GAAG,mBAAmB,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,OAAO,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,kBAAkB,IAAI,MAAM,EAAE,CAAC;QACjC,OAAO,aAAa,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,wBAAwB,IAAI,MAAM,EAAE,CAAC;QACvC,OAAO,aAAa,CAAC,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;QAC/B,OAAO,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,aAAa,IAAI,MAAM,EAAE,CAAC;QAC5B,OAAO,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,mBAAmB,IAAI,MAAM,EAAE,CAAC;QAClC,OAAO,aAAa,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,oBAAoB,IAAI,MAAM,EAAE,CAAC;QACnC,OAAO,aAAa,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACrE,CAAC;IACD,8EAA8E;IAC9E,oCAAoC;IACpC,OAAO,cAAc,CAAC;AACxB,CAAC;AA4BD;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,IAA0B;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAiB,CAAC;IAE7C,SAAS,QAAQ,CAAC,GAAW;QAC3B,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,IAAA,+BAAiB,GAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,QAAQ,CAAC,MAAc,EAAE,GAAwB;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,wEAAwE;QACxE,sEAAsE;QACtE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAC9B,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAChC,CAAC,CACF,CAAC;QACF,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YACrB,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,SAAS,SAAS,CAAC,SAAiB;QAClC,wEAAwE;QACxE,2EAA2E;QAC3E,qEAAqE;QACrE,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClF,IAAI,MAAiD,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QACH,yEAAyE;QACzE,gEAAgE;QAChE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;YACnD,IAAI,MAAM;gBAAE,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,SAAS,IAAI;QACX,OAAO,WAAW,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAWD;;;;;;;;;GASG;AACH,SAAgB,uBAAuB,CAAC,GAAoB,EAAE,UAA4B;IACxF,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,GAAG,CAAC,YAAY,GAAG,CAAC,MAAc,EAAE,eAAgC,EAAiB,EAAE;QACrF,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;QACrE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC"}

package/dist/connectors/test/connector.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @description An in-repo connector used ONLY by tests.
+ *
+ * Telegram declares every capability `true`, so without a second connector the
+ * degraded paths — the entire point of capability negotiation — are unreachable
+ * and therefore untested. This double lets a test declare any capability set
+ * and then assert what the core actually got: which content was split, which
+ * options survived, whether a pin was honoured.
+ *
+ * It is a TEST DOUBLE, not a surface: nothing is transmitted anywhere, and no
+ * production module may import it. The boundary guard does not police this
+ * directory because it imports no platform library at all.
+ */
+import type { SessionKey } from '../../sessionKey';
+import type { ConnectorInbound, InboundEvent } from '../../platform/inbound';
+import type { ActivityState, ConnectorCapabilities, ConnectorOutbound, OutboundFileRequest, OutboundHints } from '../../platform/outbound';
+/**
+ * @description The deliberately POOR surface: no editing, no pins, no tappable
+ * controls, no attachments, no threads, no activity affordance, a small message
+ * cap and plain text. Roughly the shape of a tracker comment stream, which is
+ * the first real connector this degradation has to survive.
+ */
+export declare const minimalCapabilities: ConnectorCapabilities;
+/** The opposite pole: everything supported, matching Telegram's declaration. */
+export declare const richCapabilities: ConnectorCapabilities;
+/** One recorded delivery, as the connector actually resolved it. */
+export interface RecordedDelivery {
+    key: SessionKey;
+    /** The message bodies after the connector's own splitting at `maxMessageChars`. */
+    chunks: string[];
+    /** Options the surface really offered as controls — empty when degraded away. */
+    offeredOptionIds: string[];
+    /** Whether the message was actually kept prominent. */
+    wasKeptVisible: boolean;
+    /** Whether it got a message of its own rather than joining the stream. */
+    wasOwnMessage: boolean;
+    hints?: OutboundHints;
+}
+export interface TestConnector extends ConnectorOutbound, ConnectorInbound {
+    readonly deliveries: RecordedDelivery[];
+    readonly files: OutboundFileRequest[];
+    readonly activity: {
+        key: SessionKey;
+        state: ActivityState;
+    }[];
+    readonly finalized: string[];
+    readonly disposed: string[];
+    /** Push an event as if it had arrived from the surface. */
+    emit(event: InboundEvent): Promise<void>;
+}
+export declare function createTestConnector(capabilities?: ConnectorCapabilities): TestConnector;
+//# sourceMappingURL=connector.d.ts.map

package/dist/connectors/test/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/connectors/test/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EAEb,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EAEjB,mBAAmB,EAEnB,aAAa,EACd,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,qBASjC,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,qBAS9B,CAAC;AAEF,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,UAAU,CAAC;IAChB,mFAAmF;IACnF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,uDAAuD;IACvD,cAAc,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB,EAAE,gBAAgB;IACxE,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAgBD,wBAAgB,mBAAmB,CACjC,YAAY,GAAE,qBAA2C,GACxD,aAAa,CA4Ff"}

package/dist/connectors/test/connector.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * @description An in-repo connector used ONLY by tests.
+ *
+ * Telegram declares every capability `true`, so without a second connector the
+ * degraded paths — the entire point of capability negotiation — are unreachable
+ * and therefore untested. This double lets a test declare any capability set
+ * and then assert what the core actually got: which content was split, which
+ * options survived, whether a pin was honoured.
+ *
+ * It is a TEST DOUBLE, not a surface: nothing is transmitted anywhere, and no
+ * production module may import it. The boundary guard does not police this
+ * directory because it imports no platform library at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.richCapabilities = exports.minimalCapabilities = void 0;
+exports.createTestConnector = createTestConnector;
+const sessionKey_1 = require("../../sessionKey");
+const capabilityFallback_1 = require("../../platform/capabilityFallback");
+/**
+ * @description The deliberately POOR surface: no editing, no pins, no tappable
+ * controls, no attachments, no threads, no activity affordance, a small message
+ * cap and plain text. Roughly the shape of a tracker comment stream, which is
+ * the first real connector this degradation has to survive.
+ */
+exports.minimalCapabilities = {
+    editMessages: false,
+    pinMessages: false,
+    tappableOptions: false,
+    attachments: false,
+    threadedReplies: false,
+    activityIndicator: false,
+    maxMessageChars: 40,
+    markupDialect: 'plain',
+};
+/** The opposite pole: everything supported, matching Telegram's declaration. */
+exports.richCapabilities = {
+    editMessages: true,
+    pinMessages: true,
+    tappableOptions: true,
+    attachments: true,
+    threadedReplies: true,
+    activityIndicator: true,
+    maxMessageChars: 4000,
+    markupDialect: 'markdown',
+};
+/**
+ * @description Split at the surface's own cap. Crude on purpose — the point is
+ * to prove the core's content SURVIVES a small cap, not to re-test Telegram's
+ * word-aware splitter.
+ */
+function splitAtCap(text, maxChars) {
+    if (text.length <= maxChars)
+        return [text];
+    const chunks = [];
+    for (let offset = 0; offset < text.length; offset += maxChars) {
+        chunks.push(text.slice(offset, offset + maxChars));
+    }
+    return chunks;
+}
+function createTestConnector(capabilities = exports.minimalCapabilities) {
+    const deliveries = [];
+    const files = [];
+    const activity = [];
+    const finalized = [];
+    const disposed = [];
+    const unfinalized = new Set();
+    let onEvent = null;
+    return {
+        capabilities,
+        deliveries,
+        files,
+        activity,
+        finalized,
+        disposed,
+        async deliver(key, content, hints) {
+            const degraded = (0, capabilityFallback_1.getDegradedContent)(content, capabilities);
+            deliveries.push({
+                key,
+                chunks: splitAtCap(degraded.text, capabilities.maxMessageChars),
+                offeredOptionIds: (degraded.options ?? []).map((option) => option.id),
+                wasKeptVisible: degraded.keepVisible === true,
+                wasOwnMessage: (0, capabilityFallback_1.checkNeedsOwnMessage)(degraded),
+                hints,
+            });
+            if (hints?.isFinal !== true)
+                unfinalized.add((0, sessionKey_1.keyToString)(key));
+        },
+        async deliverFile(key, request) {
+            // Fail LOUDLY rather than pretending: an agent told "sent" for a file the
+            // surface cannot carry would never retry or describe it in text instead.
+            if (!capabilities.attachments) {
+                return { ok: false, error: 'this surface cannot receive file attachments' };
+            }
+            files.push(request);
+            return { ok: true, summary: `Sent ${request.paths.length} file(s) to ${(0, sessionKey_1.keyToString)(key)}.` };
+        },
+        setActivity(key, state) {
+            // A surface with no "working" affordance drops it silently — the core
+            // must not have to know which surfaces have one.
+            if (!capabilities.activityIndicator)
+                return;
+            activity.push({ key, state });
+        },
+        async finalize(key) {
+            const serialized = (0, sessionKey_1.keyToString)(key);
+            finalized.push(serialized);
+            unfinalized.delete(serialized);
+        },
+        dispose(key) {
+            const serialized = (0, sessionKey_1.keyToString)(key);
+            disposed.push(serialized);
+            unfinalized.delete(serialized);
+        },
+        checkIsDelivering(key) {
+            return unfinalized.has((0, sessionKey_1.keyToString)(key));
+        },
+        listUnfinalizedKeys() {
+            const seen = new Map();
+            for (const delivery of deliveries) {
+                const serialized = (0, sessionKey_1.keyToString)(delivery.key);
+                if (unfinalized.has(serialized))
+                    seen.set(serialized, delivery.key);
+            }
+            return [...seen.values()];
+        },
+        async start(handler) {
+            onEvent = handler;
+        },
+        async stop() {
+            onEvent = null;
+        },
+        async listMembersWithElevatedRights() {
+            return [];
+        },
+        async emit(event) {
+            if (!onEvent)
+                return;
+            await onEvent(event);
+        },
+    };
+}
+//# sourceMappingURL=connector.js.map

package/dist/connectors/test/connector.js.map

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

package/dist/connectors/test/sessionKeyCodec.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @description The test double's {@link SessionKeyCodec}.
+ *
+ * It exists so the seam can be exercised with a NON-Telegram platform id —
+ * without one, `keysEqual`'s platform comparison, the registry's
+ * `matches()`-based dispatch and every degraded capability path are unreachable
+ * and would be shipped untested.
+ *
+ * The spelling deliberately contains no `:`, and `|` guarantees the
+ * all-numeric Telegram pattern can never claim one of these strings, and vice
+ * versa. It has no `decodeSlug`: a test key is never read back from a tmux or
+ * directory name.
+ */
+import { type SessionKey, type SessionKeyCodec } from '../../sessionKey';
+export declare const testSessionKeyCodec: SessionKeyCodec;
+/**
+ * NOT self-registering, unlike the Telegram codec: a test double that armed
+ * itself on import would silently join the production registry through any
+ * transitive import. Tests register it explicitly and
+ * `unregisterSessionKeyCodec('test')` when done.
+ */
+export declare function registerTestSessionKeyCodec(): void;
+/** Build a test {@link SessionKey}. Mirrors `makeTelegramKey`'s role. */
+export declare function makeTestKey(space: string, thread: string): SessionKey;
+//# sourceMappingURL=sessionKeyCodec.d.ts.map

package/dist/connectors/test/sessionKeyCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionKeyCodec.d.ts","sourceRoot":"","sources":["../../../src/connectors/test/sessionKeyCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAM1B,eAAO,MAAM,mBAAmB,EAAE,eAgBjC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAErE"}