fix(runtime): address CR loop round 1 findings

Source fixes:
- Fix TOCTOU race in concurrent run guard — set abortController
  synchronously before Observable creation, closing the window where
  two run() calls could both pass the guard
- Add JSON.stringify try/catch in TanStack TOOL_CALL_RESULT handler
  (matching existing aisdk.ts protection against circular refs)
- Use role allowlist (user/assistant/tool) instead of denylist in
  convertInputToTanStackAI to exclude activity/reasoning roles
- Change error+abort handler from break to return in aisdk converter
  to stop processing after error during abort
- Fix version-pinned comments (remove "AI SDK 5.0" reference)

Test fixes:
- Add timedOut flag to collectEventsIncludingErrors to distinguish
  hung observables from normal completion
- Add clearTimeout on success/error to prevent timer leaks
- Remove timing-dependent setTimeout in concurrent run guard test

Docs fixes:
- Split imports: copilotRuntimeNextJSAppRouterEndpoint from
  @copilotkit/runtime, Agent/converters from @copilotkit/runtime/v2
- Fix forwardedProps example: use CopilotKit properties prop
- Fix useCopilotChat → useCoAgent for state management reference
- Fix model syntax colon → slash (openai/gpt-4o)

Author: AlemTuzlak

docs/snippets/shared/backend/custom-agent.mdx

@@ -8,7 +8,7 @@ The `Agent` class gives you full control over the LLM call. You provide a factor
 | | `BuiltInAgent` | `Agent` |
 |---|---|---|
 | **Setup** | Minimal — pass a model string, CopilotKit handles the rest | You own the LLM call and stream |
-| **Model resolution** | Built-in (`"openai:gpt-4o"`) | You set up the model yourself |
+| **Model resolution** | Built-in (`"openai/gpt-4o"`) | You set up the model yourself |
 | **Tools, MCP, state tools** | Automatically wired | You wire them in your factory |
 | **AI SDK support** | Vercel AI SDK only | Any backend: AI SDK, TanStack AI, or custom |
 | **Best for** | Quick setup, standard use cases | Full control, non-standard backends, async initialization |
@@ -27,6 +27,8 @@ You have an existing LLM backend and you want a CopilotKit copilot using it. Pic
 import {
   CopilotRuntime,
   copilotRuntimeNextJSAppRouterEndpoint,
+} from "@copilotkit/runtime";
+import {
   Agent,
   convertMessagesToVercelAISDKMessages,
 } from "@copilotkit/runtime/v2";
