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

package/lib/interact/questions.js

@@ -0,0 +1,255 @@
+/**
+ * Answering the agent's questions from Telegram.
+ *
+ * This is the half of the plugin that has no equivalent in the existing
+ * channel bridge. When the agent calls `ask_user_question`, the harness blocks
+ * the tool call on `ctx.userQuestions.ask()` and waits for the single
+ * registered UI provider to return an answer. Until now that provider was
+ * always the browser, so a conversation held entirely in Telegram would stall
+ * on the first question with no way to answer it.
+ *
+ * This provider renders each question as a message with an inline keyboard,
+ * parks the promise, and resolves it when a button is pressed — minutes later,
+ * in a different HTTP request, possibly on a different device.
+ *
+ * Two details are load-bearing:
+ *
+ * - **Delegation.** The harness allows exactly one provider. When the browser
+ *   already registered one, this provider takes over and forwards every
+ *   question that does not belong to a Telegram-bound session back to it, so
+ *   installing this plugin never takes the web UI's questions away.
+ * - **Multi-select re-parks.** A toggle is not an answer, so each press settles
+ *   its waiter and opens a fresh one for the redrawn keyboard. The token
+ *   changes every round, which also makes a stale button inert.
+ */
+import { escapeHtml } from '../render/escape.js';
+import { clamp, escapeWithin } from '../render/clamp.js';
+/** Prefix marking callback data as belonging to a question. */
+const KIND = 'q';
+/** Index reserved for the "answer in your own words" button. */
+const OTHER_INDEX = -1;
+/** Index reserved for the multi-select "Done" button. */
+const DONE_INDEX = -2;
+/** Telegram truncates long button labels awkwardly; do it deliberately instead. */
+const MAX_BUTTON_LABEL = 48;
+/**
+ * Budgets for the model-authored parts of a prompt. Together with the option
+ * cap below they keep the assembled message inside Telegram's 4096-character
+ * limit, so a verbose question can never become a question nobody is shown.
+ */
+const HEADER_BUDGET = 120;
+const QUESTION_BUDGET = 1200;
+const DESCRIPTION_BUDGET = 220;
+/** Descriptions rendered in the body; the rest are still selectable buttons. */
+const MAX_DESCRIBED_OPTIONS = 8;
+/** Thrown when the agent abandons a question before the user answers it. */
+export class QuestionCancelledError extends Error {
+    constructor() {
+        super('ask_user_question was cancelled before the user answered');
+        this.name = 'QuestionCancelledError';
+    }
+}
+/** Thrown when a question arrives for a session with nowhere to ask it. */
+export class NoChatError extends Error {
+    constructor(sessionId) {
+        super(`no telegram chat is bound to session '${sessionId}'`);
+        this.name = 'NoChatError';
+    }
+}
+export class TelegramQuestionProvider {
+    options;
+    /**
+     * Where non-Telegram questions go. Settable after construction because the
+     * incumbent provider is only knowable at the moment this one displaces it.
+     */
+    fallback;
+    constructor(options) {
+        this.options = options;
+        this.fallback = options.fallback;
+    }
+    /**
+     * Point delegation at the provider this one displaced.
+     *
+     * @param provider - the incumbent, which keeps answering its own sessions.
+     */
+    setFallback(provider) {
+        this.fallback = provider;
+    }
+    /**
+     * Ask the human, one question at a time.
+     *
+     * @param request - the questions, the owning agent, and the agent's signal.
+     * @returns the answers, in request order.
+     * @throws {NoChatError} when the session has no Telegram chat and no
+     *   provider to delegate to.
+     * @throws {QuestionCancelledError} when the agent gives up first.
+     */
+    async ask(request) {
+        const sessionId = request.agent?.session.id ?? request.agent?.id;
+        const target = sessionId === undefined ? undefined : this.options.targetOf(sessionId);
+        if (!target) {
+            if (this.fallback)
+                return this.fallback.ask(request);
+            throw new NoChatError(sessionId ?? '<unknown>');
+        }
+        const answers = [];
+        for (const question of request.questions) {
+            answers.push(await this.askOne(question, target, request.signal));
+        }
+        return { answers };
+    }
+    /**
+     * Route one button press.
+     *
+     * @param data - raw `callback_data` from the update.
+     * @returns whether the press belonged to an open question.
+     */
+    handleCallback(data) {
+        const press = decodeCallback(data);
+        if (!press)
+            return false;
+        return this.options.pending.settle(press.token, press);
+    }
+    /** Ask one question and hold the chat open until it is answered. */
+    async askOne(question, target, signal) {
+        if (question.detail !== undefined) {
+            // Agent-authored markdown — a plan, a diff — so Telegram renders it.
+            await this.options.surface.sendMarkdown(target, question.detail);
+        }
+        const options = question.options ?? [];
+        if (options.length === 0)
+            return this.askFreeText(question, target, signal);
+        let selected = [];
+        let messageId;
+        for (;;) {
+            const waiter = this.options.pending.open({
+                ...(signal ? { signal } : {}),
+                onCancel: () => void this.retire(target, messageId, question, 'Cancelled.'),
+            });
+            const html = renderPrompt(question, selected);
+            const keyboard = buildKeyboard(question, selected, waiter.token);
+            if (messageId === undefined)
+                messageId = await this.options.surface.send(target, html, keyboard);
+            else
+                await this.options.surface.edit(target, messageId, html, keyboard);
+            const press = (await waiter.promise);
+            if (!press)
+                throw new QuestionCancelledError();
+            if (press.index === OTHER_INDEX) {
+                const custom = await this.options.readText(target, signal);
+                if (custom === undefined)
+                    throw new QuestionCancelledError();
+                await this.retire(target, messageId, question, `Answered: ${clamp(custom, 200)}`);
+                return { id: question.id, selected: [], custom };
+            }
+            if (press.index === DONE_INDEX) {
+                const labels = selected.map((index) => options[index]?.label ?? '');
+                await this.retire(target, messageId, question, summary(labels));
+                return { id: question.id, selected: labels };
+            }
+            if (!question.multiSelect) {
+                const label = options[press.index]?.label;
+                if (label === undefined)
+                    continue;
+                await this.retire(target, messageId, question, summary([label]));
+                return { id: question.id, selected: [label] };
+            }
+            selected = toggle(selected, press.index);
+        }
+    }
+    /** A question with no options is an open one: read the user's next message. */
+    async askFreeText(question, target, signal) {
+        await this.options.surface.send(target, renderPrompt(question, []));
+        const custom = await this.options.readText(target, signal);
+        if (custom === undefined)
+            throw new QuestionCancelledError();
+        return { id: question.id, selected: [], custom };
+    }
+    /** Replace a prompt with its outcome and take the buttons away. */
+    async retire(target, messageId, question, outcome) {
+        if (messageId === undefined)
+            return;
+        const html = `${renderPrompt(question, [])}\n\n<b>${escapeWithin(outcome, 400)}</b>`;
+        await this.options.surface.edit(target, messageId, html, []).catch(() => undefined);
+    }
+}
+/**
+ * Decode `callback_data` produced by this module.
+ *
+ * @param data - raw callback data, from an untrusted update.
+ * @returns the press, or undefined when the data belongs elsewhere or is malformed.
+ */
+export function decodeCallback(data) {
+    if (data === undefined)
+        return undefined;
+    const parts = data.split(':');
+    if (parts.length !== 3 || parts[0] !== KIND)
+        return undefined;
+    const token = parts[1];
+    const index = Number(parts[2]);
+    if (token === '' || !Number.isInteger(index))
+        return undefined;
+    return { token, index };
+}
+/** Add or remove an index, preserving the order options were chosen in. */
+function toggle(selected, index) {
+    return selected.includes(index)
+        ? selected.filter((value) => value !== index)
+        : [...selected, index];
+}
+/** The question itself: header, prompt, and any option descriptions. */
+function renderPrompt(question, selected) {
+    const lines = [];
+    if (question.header)
+        lines.push(`<b>${escapeWithin(question.header, HEADER_BUDGET)}</b>`);
+    lines.push(escapeWithin(question.question, QUESTION_BUDGET));
+    const described = (question.options ?? [])
+        .filter((option) => option.description)
+        .slice(0, MAX_DESCRIBED_OPTIONS);
+    if (described.length > 0) {
+        lines.push('');
+        for (const option of described) {
+            lines.push(`• <b>${escapeWithin(option.label, MAX_BUTTON_LABEL * 2)}</b> — ` +
+                `${escapeWithin(option.description, DESCRIPTION_BUDGET)}`);
+        }
+    }
+    if (question.multiSelect) {
+        lines.push('');
+        lines.push(`<i>Pick any number, then press Done (${selected.length} selected).</i>`);
+    }
+    return lines.join('\n');
+}
+/** Buttons for one question: the options, plus Done and Other where they apply. */
+function buildKeyboard(question, selected, token) {
+    const approve = question.intent?.approve;
+    const rows = (question.options ?? []).map((option, index) => [
+        {
+            text: label(option.label, {
+                checked: question.multiSelect === true && selected.includes(index),
+                approving: approve !== undefined && option.label === approve,
+            }),
+            callbackData: `${KIND}:${token}:${index}`,
+        },
+    ]);
+    if (question.multiSelect) {
+        rows.push([{ text: '✅ Done', callbackData: `${KIND}:${token}:${DONE_INDEX}` }]);
+    }
+    else {
+        rows.push([{ text: '✏️ Other…', callbackData: `${KIND}:${token}:${OTHER_INDEX}` }]);
+    }
+    return rows;
+}
+/** One button label: trimmed to length, marked as chosen or as the approval. */
+function label(text, marks) {
+    const trimmed = text.length > MAX_BUTTON_LABEL ? `${text.slice(0, MAX_BUTTON_LABEL - 1)}…` : text;
+    if (marks.checked)
+        return `✅ ${trimmed}`;
+    if (marks.approving)
+        return `👍 ${trimmed}`;
+    return trimmed;
+}
+/** Human summary of what was chosen, for the retired prompt. */
+function summary(labels) {
+    return labels.length === 0 ? 'Answered: nothing selected' : `Answered: ${labels.join(', ')}`;
+}
+//# sourceMappingURL=questions.js.map

