Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(dictation): format each window while you speak, only the last stretch at release

rubenluetke10-beepd1d2d97ea1a6
diff --git a/jarvis/dictation/polish.py b/jarvis/dictation/polish.py
index 7156e30277..d9e0f4b156 100644
--- a/jarvis/dictation/polish.py
+++ b/jarvis/dictation/polish.py
@@ -427,9 +427,16 @@ async def polish_transcript(
style: str = "neutral",
timeout_s: float | None = None,
translate_to: str = "",
+ preceding_text: str = "",
) -> PolishOutcome:
"""Format *raw* without changing what it says. Never raises, never loses text.
+ ``preceding_text`` is the already-delivered part of the SAME dictation when
+ the pass formats one stretch at a time (the incremental polish that keeps
+ the wait after key release flat). It reaches the model as a delimited
+ context block — style only, never repeated — and the guards still judge
+ *raw* against the answer alone. Ignored in translate mode.
+
``language`` is the ALREADY-RESOLVED transcript language (the pipeline
resolves it before it gets here); it steers the guards and appears in the
prompt only as a weak, explicitly-unreliable hint. ``protected_terms`` are
@@ -530,17 +537,24 @@ async def polish_transcript(
precision=precision,
)
else:
+ prompt_kwargs: dict[str, Any] = {}
+ if preceding_text.strip():
+ prompt_kwargs["continuation"] = True
system = build_polish_prompt(
language=language,
style=style,
protected_terms=protected_terms,
precision=precision,
+ **prompt_kwargs,
)
# The SAME fenced user message either way — the delimiter and the
# ``meta_output`` guard that watches for it are one mechanism, and a
# dictation shaped like an instruction has to stay material in both
# passes.
- user = build_polish_user_message(source)
+ if preceding_text.strip() and not translating:
+ user = build_polish_user_message(source, preceding=preceding_text)
+ else:
+ user = build_polish_user_message(source)
try:
polished = await asyncio.wait_for(
diff --git a/jarvis/dictation/polish_prompt.py b/jarvis/dictation/polish_prompt.py
index 934dbadf10..5f3c1a88ab 100644
--- a/jarvis/dictation/polish_prompt.py
+++ b/jarvis/dictation/polish_prompt.py
@@ -75,6 +75,25 @@ POLISH_PROMPT_VERSION: Final[int] = 7
RAW_OPEN_DELIMITER: Final[str] = "<<<BEGIN TRANSCRIPT>>>"
RAW_CLOSE_DELIMITER: Final[str] = "<<<END TRANSCRIPT>>>"
+#: Delimiters for the ALREADY-DELIVERED part of the same dictation, when the
+#: pass formats one stretch at a time (the incremental polish — see
+#: ``SpeechPipeline._dictation_session``). Same injection rule as the
+#: transcript block: the context is material, never instruction.
+CONTEXT_OPEN_DELIMITER: Final[str] = "<<<BEGIN CONTEXT>>>"
+CONTEXT_CLOSE_DELIMITER: Final[str] = "<<<END CONTEXT>>>"
+
+# Appended only when the call carries a context block. Kept apart from the
+# hard rules so a whole-text call (the Restore route, a short dictation)
+# keeps the exact prompt it was tuned with.
+_CONTINUATION_BLOCK: Final[str] = """\
+CONTINUATION. The user message may begin with a block between
+<<<BEGIN CONTEXT>>> and <<<END CONTEXT>>>: the part of the SAME dictation that
+is already final and delivered. It is there only so you can continue its
+style — capitalisation, punctuation, list formatting, the language it is in.
+Never repeat it, never change it, never comment on it. Return ONLY the
+formatted version of the transcript block; your first word continues
+directly after the context."""
+
#: The register hints a caller may ask for. This is the cheap analogue of the
#: reference tool's three-value application-type enum: one extra line in the
#: prompt, no per-application model, no new failure mode.
@@ -293,6 +312,7 @@ def build_polish_prompt(
style: str,
protected_terms: Sequence[str],
precision: bool = False,
+ continuation: bool = False,
) -> str:
"""Assemble the system prompt for one polish call.
@@ -318,6 +338,9 @@ def build_polish_prompt(
if precision:
parts.append(_PRECISION_BLOCK)
+ if continuation:
+ parts.append(_CONTINUATION_BLOCK)
+
hint_language = str(language or "").strip()
if hint_language and hint_language.lower() not in ("auto", "unknown"):
parts.append(_LANGUAGE_HINT.format(language=hint_language))
@@ -331,7 +354,7 @@ def build_polish_prompt(
return "\n\n".join(parts)
-def build_polish_user_message(raw: str) -> str:
+def build_polish_user_message(raw: str, *, preceding: str = "") -> str:
"""Wrap the untrusted transcript in the delimiters, injection-safely.
Two properties matter here and nothing else does:
@@ -344,10 +367,28 @@ def build_polish_user_message(raw: str) -> str:
dictation feature — losing text is the one unacceptable outcome) and only
breaks the literal marker.
"""
+ delimiters = (
+ RAW_OPEN_DELIMITER,
+ RAW_CLOSE_DELIMITER,
+ CONTEXT_OPEN_DELIMITER,
+ CONTEXT_CLOSE_DELIMITER,
+ )
body = str(raw or "")
- for delimiter in (RAW_OPEN_DELIMITER, RAW_CLOSE_DELIMITER):
+ for delimiter in delimiters:
body = body.replace(delimiter, _defuse(delimiter))
- return f"{RAW_OPEN_DELIMITER}\n{body}\n{RAW_CLOSE_DELIMITER}"
+ message = f"{RAW_OPEN_DELIMITER}\n{body}\n{RAW_CLOSE_DELIMITER}"
+ context = str(preceding or "")
+ if context.strip():
+ for delimiter in delimiters:
+ context = context.replace(delimiter, _defuse(delimiter))
+ # ``preceding`` is the already-delivered text of the SAME dictation —
+ # material for style only, wrapped exactly like the transcript so it
+ # can never close the block early either.
+ message = (
+ f"{CONTEXT_OPEN_DELIMITER}\n{context}\n{CONTEXT_CLOSE_DELIMITER}\n\n"
+ + message
+ )
+ return message
def _defuse(delimiter: str) -> str:
diff --git a/jarvis/speech/pipeline.py b/jarvis/speech/pipeline.py
index 833526a7c5..7857bf3c99 100644
--- a/jarvis/speech/pipeline.py
+++ b/jarvis/speech/pipeline.py
@@ -1318,6 +1318,13 @@ _DICTATION_CONCURRENT_READS = 3
_DICTATION_TAIL_DROP_MIN_S = 1.5
_DICTATION_TAIL_REREAD_BACK_S = 0.5
+# How long the release waits for the incremental polish worker to finish the
+# windows it already has — normally the last one, whose formatting started the
+# moment it was read. One configured polish budget plus a little: past that
+# the formatter is not answering and the whole-text pass (which has its own
+# ceiling and fails open to the raw text) takes over.
+_DICTATION_PREFIX_POLISH_WAIT_S = 3.0
+
class _SessionInputBuffer:
"""Replayable bounded handoff for one continuously captured mic stream.
@@ -10907,6 +10914,23 @@ class SpeechPipeline:
if code_switching or dictation_language == "auto"
else dictation_language
)
+ # INCREMENTAL POLISH. Once the final windows are read while the user is
+ # still speaking, the wording pass became the wait that grew with the
+ # dictation: 0.6-1.3 s for a long one, on text that had mostly been
+ # final for a minute. So each window is formatted as soon as it is read
+ # — one stretch at a time, each in the light of the already-formatted
+ # text before it — and on release only the last stretch is left to
+ # format. ``prefix_polish_raw`` is the merged RAW text of the windows
+ # formatted so far (a strict prefix of the final raw transcript, which
+ # is what lets ``_finish_dictation`` cut the remaining tail off);
+ # ``prefix_polish_text`` is their formatted text. The whole-text pass
+ # stays the fallback for every case the prefix does not hold.
+ prefix_polish_raw = ""
+ prefix_polish_text = ""
+ prefix_polish_windows = 0
+ prefix_polish_deltas = 0
+ prefix_polish_failed = False
+ prefix_polish_task: asyncio.Task[None] | None = None
def _append_unique(values: list[str], value: object) -> None:
text = str(value or "").strip()
@@ -11624,6 +11648,126 @@ class SpeechPipeline:
return merged
return text
+ async def _polish_delta(delta_raw: str, preceding: str) -> tuple[str, str]:
+ """One more stretch of the dictation, cleaned and formatted in the
+ light of what is already delivered. ``(text, status)``; never
+ raises, never loses the words (the cleaned stretch is the floor).
+ The same cleanup and the same pass ``_finish_dictation`` runs on a
+ whole text, applied to a stretch — so a stretch formatted early and
+ a tail formatted at release come out of the same machinery.
+ """
+ text = delta_raw
+ try:
+ from jarvis.dictation.cleanup import clean_transcript, tidy_transcript
+ from jarvis.dictation.polish import polish_enabled, polish_transcript
+
+ lang = resolve_dictation_language(
+ pinned=dictation_language, reported=language, text=delta_raw
+ )
+ outcome = clean_transcript(
+ delta_raw,
+ language=lang,
+ remove_fillers=bool(getattr(cfg, "remove_fillers", True)),
+ max_removed_fraction=float(
+ getattr(cfg, "filler_max_removed_fraction", 0.25)
+ ),
+ )
+ text = tidy_transcript(outcome.text)
+ if not text.strip():
+ return "", "skipped_short"
+ if not polish_enabled(cfg):
+ return text, "off"
+ protected = getattr(self, "_dictation_protected_terms", None)
+ result = await polish_transcript(
+ text,
+ language=lang,
+ cfg=cfg,
+ protected_terms=protected() if callable(protected) else (),
+ style=str(getattr(cfg, "polish_style", "neutral") or "neutral"),
+ preceding_text=preceding,
+ )
+ return result.text, result.status
+ except Exception: # noqa: BLE001 — never lose the words to the polish
+ log.debug("incremental dictation polish failed; keeping the stretch", exc_info=True)
+ return text, "provider_error"
+
+ async def _advance_prefix_polish() -> None:
+ """Format every final window that is read and not yet formatted, in
+ order, stopping at the first one still in flight. Re-kicked by each
+ window as it lands, so the formatted prefix follows the recording
+ at one window's distance.
+ """
+ nonlocal prefix_polish_raw, prefix_polish_text, prefix_polish_windows
+ nonlocal prefix_polish_deltas, prefix_polish_failed
+ from jarvis.dictation.merge import merge_transcripts
+
+ while not prefix_polish_failed:
+ reading = final_reads.get(prefix_polish_windows)
+ if reading is None:
+ return
+ window_text = (reading[0] or "").strip()
+ if prefix_polish_raw:
+ merged = merge_transcripts([prefix_polish_raw, window_text])
+ else:
+ merged = window_text
+ if not merged.startswith(prefix_polish_raw):
+ # The seam was rewritten — the prefix is no longer a prefix
+ # of the transcript, and the whole-text pass takes over.
+ prefix_polish_failed = True
+ log.debug("incremental dictation polish stopped: seam rewritten")
+ return
+ delta = merged[len(prefix_polish_raw) :].strip()
+ if delta:
+ piece, _status = await _polish_delta(delta, prefix_polish_text)
+ if piece:
+ prefix_polish_text = " ".join(
+ part for part in (prefix_polish_text, piece) if part
+ )
+ prefix_polish_deltas += 1
+ prefix_polish_raw = merged
+ prefix_polish_windows += 1
+
+ def _kick_prefix_polish() -> None:
+ """Start the formatting worker unless it is running or given up."""
+ nonlocal prefix_polish_task
+ if prefix_polish_failed or not final_quality_pass:
+ return
+ if not bool(getattr(cfg, "polish", True)) or bool(getattr(cfg, "translate", False)):
+ return
+ if prefix_polish_task is not None and not prefix_polish_task.done():
+ return
+ prefix_polish_task = asyncio.create_task(
+ _advance_prefix_polish(), name="dictation-prefix-polish"
+ )
+
+ async def _settle_prefix_polish() -> None:
+ """Let the worker finish the windows it already has — normally the
+ last one, started the moment it was read — within one polish budget.
+ Past that the whole-text pass takes over rather than making the
+ user wait on a formatter that is not answering.
+ """
+ nonlocal prefix_polish_failed
+ _kick_prefix_polish()
+ task = prefix_polish_task
+ if task is None:
+ return
+ try:
+ await asyncio.wait_for(
+ asyncio.shield(task), timeout=_DICTATION_PREFIX_POLISH_WAIT_S
+ )
+ except TimeoutError:
+ prefix_polish_failed = True
+ log.info(
+ "incremental dictation polish did not finish within %.1fs; "
+ "formatting the whole text instead.",
+ _DICTATION_PREFIX_POLISH_WAIT_S,
+ )
+ except asyncio.CancelledError:
+ raise
+ except Exception: # noqa: BLE001 — a formatter failure never costs the text
+ prefix_polish_failed = True
+ log.debug("incremental dictation polish worker failed", exc_info=True)
+
async def _read_final_window(idx: int, start: int, end: int) -> None:
"""Read ONE final window of the recording and file its result.
@@ -11708,6 +11852,10 @@ class SpeechPipeline:
)
lost_audio_bytes += max(0, (end - start) - final_overlap_bytes)
final_reads[idx] = ("", False)
+ finally:
+ # Whatever this window produced, the formatter may now have
+ # one more stretch to work on.
+ _kick_prefix_polish()
def _launch_final_window(start: int, end: int, *, prefetched: bool) -> None:
nonlocal final_next_index, final_prefetched
@@ -12046,6 +12194,10 @@ class SpeechPipeline:
release_wait_ms = round(
(time.monotonic() - release_started) * 1000.0
)
+ # Give the formatter the windows it has not seen yet
+ # (normally the one just read) before delivery decides how
+ # much of the text still needs formatting.
+ await _settle_prefix_polish()
if quality_text:
raw_text = quality_text
final_pass_status = "applied" # noqa: S105 - status token
@@ -12115,6 +12267,11 @@ class SpeechPipeline:
lost_audio_s=lost_audio_s,
dropped_audio_s=quality_metrics.dropout_duration_ms / 1000.0,
audio=bytes(buffer),
+ polished_prefix=(
+ (prefix_polish_raw, prefix_polish_text)
+ if prefix_polish_raw and not prefix_polish_failed
+ else None
+ ),
stt_providers=tuple(stt_providers),
stt_models=tuple(stt_models),
detected_languages=tuple(detected_languages),
@@ -12130,6 +12287,13 @@ class SpeechPipeline:
f"tail_repairs:{tail_repairs}",
f"pause_trim_ms:{round(pause_trim_bytes * 1000 / bytes_per_second)}",
f"capture_overflows:{capture_overflows}",
+ "polish_mode:"
+ + (
+ "incremental"
+ if prefix_polish_raw and not prefix_polish_failed
+ else "whole"
+ ),
+ f"polish_deltas:{prefix_polish_deltas}",
f"code_switching:{'on' if code_switching else 'off'}",
f"capture_restarts:{capture_restart_count}",
*audio_preprocessing.audit(),
@@ -12367,9 +12531,17 @@ class SpeechPipeline:
audio_clipping_ratio: float = 0.0,
audio_dropouts: int = 0,
audio_dropout_ms: int = 0,
+ polished_prefix: tuple[str, str] | None = None,
) -> str:
"""Clean, deliver and record one finished dictation. Returns the text.
+ ``polished_prefix`` is ``(raw, formatted)`` for the leading part of the
+ recording the session already cleaned and formatted while the user was
+ speaking (the incremental polish). When ``raw`` is a strict prefix of
+ ``raw_text``, only the remaining tail is formatted here — with the
+ formatted prefix as context — and the two are joined; otherwise the
+ whole text is formatted as before. The Restore route passes nothing.
+
Split out of ``_dictation_session`` so the delivery half is testable
without a microphone. Every step degrades on its own: a failed cleanup
falls back to the raw transcript, a failed insertion falls back to "it
@@ -12573,7 +12745,63 @@ class SpeechPipeline:
# wrong, is what made the delivered language alternate between
# two with nothing the user touched explaining it.
translate_to = resolve_translate_target(cfg)
- if polish_enabled(cfg) or translate_to:
+ prefix_raw, prefix_text = polished_prefix or ("", "")
+ incremental = bool(
+ prefix_raw
+ and not translate_to
+ and polish_enabled(cfg)
+ and raw_text.startswith(prefix_raw)
+ )
+ if incremental:
+ # Only the tail is left: clean it the same way the whole
+ # text was cleaned above and format it in the light of the
+ # already-formatted prefix.
+ tail_raw = raw_text[len(prefix_raw) :].strip()
+ tail_text = ""
+ polish_status = "applied"
+ if tail_raw:
+ try:
+ from jarvis.dictation.cleanup import (
+ clean_transcript,
+ tidy_transcript,
+ )
+
+ tail_outcome = clean_transcript(
+ tail_raw,
+ language=effective_language,
+ remove_fillers=bool(getattr(cfg, "remove_fillers", True)),
+ max_removed_fraction=float(
+ getattr(cfg, "filler_max_removed_fraction", 0.25)
+ ),
+ )
+ tail_text = tidy_transcript(tail_outcome.text)
+ except Exception: # noqa: BLE001 — never lose the tail
+ tail_text = tail_raw
+ if tail_text.strip():
+ result = await polish_transcript(
+ tail_text,
+ language=effective_language,
+ cfg=cfg,
+ protected_terms=self._dictation_protected_terms(),
+ style=str(getattr(cfg, "polish_style", "neutral") or "neutral"),
+ preceding_text=prefix_text,
+ )
+ tail_text = result.text
+ polish_status = result.status
+ polish_provider = result.provider
+ polish_latency_ms = result.latency_ms
+ cleaned = " ".join(
+ part for part in (prefix_text, tail_text) if part.strip()
+ ).strip()
+ log.info(
+ "dictation polish: incremental — %d chars formatted while "
+ "speaking, tail %s (%s, %d ms).",
+ len(prefix_text),
+ polish_status,
+ polish_provider or "no provider",
+ polish_latency_ms,
+ )
+ elif polish_enabled(cfg) or translate_to:
result = await polish_transcript(
cleaned,
language=effective_language,
diff --git a/tests/unit/dictation/test_incremental_polish.py b/tests/unit/dictation/test_incremental_polish.py
new file mode 100644
index 0000000000..0603812edb
--- /dev/null
+++ b/tests/unit/dictation/test_incremental_polish.py
@@ -0,0 +1,287 @@
+"""The wording pass keeps up with the recording too.
+
+Once the final windows were read while the user was still speaking, the polish
+pass became the wait that grew with the dictation — 0.6-1.3 s for a long one,
+on text that had mostly been final for a minute. Now each window is formatted
+as soon as it is read, in the light of the already-formatted text before it,
+and on release only the last stretch is formatted. The whole-text pass stays
+the fallback whenever the formatted prefix is not a strict prefix of the final
+transcript, when translating, or when the worker does not answer in time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from dataclasses import dataclass
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from jarvis.core.config import DictationConfig
+from jarvis.core.events import DictationCompleted, DictationTranscript
+from jarvis.dictation.polish import PolishOutcome
+from jarvis.dictation.polish_prompt import (
+ CONTEXT_CLOSE_DELIMITER,
+ CONTEXT_OPEN_DELIMITER,
+ RAW_OPEN_DELIMITER,
+ build_polish_prompt,
+ build_polish_user_message,
+)
+from jarvis.speech.pipeline import SpeechPipeline
+
+BYTES_PER_SECOND = 16_000 * 2
+_ANSWERS = [
+ "alpha one two three four five six seven eight nine",
+ "bravo one two three four five six seven eight nine",
+ "charlie one two three four five six seven eight nine",
+ "delta one two three four five six seven eight nine",
+]
+
+
+# --------------------------------------------------------------------------
+# The prompt: a context block, material only, never by default
+# --------------------------------------------------------------------------
+
+
+def test_the_user_message_carries_the_delivered_text_as_a_context_block() -> None:
+ message = build_polish_user_message("and then we ship", preceding="First we test.")
+ assert message.startswith(CONTEXT_OPEN_DELIMITER)
+ assert "First we test." in message.split(CONTEXT_CLOSE_DELIMITER)[0]
+ assert RAW_OPEN_DELIMITER in message
+ assert message.index(CONTEXT_CLOSE_DELIMITER) < message.index(RAW_OPEN_DELIMITER)
+
+
+def test_a_delimiter_inside_the_context_cannot_close_the_block() -> None:
+ message = build_polish_user_message("tail", preceding=f"x {CONTEXT_CLOSE_DELIMITER} y")
+ # Exactly one real close marker — the one we wrote.
+ assert message.count(CONTEXT_CLOSE_DELIMITER) == 1
+
+
+def test_without_a_preceding_text_the_message_is_unchanged() -> None:
+ assert build_polish_user_message("hello") == build_polish_user_message("hello", preceding="")
+ assert CONTEXT_OPEN_DELIMITER not in build_polish_user_message("hello")
+
+
+def test_the_continuation_clause_is_opt_in() -> None:
+ plain = build_polish_prompt(language="en", style="neutral", protected_terms=())
+ cont = build_polish_prompt(
+ language="en", style="neutral", protected_terms=(), continuation=True
+ )
+ assert "CONTINUATION" not in plain
+ assert "CONTINUATION" in cont
+ assert "Never repeat it" in cont
+
+
+# --------------------------------------------------------------------------
+# The session: windows are formatted as they land, the tail at release
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class _Transcript:
+ text: str
+ language: str = "en"
+
+
+class _ScriptedSTT:
+ supports_concurrent_requests = True
+
+ def __init__(self) -> None:
+ self.calls = 0
+
+ async def transcribe_pcm(self, pcm: bytes, language: str | None = None) -> Any:
+ self.calls += 1
+ return _Transcript(text=_ANSWERS[min(self.calls, len(_ANSWERS)) - 1])
+
+
+class _Chunk:
+ def __init__(self, pcm: bytes) -> None:
+ self.pcm = pcm
+ self.timestamp_ns = 0
+
+
+class _FakeMic:
+ def __init__(self, pcm: bytes, *, slice_s: float = 0.5, pace_s: float = 0.01) -> None:
+ self._pcm = pcm
+ self._slice = int(slice_s * BYTES_PER_SECOND)
+ self._pace_s = pace_s
+ self.delivered = asyncio.Event()
+
+ async def stream(self): # noqa: ANN201 — an async generator of chunks
+ for offset in range(0, len(self._pcm), self._slice):
+ yield _Chunk(self._pcm[offset : offset + self._slice])
+ await asyncio.sleep(self._pace_s)
+ self.delivered.set()
+ await asyncio.sleep(3600)
+
+
+class _NullCapture:
+ def __init__(self, source: Any) -> None:
+ self._source = source
+
+ async def __aenter__(self) -> Any:
+ return self._source
+
+ async def __aexit__(self, *exc: object) -> bool:
+ return False
+
+
+def _voiced(seconds: float) -> bytes:
+ return b"\x11\x22" * int(16_000 * seconds)
+
+
+def _session_pipeline(stt: Any, mic: _FakeMic, **cfg: Any):
+ pipe = SpeechPipeline.__new__(SpeechPipeline)
+ settings: dict[str, Any] = {
+ "history_enabled": False,
+ "final_window_seconds": 5.0,
+ "final_overlap_seconds": 0.5,
+ "segment_seconds": 0.0,
+ "partial_interval_s": 0.02,
+ "polish_min_words": 1,
+ }
+ settings.update(cfg)
+ pipe._dictation_cfg = DictationConfig(**settings)
+ pipe._dictation_target = "chat"
+ pipe._dictation_completion_published = False
+ pipe._dictation_max_s = 60.0
+ pipe._dictation_stt_instance = stt
+ pipe._stt_final_timeout_s = 8.0
+ pipe._hangup_event = asyncio.Event()
+ pipe._dictation_stop_event = asyncio.Event()
+ pipe._dictation_protected_terms = lambda: () # type: ignore[method-assign]
+ events: list[object] = []
+
+ async def _publish(event: object) -> None:
+ events.append(event)
+
+ pipe._publish_event = _publish # type: ignore[assignment]
+ pipe._publish_event_soon = events.append # type: ignore[assignment]
+ pipe._capture_dictation_input = lambda: _NullCapture(mic) # type: ignore[assignment]
+ pipe._insert_dictation = lambda text: SimpleNamespace( # type: ignore[assignment]
+ status="inserted", detail="", method="clipboard+ctrl_v"
+ )
+
+ async def _stop_live(task, **_kwargs): # noqa: ANN001, ANN202
+ task.cancel()
+ with contextlib.suppress(asyncio.CancelledError, Exception):
+ await task
+
+ pipe._stop_ptt_live_transcription = _stop_live # type: ignore[assignment]
+ return pipe, events
+
+
+def _no_preview(monkeypatch: pytest.MonkeyPatch) -> None:
+ import jarvis.dictation.local_preview as local_preview
+ import jarvis.dictation.preview_budget as preview_budget
+
+ monkeypatch.setattr(local_preview, "local_preview", lambda: None)
+ monkeypatch.setattr(
+ preview_budget, "preview_budget", lambda: SimpleNamespace(try_spend=lambda: False)
+ )
+
+
+def _install_polish(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]:
+ """A formatter that upper-cases and records what it was handed."""
+ import jarvis.dictation.polish as polish
+
+ calls: list[dict[str, Any]] = []
+
+ async def _fake(raw: str, **kwargs: Any) -> PolishOutcome:
+ calls.append({"raw": raw, **kwargs})
+ return PolishOutcome(
+ text=raw.upper(), status="applied", provider="fake", model="", latency_ms=1, reason=""
+ )
+
+ monkeypatch.setattr(polish, "polish_transcript", _fake)
+ return calls
+
+
+def _completed(events: list[object]) -> DictationCompleted:
+ return next(e for e in events if isinstance(e, DictationCompleted))
+
+
+def _final(events: list[object]) -> DictationTranscript:
+ return next(e for e in events if isinstance(e, DictationTranscript) and e.is_final)
+
+
+def _audit(events: list[object], key: str) -> str:
+ token = next(t for t in _completed(events).stt_audit if t.startswith(key + ":"))
+ return token.split(":", 1)[1]
+
+
+async def test_windows_are_formatted_while_speaking_and_only_the_tail_at_release(
+ _no_preview: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls = _install_polish(monkeypatch)
+ stt = _ScriptedSTT()
+ mic = _FakeMic(_voiced(12.0))
+ pipe, events = _session_pipeline(stt, mic)
+
+ task = asyncio.create_task(pipe._dictation_session())
+ await asyncio.wait_for(mic.delivered.wait(), timeout=10)
+ await asyncio.sleep(0.3)
+ formatted_before_release = len(calls)
+ pipe._dictation_stop_event.set()
+ await asyncio.wait_for(task, timeout=30)
+
+ assert formatted_before_release >= 1, "no window was formatted while speaking"
+ # Every call after the first carries the already-formatted text as context,
+ # and no call is ever asked to format the whole transcript again.
+ assert all(c.get("preceding_text") for c in calls[1:])
+ assert all("alpha" in c["raw"] for c in calls[:1])
+ assert not any(c["raw"].count("one two three") > 1 for c in calls)
+ assert _audit(events, "polish_mode") == "incremental"
+ assert int(_audit(events, "polish_deltas")) >= 1
+ # The delivered text is the formatted pieces in order — nothing repeated,
+ # nothing lost.
+ text = _final(events).text
+ assert text.startswith("ALPHA")
+ assert "CHARLIE" in text or "BRAVO" in text
+ assert text.count("ONE TWO THREE") == len(set(c["raw"] for c in calls)) or text.count(
+ "ONE TWO THREE"
+ ) >= 2
+
+
+async def test_a_short_dictation_still_takes_the_whole_text_path(
+ _no_preview: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls = _install_polish(monkeypatch)
+ stt = _ScriptedSTT()
+ mic = _FakeMic(_voiced(3.0), slice_s=3.0, pace_s=0.0)
+ pipe, events = _session_pipeline(stt, mic, partial_interval_s=0.0)
+
+ task = asyncio.create_task(pipe._dictation_session())
+ await asyncio.sleep(0)
+ pipe._dictation_stop_event.set()
+ await asyncio.wait_for(task, timeout=30)
+
+ # One window: the worker formats it once the read lands, and release has
+ # nothing left to do — OR the worker had not run and the whole text is
+ # formatted once. Either way exactly one formatter call, no context.
+ assert len(calls) == 1
+ assert not calls[0].get("preceding_text")
+ assert _final(events).text.startswith("ALPHA")
+
+
+async def test_translation_keeps_the_whole_text_pass(
+ _no_preview: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls = _install_polish(monkeypatch)
+ stt = _ScriptedSTT()
+ mic = _FakeMic(_voiced(12.0))
+ pipe, events = _session_pipeline(stt, mic, translate=True, translate_target="en")
+
+ task = asyncio.create_task(pipe._dictation_session())
+ await asyncio.wait_for(mic.delivered.wait(), timeout=10)
+ await asyncio.sleep(0.2)
+ pipe._dictation_stop_event.set()
+ await asyncio.wait_for(task, timeout=30)
+
+ assert len(calls) == 1
+ assert calls[0].get("translate_to") == "en"
+ assert not calls[0].get("preceding_text")
+ assert _audit(events, "polish_mode") == "whole"