Skip to content

refactor(desktop): remove escape filter from terminal hot path - #497

Merged
Kitenite merged 4 commits into
mainfrom
disable-processing-scrollback
Dec 24, 2025
Merged

Kitenite merged 4 commits into
mainfrom
disable-processing-scrollback

Conversation

@Kitenite

@Kitenite Kitenite commented Dec 24, 2025 •

Copy link
Copy Markdown
Member

Summary

  • Remove TerminalEscapeFilter from terminal session data handler - no more regex processing on every PTY data chunk
  • Simplify terminal-escape-filter.ts from ~300 lines to 46 lines, keeping only clear scrollback detection (ESC[3J)
  • Delete ~770 lines of filter code and tests that ran on the hot path

The escape filter was designed to strip terminal query responses (device attributes, cursor reports, color responses) before storing scrollback. This prevented "garbage" characters on session replay, but added complexity:

  1. Regex processing on every data chunk
  2. Stateful buffering to handle sequences split across chunks
  3. Risk of crashes with large scrollback

New approach: Store raw scrollback during runtime. For clean persistence, xterm.js serialize addon can be used on the cold path (session save/restore) rather than filtering every chunk.

Test plan

  • bun test passes for session and escape filter tests
  • bun run typecheck passes
  • Manual test: terminal session recovery works
  • Manual test: clear command / Cmd+K still clears scrollback correctly

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

  • Refactor

    • Simplified terminal escape sequence handling and session management
    • Terminal scrollback recovery now preserves history through direct character-based truncation rather than complex filtering
    • Streamlined overall terminal data processing pipeline
  • Tests

    • Updated terminal session and escape sequence tests to align with simplified handling

✏️ Tip: You can customize this high-level summary in your review settings.

Kitenite and others added 2 commits December 23, 2025 22:59
Remove TerminalEscapeFilter processing from the terminal session data handler.
The filter was running regex on every data chunk to strip terminal query
responses (device attributes, cursor reports, etc.) before storing scrollback.

This complexity is unnecessary - escape sequence filtering will be handled
by using xterm.js serialize addon on the cold path (session persistence)
rather than processing every chunk on the hot path.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ction

Remove the TerminalEscapeFilter class and all query response filtering
patterns. Keep only the clear scrollback detection functions which are
still needed to detect when the user clears the terminal (Cmd+K / clear).

Removed:
- TerminalEscapeFilter class (stateful chunked filter)
- filterTerminalQueryResponses function
- All FILTER_PATTERNS for CPR, DA1, DA2, DA3, DECRPM, OSC, etc.
- ~500 lines of test code for the removed functionality

Kept:
- containsClearScrollbackSequence() - detects ESC[3J
- extractContentAfterClear() - extracts content after clear

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Dec 24, 2025 •

Copy link
Copy Markdown
Contributor

Warning

Rate limit exceeded

@Kitenite has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 0 minutes and 39 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between bfef7fd and 1ef6d86.

📒 Files selected for processing (2)
  • apps/desktop/src/main/lib/terminal/manager.test.ts
  • apps/desktop/src/main/lib/terminal/session.ts
📝 Walkthrough

Walkthrough

Simplifies terminal escape sequence handling by replacing a stateful TerminalEscapeFilter class with two focused utility functions (containsClearScrollbackSequence, extractContentAfterClear) and removing filter usage from session management and recovery logic.

Changes

Cohort / File(s) Summary
Terminal Escape Filter API Refactoring
apps/desktop/src/main/lib/terminal-escape-filter.ts, apps/desktop/src/main/lib/terminal-escape-filter.test.ts
Removed TerminalEscapeFilter class, filterTerminalQueryResponses function, and patterns export. Added containsClearScrollbackSequence() and extractContentAfterClear() utility functions for ED3-based clear-scrollback handling. Test coverage updated to focus only on the new utilities and removed tests for deprecated APIs.
Session Integration Updates
apps/desktop/src/main/lib/terminal/session.ts, apps/desktop/src/main/lib/terminal/session.test.ts, apps/desktop/src/main/lib/terminal/types.ts
Removed TerminalEscapeFilter initialization and usage throughout session lifecycle. recoverScrollback now truncates via character slicing instead of filtering. setupDataHandler bypasses filter initialization on Clear Scrollback. Removed escapeFilter property from TerminalSession interface. Test cases updated to reflect direct scrollback handling without escape filtering.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐰 A filter once grand, now refined to its core,
Two helpers emerge where complexity bore.
Stateful buffering fades into the night,
Direct, simple paths bring clarity bright! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
Description check ❓ Inconclusive The description covers the main changes with a clear summary, rationale, and test plan. However, it uses an informal template structure not matching the repository's required template sections. Restructure using the repository template: add 'Description', 'Related Issues', 'Type of Change' (mark 'Refactor'), 'Testing' details, and 'Additional Notes' sections.
✅ Passed checks (1 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: removing escape filter processing from the terminal hot path, which is the core intent of all modifications across multiple files.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (1)
apps/desktop/src/main/lib/terminal/session.ts (1)

29-36: Scrollback truncation approach is sound.

The slice-based truncation to 500,000 characters is a pragmatic approach that avoids the per-chunk regex processing overhead. Using slice(-MAX_SCROLLBACK_CHARS) correctly preserves the most recent content.

Consider extracting MAX_SCROLLBACK_CHARS to a configuration or constants module if this limit might need adjustment based on user feedback or memory constraints.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e80c3df and bfef7fd.

📒 Files selected for processing (5)
  • apps/desktop/src/main/lib/terminal-escape-filter.test.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal/types.ts
💤 Files with no reviewable changes (2)
  • apps/desktop/src/main/lib/terminal/types.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.test.ts
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Avoid using any type in TypeScript - maintain type safety unless absolutely necessary

Files:

  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Run Biome for formatting, linting, import organization, and safe fixes at the root level using bun run lint:fix

Files:

  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
apps/desktop/src/{main,renderer,preload}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use type-safe IPC communication - define channel types in apps/desktop/src/shared/ipc-channels.ts before implementing handlers

Files:

  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
apps/desktop/src/main/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

Accept object parameters in IPC handlers - do not use positional parameters in ipcMain.handle()

Files:

  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
apps/desktop/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/desktop/AGENTS.md)

apps/desktop/**/*.{ts,tsx}: For Electron interprocess communication, ALWAYS use tRPC as defined in src/lib/trpc
Use alias as defined in tsconfig.json when possible
Prefer zustand for state management if it makes sense. Do not use effect unless absolutely necessary.
For tRPC subscriptions with trpc-electron, ALWAYS use the observable pattern from @trpc/server/observable instead of async generators, as the library explicitly checks isObservable(result) and throws an error otherwise

Files:

  • apps/desktop/src/main/lib/terminal/session.ts
  • apps/desktop/src/main/lib/terminal-escape-filter.ts
  • apps/desktop/src/main/lib/terminal/session.test.ts
**/*.test.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Place tests co-located with components using .test.ts or .test.tsx naming convention

Files:

  • apps/desktop/src/main/lib/terminal/session.test.ts
🧬 Code graph analysis (1)
apps/desktop/src/main/lib/terminal/session.ts (1)
apps/desktop/src/main/lib/terminal/port-manager.ts (1)
  • portManager (359-359)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Build
🔇 Additional comments (5)
apps/desktop/src/main/lib/terminal-escape-filter.ts (1)

1-46: Clean refactor of escape filter utilities.

The simplified API with containsClearScrollbackSequence and extractContentAfterClear is well-designed. Good documentation explaining why RIS (ESC c) is intentionally excluded to avoid interfering with TUI applications.

The dual representation (RegExp for test() and string constant for lastIndexOf()) is appropriate for their respective use cases.

apps/desktop/src/main/lib/terminal/session.test.ts (2)

32-51: Test appropriately simplified to match the refactor.

The test now correctly validates that raw content is recovered from disk without escape sequence filtering. The assertion on Line 46 directly compares against scrollbackContent, which is the expected behavior after removing the filter processing.


78-96: Test coverage reduced but aligned with simplified flushSession.

The test now only verifies dataBatcher.dispose() is called, which matches the simplified implementation. The local disposed flag approach is clean and straightforward.

apps/desktop/src/main/lib/terminal/session.ts (2)

152-178: Hot path optimization looks correct.

The data handler now:

  1. Correctly detects clear scrollback sequences and resets scrollback
  2. Stores raw dataToStore directly without regex filtering per chunk
  3. Scans for ports in raw output

This aligns with the PR objective to remove per-chunk regex processing. The trade-off (storing terminal query responses in scrollback) is acceptable since xterm.js serialize addon handles cleanup on the cold path during session save/restore.


220-222: Flush logic correctly simplified.

With the escape filter removed, flushSession now only needs to dispose the data batcher. This is cleaner and matches the refactored architecture.

@Kitenite
Kitenite force-pushed the disable-processing-scrollback branch from 32f09db to fb1a8bc Compare December 24, 2025 07:29
@Kitenite
Kitenite merged commit 13c172f into main Dec 24, 2025
5 checks passed
@Kitenite
Kitenite deleted the disable-processing-scrollback branch December 24, 2025 07:35
@github-actions

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

Service Status
Neon Database (Neon) ⚠️

Thank you for your contribution! 🎉


Preview resources have been processed for cleanup

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant