@vsuryav/agent-sim 0.1.0

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

@@ -0,0 +1,319 @@
+/**
+ * CSI (Control Sequence Introducer) Types
+ *
+ * Enums and types for CSI command parameters.
+ */
+
+import { ESC, ESC_TYPE, SEP } from './ansi.js'
+
+export const CSI_PREFIX = ESC + String.fromCharCode(ESC_TYPE.CSI)
+
+/**
+ * CSI parameter byte ranges
+ */
+export const CSI_RANGE = {
+  PARAM_START: 0x30,
+  PARAM_END: 0x3f,
+  INTERMEDIATE_START: 0x20,
+  INTERMEDIATE_END: 0x2f,
+  FINAL_START: 0x40,
+  FINAL_END: 0x7e,
+} as const
+
+/** Check if a byte is a CSI parameter byte */
+export function isCSIParam(byte: number): boolean {
+  return byte >= CSI_RANGE.PARAM_START && byte <= CSI_RANGE.PARAM_END
+}
+
+/** Check if a byte is a CSI intermediate byte */
+export function isCSIIntermediate(byte: number): boolean {
+  return (
+    byte >= CSI_RANGE.INTERMEDIATE_START && byte <= CSI_RANGE.INTERMEDIATE_END
+  )
+}
+
+/** Check if a byte is a CSI final byte (@ through ~) */
+export function isCSIFinal(byte: number): boolean {
+  return byte >= CSI_RANGE.FINAL_START && byte <= CSI_RANGE.FINAL_END
+}
+
+/**
+ * Generate a CSI sequence: ESC [ p1;p2;...;pN final
+ * Single arg: treated as raw body
+ * Multiple args: last is final byte, rest are params joined by ;
+ */
+export function csi(...args: (string | number)[]): string {
+  if (args.length === 0) return CSI_PREFIX
+  if (args.length === 1) return `${CSI_PREFIX}${args[0]}`
+  const params = args.slice(0, -1)
+  const final = args[args.length - 1]
+  return `${CSI_PREFIX}${params.join(SEP)}${final}`
+}
+
+/**
+ * CSI final bytes - the command identifier
+ */
+export const CSI = {
+  // Cursor movement
+  CUU: 0x41, // A - Cursor Up
+  CUD: 0x42, // B - Cursor Down
+  CUF: 0x43, // C - Cursor Forward
+  CUB: 0x44, // D - Cursor Back
+  CNL: 0x45, // E - Cursor Next Line
+  CPL: 0x46, // F - Cursor Previous Line
+  CHA: 0x47, // G - Cursor Horizontal Absolute
+  CUP: 0x48, // H - Cursor Position
+  CHT: 0x49, // I - Cursor Horizontal Tab
+  VPA: 0x64, // d - Vertical Position Absolute
+  HVP: 0x66, // f - Horizontal Vertical Position
+
+  // Erase
+  ED: 0x4a, // J - Erase in Display
+  EL: 0x4b, // K - Erase in Line
+  ECH: 0x58, // X - Erase Character
+
+  // Insert/Delete
+  IL: 0x4c, // L - Insert Lines
+  DL: 0x4d, // M - Delete Lines
+  ICH: 0x40, // @ - Insert Characters
+  DCH: 0x50, // P - Delete Characters
+
+  // Scroll
+  SU: 0x53, // S - Scroll Up
+  SD: 0x54, // T - Scroll Down
+
+  // Modes
+  SM: 0x68, // h - Set Mode
+  RM: 0x6c, // l - Reset Mode
+
+  // SGR
+  SGR: 0x6d, // m - Select Graphic Rendition
+
+  // Other
+  DSR: 0x6e, // n - Device Status Report
+  DECSCUSR: 0x71, // q - Set Cursor Style (with space intermediate)
+  DECSTBM: 0x72, // r - Set Top and Bottom Margins
+  SCOSC: 0x73, // s - Save Cursor Position
+  SCORC: 0x75, // u - Restore Cursor Position
+  CBT: 0x5a, // Z - Cursor Backward Tabulation
+} as const
+
+/**
+ * Erase in Display regions (ED command parameter)
+ */
+export const ERASE_DISPLAY = ['toEnd', 'toStart', 'all', 'scrollback'] as const
+
+/**
+ * Erase in Line regions (EL command parameter)
+ */
+export const ERASE_LINE_REGION = ['toEnd', 'toStart', 'all'] as const
+
+/**
+ * Cursor styles (DECSCUSR)
+ */
+export type CursorStyle = 'block' | 'underline' | 'bar'
+
+export const CURSOR_STYLES: Array<{ style: CursorStyle; blinking: boolean }> = [
+  { style: 'block', blinking: true }, // 0 - default
+  { style: 'block', blinking: true }, // 1
+  { style: 'block', blinking: false }, // 2
+  { style: 'underline', blinking: true }, // 3
+  { style: 'underline', blinking: false }, // 4
+  { style: 'bar', blinking: true }, // 5
+  { style: 'bar', blinking: false }, // 6
+]
+
+// Cursor movement generators
+
+/** Move cursor up n lines (CSI n A) */
+export function cursorUp(n = 1): string {
+  return n === 0 ? '' : csi(n, 'A')
+}
+
+/** Move cursor down n lines (CSI n B) */
+export function cursorDown(n = 1): string {
+  return n === 0 ? '' : csi(n, 'B')
+}
+
+/** Move cursor forward n columns (CSI n C) */
+export function cursorForward(n = 1): string {
+  return n === 0 ? '' : csi(n, 'C')
+}
+
+/** Move cursor back n columns (CSI n D) */
+export function cursorBack(n = 1): string {
+  return n === 0 ? '' : csi(n, 'D')
+}
+
+/** Move cursor to column n (1-indexed) (CSI n G) */
+export function cursorTo(col: number): string {
+  return csi(col, 'G')
+}
+
+/** Move cursor to column 1 (CSI G) */
+export const CURSOR_LEFT = csi('G')
+
+/** Move cursor to row, col (1-indexed) (CSI row ; col H) */
+export function cursorPosition(row: number, col: number): string {
+  return csi(row, col, 'H')
+}
+
+/** Move cursor to home position (CSI H) */
+export const CURSOR_HOME = csi('H')
+
+/**
+ * Move cursor relative to current position
+ * Positive x = right, negative x = left
+ * Positive y = down, negative y = up
+ */
+export function cursorMove(x: number, y: number): string {
+  let result = ''
+  // Horizontal first (matches ansi-escapes behavior)
+  if (x < 0) {
+    result += cursorBack(-x)
+  } else if (x > 0) {
+    result += cursorForward(x)
+  }
+  // Then vertical
+  if (y < 0) {
+    result += cursorUp(-y)
+  } else if (y > 0) {
+    result += cursorDown(y)
+  }
+  return result
+}
+
+// Save/restore cursor position
+
+/** Save cursor position (CSI s) */
+export const CURSOR_SAVE = csi('s')
+
+/** Restore cursor position (CSI u) */
+export const CURSOR_RESTORE = csi('u')
+
+// Erase generators
+
+/** Erase from cursor to end of line (CSI K) */
+export function eraseToEndOfLine(): string {
+  return csi('K')
+}
+
+/** Erase from cursor to start of line (CSI 1 K) */
+export function eraseToStartOfLine(): string {
+  return csi(1, 'K')
+}
+
+/** Erase entire line (CSI 2 K) */
+export function eraseLine(): string {
+  return csi(2, 'K')
+}
+
+/** Erase entire line - constant form */
+export const ERASE_LINE = csi(2, 'K')
+
+/** Erase from cursor to end of screen (CSI J) */
+export function eraseToEndOfScreen(): string {
+  return csi('J')
+}
+
+/** Erase from cursor to start of screen (CSI 1 J) */
+export function eraseToStartOfScreen(): string {
+  return csi(1, 'J')
+}
+
+/** Erase entire screen (CSI 2 J) */
+export function eraseScreen(): string {
+  return csi(2, 'J')
+}
+
+/** Erase entire screen - constant form */
+export const ERASE_SCREEN = csi(2, 'J')
+
+/** Erase scrollback buffer (CSI 3 J) */
+export const ERASE_SCROLLBACK = csi(3, 'J')
+
+/**
+ * Erase n lines starting from cursor line, moving cursor up
+ * This erases each line and moves up, ending at column 1
+ */
+export function eraseLines(n: number): string {
+  if (n <= 0) return ''
+  let result = ''
+  for (let i = 0; i < n; i++) {
+    result += ERASE_LINE
+    if (i < n - 1) {
+      result += cursorUp(1)
+    }
+  }
+  result += CURSOR_LEFT
+  return result
+}
+
+// Scroll
+
+/** Scroll up n lines (CSI n S) */
+export function scrollUp(n = 1): string {
+  return n === 0 ? '' : csi(n, 'S')
+}
+
+/** Scroll down n lines (CSI n T) */
+export function scrollDown(n = 1): string {
+  return n === 0 ? '' : csi(n, 'T')
+}
+
+/** Set scroll region (DECSTBM, CSI top;bottom r). 1-indexed, inclusive. */
+export function setScrollRegion(top: number, bottom: number): string {
+  return csi(top, bottom, 'r')
+}
+
+/** Reset scroll region to full screen (DECSTBM, CSI r). Homes the cursor. */
+export const RESET_SCROLL_REGION = csi('r')
+
+// Bracketed paste markers (input from terminal, not output)
+// These are sent by the terminal to delimit pasted content when
+// bracketed paste mode is enabled (via DEC mode 2004)
+
+/** Sent by terminal before pasted content (CSI 200 ~) */
+export const PASTE_START = csi('200~')
+
+/** Sent by terminal after pasted content (CSI 201 ~) */
+export const PASTE_END = csi('201~')
+
+// Focus event markers (input from terminal, not output)
+// These are sent by the terminal when focus changes while
+// focus events mode is enabled (via DEC mode 1004)
+
+/** Sent by terminal when it gains focus (CSI I) */
+export const FOCUS_IN = csi('I')
+
+/** Sent by terminal when it loses focus (CSI O) */
+export const FOCUS_OUT = csi('O')
+
+// Kitty keyboard protocol (CSI u)
+// Enables enhanced key reporting with modifier information
+// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+
+/**
+ * Enable Kitty keyboard protocol with basic modifier reporting
+ * CSI > 1 u - pushes mode with flags=1 (disambiguate escape codes)
+ * This makes Shift+Enter send CSI 13;2 u instead of just CR
+ */
+export const ENABLE_KITTY_KEYBOARD = csi('>1u')
+
+/**
+ * Disable Kitty keyboard protocol
+ * CSI < u - pops the keyboard mode stack
+ */
+export const DISABLE_KITTY_KEYBOARD = csi('<u')
+
+/**
+ * Enable xterm modifyOtherKeys level 2.
+ * tmux accepts this (not the kitty stack) to enable extended keys — when
+ * extended-keys-format is csi-u, tmux then emits keys in kitty format.
+ */
+export const ENABLE_MODIFY_OTHER_KEYS = csi('>4;2m')
+
+/**
+ * Disable xterm modifyOtherKeys (reset to default).
+ */
+export const DISABLE_MODIFY_OTHER_KEYS = csi('>4m')

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

