@filigran/chatbot 3.5.2 → 3.6.1

package/README.md

@@ -5,6 +5,8 @@ Filigran chat panel — a standalone React + Tailwind chatbot component with SSE
 ## Features
 
 - 🔄 **SSE Message Streaming** — Real-time response streaming with status indicators
+- ⚡ **Mid-Run Steering** — Send messages while the agent is generating; they are injected into the running agentic loop instead of waiting for the turn to finish
+- 🗂️ **Conversation History** — Switch between (and delete) past conversations from a history menu in the header
 - 🤖 **Multi-Agent Support** — Switch between different AI agents
 - 📎 **File Attachments** — Upload and paste files (PDF, TXT, images)
 - 📥 **Agent-Generated Files** — Renders downloadable file cards from agent output and strips the `[[FILE:id]]` markers from the prose
@@ -192,6 +194,37 @@ even though streaming downloads work:
 }
 ```
 
+### `GET {apiBaseUrl}/chat/sessions`
+
+Lists the user's past conversations for the history menu in the chat header.
+
+**Response** (a bare array or `{ "conversations": [...] }`):
+
+```json
+[
+  {
+    "conversation_id": "uuid-here",
+    "title": "What is the weather?",
+    "updated_at": "2026-06-10T08:30:00Z",
+    "message_count": 12
+  }
+]
+```
+
+Selecting a conversation restores it through the existing
+`POST /chat/sessions` contract above. The endpoint is fetched lazily when the
+history menu opens; a backend that doesn't implement it yet (404/405) simply
+yields an empty list, so the menu shows its empty state instead of breaking
+the chat. Set `apiEndpoints.history` to `null` to hide the history menu
+entirely, or point it at a dedicated path if your proxy can't route `GET` on
+the sessions path.
+
+### `DELETE {apiBaseUrl}/chat/sessions/{conversation_id}`
+
+Deletes a conversation from the history menu. Any 2xx response counts as
+success; deleting the active conversation resets the panel to a fresh chat so
+the next message never targets a dead conversation id.
+
 ### `POST {apiBaseUrl}/chat/messages`
 
 Sends a message and streams the response via SSE.
@@ -223,9 +256,40 @@ data: {"type": "status", "status": "analyzing"}
 data: {"type": "status", "status": "streaming"}
 data: {"type": "stream", "content": "The weather "}
 data: {"type": "stream", "content": "today is sunny."}
-data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1}
+data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1, "reasoning": "Let me check the weather data first.", "tool_call_trace": [{"name": "search_web", "input": "{\"query\": \"weather\"}", "output": "Sunny, 24C", "success": true}], "transfer_chain": [{"agent_id": "uuid", "agent_name": "General"}], "is_truncated": false}
 ```
 
+The optional `reasoning` field on `done` (and on restored session messages)
+carries the accumulated model reasoning / pre-tool preamble prose for the
+turn. When present it is surfaced in the per-message reasoning-details dialog
+(the "i" button), mirroring the XTM One web chat.
+
+The reasoning-details dialog also consumes three more optional `done` fields
+(all parsed defensively — older backends without them fall back to the flat
+tool-name list and the plain "i" affordance):
+
+- `tool_call_trace` — array of `{ name, input, output, success }` entries
+  rendered as expandable rows (numbered, success/failure icon, pretty-printed
+  JSON input, output)
+- `transfer_chain` — array of `{ agent_id, agent_name }` hops rendered as the
+  agent transfer chain
+- `is_truncated` — `true` when the agent's iteration budget was exhausted;
+  the message then shows an always-visible amber warning triangle instead of
+  the hover-only "i" and the dialog opens with a "Turn limit reached" banner
+
+The same fields are read from restored session messages, so the dialog
+survives a page reload.
+
+#### Internal links
+
+Assistant markdown links are routed through `onRelativeLinkClick` when they
+are **internal to the host application**: relative hrefs (`/dashboard/...`)
+and absolute http(s) hrefs on the **same origin** as the embedding page
+(backends emit absolute links so they work from any chat surface — when the
+chatbot is embedded in that very platform, e.g. the OpenCTI link inside
+OpenCTI, the link is reduced to `pathname + search + hash` and navigates
+in-app instead of opening a new tab). All other links open in a new tab.
+
 #### Agent-generated file attachments
 
 When an agent produces a downloadable file, the `done` event carries an `attachments` array and the streamed prose embeds `[[FILE:<file_id>]]` markers. The component strips those markers and renders a download card per attachment:
@@ -257,9 +321,11 @@ Download failures (403/404/5xx/network) are reported through the optional `onDow
 
 - `thinking` — Agent is processing
 - `tool_start` — Agent is using tools (with `tools` array)
+- `tool_heartbeat` — Liveness signal during a long tool execution (with `tools` and `elapsed_s`). The widget keeps the current status label and renders a live elapsed-time indicator next to it once the execution exceeds ~15 s, so long operations (background tasks, agent consults) never look stuck
 - `analyzing` — Agent is analyzing tool results
 - `composing` — Agent is composing the response
 - `streaming` — Content is being streamed
+- `steering` — A mid-run steering message is being incorporated (see below)
 
 **Error event:**
 
@@ -267,6 +333,51 @@ Download failures (403/404/5xx/network) are reported through the optional `onDow
 data: {"type": "error", "content": "Something went wrong"}
 ```
 
+### `POST {apiBaseUrl}/chat/messages/steer`
+
+Steers the agent mid-run: while a response is still streaming, Enter / the
+accent Send button dispatches the typed text immediately instead of blocking
+until the turn finishes. The widget POSTs:
+
+```json
+{
+  "conversation_id": "uuid-here",
+  "content": "Actually, filter by subregion instead",
+  "agent_slug": "general"
+}
+```
+
+A 2xx response means the message was persisted and will be injected into the
+running agentic loop at the next iteration boundary. On a non-2xx response or
+a network error the optimistic user bubble is rolled back and the text is
+restored into the composer (prepended on its own line if the user already
+typed something new) — so a backend without steering support degrades
+gracefully and the message is never silently lost. Set `apiEndpoints.steer`
+to `null` to disable the steering affordances entirely.
+
+Steering only applies to text-only sends on the `rest` backend with a known
+`conversation_id` (the first turn of a fresh conversation only receives its id
+on `done`). Sends with attachments keep the legacy wait behavior. Esc stops
+generating.
+
+#### Multi-segment responses
+
+A steered turn can produce **multiple response segments** on one SSE stream:
+when the steering message arrives too late to be folded into the current
+pass, the backend completes the current segment (an intermediate `done`
+event) and then runs a follow-up pass for the steering message (a fresh
+`thinking` status followed by more `stream` events and a final `done`). The
+widget renders each segment as its own assistant message:
+
+```
+data: {"type": "status", "status": "steering"}
+data: {"type": "stream", "content": "...current answer keeps streaming..."}
+data: {"type": "done", "content": "First segment answer", "conversation_id": "uuid"}
+data: {"type": "status", "status": "thinking"}
+data: {"type": "stream", "content": "Follow-up answer to the steering message"}
+data: {"type": "done", "content": "Follow-up answer to the steering message", "conversation_id": "uuid"}
+```
+
 ## Customization
 
 ### Custom Logo
@@ -321,15 +432,33 @@ function App() {
 - `'Using tools…'`
 - `'Analyzing results…'`
 - `'Composing answer…'`
+- `'Incorporating your message…'`
 - `'Ask a question...'`
 - `'Stop generating'`
+- `'Send now'`
+- `'Enter to send now · Esc to stop'`
+- `'Attachments wait for the current response'`
 - `'New chat'`
+- `'Conversation history'`
+- `'No conversations yet'`
+- `'Untitled conversation'`
+- `'New conversation'`
+- `'Delete conversation'`
+- `'just now'` / `'m ago'` / `'h ago'` / `'d ago'`
 - `'Switch view'`
 - `'Close'`
 - `'Switch to another agent'`
 - `'Browse agents'`
 - `'Create agent'`
 - `'Reasoning details'`
+- `'Reasoning details — turn limit reached'`
+- `'Model reasoning'`
+- `'iterations'`
+- `'transfer'` / `'transfers'`
+- `'Transfer chain'`
+- `'Turn limit reached.'`
+- `"The agent's iteration budget was exhausted - execution stopped before completing all planned steps. The final response is a best-effort summary of work done so far."`
+- `'Input'` / `'Output'` / `'(no output)'`
 - `'Download'`
 - `'tool call'` / `'tool calls'`
 - `'Uses AI. Verify results.'`

package/dist/index.d.ts

@@ -12,10 +12,29 @@ interface ApiEndpoints {
     singleEndpoint?: boolean;
     /** Path for sending messages. Default: '/chat/messages' */
     messages?: string;
+    /**
+     * Path for steering the agent mid-run (sending a message while a response
+     * is still streaming). Default: '/chat/messages/steer'. The widget POSTs
+     * `{ conversation_id, content, agent_slug }`; a 2xx response means the
+     * message was persisted and will be injected into the running agentic loop
+     * at the next iteration boundary. On a non-2xx response the optimistic
+     * bubble is rolled back and the text is restored into the composer, so a
+     * backend without steering support degrades gracefully. Set to null to
+     * disable mid-run steering entirely.
+     */
+    steer?: string | null;
     /** Path for fetching agents. Default: '/chat/agents'. Set to null to disable. */
     agents?: string | null;
     /** Path for fetching session history. Default: '/chat/sessions'. Set to null to disable. */
     sessions?: string | null;
+    /**
+     * Path for the multi-conversation history menu. Defaults to the sessions
+     * path: the widget lists past conversations via `GET {history}` and deletes
+     * one via `DELETE {history}/{conversation_id}`. Set to null to hide the
+     * history menu (e.g. when the backend only implements the session-restore
+     * POST contract).
+     */
+    history?: string | null;
     /** Path for uploading files. Default: '/chat/upload'. Set to null to disable file uploads. */
     upload?: string | null;
     /**
@@ -128,6 +147,39 @@ interface ChatMessage {
     toolNames?: string[];
     toolCallCount?: number;
     iterations?: number;
+    /**
+     * Accumulated model reasoning / pre-tool preamble prose for the turn
+     * (from `thinking_text` events), surfaced in the reasoning-details dialog
+     * after the answer completes — mirroring the XTM One web chat.
+     */
+    reasoning?: string;
+    /**
+     * Per-tool-call execution trace (name, input, output, success) for the
+     * reasoning-details dialog — same shape the XTM One web chat renders as
+     * expandable rows. Optional: backends without trace support fall back to
+     * the flat `toolNames` list.
+     */
+    toolCallTrace?: ToolCallTraceEntry[];
+    /** Agent transfer chain for the turn (reasoning-details dialog). */
+    transferChain?: TransferChainEntry[];
+    /**
+     * True when the agent's iteration budget was exhausted and the final
+     * response is a best-effort summary — surfaced as an amber warning on the
+     * reasoning-details affordance, mirroring the XTM One web chat.
+     */
+    isTruncated?: boolean;
+}
+/** One tool call in the reasoning-details execution trace. */
+interface ToolCallTraceEntry {
+    name: string;
+    input?: string;
+    output?: string;
+    success: boolean;
+}
+/** One hop in the agent transfer chain shown in the reasoning-details dialog. */
+interface TransferChainEntry {
+    agentId: string;
+    agentName: string;
 }
 /**
  * An agent-generated file produced during a chat turn (via the backend
@@ -162,6 +214,19 @@ interface ChatFile {
     /** Upload status: 'pending' while uploading, 'done' when uploaded, 'error' on failure. */
     uploadStatus?: 'pending' | 'done' | 'error';
 }
+/**
+ * A past conversation surfaced in the history menu (REST backend only).
+ * Listed via `GET {apiBaseUrl}{apiEndpoints.history ?? apiEndpoints.sessions ?? '/chat/sessions'}`
+ * — the optional `apiEndpoints.history` override takes precedence when the
+ * proxy cannot route GET/DELETE on the sessions path.
+ */
+interface ChatConversationSummary {
+    conversationId: string;
+    title: string;
+    /** ISO timestamp of the last activity, used for the relative-time label. */
+    updatedAt?: string;
+    messageCount?: number;
+}
 interface XtmAgent {
     id: string;
     name: string;
@@ -180,4 +245,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatAttachment, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatToggleButtonProps, TransferredAgent, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatAttachment, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatToggleButtonProps, TransferredAgent, XtmAgent };