package/lib/interact/questions.js.map

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

package/lib/interact/surface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The narrow chat surface the interactive prompts are written against.
+ *
+ * Questions and approvals only ever need to put a message in a chat and later
+ * change it. Depending on that instead of the full Bot API client keeps those
+ * modules testable with a few lines of stub, and keeps Telegram's request
+ * shapes in one place.
+ */
+import type { TelegramApi } from '../telegram/api.js';
+import type { InlineKeyboard } from '../telegram/types.js';
+/** Where a prompt is delivered. */
+export interface ChatTarget {
+    readonly chatId: string;
+    readonly threadId?: number;
+}
+/** Post and revise messages in a chat. */
+export interface ChatSurface {
+    /**
+     * Post a message built by this plugin. HTML, because these are short,
+     * assembled from escaped text, and carry the inline keyboards.
+     */
+    send(target: ChatTarget, html: string, keyboard?: InlineKeyboard): Promise<number>;
+    /** Revise a message in place. Passing an empty keyboard retires the buttons. */
+    edit(target: ChatTarget, messageId: number, html: string, keyboard?: InlineKeyboard): Promise<void>;
+    /**
+     * Post agent-authored markdown, which Telegram renders itself — the path a
+     * plan or a diff takes, so its tables and code blocks survive.
+     */
+    sendMarkdown(target: ChatTarget, markdown: string): Promise<number>;
+}
+/** Bind a {@link ChatSurface} to the live Bot API client. */
+export declare function telegramSurface(api: TelegramApi): ChatSurface;
+//# sourceMappingURL=surface.d.ts.map

