@copilotkit/channels-telegram 0.0.3

package/dist/built-in-tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Telegram-platform-universal frontend tools — tools every Telegram bot
+ * benefits from, regardless of what the bot does. Apps spread
+ * `defaultTelegramTools` into the `tools:` config they pass to
+ * `createBot`.
+ */
+import { z } from "zod";
+import type { BotTool } from "@copilotkit/channels";
+export declare const lookupTelegramUserTool: BotTool<z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>>;
+/**
+ * The flat list of tools the SDK ships. Spread into your
+ * `createBot({tools: …})`:
+ *
+ *     tools: [...defaultTelegramTools, ...myAppTools],
+ */
+export declare const defaultTelegramTools: ReadonlyArray<BotTool>;
+//# sourceMappingURL=built-in-tools.d.ts.map

package/dist/built-in-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-tools.d.ts","sourceRoot":"","sources":["../src/built-in-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AASpD,eAAO,MAAM,sBAAsB;;;;;;GAuBjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,OAAO,CAEvD,CAAC"}

package/dist/built-in-tools.js

@@ -0,0 +1,46 @@
+/**
+ * Telegram-platform-universal frontend tools — tools every Telegram bot
+ * benefits from, regardless of what the bot does. Apps spread
+ * `defaultTelegramTools` into the `tools:` config they pass to
+ * `createBot`.
+ */
+import { z } from "zod";
+import { defineBotTool } from "@copilotkit/channels";
+const lookupSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("Handle, display name, or first name of the person to look up."),
+});
+export const lookupTelegramUserTool = defineBotTool({
+    name: "lookup_telegram_user",
+    description: "Resolve a person to a Telegram user ID so you can mention them. " +
+        "Accepts a handle (`ada`), display name (`Ada Lovelace`), or first name. " +
+        "Returns an object with `found`, and on success a " +
+        "`mention` string (e.g. `@ada` or `tg://user?id=7`) — put that string verbatim " +
+        "in your reply to ping them. If `found` is false, write the plain " +
+        "name instead.",
+    parameters: lookupSchema,
+    async handler({ query }, { thread }) {
+        const u = await thread.lookupUser(query);
+        return u
+            ? {
+                found: true,
+                query,
+                userId: u.id,
+                name: u.name,
+                handle: u.handle,
+                mention: u.handle ? "@" + u.handle : "tg://user?id=" + u.id,
+            }
+            : { found: false, query };
+    },
+});
+/**
+ * The flat list of tools the SDK ships. Spread into your
+ * `createBot({tools: …})`:
+ *
+ *     tools: [...defaultTelegramTools, ...myAppTools],
+ */
+export const defaultTelegramTools = [
+    lookupTelegramUserTool,
+];

