@copilotkit/runtime 1.55.1 → 1.55.2-next.1

package/src/agent/converters/tanstack.ts

@@ -0,0 +1,286 @@
+import {
+  BaseEvent,
+  EventType,
+  RunAgentInput,
+  Message,
+  TextMessageChunkEvent,
+  ToolCallArgsEvent,
+  ToolCallEndEvent,
+  ToolCallStartEvent,
+  ToolCallResultEvent,
+} from "@ag-ui/client";
+import { randomUUID } from "@copilotkit/shared";
+
+/**
+ * A TanStack AI content part (text, image, audio, video, or document).
+ */
+export type TanStackContentPart =
+  | { type: "text"; content: string }
+  | {
+      type: "image" | "audio" | "video" | "document";
+      source:
+        | { type: "data"; value: string; mimeType: string }
+        | { type: "url"; value: string; mimeType?: string };
+    };
+
+/**
+ * Message format expected by TanStack AI's `chat()`.
+ */
+export interface TanStackChatMessage {
+  role: "user" | "assistant" | "tool";
+  content: string | null | TanStackContentPart[];
+  name?: string;
+  toolCalls?: Array<{
+    id: string;
+    type: "function";
+    function: { name: string; arguments: string };
+  }>;
+  toolCallId?: string;
+}
+
+/**
+ * Result of converting RunAgentInput to TanStack AI format.
+ */
+export interface TanStackInputResult {
+  /** Chat messages (only user/assistant/tool roles; all others excluded) */
+  messages: TanStackChatMessage[];
+  /** System prompts extracted from system/developer messages, context, and state */
+  systemPrompts: string[];
+}
+
+/**
+ * Converts AG-UI user message content to TanStack AI format.
+ * Handles plain strings, multimodal parts (image/audio/video/document),
+ * and legacy BinaryInputContent for backward compatibility.
+ */
+function convertUserContent(
+  content: unknown,
+): string | null | TanStackContentPart[] {
+  if (!content) return null;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  if (content.length === 0) return "";
+
+  const parts: TanStackContentPart[] = [];
+
+  for (const part of content) {
+    if (!part || typeof part !== "object" || !("type" in part)) continue;
+
+    switch ((part as { type: string }).type) {
+      case "text": {
+        const text = (part as { text?: string }).text;
+        if (text != null) parts.push({ type: "text", content: text });
+        break;
+      }
+
+      case "image":
+      case "audio":
+      case "video":
+      case "document": {
+        const source = (part as { source?: any }).source;
+        if (!source) break;
+        const partType = (part as { type: string }).type as
+          | "image"
+          | "audio"
+          | "video"
+          | "document";
+        if (source.type === "data") {
+          parts.push({
+            type: partType,
+            source: {
+              type: "data",
+              value: source.value,
+              mimeType: source.mimeType,
+            },
+          });
+        } else if (source.type === "url") {
+          parts.push({
+            type: partType,
+            source: {
+              type: "url",
+              value: source.value,
+              ...(source.mimeType ? { mimeType: source.mimeType } : {}),
+            },
+          });
+        }
+        break;
+      }
+
+      // Legacy BinaryInputContent backward compatibility
+      case "binary": {
+        const legacy = part as {
+          mimeType?: string;
+          data?: string;
+          url?: string;
+        };
+        const mimeType = legacy.mimeType ?? "application/octet-stream";
+        const isImage = mimeType.startsWith("image/");
+
+        if (legacy.data) {
+          const partType = isImage ? "image" : "document";
+          parts.push({
+            type: partType,
+            source: { type: "data", value: legacy.data, mimeType },
+          });
+        } else if (legacy.url) {
+          const partType = isImage ? "image" : "document";
+          parts.push({
+            type: partType,
+            source: { type: "url", value: legacy.url, mimeType },
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  return parts.length > 0 ? parts : "";
+}
+
+/**
+ * Converts a RunAgentInput into the format expected by TanStack AI's `chat()`.
+ *
+ * - Keeps only user/assistant/tool messages (activity, reasoning, and other roles are also excluded)
+ * - Extracts system/developer messages into `systemPrompts`
+ * - Appends context entries and application state to `systemPrompts`
+ * - Preserves tool calls on assistant messages and toolCallId on tool messages
+ */
+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) => chatRoles.has(m.role))
+    .map((m: Message): TanStackChatMessage => {
+      const msg: TanStackChatMessage = {
+        role: m.role as "user" | "assistant" | "tool",
+        content:
+          m.role === "user"
+            ? convertUserContent(m.content)
+            : typeof m.content === "string"
+              ? m.content
+              : null,
+      };
+      if (m.role === "assistant" && "toolCalls" in m && m.toolCalls) {
+        msg.toolCalls = m.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: "function" as const,
+          function: {
+            name: tc.function.name,
+            arguments: tc.function.arguments,
+          },
+        }));
+      }
+      if (m.role === "tool" && "toolCallId" in m) {
+        msg.toolCallId = (m as Record<string, unknown>).toolCallId as string;
+      }
+      return msg;
+    });
+
+  const systemPrompts: string[] = [];
+  for (const m of input.messages) {
+    if ((m.role === "system" || m.role === "developer") && m.content) {
+      systemPrompts.push(
+        typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+      );
+    }
+  }
+
+  if (input.context?.length) {
+    for (const ctx of input.context) {
+      systemPrompts.push(`${ctx.description}:\n${ctx.value}`);
+    }
+  }
+
+  if (
+    input.state !== undefined &&
+    input.state !== null &&
+    typeof input.state === "object" &&
+    Object.keys(input.state).length > 0
+  ) {
+    systemPrompts.push(
+      `Application State:\n\`\`\`json\n${JSON.stringify(input.state, null, 2)}\n\`\`\``,
+    );
+  }
+
+  return { messages, systemPrompts };
+}
+
+/**
+ * Converts a TanStack AI stream into AG-UI `BaseEvent` objects.
+ *
+ * This is a pure converter — it does NOT emit lifecycle events
+ * (RUN_STARTED / RUN_FINISHED / RUN_ERROR). The caller (Agent class)
+ * is responsible for those.
+ */
+export async function* convertTanStackStream(
+  stream: AsyncIterable<unknown>,
+  abortSignal: AbortSignal,
+): AsyncGenerator<BaseEvent> {
+  const messageId = randomUUID();
+
+  for await (const chunk of stream) {
+    if (abortSignal.aborted) break;
+
+    const raw = chunk as Record<string, unknown>;
+    const type = raw.type as string;
+
+    if (type === "TEXT_MESSAGE_CONTENT" && raw.delta) {
+      const textEvent: TextMessageChunkEvent = {
+        type: EventType.TEXT_MESSAGE_CHUNK,
+        role: "assistant",
+        messageId,
+        delta: raw.delta as string,
+      };
+      yield textEvent;
+    } else if (type === "TOOL_CALL_START") {
+      const startEvent: ToolCallStartEvent = {
+        type: EventType.TOOL_CALL_START,
+        parentMessageId: messageId,
+        toolCallId: raw.toolCallId as string,
+        toolCallName: raw.toolCallName as string,
+      };
+      yield startEvent;
+    } else if (type === "TOOL_CALL_ARGS") {
+      const argsEvent: ToolCallArgsEvent = {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: raw.toolCallId as string,
+        delta: raw.delta as string,
+      };
+      yield argsEvent;
+    } else if (type === "TOOL_CALL_END") {
+      const endEvent: ToolCallEndEvent = {
+        type: EventType.TOOL_CALL_END,
+        toolCallId: raw.toolCallId as string,
+      };
+      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: serializedContent,
+      };
+      yield resultEvent;
+    }
+    // Unhandled chunk types are silently ignored.
+    // Known gaps: STATE_SNAPSHOT, STATE_DELTA, and REASONING events are not
+    // converted from TanStack streams. Shared state and reasoning will not
+    // surface when using the TanStack backend. Use the AI SDK backend if these
+    // features are required.
+  }
+}

