agent-usage-manager 0.2.0__tar.gz → 0.2.2__tar.gz

{agent_usage_manager-0.2.0 → agent_usage_manager-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-usage-manager
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -25,8 +25,10 @@ shows which agents are alive and what they're costing you (CPU, memory, GPU), an
 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.
 
-No database, no auth layer, no dependencies beyond FastAPI + psutil. Runs on
-macOS and Linux. Meant to be cloned, configured, and run on any node in a fleet.
+No database, no auth framework (one static token file gates the kill switch),
+no dependencies beyond FastAPI + psutil. 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)
 
@@ -80,7 +82,14 @@ ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama ru
     command: 'terminal-notifier -title agents -message "$AUM_MSG"'
     cooldown: 600
     flags: [hot, churn, leak]   # the default; add idle to opt in
+    leak_floor_mb: 1536         # optional: leak alerts only above this RSS
   ```
+
+  `leak_floor_mb` mutes leak *alerts* (the badge still shows) until the agent's
+  absolute footprint crosses the floor — agents that accrue working state, like
+  a chat bot growing its session context, ratchet RSS exactly like leakers, so
+  relative growth alone can be noisy. Crossing the floor counts as the
+  appearance, so a genuine ratchet still alerts.
 - **Prometheus `/metrics`.** Per-agent CPU/mem/instances/restarts and badge states
   in text exposition format, aggregated per label (no pid-churn series bloat) —
   point Grafana or any Prometheus scraper at `http://127.0.0.1:8765/metrics`.
@@ -94,6 +103,19 @@ ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama ru
   while your pointer is over the table, so the kill button can't shift under your
   cursor mid-click.
 
+## Product boundary
+
+`agent-usage-manager` is intentionally **not** a fleet scheduler, dispatcher, or
+multi-host orchestrator. It answers local process questions: what agent process is
+running here, what resources is its process tree using, did it enter a suspicious
+state, and can this local operator safely stop it?
+
+If you run a separate fleet control plane, treat AUM as an optional read-only
+input. Scrape `list --json`, `/api/agents`, or `/metrics` for local OS facts, then
+make scheduling, budget, restart, and kill/retire decisions in your own
+deterministic control layer. Do not route irreversible fleet operations through
+AUM's kill endpoint as a central substrate.
+
 ## Safety
 
 This is the important part — a web page that can kill processes needs guardrails:
@@ -113,9 +135,29 @@ This is the important part — a web page that can kill processes needs guardrai
   kill request carrying a foreign `Origin` is refused (CSRF guard) — so a
   malicious page can't kill your agents or read your process list. `curl` and
   the dashboard itself are unaffected.
-- **Bind local by default.** It listens on `127.0.0.1`. Don't expose it to a network
-  without putting auth in front of it (reverse proxy + basic auth, SSH tunnel, etc.) —
-  it has no built-in authentication.
+- **Kill requires a token (caller authorization).** The allowlist above says what
+  *may* be killed; the token says *who* may kill. The monitored agents are
+  themselves untrusted HTTP callers — a prompt-injected agent with an HTTP tool
+  and localhost reach could otherwise `POST /api/kill` and take down its
+  siblings (Origin headers are trivially forged outside a browser). The token is
+  auto-generated on first run into a `0600` file —
+  `~/Library/Application Support/agent-usage-manager/kill_token` on macOS,
+  `$XDG_STATE_HOME/agent-usage-manager/kill_token` (default
+  `~/.local/state/…`) elsewhere — and every kill must send it as an
+  `X-Kill-Token` header. It is **never served over HTTP** (anything that can
+  curl the dashboard could read it): the dashboard asks you to paste it once on
+  your first kill and keeps it in the browser's localStorage. Delete the file
+  to rotate the token.
+- **Action log.** Every kill attempt — success *and* every refusal — appends a
+  JSON line to `actions.log` next to the token file: timestamp, caller address,
+  target pid/command, outcome. "What was killed at 3am" and "what's been
+  probing the kill endpoint" both have an answer. Append-only, no rotation;
+  one line per attempt stays tiny.
+- **Non-loopback binds fail closed.** It listens on `127.0.0.1`; asking it to
+  bind anything else (`--host 0.0.0.0`, a LAN IP) refuses to start unless you
+  also pass `--unsafe-expose`. Exposing the port means one static token is all
+  that stands between the network and your agents — put real auth in front
+  (reverse proxy + basic auth, SSH tunnel, etc.) before using that flag.
 
 ## Limits & known issues
 
