@signalflare-ai/ui 0.5.0

package/dist/src/blocks/agent-harness/agent-harness.tsx

@@ -0,0 +1,1122 @@
+"use client";
+
+import {
+  BrainIcon,
+  EyeIcon,
+  RobotIcon,
+  SparkleIcon,
+  SpinnerGapIcon,
+  StopCircleIcon,
+} from "@phosphor-icons/react";
+import type { ComponentProps, ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  type AgentHarnessState,
+  type AgentMessage,
+  type AgentNotice,
+  type AgentOMActivity,
+  type AgentQuestion,
+  type AgentPlanApproval,
+  type AgentSubagent,
+  type AgentTaskList,
+  type AgentThinking,
+  type AgentToolCall,
+  type AgentUsage,
+  type HarnessAdapter,
+  type HarnessEvent,
+  type UseAgentHarnessReturn,
+  createAgentHarnessState,
+  fromMastraHarness,
+  useAgentHarness,
+} from "../../components/use-agent-harness";
+import {
+  AiApproval,
+  AiConversation,
+  AiConversationScrollButton,
+  AiInfoBanner,
+  AiMessage,
+  AiMessageAction,
+  AiMessageActions,
+  AiMessageContent,
+  AiMessageToolbar,
+  AiQuestion,
+  AiReasoning,
+  AiResponse,
+  AiSubagent,
+  AiTaskList,
+  AiToolCallGroup,
+  AiUsageBar,
+  Button,
+  PromptInput,
+  PromptInputAttachButton,
+  PromptInputBackLayer,
+  PromptInputModeSelector,
+  PromptInputSpeechButton,
+  PromptInputSubmit,
+  PromptInputTextarea,
+  PromptInputToolbar,
+  PromptInputTools,
+  cn,
+  useConversationVirtualizer,
+  type ConversationItem,
+} from "../../index";
+
+// ─── Block imports patched at install time to @signalflare-ai/ui ─────────────
+// (fromMastraHarness + useAgentHarness are in the library, so they get
+//  rewritten by the CLI transformer alongside the UI imports above)
+
+// ─── Variants ─────────────────────────────────────────────────────────────────
+
+export const SF_AGENT_HARNESS_VARIANTS = {
+  hitlPlacement: {
+    inline: {
+      description:
+        "Render approval/question cards inline in the conversation stream",
+    },
+    "back-layer": {
+      description:
+        "Render approval/question cards in the PromptInput back layer",
+    },
+    both: {
+      description:
+        "Render approval/question cards both inline and in the back layer",
+    },
+  },
+} as const;
+
+export const SF_AGENT_HARNESS_DEFAULT_VARIANTS = {
+  hitlPlacement: "inline",
+} as const;
+
+export type SFAgentHarnessHitlPlacement =
+  keyof typeof SF_AGENT_HARNESS_VARIANTS.hitlPlacement;
+
+// ─── Props ────────────────────────────────────────────────────────────────────
+
+export interface AgentHarnessProps extends ComponentProps<"div"> {
+  // ── Uncontrolled mode — hook manages state ─────────────────────────────────
+  /**
+   * A HarnessAdapter to subscribe to, OR a raw Mastra Harness instance.
+   * Pass `null` to render in "static/demo" mode with no live events.
+   * Ignored when `state` is provided.
+   */
+  adapter?: HarnessAdapter | null;
+
+  // ── Controlled mode — consumer manages state ───────────────────────────────
+  /**
+   * Provide your own `AgentHarnessState` to fully control rendering.
+   * When set, `adapter` is ignored and all action callbacks must be provided.
+   *
+   * Build state from any source — Durable Streams, Zustand, Redux, a Mastra
+   * harness mapped through your own reducer, etc. Use `createAgentHarnessState()`
+   * to create the initial empty state.
+   *
+   * @example
+   * ```tsx
+   * const state = useMastraToAgentState(harness);
+   * <AgentHarness
+   *   state={state}
+   *   onSendMessage={({ content }) => harness.send(content)}
+   *   onApproveToolCall={(d) => harness.approve(d)}
+   * />
+   * ```
+   */
+  state?: AgentHarnessState;
+  /**
+   * Send a user message. Required in controlled mode.
+   */
+  onSendMessage?: (params: {
+    content: string;
+    files?: Array<{ url: string; mediaType: string; filename: string }>;
+  }) => void | Promise<void>;
+  /**
+   * Respond to a pending tool approval. Required in controlled mode when tool approvals are used.
+   */
+  onApproveToolCall?: (decision: "approve" | "decline") => void | Promise<void>;
+  /**
+   * Answer a pending question. Required in controlled mode when questions are used.
+   */
+  onAnswerQuestion?: (
+    questionId: string,
+    answer: string
+  ) => void | Promise<void>;
+  /**
+   * Respond to a pending plan approval. Required in controlled mode when plan approvals are used.
+   */
+  onApprovePlan?: (
+    planId: string,
+    response: { action: "approved" | "rejected"; feedback?: string }
+  ) => void | Promise<void>;
+  /**
+   * Abort any in-progress generation. Required in controlled mode.
+   */
+  onAbort?: () => void;
+
+  // ── Shared props (work in both modes) ─────────────────────────────────────
+  /**
+   * Placement for interactive HITL elements (approvals, questions, plans).
+   * @default "inline"
+   */
+  hitlPlacement?: SFAgentHarnessHitlPlacement;
+  /**
+   * Show the mode badge in the header (mode name + color dot).
+   * @default true
+   */
+  showMode?: boolean;
+  /**
+   * Show the model badge in the header.
+   * @default true
+   */
+  showModel?: boolean;
+  /**
+   * Show token usage bar above the prompt input.
+   * @default true
+   */
+  showUsage?: boolean;
+  /**
+   * Show the task list in the back layer when tasks are present.
+   * @default true
+   */
+  showTaskList?: boolean;
+  /**
+   * Placeholder text for the prompt input.
+   * @default "Ask anything..."
+   */
+  placeholder?: string;
+  /**
+   * Header slot — rendered at the top of the block (e.g., mode picker, model
+   * dropdown, thread list trigger). When omitted, a minimal default header is
+   * rendered showing the current mode + model.
+   */
+  header?: ReactNode;
+  /**
+   * Footer slot — rendered below the prompt input (e.g., disclaimer text).
+   */
+  footer?: ReactNode;
+  /**
+   * Empty state — rendered when there are no messages.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Override the submit button. Receives the current harness state.
+   */
+  renderSubmit?: (state: AgentHarnessState) => ReactNode;
+  /**
+   * Suggestions to show when the conversation is empty.
+   */
+  suggestions?: string[];
+  /**
+   * Callback when a suggestion is clicked — defaults to sending the suggestion
+   * as a message.
+   */
+  onSuggestionClick?: (suggestion: string) => void;
+  /**
+   * Allow file attachments in the prompt input.
+   * @default false
+   */
+  allowAttachments?: boolean;
+  /**
+   * Allow speech input in the prompt input.
+   * @default false
+   */
+  allowSpeech?: boolean;
+  /**
+   * Available modes for the mode selector in the toolbar.
+   * When provided, a mode selector will be shown in the prompt input toolbar.
+   */
+  availableModes?: { modeId: string; modeName: string }[];
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function getModelDisplayName(modelId?: string, modelName?: string): string {
+  if (modelName) return modelName;
+  if (!modelId) return "";
+  return modelId.split("/").pop() ?? modelId;
+}
+
+/** Render a single OM activity as an AiReasoning with the right icon/label. */
+function OmActivityView({ activity }: { activity: AgentOMActivity }) {
+  const isObservation = activity.type === "observation";
+  return (
+    <AiReasoning
+      part={{ text: activity.text ?? "" }}
+      isStreaming={activity.status === "streaming"}
+      icon={isObservation ? EyeIcon : BrainIcon}
+      label={isObservation ? "Observed" : "Reflected"}
+      streamingLabel={isObservation ? "Observing..." : "Reflecting..."}
+      variant="default"
+    />
+  );
+}
+
+/** Render all tool calls for a message / subagent as a group. */
+function ToolCallsView({
+  toolCallIds,
+  toolCalls,
+  pendingApprovalId,
+  onApprove,
+  onReject,
+}: {
+  toolCallIds: string[];
+  toolCalls: Record<string, AgentToolCall>;
+  pendingApprovalId?: string;
+  onApprove?: () => void;
+  onReject?: () => void;
+}) {
+  const parts = toolCallIds
+    .map((id) => toolCalls[id])
+    .filter(Boolean)
+    .map((tc) => ({
+      toolCallId: tc.id,
+      toolName: tc.toolName,
+      state: tc.state,
+      input: tc.input,
+      output: tc.output,
+      errorText: tc.errorText,
+    }));
+
+  if (parts.length === 0) return null;
+
+  const approvalStates: Record<
+    string,
+    "awaiting" | "approved" | "declined" | undefined
+  > = {};
+  for (const tc of Object.values(toolCalls)) {
+    if (toolCallIds.includes(tc.id)) {
+      approvalStates[tc.id] = tc.approvalState;
+    }
+  }
+
+  const durations: Record<string, number> = {};
+  const summaries: Record<string, string> = {};
+  for (const tc of Object.values(toolCalls)) {
+    if (toolCallIds.includes(tc.id)) {
+      if (tc.durationMs !== undefined) durations[tc.id] = tc.durationMs;
+      if (tc.summary) summaries[tc.id] = tc.summary;
+    }
+  }
+
+  return (
+    <AiToolCallGroup
+      parts={parts}
+      approvalStates={approvalStates}
+      durations={Object.keys(durations).length > 0 ? durations : undefined}
+      summaries={Object.keys(summaries).length > 0 ? summaries : undefined}
+      onApprove={pendingApprovalId ? () => onApprove?.() : undefined}
+      onReject={pendingApprovalId ? () => onReject?.() : undefined}
+    />
+  );
+}
+
+/** Render a single subagent with its nested content. */
+function SubagentView({
+  subagent,
+  toolCalls,
+  pendingApprovalId,
+  onApprove,
+  onReject,
+}: {
+  subagent: AgentSubagent;
+  toolCalls: Record<string, AgentToolCall>;
+  pendingApprovalId?: string;
+  onApprove?: () => void;
+  onReject?: () => void;
+}) {
+  return (
+    <AiSubagent
+      agentType={subagent.agentType}
+      name={subagent.name}
+      status={subagent.status}
+      modelId={subagent.modelId}
+      duration={subagent.durationMs}
+      defaultExpanded={subagent.status === "running"}
+    >
+      <div className="flex flex-col gap-2">
+        {subagent.content && (
+          <AiResponse isAnimating={subagent.status === "running"}>
+            {subagent.content}
+          </AiResponse>
+        )}
+        <ToolCallsView
+          toolCallIds={subagent.toolCallIds}
+          toolCalls={toolCalls}
+          pendingApprovalId={pendingApprovalId}
+          onApprove={onApprove}
+          onReject={onReject}
+        />
+      </div>
+    </AiSubagent>
+  );
+}
+
+/** Render a question inline. */
+function QuestionView({
+  question,
+  onAnswer,
+}: {
+  question: AgentQuestion;
+  onAnswer: (questionId: string, answer: string) => void;
+}) {
+  return (
+    <AiQuestion
+      questionId={question.questionId}
+      question={question.question}
+      header={question.header}
+      options={question.options}
+      multiple={question.multiple}
+      allowCustom={question.allowCustom ?? true}
+      status={question.status}
+      answeredWith={question.answeredWith}
+      onAnswer={onAnswer}
+    />
+  );
+}
+
+/** Render a plan approval inline. */
+function PlanApprovalView({
+  plan,
+  onApprove,
+  onReject,
+}: {
+  plan: AgentPlanApproval;
+  onApprove: () => void;
+  onReject: (feedback?: string) => void;
+}) {
+  return (
+    <AiApproval
+      kind="plan"
+      title={plan.title}
+      description={plan.description}
+      items={plan.steps?.map((s) => ({
+        id: s.id,
+        label: s.label,
+        description: s.description,
+      }))}
+      status={plan.status}
+      onApprove={onApprove}
+      onReject={onReject}
+      showFeedback={plan.status === "pending"}
+    />
+  );
+}
+
+/** Render an assistant message body: reasoning, response, tool calls, subagents, HITL. */
+function AssistantMessageBody({
+  message,
+  harnessState,
+  hitlPlacement,
+  onApprove,
+  onReject,
+  onAnswer,
+  onPlanApprove,
+  onPlanReject,
+}: {
+  message: AgentMessage;
+  harnessState: AgentHarnessState;
+  hitlPlacement: SFAgentHarnessHitlPlacement;
+  onApprove: () => void;
+  onReject: () => void;
+  onAnswer: (questionId: string, answer: string) => void;
+  onPlanApprove: (planId: string) => void;
+  onPlanReject: (planId: string, feedback?: string) => void;
+}) {
+  // OM activities attached to this message
+  const omActivities = Object.values(harnessState.omActivities).filter(
+    (a) => a.messageId === message.id
+  );
+
+  // Thinking blocks attached to this message (in order)
+  const thinkingBlocks = message.thinkingIds
+    .map((id) => harnessState.thinkings[id])
+    .filter((t): t is AgentThinking => t != null);
+
+  // Subagents attached to this message
+  const subagents = message.subagentIds
+    .map((id) => harnessState.subagents[id])
+    .filter(Boolean);
+
+  // Pending question for this message
+  const question = message.questionId
+    ? harnessState.questions[message.questionId]
+    : harnessState.pendingQuestionId
+      ? harnessState.questions[harnessState.pendingQuestionId]
+      : undefined;
+
+  // Pending plan for this message
+  const plan =
+    harnessState.pendingPlanId &&
+    (message.planId === harnessState.pendingPlanId || !message.planId)
+      ? harnessState.planApprovals[harnessState.pendingPlanId]
+      : undefined;
+
+  const showInlineHitl = hitlPlacement === "inline" || hitlPlacement === "both";
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Thinking / reasoning blocks */}
+      {thinkingBlocks.map((t) => (
+        <AiReasoning
+          key={t.id}
+          part={{ text: t.text }}
+          isStreaming={t.isStreaming}
+          icon={SparkleIcon}
+          label="Reasoning"
+          streamingLabel="Thinking..."
+          variant="default"
+        />
+      ))}
+
+      {/* OM activities (observations / reflections) */}
+      {omActivities.map((a) => (
+        <OmActivityView key={a.id} activity={a} />
+      ))}
+
+      {/* Response text */}
+      {message.content && (
+        <AiResponse isAnimating={message.isStreaming}>
+          {message.content}
+        </AiResponse>
+      )}
+
+      {/* Tool calls (top-level, no subagent) */}
+      {message.toolCallIds.length > 0 && (
+        <ToolCallsView
+          toolCallIds={message.toolCallIds}
+          toolCalls={harnessState.toolCalls}
+          pendingApprovalId={harnessState.pendingToolApprovalId}
+          onApprove={onApprove}
+          onReject={onReject}
+        />
+      )}
+
+      {/* Subagents */}
+      {subagents.map((sa) => (
+        <SubagentView
+          key={sa.id}
+          subagent={sa}
+          toolCalls={harnessState.toolCalls}
+          pendingApprovalId={harnessState.pendingToolApprovalId}
+          onApprove={onApprove}
+          onReject={onReject}
+        />
+      ))}
+
+      {/* HITL — Question */}
+      {showInlineHitl && question && (
+        <QuestionView question={question} onAnswer={onAnswer} />
+      )}
+
+      {/* HITL — Plan approval */}
+      {showInlineHitl && plan && (
+        <PlanApprovalView
+          plan={plan}
+          onApprove={() => onPlanApprove(plan.planId)}
+          onReject={(feedback) => onPlanReject(plan.planId, feedback)}
+        />
+      )}
+    </div>
+  );
+}
+
+/** Back-layer content: tasks + optional HITL when hitlPlacement includes back-layer. */
+function BackLayerContent({
+  taskList,
+  usage,
+  showUsage,
+  pendingQuestion,
+  pendingPlan,
+  hitlPlacement,
+  onAnswer,
+  onPlanApprove,
+  onPlanReject,
+}: {
+  taskList: AgentTaskList | null;
+  usage: AgentUsage | null;
+  showUsage: boolean;
+  pendingQuestion?: AgentQuestion;
+  pendingPlan?: AgentPlanApproval;
+  hitlPlacement: SFAgentHarnessHitlPlacement;
+  onAnswer: (questionId: string, answer: string) => void;
+  onPlanApprove: (planId: string) => void;
+  onPlanReject: (planId: string, feedback?: string) => void;
+}) {
+  const showBackLayerHitl =
+    hitlPlacement === "back-layer" || hitlPlacement === "both";
+
+  const hasContent =
+    taskList ||
+    (showUsage && usage) ||
+    (showBackLayerHitl && (pendingQuestion || pendingPlan));
+
+  if (!hasContent) return null;
+
+  return (
+    <PromptInputBackLayer>
+      <div className="flex flex-col gap-3">
+        {showUsage && usage && <AiUsageBar {...usage} />}
+
+        {taskList && (
+          <AiTaskList tasks={taskList.tasks} title={taskList.title} />
+        )}
+
+        {showBackLayerHitl && pendingQuestion && (
+          <QuestionView question={pendingQuestion} onAnswer={onAnswer} />
+        )}
+
+        {showBackLayerHitl && pendingPlan && (
+          <PlanApprovalView
+            plan={pendingPlan}
+            onApprove={() => onPlanApprove(pendingPlan.planId)}
+            onReject={(feedback) => onPlanReject(pendingPlan.planId, feedback)}
+          />
+        )}
+      </div>
+    </PromptInputBackLayer>
+  );
+}
+
+/** Default header — mode + model badges. */
+function DefaultHeader({
+  isRunning,
+  onAbort,
+}: {
+  isRunning: boolean;
+  onAbort: () => void;
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 border-b border-sf-line px-4 py-2.5">
+      <div className="flex items-center gap-2">
+        <RobotIcon size={16} className="text-sf-subtle" />
+        <span className="text-sm font-medium text-sf-default">Agent</span>
+      </div>
+      {isRunning && (
+        <Button
+          variant="ghost"
+          size="sm"
+          shape="square"
+          aria-label="Abort generation"
+          onClick={onAbort}
+        >
+          <StopCircleIcon size={16} />
+        </Button>
+      )}
+    </div>
+  );
+}
+
+// ─── Main Component ───────────────────────────────────────────────────────────
+
+/**
+ * `AgentHarness` — a full-chrome agent chat UI block.
+ *
+ * Composes all SignalFlare AI components into a complete, event-driven chat
+ * experience driven by a `HarnessAdapter` (or Mastra Harness instance).
+ *
+ * **State is decoupled** — use `useAgentHarness` directly when you need a
+ * custom layout or headless control.
+ *
+ * @example
+ * ```tsx
+ * import { AgentHarness, fromMastraHarness } from "./components/sf/agent-harness/agent-harness";
+ *
+ * export function App() {
+ *   const adapter = fromMastraHarness(harness);
+ *   return <AgentHarness adapter={adapter} />;
+ * }
+ * ```
+ */
+export function AgentHarness({
+  adapter = null,
+  state: controlledState,
+  onSendMessage,
+  onApproveToolCall,
+  onAnswerQuestion,
+  onApprovePlan,
+  onAbort,
+  hitlPlacement = SF_AGENT_HARNESS_DEFAULT_VARIANTS.hitlPlacement,
+  showMode = true,
+  showModel = true,
+  showUsage = true,
+  showTaskList = true,
+  placeholder = "Ask anything...",
+  header,
+  footer,
+  emptyState,
+  renderSubmit,
+  suggestions,
+  onSuggestionClick,
+  allowAttachments = false,
+  allowSpeech = false,
+  availableModes,
+  className,
+  ...props
+}: AgentHarnessProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [isBackLayerOpen, setIsBackLayerOpen] = useState(false);
+
+  // Uncontrolled: adapter drives the hook. Controlled: hook is disabled (null adapter).
+  const harness = useAgentHarness({
+    adapter: controlledState ? null : adapter,
+  });
+
+  // Dev-only warning: in controlled mode, required callbacks should be provided
+  if (process.env.NODE_ENV !== "production" && controlledState) {
+    if (!onSendMessage) {
+      console.warn(
+        "[AgentHarness] Controlled mode: `onSendMessage` is not provided — user messages will be silently dropped."
+      );
+    }
+  }
+
+  // Resolve state — controlled takes priority over hook state
+  const state = controlledState ?? harness.state;
+
+  // Resolve action callbacks — controlled props take priority over hook methods
+  const sendMessage = onSendMessage ?? harness.sendMessage;
+  const respondToToolApproval =
+    onApproveToolCall != null
+      ? (decision: "approve" | "decline") => onApproveToolCall(decision)
+      : harness.respondToToolApproval;
+  const respondToQuestion =
+    onAnswerQuestion != null
+      ? (questionId: string, answer: string) =>
+          onAnswerQuestion(questionId, answer)
+      : harness.respondToQuestion;
+  const respondToPlanApproval =
+    onApprovePlan != null
+      ? (
+          planId: string,
+          response: { action: "approved" | "rejected"; feedback?: string }
+        ) => onApprovePlan(planId, response)
+      : harness.respondToPlanApproval;
+  const abort = onAbort ?? harness.abort;
+  const selectMode = harness.selectMode;
+
+  // ── Callbacks ──────────────────────────────────────────────────────────────
+  const handleSubmit = useCallback(
+    async ({
+      text,
+      files,
+    }: {
+      text?: string;
+      files?: Array<{ url: string; mediaType: string; filename: string }>;
+    }) => {
+      if (!text?.trim() && !files?.length) return;
+      await sendMessage({ content: text ?? "", files });
+    },
+    [sendMessage]
+  );
+
+  const handleApprove = useCallback(async () => {
+    await respondToToolApproval("approve");
+  }, [respondToToolApproval]);
+
+  const handleReject = useCallback(async () => {
+    await respondToToolApproval("decline");
+  }, [respondToToolApproval]);
+
+  const handleAnswer = useCallback(
+    async (questionId: string, answer: string) => {
+      await respondToQuestion(questionId, answer);
+    },
+    [respondToQuestion]
+  );
+
+  const handlePlanApprove = useCallback(
+    async (planId: string) => {
+      await respondToPlanApproval(planId, { action: "approved" });
+    },
+    [respondToPlanApproval]
+  );
+
+  const handlePlanReject = useCallback(
+    async (planId: string, feedback?: string) => {
+      await respondToPlanApproval(planId, { action: "rejected", feedback });
+    },
+    [respondToPlanApproval]
+  );
+
+  const handleSuggestion = useCallback(
+    async (suggestion: string) => {
+      if (onSuggestionClick) {
+        onSuggestionClick(suggestion);
+      } else {
+        await sendMessage({ content: suggestion });
+      }
+    },
+    [onSuggestionClick, sendMessage]
+  );
+
+  // ── Derived ────────────────────────────────────────────────────────────────
+  const pendingQuestion = state.pendingQuestionId
+    ? state.questions[state.pendingQuestionId]
+    : undefined;
+
+  const pendingPlan = state.pendingPlanId
+    ? state.planApprovals[state.pendingPlanId]
+    : undefined;
+
+  // Auto-open back layer when pending items appear
+  useEffect(() => {
+    if (pendingQuestion || pendingPlan) {
+      setIsBackLayerOpen(true);
+    }
+  }, [pendingQuestion, pendingPlan]);
+
+  const hasBackLayerContent =
+    (showTaskList && !!state.taskList) ||
+    (showUsage && !!state.usage) ||
+    ((hitlPlacement === "back-layer" || hitlPlacement === "both") &&
+      (!!pendingQuestion || !!pendingPlan));
+
+  const promptStatus = state.isRunning ? "streaming" : "idle";
+
+  const isEmpty = state.messageIds.length === 0;
+
+  // ── Build flat item list for virtualizer ───────────────────────────────────
+  const conversationItems: ConversationItem[] = useMemo(() => {
+    const items: ConversationItem[] = [];
+
+    // Empty state
+    if (isEmpty) {
+      if (emptyState) {
+        items.push({
+          key: "__empty__",
+          render: () => (
+            <div className="flex flex-col items-center justify-center py-16 text-center">
+              {emptyState}
+            </div>
+          ),
+        });
+      } else if (suggestions && suggestions.length > 0) {
+        items.push({
+          key: "__suggestions__",
+          render: () => (
+            <div className="flex flex-col items-center gap-4 py-16">
+              <div className="flex flex-col items-center gap-1">
+                <RobotIcon size={32} className="text-sf-subtle" />
+                <p className="text-sm text-sf-subtle">
+                  How can I help you today?
+                </p>
+              </div>
+              <div className="flex flex-wrap justify-center gap-2">
+                {suggestions.map((s) => (
+                  <button
+                    key={s}
+                    type="button"
+                    onClick={() => handleSuggestion(s)}
+                    className="rounded-full border border-sf-line bg-sf-elevated px-3 py-1.5 text-sm text-sf-strong transition-colors hover:bg-sf-tint hover:text-sf-default"
+                  >
+                    {s}
+                  </button>
+                ))}
+              </div>
+            </div>
+          ),
+        });
+      }
+
+      // Spinner when waiting for first message
+      if (state.isRunning) {
+        items.push({
+          key: "__spinner__",
+          render: () => (
+            <div className="flex items-center gap-2 px-4 py-3 text-sm text-sf-subtle">
+              <SpinnerGapIcon
+                size={14}
+                className="animate-spin text-sf-brand"
+              />
+              <span>Thinking…</span>
+            </div>
+          ),
+        });
+      }
+
+      return items;
+    }
+
+    // Messages + interspersed notices
+    for (const msgId of state.messageIds) {
+      const msg = state.messages[msgId];
+      if (!msg) continue;
+
+      // Notices attached to this message (render before the message)
+      const attachedNotices = state.notices.filter(
+        (n) => n.messageId === msgId
+      );
+      for (const notice of attachedNotices) {
+        items.push({
+          key: `notice-${notice.id}`,
+          render: () => (
+            <div className="py-0.5">
+              <AiInfoBanner level={notice.level}>{notice.message}</AiInfoBanner>
+            </div>
+          ),
+        });
+      }
+
+      if (msg.role === "user") {
+        items.push({
+          key: msgId,
+          render: () => (
+            <div>
+              <AiMessage from="user">
+                <AiMessageContent>
+                  <AiResponse>{msg.content}</AiResponse>
+                </AiMessageContent>
+              </AiMessage>
+            </div>
+          ),
+        });
+      } else {
+        items.push({
+          key: msgId,
+          render: () => (
+            <div>
+              <AiMessage from="assistant">
+                <AiMessageContent>
+                  <AssistantMessageBody
+                    message={msg}
+                    harnessState={state}
+                    hitlPlacement={hitlPlacement}
+                    onApprove={handleApprove}
+                    onReject={handleReject}
+                    onAnswer={handleAnswer}
+                    onPlanApprove={handlePlanApprove}
+                    onPlanReject={handlePlanReject}
+                  />
+                </AiMessageContent>
+                {!msg.isStreaming && msg.content && (
+                  <AiMessageToolbar>
+                    <AiMessageActions>
+                      <AiMessageAction
+                        tooltip="Copy"
+                        label="Copy message"
+                        onClick={() =>
+                          navigator.clipboard?.writeText(msg.content)
+                        }
+                      >
+                        <svg
+                          width={14}
+                          height={14}
+                          viewBox="0 0 24 24"
+                          fill="none"
+                          stroke="currentColor"
+                          strokeWidth={2}
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          aria-hidden
+                        >
+                          <rect x={9} y={9} width={13} height={13} rx={2} />
+                          <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+                        </svg>
+                      </AiMessageAction>
+                    </AiMessageActions>
+                  </AiMessageToolbar>
+                )}
+              </AiMessage>
+            </div>
+          ),
+        });
+      }
+    }
+
+    // Standalone notices (not attached to a message)
+    const standaloneNotices = state.notices.filter((n) => !n.messageId);
+    for (const notice of standaloneNotices) {
+      items.push({
+        key: `notice-${notice.id}`,
+        render: () => (
+          <div className="py-0.5">
+            <AiInfoBanner level={notice.level}>{notice.message}</AiInfoBanner>
+          </div>
+        ),
+      });
+    }
+
+    // Workspace error
+    if (state.workspaceError) {
+      items.push({
+        key: "__workspace_error__",
+        render: () => (
+          <div className="py-0.5">
+            <AiInfoBanner level="error">
+              Workspace error: {state.workspaceError}
+            </AiInfoBanner>
+          </div>
+        ),
+      });
+    }
+
+    return items;
+  }, [
+    isEmpty,
+    emptyState,
+    suggestions,
+    state,
+    hitlPlacement,
+    handleApprove,
+    handleReject,
+    handleAnswer,
+    handlePlanApprove,
+    handlePlanReject,
+    handleSuggestion,
+  ]);
+
+  // ── Virtualizer ────────────────────────────────────────────────────────────
+  const { virtualItems, totalSize, measureRef, isAtBottom, scrollToBottom } =
+    useConversationVirtualizer({
+      scrollRef,
+      items: conversationItems,
+      estimateSize: 100,
+      overscan: 8,
+    });
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+  return (
+    <div
+      className={cn(
+        "flex h-full min-h-0 flex-col overflow-hidden rounded-xl border border-sf-line bg-sf-base",
+        className
+      )}
+      {...props}
+    >
+      {/* Header */}
+      {header ?? <DefaultHeader isRunning={state.isRunning} onAbort={abort} />}
+
+      {/* Virtualized conversation area */}
+      <AiConversation ref={scrollRef} className="flex-1 min-h-0">
+        <div className="relative w-full" style={{ height: totalSize }}>
+          {virtualItems.map((vi) => {
+            const item = conversationItems[vi.index];
+            if (!item) return null;
+            return (
+              <div
+                key={item.key}
+                ref={measureRef}
+                data-index={vi.index}
+                className="absolute left-0 w-full px-4"
+                style={{ top: vi.start }}
+              >
+                {item.render()}
+              </div>
+            );
+          })}
+        </div>
+
+        {!isAtBottom && (
+          <AiConversationScrollButton
+            scrollRef={scrollRef}
+            onClick={() => scrollToBottom()}
+          />
+        )}
+      </AiConversation>
+
+      {/* Prompt input */}
+      <div className="border-t border-sf-line p-3">
+        <PromptInput
+          onSubmit={(msg) => handleSubmit({ text: msg.text, files: msg.files })}
+          backLayer={
+            hasBackLayerContent ? (
+              <BackLayerContent
+                taskList={showTaskList ? state.taskList : null}
+                usage={state.usage}
+                showUsage={showUsage}
+                pendingQuestion={pendingQuestion}
+                pendingPlan={pendingPlan}
+                hitlPlacement={hitlPlacement}
+                onAnswer={handleAnswer}
+                onPlanApprove={handlePlanApprove}
+                onPlanReject={handlePlanReject}
+              />
+            ) : undefined
+          }
+          backLayerTitle={
+            state.taskList?.title ??
+            (pendingQuestion ? "Question" : undefined) ??
+            (pendingPlan ? "Plan Review" : undefined) ??
+            "Context"
+          }
+          backLayerOpen={isBackLayerOpen}
+          onBackLayerOpenChange={setIsBackLayerOpen}
+        >
+          <PromptInputTextarea placeholder={placeholder} />
+          <PromptInputToolbar>
+            <PromptInputTools>
+              {allowAttachments && <PromptInputAttachButton />}
+              {allowSpeech && <PromptInputSpeechButton />}
+              {availableModes && availableModes.length > 0 ? (
+                <PromptInputModeSelector
+                  modes={availableModes}
+                  value={state.modeId}
+                  onChange={selectMode}
+                />
+              ) : (
+                (showMode || showModel) &&
+                (state.modeName || state.modelId) && (
+                  <span className="flex items-center gap-1.5 text-[11px] text-sf-subtle">
+                    {showMode && state.modeName && (
+                      <span className="font-medium">{state.modeName}</span>
+                    )}
+                    {showMode &&
+                      state.modeName &&
+                      showModel &&
+                      state.modelId && (
+                        <span className="text-sf-inactive">·</span>
+                      )}
+                    {showModel && state.modelId && (
+                      <span>
+                        {getModelDisplayName(state.modelId, state.modelName)}
+                      </span>
+                    )}
+                  </span>
+                )
+              )}
+            </PromptInputTools>
+            {renderSubmit ? (
+              renderSubmit(state)
+            ) : (
+              <PromptInputSubmit
+                status={promptStatus}
+                {...(state.isRunning && {
+                  type: "button",
+                  onClick: abort,
+                })}
+              />
+            )}
+          </PromptInputToolbar>
+        </PromptInput>
+
+        {footer && (
+          <div className="mt-2 text-center text-xs text-sf-subtle">
+            {footer}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+AgentHarness.displayName = "AgentHarness";
+
+// Re-export utilities consumers need alongside the block
+export { createAgentHarnessState, fromMastraHarness, useAgentHarness };
+export type {
+  // Primary render contract — target this type when building your own state
+  AgentHarnessState,
+  AgentMessage,
+  AgentToolCall,
+  AgentSubagent,
+  AgentOMActivity,
+  AgentQuestion,
+  AgentPlanApproval,
+  AgentTaskList,
+  AgentUsage,
+  AgentNotice,
+  // Uncontrolled-mode API
+  HarnessAdapter,
+  HarnessEvent,
+  UseAgentHarnessReturn,
+};