clawmonitor 0.1.3__tar.gz

clawmonitor-0.1.3/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

clawmonitor-0.1.3/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: clawmonitor
+Version: 0.1.3
+Summary: Real-time OpenClaw session monitor (TUI) with Gateway log correlation and manual progress nudges.
+Author: OpenClaw community
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/openclawq/clawmonitor
+Project-URL: Repository, https://github.com/openclawq/clawmonitor
+Project-URL: Issues, https://github.com/openclawq/clawmonitor/issues
+Keywords: openclaw,monitoring,tui,observability,feishu,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Dynamic: license-file
+
+# ClawMonitor
+
+English | [简体中文](README.zh-CN.md)
+
+Real-time **OpenClaw** session monitor with:
+
+- Per-session last inbound **user** message + last outbound **assistant** message (preview + timestamp)
+- Work state: WORKING / FINISHED / INTERRUPTED / NO_MESSAGE (+ NO_FEEDBACK alert)
+- Long-run visibility via `*.jsonl.lock` (works even if Gateway is down)
+- Optional Gateway log tail + channel runtime snapshot correlation (Feishu/Telegram-focused rules)
+- Full-screen TUI with manual “nudge” (send a progress request via `chat.send`)
+
+## Install (editable)
+
+```bash
+cd ~/program/clawmonitor
+python3 -m pip install -e .
+```
+
+## Install (PyPI)
+
+Once published to PyPI, you’ll be able to install via:
+
+```bash
+pip install clawmonitor
+```
+
+## Run
+
+```bash
+clawmonitor init
+clawmonitor tui
+```
+
+Other commands:
+
+```bash
+clawmonitor snapshot --format json
+clawmonitor snapshot --format md
+clawmonitor nudge --session-key 'agent:main:main' --template progress
+clawmonitor nudge --session-key 'agent:main:main' --template continue
+clawmonitor push --session-key 'agent:main:main' --dry-run
+clawmonitor status
+clawmonitor status --format json
+clawmonitor status --format md
+clawmonitor report --session-key 'agent:main:main' --format both
+clawmonitor watch --interval 1
+```
+
+## Configuration
+
+Default config path:
+
+- `~/.config/clawmonitor/config.toml`
+
+Example config is in `config.example.toml`.
+
+Runtime data (NOT stored in this repo):
+
+- Logs: `~/.local/state/clawmonitor/events.jsonl`
+- Reports: `~/.local/state/clawmonitor/reports/`
+- Cache: `~/.cache/clawmonitor/`
+
+## Keys (TUI)
+
+- `↑/↓`: move selection
+- `Enter`: nudge selected session (choose template)
+- `?`: show help overlay
+- `l`: toggle related logs panel
+- `d`: re-run diagnosis for selected session
+- `e`: export a redacted report for selected session
+- `r`: force refresh
+- `f`: cycle refresh interval
+- `q`: quit
+
+Rows are color-coded when your terminal supports colors (`OK` green, `RUN` cyan, `IDLE` yellow, `ALERT` red).
+
+## Telegram note: ACP “thread bindings”
+
+OpenClaw can route a Telegram chat to a different session key via local *thread bindings*.
+This may make it look like your “main” session stopped receiving messages.
+
+ClawMonitor detects this and flags it:
+
+- `BOUND_OTHER` in `clawmonitor status`
+- `BIND` in the TUI list
+
+Relevant files/settings:
+
+- Thread bindings: `~/.openclaw/telegram/thread-bindings-default.json`
+- Config toggle: `~/.openclaw/openclaw.json` → `channels.telegram.threadBindings.spawnAcpSessions`
+
+## First run
+
+If no config file exists, most commands will offer to run the init wizard (interactive terminals only).
+
+See `docs/launch-post.md` for a longer intro.
+
+## Notes
+
+- ClawMonitor never prints or writes OpenClaw secrets. It avoids dumping `openclaw.json` and redacts suspicious token-like strings in logs/reports.
+- If Gateway is unreachable, ClawMonitor still works in offline mode (sessions/transcripts/locks/delivery-queue) but disables log tail + nudge.
+- If your terminal window is narrow, `clawmonitor tui` may hide the details panel; use `clawmonitor status` as a stable fallback.
+
+See `CONTRIBUTORS.md` for acknowledgements.

