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

package/dist/run-loop.js

@@ -1,4 +1,179 @@
+import { EventType } from "@ag-ui/client";
 import { parseToolArgs, stringifyHandlerResult } from "./tools.js";
+import { isChannelDeliveryTerminatedError } from "./delivery-error.js";
+/**
+ * Merge two subscriber callback results while preserving either subscriber's
+ * request to stop propagation.
+ */
+function mergeSubscriberResults(firstResult, secondResult) {
+    if ((firstResult === undefined || firstResult === null) &&
+        (secondResult === undefined || secondResult === null)) {
+        return undefined;
+    }
+    return {
+        ...(typeof firstResult === "object" ? firstResult : {}),
+        ...(typeof secondResult === "object" ? secondResult : {}),
+        stopPropagation: (typeof firstResult === "object" &&
+            firstResult !== null &&
+            "stopPropagation" in firstResult &&
+            firstResult.stopPropagation === true) ||
+            (typeof secondResult === "object" &&
+                secondResult !== null &&
+                "stopPropagation" in secondResult &&
+                secondResult.stopPropagation === true),
+    };
+}
+/**
+ * Invoke canonical ingestion before rendering, but always invoke both. A
+ * renderer failure therefore cannot prevent the same event from reaching the
+ * runner.
+ */
+async function invokeSubscriberPair(rendererCallback, ingestionCallback, params, onRendererError, isRendererClosed) {
+    let rendererResult;
+    let ingestionResult;
+    let rendererError;
+    let ingestionError;
+    let rendererFailed = false;
+    let ingestionFailed = false;
+    try {
+        ingestionResult = await ingestionCallback?.(params);
+    }
+    catch (error) {
+        ingestionFailed = true;
+        ingestionError = error;
+    }
+    if (!isRendererClosed?.()) {
+        try {
+            rendererResult = await rendererCallback?.(params);
+        }
+        catch (error) {
+            rendererFailed = true;
+            rendererError = error;
+        }
+    }
+    if (ingestionFailed)
+        throw ingestionError;
+    if (rendererFailed) {
+        if (!onRendererError)
+            throw rendererError;
+        onRendererError(rendererError);
+    }
+    return mergeSubscriberResults(rendererResult, ingestionResult);
+}
+/**
+ * Return one stamped event object for every callback generated from the same
+ * raw AG-UI event.
+ */
+function canonicalizeSubscriberParams(params, options, stampedEvents) {
+    if (typeof params !== "object" ||
+        params === null ||
+        !("event" in params) ||
+        typeof params.event !== "object" ||
+        params.event === null ||
+        !("type" in params.event)) {
+        return params;
+    }
+    const event = params.event;
+    if (options.canonicalRun &&
+        (event.type === EventType.RUN_STARTED ||
+            event.type === EventType.RUN_FINISHED ||
+            event.type === EventType.RUN_ERROR)) {
+        if (event.type === EventType.RUN_ERROR) {
+            options.onInnerRunError?.(event);
+        }
+        return undefined;
+    }
+    if (!options.canonicalRun)
+        return params;
+    let stamped = stampedEvents.get(event);
+    if (!stamped) {
+        stamped = {
+            ...event,
+            threadId: options.canonicalRun.threadId,
+            runId: options.canonicalRun.runId,
+        };
+        stampedEvents.set(event, stamped);
+    }
+    return { ...params, event: stamped };
+}
+/**
+ * Fan one agent event stream out to both the provider renderer and a canonical
+ * runner subscriber. The proxy covers every current and future subscriber
+ * callback without keeping a second callback-name registry in Channels.
+ */
+export function mergeAgentSubscribers(first, second, options = {}) {
+    const stampedEvents = new WeakMap();
+    return new Proxy({}, {
+        get(_target, property) {
+            const firstCallback = first[property];
+            const secondCallback = second[property];
+            if (typeof firstCallback !== "function" &&
+                typeof secondCallback !== "function") {
+                return undefined;
+            }
+            return async (params) => {
+                const canonicalParams = canonicalizeSubscriberParams(params, options, stampedEvents);
+                if (canonicalParams === undefined)
+                    return undefined;
+                return invokeSubscriberPair(typeof firstCallback === "function"
+                    ? firstCallback
+                    : undefined, typeof secondCallback === "function"
+                    ? secondCallback
+                    : undefined, canonicalParams, options.onRendererError, options.isRendererClosed);
+            };
+        },
+    });
+}
+/** Convert an inner AG-UI error event into the error rejected by the outer run. */
+function errorFromInnerRun(event) {
+    const error = new Error(event.message);
+    error.name = "ChannelInnerRunError";
+    if (event.code)
+        error.code = event.code;
+    return error;
+}
+/**
+ * Emit one canonical lifecycle event through the same ingestion-first fanout
+ * used by streamed events.
+ */
+async function emitCanonicalLifecycleEvent(event, result, args, onRendererError, isRendererClosed) {
+    const canonicalRun = args.canonicalRun;
+    if (!canonicalRun)
+        return;
+    const input = {
+        threadId: canonicalRun.threadId,
+        runId: canonicalRun.runId,
+        messages: args.agent.messages,
+        state: args.agent.state,
+        tools: [...args.toolDescriptors],
+        context: [...args.context],
+        forwardedProps: {},
+    };
+    const baseParams = {
+        messages: args.agent.messages,
+        state: args.agent.state,
+        agent: args.agent,
+        input,
+    };
+    const ingestion = args.subscriber ?? {};
+    const renderer = args.renderer.subscriber;
+    const eventParams = { ...baseParams, event };
+    await invokeSubscriberPair(renderer.onEvent, ingestion.onEvent, eventParams, onRendererError, isRendererClosed);
+    if (event.type === EventType.RUN_STARTED) {
+        await invokeSubscriberPair(renderer.onRunStartedEvent, ingestion.onRunStartedEvent, eventParams, onRendererError, isRendererClosed);
+    }
+    else if (event.type === EventType.RUN_FINISHED) {
+        await invokeSubscriberPair(renderer.onRunFinishedEvent, ingestion.onRunFinishedEvent, {
+            ...baseParams,
+            event,
+            outcome: "success",
+            result,
+        }, onRendererError, isRendererClosed);
+    }
+    else if (event.type === EventType.RUN_ERROR) {
+        await invokeSubscriberPair(renderer.onRunErrorEvent, ingestion.onRunErrorEvent, eventParams, onRendererError, isRendererClosed);
+    }
+}
 /**
  * Drive the agent, executing frontend-tool calls and re-invoking until the
  * agent stops calling them (or we hit the iteration cap). On a captured
@@ -8,55 +183,130 @@ import { parseToolArgs, stringifyHandlerResult } from "./tools.js";
  */
 export async function runAgentLoop(args) {
     const { agent, renderer, tools, toolDescriptors, context, makeToolCtx, handleInterrupt, isAborted, initialResume, } = args;
+    let innerRunError;
+    let hasDeliveryError = false;
+    let deliveryError;
+    const deferRendererError = (error) => {
+        if (hasDeliveryError)
+            return;
+        hasDeliveryError = true;
+        deliveryError = error;
+    };
+    const isRendererClosed = () => hasDeliveryError;
+    const subscriber = args.subscriber || args.canonicalRun
+        ? mergeAgentSubscribers(renderer.subscriber, args.subscriber ?? {}, args.canonicalRun
+            ? {
+                canonicalRun: args.canonicalRun,
+                onInnerRunError: (event) => {
+                    innerRunError ??= errorFromInnerRun(event);
+                },
+                onRendererError: deferRendererError,
+                isRendererClosed,
+            }
+            : {})
+        : renderer.subscriber;
     const maxIterations = args.maxIterations ?? 6;
     const executed = new Set();
     let resume = initialResume;
-    for (let i = 0; i < maxIterations; i++) {
-        if (resume) {
-            await agent.runAgent({ forwardedProps: { command: resume } }, renderer.subscriber);
-            resume = undefined;
-        }
-        else {
-            await agent.runAgent({ tools: toolDescriptors, context: context }, renderer.subscriber);
-        }
-        if (isAborted?.())
-            return { iterations: i + 1, interrupted: false };
-        const pending = renderer.getPendingInterrupt();
-        if (pending) {
-            renderer.clearPendingInterrupt();
-            if (handleInterrupt)
-                await handleInterrupt(pending);
-            // ack-first: picker posted; thread.resume re-enters later
-            return { iterations: i + 1, interrupted: true };
-        }
-        const calls = renderer
-            .getCapturedToolCalls()
-            .filter((c) => tools.has(c.toolCallName) && !executed.has(c.toolCallId));
-        if (calls.length === 0)
-            return { iterations: i + 1, interrupted: false };
-        ensureAssistantToolCallMessage(agent, calls);
-        for (const call of calls) {
-            const tool = tools.get(call.toolCallName);
-            let result;
-            const parsed = await parseToolArgs(tool.parameters, call.toolCallArgs);
-            if (!parsed.ok) {
-                result = JSON.stringify({
-                    error: `invalid arguments: ${parsed.error}`,
-                });
+    const executeIterations = async () => {
+        for (let i = 0; i < maxIterations; i++) {
+            if (resume) {
+                await agent.runAgent({ forwardedProps: { command: resume } }, subscriber);
+                resume = undefined;
             }
             else {
-                try {
-                    result = stringifyHandlerResult(await tool.handler(parsed.value, makeToolCtx(call)));
+                await agent.runAgent({ tools: toolDescriptors, context: context }, subscriber);
+            }
+            if (innerRunError)
+                throw innerRunError;
+            if (isAborted?.())
+                return { iterations: i + 1, interrupted: false };
+            const pending = renderer.getPendingInterrupt();
+            if (pending) {
+                renderer.clearPendingInterrupt();
+                if (handleInterrupt)
+                    await handleInterrupt(pending);
+                // ack-first: picker posted; thread.resume re-enters later
+                return { iterations: i + 1, interrupted: true };
+            }
+            const calls = renderer
+                .getCapturedToolCalls()
+                .filter((c) => tools.has(c.toolCallName) && !executed.has(c.toolCallId));
+            if (calls.length === 0)
+                return { iterations: i + 1, interrupted: false };
+            ensureAssistantToolCallMessage(agent, calls);
+            for (const call of calls) {
+                const tool = tools.get(call.toolCallName);
+                let result;
+                const parsed = await parseToolArgs(tool.parameters, call.toolCallArgs);
+                if (!parsed.ok) {
+                    result = JSON.stringify({
+                        error: `invalid arguments: ${parsed.error}`,
+                    });
                 }
-                catch (err) {
-                    result = JSON.stringify({ error: err.message });
+                else {
+                    await args.canonicalRun?.beforeToolCall?.();
+                    try {
+                        result = stringifyHandlerResult(await tool.handler(parsed.value, makeToolCtx(call)));
+                    }
+                    catch (err) {
+                        if (isChannelDeliveryTerminatedError(err)) {
+                            // The provider already terminalled this delivery. Freeze renderer
+                            // fanout before the canonical RUN_ERROR is ingested, then stop the
+                            // loop instead of inviting the model to emit through a closed path.
+                            deferRendererError(err);
+                            throw err;
+                        }
+                        result = JSON.stringify({ error: err.message });
+                    }
                 }
+                pushToolResult(agent, call.toolCallId, result);
+                executed.add(call.toolCallId);
             }
-            pushToolResult(agent, call.toolCallId, result);
-            executed.add(call.toolCallId);
         }
+        return { iterations: maxIterations, interrupted: false };
+    };
+    if (!args.canonicalRun) {
+        return executeIterations();
+    }
+    const startEvent = {
+        type: EventType.RUN_STARTED,
+        threadId: args.canonicalRun.threadId,
+        runId: args.canonicalRun.runId,
+    };
+    try {
+        await emitCanonicalLifecycleEvent(startEvent, undefined, args, deferRendererError, isRendererClosed);
+        const result = await executeIterations();
+        const finishedEvent = {
+            type: EventType.RUN_FINISHED,
+            threadId: args.canonicalRun.threadId,
+            runId: args.canonicalRun.runId,
+        };
+        await emitCanonicalLifecycleEvent(finishedEvent, result, args, deferRendererError, isRendererClosed);
+        return hasDeliveryError ? { ...result, deliveryError } : result;
+    }
+    catch (error) {
+        const runError = {
+            type: EventType.RUN_ERROR,
+            threadId: args.canonicalRun.threadId,
+            runId: args.canonicalRun.runId,
+            message: error instanceof Error ? error.message : String(error),
+            ...(typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                typeof error.code === "string"
+                ? { code: error.code }
+                : {}),
+        };
+        try {
+            await emitCanonicalLifecycleEvent(runError, undefined, args, deferRendererError, isRendererClosed);
+        }
+        catch {
+            // Preserve the original run failure after canonical ingestion got its
+            // chance to record the terminal error.
+        }
+        throw error;
     }
-    return { iterations: maxIterations, interrupted: false };
 }
 /**
  * If the agent's latest message isn't already the assistant message that

package/dist/run-loop.test.js

@@ -48,6 +48,43 @@ describe("runAgentLoop", () => {
         expect(toolResult).toBeDefined();
         expect(toolResult.toolCallId).toBe("t1");
     });
+    it("keeps ordinary tool failures recoverable by the agent", async () => {
+        const renderer = makeFakeRunRenderer();
+        const tool = {
+            name: "recoverable",
+            description: "Fail without closing the delivery.",
+            parameters: z.object({}),
+            handler: () => {
+                throw new Error("try something else");
+            },
+        };
+        const agent = new FakeAgent([
+            (sub) => {
+                sub.onToolCallEndEvent?.({
+                    event: { toolCallId: "t1" },
+                    toolCallName: "recoverable",
+                    toolCallArgs: {},
+                });
+                sub.onRunFinishedEvent?.({ event: {} });
+            },
+            (sub) => {
+                sub.onRunFinishedEvent?.({ event: {} });
+            },
+        ]);
+        await runAgentLoop({
+            agent,
+            renderer,
+            tools: new Map([["recoverable", tool]]),
+            toolDescriptors,
+            context,
+            makeToolCtx: () => ({ thread: {}, platform: "fake" }),
+        });
+        expect(agent.runAgentCalls).toBe(2);
+        expect(agent.messages.find(({ role }) => role === "tool")).toMatchObject({
+            toolCallId: "t1",
+            content: JSON.stringify({ error: "try something else" }),
+        });
+    });
     it("posts the picker via handleInterrupt and returns without running tools", async () => {
         const renderer = makeFakeRunRenderer();
         const tools = new Map();

package/dist/sanitize-agent-events.d.ts

@@ -0,0 +1,24 @@
+import type { AbstractAgent } from "@ag-ui/client";
+/**
+ * Make an agent tolerate the AG-UI event streams real agents emit.
+ *
+ * `@ag-ui/langgraph` emits a `TOOL_CALL_START` whose `parentMessageId` is
+ * `null` — notably the tool call that triggers an interrupt. The AG-UI schema
+ * declares that field optional but never nullable, so `HttpAgent`'s transform
+ * re-validates the streamed event, Zod rejects it ("Expected string, received
+ * null"), and a single rejected event aborts the entire run. That breaks
+ * LangGraph interrupts / human-in-the-loop on every Channel platform.
+ *
+ * The fix is applied at the transport rather than by replacing the event
+ * transform, which keeps everything else the stock path does — protobuf
+ * content-type negotiation, `AbortError` → `RUN_ERROR`, and strict validation
+ * of every field except the coerced one. Agents that do not stream over HTTP
+ * are returned untouched: nothing re-validates their events, so there is
+ * nothing to coerce.
+ *
+ * Channels apply this by default; opt out with
+ * `createChannel({ sanitizeAgentEvents: false })`. Remove it once
+ * `@ag-ui/langgraph` stops emitting the null (CopilotKit OSS-691).
+ */
+export declare function sanitizeAgentEventStream<T extends AbstractAgent>(agent: T): T;
+//# sourceMappingURL=sanitize-agent-events.d.ts.map

package/dist/sanitize-agent-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-agent-events.d.ts","sourceRoot":"","sources":["../src/sanitize-agent-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA8DnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA0B7E"}

package/dist/sanitize-agent-events.js

@@ -0,0 +1,88 @@
+/**
+ * Coerce `"<field>": null` to `""` on the wire. Targeted on purpose: we only
+ * touch fields where a `null` is known to come through from `@ag-ui/langgraph`
+ * and would otherwise trip strict client-side validation.
+ *
+ * Matching the quoted key means an escaped occurrence inside a JSON string
+ * (`\"parentMessageId\":null`, e.g. nested in a `rawEvent` payload) is left
+ * alone — the backslash breaks the match.
+ */
+const NULLABLE_ID_FIELDS = /("(?:parentMessageId)"\s*:\s*)null/g;
+/** Marks a transport we have already wrapped, so re-entry is a no-op. */
+const SANITIZED = Symbol.for("copilotkit.channels.sanitizedTransport");
+/**
+ * Rewrite SSE frames as they stream, coercing the known nullable-string fields.
+ *
+ * Buffering on the `\n\n` frame delimiter is what makes this safe: a `null`
+ * split across two transport chunks is still matched, and every other byte —
+ * comments, keep-alives, unrelated fields — is re-emitted verbatim.
+ */
+function coerceNullableIds() {
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    const encoder = new TextEncoder();
+    let buffered = "";
+    const coerce = (frame) => encoder.encode(frame.replace(NULLABLE_ID_FIELDS, '$1""'));
+    return new TransformStream({
+        transform(chunk, controller) {
+            buffered += decoder.decode(chunk, { stream: true });
+            const frames = buffered.split("\n\n");
+            buffered = frames.pop() ?? "";
+            for (const frame of frames)
+                controller.enqueue(coerce(`${frame}\n\n`));
+        },
+        flush(controller) {
+            buffered += decoder.decode();
+            if (buffered)
+                controller.enqueue(coerce(buffered));
+        },
+    });
+}
+/** Does this agent stream its events over HTTP, and therefore re-validate them? */
+function hasHttpTransport(agent) {
+    const candidate = agent;
+    return (typeof candidate.fetch === "function" && typeof candidate.url === "string");
+}
+/**
+ * Make an agent tolerate the AG-UI event streams real agents emit.
+ *
+ * `@ag-ui/langgraph` emits a `TOOL_CALL_START` whose `parentMessageId` is
+ * `null` — notably the tool call that triggers an interrupt. The AG-UI schema
+ * declares that field optional but never nullable, so `HttpAgent`'s transform
+ * re-validates the streamed event, Zod rejects it ("Expected string, received
+ * null"), and a single rejected event aborts the entire run. That breaks
+ * LangGraph interrupts / human-in-the-loop on every Channel platform.
+ *
+ * The fix is applied at the transport rather than by replacing the event
+ * transform, which keeps everything else the stock path does — protobuf
+ * content-type negotiation, `AbortError` → `RUN_ERROR`, and strict validation
+ * of every field except the coerced one. Agents that do not stream over HTTP
+ * are returned untouched: nothing re-validates their events, so there is
+ * nothing to coerce.
+ *
+ * Channels apply this by default; opt out with
+ * `createChannel({ sanitizeAgentEvents: false })`. Remove it once
+ * `@ag-ui/langgraph` stops emitting the null (CopilotKit OSS-691).
+ */
+export function sanitizeAgentEventStream(agent) {
+    if (!hasHttpTransport(agent))
+        return agent;
+    const transport = agent.fetch;
+    if (transport[SANITIZED])
+        return agent;
+    const sanitized = async (input, init) => {
+        const response = await transport(input, init);
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!response.ok ||
+            !response.body ||
+            !contentType.includes("text/event-stream"))
+            return response;
+        return new Response(response.body.pipeThrough(coerceNullableIds()), {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+    sanitized[SANITIZED] = true;
+    agent.fetch = sanitized;
+    return agent;
+}

package/dist/sanitize-agent-events.test.d.ts

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

package/dist/sanitize-agent-events.test.d.ts.map

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