Skip to content

ADR-006: EditorBridge Protocol

Status: Accepted
Date: 2026-05-18
Deciders: Mohsen Seyedkazemi Ardebili

Context

The v0.4 LspContextProvider injects editor symbols into the Whisper initial_prompt for the Neovim bridge implementation. Editor-LSP integration is a differentiated capability — no competing voice dictation tool implements it. Realising this advantage in v1.0 requires elevating the v0.4 prototype to a formal Protocol-level component and shipping at least two editor implementations at launch. The initial_prompt mechanism is available in every Whisper-class runtime, and the integration is entirely the application's responsibility. Active-editor detection on Linux Wayland requires compositor-specific adapters; this is new work in v1.0.

Decision

The v0.4 LspContextProvider is formalised into an EditorBridge trait. v1.0 ships NeovimBridge and VSCodeBridge; HelixBridge, EmacsBridge, and JetBrainsBridge are planned for v1.1.

The protocol contract:

pub struct EditorContext {
    pub file_path: Option<PathBuf>,
    pub language: Option<String>,
    pub project_root: Option<PathBuf>,
    pub recent_symbols: Vec<Symbol>,   // up to 32
    pub imports: Vec<Import>,
    pub cursor: Option<CursorContext>,
    pub recent_edits: Vec<Edit>,
}

pub trait EditorBridge: Send + Sync {
    fn name(&self) -> &str;
    async fn get_context(&self, cursor_hint: Option<Position>) -> Option<EditorContext>;
    async fn get_active_file(&self) -> Option<PathBuf>;
    async fn watch_context_changes(&self) -> Pin<Box<dyn Stream<Item = EditorContext>>>;
}

On hold_start, the daemon pre-warms by calling get_context(). The resulting recent_symbols are compiled into an initial_prompt string for the STT layer; the full EditorContext is serialised into a structured block in the LLM prompt.

Active-editor detection uses a tiered WindowDetector that probes compositor APIs in order: Hyprland IPC (tier 1), Sway IPC (tier 2), wlr-foreign-toplevel protocol (tier 3), X11 EWMH (tier 4), and NullWindowDetector (graceful degrade). This covers approximately 80% of the Linux target user base in v1.0; GNOME Wayland and KDE Wayland are deferred to v1.1.

Consequences

Positive: - Closes the only gap in the competitive feature matrix for editor-LSP integration. - Code-identifier transcription accuracy is expected to improve substantially from LSP-symbol vocabulary biasing via initial_prompt. - The LLM agent can reference actual file symbols and types rather than relying on training-data approximations. - The Protocol architecture allows new editor bridges to be added in one file as v1.1 additions.

Negative / trade-offs: - Each editor bridge is a small independent integration project; v1.0 ships two, v1.1 adds three, with ongoing maintenance required. - The VS Code bridge requires a companion extension published to the Marketplace and Open VSX. - GNOME Wayland and KDE Wayland active-window detection are deferred to v1.1; users on those compositors get no context injection in v1.0. - LSP server quality varies by language; the bridge handles missing data gracefully but cannot synthesise symbols where the LSP does not expose them.

Implementation

The EditorBridge trait and EditorContext struct are in yazses-core/src/editor/bridge.rs. NeovimBridge is in yazses-core/src/editor/neovim.rs (using the Neovim msgpack-RPC API). VSCodeBridge is implemented as a companion VS Code extension communicating over a local socket. The WindowDetector tiers are in yazses-core/src/editor/window_detector.rs.