fix(react-core): type the active-run completion contract and serialize the suggestion send path

Replace the brittle `"activeRunCompletionPromise" in agent` probe + double
`as unknown as` casts in CopilotChat with a typed `RunCompletionAware`
contract plus an `isRunCompletionAware` type guard, both exported from core.
IntelligenceAgent now declares the property and implements the interface, so
the in-flight-run await is reachable without a cast and non-Intelligence
agents still degrade safely. Cast sites in the attachments/e2e tests and the
MockStepwiseAgent helper are updated to the typed accessor.

Factor the await-then-send logic into a shared `waitForActiveRunToSettle`
helper and call it from BOTH onSubmitInput and handleSelectSuggestion. This
closes the suggestion-path in-flight gap: selecting a suggestion mid-run no
longer pre-empts/aborts the active run (e.g. an interrupt RESUME) — the same
regression PR CopilotKit#5195 fixed for the typed-Enter path. Adds a red-green
regression test that parks the suggestion send on the in-flight promise.

Author: jpr5

packages/core/src/intelligence-agent.ts

@@ -1,11 +1,13 @@
-import {
-  AbstractAgent,
+import type {
   RunAgentInput,
   RunAgentParameters,
   RunAgentResult,
   AgentSubscriber,
-  EventType,
   BaseEvent,
+} from "@ag-ui/client";
+import {
+  AbstractAgent,
+  EventType,
   randomUUID,
   transformChunks,
   structuredClone_,
@@ -15,15 +17,14 @@ import {
   EMPTY,
   Subject,
   Notification,
-  Observable,
   defer,
   dematerialize,
   lastValueFrom,
   merge,
   switchMap,
   throwError,
 } from "rxjs";
-import type { ObservableNotification } from "rxjs";
+import type { ObservableNotification, Observable } from "rxjs";
 import {
   catchError,
   endWith,
@@ -42,13 +43,15 @@ import { phoenixExponentialBackoff } from "@copilotkit/shared";
 import {
   ɵphoenixChannel$,
   ɵphoenixSocket$,
-  type ɵPhoenixChannelSession,
-  type ɵPhoenixSocketSession,
   ɵjoinPhoenixChannel$,
   ɵobservePhoenixSocketSignals$,
   ɵobservePhoenixSocketHealth$,
   ɵobservePhoenixEvent$,
 } from "./utils/phoenix-observable";
+import type {
+  ɵPhoenixChannelSession,
+  ɵPhoenixSocketSession,
+} from "./utils/phoenix-observable";
 
 const CLIENT_AG_UI_EVENT = "ag_ui_event";
 const REPLAY_COMPLETE_EVENT = "replay_complete";
@@ -78,6 +81,45 @@ export class AgentThreadLockedError extends Error {
   }
 }
 
+/**
+ * Typed contract for agents that expose the completion promise of their
+ * currently in-flight run.
+ *
+ * `IntelligenceAgent` resolves this promise once a run's observable pipeline
+ * finalizes (see {@link IntelligenceAgent.connectAgent}). Consumers (e.g. the
+ * v2 `CopilotChat` send-serialization path) await it to let an in-flight run —
+ * notably an interrupt RESUME — finish before dispatching a new run, instead
+ * of pre-empting it.
+ *
+ * The base `AbstractAgent` from `@ag-ui/client` does NOT declare this property,
+ * so it is reachable only through this contract plus the
+ * {@link isRunCompletionAware} type guard. This keeps callers off `as unknown`
+ * casts while still degrading safely for agents that don't implement it.
+ */
+export interface RunCompletionAware {
+  /**
+   * Resolves when the active run's pipeline finalizes (completes, errors, or is
+   * detached). `undefined` when no run is in flight.
+   */
+  readonly activeRunCompletionPromise?: Promise<void>;
+}
+
+/**
+ * Type guard for {@link RunCompletionAware}. Returns true when `agent` exposes
+ * an `activeRunCompletionPromise` property, so callers can await an in-flight
+ * run without an `as unknown as` cast. Returns false for agents that don't
+ * implement the contract, letting the caller skip the await and degrade safely.
+ */
+export function isRunCompletionAware(
+  agent: unknown,
+): agent is RunCompletionAware {
+  return (
+    typeof agent === "object" &&
+    agent !== null &&
+    "activeRunCompletionPromise" in agent
+  );
+}
+
 export interface IntelligenceAgentConfig {
   /** Phoenix websocket URL, e.g. "ws://localhost:4000/socket" */
   url: string;
@@ -93,12 +135,21 @@ export interface IntelligenceAgentConfig {
   credentials?: RequestCredentials;
 }
 
-export class IntelligenceAgent extends AbstractAgent {
+export class IntelligenceAgent
+  extends AbstractAgent
+  implements RunCompletionAware
+{
   private config: IntelligenceAgentConfig;
   private socket: Socket | null = null;
   private activeChannel: Channel | null = null;
   private canonicalRunId: string | null = null;
   private sharedState: IntelligenceAgentSharedState;
+  /**
+   * Resolves when the active run's pipeline finalizes; `undefined` between runs.
+   * Set/cleared inside {@link connectAgent}'s observable lifecycle. Declared
+   * here so {@link RunCompletionAware} consumers can read it without a cast.
+   */
+  activeRunCompletionPromise?: Promise<void>;
 
   constructor(
     config: IntelligenceAgentConfig,
@@ -177,7 +228,7 @@ export class IntelligenceAgent extends AbstractAgent {
 
       self.activeRunDetach$ = new Subject<void>();
       let resolveCompletion: (() => void) | undefined;
-      self.activeRunCompletionPromise = new Promise<void>((resolve) => {
+      this.activeRunCompletionPromise = new Promise<void>((resolve) => {
         resolveCompletion = resolve;
       });
 
@@ -202,7 +253,7 @@ export class IntelligenceAgent extends AbstractAgent {
             this.onFinalize(input, subscribers);
             resolveCompletion?.();
             resolveCompletion = undefined;
-            self.activeRunCompletionPromise = undefined;
+            this.activeRunCompletionPromise = undefined;
             self.activeRunDetach$ = undefined;
           }),
         ),

packages/react-core/src/v2/__tests__/utils/test-helpers.tsx

@@ -4,26 +4,39 @@ import { CopilotKitProvider } from "../../providers/CopilotKitProvider";
 import { CopilotChat } from "../../components/chat/CopilotChat";
 import { CopilotChatConfigurationProvider } from "../../providers/CopilotChatConfigurationProvider";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
-import {
-  AbstractAgent,
-  EventType,
-  type BaseEvent,
-  type RunAgentInput,
-} from "@ag-ui/client";
-import { Observable, Subject, from, delay } from "rxjs";
-import {
+import { AbstractAgent, EventType } from "@ag-ui/client";
+import type { BaseEvent, RunAgentInput } from "@ag-ui/client";
+import type { Observable } from "rxjs";
+import { Subject, from, delay } from "rxjs";
+import type { RunCompletionAware } from "@copilotkit/core";
+import type {
   ReactActivityMessageRenderer,
   ReactToolCallRenderer,
 } from "../../types";
-import { ReactCustomMessageRenderer } from "../../types/react-custom-message-renderer";
+import type { ReactCustomMessageRenderer } from "../../types/react-custom-message-renderer";
 
 /**
  * A controllable mock agent for deterministic E2E testing.
  * Exposes emit() and complete() methods to drive agent events step-by-step.
+ *
+ * Implements {@link RunCompletionAware} so tests can open the send-serialization
+ * await window (`onSubmitInput`/`handleSelectSuggestion` await this before
+ * dispatching) by assigning a controllable completion promise — without an
+ * `as unknown as` cast.
  */
-export class MockStepwiseAgent extends AbstractAgent {
+export class MockStepwiseAgent
+  extends AbstractAgent
+  implements RunCompletionAware
+{
   private subject = new Subject<BaseEvent>();
 
+  /**
+   * Resolves when the active run's pipeline finalizes; `undefined` between runs.
+   * Tests set this to a controllable promise to exercise the await-then-send
+   * serialization path. Mirrors the real `IntelligenceAgent` contract.
+   */
+  activeRunCompletionPromise?: Promise<void>;
+
   /**
    * Emit a single agent event
    */

packages/react-core/src/v2/components/chat/CopilotChat.tsx

@@ -16,6 +16,7 @@ import {
 } from "@copilotkit/shared";
 import type { AttachmentsConfig, InputContent } from "@copilotkit/shared";
 import type { Suggestion, CopilotKitCoreErrorCode } from "@copilotkit/core";
+import { isRunCompletionAware } from "@copilotkit/core";
 import React, {
   useCallback,
   useEffect,
@@ -295,6 +296,43 @@ export function CopilotChat({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [resolvedThreadId, agent, resolvedAgentId, hasExplicitThreadId]);
 
+  // Serializes consecutive sends: if a run is already in flight, let it finish
+  // before dispatching the next message instead of pre-empting it.
+  // `copilotkit.runAgent` would otherwise call `agent.detachActiveRun()` and
+  // ABORT the in-flight run. That abort is harmful when the in-flight run is an
+  // interrupt RESUME: the resume re-enters and completes the paused agent
+  // graph, and aborting it mid-flight leaves the graph paused — so the new
+  // message lands as another resume of the SAME paused graph (re-interrupting
+  // with no fresh payload) instead of starting a clean new turn. This is the
+  // consecutive-interrupt regression: pick turn-1's slot (kicks off the
+  // resume), then immediately send turn-2's message — without waiting, turn-2
+  // aborts the resume and the 2nd interrupt's card never mounts. Awaiting the
+  // active run's completion serializes the two turns so the resume finishes
+  // (graph completes) before the new message starts a fresh run.
+  //
+  // The completion promise lives only on `IntelligenceAgent` (via the
+  // `RunCompletionAware` contract), not on the `AbstractAgent` type held here —
+  // so it is reached through a type guard, not a cast. Agents that don't
+  // implement the contract degrade safely (the await is skipped).
+  const waitForActiveRunToSettle = useCallback(async () => {
+    if (
+      agent.isRunning &&
+      isRunCompletionAware(agent) &&
+      agent.activeRunCompletionPromise
+    ) {
+      try {
+        await agent.activeRunCompletionPromise;
+      } catch (error) {
+        // The in-flight run rejected — proceed with the new send anyway,
+        // but log so a chronically-failing in-flight run is observable.
+        console.error(
+          "CopilotChat: in-flight run rejected while queuing send",
+          error,
+        );
+      }
+    }
+  }, [agent]);
+
   const onSubmitInput = useCallback(
     async (value: string) => {
       // Block if uploads in progress (fast fail against current state before
@@ -318,40 +356,8 @@ export function CopilotChat({
       setInputValue("");
 
       // If a run is already in flight, let it finish before sending the new
-      // message instead of pre-empting it. `copilotkit.runAgent` would
-      // otherwise call `agent.detachActiveRun()` and ABORT the in-flight run.
-      // That abort is harmful when the in-flight run is an interrupt RESUME:
-      // the resume re-enters and completes the paused agent graph, and
-      // aborting it mid-flight leaves the graph paused — so this new message
-      // lands as another resume of the SAME paused graph (re-interrupting
-      // with no fresh payload) instead of starting a clean new turn. This is
-      // the consecutive-interrupt regression: pick turn-1's slot (kicks off
-      // the resume), then immediately send turn-2's message — without waiting,
-      // turn-2 aborts the resume and the 2nd interrupt's card never mounts.
-      // Awaiting the active run's completion serializes the two turns so the
-      // resume finishes (graph completes) before the new message starts a
-      // fresh run.
-      if (
-        agent.isRunning &&
-        "activeRunCompletionPromise" in agent &&
-        (agent as unknown as { activeRunCompletionPromise?: Promise<unknown> })
-          .activeRunCompletionPromise
-      ) {
-        try {
-          await (
-            agent as unknown as {
-              activeRunCompletionPromise?: Promise<unknown>;
-            }
-          ).activeRunCompletionPromise;
-        } catch (error) {
-          // The in-flight run rejected — proceed with the new send anyway,
-          // but log so a chronically-failing in-flight run is observable.
-          console.error(
-            "CopilotChat: in-flight run rejected while queuing send",
-            error,
-          );
-        }
-      }
+      // message instead of pre-empting it (see waitForActiveRunToSettle).
+      await waitForActiveRunToSettle();
 
       // Re-check the uploading guard against LIVE attachment state: an upload
       // can start (or stay in flight) during the await above, so a snapshot
@@ -409,11 +415,17 @@ export function CopilotChat({
     },
     // copilotkit is intentionally excluded — it is a stable ref that never changes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [agent, consumeAttachments],
+    [agent, consumeAttachments, waitForActiveRunToSettle],
   );
 
   const handleSelectSuggestion = useCallback(
     async (suggestion: Suggestion) => {
+      // Mirror onSubmitInput's send-serialization: if a run is in flight, wait
+      // for it to settle before dispatching, so selecting a suggestion mid-run
+      // does NOT pre-empt/abort the active run (the same #5195 fix the
+      // typed-Enter path got — here for the suggestion path).
+      await waitForActiveRunToSettle();
+
       agent.addMessage({
         id: randomUUID(),
         role: "user",
@@ -430,7 +442,7 @@ export function CopilotChat({
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [agent],
+    [agent, waitForActiveRunToSettle],
   );
 
   const stopCurrentRun = useCallback(() => {

packages/react-core/src/v2/components/chat/__tests__/CopilotChat.attachments.test.tsx

@@ -221,9 +221,7 @@ describe("CopilotChat attachments", () => {
         await waitFor(() => {
           expect(agent.isRunning).toBe(true);
         });
-        (
-          agent as unknown as { activeRunCompletionPromise?: Promise<void> }
-        ).activeRunCompletionPromise = inFlight;
+        agent.activeRunCompletionPromise = inFlight;
 
         // No attachments yet — the pre-await guard passes. Fire the send; it
         // parks on the in-flight run's completion promise.