@sympoies/dsh-telegram 0.0.0-bootstrap.0 → 0.6.0

package/lib/reply/rich-stream.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Streaming one agent turn as a rich message.
+ *
+ * The agent writes markdown, and since Bot API 10.1 Telegram parses markdown
+ * itself — tables, headings, ordered and task lists, fenced code, footnotes,
+ * math — so the reply is forwarded almost verbatim rather than approximated
+ * in HTML. The message cap rises from 4096 to 32768 characters with it.
+ *
+ * Telegram offers two ways to show a reply as it is written, and they are not
+ * interchangeable:
+ *
+ * - **Private chats** get `sendRichMessageDraft`: an ephemeral preview that
+ *   animates between frames carrying the same draft id. It expires after 30
+ *   seconds and is never persisted, so the turn must end with a real send.
+ * - **Groups have no draft API at all.** There the finished reply is simply
+ *   sent when it is ready.
+ *
+ * Nothing is sent until there is something worth showing — the first text, or
+ * the name of a tool the agent reached for. An ellipsis posted the moment a
+ * turn opens says only that a message arrived, which the user already knows,
+ * and in a group it is a permanent message saying it. Telegram's own typing
+ * indicator covers that stretch far better, and {@link onVisible} is what
+ * hands it back once this has something real to show.
+ *
+ * The draft's expiry is the subtle part: a turn that spends two minutes in a
+ * tool call emits no text, so without a heartbeat the preview would vanish and
+ * the user would think the bot had died.
+ */
+import type { ChatTarget } from '../interact/surface.js';
+import type { Logger } from '../harness/types.js';
+/** Telegram's rich-message character cap. */
+export declare const RICH_MESSAGE_LIMIT = 32768;
+/** Default gap between frames; Telegram throttles rapid updates to one chat. */
+export declare const DEFAULT_THROTTLE_MS = 1200;
+/**
+ * Whether a conversation can show a reply as it is written.
+ *
+ * Two independent reasons it cannot, and conflating them is how the operator's
+ * switch came to do nothing: streaming may be turned off, or the conversation
+ * may be a group, which has no draft API at all. Telegram gives groups and
+ * channels negative ids, which is the only signal available before a message
+ * arrives.
+ *
+ * @param chatId - the conversation's Telegram id.
+ * @param streamingEnabled - the operator's setting.
+ */
+export declare function canStreamTo(chatId: string, streamingEnabled: boolean): boolean;
+/** The Bot API surface a reply needs. */
+export interface RichChat {
+    sendRichMessage(options: {
+        chatId: string;
+        markdown: string;
+        threadId?: number;
+    }): Promise<{
+        messageId: number;
+    }>;
+    sendRichMessageDraft(options: {
+        chatId: string;
+        draftId: number;
+        markdown: string;
+        threadId?: number;
+    }): Promise<void>;
+}
+/** Construction options. */
+export interface RichReplyOptions {
+    readonly chat: RichChat;
+    readonly target: ChatTarget;
+    /** Private chats stream through drafts; groups have no draft API. */
+    readonly canDraft: boolean;
+    /** Stable for the turn: Telegram animates frames sharing a draft id. */
+    readonly draftId: number;
+    readonly throttleMs?: number;
+    readonly limit?: number;
+    /**
+     * Called once, when this turn first shows something in the chat.
+     *
+     * Whoever was standing in for it until then — the typing indicator — can
+     * stop at that point.
+     */
+    readonly onVisible?: () => void;
+    readonly logger?: Logger;
+    /** Injected so a test never waits on a real timer. */
+    readonly heartbeatMs?: number;
+}
+export declare class RichReplyStream {
+    private readonly options;
+    private readonly chat;
+    private readonly target;
+    private readonly throttleMs;
+    private readonly limit;
+    private readonly heartbeatMs;
+    private readonly logger;
+    /** Raw markdown received so far. */
+    private buffer;
+    /** What the last frame showed, so an unchanged frame is skipped. */
+    private shown;
+    /**
+     * What the agent is doing, shown above the text while it works.
+     *
+     * Draft-only: Telegram accepts the thinking block in a draft and nowhere
+     * else, and the finished reply should carry the answer, not the scaffolding
+     * that produced it.
+     */
+    private activity;
+    private started;
+    private finished;
+    private timer;
+    /** Whether anything has appeared in the chat for this turn yet. */
+    private visible;
+    private heartbeat;
+    private lastFrame;
+    private queue;
+    constructor(options: RichReplyOptions);
+    /**
+     * Open the turn.
+     *
+     * Deliberately sends nothing. Until the agent writes a word or names a tool
+     * there is nothing to show that the typing indicator is not already showing
+     * better, and a message posted here would be an ellipsis the user has to
+     * look at for the rest of the turn.
+     */
+    start(): Promise<void>;
+    /**
+     * Say what the agent is doing, above whatever text has arrived.
+     *
+     * @param activity - an escaped one-line description, or undefined to clear.
+     */
+    showActivity(activity: string | undefined): Promise<void>;
+    /**
+     * Add streamed markdown.
+     *
+     * @param delta - the new fragment.
+     */
+    append(delta: string): Promise<void>;
+    /**
+     * Close the turn, persisting the reply.
+     *
+     * @param finalText - authoritative full text when the caller has one.
+     */
+    finish(finalText?: string): Promise<void>;
+    /**
+     * Close the turn on an error, keeping whatever text had already streamed.
+     *
+     * @param error - the failure to show under the partial answer.
+     */
+    fail(error: unknown): Promise<void>;
+    /** Write the finished reply where it will survive the draft's expiry. */
+    private persist;
+    /** Post one finished chunk. */
+    private send;
+    /** Show one draft frame, remembering it so the heartbeat can repeat it. */
+    private draft;
+    /** Report, once, that this turn now shows something in the chat. */
+    private becameVisible;
+    /** Flush now, or arm a timer for the rest of the throttle window. */
+    private schedule;
+    /** Send the current buffer as a draft frame, if anything moved. */
+    private frame;
+    /**
+     * Keep the preview alive through a silent stretch.
+     *
+     * A draft lapses 30 seconds after its last frame, and a turn can spend far
+     * longer inside one tool call without emitting a character.
+     */
+    private armHeartbeat;
+    /** Re-send the frame already showing, to hold it past the draft's expiry. */
+    private repeat;
+    /** Run one send after the previous one, containing its failures. */
+    private enqueue;
+    /** Disarm the throttle and the heartbeat. */
+    private stopTimers;
+}
+//# sourceMappingURL=rich-stream.d.ts.map

