@copilotkit/channels-discord 0.0.2

package/dist/message-stream.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-Discord-message streaming text state machine.
+ *
+ * Wraps a single posted Discord message and lets callers feed it the growing
+ * text buffer of a streaming reply. Edits are throttled (Discord's edit rate
+ * limit is ~5 edits/5s per channel, tighter than Slack's ~1/sec per message)
+ * and *serialised* through a per-message promise queue so concurrent updates
+ * can't race — a hazard the previous implementation hit, where End-triggered
+ * flush of "ALPHA" could be overtaken by an in-flight flush of "AL" and the
+ * final state read "AL".
+ *
+ * Nothing in this file knows about AG-UI events or discord.js — it's a
+ * pure Discord-side primitive: "give me text, I'll keep one Discord message
+ * in sync with it."
+ */
+export interface MessageStreamConfig {
+    /** Function that actually writes `text` to Discord (e.g. message.edit). */
+    update: (text: string) => Promise<void>;
+    /** Minimum gap between consecutive flushes, in ms (defaults to 1100). */
+    minIntervalMs?: number;
+}
+export declare class MessageStream {
+    private buffer;
+    private posted;
+    private queue;
+    private lastFlushedAt;
+    private flushTimer;
+    private readonly minIntervalMs;
+    private readonly update;
+    constructor(config: MessageStreamConfig);
+    /** Replace the in-flight buffer (callers pass the accumulated text). */
+    append(text: string): void;
+    /**
+     * Mark the stream done. Cancels any pending throttled flush, enqueues a
+     * final flush, and resolves once the entire queue (including the final
+     * flush and anything previously in flight) has drained.
+     *
+     * After this resolves, the Discord message reflects the final buffer state.
+     */
+    finish(): Promise<void>;
+    private scheduleFlush;
+    private enqueueFlush;
+    private flushNow;
+}
+//# sourceMappingURL=message-stream.d.ts.map

package/dist/message-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-stream.d.ts","sourceRoot":"","sources":["../src/message-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAE7C,MAAM,EAAE,mBAAmB;IAKvC,wEAAwE;IACxE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM1B;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAS7B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,YAAY;YAIN,QAAQ;CAwBvB"}

package/dist/message-stream.js

@@ -0,0 +1,76 @@
+const DEFAULT_MIN_INTERVAL_MS = 1100;
+export class MessageStream {
+    buffer = "";
+    posted = "";
+    queue = Promise.resolve();
+    lastFlushedAt = 0;
+    flushTimer;
+    minIntervalMs;
+    update;
+    constructor(config) {
+        this.update = config.update;
+        this.minIntervalMs = config.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+    }
+    /** Replace the in-flight buffer (callers pass the accumulated text). */
+    append(text) {
+        if (text === this.buffer)
+            return;
+        this.buffer = text;
+        this.scheduleFlush();
+    }
+    /**
+     * Mark the stream done. Cancels any pending throttled flush, enqueues a
+     * final flush, and resolves once the entire queue (including the final
+     * flush and anything previously in flight) has drained.
+     *
+     * After this resolves, the Discord message reflects the final buffer state.
+     */
+    async finish() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        this.enqueueFlush();
+        await this.queue;
+    }
+    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();
+        }, delay);
+    }
+    enqueueFlush() {
+        this.queue = this.queue.then(() => this.flushNow());
+    }
+    async flushNow() {
+        if (this.buffer === this.posted)
+            return;
+        const text = this.buffer;
+        try {
+            await this.update(text);
+            // Only mark `text` as delivered once the edit actually succeeds. If we
+            // marked it before the await and update() threw, the guard above would
+            // treat the failed text as posted — and a final failed flush (via
+            // finish() with no further appends) would be lost forever. Assigning
+            // after success leaves `posted` unchanged on failure so a subsequent
+            // flush re-attempts the same buffer.
+            this.posted = text;
+        }
+        catch (err) {
+            // Rate-limit (429) edits are already handled by discord.js with
+            // automatic retry (honoring Retry-After). If we still land here the
+            // edit genuinely failed — swallow it: a single failed edit shouldn't
+            // sink the stream, and future appends retry with the latest buffer.
+            console.error("[message-stream] update failed:", err);
+        }
+        finally {
+            // Set lastFlushedAt *after* the update returns so the throttle
+            // measures wall-clock time between completions, not starts.
+            this.lastFlushedAt = Date.now();
+        }
+    }
+}

