agent-usage-manager 0.2.5__tar.gz → 0.2.6__tar.gz

agent_usage_manager-0.2.5/README.md → agent_usage_manager-0.2.6/PKG-INFO

@@ -1,17 +1,52 @@
+Metadata-Version: 2.5
+Name: agent-usage-manager
+Version: 0.2.6
+Summary: htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code).
+Project-URL: Homepage, https://github.com/minglong51/agent-usage-manager
+Project-URL: Repository, https://github.com/minglong51/agent-usage-manager
+Project-URL: Issues, https://github.com/minglong51/agent-usage-manager/issues
+Project-URL: Newsletter, https://buttondown.com/minglong51
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,gpu,llm,monitoring,observability,ollama,vllm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.110
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # agent-usage-manager
 
 A small web dashboard for **headless AI agents** running on a machine —
 OpenClaw, Hermes, Claude Code, Ollama, vLLM, llama.cpp, or anything you name. It
 shows which agents are alive and what they're costing you (CPU, memory, GPU), and
 gives you a **kill button** per agent. Think `htop`, scoped to just your agents —
-the [screenshot below](docs/dashboard.png) is a real run on a fleet node.
+the [screenshot below](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png) is a real run on a fleet node.
 
 No database, no auth framework (one static token file gates the kill switch),
 four direct dependencies (FastAPI, uvicorn, psutil, PyYAML). Runs on macOS and Linux. It is a
 per-node monitor and guarded local control panel: fleet schedulers may consume
 its read-only telemetry, but should own their own scheduling and actuation.
 
