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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/.gitignore +1 -0
  2. agent_usage_manager-0.3.0/CHANGELOG.md +75 -0
  3. agent_usage_manager-0.3.0/PKG-INFO +189 -0
  4. agent_usage_manager-0.3.0/README.md +152 -0
  5. agent_usage_manager-0.3.0/SECURITY.md +46 -0
  6. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/agent_usage_manager/app.py +533 -120
  7. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/agent_usage_manager/cli.py +5 -0
  8. agent_usage_manager-0.3.0/agent_usage_manager/static/index.html +847 -0
  9. agent_usage_manager-0.3.0/docs/reference.md +375 -0
  10. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/pyproject.toml +16 -5
  11. agent_usage_manager-0.2.6/.github/workflows/ci.yml +0 -25
  12. agent_usage_manager-0.2.6/.github/workflows/publish.yml +0 -41
  13. agent_usage_manager-0.2.6/AGENTS.md +0 -58
  14. agent_usage_manager-0.2.6/CLAUDE.md +0 -1
  15. agent_usage_manager-0.2.6/PKG-INFO +0 -560
  16. agent_usage_manager-0.2.6/README.md +0 -525
  17. agent_usage_manager-0.2.6/agent_usage_manager/static/index.html +0 -421
  18. agent_usage_manager-0.2.6/demo.tape +0 -23
  19. agent_usage_manager-0.2.6/docs/dashboard-live.gif +0 -0
  20. agent_usage_manager-0.2.6/docs/dashboard-live.png +0 -0
  21. agent_usage_manager-0.2.6/docs/dashboard.png +0 -0
  22. agent_usage_manager-0.2.6/docs/demo.gif +0 -0
  23. agent_usage_manager-0.2.6/docs/design/HLD.md +0 -120
  24. agent_usage_manager-0.2.6/docs/design/LLD.md +0 -408
  25. agent_usage_manager-0.2.6/requirements.txt +0 -4
  26. agent_usage_manager-0.2.6/run.sh +0 -11
  27. agent_usage_manager-0.2.6/tests/test_design_docs.py +0 -299
  28. agent_usage_manager-0.2.6/tests/test_smoke.py +0 -596
  29. agent_usage_manager-0.2.6/tests/test_synthetic.py +0 -434
  30. agent_usage_manager-0.2.6/uv.lock +0 -1260
  31. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/LICENSE +0 -0
  32. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/agent_usage_manager/__init__.py +0 -0
  33. {agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/agent_usage_manager/agents.default.yaml +0 -0
{agent_usage_manager-0.2.6 → agent_usage_manager-0.3.0}/.gitignore RENAMED
@@ -4,6 +4,7 @@ __pycache__/
4
4
  venv/
5
5
  .DS_Store
6
6
  agents.local.yaml
7
+ agent_usage_manager/agents.yaml
7
8
  dist/
8
9
  build/
9
10
  *.egg-info/
agent_usage_manager-0.3.0/CHANGELOG.md ADDED
@@ -0,0 +1,75 @@
1
+ # Changelog
2
+
3
+ Notable changes to `agent-usage-manager` are recorded here. GitHub Releases
4
+ remain the source for release artifacts.
5
+
6
+ ## Unreleased
7
+
8
+ ## 0.3.0 - 2026-09-13
9
+
10
+ ### Added
11
+
12
+ - Compact resource triage with CPU/memory sorting, runtime and warning filters,
13
+ process search, and an optional inspector on desktop and phone layouts.
14
+ - Measured warning evidence and CPU/RSS history. Saved warning links preserve
15
+ the first observation after clearance, with at most 100 warnings retained
16
+ in memory for up to 48 hours; restart clears them.
17
+ - Structured alert fields for a plain-language title, exact process identity,
18
+ and an optional inspection URL configured with `alerts.dashboard_url`.
19
+ - Reviewed process-tree revisions and explicit captured, signaled, skipped,
20
+ stopped, and surviving process identities in stop results and the action log.
21
+
22
+ ### Changed
23
+
24
+ - API v2 uses one shared three-second sampler, reports stale collection as
25
+ unavailable, and exposes runtime, instance, warning, and delivery metadata.
26
+ - Actionable stop requests require the exact `create_time` from the displayed
27
+ row. The dashboard also checks the reviewed tree revision before signaling.
28
+ - Stop review stays bound to the child details actually displayed, including
29
+ while text selection defers a refresh; changed or unavailable scope disables it.
30
+ - Failed alert commands retry while the condition persists, with visible
31
+ delivery state and a bounded three-attempt limit.
32
+ - Runtime-wide short-lived exits are separated from proven launchd service
33
+ restart evidence. Process labels and working directories remain navigation
34
+ hints rather than claims about task identity or progress.
35
+ - Dashboard HTML requires cache revalidation after an upgrade. The standalone
36
+ home link stays within the local AUM installation.
37
+ - Reworked the README into a concise front door and moved operator detail into
38
+ `docs/reference.md`.
39
+ - Added a security policy, private-reporting path, contribution guide, and
40
+ privacy-aware bug report form.
41
+ - Added current changelog, documentation, and security links to package metadata.
42
+ - Improved the dashboard at mid-width and phone sizes; clipboard denial now
43
+ fails visibly and leaves the stop command selected for manual copy.
44
+
45
+ ### Security and privacy
46
+
47
+ - Stopped tracking the maintainer's operational `agents.yaml`. The current
48
+ source tree keeps that file local and Git-ignored while future releases
49
+ continue to ship only the sanitized `agents.default.yaml`.
50
+ - Removed identifying dashboard captures from the current source tree.
51
+
52
+ ### Upgrade notes
53
+
54
+ - API clients that stop processes must send the exact `create_time` returned by
55
+ `/api/agents`; actionable requests without it return HTTP 428. Use the
56
+ `tree_revision` returned by `/api/tree/{pid}` to reject a changed reviewed
57
+ scope with HTTP 409 before any signal. Refresh an open dashboard after upgrade.
58
+ - Warning history is temporary. A retention deadline is a maximum, and the
59
+ 100-warning cap or a restart can remove an observation earlier.
60
+
61
+ ## 0.2.6 - 2026-08-22
62
+
63
+ ### Fixed
64
+
65
+ - The wheel and sdist now exclude the maintainer's operational configuration
66
+ and ship `agents.default.yaml` as the clean fallback.
67
+ - Removed a maintainer-specific trusted hostname from the DNS-rebinding guard.
68
+ Proxy hostnames are opt-in through `AUM_TRUSTED_HOSTS`.
69
+
70
+ For earlier history, see
71
+ [GitHub Releases](https://github.com/minglong51/agent-usage-manager/releases).
72
+
73
+ [Unreleased]: https://github.com/minglong51/agent-usage-manager/compare/v0.3.0...HEAD
74
+ [0.3.0]: https://github.com/minglong51/agent-usage-manager/releases/tag/v0.3.0
75
+ [0.2.6]: https://github.com/minglong51/agent-usage-manager/releases/tag/v0.2.6
agent_usage_manager-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,189 @@
1
+ Metadata-Version: 2.5
2
+ Name: agent-usage-manager
3
+ Version: 0.3.0
4
+ Summary: Local htop-style dashboard and guarded kill switch for headless AI-agent processes.
5
+ Project-URL: Homepage, https://github.com/minglong51/agent-usage-manager
6
+ Project-URL: Repository, https://github.com/minglong51/agent-usage-manager
7
+ Project-URL: Issues, https://github.com/minglong51/agent-usage-manager/issues
8
+ Project-URL: Documentation, https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md
9
+ Project-URL: Changelog, https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md
10
+ Project-URL: Security, https://github.com/minglong51/agent-usage-manager/security/policy
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: ai-agents,gpu,llm,monitoring,observability,ollama,vllm
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: System Administrators
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: MacOS :: MacOS X
20
+ Classifier: Operating System :: POSIX :: Linux
21
+ Classifier: Programming Language :: Python :: 3
22
+ Classifier: Programming Language :: Python :: 3.9
23
+ Classifier: Programming Language :: Python :: 3.10
24
+ Classifier: Programming Language :: Python :: 3.11
25
+ Classifier: Programming Language :: Python :: 3.12
26
+ Classifier: Topic :: System :: Monitoring
27
+ Classifier: Topic :: System :: Systems Administration
28
+ Requires-Python: >=3.9
29
+ Requires-Dist: fastapi>=0.110
30
+ Requires-Dist: psutil>=5.9
31
+ Requires-Dist: pyyaml>=6.0
32
+ Requires-Dist: uvicorn[standard]>=0.27
33
+ Provides-Extra: dev
34
+ Requires-Dist: httpx>=0.27; extra == 'dev'
35
+ Requires-Dist: pytest>=7; extra == 'dev'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # agent-usage-manager
39
+
40
+ [![CI](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml)
41
+ [![PyPI](https://img.shields.io/pypi/v/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
42
+ [![Python](https://img.shields.io/pypi/pyversions/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
43
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/minglong51/agent-usage-manager/blob/main/LICENSE)
44
+
45
+ A local `htop`-style dashboard for headless AI-agent processes. It groups each
46
+ agent's process tree, tracks CPU/RAM/GPU and sustained hot/idle/churn/leak
47
+ states, and provides an allowlisted, token-gated stop control.
48
+
49
+ **Per-node only:** AUM is not a scheduler or multi-host control plane. It runs
50
+ on macOS and Linux; per-process GPU memory is currently NVIDIA/Linux only.
51
+
52
+ ![agent-usage-manager dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
53
+
54
+ *Sanitized capture from a real macOS run. Host, path, and command details are
55
+ replaced; Apple Silicon does not expose per-process GPU memory.*
56
+
57
+ ## Quick start
58
+
59
+ ```bash
60
+ uvx agent-usage-manager
61
+ ```
62
+
63
+ The dashboard opens at `http://127.0.0.1:8765`. No database or hosted service is
64
+ required. The bundled config recognizes common tools including Claude Code,
65
+ Codex, OpenClaw, Hermes, Ollama, vLLM, llama.cpp, Kiro, Aider, and Cline.
66
+
67
+ Other install options:
68
+
69
+ ```bash
70
+ pipx install agent-usage-manager
71
+ # or, inside a virtual environment:
72
+ pip install agent-usage-manager
73
+ ```
74
+
75
+ ## What it does
76
+
77
+ - **One row per agent.** Child inference processes, MCP servers, and helpers are
78
+ rolled into the owning agent's row. CPU, memory, and GPU values are tree totals.
79
+ - **Shows change over time.** CPU sparklines and `hot`, `idle`, `churn`, and
80
+ `leak?` states surface sustained problems rather than one noisy sample.
81
+ - **Supports alerts.** A state transition can call a local command with `$AUM_*`
82
+ environment variables. `agent-usage-manager test-alert` proves the path first.
83
+ - **Stops the process tree.** `kill` sends SIGTERM and escalates after three
84
+ seconds; `force` sends SIGKILL. launchd-supervised jobs get the command that
85
+ actually stops the service.
86
+ - **Exposes read-only telemetry.** Use `agent-usage-manager list --json`,
87
+ `GET /api/agents`, or Prometheus-compatible `GET /metrics`.
88
+ - **Keeps the control local.** The default bind is `127.0.0.1`; there is no
89
+ account, remote collector, or central coordinator.
90
+
91
+ AUM complements process and telemetry tools:
92
+
93
+ - `htop` sees processes, but not ownership of a spawned agent tree or agent states.
94
+ - Grafana and Prometheus are useful fleet telemetry; AUM can feed them without
95
+ requiring that stack for a single machine.
96
+ - GenAI traces describe sessions, tokens, and cost. AUM covers the host-process
97
+ side: liveness, resource pressure, restart churn, and local stop control.
98
+
99
+ ## Configure agents
100
+
101
+ Create `agents.yaml` in the directory where you launch AUM, or pass
102
+ `--config /path/to/agents.yaml`:
103
+
104
+ ```yaml
105
+ agents:
106
+ - label: claude-code
107
+ match: "claude(\\s|$|-code)"
108
+ regex: true
109
+ - label: ollama
110
+ match: ollama
111
+
112
+ protect:
113
+ - uvicorn
114
+
115
+ ignore:
116
+ - crashpad
117
+ ```
118
+
119
+ Only matched processes are listed or stoppable. `protect:` keeps a matched
120
+ process visible but disables stopping it; `ignore:` removes a false match
121
+ entirely. Edits hot-reload while the server runs.
122
+
123
+ Advanced matching, per-instance tmux/launchd labels, alerts, API details,
124
+ service setup, and troubleshooting are in the
125
+ [operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md).
126
+
127
+ ## Safety boundary
128
+
129
+ A web page that can stop processes needs a narrow boundary:
130
+
131
+ - The server re-checks the allowlist before every signal. PID 1, AUM itself, and
132
+ configured `protect:` matches are always refused.
133
+ - Every stop request requires an `X-Kill-Token`. AUM creates the token in a
134
+ mode-`0600` state file and never serves it over HTTP.
135
+ - Browser requests are checked for DNS-rebinding and cross-origin state changes.
136
+ - Non-loopback binds fail closed unless `--unsafe-expose` is explicit.
137
+ - Every stop attempt and refusal is appended to a local action log.
138
+ - Common token and key shapes are redacted before command lines reach the UI.
139
+ Redaction is not a substitute for reviewing screenshots and issue attachments.
140
+ - Read-only endpoints still expose process metadata. Keep AUM on a trusted
141
+ machine or put an authenticated boundary in front of any proxy.
142
+
143
+ Report vulnerabilities privately through the
144
+ [security policy](https://github.com/minglong51/agent-usage-manager/security/policy). Do not open a public issue for a kill-path,
145
+ authorization, redaction, or package-privacy defect.
146
+
147
+ ## Limits
148
+
149
+ | Area | Current boundary |
150
+ |---|---|
151
+ | Process matching | Heuristic; use `ignore:` for false positives |
152
+ | GPU | Per-process values require `nvidia-smi`; unavailable on Apple Silicon |
153
+ | Supervision | launchd user jobs detected; systemd supervision is not |
154
+ | Permissions | AUM can only signal processes accessible to its OS user |
155
+ | History | In memory and reset when the server restarts |
156
+ | Windows | Untested; CI covers macOS and Linux |
157
+
158
+ ## Command-line and API entry points
159
+
160
+ ```bash
161
+ agent-usage-manager # dashboard
162
+ agent-usage-manager list # one-shot table
163
+ agent-usage-manager list --json # scriptable snapshot
164
+ agent-usage-manager test-alert # verify configured alert delivery
165
+ ```
166
+
167
+ The HTTP surface is documented in the
168
+ [operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md). External controllers should consume
169
+ the read-only endpoints and own their own scheduling or irreversible decisions.
170
+
171
+ ## Project documentation
172
+
173
+ - [Operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md): configuration, alerts, API, services,
174
+ proxying, and troubleshooting
175
+ - [Changelog](https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md): current release and unreleased changes
176
+ - [Security policy](https://github.com/minglong51/agent-usage-manager/security/policy): supported versions and private reporting
177
+ - [Contributing](https://github.com/minglong51/agent-usage-manager/blob/main/CONTRIBUTING.md): setup, scope, and privacy requirements
178
+ - [Architecture](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/HLD.md) and [implementation design](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/LLD.md)
179
+
180
+ If AUM misclassifies a process or behaves differently on macOS or Linux,
181
+ [open a bug report](https://github.com/minglong51/agent-usage-manager/issues/new?template=bug_report.yml)
182
+ with sanitized output. Never attach a live config, token file, or unreviewed
183
+ process command line.
184
+
185
+ AUM is a personal open-source project. Maintenance and support are best-effort.
186
+
187
+ ## License
188
+
189
+ MIT
agent_usage_manager-0.3.0/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # agent-usage-manager
2
+
3
+ [![CI](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/minglong51/agent-usage-manager/blob/main/LICENSE)
7
+
8
+ A local `htop`-style dashboard for headless AI-agent processes. It groups each
9
+ agent's process tree, tracks CPU/RAM/GPU and sustained hot/idle/churn/leak
10
+ states, and provides an allowlisted, token-gated stop control.
11
+
12
+ **Per-node only:** AUM is not a scheduler or multi-host control plane. It runs
13
+ on macOS and Linux; per-process GPU memory is currently NVIDIA/Linux only.
14
+
15
+ ![agent-usage-manager dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
16
+
17
+ *Sanitized capture from a real macOS run. Host, path, and command details are
18
+ replaced; Apple Silicon does not expose per-process GPU memory.*
19
+
20
+ ## Quick start
21
+
22
+ ```bash
23
+ uvx agent-usage-manager
24
+ ```
25
+
26
+ The dashboard opens at `http://127.0.0.1:8765`. No database or hosted service is
27
+ required. The bundled config recognizes common tools including Claude Code,
28
+ Codex, OpenClaw, Hermes, Ollama, vLLM, llama.cpp, Kiro, Aider, and Cline.
29
+
30
+ Other install options:
31
+
32
+ ```bash
33
+ pipx install agent-usage-manager
34
+ # or, inside a virtual environment:
35
+ pip install agent-usage-manager
36
+ ```
37
+
38
+ ## What it does
39
+
40
+ - **One row per agent.** Child inference processes, MCP servers, and helpers are
41
+ rolled into the owning agent's row. CPU, memory, and GPU values are tree totals.
42
+ - **Shows change over time.** CPU sparklines and `hot`, `idle`, `churn`, and
43
+ `leak?` states surface sustained problems rather than one noisy sample.
44
+ - **Supports alerts.** A state transition can call a local command with `$AUM_*`
45
+ environment variables. `agent-usage-manager test-alert` proves the path first.
46
+ - **Stops the process tree.** `kill` sends SIGTERM and escalates after three
47
+ seconds; `force` sends SIGKILL. launchd-supervised jobs get the command that
48
+ actually stops the service.
49
+ - **Exposes read-only telemetry.** Use `agent-usage-manager list --json`,
50
+ `GET /api/agents`, or Prometheus-compatible `GET /metrics`.
51
+ - **Keeps the control local.** The default bind is `127.0.0.1`; there is no
52
+ account, remote collector, or central coordinator.
53
+
54
+ AUM complements process and telemetry tools:
55
+
56
+ - `htop` sees processes, but not ownership of a spawned agent tree or agent states.
57
+ - Grafana and Prometheus are useful fleet telemetry; AUM can feed them without
58
+ requiring that stack for a single machine.
59
+ - GenAI traces describe sessions, tokens, and cost. AUM covers the host-process
60
+ side: liveness, resource pressure, restart churn, and local stop control.
61
+
62
+ ## Configure agents
63
+
64
+ Create `agents.yaml` in the directory where you launch AUM, or pass
65
+ `--config /path/to/agents.yaml`:
66
+
67
+ ```yaml
68
+ agents:
69
+ - label: claude-code
70
+ match: "claude(\\s|$|-code)"
71
+ regex: true
72
+ - label: ollama
73
+ match: ollama
74
+
75
+ protect:
76
+ - uvicorn
77
+
78
+ ignore:
79
+ - crashpad
80
+ ```
81
+
82
+ Only matched processes are listed or stoppable. `protect:` keeps a matched
83
+ process visible but disables stopping it; `ignore:` removes a false match
84
+ entirely. Edits hot-reload while the server runs.
85
+
86
+ Advanced matching, per-instance tmux/launchd labels, alerts, API details,
87
+ service setup, and troubleshooting are in the
88
+ [operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md).
89
+
90
+ ## Safety boundary
91
+
92
+ A web page that can stop processes needs a narrow boundary:
93
+
94
+ - The server re-checks the allowlist before every signal. PID 1, AUM itself, and
95
+ configured `protect:` matches are always refused.
96
+ - Every stop request requires an `X-Kill-Token`. AUM creates the token in a
97
+ mode-`0600` state file and never serves it over HTTP.
98
+ - Browser requests are checked for DNS-rebinding and cross-origin state changes.
99
+ - Non-loopback binds fail closed unless `--unsafe-expose` is explicit.
100
+ - Every stop attempt and refusal is appended to a local action log.
101
+ - Common token and key shapes are redacted before command lines reach the UI.
102
+ Redaction is not a substitute for reviewing screenshots and issue attachments.
103
+ - Read-only endpoints still expose process metadata. Keep AUM on a trusted
104
+ machine or put an authenticated boundary in front of any proxy.
105
+
106
+ Report vulnerabilities privately through the
107
+ [security policy](https://github.com/minglong51/agent-usage-manager/security/policy). Do not open a public issue for a kill-path,
108
+ authorization, redaction, or package-privacy defect.
109
+
110
+ ## Limits
111
+
112
+ | Area | Current boundary |
113
+ |---|---|
114
+ | Process matching | Heuristic; use `ignore:` for false positives |
115
+ | GPU | Per-process values require `nvidia-smi`; unavailable on Apple Silicon |
116
+ | Supervision | launchd user jobs detected; systemd supervision is not |
117
+ | Permissions | AUM can only signal processes accessible to its OS user |
118
+ | History | In memory and reset when the server restarts |
119
+ | Windows | Untested; CI covers macOS and Linux |
120
+
121
+ ## Command-line and API entry points
122
+
123
+ ```bash
124
+ agent-usage-manager # dashboard
125
+ agent-usage-manager list # one-shot table
126
+ agent-usage-manager list --json # scriptable snapshot
127
+ agent-usage-manager test-alert # verify configured alert delivery
128
+ ```
129
+
130
+ The HTTP surface is documented in the
131
+ [operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md). External controllers should consume
132
+ the read-only endpoints and own their own scheduling or irreversible decisions.
133
+
134
+ ## Project documentation
135
+
136
+ - [Operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md): configuration, alerts, API, services,
137
+ proxying, and troubleshooting
138
+ - [Changelog](https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md): current release and unreleased changes
139
+ - [Security policy](https://github.com/minglong51/agent-usage-manager/security/policy): supported versions and private reporting
140
+ - [Contributing](https://github.com/minglong51/agent-usage-manager/blob/main/CONTRIBUTING.md): setup, scope, and privacy requirements
141
+ - [Architecture](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/HLD.md) and [implementation design](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/LLD.md)
142
+
143
+ If AUM misclassifies a process or behaves differently on macOS or Linux,
144
+ [open a bug report](https://github.com/minglong51/agent-usage-manager/issues/new?template=bug_report.yml)
145
+ with sanitized output. Never attach a live config, token file, or unreviewed
146
+ process command line.
147
+
148
+ AUM is a personal open-source project. Maintenance and support are best-effort.
149
+
150
+ ## License
151
+
152
+ MIT
agent_usage_manager-0.3.0/SECURITY.md ADDED
@@ -0,0 +1,46 @@
1
+ # Security policy
2
+
3
+ `agent-usage-manager` exposes local process metadata and a stop endpoint. Please
4
+ report vulnerabilities privately.
5
+
6
+ ## Supported versions
7
+
8
+ | Version | Supported |
9
+ |---|---|
10
+ | Latest PyPI release | Yes |
11
+ | Older releases | No |
12
+
13
+ Security fixes are made against the latest release. Upgrade before reporting a
14
+ problem that may already be fixed.
15
+
16
+ ## Report privately
17
+
18
+ Use
19
+ [GitHub private vulnerability reporting](https://github.com/minglong51/agent-usage-manager/security/advisories/new).
20
+
21
+ Do not open a public issue for:
22
+
23
+ - bypasses of the process allowlist, protected-process checks, or kill token
24
+ - cross-origin, DNS-rebinding, or non-loopback exposure problems
25
+ - command-line redaction bypasses
26
+ - package contents that expose maintainer or user configuration
27
+ - action-log or token-file permission problems
28
+
29
+ Include the AUM version, operating system, installation method, reproduction
30
+ steps, expected impact, and the smallest safe evidence needed to reproduce the
31
+ problem.
32
+
33
+ Do not attach a live `agents.yaml`, kill token, full process command line,
34
+ hostname, home-directory path, or unsanitized screenshot. Replace identifying
35
+ values before submitting.
36
+
37
+ ## What to expect
38
+
39
+ This is a personal open-source project maintained on a best-effort basis, with
40
+ no response-time SLA. The maintainer will acknowledge a reproducible report,
41
+ work toward a fix, and coordinate disclosure when the issue is resolved.
42
+
43
+ A local user who already has permission to signal the same processes is outside
44
+ the threat boundary. Unsafe deployment choices, such as exposing read endpoints
45
+ without an authenticated proxy, are also outside the default boundary unless
46
+ AUM fails to enforce a documented guard.