@@ -62,6 +64,8 @@ export const POST = async (req: NextRequest) => {
 import {
   CopilotRuntime,
   copilotRuntimeNextJSAppRouterEndpoint,
+} from "@copilotkit/runtime";
+import {
   Agent,
   convertInputToTanStackAI,
 } from "@copilotkit/runtime/v2";
@@ -100,8 +104,8 @@ export const POST = async (req: NextRequest) => {
 import {
   CopilotRuntime,
   copilotRuntimeNextJSAppRouterEndpoint,
-  Agent,
-} from "@copilotkit/runtime/v2";
+} from "@copilotkit/runtime";
+import { Agent } from "@copilotkit/runtime/v2";
 import { EventType, type BaseEvent } from "@ag-ui/client";
 import { NextRequest } from "next/server";
 
@@ -483,15 +487,17 @@ const agent = new Agent({
 </Tab>
 </Tabs>
 
-Forward props from the frontend using `useCoAgent` or `CopilotChat`:
+Forward props from the frontend using the `CopilotKit` provider's `properties` prop:
 
 ```tsx title="app/page.tsx"
-<CopilotChat forwardedProps={{ model: "anthropic/claude-sonnet-4", temperature: 0.3 }} />
+<CopilotKit properties={{ model: "anthropic/claude-sonnet-4", temperature: 0.3 }}>
+  <CopilotChat />
+</CopilotKit>
 ```
 
 ### With State Tools
 
-`Agent` does not inject state management tools automatically. If your app uses shared state (`useCopilotChat` with state), add the tools yourself:
+`Agent` does not inject state management tools automatically. If your app uses shared state (`useCoAgent` with state), add the tools yourself:
 
 <Tabs items={["AI SDK", "TanStack AI"]}>
 <Tab value="AI SDK">

packages/runtime/src/agent/__tests__/agent-test-helpers.ts

@@ -282,6 +282,8 @@ export interface CollectedEventsResult {
   events: BaseEvent[];
   /** Whether the observable completed via error (true) or normal completion (false) */
   errored: boolean;
+  /** Whether the safety timeout fired (indicates a hung observable) */
+  timedOut: boolean;
 }
 
 /**
@@ -294,17 +296,21 @@ export async function collectEventsIncludingErrors(
 ): Promise<CollectedEventsResult> {
   return new Promise((resolve) => {
     const events: BaseEvent[] = [];
+    const timeoutId = setTimeout(() => {
+      subscription.unsubscribe();
+      resolve({ events, errored: false, timedOut: true });
+    }, 5000);
     const subscription = observable.subscribe({
       next: (event) => events.push(event),
-      error: () => resolve({ events, errored: true }),
-      complete: () => resolve({ events, errored: false }),
+      error: () => {
+        clearTimeout(timeoutId);
+        resolve({ events, errored: true, timedOut: false });
+      },
+      complete: () => {
+        clearTimeout(timeoutId);
+        resolve({ events, errored: false, timedOut: false });
+      },
     });
-
-    // Prevent hanging tests
-    setTimeout(() => {
-      subscription.unsubscribe();
-      resolve({ events, errored: false });
-    }, 5000);
   });
 }
 

packages/runtime/src/agent/__tests__/agent.test.ts

@@ -580,13 +580,10 @@ describe("Concurrent run guard", () => {
     });
     const input = createDefaultInput();
 
-    // Start first run
+    // Start first run — abortController is now set synchronously in run()
     const sub = agent.run(input).subscribe({ next: () => {} });
 
-    // Give the async IIFE time to set abortController
-    await new Promise((r) => setTimeout(r, 10));
-
-    // Second run should throw
+    // Second run should throw immediately (no timing dependency)
     expect(() => agent.run(input)).toThrow("Agent is already running");
 
     // Cleanup

packages/runtime/src/agent/agent.ts

@@ -85,18 +85,20 @@ export class Agent extends AbstractAgent {
       );
     }
 
+    // Set synchronously before Observable creation to close the TOCTOU window
+    // between the guard check above and the subscriber callback.
+    this.abortController = new AbortController();
+    const controller = this.abortController;
+
     return new Observable<BaseEvent>((subscriber) => {
-      // Emit RUN_STARTED synchronously
+      // Emit RUN_STARTED before entering the async factory
       const startEvent: RunStartedEvent = {
         type: EventType.RUN_STARTED,
         threadId: input.threadId,
         runId: input.runId,
       };
       subscriber.next(startEvent);
 
-      this.abortController = new AbortController();
-      const controller = this.abortController;
-
       const ctx: AgentFactoryContext = {
         input,
         abortController: controller,

packages/runtime/src/agent/converters/aisdk.ts

@@ -179,7 +179,7 @@ export async function* convertAISDKStream(
         }
 
         case "text-delta": {
-          // In AI SDK 5.0, the property is 'text'
+          // AI SDK text-delta events use 'text' (not 'delta')
           const textDelta = "text" in p ? (p.text as string) : "";
           const textEvent: TextMessageChunkEvent = {
             type: EventType.TEXT_MESSAGE_CHUNK,
@@ -242,7 +242,7 @@ export async function* convertAISDKStream(
         }
 
         case "tool-result": {
-          // AI SDK uses "output" (v5+), but older versions used "result" — check both
+          // AI SDK tool-result uses "output"; older versions used "result" — check both
           const toolResult =
             "output" in p ? p.output : "result" in p ? p.result : null;
           const toolName = "toolName" in p ? (p.toolName as string) : "";
@@ -302,7 +302,7 @@ export async function* convertAISDKStream(
 
         case "error": {
           if (abortSignal.aborted) {
-            break;
+            return;
           }
           // Re-throw so the caller can emit RUN_ERROR
           const err = p.error ?? p.message ?? p.cause;

packages/runtime/src/agent/converters/tanstack.ts

@@ -47,8 +47,12 @@ export interface TanStackInputResult {
 export function convertInputToTanStackAI(
   input: RunAgentInput,
 ): TanStackInputResult {
+  // Allowlist: only pass user/assistant/tool messages to TanStack.
+  // Other roles (system, developer, activity, reasoning) are either
+  // extracted into systemPrompts or not applicable.
+  const chatRoles = new Set(["user", "assistant", "tool"]);
   const messages: TanStackChatMessage[] = input.messages
-    .filter((m: Message) => m.role !== "developer" && m.role !== "system")
+    .filter((m: Message) => chatRoles.has(m.role))
     .map((m: Message): TanStackChatMessage => {
       const msg: TanStackChatMessage = {
         role: m.role as "user" | "assistant" | "tool",
@@ -148,15 +152,22 @@ export async function* convertTanStackStream(
       };
       yield endEvent;
     } else if (type === "TOOL_CALL_RESULT") {
+      let serializedContent: string;
+      if (typeof raw.content === "string") {
+        serializedContent = raw.content;
+      } else {
+        try {
+          serializedContent = JSON.stringify(raw.content ?? raw.result ?? null);
+        } catch {
+          serializedContent = "[Unserializable tool result]";
+        }
+      }
       const resultEvent: ToolCallResultEvent = {
         type: EventType.TOOL_CALL_RESULT,
         role: "tool",
         messageId: randomUUID(),
         toolCallId: raw.toolCallId as string,
-        content:
-          typeof raw.content === "string"
-            ? raw.content
-            : JSON.stringify(raw.content ?? raw.result ?? null),
+        content: serializedContent,
       };
       yield resultEvent;
     }