@copilotkit/runtime 1.55.2-next.0 → 1.55.2-next.1

package/src/agent/converters/aisdk.ts

@@ -0,0 +1,326 @@
+import {
+  BaseEvent,
+  EventType,
+  ReasoningEndEvent,
+  ReasoningMessageContentEvent,
+  ReasoningMessageEndEvent,
+  ReasoningMessageStartEvent,
+  ReasoningStartEvent,
+  TextMessageChunkEvent,
+  ToolCallArgsEvent,
+  ToolCallEndEvent,
+  ToolCallStartEvent,
+  ToolCallResultEvent,
+  StateSnapshotEvent,
+  StateDeltaEvent,
+} from "@ag-ui/client";
+import { randomUUID } from "@copilotkit/shared";
+
+/**
+ * Converts an AI SDK `fullStream` 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.
+ *
+ * Terminal stream events (finish, error, abort) cause the generator to
+ * return so the caller can handle lifecycle appropriately.
+ */
+export async function* convertAISDKStream(
+  fullStream: AsyncIterable<unknown>,
+  abortSignal: AbortSignal,
+): AsyncGenerator<BaseEvent> {
+  let messageId = randomUUID();
+  let reasoningMessageId = randomUUID();
+  let isInReasoning = false;
+
+  const toolCallStates = new Map<
+    string,
+    {
+      started: boolean;
+      hasArgsDelta: boolean;
+      ended: boolean;
+      toolName?: string;
+    }
+  >();
+
+  const ensureToolCallState = (toolCallId: string) => {
+    let state = toolCallStates.get(toolCallId);
+    if (!state) {
+      state = { started: false, hasArgsDelta: false, ended: false };
+      toolCallStates.set(toolCallId, state);
+    }
+    return state;
+  };
+
+  /**
+   * Auto-close an open reasoning lifecycle.
+   * Some AI SDK providers (notably @ai-sdk/anthropic) never emit "reasoning-end",
+   * which leaves downstream state machines stuck. This helper emits the
+   * missing REASONING_MESSAGE_END + REASONING_END events so the stream
+   * can transition to text, tool-call, or finish phases.
+   */
+  function* closeReasoningIfOpen(): Generator<BaseEvent> {
+    if (!isInReasoning) return;
+    isInReasoning = false;
+    const reasoningMsgEnd: ReasoningMessageEndEvent = {
+      type: EventType.REASONING_MESSAGE_END,
+      messageId: reasoningMessageId,
+    };
+    yield reasoningMsgEnd;
+    const reasoningEnd: ReasoningEndEvent = {
+      type: EventType.REASONING_END,
+      messageId: reasoningMessageId,
+    };
+    yield reasoningEnd;
+  }
+
+  try {
+    for await (const part of fullStream) {
+      const p = part as Record<string, unknown>;
+
+      // Close any open reasoning lifecycle on every event except
+      // reasoning-delta, which arrives mid-block and must not interrupt it.
+      if (p.type !== "reasoning-delta") {
+        yield* closeReasoningIfOpen();
+      }
+
+      switch (p.type) {
+        case "abort": {
+          // Terminal — let the caller handle lifecycle
+          return;
+        }
+
+        case "reasoning-start": {
+          // Use SDK-provided id, or generate a fresh UUID if id is falsy/"0"
+          // to prevent consecutive reasoning blocks from sharing a messageId
+          const providedId = "id" in p ? p.id : undefined;
+          reasoningMessageId =
+            providedId && providedId !== "0"
+              ? (providedId as string)
+              : randomUUID();
+          const reasoningStartEvent: ReasoningStartEvent = {
+            type: EventType.REASONING_START,
+            messageId: reasoningMessageId,
+          };
+          yield reasoningStartEvent;
+          const reasoningMessageStart: ReasoningMessageStartEvent = {
+            type: EventType.REASONING_MESSAGE_START,
+            messageId: reasoningMessageId,
+            role: "reasoning",
+          };
+          yield reasoningMessageStart;
+          isInReasoning = true;
+          break;
+        }
+
+        case "reasoning-delta": {
+          const delta = (p.text as string) ?? "";
+          if (!delta) break; // skip — @ag-ui/core schema requires delta to be non-empty
+          const reasoningDeltaEvent: ReasoningMessageContentEvent = {
+            type: EventType.REASONING_MESSAGE_CONTENT,
+            messageId: reasoningMessageId,
+            delta,
+          };
+          yield reasoningDeltaEvent;
+          break;
+        }
+
+        case "reasoning-end": {
+          // closeReasoningIfOpen() already called before the switch — no-op here
+          // if the SDK never emits this event (e.g. @ai-sdk/anthropic).
+          break;
+        }
+
+        case "tool-input-start": {
+          const toolCallId = p.id as string;
+          const state = ensureToolCallState(toolCallId);
+          state.toolName = p.toolName as string;
+          if (!state.started) {
+            state.started = true;
+            const startEvent: ToolCallStartEvent = {
+              type: EventType.TOOL_CALL_START,
+              parentMessageId: messageId,
+              toolCallId,
+              toolCallName: p.toolName as string,
+            };
+            yield startEvent;
+          }
+          break;
+        }
+
+        case "tool-input-delta": {
+          const toolCallId = p.id as string;
+          const state = ensureToolCallState(toolCallId);
+          state.hasArgsDelta = true;
+          const argsEvent: ToolCallArgsEvent = {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId,
+            delta: p.delta as string,
+          };
+          yield argsEvent;
+          break;
+        }
+
+        case "tool-input-end": {
+          // No direct event – the subsequent "tool-call" part marks completion.
+          break;
+        }
+
+        case "text-start": {
+          // New text message starting - use the SDK-provided id
+          // Use randomUUID() if part.id is falsy or "0" to prevent message merging issues
+          const providedId = "id" in p ? p.id : undefined;
+          messageId =
+            providedId && providedId !== "0"
+              ? (providedId as string)
+              : randomUUID();
+          break;
+        }
+
+        case "text-delta": {
+          // 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,
+            role: "assistant",
+            messageId,
+            delta: textDelta,
+          };
+          yield textEvent;
+          break;
+        }
+
+        case "tool-call": {
+          const toolCallId = p.toolCallId as string;
+          const state = ensureToolCallState(toolCallId);
+          state.toolName = (p.toolName as string) ?? state.toolName;
+
+          if (!state.started) {
+            state.started = true;
+            const startEvent: ToolCallStartEvent = {
+              type: EventType.TOOL_CALL_START,
+              parentMessageId: messageId,
+              toolCallId,
+              toolCallName: p.toolName as string,
+            };
+            yield startEvent;
+          }
+
+          if (!state.hasArgsDelta && "input" in p && p.input !== undefined) {
+            let serializedInput = "";
+            if (typeof p.input === "string") {
+              serializedInput = p.input;
+            } else {
+              try {
+                serializedInput = JSON.stringify(p.input);
+              } catch {
+                serializedInput = String(p.input);
+              }
+            }
+
+            if (serializedInput.length > 0) {
+              const argsEvent: ToolCallArgsEvent = {
+                type: EventType.TOOL_CALL_ARGS,
+                toolCallId,
+                delta: serializedInput,
+              };
+              yield argsEvent;
+              state.hasArgsDelta = true;
+            }
+          }
+
+          if (!state.ended) {
+            state.ended = true;
+            const endEvent: ToolCallEndEvent = {
+              type: EventType.TOOL_CALL_END,
+              toolCallId,
+            };
+            yield endEvent;
+          }
+          break;
+        }
+
+        case "tool-result": {
+          // 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) : "";
+          toolCallStates.delete(p.toolCallId as string);
+
+          // Check if this is a state update tool
+          if (
+            toolName === "AGUISendStateSnapshot" &&
+            toolResult &&
+            typeof toolResult === "object"
+          ) {
+            const snapshot = (toolResult as Record<string, unknown>).snapshot;
+            if (snapshot !== undefined) {
+              const stateSnapshotEvent: StateSnapshotEvent = {
+                type: EventType.STATE_SNAPSHOT,
+                snapshot,
+              };
+              yield stateSnapshotEvent;
+            }
+          } else if (
+            toolName === "AGUISendStateDelta" &&
+            toolResult &&
+            typeof toolResult === "object"
+          ) {
+            const delta = (toolResult as Record<string, unknown>).delta;
+            if (delta !== undefined) {
+              const stateDeltaEvent: StateDeltaEvent = {
+                type: EventType.STATE_DELTA,
+                delta,
+              };
+              yield 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 || "unknown tool"}]`;
+          }
+          const resultEvent: ToolCallResultEvent = {
+            type: EventType.TOOL_CALL_RESULT,
+            role: "tool",
+            messageId: randomUUID(),
+            toolCallId: p.toolCallId as string,
+            content: serializedResult,
+          };
+          yield resultEvent;
+          break;
+        }
+
+        case "finish": {
+          // Terminal — let the caller handle lifecycle
+          return;
+        }
+
+        case "error": {
+          if (abortSignal.aborted) {
+            return;
+          }
+          // Re-throw so the caller can emit RUN_ERROR
+          const err = p.error ?? p.message ?? p.cause;
+          if (err instanceof Error) throw err;
+          throw new Error(
+            typeof err === "string"
+              ? err
+              : `AI SDK stream error: ${JSON.stringify(p)}`,
+          );
+        }
+
+        default:
+          // Unknown event types are silently ignored
+          break;
+      }
+    }
+  } finally {
+    // Always close reasoning on exit (normal or exceptional)
+    yield* closeReasoningIfOpen();
+  }
+}

package/src/agent/converters/index.ts

@@ -0,0 +1,7 @@
+export { convertAISDKStream } from "./aisdk";
+export {
+  convertTanStackStream,
+  convertInputToTanStackAI,
+  type TanStackChatMessage,
+  type TanStackInputResult,
+} from "./tanstack";

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.
+  }
+}