Skip to content

native-helper-boundaries.md

Latest commit

 

History

History
56 lines (39 loc) · 2.76 KB

native-helper-boundaries.md

File metadata and controls

56 lines (39 loc) · 2.76 KB

Native Helper Boundaries

MirrorNote ships three Rust helper binaries. They are separate processes because capture ownership, STT runtime ownership, and agent job ownership have different failure modes, permissions, and resource profiles.

native/native-host-rust

Owns macOS integration and meeting artifact orchestration.

  • JSON-line protocol with Electron.
  • CoreAudio microphone and system-audio capture.
  • Meeting bundle creation and final artifact writes.
  • Track mixing and recording.mp3 export.
  • Source-only speaker labeling and transcript artifact assembly.
  • Launching MirrorNoteSTTServer through its framed protocol when captured audio needs transcription.

It must not call an external Whisper CLI directly or parse Whisper terminal output. STT runtime details belong to stt-server-rust. It also must not own long-lived agent jobs; those belong to agent-server-rust.

native/stt-server-rust

Owns local speech-to-text runtime behavior.

  • 4-byte length-prefixed JSON frame protocol.
  • STT runtime health checks.
  • Silero VAD model discovery and silence gating before Whisper transcription.
  • Model configuration validation.
  • Embedded whisper-rs / whisper.cpp model loading and transcription, with Metal enabled for macOS builds.
  • File and chunk transcription.
  • Whisper segment extraction.
  • Runtime session state for STT requests.

It must not create meeting bundles, write MirrorNote artifacts, manage CoreAudio capture, or know about note/source-context files.

native/agent-server-rust

Owns local agent job behavior.

  • Local daemon lifecycle independent of the desktop window.
  • JSON-line TCP protocol on localhost.
  • generateContext job execution.
  • Persistent job status under the meeting bundle's context/agent-jobs/ directory.
  • Source context packet generation using the shared Rust context packet module.

It must not capture audio, run STT, manage app windows, or introduce cloud-server assumptions.

Electron Boundary

Electron resolves helper paths and sets environment variables for packaged and development runs:

  • MIRROR_NOTE_NATIVE_HOST_PATH selects MirrorNoteNativeHost.
  • MIRROR_NOTE_STT_SERVER_PATH selects MirrorNoteSTTServer.
  • MIRROR_NOTE_AGENT_SERVER_PATH selects MirrorNoteAgentServer.
  • MIRROR_NOTE_AGENT_SERVER_PORT selects the localhost agent daemon port.
  • MIRROR_NOTE_SILERO_VAD_MODEL_PATH optionally selects the Silero VAD model used by the STT server.

Electron may call MirrorNoteSTTServer directly for explicit retry/retranscription flows, but live capture finalization goes through MirrorNoteNativeHost, which delegates transcription to MirrorNoteSTTServer. Electron sends source context jobs to MirrorNoteAgentServer, and failures are persisted as retryable note metadata without blocking transcript or note review.