@optilogic/chat 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index.d.cts

@@ -40,6 +40,37 @@ interface MemoryItem {
     content: string;
     timestamp: number;
 }
+/**
+ * Status update information from the agent
+ */
+interface StatusItem {
+    id: string;
+    message: string;
+    timestamp: number;
+    /** Optional agent name if in multi-agent scenario */
+    agent?: string;
+}
+/**
+ * A single step in structured thinking content
+ */
+interface ThinkingStep {
+    /** Unique identifier for the step */
+    id: string;
+    /** Label/title shown in the collapsible header */
+    label: string;
+    /** Content of the thinking step */
+    content: string;
+    /** Nesting depth (0 = root level, 1 = first indent, etc.) */
+    depth: number;
+    /** Whether this step should start collapsed (default: false) */
+    isCollapsed?: boolean;
+}
+/**
+ * Union type for thinking content
+ * - string: plain text (backward compatible)
+ * - ThinkingStep[]: structured with collapsible sub-sections
+ */
+type ThinkingContent = string | ThinkingStep[];
 /**
  * State shape for the agent response component
  */
@@ -48,12 +79,16 @@ interface AgentResponseState {
     status: AgentResponseStatus;
     /** Accumulated thinking/reasoning text */
     thinking: string;
+    /** Structured thinking steps (if provided, takes precedence over thinking string) */
+    thinkingSteps?: ThinkingStep[];
     /** Tool calls made during processing */
     toolCalls: ToolCall[];
     /** Knowledge items retrieved */
     knowledge: KnowledgeItem[];
     /** Memory items accessed */
     memory: MemoryItem[];
+    /** Status updates from the agent */
+    statusUpdates: StatusItem[];
     /** Final response text */
     response: string;
     /** Timestamp when first thinking message was received (for timer) */
@@ -67,7 +102,7 @@ interface AgentResponseState {
  * WebSocket message payload for agent responses
  */
 interface AgentMessage {
-    type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response";
+    type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response" | "status_update";
     /** Message content - for simple string payloads */
     message?: string;
     /** Alternative content field */
@@ -92,6 +127,20 @@ interface AgentMessage {
         type: string;
         content: string;
     };
+    /** For status_update messages */
+    statusUpdate?: {
+        id: string;
+        message: string;
+        agent?: string;
+    };
+    /** For structured thinking step messages */
+    thinkingStep?: {
+        id?: string;
+        label: string;
+        content: string;
+        depth?: number;
+        isCollapsed?: boolean;
+    };
 }
 /**
  * Generic websocket message wrapper type
@@ -106,6 +155,58 @@ interface GenericWebSocketMessage {
  */
 declare const initialAgentResponseState: AgentResponseState;
 
+/**
+ * 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.
+ */
+
+interface HITLQuestion {
+    reason: string;
+    questions: string[];
+    options: Record<string, string[]> | null;
+    context: string | null;
+    /** Timeout in seconds. When omitted, no countdown is shown and the panel never times out. */
+    timeoutSeconds?: number;
+    receivedAt: number;
+}
+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.
+ */
+declare function buildResponseString(questions: string[], selectedOptions: Record<string, string>, freeformText: string): string;
+declare const HITLQuestionPanel: React.ForwardRefExoticComponent<HITLQuestionPanelProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * 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.
+ */
+
+interface HITLInteraction {
+    question: HITLQuestion;
+    response: string;
+    respondedAt: number;
+}
+interface HITLInteractionRecordProps extends React.HTMLAttributes<HTMLDivElement> {
+    interaction: HITLInteraction;
+}
+declare const HITLInteractionRecord: React.ForwardRefExoticComponent<HITLInteractionRecordProps & React.RefAttributes<HTMLDivElement>>;
+
 /**
  * AgentResponse Component
  *
@@ -131,6 +232,32 @@ interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement> {
     onThinkingExpandedChange?: (expanded: boolean) => void;
     /** Action bar visibility mode */
     actionsVisible?: boolean | "hover";
+    /**
+     * Optional HITL (Human-in-the-Loop) interactions to display as a
+     * collapsible section within the response. When provided, a "Clarifying
+     * Questions" section appears between the thinking/metadata area and
+     * the response content.
+     */
+    hitlInteractions?: HITLInteraction[];
+    /** Whether the HITL section starts expanded (default: false) */
+    defaultHITLExpanded?: boolean;
+    /**
+     * Optional content to display in the MetadataRow's middle area,
+     * between the thinking toggle (left) and activity indicators (right).
+     * Typically used for ephemeral status messages during processing.
+     * The parent is responsible for setting and clearing this content.
+     *
+     * @example
+     * <AgentResponse
+     *   state={state}
+     *   statusContent={
+     *     state.status !== 'complete'
+     *       ? <TruncatedMessage message="Analyzing data..." />
+     *       : undefined
+     *   }
+     * />
+     */
+    statusContent?: React.ReactNode;
     /**
      * Custom markdown renderer for the response content.
      * If not provided, the response will be rendered as plain text.
@@ -142,6 +269,17 @@ interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement> {
      * />
      */
     renderMarkdown?: (content: string) => React.ReactNode;
+    /**
+     * Custom markdown renderer for the thinking content.
+     * If not provided, the thinking will be rendered as plain preformatted text.
+     *
+     * @example
+     * <AgentResponse
+     *   state={state}
+     *   renderThinkingMarkdown={(content) => <MyMarkdownRenderer content={content} />}
+     * />
+     */
+    renderThinkingMarkdown?: (content: string) => React.ReactNode;
 }
 /**
  * AgentResponse Component
@@ -190,6 +328,8 @@ interface ActivityIndicatorsProps extends React.HTMLAttributes<HTMLDivElement> {
     knowledge: KnowledgeItem[];
     /** Memory items to display */
     memory: MemoryItem[];
+    /** Status updates to display */
+    statusUpdates?: StatusItem[];
 }
 /**
  * ActivityIndicators Component
@@ -225,6 +365,10 @@ interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
     knowledge: KnowledgeItem[];
     /** Memory items to display */
     memory: MemoryItem[];
