@optilogic/chat 1.0.0-beta.8 → 1.0.0-beta.9

package/src/components/agent-response/components/HITLSection.tsx

@@ -0,0 +1,95 @@
+/**
+ * HITL Section Component
+ *
+ * Collapsible section for displaying completed HITL (Human-in-the-Loop)
+ * interactions within an AgentResponse. Follows the same pattern as
+ * ThinkingSection for consistent UX.
+ */
+
+import * as React from "react";
+import { useState, useCallback } from "react";
+import { ChevronDown, ChevronRight, MessageCircleQuestion } from "lucide-react";
+import { cn } from "@optilogic/core";
+import { HITLInteractionRecord } from "../../hitl-interactions";
+import type { HITLInteraction } from "../../hitl-interactions";
+
+export interface HITLSectionProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** The HITL interactions to display */
+  interactions: HITLInteraction[];
+  /** Whether the section starts expanded (uncontrolled) */
+  defaultExpanded?: boolean;
+  /** Whether the section is expanded (controlled) */
+  isExpanded?: boolean;
+  /** Callback when expansion state changes (controlled) */
+  onExpandedChange?: (expanded: boolean) => void;
+}
+
+const HITLSection = React.forwardRef<HTMLDivElement, HITLSectionProps>(
+  (
+    {
+      interactions,
+      defaultExpanded = false,
+      isExpanded: controlledExpanded,
+      onExpandedChange,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const [uncontrolledExpanded, setUncontrolledExpanded] =
+      useState(defaultExpanded);
+
+    const isControlled = controlledExpanded !== undefined;
+    const isExpanded = isControlled ? controlledExpanded : uncontrolledExpanded;
+
+    const toggleExpanded = useCallback(() => {
+      const newValue = !isExpanded;
+      if (isControlled) {
+        onExpandedChange?.(newValue);
+      } else {
+        setUncontrolledExpanded(newValue);
+      }
+    }, [isExpanded, isControlled, onExpandedChange]);
+
+    if (!interactions || interactions.length === 0) {
+      return null;
+    }
+
+    return (
+      <div
+        ref={ref}
+        className={cn("border-t border-border", className)}
+        {...props}
+      >
+        {/* Collapsible header */}
+        <button
+          onClick={toggleExpanded}
+          className="w-full flex items-center gap-2 py-2 px-3 hover:bg-muted/50 transition-colors text-left"
+        >
+          {isExpanded ? (
+            <ChevronDown className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          ) : (
+            <ChevronRight className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          )}
+          <MessageCircleQuestion className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          <span className="text-xs font-medium text-foreground/80">
+            Clarifying Questions ({interactions.length})
+          </span>
+        </button>
+
+        {/* Expanded content */}
+        {isExpanded && (
+          <div className="px-3 pb-3 space-y-2">
+            {interactions.map((interaction, i) => (
+              <HITLInteractionRecord key={i} interaction={interaction} />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+HITLSection.displayName = "HITLSection";
+
+export { HITLSection };

package/src/components/agent-response/components/index.ts

@@ -13,3 +13,6 @@ export type { ThinkingSectionProps } from "./ThinkingSection";
 
 export { ActionBar } from "./ActionBar";
 export type { ActionBarProps } from "./ActionBar";
+
+export { HITLSection } from "./HITLSection";
+export type { HITLSectionProps } from "./HITLSection";

package/src/components/agent-response/index.ts

@@ -15,10 +15,12 @@ export {
   MetadataRow,
   ThinkingSection,
   ActionBar,
+  HITLSection,
   type ActivityIndicatorsProps,
   type MetadataRowProps,
   type ThinkingSectionProps,
   type ActionBarProps,
+  type HITLSectionProps,
 } from "./components";
 
 // Hooks

package/src/components/hitl-interactions/HITLInteractionRecord.tsx

@@ -0,0 +1,139 @@
+/**
+ * HITLInteractionRecord — Displays a completed HITL Q&A interaction
+ * in the chat message history.
+ *
+ * Rendered below AgentResponse in the agent message block. Shows the full detail
+ * of each clarifying question the agent asked and the user's response.
+ */
+
+import * as React from "react";
+import { useMemo } from "react";
+import { cn } from "@optilogic/core";
+import type { HITLQuestion } from "./HITLQuestionPanel";
+
+export interface HITLInteraction {
+  question: HITLQuestion;
+  response: string;
+  respondedAt: number;
+}
+
+export interface HITLInteractionRecordProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  interaction: HITLInteraction;
+}
+
+/**
+ * Parse the formatted response string (produced by buildResponseString) back
+ * into a per-question answer map and optional additional context.
+ */
+function parseResponse(response: string): {
+  answers: Record<string, string>;
+  additionalContext: string | null;
+} {
+  const answers: Record<string, string> = {};
+  let additionalContext: string | null = null;
+
+  const blocks = response.split("\n\n");
+  for (const block of blocks) {
+    const qaMatch = block.match(/^Q: (.+)\nA: (.+)$/s);
+    if (qaMatch) {
+      answers[qaMatch[1].trim()] = qaMatch[2].trim();
+    } else if (block.startsWith("Additional context: ")) {
+      additionalContext = block.slice("Additional context: ".length).trim();
+    }
+  }
+
+  return { answers, additionalContext };
+}
+
+const HITLInteractionRecord = React.forwardRef<
+  HTMLDivElement,
+  HITLInteractionRecordProps
+>(({ interaction, className, ...props }, ref) => {
+  const { question, response, respondedAt } = interaction;
+  const timestamp = new Date(respondedAt).toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+
+  const { answers, additionalContext } = useMemo(
+    () => parseResponse(response),
+    [response]
+  );
+
+  // Check if parsing found any structured answers; if not, fall back to
+  // showing the raw response string (for responses not built by buildResponseString).
+  const hasParsedAnswers = Object.keys(answers).length > 0;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "rounded-lg border border-border bg-muted p-3 space-y-2 text-sm",
+        className
+      )}
+      {...props}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <span className="font-medium text-muted-foreground">
+          Clarifying Question
+        </span>
+        <span className="text-xs text-muted-foreground">{timestamp}</span>
+      </div>
+
+      {/* Reason */}
+      <p className="text-foreground font-medium">{question.reason}</p>
+
+      {/* Context (if provided) */}
+      {question.context && (
+        <div className="text-xs text-muted-foreground bg-background rounded p-2 border border-border">
+          <pre className="whitespace-pre-wrap font-mono">
+            {question.context}
+          </pre>
+        </div>
+      )}
+
+      {/* Questions with inline answers */}
+      <div className="space-y-2">
+        {question.questions.map((q, i) => (
+          <div key={i}>
+            <p className="text-foreground">{q}</p>
+            {question.options?.[q] && (
+              <p className="text-xs text-muted-foreground ml-2">
+                Options: {question.options[q].join(", ")}
+              </p>
+            )}
+            {hasParsedAnswers && answers[q] && (
+              <p className="text-xs text-foreground ml-2 mt-0.5 bg-background rounded px-2 py-1 border border-border">
+                <span className="text-muted-foreground">Answer: </span>
+                {answers[q]}
+              </p>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Additional context from freeform text, or raw fallback */}
+      {hasParsedAnswers && additionalContext && (
+        <div className="border-t border-border pt-2">
+          <span className="text-muted-foreground text-xs">
+            Additional context:
+          </span>
+          <p className="text-foreground mt-0.5">{additionalContext}</p>
+        </div>
+      )}
+
+      {/* Fallback: show raw response if it wasn't in the parsed Q/A format */}
+      {!hasParsedAnswers && (
+        <div className="border-t border-border pt-2">
+          <span className="text-muted-foreground text-xs">Response:</span>
+          <p className="text-foreground mt-0.5">{response}</p>
+        </div>
+      )}
+    </div>
+  );
+});
+HITLInteractionRecord.displayName = "HITLInteractionRecord";
+
+export { HITLInteractionRecord };

package/src/components/hitl-interactions/HITLQuestionPanel.tsx

@@ -0,0 +1,256 @@
+/**
+ * HITLQuestionPanel — Human-in-the-Loop clarifying question panel.
+ *
+ * Renders in the input area (replacing UserPromptInput) when the agent asks a
+ * clarifying question via the HumanInTheLoop tool. Shows the question details
+ * and lets the user respond via option buttons or free-form text.
+ *
+ * Option clicks select/toggle rather than immediately submitting. The "Send
+ * response" button enables once all questions have a selected option OR the
+ * textarea has text. On submit, selected options and free-form text are
+ * combined into a single formatted string for the backend.
+ */
+
+import * as React from "react";
+import { useState, useEffect, useRef, useCallback, useMemo } from "react";
+import { cn, Button, Textarea } from "@optilogic/core";
+
+export interface HITLQuestion {
+  reason: string;
+  questions: string[];
+  options: Record<string, string[]> | null;
+  context: string | null;
+  timeoutSeconds: number;
+  receivedAt: number;
+}
+
+export interface HITLQuestionPanelProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit"> {
+  question: HITLQuestion;
+  onSubmit: (response: string) => void;
+  onStop: () => void;
+}
+
+/**
+ * Build a single response string from selected options and optional free-form text.
+ * Format is designed to be easily parsed by the LLM consuming the response.
+ */
+export function buildResponseString(
+  questions: string[],
+  selectedOptions: Record<string, string>,
+  freeformText: string
+): string {
+  const parts: string[] = [];
+
+  for (const q of questions) {
+    const answer = selectedOptions[q];
+    if (answer) {
+      parts.push(`Q: ${q}\nA: ${answer}`);
+    }
+  }
+
+  const trimmed = freeformText.trim();
+  if (trimmed) {
+    parts.push(`Additional context: ${trimmed}`);
+  }
+
+  return parts.join("\n\n");
+}
+
+const HITLQuestionPanel = React.forwardRef<
+  HTMLDivElement,
+  HITLQuestionPanelProps
+>(({ question, onSubmit, onStop, className, ...props }, ref) => {
+  const [freeformText, setFreeformText] = useState("");
+  const [selectedOptions, setSelectedOptions] = useState<
+    Record<string, string>
+  >({});
+  const [secondsLeft, setSecondsLeft] = useState(() =>
+    Math.max(
+      0,
+      Math.round(
+        question.timeoutSeconds - (Date.now() - question.receivedAt) / 1000
+      )
+    )
+  );
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Focus the textarea on mount
+  useEffect(() => {
+    textareaRef.current?.focus();
+  }, []);
+
+  // Countdown timer
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const remaining = Math.max(
+        0,
+        Math.round(
+          question.timeoutSeconds - (Date.now() - question.receivedAt) / 1000
+        )
+      );
+      setSecondsLeft(remaining);
+      if (remaining <= 0) clearInterval(interval);
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [question.timeoutSeconds, question.receivedAt]);
+
+  const timedOut = secondsLeft <= 0;
+
+  // Which questions have options defined?
+  const questionsWithOptions = useMemo(
+    () => question.questions.filter((q) => question.options?.[q]?.length),
+    [question.questions, question.options]
+  );
+
+  const allOptionsSelected =
+    questionsWithOptions.length > 0 &&
+    questionsWithOptions.every((q) => selectedOptions[q]);
+
+  const hasFreeformText = freeformText.trim().length > 0;
+
+  const canSubmit = !timedOut && (allOptionsSelected || hasFreeformText);
+
+  const handleOptionClick = useCallback(
+    (questionText: string, option: string) => {
+      if (timedOut) return;
+      setSelectedOptions((prev) => {
+        // Toggle: deselect if already selected, otherwise select
+        if (prev[questionText] === option) {
+          const next = { ...prev };
+          delete next[questionText];
+          return next;
+        }
+        return { ...prev, [questionText]: option };
+      });
+    },
+    [timedOut]
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!canSubmit) return;
+    const combined = buildResponseString(
+      question.questions,
+      selectedOptions,
+      freeformText
+    );
+    onSubmit(combined);
+  }, [canSubmit, question.questions, selectedOptions, freeformText, onSubmit]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    },
+    [handleSubmit]
+  );
+
+  const formatTime = (s: number) => {
+    const m = Math.floor(s / 60);
+    const sec = s % 60;
+    return `${m}:${sec.toString().padStart(2, "0")}`;
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "rounded-lg border border-border bg-muted p-4 space-y-3",
+        className
+      )}
+      {...props}
+    >
+      {/* Header: reason + countdown */}
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex-1">
+          <p className="text-sm font-medium text-foreground">
+            {question.reason}
+          </p>
+        </div>
+        <span
+          className={cn(
+            "text-xs font-mono whitespace-nowrap",
+            secondsLeft <= 30 ? "text-destructive" : "text-muted-foreground"
+          )}
+        >
+          {timedOut ? "Timed out" : formatTime(secondsLeft)}
+        </span>
+      </div>
+
+      {/* Context (if provided) */}
+      {question.context && (
+        <div className="text-xs text-muted-foreground bg-background rounded p-2 border border-border max-h-24 overflow-y-auto">
+          <pre className="whitespace-pre-wrap font-mono">
+            {question.context}
+          </pre>
+        </div>
+      )}
+
+      {/* Questions */}
+      <div className="space-y-3">
+        {question.questions.map((q, i) => (
+          <div key={i}>
+            <p className="text-sm text-foreground">{q}</p>
+
+            {/* Options for this question (if provided) */}
+            {question.options?.[q] && (
+              <div className="flex flex-wrap gap-2 mt-1.5">
+                {question.options[q].map((option, j) => {
+                  const isSelected = selectedOptions[q] === option;
+                  return (
+                    <Button
+                      key={j}
+                      variant={isSelected ? "primary" : "outline"}
+                      size="sm"
+                      onClick={() => handleOptionClick(q, option)}
+                      disabled={timedOut}
+                    >
+                      {option}
+                    </Button>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Free-form input — always shown for additional context */}
+      <Textarea
+        ref={textareaRef}
+        value={freeformText}
+        onChange={(e) => setFreeformText(e.target.value)}
+        onKeyDown={handleKeyDown}
+        disabled={timedOut}
+        placeholder="Add additional context or type a full response..."
+        rows={2}
+        className="resize-none"
+      />
+
+      <div className="flex items-center justify-between">
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={onStop}
+          className="text-destructive hover:text-destructive hover:bg-destructive/10"
+        >
+          Stop agent
+        </Button>
+
+        <Button
+          variant="primary"
+          size="sm"
+          onClick={handleSubmit}
+          disabled={!canSubmit}
+        >
+          Send response
+        </Button>
+      </div>
+    </div>
+  );
+});
+HITLQuestionPanel.displayName = "HITLQuestionPanel";
+
+export { HITLQuestionPanel };

package/src/components/hitl-interactions/index.ts

@@ -0,0 +1,18 @@
+/**
+ * HITL (Human-in-the-Loop) Interaction Components
+ *
+ * Components for displaying and handling clarifying questions
+ * between the AI agent and the user during a conversation.
+ */
+
+// Question panel (interactive input area)
+export { HITLQuestionPanel } from "./HITLQuestionPanel";
+export type { HITLQuestionPanelProps, HITLQuestion } from "./HITLQuestionPanel";
+export { buildResponseString } from "./HITLQuestionPanel";
+
+// Interaction record (read-only history display)
+export { HITLInteractionRecord } from "./HITLInteractionRecord";
+export type {
+  HITLInteractionRecordProps,
+  HITLInteraction,
+} from "./HITLInteractionRecord";

package/src/index.ts

@@ -15,10 +15,12 @@ export {
   MetadataRow,
   ThinkingSection,
   ActionBar,
+  HITLSection,
   type ActivityIndicatorsProps,
   type MetadataRowProps,
   type ThinkingSectionProps,
   type ActionBarProps,
+  type HITLSectionProps,
 
   // Hooks
   useAgentResponseAccumulator,
@@ -57,3 +59,14 @@ export {
   type UserPromptInputProps,
   type UserPromptInputRef,
 } from "./components/user-prompt-input";
+
+// HITL Interactions - Human-in-the-loop question/response components
+export {
+  HITLQuestionPanel,
+  type HITLQuestionPanelProps,
+  HITLInteractionRecord,
+  type HITLInteractionRecordProps,
+  type HITLQuestion,
+  type HITLInteraction,
+  buildResponseString,
+} from "./components/hitl-interactions";