@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,602 @@
1
+ """hivey agent map reports: the nightly run, opening the latest report, and its launchd schedule.
2
+
3
+ Used by agent_map.py (`nightly`, `open`, `schedule`). A report is a folder
4
+ ~/.hivey/agent-map/reports/<YYYY-MM-DD-HHMM>/ with:
5
+ agent-stats.html one-page stats (archify explainer), generated here without an LLM
6
+ agent-map.html the jobs → data → agents map (archify dataflow), updated by a cheap model
7
+ (Claude Haiku by default) from the previous night's map.json
8
+ snapshot.json, agents.csv, daily.csv, stats.archify.md, map.json, nightly.log
9
+ `reports/latest` points at the newest complete report. Python standard library only.
10
+ """
11
+ from __future__ import annotations
12
+
13
+ import csv
14
+ import datetime as dt
15
+ import json
16
+ import os
17
+ import plistlib
18
+ import re
19
+ import shutil
20
+ import subprocess
21
+ import sys
22
+ from pathlib import Path
23
+
24
+ HOME = Path.home()
25
+ STATE = HOME / ".hivey" / "agent-map"
26
+ REPORTS = STATE / "reports"
27
+ LATEST = REPORTS / "latest"
28
+ SCRIPTS = Path(__file__).resolve().parent
29
+ LABEL = "com.hivey.agent-map"
30
+ PLIST = HOME / "Library" / "LaunchAgents" / f"{LABEL}.plist"
31
+ KEEP_REPORTS = 30
32
+ LAUNCH_PATH = ":".join(str(p) for p in (
33
+ HOME / ".local/bin", HOME / ".bun/bin", HOME / ".nvm/current/bin", Path("/opt/homebrew/bin"),
34
+ Path("/usr/local/bin"), Path("/usr/bin"), Path("/bin")))
35
+
36
+
37
+ def archify_bin() -> Path | None:
38
+ for p in (HOME / ".claude/skills/archify/bin/archify.mjs", HOME / ".agents/skills/archify/bin/archify.mjs"):
39
+ if p.is_file():
40
+ return p
41
+ return None
42
+
43
+
44
+ def log(folder: Path, msg: str) -> None:
45
+ line = f"[{dt.datetime.now():%Y-%m-%d %H:%M:%S}] {msg}"
46
+ print(line, flush=True)
47
+ with open(folder / "nightly.log", "a") as fh:
48
+ fh.write(line + "\n")
49
+
50
+
51
+ # ---------------------------------------------------------------- stats page (no LLM)
52
+
53
+ def money(v: float) -> str:
54
+ return f"${v:,.2f}"
55
+
56
+
57
+ def mtok(n: int) -> str:
58
+ return f"{n / 1e6:,.0f}M" if n >= 1e6 else f"{n / 1e3:,.0f}k"
59
+
60
+
61
+ def cell(text) -> str:
62
+ """Table-cell / prose-safe text: names with paths or symbols go in backticks."""
63
+ s = str(text).replace("`", "'").replace("|", "/").strip()
64
+ return f"`{s}`" if re.search(r"[<>*_~/\\\[\]{}#@]", s) else s
65
+
66
+
67
+ def node_label(node_id: str) -> str:
68
+ return re.sub(r"^(cron:|launchd:(com\.jcsancho\.|com\.hivey\.)?|agent:)", "", node_id)
69
+
70
+
71
+ def model_name(m: str) -> str:
72
+ m = m.rsplit("/", 1)[-1]
73
+ k = re.match(r"claude-(opus|sonnet|haiku)-(\d+)(?:-(\d{1,2}))?(?!\d)", m)
74
+ if not k:
75
+ return m
76
+ return f"{k.group(1).title()} {k.group(2)}" + (f".{k.group(3)}" if k.group(3) else "")
77
+
78
+
79
+ def write_stats(snap: dict, folder: Path) -> None:
80
+ from hivey_spend import price_for # one price table
81
+
82
+ u = snap["usage"]
83
+ days = snap["window_days"]
84
+ total = u["total_cost_usd"] or 0.0
85
+ agents = u["agents"]
86
+ (folder / "snapshot.json").write_text(json.dumps(snap, indent=1, default=str))
87
+ with open(folder / "daily.csv", "w", newline="") as fh:
88
+ w = csv.writer(fh)
89
+ w.writerow(["day", "cost_usd"])
90
+ for day, v in u["daily_cost_by_provider"].items():
91
+ w.writerow([day[5:], round(sum(v.values()), 2)])
92
+ with open(folder / "agents.csv", "w", newline="") as fh:
93
+ w = csv.writer(fh)
94
+ w.writerow(["agent", "cost_usd"])
95
+ for a in agents[:10]:
96
+ w.writerow([a["agent"], round(a["cost_usd"], 2)])
97
+
98
+ kinds = u["kinds"]
99
+ interactive = sum(v for k, v in kinds.items() if "interactive" in k)
100
+ headless = sum(v for k, v in kinds.items() if "headless" in k)
101
+ api = total - interactive - headless
102
+ models = sorted(u["models"].items(), key=lambda kv: -kv[1]["cost_usd"])
103
+ jobs = snap["jobs"]
104
+ failing = [j for j in jobs if job_state(j)[0] == "❌"]
105
+ n_cron = sum(1 for j in jobs if j["kind"].startswith("cron"))
106
+ gaps = [n for n in snap["nodes"] if (n.get("llm_api") or {}).get("unlogged")]
107
+ top = agents[0] if agents else None
108
+ pct = lambda v: f"{100 * v / total:.0f}%" if total else "0%"
109
+
110
+ L = []
111
+ L.append(f"# What ran on this Mac in the last {days} days, and what did it cost? {{#agent-stats}}\n")
112
+ if top:
113
+ L.append(f"Your agents used about **{money(total)} of API-equivalent tokens** in {days} days; "
114
+ f"**{cell(top['agent'])} used {money(top['cost_usd'])}** of it ({pct(top['cost_usd'])}).\n")
115
+ else:
116
+ L.append(f"No token use was recorded in the last {days} days.\n")
117
+ L.append(f"- {pct(interactive)} of the cost is interactive Claude Code ({money(interactive)}); "
118
+ f"headless runs cost {money(headless)} and direct API calls {money(api)}.")
119
+ if models:
120
+ L.append("- " + "; ".join(f"{cell(model_name(m))} {money(v['cost_usd'])}" for m, v in models[:3]) + ".")
121
+ states = [job_state(j)[0] for j in jobs]
122
+ tally = ", ".join(f"{emo} {states.count(emo)}" for emo in ("✅", "⚠️", "❌", "⏳", "❔") if states.count(emo))
123
+ L.append(f"- {len(jobs)} scheduled jobs ({n_cron} cron, {len(jobs) - n_cron} launchd): {tally}.")
124
+ L.append(f"- {len(snap['links_confirmed'])} confirmed links between jobs and agents; "
125
+ f"{len(gaps)} with LLM calls not logged yet.\n")
126
+ L.append(f'@answer scope="last {days} days to {snap["generated"][:10]} · costs are list-price estimates · '
127
+ f'Claude Code (Max) and Codex (Plus) are not billed per token"')
128
+ L.append("@meta locale=en")
129
+ L.append('@source scan title="hivey agent map snapshot (agent_map.py scan)" path=snapshot.json\n')
130
+
131
+ if agents:
132
+ L.append("## Which agents spend the most? {#by-agent}\n")
133
+ L.append(f'@chart type=bar data=agents.csv x=agent y=cost_usd unit=USD title="Cost by agent, '
134
+ f'last {days} days (API-equivalent USD, estimated)"\n')
135
+ L.append("| Agent | Cost | Calls | Tokens | Main model |")
136
+ L.append("| --- | --- | --- | --- | --- |")
137
+ for a in agents[:8]:
138
+ tok = a["input"] + a["output"] + a["cache_read"] + a["cache_write"]
139
+ badge = " {bad:" + pct(a["cost_usd"]) + "}" if a is top and total and a["cost_usd"] / total > 0.3 else ""
140
+ main = model_name(a["models"][0]) if a["models"] else "?"
141
+ L.append(f"| {cell(a['agent'])} | {money(a['cost_usd'])}{badge} | {a['calls']:,} | {mtok(tok)} | {cell(main)} |")
142
+ L.append("")
143
+
144
+ pi, po, pr, pw = price_for(top["models"][0] if top["models"] else "")
145
+ parts = [("Cache reads", top["cache_read"], pr), ("Cache writes", top["cache_write"], pw),
146
+ ("Output", top["output"], po), ("Fresh input", top["input"], pi)]
147
+ L.append(f"## Where does {cell(top['agent'])}'s cost come from? {{#top-spender}}\n")
148
+ L.append("@facts")
149
+ for name, n, p in parts:
150
+ L.append(f"| {name} | {mtok(n)} tokens → {money(n * p / 1e6)} |")
151
+ L.append("")
152
+ biggest = max(parts, key=lambda x: x[1] * x[2])[0]
153
+ if biggest.startswith("Cache"):
154
+ L.append("Most of it is context: each turn re-reads the session, so a long session costs more per turn "
155
+ "as it grows. Clearing or compacting more often, or a cheaper model for routine runs, cuts it.\n")
156
+ else:
157
+ L.append("Most of it is output tokens: long answers, reports or code written by the agent.\n")
158
+
159
+ if len(u["daily_cost_by_provider"]) > 1:
160
+ L.append("## How does the cost move day by day? {#daily}\n")
161
+ L.append('@chart type=line data=daily.csv x=day y=cost_usd unit=USD title="Daily cost, all providers '
162
+ '(API-equivalent USD, estimated; today is partial)"\n')
163
+
164
+ L.append("## How do the agents feed each other? {#map}\n")
165
+ L.append("The full map is `agent-map.html` in this folder.\n")
166
+ links = snap["links_confirmed"]
167
+ if links:
168
+ for l in links[:12]:
169
+ L.append(f"- {cell(node_label(l['from']))} → {cell(node_label(l['to']))}: {cell(l.get('via', ''))}")
170
+ if len(links) > 12:
171
+ L.append(f"- and {len(links) - 12} more links")
172
+ else:
173
+ L.append("- No links confirmed yet: the nightly run confirms them from the shared tables and folders.")
174
+ L.append("")
175
+
176
+ L.append("## Which jobs need attention? {#jobs}\n")
177
+ attention = [j for j in jobs if job_state(j)[0] in ("❌", "⚠️", "❔")]
178
+ attention.sort(key=lambda j: ORDER.get(job_state(j)[0], 9))
179
+ if attention:
180
+ L.append("| Job | Schedule | Issue |")
181
+ L.append("| --- | --- | --- |")
182
+ for j in attention[:14]:
183
+ emo, words = job_state(j)
184
+ badge = " {bad:failing}" if emo == "❌" else " {caution:check}"
185
+ err = (j.get("last_error") or words)[:90]
186
+ L.append(f"| {emo} {cell(j['name'])} | {cell(j['kind'].split()[0] + ' ' + j['schedule'])} | {cell(err)}{badge} |")
187
+ L.append("")
188
+ else:
189
+ L.append(f"✅ All {len(jobs)} jobs ran cleanly.\n")
190
+ L.append("Every job and agent, with its status, issues and the last lines of its log: `agent-logs.html` "
191
+ "in this folder (hivey menu → agent map opens it too).\n")
192
+
193
+ L.append("## What is not counted yet? {#gaps}\n")
194
+ L.append('@callout level=warning title="Spend the map cannot see"')
195
+ for n in gaps:
196
+ L.append(f"{cell(n['label'])} calls {', '.join(n['llm_api']['unlogged'])} without logging it.")
197
+ for s in u.get("sources_without_tokens", []):
198
+ L.append(cell(s.split(":")[0]) + " keeps no token data on disk.")
199
+ L.append("")
200
+ todo = [f"- [ ] Fix {cell(j['name'])} ({cell((j.get('last_error') or j['status'])[:60])})" for j in failing[:4]]
201
+ todo += [f"- [ ] Log {cell(n['label'])}'s API calls with `hivey_spend.record(...)`" for n in gaps[:4]]
202
+ if todo:
203
+ L.extend(todo)
204
+ L.append("")
205
+ (folder / "stats.archify.md").write_text("\n".join(L))
206
+
207
+
208
+ # ---------------------------------------------------------------- run log (no LLM)
209
+
210
+ def job_state(j: dict) -> tuple[str, str]:
211
+ """(emoji, words) for one scheduled job's latest run."""
212
+ st = j.get("status", "?")
213
+ if st in ("running", "RUNNING"):
214
+ return "⏳", "running now"
215
+ if st.startswith("exit") or st == "not loaded":
216
+ return "❌", st if st != "not loaded" else "not loaded in launchd"
217
+ if st == "MISSED" or j.get("overdue"):
218
+ return "⚠️", "missed its last run"
219
+ if j.get("errors"):
220
+ return "⚠️", "ran, errors in its log"
221
+ if st == "?" and not j.get("log"):
222
+ return "❔", "no log to check"
223
+ return "✅", "ran ok"
224
+
225
+
226
+ AGENT_STATE = {"working": ("🟢", "working"), "running": ("🟢", "running"), "blocked": ("🔴", "blocked, needs you"),
227
+ "idle": ("⚪", "idle"), "done": ("✅", "done"), "gone": ("⚫", "not running")}
228
+ ORDER = {"❌": 0, "⚠️": 1, "🔴": 1, "⏳": 2, "🟢": 2, "❔": 3, "⚪": 4, "✅": 4, "⚫": 5}
229
+
230
+
231
+ def write_logs_page(snap: dict, folder: Path) -> None:
232
+ import html
233
+ e = html.escape
234
+ jobs = sorted(snap["jobs"], key=lambda j: (ORDER.get(job_state(j)[0], 9), j["name"]))
235
+ usage = {a["agent"]: a for a in snap["usage"]["agents"]}
236
+ logs = snap.get("agent_logs", {})
237
+ live: dict[str, dict] = {}
238
+ for a in snap["live_agents"]:
239
+ cur = live.get(a["agent"])
240
+ if not cur or ORDER.get(AGENT_STATE.get(a["status"], ("⚪",))[0], 9) < ORDER.get(AGENT_STATE.get(cur["status"], ("⚪",))[0], 9):
241
+ live[a["agent"]] = a
242
+ names = sorted(set(live) | {n["label"] for n in snap["nodes"] if n["type"] == "agent"}
243
+ | {a for a in usage if usage[a]["cost_usd"] >= 0.5})
244
+
245
+ def details(body: list[str]) -> str:
246
+ return "".join(body)
247
+
248
+ def log_block(info: dict) -> list[str]:
249
+ out = []
250
+ if info.get("log"):
251
+ out.append(f"<p class=meta>log <code>{e(info['log'])}</code> · last written {e(info.get('log_modified', '?'))}</p>")
252
+ if info.get("errors"):
253
+ out.append("<p class=meta>issues found in its log:</p><ul class=errs>"
254
+ + "".join(f"<li><code>{e(x)}</code></li>" for x in info["errors"]) + "</ul>")
255
+ if info.get("tail"):
256
+ out.append(f"<pre>{e(chr(10).join(info['tail']))}</pre>")
257
+ return out
258
+
259
+ counts: dict[str, int] = {}
260
+ rows = []
261
+ for j in jobs:
262
+ emo, words = job_state(j)
263
+ counts[emo] = counts.get(emo, 0) + 1
264
+ issue = (j.get("errors") or [""])[-1]
265
+ last = (j.get("last_run") or j.get("log_modified") or "?").replace("T", " ")
266
+ body = [f"<p class=meta>{e(j['kind'])} · {e(j['schedule'])} · agent {e(j.get('agent') or '—')}</p>",
267
+ f"<p class=meta>command <code>{e(j['command'][:400])}</code></p>"] + log_block(j)
268
+ if not j.get("log"):
269
+ body.append("<p class=meta>this job writes no log file hivey can find.</p>")
270
+ rows.append(f"<details class=row data-state='{emo}'><summary><span class=emo>{emo}</span>"
271
+ f"<b>{e(j['name'])}</b><span class=sub>{e(words)}</span><span class=when>{e(last)}</span>"
272
+ f"<span class=issue>{e(issue[:110])}</span></summary>{details(body)}</details>")
273
+ arows = []
274
+ dormant = [n for n in names if n not in live and n not in usage and not logs.get(n)]
275
+ names = [n for n in names if n not in dormant]
276
+ for name in sorted(names, key=lambda n: (ORDER.get(AGENT_STATE.get(live.get(n, {}).get("status", "gone"), ("⚫",))[0], 9), n)):
277
+ a = live.get(name)
278
+ emo, words = AGENT_STATE.get(a["status"], ("⚪", a["status"])) if a else ("⚫", "not running")
279
+ info = logs.get(name, {})
280
+ if info.get("errors") and emo in ("⚪", "✅", "⚫"):
281
+ emo, words = "⚠️", words + ", errors in its log"
282
+ u = usage.get(name, {})
283
+ cost = f"${u['cost_usd']:,.2f} in {snap['window_days']} days" if u else "no token use"
284
+ body = [f"<p class=meta>{e(a['where'] if a else 'not open in hivey')} · {e(a.get('cwd', '') if a else '')}"
285
+ f" · last active {e(u.get('last_active') or '?')} · {e(cost)}"
286
+ + (f" · {e(', '.join(u.get('models', [])[:2]))}" if u else "") + "</p>"]
287
+ body += log_block(info) if info else ["<p class=meta>no <code>logs/</code> folder in this agent.</p>"]
288
+ arows.append(f"<details class=row><summary><span class=emo>{emo}</span><b>{e(name)}</b>"
289
+ f"<span class=sub>{e(words)}</span><span class=when>{e((u.get('last_active') or '')[:16].replace('T', ' '))}</span>"
290
+ f"<span class=issue>{e(cost)}</span></summary>{details(body)}</details>")
291
+ if dormant:
292
+ arows.append(f"<details class=row><summary><span class=emo>⚫</span><b>{len(dormant)} dormant agents</b>"
293
+ f"<span class=sub>not running, no token use, no logs</span><span class=when></span>"
294
+ f"<span class=issue>{e(', '.join(dormant[:8]))}…</span></summary>"
295
+ f"<p class=meta>{e(', '.join(dormant))}</p></details>")
296
+ summary = " · ".join(f"{k} {v}" for k, v in sorted(counts.items(), key=lambda kv: ORDER.get(kv[0], 9)))
297
+ page = f"""<!doctype html><html lang=en><meta charset=utf-8>
298
+ <meta name=viewport content="width=device-width,initial-scale=1">
299
+ <title>Agent logs · {e(snap['generated'][:16])}</title>
300
+ <style>
301
+ :root{{--bg:#fff;--fg:#1d2330;--mute:#667085;--line:#e4e7ec;--card:#f8f9fb;--accent:#2f6fec;--pre:#f2f4f7}}
302
+ @media (prefers-color-scheme:dark){{:root{{--bg:#0d1117;--fg:#e6edf3;--mute:#8b949e;--line:#30363d;--card:#161b22;--accent:#79a8ff;--pre:#0b0f14}}}}
303
+ body{{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}}
304
+ main{{max-width:1180px;margin:0 auto;padding:28px 24px 60px}}
305
+ nav a{{color:var(--accent);margin-right:18px;text-decoration:none;font-weight:600}} nav a.on{{color:var(--fg)}}
306
+ h1{{font-size:26px;margin:18px 0 4px}} h2{{font-size:19px;margin:34px 0 10px}}
307
+ .lead{{color:var(--mute);margin:0 0 6px}} .counts{{font-size:17px;margin:10px 0 0}}
308
+ .row{{border:1px solid var(--line);background:var(--card);border-radius:10px;margin:7px 0}}
309
+ summary{{display:grid;grid-template-columns:30px minmax(150px,1.1fr) minmax(130px,.9fr) 150px minmax(0,2fr);gap:12px;align-items:center;padding:10px 14px;cursor:pointer;list-style:none}}
310
+ summary::-webkit-details-marker{{display:none}}
311
+ .emo{{font-size:18px}} .sub,.when{{color:var(--mute);font-size:13px}} .issue{{font:12.5px ui-monospace,Menlo,monospace;color:var(--mute);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}}
312
+ details[open] summary{{border-bottom:1px solid var(--line)}} details>*:not(summary){{margin:10px 16px}}
313
+ .meta{{color:var(--mute);font-size:13px}} code{{font:12.5px ui-monospace,Menlo,monospace;word-break:break-all}}
314
+ .errs{{margin-top:0}} .errs li{{color:#d1242f}} @media (prefers-color-scheme:dark){{.errs li{{color:#ff7b72}}}}
315
+ pre{{background:var(--pre);border:1px solid var(--line);border-radius:8px;padding:12px;max-height:420px;overflow:auto;font:12px/1.45 ui-monospace,Menlo,monospace;white-space:pre-wrap;word-break:break-all}}
316
+ .legend{{color:var(--mute);font-size:13px;margin-top:40px}}
317
+ @media (max-width:760px){{summary{{grid-template-columns:28px 1fr}} .sub,.when,.issue{{grid-column:2}}}}
318
+ </style>
319
+ <main>
320
+ <nav><a href="agent-stats.html">Stats</a><a href="agent-map.html">Map</a><a class=on href="agent-logs.html">Logs</a></nav>
321
+ <h1>Did every job and agent run?</h1>
322
+ <p class=lead>Scan of {e(snap['generated'][:16].replace('T', ' '))}. Click a row for its issues and the last lines of its log.</p>
323
+ <p class=counts>Scheduled jobs: {summary}</p>
324
+ <h2>Scheduled jobs ({len(jobs)})</h2>
325
+ {''.join(rows)}
326
+ <h2>Agents ({len(names)} active{f", {len(dormant)} dormant" if dormant else ""})</h2>
327
+ {''.join(arows)}
328
+ <p class=legend>✅ ran ok · ⚠️ errors in its log or a missed run · ❌ failed (non-zero exit) or not loaded · ⏳ running ·
329
+ ❔ no log · 🟢 working · 🔴 blocked, needs you · ⚪ idle · ⚫ not running. "Issues" are the error lines among the
330
+ last 40 lines of each log, so an old error can show until the log moves on.</p>
331
+ </main></html>"""
332
+ (folder / "agent-logs.html").write_text(page)
333
+
334
+
335
+ # ---------------------------------------------------------------- archify
336
+
337
+ def finalize(folder: Path, kind: str, src: str, out: str) -> tuple[bool, str]:
338
+ node, archify = shutil.which("node"), archify_bin()
339
+ if not node or not archify:
340
+ return False, "archify or node not found"
341
+ n = 1
342
+ while (folder / f"review-{kind}-{n}").exists():
343
+ n += 1
344
+ cmd = [node, str(archify), "finalize", kind, src, out, "--json", "--out-dir", f"review-{kind}-{n}"]
345
+ if kind != "explainer":
346
+ cmd[6:6] = ["--quality", "showcase"]
347
+ try:
348
+ p = subprocess.run(cmd, cwd=folder, capture_output=True, text=True, timeout=300)
349
+ except (OSError, subprocess.SubprocessError) as e:
350
+ return False, str(e)
351
+ try:
352
+ r = json.loads(p.stdout)
353
+ msgs = "; ".join(d.get("message", "")[:160] for d in r.get("diagnostics", [])[:3])
354
+ return r.get("status") == "pass", msgs or r.get("status", "")
355
+ except ValueError:
356
+ return False, (p.stdout + p.stderr)[-300:]
357
+
358
+
359
+ MAP_PROMPT = """You are the nightly run of the hivey agent map. Your working folder is {folder} (your cwd);
360
+ use absolute paths and no `cd`. Read ~/.claude/skills/hivey-agent-map/SKILL.md first (Workflow step 2 and
361
+ "Drawing with archify" → the map), then archify's SKILL.md for the dataflow rules. The stats page is
362
+ already built: do not touch stats.archify.md or agent-stats.html.
363
+
364
+ 1. Links: in snapshot.json compare links_candidates.shared_stores with links_confirmed. For each store not
365
+ covered yet, read only the evidence lines you need. When it is clear who writes and who reads, save it:
366
+ python3 -I {scripts}/agent_map.py link <from-id> <to-id> --via "<what flows>" --evidence "<file:line>"
367
+ Skip anything unclear or coincidental. Then rerun: python3 -I {scripts}/agent_map.py scan --out snapshot.json
368
+ 2. Map: {map_task}
369
+ Costs and status go in each node's sublabel (from usage.agents and jobs in snapshot.json); keep at most
370
+ 25 nodes on 5 stages x rows 0-4; refresh the numbers in the cards.
371
+ 3. Run: node {archify} finalize dataflow map.json agent-map.html --quality showcase --json --out-dir review-map-llm-1
372
+ If it fails, repair map.json and rerun with review-map-llm-2, -3 ... (at most 4 runs).
373
+ Stop there and reply with one line: what changed."""
374
+
375
+
376
+ CONFIG = STATE / "config.json" # {"claude_token_command": "envsave get es_…"}: never the token itself
377
+
378
+
379
+ def claude_token(folder: Path) -> str | None:
380
+ """A long-lived Claude login (`claude setup-token`) for unattended runs, read at run time by the
381
+ configured command so it is never written to a file. None: Claude Code's normal login."""
382
+ try:
383
+ command = json.loads(CONFIG.read_text()).get("claude_token_command")
384
+ except (OSError, ValueError):
385
+ return None
386
+ if not command:
387
+ return None
388
+ try:
389
+ p = subprocess.run(["/bin/bash", "-c", command], capture_output=True, text=True, timeout=60,
390
+ env={**os.environ, "PATH": LAUNCH_PATH})
391
+ except (OSError, subprocess.SubprocessError) as e:
392
+ log(folder, f"claude token command failed: {e}; using the normal login")
393
+ return None
394
+ token = p.stdout.strip()
395
+ if p.returncode != 0 or not token:
396
+ log(folder, f"claude token command failed (exit {p.returncode}); using the normal login")
397
+ return None
398
+ return token
399
+
400
+
401
+ def set_token_command(command: str) -> int:
402
+ STATE.mkdir(parents=True, exist_ok=True)
403
+ try:
404
+ cfg = json.loads(CONFIG.read_text())
405
+ except (OSError, ValueError):
406
+ cfg = {}
407
+ if command:
408
+ cfg["claude_token_command"] = command
409
+ else:
410
+ cfg.pop("claude_token_command", None)
411
+ CONFIG.write_text(json.dumps(cfg, indent=1))
412
+ print(f"nightly Claude login: {'token from: ' + command if command else 'the normal claude login'} ({CONFIG})")
413
+ return 0
414
+
415
+
416
+ def run_llm(folder: Path, model: str, has_map: bool) -> bool:
417
+ claude = shutil.which("claude")
418
+ archify = archify_bin()
419
+ if not claude or not archify:
420
+ log(folder, "skipping the map update: claude or archify not found")
421
+ return False
422
+ task = ("map.json is last night's map: update it, adding nodes and flows for newly confirmed links."
423
+ if has_map else "there is no map.json yet: write it following the skill's map rules.")
424
+ prompt = MAP_PROMPT.format(folder=folder, scripts=SCRIPTS, archify=archify, map_task=task)
425
+ tools = ("Read,Write,Edit,Glob,Grep,Bash(python3:*),Bash(node:*),Bash(ls:*),Bash(cat:*),"
426
+ "Bash(head:*),Bash(tail:*),Bash(grep:*),Bash(sed -n:*),Bash(wc:*)")
427
+ cmd = [claude, "-p", prompt, "--model", model, "--allowedTools", tools, "--output-format", "text"]
428
+ log(folder, f"updating the map with {model}")
429
+ env = {**os.environ, "HIVEY_AGENT": "hivey-agent-map"}
430
+ token = claude_token(folder)
431
+ if token:
432
+ env["CLAUDE_CODE_OAUTH_TOKEN"] = token # this process only; never logged
433
+ try:
434
+ p = subprocess.run(cmd, cwd=folder, capture_output=True, text=True, timeout=1500, env=env)
435
+ (folder / "llm.log").write_text(p.stdout + "\n--- stderr ---\n" + p.stderr)
436
+ # the model's own words stay in llm.log: they would read as errors here ("… failed …")
437
+ log(folder, f"{model}: exit {p.returncode} (its reply: llm.log)")
438
+ return p.returncode == 0
439
+ except (OSError, subprocess.SubprocessError) as e:
440
+ log(folder, f"{model} run failed: {e}")
441
+ return False
442
+
443
+
444
+ def html_current(folder: Path, html: str, src: str) -> bool:
445
+ h, s = folder / html, folder / src
446
+ return h.is_file() and s.is_file() and h.stat().st_mtime >= s.stat().st_mtime
447
+
448
+
449
+ def nightly(scan, days: int, model: str, use_llm: bool) -> int:
450
+ REPORTS.mkdir(parents=True, exist_ok=True)
451
+ now = dt.datetime.now()
452
+ folder = REPORTS / now.strftime("%Y-%m-%d-%H%M")
453
+ if folder.exists(): # a second run in the same minute gets its own folder
454
+ folder = REPORTS / now.strftime("%Y-%m-%d-%H%M%S")
455
+ folder.mkdir(exist_ok=True)
456
+ log(folder, f"scan, last {days} days")
457
+ snap = scan(days)
458
+ (STATE / "snapshot.json").write_text(json.dumps(snap, indent=1, default=str))
459
+ write_stats(snap, folder)
460
+ write_logs_page(snap, folder)
461
+ ok, msg = finalize(folder, "explainer", "stats.archify.md", "agent-stats.html")
462
+ log(folder, f"stats page: {'ok' if ok else 'FAILED ' + msg}")
463
+
464
+ prev = LATEST.resolve() / "map.json" if LATEST.exists() else None
465
+ if prev and prev.is_file() and prev.resolve() != (folder / "map.json").resolve():
466
+ shutil.copy2(prev, folder / "map.json")
467
+ has_map = (folder / "map.json").is_file()
468
+ if use_llm:
469
+ run_llm(folder, model, has_map)
470
+ if (folder / "map.json").is_file() and not html_current(folder, "agent-map.html", "map.json"):
471
+ good, why = finalize(folder, "dataflow", "map.json", "agent-map.html")
472
+ if not good and prev and prev.is_file(): # the model broke it: last night's map, unchanged
473
+ log(folder, f"map failed ({why}); using last night's map")
474
+ shutil.copy2(prev, folder / "map.json")
475
+ good, why = finalize(folder, "dataflow", "map.json", "agent-map.html")
476
+ log(folder, f"map: {'ok' if good else 'FAILED ' + why}")
477
+ else:
478
+ log(folder, "map: ok" if (folder / "agent-map.html").is_file() else "map: none yet")
479
+
480
+ if ok:
481
+ tmp = REPORTS / ".latest-new"
482
+ if tmp.is_symlink() or tmp.exists():
483
+ tmp.unlink()
484
+ tmp.symlink_to(folder.name)
485
+ os.replace(tmp, LATEST) # atomic: `open` never sees a missing link
486
+ for old in sorted(p for p in REPORTS.iterdir() if p.is_dir() and not p.is_symlink()
487
+ and re.match(r"\d{4}-\d\d-\d\d-\d{4}(\d\d)?$", p.name))[:-KEEP_REPORTS]:
488
+ shutil.rmtree(old, ignore_errors=True)
489
+ log(folder, f"done: {folder}")
490
+ return 0 if ok else 1
491
+
492
+
493
+ # ---------------------------------------------------------------- open
494
+
495
+ def latest_report() -> Path | None:
496
+ if LATEST.exists() and (LATEST / "agent-stats.html").is_file():
497
+ return LATEST.resolve()
498
+ folders = sorted(p for p in REPORTS.glob("*-*-*-*") if (p / "agent-stats.html").is_file()) if REPORTS.is_dir() else []
499
+ return folders[-1] if folders else None
500
+
501
+
502
+ def notify(text: str) -> None:
503
+ if sys.platform == "darwin" and not (HOME / ".hivey" / "quiet").exists():
504
+ subprocess.run(["osascript", "-e", f'display notification {json.dumps(text)} with title "hivey agent map"'],
505
+ capture_output=True)
506
+
507
+
508
+ def open_latest(model: str) -> int:
509
+ folder = latest_report()
510
+ if folder:
511
+ for page in ("agent-stats.html", "agent-map.html", "agent-logs.html"):
512
+ if (folder / page).is_file():
513
+ subprocess.run(["open", str(folder / page)], capture_output=True)
514
+ print(f"opened {folder}")
515
+ return 0
516
+ # No report yet: build the first one in the background and open it when it is ready.
517
+ REPORTS.mkdir(parents=True, exist_ok=True)
518
+ with open(STATE / "first-run.log", "a") as fh:
519
+ subprocess.Popen([sys.executable, "-I", str(SCRIPTS / "agent_map.py"), "nightly", "--model", model, "--open"],
520
+ stdout=fh, stderr=fh, stdin=subprocess.DEVNULL, start_new_session=True)
521
+ notify("Building your first agent map (a few minutes); it opens when ready.")
522
+ print("no report yet: building the first one in the background (log: ~/.hivey/agent-map/first-run.log)")
523
+ return 0
524
+
525
+
526
+ # ---------------------------------------------------------------- schedule (launchd)
527
+
528
+ OFFER = STATE / "offer.json"
529
+
530
+
531
+ def offer(hour: int, minute: int, model: str) -> int:
532
+ """Asked once, by install.sh and `hivey update`: set up the nightly run? The answer is kept in
533
+ offer.json so it is never asked again; with no terminal nothing is asked (asked next time)."""
534
+ if sys.platform != "darwin" or PLIST.is_file() or OFFER.is_file() or not sys.stdin.isatty():
535
+ return 0 # not a person at a terminal (remote or scripted update): asked next time
536
+ try:
537
+ tty = open("/dev/tty", "r+")
538
+ except OSError:
539
+ return 0
540
+ with tty:
541
+ tty.write(
542
+ "\nhivey can watch this computer every night: scheduled jobs (cron, launchd), agents and\n"
543
+ "swarms, token use and estimated cost per agent and provider, failing jobs, and how\n"
544
+ "agents feed each other. The report opens from the hivey menu → agent map.\n"
545
+ f"It runs at {hour:02}:{minute:02} with Claude {model} (a few cents a night).\n"
546
+ "Set up the nightly agent monitoring? [Y/n] ")
547
+ tty.flush()
548
+ answer = tty.readline().strip().lower()
549
+ yes = not answer.startswith("n")
550
+ STATE.mkdir(parents=True, exist_ok=True)
551
+ OFFER.write_text(json.dumps({"asked": dt.datetime.now().isoformat(timespec="seconds"), "answer": "yes" if yes else "no"}))
552
+ if not yes:
553
+ print("skipped (later: hivey agent-map schedule install)")
554
+ return 0
555
+ return schedule("install", hour, minute, model)
556
+
557
+
558
+ def schedule(action: str, hour: int, minute: int, model: str) -> int:
559
+ if action == "offer":
560
+ return offer(hour, minute, model)
561
+ uid = os.getuid()
562
+ if action == "status":
563
+ if not PLIST.is_file():
564
+ print("not scheduled (hivey agent-map schedule install)")
565
+ return 1
566
+ with open(PLIST, "rb") as fh:
567
+ d = plistlib.load(fh)
568
+ cal = d.get("StartCalendarInterval", {})
569
+ loaded = subprocess.run(["launchctl", "print", f"gui/{uid}/{LABEL}"], capture_output=True).returncode == 0
570
+ print(f"nightly at {cal.get('Hour', 0):02}:{cal.get('Minute', 0):02} with "
571
+ f"{d['ProgramArguments'][-1]} · {'loaded' if loaded else 'not loaded'} · {PLIST}")
572
+ return 0
573
+ subprocess.run(["launchctl", "bootout", f"gui/{uid}/{LABEL}"], capture_output=True)
574
+ if action == "remove":
575
+ if PLIST.exists():
576
+ PLIST.unlink()
577
+ print("nightly run removed")
578
+ return 0
579
+ installed = HOME / ".claude/skills/hivey-agent-map/scripts/agent_map.py"
580
+ script = installed if installed.is_file() else SCRIPTS / "agent_map.py" # refreshed by hivey update
581
+ STATE.mkdir(parents=True, exist_ok=True)
582
+ plist = {
583
+ "Label": LABEL,
584
+ # launchd, not cron: `claude -p` needs the login keychain, which cron cannot reach.
585
+ "ProgramArguments": ["/usr/bin/env", "python3", "-I", str(script), "nightly", "--model", model],
586
+ "StartCalendarInterval": {"Hour": hour, "Minute": minute}, # a missed run happens on wake
587
+ "EnvironmentVariables": {"PATH": LAUNCH_PATH, "HOME": str(HOME)},
588
+ "WorkingDirectory": str(STATE),
589
+ "StandardOutPath": str(STATE / "nightly.log"),
590
+ "StandardErrorPath": str(STATE / "nightly.log"),
591
+ "ProcessType": "Background",
592
+ "LowPriorityIO": True,
593
+ }
594
+ PLIST.parent.mkdir(parents=True, exist_ok=True)
595
+ with open(PLIST, "wb") as fh:
596
+ plistlib.dump(plist, fh)
597
+ r = subprocess.run(["launchctl", "bootstrap", f"gui/{uid}", str(PLIST)], capture_output=True, text=True)
598
+ if r.returncode != 0:
599
+ print(f"wrote {PLIST} but launchctl bootstrap failed: {r.stderr.strip()}")
600
+ return 1
601
+ print(f"nightly at {hour:02}:{minute:02} with {model}: {PLIST} (log {STATE / 'nightly.log'})")
602
+ return 0
@@ -192,7 +192,16 @@ to the swarm root (`permissions.additionalDirectories`, plus `--vault` if the va
192
192
  elsewhere) and sets `AGENTS_TTS=0` so workers stay silent. **Code swarms:** make sure the repo