package/dist/chunked-edit-stream.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Per-Telegram-message streaming text state machine.
+ *
+ * Mirrors the Slack MessageStream + ChunkedMessageStream pattern but uses
+ * numeric Telegram message IDs instead of Slack `ts` strings.
+ *
+ * ChunkedEditStream owns N underlying EditStream instances (one per Telegram
+ * message). It accepts the full accumulated text on `append()`, decides where
+ * the chunk boundaries are (frozen once a message has been posted — no reflow),
+ * mints new Telegram messages via `postPlaceholder` as needed, and dispatches
+ * the right slice to each chunk's stream.
+ *
+ * `transform` (e.g. telegramHtml) is applied just before every `editAt` call.
+ */
+export interface ChunkedEditStreamConfig {
+    /**
+     * Soft per-message raw char limit. Defaults to Math.floor(TELEGRAM_LIMITS.messageText / 2).
+     * The headroom below the 4096 hard cap exists because `transform` (telegramHtml) can
+     * expand raw chars significantly: `&`→`&amp;` (5×), `<`/`>`→`&lt;`/`&gt;` (4×),
+     * bold/link markdown → HTML tags. Halving the limit is a risk-reduction heuristic that
+     * keeps the HTML-transformed slice under 4096 for typical prose/markdown content (which
+     * expands modestly); it is NOT a hard guarantee against adversarial all-entity input
+     * (e.g. 2048 raw `&` chars → ~10 240 transformed chars).
+     */
+    limit?: number;
+    /** Throttle floor (ms) between consecutive edits per message. Defaults to 1000. */
+    minIntervalMs?: number;
+    /** Posts a new Telegram message with placeholder text; resolves with the message id. */
+    postPlaceholder: (text: string) => Promise<number>;
+    /** Edits the Telegram message with the given id to contain `text`. */
+    editAt: (messageId: number, text: string) => Promise<void>;
+    /**
+     * Optional transformer applied to each chunk's text before `editAt` /
+     * `postPlaceholder` — e.g. telegramHtml markdown→HTML conversion.
+     */
+    transform?: (text: string) => string;
+}
+export declare class ChunkedEditStream {
+    private buffer;
+    /** Sorted character positions where a chunk ends (= where the next begins). */
+    private boundaries;
+    private streams;
+    /** Serialises new-chunk creation so async postPlaceholder calls don't race. */
+    private setupPromise;
+    private finished;
+    private readonly limit;
+    private readonly minIntervalMs;
+    private readonly postPlaceholder;
+    private readonly editAt;
+    private readonly transform;
+    constructor(config: ChunkedEditStreamConfig);
+    /**
+     * Feed the FULL accumulated text so far. The stream will work out which
+     * slice belongs to which Telegram message and throttle edits accordingly.
+     */
+    append(fullText: string): void;
+    /** Flush all pending edits and wait until every message reflects its final text. */
+    finish(): Promise<void>;
+    /** Number of Telegram messages posted so far. */
+    get chunkCount(): number;
+    /**
+     * Walk forward from the last frozen boundary, freezing new ones whenever
+     * the active chunk's length exceeds the soft limit. Choose the break point
+     * at the last newline (or last space) within the window; fall back to a hard
+     * cut if neither is found. Boundaries never move once frozen.
+     */
+    private refreezeBoundaries;
+    private ensureStreamsAndDispatch;
+}
+//# sourceMappingURL=chunked-edit-stream.d.ts.map

package/dist/chunked-edit-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked-edit-stream.d.ts","sourceRoot":"","sources":["../src/chunked-edit-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,sEAAsE;IACtE,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AA+FD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAM;IACpB,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,OAAO,CAAoB;IACnC,+EAA+E;IAC/E,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAEzC,MAAM,EAAE,uBAAuB;IAQ3C;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAU9B,oFAAoF;IAC9E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B,iDAAiD;IACjD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;YAgBZ,wBAAwB;CAsCvC"}

package/dist/chunked-edit-stream.js