package/src/agent/index.ts

@@ -49,6 +49,8 @@ import { z } from "zod";
 import type { StandardSchemaV1, InferSchemaOutput } from "@copilotkit/shared";
 import { schemaToJsonSchema } from "@copilotkit/shared";
 import { jsonSchema as aiJsonSchema } from "ai";
+import { convertAISDKStream } from "./converters/aisdk";
+import { convertTanStackStream } from "./converters/tanstack";
 import {
   StreamableHTTPClientTransport,
   StreamableHTTPClientTransportOptions,
@@ -656,9 +658,66 @@ export function convertToolDefinitionsToVercelAITools(
 }
 
 /**
- * Configuration for BuiltInAgent
+ * Context passed to the user-supplied factory function in factory mode.
  */
-export interface BuiltInAgentConfiguration {
+export interface AgentFactoryContext {
+  input: RunAgentInput;
+  /**
+   * Prefer `abortSignal` for most use cases (AI SDK, fetch, custom backends).
+   * Provided for backends like TanStack AI that require the full AbortController.
+   * Do NOT call `.abort()` on this controller — use `abortRun()` on the agent instead.
+   */
+  abortController: AbortController;
+  abortSignal: AbortSignal;
+}
+
+/**
+ * Factory config for AI SDK backend.
+ * The factory must return an object with a `fullStream` async iterable
+ * (compatible with the result of `streamText()` — only `fullStream` is consumed).
+ */
+export interface BuiltInAgentAISDKFactoryConfig {
+  type: "aisdk";
+  factory: (
+    ctx: AgentFactoryContext,
+  ) =>
+    | { fullStream: AsyncIterable<unknown> }
+    | Promise<{ fullStream: AsyncIterable<unknown> }>;
+}
+
+/**
+ * Factory config for TanStack AI backend.
+ * The factory must return an async iterable of TanStack AI stream chunks.
+ */
+export interface BuiltInAgentTanStackFactoryConfig {
+  type: "tanstack";
+  factory: (
+    ctx: AgentFactoryContext,
+  ) => AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>;
+}
+
+/**
+ * Factory config for a custom backend that directly yields AG-UI events.
+ */
+export interface BuiltInAgentCustomFactoryConfig {
+  type: "custom";
+  factory: (
+    ctx: AgentFactoryContext,
+  ) => AsyncIterable<BaseEvent> | Promise<AsyncIterable<BaseEvent>>;
+}
+
+/**
+ * Union of all factory-mode configurations.
+ */
+export type BuiltInAgentFactoryConfig =
+  | BuiltInAgentAISDKFactoryConfig
+  | BuiltInAgentTanStackFactoryConfig
+  | BuiltInAgentCustomFactoryConfig;
+
+/**
+ * Classic config — BuiltInAgent handles streamText, tools, MCP, state tools, prompt building.
+ */
+export interface BuiltInAgentClassicConfig {
   /**
    * The model to use
    */
@@ -760,6 +819,26 @@ export interface BuiltInAgentConfiguration {
   providerOptions?: Record<string, any>;
 }
 
+/**
+ * Configuration for BuiltInAgent.
+ *
+ * Two modes:
+ * - **Classic** (model + params): BuiltInAgent handles everything — streamText, tools, MCP, state tools.
+ * - **Factory** (type + factory): You own the LLM call. BuiltInAgent handles lifecycle only.
+ */
+export type BuiltInAgentConfiguration =
+  | BuiltInAgentClassicConfig
+  | BuiltInAgentFactoryConfig;
+
+/**
+ * Type guard: returns true if this is a factory-mode config.
+ */
+function isFactoryConfig(
+  config: BuiltInAgentConfiguration,
+): config is BuiltInAgentFactoryConfig {
+  return "factory" in config;
+}
+
 export class BuiltInAgent extends AbstractAgent {
   private abortController?: AbortController;
 
@@ -771,10 +850,25 @@ export class BuiltInAgent extends AbstractAgent {
    * Check if a property can be overridden by forwardedProps
    */
   canOverride(property: OverridableProperty): boolean {
+    if (isFactoryConfig(this.config)) return false;
     return this.config?.overridableProperties?.includes(property) ?? false;
   }
 
   run(input: RunAgentInput): Observable<BaseEvent> {
+    if (isFactoryConfig(this.config)) {
+      return this.runFactory(input, this.config);
+    }
+
+    if (this.abortController) {
+      throw new Error(
+        "Agent is already running. Call abortRun() first or create a new instance.",
+      );
+    }
+
+    // Set synchronously before Observable creation to close TOCTOU window
+    this.abortController = new AbortController();
+    const abortController = this.abortController;
+
     return new Observable<BaseEvent>((subscriber) => {
       // Emit RUN_STARTED event
       const startEvent: RunStartedEvent = {
@@ -980,8 +1074,6 @@ export class BuiltInAgent extends AbstractAgent {
       const mcpClients: Array<{ close: () => Promise<void> }> = [];
 
       (async () => {
-        const abortController = new AbortController();
-        this.abortController = abortController;
         let terminalEventEmitted = false;
         let messageId = randomUUID();
         let reasoningMessageId = randomUUID();
@@ -1294,7 +1386,12 @@ export class BuiltInAgent extends AbstractAgent {
               }
 
               case "tool-result": {
-                const toolResult = "output" in part ? part.output : null;
+                const toolResult =
+                  "output" in part
+                    ? part.output
+                    : "result" in part
+                      ? part.result
+                      : null;
                 const toolName = "toolName" in part ? part.toolName : "";
                 toolCallStates.delete(part.toolCallId);
 
@@ -1304,32 +1401,42 @@ export class BuiltInAgent extends AbstractAgent {
                   toolResult &&
                   typeof toolResult === "object"
                 ) {
-                  // Emit StateSnapshotEvent
-                  const stateSnapshotEvent: StateSnapshotEvent = {
-                    type: EventType.STATE_SNAPSHOT,
-                    snapshot: toolResult.snapshot,
-                  };
-                  subscriber.next(stateSnapshotEvent);
+                  const snapshot = toolResult.snapshot;
+                  if (snapshot !== undefined) {
+                    const stateSnapshotEvent: StateSnapshotEvent = {
+                      type: EventType.STATE_SNAPSHOT,
+                      snapshot,
+                    };
+                    subscriber.next(stateSnapshotEvent);
+                  }
                 } else if (
                   toolName === "AGUISendStateDelta" &&
                   toolResult &&
                   typeof toolResult === "object"
                 ) {
-                  // Emit StateDeltaEvent
-                  const stateDeltaEvent: StateDeltaEvent = {
-                    type: EventType.STATE_DELTA,
-                    delta: toolResult.delta,
-                  };
-                  subscriber.next(stateDeltaEvent);
+                  const delta = toolResult.delta;
+                  if (delta !== undefined) {
+                    const stateDeltaEvent: StateDeltaEvent = {
+                      type: EventType.STATE_DELTA,
+                      delta,
+                    };
+                    subscriber.next(stateDeltaEvent);
+                  }
                 }
 
                 // Always emit the tool result event for the LLM
+                let serializedResult: string;
+                try {
+                  serializedResult = JSON.stringify(toolResult);
+                } catch {
+                  serializedResult = `[Unserializable tool result from ${toolName || part.toolCallId}]`;
+                }
                 const resultEvent: ToolCallResultEvent = {
                   type: EventType.TOOL_CALL_RESULT,
                   role: "tool",
                   messageId: randomUUID(),
                   toolCallId: part.toolCallId,
-                  content: JSON.stringify(toolResult),
+                  content: serializedResult,
                 };
                 subscriber.next(resultEvent);
                 break;
@@ -1354,15 +1461,29 @@ export class BuiltInAgent extends AbstractAgent {
                 if (abortController.signal.aborted) {
                   break;
                 }
+                const err = part.error ?? part.message ?? part.cause;
                 const runErrorEvent: RunErrorEvent = {
                   type: EventType.RUN_ERROR,
-                  message: part.error + "",
-                };
+                  message:
+                    err instanceof Error
+                      ? err.message
+                      : typeof err === "string"
+                        ? err
+                        : `AI SDK stream error: ${JSON.stringify(part)}`,
+                  threadId: input.threadId,
+                  runId: input.runId,
+                } as RunErrorEvent;
                 subscriber.next(runErrorEvent);
                 terminalEventEmitted = true;
 
                 // Handle error
-                subscriber.error(part.error);
+                if (err instanceof Error) subscriber.error(err);
+                else
+                  subscriber.error(
+                    new Error(
+                      typeof err === "string" ? err : `AI SDK stream error`,
+                    ),
+                  );
                 break;
               }
             }
@@ -1392,8 +1513,10 @@ export class BuiltInAgent extends AbstractAgent {
           } else {
             const runErrorEvent: RunErrorEvent = {
               type: EventType.RUN_ERROR,
-              message: error + "",
-            };
+              message: error instanceof Error ? error.message : String(error),
+              threadId: input.threadId,
+              runId: input.runId,
+            } as RunErrorEvent;
             subscriber.next(runErrorEvent);
             terminalEventEmitted = true;
             subscriber.error(error);
@@ -1414,10 +1537,103 @@ export class BuiltInAgent extends AbstractAgent {
     });
   }
 
+  private runFactory(
+    input: RunAgentInput,
+    config: BuiltInAgentFactoryConfig,
+  ): Observable<BaseEvent> {
+    if (this.abortController) {
+      throw new Error(
+        "Agent is already running. Call abortRun() first or create a new instance.",
+      );
+    }
+
+    // Set synchronously before Observable creation to close TOCTOU window
+    this.abortController = new AbortController();
+    const controller = this.abortController;
+
+    return new Observable<BaseEvent>((subscriber) => {
+      const startEvent: RunStartedEvent = {
+        type: EventType.RUN_STARTED,
+        threadId: input.threadId,
+        runId: input.runId,
+      };
+      subscriber.next(startEvent);
+
+      const ctx: AgentFactoryContext = {
+        input,
+        abortController: controller,
+        abortSignal: controller.signal,
+      };
+
+      (async () => {
+        try {
+          let events: AsyncIterable<BaseEvent>;
+
+          switch (config.type) {
+            case "aisdk": {
+              const result = await config.factory(ctx);
+              events = convertAISDKStream(result.fullStream, controller.signal);
+              break;
+            }
+            case "tanstack": {
+              const stream = await config.factory(ctx);
+              events = convertTanStackStream(stream, controller.signal);
+              break;
+            }
+            case "custom": {
+              events = await config.factory(ctx);
+              break;
+            }
+            default: {
+              const _exhaustive: never = config;
+              throw new Error(
+                `Unknown agent config type: ${(_exhaustive as BuiltInAgentFactoryConfig).type}`,
+              );
+            }
+          }
+
+          for await (const event of events) {
+            subscriber.next(event);
+          }
+
+          if (!controller.signal.aborted) {
+            const finishedEvent: RunFinishedEvent = {
+              type: EventType.RUN_FINISHED,
+              threadId: input.threadId,
+              runId: input.runId,
+            };
+            subscriber.next(finishedEvent);
+          }
+          subscriber.complete();
+        } catch (error) {
+          if (controller.signal.aborted) {
+            subscriber.complete();
+          } else {
+            const runErrorEvent: RunErrorEvent = {
+              type: EventType.RUN_ERROR,
+              message: error instanceof Error ? error.message : String(error),
+              threadId: input.threadId,
+              runId: input.runId,
+            } as RunErrorEvent;
+            subscriber.next(runErrorEvent);
+            subscriber.error(error);
+          }
+        } finally {
+          this.abortController = undefined;
+        }
+      })();
+
+      return () => {
+        controller.abort();
+      };
+    });
+  }
+
   clone() {
     const cloned = new BuiltInAgent(this.config);
-    // Copy middlewares from parent class
-    // @ts-expect-error - accessing protected property from parent
+    // AbstractAgent.middlewares is private in @ag-ui/client — no public accessor exists.
+    // This coupling is intentional: clone() must preserve middleware chains.
+    // @ts-expect-error accessing private AbstractAgent.middlewares
     cloned.middlewares = [...this.middlewares];
     return cloned;
   }
@@ -1437,4 +1653,7 @@ export class BasicAgent extends BuiltInAgent {
   }
 }
 
-export type BasicAgentConfiguration = BuiltInAgentConfiguration;
+/** @deprecated Use BuiltInAgentClassicConfig instead */
+export type BasicAgentConfiguration = BuiltInAgentClassicConfig;
+
+export * from "./converters";

package/src/lib/integrations/nextjs/pages-router.ts

@@ -13,6 +13,7 @@ export const config = {
 // This import is needed to fix the type error
 // Fix is currently in TypeScript 5.5 beta, waiting for stable version
 // https://github.com/microsoft/TypeScript/issues/42873#issuecomment-2066874644
+// oxlint-disable-next-line unicorn/require-module-specifiers, typescript/no-useless-empty-export
 export type {} from "@whatwg-node/server";
 
 export function copilotRuntimeNextJSPagesRouterEndpoint(