agentwire-dev 1.59.0__tar.gz → 1.60.0__tar.gz

{agentwire_dev-1.59.0 → agentwire_dev-1.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.59.0
+Version: 1.60.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev

{agentwire_dev-1.59.0 → agentwire_dev-1.60.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.59.0"
+__version__ = "1.60.0"

{agentwire_dev-1.59.0 → agentwire_dev-1.60.0}/agentwire/doctor_cli.py

@@ -404,6 +404,77 @@ def _render_task_migration_section() -> int:
     return len(unmigrated)
 
 
+def _find_dead_managed_shims() -> list[dict]:
+    """Managed voice shims whose tmux session is alive but ``/health`` is dead.
+
+    The #734 failure mode: a wedged Kokoro (:8102) or Moonshine STT (:8101) shim
+    inside a live ``agentwire-kokoro``/``agentwire-stt`` session — say/transcribe
+    then silently fall back to browser voice/recognition with no error, and the
+    old session-existence-only ``ensure`` never relaunches it. Only the default
+    tier runs a managed shim, so we check that tier only, and reuse the same
+    ``_shim_session_state`` liveness predicate as ``start`` (SSOT).
+    """
+    from .config import load_config as load_config_typed
+    from .core import (
+        get_kokoro_session_name,
+        get_stt_session_name,
+        tmux_session_exists,
+    )
+    from .tts_cli import _shim_session_state
+
+    cfg = load_config_typed()
+    checks: list[tuple[str, str, int, str, str]] = []
+
+    if getattr(getattr(cfg, "tts", None), "backend", "default") == "default":
+        checks.append((
+            "Kokoro TTS", get_kokoro_session_name(), 8102,
+            "agentwire kokoro start", "say falls back to browser voice",
+        ))
+
+    if getattr(getattr(cfg, "stt", None), "backend", "default") == "default":
+        # Only the Moonshine path runs a shim; without it the default tier
+        # transcribes in the browser and there is nothing to probe.
+        from .stt import moonshine_importable
+
+        if moonshine_importable():
+            checks.append((
+                "Moonshine STT", get_stt_session_name(), 8101,
+                "agentwire stt start",
+                "transcription falls back to browser recognition",
+            ))
+
+    dead: list[dict] = []
+    for label, session, port, fix, impact in checks:
+        if not tmux_session_exists(session):
+            continue
+        live, status = _shim_session_state(session, port)
+        if not live:
+            dead.append({
+                "label": label, "session": session, "port": port,
+                "status": status, "fix": fix, "impact": impact,
+            })
+    return dead
+
+
+def _render_shim_liveness_section() -> int:
+    """Doctor section: managed shim session alive but ``/health`` dead (#734)."""
+    dead = _find_dead_managed_shims()
+    if not dead:
+        print("  [ok] No dead-but-present voice shims")
+        return 0
+    for d in dead:
+        print(
+            f"  [!!] {d['label']} shim session '{d['session']}' is alive but "
+            f":{d['port']}/health is not serving (state: "
+            f"{d['status'] or 'no response'}) — {d['impact']}."
+        )
+    print(
+        f"     Self-heal: re-run `{dead[0]['fix']}` — it is now health-aware and "
+        "reaps a dead session before relaunching."
+    )
+    return len(dead)
+
+
 def cmd_doctor(args) -> int:
     """Auto-diagnose and fix common issues."""
     from .hooks_cli import _managed_file_state, _managed_hook_files, get_hooks_source
@@ -926,6 +997,17 @@ def cmd_doctor(args) -> int:
     except Exception as e:
         print(f"  [..] Could not check project task migration: {e}")
 
+    # 13. Managed voice shims (Kokoro :8102, Moonshine STT :8101) whose tmux
+    # session is alive but whose /health is dead (#734). The old
+    # session-existence-only idempotency masked a wedged engine forever, so
+    # say/transcribe silently fell back to browser voice. Surfaced distinctly
+    # here with the now-health-aware self-heal command.
+    print("\nChecking managed voice shim liveness (#734)...")
+    try:
+        issues_found += _render_shim_liveness_section()
+    except Exception as e:
+        print(f"  [..] Could not check managed voice shim liveness: {e}")
+
     # Summary
     print()
     print("-" * 60)

{agentwire_dev-1.59.0 → agentwire_dev-1.60.0}/agentwire/server.py

@@ -387,10 +387,11 @@ class AgentWireServer(
         """Ensure the default-tier Moonshine shim subprocess is running.
 
         Delegates to the CLI (single source of truth): ``agentwire stt start``
-        is idempotent — ``cmd_stt_start`` early-returns if the ``agentwire-stt``
-        tmux session already exists, so a user-started shim is reused with no
-        port clash. The ~19s ONNX warm-up happens in that child process, never
-        on the portal's event loop. Mirrors ``autostart_custom_services``."""
+        is idempotent and health-aware — ``cmd_stt_start`` reuses the
+        ``agentwire-stt`` session only when it is actually serving, and reaps +
+        relaunches a dead-but-present one (#734), so a wedged shim self-heals on
+        the next ensure. The ~19s ONNX warm-up happens in that child process,
+        never on the portal's event loop. Mirrors ``autostart_custom_services``."""
         await asyncio.sleep(5)  # let the portal finish binding first
         try:
             success, result = await self.run_agentwire_cmd(["stt", "start"], json_output=False)
@@ -438,10 +439,11 @@ class AgentWireServer(
         """Ensure the default-tier Kokoro TTS shim subprocess is running.
 
         Delegates to the CLI (single source of truth): ``agentwire kokoro start``
-        is idempotent — ``cmd_kokoro_start`` early-returns if the
-        ``agentwire-kokoro`` tmux session already exists, so a user-started shim
-        is reused with no port clash. The ~200 MB download + ONNX warm-up
-        happens in that child process, never on the portal's event loop. Mirrors
+        is idempotent and health-aware — ``cmd_kokoro_start`` reuses the
+        ``agentwire-kokoro`` session only when it is actually serving, and reaps
+        + relaunches a dead-but-present one (#734), so a wedged shim self-heals
+        on the next ensure. The ~200 MB download + ONNX warm-up happens in that
+        child process, never on the portal's event loop. Mirrors
         ``ensure_managed_stt``."""
         await asyncio.sleep(5)  # let the portal finish binding first
         try:

{agentwire_dev-1.59.0 → agentwire_dev-1.60.0}/agentwire/tts_cli.py

@@ -459,19 +459,102 @@ def _resolve_shim_python() -> tuple[str | None, str | None, str | None]:
     return sys.executable, None, None
 
 
+# === Managed shim liveness (health-aware idempotency, #734) ===
+#
+# A managed voice shim (Kokoro TTS :8102, Moonshine STT :8101) runs uvicorn in
+# a tmux session and warms its model in the background. The old start path was
+# idempotent on *session existence* alone, so a dead/wedged process inside a
+# live session was treated as healthy forever — say/transcribe then silently
+# fell back to browser voice. These helpers make start/ensure health-aware:
+# reuse a session only when it is actually serving (or too young to have bound
+# its port yet); otherwise reap it and relaunch.
+
+
+def _probe_shim_health(port: int, timeout: float = 2.0) -> tuple[bool, str | None]:
+    """Probe a managed shim's ``/health`` on localhost.
+
+    Returns ``(responded, status)``: ``responded`` is True when the HTTP server
+    answered at all (even mid-warmup); ``status`` is the reported state string
+    (``ok``/``loading``/``downloading``/``absent``/``failed``/…) or None when
+    nothing answered (process dead, wedged, or the port not yet bound)."""
+    try:
+        req = urllib.request.Request(f"http://localhost:{port}/health")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode())
+            return True, data.get("status")
+    except Exception:
+        return False, None
+
+
+def _tmux_session_age(session_name: str) -> float | None:
+    """Seconds since the tmux session was created, or None if unknowable."""
+    import time
+
+    result = subprocess.run(
+        ["tmux", "display-message", "-p", "-t", session_name, "#{session_created}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    try:
+        return time.time() - int(result.stdout.strip())
+    except (ValueError, TypeError):
+        return None
+
+
+def _shim_session_state(
+    session_name: str, port: int, *, warmup_grace: float = 25.0
+) -> tuple[bool, str | None]:
+    """``(live, status)`` for an EXISTING managed-shim tmux session.
+
+    The single liveness predicate shared by ``start`` (reuse-vs-reap) and
+    ``doctor`` (flag-a-dead-shim). A session is *live* when its ``/health``
+    answers a non-``failed`` status, OR it is younger than ``warmup_grace`` (the
+    port may not be bound yet). A process that never answers past the grace, or
+    reports a terminal ``failed``, is NOT live. ``status`` is the ``/health``
+    state, ``"starting"`` for a still-booting young session, or None for a dead
+    one — carried through for human-readable diagnostics."""
+    responded, status = _probe_shim_health(port)
+    if responded:
+        return (status != "failed", status)
+    age = _tmux_session_age(session_name)
+    if age is not None and age < warmup_grace:
+        return (True, "starting")
+    return (False, status)
+
+
+def _reap_shim_session(session_name: str) -> None:
+    """Kill a dead shim tmux session so a fresh one can bind the port."""
+    import time
+
+    subprocess.run(["tmux", "kill-session", "-t", session_name], capture_output=True)
+    time.sleep(0.5)
+
+
 # === STT Commands ===
 
 def cmd_stt_start(args) -> int:
     """Start the STT server in tmux."""
     session_name = get_stt_session_name()
+    port = args.port or 8101
+    host = args.host or "0.0.0.0"
 
     if tmux_session_exists(session_name):
-        print(f"STT server already running in tmux session '{session_name}'")
-        print(f"  Attach: tmux attach -t {session_name}")
-        return 0
+        live, status = _shim_session_state(session_name, port)
+        if live:
+            print(f"STT server already running in tmux session '{session_name}'")
+            print(f"  Attach: tmux attach -t {session_name}")
+            return 0
+        # Session exists but :{port}/health isn't serving (dead/wedged) —
+        # self-heal by reaping and relaunching instead of masking a dead
+        # engine behind mere session existence (#734).
+        print(
+            f"STT server session '{session_name}' is present but not serving "
+            f"(state: {status or 'no response'}) — relaunching."
+        )
+        _reap_shim_session(session_name)
 
-    port = args.port or 8101
-    host = args.host or "0.0.0.0"
     config = load_config()
     stt_config = config.get("stt", {})
     model = args.model or stt_config.get("model", "base")
@@ -576,21 +659,31 @@ def cmd_stt_status(args) -> int:
 # === Kokoro (default-tier TTS shim) Commands ===
 
 def cmd_kokoro_start(args) -> int:
-    """Start the default-tier Kokoro TTS shim in tmux (idempotent).
+    """Start the default-tier Kokoro TTS shim in tmux (idempotent, health-aware).
 
     Mirrors ``agentwire stt start``: the portal's ``ensure_managed_tts`` calls
-    this on startup, and the early-return on an existing session means a
-    user-started shim is reused with no port clash."""
+    this on startup. An existing session is reused only when it is actually
+    serving (``/health`` ok/warming); a dead-but-present session is reaped and
+    relaunched so a wedged shim self-heals instead of masking forever (#734)."""
     session_name = get_kokoro_session_name()
-
-    if tmux_session_exists(session_name):
-        print(f"Kokoro TTS shim already running in tmux session '{session_name}'")
-        print(f"  Attach: tmux attach -t {session_name}")
-        return 0
-
     port = args.port or 8102
     host = args.host or "0.0.0.0"
 
+    if tmux_session_exists(session_name):
+        live, status = _shim_session_state(session_name, port)
+        if live:
+            print(f"Kokoro TTS shim already running in tmux session '{session_name}'")
+            print(f"  Attach: tmux attach -t {session_name}")
+            return 0
+        # Session exists but :{port}/health isn't serving (dead/wedged) —
+        # self-heal by reaping and relaunching instead of masking a dead
+        # engine behind mere session existence (#734).
+        print(
+            f"Kokoro TTS shim session '{session_name}' is present but not serving "
+            f"(state: {status or 'no response'}) — relaunching."
+        )
+        _reap_shim_session(session_name)
+
     # Resolve an interpreter that can run the shim: dev-checkout venv when one
     # exists, otherwise the installed package's interpreter.
     python_path, cwd, error = _resolve_shim_python()

agentwire_dev-1.60.0/tests/unit/test_shim_selfheal.py

@@ -0,0 +1,202 @@
+"""Health-aware managed-shim self-heal (#734).
+
+A dead/wedged Kokoro (:8102) or Moonshine STT (:8101) shim inside a live tmux
+session used to be treated as healthy forever (idempotency keyed on session
+existence alone), so say/transcribe silently fell back to browser voice. These
+tests pin the liveness predicate, the reuse-vs-reap decision in ``start``, and
+the doctor surfacing — without touching any real tmux session or port.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from agentwire import tts_cli
+
+# === _shim_session_state: the shared liveness predicate ====================
+
+
+def _patch_probe(monkeypatch, *, responded, status):
+    monkeypatch.setattr(
+        tts_cli, "_probe_shim_health", lambda port, timeout=2.0: (responded, status)
+    )
+
+
+def test_state_ok_is_live(monkeypatch):
+    _patch_probe(monkeypatch, responded=True, status="ok")
+    assert tts_cli._shim_session_state("s", 8102) == (True, "ok")
+
+
+@pytest.mark.parametrize("warming", ["loading", "downloading", "absent"])
+def test_state_warming_is_live(monkeypatch, warming):
+    # A shim mid-warmup still answers /health — reuse it, never reap it.
+    _patch_probe(monkeypatch, responded=True, status=warming)
+    live, status = tts_cli._shim_session_state("s", 8102)
+    assert live is True
+    assert status == warming
+
+
+def test_state_failed_is_not_live(monkeypatch):
+    # Terminal engine failure: the process answers but will never be ready.
+    _patch_probe(monkeypatch, responded=True, status="failed")
+    assert tts_cli._shim_session_state("s", 8102) == (False, "failed")
+
+
+def test_state_no_response_young_is_live(monkeypatch):
+    # Just launched: the port may not be bound yet — give it the grace window.
+    _patch_probe(monkeypatch, responded=False, status=None)
+    monkeypatch.setattr(tts_cli, "_tmux_session_age", lambda s: 3.0)
+    assert tts_cli._shim_session_state("s", 8102, warmup_grace=25.0) == (True, "starting")
+
+
+def test_state_no_response_old_is_dead(monkeypatch):
+    # Session has existed for hours but nothing answers — dead/wedged.
+    _patch_probe(monkeypatch, responded=False, status=None)
+    monkeypatch.setattr(tts_cli, "_tmux_session_age", lambda s: 9000.0)
+    assert tts_cli._shim_session_state("s", 8102, warmup_grace=25.0) == (False, None)
+
+
+def test_state_no_response_unknown_age_is_dead(monkeypatch):
+    # Age unknowable (session vanished mid-probe) → not live.
+    _patch_probe(monkeypatch, responded=False, status=None)
+    monkeypatch.setattr(tts_cli, "_tmux_session_age", lambda s: None)
+    assert tts_cli._shim_session_state("s", 8102) == (False, None)
+
+
+# === start commands: reuse when live, reap+relaunch when dead ==============
+
+
+class _StartHarness:
+    """Records whether start reaped the session / launched a fresh one."""
+
+    def __init__(self, monkeypatch, module=tts_cli):
+        self.reaped = False
+        self.launched = False
+        monkeypatch.setattr(module, "tmux_session_exists", lambda s: True)
+        monkeypatch.setattr(module, "_reap_shim_session", self._reap)
+        monkeypatch.setattr(
+            module, "_resolve_shim_python", lambda: ("/usr/bin/python3", None, None)
+        )
+        monkeypatch.setattr(module, "load_config", lambda: {"stt": {}})
+        monkeypatch.setattr(module.subprocess, "run", self._run)
+
+    def _reap(self, session):
+        self.reaped = True
+
+    def _run(self, cmd, *a, **k):
+        # `tmux new-session` is the launch of a fresh shim.
+        if isinstance(cmd, list) and "new-session" in cmd:
+            self.launched = True
+        return SimpleNamespace(returncode=0, stdout="", stderr="")
+
+
+def _kokoro_args():
+    return SimpleNamespace(port=None, host=None)
+
+
+def _stt_args():
+    return SimpleNamespace(port=None, host=None, model=None, backend=None)
+
+
+def test_kokoro_start_reuses_live_session(monkeypatch, capsys):
+    h = _StartHarness(monkeypatch)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (True, "ok"))
+    rc = tts_cli.cmd_kokoro_start(_kokoro_args())
+    assert rc == 0
+    assert h.reaped is False and h.launched is False
+    assert "already running" in capsys.readouterr().out
+
+
+def test_kokoro_start_reaps_and_relaunches_dead_session(monkeypatch, capsys):
+    h = _StartHarness(monkeypatch)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (False, None))
+    rc = tts_cli.cmd_kokoro_start(_kokoro_args())
+    assert rc == 0
+    assert h.reaped is True and h.launched is True
+    out = capsys.readouterr().out
+    assert "not serving" in out and "already running" not in out
+
+
+def test_stt_start_reuses_live_session(monkeypatch, capsys):
+    h = _StartHarness(monkeypatch)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (True, "ok"))
+    rc = tts_cli.cmd_stt_start(_stt_args())
+    assert rc == 0
+    assert h.reaped is False and h.launched is False
+    assert "already running" in capsys.readouterr().out
+
+
+def test_stt_start_reaps_and_relaunches_dead_session(monkeypatch, capsys):
+    h = _StartHarness(monkeypatch)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (False, "failed"))
+    rc = tts_cli.cmd_stt_start(_stt_args())
+    assert rc == 0
+    assert h.reaped is True and h.launched is True
+    out = capsys.readouterr().out
+    assert "not serving" in out and "already running" not in out
+
+
+# === doctor: flag a present-but-dead shim, ignore warming / absent =========
+
+
+def _patch_doctor(monkeypatch, *, tts="default", stt="default", moonshine=True):
+    from agentwire import doctor_cli
+
+    cfg = SimpleNamespace(
+        tts=SimpleNamespace(backend=tts),
+        stt=SimpleNamespace(backend=stt),
+    )
+    # _find_dead_managed_shims imports these lazily from their home modules.
+    import agentwire.config as cfg_mod
+    import agentwire.core as core_mod
+    import agentwire.stt as stt_mod
+
+    monkeypatch.setattr(cfg_mod, "load_config", lambda: cfg)
+    monkeypatch.setattr(core_mod, "get_kokoro_session_name", lambda: "agentwire-kokoro")
+    monkeypatch.setattr(core_mod, "get_stt_session_name", lambda: "agentwire-stt")
+    monkeypatch.setattr(stt_mod, "moonshine_importable", lambda: moonshine)
+    return doctor_cli
+
+
+def test_doctor_flags_dead_kokoro_shim(monkeypatch):
+    doctor_cli = _patch_doctor(monkeypatch, stt="none")
+    from agentwire import core as core_mod
+
+    monkeypatch.setattr(core_mod, "tmux_session_exists", lambda s: True)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (False, None))
+
+    dead = doctor_cli._find_dead_managed_shims()
+    assert len(dead) == 1
+    assert dead[0]["label"] == "Kokoro TTS" and dead[0]["port"] == 8102
+
+
+def test_doctor_ignores_warming_shim(monkeypatch):
+    doctor_cli = _patch_doctor(monkeypatch, stt="none")
+    from agentwire import core as core_mod
+
+    monkeypatch.setattr(core_mod, "tmux_session_exists", lambda s: True)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (True, "loading"))
+
+    assert doctor_cli._find_dead_managed_shims() == []
+
+
+def test_doctor_ignores_absent_session(monkeypatch):
+    doctor_cli = _patch_doctor(monkeypatch)
+    from agentwire import core as core_mod
+
+    # No tmux session → nothing to self-heal, not a dead shim.
+    monkeypatch.setattr(core_mod, "tmux_session_exists", lambda s: False)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (False, None))
+
+    assert doctor_cli._find_dead_managed_shims() == []
+
+
+def test_doctor_skips_stt_when_moonshine_absent(monkeypatch):
+    # STT default tier without Moonshine transcribes in-browser: no shim to flag.
+    doctor_cli = _patch_doctor(monkeypatch, tts="custom", moonshine=False)
+    from agentwire import core as core_mod
+
+    monkeypatch.setattr(core_mod, "tmux_session_exists", lambda s: True)
+    monkeypatch.setattr(tts_cli, "_shim_session_state", lambda s, p: (False, None))
+
+    assert doctor_cli._find_dead_managed_shims() == []