@optilogic/chat 1.0.0-beta.8 → 1.0.0

package/dist/index.d.ts

@@ -1,10 +1,53 @@
 import * as React from 'react';
+import { ReactNode, ComponentType } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** All possible timeline entry types */
+type TimelineEntryType = "thinking" | "tool_call" | "knowledge" | "memory" | "status_update" | "ai_response" | "error";
+/** A single event in the agent execution timeline */
+interface TimelineEntry {
+    /** Unique ID for React keys */
+    id: string;
+    /** Discriminated type for icon and rendering */
+    type: TimelineEntryType;
+    /** The agent that produced this entry */
+    agentName: string | null;
+    /** The parent agent (null for root agent) */
+    parentAgent: string | null;
+    /** Nesting depth (0 = root) */
+    depth: number;
+    /** Display content (may be long) */
+    content: string;
+    /** Original title from the WebSocket message */
+    title: string | null;
+    /** Millisecond timestamp for ordering */
+    timestamp: number;
+}
+/** A consecutive run of messages from the same agent */
+interface AgentRun {
+    /** Agent name (display label) */
+    agentName: string;
+    /** Parent agent name (null for root) */
+    parentAgent: string | null;
+    /** Depth in agent hierarchy */
+    depth: number;
+    /** The entries belonging to this run, in order, after dedup */
+    entries: DisplayEntry[];
+}
+/** After dedup — count > 1 means consecutive identical messages collapsed */
+interface DisplayEntry {
+    /** The underlying timeline entry (first of the group if deduped) */
+    entry: TimelineEntry;
+    /** How many consecutive identical messages were collapsed into this one */
+    count: number;
+}
 
 /**
  * Agent Response Component Types
  *
  * Type definitions for the library-ready agent response component
  */
+
 /**
  * Status of the agent response cycle
  */
@@ -21,6 +64,12 @@ interface ToolCall {
     name: string;
     arguments?: Record<string, unknown>;
     timestamp: number;
+    /** Agent that made this call (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name */
+    parentAgent?: string | null;
+    /** Nesting depth in agent hierarchy */
+    depth?: number;
 }
 /**
  * Knowledge retrieval information
@@ -30,6 +79,12 @@ interface KnowledgeItem {
     source: string;
     content: string;
     timestamp: number;
+    /** Agent that retrieved this (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name */
+    parentAgent?: string | null;
+    /** Nesting depth in agent hierarchy */
+    depth?: number;
 }
 /**
  * Memory access information
@@ -39,6 +94,23 @@ interface MemoryItem {
     type: string;
     content: string;
     timestamp: number;
+    /** Agent that accessed this (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name */
+    parentAgent?: string | null;
+    /** Nesting depth in agent hierarchy */
+    depth?: number;
+}
+/**
+ * Potential response (sub-agent intermediate AI response)
+ */
+interface PotentialResponse {
+    id: string;
+    content: string;
+    timestamp: number;
+    agentName?: string | null;
+    parentAgent?: string | null;
+    depth?: number;
 }
 /**
  * Status update information from the agent
@@ -49,6 +121,12 @@ interface StatusItem {
     timestamp: number;
     /** Optional agent name if in multi-agent scenario */
     agent?: string;
+    /** Agent that produced this (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name */
+    parentAgent?: string | null;
+    /** Nesting depth in agent hierarchy */
+    depth?: number;
 }
 /**
  * A single step in structured thinking content
@@ -64,6 +142,12 @@ interface ThinkingStep {
     depth: number;
     /** Whether this step should start collapsed (default: false) */
     isCollapsed?: boolean;
+    /** Timestamp for timeline ordering */
+    timestamp?: number;
+    /** Agent that produced this (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name */
+    parentAgent?: string | null;
 }
 /**
  * Union type for thinking content
@@ -89,8 +173,14 @@ interface AgentResponseState {
     memory: MemoryItem[];
     /** Status updates from the agent */
     statusUpdates: StatusItem[];
+    /** Potential responses (sub-agent intermediate AI responses) */
+    potentialResponses?: PotentialResponse[];
+    /** Custom timeline entries (consumer-provided) */
+    customTimelineEntries?: TimelineEntry[];
     /** Final response text */
     response: string;
+    /** Timeline entries derived from all accumulator arrays (for AgentTimeline) */
+    timelineEntries?: TimelineEntry[];
     /** Timestamp when first thinking message was received (for timer) */
     thinkingStartTime: number | null;
     /** Timestamp when response was completed (for final timer display) */
