feat(desktop): add extensible terminal output filter mechanism by Kitenite · Pull Request #584 · ParadevAI/Paradev

Kitenite · 2026-01-03T21:47:27Z

Summary

Add extensible TerminalOutputFilterChain mechanism for filtering terminal output before display
Implement OSC response filter to remove unwanted terminal query responses (color queries, device attributes, cursor position reports)
Filters apply to display only—scrollback history preserves raw data for accuracy

Why / Context

Terminal emulators respond to certain escape sequences with response strings. For example, when a shell or program queries the background color with \e]11;?\a, xterm.js responds with \e]11;rgb:RRRR/GGGG/BBBB\e\. These responses were being echoed back to the display, showing noise like 11;rgb:1a1a/1a1a/1a1a1R in the terminal output.

How It Works

Filter Interface (terminal-output-filter.ts): Defines TerminalOutputFilter interface and TerminalOutputFilterChain class
OSC Response Filter (terminal-output-filters/osc-response-filter.ts): Filters:
- OSC 10/11/12 color responses
- Device Attributes (DA) responses
- Cursor Position Reports (CPR)
- Partial/malformed OSC responses
Integration (session.ts): Applies filter chain before writing to dataBatcher (display), not before writing to scrollback

Data flow:

pty → session.onData → scrollback (unfiltered) → filterChain.apply() → dataBatcher → xterm (filtered)

Manual QA Checklist

Terminal displays normally without escape sequence noise
Strings like 11;rgb:1a1a/1a1a/1a1a1R no longer appear in terminal output
Normal ANSI color codes still work (e.g., colored ls output)
Scrollback history works correctly
App starts without errors

Testing

bun run typecheck ✅
bun test apps/desktop/src/main/lib/terminal-output-filter.test.ts ✅ (22 tests)
bun test apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.test.ts ✅

Extending

To add a new filter:

import type { TerminalOutputFilter } from "../terminal-output-filter";

export const myFilter: TerminalOutputFilter = {
  id: "my-filter",
  description: "Filters X",
  filter(data: string): string {
    return data.replace(/pattern/g, "");
  },
};

Register in terminal-output-filters/index.ts:

terminalOutputFilterChain.register(myFilter);

New Files

apps/desktop/src/main/lib/terminal-output-filter.ts - Core filter mechanism
apps/desktop/src/main/lib/terminal-output-filter.test.ts - Tests
apps/desktop/src/main/lib/terminal-output-filters/index.ts - Registration
apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.ts - OSC filter
apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.test.ts - OSC filter tests

Summary by CodeRabbit

Release Notes

New Features
- Terminal output is now automatically filtered to remove unnecessary escape sequences, improving readability of displayed terminal content in the desktop application.
Tests
- Added comprehensive unit tests for terminal output filtering functionality.

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

- Add TerminalOutputFilterChain for managing output filters - Implement OSC response filter (filters color queries, DA, CPR) - Filter applied before display only (scrollback preserves raw data) - Fixes display of unwanted sequences like '11;rgb:1a1a/1a1a/1a1a1R'

coderabbitai · 2026-01-03T21:47:38Z

📝 Walkthrough

Walkthrough

This PR introduces a terminal output filter chain system that registers filters during app startup and applies them to terminal output before display. Specifically, it registers an OSC response filter that strips terminal query/response escape sequences, integrated into the session data handling pipeline.

Changes

Cohort / File(s)	Summary
Core Filter Infrastructure `apps/desktop/src/main/lib/terminal-output-filter.ts`, `apps/desktop/src/main/lib/terminal-output-filter.test.ts`	Introduces TerminalOutputFilter interface and TerminalOutputFilterChain class (with register, unregister, apply, getRegisteredFilters, clear methods) and a singleton instance; comprehensive unit tests validate filter registration (deduplication), removal, sequential application, and chain clearing.
OSC Response Filter `apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.ts`, `apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.test.ts`	Implements oscResponseFilter using regex patterns to strip OSC color responses, device attributes (DA1/DA2), and cursor position reports (CPR); extensive tests cover mixed content, partial sequences, and terminator variations (BEL/ST).
Filter Registration & Initialization `apps/desktop/src/main/lib/terminal-output-filters/index.ts`	Exports registerDefaultFilters() function that wires oscResponseFilter into the terminalOutputFilterChain; re-exports oscResponseFilter for external use.
Integration `apps/desktop/src/main/index.ts`, `apps/desktop/src/main/lib/terminal/session.ts`	Invokes registerDefaultFilters() during app startup; injects terminalOutputFilterChain into session data handling to filter output before display while preserving raw data for port scanning.

Sequence Diagram