package/dist/message-stream.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=message-stream.test.d.ts.map

package/dist/message-stream.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-stream.test.d.ts","sourceRoot":"","sources":["../src/message-stream.test.ts"],"names":[],"mappings":""}

package/dist/message-stream.test.js

@@ -0,0 +1,162 @@
+import { describe, it, expect } from "vitest";
+import { MessageStream } from "./message-stream.js";
+/** A fake Discord `message.edit` that records every call in order and lets the
+ *  test control how long each takes — useful for proving the in-flight /
+ *  finish race that bit the original implementation can't happen here. */
+function makeFakeDiscord(updateDurationMs = 0) {
+    const calls = [];
+    let started = 0;
+    let finished = 0;
+    const update = async (text) => {
+        started++;
+        if (updateDurationMs > 0) {
+            await new Promise((r) => setTimeout(r, updateDurationMs));
+        }
+        finished++;
+        calls.push({ text, finishedAt: Date.now() });
+    };
+    return {
+        update,
+        calls,
+        get inFlight() {
+            return started - finished;
+        },
+    };
+}
+describe("MessageStream", () => {
+    it("flushes the final buffer on finish() even when end races an in-flight update", async () => {
+        // Reproduces the ALPHA → AL bug: a slow message.edit for "AL" is in
+        // flight when the stream finishes with "ALPHA". The old implementation
+        // could let the slow "AL" update overwrite "ALPHA" because message.edit
+        // calls weren't serialised. With the queue, finish() must observe the
+        // final buffer regardless of in-flight state.
+        const discord = makeFakeDiscord(50);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 0,
+        });
+        stream.append("A");
+        stream.append("AL");
+        // Let the timer fire and the first flush kick off (in-flight)
+        await new Promise((r) => setTimeout(r, 5));
+        expect(discord.inFlight).toBeGreaterThanOrEqual(0); // best effort
+        stream.append("ALP");
+        stream.append("ALPH");
+        stream.append("ALPHA");
+        await stream.finish();
+        expect(discord.calls.length).toBeGreaterThan(0);
+        // The LAST message.edit — i.e. the final state of the Discord message — must be ALPHA
+        expect(discord.calls.at(-1)?.text).toBe("ALPHA");
+        // And no concurrent updates were ever in flight (queue invariant)
+        expect(discord.inFlight).toBe(0);
+    });
+    it("never has more than one update in flight at a time", async () => {
+        const discord = makeFakeDiscord(20);
+        let maxInFlight = 0;
+        const sampler = setInterval(() => {
+            if (discord.inFlight > maxInFlight)
+                maxInFlight = discord.inFlight;
+        }, 1);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 0,
+        });
+        for (let i = 1; i <= 20; i++) {
+            stream.append("x".repeat(i));
+            await new Promise((r) => setTimeout(r, 2));
+        }
+        await stream.finish();
+        clearInterval(sampler);
+        expect(maxInFlight).toBeLessThanOrEqual(1);
+    });
+    it("throttles flushes to roughly minIntervalMs between completions", async () => {
+        const discord = makeFakeDiscord(0);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 1100,
+        });
+        const start = Date.now();
+        for (let i = 0; i < 10; i++) {
+            stream.append(`buf${i}`);
+            await new Promise((r) => setTimeout(r, 5));
+        }
+        await stream.finish();
+        // 10 rapid appends should NOT have produced 10 message.edit calls; the
+        // throttle should have coalesced them. Exact count varies by timing but
+        // should be well under 10.
+        expect(discord.calls.length).toBeLessThan(10);
+        // Final state must still match the last append
+        expect(discord.calls.at(-1)?.text).toBe("buf9");
+        // And the test ran for at least one throttle window
+        expect(Date.now() - start).toBeGreaterThanOrEqual(0);
+    });
+    it("collapses duplicate appends into zero updates", async () => {
+        const discord = makeFakeDiscord(0);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 0,
+        });
+        stream.append("hello");
+        stream.append("hello");
+        stream.append("hello");
+        await stream.finish();
+        // One actual update, not three
+        expect(discord.calls).toHaveLength(1);
+        expect(discord.calls[0]?.text).toBe("hello");
+    });
+    it("is a no-op when finish() is called before any append", async () => {
+        const discord = makeFakeDiscord(0);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 0,
+        });
+        await stream.finish();
+        expect(discord.calls).toHaveLength(0);
+    });
+    it("coalesces rapid successive append/update calls within the throttle window into fewer underlying update calls and always flushes the final state", async () => {
+        const discord = makeFakeDiscord(0);
+        const stream = new MessageStream({
+            update: discord.update,
+            minIntervalMs: 1100,
+        });
+        // Fire 15 appends very rapidly (every 10ms), well within the 1100ms throttle window
+        for (let i = 1; i <= 15; i++) {
+            stream.append("msg".repeat(i));
+            await new Promise((r) => setTimeout(r, 10));
+        }
+        await stream.finish();
+        // All 15 rapid appends over ~150ms should coalesce to far fewer than 15 calls
+        // (the 1100ms throttle window means at most ~1 intermediate flush in that window)
+        expect(discord.calls.length).toBeLessThan(15);
+        // The final state must always reflect the last appended value
+        expect(discord.calls.at(-1)?.text).toBe("msg".repeat(15));
+        // No concurrent updates were in flight
+        expect(discord.inFlight).toBe(0);
+    });
+    it("retries the final buffer on a subsequent flush when the previous update() failed", async () => {
+        // The previous implementation marked `posted = text` *before* awaiting
+        // update(). If that final update() rejected, the guard treated the failed
+        // text as delivered, so the last segment was lost forever — never retried.
+        // With the fix, `posted` is only set after update() resolves, so a failed
+        // flush leaves the buffer un-posted and the next flush re-sends it.
+        const sent = [];
+        let calls = 0;
+        const update = async (text) => {
+            calls++;
+            if (calls === 1) {
+                // First flush fails (e.g. genuine edit failure after discord.js retries).
+                throw new Error("boom");
+            }
+            sent.push(text);
+        };
+        const stream = new MessageStream({ update, minIntervalMs: 0 });
+        stream.append("FINAL");
+        // First flush attempt rejects; `posted` must stay "" so the buffer is retried.
+        await stream.finish();
+        expect(sent).toHaveLength(0); // first attempt threw, nothing delivered yet
+        // A subsequent flush (here a fresh finish()) must re-attempt the same buffer.
+        await stream.finish();
+        expect(calls).toBe(2);
+        expect(sent).toEqual(["FINAL"]); // the final segment is re-sent after the failure
+    });
+});

