@songsid/agend 2.2.0-alpha.2 → 2.2.0-alpha.3

package/dist/reply-buttons-controller.d.ts

@@ -0,0 +1,98 @@
+/**
+ * #1266: what happens to a reply's buttons after they are sent — a click on a platform or in the web chat, the one
+ * choice it makes, the message showing how it ended, and the expiry sweep. The store (reply-buttons.ts) is the truth;
+ * this decides who may click and keeps every surface in step with it. FleetManager supplies the fleet's own pieces.
+ */
+import type { ChannelAdapter } from "./channel/types.js";
+import { type ReplyButton, type ReplyButtonSet, type ReplyButtonStore } from "./reply-buttons.js";
+/** A click from a platform adapter (the fleet's callback shape). */
+export interface ReplyButtonClick {
+    callbackData: string;
+    chatId: string;
+    threadId?: string;
+    messageId: string;
+    userId?: string;
+    username?: string;
+    ack?: (notice?: string) => void;
+}
+/** What a web page shows for a reply's buttons. */
+export interface ReplyButtonsView {
+    id: string;
+    labels: string[];
+    state: "open" | "chosen" | "expired";
+    chosen?: number;
+    by?: string;
+}
+export interface ReplyButtonsDeps {
+    store: ReplyButtonStore;
+    /** Wall clock: an expiry is a calendar instant that must hold across restarts. */
+    now(): number;
+    adapterFor(adapterId: string): ChannelAdapter | undefined;
+    /** May this platform user answer this set — someone who may message its instance there? */
+    mayClick(set: ReplyButtonSet, userId: string): boolean;
+    /** Deliver the choice to the instance as an inbound message; false when it could not be delivered. */
+    deliver(set: ReplyButtonSet, button: ReplyButton, by: {
+        userId: string;
+        username: string;
+        source: "web" | string;
+    }): Promise<boolean>;
+    /** Tell the web pages a set changed. */
+    publish(instance: string, view: ReplyButtonsView): void;
+    logger: {
+        info(obj: object, msg?: string): void;
+        warn(obj: object, msg?: string): void;
+    };
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+export declare class ReplyButtonsController {
+    private readonly deps;
+    private timer;
+    private stopped;
+    /** Claims this process is delivering right now (a sweep leaves them alone). */
+    private readonly inFlight;
+    constructor(deps: ReplyButtonsDeps);
+    /** Before the send: a set for these buttons, and the callbacks the platform will carry. */
+    prepare(where: {
+        instance: string;
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+    }, buttons: readonly ReplyButton[]): {
+        id: string;
+        callbacks: Array<{
+            id: string;
+            label: string;
+        }>;
+    };
+    /** After a confirmed send: the message the buttons are on. From now on a click there can match. */
+    bind(id: string, messageId: string): void;
+    /** A send that failed: the set never existed. */
+    discard(id: string): void;
+    view(set: ReplyButtonSet, now?: number): ReplyButtonsView;
+    viewOf(id: string): ReplyButtonsView | null;
+    /** A platform click. True when the callback is a reply button's (handled here, whatever the outcome). */
+    handleCallback(data: ReplyButtonClick, adapterId: string): Promise<boolean>;
+    /** A click in the web chat (the caller has passed the /ui gate: a session, or the public link). */
+    clickWeb(instance: string, id: string, index: number): Promise<{
+        status: 200 | 400 | 403 | 409;
+        error?: string;
+    }>;
+    /** Consume, deliver, then show it everywhere. A choice the agent could not be given is undone (the set reopens). */
+    private choose;
+    /**
+     * Show how a set ended on its platform message and in the web chat; once. A failed edit is not retried. Ended is: a
+     * delivered choice, an expiry with no claim, or (`closeClaim`) a claim no process is delivering any more.
+     */
+    settle(set: ReplyButtonSet, closeClaim?: boolean): Promise<void>;
+    /**
+     * Settle what has ended (an expiry, or a choice whose message was not updated before a restart), then re-arm. A
+     * claim no one in this process is delivering was left by a process that stopped mid-delivery: whether the agent got
+     * it is unknown, so it is closed as expired ("reply in text") rather than reopened — reopening could deliver a
+     * second choice.
+     */
+    sweep(): Promise<void>;
+    /** One timer, for the next expiry. A wall-clock jump makes it fire early or late; the sweep re-reads the clock. */
+    arm(): void;
+    stop(): void;
+}

package/dist/reply-buttons-controller.js

@@ -0,0 +1,174 @@
+import { t } from "./locale.js";
+import { REPLY_BUTTON_PREFIX, newReplyButtonsId, parseReplyButtonCallback, replyButtonCallback, replyButtonsClickPlace, } from "./reply-buttons.js";
+/** Settled sets are kept a week (a page may still show the reply), then pruned. */
+const KEEP_SETTLED_MS = 7 * 24 * 60 * 60 * 1000;
+/** setTimeout's ceiling; a later expiry is reached by re-arming. */
+const MAX_TIMER_MS = 2_147_483_647;
+export class ReplyButtonsController {
+    deps;
+    timer = null;
+    stopped = false;
+    /** Claims this process is delivering right now (a sweep leaves them alone). */
+    inFlight = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Before the send: a set for these buttons, and the callbacks the platform will carry. */
+    prepare(where, buttons) {
+        const id = newReplyButtonsId();
+        this.deps.store.create({ id, instance: where.instance, adapterId: where.adapterId, chatId: where.chatId, threadId: where.threadId ?? "", buttons: [...buttons] }, this.deps.now());
+        return { id, callbacks: buttons.map((b, i) => ({ id: replyButtonCallback(id, i), label: b.label })) };
+    }
+    /** After a confirmed send: the message the buttons are on. From now on a click there can match. */
+    bind(id, messageId) {
+        this.deps.store.bind(id, messageId);
+        this.arm();
+    }
+    /** A send that failed: the set never existed. */
+    discard(id) { this.deps.store.remove(id); }
+    view(set, now = this.deps.now()) {
+        const labels = set.buttons.map(b => b.label);
+        if (set.deliveredAt !== null && set.chosenIndex !== null)
+            return { id: set.id, labels, state: "chosen", chosen: set.chosenIndex, by: set.chosenBy ?? "" };
+        // Settled without a delivered choice: expired, or a claim a stopped process never delivered (closed as expired).
+        if (set.settledAt !== null)
+            return { id: set.id, labels, state: "expired" };
+        return { id: set.id, labels, state: now >= set.expiresAt && set.consumedAt === null ? "expired" : "open" };
+    }
+    viewOf(id) {
+        const set = this.deps.store.get(id);
+        return set ? this.view(set) : null;
+    }
+    /** A platform click. True when the callback is a reply button's (handled here, whatever the outcome). */
+    async handleCallback(data, adapterId) {
+        if (!data.callbackData.startsWith(REPLY_BUTTON_PREFIX))
+            return false;
+        const parsed = parseReplyButtonCallback(data.callbackData);
+        const set = parsed ? this.deps.store.get(parsed.id) : null;
+        if (!parsed || !set) {
+            data.ack?.(t("reply_buttons.closed"));
+            return true;
+        }
+        if (!replyButtonsClickPlace(set, { adapterId, chatId: data.chatId, threadId: data.threadId, messageId: data.messageId })) {
+            this.deps.logger.warn({ adapterId, set: set.id }, "Refused reply-button click: not on the message the buttons were sent on");
+            data.ack?.(t("buttons.wrong_place"));
+            return true;
+        }
+        if (!data.userId || !this.deps.mayClick(set, data.userId)) {
+            this.deps.logger.warn({ adapterId, set: set.id, userId: data.userId }, "Refused reply-button click: not someone who may message this instance here");
+            data.ack?.(t("buttons.not_allowed"));
+            return true;
+        }
+        await this.choose(set.id, parsed.index, { userId: data.userId, username: data.username || data.userId, source: "platform" }, data.ack);
+        return true;
+    }
+    /** A click in the web chat (the caller has passed the /ui gate: a session, or the public link). */
+    async clickWeb(instance, id, index) {
+        if (!/^[0-9a-f]{32}$/.test(id) || !Number.isInteger(index) || index < 0)
+            return { status: 400, error: "Malformed button" };
+        const set = this.deps.store.get(id);
+        if (!set)
+            return { status: 409, error: t("reply_buttons.closed") };
+        if (set.instance !== instance)
+            return { status: 403, error: "This button belongs to another instance" };
+        let notice;
+        const ok = await this.choose(id, index, { userId: "web-user", username: "web-user", source: "web" }, n => { notice = n; });
+        return ok ? { status: 200 } : { status: 409, error: notice ?? t("reply_buttons.closed") };
+    }
+    /** Consume, deliver, then show it everywhere. A choice the agent could not be given is undone (the set reopens). */
+    async choose(id, index, by, ack) {
+        const now = this.deps.now();
+        const result = this.deps.store.consume(id, index, by.username, now);
+        if (!result.ok) {
+            ack?.(result.reason === "used" ? t("reply_buttons.answered") : t("reply_buttons.closed"));
+            if (result.reason === "expired" && result.set)
+                void this.settle(result.set);
+            return false;
+        }
+        let delivered = false;
+        this.inFlight.add(id);
+        try {
+            delivered = await this.deps.deliver(result.set, result.button, by);
+        }
+        catch (err) {
+            this.deps.logger.warn({ err: err.message, set: id }, "Reply-button choice could not be delivered");
+        }
+        finally {
+            this.inFlight.delete(id);
+        }
+        if (!delivered) {
+            this.deps.store.release(id, now);
+            ack?.(t("reply_buttons.closed"));
+            return false;
+        }
+        this.deps.store.markDelivered(id, this.deps.now());
+        ack?.(t("reply_buttons.sent", result.button.label));
+        await this.settle(result.set);
+        return true;
+    }
+    /**
+     * Show how a set ended on its platform message and in the web chat; once. A failed edit is not retried. Ended is: a
+     * delivered choice, an expiry with no claim, or (`closeClaim`) a claim no process is delivering any more.
+     */
+    async settle(set, closeClaim = false) {
+        const fresh = this.deps.store.get(set.id);
+        if (!fresh || fresh.settledAt !== null || fresh.messageId === null)
+            return;
+        const now = this.deps.now();
+        // Invariant (#1500 review r2): an orphan close only closes a set that is STILL claimed and not delivered. A claim
+        // released while a sweep was awaiting another set's edit is open again — re-read here, it is not an orphan.
+        const ended = fresh.deliveredAt !== null || (fresh.consumedAt === null && now >= fresh.expiresAt)
+            || (closeClaim && fresh.consumedAt !== null && fresh.deliveredAt === null && !this.inFlight.has(fresh.id));
+        if (!ended)
+            return; // open, or a claim being delivered
+        this.deps.store.markSettled(fresh.id, now); // first: a concurrent settle does nothing
+        const view = this.view({ ...fresh, settledAt: now }, now);
+        this.deps.publish(fresh.instance, view);
+        const adapter = this.deps.adapterFor(fresh.adapterId);
+        if (!adapter?.settleReplyButtons)
+            return;
+        const outcome = view.state === "chosen" ? { chosenIndex: view.chosen, by: view.by ?? "" } : { expired: true };
+        try {
+            await adapter.settleReplyButtons(fresh.chatId, fresh.messageId, fresh.threadId || undefined, view.labels, outcome);
+        }
+        catch (err) {
+            this.deps.logger.warn({ err: err.message, set: fresh.id }, "Could not update a reply's buttons on the platform");
+        }
+    }
+    /**
+     * Settle what has ended (an expiry, or a choice whose message was not updated before a restart), then re-arm. A
+     * claim no one in this process is delivering was left by a process that stopped mid-delivery: whether the agent got
+     * it is unknown, so it is closed as expired ("reply in text") rather than reopened — reopening could deliver a
+     * second choice.
+     */
+    async sweep() {
+        const now = this.deps.now();
+        for (const set of this.deps.store.unsettled(now))
+            await this.settle(set);
+        for (const set of this.deps.store.undeliveredClaims())
+            if (!this.inFlight.has(set.id))
+                await this.settle(set, true);
+        this.deps.store.prune(now - KEEP_SETTLED_MS);
+        this.arm();
+    }
+    /** One timer, for the next expiry. A wall-clock jump makes it fire early or late; the sweep re-reads the clock. */
+    arm() {
+        if (this.stopped)
+            return;
+        if (this.timer !== null)
+            this.deps.clearTimer(this.timer);
+        this.timer = null;
+        const next = this.deps.store.nextExpiry(this.deps.now());
+        if (next === null)
+            return;
+        const delay = Math.min(MAX_TIMER_MS, Math.max(1000, next - this.deps.now()));
+        this.timer = this.deps.setTimer(() => { this.timer = null; void this.sweep(); }, delay);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null)
+            this.deps.clearTimer(this.timer);
+        this.timer = null;
+    }
+}
+//# sourceMappingURL=reply-buttons-controller.js.map

