@tulip-systems/ai 0.11.0

package/src/chat/components/chat-thread.client.tsx

@@ -0,0 +1,242 @@
+"use client";
+
+import { Message, MessageContent } from "@tulip-systems/core/components";
+import {
+  MessageScroller,
+  MessageScrollerButton,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerProvider,
+  MessageScrollerViewport,
+} from "@tulip-systems/core/components/client";
+import { cn } from "@tulip-systems/core/lib";
+import type { ChatStatus, UIMessage } from "ai";
+import { type ComponentProps, createContext, useContext, useMemo } from "react";
+import type { ToolClientDefinition } from "../../tools/lib/types.client";
+import { AgentActivity } from "./agent-activity.client";
+import { ChatMessage, ChatMessageContent, ChatMessageParts } from "./chat-message.client";
+
+/**
+ * Chat Thread Context
+ */
+type ChatThreadContextValue = {
+  status: ChatStatus;
+  isAssistantResponding: boolean;
+  autoScroll: boolean;
+  defaultScrollPosition: "start" | "end" | "last-anchor";
+  scrollPreviousItemPeek: number;
+};
+
+const ChatThreadContext = createContext<ChatThreadContextValue>({} as ChatThreadContextValue);
+
+export type ChatThreadProps = ComponentProps<"div"> & {
+  status?: ChatStatus;
+  autoScroll?: boolean;
+  defaultScrollPosition?: "start" | "end" | "last-anchor";
+  scrollPreviousItemPeek?: number;
+};
+
+/**
+ * Provides shared thread state for all chat thread slots.
+ * Use it to configure chat status and scroll behavior once.
+ *
+ * @example
+ * ```tsx
+ * <ChatThread status={status}>
+ *   {messages.length === 0 && <EmptyState />}
+ *
+ *   {messages.length > 0 && (
+ *     <ChatThreadContent>
+ *       {messages.map((message) => (
+ *         <ChatThreadMessage key={message.id} message={message} />
+ *       ))}
+ *       <ChatThreadActivity />
+ *     </ChatThreadContent>
+ *   )}
+ * </ChatThread>
+ * ```
+ */
+export function ChatThread({
+  status = "ready",
+  autoScroll = true,
+  defaultScrollPosition = "end",
+  scrollPreviousItemPeek = 64,
+  className,
+  children,
+  ...props
+}: ChatThreadProps) {
+  const isAssistantResponding = status === "submitted" || status === "streaming";
+
+  const contextValue = useMemo(
+    () => ({
+      status,
+      isAssistantResponding,
+      autoScroll,
+      defaultScrollPosition,
+      scrollPreviousItemPeek,
+    }),
+    [status, isAssistantResponding, autoScroll, defaultScrollPosition, scrollPreviousItemPeek],
+  );
+
+  return (
+    <ChatThreadContext.Provider value={contextValue}>
+      <div
+        data-slot="chat-thread"
+        data-status={status}
+        data-responding={isAssistantResponding ? true : undefined}
+        className={cn("min-h-0 flex-1", className)}
+        {...props}
+      >
+        {children}
+      </div>
+    </ChatThreadContext.Provider>
+  );
+}
+
+/**
+ * Renders the scrollable message area for a chat thread.
+ * Place `ChatThreadMessage`, `ChatThreadActivity`, and optional sentinels inside it.
+ *
+ * @example
+ * ```tsx
+ * <ChatThreadContent className="px-3">
+ *   {messages.map((message) => (
+ *     <ChatThreadMessage key={message.id} message={message} />
+ *   ))}
+ *   <ChatThreadActivity />
+ * </ChatThreadContent>
+ * ```
+ */
+export function ChatThreadContent({
+  className,
+  children,
+  ...props
+}: ComponentProps<typeof MessageScrollerContent>) {
+  const { isAssistantResponding, autoScroll, defaultScrollPosition, scrollPreviousItemPeek } =
+    useContext(ChatThreadContext);
+
+  return (
+    <MessageScrollerProvider
+      autoScroll={autoScroll}
+      defaultScrollPosition={defaultScrollPosition}
+      scrollPreviousItemPeek={scrollPreviousItemPeek}
+    >
+      <MessageScroller className="min-h-0 flex-1">
+        <MessageScrollerViewport>
+          <MessageScrollerContent
+            aria-busy={isAssistantResponding}
+            className={cn("mx-auto w-full max-w-3xl gap-7 px-1 py-4 md:py-6", className)}
+            {...props}
+          >
+            {children}
+          </MessageScrollerContent>
+        </MessageScrollerViewport>
+
+        <ChatThreadScrollButton />
+      </MessageScroller>
+    </MessageScrollerProvider>
+  );
+}
+
+/**
+ * Renders one AI SDK message using the current `ChatThread` configuration.
+ * Use this inside `ChatThreadContent` when mapping over messages.
+ *
+ * @example
+ * ```tsx
+ * {messages.map((message) => (
+ *   <ChatThreadMessage key={message.id} message={message} toolRenderers={toolRenderers} />
+ * ))}
+ * ```
+ */
+export function ChatThreadMessage({
+  message,
+  messageId = message.id,
+  scrollAnchor = message.role === "user",
+  toolRenderers,
+  ...props
+}: Omit<ComponentProps<typeof MessageScrollerItem>, "children" | "messageId" | "scrollAnchor"> & {
+  message: UIMessage;
+  messageId?: string;
+  scrollAnchor?: boolean;
+  toolRenderers?: ToolClientDefinition[];
+}) {
+  return (
+    <MessageScrollerItem messageId={messageId} scrollAnchor={scrollAnchor} {...props}>
+      <ChatMessage message={message}>
+        <ChatMessageContent>
+          <ChatMessageParts toolRenderers={toolRenderers} />
+        </ChatMessageContent>
+      </ChatMessage>
+    </MessageScrollerItem>
+  );
+}
+
+/**
+ * Renders the assistant activity indicator while the thread status is `submitted` or `streaming`.
+ * It returns nothing when the assistant is not responding.
+ *
+ * @example
+ * ```tsx
+ * <ChatThreadActivity />
+ * ```
+ */
+export function ChatThreadActivity({
+  messageId = "agent-activity",
+  activityClassName,
+  ...props
+}: Omit<ComponentProps<typeof MessageScrollerItem>, "children" | "messageId"> & {
+  messageId?: string;
+  activityClassName?: string;
+}) {
+  const { isAssistantResponding } = useContext(ChatThreadContext);
+
+  if (!isAssistantResponding) return null;
+
+  return (
+    <MessageScrollerItem messageId={messageId} {...props}>
+      <Message align="start">
+        <MessageContent>
+          <AgentActivity className={activityClassName} />
+        </MessageContent>
+      </Message>
+    </MessageScrollerItem>
+  );
+}
+
+/**
+ * Renders a bottom sentinel item inside the thread scroller.
+ * Use it when callers need a stable ref at the end of the message list.
+ *
+ * @example
+ * ```tsx
+ * <ChatThreadBottom ref={bottomRef} />
+ * ```
+ */
+export function ChatThreadBottom({
+  messageId = "bottom-sentinel",
+  scrollAnchor = false,
+  ...props
+}: ComponentProps<"div"> & {
+  messageId?: string;
+  scrollAnchor?: boolean;
+}) {
+  return (
+    <MessageScrollerItem messageId={messageId} scrollAnchor={scrollAnchor}>
+      <div {...props} />
+    </MessageScrollerItem>
+  );
+}
+
+/**
+ * Renders the scroll-to-bottom button for `ChatThreadContent`.
+ * `ChatThreadContent` includes this button by default.
+ *
+ * @example
+ * ```tsx
+ * <ChatThreadScrollButton />
+ * ```
+ */
+export function ChatThreadScrollButton(props: ComponentProps<typeof MessageScrollerButton>) {
+  return <MessageScrollerButton {...props} />;
+}