package/lib/interact/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/interact/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAClF,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnG;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACpE;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA8B7D"}

package/lib/interact/surface.js

@@ -0,0 +1,39 @@
+/**
+ * The narrow chat surface the interactive prompts are written against.
+ *
+ * Questions and approvals only ever need to put a message in a chat and later
+ * change it. Depending on that instead of the full Bot API client keeps those
+ * modules testable with a few lines of stub, and keeps Telegram's request
+ * shapes in one place.
+ */
+/** Bind a {@link ChatSurface} to the live Bot API client. */
+export function telegramSurface(api) {
+    return {
+        async send(target, html, keyboard) {
+            const sent = await api.sendMessage({
+                chatId: target.chatId,
+                html,
+                ...(keyboard ? { keyboard } : {}),
+                ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+            });
+            return sent.messageId;
+        },
+        async edit(target, messageId, html, keyboard) {
+            await api.editMessageText({
+                chatId: target.chatId,
+                messageId,
+                html,
+                ...(keyboard ? { keyboard } : {}),
+            });
+        },
+        async sendMarkdown(target, markdown) {
+            const sent = await api.sendRichMessage({
+                chatId: target.chatId,
+                markdown,
+                ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+            });
+            return sent.messageId;
+        },
+    };
+}
+//# sourceMappingURL=surface.js.map