@@ -177,7 +219,9 @@ git clone <this-repo> && cd agent-usage-manager
 ```
 
 It opens the dashboard in your browser automatically. Flags: `--host`, `--port`,
-`--config /path/to/agents.yaml`, `--no-browser` (for headless/server use).
+`--config /path/to/agents.yaml`, `--no-browser` (for headless/server use),
+`--unsafe-expose` (required for any non-loopback `--host` — see
+[Safety](#safety)).
 
 ## Configure which processes are "agents"
 
@@ -211,6 +255,23 @@ a generically-named binary (Kiro.app → `Electron`) are still matched by app na
 `protect:` keeps a matched process listed but refuses to kill it; `ignore:`
 drops it from agent classification entirely.
 
+**Telling identical agents apart (`tmux_labels:`)** — a fleet of same-binary
+agents (say five `claude` bots, one per tmux session) all hits one `agents:`
+entry and shows N indistinguishable rows; a distinguishing flag deeper in
+their command lines is invisible to matching *by design* (see above). When
+each instance runs in its own tmux session, the session name is its identity:
+
+```yaml
+tmux_labels: "^bot-(.+)$"   # session bot-coder_1 → row label coder_1
+```
+
+If a matched agent root (or an ancestor) is a tmux pane process whose session
+name matches the regex, the row's label becomes the first capture group (the
+whole session name if there's no group). Churn tracking, alert transitions,
+and `/metrics` series all use the derived label, so each instance gets its own
+state. Sessions that don't match the regex keep their `agents:` label, and the
+key is ignored where tmux isn't installed or running.
+
 **Which `agents.yaml` is used** — resolved once at startup, first hit wins:
 
 1. `AGENTS_CONFIG=/path/to/agents.yaml` env var (the `--config` flag sets this)
@@ -253,11 +314,23 @@ on Macs — CPU and memory are the meaningful resource signals there.
 
 ## API
 
-- `GET  /api/agents` → `{ agents: [...], host, cpu_count, mem_total_mb, mem_used_pct, config_path, config_error, ts }`
-  — each agent includes `trend` (recent CPU samples) and `flag` (`"hot"` / `"idle"` / `null`)
+- `GET  /api/agents` → `{ api_version, aum_version, agents: [...], host, cpu_count, mem_total_mb, mem_used_pct, config_path, config_error, ts }`
+  — each agent includes read-only telemetry such as `pid`, `create_time`, `label`,
+  resource totals, recent CPU `trend`, flags (`hot`, `idle`, `churn`, `leak` when
+  present), protection state, and supervised-process guidance. Pair `pid` with
+  `create_time` when caching rows so PID reuse cannot alias two different agents.
+  This endpoint is suitable as an input to external tools, not as a fleet-control
+  contract.
 - `GET  /api/tree/{pid}` → the agent's process subtree (per-child pid/name/cpu/mem/cmdline);
   only works on recognized agents, same authorization as kill
-- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`)
+- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`).
+  Requires the `X-Kill-Token` header — the token lives in the `0600` file shown
+  in the 403 message (see [Safety](#safety)):
+
+  ```bash
+  curl -X POST -H "X-Kill-Token: $(cat ~/Library/Application\ Support/agent-usage-manager/kill_token)" \
+    http://127.0.0.1:8765/api/kill/48213
+  ```
 
 ## Run as a service
 
@@ -290,6 +363,25 @@ CI runs the test suite on Linux + macOS (Python 3.9 and 3.12) on every push and
 Cross-platform note: kill uses psutil's `terminate()`/`kill()`, which map to
 SIGTERM/SIGKILL on POSIX and TerminateProcess on Windows.
 
+## Release notes
+
+### 0.2.2 — unreleased
+
+- Added `api_version` and `aum_version` to `/api/agents` and `list --json`.
+- Added per-agent `create_time` so external telemetry consumers can pair it with
+  `pid` and avoid PID-reuse aliasing.
+- Added `tmux_labels:` — derive per-instance row labels from tmux session names,
+  so a fleet of identical agents stops rendering as N indistinguishable rows.
+
+### 0.2.1 — security and verification hardening
+
+- Kill endpoint now requires caller authorization via the static token file.
+- Non-loopback binds fail closed unless `--unsafe-expose` is explicitly passed.
+- Kill attempts and refusals append to the local action log.
+- Added deterministic kill-path regression tests, including pid/create_time pins.
+- Added synthetic hot/idle/churn/leak trace fixtures.
+- Added adversarial matcher cases so lookalike process names stay test-covered.
+
 ## Troubleshooting
 
 - **`pip install` fails building psutil** — no prebuilt wheel for your
@@ -310,6 +402,13 @@ SIGTERM/SIGKILL on POSIX and TerminateProcess on Windows.
 - **HTTP 403 on every request** — the DNS-rebinding guard refuses non-local
   hostnames. Use `http://127.0.0.1:8765` (or a bare IP) instead of a custom
   DNS name pointing at the box.
