@copilotkit/channels 0.1.0

package/dist/create-bot.test.js

@@ -0,0 +1,936 @@
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { createBot } from "./create-bot.js";
+import { defineBotCommand } from "./commands.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+import { FakeAgent } from "./testing/fake-agent.js";
+import { MemoryStore } from "./state/memory-store.js";
+import { Section, Actions, Button } from "@copilotkit/channels-ui";
+const tick = () => new Promise((r) => setTimeout(r, 0));
+/**
+ * Compile-time guards for the handler generics (validated by check-types/build,
+ * never executed). `onInterrupt<T>` types `payload`; `onInteraction<T>` types
+ * `ctx.action.value`.
+ */
+const __handlerTypeGuards = () => {
+    const bot = createBot({ adapters: [new FakeAdapter()] });
+    bot.onInterrupt("ask", ({ payload }) => {
+        payload.question.toUpperCase();
+        // @ts-expect-error 'missing' is not on the payload type
+        payload.missing;
+    });
+    bot.onInteraction("next", (ctx) => {
+        ctx.action.value?.page.toFixed(0);
+        // @ts-expect-error 'nope' is not on the action value type
+        ctx.action.value?.nope;
+    });
+};
+void __handlerTypeGuards;
+/** Recursively find the first node of a given type in an IR tree. */
+function findNode(nodes, type) {
+    for (const n of nodes) {
+        if (n.type === type)
+            return n;
+        const children = n.props.children;
+        if (Array.isArray(children)) {
+            const found = findNode(children, type);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Concatenate all text node values in an IR tree. */
+function collectText(nodes) {
+    let out = "";
+    for (const n of nodes) {
+        if (n.type === "text" && typeof n.props.value === "string")
+            out += n.props.value;
+        const children = n.props.children;
+        if (Array.isArray(children))
+            out += collectText(children);
+    }
+    return out;
+}
+describe("createBot", () => {
+    it("routes a mention to a handler that posts UI", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        bot.onMention(async ({ thread }) => {
+            await thread.post(Section({ children: "hi" }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        expect(fake.posted.length).toBe(1);
+        const ir = fake.posted[0];
+        expect(findNode(ir, "section")).toBeDefined();
+        expect(collectText(ir)).toBe("hi");
+    });
+    it("calls renderer.finish() once after a turn's run-loop resolves", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        bot.onMention(async ({ thread }) => {
+            await thread.runAgent();
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        const renderer = fake.lastRunRenderer;
+        expect(renderer.finishCalls).toBe(1);
+    });
+    it("delivers a turn's contentParts as the runAgent prompt to agent.addMessage", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        // Capture what the framework injects as the user message.
+        const added = [];
+        const origAddMessage = agent.addMessage.bind(agent);
+        agent.addMessage = (m) => {
+            added.push(m);
+            return origAddMessage(m);
+        };
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        const parts = [
+            { type: "text", text: "look" },
+            {
+                type: "image",
+                source: { type: "data", value: "QUJD", mimeType: "image/png" },
+            },
+        ];
+        bot.onMention(async ({ thread, message }) => {
+            // The example mirrors this: prefer multimodal parts over plain text.
+            await thread.runAgent({
+                prompt: message.contentParts && message.contentParts.length > 0
+                    ? message.contentParts
+                    : message.text,
+            });
+        });
+        await bot.start();
+        fake.emitTurn({
+            userText: "look",
+            conversationKey: "c1",
+            contentParts: parts,
+        });
+        await tick();
+        expect(added).toHaveLength(1);
+        const msg = added[0];
+        expect(msg.role).toBe("user");
+        // The multimodal parts array survives the string-typed `content` cast.
+        expect(msg.content).toEqual(parts);
+    });
+    it("dispatches a bound onClick handler on interaction", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let clicked = false;
+        bot.onMention(async ({ thread }) => {
+            await thread.post(Actions({
+                children: [
+                    Button({
+                        value: { ok: 1 },
+                        onClick: () => {
+                            clicked = true;
+                        },
+                        children: "Go",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        expect(typeof id).toBe("string");
+        fake.emitInteraction({ id, conversationKey: "c1", value: { ok: 1 } });
+        await tick();
+        expect(clicked).toBe(true);
+    });
+    it("resolves a HITL awaitChoice with the element value when the event carries none (Telegram)", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let chosen;
+        bot.onMention(async ({ thread }) => {
+            chosen = await thread.awaitChoice(Actions({
+                children: [
+                    Button({
+                        value: { confirmed: true },
+                        onClick: () => { },
+                        children: "Create",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "create a thing", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        // Telegram can't carry the button value in callback_data, so the event has
+        // no `value`. The waiter must still resolve with the button's value, which
+        // the registry recovers from the rendered element.
+        fake.emitInteraction({ id, conversationKey: "c1" });
+        await tick();
+        expect(chosen).toEqual({ confirmed: true });
+    });
+    it("merges per-turn runAgent context with the bot-level context", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        // Capture the context/tools passed to the agent's first runAgent call.
+        let seenContext;
+        let seenTools;
+        const origRunAgent = agent.runAgent.bind(agent);
+        agent.runAgent = async (parameters, subscriber) => {
+            if (seenContext === undefined) {
+                seenContext = parameters
+                    ?.context;
+                seenTools = parameters?.tools;
+            }
+            return origRunAgent(parameters, subscriber);
+        };
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            context: [{ description: "bot-level", value: "always here" }],
+        });
+        bot.onMention(async ({ thread }) => {
+            await thread.runAgent({
+                context: [{ description: "who", value: "user U1" }],
+            });
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "go", conversationKey: "c1" });
+        await tick();
+        expect(seenContext).toEqual([
+            { description: "bot-level", value: "always here" },
+            { description: "who", value: "user U1" },
+        ]);
+        expect(seenTools).toEqual([]);
+    });
+    it("thread.postFile returns a capability-gated error when the adapter can't upload", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let result;
+        bot.onMention(async ({ thread }) => {
+            result = await thread.postFile({
+                bytes: new Uint8Array([1, 2, 3]),
+                filename: "x.png",
+            });
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "hi", conversationKey: "c1" });
+        await tick();
+        expect(result).toEqual({
+            ok: false,
+            error: "fake does not support file upload",
+        });
+    });
+    it("thread.getMessages and thread.lookupUser surface the adapter's data", async () => {
+        const fake = new FakeAdapter();
+        fake.messages = [
+            { user: { id: "u1", name: "Ada" }, text: "hi", ts: "1", isBot: false },
+        ];
+        fake.user = { id: "u1", name: "Ada" };
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let history;
+        let resolved;
+        bot.onMention(async ({ thread }) => {
+            history = await thread.getMessages();
+            resolved = await thread.lookupUser("Ada");
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "hi", conversationKey: "c1" });
+        await tick();
+        expect(history).toEqual([
+            { user: { id: "u1", name: "Ada" }, text: "hi", ts: "1", isBot: false },
+        ]);
+        expect(resolved).toEqual({ id: "u1", name: "Ada" });
+    });
+    it("resolves awaitChoice when a matching interaction arrives", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let choicePromise;
+        bot.onMention(async ({ thread }) => {
+            choicePromise = thread.awaitChoice(Actions({
+                children: [
+                    Button({
+                        value: { confirmed: true },
+                        onClick: () => { },
+                        children: "Confirm",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "decide", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        fake.emitInteraction({
+            id,
+            conversationKey: "c1",
+            value: { confirmed: true },
+        });
+        await tick();
+        expect(choicePromise).toBeDefined();
+        await expect(choicePromise).resolves.toEqual({ confirmed: true });
+    });
+    it("drops an overlapping turn on the same conversation (onLockConflict: drop)", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: { adapter: state, onLockConflict: "drop" },
+        });
+        bot.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        // Fire two overlapping onTurn calls — second arrives while first holds the lock.
+        const p1 = sink.onTurn(turn);
+        const p2 = sink.onTurn(turn);
+        release();
+        await Promise.all([p1, p2]);
+        // Only the first turn's handler should have run; the second was dropped.
+        expect(runs).toBe(1);
+    });
+    it("runs both handlers when onLockConflict is force", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: { adapter: state, onLockConflict: "force" },
+        });
+        bot.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        // Fire two overlapping onTurn calls — second forces through the lock.
+        const p1 = sink.onTurn(turn);
+        const p2 = sink.onTurn(turn);
+        release();
+        await Promise.all([p1, p2]);
+        // Both turns' handlers should have run.
+        expect(runs).toBe(2);
+    });
+    it("dedupes turns by eventId", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: { adapter: state },
+        });
+        bot.onMention(async () => {
+            runs++;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const base = {
+            conversationKey: "c",
+            replyTarget: {},
+            userText: "x",
+            platform: "fake",
+            eventId: "E1",
+        };
+        // Same eventId delivered twice → handler runs only once.
+        await sink.onTurn(base);
+        await sink.onTurn({ ...base });
+        expect(runs).toBe(1);
+        // Different eventId → handler runs again.
+        await sink.onTurn({ ...base, eventId: "E2" });
+        expect(runs).toBe(2);
+    });
+    it("throws when identity is set without transcripts", () => {
+        const fake = new FakeAdapter();
+        expect(() => createBot({
+            adapters: [fake],
+            store: { identity: () => "key" },
+        })).toThrow("createBot: `identity` and `transcripts` must be configured together.");
+    });
+    it("throws when transcripts is set without identity", () => {
+        const fake = new FakeAdapter();
+        expect(() => createBot({
+            adapters: [fake],
+            store: { transcripts: { maxPerUser: 100 } },
+        })).toThrow("createBot: `identity` and `transcripts` must be configured together.");
+    });
+    it("stamps message.userKey when identity resolves a key", async () => {
+        const state = new MemoryStore();
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: {
+                adapter: state,
+                identity: () => "user@example.com",
+                transcripts: {},
+            },
+        });
+        let capturedKey;
+        bot.onMention(async ({ message }) => {
+            capturedKey = message.userKey;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        await sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hello",
+            platform: "fake",
+            user: { id: "u1" },
+        });
+        expect(capturedKey).toBe("user@example.com");
+    });
+    it("bot.transcripts.append/list round-trips with MemoryStore", async () => {
+        const state = new MemoryStore();
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: {
+                adapter: state,
+                identity: () => "alice@example.com",
+                transcripts: { maxPerUser: 50 },
+            },
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        // Drive a turn so identity is resolved and we can verify transcripts exist
+        const thread = { platform: "fake", conversationKey: "c1" };
+        // Directly append via bot.transcripts
+        await bot.transcripts.append(thread, { role: "user", text: "hi there" }, {
+            userKey: "alice@example.com",
+        });
+        await bot.transcripts.append(thread, { role: "assistant", text: "hello!" }, { userKey: "alice@example.com" });
+        const entries = await bot.transcripts.list({
+            userKey: "alice@example.com",
+        });
+        expect(entries).toHaveLength(2);
+        expect(entries[0].role).toBe("user");
+        expect(entries[0].text).toBe("hi there");
+        expect(entries[1].role).toBe("assistant");
+        expect(entries[1].text).toBe("hello!");
+    });
+    it("runAgent({ transcript: true }) injects prior history and captures the reply", async () => {
+        const state = new MemoryStore();
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: {
+                adapter: state,
+                identity: () => "u@x.com",
+                transcripts: {},
+            },
+        });
+        // Capture the context the agent receives on its first runAgent call, and
+        // have the fake produce an assistant message with text on agent.messages
+        // (mirroring how run-loop expects assistant replies to land there).
+        let seenContext;
+        const origRunAgent = agent.runAgent.bind(agent);
+        agent.runAgent = async (parameters, subscriber) => {
+            if (seenContext === undefined) {
+                seenContext = parameters
+                    ?.context;
+            }
+            agent.addMessage({
+                id: globalThis.crypto.randomUUID(),
+                role: "assistant",
+                content: "the assistant reply",
+            });
+            return origRunAgent(parameters, subscriber);
+        };
+        bot.onMention(async ({ thread }) => {
+            await thread.runAgent({ transcript: true });
+        });
+        await bot.start();
+        // Seed one prior cross-platform entry (different platform label) so we can
+        // assert it shows up in the injected context. Seeded post-start: transcripts
+        // are only available once the backend is resolved in start().
+        await bot.transcripts.append({ platform: "discord", conversationKey: "other" }, { role: "user", text: "remembered from discord" }, { userKey: "u@x.com" });
+        const sink = fake.getSink();
+        await sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hello from fake",
+            platform: "fake",
+            user: { id: "u1" },
+        });
+        // Append side: both the user turn and the assistant reply are recorded,
+        // oldest-first (after the seeded discord entry).
+        const entries = await bot.transcripts.list({ userKey: "u@x.com" });
+        const fakeEntries = entries.filter((e) => e.platform === "fake");
+        expect(fakeEntries).toHaveLength(2);
+        expect(fakeEntries[0].role).toBe("user");
+        expect(fakeEntries[0].text).toBe("hello from fake");
+        expect(fakeEntries[1].role).toBe("assistant");
+        expect(fakeEntries[1].text).toBe("the assistant reply");
+        // Injection side: the agent's context includes an entry whose value carries
+        // the prior discord message text.
+        const ctx = seenContext;
+        const injected = ctx.find((c) => c.value.includes("remembered from discord"));
+        expect(injected).toBeDefined();
+        expect(injected.value).toContain("[discord] user: remembered from discord");
+    });
+    it("typesafe state: setState validates against store.state schema and round-trips", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            store: {
+                adapter: new MemoryStore(),
+                state: z.object({ step: z.string() }),
+            },
+        });
+        let roundTripped;
+        let rejected = false;
+        bot.onMention(async ({ thread }) => {
+            // Typed to { step: string } via the configured schema.
+            await thread.setState({ step: "x" });
+            roundTripped = await thread.state();
+            // An invalid value (wrong shape) must reject at runtime.
+            try {
+                await thread.setState({ bad: 1 });
+            }
+            catch {
+                rejected = true;
+            }
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "go", conversationKey: "c1" });
+        await tick();
+        expect(roundTripped).toEqual({ step: "x" });
+        expect(rejected).toBe(true);
+    });
+});
+describe("createBot lock and dedup edge cases", () => {
+    it("releases the lock after the handler throws", async () => {
+        const state = new MemoryStore();
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        // Use a separate bot so the throwing handler is isolated.
+        const bot1 = createBot({
+            adapters: [fake],
+            store: { adapter: state, onLockConflict: "drop", lockTtl: 5000 },
+        });
+        let runs = 0;
+        bot1.onMention(async () => {
+            runs++;
+            await gate;
+            throw new Error("boom");
+        });
+        await bot1.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        // Turn 1 throws after gate releases.
+        const p1 = Promise.resolve(sink.onTurn(turn)).catch(() => { });
+        release();
+        await p1;
+        // Lock must be free — verify by acquiring it directly.
+        const tok = await state.lock.acquire("turn:c1");
+        expect(tok).not.toBeNull();
+        if (tok)
+            await state.lock.release("turn:c1", tok.token);
+        expect(runs).toBe(1);
+    });
+    it("onLockConflict callback drop: second turn dropped and callback receives correct args", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        let callbackConversationKey;
+        let callbackMessageText;
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: {
+                adapter: state,
+                onLockConflict: (conversationKey, message) => {
+                    callbackConversationKey = conversationKey;
+                    callbackMessageText = message.text;
+                    return "drop";
+                },
+            },
+        });
+        bot.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hello",
+            platform: "fake",
+        };
+        const p1 = sink.onTurn(turn);
+        const p2 = sink.onTurn(turn);
+        release();
+        await Promise.all([p1, p2]);
+        expect(runs).toBe(1);
+        expect(callbackConversationKey).toBe("c1");
+        expect(callbackMessageText).toBe("hello");
+    });
+    it("onLockConflict callback returning Promise<force>: both turns run", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: {
+                adapter: state,
+                onLockConflict: () => Promise.resolve("force"),
+            },
+        });
+        bot.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        const p1 = sink.onTurn(turn);
+        const p2 = sink.onTurn(turn);
+        release();
+        await Promise.all([p1, p2]);
+        expect(runs).toBe(2);
+    });
+    it("identity throws: handler still runs and userKey is undefined", async () => {
+        const state = new MemoryStore();
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: {
+                adapter: state,
+                identity: () => {
+                    throw new Error("x");
+                },
+                transcripts: {},
+            },
+        });
+        let capturedUserKey = "SENTINEL";
+        bot.onMention(async ({ message }) => {
+            capturedUserKey = message.userKey;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        await sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        });
+        expect(capturedUserKey).toBeUndefined();
+    });
+    it("identity returns null: userKey is undefined", async () => {
+        const state = new MemoryStore();
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: { adapter: state, identity: () => null, transcripts: {} },
+        });
+        let capturedUserKey = "SENTINEL";
+        bot.onMention(async ({ message }) => {
+            capturedUserKey = message.userKey;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        await sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        });
+        expect(capturedUserKey).toBeUndefined();
+    });
+    it("dedup+lock ordering: deduped turn never takes the lock", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: { adapter: state, onLockConflict: "drop" },
+        });
+        bot.onMention(async () => {
+            runs++;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const base = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "x",
+            platform: "fake",
+            eventId: "E1",
+        };
+        await sink.onTurn(base);
+        await sink.onTurn({ ...base }); // same eventId — should be deduped before lock
+        expect(runs).toBe(1);
+        // Lock must still be acquirable (deduped turn never held it).
+        const tok = await state.lock.acquire("turn:c1");
+        expect(tok).not.toBeNull();
+        if (tok)
+            await state.lock.release("turn:c1", tok.token);
+    });
+    it("dedup store error is swallowed: handler still runs", async () => {
+        const state = new MemoryStore();
+        // Wrap state.dedup.seen to throw.
+        const origSeen = state.dedup.seen.bind(state.dedup);
+        let firstCall = true;
+        state.dedup.seen = async (key, ttlMs) => {
+            if (firstCall) {
+                firstCall = false;
+                throw new Error("dedup store exploded");
+            }
+            return origSeen(key, ttlMs);
+        };
+        let runs = 0;
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake], store: { adapter: state } });
+        bot.onMention(async () => {
+            runs++;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        await sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+            eventId: "E1",
+        });
+        // Handler must still run despite the dedup store error.
+        expect(runs).toBe(1);
+    });
+    it("a turn dropped on lock-conflict does not burn its eventId — a redelivery is processed", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let releaseGate;
+        const gate = new Promise((r) => (releaseGate = r));
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: { adapter: state, onLockConflict: "drop" },
+        });
+        bot.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turnA = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "first",
+            platform: "fake",
+            eventId: "E1",
+        };
+        const turnB = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "second",
+            platform: "fake",
+            eventId: "E2",
+        };
+        // Turn A acquires the lock and blocks on the gate.
+        const p1 = sink.onTurn(turnA);
+        // Turn B arrives while A holds the lock — dropped (onLockConflict: "drop").
+        const p2 = sink.onTurn(turnB);
+        // B is dropped before reaching dedup, so E2 must NOT be burned.
+        await p2;
+        // Release A so it finishes and releases the lock.
+        releaseGate();
+        await p1;
+        // Now redeliver turn B with the same eventId "E2" — must be processed.
+        await sink.onTurn(turnB);
+        // A ran once; B's redelivery ran once = 2 total.
+        expect(runs).toBe(2);
+    });
+    it("a genuine duplicate delivery is still deduped (processed once)", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            store: { adapter: state },
+        });
+        bot.onMention(async () => {
+            runs++;
+        });
+        await bot.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c2",
+            replyTarget: {},
+            userText: "hello",
+            platform: "fake",
+            eventId: "D1",
+        };
+        // First delivery: processes successfully and marks E D1 seen.
+        await sink.onTurn(turn);
+        expect(runs).toBe(1);
+        // Second delivery of the same eventId: must be deduped — handler does NOT run again.
+        await sink.onTurn({ ...turn });
+        expect(runs).toBe(1);
+    });
+});
+describe("createBot slash commands", () => {
+    it("routes a command to its handler with the raw text", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        let seen;
+        bot.onCommand("triage", ({ command, text }) => {
+            seen = { command, text };
+        });
+        await bot.start();
+        await fake.emitCommand({ command: "/Triage", text: "db is down" });
+        expect(seen).toEqual({ command: "triage", text: "db is down" });
+    });
+    it("ignores a command with no registered handler", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        let fired = false;
+        bot.onCommand("triage", () => {
+            fired = true;
+        });
+        await bot.start();
+        await fake.emitCommand({ command: "unknown", text: "x" });
+        expect(fired).toBe(false);
+    });
+    it("parses rawOptions through the command's schema into ctx.options", async () => {
+        let captured;
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            commands: [
+                defineBotCommand({
+                    name: "book",
+                    options: z.object({ seat: z.string() }),
+                    handler: ({ options }) => {
+                        captured = options; // typed { seat: string }
+                    },
+                }),
+            ],
+        });
+        await bot.start();
+        await fake.emitCommand({
+            command: "book",
+            text: "raw",
+            rawOptions: { seat: "12A" },
+        });
+        expect(captured).toEqual({ seat: "12A" });
+    });
+    it("hands declared commands to adapters that implement registerCommands", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        bot.onCommand("triage", () => { });
+        bot.onCommand("status", () => { });
+        await bot.start();
+        expect(fake.registeredCommands?.map((c) => c.name).sort()).toEqual([
+            "status",
+            "triage",
+        ]);
+    });
+    it("start() resolves and keeps healthy adapters when one adapter's start() rejects", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        try {
+            const bad = new FakeAdapter({ platform: "telegram", failStart: true });
+            const good = new FakeAdapter({ platform: "slack" });
+            const bot = createBot({ adapters: [bad, good] });
+            await expect(bot.start()).resolves.toBeUndefined();
+            expect(good.started).toBe(true);
+            expect(errSpy.mock.calls.some((c) => String(c[0]).includes("telegram"))).toBe(true);
+        }
+        finally {
+            errSpy.mockRestore();
+        }
+    });
+    it("start() resolves and the healthy adapter still receives commands when another adapter's registerCommands() rejects", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        try {
+            const bad = new FakeAdapter({
+                platform: "telegram",
+                failRegisterCommands: true,
+            });
+            const good = new FakeAdapter({ platform: "slack" });
+            const bot = createBot({ adapters: [bad, good] });
+            bot.onCommand("triage", () => { });
+            await expect(bot.start()).resolves.toBeUndefined();
+            expect(good.started).toBe(true);
+            expect(good.registeredCommands?.map((c) => c.name)).toEqual(["triage"]);
+            expect(errSpy.mock.calls.some((c) => String(c[0]).includes("telegram"))).toBe(true);
+        }
+        finally {
+            errSpy.mockRestore();
+        }
+    });
+    it("stop() resolves and stops healthy adapters when one adapter's stop() rejects", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        try {
+            const bad = new FakeAdapter({ platform: "telegram", failStop: true });
+            const good = new FakeAdapter({ platform: "slack" });
+            const stopSpy = vi.spyOn(good, "stop");
+            const bot = createBot({ adapters: [bad, good] });
+            await bot.start();
+            await expect(bot.stop()).resolves.toBeUndefined();
+            expect(stopSpy).toHaveBeenCalled();
+            expect(errSpy.mock.calls.some((c) => String(c[0]).includes("telegram"))).toBe(true);
+        }
+        finally {
+            errSpy.mockRestore();
+        }
+    });
+});