kiwi-code 0.0.505__tar.gz → 0.0.506__tar.gz

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kiwi-code
-Version: 0.0.505
+Version: 0.0.506
 Summary: A textual-based terminal user interface application
 Project-URL: Homepage, https://kiwicode.ai
 Author-email: Anurag <anurag@meetkiwi.co>

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiwi-code"
-version = "0.0.505"
+version = "0.0.506"
 description = "A textual-based terminal user interface application"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.11,<4.0"

kiwi_code-0.0.506/src/kiwi_tui/attention.py

@@ -0,0 +1,107 @@
+"""Calling the user back when the agent needs them: a question waiting for an answer, or a
+run that has finished.
+
+While kiwi's window has focus the user is there, and the screen itself shows it. When they
+are elsewhere (the terminal tells kiwi when its window loses focus), kiwi:
+
+- shows a desktop notification, through the terminal (OSC 777 / 9 / 99), so it also works
+  over ssh; a terminal with none of them gets `notify-send` / `osascript` instead, when
+  kiwi runs on the user's own machine;
+- rings the terminal bell (a sound, and a mark on the tab or dock icon in most terminals);
+- puts a mark in the tab title, until the window has focus again.
+
+`/notify on | quiet | off` chooses: quiet leaves out the bell; off does none of it.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping
+
+MODES = ("on", "quiet", "off")
+DEFAULT_MODE = "on"
+#: The tab title kiwi starts with; set by main once it knows the folder.
+BASE_TITLE = "kiwi"
+
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]+")
+
+
+def mode_from(settings: Mapping) -> str:
+    mode = str(settings.get("notify") or DEFAULT_MODE).lower()
+    return mode if mode in MODES else DEFAULT_MODE
+
+
+def _clean(text: str, limit: int = 160) -> str:
+    """One line, no control characters (they could end the sequence), and short."""
+    text = " ".join(_CONTROL.sub(" ", str(text or "")).split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def notification_sequence(title: str, body: str, env: Mapping[str, str] = os.environ) -> str:
+    """The escape sequence that makes this terminal show a desktop notification; "" for a
+    terminal not known to have one (an unknown one would print it, or ignore it)."""
+    title, body = _clean(title, 60), _clean(body)
+    program = env.get("TERM_PROGRAM", "").lower()
+    term = env.get("TERM", "").lower()
+    if env.get("TMUX") or term.startswith(("screen", "tmux")):
+        return ""  # tmux keeps these to itself unless told to pass them on
+    if env.get("KITTY_WINDOW_ID") or "kitty" in term:
+        return f"\x1b]99;;{title}: {body}\x1b\\"
+    if program in ("ghostty", "wezterm") or "ghostty" in term:
+        # `;` separates the fields of OSC 777.
+        return f"\x1b]777;notify;{title.replace(';', ',')};{body.replace(';', ',')}\x07"
+    if program == "iterm.app":
+        return f"\x1b]9;{title}: {body}\x07"
+    return ""
+
+
+def local_notification_command(
+    title: str, body: str, env: Mapping[str, str] = os.environ, platform: str | None = None
+) -> list[str] | None:
+    """A command that shows the notification on this machine, for a terminal that cannot;
+    None over ssh (it would show on the wrong machine) or when there is none."""
+    if env.get("SSH_CONNECTION") or env.get("SSH_TTY"):
+        return None
+    platform = platform or sys.platform
+    title, body = _clean(title, 60), _clean(body)
+    if platform == "darwin":
+        def quoted(s: str) -> str:
+            return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+        return ["osascript", "-e", f"display notification {quoted(body)} with title {quoted(title)}"]
+    if platform.startswith("linux") and shutil.which("notify-send"):
+        return ["notify-send", "--app-name=Kiwi", title, body]
+    return None
+
+
+def title_sequence(title: str) -> str:
+    return f"\x1b]2;{_clean(title, 120)}\x07"
+
+
+def call_out(write, *, mode: str, title: str, body: str, tab: str, env: Mapping[str, str] = os.environ) -> None:
+    """Notify, ring and mark the tab, as `mode` allows. `write` sends text to the terminal."""
+    if mode == "off":
+        return
+    out = title_sequence(tab)
+    if mode == "on":
+        out += "\a"
+    sequence = notification_sequence(title, body, env)
+    write(out + sequence)
+    if not sequence:
+        command = local_notification_command(title, body, env)
+        if command:
+            launch(command)
+
+
+def launch(command: list[str]) -> None:
+    """Start `command` and leave it: kiwi does not wait for the notification."""
+    try:
+        subprocess.Popen(
+            command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL, start_new_session=True,
+        )
+    except OSError:
+        pass

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/main.py

@@ -43,6 +43,7 @@ from kiwi_tui.runtime_agent import (
 )
 
 from kiwi_tui.ui_settings import load_settings as load_ui_settings, update_settings as update_ui_settings
+from kiwi_tui import attention
 
 
 
@@ -902,6 +903,32 @@ class AutobotsTUI(App):
     #: The most toasts shown at once; older ones give way.
     MAX_TOASTS = 3
 
+    def call_for_attention(self, *, title: str, body: str, tab: str) -> bool:
+        """Call the user back (notification, bell, tab title) when kiwi's window is not
+        in focus: when it is, they are here. Whether it did."""
+        if self.app_focus:
+            return False
+        try:
+            mode = attention.mode_from(load_ui_settings())
+            attention.call_out(self._write_to_terminal, mode=mode, title=title, body=body, tab=tab)
+        except Exception as e:
+            logger.debug(f"Calling for attention failed: {e}")
+            return False
+        self._tab_marked = mode != "off"
+        return True
+
+    def _write_to_terminal(self, text: str) -> None:
+        driver = self._driver
+        if driver is not None and text:
+            driver.write(text)
+            driver.flush()
+
+    def on_app_focus(self, _event) -> None:
+        # Back at kiwi: the mark on the tab has done its job.
+        if getattr(self, "_tab_marked", False):
+            self._tab_marked = False
+            self._write_to_terminal(attention.title_sequence(attention.BASE_TITLE))
+
     def _on_notify(self, event) -> None:
         make_room_for_toast(self._notifications, event.notification, self.MAX_TOASTS)
         super()._on_notify(event)
@@ -1297,7 +1324,8 @@ def main() -> int:
     if sys.stdout.isatty():
         # Strip C0 control chars and DEL to prevent terminal injection via crafted dir names.
         safe_dir = "".join(ch for ch in display_dir if ch >= " " and ch != "\x7f")
-        sys.stdout.write(f"\033]0;kiwi ({safe_dir})\007")
+        attention.BASE_TITLE = f"kiwi ({safe_dir})"
+        sys.stdout.write(f"\033]0;{attention.BASE_TITLE}\007")
         sys.stdout.flush()
 
     runtime_args = _build_runtime_args(args)

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/screens/term_activity_view.py

@@ -313,17 +313,17 @@ def _spaced(parts: list) -> list:
 def trace_renderable(
     lines: list[TraceLine], start: int | None, *, cyan: str, total: int, shown: int = SHOWN_TRACE
 ) -> Text:
-    """The latest `shown` trace lines: number, time since the first event, type, what it says."""
+    """The latest `shown` trace lines: time since the first event, type, what it says.
+    Kept narrow: the trace is a column beside the conversation."""
     families = {"turn": cyan, "step": "dim", "tool": "yellow", "subagent": "magenta", "question": "blue"}
     out = Text()
-    out.append(f"Trace · latest {min(len(lines), shown)} of {total} kept · esc or ctrl+t to hide", style="dim")
+    out.append(f"Trace · {min(len(lines), shown)} of {total} · esc to close", style="dim")
     for line in lines[-shown:]:
         family = line.type.split(".", 1)[0]
         secs = ((line.at - (start or line.at)) / 1000) if line.at else 0
         out.append("\n")
-        out.append(f"{line.seq:>5} ", style="dim")
-        out.append(f"+{secs:.2f}s".ljust(10), style="dim")
-        out.append(f"{line.type:<18}", style=families.get(family, ""))
+        out.append(f"+{secs:.1f}s".ljust(8), style="dim")
+        out.append(f"{line.type:<17}", style=families.get(family, ""))
         what = line.what if line.count == 1 else f"×{line.count} {line.what}"
         out.append(what)
     return out

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/screens/term_dashboard.py

@@ -127,6 +127,16 @@ def _edits_path(run_id: str):
         return None
 
 
+class TranscriptScroll(VerticalScroll):
+    """The conversation. Scrolling it up with the wheel stops following its end at once,
+    before the next streamed text would pull the view back down."""
+
+    def _on_mouse_scroll_up(self, event: events.MouseScrollUp) -> None:
+        if not (event.ctrl or event.shift):
+            self.screen._follow_tail = False
+        super()._on_mouse_scroll_up(event)
+
+
 class TermDashboardScreen(Screen):
     BINDINGS = [
         Binding("escape", "dismiss_or_clear", "Dismiss", show=False, priority=True),
@@ -256,8 +266,11 @@ class TermDashboardScreen(Screen):
 
     def compose(self) -> ComposeResult:
         yield TermTopBar("", id="term-top-bar", markup=False)
+        # The latest activity events of the run, live, in a column at the right
+        # (ctrl+t / /trace; shown/hidden).
+        yield Static("", id="term-trace-panel", markup=False)
 
-        with VerticalScroll(id="term-scroll-transcript"):
+        with TranscriptScroll(id="term-scroll-transcript"):
 
             # Welcome header (shown at top in empty state, hidden once
             # the user sends their first real message)
@@ -300,8 +313,6 @@ class TermDashboardScreen(Screen):
                     # Consistent dismissal hint for all inline slash-command panels.
                     yield Static("Press ESC to dismiss", id="term-cmd-result-dismiss", markup=False)
         with Vertical(id="term-bottom-area"):
-            # The latest activity events of the run (ctrl+t / /trace; shown/hidden).
-            yield Static("", id="term-trace-panel", markup=False)
             # Activity row (shown/hidden)
             yield Static("", id="term-activity-bar", markup=False)
             # Subagents still working while the agent waits on them (shown/hidden).
@@ -407,10 +418,14 @@ class TermDashboardScreen(Screen):
         near_bottom = self._near_bottom(threshold=6)
         at_tail = self._window_end_turn() >= len(self._turns)
 
-        if near_bottom and at_tail:
-            self._follow_tail = True
-        elif not near_bottom:
+        # Following the end stops when the user moves up (the scrollbar too) and starts
+        # again only at the very end: new text arriving never moves the view on its own.
+        last_y = getattr(self, "_last_scroll_y", None)
+        self._last_scroll_y = min(cur_y, tgt_y)
+        if last_y is not None and min(cur_y, tgt_y) < last_y:
             self._follow_tail = False
+        elif at_tail and self._near_bottom(threshold=1):
+            self._follow_tail = True
 
         now = time.monotonic()
         last_shift = float(getattr(self, "_last_window_shift_at", 0.0))
@@ -465,6 +480,7 @@ class TermDashboardScreen(Screen):
             pass
         self._refresh_logo()
         self._refresh_input_label()
+        self._place_trace()
 
 
     def _refresh_logo(self) -> None:
@@ -1077,8 +1093,11 @@ class TermDashboardScreen(Screen):
             self._hide_slash_autocomplete()
             return
         if getattr(self, "_trace_shown", False):
+            # Closed even while hidden by a narrow terminal, so it does not pop up later.
+            shown = self._trace_visible()
             self.action_toggle_trace()
-            return
+            if shown:
+                return
         # Priority 2: hide cmd result panel
         if self._cmd_result_visible:
             self._hide_cmd_result()
@@ -2730,6 +2749,32 @@ class TermDashboardScreen(Screen):
         except Exception:
             _do()
 
+    def _call_for_attention(self, kind: str, *, answer: object = "") -> None:
+        """The run waits for the user's answer, or is done: call them back if they are
+        away from kiwi (notification, bell, tab title; see kiwi_tui.attention)."""
+        if kind == "question":
+            from kiwi_cli.human_questions import PENDING
+
+            pending = [q for t in self._turns for q in t.questions if q.get("status") == PENDING]
+            if not pending:
+                return
+            body = pending[0].get("question") or pending[0].get("header") or "The agent is waiting for your answer."
+            if len(pending) > 1:
+                body = f"{body} (+{len(pending) - 1} more)"
+            title, tab = "Kiwi needs your answer", "● kiwi – waiting for you"
+        else:
+            lines = str(answer or "").strip().splitlines()
+            body = lines[0].lstrip("#*> ").strip() if lines else "The run has finished."
+            title, tab = "Kiwi finished", "✓ kiwi – done"
+        call = getattr(self.app, "call_for_attention", None)
+        away = bool(call is not None and call(title=title, body=body, tab=tab))
+        if not away and kind == "question":
+            try:
+                self.notify("The agent is waiting for your answer below.", title="Question",
+                            severity="information", timeout=4, markup=False)
+            except Exception:
+                pass
+
     def _apply_human_questions(self, questions: list[dict], *, render: bool = True) -> None:
         """Put the run's questions on the turns they were asked in.
 
