@assistant-ui/mcp-docs-server 0.1.33 → 0.1.35

package/.docs/organized/code-examples/with-pi.md

@@ -0,0 +1,2044 @@
+# Example: with-pi
+
+## app/api/pi/fs/route.ts
+
+```typescript
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve, dirname, join } from "node:path";
+import { withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export type FsEntry = { name: string; path: string };
+export type FsListing = {
+  path: string;
+  parent: string | null;
+  entries: FsEntry[];
+};
+
+const expand = (p: string): string =>
+  p.startsWith("~") ? join(homedir(), p.slice(1)) : p;
+
+export const GET = withFail(async (request: Request) => {
+  // This lists arbitrary host directories for the local workspace picker —
+  // never expose it from a deployed instance.
+  if (process.env.NODE_ENV === "production") {
+    return new Response(null, { status: 404 });
+  }
+  const raw = new URL(request.url).searchParams.get("path");
+  const dir = resolve(raw ? expand(raw) : homedir());
+  const dirents = await readdir(dir, { withFileTypes: true });
+  const entries = dirents
+    .filter((dirent) => dirent.isDirectory() && !dirent.name.startsWith("."))
+    .map((dirent) => ({ name: dirent.name, path: join(dir, dirent.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const parent = dirname(dir);
+  return Response.json({
+    path: dir,
+    parent: parent === dir ? null : parent,
+    entries,
+  } satisfies FsListing);
+});
+
+```
+
+## app/api/pi/handshake/route.ts
+
+```typescript
+import { getHandshake } from "@/lib/pi-server";
+import { withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const GET = withFail(async () => Response.json(await getHandshake()));
+
+```
+
+## app/api/pi/models/route.ts
+
+```typescript
+import { piClient } from "@/lib/pi-server";
+import { withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const GET = withFail(async () =>
+  Response.json(await piClient.getAvailableModels()),
+);
+
+```
+
+## app/api/pi/threads/[threadId]/archive/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (_req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  await piClient.archiveThread(threadId);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/cancel/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (_req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  await piClient.cancelRun(threadId);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/events/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+/**
+ * SSE stream of `PiClientEvent`s for one thread. Snapshot-first by default;
+ * `?snapshot=false` lets a client that already called `GET /threads/:id` attach
+ * only to subsequent live events. A client disconnect unsubscribes but does NOT
+ * abort the Pi run — disconnect ≠ abort.
+ */
+export async function GET(req: NextRequest, { params }: Context) {
+  const { threadId } = await params;
+  const encoder = new TextEncoder();
+  let unsubscribe: (() => void) | undefined;
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  const stream = new TransformStream<Uint8Array, Uint8Array>();
+  const writer = stream.writable.getWriter();
+
+  const write = (chunk: string) => {
+    void writer.write(encoder.encode(chunk)).catch(() => {
+      // Writer already closed (client gone); drop.
+    });
+  };
+
+  const cleanup = () => {
+    unsubscribe?.();
+    if (heartbeat) clearInterval(heartbeat);
+    void writer.close().catch(() => {
+      // Already closed.
+    });
+  };
+
+  // Flush headers through any buffering proxy immediately.
+  write(": connected\n\n");
+  // Keep-alive under typical proxy idle timeouts (30–60s) without the write
+  // churn of a tighter interval.
+  heartbeat = setInterval(() => write(": ping\n\n"), 20_000);
+  unsubscribe = piClient.subscribe(
+    threadId,
+    (event) => {
+      write(`data: ${JSON.stringify(event)}\n\n`);
+    },
+    { includeSnapshot: req.nextUrl.searchParams.get("snapshot") !== "false" },
+  );
+  req.signal.addEventListener("abort", cleanup, { once: true });
+
+  return new Response(stream.readable, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    },
+  });
+}
+
+```
+
+## app/api/pi/threads/[threadId]/host-ui/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import type { PiHostUiResponse } from "@assistant-ui/react-pi";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  const { response } = (await req.json()) as { response: PiHostUiResponse };
+  await piClient.respondToHostUiRequest(threadId, response);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/messages/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import type { PiSendMessageInput } from "@assistant-ui/react-pi";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  const { input } = (await req.json()) as { input: PiSendMessageInput };
+  await piClient.sendMessage(threadId, input);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/model/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  const input = (await req.json()) as { provider: string; modelId: string };
+  await piClient.setModel(threadId, input);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/queue/clear/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (_req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  return Response.json(await piClient.clearQueue(threadId));
+});
+
+```
+
+## app/api/pi/threads/[threadId]/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { badRequest, noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const GET = withFail(async (_req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  return Response.json(await piClient.getThread(threadId));
+});
+
+export const PATCH = withFail(async (req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  const { title } = (await req.json()) as { title?: unknown };
+  if (typeof title !== "string" || title.trim() === "") {
+    return badRequest("title must be a non-empty string");
+  }
+  await piClient.renameThread(threadId, title);
+  return noContent();
+});
+
+export const DELETE = withFail(
+  async (_req: NextRequest, { params }: Context) => {
+    const { threadId } = await params;
+    await piClient.deleteThread(threadId);
+    return noContent();
+  },
+);
+
+```
+
+## app/api/pi/threads/[threadId]/thinking/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import type { PiThinkingLevel } from "@assistant-ui/react-pi";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  const { level } = (await req.json()) as { level: PiThinkingLevel };
+  await piClient.setThinkingLevel(threadId, level);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/[threadId]/unarchive/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { noContent, withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Context = { params: Promise<{ threadId: string }> };
+
+export const POST = withFail(async (_req: NextRequest, { params }: Context) => {
+  const { threadId } = await params;
+  await piClient.unarchiveThread(threadId);
+  return noContent();
+});
+
+```
+
+## app/api/pi/threads/route.ts
+
+```typescript
+import type { NextRequest } from "next/server";
+import { piClient } from "@/lib/pi-server";
+import { withFail } from "@/lib/http";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const GET = withFail(async (req: NextRequest) => {
+  const params = new URL(req.url).searchParams;
+  const workspacePath = params.get("workspacePath") ?? undefined;
+  const includeArchived = params.get("includeArchived") === "true";
+  const threads = await piClient.listThreads({
+    ...(workspacePath ? { workspacePath } : {}),
+    includeArchived,
+  });
+  return Response.json(threads);
+});
+
+export const POST = withFail(async (req: NextRequest) => {
+  const body = await req.json().catch(() => ({}));
+  return Response.json(await piClient.createThread(body));
+});
+
+```
+
+## app/globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@source "../../../packages/ui/src";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.92 0.004 286.32);
+  --primary-foreground: oklch(0.21 0.006 285.885);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+```
+
+## app/layout.tsx
+
+```tsx
+import "./globals.css";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: "assistant-ui × Pi",
+  description: "Pi coding-agent runtime adapter for assistant-ui",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className="h-dvh">
+      <body className="h-dvh overflow-hidden">{children}</body>
+    </html>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import { useEffect, useState } from "react";
+import { Thread } from "../components/assistant-ui/thread";
+import { ThreadList } from "@/components/assistant-ui/thread-list";
+import { usePiThreadState } from "@assistant-ui/react-pi";
+import type { PiRuntimeReadiness } from "@assistant-ui/react-pi";
+// Type-only import — erased at build time, so no server code reaches the client.
+import type { PiHandshake } from "@/lib/pi-server";
+import { PiHandshakeProvider } from "../components/pi-handshake";
+import { PiRuntimeProvider } from "./PiRuntimeProvider";
+import { WorkspaceBrowser } from "../components/workspace-browser";
+
+export default function Home() {
+  const [handshake, setHandshake] = useState<PiHandshake | null>(null);
+  const [workspacePath, setWorkspacePath] = useState("");
+
+  useEffect(() => {
+    let active = true;
+    fetch("/api/pi/handshake")
+      .then((response) => response.json())
+      .then((data: PiHandshake) => {
+        if (!active) return;
+        setHandshake(data);
+        setWorkspacePath(data.workspacePath ?? "");
+      })
+      .catch(() => {
+        /* handshake is best-effort; the runtime still works on env defaults. */
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  return (
+    <PiRuntimeProvider workspacePath={workspacePath || undefined}>
+      <PiHandshakeProvider value={handshake}>
+        <div className="flex h-dvh flex-col overflow-hidden">
+          <Header
+            workspacePath={workspacePath}
+            onCommitWorkspace={setWorkspacePath}
+          />
+          <ReadinessBanner fallback={handshake?.readiness} />
+          <div className="flex min-h-0 flex-grow">
+            <aside className="flex w-72 shrink-0 flex-col overflow-hidden border-r">
+              <div className="flex-1 overflow-y-auto p-3">
+                <ThreadList />
+              </div>
+            </aside>
+            <main className="flex min-h-0 min-w-0 flex-grow flex-col overflow-hidden">
+              <Thread />
+            </main>
+          </div>
+        </div>
+      </PiHandshakeProvider>
+    </PiRuntimeProvider>
+  );
+}
+
+function Header({
+  workspacePath,
+  onCommitWorkspace,
+}: {
+  workspacePath: string;
+  onCommitWorkspace: (value: string) => void;
+}) {
+  return (
+    <header className="flex items-center gap-3 border-b px-4 py-2">
+      <span className="font-semibold">assistant-ui × Pi</span>
+
+      <div className="ml-auto flex items-center gap-2">
+        <WorkspaceBrowser value={workspacePath} onCommit={onCommitWorkspace} />
+      </div>
+    </header>
+  );
+}
+
+function ReadinessBanner({
+  fallback,
+}: {
+  fallback?: PiRuntimeReadiness | undefined;
+}) {
+  const live = usePiThreadState((state) => state.readiness);
+  const readiness = live ?? fallback;
+  if (!readiness || readiness.state === "ready") return null;
+  return (
+    <div className="bg-destructive/10 text-destructive border-destructive/20 border-b px-4 py-2 text-sm">
+      {readiness.message ?? "The Pi runtime has no usable model selected."}
+    </div>
+  );
+}
+
+```
+
+## app/PiRuntimeProvider.tsx
+
+```tsx
+"use client";
+
+import {
+  AssistantRuntimeProvider,
+  SimpleImageAttachmentAdapter,
+} from "@assistant-ui/react";
+import { createPiHttpClient, usePiRuntime } from "@assistant-ui/react-pi";
+import { useMemo, type ReactNode } from "react";
+
+/**
+ * Wires the browser `PiClient` (HTTP/SSE over `/api/pi`) into a Pi runtime. The
+ * client is stable for the app's lifetime; `workspacePath` scopes the thread
+ * list and seeds new sessions. Image attachments ride along as Pi
+ * `ImageContent` (the adapter's data URLs pass through `buildPiSendInput`).
+ */
+export function PiRuntimeProvider({
+  workspacePath,
+  children,
+}: {
+  workspacePath?: string | undefined;
+  children: ReactNode;
+}) {
+  const client = useMemo(() => createPiHttpClient(), []);
+  const adapters = useMemo(
+    () => ({ attachments: new SimpleImageAttachmentAdapter() }),
+    [],
+  );
+  const runtime = usePiRuntime({
+    client,
+    adapters,
+    ...(workspacePath ? { workspacePath } : {}),
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide",
+  "registries": {
+    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
+  }
+}
+
+```
+
+## components/assistant-ui/thinking-level-slider.tsx
+
+```tsx
+"use client";
+
+import type { KeyboardEvent } from "react";
+import { useModelSelectorEfforts } from "@/components/assistant-ui/model-selector";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+
+/**
+ * Line-graph style thinking level picker, composed into ModelSelector.Content
+ * via the useModelSelectorEfforts hook. Pi models expose up to six levels,
+ * which overflow the built-in horizontal ModelSelector.Effort layout — here
+ * each level is a thin vertical line that grows on hover and names itself in
+ * a tooltip, with the active level standing taller in the accent color.
+ */
+export const ThinkingLevelSlider = ({
+  label = "Thinking",
+}: {
+  label?: string;
+}) => {
+  const { efforts, effort, setEffort } = useModelSelectorEfforts();
+
+  if (!efforts?.length) return null;
+
+  const activeIndex = efforts.findIndex((e) => e.id === effort);
+  const lastIndex = efforts.length - 1;
+
+  const selectIndex = (event: KeyboardEvent<HTMLDivElement>, index: number) => {
+    const target = Math.min(Math.max(index, 0), lastIndex);
+    const next = efforts[target];
+    if (!next) return;
+    event.preventDefault();
+    setEffort(next.id);
+    event.currentTarget
+      .querySelectorAll<HTMLElement>('[role="radio"]')
+      [target]?.focus();
+  };
+
+  return (
+    <div className="flex items-center justify-between gap-3 border-t px-3 py-2">
+      <span className="text-muted-foreground text-xs">{label}</span>
+      <div
+        role="radiogroup"
+        aria-label={label}
+        className="flex items-end"
+        onKeyDown={(event) => {
+          if (event.key === "ArrowRight" || event.key === "ArrowUp") {
+            selectIndex(event, activeIndex + 1);
+          } else if (event.key === "ArrowLeft" || event.key === "ArrowDown") {
+            selectIndex(event, activeIndex - 1);
+          } else if (event.key === "Home") {
+            selectIndex(event, 0);
+          } else if (event.key === "End") {
+            selectIndex(event, lastIndex);
+          }
+        }}
+      >
+        {efforts.map((option, index) => {
+          const isActive = index === activeIndex;
+          return (
+            <Tooltip key={option.id} disableHoverableContent>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  role="radio"
+                  aria-checked={isActive}
+                  aria-label={option.name}
+                  tabIndex={index === Math.max(activeIndex, 0) ? 0 : -1}
+                  data-state={isActive ? "on" : "off"}
+                  onClick={() => setEffort(option.id)}
+                  className="group focus-visible:ring-ring/50 flex h-6 w-3.5 items-end justify-center rounded-sm outline-none focus-visible:ring-2"
+                >
+                  <span
+                    className={cn(
+                      "rounded-full transition-all duration-150 ease-out",
+                      isActive
+                        ? "bg-primary h-4.5 w-0.5"
+                        : "bg-muted-foreground/40 group-hover:bg-foreground/70 h-2.5 w-0.5 group-hover:h-4 group-hover:w-[3px] group-focus-visible:h-4 group-focus-visible:w-[3px]",
+                    )}
+                  />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={2}>
+                {option.name}
+              </TooltipContent>
+            </Tooltip>
+          );
+        })}
+      </div>
+      <span className="text-foreground min-w-12 text-end text-xs">
+        {efforts[activeIndex]?.name}
+      </span>
+    </div>
+  );
+};
+
+```
+
+## components/assistant-ui/thread.tsx
+
+```tsx
+"use client";
+
+import {
+  ComposerAddAttachment,
+  ComposerAttachments,
+  UserMessageAttachments,
+} from "@/components/assistant-ui/attachment";
+import { ContextDisplay } from "@/components/assistant-ui/context-display";
+import { ModelSelector } from "@/components/assistant-ui/model-selector";
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import {
+  isPiSteerQueueItemId,
+  responseForRequest,
+  usePiHostUiRequests,
+  usePiRuntimeExtras,
+  usePiThreadState,
+  type PiHostUiRequest,
+  type PiThinkingLevel,
+} from "@assistant-ui/react-pi";
+import { usePiHandshake } from "../pi-handshake";
+import { modelKey } from "@/lib/model-key";
+import { ThinkingLevelSlider } from "./thinking-level-slider";
+import {
+  Reasoning,
+  ReasoningContent,
+  ReasoningRoot,
+  ReasoningText,
+  ReasoningTrigger,
+} from "@/components/assistant-ui/reasoning";
+import {
+  ToolGroupContent,
+  ToolGroupRoot,
+  ToolGroupTrigger,
+} from "@/components/assistant-ui/tool-group";
+import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
+import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import {
+  ActionBarMorePrimitive,
+  ActionBarPrimitive,
+  AuiIf,
+  BranchPickerPrimitive,
+  ComposerPrimitive,
+  ErrorPrimitive,
+  groupPartByType,
+  MessagePrimitive,
+  SuggestionPrimitive,
+  ThreadPrimitive,
+  useAui,
+  useAuiState,
+} from "@assistant-ui/react";
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  CheckIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  DownloadIcon,
+  ListEndIcon,
+  MoreHorizontalIcon,
+  PencilIcon,
+  RefreshCwIcon,
+  SquareIcon,
+  Trash2Icon,
+  WrenchIcon,
+} from "lucide-react";
+import { useState, type FC } from "react";
+
+export const Thread: FC = () => {
+  return (
+    <ThreadPrimitive.Root
+      className="aui-root aui-thread-root bg-background @container flex h-full flex-col"
+      style={{
+        ["--thread-max-width" as string]: "44rem",
+        ["--composer-radius" as string]: "24px",
+        ["--composer-padding" as string]: "10px",
+      }}
+    >
+      <ThreadPrimitive.Viewport
+        data-slot="aui_thread-viewport"
+        className="relative flex flex-1 flex-col overflow-x-auto overflow-y-scroll scroll-smooth"
+      >
+        <div className="mx-auto flex w-full max-w-(--thread-max-width) flex-1 flex-col px-4 pt-4">
+          <AuiIf condition={(s) => s.thread.isEmpty}>
+            <ThreadWelcome />
+          </AuiIf>
+
+          <div
+            data-slot="aui_message-group"
+            className="mb-10 flex flex-col gap-y-8 empty:hidden"
+          >
+            <ThreadPrimitive.Messages>
+              {() => <ThreadMessage />}
+            </ThreadPrimitive.Messages>
+          </div>
+
+          <ThreadPrimitive.ViewportFooter className="aui-thread-viewport-footer bg-background sticky bottom-0 mt-auto flex flex-col gap-4 overflow-visible rounded-t-(--composer-radius) pb-4 md:pb-6">
+            <ThreadScrollToBottom />
+            <HostUiRequests />
+            <Composer />
+          </ThreadPrimitive.ViewportFooter>
+        </div>
+      </ThreadPrimitive.Viewport>
+    </ThreadPrimitive.Root>
+  );
+};
+
+const ThreadMessage: FC = () => {
+  const role = useAuiState((s) => s.message.role);
+  const isEditing = useAuiState((s) => s.message.composer.isEditing);
+
+  if (isEditing) return <EditComposer />;
+  if (role === "user") return <UserMessage />;
+  return <AssistantMessage />;
+};
+
+const ThreadScrollToBottom: FC = () => {
+  return (
+    <ThreadPrimitive.ScrollToBottom asChild>
+      <TooltipIconButton
+        tooltip="Scroll to bottom"
+        variant="outline"
+        className="aui-thread-scroll-to-bottom dark:border-border dark:bg-background dark:hover:bg-accent absolute -top-12 z-10 self-center rounded-full p-4 disabled:invisible"
+      >
+        <ArrowDownIcon />
+      </TooltipIconButton>
+    </ThreadPrimitive.ScrollToBottom>
+  );
+};
+
+const ThreadWelcome: FC = () => {
+  return (
+    <div className="aui-thread-welcome-root my-auto flex grow flex-col">
+      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-center">
+        <div className="aui-thread-welcome-message flex size-full flex-col justify-center px-4">
+          <h1 className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-2xl font-semibold duration-200">
+            Hello there!
+          </h1>
+          <p className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-muted-foreground text-xl delay-75 duration-200">
+            How can I help you today?
+          </p>
+        </div>
+      </div>
+      <ThreadSuggestions />
+    </div>
+  );
+};
+
+const ThreadSuggestions: FC = () => {
+  return (
+    <div className="aui-thread-welcome-suggestions grid w-full gap-2 pb-4 @md:grid-cols-2">
+      <ThreadPrimitive.Suggestions>
+        {() => <ThreadSuggestionItem />}
+      </ThreadPrimitive.Suggestions>
+    </div>
+  );
+};
+
+const ThreadSuggestionItem: FC = () => {
+  return (
+    <div className="aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 animate-in fill-mode-both duration-200 nth-[n+3]:hidden @md:nth-[n+3]:block">
+      <SuggestionPrimitive.Trigger send asChild>
+        <Button
+          variant="ghost"
+          className="aui-thread-welcome-suggestion bg-background hover:bg-muted h-auto w-full flex-wrap items-start justify-start gap-1 rounded-3xl border px-4 py-3 text-start text-sm transition-colors @md:flex-col"
+        >
+          <SuggestionPrimitive.Title className="aui-thread-welcome-suggestion-text-1 font-medium" />
+          <SuggestionPrimitive.Description className="aui-thread-welcome-suggestion-text-2 text-muted-foreground empty:hidden" />
+        </Button>
+      </SuggestionPrimitive.Trigger>
+    </div>
+  );
+};
+
+const HostUiRequests: FC = () => {
+  const { requests, respond } = usePiHostUiRequests();
+  const request = requests[0];
+  if (!request) return null;
+  return (
+    <HostUiRequestCard key={request.id} request={request} respond={respond} />
+  );
+};
+
+const HostUiRequestCard: FC<{
+  request: PiHostUiRequest;
+  respond: ReturnType<typeof usePiHostUiRequests>["respond"];
+}> = ({ request, respond }) => {
+  const [value, setValue] = useState(
+    request.kind === "editor" ? (request.prefill ?? "") : "",
+  );
+
+  const submitValue = () => {
+    void respond(responseForRequest(request, value));
+  };
+
+  return (
+    <div className="border-border bg-background mx-2 rounded-2xl border p-3 text-sm shadow-sm">
+      <div className="font-medium">{request.title}</div>
+      {request.kind === "confirm" ? (
+        <p className="text-muted-foreground mt-1">{request.message}</p>
+      ) : request.kind === "select" ? (
+        <div className="mt-2 flex flex-wrap gap-2">
+          {request.options.map((option) => (
+            <Button
+              key={option}
+              size="sm"
+              variant="outline"
+              onClick={() => void respond(responseForRequest(request, option))}
+            >
+              {option}
+            </Button>
+          ))}
+        </div>
+      ) : request.kind === "editor" ? (
+        <textarea
+          value={value}
+          onChange={(event) => setValue(event.currentTarget.value)}
+          className="border-input mt-2 min-h-24 w-full rounded-md border bg-transparent p-2 font-mono text-xs"
+        />
+      ) : (
+        <input
+          value={value}
+          placeholder={request.placeholder}
+          onChange={(event) => setValue(event.currentTarget.value)}
+          className="border-input mt-2 w-full rounded-md border bg-transparent px-2 py-1"
+        />
+      )}
+      <div className="mt-3 flex justify-end gap-2">
+        <Button
+          size="sm"
+          variant="ghost"
+          onClick={() =>
+            void respond(
+              request.kind === "confirm"
+                ? responseForRequest(request, false)
+                : { requestId: request.id, dismissed: true },
+            )
+          }
+        >
+          {request.kind === "confirm" ? "Deny" : "Dismiss"}
+        </Button>
+        {request.kind !== "select" && (
+          <Button
+            size="sm"
+            onClick={() =>
+              request.kind === "confirm"
+                ? void respond(responseForRequest(request, true))
+                : submitValue()
+            }
+          >
+            {request.kind === "confirm" ? "Approve" : "Submit"}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+};
+
+/** Mid-run sends sit in Pi's queue (not the thread); this card mirrors them
+ * above the composer. Pi only supports clearing the whole queue — no per-item
+ * remove/promote — so the lone action restores all queued text to the composer. */
+const ComposerQueue: FC = () => {
+  const aui = useAui();
+  const { clearQueue } = usePiRuntimeExtras();
+  const queueLength = useAuiState((s) => s.composer.queue.length);
+  if (queueLength === 0) return null;
+
+  const handleClear = () => {
+    clearQueue()
+      .then(({ steering, followUp }) => {
+        const restored = [...steering, ...followUp].join("\n");
+        if (!restored) return;
+        const composer = aui.composer();
+        const current = composer.getState().text;
+        composer.setText(current ? `${current}\n${restored}` : restored);
+      })
+      .catch((error: unknown) => console.error("Failed to clear queue", error));
+  };
+
+  return (
+    <div className="bg-muted/50 border-border/60 text-muted-foreground -mb-4 flex flex-col gap-1.5 rounded-t-(--composer-radius) border border-b-0 px-4 pt-2.5 pb-7 text-sm">
+      <div className="flex items-center justify-between gap-2">
+        <span className="text-xs font-medium">Queued</span>
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-6 gap-1 px-2 text-xs"
+          onClick={handleClear}
+        >
+          <Trash2Icon className="size-3" />
+          Clear
+        </Button>
+      </div>
+      <ComposerPrimitive.Queue>
+        {({ queueItem }) => (
+          <div className="flex items-center gap-2">
+            <ListEndIcon className="size-3.5 shrink-0" />
+            <span className="min-w-0 flex-1 truncate">{queueItem.prompt}</span>
+            {isPiSteerQueueItemId(queueItem.id) && (
+              <span className="border-border rounded-full border px-1.5 text-[10px] uppercase">
+                steer
+              </span>
+            )}
+          </div>
+        )}
+      </ComposerPrimitive.Queue>
+    </div>
+  );
+};
+
+const Composer: FC = () => {
+  return (
+    <ComposerPrimitive.Root className="aui-composer-root relative flex w-full flex-col">
+      <ComposerQueue />
+      <ComposerPrimitive.AttachmentDropzone asChild>
+        <div
+          data-slot="aui_composer-shell"
+          className="bg-background focus-within:border-ring/75 focus-within:ring-ring/20 data-[dragging=true]:border-ring data-[dragging=true]:bg-accent/50 flex w-full flex-col gap-2 rounded-(--composer-radius) border p-(--composer-padding) transition-shadow focus-within:ring-2 data-[dragging=true]:border-dashed"
+        >
+          <ComposerAttachments />
+          <ComposerPrimitive.Input
+            placeholder="Send a message..."
+            className="aui-composer-input placeholder:text-muted-foreground/80 max-h-32 min-h-10 w-full resize-none bg-transparent px-1.75 py-1 text-sm outline-none"
+            rows={1}
+            autoFocus
+            aria-label="Message input"
+          />
+          <ComposerAction />
+        </div>
+      </ComposerPrimitive.AttachmentDropzone>
+    </ComposerPrimitive.Root>
+  );
+};
+
+const ComposerAction: FC = () => {
+  return (
+    <div className="aui-composer-action-wrapper relative flex items-center justify-between">
+      <div className="flex items-center gap-1">
+        <ComposerAddAttachment />
+        <ComposerModelSelector />
+      </div>
+      <div className="flex items-center gap-1.5">
+        <ComposerContextRing />
+        {/* Pi queues mid-run sends (follow-up/steer), so Send stays available
+            while text is typed even during a run; Stop shows when empty. */}
+        <AuiIf condition={(s) => !s.thread.isRunning || !s.composer.isEmpty}>
+          <ComposerPrimitive.Send asChild>
+            <TooltipIconButton
+              tooltip="Send message"
+              side="bottom"
+              type="button"
+              variant="default"
+              size="icon"
+              className="aui-composer-send size-8 rounded-full"
+              aria-label="Send message"
+            >
+              <ArrowUpIcon className="aui-composer-send-icon size-4" />
+            </TooltipIconButton>
+          </ComposerPrimitive.Send>
+        </AuiIf>
+        <AuiIf condition={(s) => s.thread.isRunning && s.composer.isEmpty}>
+          <ComposerPrimitive.Cancel asChild>
+            <Button
+              type="button"
+              variant="default"
+              size="icon"
+              className="aui-composer-cancel size-8 rounded-full"
+              aria-label="Stop generating"
+            >
+              <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
+            </Button>
+          </ComposerPrimitive.Cancel>
+        </AuiIf>
+      </div>
+    </div>
+  );
+};
+
+const selectedModelKey = (provider?: string, modelId?: string) =>
+  provider && modelId ? modelKey(provider, modelId) : undefined;
+
+/** Model + thinking-level picker seeded from the server handshake and wired to
+ * Pi's per-thread `session.setModel`/`session.setThinkingLevel`. Per-model
+ * thinking levels come from the handshake; Pi clamps unsupported levels and the
+ * effective config is reflected by the next snapshot/event. */
+const ComposerModelSelector: FC = () => {
+  const handshake = usePiHandshake();
+  const { metadata, setModel, setThinkingLevel, status } = usePiRuntimeExtras();
+  const selected =
+    selectedModelKey(metadata.config?.provider, metadata.config?.modelId) ??
+    handshake?.selectedModelId;
+  const thinkingLevel = metadata.config?.thinkingLevel;
+  if (!handshake || handshake.models.length === 0) return null;
+
+  return (
+    <ModelSelector.Root
+      models={handshake.models}
+      {...(selected ? { value: selected } : {})}
+      onValueChange={(value) => {
+        if (status === "running") return;
+        const model = handshake.models.find((m) => m.id === value);
+        if (!model) return;
+        void setModel({ provider: model.provider, modelId: model.modelId });
+      }}
+      effort={typeof thinkingLevel === "string" ? thinkingLevel : "medium"}
+      onEffortChange={(effort) => {
+        if (status === "running") return;
+        void setThinkingLevel(effort as PiThinkingLevel);
+      }}
+    >
+      <ModelSelector.Trigger variant="ghost" size="sm" />
+      <ModelSelector.Content>
+        <ModelSelector.Search />
+        <ModelSelector.List />
+        {/* Custom slider instead of ModelSelector.Effort: Pi's six thinking
+            levels overflow the horizontal segmented layout. */}
+        <ThinkingLevelSlider />
+      </ModelSelector.Content>
+    </ModelSelector.Root>
+  );
+};
+
+/** Context-window usage as a ring beside the send button. Driven by Pi's
+ * `context_usage` events (`usePiThreadState`); hidden until the first run
+ * reports a window. */
+const ComposerContextRing: FC = () => {
+  const usage = usePiThreadState((s) => s.contextUsage);
+  if (!usage || !usage.contextWindow) return null;
+  return (
+    <ContextDisplay.Ring
+      modelContextWindow={usage.contextWindow}
+      usage={{ totalTokens: usage.tokens ?? 0 }}
+      side="top"
+    />
+  );
+};
+
+const MessageError: FC = () => {
+  return (
+    <MessagePrimitive.Error>
+      <ErrorPrimitive.Root className="aui-message-error-root border-destructive bg-destructive/10 text-destructive dark:bg-destructive/5 mt-2 rounded-md border p-3 text-sm dark:text-red-200">
+        <ErrorPrimitive.Message className="aui-message-error-message line-clamp-2" />
+      </ErrorPrimitive.Root>
+    </MessagePrimitive.Error>
+  );
+};
+
+const AssistantMessage: FC = () => {
+  // reserves space for action bar and compensates with `-mb` for consistent msg spacing
+  // keeps hovered action bar from shifting layout (autohide doesn't support absolute positioning well)
+  // for pt-[n] use -mb-[n + 6] & min-h-[n + 6] to preserve compensation
+  const ACTION_BAR_PT = "pt-1.5";
+  const ACTION_BAR_HEIGHT = `-mb-7.5 min-h-7.5 ${ACTION_BAR_PT}`;
+
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_assistant-message-root"
+      data-role="assistant"
+      className="fade-in slide-in-from-bottom-1 animate-in relative duration-150"
+    >
+      <div
+        data-slot="aui_assistant-message-content"
+        // [contain-intrinsic-size:auto_24px] fixes issue #4104, don't change without checking for regressions
+        className="text-foreground px-2 leading-relaxed wrap-break-word [contain-intrinsic-size:auto_24px] [content-visibility:auto]"
+      >
+        <MessagePrimitive.GroupedParts
+          groupBy={groupPartByType({
+            reasoning: ["group-chainOfThought", "group-reasoning"],
+            "tool-call": ["group-chainOfThought", "group-tool"],
+            "standalone-tool-call": [],
+          })}
+        >
+          {({ part, children }) => {
+            switch (part.type) {
+              case "group-chainOfThought":
+                return <div data-slot="aui_chain-of-thought">{children}</div>;
+              case "group-reasoning": {
+                const running = part.status.type === "running";
+                return (
+                  <ReasoningRoot
+                    defaultOpen={running}
+                    variant="ghost"
+                    className="my-1 mb-0"
+                  >
+                    <ReasoningTrigger active={running} />
+                    <ReasoningContent aria-busy={running}>
+                      <ReasoningText>{children}</ReasoningText>
+                    </ReasoningContent>
+                  </ReasoningRoot>
+                );
+              }
+              case "group-tool":
+                if (part.indices.length === 1) return <>{children}</>;
+                return (
+                  <ToolGroupRoot variant="ghost" className="my-1">
+                    <div className="text-muted-foreground flex items-center gap-2">
+                      <WrenchIcon className="size-4 shrink-0" />
+                      <ToolGroupTrigger
+                        count={part.indices.length}
+                        active={part.status.type === "running"}
+                      />
+                    </div>
+                    <ToolGroupContent className="ml-5">
+                      {children}
+                    </ToolGroupContent>
+                  </ToolGroupRoot>
+                );
+              case "text":
+                return <MarkdownText />;
+              case "reasoning":
+                return <Reasoning {...part} />;
+              case "tool-call":
+                return part.toolUI ?? <ToolFallback {...part} />;
+              case "indicator":
+                return (
+                  <span
+                    data-slot="aui_assistant-message-indicator"
+                    className="animate-pulse font-sans"
+                    aria-label="Assistant is working"
+                  >
+                    {"●"}
+                  </span>
+                );
+              default:
+                return null;
+            }
+          }}
+        </MessagePrimitive.GroupedParts>
+        <MessageError />
+      </div>
+
+      <div
+        data-slot="aui_assistant-message-footer"
+        className={cn("ms-2 flex items-center", ACTION_BAR_HEIGHT)}
+      >
+        <BranchPicker />
+        <AssistantActionBar />
+      </div>
+    </MessagePrimitive.Root>
+  );
+};
+
+const AssistantActionBar: FC = () => {
+  return (
+    <ActionBarPrimitive.Root
+      hideWhenRunning
+      autohide="not-last"
+      className="aui-assistant-action-bar-root text-muted-foreground col-start-3 row-start-2 -ms-1 flex gap-1"
+    >
+      <ActionBarPrimitive.Copy asChild>
+        <TooltipIconButton tooltip="Copy">
+          <AuiIf condition={(s) => s.message.isCopied}>
+            <CheckIcon />
+          </AuiIf>
+          <AuiIf condition={(s) => !s.message.isCopied}>
+            <CopyIcon />
+          </AuiIf>
+        </TooltipIconButton>
+      </ActionBarPrimitive.Copy>
+      <ActionBarPrimitive.Reload asChild>
+        <TooltipIconButton tooltip="Refresh">
+          <RefreshCwIcon />
+        </TooltipIconButton>
+      </ActionBarPrimitive.Reload>
+      <ActionBarMorePrimitive.Root>
+        <ActionBarMorePrimitive.Trigger asChild>
+          <TooltipIconButton
+            tooltip="More"
+            className="data-[state=open]:bg-accent"
+          >
+            <MoreHorizontalIcon />
+          </TooltipIconButton>
+        </ActionBarMorePrimitive.Trigger>
+        <ActionBarMorePrimitive.Content
+          side="bottom"
+          align="start"
+          className="aui-action-bar-more-content bg-popover text-popover-foreground z-50 min-w-32 overflow-hidden rounded-md border p-1 shadow-md"
+        >
+          <ActionBarPrimitive.ExportMarkdown asChild>
+            <ActionBarMorePrimitive.Item className="aui-action-bar-more-item hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none select-none">
+              <DownloadIcon className="size-4" />
+              Export as Markdown
+            </ActionBarMorePrimitive.Item>
+          </ActionBarPrimitive.ExportMarkdown>
+        </ActionBarMorePrimitive.Content>
+      </ActionBarMorePrimitive.Root>
+    </ActionBarPrimitive.Root>
+  );
+};
+
+const UserMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_user-message-root"
+      className="fade-in slide-in-from-bottom-1 animate-in grid auto-rows-auto grid-cols-[minmax(72px,1fr)_auto] content-start gap-y-2 px-2 duration-150 [contain-intrinsic-size:auto_60px] [content-visibility:auto] [&:where(>*)]:col-start-2"
+      data-role="user"
+    >
+      <UserMessageAttachments />
+
+      <div className="aui-user-message-content-wrapper relative col-start-2 min-w-0">
+        <div className="aui-user-message-content peer bg-muted text-foreground rounded-2xl px-4 py-2.5 wrap-break-word empty:hidden">
+          <MessagePrimitive.Parts />
+        </div>
+        <div className="aui-user-action-bar-wrapper absolute start-0 top-1/2 -translate-x-full -translate-y-1/2 pe-2 peer-empty:hidden rtl:translate-x-full">
+          <UserActionBar />
+        </div>
+      </div>
+
+      <BranchPicker
+        data-slot="aui_user-branch-picker"
+        className="col-span-full col-start-1 row-start-3 -me-1 justify-end"
+      />
+    </MessagePrimitive.Root>
+  );
+};
+
+const UserActionBar: FC = () => {
+  return (
+    <ActionBarPrimitive.Root
+      hideWhenRunning
+      autohide="not-last"
+      className="aui-user-action-bar-root flex flex-col items-end"
+    >
+      <ActionBarPrimitive.Edit asChild>
+        <TooltipIconButton tooltip="Edit" className="aui-user-action-edit p-4">
+          <PencilIcon />
+        </TooltipIconButton>
+      </ActionBarPrimitive.Edit>
+    </ActionBarPrimitive.Root>
+  );
+};
+
+const EditComposer: FC = () => {
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_edit-composer-wrapper"
+      className="flex flex-col px-2"
+    >
+      <ComposerPrimitive.Root className="aui-edit-composer-root bg-muted ms-auto flex w-full max-w-[85%] flex-col rounded-2xl">
+        <ComposerPrimitive.Input
+          className="aui-edit-composer-input text-foreground min-h-14 w-full resize-none bg-transparent p-4 text-sm outline-none"
+          autoFocus
+        />
+        <div className="aui-edit-composer-footer mx-3 mb-3 flex items-center gap-2 self-end">
+          <ComposerPrimitive.Cancel asChild>
+            <Button variant="ghost" size="sm">
+              Cancel
+            </Button>
+          </ComposerPrimitive.Cancel>
+          <ComposerPrimitive.Send asChild>
+            <Button size="sm">Update</Button>
+          </ComposerPrimitive.Send>
+        </div>
+      </ComposerPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+};
+
+const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
+  className,
+  ...rest
+}) => {
+  return (
+    <BranchPickerPrimitive.Root
+      hideWhenSingleBranch
+      className={cn(
+        "aui-branch-picker-root text-muted-foreground -ms-2 me-2 inline-flex items-center text-xs",
+        className,
+      )}
+      {...rest}
+    >
+      <BranchPickerPrimitive.Previous asChild>
+        <TooltipIconButton tooltip="Previous">
+          <ChevronLeftIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Previous>
+      <span className="aui-branch-picker-state font-medium">
+        <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+      </span>
+      <BranchPickerPrimitive.Next asChild>
+        <TooltipIconButton tooltip="Next">
+          <ChevronRightIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Next>
+    </BranchPickerPrimitive.Root>
+  );
+};
+
+```
+
+## components/pi-handshake.tsx
+
+```tsx
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { ModelOption } from "@/components/assistant-ui/model-selector";
+
+/** The slice of the server handshake the composer needs to render its model
+ * selector. Provided by the page (which fetches `/api/pi/handshake`) and
+ * consumed deep inside the composer, so the model picker can live in the
+ * composer action bar without prop-drilling through the Thread. */
+export type PiModelOption = ModelOption & {
+  provider: string;
+  modelId: string;
+};
+
+export type PiHandshakeValue = {
+  models: PiModelOption[];
+  selectedModelId?: string | undefined;
+};
+
+const PiHandshakeContext = createContext<PiHandshakeValue | null>(null);
+
+export function PiHandshakeProvider({
+  value,
+  children,
+}: {
+  value: PiHandshakeValue | null;
+  children: ReactNode;
+}) {
+  return (
+    <PiHandshakeContext.Provider value={value}>
+      {children}
+    </PiHandshakeContext.Provider>
+  );
+}
+
+export function usePiHandshake(): PiHandshakeValue | null {
+  return useContext(PiHandshakeContext);
+}
+
+```
+
+## components/workspace-browser.tsx
+
+```tsx
+"use client";
+
+import { useRef, useState } from "react";
+import { ArrowLeft, Folder } from "lucide-react";
+import type { FsListing } from "@/app/api/pi/fs/route";
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import { Spinner } from "@/components/ui/spinner";
+
+/** Server-backed directory browser. Click a folder to navigate in; the footer
+ *  commits whatever directory is currently in view. */
+export function WorkspaceBrowser({
+  value,
+  onCommit,
+}: {
+  value: string;
+  onCommit: (path: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [listing, setListing] = useState<FsListing | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Monotonic request token: rapid navigation fires overlapping fetches, and a
+  // slow earlier response must not overwrite the directory navigated to last.
+  const requestSeq = useRef(0);
+
+  const load = (path?: string) => {
+    const seq = ++requestSeq.current;
+    setLoading(true);
+    setError(null);
+    const qs = path ? `?path=${encodeURIComponent(path)}` : "";
+    fetch(`/api/pi/fs${qs}`)
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to list directory (HTTP ${response.status})`);
+        }
+        return (await response.json()) as FsListing;
+      })
+      .then((data) => {
+        if (seq === requestSeq.current) setListing(data);
+      })
+      .catch((err: unknown) => {
+        if (seq === requestSeq.current) {
+          setError(err instanceof Error ? err.message : String(err));
+        }
+      })
+      .finally(() => {
+        if (seq === requestSeq.current) setLoading(false);
+      });
+  };
+
+  const currentName = value.split("/").filter(Boolean).at(-1);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) load(value || undefined);
+      }}
+    >
+      <div className="flex items-center gap-2">
+        {currentName && (
+          <span
+            className="text-muted-foreground max-w-72 truncate font-mono text-xs"
+            title={value}
+          >
+            …/{currentName}
+          </span>
+        )}
+        <DialogTrigger asChild>
+          <Button variant="outline" size="sm">
+            Browse…
+          </Button>
+        </DialogTrigger>
+      </div>
+
+      <DialogContent className="sm:max-w-lg">
+        <DialogHeader className="min-w-0">
+          <DialogTitle>Select workspace</DialogTitle>
+          <DialogDescription className="truncate font-mono text-xs">
+            {listing?.path ?? "…"}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="flex items-center gap-2">
+          <Button
+            variant="ghost"
+            size="xs"
+            disabled={!listing?.parent || loading}
+            onClick={() => listing?.parent && load(listing.parent)}
+          >
+            <ArrowLeft /> Back
+          </Button>
+          {loading && <Spinner className="size-4" />}
+        </div>
+
+        <ScrollArea className="h-72 min-w-0 rounded-md border [&_[data-radix-scroll-area-viewport]>div]:!block">
+          {error && (
+            <p className="text-destructive px-3 py-2 text-xs">{error}</p>
+          )}
+          {listing?.entries.map((entry) => (
+            <button
+              key={entry.path}
+              type="button"
+              onClick={() => load(entry.path)}
+              className="hover:bg-accent flex w-full min-w-0 items-center gap-2 px-3 py-1.5 text-left font-mono text-xs"
+            >
+              <Folder className="size-3.5 shrink-0" />
+              <span className="truncate">{entry.name}</span>
+            </button>
+          ))}
+          {listing && listing.entries.length === 0 && (
+            <p className="text-muted-foreground px-3 py-2 text-xs">
+              No subfolders
+            </p>
+          )}
+        </ScrollArea>
+
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="ghost" size="sm">
+              Cancel
+            </Button>
+          </DialogClose>
+          <Button
+            size="sm"
+            disabled={!listing}
+            onClick={() => {
+              if (listing) onCommit(listing.path);
+              setOpen(false);
+            }}
+          >
+            Select this folder
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+```
+
+## lib/http.ts
+
+```typescript
+/** Shared response helpers for the Pi example routes. */
+
+/** 500 with a JSON `{ error }` body — `createPiHttpClient` surfaces the text. */
+export const fail = (error: unknown): Response =>
+  Response.json(
+    { error: error instanceof Error ? error.message : String(error) },
+    { status: 500 },
+  );
+
+/** 400 with a JSON `{ error }` body, for invalid request input. */
+export const badRequest = (message: string): Response =>
+  Response.json({ error: message }, { status: 400 });
+
+/** 204 for write endpoints that return nothing. */
+export const noContent = (): Response => new Response(null, { status: 204 });
+
+/** Wrap a route handler so any thrown error becomes a `fail()` response. */
+export const withFail =
+  <Args extends unknown[]>(
+    handler: (...args: Args) => Response | Promise<Response>,
+  ) =>
+  async (...args: Args): Promise<Response> => {
+    try {
+      return await handler(...args);
+    } catch (error) {
+      return fail(error);
+    }
+  };
+
+```
+
+## lib/model-key.ts
+
+```typescript
+/** Stable, collision-free model option id — model ids repeat across providers.
+ * Shared by the server handshake and the composer's model selector; the two
+ * must agree for the seeded selection to preselect in the UI. */
+export const modelKey = (provider: string, modelId: string): string =>
+  `${provider}:${modelId}`;
+
+```
+
+## lib/pi-server.ts
+
+```typescript
+/**
+ * Server-only Pi wiring for the example.
+ *
+ * Owns the process-singleton `createPiNodeClient` (the in-process SDK host) and
+ * the env-seeded model resolution. Imported only from route
+ * handlers — never from a client component — so the Pi SDK and its file I/O stay
+ * on the server.
+ *
+ * Model resolution mirrors what Pi's own `createAgentSession` does: an explicit
+ * PI_PROVIDER + PI_MODEL_ID wins, otherwise we fall back to Pi's configured
+ * default (`settings.json`'s `defaultProvider`/`defaultModel`, read via
+ * `SettingsManager`). The resolved `Model` is handed to the supervisor as the
+ * default for every new session, and powers the model-selector catalog and the
+ * readiness banner. So a user who is simply authenticated with `pi` (and has a
+ * default model picked) needs no env at all.
+ *
+ * `PI_CODING_AGENT_DIR` is Pi's own env var for the agent config dir
+ * (~/.pi/agent by default); when set, every Pi config source below points at it.
+ */
+import {
+  AuthStorage,
+  ModelRegistry,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  createPiNodeClient,
+  type PiModelInfo,
+  type PiRuntimeReadiness,
+  type PiThinkingLevel,
+} from "@assistant-ui/react-pi/node";
+import { modelKey } from "./model-key";
+
+const env = (key: string): string | undefined => {
+  const value = process.env[key];
+  return value && value.trim() ? value.trim() : undefined;
+};
+
+const workspacePath = env("PI_WORKSPACE_PATH") ?? process.cwd();
+const agentDir = env("PI_CODING_AGENT_DIR");
+
+const authStorage = AuthStorage.create(
+  agentDir ? `${agentDir}/auth.json` : undefined,
+);
+const modelRegistry = ModelRegistry.create(authStorage);
+const settingsManager = SettingsManager.create(workspacePath, agentDir);
+
+// Env wins; otherwise fall back to Pi's configured default (settings.json).
+const provider = env("PI_PROVIDER") ?? settingsManager.getDefaultProvider();
+const modelId = env("PI_MODEL_ID") ?? settingsManager.getDefaultModel();
+const modelSource: "env" | "pi-default" =
+  env("PI_PROVIDER") && env("PI_MODEL_ID") ? "env" : "pi-default";
+
+const seededModel =
+  provider && modelId ? modelRegistry.find(provider, modelId) : undefined;
+
+export const piClient = createPiNodeClient({
+  workspacePath,
+  ...(agentDir ? { agentDir } : {}),
+  ...(seededModel ? { model: seededModel } : {}),
+});
+
+export type PiModelOption = {
+  id: string;
+  name: string;
+  description?: string;
+  provider: string;
+  modelId: string;
+  /** Thinking levels the model supports; omitted for non-reasoning models. */
+  efforts?: { id: string; name: string }[];
+};
+
+/** Display names for Pi's thinking levels (the UI-facing half of `efforts`;
+ * which levels a model supports comes from `PiModelInfo`). */
+const THINKING_LEVEL_NAMES: Record<PiThinkingLevel, string> = {
+  off: "Off",
+  minimal: "Minimal",
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  xhigh: "xHigh",
+};
+
+const ALL_THINKING_LEVELS = Object.keys(
+  THINKING_LEVEL_NAMES,
+) as PiThinkingLevel[];
+
+const thinkingEfforts = (
+  model: PiModelInfo,
+): { id: string; name: string }[] | undefined => {
+  if (!model.supportsThinking) return undefined;
+  // No `availableThinkingLevels` means the model declares no per-level map;
+  // every level stays selectable (provider defaults apply).
+  return (model.availableThinkingLevels ?? ALL_THINKING_LEVELS).map((id) => ({
+    id,
+    name: THINKING_LEVEL_NAMES[id],
+  }));
+};
+
+export type PiHandshake = {
+  workspacePath: string;
+  /** Models Pi can run here (auth-configured first, else the full catalog). */
+  models: PiModelOption[];
+  /** The env-seeded selection, shown as the selector's default. */
+  selectedModelId: string | undefined;
+  readiness: PiRuntimeReadiness;
+};
+
+const computeReadiness = (): PiRuntimeReadiness => {
+  if (!provider || !modelId) {
+    return {
+      state: "missing-model",
+      message:
+        "No default model configured. Pick one with `pi`, or set PI_PROVIDER and PI_MODEL_ID.",
+    };
+  }
+  if (!seededModel) {
+    return {
+      state: "unavailable-model",
+      selection: { provider, modelId },
+      message: `${provider}/${modelId} is not in Pi's model registry.`,
+    };
+  }
+  if (!modelRegistry.hasConfiguredAuth(seededModel)) {
+    return {
+      state: "missing-credentials",
+      provider,
+      message: `No credentials configured for ${provider}. Authenticate with \`pi\`, then restart the server.`,
+    };
+  }
+  return {
+    state: "ready",
+    selection: { provider, modelId },
+    source: modelSource,
+  };
+};
+
+export const getHandshake = async (): Promise<PiHandshake> => {
+  const catalog = await piClient.getAvailableModels();
+  return {
+    workspacePath,
+    models: catalog.map((model) => {
+      const efforts = thinkingEfforts(model);
+      return {
+        id: modelKey(model.provider, model.modelId),
+        name: model.name ?? model.modelId,
+        description: model.provider,
+        provider: model.provider,
+        modelId: model.modelId,
+        ...(efforts ? { efforts } : {}),
+      };
+    }),
+    selectedModelId: seededModel
+      ? modelKey(String(seededModel.provider), seededModel.id)
+      : undefined,
+    readiness: computeReadiness(),
+  };
+};
+
+```
+
+## next.config.ts
+
+```typescript
+import { withAui } from "@assistant-ui/next";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // The Pi SDK is a native Node dependency; keep it external to the server
+  // bundle so Next doesn't try to trace/bundle it.
+  serverExternalPackages: ["@earendil-works/pi-coding-agent"],
+};
+
+export default withAui(nextConfig);
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-pi",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-markdown": "workspace:*",
+    "@assistant-ui/react-pi": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "@earendil-works/pi-coding-agent": "^0.79.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.18.0",
+    "next": "^16.2.9",
+    "radix-ui": "^1.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.3.1",
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# assistant-ui × Pi
+
+A minimal local harness for the [`@assistant-ui/react-pi`](../../packages/react-pi)
+adapter, driving the [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+in-process.
+
+It demonstrates the MVP surface: a thread list, new sessions, a composer with
+steer / follow-up / stop, streaming assistant responses (text + reasoning), tool
+cards with streaming output, the blocking host-UI dialogs (confirm / input /
+select / editor), a model + credential readiness banner, and a context-usage
+indicator. It proves the adapter surface, not a full desktop app shell.
+
+## How it fits together
+
+```
+browser                         server (Next.js, Node runtime)
+─────────                       ──────────────────────────────
+usePiRuntime                    app/api/pi/**            ← route layer
+  └ createPiHttpClient  ──HTTP──▶ piClient = createPiNodeClient(...)
+       (fetch + SSE)               └ PiThreadSupervisor → Pi SDK (AgentSession)
+```
+
+`createPiHttpClient` and the route layer are two halves of one `PiClient`
+contract: the browser talks HTTP/SSE, the server runs the SDK in-process behind
+the process-singleton supervisor.
+
+## Model resolution
+
+Resolution mirrors Pi's own `createAgentSession` (PI_MVP_PLAN §5): if you set
+`PI_PROVIDER` + `PI_MODEL_ID` they win; otherwise the server falls back to Pi's
+configured default (`settings.json`'s `defaultProvider`/`defaultModel`). So if
+you're authenticated with `pi` and have a default model picked, **no env is
+required**. The resolved model is handed to every new session and seeds the
+in-app **model selector** (via `@assistant-ui/ui`'s `ModelSelector`) and the
+readiness banner's credential check. The selector is wired to Pi's per-thread
+`setModel`, and the composer exposes Pi's thinking-level control. Set
+`PI_CODING_AGENT_DIR` to point at a non-default agent config dir (defaults to
+`~/.pi/agent`).
+
+## Run it
+
+1. Authenticate Pi once and pick a default model (writes `~/.pi/agent/`):
+
+   ```bash
+   pnpm dlx @earendil-works/pi-coding-agent
+   ```
+
+2. Start it (no env needed if Pi has a default model):
+
+   ```bash
+   pnpm dev
+   ```
+
+   To override the model or workspace, copy `.env.example` to `.env.local` and
+   set `PI_PROVIDER` / `PI_MODEL_ID` / `PI_WORKSPACE_PATH`.
+
+The agent reads and writes files and runs shell commands in `PI_WORKSPACE_PATH`.
+Point it at a scratch directory.
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "@/components/assistant-ui/*": [
+        "../../packages/ui/src/components/assistant-ui/*"
+      ],
+      "@/components/ui/*": ["../../packages/ui/src/components/ui/*"],
+      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
+      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+