@copilotkit/runtime-client-gql 1.9.3-next.4 → 1.10.0-next.0

package/src/message-conversion/gql-to-agui.ts

@@ -0,0 +1,237 @@
+import * as gql from "../client";
+import agui from "@copilotkit/shared";
+import { MessageStatusCode } from "../graphql/@generated/graphql";
+
+// Define valid image formats based on the supported formats in the codebase
+const VALID_IMAGE_FORMATS = ["jpeg", "png", "webp", "gif"] as const;
+type ValidImageFormat = (typeof VALID_IMAGE_FORMATS)[number];
+
+// Validation function for image format
+function validateImageFormat(format: string): format is ValidImageFormat {
+  return VALID_IMAGE_FORMATS.includes(format as ValidImageFormat);
+}
+
+/*
+  ----------------------------
+  GQL Message -> AGUI Message
+  ----------------------------
+*/
+export function gqlToAGUI(
+  messages: gql.Message[] | gql.Message,
+  actions?: Record<string, any>,
+  coAgentStateRenders?: Record<string, any>,
+): agui.Message[] {
+  let aguiMessages: agui.Message[] = [];
+  messages = Array.isArray(messages) ? messages : [messages];
+
+  // Create a map of action execution ID to result for completed actions
+  const actionResults = new Map<string, string>();
+  for (const message of messages) {
+    if (message.isResultMessage()) {
+      actionResults.set(message.actionExecutionId, message.result);
+    }
+  }
+
+  for (const message of messages) {
+    if (message.isTextMessage()) {
+      aguiMessages.push(gqlTextMessageToAGUIMessage(message));
+    } else if (message.isResultMessage()) {
+      aguiMessages.push(gqlResultMessageToAGUIMessage(message));
+    } else if (message.isActionExecutionMessage()) {
+      aguiMessages.push(gqlActionExecutionMessageToAGUIMessage(message, actions, actionResults));
+    } else if (message.isAgentStateMessage()) {
+      aguiMessages.push(gqlAgentStateMessageToAGUIMessage(message, coAgentStateRenders));
+    } else if (message.isImageMessage()) {
+      aguiMessages.push(gqlImageMessageToAGUIMessage(message));
+    } else {
+      throw new Error("Unknown message type");
+    }
+  }
+
+  return aguiMessages;
+}
+
+function gqlActionExecutionMessageToAGUIMessage(
+  message: gql.ActionExecutionMessage,
+  actions?: Record<string, any>,
+  actionResults?: Map<string, string>,
+): agui.Message {
+  if (actions && Object.values(actions).some((action: any) => action.name === message.name)) {
+    const action = Object.values(actions).find((action: any) => action.name === message.name);
+
+    // Create render function wrapper that provides proper props
+    const createRenderWrapper = (originalRender: any) => {
+      if (!originalRender) return undefined;
+
+      return (props?: any) => {
+        // Determine the correct status based on the same logic as RenderActionExecutionMessage
+        const actionResult = actionResults?.get(message.id);
+        let status: "inProgress" | "executing" | "complete" = "inProgress";
+
+        if (actionResult !== undefined) {
+          status = "complete";
+        } else if (message.status?.code !== MessageStatusCode.Pending) {
+          status = "executing";
+        }
+
+        // Provide the full props structure that the render function expects
+        const renderProps = {
+          status: props?.status || status,
+          args: message.arguments || {},
+          result: props?.result || actionResult || undefined,
+          respond: props?.respond || (() => {}),
+          messageId: message.id,
+          ...props,
+        };
+
+        return originalRender(renderProps);
+      };
+    };
+
+    return {
+      id: message.id,
+      role: "assistant",
+      content: "",
+      toolCalls: [actionExecutionMessageToAGUIMessage(message)],
+      generativeUI: createRenderWrapper(action.render),
+      name: message.name,
+    } as agui.AIMessage;
+  }
+
+  return {
+    id: message.id,
+    role: "assistant",
+    toolCalls: [actionExecutionMessageToAGUIMessage(message)],
+    name: message.name,
+  };
+}
+
+function gqlAgentStateMessageToAGUIMessage(
+  message: gql.AgentStateMessage,
+  coAgentStateRenders?: Record<string, any>,
+): agui.Message {
+  if (
+    coAgentStateRenders &&
+    Object.values(coAgentStateRenders).some((render: any) => render.name === message.agentName)
+  ) {
+    const render = Object.values(coAgentStateRenders).find(
+      (render: any) => render.name === message.agentName,
+    );
+
+    // Create render function wrapper that provides proper props
+    const createRenderWrapper = (originalRender: any) => {
+      if (!originalRender) return undefined;
+
+      return (props?: any) => {
+        // Determine the correct status based on the same logic as RenderActionExecutionMessage
+        const state = message.state;
+
+        // Provide the full props structure that the render function expects
+        const renderProps = {
+          state: state,
+        };
+
+        return originalRender(renderProps);
+      };
+    };
+
+    return {
+      id: message.id,
+      role: "assistant",
+      generativeUI: createRenderWrapper(render.render),
+      agentName: message.agentName,
+      state: message.state,
+    };
+  }
+
+  return {
+    id: message.id,
+    role: "assistant",
+    agentName: message.agentName,
+    state: message.state,
+  };
+}
+
+function actionExecutionMessageToAGUIMessage(
+  actionExecutionMessage: gql.ActionExecutionMessage,
+): agui.ToolCall {
+  return {
+    id: actionExecutionMessage.id,
+    function: {
+      name: actionExecutionMessage.name,
+      arguments: JSON.stringify(actionExecutionMessage.arguments),
+    },
+    type: "function",
+  };
+}
+
+export function gqlTextMessageToAGUIMessage(message: gql.TextMessage): agui.Message {
+  switch (message.role) {
+    case gql.Role.Developer:
+      return {
+        id: message.id,
+        role: "developer",
+        content: message.content,
+      };
+    case gql.Role.System:
+      return {
+        id: message.id,
+        role: "system",
+        content: message.content,
+      };
+    case gql.Role.Assistant:
+      return {
+        id: message.id,
+        role: "assistant",
+        content: message.content,
+      };
+    case gql.Role.User:
+      return {
+        id: message.id,
+        role: "user",
+        content: message.content,
+      };
+    default:
+      throw new Error("Unknown message role");
+  }
+}
+
+export function gqlResultMessageToAGUIMessage(message: gql.ResultMessage): agui.Message {
+  return {
+    id: message.id,
+    role: "tool",
+    content: message.result,
+    toolCallId: message.actionExecutionId,
+    toolName: message.actionName,
+  };
+}
+
+export function gqlImageMessageToAGUIMessage(message: gql.ImageMessage): agui.Message {
+  // Validate image format
+  if (!validateImageFormat(message.format)) {
+    throw new Error(
+      `Invalid image format: ${message.format}. Supported formats are: ${VALID_IMAGE_FORMATS.join(", ")}`,
+    );
+  }
+
+  // Validate that bytes is a non-empty string
+  if (!message.bytes || typeof message.bytes !== "string" || message.bytes.trim() === "") {
+    throw new Error("Image bytes must be a non-empty string");
+  }
+
+  // Determine the role based on the message role
+  const role = message.role === gql.Role.Assistant ? "assistant" : "user";
+
+  // Create the image message with proper typing
+  const imageMessage: agui.Message = {
+    id: message.id,
+    role,
+    content: "",
+    image: {
+      format: message.format,
+      bytes: message.bytes,
+    },
+  };
+
+  return imageMessage;
+}

