@ai-matrx/chat 0.4.2 → 0.4.8

package/dist/ui/markdown-stream/MarkdownStream.d.ts

@@ -0,0 +1,88 @@
+import type { AnswerEditRemarkMeta } from "../../agents/redux/execution-system/instance-resources/remarks.js";
+import { TypedStreamEvent } from "@ai-matrx/rich-content/display/chat-markdown/types";
+import type { ServerProcessedBlock } from "./EnhancedChatMarkdown.js";
+/**
+ * Props for the MarkdownStream component.
+ * Defined here (in the shell) so consumers can import the type without
+ * pulling in the heavy implementation module.
+ */
+export interface MarkdownStreamProps {
+    /** Markdown content to render (legacy mode) */
+    content?: string;
+    /** Stream events to process (new mode) */
+    events?: TypedStreamEvent[];
+    /** Optional task ID for streaming updates (legacy mode with Redux) */
+    taskId?: string;
+    requestId?: string;
+    /** Every committed row a multi-iteration turn's one render stands for (see EnhancedChatMarkdown). */
+    recordMessageIds?: readonly string[];
+    /** Inclusive/exclusive source timeline range for one live transcript segment. */
+    streamSlotStart?: number;
+    streamSlotEnd?: number;
+    /**
+     * Render ONE collaboration `agent_call` child's live blocks from `requestId`
+     * (the parent request it streams inside) — the call id of the owning card.
+     * Its blocks go through the normal BlockRenderer path, so kinds route as in
+     * the parent (`selectAgentCallChildSlots`; the transcript still hides them).
+     */
+    agentCallId?: string;
+    /** Turn ID for DB-loaded turn rendering */
+    turnId?: string;
+    /** Conversation ID for DB-loaded turn rendering */
+    conversationId?: string;
+    /**
+     * @deprecated No longer used — `MarkdownStream` now always renders in
+     * `message` mode. This prop is kept on the interface for backward
+     * compatibility only and is ignored. Remove from callers.
+     */
+    type?: "flashcard" | "message" | "text" | "image" | "audio" | "video" | "file" | string;
+    /**
+     * @deprecated No longer used — `MarkdownStream` now always renders as
+     * `assistant`. This prop is kept on the interface for backward
+     * compatibility only and is ignored. Remove from callers.
+     */
+    role?: "user" | "assistant" | "system" | "tool" | string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Whether streaming is currently active */
+    isStreamActive?: boolean;
+    /** Callback for content changes */
+    /** See EnhancedChatMarkdown: `previousContent` is the text the edit applied to. */
+    onContentChange?: (newContent: string, previousContent: string, remark?: AnswerEditRemarkMeta) => void;
+    /**
+     * When false (with onContentChange), block edits are reported via onContentChange but
+     * the visible markdown stays tied to the `content` prop (no local edited overlay).
+     */
+    applyLocalEdits?: boolean;
+    /** Additional analysis data */
+    analysisData?: any;
+    /** Message ID for identification */
+    messageId?: string;
+    /** Allow full-screen editor mode */
+    allowFullScreenEditor?: boolean;
+    /** Hide the copy button */
+    hideCopyButton?: boolean;
+    /** Callback when an error event is received (new mode) */
+    onError?: (error: string) => void;
+    /** Callback when phase events are received (new mode) */
+    onPhaseUpdate?: (phase: string) => void;
+    /** Pre-processed content blocks from server/Redux (new content_block protocol). */
+    serverProcessedBlocks?: ServerProcessedBlock[];
+    /**
+     * Strict server-data mode — for testing/debugging only.
+     * When true, structured blocks will NOT fall back to client-side parsing
+     * if block.serverData is null. Leave false (default) for production.
+     */
+    strictServerData?: boolean;
+    /**
+     * WHO WROTE this content — "ai" (a model: answers, agent output), "other"
+     * (someone else: shared or public records) or "self" (the viewer). Decides
+     * whether remote images load by themselves (components/rich-content/prose/
+     * remote-image-policy.tsx, chair ruling 2026-09-25). Declare it at every
+     * call site — guard: components/rich-content/__tests__/image-policy-declared.test.ts.
+     */
+    imagePolicy?: "self" | "other" | "ai" | "inherit";
+}
+declare function MarkdownStream(props: MarkdownStreamProps): import("react").FunctionComponentElement<import("react").SuspenseProps> | null;
+export { MarkdownStream };
+export default MarkdownStream;

package/dist/ui/markdown-stream/MarkdownStream.js