+    /** Status updates to display */
+    statusUpdates?: StatusItem[];
+    /** Optional content to display in the middle area between left content and activity indicators */
+    statusContent?: React.ReactNode;
     /** Current response status */
     status: AgentResponseStatus;
     /** Elapsed time in seconds */
@@ -253,22 +397,40 @@ declare const MetadataRow: React.ForwardRefExoticComponent<MetadataRowProps & Re
 /**
  * Thinking Section Component
  *
- * Collapsible section for displaying agent thinking/reasoning content
+ * Collapsible section for displaying agent thinking/reasoning content.
+ * Supports both plain text and structured collapsible sub-sections.
  */
 
-interface ThinkingSectionProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** The thinking content to display */
-    content: string;
+interface ThinkingSectionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "content"> {
+    /** The thinking content to display (string or structured steps) */
+    content: string | ThinkingStep[];
     /** Whether the section is expanded */
     isExpanded: boolean;
+    /**
+     * Custom markdown renderer for the thinking content.
+     * If not provided, the content will be rendered as plain preformatted text.
+     */
+    renderMarkdown?: (content: string) => React.ReactNode;
 }
 /**
  * ThinkingSection Component
  *
  * Displays the agent's thinking/reasoning content in a collapsible panel.
+ * Supports both plain text content and structured collapsible sub-sections.
  *
  * @example
+ * // Plain text content
  * <ThinkingSection content={state.thinking} isExpanded={isExpanded} />
+ *
+ * @example
+ * // Structured content with sub-sections
+ * <ThinkingSection
+ *   content={[
+ *     { id: "1", label: "Analysis", content: "...", depth: 0 },
+ *     { id: "2", label: "Sub-analysis", content: "...", depth: 1 },
+ *   ]}
+ *   isExpanded={isExpanded}
+ * />
  */
 declare const ThinkingSection: React.ForwardRefExoticComponent<ThinkingSectionProps & React.RefAttributes<HTMLDivElement>>;
 
@@ -310,6 +472,56 @@ interface ActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
  */
 declare const ActionBar: React.ForwardRefExoticComponent<ActionBarProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * 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.
+ */
+
+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;
+}
+declare const HITLSection: React.ForwardRefExoticComponent<HITLSectionProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Truncated Message Component
+ *
+ * Renders a single-line text message with CSS-based truncation (text-overflow: ellipsis).
+ * Designed as a standalone utility that can be used anywhere, including as
+ * the statusContent slot in MetadataRow.
+ */
+
+interface TruncatedMessageProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The message string to display (truncated with ellipsis if it overflows) */
+    message: string;
+}
+/**
+ * TruncatedMessage Component
+ *
+ * Displays a single-line text message that truncates with an ellipsis when
+ * it overflows its container. Uses CSS text-overflow for zero-JS truncation.
+ *
+ * @example
+ * <TruncatedMessage message="Searching the knowledge base for relevant documents..." />
+ *
+ * @example
+ * // Inside MetadataRow's statusContent slot
+ * <AgentResponse
+ *   state={state}
+ *   statusContent={<TruncatedMessage message="Running analysis..." />}
+ * />
+ */
+declare const TruncatedMessage: React.ForwardRefExoticComponent<TruncatedMessageProps & React.RefAttributes<HTMLDivElement>>;
+
 /**
  * useThinkingTimer Hook
  *
@@ -375,4 +587,105 @@ declare function formatTime(seconds: number, isComplete: boolean): string;
  */
 declare function formatTotalTime(seconds: number): string;
 
