@copilotkit/channels-discord 0.0.2

package/dist/auto-close-streaming.test.d.ts

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

package/dist/auto-close-streaming.test.d.ts.map

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

package/dist/auto-close-streaming.test.js

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "vitest";
+import { autoCloseOpenMarkdown } from "./auto-close-streaming.js";
+describe("autoCloseOpenMarkdown", () => {
+    // ── No-op cases ──────────────────────────────────────────────────
+    it("returns empty string unchanged", () => {
+        expect(autoCloseOpenMarkdown("")).toBe("");
+    });
+    it("returns plain text unchanged", () => {
+        expect(autoCloseOpenMarkdown("just plain text 123")).toBe("just plain text 123");
+    });
+    it("does not modify already-balanced markdown", () => {
+        expect(autoCloseOpenMarkdown("**bold** and *italic* and ~~strike~~")).toBe("**bold** and *italic* and ~~strike~~");
+    });
+    // ── Bold ──────────────────────────────────────────────────────────
+    it("closes an unbalanced **opening — `**hello` → `**hello**`", () => {
+        expect(autoCloseOpenMarkdown("**hello")).toBe("**hello**");
+    });
+    it("does NOT close a `**` with nothing after it", () => {
+        // Just opened — closing would render as `****`, which looks worse.
+        expect(autoCloseOpenMarkdown("hi **")).toBe("hi **");
+    });
+    it("closes `__bold` as `__bold__`", () => {
+        expect(autoCloseOpenMarkdown("__bold")).toBe("__bold__");
+    });
+    // ── Italic ───────────────────────────────────────────────────────
+    it("closes `*italic` → `*italic*`", () => {
+        expect(autoCloseOpenMarkdown("*italic")).toBe("*italic*");
+    });
+    it("closes `_italic` → `_italic_`", () => {
+        expect(autoCloseOpenMarkdown("_italic")).toBe("_italic_");
+    });
+    it("does NOT close a `*` with nothing after it", () => {
+        expect(autoCloseOpenMarkdown("text *")).toBe("text *");
+    });
+    it("closes an open italic `*` that precedes an empty trailing `**` — `*ab**`", () => {
+        // The trailing `**` is empty (just opened) and is dropped, but the
+        // leading `*ab` italic has real content and must still be closed.
+        // Regression: lastIndexOf("*") used to match the `*` inside `**`,
+        // wrongly treating the italic as empty and leaving it unbalanced.
+        expect(autoCloseOpenMarkdown("*ab**")).toBe("*ab***");
+    });
+    it("closes an open underscore-italic `_` that precedes an empty trailing `__` — `_ab__`", () => {
+        expect(autoCloseOpenMarkdown("_ab__")).toBe("_ab___");
+    });
+    // ── Strike ───────────────────────────────────────────────────────
+    it("closes `~~strike` → `~~strike~~`", () => {
+        expect(autoCloseOpenMarkdown("~~strike")).toBe("~~strike~~");
+    });
+    // ── Inline code ──────────────────────────────────────────────────
+    it("closes `` `code `` → `` `code` ``", () => {
+        expect(autoCloseOpenMarkdown("`code")).toBe("`code`");
+    });
+    it("doesn't touch content inside paired inline code", () => {
+        // `code with *stars*` — the stars are inside code, so no italic close.
+        expect(autoCloseOpenMarkdown("`code *stars*` and more")).toBe("`code *stars*` and more");
+    });
+    it("treats unbalanced markers INSIDE inline code as opaque", () => {
+        // `**foo` is inside an unclosed inline → we close the backtick, but
+        // don't try to close the `**` inside code.
+        expect(autoCloseOpenMarkdown("see `**foo")).toBe("see `**foo`");
+    });
+    // ── Fenced code ──────────────────────────────────────────────────
+    it("closes an open fence — adds `\\n```` after the content", () => {
+        const input = "```py\ndef foo():";
+        const out = autoCloseOpenMarkdown(input);
+        expect(out.startsWith(input)).toBe(true);
+        expect(out.trim().endsWith("```")).toBe(true);
+    });
+    it("does NOT close a bare ``` with nothing after it (just opened)", () => {
+        expect(autoCloseOpenMarkdown("```")).toBe("```");
+        expect(autoCloseOpenMarkdown("```py")).toBe("```py"); // language tag alone
+    });
+    it("balanced fences left untouched", () => {
+        const input = "before\n```\ncode\n```\nafter";
+        expect(autoCloseOpenMarkdown(input)).toBe(input);
+    });
+    it("balanced fence + unbalanced markers in surrounding text close correctly", () => {
+        // The fence is paired; the trailing `**hel` outside the fence needs close.
+        const input = "**hel ```code``` more text";
+        const out = autoCloseOpenMarkdown(input);
+        expect(out).toContain("**hel");
+        expect(out).toContain("```code```");
+        expect(out).toContain("**"); // close
+    });
+    it("markers inside paired fences don't count toward balance", () => {
+        // Inside the fence we have `**oops`, but the markdown text is balanced.
+        const input = "```\n**oops never closes\n``` after";
+        expect(autoCloseOpenMarkdown(input)).toBe(input);
+    });
+    // ── Nesting ──────────────────────────────────────────────────────
+    it("closes innermost first — `**bold _italic` → `**bold _italic_**`", () => {
+        expect(autoCloseOpenMarkdown("**bold _italic")).toBe("**bold _italic_**");
+    });
+    it("doesn't double-close already-balanced inner markers", () => {
+        expect(autoCloseOpenMarkdown("**bold _italic_ tail")).toBe("**bold _italic_ tail**");
+    });
+    // ── Stream-evolution: simulate consecutive deltas; the agent's eventual
+    // close should NOT cause double-closes in the produced text. ──
+    it("stream-evolution: agent eventually closes; auto-close adds nothing at that point", () => {
+        const states = [
+            "**h",
+            "**he",
+            "**hel",
+            "**hell",
+            "**hello",
+            "**hello*",
+            "**hello**",
+        ];
+        const out = states.map(autoCloseOpenMarkdown);
+        // Intermediate states are closed
+        expect(out[0]).toBe("**h**");
+        expect(out[4]).toBe("**hello**");
+        // Final state is unchanged (already balanced)
+        expect(out[out.length - 1]).toBe("**hello**");
+    });
+    it("stream-evolution for fenced code: closes mid-stream; goes silent on real close", () => {
+        const states = [
+            "```py\n",
+            "```py\ndef ",
+            "```py\ndef foo():",
+            "```py\ndef foo():\n    pass\n```",
+        ];
+        const out = states.map(autoCloseOpenMarkdown);
+        // First state: just opened — no content yet, don't auto-close
+        expect(out[0]).toBe("```py\n");
+        // Middle states: closed
+        expect(out[1].trim().endsWith("```")).toBe(true);
+        expect(out[2].trim().endsWith("```")).toBe(true);
+        // Final: agent emitted the close, balanced, no change
+        expect(out[3]).toBe(states[3]);
+    });
+    // ── Combined ────────────────────────────────────────────────────
+    it("closes bold before an unclosed fence opener, and closes the fence too", () => {
+        // `**bold ` is open bold then a space; `\`\`\`code\n` opens a fence with
+        // content. We close bold (with closer inserted before the trailing
+        // space, so the space stays adjacent to the fence) and close the fence.
+        const input = "**bold ```py\ndef foo():";
+        const out = autoCloseOpenMarkdown(input);
+        expect(out).toContain("**bold**"); // bold closed before fence
+        expect(out).toContain("def foo():"); // fence content preserved
+        expect(out.trim().endsWith("```")).toBe(true); // fence closed
+    });
+    // ── Sanity: long input ─────────────────────────────────────────
+    it("handles a long buffer with mixed structures", () => {
+        const lots = "**Bold opener** and `code` and *italic* and `unclosed inline";
+        const out = autoCloseOpenMarkdown(lots);
+        expect(out).toBe("**Bold opener** and `code` and *italic* and `unclosed inline`");
+    });
+});

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