@@ -0,0 +1,14 @@
+"use client";
+import { createElement, lazy, Suspense, useEffect, useState } from "react";
+const MarkdownStreamImpl = lazy(() => import("./MarkdownStreamImpl.js"));
+function MarkdownStream(props) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return null;
+  return createElement(Suspense, { fallback: null }, createElement(MarkdownStreamImpl, props));
+}
+var MarkdownStream_default = MarkdownStream;
+export {
+  MarkdownStream,
+  MarkdownStream_default as default
+};

package/dist/ui/markdown-stream/MarkdownStreamImpl.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import type { MarkdownStreamProps } from "./MarkdownStream.js";
+declare const MarkdownStreamImpl: React.FC<MarkdownStreamProps>;
+export default MarkdownStreamImpl;

package/dist/ui/markdown-stream/MarkdownStreamImpl.js

@@ -0,0 +1,86 @@
+"use client";
+import { Fragment, jsx } from "react/jsx-runtime";
+import { RichContentHostGate } from "@ai-matrx/rich-content/host";
+import { PlainTextFallback } from "@ai-matrx/rich-content/display/chat-markdown/internal-handlers/PlainTextFallback";
+import { MarkdownErrorBoundary } from "@ai-matrx/rich-content/display/chat-markdown/internal-handlers/MarkdownErrorBoundary";
+import { StreamAwareChatMarkdown } from "./StreamAwareChatMarkdown.js";
+import { BlockRenderingProvider } from "@ai-matrx/rich-content/display/chat-markdown/BlockRenderingContext";
+import { withImagePolicy } from "@ai-matrx/rich-content/levels/prose/remote-image-policy";
+const MarkdownStreamImpl = ({
+  content = "",
+  events,
+  taskId,
+  requestId,
+  recordMessageIds,
+  streamSlotStart,
+  streamSlotEnd,
+  agentCallId,
+  turnId,
+  conversationId,
+  type,
+  role,
+  className,
+  isStreamActive,
+  onContentChange,
+  applyLocalEdits,
+  analysisData,
+  messageId,
+  allowFullScreenEditor,
+  hideCopyButton,
+  onError,
+  onPhaseUpdate,
+  serverProcessedBlocks,
+  strictServerData = false,
+  imagePolicy
+}) => {
+  const rendered = /* @__PURE__ */ jsx(
+    RichContentHostGate,
+    {
+      fallback: /* @__PURE__ */ jsx(PlainTextFallback, { content, className }),
+      children: /* @__PURE__ */ jsx(BlockRenderingProvider, { strictServerData, children: /* @__PURE__ */ jsx(
+        MarkdownErrorBoundary,
+        {
+          fallback: /* @__PURE__ */ jsx(PlainTextFallback, { content, className }),
+          onError: (error, errorInfo) => {
+            console.error(
+              "[MarkdownStream] Top-level error boundary caught:",
+              error,
+              errorInfo
+            );
+          },
+          children: /* @__PURE__ */ jsx(
+            StreamAwareChatMarkdown,
+            {
+              requestId,
+              recordMessageIds,
+              streamSlotStart,
+              streamSlotEnd,
+              agentCallId,
+              turnId,
+              conversationId,
+              content,
+              events,
+              taskId,
+              className,
+              isStreamActive,
+              onContentChange,
+              applyLocalEdits,
+              analysisData,
+              messageId,
+              allowFullScreenEditor,
+              hideCopyButton,
+              onError,
+              onPhaseUpdate,
+              serverProcessedBlocks
+            }
+          )
+        }
+      ) })
+    }
+  );
+  return /* @__PURE__ */ jsx(Fragment, { children: withImagePolicy(imagePolicy, rendered) });
+};
+var MarkdownStreamImpl_default = MarkdownStreamImpl;
+export {
+  MarkdownStreamImpl_default as default
+};

package/dist/ui/markdown-stream/StreamAwareChatMarkdown.d.ts