package/dist/pending-interactions.d.ts

@@ -0,0 +1,26 @@
+interface LiveInteraction {
+    id: string;
+    deferred?: boolean;
+    replied?: boolean;
+}
+export interface PendingOpts {
+    /** How long before the 3s window we auto-defer (e.g. 2500). */
+    ackBufferMs: number;
+    /** Ack the interaction (deferUpdate for components, deferReply for commands). */
+    defer: (interaction: LiveInteraction) => Promise<void>;
+}
+/** Tracks live discord.js interactions so a handler can open a modal before the adapter acks. */
+export declare class PendingInteractions {
+    private opts;
+    private entries;
+    constructor(opts: PendingOpts);
+    /** Stash a live interaction, arm the auto-defer timer, return its triggerId. */
+    register(interaction: LiveInteraction): string;
+    /** Run `fn` (e.g. showModal) only if still unresponded. Returns whether it ran. */
+    respondWith(triggerId: string, fn: (interaction: LiveInteraction) => Promise<void>): Promise<boolean>;
+    /** After dispatch: ack if the handler never responded. Then forget the entry. */
+    settle(triggerId: string): Promise<void>;
+    private ack;
+}
+export {};
+//# sourceMappingURL=pending-interactions.d.ts.map

package/dist/pending-interactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-interactions.d.ts","sourceRoot":"","sources":["../src/pending-interactions.ts"],"names":[],"mappings":"AAAA,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,KAAK,EAAE,CAAC,WAAW,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,iGAAiG;AACjG,qBAAa,mBAAmB;IAElB,OAAO,CAAC,IAAI;IADxB,OAAO,CAAC,OAAO,CAA4B;gBACvB,IAAI,EAAE,WAAW;IAErC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM;IAS9C,mFAAmF;IAC7E,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,WAAW,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC;IASnB,iFAAiF;IAC3E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAOhC,GAAG;CAUlB"}