@@ -0,0 +1,60 @@
+/**
+ * DEC (Digital Equipment Corporation) Private Mode Sequences
+ *
+ * DEC private modes use CSI ? N h (set) and CSI ? N l (reset) format.
+ * These are terminal-specific extensions to the ANSI standard.
+ */
+
+import { csi } from './csi.js'
+
+/**
+ * DEC private mode numbers
+ */
+export const DEC = {
+  CURSOR_VISIBLE: 25,
+  ALT_SCREEN: 47,
+  ALT_SCREEN_CLEAR: 1049,
+  MOUSE_NORMAL: 1000,
+  MOUSE_BUTTON: 1002,
+  MOUSE_ANY: 1003,
+  MOUSE_SGR: 1006,
+  FOCUS_EVENTS: 1004,
+  BRACKETED_PASTE: 2004,
+  SYNCHRONIZED_UPDATE: 2026,
+} as const
+
+/** Generate CSI ? N h sequence (set mode) */
+export function decset(mode: number): string {
+  return csi(`?${mode}h`)
+}
+
+/** Generate CSI ? N l sequence (reset mode) */
+export function decreset(mode: number): string {
+  return csi(`?${mode}l`)
+}
+
+// Pre-generated sequences for common modes
+export const BSU = decset(DEC.SYNCHRONIZED_UPDATE)
+export const ESU = decreset(DEC.SYNCHRONIZED_UPDATE)
+export const EBP = decset(DEC.BRACKETED_PASTE)
+export const DBP = decreset(DEC.BRACKETED_PASTE)
+export const EFE = decset(DEC.FOCUS_EVENTS)
+export const DFE = decreset(DEC.FOCUS_EVENTS)
+export const SHOW_CURSOR = decset(DEC.CURSOR_VISIBLE)
+export const HIDE_CURSOR = decreset(DEC.CURSOR_VISIBLE)
+export const ENTER_ALT_SCREEN = decset(DEC.ALT_SCREEN_CLEAR)
+export const EXIT_ALT_SCREEN = decreset(DEC.ALT_SCREEN_CLEAR)
+// Mouse tracking: 1000 reports button press/release/wheel, 1002 adds drag
+// events (button-motion), 1003 adds all-motion (no button held — for
+// hover), 1006 uses SGR format (CSI < btn;col;row M/m) instead of legacy
+// X10 bytes. Combined: wheel + click/drag for selection + hover.
+export const ENABLE_MOUSE_TRACKING =
+  decset(DEC.MOUSE_NORMAL) +
+  decset(DEC.MOUSE_BUTTON) +
+  decset(DEC.MOUSE_ANY) +
+  decset(DEC.MOUSE_SGR)
+export const DISABLE_MOUSE_TRACKING =
+  decreset(DEC.MOUSE_SGR) +
+  decreset(DEC.MOUSE_ANY) +
+  decreset(DEC.MOUSE_BUTTON) +
+  decreset(DEC.MOUSE_NORMAL)

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