@@ -3286,6 +3331,41 @@ class TermDashboardScreen(Screen):
                     self._show_inline_cmd_result(command, token_usage_renderable(usage, cyan=cyan))
                 return
 
+            if cmd == "/notify":
+                from kiwi_tui import attention
+                from kiwi_tui.ui_settings import load_settings, update_settings
+
+                choice = args[0].lower() if args else ""
+                if choice in attention.MODES:
+                    update_settings({"notify": choice})
+                    toast({
+                        "on": "Notifications on: notification and bell when kiwi needs you and you are away.",
+                        "quiet": "Notifications quiet: a notification without the bell.",
+                        "off": "Notifications off.",
+                    }[choice], title="/notify")
+                    return
+                if choice == "test":
+                    # Shown even with kiwi in focus (and when off): this is how it looks.
+                    mode = attention.mode_from(load_settings())
+                    attention.call_out(
+                        self.app._write_to_terminal, mode="quiet" if mode == "off" else mode,
+                        title="Kiwi", body="This is how kiwi calls you back.", tab=attention.BASE_TITLE,
+                    )
+                    toast("Sent a test notification.", title="/notify")
+                    return
+                show("\n".join([
+                    f"Notifications: {attention.mode_from(load_settings())}",
+                    "",
+                    "When a question waits for your answer, or a run finishes, while you are in",
+                    "another window: a desktop notification, the bell, and a mark on the tab.",
+                    "",
+                    "  /notify on      notification and bell (default)",
+                    "  /notify quiet   notification, no bell",
+                    "  /notify off     none of it",
+                    "  /notify test    send a test notification",
+                ]))
+                return
+
             if cmd == "/theme":
                 if not args:
                     current = getattr(self.app, "theme", None) or "(unknown)"
