ring-cli 0.8.1__tar.gz → 0.10.0__tar.gz

{ring_cli-0.8.1 → ring_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.8.1
+Version: 0.10.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -179,13 +179,6 @@ and sends a system notification right then — **no RiNG board needs to be open*
 after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
 also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
-A second kind of reminder is 🟡 **idle for too long** (`idle_threshold_seconds`, default 2h): once a
-session has sat idle past the threshold, it notifies once. Unlike waiting, idle is time-based — there
-is no event to hang a hook on, so it can only be detected by polling. That means it **fires only while
-`ring watch` or a TUI is open** (and when both are open, only one of them fires it, never twice). Close
-every board and idle reminders go silent — waiting still rings you, since that path runs off the hook.
-This is a deliberate trade-off: idle is a secondary signal, not worth a resident background process.
-
 For clickable notifications on macOS, install `terminal-notifier`:
 
 ```sh
@@ -343,8 +336,14 @@ RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on ma
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
 Config keys include `notify_sound`, `notify_sound_name`, `notify_ignore_dnd`,
-`notify_repeat_seconds`, `notify_repeat_max`, and `notify_backend`. Custom notification channels
-can be added by registering another `Notifier`.
+`notify_repeat_seconds`, `notify_repeat_max`, `notify_backend`, and `waiting_cooldown_seconds`.
+Custom notification channels can be added by registering another `Notifier`.
+
+Background subagent permission requests can make a session flap between waiting and working in
+quick succession. `waiting_cooldown_seconds` (180s by default) stops `ring hook`'s system
+notification and the TUI's bell/reminder from firing again the instant a session re-enters waiting
+within the cooldown window of its last alert; set it to `0` to disable the cooldown (alert on
+every re-entry, the old behavior).
 
 `agent-hooks` is an optional external hook helper / decision UI. If it is installed and
 `notify_backend = "agent-hooks"`, `ring hook` still writes RiNG registry state, then passes the
@@ -373,13 +372,13 @@ legend = true
 active_window_seconds = 21600
 working_threshold_seconds = 90
 waiting_window_seconds = 1800
-idle_threshold_seconds = 7200    # 🟡 remind once idle for this long (default 2h; 0 = off)
 notify_sound = true
 notify_sound_name = "Glass"
 notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
+waiting_cooldown_seconds = 180   # suppress an immediate re-alert on re-entering waiting within this window; 0 = off
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]

{ring_cli-0.8.1 → ring_cli-0.10.0}/README.en.md

@@ -154,13 +154,6 @@ and sends a system notification right then — **no RiNG board needs to be open*
 after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
 also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
-A second kind of reminder is 🟡 **idle for too long** (`idle_threshold_seconds`, default 2h): once a
-session has sat idle past the threshold, it notifies once. Unlike waiting, idle is time-based — there
-is no event to hang a hook on, so it can only be detected by polling. That means it **fires only while
-`ring watch` or a TUI is open** (and when both are open, only one of them fires it, never twice). Close
-every board and idle reminders go silent — waiting still rings you, since that path runs off the hook.
-This is a deliberate trade-off: idle is a secondary signal, not worth a resident background process.
-
 For clickable notifications on macOS, install `terminal-notifier`:
 
 ```sh
@@ -318,8 +311,14 @@ RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on ma
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
 Config keys include `notify_sound`, `notify_sound_name`, `notify_ignore_dnd`,
-`notify_repeat_seconds`, `notify_repeat_max`, and `notify_backend`. Custom notification channels
-can be added by registering another `Notifier`.
+`notify_repeat_seconds`, `notify_repeat_max`, `notify_backend`, and `waiting_cooldown_seconds`.
+Custom notification channels can be added by registering another `Notifier`.
+
+Background subagent permission requests can make a session flap between waiting and working in
+quick succession. `waiting_cooldown_seconds` (180s by default) stops `ring hook`'s system
+notification and the TUI's bell/reminder from firing again the instant a session re-enters waiting
+within the cooldown window of its last alert; set it to `0` to disable the cooldown (alert on
+every re-entry, the old behavior).
 
 `agent-hooks` is an optional external hook helper / decision UI. If it is installed and
 `notify_backend = "agent-hooks"`, `ring hook` still writes RiNG registry state, then passes the
@@ -348,13 +347,13 @@ legend = true
 active_window_seconds = 21600
 working_threshold_seconds = 90
 waiting_window_seconds = 1800
-idle_threshold_seconds = 7200    # 🟡 remind once idle for this long (default 2h; 0 = off)
 notify_sound = true
 notify_sound_name = "Glass"
 notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
+waiting_cooldown_seconds = 180   # suppress an immediate re-alert on re-entering waiting within this window; 0 = off
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]

