orchid-ai 2.0.3 → 2.1.1

package/README.md

@@ -0,0 +1,304 @@
+# orchid-ai
+
+Shared Orchid AI chat UI and visualization components. A source-distributed React component library — no compilation step; the consuming app's bundler handles JSX.
+
+---
+
+## Publishing
+
+```bash
+npm version patch   # or minor / major
+npm publish
+```
+
+---
+
+## Installation
+
+```bash
+npm install orchid-ai
+```
+
+Import the stylesheet once in your app entry point:
+
+```js
+import 'orchid-ai/orchid-ai.css';
+```
+
+### Peer dependencies
+
+Your app must provide:
+
+```
+react >= 18
+react-dom >= 18
+react-markdown >= 9
+remark-gfm >= 4
+html2canvas >= 1.4   (for chart PNG export)
+```
+
+---
+
+## Quick start
+
+```jsx
+import { ChatWindow, ChatInput, useOrchidAiChat } from 'orchid-ai';
+import 'orchid-ai/orchid-ai.css';
+
+export default function App() {
+  const { messages, loading, statusText, sendMessage } = useOrchidAiChat({
+    endpoint: '/api/ai/chat',
+    buildBody: (userMessage, history) => ({ message: userMessage, history }),
+    getHeaders: () => ({ 'X-CSRF-Token': getCsrfToken() }),
+  });
+
+  return (
+    <div className="ai-chat-container">
+      <ChatWindow
+        messages={messages}
+        loading={loading}
+        statusText={statusText}
+        aiEnabled={true}
+        organisationName="Acme Ltd"
+      />
+      <ChatInput onSend={sendMessage} disabled={loading} />
+    </div>
+  );
+}
+```
+
+---
+
+## `useOrchidAiChat`
+
+```ts
+const { messages, loading, statusText, sendMessage, clearMessages } =
+  useOrchidAiChat(options);
+```
+
+### Options
+
+| Option            | Type                                                             | Default | Description                                                     |
+|-------------------|------------------------------------------------------------------|---------|-----------------------------------------------------------------|
+| `endpoint`        | `string`                                                         | —       | POST URL the hook fetches on each message                       |
+| `buildBody`       | `(userMessage, history, sendOptions?) => object`                 | —       | Builds the JSON request body                                    |
+| `getHeaders`      | `() => Record<string, string>`                                   | —       | Returns extra headers (e.g. CSRF token)                         |
+| `showStatus`      | `boolean`                                                        | `true`  | Set `false` to suppress the live status text entirely           |
+| `initialMessages` | `ChatMessage[]`                                                  | `[]`    | Seed the transcript (e.g. from localStorage)                    |
+
+### Returns
+
+| Key             | Type                                         | Description                                              |
+|-----------------|----------------------------------------------|----------------------------------------------------------|
+| `messages`      | `ChatMessage[]`                              | Full transcript including streaming assistant messages   |
+| `loading`       | `boolean`                                    | True while a request is in flight                        |
+| `statusText`    | `string`                                     | Latest `status` event text (e.g. "Looking up data")      |
+| `sendMessage`   | `(text: string, opts?: SendOptions) => void` | Send a user message                                      |
+| `clearMessages` | `() => void`                                 | Reset the transcript                                     |
+
+### `ChatMessage` shape
+
+```ts
+{
+  role: 'user' | 'assistant';
+  content: string;
+  truncated?: boolean;
+  isStreaming?: boolean;
+  processTrace?: { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed?: boolean };
+  processInterimLive?: string;
+  queryContext?: Record<string, unknown>;
+}
+```
+
+---
+
+## Components
+
+### `<ChatWindow>`
+
+Renders the full message list, empty state, and typing indicator. Wrap it with a `<div className="ai-chat-container">` (sets layout and font).
+
+| Prop                  | Type            | Default              | Description                                                                                        |
+|-----------------------|-----------------|----------------------|----------------------------------------------------------------------------------------------------|
+| `messages`            | `ChatMessage[]` | —                    | From `useOrchidAiChat`                                                                             |
+| `loading`             | `boolean`       | —                    | Shows typing indicator when true and no streaming message is present                               |
+| `statusText`          | `string`        | —                    | Live status shown above the typing indicator                                                       |
+| `aiEnabled`           | `boolean`       | —                    | Shows a disabled state with `unavailableMessage` when false                                        |
+| `appName`             | `string`        | `"Hermes Chat"`      | Used in the disabled state heading and as the PDF export filename prefix                           |
+| `organisationName`    | `string`        | —                    | Shown in the empty-state description ("Ask about ...")                                             |
+| `unavailableMessage`  | `string`        | —                    | Overrides the default "needs an API key" copy when `aiEnabled` is false                            |
+| `emptyDescription`    | `string`        | —                    | Overrides the default empty-state paragraph                                                        |
+| `suggestions`         | `string[]`      | 3 built-in prompts   | Clickable suggestion chips shown in the empty state                                                |
+| `suggestionsDisabled` | `boolean`       | `false`              | Renders suggestion chips as non-interactive (e.g. while loading)                                   |
+| `onSuggestionClick`   | `(text) => void`| —                    | Called when a suggestion chip is clicked                                                           |
+| `showProcessTracePanel`| `boolean`      | `true`               | Set `false` to show statuses inline next to the typing dots instead of in the collapsible panel    |
+| `showQuerySummary`    | `boolean`       | `false`              | Shows a collapsed "Filters used" disclosure on messages that have `queryContext`                    |
+
+### `<ChatInput>`
+
+The text input bar with auto-growing textarea and send button.
+
+| Prop              | Type            | Description                                                           |
+|-------------------|-----------------|-----------------------------------------------------------------------|
+| `onSend`          | `(text) => void`| Called with trimmed text when the user submits                        |
+| `disabled`        | `boolean`       | Disables the textarea and send button                                 |
+| `disabledReason`  | `string`        | When set, shows a clickable overlay and updates the placeholder text  |
+| `onDisabledClick` | `() => void`    | Called when the user taps the disabled overlay                        |
+
+### `<Message>`
+
+Renders a single message bubble. Used internally by `ChatWindow`; import directly if you need a custom layout.
+
+| Prop                   | Type            | Description                                             |
+|------------------------|-----------------|---------------------------------------------------------|
+| `role`                 | `'user' \| 'assistant'` | —                                               |
+| `content`              | `string`        | Markdown for assistant; plain text for user             |
+| `truncated`            | `boolean`       | Shows a cut-off warning                                 |
+| `exportPrefix`         | `string`        | Filename prefix for PDF download (default `orchid-ai`)  |
+| `isStreaming`          | `boolean`       | Enables streaming placeholders for open code fences     |
+| `streamingStatusText`  | `string`        | Status text shown above streaming content               |
+| `processTrace`         | object          | See `ChatMessage.processTrace`                          |
+| `processInterimLive`   | `string`        | Live interim preamble (streaming only)                  |
+| `showProcessTracePanel`| `boolean`       | Default `true`                                          |
+| `queryContext`         | `object`        | Filters to display when `showQuerySummary` is true      |
+| `showQuerySummary`     | `boolean`       | Default `false`                                         |
+
+---
+
+## Server-side: SSE protocol
+
+The hook handles both streaming (`Content-Type: text/event-stream`) and plain JSON responses. For streaming, emit newline-delimited `data:` events:
+
+```
+data: {"type":"status","text":"Looking up data"}\n\n
+data: {"type":"delta","text":"Here are the "}\n\n
+data: {"type":"delta","text":"results..."}\n\n
+data: {"type":"done","response":"Here are the results...","truncated":false}\n\n
+```
+
+### Event types
+
+| `type`   | Required fields              | Optional fields              |
+|----------|------------------------------|------------------------------|
+| `status` | `text: string`               | —                            |
+| `delta`  | `text: string`               | —                            |
+| `done`   | `response: string`           | `truncated: boolean`, `queryContext: object` |
+| `error`  | `error: string`              | —                            |
+
+### Status labels that trigger the Working panel
+
+The collapsible "Working" panel appears when statuses matching these patterns are received:
+
+- `Looking up…`
+- `Found N…`
+- `Searching the web…`
+- `Searching knowledge base…`
+
+The special status `"Compiling response"` (exported as `ORCHID_AI_SSE_STATUS_CLEAR_STREAM`) signals the boundary between interim tool preamble and the final answer — the collector flushes its interim buffer and begins accumulating the reply.
+
+Use the exported constants to keep server and client in sync:
+
+```js
+import { ORCHID_AI_DEFAULT_STATUS, ORCHID_AI_SSE_STATUS_CLEAR_STREAM } from 'orchid-ai';
+
+// ORCHID_AI_DEFAULT_STATUS.thinking        → 'Thinking'
+// ORCHID_AI_DEFAULT_STATUS.lookingUpData   → 'Looking up data'
+// ORCHID_AI_DEFAULT_STATUS.compilingResponse → 'Compiling response'
+// ORCHID_AI_SSE_STATUS_CLEAR_STREAM        → 'Compiling response'
+```
+
+### Query context
+
+Include `queryContext` on the `done` event to let users see what filters the AI applied:
+
+```js
+res.write(`data: ${JSON.stringify({
+  type: 'done',
+  response: finalText,
+  queryContext: {
+    customerId: 123,
+    status: 'active',
+    dateFrom: '2024-01-01',
+  },
+})}\n\n`);
+```
+
+Enable display with `<ChatWindow showQuerySummary={true} />`. Keys are automatically converted from camelCase to Title Case ("customerId" → "Customer ID").
+
+---
+
+## AI response title
+
+The assistant can set the PDF export filename by embedding an HTML comment anywhere in its reply:
+
+```
+<!-- title: Monthly Shipment Summary -->
+```
+
+The comment is stripped from the rendered content and used as the PDF title slug.
+
+---
+
+## Visualizations
+
+The AI embeds charts using a fenced code block with language `orchid-ai-chart` (legacy alias `hemiq-chart` is still parsed):
+
+````
+```orchid-ai-chart
+{
+  "type": "bar_chart",
+  "title": "Shipments by carrier",
+  "bars": [
+    { "label": "FedEx", "value": 42 },
+    { "label": "DHL",   "value": 31 }
+  ]
+}
+```
+````
+
+The `type` field determines which component renders. All supported types:
+
+| `type`              | Component          | Key fields                                                   |
+|---------------------|--------------------|--------------------------------------------------------------|
+| `bar_chart`         | `BarChart`         | `bars: [{ label, value }]`                                   |
+| `line_chart`        | `LineChart`        | `xAxis` (label + categories), `yAxis` (label), `series`     |
+| `stacked_bar_chart` | `StackedBarChart`  | Same as `line_chart`                                         |
+| `grouped_bar_chart` | `GroupedBarChart`  | Same as `line_chart`                                         |
+| `dot_chart`         | `DotChart`         | `series[].points` with numeric `x`, categorical `y`         |
+| `histogram`         | `HistogramChart`   | `bins: [{ start, end, value }]` or `{ range, count }`       |
+| `scatter_plot`      | `ScatterPlot`      | Standard numeric axes + series                               |
+| `stat_cards`        | `StatCards`        | `cards: [{ label, value, unit?, subtitle?, trend? }]`        |
+| `table`             | `DataTable`        | `columns` + `rows`                                           |
+| `timeline`          | `Timeline`         | `items: [{ label, start, end }]` (ISO 8601 dates)            |
+
+Charts are downloadable as PNG (via `html2canvas`). Each chart block is validated against its schema on render — invalid JSON or schema errors show an error card instead of crashing.
+
+### System prompt constant
+
+Import `ORCHID_AI_VISUALIZATION_INSTRUCTIONS` to inject the chart format instructions into your AI system prompt:
+
+```js
+import { ORCHID_AI_VISUALIZATION_INSTRUCTIONS } from 'orchid-ai';
+
+const systemPrompt = `You are a helpful assistant. ${ORCHID_AI_VISUALIZATION_INSTRUCTIONS}`;
+```
+
+---
+
+## Using visualization components standalone
+
+Each chart component can be used outside the chat context:
+
+```jsx
+import { BarChart } from 'orchid-ai';
+import 'orchid-ai/orchid-ai.css';
+
+<BarChart chart={{
+  type: 'bar_chart',
+  title: 'Revenue by month',
+  bars: [
+    { label: 'Jan', value: 120000 },
+    { label: 'Feb', value: 98000 },
+  ],
+}} />
+```

