feat(showcase/google-adk/headless-complete): port frontend from langgraph-python

Copy the full headless-complete demo verbatim from langgraph-python (the
parity north-star). The demo now exposes the full headless surface
CopilotKit provides: useRenderTool / useDefaultRenderTool, useComponent,
useConfigureSuggestions, useAttachments, plus useRenderToolCall and
useRenderActivityMessage rendered inside a hand-rolled chat shell built on
useAgent + useCopilotKit.

Workspace plumbing required to make the verbatim port runnable:
- Add shadcn primitives (avatar, badge, button, card, scroll-area,
  separator, textarea) and `cn` util at src/components/ui/* + src/lib/utils.ts.
- Add lucide-react, radix-ui, react-markdown, remark-gfm, clsx,
  tailwind-merge, class-variance-authority to package.json.
- Extend globals.css with Tailwind v4 @theme tokens that map onto the
  shadcn CSS variables (background/foreground/card/muted/border/etc.) so
  utilities like `bg-background` actually generate styles.
- Register a `headless-complete` HttpAgent on the existing MCP Apps
  runtime route so the LP frontend's `agent="headless-complete"` resolves
  to the ADK backend path `/headless_complete` (mapped to _simple_chat in
  registry.py).

The ADK `_simple_chat` agent is left unchanged — it already covers the
behaviour the demo exercises (frontend tools, MCP Apps tool calls).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tylerslaton

showcase/integrations/google-adk/package.json

@@ -20,11 +20,18 @@
     "@hashbrownai/react": "0.5.0-beta.4",
     "@json-render/core": "0.18.0",
     "@json-render/react": "0.18.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.14.0",
     "next": "^15.5.15",
     "openai": "^5.9.0",
+    "radix-ui": "^1.4.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
     "recharts": "^2.15.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.5.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {

showcase/integrations/google-adk/src/app/api/copilotkit-mcp-apps/route.ts

@@ -23,6 +23,14 @@ const mcpAppsAgent: AbstractAgent = new HttpAgent({
   url: `${AGENT_URL}/mcp_apps`,
 });
 
+// headless-complete shares this runtime because its cell also exercises
+// MCP Apps rendering (via useRenderActivityMessage). The backend path
+// `/headless_complete` is mounted by the ADK agent_server from the
+// registry entry of the same name (mapped to _simple_chat).
+const headlessCompleteAgent: AbstractAgent = new HttpAgent({
+  url: `${AGENT_URL}/headless_complete`,
+});
+
 // @region[runtime-mcpapps-config]
 // The `mcpApps.servers` config is all you need server-side. The runtime
 // auto-applies the MCP Apps middleware to every registered agent: on each
@@ -35,6 +43,7 @@ const runtime = new CopilotRuntime({
   // fixed in source, pending release.
   agents: {
     mcp_apps: mcpAppsAgent,
+    "headless-complete": headlessCompleteAgent,
   },
   mcpApps: {
     servers: [

showcase/integrations/google-adk/src/app/demos/headless-complete/attachments/attachment-preview.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+/**
+ * Compact chip rendered above the composer for each pending attachment.
+ * Shows a thumbnail (image) or icon (document), the filename, and an X
+ * button to remove. Doubles as the in-message preview rendered alongside
+ * a sent user message in `chat/message-user.tsx`.
+ */
+
+import React from "react";
+import { File, Loader2, X } from "lucide-react";
+import type { Attachment } from "@copilotkit/shared";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+export function AttachmentChip({
+  attachment,
+  onRemove,
+}: {
+  attachment: Attachment;
+  onRemove?: (id: string) => void;
+}) {
+  const isImage = attachment.type === "image";
+  const isUploading = attachment.status === "uploading";
+  const src = isImage ? attachmentSrc(attachment) : undefined;
+
+  return (
+    <div
+      className={cn(
+        "group relative inline-flex items-center gap-2 rounded-lg border bg-card px-2 py-1.5 text-xs shadow-sm",
+        onRemove ? "pr-7" : "pr-2",
+      )}
+    >
+      <div className="flex h-7 w-7 shrink-0 items-center justify-center overflow-hidden rounded-md bg-muted text-muted-foreground">
+        {isUploading ? (
+          <Loader2 className="h-4 w-4 animate-spin" />
+        ) : isImage && src ? (
+          <img
+            src={src}
+            alt={attachment.filename ?? "attachment"}
+            className="h-full w-full object-cover"
+          />
+        ) : (
+          <File className="h-4 w-4" />
+        )}
+      </div>
+      <div className="flex min-w-0 flex-col leading-tight">
+        <span className="max-w-[180px] truncate font-medium text-foreground">
+          {attachment.filename ?? "attachment"}
+        </span>
+        <span className="text-[10px] text-muted-foreground">
+          {isUploading ? "uploading…" : prettyBytes(attachment.size)}
+        </span>
+      </div>
+      {onRemove && (
+        <Button
+          type="button"
+          size="icon"
+          variant="ghost"
+          aria-label="Remove attachment"
+          onClick={() => onRemove(attachment.id)}
+          className="absolute right-0.5 top-1/2 h-5 w-5 -translate-y-1/2"
+        >
+          <X className="h-3 w-3" />
+        </Button>
+      )}
+    </div>
+  );
+}
+
+function attachmentSrc(att: Attachment): string | undefined {
+  const src = att.source;
+  if (src.type === "url") return src.value;
+  if (src.type === "data") {
+    return `data:${src.mimeType};base64,${src.value}`;
+  }
+  return undefined;
+}
+
+function prettyBytes(size?: number): string {
+  if (!size) return "";
+  if (size < 1024) return `${size}B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)}KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)}MB`;
+}

