charness 0.0.0-stage → 3.0.0

package/dist/utils/displayVerbosity.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultDisplayVerbosityMode = exports.displayVerbosityModeOptions = void 0;
+exports.getDefaultDisplayPrefs = getDefaultDisplayPrefs;
+exports.checkIsDisplayVerbosityMode = checkIsDisplayVerbosityMode;
+exports.normalizeDisplayVerbosityMode = normalizeDisplayVerbosityMode;
+const topicView_1 = require("./topicView");
+/** Every selectable display-verbosity mode, in picker-button order (quiet →
+ * loud). Single source of truth for arg validation and the mode keyboards of
+ * all three display commands. */
+exports.displayVerbosityModeOptions = ['minimal', 'short', 'full'];
+/**
+ * @description Locked default for EVERY display pref (user decision
+ * 2026-06-11: "по умолчанию минимум"). `state.ts` resolves absent persisted
+ * fields to it, and the adapters fall back to it for reads that happen before
+ * the bot injects its mode reader at boot.
+ */
+exports.defaultDisplayVerbosityMode = 'minimal';
+/**
+ * @description Every display pref at its locked default — what the adapters
+ * resolve for a read that happens before the bot injects its prefs reader at
+ * boot, and the baseline `state.ts` fills absent persisted fields from.
+ */
+function getDefaultDisplayPrefs() {
+    return {
+        thinking: exports.defaultDisplayVerbosityMode,
+        toolResults: exports.defaultDisplayVerbosityMode,
+        subagent: exports.defaultDisplayVerbosityMode,
+        view: topicView_1.defaultTopicView,
+    };
+}
+/**
+ * @description Type guard: is `value` one of the {@link DisplayVerbosityMode}
+ * options? Narrows a free-form string to the union WITHOUT a cast. Accepts
+ * ONLY the new vocabulary — legacy names go through
+ * {@link normalizeDisplayVerbosityMode}.
+ */
+function checkIsDisplayVerbosityMode(value) {
+    return exports.displayVerbosityModeOptions.includes(value);
+}
+/**
+ * @description The retired per-command mode names mapped onto the unified
+ * vocabulary, preserving each one's behavior:
+ *
+ * - `detailed` → `full`    (thinking: keep the streamed reasoning)
+ * - `brief`    → `short`   (thinking: collapse to "thought for {N}s")
+ * - `hide`     → `minimal` (thinking/tool-results: nothing permanent remains)
+ * - `compact`  → `short`   (subagent: status-only)
+ *
+ * No name collides across the three commands, so ONE shared map covers them
+ * all. Used both for old values persisted in `state.json` and for old names
+ * arriving from command args / stale picker buttons.
+ */
+const legacyDisplayVerbosityAliases = {
+    detailed: 'full',
+    brief: 'short',
+    hide: 'minimal',
+    compact: 'short',
+};
+/**
+ * @description Normalize a mode string to the unified vocabulary: a new name
+ * passes through, a legacy name maps per
+ * {@link legacyDisplayVerbosityAliases}, anything else (unknown string,
+ * `undefined`) → `null` so the caller decides between "use the default"
+ * (read-time normalization of persisted values) and "reject the input"
+ * (command arg / callback validation).
+ */
+function normalizeDisplayVerbosityMode(value) {
+    if (value === undefined)
+        return null;
+    if (checkIsDisplayVerbosityMode(value))
+        return value;
+    return legacyDisplayVerbosityAliases[value] ?? null;
+}
+//# sourceMappingURL=displayVerbosity.js.map

package/dist/utils/displayVerbosity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayVerbosity.js","sourceRoot":"","sources":["../../src/utils/displayVerbosity.ts"],"names":[],"mappings":";;;AA8BA,wDAOC;AAQD,kEAEC;AA8BD,sEAIC;AAvED,2CAA+C;AAE/C;;iCAEiC;AACpB,QAAA,2BAA2B,GAAoC,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAEzG;;;;;GAKG;AACU,QAAA,2BAA2B,GAAyB,SAAS,CAAC;AAE3E;;;;GAIG;AACH,SAAgB,sBAAsB;IACpC,OAAO;QACL,QAAQ,EAAE,mCAA2B;QACrC,WAAW,EAAE,mCAA2B;QACxC,QAAQ,EAAE,mCAA2B;QACrC,IAAI,EAAE,4BAAgB;KACvB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,2BAA2B,CAAC,KAAa;IACvD,OAAQ,mCAAiD,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,6BAA6B,GAA4D;IAC7F,QAAQ,EAAE,MAAM;IAChB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,OAAO;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,6BAA6B,CAAC,KAAyB;IACrE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,2BAA2B,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO,6BAA6B,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AACtD,CAAC"}

