devnonla-ui 0.1.0

package/src/button/ButtonCopy.tsx

@@ -0,0 +1,60 @@
+import { type ComponentProps, useEffect, useState } from "react";
+import { cn } from "../lib/cn";
+
+export type ButtonCopyProps = Omit<ComponentProps<"button">, "children"> & {
+  text?: string;
+  getText?: () => string;
+  /** Idle tooltip / aria-label. Copied state uses "Copied". */
+  label?: string;
+};
+
+function CopyIcon({ size = 14 }: { size?: number }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden>
+      <rect x="8" y="8" width="14" height="14" rx="2" stroke="currentColor" strokeWidth="2" />
+      <path d="M4 16V4c0-1.1.9-2 2-2h10" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+    </svg>
+  );
+}
+
+function CheckIcon({ size = 14 }: { size?: number }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden>
+      <path d="M5 13l4 4L19 7" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+export function ButtonCopy({ text, getText, label = "Copy", className, onClick, ...props }: ButtonCopyProps) {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (!copied) return;
+    const t = window.setTimeout(() => setCopied(false), 1600);
+    return () => window.clearTimeout(t);
+  }, [copied]);
+
+  return (
+    <button
+      type="button"
+      {...props}
+      title={copied ? "Copied" : label}
+      aria-label={copied ? "Copied" : label}
+      className={cn("inline-flex size-7 cursor-pointer shrink-0 items-center justify-center text-muted-foreground transition-colors duration-200 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className)}
+      onClick={async (e) => {
+        onClick?.(e);
+        if (e.defaultPrevented) return;
+        const value = getText?.() ?? text ?? "";
+        if (!value) return;
+        try {
+          await navigator.clipboard.writeText(value);
+          setCopied(true);
+        } catch {
+          /* ignore */
+        }
+      }}
+    >
+      {copied ? <CheckIcon /> : <CopyIcon />}
+    </button>
+  );
+}

package/src/calendar/Calendar.tsx

@@ -0,0 +1,133 @@
+import { type CSSProperties, useEffect, useRef } from "react";
+import { DayPicker, getDefaultClassNames, type DayButtonProps, type DayPickerProps } from "react-day-picker";
+import { cn } from "../lib/cn";
+
+export type CalendarProps = DayPickerProps;
+
+function Chevron({
+  className,
+  orientation,
+  size = 16,
+  ...props
+}: {
+  className?: string;
+  orientation?: "left" | "right" | "up" | "down";
+  size?: number;
+  disabled?: boolean;
+  style?: CSSProperties;
+}) {
+  const d =
+    orientation === "left"
+      ? "M15 18L9 12L15 6"
+      : orientation === "right"
+        ? "M9 18L15 12L9 6"
+        : orientation === "up"
+          ? "M6 15L12 9L18 15"
+          : "M6 9L12 15L18 9";
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden className={cn("opacity-70", className)} {...props}>
+      <path d={d} stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+function CalendarDayButton({ className, day, modifiers, children, ...props }: DayButtonProps) {
+  const defaultClassNames = getDefaultClassNames();
+  const ref = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (modifiers.focused) ref.current?.focus();
+  }, [modifiers.focused]);
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      {...props}
+      data-day={day.date.toLocaleDateString()}
+      data-today={modifiers.today ? "true" : undefined}
+      data-selected-single={modifiers.selected && !modifiers.range_start && !modifiers.range_end && !modifiers.range_middle ? "true" : undefined}
+      data-range-start={modifiers.range_start ? "true" : undefined}
+      data-range-end={modifiers.range_end ? "true" : undefined}
+      data-range-middle={modifiers.range_middle ? "true" : undefined}
+      className={cn(
+        "relative flex aspect-square size-full min-w-8 items-center justify-center rounded-md bg-transparent text-sm font-normal leading-none",
+        "transition-colors hover:bg-brand-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "data-[selected-single=true]:bg-brand-200 data-[selected-single=true]:text-foreground data-[selected-single=true]:hover:bg-brand-200",
+        "data-[range-start=true]:bg-brand-200 data-[range-start=true]:text-foreground data-[range-start=true]:hover:bg-brand-200 data-[range-start=true]:rounded-md",
+        "data-[range-end=true]:bg-brand-200 data-[range-end=true]:text-foreground data-[range-end=true]:hover:bg-brand-200 data-[range-end=true]:rounded-md",
+        "data-[range-middle=true]:bg-brand-50 data-[range-middle=true]:text-foreground data-[range-middle=true]:rounded-none",
+        defaultClassNames.day_button,
+        className,
+      )}
+    >
+      {children}
+      {modifiers.today ? <span aria-hidden className="absolute bottom-1 left-1/2 size-1 -translate-x-1/2 rounded-full bg-brand" /> : null}
+    </button>
+  );
+}
+
+export function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = "label",
+  components,
+  formatters,
+  ...props
+}: CalendarProps) {
+  const defaultClassNames = getDefaultClassNames();
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      captionLayout={captionLayout}
+      className={cn("group/calendar w-fit bg-transparent p-0 [--cell-size:2.25rem]", className)}
+      formatters={{
+        formatMonthDropdown: (date) => date.toLocaleString("default", { month: "short" }),
+        ...formatters,
+      }}
+      classNames={{
+        root: cn("w-fit", defaultClassNames.root),
+        months: cn("relative flex flex-col gap-4 sm:flex-row sm:gap-6", defaultClassNames.months),
+        month: cn("flex w-full flex-col gap-3", defaultClassNames.month),
+        nav: cn("absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1", defaultClassNames.nav),
+        button_previous: cn(
+          "inline-flex size-[var(--cell-size)] items-center justify-center rounded-md p-0 text-foreground select-none",
+          "hover:bg-brand-50 disabled:opacity-40",
+          defaultClassNames.button_previous,
+        ),
+        button_next: cn(
+          "inline-flex size-[var(--cell-size)] items-center justify-center rounded-md p-0 text-foreground select-none",
+          "hover:bg-brand-50 disabled:opacity-40",
+          defaultClassNames.button_next,
+        ),
+        month_caption: cn("flex h-[var(--cell-size)] w-full items-center justify-center px-[var(--cell-size)]", defaultClassNames.month_caption),
+        caption_label: cn("select-none text-sm font-medium text-foreground", defaultClassNames.caption_label),
+        dropdowns: cn("flex h-[var(--cell-size)] w-full items-center justify-center gap-1.5 text-sm font-medium", defaultClassNames.dropdowns),
+        month_grid: cn("w-full border-collapse", defaultClassNames.month_grid),
+        weekdays: cn("flex", defaultClassNames.weekdays),
+        weekday: cn("flex-1 select-none rounded-md text-[0.8rem] font-normal text-muted-foreground", defaultClassNames.weekday),
+        week: cn("mt-1.5 flex w-full", defaultClassNames.week),
+        day: cn(
+          "group/day relative aspect-square h-full w-full p-0 text-center select-none",
+          "[&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md",
+          defaultClassNames.day,
+        ),
+        today: cn(defaultClassNames.today),
+        outside: cn("text-muted-foreground/60 aria-selected:text-muted-foreground", defaultClassNames.outside),
+        disabled: cn("text-muted-foreground opacity-40", defaultClassNames.disabled),
+        hidden: cn("invisible", defaultClassNames.hidden),
+        range_start: cn("rounded-l-md bg-brand-50", defaultClassNames.range_start),
+        range_middle: cn("rounded-none bg-brand-50", defaultClassNames.range_middle),
+        range_end: cn("rounded-r-md bg-brand-50", defaultClassNames.range_end),
+        ...classNames,
+      }}
+      components={{
+        Chevron,
+        DayButton: CalendarDayButton,
+        ...components,
+      }}
+      {...props}
+    />
+  );
+}