{ring_cli-0.8.1 → ring_cli-0.10.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.8.1"
+version = "0.10.0"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"

{ring_cli-0.8.1 → ring_cli-0.10.0}/src/ring/cli.py

@@ -33,12 +33,10 @@ from ring.config import get_config as get_config
 from ring.config import set_value as set_value
 from ring.i18n import gettext as _
 from ring.i18n import ngettext, set_lang
-from ring.ipc import read_tui_presence
 from ring.labels import load_labels
 from ring.plugins import load_plugins
 from ring.registry import Session, Status, running_agent_pids
 from ring.sources import discover_sessions
-from ring.watcher import IdleAlertScheduler
 
 try:
     from rich.box import SIMPLE_HEAD
@@ -402,33 +400,15 @@ def run_config(args: list[str]) -> int:
 
 
 def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int:
-    # 🔴 等你的通知由 ``ring hook`` 在 session 轉態的當下就地發出（見 hook._ring_waiting_now），
-    # 這樣關掉看板也照樣 ring 你；watch 迴圈額外負責輪詢發 🟡 閒置提醒——
-    # 閒置是時間累積出來的，沒有事件可掛，只能靠輪詢偵測。
+    # 系統通知由 ``ring hook`` 在 session 轉 🔴 等你的當下就地發出（見 hook._ring_waiting_now）；
+    # watch 只負責顯示看板，不再輪詢發通知——這樣關掉看板也照樣 ring 你。
     frames = 0
     footer_text = _("每 {interval}s 刷新 · Ctrl-C 離場", interval=int(interval))
-    idle_alerts = IdleAlertScheduler(get_config().idle_threshold_seconds)
-
-    def _notify_idle_alerts(sessions: list[Session]) -> None:
-        # scheduler 照常 feed 讓狀態持續前進；但若 TUI（ring tui）也開著，
-        # 就讓它去發、watch 這邊不重複發系統通知——否則同一 session 會被兩個行程各響一次。
-        # 已標記為 due 的 session 在這裡仍算「提醒過」，所以 TUI 關掉後 watch 不會補發。
-        alerts = idle_alerts.feed(sessions)
-        if not alerts or read_tui_presence() is not None:
-            return
-        try:
-            from ring.notify import notify_idle
-
-            notify_idle(alerts)
-        except Exception:
-            pass
-
     if not HAVE_RICH:
         try:
             while True:
                 sys.stdout.write("\033[2J\033[H")
                 sessions = board(show_all)
-                _notify_idle_alerts(sessions)
                 print(_render_plain(sessions, show_legend, show_tool_column(sessions)))
                 print(f"\n{footer_text}")
                 sys.stdout.flush()
@@ -444,7 +424,6 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
         with Live(console=console, screen=True, auto_refresh=False) as live:
             while True:
                 sessions = board(show_all)
-                _notify_idle_alerts(sessions)
                 body = _rich_renderable(sessions, show_legend, show_tool_column(sessions))
                 live.update(Group(body, Text(f"\n{footer_text}", style=_MUTED)), refresh=True)
                 frames += 1

{ring_cli-0.8.1 → ring_cli-0.10.0}/src/ring/config.py

@@ -9,7 +9,6 @@
     active_window_seconds = 21600     # 只看最近這段時間動過的 session（預設 6h）
     working_threshold_seconds = 90    # 多久沒動就從 🟢 工作中 變 🟡 閒置
     waiting_window_seconds = 1800     # 跑完停著升等你的時間窗上限（預設 30 分）
-    idle_threshold_seconds = 7200     # 🟡 閒置多久後提醒一次（預設 2h；0 = 關閉）
     notify_sound = true               # 系統通知帶聲音
     notify_sound_name = "Glass"       # macOS / terminal-notifier sound name
     notify_ignore_dnd = false         # terminal-notifier 是否加 -ignoreDnD（穿透勿擾 / Focus）
@@ -21,6 +20,8 @@
                                       #   "none" = 完全不發通知（RiNG 當純看板）
     notify_repeat_seconds = [30, 120, 300]  # 持續等你時，多久後重複提醒
     notify_repeat_max = 3             # 重複提醒上限；0 = 不限
+    waiting_cooldown_seconds = 180    # session 離開 WAITING 又轉回時，距上次提醒未滿這段時間就
+                                      #   不再當「新轉入」立即提醒（防翻轉轟炸）；0 = 關閉（現行為）
     notify_ntfy_url = "https://ntfy.sh/my-topic"   # 設了才啟用 ntfy 後端（推到手機）
     notify_webhook_url = "https://example.com/hook"  # 設了才啟用 webhook 後端（JSON POST）
     notify_also = ["ntfy"]            # 主後端之外「加發」的後端（例如桌面通知＋手機各一份）
@@ -59,7 +60,6 @@ class Config:
     active_window_seconds: int = 6 * 60 * 60
     working_threshold_seconds: int = 90
     waiting_window_seconds: int = 1800  # 跑完停著升等你的時間窗上限（預設 30 分）
-    idle_threshold_seconds: int = 2 * 60 * 60  # 🟡 閒置多久後提醒一次；0 = 關閉
     notify_sound: bool = True
     notify_sound_name: str = "Glass"
     notify_ignore_dnd: bool = False
@@ -71,6 +71,7 @@ class Config:
     notify_backend: str = "auto"
     notify_repeat_seconds: tuple[int, ...] = (30, 120, 300)
     notify_repeat_max: int = 3  # 0 = 不限
+    waiting_cooldown_seconds: int = 180  # 離開 WAITING 又轉回時的提醒冷卻期；0 = 關閉（現行為）
     notify_ntfy_url: str = ""  # 完整 ntfy topic URL；空＝ntfy 後端不可用
     notify_webhook_url: str = ""  # webhook URL；空＝webhook 後端不可用
     notify_also: tuple[str, ...] = ()  # 主後端之外加發的後端名（如 ["ntfy"]）
@@ -133,7 +134,6 @@ def load(path: Path | None = None) -> Config:
         active_window_seconds=_as_int(raw.get("active_window_seconds"), d.active_window_seconds),
         working_threshold_seconds=_as_int(raw.get("working_threshold_seconds"), d.working_threshold_seconds),
         waiting_window_seconds=_as_int(raw.get("waiting_window_seconds"), d.waiting_window_seconds),
-        idle_threshold_seconds=max(0, _as_int(raw.get("idle_threshold_seconds"), d.idle_threshold_seconds)),
         notify_sound=_as_bool(raw.get("notify_sound"), d.notify_sound),
         notify_sound_name=(
             raw["notify_sound_name"] if isinstance(raw.get("notify_sound_name"), str) else d.notify_sound_name
@@ -141,6 +141,7 @@ def load(path: Path | None = None) -> Config:
         notify_ignore_dnd=_as_bool(raw.get("notify_ignore_dnd"), d.notify_ignore_dnd),
         notify_repeat_seconds=_as_positive_int_tuple(raw.get("notify_repeat_seconds"), d.notify_repeat_seconds),
         notify_repeat_max=max(0, _as_int(raw.get("notify_repeat_max"), d.notify_repeat_max)),
+        waiting_cooldown_seconds=max(0, _as_int(raw.get("waiting_cooldown_seconds"), d.waiting_cooldown_seconds)),
         notify_backend=notify_backend,
         notify_ntfy_url=(raw["notify_ntfy_url"] if isinstance(raw.get("notify_ntfy_url"), str) else ""),
         notify_webhook_url=(raw["notify_webhook_url"] if isinstance(raw.get("notify_webhook_url"), str) else ""),
@@ -205,13 +206,13 @@ _SETTERS: dict[str, Callable[[str], object]] = {
     "active_window_seconds": _coerce_int,
     "working_threshold_seconds": _coerce_int,
     "waiting_window_seconds": _coerce_int,
-    "idle_threshold_seconds": _coerce_int,
     "notify_sound": _coerce_bool,
     "notify_sound_name": str,
     "notify_ignore_dnd": _coerce_bool,
     "notify_backend": str,
     "notify_repeat_seconds": _coerce_int_list,
     "notify_repeat_max": _coerce_int,
+    "waiting_cooldown_seconds": _coerce_int,
     "notify_ntfy_url": str,
     "notify_webhook_url": str,
     "notify_also": _coerce_str_list,

{ring_cli-0.8.1 → ring_cli-0.10.0}/src/ring/hook.py

@@ -169,7 +169,8 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
 
     unhide_session(event.session_id)
     path = RING_REGISTRY / f"{quote(event.session_id, safe=':')}.json"
-    prev_status = _previous_status(path)
+    prev_row = _previous_row(path)
+    prev_status = str(prev_row["status"]) if "status" in prev_row else None
     if event.status is Status.ENDED:
         path.unlink(missing_ok=True)  # 乾淨離場：直接消失
         if prev_status is not None and prev_status != Status.ENDED.value:
@@ -213,6 +214,19 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
     if tty:
         payload["tty"] = tty
 
+    # waiting 通知冷卻（防翻轉轟炸）：hook 是短命 process，冷卻狀態持久化在 registry row
+    # 的 waiting_notified_at（上次 waiting 通知的 epoch 時間戳）。離開 WAITING 也要把時間戳
+    # 帶進新 row（payload 每次重建，不帶會遺失），快速翻回 WAITING 時才判得出「還在冷卻期」。
+    # 舊 row 沒這欄位 = 從未通知過 → 照發。並發寫沿用既有 tmp+replace 的 last-write-wins。
+    last_notified = _as_epoch(prev_row.get("waiting_notified_at"))
+    if last_notified is not None:
+        payload["waiting_notified_at"] = last_notified
+    should_ring = False
+    if event.status is Status.WAITING:
+        should_ring = _waiting_ring_allowed(last_notified, now)
+        if should_ring:
+            payload["waiting_notified_at"] = now
+
     RING_REGISTRY.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(".json.tmp")
     tmp.write_text(json.dumps(payload))
@@ -221,17 +235,35 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
     if prev_status != event.status.value:
         log_transition(event.session_id, event.provider, event.cwd, event.status.value)
 
-    if event.status is Status.WAITING:
+    if should_ring:
         _ring_waiting_now(event, payload, last_action)
 
 
-def _previous_status(path: Path) -> str | None:
-    """讀 registry 檔目前的狀態值（給轉換偵測用）；沒檔 / 壞檔回 None。"""
+def _previous_row(path: Path) -> dict[str, Any]:
+    """讀 registry 檔目前的內容（給轉換偵測與通知冷卻用）；沒檔 / 壞檔回空 dict。"""
     try:
         data = json.loads(path.read_text())
-        return str(data["status"])
+        return data if isinstance(data, dict) else {}
     except Exception:
-        return None
+        return {}
+
+
+def _as_epoch(v: Any) -> float | None:
+    """把 row 欄位值安全轉成 epoch float；缺欄位 / 型別不對回 None（視為從未通知）。"""
+    return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
+
+
+def _waiting_ring_allowed(last_notified: float | None, now: float) -> bool:
+    """hook 的 waiting 通知是否放行：距上次通知未滿 ``waiting_cooldown_seconds`` 就不發。
+
+    背景 subagent 的權限請求會讓 session 以 30 秒～2 分鐘頻率在 working↔waiting 間翻轉，
+    每次轉入都發一則系統通知會轟炸使用者。cooldown=0 = 關閉（維持現行為：每次轉入都發）；
+    從未通知過（``last_notified`` 為 None，含舊版 row 沒有該欄位）一律放行。
+    """
+    cooldown = get_config().waiting_cooldown_seconds
+    if cooldown <= 0 or last_notified is None:
+        return True
+    return now - last_notified >= cooldown
 
 
 def _ring_waiting_now(event: Any, payload: dict[str, Any], last_action: str) -> None:

{ring_cli-0.8.1 → ring_cli-0.10.0}/src/ring/locale/en/LC_MESSAGES/ring.po

@@ -124,9 +124,6 @@ msgstr "↑/↓ to select, Enter or Space to jump to its terminal"
 msgid "🔔 {names} 在等你回話"
 msgstr "🔔 {names} waiting for your reply"
 
-msgid "🟡 {names} 已閒置"
-msgstr "🟡 {names} has gone idle"
-
 msgid "（沒有選到 session）"
 msgstr "(no session selected)"
 
@@ -198,15 +195,9 @@ msgid "✅ 已移除 RiNG hooks（{events}）從 {path}"
 msgstr "✅ Removed RiNG hooks ({events}) from {path}"
 
 # ── notify 文案明確化 ──
-msgid "RiNG · {project} 已閒置"
-msgstr "RiNG · {project} has gone idle"
-
 msgid "RiNG · {project} 在等你回話"
 msgstr "RiNG · {project} is waiting for you"
 
-msgid "已閒置 {duration}"
-msgstr "Idle for {duration}"
-
 msgid "{project} · …/{tail}"
 msgstr "{project} · …/{tail}"