193
193
  (e.g. `<root>/app`) exists with at least one commit, then pass `--worktree <repo>` for each
194
194
  builder: it gets `<root>/<agent>/repo` on branch `swarm/<agent>`. Builders commit on their
195
- branch; the integrator merges into the main checkout and runs the checks there.
195
+ branch; the integrator merges into the main checkout and runs the checks there. A fresh
196
+ worktree has no gitignored files: if the builders need local config (an env file, keys), list
197
+ those paths in the repo's `.worktreeinclude` (gitignore syntax, the file Claude Code's own
198
+ worktrees read) before running `setup_agent.py`, and it copies them in.
199
+
200
+ It also registers the **swarm done gate** in each agent's settings (Claude Code only; `--no-gate`
201
+ leaves it out): when an agent tries to stop while it still owns an `in-progress` task, it is
202
+ reminded once to `submit` it, set it `blocked` with a note, or say why it stays open. Each
203
+ worker's helper subagents run on Haiku (`CLAUDE_CODE_SUBAGENT_MODEL`, set by `hivey swarm
204
+ launch`; an agent on DeepSeek or Muse keeps its own model).
196
205
 
197
206
  Then install each agent's skills as `hivey skills guide` says (step 4 of the guide), and check
198
207
  `ls <root>/<agent>/.claude/skills`.
@@ -368,6 +377,14 @@ that ended in ERROR, is yours: read the review and accept it (`set <ID> approved
368
377
  coordinator`), re-scope it, or give the owner a specific fix. If an owner disputes a defect, it
369
378
  tells you with evidence; you decide. Don't review deliverables yourself instead of the critics.
370
379
 
380
+ **Big fan-out jobs: suggest a dynamic workflow.** For a job that needs many parallel reads with
381
+ cross-checked results (audit every file for one issue, a migration across hundreds of files,
382
+ research cross-checked across many sources), suggest the user run it as a Claude Code dynamic
383
+ workflow: a script that runs up to dozens of subagents, verifies their findings against each
384
+ other and returns one result, so it doesn't take a swarm agent's whole context. It starts only
385
+ when the user opts in (their message says `ultracode` or "use a workflow"); never start one on
386
+ your own. It uses much more quota, so suggest trying it on one folder first.
387
+
371
388
  **Too much talk.** If agents ping-pong, flood `@all` or Slack, tighten the swarm's limits
372
389
  (`hivey swarm comms <name> --preset quiet`, or one flag such as `--hourly-wakes 12` or
373
390
  `--slack masters`) and tell the agents involved to batch their messages. Ask the user before
@@ -32,6 +32,9 @@ that genuinely don't apply (e.g. the wiki when the user said no); don't leave pl
32
32
  market report`).
