pre-release commit

packages/cli/src/ui/utils/CodeColorizer.tsx

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { Text, Box } from 'ink';
+import { common, createLowlight } from 'lowlight';
+import type {
+  Root,
+  Element,
+  Text as HastText,
+  ElementContent,
+  RootContent,
+} from 'hast';
+import { themeManager } from '../themes/theme-manager.js';
+import { Theme } from '../themes/theme.js';
+import {
+  MaxSizedBox,
+  MINIMUM_MAX_HEIGHT,
+} from '../components/shared/MaxSizedBox.js';
+
+// Configure theming and parsing utilities.
+const lowlight = createLowlight(common);
+
+function renderHastNode(
+  node: Root | Element | HastText | RootContent,
+  theme: Theme,
+  inheritedColor: string | undefined,
+): React.ReactNode {
+  if (node.type === 'text') {
+    // Use the color passed down from parent element, if any
+    return <Text color={inheritedColor}>{node.value}</Text>;
+  }
+
+  // Handle Element Nodes: Determine color and pass it down, don't wrap
+  if (node.type === 'element') {
+    const nodeClasses: string[] =
+      (node.properties?.className as string[]) || [];
+    let elementColor: string | undefined = undefined;
+
+    // Find color defined specifically for this element's class
+    for (let i = nodeClasses.length - 1; i >= 0; i--) {
+      const color = theme.getInkColor(nodeClasses[i]);
+      if (color) {
+        elementColor = color;
+        break;
+      }
+    }
+
+    // Determine the color to pass down: Use this element's specific color
+    // if found, otherwise, continue passing down the already inherited color.
+    const colorToPassDown = elementColor || inheritedColor;
+
+    // Recursively render children, passing the determined color down
+    // Ensure child type matches expected HAST structure (ElementContent is common)
+    const children = node.children?.map(
+      (child: ElementContent, index: number) => (
+        <React.Fragment key={index}>
+          {renderHastNode(child, theme, colorToPassDown)}
+        </React.Fragment>
+      ),
+    );
+
+    // Element nodes now only group children; color is applied by Text nodes.
+    // Use a React Fragment to avoid adding unnecessary elements.
+    return <React.Fragment>{children}</React.Fragment>;
+  }
+
+  // Handle Root Node: Start recursion with initial inherited color
+  if (node.type === 'root') {
+    // Check if children array is empty - this happens when lowlight can't detect language – fallback to plain text
+    if (!node.children || node.children.length === 0) {
+      return null;
+    }
+
+    // Pass down the initial inheritedColor (likely undefined from the top call)
+    // Ensure child type matches expected HAST structure (RootContent is common)
+    return node.children?.map((child: RootContent, index: number) => (
+      <React.Fragment key={index}>
+        {renderHastNode(child, theme, inheritedColor)}
+      </React.Fragment>
+    ));
+  }
+
+  // Handle unknown or unsupported node types
+  return null;
+}
+
+/**
+ * Renders syntax-highlighted code for Ink applications using a selected theme.
+ *
+ * @param code The code string to highlight.
+ * @param language The language identifier (e.g., 'javascript', 'css', 'html')
+ * @returns A React.ReactNode containing Ink <Text> elements for the highlighted code.
+ */
+export function colorizeCode(
+  code: string,
+  language: string | null,
+  availableHeight?: number,
+  maxWidth?: number,
+): React.ReactNode {
+  const codeToHighlight = code.replace(/\n$/, '');
+  const activeTheme = themeManager.getActiveTheme();
+
+  try {
+    // Render the HAST tree using the adapted theme
+    // Apply the theme's default foreground color to the top-level Text element
+    let lines = codeToHighlight.split('\n');
+    const padWidth = String(lines.length).length; // Calculate padding width based on number of lines
+
+    let hiddenLinesCount = 0;
+
+    // Optimization to avoid highlighting lines that cannot possibly be displayed.
+    if (availableHeight !== undefined) {
+      availableHeight = Math.max(availableHeight, MINIMUM_MAX_HEIGHT);
+      if (lines.length > availableHeight) {
+        const sliceIndex = lines.length - availableHeight;
+        hiddenLinesCount = sliceIndex;
+        lines = lines.slice(sliceIndex);
+      }
+    }
+
+    const getHighlightedLines = (line: string) =>
+      !language || !lowlight.registered(language)
+        ? lowlight.highlightAuto(line)
+        : lowlight.highlight(language, line);
+
+    return (
+      <MaxSizedBox
+        maxHeight={availableHeight}
+        maxWidth={maxWidth}
+        additionalHiddenLinesCount={hiddenLinesCount}
+        overflowDirection="top"
+      >
+        {lines.map((line, index) => {
+          const renderedNode = renderHastNode(
+            getHighlightedLines(line),
+            activeTheme,
+            undefined,
+          );
+
+          const contentToRender = renderedNode !== null ? renderedNode : line;
+          return (
+            <Box key={index}>
+              <Text color={activeTheme.colors.Gray}>
+                {`${String(index + 1 + hiddenLinesCount).padStart(padWidth, ' ')} `}
+              </Text>
+              <Text color={activeTheme.defaultColor} wrap="wrap">
+                {contentToRender}
+              </Text>
+            </Box>
+          );
+        })}
+      </MaxSizedBox>
+    );
+  } catch (error) {
+    console.error(
+      `[colorizeCode] Error highlighting code for language "${language}":`,
+      error,
+    );
+    // Fallback to plain text with default color on error
+    // Also display line numbers in fallback
+    const lines = codeToHighlight.split('\n');
+    const padWidth = String(lines.length).length; // Calculate padding width based on number of lines
+    return (
+      <MaxSizedBox
+        maxHeight={availableHeight}
+        maxWidth={maxWidth}
+        overflowDirection="top"
+      >
+        {lines.map((line, index) => (
+          <Box key={index}>
+            <Text color={activeTheme.defaultColor}>
+              {`${String(index + 1).padStart(padWidth, ' ')} `}
+            </Text>
+            <Text color={activeTheme.colors.Gray}>{line}</Text>
+          </Box>
+        ))}
+      </MaxSizedBox>
+    );
+  }
+}

packages/cli/src/ui/utils/ConsolePatcher.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import util from 'util';
+import { ConsoleMessageItem } from '../types.js';
+
+interface ConsolePatcherParams {
+  onNewMessage: (message: Omit<ConsoleMessageItem, 'id'>) => void;
+  debugMode: boolean;
+}
+
+export class ConsolePatcher {
+  private originalConsoleLog = console.log;
+  private originalConsoleWarn = console.warn;
+  private originalConsoleError = console.error;
+  private originalConsoleDebug = console.debug;
+
+  private params: ConsolePatcherParams;
+
+  constructor(params: ConsolePatcherParams) {
+    this.params = params;
+  }
+
+  patch() {
+    console.log = this.patchConsoleMethod('log', this.originalConsoleLog);
+    console.warn = this.patchConsoleMethod('warn', this.originalConsoleWarn);
+    console.error = this.patchConsoleMethod('error', this.originalConsoleError);
+    console.debug = this.patchConsoleMethod('debug', this.originalConsoleDebug);
+  }
+
+  cleanup = () => {
+    console.log = this.originalConsoleLog;
+    console.warn = this.originalConsoleWarn;
+    console.error = this.originalConsoleError;
+    console.debug = this.originalConsoleDebug;
+  };
+
+  private formatArgs = (args: unknown[]): string => util.format(...args);
+
+  private patchConsoleMethod =
+    (
+      type: 'log' | 'warn' | 'error' | 'debug',
+      originalMethod: (...args: unknown[]) => void,
+    ) =>
+    (...args: unknown[]) => {
+      if (this.params.debugMode) {
+        originalMethod.apply(console, args);
+      }
+
+      if (type !== 'debug' || this.params.debugMode) {
+        this.params.onNewMessage({
+          type,
+          content: this.formatArgs(args),
+          count: 1,
+        });
+      }
+    };
+}

packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { Text } from 'ink';
+import { Colors } from '../colors.js';
+import stringWidth from 'string-width';
+
+// Constants for Markdown parsing
+const BOLD_MARKER_LENGTH = 2; // For "**"
+const ITALIC_MARKER_LENGTH = 1; // For "*" or "_"
+const STRIKETHROUGH_MARKER_LENGTH = 2; // For "~~"
+const INLINE_CODE_MARKER_LENGTH = 1; // For "`"
+const UNDERLINE_TAG_START_LENGTH = 3; // For "<u>"
+const UNDERLINE_TAG_END_LENGTH = 4; // For "</u>"
+
+interface RenderInlineProps {
+  text: string;
+}
+
+const RenderInlineInternal: React.FC<RenderInlineProps> = ({ text }) => {
+  const nodes: React.ReactNode[] = [];
+  let lastIndex = 0;
+  const inlineRegex =
+    /(\*\*.*?\*\*|\*.*?\*|_.*?_|~~.*?~~|\[.*?\]\(.*?\)|`+.+?`+|<u>.*?<\/u>)/g;
+  let match;
+
+  while ((match = inlineRegex.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      nodes.push(
+        <Text key={`t-${lastIndex}`}>
+          {text.slice(lastIndex, match.index)}
+        </Text>,
+      );
+    }
+
+    const fullMatch = match[0];
+    let renderedNode: React.ReactNode = null;
+    const key = `m-${match.index}`;
+
+    try {
+      if (
+        fullMatch.startsWith('**') &&
+        fullMatch.endsWith('**') &&
+        fullMatch.length > BOLD_MARKER_LENGTH * 2
+      ) {
+        renderedNode = (
+          <Text key={key} bold>
+            {fullMatch.slice(BOLD_MARKER_LENGTH, -BOLD_MARKER_LENGTH)}
+          </Text>
+        );
+      } else if (
+        fullMatch.length > ITALIC_MARKER_LENGTH * 2 &&
+        ((fullMatch.startsWith('*') && fullMatch.endsWith('*')) ||
+          (fullMatch.startsWith('_') && fullMatch.endsWith('_'))) &&
+        !/\w/.test(text.substring(match.index - 1, match.index)) &&
+        !/\w/.test(
+          text.substring(inlineRegex.lastIndex, inlineRegex.lastIndex + 1),
+        ) &&
+        !/\S[./\\]/.test(text.substring(match.index - 2, match.index)) &&
+        !/[./\\]\S/.test(
+          text.substring(inlineRegex.lastIndex, inlineRegex.lastIndex + 2),
+        )
+      ) {
+        renderedNode = (
+          <Text key={key} italic>
+            {fullMatch.slice(ITALIC_MARKER_LENGTH, -ITALIC_MARKER_LENGTH)}
+          </Text>
+        );
+      } else if (
+        fullMatch.startsWith('~~') &&
+        fullMatch.endsWith('~~') &&
+        fullMatch.length > STRIKETHROUGH_MARKER_LENGTH * 2
+      ) {
+        renderedNode = (
+          <Text key={key} strikethrough>
+            {fullMatch.slice(
+              STRIKETHROUGH_MARKER_LENGTH,
+              -STRIKETHROUGH_MARKER_LENGTH,
+            )}
+          </Text>
+        );
+      } else if (
+        fullMatch.startsWith('`') &&
+        fullMatch.endsWith('`') &&
+        fullMatch.length > INLINE_CODE_MARKER_LENGTH
+      ) {
+        const codeMatch = fullMatch.match(/^(`+)(.+?)\1$/s);
+        if (codeMatch && codeMatch[2]) {
+          renderedNode = (
+            <Text key={key} color={Colors.AccentPurple}>
+              {codeMatch[2]}
+            </Text>
+          );
+        }
+      } else if (
+        fullMatch.startsWith('[') &&
+        fullMatch.includes('](') &&
+        fullMatch.endsWith(')')
+      ) {
+        const linkMatch = fullMatch.match(/\[(.*?)\]\((.*?)\)/);
+        if (linkMatch) {
+          const linkText = linkMatch[1];
+          const url = linkMatch[2];
+          renderedNode = (
+            <Text key={key}>
+              {linkText}
+              <Text color={Colors.AccentBlue}> ({url})</Text>
+            </Text>
+          );
+        }
+      } else if (
+        fullMatch.startsWith('<u>') &&
+        fullMatch.endsWith('</u>') &&
+        fullMatch.length >
+          UNDERLINE_TAG_START_LENGTH + UNDERLINE_TAG_END_LENGTH - 1 // -1 because length is compared to combined length of start and end tags
+      ) {
+        renderedNode = (
+          <Text key={key} underline>
+            {fullMatch.slice(
+              UNDERLINE_TAG_START_LENGTH,
+              -UNDERLINE_TAG_END_LENGTH,
+            )}
+          </Text>
+        );
+      }
+    } catch (e) {
+      console.error('Error parsing inline markdown part:', fullMatch, e);
+      renderedNode = null;
+    }
+
+    nodes.push(renderedNode ?? <Text key={key}>{fullMatch}</Text>);
+    lastIndex = inlineRegex.lastIndex;
+  }
+
+  if (lastIndex < text.length) {
+    nodes.push(<Text key={`t-${lastIndex}`}>{text.slice(lastIndex)}</Text>);
+  }
+
+  return <>{nodes.filter((node) => node !== null)}</>;
+};
+
+export const RenderInline = React.memo(RenderInlineInternal);
+
+/**
+ * Utility function to get the plain text length of a string with markdown formatting
+ * This is useful for calculating column widths in tables
+ */
+export const getPlainTextLength = (text: string): number => {
+  const cleanText = text
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/_(.*?)_/g, '$1')
+    .replace(/~~(.*?)~~/g, '$1')
+    .replace(/`(.*?)`/g, '$1')
+    .replace(/<u>(.*?)<\/u>/g, '$1')
+    .replace(/\[(.*?)\]\(.*?\)/g, '$1');
+  return stringWidth(cleanText);
+};

packages/cli/src/ui/utils/MarkdownDisplay.test.tsx

@@ -0,0 +1,176 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { render } from 'ink-testing-library';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MarkdownDisplay } from './MarkdownDisplay.js';
+
+describe('<MarkdownDisplay />', () => {
+  const baseProps = {
+    isPending: false,
+    terminalWidth: 80,
+    availableTerminalHeight: 40,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders nothing for empty text', () => {
+    const { lastFrame } = render(<MarkdownDisplay {...baseProps} text="" />);
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders a simple paragraph', () => {
+    const text = 'Hello, world.';
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders headers with correct levels', () => {
+    const text = `
+# Header 1
+## Header 2
+### Header 3
+#### Header 4
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders a fenced code block with a language', () => {
+    const text = '```javascript\nconst x = 1;\nconsole.log(x);\n```';
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders a fenced code block without a language', () => {
+    const text = '```\nplain text\n```';
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('handles unclosed (pending) code blocks', () => {
+    const text = '```typescript\nlet y = 2;';
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} isPending={true} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders unordered lists with different markers', () => {
+    const text = `
+- item A
+* item B
++ item C
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders nested unordered lists', () => {
+    const text = `
+* Level 1
+  * Level 2
+    * Level 3
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders ordered lists', () => {
+    const text = `
+1. First item
+2. Second item
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders horizontal rules', () => {
+    const text = `
+Hello
+---
+World
+***
+Test
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('renders tables correctly', () => {
+    const text = `
+| Header 1 | Header 2 |
+|----------|:--------:|
+| Cell 1   | Cell 2   |
+| Cell 3   | Cell 4   |
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('handles a table at the end of the input', () => {
+    const text = `
+Some text before.
+| A | B |
+|---|
+| 1 | 2 |`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('inserts a single space between paragraphs', () => {
+    const text = `Paragraph 1.
+
+Paragraph 2.`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+
+  it('correctly parses a mix of markdown elements', () => {
+    const text = `
+# Main Title
+
+Here is a paragraph.
+
+- List item 1
+- List item 2
+
+\`\`\`
+some code
+\`\`\`
+
+Another paragraph.
+`;
+    const { lastFrame } = render(
+      <MarkdownDisplay {...baseProps} text={text} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
+});

packages/cli/src/ui/utils/MarkdownDisplay.tsx

@@ -0,0 +1,409 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { Text, Box } from 'ink';
+import { Colors } from '../colors.js';
+import { colorizeCode } from './CodeColorizer.js';
+import { TableRenderer } from './TableRenderer.js';
+import { RenderInline } from './InlineMarkdownRenderer.js';
+
+interface MarkdownDisplayProps {
+  text: string;
+  isPending: boolean;
+  availableTerminalHeight?: number;
+  terminalWidth: number;
+}
+
+// Constants for Markdown parsing and rendering
+
+const EMPTY_LINE_HEIGHT = 1;
+const CODE_BLOCK_PREFIX_PADDING = 1;
+const LIST_ITEM_PREFIX_PADDING = 1;
+const LIST_ITEM_TEXT_FLEX_GROW = 1;
+
+const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
+  text,
+  isPending,
+  availableTerminalHeight,
+  terminalWidth,
+}) => {
+  if (!text) return <></>;
+
+  const lines = text.split('\n');
+  const headerRegex = /^ *(#{1,4}) +(.*)/;
+  const codeFenceRegex = /^ *(`{3,}|~{3,}) *(\w*?) *$/;
+  const ulItemRegex = /^([ \t]*)([-*+]) +(.*)/;
+  const olItemRegex = /^([ \t]*)(\d+)\. +(.*)/;
+  const hrRegex = /^ *([-*_] *){3,} *$/;
+  const tableRowRegex = /^\s*\|(.+)\|\s*$/;
+  const tableSeparatorRegex = /^\s*\|?\s*(:?-+:?)\s*(\|\s*(:?-+:?)\s*)+\|?\s*$/;
+
+  const contentBlocks: React.ReactNode[] = [];
+  let inCodeBlock = false;
+  let lastLineEmpty = true;
+  let codeBlockContent: string[] = [];
+  let codeBlockLang: string | null = null;
+  let codeBlockFence = '';
+  let inTable = false;
+  let tableRows: string[][] = [];
+  let tableHeaders: string[] = [];
+
+  function addContentBlock(block: React.ReactNode) {
+    if (block) {
+      contentBlocks.push(block);
+      lastLineEmpty = false;
+    }
+  }
+
+  lines.forEach((line, index) => {
+    const key = `line-${index}`;
+
+    if (inCodeBlock) {
+      const fenceMatch = line.match(codeFenceRegex);
+      if (
+        fenceMatch &&
+        fenceMatch[1].startsWith(codeBlockFence[0]) &&
+        fenceMatch[1].length >= codeBlockFence.length
+      ) {
+        addContentBlock(
+          <RenderCodeBlock
+            key={key}
+            content={codeBlockContent}
+            lang={codeBlockLang}
+            isPending={isPending}
+            availableTerminalHeight={availableTerminalHeight}
+            terminalWidth={terminalWidth}
+          />,
+        );
+        inCodeBlock = false;
+        codeBlockContent = [];
+        codeBlockLang = null;
+        codeBlockFence = '';
+      } else {
+        codeBlockContent.push(line);
+      }
+      return;
+    }
+
+    const codeFenceMatch = line.match(codeFenceRegex);
+    const headerMatch = line.match(headerRegex);
+    const ulMatch = line.match(ulItemRegex);
+    const olMatch = line.match(olItemRegex);
+    const hrMatch = line.match(hrRegex);
+    const tableRowMatch = line.match(tableRowRegex);
+    const tableSeparatorMatch = line.match(tableSeparatorRegex);
+
+    if (codeFenceMatch) {
+      inCodeBlock = true;
+      codeBlockFence = codeFenceMatch[1];
+      codeBlockLang = codeFenceMatch[2] || null;
+    } else if (tableRowMatch && !inTable) {
+      // Potential table start - check if next line is separator
+      if (
+        index + 1 < lines.length &&
+        lines[index + 1].match(tableSeparatorRegex)
+      ) {
+        inTable = true;
+        tableHeaders = tableRowMatch[1].split('|').map((cell) => cell.trim());
+        tableRows = [];
+      } else {
+        // Not a table, treat as regular text
+        addContentBlock(
+          <Box key={key}>
+            <Text wrap="wrap">
+              <RenderInline text={line} />
+            </Text>
+          </Box>,
+        );
+      }
+    } else if (inTable && tableSeparatorMatch) {
+      // Skip separator line - already handled
+    } else if (inTable && tableRowMatch) {
+      // Add table row
+      const cells = tableRowMatch[1].split('|').map((cell) => cell.trim());
+      // Ensure row has same column count as headers
+      while (cells.length < tableHeaders.length) {
+        cells.push('');
+      }
+      if (cells.length > tableHeaders.length) {
+        cells.length = tableHeaders.length;
+      }
+      tableRows.push(cells);
+    } else if (inTable && !tableRowMatch) {
+      // End of table
+      if (tableHeaders.length > 0 && tableRows.length > 0) {
+        addContentBlock(
+          <RenderTable
+            key={`table-${contentBlocks.length}`}
+            headers={tableHeaders}
+            rows={tableRows}
+            terminalWidth={terminalWidth}
+          />,
+        );
+      }
+      inTable = false;
+      tableRows = [];
+      tableHeaders = [];
+
+      // Process current line as normal
+      if (line.trim().length > 0) {
+        addContentBlock(
+          <Box key={key}>
+            <Text wrap="wrap">
+              <RenderInline text={line} />
+            </Text>
+          </Box>,
+        );
+      }
+    } else if (hrMatch) {
+      addContentBlock(
+        <Box key={key}>
+          <Text dimColor>---</Text>
+        </Box>,
+      );
+    } else if (headerMatch) {
+      const level = headerMatch[1].length;
+      const headerText = headerMatch[2];
+      let headerNode: React.ReactNode = null;
+      switch (level) {
+        case 1:
+          headerNode = (
+            <Text bold color={Colors.AccentCyan}>
+              <RenderInline text={headerText} />
+            </Text>
+          );
+          break;
+        case 2:
+          headerNode = (
+            <Text bold color={Colors.AccentBlue}>
+              <RenderInline text={headerText} />
+            </Text>
+          );
+          break;
+        case 3:
+          headerNode = (
+            <Text bold>
+              <RenderInline text={headerText} />
+            </Text>
+          );
+          break;
+        case 4:
+          headerNode = (
+            <Text italic color={Colors.Gray}>
+              <RenderInline text={headerText} />
+            </Text>
+          );
+          break;
+        default:
+          headerNode = (
+            <Text>
+              <RenderInline text={headerText} />
+            </Text>
+          );
+          break;
+      }
+      if (headerNode) addContentBlock(<Box key={key}>{headerNode}</Box>);
+    } else if (ulMatch) {
+      const leadingWhitespace = ulMatch[1];
+      const marker = ulMatch[2];
+      const itemText = ulMatch[3];
+      addContentBlock(
+        <RenderListItem
+          key={key}
+          itemText={itemText}
+          type="ul"
+          marker={marker}
+          leadingWhitespace={leadingWhitespace}
+        />,
+      );
+    } else if (olMatch) {
+      const leadingWhitespace = olMatch[1];
+      const marker = olMatch[2];
+      const itemText = olMatch[3];
+      addContentBlock(
+        <RenderListItem
+          key={key}
+          itemText={itemText}
+          type="ol"
+          marker={marker}
+          leadingWhitespace={leadingWhitespace}
+        />,
+      );
+    } else {
+      if (line.trim().length === 0 && !inCodeBlock) {
+        if (!lastLineEmpty) {
+          contentBlocks.push(
+            <Box key={`spacer-${index}`} height={EMPTY_LINE_HEIGHT} />,
+          );
+          lastLineEmpty = true;
+        }
+      } else {
+        addContentBlock(
+          <Box key={key}>
+            <Text wrap="wrap">
+              <RenderInline text={line} />
+            </Text>
+          </Box>,
+        );
+      }
+    }
+  });
+
+  if (inCodeBlock) {
+    addContentBlock(
+      <RenderCodeBlock
+        key="line-eof"
+        content={codeBlockContent}
+        lang={codeBlockLang}
+        isPending={isPending}
+        availableTerminalHeight={availableTerminalHeight}
+        terminalWidth={terminalWidth}
+      />,
+    );
+  }
+
+  // Handle table at end of content
+  if (inTable && tableHeaders.length > 0 && tableRows.length > 0) {
+    addContentBlock(
+      <RenderTable
+        key={`table-${contentBlocks.length}`}
+        headers={tableHeaders}
+        rows={tableRows}
+        terminalWidth={terminalWidth}
+      />,
+    );
+  }
+
+  return <>{contentBlocks}</>;
+};
+
+// Helper functions (adapted from static methods of MarkdownRenderer)
+
+interface RenderCodeBlockProps {
+  content: string[];
+  lang: string | null;
+  isPending: boolean;
+  availableTerminalHeight?: number;
+  terminalWidth: number;
+}
+
+const RenderCodeBlockInternal: React.FC<RenderCodeBlockProps> = ({
+  content,
+  lang,
+  isPending,
+  availableTerminalHeight,
+  terminalWidth,
+}) => {
+  const MIN_LINES_FOR_MESSAGE = 1; // Minimum lines to show before the "generating more" message
+  const RESERVED_LINES = 2; // Lines reserved for the message itself and potential padding
+
+  if (isPending && availableTerminalHeight !== undefined) {
+    const MAX_CODE_LINES_WHEN_PENDING = Math.max(
+      0,
+      availableTerminalHeight - RESERVED_LINES,
+    );
+
+    if (content.length > MAX_CODE_LINES_WHEN_PENDING) {
+      if (MAX_CODE_LINES_WHEN_PENDING < MIN_LINES_FOR_MESSAGE) {
+        // Not enough space to even show the message meaningfully
+        return (
+          <Box paddingLeft={CODE_BLOCK_PREFIX_PADDING}>
+            <Text color={Colors.Gray}>... code is being written ...</Text>
+          </Box>
+        );
+      }
+      const truncatedContent = content.slice(0, MAX_CODE_LINES_WHEN_PENDING);
+      const colorizedTruncatedCode = colorizeCode(
+        truncatedContent.join('\n'),
+        lang,
+        availableTerminalHeight,
+        terminalWidth - CODE_BLOCK_PREFIX_PADDING,
+      );
+      return (
+        <Box paddingLeft={CODE_BLOCK_PREFIX_PADDING} flexDirection="column">
+          {colorizedTruncatedCode}
+          <Text color={Colors.Gray}>... generating more ...</Text>
+        </Box>
+      );
+    }
+  }
+
+  const fullContent = content.join('\n');
+  const colorizedCode = colorizeCode(
+    fullContent,
+    lang,
+    availableTerminalHeight,
+    terminalWidth - CODE_BLOCK_PREFIX_PADDING,
+  );
+
+  return (
+    <Box
+      paddingLeft={CODE_BLOCK_PREFIX_PADDING}
+      flexDirection="column"
+      width={terminalWidth}
+      flexShrink={0}
+    >
+      {colorizedCode}
+    </Box>
+  );
+};
+
+const RenderCodeBlock = React.memo(RenderCodeBlockInternal);
+
+interface RenderListItemProps {
+  itemText: string;
+  type: 'ul' | 'ol';
+  marker: string;
+  leadingWhitespace?: string;
+}
+
+const RenderListItemInternal: React.FC<RenderListItemProps> = ({
+  itemText,
+  type,
+  marker,
+  leadingWhitespace = '',
+}) => {
+  const prefix = type === 'ol' ? `${marker}. ` : `${marker} `;
+  const prefixWidth = prefix.length;
+  const indentation = leadingWhitespace.length;
+
+  return (
+    <Box
+      paddingLeft={indentation + LIST_ITEM_PREFIX_PADDING}
+      flexDirection="row"
+    >
+      <Box width={prefixWidth}>
+        <Text>{prefix}</Text>
+      </Box>
+      <Box flexGrow={LIST_ITEM_TEXT_FLEX_GROW}>
+        <Text wrap="wrap">
+          <RenderInline text={itemText} />
+        </Text>
+      </Box>
+    </Box>
+  );
+};
+
+const RenderListItem = React.memo(RenderListItemInternal);
+
+interface RenderTableProps {
+  headers: string[];
+  rows: string[][];
+  terminalWidth: number;
+}
+
+const RenderTableInternal: React.FC<RenderTableProps> = ({
+  headers,
+  rows,
+  terminalWidth,
+}) => (
+  <TableRenderer headers={headers} rows={rows} terminalWidth={terminalWidth} />
+);
+
+const RenderTable = React.memo(RenderTableInternal);
+
+export const MarkdownDisplay = React.memo(MarkdownDisplayInternal);

packages/cli/src/ui/utils/TableRenderer.tsx

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { Text, Box } from 'ink';
+import { Colors } from '../colors.js';
+import { RenderInline, getPlainTextLength } from './InlineMarkdownRenderer.js';
+
+interface TableRendererProps {
+  headers: string[];
+  rows: string[][];
+  terminalWidth: number;
+}
+
+/**
+ * Custom table renderer for markdown tables
+ * We implement our own instead of using ink-table due to module compatibility issues
+ */
+export const TableRenderer: React.FC<TableRendererProps> = ({
+  headers,
+  rows,
+  terminalWidth,
+}) => {
+  // Calculate column widths using actual display width after markdown processing
+  const columnWidths = headers.map((header, index) => {
+    const headerWidth = getPlainTextLength(header);
+    const maxRowWidth = Math.max(
+      ...rows.map((row) => getPlainTextLength(row[index] || '')),
+    );
+    return Math.max(headerWidth, maxRowWidth) + 2; // Add padding
+  });
+
+  // Ensure table fits within terminal width
+  const totalWidth = columnWidths.reduce((sum, width) => sum + width + 1, 1);
+  const scaleFactor =
+    totalWidth > terminalWidth ? terminalWidth / totalWidth : 1;
+  const adjustedWidths = columnWidths.map((width) =>
+    Math.floor(width * scaleFactor),
+  );
+
+  // Helper function to render a cell with proper width
+  const renderCell = (
+    content: string,
+    width: number,
+    isHeader = false,
+  ): React.ReactNode => {
+    const contentWidth = Math.max(0, width - 2);
+    const displayWidth = getPlainTextLength(content);
+
+    let cellContent = content;
+    if (displayWidth > contentWidth) {
+      if (contentWidth <= 3) {
+        // Just truncate by character count
+        cellContent = content.substring(
+          0,
+          Math.min(content.length, contentWidth),
+        );
+      } else {
+        // Truncate preserving markdown formatting using binary search
+        let left = 0;
+        let right = content.length;
+        let bestTruncated = content;
+
+        // Binary search to find the optimal truncation point
+        while (left <= right) {
+          const mid = Math.floor((left + right) / 2);
+          const candidate = content.substring(0, mid);
+          const candidateWidth = getPlainTextLength(candidate);
+
+          if (candidateWidth <= contentWidth - 3) {
+            bestTruncated = candidate;
+            left = mid + 1;
+          } else {
+            right = mid - 1;
+          }
+        }
+
+        cellContent = bestTruncated + '...';
+      }
+    }
+
+    // Calculate exact padding needed
+    const actualDisplayWidth = getPlainTextLength(cellContent);
+    const paddingNeeded = Math.max(0, contentWidth - actualDisplayWidth);
+
+    return (
+      <Text>
+        {isHeader ? (
+          <Text bold color={Colors.AccentCyan}>
+            <RenderInline text={cellContent} />
+          </Text>
+        ) : (
+          <RenderInline text={cellContent} />
+        )}
+        {' '.repeat(paddingNeeded)}
+      </Text>
+    );
+  };
+
+  // Helper function to render border
+  const renderBorder = (type: 'top' | 'middle' | 'bottom'): React.ReactNode => {
+    const chars = {
+      top: { left: '┌', middle: '┬', right: '┐', horizontal: '─' },
+      middle: { left: '├', middle: '┼', right: '┤', horizontal: '─' },
+      bottom: { left: '└', middle: '┴', right: '┘', horizontal: '─' },
+    };
+
+    const char = chars[type];
+    const borderParts = adjustedWidths.map((w) => char.horizontal.repeat(w));
+    const border = char.left + borderParts.join(char.middle) + char.right;
+
+    return <Text>{border}</Text>;
+  };
+
+  // Helper function to render a table row
+  const renderRow = (cells: string[], isHeader = false): React.ReactNode => {
+    const renderedCells = cells.map((cell, index) => {
+      const width = adjustedWidths[index] || 0;
+      return renderCell(cell || '', width, isHeader);
+    });
+
+    return (
+      <Text>
+        │{' '}
+        {renderedCells.map((cell, index) => (
+          <React.Fragment key={index}>
+            {cell}
+            {index < renderedCells.length - 1 ? ' │ ' : ''}
+          </React.Fragment>
+        ))}{' '}
+        │
+      </Text>
+    );
+  };
+
+  return (
+    <Box flexDirection="column" marginY={1}>
+      {/* Top border */}
+      {renderBorder('top')}
+
+      {/* Header row */}
+      {renderRow(headers, true)}
+
+      {/* Middle border */}
+      {renderBorder('middle')}
+
+      {/* Data rows */}
+      {rows.map((row, index) => (
+        <React.Fragment key={index}>{renderRow(row)}</React.Fragment>
+      ))}
+
+      {/* Bottom border */}
+      {renderBorder('bottom')}
+    </Box>
+  );
+};

packages/cli/src/ui/utils/__snapshots__/MarkdownDisplay.test.tsx.snap

@@ -0,0 +1,89 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`<MarkdownDisplay /> > correctly parses a mix of markdown elements 1`] = `
+"Main Title
+
+Here is a paragraph.
+
+ - List item 1
+ - List item 2
+
+ 1 some code
+
+Another paragraph.
+"
+`;
+
+exports[`<MarkdownDisplay /> > handles a table at the end of the input 1`] = `
+"Some text before.
+| A | B |
+|---|
+| 1 | 2 |"
+`;
+
+exports[`<MarkdownDisplay /> > handles unclosed (pending) code blocks 1`] = `" 1 let y = 2;"`;
+
+exports[`<MarkdownDisplay /> > inserts a single space between paragraphs 1`] = `
+"Paragraph 1.
+
+Paragraph 2."
+`;
+
+exports[`<MarkdownDisplay /> > renders a fenced code block with a language 1`] = `
+" 1 const x = 1;
+ 2 console.log(x);"
+`;
+
+exports[`<MarkdownDisplay /> > renders a fenced code block without a language 1`] = `" 1 plain text"`;
+
+exports[`<MarkdownDisplay /> > renders a simple paragraph 1`] = `"Hello, world."`;
+
+exports[`<MarkdownDisplay /> > renders headers with correct levels 1`] = `
+"Header 1
+Header 2
+Header 3
+Header 4
+"
+`;
+
+exports[`<MarkdownDisplay /> > renders horizontal rules 1`] = `
+"Hello
+---
+World
+---
+Test
+"
+`;
+
+exports[`<MarkdownDisplay /> > renders nested unordered lists 1`] = `
+" * Level 1
+   * Level 2
+     * Level 3
+"
+`;
+
+exports[`<MarkdownDisplay /> > renders nothing for empty text 1`] = `""`;
+
+exports[`<MarkdownDisplay /> > renders ordered lists 1`] = `
+" 1. First item
+ 2. Second item
+"
+`;
+
+exports[`<MarkdownDisplay /> > renders tables correctly 1`] = `
+"
+┌──────────┬──────────┐
+│ Header 1 │ Header 2 │
+├──────────┼──────────┤
+│ Cell 1   │ Cell 2   │
+│ Cell 3   │ Cell 4   │
+└──────────┴──────────┘
+"
+`;
+
+exports[`<MarkdownDisplay /> > renders unordered lists with different markers 1`] = `
+" - item A
+ * item B
+ + item C
+"
+`;

packages/cli/src/ui/utils/clipboardUtils.test.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  clipboardHasImage,
+  saveClipboardImage,
+  cleanupOldClipboardImages,
+} from './clipboardUtils.js';
+
+describe('clipboardUtils', () => {
+  describe('clipboardHasImage', () => {
+    it('should return false on non-macOS platforms', async () => {
+      if (process.platform !== 'darwin') {
+        const result = await clipboardHasImage();
+        expect(result).toBe(false);
+      } else {
+        // Skip on macOS as it would require actual clipboard state
+        expect(true).toBe(true);
+      }
+    });
+
+    it('should return boolean on macOS', async () => {
+      if (process.platform === 'darwin') {
+        const result = await clipboardHasImage();
+        expect(typeof result).toBe('boolean');
+      } else {
+        // Skip on non-macOS
+        expect(true).toBe(true);
+      }
+    });
+  });
+
+  describe('saveClipboardImage', () => {
+    it('should return null on non-macOS platforms', async () => {
+      if (process.platform !== 'darwin') {
+        const result = await saveClipboardImage();
+        expect(result).toBe(null);
+      } else {
+        // Skip on macOS
+        expect(true).toBe(true);
+      }
+    });
+
+    it('should handle errors gracefully', async () => {
+      // Test with invalid directory (should not throw)
+      const result = await saveClipboardImage(
+        '/invalid/path/that/does/not/exist',
+      );
+
+      if (process.platform === 'darwin') {
+        // On macOS, might return null due to various errors
+        expect(result === null || typeof result === 'string').toBe(true);
+      } else {
+        // On other platforms, should always return null
+        expect(result).toBe(null);
+      }
+    });
+  });
+
+  describe('cleanupOldClipboardImages', () => {
+    it('should not throw errors', async () => {
+      // Should handle missing directories gracefully
+      await expect(
+        cleanupOldClipboardImages('/path/that/does/not/exist'),
+      ).resolves.not.toThrow();
+    });
+
+    it('should complete without errors on valid directory', async () => {
+      await expect(cleanupOldClipboardImages('.')).resolves.not.toThrow();
+    });
+  });
+});

packages/cli/src/ui/utils/clipboardUtils.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * Checks if the system clipboard contains an image (macOS only for now)
+ * @returns true if clipboard contains an image
+ */
+export async function clipboardHasImage(): Promise<boolean> {
+  if (process.platform !== 'darwin') {
+    return false;
+  }
+
+  try {
+    // Use osascript to check clipboard type
+    const { stdout } = await execAsync(
+      `osascript -e 'clipboard info' 2>/dev/null | grep -qE "«class PNGf»|TIFF picture|JPEG picture|GIF picture|«class JPEG»|«class TIFF»" && echo "true" || echo "false"`,
+      { shell: '/bin/bash' },
+    );
+    return stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Saves the image from clipboard to a temporary file (macOS only for now)
+ * @param targetDir The target directory to create temp files within
+ * @returns The path to the saved image file, or null if no image or error
+ */
+export async function saveClipboardImage(
+  targetDir?: string,
+): Promise<string | null> {
+  if (process.platform !== 'darwin') {
+    return null;
+  }
+
+  try {
+    // Create a temporary directory for clipboard images within the target directory
+    // This avoids security restrictions on paths outside the target directory
+    const baseDir = targetDir || process.cwd();
+    const tempDir = path.join(baseDir, '.gemini-clipboard');
+    await fs.mkdir(tempDir, { recursive: true });
+
+    // Generate a unique filename with timestamp
+    const timestamp = new Date().getTime();
+
+    // Try different image formats in order of preference
+    const formats = [
+      { class: 'PNGf', extension: 'png' },
+      { class: 'JPEG', extension: 'jpg' },
+      { class: 'TIFF', extension: 'tiff' },
+      { class: 'GIFf', extension: 'gif' },
+    ];
+
+    for (const format of formats) {
+      const tempFilePath = path.join(
+        tempDir,
+        `clipboard-${timestamp}.${format.extension}`,
+      );
+
+      // Try to save clipboard as this format
+      const script = `
+        try
+          set imageData to the clipboard as «class ${format.class}»
+          set fileRef to open for access POSIX file "${tempFilePath}" with write permission
+          write imageData to fileRef
+          close access fileRef
+          return "success"
+        on error errMsg
+          try
+            close access POSIX file "${tempFilePath}"
+          end try
+          return "error"
+        end try
+      `;
+
+      const { stdout } = await execAsync(`osascript -e '${script}'`);
+
+      if (stdout.trim() === 'success') {
+        // Verify the file was created and has content
+        try {
+          const stats = await fs.stat(tempFilePath);
+          if (stats.size > 0) {
+            return tempFilePath;
+          }
+        } catch {
+          // File doesn't exist, continue to next format
+        }
+      }
+
+      // Clean up failed attempt
+      try {
+        await fs.unlink(tempFilePath);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+
+    // No format worked
+    return null;
+  } catch (error) {
+    console.error('Error saving clipboard image:', error);
+    return null;
+  }
+}
+
+/**
+ * Cleans up old temporary clipboard image files
+ * Removes files older than 1 hour
+ * @param targetDir The target directory where temp files are stored
+ */
+export async function cleanupOldClipboardImages(
+  targetDir?: string,
+): Promise<void> {
+  try {
+    const baseDir = targetDir || process.cwd();
+    const tempDir = path.join(baseDir, '.gemini-clipboard');
+    const files = await fs.readdir(tempDir);
+    const oneHourAgo = Date.now() - 60 * 60 * 1000;
+
+    for (const file of files) {
+      if (
+        file.startsWith('clipboard-') &&
+        (file.endsWith('.png') ||
+          file.endsWith('.jpg') ||
+          file.endsWith('.tiff') ||
+          file.endsWith('.gif'))
+      ) {
+        const filePath = path.join(tempDir, file);
+        const stats = await fs.stat(filePath);
+        if (stats.mtimeMs < oneHourAgo) {
+          await fs.unlink(filePath);
+        }
+      }
+    }
+  } catch {
+    // Ignore errors in cleanup
+  }
+}

packages/cli/src/ui/utils/commandUtils.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Checks if a query string potentially represents an '@' command.
+ * It triggers if the query starts with '@' or contains '@' preceded by whitespace
+ * and followed by a non-whitespace character.
+ *
+ * @param query The input query string.
+ * @returns True if the query looks like an '@' command, false otherwise.
+ */
+export const isAtCommand = (query: string): boolean =>
+  // Check if starts with @ OR has a space, then @
+  query.startsWith('@') || /\s@/.test(query);
+
+/**
+ * Checks if a query string potentially represents an '/' command.
+ * It triggers if the query starts with '/'
+ *
+ * @param query The input query string.
+ * @returns True if the query looks like an '/' command, false otherwise.
+ */
+export const isSlashCommand = (query: string): boolean => query.startsWith('/');

packages/cli/src/ui/utils/computeStats.test.ts

@@ -0,0 +1,247 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  calculateAverageLatency,
+  calculateCacheHitRate,
+  calculateErrorRate,
+  computeSessionStats,
+} from './computeStats.js';
+import { ModelMetrics, SessionMetrics } from '../contexts/SessionContext.js';
+
+describe('calculateErrorRate', () => {
+  it('should return 0 if totalRequests is 0', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 0, totalErrors: 0, totalLatencyMs: 0 },
+      tokens: {
+        prompt: 0,
+        candidates: 0,
+        total: 0,
+        cached: 0,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateErrorRate(metrics)).toBe(0);
+  });
+
+  it('should calculate the error rate correctly', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 10, totalErrors: 2, totalLatencyMs: 0 },
+      tokens: {
+        prompt: 0,
+        candidates: 0,
+        total: 0,
+        cached: 0,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateErrorRate(metrics)).toBe(20);
+  });
+});
+
+describe('calculateAverageLatency', () => {
+  it('should return 0 if totalRequests is 0', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 0, totalErrors: 0, totalLatencyMs: 1000 },
+      tokens: {
+        prompt: 0,
+        candidates: 0,
+        total: 0,
+        cached: 0,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateAverageLatency(metrics)).toBe(0);
+  });
+
+  it('should calculate the average latency correctly', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 10, totalErrors: 0, totalLatencyMs: 1500 },
+      tokens: {
+        prompt: 0,
+        candidates: 0,
+        total: 0,
+        cached: 0,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateAverageLatency(metrics)).toBe(150);
+  });
+});
+
+describe('calculateCacheHitRate', () => {
+  it('should return 0 if prompt tokens is 0', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 0, totalErrors: 0, totalLatencyMs: 0 },
+      tokens: {
+        prompt: 0,
+        candidates: 0,
+        total: 0,
+        cached: 100,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateCacheHitRate(metrics)).toBe(0);
+  });
+
+  it('should calculate the cache hit rate correctly', () => {
+    const metrics: ModelMetrics = {
+      api: { totalRequests: 0, totalErrors: 0, totalLatencyMs: 0 },
+      tokens: {
+        prompt: 200,
+        candidates: 0,
+        total: 0,
+        cached: 50,
+        thoughts: 0,
+        tool: 0,
+      },
+    };
+    expect(calculateCacheHitRate(metrics)).toBe(25);
+  });
+});
+
+describe('computeSessionStats', () => {
+  it('should return all zeros for initial empty metrics', () => {
+    const metrics: SessionMetrics = {
+      models: {},
+      tools: {
+        totalCalls: 0,
+        totalSuccess: 0,
+        totalFail: 0,
+        totalDurationMs: 0,
+        totalDecisions: { accept: 0, reject: 0, modify: 0 },
+        byName: {},
+      },
+    };
+
+    const result = computeSessionStats(metrics);
+
+    expect(result).toEqual({
+      totalApiTime: 0,
+      totalToolTime: 0,
+      agentActiveTime: 0,
+      apiTimePercent: 0,
+      toolTimePercent: 0,
+      cacheEfficiency: 0,
+      totalDecisions: 0,
+      successRate: 0,
+      agreementRate: 0,
+      totalPromptTokens: 0,
+      totalCachedTokens: 0,
+    });
+  });
+
+  it('should correctly calculate API and tool time percentages', () => {
+    const metrics: SessionMetrics = {
+      models: {
+        'gemini-pro': {
+          api: { totalRequests: 1, totalErrors: 0, totalLatencyMs: 750 },
+          tokens: {
+            prompt: 10,
+            candidates: 10,
+            total: 20,
+            cached: 0,
+            thoughts: 0,
+            tool: 0,
+          },
+        },
+      },
+      tools: {
+        totalCalls: 1,
+        totalSuccess: 1,
+        totalFail: 0,
+        totalDurationMs: 250,
+        totalDecisions: { accept: 0, reject: 0, modify: 0 },
+        byName: {},
+      },
+    };
+
+    const result = computeSessionStats(metrics);
+
+    expect(result.totalApiTime).toBe(750);
+    expect(result.totalToolTime).toBe(250);
+    expect(result.agentActiveTime).toBe(1000);
+    expect(result.apiTimePercent).toBe(75);
+    expect(result.toolTimePercent).toBe(25);
+  });
+
+  it('should correctly calculate cache efficiency', () => {
+    const metrics: SessionMetrics = {
+      models: {
+        'gemini-pro': {
+          api: { totalRequests: 2, totalErrors: 0, totalLatencyMs: 1000 },
+          tokens: {
+            prompt: 150,
+            candidates: 10,
+            total: 160,
+            cached: 50,
+            thoughts: 0,
+            tool: 0,
+          },
+        },
+      },
+      tools: {
+        totalCalls: 0,
+        totalSuccess: 0,
+        totalFail: 0,
+        totalDurationMs: 0,
+        totalDecisions: { accept: 0, reject: 0, modify: 0 },
+        byName: {},
+      },
+    };
+
+    const result = computeSessionStats(metrics);
+
+    expect(result.cacheEfficiency).toBeCloseTo(33.33); // 50 / 150
+  });
+
+  it('should correctly calculate success and agreement rates', () => {
+    const metrics: SessionMetrics = {
+      models: {},
+      tools: {
+        totalCalls: 10,
+        totalSuccess: 8,
+        totalFail: 2,
+        totalDurationMs: 1000,
+        totalDecisions: { accept: 6, reject: 2, modify: 2 },
+        byName: {},
+      },
+    };
+
+    const result = computeSessionStats(metrics);
+
+    expect(result.successRate).toBe(80); // 8 / 10
+    expect(result.agreementRate).toBe(60); // 6 / 10
+  });
+
+  it('should handle division by zero gracefully', () => {
+    const metrics: SessionMetrics = {
+      models: {},
+      tools: {
+        totalCalls: 0,
+        totalSuccess: 0,
+        totalFail: 0,
+        totalDurationMs: 0,
+        totalDecisions: { accept: 0, reject: 0, modify: 0 },
+        byName: {},
+      },
+    };
+
+    const result = computeSessionStats(metrics);
+
+    expect(result.apiTimePercent).toBe(0);
+    expect(result.toolTimePercent).toBe(0);
+    expect(result.cacheEfficiency).toBe(0);
+    expect(result.successRate).toBe(0);
+    expect(result.agreementRate).toBe(0);
+  });
+});

packages/cli/src/ui/utils/computeStats.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  SessionMetrics,
+  ComputedSessionStats,
+  ModelMetrics,
+} from '../contexts/SessionContext.js';
+
+export function calculateErrorRate(metrics: ModelMetrics): number {
+  if (metrics.api.totalRequests === 0) {
+    return 0;
+  }
+  return (metrics.api.totalErrors / metrics.api.totalRequests) * 100;
+}
+
+export function calculateAverageLatency(metrics: ModelMetrics): number {
+  if (metrics.api.totalRequests === 0) {
+    return 0;
+  }
+  return metrics.api.totalLatencyMs / metrics.api.totalRequests;
+}
+
+export function calculateCacheHitRate(metrics: ModelMetrics): number {
+  if (metrics.tokens.prompt === 0) {
+    return 0;
+  }
+  return (metrics.tokens.cached / metrics.tokens.prompt) * 100;
+}
+
+export const computeSessionStats = (
+  metrics: SessionMetrics,
+): ComputedSessionStats => {
+  const { models, tools } = metrics;
+  const totalApiTime = Object.values(models).reduce(
+    (acc, model) => acc + model.api.totalLatencyMs,
+    0,
+  );
+  const totalToolTime = tools.totalDurationMs;
+  const agentActiveTime = totalApiTime + totalToolTime;
+  const apiTimePercent =
+    agentActiveTime > 0 ? (totalApiTime / agentActiveTime) * 100 : 0;
+  const toolTimePercent =
+    agentActiveTime > 0 ? (totalToolTime / agentActiveTime) * 100 : 0;
+
+  const totalCachedTokens = Object.values(models).reduce(
+    (acc, model) => acc + model.tokens.cached,
+    0,
+  );
+  const totalPromptTokens = Object.values(models).reduce(
+    (acc, model) => acc + model.tokens.prompt,
+    0,
+  );
+  const cacheEfficiency =
+    totalPromptTokens > 0 ? (totalCachedTokens / totalPromptTokens) * 100 : 0;
+
+  const totalDecisions =
+    tools.totalDecisions.accept +
+    tools.totalDecisions.reject +
+    tools.totalDecisions.modify;
+  const successRate =
+    tools.totalCalls > 0 ? (tools.totalSuccess / tools.totalCalls) * 100 : 0;
+  const agreementRate =
+    totalDecisions > 0
+      ? (tools.totalDecisions.accept / totalDecisions) * 100
+      : 0;
+
+  return {
+    totalApiTime,
+    totalToolTime,
+    agentActiveTime,
+    apiTimePercent,
+    toolTimePercent,
+    cacheEfficiency,
+    totalDecisions,
+    successRate,
+    agreementRate,
+    totalCachedTokens,
+    totalPromptTokens,
+  };
+};

packages/cli/src/ui/utils/displayUtils.test.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  getStatusColor,
+  TOOL_SUCCESS_RATE_HIGH,
+  TOOL_SUCCESS_RATE_MEDIUM,
+  USER_AGREEMENT_RATE_HIGH,
+  USER_AGREEMENT_RATE_MEDIUM,
+  CACHE_EFFICIENCY_HIGH,
+  CACHE_EFFICIENCY_MEDIUM,
+} from './displayUtils.js';
+import { Colors } from '../colors.js';
+
+describe('displayUtils', () => {
+  describe('getStatusColor', () => {
+    const thresholds = {
+      green: 80,
+      yellow: 50,
+    };
+
+    it('should return green for values >= green threshold', () => {
+      expect(getStatusColor(90, thresholds)).toBe(Colors.AccentGreen);
+      expect(getStatusColor(80, thresholds)).toBe(Colors.AccentGreen);
+    });
+
+    it('should return yellow for values < green and >= yellow threshold', () => {
+      expect(getStatusColor(79, thresholds)).toBe(Colors.AccentYellow);
+      expect(getStatusColor(50, thresholds)).toBe(Colors.AccentYellow);
+    });
+
+    it('should return red for values < yellow threshold', () => {
+      expect(getStatusColor(49, thresholds)).toBe(Colors.AccentRed);
+      expect(getStatusColor(0, thresholds)).toBe(Colors.AccentRed);
+    });
+
+    it('should return defaultColor for values < yellow threshold when provided', () => {
+      expect(
+        getStatusColor(49, thresholds, { defaultColor: Colors.Foreground }),
+      ).toBe(Colors.Foreground);
+    });
+  });
+
+  describe('Threshold Constants', () => {
+    it('should have the correct values', () => {
+      expect(TOOL_SUCCESS_RATE_HIGH).toBe(95);
+      expect(TOOL_SUCCESS_RATE_MEDIUM).toBe(85);
+      expect(USER_AGREEMENT_RATE_HIGH).toBe(75);
+      expect(USER_AGREEMENT_RATE_MEDIUM).toBe(45);
+      expect(CACHE_EFFICIENCY_HIGH).toBe(40);
+      expect(CACHE_EFFICIENCY_MEDIUM).toBe(15);
+    });
+  });
+});

packages/cli/src/ui/utils/displayUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Colors } from '../colors.js';
+
+// --- Thresholds ---
+export const TOOL_SUCCESS_RATE_HIGH = 95;
+export const TOOL_SUCCESS_RATE_MEDIUM = 85;
+
+export const USER_AGREEMENT_RATE_HIGH = 75;
+export const USER_AGREEMENT_RATE_MEDIUM = 45;
+
+export const CACHE_EFFICIENCY_HIGH = 40;
+export const CACHE_EFFICIENCY_MEDIUM = 15;
+
+// --- Color Logic ---
+export const getStatusColor = (
+  value: number,
+  thresholds: { green: number; yellow: number },
+  options: { defaultColor?: string } = {},
+) => {
+  if (value >= thresholds.green) {
+    return Colors.AccentGreen;
+  }
+  if (value >= thresholds.yellow) {
+    return Colors.AccentYellow;
+  }
+  return options.defaultColor || Colors.AccentRed;
+};

packages/cli/src/ui/utils/errorParsing.test.ts

@@ -0,0 +1,378 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseAndFormatApiError } from './errorParsing.js';
+import {
+  AuthType,
+  UserTierId,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  isProQuotaExceededError,
+} from '@qwen/qwen-code-core';
+
+describe('parseAndFormatApiError', () => {
+  const _enterpriseMessage =
+    'upgrade to a Gemini Code Assist Standard or Enterprise plan with higher limits';
+  const vertexMessage = 'request a quota increase through Vertex';
+  const geminiMessage = 'request a quota increase through AI Studio';
+
+  it('should format a valid API error JSON', () => {
+    const errorMessage =
+      'got status: 400 Bad Request. {"error":{"code":400,"message":"API key not valid. Please pass a valid API key.","status":"INVALID_ARGUMENT"}}';
+    const expected =
+      '[API Error: API key not valid. Please pass a valid API key. (Status: INVALID_ARGUMENT)]';
+    expect(parseAndFormatApiError(errorMessage)).toBe(expected);
+  });
+
+  it('should format a 429 API error with the default message', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Rate limit exceeded","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      undefined,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain('[API Error: Rate limit exceeded');
+    expect(result).toContain(
+      'Possible quota limitations in place or slow response times detected. Switching to the gemini-2.5-flash model',
+    );
+  });
+
+  it('should format a 429 API error with the personal message', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Rate limit exceeded","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain('[API Error: Rate limit exceeded');
+    expect(result).toContain(
+      'Possible quota limitations in place or slow response times detected. Switching to the gemini-2.5-flash model',
+    );
+  });
+
+  it('should format a 429 API error with the vertex message', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Rate limit exceeded","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(errorMessage, AuthType.USE_VERTEX_AI);
+    expect(result).toContain('[API Error: Rate limit exceeded');
+    expect(result).toContain(vertexMessage);
+  });
+
+  it('should return the original message if it is not a JSON error', () => {
+    const errorMessage = 'This is a plain old error message';
+    expect(parseAndFormatApiError(errorMessage)).toBe(
+      `[API Error: ${errorMessage}]`,
+    );
+  });
+
+  it('should return the original message for malformed JSON', () => {
+    const errorMessage = '[Stream Error: {"error": "malformed}';
+    expect(parseAndFormatApiError(errorMessage)).toBe(
+      `[API Error: ${errorMessage}]`,
+    );
+  });
+
+  it('should handle JSON that does not match the ApiError structure', () => {
+    const errorMessage = '[Stream Error: {"not_an_error": "some other json"}]';
+    expect(parseAndFormatApiError(errorMessage)).toBe(
+      `[API Error: ${errorMessage}]`,
+    );
+  });
+
+  it('should format a nested API error', () => {
+    const nestedErrorMessage = JSON.stringify({
+      error: {
+        code: 429,
+        message:
+          "Gemini 2.5 Pro Preview doesn't have a free quota tier. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits.",
+        status: 'RESOURCE_EXHAUSTED',
+      },
+    });
+
+    const errorMessage = JSON.stringify({
+      error: {
+        code: 429,
+        message: nestedErrorMessage,
+        status: 'Too Many Requests',
+      },
+    });
+
+    const result = parseAndFormatApiError(errorMessage, AuthType.USE_GEMINI);
+    expect(result).toContain('Gemini 2.5 Pro Preview');
+    expect(result).toContain(geminiMessage);
+  });
+
+  it('should format a StructuredError', () => {
+    const error: StructuredError = {
+      message: 'A structured error occurred',
+      status: 500,
+    };
+    const expected = '[API Error: A structured error occurred]';
+    expect(parseAndFormatApiError(error)).toBe(expected);
+  });
+
+  it('should format a 429 StructuredError with the vertex message', () => {
+    const error: StructuredError = {
+      message: 'Rate limit exceeded',
+      status: 429,
+    };
+    const result = parseAndFormatApiError(error, AuthType.USE_VERTEX_AI);
+    expect(result).toContain('[API Error: Rate limit exceeded]');
+    expect(result).toContain(vertexMessage);
+  });
+
+  it('should handle an unknown error type', () => {
+    const error = 12345;
+    const expected = '[API Error: An unknown error occurred.]';
+    expect(parseAndFormatApiError(error)).toBe(expected);
+  });
+
+  it('should format a 429 API error with Pro quota exceeded message for Google auth (Free tier)', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5 Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'Gemini 2.5 Pro Requests'",
+    );
+    expect(result).toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+    expect(result).toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+
+  it('should format a regular 429 API error with standard message for Google auth', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Rate limit exceeded","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain('[API Error: Rate limit exceeded');
+    expect(result).toContain(
+      'Possible quota limitations in place or slow response times detected. Switching to the gemini-2.5-flash model',
+    );
+    expect(result).not.toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+  });
+
+  it('should format a 429 API error with generic quota exceeded message for Google auth', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'GenerationRequests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'GenerationRequests'",
+    );
+    expect(result).toContain('You have reached your daily quota limit');
+    expect(result).not.toContain(
+      'You have reached your daily Gemini 2.5 Pro quota limit',
+    );
+  });
+
+  it('should prioritize Pro quota message over generic quota message for Google auth', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5 Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'Gemini 2.5 Pro Requests'",
+    );
+    expect(result).toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+    expect(result).not.toContain('You have reached your daily quota limit');
+  });
+
+  it('should format a 429 API error with Pro quota exceeded message for Google auth (Standard tier)', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5 Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      UserTierId.STANDARD,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'Gemini 2.5 Pro Requests'",
+    );
+    expect(result).toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+    expect(result).toContain(
+      'We appreciate you for choosing Gemini Code Assist and the Gemini CLI',
+    );
+    expect(result).not.toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+
+  it('should format a 429 API error with Pro quota exceeded message for Google auth (Legacy tier)', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5 Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      UserTierId.LEGACY,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'Gemini 2.5 Pro Requests'",
+    );
+    expect(result).toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+    expect(result).toContain(
+      'We appreciate you for choosing Gemini Code Assist and the Gemini CLI',
+    );
+    expect(result).not.toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+
+  it('should handle different Gemini 2.5 version strings in Pro quota exceeded errors', () => {
+    const errorMessage25 =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5 Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const errorMessagePreview =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'Gemini 2.5-preview Pro Requests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+
+    const result25 = parseAndFormatApiError(
+      errorMessage25,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    const resultPreview = parseAndFormatApiError(
+      errorMessagePreview,
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      'gemini-2.5-preview-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+
+    expect(result25).toContain(
+      'You have reached your daily gemini-2.5-pro quota limit',
+    );
+    expect(resultPreview).toContain(
+      'You have reached your daily gemini-2.5-preview-pro quota limit',
+    );
+    expect(result25).toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+    expect(resultPreview).toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+
+  it('should not match non-Pro models with similar version strings', () => {
+    // Test that Flash models with similar version strings don't match
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'Gemini 2.5 Flash Requests' and limit",
+      ),
+    ).toBe(false);
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'Gemini 2.5-preview Flash Requests' and limit",
+      ),
+    ).toBe(false);
+
+    // Test other model types
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'Gemini 2.5 Ultra Requests' and limit",
+      ),
+    ).toBe(false);
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'Gemini 2.5 Standard Requests' and limit",
+      ),
+    ).toBe(false);
+
+    // Test generic quota messages
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'GenerationRequests' and limit",
+      ),
+    ).toBe(false);
+    expect(
+      isProQuotaExceededError(
+        "Quota exceeded for quota metric 'EmbeddingRequests' and limit",
+      ),
+    ).toBe(false);
+  });
+
+  it('should format a generic quota exceeded message for Google auth (Standard tier)', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Quota exceeded for quota metric \'GenerationRequests\' and limit \'RequestsPerDay\' of service \'generativelanguage.googleapis.com\' for consumer \'project_number:123456789\'.","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      UserTierId.STANDARD,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain(
+      "[API Error: Quota exceeded for quota metric 'GenerationRequests'",
+    );
+    expect(result).toContain('You have reached your daily quota limit');
+    expect(result).toContain(
+      'We appreciate you for choosing Gemini Code Assist and the Gemini CLI',
+    );
+    expect(result).not.toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+
+  it('should format a regular 429 API error with standard message for Google auth (Standard tier)', () => {
+    const errorMessage =
+      'got status: 429 Too Many Requests. {"error":{"code":429,"message":"Rate limit exceeded","status":"RESOURCE_EXHAUSTED"}}';
+    const result = parseAndFormatApiError(
+      errorMessage,
+      AuthType.LOGIN_WITH_GOOGLE,
+      UserTierId.STANDARD,
+      'gemini-2.5-pro',
+      DEFAULT_GEMINI_FLASH_MODEL,
+    );
+    expect(result).toContain('[API Error: Rate limit exceeded');
+    expect(result).toContain(
+      'We appreciate you for choosing Gemini Code Assist and the Gemini CLI',
+    );
+    expect(result).not.toContain(
+      'upgrade to a Gemini Code Assist Standard or Enterprise plan',
+    );
+  });
+});

packages/cli/src/ui/utils/errorParsing.ts

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  AuthType,
+  UserTierId,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  DEFAULT_GEMINI_MODEL,
+  isProQuotaExceededError,
+  isGenericQuotaExceededError,
+  isApiError,
+  isStructuredError,
+} from '@qwen/qwen-code-core';
+// Free Tier message functions
+const getRateLimitErrorMessageGoogleFree = (
+  fallbackModel: string = DEFAULT_GEMINI_FLASH_MODEL,
+) =>
+  `\nPossible quota limitations in place or slow response times detected. Switching to the ${fallbackModel} model for the rest of this session.`;
+
+const getRateLimitErrorMessageGoogleProQuotaFree = (
+  currentModel: string = DEFAULT_GEMINI_MODEL,
+  fallbackModel: string = DEFAULT_GEMINI_FLASH_MODEL,
+) =>
+  `\nYou have reached your daily ${currentModel} quota limit. You will be switched to the ${fallbackModel} model for the rest of this session. To increase your limits, upgrade to a Gemini Code Assist Standard or Enterprise plan with higher limits at https://goo.gle/set-up-gemini-code-assist, or use /auth to switch to using a paid API key from AI Studio at https://aistudio.google.com/apikey`;
+
+const getRateLimitErrorMessageGoogleGenericQuotaFree = () =>
+  `\nYou have reached your daily quota limit. To increase your limits, upgrade to a Gemini Code Assist Standard or Enterprise plan with higher limits at https://goo.gle/set-up-gemini-code-assist, or use /auth to switch to using a paid API key from AI Studio at https://aistudio.google.com/apikey`;
+
+// Legacy/Standard Tier message functions
+const getRateLimitErrorMessageGooglePaid = (
+  fallbackModel: string = DEFAULT_GEMINI_FLASH_MODEL,
+) =>
+  `\nPossible quota limitations in place or slow response times detected. Switching to the ${fallbackModel} model for the rest of this session. We appreciate you for choosing Gemini Code Assist and the Gemini CLI.`;
+
+const getRateLimitErrorMessageGoogleProQuotaPaid = (
+  currentModel: string = DEFAULT_GEMINI_MODEL,
+  fallbackModel: string = DEFAULT_GEMINI_FLASH_MODEL,
+) =>
+  `\nYou have reached your daily ${currentModel} quota limit. You will be switched to the ${fallbackModel} model for the rest of this session. We appreciate you for choosing Gemini Code Assist and the Gemini CLI. To continue accessing the ${currentModel} model today, consider using /auth to switch to using a paid API key from AI Studio at https://aistudio.google.com/apikey`;
+
+const getRateLimitErrorMessageGoogleGenericQuotaPaid = (
+  currentModel: string = DEFAULT_GEMINI_MODEL,
+) =>
+  `\nYou have reached your daily quota limit. We appreciate you for choosing Gemini Code Assist and the Gemini CLI. To continue accessing the ${currentModel} model today, consider using /auth to switch to using a paid API key from AI Studio at https://aistudio.google.com/apikey`;
+const RATE_LIMIT_ERROR_MESSAGE_USE_GEMINI =
+  '\nPlease wait and try again later. To increase your limits, request a quota increase through AI Studio, or switch to another /auth method';
+const RATE_LIMIT_ERROR_MESSAGE_VERTEX =
+  '\nPlease wait and try again later. To increase your limits, request a quota increase through Vertex, or switch to another /auth method';
+const getRateLimitErrorMessageDefault = (
+  fallbackModel: string = DEFAULT_GEMINI_FLASH_MODEL,
+) =>
+  `\nPossible quota limitations in place or slow response times detected. Switching to the ${fallbackModel} model for the rest of this session.`;
+
+function getRateLimitMessage(
+  authType?: AuthType,
+  error?: unknown,
+  userTier?: UserTierId,
+  currentModel?: string,
+  fallbackModel?: string,
+): string {
+  switch (authType) {
+    case AuthType.LOGIN_WITH_GOOGLE: {
+      // Determine if user is on a paid tier (Legacy or Standard) - default to FREE if not specified
+      const isPaidTier =
+        userTier === UserTierId.LEGACY || userTier === UserTierId.STANDARD;
+
+      if (isProQuotaExceededError(error)) {
+        return isPaidTier
+          ? getRateLimitErrorMessageGoogleProQuotaPaid(
+              currentModel || DEFAULT_GEMINI_MODEL,
+              fallbackModel,
+            )
+          : getRateLimitErrorMessageGoogleProQuotaFree(
+              currentModel || DEFAULT_GEMINI_MODEL,
+              fallbackModel,
+            );
+      } else if (isGenericQuotaExceededError(error)) {
+        return isPaidTier
+          ? getRateLimitErrorMessageGoogleGenericQuotaPaid(
+              currentModel || DEFAULT_GEMINI_MODEL,
+            )
+          : getRateLimitErrorMessageGoogleGenericQuotaFree();
+      } else {
+        return isPaidTier
+          ? getRateLimitErrorMessageGooglePaid(fallbackModel)
+          : getRateLimitErrorMessageGoogleFree(fallbackModel);
+      }
+    }
+    case AuthType.USE_GEMINI:
+      return RATE_LIMIT_ERROR_MESSAGE_USE_GEMINI;
+    case AuthType.USE_VERTEX_AI:
+      return RATE_LIMIT_ERROR_MESSAGE_VERTEX;
+    default:
+      return getRateLimitErrorMessageDefault(fallbackModel);
+  }
+}
+
+export function parseAndFormatApiError(
+  error: unknown,
+  authType?: AuthType,
+  userTier?: UserTierId,
+  currentModel?: string,
+  fallbackModel?: string,
+): string {
+  if (isStructuredError(error)) {
+    let text = `[API Error: ${error.message}]`;
+    if (error.status === 429) {
+      text += getRateLimitMessage(
+        authType,
+        error,
+        userTier,
+        currentModel,
+        fallbackModel,
+      );
+    }
+    return text;
+  }
+
+  // The error message might be a string containing a JSON object.
+  if (typeof error === 'string') {
+    const jsonStart = error.indexOf('{');
+    if (jsonStart === -1) {
+      return `[API Error: ${error}]`; // Not a JSON error, return as is.
+    }
+
+    const jsonString = error.substring(jsonStart);
+
+    try {
+      const parsedError = JSON.parse(jsonString) as unknown;
+      if (isApiError(parsedError)) {
+        let finalMessage = parsedError.error.message;
+        try {
+          // See if the message is a stringified JSON with another error
+          const nestedError = JSON.parse(finalMessage) as unknown;
+          if (isApiError(nestedError)) {
+            finalMessage = nestedError.error.message;
+          }
+        } catch (_e) {
+          // It's not a nested JSON error, so we just use the message as is.
+        }
+        let text = `[API Error: ${finalMessage} (Status: ${parsedError.error.status})]`;
+        if (parsedError.error.code === 429) {
+          text += getRateLimitMessage(
+            authType,
+            parsedError,
+            userTier,
+            currentModel,
+            fallbackModel,
+          );
+        }
+        return text;
+      }
+    } catch (_e) {
+      // Not a valid JSON, fall through and return the original message.
+    }
+    return `[API Error: ${error}]`;
+  }
+
+  return '[API Error: An unknown error occurred.]';
+}

packages/cli/src/ui/utils/formatters.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatDuration, formatMemoryUsage } from './formatters.js';
+
+describe('formatters', () => {
+  describe('formatMemoryUsage', () => {
+    it('should format bytes into KB', () => {
+      expect(formatMemoryUsage(12345)).toBe('12.1 KB');
+    });
+
+    it('should format bytes into MB', () => {
+      expect(formatMemoryUsage(12345678)).toBe('11.8 MB');
+    });
+
+    it('should format bytes into GB', () => {
+      expect(formatMemoryUsage(12345678901)).toBe('11.50 GB');
+    });
+  });
+
+  describe('formatDuration', () => {
+    it('should format milliseconds less than a second', () => {
+      expect(formatDuration(500)).toBe('500ms');
+    });
+
+    it('should format a duration of 0', () => {
+      expect(formatDuration(0)).toBe('0s');
+    });
+
+    it('should format an exact number of seconds', () => {
+      expect(formatDuration(5000)).toBe('5.0s');
+    });
+
+    it('should format a duration in seconds with one decimal place', () => {
+      expect(formatDuration(12345)).toBe('12.3s');
+    });
+
+    it('should format an exact number of minutes', () => {
+      expect(formatDuration(120000)).toBe('2m');
+    });
+
+    it('should format a duration in minutes and seconds', () => {
+      expect(formatDuration(123000)).toBe('2m 3s');
+    });
+
+    it('should format an exact number of hours', () => {
+      expect(formatDuration(3600000)).toBe('1h');
+    });
+
+    it('should format a duration in hours and seconds', () => {
+      expect(formatDuration(3605000)).toBe('1h 5s');
+    });
+
+    it('should format a duration in hours, minutes, and seconds', () => {
+      expect(formatDuration(3723000)).toBe('1h 2m 3s');
+    });
+
+    it('should handle large durations', () => {
+      expect(formatDuration(86400000 + 3600000 + 120000 + 1000)).toBe(
+        '25h 2m 1s',
+      );
+    });
+
+    it('should handle negative durations', () => {
+      expect(formatDuration(-100)).toBe('0s');
+    });
+  });
+});

packages/cli/src/ui/utils/formatters.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const formatMemoryUsage = (bytes: number): string => {
+  const gb = bytes / (1024 * 1024 * 1024);
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  if (bytes < 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  return `${gb.toFixed(2)} GB`;
+};
+
+/**
+ * Formats a duration in milliseconds into a concise, human-readable string (e.g., "1h 5s").
+ * It omits any time units that are zero.
+ * @param milliseconds The duration in milliseconds.
+ * @returns A formatted string representing the duration.
+ */
+export const formatDuration = (milliseconds: number): string => {
+  if (milliseconds <= 0) {
+    return '0s';
+  }
+
+  if (milliseconds < 1000) {
+    return `${Math.round(milliseconds)}ms`;
+  }
+
+  const totalSeconds = milliseconds / 1000;
+
+  if (totalSeconds < 60) {
+    return `${totalSeconds.toFixed(1)}s`;
+  }
+
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = Math.floor(totalSeconds % 60);
+
+  const parts: string[] = [];
+
+  if (hours > 0) {
+    parts.push(`${hours}h`);
+  }
+  if (minutes > 0) {
+    parts.push(`${minutes}m`);
+  }
+  if (seconds > 0) {
+    parts.push(`${seconds}s`);
+  }
+
+  // If all parts are zero (e.g., exactly 1 hour), return the largest unit.
+  if (parts.length === 0) {
+    if (hours > 0) return `${hours}h`;
+    if (minutes > 0) return `${minutes}m`;
+    return `${seconds}s`;
+  }
+
+  return parts.join(' ');
+};

packages/cli/src/ui/utils/markdownUtilities.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { findLastSafeSplitPoint } from './markdownUtilities.js';
+
+describe('markdownUtilities', () => {
+  describe('findLastSafeSplitPoint', () => {
+    it('should split at the last double newline if not in a code block', () => {
+      const content = 'paragraph1\n\nparagraph2\n\nparagraph3';
+      expect(findLastSafeSplitPoint(content)).toBe(24); // After the second \n\n
+    });
+
+    it('should return content.length if no safe split point is found', () => {
+      const content = 'longstringwithoutanysafesplitpoint';
+      expect(findLastSafeSplitPoint(content)).toBe(content.length);
+    });
+
+    it('should prioritize splitting at \n\n over being at the very end of the string if the end is not in a code block', () => {
+      const content = 'Some text here.\n\nAnd more text here.';
+      expect(findLastSafeSplitPoint(content)).toBe(17); // after the \n\n
+    });
+
+    it('should return content.length if the only \n\n is inside a code block and the end of content is not', () => {
+      const content = '```\nignore this\n\nnewline\n```KeepThis';
+      expect(findLastSafeSplitPoint(content)).toBe(content.length);
+    });
+
+    it('should correctly identify the last \n\n even if it is followed by text not in a code block', () => {
+      const content =
+        'First part.\n\nSecond part.\n\nThird part, then some more text.';
+      // Split should be after "Second part.\n\n"
+      // "First part.\n\n" is 13 chars. "Second part.\n\n" is 14 chars. Total 27.
+      expect(findLastSafeSplitPoint(content)).toBe(27);
+    });
+
+    it('should return content.length if content is empty', () => {
+      const content = '';
+      expect(findLastSafeSplitPoint(content)).toBe(0);
+    });
+
+    it('should return content.length if content has no newlines and no code blocks', () => {
+      const content = 'Single line of text';
+      expect(findLastSafeSplitPoint(content)).toBe(content.length);
+    });
+  });
+});

packages/cli/src/ui/utils/markdownUtilities.ts

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+**Background & Purpose:**
+
+The `findSafeSplitPoint` function is designed to address the challenge of displaying or processing large, potentially streaming, pieces of Markdown text. When content (e.g., from an LLM like Gemini) arrives in chunks or grows too large for a single display unit (like a message bubble), it needs to be split. A naive split (e.g., just at a character limit) can break Markdown formatting, especially critical for multi-line elements like code blocks, lists, or blockquotes, leading to incorrect rendering.
+
+This function aims to find an *intelligent* or "safe" index within the provided `content` string at which to make such a split, prioritizing the preservation of Markdown integrity.
+
+**Key Expectations & Behavior (Prioritized):**
+
+1.  **No Split if Short Enough:**
+    * If `content.length` is less than or equal to `idealMaxLength`, the function should return `content.length` (indicating no split is necessary for length reasons).
+
+2.  **Code Block Integrity (Highest Priority for Safety):**
+    * The function must try to avoid splitting *inside* a fenced code block (i.e., between ` ``` ` and ` ``` `).
+    * If `idealMaxLength` falls within a code block:
+        * The function will attempt to return an index that splits the content *before* the start of that code block.
+        * If a code block starts at the very beginning of the `content` and `idealMaxLength` falls within it (meaning the block itself is too long for the first chunk), the function might return `0`. This effectively makes the first chunk empty, pushing the entire oversized code block to the second part of the split.
+    * When considering splits near code blocks, the function prefers to keep the entire code block intact in one of the resulting chunks.
+
+3.  **Markdown-Aware Newline Splitting (If Not Governed by Code Block Logic):**
+    * If `idealMaxLength` does not fall within a code block (or after code block considerations have been made), the function will look for natural break points by scanning backwards from `idealMaxLength`:
+        * **Paragraph Breaks:** It prioritizes splitting after a double newline (`\n\n`), as this typically signifies the end of a paragraph or a block-level element.
+        * **Single Line Breaks:** If no double newline is found in a suitable range, it will look for a single newline (`\n`).
+    * Any newline chosen as a split point must also not be inside a code block.
+
+4.  **Fallback to `idealMaxLength`:**
+    * If no "safer" split point (respecting code blocks or finding suitable newlines) is identified before or at `idealMaxLength`, and `idealMaxLength` itself is not determined to be an unsafe split point (e.g., inside a code block), the function may return a length larger than `idealMaxLength`, again it CANNOT break markdown formatting. This could happen with very long lines of text without Markdown block structures or newlines.
+
+**In essence, `findSafeSplitPoint` tries to be a good Markdown citizen when forced to divide content, preferring structural boundaries over arbitrary character limits, with a strong emphasis on not corrupting code blocks.**
+*/
+
+/**
+ * Checks if a given character index within a string is inside a fenced (```) code block.
+ * @param content The full string content.
+ * @param indexToTest The character index to test.
+ * @returns True if the index is inside a code block's content, false otherwise.
+ */
+const isIndexInsideCodeBlock = (
+  content: string,
+  indexToTest: number,
+): boolean => {
+  let fenceCount = 0;
+  let searchPos = 0;
+  while (searchPos < content.length) {
+    const nextFence = content.indexOf('```', searchPos);
+    if (nextFence === -1 || nextFence >= indexToTest) {
+      break;
+    }
+    fenceCount++;
+    searchPos = nextFence + 3;
+  }
+  return fenceCount % 2 === 1;
+};
+
+/**
+ * Finds the starting index of the code block that encloses the given index.
+ * Returns -1 if the index is not inside a code block.
+ * @param content The markdown content.
+ * @param index The index to check.
+ * @returns Start index of the enclosing code block or -1.
+ */
+const findEnclosingCodeBlockStart = (
+  content: string,
+  index: number,
+): number => {
+  if (!isIndexInsideCodeBlock(content, index)) {
+    return -1;
+  }
+  let currentSearchPos = 0;
+  while (currentSearchPos < index) {
+    const blockStartIndex = content.indexOf('```', currentSearchPos);
+    if (blockStartIndex === -1 || blockStartIndex >= index) {
+      break;
+    }
+    const blockEndIndex = content.indexOf('```', blockStartIndex + 3);
+    if (blockStartIndex < index) {
+      if (blockEndIndex === -1 || index < blockEndIndex + 3) {
+        return blockStartIndex;
+      }
+    }
+    if (blockEndIndex === -1) break;
+    currentSearchPos = blockEndIndex + 3;
+  }
+  return -1;
+};
+
+export const findLastSafeSplitPoint = (content: string) => {
+  const enclosingBlockStart = findEnclosingCodeBlockStart(
+    content,
+    content.length,
+  );
+  if (enclosingBlockStart !== -1) {
+    // The end of the content is contained in a code block. Split right before.
+    return enclosingBlockStart;
+  }
+
+  // Search for the last double newline (\n\n) not in a code block.
+  let searchStartIndex = content.length;
+  while (searchStartIndex >= 0) {
+    const dnlIndex = content.lastIndexOf('\n\n', searchStartIndex);
+    if (dnlIndex === -1) {
+      // No more double newlines found.
+      break;
+    }
+
+    const potentialSplitPoint = dnlIndex + 2;
+    if (!isIndexInsideCodeBlock(content, potentialSplitPoint)) {
+      return potentialSplitPoint;
+    }
+
+    // If potentialSplitPoint was inside a code block,
+    // the next search should start *before* the \n\n we just found to ensure progress.
+    searchStartIndex = dnlIndex - 1;
+  }
+
+  // If no safe double newline is found, return content.length
+  // to keep the entire content as one piece.
+  return content.length;
+};

packages/cli/src/ui/utils/textUtils.test.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { isBinary } from './textUtils';
+
+describe('textUtils', () => {
+  describe('isBinary', () => {
+    it('should return true for a buffer containing a null byte', () => {
+      const buffer = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x1a, 0x0a, 0x00,
+      ]);
+      expect(isBinary(buffer)).toBe(true);
+    });
+
+    it('should return false for a buffer containing only text', () => {
+      const buffer = Buffer.from('This is a test string.');
+      expect(isBinary(buffer)).toBe(false);
+    });
+
+    it('should return false for an empty buffer', () => {
+      const buffer = Buffer.from([]);
+      expect(isBinary(buffer)).toBe(false);
+    });
+
+    it('should return false for a null or undefined buffer', () => {
+      expect(isBinary(null)).toBe(false);
+      expect(isBinary(undefined)).toBe(false);
+    });
+
+    it('should only check the sample size', () => {
+      const longBufferWithNullByteAtEnd = Buffer.concat([
+        Buffer.from('a'.repeat(1024)),
+        Buffer.from([0x00]),
+      ]);
+      expect(isBinary(longBufferWithNullByteAtEnd, 512)).toBe(false);
+    });
+  });
+});

packages/cli/src/ui/utils/textUtils.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Calculates the maximum width of a multi-line ASCII art string.
+ * @param asciiArt The ASCII art string.
+ * @returns The length of the longest line in the ASCII art.
+ */
+export const getAsciiArtWidth = (asciiArt: string): number => {
+  if (!asciiArt) {
+    return 0;
+  }
+  const lines = asciiArt.split('\n');
+  return Math.max(...lines.map((line) => line.length));
+};
+
+/**
+ * Checks if a Buffer is likely binary by testing for the presence of a NULL byte.
+ * The presence of a NULL byte is a strong indicator that the data is not plain text.
+ * @param data The Buffer to check.
+ * @param sampleSize The number of bytes from the start of the buffer to test.
+ * @returns True if a NULL byte is found, false otherwise.
+ */
+export function isBinary(
+  data: Buffer | null | undefined,
+  sampleSize = 512,
+): boolean {
+  if (!data) {
+    return false;
+  }
+
+  const sample = data.length > sampleSize ? data.subarray(0, sampleSize) : data;
+
+  for (const byte of sample) {
+    // The presence of a NULL byte (0x00) is one of the most reliable
+    // indicators of a binary file. Text files should not contain them.
+    if (byte === 0) {
+      return true;
+    }
+  }
+
+  // If no NULL bytes were found in the sample, we assume it's text.
+  return false;
+}
+
+/*
+ * -------------------------------------------------------------------------
+ *  Unicode‑aware helpers (work at the code‑point level rather than UTF‑16
+ *  code units so that surrogate‑pair emoji count as one "column".)
+ * ---------------------------------------------------------------------- */
+
+export function toCodePoints(str: string): string[] {
+  // [...str] or Array.from both iterate by UTF‑32 code point, handling
+  // surrogate pairs correctly.
+  return Array.from(str);
+}
+
+export function cpLen(str: string): number {
+  return toCodePoints(str).length;
+}
+
+export function cpSlice(str: string, start: number, end?: number): string {
+  // Slice by code‑point indices and re‑join.
+  const arr = toCodePoints(str).slice(start, end);
+  return arr.join('');
+}

packages/cli/src/ui/utils/updateCheck.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+import { checkForUpdates } from './updateCheck.js';
+
+const getPackageJson = vi.hoisted(() => vi.fn());
+vi.mock('../../utils/package.js', () => ({
+  getPackageJson,
+}));
+
+const updateNotifier = vi.hoisted(() => vi.fn());
+vi.mock('update-notifier', () => ({
+  default: updateNotifier,
+}));
+
+describe('checkForUpdates', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('should return null if package.json is missing', async () => {
+    getPackageJson.mockResolvedValue(null);
+    const result = await checkForUpdates();
+    expect(result).toBeNull();
+  });
+
+  it('should return null if there is no update', async () => {
+    getPackageJson.mockResolvedValue({
+      name: 'test-package',
+      version: '1.0.0',
+    });
+    updateNotifier.mockReturnValue({ update: null });
+    const result = await checkForUpdates();
+    expect(result).toBeNull();
+  });
+
+  it('should return a message if a newer version is available', async () => {
+    getPackageJson.mockResolvedValue({
+      name: 'test-package',
+      version: '1.0.0',
+    });
+    updateNotifier.mockReturnValue({
+      update: { current: '1.0.0', latest: '1.1.0' },
+    });
+    const result = await checkForUpdates();
+    expect(result).toContain('1.0.0 → 1.1.0');
+  });
+
+  it('should return null if the latest version is the same as the current version', async () => {
+    getPackageJson.mockResolvedValue({
+      name: 'test-package',
+      version: '1.0.0',
+    });
+    updateNotifier.mockReturnValue({
+      update: { current: '1.0.0', latest: '1.0.0' },
+    });
+    const result = await checkForUpdates();
+    expect(result).toBeNull();
+  });
+
+  it('should return null if the latest version is older than the current version', async () => {
+    getPackageJson.mockResolvedValue({
+      name: 'test-package',
+      version: '1.1.0',
+    });
+    updateNotifier.mockReturnValue({
+      update: { current: '1.1.0', latest: '1.0.0' },
+    });
+    const result = await checkForUpdates();
+    expect(result).toBeNull();
+  });
+
+  it('should handle errors gracefully', async () => {
+    getPackageJson.mockRejectedValue(new Error('test error'));
+    const result = await checkForUpdates();
+    expect(result).toBeNull();
+  });
+});

packages/cli/src/ui/utils/updateCheck.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import updateNotifier from 'update-notifier';
+import semver from 'semver';
+import { getPackageJson } from '../../utils/package.js';
+
+export async function checkForUpdates(): Promise<string | null> {
+  try {
+    const packageJson = await getPackageJson();
+    if (!packageJson || !packageJson.name || !packageJson.version) {
+      return null;
+    }
+    const notifier = updateNotifier({
+      pkg: {
+        name: packageJson.name,
+        version: packageJson.version,
+      },
+      // check every time
+      updateCheckInterval: 0,
+      // allow notifier to run in scripts
+      shouldNotifyInNpmScript: true,
+    });
+
+    if (
+      notifier.update &&
+      semver.gt(notifier.update.latest, notifier.update.current)
+    ) {
+      return `Gemini CLI update available! ${notifier.update.current} → ${notifier.update.latest}\nRun npm install -g ${packageJson.name} to update`;
+    }
+
+    return null;
+  } catch (e) {
+    console.warn('Failed to check for updates: ' + e);
+    return null;
+  }
+}