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(voice): Jarvis reports back when a pane or agent finishes a job

rubenluetke10-beep4ff410c7c927
diff --git a/jarvis/agentic_ide/fanout.py b/jarvis/agentic_ide/fanout.py
index 521945494e..cd3e693187 100644
--- a/jarvis/agentic_ide/fanout.py
+++ b/jarvis/agentic_ide/fanout.py
@@ -443,7 +443,9 @@ async def _default_send(name: str, text: str, **receipt: Any) -> Any:
"""
from .session import get_registry
- return await get_registry().send_prompt(name, text, **receipt)
+ # A job Jarvis handed over on the user's behalf: its end is reported by
+ # voice (see `voice_readback`).
+ return await get_registry().send_prompt(name, text, readback=True, **receipt)
async def deliver(
diff --git a/jarvis/agentic_ide/notifications.py b/jarvis/agentic_ide/notifications.py
index 33fd035dea..5629cb3ec2 100644
--- a/jarvis/agentic_ide/notifications.py
+++ b/jarvis/agentic_ide/notifications.py
@@ -95,6 +95,7 @@ from typing import TYPE_CHECKING, Any, Literal, NamedTuple
from loguru import logger
+from . import voice_readback
from .activity import (
RESIZE_SHADOW_S,
STILL_S,
@@ -444,6 +445,13 @@ class ActivityWatcher:
self.center = center
self._panes: dict[tuple[str, str], _PaneWatch] = {}
self._resume_dirty = False
+ #: Jarvis-given jobs that just stopped: (kind, terminal), in order.
+ self._readbacks: list[tuple[Kind, Any]] = []
+
+ def take_readbacks(self) -> list[tuple[Kind, Any]]:
+ """Return and clear the stops that owe the user a spoken readback."""
+ taken, self._readbacks = self._readbacks, []
+ return taken
def take_resume_dirty(self) -> bool:
"""Return and clear whether activity changed the resume checkpoint."""
@@ -641,6 +649,14 @@ class ActivityWatcher:
watch.announced = True
watch.worked = False
+ if kind in ("completed", "needs_input") and getattr(term, "voice_readback", False):
+ # Jarvis handed this job over for the user, so the user hears how
+ # it ended — independent of the bell switch below. A question keeps
+ # the job open: the answer resumes the same job, and its end is
+ # still owed.
+ if kind == "completed":
+ term.voice_readback = False
+ self._readbacks.append((kind, term))
if not emit:
return None
return self.center.add(
@@ -975,6 +991,7 @@ def reset() -> None:
_CENTER.clear()
_WATCHER._panes.clear() # noqa: SLF001 - same module, one owner
_WATCHER._resume_dirty = False # noqa: SLF001 - same module, one owner
+ _WATCHER._readbacks.clear() # noqa: SLF001 - same module, one owner
_FEED.clear()
set_publisher(None)
reset_switch_cache()
@@ -1008,6 +1025,10 @@ async def _run(registry: Registry) -> None:
# with notifications disabled, restored panes must not be
# offered a blind Continue merely because history exists.
_WATCHER.poll(registry, emit=await _enabled_off_loop())
+ for kind, term in _WATCHER.take_readbacks():
+ # Its own task: composing the sentence waits on a model,
+ # and the sweep must keep its two-second rhythm.
+ voice_readback.schedule(kind, term, _publisher)
if _WATCHER.take_resume_dirty():
await registry.persist_resume_activity()
# After the stamps, so the event carries the word this sweep
diff --git a/jarvis/agentic_ide/session.py b/jarvis/agentic_ide/session.py
index 0f5c7f770c..288e196ec6 100644
--- a/jarvis/agentic_ide/session.py
+++ b/jarvis/agentic_ide/session.py
@@ -1134,6 +1134,14 @@ class Terminal:
# bursts — for work nobody had asked for. A pane nobody has given an
# instruction cannot have finished one, and this is how that is known.
last_submit_at: float | None = None
+ # Is the job this pane is working on one the user gave THROUGH Jarvis (a
+ # spoken order, the IDE prompt bar)? Then Jarvis owes the user a spoken
+ # "here is what it did" when the pane stops (see `.voice_readback`). Set by
+ # the prompt paths that ask for it, cleared by a job typed in by hand and by
+ # the readback itself. Ephemeral: a restored pane owes nobody anything.
+ voice_readback: bool = False
+ # The user's own words for that job — what the readback is about.
+ voice_readback_request: str = ""
# Did the last prompt actually leave the input line? None = none sent yet.
submitted: bool | None = None
# A hand-pressed Enter on an injected prompt is being checked against the
@@ -4577,6 +4585,11 @@ class Registry:
else:
term.last_submit_at = term.last_input_at
term.submit_generation = term.process_generation
+ if term.reading().activity != "asking":
+ # A new job typed by hand is the user's own, and nobody
+ # asked Jarvis to report on it. Answering the pane's
+ # question keeps the Jarvis job (and its readback) alive.
+ term.voice_readback = False
# And the pane's conversation may have just begun, which for most
# coding CLIs is the first moment its id exists on disk at all. A
# pane driven only by hand never goes through `send_prompt`, so
@@ -5958,8 +5971,14 @@ class Registry:
require_idle: bool = False,
expected_input: str = "",
allow_question: bool = False,
+ readback: bool = False,
) -> Terminal:
- """Serialize deliveries and pin the pane before the first await."""
+ """Serialize deliveries and pin the pane before the first await.
+
+ ``readback`` marks the job as one the user gave through Jarvis, so its
+ end is reported by voice (see :mod:`.voice_readback`). Callers that
+ supervise the pane themselves (a society agent) leave it off.
+ """
found = self.find_terminal(wanted, workspace_id)
if found is None:
raise self._unknown_terminal(wanted)
@@ -5992,6 +6011,7 @@ class Registry:
attachments=attachments,
expected_input=expected_input,
allow_question=allow_question,
+ readback=readback,
)
@staticmethod
@@ -6010,6 +6030,7 @@ class Registry:
attachments: Sequence[Any] = (),
expected_input: str = "",
allow_question: bool = False,
+ readback: bool = False,
) -> Terminal:
"""Type ``text`` into a terminal, press Enter, and CONFIRM it was sent.
@@ -6156,6 +6177,10 @@ class Registry:
term.manual_submit_token += 1
term.submitted = submitted
term.sent_multiline = multiline and submitted is True
+ # Whoever sent THIS job decides whether its end is reported by voice; a
+ # supervising agent's follow-up replaces a Jarvis job and its readback.
+ term.voice_readback = readback
+ term.voice_readback_request = (typed or payload).strip() if readback else ""
from .prompt_receipts import receipts_for
history_entry = prompt_history.PromptHistoryEntry(
diff --git a/jarvis/agentic_ide/voice_readback.py b/jarvis/agentic_ide/voice_readback.py
new file mode 100644
index 0000000000..ca88b53a5e
--- /dev/null
+++ b/jarvis/agentic_ide/voice_readback.py
@@ -0,0 +1,211 @@
+"""Tell the user, out loud, how a job they gave a pane through Jarvis ended.
+
+"Prompt terminal T1 to fix the login bug" used to end at "Sent — T1 has the
+brief and is working on it." The pane then worked for minutes, stopped, and
+nothing more was said: the only sign was the bell in the IDE header. A job
+the user gave Jarvis is a question Jarvis owes an answer to, so when such a
+pane stops, Jarvis now says what it did — or, when it stopped on a question,
+what it is asking.
+
+What counts as "given through Jarvis" is decided at the send site
+(``Registry.send_prompt(readback=True)``: the voice fan-out and the IDE prompt
+bar) and carried on the pane (``Terminal.voice_readback``). A job typed into
+the pane by hand, and one a supervising Jarvis agent handed over (it reports
+itself), are not announced.
+
+When it is spoken: the announcement uses a source the speech pipeline holds
+for an open call (``_HELD_FOR_CALL_SOURCES``) — inside a call it is spoken at
+the next free moment, outside one it waits for the next call. Jarvis never
+speaks into a room where nobody called it.
+
+What it says comes from the pane's own record: the coding CLI's final message
+when its transcript is readable, else the last lines of its screen. That text
+is phrased into one short sentence by the readback composer
+(:mod:`jarvis.voice.report_readback`); the canned fallback names the pane and
+quotes the report's first sentence.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+from loguru import logger
+
+#: Where these announcements come from. Listed in the speech pipeline's
+#: held-for-call sources, which is what keeps them out of an idle room.
+SOURCE_LAYER = "agentic_ide.readback"
+
+#: How many screen lines are read when no transcript is available.
+SCREEN_LINES = 24
+
+ReadbackKind = Literal["completed", "needs_input"]
+Publisher = Callable[[Any], Awaitable[None]]
+
+#: Deterministic fallbacks, spoken when the composer cannot phrase the report.
+_CANNED: dict[str, dict[str, str]] = {
+ "completed": {
+ "de": "{name} ist fertig: {report}", # i18n-allow: spoken readback
+ "en": "{name} is done: {report}",
+ "es": "{name} ha terminado: {report}",
+ },
+ "completed_bare": {
+ "de": "{name} ist mit deinem Auftrag fertig.", # i18n-allow: spoken readback
+ "en": "{name} has finished your task.",
+ "es": "{name} ha terminado tu encargo.",
+ },
+ "needs_input": {
+ "de": "{name} hat eine Frage: {report}", # i18n-allow: spoken readback
+ "en": "{name} has a question: {report}",
+ "es": "{name} tiene una pregunta: {report}",
+ },
+ "needs_input_bare": {
+ "de": "{name} wartet auf deine Antwort.", # i18n-allow: spoken readback
+ "en": "{name} is waiting for your answer.",
+ "es": "{name} espera tu respuesta.",
+ },
+}
+
+_INSTRUCTIONS: dict[str, str] = {
+ "completed": (
+ "A coding agent in the terminal named {name} has finished the task the "
+ "user gave it through you. Tell the user what it did or found, based "
+ "only on its report. Name the terminal. If the report says something "
+ "failed or is still open, say so."
+ ),
+ "needs_input": (
+ "A coding agent in the terminal named {name} stopped while working on "
+ "the user's task and is waiting for the user. Tell the user briefly what "
+ "it is asking or needs, based only on its screen. Name the terminal."
+ ),
+}
+
+#: Box drawing, block elements and the spinner/prompt glyphs a TUI paints.
+_TUI_NOISE_RE = re.compile(r"[─-▟⠀-⣿■-◿❯⏵⏸]+")
+
+_tasks: set[asyncio.Task[None]] = set()
+
+
+def schedule(kind: ReadbackKind, term: Any, publish: Publisher | None) -> None:
+ """Compose and publish the readback for ``term`` in a task of its own."""
+ if publish is None:
+ logger.debug("Agentic IDE readback for {}: no bus to speak on", getattr(term, "name", "?"))
+ return
+ try:
+ loop = asyncio.get_running_loop()
+ except RuntimeError:
+ return
+ task = loop.create_task(readback(kind, term, publish), name="agentic-ide-readback")
+ _tasks.add(task)
+ task.add_done_callback(_tasks.discard)
+
+
+async def readback(kind: ReadbackKind, term: Any, publish: Publisher) -> None:
+ """Tell the user how the pane's Jarvis job ended. Never raises."""
+ name = str(getattr(term, "name", "") or "the terminal")
+ try:
+ request = str(getattr(term, "voice_readback_request", "") or "")
+ report = ""
+ if kind == "completed":
+ report = await asyncio.to_thread(final_report, term)
+ screen = "" if report else screen_text(term)
+ language = await asyncio.to_thread(_language, request)
+ text = await _compose(kind, name, language, request, report, screen)
+ if not text.strip():
+ return
+ from jarvis.core.events import AnnouncementRequested
+
+ result = publish(
+ AnnouncementRequested(
+ source_layer=SOURCE_LAYER,
+ text=text,
+ language=language,
+ priority="normal",
+ # A readback kind: the answer to something the user asked for.
+ kind="completion",
+ detail=f"agentic_ide pane={name} outcome={kind}",
+ )
+ )
+ if inspect.isawaitable(result):
+ await result
+ logger.info("Agentic IDE readback for {} ({}): {!r}", name, kind, text[:120])
+ except Exception: # noqa: BLE001 - a lost readback must never touch the sweep
+ logger.opt(exception=True).warning("Agentic IDE readback for {} failed", name)
+
+
+async def _compose(
+ kind: ReadbackKind, name: str, language: str, request: str, report: str, screen: str
+) -> str:
+ from jarvis.voice.report_readback import compose_report, plain_excerpt
+
+ excerpt = plain_excerpt(report, max_words=35)
+
+ def canned() -> str:
+ key = kind if excerpt else f"{kind}_bare"
+ table = _CANNED[key]
+ return table.get(language, table["en"]).format(name=name, report=excerpt)
+
+ facts: dict[str, object] = {"terminal": name}
+ if request:
+ facts["task the user gave"] = request[:400]
+ if screen:
+ facts["what the terminal shows"] = screen
+ return await compose_report(
+ instruction=_INSTRUCTIONS[kind].format(name=name),
+ language=language,
+ canned=canned,
+ report=report,
+ facts=facts,
+ )
+
+
+def final_report(term: Any) -> str:
+ """The coding agent's last message, from its own transcript, or ``""``.
+
+ Only the answer to the newest user message counts: a transcript whose last
+ turn is the user's own has not answered yet.
+ """
+ from . import agent_transcript
+ from .session import account_home
+
+ handle = getattr(term, "resume", None)
+ agent = str(getattr(term, "agent", "") or "")
+ if handle is None or not agent_transcript.can_read(agent):
+ return ""
+ turns = agent_transcript.read(
+ agent, handle.id, home=account_home(agent, getattr(term, "account", None))
+ )
+ if not turns or turns[-1].role != "assistant":
+ return ""
+ return str(turns[-1].text or "").strip()
+
+
+def screen_text(term: Any) -> str:
+ """The last lines on the pane's screen, without the TUI's drawing."""
+ try:
+ lines = list(term.transcript.tail(SCREEN_LINES))
+ except Exception: # noqa: BLE001 - no screen is an empty fact, not an error
+ logger.opt(exception=True).debug("Agentic IDE readback: screen unreadable")
+ return ""
+ cleaned = (" ".join(_TUI_NOISE_RE.sub(" ", line).split()) for line in lines)
+ return "\n".join(line for line in cleaned if line)[-1500:]
+
+
+def _language(request: str) -> str:
+ """The language to speak in: the user's pin, else the words they used."""
+ from jarvis.core.turn_language import DEFAULT_LOCALE, resolve_output_language
+
+ pin = ""
+ try:
+ from jarvis.core.config import load_config
+
+ pin = str(getattr(load_config().brain, "reply_language", "") or "")
+ except Exception: # noqa: BLE001 - an unreadable config means "no pin"
+ logger.opt(exception=True).debug("Agentic IDE readback: reply-language pin unreadable")
+ return resolve_output_language(pin, "", request, default=DEFAULT_LOCALE)
+
+
+__all__ = ["SOURCE_LAYER", "final_report", "readback", "schedule", "screen_text"]
diff --git a/jarvis/society/runtime.py b/jarvis/society/runtime.py
index 52bcaa6e68..ceaf2a6008 100644
--- a/jarvis/society/runtime.py
+++ b/jarvis/society/runtime.py
@@ -90,6 +90,53 @@ _LEAD_MESSAGE: dict[str, str] = {
"es": "{name} informa: {text}",
}
+#: The situation the readback composer is told about, per case. The agent's own
+#: text is the only content it may use; the spoken line is Jarvis passing it on
+#: in one short sentence, not the raw text clipped at a character count.
+_LEAD_DONE_SITUATION = (
+ "The user's Jarvis agent named {name} finished a task the user gave it through "
+ "you. Tell the user what it did or found, based only on its report. Name the agent."
+)
+_LEAD_BLOCKED_SITUATION = (
+ "The user's Jarvis agent named {name} could not finish a task the user gave it "
+ "through you. Tell the user what stopped it, based only on its report. Name the agent."
+)
+_LEAD_MESSAGE_SITUATION: dict[MsgType, str] = {
+ MsgType.SAY: (
+ "The user's Jarvis agent named {name} sent a message. Pass it on to the "
+ "user in your own words. Name the agent."
+ ),
+ MsgType.QUERY: (
+ "The user's Jarvis agent named {name} is asking the user a question. Pass "
+ "the question on in your own words, keeping what exactly it asks. Name the agent."
+ ),
+ MsgType.ANSWER: (
+ "The user's Jarvis agent named {name} answered. Tell the user its answer in "
+ "your own words. Name the agent."
+ ),
+ MsgType.PROPOSE: (
+ "The user's Jarvis agent named {name} proposes something. Tell the user what "
+ "it proposes in your own words. Name the agent."
+ ),
+}
+
+
+async def _spoken_report(
+ *, instruction: str, language: str, line: str, name: str, report: str
+) -> str:
+ """The agent's report as one short spoken sentence; ``line`` is the fallback."""
+ from jarvis.voice.report_readback import compose_report, plain_excerpt
+
+ excerpt = plain_excerpt(report, max_words=40)
+ return await compose_report(
+ instruction=instruction,
+ language=language,
+ canned=lambda: line.format(name=name, text=excerpt),
+ report=report,
+ facts={"agent": name},
+ )
+
+
#: Board types that are somebody TALKING to the lead. RESULT stays out: chat
#: runs announce it via report_to_lead and mission runs via MissionAnnouncer —
#: announcing it here as well would speak every completion twice.
@@ -399,7 +446,6 @@ class SocietyRuntime:
return
lang = await self._lead_message_lang(env)
line = _LEAD_MESSAGE.get(lang, _LEAD_MESSAGE["en"])
- text = line.format(name=sender.name, text=summary[:400])
svc = self._get_chat()
post = getattr(svc, "post_notice", None)
if svc is not None and post is not None:
@@ -425,6 +471,17 @@ class SocietyRuntime:
)
if self._publish_event is None:
return
+ # Phrased after the chat notice: the notice carries the full text
+ # and must not wait on the composer.
+ text = await _spoken_report(
+ instruction=_LEAD_MESSAGE_SITUATION.get(
+ env.msg_type, _LEAD_MESSAGE_SITUATION[MsgType.SAY]
+ ).format(name=sender.name),
+ language=lang,
+ line=line,
+ name=sender.name,
+ report=summary,
+ )
try:
from jarvis.core.events import AnnouncementRequested
@@ -945,7 +1002,6 @@ class SocietyRuntime:
line = (_LEAD_DONE if status == "done" else _LEAD_BLOCKED).get(
lang, (_LEAD_DONE if status == "done" else _LEAD_BLOCKED)["en"]
)
- text = line.format(name=target.name, text=" ".join(summary.split())[:400])
svc = self._get_chat()
post = getattr(svc, "post_notice", None)
if svc is not None and post is not None:
@@ -968,6 +1024,17 @@ class SocietyRuntime:
log.warning("society: result notice for the lead chat failed", exc_info=True)
if self._publish_event is None:
return
+ # Phrased after the chat notice: the notice carries the full text
+ # and must not wait on the composer.
+ text = await _spoken_report(
+ instruction=(
+ _LEAD_DONE_SITUATION if status == "done" else _LEAD_BLOCKED_SITUATION
+ ).format(name=target.name),
+ language=lang if lang in _LEAD_DONE else "en",
+ line=line,
+ name=target.name,
+ report=summary,
+ )
try:
from jarvis.core.events import AnnouncementRequested
diff --git a/jarvis/speech/pipeline.py b/jarvis/speech/pipeline.py
index 19cf2796ce..fa67731cff 100644
--- a/jarvis/speech/pipeline.py
+++ b/jarvis/speech/pipeline.py
@@ -396,6 +396,9 @@ _READBACK_KINDS: frozenset[str] = frozenset(
_HELD_FOR_CALL_SOURCES: frozenset[str] = frozenset(
{
"society.lead",
+ # A pane finishing a job Jarvis handed it (jarvis/agentic_ide/
+ # voice_readback.py): spoken inside the call, else at the next one.
+ "agentic_ide.readback",
"tasks.runner",
"workflows.runner",
"workflows.scheduler",
diff --git a/jarvis/ui/web/agentic_ide_routes.py b/jarvis/ui/web/agentic_ide_routes.py
index 0e4fee8ff8..fefaed9152 100644
--- a/jarvis/ui/web/agentic_ide_routes.py
+++ b/jarvis/ui/web/agentic_ide_routes.py
@@ -4251,6 +4251,8 @@ async def terminal_prompt(
workspace_id=found[0].id,
typed=req.prompt,
attachments=attachments,
+ # Asked of Jarvis, so Jarvis reports how it ended.
+ readback=True,
)
except SessionError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from exc
diff --git a/jarvis/voice/report_readback.py b/jarvis/voice/report_readback.py
new file mode 100644
index 0000000000..cd1da2c0f4
--- /dev/null
+++ b/jarvis/voice/report_readback.py
@@ -0,0 +1,146 @@
+"""Turn another agent's report into a short spoken sentence for the user.
+
+Two things report back to the user through Jarvis: a coding agent in an
+Agentic-IDE pane that finished the job Jarvis handed it, and a Jarvis agent
+answering the lead. Both used to be read out raw — a markdown report clipped
+at a character count, often mid-word, in whatever language the agent wrote.
+What the user wants to hear is what Jarvis would say about it: one short,
+natural sentence, in the conversation's language.
+
+So the report goes through the same bounded flash composer every other
+readback uses (:mod:`jarvis.voice.contextual_readback`), with the report as
+the only facts it may use. When that composer is unavailable or its answer is
+rejected, the canned line is spoken instead — built from the report's leading
+sentences, cut at a sentence or word boundary and never inside a word.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from collections.abc import Callable
+from typing import Any
+
+from loguru import logger
+
+__all__ = ["compose_report", "plain_excerpt", "set_composer"]
+
+#: Off the turn-critical path: a background result may take a little longer to
+#: phrase than an acknowledgement, but it must not hang on a dead provider.
+LATENCY_BUDGET_MS = 4000
+
+#: How much of a report the composer is shown. The end of a long report is
+#: where an agent states its result, so a longer one keeps both ends.
+MAX_REPORT_CHARS = 1800
+
+_CODE_FENCE_RE = re.compile(r"```.*?```", re.DOTALL)
+_INLINE_CODE_RE = re.compile(r"`([^`\n]*)`")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]*\)")
+_MARKUP_RE = re.compile(r"(^|\s)(?:#{1,6}|[-*+>]|\d+[.)])\s+", re.MULTILINE)
+_EMPHASIS_RE = re.compile(r"[*_~]{1,3}")
+_SENTENCE_SPLIT_RE = re.compile(r"(?<=[.!?])\s+")
+
+_composer: Any = None
+_composer_lock = asyncio.Lock()
+
+
+def _plain(text: str) -> str:
+ """``text`` without markdown, code blocks and line structure."""
+ value = _CODE_FENCE_RE.sub(" ", str(text or ""))
+ value = _LINK_RE.sub(r"\1", value)
+ value = _INLINE_CODE_RE.sub(r"\1", value)
+ value = _MARKUP_RE.sub(r"\1", value)
+ value = _EMPHASIS_RE.sub("", value)
+ return " ".join(value.split())
+
+
+def plain_excerpt(text: str, *, max_words: int = 40) -> str:
+ """The leading sentences of ``text`` as plain speech, within ``max_words``.
+
+ Cut at a sentence boundary when one fits, else at a word boundary — never
+ inside a word, which is how the old 400-character cut ended readbacks.
+ """
+ plain = _plain(text)
+ if not plain:
+ return ""
+ kept: list[str] = []
+ total = 0
+ for sentence in _SENTENCE_SPLIT_RE.split(plain):
+ words = sentence.split()
+ if not words:
+ continue
+ if total + len(words) > max_words:
+ if not kept:
+ kept.append(" ".join(words[:max_words]).rstrip(",;:") + " …")
+ break
+ kept.append(sentence.strip())
+ total += len(words)
+ return " ".join(kept)
+
+
+def _report_facts(report: str) -> str:
+ plain = _plain(report)
+ if len(plain) <= MAX_REPORT_CHARS:
+ return plain
+ half = MAX_REPORT_CHARS // 2
+ return f"{plain[:half]} … {plain[-half:]}"
+
+
+async def _get_composer() -> Any:
+ """The readback composer, built once and off the event loop.
+
+ Building it reads ``jarvis.toml`` and constructs a provider client, so it
+ runs in a thread; it never raises and falls back to canned-only mode.
+ """
+ global _composer
+ if _composer is not None:
+ return _composer
+ async with _composer_lock:
+ if _composer is None:
+ from jarvis.brain.factory import build_readback_composer
+
+ _composer = await asyncio.to_thread(build_readback_composer)
+ return _composer
+
+
+async def compose_report(
+ *,
+ instruction: str,
+ language: str,
+ canned: Callable[[], str],
+ report: str,
+ facts: dict[str, object] | None = None,
+) -> str:
+ """One short spoken sentence about ``report``, or the canned line.
+
+ ``instruction`` describes the situation in English; ``report`` is the
+ agent's own words, the only content the sentence may draw on. Never raises.
+ """
+ from jarvis.voice.contextual_readback import render_readback
+
+ all_facts: dict[str, object] = dict(facts or {})
+ if report.strip():
+ all_facts["report"] = _report_facts(report)
+ try:
+ composer = await _get_composer()
+ except Exception: # noqa: BLE001 - a missing composer only costs the phrasing
+ logger.opt(exception=True).warning("Report readback: composer unavailable")
+ composer = None
+ return await render_readback(
+ composer,
+ instruction=instruction,
+ language=language,
+ canned=canned,
+ facts=all_facts,
+ # The report is usually in another language than the speech (briefs are
+ # English), so the content-overlap guard would reject every good
+ # rephrasing; the digit and vocabulary guards still apply.
+ honesty_bound=False,
+ latency_budget_ms=LATENCY_BUDGET_MS,
+ )
+
+
+def set_composer(composer: Any) -> None:
+ """Use ``composer`` from now on; ``None`` builds it again on next use."""
+ global _composer
+ _composer = composer
diff --git a/tests/conftest.py b/tests/conftest.py
index 99427218f1..03197623b3 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -183,6 +183,23 @@ def _pricing_feed_in_tmp(tmp_path_factory, monkeypatch): # noqa: ANN001
yield
[email protected](autouse=True)
+def _report_readback_canned_only():
+ """Keep spoken report readbacks off the real flash provider.
+
+ ``jarvis.voice.report_readback`` builds its composer from the host's own
+ ``jarvis.toml`` on first use, which in a test would be a real model call.
+ A bare composer speaks the deterministic canned line; suites that test the
+ phrasing hand in their own composer on top of this.
+ """
+ from jarvis.voice import report_readback
+ from jarvis.voice.contextual_readback import ReadbackComposer
+
+ report_readback.set_composer(ReadbackComposer())
+ yield
+ report_readback.set_composer(None)
+
+
@pytest.fixture(autouse=True)
def _reset_bus():
"""Reset the global default bus before and after each test."""
diff --git a/tests/unit/agentic_ide/test_voice_readback.py b/tests/unit/agentic_ide/test_voice_readback.py
new file mode 100644
index 0000000000..d1e48a24b6
--- /dev/null
+++ b/tests/unit/agentic_ide/test_voice_readback.py
@@ -0,0 +1,207 @@
+"""A job the user gave a pane through Jarvis ends with Jarvis saying how it went.
+
+The bell (``test_pane_notifications``) says THAT a pane stopped. This is the
+spoken half: only for jobs handed over through Jarvis, once per job, phrased
+from the pane's own report, and routed through the speech pipeline's
+held-for-call gate so it never speaks into an idle room.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from jarvis.agentic_ide import notifications, voice_readback
+from jarvis.agentic_ide import session as session_mod
+from jarvis.agentic_ide.activity import STILL_S
+from jarvis.agentic_ide.session import Registry
+from jarvis.core.events import AnnouncementRequested
+from jarvis.speech.pipeline import SpeechPipeline
+from jarvis.voice.report_readback import plain_excerpt
+from tests.fakes.fake_pty_manager import FakePtyManager
+
+QUESTION_SCREEN = "\r\nDo you want to make this edit to config.py?\r\n❯ 1. Yes\r\n"
+
+
[email protected](autouse=True)
+def _clean_store() -> Any:
+ notifications.reset()
+ yield
+ notifications.reset()
+
+
+def registry(monkeypatch: pytest.MonkeyPatch) -> Registry:
+ monkeypatch.setattr(session_mod, "agent_argv", lambda name: (f"/usr/bin/{name}",))
+ return Registry(pty_manager=FakePtyManager())
+
+
+def no_pin(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Keep the host's real reply-language pin out of the language decision."""
+ from jarvis.core import config
+
+ def _unreadable() -> Any:
+ raise OSError("no config in this test")
+
+ monkeypatch.setattr(config, "load_config", _unreadable)
+
+
+async def _noop(_data: Any) -> None:
+ return None
+
+
+async def _pane(registry: Registry, folder: Path) -> tuple[Any, Any]:
+ session = await registry.start(str(folder), [{"agent": "claude", "name": "Alex"}])
+ term = await registry.attach("Alex", 100, 30, _noop, _noop)
+ return session, term
+
+
+def _work_then_rest(
+ watcher: Any, registry: Registry, term: Any, screen: str, *, emit: bool
+) -> None:
+ """Busy for three sweeps, then still until the stop is reported."""
+ term.last_submit_at = 99.9
+ term.submit_generation = term.process_generation
+ at = 100.0
+ for step in range(3):
+ at = 100.0 + step * notifications.SWEEP_INTERVAL_S
+ term.transcript.clear()
+ term.transcript.feed(f"\r\n· working, frame {step}\r\n")
+ watcher.poll(registry, now=at, emit=emit)
+ rest = at + 1
+ term.transcript.clear()
+ term.transcript.feed(screen)
+ term.last_output_at = rest
+ term.last_input_at = None
+ watcher.poll(registry, now=rest, emit=emit)
+ watcher.poll(registry, now=rest + STILL_S + 2, emit=emit)
+ watcher.poll(registry, now=rest + STILL_S + notifications.SETTLE_S + 4, emit=emit)
+
+
+async def test_a_jarvis_job_that_finishes_owes_one_readback(
+ registry: Registry, tmp_path: Path
+) -> None:
+ watcher = notifications.watcher()
+ _session, term = await _pane(registry, tmp_path)
+ term.voice_readback = True
+
+ # The bell switch is off: the spoken readback does not depend on it.
+ _work_then_rest(watcher, registry, term, "\r\n❯ \r\n", emit=False)
+
+ assert watcher.take_readbacks() == [("completed", term)]
+ assert term.voice_readback is False, "one readback per job"
+ assert watcher.take_readbacks() == []
+
+
+async def test_a_job_nobody_gave_through_jarvis_is_not_announced(
+ registry: Registry, tmp_path: Path
+) -> None:
+ watcher = notifications.watcher()
+ _session, term = await _pane(registry, tmp_path)
+
+ _work_then_rest(watcher, registry, term, "\r\n❯ \r\n", emit=True)
+
+ assert watcher.take_readbacks() == []
+
+
+async def test_a_question_is_announced_and_keeps_the_job_open(
+ registry: Registry, tmp_path: Path
+) -> None:
+ watcher = notifications.watcher()
+ _session, term = await _pane(registry, tmp_path)
+ term.voice_readback = True
+
+ _work_then_rest(watcher, registry, term, QUESTION_SCREEN, emit=True)
+
+ assert watcher.take_readbacks() == [("needs_input", term)]
+ assert term.voice_readback is True, "its end is still owed"
+
+
+async def test_a_job_typed_by_hand_cancels_the_readback(
+ registry: Registry, tmp_path: Path
+) -> None:
+ session, term = await _pane(registry, tmp_path)
+ term.voice_readback = True
+
+ registry.write(term.key, "do something else\r", workspace_id=session.id)
+
+ assert term.voice_readback is False
+
+
+async def test_the_readback_is_phrased_from_the_agents_report(
+ monkeypatch: pytest.MonkeyPatch, no_pin: None
+) -> None:
+ published: list[Any] = []
+
+ async def publish(event: Any) -> None:
+ published.append(event)
+
+ term = _FakeTerm(request="Behebe bitte den Login-Fehler") # i18n-allow: user's words
+ monkeypatch.setattr(
+ voice_readback,
+ "final_report",
+ lambda _term: "## Summary\n\nFixed the **login** bug in `auth.py`. All 12 tests pass.",
+ )
+
+ await voice_readback.readback("completed", term, publish)
+
+ assert len(published) == 1
+ event = published[0]
+ assert isinstance(event, AnnouncementRequested)
+ assert event.source_layer == voice_readback.SOURCE_LAYER
+ assert event.kind == "completion"
+ assert event.language == "de"
+ # The test composer is canned-only (root conftest): pane name + the
+ # report's first sentences, markdown gone.
+ spoken = (
+ "Alex ist fertig: " # i18n-allow: spoken readback
+ "Summary Fixed the login bug in auth.py. All 12 tests pass."
+ )
+ assert event.text == spoken
+
+
+async def test_without_a_report_the_readback_still_names_the_pane(
+ monkeypatch: pytest.MonkeyPatch, no_pin: None
+) -> None:
+ published: list[Any] = []
+
+ async def publish(event: Any) -> None:
+ published.append(event)
+
+ monkeypatch.setattr(voice_readback, "final_report", lambda _term: "")
+
+ await voice_readback.readback("completed", _FakeTerm(request="Run the tests"), publish)
+
+ assert [e.text for e in published] == ["Alex has finished your task."]
+
+
+def test_the_pipeline_holds_pane_readbacks_for_an_open_call() -> None:
+ event = AnnouncementRequested(
+ source_layer=voice_readback.SOURCE_LAYER, kind="completion", text="Alex is done."
+ )
+ assert SpeechPipeline._is_agent_reply(event)
+
+
+def test_an_excerpt_is_never_cut_inside_a_word() -> None:
+ long = " ".join(f"word{i}" for i in range(80))
+ excerpt = plain_excerpt(long, max_words=10)
+ assert excerpt.split()[:10] == [f"word{i}" for i in range(10)]
+ assert excerpt.endswith("…")
+ assert plain_excerpt("First one. Second one. Third.", max_words=4) == "First one. Second one."
+
+
+class _FakeTerm:
+ name = "Alex"
+
+ def __init__(self, *, request: str) -> None:
+ self.voice_readback_request = request
+ self.transcript = _Screen()
+
+
+class _Screen:
+ @staticmethod
+ def tail(_n: int) -> list[str]:
+ return []