package/dist/pending-interactions.js

@@ -0,0 +1,50 @@
+/** Tracks live discord.js interactions so a handler can open a modal before the adapter acks. */
+export class PendingInteractions {
+    opts;
+    entries = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Stash a live interaction, arm the auto-defer timer, return its triggerId. */
+    register(interaction) {
+        const prev = this.entries.get(interaction.id);
+        if (prev?.timer)
+            clearTimeout(prev.timer);
+        const entry = { interaction, responded: false };
+        entry.timer = setTimeout(() => void this.ack(entry), this.opts.ackBufferMs);
+        this.entries.set(interaction.id, entry);
+        return interaction.id;
+    }
+    /** Run `fn` (e.g. showModal) only if still unresponded. Returns whether it ran. */
+    async respondWith(triggerId, fn) {
+        const entry = this.entries.get(triggerId);
+        if (!entry || entry.responded)
+            return false;
+        entry.responded = true;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        await fn(entry.interaction);
+        return true;
+    }
+    /** After dispatch: ack if the handler never responded. Then forget the entry. */
+    async settle(triggerId) {
+        const entry = this.entries.get(triggerId);
+        if (!entry)
+            return;
+        await this.ack(entry);
+        this.entries.delete(triggerId);
+    }
+    async ack(entry) {
+        if (entry.responded)
+            return;
+        entry.responded = true;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        try {
+            await this.opts.defer(entry.interaction);
+        }
+        catch {
+            /* interaction already gone; nothing to do */
+        }
+    }
+}

package/dist/pending-interactions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pending-interactions.test.d.ts.map

package/dist/pending-interactions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-interactions.test.d.ts","sourceRoot":"","sources":["../src/pending-interactions.test.ts"],"names":[],"mappings":""}

