Skip to content

The Open Standard for Generative UI

17.2 KB
Raw Blame
import { EventSchemas, EventType, type AGUIEvent } from "@ag-ui/core";
import { afterEach, describe, expect, it, vi } from "vitest";

import { streamOpenUI } from "../stream-relay";

afterEach(() => {
  vi.unstubAllGlobals();
});

describe("streamOpenUI", () => {
  it("relays only valid OpenUI custom-channel events across chunked CRLF SSE", async () => {
    const start = { type: EventType.TEXT_MESSAGE_START, messageId: "m1", role: "assistant" };
    const content = { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: "Hello" };
    const end = { type: EventType.TEXT_MESSAGE_END, messageId: "m1" };
    const sse = [
      protocolFrame("custom", { name: "other", payload: start }, "\r\n"),
      "event: custom\r\ndata: not-json\r\n\r\n",
      protocolFrame("custom", { name: "openui", payload: start }, "\r\n"),
      bareFrame("custom:openui", content, "\r\n"),
      protocolFrame("custom", { name: "openui", payload: end }, "\r\n"),
    ].join("");

    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      const url = String(input);
      if (url.endsWith("/stream/events")) {
        return new Response(chunkedBody([sse.slice(0, 47), sse.slice(47, 131), sse.slice(131)]));
      }
      expect(init?.method).toBe("POST");
      return runStartedResponse("run-1");
    });
    vi.stubGlobal("fetch", fetchMock);

    const output = await new Response(
      streamOpenUI({
        apiUrl: "https://langgraph.example/",
        assistantId: "agent",
        apiKey: "secret",
        input: { messages: [] },
        cleanupThread: false,
      }),
    ).text();

    const events = parseOutput(output);
    expect(events).toEqual([
      {
        type: EventType.RUN_STARTED,
        threadId: expect.any(String),
        runId: "run-1",
      },
      start,
      content,
      end,
      {
        type: EventType.RUN_FINISHED,
        threadId: expect.any(String),
        runId: "run-1",
      },
    ]);
    expect(events[0]?.threadId).toBe(events.at(-1)?.threadId);
    expectValidAGUIEvents(events);
    expect(fetchMock).toHaveBeenCalledTimes(2);

    const commandCall = fetchMock.mock.calls.find(([input]) => String(input).endsWith("/commands"));
    expect(commandCall).toBeDefined();
    expect(commandCall?.[1]?.headers).toEqual({
      "Content-Type": "application/json",
      "x-api-key": "secret",
    });
    expect(JSON.parse(String(commandCall?.[1]?.body))).toMatchObject({
      method: "run.start",
      params: { assistant_id: "agent", input: { messages: [] } },
    });
    const streamCall = fetchMock.mock.calls.find(([input]) =>
      String(input).endsWith("/stream/events"),
    );
    expect(JSON.parse(String(streamCall?.[1]?.body))).toEqual({
      channels: ["custom:openui", "lifecycle"],
    });
  });

  it("relays multiple assistant messages and tool results until root lifecycle completes", async () => {
    const relayed = [
      { type: EventType.TEXT_MESSAGE_START, messageId: "m1", role: "assistant" },
      { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: "Let me check." },
      { type: EventType.TOOL_CALL_START, toolCallId: "call-1", toolCallName: "weather" },
      { type: EventType.TOOL_CALL_ARGS, toolCallId: "call-1", delta: '{"city":"Paris"}' },
      { type: EventType.TOOL_CALL_END, toolCallId: "call-1" },
      { type: EventType.TEXT_MESSAGE_END, messageId: "m1" },
      {
        type: EventType.TOOL_CALL_RESULT,
        messageId: "tool-result-call-1",
        toolCallId: "call-1",
        content: '{"temperature":21}',
        role: "tool",
      },
      { type: EventType.TEXT_MESSAGE_START, messageId: "m2", role: "assistant" },
      {
        type: EventType.TEXT_MESSAGE_CONTENT,
        messageId: "m2",
        delta: '<Card title="Paris">21C</Card>',
      },
      { type: EventType.TEXT_MESSAGE_END, messageId: "m2" },
    ] satisfies AGUIEvent[];
    const sse = [
      ...relayed.map((event) => protocolFrame("custom", { name: "openui", payload: event })),
      lifecycleFrame({ event: "completed" }),
    ].join("");

    const fetchMock = vi.fn(async (input: string | URL | Request) => {
      if (String(input).endsWith("/stream/events")) return new Response(sse);
      return runStartedResponse("run-multiple");
    });
    vi.stubGlobal("fetch", fetchMock);

    const events = parseOutput(
      await new Response(
        streamOpenUI({
          apiUrl: "https://langgraph.example",
          assistantId: "agent",
          input: { messages: [] },
          cleanupThread: false,
        }),
      ).text(),
    );

    expect(events.slice(1, -1)).toEqual(relayed);
    expect(events[0]).toMatchObject({ type: EventType.RUN_STARTED, runId: "run-multiple" });
    expect(events.at(-1)).toMatchObject({
      type: EventType.RUN_FINISHED,
      runId: "run-multiple",
    });
    expectValidAGUIEvents(events);
  });

  it("ignores nested lifecycle completion until the root run completes", async () => {
    const start = {
      type: EventType.TEXT_MESSAGE_START,
      messageId: "nested-message",
      role: "assistant",
    } satisfies AGUIEvent;
    const content = {
      type: EventType.TEXT_MESSAGE_CONTENT,
      messageId: "nested-message",
      delta: "Still running",
    } satisfies AGUIEvent;
    const sse = [
      protocolFrame("custom", { name: "openui", payload: start }),
      lifecycleFrame({ event: "completed" }, ["subgraph:worker"]),
      protocolFrame("custom", { name: "openui", payload: content }),
      lifecycleFrame({ event: "completed" }),
    ].join("");

    vi.stubGlobal(
      "fetch",
      vi.fn(async (input: string | URL | Request) => {
        if (String(input).endsWith("/stream/events")) return new Response(sse);
        return runStartedResponse("run-root");
      }),
    );

    const events = parseOutput(
      await new Response(
        streamOpenUI({
          apiUrl: "https://langgraph.example",
          assistantId: "agent",
          input: {},
          cleanupThread: false,
        }),
      ).text(),
    );

    expect(events).toEqual([
      expect.objectContaining({ type: EventType.RUN_STARTED, runId: "run-root" }),
      start,
      content,
      expect.objectContaining({ type: EventType.RUN_FINISHED, runId: "run-root" }),
    ]);
    expectValidAGUIEvents(events);
  });

  it("redacts run-start internals by default", async () => {
    let eventStreamSignal: AbortSignal | null | undefined;
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      const url = String(input);
      if (url.endsWith("/stream/events")) {
        eventStreamSignal = init?.signal;
        return new Response(abortableBody(eventStreamSignal));
      }
      if (url.endsWith("/commands")) return new Response("assistant not found", { status: 404 });
      throw new Error(`Unexpected URL: ${url}`);
    });
    vi.stubGlobal("fetch", fetchMock);

    const output = await new Response(
      streamOpenUI({
        apiUrl: "https://langgraph.example",
        assistantId: "missing-agent",
        input: {},
        cleanupThread: false,
      }),
    ).text();

    expect(parseOutput(output)).toEqual([
      {
        type: EventType.RUN_ERROR,
        message: "Unable to complete LangGraph run",
      },
    ]);
    expect(eventStreamSignal?.aborted).toBe(true);
    expect(fetchMock).toHaveBeenCalledTimes(2);
  });

  it("includes assistant hints only when debug errors are enabled", async () => {
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      const url = String(input);
      if (url.endsWith("/stream/events")) return new Response(abortableBody(init?.signal));
      if (url.endsWith("/commands")) return new Response("assistant not found", { status: 404 });
      if (url.endsWith("/assistants/search")) {
        return Response.json([{ graph_id: "weather-agent" }, { graph_id: "research-agent" }]);
      }
      throw new Error(`Unexpected URL: ${url}`);
    });
    vi.stubGlobal("fetch", fetchMock);

    const output = await new Response(
      streamOpenUI({
        apiUrl: "https://langgraph.example",
        assistantId: "missing-agent",
        input: {},
        debug: true,
        cleanupThread: false,
      }),
    ).text();

    expect(parseOutput(output)).toEqual([
      {
        type: EventType.RUN_ERROR,
        message: expect.stringContaining(
          'Configured assistant "missing-agent" is not registered on this LangGraph server; available graph ids: weather-agent, research-agent',
        ),
      },
    ]);
  });

  it("deletes its temporary LangGraph thread after completion by default", async () => {
    let finishDelete: (() => void) | undefined;
    const deleteGate = new Promise<void>((resolve) => {
      finishDelete = resolve;
    });
    const waitUntil = vi.fn<(task: Promise<void>) => void>();
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      const url = String(input);
      if (url.endsWith("/stream/events")) {
        return new Response(lifecycleFrame({ event: "completed" }));
      }
      if (url.endsWith("/commands")) return runStartedResponse("run-cleanup");
      if (init?.method === "DELETE") {
        await deleteGate;
        return new Response(null, { status: 204 });
      }
      throw new Error(`Unexpected URL: ${url}`);
    });
    vi.stubGlobal("fetch", fetchMock);

    const outputPromise = new Response(
      streamOpenUI({
        apiUrl: "https://langgraph.example",
        assistantId: "agent",
        input: {},
        waitUntil,
      }),
    ).text();
    let responseClosed = false;
    void outputPromise.then(() => {
      responseClosed = true;
    });

    await vi.waitFor(() =>
      expect(fetchMock.mock.calls.some(([, init]) => init?.method === "DELETE")).toBe(true),
    );
    expect(responseClosed).toBe(false);
    expect(waitUntil).toHaveBeenCalledTimes(1);

    finishDelete?.();
    const events = parseOutput(await outputPromise);

    expect(responseClosed).toBe(true);
    const threadId = events[0]?.type === EventType.RUN_STARTED ? events[0].threadId : undefined;
    const deleteCall = fetchMock.mock.calls.find(([, init]) => init?.method === "DELETE");
    expect(String(deleteCall?.[0])).toBe(`https://langgraph.example/threads/${threadId}`);
  });

  it.each([
    ["an empty response", ""],
    ["a response without run_id", JSON.stringify({ type: "success", id: 1, result: {} })],
  ])("rejects %s instead of fabricating a run id", async (_label, commandBody) => {
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      if (String(input).endsWith("/stream/events")) {
        return new Response(abortableBody(init?.signal));
      }
      return new Response(commandBody);
    });
    vi.stubGlobal("fetch", fetchMock);

    const events = parseOutput(
      await new Response(
        streamOpenUI({
          apiUrl: "https://langgraph.example",
          assistantId: "agent",
          input: {},
          debug: true,
          cleanupThread: false,
        }),
      ).text(),
    );

    expect(events).toEqual([
      { type: EventType.RUN_ERROR, message: "LangGraph run.start returned no run id" },
    ]);
  });

  it("aborts upstream requests when the consumer cancels", async () => {
    const signals: AbortSignal[] = [];
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      if (init?.signal) signals.push(init.signal);
      const url = String(input);
      if (url.endsWith("/stream/events")) {
        return new Response(abortableBody(init?.signal));
      }
      return Response.json({ type: "success" });
    });
    vi.stubGlobal("fetch", fetchMock);

    const reader = streamOpenUI({
      apiUrl: "https://langgraph.example",
      assistantId: "agent",
      input: {},
      cleanupThread: false,
    }).getReader();

    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
    await reader.cancel();

    expect(signals).toHaveLength(2);
    expect(signals.every((signal) => signal.aborted)).toBe(true);
  });

  it("registers and awaits thread cleanup when the consumer cancels after run start", async () => {
    const waitUntil = vi.fn<(task: Promise<void>) => void>();
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      const url = String(input);
      if (url.endsWith("/stream/events")) return new Response(abortableBody(init?.signal));
      if (url.endsWith("/commands")) return runStartedResponse("run-cancel-cleanup");
      if (init?.method === "DELETE") return new Response(null, { status: 204 });
      throw new Error(`Unexpected URL: ${url}`);
    });
    vi.stubGlobal("fetch", fetchMock);

    const reader = streamOpenUI({
      apiUrl: "https://langgraph.example",
      assistantId: "agent",
      input: {},
      waitUntil,
    }).getReader();

    const started = await reader.read();
    expect(parseOutput(new TextDecoder().decode(started.value))).toEqual([
      expect.objectContaining({ type: EventType.RUN_STARTED, runId: "run-cancel-cleanup" }),
    ]);
    await reader.cancel();

    expect(waitUntil).toHaveBeenCalledTimes(1);
    expect(fetchMock.mock.calls.some(([, init]) => init?.method === "DELETE")).toBe(true);
  });

  it("closes the relay when the caller signal aborts while output is backpressured", async () => {
    const signals: AbortSignal[] = [];
    const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
      if (init?.signal) signals.push(init.signal);
      if (String(input).endsWith("/stream/events")) {
        return new Response(abortableBody(init?.signal));
      }
      return runStartedResponse("run-abort");
    });
    vi.stubGlobal("fetch", fetchMock);
    const callerAbort = new AbortController();
    const outputReader = streamOpenUI({
      apiUrl: "https://langgraph.example",
      assistantId: "agent",
      input: {},
      signal: callerAbort.signal,
      cleanupThread: false,
    }).getReader();

    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
    callerAbort.abort();

    await expect(outputReader.read()).resolves.toEqual({ done: true, value: undefined });
    expect(signals).toHaveLength(2);
    expect(signals.every((signal) => signal.aborted)).toBe(true);
  });

  it("waits for downstream demand before reading the upstream event stream", async () => {
    let upstreamPulls = 0;
    const eventBody = new ReadableStream<Uint8Array>(
      {
        pull(controller) {
          upstreamPulls += 1;
          controller.enqueue(new TextEncoder().encode(lifecycleFrame({ event: "completed" })));
          controller.close();
        },
      },
      { highWaterMark: 0 },
    );
    const fetchMock = vi.fn(async (input: string | URL | Request) => {
      if (String(input).endsWith("/stream/events")) return new Response(eventBody);
      return runStartedResponse("run-backpressure");
    });
    vi.stubGlobal("fetch", fetchMock);

    const outputReader = streamOpenUI({
      apiUrl: "https://langgraph.example",
      assistantId: "agent",
      input: {},
      cleanupThread: false,
    }).getReader();

    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
    expect(upstreamPulls).toBe(0);

    const start = await outputReader.read();
    expect(parseOutput(new TextDecoder().decode(start.value))).toEqual([
      expect.objectContaining({ type: EventType.RUN_STARTED, runId: "run-backpressure" }),
    ]);
    await vi.waitFor(() => expect(upstreamPulls).toBe(1));

    const finish = await outputReader.read();
    expect(parseOutput(new TextDecoder().decode(finish.value))).toEqual([
      expect.objectContaining({ type: EventType.RUN_FINISHED, runId: "run-backpressure" }),
    ]);
    await expect(outputReader.read()).resolves.toEqual({ done: true, value: undefined });
  });
});

