@ai-sdk/tui 0.0.0 → 1.0.0-beta.13

package/src/run-agent-tui.ts

@@ -0,0 +1,85 @@
+import { AgentTUIRunner } from './agent-tui-runner';
+import type { Agent } from 'ai';
+
+/**
+ * Controls how terminal UI sections for stream parts are displayed.
+ *
+ * - `full`: show the section header and full content.
+ * - `collapsed`: show only the section header.
+ * - `auto-collapsed`: show the latest section expanded until another visible
+ *   section appears, then collapse it.
+ * - `hidden`: omit the section entirely.
+ */
+export type TerminalPartDisplayMode =
+  | 'full'
+  | 'collapsed'
+  | 'auto-collapsed'
+  | 'hidden';
+
+/**
+ * Controls which response statistic is shown.
+ *
+ * - `outputTokenCount`: show the number of output tokens in the response.
+ * - `outputTokensPerSecond`: show output token throughput for the response.
+ */
+export type ResponseStatisticsMode =
+  | 'outputTokenCount'
+  | 'outputTokensPerSecond';
+
+/**
+ * An agent that is compatible with the terminal UI.
+ *
+ * It has no call options and no structured output.
+ */
+export type AgentTUIAgent = Agent<undefined, any, any, never>;
+
+/**
+ * Options for starting an agent in the default terminal UI.
+ */
+export type RunAgentTUIOptions = {
+  /**
+   * The agent to run.
+   */
+  agent: AgentTUIAgent;
+
+  /**
+   * The title shown in the terminal UI.
+   */
+  title?: string;
+
+  /**
+   * How tool calls should render.
+   *
+   * @default "auto-collapsed"
+   */
+  tools?: TerminalPartDisplayMode;
+
+  /**
+   * How reasoning parts should render.
+   *
+   * @default "auto-collapsed"
+   */
+  reasoning?: TerminalPartDisplayMode;
+
+  /**
+   * Which response statistic to show.
+   *
+   * @default "outputTokensPerSecond"
+   */
+  responseStatistics?: ResponseStatisticsMode;
+
+  /**
+   * The model context window size in tokens.
+   *
+   * When provided, the terminal UI shows the current total token usage as a
+   * percentage of this context window.
+   */
+  contextSize?: number;
+};
+
+/**
+ * Runs an agent in the default terminal UI until the user exits.
+ */
+export async function runAgentTUI(options: RunAgentTUIOptions) {
+  await new AgentTUIRunner(options).run();
+}

package/src/test/mock-terminal.ts