package/lib/interact/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/interact/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA2BH,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,GAAgB;IAC9C,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YAC/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI;gBACJ,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjC,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC,CAAA;YACF,OAAO,IAAI,CAAC,SAAS,CAAA;QACvB,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ;YAC1C,MAAM,GAAG,CAAC,eAAe,CAAC;gBACxB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,SAAS;gBACT,IAAI;gBACJ,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClC,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ;YACjC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC;gBACrC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ;gBACR,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC,CAAA;YACF,OAAO,IAAI,CAAC,SAAS,CAAA;QACvB,CAAC;KACF,CAAA;AACH,CAAC"}

package/lib/interact/text-capture.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Borrowing the next chat message as an answer.
+ *
+ * When a question offers no options — or the user picks "Other…" — the answer
+ * is whatever they type next. That message would otherwise be routed to the
+ * agent as a new prompt, so the capture has to be consulted before ordinary
+ * routing, and it has to be per-conversation: a question pending in one chat
+ * must not swallow a message typed in another.
+ */
+import type { ChatTarget } from './surface.js';
+export declare class TextCapture {
+    private readonly waiting;
+    /**
+     * Wait for the next plain-text message in a conversation.
+     *
+     * A second wait on the same conversation supersedes the first, which is
+     * resolved as cancelled — the agent moved on, and only one prompt can own
+     * the user's next message.
+     *
+     * @param target - the conversation to listen in.
+     * @param signal - cancels the wait when the agent gives up.
+     * @returns the typed text, or undefined when cancelled.
+     */
+    next(target: ChatTarget, signal?: AbortSignal): Promise<string | undefined>;
+    /** Whether a conversation is currently waiting for typed input. */
+    isWaiting(target: ChatTarget): boolean;
+    /**
+     * Hand a message to a waiting prompt.
+     *
+     * @returns whether a prompt consumed it; false means route it normally.
+     */
+    deliver(target: ChatTarget, text: string): boolean;
+    /** Cancel every wait — the plugin is unloading. */
+    dispose(): void;
+    /** Cancel one conversation's wait. */
+    private cancel;
+}
+//# sourceMappingURL=text-capture.d.ts.map

package/lib/interact/text-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-capture.d.ts","sourceRoot":"","sources":["../../src/interact/text-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAQ9C,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgB3E,mEAAmE;IACnE,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAItC;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAWlD,mDAAmD;IACnD,OAAO,IAAI,IAAI;IAIf,sCAAsC;IACtC,OAAO,CAAC,MAAM;CAQf"}

package/lib/interact/text-capture.js