33
33
  - Look up library, API, CLI and cloud docs with the `hivey-context7` skill first, before a web
34
34
  search or your memory.
35
+ - A script you write that calls an LLM API directly (not through Claude Code, Codex or Grok CLI)
36
+ logs each call with `hivey_spend.record(response, agent="<agent name>")` from
37
+ `~/.claude/skills/hivey-agent-map/scripts/hivey_spend.py`, so the agent map counts its cost.
35
38
  - Style Obsidian notes with callouts: `> [!tip] Title` then `> content`. Types: note, tip,
36
39
  warning, danger, info, example, quote.
37
40
  - When you create a new skill, offer to publish it with skylls (`skylls push <skill folder>
@@ -19,6 +19,12 @@ one message (or let the task board and files speak). Your swarm's limits: `hivey
19
19
  For any library, framework, SDK, API, CLI or cloud service, look the docs up with the
20
20
  `hivey-context7` skill before a web search or your memory.
21
21
 
22
+ # Spend log
23
+
24
+ A script that calls an LLM API directly (not through Claude Code, Codex or Grok CLI) logs each
25
+ call with `hivey_spend.record(response, agent="<agent name>")` from
26
+ `~/.claude/skills/hivey-agent-map/scripts/hivey_spend.py`, so the agent map counts its cost.
27
+
22
28
  # Safety and secrets
23
29
 
24
30
  Agents run with permissions pre-approved; hivey's safety hooks (`hivey safety`, on by default)