mu-coding 0.5.0 → 0.8.0

package/src/tui/chat/useChatSession.ts

@@ -1,11 +1,18 @@
-import type { PluginRegistry } from 'mu-agents';
-import type { ChatMessage, ProviderConfig } from 'mu-provider';
-import { useCallback } from 'react';
+import type { ChatMessage, ProviderConfig, Session } from 'mu-core';
+import { type PluginRegistry, runTransformUserInputHooks } from 'mu-core';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { HostMessageBus } from '../../runtime/messageBus';
 import type { AttachmentState } from './useAttachment';
 import { useSessionPersistence } from './useSessionPersistence';
-import { type StreamState, useStreamConsumer } from './useStreamConsumer';
 
-export type { StreamState } from './useStreamConsumer';
+export interface StreamState {
+  text: string;
+  reasoning: string;
+  totalTokens: number;
+  cachedTokens: number;
+}
+
+const EMPTY_STREAM: StreamState = { text: '', reasoning: '', totalTokens: 0, cachedTokens: 0 };
 
 export interface ChatSessionState {
   messages: ChatMessage[];
@@ -19,94 +26,256 @@ export interface ChatSessionState {
 }
 
 interface SessionDeps {
+  /**
+   * mu-core Session instance owned by the host. Authoritative for the
+   * transcript — this hook only mirrors it into React state and writes
+   * persistence on each message_changed event.
+   */
+  session: Session;
+  /** Provider config used as `runTurn` override (model lookup happens here). */
   config: ProviderConfig;
+  /** Currently selected model id (may shift across sends). */
   currentModel: string;
   attachment: AttachmentState;
   controllerRef: React.RefObject<AbortController | null>;
   initialMessages?: ChatMessage[];
   registry: PluginRegistry;
+  messageBus?: HostMessageBus;
 }
 
 /**
- * Top-level chat-session hook. Composes:
- *  - `useSessionPersistence` — transcript, history, save path
- *  - `useStreamConsumer`     — in-flight tokens, tps, error
- *
- * Provides the `onSend` glue that wires user input through the agent.
+ * Wire the host MessageBus to the Session: bus.append flows through
+ * `session.appendSynthetic` so every subscriber (TUI, broadcaster) sees the
+ * same change. `bus.get()` mirrors the live transcript.
  */
-export function useChatSession(deps: SessionDeps): ChatSessionState {
-  const { config, currentModel, attachment, controllerRef, initialMessages, registry } = deps;
-  const persistence = useSessionPersistence(initialMessages);
-  const consumer = useStreamConsumer();
-  const { messages, setMessages, appendHistory, saveCurrent } = persistence;
+function useMessageBusWiring(messageBus: HostMessageBus | undefined, messages: ChatMessage[], session: Session): void {
+  useEffect(() => {
+    messageBus?.setMessages(messages);
+  }, [messageBus, messages]);
+
+  useEffect(() => {
+    if (!messageBus) return;
+    messageBus.setAppender((message) => {
+      session.appendSynthetic(message);
+    });
+    return () => {
+      messageBus.setAppender(null);
+    };
+  }, [messageBus, session]);
+}
+
+interface SubscriptionDeps {
+  session: Session;
+  setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
+  setStream: React.Dispatch<React.SetStateAction<StreamState>>;
+  setStreaming: React.Dispatch<React.SetStateAction<boolean>>;
+  setError: React.Dispatch<React.SetStateAction<string | null>>;
+  saveCurrent: (messages: ChatMessage[]) => void;
+}
+
+/**
+ * Subscribe React state to mu-core Session events. Session is authoritative;
+ * this hook only mirrors. Persistence is driven from the same stream so disk
+ * writes are guaranteed to match what the user sees, but writes are
+ * coalesced to once per `stream_ended` to keep tool-heavy turns light on I/O.
+ */
+/**
+ * Build the event handler. Extracted so the cognitive complexity of the
+ * dispatch lives outside the React effect closure (the effect itself is
+ * just `session.subscribe(handler)`).
+ */
+function makeSessionEventHandler(
+  deps: SubscriptionDeps,
+  lastMessagesRef: React.MutableRefObject<ChatMessage[]>,
+): (event: import('mu-core').SessionEvent) => void {
+  const { setMessages, setStream, setStreaming, setError, saveCurrent } = deps;
+  return (event) => {
+    if (event.type === 'messages_changed') {
+      lastMessagesRef.current = event.messages;
+      setMessages(event.messages);
+      return;
+    }
+    if (event.type === 'stream_partial') {
+      setStream((s) => ({ ...s, text: event.text, reasoning: event.reasoning ?? '' }));
+      return;
+    }
+    if (event.type === 'stream_started') {
+      setStreaming(true);
+      setError(null);
+      return;
+    }
+    if (event.type === 'stream_ended') {
+      setStreaming(false);
+      setStream((s) => ({ ...s, text: '', reasoning: '' }));
+      if (lastMessagesRef.current.length > 0) saveCurrent(lastMessagesRef.current);
+      return;
+    }
+    if (event.type === 'usage') {
+      setStream((s) => ({
+        ...s,
+        totalTokens: s.totalTokens + event.totalTokens,
+        cachedTokens: s.cachedTokens + event.cachedTokens,
+      }));
+      return;
+    }
+    if (event.type === 'error') {
+      setError(event.message);
+    }
+  };
+}
+
+function useSessionSubscription(deps: SubscriptionDeps): void {
+  const { session, setMessages, setStream, setStreaming, setError, saveCurrent } = deps;
+  // The "last completed transcript" buffer survives effect re-subscriptions
+  // (e.g. if `saveCurrent` identity ever changes mid-stream). Without a ref
+  // we'd lose the in-flight save target on the next deps change.
+  const lastMessagesRef = useRef<ChatMessage[]>([]);
+  useEffect(() => {
+    const handler = makeSessionEventHandler(
+      { session, setMessages, setStream, setStreaming, setError, saveCurrent },
+      lastMessagesRef,
+    );
+    return session.subscribe(handler);
+  }, [session, setMessages, setStream, setStreaming, setError, saveCurrent]);
+}
+
+interface OnSendDeps {
+  session: Session;
+  config: ProviderConfig;
+  currentModel: string;
+  attachment: AttachmentState;
+  controllerRef: React.RefObject<AbortController | null>;
+  registry: PluginRegistry;
+  messageBus?: HostMessageBus;
+  appendHistory: (text: string) => void;
+  streaming: boolean;
+}
 
-  const onSend = useCallback(
+function useOnSend(deps: OnSendDeps): (text: string) => Promise<void> {
+  const { session, config, currentModel, attachment, controllerRef, registry, messageBus, appendHistory, streaming } =
+    deps;
+  return useCallback(
     async (text: string) => {
-      if (consumer.streaming) {
-        return;
-      }
+      if (streaming) return;
+
+      const transform = await runTransformUserInputHooks(registry.getHooks(), text);
+      if (transform.kind === 'intercept') return;
+      const finalText = transform.kind === 'transform' ? transform.text : text;
+
       const userMsg: ChatMessage = {
         role: 'user',
-        content: text,
+        content: finalText,
         ...(attachment.attachment ? { images: [attachment.attachment] } : {}),
       };
-      setMessages((prev) => [...prev, userMsg]);
+
+      const injections = messageBus?.drainNext() ?? [];
+      for (const inj of injections) session.queueForNextTurn(inj);
+
       appendHistory(text);
       attachment.clear();
 
       const controller = new AbortController();
       controllerRef.current = controller;
+      controller.signal.addEventListener('abort', () => session.abort(), { once: true });
 
       try {
-        const final = await consumer.runStream(
-          [...messages, userMsg],
+        await session.runTurn({
+          userMessage: userMsg,
           config,
-          currentModel,
-          controller.signal,
+          model: currentModel,
           registry,
-          setMessages,
-        );
-        if (final) {
-          saveCurrent(final);
-        }
+        });
       } finally {
         controllerRef.current = null;
       }
     },
-    [
-      consumer.streaming,
-      consumer.runStream,
-      messages,
-      config,
-      currentModel,
-      attachment,
-      controllerRef,
-      registry,
-      setMessages,
-      appendHistory,
-      saveCurrent,
-    ],
+    [streaming, session, config, currentModel, attachment, controllerRef, registry, messageBus, appendHistory],
   );
+}
+
+/**
+ * Top-level chat-session hook. Composes:
+ *  - mu-core `Session` — single source of truth for the transcript
+ *  - `useSessionPersistence` — disk write + history + session paths
+ *
+ * The hook is purely reactive: it subscribes to session events and exposes
+ * the resulting state, plus thin wrappers around `session.runTurn` /
+ * `session.setMessages` for user actions.
+ */
+export function useChatSession(deps: SessionDeps): ChatSessionState {
+  const { session, config, currentModel, attachment, controllerRef, initialMessages, registry, messageBus } = deps;
+  const persistence = useSessionPersistence(initialMessages);
+  const { appendHistory, saveCurrent, resetForNew, loadFromPath } = persistence;
+
+  // Initial seed: feed any persisted messages into the session once.
+  // The session subscription below will then mirror them into React state.
+  useEffect(() => {
+    if (initialMessages?.length) session.setMessages(initialMessages);
+    // Run once per session instance.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session, initialMessages?.length, initialMessages]);
+
+  const [messages, setMessages] = useState<ChatMessage[]>(() => initialMessages ?? []);
+  const [streaming, setStreaming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [stream, setStream] = useState<StreamState>(EMPTY_STREAM);
+
+  useMessageBusWiring(messageBus, messages, session);
+  useSessionSubscription({ session, setMessages, setStream, setStreaming, setError, saveCurrent });
+
+  const onSend = useOnSend({
+    session,
+    config,
+    currentModel,
+    attachment,
+    controllerRef,
+    registry,
+    messageBus,
+    appendHistory,
+    streaming,
+  });
 
   const onNew = useCallback(() => {
-    persistence.onNew();
-    consumer.resetError();
+    // Abort any in-flight turn *before* rotating the session path.
+    // Without this, the streaming `runTurn` keeps emitting `messages_changed`
+    // events that are saved to the newly-rotated path via `stream_ended`,
+    // mixing the old transcript into the brand-new file.
+    if (controllerRef.current) {
+      controllerRef.current.abort();
+      controllerRef.current = null;
+    }
+    resetForNew();
+    // `session.setMessages([])` emits `messages_changed` which the
+    // subscription mirrors into React state, so we don't double-write here.
+    session.setMessages([]);
+    setStream(EMPTY_STREAM);
+    setError(null);
     attachment.clear();
-  }, [persistence.onNew, consumer.resetError, attachment]);
+  }, [resetForNew, session, attachment, controllerRef]);
 
   const onLoadSession = useCallback(
     (path: string) => {
-      persistence.onLoadSession(path);
-      consumer.resetError();
+      const loaded = loadFromPath(path);
+      if (loaded.length === 0) return;
+      // Abort any in-flight turn before replacing the transcript, for the
+      // same reason as onNew above.
+      if (controllerRef.current) {
+        controllerRef.current.abort();
+        controllerRef.current = null;
+      }
+      // setMessages emits messages_changed → React state mirrors it.
+      session.setMessages(loaded);
+      setStream(EMPTY_STREAM);
+      setError(null);
     },
-    [persistence.onLoadSession, consumer.resetError],
+    [loadFromPath, session, controllerRef],
   );
 
   return {
-    messages: persistence.messages,
-    streaming: consumer.streaming,
-    error: consumer.error,
-    stream: consumer.stream,
+    messages,
+    streaming,
+    error,
+    stream,
     inputHistory: persistence.inputHistory,
     onSend,
     onNew,

package/src/tui/chat/useModels.ts

@@ -1,4 +1,5 @@
-import { type ApiModel, listModels } from 'mu-provider';
+import type { ApiModel } from 'mu-core';
+import { listModels } from 'mu-openai-provider';
 import { useCallback, useEffect, useState } from 'react';
 import { saveConfig } from '../../config/index';
 

package/src/tui/chat/usePluginStatus.ts

@@ -1,4 +1,4 @@
-import type { PluginRegistry, StatusSegment } from 'mu-agents';
+import type { PluginRegistry, StatusSegment } from 'mu-core';
 import { useEffect, useMemo, useState } from 'react';
 import type { InkUIService } from '../plugins/InkUIService';
 

package/src/tui/chat/useSessionPersistence.ts

@@ -1,16 +1,22 @@
-import type { ChatMessage } from 'mu-provider';
+import type { ChatMessage } from 'mu-core';
 import { useCallback, useRef, useState } from 'react';
 import { generateSessionPath, loadSession, saveSession } from '../../sessions/index';
 
 export interface SessionPersistenceState {
-  messages: ChatMessage[];
-  setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
   inputHistory: string[];
   appendHistory: (text: string) => void;
   sessionPathRef: React.RefObject<string>;
+  /** Persist the given transcript to the current session file. */
   saveCurrent: (messages: ChatMessage[]) => void;
-  onNew: () => void;
-  onLoadSession: (path: string) => void;
+  /** Reset to a brand-new session: rotates the file path. */
+  resetForNew: () => void;
+  /**
+   * Load a transcript from disk and adopt its path. Returns the loaded
+   * messages so the caller can hand them to the session.
+   */
+  loadFromPath: (path: string) => ChatMessage[];
+  /** Replace history (used after resume / load). */
+  setHistory: (history: string[]) => void;
 }
 
 function userPromptsFrom(messages: ChatMessage[]): string[] {
@@ -18,14 +24,15 @@ function userPromptsFrom(messages: ChatMessage[]): string[] {
 }
 
 /**
- * Owns the conversation transcript and its on-disk persistence. Keeps the
- * current session path, the transcript, and the user-input history in sync.
+ * Side-channel persistence: history bookkeeping, on-disk save, and session
+ * file path management. Does NOT own the transcript — `Session` is the
+ * single source of truth in the new architecture, this hook only writes to
+ * disk and tracks the current target path.
  *
  * Save errors are logged to stderr and do not surface to the chat error
  * channel — they're considered non-fatal (next save attempt may succeed).
  */
 export function useSessionPersistence(initialMessages?: ChatMessage[]): SessionPersistenceState {
-  const [messages, setMessages] = useState<ChatMessage[]>(initialMessages ?? []);
   const [inputHistory, setInputHistory] = useState<string[]>(userPromptsFrom(initialMessages ?? []));
   const sessionPathRef = useRef(generateSessionPath());
 
@@ -39,19 +46,23 @@ export function useSessionPersistence(initialMessages?: ChatMessage[]): SessionP
     });
   }, []);
 
-  const onNew = useCallback(() => {
-    setMessages([]);
+  const resetForNew = useCallback(() => {
     sessionPathRef.current = generateSessionPath();
+    setInputHistory([]);
   }, []);
 
-  const onLoadSession = useCallback((path: string) => {
+  const loadFromPath = useCallback((path: string): ChatMessage[] => {
     const msgs = loadSession(path);
     if (msgs.length > 0) {
-      setMessages(msgs);
-      setInputHistory(userPromptsFrom(msgs));
       sessionPathRef.current = path;
+      setInputHistory(userPromptsFrom(msgs));
     }
+    return msgs;
+  }, []);
+
+  const setHistory = useCallback((history: string[]) => {
+    setInputHistory(history);
   }, []);
 
-  return { messages, setMessages, inputHistory, appendHistory, sessionPathRef, saveCurrent, onNew, onLoadSession };
+  return { inputHistory, appendHistory, sessionPathRef, saveCurrent, resetForNew, loadFromPath, setHistory };
 }

package/src/tui/chat/useStatusSegments.ts

@@ -1,4 +1,4 @@
-import type { StatusSegment } from 'mu-agents';
+import type { StatusSegment } from 'mu-core';
 import type { StatusBarSegment } from '../components/statusBar';
 import { useSpinner } from '../hooks/useUI';
 
@@ -10,7 +10,10 @@ interface StatusSegmentOptions {
   quitWarning: boolean;
   error: string | null;
   modelError: string | null;
-  tokensPerSecond: number;
+  totalTokens: number;
+  /** Tokens served from server-side prompt cache. Rendered as `(N cached)`
+   *  next to the total when > 0. Omit (or pass 0) to hide the suffix. */
+  cachedTokens?: number;
   pluginStatus?: StatusSegment[];
 }
 
@@ -18,6 +21,11 @@ function truncate(text: string, max: number): string {
   return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 
+const tokenFormatter = new Intl.NumberFormat('en-US');
+function formatTokens(n: number): string {
+  return tokenFormatter.format(n);
+}
+
 export function useStatusSegments(options: StatusSegmentOptions): StatusBarSegment[] {
   const spinner = useSpinner(options.streaming);
   const segments: StatusBarSegment[] = [];
@@ -25,8 +33,13 @@ export function useStatusSegments(options: StatusSegmentOptions): StatusBarSegme
   if (options.streaming) {
     segments.push({ text: `${spinner} generating`, color: 'yellow' });
   }
-  if (options.tokensPerSecond > 0) {
-    segments.push({ text: `${options.tokensPerSecond} tok/s`, dim: true });
+  if (options.totalTokens > 0) {
+    const cached = options.cachedTokens ?? 0;
+    const label =
+      cached > 0
+        ? `${formatTokens(options.totalTokens)} tokens (${formatTokens(cached)} cached)`
+        : `${formatTokens(options.totalTokens)} tokens`;
+    segments.push({ text: label, dim: true });
   }
   if (options.abortWarning) {
     segments.push({ text: 'Esc again to stop', color: 'yellow' });

package/src/tui/components/chat/ChatPanel.tsx

@@ -1,7 +1,8 @@
-import type { PluginRegistry } from 'mu-agents';
-import type { ChatMessage, ProviderConfig } from 'mu-provider';
+import type { ChatMessage, PluginRegistry, ProviderConfig } from 'mu-core';
 import type { ShutdownFn } from '../../../app/shutdown';
+import type { HostMessageBus } from '../../../runtime/messageBus';
 import { ChatContext } from '../../chat/ChatContext';
+import { MessageRendererProvider, useRegistryRenderers } from '../../chat/MessageRendererContext';
 import { ToolDisplayProvider, useToolDisplayMap } from '../../chat/ToolDisplayContext';
 import { useChatPanel } from '../../chat/useChatPanel';
 import type { InkUIService } from '../../plugins/InkUIService';
@@ -11,22 +12,27 @@ export function ChatPanel({
   config,
   initialMessages,
   registry,
+  messageBus,
   uiService,
   shutdown,
 }: {
   config: ProviderConfig;
   initialMessages?: ChatMessage[];
   registry: PluginRegistry;
+  messageBus?: HostMessageBus;
   uiService?: InkUIService;
   shutdown?: ShutdownFn;
 }) {
-  const { ctx, bodyProps } = useChatPanel({ config, initialMessages, registry, uiService, shutdown });
+  const { ctx, bodyProps } = useChatPanel({ config, initialMessages, registry, messageBus, uiService, shutdown });
   const toolDisplays = useToolDisplayMap(registry);
+  const renderers = useRegistryRenderers(registry);
 
   return (
     <ChatContext.Provider value={ctx}>
       <ToolDisplayProvider value={toolDisplays}>
-        <ChatPanelBody {...bodyProps} />
+        <MessageRendererProvider value={renderers}>
+          <ChatPanelBody {...bodyProps} />
+        </MessageRendererProvider>
       </ToolDisplayProvider>
     </ChatContext.Provider>
   );

package/src/tui/components/chat/ChatPanelBody.tsx

@@ -1,5 +1,5 @@
 import { Box, type DOMElement as InkDOMElement } from 'ink';
-import type { ChatMessage } from 'mu-provider';
+import type { ChatMessage } from 'mu-core';
 import type { StreamState } from '../../chat/useChatSession';
 import { InputBox } from '../../input/InputBox';
 import type { InkUIService } from '../../plugins/InkUIService';

package/src/tui/components/messageView.tsx

@@ -1,8 +1,9 @@
 import type { DOMElement } from 'ink';
 import { Box, Text } from 'ink';
-import type { ChatMessage } from 'mu-provider';
+import type { ChatMessage } from 'mu-core';
 import { type RefObject, useMemo } from 'react';
 import type { StreamState } from '../chat/useChatSession';
+import { useTheme } from '../context/ThemeContext';
 import { MessageItem } from './messages/messageItem';
 import { StreamingOutput } from './messages/streamingOutput';
 import { Scrollbar } from './primitives/scrollbar';
@@ -50,6 +51,7 @@ export function MessageView({
   viewHeight: number;
   contentHeight: number;
 }) {
+  const theme = useTheme();
   const toolMessageIndex = useMemo(() => indexToolMessages(messages), [messages]);
 
   return (
@@ -61,7 +63,7 @@ export function MessageView({
             <MessageItem key={i} msg={msg} toolMessages={toolMessageIndex.get(i)} />
           ))}
           {streaming && <StreamingOutput currentText={stream.text} currentReasoning={stream.reasoning} />}
-          {error && <Text color="red">Error: {error}</Text>}
+          {error && <Text color={theme.common.error}>Error: {error}</Text>}
         </Box>
       </Box>
       <Scrollbar viewHeight={viewHeight} contentHeight={contentHeight} scrollOffset={scrollOffset} />

package/src/tui/components/messages/EditOutput.tsx

@@ -1,6 +1,7 @@
 import { Box, Text } from 'ink';
-import type { ToolDisplayHint } from 'mu-agents';
+import type { ToolDisplayHint } from 'mu-core';
 import { computeDiff, renderDiff } from '../../../utils/diff';
+import { useTheme } from '../../context/ThemeContext';
 import { ToolHeader } from './ToolHeader';
 
 interface EditOutputProps {
@@ -41,6 +42,7 @@ function parseEditArgs(args: string, hint: ToolDisplayHint | undefined): ParsedE
 }
 
 export function EditOutput({ args, content, error, hint }: EditOutputProps) {
+  const theme = useTheme();
   const { path, before, after } = parseEditArgs(args, hint);
   const verb = hint?.verb ?? 'edit_file';
 
@@ -60,7 +62,7 @@ export function EditOutput({ args, content, error, hint }: EditOutputProps) {
   if (diff.lines.length === 0 && diff.totalOldLines > 0 && diff.totalNewLines > 0) {
     return (
       <Box flexDirection="column" flexShrink={0} marginBottom={1}>
-        <Text color="yellow" bold={true}>
+        <Text color={theme.diff.warning} bold={true}>
           ! {verb}
         </Text>
         <Text dimColor={true}> {path}</Text>
@@ -88,8 +90,8 @@ export function EditOutput({ args, content, error, hint }: EditOutputProps) {
       <Box flexDirection="column" flexShrink={0}>
         {lines.map((line, i) => {
           let color: string | undefined;
-          if (line.startsWith('-')) color = 'red';
-          else if (line.startsWith('+')) color = 'green';
+          if (line.startsWith('-')) color = theme.diff.removed;
+          else if (line.startsWith('+')) color = theme.diff.added;
           return (
             // biome-ignore lint/suspicious/noArrayIndexKey: diff lines may repeat (blank lines, braces); index disambiguates
             <Text key={`${i}-${line}`} color={color} dimColor={color === undefined} wrap="wrap">

package/src/tui/components/messages/ToolHeader.tsx

@@ -1,4 +1,5 @@
 import { Box, Text } from 'ink';
+import { useTheme } from '../../context/ThemeContext';
 
 interface ToolHeaderProps {
   /** The tool name shown after the status icon. */
@@ -15,9 +16,10 @@ interface ToolHeaderProps {
  * specific component doesn't have to re-implement the same layout.
  */
 export function ToolHeader({ name, subtitle, error = false }: ToolHeaderProps) {
+  const theme = useTheme();
   return (
     <Box flexDirection="column" flexShrink={0}>
-      <Text color={error ? 'red' : 'green'} bold={true}>
+      <Text color={error ? theme.tool.error : theme.tool.success} bold={true}>
         {error ? '✗' : '✓'} {name}
       </Text>
       {subtitle && <Text dimColor={true}> {subtitle}</Text>}

package/src/tui/components/messages/assistantMessage.tsx

@@ -1,5 +1,5 @@
 import { Box, Text } from 'ink';
-import type { ChatMessage } from 'mu-provider';
+import type { ChatMessage } from 'mu-core';
 import React from 'react';
 import { ReasoningBlock } from './reasoningBlock';
 import { ToolCallBlock } from './toolCallBlock';
@@ -8,8 +8,18 @@ export const AssistantMessage: React.FC<{
   msg: ChatMessage;
   toolMessages?: ChatMessage[];
 }> = React.memo(function AssistantMessage({ msg, toolMessages }) {
+  const badge = msg.display?.badge;
+  const prefix = msg.display?.prefix;
+  const color = msg.display?.color;
   return (
     <Box flexDirection="column" flexShrink={0} marginBottom={1}>
+      {badge && (
+        <Box marginBottom={1}>
+          <Text color={color} bold={true}>
+            [{badge}]
+          </Text>
+        </Box>
+      )}
       {msg.reasoning && <ReasoningBlock reasoning={msg.reasoning} />}
       {msg.toolCalls?.length ? (
         <Box flexDirection="column" marginBottom={1}>
@@ -18,7 +28,12 @@ export const AssistantMessage: React.FC<{
           ))}
         </Box>
       ) : null}
-      {msg.content && <Text wrap="wrap">{msg.content}</Text>}
+      {msg.content && (
+        <Text wrap="wrap" color={color}>
+          {prefix && <Text color={color}>{prefix}</Text>}
+          {msg.content}
+        </Text>
+      )}
     </Box>
   );
 });

package/src/tui/components/messages/messageItem.tsx

@@ -1,5 +1,6 @@
-import type { ChatMessage } from 'mu-provider';
+import type { ChatMessage } from 'mu-core';
 import React from 'react';
+import { useMessageRenderer } from '../../chat/MessageRendererContext';
 import { AssistantMessage } from './assistantMessage';
 import { UserMessage } from './userMessage';
 
@@ -7,6 +8,23 @@ export const MessageItem: React.FC<{
   msg: ChatMessage;
   toolMessages?: ChatMessage[];
 }> = React.memo(function MessageItem({ msg, toolMessages }) {
+  const customRenderer = useMessageRenderer(msg.customType);
+
+  // Plugins may flag a message as `hidden` to keep it in the LLM transcript
+  // while suppressing on-screen rendering (e.g. system reminders carried with
+  // the user's next turn).
+  if (msg.display?.hidden) {
+    return null;
+  }
+
+  // Custom-typed messages always defer to a registered renderer when one is
+  // available; otherwise fall through to the role-default rendering so a
+  // plugin can ship messages whose renderer isn't loaded yet without losing
+  // their content.
+  if (customRenderer) {
+    return <>{customRenderer(msg)}</>;
+  }
+
   // Tool result messages are rendered inline within ToolCallBlock via the
   // pre-built index passed from MessageView; suppress them at the top level.
   if (msg.role === 'tool') {