@@ -0,0 +1,20 @@
+/**
+ * Discord-platform-universal context entries — knowledge the LLM needs
+ * about Discord itself (tagging procedure, formatting, conversation
+ * model). Apps spread `defaultDiscordContext` into the `context:` config
+ * they pass to `createBot`.
+ *
+ * Each entry is exported individually too so apps can cherry-pick.
+ */
+import type { ContextEntry } from "@copilotkit/channels";
+export declare const discordTaggingContext: ContextEntry;
+export declare const discordFormattingContext: ContextEntry;
+export declare const discordConversationModelContext: ContextEntry;
+/**
+ * The default context entries the SDK ships. Spread into your
+ * `createBot({context: …})`:
+ *
+ *     context: [...defaultDiscordContext, ...myAppContext],
+ */
+export declare const defaultDiscordContext: ContextEntry[];
+//# sourceMappingURL=built-in-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-context.d.ts","sourceRoot":"","sources":["../src/built-in-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,eAAO,MAAM,qBAAqB,EAAE,YAMnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,YAOtC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,YAM7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAAY,EAI/C,CAAC"}

package/dist/built-in-context.js

@@ -0,0 +1,30 @@
+export const discordTaggingContext = {
+    description: "How to tag/mention people in Discord",
+    value: "To mention a user, use <@USER_ID> (numeric id). If you only know a name or " +
+        "handle, call lookup_discord_user to resolve it to an id first, then mention " +
+        "with <@id>. Mention a channel with <#CHANNEL_ID>.",
+};
+export const discordFormattingContext = {
+    description: "Discord message formatting",
+    value: "Use standard Markdown: **bold**, *italic*, `code`, ```fenced``` blocks, > quotes, " +
+        "and # / ## / ### headings. Discord renders NO tables — never output a pipe table; " +
+        "put tabular data in a fenced code block or call the appropriate render tool. " +
+        "Mentions use <@USER_ID> and channels <#CHANNEL_ID>.",
+};
+export const discordConversationModelContext = {
+    description: "The Discord conversation model",
+    value: "Each channel, thread, and DM is one conversation. You reply in the same channel " +
+        "the message arrived in. Use the read-history tool to see prior messages when you " +
+        "need context from earlier in the conversation.",
+};
+/**
+ * The default context entries the SDK ships. Spread into your
+ * `createBot({context: …})`:
+ *
+ *     context: [...defaultDiscordContext, ...myAppContext],
+ */
+export const defaultDiscordContext = [
+    discordTaggingContext,
+    discordFormattingContext,
+    discordConversationModelContext,
+];