showcase/integrations/google-adk/src/app/demos/headless-complete/attachments/use-attachments-config.ts

@@ -0,0 +1,62 @@
+"use client";
+
+/**
+ * Configures `useAttachments` for the headless-complete demo. Inlines
+ * uploads as base64 (no external storage), accepts images and PDFs, and
+ * caps each file at 20MB.
+ *
+ * The hook returns the full attachment pipeline: `fileInputRef` for the
+ * hidden `<input type="file">`, `containerRef` for paste support,
+ * drag/drop handlers, the live attachment list, plus `consumeAttachments`
+ * which is called at submit time and clears the queue.
+ */
+
+import { useCallback } from "react";
+import {
+  useAttachments,
+  type UseAttachmentsReturn,
+} from "@copilotkit/react-core/v2";
+import type { AttachmentUploadResult } from "@copilotkit/shared";
+
+const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024;
+const ACCEPT_MIME = "image/*,application/pdf";
+
+export function useAttachmentsConfig(): UseAttachmentsReturn {
+  const onUpload = useCallback(fileToBase64, []);
+
+  return useAttachments({
+    config: {
+      enabled: true,
+      accept: ACCEPT_MIME,
+      maxSize: MAX_FILE_SIZE_BYTES,
+      onUpload,
+      onUploadFailed: (err) => {
+        console.warn("[headless-complete] attachment rejected", err);
+      },
+    },
+  });
+}
+
+function fileToBase64(file: File): Promise<AttachmentUploadResult> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () =>
+      reject(reader.error ?? new Error(`FileReader failed for ${file.name}`));
+    reader.onload = () => {
+      const result = reader.result;
+      if (typeof result !== "string") {
+        reject(new Error(`Unexpected FileReader result for ${file.name}`));
+        return;
+      }
+      const commaIdx = result.indexOf(",");
+      const base64 = commaIdx >= 0 ? result.slice(commaIdx + 1) : result;
+      resolve({
+        type: "data",
+        value: base64,
+        mimeType: file.type || "application/octet-stream",
+        metadata: { filename: file.name, size: file.size },
+      });
+    };
+    reader.readAsDataURL(file);
+  });
+}

showcase/integrations/google-adk/src/app/demos/headless-complete/chat/chat.tsx