package/dist/pending-interactions.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { PendingInteractions } from "./pending-interactions.js";
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+function fakeInteraction() {
+    return {
+        id: "i1",
+        deferred: false,
+        replied: false,
+        deferUpdate: vi.fn(async function () {
+            this.deferred = true;
+        }),
+        showModal: vi.fn(async () => { }),
+    };
+}
+describe("PendingInteractions", () => {
+    it("auto-defers at the deadline when nothing responds", async () => {
+        const reg = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferUpdate(),
+        });
+        const i = fakeInteraction();
+        reg.register(i);
+        await vi.advanceTimersByTimeAsync(2500);
+        expect(i.deferUpdate).toHaveBeenCalledTimes(1);
+    });
+    it("respondWith runs the responder and cancels the deferral", async () => {
+        const reg = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferUpdate(),
+        });
+        const i = fakeInteraction();
+        const tid = reg.register(i);
+        const ok = await reg.respondWith(tid, (live) => live.showModal({}));
+        expect(ok).toBe(true);
+        expect(i.showModal).toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(i.deferUpdate).not.toHaveBeenCalled();
+    });
+    it("respondWith returns false once the interaction was already acked", async () => {
+        const reg = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferUpdate(),
+        });
+        const i = fakeInteraction();
+        const tid = reg.register(i);
+        await vi.advanceTimersByTimeAsync(2500); // auto-defer fires
+        const ok = await reg.respondWith(tid, (live) => live.showModal({}));
+        expect(ok).toBe(false);
+        expect(i.showModal).not.toHaveBeenCalled();
+    });
+    it("settle acks an unresponded interaction immediately (fast handler path)", async () => {
+        const reg = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferUpdate(),
+        });
+        const i = fakeInteraction();
+        const tid = reg.register(i);
+        await reg.settle(tid);
+        expect(i.deferUpdate).toHaveBeenCalledTimes(1);
+    });
+    it("re-registering the same id clears the old timer so defer fires at most once", async () => {
+        const defer = vi.fn(async () => { });
+        const reg = new PendingInteractions({ ackBufferMs: 2500, defer });
+        const i = { id: "dup", deferred: false, replied: false };
+        // Register twice with the same id — simulates a re-registration race
+        reg.register(i);
+        reg.register(i);
+        // Advance past the ackBufferMs — both timers would fire if the first wasn't cleared
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(defer).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/render/budget.d.ts

@@ -0,0 +1,28 @@
+/** Per-element ceilings the Discord API enforces. Degradation is truncate/clamp — never silent drop. */
+export declare const DISCORD_LIMITS: {
+    readonly componentsPerMessage: 40;
+    readonly actionRows: 5;
+    readonly buttonsPerRow: 5;
+    readonly selectOptions: 25;
+    readonly selectPlaceholder: 150;
+    readonly textDisplayChars: 2000;
+    readonly totalTextChars: 4000;
+    readonly buttonLabel: 80;
+    readonly customId: 100;
+    readonly headerText: 256;
+};
+/** Truncate to max chars, appending an ellipsis marker if the input was longer. Never returns >max. */
+export declare function truncateText(text: string, max: number): string;
+/** Clamp an array to max items; return the kept items plus how many overflowed (for an overflow signal). */
+export declare function clampArray<T>(items: readonly T[], max: number): {
+    items: T[];
+    overflow: number;
+};
+/**
+ * Truncate text that may contain ``` code fences, then re-balance: if truncation
+ * left an odd number of fence delimiters (i.e. a fence was cut open), append a
+ * closing fence. The result never exceeds `max` — the closing fence is added by
+ * trimming further if needed so the total stays within budget.
+ */
+export declare function truncateFenced(text: string, max: number): string;
+//# sourceMappingURL=budget.d.ts.map

package/dist/render/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/render/budget.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,eAAO,MAAM,cAAc;;;;;;;;;;;CAWjB,CAAC;AAEX,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAchE"}

package/dist/render/budget.js

@@ -0,0 +1,49 @@
+/** Per-element ceilings the Discord API enforces. Degradation is truncate/clamp — never silent drop. */
+export const DISCORD_LIMITS = {
+    componentsPerMessage: 40, // total components (nested counted) in a Components V2 message
+    actionRows: 5, // action rows per message
+    buttonsPerRow: 5, // buttons per action row
+    selectOptions: 25, // options per string select
+    selectPlaceholder: 150, // chars per select placeholder
+    textDisplayChars: 2000, // chars per TextDisplay
+    totalTextChars: 4000, // summed text across the message
+    buttonLabel: 80, // button label chars
+    customId: 100, // custom_id chars
+    headerText: 256, // header line chars (TextDisplay with `# ` prefix)
+};
+/** Truncate to max chars, appending an ellipsis marker if the input was longer. Never returns >max. */
+export function truncateText(text, max) {
+    if (text.length <= max)
+        return text;
+    if (max <= 1)
+        return text.slice(0, max);
+    return text.slice(0, max - 1) + "…"; // …
+}
+/** Clamp an array to max items; return the kept items plus how many overflowed (for an overflow signal). */
+export function clampArray(items, max) {
+    if (items.length <= max)
+        return { items: [...items], overflow: 0 };
+    return { items: items.slice(0, max), overflow: items.length - max };
+}
+/**
+ * Truncate text that may contain ``` code fences, then re-balance: if truncation
+ * left an odd number of fence delimiters (i.e. a fence was cut open), append a
+ * closing fence. The result never exceeds `max` — the closing fence is added by
+ * trimming further if needed so the total stays within budget.
+ */
+export function truncateFenced(text, max) {
+    const truncated = truncateText(text, max);
+    const fences = (truncated.match(/```/g) ?? []).length;
+    if (fences % 2 === 0)
+        return truncated;
+    // A fence was left open. Close it, trimming to keep within `max`.
+    const closer = "\n```";
+    // If there's no room for even the closer, we can't append a balanced fence
+    // without exceeding `max`. Fall back to a plain truncation (no fence append)
+    // so the documented "never exceeds max" invariant holds.
+    if (max <= closer.length)
+        return truncateText(text, max);
+    const room = max - closer.length;
+    const body = truncated.length > room ? truncated.slice(0, Math.max(0, room)) : truncated;
+    return body + closer;
+}

package/dist/render/budget.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=budget.test.d.ts.map

package/dist/render/budget.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.test.d.ts","sourceRoot":"","sources":["../../src/render/budget.test.ts"],"names":[],"mappings":""}

package/dist/render/budget.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { DISCORD_LIMITS, truncateText, truncateFenced, clampArray, } from "./budget.js";
+describe("truncateText", () => {
+    it("returns short text unchanged", () => {
+        expect(truncateText("hi", 10)).toBe("hi");
+    });
+    it("truncates with an ellipsis at the limit", () => {
+        const out = truncateText("abcdefghij", 5);
+        expect(out.length).toBeLessThanOrEqual(5);
+        expect(out.endsWith("…")).toBe(true);
+    });
+});
+describe("clampArray", () => {
+    it("keeps all items under the cap and reports zero overflow", () => {
+        expect(clampArray([1, 2, 3], 5)).toEqual({ items: [1, 2, 3], overflow: 0 });
+    });
+    it("clamps over the cap and reports overflow count", () => {
+        expect(clampArray([1, 2, 3, 4], 2)).toEqual({ items: [1, 2], overflow: 2 });
+    });
+});
+describe("truncateFenced", () => {
+    it("leaves balanced-fence text within budget unchanged", () => {
+        const text = "```\nhi\n```";
+        expect(truncateFenced(text, 100)).toBe(text);
+    });
+    it("re-balances an open fence left by truncation", () => {
+        // A fenced table that gets cut mid-content leaves an odd fence count.
+        const text = "```\n| A | B |\n| 1 | 2 |\n| 3 | 4 |\n```";
+        const out = truncateFenced(text, 20);
+        expect(out.length).toBeLessThanOrEqual(20);
+        // Even number of fence delimiters → the block is closed.
+        expect((out.match(/```/g) ?? []).length % 2).toBe(0);
+        expect(out.endsWith("```")).toBe(true);
+    });
+    it("does not add a fence when none is open", () => {
+        const out = truncateFenced("plain text with no fences here", 10);
+        expect(out).not.toContain("```");
+        expect(out.length).toBeLessThanOrEqual(10);
+    });
+    it("never exceeds max even when max is smaller than the closing fence", () => {
+        // An open fence with max=3 (< "\n```".length = 4) must not append a 4-char
+        // closer that overruns max; it falls back to a plain clamp.
+        const longFenced = "```\n" + "a".repeat(50);
+        const out = truncateFenced(longFenced, 3);
+        expect(out.length).toBeLessThanOrEqual(3);
+    });
+});
+describe("DISCORD_LIMITS", () => {
+    it("pins the documented ceilings", () => {
+        expect(DISCORD_LIMITS.componentsPerMessage).toBe(40);
+        expect(DISCORD_LIMITS.customId).toBe(100);
+        expect(DISCORD_LIMITS.buttonsPerRow).toBe(5);
+        expect(DISCORD_LIMITS.actionRows).toBe(5);
+        expect(DISCORD_LIMITS.selectOptions).toBe(25);
+        expect(DISCORD_LIMITS.textDisplayChars).toBe(2000);
+        expect(DISCORD_LIMITS.totalTextChars).toBe(4000);
+        expect(DISCORD_LIMITS.selectPlaceholder).toBe(150);
+    });
+});

package/dist/render/components-v2.d.ts

@@ -0,0 +1,16 @@
+import { ContainerBuilder } from "discord.js";
+import type { BotNode } from "@copilotkit/channels-ui";
+/**
+ * Render a cross-platform IR tree (already expanded + action-bound, so event
+ * props are `{ id }`) into a single top-level Components V2 `ContainerBuilder`.
+ *
+ * Total renderer: unknown intrinsics are skipped, never thrown. Per-element
+ * limits apply via truncate/clamp; nothing is silently dropped.
+ */
+export declare function renderComponents(ir: BotNode[]): ContainerBuilder;
+/** Ready-to-send payload for channel.send / message.edit. */
+export declare function renderDiscordMessage(ir: BotNode[]): {
+    components: ContainerBuilder[];
+    flags: number;
+};
+//# sourceMappingURL=components-v2.d.ts.map

package/dist/render/components-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components-v2.d.ts","sourceRoot":"","sources":["../../src/render/components-v2.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAYjB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAwFvD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAiBhE;AAED,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG;IACnD,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf,CAKA"}