package/dist/built-in-context.test.d.ts

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

package/dist/built-in-context.test.d.ts.map

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

package/dist/built-in-context.test.js

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { discordFormattingContext, discordConversationModelContext, discordTaggingContext, defaultDiscordContext, } from "./built-in-context.js";
+describe("defaultDiscordContext", () => {
+    it("bundles the three context entries", () => {
+        expect(defaultDiscordContext).toEqual([
+            discordTaggingContext,
+            discordFormattingContext,
+            discordConversationModelContext,
+        ]);
+    });
+    it("each entry has a description and value", () => {
+        for (const e of defaultDiscordContext) {
+            expect(typeof e.description).toBe("string");
+            expect(e.value.length).toBeGreaterThan(0);
+        }
+    });
+    it("formatting guidance warns there are no tables and gives mention syntax", () => {
+        expect(discordFormattingContext.value).toMatch(/table/i);
+        expect(discordFormattingContext.value).toContain("<@");
+    });
+});

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

@@ -0,0 +1,4 @@
+import type { BotTool } from "@copilotkit/channels";
+export declare const lookupDiscordUserTool: BotTool;
+export declare const defaultDiscordTools: 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":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,qBAAqB,EAAE,OAsBlC,CAAC;AAEH,eAAO,MAAM,mBAAmB,EAAE,OAAO,EAA4B,CAAC"}