@@ -0,0 +1,208 @@
+"use client";
+
+/**
+ * Hand-rolled chat shell.
+ *
+ * Owns the read/write loop:
+ * - `useAgent`        — message list, isRunning, addMessage, abortRun, setMessages
+ * - `useCopilotKit`   — `runAgent({ agent })` to dispatch a turn
+ *
+ * Renders the message tree via `<MessageList />` (which uses
+ * `useRenderToolCall` and `useRenderActivityMessage` internally), shows
+ * a typing indicator while the agent is thinking, and composes the
+ * suggestion bar + composer (with attachments) at the bottom.
+ *
+ * The visual chrome is identical to `headless-simple/chat.tsx` — same
+ * outer wrapper, same `Card` shell, same bubble palette — so the two
+ * demos read as a pair.
+ */
+
+import React, { useCallback, useState } from "react";
+import { useAgent, useCopilotKit } from "@copilotkit/react-core/v2";
+import type { Attachment, InputContent } from "@copilotkit/shared";
+import { Card, CardContent } from "@/components/ui/card";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import { Separator } from "@/components/ui/separator";
+import { cn } from "@/lib/utils";
+import { useAttachmentsConfig } from "../attachments/use-attachments-config";
+import { useAutoScroll } from "../hooks/use-auto-scroll";
+import { useTypingIndicator } from "../hooks/use-typing-indicator";
+import { Composer } from "./composer";
+import { EmptyState } from "./empty-state";
+import { Header } from "./header";
+import { MessageList } from "./message-list";
+import { SuggestionBar } from "./suggestion-bar";
+import { TypingIndicator } from "./typing-indicator";
+
+export function Chat({ agentId }: { agentId: string }) {
+  const { agent } = useAgent({ agentId });
+  const { copilotkit } = useCopilotKit();
+
+  const {
+    attachments,
+    fileInputRef,
+    containerRef,
+    handleFileUpload,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    dragOver,
+    removeAttachment,
+    consumeAttachments,
+  } = useAttachmentsConfig();
+
+  const [input, setInput] = useState("");
+  const messages = agent.messages;
+  const { listRef, bottomRef, stickRef } = useAutoScroll(
+    messages,
+    agent.isRunning,
+  );
+
+  // Send pipeline: consume any ready attachments at submit time, build
+  // the multimodal `content` array if needed, then dispatch the run.
+  const sendText = useCallback(
+    (text: string) => {
+      const trimmed = text.trim();
+      // Consume queued uploads first so they get sent even if the user
+      // didn't type any text alongside them.
+      const ready = consumeAttachments();
+      if (!trimmed && ready.length === 0) return;
+      if (agent.isRunning) return;
+
+      stickRef.current = true;
+
+      const content = buildContent(trimmed, ready);
+      agent.addMessage({
+        id: crypto.randomUUID(),
+        role: "user",
+        content,
+      });
+      void copilotkit
+        .runAgent({ agent })
+        .catch((err) =>
+          console.error("[headless-complete] runAgent failed", err),
+        );
+    },
+    [agent, copilotkit, consumeAttachments],
+  );
+
+  const handleSend = useCallback(() => {
+    sendText(input);
+    setInput("");
+  }, [input, sendText]);
+
+  const handleSuggestion = useCallback(
+    (text: string) => {
+      sendText(text);
+    },
+    [sendText],
+  );
+
+  const handleReset = useCallback(() => {
+    if (agent.isRunning) {
+      try {
+        agent.abortRun();
+      } catch {
+        // no-op: some transports don't support abort
+      }
+    }
+    agent.setMessages([]);
+    setInput("");
+    stickRef.current = true;
+  }, [agent]);
+
+  const showTypingIndicator = useTypingIndicator(messages, agent.isRunning);
+
+  const hasUploadingAttachment = attachments.some(
+    (a) => a.status === "uploading",
+  );
+  const hasReadyAttachment = attachments.some((a) => a.status === "ready");
+  const sendDisabled =
+    agent.isRunning ||
+    hasUploadingAttachment ||
+    (!input.trim() && !hasReadyAttachment);
+  const canReset = messages.length > 0 || agent.isRunning;
+  const hasMessages = messages.length > 0;
+
+  return (
+    <div className="flex h-screen w-full justify-center bg-background p-4 sm:p-6">
+      <Card className="flex h-full w-full max-w-3xl flex-col gap-0 overflow-hidden border-border py-0 shadow-2xl shadow-black/10">
+        <Header onReset={handleReset} canReset={canReset} />
+
+        <CardContent className="flex min-h-0 flex-1 flex-col p-0">
+          {!hasMessages ? (
+            // Render empty state outside the ScrollArea so flex-1 + justify-
+            // center actually fills the available height. Radix ScrollArea
+            // wraps its content in a `display: table` div that breaks
+            // `h-full` propagation, so a centered empty state inside it
+            // hugs the top of the viewport.
+            <div className="flex min-h-0 flex-1 flex-col">
+              <EmptyState onPick={handleSuggestion} />
+            </div>
+          ) : (
+            <ScrollArea className="min-h-0 flex-1">
+              <div
+                ref={listRef}
+                className={cn("flex flex-col gap-4 px-4 py-4 sm:px-6")}
+              >
+                <MessageList messages={messages} />
+                {showTypingIndicator && <TypingIndicator />}
+                <div ref={bottomRef} />
+              </div>
+            </ScrollArea>
+          )}
+
+          {hasMessages && (
+            <SuggestionBar
+              agentId={agentId}
+              isRunning={agent.isRunning}
+              onPick={handleSuggestion}
+            />
+          )}
+
+          <Separator className="bg-border/60" />
+
+          <Composer
+            value={input}
+            onChange={setInput}
+            onSend={handleSend}
+            disabled={sendDisabled}
+            isRunning={agent.isRunning}
+            attachments={attachments}
+            onRemoveAttachment={removeAttachment}
+            onFileChange={handleFileUpload}
+            fileInputRef={fileInputRef}
+            containerRef={containerRef}
+            onDragOver={handleDragOver}
+            onDragLeave={handleDragLeave}
+            onDrop={handleDrop}
+            dragOver={dragOver}
+          />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+// Build the user message body. If no attachments, send a plain string
+// (legacy shape). If attachments are present, send the multimodal array
+// — text first, then each attachment as its own InputContent part.
+function buildContent(
+  text: string,
+  attachments: Attachment[],
+): string | InputContent[] {
+  if (attachments.length === 0) return text;
+  const parts: InputContent[] = [];
+  if (text) parts.push({ type: "text", text });
+  for (const att of attachments) {
+    parts.push({
+      type: att.type,
+      source: att.source,
+      metadata: {
+        ...(att.filename ? { filename: att.filename } : {}),
+        ...att.metadata,
+      },
+    } as InputContent);
+  }
+  return parts;
+}