-![agent-usage-manager — live dashboard](docs/dashboard.png)
+![agent-usage-manager — live dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
 
 *A real run: ten agents grouped by process tree (`+N` = children rolled up),
 per-agent CPU/memory/uptime, launchd-supervised jobs flagged, and a kill button
@@ -39,7 +74,10 @@ uvx agent-usage-manager      # then open http://127.0.0.1:8765 (opens automatica
 One command — no install, no virtualenv, no leftovers. Other install options,
 config, and flags: [Install & run](#install--run).
 
-![one command to a live dashboard](docs/demo.gif)
+![one command to a live dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/demo.gif)
+
+*Field notes on running agents with discipline go out on the
+[Agent Discipline](https://buttondown.com/minglong51) list — a few emails a month.*
 
 ## What it does
 
@@ -179,6 +217,18 @@ This is the important part — a web page that can kill processes needs guardrai
   actions. That is deliberate (owner-only tailnet + token-gated actions), but do
   not read "loopback-only" as "not network-reachable" — a proxy in front is not
   a trust boundary.
+- **Fronting it with a proxy needs `AUM_TRUSTED_HOSTS`.** The DNS-rebinding guard
+  refuses any request whose `Host` is a non-local DNS name — which is exactly what
+  a proxy forwards. Opt that one name in explicitly:
+
+  ```bash
+  AUM_TRUSTED_HOSTS=box.your-tailnet.ts.net agent-usage-manager
+  ```
+
+  Comma-separated for several. Only add a name nobody else can mint a cert for on
+  this node; a name you don't control reopens the hole the guard exists to close.
+  Empty by default — out of the box only `localhost`, `127.0.0.1` and `::1` are
+  accepted.
 
 ## Limits & known issues
 

agent_usage_manager-0.2.5/PKG-INFO → agent_usage_manager-0.2.6/README.md

@@ -1,36 +1,17 @@
-Metadata-Version: 2.5
-Name: agent-usage-manager
-Version: 0.2.5
-Summary: htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code).
-Project-URL: Homepage, https://github.com/minglong51/agent-usage-manager
-Project-URL: Repository, https://github.com/minglong51/agent-usage-manager
-License: MIT
-License-File: LICENSE
-Keywords: ai-agents,gpu,llm,monitoring,observability,ollama,vllm
-Requires-Python: >=3.9
-Requires-Dist: fastapi>=0.110
-Requires-Dist: psutil>=5.9
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: uvicorn[standard]>=0.27
-Provides-Extra: dev
-Requires-Dist: httpx>=0.27; extra == 'dev'
-Requires-Dist: pytest>=7; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # agent-usage-manager
 
 A small web dashboard for **headless AI agents** running on a machine —
 OpenClaw, Hermes, Claude Code, Ollama, vLLM, llama.cpp, or anything you name. It
 shows which agents are alive and what they're costing you (CPU, memory, GPU), and
 gives you a **kill button** per agent. Think `htop`, scoped to just your agents —
-the [screenshot below](docs/dashboard.png) is a real run on a fleet node.
+the [screenshot below](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png) is a real run on a fleet node.
 
 No database, no auth framework (one static token file gates the kill switch),
 four direct dependencies (FastAPI, uvicorn, psutil, PyYAML). Runs on macOS and Linux. It is a
 per-node monitor and guarded local control panel: fleet schedulers may consume
 its read-only telemetry, but should own their own scheduling and actuation.
 
-![agent-usage-manager — live dashboard](docs/dashboard.png)
+![agent-usage-manager — live dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
 
 *A real run: ten agents grouped by process tree (`+N` = children rolled up),
 per-agent CPU/memory/uptime, launchd-supervised jobs flagged, and a kill button
@@ -58,7 +39,10 @@ uvx agent-usage-manager      # then open http://127.0.0.1:8765 (opens automatica
 One command — no install, no virtualenv, no leftovers. Other install options,
 config, and flags: [Install & run](#install--run).
 
-![one command to a live dashboard](docs/demo.gif)
+![one command to a live dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/demo.gif)
+
+*Field notes on running agents with discipline go out on the
+[Agent Discipline](https://buttondown.com/minglong51) list — a few emails a month.*
 
 ## What it does
 
@@ -198,6 +182,18 @@ This is the important part — a web page that can kill processes needs guardrai
   actions. That is deliberate (owner-only tailnet + token-gated actions), but do
   not read "loopback-only" as "not network-reachable" — a proxy in front is not
   a trust boundary.
+- **Fronting it with a proxy needs `AUM_TRUSTED_HOSTS`.** The DNS-rebinding guard
+  refuses any request whose `Host` is a non-local DNS name — which is exactly what
+  a proxy forwards. Opt that one name in explicitly:
+
+  ```bash
+  AUM_TRUSTED_HOSTS=box.your-tailnet.ts.net agent-usage-manager
+  ```
+
+  Comma-separated for several. Only add a name nobody else can mint a cert for on
+  this node; a name you don't control reopens the hole the guard exists to close.
+  Empty by default — out of the box only `localhost`, `127.0.0.1` and `::1` are
+  accepted.
 
 ## Limits & known issues
 

agent_usage_manager-0.2.5/agent_usage_manager/agents.yaml → agent_usage_manager-0.2.6/agent_usage_manager/agents.default.yaml

@@ -1,3 +1,8 @@
+# Default configuration shipped with the package. It is used only when you have
+# no agents.yaml of your own: `--config` wins, then ./agents.yaml in the current
+# directory, then this file. Copy it somewhere and edit rather than editing it
+# in place — a package upgrade replaces this file.
+#
 # Which processes count as "agents". A process matches if the pattern hits its
 # executable name + first few arguments (case-insensitive substring or regex) —
 # NOT the entire command line, so a process that merely mentions an agent name
@@ -68,38 +73,35 @@ ignore:
 
 # Optional: per-instance labels from launchd job labels — the supervised-fleet
 # counterpart of tmux_labels below. Several LaunchAgents running the same
-# binary (e.g. ai.hermes.gateway, ai.hermes.gateway-frontdoor, …) all hit one
-# agents: entry and land as indistinguishable rows, and tmux never sees them.
-# When a matched root's own launchd job label matches this regex, the first
-# capture group (the whole label if no group) becomes the row label — churn
-# tracking, alert transitions, and /metrics all get per-instance identity.
-# tmux_labels wins when both apply. Empty/absent = off.
-launchd_labels: "^ai\\.hermes\\.(?:gateway-)?(.+)$"   # → gateway, frontdoor, engineering_3
+# binary all hit one agents: entry and land as indistinguishable rows, and tmux
+# never sees them. When a matched root's own launchd job label matches this
+# regex, the first capture group (the whole label if no group) becomes the row
+# label — churn tracking, alert transitions, and /metrics all get per-instance
+# identity. tmux_labels wins when both apply. Empty/absent = off.
+#
+#   launchd_labels: "^com\\.example\\.worker-(.+)$"   # → worker-1, worker-2
 
 # Optional: per-instance labels from tmux session names. A fleet of identical
-# agents (e.g. several claude-code bots, one per tmux session bot-*) all hit
-# one agents: entry above and land as N indistinguishable rows — their
-# cmdlines can't tell them apart, because matching deliberately sees only the
-# executable + first args. The tmux session each one runs in IS its identity:
-# when a matched root (or an ancestor) is a tmux pane whose session name
-# matches this regex, the row is labeled with the first capture group (the
-# whole session name if there is no group). Sessions that don't match keep
-# their agents: label, so incidental tmux use never renames rows.
-tmux_labels: "^bot-(.+)$"      # session bot-coder_1 → row label coder_1
+# agents (e.g. several claude-code bots, one per tmux session) all hit one
+# agents: entry above and land as N indistinguishable rows — their cmdlines
+# can't tell them apart, because matching deliberately sees only the executable
+# + first args. The tmux session each one runs in IS its identity: when a
+# matched root (or an ancestor) is a tmux pane whose session name matches this
+# regex, the row is labeled with the first capture group (the whole session
+# name if there is no group). Sessions that don't match keep their agents:
+# label, so incidental tmux use never renames rows.
+#
+#   tmux_labels: "^bot-(.+)$"      # session bot-worker1 → row label worker1
 
-# Labels whose idle state is NORMAL — agents that wait for work (bots parked
-# on a Telegram poll, gateways waiting for requests). They get no "idle"
-# badge: badging the whole waiting fleet wallpapers the dashboard and trains
-# badge-blindness (12 of 22 rows wore "idle 10m+" before this existed). Same
-# reasoning as `idle` being opt-in for alerts below. Case-insensitive
+# Labels whose idle state is NORMAL — agents that wait for work (bots parked on
+# a chat poll, gateways waiting for requests). They get no "idle" badge: badging
+# the whole waiting fleet wallpapers the dashboard and trains badge-blindness.
+# Same reasoning as `idle` being opt-in for alerts below. Case-insensitive
 # substrings of the row label (incl. tmux-derived ones), like ignore:.
-idle_ok:
-  - admin
-  - coder        # covers coder_1…coder_4
-  - hermes       # covers the launchd_labels-renamed rows too (gateway,
-                 # frontdoor, engineering_*) — suppression matches the BASE
-                 # matcher label as well as the instance label
-  - codex
+#
+#   idle_ok:
+#     - gateway
+#     - worker
 
 # GPU sampling: nvidia-smi is used automatically when present (Linux/NVIDIA).
 # On Apple Silicon there is no per-process GPU API, so the GPU column is blank.
@@ -113,29 +115,15 @@ idle_ok:
 # fleet of agents that wait for work, idle is the NORMAL state, and alerting on
 # it floods the channel every time the server restarts and re-learns the fleet.
 #
-# Example (desktop notification):
+# Nothing is wired by default — uncomment and point it at your own channel, then
+# prove it with `agent-usage-manager test-alert` before a real badge depends on
+# it. Two things worth knowing before you turn `hot` on: for inference agents
+# pegged CPU IS the job, and spawn-heavy agents look like churn while working.
+#
 #   alerts:
 #     command: 'terminal-notifier -title agent-usage-manager -message "$AUM_MSG"'
 #     cooldown: 600              # seconds, default 600
 #     flags: [hot, churn, leak]  # default; add idle only if you really want it
-#
-# Live wiring on this host: record to the attention feed, never ring
-# (2026-07-06, Ming: "most of them are noise"). First live day pushed two false
-# positives — "codex churn" during legitimate spawn work and "claude-code hot"
-# during a working session; for inference agents, pegged-CPU IS the job.
-# Badges stay live on the dashboard + machinery panel; the feed line rides the
-# next digest. Genuine breakage has louder, independent signals (mcp-autoheal
-# GAVE UP, cron-health, sync-bot liveness). `hot` dropped from alerting
-# entirely.
-# Ref discipline (2026-07-30): one stable ref per (agent, flag) + --upsert-open,
-# so a repeat firing UPDATES the single open card in place instead of stacking
-# one per cooldown expiry (nine churn cards in five days); the refreshed card
-# carries the latest cpu/mem/pid snapshot. fyi level = feed-only, riding the
-# digest exactly like the retired notify.py --feed-only wiring did.
-alerts:
-  command: '"$HOME/workspace/founder-agent-os/bin/attention" add --level fyi --source usage-manager --title "$AUM_MSG" --body "$AUM_MSG" --ref "usage-manager:$AUM_LABEL:$AUM_FLAG" --upsert-open'
-  cooldown: 7200                 # 2 h per (agent, flag)
-  flags: [churn, leak]
-  leak_floor_mb: 1536            # bots legitimately ratchet RSS as session
-                                 # context grows; only push leak alerts once
-                                 # the absolute footprint is actually large
+#     leak_floor_mb: 1536        # only alert on leak once the absolute footprint
+#                                # is large — long-running agents legitimately
+#                                # ratchet RSS as their context grows

{agent_usage_manager-0.2.5 → agent_usage_manager-0.2.6}/agent_usage_manager/app.py

@@ -41,7 +41,10 @@ def _resolve_config() -> Path:
     cwd_cfg = Path.cwd() / "agents.yaml"
     if cwd_cfg.exists():
         return cwd_cfg
-    return BASE / "agents.yaml"
+    local = BASE / "agents.yaml"
+    if local.exists():
+        return local
+    return BASE / "agents.default.yaml"
 
 
 CONFIG_PATH = _resolve_config()
@@ -688,11 +691,18 @@ async def _lifespan(_: FastAPI):
 app = FastAPI(title="agent-usage-manager", lifespan=_lifespan)
 
 
-# Loopback names are always local. The ts.net FQDN is the tailnet front door:
-# `tailscale serve --https=8448` proxies to this app and preserves the Host
-# header. Only tailscaled can mint that name/cert for this node, so allowing
-# it does not reopen the DNS-rebinding hole _host_allowed exists to close.
-_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1", "minglongs-mac-mini.tailab5be0.ts.net"}
+# Loopback names are always local. Anything else must be opted in per install via
+# AUM_TRUSTED_HOSTS (comma-separated hostnames) — typically the FQDN of a reverse
+# proxy or tailnet front door that preserves the Host header, e.g.
+# `tailscale serve --https=8448` fronting this app. Only add a name that nobody
+# else can mint a cert for on this node; any other name reopens the DNS-rebinding
+# hole _host_allowed exists to close.
+def _configured_trusted_hosts() -> set[str]:
+    raw = os.environ.get("AUM_TRUSTED_HOSTS", "")
+    return {h.strip().lower() for h in raw.split(",") if h.strip()}
+
+
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"} | _configured_trusted_hosts()
 
 
 def _hostname_of(hostport: str) -> str:

agent_usage_manager-0.2.6/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-usage-manager"
+version = "0.2.6"
+description = "htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["ai-agents", "monitoring", "gpu", "ollama", "vllm", "llm", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "psutil>=5.9",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/minglong51/agent-usage-manager"
+Repository = "https://github.com/minglong51/agent-usage-manager"
+Issues = "https://github.com/minglong51/agent-usage-manager/issues"
+Newsletter = "https://buttondown.com/minglong51"
+
+[project.scripts]
+agent-usage-manager = "agent_usage_manager.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_usage_manager"]
+# agents.yaml is the maintainer's live config in a source checkout, not a
+# shippable default — the wheel carries agents.default.yaml instead.
+exclude = ["agent_usage_manager/agents.yaml"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["agent_usage_manager/agents.yaml"]

{agent_usage_manager-0.2.5 → agent_usage_manager-0.2.6}/tests/test_design_docs.py

@@ -17,6 +17,9 @@ context only.
 
 This file is shared verbatim across repos — it locates its own repo root, so it works
 at any depth. Do not fork it per repo.
+
+Canonical home: ~/dotfiles/design-doc-contract/test_design_docs.py — patch there, then
+propagate with ~/dotfiles/local-bin/design-doc-checker-sync.
 """
 
 import re
@@ -59,9 +62,7 @@ def contract_files() -> list[Path]:
 
 def contract_path() -> Path:
     """The contract file carrying the map. Prefers AGENTS.md when both have it."""
-    candidates = [
-        p for p in contract_files() if FENCE.search(p.read_text(encoding="utf-8"))
-    ]
+    candidates = [p for p in contract_files() if FENCE.search(p.read_text(encoding="utf-8"))]
     if not candidates:
         raise ValueError(
             f"no ```design-doc-map fence in {[p.name for p in contract_files()]} at {REPO}"
@@ -160,9 +161,7 @@ def drift(doc: str, paths: list[str]) -> dict[str, object]:
         return {"doc": doc, "untracked": True, "added": [], "removed": [], "commits": 0}
 
     def modules(filt: str) -> list[str]:
-        out = git(
-            "diff", f"--diff-filter={filt}", "--name-only", f"{sha}..HEAD", "--", *paths
-        )
+        out = git("diff", f"--diff-filter={filt}", "--name-only", f"{sha}..HEAD", "--", *paths)
         return [p for p in out.splitlines() if p and not IS_TEST.search(p)]
 
     return {

{agent_usage_manager-0.2.5 → agent_usage_manager-0.2.6}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "agent-usage-manager"
-version = "0.2.4"
+version = "0.2.6"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi", version = "0.128.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },

agent_usage_manager-0.2.5/pyproject.toml

@@ -1,31 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "agent-usage-manager"
-version = "0.2.5"
-description = "htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code)."
-readme = "README.md"
-license = { text = "MIT" }
-requires-python = ">=3.9"
-keywords = ["ai-agents", "monitoring", "gpu", "ollama", "vllm", "llm", "observability"]
-dependencies = [
-    "fastapi>=0.110",
-    "uvicorn[standard]>=0.27",
-    "psutil>=5.9",
-    "pyyaml>=6.0",
-]
-
-[project.optional-dependencies]
-dev = ["pytest>=7", "httpx>=0.27"]
-
-[project.urls]
-Homepage = "https://github.com/minglong51/agent-usage-manager"
-Repository = "https://github.com/minglong51/agent-usage-manager"
-
-[project.scripts]
-agent-usage-manager = "agent_usage_manager.cli:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["agent_usage_manager"]