@@ -0,0 +1,207 @@
+import { EventEmitter } from 'node:events';
+import type { TerminalInput, TerminalOutput } from '../tui/terminal-renderer';
+
+const ansiControlSequencePattern = new RegExp(
+  `^${String.fromCharCode(27)}\\[([0-9?;]*)([ -/]*)([@-~])`,
+);
+
+export class MockUserInput extends EventEmitter implements TerminalInput {
+  isTTY = true;
+  rawModes: boolean[] = [];
+  resumeCalls = 0;
+  pauseCalls = 0;
+
+  setRawMode(mode: boolean) {
+    this.rawModes.push(mode);
+    return this;
+  }
+
+  resume() {
+    this.resumeCalls += 1;
+    return this;
+  }
+
+  pause() {
+    this.pauseCalls += 1;
+    return this;
+  }
+
+  type(text: string) {
+    this.emit('data', Buffer.from(text));
+  }
+
+  enter() {
+    this.emit('data', Buffer.from('\r'));
+  }
+
+  ctrlC() {
+    this.emit('data', Buffer.from('\u0003'));
+  }
+}
+
+export class MockScreen extends EventEmitter implements TerminalOutput {
+  columns: number;
+  rows: number;
+  #rawOutput = '';
+  #lines: string[] = [];
+  #cursorLine = 0;
+  #cursorColumn = 0;
+  #waiters: Array<{
+    text: string;
+    resolve: () => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+  }> = [];
+
+  constructor({ columns, rows }: { columns: number; rows: number }) {
+    super();
+    this.columns = columns;
+    this.rows = rows;
+  }
+
+  write(
+    chunk: string | Uint8Array,
+    encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+    callback?: (error?: Error | null) => void,
+  ) {
+    const text = String(chunk);
+    this.#rawOutput += text;
+    this.#apply(text);
+
+    if (typeof encodingOrCallback === 'function') {
+      encodingOrCallback();
+    }
+    callback?.();
+
+    this.#resolveWaiters();
+    return true;
+  }
+
+  resize(columns: number, rows: number) {
+    this.columns = columns;
+    this.rows = rows;
+    this.emit('resize');
+  }
+
+  snapshot() {
+    return this.#lines.join('\n');
+  }
+
+  rawOutput() {
+    return this.#rawOutput;
+  }
+
+  async waitForText(
+    text: string,
+    timeoutMs = 1000,
+    getDebugOutput = () => this.snapshot(),
+  ) {
+    if (this.snapshot().includes(text)) {
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const waiter = {
+        text,
+        resolve,
+        reject,
+        timeout: setTimeout(() => {
+          this.#waiters = this.#waiters.filter(
+            candidate => candidate !== waiter,
+          );
+          reject(
+            new Error(
+              `Timed out waiting for screen text: ${text}\n\nScreen:\n${getDebugOutput()}`,
+            ),
+          );
+        }, timeoutMs),
+      };
+      this.#waiters.push(waiter);
+    });
+  }
+
+  #resolveWaiters() {
+    const snapshot = this.snapshot();
+
+    for (const waiter of this.#waiters.slice()) {
+      if (!snapshot.includes(waiter.text)) {
+        continue;
+      }
+
+      clearTimeout(waiter.timeout);
+      this.#waiters = this.#waiters.filter(candidate => candidate !== waiter);
+      waiter.resolve();
+    }
+  }
+
+  #apply(input: string) {
+    let index = 0;
+
+    while (index < input.length) {
+      if (input[index] === '\x1b') {
+        const nextIndex = this.#applyEscape(input, index);
+
+        if (nextIndex > index) {
+          index = nextIndex;
+          continue;
+        }
+      }
+
+      const character = input[index];
+      index += 1;
+
+      if (character === undefined) {
+        continue;
+      }
+
+      if (character === '\n') {
+        this.#cursorLine += 1;
+        this.#cursorColumn = 0;
+        continue;
+      }
+
+      if (character === '\r') {
+        this.#cursorColumn = 0;
+        continue;
+      }
+
+      this.#writeCharacter(character);
+    }
+  }
+
+  #applyEscape(input: string, startIndex: number) {
+    const match = input.slice(startIndex).match(ansiControlSequencePattern);
+
+    if (!match) {
+      return startIndex;
+    }
+
+    const [sequence, rawParameters, , command] = match;
+    const parameters = rawParameters ? rawParameters.split(';') : [];
+
+    if (command === 'H' && parameters.length === 0) {
+      this.#cursorLine = 0;
+      this.#cursorColumn = 0;
+    } else if (command === 'J' && parameters[0] === '2') {
+      this.#lines = [];
+    } else if (command === 'K' && parameters[0] === '2') {
+      this.#lines[this.#cursorLine] = '';
+      this.#cursorColumn = 0;
+    } else if (command === 'H') {
+      this.#cursorLine = Number(parameters[0] ?? 1) - 1;
+      this.#cursorColumn = Number(parameters[1] ?? 1) - 1;
+    }
+
+    return startIndex + sequence.length;
+  }
+
+  #writeCharacter(character: string) {
+    const line = this.#lines[this.#cursorLine] ?? '';
+    const nextLine =
+      line.slice(0, this.#cursorColumn) +
+      character +
+      line.slice(this.#cursorColumn + character.length);
+    this.#lines[this.#cursorLine] = nextLine;
+    this.#cursorColumn += character.length;
+  }
+}

