feat: add pty_snapshot tool for parsed terminal screen capture

Add a headless terminal emulator (@xterm/headless) to each PTY session
that processes raw output in parallel with the existing ring buffer.
This enables clean, ANSI-free screen capture via a new pty_snapshot tool.

The snapshot returns the visible terminal screen text, cursor position,
terminal size, and a content hash for efficient change detection -
useful for monitoring TUI applications during development.

Also improves the web UI plain-text buffer endpoint to use the parsed
screen instead of naive ANSI regex stripping.

Author: JosXa

bun.lock

@@ -78,6 +78,7 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.1.51",
     "@opencode-ai/sdk": "^1.1.51",
+    "@xterm/headless": "^6.0.0",
     "bun-pty": "^0.4.8",
     "moment": "^2.30.1",
     "open": "^11.0.0"

package.json

@@ -6,6 +6,7 @@ import { ptyWrite } from './plugin/pty/tools/write.ts'
 import { ptyRead } from './plugin/pty/tools/read.ts'
 import { ptyList } from './plugin/pty/tools/list.ts'
 import { ptyKill } from './plugin/pty/tools/kill.ts'
+import { ptySnapshot } from './plugin/pty/tools/snapshot.ts'
 import { PTYServer } from './web/server/server.ts'
 import open from 'open'
 
@@ -48,6 +49,7 @@ export const PTYPlugin = async ({ client, directory }: PluginContext): Promise<P
       pty_spawn: ptySpawn,
       pty_write: ptyWrite,
       pty_read: ptyRead,
+      pty_snapshot: ptySnapshot,
       pty_list: ptyList,
       pty_kill: ptyKill,
     },

src/plugin.ts

@@ -5,7 +5,13 @@ import { version as bunPtyVersion } from 'bun-pty/package.json'
 import { NotificationManager } from './notification-manager.ts'
 import { OutputManager } from './output-manager.ts'
 import { SessionLifecycleManager } from './session-lifecycle.ts'
-import type { PTYSessionInfo, ReadResult, SearchResult, SpawnOptions } from './types.ts'
+import type {
+  PTYSessionInfo,
+  ReadResult,
+  SearchResult,
+  SnapshotResult,
+  SpawnOptions,
+} from './types.ts'
 import { withSession } from './utils.ts'
 
 // Monkey-patch bun-pty to fix race condition in _startReadLoop
@@ -159,6 +165,10 @@ class PTYManager {
     )
   }
 
+  snapshot(id: string): SnapshotResult | null {
+    return withSession(this.lifecycleManager, id, (session) => this.outputManager.snapshot(session), null)
+  }
+
   kill(id: string, cleanup: boolean = false): boolean {
     return this.lifecycleManager.kill(id, cleanup)
   }

src/plugin/pty/manager.ts

