@flamingo-stack/openframe-frontend-core 0.0.479 → 0.0.480

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.479",
+  "version": "0.0.480",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/chat-message-enhanced.tsx

@@ -548,6 +548,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                       key={index}
                       message={segment.data}
                       assistantType={assistantType}
+                      variant={approvalVariant}
                     />
                   )
                 } else if (segment.type === 'approval_request') {

package/src/components/chat/hooks/use-nats-chat-adapter.ts

@@ -586,6 +586,7 @@ export function applyToolExecutionToMessages(
           data: {
             ...toolData,
             toolTitle: toolData.toolTitle ?? seg.data.toolTitle,
+            toolExplanation: toolData.toolExplanation ?? seg.data.toolExplanation,
             parameters: toolData.parameters || seg.data.parameters,
           },
         }

package/src/components/chat/tool-execution-display.tsx

@@ -15,24 +15,47 @@ import type { ToolExecutionDisplayProps } from "./types"
 const COMMAND_BODY_KEYS = new Set<string>(COMMAND_BODY_ARG_KEYS)
 
 const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProps>(
-  ({ className, message, assistantType, ...props }, ref) => {
+  ({ className, message, assistantType, variant = "admin", ...props }, ref) => {
     const [expanded, setExpanded] = useState(false)
     const { innerRef, containerStyle } = useCollapsible({ expanded })
     const isClient = assistantType === "fae"
+    // Render audience (consumer-declared, NOT `assistantType`). The end-client
+    // Fae app (`'client'`) gets a static, non-expandable row — just the
+    // explanation + status; the command/args/result are admin-only detail the
+    // end user doesn't need. Every admin surface keeps the expandable accordion.
+    const isClientView = variant === "client"
 
     const isExecuting = message.type === "EXECUTING_TOOL"
     const isExecuted = message.type === "EXECUTED_TOOL"
     const integratedToolType = (message.integratedToolType as ToolType) || ("OPENFRAME" as ToolType)
 
-    // Header always shows the BE-provided `title` verbatim — no command/name fallback.
-    const previewText = message.toolTitle
+    // Header text depends on the render audience (the consumer-declared
+    // `variant`, NOT `assistantType`: a ticket's Fae client tab on the admin
+    // dashboard is still `assistantType === 'fae'`). The end-client Fae app
+    // (`variant === 'client'`) reads the human-readable explanation (what/why);
+    // every admin surface reads the concise BE-provided title. Each falls back
+    // to the other when its preferred field is absent (older backends /
+    // EXECUTED rows).
+    const previewText =
+      variant === "client"
+        ? message.toolExplanation?.trim()
+        : message.toolTitle?.trim()
 
     const argEntries = useMemo<Array<[string, unknown]>>(() => {
       if (!message.parameters || typeof message.parameters !== "object") return []
-      return Object.entries(message.parameters).filter(
-        ([k, v]) => !COMMAND_BODY_KEYS.has(k) && v !== null && v !== undefined && v !== "",
+      const entries = Object.entries(message.parameters).filter(
+        ([, v]) => v !== null && v !== undefined && v !== "",
       )
-    }, [message.parameters])
+      // The end client (Fae app) never sees the raw command/query/script body —
+      // only the secondary args. Every admin surface DOES: surface the command
+      // body first (as a labeled `command:` row), then the rest of the args.
+      if (variant === "client") {
+        return entries.filter(([k]) => !COMMAND_BODY_KEYS.has(k))
+      }
+      const commandEntries = entries.filter(([k]) => COMMAND_BODY_KEYS.has(k))
+      const otherEntries = entries.filter(([k]) => !COMMAND_BODY_KEYS.has(k))
+      return [...commandEntries, ...otherEntries]
+    }, [message.parameters, variant])
 
     const hasResult = isExecuted && typeof message.result === "string" && message.result.length > 0
     const hasBody = argEntries.length > 0 || hasResult || isExecuting
@@ -44,6 +67,34 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
       return null
     }
 
+    const headerContent = (
+      <>
+        {!isClient && (
+          <div className="flex items-center justify-center shrink-0 w-5 h-5">
+            <ToolIcon toolType={integratedToolType} size={16} />
+          </div>
+        )}
+        <div
+          className={cn(
+            "flex-1 min-w-0 text-h6",
+            isClientView
+              ? "text-ods-text-primary whitespace-pre-wrap break-words"
+              : expanded
+                ? "text-ods-text-primary whitespace-pre-wrap break-all"
+                : "text-ods-text-secondary line-clamp-2 max-h-10 break-all",
+          )}
+        >
+          {previewText}
+        </div>
+        <div className="flex items-center justify-center shrink-0 w-5 h-5">{renderStatusIcon()}</div>
+        {!isClientView && (
+          <div className="flex items-center justify-center shrink-0 w-5 h-5">
+            <ExpandChevron expanded={expanded} />
+          </div>
+        )}
+      </>
+    )
+
     return (
       <div
         ref={ref}
@@ -55,60 +106,52 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
         )}
         {...props}
       >
-        <button
-          type="button"
-          className="flex gap-[var(--spacing-system-xs)] items-start p-[var(--spacing-system-s)] cursor-pointer text-left w-full"
-          onClick={() => setExpanded((prev) => !prev)}
-        >
-          {!isClient && (
-            <div className="flex items-center justify-center shrink-0 w-5 h-5">
-              <ToolIcon toolType={integratedToolType} size={16} />
-            </div>
-          )}
-          <div
-            className={cn(
-              "flex-1 min-w-0 text-h6",
-              expanded
-                ? "text-ods-text-primary whitespace-pre-wrap break-all"
-                : "text-ods-text-secondary line-clamp-2 max-h-10 break-all",
-            )}
-          >
-            {previewText}
-          </div>
-          <div className="flex items-center justify-center shrink-0 w-5 h-5">{renderStatusIcon()}</div>
-          <div className="flex items-center justify-center shrink-0 w-5 h-5">
-            <ExpandChevron expanded={expanded} />
+        {isClientView ? (
+          // Client (Fae end-user): static, non-expandable row — no chevron, no
+          // body. Just the explanation + status; command/args/result are hidden.
+          <div className="flex gap-[var(--spacing-system-xs)] items-start p-[var(--spacing-system-s)] w-full text-left">
+            {headerContent}
           </div>
-        </button>
+        ) : (
+          <>
+            <button
+              type="button"
+              className="flex gap-[var(--spacing-system-xs)] items-start p-[var(--spacing-system-s)] cursor-pointer text-left w-full"
+              onClick={() => setExpanded((prev) => !prev)}
+            >
+              {headerContent}
+            </button>
 
-        <div className="w-full" style={containerStyle}>
-          <div ref={innerRef}>
-            {hasBody && (
-              <div className="flex flex-col gap-0 items-start w-full text-h6 p-[var(--spacing-system-sf)] bg-ods-card">
-                {argEntries.map(([key, value]) => (
-                  <ArgRow key={key} argKey={key} value={value} />
-                ))}
-                {hasResult && (
-                  <ResultBlock
-                    result={message.result}
-                    className={argEntries.length > 0 ? "mt-[var(--spacing-system-xsf)]" : undefined}
-                  />
-                )}
-                {isExecuting && (
-                  <div
-                    className={cn(
-                      "flex flex-col gap-[var(--spacing-system-xxs)] items-start w-full",
-                      argEntries.length > 0 && "mt-[var(--spacing-system-xsf)]",
+            <div className="w-full" style={containerStyle}>
+              <div ref={innerRef}>
+                {hasBody && (
+                  <div className="flex flex-col gap-0 items-start w-full text-h6 p-[var(--spacing-system-sf)] bg-ods-card">
+                    {argEntries.map(([key, value]) => (
+                      <ArgRow key={key} argKey={key} value={value} />
+                    ))}
+                    {hasResult && (
+                      <ResultBlock
+                        result={message.result}
+                        className={argEntries.length > 0 ? "mt-[var(--spacing-system-xsf)]" : undefined}
+                      />
+                    )}
+                    {isExecuting && (
+                      <div
+                        className={cn(
+                          "flex flex-col gap-[var(--spacing-system-xxs)] items-start w-full",
+                          argEntries.length > 0 && "mt-[var(--spacing-system-xsf)]",
+                        )}
+                      >
+                        <span className="text-ods-text-secondary">Result:</span>
+                        <DotsLoaderIcon size={16} className="text-ods-text-secondary" />
+                      </div>
                     )}
-                  >
-                    <span className="text-ods-text-secondary">Result:</span>
-                    <DotsLoaderIcon size={16} className="text-ods-text-secondary" />
                   </div>
                 )}
               </div>
-            )}
-          </div>
-        </div>
+            </div>
+          </>
+        )}
       </div>
     )
   },

package/src/components/chat/types/component.types.ts

@@ -506,6 +506,12 @@ export interface ToolExecutionDisplayProps extends HTMLAttributes<HTMLDivElement
   /** Chat identity. `'fae'` (client) hides the tool icon; `'mingo'`/undefined
    *  keep the admin layout. */
   assistantType?: AssistantType
+  /** Viewer variant — the consumer-declared render audience (NOT derived from
+   *  `assistantType`, which only says which assistant the dialog belongs to).
+   *  `'client'` (end-client Fae app) shows the human-readable `toolExplanation`;
+   *  `'admin'` (default — every dashboard surface, incl. a ticket's Fae client
+   *  tab) shows the concise `toolTitle`. */
+  variant?: ApprovalBlockVariant
 }
 
 // ========== Approval Request Message Props ==========

package/src/components/chat/types/message.types.ts

@@ -50,6 +50,12 @@ export interface ToolExecutionData {
   toolFunction: string
   /** Backend-issued human-readable title (mirrors `PendingToolCallData.toolTitle`). */
   toolTitle?: string
+  /**
+   * Backend-issued human-readable explanation of what the tool is doing and why
+   * (mirrors `PendingToolCallData.toolExplanation`). Only sent on `EXECUTING_TOOL`;
+   * the accumulator restores it onto the merged `EXECUTED_TOOL` segment.
+   */
+  toolExplanation?: string
   parameters?: Record<string, any>
   result?: string
   success?: boolean
@@ -73,6 +79,8 @@ export interface ExecutingToolState {
   toolFunction: string
   /** Mirrors {@link ToolExecutionData.toolTitle}; absent on `EXECUTED_TOOL`. */
   toolTitle?: string
+  /** Mirrors {@link ToolExecutionData.toolExplanation}; absent on `EXECUTED_TOOL`. */
+  toolExplanation?: string
   parameters?: Record<string, any>
 }
 
@@ -226,6 +234,8 @@ export interface ExecutingToolMessageData extends MessageDataBase {
   toolFunction?: string
   /** Backend-issued human-readable title (wire field, mirrors `ChunkData.title`). */
   title?: string
+  /** Backend-issued human-readable explanation (what/why) of the tool call. */
+  toolExplanation?: string
   parameters?: Record<string, any>
   toolExecutionRequestId?: string
 }

package/src/components/chat/types/network.types.ts

@@ -44,6 +44,8 @@ export interface ChunkData {
   toolFunction?: string
   /** Execution chunks carry the human-readable title as `title`. */
   title?: string
+  /** EXECUTING_TOOL chunks carry the tool's human-readable explanation (what/why). */
+  toolExplanation?: string
   parameters?: Record<string, any>
   result?: string
   success?: boolean

package/src/components/chat/utils/chunk-parser.ts

@@ -75,6 +75,7 @@ export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
             toolTitle: typeof data.title === 'string' ? data.title : undefined,
+            toolExplanation: typeof data.toolExplanation === 'string' ? data.toolExplanation : undefined,
             parameters: data.parameters,
             toolExecutionRequestId: typeof data.toolExecutionRequestId === 'string' ? data.toolExecutionRequestId : undefined,
           }

package/src/components/chat/utils/extract-incomplete-message-state.ts

@@ -41,6 +41,7 @@ export function extractIncompleteMessageState(
             integratedToolType: segment.data.integratedToolType,
             toolFunction: segment.data.toolFunction,
             toolTitle: segment.data.toolTitle,
+            toolExplanation: segment.data.toolExplanation,
             parameters: segment.data.parameters,
           })
           hasIncompleteState = true

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -169,6 +169,7 @@ export class MessageSegmentAccumulator {
         integratedToolType: toolData.integratedToolType,
         toolFunction: toolData.toolFunction,
         toolTitle: toolData.toolTitle,
+        toolExplanation: toolData.toolExplanation,
         parameters: toolData.parameters,
       })
       this.segments.push(segment)
@@ -195,6 +196,8 @@ export class MessageSegmentAccumulator {
         data: {
           ...toolData,
           toolTitle: toolData.toolTitle ?? existingExecuting?.data.toolTitle ?? executingTool?.toolTitle,
+          toolExplanation:
+            toolData.toolExplanation ?? existingExecuting?.data.toolExplanation ?? executingTool?.toolExplanation,
           parameters: toolData.parameters || executingTool?.parameters,
         }
       }

package/src/components/chat/utils/process-historical-messages.ts

@@ -284,6 +284,7 @@ function processMessageData(
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
             toolTitle: typeof data.title === 'string' ? data.title : undefined,
+            toolExplanation: typeof data.toolExplanation === 'string' ? data.toolExplanation : undefined,
             parameters: data.parameters,
             toolExecutionRequestId: data.toolExecutionRequestId,
           },