package/src/tui/layout.ts

@@ -0,0 +1,260 @@
+import { renderMarkdown } from './markdown';
+import {
+  ansiPrefixPattern,
+  codePointWidth,
+  sliceVisible,
+  visibleLength,
+} from './terminal-text';
+
+export { sliceVisible, stripAnsi, visibleLength } from './terminal-text';
+
+const horizontal = '─';
+
+export type TUIScreenState = {
+  width: number;
+  height: number;
+  title: string;
+  rightTitle?: string;
+  body: string;
+  input: string;
+  inputActive: boolean;
+  inputCursorVisible?: boolean;
+  scrollOffset: number;
+  status?: string;
+};
+
+export type TUIScreenLinesState = Omit<TUIScreenState, 'body'> & {
+  bodyLines: string[];
+};
+
+export type TUIScreenViewportState = Omit<
+  TUIScreenLinesState,
+  'bodyLines' | 'scrollOffset'
+> & {
+  visibleBodyLines: string[];
+};
+
+export function renderScreen(state: TUIScreenState): string {
+  const width = Math.max(20, state.width);
+  const contentWidth = width - 4;
+  const bodyLines = wrapText(renderMarkdown(state.body), contentWidth);
+
+  return renderScreenLines({ ...state, bodyLines });
+}
+
+export function renderScreenLines(state: TUIScreenLinesState): string {
+  const height = Math.max(8, state.height);
+  const inputHeight = 3;
+  const bodyHeight = height - inputHeight;
+  const bodyContentHeight = bodyHeight - 2;
+
+  const maxScrollOffset = Math.max(
+    0,
+    state.bodyLines.length - bodyContentHeight,
+  );
+  const scrollOffset = Math.min(
+    Math.max(0, state.scrollOffset),
+    maxScrollOffset,
+  );
+  const start = Math.max(
+    0,
+    state.bodyLines.length - bodyContentHeight - scrollOffset,
+  );
+  const visibleBody = state.bodyLines.slice(start, start + bodyContentHeight);
+
+  return renderScreenViewport({ ...state, visibleBodyLines: visibleBody });
+}
+
+export function renderScreenViewport(state: TUIScreenViewportState): string {
+  const width = Math.max(20, state.width);
+  const height = Math.max(8, state.height);
+  const inputHeight = 3;
+  const bodyHeight = height - inputHeight;
+  const bodyContentHeight = bodyHeight - 2;
+  const visibleBody = state.visibleBodyLines.slice(0, bodyContentHeight);
+
+  while (visibleBody.length < bodyContentHeight) {
+    visibleBody.push('');
+  }
+
+  const lines = [
+    topBorder(width, state.title, state.rightTitle),
+    ...visibleBody.map(line => boxLine(line, width)),
+    bottomBorder(width),
+    topBorder(width, state.inputActive ? 'Input' : 'Status'),
+    boxLine(
+      state.inputActive
+        ? `> ${state.input}${state.inputCursorVisible === false ? ' ' : '█'}`
+        : (state.status ?? 'Streaming... ↑/↓ scroll · Ctrl+C quit'),
+      width,
+    ),
+    bottomBorder(width),
+  ];
+
+  return lines.join('\n');
+}
+
+export function wrapText(input: string, width: number): string[] {
+  if (width <= 0) {
+    return [''];
+  }
+
+  const output: string[] = [];
+
+  for (const rawLine of input.split('\n')) {
+    if (rawLine.length === 0) {
+      output.push('');
+      continue;
+    }
+
+    let remaining = rawLine;
+
+    while (visibleLength(remaining) > width) {
+      const breakAt = findBreakPoint(remaining, width);
+      output.push(remaining.slice(0, breakAt).trimEnd());
+      remaining = remaining.slice(breakAt).trimStart();
+    }
+
+    output.push(remaining);
+  }
+
+  return output;
+}
+
+export function clampScrollOffset(
+  scrollOffset: number,
+  body: string,
+  bodyHeight: number,
+  width: number,
+): number {
+  const bodyContentHeight = Math.max(1, bodyHeight - 2);
+  const bodyLines = wrapText(renderMarkdown(body), Math.max(1, width - 4));
+  const maxScrollOffset = Math.max(0, bodyLines.length - bodyContentHeight);
+
+  return Math.min(Math.max(0, scrollOffset), maxScrollOffset);
+}
+
+function findBreakPoint(input: string, width: number): number {
+  let index = 0;
+  let visible = 0;
+  let lastSpace = -1;
+
+  while (index < input.length && visible < width) {
+    const ansiMatch = input.slice(index).match(ansiPrefixPattern);
+
+    if (ansiMatch) {
+      index += ansiMatch[0].length;
+      continue;
+    }
+
+    const codePoint = input.codePointAt(index);
+
+    if (codePoint == null) {
+      break;
+    }
+
+    const character = String.fromCodePoint(codePoint);
+    const characterWidth = codePointWidth(codePoint);
+
+    if (characterWidth > 0 && visible + characterWidth > width) {
+      break;
+    }
+
+    if (character === ' ') {
+      lastSpace = index;
+    }
+
+    index += character.length;
+    visible += characterWidth;
+  }
+
+  const nextBreakIndex = indexAfterAnsiSequences(input, index);
+  if (visible === width && input.codePointAt(nextBreakIndex) === 0x20) {
+    return nextBreakIndex;
+  }
+
+  if (lastSpace > 0) {
+    return lastSpace;
+  }
+
+  return indexAtVisibleWidth(input, width);
+}
+
+function topBorder(width: number, title: string, rightTitle?: string): string {
+  const contentWidth = Math.max(0, width - 2);
+  const label = title ? sliceVisible(` ${title} `, contentWidth) : '';
+  const rightLabel = rightTitle
+    ? sliceVisible(
+        ` ${rightTitle} `,
+        Math.max(0, contentWidth - visibleLength(label)),
+      )
+    : '';
+  const remaining = Math.max(
+    0,
+    contentWidth - visibleLength(label) - visibleLength(rightLabel),
+  );
+
+  return `┌${label}${horizontal.repeat(remaining)}${rightLabel}┐`;
+}
+
+function bottomBorder(width: number): string {
+  return `└${horizontal.repeat(width - 2)}┘`;
+}
+
+function boxLine(line: string, width: number): string {
+  const contentWidth = width - 4;
+  const visible = sliceVisible(line, contentWidth);
+  const padding = ' '.repeat(
+    Math.max(0, contentWidth - visibleLength(visible)),
+  );
+
+  return `│ ${visible}${padding} │`;
+}
+
+function indexAtVisibleWidth(input: string, width: number): number {
+  let index = 0;
+  let visible = 0;
+
+  while (index < input.length && visible < width) {
+    const ansiMatch = input.slice(index).match(ansiPrefixPattern);
+
+    if (ansiMatch) {
+      index += ansiMatch[0].length;
+      continue;
+    }
+
+    const codePoint = input.codePointAt(index);
+
+    if (codePoint == null) {
+      break;
+    }
+
+    const character = String.fromCodePoint(codePoint);
+    const characterWidth = codePointWidth(codePoint);
+
+    if (characterWidth > 0 && visible + characterWidth > width) {
+      break;
+    }
+
+    index += character.length;
+    visible += characterWidth;
+  }
+
+  return index;
+}
+
+function indexAfterAnsiSequences(input: string, startIndex: number): number {
+  let index = startIndex;
+
+  while (index < input.length) {
+    const ansiMatch = input.slice(index).match(ansiPrefixPattern);
+
+    if (!ansiMatch) {
+      break;
+    }
+
+    index += ansiMatch[0].length;
+  }
+
+  return index;
+}