@assistant-ui/react-google-adk 0.0.1

package/src/server/adkEventStream.ts

@@ -0,0 +1,161 @@
+import type { AdkEvent, AdkEventActions, AdkEventPart } from "../types";
+
+/**
+ * The ADK SDK Event type. Intentionally loose to avoid requiring @google/adk.
+ */
+type AdkSdkEvent = {
+  id?: string;
+  invocationId?: string;
+  author?: string;
+  branch?: string;
+  partial?: boolean;
+  turnComplete?: boolean;
+  interrupted?: boolean;
+  finishReason?: string;
+  timestamp?: number;
+  content?: {
+    role?: string;
+    parts?: Array<Record<string, unknown>>;
+  };
+  actions?: Record<string, unknown>;
+  longRunningToolIds?: string[];
+  errorCode?: string;
+  errorMessage?: string;
+  groundingMetadata?: unknown;
+  citationMetadata?: unknown;
+  usageMetadata?: unknown;
+  customMetadata?: Record<string, unknown>;
+};
+
+const convertSdkPart = (part: Record<string, unknown>): AdkEventPart => {
+  const result: Record<string, unknown> = {};
+  if ("text" in part && typeof part.text === "string") result.text = part.text;
+  if ("thought" in part && typeof part.thought === "boolean")
+    result.thought = part.thought;
+  if ("functionCall" in part && part.functionCall)
+    result.functionCall = part.functionCall;
+  if ("functionResponse" in part && part.functionResponse)
+    result.functionResponse = part.functionResponse;
+  if ("executableCode" in part && part.executableCode)
+    result.executableCode = part.executableCode;
+  if ("codeExecutionResult" in part && part.codeExecutionResult)
+    result.codeExecutionResult = part.codeExecutionResult;
+  if ("inlineData" in part && part.inlineData)
+    result.inlineData = part.inlineData;
+  if ("fileData" in part && part.fileData) result.fileData = part.fileData;
+  return result as AdkEventPart;
+};
+
+const convertSdkActions = (
+  actions: Record<string, unknown>,
+): AdkEventActions => {
+  const result: Record<string, unknown> = {};
+  if (actions.stateDelta != null) result.stateDelta = actions.stateDelta;
+  if (actions.artifactDelta != null)
+    result.artifactDelta = actions.artifactDelta;
+  if (actions.transferToAgent != null)
+    result.transferToAgent = actions.transferToAgent;
+  if (actions.escalate != null) result.escalate = actions.escalate;
+  if (actions.skipSummarization != null)
+    result.skipSummarization = actions.skipSummarization;
+  if (actions.requestedAuthConfigs != null)
+    result.requestedAuthConfigs = actions.requestedAuthConfigs;
+  if (actions.requestedToolConfirmations != null)
+    result.requestedToolConfirmations = actions.requestedToolConfirmations;
+  return result as AdkEventActions;
+};
+
+const convertSdkEvent = (event: AdkSdkEvent): AdkEvent => {
+  const result: Record<string, unknown> = { id: event.id ?? "" };
+  if (event.invocationId != null) result.invocationId = event.invocationId;
+  if (event.author != null) result.author = event.author;
+  if (event.branch != null) result.branch = event.branch;
+  if (event.partial != null) result.partial = event.partial;
+  if (event.turnComplete != null) result.turnComplete = event.turnComplete;
+  if (event.interrupted != null) result.interrupted = event.interrupted;
+  if (event.finishReason != null) result.finishReason = event.finishReason;
+  if (event.timestamp != null) result.timestamp = event.timestamp;
+  if (event.content) {
+    const content: Record<string, unknown> = {};
+    if (event.content.role != null) content.role = event.content.role;
+    if (event.content.parts)
+      content.parts = event.content.parts.map(convertSdkPart);
+    result.content = content;
+  }
+  if (event.actions) result.actions = convertSdkActions(event.actions);
+  if (event.longRunningToolIds)
+    result.longRunningToolIds = event.longRunningToolIds;
+  if (event.errorCode != null) result.errorCode = event.errorCode;
+  if (event.errorMessage != null) result.errorMessage = event.errorMessage;
+  if (event.groundingMetadata != null)
+    result.groundingMetadata = event.groundingMetadata;
+  if (event.citationMetadata != null)
+    result.citationMetadata = event.citationMetadata;
+  if (event.usageMetadata != null) result.usageMetadata = event.usageMetadata;
+  if (event.customMetadata != null)
+    result.customMetadata = event.customMetadata;
+  return result as AdkEvent;
+};
+
+export type AdkEventStreamOptions = {
+  onError?: (error: unknown) => void;
+};
+
+/**
+ * Converts an AsyncGenerator of ADK SDK Events into an SSE Response.
+ *
+ * @example
+ * ```ts
+ * import { adkEventStream } from '@assistant-ui/react-google-adk/server';
+ * const events = runner.runAsync({ userId, sessionId, newMessage });
+ * return adkEventStream(events);
+ * ```
+ */
+export const adkEventStream = (
+  events: AsyncGenerator<AdkSdkEvent, void, undefined>,
+  options?: AdkEventStreamOptions,
+): Response => {
+  const encoder = new TextEncoder();
+  let cancelled = false;
+  const stream = new ReadableStream({
+    async start(controller) {
+      // Initial SSE comment to keep connection alive through proxies
+      controller.enqueue(encoder.encode(":ok\n\n"));
+      try {
+        for await (const event of events) {
+          if (cancelled) break;
+          const wireEvent = convertSdkEvent(event);
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(wireEvent)}\n\n`),
+          );
+        }
+      } catch (e) {
+        if (!cancelled) {
+          options?.onError?.(e);
+          const errorEvent: AdkEvent = {
+            id: "",
+            errorCode: "STREAM_ERROR",
+            errorMessage:
+              e instanceof Error ? e.message : "Unknown stream error",
+          };
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(errorEvent)}\n\n`),
+          );
+        }
+      } finally {
+        controller.close();
+      }
+    },
+    async cancel() {
+      cancelled = true;
+      await events.return?.(undefined as any);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+    },
+  });
+};