package/dist/reply-buttons-controller.js.map

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

package/dist/reply-buttons.d.ts

@@ -0,0 +1,113 @@
+export declare const REPLY_BUTTONS_MAX = 10;
+/** Discord's limit per label (the strictest of the three); counted in UTF-16 units, as Discord counts. */
+export declare const REPLY_BUTTON_LABEL_MAX = 80;
+export declare const REPLY_BUTTON_VALUE_MAX = 200;
+export declare const REPLY_BUTTON_TTL_MS: number;
+export declare const REPLY_BUTTON_PREFIX = "rb:";
+export interface ReplyButton {
+    label: string;
+    value: string;
+}
+/**
+ * The reply's `buttons`, checked: null when there are none, `{ error }` when they cannot be sent as given.
+ * Labels are plain text on every surface; a newline or control character is refused rather than rewritten.
+ */
+export declare function parseReplyButtons(raw: unknown, args: {
+    text?: unknown;
+    stickers?: unknown;
+}): {
+    buttons: ReplyButton[];
+} | {
+    error: string;
+} | null;
+export declare function newReplyButtonsId(): string;
+/** What a platform carries for one button: an unguessable set id and the button's index — never its label or value. */
+export declare function replyButtonCallback(id: string, index: number): string;
+export declare function parseReplyButtonCallback(data: string): {
+    id: string;
+    index: number;
+} | null;
+/** The message the agent receives for a click: an ordinary inbound line, marked as a button. */
+export declare function replyButtonClickText(b: ReplyButton): string;
+/** Where buttons cannot be shown: the choices as text, so the question can still be answered by writing back. */
+export declare function replyButtonsFallbackText(buttons: readonly ReplyButton[]): string;
+/**
+ * Is a platform click on this set's own message? Same adapter, same message id, and the click's chat or thread is the
+ * set's chat or thread (Discord reports a click as guild + channel, Telegram as chat + topic; a reply recorded its
+ * chat_id and thread). A callback copied onto another message, or replayed from another chat, is not.
+ */
+export declare function replyButtonsClickPlace(set: ReplyButtonSet, at: {
+    adapterId: string;
+    chatId: string;
+    threadId?: string;
+    messageId: string;
+}): boolean;
+export interface ReplyButtonSet {
+    id: string;
+    instance: string;
+    /** The world (adapter id) it was sent through, or "web" on a web-only fleet. */
+    adapterId: string;
+    chatId: string;
+    threadId: string;
+    /** The platform message carrying the buttons; null while the send is in flight. */
+    messageId: string | null;
+    buttons: ReplyButton[];
+    createdAt: number;
+    expiresAt: number;
+    consumedAt: number | null;
+    chosenIndex: number | null;
+    chosenBy: string | null;
+    /**
+     * When the agent was given the choice (#1500 review). A claim (consumedAt) is not a choice until then: only a
+     * delivered one is shown as chosen; one that cannot be delivered is released.
+     */
+    deliveredAt: number | null;
+    /** Set when the platform message was updated to its final state (chosen / expired). */
+    settledAt: number | null;
+}
+export type ConsumeResult = {
+    ok: true;
+    set: ReplyButtonSet;
+    button: ReplyButton;
+} | {
+    ok: false;
+    reason: "missing" | "pending" | "used" | "expired";
+    set?: ReplyButtonSet;
+};
+/** The button sets, in `<dataDir>/reply-buttons.db`. Wall-clock instants: an expiry is a calendar time that must hold across restarts. */
+export declare class ReplyButtonStore {
+    private db;
+    constructor(path: string);
+    close(): void;
+    /** Before the send: the set exists, unbound (a click cannot match it until the platform message is known). */
+    create(set: Pick<ReplyButtonSet, "id" | "instance" | "adapterId" | "chatId" | "threadId" | "buttons">, now: number): ReplyButtonSet;
+    /** After the send: the message the buttons are on. Only an unbound set can be bound. */
+    bind(id: string, messageId: string): boolean;
+    /** A send that failed: the set never existed for anyone. */
+    remove(id: string): void;
+    get(id: string): ReplyButtonSet | null;
+    /**
+     * One click, already placed on this set's message by the caller (replyButtonsClickPlace). The first permitted click
+     * consumes the whole set, atomically: of two clicks racing here only one changes the row.
+     */
+    consume(id: string, index: number, by: string, now: number): ConsumeResult;
+    /** The claim reached the agent: from now on it is the choice. */
+    markDelivered(id: string, now: number): void;
+    /** A consumed click that could not reach the agent: the set is open again (only that click's own claim is undone). */
+    release(id: string, consumedAt: number): void;
+    /** Claims never delivered nor released — in flight now, or left by a process that stopped mid-delivery. */
+    undeliveredClaims(): ReplyButtonSet[];
+    /** The platform message shows the final state now (chosen or expired). */
+    markSettled(id: string, now: number): void;
+    /**
+     * Sets that ended and whose message does not show it yet: a delivered choice, or an expiry nobody claimed. A claim
+     * still being delivered is neither (#1500 review): it may yet be released.
+     */
+    unsettled(now: number): ReplyButtonSet[];
+    /** The next expiry still to come, for the one sweep timer. */
+    nextExpiry(now: number): number | null;
+    /** Sets on these messages, for the web chat's view of a reply's buttons. */
+    forMessages(instance: string, messageIds: readonly string[]): ReplyButtonSet[];
+    /** Settled sets older than `before` are history the store no longer needs. */
+    prune(before: number): number;
+}

