Skip to content

The Open Standard for Generative UI

10.9 KB
Raw Blame
import type { Message as ConversationMessage } from "openai/resources/conversations/conversations";
import type { ConversationItem } from "openai/resources/conversations/items";
import type {
  EasyInputMessage,
  ResponseFunctionToolCall,
  ResponseFunctionToolCallOutputItem,
  ResponseInputItem,
  ResponseInputMessageContentList,
} from "openai/resources/responses/responses";
import type { AssistantMessage, Message, ToolMessage, UserMessage } from "../../types";
import type { MessageFormat } from "../../types/messageFormat";

// ── Outbound (AG-UI → OpenAI Responses/Conversations input) ─────

/**
 * Both the Responses API and the Conversations API accept
 * `ResponseInputItem[]` as input, so a single outbound conversion
 * works for both.
 *
 * Tool calls are *sibling items* of the assistant message, not nested
 * inside it.  We flatten each AG-UI assistant message into:
 *   1. An `EasyInputMessage` with `role: "assistant"` (text part)
 *   2. One `ResponseFunctionToolCall` per tool call
 *
 * Tool result messages become `FunctionCallOutput` items.
 */
function toItems(message: Message): ResponseInputItem[] {
  switch (message.role) {
    case "user":
      return [toInputMessage(message)];

    case "assistant": {
      const items: ResponseInputItem[] = [];

      if (message.content) {
        items.push({
          role: "assistant",
          content: message.content,
          type: "message",
        } satisfies EasyInputMessage);
      }

      if (message.toolCalls?.length) {
        for (const tc of message.toolCalls) {
          items.push({
            type: "function_call",
            call_id: tc.id,
            name: tc.function.name,
            arguments: tc.function.arguments,
          } satisfies ResponseFunctionToolCall);
        }
      }

      return items;
    }

    case "tool":
      return [
        {
          type: "function_call_output",
          call_id: message.toolCallId,
          output: message.content,
        } as ResponseInputItem,
      ];

    case "system":
      return [
        { role: "system", content: message.content, type: "message" } satisfies EasyInputMessage,
      ];

    case "developer":
      return [
        { role: "developer", content: message.content, type: "message" } satisfies EasyInputMessage,
      ];

    default:
      return [];
  }
}

function toInputMessage(message: UserMessage): EasyInputMessage {
  const content = message.content;

  if (typeof content === "string") {
    return { role: "user", content, type: "message" };
  }

  const parts: ResponseInputMessageContentList =
    content?.map((part) => {
      if (part.type === "text") {
        return { type: "input_text" as const, text: part.text };
      }
      if (part.type === "binary") {
        const url = part.url ?? `data:${part.mimeType};base64,${part.data ?? ""}`;
        return { type: "input_image" as const, image_url: url, detail: "auto" as const };
      }
      return { type: "input_text" as const, text: "" };
    }) ?? [];

  return { role: "user", content: parts, type: "message" };
}

// ── Inbound (OpenAI Conversations/Responses → AG-UI) ────────────

/**
 * Converts `ConversationItem[]` (from the Conversations API) or
 * `ResponseItem[]` (from the Responses API) into AG-UI `Message[]`.
 *
 * Both APIs return items as a flat list with `type` discriminator:
 *   - `"message"` → user / assistant / system / developer / tool message
 *   - `"function_call"` → tool call (grouped into the preceding assistant)
 *   - `"function_call_output"` → tool result
 *
 * The Conversations API `Message` type is a superset that also handles
 * `reasoning_text`, `summary_text`, and `text` content parts, as well
 * as additional roles like `tool` and `critic`.
 */