package/src/chat/components/message-part.client.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { cn } from "@tulip-systems/core/lib";
+import type { ToolClientDefinition } from "../../tools/lib/types.client";
+import { isToolPart } from "../lib/parts";
+import type { ChatPart, ToolChatPart } from "../lib/types";
+import { ToolCallCard } from "./tool-call-card.client";
+
+export type ChatMessagePartProps = {
+  part: ChatPart;
+  isUser?: boolean;
+  toolRenderers?: ToolClientDefinition[];
+  className?: string;
+};
+
+/**
+ * Renders a visible AI SDK message part with a user bubble and plain assistant text.
+ */
+export function ChatMessagePart({
+  part,
+  isUser = false,
+  toolRenderers,
+  className,
+}: ChatMessagePartProps) {
+  if (part.type === "text") {
+    return (
+      <div
+        className={cn(
+          "max-w-[min(44rem,100%)]",
+          isUser ? "rounded-3xl bg-muted px-4 py-2.5 text-foreground" : "px-1 text-foreground",
+          className,
+        )}
+      >
+        <p className="whitespace-pre-wrap text-[15px] leading-7">{part.text}</p>
+      </div>
+    );
+  }
+
+  if (isToolPart(part)) {
+    const toolRenderer = getToolRenderer(part, toolRenderers);
+
+    return toolRenderer ? toolRenderer.render(part) : <ToolCallCard part={part} />;
+  }
+
+  return null;
+}
+
+/**
+ * Helpers
+ */
+function getToolName(part: ToolChatPart) {
+  return part.type.startsWith("tool-") ? part.type.slice(5) : part.type;
+}
+
+function getToolRenderer(part: ToolChatPart, toolRenderers?: ToolClientDefinition[]) {
+  const toolName = getToolName(part);
+
+  return toolRenderers?.find((renderer) => renderer.toolName === toolName);
+}