package/src/server/createAdkApiRoute.test.ts

@@ -0,0 +1,370 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ── Module mocks ──
+
+vi.mock("./parseAdkRequest", () => ({
+  parseAdkRequest: vi.fn(),
+  toAdkContent: vi.fn(),
+}));
+
+vi.mock("./adkEventStream", () => ({
+  adkEventStream: vi.fn(),
+}));
+
+import { createAdkApiRoute } from "./createAdkApiRoute";
+import { parseAdkRequest, toAdkContent } from "./parseAdkRequest";
+import { adkEventStream } from "./adkEventStream";
+
+const mockParseAdkRequest = vi.mocked(parseAdkRequest);
+const mockToAdkContent = vi.mocked(toAdkContent);
+const mockAdkEventStream = vi.mocked(adkEventStream);
+
+const makeRequest = (body: unknown = { message: "Hello" }) =>
+  new Request("http://localhost/api/adk", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+const makeRunner = () => ({
+  runAsync: vi.fn().mockReturnValue(
+    (async function* () {
+      yield { id: "e1" };
+    })(),
+  ),
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockParseAdkRequest.mockResolvedValue({
+    type: "message",
+    text: "Hello",
+    config: {},
+  });
+  mockToAdkContent.mockReturnValue({
+    role: "user",
+    parts: [{ text: "Hello" }],
+  });
+  mockAdkEventStream.mockReturnValue(new Response("stream", { status: 200 }));
+});
+
+// ── Basic flow ──
+
+describe("createAdkApiRoute - basic flow", () => {
+  it("calls parseAdkRequest with the request", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    const req = makeRequest();
+    await handler(req);
+
+    expect(mockParseAdkRequest).toHaveBeenCalledOnce();
+    expect(mockParseAdkRequest).toHaveBeenCalledWith(req);
+  });
+
+  it("calls toAdkContent with the parsed request", async () => {
+    const parsed = { type: "message" as const, text: "Hi", config: {} };
+    mockParseAdkRequest.mockResolvedValue(parsed);
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(mockToAdkContent).toHaveBeenCalledOnce();
+    expect(mockToAdkContent).toHaveBeenCalledWith(parsed);
+  });
+
+  it("calls runner.runAsync with the correct arguments", async () => {
+    const newMessage = { role: "user", parts: [{ text: "Hi" }] };
+    mockToAdkContent.mockReturnValue(newMessage);
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(runner.runAsync).toHaveBeenCalledOnce();
+    expect(runner.runAsync).toHaveBeenCalledWith({
+      userId: "user-1",
+      sessionId: "session-1",
+      newMessage,
+    });
+  });
+
+  it("passes runner.runAsync result to adkEventStream and returns its response", async () => {
+    const runner = makeRunner();
+    const expectedResponse = new Response("ok", { status: 200 });
+    mockAdkEventStream.mockReturnValue(expectedResponse);
+
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    const result = await handler(makeRequest());
+
+    expect(mockAdkEventStream).toHaveBeenCalledOnce();
+    expect(result).toBe(expectedResponse);
+  });
+});
+
+// ── userId and sessionId as functions ──
+
+describe("createAdkApiRoute - dynamic userId/sessionId", () => {
+  it("resolves userId from a function", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: (req) => new URL(req.url).searchParams.get("user") ?? "default",
+      sessionId: "session-1",
+    });
+
+    const req = new Request("http://localhost/api/adk?user=alice", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message: "Hi" }),
+    });
+    await handler(req);
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: "alice" }),
+    );
+  });
+
+  it("resolves sessionId from a function", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: (req) =>
+        new URL(req.url).searchParams.get("session") ?? "default",
+    });
+
+    const req = new Request("http://localhost/api/adk?session=s42", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message: "Hi" }),
+    });
+    await handler(req);
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: "s42" }),
+    );
+  });
+
+  it("resolves async userId function", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: async () => "async-user",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: "async-user" }),
+    );
+  });
+
+  it("resolves async sessionId function", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: async () => "async-session",
+    });
+
+    await handler(makeRequest());
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: "async-session" }),
+    );
+  });
+});
+
+// ── stateDelta passthrough ──
+
+describe("createAdkApiRoute - stateDelta", () => {
+  it("passes stateDelta to runner.runAsync when present", async () => {
+    mockParseAdkRequest.mockResolvedValue({
+      type: "message",
+      text: "Hello",
+      config: {},
+      stateDelta: { count: 1 },
+    });
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ stateDelta: { count: 1 } }),
+    );
+  });
+
+  it("does not include stateDelta when it is null/undefined", async () => {
+    mockParseAdkRequest.mockResolvedValue({
+      type: "message",
+      text: "Hello",
+      config: {},
+    });
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    const callArgs = runner.runAsync.mock.calls[0]![0];
+    expect(callArgs).not.toHaveProperty("stateDelta");
+  });
+});
+
+// ── runConfig passthrough ──
+
+describe("createAdkApiRoute - runConfig", () => {
+  it("passes runConfig to runner.runAsync when present", async () => {
+    mockParseAdkRequest.mockResolvedValue({
+      type: "message",
+      text: "Hello",
+      config: { runConfig: { temperature: 0.5 } },
+    });
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(runner.runAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ runConfig: { temperature: 0.5 } }),
+    );
+  });
+
+  it("does not include runConfig when it is null/undefined", async () => {
+    mockParseAdkRequest.mockResolvedValue({
+      type: "message",
+      text: "Hello",
+      config: {},
+    });
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    const callArgs = runner.runAsync.mock.calls[0]![0];
+    expect(callArgs).not.toHaveProperty("runConfig");
+  });
+});
+
+// ── onError passthrough ──
+
+describe("createAdkApiRoute - onError", () => {
+  it("passes onError to adkEventStream", async () => {
+    const onError = vi.fn();
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+      onError,
+    });
+
+    await handler(makeRequest());
+
+    expect(mockAdkEventStream).toHaveBeenCalledWith(expect.anything(), {
+      onError,
+    });
+  });
+
+  it("does not pass onError when not provided", async () => {
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(mockAdkEventStream).toHaveBeenCalledWith(
+      expect.anything(),
+      undefined,
+    );
+  });
+});
+
+// ── tool-result flow ──
+
+describe("createAdkApiRoute - tool-result flow", () => {
+  it("handles tool-result requests", async () => {
+    const toolParsed = {
+      type: "tool-result" as const,
+      toolCallId: "tc-1",
+      toolName: "search",
+      result: { found: true },
+      isError: false,
+      config: {},
+    };
+    mockParseAdkRequest.mockResolvedValue(toolParsed);
+    mockToAdkContent.mockReturnValue({
+      role: "user",
+      parts: [
+        {
+          functionResponse: {
+            name: "search",
+            id: "tc-1",
+            response: { found: true },
+          },
+        },
+      ],
+    });
+
+    const runner = makeRunner();
+    const handler = createAdkApiRoute({
+      runner,
+      userId: "user-1",
+      sessionId: "session-1",
+    });
+
+    await handler(makeRequest());
+
+    expect(mockToAdkContent).toHaveBeenCalledWith(toolParsed);
+    expect(runner.runAsync).toHaveBeenCalledOnce();
+    const callArgs = runner.runAsync.mock.calls[0]![0];
+    expect(callArgs.newMessage.parts[0]).toMatchObject({
+      functionResponse: { name: "search", id: "tc-1" },
+    });
+  });
+});