sequenceDiagram
    participant App as Application<br/>Startup
    participant Main as Main Process<br/>(index.ts)
    participant Chain as TerminalOutputFilterChain
    participant OSCFilter as OSC Response<br/>Filter
    participant Session as Terminal<br/>Session
    participant Display as Display/Batcher

    App->>Main: Application starts
    Main->>Main: registerDefaultFilters()
    Main->>OSCFilter: Create oscResponseFilter
    OSCFilter->>Chain: register(oscResponseFilter)
    Chain->>Chain: Store filter by id
    Note over Chain: Filter chain ready

    Session->>Session: Terminal data received
    Session->>Chain: apply(rawData)
    Chain->>OSCFilter: filter(data)
    OSCFilter->>OSCFilter: Strip OSC sequences<br/>via regex
    OSCFilter-->>Chain: Filtered data
    Chain-->>Session: Result
    Session->>Display: Write filtered data<br/>to batcher

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

refactor(desktop): remove escape filter from terminal hot path #497: Directly modifies the same session.ts hot path and removes previous TerminalEscapeFilter-based filtering in favor of this filter chain approach.
fix: filter terminal query responses from scrollback on reattach #154: Implements the same terminal query/OSC/CPR/DA response filtering logic to sanitize persisted and displayed terminal output.
implement more font and xterm rendering improvements #324: Modifies terminal session data handling in session.ts, establishing data flow patterns that interact with this filter integration.

Poem

🐰 A filter chain springs to life,
Stripping escape codes, ending the strife!
OSC responses fade away,
Clean terminal output on display.
—Rabbit's whisker-twitch of glee ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.
Linked Issues check	❓ Inconclusive	The PR description lacks any GitHub issue links or references (e.g., 'closes #123', 'fixes #456') in the Related Issues section, which appears to be empty.	Add GitHub issue references if this PR resolves or relates to specific issues; update the Related Issues section accordingly.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding an extensible terminal output filter mechanism, which is the primary objective of this PR.
Description check	✅ Passed	The PR description is comprehensive and complete, covering all template sections: summary, context, implementation details, testing, and additional guidance for extending the system.
Out of Scope Changes check	✅ Passed	All changes are directly related to the stated objective: implementing a terminal output filter mechanism. No unrelated or out-of-scope modifications are evident.

✨ Finishing touches

📝 Generate docstrings

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

Actionable comments posted: 2

🧹 Nitpick comments (3)

apps/desktop/src/main/index.ts (1)
17-20: Good placement for filter registration.

The registerDefaultFilters() call is correctly positioned at the module level after Sentry initialization but before app startup. The synchronous registration ensures filters are ready before any terminal sessions are created.

Consider wrapping the call in a try-catch block to prevent startup failures if filter registration encounters issues:
🔎 Optional defensive error handling
-registerDefaultFilters();
+try {
+	registerDefaultFilters();
+} catch (error) {
+	console.error("[main] Failed to register terminal output filters:", error);
+	// App can continue without filters, but log the failure
+}
This follows the pattern already established in the codebase (lines 229-234) for optional initialization steps that shouldn't block app startup.
apps/desktop/src/main/lib/terminal-output-filter.ts (2)
14-19: Add logging for duplicate filter registration.

The method silently returns when a duplicate filter ID is detected, which could hide configuration issues. According to the coding guidelines, use prefixed console logging with context.
🔎 Proposed fix to add logging
 register(filter: TerminalOutputFilter): void {
   if (this.filters.some((f) => f.id === filter.id)) {
+    console.warn(`[terminal-output-filter/register] Duplicate filter ID "${filter.id}" - skipping registration`);
     return;
   }
   this.filters.push(filter);
+  console.debug(`[terminal-output-filter/register] Registered filter: ${filter.id}`);
 }
21-28: Consider adding logging for unregister operations.

While the boolean return value indicates success, adding debug logging would help troubleshoot filter lifecycle issues, consistent with the logging pattern suggested for register().
🔎 Proposed addition
 unregister(filterId: string): boolean {
   const index = this.filters.findIndex((f) => f.id === filterId);
   if (index === -1) {
+    console.debug(`[terminal-output-filter/unregister] Filter not found: ${filterId}`);
     return false;
   }
   this.filters.splice(index, 1);
+  console.debug(`[terminal-output-filter/unregister] Unregistered filter: ${filterId}`);
   return true;
 }

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a818bc2 and ea688cf.

📒 Files selected for processing (7)

apps/desktop/src/main/index.ts
apps/desktop/src/main/lib/terminal-output-filter.test.ts
apps/desktop/src/main/lib/terminal-output-filter.ts
apps/desktop/src/main/lib/terminal-output-filters/index.ts
apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.test.ts
apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.ts
apps/desktop/src/main/lib/terminal/session.ts

🧰 Additional context used

📓 Path-based instructions (6)

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-output-filters/osc-response-filter.test.ts
apps/desktop/src/main/lib/terminal-output-filter.test.ts
apps/desktop/src/main/index.ts
apps/desktop/src/main/lib/terminal-output-filters/index.ts
apps/desktop/src/main/lib/terminal-output-filter.ts
apps/desktop/src/main/lib/terminal-output-filters/osc-response-filter.ts
apps/desktop/src/main/lib/terminal/session.ts

**/*.{ts,tsx}