package/dist/built-in-tools.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { defineBotTool } from "@copilotkit/channels";
+export const lookupDiscordUserTool = defineBotTool({
+    name: "lookup_discord_user",
+    description: "Resolve a person's name, display name, or handle to a Discord user id and a " +
+        "ready-to-use <@id> mention.",
+    parameters: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe("A name, display name, or handle to resolve."),
+    }),
+    async handler({ query }, { thread }) {
+        let user;
+        try {
+            user = await thread.lookupUser(query);
+        }
+        catch (error) {
+            console.error(`lookup_discord_user failed for "${query}":`, error);
+            return `Couldn't resolve a Discord user for "${query}" (lookup unavailable).`;
+        }
+        if (!user)
+            return `No Discord user found matching "${query}".`;
+        return { id: user.id, name: user.name, mention: `<@${user.id}>` };
+    },
+});
+export const defaultDiscordTools = [lookupDiscordUserTool];

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

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

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

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

package/dist/built-in-tools.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from "vitest";
+import { lookupDiscordUserTool, defaultDiscordTools, } from "./built-in-tools.js";
+describe("lookupDiscordUserTool", () => {
+    it("resolves a query via thread.lookupUser and returns a mention", async () => {
+        const thread = {
+            lookupUser: vi.fn(async () => ({ id: "u9", name: "Ann", handle: "ann" })),
+        };
+        const res = await lookupDiscordUserTool.handler({ query: "ann" }, {
+            thread,
+        });
+        expect(thread.lookupUser).toHaveBeenCalledWith("ann");
+        expect(JSON.stringify(res)).toContain("<@u9>");
+    });
+    it("returns a graceful string when thread.lookupUser rejects", async () => {
+        const thread = {
+            lookupUser: vi.fn(async () => {
+                throw new Error("intent missing");
+            }),
+        };
+        const res = await lookupDiscordUserTool.handler({ query: "ann" }, {
+            thread,
+        });
+        expect(thread.lookupUser).toHaveBeenCalledWith("ann");
+        expect(typeof res).toBe("string");
+        expect(res).toContain("lookup unavailable");
+    });
+    it("is included in defaultDiscordTools", () => {
+        expect(defaultDiscordTools).toContain(lookupDiscordUserTool);
+    });
+});

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