package/src/message-conversion/index.ts

@@ -0,0 +1,2 @@
+export * from "./agui-to-gql";
+export * from "./gql-to-agui";

package/src/message-conversion/roundtrip-conversion.test.ts

@@ -0,0 +1,212 @@
+import { describe, test, expect, vi } from "vitest";
+import * as gql from "../client";
+import agui from "@copilotkit/shared";
+import { aguiToGQL } from "./agui-to-gql";
+import { gqlToAGUI } from "./gql-to-agui";
+
+// Helper to strip functions for deep equality
+function stripFunctions(obj: any): any {
+  if (typeof obj === "function") return undefined;
+  if (Array.isArray(obj)) return obj.map(stripFunctions);
+  if (obj && typeof obj === "object") {
+    const out: any = {};
+    for (const k in obj) {
+      if (typeof obj[k] !== "function") {
+        out[k] = stripFunctions(obj[k]);
+      }
+    }
+    return out;
+  }
+  return obj;
+}
+
+describe("roundtrip message conversion", () => {
+  test("text message AGUI -> GQL -> AGUI", () => {
+    const aguiMsg: agui.Message = {
+      id: "user-1",
+      role: "user",
+      content: "Hello!",
+    };
+    const gqlMsgs = aguiToGQL(aguiMsg);
+    const aguiMsgs2 = gqlToAGUI(gqlMsgs);
+    expect(stripFunctions(aguiMsgs2[0])).toEqual(stripFunctions(aguiMsg));
+  });
+
+  test("text message GQL -> AGUI -> GQL", () => {
+    const gqlMsg = new gql.TextMessage({
+      id: "assistant-1",
+      content: "Hi!",
+      role: gql.Role.Assistant,
+    });
+    const aguiMsgs = gqlToAGUI(gqlMsg);
+    const gqlMsgs2 = aguiToGQL(aguiMsgs);
+    // Should be equivalent in content, id, and role
+    expect(gqlMsgs2[0].id).toBe(gqlMsg.id);
+    expect((gqlMsgs2[0] as any).content).toBe(gqlMsg.content);
+    expect((gqlMsgs2[0] as any).role).toBe(gqlMsg.role);
+  });
+
+  test("tool message AGUI -> GQL -> AGUI", () => {
+    const aguiMsg: agui.Message = {
+      id: "tool-1",
+      role: "tool",
+      content: "Tool result",
+      toolCallId: "tool-call-1",
+      toolName: "testAction",
+    };
+    const gqlMsgs = aguiToGQL(aguiMsg);
+    const aguiMsgs2 = gqlToAGUI(gqlMsgs);
+    expect(stripFunctions(aguiMsgs2[0])).toEqual(stripFunctions(aguiMsg));
+  });
+
+  test("tool message GQL -> AGUI -> GQL", () => {
+    const gqlMsg = new gql.ResultMessage({
+      id: "tool-1",
+      result: "Tool result",
+      actionExecutionId: "tool-call-1",
+      actionName: "testAction",
+    });
+    const aguiMsgs = gqlToAGUI(gqlMsg);
+    const gqlMsgs2 = aguiToGQL(aguiMsgs);
+    expect(gqlMsgs2[0].id).toBe(gqlMsg.id);
+    expect((gqlMsgs2[0] as any).result).toBe(gqlMsg.result);
+    expect((gqlMsgs2[0] as any).actionExecutionId).toBe(gqlMsg.actionExecutionId);
+  });
+
+  test("action execution AGUI -> GQL -> AGUI", () => {
+    const aguiMsg: agui.Message = {
+      id: "assistant-1",
+      role: "assistant",
+      content: "Running action",
+      toolCalls: [
+        {
+          id: "tool-call-1",
+          type: "function",
+          function: {
+            name: "doSomething",
+            arguments: JSON.stringify({ foo: "bar" }),
+          },
+        },
+      ],
+    };
+    const gqlMsgs = aguiToGQL(aguiMsg);
+    const aguiMsgs2 = gqlToAGUI(gqlMsgs);
+    // Should have an assistant message and an action execution message
+    expect(aguiMsgs2[0].role).toBe("assistant");
+    expect(aguiMsgs2[1].role).toBe("assistant");
+    // Only check toolCalls if present
+    if ("toolCalls" in aguiMsgs2[1]) {
+      expect((aguiMsgs2[1] as any).toolCalls[0].function.name).toBe("doSomething");
+    }
+  });
+
+  test("action execution GQL -> AGUI -> GQL", () => {
+    const actionExecMsg = new gql.ActionExecutionMessage({
+      id: "tool-call-1",
+      name: "doSomething",
+      arguments: { foo: "bar" },
+      parentMessageId: "assistant-1",
+    });
+    const aguiMsgs = gqlToAGUI([actionExecMsg]);
+    const gqlMsgs2 = aguiToGQL(aguiMsgs);
+    // The ActionExecutionMessage is at index 1, not index 0
+    expect(gqlMsgs2[1].id).toBe("tool-call-1");
+    // The name should be extracted from the toolCall function name
+    expect((gqlMsgs2[1] as any).name).toBe("doSomething");
+    expect((gqlMsgs2[1] as any).arguments).toEqual({ foo: "bar" });
+  });
+
+  test("agent state GQL -> AGUI -> GQL", () => {
+    const agentStateMsg = new gql.AgentStateMessage({
+      id: "agent-state-1",
+      agentName: "testAgent",
+      state: { status: "running" },
+      role: gql.Role.Assistant,
+    });
+    const aguiMsgs = gqlToAGUI([agentStateMsg]);
+    const gqlMsgs2 = aguiToGQL(aguiMsgs);
+    expect(gqlMsgs2[0].id).toBe("agent-state-1");
+    // The agentName should be preserved in the roundtrip
+    expect((gqlMsgs2[0] as any).agentName).toBe("testAgent");
+  });
+
+  test("action execution with render function roundtrip", () => {
+    const mockRender = vi.fn();
+    const aguiMsg: agui.Message = {
+      id: "assistant-1",
+      role: "assistant",
+      content: "Running action",
+      toolCalls: [
+        {
+          id: "tool-call-1",
+          type: "function",
+          function: {
+            name: "doSomething",
+            arguments: JSON.stringify({ foo: "bar" }),
+          },
+        },
+      ],
+      generativeUI: mockRender,
+    };
+    const actions: Record<string, any> = { doSomething: { name: "doSomething" } };
+    const gqlMsgs = aguiToGQL(aguiMsg, actions);
+    const aguiMsgs2 = gqlToAGUI(gqlMsgs, actions);
+    // The render function should be preserved in actions context
+    expect(typeof actions.doSomething.render).toBe("function");
+    // The roundtripped message should have the same tool call
+    if ("toolCalls" in aguiMsgs2[1]) {
+      expect((aguiMsgs2[1] as any).toolCalls[0].function.name).toBe("doSomething");
+    }
+  });
+
+  test("image message GQL -> AGUI -> GQL", () => {
+    const gqlMsg = new gql.ImageMessage({
+      id: "img-1",
+      format: "jpeg",
+      bytes: "somebase64string",
+      role: gql.Role.User,
+    });
+    const aguiMsgs = gqlToAGUI(gqlMsg);
+    const gqlMsgs2 = aguiToGQL(aguiMsgs);
+    expect(gqlMsgs2[0].id).toBe(gqlMsg.id);
+    expect((gqlMsgs2[0] as any).format).toBe(gqlMsg.format);
+    expect((gqlMsgs2[0] as any).bytes).toBe(gqlMsg.bytes);
+    expect((gqlMsgs2[0] as any).role).toBe(gqlMsg.role);
+  });
+
+  test("image message AGUI -> GQL -> AGUI (assistant and user)", () => {
+    // Assistant image message
+    const aguiAssistantImageMsg: agui.Message = {
+      id: "img-assistant-1",
+      role: "assistant",
+      image: {
+        format: "jpeg",
+        bytes: "assistantbase64data",
+      },
+      content: "", // required for type
+    };
+    const gqlAssistantMsgs = aguiToGQL(aguiAssistantImageMsg);
+    const aguiAssistantMsgs2 = gqlToAGUI(gqlAssistantMsgs);
+    expect(aguiAssistantMsgs2[0].id).toBe(aguiAssistantImageMsg.id);
+    expect(aguiAssistantMsgs2[0].role).toBe("assistant");
+    expect((aguiAssistantMsgs2[0] as any).image.format).toBe("jpeg");
+    expect((aguiAssistantMsgs2[0] as any).image.bytes).toBe("assistantbase64data");
+
+    // User image message
+    const aguiUserImageMsg: agui.Message = {
+      id: "img-user-1",
+      role: "user",
+      image: {
+        format: "png",
+        bytes: "userbase64data",
+      },
+      content: "", // required for type
+    };
+    const gqlUserMsgs = aguiToGQL(aguiUserImageMsg);
+    const aguiUserMsgs2 = gqlToAGUI(gqlUserMsgs);
+    expect(aguiUserMsgs2[0].id).toBe(aguiUserImageMsg.id);
+    expect(aguiUserMsgs2[0].role).toBe("user");
+    expect((aguiUserMsgs2[0] as any).image.format).toBe("png");
+    expect((aguiUserMsgs2[0] as any).image.bytes).toBe("userbase64data");
+  });
+});