clawmonitor-0.1.3/README.md

@@ -0,0 +1,105 @@
+# ClawMonitor
+
+English | [简体中文](README.zh-CN.md)
+
+Real-time **OpenClaw** session monitor with:
+
+- Per-session last inbound **user** message + last outbound **assistant** message (preview + timestamp)
+- Work state: WORKING / FINISHED / INTERRUPTED / NO_MESSAGE (+ NO_FEEDBACK alert)
+- Long-run visibility via `*.jsonl.lock` (works even if Gateway is down)
+- Optional Gateway log tail + channel runtime snapshot correlation (Feishu/Telegram-focused rules)
+- Full-screen TUI with manual “nudge” (send a progress request via `chat.send`)
+
+## Install (editable)
+
+```bash
+cd ~/program/clawmonitor
+python3 -m pip install -e .
+```
+
+## Install (PyPI)
+
+Once published to PyPI, you’ll be able to install via:
+
+```bash
+pip install clawmonitor
+```
+
+## Run
+
+```bash
+clawmonitor init
+clawmonitor tui
+```
+
+Other commands:
+
+```bash
+clawmonitor snapshot --format json
+clawmonitor snapshot --format md
+clawmonitor nudge --session-key 'agent:main:main' --template progress
+clawmonitor nudge --session-key 'agent:main:main' --template continue
+clawmonitor push --session-key 'agent:main:main' --dry-run
+clawmonitor status
+clawmonitor status --format json
+clawmonitor status --format md
+clawmonitor report --session-key 'agent:main:main' --format both
+clawmonitor watch --interval 1
+```
+
+## Configuration
+
+Default config path:
+
+- `~/.config/clawmonitor/config.toml`
+
+Example config is in `config.example.toml`.
+
+Runtime data (NOT stored in this repo):
+
+- Logs: `~/.local/state/clawmonitor/events.jsonl`
+- Reports: `~/.local/state/clawmonitor/reports/`
+- Cache: `~/.cache/clawmonitor/`
+
+## Keys (TUI)
+
+- `↑/↓`: move selection
+- `Enter`: nudge selected session (choose template)
+- `?`: show help overlay
+- `l`: toggle related logs panel
+- `d`: re-run diagnosis for selected session
+- `e`: export a redacted report for selected session
+- `r`: force refresh
+- `f`: cycle refresh interval
+- `q`: quit
+
+Rows are color-coded when your terminal supports colors (`OK` green, `RUN` cyan, `IDLE` yellow, `ALERT` red).
+
+## Telegram note: ACP “thread bindings”
+
+OpenClaw can route a Telegram chat to a different session key via local *thread bindings*.
+This may make it look like your “main” session stopped receiving messages.
+
+ClawMonitor detects this and flags it:
+
+- `BOUND_OTHER` in `clawmonitor status`
+- `BIND` in the TUI list
+
+Relevant files/settings:
+
+- Thread bindings: `~/.openclaw/telegram/thread-bindings-default.json`
+- Config toggle: `~/.openclaw/openclaw.json` → `channels.telegram.threadBindings.spawnAcpSessions`
+
+## First run
+
+If no config file exists, most commands will offer to run the init wizard (interactive terminals only).
+
+See `docs/launch-post.md` for a longer intro.
+
+## Notes
+
+- ClawMonitor never prints or writes OpenClaw secrets. It avoids dumping `openclaw.json` and redacts suspicious token-like strings in logs/reports.
+- If Gateway is unreachable, ClawMonitor still works in offline mode (sessions/transcripts/locks/delivery-queue) but disables log tail + nudge.
+- If your terminal window is narrow, `clawmonitor tui` may hide the details panel; use `clawmonitor status` as a stable fallback.
+
+See `CONTRIBUTORS.md` for acknowledgements.