@@ -0,0 +1,197 @@
+/**
+ * Per-Telegram-message streaming text state machine.
+ *
+ * Mirrors the Slack MessageStream + ChunkedMessageStream pattern but uses
+ * numeric Telegram message IDs instead of Slack `ts` strings.
+ *
+ * ChunkedEditStream owns N underlying EditStream instances (one per Telegram
+ * message). It accepts the full accumulated text on `append()`, decides where
+ * the chunk boundaries are (frozen once a message has been posted — no reflow),
+ * mints new Telegram messages via `postPlaceholder` as needed, and dispatches
+ * the right slice to each chunk's stream.
+ *
+ * `transform` (e.g. telegramHtml) is applied just before every `editAt` call.
+ */
+import { TELEGRAM_LIMITS } from "./render/budget.js";
+/**
+ * Default raw-char limit per chunk. Set to half of Telegram's 4096 hard cap as a
+ * generous headroom heuristic: typical prose/markdown content expands modestly under
+ * telegramHtml, so this keeps the rendered output well under 4096 in practice.
+ * It is NOT a hard guarantee — adversarial all-entity input can still exceed the cap.
+ */
+const DEFAULT_LIMIT = Math.floor(TELEGRAM_LIMITS.messageText / 2); // 2048
+const DEFAULT_MIN_INTERVAL_MS = 1000;
+class EditStream {
+    buffer = "";
+    posted = "";
+    queue = Promise.resolve();
+    lastFlushedAt = 0;
+    flushTimer;
+    minIntervalMs;
+    update;
+    /** Non-null when the terminal flush (from finish()) failed. */
+    terminalError = undefined;
+    constructor(config) {
+        this.update = config.update;
+        this.minIntervalMs = config.minIntervalMs;
+    }
+    append(text) {
+        if (text === this.buffer)
+            return;
+        this.buffer = text;
+        this.scheduleFlush();
+    }
+    async finish() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        this.enqueueFlush(/* terminal */ true);
+        await this.queue;
+        if (this.terminalError !== undefined) {
+            throw this.terminalError;
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        const elapsed = Date.now() - this.lastFlushedAt;
+        const delay = Math.max(0, this.minIntervalMs - elapsed);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            this.enqueueFlush(false);
+        }, delay);
+    }
+    enqueueFlush(terminal) {
+        this.queue = this.queue.then(() => this.flushNow(terminal));
+    }
+    async flushNow(terminal) {
+        if (this.buffer === this.posted)
+            return;
+        const text = this.buffer;
+        try {
+            await this.update(text);
+            // Only advance posted after a successful edit so a transient failure
+            // leaves the text eligible for retry on the next flush.
+            this.posted = text;
+        }
+        catch (err) {
+            if (terminal) {
+                // Surface terminal-flush failures to finish() so the caller can react.
+                this.terminalError = err;
+            }
+            else {
+                // Intermediate flush: log but leave posted unchanged so the next
+                // flush will re-attempt the current buffer.
+                console.error("[chunked-edit-stream] editAt failed:", err);
+            }
+        }
+        finally {
+            this.lastFlushedAt = Date.now();
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// ChunkedEditStream
+// ---------------------------------------------------------------------------
+export class ChunkedEditStream {
+    buffer = "";
+    /** Sorted character positions where a chunk ends (= where the next begins). */
+    boundaries = [];
+    streams = [];
+    /** Serialises new-chunk creation so async postPlaceholder calls don't race. */
+    setupPromise = Promise.resolve();
+    finished = false;
+    limit;
+    minIntervalMs;
+    postPlaceholder;
+    editAt;
+    transform;
+    constructor(config) {
+        this.limit = config.limit ?? DEFAULT_LIMIT;
+        this.minIntervalMs = config.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+        this.postPlaceholder = config.postPlaceholder;
+        this.editAt = config.editAt;
+        this.transform = config.transform ?? ((t) => t);
+    }
+    /**
+     * Feed the FULL accumulated text so far. The stream will work out which
+     * slice belongs to which Telegram message and throttle edits accordingly.
+     */
+    append(fullText) {
+        if (this.finished)
+            return;
+        if (fullText === this.buffer)
+            return;
+        this.buffer = fullText;
+        this.refreezeBoundaries();
+        this.setupPromise = this.setupPromise.then(() => this.ensureStreamsAndDispatch());
+    }
+    /** Flush all pending edits and wait until every message reflects its final text. */
+    async finish() {
+        this.finished = true;
+        this.setupPromise = this.setupPromise.then(() => this.ensureStreamsAndDispatch());
+        await this.setupPromise;
+        for (const s of this.streams)
+            await s.finish();
+    }
+    /** Number of Telegram messages posted so far. */
+    get chunkCount() {
+        return this.streams.length;
+    }
+    /**
+     * Walk forward from the last frozen boundary, freezing new ones whenever
+     * the active chunk's length exceeds the soft limit. Choose the break point
+     * at the last newline (or last space) within the window; fall back to a hard
+     * cut if neither is found. Boundaries never move once frozen.
+     */
+    refreezeBoundaries() {
+        const minAdvance = Math.max(1, Math.floor(this.limit / 2));
+        let lastFrozen = this.boundaries.at(-1) ?? 0;
+        while (this.buffer.length - lastFrozen > this.limit) {
+            const window = this.buffer.slice(lastFrozen, lastFrozen + this.limit);
+            let breakAt = window.lastIndexOf("\n");
+            if (breakAt < this.limit / 4)
+                breakAt = window.lastIndexOf(" ");
+            // Bug 1 fix: enforce a minimum advance floor so adversarial input
+            // (e.g. leading spaces / early newlines) doesn't produce ~1-char chunks.
+            if (breakAt < minAdvance)
+                breakAt = this.limit - 1;
+            const candidate = lastFrozen + breakAt + 1;
+            this.boundaries.push(candidate);
+            lastFrozen = candidate;
+        }
+    }
+    async ensureStreamsAndDispatch() {
+        if (this.buffer.length === 0)
+            return;
+        // Bug 2 fix: if the last boundary lands exactly at buffer.length the final
+        // "chunk" would be an empty string — drop that phantom boundary so we don't
+        // post a blank placeholder message.
+        while (this.boundaries.length > 0 &&
+            this.boundaries[this.boundaries.length - 1] >= this.buffer.length) {
+            this.boundaries.pop();
+        }
+        const chunkCount = this.boundaries.length + 1;
+        while (this.streams.length < chunkCount) {
+            // Plain-text placeholder (no Markdown): postPlaceholder sends with
+            // parse_mode:"HTML", so Markdown italics would render literal underscores.
+            const placeholder = "…";
+            const messageId = await this.postPlaceholder(placeholder);
+            this.streams.push(new EditStream({
+                update: (text) => this.editAt(messageId, this.transform(text) || " "),
+                minIntervalMs: this.minIntervalMs,
+            }));
+        }
+        // Dispatch slices to each message's stream.
+        for (let i = 0; i < chunkCount; i++) {
+            const start = i === 0 ? 0 : this.boundaries[i - 1];
+            const end = i < this.boundaries.length ? this.boundaries[i] : this.buffer.length;
+            const slice = this.buffer.slice(start, end);
+            // Bug 2 fix: never dispatch an empty slice.
+            if (slice.length > 0) {
+                this.streams[i].append(slice);
+            }
+        }
+    }
+}

package/dist/conversation-store.d.ts

@@ -0,0 +1,56 @@
+import type { AbstractAgent } from "@ag-ui/client";
+import type { ThreadMessage } from "@copilotkit/channels-ui";
+import type { ConversationStore, AgentSession } from "@copilotkit/channels";
+import type { ReplyTarget } from "./types.js";
+import type { AgentContentPart } from "./download-files.js";
+/**
+ * Telegram conversation store with stable threadIds.
+ *
+ * Unlike Slack (which rebuilds history from the platform API and mints a fresh
+ * threadId per turn), Telegram's Bot API cannot read chat history.  This store
+ * therefore:
+ *  - assigns each conversation a **stable** threadId (`tg-thread-<key>`) so the
+ *    agent's own persistence layer can accumulate state across turns; and
+ *  - maintains an in-memory message log (lost on restart, capped at 200 entries)
+ *    that callers can use for lightweight within-session context.
+ */
+export declare class TelegramConversationStore implements ConversationStore {
+    private readonly sessions;
+    private readonly history;
+    /**
+     * Per-conversation queue of user messages awaiting delivery to the agent.
+     *
+     * The listener enqueues each turn's user message (text, or text + file
+     * parts) BEFORE invoking the bot handler that calls `runAgent` →
+     * {@link getOrCreate}, which drains the queue into the cached agent. This is
+     * how Telegram delivers the user's turn to the agent: unlike Slack, the Bot
+     * API cannot read chat history, so `Thread.run()` (which only injects a
+     * message when `extra.prompt` is set) would otherwise never see the input.
+     */
+    private readonly pending;
+    private threadIdFor;
+    /**
+     * Enqueue a user message to be delivered to the agent on the next
+     * {@link getOrCreate} for `conversationKey`. Content is either a plain text
+     * string or an array of AG-UI content parts (text + media).
+     */
+    enqueueUserMessage(conversationKey: string, content: string | AgentContentPart[]): void;
+    /**
+     * Return the cached AgentSession for `conversationKey`, or create one.
+     *
+     * On first call for a key `makeAgent` is invoked exactly once with the
+     * stable threadId; subsequent calls return the same cached session without
+     * invoking `makeAgent` again.
+     */
+    getOrCreate(conversationKey: string, _replyTarget: ReplyTarget, makeAgent: (threadId: string) => AbstractAgent): Promise<AgentSession>;
+    /**
+     * Append `msg` to the in-memory history for `conversationKey`.
+     * Drops the oldest entry when the list exceeds {@link MAX_HISTORY}.
+     */
+    recordMessage(conversationKey: string, msg: ThreadMessage): void;
+    /** Return the recorded message history for `conversationKey` (or `[]`). */
+    getMessages(conversationKey: string): ThreadMessage[];
+    /** Whether a session exists for `conversationKey`. */
+    has(conversationKey: string): boolean;
+}
+//# sourceMappingURL=conversation-store.d.ts.map

package/dist/conversation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-store.d.ts","sourceRoot":"","sources":["../src/conversation-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5D;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IAEJ,OAAO,CAAC,WAAW;IAInB;;;;OAIG;IACH,kBAAkB,CAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE,GACnC,IAAI;IASP;;;;;;OAMG;IACG,WAAW,CACf,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,WAAW,EACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,GAC7C,OAAO,CAAC,YAAY,CAAC;IA2BxB;;;OAGG;IACH,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI;IAYhE,2EAA2E;IAC3E,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,aAAa,EAAE;IAIrD,sDAAsD;IACtD,GAAG,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO;CAGtC"}

package/dist/conversation-store.js

@@ -0,0 +1,98 @@
+/** Maximum number of messages retained per conversation (oldest dropped). */
+const MAX_HISTORY = 200;
+/**
+ * Telegram conversation store with stable threadIds.
+ *
+ * Unlike Slack (which rebuilds history from the platform API and mints a fresh
+ * threadId per turn), Telegram's Bot API cannot read chat history.  This store
+ * therefore:
+ *  - assigns each conversation a **stable** threadId (`tg-thread-<key>`) so the
+ *    agent's own persistence layer can accumulate state across turns; and
+ *  - maintains an in-memory message log (lost on restart, capped at 200 entries)
+ *    that callers can use for lightweight within-session context.
+ */
+export class TelegramConversationStore {
+    sessions = new Map();
+    history = new Map();
+    /**
+     * Per-conversation queue of user messages awaiting delivery to the agent.
+     *
+     * The listener enqueues each turn's user message (text, or text + file
+     * parts) BEFORE invoking the bot handler that calls `runAgent` →
+     * {@link getOrCreate}, which drains the queue into the cached agent. This is
+     * how Telegram delivers the user's turn to the agent: unlike Slack, the Bot
+     * API cannot read chat history, so `Thread.run()` (which only injects a
+     * message when `extra.prompt` is set) would otherwise never see the input.
+     */
+    pending = new Map();
+    threadIdFor(conversationKey) {
+        return `tg-thread-${conversationKey}`;
+    }
+    /**
+     * Enqueue a user message to be delivered to the agent on the next
+     * {@link getOrCreate} for `conversationKey`. Content is either a plain text
+     * string or an array of AG-UI content parts (text + media).
+     */
+    enqueueUserMessage(conversationKey, content) {
+        let list = this.pending.get(conversationKey);
+        if (!list) {
+            list = [];
+            this.pending.set(conversationKey, list);
+        }
+        list.push({ content });
+    }
+    /**
+     * Return the cached AgentSession for `conversationKey`, or create one.
+     *
+     * On first call for a key `makeAgent` is invoked exactly once with the
+     * stable threadId; subsequent calls return the same cached session without
+     * invoking `makeAgent` again.
+     */
+    async getOrCreate(conversationKey, _replyTarget, makeAgent) {
+        let session = this.sessions.get(conversationKey);
+        if (!session) {
+            const threadId = this.threadIdFor(conversationKey);
+            const agent = makeAgent(threadId);
+            session = { agent };
+            this.sessions.set(conversationKey, session);
+        }
+        // Drain any user messages the listener enqueued for this turn into the
+        // agent so they actually reach the model. Clears the queue so a later
+        // getOrCreate (e.g. a follow-up run) does not re-deliver them.
+        const queued = this.pending.get(conversationKey);
+        if (queued && queued.length > 0) {
+            for (const { content } of queued) {
+                session.agent.addMessage({
+                    id: globalThis.crypto.randomUUID(),
+                    role: "user",
+                    content,
+                });
+            }
+            this.pending.delete(conversationKey);
+        }
+        return session;
+    }
+    /**
+     * Append `msg` to the in-memory history for `conversationKey`.
+     * Drops the oldest entry when the list exceeds {@link MAX_HISTORY}.
+     */
+    recordMessage(conversationKey, msg) {
+        let list = this.history.get(conversationKey);
+        if (!list) {
+            list = [];
+            this.history.set(conversationKey, list);
+        }
+        list.push(msg);
+        if (list.length > MAX_HISTORY) {
+            list.shift();
+        }
+    }
+    /** Return the recorded message history for `conversationKey` (or `[]`). */
+    getMessages(conversationKey) {
+        return this.history.get(conversationKey) ?? [];
+    }
+    /** Whether a session exists for `conversationKey`. */
+    has(conversationKey) {
+        return this.sessions.has(conversationKey);
+    }
+}

package/dist/download-files.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Inbound file transport. Telegram messages can carry file attachments; this
+ * turns them into AG-UI multimodal message content the agent's model can
+ * read — images, audio, video, and documents as their respective binary parts —
+ * downloading each from the Telegram Bot API file endpoint.
+ *
+ * The bridge is transport-only: it delivers the bytes to the agent and lets
+ * the app decide what to do with them. Anything it can't represent is skipped
+ * with a short note so the agent knows a file was dropped and why.
+ */
+/** The subset of a Telegram file object we use. */
+export interface TelegramFileRef {
+    fileId: string;
+    fileName?: string;
+    mimeType?: string;
+    size?: number;
+}
+/** A base64 data source, shared by every binary media part. */
+type MediaDataSource = {
+    type: "data";
+    value: string;
+    mimeType: string;
+};
+/**
+ * AG-UI multimodal content parts (shape the runtime's converter expects).
+ *
+ * Binary media (image/audio/video/document) is passed straight through as a
+ * data part; the agent's model decides what it can actually consume.
+ */
+export type AgentContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: MediaDataSource;
+} | {
+    type: "audio";
+    source: MediaDataSource;
+} | {
+    type: "video";
+    source: MediaDataSource;
+} | {
+    type: "document";
+    source: MediaDataSource;
+};
+/** Tunables for inbound file handling (all optional; sane defaults). */
+export interface FileDeliveryConfig {
+    /** Skip a single file larger than this many bytes. Default 8 MiB. */
+    maxBytesPerFile?: number;
+    /** Process at most this many files per message. Default 5. */
+    maxFiles?: number;
+}
+/**
+ * Download a message's files and turn them into AG-UI content parts. Returns
+ * the parts plus human-readable `notes` for anything skipped (appended to the
+ * message as a text part by the caller).
+ *
+ * @param files      List of Telegram file references to process.
+ * @param token      Telegram bot token used to build the download URL.
+ * @param getFilePath  Resolves a fileId to a Telegram file path (e.g. via getFile API).
+ * @param config     Optional delivery configuration.
+ */
+export declare function buildFileContentParts(files: TelegramFileRef[], token: string, getFilePath: (fileId: string) => Promise<string>, config?: FileDeliveryConfig): Promise<{
+    parts: AgentContentPart[];
+    notes: string[];
+}>;
+export {};
+//# sourceMappingURL=download-files.d.ts.map

package/dist/download-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-files.d.ts","sourceRoot":"","sources":["../src/download-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAElD,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA0DD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,eAAe,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAChD,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAoGzD"}