function fromItems(items: ConversationItem[]): Message[] {
  const messages: Message[] = [];
  let currentAssistant: AssistantMessage | null = null;
  // Tool outputs for the in-progress assistant turn. BUFFERED rather than
  // pushed immediately so that an assistant turn with MULTIPLE tool calls
  // (e.g. thesys_get_artifact_description THEN thesys_generate_artifact)
  // reconstructs as ONE assistant message + its tool messages — matching the
  // live stream shape — instead of one assistant message PER tool call. The
  // latter renders a duplicate "Behind the scenes" group for every call on
  // reload, because each function_call_output used to flush the assistant.
  let pendingToolMsgs: ToolMessage[] = [];

  // Emit the in-progress assistant turn: the assistant message first, then its
  // buffered tool results (the renderer pairs tool messages that immediately
  // follow their assistant message).
  const flushAssistant = () => {
    if (currentAssistant) {
      messages.push(currentAssistant);
      currentAssistant = null;
    }
    if (pendingToolMsgs.length > 0) {
      messages.push(...pendingToolMsgs);
      pendingToolMsgs = [];
    }
  };

  for (const item of items) {
    switch (item.type) {
      case "message": {
        // A non-tool message ends the current assistant turn.
        flushAssistant();

        const msg = item as ConversationMessage;

        if (msg.role === "assistant") {
          currentAssistant = {
            id: msg.id,
            role: "assistant",
            content: extractTextContent(msg) || undefined,
          };
        } else if (msg.role === "tool") {
          // Conversations API can have tool messages with type: "message"
          messages.push({
            id: msg.id,
            role: "tool",
            content: extractTextContent(msg),
            toolCallId: "",
          } as ToolMessage);
        } else if (msg.role === "user") {
          messages.push(fromUserMessage(msg));
        } else {
          // system / developer / unknown / critic / discriminator
          const role = msg.role === "developer" ? "developer" : "system";
          messages.push({
            id: msg.id,
            role,
            content: extractTextContent(msg),
          } as Message);
        }
        break;
      }

      case "function_call": {
        const tc = item as { id?: string; call_id: string; name: string; arguments: string };

        if (!currentAssistant) {
          currentAssistant = { id: crypto.randomUUID(), role: "assistant" };
        }

        currentAssistant = {
          ...currentAssistant,
          toolCalls: [
            ...(currentAssistant.toolCalls ?? []),
            {
              id: tc.call_id,
              type: "function" as const,
              function: { name: tc.name, arguments: tc.arguments },
            },
          ],
        };
        break;
      }

      case "function_call_output": {
        // Buffer alongside the current assistant — do NOT flush here, so
        // sibling tool calls in the same turn stay on one assistant message.
        const output = item as ResponseFunctionToolCallOutputItem;
        pendingToolMsgs.push({
          id: output.id,
          role: "tool",
          content:
            typeof output.output === "string" ? output.output : JSON.stringify(output.output),
          toolCallId: output.call_id,
        } as ToolMessage);
        break;
      }

      case "mcp_call": {
        if (!currentAssistant) {
          currentAssistant = { id: crypto.randomUUID(), role: "assistant" };
        }

        currentAssistant = {
          ...currentAssistant,
          toolCalls: [
            ...(currentAssistant.toolCalls ?? []),
            {
              id: item.id,
              type: "function" as const,
              function: { name: item.name, arguments: item.arguments },
            },
          ],
        };

        const errorText =
          typeof item.error === "string" && item.error.length > 0 ? item.error : undefined;
        pendingToolMsgs.push({
          id: `${item.id}-output`,
          role: "tool",
          content: item.output ?? "",
          toolCallId: item.id,
          ...(errorText ? { error: errorText } : {}),
        } as ToolMessage);
        break;
      }

      default:
        // file_search, web_search, computer_call, reasoning, etc. — skip
        break;
    }
  }

  flushAssistant();

  return messages;
}

/**
 * Extract text content from a Conversations API `Message`.
 *
 * Handles the full content union:
 *   - `output_text` (assistant output)
 *   - `input_text` (user/system/developer input)
 *   - `text` (generic text)
 *   - `summary_text`, `reasoning_text` (appended)
 *   - `refusal` (mapped to text)
 */
function extractTextContent(msg: ConversationMessage): string {
  return msg.content
    .map((part) => {
      switch (part.type) {
        case "output_text":
          return part.text;
        case "input_text":
          return part.text;
        case "text":
          return part.text;
        case "summary_text":
          return part.text;
        case "reasoning_text":
          return part.text;
        case "refusal":
          return `[Refusal]: ${part.refusal}`;
        default:
          return "";
      }
    })
    .filter(Boolean)
    .join("");
}

function fromUserMessage(msg: ConversationMessage): UserMessage {
  // Check if content has images/files — if so, use multipart
  const hasMedia = msg.content.some(
    (part) => part.type === "input_image" || part.type === "input_file",
  );

  if (!hasMedia) {
    return { id: msg.id, role: "user", content: extractTextContent(msg) };
  }

  const parts = msg.content.map(
    (part): { type: "text"; text: string } | { type: "binary"; url: string; mimeType: string } => {
      if (part.type === "input_text" || part.type === "text") {
        return { type: "text", text: part.text };
      }
      if (part.type === "input_image" && part.image_url) {
        return { type: "binary", url: part.image_url, mimeType: "image/*" };
      }
      return { type: "text", text: "" };
    },
  );

  return { id: msg.id, role: "user", content: parts };
}

// ── MessageFormat implementation ─────────────────────────────────

/**
 * Converts between AG-UI message format and OpenAI's item-based format,
 * compatible with both the **Responses API** and **Conversations API**.
 *
 * AG-UI → OpenAI (toApi):
 *   - Returns `ResponseInputItem[]` — works for both `responses.create({ input })`
 *     and `conversations.items.create({ items })`
 *   - Flattens assistant messages: text → `EasyInputMessage`, tool calls → `ResponseFunctionToolCall`
 *
 * OpenAI → AG-UI (fromApi):
 *   - Accepts `ConversationItem[]` (or `ResponseItem[]`, which is a subset)
 *   - Groups adjacent assistant messages + function_calls into `AssistantMessage`
 *   - Handles Conversations-specific content types (`reasoning_text`, `summary_text`, etc.)
 */
export const openAIConversationMessageFormat: MessageFormat = {
  toApi(messages: Message[]): ResponseInputItem[] {
    return messages.flatMap(toItems);
  },

  fromApi(data: unknown): Message[] {
    return fromItems(data as ConversationItem[]);
  },
};