@@ -5214,6 +5294,9 @@ class TermDashboardScreen(Screen):
                             self._set_streaming(False)
                             if status == WAITING_STATUS:
                                 self._focus_pending_questions()
+                                self._call_for_attention("question")
+                            else:
+                                self._call_for_attention("finished", answer=extract_text(last["output"]))
                             return True
                     if status == WAITING_STATUS:
                         # Asked without a closing sentence: the cards are the whole reply.
@@ -5225,6 +5308,7 @@ class TermDashboardScreen(Screen):
                         self._set_run_inflight(False)
                         self._set_streaming(False)
                         self._focus_pending_questions()
+                        self._call_for_attention("question")
                         return True
                     return False
             except Exception as e:
@@ -5486,7 +5570,7 @@ class TermDashboardScreen(Screen):
         except Exception:
             t = None
 
-        should_follow = bool(self._follow_tail) or self._near_bottom(threshold=6)
+        should_follow = bool(self._follow_tail) or self._near_bottom(threshold=1)
         if should_follow:
             self._follow_tail = True
             self._set_window_to_tail()
@@ -5544,7 +5628,7 @@ class TermDashboardScreen(Screen):
         except Exception:
             t = None
 
-        should_follow = bool(self._follow_tail) or self._near_bottom(threshold=6)
+        should_follow = bool(self._follow_tail) or self._near_bottom(threshold=1)
         if should_follow:
             self._follow_tail = True
             self._set_window_to_tail()