package/dist/reply-buttons.js

@@ -0,0 +1,208 @@
+/**
+ * #1266: buttons on an agent's reply — the same choice in the web chat, on Telegram (inline keyboard) and on Discord
+ * (message components). Design: https://github.com/songsid/AgEnD/issues/1266#issuecomment-6082375631
+ *
+ * - A reply's `buttons` are checked here before anything is sent (the reply tool's arguments are not validated by
+ *   the MCP schema at run time).
+ * - Each button set is one row of a small SQLite store, so it outlives a restart. The platform sees only
+ *   `rb:<32 hex>:<index>`; the labels and values stay here.
+ * - A click is consumed once for the whole set (`UPDATE … WHERE consumed_at IS NULL`), only on the exact message the
+ *   set was delivered on, and only before it expires: a replayed or late click changes nothing.
+ */
+import Database from "better-sqlite3";
+import { randomBytes } from "node:crypto";
+export const REPLY_BUTTONS_MAX = 10;
+/** Discord's limit per label (the strictest of the three); counted in UTF-16 units, as Discord counts. */
+export const REPLY_BUTTON_LABEL_MAX = 80;
+export const REPLY_BUTTON_VALUE_MAX = 200;
+export const REPLY_BUTTON_TTL_MS = 24 * 60 * 60 * 1000;
+export const REPLY_BUTTON_PREFIX = "rb:";
+/**
+ * The reply's `buttons`, checked: null when there are none, `{ error }` when they cannot be sent as given.
+ * Labels are plain text on every surface; a newline or control character is refused rather than rewritten.
+ */
+export function parseReplyButtons(raw, args) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (!Array.isArray(raw))
+        return { error: "buttons must be a list of { label, value? }" };
+    if (raw.length === 0)
+        return null;
+    if (raw.length > REPLY_BUTTONS_MAX)
+        return { error: `at most ${REPLY_BUTTONS_MAX} buttons on one reply (${raw.length} given)` };
+    if (typeof args.text !== "string" || !args.text.trim())
+        return { error: "buttons need text: they sit on the reply's message" };
+    if (Array.isArray(args.stickers) && args.stickers.length)
+        return { error: "buttons and stickers cannot go on one reply: send the stickers in another reply" };
+    const out = [];
+    const seen = new Set();
+    for (const [i, b] of raw.entries()) {
+        if (!b || typeof b !== "object" || Array.isArray(b))
+            return { error: `buttons[${i}] must be { label, value? }` };
+        const { label, value } = b;
+        if (typeof label !== "string" || !label.trim())
+            return { error: `buttons[${i}].label must be non-empty text` };
+        if (label.length > REPLY_BUTTON_LABEL_MAX)
+            return { error: `buttons[${i}].label is ${label.length} characters; at most ${REPLY_BUTTON_LABEL_MAX}` };
+        // eslint-disable-next-line no-control-regex
+        if (/[\u0000-\u001f\u007f]/.test(label))
+            return { error: `buttons[${i}].label must be one line of text` };
+        if (value !== undefined && typeof value !== "string")
+            return { error: `buttons[${i}].value must be text` };
+        if (typeof value === "string" && value.length > REPLY_BUTTON_VALUE_MAX)
+            return { error: `buttons[${i}].value is ${value.length} characters; at most ${REPLY_BUTTON_VALUE_MAX}` };
+        const trimmed = label.trim();
+        if (seen.has(trimmed))
+            return { error: `buttons[${i}].label "${trimmed}" is used twice` };
+        seen.add(trimmed);
+        out.push({ label: trimmed, value: typeof value === "string" && value !== "" ? value : trimmed });
+    }
+    return { buttons: out };
+}
+export function newReplyButtonsId() { return randomBytes(16).toString("hex"); }
+/** What a platform carries for one button: an unguessable set id and the button's index — never its label or value. */
+export function replyButtonCallback(id, index) { return `${REPLY_BUTTON_PREFIX}${id}:${index}`; }
+export function parseReplyButtonCallback(data) {
+    const m = /^rb:([0-9a-f]{32}):(\d{1,2})$/.exec(data);
+    if (!m)
+        return null;
+    const index = Number(m[2]);
+    return index < REPLY_BUTTONS_MAX ? { id: m[1], index } : null;
+}
+/** The message the agent receives for a click: an ordinary inbound line, marked as a button. */
+export function replyButtonClickText(b) {
+    return b.value === b.label ? `[button] ${b.label}` : `[button] ${b.label} (value: ${b.value})`;
+}
+/** Where buttons cannot be shown: the choices as text, so the question can still be answered by writing back. */
+export function replyButtonsFallbackText(buttons) {
+    return `Options: ${buttons.map((b, i) => `${i + 1}) ${b.label}`).join("  ")} — reply with your choice.`;
+}
+/**
+ * Is a platform click on this set's own message? Same adapter, same message id, and the click's chat or thread is the
+ * set's chat or thread (Discord reports a click as guild + channel, Telegram as chat + topic; a reply recorded its
+ * chat_id and thread). A callback copied onto another message, or replayed from another chat, is not.
+ */
+export function replyButtonsClickPlace(set, at) {
+    if (set.messageId === null || at.adapterId !== set.adapterId || at.messageId !== set.messageId)
+        return false;
+    const places = [set.chatId, set.threadId].filter(Boolean);
+    return [at.chatId, at.threadId].some(v => !!v && places.includes(v));
+}
+const fromRow = (r) => ({
+    id: r.id, instance: r.instance, adapterId: r.adapter_id, chatId: r.chat_id, threadId: r.thread_id, messageId: r.message_id,
+    buttons: JSON.parse(r.buttons), createdAt: r.created_at, expiresAt: r.expires_at, consumedAt: r.consumed_at,
+    chosenIndex: r.chosen_index, chosenBy: r.chosen_by, deliveredAt: r.delivered_at ?? null, settledAt: r.settled_at,
+});
+/** The button sets, in `<dataDir>/reply-buttons.db`. Wall-clock instants: an expiry is a calendar time that must hold across restarts. */
+export class ReplyButtonStore {
+    db;
+    constructor(path) {
+        this.db = new Database(path);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("busy_timeout = 5000");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS reply_buttons (
+        id TEXT PRIMARY KEY,
+        instance TEXT NOT NULL,
+        adapter_id TEXT NOT NULL,
+        chat_id TEXT NOT NULL,
+        thread_id TEXT NOT NULL DEFAULT '',
+        message_id TEXT,
+        buttons TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        consumed_at INTEGER,
+        chosen_index INTEGER,
+        chosen_by TEXT,
+        settled_at INTEGER,
+        delivered_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_reply_buttons_open ON reply_buttons(settled_at, expires_at);
+    `);
+        const columns = this.db.prepare("PRAGMA table_info(reply_buttons)").all().map(c => c.name);
+        if (!columns.includes("delivered_at"))
+            this.db.exec("ALTER TABLE reply_buttons ADD COLUMN delivered_at INTEGER");
+    }
+    close() { this.db.close(); }
+    /** Before the send: the set exists, unbound (a click cannot match it until the platform message is known). */
+    create(set, now) {
+        this.db.prepare(`INSERT INTO reply_buttons (id, instance, adapter_id, chat_id, thread_id, buttons, created_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(set.id, set.instance, set.adapterId, set.chatId, set.threadId ?? "", JSON.stringify(set.buttons), now, now + REPLY_BUTTON_TTL_MS);
+        return this.get(set.id);
+    }
+    /** After the send: the message the buttons are on. Only an unbound set can be bound. */
+    bind(id, messageId) {
+        return this.db.prepare("UPDATE reply_buttons SET message_id = ? WHERE id = ? AND message_id IS NULL").run(messageId, id).changes === 1;
+    }
+    /** A send that failed: the set never existed for anyone. */
+    remove(id) { this.db.prepare("DELETE FROM reply_buttons WHERE id = ?").run(id); }
+    get(id) {
+        const r = this.db.prepare("SELECT * FROM reply_buttons WHERE id = ?").get(id);
+        return r ? fromRow(r) : null;
+    }
+    /**
+     * One click, already placed on this set's message by the caller (replyButtonsClickPlace). The first permitted click
+     * consumes the whole set, atomically: of two clicks racing here only one changes the row.
+     */
+    consume(id, index, by, now) {
+        const set = this.get(id);
+        if (!set)
+            return { ok: false, reason: "missing" };
+        if (set.messageId === null)
+            return { ok: false, reason: "pending", set };
+        if (set.consumedAt !== null)
+            return { ok: false, reason: "used", set };
+        if (now >= set.expiresAt)
+            return { ok: false, reason: "expired", set };
+        const button = set.buttons[index];
+        if (!button)
+            return { ok: false, reason: "missing", set };
+        const won = this.db.prepare(`UPDATE reply_buttons SET consumed_at = ?, chosen_index = ?, chosen_by = ?
+      WHERE id = ? AND consumed_at IS NULL AND message_id IS NOT NULL AND expires_at > ?`).run(now, index, by, id, now).changes === 1;
+        const after = this.get(id);
+        return won ? { ok: true, set: after, button } : { ok: false, reason: after.consumedAt !== null ? "used" : "expired", set: after };
+    }
+    /** The claim reached the agent: from now on it is the choice. */
+    markDelivered(id, now) {
+        this.db.prepare("UPDATE reply_buttons SET delivered_at = ? WHERE id = ? AND consumed_at IS NOT NULL AND delivered_at IS NULL").run(now, id);
+    }
+    /** A consumed click that could not reach the agent: the set is open again (only that click's own claim is undone). */
+    release(id, consumedAt) {
+        this.db.prepare(`UPDATE reply_buttons SET consumed_at = NULL, chosen_index = NULL, chosen_by = NULL
+      WHERE id = ? AND consumed_at = ? AND delivered_at IS NULL AND settled_at IS NULL`).run(id, consumedAt);
+    }
+    /** Claims never delivered nor released — in flight now, or left by a process that stopped mid-delivery. */
+    undeliveredClaims() {
+        return this.db.prepare(`SELECT * FROM reply_buttons WHERE settled_at IS NULL AND message_id IS NOT NULL
+      AND consumed_at IS NOT NULL AND delivered_at IS NULL ORDER BY created_at, id`).all().map(fromRow);
+    }
+    /** The platform message shows the final state now (chosen or expired). */
+    markSettled(id, now) { this.db.prepare("UPDATE reply_buttons SET settled_at = ? WHERE id = ? AND settled_at IS NULL").run(now, id); }
+    /**
+     * Sets that ended and whose message does not show it yet: a delivered choice, or an expiry nobody claimed. A claim
+     * still being delivered is neither (#1500 review): it may yet be released.
+     */
+    unsettled(now) {
+        return this.db.prepare(`SELECT * FROM reply_buttons WHERE settled_at IS NULL AND message_id IS NOT NULL
+      AND (delivered_at IS NOT NULL OR (consumed_at IS NULL AND expires_at <= ?))`).all(now).map(fromRow);
+    }
+    /** The next expiry still to come, for the one sweep timer. */
+    nextExpiry(now) {
+        const r = this.db.prepare(`SELECT MIN(expires_at) AS t FROM reply_buttons WHERE settled_at IS NULL AND consumed_at IS NULL
+      AND message_id IS NOT NULL AND expires_at > ?`).get(now);
+        return r.t ?? null;
+    }
+    /** Sets on these messages, for the web chat's view of a reply's buttons. */
+    forMessages(instance, messageIds) {
+        if (!messageIds.length)
+            return [];
+        const rows = this.db.prepare(`SELECT * FROM reply_buttons WHERE instance = ? AND message_id IN (${messageIds.map(() => "?").join(",")})`)
+            .all(instance, ...messageIds);
+        return rows.map(fromRow);
+    }
+    /** Settled sets older than `before` are history the store no longer needs. */
+    prune(before) {
+        return this.db.prepare("DELETE FROM reply_buttons WHERE settled_at IS NOT NULL AND settled_at < ?").run(before).changes;
+    }
+}
+//# sourceMappingURL=reply-buttons.js.map

package/dist/reply-buttons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply-buttons.js","sourceRoot":"","sources":["../src/reply-buttons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,0GAA0G;AAC1G,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAIzC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,IAA4C;IAC1F,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,6CAA6C,EAAE,CAAC;IACzF,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,GAAG,CAAC,MAAM,GAAG,iBAAiB;QAAE,OAAO,EAAE,KAAK,EAAE,WAAW,iBAAiB,0BAA0B,GAAG,CAAC,MAAM,SAAS,EAAE,CAAC;IAChI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC;IAC/H,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,iFAAiF,EAAE,CAAC;IAC9J,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,6BAA6B,EAAE,CAAC;QACjH,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAA4B,CAAC;QACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,gCAAgC,EAAE,CAAC;QAC/G,IAAI,KAAK,CAAC,MAAM,GAAG,sBAAsB;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,cAAc,KAAK,CAAC,MAAM,wBAAwB,sBAAsB,EAAE,EAAE,CAAC;QACpJ,4CAA4C;QAC5C,IAAI,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,kCAAkC,EAAE,CAAC;QAC1G,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,sBAAsB,EAAE,CAAC;QAC3G,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,sBAAsB;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,cAAc,KAAK,CAAC,MAAM,wBAAwB,sBAAsB,EAAE,EAAE,CAAC;QACjL,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,YAAY,OAAO,iBAAiB,EAAE,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iBAAiB,KAAa,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvF,uHAAuH;AACvH,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,KAAa,IAAY,OAAO,GAAG,mBAAmB,GAAG,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;AACzH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,CAAC,GAAG,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,KAAK,GAAG,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,oBAAoB,CAAC,CAAc;IACjD,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,KAAK,GAAG,CAAC;AACjG,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,wBAAwB,CAAC,OAA+B;IACtE,OAAO,YAAY,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,CAAC;AAC1G,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAmB,EAAE,EAA+E;IACzI,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,EAAE,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7G,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAmCD,MAAM,OAAO,GAAG,CAAC,CAAM,EAAkB,EAAE,CAAC,CAAC;IAC3C,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU;IAC1H,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAkB,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC,WAAW;IAC5H,WAAW,EAAE,CAAC,CAAC,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU;CACjH,CAAC,CAAC;AAEH,0IAA0I;AAC1I,MAAM,OAAO,gBAAgB;IACnB,EAAE,CAAoB;IAC9B,YAAY,IAAY;QACtB,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;KAkBZ,CAAC,CAAC;QACH,MAAM,OAAO,GAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC,GAAG,EAA8B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxH,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACnH,CAAC;IACD,KAAK,KAAW,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAElC,8GAA8G;IAC9G,MAAM,CAAC,GAA8F,EAAE,GAAW;QAChH,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;sCACkB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,mBAAmB,CAAC,CAAC;QAC1K,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;IAC3B,CAAC;IACD,wFAAwF;IACxF,IAAI,CAAC,EAAU,EAAE,SAAiB;QAChC,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,6EAA6E,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC;IACzI,CAAC;IACD,4DAA4D;IAC5D,MAAM,CAAC,EAAU,IAAU,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,wCAAwC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/F,GAAG,CAAC,EAAU;QACZ,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,0CAA0C,CAAC,CAAC,GAAG,CAAC,EAAE,CAAoB,CAAC;QACjG,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,EAAU,EAAE,KAAa,EAAE,EAAU,EAAE,GAAW;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAClD,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;QACzE,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QACvE,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;QACvE,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;yFACyD,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC;QAClI,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;QAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACpI,CAAC;IACD,iEAAiE;IACjE,aAAa,CAAC,EAAU,EAAE,GAAW;QACnC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,6GAA6G,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9I,CAAC;IACD,sHAAsH;IACtH,OAAO,CAAC,EAAU,EAAE,UAAkB;QACpC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;uFACmE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAC3G,CAAC;IACD,2GAA2G;IAC3G,iBAAiB;QACf,OAAQ,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;mFACuD,CAAC,CAAC,GAAG,EAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChH,CAAC;IACD,0EAA0E;IAC1E,WAAW,CAAC,EAAU,EAAE,GAAW,IAAU,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,6EAA6E,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3J;;;OAGG;IACH,SAAS,CAAC,GAAW;QACnB,OAAQ,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;kFACsD,CAAC,CAAC,GAAG,CAAC,GAAG,CAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClH,CAAC;IACD,8DAA8D;IAC9D,UAAU,CAAC,GAAW;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;oDACsB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAyB,CAAC;QACnF,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACrB,CAAC;IACD,4EAA4E;IAC5E,WAAW,CAAC,QAAgB,EAAE,UAA6B;QACzD,IAAI,CAAC,UAAU,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,qEAAqE,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;aACtI,GAAG,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAU,CAAC;QACzC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IACD,8EAA8E;IAC9E,KAAK,CAAC,MAAc;QAClB,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,2EAA2E,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;IAC1H,CAAC;CACF"}

package/dist/reply-dedup.js

@@ -28,7 +28,9 @@ import { createHash } from "node:crypto";
 export function replyDedupText(args) {
     const text = String(args.text ?? "");
     const stickers = Array.isArray(args.stickers) ? args.stickers.map(String) : [];
-    return stickers.length ? `${text}\u0000stickers:${stickers.join(",")}` : text;
+    const keyed = stickers.length ? `${text}\u0000stickers:${stickers.join(",")}` : text;
+    // #1266: the same text with other buttons is another reply.
+    return Array.isArray(args.buttons) && args.buttons.length ? `${keyed}\u0000buttons:${JSON.stringify(args.buttons)}` : keyed;
 }
 export class ReplyDeduper {
     inFlightTimeoutMs;