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

package/lib/session/runner.js

@@ -0,0 +1,260 @@
+/**
+ * One harness session per Telegram conversation.
+ *
+ * The lifecycle has three states and the transitions between them are the
+ * whole job: a conversation with no session yet, one whose session is loaded
+ * in this process, and one whose session exists only in the durable log
+ * because the harness has restarted since.
+ *
+ * The third case is why `resume` exists and why a failed resume is not fatal.
+ * A session log can be pruned, moved, or written by an incompatible version;
+ * when it can no longer be loaded, the user gets a fresh conversation and a
+ * note, which is far better than a bot that answers every message with the
+ * same load error.
+ *
+ * The agent host is injected rather than reached for directly, so this logic
+ * is exercised without a running harness.
+ */
+import { randomUUID } from 'node:crypto';
+import { SILENT_LOGGER } from '../harness/types.js';
+import { escapeHtml } from '../render/escape.js';
+/** The first words of a prompt, for labelling the conversation in a list. */
+function firstText(content) {
+    const said = content.find((part) => part.type === 'text');
+    return said?.type === 'text' && said.text.trim() !== '' ? said.text : undefined;
+}
+/** Whether a prompt carries an image, which changes a conversation for good. */
+function carriesImage(content) {
+    return content.some((part) => part.type === 'image');
+}
+export class SessionRunner {
+    options;
+    logger;
+    newSessionId;
+    /** Serialises work per conversation, so two fast messages cannot both create. */
+    chains = new Map();
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? SILENT_LOGGER;
+        this.newSessionId = options.newSessionId ?? (() => `tg-${randomUUID()}`);
+    }
+    /**
+     * Deliver a prompt, opening or resuming the conversation's session first.
+     *
+     * @param target - the conversation the prompt came from.
+     * @param text - what the user typed.
+     */
+    async prompt(target, content) {
+        if (content.length === 0)
+            return;
+        // Asked once and used three times: whether to read the picture elsewhere,
+        // whether to refuse it, and whether to move the conversation off its own
+        // model. A model that can look wants none of that done for it.
+        const sees = (await this.options.modelSees?.(target).catch(() => false)) === true;
+        // Resolved before the conversation's agent is touched at all, and outside
+        // the serialisation: reading an image takes a model call, and holding the
+        // conversation's queue for it would stall every later message behind it.
+        const resolved = sees ? [...content] : await this.resolve(target, content);
+        if (resolved.length === 0)
+            return;
+        await this.serialize(target, async () => {
+            const agent = await this.agentFor(target);
+            // Only reached when an image survived resolution. Set before the prompt:
+            // the harness reads the selection while assembling each step, so the
+            // override must be in place by the time the turn runs.
+            agent.useModel(this.routeFor(target, resolved, sees));
+            // Recorded BEFORE the turn runs, because from this point the session's
+            // log carries an image and every later turn must be routed for it.
+            if (carriesImage(resolved))
+                await this.options.bindings.markImages(target);
+            // Recorded with the prompt rather than at creation, because the opening
+            // words are what make the conversation recognisable in a list.
+            await this.options.history
+                ?.remember(target, {
+                sessionId: agent.sessionId,
+                startedAt: Date.now(),
+                cwd: this.options.cwdFor(target),
+                ...(firstText(resolved) === undefined ? {} : { label: firstText(resolved) }),
+            })
+                .catch(() => undefined);
+            agent.followup(resolved);
+        });
+    }
+    /**
+     * Turn images into text, where there is anything able to do it.
+     *
+     * A failure here is not the turn's failure: the picture simply goes through
+     * as it is, and the conversation moves to a model that can see it.
+     */
+    async resolve(target, content) {
+        const extractor = this.options.extractor;
+        if (!extractor?.available || !carriesImage(content))
+            return [...content];
+        try {
+            return await extractor.resolve(content, this.options.visionRoute?.(target));
+        }
+        catch (error) {
+            this.logger.warn('[dsh-telegram] could not read an image; sending it as it is', error);
+            return [...content];
+        }
+    }
+    /**
+     * Which model this conversation's next step must run on.
+     *
+     * Not a per-turn choice, though it looks like one. A provider checks the
+     * WHOLE request history for images, so once a session's log carries one,
+     * every later turn — however plain its own text — fails on a model that
+     * cannot see. The override therefore sticks to the conversation from the
+     * first image until it is reset with `/new`.
+     */
+    routeFor(target, content, sees) {
+        // The conversation's own choice always applies. Dropping it here is what
+        // made a model chosen with `/model` fall back to the deployment default —
+        // and since that choice is the whole reason the model could see, the check
+        // for "it can see" was undoing the thing it had just observed.
+        const chosen = this.options.chosenRoute?.(target);
+        if (sees)
+            return chosen;
+        const carried = this.options.bindings.forChat(target)?.hasImages === true;
+        // An image outranks the conversation's own choice: a model that cannot see
+        // fails the whole request, so this is not a preference to honour.
+        if (carriesImage(content) || carried)
+            return this.options.visionRoute?.(target) ?? chosen;
+        return chosen;
+    }
+    /**
+     * Point a conversation at a session it had before.
+     *
+     * The session is not loaded here: the next message resumes it through the
+     * ordinary path, which is also the path that handles a log that can no
+     * longer be read.
+     *
+     * @param target - the conversation.
+     * @param sessionId - a session this chat had earlier.
+     */
+    async adopt(target, sessionId) {
+        await this.serialize(target, async () => {
+            const binding = this.options.bindings.forChat(target);
+            if (binding?.sessionId === sessionId)
+                return;
+            // Released rather than disposed: the conversation being left is one the
+            // user may well come back to, and disposing would end it.
+            await this.options.bindings.bind(target, sessionId);
+        });
+    }
+    /**
+     * Forget the conversation's session so the next prompt opens a new one.
+     *
+     * @param target - the conversation to reset.
+     */
+    async reset(target) {
+        await this.serialize(target, async () => {
+            const binding = this.options.bindings.forChat(target);
+            if (!binding)
+                return;
+            const live = this.options.host.live(binding.sessionId);
+            if (live)
+                await live.dispose().catch((error) => {
+                    this.logger.warn('[dsh-telegram] could not dispose the previous agent', error);
+                });
+            await this.options.bindings.unbind(target);
+        });
+    }
+    /**
+     * Cancel whatever the conversation's agent is doing.
+     *
+     * @returns whether there was a loaded agent to cancel.
+     */
+    async stop(target) {
+        const binding = this.options.bindings.forChat(target);
+        if (!binding)
+            return false;
+        const live = this.options.host.live(binding.sessionId);
+        if (!live)
+            return false;
+        live.cancel('stopped from Telegram');
+        return true;
+    }
+    /**
+     * Describe the conversation as rows, for the caller to render.
+     *
+     * Rows rather than finished markup, because the caller adds its own — the
+     * model, the effort, what the agent may do — and stitching those onto a
+     * rendered string would mean parsing it back apart.
+     */
+    async status(target) {
+        const directory = this.options.cwdFor(target);
+        const binding = this.options.bindings.forChat(target);
+        // Worth naming the directory even with no conversation: it is what the
+        // next message opens in, and `/cd` before the first message is reasonable.
+        if (!binding) {
+            return [
+                { label: 'Session', value: 'none yet — send a message to start one' },
+                { label: 'Directory', value: directory },
+            ];
+        }
+        const live = this.options.host.live(binding.sessionId) !== undefined;
+        return [
+            { label: 'Session', value: binding.sessionId },
+            { label: 'Directory', value: directory },
+            { label: 'State', value: live ? 'loaded' : 'idle, resumes on your next message' },
+            {
+                label: 'Since',
+                value: new Date(binding.createdAt).toISOString().replace('T', ' ').slice(0, 16),
+            },
+        ];
+    }
+    /**
+     * The agent for a conversation: loaded, resumed, or freshly created.
+     *
+     * A binding whose session cannot be resumed is replaced rather than
+     * reported: the user's next message should work.
+     */
+    async agentFor(target) {
+        const binding = this.options.bindings.forChat(target);
+        if (binding) {
+            const live = this.options.host.live(binding.sessionId);
+            if (live)
+                return live;
+            const resumed = await this.options.host.resume(binding.sessionId).catch((error) => {
+                this.logger.warn(`[dsh-telegram] could not resume '${binding.sessionId}'`, error);
+                return undefined;
+            });
+            if (resumed) {
+                this.options.permission?.apply(target, resumed.sessionId);
+                return resumed;
+            }
+            this.logger.warn(`[dsh-telegram] session '${binding.sessionId}' is gone; starting a fresh conversation`);
+            await this.options.bindings.unbind(target);
+        }
+        const sessionId = this.newSessionId();
+        const cwd = this.options.cwdFor(target);
+        const agent = await this.options.host.create(sessionId, cwd);
+        // After creation, because the harness pins an initial permission before
+        // publishing the session; switching afterwards is the supported path.
+        this.options.permission?.apply(target, sessionId);
+        await this.options.bindings.bind(target, sessionId);
+        await this.options.history
+            ?.remember(target, { sessionId, startedAt: Date.now(), cwd })
+            .catch((error) => {
+            // Losing the entry costs a way back to this conversation, not the
+            // conversation itself.
+            this.logger.warn('[dsh-telegram] could not record the conversation', error);
+        });
+        return agent;
+    }
+    /**
+     * Run one conversation's work after its previous work.
+     *
+     * Two messages arriving in the same poll batch would otherwise both see no
+     * binding and both create a session, orphaning the first.
+     */
+    serialize(target, task) {
+        const key = target.threadId === undefined ? target.chatId : `${target.chatId}#${target.threadId}`;
+        const previous = this.chains.get(key) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        this.chains.set(key, next.then(() => undefined, () => undefined));
+        return next;
+    }
+}
+//# sourceMappingURL=runner.js.map

