fix(pty): strip terminal control sequences from pty_read and pty_exited output

PTY output is handed to the host as plain text: pty_read results and the <pty_exited> notification. Escape sequences in it (on Windows, ConPTY prefixes every session with mode, clear-screen and window-title sequences) carry no information for the agent and are executed by the OpenCode TUI, which writes text content to the terminal verbatim in both V1 and V2.

Strip them with node:util stripVTControlCharacters plus string-type sequences (OSC/DCS/APC) and leftover C0/C1 control characters, so it works under both Bun and Node hosts. Search now matches against the sanitized text, and the exit notification skips lines that are empty once sanitized. The raw buffer used by the Web UI is unchanged. PTY_SANITIZE_OUTPUT=0 restores the raw output.

Fixes #75

Author: NAnD71

README.md

@@ -294,6 +294,7 @@ This eliminates the need for polling—perfect for long-running processes like b
 | `PTY_MAX_BUFFER_LINES` | `50000`    | Maximum lines to keep in output buffer per session |
 | `PTY_WEB_HOSTNAME`     | `::1`      | Hostname for the web server to bind to (IPv6 loopback by default) |
 | `PTY_WEB_PORT`         | `0` (random) | Port for the web server (0 = random port)        |
+| `PTY_SANITIZE_OUTPUT`  | enabled    | Strip terminal control sequences from `pty_read` output and `<pty_exited>` notifications; set to `0` or `false` to get the raw output |
 
 ### Permissions
 

src/plugin/pty/buffer.ts

@@ -42,12 +42,18 @@ export class RingBuffer {
     return this.buffer
   }
 