@@ -0,0 +1,75 @@
+/**
+ * Borrowing the next chat message as an answer.
+ *
+ * When a question offers no options — or the user picks "Other…" — the answer
+ * is whatever they type next. That message would otherwise be routed to the
+ * agent as a new prompt, so the capture has to be consulted before ordinary
+ * routing, and it has to be per-conversation: a question pending in one chat
+ * must not swallow a message typed in another.
+ */
+export class TextCapture {
+    waiting = new Map();
+    /**
+     * Wait for the next plain-text message in a conversation.
+     *
+     * A second wait on the same conversation supersedes the first, which is
+     * resolved as cancelled — the agent moved on, and only one prompt can own
+     * the user's next message.
+     *
+     * @param target - the conversation to listen in.
+     * @param signal - cancels the wait when the agent gives up.
+     * @returns the typed text, or undefined when cancelled.
+     */
+    next(target, signal) {
+        const key = keyOf(target);
+        this.cancel(key);
+        return new Promise((resolve) => {
+            if (signal?.aborted)
+                return resolve(undefined);
+            const onAbort = () => this.cancel(key);
+            this.waiting.set(key, {
+                settle: resolve,
+                detach: () => signal?.removeEventListener('abort', onAbort),
+            });
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /** Whether a conversation is currently waiting for typed input. */
+    isWaiting(target) {
+        return this.waiting.has(keyOf(target));
+    }
+    /**
+     * Hand a message to a waiting prompt.
+     *
+     * @returns whether a prompt consumed it; false means route it normally.
+     */
+    deliver(target, text) {
+        const key = keyOf(target);
+        const capture = this.waiting.get(key);
+        if (!capture)
+            return false;
+        this.waiting.delete(key);
+        capture.detach();
+        capture.settle(text);
+        return true;
+    }
+    /** Cancel every wait — the plugin is unloading. */
+    dispose() {
+        for (const key of [...this.waiting.keys()])
+            this.cancel(key);
+    }
+    /** Cancel one conversation's wait. */
+    cancel(key) {
+        const capture = this.waiting.get(key);
+        if (!capture)
+            return;
+        this.waiting.delete(key);
+        capture.detach();
+        capture.settle(undefined);
+    }
+}
+/** Conversation key; a forum topic is its own conversation. */
+function keyOf(target) {
+    return target.threadId === undefined ? target.chatId : `${target.chatId}#${target.threadId}`;
+}
+//# sourceMappingURL=text-capture.js.map

package/lib/interact/text-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-capture.js","sourceRoot":"","sources":["../../src/interact/text-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,OAAO,WAAW;IACL,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAA;IAErD;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAkB,EAAE,MAAoB;QAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAEhB,OAAO,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,EAAE;YACjD,IAAI,MAAM,EAAE,OAAO;gBAAE,OAAO,OAAO,CAAC,SAAS,CAAC,CAAA;YAE9C,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;gBACpB,MAAM,EAAE,OAAO;gBACf,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;aAC5D,CAAC,CAAA;YACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5D,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,mEAAmE;IACnE,SAAS,CAAC,MAAkB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;IACxC,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAkB,EAAE,IAAY;QACtC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAA;QAE1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxB,OAAO,CAAC,MAAM,EAAE,CAAA;QAChB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,mDAAmD;IACnD,OAAO;QACL,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC9D,CAAC;IAED,sCAAsC;IAC9B,MAAM,CAAC,GAAW;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrC,IAAI,CAAC,OAAO;YAAE,OAAM;QAEpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxB,OAAO,CAAC,MAAM,EAAE,CAAA;QAChB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,+DAA+D;AAC/D,SAAS,KAAK,CAAC,MAAkB;IAC/B,OAAO,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAA;AAC9F,CAAC"}

package/lib/media/collect.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Fetching a message's media and turning it into prompt content.
+ *
+ * Downloading is the part that can go wrong in ordinary ways — a file above
+ * the bot download limit, a network drop, an image the harness refuses — and
+ * none of them should cost the user their message. So every failure becomes a
+ * note in the prompt saying what could not be read, and the text the user
+ * typed alongside it still reaches the agent.
+ */
+import type { TelegramMessage } from '../telegram/types.js';
+import type { Logger } from '../harness/types.js';
+import type { ImageLimits } from './limits.js';
+import type { VisionCheck } from './vision.js';
+/** A durable image reference, as the harness attachment seam returns it. */
+export interface ImageRef {
+    readonly attachmentId: unknown;
+    readonly mediaType: string;
+    readonly bytes: number;
+    readonly width: number;
+    readonly height: number;
+    readonly name?: string;
+}
+/** One piece of a prompt. */
+export type PromptPart = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'image';
+    readonly attachment: ImageRef;
+};
+/** Downloading bytes from Telegram. */
+export interface MediaSource {
+    getFile(fileId: string): Promise<{
+        file_path?: string;
+        file_size?: number;
+    }>;
+    downloadFile(filePath: string, signal?: AbortSignal): Promise<Uint8Array>;
+}
+/** The harness attachment seam, narrowed to what this needs. */
+export interface AttachmentStore {
+    saveImage(input: {
+        data: Uint8Array;
+        mediaType: string;
+        name?: string;
+    }): Promise<ImageRef>;
+    /**
+     * The seam's own limits, where it publishes them.
+     *
+     * Read rather than configured a second time: the operator sets this on the
+     * attachment plugin, and a copy on this side would silently drift out of
+     * step with the number that actually decides.
+     */
+    readonly imageLimits?: ImageLimits;
+}
+/** What the caller knows about the turn these attachments are for. */
+export interface CollectionContext {
+    /**
+     * Whether the model this turn will run on accepts images itself.
+     *
+     * Decided per conversation, because `/model` is per conversation: judging
+     * the deployment default would refuse an image on a chat that had switched
+     * to a model which can see.
+     */
+    readonly modelSees?: boolean;
+}
+/** What a message's attachments became, plus anything the user should be told. */
+export interface CollectedMedia {
+    /** Content for the agent, in the order the model should read it. */
+    readonly parts: PromptPart[];
+    /**
+     * A line for the chat, when something the user sent could not be used. The
+     * agent's prompt says so too, but the person who sent it should not have to
+     * wait for a reply to learn their screenshot went nowhere.
+     */
+    readonly notice?: string;
+}
+/** Construction options. */
+export interface MediaCollectorOptions {
+    readonly source: MediaSource;
+    /** Absent on a deployment with no attachment seam; images are then declined. */
+    readonly attachments?: AttachmentStore;
+    /**
+     * Whether the model can read an image at all. Absent skips the check and
+     * lets the provider be the authority, which is the older behaviour.
+     */
+    readonly vision?: VisionCheck;
+    /**
+     * Whether an image can be read even where no model accepts one — OCR.
+     *
+     * Consulted before refusing, because a refusal here happens before the
+     * download and so takes the picture away from whatever could have read it.
+     */
+    readonly canReadWithoutModel?: () => Promise<boolean>;
+    /** Refuse anything larger, before downloading it. */
+    readonly maxBytes: number;
+    /** Truncate an inlined text file to this many characters. */
+    readonly maxTextChars: number;
+    /**
+     * Strip anything secret from a refusal before it is written down.
+     *
+     * A refusal quotes the failure that caused it, and lands in two durable
+     * places at once: the chat, and the session log the agent carries forward.
+     * The API client already redacts its own errors, so this is the second lock
+     * rather than the first — but this sink is the one that persists.
+     */
+    readonly redact?: (text: string) => string;
+    readonly logger?: Logger;
+}
+export declare class MediaCollector {
+    private readonly options;
+    private readonly logger;
+    constructor(options: MediaCollectorOptions);
+    /**
+     * Turn one message into the parts a prompt is built from.
+     *
+     * @param message - the incoming message.
+     * @param caption - the text the user typed, if any.
+     * @returns text and image parts, in the order the model should read them.
+     */
+    collect(message: TelegramMessage, caption: string | undefined, context?: CollectionContext): Promise<CollectedMedia>;
+    /**
+     * Turn a whole album into one prompt.
+     *
+     * Each part is collected on its own — the same path a single photo takes, so
+     * refusals and size limits behave identically — and the results are then
+     * laid out as one message would have been: what the user said, then every
+     * image, then anything that could not be read.
+     *
+     * @param messages - the album's parts, in the order they were sent.
+     * @param caption - the one caption the album carries.
+     */
+    collectAll(messages: readonly TelegramMessage[], caption: string | undefined, context?: CollectionContext): Promise<CollectedMedia>;
+    /**
+     * Store an image, stepping down through Telegram's smaller renderings.
+     *
+     * The seam refuses anything over its per-side limit, and the largest size of
+     * a phone screenshot is always over it — 1179×2556 against a limit of 2000.
+     * The largest size that fits is tried first, and a rejection falls through
+     * to the next, because the limit belongs to the harness and may not be the
+     * number read here.
+     *
+     * @returns the stored reference, or undefined when no size was accepted.
+     */
+    private storeImage;
+    /**
+     * Why an image must not be sent on the current route, if it must not.
+     *
+     * A model with no image input rejects the entire request, so this refusal
+     * replaces a failed turn with a sentence naming what would have worked.
+     */
+    private imageRefusal;
+    /** Keep the caption, tell the agent what was left out, and tell the user why. */
+    private declined;
+    /** Resolve a file id and pull its bytes, refusing anything oversized. */
+    private download;
+}
+//# sourceMappingURL=collect.d.ts.map

package/lib/media/collect.d.ts.map

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