package/lib/session/runner.js.map

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

package/lib/session/workspaces.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Working out which directory a `/cd` argument names.
+ *
+ * The store itself is {@link ChatPreferences}: a chat's directory and a chat's
+ * model are the same shape — one durable string per conversation that has to
+ * outlive both `/new` and a restart — so they share one implementation.
+ *
+ * A session's cwd is fixed when the session opens; the sandbox derives its
+ * writable root from it and the harness calls that root immutable. Changing
+ * directory therefore starts a new conversation, which is why the choice
+ * cannot live on the session binding that `/new` discards.
+ */
+/**
+ * Work out which directory a `/cd` argument names.
+ *
+ * Pure, so every spelling a person might type is pinned by a test rather than
+ * discovered in a chat. Nothing here touches the filesystem — whether the
+ * result exists is the caller's question, and a separate one.
+ *
+ * @param input - what the user typed after `/cd`.
+ * @param current - the conversation's directory now, for relative paths.
+ * @param home - the user's home directory, for `~`.
+ * @returns an absolute, normalized path, or undefined for empty input.
+ */
+export declare function resolveDirectory(input: string, current: string, home: string): string | undefined;
+/** Whether a stored directory is still usable as one. */
+export declare function isUsableDirectory(value: string): boolean;
+//# sourceMappingURL=workspaces.d.ts.map