@@ -5574,18 +5658,41 @@ class TermDashboardScreen(Screen):
 
     # ---- trace panel ----
 
+    #: Narrower than this, the trace column would squeeze the conversation: it hides, and
+    #: comes back when the terminal is wide enough again.
+    TRACE_MIN_WIDTH = 90
+
     def action_toggle_trace(self) -> None:
         """Show or hide the latest activity events of the run being followed."""
         self._trace_shown = not getattr(self, "_trace_shown", False)
+        if self._trace_shown and not self._trace_fits():
+            self.notify(
+                f"The trace needs a terminal at least {self.TRACE_MIN_WIDTH} columns wide; "
+                "it opens when the window is wider.",
+                title="/trace", severity="warning", timeout=4, markup=False,
+            )
+        self._place_trace()
+
+    def _trace_fits(self) -> bool:
+        return self.size.width >= self.TRACE_MIN_WIDTH
+
+    def _trace_visible(self) -> bool:
+        return getattr(self, "_trace_shown", False) and self._trace_fits()
+
+    def _place_trace(self) -> None:
+        """Show the trace column when it is asked for and fits; hide it otherwise."""
         try:
             panel = self.query_one("#term-trace-panel", Static)
-            panel.set_class(self._trace_shown, "visible")
         except Exception:
             return