@@ -1,4 +1,4 @@
-import type { PTYSession, ReadResult, SearchResult } from './types.ts'
+import type { PTYSession, ReadResult, SearchResult, SnapshotResult } from './types.ts'
 
 export class OutputManager {
   write(session: PTYSession, data: string): boolean {
@@ -26,4 +26,12 @@ export class OutputManager {
     const hasMore = offset + paginatedMatches.length < totalMatches
     return { matches: paginatedMatches, totalMatches, totalLines, offset, hasMore }
   }
+
+  snapshot(session: PTYSession): SnapshotResult {
+    return {
+      id: session.id,
+      status: session.status,
+      ...session.snapshot.getState(),
+    }
+  }
 }

src/plugin/pty/output-manager.ts

@@ -1,5 +1,6 @@
 import { spawn, type IPty } from 'bun-pty'
 import { RingBuffer } from './buffer.ts'
+import { TerminalSnapshot } from './snapshot.ts'
 import type { PTYSession, PTYSessionInfo, SpawnOptions } from './types.ts'
 import { DEFAULT_TERMINAL_COLS, DEFAULT_TERMINAL_ROWS } from '../constants.ts'
 import moment from 'moment'
@@ -24,6 +25,7 @@ export class SessionLifecycleManager {
       opts.title ?? (`${opts.command} ${args.join(' ')}`.trim() || `Terminal ${id.slice(-4)}`)
 
     const buffer = new RingBuffer()
+    const snapshot = new TerminalSnapshot(DEFAULT_TERMINAL_COLS, DEFAULT_TERMINAL_ROWS)
     return {
       id,
       title,
@@ -39,6 +41,7 @@ export class SessionLifecycleManager {
       parentAgent: opts.parentAgent,
       notifyOnExit: opts.notifyOnExit ?? false,
       buffer,
+      snapshot,
       process: null, // will be set
     }
   }
@@ -63,6 +66,7 @@ export class SessionLifecycleManager {
   ): void {
     session.process?.onData((data: string) => {
       session.buffer.append(data)
+      session.snapshot.write(data)
       onData(session, data)
     })
 
@@ -143,6 +147,8 @@ export class SessionLifecycleManager {
   }
 
   toInfo(session: PTYSession): PTYSessionInfo {
+    const snapshot = session.snapshot.getState()
+
     return {
       id: session.id,
       title: session.title,
@@ -156,6 +162,7 @@ export class SessionLifecycleManager {
       pid: session.pid,
       createdAt: session.createdAt.toISOString(true),
       lineCount: session.buffer.length,
+      size: snapshot.size,
     }
   }
 }

src/plugin/pty/session-lifecycle.ts

@@ -0,0 +1,109 @@
+import { Terminal } from '@xterm/headless'
+
+// FNV-1a 64-bit constants for content hashing
+const FNV_OFFSET_BASIS = BigInt('14695981039346656037')
+const FNV_PRIME = BigInt('1099511628211')
+const FNV_MASK = BigInt('18446744073709551615')
+
+export interface SnapshotCursor {
+  row: number
+  col: number
+  visible: boolean
+}
+
+export interface SnapshotSize {
+  cols: number
+  rows: number
+}
+
+export interface SnapshotState {
+  size: SnapshotSize
+  cursor: SnapshotCursor
+  text: string
+  contentHash: string
+}
+
+/**
+ * Maintains a headless xterm.js terminal that mirrors PTY output,
+ * providing parsed screen state (visible text, cursor, dimensions)
+ * without any ANSI escape code noise.
+ */
+export class TerminalSnapshot {
+  private readonly terminal: Terminal
+  private pendingWrite: Promise<void> = Promise.resolve()
+  private cachedState: SnapshotState
+
+  constructor(cols: number, rows: number, scrollback: number = rows * 10) {
+    this.terminal = new Terminal({
+      cols,
+      rows,
+      scrollback,
+      allowProposedApi: true,
+    })
+    this.cachedState = this.buildState()
+  }
+
+  /**
+   * Queues data for the headless terminal to parse.
+   * xterm.js processes writes asynchronously via time-slicing,
+   * so we chain each write's completion callback to ensure the
+   * cached state is always built from fully-parsed output.
+   */
+  write(data: string): void {
+    this.pendingWrite = this.pendingWrite.then(
+      () =>
+        new Promise<void>((resolve) => {
+          this.terminal.write(data, resolve)
+        })
+    ).then(() => {
+      this.cachedState = this.buildState()
+    })
+  }
+
+  getState(): SnapshotState {
+    return this.cachedState
+  }
+
+  async getSettledState(): Promise<SnapshotState> {
+    await this.pendingWrite
+    return this.cachedState
+  }
+
+  private buildState(): SnapshotState {
+    const buffer = this.terminal.buffer.active
+    const startLine = buffer.viewportY
+    const lines: string[] = []
+
+    for (let row = 0; row < this.terminal.rows; row++) {
+      const line = buffer.getLine(startLine + row)
+      lines.push(line?.translateToString(false) ?? '')
+    }
+
+    const text = lines.join('\n').replace(/\s+$/u, '')
+
+    return {
+      size: {
+        cols: this.terminal.cols,
+        rows: this.terminal.rows,
+      },
+      cursor: {
+        row: buffer.cursorY,
+        col: buffer.cursorX,
+        // Local @xterm/headless typings omit showCursor from modes
+        visible: (this.terminal.modes as { showCursor?: boolean }).showCursor ?? true,
+      },
+      text,
+      contentHash: computeContentHash(text),
+    }
+  }
+}
+
+/** FNV-1a 64-bit hash for fast, stable change detection of screen content. */
+function computeContentHash(text: string): string {
+  let hash = FNV_OFFSET_BASIS
+  for (let index = 0; index < text.length; index++) {
+    hash ^= BigInt(text.charCodeAt(index))
+    hash = (hash * FNV_PRIME) & FNV_MASK
+  }
+  return hash.toString()
+}

src/plugin/pty/snapshot.ts

@@ -0,0 +1,26 @@
+import { tool } from '@opencode-ai/plugin'
+import { manager } from '../manager.ts'
+import { buildSessionNotFoundError } from '../utils.ts'
+import DESCRIPTION from './snapshot.txt'
+
+export const ptySnapshot = tool({
+  description: DESCRIPTION,
+  args: {
+    id: tool.schema.string().describe('The PTY session ID (e.g., pty_a1b2c3d4)'),
+  },
+  async execute(args) {
+    const snapshot = manager.snapshot(args.id)
+    if (!snapshot) {
+      throw buildSessionNotFoundError(args.id)
+    }
+
+    return [
+      `<pty_snapshot id="${snapshot.id}" status="${snapshot.status}" hash="${snapshot.contentHash}">`,
+      `Size: ${snapshot.size.cols}x${snapshot.size.rows}`,
+      `Cursor: (${snapshot.cursor.row}, ${snapshot.cursor.col}) visible=${snapshot.cursor.visible}`,
+      '---',
+      snapshot.text || '(Screen is empty)',
+      `</pty_snapshot>`,
+    ].join('\n')
+  },
+})

src/plugin/pty/tools/snapshot.ts

@@ -0,0 +1 @@
+Captures the current visible terminal screen as clean text (ANSI-free) with cursor position, size, and a contentHash for change detection. Prefer over pty_read for TUI apps.

src/plugin/pty/tools/snapshot.txt

@@ -1,5 +1,6 @@
 import type { IPty } from 'bun-pty'
 import type { RingBuffer } from './buffer.ts'
+import type { SnapshotState, TerminalSnapshot } from './snapshot.ts'
 import type moment from 'moment'
 
 export type PTYStatus = 'running' | 'exited' | 'killing' | 'killed'
@@ -21,6 +22,7 @@ export interface PTYSession {
   parentAgent?: string
   notifyOnExit: boolean
   buffer: RingBuffer
+  snapshot: TerminalSnapshot
   process: IPty | null
 }
 
@@ -37,6 +39,7 @@ export interface PTYSessionInfo {
   pid: number
   createdAt: string
   lineCount: number
+  size?: SnapshotState['size']
 }
 
 export interface SpawnOptions {
@@ -65,3 +68,8 @@ export interface SearchResult {
   offset: number
   hasMore: boolean
 }
+
+export interface SnapshotResult extends SnapshotState {
+  id: string
+  status: PTYStatus
+}