package/src/server/createAdkApiRoute.ts

@@ -0,0 +1,86 @@
+import { parseAdkRequest, toAdkContent } from "./parseAdkRequest";
+import { adkEventStream, type AdkEventStreamOptions } from "./adkEventStream";
+
+/**
+ * Loose runner type matching the ADK SDK's Runner interface.
+ * Avoids requiring `@google/adk` as a dependency.
+ */
+type AdkRunner = {
+  runAsync(
+    options: Record<string, unknown>,
+  ): AsyncGenerator<any, void, undefined>;
+};
+
+export type CreateAdkApiRouteOptions = {
+  /**
+   * ADK Runner instance.
+   */
+  runner: AdkRunner;
+
+  /**
+   * User ID to use for the ADK session. Can be a static string
+   * or a function that extracts it from the request.
+   */
+  userId: string | ((req: Request) => string | Promise<string>);
+
+  /**
+   * Session ID to use. Can be a static string or a function
+   * that extracts it from the request (e.g. from query params or headers).
+   */
+  sessionId: string | ((req: Request) => string | Promise<string>);
+
+  /**
+   * Error handler for stream errors.
+   */
+  onError?: AdkEventStreamOptions["onError"];
+};
+
+/**
+ * Creates a request handler that combines `parseAdkRequest`, `toAdkContent`,
+ * and `adkEventStream` into a single function.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * import { createAdkApiRoute } from '@assistant-ui/react-google-adk/server';
+ * import { runner } from './agent';
+ *
+ * export const POST = createAdkApiRoute({
+ *   runner,
+ *   userId: "default-user",
+ *   sessionId: (req) => new URL(req.url).searchParams.get("sessionId") ?? "default",
+ * });
+ * ```
+ */
+export function createAdkApiRoute(
+  options: CreateAdkApiRouteOptions,
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    const parsed = await parseAdkRequest(req);
+    const newMessage = toAdkContent(parsed);
+
+    const userId =
+      typeof options.userId === "function"
+        ? await options.userId(req)
+        : options.userId;
+
+    const sessionId =
+      typeof options.sessionId === "function"
+        ? await options.sessionId(req)
+        : options.sessionId;
+
+    const events = options.runner.runAsync({
+      userId,
+      sessionId,
+      newMessage,
+      ...(parsed.stateDelta != null && { stateDelta: parsed.stateDelta }),
+      ...(parsed.config.runConfig != null && {
+        runConfig: parsed.config.runConfig,
+      }),
+    });
+
+    return adkEventStream(
+      events,
+      options.onError ? { onError: options.onError } : undefined,
+    );
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,6 @@
+export { adkEventStream, type AdkEventStreamOptions } from "./adkEventStream";
+export { parseAdkRequest, toAdkContent } from "./parseAdkRequest";
+export {
+  createAdkApiRoute,
+  type CreateAdkApiRouteOptions,
+} from "./createAdkApiRoute";