-        self._refresh_trace_panel(force=True)
+        visible = self._trace_visible()
+        if panel.has_class("visible") != visible:
+            panel.set_class(visible, "visible")
+            if visible:
+                self._refresh_trace_panel(force=True)
 
     def _refresh_trace_panel(self, *, force: bool = False) -> None:
-        if not getattr(self, "_trace_shown", False):
+        if not self._trace_visible():
             return
         view = getattr(self, "_activity_view", None)
         now = time.monotonic()
@@ -5609,11 +5716,10 @@ class TermDashboardScreen(Screen):
             cyan = self.app.get_css_variables().get("brand-cyan", "#63d8dc")
         except Exception:
             cyan = "#63d8dc"
-        # About two fifths of the terminal, so the conversation stays in view.
-        shown = max(8, int(self.size.height * 0.4) - 1)
-        panel.styles.max_height = shown + 1
+        # As many as fit in the column, under its heading.
+        shown = max(8, self.size.height - 3)
         if view is None or not view.trace:
-            panel.update("Trace · no activity yet · esc or ctrl+t to hide")
+            panel.update("Trace · no activity yet · esc to close")
             return
         lines = list(view.trace)
         panel.update(trace_renderable(lines, view.trace_start, cyan=cyan, total=len(lines), shown=shown))
@@ -6008,6 +6114,7 @@ class TermDashboardScreen(Screen):
     def action_transcript_page_up(self) -> None:
         if not self._transcript_nav_enabled():
             return
+        self._follow_tail = False
         root = self._transcript_scroll()
         if root is None:
             return

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/screens/term_dashboard_css.py

@@ -230,13 +230,16 @@ TERM_DASHBOARD_CSS = """
     /* ── Activity / pending files bars ─────────────────── */
     #term-trace-panel {
         display: none;
-        height: auto;
-        max-height: 40%;
-        width: 100%;
-        padding: 0 2;
-        margin: 1 0 0 0;
+        dock: right;
+        width: 40%;
+        min-width: 36;
+        height: 100%;
+        padding: 0 1;
+        border-left: vkey $panel-lighten-2;
         background: $surface;
         overflow: hidden;
+        text-wrap: nowrap;
+        text-overflow: ellipsis;
     }
 
     #term-trace-panel.visible {

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/screens/term_dashboard_helpers.py

@@ -30,6 +30,7 @@ from kiwi_cli.commands import (
 STREAMING_SAFE_SLASH_PREFIXES = (
     "/help",
     "/theme",
+    "/notify",
     "/show-logs",
     "/status",
     "/cancel",

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/src/kiwi_tui/slash_commands.py

@@ -56,6 +56,13 @@ SLASH_COMMANDS: list[SlashCommand] = [
     SlashCommand("Runtime", "/show-logs", "Show local CLI (runtime) logs", "/show-logs"),
     SlashCommand("Runtime", "/runtime", "Runtime commands (currently disabled)", "/runtime"),
 
+    # Notifications
+    SlashCommand("Notify", "/notify", "How kiwi calls you back when it needs you", "/notify"),
+    SlashCommand("Notify", "/notify on", "Notification and bell when a question waits or a run finishes", "/notify on"),
+    SlashCommand("Notify", "/notify quiet", "Notification without the bell", "/notify quiet"),
+    SlashCommand("Notify", "/notify off", "No notifications", "/notify off"),
+    SlashCommand("Notify", "/notify test", "Send a test notification", "/notify test"),
+
     # Theme
     SlashCommand("Theme", "/theme", "Show current theme / usage", "/theme"),
     SlashCommand("Theme", "/theme list", "List available themes", "/theme list"),

{kiwi_code-0.0.505 → kiwi_code-0.0.506}/tests/conftest.py

@@ -63,3 +63,14 @@ def isolated_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     # Prevent the re-exec trick in kiwi_tui.main from firing during tests.
     monkeypatch.setenv("_KIWI_PROC_RENAMED", "1")
     return tmp_path
+
+
+@pytest.fixture(autouse=True)
+def no_desktop_notifications(monkeypatch: pytest.MonkeyPatch) -> list:
+    """Kiwi calls the user back with `notify-send` / `osascript` when its terminal cannot
+    show a notification: tests must never pop one up on the developer's desktop."""
+    from kiwi_tui import attention
+
+    launched: list = []
+    monkeypatch.setattr(attention, "launch", launched.append)
+    return launched

