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

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

@@ -0,0 +1,270 @@
+/**
+ * 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;
+  /** Timeout in seconds. When omitted, no countdown is shown and the panel never times out. */
+  timeoutSeconds?: number;
+  receivedAt: number;
+}
+
+export 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;
+}
+
+export 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.
+ */
+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 hasTimeout = question.timeoutSeconds != null;
+  const [secondsLeft, setSecondsLeft] = useState(() =>
+    hasTimeout
+      ? Math.max(
+          0,
+          Math.round(
+            question.timeoutSeconds! - (Date.now() - question.receivedAt) / 1000
+          )
+        )
+      : Infinity
+  );
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Focus the textarea on mount
+  useEffect(() => {
+    textareaRef.current?.focus();
+  }, []);
+
+  // Countdown timer (only when timeoutSeconds is provided)
+  useEffect(() => {
+    if (!hasTimeout) return;
+    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);
+  }, [hasTimeout, question.timeoutSeconds, question.receivedAt]);
+
+  const timedOut = hasTimeout && 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, { selectedOptions, freeformText });
+  }, [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>
+        {hasTimeout && (
+          <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, HITLResponseData } from "./HITLQuestionPanel";
+export { buildResponseString } from "./HITLQuestionPanel";
+
+// Interaction record (read-only history display)
+export { HITLInteractionRecord } from "./HITLInteractionRecord";
+export type {
+  HITLInteractionRecordProps,
+  HITLInteraction,
+} from "./HITLInteractionRecord";

package/src/components/inline-actions/ActionMarkdownRenderer.tsx

@@ -0,0 +1,60 @@
+import { useMemo } from "react";
+import { parseResponseSegments } from "./parseResponseSegments";
+import type { ActionMarkdownRendererProps } from "./types";
+
+/**
+ * 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.
+ */
+export function ActionMarkdownRenderer({
+  content,
+  registry,
+  renderMarkdown,
+  onAction,
+  isLatest,
+}: ActionMarkdownRendererProps) {
+  const segments = useMemo(() => parseResponseSegments(content), [content]);
+
+  // If no action blocks found, render as plain markdown (skip extra wrapper divs)
+  if (segments.length === 1 && segments[0].kind === "markdown") {
+    return <>{renderMarkdown(segments[0].content)}</>;
+  }
+
+  return (
+    <>
+      {segments.map((segment, index) => {
+        if (segment.kind === "markdown") {
+          return <div key={`md-${index}`}>{renderMarkdown(segment.content)}</div>;
+        }
+
+        // Action segment — look up registered component
+        const Component = registry[segment.actionType];
+        if (!Component) {
+          // Fallback: render raw JSON as a styled code block
+          return (
+            <pre
+              key={`action-fallback-${index}`}
+              className="my-4 p-4 rounded-lg border border-border bg-muted text-sm font-mono overflow-x-auto"
+            >
+              <code>{JSON.stringify(segment.payload, null, 2)}</code>
+            </pre>
+          );
+        }
+
+        return (
+          <Component
+            key={`action-${segment.actionType}-${index}`}
+            payload={segment.payload}
+            onAction={onAction}
+            isLatest={isLatest}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/components/inline-actions/index.ts

@@ -0,0 +1,18 @@
+// Components
+export { ActionMarkdownRenderer } from "./ActionMarkdownRenderer";
+
+// Parser
+export { parseResponseSegments } from "./parseResponseSegments";
+
+// Types
+export type {
+  ResponseSegment,
+  MarkdownSegment,
+  ActionSegment,
+  InlineActionProps,
+  ActionComponentRegistry,
+  ActionMarkdownRendererProps,
+} from "./types";
+
+// Prompt template
+export { INLINE_ACTION_PROMPT } from "./prompts";

package/src/components/inline-actions/parseResponseSegments.ts

@@ -0,0 +1,66 @@
+import type { ResponseSegment } from "./types";
+
+/**
+ * Regex to match ```json:action fenced code blocks.
+ * Captures the JSON content between the fences.
+ */
+const ACTION_BLOCK_REGEX = /```json:action\s*\n([\s\S]*?)```/g;
+
+/**
+ * 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.
+ */
+export function parseResponseSegments(text: string): ResponseSegment[] {
+  if (!text) return [];
+
+  const segments: ResponseSegment[] = [];
+  let lastIndex = 0;
+
+  // Reset regex state (global regexes are stateful)
+  ACTION_BLOCK_REGEX.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = ACTION_BLOCK_REGEX.exec(text)) !== null) {
+    // Add markdown segment for text before this match
+    const before = text.slice(lastIndex, match.index);
+    if (before.trim()) {
+      segments.push({ kind: "markdown", content: before });
+    }
+
+    // Try to parse the JSON content
+    const jsonContent = match[1].trim();
+    let parsed: Record<string, unknown> | null = null;
+    try {
+      parsed = JSON.parse(jsonContent);
+    } catch {
+      // Malformed JSON — fall back to markdown
+    }
+
+    if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+      segments.push({
+        kind: "action",
+        actionType: parsed.type as string,
+        payload: parsed,
+      });
+    } else {
+      // Missing "type" field or invalid JSON — render as raw code block
+      const rawBlock = match[0];
+      segments.push({ kind: "markdown", content: rawBlock });
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add trailing markdown segment
+  const trailing = text.slice(lastIndex);
+  if (trailing.trim()) {
+    segments.push({ kind: "markdown", content: trailing });
+  }
+
+  return segments;
+}

package/src/components/inline-actions/prompts.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export const INLINE_ACTION_PROMPT = `
+<inline_actions>
+When your response should include interactive components (like query viewers,
+data tables, or executable actions), embed them as fenced code blocks using
+the \`json:action\` language tag:
+
+\`\`\`json:action
+{
+  "type": "action-type-here",
+  ...action-specific fields
+}
+\`\`\`
+
+Rules:
+- Each block must contain valid JSON with a "type" field.
+- The "type" must match a registered action component on the frontend.
+- Multiple action blocks per response are allowed.
+- Surround action blocks with normal markdown text for user context.
+- The action block is rendered as an interactive component in the chat UI.
+- SQL strings inside JSON must be properly escaped (newlines as \\n, quotes as \\").
+
+Available action types:
+
+- "optimap-query": Displays SQL queries with a button to execute them and
+  update the 3D globe map.
+  Required fields:
+    - type: "optimap-query"
+    - locations_sql: string (the validated locations SQL query)
+    - routes_sql: string (the validated routes SQL query)
+    - database_name: string (the target database name)
+</inline_actions>
+`;

package/src/components/inline-actions/types.ts

@@ -0,0 +1,57 @@
+import type { ReactNode, ComponentType } from "react";
+
+// --- Segment types (output of parser) ---
+
+export interface MarkdownSegment {
+  kind: "markdown";
+  content: string;
+}
+
+export interface ActionSegment {
+  kind: "action";
+  actionType: string;
+  payload: Record<string, unknown>;
+}
+
+export type ResponseSegment = MarkdownSegment | ActionSegment;
+
+// --- Component props ---
+
+/**
+ * Props passed to every inline action component.
+ * T is the shape of the payload for this specific action type.
+ */
+export 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;
+}
+
+// --- Registry ---
+
+/**
+ * Maps action type strings to React components that render them.
+ * The consuming page owns this registry.
+ */
+export type ActionComponentRegistry = Record<
+  string,
+  ComponentType<InlineActionProps<any>>
+>;
+
+// --- Renderer props ---
+
+export 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;
+}

package/src/components/user-prompt/UserPrompt.tsx

@@ -0,0 +1,60 @@
+import * as React from "react";
+import { cn } from "@optilogic/core";
+
+export 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"
+ * />
+ * ```
+ */
+export const UserPrompt = React.forwardRef<HTMLDivElement, UserPromptProps>(
+  ({ content, timestamp, className, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "w-fit max-w-[80%] rounded-lg px-4 pt-3.5 pb-3",
+          "bg-secondary text-secondary-foreground",
+          className
+        )}
+        {...props}
+      >
+        <p className="whitespace-pre-wrap">{content}</p>
+        {timestamp && (
+          <p className="text-xs text-secondary-foreground/70 mt-1">
+            {timestamp.toLocaleTimeString([], {
+              hour: "2-digit",
+              minute: "2-digit",
+            })}
+          </p>
+        )}
+      </div>
+    );
+  }
+);
+
+UserPrompt.displayName = "UserPrompt";

package/src/components/user-prompt/index.ts

@@ -0,0 +1 @@
+export { UserPrompt, type UserPromptProps } from "./UserPrompt";