@copilotkit/channels-core 0.4.1-canary.parallel1 → 0.5.0

package/dist/create-channel.test.js

@@ -52,17 +52,147 @@ function collectText(nodes) {
     }
     return out;
 }
-/** Capture user messages injected into a fake agent without changing its behavior. */
+/**
+ * Apply `patch` to `agent` and, recursively, to every clone descended from it.
+ *
+ * `createChannel` isolates every turn via `clone()`, so the instance a turn
+ * actually runs on is never the one the test configured. A spy installed only on
+ * the configured agent would observe nothing.
+ */
+function patchAgentAndClones(agent, patch) {
+    const wrap = (target) => {
+        patch(target);
+        const origClone = target.clone.bind(target);
+        target.clone = () => {
+            const cloned = origClone();
+            wrap(cloned);
+            return cloned;
+        };
+    };
+    wrap(agent);
+}
+/** Capture user messages injected into a fake agent (and every clone of it). */
 function captureAddedMessages(agent) {
     const added = [];
-    const addMessage = agent.addMessage.bind(agent);
-    agent.addMessage = (message) => {
-        added.push(message);
-        return addMessage(message);
-    };
+    patchAgentAndClones(agent, (target) => {
+        const addMessage = target.addMessage.bind(target);
+        target.addMessage = (message) => {
+            added.push(message);
+            return addMessage(message);
+        };
+    });
     return added;
 }
+/** Sum `runAgent` calls across the configured agent and every clone of it. */
+function trackRunAgentCalls(agent) {
+    let total = 0;
+    patchAgentAndClones(agent, (target) => {
+        const orig = target.runAgent.bind(target);
+        target.runAgent = async (parameters, subscriber) => {
+            total += 1;
+            return orig(parameters, subscriber);
+        };
+    });
+    return { total: () => total };
+}
+/**
+ * Capture the agent instances handed to the conversation store — i.e. the ones
+ * that actually run, post-isolation — rather than the configured prototype.
+ */
+function captureSessionAgents(fake) {
+    const agents = [];
+    const orig = fake.conversationStore.getOrCreate.bind(fake.conversationStore);
+    fake.conversationStore.getOrCreate = async (key, target, makeAgent) => {
+        const session = await orig(key, target, makeAgent);
+        agents.push(session.agent);
+        return session;
+    };
+    return { agents };
+}
 describe("createChannel", () => {
+    it("rejects activation when a message-capable adapter has no eligible handler", async () => {
+        const fake = new FakeAdapter({ messageEvents: true });
+        const channel = createChannel({ name: "support", adapters: [fake] });
+        await expect(channel.ɵruntime.start()).rejects.toThrow('channel "support" must register onMention or onMessage');
+        expect(fake.started).toBe(false);
+    });
+    it("routes an explicit mention only to onMention", async () => {
+        const fake = new FakeAdapter();
+        const channel = createChannel({ adapters: [fake] });
+        const mentions = vi.fn();
+        const messages = vi.fn();
+        channel.onMention(mentions);
+        channel.onMessage(messages);
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hello",
+            platform: "fake",
+            operation: {
+                kind: "created",
+                logicalMessageId: "message-1",
+                revisionId: "revision-1",
+                mentioned: true,
+            },
+        });
+        expect(mentions).toHaveBeenCalledOnce();
+        expect(messages).not.toHaveBeenCalled();
+    });
+    it("falls an explicit mention back to onMessage", async () => {
+        const fake = new FakeAdapter();
+        const channel = createChannel({ adapters: [fake] });
+        const messages = vi.fn();
+        channel.onMessage(messages);
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hello",
+            platform: "fake",
+            operation: {
+                kind: "updated",
+                logicalMessageId: "message-1",
+                revisionId: "revision-2",
+                mentioned: true,
+            },
+        });
+        expect(messages).toHaveBeenCalledOnce();
+        expect(messages).toHaveBeenCalledWith({
+            thread: expect.anything(),
+            message: expect.objectContaining({
+                operation: {
+                    kind: "updated",
+                    logicalMessageId: "message-1",
+                    revisionId: "revision-2",
+                    mentioned: true,
+                },
+            }),
+        });
+    });
+    it("routes an ordinary message only to onMessage", async () => {
+        const fake = new FakeAdapter();
+        const channel = createChannel({ adapters: [fake] });
+        const mentions = vi.fn();
+        const messages = vi.fn();
+        channel.onMention(mentions);
+        channel.onMessage(messages);
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "",
+            platform: "fake",
+            operation: {
+                kind: "deleted",
+                logicalMessageId: "message-1",
+                revisionId: "revision-3",
+                mentioned: false,
+            },
+        });
+        expect(messages).toHaveBeenCalledOnce();
+        expect(mentions).not.toHaveBeenCalled();
+    });
     it("routes a mention to a handler that posts UI", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();
@@ -112,6 +242,89 @@ describe("createChannel", () => {
             content: "Say my name",
         });
     });