clawmonitor-0.1.3/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clawmonitor"
+version = "0.1.3"
+description = "Real-time OpenClaw session monitor (TUI) with Gateway log correlation and manual progress nudges."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "OpenClaw community" }]
+keywords = ["openclaw", "monitoring", "tui", "observability", "feishu", "telegram"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Monitoring",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "tomli>=2.0.1; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/openclawq/clawmonitor"
+Repository = "https://github.com/openclawq/clawmonitor"
+Issues = "https://github.com/openclawq/clawmonitor/issues"
+
+[project.scripts]
+clawmonitor = "clawmonitor.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

clawmonitor-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clawmonitor-0.1.3/src/clawmonitor/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except ImportError:  # pragma: no cover
+    from importlib_metadata import PackageNotFoundError, version  # type: ignore
+
+try:
+    __version__ = version("clawmonitor")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"

clawmonitor-0.1.3/src/clawmonitor/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()
+

clawmonitor-0.1.3/src/clawmonitor/actions.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .openclaw_cli import gateway_call
+
+
+TEMPLATES: Dict[str, str] = {
+    "progress": "请用不超过8行汇报：当前进度、下一步、预估完成时间；已完成请写 DONE；受阻请写 BLOCKED: 原因。",
+    "status": "只回复一个词：WORKING / DONE / BLOCKED，并补充1行原因或下一步。",
+    "last_action": "请列出你最近一次工具/命令执行的名称与结果摘要（最多5行）。",
+    "continue": "继续完成你正在做/上次未完成的任务；如果正在运行长任务也不要中断，完成后汇报 DONE，并在过程中每隔10分钟用不超过6行汇报一次进度。",
+    "finalize": "如果你已经完成了用户交代的任务：请输出最终总结（<=10行）+ 交付物/结果位置（路径/链接）+ 用一行写 DONE。若尚未完成：用 <=6 行汇报当前进度、下一步、预估完成时间，并用 WORKING 结尾。",
+}
+
+
+@dataclass(frozen=True)
+class NudgeResult:
+    ok: bool
+    run_id: Optional[str]
+    status: Optional[str]
+    error: Optional[str]
+
+
+def send_nudge(openclaw_bin: str, session_key: str, template_id: str, deliver: bool = True) -> NudgeResult:
+    msg = TEMPLATES.get(template_id)
+    if not msg:
+        return NudgeResult(ok=False, run_id=None, status=None, error=f"unknown template: {template_id}")
+    params: Dict[str, Any] = {
+        "sessionKey": session_key,
+        "message": msg,
+        "deliver": bool(deliver),
+        "timeoutMs": 0,
+        "idempotencyKey": str(uuid.uuid4()),
+    }
+    res = gateway_call(openclaw_bin, "chat.send", params=params, timeout_ms=10000)
+    if not res.ok or not res.data:
+        return NudgeResult(ok=False, run_id=None, status=None, error=f"chat.send failed (rc={res.returncode})")
+    run_id = res.data.get("runId") if isinstance(res.data.get("runId"), str) else None
+    status = res.data.get("status") if isinstance(res.data.get("status"), str) else None
+    return NudgeResult(ok=True, run_id=run_id, status=status, error=None)

clawmonitor-0.1.3/src/clawmonitor/channels_status.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .openclaw_cli import gateway_call
+
+
+@dataclass(frozen=True)
+class ChannelsSnapshot:
+    ts: Optional[int]
+    raw: Dict[str, Any]
+
+
+def fetch_channels_status(openclaw_bin: str, probe: bool = False, timeout_ms: int = 10000) -> Optional[ChannelsSnapshot]:
+    params: Dict[str, Any] = {}
+    if probe:
+        params["probe"] = True
+        params["timeoutMs"] = timeout_ms
+    res = gateway_call(openclaw_bin, "channels.status", params=params, timeout_ms=timeout_ms)
+    if not res.ok or not res.data:
+        return None
+    data = res.data
+    ts = data.get("ts")
+    return ChannelsSnapshot(ts=int(ts) if isinstance(ts, int) else None, raw=data)
+