fix(core,react-core): handle onRunErrorEvent in useAgent and document in subscribeToAgentWithOptions

React's useAgent was missing onRunErrorEvent under OnRunStatusChanged,
causing isRunning to stay true after protocol-level RUN_ERROR events
(infinite spinner). Angular already handled this via PR CopilotKit#3749.

Also updates SubscribeToAgentSubscriber JSDoc to accurately document
onRunErrorEvent as the sixth allowed callback with rationale for its
inclusion despite having stopPropagation in its return type, and adds
a core-level test for onRunErrorEvent firing immediately during
throttle windows.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mxmzb

packages/core/src/__tests__/core-subscribe-to-agent.test.ts

@@ -60,7 +60,11 @@ function notifyStateChanged(agent: TestAgent) {
 
 function notifyLifecycle(
   agent: TestAgent,
-  event: "onRunInitialized" | "onRunFinalized" | "onRunFailed",
+  event:
+    | "onRunInitialized"
+    | "onRunFinalized"
+    | "onRunFailed"
+    | "onRunErrorEvent",
 ) {
   const base: AgentSubscriberParams = {
     messages: agent.messages,
@@ -71,6 +75,12 @@ function notifyLifecycle(
   if (event === "onRunFailed") {
     const params = { ...base, error: new Error("run failed") };
     agent.subscribers.forEach((s) => s.onRunFailed?.(params));
+  } else if (event === "onRunErrorEvent") {
+    const params = {
+      ...base,
+      event: { type: "RUN_ERROR", message: "backend error" } as any,
+    };
+    agent.subscribers.forEach((s) => s.onRunErrorEvent?.(params));
   } else {
     agent.subscribers.forEach((s) => s[event]?.(base));
   }
@@ -397,6 +407,25 @@ describe("CopilotKitCore.subscribeToAgentWithOptions", () => {
     expect(onRunFailed).toHaveBeenCalledTimes(1);
   });
 
+  it("onRunErrorEvent fires immediately during throttle window", () => {
+    const onMessages = vi.fn();
+    const onRunErrorEvent = vi.fn();
+
+    core.subscribeToAgentWithOptions(
+      agent,
+      { onMessagesChanged: onMessages, onRunErrorEvent },
+      { throttleMs: 100 },
+    );
+
+    // Start throttle window
+    agent.messages = [userMsg("1", "a")];
+    notifyMessagesChanged(agent);
+
+    // Protocol-level RUN_ERROR — should fire immediately (not throttled)
+    notifyLifecycle(agent, "onRunErrorEvent");
+    expect(onRunErrorEvent).toHaveBeenCalledTimes(1);
+  });
+
   // -------------------------------------------------------------------------
   // Only subscribed callbacks are wrapped
   // -------------------------------------------------------------------------

packages/core/src/core/core.ts

@@ -203,10 +203,11 @@ const ALLOWED_KEYS: ReadonlySet<(typeof SUBSCRIBE_TO_AGENT_KEYS)[number]> =
 
 /**
  * The subset of `AgentSubscriber` callbacks accepted by
- * {@link CopilotKitCore.subscribeToAgentWithOptions}. Only the five callbacks listed
- * in {@link SUBSCRIBE_TO_AGENT_KEYS} are supported: `onMessagesChanged`,
- * `onStateChanged`, and the three run lifecycle callbacks
- * (`onRunInitialized`, `onRunFinalized`, `onRunFailed`).
+ * {@link CopilotKitCore.subscribeToAgentWithOptions}. Only the callbacks
+ * listed in {@link SUBSCRIBE_TO_AGENT_KEYS} are supported:
+ * `onMessagesChanged`, `onStateChanged`, and the four run lifecycle
+ * callbacks (`onRunInitialized`, `onRunFinalized`, `onRunFailed`,
+ * `onRunErrorEvent`).
  *
  * Two categories of `AgentSubscriber` members are excluded:
  *
@@ -220,9 +221,18 @@ const ALLOWED_KEYS: ReadonlySet<(typeof SUBSCRIBE_TO_AGENT_KEYS)[number]> =
  *   same data at a coarser granularity, and throttling per-item callbacks
  *   would have different semantic expectations.
  *
- * Note: the included lifecycle callbacks also return
- * `Omit<AgentStateMutation, "stopPropagation">`. On the error path,
- * `safeCall` discards those return values (see its inline documentation).
+ * `onRunErrorEvent` is technically an AG-UI event handler (its return type
+ * includes `stopPropagation`), but it is included here because all
+ * framework consumers need it to reset `isRunning` on protocol-level
+ * `RUN_ERROR` events — distinct from `onRunFailed` which handles local
+ * exceptions like network errors. In practice, consumers return `void`
+ * from this callback, so the `stopPropagation` semantics are unused.
+ *
+ * Note: the included lifecycle callbacks return
+ * `Omit<AgentStateMutation, "stopPropagation">` (or full
+ * `AgentStateMutation` in the case of `onRunErrorEvent`). On the error
+ * path, `safeCall` discards those return values (see its inline
+ * documentation).
  *
  * Use `agent.subscribe()` directly when event mutation or per-item
  * notification semantics are needed.

packages/react-core/src/v2/hooks/use-agent.tsx

@@ -41,7 +41,7 @@ export interface UseAgentProps {
    * provider specifies a non-zero `defaultThrottleMs`.
    *
    * Run lifecycle callbacks (`onRunInitialized`, `onRunFinalized`,
-   * `onRunFailed`) always fire immediately.
+   * `onRunFailed`, `onRunErrorEvent`) always fire immediately.
    *
    * @default undefined
    * When unset, inherits from the provider's `defaultThrottleMs`;
@@ -301,6 +301,9 @@ export function useAgent({
       handlers.onRunInitialized = batchedForceUpdate;
       handlers.onRunFinalized = batchedForceUpdate;
       handlers.onRunFailed = batchedForceUpdate;
+      // Protocol-level RUN_ERROR event (distinct from onRunFailed which
+      // handles local exceptions like network errors).
+      handlers.onRunErrorEvent = batchedForceUpdate;
     }
 
     const subscription = copilotkit.subscribeToAgentWithOptions(