+    it("injects the inbound turn only into the first managed run in one handler", async () => {
+        const fake = new FakeAdapter();
+        Object.defineProperty(fake, "injectInboundTurnOnce", { value: true });
+        const agent = new FakeAgent();
+        const added = captureAddedMessages(agent);
+        const runs = trackRunAgentCalls(agent);
+        const channel = createChannel({ adapters: [fake], agent: () => agent });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent();
+            await thread.runAgent();
+        });
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "Use this once",
+            platform: "fake",
+        });
+        // Each `thread.runAgent()` resolves its own isolated instance, so count runs
+        // across the configured agent and its clones rather than on one object.
+        expect(runs.total()).toBe(2);
+        expect(added).toEqual([
+            expect.objectContaining({
+                role: "user",
+                content: "Use this once",
+            }),
+        ]);
+    });
+    it("wraps every local tool iteration in one managed lifecycle", async () => {
+        const fake = new FakeAdapter();
+        const canonicalToolEnds = [];
+        const lifecycleCalls = [];
+        fake.runAgentLifecycle = async (args) => {
+            lifecycleCalls.push(1);
+            const subscriber = {
+                onToolCallEndEvent({ event }) {
+                    canonicalToolEnds.push(event.toolCallId);
+                },
+            };
+            return args.execute(subscriber);
+        };
+        const agent = new FakeAgent([
+            (subscriber) => {
+                subscriber.onToolCallEndEvent?.({
+                    event: { toolCallId: "tool-1" },
+                    toolCallName: "echo",
+                    toolCallArgs: { value: "hello" },
+                });
+            },
+            () => undefined,
+        ]);
+        const sessionAgents = captureSessionAgents(fake);
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => agent,
+            tools: [
+                {
+                    name: "echo",
+                    description: "Return the input",
+                    parameters: z.object({ value: z.string() }),
+                    handler: ({ value }) => value,
+                },
+            ],
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent();
+        });
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "Run the tool",
+            platform: "fake",
+        });
+        expect(lifecycleCalls).toHaveLength(1);
+        // One `thread.runAgent()` → one isolated instance, and the tool loop iterates
+        // twice on that instance. Assert on it, not on the configured prototype.
+        expect(sessionAgents.agents).toHaveLength(1);
+        const ran = sessionAgents.agents[0];
+        expect(ran.runAgentCalls).toBe(2);
+        expect(canonicalToolEnds).toEqual(["tool-1"]);
+        expect(ran.messages.some((message) => message.role === "tool" && message.toolCallId === "tool-1")).toBe(true);
+    });
     it("does not duplicate an inbound message seeded by the conversation store", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();
@@ -147,6 +360,37 @@ describe("createChannel", () => {
             content: "Say my name",
         });
     });