@@ -0,0 +1,94 @@
+/**
+ * Placeholder texts posted for streaming messages: the first chunk shows
+ * "_thinking…_" and later (continuation) chunks show "_…(continued)_" until
+ * real content lands. Exported as a shared const so the producer here and the
+ * history filter in adapter.ts (which excludes the bot's own placeholders from
+ * `read_thread`) never drift apart. The `…` is a real U+2026 ellipsis.
+ */
+export declare const STREAM_PLACEHOLDERS: readonly ["_thinking…_", "_…(continued)_"];
+/**
+ * Discord's HARD per-message content limit is 2000 chars. For longer agent
+ * responses we spread the text over several Discord messages — but the
+ * *chunk boundaries* must be stable once committed (we can't reflow a
+ * sentence into a previous chunk after that chunk has already been posted
+ * to Discord).
+ *
+ * ChunkedMessageStream owns N underlying `MessageStream`s (one per Discord
+ * message). It accepts the full accumulated text on `append()`, decides
+ * where the chunk boundaries are, mints new Discord messages as needed,
+ * and dispatches the right slice to each chunk's stream.
+ *
+ * Boundaries are chosen greedily: once an active chunk exceeds the soft
+ * limit, freeze the boundary at the last newline (or last space) within
+ * the limit; remaining text becomes the next chunk. Boundaries don't
+ * move once frozen, so an already-posted chunk's text never shrinks.
+ */
+export interface ChunkedMessageStreamConfig {
+    /**
+     * Soft per-message char limit used to choose chunk boundaries. Defaults to
+     * 1900 — deliberately below Discord's 2000 hard limit so the per-chunk
+     * `transform` has headroom to grow the text without overflowing. The
+     * transform appends a fence/marker closer (autoCloseOpenMarkdown) and, for
+     * continuation chunks, prepends a re-opener (e.g. "```longlangname\n"); a
+     * chunk sliced to exactly 2000 raw chars would exceed 2000 once transformed
+     * and Discord would reject the edit with BASE_TYPE_MAX_LENGTH.
+     */
+    limit?: number;
+    /** Throttle floor for each underlying stream's message edit. */
+    minIntervalMs?: number;
+    /** Posts a new Discord message with placeholder text; resolves with its id. */
+    postPlaceholder: (text: string) => Promise<string>;
+    /** Updates the Discord message at `id` with `text`. */
+    updateAt: (id: string, text: string) => Promise<void>;
+    /**
+     * Optional transformer for the text *just before* it hits the edit call —
+     * e.g. markdown translation. Applied per-chunk.
+     * Defaults to `discordMarkdown`.
+     */
+    transform?: (text: string) => string;
+}
+export declare class ChunkedMessageStream {
+    private buffer;
+    /** Sorted positions where a chunk ends (= where the next chunk begins). */
+    private boundaries;
+    private streams;
+    /** Serialises new-chunk creation so async postPlaceholder calls don't race. */
+    private setupPromise;
+    /**
+     * Records the first setup-chain failure (e.g. a rejecting `postPlaceholder`).
+     * The chain itself is kept rejection-free via a `.catch` so no interim
+     * unhandled promise rejection is emitted; the stored error is rethrown
+     * deterministically at the next `append`/`finish`.
+     */
+    private setupError;
+    private finished;
+    private readonly limit;
+    private readonly minIntervalMs;
+    private readonly postPlaceholder;
+    private readonly updateAt;
+    private readonly transform;
+    constructor(config: ChunkedMessageStreamConfig);
+    append(fullText: string): void;
+    finish(): Promise<void>;
+    /** Wraps the recorded setup failure with context for surfacing to callers. */
+    private asSetupError;
+    /** Returns the number of Discord messages this stream has 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. Once frozen, a
+     * boundary doesn't move.
+     *
+     * Special case (block-keeps-whole): if the chosen boundary lands INSIDE
+     * an open fenced code block, we try to move the boundary BACK to the
+     * position right before the fence opener, so the *whole* block lives in
+     * the next Discord message rather than being split. The previous chunk
+     * gets shortened (message edit will update it down). Fallback when the
+     * block is too large to fit in one chunk: keep the inside-fence
+     * boundary; the dispatcher will prepend the fence opener to the next
+     * chunk (re-opener path).
+     */
+    private refreezeBoundaries;
+    private ensureStreamsAndDispatch;
+}
+//# sourceMappingURL=chunked-message-stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunked-message-stream.d.ts","sourceRoot":"","sources":["../src/chunked-message-stream.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,4CAA6C,CAAC;AAyC9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,uDAAuD;IACvD,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAM;IACpB,2EAA2E;IAC3E,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,OAAO,CAAuB;IACtC,+EAA+E;IAC/E,OAAO,CAAC,YAAY,CAAoC;IACxD;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAEzC,MAAM,EAAE,0BAA0B;IAQ9C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAmBxB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAe7B,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IAKpB,4EAA4E;IAC5E,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;YA0BZ,wBAAwB;CAwCvC"}

package/dist/chunked-message-stream.js

