@hivey/cli 0.9.47 → 0.9.50

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.
@@ -0,0 +1,808 @@
1
+ #!/usr/bin/env python3
2
+ """hivey agent map: what runs on this Mac, what it costs, and how the pieces feed each other.
3
+
4
+ agent_map.py scan [--days 7] [--out FILE] collect everything into a snapshot (JSON)
5
+ agent_map.py stats [--days 7] print a summary (runs scan first)
6
+ agent_map.py log --agent NAME --provider P --model M [--in N] [--out N]
7
+ [--cache-read N] [--cache-write N] [--cost USD] [--note TEXT]
8
+ add one entry to the spend log
9
+ agent_map.py link FROM TO --via WHAT [--evidence TEXT] [--remove]
10
+ confirm (or remove) a link between two nodes
11
+ agent_map.py nightly [--model haiku] [--no-llm] [--open]
12
+ a full report in ~/.hivey/agent-map/reports/<date>/
13
+ agent_map.py open open the latest report (hivey menu → agent map)
14
+ agent_map.py schedule [install|remove|status|offer] [--at 06:30] [--model haiku]
15
+ agent_map.py schedule token --command "envsave get es_…" long-lived Claude login for the run
16
+ the nightly launchd run (com.hivey.agent-map)
17
+
18
+ Sources (all read-only):
19
+ scheduled jobs crontab, ~/.config/cron-catchup/jobs.tsv (+ `cron-catchup.py list` status),
20
+ ~/Library/LaunchAgents/*.plist (non-Apple) with `launchctl list` exit codes
21
+ live agents `hivey agent list`, plus claude/codex/grok/agy processes outside hivey
22
+ tokens Claude Code ~/.claude/projects/**/*.jsonl (also DeepSeek/OpenRouter/Muse agents,
23
+ which run through Claude Code), Codex ~/.codex/sessions (.jsonl/.jsonl.zst),
24
+ Grok ~/.grok/sessions/*/*/usage.json, claude-api-guard ledger,
25
+ hivey spend log ~/.hivey/spend/ledger.jsonl (this script's `log`)
26
+ links heuristic: two nodes whose scripts/briefs name the same Baserow table or the
27
+ same data folder; confirmed links live in ~/.hivey/agent-map/links.json
28
+
29
+ Costs are API-list-price estimates (prices in hivey_spend.PRICES, overridable in ~/.hivey/agent-map/prices.json).
30
+ Claude Code on a Max plan and Codex on Plus are not billed per token: their cost is "API-equivalent".
31
+ Python standard library only.
32
+ """
33
+ from __future__ import annotations
34
+
35
+ import argparse
36
+ import collections
37
+ import datetime as dt
38
+ import glob
39
+ import json
40
+ import os
41
+ import plistlib
42
+ import re
43
+ import shutil
44
+ import subprocess
45
+ import sys
46
+ from pathlib import Path
47
+
48
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
49
+ from hivey_spend import SPEND_LOG, agent_of, cost, prices, record_usage # noqa: E402 one price table
50
+
51
+ HOME = Path.home()
52
+ STATE = HOME / ".hivey" / "agent-map"
53
+ LINKS = STATE / "links.json"
54
+ GUARD_LEDGER = HOME / ".config" / "claude-api-guard" / "ledger.jsonl"
55
+
56
+ AGENT_CLIS = {"claude": "claude-code", "codex": "codex", "grok": "grok", "agy": "antigravity", "gemini": "antigravity"}
57
+
58
+
59
+ # ---------------------------------------------------------------- helpers
60
+
61
+ def sh(cmd: list[str], timeout: int = 20) -> str:
62
+ try:
63
+ return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout).stdout
64
+ except (OSError, subprocess.SubprocessError):
65
+ return ""
66
+
67
+
68
+ def load_json(path: Path, default):
69
+ try:
70
+ return json.loads(path.read_text())
71
+ except (OSError, ValueError):
72
+ return default
73
+
74
+
75
+ def short(path: str) -> str:
76
+ return path.replace(str(HOME), "~") if path else path
77
+
78
+
79
+ def since(days: int) -> dt.datetime:
80
+ return dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=days)
81
+
82
+
83
+ def parse_ts(s: str) -> dt.datetime | None:
84
+ try:
85
+ t = dt.datetime.fromisoformat(s.replace("Z", "+00:00"))
86
+ return t if t.tzinfo else t.replace(tzinfo=dt.timezone.utc)
87
+ except (ValueError, AttributeError):
88
+ return None
89
+
90
+
91
+ # ---------------------------------------------------------------- scheduled jobs
92
+
93
+ PATH_RE = re.compile(r"(?:~|/Users/[^/\s]+)/[\w.@%+-]+(?:/[\w.@%+-]+)*")
94
+
95
+
96
+ def paths_in(text: str) -> list[str]:
97
+ return [os.path.expanduser(m.replace("~", str(HOME), 1) if m.startswith("~") else m) for m in PATH_RE.findall(text)]
98
+
99
+
100
+ def log_path(command: str) -> str | None:
101
+ m = re.search(r">>?\s*(\S+\.log)", command)
102
+ return os.path.expanduser(m.group(1)) if m else None
103
+
104
+
105
+ def log_info(path: str | None) -> dict:
106
+ if not path or not os.path.isfile(path):
107
+ return {}
108
+ st = os.stat(path)
109
+ info = {"log": short(path), "log_modified": dt.datetime.fromtimestamp(st.st_mtime).isoformat(timespec="minutes")}
110
+ try:
111
+ with open(path, "rb") as f:
112
+ f.seek(max(0, st.st_size - 6000))
113
+ tail = f.read().decode("utf-8", "replace").splitlines()[-40:]
114
+ tail = [re.sub(r"\x1b\[[0-9;]*[A-Za-z]|\r", "", l)[:300] for l in tail]
115
+ errs = [l.strip() for l in tail
116
+ if re.search(r"error|traceback|exception|failed|fatal", l, re.I)
117
+ and not re.search(r"\b0 failed|failed:? 0\b|0 errors?\b|errors?:? 0\b|rerun picks", l, re.I)]
118
+ if errs:
119
+ info["last_error"] = errs[-1][:200]
120
+ info["errors"] = list(dict.fromkeys(e[:200] for e in errs))[-5:]
121
+ info["tail"] = tail
122
+ except OSError:
123
+ pass
124
+ return info
125
+
126
+
127
+ def job_agent(command: str, cwd: str | None = None) -> str:
128
+ """The agent a job belongs to: first path in the command under a known agent root."""
129
+ for p in ([cwd] if cwd else []) + paths_in(command):
130
+ name = agent_of(p)
131
+ if name.startswith(("~/", "home", "unknown", "/")) or name == "tmp":
132
+ continue
133
+ return name
134
+ return ""
135
+
136
+
137
+ def cron_jobs() -> list[dict]:
138
+ jobs = []
139
+ catchup_status = {}
140
+ cc = HOME / "bin" / "cron-catchup.py"
141
+ if cc.exists():
142
+ for line in sh([sys.executable, "-I", str(cc), "list"]).splitlines():
143
+ m = re.match(r"(\S+)\s+\[([^\]]+)\]\s+last run (\S+ \S+)\s+last due (\S+ \S+)\s+(\S+)", line)
144
+ if m:
145
+ catchup_status[m.group(1)] = {"last_run": m.group(3), "last_due": m.group(4), "state": m.group(5)}
146
+ tsv = HOME / ".config" / "cron-catchup" / "jobs.tsv"
147
+ catchup = {}
148
+ if tsv.exists():
149
+ for line in tsv.read_text().splitlines():
150
+ if not line.strip() or line.lstrip().startswith("#"):
151
+ continue
152
+ parts = line.split("\t")
153
+ if len(parts) >= 3:
154
+ catchup[parts[0]] = (parts[1], parts[2])
155
+ for name, (sched, cmd) in catchup.items():
156
+ st = catchup_status.get(name, {})
157
+ jobs.append({
158
+ "id": f"cron:{name}", "name": name, "kind": "cron (cron-catchup)", "schedule": sched,
159
+ "command": cmd, "agent": job_agent(cmd), "status": st.get("state", "?"),
160
+ "last_run": st.get("last_run"), **log_info(log_path(cmd)),
161
+ })
162
+ for line in sh(["crontab", "-l"]).splitlines():
163
+ s = line.strip()
164
+ if not s or s.startswith("#") or re.match(r"^\w+=", s) or "cron-catchup.py" in s:
165
+ continue
166
+ f = s.split(None, 5)
167
+ if len(f) < 6:
168
+ continue
169
+ sched, cmd = " ".join(f[:5]), f[5]
170
+ name = Path(paths_in(cmd)[0]).stem if paths_in(cmd) else cmd[:30]
171
+ jobs.append({
172
+ "id": f"cron:{name}", "name": name, "kind": "cron", "schedule": sched, "command": cmd,
173
+ "agent": job_agent(cmd), "status": "?", **log_info(log_path(cmd)),
174
+ })
175
+ return jobs
176
+
177
+
178
+ def describe_calendar(cal) -> str:
179
+ if isinstance(cal, list):
180
+ return "; ".join(describe_calendar(c) for c in cal)
181
+ if not isinstance(cal, dict):
182
+ return str(cal)
183
+ days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
184
+ t = f"{cal.get('Hour', '*'):0>2}:{cal.get('Minute', 0):0>2}" if "Hour" in cal else f"min {cal.get('Minute', 0)} hourly"
185
+ if "Weekday" in cal:
186
+ t = f"{days[cal['Weekday'] % 7]} {t}"
187
+ if "Day" in cal:
188
+ t = f"day {cal['Day']} {t}"
189
+ return t if "Weekday" in cal or "Day" in cal else f"daily {t}"
190
+
191
+
192
+ def calendar_period_hours(cal) -> float | None:
193
+ """How long a launchd calendar job may go without running (plus slack), or None."""
194
+ if isinstance(cal, list):
195
+ periods = [calendar_period_hours(c) for c in cal]
196
+ return min((p for p in periods if p), default=None)
197
+ if not isinstance(cal, dict):
198
+ return None
199
+ if "Day" in cal:
200
+ return 32 * 24
201
+ if "Weekday" in cal:
202
+ return 8 * 24
203
+ return 26 if "Hour" in cal else 2
204
+
205
+
206
+ def launchd_jobs() -> list[dict]:
207
+ status = {}
208
+ for line in sh(["launchctl", "list"]).splitlines()[1:]:
209
+ f = line.split("\t")
210
+ if len(f) == 3:
211
+ status[f[2]] = (f[0], f[1])
212
+ jobs = []
213
+ for plist in sorted(glob.glob(str(HOME / "Library/LaunchAgents/*.plist"))):
214
+ try:
215
+ with open(plist, "rb") as fh:
216
+ d = plistlib.load(fh)
217
+ except Exception:
218
+ continue
219
+ label = d.get("Label", Path(plist).stem)
220
+ if label.startswith(("com.apple.", "com.google.", "com.github.facebook")) or "updater" in label.lower():
221
+ continue
222
+ args = d.get("ProgramArguments") or [d.get("Program", "")]
223
+ cmd = " ".join(args)
224
+ if "StartCalendarInterval" in d:
225
+ sched = describe_calendar(d["StartCalendarInterval"])
226
+ elif "StartInterval" in d:
227
+ sched = f"every {d['StartInterval']}s"
228
+ elif d.get("KeepAlive") or d.get("RunAtLoad"):
229
+ sched = "always on" if d.get("KeepAlive") else "at login"
230
+ else:
231
+ sched = "on demand"
232
+ period_h = calendar_period_hours(d.get("StartCalendarInterval"))
233
+ pid, code = status.get(label, ("-", "?"))
234
+ state = "running" if pid != "-" else ("not loaded" if label not in status else ("ok" if code == "0" else f"exit {code}"))
235
+ jobs.append({
236
+ "id": f"launchd:{label}", "name": re.sub(r"^com\.(jcsancho|hivey)\.", "", label), "kind": "launchd",
237
+ "schedule": sched, "command": cmd, "agent": job_agent(cmd, d.get("WorkingDirectory")),
238
+ "status": state, **log_info(d.get("StandardOutPath") or d.get("StandardErrorPath")),
239
+ })
240
+ mod = jobs[-1].get("log_modified")
241
+ if period_h and mod and dt.datetime.now() - dt.datetime.fromisoformat(mod) > dt.timedelta(hours=period_h):
242
+ jobs[-1]["overdue"] = True # its log did not change since the last time it should have run
243
+ return jobs
244
+
245
+
246
+ # ---------------------------------------------------------------- live agents
247
+
248
+ def agent_logs() -> dict:
249
+ """Newest log in each agent's or swarm's logs/ folder."""
250
+ out = {}
251
+ for d in sorted(glob.glob(str(HOME / "agents/*/"))) + sorted(glob.glob(str(HOME / "swarms/*/"))):
252
+ if re.search(r"backup|-old|\.bak", d):
253
+ continue
254
+ logs = [p for p in glob.glob(os.path.join(d, "logs", "**", "*"), recursive=True)
255
+ if os.path.isfile(p) and p.endswith((".log", ".txt", ".jsonl", ".out"))]
256
+ if logs:
257
+ out[agent_of(d)] = log_info(max(logs, key=os.path.getmtime))
258
+ return out
259
+
260
+
261
+ def live_agents() -> list[dict]:
262
+ out = []
263
+ seen_cwds = set()
264
+ hv = shutil.which("hivey")
265
+ if hv:
266
+ try:
267
+ data = json.loads(sh([hv, "agent", "list"]) or "{}")
268
+ for a in data.get("result", {}).get("agents", []):
269
+ cwd = a.get("foreground_cwd") or a.get("cwd")
270
+ seen_cwds.add(cwd)
271
+ out.append({
272
+ "agent": agent_of(cwd), "cli": AGENT_CLIS.get(a.get("agent"), a.get("agent")),
273
+ "status": a.get("agent_status", "?"), "cwd": short(cwd), "where": f"hivey {a.get('pane_id')}",
274
+ "role": (a.get("tokens") or {}).get("role"), "session": (a.get("agent_session") or {}).get("value"),
275
+ "title": a.get("title") or a.get("terminal_title_stripped"),
276
+ })
277
+ except ValueError:
278
+ pass
279
+ for line in sh(["ps", "-axo", "pid=,etime=,command="]).splitlines():
280
+ f = line.split(None, 2)
281
+ if len(f) < 3:
282
+ continue
283
+ pid, etime, cmd = f
284
+ exe = os.path.basename(cmd.split()[0])
285
+ if exe not in AGENT_CLIS or "--version" in cmd or ".app/" in cmd:
286
+ continue
287
+ cwd = ""
288
+ for l in sh(["lsof", "-a", "-p", pid, "-d", "cwd", "-Fn"], timeout=5).splitlines():
289
+ if l.startswith("n"):
290
+ cwd = l[1:]
291
+ if cwd in seen_cwds:
292
+ continue
293
+ headless = " -p " in f" {cmd} " or " exec " in f" {cmd} "
294
+ out.append({
295
+ "agent": agent_of(cwd), "cli": AGENT_CLIS[exe], "status": "running", "cwd": short(cwd),
296
+ "where": f"pid {pid}" + (" (headless)" if headless else ""), "uptime": etime,
297
+ })
298
+ return out
299
+
300
+
301
+ # ---------------------------------------------------------------- tokens
302
+
303
+ def blank():
304
+ return {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "cost_usd": 0.0, "calls": 0}
305
+
306
+
307
+ class Usage:
308
+ def __init__(self, days: int):
309
+ self.cutoff = since(days)
310
+ self.table = prices()
311
+ self.rows = [] # (day, agent, provider, model, kind, usage dict)
312
+ self.last_seen: dict[str, dt.datetime] = {}
313
+
314
+ def add(self, ts, agent, provider, model, kind, inp=0, out=0, read=0, write=0, cost_usd=None, calls=1):
315
+ if ts is None or ts < self.cutoff:
316
+ return
317
+ c = cost(model, inp, out, read, write, self.table) if cost_usd is None else cost_usd
318
+ if ts > self.last_seen.get(agent, ts.min.replace(tzinfo=dt.timezone.utc)):
319
+ self.last_seen[agent] = ts
320
+ self.rows.append((ts.astimezone().date().isoformat(), agent, provider, model or "?", kind,
321
+ {"input": inp, "output": out, "cache_read": read, "cache_write": write,
322
+ "cost_usd": c, "calls": calls}))
323
+
324
+ def claude_code(self):
325
+ seen = set()
326
+ cutoff_epoch = self.cutoff.timestamp()
327
+ for f in glob.glob(str(HOME / ".claude/projects/*/**/*.jsonl"), recursive=True):
328
+ if "/memory/" in f or os.path.getmtime(f) < cutoff_epoch:
329
+ continue
330
+ try:
331
+ fh = open(f, encoding="utf-8", errors="replace")
332
+ except OSError:
333
+ continue
334
+ with fh:
335
+ for line in fh:
336
+ if '"usage"' not in line:
337
+ continue
338
+ try:
339
+ d = json.loads(line)
340
+ except ValueError:
341
+ continue
342
+ msg = d.get("message") or {}
343
+ u = msg.get("usage")
344
+ if not isinstance(u, dict) or msg.get("model") == "<synthetic>":
345
+ continue
346
+ key = (msg.get("id"), d.get("requestId"))
347
+ if key[0] and key in seen:
348
+ continue
349
+ seen.add(key)
350
+ model = msg.get("model", "")
351
+ provider = ("openrouter" if "deepseek" in model or "/" in model and not model.startswith("/")
352
+ else "local" if model.startswith("/") or "muse" in model else "anthropic")
353
+ kind = "headless" if d.get("entrypoint") in ("sdk-cli", "sdk-ts", "sdk-py") else "interactive"
354
+ self.add(parse_ts(d.get("timestamp", "")), agent_of(d.get("cwd")), provider, model,
355
+ f"claude-code {kind}", u.get("input_tokens", 0) or 0, u.get("output_tokens", 0) or 0,
356
+ u.get("cache_read_input_tokens", 0) or 0, u.get("cache_creation_input_tokens", 0) or 0)
357
+
358
+ def codex(self):
359
+ cutoff_epoch = self.cutoff.timestamp()
360
+ zstd = shutil.which("zstd")
361
+ for f in glob.glob(str(HOME / ".codex/sessions/**/*.jsonl*"), recursive=True):
362
+ if os.path.getmtime(f) < cutoff_epoch:
363
+ continue
364
+ if f.endswith(".zst"):
365
+ if not zstd:
366
+ continue
367
+ text = sh([zstd, "-dcq", f], timeout=30)
368
+ else:
369
+ try:
370
+ text = Path(f).read_text(errors="replace")
371
+ except OSError:
372
+ continue
373
+ cwd, model, last, ts = None, "", None, None
374
+ for line in text.splitlines():
375
+ if '"session_meta"' in line or '"turn_context"' in line or '"token_count"' in line:
376
+ try:
377
+ d = json.loads(line)
378
+ except ValueError:
379
+ continue
380
+ p = d.get("payload") or {}
381
+ if d.get("type") == "session_meta":
382
+ cwd = p.get("cwd")
383
+ elif d.get("type") == "turn_context":
384
+ model = p.get("model") or model
385
+ cwd = p.get("cwd") or cwd
386
+ elif p.get("type") == "token_count" and p.get("info"):
387
+ last = p["info"].get("total_token_usage")
388
+ ts = parse_ts(d.get("timestamp", ""))
389
+ if last:
390
+ cached = last.get("cached_input_tokens", 0) or 0
391
+ self.add(ts, agent_of(cwd), "openai", model or "codex", "codex",
392
+ (last.get("input_tokens", 0) or 0) - cached, last.get("output_tokens", 0) or 0, cached,
393
+ last.get("cache_write_input_tokens", 0) or 0)
394
+
395
+ def grok(self):
396
+ for f in glob.glob(str(HOME / ".grok/sessions/*/*/usage.json")):
397
+ d = load_json(Path(f), {})
398
+ s = d.get("session") or {}
399
+ folder = Path(f).parent.parent.name.replace("%2F", "/")
400
+ ticks = s.get("costUsdTicks")
401
+ self.add(parse_ts(d.get("updatedAt", "")), agent_of(folder), "xai", s.get("primaryModelId", "grok"),
402
+ "grok cli", s.get("inputTokens", 0) - s.get("cachedReadTokens", 0), s.get("outputTokens", 0),
403
+ s.get("cachedReadTokens", 0), s.get("cacheCreationTokens", 0),
404
+ cost_usd=ticks / 1e10 if ticks is not None else None, calls=s.get("modelCalls", 1))
405
+
406
+ def ledgers(self):
407
+ for path, provider_default in ((GUARD_LEDGER, "anthropic"), (SPEND_LOG, None)):
408
+ if not path.exists():
409
+ continue
410
+ for line in path.read_text(errors="replace").splitlines():
411
+ try:
412
+ d = json.loads(line)
413
+ except ValueError:
414
+ continue
415
+ model = d.get("model", "")
416
+ if model == "claude-code":
417
+ continue # already counted from the Claude Code transcripts
418
+ agent = d.get("agent") or (d.get("source") or "api").split(":")[0]
419
+ self.add(parse_ts(d.get("at", "")), agent, d.get("provider") or provider_default or "?", model,
420
+ "api" if path == GUARD_LEDGER else d.get("kind", "logged"),
421
+ d.get("input_tokens", 0) or 0, d.get("output_tokens", 0) or 0,
422
+ d.get("cache_read_tokens", 0) or 0, d.get("cache_write_tokens", 0) or 0,
423
+ cost_usd=d.get("cost_usd"))
424
+
425
+ def collect(self):
426
+ for step in (self.claude_code, self.codex, self.grok, self.ledgers):
427
+ try:
428
+ step()
429
+ except Exception as e: # one broken source must not hide the others
430
+ print(f"warning: {step.__name__}: {e}", file=sys.stderr)
431
+ return self
432
+
433
+ def summary(self) -> dict:
434
+ def group(keyf):
435
+ g = collections.defaultdict(blank)
436
+ for row in self.rows:
437
+ acc = g[keyf(row)]
438
+ for k, v in row[5].items():
439
+ acc[k] += v
440
+ return g
441
+ by_agent = group(lambda r: r[1])
442
+ agents = []
443
+ for name, tot in sorted(by_agent.items(), key=lambda kv: -kv[1]["cost_usd"]):
444
+ models = collections.Counter()
445
+ providers = collections.Counter()
446
+ for r in self.rows:
447
+ if r[1] == name:
448
+ models[r[3]] += r[5]["cost_usd"] + 1e-12
449
+ providers[r[2]] += r[5]["cost_usd"] + 1e-12
450
+ seen = self.last_seen.get(name)
451
+ agents.append({"agent": name, "last_active": seen.astimezone().isoformat(timespec="minutes") if seen else None,
452
+ **{k: round(v, 4) if isinstance(v, float) else v for k, v in tot.items()},
453
+ "models": [m for m, _ in models.most_common()], "providers": [p for p, _ in providers.most_common()]})
454
+ daily = collections.defaultdict(dict)
455
+ for (day, prov), tot in group(lambda r: (r[0], r[2])).items():
456
+ daily[day][prov] = round(tot["cost_usd"], 4)
457
+ return {
458
+ "agents": agents,
459
+ "providers": {k: {kk: round(vv, 4) if isinstance(vv, float) else vv for kk, vv in v.items()}
460
+ for k, v in group(lambda r: r[2]).items()},
461
+ "models": {k: {kk: round(vv, 4) if isinstance(vv, float) else vv for kk, vv in v.items()}
462
+ for k, v in group(lambda r: r[3]).items()},
463
+ "kinds": {k: round(v["cost_usd"], 4) for k, v in group(lambda r: r[4]).items()},
464
+ "daily_cost_by_provider": dict(sorted(daily.items())),
465
+ "total_cost_usd": round(sum(r[5]["cost_usd"] for r in self.rows), 2),
466
+ "total_tokens": sum(r[5]["input"] + r[5]["output"] + r[5]["cache_read"] + r[5]["cache_write"] for r in self.rows),
467
+ "sources_without_tokens": ["antigravity (agy): no per-session token data on disk"],
468
+ }
469
+
470
+
471
+ # ---------------------------------------------------------------- links
472
+
473
+ TABLE_RES = [
474
+ re.compile(r'"(\w*table\w*)"\s*:\s*(\d{3,})', re.I),
475
+ re.compile(r"\b([A-Z_]*TABLE[A-Z_]*)\s*=\s*['\"]?(\d{3,})"),
476
+ re.compile(r"rows/table/(\d{3,})"),
477
+ ]
478
+ NOISE_ROOTS = ("bin", "Library", "Downloads", "Documents", "Pictures", "Desktop", "SKILLS", "out", "models", "go")
479
+ SKIP_DIRS = ("/logs", "/.local", "/.cache", "/node_modules", "/.git", "/.venv", "/__pycache__")
480
+
481
+
482
+ def node_files(paths: list[str]) -> list[Path]:
483
+ """Script files of a node, and their siblings (scripts, configs, briefs), bounded."""
484
+ files: list[Path] = []
485
+ for p in paths:
486
+ pp = Path(p)
487
+ if pp.is_dir():
488
+ cands = [pp / "CLAUDE.md", pp / "AGENTS.md"] + sorted(pp.glob("scripts/*"))
489
+ elif pp.is_file() and pp.suffix in (".py", ".sh", ".json", ".md", ".toml", ".ts", ".js", ""):
490
+ cands = [pp]
491
+ if pp.parent.name == "scripts": # a skill's or agent's scripts folder: its siblings are one unit
492
+ cands += sorted(pp.parent.glob("*"))[:40]
493
+ cands += [pp.parent.parent / "SKILL.md", pp.parent.parent / "CLAUDE.md"]
494
+ else:
495
+ continue
496
+ for c in cands:
497
+ if c.is_file() and c.suffix in (".py", ".sh", ".json", ".md", ".toml", ".ts", ".js") and c.stat().st_size < 400_000:
498
+ files.append(c)
499
+ return list(dict.fromkeys(files))[:80]
500
+
501
+
502
+ def resources_of(paths: list[str], own_dir: str | None) -> dict:
503
+ res: dict[str, str] = {}
504
+ for f in node_files(paths):
505
+ try:
506
+ text = f.read_text(errors="replace")
507
+ except OSError:
508
+ continue
509
+ for rx in TABLE_RES:
510
+ for m in rx.finditer(text):
511
+ tid = m.groups()[-1]
512
+ label = m.group(1) if len(m.groups()) > 1 else "table"
513
+ res.setdefault(f"baserow:table/{tid}", f"{label} in {short(str(f))}")
514
+ for p in paths_in(text):
515
+ if any(s in p for s in SKIP_DIRS) or p.endswith((".log", ".py", ".sh", ".plist")):
516
+ continue
517
+ rel = os.path.relpath(p, HOME).split(os.sep)
518
+ if rel[0].startswith(".") or rel[0] in NOISE_ROOTS:
519
+ continue # dotfolders, tool installs, downloads, trash: not data that flows
520
+ depth = 3 if rel[0] in ("agents", "swarms", "projects") else 2
521
+ if len(rel) < depth:
522
+ continue # a bare root like ~/agents says nothing
523
+ if "." in rel[depth - 1]:
524
+ continue # a single file (cookies, bundles), not a shared data folder
525
+ key = "~/" + "/".join(rel[:depth])
526
+ full = os.path.realpath(os.path.join(HOME, key[2:]))
527
+ if own_dir and (full + os.sep).startswith(os.path.realpath(own_dir) + os.sep):
528
+ continue # inside the node's own folder: not a link to anyone
529
+ res.setdefault(f"dir:{key}", short(str(f)))
530
+ return res
531
+
532
+
533
+ API_MARKERS = {
534
+ "anthropic": r"api\.anthropic\.com|anthropic\.Anthropic\(|messages\.create\(",
535
+ "openai": r"api\.openai\.com|OpenAI\(|chat\.completions\.create|responses\.create\(",
536
+ "openrouter": r"openrouter\.ai/api",
537
+ "xai": r"api\.x\.ai",
538
+ "deepseek": r"api\.deepseek\.com",
539
+ "google": r"generativelanguage\.googleapis|google\.genai|genai\.Client\(",
540
+ "claude-cli": r"\bclaude\b[^\n]{0,40}\s-p\b",
541
+ }
542
+
543
+
544
+ def run_files(paths: list[str]) -> list[Path]:
545
+ """The files a node actually runs: its referenced scripts, the local modules they import and the
546
+ scripts they call (one level). Agents (folders): their scripts folder."""
547
+ files: list[Path] = []
548
+ for p in paths:
549
+ pp = Path(p)
550
+ if pp.is_dir():
551
+ files += [f for f in sorted(pp.glob("scripts/*")) if f.is_file()][:40]
552
+ elif pp.is_file() and pp.suffix in (".py", ".sh", ".ts", ".js", ""):
553
+ files.append(pp)
554
+ for f in list(files):
555
+ try:
556
+ text = f.read_text(errors="replace")
557
+ except (OSError, UnicodeError):
558
+ continue
559
+ for mod in re.findall(r"^\s*(?:from|import)\s+([\w.]+)", text, re.M):
560
+ cand = f.parent / (mod.split(".")[0] + ".py")
561
+ if cand.is_file():
562
+ files.append(cand)
563
+ for q in paths_in(text):
564
+ if q.endswith((".py", ".sh")) and os.path.isfile(q):
565
+ files.append(Path(q))
566
+ return [f for f in dict.fromkeys(files) if f.stat().st_size < 400_000][:60]
567
+
568
+
569
+ def api_usage(paths: list[str], command: str = "") -> dict:
570
+ """Which LLM APIs a node's code calls, and which of those already log their spend
571
+ (hivey_spend logs any provider; claude-api-guard only Anthropic; claude -p is in the transcripts)."""
572
+ providers, logged_by, files = set(), set(), []
573
+ if re.search(API_MARKERS["claude-cli"], command):
574
+ providers.add("claude-cli")
575
+ files.append("(job command)")
576
+ for f in run_files(paths):
577
+ try:
578
+ text = f.read_text(errors="replace")
579
+ except OSError:
580
+ continue
581
+ hit = {p for p, rx in API_MARKERS.items() if re.search(rx, text)}
582
+ if hit:
583
+ providers |= hit
584
+ files.append(short(str(f)))
585
+ if "hivey_spend" in text:
586
+ logged_by.add("all")
587
+ if re.search(r"claude[-_]api[-_]guard", text):
588
+ logged_by.add("anthropic")
589
+ if not providers:
590
+ return {}
591
+ unlogged = sorted(p for p in providers if p != "claude-cli" and "all" not in logged_by and p not in logged_by)
592
+ return {"providers": sorted(providers), "unlogged": unlogged, "files": files[:6]}
593
+
594
+
595
+ def job_run_files(command: str) -> list[str]:
596
+ """Script files a job command runs, relative ones resolved against its `cd DIR`."""
597
+ m = re.search(r"\bcd\s+(\S+)", command)
598
+ cwd = os.path.expanduser(m.group(1)) if m else str(HOME)
599
+ out = []
600
+ for tok in re.split(r"[\s;&|<>()]+", command):
601
+ tok = tok.strip("'\"")
602
+ if not tok.endswith((".py", ".sh", ".ts", ".js")):
603
+ continue
604
+ p = os.path.expanduser(tok) if tok.startswith(("~", "/")) else os.path.join(cwd, tok)
605
+ if os.path.isfile(p):
606
+ out.append(p)
607
+ return out or [p for p in paths_in(command) if os.path.isfile(p)]
608
+
609
+
610
+ def build_links(jobs: list[dict], live: list[dict]) -> tuple[list[dict], dict]:
611
+ nodes: dict[str, dict] = {}
612
+ for j in jobs:
613
+ nodes[j["id"]] = {"id": j["id"], "label": j["name"], "type": "job", "agent": j.get("agent"),
614
+ "paths": paths_in(j["command"]), "run": job_run_files(j["command"]), "command": j["command"]}
615
+ agent_dirs = [d for d in sorted(glob.glob(str(HOME / "agents/*/"))) + sorted(glob.glob(str(HOME / "swarms/*/")))
616
+ if not re.search(r"backup|-old|\.bak", d)]
617
+ for d in agent_dirs:
618
+ name = agent_of(d)
619
+ nodes[f"agent:{name}"] = {"id": f"agent:{name}", "label": name, "type": "agent", "agent": name,
620
+ "paths": [d.rstrip("/")], "dir": d.rstrip("/")}
621
+ for a in live:
622
+ nid = f"agent:{a['agent']}"
623
+ nodes.setdefault(nid, {"id": nid, "label": a["agent"], "type": "agent", "agent": a["agent"], "paths": []})
624
+ for n in nodes.values():
625
+ u = api_usage(n["run"], n["command"]) if n["type"] == "job" else api_usage(n["paths"])
626
+ if u:
627
+ n["llm_api"] = u
628
+ touches: dict[str, list[tuple[str, str]]] = collections.defaultdict(list)
629
+ for n in nodes.values():
630
+ for r, ev in resources_of(n["paths"], n.get("dir")).items():
631
+ touches[r].append((n["id"], ev))
632
+ # a job that runs inside an agent's folder belongs to that agent
633
+ belongs = [{"job": n["id"], "agent": f"agent:{n['agent']}"} for n in nodes.values()
634
+ if n["type"] == "job" and n.get("agent") and f"agent:{n['agent']}" in nodes]
635
+ stores = []
636
+ for r, who in sorted(touches.items()):
637
+ owner = None
638
+ if r.startswith("dir:"):
639
+ full = os.path.realpath(os.path.join(HOME, r[6:]))
640
+ for n in nodes.values():
641
+ if n.get("dir") and (full + os.sep).startswith(os.path.realpath(n["dir"]) + os.sep):
642
+ owner = n["id"]
643
+ users = list(dict.fromkeys(i for i, _ in who))
644
+ if len(set(users) | ({owner} if owner else set())) < 2 or len(users) > 8:
645
+ continue # used by one node only, or so common it is noise
646
+ stores.append({"resource": r, "owner": owner,
647
+ "nodes": [{"id": i, "evidence": ev} for i, ev in who]})
648
+ return list(nodes.values()), {"belongs_to": belongs, "shared_stores": stores}
649
+
650
+
651
+ # ---------------------------------------------------------------- commands
652
+
653
+ def scan(days: int) -> dict:
654
+ jobs = cron_jobs() + launchd_jobs()
655
+ live = live_agents()
656
+ usage = Usage(days).collect().summary()
657
+ nodes, candidates = build_links(jobs, live)
658
+ for n in nodes:
659
+ n.pop("paths", None)
660
+ n.pop("run", None)
661
+ n.pop("command", None)
662
+ return {
663
+ "generated": dt.datetime.now().isoformat(timespec="seconds"),
664
+ "window_days": days,
665
+ "jobs": jobs,
666
+ "live_agents": live,
667
+ "agent_logs": agent_logs(),
668
+ "usage": usage,
669
+ "nodes": nodes,
670
+ "links_confirmed": load_json(LINKS, []),
671
+ "links_candidates": candidates,
672
+ "notes": [
673
+ "Costs are API-list-price estimates; Claude Code (Max) and Codex (Plus) usage is API-equivalent, not billed.",
674
+ "Claude Code transcripts older than the weekly purge (15 days) are gone; longer windows undercount.",
675
+ "Candidate links are heuristic: shared_stores lists Baserow tables and data folders named by 2+ nodes (or by one node and the folder owner). Read the evidence files to decide who writes and who reads before drawing.",
676
+ ],
677
+ }
678
+
679
+
680
+ def fmt_money(v: float) -> str:
681
+ return f"${v:,.2f}"
682
+
683
+
684
+ def fmt_tok(n: int) -> str:
685
+ return f"{n / 1e6:.1f}M" if n >= 1e6 else f"{n / 1e3:.0f}k" if n >= 1e3 else str(n)
686
+
687
+
688
+ def print_stats(snap: dict) -> None:
689
+ u = snap["usage"]
690
+ print(f"hivey agent map — last {snap['window_days']} days — {snap['generated']}\n")
691
+ print(f"Scheduled jobs: {len(snap['jobs'])} live agents: {len(snap['live_agents'])} "
692
+ f"est. cost: {fmt_money(u['total_cost_usd'])} tokens: {fmt_tok(u['total_tokens'])}\n")
693
+ print("Cost by provider")
694
+ for p, v in sorted(u["providers"].items(), key=lambda kv: -kv[1]["cost_usd"]):
695
+ print(f" {p:12} {fmt_money(v['cost_usd']):>10} {v['calls']:>7} calls out {fmt_tok(v['output'])}")
696
+ print("\nTop agents by cost")
697
+ for a in u["agents"][:15]:
698
+ tok = a["input"] + a["output"] + a["cache_read"] + a["cache_write"]
699
+ print(f" {a['agent'][:28]:28} {fmt_money(a['cost_usd']):>10} {fmt_tok(tok):>7} tok {', '.join(a['models'][:2])}")
700
+ print("\nJobs needing attention")
701
+ bad = [j for j in snap["jobs"] if j["status"] not in ("ok", "?", "running") or j.get("last_error")]
702
+ for j in bad:
703
+ print(f" {j['name']:28} {j['status']:10} {j.get('last_error', '')[:70]}")
704
+ if not bad:
705
+ print(" none")
706
+ print("\nCalls LLM APIs without logging spend (claude -p runs are counted from transcripts)")
707
+ unlogged = [n for n in snap["nodes"] if (n.get("llm_api") or {}).get("unlogged")]
708
+ for n in unlogged:
709
+ print(f" {n['label'][:28]:28} {', '.join(n['llm_api']['unlogged']):24} {n['llm_api']['files'][0]}")
710
+ if not unlogged:
711
+ print(" none")
712
+ print("\nRunning now")
713
+ for a in snap["live_agents"]:
714
+ if a["status"] in ("working", "running", "blocked"):
715
+ print(f" {a['agent'][:28]:28} {a['cli']:12} {a['status']:8} {a['where']}")
716
+ c = snap["links_candidates"]
717
+ print(f"\nLinks: {len(snap['links_confirmed'])} confirmed; candidates: {len(c['shared_stores'])} shared stores, "
718
+ f"{len(c['belongs_to'])} jobs inside agent folders")
719
+ for st in c["shared_stores"][:25]:
720
+ owner = f" (owner {st['owner']})" if st["owner"] else ""
721
+ print(f" {st['resource']}{owner}: " + ", ".join(dict.fromkeys(n['id'] for n in st['nodes'])))
722
+
723
+
724
+ def main() -> int:
725
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
726
+ sub = ap.add_subparsers(dest="cmd", required=True)
727
+ s = sub.add_parser("scan")
728
+ s.add_argument("--days", type=int, default=7)
729
+ s.add_argument("--out", default=str(STATE / "snapshot.json"))
730
+ st = sub.add_parser("stats")
731
+ st.add_argument("--days", type=int, default=7)
732
+ lg = sub.add_parser("log")
733
+ lg.add_argument("--agent", required=True)
734
+ lg.add_argument("--provider", required=True)
735
+ lg.add_argument("--model", required=True)
736
+ lg.add_argument("--in", dest="inp", type=int, default=0)
737
+ lg.add_argument("--out", type=int, default=0)
738
+ lg.add_argument("--cache-read", type=int, default=0)
739
+ lg.add_argument("--cache-write", type=int, default=0)
740
+ lg.add_argument("--cost", type=float)
741
+ lg.add_argument("--kind", default="logged")
742
+ lg.add_argument("--note")
743
+ nt = sub.add_parser("nightly", help="scan, stats page, map update with a cheap model, reports/latest")
744
+ nt.add_argument("--days", type=int, default=7)
745
+ nt.add_argument("--model", default="haiku")
746
+ nt.add_argument("--no-llm", action="store_true", help="no model run: last night's map, unchanged")
747
+ nt.add_argument("--open", action="store_true", help="open the report when done")
748
+ op = sub.add_parser("open", help="open the latest report (builds the first one if there is none)")
749
+ op.add_argument("--model", default="haiku")
750
+ sc = sub.add_parser("schedule", help="the nightly launchd run: install | remove | status")
751
+ sc.add_argument("action", choices=["install", "remove", "status", "offer", "token"], nargs="?", default="status")
752
+ sc.add_argument("--command", help='token: the command printing the `claude setup-token` token, '
753
+ 'e.g. "envsave get es_…" ("" = the normal claude login)')
754
+ sc.add_argument("--at", default="06:30", help="HH:MM, local time (default 06:30, after the night's jobs)")
755
+ sc.add_argument("--model", default="haiku")
756
+ lk = sub.add_parser("link")
757
+ lk.add_argument("src")
758
+ lk.add_argument("dst")
759
+ lk.add_argument("--via", default="")
760
+ lk.add_argument("--evidence", default="")
761
+ lk.add_argument("--remove", action="store_true")
762
+ a = ap.parse_args()
763
+
764
+ if a.cmd in ("scan", "stats"):
765
+ snap = scan(a.days)
766
+ STATE.mkdir(parents=True, exist_ok=True)
767
+ out = Path(getattr(a, "out", STATE / "snapshot.json"))
768
+ out.write_text(json.dumps(snap, indent=1, default=str))
769
+ if a.cmd == "stats":
770
+ print_stats(snap)
771
+ print(f"snapshot: {short(str(out))}", file=sys.stderr if a.cmd == "stats" else sys.stdout)
772
+ return 0
773
+ if a.cmd == "nightly":
774
+ import report
775
+ code = report.nightly(scan, a.days, a.model, not a.no_llm)
776
+ if a.open:
777
+ report.open_latest(a.model)
778
+ return code
779
+ if a.cmd == "open":
780
+ import report
781
+ return report.open_latest(a.model)
782
+ if a.cmd == "schedule":
783
+ import report
784
+ if a.action == "token":
785
+ if a.command is None:
786
+ sc.error('token needs --command "envsave get es_…" (or "" for the normal login)')
787
+ return report.set_token_command(a.command)
788
+ hh, _, mm = a.at.partition(":")
789
+ return report.schedule(a.action, int(hh), int(mm or 0), a.model)
790
+ if a.cmd == "log":
791
+ entry = record_usage(a.agent, a.provider, a.model, a.inp, a.out, a.cache_read, a.cache_write,
792
+ a.cost, a.kind, a.note)
793
+ print(json.dumps(entry))
794
+ return 0 if entry else 1
795
+ if a.cmd == "link":
796
+ links = [l for l in load_json(LINKS, []) if not (l["from"] == a.src and l["to"] == a.dst)]
797
+ if not a.remove:
798
+ links.append({"from": a.src, "to": a.dst, "via": a.via, "evidence": a.evidence,
799
+ "confirmed": dt.date.today().isoformat()})
800
+ STATE.mkdir(parents=True, exist_ok=True)
801
+ LINKS.write_text(json.dumps(links, indent=1))
802
+ print(f"{len(links)} confirmed links in {short(str(LINKS))}")
803
+ return 0
804
+ return 2
805
+
806
+
807
+ if __name__ == "__main__":
808
+ sys.exit(main())