🐛 Bug: `finalizeRunEvents` appends `TEXT_MESSAGE_END` after `RUN_ERROR` — stop button crashes with "run has already errored"

[lukekh]

♻️ Reproduction Steps

1. Run the standard Node-proxy setup: a CopilotRuntime with an HttpAgent pointing at a remote AG-UI endpoint, served via copilotRuntimeNodeHttpEndpoint. Frontend uses CopilotChat.
2. Start a chat and send a message that produces a streamed assistant response of a few seconds.
3. While the assistant is still streaming text (i.e. between TEXT_MESSAGE_START and TEXT_MESSAGE_END), press the Stop button.
4. Observe the console error (below). The assistant message is left in a broken state and the chat becomes unreliable.

Minimal server setup that reproduces:

const { CopilotRuntime, EmptyAdapter, copilotRuntimeNodeHttpEndpoint } = require('@copilotkit/runtime');
const { HttpAgent } = require('@ag-ui/client');

const runtime = new CopilotRuntime({
  agents: { my_agent: new HttpAgent({ url: 'http://localhost:8000/api' }) },
});
const handler = copilotRuntimeNodeHttpEndpoint({ runtime, serviceAdapter: new EmptyAdapter(), endpoint: '/copilotkit' });

…where http://localhost:8000/api is any AG-UI-compliant agent that streams a TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT… response and does not close the message before the run is aborted (e.g. pydantic-ai's AGUIAdapter — see pydantic/pydantic-ai#3108).

✅ Expected Behavior

Pressing Stop should end the run cleanly: the open text message is closed and a single terminal event (RUN_FINISHED) is emitted. No console error. The chat remains usable for the next message.

Per the AG-UI spec invariant: at most one terminal event per run, and all sub-events (TEXT_MESSAGE_END, TOOL_CALL_END) must close before the terminal.

❌ Actual Behavior

The browser throws:

Agent execution failed: Cannot send event type 'TEXT_MESSAGE_END':
The run has already errored with 'RUN_ERROR'. No further events can be sent.

Screenshots

No response

𝌚 CopilotKit Version

@copilotkit/react-core 1.62.2
@copilotkit/react-ui 1.62.2
@copilotkit/runtime 1.62.2

📄 Logs (Optional)

Error message in the browser:

Agent execution failed: D: Cannot send event type 'TEXT_MESSAGE_END': The run has already errored with 'RUN_ERROR'. No further events can be sent.


Example data in response

...

data: {"type":"TEXT_MESSAGE_CONTENT","timestamp":1783057434585,"messageId":"225f30a2-c662-4d0d-a05e-789cb51e17cc","delta":" frames"}

data: {"type":"RUN_ERROR","message":"This operation was aborted","code":"abort","rawEvent":{}}

data: {"type":"TEXT_MESSAGE_END","messageId":"225f30a2-c662-4d0d-a05e-789cb51e17cc"}

[copilotkit-support-bot]

The codebase analysis attributes the issue to finalizeRunEvents appending cleanup events after a terminal RUN_ERROR. It recommends skipping cleanup if a terminal event already exists in the stream to comply with the AG-UI protocol.

Details

To address the reported bug where finalizeRunEvents appends cleanup events (like TEXT_MESSAGE_END) after a terminal event (like RUN_ERROR), I have analyzed the implementation in packages/shared/src/finalize-events.ts.

Analysis of the Bug

The current implementation of finalizeRunEvents collects all unclosed message IDs and tool calls and appends their respective END events to the result array, regardless of whether a terminal event (RUN_FINISHED or RUN_ERROR) is already present in the event stream.

In a typical CopilotRuntime setup:

1. The runtime receives a RUN_ERROR from an agent (e.g., due to an abort).
2. The runtime immediate forwards this RUN_ERROR to the client.
3. The runtime's finalization logic calls finalizeRunEvents.
4. finalizeRunEvents sees that a message was started but never ended, so it appends a TEXT_MESSAGE_END event to the appended list.
5. The runtime sends these appended events to the client.
6. The client receive a TEXT_MESSAGE_END after a RUN_ERROR, which violates the AG-UI protocol invariant and causes a crash.

Proposed Solution

finalizeRunEvents should be modified to avoid appending cleanup events if a terminal event is already present in the stream. Alternatively, if it must cleanup, it should ensure those events are return/emitted before the terminal event.

However, since the callers often emit the terminal event immediately upon receipt, the safest fix within finalizeRunEvents is to skip cleanup if the run is already terminated, as the protocol forbids further events.

Recommended Change in packages/shared/src/finalize-events.ts:

Modify finalizeRunEvents to check for a terminal event before appending message and tool closures.

// packages/shared/src/finalize-events.ts

export function finalizeRunEvents(
  events: BaseEvent[],
  options: FinalizeRunOptions = {},
): BaseEvent[] {
  // ... (previous logic for collecting openMessageIds and openToolCalls)

  const hasRunFinished = events.some(
    (event) => event.type === EventType.RUN_FINISHED,
  );
  const hasRunError = events.some(
    (event) => event.type === EventType.RUN_ERROR,
  );
  const hasTerminalEvent = hasRunFinished || hasRunError;
  const terminalEventMissing = !hasTerminalEvent;

  // FIX: If a terminal event already exists, we cannot append more events
  // as it would violate the AG-UI protocol.
  if (hasTerminalEvent) {
    return [];
  }

  for (const messageId of openMessageIds) {
    const endEvent = {
      type: EventType.TEXT_MESSAGE_END,
      messageId,
    } as BaseEvent;
    events.push(endEvent);
    appended.push(endEvent);
  }

  // ... (rest of the tool call cleanup and terminal event generation)
}

Affected Files

• packages/shared/src/finalize-events.ts: The core logic for event finalization.
• packages/runtime/src/v2/runtime/runner/in-memory.ts and intelligence.ts: Callers of this function in the runtime.

Verification and Confidence

• Confidence: High. The provided logs clearly show the TEXT_MESSAGE_END following RUN_ERROR, and the code confirms this behavior.
• Protocol Adherence: The AG-UI protocol states that no events can follow a terminal event. Stopping the stop-gap cleanup when a terminal event is already present is the correct way to respect this invariant in a proxy/streaming context.

Documentation References:

• CopilotKit Runtime Reference
• Agent Protocol Concepts

Example Links:

• Runtime Implementation

---

Was this helpful?

If this solution worked for you, please click on the appropriate option below to help us improve:

✅ This was helpful | ❌ Need more help

[morgan-coded]

I can take a small pass at this if you want it. My read is that finalizeRunEvents should not append cleanup events after a terminal RUN_ERROR, or it needs to ensure the cleanup happens before the terminal event. I would keep the PR focused on that AG-UI invariant with a regression around the stop-button/aborted-stream case.

Does that shape sound right?