@@ -0,0 +1,67 @@
+/**
+ * ESC Sequence Parser
+ *
+ * Handles simple escape sequences: ESC + one or two characters
+ */
+
+import type { Action } from './types.js'
+
+/**
+ * Parse a simple ESC sequence
+ *
+ * @param chars - Characters after ESC (not including ESC itself)
+ */
+export function parseEsc(chars: string): Action | null {
+  if (chars.length === 0) return null
+
+  const first = chars[0]!
+
+  // Full reset (RIS)
+  if (first === 'c') {
+    return { type: 'reset' }
+  }
+
+  // Cursor save (DECSC)
+  if (first === '7') {
+    return { type: 'cursor', action: { type: 'save' } }
+  }
+
+  // Cursor restore (DECRC)
+  if (first === '8') {
+    return { type: 'cursor', action: { type: 'restore' } }
+  }
+
+  // Index - move cursor down (IND)
+  if (first === 'D') {
+    return {
+      type: 'cursor',
+      action: { type: 'move', direction: 'down', count: 1 },
+    }
+  }
+
+  // Reverse index - move cursor up (RI)
+  if (first === 'M') {
+    return {
+      type: 'cursor',
+      action: { type: 'move', direction: 'up', count: 1 },
+    }
+  }
+
+  // Next line (NEL)
+  if (first === 'E') {
+    return { type: 'cursor', action: { type: 'nextLine', count: 1 } }
+  }
+
+  // Horizontal tab set (HTS)
+  if (first === 'H') {
+    return null // Tab stop, not commonly needed
+  }
+
+  // Charset selection (ESC ( X, ESC ) X, etc.) - silently ignore
+  if ('()'.includes(first) && chars.length >= 2) {
+    return null
+  }
+
+  // Unknown
+  return { type: 'unknown', sequence: `\x1b${chars}` }
+}