ring-cli 0.11.3__tar.gz → 0.12.0__tar.gz

ring_cli-0.11.3/README.en.md → ring_cli-0.12.0/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: ring-cli
+Version: 0.12.0
+Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
+Keywords: claude-code,codex,ollama,llama-cpp,tui,dashboard,session,monitor,rich
+Author: Wei Lee
+Author-email: Wei Lee <weilee.rx@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Dist: rich>=13
+Requires-Dist: textual>=0.80 ; extra == 'tui'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/Lee-W/ring
+Project-URL: Repository, https://github.com/Lee-W/ring
+Provides-Extra: tui
+Description-Content-Type: text/markdown
+
 # RiNG 🎤
 
 [台灣漢語](https://github.com/Lee-W/ring/blob/main/README.md) · **English**
@@ -243,11 +268,18 @@ RiNG collects sessions from registered sources. Built-ins:
 |--------|------------|-----------|
 | **Claude Code zero-config** | `~/.claude/projects/**/*.jsonl`, mtimes, and `cwd` fields | no setup; detects recent activity and turn completion. Precise user-action prompts require hooks |
 | **Codex zero-config** | `~/.codex/state_5.sqlite`, rollout JSONL, and live `codex` processes | no setup; detects live / ended / turn completion. Use hooks for precise jumps when multiple sessions share a cwd |
+| **Ollama zero-config** | interactive `ollama run` processes with a controlling terminal | process-liveness only; shows cwd, TTY, and model, and excludes `ollama serve` |
+| **llama.cpp zero-config** | interactive `llama-cli` processes with a controlling terminal | process-liveness only; shows cwd, TTY, and model, and excludes `llama-server` |
 | **hook registry** | `~/.config/ring/sessions/`, written by `ring hook` | precise: 🔴 waiting / 🟢 working / 🟡 idle / ⚫ ended |
 
 Zero-config needs no setup. For precise “who needs me”, install hooks so provider events feed the RiNG registry.
 RiNG includes installers for Claude Code and Codex; other tools can use the provider-neutral `ring hook` protocol.
 
+Ollama and llama.cpp do not expose a session transcript or interaction hooks that RiNG can read, so their
+zero-config rows stay 🟡: the row means the interactive CLI is alive, not that RiNG can distinguish generation
+from waiting for the next prompt. The row disappears when the CLI exits. An outer agent that can emit lifecycle
+events can use the provider-neutral hook protocol for precise states.
+
 ## States
 
 RiNG reduces every session to four user-facing states. 🔴 waiting is sorted first.
@@ -294,7 +326,9 @@ Claude Code events:
 | `PermissionRequest` / `PreToolUse` with `AskUserQuestion` | 🔴 waiting |
 | `SessionEnd` | removed from the board |
 
-Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`.
+Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`. Codex
+also emits `PermissionRequest` before an existing policy auto-approves the call; a bare event therefore stays
+🟢 working, and it only turns 🔴 waiting when the payload explicitly carries `requires_action` / `waiting_for`.
 
 Verify that hooks are writing:
 
@@ -404,7 +438,7 @@ RiNG is not tied to a specific tool or terminal.
 
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
-| `SessionSource` | find sessions | Claude Code, Codex, hook registry |
+| `SessionSource` | find sessions | Claude Code, Codex, Ollama, llama.cpp, hook registry |
 | `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
 | `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 

ring_cli-0.11.3/PKG-INFO → ring_cli-0.12.0/README.en.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: ring-cli
-Version: 0.11.3
-Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
-Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
-Author: Wei Lee
-Author-email: Wei Lee <weilee.rx@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development
-Classifier: Topic :: Utilities
-Requires-Dist: rich>=13
-Requires-Dist: textual>=0.80 ; extra == 'tui'
-Requires-Python: >=3.13
-Project-URL: Homepage, https://github.com/Lee-W/ring
-Project-URL: Repository, https://github.com/Lee-W/ring
-Provides-Extra: tui
-Description-Content-Type: text/markdown
-
 # RiNG 🎤
 
 [台灣漢語](https://github.com/Lee-W/ring/blob/main/README.md) · **English**
@@ -268,11 +243,18 @@ RiNG collects sessions from registered sources. Built-ins:
 |--------|------------|-----------|
 | **Claude Code zero-config** | `~/.claude/projects/**/*.jsonl`, mtimes, and `cwd` fields | no setup; detects recent activity and turn completion. Precise user-action prompts require hooks |
 | **Codex zero-config** | `~/.codex/state_5.sqlite`, rollout JSONL, and live `codex` processes | no setup; detects live / ended / turn completion. Use hooks for precise jumps when multiple sessions share a cwd |
+| **Ollama zero-config** | interactive `ollama run` processes with a controlling terminal | process-liveness only; shows cwd, TTY, and model, and excludes `ollama serve` |
+| **llama.cpp zero-config** | interactive `llama-cli` processes with a controlling terminal | process-liveness only; shows cwd, TTY, and model, and excludes `llama-server` |
 | **hook registry** | `~/.config/ring/sessions/`, written by `ring hook` | precise: 🔴 waiting / 🟢 working / 🟡 idle / ⚫ ended |
 
 Zero-config needs no setup. For precise “who needs me”, install hooks so provider events feed the RiNG registry.
 RiNG includes installers for Claude Code and Codex; other tools can use the provider-neutral `ring hook` protocol.
 
+Ollama and llama.cpp do not expose a session transcript or interaction hooks that RiNG can read, so their
+zero-config rows stay 🟡: the row means the interactive CLI is alive, not that RiNG can distinguish generation
+from waiting for the next prompt. The row disappears when the CLI exits. An outer agent that can emit lifecycle
+events can use the provider-neutral hook protocol for precise states.
+
 ## States
 
 RiNG reduces every session to four user-facing states. 🔴 waiting is sorted first.
@@ -319,7 +301,9 @@ Claude Code events:
 | `PermissionRequest` / `PreToolUse` with `AskUserQuestion` | 🔴 waiting |
 | `SessionEnd` | removed from the board |
 
-Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`.
+Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`. Codex
+also emits `PermissionRequest` before an existing policy auto-approves the call; a bare event therefore stays
+🟢 working, and it only turns 🔴 waiting when the payload explicitly carries `requires_action` / `waiting_for`.
 
 Verify that hooks are writing:
 
@@ -429,7 +413,7 @@ RiNG is not tied to a specific tool or terminal.
 
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
-| `SessionSource` | find sessions | Claude Code, Codex, hook registry |
+| `SessionSource` | find sessions | Claude Code, Codex, Ollama, llama.cpp, hook registry |
 | `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
 | `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 

{ring_cli-0.11.3 → ring_cli-0.12.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.11.3"
+version = "0.12.0"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"
@@ -12,6 +12,8 @@ authors = [{ name = "Wei Lee", email = "weilee.rx@gmail.com" }]
 keywords = [
   "claude-code",
   "codex",
+  "ollama",
+  "llama-cpp",
   "tui",
   "dashboard",
   "session",

{ring_cli-0.11.3 → ring_cli-0.12.0}/src/ring/config.py

@@ -27,6 +27,10 @@
     notify_also = ["ntfy"]            # 主後端之外「加發」的後端（例如桌面通知＋手機各一份）
     focusers = ["Neovim", "tmux", "iTerm2", "Terminal", "linux-wm"]  # 跳轉嘗試順序；省略＝內建預設
     plugins = ["my_ring_plugin"]      # 啟動時 import 的外部 plugin 模組（自行 register_*）
+    debug_payload_log = false         # 診斷用：記錄 hook 收到的原始 payload
+                                      #   （見 payload_log.py，寫到 ~/.config/ring/hook_payloads.jsonl）；
+                                      #   預設關閉，payload 可能含使用者輸入才要開；
+                                      #   環境變數 RING_DEBUG_PAYLOAD_LOG 可覆寫（優先於本鍵）
 """
 
 from __future__ import annotations
@@ -77,6 +81,7 @@ class Config:
     notify_also: tuple[str, ...] = ()  # 主後端之外加發的後端名（如 ["ntfy"]）
     focusers: tuple[str, ...] = ()  # 空＝用內建預設順序
     plugins: tuple[str, ...] = ()  # 啟動時 import 的外部 plugin 模組（entry point 之外的本機路）
+    debug_payload_log: bool = False  # 診斷用：記錄 hook 收到的原始 payload；預設關閉
     colors: dict[str, str] = field(default_factory=lambda: dict(_DEFAULT_COLORS))
 
 
@@ -148,6 +153,7 @@ def load(path: Path | None = None) -> Config:
         notify_also=_as_str_tuple(raw.get("notify_also")),
         focusers=_as_str_tuple(raw.get("focusers")),
         plugins=_as_str_tuple(raw.get("plugins")),
+        debug_payload_log=_as_bool(raw.get("debug_payload_log"), d.debug_payload_log),
         colors=_parse_colors(raw.get("colors")),
     )
 
@@ -218,6 +224,7 @@ _SETTERS: dict[str, Callable[[str], object]] = {
     "notify_also": _coerce_str_list,
     "focusers": _coerce_str_list,
     "plugins": _coerce_str_list,
+    "debug_payload_log": _coerce_bool,
 }
 
 

{ring_cli-0.11.3 → ring_cli-0.12.0}/src/ring/hook.py

@@ -31,6 +31,7 @@ from ring.config import get_config
 from ring.hook_protocol import HOOK_EVENTS, adapter_for, provider_from_payload
 from ring.i18n import gettext as _
 from ring.i18n import set_lang
+from ring.payload_log import maybe_log_raw_payload
 from ring.registry import (
     RING_REGISTRY,
     Session,
@@ -44,8 +45,9 @@ from ring.transcript import _extract_todo, _latest_action, _tail_records
 _HOOK_EVENTS = list(HOOK_EVENTS)
 
 # Codex 的 hooks.json 用跟 Claude 同樣的 PascalCase 事件名，但只支援其中一小撮。
-# 保守取有實證可用的：PermissionRequest（→ 🔴 等核可）、PreToolUse（→ 動作/清除）、
-# Stop（→ 🟡 回合結束、清掉 waiting）。多裝 Codex 不認的事件有風險，故不照搬 Claude 全套。
+# 保守取有實證可用的：PermissionRequest（裸事件只代表權限準備判定；明確需互動才 → 🔴）、
+# PreToolUse（→ 動作/清除）、Stop（→ 🟡 回合結束、清掉 waiting）。多裝 Codex 不認的事件
+# 有風險，故不照搬 Claude 全套。
 _CODEX_HOOK_EVENTS = ["PreToolUse", "PermissionRequest", "Stop"]
 
 # hook command 的 timeout（秒）。給足，因為 notify_backend="agent-hooks" 時權限 modal 會
@@ -156,6 +158,9 @@ def run_hook(provider: str = "claude-code") -> int:
         return 0
 
     selected_provider = provider_from_payload(data, fallback=provider)
+    # 取證 log：診斷用、預設關閉（見 payload_log.py）。故意放在任何狀態判定/改寫之前，
+    # 記下 hook 實際收到的原始資料——不影響、不參與下面的正規化流程。
+    maybe_log_raw_payload(selected_provider, data)
     _record_session_state(data, selected_provider)
     return _delegate_to_agent_hooks(raw, selected_provider)
 

{ring_cli-0.11.3 → ring_cli-0.12.0}/src/ring/hook_protocol.py

@@ -105,6 +105,13 @@ class CommonHookAdapter:
             status = Status.WORKING
         elif explicit_requires_action is not None:
             status = Status.WAITING if explicit_requires_action else Status.IDLE
+        elif event == "PermissionRequest" and self.provider == "codex":
+            # Codex 會在權限「準備判定」時送 PermissionRequest；即使既有 policy
+            # 隨後自動放行、畫面從未停下來等人，也會經過這個 hook。裸事件因此只能
+            # 證明 agent 還在處理工具呼叫，不能當成使用者需要回應。若 payload 有
+            # requires_action / waiting_for 等明確訊號，已由上面的分支判成 WAITING；
+            # 明確的 requires_action=false 也在上面判成 IDLE，不會落到這裡的 WORKING。
+            status = Status.WORKING
         elif event == "Notification":
             status = Status.WAITING if _is_action_required_notification(data) else Status.IDLE
         elif event == "PreToolUse":

ring_cli-0.12.0/src/ring/payload_log.py

@@ -0,0 +1,110 @@
+"""原始 hook payload 取證 logger——診斷用，預設關閉。
+
+診斷「claude-code 裸 PermissionRequest 被誤判 WAITING」與「codex 裸 PermissionRequest
+永遠判 WORKING」這類問題時，需要看到 hook 實際收到的原始 event payload——現有的
+registry（``~/.config/ring/sessions/*.json``）與 ``events.jsonl`` 都只留正規化後的
+status，原始資料在 ``hook_protocol.normalize`` 跑完就遺失了。
+
+這支 logger 在 hook 收到 stdin 的當下、任何狀態判定/改寫之前，把原始 payload 整段
+append 一行，供事後分析用。設計原則跟 ``stats.log_transition`` 一致：
+
+- append-only、JSONL，一行一事件
+- 檔案超過上限自動砍半保新，不無限成長
+- 任何錯誤（含讀 config 失敗、payload 無法序列化）一律安靜吞掉，絕不影響 hook 主流程
+
+開關：``debug_payload_log`` config 鍵，或環境變數 ``RING_DEBUG_PAYLOAD_LOG``
+（``1``/``true``/``yes``/``on`` 開，``0``/``false``/``no``/``off`` 關；env 優先於 config）。
+**預設關閉**——payload 可能含使用者輸入/檔案內容，開了才寫。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+PAYLOAD_LOG_PATH = Path.home() / ".config" / "ring" / "hook_payloads.jsonl"
+
+# log 檔上限；超過就砍半保新（append 前檢查）。原始 payload 比 events.jsonl 的轉換記錄
+# 大很多（可能含完整 tool_input／transcript 片段），給足空間再砍半。
+_MAX_BYTES = 20 * 1024 * 1024
+
+_ENV_FLAG = "RING_DEBUG_PAYLOAD_LOG"
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def payload_log_enabled() -> bool:
+    """是否要記原始 payload：env var 優先，其次 config 鍵，預設關閉。"""
+    env = os.environ.get(_ENV_FLAG, "").strip().lower()
+    if env in _TRUE:
+        return True
+    if env in _FALSE:
+        return False
+    try:
+        from ring.config import get_config
+
+        return get_config().debug_payload_log
+    except Exception:
+        return False
+
+
+def _raw_event_name(data: Mapping[str, Any]) -> str:
+    """從原始 payload 猜事件名（只為了記錄好讀，不影響任何判定邏輯）。"""
+    for key in ("event", "event_name", "hook_event_name", "hookEventName"):
+        v = data.get(key)
+        if isinstance(v, str) and v:
+            return v
+    return ""
+
+
+def maybe_log_raw_payload(
+    provider: str,
+    data: Mapping[str, Any],
+    *,
+    path: Path | None = None,
+    now: float | None = None,
+) -> None:
+    """開關開啟時，把 hook 收到的原始 payload 整段 append 一行（診斷用）。
+
+    呼叫端應放在 hook 處理最前端，早於 ``hook_protocol`` 的任何狀態判定/改寫。
+    開關預設關閉（見模組 docstring）；任何錯誤一律安靜吞掉，呼叫端不需要自己包 try。
+    """
+    try:
+        if not payload_log_enabled():
+            return
+        p = path or PAYLOAD_LOG_PATH
+        line = json.dumps(
+            {
+                "ts": now if now is not None else time.time(),
+                "provider": provider,
+                "event": _raw_event_name(data),
+                "payload": data,
+            },
+            ensure_ascii=False,
+            default=str,
+        )
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _trim_if_oversized(p)
+        with p.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        pass
+
+
+def _trim_if_oversized(p: Path) -> None:
+    """log 超過 ``_MAX_BYTES`` 時砍半保新，避免無上限成長。失敗安靜放棄（不擋 append）。"""
+    try:
+        if p.stat().st_size <= _MAX_BYTES:
+            return
+        lines = p.read_text(encoding="utf-8").splitlines()
+        keep = lines[len(lines) // 2 :]
+        tmp = p.with_suffix(".jsonl.tmp")
+        tmp.write_text("\n".join(keep) + "\n", encoding="utf-8")
+        tmp.replace(p)  # atomic
+    except Exception:
+        pass

{ring_cli-0.11.3 → ring_cli-0.12.0}/src/ring/registry.py

@@ -872,7 +872,10 @@ def running_agent_pids() -> list[int]:
     顯示用途，不是存活判定；真正的 ENDED 判定路徑（``_hook_sessions``）用的是
     未攤平的 ``running_claude_pids`` / ``running_codex_pids`` 原始回傳值。
     """
-    return [*(running_claude_pids() or []), *(running_codex_pids() or [])]
+    # 延後 import，避免 registry（Session model）與 sources package 初始化時循環相依。
+    from ring.sources.local_llm import running_pids as running_local_llm_pids
+
+    return [*(running_claude_pids() or []), *(running_codex_pids() or []), *running_local_llm_pids()]
 
 
 def _pids_cwd(pids: list[int]) -> dict[int, str] | None:

{ring_cli-0.11.3 → ring_cli-0.12.0}/src/ring/sources/__init__.py

@@ -13,9 +13,11 @@ from ring.sources.base import SessionSource
 from ring.sources.claude_code import source as _claude_code
 from ring.sources.codex import source as _codex
 from ring.sources.hook_registry import source as _hook_registry
+from ring.sources.local_llm import llama_cpp_source as _llama_cpp
+from ring.sources.local_llm import ollama_source as _ollama
 
 # 註冊表（順序＝彙整順序）。hook registry 先於 zero-config source，精準事件優先。
-_SOURCES: list[SessionSource] = [_hook_registry, _claude_code, _codex]
+_SOURCES: list[SessionSource] = [_hook_registry, _claude_code, _codex, _ollama, _llama_cpp]
 
 
 def register_source(source: SessionSource, *, first: bool = False) -> None:

ring_cli-0.12.0/src/ring/sources/local_llm.py

@@ -0,0 +1,157 @@
+"""Ollama 與 llama.cpp 互動式 CLI 的 zero-config 行程來源。
+
+兩者都沒有可供 RiNG 讀取的 session transcript；這個來源因此只承諾行程層級的
+存活資訊。只收有控制終端的 ``ollama run`` / ``llama-cli``，刻意排除長駐 API
+server，避免把基礎設施誤當成「需要使用者回去處理」的 session。
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from dataclasses import dataclass
+
+import ring.registry as registry
+from ring.registry import Session, Status
+
+_CACHE_TTL = 1.0
+
+
+@dataclass(frozen=True)
+class LocalLLMProcess:
+    pid: int
+    provider: str
+    cwd: str
+    tty: str
+    started_at: float
+    model: str
+
+
+_process_cache: tuple[float, list[LocalLLMProcess] | None] = (-1.0, [])
+
+
+def _elapsed_seconds(value: str) -> int | None:
+    """解析 ps ``etime``（``[[dd-]hh:]mm:ss``）。"""
+    try:
+        day_part, clock = value.split("-", 1) if "-" in value else ("0", value)
+        fields = [int(part) for part in clock.split(":")]
+        if len(fields) == 2:
+            hours, minutes, seconds = 0, fields[0], fields[1]
+        elif len(fields) == 3:
+            hours, minutes, seconds = fields
+        else:
+            return None
+        return int(day_part) * 86400 + hours * 3600 + minutes * 60 + seconds
+    except ValueError:
+        return None
+
+
+def _command_tokens(comm: str, args: str) -> tuple[str, list[str]]:
+    """找出實際 executable 與其後參數；ps args 不保證保留 shell quoting。"""
+    tokens = args.split()
+    executable = os.path.basename(comm.strip())
+    for index, token in enumerate(tokens):
+        if os.path.basename(token) == executable:
+            return executable, tokens[index + 1 :]
+    return executable, tokens[1:] if tokens else []
+
+
+def _classify(comm: str, args: str) -> tuple[str, str] | None:
+    executable, argv = _command_tokens(comm, args)
+    if executable == "ollama":
+        if len(argv) < 2 or argv[0] != "run":
+            return None
+        return "ollama", argv[1]
+    if executable == "llama-cli":
+        model_flags = {"-m", "--model", "-hf", "-hfr", "--hf-repo", "-mu", "--model-url"}
+        for index, token in enumerate(argv[:-1]):
+            if token in model_flags:
+                return "llama.cpp", argv[index + 1]
+        return "llama.cpp", "llama-cli"
+    return None
+
+
+def _scan_processes() -> list[LocalLLMProcess] | None:
+    """一次 ps + 一次批次 lsof 找出兩種本機互動 CLI；失敗以 ``None`` 表示未知。"""
+    global _process_cache
+    monotonic_now = time.monotonic()
+    if 0 <= monotonic_now - _process_cache[0] <= _CACHE_TTL:
+        return _process_cache[1]
+
+    try:
+        result = subprocess.run(
+            ["ps", "-Ao", "pid=,tty=,etime=,comm=,args="],
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+
+    now = time.time()
+    candidates: list[tuple[int, str, float, str, str]] = []
+    for line in result.stdout.splitlines():
+        parts = line.split(None, 4)
+        if len(parts) < 4:
+            continue
+        tty = registry._normalize_tty(parts[1])
+        if not tty:
+            continue
+        classified = _classify(parts[3], parts[4] if len(parts) == 5 else "")
+        elapsed = _elapsed_seconds(parts[2])
+        if classified is None or elapsed is None:
+            continue
+        try:
+            pid = int(parts[0])
+        except ValueError:
+            continue
+        provider, model = classified
+        candidates.append((pid, tty, now - elapsed, provider, model))
+
+    cwd_by_pid = registry._pids_cwd([pid for pid, *_rest in candidates])
+    if cwd_by_pid is None:
+        return None
+    processes = [
+        LocalLLMProcess(pid, provider, cwd, tty, started_at, model)
+        for pid, tty, started_at, provider, model in candidates
+        if (cwd := cwd_by_pid.get(pid, ""))
+    ]
+    _process_cache = (monotonic_now, processes)
+    return processes
+
+
+def running_pids() -> list[int]:
+    """顯示用途的 live local-LLM CLI pid；掃描未知時回空清單。"""
+    return [process.pid for process in (_scan_processes() or [])]
+
+
+class LocalLLMSource:
+    def __init__(self, provider: str) -> None:
+        self.name = provider
+
+    def discover(self) -> list[Session]:
+        processes = _scan_processes()
+        if processes is None:
+            return []
+        return [
+            Session(
+                session_id=f"{self.name}:pid-{process.pid}",
+                cwd=process.cwd,
+                status=Status.IDLE,
+                last_active=process.started_at,
+                last_action=process.model,
+                source=self.name,
+                tty=process.tty,
+                provider=self.name,
+                origin_cwd=process.cwd,
+            )
+            for process in processes
+            if process.provider == self.name
+        ]
+
+
+ollama_source = LocalLLMSource("ollama")
+llama_cpp_source = LocalLLMSource("llama.cpp")