kiwi_code-0.0.506/tests/test_attention.py

@@ -0,0 +1,139 @@
+"""Kiwi calls the user back when a question waits for their answer or a run finishes, while
+they are in another window: a desktop notification, the bell, a mark on the tab."""
+from __future__ import annotations
+
+import pytest
+
+from kiwi_tui import attention
+
+GHOSTTY = {"TERM_PROGRAM": "ghostty", "TERM": "xterm-ghostty"}
+
+
+@pytest.mark.parametrize(
+    ("env", "expected"),
+    [
+        (GHOSTTY, "\x1b]777;notify;Kiwi;Pick one, please\x07"),
+        ({"TERM_PROGRAM": "WezTerm"}, "\x1b]777;notify;Kiwi;Pick one, please\x07"),
+        ({"TERM_PROGRAM": "iTerm.app"}, "\x1b]9;Kiwi: Pick one; please\x07"),
+        ({"TERM": "xterm-kitty"}, "\x1b]99;;Kiwi: Pick one; please\x1b\\"),
+        ({**GHOSTTY, "TMUX": "/tmp/tmux-1/default,1,0"}, ""),
+        ({"TERM_PROGRAM": "Apple_Terminal"}, ""),
+        ({}, ""),
+    ],
+)
+def test_each_terminal_gets_the_notification_it_understands(env, expected) -> None:
+    assert attention.notification_sequence("Kiwi", "Pick one; please", env) == expected
+
+
+def test_what_the_agent_wrote_cannot_break_out_of_the_sequence() -> None:
+    seq = attention.notification_sequence("Kiwi", "line one\nline\x07two\x1b]0;evil\x07", GHOSTTY)
+    assert seq == "\x1b]777;notify;Kiwi;line one line two ]0,evil\x07"
+    assert len(attention.notification_sequence("Kiwi", "x" * 500, GHOSTTY)) < 200
+
+
+def test_a_terminal_without_notifications_uses_the_desktops_own_off_ssh(monkeypatch) -> None:
+    monkeypatch.setattr(attention.shutil, "which", lambda name: "/usr/bin/notify-send")
+    assert attention.local_notification_command("Kiwi", "Done", {}, "linux") == [
+        "notify-send", "--app-name=Kiwi", "Kiwi", "Done",
+    ]
+    assert attention.local_notification_command("Kiwi", 'Say "hi"', {}, "darwin") == [
+        "osascript", "-e", 'display notification "Say \\"hi\\"" with title "Kiwi"',
+    ]
+    # Over ssh it would show on the wrong machine.
+    assert attention.local_notification_command("Kiwi", "Done", {"SSH_CONNECTION": "1 2 3 4"}, "linux") is None
+
+
+@pytest.mark.parametrize(("mode", "bell"), [("on", True), ("quiet", False)])
+def test_calling_out_marks_the_tab_rings_as_chosen_and_notifies(mode, bell) -> None:
+    written: list[str] = []
+    attention.call_out(written.append, mode=mode, title="Kiwi", body="Done", tab="✓ kiwi – done", env=GHOSTTY)
+    (out,) = written
+    assert out.startswith("\x1b]2;✓ kiwi – done\x07")
+    # BEL ends the title and the notification too: the bell is a third one.
+    assert out.count("\x07") == (3 if bell else 2)
+    assert out.endswith("\x1b]777;notify;Kiwi;Done\x07")
+
+
+def test_off_does_nothing_and_an_unknown_terminal_uses_the_desktop(no_desktop_notifications, monkeypatch) -> None:
+    written: list[str] = []
+    attention.call_out(written.append, mode="off", title="Kiwi", body="Done", tab="t", env=GHOSTTY)
+    assert written == [] and no_desktop_notifications == []
+
+    monkeypatch.setattr(attention.shutil, "which", lambda name: "/usr/bin/notify-send")
+    monkeypatch.setattr(attention.sys, "platform", "linux")
+    attention.call_out(written.append, mode="on", title="Kiwi", body="Done", tab="t", env={})
+    assert written == ["\x1b]2;t\x07\a"]
+    assert no_desktop_notifications == [["notify-send", "--app-name=Kiwi", "Kiwi", "Done"]]
+
+
+def test_the_mode_is_read_from_the_settings() -> None:
+    assert attention.mode_from({}) == "on"
+    assert attention.mode_from({"notify": "Quiet"}) == "quiet"
+    assert attention.mode_from({"notify": "loud"}) == "on"
+
+
+async def test_the_app_calls_out_only_when_its_window_is_not_in_focus(isolated_home, monkeypatch) -> None:
+    from textual.app import App
+
+    from kiwi_tui.main import AutobotsTUI
+
+    class _KiwiApp(App):
+        call_for_attention = AutobotsTUI.call_for_attention
+        _write_to_terminal = AutobotsTUI._write_to_terminal
+        on_app_focus = AutobotsTUI.on_app_focus
+
+    monkeypatch.setattr(attention, "BASE_TITLE", "kiwi (~/proj)")
+    for key, value in GHOSTTY.items():
+        monkeypatch.setenv(key, value)
+    monkeypatch.delenv("TMUX", raising=False)
+    app = _KiwiApp()
+    async with app.run_test(size=(100, 30)) as pilot:
+        written: list[str] = []
+        app._write_to_terminal = written.append
+        app.app_focus = True
+        assert app.call_for_attention(title="Kiwi", body="Done", tab="✓ kiwi – done") is False
+        assert written == []
+
+        app.app_focus = False
+        assert app.call_for_attention(title="Kiwi", body="Done", tab="✓ kiwi – done") is True
+        assert "\x1b]777;notify;Kiwi;Done\x07" in written[0]
+
+        # Back in kiwi: the tab title is put back.
+        from textual import events
+
+        app.post_message(events.AppFocus())
+        await pilot.pause(0.05)
+        assert written[-1] == "\x1b]2;kiwi (~/proj)\x07"
+
+
+async def test_a_waiting_question_names_itself_and_a_finished_run_its_answer(monkeypatch) -> None:
+    from kiwi_tui.screens.term_dashboard_widgets import TermTurn
+    from tests.test_term_dashboard_ui import _TermDashboardTestApp
+
+    app = _TermDashboardTestApp()
+    async with app.run_test(size=(100, 30), notifications=True) as pilot:
+        await pilot.pause(0.05)
+        screen = app.screen
+        calls: list[dict] = []
+        app.call_for_attention = lambda **kw: calls.append(kw) or True
+        turn = TermTurn(user_text="set it up", assistant_text="")
+        turn.questions = [
+            {"question_id": "q1", "question": "Which database should I use?", "status": "pending"},
+            {"question_id": "q2", "question": "Which port?", "status": "pending"},
+            {"question_id": "q0", "question": "Old one", "status": "answered"},
+        ]
+        screen._turns = [turn]
+
+        screen._call_for_attention("question")
+        screen._call_for_attention("finished", answer="## Done\nAll tests pass.")
+        assert calls == [
+            {"title": "Kiwi needs your answer", "body": "Which database should I use? (+1 more)",
+             "tab": "● kiwi – waiting for you"},
+            {"title": "Kiwi finished", "body": "Done", "tab": "✓ kiwi – done"},
+        ]
+
+        # In kiwi already: a question is pointed out on the screen instead.
+        app.call_for_attention = lambda **kw: False
+        screen._call_for_attention("question")
+        await pilot.pause(0.05)
+        assert any("waiting for your answer" in str(n.message) for n in app._notifications)