-  search(pattern: RegExp): SearchMatch[] {
+  /**
+   * Returns the lines matching `pattern`. When `normalize` is given, each line
+   * is normalized first and the pattern is matched against (and returns) the
+   * normalized text.
+   */
+  search(pattern: RegExp, normalize?: (line: string) => string): SearchMatch[] {
     const matches: SearchMatch[] = []
     const lines: string[] = this.splitBufferLines()
 
     for (let i = 0; i < lines.length; i++) {
-      const line = lines[i]
+      const rawLine = lines[i]
+      const line = rawLine !== undefined && normalize ? normalize(rawLine) : rawLine
       if (line && pattern.test(line)) {
         matches.push({ lineNumber: i + 1, text: line })
       }

src/plugin/pty/manager.ts

@@ -127,11 +127,17 @@ class PTYManager {
     )
   }
 
-  search(id: string, pattern: RegExp, offset: number = 0, limit?: number): SearchResult | null {
+  search(
+    id: string,
+    pattern: RegExp,
+    offset: number = 0,
+    limit?: number,
+    normalize?: (line: string) => string
+  ): SearchResult | null {
     return withSession(
       this.lifecycleManager,
       id,
-      (session) => this.outputManager.search(session, pattern, offset, limit),
+      (session) => this.outputManager.search(session, pattern, offset, limit, normalize),
       null
     )
   }

src/plugin/pty/notification-manager.ts

@@ -2,6 +2,7 @@ import type { SessionNotifier } from '../../adapters/types.ts'
 import type { PTYSession } from './types.ts'
 import type { OpencodeClient } from '@opencode-ai/sdk'
 import { NOTIFICATION_LINE_TRUNCATE, NOTIFICATION_TITLE_TRUNCATE } from '../constants.ts'
+import { isOutputSanitizationEnabled, sanitizeTerminalText } from './sanitize.ts'
 
 export class NotificationManager implements SessionNotifier {
   private client: OpencodeClient | null = null
@@ -63,19 +64,22 @@ export class NotificationManager implements SessionNotifier {
  * context's `ctx.session.prompt`).
  */
 export function buildExitNotification(session: PTYSession, exitCode: number): string {
-  const lineCount = session.buffer.length
+  const bufferLines = session.buffer.read()
+  const lineCount = bufferLines.length
+  const sanitize = isOutputSanitizationEnabled()
   let lastLine = ''
-  if (lineCount > 0) {
-    for (let i = lineCount - 1; i >= 0; i--) {
-      const bufferLines = session.buffer.read(i, 1)
-      const line = bufferLines[0]
-      if (line !== undefined && line.trim() !== '') {
-        lastLine =
-          line.length > NOTIFICATION_LINE_TRUNCATE
-            ? `${line.slice(0, NOTIFICATION_LINE_TRUNCATE)}...`
-            : line
-        break
-      }
+  for (let i = lineCount - 1; i >= 0; i--) {
+    const rawLine = bufferLines[i]
+    if (rawLine === undefined) continue
+    // Lines that hold only control sequences (e.g. the ConPTY preamble) are
+    // blank once sanitized and must not be reported as the last line.
+    const line = sanitize ? sanitizeTerminalText(rawLine) : rawLine
+    if (line.trim() !== '') {
+      lastLine =
+        line.length > NOTIFICATION_LINE_TRUNCATE
+          ? `${line.slice(0, NOTIFICATION_LINE_TRUNCATE)}...`
+          : line
+      break
     }
   }
 

src/plugin/pty/output-manager.ts

@@ -17,8 +17,14 @@ export class OutputManager {
     return { lines, totalLines, offset, hasMore }
   }
 
-  search(session: PTYSession, pattern: RegExp, offset: number = 0, limit?: number): SearchResult {
-    const allMatches = session.buffer.search(pattern)
+  search(
+    session: PTYSession,
+    pattern: RegExp,
+    offset: number = 0,
+    limit?: number,
+    normalize?: (line: string) => string
+  ): SearchResult {
+    const allMatches = session.buffer.search(pattern, normalize)
     const totalMatches = allMatches.length
     const totalLines = session.buffer.length
     const paginatedMatches =

src/plugin/pty/sanitize.ts

@@ -0,0 +1,41 @@
+import { stripVTControlCharacters } from 'node:util'
+
+// String-type sequences: OSC (ESC ]), DCS (ESC P), SOS (ESC X), PM (ESC ^) and
+// APC (ESC _), plus their C1 forms, up to BEL or ST (or the end of the line).
+// `stripVTControlCharacters` only knows a restricted OSC payload alphabet and
+// leaves e.g. Windows window titles (`ESC]0;C:\Program Files\...BEL`) behind.
+const STRING_SEQUENCES =
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal control sequences is the point
+  /(?:\u001B[\]PX^_]|[\u0090\u0098\u009D-\u009F])[\s\S]*?(?:\u0007|\u001B\\|\u009C|$)/g
+
+// C0 controls except \t and \n, DEL, and C1 controls. Whatever survives the
+// passes above (a lone ESC, \r, BEL, BS, ...) is still written to the terminal
+// verbatim by hosts that render this text.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g
+
+/**
+ * Whether text handed to the host (`pty_read` results and `<pty_exited>`
+ * notifications) is stripped of terminal control sequences.
+ *
+ * Enabled by default; set `PTY_SANITIZE_OUTPUT=0` (or `false`) to receive the
+ * raw terminal output instead.
+ */
+export function isOutputSanitizationEnabled(): boolean {
+  const value = process.env.PTY_SANITIZE_OUTPUT?.trim().toLowerCase()
+  return value !== '0' && value !== 'false'
+}
+
+/**
+ * Removes terminal control sequences (CSI, OSC, ...) and remaining control
+ * characters from a single line of PTY output, keeping tabs.
+ *
+ * Only applied where output leaves the plugin as text; the raw buffer is kept
+ * intact for the Web UI terminal.
+ */
+export function sanitizeTerminalText(text: string): string {
+  return stripVTControlCharacters(text.replace(STRING_SEQUENCES, '')).replace(
+    CONTROL_CHARACTERS,
+    ''
+  )
+}

src/plugin/pty/tools/read.ts

@@ -3,6 +3,7 @@ import { manager } from '../manager.ts'
 import { DEFAULT_READ_LIMIT, MAX_LINE_LENGTH } from '../../../shared/constants.ts'
 import { buildSessionNotFoundError } from '../utils.ts'
 import { formatLine } from '../formatters.ts'
+import { isOutputSanitizationEnabled, sanitizeTerminalText } from '../sanitize.ts'
 import type { PTYSessionInfo } from '../types.ts'
 import DESCRIPTION from './read.txt'
 
@@ -106,7 +107,9 @@ function handlePatternRead(
 ): string {
   const regex = validateAndCreateRegex(pattern, ignoreCase)
 
-  const result = manager.search(id, regex, offset, limit)
+  // Match against the text the agent will see, not the raw escape sequences.
+  const normalize = isOutputSanitizationEnabled() ? sanitizeTerminalText : undefined
+  const result = manager.search(id, regex, offset, limit, normalize)
   if (!result) {
     throw buildSessionNotFoundError(id)
   }
@@ -170,8 +173,13 @@ function handlePlainRead(
     )
   }
 
+  const sanitize = isOutputSanitizationEnabled()
   const formattedLines = result.lines.map((line, index) =>
-    formatLine(line, result.offset + index + 1, MAX_LINE_LENGTH)
+    formatLine(
+      sanitize ? sanitizeTerminalText(line) : line,
+      result.offset + index + 1,
+      MAX_LINE_LENGTH
+    )
   )
 
   const paginationMessage = `(Buffer has more lines. Use offset=${result.offset + result.lines.length} to read beyond line ${result.offset + result.lines.length})`

test/notification-manager.test.ts

@@ -1,7 +1,10 @@
-import { describe, expect, it, mock } from 'bun:test'
+import { afterEach, describe, expect, it, mock } from 'bun:test'
 import type { OpencodeClient } from '@opencode-ai/sdk'
 import { RingBuffer } from '../src/plugin/pty/buffer.ts'
-import { NotificationManager } from '../src/plugin/pty/notification-manager.ts'
+import {
+  NotificationManager,
+  buildExitNotification,
+} from '../src/plugin/pty/notification-manager.ts'
 import type { PTYSession } from '../src/plugin/pty/types.ts'
 
 type PromptPayload = {
@@ -159,3 +162,63 @@ describe('NotificationManager', () => {
     expect(text).toContain('Process reached its PTY timeout and was stopped automatically.')
   })
 })
+
+describe('buildExitNotification', () => {
+  const original = process.env.PTY_SANITIZE_OUTPUT
+
+  afterEach(() => {
+    if (original === undefined) {
+      delete process.env.PTY_SANITIZE_OUTPUT
+    } else {
+      process.env.PTY_SANITIZE_OUTPUT = original
+    }
+  })
+
+  function sessionWithOutput(output: string): PTYSession {
+    const buffer = new RingBuffer()
+    buffer.append(output)
+    return createSession({ buffer })
+  }
+
+  it('reports the last line without terminal control sequences', () => {
+    delete process.env.PTY_SANITIZE_OUTPUT
+
+    const text = buildExitNotification(
+      sessionWithOutput('\x1b[?25l\x1b[2J\x1b[H\r\n\x1b[32mBuild completed.\x1b[0m\x1b[K\r\n'),
+      0
+    )
+
+    expect(text).toContain('Last Line: Build completed.\n')
+    expect(text).not.toContain('\x1b')
+    expect(text).not.toContain('\r')
+  })
+
+  it('skips trailing lines that only contain control sequences', () => {
+    delete process.env.PTY_SANITIZE_OUTPUT
+
+    const text = buildExitNotification(
+      sessionWithOutput(
+        'real output\r\n\x1b[?9001h\x1b[?1004h\x1b]0;C:\\Windows\\pwsh.exe\x07\x1b[K'
+      ),
+      0
+    )
+
+    expect(text).toContain('Last Line: real output\n')
+  })
+
+  it('reports an empty last line when the output is only control sequences', () => {
+    delete process.env.PTY_SANITIZE_OUTPUT
+
+    const text = buildExitNotification(sessionWithOutput('\x1b[?9001h\x1b[?1004h\x1b[2J\x1b[H'), 0)
+
+    expect(text).toContain('Output Lines: 1\nLast Line: \n')
+  })
+
+  it('keeps the raw last line when PTY_SANITIZE_OUTPUT=0', () => {
+    process.env.PTY_SANITIZE_OUTPUT = '0'
+
+    const text = buildExitNotification(sessionWithOutput('\x1b[32mdone\x1b[0m\n'), 0)
+
+    expect(text).toContain('Last Line: \x1b[32mdone\x1b[0m\n')
+  })
+})

test/pty-tools.test.ts

@@ -1,9 +1,10 @@
-import { describe, it, expect, beforeEach, mock, spyOn, afterAll } from 'bun:test'
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn, afterAll } from 'bun:test'
 import { ptySpawn } from '../src/plugin/pty/tools/spawn.ts'
 import { ptyRead } from '../src/plugin/pty/tools/read.ts'
 import { ptyList } from '../src/plugin/pty/tools/list.ts'
 import { RingBuffer } from '../src/plugin/pty/buffer.ts'
 import { manager } from '../src/plugin/pty/manager.ts'
+import { sanitizeTerminalText } from '../src/plugin/pty/sanitize.ts'
 
 describe('PTY Tools', () => {
   afterAll(() => {
@@ -239,12 +240,76 @@ describe('PTY Tools', () => {
 
       const result = await ptyRead.execute(args, ctx)
 
-      expect(manager.search).toHaveBeenCalledWith('test-session-id', /line/, 0, 500)
+      expect(manager.search).toHaveBeenCalledWith(
+        'test-session-id',
+        /line/,
+        0,
+        500,
+        sanitizeTerminalText
+      )
       expect(result).toContain('<pty_output id="test-session-id" status="running" pattern="line">')
       expect(result).toContain('00001| line 1')
       expect(result).toContain('(1 match from 2 total lines)')
     })
 
+    describe('terminal control sequences', () => {
+      const original = process.env.PTY_SANITIZE_OUTPUT
+      const ctx = {
+        sessionID: 'parent',
+        messageID: 'msg',
+        agent: 'agent',
+        abort: new AbortController().signal,
+        metadata: () => {},
+        ask: async () => {},
+        directory: '/tmp',
+        worktree: '/tmp',
+      }
+
+      beforeEach(() => {
+        spyOn(manager, 'read').mockReturnValue({
+          lines: ['\x1b[?9001h\x1b[?1004h\x1b[2J\x1b[H', '\x1b[31merror:\x1b[0m boom\r'],
+          offset: 0,
+          hasMore: false,
+          totalLines: 2,
+        })
+      })
+
+      afterEach(() => {
+        if (original === undefined) {
+          delete process.env.PTY_SANITIZE_OUTPUT
+        } else {
+          process.env.PTY_SANITIZE_OUTPUT = original
+        }
+      })
+
+      it('strips them from read output', async () => {
+        delete process.env.PTY_SANITIZE_OUTPUT
+
+        const result = await ptyRead.execute({ id: 'test-session-id' }, ctx)
+
+        expect(result).not.toContain('\x1b')
+        expect(result).not.toContain('\r')
+        expect(result).toContain('00001| \n')
+        expect(result).toContain('00002| error: boom\n')
+      })
+
+      it('keeps them when PTY_SANITIZE_OUTPUT=0', async () => {
+        process.env.PTY_SANITIZE_OUTPUT = '0'
+
+        const result = await ptyRead.execute({ id: 'test-session-id' }, ctx)
+
+        expect(result).toContain('00002| \x1b[31merror:\x1b[0m boom\r')
+      })
+
+      it('does not normalize search lines when PTY_SANITIZE_OUTPUT=0', async () => {
+        process.env.PTY_SANITIZE_OUTPUT = '0'
+
+        await ptyRead.execute({ id: 'test-session-id', pattern: 'boom' }, ctx)
+
+        expect(manager.search).toHaveBeenCalledWith('test-session-id', /boom/, 0, 500, undefined)
+      })
+    })
+
     it('should throw for invalid session', async () => {
       spyOn(manager, 'get').mockReturnValue(null)
 
@@ -378,6 +443,18 @@ describe('PTY Tools', () => {
       ])
     })
 
+    it('should match and return normalized lines when searching with a normalizer', () => {
+      const buffer = new RingBuffer(200)
+      buffer.append('\x1b[?25l\x1b[2J\n\x1b[31merror:\x1b[0m boom\nok 1\n')
+
+      expect(buffer.search(/^error: boom$/, sanitizeTerminalText)).toEqual([
+        { lineNumber: 2, text: 'error: boom' },
+      ])
+      // Digits inside escape sequences must not produce matches.
+      expect(buffer.search(/\d/, sanitizeTerminalText)).toEqual([{ lineNumber: 3, text: 'ok 1' }])
+      expect(buffer.readRaw()).toContain('\x1b[31m')
+    })
+
     it('should clear buffer', () => {
       const buffer = new RingBuffer(100)
       buffer.append('line1\nline2')