+- **HTTP 403 on kill only ("Kill requires the X-Kill-Token header")** — send
+  the token from the file named in the message. In the dashboard, the paste
+  prompt reappears on your next kill click (a stored stale token is forgotten
+  automatically when the server rejects it).
+- **"refusing to bind …" at startup** — non-loopback `--host` values fail
+  closed; add `--unsafe-expose` only with auth in front (see
+  [Safety](#safety)).
 
 ## License
 

{agent_usage_manager-0.2.0 → agent_usage_manager-0.2.2}/README.md

@@ -6,8 +6,10 @@ shows which agents are alive and what they're costing you (CPU, memory, GPU), an
 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.
 
-No database, no auth layer, no dependencies beyond FastAPI + psutil. Runs on
-macOS and Linux. Meant to be cloned, configured, and run on any node in a fleet.
+No database, no auth framework (one static token file gates the kill switch),
+no dependencies beyond FastAPI + psutil. 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)
 
@@ -61,7 +63,14 @@ ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama ru
     command: 'terminal-notifier -title agents -message "$AUM_MSG"'
     cooldown: 600
     flags: [hot, churn, leak]   # the default; add idle to opt in
+    leak_floor_mb: 1536         # optional: leak alerts only above this RSS
   ```
+
+  `leak_floor_mb` mutes leak *alerts* (the badge still shows) until the agent's
+  absolute footprint crosses the floor — agents that accrue working state, like
+  a chat bot growing its session context, ratchet RSS exactly like leakers, so
+  relative growth alone can be noisy. Crossing the floor counts as the
+  appearance, so a genuine ratchet still alerts.
 - **Prometheus `/metrics`.** Per-agent CPU/mem/instances/restarts and badge states
   in text exposition format, aggregated per label (no pid-churn series bloat) —
   point Grafana or any Prometheus scraper at `http://127.0.0.1:8765/metrics`.
@@ -75,6 +84,19 @@ ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama ru
   while your pointer is over the table, so the kill button can't shift under your
   cursor mid-click.
 
+## Product boundary
+
+`agent-usage-manager` is intentionally **not** a fleet scheduler, dispatcher, or
+multi-host orchestrator. It answers local process questions: what agent process is
+running here, what resources is its process tree using, did it enter a suspicious
+state, and can this local operator safely stop it?
+
+If you run a separate fleet control plane, treat AUM as an optional read-only
+input. Scrape `list --json`, `/api/agents`, or `/metrics` for local OS facts, then
+make scheduling, budget, restart, and kill/retire decisions in your own
+deterministic control layer. Do not route irreversible fleet operations through
+AUM's kill endpoint as a central substrate.
+
 ## Safety
 
 This is the important part — a web page that can kill processes needs guardrails:
@@ -94,9 +116,29 @@ This is the important part — a web page that can kill processes needs guardrai
   kill request carrying a foreign `Origin` is refused (CSRF guard) — so a
   malicious page can't kill your agents or read your process list. `curl` and
   the dashboard itself are unaffected.
-- **Bind local by default.** It listens on `127.0.0.1`. Don't expose it to a network
-  without putting auth in front of it (reverse proxy + basic auth, SSH tunnel, etc.) —
-  it has no built-in authentication.
+- **Kill requires a token (caller authorization).** The allowlist above says what
+  *may* be killed; the token says *who* may kill. The monitored agents are
+  themselves untrusted HTTP callers — a prompt-injected agent with an HTTP tool
+  and localhost reach could otherwise `POST /api/kill` and take down its
+  siblings (Origin headers are trivially forged outside a browser). The token is
+  auto-generated on first run into a `0600` file —
+  `~/Library/Application Support/agent-usage-manager/kill_token` on macOS,
+  `$XDG_STATE_HOME/agent-usage-manager/kill_token` (default
+  `~/.local/state/…`) elsewhere — and every kill must send it as an
+  `X-Kill-Token` header. It is **never served over HTTP** (anything that can
+  curl the dashboard could read it): the dashboard asks you to paste it once on
+  your first kill and keeps it in the browser's localStorage. Delete the file
+  to rotate the token.
+- **Action log.** Every kill attempt — success *and* every refusal — appends a
+  JSON line to `actions.log` next to the token file: timestamp, caller address,
+  target pid/command, outcome. "What was killed at 3am" and "what's been
+  probing the kill endpoint" both have an answer. Append-only, no rotation;
+  one line per attempt stays tiny.
+- **Non-loopback binds fail closed.** It listens on `127.0.0.1`; asking it to
+  bind anything else (`--host 0.0.0.0`, a LAN IP) refuses to start unless you
+  also pass `--unsafe-expose`. Exposing the port means one static token is all
+  that stands between the network and your agents — put real auth in front
+  (reverse proxy + basic auth, SSH tunnel, etc.) before using that flag.
 
 ## Limits & known issues
 
@@ -158,7 +200,9 @@ git clone <this-repo> && cd agent-usage-manager
 ```
 
 It opens the dashboard in your browser automatically. Flags: `--host`, `--port`,
-`--config /path/to/agents.yaml`, `--no-browser` (for headless/server use).
+`--config /path/to/agents.yaml`, `--no-browser` (for headless/server use),
+`--unsafe-expose` (required for any non-loopback `--host` — see
+[Safety](#safety)).
 
 ## Configure which processes are "agents"
 
@@ -192,6 +236,23 @@ a generically-named binary (Kiro.app → `Electron`) are still matched by app na
 `protect:` keeps a matched process listed but refuses to kill it; `ignore:`
 drops it from agent classification entirely.
 
+**Telling identical agents apart (`tmux_labels:`)** — a fleet of same-binary
+agents (say five `claude` bots, one per tmux session) all hits one `agents:`
+entry and shows N indistinguishable rows; a distinguishing flag deeper in
+their command lines is invisible to matching *by design* (see above). When
+each instance runs in its own tmux session, the session name is its identity:
+
+```yaml
+tmux_labels: "^bot-(.+)$"   # session bot-coder_1 → row label coder_1
+```
+
+If a matched agent root (or an ancestor) is a tmux pane process whose session
+name matches the regex, the row's label becomes the first capture group (the
+whole session name if there's no group). Churn tracking, alert transitions,
+and `/metrics` series all use the derived label, so each instance gets its own
+state. Sessions that don't match the regex keep their `agents:` label, and the
+key is ignored where tmux isn't installed or running.
+
 **Which `agents.yaml` is used** — resolved once at startup, first hit wins:
 
 1. `AGENTS_CONFIG=/path/to/agents.yaml` env var (the `--config` flag sets this)
@@ -234,11 +295,23 @@ on Macs — CPU and memory are the meaningful resource signals there.
 
 ## API
 
-- `GET  /api/agents` → `{ agents: [...], host, cpu_count, mem_total_mb, mem_used_pct, config_path, config_error, ts }`
-  — each agent includes `trend` (recent CPU samples) and `flag` (`"hot"` / `"idle"` / `null`)
+- `GET  /api/agents` → `{ api_version, aum_version, agents: [...], host, cpu_count, mem_total_mb, mem_used_pct, config_path, config_error, ts }`
+  — each agent includes read-only telemetry such as `pid`, `create_time`, `label`,
+  resource totals, recent CPU `trend`, flags (`hot`, `idle`, `churn`, `leak` when
+  present), protection state, and supervised-process guidance. Pair `pid` with
+  `create_time` when caching rows so PID reuse cannot alias two different agents.
+  This endpoint is suitable as an input to external tools, not as a fleet-control
+  contract.
 - `GET  /api/tree/{pid}` → the agent's process subtree (per-child pid/name/cpu/mem/cmdline);
   only works on recognized agents, same authorization as kill
-- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`)
+- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`).
+  Requires the `X-Kill-Token` header — the token lives in the `0600` file shown
+  in the 403 message (see [Safety](#safety)):
+
+  ```bash
+  curl -X POST -H "X-Kill-Token: $(cat ~/Library/Application\ Support/agent-usage-manager/kill_token)" \
+    http://127.0.0.1:8765/api/kill/48213
+  ```
 
 ## Run as a service
 
@@ -271,6 +344,25 @@ CI runs the test suite on Linux + macOS (Python 3.9 and 3.12) on every push and
 Cross-platform note: kill uses psutil's `terminate()`/`kill()`, which map to
 SIGTERM/SIGKILL on POSIX and TerminateProcess on Windows.
 
+## Release notes
+
+### 0.2.2 — unreleased
+
+- Added `api_version` and `aum_version` to `/api/agents` and `list --json`.
+- Added per-agent `create_time` so external telemetry consumers can pair it with
+  `pid` and avoid PID-reuse aliasing.
+- Added `tmux_labels:` — derive per-instance row labels from tmux session names,
+  so a fleet of identical agents stops rendering as N indistinguishable rows.
+
+### 0.2.1 — security and verification hardening
+
+- Kill endpoint now requires caller authorization via the static token file.
+- Non-loopback binds fail closed unless `--unsafe-expose` is explicitly passed.
+- Kill attempts and refusals append to the local action log.
+- Added deterministic kill-path regression tests, including pid/create_time pins.
+- Added synthetic hot/idle/churn/leak trace fixtures.
+- Added adversarial matcher cases so lookalike process names stay test-covered.
+
 ## Troubleshooting
 
 - **`pip install` fails building psutil** — no prebuilt wheel for your
@@ -291,6 +383,13 @@ SIGTERM/SIGKILL on POSIX and TerminateProcess on Windows.
 - **HTTP 403 on every request** — the DNS-rebinding guard refuses non-local
   hostnames. Use `http://127.0.0.1:8765` (or a bare IP) instead of a custom
   DNS name pointing at the box.
+- **HTTP 403 on kill only ("Kill requires the X-Kill-Token header")** — send
+  the token from the file named in the message. In the dashboard, the paste
+  prompt reappears on your next kill click (a stored stale token is forgotten
+  automatically when the server rejects it).
+- **"refusing to bind …" at startup** — non-loopback `--host` values fail
+  closed; add `--unsafe-expose` only with auth in front (see
+  [Safety](#safety)).
 
 ## License
 

{agent_usage_manager-0.2.0 → agent_usage_manager-0.2.2}/agent_usage_manager/agents.yaml

@@ -58,6 +58,17 @@ ignore:
   - shipit        # Squirrel.framework auto-updater
   - kiro-cli-term # Kiro's integrated-terminal shells (zsh), not the agent
 
+# 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
+
 # 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.
 
@@ -70,7 +81,24 @@ ignore:
 # 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.
 #
-# 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
+# Example (desktop notification):
+#   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; notify.py is a `uv run` script, hence the inline PATH prefix.
+alerts:
+  command: 'PATH="$HOME/.local/bin:$PATH"; "$HOME/.claude/skills/_finance_lib/scripts/notify.py" --plain --priority digest --source usage-manager --feed-only --text "$AUM_MSG"'
+  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