@@ -0,0 +1,203 @@
+import { MessageStream } from "./message-stream.js";
+import { detectOpenContext, renderContextOpener, } from "./auto-close-streaming.js";
+import { discordMarkdown } from "./markdown.js";
+/** Discord's hard per-message content limit. Edits above this are rejected. */
+const DISCORD_HARD_LIMIT = 2000;
+/**
+ * Placeholder texts posted for streaming messages: the first chunk shows
+ * "_thinking…_" and later (continuation) chunks show "_…(continued)_" until
+ * real content lands. Exported as a shared const so the producer here and the
+ * history filter in adapter.ts (which excludes the bot's own placeholders from
+ * `read_thread`) never drift apart. The `…` is a real U+2026 ellipsis.
+ */
+export const STREAM_PLACEHOLDERS = ["_thinking…_", "_…(continued)_"];
+/**
+ * Soft chunk limit. Sits ~100 chars below the hard limit to leave headroom
+ * for the per-chunk transform, which can both append a closer ("\n```") and
+ * prepend a continuation re-opener ("```longlangname\n").
+ */
+const DEFAULT_LIMIT = 1900;
+/**
+ * Last-resort safety net: guarantee a transformed chunk never exceeds
+ * Discord's hard limit. The 1900-char soft limit is the primary defence;
+ * this clamp only fires in pathological cases (e.g. an enormous re-opener
+ * language tag). If truncation severs an open code fence, re-append a
+ * closing fence so the message still renders as a balanced block — at the
+ * cost of dropping the overflow characters, which is preferable to a
+ * rejected edit that freezes the chunk on its placeholder.
+ */
+function clampToHardLimit(text) {
+    if (text.length <= DISCORD_HARD_LIMIT)
+        return text;
+    let clamped = text.slice(0, DISCORD_HARD_LIMIT);
+    // Odd number of triple-backticks → an open fence was severed. Reserve room
+    // for a "\n```" closer (4 chars) and re-append it to keep the fence balanced.
+    if ((clamped.match(/```/g) || []).length % 2 === 1) {
+        clamped = clamped.slice(0, DISCORD_HARD_LIMIT - 4) + "\n```";
+    }
+    return clamped;
+}
+/**
+ * Position (0-based) of the unpaired opening ``` in `buffer.slice(0, end)`,
+ * or null if all triple-backticks before `end` are paired.
+ */
+function findUnpairedFenceStart(buffer, end) {
+    const before = buffer.slice(0, end);
+    const parts = before.split("```");
+    // length is odd → balanced; even → one unpaired opener exists
+    if (parts.length % 2 !== 0)
+        return null;
+    return before.lastIndexOf("```");
+}
+export class ChunkedMessageStream {
+    buffer = "";
+    /** Sorted positions where a chunk ends (= where the next chunk begins). */
+    boundaries = [];
+    streams = [];
+    /** Serialises new-chunk creation so async postPlaceholder calls don't race. */
+    setupPromise = Promise.resolve();
+    /**
+     * Records the first setup-chain failure (e.g. a rejecting `postPlaceholder`).
+     * The chain itself is kept rejection-free via a `.catch` so no interim
+     * unhandled promise rejection is emitted; the stored error is rethrown
+     * deterministically at the next `append`/`finish`.
+     */
+    setupError = undefined;
+    finished = false;
+    limit;
+    minIntervalMs;
+    postPlaceholder;
+    updateAt;
+    transform;
+    constructor(config) {
+        this.limit = config.limit ?? DEFAULT_LIMIT;
+        this.minIntervalMs = config.minIntervalMs;
+        this.postPlaceholder = config.postPlaceholder;
+        this.updateAt = config.updateAt;
+        this.transform = config.transform ?? discordMarkdown;
+    }
+    append(fullText) {
+        if (this.finished)
+            return;
+        // A prior setup-chain failure is fatal for the stream — surface it
+        // synchronously here rather than chaining more work onto a doomed promise.
+        if (this.setupError !== undefined)
+            throw this.asSetupError();
+        if (fullText === this.buffer)
+            return;
+        this.buffer = fullText;
+        this.refreezeBoundaries();
+        // Make sure we have one Discord message per chunk, then dispatch. The
+        // `.catch` keeps `setupPromise` itself rejection-free (no unhandled
+        // rejection between this append and the next surfacing point); the failure
+        // is recorded once and rethrown at the next append/finish.
+        this.setupPromise = this.setupPromise
+            .then(() => this.ensureStreamsAndDispatch())
+            .catch((err) => {
+            if (this.setupError === undefined)
+                this.setupError = err;
+        });
+    }
+    async finish() {
+        this.finished = true;
+        // Drain any pending setup, then a final dispatch, then finish each stream.
+        this.setupPromise = this.setupPromise
+            .then(() => this.ensureStreamsAndDispatch())
+            .catch((err) => {
+            if (this.setupError === undefined)
+                this.setupError = err;
+        });
+        await this.setupPromise;
+        // Surface a setup failure (e.g. a rejecting postPlaceholder) here so the
+        // caller still sees it — just without an interim unhandled rejection.
+        if (this.setupError !== undefined)
+            throw this.asSetupError();
+        for (const s of this.streams)
+            await s.finish();
+    }
+    /** Wraps the recorded setup failure with context for surfacing to callers. */
+    asSetupError() {
+        const cause = this.setupError;
+        return new Error("ChunkedMessageStream setup failed", { cause });
+    }
+    /** Returns the number of Discord messages this stream has 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. Once frozen, a
+     * boundary doesn't move.
+     *
+     * Special case (block-keeps-whole): if the chosen boundary lands INSIDE
+     * an open fenced code block, we try to move the boundary BACK to the
+     * position right before the fence opener, so the *whole* block lives in
+     * the next Discord message rather than being split. The previous chunk
+     * gets shortened (message edit will update it down). Fallback when the
+     * block is too large to fit in one chunk: keep the inside-fence
+     * boundary; the dispatcher will prepend the fence opener to the next
+     * chunk (re-opener path).
+     */
+    refreezeBoundaries() {
+        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(" ");
+            if (breakAt < 0)
+                breakAt = this.limit - 1;
+            let candidate = lastFrozen + breakAt + 1;
+            // Block-keeps-whole: move boundary back if it lands inside an open
+            // fence. Only adjust if the fence opener is in the latter ~70% of
+            // the active chunk — otherwise shrinking would lose too much
+            // content (chunk N would be tiny) and the re-opener path is better.
+            const fenceStart = findUnpairedFenceStart(this.buffer, candidate);
+            if (fenceStart !== null) {
+                const minAcceptable = lastFrozen + Math.floor(this.limit * 0.3);
+                if (fenceStart > minAcceptable) {
+                    candidate = fenceStart;
+                }
+            }
+            this.boundaries.push(candidate);
+            lastFrozen = candidate;
+        }
+    }
+    async ensureStreamsAndDispatch() {
+        // If we've never received any content, don't post a placeholder. This
+        // matters for the empty-response case: a TEXT_MESSAGE_START + END
+        // pair with no content events should produce no Discord message.
+        if (this.buffer.length === 0)
+            return;
+        const chunkCount = this.boundaries.length + 1;
+        while (this.streams.length < chunkCount) {
+            const i = this.streams.length;
+            const placeholder = i === 0 ? STREAM_PLACEHOLDERS[0] : STREAM_PLACEHOLDERS[1];
+            const id = await this.postPlaceholder(placeholder);
+            this.streams.push(new MessageStream({
+                update: (text) => this.updateAt(id, clampToHardLimit(this.transform(text)) || " "),
+                minIntervalMs: this.minIntervalMs,
+            }));
+        }
+        // Dispatch slices.
+        //
+        // For continuation chunks (i > 0), if the boundary fell inside an open
+        // markdown construct (e.g. inside a ```python block), prepend the
+        // opener for that construct to the slice. Otherwise the second Discord
+        // message would begin with raw code that Discord renders as plain text.
+        // The closer at the end of the chunk is added by `transform`
+        // (autoCloseOpenMarkdown), which runs per chunk.
+        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;
+            let slice = this.buffer.slice(start, end);
+            if (i > 0) {
+                const ctx = detectOpenContext(this.buffer.slice(0, start));
+                const opener = renderContextOpener(ctx);
+                if (opener)
+                    slice = opener + slice;
+            }
+            this.streams[i].append(slice);
+        }
+    }
+}

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

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

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

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