@@ -102,13 +192,21 @@ interface AgentResponseState {
  * WebSocket message payload for agent responses
  */
 interface AgentMessage {
-    type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response" | "status_update";
+    type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response" | "status_update" | "potential_response";
     /** Message content - for simple string payloads */
     message?: string;
     /** Alternative content field */
     content?: string;
     /** For status messages */
     status?: string;
+    /** Agent name (multi-agent scenarios) */
+    agentName?: string | null;
+    /** Parent agent name (multi-agent scenarios) */
+    parentAgent?: string | null;
+    /** Agent nesting depth (0 = root) */
+    depth?: number;
+    /** Title/label for timeline display */
+    title?: string | null;
     /** For tool_call messages */
     tool?: {
         id: string;
@@ -155,6 +253,64 @@ 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 HITLResponseData {
+    /** Raw selected option text per question, keyed by question text */
+    selectedOptions: Record<string, string>;
+    /** Freeform text entered by the user (untrimmed) */
+    freeformText: string;
+}
+interface HITLQuestionPanelProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit"> {
+    question: HITLQuestion;
+    onSubmit: (response: string, data: HITLResponseData) => 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
  *
@@ -180,6 +336,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.
@@ -202,6 +384,11 @@ interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement> {
      * />
      */
     renderThinkingMarkdown?: (content: string) => React.ReactNode;
+    /**
+     * Maximum height of the AgentTimeline scrollable container.
+     * Defaults to "300px". Set to "none" to disable the constraint.
+     */
+    timelineMaxHeight?: string;
 }
 /**
  * AgentResponse Component
@@ -289,6 +476,8 @@ interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
     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 */
@@ -392,6 +581,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
  *
@@ -457,6 +696,49 @@ declare function formatTime(seconds: number, isComplete: boolean): string;
  */
 declare function formatTotalTime(seconds: number): string;
 
+/** Externalized UI state that survives component remounts */
+interface TimelineUIState {
+    expandedItems: Set<string>;
+    collapsedRuns: Set<string>;
+    activeFilters: Set<TimelineEntryType>;
+}
+declare function createTimelineUIState(): TimelineUIState;
+interface AgentTimelineProps {
+    entries: TimelineEntry[];
+    renderMarkdown?: (content: string) => ReactNode;
+    /**
+     * External UI state store. When provided, expand/collapse/filter state
+     * is read from and written to this object (which should be ref-backed
+     * in the parent) so it survives component remounts during streaming.
+     */
+    uiState?: TimelineUIState;
+    /**
+     * Maximum height of the scrollable timeline container.
+     * Defaults to "300px". Set to "none" to disable.
+     */
+    maxHeight?: string;
+}
+declare function AgentTimeline({ entries, renderMarkdown, uiState, maxHeight }: AgentTimelineProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Build a flat, chronologically sorted array of TimelineEntry from the
+ * accumulator state. Maps each typed array (toolCalls, knowledge, etc.)
+ * to unified TimelineEntry objects with per-source stable IDs.
+ */
+declare function buildTimelineEntries(state: AgentResponseState): TimelineEntry[];
+/**
+ * Group a sorted array of timeline entries into consecutive "agent runs".
+ * A new run starts whenever the agentName changes.
+ * Each run's entries are deduplicated.
+ */
+declare function groupIntoAgentRuns(entries: TimelineEntry[]): AgentRun[];
+/**
+ * Collapse consecutive entries with identical type AND content into
+ * a single DisplayEntry with count > 1.
+ * Handles patterns like "Loading documents" appearing 8 times.
+ */
+declare function deduplicateEntries(entries: DisplayEntry[]): DisplayEntry[];
+
 interface UserPromptProps extends React.HTMLAttributes<HTMLDivElement> {
     /** The text content of the user's message */
     content: string;
@@ -505,6 +787,10 @@ interface UserPromptInputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     isSubmitting?: boolean;
     /** Called when user clicks Stop during submission */
     onStop?: () => void;
+    /** Tooltip text shown on hover over the stop button */
+    stopTooltip?: string;
+    /** Additional CSS class names applied to the stop button */
+    stopClassName?: string;
     /** Whether to disable input while submitting (default: true) */
     disableWhileSubmitting?: boolean;
     /** Auto-focus the editor when mounted (handles Slate initialization timing) */
@@ -558,4 +844,77 @@ interface UserPromptInputRef {
  */
 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 KnowledgeItem, type MemoryItem, MetadataRow, type MetadataRowProps, type StatusItem, type ThinkingContent, ThinkingSection, type ThinkingSectionProps, type ThinkingStep, type ToolCall, type UseAgentResponseAccumulatorOptions, type UseAgentResponseAccumulatorReturn, type UseThinkingTimerOptions, UserPrompt, UserPromptInput, type UserPromptInputProps, type UserPromptInputRef, type UserPromptProps, formatTime, formatTotalTime, initialAgentResponseState, useAgentResponseAccumulator, useThinkingTimer };
+interface MarkdownSegment {
+    kind: "markdown";
+    content: string;
+}
+interface ActionSegment {
+    kind: "action";
+    actionType: string;
+    payload: Record<string, unknown>;
+}
+type ResponseSegment = MarkdownSegment | ActionSegment;
+/**
+ * Props passed to every inline action component.
+ * T is the shape of the payload for this specific action type.
+ */
+interface InlineActionProps<T = Record<string, unknown>> {
+    /** The parsed payload from the json:action block */
+    payload: T;
+    /** Callback to send results back to the page (e.g., map data) */
+    onAction?: (actionType: string, result: unknown) => void;
+    /** True for the most recent agent message; affects button labels */
+    isLatest?: boolean;
+}
+/**
+ * Maps action type strings to React components that render them.
+ * The consuming page owns this registry.
+ */
+type ActionComponentRegistry = Record<string, ComponentType<InlineActionProps<any>>>;
+interface ActionMarkdownRendererProps {
+    /** The raw response text (may contain json:action blocks) */
+    content: string;
+    /** Registry of action type -> component */
+    registry: ActionComponentRegistry;
+    /** The existing renderMarkdown function for plain markdown segments */
+    renderMarkdown: (content: string) => ReactNode;
+    /** Callback forwarded to action components */
+    onAction?: (actionType: string, result: unknown) => void;
+    /** Whether this is the latest (most recent) agent message */
+    isLatest?: boolean;
+}
+
+/**
+ * Renders agent response text with inline action components.
+ *
+ * Parses the response for ```json:action blocks, renders markdown
+ * segments via the provided renderMarkdown function, and renders
+ * action segments via the component registry.
+ *
+ * Unknown action types fall back to a raw JSON code block display.
+ */
+declare function ActionMarkdownRenderer({ content, registry, renderMarkdown, onAction, isLatest, }: ActionMarkdownRendererProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Parse response text into interleaved markdown and action segments.
+ *
+ * Finds ```json:action ... ``` fenced code blocks, extracts them as
+ * action segments, and returns the surrounding text as markdown segments.
+ *
+ * Malformed JSON or blocks missing a "type" field are left as markdown
+ * (rendered as raw code blocks) for graceful degradation.
+ */
+declare function parseResponseSegments(text: string): ResponseSegment[];
+
+/**
+ * System prompt instructions for agents that emit inline action blocks.
+ *
+ * Import and append to your agent's system prompt so it knows the
+ * json:action format. The XML tags ensure clear boundaries for the LLM.
+ *
+ * When adding a new action type, add an entry under "Available action types"
+ * and create the corresponding React component + registry entry.
+ */
+declare const INLINE_ACTION_PROMPT = "\n<inline_actions>\nWhen your response should include interactive components (like query viewers,\ndata tables, or executable actions), embed them as fenced code blocks using\nthe `json:action` language tag:\n\n```json:action\n{\n  \"type\": \"action-type-here\",\n  ...action-specific fields\n}\n```\n\nRules:\n- Each block must contain valid JSON with a \"type\" field.\n- The \"type\" must match a registered action component on the frontend.\n- Multiple action blocks per response are allowed.\n- Surround action blocks with normal markdown text for user context.\n- The action block is rendered as an interactive component in the chat UI.\n- SQL strings inside JSON must be properly escaped (newlines as \\n, quotes as \\\").\n\nAvailable action types:\n\n- \"optimap-query\": Displays SQL queries with a button to execute them and\n  update the 3D globe map.\n  Required fields:\n    - type: \"optimap-query\"\n    - locations_sql: string (the validated locations SQL query)\n    - routes_sql: string (the validated routes SQL query)\n    - database_name: string (the target database name)\n</inline_actions>\n";
+
+export { ActionBar, type ActionBarProps, type ActionComponentRegistry, ActionMarkdownRenderer, type ActionMarkdownRendererProps, type ActionSegment, ActivityIndicators, type ActivityIndicatorsProps, type AgentMessage, AgentResponse, type AgentResponseProps, type AgentResponseState, type AgentResponseStatus, type AgentRun, AgentTimeline, type DisplayEntry, type FeedbackValue, type GenericWebSocketMessage, type HITLInteraction, HITLInteractionRecord, type HITLInteractionRecordProps, type HITLQuestion, HITLQuestionPanel, type HITLQuestionPanelProps, type HITLResponseData, HITLSection, type HITLSectionProps, INLINE_ACTION_PROMPT, type InlineActionProps, type KnowledgeItem, type MarkdownSegment, type MemoryItem, MetadataRow, type MetadataRowProps, type PotentialResponse, type ResponseSegment, type StatusItem, type ThinkingContent, ThinkingSection, type ThinkingSectionProps, type ThinkingStep, type TimelineEntry, type TimelineEntryType, type TimelineUIState, type ToolCall, TruncatedMessage, type TruncatedMessageProps, type UseAgentResponseAccumulatorOptions, type UseAgentResponseAccumulatorReturn, type UseThinkingTimerOptions, UserPrompt, UserPromptInput, type UserPromptInputProps, type UserPromptInputRef, type UserPromptProps, buildResponseString, buildTimelineEntries, createTimelineUIState, deduplicateEntries, formatTime, formatTotalTime, groupIntoAgentRuns, initialAgentResponseState, parseResponseSegments, useAgentResponseAccumulator, useThinkingTimer };