+    it("does not duplicate an explicitly repeated inbound prompt seeded by the conversation store", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const added = captureAddedMessages(agent);
+        const getOrCreate = fake.conversationStore.getOrCreate.bind(fake.conversationStore);
+        Object.defineProperty(fake.conversationStore, "seedsInboundTurn", {
+            value: true,
+        });
+        fake.conversationStore.getOrCreate = async (...args) => {
+            const session = await getOrCreate(...args);
+            session.agent.addMessage({
+                id: "inbound",
+                role: "user",
+                content: "Say my name",
+            });
+            return session;
+        };
+        const channel = createChannel({ adapters: [fake], agent: () => agent });
+        channel.onMention(async ({ thread, message }) => {
+            await thread.runAgent({ prompt: message.text });
+        });
+        await channel.ɵruntime.start();
+        await fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "Say my name",
+            platform: "fake",
+        });
+        expect(added).toHaveLength(1);
+        expect(added[0]).toMatchObject({ id: "inbound" });
+    });
     it("defaults runAgent prompt to inbound multimodal content parts", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();
@@ -265,18 +509,21 @@ describe("createChannel", () => {
     it("merges per-turn runAgent context with the channel-level context", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();
-        // Capture the context/tools passed to the agent's first runAgent call.
+        // Capture the context/tools passed to the first runAgent call on whichever
+        // isolated instance ends up running.
         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);
-        };
+        patchAgentAndClones(agent, (target) => {
+            const origRunAgent = target.runAgent.bind(target);
+            target.runAgent = async (parameters, subscriber) => {
+                if (seenContext === undefined) {
+                    seenContext = parameters
+                        ?.context;
+                    seenTools = parameters?.tools;
+                }
+                return origRunAgent(parameters, subscriber);
+            };
+        });
         const channel = createChannel({
             adapters: [fake],
             agent: () => agent,
@@ -431,6 +678,278 @@ describe("createChannel", () => {
         // Both turns' handlers should have run.
         expect(runs).toBe(2);
     });
+    it("default concurrency is parallel: overlapping same-conversation turns both run", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+            store: { adapter: state },
+        });
+        channel.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        const p1 = sink.onTurn({ ...turn, eventId: "E-a" });
+        const p2 = sink.onTurn({ ...turn, eventId: "E-b" });
+        // Both handlers must have started before either finishes (parallel).
+        await vi.waitFor(() => expect(runs).toBe(2));
+        release();
+        await Promise.all([p1, p2]);
+        expect(runs).toBe(2);
+    });
+    it("concurrency: serial queues the second turn until the first finishes", async () => {
+        const state = new MemoryStore();
+        const order = [];
+        let release1;
+        const gate1 = new Promise((r) => (release1 = r));
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+            store: { adapter: state, concurrency: "serial" },
+        });
+        channel.onMention(async ({ message }) => {
+            order.push(`start:${message.eventId}`);
+            if (message.eventId === "E1")
+                await gate1;
+            order.push(`end:${message.eventId}`);
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        const base = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        const p1 = sink.onTurn({ ...base, eventId: "E1" });
+        const p2 = sink.onTurn({ ...base, eventId: "E2" });
+        await vi.waitFor(() => expect(order).toContain("start:E1"));
+        // Second must not start while first is gated.
+        expect(order).toEqual(["start:E1"]);
+        release1();
+        await Promise.all([p1, p2]);
+        expect(order).toEqual(["start:E1", "end:E1", "start:E2", "end:E2"]);
+    });
+    it("concurrency: drop discards the overlapping turn", async () => {
+        const state = new MemoryStore();
+        let runs = 0;
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+            store: { adapter: state, concurrency: "drop" },
+        });
+        channel.onMention(async () => {
+            runs++;
+            await gate;
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        const turn = {
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+        };
+        const p1 = sink.onTurn({ ...turn, eventId: "E1" });
+        const p2 = sink.onTurn({ ...turn, eventId: "E2" });
+        release();
+        await Promise.all([p1, p2]);
+        expect(runs).toBe(1);
+    });
+    it("singleton agent is cloned per run (distinct instances)", async () => {
+        const state = new MemoryStore();
+        const prototype = new FakeAgent();
+        const fake = new FakeAdapter();
+        const { agents: seen } = captureSessionAgents(fake);
+        const channel = createChannel({
+            adapters: [fake],
+            agent: prototype, // singleton, not factory
+            store: { adapter: state },
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent({ prompt: "hi" });
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        await Promise.all([
+            sink.onTurn({
+                conversationKey: "c1",
+                replyTarget: {},
+                userText: "a",
+                platform: "fake",
+                eventId: "E1",
+            }),
+            sink.onTurn({
+                conversationKey: "c1",
+                replyTarget: {},
+                userText: "b",
+                platform: "fake",
+                eventId: "E2",
+            }),
+        ]);
+        expect(seen.length).toBe(2);
+        expect(seen[0]).not.toBe(prototype);
+        expect(seen[1]).not.toBe(prototype);
+        expect(seen[0]).not.toBe(seen[1]);
+    });
+    it("singleton agent whose clone returns itself fails loud", async () => {
+        const state = new MemoryStore();
+        const bad = new FakeAgent();
+        bad.clone = () => bad;
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: bad,
+            store: { adapter: state },
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent({ prompt: "hi" });
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        await expect(sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+            eventId: "E1",
+        })).rejects.toThrow(/clone\(\) must return a distinct instance/);
+    });
+    it("factory returning a shared instance isolates each turn from the others", async () => {
+        const state = new MemoryStore();
+        const shared = new FakeAgent();
+        const fake = new FakeAdapter();
+        const { agents: seen } = captureSessionAgents(fake);
+        // The shape this exists for: a factory that hands back the same object on
+        // every call. Turn concurrency is parallel by default, so without isolation
+        // both turns would run on `shared` and append into its one `messages` array.
+        const channel = createChannel({
+            adapters: [fake],
+            agent: (threadId) => {
+                shared.threadId = threadId;
+                return shared;
+            },
+            store: { adapter: state },
+        });
+        // What each run believes it was asked, read while both turns are in flight.
+        const askedPerRun = [];
+        patchAgentAndClones(shared, (target) => {
+            const orig = target.runAgent.bind(target);
+            target.runAgent = async (parameters, subscriber) => {
+                // Hold the run open so the turns genuinely overlap, then read back. On a
+                // shared instance the other turn's user message has landed by now.
+                await new Promise((r) => setTimeout(r, 20));
+                askedPerRun.push(target.messages
+                    .filter((m) => m.role === "user")
+                    .map((m) => String(m.content))
+                    .join("+"));
+                return orig(parameters, subscriber);
+            };
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent();
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        await Promise.all([
+            sink.onTurn({
+                conversationKey: "c1",
+                replyTarget: {},
+                userText: "first",
+                platform: "fake",
+                eventId: "E1",
+            }),
+            sink.onTurn({
+                conversationKey: "c1",
+                replyTarget: {},
+                userText: "second",
+                platform: "fake",
+                eventId: "E2",
+            }),
+        ]);
+        // Assert the symptom before the mechanism, so a regression reports the
+        // user-visible defect rather than an object-identity puzzle: without
+        // isolation both runs read "first+second" off the one shared `messages`
+        // array, so each turn is prompted with the other user's question too.
+        // Completion order between the turns isn't guaranteed — compare as a set.
+        expect(askedPerRun.sort()).toEqual(["first", "second"]);
+        // Mechanism: two distinct clones, neither of them the configured object.
+        expect(seen).toHaveLength(2);
+        expect(seen[0]).not.toBe(shared);
+        expect(seen[1]).not.toBe(shared);
+        expect(seen[0]).not.toBe(seen[1]);
+        // Nothing ever runs on the configured object, so it stays pristine.
+        expect(shared.messages).toEqual([]);
+    });
+    it("agent whose clone() drops subclass state fails loud", async () => {
+        const state = new MemoryStore();
+        // Inherits `FakeAgent.clone()`, which builds a plain `FakeAgent` and so
+        // cannot carry this field — the same shape as a subclass inheriting
+        // `AbstractAgent.prototype.clone()`, which copies a fixed field list.
+        class StatefulAgent extends FakeAgent {
+            authClient = { token: "secret" };
+        }
+        const agent = new StatefulAgent();
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => agent,
+            store: { adapter: state },
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent({ prompt: "hi" });
+        });
+        await channel.ɵruntime.start();
+        const sink = fake.getSink();
+        await expect(sink.onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+            eventId: "E1",
+        })).rejects.toThrow(/StatefulAgent\.clone\(\) dropped authClient/);
+    });
+    it("does not fail loud when clone() drops an instance-patched method", async () => {
+        const state = new MemoryStore();
+        const agent = new FakeAgent();
+        // Spies and instrumentation assign methods on the instance. `FakeAgent.clone()`
+        // does not carry them, but the prototype method survives, so the clone still
+        // behaves correctly and this must not be treated as dropped state.
+        agent.runAgent = async (parameters, subscriber) => FakeAgent.prototype.runAgent.call(agent, parameters, subscriber);
+        const fake = new FakeAdapter();
+        const channel = createChannel({
+            adapters: [fake],
+            agent: () => agent,
+            store: { adapter: state },
+        });
+        channel.onMention(async ({ thread }) => {
+            await thread.runAgent({ prompt: "hi" });
+        });
+        await channel.ɵruntime.start();
+        await expect(fake.getSink().onTurn({
+            conversationKey: "c1",
+            replyTarget: {},
+            userText: "hi",
+            platform: "fake",
+            eventId: "E1",
+        })).resolves.not.toThrow();
+    });
     it("dedupes turns by eventId", async () => {
         const state = new MemoryStore();
         let runs = 0;
@@ -551,19 +1070,23 @@ describe("createChannel", () => {
         // 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);
-        };
+        patchAgentAndClones(agent, (target) => {
+            const origRunAgent = target.runAgent.bind(target);
+            target.runAgent = async (parameters, subscriber) => {
+                if (seenContext === undefined) {
+                    seenContext = parameters
+                        ?.context;
+                }
+                // Add to the instance that is running, so the reply lands on the
+                // messages the run loop reads back.
+                target.addMessage({
+                    id: globalThis.crypto.randomUUID(),
+                    role: "assistant",
+                    content: "the assistant reply",
+                });
+                return origRunAgent(parameters, subscriber);
+            };
+        });
         channel.onMention(async ({ thread }) => {
             await thread.runAgent({ transcript: true });
         });

package/dist/delivery-error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A provider delivery has already reached a terminal outcome.
+ *
+ * Tool handlers must not convert this error into model-visible tool output:
+ * continuing the agent would let later events render through a closed delivery.
+ */
+declare const CHANNEL_DELIVERY_TERMINATED: unique symbol;
+export declare class ChannelDeliveryTerminatedError extends Error {
+    readonly [CHANNEL_DELIVERY_TERMINATED] = true;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Recognize terminal delivery errors across duplicated package installations.
+ */
+export declare function isChannelDeliveryTerminatedError(error: unknown): error is ChannelDeliveryTerminatedError;
+export {};
+//# sourceMappingURL=delivery-error.d.ts.map

package/dist/delivery-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-error.d.ts","sourceRoot":"","sources":["../src/delivery-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,QAAA,MAAM,2BAA2B,eAEhC,CAAC;AAEF,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,CAAC,2BAA2B,CAAC,QAAQ;gBAElC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,8BAA8B,CAQzC"}

package/dist/delivery-error.js

@@ -0,0 +1,22 @@
+/**
+ * A provider delivery has already reached a terminal outcome.
+ *
+ * Tool handlers must not convert this error into model-visible tool output:
+ * continuing the agent would let later events render through a closed delivery.
+ */
+const CHANNEL_DELIVERY_TERMINATED = Symbol.for("copilotkit.channels.deliveryTerminated");
+export class ChannelDeliveryTerminatedError extends Error {
+    [CHANNEL_DELIVERY_TERMINATED] = true;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ChannelDeliveryTerminatedError";
+    }
+}
+/**
+ * Recognize terminal delivery errors across duplicated package installations.
+ */
+export function isChannelDeliveryTerminatedError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error[CHANNEL_DELIVERY_TERMINATED] === true);
+}