package/src/chat/AgentPanel.tsx

@@ -0,0 +1,203 @@
+import { type ReactNode, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { cn } from "../lib/cn";
+import { OverlayScroll, type OverlayScrollVisibility } from "../scroll/OverlayScroll";
+import type { AgentMessage, AgentPanelEndpoint, AgentToolAction } from "./common/types";
+import { parseBgTaskRef } from "./common/bgTasks";
+import { useAgentStream } from "./common/useAgentStream";
+import { formatToolName } from "./common/utils";
+import { ChatAgentMessage } from "./message-ui/ChatAgentMessage";
+import { ChatError } from "./message-ui/ChatError";
+import { ChatInput } from "./message-ui/ChatInput";
+import { ChatMarkdown } from "./message-ui/ChatMarkdown";
+import { ChatThinking } from "./message-ui/ChatThinking";
+import { ChatUserMessage } from "./message-ui/ChatUserMessage";
+import { ChatWelcome } from "./message-ui/ChatWelcome";
+import { BackgroundTaskToolUI } from "./tool-ui/BackgroundTaskToolUI";
+import { ChatToolCall } from "./tool-ui/ChatToolCall";
+import { resolveToolUI } from "./tool-ui/registry";
+
+export type AgentPanelProps = {
+  /** POST URL, or a function that returns an SSE `Response`. */
+  endpoint: AgentPanelEndpoint;
+  title?: string;
+  /** Welcome name. Falls back to `title`. */
+  name?: string;
+  description?: string;
+  avatar?: ReactNode;
+  starters?: string[];
+  placeholder?: string;
+  /** Extra JSON merged into the POST body (string endpoint only). */
+  extraBody?: Record<string, unknown> | (() => Record<string, unknown>);
+  headers?: Record<string, string>;
+  fetcher?: typeof fetch;
+  initialMessages?: AgentMessage[];
+  toolbar?: ReactNode;
+  accessory?: ReactNode;
+  emptyState?: ReactNode;
+  /** Overlay scrollbar — does not reserve layout space. */
+  scrollbar?: OverlayScrollVisibility;
+  className?: string;
+  onToolAction?: (event: AgentToolAction) => void;
+  onGeneratingChange?: (generating: boolean) => void;
+};
+
+function activityStatus(messages: AgentMessage[]): string {
+  const last = messages[messages.length - 1];
+  if (!last) return "Thinking...";
+  if (last.role === "tool-call") {
+    if (last.toolOutput != null || last.toolError) return "Waiting for model...";
+    return `Running ${last.toolLabel ?? formatToolName(last.toolName ?? "tool")}...`;
+  }
+  if (last.role === "assistant" && last.streaming && last.content) return "Writing...";
+  return "Thinking...";
+}
+
+function useStickToBottom() {
+  const elRef = useRef<HTMLDivElement | null>(null);
+  const pinned = useRef(true);
+
+  const scrollRef = useCallback((node: HTMLDivElement | null) => {
+    elRef.current = node;
+  }, []);
+
+  const onScroll = () => {
+    const el = elRef.current;
+    if (!el) return;
+    pinned.current = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+  };
+
+  const scrollToBottom = useCallback((opts?: { force?: boolean }) => {
+    const el = elRef.current;
+    if (!el) return;
+    if (!opts?.force && !pinned.current) return;
+    pinned.current = true;
+    el.scrollTop = el.scrollHeight;
+  }, []);
+
+  return { scrollRef, onScroll, scrollToBottom };
+}
+
+function MessageRow({ msg, generating }: { msg: AgentMessage; generating: boolean }) {
+  if (msg.role === "user") return <ChatUserMessage content={msg.content} />;
+  if (msg.role === "error") return <ChatError>{msg.content}</ChatError>;
+  if (msg.role === "thinking") {
+    return <ChatThinking thinking={msg.content} duration={(msg.meta?.thinkingDuration as number) ?? 0} />;
+  }
+  if (msg.role === "tool-call") {
+    const CustomUI = resolveToolUI(msg.toolName);
+    if (CustomUI) {
+      return <CustomUI msg={msg} generating={generating} showAvatar={false} />;
+    }
+    if (parseBgTaskRef(msg.toolOutput)) {
+      return <BackgroundTaskToolUI msg={msg} generating={generating} showAvatar={false} />;
+    }
+    const pending = msg.toolOutput == null && !msg.toolError;
+    return (
+      <ChatToolCall
+        toolName={msg.toolName}
+        label={msg.toolLabel}
+        toolInput={msg.toolInput}
+        toolOutput={msg.toolOutput}
+        toolError={msg.toolError}
+        running={pending && generating}
+      />
+    );
+  }
+
+  const thinking = msg.meta?.thinking;
+  const thinkingDuration = msg.meta?.thinkingDuration;
+  return (
+    <ChatAgentMessage thinking={thinking} thinkingDuration={thinkingDuration ?? 0} thinkingStreaming={thinking != null && thinkingDuration == null}>
+      {msg.content ? <ChatMarkdown content={msg.content} streaming={!!msg.streaming} /> : null}
+    </ChatAgentMessage>
+  );
+}
+
+export function AgentPanel({
+  endpoint,
+  title = "Assistant",
+  name,
+  description,
+  avatar,
+  starters,
+  placeholder = "Message…",
+  extraBody,
+  headers,
+  fetcher,
+  initialMessages,
+  toolbar,
+  accessory,
+  emptyState,
+  scrollbar = "hover",
+  className,
+  onToolAction,
+  onGeneratingChange,
+}: AgentPanelProps) {
+  const { messages, generating, send, cancel, clear } = useAgentStream({
+    endpoint,
+    extraBody,
+    headers,
+    fetcher,
+    initialMessages,
+    onToolAction,
+  });
+  const { scrollRef, onScroll, scrollToBottom } = useStickToBottom();
+  const [epoch, setEpoch] = useState(0);
+  const welcomeName = name ?? title;
+  const lastMsg = messages[messages.length - 1];
+  const status = activityStatus(messages);
+  const lastToolPending = lastMsg?.role === "tool-call" && lastMsg.toolOutput == null && !lastMsg.toolError;
+  const hasActiveThinking = lastMsg?.role === "assistant" && Boolean(lastMsg.meta?.thinking) && lastMsg.meta?.thinkingDuration == null;
+  const isLiveText = status === "Writing..." || (lastMsg?.role === "assistant" && Boolean(lastMsg.streaming) && Boolean(lastMsg.content));
+  const showFooter = generating && !hasActiveThinking && !lastToolPending && !isLiveText;
+
+  useEffect(() => {
+    onGeneratingChange?.(generating);
+  }, [generating, onGeneratingChange]);
+
+  useLayoutEffect(() => {
+    scrollToBottom();
+  }, [messages, generating, showFooter, scrollToBottom]);
+
+  const sendMessage = (text: string) => {
+    scrollToBottom({ force: true });
+    void send(text);
+  };
+
+  const handleNewChat = () => {
+    clear();
+    setEpoch((n) => n + 1);
+  };
+
+  return (
+    <div className={cn("nonla-agent-panel relative flex h-full min-h-0 flex-col overflow-hidden bg-chat", className)}>
+      <OverlayScroll visibility={scrollbar} scrollRef={scrollRef} onScroll={onScroll} className="flex-1 min-h-0 min-w-0" innerClassName={messages.length === 0 ? "flex flex-col" : undefined}>
+        <div data-chat-scroll-content className={`max-w-190 mx-auto min-w-0 w-full ${messages.length === 0 ? "flex flex-1 flex-col pb-24" : "pt-4 pb-28"}`}>
+          {messages.length === 0 ? (
+            (emptyState ?? (
+              <ChatWelcome name={welcomeName} description={description} avatar={avatar} starters={starters} onStarter={sendMessage} disabled={generating} />
+            ))
+          ) : (
+            <div className="flex flex-col">
+              {messages.map((msg) => (
+                <MessageRow key={msg.id} msg={msg} generating={generating} />
+              ))}
+              {showFooter ? (
+                <div className="mt-1 px-4 pb-0.5">
+                  <span className="nonla-chat-shimmer text-(length:--chat-body-size) leading-5.5 font-medium">{status}</span>
+                </div>
+              ) : null}
+            </div>
+          )}
+        </div>
+      </OverlayScroll>
+
+      <div className="relative shrink-0">
+        {accessory}
+        <div className="mx-auto w-full max-w-190">
+          <ChatInput generating={generating} placeholder={placeholder} onSend={sendMessage} onCancel={cancel} onClear={handleNewChat} toolbar={toolbar} focusSignal={String(epoch)} enableTypeToFocus />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/chat/common/bgTasks.ts

@@ -0,0 +1,41 @@
+export type ChatBgTaskStatus = "running" | "completed" | "failed" | "cancelled" | "expired";
+
+export type ChatBgTask = {
+  taskId: string;
+  toolId?: string;
+  toolName: string;
+  conversationId?: string | null;
+  status: ChatBgTaskStatus;
+  startedAt: number;
+  finishedAt?: number;
+  error?: string;
+  console?: string;
+  result?: unknown;
+};
+
+export function parseBgTaskRef(output: unknown): { taskId: string; toolName?: string } | null {
+  if (output == null) return null;
+  let parsed: unknown = output;
+  if (typeof output === "string") {
+    try {
+      parsed = JSON.parse(output);
+    } catch {
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const rec = parsed as Record<string, unknown>;
+  if (rec.status !== "running" || typeof rec.taskId !== "string" || !rec.taskId) return null;
+  return { taskId: rec.taskId, toolName: typeof rec.toolName === "string" ? rec.toolName : undefined };
+}
+
+export function formatBgElapsed(startedAt: number, now: number, finishedAt?: number): string {
+  const end = finishedAt && finishedAt > startedAt ? finishedAt : now;
+  const sec = Math.max(0, Math.floor((end - startedAt) / 1000));
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  const rem = sec % 60;
+  if (min < 60) return rem ? `${min}m ${rem}s` : `${min}m`;
+  const hr = Math.floor(min / 60);
+  return `${hr}h ${min % 60}m`;
+}

package/src/chat/common/sse.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared SSE protocol for agent streams.
+ *
+ * Canonical event types:
+ *   text-delta | thinking-delta | tool-call | tool-result | done | error
+ *
+ * Legacy aliases (`chunk`, `thinking`) are normalized.
+ */
+
+export type AgentSseEvent =
+  | { type: "text-delta"; text: string }
+  | { type: "thinking-delta"; text: string }
+  | { type: "tool-call"; toolCallId?: string; toolName: string; toolLabel?: string; input: unknown }
+  | { type: "tool-result"; toolCallId?: string; toolName: string; result: unknown }
+  | { type: "done"; text?: string; reason?: string }
+  | { type: "error"; error: string };
+
+export interface AgentSseCallbacks {
+  onTextDelta: (text: string) => void;
+  onThinkingDelta: (text: string) => void;
+  onToolCall: (call: { toolCallId?: string; toolName: string; toolLabel?: string; input: unknown }) => void;
+  onToolResult: (call: { toolCallId?: string; toolName: string; result: unknown }) => void;
+  onDone: (text: string) => void | Promise<void>;
+  onError: (error: string) => void | Promise<void>;
+}
+
+export type ParseSseResult = "done" | "error" | "aborted" | "connection-lost";
+
+export function normalizeSseEvent(raw: Record<string, unknown>): AgentSseEvent | null {
+  const type = raw.type;
+  if (type === "ping") return null;
+  if (type === "text-delta" || type === "chunk") {
+    return { type: "text-delta", text: String(raw.text ?? "") };
+  }
+  if (type === "thinking-delta" || type === "thinking") {
+    return { type: "thinking-delta", text: String(raw.text ?? "") };
+  }
+  if (type === "tool-call") {
+    return {
+      type: "tool-call",
+      toolCallId: raw.toolCallId as string | undefined,
+      toolName: String(raw.toolName ?? "unknown"),
+      toolLabel: raw.toolLabel as string | undefined,
+      input: raw.input,
+    };
+  }
+  if (type === "tool-result") {
+    return {
+      type: "tool-result",
+      toolCallId: raw.toolCallId as string | undefined,
+      toolName: String(raw.toolName ?? "unknown"),
+      result: raw.result,
+    };
+  }
+  if (type === "context-usage" || type === "token-usage") return null;
+  if (type === "done") {
+    return { type: "done", text: raw.text as string | undefined, reason: raw.reason as string | undefined };
+  }
+  if (type === "error") {
+    return { type: "error", error: String(raw.error ?? "Unknown error") };
+  }
+  return null;
+}
+
+export async function parseSseStream(body: ReadableStream<Uint8Array>, callbacks: AgentSseCallbacks, options?: { signal?: AbortSignal }): Promise<ParseSseResult> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let gotTerminal = false;
+  let terminal: ParseSseResult = "connection-lost";
+
+  const handleLine = async (line: string): Promise<boolean> => {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("data:")) return false;
+    const jsonStr = trimmed.slice(5).trim();
+    if (!jsonStr) return false;
+
+    let raw: Record<string, unknown>;
+    try {
+      raw = JSON.parse(jsonStr) as Record<string, unknown>;
+    } catch {
+      return false;
+    }
+
+    const event = normalizeSseEvent(raw);
+    if (!event) return false;
+
+    switch (event.type) {
+      case "text-delta":
+        callbacks.onTextDelta(event.text);
+        return false;
+      case "thinking-delta":
+        callbacks.onThinkingDelta(event.text);
+        return false;
+      case "tool-call":
+        callbacks.onToolCall({
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          toolLabel: event.toolLabel,
+          input: event.input,
+        });
+        return false;
+      case "tool-result":
+        callbacks.onToolResult({
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          result: event.result,
+        });
+        return false;
+      case "done":
+        gotTerminal = true;
+        terminal = "done";
+        await Promise.resolve(callbacks.onDone(event.text ?? ""));
+        return true;
+      case "error":
+        gotTerminal = true;
+        terminal = "error";
+        await Promise.resolve(callbacks.onError(event.error));
+        return true;
+    }
+  };
+
+  try {
+    while (true) {
+      if (options?.signal?.aborted) return "aborted";
+
+      const { done, value } = await reader.read();
+      if (done) {
+        buffer += decoder.decode();
+        for (const line of buffer.split("\n")) {
+          if (await handleLine(line)) return terminal;
+        }
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (await handleLine(line)) return terminal;
+      }
+    }
+
+    if (!gotTerminal && !options?.signal?.aborted) {
+      await Promise.resolve(callbacks.onError("Connection lost"));
+      return "connection-lost";
+    }
+
+    return gotTerminal ? terminal : "aborted";
+  } catch (err) {
+    if ((err as Error).name === "AbortError" || options?.signal?.aborted) return "aborted";
+    await Promise.resolve(callbacks.onError((err as Error).message ?? "Stream read error"));
+    return "error";
+  }
+}

package/src/chat/common/types.ts

@@ -0,0 +1,43 @@
+export type AgentMessageRole = "user" | "assistant" | "thinking" | "tool-call" | "error";
+
+export type AgentMessage = {
+  id: string;
+  role: AgentMessageRole;
+  content: string;
+  streaming?: boolean;
+  timestamp: Date;
+  toolCallId?: string;
+  toolName?: string;
+  toolLabel?: string;
+  toolInput?: unknown;
+  toolOutput?: unknown;
+  toolError?: boolean | string;
+  meta?: {
+    thinking?: string;
+    thinkingDuration?: number;
+  };
+};
+
+export type AgentHistoryMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string }
+  | {
+      role: "tool-call";
+      content: "";
+      toolCallId?: string;
+      toolName?: string;
+      toolInput?: unknown;
+      toolOutput?: unknown;
+    };
+
+export type AgentStreamRequest = {
+  messages: AgentHistoryMessage[];
+  signal: AbortSignal;
+};
+
+/** POST URL, or a function that returns an SSE `Response`. */
+export type AgentPanelEndpoint = string | ((req: AgentStreamRequest) => Promise<Response>);
+
+export type AgentToolAction =
+  | { type: "tool-call"; toolName: string; toolLabel: string; input: unknown }
+  | { type: "tool-result"; toolName: string; output: unknown };