@@ -0,0 +1,58 @@
+import React from "react";
+import { ChatMarkdownDisplayProps } from "./EnhancedChatMarkdown.js";
+import { TypedStreamEvent } from "@ai-matrx/rich-content/display/chat-markdown/types";
+interface ProcessedBlockState {
+    blockId: string;
+    blockIndex: number;
+    type: string;
+    status: "streaming" | "complete" | "error";
+    content?: string | null;
+    data?: Record<string, unknown> | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Extended props that include stream event handling
+ */
+export interface StreamAwareChatMarkdownProps extends Omit<ChatMarkdownDisplayProps, "content"> {
+    /**
+     * Direct content (legacy mode - used when not using events)
+     */
+    content?: string;
+    /** Turn ID for DB-loaded turn rendering */
+    turnId?: string;
+    /** Conversation ID for DB-loaded turn rendering */
+    conversationId?: string;
+    /**
+     * Array of stream events to process (new mode)
+     * When provided, this takes precedence over content prop
+     */
+    events?: TypedStreamEvent[];
+    /**
+     * Callback when an error event is received
+     */
+    onError?: (error: string) => void;
+    /**
+     * Callback when phase events are received
+     */
+    onPhaseUpdate?: (phase: string) => void;
+    /**
+     * Pre-processed blocks from the server (new render_block protocol).
+     * When present and non-empty, the component skips client-side parsing
+     * and renders these blocks directly.
+     */
+    serverProcessedBlocks?: ProcessedBlockState[];
+}
+/**
+ * Stream-aware wrapper for EnhancedChatMarkdown
+ *
+ * Supports two modes:
+ * 1. Legacy mode: Pass `content` directly (works with existing Redux/Socket.io)
+ * 2. Event mode: Pass `events` array (new unified API)
+ *
+ * In event mode, text and tool_call blocks are rendered in arrival order using
+ * buildCanonicalBlocks. This ensures tool calls appear inline at the exact
+ * position they were emitted relative to surrounding text — not pinned to the
+ * top of the message.
+ */
+export declare const StreamAwareChatMarkdown: React.FC<StreamAwareChatMarkdownProps>;
+export default StreamAwareChatMarkdown;

package/dist/ui/markdown-stream/StreamAwareChatMarkdown.js

@@ -0,0 +1,294 @@
+"use client";
+import { Fragment, jsx } from "react/jsx-runtime";
+import React, { useState, useEffect } from "react";
+import {
+  EnhancedChatMarkdownInternal
+} from "./EnhancedChatMarkdown.js";
+import { buildCanonicalBlocks } from "../chat-protocol-from-stream.js";
+import { MarkdownErrorBoundary } from "@ai-matrx/rich-content/display/chat-markdown/internal-handlers/MarkdownErrorBoundary";
+import { LiveToolCallCard } from "../../tool-call-visualization/components/LiveToolCallCard.js";
+import { useRetainRequestForViewer } from "../../agents/redux/execution-system/active-requests/useRetainRequestForViewer.js";
+const StreamAwareChatMarkdown = ({
+  requestId,
+  recordMessageIds,
+  streamSlotStart,
+  streamSlotEnd,
+  agentCallId,
+  turnId,
+  conversationId,
+  content,
+  events,
+  onError,
+  onPhaseUpdate,
+  serverProcessedBlocks: serverBlocksProp,
+  taskId,
+  className,
+  isStreamActive,
+  onContentChange,
+  analysisData,
+  messageId,
+  allowFullScreenEditor,
+  hideCopyButton,
+  applyLocalEdits
+}) => {
+  if (process.env.NODE_ENV !== "production") {
+    if (taskId !== void 0) {
+      console.warn(
+        "[StreamAwareChatMarkdown] `taskId` prop is a removal candidate \u2014 still in use:",
+        { requestId, turnId, conversationId, messageId, taskId }
+      );
+    }
+  }
+  useRetainRequestForViewer(requestId, "markdown-stream");
+  const [processedContent, setProcessedContent] = useState(
+    content || ""
+  );
+  const [hasStreamError, setHasStreamError] = useState(false);
+  const [canonicalBlocks, setCanonicalBlocks] = useState([]);
+  const [serverBlocks, setServerBlocks] = useState([]);
+  const serverBlockMapRef = React.useRef(
+    /* @__PURE__ */ new Map()
+  );
+  const isNewProtocolRef = React.useRef(false);
+  const onErrorRef = React.useRef(onError);
+  const onPhaseUpdateRef = React.useRef(onPhaseUpdate);
+  const lastProcessedIndexRef = React.useRef(-1);
+  const accumulatedContentRef = React.useRef("");
+  const canonicalBlocksChangedRef = React.useRef(false);
+  const eventsRef = React.useRef(events);
+  const rafIdRef = React.useRef(null);
+  const pendingContentUpdateRef = React.useRef(false);
+  const pendingCanonicalUpdateRef = React.useRef(false);
+  const pendingBlocksUpdateRef = React.useRef(false);
+  useEffect(() => {
+    onErrorRef.current = onError;
+    onPhaseUpdateRef.current = onPhaseUpdate;
+  }, [onError, onPhaseUpdate]);
+  useEffect(() => {
+    return () => {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+    };
+  }, []);
+  useEffect(() => {
+    eventsRef.current = events;
+  });
+  useEffect(() => {
+    if (!events || events.length === 0) {
+      if (content !== void 0 && content !== accumulatedContentRef.current) {
+        setProcessedContent(content);
+        accumulatedContentRef.current = content;
+        lastProcessedIndexRef.current = -1;
+        canonicalBlocksChangedRef.current = false;
+      }
+      return;
+    }
+    if (events.length <= lastProcessedIndexRef.current) {
+      lastProcessedIndexRef.current = -1;
+      accumulatedContentRef.current = "";
+      canonicalBlocksChangedRef.current = false;
+    }
+    const startIndex = lastProcessedIndexRef.current + 1;
+    if (startIndex >= events.length) return;
+    let hasNewContent = false;
+    let hasNewCanonical = false;
+    let hasNewBlocks = false;
+    for (let i = startIndex; i < events.length; i++) {
+      const event = events[i];
+      switch (event.event) {
+        case "chunk": {
+          accumulatedContentRef.current += event.data.text;
+          hasNewContent = true;
+          canonicalBlocksChangedRef.current = true;
+          hasNewCanonical = true;
+          break;
+        }
+        case "tool_event": {
+          console.log(
+            "[STREAM] tool_event:",
+            JSON.stringify(event.data, null, 2)
+          );
+          canonicalBlocksChangedRef.current = true;
+          hasNewCanonical = true;
+          break;
+        }
+        case "error": {
+          console.log("[STREAM] error:", JSON.stringify(event.data, null, 2));
+          const errorMessage = event.data.user_message || event.data.message || "An error occurred";
+          onErrorRef.current?.(errorMessage);
+          setHasStreamError(true);
+          break;
+        }
+        case "phase": {
+          console.log("[STREAM] phase:", JSON.stringify(event.data, null, 2));
+          onPhaseUpdateRef.current?.(event.data.phase);
+          break;
+        }
+        case "render_block": {
+          console.log(
+            "[STREAM] render_block:",
+            JSON.stringify(event.data, null, 2)
+          );
+          isNewProtocolRef.current = true;
+          const block = event.data;
+          if (block.blockId !== void 0) {
+            serverBlockMapRef.current.set(block.blockId, {
+              blockId: block.blockId,
+              blockIndex: block.blockIndex ?? 0,
+              type: block.type,
+              status: block.status ?? "streaming",
+              content: block.content ?? null,
+              data: block.data ?? null,
+              metadata: block.metadata ?? {}
+            });
+            hasNewBlocks = true;
+          }
+          break;
+        }
+        case "completion":
+          console.log(
+            "[STREAM] completion:",
+            JSON.stringify(event.data, null, 2)
+          );
+          break;
+        case "heartbeat":
+          console.log(
+            "[STREAM] heartbeat:",
+            JSON.stringify(event.data, null, 2)
+          );
+          break;
+        case "data":
+          console.log("[STREAM] data:", JSON.stringify(event.data, null, 2));
+          break;
+        case "end":
+          console.log("[STREAM] end:", JSON.stringify(event.data, null, 2));
+          break;
+        default:
+          console.log(
+            "[STREAM] \u26A0\uFE0F UNKNOWN event type:",
+            event.event,
+            JSON.stringify(event.data, null, 2)
+          );
+      }
+    }
+    lastProcessedIndexRef.current = events.length - 1;
+    if (hasNewContent) pendingContentUpdateRef.current = true;
+    if (hasNewCanonical) pendingCanonicalUpdateRef.current = true;
+    if (hasNewBlocks) pendingBlocksUpdateRef.current = true;
+    if ((hasNewContent || hasNewCanonical || hasNewBlocks) && rafIdRef.current === null) {
+      rafIdRef.current = requestAnimationFrame(() => {
+        rafIdRef.current = null;
+        if (pendingContentUpdateRef.current) {
+          setProcessedContent(accumulatedContentRef.current);
+          pendingContentUpdateRef.current = false;
+        }
+        if (pendingCanonicalUpdateRef.current && canonicalBlocksChangedRef.current) {
+          const currentEvents = eventsRef.current;
+          if (currentEvents) {
+            setCanonicalBlocks(buildCanonicalBlocks(currentEvents));
+          }
+          canonicalBlocksChangedRef.current = false;
+          pendingCanonicalUpdateRef.current = false;
+        }
+        if (pendingBlocksUpdateRef.current) {
+          const blockArray = Array.from(
+            serverBlockMapRef.current.values()
+          ).sort((a, b) => a.blockIndex - b.blockIndex);
+          setServerBlocks(blockArray);
+          pendingBlocksUpdateRef.current = false;
+        }
+      });
+    }
+  }, [events, content]);
+  const isEventMode = events && events.length > 0;
+  const hasToolBlocks = isEventMode && canonicalBlocks.some((b) => b.type === "tool_call");
+  const effectiveServerBlocks = serverBlocksProp ?? (isNewProtocolRef.current ? serverBlocks : void 0);
+  if (isEventMode && hasToolBlocks) {
+    return /* @__PURE__ */ jsx(Fragment, { children: canonicalBlocks.map((block, index) => {
+      const isLastBlock = index === canonicalBlocks.length - 1;
+      if (block.type === "text") {
+        const textBlock = block;
+        return /* @__PURE__ */ jsx(
+          EnhancedChatMarkdownInternal,
+          {
+            requestId,
+            recordMessageIds,
+            streamSlotStart,
+            streamSlotEnd,
+            agentCallId,
+            turnId,
+            conversationId,
+            content: textBlock.content,
+            taskId,
+            className,
+            isStreamActive: isLastBlock ? isStreamActive : false,
+            onContentChange,
+            analysisData,
+            messageId,
+            allowFullScreenEditor,
+            hideCopyButton,
+            applyLocalEdits,
+            serverProcessedBlocks: isLastBlock ? effectiveServerBlocks : void 0
+          },
+          `text-${index}`
+        );
+      }
+      if (block.type === "tool_call") {
+        const toolBlock = block;
+        const hasContentAfter = canonicalBlocks.slice(index + 1).some(
+          (b) => b.type === "tool_call" || b.type === "text" && b.content.trim()
+        );
+        return /* @__PURE__ */ jsx(
+          MarkdownErrorBoundary,
+          {
+            fallback: null,
+            onError: (error) => console.error(
+              "[MarkdownStream] LiveToolCallCard error:",
+              error
+            ),
+            children: requestId ? /* @__PURE__ */ jsx(
+              LiveToolCallCard,
+              {
+                requestId,
+                callId: toolBlock.callId,
+                conversationId,
+                hasContentAfter
+              }
+            ) : null
+          },
+          `tool-${toolBlock.callId}`
+        );
+      }
+      return null;
+    }) });
+  }
+  return /* @__PURE__ */ jsx(
+    EnhancedChatMarkdownInternal,
+    {
+      requestId,
+      recordMessageIds,
+      streamSlotStart,
+      streamSlotEnd,
+      agentCallId,
+      turnId,
+      conversationId,
+      content: processedContent,
+      taskId,
+      className,
+      isStreamActive,
+      onContentChange,
+      analysisData,
+      messageId,
+      allowFullScreenEditor,
+      hideCopyButton,
+      applyLocalEdits,
+      serverProcessedBlocks: effectiveServerBlocks
+    }
+  );
+};
+var StreamAwareChatMarkdown_default = StreamAwareChatMarkdown;
+export {
+  StreamAwareChatMarkdown,
+  StreamAwareChatMarkdown_default as default
+};

package/dist/ui/markdown-stream/internal-handlers/AgentCallChildTrace.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AgentCallChildTrace — a sub-agent's thinking and tool calls, drawn in the
+ * transcript directly under the `agent_call` card that ran it, live AND after
+ * a reload (Arman, 2026-10-01: nested work is shown, never hidden inside the
+ * card). Items come from `utils/agent-call-trace.ts` (one list, two sources);
+ * each renders through the components the top level uses — `ToolCard` for a
+ * call (so a nested `agent_call` brings its own trace: depth by recursion) and
+ * the canonical reasoning renderer for thinking. The door opens the child's
+ * own conversation.
+ */
+import React from "react";
+import type { ToolLifecycleEntry } from "../../../agents/types/request.types.js";
+import type { ToolCardProps } from "./ToolHandlers.js";
+export interface AgentCallChildTraceProps {
+    entry: ToolLifecycleEntry;
+    conversationId: string;
+    /** Live source — the parent request whose wire carried the child. */
+    requestId?: string;
+    /** Passed in (not imported) — `ToolCard` renders this trace. */
+    ToolCardComponent: React.ComponentType<ToolCardProps>;
+}
+export declare function AgentCallChildTrace({ entry, conversationId, requestId, ToolCardComponent, }: AgentCallChildTraceProps): React.JSX.Element | null;