package/lib/session/workspaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/session/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAcpB;AASD,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIxD"}

package/lib/session/workspaces.js

@@ -0,0 +1,53 @@
+/**
+ * Working out which directory a `/cd` argument names.
+ *
+ * The store itself is {@link ChatPreferences}: a chat's directory and a chat's
+ * model are the same shape — one durable string per conversation that has to
+ * outlive both `/new` and a restart — so they share one implementation.
+ *
+ * A session's cwd is fixed when the session opens; the sandbox derives its
+ * writable root from it and the harness calls that root immutable. Changing
+ * directory therefore starts a new conversation, which is why the choice
+ * cannot live on the session binding that `/new` discards.
+ */
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * Work out which directory a `/cd` argument names.
+ *
+ * Pure, so every spelling a person might type is pinned by a test rather than
+ * discovered in a chat. Nothing here touches the filesystem — whether the
+ * result exists is the caller's question, and a separate one.
+ *
+ * @param input - what the user typed after `/cd`.
+ * @param current - the conversation's directory now, for relative paths.
+ * @param home - the user's home directory, for `~`.
+ * @returns an absolute, normalized path, or undefined for empty input.
+ */
+export function resolveDirectory(input, current, home) {
+    // Paths get pasted from a terminal, and a shell would have eaten the quotes.
+    const trimmed = unquote(input.trim());
+    if (trimmed === '')
+        return undefined;
+    if (trimmed === '~')
+        return resolve(home);
+    if (trimmed.startsWith('~/'))
+        return resolve(home, trimmed.slice(2));
+    // A bare `~user` is deliberately NOT expanded: resolving another account's
+    // home needs the password database, and guessing it wrong would silently
+    // open a directory the user did not name.
+    if (isAbsolute(trimmed))
+        return resolve(trimmed);
+    return resolve(current, trimmed);
+}
+/** Strip one matching pair of surrounding quotes. */
+function unquote(text) {
+    const quoted = (text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"));
+    return quoted && text.length >= 2 ? text.slice(1, -1) : text;
+}
+/** Whether a stored directory is still usable as one. */
+export function isUsableDirectory(value) {
+    // A relative path would resolve against whatever the process happens to be
+    // running in, which is not the directory the user chose.
+    return isAbsolute(value);
+}
+//# sourceMappingURL=workspaces.js.map

package/lib/session/workspaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/session/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAa,EACb,OAAe,EACf,IAAY;IAEZ,6EAA6E;IAC7E,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;IACrC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IAEpC,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpE,2EAA2E;IAC3E,yEAAyE;IACzE,0CAA0C;IAC1C,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhD,OAAO,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAClC,CAAC;AAED,qDAAqD;AACrD,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,MAAM,GACV,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;IAC9F,OAAO,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9D,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,2EAA2E;IAC3E,yDAAyD;IACzD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC"}

package/lib/telegram/addressing.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whether a message in a group was meant for this bot.
+ *
+ * In a private chat the question does not arise: every message is for the bot,
+ * because there is nobody else there. A group is the opposite — people talk to
+ * each other all day, and a bot that answers every line is one nobody keeps in
+ * the room. Telegram's own convention is the one users already expect: address
+ * it by @handle, or reply to something it said.
+ *
+ * This is separate from access. Access asks whether a person MAY drive the
+ * agent and is checked first; this asks whether they were talking to it at all.
+ * Conflating them would either let a stranger's @mention through or make the
+ * allowlist decide conversational etiquette.
+ */
+import type { TelegramMessage } from './types.js';
+/** Whether a chat is one where other people are talking too. */
+export declare function isGroupChat(message: TelegramMessage): boolean;
+/**
+ * Whether this message addresses the bot.
+ *
+ * @param message - the incoming message.
+ * @param botUsername - this bot's @handle, without the `@`.
+ * @param botId - this bot's user id, for recognising a reply to itself.
+ * @returns true in a private chat, and in a group only when addressed.
+ */
+export declare function addressesBot(message: TelegramMessage, botUsername: string | undefined, botId: number | undefined): boolean;
+/**
+ * Remove the bot's own @mention from the text it was addressed with.
+ *
+ * The mention is addressing, not content. Left in, every prompt in a group
+ * would open with the bot's own name, which reads to the model as part of the
+ * question.
+ *
+ * @param text - the message text.
+ * @param botUsername - this bot's @handle, without the `@`.
+ * @returns the text without a leading or trailing self-mention.
+ */
+export declare function stripMention(text: string, botUsername: string | undefined): string;
+//# sourceMappingURL=addressing.d.ts.map

package/lib/telegram/addressing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.d.ts","sourceRoot":"","sources":["../../src/telegram/addressing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAG7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAgCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKlF"}

package/lib/telegram/addressing.js

@@ -0,0 +1,81 @@
+/**
+ * Whether a message in a group was meant for this bot.
+ *
+ * In a private chat the question does not arise: every message is for the bot,
+ * because there is nobody else there. A group is the opposite — people talk to
+ * each other all day, and a bot that answers every line is one nobody keeps in
+ * the room. Telegram's own convention is the one users already expect: address
+ * it by @handle, or reply to something it said.
+ *
+ * This is separate from access. Access asks whether a person MAY drive the
+ * agent and is checked first; this asks whether they were talking to it at all.
+ * Conflating them would either let a stranger's @mention through or make the
+ * allowlist decide conversational etiquette.
+ */
+/** Whether a chat is one where other people are talking too. */
+export function isGroupChat(message) {
+    const type = message.chat.type;
+    return type === 'group' || type === 'supergroup';
+}
+/**
+ * Whether this message addresses the bot.
+ *
+ * @param message - the incoming message.
+ * @param botUsername - this bot's @handle, without the `@`.
+ * @param botId - this bot's user id, for recognising a reply to itself.
+ * @returns true in a private chat, and in a group only when addressed.
+ */
+export function addressesBot(message, botUsername, botId) {
+    if (!isGroupChat(message))
+        return true;
+    // A reply to something the bot said continues that exchange. This is the
+    // path that makes a group usable: nobody wants to re-@mention a bot to say
+    // "yes, do it".
+    const repliedTo = message.reply_to_message?.from;
+    if (repliedTo !== undefined && botId !== undefined && repliedTo.id === botId)
+        return true;
+    const text = message.text ?? message.caption;
+    if (text === undefined)
+        return false;
+    const entities = message.entities ?? message.caption_entities ?? [];
+    for (const entity of entities) {
+        // `text_mention` names a user without a @handle — the reliable signal when
+        // a bot has none, and the only one for an account that hides its username.
+        if (entity.type === 'text_mention') {
+            if (botId !== undefined && entity.user?.id === botId)
+                return true;
+            continue;
+        }
+        if (entity.type !== 'mention' || botUsername === undefined)
+            continue;
+        // Compared against the entity's own span rather than searched for in the
+        // text: `@mybot_staging` contains `@mybot`, and a substring match would
+        // hand another bot's mentions to this one.
+        const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+        if (mentioned.toLowerCase() === `@${botUsername.toLowerCase()}`)
+            return true;
+    }
+    return false;
+}
+/**
+ * Remove the bot's own @mention from the text it was addressed with.
+ *
+ * The mention is addressing, not content. Left in, every prompt in a group
+ * would open with the bot's own name, which reads to the model as part of the
+ * question.
+ *
+ * @param text - the message text.
+ * @param botUsername - this bot's @handle, without the `@`.
+ * @returns the text without a leading or trailing self-mention.
+ */
+export function stripMention(text, botUsername) {
+    if (botUsername === undefined)
+        return text;
+    const mention = new RegExp(`@${escapeRegExp(botUsername)}\\b`, 'gi');
+    return text.replace(mention, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Quote a username for use inside a pattern. */
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=addressing.js.map

package/lib/telegram/addressing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing.js","sourceRoot":"","sources":["../../src/telegram/addressing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,OAAwB;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA;IAC9B,OAAO,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,YAAY,CAAA;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAwB,EACxB,WAA+B,EAC/B,KAAyB;IAEzB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAA;IAEtC,yEAAyE;IACzE,2EAA2E;IAC3E,gBAAgB;IAChB,MAAM,SAAS,GAAG,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAA;IAChD,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,EAAE,KAAK,KAAK;QAAE,OAAO,IAAI,CAAA;IAEzF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAA;IAC5C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IAEpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAA;IAEnE,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,2EAA2E;QAC3E,2EAA2E;QAC3E,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,KAAK;gBAAE,OAAO,IAAI,CAAA;YACjE,SAAQ;QACV,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS;YAAE,SAAQ;QAEpE,yEAAyE;QACzE,wEAAwE;QACxE,2CAA2C;QAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;QAC1E,IAAI,SAAS,CAAC,WAAW,EAAE,KAAK,IAAI,WAAW,CAAC,WAAW,EAAE,EAAE;YAAE,OAAO,IAAI,CAAA;IAC9E,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,WAA+B;IACxE,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAE1C,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,IAAI,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACpE,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;AAC/D,CAAC;AAED,iDAAiD;AACjD,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;AACpD,CAAC"}

package/lib/telegram/albums.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gathering an album back into one message.
+ *
+ * Telegram has no "several photos in one message". Sending three screenshots
+ * produces three separate updates, tied together only by a shared
+ * `media_group_id`, with the caption on exactly one of them. Handled one at a
+ * time that becomes three turns: the first carries the question, and the other
+ * two arrive as bare images the agent has no reason for.
+ *
+ * So a message belonging to an album is held briefly rather than answered, and
+ * the group is delivered once it stops growing. The wait is the cost: it is
+ * paid only by albums, and only once per album, which is a better trade than
+ * answering the same question three times.
+ */
+import type { TelegramMessage } from './types.js';
+/** Construction options. */
+export interface AlbumBufferOptions {
+    /** Called once per album, with its parts in the order Telegram numbered them. */
+    readonly deliver: (messages: TelegramMessage[]) => void;
+    readonly windowMs?: number;
+    readonly maxParts?: number;
+}
+export declare class AlbumBuffer {
+    private readonly options;
+    private readonly gathering;
+    constructor(options: AlbumBufferOptions);
+    /**
+     * Take a message if it belongs to an album.
+     *
+     * @param message - the incoming message.
+     * @returns whether it was taken; the caller should stop handling it if so,
+     *   because the whole album is delivered later instead.
+     */
+    offer(message: TelegramMessage): boolean;
+    /** Deliver every album still gathering — the plugin is unloading. */
+    flush(): void;
+    /** Drop every album still gathering, delivering none. */
+    dispose(): void;
+    /** Start gathering one album. */
+    private hold;
+    /** Arm the "it stopped growing" timer for one album. */
+    private arm;
+}
+/** The caption an album carries, which exactly one of its parts holds. */
+export declare function captionOf(messages: readonly TelegramMessage[]): string | undefined;
+//# sourceMappingURL=albums.d.ts.map

package/lib/telegram/albums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"albums.d.ts","sourceRoot":"","sources":["../../src/telegram/albums.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAQjD,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,IAAI,CAAA;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAQD,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;gBAE5B,OAAO,EAAE,kBAAkB;IAExD;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO;IA0BxC,qEAAqE;IACrE,KAAK,IAAI,IAAI;IAQb,yDAAyD;IACzD,OAAO,IAAI,IAAI;IAKf,iCAAiC;IACjC,OAAO,CAAC,IAAI;IAIZ,wDAAwD;IACxD,OAAO,CAAC,GAAG;CAaZ;AAYD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,GAAG,SAAS,CAMlF"}

package/lib/telegram/albums.js

@@ -0,0 +1,104 @@
+/**
+ * Gathering an album back into one message.
+ *
+ * Telegram has no "several photos in one message". Sending three screenshots
+ * produces three separate updates, tied together only by a shared
+ * `media_group_id`, with the caption on exactly one of them. Handled one at a
+ * time that becomes three turns: the first carries the question, and the other
+ * two arrive as bare images the agent has no reason for.
+ *
+ * So a message belonging to an album is held briefly rather than answered, and
+ * the group is delivered once it stops growing. The wait is the cost: it is
+ * paid only by albums, and only once per album, which is a better trade than
+ * answering the same question three times.
+ */
+/** How long to wait after the last part before deciding an album is complete. */
+const WINDOW_MS = 1200;
+/** Telegram's own album limit; anything beyond it is a different album. */
+const MAX_PARTS = 10;
+export class AlbumBuffer {
+    options;
+    gathering = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Take a message if it belongs to an album.
+     *
+     * @param message - the incoming message.
+     * @returns whether it was taken; the caller should stop handling it if so,
+     *   because the whole album is delivered later instead.
+     */
+    offer(message) {
+        const id = message.media_group_id;
+        if (id === undefined)
+            return false;
+        const existing = this.gathering.get(id);
+        if (existing) {
+            clearTimeout(existing.timer);
+            // Beyond Telegram's own limit this is no longer one album, so the parts
+            // held so far go out rather than growing without bound.
+            if (existing.messages.length >= (this.options.maxParts ?? MAX_PARTS)) {
+                this.gathering.delete(id);
+                this.options.deliver(sorted(existing.messages));
+                this.hold(id, [message]);
+                return true;
+            }
+            existing.messages.push(message);
+            existing.timer = this.arm(id);
+            return true;
+        }
+        this.hold(id, [message]);
+        return true;
+    }
+    /** Deliver every album still gathering — the plugin is unloading. */
+    flush() {
+        for (const [id, entry] of [...this.gathering]) {
+            clearTimeout(entry.timer);
+            this.gathering.delete(id);
+            this.options.deliver(sorted(entry.messages));
+        }
+    }
+    /** Drop every album still gathering, delivering none. */
+    dispose() {
+        for (const entry of this.gathering.values())
+            clearTimeout(entry.timer);
+        this.gathering.clear();
+    }
+    /** Start gathering one album. */
+    hold(id, messages) {
+        this.gathering.set(id, { messages, timer: this.arm(id) });
+    }
+    /** Arm the "it stopped growing" timer for one album. */
+    arm(id) {
+        const timer = setTimeout(() => {
+            const entry = this.gathering.get(id);
+            if (!entry)
+                return;
+            this.gathering.delete(id);
+            this.options.deliver(sorted(entry.messages));
+        }, this.options.windowMs ?? WINDOW_MS);
+        // A pending album is never a reason to keep the process alive.
+        timer.unref?.();
+        return timer;
+    }
+}
+/**
+ * The album in the order it was sent.
+ *
+ * Telegram numbers the parts even when it delivers them out of order, and the
+ * order is what decides which image the caption belongs to.
+ */
+function sorted(messages) {
+    return [...messages].sort((a, b) => a.message_id - b.message_id);
+}
+/** The caption an album carries, which exactly one of its parts holds. */
+export function captionOf(messages) {
+    for (const message of messages) {
+        const said = (message.caption ?? message.text)?.trim();
+        if (said !== undefined && said !== '')
+            return said;
+    }
+    return undefined;
+}
+//# sourceMappingURL=albums.js.map