package/orchid-ai.css

@@ -2048,6 +2048,141 @@
   color: #b45309;
 }
 
+/* ── Query Summary ── */
+
+.ai-chat-query-summary {
+  margin-top: 10px;
+  border-radius: 7px;
+  border: 1px solid #e5e7eb;
+  background: #f9fafb;
+  font-size: 12px;
+}
+
+.ai-chat-query-summary__summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 6px 10px;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+  list-style: none;
+  color: #6b7280;
+  gap: 8px;
+}
+
+.ai-chat-query-summary__summary::-webkit-details-marker {
+  display: none;
+}
+
+.ai-chat-query-summary__summary:hover {
+  color: #374151;
+}
+
+.ai-chat-query-summary__label {
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.ai-chat-query-summary__chevron {
+  font-size: 10px;
+  transition: transform 0.15s;
+  flex-shrink: 0;
+}
+
+.ai-chat-query-summary[open] .ai-chat-query-summary__chevron {
+  transform: rotate(90deg);
+}
+
+.ai-chat-query-summary__list {
+  list-style: none;
+  margin: 0;
+  padding: 4px 10px 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.ai-chat-query-summary__item {
+  display: flex;
+  gap: 6px;
+  align-items: baseline;
+  line-height: 1.5;
+}
+
+.ai-chat-query-summary__key {
+  color: #6b7280;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.ai-chat-query-summary__key::after {
+  content: ':';
+}
+
+.ai-chat-query-summary__value {
+  color: #374151;
+  word-break: break-word;
+}
+
+/* ── Query sub-step (nested under a tool status row) ── */
+
+.ai-chat-process-trace__step--query {
+  padding-left: 16px;
+}
+
+.ai-chat-process-trace__step--query .ai-chat-process-trace__rail {
+  opacity: 0.4;
+}
+
+.ai-chat-process-trace__step--query .ai-chat-process-trace__dot {
+  width: 6px;
+  height: 6px;
+  background: var(--ai-process-dot, #9aa5b1);
+}
+
+.ai-chat-process-trace__query-collection {
+  display: block;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--ai-process-text, #5c6570);
+  margin-bottom: 4px;
+}
+
+.ai-chat-process-trace__query-params {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 1px 10px;
+  margin: 0;
+}
+
+.ai-chat-process-trace__query-param {
+  display: contents;
+  font-size: 11.5px;
+  line-height: 1.5;
+}
+
+.ai-chat-process-trace__query-param dt {
+  color: var(--ai-process-text, #5c6570);
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+.ai-chat-process-trace__query-param dt::after {
+  content: ":";
+}
+
+.ai-chat-process-trace__query-param dd {
+  color: var(--ai-process-text-strong, #2d3748);
+  margin: 0;
+  word-break: break-word;
+}
+
 /* ── Message Actions ── */
 
 .ai-chat-message-actions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchid-ai",
-  "version": "2.0.3",
+  "version": "2.1.1",
   "description": "Shared Orchid AI chat UI and visualization components",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/components/ChatWindow.jsx

@@ -23,6 +23,7 @@ export default function ChatWindow({
   suggestions = DEFAULT_SUGGESTIONS,
   suggestionsDisabled = false,
   showProcessTracePanel = true,
+  showQuerySummary = false,
 }) {
   const exportPrefix = appName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
   const bottomRef = useRef(null);
@@ -123,6 +124,8 @@ export default function ChatWindow({
             processTrace={msg.processTrace}
             processInterimLive={msg.processInterimLive}
             showProcessTracePanel={showProcessTracePanel}
+            queryContext={msg.queryContext}
+            showQuerySummary={showQuerySummary}
           />
         );
       })}

package/src/components/Message.jsx

@@ -46,6 +46,53 @@ function getBlockLabel(lang) {
   return `Generating ${lang}`;
 }
 
+const UPPER_ABBREV = new Set(['id', 'url', 'api', 'uuid', 'ip', 'sku', 'po', 'eta', 'ref']);
+
+function camelToTitleCase(str) {
+  const words = String(str)
+    .replace(/_/g, ' ')
+    .replace(/([A-Z])/g, ' $1')
+    .trim()
+    .split(/\s+/);
+  return words
+    .map((w) => {
+      const lower = w.toLowerCase();
+      if (UPPER_ABBREV.has(lower)) return lower.toUpperCase();
+      return lower.charAt(0).toUpperCase() + lower.slice(1);
+    })
+    .join(' ');
+}
+
+function formatQueryValue(value) {
+  if (Array.isArray(value)) return value.map(String).join(', ');
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  return String(value);
+}
+
+function QuerySummaryPanel({ queryContext }) {
+  if (!queryContext || typeof queryContext !== 'object' || Array.isArray(queryContext)) return null;
+  const entries = Object.entries(queryContext).filter(
+    ([, v]) => v !== null && v !== undefined && v !== ''
+  );
+  if (!entries.length) return null;
+  return (
+    <details className="ai-chat-query-summary">
+      <summary className="ai-chat-query-summary__summary">
+        <span className="ai-chat-query-summary__label">Filters used</span>
+        <span className="ai-chat-query-summary__chevron" aria-hidden>▸</span>
+      </summary>
+      <ul className="ai-chat-query-summary__list">
+        {entries.map(([key, value]) => (
+          <li key={key} className="ai-chat-query-summary__item">
+            <span className="ai-chat-query-summary__key">{camelToTitleCase(key)}</span>
+            <span className="ai-chat-query-summary__value">{formatQueryValue(value)}</span>
+          </li>
+        ))}
+      </ul>
+    </details>
+  );
+}
+
 const TITLE_COMMENT_RE = /<!--\s*title:\s*([^-][^>]*?)\s*-->/gi;
 
 /** Prefer the last `<!--title:...-->` so end-of-reply titles work; still removes legacy start-of-reply comments. */
@@ -100,6 +147,37 @@ function UserBubbleContent({ content }) {
   ));
 }
 
+function formatToolName(tool) {
+  return String(tool)
+    .replace(/^(query_|get_)/, '')
+    .replace(/_/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function QueryStep({ entry }) {
+  const params = Object.entries(entry.input || {}).filter(([, v]) => v !== null && v !== undefined && v !== '');
+  return (
+    <li className="ai-chat-process-trace__step ai-chat-process-trace__step--query">
+      <div className="ai-chat-process-trace__rail" aria-hidden>
+        <span className="ai-chat-process-trace__dot" />
+      </div>
+      <div className="ai-chat-process-trace__body">
+        <span className="ai-chat-process-trace__query-collection">{formatToolName(entry.tool)}</span>
+        {params.length > 0 && (
+          <dl className="ai-chat-process-trace__query-params">
+            {params.map(([key, value]) => (
+              <div key={key} className="ai-chat-process-trace__query-param">
+                <dt>{camelToTitleCase(key)}</dt>
+                <dd>{formatQueryValue(value)}</dd>
+              </div>
+            ))}
+          </dl>
+        )}
+      </div>
+    </li>
+  );
+}
+
 function ProcessTracePanel({ processTrace, processInterimLive, isStreaming, showProcessTracePanel }) {
   if (showProcessTracePanel === false) return null;
 
@@ -140,6 +218,9 @@ function ProcessTracePanel({ processTrace, processInterimLive, isStreaming, show
       <div className="ai-chat-process-trace__panel">
         <ul className="ai-chat-process-trace__timeline">
           {items.map((entry, i) => {
+            if (entry.type === 'query') {
+              return <QueryStep key={i} entry={entry} />;
+            }
             const lane = orchidAiProcessTraceEntryKind(entry);
             const isLiveStatus = isStreaming && !processInterimLive && i === items.length - 1 && entry.type === "status";
             return (
@@ -154,9 +235,7 @@ function ProcessTracePanel({ processTrace, processInterimLive, isStreaming, show
                   {entry.type === "status" ? (
                     <span className="ai-chat-process-trace__line">{entry.value}</span>
                   ) : (
-                    <div className="ai-chat-process-trace__prose">
-                      {entry.value}
-                    </div>
+                    <div className="ai-chat-process-trace__prose">{entry.value}</div>
                   )}
                 </div>
               </li>

package/src/hooks/useOrchidAiChat.js

@@ -127,6 +127,9 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
                     isClearStream: orchidAiStatusClearsStreamBuffer(event.text),
                   });
                   patchStreamingAssistant();
+                } else if (event.type === 'query') {
+                  collector.onQuery(event.tool, event.input);
+                  patchStreamingAssistant();
                 } else if (event.type === 'delta') {
                   collector.onDelta(event.text);
                   patchStreamingAssistant();
@@ -144,6 +147,7 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
                       content: event.response,
                       truncated: event.truncated === true,
                       ...(trace ? { processTrace: trace } : {}),
+                      ...(event.queryContext ? { queryContext: event.queryContext } : {}),
                     };
                     if (last?.role === 'assistant' && last?.isStreaming) {
                       next[next.length - 1] = finalMsg;
@@ -175,7 +179,12 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
         } else {
           const data = await response.json();
           if (response.ok) {
-            addMessage({ role: 'assistant', content: data.response, truncated: data.truncated });
+            addMessage({
+              role: 'assistant',
+              content: data.response,
+              truncated: data.truncated,
+              ...(data.queryContext ? { queryContext: data.queryContext } : {}),
+            });
           } else {
             addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
           }

package/src/index.d.ts

@@ -15,6 +15,12 @@ export interface ChatMessage {
   };
   /** Live tool preamble not yet flushed into processTrace.items (streaming only). */
   processInterimLive?: string;
+  /**
+   * Filters/parameters the AI used to query the database. Sent by the server in the
+   * `done` SSE event or JSON response as `queryContext`. Displayed when `showQuerySummary`
+   * is true on ChatWindow or Message.
+   */
+  queryContext?: Record<string, unknown>;
 }
 
 export interface ChatWindowProps {
@@ -26,6 +32,12 @@ export interface ChatWindowProps {
   organisationName?: string;
   /** When false, tool/interim statuses show inline next to typing dots (Hermes / iLink config). */
   showProcessTracePanel?: boolean;
+  /**
+   * When true, shows a collapsed "Filters used" disclosure under each assistant message
+   * that has a `queryContext`. Helps users understand why the AI returned specific data.
+   * Defaults to false.
+   */
+  showQuerySummary?: boolean;
   /** Any extra props are forwarded to the root element */
   [key: string]: unknown;
 }
@@ -49,6 +61,8 @@ export interface MessageProps {
   processTrace?: ChatMessage['processTrace'];
   processInterimLive?: string;
   showProcessTracePanel?: boolean;
+  queryContext?: Record<string, unknown>;
+  showQuerySummary?: boolean;
 }
 
 export const ChatWindow: React.FC<ChatWindowProps>;
@@ -159,27 +173,32 @@ export function orchidAiProcessTraceEntryKind(entry: {
   value: string;
 }): 'text' | 'tool' | 'compile' | 'mind';
 
+export type OrchidAiProcessTraceItem =
+  | { type: 'status' | 'text'; value: string }
+  | { type: 'query'; tool: string; input: Record<string, unknown> };
+
 export function createOrchidAiProcessTraceCollector(): {
+  onQuery(tool: string, input: Record<string, unknown>): void;
   onStatus(text: string, opts?: { isClearStream?: boolean }): void;
   onDelta(text: string): void;
   getLiveMain(): string;
   getLiveInterim(): string;
-  getItems(): Array<{ type: 'status' | 'text'; value: string }>;
+  getItems(): Array<OrchidAiProcessTraceItem>;
   reset(): void;
   buildPersistedTrace():
-    | { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean }
+    | { items: Array<OrchidAiProcessTraceItem>; defaultCollapsed: boolean }
     | undefined;
 };
 
 export function snapshotOrchidAiProcessTraceItems(
   collector: ReturnType<typeof createOrchidAiProcessTraceCollector>
-): { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean };
+): { items: Array<OrchidAiProcessTraceItem>; defaultCollapsed: boolean };
 
 export function augmentLiveProcessTraceSnapshot(
-  trace: { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean },
+  trace: { items: Array<OrchidAiProcessTraceItem>; defaultCollapsed: boolean },
   streamingMain: string,
   liveInterim?: string
-): { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean };
+): { items: Array<OrchidAiProcessTraceItem>; defaultCollapsed: boolean };
 
 export function orchidAiProcessTraceHasDisplayableContent(
   trace: ChatMessage['processTrace'] | undefined,

package/src/orchidAiProcessTrace.js

@@ -50,6 +50,13 @@ export function createOrchidAiProcessTraceCollector() {
   }
 
   return {
+    /**
+     * @param {string} tool - tool name e.g. "query_orders"
+     * @param {Record<string, unknown>} input - raw tool input parameters
+     */
+    onQuery(tool, input) {
+      items.push({ type: 'query', tool: String(tool), input: input || {} });
+    },
     /**
      * @param {string} text
      * @param {{ isClearStream?: boolean }} [opts] — true for {@link ORCHID_AI_SSE_STATUS_CLEAR_STREAM}
@@ -98,18 +105,23 @@ export function createOrchidAiProcessTraceCollector() {
     buildPersistedTrace() {
       if (!items.length) return undefined;
       return {
-        items: items.map((x) => ({ type: x.type, value: x.value })),
+        items: items.map(serializeTraceItem),
         defaultCollapsed: true,
       };
     },
   };
 }
 
+function serializeTraceItem(x) {
+  if (x.type === 'query') return { type: 'query', tool: x.tool, input: x.input };
+  return { type: x.type, value: x.value };
+}
+
 /** Snapshot `items` for React state / persisted shape (live streaming; not collapsed). */
 export function snapshotOrchidAiProcessTraceItems(collector) {
   const items = collector.getItems();
   return {
-    items: items.map((x) => ({ type: x.type, value: x.value })),
+    items: items.map(serializeTraceItem),
     defaultCollapsed: false,
   };
 }