package/dist/utils/download.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @description Resilient file download for Telegram media (voice notes, etc.).
+ *
+ * Extracted from `bot.ts` so it is side-effect-free and unit-testable against a
+ * local HTTP server (importing `bot.ts` would construct a Telegraf instance and
+ * read ENV at module load).
+ *
+ * Why this exists as its own module with retries:
+ *
+ * Telegram **API calls** (getUpdates, getFileLink, sendMessage) ride a tuned,
+ * keep-alive, IPv4-pinned `https.Agent` shared by Telegraf — so they reuse a
+ * warm socket. File **downloads** previously used the global agent: a fresh
+ * cold TCP+TLS handshake to `api.telegram.org` on every voice note. On a
+ * throttled / high-latency link that handshake intermittently stalls and trips
+ * the 20s timeout — surfacing to the user as "Download timed out", forcing a
+ * manual re-send. We fix that two ways:
+ *
+ *   1. Reuse the caller's warm agent (passed via `opts.agent`) so downloads
+ *      ride the same pooled IPv4 connection as the API calls.
+ *   2. Retry transient failures (timeout / connection reset / 5xx / 429)
+ *      automatically with exponential backoff, so a single stall recovers on
+ *      its own instead of bubbling up to the user.
+ */
+import * as https from 'https';
+export interface DownloadOptions {
+    /** Reuse a warm keep-alive agent (HTTPS only). Cuts the cold-handshake stall. */
+    agent?: https.Agent;
+    /** Per-attempt socket timeout. */
+    timeoutMs?: number;
+    /** Number of RETRIES after the first attempt (so attempts = retries + 1). */
+    retries?: number;
+    /** Observability hook fired before each retry (1-based attempt that just failed). */
+    onRetry?: (attempt: number, err: Error, delayMs: number) => void;
+}
+/**
+ * @description A download failure that knows whether retrying could help.
+ * Network stalls (timeout, ECONNRESET, …), HTTP 429 and 5xx are retryable;
+ * HTTP 4xx and "too many redirects" are not (resending the same request will
+ * keep failing).
+ */
+export declare class DownloadError extends Error {
+    readonly retryable: boolean;
+    readonly statusCode?: number;
+    constructor(message: string, opts: {
+        retryable: boolean;
+        statusCode?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * @description Classify an arbitrary thrown value into retryable / not.
+ * `DownloadError` carries its own verdict; raw socket errors are matched by
+ * `code`; an unknown error is treated as NON-retryable (fail fast rather than
+ * loop on a bug).
+ */
+export declare function checkIsRetryableDownloadError(err: unknown): boolean;
+/**
+ * @description One download attempt. Follows up to {@link MAX_REDIRECTS} 3xx
+ * hops, rejects non-2xx with a status-tagged {@link DownloadError}, and tears
+ * down the partial file on any failure. Reuses `opts.agent` for HTTPS so the
+ * request rides the warm pooled connection instead of a cold handshake.
+ */
+export declare function downloadFileOnce(url: string, destPath: string, opts?: DownloadOptions, depth?: number): Promise<void>;
+/**
+ * @description Download with automatic retries on transient failures. Resolves
+ * once the file is written; rejects with the LAST error after exhausting
+ * retries (or immediately on a non-retryable error). This is the function
+ * callers should use — a stalled connection now recovers on its own instead of
+ * forcing the user to re-send the media.
+ */
+export declare function downloadFile(url: string, destPath: string, opts?: DownloadOptions): Promise<void>;
+//# sourceMappingURL=download.d.ts.map

package/dist/utils/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/utils/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAc/B,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;IACpB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBACjB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOhG;AAcD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOnE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA8EpH;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3G"}

package/dist/utils/download.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * @description Resilient file download for Telegram media (voice notes, etc.).
+ *
+ * Extracted from `bot.ts` so it is side-effect-free and unit-testable against a
+ * local HTTP server (importing `bot.ts` would construct a Telegraf instance and
+ * read ENV at module load).
+ *
+ * Why this exists as its own module with retries:
+ *
+ * Telegram **API calls** (getUpdates, getFileLink, sendMessage) ride a tuned,
+ * keep-alive, IPv4-pinned `https.Agent` shared by Telegraf — so they reuse a
+ * warm socket. File **downloads** previously used the global agent: a fresh
+ * cold TCP+TLS handshake to `api.telegram.org` on every voice note. On a
+ * throttled / high-latency link that handshake intermittently stalls and trips
+ * the 20s timeout — surfacing to the user as "Download timed out", forcing a
+ * manual re-send. We fix that two ways:
+ *
+ *   1. Reuse the caller's warm agent (passed via `opts.agent`) so downloads
+ *      ride the same pooled IPv4 connection as the API calls.
+ *   2. Retry transient failures (timeout / connection reset / 5xx / 429)
+ *      automatically with exponential backoff, so a single stall recovers on
+ *      its own instead of bubbling up to the user.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DownloadError = void 0;
+exports.checkIsRetryableDownloadError = checkIsRetryableDownloadError;
+exports.downloadFileOnce = downloadFileOnce;
+exports.downloadFile = downloadFile;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const fs = __importStar(require("fs"));
+const fs_1 = require("fs");
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_RETRIES = 2; // → up to 3 attempts total
+const MAX_REDIRECTS = 5;
+/** Backoff before retry attempt N (1-based): 500ms, 1500ms, 3500ms, … (capped). */
+function backoffMs(attempt) {
+    return Math.min(500 * (2 ** attempt - 1), 8_000);
+}
+/**
+ * @description A download failure that knows whether retrying could help.
+ * Network stalls (timeout, ECONNRESET, …), HTTP 429 and 5xx are retryable;
+ * HTTP 4xx and "too many redirects" are not (resending the same request will
+ * keep failing).
+ */
+class DownloadError extends Error {
+    retryable;
+    statusCode;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'DownloadError';
+        this.retryable = opts.retryable;
+        this.statusCode = opts.statusCode;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+exports.DownloadError = DownloadError;
+/** Node socket/DNS error codes that are worth a retry. */
+const RETRYABLE_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ECONNREFUSED',
+    'EAI_AGAIN',
+    'EPIPE',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'ECONNABORTED',
+]);
+/**
+ * @description Classify an arbitrary thrown value into retryable / not.
+ * `DownloadError` carries its own verdict; raw socket errors are matched by
+ * `code`; an unknown error is treated as NON-retryable (fail fast rather than
+ * loop on a bug).
+ */
+function checkIsRetryableDownloadError(err) {
+    if (err instanceof DownloadError)
+        return err.retryable;
+    const code = err?.code;
+    if (code && RETRYABLE_CODES.has(code))
+        return true;
+    // Telegraf/undici sometimes surface socket resets as a bare "socket hang up".
+    const msg = err instanceof Error ? err.message : '';
+    return /socket hang up|timed out|timeout/i.test(msg);
+}
+/**
+ * @description One download attempt. Follows up to {@link MAX_REDIRECTS} 3xx
+ * hops, rejects non-2xx with a status-tagged {@link DownloadError}, and tears
+ * down the partial file on any failure. Reuses `opts.agent` for HTTPS so the
+ * request rides the warm pooled connection instead of a cold handshake.
+ */
+function downloadFileOnce(url, destPath, opts = {}, depth = 0) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (depth > MAX_REDIRECTS) {
+        return Promise.reject(new DownloadError(`Too many redirects (>${MAX_REDIRECTS}) for ${url}`, { retryable: false }));
+    }
+    return new Promise((resolve, reject) => {
+        const isHttps = url.startsWith('https');
+        const client = isHttps ? https : http;
+        const file = fs.createWriteStream(destPath);
+        const cleanup = () => fs_1.promises.unlink(destPath).catch(() => { });
+        // Only an https.Agent makes sense for https requests; never hand it to the
+        // plain-http client (Telegram file URLs are https, but stay defensive).
+        const reqOptions = isHttps && opts.agent ? { agent: opts.agent } : {};
+        const req = client.get(url, reqOptions, (response) => {
+            const status = response.statusCode ?? 0;
+            // Follow redirects (301/302/303/307/308). Drain the response so the
+            // socket can be returned to the keep-alive pool instead of being torn
+            // down — important when reusing a shared agent.
+            if ([301, 302, 303, 307, 308].includes(status)) {
+                const redirectUrl = response.headers.location;
+                if (redirectUrl) {
+                    response.resume();
+                    file.close(() => {
+                        cleanup().then(() => downloadFileOnce(redirectUrl, destPath, opts, depth + 1).then(resolve, reject));
+                    });
+                    return;
+                }
+            }
+            // Anything outside 2xx is a failure. Without this the error body (HTML /
+            // JSON) was piped into the file, yielding broken "audio" that Whisper
+            // later rejected with an opaque 400. 4xx is permanent; 429/5xx may pass
+            // on a retry.
+            if (status < 200 || status >= 300) {
+                response.resume();
+                const retryable = status === 429 || status >= 500;
+                file.close(() => {
+                    cleanup().then(() => reject(new DownloadError(`Download failed: HTTP ${status} ${response.statusMessage ?? ''}`.trim(), { retryable, statusCode: status })));
+                });
+                return;
+            }
+            response.pipe(file);
+            file.on('finish', () => { file.close(() => resolve()); });
+            file.on('error', (err) => {
+                // A local write error (disk full, etc.) is not worth retrying.
+                cleanup().then(() => reject(new DownloadError(`Write failed: ${err.message}`, { retryable: false, cause: err })));
+            });
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy(new DownloadError(`Download timed out after ${timeoutMs}ms`, { retryable: true }));
+        });
+        req.on('error', (err) => {
+            cleanup().then(() => {
+                // `req.destroy(downloadError)` re-emits our own error here — pass it
+                // through unchanged so its `retryable` verdict survives.
+                if (err instanceof DownloadError) {
+                    reject(err);
+                    return;
+                }
+                reject(new DownloadError(err.message, { retryable: checkIsRetryableDownloadError(err), cause: err }));
+            });
+        });
+    });
+}
+/**
+ * @description Download with automatic retries on transient failures. Resolves
+ * once the file is written; rejects with the LAST error after exhausting
+ * retries (or immediately on a non-retryable error). This is the function
+ * callers should use — a stalled connection now recovers on its own instead of
+ * forcing the user to re-send the media.
+ */
+async function downloadFile(url, destPath, opts = {}) {
+    const retries = opts.retries ?? DEFAULT_RETRIES;
+    let lastErr = new DownloadError('download not attempted', { retryable: false });
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            await downloadFileOnce(url, destPath, opts);
+            return;
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err : new Error(String(err));
+            const canRetry = attempt < retries && checkIsRetryableDownloadError(err);
+            if (!canRetry)
+                throw lastErr;
+            const delay = backoffMs(attempt + 1);
+            opts.onRetry?.(attempt + 1, lastErr, delay);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw lastErr;
+}
+//# sourceMappingURL=download.js.map

package/dist/utils/download.js.map

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

package/dist/utils/draftFinalize.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @description Pure boundary/finalize decision for the DM-mode draft "cursor"
+ * (DM streaming v2). The bot keeps ONE accumulating draft holding the full
+ * current reply text and FINALIZES it into a permanent `sendMessage` on a
+ * boundary; after a finalize the next output starts a fresh draft → a new
+ * message.
+ *
+ * This module decides WHICH boundary (if any) a given feed / idle tick hits; the
+ * `bot.ts` draft manager owns the real timers and the Telegram IO (rendering,
+ * `splitMessage`, `sendMessageDraft`, `replyToThread`). Keeping the decision
+ * pure lets a timeline test with an injectable clock prove the gates fire
+ * (mirrors `draftPacer.test.ts`).
+ *
+ * The boundaries (locked in the plan):
+ *  - new-response — a non-continuation output (or a forced new-message break)
+ *    arriving while a draft is already active: finalize the previous draft, then
+ *    start a fresh one for this output;
+ *  - overflow — the prospective accumulated text would render past the Telegram
+ *    cap: finalize the full chunk(s) and continue the remainder in a new draft;
+ *  - isFinal — the turn's last frame: finalize and do not reopen a draft;
+ *  - idle — no new output for {@link FINALIZE_IDLE_MS}: finalize the snapshot;
+ *  - append — none of the above: just grow the draft and pace it.
+ */
+/**
+ * Idle window after the last draft feed with no new output before the draft is
+ * FINALIZED into a permanent message (a pause is a natural message boundary —
+ * like sending what you've typed, then continuing in a new bubble). Repurposes
+ * the value the removed `OUTPUT_DEBOUNCE_MS_DM` held; it is NOT a send-throttle.
+ */
+export declare const FINALIZE_IDLE_MS = 4000;
+/**
+ * @name DraftFeedAction
+ * @description What the draft manager should do with an incoming `output` feed.
+ *
+ * - `finalizeThenStart` — a new response began while a draft was active: finalize
+ *   the active draft to a permanent message FIRST, then open a fresh draft and
+ *   append this output.
+ * - `finalize` — the turn ended (`isFinal`): finalize the active draft (with this
+ *   output appended) and do NOT reopen a draft.
+ * - `overflow` — appending this output makes the draft render past the cap:
+ *   finalize the full chunk(s) as permanent message(s) and carry the remainder
+ *   into a new draft.
+ * - `append` — ordinary streaming tail: grow the draft and pace the update.
+ */
+export type DraftFeedAction = 'finalizeThenStart' | 'finalize' | 'overflow' | 'append';
+export interface DraftFeedInput {
+    /** Is a draft turn currently active (a response is mid-stream)? */
+    isDraftActive: boolean;
+    /** Does this output continue the in-flight response (vs a standalone one)? */
+    isContinuation: boolean;
+    /** Thread flag: the next output must start a new message (user prompt, etc.). */
+    needsNewMessage: boolean;
+    /** Is this the turn's last frame (`OutboundHints.isFinal`)? */
+    isFinal: boolean;
+    /**
+     * Rendered length of the PROSPECTIVE accumulated text once this output is
+     * appended to the active draft (the bot measures it the same way it renders
+     * the draft body). Compared against {@link DraftFeedInput.renderedCap}.
+     */
+    prospectiveRenderedLength: number;
+    /** The rendered-length cap a single draft/message must fit under. */
+    renderedCap: number;
+}
+/**
+ * @description Decide what the draft manager does with an incoming feed.
+ *
+ * Order matters and is load-bearing:
+ *  1. new-response (active draft + a non-continuation / forced break) →
+ *     `finalizeThenStart`: the previous reply is complete, snapshot it before the
+ *     new one overwrites the cursor. Checked before overflow because the
+ *     prospective length is computed against the OLD accumulator and would be
+ *     meaningless across a response boundary.
+ *  2. isFinal → `finalize`: end the turn; no new draft.
+ *  3. overflow (prospective render > cap) → `overflow`: spill into permanent
+ *     message(s) + a fresh draft for the remainder.
+ *  4. otherwise → `append`.
+ */
+export declare function getDraftFeedAction(input: DraftFeedInput): DraftFeedAction;
+/**
+ * @description The effective continuation flag the DM draft cursor should use
+ * for an incoming `output`, accounting for adapters that stream WITHOUT marking
+ * continuations.
+ *
+ * OpenCode marks every tail except the first of a response with
+ * `meta.isContinuation` (it tracks `lastEmittedLength`), so the cursor knows
+ * which outputs accumulate into the live draft. The Claude scrape adapter emits
+ * each poll's delta with NO meta — `metaIsContinuation` is always false — even
+ * though every delta is the SAME answer continuing. Treating those as
+ * non-continuations would hit the new-response boundary on every poll
+ * (`getDraftFeedAction` → `finalizeThenStart`) and flood the topic with one tiny
+ * message per delta.
+ *
+ * For a delta-emitting adapter the answer therefore accumulates as a
+ * continuation; the real turn boundaries are driven separately by
+ * `needsNewMessage` (a new prompt, or the answer→tool transition the bot marks
+ * when output resumes after a status frame), the idle timer, overflow, and
+ * isFinal — exactly the boundary set `getDraftFeedAction` already honours. For a
+ * continuation-marking adapter the meta flag is authoritative and passes through
+ * unchanged.
+ */
+export declare function getDmDraftContinuation(metaIsContinuation: boolean, outputsDeltas: boolean): boolean;
+/**
+ * @description Should the idle timer finalize the draft now? True once a draft
+ * is active and at least {@link FINALIZE_IDLE_MS} has elapsed since the last
+ * feed with no newer output. Never true when nothing has been fed yet
+ * (`lastFedAtMs === null`) or the draft is inactive — there is nothing to
+ * finalize.
+ */
+export declare function checkShouldFinalizeOnIdle(nowMs: number, lastFedAtMs: number | null, isDraftActive: boolean, idleMs: number): boolean;
+//# sourceMappingURL=draftFinalize.d.ts.map

package/dist/utils/draftFinalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draftFinalize.d.ts","sourceRoot":"","sources":["../../src/utils/draftFinalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAMzE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,kBAAkB,EAAE,OAAO,EAC3B,aAAa,EAAE,OAAO,GACrB,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,aAAa,EAAE,OAAO,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAIT"}

package/dist/utils/draftFinalize.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * @description Pure boundary/finalize decision for the DM-mode draft "cursor"
+ * (DM streaming v2). The bot keeps ONE accumulating draft holding the full
+ * current reply text and FINALIZES it into a permanent `sendMessage` on a
+ * boundary; after a finalize the next output starts a fresh draft → a new
+ * message.
+ *
+ * This module decides WHICH boundary (if any) a given feed / idle tick hits; the
+ * `bot.ts` draft manager owns the real timers and the Telegram IO (rendering,
+ * `splitMessage`, `sendMessageDraft`, `replyToThread`). Keeping the decision
+ * pure lets a timeline test with an injectable clock prove the gates fire
+ * (mirrors `draftPacer.test.ts`).
+ *
+ * The boundaries (locked in the plan):
+ *  - new-response — a non-continuation output (or a forced new-message break)
+ *    arriving while a draft is already active: finalize the previous draft, then
+ *    start a fresh one for this output;
+ *  - overflow — the prospective accumulated text would render past the Telegram
+ *    cap: finalize the full chunk(s) and continue the remainder in a new draft;
+ *  - isFinal — the turn's last frame: finalize and do not reopen a draft;
+ *  - idle — no new output for {@link FINALIZE_IDLE_MS}: finalize the snapshot;
+ *  - append — none of the above: just grow the draft and pace it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINALIZE_IDLE_MS = void 0;
+exports.getDraftFeedAction = getDraftFeedAction;
+exports.getDmDraftContinuation = getDmDraftContinuation;
+exports.checkShouldFinalizeOnIdle = checkShouldFinalizeOnIdle;
+/**
+ * Idle window after the last draft feed with no new output before the draft is
+ * FINALIZED into a permanent message (a pause is a natural message boundary —
+ * like sending what you've typed, then continuing in a new bubble). Repurposes
+ * the value the removed `OUTPUT_DEBOUNCE_MS_DM` held; it is NOT a send-throttle.
+ */
+exports.FINALIZE_IDLE_MS = 4000;
+/**
+ * @description Decide what the draft manager does with an incoming feed.
+ *
+ * Order matters and is load-bearing:
+ *  1. new-response (active draft + a non-continuation / forced break) →
+ *     `finalizeThenStart`: the previous reply is complete, snapshot it before the
+ *     new one overwrites the cursor. Checked before overflow because the
+ *     prospective length is computed against the OLD accumulator and would be
+ *     meaningless across a response boundary.
+ *  2. isFinal → `finalize`: end the turn; no new draft.
+ *  3. overflow (prospective render > cap) → `overflow`: spill into permanent
+ *     message(s) + a fresh draft for the remainder.
+ *  4. otherwise → `append`.
+ */
+function getDraftFeedAction(input) {
+    const isStartOfResponse = !input.isContinuation || input.needsNewMessage;
+    if (input.isDraftActive && isStartOfResponse)
+        return 'finalizeThenStart';
+    if (input.isFinal)
+        return 'finalize';
+    if (input.prospectiveRenderedLength > input.renderedCap)
+        return 'overflow';
+    return 'append';
+}
+/**
+ * @description The effective continuation flag the DM draft cursor should use
+ * for an incoming `output`, accounting for adapters that stream WITHOUT marking
+ * continuations.
+ *
+ * OpenCode marks every tail except the first of a response with
+ * `meta.isContinuation` (it tracks `lastEmittedLength`), so the cursor knows
+ * which outputs accumulate into the live draft. The Claude scrape adapter emits
+ * each poll's delta with NO meta — `metaIsContinuation` is always false — even
+ * though every delta is the SAME answer continuing. Treating those as
+ * non-continuations would hit the new-response boundary on every poll
+ * (`getDraftFeedAction` → `finalizeThenStart`) and flood the topic with one tiny
+ * message per delta.
+ *
+ * For a delta-emitting adapter the answer therefore accumulates as a
+ * continuation; the real turn boundaries are driven separately by
+ * `needsNewMessage` (a new prompt, or the answer→tool transition the bot marks
+ * when output resumes after a status frame), the idle timer, overflow, and
+ * isFinal — exactly the boundary set `getDraftFeedAction` already honours. For a
+ * continuation-marking adapter the meta flag is authoritative and passes through
+ * unchanged.
+ */
+function getDmDraftContinuation(metaIsContinuation, outputsDeltas) {
+    return outputsDeltas ? true : metaIsContinuation;
+}
+/**
+ * @description Should the idle timer finalize the draft now? True once a draft
+ * is active and at least {@link FINALIZE_IDLE_MS} has elapsed since the last
+ * feed with no newer output. Never true when nothing has been fed yet
+ * (`lastFedAtMs === null`) or the draft is inactive — there is nothing to
+ * finalize.
+ */
+function checkShouldFinalizeOnIdle(nowMs, lastFedAtMs, isDraftActive, idleMs) {
+    if (!isDraftActive)
+        return false;
+    if (lastFedAtMs === null)
+        return false;
+    return nowMs - lastFedAtMs >= idleMs;
+}
+//# sourceMappingURL=draftFinalize.js.map

package/dist/utils/draftFinalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draftFinalize.js","sourceRoot":"","sources":["../../src/utils/draftFinalize.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AA2DH,gDAMC;AAwBD,wDAKC;AASD,8DASC;AA9GD;;;;;GAKG;AACU,QAAA,gBAAgB,GAAG,IAAI,CAAC;AAqCrC;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAAC,KAAqB;IACtD,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,eAAe,CAAC;IACzE,IAAI,KAAK,CAAC,aAAa,IAAI,iBAAiB;QAAE,OAAO,mBAAmB,CAAC;IACzE,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,UAAU,CAAC;IACrC,IAAI,KAAK,CAAC,yBAAyB,GAAG,KAAK,CAAC,WAAW;QAAE,OAAO,UAAU,CAAC;IAC3E,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,sBAAsB,CACpC,kBAA2B,EAC3B,aAAsB;IAEtB,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,yBAAyB,CACvC,KAAa,EACb,WAA0B,EAC1B,aAAsB,EACtB,MAAc;IAEd,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,KAAK,GAAG,WAAW,IAAI,MAAM,CAAC;AACvC,CAAC"}

package/dist/utils/draftId.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @description Draft-id allocator for the DM-mode live-streaming draft channel
+ * (P3). Telegram's `sendMessageDraft` animates updates that share the SAME
+ * `draft_id` as one in-progress draft; a NEW id starts a fresh draft. So one
+ * streamed response must keep ONE stable id across all its updates, and each new
+ * response (a fresh, non-continuation turn) must get a DISTINCT id so it animates
+ * separately from the previous turn.
+ *
+ * A pure module-scoped monotonic counter gives both: {@link nextDraftId} is
+ * called ONCE per response (at `startDraftTurn`), and the returned id is then
+ * stored on the per-thread draft state and reused for every update of that
+ * response. Two DM topics streaming at once get distinct ids because each pulls
+ * its own value off the shared counter.
+ *
+ * The id is folded into a NON-ZERO 31-bit positive int: Telegram requires a
+ * non-zero draft id, and a small positive int avoids any signedness surprises in
+ * the Bot API. The counter wraps at {@link DRAFT_ID_MODULO} without ever
+ * yielding 0.
+ */
+/**
+ * Wrap point for the draft-id counter. Kept well inside the 31-bit positive
+ * range (2_147_483_647) so the `+1` fold can never reach a 32-bit boundary.
+ */
+export declare const DRAFT_ID_MODULO = 2000000000;
+/**
+ * @description Allocate the next draft id. Monotonic per process, folded into a
+ * non-zero positive 31-bit int via `(counter % MODULO) + 1`, so the value is
+ * always in `[1, DRAFT_ID_MODULO]` and never 0 even at the wrap boundary.
+ *
+ * `prevId` is accepted for symmetry with the per-thread state (and to make a
+ * future "derive from previous" tweak local to this module) but is intentionally
+ * unused: uniqueness comes from the shared monotonic counter, not the caller's
+ * last id, so two interleaved per-thread turns can never collide.
+ */
+export declare function nextDraftId(prevId: number | null): number;
+//# sourceMappingURL=draftId.d.ts.map

package/dist/utils/draftId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draftId.d.ts","sourceRoot":"","sources":["../../src/utils/draftId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,aAAgB,CAAC;AAI7C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKzD"}