deepparallel 0.5.2__tar.gz → 0.5.4__tar.gz

{deepparallel-0.5.2 → deepparallel-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepparallel
-Version: 0.5.2
+Version: 0.5.4
 Summary: DeepParallel - a multi-model agentic coding CLI with cross-model Guardian review, served via Crowe Logic.
 Author-email: Michael Crowe <michael@crowelogic.com>
 License: Apache-2.0

{deepparallel-0.5.2 → deepparallel-0.5.4}/deepparallel/__init__.py

@@ -1,3 +1,3 @@
 """DeepParallel CLI package."""
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"

{deepparallel-0.5.2 → deepparallel-0.5.4}/deepparallel/agent.py

@@ -307,6 +307,7 @@ def run_agent(
     max_steps: int | None = None,
     stream: bool = False,
     guardian=None,
+    on_event=None,
 ) -> str:
     steps = max_steps if max_steps is not None else settings.max_steps
     schemas = registry.schemas()
@@ -354,6 +355,11 @@ def run_agent(
                 except Exception as e:  # noqa: BLE001 - surface tool failure to model
                     result = json.dumps({"error": f"{type(e).__name__}: {e}"})
             result = str(result)[:_MAX_TOOL_RESULT]
+            if on_event is not None:
+                try:
+                    on_event(name, args, result)
+                except Exception:  # noqa: BLE001 - observation must never break the loop
+                    pass
             ok = '"error"' not in result[:30]
             renderer.tool_result(ok, _summarize_result(name, result), time.monotonic() - start)
             messages.append({"role": "tool", "tool_call_id": tc["id"], "content": result})

{deepparallel-0.5.2 → deepparallel-0.5.4}/deepparallel/cli.py

@@ -16,6 +16,8 @@ apply to chat and run.
 
 from __future__ import annotations
 
+import os
+import subprocess
 import sys
 from dataclasses import replace
 from pathlib import Path
@@ -53,6 +55,8 @@ from deepparallel.fusion import (
 )
 from deepparallel.renderer import PlainRenderer, Renderer, RichRenderer
 from deepparallel.tools import get_registry
+from deepparallel.cockpit import Cockpit
+from deepparallel.cockpit_observe import make_observer
 
 
 def _build_messages(history: list[tuple[str, str]], system: str, user_msg: str) -> list[dict]:
@@ -486,6 +490,74 @@ def run(
         sys.exit(1)
 
 
+@main.command()
+@click.option("--yes", "-y", "assume_yes", is_flag=True, help="Auto-approve tool calls.")
+@click.argument("prompt", nargs=-1, required=True)
+@click.pass_context
+def cockpit(ctx: click.Context, assume_yes: bool, prompt: tuple[str, ...]) -> None:
+    """Run a task in cockpit mode: a live data window plus WaveTerm render blocks.
+
+    The terminal streams the agent while an adjacent block shows a live data
+    window (sources, citations, claims) and pages the agent reads open as web
+    blocks. Outside WaveTerm it runs normally and still logs the event stream.
+    """
+    settings = _apply_flags(ctx.obj["settings"], False, assume_yes)
+    backend = _require_ready(settings)
+    events_path = os.path.abspath(os.path.join(".cockpit", "events.jsonl"))
+    os.makedirs(os.path.dirname(events_path), exist_ok=True)
+    open(events_path, "w").close()
+    cp = Cockpit(events_path)
+    cp.status("start", "cockpit online")
+    if cp.in_waveterm():
+        try:
+            subprocess.Popen(
+                ["wsh", "run", "--", "dp", "_cockpit-panel", events_path],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except Exception:  # noqa: BLE001 - the panel block is best-effort
+            pass
+    backend = _wrap_fusion(backend, settings)
+    system = load_system_prompt()
+    messages = _build_messages([], system, " ".join(prompt))
+    renderer = _make_renderer(force_plain=False, assume_yes=settings.auto_approve)
+    try:
+        run_agent(
+            backend,
+            get_registry(),
+            messages,
+            settings,
+            renderer,
+            interactive=True,
+            auto_approve=settings.auto_approve,
+            stream=True,
+            on_event=make_observer(cp),
+        )
+    except Exception as e:  # noqa: BLE001 - surface as friendly message
+        renderer.error(_translate_error(e))
+        failed = True
+    else:
+        failed = False
+    cp.status("done", "cockpit complete")
+    cp.notify("DeepParallel cockpit run complete")
+    if failed:
+        sys.exit(1)
+
+
+@main.command(name="_cockpit-panel", hidden=True)
+@click.argument("events_path")
+def _cockpit_panel(events_path: str) -> None:
+    """Internal: render the live cockpit data window for an events log."""
+    from deepparallel.cockpit_panel import run_panel
+
+    def _complete(state) -> bool:
+        # cli.cockpit emits status(phase="done", message="cockpit complete")
+        # at the end of a run; stop the panel so its process does not leak.
+        return "cockpit complete" in getattr(state, "status", "")
+
+    run_panel(events_path, stop_when=_complete)
+
+
 @main.command()
 @click.option("--diff", "as_diff", is_flag=True, help="Read a unified diff from stdin.")
 @click.argument("path", required=False)

deepparallel-0.5.4/deepparallel/cockpit.py

@@ -0,0 +1,143 @@
+# Copyright 2026, Crowe Logic Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""WaveTerm orchestration and event-log layer for the DeepParallel cockpit.
+
+The terminal (WaveTerm) is the control and DATA WINDOW; the agent spawns
+adjacent RENDER blocks (web, file preview) via WaveTerm's `wsh` CLI. Everything
+flows through ONE append-only event log: a `.jsonl` file, one JSON object per
+line, default `./.cockpit/events.jsonl`. Producers append; consumers tail.
+
+Event shape:
+  {"t": <float epoch seconds>, "type": <string>, "data": <object>}
+
+`Cockpit` is the single producer surface. `emit` appends a contract event line
+(creating the parent dir, never raising). `open_web` / `view_file` shell out to
+`wsh`, parse the "created block <id>" line, emit a matching "block" event, and
+return the block id. Off WaveTerm (env `WAVETERM` / `WAVETERM_BLOCKID` unset) or
+on any failure these block helpers are graceful no-ops returning None, while
+`emit` still records events so the log stays useful in plain terminals.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+# Bound every shell-out so a hung `wsh` can never stall the agent loop.
+_WSH_TIMEOUT_S = 5.0
+
+# `wsh web open` / `wsh view` print a line like "created block <blockid>".
+_BLOCK_RE = re.compile(r"created block\s+(\S+)", re.IGNORECASE)
+
+
+class Cockpit:
+    """Append-only event log plus WaveTerm `wsh` block orchestration.
+
+    Args:
+        events_path: path to the append-only `.jsonl` event log.
+    """
+
+    def __init__(self, events_path: str = ".cockpit/events.jsonl"):
+        self.events_path = Path(events_path)
+
+    # --- environment -------------------------------------------------------
+
+    def in_waveterm(self) -> bool:
+        """True when running inside a WaveTerm block (env signals present)."""
+        return bool(os.environ.get("WAVETERM") or os.environ.get("WAVETERM_BLOCKID"))
+
+    # --- event log ---------------------------------------------------------
+
+    def emit(self, type: str, **data: Any) -> None:
+        """Append one contract event line. Creates the parent dir. Never raises."""
+        event = {"t": time.time(), "type": type, "data": data}
+        try:
+            self.events_path.parent.mkdir(parents=True, exist_ok=True)
+            line = json.dumps(event, ensure_ascii=False, default=str)
+            with self.events_path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+        except Exception:
+            # The event log is best-effort; a failed write must not break the
+            # agent loop or any producer.
+            pass
+
+    # --- wsh block orchestration ------------------------------------------
+
+    def _run_wsh(self, args: list[str]) -> str | None:
+        """Run `wsh <args>` time-bounded; return stdout or None on any failure."""
+        if not self.in_waveterm():
+            return None
+        try:
+            proc = subprocess.run(
+                ["wsh", *args],
+                capture_output=True,
+                text=True,
+                timeout=_WSH_TIMEOUT_S,
+                check=False,
+            )
+        except Exception:
+            return None
+        if proc.returncode != 0:
+            return None
+        return proc.stdout
+
+    @staticmethod
+    def _parse_blockid(stdout: str | None) -> str | None:
+        """Extract the block id from a `wsh` "created block <id>" line."""
+        if not stdout:
+            return None
+        match = _BLOCK_RE.search(stdout)
+        return match.group(1) if match else None
+
+    def open_web(self, url: str) -> str | None:
+        """Open a WaveTerm web block for `url`; emit a "block" event; return id.
+
+        No-op returning None off WaveTerm or on any `wsh` failure.
+        """
+        blockid = self._parse_blockid(self._run_wsh(["web", "open", url]))
+        if blockid is not None:
+            self.emit("block", action="open", kind="web", target=url, blockid=blockid)
+        return blockid
+
+    def view_file(self, path: str) -> str | None:
+        """Open a WaveTerm preview block for `path`; emit a "block" event; return id.
+
+        No-op returning None off WaveTerm or on any `wsh` failure.
+        """
+        blockid = self._parse_blockid(self._run_wsh(["view", path]))
+        if blockid is not None:
+            self.emit("block", action="open", kind="file", target=path, blockid=blockid)
+        return blockid
+
+    def notify(self, message: str) -> None:
+        """Best-effort `wsh notify`. Silent no-op off WaveTerm or on failure."""
+        self._run_wsh(["notify", message])
+
+    # --- contract event helpers -------------------------------------------
+
+    def status(self, phase: str, message: str) -> None:
+        """Emit a "status" event."""
+        self.emit("status", phase=phase, message=message)
+
+    def source(self, url: str, title: str, provider: str) -> None:
+        """Emit a "source" event for a grounded source fetched."""
+        self.emit("source", url=url, title=title, provider=provider)
+
+    def citation(self, ref: int, url: str, title: str) -> None:
+        """Emit a "citation" event for a cited reference."""
+        self.emit("citation", ref=ref, url=url, title=title)
+
+    def claim(self, text: str, grounded: bool, confidence: float) -> None:
+        """Emit a "claim" event. Confidence is clamped to the 0..1 contract range."""
+        confidence = min(1.0, max(0.0, confidence))
+        self.emit("claim", text=text, grounded=grounded, confidence=confidence)
+
+    def sim(self, step: int, arm: str, metric: str, value: float) -> None:
+        """Emit a "sim" event for one A/B simulation datapoint."""
+        self.emit("sim", step=step, arm=arm, metric=metric, value=value)

deepparallel-0.5.4/deepparallel/cockpit_observe.py

@@ -0,0 +1,58 @@
+# Copyright 2026, Crowe Logic Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Translate agent tool results into cockpit events and render blocks.
+
+`make_observer(cockpit)` returns a callback the agent loop invokes after every
+tool call as `observe(name, args, result)`. It reads grounding tool results
+(web_search, web_fetch, mcp_search) and emits the matching contract events so
+the live data window updates, and opens the pages the agent reads as adjacent
+WaveTerm web blocks (capped, so a long run does not spawn dozens of blocks).
+Observation is best-effort: it never raises into the agent loop.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+_MAX_WEB_BLOCKS = 4  # cap render blocks opened from fetched pages
+
+
+def make_observer(cockpit) -> Callable[[str, dict, str], None]:
+    """Return an observe(name, args, result) callback bound to `cockpit`."""
+    counters = {"ref": 0, "blocks": 0}
+
+    def observe(name: str, args: dict, result: str) -> None:
+        try:
+            obj: Any = json.loads(result)
+        except (ValueError, TypeError):
+            obj = None
+        try:
+            if isinstance(obj, dict) and "error" not in obj:
+                if name == "web_search":
+                    provider = obj.get("provider", "web")
+                    for r in (obj.get("results") or [])[:8]:
+                        url = r.get("url")
+                        if not url:
+                            continue
+                        counters["ref"] += 1
+                        cockpit.source(url=url, title=r.get("title", ""), provider=provider)
+                        cockpit.citation(ref=counters["ref"], url=url, title=r.get("title", ""))
+                    answer = obj.get("answer")
+                    if answer:
+                        cockpit.claim(text=str(answer)[:240], grounded=True, confidence=0.7)
+                elif name == "web_fetch":
+                    url = obj.get("url") or (args or {}).get("url", "")
+                    if url:
+                        cockpit.source(url=url, title=obj.get("title", ""), provider="fetch")
+                        if counters["blocks"] < _MAX_WEB_BLOCKS and cockpit.open_web(url):
+                            counters["blocks"] += 1
+                elif name == "mcp_search":
+                    for s in (obj.get("servers") or [])[:5]:
+                        cockpit.source(url="", title=s.get("name", ""), provider="mcp")
+            cockpit.status("tool", name)
+        except Exception:  # noqa: BLE001 - observation must never break the loop
+            pass
+
+    return observe

deepparallel-0.5.4/deepparallel/cockpit_panel.py

@@ -0,0 +1,320 @@
+"""Live terminal DATA WINDOW for the DeepParallel cockpit.
+
+The cockpit's terminal pane (WaveTerm) is the control surface and data window;
+the agent spawns adjacent RENDER blocks for the visual output. This module owns
+the data window: it tails the shared append-only event log (one JSON object per
+line, see the cockpit contract) and drives a dense, no-chrome Rich panel that
+tallies sources, citations, claims, and the A/B simulation metrics in real time.
+
+It is UI-only and side-effect-free apart from tailing the log: state is a plain
+dataclass, `apply_event` mutates it from one contract event, and `render`
+returns a Rich renderable. `run_panel` wires those into a `rich.live.Live` at a
+calm refresh rate and is safe to start before the log file exists.
+
+Aesthetic follows the DeepParallel CLI family (see `branding`): cyan identity
+accent, the shared glyph alphabet, status hues for grounded vs unverified, no
+emojis and no em dashes in any user-facing string.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+from rich import box
+from rich.console import Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from deepparallel import branding
+
+# Refresh cadence for the Live region. ~6 fps is dense enough to feel live while
+# leaving the terminal idle between event bursts.
+_FPS = 6
+_POLL_SECONDS = 1.0 / _FPS
+# How many of the most recent sources to show; older ones collapse into a count.
+_SOURCES_SHOWN = 4
+
+
+@dataclass
+class CockpitState:
+    """Accumulated view of the cockpit event stream.
+
+    Append-only collections mirror the log; `sim` keeps only the latest value
+    per (arm, metric) so the A/B table stays current rather than historical.
+    """
+
+    sources: list[dict] = field(default_factory=list)
+    citations: list[dict] = field(default_factory=list)
+    claims: list[dict] = field(default_factory=list)
+    sim: dict[tuple[str, str], float] = field(default_factory=dict)
+    status: str = "idle"
+
+    @property
+    def grounded_claims(self) -> int:
+        return sum(1 for c in self.claims if c.get("grounded"))
+
+    @property
+    def unverified_claims(self) -> int:
+        return sum(1 for c in self.claims if not c.get("grounded"))
+
+
+def apply_event(state: CockpitState, event: dict) -> None:
+    """Mutate `state` from one contract event. Unknown or malformed events are
+    ignored so a single bad line never derails the data window."""
+    if not isinstance(event, dict):
+        return
+    etype = event.get("type")
+    data = event.get("data")
+    if not isinstance(data, dict):
+        return
+
+    if etype == "status":
+        phase = str(data.get("phase", "")).strip()
+        message = str(data.get("message", "")).strip()
+        state.status = " ".join(p for p in (phase, message) if p) or state.status
+    elif etype == "source":
+        state.sources.append(
+            {
+                "url": str(data.get("url", "")),
+                "title": str(data.get("title", "")),
+                "provider": str(data.get("provider", "")),
+            }
+        )
+    elif etype == "citation":
+        state.citations.append(
+            {
+                "ref": data.get("ref"),
+                "url": str(data.get("url", "")),
+                "title": str(data.get("title", "")),
+            }
+        )
+    elif etype == "claim":
+        state.claims.append(
+            {
+                "text": str(data.get("text", "")),
+                "grounded": bool(data.get("grounded", False)),
+                "confidence": min(1.0, max(0.0, _as_float(data.get("confidence"), 0.0))),
+            }
+        )
+    elif etype == "sim":
+        arm = str(data.get("arm", ""))
+        metric = str(data.get("metric", ""))
+        if arm and metric:
+            state.sim[(arm, metric)] = _as_float(data.get("value"), 0.0)
+    # "block" events drive render blocks elsewhere; the data window ignores them.
+
+
+def _as_float(value: object, default: float) -> float:
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+
+
+def _counter(label: str, value: object, accent: str) -> Text:
+    """A compact 'label value' counter chip."""
+    t = Text()
+    t.append(f"{label} ", style=branding.DIM)
+    t.append(str(value), style=f"bold {accent}")
+    return t
+
+
+def _sources_section(state: CockpitState) -> Group:
+    header = Text()
+    header.append(f"{branding.MARK} Sources ", style=f"bold {branding.DP_ACCENT}")
+    header.append(str(len(state.sources)), style=f"bold {branding.BLUE_HEX}")
+    if not state.sources:
+        return Group(header, Text("  (none yet)", style=branding.DIM))
+
+    table = Table.grid(padding=(0, 1))
+    table.add_column(justify="right", style=branding.DIM, no_wrap=True)
+    table.add_column(style="white", no_wrap=True, max_width=44)
+    table.add_column(style=branding.DIM, no_wrap=True)
+    recent = state.sources[-_SOURCES_SHOWN:]
+    start = len(state.sources) - len(recent) + 1
+    for i, src in enumerate(recent, start=start):
+        title = src.get("title") or src.get("url") or "(untitled)"
+        provider = src.get("provider") or ""
+        table.add_row(f"{i}.", _ellipsize(title, 44), provider)
+    return Group(header, table)
+
+
+def _claims_section(state: CockpitState) -> Group:
+    total = len(state.claims)
+    header = Text()
+    header.append(f"{branding.MARK} Claims ", style=f"bold {branding.DP_ACCENT}")
+    header.append(str(total), style="bold white")
+
+    line = Text("  ")
+    line.append(f"{branding.CHECK} grounded ", style=branding.GREEN_HEX)
+    line.append(str(state.grounded_claims), style=f"bold {branding.GREEN_HEX}")
+    line.append(f"   {branding.DOT}   ", style=branding.DIM)
+    line.append(f"{branding.CROSS} unverified ", style=branding.AMBER_HEX)
+    line.append(str(state.unverified_claims), style=f"bold {branding.AMBER_HEX}")
+    return Group(header, line)
+
+
+def _sim_table(state: CockpitState) -> Table:
+    """A/B simulation metrics: one row per metric, latest A vs B values, with the
+    leading arm highlighted. Arms beyond A/B are tolerated but not columned."""
+    table = Table(
+        box=box.SIMPLE_HEAD,
+        padding=(0, 1),
+        title=Text(f"{branding.MARK} Sim metrics", style=f"bold {branding.DP_ACCENT}"),
+        title_justify="left",
+        expand=False,
+    )
+    table.add_column("metric", style=branding.DIM, no_wrap=True)
+    table.add_column("arm A", justify="right", no_wrap=True)
+    table.add_column("arm B", justify="right", no_wrap=True)
+
+    metrics = sorted({metric for (_arm, metric) in state.sim})
+    if not metrics:
+        table.add_row("(none yet)", "-", "-")
+        return table
+    for metric in metrics:
+        a = state.sim.get(("A", metric))
+        b = state.sim.get(("B", metric))
+        table.add_row(metric, _arm_cell(a, a, b), _arm_cell(b, a, b))
+    return table
+
+
+def _arm_cell(value: float | None, a: float | None, b: float | None) -> Text:
+    """Format one arm cell, bolding the leader when both arms are present."""
+    if value is None:
+        return Text("-", style=branding.DIM)
+    leading = a is not None and b is not None and value == max(a, b) and a != b
+    style = f"bold {branding.GREEN_HEX}" if leading else "white"
+    return Text(f"{value:.4g}", style=style)
+
+
+def _status_line(state: CockpitState) -> Text:
+    line = Text()
+    line.append(f"{branding.ARROW} ", style=branding.DP_ACCENT)
+    line.append("status ", style=branding.DIM)
+    line.append(state.status or "idle", style=f"bold {branding.DP_ACCENT}")
+    return line
+
+
+def render(state: CockpitState):
+    """Build the data-window panel: counters, sources, claims, sim, status.
+
+    Returns a Rich renderable (a titled `Panel`) so callers can print it once or
+    feed it to a `Live` region.
+    """
+    counters = Table.grid(padding=(0, 3))
+    counters.add_column()
+    counters.add_column()
+    counters.add_column()
+    counters.add_row(
+        _counter("sources", len(state.sources), branding.BLUE_HEX),
+        _counter("citations", len(state.citations), branding.DP_ACCENT),
+        _counter("claims", len(state.claims), "white"),
+    )
+
+    body = Group(
+        counters,
+        Text(branding.RULE * 40, style=branding.DIM),
+        _sources_section(state),
+        Text(),
+        _claims_section(state),
+        Text(),
+        _sim_table(state),
+        Text(branding.RULE * 40, style=branding.DIM),
+        _status_line(state),
+    )
+
+    title = Text()
+    title.append("DeepParallel ", style=f"bold {branding.DP_ACCENT}")
+    title.append("data window", style=branding.DIM)
+    return Panel(
+        body,
+        title=title,
+        title_align="left",
+        border_style=branding.DP_ACCENT,
+        box=box.ROUNDED,
+        padding=(0, 1),
+    )
+
+
+def _ellipsize(text: str, width: int) -> str:
+    text = text.replace("\n", " ").strip()
+    if len(text) <= width:
+        return text
+    return text[: max(1, width - 1)] + branding.DOT
+
+
+def _read_new_lines(path: str, offset: int) -> tuple[list[str], int]:
+    """Read any lines appended past `offset`. Returns (lines, new_offset). Safe
+    when the file is missing or was truncated/rotated (offset resets to 0)."""
+    try:
+        size = _file_size(path)
+        if size < offset:  # truncated or rotated: start over
+            offset = 0
+        with open(path, "r", encoding="utf-8") as fh:
+            fh.seek(offset)
+            chunk = fh.read()
+            new_offset = fh.tell()
+    except FileNotFoundError:
+        return [], offset
+    except OSError:
+        return [], offset
+    if not chunk:
+        return [], new_offset
+    # Keep only complete lines; a trailing partial line stays for the next poll.
+    if not chunk.endswith("\n"):
+        last_nl = chunk.rfind("\n")
+        if last_nl == -1:
+            return [], offset  # no complete line yet; do not advance
+        new_offset = offset + len(chunk[: last_nl + 1].encode("utf-8"))
+        chunk = chunk[: last_nl + 1]
+    return [ln for ln in chunk.splitlines() if ln.strip()], new_offset
+
+
+def _file_size(path: str) -> int:
+    import os
+
+    return os.path.getsize(path)
+
+
+def run_panel(
+    events_path: str,
+    stop_when: Callable[[CockpitState], bool] | None = None,
+    *,
+    console=None,
+    poll_seconds: float = _POLL_SECONDS,
+    sleep: Callable[[float], None] = time.sleep,
+) -> CockpitState:
+    """Tail `events_path` and drive a Live data window at ~6 fps.
+
+    Appended events are applied to a fresh `CockpitState` and the panel
+    re-rendered each tick. Returns the final state. Stops when `stop_when(state)`
+    is truthy (checked after each batch) or on KeyboardInterrupt; if `stop_when`
+    is None it runs until interrupted. Safe to start before the file exists.
+    """
+    from rich.live import Live
+
+    con = console or branding.console
+    state = CockpitState()
+    offset = 0
+
+    with Live(render(state), console=con, refresh_per_second=_FPS, transient=False) as live:
+        try:
+            while True:
+                lines, offset = _read_new_lines(events_path, offset)
+                for line in lines:
+                    try:
+                        apply_event(state, json.loads(line))
+                    except (json.JSONDecodeError, ValueError):
+                        continue  # tolerate a partial or malformed line
+                live.update(render(state))
+                if stop_when is not None and stop_when(state):
+                    break
+                sleep(poll_seconds)
+        except KeyboardInterrupt:
+            pass
+    return state