agentburn 0.2.0__tar.gz

agentburn-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ion
+
+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.

agentburn-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: agentburn
+Version: 0.2.0
+Summary: Where does your AI agent burn money? Local token/cost profiler for always-on agents (Hermes Agent first). Zero dependencies.
+Author: Ion
+License: MIT
+Project-URL: Homepage, https://github.com/Socialpranker/agentburn
+Keywords: hermes-agent,tokens,cost,profiler,ai-agents,openrouter
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agentburn
+
+> **Where does your AI agent burn money — while you sleep?**
+
+Always-on agents bill you around the clock. Hermes Agent users wake up to
+[**$47 overnight bills**](https://dev.to/chintanonweb/hermes-agent-gets-smarter-every-day-so-does-the-bill-4i8o)
+from recursive subagent runs; one user measured that
+[**73% of every API call is fixed overhead**](https://github.com/NousResearch/hermes-agent/issues/4379)
+(tool definitions + system prompt, resent every time); chained delegation means
+*"step 3 costs 4× step 1 — no alert, just a bill."* Built-in `/usage` shows totals.
+Nothing shows **where** it burns.
+
+agentburn is a local profiler for your agent's own accounting database. One command, zero dependencies, nothing leaves your machine:
+
+```bash
+uvx agentburn          # or: pipx run agentburn / pip install agentburn
+```
+
+```text
+🔥 agentburn — hermes · last 30d
+
+   ~$45.50 total · 1.75M tokens · 7 sessions · 123 API calls
+   ≈ ~$431.24/month at the current pace
+
+   WHERE IT BURNS (by source)
+   cron                 ██████████████····  79%     ~$36.00    1.24M  2 sess
+   cli                  ██················   9%      ~$4.00     185K  1 sess
+   gateway:telegram     █·················   7%      ~$3.00     210K  1 sess
+   subagent             █·················   5%      ~$2.50     113K  2 sess
+
+   🌙 WHILE YOU SLEPT (00:00–08:00): ~$36.00 (79% of spend) · 2 sessions
+      mostly: cron
+
+   FIXED OVERHEAD (avg input tokens per API call)
+   gateway:telegram       20,000 ← heavy
+   cron                   15,000 ← heavy
+      input composition (sampled from 3 request dumps): system 30% · tools 58% · history 12%
+
+   💡 DO THIS
+   1. 79% of spend happens at night — that's ≈$341/mo while you sleep. Route night work to a cheaper model.
+   2. Scheduled (cron) sessions run on anthropic/claude-opus-x — maintenance rarely needs a frontier model.
+   3. 20,000 input tokens per call on telegram: trim per-platform toolsets, prune unused skills.
+```
+
+## What it answers
+
+- **Where it burns** — by source: `cron` / `subagent` / `gateway:telegram|discord|whatsapp` / `cli`. Always-on ≠ free: scheduled jobs and gateways spend without you.
+- **🌙 While you slept** — the overnight bill, isolated and named (configurable window: `--night 23-7`).
+- **Fixed overhead** — average input tokens per API call per source. The "73% overhead" pattern is visible in one glance; with request dumps enabled, you get the sampled composition (system prompt vs tool definitions vs history).
+- **Subagent rollups** — delegation cost chained back to the session that spawned it. Recursion compounds; here is the receipt.
+- **Top tools** — which tool results weigh most in your context.
+- **What to do** — up to 4 conservative, named recommendations with monthly estimates.
+
+## Why trust these numbers
+
+Most token trackers quietly disagree with each other (2–91× in public issue threads). agentburn takes the opposite stance:
+
+- Numbers come from **the agent's own accounting** (`~/.hermes/state.db`: per-session token counters and cost fields). No scraping, no proxies, no guessing.
+- Provider-billed costs are shown as-is; Hermes estimates are marked with `~`. Mixed data is labeled mixed.
+- Sessions with messages but **zero recorded tokens** (known Hermes accounting gaps, e.g. [#12023](https://github.com/NousResearch/hermes-agent/issues/12023)) are detected and reported: totals are then explicitly a **lower bound** — and fixing the accounting becomes recommendation #1.
+- Input composition from request dumps is char-proportional and labeled *sampled estimate*, not truth.
+
+## Privacy
+
+Everything runs locally and reads your database **read-only**. No network calls. No telemetry. The report is yours.
+
+## Usage
+
+```bash
+agentburn                  # autodetect agent, last 30 days
+agentburn --days 7
+agentburn --db /path/to/state.db
+agentburn --night 23-7     # custom overnight window (local time)
+agentburn --json           # machine-readable, pipe it anywhere
+agentburn --no-color
+```
+
+## Mechanics
+
+**📤 Share your burn (`--share`).** An anonymized card — categories, models and totals only; session titles, paths and content are excluded *by construction*. Safe to paste into a post; `--svg card.svg` renders the same card as an image:
+
+```text
+🔥 my hermes agent · last 30d
+~$45.50 · 1.75M tokens → ~$430/mo pace
+cron 79% · cli 9% · telegram 7% · subagent 5%
+🌙 while I slept (00–08): ~$36.00 (79%)
+heaviest overhead: telegram 20,000 tokens/call (community baseline ≈8k/call: +150%)
+```
+
+**📏 Calibration against public benchmarks.** "Is 15k input tokens per call normal?" The report compares your fixed overhead with community-measured references embedded as dated constants (e.g. the [Phala always-on-agent benchmark](https://phala.com/posts/understanding-openclaws-token-usage), 2026-03: ≈8k/call baseline). No network — sources are cited inline.
+
+**📐 Optimize → prove it (`--save-baseline` / `--compare`).** Snapshot your pace, change the config (cheaper cron model, trimmed toolsets), then `agentburn --compare` shows the delta in $/month — pace-normalized, so a 7-day baseline compares honestly with a 30-day window. Every recommendation becomes a testable promise.
+
+**🩺 `agentburn doctor`.** Trackers disagree because the agent's own accounting has gaps. doctor names the broken combinations (provider × model × source) for zero-usage and unpriced sessions, and generates a ready-to-paste upstream bug report — counters only, no message content.
+
+## Supported agents
+
+| Agent | Status | Data source |
+|---|---|---|
+| **Hermes Agent** | ✅ v0.1 | `~/.hermes/state.db` (+ optional `request_dump_*.json` for input composition) |
+| OpenClaw | roadmap | session JSONL |
+| Claude Code | roadmap | `~/.claude/projects/**.jsonl` |
+
+The core is agent-agnostic (normalized session/event model); adapters are ~150 lines each. PRs welcome.
+
+## Related
+
+[token-history](https://github.com/Socialpranker/token-history) — the macro view: daily archive of *which agents the world uses* (OpenRouter rankings). agentburn is the micro view: *where yours burns*.
+
+## License
+
+MIT

agentburn-0.2.0/README.md

@@ -0,0 +1,112 @@
+# agentburn
+
+> **Where does your AI agent burn money — while you sleep?**
+
+Always-on agents bill you around the clock. Hermes Agent users wake up to
+[**$47 overnight bills**](https://dev.to/chintanonweb/hermes-agent-gets-smarter-every-day-so-does-the-bill-4i8o)
+from recursive subagent runs; one user measured that
+[**73% of every API call is fixed overhead**](https://github.com/NousResearch/hermes-agent/issues/4379)
+(tool definitions + system prompt, resent every time); chained delegation means
+*"step 3 costs 4× step 1 — no alert, just a bill."* Built-in `/usage` shows totals.
+Nothing shows **where** it burns.
+
+agentburn is a local profiler for your agent's own accounting database. One command, zero dependencies, nothing leaves your machine:
+
+```bash
+uvx agentburn          # or: pipx run agentburn / pip install agentburn
+```
+
+```text
+🔥 agentburn — hermes · last 30d
+
+   ~$45.50 total · 1.75M tokens · 7 sessions · 123 API calls
+   ≈ ~$431.24/month at the current pace
+
+   WHERE IT BURNS (by source)
+   cron                 ██████████████····  79%     ~$36.00    1.24M  2 sess
+   cli                  ██················   9%      ~$4.00     185K  1 sess
+   gateway:telegram     █·················   7%      ~$3.00     210K  1 sess
+   subagent             █·················   5%      ~$2.50     113K  2 sess
+
+   🌙 WHILE YOU SLEPT (00:00–08:00): ~$36.00 (79% of spend) · 2 sessions
+      mostly: cron
+
+   FIXED OVERHEAD (avg input tokens per API call)
+   gateway:telegram       20,000 ← heavy
+   cron                   15,000 ← heavy
+      input composition (sampled from 3 request dumps): system 30% · tools 58% · history 12%
+
+   💡 DO THIS
+   1. 79% of spend happens at night — that's ≈$341/mo while you sleep. Route night work to a cheaper model.
+   2. Scheduled (cron) sessions run on anthropic/claude-opus-x — maintenance rarely needs a frontier model.
+   3. 20,000 input tokens per call on telegram: trim per-platform toolsets, prune unused skills.
+```
+
+## What it answers
+
+- **Where it burns** — by source: `cron` / `subagent` / `gateway:telegram|discord|whatsapp` / `cli`. Always-on ≠ free: scheduled jobs and gateways spend without you.
+- **🌙 While you slept** — the overnight bill, isolated and named (configurable window: `--night 23-7`).
+- **Fixed overhead** — average input tokens per API call per source. The "73% overhead" pattern is visible in one glance; with request dumps enabled, you get the sampled composition (system prompt vs tool definitions vs history).
+- **Subagent rollups** — delegation cost chained back to the session that spawned it. Recursion compounds; here is the receipt.
+- **Top tools** — which tool results weigh most in your context.
+- **What to do** — up to 4 conservative, named recommendations with monthly estimates.
+
+## Why trust these numbers
+
+Most token trackers quietly disagree with each other (2–91× in public issue threads). agentburn takes the opposite stance:
+
+- Numbers come from **the agent's own accounting** (`~/.hermes/state.db`: per-session token counters and cost fields). No scraping, no proxies, no guessing.
+- Provider-billed costs are shown as-is; Hermes estimates are marked with `~`. Mixed data is labeled mixed.
+- Sessions with messages but **zero recorded tokens** (known Hermes accounting gaps, e.g. [#12023](https://github.com/NousResearch/hermes-agent/issues/12023)) are detected and reported: totals are then explicitly a **lower bound** — and fixing the accounting becomes recommendation #1.
+- Input composition from request dumps is char-proportional and labeled *sampled estimate*, not truth.
+
+## Privacy
+
+Everything runs locally and reads your database **read-only**. No network calls. No telemetry. The report is yours.
+
+## Usage
+
+```bash
+agentburn                  # autodetect agent, last 30 days
+agentburn --days 7
+agentburn --db /path/to/state.db
+agentburn --night 23-7     # custom overnight window (local time)
+agentburn --json           # machine-readable, pipe it anywhere
+agentburn --no-color
+```
+
+## Mechanics
+
+**📤 Share your burn (`--share`).** An anonymized card — categories, models and totals only; session titles, paths and content are excluded *by construction*. Safe to paste into a post; `--svg card.svg` renders the same card as an image:
+
+```text
+🔥 my hermes agent · last 30d
+~$45.50 · 1.75M tokens → ~$430/mo pace
+cron 79% · cli 9% · telegram 7% · subagent 5%
+🌙 while I slept (00–08): ~$36.00 (79%)
+heaviest overhead: telegram 20,000 tokens/call (community baseline ≈8k/call: +150%)
+```
+
+**📏 Calibration against public benchmarks.** "Is 15k input tokens per call normal?" The report compares your fixed overhead with community-measured references embedded as dated constants (e.g. the [Phala always-on-agent benchmark](https://phala.com/posts/understanding-openclaws-token-usage), 2026-03: ≈8k/call baseline). No network — sources are cited inline.
+
+**📐 Optimize → prove it (`--save-baseline` / `--compare`).** Snapshot your pace, change the config (cheaper cron model, trimmed toolsets), then `agentburn --compare` shows the delta in $/month — pace-normalized, so a 7-day baseline compares honestly with a 30-day window. Every recommendation becomes a testable promise.
+
+**🩺 `agentburn doctor`.** Trackers disagree because the agent's own accounting has gaps. doctor names the broken combinations (provider × model × source) for zero-usage and unpriced sessions, and generates a ready-to-paste upstream bug report — counters only, no message content.
+
+## Supported agents
+
+| Agent | Status | Data source |
+|---|---|---|
+| **Hermes Agent** | ✅ v0.1 | `~/.hermes/state.db` (+ optional `request_dump_*.json` for input composition) |
+| OpenClaw | roadmap | session JSONL |
+| Claude Code | roadmap | `~/.claude/projects/**.jsonl` |
+
+The core is agent-agnostic (normalized session/event model); adapters are ~150 lines each. PRs welcome.
+
+## Related
+
+[token-history](https://github.com/Socialpranker/token-history) — the macro view: daily archive of *which agents the world uses* (OpenRouter rankings). agentburn is the micro view: *where yours burns*.
+
+## License
+
+MIT

agentburn-0.2.0/agentburn/__init__.py

@@ -0,0 +1,8 @@
+"""agentburn — where does your AI agent burn money?
+
+Local, zero-dependency token/cost profiler for always-on AI agents.
+Adapter #1: Hermes Agent (~/.hermes/state.db). Honest methodology:
+numbers come from the agent's own accounting; gaps are surfaced, not hidden.
+"""
+
+__version__ = "0.2.0"

agentburn-0.2.0/agentburn/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapter registry. v0.1 ships Hermes; OpenClaw and Claude Code are next."""
+
+from __future__ import annotations
+
+from . import hermes
+
+ADAPTERS = {
+    "hermes": hermes,
+}
+
+
+def detect() -> list[str]:
+    """Return adapter names whose data is present on this machine."""
+    return [name for name, mod in ADAPTERS.items() if mod.available()]

agentburn-0.2.0/agentburn/adapters/hermes.py

@@ -0,0 +1,239 @@
+"""Hermes Agent adapter: reads ~/.hermes/state.db (SQLite) read-only.
+
+Schema observed in NousResearch/hermes-agent `hermes_state.py` (June 2026):
+  sessions(id, source, model, parent_session_id, started_at, ended_at,
+           message_count, tool_call_count, api_call_count,
+           input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+           reasoning_tokens, estimated_cost_usd, actual_cost_usd, cost_status,
+           title, archived, ...)
+  messages(session_id, role, tool_name, tool_calls, timestamp, token_count, ...)
+
+Known upstream accounting gaps (hermes-agent #12023, #6775, #8337): some
+providers/streams record zero tokens. We DETECT and REPORT those gaps instead
+of silently presenting totals as truth.
+
+Optional precision layer: request_dump_*.json files (written when request
+dumping is enabled) contain the full API body; we sample them to estimate the
+input composition (system prompt vs tool definitions vs history).
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import sqlite3
+import time
+from typing import Optional
+
+from ..model import DumpComposition, SessionRec, Snapshot, ToolStat
+
+GATEWAY_SOURCES = {
+    "telegram",
+    "whatsapp",
+    "discord",
+    "slack",
+    "signal",
+    "imessage",
+    "email",
+    "api",
+    "api_server",
+    "web",
+}
+
+
+def default_db_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".hermes", "state.db")
+
+
+def available() -> bool:
+    return os.path.exists(default_db_path())
+
+
+def normalize_source(raw: Optional[str]) -> str:
+    s = (raw or "unknown").strip().lower()
+    if s in ("cli", "cron", "subagent"):
+        return s
+    if s in GATEWAY_SOURCES:
+        return f"gateway:{s}"
+    if s.startswith(("gateway:", "other:")):
+        return s
+    return f"other:{s}"
+
+
+def _columns(con: sqlite3.Connection, table: str) -> set:
+    try:
+        return {r[1] for r in con.execute(f"PRAGMA table_info({table})")}
+    except sqlite3.Error:
+        return set()
+
+
+def _col(cols: set, name: str, default_sql: str = "NULL") -> str:
+    return name if name in cols else f"{default_sql} AS {name}"
+
+
+def load(
+    db_path: Optional[str] = None,
+    days: Optional[int] = 30,
+    dumps_dir: Optional[str] = None,
+    now: Optional[float] = None,
+) -> Snapshot:
+    path = db_path or default_db_path()
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"Hermes state not found at {path}. Pass --db /path/to/state.db "
+            "or run on the machine where Hermes Agent lives."
+        )
+    now = now or time.time()
+    since = now - days * 86400 if days else 0
+
+    snap = Snapshot(
+        agent="hermes",
+        source_path=path,
+        generated_at=now,
+        days=days,
+    )
+
+    con = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    try:
+        con.row_factory = sqlite3.Row
+        scols = _columns(con, "sessions")
+        if "id" not in scols:
+            raise RuntimeError(
+                "sessions table not found — is this really a Hermes state.db? "
+                "(schema may have changed; please open an issue with `PRAGMA table_info(sessions)` output)"
+            )
+
+        fields = ", ".join(
+            [
+                "id",
+                _col(scols, "source", "'unknown'"),
+                _col(scols, "model"),
+                _col(scols, "parent_session_id"),
+                _col(scols, "started_at"),
+                _col(scols, "ended_at"),
+                _col(scols, "title"),
+                _col(scols, "message_count", "0"),
+                _col(scols, "api_call_count", "0"),
+                _col(scols, "input_tokens", "0"),
+                _col(scols, "output_tokens", "0"),
+                _col(scols, "cache_read_tokens", "0"),
+                _col(scols, "cache_write_tokens", "0"),
+                _col(scols, "reasoning_tokens", "0"),
+                _col(scols, "estimated_cost_usd"),
+                _col(scols, "actual_cost_usd"),
+                _col(scols, "billing_provider"),
+            ]
+        )
+        where = "WHERE COALESCE(started_at, 0) >= ?" if days else ""
+        rows = con.execute(
+            f"SELECT {fields} FROM sessions {where}", (since,) if days else ()
+        ).fetchall()
+
+        for r in rows:
+            actual = r["actual_cost_usd"]
+            est = r["estimated_cost_usd"]
+            cost, basis = (
+                (actual, "actual")
+                if actual is not None
+                else (est, "estimated")
+                if est is not None
+                else (None, "unknown")
+            )
+            snap.sessions.append(
+                SessionRec(
+                    id=str(r["id"]),
+                    source=normalize_source(r["source"]),
+                    model=r["model"],
+                    started_at=r["started_at"],
+                    ended_at=r["ended_at"],
+                    parent_id=r["parent_session_id"],
+                    title=r["title"],
+                    api_calls=int(r["api_call_count"] or 0),
+                    input_tokens=int(r["input_tokens"] or 0),
+                    output_tokens=int(r["output_tokens"] or 0),
+                    cache_read_tokens=int(r["cache_read_tokens"] or 0),
+                    cache_write_tokens=int(r["cache_write_tokens"] or 0),
+                    reasoning_tokens=int(r["reasoning_tokens"] or 0),
+                    cost_usd=float(cost) if cost is not None else None,
+                    cost_basis=basis,
+                    message_count=int(r["message_count"] or 0),
+                    provider=r["billing_provider"],
+                )
+            )
+
+        mcols = _columns(con, "messages")
+        if {"tool_name", "timestamp"} <= mcols:
+            tok = "COALESCE(token_count, 0)" if "token_count" in mcols else "0"
+            mwhere = "AND timestamp >= ?" if days else ""
+            for r in con.execute(
+                f"""SELECT tool_name, COUNT(*) AS calls, SUM({tok}) AS toks
+                    FROM messages
+                    WHERE tool_name IS NOT NULL AND tool_name != '' {mwhere}
+                    GROUP BY tool_name ORDER BY toks DESC""",
+                (since,) if days else (),
+            ):
+                snap.tools.append(
+                    ToolStat(name=r["tool_name"], calls=int(r["calls"]), result_tokens=int(r["toks"] or 0))
+                )
+    finally:
+        con.close()
+
+    comp = _sample_dumps(dumps_dir or os.path.join(os.path.dirname(path), "sessions"))
+    if comp:
+        snap.composition = comp
+    return snap
+
+
+def _sample_dumps(dumps_dir: str, limit: int = 20) -> Optional[DumpComposition]:
+    """Estimate input composition from request dumps (newest `limit` files).
+
+    Char-proportional split of the request body: system prompt vs tool
+    definitions vs message history. Proportions, not exact tokens — labeled
+    as sampled estimate in the report.
+    """
+    try:
+        files = sorted(glob.glob(os.path.join(dumps_dir, "request_dump_*.json")))[-limit:]
+    except OSError:
+        return None
+    if not files:
+        return None
+    sys_c = tools_c = hist_c = 0
+    samples = 0
+    for f in files:
+        try:
+            with open(f, "r", encoding="utf-8", errors="replace") as fh:
+                payload = json.load(fh)
+        except (OSError, json.JSONDecodeError):
+            continue
+        body = payload.get("body") or payload.get("request") or payload
+        if not isinstance(body, dict):
+            continue
+        msgs = body.get("messages") or []
+        tools = body.get("tools") or []
+        s = t = h = 0
+        if isinstance(body.get("system"), str):
+            s += len(body["system"])
+        for m in msgs if isinstance(msgs, list) else []:
+            chunk = len(json.dumps(m, ensure_ascii=False, default=str))
+            if isinstance(m, dict) and m.get("role") == "system":
+                s += chunk
+            else:
+                h += chunk
+        t = len(json.dumps(tools, ensure_ascii=False, default=str)) if tools else 0
+        total = s + t + h
+        if total <= 0:
+            continue
+        sys_c += s
+        tools_c += t
+        hist_c += h
+        samples += 1
+    total = sys_c + tools_c + hist_c
+    if samples == 0 or total == 0:
+        return None
+    return DumpComposition(
+        samples=samples,
+        system_share=sys_c / total,
+        tools_share=tools_c / total,
+        history_share=hist_c / total,
+    )