package/lib/reply/rich-stream.d.ts.map

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

package/lib/reply/rich-stream.js

@@ -0,0 +1,286 @@
+/**
+ * Streaming one agent turn as a rich message.
+ *
+ * The agent writes markdown, and since Bot API 10.1 Telegram parses markdown
+ * itself — tables, headings, ordered and task lists, fenced code, footnotes,
+ * math — so the reply is forwarded almost verbatim rather than approximated
+ * in HTML. The message cap rises from 4096 to 32768 characters with it.
+ *
+ * Telegram offers two ways to show a reply as it is written, and they are not
+ * interchangeable:
+ *
+ * - **Private chats** get `sendRichMessageDraft`: an ephemeral preview that
+ *   animates between frames carrying the same draft id. It expires after 30
+ *   seconds and is never persisted, so the turn must end with a real send.
+ * - **Groups have no draft API at all.** There the finished reply is simply
+ *   sent when it is ready.
+ *
+ * Nothing is sent until there is something worth showing — the first text, or
+ * the name of a tool the agent reached for. An ellipsis posted the moment a
+ * turn opens says only that a message arrived, which the user already knows,
+ * and in a group it is a permanent message saying it. Telegram's own typing
+ * indicator covers that stretch far better, and {@link onVisible} is what
+ * hands it back once this has something real to show.
+ *
+ * The draft's expiry is the subtle part: a turn that spends two minutes in a
+ * tool call emits no text, so without a heartbeat the preview would vanish and
+ * the user would think the bot had died.
+ */
+import { SILENT_LOGGER } from '../harness/types.js';
+import { splitMarkdown } from './split-markdown.js';
+import { thinkingBlock } from './activity.js';
+/** Telegram's rich-message character cap. */
+export const RICH_MESSAGE_LIMIT = 32_768;
+/** Default gap between frames; Telegram throttles rapid updates to one chat. */
+export const DEFAULT_THROTTLE_MS = 1200;
+/**
+ * How often to re-send an unchanged draft.
+ *
+ * Comfortably inside the 30-second expiry, so a long silent tool call cannot
+ * let the preview lapse.
+ */
+const HEARTBEAT_MS = 20_000;
+/**
+ * Whether a conversation can show a reply as it is written.
+ *
+ * Two independent reasons it cannot, and conflating them is how the operator's
+ * switch came to do nothing: streaming may be turned off, or the conversation
+ * may be a group, which has no draft API at all. Telegram gives groups and
+ * channels negative ids, which is the only signal available before a message
+ * arrives.
+ *
+ * @param chatId - the conversation's Telegram id.
+ * @param streamingEnabled - the operator's setting.
+ */
+export function canStreamTo(chatId, streamingEnabled) {
+    return streamingEnabled && !chatId.startsWith('-');
+}
+export class RichReplyStream {
+    options;
+    chat;
+    target;
+    throttleMs;
+    limit;
+    heartbeatMs;
+    logger;
+    /** Raw markdown received so far. */
+    buffer = '';
+    /** What the last frame showed, so an unchanged frame is skipped. */
+    shown = '';
+    /**
+     * What the agent is doing, shown above the text while it works.
+     *
+     * Draft-only: Telegram accepts the thinking block in a draft and nowhere
+     * else, and the finished reply should carry the answer, not the scaffolding
+     * that produced it.
+     */
+    activity;
+    started = false;
+    finished = false;
+    timer;
+    /** Whether anything has appeared in the chat for this turn yet. */
+    visible = false;
+    heartbeat;
+    lastFrame = 0;
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.chat = options.chat;
+        this.target = options.target;
+        this.throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+        this.limit = options.limit ?? RICH_MESSAGE_LIMIT;
+        this.heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS;
+        this.logger = options.logger ?? SILENT_LOGGER;
+    }
+    /**
+     * Open the turn.
+     *
+     * Deliberately sends nothing. Until the agent writes a word or names a tool
+     * there is nothing to show that the typing indicator is not already showing
+     * better, and a message posted here would be an ellipsis the user has to
+     * look at for the rest of the turn.
+     */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+    }
+    /**
+     * Say what the agent is doing, above whatever text has arrived.
+     *
+     * @param activity - an escaped one-line description, or undefined to clear.
+     */
+    async showActivity(activity) {
+        if (this.finished || !this.options.canDraft)
+            return;
+        if (this.activity === activity)
+            return;
+        this.activity = activity;
+        if (!this.started)
+            return await this.start();
+        await this.schedule();
+    }
+    /**
+     * Add streamed markdown.
+     *
+     * @param delta - the new fragment.
+     */
+    async append(delta) {
+        if (this.finished || delta === '')
+            return;
+        if (!this.started)
+            await this.start();
+        this.buffer += delta;
+        // Only a draft can show progress; a group waits for the finished reply.
+        if (this.options.canDraft)
+            await this.schedule();
+    }
+    /**
+     * Close the turn, persisting the reply.
+     *
+     * @param finalText - authoritative full text when the caller has one.
+     */
+    async finish(finalText) {
+        if (this.finished)
+            return;
+        if (finalText !== undefined)
+            this.buffer = finalText;
+        if (!this.started && this.buffer === '')
+            return;
+        if (!this.started)
+            await this.start();
+        this.finished = true;
+        this.stopTimers();
+        await this.enqueue(() => this.persist(this.buffer));
+    }
+    /**
+     * Close the turn on an error, keeping whatever text had already streamed.
+     *
+     * @param error - the failure to show under the partial answer.
+     */
+    async fail(error) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.stopTimers();
+        const reason = error instanceof Error ? error.message : String(error);
+        const body = this.buffer === '' ? '' : `${this.buffer}\n\n`;
+        await this.enqueue(() => this.persist(`${body}⚠️ ${reason}`));
+    }
+    /** Write the finished reply where it will survive the draft's expiry. */
+    async persist(markdown) {
+        const chunks = splitMarkdown(markdown, this.limit);
+        if (chunks.length === 0)
+            return;
+        for (const chunk of chunks)
+            await this.send(chunk);
+    }
+    /** Post one finished chunk. */
+    async send(markdown) {
+        await this.chat.sendRichMessage({
+            chatId: this.target.chatId,
+            markdown,
+            ...(this.target.threadId !== undefined ? { threadId: this.target.threadId } : {}),
+        });
+        this.becameVisible();
+    }
+    /** Show one draft frame, remembering it so the heartbeat can repeat it. */
+    async draft(markdown) {
+        const thinking = thinkingBlock(this.activity);
+        const composed = thinking === '' ? markdown : `${thinking}\n\n${markdown}`;
+        // A draft cannot exceed the message cap either; the tail is what the user
+        // is watching, and the whole text lands when the turn is persisted.
+        const frame = composed.length > this.limit ? composed.slice(-this.limit) : composed;
+        await this.chat.sendRichMessageDraft({
+            chatId: this.target.chatId,
+            draftId: this.options.draftId,
+            markdown: frame,
+            ...(this.target.threadId !== undefined ? { threadId: this.target.threadId } : {}),
+        });
+        this.shown = frame;
+        // Armed here rather than at start, because until the first frame there is
+        // no preview to keep alive.
+        this.armHeartbeat();
+        this.becameVisible();
+    }
+    /** Report, once, that this turn now shows something in the chat. */
+    becameVisible() {
+        if (this.visible)
+            return;
+        this.visible = true;
+        this.options.onVisible?.();
+    }
+    /** Flush now, or arm a timer for the rest of the throttle window. */
+    async schedule() {
+        if (this.throttleMs === 0)
+            return await this.enqueue(() => this.frame());
+        const due = this.lastFrame + this.throttleMs - Date.now();
+        if (due <= 0) {
+            this.lastFrame = Date.now();
+            return await this.enqueue(() => this.frame());
+        }
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.lastFrame = Date.now();
+            void this.enqueue(() => this.frame());
+        }, due);
+    }
+    /** Send the current buffer as a draft frame, if anything moved. */
+    async frame() {
+        if (this.finished)
+            return;
+        // The activity line alone is worth a frame: during a long tool call it is
+        // the only thing that changes, and it is the whole point of showing it.
+        // With neither there is nothing to draw, and Telegram refuses an empty
+        // draft anyway — so the previous frame stays, which is what the reader
+        // was looking at.
+        if (this.buffer === '' && this.activity === undefined)
+            return;
+        await this.draft(this.buffer);
+    }
+    /**
+     * Keep the preview alive through a silent stretch.
+     *
+     * A draft lapses 30 seconds after its last frame, and a turn can spend far
+     * longer inside one tool call without emitting a character.
+     */
+    armHeartbeat() {
+        if (this.heartbeat || this.heartbeatMs <= 0)
+            return;
+        this.heartbeat = setInterval(() => {
+            if (this.finished || this.shown === '')
+                return;
+            // Re-sends exactly what is on screen. Keeping a preview alive means
+            // repeating it, not replacing it with something that says less.
+            void this.enqueue(() => this.repeat());
+        }, this.heartbeatMs);
+    }
+    /** Re-send the frame already showing, to hold it past the draft's expiry. */
+    async repeat() {
+        await this.chat.sendRichMessageDraft({
+            chatId: this.target.chatId,
+            draftId: this.options.draftId,
+            markdown: this.shown,
+            ...(this.target.threadId !== undefined ? { threadId: this.target.threadId } : {}),
+        });
+    }
+    /** Run one send after the previous one, containing its failures. */
+    enqueue(task) {
+        this.queue = this.queue.then(task).catch((error) => {
+            this.logger.warn('[dsh-telegram] reply delivery failed', error);
+        });
+        return this.queue;
+    }
+    /** Disarm the throttle and the heartbeat. */
+    stopTimers() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+    }
+}
+//# sourceMappingURL=rich-stream.js.map