package/src/chat/components/starter-prompts.client.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { cn } from "@tulip-systems/core/lib";
+import type { ReactNode } from "react";
+
+export type StarterPromptsProps = {
+  prompts: string[];
+  onSelect: (prompt: string) => void;
+  disabled?: boolean;
+  label?: ReactNode;
+  icon?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Renders starter prompt buttons for a new chat state.
+ */
+export function StarterPrompts({
+  prompts,
+  onSelect,
+  disabled = false,
+  label,
+  icon,
+  className,
+}: StarterPromptsProps) {
+  const hasMeta = Boolean(label || icon);
+
+  return (
+    <div className={cn("grid w-full gap-2 sm:grid-cols-2", className)}>
+      {prompts.map((prompt) => (
+        <button
+          key={prompt}
+          type="button"
+          className="group rounded-2xl border border-border/60 bg-background/80 p-3 text-left shadow-sm backdrop-blur transition-colors hover:bg-muted/40 disabled:cursor-not-allowed disabled:opacity-60"
+          disabled={disabled}
+          onClick={() => onSelect(prompt)}
+        >
+          {hasMeta && (
+            <div className="mb-2 flex items-center gap-2 font-medium text-muted-foreground text-xs uppercase tracking-[0.14em]">
+              {icon}
+              {label}
+            </div>
+          )}
+          <p className="text-foreground/90 text-sm leading-6">{prompt}</p>
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/chat/components/tool-call-card.client.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { cn } from "@tulip-systems/core/lib";
+import type { ReactNode } from "react";
+import { getDefaultToolTitle, getToolName, stringifyChatValue } from "../lib/parts";
+import type { ToolChatPart } from "../lib/types";
+
+export type ToolCallCardLabels = {
+  input?: string;
+  output?: string;
+  preliminaryOutput?: string;
+};
+
+export type ToolCallCardProps = {
+  part: ToolChatPart;
+  title?: ReactNode | ((toolName: string, part: ToolChatPart) => ReactNode);
+  icon?: ReactNode | ((toolName: string, part: ToolChatPart) => ReactNode);
+  labels?: ToolCallCardLabels;
+  className?: string;
+};
+
+/**
+ * Renders a streamed AI SDK tool part with input, output, state, and error details.
+ */
+export function ToolCallCard({ part, title, icon, labels, className }: ToolCallCardProps) {
+  const toolName = getToolName(part);
+  const resolvedTitle = typeof title === "function" ? title(toolName, part) : title;
+  const resolvedIcon = typeof icon === "function" ? icon(toolName, part) : icon;
+  const inputLabel = labels?.input ?? "Input";
+  const outputLabel = part.preliminary
+    ? (labels?.preliminaryOutput ?? "Intermediate result")
+    : (labels?.output ?? "Result");
+
+  return (
+    <div
+      className={cn(
+        "max-w-full rounded-3xl border border-border/60 bg-muted/35 p-3.5 text-sm shadow-sm backdrop-blur-sm",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 font-medium text-[11px] text-muted-foreground uppercase tracking-[0.18em]">
+        {resolvedIcon}
+        <span>{resolvedTitle ?? getDefaultToolTitle(toolName)}</span>
+        {part.state && (
+          <span className="text-[10px] normal-case tracking-normal">{part.state}</span>
+        )}
+      </div>
+
+      {part.input !== undefined && (
+        <div className="mt-3 space-y-1.5">
+          <div className="font-medium text-[11px] text-muted-foreground uppercase tracking-[0.14em]">
+            {inputLabel}
+          </div>
+          <pre className="overflow-x-auto whitespace-pre-wrap rounded-2xl bg-background/80 p-3 text-foreground/90 text-xs leading-5">
+            {stringifyChatValue(part.input)}
+          </pre>
+        </div>
+      )}
+
+      {part.output !== undefined && (
+        <div className="mt-3 space-y-1.5">
+          <div className="font-medium text-[11px] text-muted-foreground uppercase tracking-[0.14em]">
+            {outputLabel}
+          </div>
+          <pre className="overflow-x-auto whitespace-pre-wrap rounded-2xl bg-background/80 p-3 text-foreground/90 text-xs leading-5">
+            {stringifyChatValue(part.output)}
+          </pre>
+        </div>
+      )}
+
+      {part.errorText && (
+        <div className="mt-3 rounded-xl border border-red-200 bg-red-50 p-3 text-red-700 text-xs">
+          {part.errorText}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/chat/entry.client.ts

@@ -0,0 +1,18 @@
+"use client";
+
+/**
+ * Components
+ */
+export * from "./components/agent-activity.client";
+export * from "./components/chat-composer.client";
+export * from "./components/chat-message.client";
+export * from "./components/chat-thread.client";
+export * from "./components/message-part.client";
+export * from "./components/starter-prompts.client";
+export * from "./components/tool-call-card.client";
+
+/**
+ * Lib
+ */
+export * from "./lib/parts";
+export * from "./lib/types";

package/src/chat/entry.server.ts

@@ -0,0 +1,5 @@
+/**
+ * Lib
+ */
+export * from "./lib/stream.server";
+export * from "./lib/types";

package/src/chat/entry.ts

@@ -0,0 +1,5 @@
+/**
+ * Lib
+ */
+export * from "./lib/parts";
+export * from "./lib/types";

package/src/chat/lib/parts.ts

@@ -0,0 +1,33 @@
+import type { ChatPart, ToolChatPart } from "./types";
+
+export function isToolPart(part: ChatPart): part is ToolChatPart {
+  return part.type.startsWith("tool-");
+}
+
+export function getToolName(part: ToolChatPart) {
+  return part.type.slice(5);
+}
+
+export function getDefaultToolTitle(toolName: string) {
+  return toolName.replaceAll("_", " ");
+}
+
+export function stringifyChatValue(value: unknown) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export function getChatPartKey(messageId: string, part: ChatPart) {
+  if (part.type === "text") {
+    return `${messageId}-text-${part.text.slice(0, 40)}`;
+  }
+
+  if (isToolPart(part)) {
+    return `${messageId}-${part.type}-${stringifyChatValue(part.input ?? part.output ?? part.type).slice(0, 60)}`;
+  }
+
+  return `${messageId}-${part.type}`;
+}

package/src/chat/lib/stream.server.ts

@@ -0,0 +1,40 @@
+import "server-cli-only";
+
+import { streamToEventIterator } from "@orpc/server";
+import { convertToModelMessages, toUIMessageStream } from "ai";
+import type { StreamAgentChatOptions } from "./types";
+
+/**
+ * Streams a Tulip agent response as an AI SDK UI message stream.
+ * Use this when the caller wants a framework-neutral `ReadableStream`.
+ */
+export async function streamAgentChat({
+  agent,
+  messages,
+  abortSignal,
+  convertToModelMessagesOptions,
+  uiMessageStreamOptions,
+}: StreamAgentChatOptions) {
+  const modelMessages = await convertToModelMessages(messages, {
+    ignoreIncompleteToolCalls: true,
+    ...convertToModelMessagesOptions,
+  });
+  const result = await agent.stream({
+    messages: modelMessages,
+    abortSignal,
+  });
+
+  return toUIMessageStream({
+    ...uiMessageStreamOptions,
+    stream: result.stream,
+    tools: agent.tools,
+  });
+}
+
+/**
+ * Streams a Tulip agent response as an oRPC event iterator.
+ * Use this from oRPC procedures that return an AI SDK UI message stream to clients.
+ */
+export async function streamAgentChatEventIterator(options: StreamAgentChatOptions) {
+  return streamToEventIterator(await streamAgentChat(options));
+}

package/src/chat/lib/types.ts

@@ -0,0 +1,20 @@
+import type { convertToModelMessages, toUIMessageStream, UIMessage } from "ai";
+import type { CreatedAgent } from "../../agents/lib/types";
+
+export type ChatPart = UIMessage["parts"][number];
+
+export type ToolChatPart = ChatPart & {
+  input?: unknown;
+  output?: unknown;
+  state?: string;
+  preliminary?: boolean;
+  errorText?: string;
+};
+
+export type StreamAgentChatOptions = {
+  agent: CreatedAgent;
+  messages: UIMessage[];
+  abortSignal?: AbortSignal;
+  convertToModelMessagesOptions?: Parameters<typeof convertToModelMessages>[1];
+  uiMessageStreamOptions?: Omit<Parameters<typeof toUIMessageStream>[0], "stream" | "tools">;
+};

package/src/entry.ts

@@ -0,0 +1,24 @@
+/**
+ * Entrypoints for Vite
+ */
+export const entry = {
+  /**
+   * Agents
+   */
+  "agents/server": "./src/agents/entry.server.ts",
+  /**
+   * Chat
+   */
+  chat: "./src/chat/entry.ts",
+  "chat/client": "./src/chat/entry.client.ts",
+  "chat/server": "./src/chat/entry.server.ts",
+  /**
+   * MCP
+   */
+  "mcp/server": "./src/mcp/entry.server.ts",
+  /**
+   * Tools
+   */
+  "tools/client": "./src/tools/entry.client.ts",
+  "tools/server": "./src/tools/entry.server.ts",
+};

package/src/mcp/entry.server.ts

@@ -0,0 +1,2 @@
+export * from "./lib/content";
+export * from "./lib/types";