@vsuryav/agent-sim 0.1.0

package/src/engine/ink/termio/tokenize.ts

@@ -0,0 +1,319 @@
+/**
+ * Input Tokenizer - Escape sequence boundary detection
+ *
+ * Splits terminal input into tokens: text chunks and raw escape sequences.
+ * Unlike the Parser which interprets sequences semantically, this just
+ * identifies boundaries for use by keyboard input parsing.
+ */
+
+import { C0, ESC_TYPE, isEscFinal } from './ansi.js'
+import { isCSIFinal, isCSIIntermediate, isCSIParam } from './csi.js'
+
+export type Token =
+  | { type: 'text'; value: string }
+  | { type: 'sequence'; value: string }
+
+type State =
+  | 'ground'
+  | 'escape'
+  | 'escapeIntermediate'
+  | 'csi'
+  | 'ss3'
+  | 'osc'
+  | 'dcs'
+  | 'apc'
+
+export type Tokenizer = {
+  /** Feed input and get resulting tokens */
+  feed(input: string): Token[]
+  /** Flush any buffered incomplete sequences */
+  flush(): Token[]
+  /** Reset tokenizer state */
+  reset(): void
+  /** Get any buffered incomplete sequence */
+  buffer(): string
+}
+
+type TokenizerOptions = {
+  /**
+   * Treat `CSI M` as an X10 mouse event prefix and consume 3 payload bytes.
+   * Only enable for stdin input — `\x1b[M` is also CSI DL (Delete Lines) in
+   * output streams, and enabling this there swallows display text. Default false.
+   */
+  x10Mouse?: boolean
+}
+
+/**
+ * Create a streaming tokenizer for terminal input.
+ *
+ * Usage:
+ * ```typescript
+ * const tokenizer = createTokenizer()
+ * const tokens1 = tokenizer.feed('hello\x1b[')
+ * const tokens2 = tokenizer.feed('A')  // completes the escape sequence
+ * const remaining = tokenizer.flush()  // force output incomplete sequences
+ * ```
+ */
+export function createTokenizer(options?: TokenizerOptions): Tokenizer {
+  let currentState: State = 'ground'
+  let currentBuffer = ''
+  const x10Mouse = options?.x10Mouse ?? false
+
+  return {
+    feed(input: string): Token[] {
+      const result = tokenize(
+        input,
+        currentState,
+        currentBuffer,
+        false,
+        x10Mouse,
+      )
+      currentState = result.state.state
+      currentBuffer = result.state.buffer
+      return result.tokens
+    },
+
+    flush(): Token[] {
+      const result = tokenize('', currentState, currentBuffer, true, x10Mouse)
+      currentState = result.state.state
+      currentBuffer = result.state.buffer
+      return result.tokens
+    },
+
+    reset(): void {
+      currentState = 'ground'
+      currentBuffer = ''
+    },
+
+    buffer(): string {
+      return currentBuffer
+    },
+  }
+}
+
+type InternalState = {
+  state: State
+  buffer: string
+}
+
+function tokenize(
+  input: string,
+  initialState: State,
+  initialBuffer: string,
+  flush: boolean,
+  x10Mouse: boolean,
+): { tokens: Token[]; state: InternalState } {
+  const tokens: Token[] = []
+  const result: InternalState = {
+    state: initialState,
+    buffer: '',
+  }
+
+  const data = initialBuffer + input
+  let i = 0
+  let textStart = 0
+  let seqStart = 0
+
+  const flushText = (): void => {
+    if (i > textStart) {
+      const text = data.slice(textStart, i)
+      if (text) {
+        tokens.push({ type: 'text', value: text })
+      }
+    }
+    textStart = i
+  }
+
+  const emitSequence = (seq: string): void => {
+    if (seq) {
+      tokens.push({ type: 'sequence', value: seq })
+    }
+    result.state = 'ground'
+    textStart = i
+  }
+
+  while (i < data.length) {
+    const code = data.charCodeAt(i)
+
+    switch (result.state) {
+      case 'ground':
+        if (code === C0.ESC) {
+          flushText()
+          seqStart = i
+          result.state = 'escape'
+          i++
+        } else {
+          i++
+        }
+        break
+
+      case 'escape':
+        if (code === ESC_TYPE.CSI) {
+          result.state = 'csi'
+          i++
+        } else if (code === ESC_TYPE.OSC) {
+          result.state = 'osc'
+          i++
+        } else if (code === ESC_TYPE.DCS) {
+          result.state = 'dcs'
+          i++
+        } else if (code === ESC_TYPE.APC) {
+          result.state = 'apc'
+          i++
+        } else if (code === 0x4f) {
+          // 'O' - SS3
+          result.state = 'ss3'
+          i++
+        } else if (isCSIIntermediate(code)) {
+          // Intermediate byte (e.g., ESC ( for charset) - continue buffering
+          result.state = 'escapeIntermediate'
+          i++
+        } else if (isEscFinal(code)) {
+          // Two-character escape sequence
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else if (code === C0.ESC) {
+          // Double escape - emit first, start new
+          emitSequence(data.slice(seqStart, i))
+          seqStart = i
+          result.state = 'escape'
+          i++
+        } else {
+          // Invalid - treat ESC as text
+          result.state = 'ground'
+          textStart = seqStart
+        }
+        break
+
+      case 'escapeIntermediate':
+        // After intermediate byte(s), wait for final byte
+        if (isCSIIntermediate(code)) {
+          // More intermediate bytes
+          i++
+        } else if (isEscFinal(code)) {
+          // Final byte - complete the sequence
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else {
+          // Invalid - treat as text
+          result.state = 'ground'
+          textStart = seqStart
+        }
+        break
+
+      case 'csi':
+        // X10 mouse: CSI M + 3 raw payload bytes (Cb+32, Cx+32, Cy+32).
+        // M immediately after [ (offset 2) means no params — SGR mouse
+        // (CSI < … M) has a `<` param byte first and reaches M at offset > 2.
+        // Terminals that ignore DECSET 1006 but honor 1000/1002 emit this
+        // legacy encoding; without this branch the 3 payload bytes leak
+        // through as text (`` `rK `` / `arK` garbage in the prompt).
+        //
+        // Gated on x10Mouse — `\x1b[M` is also CSI DL (Delete Lines) and
+        // blindly consuming 3 chars corrupts output rendering (Parser/Ansi)
+        // and fragments bracketed-paste PASTE_END. Only stdin enables this.
+        // The ≥0x20 check on each payload slot is belt-and-suspenders: X10
+        // guarantees Cb≥32, Cx≥33, Cy≥33, so a control byte (ESC=0x1B) in
+        // any slot means this is CSI DL adjacent to another sequence, not a
+        // mouse event. Checking all three slots prevents PASTE_END's ESC
+        // from being consumed when paste content ends in `\x1b[M`+0-2 chars.
+        //
+        // Known limitation: this counts JS string chars, but X10 is byte-
+        // oriented and stdin uses utf8 encoding (App.tsx). At col 162-191 ×
+        // row 96-159 the two coord bytes (0xC2-0xDF, 0x80-0xBF) form a valid
+        // UTF-8 2-byte sequence and collapse to one char — the length check
+        // fails and the event buffers until the next keypress absorbs it.
+        // Fixing this requires latin1 stdin; X10's 223-coord cap is exactly
+        // why SGR was invented, and no-SGR terminals at 162+ cols are rare.
+        if (
+          x10Mouse &&
+          code === 0x4d /* M */ &&
+          i - seqStart === 2 &&
+          (i + 1 >= data.length || data.charCodeAt(i + 1) >= 0x20) &&
+          (i + 2 >= data.length || data.charCodeAt(i + 2) >= 0x20) &&
+          (i + 3 >= data.length || data.charCodeAt(i + 3) >= 0x20)
+        ) {
+          if (i + 4 <= data.length) {
+            i += 4
+            emitSequence(data.slice(seqStart, i))
+          } else {
+            // Incomplete — exit loop; end-of-input buffers from seqStart.
+            // Re-entry re-tokenizes from ground via the invalid-CSI fallthrough.
+            i = data.length
+          }
+          break
+        }
+        if (isCSIFinal(code)) {
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else if (isCSIParam(code) || isCSIIntermediate(code)) {
+          i++
+        } else {
+          // Invalid CSI - abort, treat as text
+          result.state = 'ground'
+          textStart = seqStart
+        }
+        break
+
+      case 'ss3':
+        // SS3 sequences: ESC O followed by a single final byte
+        if (code >= 0x40 && code <= 0x7e) {
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else {
+          // Invalid - treat as text
+          result.state = 'ground'
+          textStart = seqStart
+        }
+        break
+
+      case 'osc':
+        if (code === C0.BEL) {
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else if (
+          code === C0.ESC &&
+          i + 1 < data.length &&
+          data.charCodeAt(i + 1) === ESC_TYPE.ST
+        ) {
+          i += 2
+          emitSequence(data.slice(seqStart, i))
+        } else {
+          i++
+        }
+        break
+
+      case 'dcs':
+      case 'apc':
+        if (code === C0.BEL) {
+          i++
+          emitSequence(data.slice(seqStart, i))
+        } else if (
+          code === C0.ESC &&
+          i + 1 < data.length &&
+          data.charCodeAt(i + 1) === ESC_TYPE.ST
+        ) {
+          i += 2
+          emitSequence(data.slice(seqStart, i))
+        } else {
+          i++
+        }
+        break
+    }
+  }
+
+  // Handle end of input
+  if (result.state === 'ground') {
+    flushText()
+  } else if (flush) {
+    // Force output incomplete sequence
+    const remaining = data.slice(seqStart)
+    if (remaining) tokens.push({ type: 'sequence', value: remaining })
+    result.state = 'ground'
+  } else {
+    // Buffer incomplete sequence for next call
+    result.buffer = data.slice(seqStart)
+  }
+
+  return { tokens, state: result }
+}

package/src/engine/ink/termio/types.ts

@@ -0,0 +1,236 @@
+/**
+ * ANSI Parser - Semantic Types
+ *
+ * These types represent the semantic meaning of ANSI escape sequences,
+ * not their string representation. Inspired by ghostty's action-based design.
+ */
+
+// =============================================================================
+// Colors
+// =============================================================================
+
+/** Named colors from the 16-color palette */
+export type NamedColor =
+  | 'black'
+  | 'red'
+  | 'green'
+  | 'yellow'
+  | 'blue'
+  | 'magenta'
+  | 'cyan'
+  | 'white'
+  | 'brightBlack'
+  | 'brightRed'
+  | 'brightGreen'
+  | 'brightYellow'
+  | 'brightBlue'
+  | 'brightMagenta'
+  | 'brightCyan'
+  | 'brightWhite'
+
+/** Color specification - can be named, indexed (256), or RGB */
+export type Color =
+  | { type: 'named'; name: NamedColor }
+  | { type: 'indexed'; index: number } // 0-255
+  | { type: 'rgb'; r: number; g: number; b: number }
+  | { type: 'default' }
+
+// =============================================================================
+// Text Styles
+// =============================================================================
+
+/** Underline style variants */
+export type UnderlineStyle =
+  | 'none'
+  | 'single'
+  | 'double'
+  | 'curly'
+  | 'dotted'
+  | 'dashed'
+
+/** Text style attributes - represents current styling state */
+export type TextStyle = {
+  bold: boolean
+  dim: boolean
+  italic: boolean
+  underline: UnderlineStyle
+  blink: boolean
+  inverse: boolean
+  hidden: boolean
+  strikethrough: boolean
+  overline: boolean
+  fg: Color
+  bg: Color
+  underlineColor: Color
+}
+
+/** Create a default (reset) text style */
+export function defaultStyle(): TextStyle {
+  return {
+    bold: false,
+    dim: false,
+    italic: false,
+    underline: 'none',
+    blink: false,
+    inverse: false,
+    hidden: false,
+    strikethrough: false,
+    overline: false,
+    fg: { type: 'default' },
+    bg: { type: 'default' },
+    underlineColor: { type: 'default' },
+  }
+}
+
+/** Check if two styles are equal */
+export function stylesEqual(a: TextStyle, b: TextStyle): boolean {
+  return (
+    a.bold === b.bold &&
+    a.dim === b.dim &&
+    a.italic === b.italic &&
+    a.underline === b.underline &&
+    a.blink === b.blink &&
+    a.inverse === b.inverse &&
+    a.hidden === b.hidden &&
+    a.strikethrough === b.strikethrough &&
+    a.overline === b.overline &&
+    colorsEqual(a.fg, b.fg) &&
+    colorsEqual(a.bg, b.bg) &&
+    colorsEqual(a.underlineColor, b.underlineColor)
+  )
+}
+
+/** Check if two colors are equal */
+export function colorsEqual(a: Color, b: Color): boolean {
+  if (a.type !== b.type) return false
+  switch (a.type) {
+    case 'named':
+      return a.name === (b as typeof a).name
+    case 'indexed':
+      return a.index === (b as typeof a).index
+    case 'rgb':
+      return (
+        a.r === (b as typeof a).r &&
+        a.g === (b as typeof a).g &&
+        a.b === (b as typeof a).b
+      )
+    case 'default':
+      return true
+  }
+}
+
+// =============================================================================
+// Cursor Actions
+// =============================================================================
+
+export type CursorDirection = 'up' | 'down' | 'forward' | 'back'
+
+export type CursorAction =
+  | { type: 'move'; direction: CursorDirection; count: number }
+  | { type: 'position'; row: number; col: number }
+  | { type: 'column'; col: number }
+  | { type: 'row'; row: number }
+  | { type: 'save' }
+  | { type: 'restore' }
+  | { type: 'show' }
+  | { type: 'hide' }
+  | {
+      type: 'style'
+      style: 'block' | 'underline' | 'bar'
+      blinking: boolean
+    }
+  | { type: 'nextLine'; count: number }
+  | { type: 'prevLine'; count: number }
+
+// =============================================================================
+// Erase Actions
+// =============================================================================
+
+export type EraseAction =
+  | { type: 'display'; region: 'toEnd' | 'toStart' | 'all' | 'scrollback' }
+  | { type: 'line'; region: 'toEnd' | 'toStart' | 'all' }
+  | { type: 'chars'; count: number }
+
+// =============================================================================
+// Scroll Actions
+// =============================================================================
+
+export type ScrollAction =
+  | { type: 'up'; count: number }
+  | { type: 'down'; count: number }
+  | { type: 'setRegion'; top: number; bottom: number }
+
+// =============================================================================
+// Mode Actions
+// =============================================================================
+
+export type ModeAction =
+  | { type: 'alternateScreen'; enabled: boolean }
+  | { type: 'bracketedPaste'; enabled: boolean }
+  | { type: 'mouseTracking'; mode: 'off' | 'normal' | 'button' | 'any' }
+  | { type: 'focusEvents'; enabled: boolean }
+
+// =============================================================================
+// Link Actions (OSC 8)
+// =============================================================================
+
+export type LinkAction =
+  | { type: 'start'; url: string; params?: Record<string, string> }
+  | { type: 'end' }
+
+// =============================================================================
+// Title Actions (OSC 0/1/2)
+// =============================================================================
+
+export type TitleAction =
+  | { type: 'windowTitle'; title: string }
+  | { type: 'iconName'; name: string }
+  | { type: 'both'; title: string }
+
+// =============================================================================
+// Tab Status Action (OSC 21337)
+// =============================================================================
+
+/**
+ * Per-tab chrome metadata. Tristate for each field:
+ *  - property absent → not mentioned in sequence, no change
+ *  - null → explicitly cleared (bare key or key= with empty value)
+ *  - value → set to this
+ */
+export type TabStatusAction = {
+  indicator?: Color | null
+  status?: string | null
+  statusColor?: Color | null
+}
+
+// =============================================================================
+// Parsed Segments - The output of the parser
+// =============================================================================
+
+/** A segment of styled text */
+export type TextSegment = {
+  type: 'text'
+  text: string
+  style: TextStyle
+}
+
+/** A grapheme (visual character unit) with width info */
+export type Grapheme = {
+  value: string
+  width: 1 | 2 // Display width in columns
+}
+
+/** All possible parsed actions */
+export type Action =
+  | { type: 'text'; graphemes: Grapheme[]; style: TextStyle }
+  | { type: 'cursor'; action: CursorAction }
+  | { type: 'erase'; action: EraseAction }
+  | { type: 'scroll'; action: ScrollAction }
+  | { type: 'mode'; action: ModeAction }
+  | { type: 'link'; action: LinkAction }
+  | { type: 'title'; action: TitleAction }
+  | { type: 'tabStatus'; action: TabStatusAction }
+  | { type: 'sgr'; params: string } // Select Graphic Rendition (style change)
+  | { type: 'bell' }
+  | { type: 'reset' } // Full terminal reset (ESC c)
+  | { type: 'unknown'; sequence: string } // Unrecognized sequence

package/src/engine/ink/useTerminalNotification.ts

@@ -0,0 +1,126 @@
+import { createContext, useCallback, useContext, useMemo } from 'react'
+import { isProgressReportingAvailable, type Progress } from './terminal.js'
+import { BEL } from './termio/ansi.js'
+import { ITERM2, OSC, osc, PROGRESS, wrapForMultiplexer } from './termio/osc.js'
+
+type WriteRaw = (data: string) => void
+
+export const TerminalWriteContext = createContext<WriteRaw | null>(null)
+
+export const TerminalWriteProvider = TerminalWriteContext.Provider
+
+export type TerminalNotification = {
+  notifyITerm2: (opts: { message: string; title?: string }) => void
+  notifyKitty: (opts: { message: string; title: string; id: number }) => void
+  notifyGhostty: (opts: { message: string; title: string }) => void
+  notifyBell: () => void
+  /**
+   * Report progress to the terminal via OSC 9;4 sequences.
+   * Supported terminals: ConEmu, Ghostty 1.2.0+, iTerm2 3.6.6+
+   * Pass state=null to clear progress.
+   */
+  progress: (state: Progress['state'] | null, percentage?: number) => void
+}
+
+export function useTerminalNotification(): TerminalNotification {
+  const writeRaw = useContext(TerminalWriteContext)
+  if (!writeRaw) {
+    throw new Error(
+      'useTerminalNotification must be used within TerminalWriteProvider',
+    )
+  }
+
+  const notifyITerm2 = useCallback(
+    ({ message, title }: { message: string; title?: string }) => {
+      const displayString = title ? `${title}:\n${message}` : message
+      writeRaw(wrapForMultiplexer(osc(OSC.ITERM2, `\n\n${displayString}`)))
+    },
+    [writeRaw],
+  )
+
+  const notifyKitty = useCallback(
+    ({
+      message,
+      title,
+      id,
+    }: {
+      message: string
+      title: string
+      id: number
+    }) => {
+      writeRaw(wrapForMultiplexer(osc(OSC.KITTY, `i=${id}:d=0:p=title`, title)))
+      writeRaw(wrapForMultiplexer(osc(OSC.KITTY, `i=${id}:p=body`, message)))
+      writeRaw(wrapForMultiplexer(osc(OSC.KITTY, `i=${id}:d=1:a=focus`, '')))
+    },
+    [writeRaw],
+  )
+
+  const notifyGhostty = useCallback(
+    ({ message, title }: { message: string; title: string }) => {
+      writeRaw(wrapForMultiplexer(osc(OSC.GHOSTTY, 'notify', title, message)))
+    },
+    [writeRaw],
+  )
+
+  const notifyBell = useCallback(() => {
+    // Raw BEL — inside tmux this triggers tmux's bell-action (window flag).
+    // Wrapping would make it opaque DCS payload and lose that fallback.
+    writeRaw(BEL)
+  }, [writeRaw])
+
+  const progress = useCallback(
+    (state: Progress['state'] | null, percentage?: number) => {
+      if (!isProgressReportingAvailable()) {
+        return
+      }
+      if (!state) {
+        writeRaw(
+          wrapForMultiplexer(
+            osc(OSC.ITERM2, ITERM2.PROGRESS, PROGRESS.CLEAR, ''),
+          ),
+        )
+        return
+      }
+      const pct = Math.max(0, Math.min(100, Math.round(percentage ?? 0)))
+      switch (state) {
+        case 'completed':
+          writeRaw(
+            wrapForMultiplexer(
+              osc(OSC.ITERM2, ITERM2.PROGRESS, PROGRESS.CLEAR, ''),
+            ),
+          )
+          break
+        case 'error':
+          writeRaw(
+            wrapForMultiplexer(
+              osc(OSC.ITERM2, ITERM2.PROGRESS, PROGRESS.ERROR, pct),
+            ),
+          )
+          break
+        case 'indeterminate':
+          writeRaw(
+            wrapForMultiplexer(
+              osc(OSC.ITERM2, ITERM2.PROGRESS, PROGRESS.INDETERMINATE, ''),
+            ),
+          )
+          break
+        case 'running':
+          writeRaw(
+            wrapForMultiplexer(
+              osc(OSC.ITERM2, ITERM2.PROGRESS, PROGRESS.SET, pct),
+            ),
+          )
+          break
+        case null:
+          // Handled by the if guard above
+          break
+      }
+    },
+    [writeRaw],
+  )
+
+  return useMemo(
+    () => ({ notifyITerm2, notifyKitty, notifyGhostty, notifyBell, progress }),
+    [notifyITerm2, notifyKitty, notifyGhostty, notifyBell, progress],
+  )
+}

package/src/engine/ink/warn.ts

@@ -0,0 +1,9 @@
+import { logForDebugging } from '../utils/debug.js'
+
+export function ifNotInteger(value: number | undefined, name: string): void {
+  if (value === undefined) return
+  if (Number.isInteger(value)) return
+  logForDebugging(`${name} should be an integer, got ${value}`, {
+    level: 'warn',
+  })
+}

package/src/engine/ink/widest-line.ts

@@ -0,0 +1,19 @@
+import { lineWidth } from './line-width-cache.js'
+
+export function widestLine(string: string): number {
+  let maxWidth = 0
+  let start = 0
+
+  while (start <= string.length) {
+    const end = string.indexOf('\n', start)
+    const line =
+      end === -1 ? string.substring(start) : string.substring(start, end)
+
+    maxWidth = Math.max(maxWidth, lineWidth(line))
+
+    if (end === -1) break
+    start = end + 1
+  }
+
+  return maxWidth
+}