package/lib/reply/rich-stream.js.map

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

package/lib/reply/split-markdown.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Splitting a reply that outgrows one message.
+ *
+ * At 32768 characters this is rare, but a file listing or a long diff still
+ * reaches it. Telegram parses the markdown itself, so the split has to happen
+ * where the markdown stays coherent: cutting inside a fenced code block would
+ * leave the first chunk with an unterminated fence and the second beginning
+ * with a stray one, and Telegram would render both wrongly.
+ *
+ * So the split walks block boundaries — blank lines first, then line breaks —
+ * and closes and reopens a fence it had to cut through.
+ */
+/**
+ * Split markdown into chunks Telegram will accept.
+ *
+ * @param markdown - the reply as the agent wrote it.
+ * @param limit - maximum characters per message.
+ * @returns chunks in order; empty when there is no visible content.
+ */
+export declare function splitMarkdown(markdown: string, limit: number): string[];
+//# sourceMappingURL=split-markdown.d.ts.map

package/lib/reply/split-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-markdown.d.ts","sourceRoot":"","sources":["../../src/reply/split-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgCvE"}

package/lib/reply/split-markdown.js

@@ -0,0 +1,87 @@
+/**
+ * Splitting a reply that outgrows one message.
+ *
+ * At 32768 characters this is rare, but a file listing or a long diff still
+ * reaches it. Telegram parses the markdown itself, so the split has to happen
+ * where the markdown stays coherent: cutting inside a fenced code block would
+ * leave the first chunk with an unterminated fence and the second beginning
+ * with a stray one, and Telegram would render both wrongly.
+ *
+ * So the split walks block boundaries — blank lines first, then line breaks —
+ * and closes and reopens a fence it had to cut through.
+ */
+/** Opening or closing fence of a code block, capturing its language. */
+const FENCE = /^\s{0,3}(`{3,}|~{3,})\s*(\S*)/;
+/** How far back from the limit a cleaner boundary is still worth taking. */
+const BOUNDARY_SEARCH_RATIO = 0.5;
+/**
+ * Split markdown into chunks Telegram will accept.
+ *
+ * @param markdown - the reply as the agent wrote it.
+ * @param limit - maximum characters per message.
+ * @returns chunks in order; empty when there is no visible content.
+ */
+export function splitMarkdown(markdown, limit) {
+    const trimmed = markdown.trim();
+    if (trimmed === '')
+        return [];
+    if (trimmed.length <= limit)
+        return [trimmed];
+    const chunks = [];
+    let rest = trimmed;
+    /** The fence a previous chunk was cut inside, to reopen at the next start. */
+    let openFence;
+    while (rest.length > 0) {
+        const prefix = openFence ? `${openFence.marker}${openFence.language}\n` : '';
+        const budget = limit - prefix.length;
+        if (rest.length <= budget) {
+            chunks.push(prefix + rest);
+            break;
+        }
+        const cut = findCut(rest, budget);
+        const body = rest.slice(0, cut);
+        const carried = openFence;
+        openFence = fenceLeftOpen(body, openFence);
+        const suffix = openFence ? `\n${openFence.marker}` : '';
+        chunks.push(prefix + body.trimEnd() + suffix);
+        rest = rest.slice(cut).replace(/^\n+/, '');
+        if (carried && !openFence)
+            openFence = undefined;
+    }
+    return chunks;
+}
+/** The latest clean boundary within `budget`, or a hard cut when there is none. */
+function findCut(markdown, budget) {
+    const floor = Math.floor(budget * BOUNDARY_SEARCH_RATIO);
+    for (const boundary of ['\n\n', '\n']) {
+        const at = markdown.lastIndexOf(boundary, budget - boundary.length);
+        if (at >= floor)
+            return at + boundary.length;
+    }
+    return budget;
+}
+/**
+ * Whether a chunk ended inside a code fence, and which one.
+ *
+ * Fences toggle, so folding them in order tells us what is still open at the
+ * cut — the only construct where reopening matters, because Telegram treats
+ * the rest of the document as code until the fence closes.
+ */
+function fenceLeftOpen(body, carried) {
+    let open = carried;
+    for (const line of body.split('\n')) {
+        const match = FENCE.exec(line);
+        if (!match)
+            continue;
+        const marker = match[1];
+        if (open) {
+            // A closing fence is the same character, at least as long.
+            if (marker[0] === open.marker[0] && marker.length >= open.marker.length)
+                open = undefined;
+            continue;
+        }
+        open = { marker, language: match[2] ?? '' };
+    }
+    return open;
+}
+//# sourceMappingURL=split-markdown.js.map

package/lib/reply/split-markdown.js.map

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