function runStartedResponse(runId: string): Response {
  return Response.json({ type: "success", id: 1, result: { run_id: runId } });
}

function protocolFrame(event: string, data: unknown, newline = "\n"): string {
  return `${bareFrame(event, { type: "event", params: { data } }, newline)}`;
}

function bareFrame(event: string, data: unknown, newline = "\n"): string {
  return `event: ${event}${newline}data: ${JSON.stringify(data)}${newline}${newline}`;
}

function lifecycleFrame(data: unknown, namespace: string[] = []): string {
  return bareFrame("lifecycle", {
    type: "event",
    method: "lifecycle",
    params: { namespace, data },
  });
}

function chunkedBody(chunks: string[]): ReadableStream<Uint8Array> {
  const textEncoder = new TextEncoder();
  return new ReadableStream({
    start(controller) {
      for (const chunk of chunks) controller.enqueue(textEncoder.encode(chunk));
      controller.close();
    },
  });
}

function abortableBody(signal?: AbortSignal | null): ReadableStream<Uint8Array> {
  return new ReadableStream({
    start(controller) {
      signal?.addEventListener(
        "abort",
        () => controller.error(new DOMException("Aborted", "AbortError")),
        { once: true },
      );
    },
  });
}

function parseOutput(output: string): AGUIEvent[] {
  return output
    .trim()
    .split("\n\n")
    .filter(Boolean)
    .map((frame) => JSON.parse(frame.replace(/^data: /, "")) as AGUIEvent);
}

function expectValidAGUIEvents(events: AGUIEvent[]): void {
  for (const event of events) {
    expect(EventSchemas.safeParse(event).success, JSON.stringify(event)).toBe(true);
  }
}