agent-cli 0.98.2__tar.gz → 0.98.4__tar.gz

{agent_cli-0.98.2 → agent_cli-0.98.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.98.2
+Version: 0.98.4
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>
@@ -899,8 +899,9 @@ the `[defaults]` section of your configuration file.
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮
-│ --extra-instructions                TEXT  Extra instructions appended to the LLM       │
-│                                           cleanup prompt (requires --llm).             │
+│ --extra-instructions                TEXT  Extra ASR context where supported, and LLM   │
+│                                           cleanup instructions when --llm is enabled.  │
+│                                           The NeMo backend ignores ASR text prompts.   │
 │ --llm                   --no-llm          Clean up transcript with LLM: fix errors,    │
 │                                           add punctuation, remove filler words. Uses   │
 │                                           --extra-instructions if set (via CLI or      │

{agent_cli-0.98.2 → agent_cli-0.98.4}/README.md

@@ -791,8 +791,9 @@ the `[defaults]` section of your configuration file.
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮
-│ --extra-instructions                TEXT  Extra instructions appended to the LLM       │
-│                                           cleanup prompt (requires --llm).             │
+│ --extra-instructions                TEXT  Extra ASR context where supported, and LLM   │
+│                                           cleanup instructions when --llm is enabled.  │
+│                                           The NeMo backend ignores ASR text prompts.   │
 │ --llm                   --no-llm          Clean up transcript with LLM: fix errors,    │
 │                                           add punctuation, remove filler words. Uses   │
 │                                           --extra-instructions if set (via CLI or      │

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/agents/transcribe.py

@@ -10,14 +10,14 @@ import time
 from contextlib import suppress
 from datetime import UTC, datetime, timedelta
 from pathlib import Path  # noqa: TC003
-from typing import Any, TypedDict
+from typing import TYPE_CHECKING, Any, TypedDict
 
 import typer
 
 from agent_cli import config, opts
 from agent_cli.cli import app
 from agent_cli.core import process
-from agent_cli.core.audio import setup_devices
+from agent_cli.core.audio import AudioLevelLogWriter, setup_devices
 from agent_cli.core.deps import requires_extras
 from agent_cli.core.diarization import (
     SpeakerDiarizer,
@@ -54,6 +54,9 @@ from agent_cli.services.llm import process_and_update_clipboard
 
 LOGGER = logging.getLogger()
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 
 class TranscriptResult(TypedDict, total=False):
     """Result of transcription with optional LLM processing."""
@@ -361,6 +364,7 @@ async def _async_main(  # noqa: PLR0912, PLR0915, C901
     diarization_cfg: config.Diarization | None = None,
     emit_output: bool = True,
     raise_diarization_errors: bool = False,
+    audio_level_callback: Callable[[bytes], None] | None = None,
 ) -> TranscriptResult:
     """Unified async entry point for both live and file-based transcription."""
     start_time = time.monotonic()
@@ -451,6 +455,7 @@ async def _async_main(  # noqa: PLR0912, PLR0915, C901
                     save_recording=save_recording,
                     extra_instructions=extra_instructions,
                     recording_path_callback=_set_saved_recording_path,
+                    audio_level_callback=audio_level_callback,
                 )
 
         elapsed = time.monotonic() - start_time
@@ -598,7 +603,10 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     extra_instructions: str | None = typer.Option(
         None,
         "--extra-instructions",
-        help="Extra instructions appended to the LLM cleanup prompt (requires `--llm`).",
+        help=(
+            "Extra ASR context where supported, and LLM cleanup instructions when "
+            "`--llm` is enabled. The NeMo backend ignores ASR text prompts."
+        ),
         rich_help_panel="LLM Configuration",
     ),
     from_file: Path | None = opts.FROM_FILE,
@@ -641,6 +649,7 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
     transcription_log: Path | None = opts.TRANSCRIPTION_LOG,
+    voice_level_log: Path | None = opts.VOICE_LEVEL_LOG,
     # --- Diarization Options ---
     diarize: bool = opts.DIARIZE,
     diarize_format: opts.DiarizeFormat = opts.DIARIZE_FORMAT,
@@ -691,6 +700,9 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     # Expand user path for transcription log
     if transcription_log:
         transcription_log = transcription_log.expanduser()
+    voice_level_log = _option_default(voice_level_log)
+    if voice_level_log:
+        voice_level_log = voice_level_log.expanduser()
 
     enroll_speakers = _option_default(enroll_speakers)
     identify_speakers = _option_default(identify_speakers)
@@ -895,6 +907,7 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     # Use context manager before audio setup so --stop can target startup reliably.
     try:
         with process.pid_file_context(process_name), suppress(KeyboardInterrupt):
+            audio_level_writer = AudioLevelLogWriter(voice_level_log) if voice_level_log else None
             audio_in_cfg = config.AudioInput(
                 input_device_index=input_device_index,
                 input_device_name=input_device_name,
@@ -926,6 +939,9 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
                     diarization_cfg=diarization_cfg,
                     emit_output=not json_output,
                     raise_diarization_errors=diarize,
+                    audio_level_callback=audio_level_writer.write_chunk
+                    if audio_level_writer
+                    else None,
                 ),
             )
     except ImportError as exc:

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/agents/voice_edit.py

@@ -46,7 +46,7 @@ from agent_cli.agents._voice_agent_common import (
 )
 from agent_cli.cli import app
 from agent_cli.core import process
-from agent_cli.core.audio import setup_devices
+from agent_cli.core.audio import AudioLevelLogWriter, setup_devices
 from agent_cli.core.deps import requires_extras
 from agent_cli.core.utils import (
     enable_json_mode,
@@ -106,6 +106,7 @@ async def _async_main(
     openai_tts_cfg: config.OpenAITTS,
     kokoro_tts_cfg: config.KokoroTTS,
     gemini_tts_cfg: config.GeminiTTS,
+    audio_level_log: Path | None = None,
 ) -> str | None:
     """Core asynchronous logic for the voice assistant."""
     device_info = setup_devices(general_cfg, audio_in_cfg, audio_out_cfg)
@@ -114,6 +115,7 @@ async def _async_main(
     input_device_index, _, tts_output_device_index = device_info
     audio_in_cfg.input_device_index = input_device_index
     audio_out_cfg.output_device_index = tts_output_device_index
+    audio_level_writer = AudioLevelLogWriter(audio_level_log) if audio_level_log else None
 
     original_text = get_clipboard_text()
     if original_text is None:
@@ -132,6 +134,7 @@ async def _async_main(
             LOGGER,
             live=live,
             quiet=general_cfg.quiet,
+            audio_level_callback=audio_level_writer.write_chunk if audio_level_writer else None,
         )
 
         if not audio_data:
@@ -226,6 +229,7 @@ def voice_edit(
     list_devices: bool = opts.LIST_DEVICES,
     quiet: bool = opts.QUIET,
     json_output: bool = opts.JSON_OUTPUT,
+    voice_level_log: Path | None = opts.VOICE_LEVEL_LOG,
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
@@ -255,6 +259,9 @@ def voice_edit(
         enable_json_mode()
 
     setup_logging(log_level, log_file, quiet=effective_quiet)
+    voice_level_log = getattr(voice_level_log, "default", voice_level_log)
+    if voice_level_log:
+        voice_level_log = voice_level_log.expanduser()
     general_cfg = config.General(
         log_level=log_level,
         log_file=log_file,
@@ -293,6 +300,7 @@ def voice_edit(
                 openai_tts_cfg=cfgs.openai_tts,
                 kokoro_tts_cfg=cfgs.kokoro_tts,
                 gemini_tts_cfg=cfgs.gemini_tts,
+                audio_level_log=voice_level_log,
             ),
         )
         if json_output:

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/core/audio.py

@@ -4,10 +4,15 @@ from __future__ import annotations
 
 import asyncio
 import functools
+import json
 import logging
+import math
+import struct
 import threading
+import time
 from contextlib import asynccontextmanager, contextmanager
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Literal
 
 from rich.text import Text
@@ -22,6 +27,7 @@ from agent_cli.core.utils import (
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Awaitable, Callable, Generator
+    from pathlib import Path
 
     import sounddevice as sd
     from rich.live import Live
@@ -30,6 +36,7 @@ if TYPE_CHECKING:
 
 LOGGER = logging.getLogger(__name__)
 _AUDIO_SHUTDOWN_TIMEOUT_SECONDS = 0.5
+_MINIMUM_INPUT_DECIBELS = -55.0
 
 
 @dataclass
@@ -64,6 +71,74 @@ class StreamConfig:
         )
 
 
+def normalized_audio_level(chunk: bytes) -> float:
+    """Return a 0...1 speech level from mono little-endian int16 PCM."""
+    sample_count = len(chunk) // constants.AUDIO_FORMAT_WIDTH
+    if sample_count <= 0:
+        return 0.0
+
+    pcm = chunk[: sample_count * constants.AUDIO_FORMAT_WIDTH]
+    samples = struct.unpack(f"<{sample_count}h", pcm)
+    mean_square = sum((sample / 32768.0) ** 2 for sample in samples) / sample_count
+    if mean_square <= 0:
+        return 0.0
+
+    root_mean_square = math.sqrt(mean_square)
+    decibels = 20 * math.log10(root_mean_square)
+    if decibels <= _MINIMUM_INPUT_DECIBELS:
+        return 0.0
+
+    linear_level = (decibels - _MINIMUM_INPUT_DECIBELS) / abs(_MINIMUM_INPUT_DECIBELS)
+    return min(1.0, math.sqrt(linear_level))
+
+
+class AudioLevelLogWriter:
+    """Append normalized audio levels for UI consumers."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        interval_seconds: float = 0.05,
+        monotonic_clock: Callable[[], float] = time.monotonic,
+        timestamp_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        """Create a writer and clear stale samples at the destination."""
+        self.path = path.expanduser()
+        self.interval_seconds = interval_seconds
+        self.monotonic_clock = monotonic_clock
+        self.timestamp_clock = timestamp_clock
+        self._last_write = -math.inf
+        self._enabled = True
+        self._lock = threading.Lock()
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text("")
+        except OSError:
+            self._enabled = False
+
+    def write_chunk(self, chunk: bytes) -> None:
+        """Append one normalized level sample for a PCM chunk."""
+        with self._lock:
+            if not self._enabled:
+                return
+            now = self.monotonic_clock()
+            if now - self._last_write < self.interval_seconds:
+                return
+            self._last_write = now
+
+            entry = {
+                "timestamp": self.timestamp_clock().isoformat(),
+                "level": round(normalized_audio_level(chunk), 4),
+            }
+            try:
+                with self.path.open("a", encoding="utf-8") as file:
+                    file.write(json.dumps(entry, separators=(",", ":")))
+                    file.write("\n")
+            except OSError:
+                self._enabled = False
+
+
 class _AudioTee:
     """A thread-safe class to tee a continuous audio stream into multiple asyncio queues.
 

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/opts.py

@@ -429,6 +429,13 @@ TRANSCRIPTION_LOG: Path | None = typer.Option(
     "Recent entries provide context for LLM cleanup.",
     rich_help_panel="General Options",
 )
+VOICE_LEVEL_LOG: Path | None = typer.Option(
+    None,
+    "--voice-level-log",
+    help="Append normalized microphone levels to a JSONL file for UI indicators.",
+    hidden=True,
+    rich_help_panel="General Options",
+)
 
 # --- Server Options ---
 SERVER_HOST: str = typer.Option(

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/server/whisper/backends/nemo.py

@@ -344,6 +344,7 @@ class NemoWhisperBackend:
         self._resolved_model = _resolve_model_name(config.model_name)
         self._executor: ProcessPoolExecutor | None = None
         self._device: str | None = None
+        self._warned_initial_prompt_ignored = False
 
     @property
     def is_loaded(self) -> bool:
@@ -415,7 +416,7 @@ class NemoWhisperBackend:
         source_filename: str | None = None,
         language: str | None = None,
         task: Literal["transcribe", "translate"] = "transcribe",  # noqa: ARG002
-        initial_prompt: str | None = None,  # noqa: ARG002
+        initial_prompt: str | None = None,
         temperature: float = 0.0,  # noqa: ARG002
         vad_filter: bool = True,  # noqa: ARG002
         word_timestamps: bool = False,
@@ -424,6 +425,13 @@ class NemoWhisperBackend:
         if self._executor is None:
             msg = "Model not loaded. Call load() first."
             raise RuntimeError(msg)
+        if initial_prompt and not self._warned_initial_prompt_ignored:
+            logger.warning(
+                "Whisper-style initial prompts are not supported by the agent-cli NeMo backend; "
+                "ignoring prompt for model %s",
+                self._config.model_name,
+            )
+            self._warned_initial_prompt_ignored = True
 
         audio = await asyncio.to_thread(_prepare_audio_for_nemo, audio, source_filename)
 

{agent_cli-0.98.2 → agent_cli-0.98.4}/agent_cli/services/asr.py

@@ -210,6 +210,31 @@ def create_recorded_audio_transcriber(
     raise ValueError(msg)
 
 
+def _schedule_audio_level_callback(
+    pending_tasks: set[asyncio.Task[None]],
+    audio_level_callback: Callable[[bytes], None],
+    chunk: bytes,
+    logger: logging.Logger,
+) -> None:
+    """Run level callbacks off the event loop so UI metering cannot delay ASR sends."""
+
+    async def run_callback() -> None:
+        try:
+            await asyncio.to_thread(audio_level_callback, chunk)
+        except Exception:
+            logger.exception("Audio level callback failed")
+
+    task = asyncio.create_task(run_callback())
+    pending_tasks.add(task)
+    task.add_done_callback(pending_tasks.discard)
+
+
+async def _finish_audio_level_callbacks(pending_tasks: set[asyncio.Task[None]]) -> None:
+    """Wait for scheduled level callbacks to finish before returning."""
+    if pending_tasks:
+        await asyncio.gather(*pending_tasks, return_exceptions=True)
+
+
 async def _send_audio(
     client: AsyncClient,
     stream: sd.InputStream,
@@ -221,6 +246,7 @@ async def _send_audio(
     save_recording: bool = True,
     initial_prompt: str | None = None,
     recording_path_callback: Callable[[Path], None] | None = None,
+    audio_level_callback: Callable[[bytes], None] | None = None,
 ) -> None:
     """Read from mic and send to Wyoming server."""
     from wyoming.asr import Transcribe  # noqa: PLC0415
@@ -233,11 +259,19 @@ async def _send_audio(
 
     # Buffer to save audio if requested
     audio_buffer = io.BytesIO() if save_recording else None
+    pending_audio_level_tasks: set[asyncio.Task[None]] = set()
 
     async def send_chunk(chunk: bytes) -> None:
         """Send audio chunk to ASR server and optionally buffer it."""
         if audio_buffer is not None:
             audio_buffer.write(chunk)
+        if audio_level_callback:
+            _schedule_audio_level_callback(
+                pending_audio_level_tasks,
+                audio_level_callback,
+                chunk,
+                logger,
+            )
         await client.write_event(AudioChunk(audio=chunk, **constants.WYOMING_AUDIO_CONFIG).event())
 
     try:
@@ -252,16 +286,19 @@ async def _send_audio(
             progress_style="blue",
         )
     finally:
-        await client.write_event(AudioStop().event())
-        logger.debug("Sent AudioStop")
+        try:
+            await client.write_event(AudioStop().event())
+            logger.debug("Sent AudioStop")
 
-        # Save the recording to disk if requested
-        if save_recording and audio_buffer:
-            audio_data = audio_buffer.getvalue()
-            if audio_data:
-                saved_path = _save_audio_to_file(audio_data, logger)
-                if saved_path and recording_path_callback:
-                    recording_path_callback(saved_path)
+            # Save the recording to disk if requested
+            if save_recording and audio_buffer:
+                audio_data = audio_buffer.getvalue()
+                if audio_data:
+                    saved_path = _save_audio_to_file(audio_data, logger)
+                    if saved_path and recording_path_callback:
+                        recording_path_callback(saved_path)
+        finally:
+            await _finish_audio_level_callbacks(pending_audio_level_tasks)
 
 
 async def record_audio_to_buffer(queue: asyncio.Queue, logger: logging.Logger) -> bytes:
@@ -328,6 +365,7 @@ async def record_audio_with_manual_stop(
     live: Live | None = None,
     save_recording: bool = True,
     recording_path_callback: Callable[[Path], None] | None = None,
+    audio_level_callback: Callable[[bytes], None] | None = None,
 ) -> bytes:
     """Record audio to a buffer using a manual stop signal.
 
@@ -339,29 +377,41 @@ async def record_audio_with_manual_stop(
         live: Rich Live display for progress
         save_recording: If True, save the recording to disk
         recording_path_callback: Optional callback invoked with the saved WAV path.
+        audio_level_callback: Optional callback invoked with each PCM chunk.
 
     Returns:
         The recorded audio data as bytes
 
     """
     audio_buffer = io.BytesIO()
+    pending_audio_level_tasks: set[asyncio.Task[None]] = set()
 
     def buffer_chunk(chunk: bytes) -> None:
         """Buffer audio chunk."""
         audio_buffer.write(chunk)
+        if audio_level_callback:
+            _schedule_audio_level_callback(
+                pending_audio_level_tasks,
+                audio_level_callback,
+                chunk,
+                logger,
+            )
 
     stream_config = setup_input_stream(input_device_index)
     with open_audio_stream(stream_config) as stream:
-        await read_audio_stream(
-            stream=stream,
-            stop_event=stop_event,
-            chunk_handler=buffer_chunk,
-            logger=logger,
-            live=live,
-            quiet=quiet,
-            progress_message="Recording",
-            progress_style="green",
-        )
+        try:
+            await read_audio_stream(
+                stream=stream,
+                stop_event=stop_event,
+                chunk_handler=buffer_chunk,
+                logger=logger,
+                live=live,
+                quiet=quiet,
+                progress_message="Recording",
+                progress_style="green",
+            )
+        finally:
+            await _finish_audio_level_callbacks(pending_audio_level_tasks)
 
     audio_data = audio_buffer.getvalue()
 
@@ -431,6 +481,7 @@ async def _transcribe_live_audio_wyoming(
     final_callback: Callable[[str], None] | None = None,
     extra_instructions: str | None = None,
     recording_path_callback: Callable[[Path], None] | None = None,
+    audio_level_callback: Callable[[bytes], None] | None = None,
     **_kwargs: object,
 ) -> str | None:
     """Unified ASR transcription function."""
@@ -460,6 +511,7 @@ async def _transcribe_live_audio_wyoming(
                         save_recording=save_recording,
                         initial_prompt=effective_prompt,
                         recording_path_callback=recording_path_callback,
+                        audio_level_callback=audio_level_callback,
                     ),
                     _receive_transcript(
                         client,
@@ -488,6 +540,7 @@ async def _transcribe_live_audio_buffered(
     save_recording: bool = True,
     extra_instructions: str | None = None,
     recording_path_callback: Callable[[Path], None] | None = None,
+    audio_level_callback: Callable[[bytes], None] | None = None,
     **_kwargs: object,
 ) -> str | None:
     """Record audio to buffer, then transcribe.
@@ -502,6 +555,7 @@ async def _transcribe_live_audio_buffered(
         live=live,
         save_recording=save_recording,
         recording_path_callback=recording_path_callback,
+        audio_level_callback=audio_level_callback,
     )
     if not audio_data:
         return None

{agent_cli-0.98.2 → agent_cli-0.98.4}/docs/commands/transcribe.md

@@ -95,7 +95,7 @@ The `--from-file` option supports multiple audio formats:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--extra-instructions` | - | Extra instructions appended to the LLM cleanup prompt (requires `--llm`). |
+| `--extra-instructions` | - | Extra ASR context where supported, and LLM cleanup instructions when `--llm` is enabled. The NeMo backend ignores ASR text prompts. |
 | `--llm/--no-llm` | `false` | Clean up transcript with LLM: fix errors, add punctuation, remove filler words. Uses `--extra-instructions` if set (via CLI or config file). Not compatible with --diarize. |
 
 ### Audio Recovery

{agent_cli-0.98.2 → agent_cli-0.98.4}/macos/AgentCLI/Sources/AgentCLI/AgentCommand.swift

@@ -76,6 +76,8 @@ struct AgentCommand {
             "transcribe",
             "--toggle",
             "--quiet",
+            "--voice-level-log",
+            VoiceLevelLog.defaultLogPath,
             "--transcription-log",
             RecentTranscriptionReader.defaultLogPath,
         ],
@@ -97,7 +99,13 @@ struct AgentCommand {
     static let voiceEdit = AgentCommand(
         identifier: "voice-edit",
         title: "Voice Edit Clipboard",
-        arguments: ["voice-edit", "--toggle", "--quiet"],
+        arguments: [
+            "voice-edit",
+            "--toggle",
+            "--quiet",
+            "--voice-level-log",
+            VoiceLevelLog.defaultLogPath,
+        ],
         bootstrapRequirement: .transcription,
         showsRecordingIndicator: true,
         startNotificationTitle: "Voice Edit Started",

{agent_cli-0.98.2 → agent_cli-0.98.4}/macos/AgentCLI/Sources/AgentCLI/AgentRuntime.swift

@@ -177,6 +177,17 @@ struct AgentRuntime {
             }
         }
 
+        if CommandLine.arguments.contains("--agentcli-voice-level-self-test") {
+            do {
+                try Self.runVoiceLevelSelfTest()
+                print("AgentCLI voice-level self-test ok")
+                exit(0)
+            } catch {
+                print("AgentCLI voice-level self-test failed: \(error.localizedDescription)")
+                exit(1)
+            }
+        }
+
         guard CommandLine.arguments.contains("--agentcli-bootstrap-self-test") else { return }
 
         let bootstrap = ensureReady(for: .transcription, force: true)
@@ -201,6 +212,54 @@ struct AgentRuntime {
         exit(0)
     }
 
+    private static func runVoiceLevelSelfTest() throws {
+        guard argumentValue(AgentCommand.toggleTranscription.arguments, for: "--voice-level-log") == VoiceLevelLog.defaultLogPath else {
+            throw SelfTestError("Toggle Transcription does not pass --voice-level-log")
+        }
+        guard argumentValue(AgentCommand.voiceEdit.arguments, for: "--voice-level-log") == VoiceLevelLog.defaultLogPath else {
+            throw SelfTestError("Voice Edit does not pass --voice-level-log")
+        }
+
+        let logURL = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString)
+            .appendingPathExtension("jsonl")
+        defer { try? FileManager.default.removeItem(at: logURL) }
+
+        try """
+        {"timestamp":"2026-06-04T12:00:00Z","level":0.25}
+        {"timestamp":"2026-06-04T12:00:01Z","level":0.75}
+        """.write(to: logURL, atomically: true, encoding: .utf8)
+
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime]
+        guard let now = formatter.date(from: "2026-06-04T12:00:01Z") else {
+            throw SelfTestError("Could not construct voice-level test timestamp")
+        }
+        guard VoiceLevelLog.latestLevel(from: logURL, now: now) == CGFloat(0.75) else {
+            throw SelfTestError("VoiceLevelLog did not read latest fresh level")
+        }
+    }
+
+    private static func argumentValue(_ arguments: [String], for option: String) -> String? {
+        guard let index = arguments.firstIndex(of: option),
+              arguments.indices.contains(index + 1) else {
+            return nil
+        }
+        return arguments[index + 1]
+    }
+
+    private struct SelfTestError: LocalizedError {
+        let message: String
+
+        init(_ message: String) {
+            self.message = message
+        }
+
+        var errorDescription: String? {
+            message
+        }
+    }
+
     func ensureInstalled(
         force: Bool = false,
         progress: AgentBootstrapProgress = { _ in }