-export { ActionBar, type ActionBarProps, ActivityIndicators, type ActivityIndicatorsProps, type AgentMessage, AgentResponse, type AgentResponseProps, type AgentResponseState, type AgentResponseStatus, type FeedbackValue, type GenericWebSocketMessage, type KnowledgeItem, type MemoryItem, MetadataRow, type MetadataRowProps, ThinkingSection, type ThinkingSectionProps, type ToolCall, type UseAgentResponseAccumulatorOptions, type UseAgentResponseAccumulatorReturn, type UseThinkingTimerOptions, formatTime, formatTotalTime, initialAgentResponseState, useAgentResponseAccumulator, useThinkingTimer };
+interface UserPromptProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The text content of the user's message */
+    content: string;
+    /** Optional timestamp to display below the message */
+    timestamp?: Date;
+}
+/**
+ * UserPrompt component
+ *
+ * Displays a user's chat message in a styled bubble.
+ * Used alongside AgentResponse to create chat interfaces.
+ *
+ * @example
+ * ```tsx
+ * <UserPrompt
+ *   content="What is the weather today?"
+ *   timestamp={new Date()}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <UserPrompt
+ *   content="Hello world"
+ *   className="max-w-full"
+ * />
+ * ```
+ */
+declare const UserPrompt: React.ForwardRefExoticComponent<UserPromptProps & React.RefAttributes<HTMLDivElement>>;
+
+interface UserPromptInputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "onSubmit"> {
+    /** Current text value */
+    value?: string;
+    /** Callback when text changes */
+    onChange?: (value: string) => void;
+    /** Callback when user submits (Enter key or send button) */
+    onSubmit?: (text: string) => void;
+    /** Clear input after submit (default: true) */
+    clearOnSubmit?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Whether a submission is in progress (shows loading state) */
+    isSubmitting?: boolean;
+    /** Called when user clicks Stop during submission */
+    onStop?: () => void;
+    /** Whether to disable input while submitting (default: true) */
+    disableWhileSubmitting?: boolean;
+    /** Auto-focus the editor when mounted (handles Slate initialization timing) */
+    autoFocus?: boolean;
+    /** Refocus the input after submission completes (default: false) */
+    refocusAfterSubmit?: boolean;
+    /** Called when the editor is fully initialized and ready for interaction */
+    onReady?: () => void;
+    /** Minimum number of rows for the editor */
+    minRows?: number;
+    /** Maximum number of rows before scrolling */
+    maxRows?: number;
+    /** Render function for additional action buttons (left side) */
+    renderActions?: () => React.ReactNode;
+    /** Enable tag detection with # character */
+    enableTags?: boolean;
+    /** Callback when a tag is created */
+    onTagCreate?: (tag: string) => void;
+    /** Callback when a tag is deleted */
+    onTagDelete?: (tag: string) => void;
+}
+interface UserPromptInputRef {
+    /** Focus the editor */
+    focus: () => void;
+    /** Clear the editor content */
+    clear: () => void;
+    /** Get the current text content */
+    getText: () => string;
+    /** Insert text at cursor position */
+    insertText: (text: string) => void;
+}
+
+/**
+ * UserPromptInput Component
+ *
+ * A rich text input for user messages that wraps SlateEditor.
+ * Features:
+ * - Code block styling with triple backticks
+ * - Send button with loading state
+ * - Action slot for additional buttons
+ * - Tag support (optional)
+ *
+ * @example
+ * <UserPromptInput
+ *   placeholder="Type your message..."
+ *   onSubmit={(text) => sendMessage(text)}
+ *   renderActions={() => (
+ *     <IconButton icon={<Paperclip />} aria-label="Attach file" />
+ *   )}
+ * />
+ */
+declare const UserPromptInput: React.ForwardRefExoticComponent<UserPromptInputProps & React.RefAttributes<UserPromptInputRef>>;
+
+export { ActionBar, type ActionBarProps, ActivityIndicators, type ActivityIndicatorsProps, type AgentMessage, AgentResponse, type AgentResponseProps, type AgentResponseState, type AgentResponseStatus, type FeedbackValue, type GenericWebSocketMessage, type HITLInteraction, HITLInteractionRecord, type HITLInteractionRecordProps, type HITLQuestion, HITLQuestionPanel, type HITLQuestionPanelProps, HITLSection, type HITLSectionProps, type KnowledgeItem, type MemoryItem, MetadataRow, type MetadataRowProps, type StatusItem, type ThinkingContent, ThinkingSection, type ThinkingSectionProps, type ThinkingStep, type ToolCall, TruncatedMessage, type TruncatedMessageProps, type UseAgentResponseAccumulatorOptions, type UseAgentResponseAccumulatorReturn, type UseThinkingTimerOptions, UserPrompt, UserPromptInput, type UserPromptInputProps, type UserPromptInputRef, type UserPromptProps, buildResponseString, formatTime, formatTotalTime, initialAgentResponseState, useAgentResponseAccumulator, useThinkingTimer };